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>
This commit is contained in:
Claude Sonnet 5
@@ -0,0 +1,49 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Auth;
|
||||
|
||||
use App\Exception\ApiException;
|
||||
use App\Repository\UserRepository;
|
||||
use Psr\Http\Message\ResponseInterface as Response;
|
||||
use Psr\Http\Message\ServerRequestInterface as Request;
|
||||
use Psr\Http\Server\MiddlewareInterface;
|
||||
use Psr\Http\Server\RequestHandlerInterface as RequestHandler;
|
||||
use Throwable;
|
||||
|
||||
/**
|
||||
* Requires a valid `Authorization: Bearer <jwt>` header. On success the resolved
|
||||
* user row is attached to the request as the `user` attribute.
|
||||
*/
|
||||
final class AuthMiddleware implements MiddlewareInterface
|
||||
{
|
||||
public function __construct(
|
||||
private readonly JwtService $jwt,
|
||||
private readonly UserRepository $users,
|
||||
) {
|
||||
}
|
||||
|
||||
public function process(Request $request, RequestHandler $handler): Response
|
||||
{
|
||||
$header = $request->getHeaderLine('Authorization');
|
||||
|
||||
if (preg_match('/^Bearer\s+(\S+)$/i', $header, $matches) !== 1) {
|
||||
throw new ApiException('Missing or malformed Authorization header.', 401);
|
||||
}
|
||||
|
||||
try {
|
||||
$claims = $this->jwt->verify($matches[1]);
|
||||
} catch (Throwable) {
|
||||
throw new ApiException('The access token is invalid or has expired.', 401);
|
||||
}
|
||||
|
||||
$user = $this->users->findById((int) ($claims['sub'] ?? 0));
|
||||
|
||||
if ($user === null) {
|
||||
throw new ApiException('The account for this token no longer exists.', 401);
|
||||
}
|
||||
|
||||
return $handler->handle($request->withAttribute('user', $user));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,56 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Auth;
|
||||
|
||||
use Firebase\JWT\JWT;
|
||||
use Firebase\JWT\Key;
|
||||
|
||||
/**
|
||||
* Issues and verifies stateless HS256 JSON Web Tokens for authenticated users.
|
||||
*/
|
||||
final class JwtService
|
||||
{
|
||||
private const ALGORITHM = 'HS256';
|
||||
|
||||
public function __construct(
|
||||
private readonly string $secret,
|
||||
private readonly int $ttl,
|
||||
) {
|
||||
}
|
||||
|
||||
/**
|
||||
* @param array{id: int, email: string, ...} $user
|
||||
* @return array{token: string, expires_at: string}
|
||||
*/
|
||||
public function issue(array $user): array
|
||||
{
|
||||
$issuedAt = time();
|
||||
$expiresAt = $issuedAt + $this->ttl;
|
||||
|
||||
$token = JWT::encode([
|
||||
'sub' => (int) $user['id'],
|
||||
'email' => $user['email'],
|
||||
'iat' => $issuedAt,
|
||||
'exp' => $expiresAt,
|
||||
], $this->secret, self::ALGORITHM);
|
||||
|
||||
return [
|
||||
'token' => $token,
|
||||
'expires_at' => gmdate('c', $expiresAt),
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
* @return array<string, mixed> The decoded claims.
|
||||
*
|
||||
* @throws \Firebase\JWT\ExpiredException
|
||||
* @throws \Firebase\JWT\SignatureInvalidException
|
||||
* @throws \UnexpectedValueException
|
||||
*/
|
||||
public function verify(string $token): array
|
||||
{
|
||||
return (array) JWT::decode($token, new Key($this->secret, self::ALGORITHM));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Exception;
|
||||
|
||||
use RuntimeException;
|
||||
|
||||
/**
|
||||
* An error that should be reported to the client with a specific HTTP status and
|
||||
* a JSON body. Thrown by controllers and middleware, rendered by JsonErrorHandler.
|
||||
*/
|
||||
class ApiException extends RuntimeException
|
||||
{
|
||||
/**
|
||||
* @param array<string, mixed> $details Optional machine-readable context.
|
||||
*/
|
||||
public function __construct(
|
||||
string $message,
|
||||
private readonly int $statusCode = 400,
|
||||
private readonly array $details = [],
|
||||
) {
|
||||
parent::__construct($message);
|
||||
}
|
||||
|
||||
public function getStatusCode(): int
|
||||
{
|
||||
return $this->statusCode;
|
||||
}
|
||||
|
||||
/**
|
||||
* @return array<string, mixed>
|
||||
*/
|
||||
public function getDetails(): array
|
||||
{
|
||||
return $this->details;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Exception;
|
||||
|
||||
/**
|
||||
* Raised when request input fails validation. Carries a field => messages map.
|
||||
*/
|
||||
final class ValidationException extends ApiException
|
||||
{
|
||||
/**
|
||||
* @param array<string, string[]> $errors
|
||||
*/
|
||||
public function __construct(array $errors)
|
||||
{
|
||||
parent::__construct('The submitted data was invalid.', 422, $errors);
|
||||
}
|
||||
}
|
||||
@@ -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,
|
||||
];
|
||||
}
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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]];
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,76 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Repository;
|
||||
|
||||
use PDO;
|
||||
|
||||
/**
|
||||
* Data access for the `users` table. Rows are returned as associative arrays.
|
||||
*
|
||||
* @phpstan-type UserRow array{id: int, email: string, password_hash: string, created_at: string, updated_at: string}
|
||||
*/
|
||||
final class UserRepository
|
||||
{
|
||||
public function __construct(private readonly PDO $pdo)
|
||||
{
|
||||
}
|
||||
|
||||
/**
|
||||
* @return UserRow|null
|
||||
*/
|
||||
public function findByEmail(string $email): ?array
|
||||
{
|
||||
$stmt = $this->pdo->prepare('SELECT * FROM users WHERE email = :email');
|
||||
$stmt->execute(['email' => $email]);
|
||||
|
||||
$row = $stmt->fetch();
|
||||
|
||||
return $row === false ? null : $this->cast($row);
|
||||
}
|
||||
|
||||
/**
|
||||
* @return UserRow|null
|
||||
*/
|
||||
public function findById(int $id): ?array
|
||||
{
|
||||
$stmt = $this->pdo->prepare('SELECT * FROM users WHERE id = :id');
|
||||
$stmt->execute(['id' => $id]);
|
||||
|
||||
$row = $stmt->fetch();
|
||||
|
||||
return $row === false ? null : $this->cast($row);
|
||||
}
|
||||
|
||||
/**
|
||||
* @return UserRow
|
||||
*/
|
||||
public function create(string $email, string $passwordHash): array
|
||||
{
|
||||
$stmt = $this->pdo->prepare(
|
||||
'INSERT INTO users (email, password_hash) VALUES (:email, :password_hash)'
|
||||
);
|
||||
$stmt->execute([
|
||||
'email' => $email,
|
||||
'password_hash' => $passwordHash,
|
||||
]);
|
||||
|
||||
/** @var UserRow $user */
|
||||
$user = $this->findById((int) $this->pdo->lastInsertId());
|
||||
|
||||
return $user;
|
||||
}
|
||||
|
||||
/**
|
||||
* @param array<string, mixed> $row
|
||||
* @return UserRow
|
||||
*/
|
||||
private function cast(array $row): array
|
||||
{
|
||||
$row['id'] = (int) $row['id'];
|
||||
|
||||
/** @var UserRow $row */
|
||||
return $row;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,76 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Support;
|
||||
|
||||
/**
|
||||
* Immutable application configuration, resolved from environment variables with
|
||||
* development-friendly defaults.
|
||||
*/
|
||||
final class Config
|
||||
{
|
||||
public function __construct(
|
||||
public readonly string $databasePath,
|
||||
public readonly string $jwtSecret,
|
||||
public readonly int $jwtTtl,
|
||||
public readonly bool $displayErrors,
|
||||
) {
|
||||
}
|
||||
|
||||
public static function load(string $basePath): self
|
||||
{
|
||||
if (is_file($basePath . '/.env')) {
|
||||
\Dotenv\Dotenv::createImmutable($basePath)->safeLoad();
|
||||
}
|
||||
|
||||
$storagePath = $basePath . '/storage';
|
||||
if (!is_dir($storagePath)) {
|
||||
mkdir($storagePath, 0775, true);
|
||||
}
|
||||
|
||||
$databasePath = self::env('DATABASE_PATH', $storagePath . '/database.sqlite');
|
||||
if (!self::isAbsolutePath($databasePath)) {
|
||||
$databasePath = $basePath . '/' . ltrim($databasePath, '/');
|
||||
}
|
||||
|
||||
$jwtSecret = self::env('JWT_SECRET') ?? self::resolveSecret($storagePath . '/secret.key');
|
||||
$jwtTtl = (int) (self::env('JWT_TTL') ?? '86400');
|
||||
$displayErrors = filter_var(self::env('APP_DEBUG', 'false'), FILTER_VALIDATE_BOOL);
|
||||
|
||||
return new self($databasePath, $jwtSecret, $jwtTtl, $displayErrors);
|
||||
}
|
||||
|
||||
private static function env(string $key, ?string $default = null): ?string
|
||||
{
|
||||
$value = $_ENV[$key] ?? $_SERVER[$key] ?? getenv($key);
|
||||
|
||||
if ($value === false || $value === null || $value === '') {
|
||||
return $default;
|
||||
}
|
||||
|
||||
return (string) $value;
|
||||
}
|
||||
|
||||
private static function isAbsolutePath(string $path): bool
|
||||
{
|
||||
return str_starts_with($path, '/') || preg_match('#^[A-Za-z]:[\\\\/]#', $path) === 1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Return the persisted signing secret, generating and storing one on first run
|
||||
* so local development works with zero configuration.
|
||||
*/
|
||||
private static function resolveSecret(string $path): string
|
||||
{
|
||||
if (is_file($path)) {
|
||||
return trim((string) file_get_contents($path));
|
||||
}
|
||||
|
||||
$secret = bin2hex(random_bytes(32));
|
||||
file_put_contents($path, $secret);
|
||||
@chmod($path, 0600);
|
||||
|
||||
return $secret;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Support;
|
||||
|
||||
use PDO;
|
||||
|
||||
/**
|
||||
* Thin wrapper around a PDO connection to the SQLite database.
|
||||
*/
|
||||
final class Database
|
||||
{
|
||||
private PDO $pdo;
|
||||
|
||||
public function __construct(string $path)
|
||||
{
|
||||
$this->pdo = new PDO('sqlite:' . $path, null, null, [
|
||||
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
|
||||
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
|
||||
PDO::ATTR_EMULATE_PREPARES => false,
|
||||
]);
|
||||
|
||||
$this->pdo->exec('PRAGMA foreign_keys = ON');
|
||||
$this->pdo->exec('PRAGMA journal_mode = WAL');
|
||||
}
|
||||
|
||||
public function pdo(): PDO
|
||||
{
|
||||
return $this->pdo;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,52 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
use App\Auth\AuthMiddleware;
|
||||
use App\Auth\JwtService;
|
||||
use App\Http\Controllers\AuthController;
|
||||
use App\Http\JsonErrorHandler;
|
||||
use App\Repository\UserRepository;
|
||||
use App\Support\Config;
|
||||
use App\Support\Database;
|
||||
use Psr\Http\Message\ResponseInterface as Response;
|
||||
use Psr\Http\Message\ServerRequestInterface as Request;
|
||||
use Slim\Factory\AppFactory;
|
||||
use Slim\Routing\RouteCollectorProxy;
|
||||
|
||||
$config = Config::load(dirname(__DIR__));
|
||||
$database = new Database($config->databasePath);
|
||||
|
||||
$app = AppFactory::create();
|
||||
|
||||
$app->addBodyParsingMiddleware();
|
||||
$app->addRoutingMiddleware();
|
||||
|
||||
$errorMiddleware = $app->addErrorMiddleware($config->displayErrors, true, true);
|
||||
$errorMiddleware->setDefaultErrorHandler(
|
||||
new JsonErrorHandler($app->getResponseFactory(), $config->displayErrors)
|
||||
);
|
||||
|
||||
// --- Wiring -----------------------------------------------------------------
|
||||
|
||||
$users = new UserRepository($database->pdo());
|
||||
$jwt = new JwtService($config->jwtSecret, $config->jwtTtl);
|
||||
|
||||
$authController = new AuthController($users, $jwt);
|
||||
$authMiddleware = new AuthMiddleware($jwt, $users);
|
||||
|
||||
// --- Routes ---------------------------------------------------------------
|
||||
|
||||
$app->group('/api', function (RouteCollectorProxy $group) use ($authController, $authMiddleware) {
|
||||
$group->get('/health', function (Request $request, Response $response): Response {
|
||||
$response->getBody()->write((string) json_encode(['status' => 'ok']));
|
||||
return $response->withHeader('Content-Type', 'application/json');
|
||||
});
|
||||
|
||||
$group->post('/auth/register', [$authController, 'register']);
|
||||
$group->post('/auth/login', [$authController, 'login']);
|
||||
|
||||
$group->get('/me', [$authController, 'me'])->add($authMiddleware);
|
||||
});
|
||||
|
||||
return $app;
|
||||
Reference in New Issue
Block a user