@pithy-sh/auth 0.1.0

package/src/seeds/devSession.ts

@@ -0,0 +1,286 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { normalizeAddress } from "@pithy-sh/core/src/address/address";
+import { fromZodError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { MAX_SEED_ORDER } from "@pithy-sh/core/src/seed/compose";
+import { DEV_LOGIN_FILE, DEV_LOGIN_PATH, DevLogin } from "@pithy-sh/core/src/seed/devLogin";
+import {
+  d1SeedGroup,
+  defineSeed,
+  type SeedPreparation,
+  type SeedPrepareContext,
+  type SeedSet,
+} from "@pithy-sh/core/src/seed/seed";
+import { z } from "zod";
+import { Session } from "../data/betterAuth";
+import { DEV_PROTOCOL, sessionCookieName } from "../http/baseUrl";
+import { AUTH_SESSION_SECRET } from "../instance/secrets";
+
+/**
+ * The dev-login seed set: a real, signed-in session for one seeded user, so local development does not
+ * begin with a magic-link round trip.
+ *
+ * Sign-in is passwordless by design, which is right in production and a tax in development — and more
+ * than a tax for anything automated, which cannot read a mailbox at all. The interesting part is *where*
+ * the work happens: the session is minted during seed, so the database holds a genuine row and the browser
+ * is handed a genuine cookie. Nothing about the request path is relaxed to make it work.
+ *
+ * Four guard rails, because what this writes is a live credential:
+ *
+ * - `environments: ["dev"]` — it can never be composed into staging or production.
+ * - No `~/.config/pithy/<project>/dev.json`, no session. The default stays "there is no way in but a magic link";
+ *   opting in is a per-machine file outside the repo, so two developers on one checkout can differ.
+ * - The login file is transient, written under the gitignored `logs/` ({@link DEV_LOGIN_PATH}). A seeded
+ *   cookie must never be committable.
+ * - The named user must be one this run actually creates. A session for a user nobody seeded is a dangling
+ *   row, so `dev.json` is checked against `context.seeded` — the run's own inventory — and a miss fails
+ *   saying who *was* seeded.
+ *
+ * Not an example set. It seeds no users of its own; it signs in as whoever the run creates — auth's example
+ * cast when the project enables `includeExamples`, the app's own users otherwise, both when both. An adopter
+ * should not have to turn on a fictional cast to get a dev login, and the cast is no more seeded than before:
+ * it still arrives only through `authExampleSeed`, which is still `example: true`.
+ */
+
+/**
+ * Where this set sorts: last, at the ceiling. It depends on every set that can create a user — auth's own
+ * example set, and an adopter's app set, which sorts high by convention — so it sorts after all of them.
+ * Ties break on the namespaced key, but nothing rests on that: what this set needs to *know* comes from the
+ * composed plan, not from what has already been written, and the session row carries no foreign key.
+ */
+export const AUTH_DEV_SESSION_SEED_ORDER = MAX_SEED_ORDER;
+
+/** The composed registry coordinates of the users table this set reads and signs in as. */
+const USERS_DATABASE = "app";
+const USERS_TABLE = "pithyAuthUsers";
+
+/**
+ * The cookie Better Auth reads the session from, in the one environment this set runs in.
+ *
+ * It used to be a literal beside a comment asserting that a `dev` base URL is not HTTPS. Nothing made
+ * that true: `baseURL` was one string for every environment, so an adopter whose production origin was
+ * HTTPS — every adopter — seeded this name while the running instance looked for `__Secure-` (#244).
+ * The session was there, the cookie was there, and `get-session` returned `null` with nothing logged.
+ *
+ * Now it is computed from the same two facts the composition computes its own name from: a `dev`
+ * composition serves over {@link DEV_PROTOCOL}, and {@link sessionCookieName} is the prefix rule. The
+ * host and port never enter it, which is what lets a seed name a cookie for a port not yet assigned.
+ * Still locked to the running Better Auth version by a test that reads the name off a live instance.
+ */
+export const DEV_SESSION_COOKIE_NAME = sessionCookieName(DEV_PROTOCOL);
+
+/**
+ * The prefix every seeded dev session's id and token carry.
+ *
+ * It is what makes a dev session **findable without being told**, which is what the dev-login route
+ * needs: the route reads the session out of D1 and has no artifact to consult (a Worker has no
+ * filesystem). And it is what makes one identifiable at all — a `pithy_auth_sessions` row minted by a
+ * seed is otherwise indistinguishable from one a real sign-in created.
+ */
+export const DEV_SESSION_TOKEN_PREFIX = "dev-session-";
+
+/** How long a seeded session lives. Long, because reseeding to restore a dev login is the friction this removes. */
+const DEV_SESSION_LIFETIME_MS = 365 * 24 * 60 * 60 * 1000;
+
+/** Bytes of the secret digest kept as the token's fingerprint — enough to separate secrets, short enough to read. */
+const FINGERPRINT_BYTES = 4;
+
+/** The developer's machine-local preferences for this project, read from `~/.config/pithy/<project>/dev.json`. */
+export const DevPreferences = z
+  .object({
+    user: z
+      .string()
+      .describe(
+        "The email of the seeded user to sign in as. Must be a user this seed run creates, or the seed fails rather than signing in as nobody.",
+      ),
+  })
+  .describe(
+    "A developer's machine-local dev preferences, from the Pithy config directory (`~/.config/pithy/<project>/dev.json`, or `%APPDATA%\\pithy\\<project>\\dev.json` on Windows) — outside the repo, so opting in needs no commit.",
+  );
+export type DevPreferences = z.output<typeof DevPreferences>;
+
+/**
+ * A user this run seeds, read back out of the composed plan.
+ *
+ * Narrow on purpose: the rows come from a set this capability does not own — an adopter's, most of the time —
+ * so they cross a trust boundary and are validated, but only for the two fields a session needs. A row with
+ * more in it is fine; a row without these is not a user this set can sign in as.
+ */
+export const SeededUser = z
+  .object({
+    id: z.string().min(1).describe("The user id the session's `userId` points at."),
+    email: z.string().min(1).describe("The email `dev.json` names, and the login artifact records."),
+  })
+  .describe("A seeded `pithy_auth_users` row, narrowed to what minting a dev session for it requires.");
+export type SeededUser = z.output<typeof SeededUser>;
+
+/** What {@link mintDevSession} produces: the row to write, and the artifact the browser is handed. */
+export interface MintedDevSession {
+  /** The `pithy_auth_sessions` row, in app shape — re-encoded and validated by the seed writer. */
+  session: Session;
+  /** The dev-login artifact, written to `logs/dev-login.json` once the row lands. */
+  login: DevLogin;
+}
+
+/**
+ * Sign a value the way better-call does, so Better Auth accepts the cookie as one it signed itself:
+ * HMAC-SHA-256 over the value with the auth secret, base64, appended after a dot, then URI-encoded.
+ *
+ * Mirrored rather than imported: `signCookieValue` is internal to `better-call/dist/crypto`, not part of
+ * anything Better Auth re-exports, so importing it would bind us to a private path. Verified against
+ * better-call 1.3.6 — the version Better Auth 1.6.19 resolves — and pinned by a round-trip test that makes
+ * a real instance accept the result, which is the only check that actually matters.
+ */
+export async function signCookieValue(value: string, secret: string): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(value));
+  const base64 = btoa(String.fromCharCode(...new Uint8Array(signature)));
+  return encodeURIComponent(`${value}.${base64}`);
+}
+
+/**
+ * A short, stable fingerprint of the auth secret.
+ *
+ * Putting it in the session token makes the token deterministic across reseeds — the same cookie keeps
+ * working in every worktree once each is seeded, which is the whole point — while rotating the secret
+ * changes the token *and* invalidates every cookie signed with the old one, for free. A truncated digest,
+ * never the secret: the token is written to a file and read back by tooling.
+ */
+export async function secretFingerprint(secret: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(secret));
+  return Array.from(new Uint8Array(digest).slice(0, FINGERPRINT_BYTES))
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/** Inputs to {@link mintDevSession}. `now` is a seam so the determinism tests do not depend on the clock. */
+export interface MintDevSessionInput {
+  /** The seeded user to sign in as. */
+  user: SeededUser;
+  /** The Better Auth signing secret for this environment — never logged, never stored, never in an error. */
+  secret: string;
+  /** The moment the session is minted. Defaults to now. */
+  now?: Date;
+}
+
+/**
+ * Mint one deterministic dev session: the `pithy_auth_sessions` row and the signed cookie for it.
+ *
+ * The row id carries the fingerprint too, not just the token. Seed writes are `INSERT OR IGNORE`, so an
+ * id that ignored a rotation would keep the stale token alive under a row the next run refuses to replace.
+ */
+export async function mintDevSession(input: MintDevSessionInput): Promise<MintedDevSession> {
+  const now = input.now ?? new Date();
+  const expiresAt = new Date(now.getTime() + DEV_SESSION_LIFETIME_MS);
+  const fingerprint = await secretFingerprint(input.secret);
+  const token = `${DEV_SESSION_TOKEN_PREFIX}${input.user.id}-${fingerprint}`;
+
+  const session: Session = {
+    id: token,
+    token,
+    userId: input.user.id,
+    expiresAt,
+    createdAt: now,
+    updatedAt: now,
+    ipAddress: "127.0.0.1",
+    userAgent: "pithy seed (dev login)",
+    deviceId: null,
+    familyId: null,
+  };
+
+  return {
+    session,
+    login: {
+      email: input.user.email,
+      userId: input.user.id,
+      cookieName: DEV_SESSION_COOKIE_NAME,
+      cookieValue: await signCookieValue(token, input.secret),
+      expiresAt,
+    },
+  };
+}
+
+/**
+ * The users this run creates, whichever set contributes them.
+ *
+ * A row that does not parse is skipped rather than fatal: it belongs to some other set, which owns its own
+ * validation, and failing the dev login over someone else's fixture would be the wrong place to find out.
+ */
+function seededUsers(seeded: SeedPrepareContext["seeded"]): SeededUser[] {
+  return seeded(USERS_DATABASE, USERS_TABLE).flatMap((row) => {
+    const parsed = SeededUser.safeParse(row);
+    return parsed.success ? [parsed.data] : [];
+  });
+}
+
+/** What to do about it — the actionable half of every failure here, and never a guess. */
+function nameOneOf(users: readonly SeededUser[]): string {
+  if (users.length === 0) {
+    return "This run seeds no users at all. Add a user fixture to your app's seed set, or turn on seed.includeExamples for the example cast.";
+  }
+  return `Name one of the users this run seeds instead: ${users.map((user) => user.email).join(", ")}.`;
+}
+
+/** Resolve the preference file into the user to sign in as, or fail saying who this run does seed. */
+function requireUser(preferences: unknown, users: readonly SeededUser[]): SeededUser {
+  const parsed = DevPreferences.safeParse(preferences);
+  if (!parsed.success) {
+    throw fromZodError(parsed.error, {
+      message: "The dev.json preference file does not name a user.",
+      action: `Set { "user": "<email>" } in it. ${nameOneOf(users)}`,
+    });
+  }
+  // Both sides normalized: `dev.json` is hand-typed, and refusing to sign in over the capital in
+  // `Ada@example.com` would be a puzzle rather than an error.
+  const wanted = normalizeAddress(parsed.data.user);
+  const user = users.find((candidate) => normalizeAddress(candidate.email) === wanted);
+  if (!user) {
+    throw new ValidationError({
+      message: `dev.json asks to sign in as ${parsed.data.user}, which this seed run does not create.`,
+      action: nameOneOf(users),
+    });
+  }
+  return user;
+}
+
+/**
+ * The dev-login seed set. Composed by the auth capability; runs only in `dev`, only for a user this same run
+ * creates, and only when the developer has opted in with a `dev.json`.
+ */
+export const authDevSessionSeed: SeedSet = defineSeed({
+  name: "dev-session",
+  order: AUTH_DEV_SESSION_SEED_ORDER,
+  environments: ["dev"],
+  prepare: async (context): Promise<SeedPreparation> => {
+    // No dev.json, no session. This is the default, and it is the one that keeps "there is no way in but
+    // a magic link" true for everyone who never asked for anything else.
+    if (context.preferences === undefined || context.preferences === null) return {};
+
+    const user = requireUser(context.preferences, seededUsers(context.seeded));
+    const secret = await context.secret(AUTH_SESSION_SECRET);
+    if (!secret) {
+      throw new ValidationError({
+        message: "Cannot mint a dev session without this environment's auth secret.",
+        // Never `.dev.vars` (#176). Every `d1` secret left that file in #153, and telling an adopter to
+        // put one back there is telling them to undo it — the value would be inert, and the seed would
+        // fail again with the same sentence. The path is deliberately unnamed rather than guessed: this
+        // set runs inside a Worker with no filesystem and no config directory to resolve, and `pithy
+        // doctor` prints the resolved path on every run precisely so a message like this does not have to.
+        action: `Add ${AUTH_SESSION_SECRET} to this project's dev secrets file — pithy doctor prints its path — then seed again.`,
+      });
+    }
+
+    const minted = await mintDevSession({ user, secret });
+    return {
+      d1: [d1SeedGroup("app", "pithyAuthSessions", Session, [minted.session])],
+      artifacts: [{ file: DEV_LOGIN_FILE, contents: `${JSON.stringify(DevLogin.encode(minted.login), null, 2)}\n` }],
+    };
+  },
+});

