Saltar al contenido principal

Autenticación y Seguridad

Sistema completo de autenticación y autorización con múltiples capas de protección que garantizan la seguridad de todos los endpoints de la plataforma.

Protección Multicapa

Este módulo implementa un sistema de seguridad en capas donde cada request es validado por múltiples guards antes de llegar al controlador. Esto garantiza que solo usuarios autenticados, verificados y autorizados puedan acceder a recursos sensibles.

Guards Disponibles​

JWT Auth Guard​

Guard principal de autenticación que maneja todo el flujo de validación de tokens:

  • Verificación JWT – Valida la firma y vigencia del token
  • Sesiones en Redis – Verifica que la sesión esté activa y no haya sido revocada
  • Integración KYC – Valida automáticamente el estado de verificación del usuario
  • Sistema PIN – Requiere sesión PIN aprobada para operaciones sensibles
  • Auto-migración – Migra automáticamente usuarios sin configuración PIN

Guard Todo-en-Uno

Al aplicar JwtAuthGuard en un endpoint, automáticamente obtienes validación de JWT + KYC + PIN sin necesidad de configuración adicional. Este guard está diseñado para ser el guard principal en la mayoría de endpoints protegidos.

PIN Security System​

Sistema de autenticación de segundo factor con sesiones aprobadas:

Características Principales​

  • PINs de 6 dígitos – Formato numérico fácil de recordar pero seguro
  • Hash bcrypt – Almacenamiento seguro con salt automático
  • Sesiones aprobadas – Sesiones temporales que persisten en Redis
  • Timeouts configurables – Duración personalizable de sesiones PIN
  • Protección anti-brute-force – Máximo 5 intentos cada 15 minutos

Componentes del Sistema​

PIN Security Service – Servicio principal que gestiona:

  • Configuración inicial de PIN
  • Verificación de PIN con intentos fallidos
  • Creación de sesiones aprobadas
  • Actualización de PIN existente
  • Revocación de sesiones

PIN Guard – Guard específico que:

  • Valida existencia de sesión PIN aprobada
  • Verifica que la sesión no haya expirado
  • Integra con JWT para validación completa

Tracking de Sesiones – Sistema de monitoreo que:

  • Rastrea sesiones activas por usuario
  • Permite revocación individual o masiva
  • Almacena metadata de dispositivos

Flujo de Autenticación PIN

El flujo típico es:

  1. Usuario se autentica con JWT (email/password)
  2. Para operaciones sensibles, se solicita PIN
  3. Al verificar PIN correctamente, se crea una sesión aprobada
  4. La sesión aprobada permite acceso temporal sin solicitar PIN nuevamente
  5. La sesión expira después del timeout configurado

Device Authentication​

Control de acceso basado en dispositivos vinculados:

  • Device Auth Guard – Valida que el dispositivo esté vinculado a la cuenta
  • Device Header Guard – Verifica headers de dispositivo requeridos
  • Linked Device Schema – Almacena información de dispositivos autorizados
  • Vinculación de dispositivos – Proceso de autorización de nuevos dispositivos

Headers Requeridos​

Los guards de dispositivo validan la presencia de:

  • device-id – Identificador único del dispositivo
  • device-name – Nombre descriptivo del dispositivo
  • device-type – Tipo de dispositivo (móvil, web, desktop)

Guards Adicionales​

KYC Guard​

Valida el estado de verificación Know Your Customer:

  • Verifica que el usuario haya completado KYC
  • Bloquea acceso a funcionalidades premium sin verificación
  • Integrado automáticamente en JwtAuthGuard

Roles Guard​

Control de acceso basado en roles:

  • Valida roles específicos del usuario
  • Soporta múltiples roles por usuario
  • Permite configuración granular por endpoint

Authenticated Guard​

Guard simple de sesión:

  • Verifica que exista una sesión activa
  • Usado para endpoints que no requieren JWT completo
  • Compatible con autenticación de sesión tradicional

JWT Module​

Módulo compartido de JSON Web Tokens que proporciona:

Funcionalidades​

  • Generación de tokens – Crea JWTs con claims personalizados
  • Validación de tokens – Verifica firma, vigencia y claims
  • Refresh tokens – Sistema de renovación de tokens
  • Revocación – Invalidación de tokens comprometidos
  • Claims personalizados – Soporte para metadata adicional

Integración con Redis​

