Two-Factor Auth

Two-Factor Auth

TOTP (RFC 6238), backup codes, QR code generation for authenticator apps, and recovery flows. Zero dependencies.

Part of the Auth Vault toolkit by [CodeVault](https://codevault.dev).

Features

• TOTP generation per RFC 6238 (30-second intervals, 6-digit codes)
• QR code generation as SVG — no image library dependencies
• Backup codes: cryptographically secure, single-use
• Compatible with Google Authenticator, Authy, and 1Password
• Configurable time window tolerance for clock drift
• Recovery flow with backup code verification
• CLI tool for enrollment, verification, and backup code management
• Zero dependencies — Python stdlib only

Quick Start

# Enroll a new user (generates secret + QR code)
python3 src/main.py enroll --user user@example.com --issuer "My App"

# Verify a TOTP code
python3 src/main.py verify --user user@example.com --code 123456

# Generate backup codes
python3 src/main.py backup-codes --user user@example.com

# Verify a backup code
python3 src/main.py verify-backup --user user@example.com --code "abcd-efgh"

# Show the QR code SVG
python3 src/main.py qr --user user@example.com --issuer "My App"

Using as a Library

from main import TwoFactorAuth

tfa = TwoFactorAuth()

# Enroll a user
secret, qr_svg, backup_codes = tfa.enroll(
    user="user@example.com",
    issuer="My App",
)
print(f"Secret: {secret}")   # Store securely
print(f"Backup codes: {backup_codes}")  # Show once to user

# Save QR code SVG to file
with open("qr.svg", "w") as f:
    f.write(qr_svg)

# Verify a TOTP code from the user's authenticator app
is_valid = tfa.verify(user="user@example.com", code="123456")

TOTP Parameters

... continues with setup instructions, usage examples, and more.