@ultimat3/auth 9.0.0 → 10.0.0

package/CLAUDE.md

@@ -202,7 +202,7 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   provider, so it is unrepresentable rather than discouraged. An app that wants it wraps
   `signInWithOAuth`.
 - **The OAuth route paths are not configurable.** `oauth-paths.ts` imports nothing and is
-  read by both `errors.ts` and `oauth-route.ts`, so a `fix:` line naming
+  read by both `oauth-errors.ts` and `oauth-route.ts`, so a `fix:` line naming
   `GET /auth/oauth/<provider>` cannot outlive the route again — which is exactly what it did
   through 1.2.0, when the library functions shipped with no route to mount them in. Every
   "start over" fix is built from `restartAt(provider)`.
@@ -214,9 +214,60 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   implementation of the open-redirect check and a second copy is one that drifts.
 - The handshake cookie is cleared on **every** callback outcome, success and failure alike:
   the code it authorised is spent either way.
-- Refresh is **not implemented**. `AuthAccount` persists `refreshToken` and `expiresAt`, and
-  nothing reads them yet — the session is the framework's own credential and does not depend
-  on the provider token.
+- Refresh is **not implemented**, and the framework therefore **stores no provider token** (`As of
+  2026-08-23`). `accountFor` (`oauth-login.ts`) writes `accessToken: null, refreshToken: null`:
+  nothing in this package ever read either column back — `oauth-profile.ts` uses the token from the
+  exchange, in flight — while `tables.ts`'s header promised "no column holds a plaintext secret".
+  Declared and never wired, the deletion this repo already ran for `jobs.driver`, except this one
+  turned a database dump into a set of usable third-party credentials. The COLUMNS and the
+  `AuthAccount` fields both stay: the type is the documented adapter seam, and an app that
+  deliberately stores tokens implements `linkAccount` itself. `expiresAt` is still written.
+- **`defineAuth({ providers })` defaults to `[]`**, never the live registry (`As of 2026-08-23`,
+  BREAKING). It was `oauthProviderIds()`, so nothing was ever "left out" and the uniform-404 the
+  option exists for could not fire — while a registry any dependency writes into decided which
+  login endpoints the app served. Name what you enabled.
+- **A provider with no credentials answers the SAME 404 an unknown one does.** Past `assertEnabled`,
+  `oauthCredentials` threw `X_ENV_MISSING` and the route published a 500 carrying the app's own env
+  var names, so `500 = registered here, 404 = not` re-opened the oracle one request later.
+  `credentialsFor` (`oauth-route.ts`) catches it on BOTH legs, logs the real cause under
+  `auth.oauth.credentials_missing`, and re-throws `oauthProviderUnknown`.
+- **Nothing this package does not own reaches a published `cause:`.** Both legs of the OAuth flow
+  are anonymous by definition and `publicBody` serialises `cause`. Two paths carried an internal
+  message into it and both now log instead: an uncoded throw from an adapter (`uncoded()` in
+  `oauth-route.ts` → `auth.oauth.uncoded_failure`) and a rejecting `OAuthFetch`
+  (`postForm` → `auth.oauth.token_fetch_failed`). The `POST /token` leg also reads its response
+  body as `providerDetail(response, 'coded-only')` — that request carries `client_secret`, and an
+  echoing endpoint put 38 of 42 characters of it into a 502 body. `error`/`error_description` still
+  come through; userinfo, discovery and jwks keep the raw fallback, because their requests carry
+  no secret.
+- **`x_users.mfa_secret` is a PLAINTEXT secret and `tables.ts` now says so, column by column.** A
+  TOTP seed is symmetric, so a digest cannot verify a code; encrypting it needs a key-management
+  seam this package does not have. **Deferred deliberately** — `mfa.ts`'s "a database dump is not a
+  permanent MFA bypass" is true of the recovery CODES and not of the seed.
+- **`issueVerification`/`consumeVerification` normalise too** — the fourth identity door.
+  `putVerification` upserts on `(purpose, identifier)` and `adapter.ts` promises a new token
+  invalidates the previous one; that promise was per SPELLING, so N live reset tokens for one
+  address could be held at once by varying the case, and each is a password.
+- **`providerJwks` memoises only the DEFAULT client.** The memo was keyed on the provider id alone
+  and silently discarded a later caller's options, so an app pinning a corporate egress proxy got
+  it only if it called first — the `jobs.driver` shape, with a network path as the substituted
+  value. A caller that supplies options gets its own client.
+- **`verifyIdToken` checks `nbf` and `azp`.** `workload.ts` imports `ID_TOKEN_CLOCK_SKEW_MS` from
+  `id-token.ts` and then enforced a bound `id-token.ts` did not: an `nbf` ten years out verified.
+  `azp` is OIDC Core 3.1.3.7 step 5 — with more than one audience, `aud` naming this client says
+  only that the token MENTIONS it. Both only narrow what is accepted.
+- **A success clears the ACCOUNT bucket and nothing else.** `recordSuccess(ipKey(ip))` used to run
+  on every login and deleted the whole address bucket, which made it inert against the attack it
+  exists for: a stuffing run never spends `maxAttempts` guesses on one account, so
+  `4 wrong + 1 login to an account the attacker owns, repeat` never locked. Measured: 5 guesses to
+  `X_ACCOUNT_LOCKED` without the reset, 160 and unlocked with it. The cost is a shared NAT
+  accumulating failures, which is what `windowMs` bounds and what `X_ACCOUNT_LOCKED`'s `fix:`
+  already names the manual escape for.
+- **`MemoryAdapter.createUser` enforces the two UNIQUE constraints `BuiltinAdapter` leans on** —
+  `x_users.email` and `x_users.external_id`, `authUniqueViolation` (`X_AUTH_WRITE_FAILED`). It is
+  what `x new` scaffolds and what every test runs against, so the duplicate path was only ever
+  exercised against the permissive half of the seam: two `register()` calls at one address made two
+  rows, and the second was unreachable forever. `adapter-parity.test.ts` pins both halves.
 - The new `AuthAdapter` members are OPTIONAL (`findUserByExternalId`, `listUsersByOrg`,
   `deleteSessionsForUser`, `deleteSessionsForOrg`, `deleteSessionsCreatedBefore`). A required
   member is a breaking change to every third-party adapter; the callers throw
