@pithy-sh/auth 0.1.0

package/src/instance/plugins.ts

@@ -0,0 +1,172 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { i18n } from "@better-auth/i18n";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { BetterAuthPlugin } from "better-auth";
+import { bearer } from "better-auth/plugins/bearer";
+import { emailOTP } from "better-auth/plugins/email-otp";
+import { jwt } from "better-auth/plugins/jwt";
+import { magicLink } from "better-auth/plugins/magic-link";
+import { z } from "zod";
+import { authErrorTranslations } from "../i18n/errorCopy";
+import type { SendAuthEmail } from "./auth";
+
+/**
+ * The four Better Auth plugins the kit composes for itself, and the reason they are fixed.
+ *
+ * `magic-link` and `email-otp` **are** the sign-in this product promises — passwordless, no
+ * `emailAndPassword` anywhere. `jwt` mints the JWKS the control-plane seam verifies against and
+ * `bearer` is how a mobile client presents its credential. Every one of them is depended on by code
+ * outside this package, so an adopter who removed or redefined one would break a contract they cannot
+ * see from their config. The adopter's list is therefore **additive**: it extends this set, never
+ * replaces a member of it.
+ */
+export const KIT_PLUGIN_IDS = ["i18n", "bearer", "jwt", "magic-link", "email-otp"] as const;
+
+/** What the kit's own plugins need to be constructed. The subset of `AuthInstanceDeps` they read. */
+export interface KitPluginDeps {
+  /** 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;
+  /** Deliver a magic link or OTP. Enqueues an email job; never sends inline. */
+  sendEmail: SendAuthEmail;
+  /**
+   * The catalog locale this request negotiated, or `null`/absent when nothing did.
+   *
+   * Read from `c.var.locale` where the instance is built, which is per request — so this is the locale
+   * the *project* resolved through its own configured chain, never a second negotiation of Better
+   * Auth's own. Without that a reader who chose Spanish with `?lang=es` would get Spanish screens and
+   * English refusals on the same page, because the two chains ask different signals in different
+   * orders (#452).
+   *
+   * `null` is the ordinary state of a project that never composed `i18n`, and it means English — which
+   * is what the plugin answers with anyway, so its absence is not a special case.
+   */
+  locale?: string | null;
+}
+
+/**
+ * The kit's four, as a **tuple** rather than an array. Better Auth infers a composed instance's whole
+ * `$Infer` surface from the element types of its `plugins` list, so widening this to
+ * `BetterAuthPlugin[]` here would erase the adopter's plugin types one line later, where `makeAuth`
+ * spreads the two lists together.
+ */
+export type KitPlugins = [
+  // Widened where the other four are not, and it costs nothing: the translator contributes no
+  // endpoints and no `$Infer` surface, so there is no adopter-visible type to erase. Its own return
+  // type names an internal `MiddlewareOptions` that cannot be named from here, which is a TS4058 on
+  // `makeAuth`'s declaration emit rather than anything about the composition.
+  BetterAuthPlugin,
+  ReturnType<typeof bearer>,
+  ReturnType<typeof jwt>,
+  ReturnType<typeof magicLink>,
+  ReturnType<typeof emailOTP>,
+];
+
+/**
+ * Build the kit's own plugins. **One definition, two readers**: `makeAuth` composes these into the
+ * live instance, and the migration builder composes the same four into the baseline schema it diffs an
+ * adopter's plugins against. Two copies of this list would be drift that no test could see — the
+ * baseline would claim a table the instance never created, or miss one it did.
+ */
+export function kitPlugins(deps: KitPluginDeps): KitPlugins {
+  return [
+    /**
+     * Better Auth's own refusals, in the reader's language (#452).
+     *
+     * **First in the list deliberately.** It works by wrapping the error rendering of the plugins
+     * registered around it, so anything composed before it answers in English regardless.
+     *
+     * `getLocale` is the whole of the integration: one chain, the project's, resolved before this
+     * instance was built. The plugin's own `header`/`cookie`/`session` strategies are deliberately
+     * unused — each is a second negotiation, and two chains over one page is the bug where the screens
+     * and the errors disagree about who is reading.
+     */
+    i18n({
+      translations: authErrorTranslations(),
+      detection: ["callback"],
+      getLocale: () => deps.locale ?? null,
+    }),
+    bearer(),
+    jwt({ schema: { jwks: { modelName: "pithyAuthJwks" } } }),
+    magicLink({
+      expiresIn: deps.verificationExpiresIn,
+      disableSignUp: deps.disableSignUp,
+      sendMagicLink: async ({ email, url, token }) => {
+        await deps.sendEmail({ to: email, template: "magicLink", token, url });
+      },
+    }),
+    emailOTP({
+      otpLength: deps.otpLength,
+      expiresIn: deps.verificationExpiresIn,
+      disableSignUp: deps.disableSignUp,
+      sendVerificationOTP: async ({ email, otp, type }) => {
+        if (type !== "sign-in") return;
+        await deps.sendEmail({ to: email, template: "otp", code: otp });
+      },
+    }),
+  ];
+}
+
+/** Is this value shaped like a Better Auth plugin — an object carrying a non-empty string `id`? */
+function isBetterAuthPlugin(value: unknown): value is BetterAuthPlugin {
+  if (typeof value !== "object" || value === null) return false;
+  const id = (value as { id?: unknown }).id;
+  return typeof id === "string" && id.length > 0;
+}
+
+/**
+ * One additional Better Auth plugin, validated at the config boundary.
+ *
+ * `z.custom` rather than a `z.object`, and deliberately: a plugin is a live object carrying endpoints,
+ * hooks and an `init` closure, and an object schema would hand back a **copy** — a different object from
+ * the one Better Auth was given, with whatever the schema did not name quietly dropped. What can be
+ * checked without rebuilding it is checked: it is an object, and it has the `id` every other rule here
+ * (reservation, duplication, migration keys, `pithy doctor`) is written in terms of.
+ */
+export const AuthPlugin = z
+  .custom<BetterAuthPlugin>(isBetterAuthPlugin, {
+    message: "Expected a Better Auth plugin — an object with a non-empty string `id`.",
+  })
+  .describe(
+    "An additional Better Auth plugin, e.g. `organization()`, `passkey()`, `twoFactor()`. Added to the set the kit composes, never in place of one.",
+  );
+
+/**
+ * Refuse a plugin list that is not purely additive, naming the offending plugin.
+ *
+ * Two ways it can fail, and both name a single id because that is what the adopter has to go delete:
+ * a plugin whose id is one of {@link KIT_PLUGIN_IDS} would sit beside the kit's own copy (Better Auth
+ * merges endpoints by id — the later registration silently wins, so this is a redefinition even when it
+ * reads like an addition), and two plugins sharing an id do the same to each other.
+ *
+ * **The `message` stays short on purpose.** `auth()` runs while `pithy.config.ts` is being imported, so
+ * the CLI catches this through `classifyConfigLoadFailure`, which prints the cause's message and nothing
+ * else — and drops it entirely past 160 characters (`safeReason`). A refusal whose whole content is in
+ * its `action` reaches the adopter as "the config threw while loading", which names nothing.
+ */
+export function assertAdditivePlugins(plugins: readonly BetterAuthPlugin[]): void {
+  const reserved: readonly string[] = KIT_PLUGIN_IDS;
+  const seen = new Set<string>();
+  for (const plugin of plugins) {
+    if (reserved.includes(plugin.id)) {
+      throw new ValidationError({
+        message: `The auth capability already composes the Better Auth "${plugin.id}" plugin.`,
+        action: `Remove ${plugin.id}() from auth({ plugins: [...] }). The four the kit composes (${KIT_PLUGIN_IDS.join(", ")}) are the sign-in this product promises and what the control-plane seam verifies against; your list adds to them.`,
+        detail: `reserved plugin id "${plugin.id}" supplied through AuthConfig.plugins`,
+      });
+    }
+    if (seen.has(plugin.id)) {
+      throw new ValidationError({
+        message: `The Better Auth "${plugin.id}" plugin is listed twice in auth({ plugins: [...] }).`,
+        action: `Keep one ${plugin.id}() in auth({ plugins: [...] }) — the second registration would silently win over the first.`,
+        detail: `duplicate plugin id "${plugin.id}" supplied through AuthConfig.plugins`,
+      });
+    }
+    seen.add(plugin.id);
+  }
+}

