@pithy-sh/auth 0.1.0

package/src/http/views.ts

@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Session, User } from "../data/betterAuth";
+import type { Device } from "../data/device";
+import type { AdminDeviceView, AdminSessionView, AdminUserView } from "./responses";
+
+/**
+ * The admin projections — what a management client is shown of a user, a session, and a device.
+ *
+ * **No handler returns a row.** Each function below states what leaves the Worker, and each return
+ * type is `z.output` of the matching object in `responses.ts`, so the shape a client validates
+ * against and the shape this produces are one declaration. Adding a field to one and not the other
+ * does not compile.
+ *
+ * Separated from `adminRoutes.ts` so they can be exercised without a request, a scope, or a
+ * credential: `responses.test.ts` runs each against a fully populated row and compares the result
+ * with its schema. A leak here is a leak in every pane, and it should not need a Workers pool to
+ * catch.
+ */
+
+/**
+ * The user projection.
+ *
+ * Email and display name are personal data and they are here on purpose: identifying the right person
+ * is the entire job of a support pane, and `auth:users:read` is precisely the grant an adopter makes
+ * when they accept that. Nothing else on `pithy_auth_users` is withheld because nothing else on it is
+ * sensitive — the table holds no credential at all, which is what passwordless-only buys.
+ *
+ * `locale` is projected for the same reason: a support pane answering "why is this person getting
+ * English emails" needs to see whether they ever chose, and null — never chosen — is the answer half
+ * the time. It is a preference, not a credential.
+ */
+export function userView(user: User): AdminUserView {
+  return {
+    id: user.id,
+    email: user.email,
+    name: user.name,
+    emailVerified: user.emailVerified,
+    image: user.image,
+    locale: user.locale,
+    createdAt: user.createdAt.toISOString(),
+    updatedAt: user.updatedAt.toISOString(),
+  };
+}
+
+/**
+ * The session projection — **without the token**.
+ *
+ * The token *is* the credential: a bearer of it is the user, everywhere, until it expires. Projecting
+ * it would turn a read scope into silent impersonation and would leave no trace distinguishable from
+ * the person's own activity, which is exactly the capability this surface refuses to offer. The `id` is
+ * the handle instead, and it is what `POST /admin/sessions/revoke` accepts.
+ *
+ * `familyId` is dropped too — it is internal rotation bookkeeping, and a pane that rendered it would
+ * invite somebody to act on a correlation the model does not promise to keep stable.
+ *
+ * The IP and user-agent stay: "where is this person signed in from" is the question the pane exists to
+ * answer, and it is the one that catches a stolen session.
+ */
+export function sessionView(session: Session): AdminSessionView {
+  return {
+    id: session.id,
+    deviceId: session.deviceId,
+    ipAddress: session.ipAddress,
+    userAgent: session.userAgent,
+    createdAt: session.createdAt.toISOString(),
+    updatedAt: session.updatedAt.toISOString(),
+    expiresAt: session.expiresAt.toISOString(),
+  };
+}
+
+/**
+ * The device projection — **without the push token**.
+ *
+ * An APNs/FCM token is the capability to put a notification on somebody's lock screen. It is a
+ * credential, it is useless to a dashboard, and a management client that held one could message an
+ * adopter's users under the adopter's own app identity. It never leaves the Worker.
+ */
+export function deviceView(device: Device): AdminDeviceView {
+  return {
+    id: device.id,
+    userId: device.userId,
+    platform: device.platform,
+    name: device.name,
+    model: device.model,
+    osVersion: device.osVersion,
+    appVersion: device.appVersion,
+    lastIp: device.lastIp,
+    lastSeenAt: device.lastSeenAt.toISOString(),
+    createdAt: device.createdAt.toISOString(),
+  };
+}

