cloud/project-manager
3
0
Fork 0
Code Issues Pull Requests Actions Packages Releases Activity

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

Browse Source 
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>
This commit is contained in:
aneurin
2026-09-03 20:04:49 +01:00
co-authored by Claude Sonnet 5
parent c4c947896e
commit f9b65cc4a7
32 changed files with 1374 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/ApiTestCase.php
+82 -7
View File
@@ -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>
*/
tests/AuthTest.php
+2 -58
View File
@@ -4,38 +4,8 @@ declare(strict_types=1);
namespace Tests;
use PDO;
use PHPUnit\Framework\TestCase;
use Psr\Http\Message\ResponseInterface;
use Slim\App;
use Slim\Psr7\Factory\ServerRequestFactory;
final class AuthTest extends TestCase
final class AuthTest extends ApiTestCase
{
private App $app;
private string $databasePath;
protected function setUp(): void
{
$this->databasePath = sys_get_temp_dir() . '/todo-test-' . uniqid() . '.sqlite';
putenv('DATABASE_PATH=' . $this->databasePath);
$_ENV['DATABASE_PATH'] = $this->databasePath;
$pdo = new PDO('sqlite:' . $this->databasePath);
foreach (glob(dirname(__DIR__) . '/migrations/*.sql') ?: [] as $migration) {
$pdo->exec((string) file_get_contents($migration));
}
$this->app = require dirname(__DIR__) . '/src/bootstrap.php';
}
protected function tearDown(): void
{
@unlink($this->databasePath);
putenv('DATABASE_PATH');
unset($_ENV['DATABASE_PATH']);
}
public function test_registration_returns_a_user_and_token(): void
{
$response = $this->request('POST', '/api/auth/register', [
@@ -49,6 +19,7 @@ final class AuthTest extends TestCase
self::assertSame('ada@example.com', $body['user']['email']);
self::assertFalse($body['user']['email_verified']);
self::assertNull($body['user']['email_verified_at']);
self::assertNull($body['user']['pending_email']);
self::assertArrayNotHasKey('password_hash', $body['user']);
self::assertNotEmpty($body['token']);
}
@@ -123,31 +94,4 @@ final class AuthTest extends TestCase
self::assertSame(200, $response->getStatusCode());
self::assertSame('linus@example.com', $this->decode($response)['user']['email']);
}
/**
* @param array<string, mixed>|null $body
* @param array<string, string> $headers
*/
private function request(string $method, string $path, ?array $body = null, array $headers = []): ResponseInterface
{
$request = (new ServerRequestFactory())->createServerRequest($method, $path);
foreach ($headers as $name => $value) {
$request = $request->withHeader($name, $value);
}
if ($body !== null) {
$request = $request->withParsedBody($body)->withHeader('Content-Type', 'application/json');
}
return $this->app->handle($request);
}
/**
* @return array<string, mixed>
*/
private function decode(ResponseInterface $response): array
{
return (array) json_decode((string) $response->getBody(), true, 512, JSON_THROW_ON_ERROR);
}
}
tests/EmailVerificationTest.php
+176
View File
@@ -0,0 +1,176 @@
<?php
declare(strict_types=1);
namespace Tests;
final class EmailVerificationTest extends ApiTestCase
{
public function test_registration_sends_a_verification_email(): void
{
$this->request('POST', '/api/auth/register', ['email' => 'ada@example.com', 'password' => 'password123']);
$email = $this->lastEmail();
self::assertSame('ada@example.com', $email['to']);
self::assertStringContainsString('verify-email?token=', $email['body']);
self::assertStringContainsString('https://app.test/verify-email?token=', $email['body']);
}
public function test_opening_the_magic_link_verifies_and_logs_in(): void
{
$this->request('POST', '/api/auth/register', ['email' => 'ada@example.com', 'password' => 'password123']);
$response = $this->request('POST', '/api/auth/verify-email', ['token' => $this->tokenFromEmail()]);
self::assertSame(200, $response->getStatusCode());
$body = $this->decode($response);
self::assertTrue($body['user']['email_verified']);
self::assertNotEmpty($body['token']);
$me = $this->decode($this->request('GET', '/api/me', null, ['Authorization' => 'Bearer ' . $body['token']]));
self::assertTrue($me['user']['email_verified']);
}
public function test_an_invalid_token_is_rejected(): void
{
$response = $this->request('POST', '/api/auth/verify-email', ['token' => 'not-a-real-token']);
self::assertSame(400, $response->getStatusCode());
}
public function test_a_token_cannot_be_used_twice(): void
{
$this->request('POST', '/api/auth/register', ['email' => 'ada@example.com', 'password' => 'password123']);
$token = $this->tokenFromEmail();
self::assertSame(200, $this->request('POST', '/api/auth/verify-email', ['token' => $token])->getStatusCode());
$again = $this->request('POST', '/api/auth/verify-email', ['token' => $token]);
self::assertSame(400, $again->getStatusCode());
self::assertStringContainsString('already been used', $this->decode($again)['error']['message']);
}
public function test_an_expired_token_is_rejected(): void
{
$this->request('POST', '/api/auth/register', ['email' => 'ada@example.com', 'password' => 'password123']);
$token = $this->tokenFromEmail();
$this->db()->prepare('UPDATE email_verifications SET expires_at = :past WHERE token_hash = :hash')->execute([
'past' => gmdate('Y-m-d\TH:i:s\Z', time() - 60),
'hash' => hash('sha256', $token),
]);
$response = $this->request('POST', '/api/auth/verify-email', ['token' => $token]);
self::assertSame(400, $response->getStatusCode());
self::assertStringContainsString('expired', $this->decode($response)['error']['message']);
}
public function test_resend_is_throttled_immediately_after_registration(): void
{
$auth = $this->authHeader('ada@example.com');
$response = $this->request('POST', '/api/email/verification', null, $auth);
self::assertSame(429, $response->getStatusCode());
self::assertArrayHasKey('retry_after', $this->decode($response)['error']['details']);
}
public function test_resend_works_once_the_interval_has_passed(): void
{
$auth = $this->authHeader('ada@example.com');
$this->cooldownElapsed('ada@example.com');
$response = $this->request('POST', '/api/email/verification', null, $auth);
self::assertSame(202, $response->getStatusCode());
self::assertCount(2, $this->sentEmails());
self::assertSame('ada@example.com', $this->lastEmail()['to']);
}
public function test_resend_conflicts_when_already_verified(): void
{
$auth = $this->authHeader('ada@example.com');
$this->request('POST', '/api/auth/verify-email', ['token' => $this->tokenFromEmail()]);
$this->cooldownElapsed('ada@example.com');
$response = $this->request('POST', '/api/email/verification', null, $auth);
self::assertSame(409, $response->getStatusCode());
}
public function test_email_change_is_deferred_until_the_new_address_is_confirmed(): void
{
$auth = $this->authHeader('old@example.com');
$this->cooldownElapsed('old@example.com');
$change = $this->request('POST', '/api/email/change', [
'email' => 'New@example.com',
'password' => 'password123',
], $auth);
self::assertSame(202, $change->getStatusCode());
self::assertSame('new@example.com', $this->decode($change)['pending_email']);
self::assertSame('new@example.com', $this->lastEmail()['to']);
// Not applied yet.
$me = $this->decode($this->request('GET', '/api/me', null, $auth));
self::assertSame('old@example.com', $me['user']['email']);
self::assertSame('new@example.com', $me['user']['pending_email']);
// Open the link from the new inbox.
$verified = $this->request('POST', '/api/auth/verify-email', ['token' => $this->tokenFromEmail()]);
self::assertSame(200, $verified->getStatusCode());
$body = $this->decode($verified);
self::assertSame('new@example.com', $body['user']['email']);
self::assertTrue($body['user']['email_verified']);
self::assertNull($body['user']['pending_email']);
}
public function test_email_change_requires_the_current_password(): void
{
$auth = $this->authHeader('old@example.com');
$this->cooldownElapsed('old@example.com');
$response = $this->request('POST', '/api/email/change', [
'email' => 'new@example.com',
'password' => 'wrong-password',
], $auth);
self::assertSame(422, $response->getStatusCode());
self::assertArrayHasKey('password', $this->decode($response)['error']['details']);
}
public function test_email_change_rejects_an_address_already_in_use(): void
{
$this->authHeader('taken@example.com');
$auth = $this->authHeader('mine@example.com');
$this->cooldownElapsed('mine@example.com');
$response = $this->request('POST', '/api/email/change', [
'email' => 'taken@example.com',
'password' => 'password123',
], $auth);
self::assertSame(409, $response->getStatusCode());
}
public function test_email_change_rejects_the_current_address(): void
{
$auth = $this->authHeader('same@example.com');
$this->cooldownElapsed('same@example.com');
$response = $this->request('POST', '/api/email/change', [
'email' => 'same@example.com',
'password' => 'password123',
], $auth);
self::assertSame(422, $response->getStatusCode());
self::assertArrayHasKey('email', $this->decode($response)['error']['details']);
}
/** Push the user's last-sent timestamp far enough back to clear the throttle. */
private function cooldownElapsed(string $email): void
{
$this->db()
->prepare('UPDATE users SET verification_email_sent_at = :ts WHERE email = :email')
->execute(['ts' => gmdate('Y-m-d\TH:i:s\Z', time() - 120), 'email' => $email]);
}
}