El módulo JWT está completamente integrado con Redis para:

  • Almacenar sesiones activas – Cada token tiene una entrada en Redis
  • Invalidación instantánea – Revocación sin esperar expiración del token
  • Tracking de múltiples sesiones – Un usuario puede tener varias sesiones activas
  • Cleanup automático – Limpieza de sesiones expiradas

Schemas Relacionados​

User Schema​

Schema principal con campos de seguridad:

  • email – Email único del usuario
  • password – Hash bcrypt de la contraseña
  • pinSecurity – Objeto con configuración PIN
  • kycVerified – Estado de verificación KYC
  • roles – Array de roles asignados
  • twoFactorEnabled – Estado de 2FA

OAuth2 Schema​

Configuración de OAuth2 y KYC:

  • userId – Referencia al usuario
  • provider – Proveedor OAuth (Google, Facebook, etc.)
  • kycStatus – Estado detallado de KYC
  • verificationLevel – Nivel de verificación alcanzado

SessionAccess Schema​

Control de sesiones activas:

  • userId – Usuario propietario de la sesión
  • jti – JWT ID único
  • deviceInfo – Información del dispositivo
  • lastActivity – Última actividad registrada
  • expiresAt – Fecha de expiración

LogoutRecord Schema​

Registro de cierres de sesión:

  • userId – Usuario que cerró sesión
  • jti – JWT ID revocado
  • logoutType – Manual, automático o forzado
  • deviceInfo – Dispositivo donde se cerró sesión

LinkedDevice Schema​

Dispositivos vinculados:

  • userId – Usuario propietario
  • deviceId – Identificador único
  • deviceName – Nombre descriptivo
  • deviceType – Tipo de dispositivo
  • linkedAt – Fecha de vinculación
  • lastUsed – Último uso del dispositivo

Servicios de Autenticación​

PIN Security Service​

Servicio principal de gestión de PINs:

Métodos principales:

  • configurePin(userId, pin) – Configuración inicial de PIN
  • verifyPin(userId, pin) – Verificación con tracking de intentos
  • createApprovedSession(jti, userId) – Crea sesión aprobada en Redis
  • updatePin(userId, oldPin, newPin) – Cambio de PIN
  • revokeSession(jti) – Revoca sesión específica
  • revokeAllSessions(userId) – Revoca todas las sesiones del usuario

Protecciones incluidas:

  • Límite de intentos fallidos
  • Bloqueo temporal tras múltiples fallos
  • Logging de eventos de seguridad
  • Notificaciones de intentos sospechosos

Notification Service​

Servicio de notificaciones de seguridad:

Eventos notificados:

  • Inicio de sesión desde nuevo dispositivo
  • Intentos fallidos de PIN
  • Cambios de contraseña o PIN
  • Vinculación de nuevos dispositivos
  • Detección de actividad sospechosa

Canales soportados:

  • Email
  • Push notifications
  • SMS (integración con proveedores externos)
  • Webhooks

DTOs de Autenticación​

LoginUserDto​

Validación de login:

  • email – Email válido requerido
  • password – Mínimo 8 caracteres
  • deviceInfo – Información opcional del dispositivo

CreateUserDto​

Registro de nuevos usuarios:

  • email – Email único
  • password – Con requisitos de complejidad
  • firstName – Nombre requerido
  • lastName – Apellido requerido

ConfigurePinDto​

Configuración inicial de PIN:

  • pin – Exactamente 6 dígitos
  • confirmPin – Confirmación que debe coincidir

VerifyPinDto​

Verificación de PIN:

  • pin – 6 dígitos a verificar
  • jti – JWT ID para crear sesión aprobada

UpdatePinDto​

Cambio de PIN:

  • oldPin – PIN actual para validación
  • newPin – Nuevo PIN de 6 dígitos
  • confirmNewPin – Confirmación del nuevo PIN

Guards Encadenados

Los guards se pueden encadenar para crear capas de seguridad personalizadas. Por ejemplo:

  • @UseGuards(JwtAuthGuard) – JWT + KYC + PIN automático
  • @UseGuards(JwtAuthGuard, RolesGuard) – Autenticación + validación de roles
  • @UseGuards(JwtAuthGuard, DeviceAuthGuard) – Autenticación + dispositivo autorizado
  • @UseGuards(JwtAuthGuard, PinGuard) – Fuerza verificación PIN adicional

Esta flexibilidad permite adaptar la seguridad según la sensibilidad de cada endpoint.