Add stage 1: authentication REST API

Slim 4 + SQLite todo-list API providing email/password registration,
login, and an authenticated GET /me endpoint. Stateless HS256 JWTs,
bcrypt password hashing, uniform JSON error envelope, and a SQL
migration runner. Includes PHPUnit feature tests and stage-1 docs.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

src/Http/Controllers/AuthController.php

@@ -0,0 +1,139 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use App\Auth\JwtService;
+use App\Exception\ApiException;
+use App\Exception\ValidationException;
+use App\Repository\UserRepository;
+use Psr\Http\Message\ResponseInterface as Response;
+use Psr\Http\Message\ServerRequestInterface as Request;
+
+final class AuthController extends Controller
+{
+    private const PASSWORD_MIN = 8;
+
+    // bcrypt (password_hash's current default) only considers the first 72 bytes.
+    private const PASSWORD_MAX = 72;
+
+    private const EMAIL_MAX = 255;
+
+    public function __construct(
+        private readonly UserRepository $users,
+        private readonly JwtService $jwt,
+    ) {
+    }
+
+    /**
+     * POST /api/auth/register
+     */
+    public function register(Request $request, Response $response): Response
+    {
+        [$email, $password] = $this->credentials($request);
+
+        if ($this->users->findByEmail($email) !== null) {
+            throw new ApiException('That email address is already registered.', 409);
+        }
+
+        $user = $this->users->create($email, password_hash($password, PASSWORD_DEFAULT));
+
+        return $this->json($response, $this->session($user), 201);
+    }
+
+    /**
+     * POST /api/auth/login
+     */
+    public function login(Request $request, Response $response): Response
+    {
+        [$email, $password] = $this->credentials($request);
+
+        $user = $this->users->findByEmail($email);
+
+        if ($user === null || !password_verify($password, $user['password_hash'])) {
+            // Same message either way so we don't reveal which emails are registered.
+            throw new ApiException('Invalid email or password.', 401);
+        }
+
+        return $this->json($response, $this->session($user));
+    }
+
+    /**
+     * GET /api/me  (requires AuthMiddleware)
+     */
+    public function me(Request $request, Response $response): Response
+    {
+        /** @var array{id: int, email: string, created_at: string} $user */
+        $user = $request->getAttribute('user');
+
+        return $this->json($response, ['user' => $this->presentUser($user)]);
+    }
+
+    /**
+     * Extract and validate the email/password pair from the request body.
+     *
+     * @return array{0: string, 1: string} Normalised email and raw password.
+     */
+    private function credentials(Request $request): array
+    {
+        $body = (array) ($request->getParsedBody() ?? []);
+
+        $email = is_string($body['email'] ?? null) ? trim($body['email']) : '';
+        $password = is_string($body['password'] ?? null) ? $body['password'] : '';
+
+        $errors = [];
+
+        if ($email === '') {
+            $errors['email'][] = 'Email is required.';
+        } elseif (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
+            $errors['email'][] = 'Email must be a valid address.';
+        } elseif (strlen($email) > self::EMAIL_MAX) {
+            $errors['email'][] = sprintf('Email must be at most %d characters.', self::EMAIL_MAX);
+        }
+
+        if ($password === '') {
+            $errors['password'][] = 'Password is required.';
+        } elseif (strlen($password) < self::PASSWORD_MIN) {
+            $errors['password'][] = sprintf('Password must be at least %d characters.', self::PASSWORD_MIN);
+        } elseif (strlen($password) > self::PASSWORD_MAX) {
+            $errors['password'][] = sprintf('Password must be at most %d characters.', self::PASSWORD_MAX);
+        }
+
+        if ($errors !== []) {
+            throw new ValidationException($errors);
+        }
+
+        return [mb_strtolower($email), $password];
+    }
+
+    /**
+     * Build the standard authentication payload returned by register and login.
+     *
+     * @param array{id: int, email: string, created_at: string} $user
+     * @return array<string, mixed>
+     */
+    private function session(array $user): array
+    {
+        $token = $this->jwt->issue($user);
+
+        return [
+            'user' => $this->presentUser($user),
+            'token' => $token['token'],
+            'expires_at' => $token['expires_at'],
+        ];
+    }
+
+    /**
+     * @param array{id: int, email: string, created_at?: string} $user
+     * @return array<string, mixed>
+     */
+    private function presentUser(array $user): array
+    {
+        return [
+            'id' => (int) $user['id'],
+            'email' => $user['email'],
+            'created_at' => $user['created_at'] ?? null,
+        ];
+    }
+}

src/Http/Controllers/Controller.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use Psr\Http\Message\ResponseInterface as Response;
+
+/**
+ * Shared helpers for HTTP controllers.
+ */
+abstract class Controller
+{
+    /**
+     * Write a JSON body and return the response with the appropriate headers.
+     *
+     * @param array<string, mixed> $data
+     */
+    protected function json(Response $response, array $data, int $status = 200): Response
+    {
+        $response->getBody()->write(
+            (string) json_encode($data, JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT)
+        );
+
+        return $response
+            ->withHeader('Content-Type', 'application/json')
+            ->withStatus($status);
+    }
+}

src/Http/JsonErrorHandler.php

@@ -0,0 +1,76 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http;
+
+use App\Exception\ApiException;
+use Psr\Http\Message\ResponseFactoryInterface;
+use Psr\Http\Message\ResponseInterface as Response;
+use Psr\Http\Message\ServerRequestInterface as Request;
+use Slim\Exception\HttpMethodNotAllowedException;
+use Slim\Exception\HttpNotFoundException;
+use Throwable;
+
+/**
+ * Renders every uncaught error as a consistent JSON envelope:
+ *
+ *   { "error": { "message": string, "details"?: object } }
+ */
+final class JsonErrorHandler
+{
+    public function __construct(
+        private readonly ResponseFactoryInterface $responseFactory,
+        private readonly bool $displayErrorDetails,
+    ) {
+    }
+
+    public function __invoke(
+        Request $request,
+        Throwable $exception,
+        bool $displayErrorDetails,
+        bool $logErrors,
+        bool $logErrorDetails,
+    ): Response {
+        [$status, $payload] = $this->describe($exception);
+
+        $response = $this->responseFactory->createResponse($status);
+        $response->getBody()->write(
+            (string) json_encode($payload, JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT)
+        );
+
+        return $response->withHeader('Content-Type', 'application/json');
+    }
+
+    /**
+     * @return array{0: int, 1: array<string, mixed>}
+     */
+    private function describe(Throwable $exception): array
+    {
+        if ($exception instanceof ApiException) {
+            $error = ['message' => $exception->getMessage()];
+            if ($exception->getDetails() !== []) {
+                $error['details'] = $exception->getDetails();
+            }
+
+            return [$exception->getStatusCode(), ['error' => $error]];
+        }
+
+        if ($exception instanceof HttpNotFoundException) {
+            return [404, ['error' => ['message' => 'The requested resource was not found.']]];
+        }
+
+        if ($exception instanceof HttpMethodNotAllowedException) {
+            return [405, ['error' => ['message' => 'Method not allowed for this resource.']]];
+        }
+
+        $error = ['message' => 'An unexpected error occurred.'];
+        if ($this->displayErrorDetails) {
+            $error['message'] = $exception->getMessage();
+            $error['exception'] = $exception::class;
+            $error['file'] = $exception->getFile() . ':' . $exception->getLine();
+        }
+
+        return [500, ['error' => $error]];
+    }
+}