template-saas/docs/01-modulos/SAAS-001-auth.md

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

• Registro funciona
• Login funciona
• JWT se genera y valida
• Refresh token funciona
• OAuth Google funciona
• MFA TOTP funciona
• Sesiones se pueden revocar

---

Ultima actualizacion: 2026-01-07