package/src/instance/providers.ts

@@ -0,0 +1,185 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import type {
+  AppleOAuthCredentials,
+  FacebookOAuthCredentials,
+  GithubOAuthCredentials,
+  GoogleOAuthCredentials,
+} from "./secrets";
+
+/**
+ * What one social provider *is*, for one instance — three states, carried on the value (#381).
+ *
+ * ## Why three
+ *
+ * A provider used to be `Credentials | undefined`, and that shape had room for two facts and needed
+ * room for three. `undefined` meant "the adopter did not enable this"; there was no way to say "the
+ * adopter enabled it and its credential would not read", so that third fact was expressed by the only
+ * means left — the resolution rejecting, inside a `Promise.all` that also carried the session secret.
+ * One unreadable `auth-github-credentials` therefore took down magic link and OTP for every user,
+ * because a contributor to sign-in was wired as a precondition of it.
+ *
+ * The session secret and the D1 binding really are preconditions: without either there is no sign-in of
+ * any kind, and they keep failing the whole instance. A provider is one method among several.
+ *
+ * ## Why on the value
+ *
+ * This is #350's shape, applied to a provider rather than an aggregate. The credentials live *behind*
+ * the healthy member, so a call site reaches `clientId` only by narrowing on `state`, and one that
+ * forgets the sick case does not silently build a provider out of nothing — it does not compile. A flag
+ * beside an optional credential would be the same information and the opposite property.
+ *
+ * ## Why `unresolvable` carries nothing
+ *
+ * {@link resolveProvider}'s `catch` takes no binding, so nothing derived from the throw is in reach to
+ * put here. That is deliberate rather than incidental: what a secret resolution throws is a
+ * `SecretNotFoundError` whose `message` names `auth-github-credentials`, or a schema failure whose
+ * issues quote what was stored. Neither may reach a browser. Everything the refusal needs — *which*
+ * provider — is known at the call site from the key it was resolved under, so it never has to be
+ * recovered from an error.
+ */
+export type ResolvedProvider<Credentials> =
+  | { readonly state: "disabled" }
+  | { readonly state: "ready"; readonly credentials: Credentials }
+  | { readonly state: "unresolvable" };
+
+/**
+ * The one `disabled` value, so the state has one spelling.
+ *
+ * Typed as the bare member rather than `ResolvedProvider<never>`: it is assignable to every
+ * `ResolvedProvider<C>` either way, and this way nothing can read a `credentials` off it by widening.
+ */
+export const PROVIDER_DISABLED: { readonly state: "disabled" } = { state: "disabled" };
+
+/** The social providers the kit composes. Ordered as they are declared in config. */
+export const SOCIAL_PROVIDER_IDS = ["google", "apple", "facebook", "github"] as const;
+
+/** One of the kit's social providers. */
+export type SocialProviderId = (typeof SOCIAL_PROVIDER_IDS)[number];
+
+/**
+ * Every provider's state for one instance.
+ *
+ * A record rather than four loose fields, because two things read it — the `socialProviders` block the
+ * instance is built from, and the refusal that answers a caller who asked for one that is not there —
+ * and they must be reading the same four values or they will disagree about what is available.
+ */
+export interface ResolvedProviders {
+  /** Google OAuth: disabled, ready with its credential pair, or declared and unreadable. */
+  google: ResolvedProvider<GoogleOAuthCredentials>;
+  /** Apple Sign-In: disabled, ready with its credential set, or declared and unreadable. */
+  apple: ResolvedProvider<AppleOAuthCredentials>;
+  /** Facebook Login: disabled, ready with its credential pair, or declared and unreadable. */
+  facebook: ResolvedProvider<FacebookOAuthCredentials>;
+  /** GitHub OAuth: disabled, ready with its credential pair, or declared and unreadable. */
+  github: ResolvedProvider<GithubOAuthCredentials>;
+}
+
+/**
+ * Every provider disabled — what a composition that enables no social sign-in resolves to, and the
+ * base a construction site spreads over rather than spelling four times.
+ */
+export const NO_SOCIAL_PROVIDERS: Readonly<ResolvedProviders> = {
+  google: PROVIDER_DISABLED,
+  apple: PROVIDER_DISABLED,
+  facebook: PROVIDER_DISABLED,
+  github: PROVIDER_DISABLED,
+};
+
+/**
+ * Resolve one provider: `disabled` when the adopter did not enable it, `ready` with its credentials, or
+ * `unresolvable` when it is enabled and the read failed.
+ *
+ * **`try`/`catch`, and `read` is invoked inside it.** A `.catch()` on the returned promise would guard
+ * only a rejection, and a seam that throws *before* it returns a promise is not a rejected promise —
+ * that is how #371's first plant walked straight through its own guard. Calling `read()` inside the
+ * `try` catches both, and `providers.test.ts` plants a synchronous throw to prove it.
+ *
+ * **The `catch` takes no binding.** See {@link ResolvedProvider} — what a secret resolution throws
+ * names the secret, and nothing derived from it may travel toward a browser.
+ */
+export async function resolveProvider<Credentials>(
+  enabled: boolean,
+  read: () => Promise<Credentials>,
+): Promise<ResolvedProvider<Credentials>> {
+  if (!enabled) return PROVIDER_DISABLED;
+  try {
+    return { state: "ready", credentials: await read() };
+  } catch {
+    return { state: "unresolvable" };
+  }
+}
+
+/**
+ * The Better Auth endpoints that name a social provider in their body, as their `ctx.path` reads —
+ * mounted paths, so no `basePath` appears here.
+ *
+ * `/callback/:provider` is deliberately absent: a callback can only arrive for a provider that already
+ * served an authorize redirect, and an unresolvable one never did.
+ */
+const PROVIDER_BODY_PATHS: ReadonlySet<string> = new Set(["/sign-in/social", "/link-social"]);
+
+/**
+ * The provider named in a social sign-in body.
+ *
+ * Parsed rather than cast. Better Auth has already validated the body against the endpoint's own
+ * schema by the time a `before` hook runs, so this is not the trust boundary — but a `catchall` shape
+ * read with a cast is how a hook starts reading a field that is not there, and `unknown` narrows for
+ * free here.
+ */
+const ProviderBody = z
+  .object({
+    provider: z.string().min(1).describe("The social provider id the caller asked to sign in or link with."),
+  })
+  .describe("The part of a social sign-in body this refusal reads: which provider was asked for.");
+
+/**
+ * Which provider this request asks for, when the request is one that names one and that provider is
+ * enabled but unreadable. `undefined` for every other request, which is nearly all of them.
+ *
+ * A provider that is merely *disabled* is not this function's business: Better Auth answers that with
+ * its own `PROVIDER_NOT_FOUND` 404, which is the right answer — nobody configured it. This exists so
+ * the two stop looking alike from outside the Worker.
+ */
+export function unavailableProviderFor(
+  path: string,
+  body: unknown,
+  providers: ResolvedProviders,
+): SocialProviderId | undefined {
+  if (!PROVIDER_BODY_PATHS.has(path)) return undefined;
+  const parsed = ProviderBody.safeParse(body);
+  if (!parsed.success) return undefined;
+  const asked = SOCIAL_PROVIDER_IDS.find((id) => id === parsed.data.provider);
+  if (!asked) return undefined;
+  return providers[asked].state === "unresolvable" ? asked : undefined;
+}
+
+/**
+ * The refusal a caller gets for a provider this deployment means to serve and cannot.
+ *
+ * Three audiences, three fields, exactly as the error family prescribes:
+ *
+ * - `message` is the caller's, and it is the whole of what crosses the wire. It says the method is
+ *   unavailable *right now* and names one that works, because a 404 saying "provider not found" tells
+ *   somebody who signs in with GitHub every day that they were wrong about their own account.
+ * - `action` is the operator's — the command that fixes it, and the config key that turns it off.
+ * - `detail` is the throw site's. It names the provider and says the credential would not resolve. It
+ *   does **not** carry the resolution's own error: `resolveProvider` dropped that whole, on purpose.
+ *
+ * `503` rather than `500`, and rather than `404`. This deployment's own dependency — the credential row
+ * for one sign-in method — is the thing that could not be served, which is what 503 means and what
+ * `payments/provider_unavailable` already uses it for. A 404 would be indistinguishable from a provider
+ * nobody enabled, and that indistinguishability is the defect.
+ */
+export function providerUnavailable(provider: SocialProviderId): PithyError {
+  return new PithyError({
+    code: "auth/provider_unavailable",
+    status: 503,
+    message: `Signing in with ${provider} is unavailable right now. Use a magic link instead.`,
+    action: `Provision \`auth-${provider}-credentials\` for this environment with \`pithy secrets create\`, or set \`${provider}.enabled\` to false in pithy.config.ts.`,
+    detail: `provider ${provider} is enabled and its credential could not be resolved; the instance was built without it`,
+  });
+}

