Feature: Multi-factor authentication (TOTP) with backup codes and step-up login

[hoangsonww]

Why

Password-only authentication leaves accounts vulnerable when credentials are leaked. MFA is a high-impact security feature expected in modern auth systems.

Proposal

Implement optional TOTP-based MFA:

• Enroll TOTP app (RFC 6238 compatible)
• Verify setup with one-time code before activation
• Backup recovery codes (single-use, hashed at rest)
• Step-up challenge during login when MFA is enabled

Scope

• Endpoints for MFA setup, confirm, disable, and regenerate backup codes
• Login flow updates: password validation -> MFA challenge -> token issuance
• Account recovery path using backup codes

API Additions (proposed)

• POST /auth/mfa/setup
• POST /auth/mfa/verify-setup
• POST /auth/mfa/challenge
• POST /auth/mfa/disable
• POST /auth/mfa/recovery

Technical Notes

• Store TOTP secret encrypted at rest
• Rate-limit MFA challenge attempts separately from password login
• Add audit events for setup/disable/recovery actions

Acceptance Criteria

• MFA-enabled accounts require valid second factor to complete login
• Backup codes are one-time use and cannot be replayed
• Disabling MFA requires strong confirmation (password + current factor or recovery flow)
• Automated tests cover enrollment, challenge, recovery, and lockout behavior
• Public docs include secure UX recommendations for clients

Out of Scope

• SMS-based OTP
• Hardware WebAuthn keys (separate feature)