@@ -329,6 +380,8 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | `oauth-login.ts` | profile → account link → session. `completeOAuthLogin` is the entry point |
 | `oauth-login-fixture.ts` | the adapter, clock and profile the three `oauth-login*` suites share. Off `index.ts` |
 | `oauth-paths.ts` | the one declaration of where the two routes live. Imports nothing |
+| `errors.ts` | the codes this package owns and borrows, their titles, the one `registerErrorCodes()` call, `AuthError`, and every non-OAuth factory |
+| `oauth-errors.ts` | the OAuth half of those factories, and `restartAt`. Split off at the 500-line ceiling; declares no code and registers nothing |
 | `oauth-route.ts` | `oauthLogin(auth)` — the redirect out and the callback back |
 | `kdf-gate.ts` | the one bound on concurrent argon2 work, and the `X_OVERLOADED` past it |
 | `email.ts` | `normaliseEmail` — the one normalisation an address gets before it is an identity key |

package/README.md

@@ -12,7 +12,7 @@ export const auth = defineAuth({
   session: { absoluteTtlMs: 30 * 864e5, idleTtlMs: 7 * 864e5 },
   password: { minLength: 12 },
   mfa: { issuer: 'Acme' },                // the authenticator app's name; `required` only as `false`
-  providers: ['github', 'google'],
+  providers: ['github', 'google'],       // REQUIRED to serve any OAuth route — the default is []
   link: 'verified-email',                 // the default; `'never'` is the only other value
 });
 
