@ultimat3/auth 9.0.0 → 10.0.0

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>();
 

package/src/oauth-route.ts

@@ -8,12 +8,18 @@
 // is tier 4 and describes a rendered page. A bare `Request` in, a `Response` out, drivable from
 // a test and mountable by any router that can match a `:param`.
 
-import { type Clock, isUltimateError, renderThrowable, type UltimateError } from '@ultimat3/core';
+import {
+  type Clock,
+  isUltimateError,
+  logger,
+  renderThrowable,
+  type UltimateError,
+} from '@ultimat3/core';
 import type { Auth, LoginResult } from './auth';
-import { oauthDenied, oauthExchangeFailed, oauthProviderUnknown } from './errors';
 import { beginOAuth, type OAuthProviderId } from './oauth';
 import { BUILTIN_OAUTH_PROVIDER_IDS } from './oauth-builtins';
 import { clearHandshakeCookie, handshakeCookie, readHandshakeCookie } from './oauth-cookie';
+import { oauthDenied, oauthExchangeFailed, oauthProviderUnknown } from './oauth-errors';
 import type { OAuthClientCredentials, OAuthFetch } from './oauth-exchange';
 import { oauthCredentials } from './oauth-exchange';
 import { completeOAuthLogin, type ResolveOAuthGrants } from './oauth-login';
@@ -101,6 +107,24 @@ export const OAUTH_ROUTE_STATUS: Readonly<Record<string, number>> = {
   X_CONFIG_INVALID: 500,
 };
 
+/**
+ * The status for a code, read as an OWN key of the table above.
+ *
+ * `OAUTH_ROUTE_STATUS[code] ?? 502` is an index read on a plain object, so `Object.prototype`
+ * answered for `toString`, `constructor`, `hasOwnProperty` and `__proto__` — and `toString`
+ * yields a FUNCTION, which was handed straight to `ResponseInit.status`. `code` is a plain
+ * `string` on every `UltimateError`, so no cast makes that unreachable. Fourth instance of the
+ * class in the framework, after i18n's catalog lookup, schema's `coerce` and mcp's `validate-args`.
+ *
+ * Exported so a test can drive it without building a `Response`; `OAUTH_ROUTE_STATUS` stays
+ * exported unchanged, because `scripts/oauth-route-status.test.ts` pins it against
+ * `@ultimat3/http`'s `statusFor`.
+ */
+export function oauthRouteStatus(code: string): number {
+  // 502 is the default: an uncoded throw on this path came out of the provider conversation.
+  return Object.hasOwn(OAUTH_ROUTE_STATUS, code) ? (OAUTH_ROUTE_STATUS[code] ?? 502) : 502;
+}
+
 /**
  * What an anonymous caller is allowed to read. `UltimateError.toJSON()` carries `meta` and `stack`
  * — a developer's fields — and BOTH legs of this flow are public by definition, so serialising it
@@ -122,26 +146,42 @@ const publicBody = (coded: UltimateError): Record<string, string> => ({
  * wants a rendered page wraps these two descriptors; the framework ships the debuggable answer.
  */
 function problem(error: unknown, extraCookies: readonly string[]): Response {
-  const coded = isUltimateError(error)
-    ? error
-    : oauthExchangeFailed({
-        provider: 'oauth',
-        stage: 'token',
-        // `renderThrowable`, never `error.message`: the throw came from an adapter or a `fetch`
-        // this package does not own, and a getter on `message` — or a `Proxy` trapping
-        // `getPrototypeOf` — would make the callback's last answer throw instead of send.
-        detail: renderThrowable(error),
-        fix: 'throw an UltimateError from the AuthAdapter or OAuthFetch that failed — the factories are in packages/auth/src/errors.ts',
-      });
+  const coded = isUltimateError(error) ? error : uncoded(error);
   const headers = new Headers({ 'content-type': 'application/json; charset=utf-8' });
   for (const cookie of extraCookies) headers.append('set-cookie', cookie);
   return new Response(JSON.stringify(publicBody(coded)), {
-    // 502 is the default: an uncoded throw on this path came out of the provider conversation.
-    status: OAUTH_ROUTE_STATUS[coded.code] ?? 502,
+    status: oauthRouteStatus(coded.code),
     headers,
   });
 }
 
