breadcrumb-the-shire/docs/todo-2fa.md

TODO: 2FA (TOTP) Integration

Goal: Add optional TOTP-based 2FA for users (admin-managed, later self-managed).

Proposed library:

• Start with a lightweight TOTP library (e.g. remotemerge/totp-php) or a more established one (e.g. spomky-labs/otphp).

Data model:

• users: totp_secret (encrypted), totp_enabled (tinyint), totp_verified_at (nullable)
• user_backup_codes: user_id, code_hash, created_at, used_at (nullable)

Admin user edit flow:

• Enable 2FA: generate secret + show QR (otpauth URI).
• Verify code to activate.
• Generate backup codes (show once).

Login flow:

• After password: prompt TOTP if totp_enabled.
• Rate-limit attempts.

Security notes:

• Encrypt secret at rest.
• Accept small time drift (+/- 1 step).
• Default to SHA-1 for compatibility.