@@ -223,7 +223,7 @@ registerOAuthProvider(await discoverOAuthProvider({ id: 'bigco-sso', issuer: 'ht
 | `providerFor(id)` | the provider, or throws `X_OAUTH_PROVIDER_UNKNOWN` — never `undefined` |
 | `hasOAuthProvider(id)` | whether the id is registered |
 | `BUILTIN_OAUTH_PROVIDER_IDS` | the three shipped ids — the only list an **anonymous** refusal names |
-| `oauthProviderIds()` | every registered id, live — `defineAuth({ providers })` defaults to it |
+| `oauthProviderIds()` | every registered id, live. **NOT** what `defineAuth({ providers })` defaults to — that is `[]`, so an app names what it enabled |
 
 `discoverOAuthProvider` refuses a document with no `jwks_uri`: without a key set there is nothing
 to check an id token's signature against, and the token-endpoint TLS exemption below is a thing a
@@ -644,7 +644,7 @@ An api key's scopes become **exactly** the agent actor's scopes — never the ow
 | `X_OAUTH_STATE_INVALID` | state, nonce or PKCE verifier did not match |
 | `X_OAUTH_EXCHANGE_FAILED` | the provider refused the exchange, or returned no usable identity |
 | `X_OAUTH_TOKEN_INVALID` | the id token failed its signature, issuer, audience or expiry check, or no key in the published set matched its `kid` |
-| `X_OAUTH_PROVIDER_UNKNOWN` | the URL named a provider nothing registered, or one `defineAuth({ providers })` did not enable — the route's refusal lists only the three built-ins, never your registry |
+| `X_OAUTH_PROVIDER_UNKNOWN` | the URL named a provider nothing registered, one `defineAuth({ providers })` did not enable, or one whose `*_CLIENT_ID`/`*_CLIENT_SECRET` are unset — all three answer 404 with the same body, because telling an anonymous caller which is which describes this deployment for free. The real reason is logged. The refusal lists only the three built-ins, never your registry |
 | `X_OAUTH_PROVIDER_DUPLICATE` | two `registerOAuthProvider` calls claimed one id — at boot, never at a login |
 | `X_OAUTH_DENIED` | the user pressed Cancel, or the provider declined — `403`, never a `502` |
 | `X_PASSWORD_WEAK` | strength check rejected the password |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "9.0.0",
+  "version": "10.0.0",
   "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
   "license": "MIT",
   "type": "module",
@@ -31,8 +31,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "9.0.0",
-    "@ultimat3/db": "9.0.0",
-    "@ultimat3/schema": "9.0.0"
+    "@ultimat3/core": "10.0.0",
+    "@ultimat3/db": "10.0.0",
+    "@ultimat3/schema": "10.0.0"
   }
 }

package/src/auth.ts

@@ -10,7 +10,6 @@ import { normaliseEmail } from './email';
 import { mfaRequired, mfaRequiredUnenforceable, sessionUnknown } from './errors';
 import { installedAuthLimiter } from './limiter-install';
 import type { OAuthProviderId } from './oauth';
-import { oauthProviderIds } from './oauth-registry';
 import {
   checkPasswordStrength,
   DEFAULT_PASSWORD_POLICY,
@@ -147,6 +146,11 @@ export interface AuthConfigInput {
    */
   readonly orgLimiter?: AuthLimiter | undefined;
   readonly mfa?: Partial<AuthMfaPolicy> | undefined;
+  /**
+   * The OAuth providers this app serves login routes for. Defaults to `[]` — an empty list is
+   * "no OAuth", and every `/auth/oauth/<id>` answers `X_OAUTH_PROVIDER_UNKNOWN`. Never the live
+   * registry, which a dependency can write into.
+   */
   readonly providers?: readonly OAuthProviderId[] | undefined;
   /** Defaults to `'verified-email'` — both halves proven. See `OAuthLinkPolicy`. */
   readonly link?: OAuthLinkPolicy | undefined;
@@ -213,7 +217,17 @@ export function defineAuth(config: AuthConfigInput): Auth {
     orgRateLimit: orgLimiter.policy,
     orgLimiter,
     mfa,
-    providers: config.providers ?? oauthProviderIds(),
+    // BREAKING (majors only): the default is `[]`, never the live registry.
+    //
+    // It was `oauthProviderIds()`, so `defineAuth({ providers })`'s own documented purpose — the
+    // uniform 404 for a provider this app "left out" — could never fire: nothing was ever left
+    // out. Worse, a registry any dependency writes into with `registerOAuthProvider` decided which
+    // login endpoints an app serves. A capability is DECLARED, never inherited.
+    //
+    // Migration is one line: `defineAuth({ providers: ['github', 'google'] })`, naming what the app
+    // actually enabled. Nothing else changes — an unnamed provider is the 404 it was always meant
+    // to be.
+    providers: config.providers ?? [],
     link: config.link ?? 'verified-email',
   });
 }
@@ -286,10 +300,21 @@ export async function login(auth: Auth, input: LoginInput): Promise<LoginResult>
   }
 
   await auth.limiter.recordSuccess(account);
