@ultimat3/auth 8.0.0 → 10.0.0

package/src/index.ts

@@ -57,7 +57,7 @@ export { describeUser, findUserByExternalId, listOrgUsers } from './directory';
 // The one normalisation an address gets before it is an identity key. Public because an app
 // writing its own `AuthAdapter`, or its own login route, has to key exactly the way this does.
 export { normaliseEmail } from './email';
-export type { AuthErrorCode, AuthThrowCode, OAuthExchangeFailure } from './errors';
+export type { AuthErrorCode, AuthThrowCode } from './errors';
 export {
   AUTH_BORROWED_ERROR_CODES,
   AUTH_ERROR_CODES,
@@ -68,28 +68,18 @@ export {
   authLimiterNotShared,
   authLimiterPolicyMismatch,
   authNotImplemented,
+  authUniqueViolation,
   authWriteFailed,
-  emailVerifiedNotStored,
   forbidden,
   kdfOverloaded,
   mfaRequired,
   mfaRequiredUnenforceable,
   mfaSecretInvalid,
-  oauthAccountNotLinked,
-  oauthDenied,
-  oauthExchangeFailed,
-  oauthLinkingDisabled,
-  oauthProviderDuplicate,
-  oauthProviderUnknown,
-  oauthStateInvalid,
-  oauthTokenInvalid,
   passwordWeak,
-  restartAt,
   sessionExpired,
   sessionUnknown,
   unauthenticated,
 } from './errors';
-
 export { currentActor, requireActor } from './guards';
 export type { IdTokenClaims, VerifyIdTokenInput } from './id-token';
 export {
@@ -120,6 +110,10 @@ export {
   kdfGate,
   resetKdfGate,
 } from './kdf-gate';
+export type { AuthLimiterFactory } from './limiter-install';
+// `installedAuthLimiter` is deliberately absent: `defineAuth` is the one reader, and a second
+// caller building limiters out of band would be a second answer to where failures are counted.
+export { configureAuthLimiters, purgeAuthLimits, resetAuthLimiters } from './limiter-install';
 export { MemoryAdapter } from './memory-adapter';
 export type {
   EnrolTotpInput,
@@ -176,6 +170,21 @@ export {
 } from './oauth-cookie';
 export type { DiscoverOAuthProviderInput } from './oauth-discovery';
 export { discoverOAuthProvider, discoveryUrl } from './oauth-discovery';
+// The OAuth half of the same contract, split out of `errors.ts` at the 500-line ceiling. Every
+// name below was exported from `./errors` before the split and is exported here after it.
+export type { OAuthExchangeFailure } from './oauth-errors';
+export {
+  emailVerifiedNotStored,
+  oauthAccountNotLinked,
+  oauthDenied,
+  oauthExchangeFailed,
+  oauthLinkingDisabled,
+  oauthProviderDuplicate,
+  oauthProviderUnknown,
+  oauthStateInvalid,
+  oauthTokenInvalid,
+  restartAt,
+} from './oauth-errors';
 export type {
   OAuthClientCredentials,
   OAuthExchangeOptions,

package/src/jwks.ts

@@ -8,9 +8,9 @@
 
 import type { Clock } from '@ultimat3/core';
 import { renderThrowable, systemClock } from '@ultimat3/core';
-import { oauthExchangeFailed, oauthTokenInvalid } from './errors';
 import { decodeJwtSegment, isRecord } from './json';
 import type { OAuthProvider } from './oauth';
+import { oauthExchangeFailed, oauthTokenInvalid } from './oauth-errors';
 import type { OAuthFetch } from './oauth-exchange';
 import { base64UrlBytes } from './tokens';
 
@@ -200,8 +200,19 @@ export function createJwksClient(options: JwksClientOptions): JwksKeySource {
 const clients = new Map<string, JwksKeySource>();
 
 /**
- * The provider's own key set, built once per provider id. Memoised because the cache is the point:
- * a client rebuilt per request refetches the key set per request.
+ * The provider's own key set. The DEFAULT client is built once per provider id — memoised because
+ * the cache is the point: a client rebuilt per request refetches the key set per request.
+ *
+ * A caller that SUPPLIES options gets a client built with them, and is not served the memo. The
+ * memo was keyed on the provider id alone, so the second caller's `fetch`, `clock`, `ttlMs` and
+ * `timeoutMs` were silently discarded: an app pinning a corporate egress proxy got it only if it
+ * happened to call first, and nothing said otherwise. That is the `jobs.driver` shape — a key read
+ * once and thereafter ignored — except the value quietly substituted here is a network path.
+ *
+ * Not cached by option identity, deliberately: `fetch` and `clock` are functions and objects, so
+ * any canonical key over them either collides (two different proxies, one entry) or never hits.
+ * A bespoke client is a bespoke client; `createJwksClient` is what it is, and its own cache still
+ * works for as long as the caller holds it.
  */
 export function providerJwks(
   provider: OAuthProvider,
@@ -214,10 +225,11 @@ export function providerJwks(
       `register ${provider.id} with an explicit jwksUri, or read its id token only through exchangeOAuthCode()`,
     );
   }
-  const existing = clients.get(provider.id);
+  const bespoke = options !== undefined && Object.keys(options).length > 0;
+  const existing = bespoke ? undefined : clients.get(provider.id);
   if (existing !== undefined) return existing;
   const client = createJwksClient({ ...options, provider: provider.id, jwksUri: provider.jwksUri });
-  clients.set(provider.id, client);
+  if (!bespoke) clients.set(provider.id, client);
   return client;
 }
 

package/src/limiter-install.ts

@@ -0,0 +1,90 @@
+// Single responsibility: the ONE ambient install point for where failed credential attempts are
+// counted, plus the purge over whatever it built.
+//
+// WHY a seam and not a `defineAuth` argument: `defineAuth` is the APP's call, and the app is not
+// the thing that knows which database this process opened. A host boot resolves the pool long
+// before it imports app modules (`@ultimat3/cli`'s `startServices` runs before `loadApp`), so
+// until this existed `postgresAuthLimiter` shipped with nowhere to be installed from — account
+// lockouts stayed per-pod while the shipped chart runs three `web` replicas, and an attacker got
+// N x the lockout budget by spreading a spray across them.
+//
+// WHY a FACTORY and not a limiter: `defineAuth` compares what a limiter reports against what the
+// app declared (`assertAuthLimiterPolicy`), and the boot cannot know the app's `maxAttempts`,
+// `windowMs` or `lockoutMs` — it has not imported the app yet. Handing over a built limiter would
+// make every app that tunes its own numbers fail at boot with `X_AUTH_LIMITER_POLICY_MISMATCH`.
+// The factory is called WITH the resolved policy, so the two halves cannot disagree.
+
+import type { AuthLimiter, AuthRateLimitPolicy } from './rate-limit';
+
+/**
+ * Build a limiter enforcing exactly `policy`. Called once per bucket — the account/IP bucket and
+ * the tenant bucket are separate instances over one store, because they enforce different
+ * `maxAttempts` and their keys are prefix-disjoint (`account:` / `ip:` / `org:`).
+ */
+export type AuthLimiterFactory = (policy: AuthRateLimitPolicy) => AuthLimiter;
+
+let factory: AuthLimiterFactory | undefined;
+/** Every limiter this process built through the factory above, so a purge can reach them. */
+let built: AuthLimiter[] = [];
+
+/**
+ * The ONE install point, the same shape as `configureKdfGate` beside it: a host that owns the
+ * database connection says where failed attempts are counted, and every `defineAuth` in the
+ * process picks it up without the app declaring anything.
+ *
+ * A second install replaces the first and forgets what the first built — a limiter over a pool
+ * the previous boot has closed is not something a purge should still be sweeping through.
+ */
+export function configureAuthLimiters(next: AuthLimiterFactory): void {
+  factory = next;
+  built = [];
+}
+
+/** Back to `createAuthLimiter`, the per-process default. A host that installs one calls this on stop. */
+export function resetAuthLimiters(): void {
+  factory = undefined;
+  built = [];
+}
+
+/**
+ * `defineAuth`'s reader, and deliberately NOT exported from `src/index.ts`: a second caller
+ * building limiters out of band would be a second answer to "where are failures counted", which
+ * is the ambiguity axiom 1 refuses. `undefined` means no host installed one, and the caller falls
+ * back to the in-memory limiter.
+ */
+export function installedAuthLimiter(policy: AuthRateLimitPolicy): AuthLimiter | undefined {
+  if (factory === undefined) return undefined;
+  const limiter = factory(policy);
+  built.push(limiter);
+  return limiter;
+}
+
+/** A limiter that keeps rows somebody else has to delete. The memory limiter sweeps itself. */
+type PurgingAuthLimiter = AuthLimiter & { purgeExpired(): Promise<number> };
+
+const canPurge = (limiter: AuthLimiter): limiter is PurgingAuthLimiter =>
+  typeof limiter.purgeExpired === 'function';
+
+/**
+ * Drop every failure past the window and every expired lockout the installed limiters left
+ * behind, and answer how many rows went. `0` when nothing was installed, or when what was
+ * installed keeps no rows.
+ *
+ * The WIDEST window wins, and only that limiter is swept. Every limiter here writes to the same
+ * two tables, so sweeping the narrow one would delete failures the wide one is still counting —
+ * which is a sprayer buying attempts back from the cleanup job. The same defect the http store's
+ * `purgeExpired(nowMs)` exists to prevent, one level up.
+ *
+ * No `nowMs` argument, unlike `postgresRateLimitStore.purgeExpired`: a limiter built through this
+ * seam already holds the clock its host handed it, and that is the clock every `at_ms` in those
+ * tables was written from. A second clock at the call site is exactly the mismatch that reads a
+ * frozen test clock as a 20,000,000-second refill.
+ */
+export async function purgeAuthLimits(): Promise<number> {
+  let widest: PurgingAuthLimiter | undefined;
+  for (const limiter of built) {
+    if (!canPurge(limiter)) continue;
+    if (widest === undefined || limiter.policy.windowMs > widest.policy.windowMs) widest = limiter;
+  }
+  return widest === undefined ? 0 : await widest.purgeExpired();
+}

package/src/memory-adapter.ts

@@ -14,6 +14,7 @@ import type {
   UserPatch,
   UserQuery,
 } from './adapter';
+import { authUniqueViolation } from './errors';
 import { timingSafeEqual } from './tokens';
 
 const verificationKey = (purpose: string, identifier: string): string => `${purpose}:${identifier}`;
@@ -43,7 +44,25 @@ export class MemoryAdapter implements AuthAdapter {
     return this.#users.get(id) ?? null;
   }
 
+  /**
+   * The two UNIQUE constraints `x_users` declares, enforced here because `BuiltinAdapter` LEANS on
+   * them: `email text not null unique` and `external_id text unique` (`tables.ts`). Without them
+   * this adapter — the one `x new` scaffolds and every test runs against — accepted two rows at one
+   * address, and the second was unreachable forever, since `findUserByEmail` returns the first.
+   *
+   * Over the STORED string, exactly as Postgres compares it. No case folding: that is the
+   * divergence `adapter-parity.test.ts`'s first case pins, and `normaliseEmail` above the seam is
+   * what makes two spellings one address.
+   */
   async createUser(input: CreateUserInput): Promise<AuthUser> {
+    for (const existing of this.#users.values()) {
+      if (existing.email === input.email) {
+        throw authUniqueViolation('createUser', 'x_users', 'email');
+      }
+      if (input.externalId !== undefined && existing.externalId === input.externalId) {
+        throw authUniqueViolation('createUser', 'x_users', 'external_id');
+      }
+    }
     const user: AuthUser = {
       id: input.id,
       // Stored as handed over, exactly as the `insert into x_users` binds it.

package/src/oauth-cookie.ts

@@ -7,8 +7,8 @@
 
 import type { Clock } from '@ultimat3/core';
 import { EnvMissingError, systemClock } from '@ultimat3/core';
-import { oauthStateInvalid } from './errors';
 import type { OAuthHandshake, OAuthProviderId } from './oauth';
+import { oauthStateInvalid } from './oauth-errors';
 import { hasOAuthProvider } from './oauth-registry';
 import { type RequestLike, readCookie } from './session';
 import { base64Url, timingSafeEqual } from './tokens';

package/src/oauth-discovery.ts

@@ -4,9 +4,9 @@
 // four endpoints that nobody re-checks when the vendor moves one.
 
 import { renderThrowable } from '@ultimat3/core';
-import { oauthExchangeFailed } from './errors';
 import { isRecord } from './json';
 import type { OAuthProvider } from './oauth';
+import { oauthExchangeFailed } from './oauth-errors';
 import type { OAuthFetch } from './oauth-exchange';
 
 const DEFAULT_TIMEOUT_MS = 10_000;

package/src/oauth-errors.ts

@@ -0,0 +1,178 @@
+// Single responsibility: the OAuth half of this package's error factories — every refusal a
+// provider handshake can produce, and the one phrase their fixes are built from.
+// Split from `errors.ts` at the 500-line ceiling; the codes, the titles and the single
+// `registerErrorCodes()` call stay there, so this file adds no code and registers nothing.
+
+import { renderCauseValue, renderFixLiteral } from '@ultimat3/core';
+import { AuthError } from './errors';
+import { oauthStartPath } from './oauth-paths';
+
+/**
+ * The `fix:` quotes `oauthStartPath` rather than a hand-written path. That is not tidiness: this
+ * line shipped naming `GET /auth/oauth/<provider>` while `@ultimat3/auth` mounted no route at all,
+ * so every caller who followed it hit a 404. One declaration, read by the mount and by the fix,
+ * is what stops that recurring — `oauthLogin()` cannot move without moving this sentence.
+ */
+export const oauthStateInvalid = (provider: string, part: string): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_STATE_INVALID',
+    cause: `${provider} callback rejected: ${part}`,
+    fix: `${restartAt(provider)} — a callback URL is single-use`,
+    meta: { provider },
+  });
+
+/** The one phrase every "start over" fix is built from, so none of them can name a dead route. */
+export const restartAt = (provider: string): string =>
+  `restart the flow at GET ${oauthStartPath(provider)}`;
+
+/**
+ * The provider came back with `error=` and no code — almost always the user pressing Cancel.
+ * A separate code from `X_OAUTH_EXCHANGE_FAILED` on purpose: nothing was exchanged, nothing is
+ * misconfigured, and folding the single commonest non-success outcome of a login into the code
+ * that means "the client secret is wrong" makes both unreadable in a log and pages the wrong person.
+ */
+export const oauthDenied = (
+  provider: string,
+  reason: string,
+  description: string | null,
+): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_DENIED',
+    // `reason` and `description` are query parameters off the callback URL — whatever the browser
+    // was redirected with, newlines and quotes included. `renderCauseValue` renders them as JSON
+    // string literals, so a forged `error_description` cannot forge a second log line or break the
+    // sentence around it. Both are already `string` by type: this is escaping, not throw-safety.
+    cause: `${provider} declined the authorization: ${renderCauseValue(reason)}${
+      description === null ? '' : ` (${renderCauseValue(description)})`
+    }`,
+    fix: `${restartAt(provider)} and approve the ${provider} consent screen`,
+    meta: { provider, reason },
+  });
+
+/**
+ * A URL segment naming a provider no `registerOAuthProvider` call has claimed, or one that is but
+ * was left out of `defineAuth({ providers })`. One refusal for both: which of the two it is
+ * describes the app's configuration to an unauthenticated caller, and the fix is the same sentence
+ * either way.
+ *
+ * **`supported` is the CALLER's to scope, because the two callers have two audiences.**
+ * `oauth-route.ts` passes `BUILTIN_OAUTH_PROVIDER_IDS` — its reader is an anonymous stranger who
+ * typed a URL, and the three built-ins are a framework constant already in the public docs, while
+ * the live registry holds whatever internal OP this deployment registered. `providerFor()` passes
+ * `oauthProviderIds()` — its reader is a developer holding a stack trace, and there the full list
+ * is exactly what makes the fix runnable. Neither ever passes `defineAuth({ providers })`: naming
+ * what this deployment turned on is the disclosure the shared refusal exists to prevent.
+ *
+ * The fix names `registerOAuthProvider` first so it stays executable for the branch the narrowed
+ * list cannot cover — a segment nothing registered cannot be added to `providers` at all, so
+ * "add it" alone was an instruction that could not be followed.
+ *
+ * The segment itself is a URL path the caller typed, so it goes through `renderCauseValue` in the
+ * sentence and `renderFixLiteral` in the command — a fix has to parse after a hostile value lands
+ * in it.
+ */
+export const oauthProviderUnknown = (provider: string, supported: readonly string[]): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_PROVIDER_UNKNOWN',
+    cause: `no oauth provider is mounted at ${renderCauseValue(oauthStartPath(provider))}`,
+    fix: `registerOAuthProvider({ id: ${renderFixLiteral(provider, '<id>')} }) if it is not built in, then add that id to defineAuth({ providers: [...] }) — known here: ${supported.map((id) => `'${id}'`).join(', ')}`,
+    meta: { provider },
+  });
+
+/**
+ * Two `registerOAuthProvider` calls claiming one id. A silent replacement would let whichever
+ * module imported second decide where every login for that id goes — including which `issuers`
+ * an id token may claim — so the second registration refuses at boot instead.
+ */
+export const oauthProviderDuplicate = (provider: string): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_PROVIDER_DUPLICATE',
+    cause: `an oauth provider is already registered as ${renderCauseValue(provider)}, so the second registration would silently replace the first`,
+    fix: `give one of them a different id, or delete the duplicate registerOAuthProvider({ id: ${renderFixLiteral(provider, '<id>')} }) call`,
+    meta: { provider },
+  });
+
+export interface OAuthExchangeFailure {
+  readonly provider: string;
+  /**
+   * Which leg of the server-to-server conversation failed. `discovery` and `jwks` are the two
+   * boot/verification legs an enterprise OP adds: reading `/.well-known/openid-configuration`,
+   * and reading the key set an id token's signature is checked against.
+   */
+  readonly stage: 'token' | 'userinfo' | 'discovery' | 'jwks';
+  readonly detail: string;
+  readonly status?: number | undefined;
+  readonly fix: string;
+}
+
+/**
+ * Deliberately specific, unlike every credential error above it. This one describes a
+ * conversation between two servers — naming the stage, the provider and its own status
+ * discloses nothing about any user, and is the difference between a fixable misconfiguration
+ * and a shrug.
+ */
+export const oauthExchangeFailed = (failure: OAuthExchangeFailure): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_EXCHANGE_FAILED',
+    cause:
+      `${failure.provider} ${failure.stage} request failed` +
+      `${failure.status === undefined ? '' : ` with HTTP ${failure.status}`}: ${failure.detail}`,
+    fix: failure.fix,
+    meta: {
+      provider: failure.provider,
+      stage: failure.stage,
+      ...(failure.status === undefined ? {} : { status: failure.status }),
+    },
+  });
+
+/**
+ * The address is proven to the provider, and an account that never proved it already holds it.
+ * Naming that is not account enumeration — this caller just demonstrated they own the address —
+ * and staying silent would leave them with a login that fails forever and no way out.
+ *
+ * The address itself rides in `meta`, never in `cause`: a log pipeline can redact a field by
+ * key, and cannot redact an address that was already interpolated into a sentence.
+ */
+export const oauthAccountNotLinked = (provider: string, email: string): AuthError =>
+  new AuthError({
+    code: 'X_UNAUTHENTICATED',
+    cause: `an account holds this ${provider} address but never verified it, so ${provider} may not claim it`,
+    fix: `sign in with that account's password and confirm the email-verify link, then retry ${provider}`,
+    meta: { provider, email },
+  });
+
+/**
+ * `link: 'never'` and a local account already holds the address. Same code and same disclosure
+ * rule as `oauthAccountNotLinked` — the caller proved to the provider that the address is theirs,
+ * so naming the collision is not enumeration — and the address rides in `meta`, never in `cause`.
+ */
+export const oauthLinkingDisabled = (provider: string, email: string): AuthError =>
+  new AuthError({
+    code: 'X_UNAUTHENTICATED',
+    cause: `an account already holds this address and defineAuth({ link: 'never' }) forbids ${provider} from claiming it`,
+    fix: "sign in with that account's own credentials, or set link: 'verified-email' in defineAuth to let a provider-verified address claim a locally-verified account",
+    meta: { provider, email },
+  });
+
+/**
+ * `CreateUserInput` carries no `emailVerifiedAt`, so a provider-verified address takes a second
+ * write. Falling back to the unstamped row would mint a session for a user every later login
+ * reads as unverified — the exact state `resolveUser` refuses to link a provider to — so the
+ * flow fails closed on an adapter that loses the stamp instead of half-succeeding.
+ */
+export const emailVerifiedNotStored = (provider: string, userId: string): AuthError =>
+  new AuthError({
+    code: 'X_NOT_IMPLEMENTED',
+    cause: `the adapter returned no row for new user ${userId}, so the ${provider}-verified address was never stamped verified`,
+    fix: 'return the updated row from AuthAdapter.updateUser — MemoryAdapter.updateUser is the reference implementation',
+    meta: { provider, userId },
+  });
+
+/** The token arrived, and is not one this handshake can trust: wrong `iss`, `aud`, or expired. */
+export const oauthTokenInvalid = (provider: string, reason: string, fix: string): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_TOKEN_INVALID',
+    cause: `${provider} id token rejected: ${reason}`,
+    fix,
+    meta: { provider },
+  });

