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>

tests/ApiTestCase.php

@@ -12,20 +12,32 @@ use Slim\Psr7\Factory\ServerRequestFactory;
 
 /**
  * Boots the real Slim app against a throwaway SQLite database with all
- * migrations applied.
+ * migrations applied. Email goes to a per-test log file (MAIL_TRANSPORT=log).
  */
 abstract class ApiTestCase extends TestCase
 {
     protected App $app;
     private string $databasePath;
+    private string $mailLogPath;
+    private ?PDO $db = null;
+
+    /** @var array<string, string> */
+    private array $env = [];
 
     protected function setUp(): void
     {
-        $this->databasePath = sys_get_temp_dir() . '/todo-test-' . uniqid() . '.sqlite';
-        putenv('DATABASE_PATH=' . $this->databasePath);
-        $_ENV['DATABASE_PATH'] = $this->databasePath;
+        $unique = uniqid('todo-test-', true);
+        $this->databasePath = sys_get_temp_dir() . "/{$unique}.sqlite";
+        $this->mailLogPath = sys_get_temp_dir() . "/{$unique}.mail.log";
 
-        $pdo = new PDO('sqlite:' . $this->databasePath);
+        $this->setEnv([
+            'DATABASE_PATH' => $this->databasePath,
+            'APP_URL' => 'https://app.test',
+            'MAIL_TRANSPORT' => 'log',
+            'MAIL_LOG_PATH' => $this->mailLogPath,
+        ]);
+
+        $pdo = $this->db();
         $pdo->exec('PRAGMA foreign_keys = ON');
         foreach (glob(dirname(__DIR__) . '/migrations/*.sql') ?: [] as $migration) {
             $pdo->exec((string) file_get_contents($migration));
@@ -36,9 +48,39 @@ abstract class ApiTestCase extends TestCase
 
     protected function tearDown(): void
     {
+        $this->db = null;
         @unlink($this->databasePath);
-        putenv('DATABASE_PATH');
-        unset($_ENV['DATABASE_PATH']);
+        @unlink($this->mailLogPath);
+
+        foreach (array_keys($this->env) as $key) {
+            putenv($key);
+            unset($_ENV[$key], $_SERVER[$key]);
+        }
+        $this->env = [];
+    }
+
+    /** @param array<string, string> $vars */
+    private function setEnv(array $vars): void
+    {
+        foreach ($vars as $key => $value) {
+            putenv("{$key}={$value}");
+            $_ENV[$key] = $value;
+            $_SERVER[$key] = $value;
+            $this->env[$key] = $value;
+        }
+    }
+
+    /** A connection to the test database, for seeding rows directly. */
+    protected function db(): PDO
+    {
+        if ($this->db === null) {
+            $this->db = new PDO('sqlite:' . $this->databasePath, null, null, [
+                PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
+                PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
+            ]);
+        }
+
+        return $this->db;
     }
 
     /**
@@ -78,6 +120,39 @@ abstract class ApiTestCase extends TestCase
         return ['Authorization' => 'Bearer ' . $token];
     }
 
+    /** All emails sent so far, oldest first. @return list<array{to: string, subject: string, body: string}> */
+    protected function sentEmails(): array
+    {
+        if (!is_file($this->mailLogPath)) {
+            return [];
+        }
+
+        $lines = array_filter(explode("\n", (string) file_get_contents($this->mailLogPath)));
+
+        return array_map(
+            static fn (string $line): array => json_decode($line, true, 512, JSON_THROW_ON_ERROR),
+            array_values($lines),
+        );
+    }
+
+    /** @return array{to: string, subject: string, body: string} */
+    protected function lastEmail(): array
+    {
+        $emails = $this->sentEmails();
+        self::assertNotEmpty($emails, 'Expected an email to have been sent.');
+
+        return $emails[array_key_last($emails)];
+    }
+
+    /** Pull the magic-link token out of an email body. */
+    protected function tokenFromEmail(?array $email = null): string
+    {
+        $email ??= $this->lastEmail();
+        self::assertSame(1, preg_match('/verify-email\?token=([a-f0-9]+)/', $email['body'], $m));
+
+        return $m[1];
+    }
+
     /**
      * @return array<string, mixed>
      */