-  if (ip !== null) await auth.limiter.recordSuccess(ipKey(ip));
-  // No `recordSuccess` on the tenant bucket, and that asymmetry is the point: one member signing
-  // in successfully must not clear the count a broken integration is running up beside them, or
-  // the tenant cap is cleared by exactly the traffic that proves the tenant is still in use.
+  // ONLY the account bucket is cleared. The ACCOUNT window belongs to one person, so a success
+  // proves the typos before it were theirs and clearing it is what stops a typo costing a lockout.
+  //
+  // Neither the IP nor the tenant bucket is cleared, and it is the same argument for both: they
+  // count traffic from a SHARED source, so a success is not evidence the failures beside it were
+  // benign. `recordSuccess(ipKey(ip))` used to run here and deleted the whole address bucket —
+  // which made it inert against the attack it exists for. A credential-stuffing run never spends
+  // `maxAttempts` guesses on one account, so the per-account bucket never fires; the address
+  // bucket is the only one that sees the pattern, and `4 wrong guesses + 1 login to an account
+  // the attacker owns, repeat` wiped it every fifth request. Measured: 5 guesses to
+  // `X_ACCOUNT_LOCKED` without the reset, 160 and never locked with it.
+  //
+  // The cost is a shared NAT accumulating failures from unrelated people, which is exactly what
+  // `windowMs` bounds — and `X_ACCOUNT_LOCKED`'s `fix:` already names `recordSuccess(<key>)` as
+  // the deliberate manual escape for that case.
 
   // Parameters were raised since this hash was written: upgrade it now, while we hold the
   // plaintext. This is the only moment it is possible without asking the user for anything.

package/src/errors.ts

@@ -9,7 +9,6 @@ import {
   renderFixLiteral,
   UltimateError,
 } from '@ultimat3/core';
-import { oauthStartPath } from './oauth-paths';
 
 /** Codes this package declares and owns. `X_UNAUTHENTICATED` is auth's; http only borrows it. */
 export const AUTH_OWNED_ERROR_CODES = [
@@ -95,11 +94,12 @@ export class AuthError extends UltimateError {
     fix: string;
     meta?: Readonly<Record<string, unknown>> | undefined;
   }) {
+    // No `docs:`: `UltimateError` fills it from `describeErrorCode(code).docs`. The
+    // `https://ultimate.dev/errors/<code>` link this built until 9.x answered 404, host and all.
     super({
       code: init.code,
       cause: init.cause,
       fix: init.fix,
-      docs: `https://ultimate.dev/errors/${init.code}`,
       meta: init.meta,
     });
   }
@@ -216,176 +216,6 @@ export const mfaRequiredUnenforceable = (): AuthError =>
     fix: 'drop required from defineAuth({ mfa }) and gate it in your own sign-in handler, which is where the enrolment route lives: if (user.mfaSecret === null) send them to enrolTotp(auth, { account: user.email }) instead of createSession(auth.sessions, ...)',
   });
 
-/**
- * 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 },
-  });
-
 export const passwordWeak = (reasons: readonly string[]): AuthError =>
   new AuthError({
     code: 'X_PASSWORD_WEAK',
@@ -411,6 +241,9 @@ export const accountLocked = (key: string, retryAfterSeconds: number): AuthError
     // escaping, not throw-safety.
     cause: `${renderCauseValue(key)} is locked out for another ${retryAfterSeconds}s after repeated failures`,
     fix: `wait ${retryAfterSeconds}s — or clear this one bucket: auth.limiter.recordSuccess(${renderFixLiteral(key, '<key>')}), auth.orgLimiter for an org: key — or raise defineAuth({ rateLimit })`,
+    // `kdfOverloaded`'s shape: `@ultimat3/http`'s `retryAfterOf` reads exactly this field. `key`
+    // stays out — `cause`/`fix` escape it on purpose and `meta` is read by surfaces that do not.
+    meta: { retryAfterSeconds },
   });
 
 /** One shape for every api-key rejection: unknown, revoked, expired and wrong all look alike. */
@@ -436,6 +269,25 @@ export const authWriteFailed = (operation: string, table: string): AuthError =>
     meta: { operation, table },
   });
 
