feat: verify email addresses and recover forgotten passwords

Ekklesia could authenticate a person and, since Pass 1, send a
transactional email — but it had no way to establish that an address
belonged to whoever claimed it, and no way back in for someone who
forgot their password.

A verified address is now a precondition for holding a session. Better
Auth enforces that after the password check and before any session
exists, so an unverified sign-in returns 403 with no cookie. That is why
no "unverified principal" was needed: a correct password on an
unverified address carries exactly the authority of no password, and
/api/v1/principal is unchanged.

Better Auth keeps every token. Ekklesia adds no token table, no hashing,
and no expiry clock. It supplies a recipient, a subject, and two bodies,
and the mail provider supplies everything about SMTP.

Verification and reset links are rebuilt from a validated Dashboard
origin, taking only the token — never the URL Better Auth prebuilds from
a caller-supplied callbackURL — so no request can steer where a
recipient lands. Following a verification link mints no session, because
mail infrastructure dereferences links. Reset revokes that person's
other sessions and leaves managed devices alone.

Recovery answers identically for an address with an account, without
one, already verified, or undeliverable — including when SMTP is broken,
which is why the delivery adapter never throws.

The initial platform owner is the one exception: created already
verified by an operator command with no mail prerequisite, so a fresh
server can be signed in to before a relay exists. Migration 0007 extends
that to owners of installations that already exist. Public signup stays
disabled; verification is not a licence to self-register.

Co-Authored-By: Claude Opus 5 <[email protected]>

apps/api/package.json

@@ -31,8 +31,10 @@
     "@ekklesia/typescript-config": "workspace:*",
     "@types/node": "24.13.3",
     "@types/pg": "8.20.0",
+    "@types/smtp-server": "3.5.13",
     "better-auth": "1.6.23",
     "pg": "8.22.0",
+    "smtp-server": "3.19.3",
     "typescript": "7.0.2",
     "vitest": "4.1.10"
   },

apps/api/src/config.ts

