@pithy-sh/auth 0.1.0

package/src/http/devLoginRoute.ts

@@ -0,0 +1,159 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { JsonDate } from "@pithy-sh/core/src/data/codecs";
+import { type AmbientEnv, ambientEnv, compositionEnvironment } from "@pithy-sh/core/src/env/ambient";
+import { isContinuousIntegration } from "@pithy-sh/core/src/env/ci";
+import { fromZodError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import { DEV_LOGIN_ROUTE } from "@pithy-sh/core/src/seed/devLogin";
+import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
+import type { Context, Hono } from "hono";
+import { z } from "zod";
+import type { AuthWiring } from "../capability";
+import { authDatabase } from "../data/tables";
+import { resolveSessionSecret } from "../instance/secrets";
+import {
+  DEV_SESSION_COOKIE_NAME,
+  DEV_SESSION_TOKEN_PREFIX,
+  secretFingerprint,
+  signCookieValue,
+} from "../seeds/devSession";
+import { resolveDb } from "./resolve";
+
+/**
+ * `GET /__pithy/dev-login` — the seeded session, as a redirect that signs the browser in.
+ *
+ * The seed already mints a real session row and a real signed cookie. What was missing was a way to
+ * *hand it to a browser*: the artifact is a file, and the only route to a browser from a file was the
+ * terminal — `document.cookie = "…"`, printed on the ready banner, pasted into a console. That line put
+ * a live session token in the one place a credential must never be, which is a place people read, copy,
+ * screenshot, and tee into a log. A URL carries the same credential to the same browser without it ever
+ * being rendered as text.
+ *
+ * ## The two gates, and why they are two statements
+ *
+ * This route mints an authenticated session with **no credential presented**. That is the entire risk of
+ * the feature, so it is refused twice, independently:
+ *
+ * 1. The composition's environment is not `dev`.
+ * 2. `CI` is set to any non-blank value — even in a `dev` composition.
+ *
+ * Neither implies the other. CI runs `dev` compositions constantly (integration suites, packaging
+ * checks, `pithy dev` itself), and a developer's laptop is not CI, so "not `dev`" does not cover CI and
+ * "not CI" does not cover production. Written as one `||` the pair reads like a single condition, and a
+ * single condition is one edit from an `&&` — with a session-minting endpoint answering as the failure
+ * mode, silently. Two `if`s, two comments, two tests.
+ *
+ * ## And the gates are at registration
+ *
+ * Not inside the handler. A route that exists and refuses is one refactor away from a route that exists
+ * and does not, and it is visible in the route table of a production Worker, where its presence alone is
+ * a finding. The assertion the tests make is therefore about what a composition *mounts*.
+ *
+ * **What the CI gate can and cannot see.** In a Worker, `process.env` is the script's bindings and
+ * nothing else — the shell's `CI` does not cross into workerd. `pithy dev` forwards it as a var for
+ * exactly this reason, so the read is truthful for every Worker Pithy starts; a Worker started some
+ * other way in CI is covered only by the environment gate. That is why there are two, and why the
+ * second is the one that needs no cooperation.
+ */
+export function registerDevLoginRoute(
+  wiring: AuthWiring,
+  env: AmbientEnv = ambientEnv(),
+): (app: Hono<PithyHonoEnv>) => void {
+  return (app) => {
+    // Gate one: the composition's environment. `undefined` — nothing stamped `ENVIRONMENT` — is not `dev`.
+    if (compositionEnvironment(env) !== "dev") return;
+    // Gate two: continuous integration, independently. A `dev` composition in CI gets no route either.
+    if (isContinuousIntegration(env)) return;
+    app.get(DEV_LOGIN_ROUTE, (c) => serveDevLogin(c, wiring));
+  };
+}
+
+/**
+ * The seeded session row, narrowed to what handing it to a browser needs — and validated, because a D1
+ * row is a boundary like any other. `z.input` is the stored row (ISO-8601 text); `z.output` the app shape.
+ */
+const DevSessionRow = z
+  .object({
+    token: z
+      .string()
+      .min(1)
+      .describe("The seeded session's opaque token — signed with this environment's secret to make the cookie."),
+    expiresAt: JsonDate.describe("When the seeded session expires. ISO-8601 text in SQLite; a `Date` here."),
+  })
+  .describe("A seeded dev session, narrowed to the two columns the dev-login redirect needs.");
+type DevSessionRow = z.output<typeof DevSessionRow>;
+
+/** How long the browser is told to keep the cookie: whatever is left of the seeded session, never longer. */
+function maxAgeSeconds(expiresAt: Date, now: Date): number {
+  return Math.floor((expiresAt.getTime() - now.getTime()) / 1000);
+}
+
+/**
+ * The refusal when there is nothing to sign in as. A 404, because the honest answer is that this
+ * composition has no seeded session — not that the caller got something wrong.
+ *
+ * It names `pithy seed` because that is the command that mints one, and it carries no detail about what
+ * was searched for: the search key is derived from the signing secret.
+ *
+ * **In `message`, not in `action` (#344).** `action` is the operator's field and the HTTP codec strips it,
+ * because on every other route the caller is somebody who must not be handed a `pithy` command. This route
+ * is the exception the gates above already make: it registers only in a `dev` composition outside CI, so
+ * the browser at the other end is the developer's own. That is a decision one route makes in the open,
+ * which is the opposite of a field nobody classified carrying it everywhere.
+ */
+function noSeededSession(): NotFoundError {
+  return new NotFoundError({
+    message: "No dev login has been seeded for this environment. Run pithy seed, then open this URL again.",
+  });
+}
+
+/**
+ * Serve the seeded session as a `Set-Cookie` and a redirect to `/`.
+ *
+ * The row is found by the prefix every seeded session carries and **verified against the current
+ * signing secret's fingerprint**, which the seed puts in the token for this exact purpose. A session
+ * minted before a rotation is a cookie Better Auth will reject, so handing it over would sign nobody in
+ * and send the developer hunting through auth for a bug that is a stale seed. Unfound is unfound.
+ *
+ * Nothing about the cookie is logged, and nothing is written to a response body: the value exists in
+ * this handler and in the browser, and in no third place.
+ */
+async function serveDevLogin(c: Context<PithyHonoEnv>, wiring: AuthWiring): Promise<Response> {
+  const secret = await resolveSessionSecret(c.env as unknown as SecretsStoreEnv);
+  const fingerprint = await secretFingerprint(secret);
+
+  const db = authDatabase(resolveDb(c.env, wiring.config.database));
+  const found = await db
+    .selectFrom("pithyAuthSessions")
+    .select(["token", "expiresAt"])
+    .where("token", "like", `${DEV_SESSION_TOKEN_PREFIX}%-${fingerprint}`)
+    .orderBy("createdAt", "desc")
+    .limit(1)
+    .executeTakeFirst();
+  if (!found) throw noSeededSession();
+
+  const parsed = DevSessionRow.safeParse(found);
+  if (!parsed.success) {
+    throw fromZodError(parsed.error, {
+      // Same reason as `noSeededSession`: this route's caller is the developer who can run the command.
+      message: "The seeded dev session is not readable. Run pithy seed to mint a fresh one.",
+    });
+  }
+  const row: DevSessionRow = parsed.data;
+  const maxAge = maxAgeSeconds(row.expiresAt, new Date());
+  // An expired session is worse than none: the cookie looks like a way in and fails silently in the
+  // browser. Same answer, same action — reseeding is what fixes both.
+  if (maxAge <= 0) throw noSeededSession();
+
+  const value = await signCookieValue(row.token, secret);
+  // The attributes Better Auth's own session cookie carries in a `dev` composition: `HttpOnly` (a
+  // session token has no business in `document.cookie`, which is also the habit this route retires),
+  // `SameSite=Lax`, root path. No `Secure` — a `dev` base URL is `http://localhost`, and a `Secure`
+  // cookie there is one the browser accepts and never sends back.
+  const cookie = `${DEV_SESSION_COOKIE_NAME}=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAge}`;
+  // 302 to the app root rather than 200 with a page: the developer asked to be signed in, not to read a
+  // confirmation, and a redirect leaves the address bar on the app instead of on this route.
+  return c.body(null, 302, { "Set-Cookie": cookie, Location: "/" });
+}

package/src/http/errors.ts

@@ -0,0 +1,70 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import {
+  ConflictError,
+  ForbiddenError,
+  InternalError,
+  NotFoundError,
+  PithyError,
+  RateLimitError,
+  UnauthorizedError,
+  ValidationError,
+} from "@pithy-sh/core/src/error/pithyError";
+import { isAPIError } from "better-auth/api";
+
+/**
+ * Translate a thrown Better-Auth `APIError` into the matching `PithyError` subclass, by HTTP status.
+ *
+ * **What reaches here is a much smaller set than `onAPIError: { throw: true }` suggests.** That option
+ * reads as though every endpoint's `APIError` bubbles to the Hono boundary, and none of them do:
+ * better-auth's `onError` re-raises (`better-auth/dist/api/index.mjs:193`) straight into better-call's
+ * own catch (`better-call@1.4.0`, `dist/router.mjs:83-89`), which renders an `APIError` as a Response
+ * and returns it. An endpoint refusal is therefore an ordinary non-2xx answer, and `handleBetterAuth`
+ * hands it back untouched (#449).
+ *
+ * What still arrives is what better-call declined to handle: a non-`APIError` throw from an endpoint
+ * (`throw error` at `router.mjs:88` — a database failure, a genuine bug), and a throw from a plugin's
+ * `onRequest` hook, which runs outside the router's try. The `isAPIError` branch is kept for those,
+ * which can carry one, and because a caller other than the delegating route may hand this anything.
+ *
+ * The shape, when it is one: `{ statusCode, status, message, body: { message, code } }`. We re-home it
+ * in the one `PithyError` family so the HTTP codec owns the response shape and strips `detail`. For 4xx the
+ * Better-Auth message is user-actionable and safe to surface (it never reveals account existence —
+ * sign-up is silently no-op'd for unknown users); 5xx gets a generic public message. The Better-Auth
+ * status + error code stay in `detail` (logs/audit only, never the client).
+ */
+export function apiErrorToPithy(error: unknown): PithyError {
+  if (error instanceof PithyError) return error;
+  if (!isAPIError(error)) {
+    return new InternalError({
+      message: "Authentication failed.",
+      detail: error instanceof Error ? error.message : String(error),
+    });
+  }
+  const e = error as {
+    statusCode?: number;
+    status?: unknown;
+    message?: string;
+    body?: { message?: string; code?: string };
+  };
+  const status = typeof e.statusCode === "number" ? e.statusCode : 500;
+  const publicMessage = e.body?.message ?? e.message ?? "Authentication failed.";
+  const detail = `better-auth ${String(e.status)}${e.body?.code ? ` ${e.body.code}` : ""}: ${e.message ?? ""}`.trim();
+  switch (status) {
+    case 400:
+      return new ValidationError({ message: publicMessage, detail });
+    case 401:
+      return new UnauthorizedError({ message: publicMessage, detail });
+    case 403:
+      return new ForbiddenError({ message: publicMessage, detail });
+    case 404:
+      return new NotFoundError({ message: publicMessage, detail });
+    case 409:
+      return new ConflictError({ message: publicMessage, detail });
+    case 429:
+      return new RateLimitError({ message: publicMessage, detail });
+    default:
+      return new InternalError({ message: "Authentication failed.", detail });
+  }
+}

package/src/http/guards.ts

@@ -0,0 +1,158 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { AdminRoute } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
+import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
+
+/**
+ * Auth's control-plane scopes, and the admin surface a manifest advertises.
+ *
+ * ## The gate is core's; auth contributes only the scope names
+ *
+ * `requireControlPlane` lives in `@pithy-sh/core/src/controlPlane/http/guard` and every admin route
+ * wears it directly. Auth verifies nothing itself: a management call arrives as an EdDSA-signed compact
+ * JWS on the `pithy-control-plane` header, and the seam checks the signature against a public key the
+ * **adopter** registered, the connection it addresses, that connection's environment, the token's
+ * lifetime, a digest of the body, and the token's single use.
+ *
+ * Importing that gate is not the opposite of `requireAuth` being copied into every other capability; it
+ * is the same rule. The rule is never to import authorization from a package that might be absent.
+ * `@pithy-sh/core` is a hard dependency of every capability there is, and with the seam *uncomposed*
+ * the imported gate raises `controlplane/not_connected` rather than passing. Both halves fail closed.
+ *
+ * ## `requireAuth()` must never appear on one of these routes
+ *
+ * This is the sharpest edge in this package, because auth is the capability that *implements*
+ * `requireAuth`. A management client is not a user of the adopter's app: it holds no session, owns no
+ * user row, and the seam deliberately leaves `c.var.auth` null so a control-plane credential cannot
+ * satisfy an ordinary `requireAuth()` anywhere in the tree. An auth gate on an admin route would deny
+ * every legitimate management call, permanently, and **no credential could fix it** — there is no user
+ * to sign in as. `controlPlaneIsolation.workers.test.ts` pins both directions of that separation.
+ *
+ * ## Five scopes, because these are five different blast radii
+ *
+ * The temptation is one `auth:admin` flag, and on this capability it is the most dangerous version of
+ * that mistake. **Reading a user is a privacy operation; revoking their sessions is an availability
+ * one.** A support tool that looks people up should never be able to sign the whole customer base out,
+ * and an incident-response tool that kills a stolen session has no business reading every address in
+ * the user table. `scopeCovers` matches exactly, with no prefix or wildcard rule, so holding one of
+ * these confers nothing whatever about the others — `auth:users` grants none of them.
+ *
+ * The split within *reads* is between one user and the fleet: `auth:users:read` answers "who is this
+ * person", while `auth:devices:read` walks every device of every user, which is a different question
+ * with a much larger answer. The split within *writes* is by blast radius: one session, one device, or
+ * every session a person has.
+ *
+ * The names are constants rather than config. A configurable scope name is a way to misconfigure a
+ * default-denied gate into a differently-named one, and tooling that read the docs would then hold a
+ * scope nothing checks. They are also the join key with what `pithy dashboard connect` offers an
+ * adopter to grant, so they must be the same strings in both places.
+ *
+ * ## There is no impersonation scope, and its absence is deliberate
+ *
+ * "Sign in as this user" is the most dangerous administrative capability there is: it produces a
+ * credential indistinguishable from the user's own, so every action taken with it reads in the trail as
+ * theirs. It is excluded from this surface on purpose and is not reachable by composing what is here —
+ * nothing below mints a session, and the read routes never project a session token. If it is ever
+ * built it gets its own design and its own security review, not a scope added to this list.
+ */
+
+/**
+ * Look a user up and read their account: the listing, the search, and one user with their sessions and
+ * devices. The privacy-bearing read — it returns email addresses, IPs, and user agents — and by far the
+ * most commonly granted, because nearly every dashboard pane resolves to a user.
+ */
+export const AUTH_USERS_READ_SCOPE: ControlPlaneScope = "auth:users:read";
+
+/**
+ * Walk the device registry across every user. Separate from reading one user because the question is
+ * different in kind: this is fleet-wide, and answers "what is signing in to this product" rather than
+ * "what does this person use".
+ */
+export const AUTH_DEVICES_READ_SCOPE: ControlPlaneScope = "auth:devices:read";
+
+/**
+ * Revoke one named session. The targeted write — what an incident-response tool needs to kill a stolen
+ * token, and nothing more. Granting it confers no ability to read who the session belongs to.
+ */
+export const AUTH_SESSIONS_REVOKE_SCOPE: ControlPlaneScope = "auth:sessions:revoke";
+
+/**
+ * Sign one user out everywhere: every session on every device, at once. The most disruptive thing on
+ * this surface — the person is signed out of the product mid-use with no warning — which is exactly why
+ * it is granted separately from revoking a single session.
+ */
+export const AUTH_USERS_LOGOUT_SCOPE: ControlPlaneScope = "auth:users:logout";
+
+/**
+ * Sign one of a user's devices out and drop its registration, so it must register again at next
+ * sign-in. The admin counterpart of the user's own `POST /devices/revoke`, for a phone somebody
+ * reported lost — and destructive in a way the session revokes are not, because the device row and its
+ * push token go with it.
+ */
+export const AUTH_DEVICES_REVOKE_SCOPE: ControlPlaneScope = "auth:devices:revoke";
+
+/**
+ * Every control-plane scope auth defines — what `pithy dashboard connect` offers for this capability,
+ * and the list a manifest or a doc quotes rather than re-typing.
+ */
+export const AUTH_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[] = [
+  AUTH_USERS_READ_SCOPE,
+  AUTH_DEVICES_READ_SCOPE,
+  AUTH_SESSIONS_REVOKE_SCOPE,
+  AUTH_USERS_LOGOUT_SCOPE,
+  AUTH_DEVICES_REVOKE_SCOPE,
+];
+
+/**
+ * Auth's management surface, as `GET /control-plane/manifest` reports it.
+ *
+ * Declared beside the scopes rather than in `adminRoutes.ts`, so the scope a route demands and the
+ * scope a manifest advertises are the same constant read from one place. `basePath` is a parameter and
+ * never a default: an adopter who mounted auth at `/identity` must get a manifest naming
+ * `/identity/admin/users`, or a management client composing its calls from the manifest would 404
+ * against exactly the adopters who customized anything.
+ *
+ * The summaries say what the operation is *for*. A client renders these next to a button somebody is
+ * about to press on a real person's account.
+ */
+export function authAdminRoutes(basePath: string): AdminRoute[] {
+  return [
+    {
+      method: "GET",
+      path: `${basePath}/admin/users`,
+      scope: AUTH_USERS_READ_SCOPE,
+      summary: "Find a user. Lists everyone newest first, or searches email and display name.",
+    },
+    {
+      method: "GET",
+      path: `${basePath}/admin/users/:userId`,
+      scope: AUTH_USERS_READ_SCOPE,
+      summary: "One user, with where they are signed in and what they sign in with.",
+    },
+    {
+      method: "GET",
+      path: `${basePath}/admin/devices`,
+      scope: AUTH_DEVICES_READ_SCOPE,
+      summary: "The device registry across users, most-recently-seen first.",
+    },
+    {
+      method: "POST",
+      path: `${basePath}/admin/sessions/revoke`,
+      scope: AUTH_SESSIONS_REVOKE_SCOPE,
+      summary: "Kill one session. The rest of that person's sign-ins keep working.",
+    },
+    {
+      method: "POST",
+      path: `${basePath}/admin/users/:userId/sessions/revoke`,
+      scope: AUTH_USERS_LOGOUT_SCOPE,
+      summary: "Sign a user out everywhere, on every device, immediately.",
+    },
+    {
+      method: "POST",
+      path: `${basePath}/admin/users/:userId/devices/revoke`,
+      scope: AUTH_DEVICES_REVOKE_SCOPE,
+      summary: "Sign one device out and forget it — for a phone reported lost.",
+    },
+  ];
+}

package/src/http/middleware.ts

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyHonoEnv, PithyMiddleware } from "@pithy-sh/core/src/capability/capability";
+import { UnauthorizedError } from "@pithy-sh/core/src/error/pithyError";
+import { AuthContext } from "@pithy-sh/core/src/http/authContext";
+import { isLocale } from "@pithy-sh/core/src/i18n/locale";
+import type { MiddlewareHandler } from "hono";
+import type { AuthWiring } from "../capability";
+import { getAuthInstance } from "./resolve";
+
+/**
+ * The session-resolution middleware: it fills core's `AuthContext` seam (`c.var.auth`) for every
+ * request that carries a credential — a bearer token or a session cookie. Better Auth resolves both
+ * transparently (the bearer plugin rewrites the header into the session cookie), so one `getSession`
+ * call covers mobile and web. A credential-less request stays anonymous (no instance build, no D1 hit).
+ * Resolution never throws — an invalid credential simply leaves `auth` null for `requireAuth` to reject.
+ */
+export function createSessionMiddleware(wiring: AuthWiring): PithyMiddleware {
+  return (app) => {
+    app.use("*", async (c, next) => {
+      const headers = c.req.raw.headers;
+      if (headers.has("authorization") || headers.has("cookie")) {
+        try {
+          const instance = await getAuthInstance(c, wiring);
+          const session = await instance.api.getSession({ headers });
+          if (session) {
+            // `locale` comes off the user row the session lookup already loaded, so publishing it
+            // costs nothing — and it is the `user` link of `@pithy-sh/i18n`'s server chain, the one
+            // that makes a reader's stored choice outrank their device's `Accept-Language`. Read
+            // through `AuthContext.parse`, so a column holding something that is not a tag lands as
+            // `undefined` rather than reaching `Intl`.
+            const stored = (session.user as { locale?: unknown }).locale;
+            c.set(
+              "auth",
+              AuthContext.parse({
+                userId: session.user.id,
+                sessionId: session.session.id,
+                scopes: [],
+                locale: typeof stored === "string" && isLocale(stored) ? stored : null,
+              }),
+            );
+          }
+        } catch {
+          // Leave `auth` null; the credential was missing/invalid.
+        }
+      }
+      await next();
+    });
+  };
+}
+
+/**
+ * The gate other capabilities stack on a protected route. Rejects a request whose `AuthContext` was
+ * not filled (no valid credential) with a `PithyError` `auth/invalid_token` (401).
+ */
+export function requireAuth(): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    if (!c.var.auth) {
+      throw new UnauthorizedError({
+        message: "Authentication required.",
+        action: "Sign in and retry with a valid session or bearer token.",
+      });
+    }
+    await next();
+  };
+}

