hoangsonww / hoangsonww/JWT-Module

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

Open
#4 0 comments 0 reactions 1 assignee Claimed by @hoangsonww View on GitHub
bug documentation enhancement good first issue help wanted question
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.