erp-core/docs/01-fase-foundation/MGN-001-auth

MGN-001: Autenticacion

Metadata

Campo	Valor
ID	MGN-001
Nombre	Autenticacion
Fase	01 - Foundation
Prioridad	P0 (Critico)
Story Points	40 SP
Estado	Documentado
Dependencias	Ninguna

---

Descripcion

Sistema de autenticacion completo para el ERP que incluye:

• Login con email/password: Autenticacion tradicional con validacion de credenciales
• Tokens JWT: Access tokens de corta duracion y refresh tokens de larga duracion
• OAuth Social: Login con Google y Microsoft
• Recuperacion de password: Flujo de reset via email
• Proteccion brute force: Rate limiting y bloqueo temporal

---

Objetivos

1. Proveer autenticacion segura para todos los usuarios del sistema
2. Soportar multiples metodos de autenticacion (local, OAuth)
3. Implementar manejo robusto de sesiones con tokens JWT
4. Proteger contra ataques comunes (brute force, session hijacking)
5. Permitir recuperacion segura de credenciales

---

Alcance

Incluido

• Login/logout con email y password
• Generacion y validacion de JWT (access + refresh tokens)
• Recuperacion de password via email
• OAuth con Google y Microsoft
• Registro de intentos de login fallidos
• Bloqueo temporal por intentos fallidos
• Manejo de sesiones multiples por usuario

Excluido

• Registro de nuevos usuarios (ver MGN-002 Users)
• Gestion de perfiles (ver MGN-002 Users)
• Asignacion de roles (ver MGN-003 Roles)
• 2FA/MFA (futuro enhancement)

---

User Stories Principales

ID	Titulo	SP	Prioridad
US-MGN001-001	Login con Email/Password	8	P0
US-MGN001-002	Logout de Sesion	3	P0
US-MGN001-003	Recuperar Password	5	P1
US-MGN001-004	Refresh de Token	5	P0
US-MGN001-005	Login con Google	8	P2

Total: 29 SP + 11 SP buffer = 40 SP

---

Arquitectura

┌─────────────────┐     ┌─────────────────┐
│   Frontend      │     │    Backend      │
│  (React/Vite)   │────▶│   (NestJS)      │
└─────────────────┘     └────────┬────────┘
        │                        │
        │                        ▼
        │               ┌─────────────────┐
        │               │  AuthService    │
        │               │  TokenService   │
        │               │  PasswordSvc    │
        │               │  OAuthService   │
        │               └────────┬────────┘
        │                        │
        │                        ▼
        │               ┌─────────────────┐
        │               │   PostgreSQL    │
        │               │   core_auth     │
        │               └─────────────────┘
        │
        ▼
┌─────────────────┐
│   authStore     │
│   (Zustand)     │
└─────────────────┘

---

Endpoints API

Metodo	Path	Descripcion
POST	/api/v1/auth/login	Login con credenciales
POST	/api/v1/auth/logout	Cerrar sesion
POST	/api/v1/auth/refresh	Renovar tokens
POST	/api/v1/auth/forgot-password	Solicitar reset
POST	/api/v1/auth/reset-password	Cambiar password
GET	/api/v1/auth/me	Usuario actual
GET	/api/v1/auth/oauth/:provider	Iniciar OAuth

---

Tablas de Base de Datos

Tabla	Descripcion
users_auth	Credenciales de autenticacion
sessions	Sesiones activas
refresh_tokens	Tokens de refresco
password_resets	Tokens de reset
login_attempts	Intentos de login
oauth_accounts	Cuentas OAuth vinculadas

---

Seguridad

• Passwords hasheados con bcrypt (cost factor 12)
• Access tokens JWT con expiracion de 15 minutos
• Refresh tokens con expiracion de 7 dias
• Rate limiting: 5 intentos por minuto por IP
• Bloqueo temporal: 15 minutos despues de 5 intentos fallidos
• Tokens de reset expiran en 1 hora

---

Dependencias

Este modulo no depende de otros modulos

MGN-001 es la base del sistema y no tiene dependencias.

Modulos que dependen de este

• MGN-002 Users: Para autenticar usuarios
• MGN-003 Roles: Para verificar permisos en JWT
• MGN-004 Tenants: Para incluir tenant_id en JWT
• Todos los demas modulos: Requieren autenticacion

---

Documentacion

• Mapa del modulo: _MAP.md
• Trazabilidad: TRACEABILITY.yml
• Requerimientos: requerimientos/
• Especificaciones: especificaciones/
• User Stories: historias-usuario/

---

Historial

Fecha	Cambio	Autor
2025-12-05	Creacion del modulo con estructura GAMILIT	Requirements-Analyst

---

Generado por: Requirements-Analyst Fecha: 2025-12-05