package/src/http/rateLimit.ts

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { RateLimitError } from "@pithy-sh/core/src/error/pithyError";
+import type { MiddlewareHandler } from "hono";
+
+/**
+ * Tier 1 of two: the coarse edge rate limiter.
+ *
+ * Cloudflare's native Workers Rate Limiting binding caps requests per client IP at the edge with no
+ * storage round-trip — blunting floods and credential-stuffing before they reach Better Auth's
+ * per-action D1 limiter (tier 2: the 5/min magic-link and 3/min OTP caps, keyed per identity). Two
+ * limiters, two jobs: this one is a cheap per-IP flood guard across every auth route; tier 2 is the
+ * fine-grained per-action cap.
+ *
+ * Keys on `cf-connecting-ip`. The limit and window are set on the binding in `wrangler.jsonc`, not
+ * here. Skips only when the binding is absent (local dev / tests) — in a real deployment the binding is
+ * a required binding, enforced at compose.
+ */
+export function createRateLimitMiddleware(bindingName: string): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    const limiter = (c.env as Record<string, unknown>)[bindingName] as RateLimit | undefined;
+    if (limiter && typeof limiter.limit === "function") {
+      const key = c.req.raw.headers.get("cf-connecting-ip") ?? "anonymous";
+      const { success } = await limiter.limit({ key });
+      if (!success) {
+        throw new RateLimitError({
+          message: "Too many requests.",
+          action: "Slow down and retry in a moment.",
+        });
+      }
+    }
+    await next();
+  };
+}

