hoangsonww / hoangsonww/JWT-Module
Feature: Multi-factor authentication (TOTP) with backup codes and step-up login
- Dominant language
- TypeScript
- Stars
- 12
- Forks
- 6
- PR merge metrics
- No merged PRs in 30d
Description
## 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)
Contributor guide
Assessment
This issue has not been assessed yet.