Module mfa 

Multi-Factor Authentication API Endpoints

Handles TOTP setup, verification, backup codes, and MFA management.

Storage keys

• mfa_pending_secret:{user_id} — base32 TOTP secret, TTL 10 min (before verification)
• mfa_pending_backup_codes:{user_id} — JSON array of hex-encoded SHA-256 hashes, TTL 10 min
• mfa_secret:{user_id} — active base32 TOTP secret (no TTL)
• mfa_backup_codes:{user_id} — JSON array of hex-encoded SHA-256 hashes (no TTL)
• mfa_enabled:{user_id} — b“true“ when MFA is active (no TTL)

Structs

BackupCodeVerifyRequest

POST /mfa/verify-backup-code — authenticate with a one-time backup code.

MfaDisableRequest

Request payload to disable MFA (requires proof of identity).

MfaSetupResponse

Response returned after initiating MFA setup.

MfaStatusResponse

Current MFA enrollment status for the authenticated user.

MfaVerifyRequest

Request payload for the TOTP verification step.

Functions

check_user_mfa_status

Returns true if MFA is currently active for user_id.

disable_mfa

POST /mfa/disable — remove MFA from the authenticated account.

get_mfa_status

GET /mfa/status — query the current MFA enrollment state.

regenerate_backup_codes

POST /mfa/regenerate-backup-codes — replace all backup codes.

setup_mfa

POST /mfa/setup — initiate MFA enrollment.

verify_backup_code

Handler for POST /mfa/verify-backup-code.

verify_mfa

POST /mfa/verify — complete MFA enrollment.