Saltar al contenido principal

TEC-006 — Autenticación 2FA para usuarios privilegiados

· 4 min de lectura
Yovany Suárez Silva
Software Engineer - FullStack Developer

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​

RFEntregable
RF-TEC-006-012FA 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-02Método estándar: TOTP (aplicación autenticadora, RFC 6238) + 10 códigos de recuperación de un solo uso
RF-TEC-006-03Política configurable: qué roles son obligatorios, intentos por desafío, vigencia y emisor
RF-TEC-006-04Todos 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ónPor qué
TOTP implementado con node:cryptoSin 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 HMACSolo se comprueban, nunca se leen; el código en claro se muestra una sola vez
Cifrado y desafío con secretos distintosUn token de 2FA pendiente no debe poder usarse como sesión, ni por error de configuración
Código inválido → 400, intentos agotados → 429El 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 TOTPEl mismo código de 30 s no sirve dos veces (ultimo_uso_en)
Auditoría en el servidor, nunca en el clienteUn 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.
Sin QR

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​

PruebaResultado
Suite completa del API545 pruebas / 55 suites / 0 fallos (incluye suites de otras sesiones en paralelo)
Pruebas nuevas del dominio 2FA93 (vectores RFC, cifrado, servicio, login, guardas, DI y auditoría)
Integración contra la base y la API reales19/19 verificaciones OK (migración 030 ejecutada; el usuario temporal de la prueba se elimina al terminar)
Frontendtsc --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​