2FA: setup, activación, login y baja

petid-apipetid-client
actualizado 2026-09-02

Objetivo

Verificación en dos pasos por TOTP (Google Authenticator, etc.), con backup codes para cuando el usuario pierde el dispositivo.

Cómo empieza

Usuario logueado va a Settings → Seguridad → “Activar” (petid-client, two-factor-setup.tsx).

Pasos principales

1. POST /two-factor/setup (setup-two-factor.use-case.ts) genera un secret TOTP y lo guarda cifrado en user.twoFactorSecret — pero 2FA sigue inactivo hasta confirmar un código. Devuelve { secret, otpauthUrl } para pintar el QR.
2. Usuario escanea + introduce un código de 6 dígitos → POST /two-factor/enable (enable-two-factor.use-case.ts): verifica el TOTP contra el secret descifrado, marca twoFactorEnabledAt, y genera 10 backup codes (issue-backup-codes.use-case.ts) que solo se devuelven en esta respuesta — no se pueden volver a consultar.
3. Login con 2FA activo: POST /auth/login no emite tokens, devuelve { mfaRequired: true, challengeToken } (JWT firmado, corta vida). El cliente pide el código en mfa-challenge.tsx y llama POST /auth/login/2fa.
4. verify-two-factor.use-case.ts acepta TOTP válido O un backup code sin usar (consumeBackupCode) — cualquiera de los dos completa el login.

Reglas de negocio

• Desactivar 2FA (disable-two-factor.use-case.ts) exige reintroducir la contraseña — una sesión secuestrada no puede bajar el 2FA por sí sola.
• Al desactivar se borran todos los backup codes (backupCodes.deleteForUser).
• Regenerar códigos invalida los anteriores (mismo patrón “se muestran una sola vez”).

Interacciones

• TwoFactorEnabledEvent/TwoFactorDisabledEvent disparan email (2fa-enabled/2fa-disabled) y push (account-security-updated) — ver notification-template-routing.md.

Dónde seguir mirando

• petid-api/src/application/auth/{setup,enable,verify,disable}-two-factor.use-case.ts
• petid-client/src/app/(home)/two-factor-setup.tsx, mfa-challenge.tsx

Casos especiales

• El secret TOTP nunca viaja en claro a la DB — pasa por SecretCipher (cifrado simétrico, no hash: hace falta poder descifrarlo para verificar el código).
• EnableTwoFactorUseCase falla con TwoFactorNotInitializedError si se llama sin haber pasado por /setup antes (protege contra saltarse el paso 1).