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]>

core/src/identity/config.ts

@@ -5,6 +5,10 @@ export type IdentityConfigErrorCode =
   | "BASE_URL_INVALID"
   | "BASE_URL_LOOPBACK_IN_PRODUCTION"
   | "BASE_URL_MISSING"
+  | "DASHBOARD_ORIGIN_INSECURE_IN_PRODUCTION"
+  | "DASHBOARD_ORIGIN_INVALID"
+  | "DASHBOARD_ORIGIN_LOOPBACK_IN_PRODUCTION"
+  | "DASHBOARD_ORIGIN_UNTRUSTED"
   | "PUBLIC_SIGNUP_ENABLED_INVALID"
   | "PUBLIC_SIGNUP_UNSUPPORTED_IN_PRODUCTION"
   | "SECRET_LOW_ENTROPY"
@@ -127,6 +131,13 @@ const errorMessages: Readonly<Record<IdentityConfigErrorCode, string>> = Object.
   BASE_URL_LOOPBACK_IN_PRODUCTION:
     "The identity base URL must not resolve to a loopback host in production.",
   BASE_URL_MISSING: "The identity base URL is required.",
+  DASHBOARD_ORIGIN_INSECURE_IN_PRODUCTION: "The Dashboard origin must use https in production.",
+  DASHBOARD_ORIGIN_INVALID:
+    "The Dashboard origin must be an absolute http or https origin with no path, query, or fragment.",
+  DASHBOARD_ORIGIN_LOOPBACK_IN_PRODUCTION:
+    "The Dashboard origin must not resolve to a loopback host in production.",
+  DASHBOARD_ORIGIN_UNTRUSTED:
+    "The Dashboard origin must also be listed as a trusted origin, or emailed links will be refused.",
   PUBLIC_SIGNUP_ENABLED_INVALID:
     'Public signup enablement must be an explicit boolean or the exact string "true"/"false".',
   PUBLIC_SIGNUP_UNSUPPORTED_IN_PRODUCTION:
@@ -163,6 +174,21 @@ export class IdentityConfigError extends Error {
 
 export interface IdentityConfig {
   readonly baseUrl: string;
+  /**
+   * The browser origin an emailed verification or password-reset link sends a person to.
+   *
+   * Defaults to `baseUrl`, which is the ordinary production shape: the Dashboard bundle and the API
+   * are served from one origin. It exists as its own value because they are not the same *concept* —
+   * `baseUrl` is where the `/api/auth` transport lives, this is where a human's browser lands — and
+   * a deployment may separate them (an API at `https://api.example.org`, the Dashboard at
+   * `https://dash.example.org`). It is deliberately **not** the public church website origin: this
+   * is the authenticated Dashboard host and nothing else.
+   *
+   * Validated to be one of `trustedOrigins` (or `baseUrl`, which Better Auth trusts implicitly), so
+   * a misconfiguration fails at startup rather than producing emailed links every recipient is
+   * refused at.
+   */
+  readonly dashboardOrigin: string;
   /** Whether `POST /api/auth/sign-up/email` accepts new accounts. Defaults to `false` (disabled) —
    * public signup never becomes reachable merely because this input was omitted, misspelled, or
    * loosely parsed. Development and test composition may enable it explicitly; production
@@ -176,6 +202,8 @@ export interface IdentityConfig {
 
 export interface IdentityConfigInput {
   readonly baseUrl?: unknown;
+  /** Optional. Absent or empty means the Dashboard is served from `baseUrl`. */
+  readonly dashboardOrigin?: unknown;
   readonly publicSignupEnabled?: unknown;
   readonly secret?: unknown;
   readonly trustedOrigins?: unknown;
@@ -261,6 +289,45 @@ function validateBaseUrl(baseUrl: unknown, environment: IdentityEnvironment): st
   return url.origin;
 }
 
+/**
+ * Resolves the origin an emailed link points a browser at.
+ *
+ * Unset falls back to the identity base URL — the same-origin production shape — rather than
+ * failing, because a deployment that has not separated its Dashboard from its API has nothing to
+ * configure. When it *is* set it is held to exactly the base URL's rules and then to one more: it
+ * must be an origin Better Auth already trusts, because Better Auth validates the emailed callback
+ * against `trustedOrigins` before redirecting. Checking it here converts a broken link every
+ * recipient would hit into a startup failure the operator sees once.
+ */
+function validateDashboardOrigin(
+  dashboardOrigin: unknown,
+  baseUrl: string,
+  trustedOrigins: readonly string[],
+  environment: IdentityEnvironment,
+): string {
+  if (dashboardOrigin === undefined || dashboardOrigin === null || dashboardOrigin === "") {
+    return baseUrl;
+  }
+  const url = parseCanonicalHttpOrigin(dashboardOrigin);
+  if (!url) {
+    throw new IdentityConfigError("DASHBOARD_ORIGIN_INVALID");
+  }
+  if (environment === "production") {
+    if (url.protocol !== "https:") {
+      throw new IdentityConfigError("DASHBOARD_ORIGIN_INSECURE_IN_PRODUCTION");
+    }
+    if (isLoopbackOrUnspecifiedHostname(url.hostname)) {
+      throw new IdentityConfigError("DASHBOARD_ORIGIN_LOOPBACK_IN_PRODUCTION");
+    }
+  }
+  // `baseUrl` is accepted without appearing in `trustedOrigins` because Better Auth itself adds the
+  // base URL's origin to its trusted set (`getTrustedOrigins`, pinned release).
+  if (url.origin !== baseUrl && !trustedOrigins.includes(url.origin)) {
+    throw new IdentityConfigError("DASHBOARD_ORIGIN_UNTRUSTED");
+  }
+  return url.origin;
+}
+
 function validateTrustedOrigin(origin: unknown, environment: IdentityEnvironment): string {
   if (typeof origin !== "string" || origin.length === 0) {
     throw new IdentityConfigError("TRUSTED_ORIGIN_INVALID");
@@ -355,7 +422,19 @@ export function createIdentityConfig(
   const secret = validateSecret(input.secret);
   const baseUrl = validateBaseUrl(input.baseUrl, environment);
   const trustedOrigins = validateTrustedOrigins(input.trustedOrigins, environment);
+  const dashboardOrigin = validateDashboardOrigin(
+    input.dashboardOrigin,
+    baseUrl,
+    trustedOrigins,
+    environment,
+  );
   const publicSignupEnabled = validatePublicSignupEnabled(input.publicSignupEnabled, environment);
 
-  return Object.freeze({ baseUrl, publicSignupEnabled, secret, trustedOrigins });
+  return Object.freeze({
+    baseUrl,
+    dashboardOrigin,
+    publicSignupEnabled,
+    secret,
+    trustedOrigins,
+  });
 }