package/src/i18n/errorCopy.es.ts

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//
+// LOCALE es — an unreviewed first pass. Not American English by design.
+
+/**
+ * What this kit says in Spanish that `@better-auth/i18n` does not (#452).
+ *
+ * **Only the gaps, and only the ones a reader meets.** The plugin ships 22 languages of its own, and
+ * they are maintained upstream — copying them here would fork every one of them on the day it landed.
+ * This layers over its `es`, which covers 34 of the 52 codes the kit's composed plugin set can raise.
+ *
+ * The three that matter most were among the missing: `INVALID_OTP`, `OTP_EXPIRED` and
+ * `TOO_MANY_ATTEMPTS` are the whole of `emailOTP`'s vocabulary, which is to say the whole of what a
+ * person meets when a passwordless sign-in goes wrong. A reader who mistyped a code was reading English
+ * on an otherwise Spanish screen.
+ *
+ * The rest of the gap is misconfiguration an adopter causes rather than anything a reader can act on,
+ * and it stays English deliberately — see `ENGLISH_ON_PURPOSE` in `./errorCopy`.
+ */
+export const AUTH_ERRORS_ES = {
+  /** A one-time code that is not the one. The commonest refusal there is. */
+  INVALID_OTP: "El código no es válido.",
+  /** The code was right once. Codes are short-lived on purpose. */
+  OTP_EXPIRED: "El código ha caducado. Pide uno nuevo.",
+  /** Rate limiting on the verification attempt, not on the request for a code. */
+  TOO_MANY_ATTEMPTS: "Demasiados intentos. Espera un momento y vuelve a intentarlo.",
+  /**
+   * The sign-in was reached by a cross-site navigation and refused.
+   *
+   * A person can meet this without doing anything wrong — an embedded browser, a link opened from
+   * another site — so it says what to do rather than naming the mechanism.
+   */
+  CROSS_SITE_NAVIGATION_LOGIN_BLOCKED: "Por seguridad, abre el enlace directamente en tu navegador.",
+} as const satisfies Record<string, string>;

package/src/i18n/errorCopy.ts

