PRD — Dominio 01: auth

Identidad. Registro, verificación, login, sesiones, credenciales. Toda decisión de autorización (qué puede hacer un usuario) se delega al dominio authz.

---

1. Propósito

Gestionar la identidad de los usuarios: registro, verificación, login, sesiones y credenciales. Garantizar que toda persona que accede a la plataforma tiene una identidad verificable y un token válido.

2. Entidades

Entidad	Responsabilidad
AuthCredentials	Email/teléfono + password hash asociado a un Account
Session	Refresh tokens activos por dispositivo
VerificationCode	OTP para verificación de email/teléfono y reset de password

Lee de accounts: solo el Account para coordinar creación al registrar.

3. Historias de usuario

• U-1. Registrarme con email + password.
• U-2. Verificar mi email antes de poder operar (reservar, publicar servicios).
• U-3. Iniciar sesión y recibir un par de tokens.
• U-4. Recuperar mi password vía código enviado a email/WhatsApp.
• U-5. Cerrar sesión en un dispositivo específico o en todos.
• U-6. Renovar mi token automáticamente sin reingresar credenciales.

4. Requerimientos funcionales

• RF-1 Registro con email + password. Teléfono opcional al inicio.
• RF-2 Password mínimo: 8 caracteres, ≥1 número. Hash con Argon2id.
• RF-3 Al registrarse → código de verificación al email (6 dígitos, expira 15 min).
• RF-4 Al registrarse → se crea también un Account en el dominio accounts (transacción coordinada).
• RF-5 Login emite: access_token (JWT, 15 min) + refresh_token (30 días, rotado).
• RF-6 El JWT solo contiene: account_id, device_id, iat, exp, email_verified. No lleva roles ni permisos.
• RF-7 Endpoint /auth/refresh rota el par de tokens.
• RF-8 Endpoint /auth/logout revoca el refresh del dispositivo actual.
• RF-9 Endpoint /auth/logout/all revoca todos los refresh del Account.
• RF-10 Endpoint /auth/reset-password (solicitar) y /auth/reset-password/confirm (con código).
• RF-11 Rate limiting: 5 intentos de login por IP/email en 15 min.
• RF-12 Endpoint /auth/me devuelve identidad básica del usuario. No devuelve permisos — las apps consultan authz cuando los necesitan para la UI.
• RF-13 OAuth social (Google, Apple) — fuera de MVP, fase 2.

5. Reglas de negocio

• RN-1 Un Account puede tener múltiples sesiones activas simultáneas (una por dispositivo).
• RN-2 El rol global platform_admin NO se auto-asigna, lo asigna otro admin escribiendo directamente en authz (relación platform:main#admin@account).
• RN-3 Usuario no verificado puede navegar la plataforma, pero cualquier acción sensible la bloquea authz o un gate explícito basado en email_verified.
• RN-4 Cambiar password → revoca todas las sesiones del Account.
• RN-5 Los OTP son de un solo uso, expiran en 15 minutos.

6. Flujos críticos

Registro:

POST /auth/register → crea Account + AuthCredentials (en la misma transacción)
  → emite VerificationCode
  → emite relación inicial en authz (p.ej. self-ownership)
  → 201 + tokens + email_verified:false

Login:

POST /auth/login → verifica credencial (Argon2id) + rate limit
  → crea Session
  → emite JWT
  → 200 + tokens

Refresh:

POST /auth/refresh → verifica refresh válido y no revocado
  → rota par de tokens
  → 200 + nuevos tokens

7. Dependencias

Dominio	Tipo
accounts	Crea el Account al registrarse.
authz	Escribe relación inicial (self-account) al registrar. Sin lectura en el flujo de auth.
notifications	Envía códigos de verificación y reset.

Ningún dominio depende de auth más allá de la validación del JWT (middleware compartido verifica firma y extrae account_id).

8. Fuera de alcance (MVP)

• OAuth social (Google/Apple) — fase 2.
• Biometría en móvil — fase 2.
• 2FA con TOTP — fase 2.
• SSO empresarial — no roadmap.

9. Métricas

• ≥95% verifican email en 24h
• <1% tasa de fallos técnicos de login
• Registro completo en <30s
• 0 incidentes de seguridad