package/src/seeds/example.ts

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { EXAMPLE_IDENTITIES } from "@pithy-sh/core/src/seed/exampleIdentities";
+import { d1SeedGroup, defineSeed, type SeedSet } from "@pithy-sh/core/src/seed/seed";
+import { User } from "../data/betterAuth";
+
+/**
+ * Where the example set sorts among the whole project's seed registry. Auth seeds the identities
+ * first — before the leaderboard/ledger/multiplayer example sets, which reference these same users
+ * by id — so `order` encodes that dependency, exactly like the migration registry.
+ */
+const AUTH_EXAMPLE_SEED_ORDER = 100;
+
+/**
+ * The canonical demo cast ({@link EXAMPLE_IDENTITIES}) as `pithy_auth_users` rows — the shared,
+ * passwordless test identities every other capability's example seed references by `userId`. No
+ * `Account`/`Session`/password rows: these are the users, not a signed-in session, and Pithy is
+ * passwordless-only regardless. `emailVerified` is true so a seeded identity behaves exactly like a
+ * user who has completed magic-link/OTP verification. Composed in only when the project turns on
+ * `seed.includeExamples` (`pithy.config.ts`), and only for `dev` and `staging` — an example fixture
+ * never targets production, regardless of that setting.
+ */
+export const authExampleSeed: SeedSet = defineSeed({
+  name: "example",
+  order: AUTH_EXAMPLE_SEED_ORDER,
+  environments: ["dev", "staging"],
+  example: true,
+  d1: [
+    d1SeedGroup(
+      "app",
+      "pithyAuthUsers",
+      User,
+      EXAMPLE_IDENTITIES.map((identity) => ({
+        id: identity.id,
+        name: identity.name,
+        email: identity.email,
+        emailVerified: true,
+        image: null,
+        // The example cast has never picked a language, which is the state most real users are in:
+        // negotiate from `Accept-Language` until they do.
+        locale: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      })),
+    ),
+  ],
+});