@@ -0,0 +1,99 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { locales } from "@better-auth/i18n";
+import type { BetterAuthPlugin } from "better-auth";
+import { BASE_ERROR_CODES } from "better-auth";
+import { AUTH_ERRORS_ES } from "./errorCopy.es";
+
+/**
+ * The words Better Auth's own refusals are said in.
+ *
+ * ## Why this is server-side, when every other translation in the kit is not
+ *
+ * `docs/I18N.md` holds that the server never localizes an error: a `PithyError`'s `message` stays
+ * English permanently, because it is at once the operator's diagnostic and the fallback for a client
+ * that cannot translate, and a translating client renders `t.maybe(code, params) ?? message`.
+ *
+ * These are not `PithyError`s. Better Auth owns these routes and answers them in its own flat
+ * `{ message, code }` before anything of ours sees the failure — better-call renders an endpoint's
+ * `APIError` into a Response inside `instance.handler` (#449). So the choice is not *where* to
+ * translate them but *whether*, and leaving them was leaving the last English sentences on an otherwise
+ * translated screen — met by the most ordinary mistake there is, mistyping a one-time code.
+ *
+ * Translating them at the server also reaches a caller the client seam cannot: a mobile app holding a
+ * bearer token, or a second-party integration, gets the reader's language without shipping
+ * `@pithy-sh/i18n`. And nothing is lost to the operator, because the plugin keeps the English on
+ * `originalMessage` rather than replacing it.
+ *
+ * ## Where the words come from
+ *
+ * `@better-auth/i18n` (MIT) ships 22 languages of its own, maintained upstream. This layers over them
+ * rather than restating them: copying a locale here would fork it on the day it landed, and the kit's
+ * own rule for catalogs is that they ship in the package and are never copied. {@link AUTH_ERRORS_ES}
+ * carries only what its `es` is missing.
+ *
+ * **The layering is per key, never per locale**, for the same reason `composeMessages` merges that way:
+ * a locale object replacing another is a fork wearing the shape of an override.
+ */
+
+/** Every locale this kit writes Better Auth's refusals in. English is the source and is not listed. */
+const KIT_OVERRIDES: Record<string, Record<string, string>> = { es: AUTH_ERRORS_ES };
+
+/**
+ * Codes that stay English on purpose, and why.
+ *
+ * **A declared list rather than a silent remainder.** The gate in `./errorCopy.test.ts` requires every
+ * code the composed plugin set can raise to be either translated or named here, so a code Better Auth
+ * adds in a later release fails the build instead of quietly reaching somebody in English. That is the
+ * same shape the migration-order table uses, and for the same reason: the property is only true as a
+ * set.
+ *
+ * Every entry is a fault an **adopter** caused in their own configuration or their own request, not
+ * anything a reader can act on. Translating those makes them harder to search for and no easier to fix.
+ */
+export const ENGLISH_ON_PURPOSE: Record<string, string> = {
+  ASYNC_VALIDATION_NOT_SUPPORTED: "A field validator returned a promise where the adapter takes none.",
+  BODY_MUST_BE_AN_OBJECT: "The caller sent something that is not a JSON object.",
+  CALLBACK_URL_REQUIRED: "The adopter's own call omitted the URL it wants a reader returned to.",
+  CHANGE_EMAIL_DISABLED: "The adopter switched the feature off in their own config.",
+  FAILED_TO_CREATE_VERIFICATION: "A write this Worker owns failed; the operator reads our logs, not a reader.",
+  FIELD_NOT_ALLOWED: "The caller sent a field the adopter's own schema does not declare.",
+  ID_TOKEN_NOT_SUPPORTED: "The configured provider does not do id-token sign-in.",
+  INVALID_CALLBACK_URL: "The adopter's configured callback is not a URL this Worker trusts.",
+  INVALID_ERROR_CALLBACK_URL: "As above, for the error return.",
+  INVALID_NEW_USER_CALLBACK_URL: "As above, for the first-sign-in return.",
+  INVALID_ORIGIN: "The CSRF origin gate. An operator reads this while checking `trustedOrigins`.",
+  INVALID_REDIRECT_URL: "A redirect target outside the configured set.",
+  METHOD_NOT_ALLOWED_DEFER_SESSION_REQUIRED: "A caller used the wrong verb on the session route.",
+  MISSING_OR_NULL_ORIGIN: "The other half of the origin gate, and the same audience.",
+};
+
+/** Every error code the given plugin set can raise, plus Better Auth's own base vocabulary. */
+export function composedErrorCodes(plugins: readonly BetterAuthPlugin[]): string[] {
+  const codes = new Set(Object.keys(BASE_ERROR_CODES as Record<string, unknown>));
+  for (const plugin of plugins) {
+    const own = (plugin as { $ERROR_CODES?: Record<string, unknown> }).$ERROR_CODES;
+    for (const code of Object.keys(own ?? {})) codes.add(code);
+  }
+  return [...codes].sort();
+}
+
+/**
+ * The dictionary the plugin is configured with: what it ships, with this kit's own words over the top.
+ *
+ * `en` is included and is the plugin's own, so a reader whose negotiated locale is English gets exactly
+ * the sentences Better Auth already wrote — this changes nothing for a project that serves one language.
+ */
+export function authErrorTranslations(): Record<string, Record<string, string>> {
+  const bundled = locales as unknown as Record<string, Record<string, string>>;
+  const merged: Record<string, Record<string, string>> = {};
+  for (const [locale, dictionary] of Object.entries(bundled)) {
+    merged[locale] = { ...dictionary, ...(KIT_OVERRIDES[locale] ?? {}) };
+  }
+  // A locale this kit writes that the plugin does not ship at all still has to reach the reader.
+  for (const [locale, dictionary] of Object.entries(KIT_OVERRIDES)) {
+    if (!merged[locale]) merged[locale] = { ...dictionary };
+  }
+  return merged;
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The package entrypoint — the surface `pithy add auth` wires into `pithy.config.ts`. Deliberately
+ * narrow: the capability factory, the `requireAuth()` gate other capabilities stack, and the data /
+ * secret types an app or tool needs. Every other module is imported by deep path
+ * (`@pithy-sh/auth/src/...`) — this is the documented contract, not a barrel over the package.
+ */
+
+export { AuthAuditActions } from "./audit/actions";
+export { type AuthCapability, AuthConfig, type AuthConfigInput, auth, isAuthCapability } from "./capability";
+export { type Device, DevicePlatform } from "./data/device";
+export { type AuthDatabase, authDatabase } from "./data/tables";
+export { DEVICE_HEADERS, type DeviceMeta } from "./device/registry";
+export { requireAuth } from "./http/middleware";
+export {
+  AppleOAuthCredentials,
+  AUTH_APPLE_CREDENTIALS,
+  AUTH_GOOGLE_CREDENTIALS,
+  AUTH_SESSION_SECRET,
+  authSecretsRegistry,
+  GoogleOAuthCredentials,
+} from "./instance/secrets";

package/src/instance/auth.ts

@@ -0,0 +1,309 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { AuditEmit } from "@pithy-sh/core/src/audit/recorder";
+import { type BetterAuthPlugin, betterAuth } from "better-auth";
+import { APIError, createAuthMiddleware } from "better-auth/api";
+import { emitAfterRequest, emitProviderUnavailable } from "../audit/emit";
+import { KIT_SESSION_FIELDS, KIT_USER_FIELDS } from "../data/kitFields";
+import type { AuthDatabase } from "../data/tables";
+import { parseDeviceMeta, registerDevice } from "../device/registry";
+import { kitPlugins } from "./plugins";
+import { providerUnavailable, type ResolvedProviders, unavailableProviderFor } from "./providers";
+
+/**
+ * Build the `socialProviders` block from whichever provider credentials were resolved. Exported so the
+ * per-provider branch matrix is unit-testable without constructing a Better Auth instance — it reads
+ * only the resolved credentials on `deps`, never the database.
+ *
+ * **Only a `ready` provider is registered.** A `disabled` one never was; an `unresolvable` one is the
+ * change #381 made, and it is what keeps magic link and OTP working while one credential is unreadable.
+ * The narrowing is the type's doing rather than this function's discipline — `deps.google.credentials`
+ * does not exist until `state === "ready"` has been established.
+ */
+export function socialProviders(deps: AuthInstanceDeps): Record<string, unknown> | undefined {
+  const providers: Record<string, unknown> = {};
+  if (deps.google.state === "ready") {
+    providers.google = {
+      clientId: deps.google.credentials.clientId,
+      clientSecret: deps.google.credentials.clientSecret,
+      accessType: "offline",
+      prompt: "select_account consent",
+    };
+  }
+  if (deps.apple.state === "ready") {
+    const apple = deps.apple.credentials;
+    providers.apple = {
+      clientId: apple.clientId,
+      clientSecret: apple.clientSecret,
+      ...(apple.appBundleIdentifier ? { appBundleIdentifier: apple.appBundleIdentifier } : {}),
+    };
+  }
+  if (deps.facebook.state === "ready") {
+    // Assert Facebook's email as verified. Facebook confirms a user's email before it will return it,
+    // and Better Auth validates the access token against this app before trusting the `/me` profile —
+    // so the email is genuinely the authenticated user's, verified by Facebook (the same trust Google
+    // and Apple get). Better Auth otherwise defaults Facebook's `emailVerified` to `false` (its OAuth
+    // response carries no `email_verified` claim, and the Graph API exposes no such field), which would
+    // wrongly route every Facebook sign-in through verify-to-link. `mapProfileToUser` overrides only
+    // Facebook's own email; Facebook stays out of `trustedProviders`.
+    providers.facebook = {
+      clientId: deps.facebook.credentials.clientId,
+      clientSecret: deps.facebook.credentials.clientSecret,
+      scope: ["email"],
+      mapProfileToUser: () => ({ emailVerified: true }),
+    };
+  }
+  if (deps.github.state === "ready") {
+    // `user:email` (Better Auth's default GitHub scope, requested explicitly here) lets the provider
+    // read the primary email's verified flag from the GitHub emails API — the signal account-linking
+    // gates on. GitHub is not a trusted provider, so an unverified GitHub email never auto-links.
+    providers.github = {
+      clientId: deps.github.credentials.clientId,
+      clientSecret: deps.github.credentials.clientSecret,
+      scope: ["user:email"],
+    };
+  }
+  return Object.keys(providers).length > 0 ? providers : undefined;
+}
+
+/**
+ * The seeding guard: a new account may be created only for an email a provider has **verified**.
+ *
+ * Passwordless sign-up (magic link / OTP) always creates `emailVerified: true`; a social sign-up
+ * carries the provider's own flag. Refusing an unverified-email create closes the rival-account
+ * seeding vector — otherwise an untrusted provider (e.g. a GitHub account holding an *unverified*
+ * email at someone else's address) could mint a row that a later magic-link login by the true owner
+ * would inherit. Returns `true` when the create must be refused. Account *linking* into an existing
+ * user is handled separately by Better Auth's `trustedProviders` gate; this only guards creation.
+ */
+export function isUnverifiedSignup(user: { emailVerified?: boolean | null }): boolean {
+  return user.emailVerified !== true;
+}
+
+/**
+ * What the instance hands to Pithy's email seam to deliver. The route never sends inline — the hook
+ * enqueues an `@pithy-sh/email` job (`magicLink`/`otp` template) which a Workflow delivers.
+ */
+export type AuthEmailMessage =
+  | { to: string; template: "magicLink"; token: string; url: string }
+  | { to: string; template: "otp"; code: string };
+
+/** The email-delivery seam: enqueue (never send inline). Injected so the instance stays I/O-agnostic. */
+export type SendAuthEmail = (message: AuthEmailMessage) => Promise<void>;
+
+/**
+ * Everything the Better-Auth instance needs, resolved per invocation from config + request env.
+ *
+ * Generic in the adopter's plugin tuple so the composed instance's type — and therefore its `$Infer`
+ * surface — reflects what was actually composed rather than only the kit's own.
+ */
+export interface AuthInstanceDeps<Plugins extends readonly BetterAuthPlugin[] = readonly BetterAuthPlugin[]>
+  extends ResolvedProviders {
+  /** The shared Kysely over the `pithy_auth_*` tables (carries `CamelCasePlugin`). */
+  db: AuthDatabase;
+  /** The Better-Auth signing/encryption secret, sourced from `@pithy-sh/secrets`. */
+  secret: string;
+  /** The public base URL of this environment's auth worker (no trailing slash). */
+  baseURL: string;
+  /** The mount path; must equal the Hono route the handler is mounted under. */
+  basePath: string;
+  /** Web origins and mobile deep-link schemes allowed as OAuth/redirect targets and for CSRF origin checks. */
+  trustedOrigins: string[];
+  // The four social providers arrive from `ResolvedProviders` — each one `disabled`, `ready` with its
+  // credentials, or `unresolvable`. They are the one part of this interface that is deliberately not a
+  // precondition: `db` and `secret` above fail the whole instance, and a provider does not (#381).
+  /** Deliver a magic link or OTP. Enqueues an email job; never sends inline. */
+  sendEmail: SendAuthEmail;
+  /**
+   * The catalog locale this request negotiated, or `null` when nothing did.
+   *
+   * Threaded through to the translator plugin, which is what puts Better Auth's own refusals in the
+   * reader's language (#452). An instance is built per request, so this is that request's locale.
+   */
+  locale?: string | null;
+  /** Session lifetime in seconds. */
+  sessionExpiresIn: number;
+  /** How often (seconds) an active session's expiry slides forward. */
+  sessionUpdateAge: number;
+  /** Magic-link / OTP token lifetime in seconds. */
+  verificationExpiresIn: number;
+  /** OTP length (digits). */
+  otpLength: number;
+  /** When true, sign-in never provisions a new user (existing accounts only). */
+  disableSignUp: boolean;
+  /** Audit seam — emits `auth/*` events. A no-op when the audit capability is absent. */
+  emit: AuditEmit;
+  /**
+   * The adopter's additional Better Auth plugins, from `auth({ plugins: [...] })`. Composed **after**
+   * the kit's own, never in place of one — `assertAdditivePlugins` has already refused a list that
+   * names one of them.
+   */
+  plugins: Plugins;
+}
+
+/**
+ * The concrete return type of `makeAuth` — the Better-Auth instance with Pithy's plugin set, and the
+ * adopter's on top of it.
+ *
+ * Parameterized in the plugin tuple so an adopter can name the instance their own composition produces:
+ * `AuthInstance<[ReturnType<typeof organization>]>`. That is the type
+ * `inferAdditionalFields<…>()` needs on the client, and the reason the plugin tuple is threaded through
+ * `makeAuth` rather than widened to `BetterAuthPlugin[]` at the door.
+ */
+export type AuthInstance<Plugins extends readonly BetterAuthPlugin[] = readonly BetterAuthPlugin[]> = ReturnType<
+  typeof makeAuth<Plugins>
+>;
+
+/**
+ * Build the Better-Auth instance for one request.
+ *
+ * Passwordless only — `emailAndPassword` is never enabled. The Kysely adapter wraps our shared
+ * `CamelCasePlugin` instance, so Better Auth's camelCase model names + fields map to the snake_case
+ * `pithy_auth_*` columns the migration created. Dates are ISO-8601 text on SQLite; ids are WebCrypto
+ * UUIDs; rate limiting is durable (D1-backed) since memory limiting is per-isolate on Workers.
+ */
+export function makeAuth<const Plugins extends readonly BetterAuthPlugin[]>(deps: AuthInstanceDeps<Plugins>) {
+  return betterAuth({
+    appName: "Pithy",
+    baseURL: deps.baseURL,
+    basePath: deps.basePath,
+    secret: deps.secret,
+    telemetry: { enabled: false },
+    trustedOrigins: deps.trustedOrigins,
+    database: { db: deps.db, type: "sqlite", transaction: false },
+    advanced: {
+      // WebCrypto UUID ids for every model — anti-enumeration, Workers-safe.
+      database: { generateId: () => crypto.randomUUID() },
+    },
+    // Better Auth's errors bubble out of `handler` so the Hono boundary maps them to PithyError.
+    //
+    // **Load-bearing, and measured rather than assumed (#385).** The `before` hook below throws a
+    // `PithyError`, which better-call's router does not recognize as its own `APIError` — so without
+    // this it takes the default branch: `console.error("# SERVER_ERROR: ", error)`, which prints the
+    // whole payload including the `action` naming `auth-github-credentials`, and answers a bodyless
+    // 500. Removing it reddens two cases in `http/providerResolution.workers.test.ts` (503 becomes
+    // 500, and the caller's message disappears) and puts a secret name in the log. A handler could not
+    // replace it: `onAPIError.onError`'s return value is ignored, so the only way it reaches the same
+    // outcome is by throwing, which is what this is.
+    onAPIError: { throw: true },
+    databaseHooks: {
+      user: {
+        create: {
+          // Seeding guard: refuse to create a user whose email a provider has not verified. Every
+          // passwordless sign-up creates emailVerified=true and every trusted/verified social sign-up
+          // carries a verified flag, so only an untrusted+unverified social sign-up is blocked — the
+          // vector where a provider could seed a rival row at an address the caller doesn't own.
+          before: async (user) => {
+            if (isUnverifiedSignup(user)) {
+              throw new APIError("FORBIDDEN", {
+                code: "EMAIL_NOT_VERIFIED",
+                message:
+                  "This email isn't verified by the provider. Sign in with a magic link to verify it, then connect the provider.",
+              });
+            }
+          },
+        },
+      },
+      session: {
+        create: {
+          // Bind the session to its device (registering the device first, so the linkage is valid).
+          // Only fires when a request carried device headers — an internal rotation passes deviceId
+          // via override instead, so this hook leaves it untouched.
+          before: async (session, ctx) => {
+            const meta = ctx?.headers ? parseDeviceMeta(ctx.headers) : undefined;
+            if (!meta) return;
+            await registerDevice(deps.db, meta, {
+              userId: session.userId,
+              lastIp: session.ipAddress ?? null,
+              now: new Date(),
+            });
+            return { data: { ...session, deviceId: meta.id } };
+          },
+        },
+      },
+    },
+    hooks: {
+      /**
+       * Refuse a provider this deployment enables and could not resolve, before Better Auth answers it
+       * with the 404 it gives a provider nobody configured (#381).
+       *
+       * **This is what makes degrading not the same as degrading quietly.** The instance was built
+       * without the provider, so `socialProviders` does not hold it, so `sign-in/social` would throw
+       * `PROVIDER_NOT_FOUND` — a 404 that tells somebody who signs in with GitHub every day that
+       * GitHub was never set up. It is the same answer for a fault and for a choice, and the two are
+       * not the same fact. This hook answers 503 with its own code instead, and records the attempt.
+       *
+       * **A `before` hook rather than a Hono route, and that is forced rather than preferred.** The
+       * provider is in the request *body*, and the body is Better Auth's to read: a Hono handler ahead
+       * of the catch-all would have to consume the stream that the catch-all then hands to
+       * `instance.handler(c.req.raw)`. Here the body is already parsed against the endpoint's own
+       * schema, and this reads one field out of it.
+       */
+      before: createAuthMiddleware(async (ctx) => {
+        const provider = unavailableProviderFor(ctx.path ?? "", ctx.body, deps);
+        if (!provider) return;
+        // Recorded before the throw, so the trail holds the attempt whether or not anything logs the
+        // refusal. `emitProviderUnavailable` swallows its own failure by contract.
+        await emitProviderUnavailable(deps.emit, { provider, headers: ctx.headers });
+        throw providerUnavailable(provider);
+      }),
+      // Emit audit events for every completed auth request: sign-in (+device) from the new session,
+      // plus the send/sign-out/token/OAuth events by path. Endpoint-scoped, so a rotation never emits.
+      after: createAuthMiddleware(async (ctx) => {
+        const newSession = ctx.context.newSession;
+        await emitAfterRequest(deps.emit, {
+          path: ctx.path ?? "",
+          headers: ctx.headers,
+          newSession: newSession
+            ? {
+                userId: newSession.user.id,
+                sessionId: newSession.session.id,
+                deviceId: (newSession.session as { deviceId?: string | null }).deviceId ?? null,
+              }
+            : null,
+          currentUserId: ctx.context.session?.user?.id ?? null,
+        });
+      }),
+    },
+    rateLimit: {
+      // Memory limiting is per-isolate (useless on Workers); back it with the durable D1 table.
+      enabled: true,
+      storage: "database",
+      modelName: "pithyAuthRateLimit",
+    },
+    user: {
+      modelName: "pithyAuthUsers",
+      // One declaration, shared with the schema baseline in `../migrations/pluginTables.ts`. See
+      // `../data/kitFields.ts` for why a column missing here is invisible to Better Auth, and why the
+      // two used to be written out twice.
+      additionalFields: KIT_USER_FIELDS,
+    },
+    session: {
+      modelName: "pithyAuthSessions",
+      expiresIn: deps.sessionExpiresIn,
+      updateAge: deps.sessionUpdateAge,
+      // Server-set session fields clients never supply: the bound device, and the refresh-token family
+      // (carried across rotations via createSession override, like deviceId — see `token/rotation.ts`).
+      additionalFields: KIT_SESSION_FIELDS,
+    },
+    account: {
+      modelName: "pithyAuthAccounts",
+      accountLinking: {
+        enabled: true,
+        // Link a social sign-in to an existing magic-link user when the verified emails match.
+        trustedProviders: ["google", "apple"],
+      },
+    },
+    verification: { modelName: "pithyAuthVerifications" },
+    ...((): { socialProviders?: Record<string, unknown> } => {
+      const providers = socialProviders(deps);
+      return providers ? { socialProviders: providers } : {};
+    })(),
+    // The kit's four first, the adopter's after. Order is the contract: Better Auth merges plugin
+    // endpoints by id and a later registration wins, so composing the adopter's list first would let
+    // it quietly redefine the sign-in this product promises. `assertAdditivePlugins` has already
+    // refused a list that names one of the four; this order is what makes that refusal the only way in.
+    plugins: [...kitPlugins(deps), ...deps.plugins],
+  });
+}