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/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,