specleap-framework 2.1.0 → 2.1.5

package/openspec/examples/CHANGE-SAMPLE-001-user-authentication/specs/technical/T001-jwt-implementation.spec.md

@@ -0,0 +1,606 @@
+# T001 — Implementación JWT
+
+| Campo | Valor |
+|-------|-------|
+| ID | T001 |
+| Título | Implementación de Autenticación JWT |
+| Dominio | technical |
+| Estado | implemented |
+| Autor | SpecLeap Contributor |
+| Fecha Creación | 2026-02-12 |
+| Última Actualización | 2026-02-12 |
+| Versión | 1.0 |
+| Relacionada | F001-authentication |
+
+## Descripción
+
+Especificación técnica de la implementación de autenticación basada en JSON Web Tokens (JWT) con algoritmo RS256, gestión de claves RSA, y middleware de autorización.
+
+## Arquitectura de Componentes
+
+### Componentes Implementados
+
+```
+AuthController (API Layer)
+    ├── AuthService (Business Logic)
+    │   ├── UserRepository (Data Access)
+    │   └── JWTService (Token Management)
+    │       └── RSA Keys (public/private)
+    │
+    ├── RateLimitMiddleware
+    │   └── LoginAttemptsRepository
+    │
+    └── AuthMiddleware (Request Guard)
+        └── JWTService (validation)
+```
+
+## Especificación de Clases
+
+### JWTService
+
+**Responsabilidad:** Generación y validación de tokens JWT.
+
+#### Métodos
+
+```php
+class JWTService
+{
+    /**
+     * Genera un token JWT para un usuario.
+     *
+     * @param User $user Usuario autenticado
+     * @param bool $remember Extender expiración a 30 días
+     * @return string Token JWT firmado
+     */
+    public function generateToken(User $user, bool $remember = false): string;
+
+    /**
+     * Valida un token JWT.
+     *
+     * @param string $token Token a validar
+     * @return array Payload decodificado
+     * @throws TokenExpiredException Si el token expiró
+     * @throws TokenInvalidException Si la firma no es válida
+     */
+    public function validateToken(string $token): array;
+
+    /**
+     * Refresca un token JWT.
+     *
+     * @param string $token Token actual
+     * @return string Nuevo token
+     */
+    public function refreshToken(string $token): string;
+
+    /**
+     * Revoca un token (añade a blacklist).
+     *
+     * @param string $token Token a revocar
+     * @return void
+     */
+    public function revokeToken(string $token): void;
+}
+```
+
+#### Estructura del Token JWT
+
+**Header:**
+```json
+{
+  "alg": "RS256",
+  "typ": "JWT"
+}
+```
+
+**Payload:**
+```json
+{
+  "sub": 123,              // user_id
+  "email": "user@example.com",
+  "iat": 1707753600,       // issued at (Unix timestamp)
+  "exp": 1707840000,       // expiration (Unix timestamp)
+  "remember": false        // opcional
+}
+```
+
+**Signature:**
+```
+RSASHA256(
+  base64UrlEncode(header) + "." +
+  base64UrlEncode(payload),
+  privateKey
+)
+```
+
+#### Configuración de Claves RSA
+
+**Generación:**
+```bash
+# Private key (4096 bits)
+openssl genrsa -out private.pem 4096
+
+# Public key
+openssl rsa -in private.pem -pubout -out public.pem
+```
+
+**Ubicación:**
+```
+storage/keys/
+├── private.pem  (chmod 600, no commitear)
+└── public.pem   (chmod 644, OK commitear)
+```
+
+**Variables de entorno:**
+```env
+JWT_PRIVATE_KEY_PATH=/path/to/private.pem
+JWT_PUBLIC_KEY_PATH=/path/to/public.pem
+JWT_TTL=86400              # 24 horas en segundos
+JWT_TTL_REMEMBER=2592000   # 30 días en segundos
+```
+
+---
+
+### AuthService
+
+**Responsabilidad:** Lógica de negocio de autenticación.
+
+#### Métodos
+
+```php
+class AuthService
+{
+    /**
+     * Autentica un usuario con email y contraseña.
+     *
+     * @param string $email
+     * @param string $password
+     * @param bool $remember
+     * @return array ['token' => string, 'user' => User]
+     * @throws AuthenticationException Si credenciales inválidas
+     */
+    public function authenticate(
+        string $email,
+        string $password,
+        bool $remember = false
+    ): array;
+
+    /**
+     * Cierra la sesión de un usuario.
+     *
+     * @param string $token Token a invalidar
+     * @return void
+     */
+    public function logout(string $token): void;
+}
+```
+
+#### Flujo de Autenticación
+
+1. **Validar inputs:**
+   - Email: formato válido, max 255 chars
+   - Password: min 8 chars, max 255 chars
+
+2. **Buscar usuario:**
+   ```php
+   $user = UserRepository::findByEmail($email);
+   if (!$user) {
+       throw new AuthenticationException('Credenciales inválidas');
+   }
+   ```
+
+3. **Verificar contraseña:**
+   ```php
+   if (!Hash::check($password, $user->password_hash)) {
+       // Registrar intento fallido
+       LoginAttempt::create([
+           'email' => $email,
+           'ip_address' => request()->ip(),
+           'success' => false
+       ]);
+       throw new AuthenticationException('Credenciales inválidas');
+   }
+   ```
+
+4. **Generar token:**
+   ```php
+   $token = JWTService::generateToken($user, $remember);
+   ```
+
+5. **Registrar intento exitoso:**
+   ```php
+   LoginAttempt::create([
+       'email' => $email,
+       'ip_address' => request()->ip(),
+       'success' => true
+   ]);
+   ```
+
+6. **Retornar respuesta:**
+   ```php
+   return [
+       'token' => $token,
+       'token_type' => 'Bearer',
+       'expires_in' => $remember ? 2592000 : 86400,
+       'user' => [
+           'id' => $user->id,
+           'email' => $user->email
+       ]
+   ];
+   ```
+
+---
+
+### AuthMiddleware
+
+**Responsabilidad:** Proteger rutas que requieren autenticación.
+
+#### Implementación
+
+```php
+class AuthMiddleware
+{
+    public function handle(Request $request, Closure $next)
+    {
+        // 1. Extraer token del header
+        $token = $request->bearerToken();
+        
+        if (!$token) {
+            return response()->json([
+                'error' => 'No autenticado. Token requerido.'
+            ], 401);
+        }
+        
+        try {
+            // 2. Validar token
+            $payload = JWTService::validateToken($token);
+            
+            // 3. Obtener usuario
+            $user = User::find($payload['sub']);
+            
+            if (!$user) {
+                return response()->json([
+                    'error' => 'Usuario no encontrado'
+                ], 401);
+            }
+            
+            // 4. Adjuntar usuario al request
+            $request->setUserResolver(function () use ($user) {
+                return $user;
+            });
+            
+            return $next($request);
+            
+        } catch (TokenExpiredException $e) {
+            return response()->json([
+                'error' => 'Token expirado. Inicie sesión nuevamente.'
+            ], 401);
+            
+        } catch (TokenInvalidException $e) {
+            return response()->json([
+                'error' => 'Token inválido'
+            ], 401);
+        }
+    }
+}
+```
+
+---
+
+### RateLimitMiddleware
+
+**Responsabilidad:** Protección contra brute force.
+
+#### Configuración
+
+```php
+const MAX_ATTEMPTS = 5;
+const LOCKOUT_TIME = 1800; // 30 minutos en segundos
+const DECAY_MINUTES = 15;
+```
+
+#### Implementación
+
+```php
+class RateLimitMiddleware
+{
+    public function handle(Request $request, Closure $next)
+    {
+        $email = $request->input('email');
+        $ip = $request->ip();
+        $key = "login_attempts:{$email}:{$ip}";
+        
+        // 1. Contar intentos fallidos recientes
+        $attempts = LoginAttempt::where('email', $email)
+            ->where('ip_address', $ip)
+            ->where('success', false)
+            ->where('attempted_at', '>=', now()->subMinutes(self::DECAY_MINUTES))
+            ->count();
+        
+        // 2. Verificar si está bloqueado
+        if ($attempts >= self::MAX_ATTEMPTS) {
+            $lastAttempt = LoginAttempt::where('email', $email)
+                ->where('ip_address', $ip)
+                ->orderBy('attempted_at', 'desc')
+                ->first();
+            
+            $lockoutUntil = $lastAttempt->attempted_at
+                ->addSeconds(self::LOCKOUT_TIME);
+            
+            if (now()->lt($lockoutUntil)) {
+                $remainingMinutes = now()->diffInMinutes($lockoutUntil);
+                
+                return response()->json([
+                    'error' => "Cuenta temporalmente bloqueada por intentos fallidos. Intente nuevamente en {$remainingMinutes} minutos."
+                ], 429);
+            }
+        }
+        
+        return $next($request);
+    }
+}
+```
+
+---
+
+## Modelo de Datos
+
+### Tabla: `login_attempts`
+
+```sql
+CREATE TABLE login_attempts (
+    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+    email VARCHAR(255) NOT NULL,
+    ip_address VARCHAR(45) NOT NULL,
+    user_agent TEXT,
+    success BOOLEAN DEFAULT FALSE,
+    attempted_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    
+    INDEX idx_email_ip (email, ip_address),
+    INDEX idx_attempted_at (attempted_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+```
+
+**Campos:**
+- `email`: Email del intento (puede no existir en users)
+- `ip_address`: IPv4 o IPv6
+- `user_agent`: User agent del navegador
+- `success`: true = login exitoso, false = fallido
+- `attempted_at`: Timestamp del intento
+
+**Índices:**
+- `idx_email_ip`: Para rate limiting (WHERE email AND ip_address)
+- `idx_attempted_at`: Para cleanup de registros antiguos
+
+---
+
+## Endpoints API
+
+### POST /api/v1/auth/login
+
+**Middleware:** RateLimitMiddleware
+
+**Request:**
+```http
+POST /api/v1/auth/login HTTP/1.1
+Content-Type: application/json
+
+{
+  "email": "user@example.com",
+  "password": "SecureP@ssw0rd",
+  "remember": false
+}
+```
+
+**Response (200 OK):**
+```json
+{
+  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "Bearer",
+  "expires_in": 86400,
+  "user": {
+    "id": 123,
+    "email": "user@example.com"
+  }
+}
+```
+
+---
+
+### POST /api/v1/auth/logout
+
+**Middleware:** AuthMiddleware
+
+**Request:**
+```http
+POST /api/v1/auth/logout HTTP/1.1
+Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+**Response (200 OK):**
+```json
+{
+  "message": "Sesión cerrada exitosamente"
+}
+```
+
+---
+
+### GET /api/v1/auth/me
+
+**Middleware:** AuthMiddleware
+
+**Request:**
+```http
+GET /api/v1/auth/me HTTP/1.1
+Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+**Response (200 OK):**
+```json
+{
+  "id": 123,
+  "email": "user@example.com",
+  "created_at": "2026-01-15T10:30:00Z"
+}
+```
+
+---
+
+## Seguridad
+
+### Protecciones Implementadas
+
+1. **Hashing de contraseñas:**
+   - Bcrypt con cost factor 12
+   - Nunca almacenar contraseñas en texto plano
+   - Verificación con timing-safe comparison
+
+2. **Rate limiting:**
+   - 5 intentos/15min por IP+email
+   - Bloqueo temporal de 30 minutos
+   - No aplicar a logins exitosos
+
+3. **JWT seguro:**
+   - Firma asimétrica (RS256)
+   - Claves RSA 4096 bits
+   - Payload mínimo (sin datos sensibles)
+   - Expiración obligatoria
+
+4. **Headers de seguridad:**
+   ```php
+   'X-Content-Type-Options' => 'nosniff',
+   'X-Frame-Options' => 'DENY',
+   'Content-Security-Policy' => "default-src 'self'",
+   'Strict-Transport-Security' => 'max-age=31536000; includeSubDomains'
+   ```
+
+5. **Logging y auditoría:**
+   - Todos los intentos registrados
+   - IP, user agent, timestamp
+   - Retención 90 días mínimo
+
+### Vulnerabilidades Mitigadas
+
+| Vulnerabilidad | Mitigación |
+|----------------|-----------|
+| Brute force | Rate limiting + bloqueo temporal |
+| Timing attacks | Hash comparison constante |
+| SQL injection | ORM + prepared statements |
+| XSS | Sanitización de outputs |
+| CSRF | Tokens CSRF en formularios web |
+| Session hijacking | Tokens HttpOnly, HTTPS obligatorio |
+| Enumeración de usuarios | Mensajes genéricos |
+
+---
+
+## Performance
+
+### Benchmarks
+
+| Operación | Tiempo (P95) |
+|-----------|--------------|
+| generateToken() | 15ms |
+| validateToken() | 8ms |
+| Hash::check() | 250ms |
+| DB query (findByEmail) | 5ms |
+| Total login | ~280ms |
+
+### Optimizaciones
+
+1. **Cachear public key:**
+   ```php
+   Cache::remember('jwt_public_key', 3600, function () {
+       return file_get_contents(config('jwt.public_key_path'));
+   });
+   ```
+
+2. **Índices de BD:**
+   - `users.email` (UNIQUE)
+   - `login_attempts.email_ip` (compuesto)
+   - `login_attempts.attempted_at` (para queries con ventana de tiempo)
+
+3. **Rate limiting en Redis (futuro):**
+   ```php
+   // Mover de DB a Redis para mejor performance
+   Redis::incr("rate_limit:{$email}:{$ip}");
+   Redis::expire("rate_limit:{$email}:{$ip}", 900);
+   ```
+
+---
+
+## Testing
+
+### Unit Tests Requeridos
+
+```php
+// JWTServiceTest.php
+test_generate_token_includes_correct_claims()
+test_generate_token_with_remember_extends_expiry()
+test_validate_token_with_valid_token()
+test_validate_token_throws_on_expired_token()
+test_validate_token_throws_on_tampered_signature()
+
+// AuthServiceTest.php
+test_authenticate_with_valid_credentials()
+test_authenticate_with_invalid_password()
+test_authenticate_with_nonexistent_email()
+test_logout_revokes_token()
+
+// RateLimitMiddlewareTest.php
+test_allows_requests_under_limit()
+test_blocks_after_max_attempts()
+test_resets_after_lockout_period()
+```
+
+### Integration Tests Requeridos
+
+```php
+test_login_endpoint_returns_token()
+test_login_endpoint_fails_with_invalid_credentials()
+test_logout_endpoint_invalidates_token()
+test_me_endpoint_returns_user_data()
+test_protected_route_requires_valid_token()
+```
+
+---
+
+## Configuración
+
+### Variables de Entorno
+
+```env
+# JWT Configuration
+JWT_PRIVATE_KEY_PATH=/var/www/storage/keys/private.pem
+JWT_PUBLIC_KEY_PATH=/var/www/storage/keys/public.pem
+JWT_TTL=86400
+JWT_TTL_REMEMBER=2592000
+JWT_ALGORITHM=RS256
+
+# Rate Limiting
+RATE_LIMIT_MAX_ATTEMPTS=5
+RATE_LIMIT_DECAY_MINUTES=15
+RATE_LIMIT_LOCKOUT_SECONDS=1800
+
+# Security
+BCRYPT_COST=12
+HTTPS_ONLY=true
+```
+
+---
+
+## Referencias
+
+- JWT RFC 7519: https://tools.ietf.org/html/rfc7519
+- RS256 Algorithm: https://tools.ietf.org/html/rfc7518#section-3.3
+- OWASP Auth Cheatsheet: https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html
+
+## 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