package/src/http/resolve.ts

@@ -0,0 +1,152 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { EmailEnqueueEnv } from "@pithy-sh/email/src/capability";
+import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
+import type { Context } from "hono";
+import type { AuthWiring } from "../capability";
+import { authDatabase } from "../data/tables";
+import { makeSendAuthEmail, type ResolveRecipientLocale } from "../email/send";
+import { type AuthInstance, makeAuth } from "../instance/auth";
+import { resolveProvider } from "../instance/providers";
+import {
+  resolveAppleCredentials,
+  resolveFacebookCredentials,
+  resolveGithubCredentials,
+  resolveGoogleCredentials,
+  resolveSessionSecret,
+} from "../instance/secrets";
+import { baseURLResolver } from "./baseUrl";
+
+/**
+ * Build the Better-Auth instance for one request, memoized on the request context so the
+ * session-resolving middleware and the route handler share a single instance (one secret resolution,
+ * one construction). The instance closes over request-scoped state: the audit `emit` seam and the D1
+ * binding from `c.env`.
+ */
+const cache = new WeakMap<object, Promise<AuthInstance>>();
+
+type AuthEnv = SecretsStoreEnv & EmailEnqueueEnv;
+
+/** Read the configured D1 binding by name from the worker env, or fail loudly (not a silent undefined). */
+export function resolveDb(env: Record<string, unknown>, bindingName: string): D1Database {
+  const binding = env[bindingName];
+  if (!binding) {
+    throw new InternalError({
+      message: "The auth database binding is missing.",
+      detail: `D1 binding "${bindingName}" is not present on the worker env`,
+    });
+  }
+  return binding as D1Database;
+}
+
+/**
+ * The language to write a sign-in email in, for one address.
+ *
+ * **The stored preference first, the request's negotiation second** (pithy-sh/pithy#441). Somebody who
+ * picked a language in a settings pane has said something durable about themselves; the device they are
+ * signing in from tonight has only sent an `Accept-Language`. But most of what this is asked about is a
+ * *first* sign-in, where no row exists yet — and that is precisely the message a project cannot afford
+ * to send in the wrong language, because passwordless has no password to fall back to. So the header's
+ * answer, which `@pithy-sh/i18n` has already matched against this project's supported set and put on
+ * `c.var.locale`, is what covers that case.
+ *
+ * One indexed lookup on a unique column, per sign-in email, and only for the two templates that send
+ * one. `null` when neither answers, which renders the kit's English — not the same statement as `en`.
+ *
+ * `c.var.locale` is null unless the i18n capability is composed, so a project that never opted in gets
+ * a resolver that reads a column nobody fills and returns null: the behavior it had before any of this.
+ */
+function recipientLocale(c: Context<PithyHonoEnv>, db: ReturnType<typeof authDatabase>): ResolveRecipientLocale {
+  return async (email) => {
+    const row = await db.selectFrom("pithyAuthUsers").select("locale").where("email", "=", email).executeTakeFirst();
+    return row?.locale ?? c.var.locale?.catalogLocale ?? null;
+  };
+}
+
+export function getAuthInstance(c: Context<PithyHonoEnv>, wiring: AuthWiring): Promise<AuthInstance> {
+  const existing = cache.get(c);
+  if (existing) return existing;
+  const built = buildAuthInstance(c, wiring);
+  cache.set(c, built);
+  return built;
+}
+
+async function buildAuthInstance(c: Context<PithyHonoEnv>, wiring: AuthWiring): Promise<AuthInstance> {
+  const cfg = wiring.config;
+  const enqueueEmail = wiring.enqueueEmail;
+  if (!enqueueEmail) {
+    throw new InternalError({
+      message: "Authentication is misconfigured.",
+      detail: "auth.compose did not resolve the email enqueue seam; ensure email() is composed.",
+    });
+  }
+  const env = c.env as unknown as AuthEnv;
+  // Secret resolutions hit the same per-invocation cache; run them concurrently. Five reads, and they
+  // are not alike — which is the whole of #381.
+  //
+  // `resolveSessionSecret` is what an auth instance *is*: nothing signs a session without it, so its
+  // failure stays a precondition and still fails this call. `resolveDb` below is the same. A provider
+  // credential is one sign-in method among several, and it used to sit in this list as an equal — so a
+  // single unreadable `auth-github-credentials` rejected the whole `Promise.all` and every magic-link
+  // and OTP caller in the deployment got the secrets reader's own refusal instead of a sign-in:
+  // measured, `404 secrets/not_found`, message `Secret 'auth-github-credentials' is declared but not
+  // provisioned.` So the old behavior named the secret loudly and named it to *the browser*, on a
+  // route that has nothing to do with GitHub. Both halves of that are fixed here.
+  //
+  // `resolveProvider` catches per provider and hands back a state rather than a rejection, so this
+  // `Promise.all` settles whenever the session secret does. What the instance then lacks is one
+  // provider, and `makeAuth`'s `before` hook answers a caller who asks for it — see `instance/providers.ts`.
+  //
+  // A held failure belongs to its own secret (#170), so an unreadable provider credential does not
+  // disturb the session secret's own read, and a *disabled* provider never calls `.get()` at all.
+  const [secret, google, apple, facebook, github] = await Promise.all([
+    resolveSessionSecret(env),
+    resolveProvider(cfg.google.enabled, () => resolveGoogleCredentials(env)),
+    resolveProvider(cfg.apple.enabled, () => resolveAppleCredentials(env)),
+    resolveProvider(cfg.facebook.enabled, () => resolveFacebookCredentials(env)),
+    resolveProvider(cfg.github.enabled, () => resolveGithubCredentials(env)),
+  ]);
+  const expiresMinutes = Math.max(1, Math.round(cfg.verificationExpiresIn / 60));
+  return makeAuth({
+    db: authDatabase(resolveDb(c.env, cfg.database)),
+    secret,
+    // Never `cfg.baseURL` directly. The instance derives the session cookie's name, the OAuth callback
+    // URLs, and the magic-link URL from whatever base URL it is handed, so in a `dev` composition every
+    // one of those has to name the address this run is actually serving on — not the production origin
+    // the config records. The gate lives in `baseURLResolver` and nowhere else; outside `dev` this is
+    // `cfg.baseURL`, unchanged. Resolved here because the instance is itself built per request.
+    baseURL: baseURLResolver(cfg.baseURL)(c.req.raw),
+    // The language this request negotiated, for the translator plugin. `c.var.locale` is the project's
+    // own chain already resolved — never a second negotiation of Better Auth's, which would let the
+    // screens and the refusals disagree about who is reading (#452). `null` when nothing negotiated,
+    // which is every project that does not compose `i18n`, and which means English.
+    locale: c.var.locale?.catalogLocale ?? null,
+    basePath: cfg.basePath,
+    trustedOrigins: cfg.trustedOrigins,
+    google,
+    apple,
+    facebook,
+    github,
+    sendEmail: makeSendAuthEmail(
+      (input) => enqueueEmail(env, input),
+      expiresMinutes,
+      recipientLocale(c, authDatabase(resolveDb(c.env, cfg.database))),
+    ),
+    sessionExpiresIn: cfg.sessionExpiresIn,
+    sessionUpdateAge: cfg.sessionUpdateAge,
+    verificationExpiresIn: cfg.verificationExpiresIn,
+    otpLength: cfg.otpLength,
+    disableSignUp: cfg.disableSignUp,
+    // Read the emit seam lazily so a later-composed audit capability is honored regardless of the
+    // capability order (the instance may be built before audit's middleware runs).
+    emit: (event) => c.var.emit(event),
+    // The adopter's additional Better Auth plugins, exactly as `auth({ plugins: [...] })` declared them
+    // and already checked for additivity at `auth()` call time. The same list the derived migrations
+    // were built from — the routes a plugin serves and the tables it needs come from one declaration.
+    plugins: cfg.plugins,
+  });
+}