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/Mail/EmailVerifier.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Mail;
+
+use App\Repository\EmailVerificationRepository;
+use App\Repository\UserRepository;
+
+/**
+ * Issues a magic-link token and emails it, for both "verify your address" and
+ * "confirm your new address" flows.
+ */
+final class EmailVerifier
+{
+    public const TOKEN_TTL_SECONDS = 900; // 15 minutes
+
+    public function __construct(
+        private readonly EmailVerificationRepository $tokens,
+        private readonly UserRepository $users,
+        private readonly Mailer $mailer,
+        private readonly string $appUrl,
+    ) {
+    }
+
+    /**
+     * Send a link that verifies the user's current address.
+     *
+     * @param array{id: int, email: string} $user
+     */
+    public function sendVerification(array $user): void
+    {
+        $link = $this->issue((int) $user['id'], null);
+
+        $this->mailer->send(
+            $user['email'],
+            'Verify your email address',
+            "Welcome!\n\n"
+            . "Confirm this email address by opening the link below. It expires in 15 minutes.\n\n"
+            . $link . "\n\n"
+            . "If you didn't create an account, you can ignore this message.\n",
+        );
+    }
+
+    /**
+     * Send a link (to the new address) that, once opened, changes the user's
+     * email to $newEmail.
+     *
+     * @param array{id: int, email: string} $user
+     */
+    public function sendEmailChange(array $user, string $newEmail): void
+    {
+        $link = $this->issue((int) $user['id'], $newEmail);
+
+        $this->mailer->send(
+            $newEmail,
+            'Confirm your new email address',
+            "A request was made to change the email address on an account to this one.\n\n"
+            . "Confirm the change by opening the link below. It expires in 15 minutes.\n\n"
+            . $link . "\n\n"
+            . "If this wasn't you, you can ignore this message; nothing will change.\n",
+        );
+    }
+
+    private function issue(int $userId, ?string $newEmail): string
+    {
+        $token = bin2hex(random_bytes(32));
+
+        $this->tokens->issue($userId, hash('sha256', $token), $newEmail, self::TOKEN_TTL_SECONDS);
+        $this->users->markVerificationEmailSent($userId);
+
+        return $this->appUrl . '/verify-email?token=' . $token;
+    }
+}

src/Mail/LogMailer.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Mail;
+
+/**
+ * Appends each message as a JSON line to a file instead of sending it. Handy for
+ * local development and used by the test suite. Enable with MAIL_TRANSPORT=log.
+ */
+final class LogMailer implements Mailer
+{
+    public function __construct(private readonly string $path)
+    {
+    }
+
+    public function send(string $to, string $subject, string $body): void
+    {
+        $dir = dirname($this->path);
+        if (!is_dir($dir)) {
+            mkdir($dir, 0775, true);
+        }
+
+        $line = json_encode([
+            'sent_at' => gmdate('c'),
+            'to' => $to,
+            'subject' => $subject,
+            'body' => $body,
+        ], JSON_UNESCAPED_SLASHES) . "\n";
+
+        if (file_put_contents($this->path, $line, FILE_APPEND | LOCK_EX) === false) {
+            throw new MailException("Could not write to the mail log at {$this->path}.");
+        }
+    }
+}

src/Mail/MailException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Mail;
+
+use RuntimeException;
+
+final class MailException extends RuntimeException
+{
+}

src/Mail/Mailer.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Mail;
+
+interface Mailer
+{
+    /**
+     * Send a plain-text email.
+     *
+     * @throws MailException when delivery fails.
+     */
+    public function send(string $to, string $subject, string $body): void;
+}

src/Mail/PhpMailerMailer.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Mail;
+
+use App\Support\MailConfig;
+use PHPMailer\PHPMailer\Exception as PhpMailerException;
+use PHPMailer\PHPMailer\PHPMailer;
+
+/**
+ * Sends via SMTP when MAIL_TRANSPORT=smtp, otherwise via PHP's mail() function.
+ */
+final class PhpMailerMailer implements Mailer
+{
+    public function __construct(private readonly MailConfig $config)
+    {
+    }
+
+    public function send(string $to, string $subject, string $body): void
+    {
+        $mail = new PHPMailer(true);
+
+        try {
+            if ($this->config->transport === 'smtp') {
+                $this->configureSmtp($mail);
+            } else {
+                $mail->isMail();
+            }
+
+            $mail->setFrom($this->config->fromAddress, $this->config->fromName);
+            $mail->addAddress($to);
+            $mail->Subject = $subject;
+            $mail->isHTML(false);
+            $mail->Body = $body;
+
+            $mail->send();
+        } catch (PhpMailerException $e) {
+            throw new MailException('Failed to send email: ' . $e->getMessage(), 0, $e);
+        }
+    }
+
+    private function configureSmtp(PHPMailer $mail): void
+    {
+        $mail->isSMTP();
+        $mail->Host = (string) $this->config->smtpHost;
+        $mail->Port = $this->config->smtpPort;
+
+        if ($this->config->smtpUsername !== null) {
+            $mail->SMTPAuth = true;
+            $mail->Username = $this->config->smtpUsername;
+            $mail->Password = (string) $this->config->smtpPassword;
+        }
+
+        switch ($this->config->smtpEncryption) {
+            case 'ssl':
+                $mail->SMTPSecure = PHPMailer::ENCRYPTION_SMTPS;
+                break;
+            case 'none':
+                $mail->SMTPSecure = '';
+                $mail->SMTPAutoTLS = false;
+                break;
+            default:
+                $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
+        }
+    }
+}