package/src/instance/secrets.ts

@@ -0,0 +1,197 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
+import { defineSecretRegistry } from "@pithy-sh/secrets/src/registry";
+import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
+import { z } from "zod";
+
+/**
+ * The secrets `@pithy-sh/auth` reads, declared as a minimal registry. The secret name is the join key:
+ * `secretsStore` resolves the same encrypted D1 row regardless of which capability's registry names it,
+ * so auth never needs the project-wide registry to read its own secrets.
+ *
+ * - `auth-session-secret` — the Better Auth signing/encryption secret. Signs session cookies and the
+ *   bearer HMAC, and encrypts the JWKS private keys at rest. Rotatable (Better Auth accepts a version
+ *   set so a rotation keeps prior signatures valid).
+ * - `auth-google-credentials` — the Google OAuth client id and secret together, as a typed JSON value.
+ *   Both travel as one atomic secret so the credential pair is never split across config and store.
+ *   Read only when the provider is enabled; rotated in Google Cloud Console, not on our schedule.
+ * - `auth-apple-credentials` — the Apple Sign-In Services id, client secret, and (optional) app bundle
+ *   id, as a typed JSON value. Apple's client secret is an ES256 JWT minted from the `.p8` key that
+ *   expires (max 6 months), so this one is rotatable.
+ * - `auth-facebook-credentials` — the Facebook Login app id and client secret, as a typed JSON value.
+ *   Read only when the provider is enabled; rotated in the Meta app dashboard, not on our schedule.
+ * - `auth-github-credentials` — the GitHub OAuth app client id and secret, as a typed JSON value.
+ *   Read only when the provider is enabled; rotated in GitHub Developer settings, not on our schedule.
+ */
+export const AUTH_SESSION_SECRET = "auth-session-secret";
+export const AUTH_GOOGLE_CREDENTIALS = "auth-google-credentials";
+export const AUTH_APPLE_CREDENTIALS = "auth-apple-credentials";
+export const AUTH_FACEBOOK_CREDENTIALS = "auth-facebook-credentials";
+export const AUTH_GITHUB_CREDENTIALS = "auth-github-credentials";
+
+/** The Google OAuth credential pair, stored as one typed JSON secret. */
+export const GoogleOAuthCredentials = z
+  .object({
+    clientId: z
+      .string()
+      .describe(
+        "The Google OAuth client id for this environment. Not secret on its own, but stored with the secret so the pair is atomic.",
+      ),
+    clientSecret: z
+      .string()
+      .describe("The Google OAuth client secret for this environment. Never committed, never an env literal."),
+  })
+  .describe("A Google OAuth client credential pair (`clientId` + `clientSecret`) for one environment.");
+export type GoogleOAuthCredentials = z.infer<typeof GoogleOAuthCredentials>;
+
+/** The Apple Sign-In credentials, stored as one typed JSON secret. */
+export const AppleOAuthCredentials = z
+  .object({
+    clientId: z.string().describe("The Apple Sign-In Services id (the web OAuth client id) for this environment."),
+    clientSecret: z
+      .string()
+      .describe(
+        "The Apple client secret — an ES256 JWT minted from the `.p8` key. Expires (max 6 months), so rotate it on schedule.",
+      ),
+    appBundleIdentifier: z
+      .string()
+      .optional()
+      .describe(
+        "The native iOS app bundle id, used as the id-token audience for the native Sign-in-with-Apple flow. Optional.",
+      ),
+  })
+  .describe(
+    "An Apple Sign-In credential set (`clientId` + `clientSecret`, optional `appBundleIdentifier`) for one environment.",
+  );
+export type AppleOAuthCredentials = z.infer<typeof AppleOAuthCredentials>;
+
+/** The Facebook Login credential pair, stored as one typed JSON secret. */
+export const FacebookOAuthCredentials = z
+  .object({
+    clientId: z
+      .string()
+      .describe(
+        "The Facebook Login app id for this environment. Not secret on its own, but stored with the secret so the pair is atomic.",
+      ),
+    clientSecret: z
+      .string()
+      .describe("The Facebook Login app secret for this environment. Never committed, never an env literal."),
+  })
+  .describe("A Facebook Login credential pair (`clientId` + `clientSecret`) for one environment.");
+export type FacebookOAuthCredentials = z.infer<typeof FacebookOAuthCredentials>;
+
+/** The GitHub OAuth credential pair, stored as one typed JSON secret. */
+export const GithubOAuthCredentials = z
+  .object({
+    clientId: z
+      .string()
+      .describe(
+        "The GitHub OAuth app client id for this environment. Not secret on its own, but stored with the secret so the pair is atomic.",
+      ),
+    clientSecret: z
+      .string()
+      .describe("The GitHub OAuth app client secret for this environment. Never committed, never an env literal."),
+  })
+  .describe("A GitHub OAuth credential pair (`clientId` + `clientSecret`) for one environment.");
+export type GithubOAuthCredentials = z.infer<typeof GithubOAuthCredentials>;
+
+/**
+ * Where a human goes for each OAuth credential pair, and where the same human rotates it.
+ *
+ * **The settings page, not the product homepage.** The point is to end a search, not to start one — and
+ * these four are the case with no command and no possible one, so the link is the entire remedy the kit
+ * can offer. Named constants because origin and rotation are the same page for all four, and two copies
+ * of a URL is one that goes stale.
+ */
+const GOOGLE_CREDENTIALS_PAGE = "https://console.cloud.google.com/apis/credentials";
+const APPLE_KEYS_PAGE = "https://developer.apple.com/account/resources/authkeys/list";
+const FACEBOOK_APPS_PAGE = "https://developers.facebook.com/apps/";
+const GITHUB_OAUTH_APPS_PAGE = "https://github.com/settings/developers";
+
+export const authSecretsRegistry = defineSecretRegistry({
+  // `devValue` is the whole difference between an app that runs after `pithy add auth` and one that
+  // signs nobody in: this secret is not a required binding, so nothing names it until the first
+  // sign-in. Any random string signs a session — nothing outside the project has to agree with it.
+  [AUTH_SESSION_SECRET]: {
+    backend: "d1",
+    scope: "environment",
+    rotatable: true,
+    valueType: "text",
+    devValue: "random",
+    // `project` is the issuer, which is the whole reason this one is different: nobody outside validates
+    // a session signature, so the kit both makes it and replaces it.
+    origin: { kind: "minted", recipe: { kind: "random", bytes: 32, encoding: "base64url" } },
+    rotation: { kind: "local" },
+  },
+  // The four below are `obtained` and rotate `manual`, and each names the page rather than the product.
+  // An adopter searching Google's console for which of four credential types "client secret" means is the
+  // gap this closes — and nothing will ever mint one, so saying where is the whole of what the kit can do.
+  [AUTH_GOOGLE_CREDENTIALS]: {
+    backend: "d1",
+    scope: "environment",
+    rotatable: false,
+    valueType: "json",
+    schema: GoogleOAuthCredentials,
+    origin: { kind: "obtained", issuer: "google", documentation: GOOGLE_CREDENTIALS_PAGE },
+    rotation: { kind: "manual", issuer: "google", documentation: GOOGLE_CREDENTIALS_PAGE },
+  },
+  [AUTH_APPLE_CREDENTIALS]: {
+    backend: "d1",
+    scope: "environment",
+    rotatable: true,
+    valueType: "json",
+    schema: AppleOAuthCredentials,
+    origin: { kind: "obtained", issuer: "apple", documentation: APPLE_KEYS_PAGE },
+    rotation: { kind: "manual", issuer: "apple", documentation: APPLE_KEYS_PAGE },
+  },
+  [AUTH_FACEBOOK_CREDENTIALS]: {
+    backend: "d1",
+    scope: "environment",
+    rotatable: false,
+    valueType: "json",
+    schema: FacebookOAuthCredentials,
+    origin: { kind: "obtained", issuer: "facebook", documentation: FACEBOOK_APPS_PAGE },
+    rotation: { kind: "manual", issuer: "facebook", documentation: FACEBOOK_APPS_PAGE },
+  },
+  [AUTH_GITHUB_CREDENTIALS]: {
+    backend: "d1",
+    scope: "environment",
+    rotatable: false,
+    valueType: "json",
+    schema: GithubOAuthCredentials,
+    origin: { kind: "obtained", issuer: "github", documentation: GITHUB_OAUTH_APPS_PAGE },
+    rotation: { kind: "manual", issuer: "github", documentation: GITHUB_OAUTH_APPS_PAGE },
+  },
+});
+
+/** Resolve the Better Auth session secret for this invocation. */
+export async function resolveSessionSecret(env: SecretsStoreEnv): Promise<string> {
+  const secrets = await sharedSecretsStore(env, authSecretsRegistry);
+  return secrets.get(AUTH_SESSION_SECRET);
+}
+
+/** Resolve the Google OAuth credential pair for this invocation (only call when Google is enabled). */
+export async function resolveGoogleCredentials(env: SecretsStoreEnv): Promise<GoogleOAuthCredentials> {
+  const secrets = await sharedSecretsStore(env, authSecretsRegistry);
+  return secrets.get(AUTH_GOOGLE_CREDENTIALS);
+}
+
+/** Resolve the Apple Sign-In credentials for this invocation (only call when Apple is enabled). */
+export async function resolveAppleCredentials(env: SecretsStoreEnv): Promise<AppleOAuthCredentials> {
+  const secrets = await sharedSecretsStore(env, authSecretsRegistry);
+  return secrets.get(AUTH_APPLE_CREDENTIALS);
+}
+
+/** Resolve the Facebook Login credential pair for this invocation (only call when Facebook is enabled). */
+export async function resolveFacebookCredentials(env: SecretsStoreEnv): Promise<FacebookOAuthCredentials> {
+  const secrets = await sharedSecretsStore(env, authSecretsRegistry);
+  return secrets.get(AUTH_FACEBOOK_CREDENTIALS);
+}
+
+/** Resolve the GitHub OAuth credential pair for this invocation (only call when GitHub is enabled). */
+export async function resolveGithubCredentials(env: SecretsStoreEnv): Promise<GithubOAuthCredentials> {
+  const secrets = await sharedSecretsStore(env, authSecretsRegistry);
+  return secrets.get(AUTH_GITHUB_CREDENTIALS);
+}