package/src/oauth-exchange.ts

@@ -4,8 +4,13 @@
 // token is verified here, so no caller downstream can forget to.
 
 import type { Clock } from '@ultimat3/core';
-import { EnvMissingError, renderCauseValue, renderThrowable, systemClock } from '@ultimat3/core';
-import { oauthExchangeFailed, restartAt } from './errors';
+import {
+  EnvMissingError,
+  logger,
+  renderCauseValue,
+  renderThrowable,
+  systemClock,
+} from '@ultimat3/core';
 import { type IdTokenClaims, verifyIdToken } from './id-token';
 import { isRecord } from './json';
 import type { IdTokenKeys } from './jwks';
@@ -15,6 +20,7 @@ import {
   type OAuthHandshake,
   type OAuthProviderId,
 } from './oauth';
+import { oauthExchangeFailed, restartAt } from './oauth-errors';
 import { providerFor } from './oauth-registry';
 
 /** Just the call. `typeof fetch` also carries `preconnect`, which no test double should have to. */
@@ -91,7 +97,31 @@ export function oauthCredentials(
  * mostly prose this package authored, and quoting that would make every readable message unread-
  * able. The rule is "remote text is rendered", and this function is where remote text is made.
  */
-export async function providerDetail(response: Response): Promise<string> {
+/**
+ * How much of a body this leg may quote back.
+ *
+ * `'raw'` — the default and what userinfo, discovery and jwks use: those requests carry a bearer
+ * token or nothing, and the raw text is what makes a misconfigured enterprise OP debuggable.
+ *
+ * `'coded-only'` — the `POST /token` leg, and ONLY it. That request carries `client_secret`, and
+ * an endpoint that echoes what it was sent (compromised, impersonated, or a misbehaving gateway)
+ * put the secret into an `X_OAUTH_EXCHANGE_FAILED` `cause:` that `oauth-route.ts` publishes to an
+ * unauthenticated caller. Measured: 38 of 42 characters of the secret reached the response body,
+ * and a shorter `redirect_uri` fits all of it inside `MAX_DETAIL_LENGTH`. A coded OAuth error
+ * still comes through — `invalid_grant`, `redirect_uri_mismatch` — because that is a field the
+ * SPEC defines and the whole reason this string exists.
+ */
+export type DetailEcho = 'raw' | 'coded-only';
+
+/** What a `coded-only` leg says instead of the body. Names why, so nobody re-adds the echo. */
+const OPAQUE_BODY =
+  'the endpoint answered with a body that is not a coded OAuth error, and this leg does not quote ' +
+  'one back because its request carries the client secret';
+
+export async function providerDetail(
+  response: Response,
+  echo: DetailEcho = 'raw',
+): Promise<string> {
   const text = await response.text().catch(() => '');
   if (text === '') return 'the response body was empty';
   try {
@@ -105,6 +135,7 @@ export async function providerDetail(response: Response): Promise<string> {
   } catch {
     // Not JSON — fall through to the truncated raw text below.
   }
+  if (echo === 'coded-only') return OPAQUE_BODY;
   return renderCauseValue(
     text.length > MAX_DETAIL_LENGTH ? `${text.slice(0, MAX_DETAIL_LENGTH)}…` : text,
   );
@@ -143,16 +174,31 @@ async function postForm(
       signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
     });
   } catch (error) {
-    // `renderThrowable`, never `error.message` behind an `instanceof`: the rejection comes from
-    // an injected `fetch`, and `instanceof` itself throws on a value whose `getPrototypeOf` trap
-    // does — losing the one refusal that tells a caller the code is already spent.
-    const reason = renderThrowable(error);
+    // The rendered value goes to the LOG, never into the `detail:`.
+    //
+    // `oauth-route.ts` publishes this cause to an unauthenticated caller, and the rejection comes
+    // from an injected `OAuthFetch` — an app's own wrapper, a proxy client, an adapter behind it —
+    // so its text is a server's internals. Reproduced: a bare
+    // `Error('connect ECONNREFUSED 10.4.2.17:5432 (postgres://app:hunter2@db.internal/prod)')`
+    // was served as the 502 body of a public callback. `problem()`'s uncoded branch does NOT catch
+    // this one: it is coded by the time it gets there.
+    //
+    // `renderThrowable`, never `error.message` behind an `instanceof`: `instanceof` itself throws
+    // on a value whose `getPrototypeOf` trap does, losing the one refusal that tells a caller the
+    // code is already spent. What stays in the sentence is `url` and the remedy, both framework
+    // constants, so the failure is still fixable without quoting anything this package does not own.
+    logger.error('auth.oauth.token_fetch_failed', {
+      provider,
+      url,
+      detail: renderThrowable(error),
+    });
     throw oauthExchangeFailed({
       provider,
       stage: 'token',
       detail:
-        `${reason} — nothing left this host for ${url} (egress, DNS or TLS); restart the ` +
-        'flow once it does, since the code is already spent',
+        `nothing left this host for ${url} (egress, DNS or TLS); the reason is in this process ` +
+        'log under auth.oauth.token_fetch_failed. Restart the flow once it does, since the code ' +
+        'is already spent',
       fix: `curl -sS -m 5 -o /dev/null ${url}`,
     });
   }
@@ -161,7 +207,9 @@ async function postForm(
     throw oauthExchangeFailed({
       provider,
       stage: 'token',
-      detail: await providerDetail(response),
+      // `coded-only`: this request carried `client_secret`, and `oauth-route.ts` publishes this
+      // cause to whoever typed the URL.
+      detail: await providerDetail(response, 'coded-only'),
       status: response.status,
       fix: fixForStatus(provider, response.status),
     });

package/src/oauth-login.ts

@@ -7,16 +7,15 @@ import { ConfigInvalidError, logger, uuid } from '@ultimat3/core';
 import type { AuthAccount, AuthUser } from './adapter';
 import type { Auth, LoginResult } from './auth';
 import { normaliseEmail } from './email';
+import { authWriteFailed, mfaRequired } from './errors';
+import type { OAuthCallback, OAuthHandshake } from './oauth';
 import {
-  authWriteFailed,
   emailVerifiedNotStored,
-  mfaRequired,
   oauthAccountNotLinked,
   oauthExchangeFailed,
   oauthLinkingDisabled,
   restartAt,
-} from './errors';
-import type { OAuthCallback, OAuthHandshake } from './oauth';
+} from './oauth-errors';
 import {
   exchangeOAuthCode,
   type OAuthClientCredentials,
@@ -200,8 +199,20 @@ function accountFor(auth: Auth, user: AuthUser, input: OAuthSignInInput): AuthAc
     userId: user.id,
     provider: input.profile.provider,
     providerAccountId: input.profile.providerAccountId,
-    accessToken: input.tokens.accessToken,
-    refreshToken: input.tokens.refreshToken,
+    // `null`, deliberately — this package does not persist a provider credential.
+    //
+    // `x_accounts.access_token` and `refresh_token` held live provider tokens in the CLEAR, under
+    // a `tables.ts` header promising "no column holds a plaintext secret", and NOTHING read either
+    // one back: `oauth-profile.ts` uses the token from the exchange, in flight, and
+    // `packages/auth/CLAUDE.md` states that refresh is not implemented. Declared and never wired
+    // — the same deletion this repo already ran for `jobs.driver`, except this one made a database
+    // dump into a set of usable third-party credentials.
+    //
+    // The TYPE keeps both fields: `AuthAccount` is the documented adapter seam, and an app that
+    // deliberately stores tokens implements `linkAccount` itself. What changed is what the
+    // framework writes.
+    accessToken: null,
+    refreshToken: null,
     expiresAt: input.tokens.expiresAt,
     createdAt: auth.clock.now(),
   };

package/src/oauth-profile.ts

@@ -4,10 +4,10 @@
 // decides whether this login may attach itself to an existing account by address.
 
 import { logger, renderThrowable } from '@ultimat3/core';
-import { oauthExchangeFailed, restartAt } from './errors';
 import { idTokenEmailVerified, isVerifiedFlag } from './id-token';
 import { isRecord } from './json';
 import type { OAuthProviderId } from './oauth';
+import { oauthExchangeFailed, restartAt } from './oauth-errors';
 import {
   OAUTH_USER_AGENT,
   type OAuthFetch,

package/src/oauth-registry.ts

@@ -5,9 +5,9 @@
 // account linking with it. The three built-ins register through the same call an app uses, so the
 // opening does not create a second path.
 
-import { oauthProviderDuplicate, oauthProviderUnknown } from './errors';
 import type { OAuthProvider } from './oauth';
 import { BUILTIN_OAUTH_PROVIDERS } from './oauth-builtins';
+import { oauthProviderDuplicate, oauthProviderUnknown } from './oauth-errors';
 
 const registry = new Map<string, OAuthProvider>();