Protect user accounts against credential stuffing and password theft with time-based one-time passwords (TOTP), QR code enrollment, and single-use backup recovery codes.
1. TOTP Security Architecture
HVT implements two-factor authentication following the RFC 6238 standard (Time-Based One-Time Password Algorithm), derived from HMAC-based One-Time Passwords (RFC 4226).
When a user initiates MFA setup, HVT generates a high-entropy cryptographically random 160-bit shared secret and encodes it as a Base32 string. This secret is stored securely on the user's TOTPDevice model.
RFC 6238 Algorithm
The 6-digit one-time code is calculated as: TOTP = Truncate(HMAC-SHA1(Secret, Floor(UnixTime / 30))) mod 10^6 Because each 30-second window produces a unique code, stolen passwords cannot be used without physical possession of the authenticator device.
2. Enrolling an Authenticator (QR Code)
Users scan a standard otpauth:// URI formatted QR code using their authenticator app (Google Authenticator, Microsoft Authenticator, 1Password, Apple Passwords):
When MFA is verified, HVT generates exactly 10 single-use 8-character alphanumeric recovery codes formatted as xxxx-xxxx (e.g. a1b2-c3d4). Backup codes are hashed at rest using SHA-256 before storage in auth_totp_backup_codes.
Users can enter a backup recovery code directly into the 2FA login challenge prompt in place of a 6-digit TOTP code. Once used, the code is marked with a timestamp in used_at and cannot be reused.
Regenerating Backup Codes
If a user runs out of backup codes or suspects their recovery codes were compromised, they can generate a fresh batch of 10 codes: