specleap-framework 2.1.0 → 2.1.5

package/openspec/examples/CHANGE-SAMPLE-001-user-authentication/specs/functional/F001-authentication.spec.md

@@ -0,0 +1,399 @@
+# F001 — Autenticación de Usuario
+
+| Campo | Valor |
+|-------|-------|
+| ID | F001 |
+| Título | Autenticación de Usuario |
+| Dominio | functional |
+| Estado | implemented |
+| Autor | SpecLeap Contributor |
+| Fecha Creación | 2026-02-12 |
+| Última Actualización | 2026-02-12 |
+| Versión | 1.0 |
+
+## Descripción
+
+Sistema de autenticación basado en email y contraseña que permite a los usuarios identificarse de forma segura y acceder a funcionalidades protegidas del sistema mediante tokens JWT.
+
+## Actores
+
+- **Usuario Registrado:** Usuario con cuenta activa en el sistema
+- **Sistema:** Backend que valida credenciales y genera tokens
+- **Usuario Anónimo:** Visitante sin credenciales válidas
+
+## Precondiciones
+
+- El usuario debe estar registrado en el sistema
+- El email del usuario debe estar verificado (fuera de alcance de esta spec)
+- El sistema debe tener par de claves RSA configuradas para JWT
+
+## Escenarios
+
+### Escenario 1: Login exitoso con credenciales válidas
+
+**Descripción:** Usuario registrado se autentica correctamente.
+
+**GIVEN:**
+- Un usuario registrado con email `usuario@example.com`
+- Contraseña válida `Passw0rd!123`
+- Menos de 5 intentos fallidos en los últimos 15 minutos
+
+**WHEN:**
+- El usuario envía POST a `/api/v1/auth/login` con:
+  ```json
+  {
+    "email": "usuario@example.com",
+    "password": "Passw0rd!123"
+  }
+  ```
+
+**THEN:**
+- El sistema valida las credenciales contra la base de datos
+- AND genera un token JWT válido por 24 horas
+- AND devuelve respuesta 200 OK con:
+  ```json
+  {
+    "token": "eyJhbGciOiJSUzI1NiIs...",
+    "token_type": "Bearer",
+    "expires_in": 86400,
+    "user": {
+      "id": 123,
+      "email": "usuario@example.com"
+    }
+  }
+  ```
+- AND registra el intento exitoso en `login_attempts`
+- AND resetea el contador de intentos fallidos
+
+---
+
+### Escenario 2: Login con "Remember Me"
+
+**Descripción:** Usuario solicita sesión extendida.
+
+**GIVEN:**
+- Un usuario registrado con credenciales válidas
+
+**WHEN:**
+- El usuario envía POST a `/api/v1/auth/login` con:
+  ```json
+  {
+    "email": "usuario@example.com",
+    "password": "Passw0rd!123",
+    "remember": true
+  }
+  ```
+
+**THEN:**
+- El sistema genera token JWT válido por **30 días** (en lugar de 24h)
+- AND devuelve respuesta 200 OK con `expires_in: 2592000`
+- AND el token incluye claim `remember: true`
+
+---
+
+### Escenario 3: Login fallido - contraseña incorrecta
+
+**Descripción:** Usuario ingresa contraseña errónea.
+
+**GIVEN:**
+- Un usuario registrado con email `usuario@example.com`
+- Contraseña incorrecta `WrongPassword`
+
+**WHEN:**
+- El usuario envía POST con contraseña incorrecta
+
+**THEN:**
+- El sistema devuelve 401 Unauthorized con:
+  ```json
+  {
+    "error": "Credenciales inválidas"
+  }
+  ```
+- AND **NO** revela que el email existe
+- AND **NO** revela que la contraseña es incorrecta
+- AND registra el intento fallido en `login_attempts`
+- AND incrementa contador de intentos fallidos
+
+---
+
+### Escenario 4: Login fallido - email no registrado
+
+**Descripción:** Usuario intenta login con email que no existe.
+
+**GIVEN:**
+- Email `noexiste@example.com` no está en la base de datos
+
+**WHEN:**
+- El usuario envía POST con ese email
+
+**THEN:**
+- El sistema devuelve 401 Unauthorized con:
+  ```json
+  {
+    "error": "Credenciales inválidas"
+  }
+  ```
+- AND **NO** revela que el email no existe
+- AND registra el intento con IP y email
+- AND **NO** bloquea por intentos (no hay cuenta que bloquear)
+
+---
+
+### Escenario 5: Bloqueo por intentos fallidos
+
+**Descripción:** Protección contra brute force.
+
+**GIVEN:**
+- Un usuario ha fallado 5 intentos de login en los últimos 15 minutos
+- Desde la misma IP
+
+**WHEN:**
+- El usuario intenta login nuevamente (6º intento)
+
+**THEN:**
+- El sistema devuelve 429 Too Many Requests con:
+  ```json
+  {
+    "error": "Cuenta temporalmente bloqueada por intentos fallidos. Intente nuevamente en 30 minutos."
+  }
+  ```
+- AND **NO** valida las credenciales (bloqueo preventivo)
+- AND registra el intento bloqueado
+- AND el bloqueo dura 30 minutos desde el 5º intento fallido
+
+---
+
+### Escenario 6: Desbloqueo automático tras expiración
+
+**Descripción:** Bloqueo temporal se levanta automáticamente.
+
+**GIVEN:**
+- Un usuario fue bloqueado hace 31 minutos
+- No hubo más intentos desde entonces
+
+**WHEN:**
+- El usuario intenta login con credenciales válidas
+
+**THEN:**
+- El sistema permite el login
+- AND resetea contador de intentos fallidos
+- AND genera token JWT normal
+
+---
+
+### Escenario 7: Logout
+
+**Descripción:** Usuario cierra sesión.
+
+**GIVEN:**
+- Un usuario autenticado con token JWT válido
+
+**WHEN:**
+- El usuario envía POST a `/api/v1/auth/logout` con header:
+  ```
+  Authorization: Bearer {token}
+  ```
+
+**THEN:**
+- El sistema invalida el token (añade a blacklist o marca como revocado)
+- AND devuelve 200 OK con:
+  ```json
+  {
+    "message": "Sesión cerrada exitosamente"
+  }
+  ```
+- AND el token ya no es válido para requests subsiguientes
+
+---
+
+### Escenario 8: Acceso a ruta protegida con token válido
+
+**Descripción:** Middleware de autenticación permite acceso.
+
+**GIVEN:**
+- Un usuario tiene token JWT válido y no expirado
+
+**WHEN:**
+- El usuario envía request a ruta protegida con header:
+  ```
+  Authorization: Bearer {token}
+  ```
+
+**THEN:**
+- El middleware valida el token
+- AND extrae el user_id del payload
+- AND adjunta el objeto `user` al request
+- AND permite continuar con el request
+
+---
+
+### Escenario 9: Acceso a ruta protegida con token expirado
+
+**Descripción:** Middleware rechaza tokens expirados.
+
+**GIVEN:**
+- Un usuario tiene token JWT que expiró hace 1 hora
+
+**WHEN:**
+- El usuario envía request a ruta protegida con token expirado
+
+**THEN:**
+- El middleware valida el token
+- AND detecta que está expirado
+- AND devuelve 401 Unauthorized con:
+  ```json
+  {
+    "error": "Token expirado. Inicie sesión nuevamente."
+  }
+  ```
+- AND **NO** procesa el request
+
+---
+
+### Escenario 10: Acceso a ruta protegida sin token
+
+**Descripción:** Middleware rechaza requests sin autenticación.
+
+**GIVEN:**
+- Un usuario no autenticado
+
+**WHEN:**
+- El usuario envía request a ruta protegida sin header `Authorization`
+
+**THEN:**
+- El middleware devuelve 401 Unauthorized con:
+  ```json
+  {
+    "error": "No autenticado. Token requerido."
+  }
+  ```
+
+---
+
+### Escenario 11: Token con firma alterada (tampered)
+
+**Descripción:** Detección de tokens manipulados.
+
+**GIVEN:**
+- Un token JWT con firma modificada manualmente
+
+**WHEN:**
+- Se envía request con el token alterado
+
+**THEN:**
+- El middleware detecta firma inválida
+- AND devuelve 401 Unauthorized con:
+  ```json
+  {
+    "error": "Token inválido"
+  }
+  ```
+- AND registra el intento en logs de seguridad
+
+---
+
+### Escenario 12: Obtener información del usuario autenticado
+
+**Descripción:** Endpoint `/me` devuelve datos del usuario actual.
+
+**GIVEN:**
+- Un usuario autenticado con token válido
+
+**WHEN:**
+- El usuario envía GET a `/api/v1/auth/me` con token válido
+
+**THEN:**
+- El sistema devuelve 200 OK con:
+  ```json
+  {
+    "id": 123,
+    "email": "usuario@example.com",
+    "created_at": "2026-01-15T10:30:00Z"
+  }
+  ```
+
+---
+
+## Reglas de Negocio
+
+### RN-001: Contraseñas hasheadas
+- Las contraseñas NUNCA se almacenan en texto plano
+- Usar bcrypt con cost factor 12 mínimo
+- Verificación con `Hash::check()` o equivalente
+
+### RN-002: Rate limiting
+- Máximo 5 intentos fallidos por IP + email en 15 minutos
+- Bloqueo automático de 30 minutos tras exceder límite
+- No aplicar rate limiting a intentos exitosos
+
+### RN-003: Mensajes de error genéricos
+- NUNCA revelar si un email existe o no en el sistema
+- Siempre responder "Credenciales inválidas" (sin detalles)
+- Evitar ataques de enumeración de usuarios
+
+### RN-004: Tokens JWT
+- Firma con RS256 (asimétrico)
+- Expiración: 24 horas (normal) / 30 días (remember me)
+- Payload mínimo: user_id, exp, iat
+- No incluir datos sensibles en el payload
+
+### RN-005: Logging y auditoría
+- Registrar TODOS los intentos de login (exitosos y fallidos)
+- Almacenar: email, IP, user agent, timestamp, resultado
+- Retener logs mínimo 90 días (configurable)
+
+### RN-006: HTTPS obligatorio
+- En producción, rechazar requests HTTP
+- Redirigir HTTP → HTTPS automáticamente
+
+## Dependencias
+
+### Dependencias de Entrada
+- Usuario debe estar registrado (tabla `users`)
+- Par de claves RSA generadas y configuradas
+- Sistema de logging disponible
+
+### Dependencias de Salida
+- Tabla `login_attempts` para auditoría
+- Cache (Redis) opcional para tokens revocados
+- Sistema de notificaciones para alertas de bloqueo
+
+## Métricas
+
+### KPIs
+- **Tasa de éxito de login:** >95%
+- **Tiempo medio de autenticación:** <500ms
+- **Intentos de brute force bloqueados:** trackear y alertar
+
+### Monitoreo
+- Alertar si tasa de fallos >10% en 1 hora
+- Alertar si múltiples IPs atacan mismo usuario
+- Dashboard de intentos por hora/día
+
+## Casos No Cubiertos (Fuera de Alcance)
+
+- OAuth / Social login
+- Autenticación de dos factores (2FA)
+- Recuperación de contraseña
+- Verificación de email
+- SSO (Single Sign-On)
+- Biometría
+
+Estos se abordarán en specs futuras.
+
+## Referencias
+
+- OWASP Authentication Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html
+- JWT RFC 7519: https://tools.ietf.org/html/rfc7519
+- Bcrypt: https://en.wikipedia.org/wiki/Bcrypt
+
+## Historial de Cambios
+
+| Versión | Fecha | Autor | Cambios |
+|---------|-------|-------|---------|
+| 1.0 | 2026-02-12 | SpecLeap Contributor | Versión inicial implementada |
+
+---
+
+**Estado:** implemented  
+**Última revisión:** 2026-02-12