@pithy-sh/auth 0.1.0

package/src/http/adminRoutes.ts

@@ -0,0 +1,368 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { zValidator } from "@hono/zod-validator";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import type { ControlPlaneContext } from "@pithy-sh/core/src/controlPlane/context";
+import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
+import { MAX_PAGE_SIZE } from "@pithy-sh/core/src/data/cursor";
+import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import { validationHook } from "@pithy-sh/core/src/http/validation";
+import type { Context, Hono } from "hono";
+import {
+  type AdminSubList,
+  findSessionById,
+  getUser,
+  listDeviceRegistry,
+  listUserDevices,
+  listUserSessions,
+  listUsers,
+  userProviders,
+  userSessionTokens,
+} from "../admin/users";
+import { AuthAuditActions } from "../audit/actions";
+import { correlation, emitControlPlaneAction } from "../audit/emit";
+import type { AuthWiring } from "../capability";
+import { authDatabase } from "../data/tables";
+import { deleteDevice, deviceSessionTokens } from "../device/registry";
+import {
+  AUTH_DEVICES_READ_SCOPE,
+  AUTH_DEVICES_REVOKE_SCOPE,
+  AUTH_SESSIONS_REVOKE_SCOPE,
+  AUTH_USERS_LOGOUT_SCOPE,
+  AUTH_USERS_READ_SCOPE,
+} from "./guards";
+import { getAuthInstance, resolveDb } from "./resolve";
+import type {
+  AdminDeviceRevokeResponse,
+  AdminDevicesResponse,
+  AdminRevokeResponse,
+  AdminUserResponse,
+  AdminUsersResponse,
+} from "./responses";
+import { ListDevicesQuery, ListUsersQuery, RevokeDeviceBody, RevokeSessionBody, UserIdParam } from "./schemas";
+import { deviceView, sessionView, userView } from "./views";
+
+type Ctx = Context<PithyHonoEnv>;
+
+/**
+ * The control-plane admin surface: the reads a management dashboard's user panes resolve to, and the
+ * revocations an incident costs.
+ *
+ *   GET  {base}/admin/users                          auth:users:read       query: ListUsersQuery
+ *   GET  {base}/admin/users/:userId                  auth:users:read       param: UserIdParam
+ *   GET  {base}/admin/devices                        auth:devices:read     query: ListDevicesQuery
+ *   POST {base}/admin/sessions/revoke                auth:sessions:revoke  json:  RevokeSessionBody
+ *   POST {base}/admin/users/:userId/sessions/revoke  auth:users:logout     param: UserIdParam
+ *   POST {base}/admin/users/:userId/devices/revoke   auth:devices:revoke   param + json
+ *
+ * ## Registered before the catch-all, or dead
+ *
+ * `createAuthRoutes` ends with `app.all(`${base}/*`, handleBetterAuth)`, and `handleBetterAuth` returns
+ * a Response — which ends the chain. **Anything registered after that line is silently unreachable**,
+ * and a route-inspection test would still pass because the route is genuinely mounted; it just never
+ * runs. So these are registered from inside `createAuthRoutes` before the catch-all, and
+ * `routeContract.test.ts` proves it with a real request rather than by reading `app.routes`.
+ *
+ * ## `requireControlPlane` only, never `requireAuth`
+ *
+ * See `guards.ts` for the whole argument. The short version: the seam deliberately leaves `c.var.auth`
+ * null, so an auth gate here would deny every legitimate management call forever, and there is no user
+ * to sign in as that would fix it.
+ *
+ * ## Validators after the gate, on every line
+ *
+ * A validator ahead of the gate turns a 403 into a 400 and tells an unverified caller which requests
+ * were well-formed. On this surface that is a live oracle for an adopter's identity model, so the
+ * ordering is asserted in `routeContract.test.ts` rather than trusted to the order somebody typed the
+ * arguments in.
+ *
+ * ## Every response is a deliberate projection, and every projection has a schema
+ *
+ * No handler returns a row. The projections live in `views.ts` and the objects a client validates
+ * against live in `responses.ts`, each view typed as `z.output` of its own schema — so what this
+ * Worker sends and what a management client is told to expect are one declaration rather than two
+ * that drift. `sessionView` drops the session **token**; `deviceView` drops the **push token**; and
+ * the account link is read as a list of provider slugs by a query that selects only `providerId`, so
+ * the OAuth `accessToken`, `refreshToken` and `idToken` are never loaded at all.
+ *
+ * Each `c.json` below is `satisfies`-checked against its envelope. The check belongs at compile time:
+ * parsing every response would spend a validation pass on data this Worker just built from its own
+ * rows, and it would turn a shape mistake into a 500 in production rather than a red build.
+ */
+
+/** The auth Kysely for this request. */
+function db(c: Ctx, wiring: AuthWiring) {
+  return authDatabase(resolveDb(c.env, wiring.config.database));
+}
+
+/**
+ * One of the user pane's sub-reads, guarded and projected in one step (#380).
+ *
+ * **`try`/`catch` inside an `async` function, never `.catch()`.** The read is *called* inside the `try`,
+ * so a seam that throws before it returns a promise is caught too — a rejected promise is not the only
+ * way a D1 read fails, and a `.catch()` guard has been escaped by exactly that before (#371).
+ *
+ * **The guard takes no binding.** The state is the whole of what travels; what the read threw names a
+ * query and a table, and this response goes to a management client across a trust boundary.
+ *
+ * It projects while it is here, because the alternative is a second helper mapping a union it just
+ * built, and a projection that runs outside the guard is a second place a row can throw.
+ */
+async function readBounded<T, V>(
+  read: () => Promise<AdminSubList<T>>,
+  project: (row: T) => V,
+): Promise<{ state: "read"; items: V[]; truncated: boolean } | { state: "unavailable" }> {
+  try {
+    const list = await read();
+    return { state: "read", items: list.items.map(project), truncated: list.truncated };
+  } catch {
+    return { state: "unavailable" };
+  }
+}
+
+/** The same guard for a read with no bound to exceed — the provider slugs, which carry no truncation. */
+async function readWhole<T>(
+  read: () => Promise<T[]>,
+): Promise<{ state: "read"; items: T[] } | { state: "unavailable" }> {
+  try {
+    return { state: "read", items: await read() };
+  } catch {
+    return { state: "unavailable" };
+  }
+}
+
+/**
+ * The verified management client behind a control-plane call.
+ *
+ * `requireControlPlane()` has run on every route below, so a null context is a wiring mistake rather
+ * than an unverified request — hence `InternalError`, not a 401. Deliberately not read off `c.var.auth`:
+ * a management client has no user row and no session, and keeping the two accessors apart is what stops
+ * a control-plane caller from being recorded as, or mistaken for, a user of this app.
+ */
+function controlPlaneCaller(c: Ctx): ControlPlaneContext {
+  const caller = c.var.controlPlane;
+  if (!caller) {
+    throw new InternalError({
+      message: "Authentication is misconfigured.",
+      detail: "requireControlPlane() must run before an auth admin handler reads the management caller.",
+    });
+  }
+  return caller;
+}
+
+/** The request correlation every admin audit event carries. */
+function context(c: Ctx): { ip?: string; userAgent?: string; requestId?: string } {
+  return { ...correlation(c.req.raw.headers), requestId: c.req.header("cf-ray") };
+}
+
+/** Delete sessions through Better Auth's own adapter, so its bookkeeping stays consistent. */
+async function revokeTokens(c: Ctx, wiring: AuthWiring, tokens: readonly string[]): Promise<number> {
+  if (tokens.length === 0) return 0;
+  // `internalAdapter.deleteSession`, never a raw DELETE — the same path `revokeMyDevice` and the
+  // reuse-detection family revoke take. A direct delete would leave whatever Better Auth keeps beside
+  // the row (secondary storage, its own caches) pointing at a session that no longer exists.
+  const ctx = await (await getAuthInstance(c, wiring)).$context;
+  for (const token of tokens) {
+    await ctx.internalAdapter.deleteSession(token);
+  }
+  return tokens.length;
+}
+
+/**
+ * Register the control-plane admin routes. Called by `createAuthRoutes` **before** the Better Auth
+ * catch-all; see the file header for why that ordering is load-bearing.
+ */
+export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHonoEnv>) => void {
+  return (app) => {
+    const base = wiring.config.basePath;
+
+    app.get(
+      `${base}/admin/users`,
+      requireControlPlane(AUTH_USERS_READ_SCOPE),
+      zValidator("query", ListUsersQuery, validationHook),
+      async (c) => {
+        const query = c.req.valid("query");
+        const caller = controlPlaneCaller(c);
+        const page = await listUsers(db(c, wiring), query);
+        await emitControlPlaneAction(c.var.emit, {
+          action: AuthAuditActions.adminUsersListed,
+          subject: caller.subject,
+          connectionId: caller.connectionId,
+          resourceType: "user",
+          ...context(c),
+          // `searched`, not the term. A search term on this route is usually somebody's email address,
+          // and the audit trail is queryable and kept far longer than the pane that displayed it — so
+          // recording the term would copy the personal data the caller already saw into a second store
+          // with a different retention policy. That it was a search, and how much came back, is what
+          // makes an exfiltration pattern visible; the string itself adds nothing to that.
+          metadata: { searched: query.search !== undefined, returned: page.items.length },
+        });
+        return c.json({ users: page.items.map(userView), nextCursor: page.nextCursor } satisfies AdminUsersResponse);
+      },
+    );
+
+    app.get(
+      `${base}/admin/users/:userId`,
+      requireControlPlane(AUTH_USERS_READ_SCOPE),
+      zValidator("param", UserIdParam, validationHook),
+      async (c) => {
+        const { userId } = c.req.valid("param");
+        const caller = controlPlaneCaller(c);
+        const database = db(c, wiring);
+
+        const user = await getUser(database, userId);
+        if (!user)
+          throw new NotFoundError({ message: "No such user.", detail: `no pithy_auth_users row for ${userId}` });
+
+        // Bounded, because a device id is client-generated: a user can mint as many device rows as they
+        // like, so an unbounded sub-list would let any end user decide how much work this pane does.
+        //
+        // Each read is guarded on its own (#380). They are three independent tables and this was a
+        // `Promise.all`, so one of them failing 500'd the whole page — the user, their sessions and
+        // their devices all lost to whichever list would not read, on the pane a support agent opens
+        // when an account is already in trouble. Still concurrent: the guard is inside each arm.
+        const [sessions, devices, providers] = await Promise.all([
+          readBounded(() => listUserSessions(database, userId, MAX_PAGE_SIZE), sessionView),
+          readBounded(() => listUserDevices(database, userId, MAX_PAGE_SIZE), deviceView),
+          readWhole(() => userProviders(database, userId)),
+        ]);
+
+        await emitControlPlaneAction(c.var.emit, {
+          action: AuthAuditActions.adminUserRead,
+          subject: caller.subject,
+          connectionId: caller.connectionId,
+          resourceType: "user",
+          resourceId: userId,
+          ...context(c),
+          // `null` where a list did not read, never `0`. The trail is what answers "how much did this
+          // caller see", and a zero there is a claim that the user had none.
+          metadata: {
+            sessions: sessions.state === "read" ? sessions.items.length : null,
+            devices: devices.state === "read" ? devices.items.length : null,
+          },
+        });
+
+        return c.json({
+          user: userView(user),
+          providers,
+          sessions,
+          devices,
+        } satisfies AdminUserResponse);
+      },
+    );
+
+    app.get(
+      `${base}/admin/devices`,
+      requireControlPlane(AUTH_DEVICES_READ_SCOPE),
+      zValidator("query", ListDevicesQuery, validationHook),
+      async (c) => {
+        const query = c.req.valid("query");
+        const caller = controlPlaneCaller(c);
+        const page = await listDeviceRegistry(db(c, wiring), query);
+        await emitControlPlaneAction(c.var.emit, {
+          action: AuthAuditActions.adminDevicesListed,
+          subject: caller.subject,
+          connectionId: caller.connectionId,
+          resourceType: "device",
+          resourceId: query.userId ?? null,
+          ...context(c),
+          metadata: { returned: page.items.length, filteredByUser: query.userId !== undefined },
+        });
+        return c.json({
+          devices: page.items.map(deviceView),
+          nextCursor: page.nextCursor,
+        } satisfies AdminDevicesResponse);
+      },
+    );
+
+    app.post(
+      `${base}/admin/sessions/revoke`,
+      requireControlPlane(AUTH_SESSIONS_REVOKE_SCOPE),
+      zValidator("json", RevokeSessionBody, validationHook),
+      async (c) => {
+        const { sessionId } = c.req.valid("json");
+        const caller = controlPlaneCaller(c);
+        const session = await findSessionById(db(c, wiring), sessionId);
+
+        // Idempotent rather than a 404, so a retried job — the normal shape of automated incident
+        // response — lands on the state the caller meant instead of failing the second time. It also
+        // keeps this scope from answering "does this session exist" any more precisely than "did I
+        // revoke one", which matters because holding it confers no right to read the session at all.
+        const revoked = session ? await revokeTokens(c, wiring, [session.token]) : 0;
+
+        await emitControlPlaneAction(c.var.emit, {
+          action: AuthAuditActions.adminSessionRevoked,
+          subject: caller.subject,
+          connectionId: caller.connectionId,
+          resourceType: "session",
+          resourceId: sessionId,
+          ...context(c),
+          // The owning user reaches the trail, where it belongs, and not the response — the caller holds
+          // a revoke scope, which is not a license to learn whose session it was.
+          metadata: { revoked, userId: session?.userId ?? null },
+        });
+
+        return c.json({ revoked } satisfies AdminRevokeResponse);
+      },
+    );
+
+    app.post(
+      `${base}/admin/users/:userId/sessions/revoke`,
+      requireControlPlane(AUTH_USERS_LOGOUT_SCOPE),
+      zValidator("param", UserIdParam, validationHook),
+      async (c) => {
+        const { userId } = c.req.valid("param");
+        const caller = controlPlaneCaller(c);
+        const tokens = await userSessionTokens(db(c, wiring), userId);
+        const revoked = await revokeTokens(c, wiring, tokens);
+
+        await emitControlPlaneAction(c.var.emit, {
+          action: AuthAuditActions.adminUserSessionsRevoked,
+          subject: caller.subject,
+          connectionId: caller.connectionId,
+          resourceType: "user",
+          resourceId: userId,
+          ...context(c),
+          metadata: { revoked },
+        });
+
+        // No 404 for an unknown user, for the same two reasons as the single-session revoke: signing out
+        // somebody who is already signed out everywhere is a success, and this scope is not a read scope.
+        return c.json({ revoked } satisfies AdminRevokeResponse);
+      },
+    );
+
+    app.post(
+      `${base}/admin/users/:userId/devices/revoke`,
+      requireControlPlane(AUTH_DEVICES_REVOKE_SCOPE),
+      zValidator("param", UserIdParam, validationHook),
+      zValidator("json", RevokeDeviceBody, validationHook),
+      async (c) => {
+        const { userId } = c.req.valid("param");
+        const { deviceId } = c.req.valid("json");
+        const caller = controlPlaneCaller(c);
+        const database = db(c, wiring);
+
+        // Both halves are scoped to the named user, which is what the devices table's composite primary
+        // key exists for: a device id belonging to somebody else matches nothing here rather than
+        // revoking a stranger's phone.
+        const tokens = await deviceSessionTokens(database, userId, deviceId);
+        const revoked = await revokeTokens(c, wiring, tokens);
+        const removed = await deleteDevice(database, userId, deviceId);
+
+        await emitControlPlaneAction(c.var.emit, {
+          action: AuthAuditActions.adminDeviceRevoked,
+          subject: caller.subject,
+          connectionId: caller.connectionId,
+          resourceType: "device",
+          resourceId: deviceId,
+          ...context(c),
+          metadata: { userId, revoked, removed },
+        });
+
+        return c.json({ revoked, removed } satisfies AdminDeviceRevokeResponse);
+      },
+    );
+  };
+}

