# 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](./_MAP.md)
- **Trazabilidad:** [TRACEABILITY.yml](./implementacion/TRACEABILITY.yml)
- **Requerimientos:** [requerimientos/](./requerimientos/)
- **Especificaciones:** [especificaciones/](./especificaciones/)
- **User Stories:** [historias-usuario/](./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
