feat: add refresh token flow for long-lived sessions

- Add RefreshToken model with rotation
- Add POST /auth/refresh endpoint
- Add POST /auth/logout that revokes refresh token
- Login returns JWT (8h) + refresh_token (30 days)
- Refresh rotates token (old is revoked)
- Fix Carbon\Carbon::now() calls instead of now() helper
- Update API docs

api/src/Controllers/AuthController.php

@@ -5,12 +5,16 @@ declare(strict_types=1);
 namespace App\Controllers;
 
 use App\Models\User;
+use App\Models\RefreshToken;
 use Firebase\JWT\JWT;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 
 final class AuthController
 {
+    private const JWT_EXPIRY = 8 * 60 * 60; // 8 hours
+    private const REFRESH_EXPIRY_DAYS = 30;
+
     public function login(ServerRequestInterface $request, ResponseInterface $response): ResponseInterface
     {
         $body = json_decode($request->getBody()->getContents(), true);
@@ -32,6 +36,80 @@ final class AuthController
         }
 
         // Generate JWT
+        $jwt = $this->generateJwt($user);
+
+        // Generate refresh token
+        $refreshToken = $this->generateRefreshToken($user->id);
+
+        $userData = $user->toArray();
+        unset($userData['password_hash']);
+
+        return $this->json($response, [
+            'token' => $jwt,
+            'refresh_token' => $refreshToken,
+            'expires_in' => self::JWT_EXPIRY,
+            'user' => $userData,
+        ]);
+    }
+
+    public function refresh(ServerRequestInterface $request, ResponseInterface $response): ResponseInterface
+    {
+        $body = json_decode($request->getBody()->getContents(), true);
+        $refreshToken = $body['refresh_token'] ?? '';
+
+        if (empty($refreshToken)) {
+            return $this->json($response, ['message' => 'Refresh token required'], 400);
+        }
+
+        // Find and validate refresh token
+        $tokenRecord = RefreshToken::findValid($refreshToken);
+
+        if (!$tokenRecord) {
+            return $this->json($response, ['message' => 'Invalid or expired refresh token'], 401);
+        }
+
+        // Load user
+        $user = User::find($tokenRecord->user_id);
+
+        if (!$user || !$user->is_active) {
+            return $this->json($response, ['message' => 'User not found or disabled'], 401);
+        }
+
+        // Generate new JWT
+        $jwt = $this->generateJwt($user);
+
+        // Optionally rotate refresh token (revoke old, create new)
+        $tokenRecord->revoke();
+        $newRefreshToken = $this->generateRefreshToken($user->id);
+
+        $userData = $user->toArray();
+        unset($userData['password_hash']);
+
+        return $this->json($response, [
+            'token' => $jwt,
+            'refresh_token' => $newRefreshToken,
+            'expires_in' => self::JWT_EXPIRY,
+            'user' => $userData,
+        ]);
+    }
+
+    public function logout(ServerRequestInterface $request, ResponseInterface $response): ResponseInterface
+    {
+        $body = json_decode($request->getBody()->getContents(), true);
+        $refreshToken = $body['refresh_token'] ?? null;
+
+        if ($refreshToken) {
+            $tokenRecord = RefreshToken::findValid($refreshToken);
+            if ($tokenRecord) {
+                $tokenRecord->revoke();
+            }
+        }
+
+        return $this->json($response, ['message' => 'Logged out']);
+    }
+
+    private function generateJwt(User $user): string
+    {
         $now = time();
         $payload = [
             'iss' => 'api.fahrschultermin.de',
@@ -39,35 +117,28 @@ final class AuthController
             'tenant_id' => $user->tenant_id,
             'role' => $user->role,
             'iat' => $now,
-            'exp' => $now + (8 * 60 * 60), // 8 hours
+            'exp' => $now + self::JWT_EXPIRY,
         ];
 
-        $jwt = JWT::encode($payload, $_ENV['JWT_SECRET'] ?? 'this-is-a-32-character-secret-key-for-testing', 'HS256');
-
-        $userData = $user->toArray();
-        unset($userData['password_hash']);
-
-        return $this->json($response, [
-            'token' => $jwt,
-            'user' => $userData,
-        ]);
-    }
-
-    public function me(ServerRequestInterface $request, ResponseInterface $response): ResponseInterface
-    {
-        $user = $request->getAttribute('user');
-
-        if (!$user) {
-            return $this->json($response, ['message' => 'Unauthenticated'], 401);
+        $secret = $_ENV['JWT_SECRET'] ?? null;
+        if (!$secret) {
+            throw new \RuntimeException('JWT_SECRET environment variable not set');
         }
-
-        return $this->json($response, ['user' => $user]);
+        return JWT::encode($payload, $secret, 'HS256');
     }
 
-    public function logout(ResponseInterface $response): ResponseInterface
+    private function generateRefreshToken(int $userId): string
     {
-        // JWT is stateless, logout is client-side (discard token)
-        return $this->json($response, ['message' => 'Logged out']);
+        $token = bin2hex(random_bytes(32)); // 64-char hex token
+        $hash = hash('sha256', $token);
+
+        RefreshToken::create([
+            'user_id' => $userId,
+            'token_hash' => $hash,
+            'expires_at' => \Carbon\Carbon::now()->addDays(self::REFRESH_EXPIRY_DAYS),
+        ]);
+
+        return $token;
     }
 
     private function json(ResponseInterface $response, array $data, int $status = 200): ResponseInterface