Configuración de TOTP con código QR, códigos de recuperación, dispositivos de confianza, restablecimiento por un administrador.
Spec — Two-factor authentication
Status: draft · Created: 2026-11-10
1. Context and goal
Accounts add a second factor from an authenticator app, so a stolen password alone no longer opens them, with safe ways back when the phone is lost.
2. Functional requirements (EARS)
- FR-1: WHEN a person starts setup, THE SYSTEM SHALL generate a 160-bit TOTP secret (RFC 6238, SHA-1, 6 digits, 30-second step) and show it as a QR code and as text.
- FR-2: THE SYSTEM SHALL enable two-factor authentication only after the person enters a valid code from the new secret, and SHALL discard an unconfirmed secret after 15 minutes.
- FR-3: WHEN setup is confirmed, THE SYSTEM SHALL show 10 single-use recovery codes once and store only their hashes.
- FR-4: WHEN an account with two-factor authentication signs in with the right password, THE SYSTEM SHALL require a code before creating a session, accepting the current step and one step before or after it.
- FR-5: IF a code is reused within its validity window or 5 codes fail in a row, THEN THE SYSTEM SHALL reject it, and after the fifth failure lock the second step for 15 minutes.
- FR-6: WHEN a recovery code is used, THE SYSTEM SHALL accept it only once, email the owner, and show how many codes remain.
- FR-7: WHERE the person ticks "trust this device", THE SYSTEM SHALL skip the second step on that browser for 30 days, and SHALL let the person revoke all trusted devices at once.
- FR-8: WHEN an admin resets a member's two-factor authentication, THE SYSTEM SHALL require the admin's own second factor, remove the secret, recovery codes and trusted devices, email the member and write an audit entry.
- FR-9: WHEN a person disables two-factor authentication or regenerates recovery codes, THE SYSTEM SHALL require a current code or the password entered in the last 5 minutes, and invalidate the old recovery codes.
3. Out of scope
- SMS and email codes.
- WebAuthn security keys and passkeys.