Add stage 7: email verification magic links and a profile page

Backend
- New Mail namespace: a Mailer interface with SMTP (phpmailer), PHP mail()
  (the default fallback), and log-to-file transports, selected by
  MAIL_TRANSPORT. EmailVerifier issues a hashed, 15-minute magic-link token
  and sends the link (APP_URL/verify-email?token=...).
- Migration 005: email_verifications table + users.verification_email_sent_at.
- Registration now emails a verification link (best effort — a send failure
  doesn't fail registration).
- POST /api/auth/verify-email consumes a token and returns a session, so
  opening the link verifies the address (or applies a pending email change)
  and logs the user in. Single-use; distinct 400s for invalid/used/expired.
- POST /api/email/verification resends; POST /api/email/change requests a
  deferred change (current password required; link goes to the new address;
  users.email only updates when that link is opened). Both throttled to once
  per 60s, returning 429 + retry_after.
- GET /api/me and every session payload now include pending_email. Shared
  SessionPayload builds the user/session JSON for all entry points.

Frontend
- /verify-email view: posts the token, adopts the returned session, redirects.
- /profile view: shows address + status, a resend button with a live cooldown
  (driven by retry_after / 429), and a change-email form (new address +
  current password) that surfaces the pending change.
- Header shows a "verify email" badge linking to the profile.

Tests: 9 new (EmailVerificationTest) covering the link lifecycle, throttle,
and deferred change; AuthTest folded into ApiTestCase, which now routes mail
to a per-test log. Suite: 32 passing.

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

src/Http/Controllers/AuthController.php

@@ -4,9 +4,11 @@ declare(strict_types=1);
 
 namespace App\Http\Controllers;
 
-use App\Auth\JwtService;
+use App\Auth\SessionPayload;
 use App\Exception\ApiException;
 use App\Exception\ValidationException;
+use App\Mail\EmailVerifier;
+use App\Mail\MailException;
 use App\Repository\UserRepository;
 use Psr\Http\Message\ResponseInterface as Response;
 use Psr\Http\Message\ServerRequestInterface as Request;
@@ -22,7 +24,8 @@ final class AuthController extends Controller
 
     public function __construct(
         private readonly UserRepository $users,
-        private readonly JwtService $jwt,
+        private readonly SessionPayload $session,
+        private readonly EmailVerifier $verifier,
     ) {
     }
 
@@ -39,7 +42,15 @@ final class AuthController extends Controller
 
         $user = $this->users->create($email, password_hash($password, PASSWORD_DEFAULT));
 
-        return $this->json($response, $this->session($user), 201);
+        // Best effort: a failed send must not fail registration — the user can
+        // resend from their profile.
+        try {
+            $this->verifier->sendVerification($user);
+        } catch (MailException $e) {
+            error_log('Verification email failed for user ' . $user['id'] . ': ' . $e->getMessage());
+        }
+
+        return $this->json($response, $this->session->forUser($user), 201);
     }
 
     /**
@@ -56,7 +67,7 @@ final class AuthController extends Controller
             throw new ApiException('Invalid email or password.', 401);
         }
 
-        return $this->json($response, $this->session($user));
+        return $this->json($response, $this->session->forUser($user));
     }
 
     /**
@@ -64,10 +75,7 @@ final class AuthController extends Controller
      */
     public function me(Request $request, Response $response): Response
     {
-        /** @var array{id: int, email: string, email_verified_at: string|null, created_at: string} $user */
-        $user = $request->getAttribute('user');
-
-        return $this->json($response, ['user' => $this->presentUser($user)]);
+        return $this->json($response, ['user' => $this->session->present($this->user($request))]);
     }
 
     /**
@@ -106,38 +114,4 @@ final class AuthController extends Controller
 
         return [mb_strtolower($email), $password];
     }
-
-    /**
-     * Build the standard authentication payload returned by register and login.
-     *
-     * @param array{id: int, email: string, email_verified_at: string|null, 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, email_verified_at?: string|null, created_at?: string} $user
-     * @return array<string, mixed>
-     */
-    private function presentUser(array $user): array
-    {
-        $verifiedAt = $user['email_verified_at'] ?? null;
-
-        return [
-            'id' => (int) $user['id'],
-            'email' => $user['email'],
-            'email_verified' => $verifiedAt !== null,
-            'email_verified_at' => $verifiedAt,
-            'created_at' => $user['created_at'] ?? null,
-        ];
-    }
 }

src/Http/Controllers/Controller.php