+/**
+ * A write the table's own UNIQUE constraint refuses. Same code as the write above, because it is
+ * the same failure to an operator — the row is not there and the caller must not assume it is —
+ * and the cause says which of the two happened.
+ *
+ * `MemoryAdapter` enforced neither `x_users.email` nor `x_users.external_id`, while `BuiltinAdapter`
+ * leans on both: two `register()` calls at one address made TWO rows in memory, and the second was
+ * unreachable forever because `findUserByEmail` returns the first. That adapter is what `x new`
+ * scaffolds and what every test runs against, so the duplicate path was only exercised against the
+ * permissive half of the seam.
+ */
+export const authUniqueViolation = (operation: string, table: string, column: string): AuthError =>
+  new AuthError({
+    code: 'X_AUTH_WRITE_FAILED',
+    cause: `${operation} would add a second ${table} row with the same ${column}, which that column's unique constraint refuses`,
+    fix: `look the row up first and update it — findUserByEmail(normaliseEmail(email)) — or write a different ${column}`,
+    meta: { operation, table, column },
+  });
+
 /**
  * At `defineAuth`, never at a login. `replicas: 3` behind one policy means each process counts
  * failures on its own, so the account survives `maxAttempts × 3` guesses and a lockout established

package/src/id-token.ts

@@ -7,10 +7,10 @@
 
 import type { Clock } from '@ultimat3/core';
 import { renderCauseValue } from '@ultimat3/core';
-import { oauthStateInvalid, oauthTokenInvalid, restartAt } from './errors';
 import { decodeJwtSegment } from './json';
 import { type IdTokenKeys, verifyJwtSignature } from './jwks';
 import type { OAuthProvider, OAuthProviderId } from './oauth';
+import { oauthStateInvalid, oauthTokenInvalid, restartAt } from './oauth-errors';
 import { providerFor } from './oauth-registry';
 import { timingSafeEqual } from './tokens';
 
@@ -21,6 +21,13 @@ export interface IdTokenClaims {
   readonly sub: string;
   readonly exp: number;
   readonly iat?: number | undefined;
+  /** Not-before. Checked with the same skew `workload.ts` allows, from the same constant. */
+  readonly nbf?: number | undefined;
+  /**
+   * Authorised party — the client this token was minted FOR. OIDC Core 3.1.3.7 step 5: with more
+   * than one audience, `aud` naming this client is not evidence the token is addressed to it.
+   */
+  readonly azp?: string | undefined;
   readonly nonce?: string | undefined;
   readonly email?: string | undefined;
   /** Google sends a boolean, Apple a `"true"` string. Both mean the same thing. */
@@ -75,6 +82,8 @@ export function decodeIdToken(provider: OAuthProviderId, idToken: string): IdTok
   }
   // `exactOptionalPropertyTypes`: an absent claim must be absent, not present-and-undefined.
   const iat = payload['iat'];
+  const nbf = payload['nbf'];
+  const azp = stringOrUndefined(payload['azp']);
   const verified = payload['email_verified'];
   const nonce = stringOrUndefined(payload['nonce']);
   const email = stringOrUndefined(payload['email']);
@@ -85,6 +94,8 @@ export function decodeIdToken(provider: OAuthProviderId, idToken: string): IdTok
     sub,
     exp,
     ...(typeof iat === 'number' ? { iat } : {}),
+    ...(typeof nbf === 'number' ? { nbf } : {}),
+    ...(azp === undefined ? {} : { azp }),
     ...(nonce === undefined ? {} : { nonce }),
     ...(email === undefined ? {} : { email }),
     ...(typeof verified === 'boolean' || typeof verified === 'string'
@@ -167,7 +178,19 @@ export async function verifyIdToken(input: VerifyIdTokenInput): Promise<IdTokenC
     );
   }
 
-  if (claims.exp * 1000 + ID_TOKEN_CLOCK_SKEW_MS <= input.clock.now().getTime()) {
+  // OIDC Core 3.1.3.7 steps 4-5. With more than one audience, `aud` naming this client says only
+  // that the token MENTIONS it — the authorised party is what says it was minted for it. Without
+  // this, a token an OP issued for another client that also lists ours verified here.
+  if (audience.length > 1 && claims.azp !== input.clientId) {
+    throw oauthTokenInvalid(
+      provider.id,
+      'the token names several audiences and its azp is not this client',
+      `ask ${provider.id} for a token whose azp is ${provider.clientIdEnv}'s client id, or one with a single aud`,
+    );
+  }
+
+  const nowMs = input.clock.now().getTime();
+  if (claims.exp * 1000 + ID_TOKEN_CLOCK_SKEW_MS <= nowMs) {
     throw oauthTokenInvalid(
       provider.id,
       'the token is already expired',
@@ -175,6 +198,17 @@ export async function verifyIdToken(input: VerifyIdTokenInput): Promise<IdTokenC
     );
   }
 
+  // The bound `workload.ts` already checks, with the same skew, from THIS FILE's constant — it
+  // imports `ID_TOKEN_CLOCK_SKEW_MS` from here and then enforced a limit here did not. An `nbf`
+  // ten years out verified.
+  if (claims.nbf !== undefined && claims.nbf * 1000 - ID_TOKEN_CLOCK_SKEW_MS > nowMs) {
+    throw oauthTokenInvalid(
+      provider.id,
+      'the token is not valid yet',
+      `sync this host's clock (\`timedatectl status\`), then ${restartAt(provider.id)}`,
+    );
+  }
+
   if (provider.usesNonce && !timingSafeEqual(input.nonce, claims.nonce ?? '')) {
     throw oauthStateInvalid(provider.id, 'the id token nonce did not match the stored handshake');
   }

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 {
@@ -180,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/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.