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/Repository/EmailVerificationRepository.php

@@ -0,0 +1,98 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Repository;
+
+use PDO;
+
+/**
+ * Data access for `email_verifications` (magic-link tokens).
+ *
+ * @phpstan-type TokenRow array{
+ *     id: int, user_id: int, token_hash: string, new_email: string|null,
+ *     expires_at: string, consumed_at: string|null, created_at: string
+ * }
+ */
+final class EmailVerificationRepository
+{
+    public function __construct(private readonly PDO $pdo)
+    {
+    }
+
+    /**
+     * Replace any outstanding (unconsumed) tokens of the same kind for the user,
+     * then store a new one.
+     */
+    public function issue(int $userId, string $tokenHash, ?string $newEmail, int $ttlSeconds): void
+    {
+        // Drop the user's outstanding tokens of the same kind (verify vs. change).
+        $nullClause = $newEmail === null ? 'new_email IS NULL' : 'new_email IS NOT NULL';
+        $this->pdo
+            ->prepare("DELETE FROM email_verifications WHERE user_id = :user AND consumed_at IS NULL AND {$nullClause}")
+            ->execute(['user' => $userId]);
+
+        $insert = $this->pdo->prepare(
+            'INSERT INTO email_verifications (user_id, token_hash, new_email, expires_at)
+             VALUES (:user, :hash, :new_email, :expires_at)'
+        );
+        $insert->execute([
+            'user' => $userId,
+            'hash' => $tokenHash,
+            'new_email' => $newEmail,
+            'expires_at' => gmdate('Y-m-d\TH:i:s\Z', time() + $ttlSeconds),
+        ]);
+    }
+
+    /**
+     * @return TokenRow|null
+     */
+    public function findByHash(string $tokenHash): ?array
+    {
+        $stmt = $this->pdo->prepare('SELECT * FROM email_verifications WHERE token_hash = :hash');
+        $stmt->execute(['hash' => $tokenHash]);
+
+        $row = $stmt->fetch();
+        if ($row === false) {
+            return null;
+        }
+
+        $row['id'] = (int) $row['id'];
+        $row['user_id'] = (int) $row['user_id'];
+
+        /** @var TokenRow $row */
+        return $row;
+    }
+
+    /**
+     * Mark the token consumed. Returns false if it was already consumed (race).
+     */
+    public function consume(int $id): bool
+    {
+        $stmt = $this->pdo->prepare(
+            "UPDATE email_verifications SET consumed_at = strftime('%Y-%m-%dT%H:%M:%SZ', 'now')
+             WHERE id = :id AND consumed_at IS NULL"
+        );
+        $stmt->execute(['id' => $id]);
+
+        return $stmt->rowCount() === 1;
+    }
+
+    /**
+     * The address a still-valid change request is waiting on, if any.
+     */
+    public function pendingEmailFor(int $userId): ?string
+    {
+        $stmt = $this->pdo->prepare(
+            "SELECT new_email FROM email_verifications
+             WHERE user_id = :user AND new_email IS NOT NULL AND consumed_at IS NULL
+               AND expires_at > strftime('%Y-%m-%dT%H:%M:%SZ', 'now')
+             ORDER BY id DESC LIMIT 1"
+        );
+        $stmt->execute(['user' => $userId]);
+
+        $value = $stmt->fetchColumn();
+
+        return $value === false ? null : (string) $value;
+    }
+}

src/Repository/UserRepository.php

@@ -9,7 +9,7 @@ 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, email_verified_at: string|null, created_at: string, updated_at: string}
+ * @phpstan-type UserRow 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}
  */
 final class UserRepository
 {
@@ -62,6 +62,35 @@ final class UserRepository
         return $user;
     }
 
+    public function markEmailVerified(int $id): void
+    {
+        $this->pdo->prepare(
+            "UPDATE users SET email_verified_at = strftime('%Y-%m-%dT%H:%M:%SZ', 'now'),
+                    updated_at = strftime('%Y-%m-%dT%H:%M:%SZ', 'now')
+             WHERE id = :id"
+        )->execute(['id' => $id]);
+    }
+
+    /**
+     * Apply a confirmed email change: set the address and mark it verified.
+     */
+    public function updateEmail(int $id, string $email): void
+    {
+        $this->pdo->prepare(
+            "UPDATE users SET email = :email,
+                    email_verified_at = strftime('%Y-%m-%dT%H:%M:%SZ', 'now'),
+                    updated_at = strftime('%Y-%m-%dT%H:%M:%SZ', 'now')
+             WHERE id = :id"
+        )->execute(['email' => $email, 'id' => $id]);
+    }
+
+    public function markVerificationEmailSent(int $id): void
+    {
+        $this->pdo->prepare(
+            "UPDATE users SET verification_email_sent_at = strftime('%Y-%m-%dT%H:%M:%SZ', 'now') WHERE id = :id"
+        )->execute(['id' => $id]);
+    }
+
     /**
      * @param array<string, mixed> $row
      * @return UserRow