@@ -41,13 +41,13 @@ abstract class Controller
     }
 
     /**
-     * The authenticated user attached by AuthMiddleware.
+     * The authenticated user row attached by AuthMiddleware.
      *
-     * @return array{id: int, email: string, email_verified_at: string|null, created_at: string}
+     * @return array{id: int, email: string, password_hash: string, email_verified_at: string|null, verification_email_sent_at: string|null, created_at: string, updated_at: string}
      */
     protected function user(Request $request): array
     {
-        /** @var array{id: int, email: string, email_verified_at: string|null, created_at: string} $user */
+        /** @var array{id: int, email: string, password_hash: string, email_verified_at: string|null, verification_email_sent_at: string|null, created_at: string, updated_at: string} $user */
         $user = $request->getAttribute('user');
 
         return $user;

src/Http/Controllers/EmailVerificationController.php

@@ -0,0 +1,176 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use App\Auth\SessionPayload;
+use App\Exception\ApiException;
+use App\Exception\ValidationException;
+use App\Mail\EmailVerifier;
+use App\Mail\MailException;
+use App\Repository\EmailVerificationRepository;
+use App\Repository\UserRepository;
+use Psr\Http\Message\ResponseInterface as Response;
+use Psr\Http\Message\ServerRequestInterface as Request;
+
+final class EmailVerificationController extends Controller
+{
+    private const RESEND_INTERVAL_SECONDS = 60;
+    private const EMAIL_MAX = 255;
+    private const PASSWORD_MAX = 72;
+
+    public function __construct(
+        private readonly UserRepository $users,
+        private readonly EmailVerificationRepository $tokens,
+        private readonly EmailVerifier $verifier,
+        private readonly SessionPayload $session,
+    ) {
+    }
+
+    /**
+     * POST /api/auth/verify-email  (public)
+     *
+     * Consumes a magic-link token: verifies the address (or applies a pending
+     * email change), then returns a session so the caller is logged in.
+     */
+    public function verify(Request $request, Response $response): Response
+    {
+        $token = trim((string) ($this->body($request)['token'] ?? ''));
+        if ($token === '') {
+            throw new ValidationException(['token' => ['A verification token is required.']]);
+        }
+
+        $row = $this->tokens->findByHash(hash('sha256', $token));
+
+        if ($row === null) {
+            throw new ApiException('This verification link is not valid.', 400);
+        }
+        if ($row['consumed_at'] !== null) {
+            throw new ApiException('This verification link has already been used.', 400);
+        }
+        if (strtotime($row['expires_at']) < time()) {
+            throw new ApiException('This verification link has expired. Request a new one.', 400);
+        }
+
+        if ($row['new_email'] !== null) {
+            $clash = $this->users->findByEmail($row['new_email']);
+            if ($clash !== null && $clash['id'] !== $row['user_id']) {
+                throw new ApiException('That email address is now in use by another account.', 409);
+            }
+        }
+
+        if (!$this->tokens->consume($row['id'])) {
+            throw new ApiException('This verification link has already been used.', 400);
+        }
+
+        if ($row['new_email'] !== null) {
+            $this->users->updateEmail($row['user_id'], $row['new_email']);
+        } else {
+            $this->users->markEmailVerified($row['user_id']);
+        }
+
+        $user = $this->users->findById($row['user_id']);
+        if ($user === null) {
+            throw new ApiException('The account for this link no longer exists.', 404);
+        }
+
+        return $this->json($response, $this->session->forUser($user));
+    }
+
+    /**
+     * POST /api/email/verification  (auth) — resend the verification email.
+     */
+    public function resend(Request $request, Response $response): Response
+    {
+        $user = $this->user($request);
+
+        if (($user['email_verified_at'] ?? null) !== null) {
+            throw new ApiException('Your email address is already verified.', 409);
+        }
+
+        $this->guardResendInterval($user);
+
+        try {
+            $this->verifier->sendVerification($user);
+        } catch (MailException $e) {
+            throw new ApiException('Could not send the email right now. Please try again shortly.', 502);
+        }
+
+        return $this->json($response, [
+            'message' => 'Verification email sent.',
+            'retry_after' => self::RESEND_INTERVAL_SECONDS,
+        ], 202);
+    }
+
+    /**
+     * POST /api/email/change  (auth) — request a deferred email change. The new
+     * address only takes effect once its magic link is opened.
+     */
+    public function requestChange(Request $request, Response $response): Response
+    {
+        $user = $this->user($request);
+        $body = $this->body($request);
+
+        $newEmail = is_string($body['email'] ?? null) ? mb_strtolower(trim($body['email'])) : '';
+        $password = is_string($body['password'] ?? null) ? $body['password'] : '';
+
+        $errors = [];
+        if ($newEmail === '') {
+            $errors['email'][] = 'Email is required.';
+        } elseif (!filter_var($newEmail, FILTER_VALIDATE_EMAIL) || strlen($newEmail) > self::EMAIL_MAX) {
+            $errors['email'][] = 'Enter a valid email address.';
+        } elseif ($newEmail === mb_strtolower($user['email'])) {
+            $errors['email'][] = 'That is already your email address.';
+        }
+        if ($password === '' || strlen($password) > self::PASSWORD_MAX) {
+            $errors['password'][] = 'Your current password is required.';
+        }
+        if ($errors !== []) {
+            throw new ValidationException($errors);
+        }
+
+        $full = $this->users->findById($user['id']);
+        if ($full === null || !password_verify($password, $full['password_hash'])) {
+            throw new ValidationException(['password' => ['That password is incorrect.']]);
+        }
+
+        if ($this->users->findByEmail($newEmail) !== null) {
+            throw new ApiException('That email address is already in use.', 409);
+        }
+
+        $this->guardResendInterval($user);
+
+        try {
+            $this->verifier->sendEmailChange($user, $newEmail);
+        } catch (MailException $e) {
+            throw new ApiException('Could not send the email right now. Please try again shortly.', 502);
+        }
+
+        return $this->json($response, [
+            'message' => 'Confirmation email sent to the new address.',
+            'pending_email' => $newEmail,
+            'retry_after' => self::RESEND_INTERVAL_SECONDS,
+        ], 202);
+    }
+
+    /**
+     * @param array{verification_email_sent_at?: string|null} $user
+     */
+    private function guardResendInterval(array $user): void
+    {
+        $lastSent = $user['verification_email_sent_at'] ?? null;
+        if ($lastSent === null) {
+            return;
+        }
+
+        $elapsed = time() - (int) strtotime($lastSent);
+        if ($elapsed < self::RESEND_INTERVAL_SECONDS) {
+            throw new ApiException(
+                'Please wait a moment before requesting another email.',
+                429,
+                ['retry_after' => self::RESEND_INTERVAL_SECONDS - $elapsed],
+            );
+        }
+    }
+}