package/src/test-utils/liveApp.ts

@@ -0,0 +1,338 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import type { D1Database } from "@cloudflare/workers-types";
+import type { AuditEventInput } from "@pithy-sh/core/src/audit/auditEvent";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { pithyErrorHandler } from "@pithy-sh/core/src/error/http";
+import { createMigrationRegistry } from "@pithy-sh/core/src/migrations/registry";
+import { runMigrations } from "@pithy-sh/core/src/migrations/runner";
+import { email } from "@pithy-sh/email/src/capability";
+import { email_0001_init } from "@pithy-sh/email/src/migrations/0001_init";
+import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
+import { configureSharedSecrets, resetSharedSecrets } from "@pithy-sh/secrets/src/sharedSecretsStore";
+import { devEncryptionKeys } from "@pithy-sh/secrets/src/test-utils/devEncryptionKeys";
+import { type SecretFixture, seedSecrets } from "@pithy-sh/secrets/src/test-utils/secretFixtures";
+import { turnstileSecretsRegistry } from "@pithy-sh/turnstile/src/secret/registry";
+import { Hono } from "hono";
+import { Miniflare } from "miniflare";
+import { AuthConfig, type AuthWiring } from "../capability";
+import { publishSameOrigin } from "../http/csrf";
+import { createSessionMiddleware } from "../http/middleware";
+import { createRateLimitMiddleware } from "../http/rateLimit";
+import { createAuthRoutes } from "../http/routes";
+import { authSecretsRegistry } from "../instance/secrets";
+import { AUTH_MIGRATION_ORDER, auth_0001_init } from "../migrations/0001_init";
+
+/**
+ * A real auth Worker on a real port, for the live suites (#84).
+ *
+ * The live E2E questions this package has are about an **origin**: which `redirect_uri` Better Auth
+ * hands Google, whether a token posted from a browser survives the humanity gate, whether a callback
+ * arriving with a forged `state` sets a cookie. None of those are answerable inside the workers pool,
+ * which has no listening socket and therefore no port a redirect URI could name; and none are
+ * answerable against a hand-built Better Auth instance either, because the thing under test is the
+ * route stack the capability composes — the turnstile gate on two paths and not a third, the CSRF
+ * publication, the rate limiter — rather than the instance underneath it.
+ *
+ * So this boots the real stack in Node:
+ *
+ * - **Miniflare supplies D1**, from Node rather than from inside a worker. Two databases, as a deployed
+ *   worker has: `DB` for the `pithy_auth_*` and `pithy_email_*` tables, `SECRETS` for the encrypted
+ *   rows every secret is read from (#153). No plaintext binding stands in for either.
+ * - **The migrations are the real ones**, run through the real registry and runner.
+ * - **`node:http` gives the port.** Vitest's `fetch` reaches the app the way a browser would, so an
+ *   `Origin` header is a real one and a `Set-Cookie` is a real one.
+ *
+ * It reaches Cloudflare for nothing. What is live in a suite built on this is the third party the suite
+ * names — Google's token endpoint, Turnstile's siteverify — and nothing else.
+ */
+
+/** The registry these suites resolve through: auth's slice plus turnstile's, since one route stacks the gate. */
+export const LIVE_REGISTRY = { ...authSecretsRegistry, ...turnstileSecretsRegistry };
+
+/** Unconfigure the module-scoped shared secrets store. For the end of a file, never for one app's close. */
+export function resetLiveSecrets(): void {
+  resetSharedSecrets();
+}
+
+/** Tables the app database holds once both capabilities' migrations have run. */
+const TABLES = [
+  "pithy_auth_accounts",
+  "pithy_auth_devices",
+  "pithy_auth_jwks",
+  "pithy_auth_rate_limit",
+  "pithy_auth_rotated_tokens",
+  "pithy_auth_sessions",
+  "pithy_auth_users",
+  "pithy_auth_verifications",
+  "pithy_email_jobs",
+  "pithy_email_events",
+];
+
+/**
+ * The session secret these suites sign with.
+ *
+ * A fixed throwaway rather than a random one, so a failure is reproducible; it authenticates nothing
+ * anywhere, and it is not a value the fixture report or an error message ever carries.
+ */
+const SESSION_SECRET = "live-e2e-secret-please-rotate-000000";
+
+/** An email job the app wrote: which template, and to whom. The body is never read — it carries a token. */
+export interface EnqueuedEmail {
+  /** The job's template — `magic-link`, `otp`, … as `pithy_email_jobs` recorded it. */
+  template: string;
+  /** The recipient address. */
+  to: string;
+}
+
+/** What a suite may change about the app it boots. Everything else is the capability's own default. */
+export interface LiveAppOptions {
+  /**
+   * The mount path, **always stated**.
+   *
+   * `AuthConfig` defaults it to `/auth`, and that default is precisely what a live suite must not lean
+   * on: every `redirect_uri` registered with an OAuth provider embeds this path, so moving it silently
+   * invalidates all of them at once, and a suite that took the default could not tell that it had moved.
+   * Required here, so the pin is in the suite where its reader can see it.
+   */
+  basePath: string;
+  /** Whether Google is enabled. When true, `google` credentials must be supplied. */
+  google?: { clientId: string; clientSecret: string } | undefined;
+  /** When set, the turnstile gate is composed at this widget mode, exactly as `auth.compose` stacks it. */
+  turnstile?: { mode: "visible" | "invisible"; secretKey: string } | undefined;
+  /**
+   * The `ENVIRONMENT` var this Worker is stamped with, as `pithy init` writes into every wrangler
+   * stanza. `dev` by default, because that is what these suites are: a developer's machine, running the
+   * stack the way `pithy dev` does.
+   *
+   * It is an option because one thing now reads it — the turnstile gate refuses a Cloudflare test key
+   * outside dev and staging (#374) — so a suite has to be able to say it is prod to prove that.
+   */
+  environment?: string;
+}
+
+/** A booted app: where it listens, what it was pinned to, and what it recorded. */
+export interface LiveApp {
+  /** The origin the app is actually serving on — `http://localhost:<port>`, port assigned by the OS. */
+  origin: string;
+  /** The mount path the suite pinned. Every asserted URL is composed from this, never from a literal. */
+  basePath: string;
+  /** The OAuth callback URL for a provider, composed from this run's origin and pinned base path. */
+  callbackUrl(provider: string): string;
+  /** Every audit event the app emitted, in order. */
+  events: AuditEventInput[];
+  /** Read the email jobs the app enqueued — the evidence a gated route did or did not reach its handler. */
+  enqueued(): Promise<EnqueuedEmail[]>;
+  /**
+   * The one-time code this app last mailed to an address, read out of the job payload.
+   *
+   * **What it is for is a signed-in browser.** A suite about a route that needs a session has to get
+   * one the way a reader does — ask for a code, then post it back — and the code exists nowhere a
+   * browser can see it. Reading the enqueued job is the harness standing in for the mailbox, and it is
+   * the only stand-in available: no Workflow runs here, so nothing is ever delivered or redacted.
+   *
+   * `null` when nothing was mailed to that address, which is a suite asserting on a send that never
+   * happened rather than a code that was blank.
+   */
+  mailedOtp(to: string): Promise<string | null>;
+  /** Stop the server and dispose the runtime. Always from a `finally` or an `afterAll`. */
+  close(): Promise<void>;
+}
+
+/**
+ * Boot the auth Worker on an ephemeral port.
+ *
+ * The caller owns the teardown: `close()` stops the listener and disposes Miniflare, and a suite that
+ * forgets leaves a workerd process behind.
+ */
+export async function startLiveApp(options: LiveAppOptions): Promise<LiveApp> {
+  const miniflare = new Miniflare({
+    modules: true,
+    script: "export default {};",
+    d1Databases: { DB: "DB", SECRETS: "SECRETS" },
+  });
+  const db = (await miniflare.getD1Database("DB")) as unknown as D1Database;
+  const secretsDb = (await miniflare.getD1Database("SECRETS")) as unknown as D1Database;
+
+  const env: Record<string, unknown> = {
+    DB: db,
+    SECRETS: secretsDb,
+    SECRETS_ENCRYPTION_KEYS: devEncryptionKeys(),
+    // What a Worker knows about itself (`core/src/worker/identity`), stamped as the scaffold stamps it.
+    ENVIRONMENT: options.environment ?? "dev",
+    // The tier-1 edge limiter's binding. Always allows: these suites are about the gate below it, and a
+    // limiter that denied would make a failure read as a bug in the thing under test.
+    AUTH_RATE_LIMITER: { limit: async () => ({ success: true }) } satisfies RateLimit,
+  };
+
+  await migrate(db);
+
+  const fixture: SecretFixture<typeof LIVE_REGISTRY> = { "auth-session-secret": SESSION_SECRET };
+  if (options.google) fixture["auth-google-credentials"] = options.google;
+  if (options.turnstile) {
+    fixture["turnstile-secret-keys"] = { [options.turnstile.mode]: { key: options.turnstile.secretKey } };
+  }
+  configureSharedSecrets({ registry: LIVE_REGISTRY });
+  await seedSecrets(env as unknown as SecretsStoreEnv, LIVE_REGISTRY, fixture);
+
+  const events: AuditEventInput[] = [];
+  const server = createServer();
+  const origin = await listen(server);
+
+  const emailCapability = email({ fromAddress: "no@reply.test", fromName: "Live E2E", baseUrl: origin });
+  const wiring: AuthWiring = {
+    config: AuthConfig.parse({
+      baseURL: origin,
+      basePath: options.basePath,
+      trustedOrigins: [origin],
+      google: { enabled: Boolean(options.google) },
+    }),
+    enqueueEmail: emailCapability.enqueue,
+    turnstile: options.turnstile ? { mode: options.turnstile.mode } : undefined,
+  };
+
+  const app = buildApp(wiring, events);
+  server.on("request", (request, response) => {
+    void serve(app, env, origin, request, response);
+  });
+
+  return {
+    origin,
+    basePath: options.basePath,
+    callbackUrl: (provider) => `${origin}${options.basePath}/callback/${provider}`,
+    events,
+    enqueued: async () => {
+      const rows = await db.prepare("select template, to_address from pithy_email_jobs order by rowid").all();
+      return (rows.results as { template: string; to_address: string }[]).map((row) => ({
+        template: row.template,
+        to: row.to_address,
+      }));
+    },
+    mailedOtp: async (to) => {
+      const row = await db
+        .prepare(
+          "select payload from pithy_email_jobs where to_address = ? and template = 'otp' order by rowid desc limit 1",
+        )
+        .bind(to)
+        .first<{ payload: string }>();
+      if (!row) return null;
+      const parsed: unknown = JSON.parse(row.payload);
+      const code = typeof parsed === "object" && parsed !== null ? (parsed as { code?: unknown }).code : undefined;
+      return typeof code === "string" ? code : null;
+    },
+    close: async () => {
+      // Deliberately **not** `resetSharedSecrets()`. That configuration is module-scoped, as it is in a
+      // worker isolate, so a suite running two apps at once — one pinned at `/auth`, one at `/identity`
+      // — would have the second's teardown unconfigure the first, and every later request to it would
+      // answer 500. The configuration holds a registry and no values; each app resolves its own secrets
+      // from its own `SECRETS` D1 through its own env, so sharing it costs nothing. `resetLiveSecrets`
+      // is there for a suite that wants the module clean at the end.
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await miniflare.dispose();
+    },
+  };
+}
+
+/** Run auth's and email's real migrations against a fresh database. */
+async function migrate(db: D1Database): Promise<void> {
+  for (const table of [...TABLES, "pithy_migrations", "pithy_migrations_lock"]) {
+    await db.prepare(`drop table if exists ${table}`).run();
+  }
+  const provider = createMigrationRegistry([
+    { database: "app", namespace: "auth", order: AUTH_MIGRATION_ORDER, migrations: { "0001_init": auth_0001_init } },
+    { database: "app", namespace: "email", order: 200, migrations: { "0001_init": email_0001_init } },
+  ]).app;
+  if (!provider) throw new Error('expected a migration provider for database "app"');
+  await runMigrations(db, provider);
+}
+
+/**
+ * The capability's middleware order, mirrored: same-origin publication, the tier-1 limiter, session
+ * resolution, then the routes.
+ *
+ * Mirrored rather than obtained from `auth().compose()` because composing the capability needs a
+ * `pithy.config.ts`, a project on disk and a CLI to resolve it. The order here is the order
+ * `capability.ts` registers, and `routeContract.test.ts` is what holds that claim honest.
+ */
+function buildApp(wiring: AuthWiring, events: AuditEventInput[]): Hono<PithyHonoEnv> {
+  const app = new Hono<PithyHonoEnv>();
+  app.onError(pithyErrorHandler);
+  app.use("*", async (c, next) => {
+    if (c.get("emit") === undefined) {
+      c.set("emit", async (event) => {
+        events.push(event);
+      });
+    }
+    if (c.get("auth") === undefined) c.set("auth", null);
+    await next();
+  });
+  publishSameOrigin(wiring)(app);
+  app.use(`${wiring.config.basePath}/*`, createRateLimitMiddleware(wiring.config.rateLimiterBinding));
+  createSessionMiddleware(wiring)(app);
+  createAuthRoutes(wiring)(app);
+  return app;
+}
+
+/** Listen on an OS-assigned port and answer with the origin that names it. */
+function listen(server: Server): Promise<string> {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address() as AddressInfo;
+      resolve(`http://localhost:${address.port}`);
+    });
+  });
+}
+
+/** Hand one Node request to the Hono app and write back what it answered. */
+async function serve(
+  app: Hono<PithyHonoEnv>,
+  env: Record<string, unknown>,
+  origin: string,
+  request: IncomingMessage,
+  response: ServerResponse,
+): Promise<void> {
+  try {
+    const answer = await app.fetch(await toRequest(request, origin), env);
+    // `getSetCookie()` and not `headers.forEach`: a response carrying two cookies has two headers of
+    // the same name, and folding them into one comma-joined value is how a session cookie arrives
+    // unparseable at a client that would otherwise have accepted it.
+    const headers: [string, string][] = [];
+    for (const [key, value] of answer.headers) if (key.toLowerCase() !== "set-cookie") headers.push([key, value]);
+    for (const cookie of answer.headers.getSetCookie()) headers.push(["set-cookie", cookie]);
+    response.writeHead(answer.status, headers);
+    response.end(answer.body ? Buffer.from(await answer.arrayBuffer()) : undefined);
+  } catch (cause) {
+    // A throw here is a defect in the harness, never a result. Answering 500 silently would let a suite
+    // read a harness crash as the app denying a request, which is the exact confusion these tests exist
+    // to remove — so the reason goes on the wire.
+    response.writeHead(500, { "content-type": "text/plain" });
+    response.end(`live harness failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+  }
+}
+
+/** A Node request as a Web `Request`, body and all. */
+async function toRequest(request: IncomingMessage, origin: string): Promise<Request> {
+  const method = request.method ?? "GET";
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(request.headers)) {
+    if (value === undefined) continue;
+    for (const one of Array.isArray(value) ? value : [value]) headers.append(key, one);
+  }
+  const hasBody = method !== "GET" && method !== "HEAD";
+  const body = hasBody ? await readBody(request) : undefined;
+  return new Request(new URL(request.url ?? "/", origin), { method, headers, body });
+}
+
+/** Collect a request body. */
+function readBody(request: IncomingMessage): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    request.on("data", (chunk: Buffer) => chunks.push(chunk));
+    request.on("end", () => resolve(Buffer.concat(chunks)));
+    request.on("error", reject);
+  });
+}