package/src/http/baseUrl.ts

@@ -0,0 +1,109 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type AmbientEnv, ambientEnv, compositionEnvironment } from "@pithy-sh/core/src/env/ambient";
+
+/**
+ * Where a composition's base URL comes from — and therefore what its session cookie is called, and
+ * which origin its CSRF gate calls its own.
+ *
+ * ## The shape, and the two that lost
+ *
+ * `baseURL` stays **one string, and it means the deployed origin**. A `dev` composition does not read
+ * it: it resolves its base URL from the host the request actually arrived on, over `http`.
+ *
+ * A per-environment record (`{ prod, staging, dev }`, the way a Worker's `domains` block reads) was the
+ * obvious shape and it fails on the one value it exists to hold. The dev port is assigned per Worker per
+ * run from the feature's reserved block, so `dev: "http://localhost:8787"` is wrong the moment a second
+ * Worker starts or that port is taken — and a record whose `dev` key must be left empty to be correct is
+ * a field that only ever holds a mistake.
+ *
+ * Resolving from the request is what survives that, because the request is the only thing that knows the
+ * port. It cannot be stale, it needs no cooperation from `pithy dev`, and nothing has to be written down.
+ *
+ * ## We run no TLS locally, so the scheme is a constant
+ *
+ * That is settled policy, and it is what makes the rest hold **by construction** rather than by comment.
+ * `devBaseURL` fixes the scheme and takes only the host; {@link sessionCookieName} reads only the scheme.
+ * So the part nobody can know ahead of time — the port — cannot reach the cookie name, and the part that
+ * decides the cookie name is a constant. The dev seed and the running composition agree because they are
+ * reading the same two lines, not because they were written on the same day.
+ *
+ * ## One gate, on the environment alone
+ *
+ * {@link baseURLResolver} contains the only environment test in this seam: one `if`, on
+ * `compositionEnvironment` and nothing else, and-ed and or-ed with nothing. Outside `dev` it returns the
+ * configured value verbatim for every request, so a staging or production Worker resolves exactly what it
+ * resolved before this module existed — and the same-origin set it builds is byte-identical, because the
+ * origin the gate adds is the origin the configured base URL already contributed.
+ *
+ * `undefined` — nothing stamped `ENVIRONMENT` — is not `dev`, which is `compositionEnvironment`'s own
+ * rule and the right one here too: a deployment whose `wrangler.jsonc` lost the var must not start
+ * trusting whatever host a request claims to have arrived at.
+ */
+
+/** The one environment whose base URL is derived from the request rather than read from config. */
+const DERIVED_ENVIRONMENT = "dev";
+
+/**
+ * The scheme every `dev` composition serves on.
+ *
+ * Not a default and not a guess: Pithy runs no TLS locally, so there is no second possibility to choose
+ * between. It is exported because the dev-session seed needs it to name the cookie it writes, and that
+ * agreement is the whole invariant.
+ */
+export const DEV_PROTOCOL = "http:";
+
+/** Better Auth's session cookie, before any prefix — `<cookiePrefix>.session_token`, prefix unchanged. */
+const SESSION_COOKIE = "better-auth.session_token";
+
+/**
+ * The base URL a `dev` composition resolves for a request that arrived at `host`.
+ *
+ * `host`, not `hostname`: the port is the whole point, and it is the part of a dev address that nobody
+ * can know before the run allocates it.
+ */
+export function devBaseURL(host: string): string {
+  return `${DEV_PROTOCOL}//${host}`;
+}
+
+/**
+ * A base URL's scheme, or `""` for a string that is not a URL at all.
+ *
+ * Tolerant rather than throwing, for the same reason the CSRF gate's `originOf` is: `baseURL` is a
+ * `z.string()` an adopter writes by hand, and a malformed one must fail as "no `__Secure-` prefix" —
+ * matching what Better Auth itself does with it — not as a 500 on every request.
+ */
+export function baseURLProtocol(baseURL: string): string {
+  try {
+    return new URL(baseURL).protocol;
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Better Auth's session cookie name for a base URL served over `protocol`.
+ *
+ * Our mirror of a rule that lives in Better Auth: it adds the `__Secure-` prefix when the base URL is
+ * HTTPS. Mirrored because the seed has to name the cookie before any instance exists, and pinned to the
+ * running version by a test that reads the name off a live instance — so an upgrade that changed the
+ * rule fails there rather than in a browser.
+ */
+export function sessionCookieName(protocol: string): string {
+  return protocol === "https:" ? `__Secure-${SESSION_COOKIE}` : SESSION_COOKIE;
+}
+
+/** Resolve the base URL this composition serves under, for one request. */
+export type ResolveBaseURL = (request: Request) => string;
+
+/**
+ * Build this composition's base-URL resolver. The environment is read once, here, and nowhere else in
+ * this seam.
+ */
+export function baseURLResolver(configured: string, env: AmbientEnv = ambientEnv()): ResolveBaseURL {
+  // The gate. Its own condition, on the environment alone — never folded into the per-request check,
+  // where a dev relaxation would be one edit away from applying in production.
+  if (compositionEnvironment(env) !== DERIVED_ENVIRONMENT) return () => configured;
+  return (request) => devBaseURL(new URL(request.url).host);
+}

package/src/http/csrf.ts

@@ -0,0 +1,98 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyMiddleware } from "@pithy-sh/core/src/capability/capability";
+import { type AmbientEnv, ambientEnv } from "@pithy-sh/core/src/env/ambient";
+import { ForbiddenError } from "@pithy-sh/core/src/error/pithyError";
+import type { SameOriginGate } from "@pithy-sh/core/src/http/sameOrigin";
+import type { AuthWiring } from "../capability";
+import { baseURLResolver, type ResolveBaseURL } from "./baseUrl";
+
+/**
+ * CSRF origin guard for every state-changing route in the Worker — Pithy's own (token rotation, device
+ * revoke) and the adopter's alike.
+ *
+ * Better Auth applies this check to its own endpoints; routes in front of the catch-all must enforce
+ * it themselves to honor principle 2 ("cookie/session mode ⇒ CSRF on"). Bearer requests carry no
+ * ambient credential, so they are CSRF-exempt and pass through. A cookie-authenticated request must
+ * present an `Origin` (or `Referer`) matching an allowed origin.
+ *
+ * ## Nothing here takes an origin list
+ *
+ * The gate used to be built by whoever needed it, from origins they passed in. Auth's own routes had
+ * the resolved ones; an adopter's routes did not — the `routes` hook receives only the Hono app — so
+ * the adopter wrote the check again from the request and hoped the two agreed. One Worker, two
+ * same-origin implementations, free to drift, and the weaker one is the real policy.
+ *
+ * Now the capability publishes the gate **already bound** to the origins it resolved, and core's
+ * `requireSameOrigin()` takes no argument. There is no list to pass, so there is no wrong list to
+ * pass — and no second implementation to keep in step.
+ */
+function originOf(value: string | null): string | null {
+  if (!value) return null;
+  try {
+    return new URL(value).origin;
+  } catch {
+    return null;
+  }
+}
+
+/** The origins a cookie-authenticated mutating request may come from: the base URL plus trustedOrigins. */
+function allowedOrigins(baseURL: string, trustedOrigins: readonly string[]): string[] {
+  const origins = new Set<string>(trustedOrigins);
+  const base = originOf(baseURL);
+  if (base) origins.add(base);
+  return [...origins];
+}
+
+/** The decision itself, closed over the one resolved origin set. Never exported: see the module doc. */
+function sameOriginGate(allowedOrigins: readonly string[], resolveBaseURL: ResolveBaseURL): SameOriginGate {
+  const allowed = new Set(allowedOrigins);
+  return async (c, next) => {
+    // A bearer request has no ambient credential to forge — CSRF-exempt.
+    if (c.req.raw.headers.has("authorization")) {
+      await next();
+      return;
+    }
+    const origin = c.req.raw.headers.get("origin") ?? originOf(c.req.raw.headers.get("referer"));
+    // The origin this composition is serving on, for this request. Outside `dev` it is the configured
+    // base URL's, which `allowedOrigins` already put in the set — so this adds nothing and production
+    // is byte-for-byte what it was. In `dev` it is the live local origin, which is the only correct
+    // answer when the port is assigned per Worker per run.
+    const own = originOf(resolveBaseURL(c.req.raw));
+    if (!origin || (origin !== own && !allowed.has(origin))) {
+      throw new ForbiddenError({
+        message: "Cross-origin request rejected.",
+        action: "Send the request from an allowed origin, or use a bearer token.",
+        detail: `origin ${origin ?? "(none)"} is not in trustedOrigins`,
+      });
+    }
+    await next();
+  };
+}
+
+/**
+ * Publish the bound gate on every request, as capability middleware.
+ *
+ * The configured origin set is built once at composition: it is resolved config, and re-deriving it on
+ * the hot path is work that can only ever produce the same answer — or a different one, which is the
+ * bug. The composition's *own* origin is the one part that is not config, and only in `dev`: it is the
+ * address this run was assigned, which no config file can hold. So the resolver is built here, at
+ * composition, with the environment gate inside it ({@link baseURLResolver}), and the gate it hands
+ * back is a constant everywhere but `dev`.
+ *
+ * Registered on `*` rather than under `basePath`, because the routes that most need it are the
+ * adopter's, and those are anywhere.
+ */
+export function publishSameOrigin(wiring: AuthWiring, env: AmbientEnv = ambientEnv()): PithyMiddleware {
+  const gate = sameOriginGate(
+    allowedOrigins(wiring.config.baseURL, wiring.config.trustedOrigins),
+    baseURLResolver(wiring.config.baseURL, env),
+  );
+  return (app) => {
+    app.use("*", async (c, next) => {
+      c.set("sameOrigin", gate);
+      await next();
+    });
+  };
+}