+/**
+ * A throw with no code: a bug in an `AuthAdapter` or an `OAuthFetch` this package does not own.
+ *
+ * Its text goes to the LOG and never into the response. `publicBody` publishes `cause`, and the
+ * rendered value went straight into it — so a bare
+ * `Error('connect ECONNREFUSED 10.4.2.17:5432 (postgres://app:hunter2@db.internal/prod)')` from a
+ * pool inside a callback was served to whoever typed the URL, as a 502 with the connection string
+ * in the body. The comment above `publicBody` says a stack and `meta` must never reach that
+ * reader; the field carrying the message was the one exception nobody meant to make.
+ *
+ * `renderThrowable`, never `error.message`: the value came from code this package does not own,
+ * and a getter on `message` — or a `Proxy` trapping `getPrototypeOf` — would make the callback's
+ * last answer throw instead of send. Same shape `rate-limit.ts`'s `loginFailed()` uses: one fixed
+ * sentence outward, the discriminating detail kept where only an operator can read it.
+ */
+function uncoded(error: unknown): UltimateError {
+  logger.error('auth.oauth.uncoded_failure', { detail: renderThrowable(error) });
+  return oauthExchangeFailed({
+    provider: 'oauth',
+    stage: 'token',
+    detail:
+      'an adapter or fetch this package does not own threw a value with no error code; the ' +
+      'detail is in this process log under auth.oauth.uncoded_failure',
+    fix: 'throw an UltimateError from the AuthAdapter or OAuthFetch that failed — the factories are in packages/auth/src/errors.ts, and the OAuth ones in packages/auth/src/oauth-errors.ts',
+  });
+}
+
 /** `/auth/oauth/github` → `github`; `/auth/oauth/github/callback` → `github`. */
 function providerSegment(request: Request, leg: 'start' | 'callback'): string {
   const segments = new URL(request.url).pathname.split('/').filter((s) => s.length > 0);
@@ -173,6 +213,37 @@ function assertEnabled(auth: Auth, segment: string): OAuthProviderId {
   return provider;
 }
 
+/**
+ * The credentials for a provider, or the SAME 404 an unknown provider gets.
+ *
+ * `assertEnabled` collapses "never heard of it" and "not enabled here" into one answer so an
+ * anonymous caller cannot enumerate this deployment's configuration. Past it, `oauthCredentials`
+ * threw `X_ENV_MISSING` and `problem()` answered 500 — publishing the app's own environment
+ * variable names in the `cause` and, worse, restoring the oracle: 500 meant "registered here",
+ * 404 meant "not". A provider with no credentials is not usable, which is the only thing this
+ * caller is entitled to learn.
+ *
+ * The real cause is not lost: `X_ENV_MISSING`'s `cause` and `fix` are the operator's, and they go
+ * to the process log where only an operator can read them.
+ */
+function credentialsFor(
+  provider: OAuthProviderId,
+  options: OAuthLoginOptions,
+): OAuthClientCredentials {
+  if (options.credentials !== undefined) return options.credentials;
+  try {
+    return oauthCredentials(provider, options.env ?? Bun.env);
+  } catch (error) {
+    if (!isUltimateError(error) || error.code !== 'X_ENV_MISSING') throw error;
+    logger.error('auth.oauth.credentials_missing', {
+      provider,
+      cause: error.cause,
+      fix: error.fix,
+    });
+    throw oauthProviderUnknown(provider, BUILTIN_OAUTH_PROVIDER_IDS);
+  }
+}
+
 function originFor(request: Request, options: OAuthLoginOptions): string {
   const env = options.env ?? Bun.env;
   const declared = options.baseUrl ?? env['APP_URL']?.trim() ?? '';
@@ -195,7 +266,7 @@ async function startHandler(
 ): Promise<Response> {
   try {
     const provider = assertEnabled(auth, providerSegment(request, 'start'));
-    const credentials = options.credentials ?? oauthCredentials(provider, options.env ?? Bun.env);
+    const credentials = credentialsFor(provider, options);
     const handshake = beginOAuth({
       provider,
       clientId: credentials.clientId,
@@ -233,6 +304,10 @@ async function callbackHandler(
   const clear = hasOAuthProvider(segment) ? [clearHandshakeCookie(segment)] : [];
   try {
     const provider = assertEnabled(auth, segment);
+    // Asked here purely so a provider with no credentials answers 404 on THIS leg too: the
+    // exchange below resolves them again from the same two sources. One oracle, closed on both
+    // halves — a 404 on start and a 500 on callback is the same enumeration one request later.
+    credentialsFor(provider, options);
     const url = new URL(request.url);
     assertNoProviderError(url, provider);
     const result: LoginResult = await completeOAuthLogin(auth, {

package/src/oauth.ts

@@ -4,7 +4,7 @@
 // configs are pure data and live in `oauth-registry.ts`: importing this file performs no network
 // I/O and reads no env.
 
-import { oauthStateInvalid } from './errors';
+import { oauthStateInvalid } from './oauth-errors';
 import { providerFor } from './oauth-registry';
 import { base64Url, randomToken, sha256Bytes, timingSafeEqual } from './tokens';
 

package/src/tables.ts

@@ -1,6 +1,29 @@
 // Single responsibility: the DDL `BuiltinAdapter` expects. Exported as plain strings so an app
-// can paste them into a migration and read exactly what auth stores — no column holds a
-// plaintext secret, and that is meant to be verifiable by reading, not by trusting.
+// can paste them into a migration and read EXACTLY what auth stores — verifiable by reading,
+// never by trusting.
+//
+// What is at rest, stated column by column rather than as a claim:
+//
+// | Column | Holds |
+// |---|---|
+// | `x_users.password_hash` | an argon2id digest, never the password |
+// | `x_users.recovery_code_hashes` | SHA-256 digests, never the codes (`mfa.ts`) |
+// | `x_users.mfa_secret` | **the base32 TOTP seed, in the clear** — see below |
+// | `x_accounts.access_token` / `refresh_token` | **nothing.** The framework writes `null` |
+// | `x_sessions.*`, `x_verifications.token_hash` | digests and metadata, never a token |
+//
+// `mfa_secret` is the one plaintext secret this schema still holds, and it is stated here rather
+// than glossed: a TOTP seed is symmetric, so verifying a code requires the seed itself and a
+// digest cannot replace it. Encrypting it needs a key-management seam this package does not have,
+// which is a design change and not a patch — DEFERRED, deliberately, and written down so nobody
+// reads the header above as covering it. `mfa.ts`'s "a database dump is not a permanent MFA
+// bypass" is true of the recovery CODES and not of the seed.
+//
+// The two `x_accounts` token columns are kept in the DDL and written `null`: they held live
+// provider credentials in the clear and nothing in this package ever read them back
+// (`oauth-login.ts`'s `accountFor`). The columns stay so an app that deliberately stores tokens
+// through its own `linkAccount` has somewhere to put them, and so an existing deployment needs
+// no migration to stop.
 
 export const X_USERS_TABLE = `create table if not exists x_users (
   id                    uuid primary key,
@@ -12,6 +35,8 @@ export const X_USERS_TABLE = `create table if not exists x_users (
   permissions           text[] not null default '{}',
   scopes                text[] not null default '{}',
   external_id           text unique,
+  -- The base32 TOTP seed, in the clear. A seed is symmetric: a digest cannot verify a code.
+  -- Encryption at rest is deferred and needs a key-management seam - see the header.
   mfa_secret            text,
   recovery_code_hashes  text[] not null default '{}',
   disabled_at           timestamptz,
@@ -52,6 +77,8 @@ export const X_ACCOUNTS_TABLE = `create table if not exists x_accounts (
   user_id               uuid not null references x_users (id) on delete cascade,
   provider              text not null,
   provider_account_id   text not null,
+  -- Written NULL by the framework. Nothing reads them back, and a live provider credential at
+  -- rest turns a database dump into third-party access. Kept for an app's own linkAccount().
   access_token          text,
   refresh_token         text,
   expires_at            timestamptz,

package/src/verify.ts

@@ -5,6 +5,7 @@
 
 import type { Clock } from '@ultimat3/core';
 import type { AuthVerification, VerificationStore } from './adapter';
+import { normaliseEmail } from './email';
 import { AuthError } from './errors';
 import { randomToken, sha256Hex, timingSafeEqual } from './tokens';
 
@@ -68,10 +69,17 @@ export async function issueVerification(
   const token = randomToken(32);
   const ttl = input.ttlMs ?? DEFAULT_VERIFICATION_TTL_MS[input.purpose];
   const expiresAt = new Date(now.getTime() + ttl);
+  // The FOURTH identity door, and the one that did not normalise: `register`, `login`,
+  // `profileEmail` and `accountKey` all do. `putVerification` upserts on `(purpose, identifier)`
+  // and `adapter.ts` promises that "issuing a new token invalidates the previous one" — a promise
+  // that was per SPELLING, so N live reset tokens for one address could be held at once by varying
+  // the case, and each one of them is a password. It is also the address the mail is sent to, so
+  // the link goes to the inbox the account is keyed by rather than to whatever a form posted.
+  const identifier = normaliseEmail(input.identifier);
   await runtime.store.putVerification({
     id: randomToken(12),
     purpose: input.purpose,
-    identifier: input.identifier,
+    identifier,
     tokenHash: sha256Hex(token),
     expiresAt,
     consumedAt: null,
@@ -79,7 +87,7 @@ export async function issueVerification(
   });
   await runtime.mail.send(
     VERIFICATION_TEMPLATES[input.purpose],
-    input.identifier,
+    identifier,
     {
       ...(input.data ?? {}),
       link: input.link?.(token) ?? token,
@@ -119,7 +127,13 @@ export async function consumeVerification(
   input: ConsumeVerificationInput,
 ): Promise<AuthVerification> {
   const tokenHash = sha256Hex(input.token);
-  const record = await runtime.store.takeVerification(input.purpose, input.identifier, tokenHash);
+  // Normalised on the way OUT as well as in, or a link issued for `ada@x.test` is unredeemable by
+  // a form that posted `Ada@X.test` — one door, one key.
+  const record = await runtime.store.takeVerification(
+    input.purpose,
+    normaliseEmail(input.identifier),
+    tokenHash,
+  );
   if (record === null) throw verificationInvalid(input.purpose);
   // Kept for the seam, not for the blessed adapters: `VerificationStore` is implementable by an
   // app, and one that ignores the third argument would otherwise redeem any token. Constant-time