@@ -79,8 +79,10 @@ export interface ApiRuntimeConfig {
    * The validated host outbound-email provider, or `undefined` when this installation has none
    * (ADR 0037).
    *
-   * `undefined` is a complete, valid deployment: nothing in the platform sends email yet, and a
-   * future feature that needs to discovers a structured `MAIL_NOT_CONFIGURED` rather than crashing.
+   * `undefined` is a valid deployment: the platform starts, every existing feature works, and the
+   * initial platform owner — created already verified by an operator command — can still sign in
+   * (ADR 0038). What it cannot do is verify a new account or deliver a password reset; each attempt
+   * reports a sanitized `MAIL_NOT_CONFIGURED` out of band rather than changing any HTTP response.
    * These values reach Core's provider and nowhere else — no module, browser bundle, diagnostic, or
    * API response ever sees the host or the password.
    */

apps/api/src/server.ts

@@ -13,7 +13,12 @@ import {
 import { createDashboardStore } from "@ekklesia/core/dashboard";
 import { createDeviceStore } from "@ekklesia/core/devices";
 import { type HostEnvironment, loadHostConfiguration } from "@ekklesia/core/host";
-import { createIdentityRuntime, type IdentityRateLimitOverride } from "@ekklesia/core/identity";
+import {
+  createIdentityNotifications,
+  createIdentityRuntime,
+  type IdentityNotificationReporter,
+  type IdentityRateLimitOverride,
+} from "@ekklesia/core/identity";
 import { createSmtpMailProvider, type MailProvider } from "@ekklesia/core/mail";
 import {
   createModuleConfigurationStore,
@@ -138,6 +143,15 @@ export interface StartApiOptions {
   /** Test-only escape hatch: never set by the executable entry point. See
    * `IdentityRateLimitOverride` for why production must leave this unset. */
   readonly rateLimitOverride?: IdentityRateLimitOverride;
+  /**
+   * Where a verification or reset message that could not be delivered is reported.
+   *
+   * Production composition leaves this unset and one fixed sanitized line is written. It exists as a
+   * seam because the *only* externally observable difference between "the relay is down" and "there
+   * is no such account" must be this report — every HTTP response is deliberately identical — so a
+   * test needs somewhere to observe the operational failure the user is never shown.
+   */
+  readonly reportNotificationFailure?: IdentityNotificationReporter;
   /** Test-only escape hatch: overrides the directory module discovery scans. Never set by the
    * executable entry point. See `prepareStartupModuleInventory`. */
   readonly modulesDirectoryOverride?: string;
@@ -430,6 +444,14 @@ export async function startApi(
     transport: config.databaseTransport,
   });
 
+  // Both host providers are constructed from validated configuration **before** anything that uses
+  // them, and neither touches the network while being built: an S3 client opens no connection and a
+  // Nodemailer transport opens no socket, so an unreachable relay or storage service can never stop
+  // the platform from booting (ADR 0030, ADR 0037). An installation with neither configured gets
+  // `undefined` for both, which is a complete, valid deployment.
+  const storageProvider = config.storage ? createS3StorageProvider(config.storage) : undefined;
+  const mailProvider = config.mail ? createSmtpMailProvider(config.mail) : undefined;
+
   let services: ModuleRuntimeServices;
   let runtime: ReturnType<typeof createIdentityRuntime>;
   let authorizationStore: ReturnType<typeof createAuthorizationStore>;
@@ -439,11 +461,22 @@ export async function startApi(
     runtime = createIdentityRuntime({
       config: config.identity,
       db: databaseHandle.identity,
+      // Identity's two outbound messages, composed here — the one place that knows both the
+      // validated identity configuration and the host's mail provider. Core's identity code learns
+      // a recipient, a subject, and two bodies and nothing whatsoever about SMTP (ADR 0038).
+      notifications: createIdentityNotifications({
+        authBaseUrl: config.identity.baseUrl,
+        dashboardOrigin: config.identity.dashboardOrigin,
+        mail: mailProvider,
+        ...(options.reportNotificationFailure ? { report: options.reportNotificationFailure } : {}),
+      }),
       ...(options.rateLimitOverride ? { rateLimitOverride: options.rateLimitOverride } : {}),
     });
     authorizationStore = createAuthorizationStore(databaseHandle.authorization);
     deviceStore = createDeviceStore(databaseHandle.devices);
   } catch (error) {
+    await safeCloseStorage(storageProvider);
+    await safeCloseMail(mailProvider);
     await safeCloseDatabase(databaseHandle);
     throw error;
   }
@@ -460,21 +493,6 @@ export async function startApi(
   // start, before a single module entrypoint is imported. A failure here fails startup rather than
   // falling back to "start everything": the platform cannot know what it was told, and starting a
   // module an administrator disabled is worse than not starting at all.
-  // The host's object-storage provider, constructed from validated configuration before any module
-  // runs — and **without touching the network**. Building the client opens no connection, so a
-  // storage outage can never stop the platform from booting; a bucket is ensured lazily on first
-  // use instead (ADR 0030). An installation with no storage configured gets `undefined` here, which
-  // is a complete, valid deployment.
-  const storageProvider = config.storage ? createS3StorageProvider(config.storage) : undefined;
-
-  // The host's outbound mail provider, constructed from validated configuration and — like the
-  // storage client above — **without touching the network**. Building a Nodemailer transport opens
-  // no socket and sends nothing, so an unreachable relay can never stop the platform from booting;
-  // the first connection happens when something actually sends (ADR 0037). Nothing sends yet: this
-  // exists so Pass 2 can hand it to Better Auth's verification and reset hooks. An installation with
-  // no SMTP configured gets `undefined`, which is a complete, valid deployment.
-  const mailProvider = config.mail ? createSmtpMailProvider(config.mail) : undefined;
-
   const moduleLifecycleStore = createModuleLifecycleStore(databaseHandle.moduleLifecycle);
   const moduleConfigurationStore = createModuleConfigurationStore(
     databaseHandle.moduleConfiguration,

apps/api/tests/api-http.integration.ts

@@ -224,6 +224,7 @@ async function applyCoreMigrations(url: string): Promise<void> {
       "core:0004_module_lifecycle_state",
       "core:0005_module_configuration",
       "core:0006_device_identity",
+      "core:0007_verified_bootstrap_owners",
     ]);
     expect(aggregate.migrations[0]?.checksum).toBe(
       "f8f2086ef06f7a6943e8ffc4350bb010b37aed04c0a72030d2b153c986b1325f",
@@ -522,6 +523,32 @@ function apiOrigin(running: RunningApi): string {
   return `http://127.0.0.1:${address.port}`;
 }
 
+/**
+ * Marks an address verified out of band, the same trusted step the initial-owner bootstrap performs
+ * (ADR 0038).
+ *
+ * Deliberately not a weakening of the policy: it is the test-harness equivalent of an operator with
+ * database credentials, used only so scenarios that are about something else are not obliged to run
+ * an SMTP server. That the policy itself is enforced — that an unverified account genuinely cannot
+ * sign in — is asserted separately, both in this file and in `email-verification.integration.ts`.
+ */
+async function markEmailVerified(origin: string, email: string): Promise<void> {
+  const url = databaseUrlByOrigin.get(origin);
+  if (!url) {
+    throw harnessError("No database is registered for that API origin.");
+  }
+  const client = new Client({ connectionString: url });
+  await client.connect();
+  try {
+    await client.query(
+      'update "ekklesia_core_user" set "email_verified" = true where lower("email") = $1',
+      [email.trim().toLowerCase()],
+    );
+  } finally {
+    await client.end().catch(() => undefined);
+  }
+}
+
 interface StartConfiguredApiOptions {
   readonly clientAddress?: ClientAddressConfigInput;
   /** Test-only narrowing of the platform's 30-second graceful HTTP drain deadline. */
@@ -537,6 +564,16 @@ interface StartConfiguredApiOptions {
   readonly rateLimitOverride?: { readonly max: number; readonly window: number } | undefined;
 }
 
+/**
+ * The database each running API in this suite is attached to, keyed by its bound origin.
+ *
+ * Needed because Phase 7C Pass 2 made a verified address a precondition for holding a session
+ * (ADR 0038), so `signUp` below has to mark the account verified before these scenarios — which are
+ * about cookies, CSRF, principals, sessions, and authorization, not about verification — can sign
+ * in. Verification itself has its own dedicated end-to-end suite.
+ */
+const databaseUrlByOrigin = new Map<string, string>();
+
 async function startConfiguredApi(
   url: string,
   options: StartConfiguredApiOptions = {},
@@ -571,7 +608,7 @@ async function startConfiguredApi(
     },
     { environment },
   );
-  return startApi(config, {
+  const running = await startApi(config, {
     ...("rateLimitOverride" in options
       ? { ...(options.rateLimitOverride ? { rateLimitOverride: options.rateLimitOverride } : {}) }
       : { rateLimitOverride: { max: 1000, window: 1 } }),
@@ -585,6 +622,8 @@ async function startConfiguredApi(
       ? {}
       : { drainTimeoutMsOverride: options.drainTimeoutMsOverride }),
   });
+  databaseUrlByOrigin.set(apiOrigin(running), url);
+  return running;
 }
 
 async function startMigratedApi(
@@ -763,6 +802,12 @@ async function signUp(
     headers: { "content-type": "application/json", origin: dashboardOrigin, ...headers },
     method: "POST",
   });
+  if (response.ok) {
+    // A verified address is a precondition for holding a session (ADR 0038). Sign-up itself always
+    // writes `emailVerified: false`, so these scenarios — none of which are about verification —
+    // complete that step out of band rather than standing up an SMTP server apiece.
+    await markEmailVerified(origin, email);
+  }
   return { body: (await response.clone().json()) as SignUpResult["body"], response };
 }
 

apps/api/tests/config.test.ts

@@ -28,6 +28,9 @@ describe("API runtime configuration", () => {
       host: "127.0.0.1",
       identity: {
         baseUrl: "https://identity.example.test",
+        // Defaults to the identity base URL: the Dashboard and the API share one origin unless a
+        // deployment separates them (ADR 0038).
+        dashboardOrigin: "https://identity.example.test",
         publicSignupEnabled: false,
         secret: validSecret,
         trustedOrigins: ["https://identity.example.test"],

apps/api/tests/email-verification.integration.ts

@@ -0,0 +1,816 @@
+import { createHmac, randomBytes } from "node:crypto";
+import { mkdtemp, rm } from "node:fs/promises";
+import type { AddressInfo } from "node:net";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  createBootstrapIdentityCreator,
+  createIdentityDrizzleDatabase,
+  type IdentityNotificationFailure,
+} from "@ekklesia/core/identity";
+import {
+  applyModuleMigrations,
+  createPostgresMigrationDatabase,
+  discoverAllMigrations,
+} from "@ekklesia/core/migrations";
+import { Client, type QueryResultRow } from "pg";
+import { SMTPServer } from "smtp-server";
+import { afterAll, afterEach, describe, expect, it } from "vitest";
+import { createApiRuntimeConfig } from "../src/config.js";
+import { type RunningApi, startApi } from "../src/server.js";
+
+/**
+ * Email verification and password recovery, end to end (ADR 0038).
+ *
+ * Everything here is real: a disposable PostgreSQL, the actual HTTP transport, the actual Better
+ * Auth endpoints, the actual SMTP provider, and an actual SMTP server accepting the message. The
+ * verification and reset links are **extracted from the delivered message** and then followed, which
+ * is the only way to prove the whole path rather than the pieces — a fake mail function would prove
+ * that a callback was invoked and nothing about whether the resulting link works.
+ *
+ * `smtp-server` runs in-process and is never given a live credential, so nothing here reaches the
+ * internet and no real email is ever sent.
+ *
+ * Public signup is disabled in every scenario, matching production. Accounts that are not the
+ * bootstrap owner are created through the same trusted server-side creator the bootstrap CLI uses,
+ * which is deliberately not reachable over HTTP.
+ */
+const integrationDatabaseUrlEnvironment = "EKKLESIA_MIGRATION_TEST_DATABASE_URL";
+const repositoryRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+const coreMigrationsDirectory = path.join(repositoryRoot, "core", "drizzle");
+const trackedDatabases = new Set<string>();
+let databaseCounter = 0;
+
+const dashboardOrigin = "http://dashboard.localhost:5173";
+const integrationSecret = "integration-test-secret-0123456789abcdefgh";
+const initialPassword = "correct horse battery staple";
+const replacementPassword = "an entirely different passphrase";
+
+class IntegrationHarnessError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "IntegrationHarnessError";
+    this.stack = `${this.name}: ${this.message}`;
+  }
+}
+
+function baseDatabaseUrl(): string {
+  const url = process.env[integrationDatabaseUrlEnvironment];
+  if (typeof url !== "string" || url.trim() === "") {
+    throw new IntegrationHarnessError("The integration database URL is not configured.");
+  }
+  return url;
+}
+
+function databaseUrl(name: string): string {
+  const url = new URL(baseDatabaseUrl());
+  url.pathname = `/${name}`;
+  return url.toString();
+}
+
+async function openAdministrativeClient(): Promise<Client> {
+  const client = new Client({ connectionString: baseDatabaseUrl() });
+  await client.connect();
+  return client;
+}
+
+async function safeQuery<T extends QueryResultRow>(
+  client: Client,
+  text: string,
+  values: readonly unknown[] = [],
+): Promise<T[]> {
+  try {
+    const result = await client.query<T>(text, [...values]);
+    return result.rows;
+  } catch {
+    // Never rethrows the driver error: it can carry SQL, a connection string, and a host.
+    throw new IntegrationHarnessError("An integration database statement failed.");
+  }
+}
+
+async function applyCoreMigrations(url: string): Promise<void> {
+  const emptyModules = await mkdtemp(path.join(tmpdir(), "ekklesia-verify-no-modules-"));
+  try {
+    const aggregate = await discoverAllMigrations({
+      coreMigrationsDirectory,
+      moduleDiscovery: {
+        moduleSdkVersion: "0.1.0",
+        modulesDirectory: emptyModules,
+        platformVersion: "0.1.0",
+      },
+    });
+    await applyModuleMigrations({ aggregate, database: createPostgresMigrationDatabase(url) });
+  } finally {
+    await rm(emptyModules, { force: true, recursive: true });
+  }
+}
+
+async function freshInstallation(label: string): Promise<string> {
+  databaseCounter += 1;
+  const name =
+    `ekk_verify_${label}_${databaseCounter}_${randomBytes(4).toString("hex")}`.toLowerCase();
+  const admin = await openAdministrativeClient();
+  try {
+    await safeQuery(admin, `create database "${name}"`);
+  } finally {
+    await admin.end().catch(() => undefined);
+  }
+  trackedDatabases.add(name);
+  const url = databaseUrl(name);
+  await applyCoreMigrations(url);
+  return url;
+}
+
+/** A delivered message, as the SMTP server actually received it. */
+interface DeliveredMessage {
+  readonly to: readonly string[];
+  readonly data: string;
+}
+
+interface MailHarness {
+  readonly port: number;
+  readonly delivered: DeliveredMessage[];
+  readonly close: () => Promise<void>;
+}
+
+const openResources: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  for (const close of openResources.splice(0).reverse()) {
+    await close().catch(() => undefined);
+  }
+});
+
+/**
+ * Picks a free port before the API is configured.
+ *
+ * The identity base URL is what the emailed link is built from, so it has to be known *before*
+ * `startApi` binds. Without this the test could only assert the link's shape and would have to
+ * rewrite its host before following it — which is exactly the part worth proving. Reserving and
+ * releasing a port leaves a theoretical race, but nothing else on the loopback interface is
+ * competing for ephemeral ports inside this suite.
+ */
+async function reservePort(): Promise<number> {
+  const { createServer } = await import("node:net");
+  const server = createServer();
+  const port = await new Promise<number>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address() as AddressInfo;
+      resolve(address.port);
+    });
+  });
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  return port;
+}
+
+async function startMailServer(): Promise<MailHarness> {
+  const delivered: DeliveredMessage[] = [];
+  const server = new SMTPServer({
+    authOptional: true,
+    disabledCommands: ["STARTTLS"],
+    onData(stream, session, callback) {
+      let data = "";
+      stream.on("data", (chunk: Buffer) => {
+        data += chunk.toString("utf8");
+      });
+      stream.on("end", () => {
+        delivered.push({
+          data,
+          to: session.envelope.rcptTo.map((recipient) => recipient.address),
+        });
+        callback();
+      });
+    },
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+  const address = server.server.address() as AddressInfo;
+  const harness: MailHarness = {
+    close: async () =>
+      await new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      }),
+    delivered,
+    port: address.port,
+  };
+  openResources.push(harness.close);
+  return harness;
+}
+
+interface Installation {
+  readonly url: string;
+  readonly api: RunningApi;
+  readonly origin: string;
+  readonly mail: MailHarness | undefined;
+  readonly notificationFailures: IdentityNotificationFailure[];
+  readonly createIdentity: (input: {
+    readonly email: string;
+    readonly password: string;
+    readonly name: string;
+  }) => Promise<void>;
+}
+
+/**
+ * A migrated installation with the API running, optionally with a working SMTP relay.
+ *
+ * `plaintext` SMTP and an `http` Dashboard origin are only acceptable because this is explicitly the
+ * development environment; production configuration refuses both, which `identity-config` and
+ * `mail-contract` assert separately.
+ */
+async function installation(
+  label: string,
+  options: { readonly mail?: boolean } = {},
+): Promise<Installation> {
+  const url = await freshInstallation(label);
+  const mail = options.mail === false ? undefined : await startMailServer();
+  const notificationFailures: IdentityNotificationFailure[] = [];
+  const identity = createIdentityDrizzleDatabase(url, {});
+  openResources.push(async () => {
+    await identity.close().catch(() => undefined);
+  });
+
+  const apiPort = await reservePort();
+  const identityBaseUrl = `http://127.0.0.1:${apiPort}`;
+  const config = createApiRuntimeConfig(
+    {
+      databaseUrl: url,
+      host: "127.0.0.1",
+      identity: {
+        baseUrl: identityBaseUrl,
+        dashboardOrigin,
+        publicSignupEnabled: false,
+        secret: integrationSecret,
+        trustedOrigins: [dashboardOrigin],
+      },
+      ...(mail
+        ? {
+            mail: {
+              fromAddress: "[email protected]",
+              fromName: "Ekklesia",
+              host: "127.0.0.1",
+              port: String(mail.port),
+              security: "plaintext",
+            },
+          }
+        : {}),
+      port: apiPort,
+    },
+    { environment: "development" },
+  );
+  const api = await startApi(config, {
+    rateLimitOverride: { max: 1000, window: 1 },
+    reportNotificationFailure: (failure) => notificationFailures.push(failure),
+  });
+  openResources.push(async () => {
+    await api.shutdown().catch(() => undefined);
+  });
+
+  const address = api.server.address();
+  if (!address || typeof address !== "object" || address.port !== apiPort) {
+    throw new IntegrationHarnessError("The API integration server did not bind the reserved port.");
+  }
+  return {
+    api,
+    createIdentity: createBootstrapIdentityCreator(identity.db),
+    mail,
+    notificationFailures,
+    origin: identityBaseUrl,
+    url,
+  };
+}
+
+async function post(
+  origin: string,
+  path: string,
+  body: unknown,
+  headers: Readonly<Record<string, string>> = {},
+): Promise<Response> {
+  return await fetch(`${origin}${path}`, {
+    body: JSON.stringify(body),
+    headers: { "content-type": "application/json", origin: dashboardOrigin, ...headers },
+    method: "POST",
+    redirect: "manual",
+  });
+}
+
+function firstCookiePair(response: Response): string | undefined {
+  const setCookie = response.headers.get("set-cookie");
+  return setCookie === null ? undefined : setCookie.split(",")[0]?.split(";")[0]?.trim();
+}
+
+async function signIn(
+  origin: string,
+  email: string,
+  password: string,
+): Promise<{ readonly response: Response; readonly cookiePair: string | undefined }> {
+  const response = await post(origin, "/api/auth/sign-in/email", { email, password });
+  return { cookiePair: firstCookiePair(response), response };
+}
+
+async function principalKind(origin: string, cookiePair: string | undefined): Promise<string> {
+  const response = await fetch(`${origin}/api/v1/principal`, {
+    headers: cookiePair ? { cookie: cookiePair } : {},
+  });
+  const body = (await response.json()) as { readonly kind?: unknown };
+  return String(body.kind);
+}
+
+/**
+ * The one place a test reads a token, and only ever out of a message this suite's own SMTP server
+ * received. Nothing in the platform exposes one.
+ *
+ * Quoted-printable soft line breaks are undone first: a URL longer than 76 characters is split by
+ * the encoder, and reassembling it here is what makes the extracted link the one a mail client would
+ * actually resolve.
+ */
+function extractLink(message: DeliveredMessage, contains: string): URL {
+  const unwrapped = message.data.replaceAll("=\r\n", "").replaceAll("=\n", "");
+  const decoded = unwrapped.replaceAll(/=([0-9A-F]{2})/gu, (_match, hex: string) =>
+    String.fromCharCode(Number.parseInt(hex, 16)),
+  );
+  const match = decoded.match(/https?:\/\/[^\s"<>]+/gu)?.find((url) => url.includes(contains));
+  if (!match) {
+    throw new IntegrationHarnessError(`No ${contains} link was delivered.`);
+  }
+  return new URL(match);
+}
+
+function lastMessage(mail: MailHarness): DeliveredMessage {
+  const message = mail.delivered.at(-1);
+  if (!message) {
+    throw new IntegrationHarnessError("No message was delivered.");
+  }
+  return message;
+}
+
+async function emailVerifiedFlag(url: string, email: string): Promise<boolean | undefined> {
+  const client = new Client({ connectionString: url });
+  await client.connect();
+  try {
+    const rows = await safeQuery<{ email_verified: boolean }>(
+      client,
+      'select "email_verified" from "ekklesia_core_user" where lower("email") = $1',
+      [email.toLowerCase()],
+    );
+    return rows[0]?.email_verified;
+  } finally {
+    await client.end().catch(() => undefined);
+  }
+}
+
+/**
+ * An account that has completed the real verification round trip.
+ *
+ * Recovery is only meaningful for a verified account, and building one through the actual flow —
+ * rather than by writing `email_verified` directly — keeps every recovery test standing on a
+ * verification path that genuinely works.
+ */
+async function verifiedAccountFor(install: Installation, email: string): Promise<void> {
+  await install.createIdentity({ email, name: "Member", password: initialPassword });
+  await signIn(install.origin, email, initialPassword);
+  const link = extractLink(lastMessage(install.mail as MailHarness), "/verify-email");
+  await fetch(link, { redirect: "manual" });
+  (install.mail as MailHarness).delivered.length = 0;
+}
+
+afterAll(async () => {
+  const admin = await openAdministrativeClient().catch(() => undefined);
+  if (!admin) {
+    return;
+  }
+  try {
+    for (const name of trackedDatabases) {
+      await safeQuery(admin, `drop database if exists "${name}" with (force)`).catch(
+        () => undefined,
+      );
+    }
+  } finally {
+    await admin.end().catch(() => undefined);
+  }
+});
+
+/**
+ * Forges a verification token that is structurally valid but already expired.
+ *
+ * Better Auth's verification token is a plain HS256 JWS over the auth secret (`signJWT`, pinned
+ * release) — not a database row — so an expired one can be produced here from the same secret this
+ * suite configured, with no library internals and no waiting an hour. This is the only place any
+ * test constructs a token rather than reading one out of a delivered message.
+ */
+function forgeExpiredVerificationToken(email: string): string {
+  const encode = (value: object): string =>
+    Buffer.from(JSON.stringify(value)).toString("base64url");
+  const issued = Math.floor(Date.now() / 1000) - 7200;
+  const signingInput = `${encode({ alg: "HS256", typ: "JWT" })}.${encode({
+    email: email.toLowerCase(),
+    exp: issued + 3600,
+    iat: issued,
+  })}`;
+  const signature = createHmac("sha256", integrationSecret)
+    .update(signingInput)
+    .digest("base64url");
+  return `${signingInput}.${signature}`;
+}
+
+describe("email verification, end to end", () => {
+  it("takes a new human account from unverified to signed in through a real emailed link", async () => {
+    const install = await installation("flow");
+    const email = "[email protected]";
+    await install.createIdentity({ email, name: "Member", password: initialPassword });
+
+    // 1. Unverified. A correct password does not produce a session — the identity system refuses
+    //    before creating one, so there is no half-authenticated state anywhere (ADR 0038).
+    expect(await emailVerifiedFlag(install.url, email)).toBe(false);
+    const refused = await signIn(install.origin, email, initialPassword);
+    expect(refused.response.status).toBe(403);
+    expect(await refused.response.clone().json()).toMatchObject({ code: "EMAIL_NOT_VERIFIED" });
+    expect(refused.cookiePair).toBeUndefined();
+    expect(await principalKind(install.origin, refused.cookiePair)).toBe("anonymous");
+
+    // 2. That attempt delivered a verification message through the real SMTP provider.
+    const mail = install.mail as MailHarness;
+    expect(mail.delivered).toHaveLength(1);
+    expect(lastMessage(mail).to).toEqual([email]);
+    expect(lastMessage(mail).data).toContain("Verify your Ekklesia email address");
+
+    // 3. Follow the link exactly as it was delivered. Nothing rewrites it.
+    const link = extractLink(lastMessage(mail), "/verify-email");
+    expect(link.origin).toBe(install.origin);
+    const verified = await fetch(link, { redirect: "manual" });
+
+    // 4. Better Auth redirects to the Dashboard landing this deployment configured — never to the
+    //    API origin, and never to anything a request supplied.
+    expect(verified.status).toBe(302);
+    const landing = new URL(verified.headers.get("location") ?? "");
+    expect(landing.origin).toBe(dashboardOrigin);
+    expect(landing.searchParams.get("ekklesia_auth")).toBe("verify-email");
+    expect(landing.searchParams.get("error")).toBeNull();
+    // No session was minted by following an emailed link.
+    expect(verified.headers.get("set-cookie")).toBeNull();
+    expect(await emailVerifiedFlag(install.url, email)).toBe(true);
+
+    // 5. The same credentials now work, and the principal is a fully authenticated human.
+    const accepted = await signIn(install.origin, email, initialPassword);
+    expect(accepted.response.status).toBe(200);
+    expect(accepted.cookiePair).toBeDefined();
+    expect(await principalKind(install.origin, accepted.cookiePair)).toBe("authenticated");
+  });
+
+  it("refuses a malformed token and an expired token, each with its own reason", async () => {
+    const install = await installation("bad-token");
+    const email = "[email protected]";
+    await install.createIdentity({ email, name: "Expired", password: initialPassword });
+    const callback = encodeURIComponent(`${dashboardOrigin}/?ekklesia_auth=verify-email`);
+
+    for (const [token, reason] of [
+      ["not-a-jwt", "INVALID_TOKEN"],
+      [forgeExpiredVerificationToken(email), "TOKEN_EXPIRED"],
+    ] as const) {
+      const response = await fetch(
+        `${install.origin}/api/auth/verify-email?token=${encodeURIComponent(token)}&callbackURL=${callback}`,
+        { redirect: "manual" },
+      );
+      expect(response.status).toBe(302);
+      const landing = new URL(response.headers.get("location") ?? "");
+      // The failure still lands on the host's own screen rather than a raw JSON error page.
+      expect(landing.origin).toBe(dashboardOrigin);
+      expect(landing.searchParams.get("error")).toBe(reason);
+      expect(await emailVerifiedFlag(install.url, email)).toBe(false);
+    }
+  });
+
+  it("is idempotent when a link is followed twice, because the token is a signed claim", async () => {
+    const install = await installation("replay");
+    const email = "[email protected]";
+    await install.createIdentity({ email, name: "Replay", password: initialPassword });
+    await signIn(install.origin, email, initialPassword);
+    const link = extractLink(lastMessage(install.mail as MailHarness), "/verify-email");
+
+    const first = await fetch(link, { redirect: "manual" });
+    const second = await fetch(link, { redirect: "manual" });
+
+    // Documented honestly (ADR 0038): the verification token is a signed JWT, not a consumed
+    // database row, so it is **not** single-use — it is valid until it expires. Replaying it is a
+    // no-op on an already-verified address and mints no session, which is what makes that safe.
+    // Mail scanners and prefetchers dereference links, so idempotence is a requirement here.
+    expect(first.status).toBe(302);
+    expect(second.status).toBe(302);
+    expect(second.headers.get("set-cookie")).toBeNull();
+    expect(await emailVerifiedFlag(install.url, email)).toBe(true);
+  });
+
+  it("resends on request without revealing whether the address has an account", async () => {
+    const install = await installation("resend");
+    const email = "[email protected]";
+    await install.createIdentity({ email, name: "Resend", password: initialPassword });
+    const mail = install.mail as MailHarness;
+
+    const known = await post(install.origin, "/api/auth/send-verification-email", { email });
+    const unknown = await post(install.origin, "/api/auth/send-verification-email", {
+      email: "[email protected]",
+    });
+    const verifiedAlready = await post(install.origin, "/api/auth/send-verification-email", {
+      email: "[email protected]",
+    });
+
+    // Identical answers. The only difference anywhere is that a message was delivered, which the
+    // requester cannot observe.
+    expect(known.status).toBe(200);
+    expect(unknown.status).toBe(200);
+    expect(verifiedAlready.status).toBe(200);
+    expect(await known.clone().json()).toEqual(await unknown.clone().json());
+    expect(mail.delivered.map((message) => message.to)).toEqual([[email]]);
+  });
+});
+
+describe("password recovery, end to end", () => {
+  it("replaces the password through a real emailed link and invalidates the old one", async () => {
+    const install = await installation("reset");
+    const email = "[email protected]";
+    await verifiedAccountFor(install, email);
+    const mail = install.mail as MailHarness;
+
+    const requested = await post(install.origin, "/api/auth/request-password-reset", { email });
+    expect(requested.status).toBe(200);
+    expect(mail.delivered).toHaveLength(1);
+    expect(lastMessage(mail).to).toEqual([email]);
+    expect(lastMessage(mail).data).toContain("Reset your Ekklesia password");
+
+    // Follow the emailed link. Better Auth validates the token and hands the browser on to the
+    // Dashboard landing with it attached — which is where the host's reset form picks it up.
+    const link = extractLink(lastMessage(mail), "/reset-password/");
+    expect(link.origin).toBe(install.origin);
+    const handoff = await fetch(link, { redirect: "manual" });
+    expect(handoff.status).toBe(302);
+    const landing = new URL(handoff.headers.get("location") ?? "");
+    expect(landing.origin).toBe(dashboardOrigin);
+    expect(landing.searchParams.get("ekklesia_auth")).toBe("reset-password");
+    const token = landing.searchParams.get("token") ?? "";
+    expect(token).not.toBe("");
+
+    const completed = await post(install.origin, "/api/auth/reset-password", {
+      newPassword: replacementPassword,
+      token,
+    });
+    expect(completed.status).toBe(200);
+
+    const oldCredential = await signIn(install.origin, email, initialPassword);
+    expect(oldCredential.response.status).toBe(401);
+    const newCredential = await signIn(install.origin, email, replacementPassword);
+    expect(newCredential.response.status).toBe(200);
+    expect(await principalKind(install.origin, newCredential.cookiePair)).toBe("authenticated");
+  });
+
+  it("consumes the reset token, so a captured link cannot be replayed", async () => {
+    const install = await installation("reset-replay");
+    const email = "[email protected]";
+    await verifiedAccountFor(install, email);
+    await post(install.origin, "/api/auth/request-password-reset", { email });
+    const link = extractLink(lastMessage(install.mail as MailHarness), "/reset-password/");
+    const handoff = await fetch(link, { redirect: "manual" });
+    const token = new URL(handoff.headers.get("location") ?? "").searchParams.get("token") ?? "";
+
+    const first = await post(install.origin, "/api/auth/reset-password", {
+      newPassword: replacementPassword,
+      token,
+    });
+    const second = await post(install.origin, "/api/auth/reset-password", {
+      newPassword: "yet another different passphrase",
+      token,
+    });
+
+    // Unlike the verification token, this one is a database row Better Auth consumes.
+    expect(first.status).toBe(200);
+    expect(second.status).toBe(400);
+    expect(await second.json()).toMatchObject({ code: "INVALID_TOKEN" });
+    expect((await signIn(install.origin, email, replacementPassword)).response.status).toBe(200);
+  });
+
+  it("signs out every existing session for that account", async () => {
+    const install = await installation("reset-sessions");
+    const email = "[email protected]";
+    await verifiedAccountFor(install, email);
+    const before = await signIn(install.origin, email, initialPassword);
+    expect(await principalKind(install.origin, before.cookiePair)).toBe("authenticated");
+
+    await post(install.origin, "/api/auth/request-password-reset", { email });
+    const link = extractLink(lastMessage(install.mail as MailHarness), "/reset-password/");
+    const handoff = await fetch(link, { redirect: "manual" });
+    const token = new URL(handoff.headers.get("location") ?? "").searchParams.get("token") ?? "";
+    await post(install.origin, "/api/auth/reset-password", {
+      newPassword: replacementPassword,
+      token,
+    });
+
+    // The whole point of recovery is that it works when the credential is already compromised, so
+    // an attacker's existing session must not survive it (`revokeSessionsOnPasswordReset`).
+    expect(await principalKind(install.origin, before.cookiePair)).toBe("anonymous");
+  });
+
+  it("enforces the identity system's own password policy, with no reset-specific rule", async () => {
+    const install = await installation("reset-policy");
+    const email = "[email protected]";
+    await verifiedAccountFor(install, email);
+    await post(install.origin, "/api/auth/request-password-reset", { email });
+    const link = extractLink(lastMessage(install.mail as MailHarness), "/reset-password/");
+    const handoff = await fetch(link, { redirect: "manual" });
+    const token = new URL(handoff.headers.get("location") ?? "").searchParams.get("token") ?? "";
+
+    const tooShort = await post(install.origin, "/api/auth/reset-password", {
+      newPassword: "short",
+      token,
+    });
+
+    expect(tooShort.status).toBe(400);
+    expect(await tooShort.json()).toMatchObject({ code: "PASSWORD_TOO_SHORT" });
+    // The old password still works: a rejected reset changes nothing.
+    expect((await signIn(install.origin, email, initialPassword)).response.status).toBe(200);
+  });
+
+  it("answers a request for an address with no account exactly as it answers a real one", async () => {
+    const install = await installation("enumeration");
+    const email = "[email protected]";
+    await verifiedAccountFor(install, email);
+    const mail = install.mail as MailHarness;
+
+    const known = await post(install.origin, "/api/auth/request-password-reset", { email });
+    const unknown = await post(install.origin, "/api/auth/request-password-reset", {
+      email: "[email protected]",
+    });
+
+    expect(known.status).toBe(unknown.status);
+    expect(await known.clone().json()).toEqual(await unknown.clone().json());
+    expect(JSON.stringify(await unknown.json())).not.toContain("stranger");
+    // Only the real account received anything.
+    expect(mail.delivered.map((message) => message.to)).toEqual([[email]]);
+  });
+});
+
+describe("recovery when the installation has no outbound email", () => {
+  it("answers identically and records the operational failure out of band", async () => {
+    const install = await installation("no-mail", { mail: false });
+    const email = "[email protected]";
+    await install.createIdentity({ email, name: "No Mail", password: initialPassword });
+
+    const reset = await post(install.origin, "/api/auth/request-password-reset", { email });
+    const resend = await post(install.origin, "/api/auth/send-verification-email", { email });
+
+    // The user-facing answer must not change: "we could not send it" for a real address and a
+    // generic success for an unknown one is an enumeration oracle that appears when SMTP breaks.
+    expect(reset.status).toBe(200);
+    expect(resend.status).toBe(200);
+    // The operator still learns about it, with a sanitized code and no address or token.
+    expect(install.notificationFailures).toEqual([
+      { kind: "password-reset", reason: "MAIL_NOT_CONFIGURED" },
+      { kind: "email-verification", reason: "MAIL_NOT_CONFIGURED" },
+    ]);
+    expect(JSON.stringify(install.notificationFailures)).not.toContain("[email protected]");
+  });
+
+  it("still starts, serves the API, and refuses an unverified sign-in", async () => {
+    const install = await installation("no-mail-runs", { mail: false });
+    const email = "[email protected]";
+    await install.createIdentity({ email, name: "No Mail", password: initialPassword });
+
+    // Absent mail is a complete deployment (ADR 0037) and does **not** relax the verification
+    // policy — which is exactly why the initial owner is created already verified.
+    expect((await fetch(`${install.origin}/api/v1/principal`)).status).toBe(200);
+    expect((await signIn(install.origin, email, initialPassword)).response.status).toBe(403);
+  });
+});
+
+describe("recovery cannot be turned into a redirect or an account factory", () => {
+  it("refuses an attacker-supplied reset destination", async () => {
+    const install = await installation("redirect");
+    const email = "[email protected]";
+    await install.createIdentity({ email, name: "Redirect", password: initialPassword });
+
+    const external = await post(install.origin, "/api/auth/request-password-reset", {
+      email,
+      redirectTo: "https://evil.example.test/steal",
+    });
+
+    expect(external.status).toBe(403);
+    expect(await external.json()).toMatchObject({ code: "INVALID_REDIRECT_URL" });
+    expect((install.mail as MailHarness).delivered).toHaveLength(0);
+  });
+
+  it("refuses an attacker-supplied verification destination", async () => {
+    const install = await installation("redirect-verify");
+
+    for (const callbackURL of [
+      "https://evil.example.test",
+      "//evil.example.test",
+      "/\\evil.example.test",
+      "javascript:alert(1)",
+    ]) {
+      const response = await fetch(
+        `${install.origin}/api/auth/verify-email?token=x&callbackURL=${encodeURIComponent(callbackURL)}`,
+        { redirect: "manual" },
+      );
+      expect(response.status).toBe(403);
+      expect(response.headers.get("location")).toBeNull();
+    }
+  });
+
+  it("ignores a supplied destination even where one is accepted, because the link is rebuilt", async () => {
+    const install = await installation("redirect-ignored");
+    const email = "[email protected]";
+    await verifiedAccountFor(install, email);
+
+    // A *trusted* origin passes Better Auth's own check, so this is the case where the emailed
+    // link's destination would otherwise be caller-chosen. It is not: the message is built from
+    // configuration and the supplied value never reaches it.
+    await post(install.origin, "/api/auth/request-password-reset", {
+      email,
+      redirectTo: `${dashboardOrigin}/somewhere-else`,
+    });
+
+    const link = extractLink(lastMessage(install.mail as MailHarness), "/reset-password/");
+    const callback = new URL(link.searchParams.get("callbackURL") ?? "");
+    expect(callback.origin).toBe(dashboardOrigin);
+    expect(callback.pathname).toBe("/");
+    expect(callback.searchParams.get("ekklesia_auth")).toBe("reset-password");
+    expect(link.href).not.toContain("somewhere-else");
+  });
+
+  it("keeps public signup disabled now that verification exists", async () => {
+    const install = await installation("signup");
+
+    const response = await post(install.origin, "/api/auth/sign-up/email", {
+      email: "[email protected]",
+      name: "Intruder",
+      password: initialPassword,
+    });
+
+    // Email verification is not a licence to self-register. Future accounts arrive through
+    // deliberate administration, which this pass does not build.
+    expect(response.status).toBe(400);
+    expect(await response.json()).toMatchObject({ code: "EMAIL_PASSWORD_SIGN_UP_DISABLED" });
+    expect(await emailVerifiedFlag(install.url, "[email protected]")).toBeUndefined();
+  });
+});
+
+describe("managed devices are untouched by human email identity", () => {
+  it("leaves a paired device intact across a human password reset", async () => {
+    const install = await installation("devices");
+    const email = "[email protected]";
+    await verifiedAccountFor(install, email);
+
+    // A device is a row with a credential digest and no email, no password, and no verification
+    // state (ADR 0036). It is inserted directly here because pairing it through HTTP would prove
+    // something this test is not about.
+    const client = new Client({ connectionString: install.url });
+    await client.connect();
+    try {
+      await safeQuery(
+        client,
+        'insert into "ekklesia_core_device" ("name", "credential_hash") values ($1, $2)',
+        ["Sanctuary display", "a".repeat(64)],
+      );
+
+      await post(install.origin, "/api/auth/request-password-reset", { email });
+      const link = extractLink(lastMessage(install.mail as MailHarness), "/reset-password/");
+      const handoff = await fetch(link, { redirect: "manual" });
+      const token = new URL(handoff.headers.get("location") ?? "").searchParams.get("token") ?? "";
+      await post(install.origin, "/api/auth/reset-password", {
+        newPassword: replacementPassword,
+        token,
+      });
+
+      const devices = await safeQuery<{ credential_hash: string; revoked_at: Date | null }>(
+        client,
+        'select "credential_hash", "revoked_at" from "ekklesia_core_device"',
+      );
+      expect(devices).toEqual([{ credential_hash: "a".repeat(64), revoked_at: null }]);
+
+      // The device table has no email or verification concept for a human flow to reach.
+      const columns = await safeQuery<{ column_name: string }>(
+        client,
+        "select column_name from information_schema.columns where table_name = 'ekklesia_core_device'",
+      );
+      const names = columns.map((column) => column.column_name).join(" ");
+      expect(names).not.toContain("email");
+      expect(names).not.toContain("verified");
+      expect(names).not.toContain("password");
+    } finally {
+      await client.end().catch(() => undefined);
+    }
+  });
+
+  it("sends a device no mail, because a device has no address to send to", async () => {
+    const install = await installation("devices-mail");
+
+    await post(install.origin, "/api/auth/request-password-reset", {
+      email: "[email protected]",
+    });
+
+    // Nothing about device identity participates in either flow.
+    expect((install.mail as MailHarness).delivered).toHaveLength(0);
+    expect(install.notificationFailures).toEqual([]);
+  });
+});

apps/api/tests/initial-owner.integration.ts

@@ -170,9 +170,13 @@ function bootstrapAgainst(url: string): BootstrapHandles {
   };
 }
 
-/** The production posture: public signup disabled, exactly as a real deployment must run. */
-async function startApiWithoutSignup(url: string): Promise<RunningApi> {
-  const config = createApiRuntimeConfig(
+/**
+ * The production posture: public signup disabled, exactly as a real deployment must run — and, just
+ * as deliberately, **no outbound email configured at all**. A fresh installation has no relay yet,
+ * which is the whole reason the initial owner is created already verified (ADR 0038).
+ */
+function ownerApiConfig(url: string): ReturnType<typeof createApiRuntimeConfig> {
+  return createApiRuntimeConfig(
     {
       databaseUrl: url,
       host: "127.0.0.1",
@@ -186,7 +190,10 @@ async function startApiWithoutSignup(url: string): Promise<RunningApi> {
     },
     { environment: "development" },
   );
-  return startApi(config, { rateLimitOverride: { max: 1000, window: 1 } });
+}
+
+async function startApiWithoutSignup(url: string): Promise<RunningApi> {
+  return startApi(ownerApiConfig(url), { rateLimitOverride: { max: 1000, window: 1 } });
 }
 
 function apiOrigin(running: RunningApi): string {
@@ -270,6 +277,22 @@ async function countRows(url: string, table: string): Promise<number> {
   }
 }
 
+/** Better Auth's own `emailVerified` column — the same value its `/verify-email` endpoint writes. */
+async function emailVerifiedFlag(url: string, email: string): Promise<boolean | undefined> {
+  const client = new Client({ connectionString: url });
+  await client.connect();
+  try {
+    const rows = await safeQuery<{ email_verified: boolean }>(
+      client,
+      'select "email_verified" from "ekklesia_core_user" where lower("email") = $1',
+      [email.trim().toLowerCase()],
+    );
+    return rows[0]?.email_verified;
+  } finally {
+    await client.end().catch(() => undefined);
+  }
+}
+
 afterAll(async () => {
   const admin = await openAdministrativeClient().catch(() => undefined);
   if (!admin) {
@@ -685,3 +708,141 @@ describe.sequential("initial platform-owner bootstrap", () => {
     });
   });
 });
+
+describe.sequential("initial platform-owner bootstrap and email verification", () => {
+  /**
+   * The trusted-bootstrap verification exception (ADR 0038).
+   *
+   * A verified address became a precondition for holding a session in Phase 7C Pass 2. The initial
+   * owner is created on a freshly provisioned server, by an operator holding the database
+   * credentials, at a moment when SMTP may not exist — so requiring an email round trip here would
+   * produce a working installation nobody can ever sign in to. These scenarios exist to prove that
+   * the exception is real, that it is narrow, and that mail remains genuinely absent throughout.
+   */
+  it("creates the owner already verified, proven in the database and in the browser", async () => {
+    const url = await freshInstallation("verifiedowner");
+    const email = `owner-${randomBytes(4).toString("hex")}@example.test`;
+
+    const bootstrap = bootstrapAgainst(url);
+    try {
+      await bootstrap.run(email);
+    } finally {
+      await bootstrap.close();
+    }
+
+    // Database state: the exact column Better Auth's own verification endpoint writes, so the row
+    // is indistinguishable from one that verified normally.
+    expect(await emailVerifiedFlag(url, email)).toBe(true);
+
+    // ...and the browser-facing consequence, which is the only thing that actually matters.
+    const api = await startApiWithoutSignup(url);
+    try {
+      const origin = apiOrigin(api);
+      const session = await signIn(origin, email, ownerPassword);
+      expect(session.response.status).toBe(200);
+      expect(session.cookiePair).toBeDefined();
+    } finally {
+      await api.shutdown();
+    }
+  });
+
+  it("needs no outbound email configured, at bootstrap or at sign-in", async () => {
+    const url = await freshInstallation("nomailowner");
+    const email = `owner-${randomBytes(4).toString("hex")}@example.test`;
+
+    const bootstrap = bootstrapAgainst(url);
+    try {
+      // No SMTP host, no relay, no network: `createBootstrapIdentityCreator` constructs its own
+      // Better Auth instance with no `emailVerification` configuration at all.
+      await bootstrap.run(email);
+    } finally {
+      await bootstrap.close();
+    }
+
+    const api = await startApiWithoutSignup(url);
+    try {
+      // The API this suite starts configures no mail either, so nothing in this scenario could have
+      // sent or received a message.
+      expect(ownerApiConfig(url).mail).toBeUndefined();
+      expect((await signIn(apiOrigin(api), email, ownerPassword)).response.status).toBe(200);
+    } finally {
+      await api.shutdown();
+    }
+  });
+
+  it("marks an adopted identity verified too, so bootstrap never yields an owner who cannot sign in", async () => {
+    const url = await freshInstallation("adoptverified");
+    const email = `owner-${randomBytes(4).toString("hex")}@example.test`;
+
+    // An identity that exists before bootstrap runs — created here through the same trusted creator,
+    // which always writes `emailVerified: false`.
+    const first = bootstrapAgainst(url);
+    try {
+      await first.run(email);
+    } finally {
+      await first.close();
+    }
+    const client = new Client({ connectionString: url });
+    await client.connect();
+    try {
+      await safeQuery(client, 'update "ekklesia_core_user" set "email_verified" = false');
+      await safeQuery(client, 'delete from "ekklesia_core_platform_owner_bootstrap"');
+      await safeQuery(client, 'delete from "ekklesia_core_platform_owner"');
+    } finally {
+      await client.end().catch(() => undefined);
+    }
+    expect(await emailVerifiedFlag(url, email)).toBe(false);
+
+    const second = bootstrapAgainst(url);
+    let adopted: Awaited<ReturnType<typeof createInitialPlatformOwner>>;
+    try {
+      adopted = await second.run(email);
+    } finally {
+      await second.close();
+    }
+
+    expect(adopted.identity).toBe("adopted");
+    expect(await emailVerifiedFlag(url, email)).toBe(true);
+  });
+
+  it("verifies only the owner, leaving every other account subject to the normal policy", async () => {
+    const url = await freshInstallation("narrowexception");
+    const ownerEmail = `owner-${randomBytes(4).toString("hex")}@example.test`;
+    const otherEmail = `member-${randomBytes(4).toString("hex")}@example.test`;
+
+    const bootstrap = bootstrapAgainst(url);
+    try {
+      await bootstrap.run(ownerEmail);
+      // A second identity created through the identical trusted creator, but never bootstrapped.
+      const identity = createIdentityDrizzleDatabase(url, {});
+      try {
+        await createBootstrapIdentityCreator(identity.db)({
+          email: otherEmail,
+          name: "Ordinary Member",
+          password: ownerPassword,
+        });
+      } finally {
+        await identity.close().catch(() => undefined);
+      }
+    } finally {
+      await bootstrap.close();
+    }
+
+    expect(await emailVerifiedFlag(url, ownerEmail)).toBe(true);
+    expect(await emailVerifiedFlag(url, otherEmail)).toBe(false);
+
+    const api = await startApiWithoutSignup(url);
+    try {
+      const origin = apiOrigin(api);
+      expect((await signIn(origin, ownerEmail, ownerPassword)).response.status).toBe(200);
+      // The exception did not widen: an ordinary account still has to verify, and on this
+      // mail-less installation it simply cannot sign in yet.
+      const refused = await signIn(origin, otherEmail, ownerPassword);
+      expect(refused.response.status).toBe(403);
+      expect(await refused.response.json()).toMatchObject({ code: "EMAIL_NOT_VERIFIED" });
+      expect(refused.cookiePair).toBeUndefined();
+    } finally {
+      await api.shutdown();
+    }
+  });
+});

apps/api/tests/module-database.integration.ts

@@ -224,6 +224,7 @@ async function applyCoreMigrations(url: string): Promise<void> {
       "core:0004_module_lifecycle_state",
       "core:0005_module_configuration",
       "core:0006_device_identity",
+      "core:0007_verified_bootstrap_owners",
     ]);
     await applyModuleMigrations({ aggregate, database: createPostgresMigrationDatabase(url) });
   } finally {
@@ -253,6 +254,7 @@ async function applyMigrationsWithModule(url: string): Promise<void> {
     "core:0004_module_lifecycle_state",
     "core:0005_module_configuration",
     "core:0006_device_identity",
+    "core:0007_verified_bootstrap_owners",
     "db-facade:0000_initial",
   ]);
   expect(aggregate.migrations[0]?.checksum).toBe(
@@ -319,6 +321,27 @@ async function signUp(origin: string, email: string, password: string): Promise<
   return { userId: body.user.id };
 }
 
+/**
+ * Marks an address verified out of band, the same trusted step the initial-owner bootstrap performs.
+ *
+ * A verified address is a precondition for holding a session (ADR 0038), and this suite is about
+ * module database access rather than identity, so it completes that step directly rather than
+ * standing up an SMTP server. That the policy is genuinely enforced is asserted in
+ * `email-verification.integration.ts`.
+ */
+async function markEmailVerified(url: string, email: string): Promise<void> {
+  const client = new Client({ connectionString: url });
+  await client.connect();
+  try {
+    await client.query(
+      'update "ekklesia_core_user" set "email_verified" = true where lower("email") = $1',
+      [email.trim().toLowerCase()],
+    );
+  } finally {
+    await client.end().catch(() => undefined);
+  }
+}
+
 async function signIn(origin: string, email: string, password: string): Promise<string> {
   const response = await fetch(`${origin}/api/auth/sign-in/email`, {
     body: JSON.stringify({ email, password }),
@@ -507,6 +530,7 @@ describe.sequential("live API — module database access through ModuleRuntimeSe
     expect(startupRow).toEqual({ id: STARTUP_RECORD_ID, value: "startup-value" });
 
     const signedUp = await signUp(origin, "[email protected]", "correct horse battery");
+    await markEmailVerified(database.url, "[email protected]");
     ownerCookie = await signIn(origin, "[email protected]", "correct horse battery");
     expect(signedUp.userId).toBeDefined();
   });