TEC-006 — Autenticación 2FA para usuarios privilegiados
Implementación de la mejora TEC-006 (Autenticación 2FA), dentro de 6.2 Seguridad y de la Fase 1. Hasta ahora una contraseña filtrada bastaba para operar como Administrador; a partir de esta entrega, los roles privilegiados necesitan además un segundo factor.
📋 Alcance
| RF | Entregable |
|---|---|
| RF-TEC-006-01 | 2FA exigido a los usuarios privilegiados: sin segundo factor no hay sesión, y un guard bloquea en cada petición los tokens que no lo hayan superado |
| RF-TEC-006-02 | Método estándar: TOTP (aplicación autenticadora, RFC 6238) + 10 códigos de recuperación de un solo uso |
| RF-TEC-006-03 | Política configurable: qué roles son obligatorios, intentos por desafío, vigencia y emisor |
| RF-TEC-006-04 | Todos los eventos de 2FA en el log de auditoría (loggers, entidad = '2FA') |
⚙️ Cómo funciona
El login pasa a tener dos pasos. POST /api/auths/login ya no siempre devuelve un token:
credenciales ──► ¿tiene 2FA? ──► sí ──► desafío de VERIFICACIÓN
│
├── ¿su rol lo exige y no lo tiene? ──► desafío de ENROLAMIENTO
│
└── no ──► sesión (flujo de siempre)
El desafío es un JWT de 5 minutos firmado con un secreto propio (TWOFA_JWT_SECRET) y con
scope: '2fa': no sirve como sesión (verificado contra la API real: usar el desafío como
Bearer responde 401). La sesión, el «conectado» y el aviso por WebSocket solo ocurren al
superar el segundo factor.
🔐 Decisiones de seguridad
| Decisión | Por qué |
|---|---|
TOTP implementado con node:crypto | Sin dependencias nuevas en un módulo de seguridad; la corrección se demuestra con los vectores del RFC 6238 (94287082, 07081804, …) |
| El secreto TOTP se guarda cifrado (AES-256-GCM) | Un segundo factor legible en la base no es un segundo factor; GCM además detecta manipulación |
| Los códigos de recuperación se guardan como huella HMAC | Solo se comprueban, nunca se leen; el código en claro se muestra una sola vez |
| Cifrado y desafío con secretos distintos | Un token de 2FA pendiente no debe poder usarse como sesión, ni por error de configuración |
| Código inválido → 400, intentos agotados → 429 | El interceptor del cliente cierra la sesión ante 401/403, y eso expulsaría al usuario justo del paso que debe completar |
| Anti-replay del código TOTP | El mismo código de 30 s no sirve dos veces (ultimo_uso_en) |
| Auditoría en el servidor, nunca en el cliente | Un registro que depende del navegador no es un registro de seguridad |
🗄️ Datos
usuario_2fa: una fila por usuario con el secreto cifrado, el estado, la marca de último uso y los códigos de recuperación hasheados.configuracion_2fa: fila única con la política (roles obligatorios, intentos, vigencia, emisor). La migración la siembra con["Administrador"], 5 intentos y 300 s.- Migración
030-create-2fa.ts, idempotente y reversible.
🖥️ Interfaz
- Login en dos pasos: campo de 6 dígitos (con pegado completo), alterna a código de recuperación, muestra los intentos restantes y permite volver a las credenciales. El desafío vive solo en memoria: recargar la página devuelve al paso de credenciales.
- Enrolamiento (también en el login bloqueado): clave Base32 en grupos de 4, enlace
otpauth://copiable, confirmación por código y pantalla única con los 10 códigos (copiar o descargar.txt). - Mi Perfil → Seguridad: estado del 2FA, activar, regenerar códigos y desactivar.
- Configuración → Seguridad 2FA (solo Administrador): política y tabla de usuarios con su estado, más el reinicio auditado del 2FA de un usuario.
El enrolamiento es por clave manual o enlace copiable: no se añadió una dependencia de codificación de QR. Todas las aplicaciones autenticadoras admiten la entrada manual.
🧪 Verificación
| Prueba | Resultado |
|---|---|
| Suite completa del API | 545 pruebas / 55 suites / 0 fallos (incluye suites de otras sesiones en paralelo) |
| Pruebas nuevas del dominio 2FA | 93 (vectores RFC, cifrado, servicio, login, guardas, DI y auditoría) |
| Integración contra la base y la API reales | 19/19 verificaciones OK (migración 030 ejecutada; el usuario temporal de la prueba se elimina al terminar) |
| Frontend | tsc --noEmit EXIT 0 · next lint sin warnings nuevos · 45 pruebas / 11 suites |
| E2E (Playwright) | Helper de login actualizado para completar el segundo factor; validado por tipos y --list, no ejecutable en este entorno (next dev falla con spawn EPERM) |
La verificación real comprobó, entre otras cosas: el bloqueo sin sesión de un Administrador sin
2FA, el enrolamiento con código calculado, que el secreto esté cifrado y los códigos no estén en
claro en la base, el 403 TWOFA_REQUERIDO de un token privilegiado sin segundo factor, el 401
de un desafío usado como sesión, el 400 con intentos restantes, el uso único de un código de
recuperación y los 7 eventos de auditoría generados por el flujo.
📎 Documentación
- Spec: TEC-006: Autenticación 2FA
- Manual de usuario: Autenticación en Dos Pasos
- Requerimiento: Mejoras propuestas — 6.2 Seguridad
