# SAAS-001: Autenticacion

## Metadata
- **Codigo:** SAAS-001
- **Modulo:** Auth
- **Prioridad:** P0
- **Estado:** Completado
- **Fase:** 1 - Foundation

## Descripcion

Sistema de autenticacion completo para SaaS multi-tenant: JWT con refresh tokens, OAuth 2.0 con multiples proveedores, MFA opcional, y gestion de sesiones.

## Objetivos

1. Login con email/password
2. OAuth 2.0 (Google, Microsoft, GitHub)
3. JWT con refresh tokens
4. MFA (TOTP)
5. Gestion de sesiones

## Alcance

### Incluido
- Registro con email
- Login con email/password
- OAuth 2.0 (Google, Microsoft, GitHub)
- JWT access tokens (15min)
- Refresh tokens (7 dias)
- MFA via TOTP (Google Authenticator)
- Session management
- Password reset flow
- Email verification

### Excluido
- Passwordless (magic links) - fase posterior
- Biometric auth - fase posterior
- SSO/SAML - enterprise feature

## Modelo de Datos

### Tablas (schema: auth)

**sessions**
- id, user_id, token, device_info
- ip_address, user_agent
- expires_at, revoked_at, created_at

**tokens**
- id, user_id, type (verify_email/reset_password/mfa_setup)
- token, expires_at, used_at

**oauth_connections**
- id, user_id, provider (google/microsoft/github)
- provider_id, access_token, refresh_token
- expires_at, created_at

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /auth/register | Registro nuevo usuario |
| POST | /auth/login | Login email/password |
| POST | /auth/logout | Cerrar sesion |
| POST | /auth/refresh | Renovar tokens |
| GET | /auth/me | Usuario actual |
| POST | /auth/forgot-password | Solicitar reset |
| POST | /auth/reset-password | Resetear password |
| POST | /auth/verify-email | Verificar email |
| GET | /auth/oauth/:provider | Iniciar OAuth |
| GET | /auth/oauth/:provider/callback | Callback OAuth |
| POST | /auth/mfa/setup | Configurar MFA |
| POST | /auth/mfa/verify | Verificar MFA |
| DELETE | /auth/mfa | Desactivar MFA |
| GET | /auth/sessions | Listar sesiones |
| DELETE | /auth/sessions/:id | Revocar sesion |

## Flujos

### Registro
```
1. Usuario ingresa email, password, nombre
2. Backend valida datos
3. Crea user + tenant (si es owner)
4. Envia email de verificacion
5. Usuario verifica email
6. Puede hacer login
```

### Login con MFA
```
1. Usuario ingresa email/password
2. Backend valida credenciales
3. Si MFA activo: responde {mfa_required: true}
4. Usuario ingresa codigo TOTP
5. Backend valida TOTP
6. Genera JWT + refresh token
7. Usuario autenticado
```

### OAuth Flow
```
1. Usuario click "Login con Google"
2. Redirect a Google
3. Usuario autoriza
4. Google redirige a callback
5. Backend intercambia code por tokens
6. Busca o crea usuario
7. Genera JWT
8. Redirige a app
```

## Seguridad

- Passwords hasheados con bcrypt (cost 12)
- Rate limiting en login (5 intentos/15min)
- Refresh token rotation
- Sesiones revocables
- IP tracking por sesion
- TOTP con drift tolerance

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| auth.module.ts | Completado | `modules/auth/` |
| jwt.strategy.ts | Completado | `strategies/` |
| oauth strategies | Completado | `strategies/` |
| DDL auth schema | Completado | `ddl/schemas/auth/` |

## Dependencias

### Depende de
- Ninguno (modulo base)

### Bloquea a
- SAAS-002 (Tenants)
- SAAS-003 (Users)
- Todos los modulos protegidos

## Criterios de Aceptacion

- [x] Registro funciona
- [x] Login funciona
- [x] JWT se genera y valida
- [x] Refresh token funciona
- [x] OAuth Google funciona
- [x] MFA TOTP funciona
- [x] Sesiones se pueden revocar

---

**Ultima actualizacion:** 2026-01-07