@ultimat3/auth 8.0.0 → 10.0.0

package/CLAUDE.md

@@ -48,7 +48,7 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   `maxKeys` is **not** compared: it bounds one process' table, so a shared limiter has no opinion
   on it. The point is that `Auth.rateLimit` is what an operator reads as "what this deployment
   enforces", so an injected limiter may not quietly enforce something else. Nothing here reads the
-  environment to guess a replica count. `defineAuth({ limiter })` is the one install point.
+  environment to guess a replica count.
 - **`postgresAuthLimiter` is the shared limiter, and a row per FAILURE is what makes it correct**
   (`As of 2026-08`). `assertAuthLimiterPolicy` refused a per-process limiter under
   `scope: 'shared'` and there was nothing else to pass, so the declaration was unsatisfiable while
@@ -71,6 +71,34 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   declared structurally
   even though this package already depends on `@ultimat3/db`: the connection is the HOST's, so the
   limiter takes the pool the boot opened rather than opening a second one.
+- **`configureAuthLimiters` is the HOST's install point and it takes a FACTORY, not a limiter**
+  (`As of 2026-08`). `defineAuth({ limiter })` is still the app's, and it still wins; what was
+  missing is that `postgresAuthLimiter` shipped with **nowhere a host could install it from**.
+  `defineAuth` is the APP's call and the app does not know which pool this process opened —
+  `@ultimat3/cli`'s `startServices` resolves that long before `loadApp` imports a single app
+  module — so a scaffolded app got a per-POD lockout while `x new` scaffolds `replicas: 2` and
+  `docker/helm` runs three: `maxAttempts × N` guesses per account, and a lockout one replica
+  established invisible to the rest.
+
+  A **factory** because the boot cannot know the app's numbers. `assertAuthLimiterPolicy` compares
+  what a limiter enforces against what the app declared, so a limiter built at boot on
+  `DEFAULT_AUTH_RATE_LIMIT` is `X_AUTH_LIMITER_POLICY_MISMATCH` for every app that tuned one. The
+  factory is called with the RESOLVED policy, once per bucket, so the two halves cannot disagree —
+  and the comparison still runs on what comes back, so a factory that ignores its argument is
+  refused exactly as an injected limiter is. Precedence: `config.limiter` → the installed factory →
+  `createAuthLimiter`. `installedAuthLimiter` is deliberately NOT in `src/index.ts`, for the reason
+  `registerJob` is not in `@ultimat3/jobs`': a second caller building limiters out of band is a
+  second answer to where failures are counted.
+
+  `purgeAuthLimits()` is the other half, and it exists because `PostgresAuthLimiter.purgeExpired()`
+  had **no caller anywhere** — every failure row and every dead lockout was kept forever. It sweeps
+  only the **widest** window among the limiters the factory built: they all write the same two
+  tables, so a sweep measured on a narrower window deletes failures a wider limiter is still
+  counting, which is a sprayer buying attempts back from the cleanup job. No `nowMs` argument —
+  a limiter built through the seam holds the clock its host handed it, and that is the clock every
+  `at_ms` in those tables was written from. `AuthLimiter.purgeExpired` is OPTIONAL so
+  `createAuthLimiter` can keep bounding itself; a limiter with no table declares nothing.
+
 - **`normaliseEmail` is the ONE normalisation, it lives ABOVE the `AuthAdapter` seam, and no
   adapter may fold case** (`As of 2026-08`). `MemoryAdapter` lowercased and trimmed on both
   `findUserByEmail` and `createUser`; `BuiltinAdapter` issues `where email = $1` against a plain
@@ -174,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)`.
@@ -186,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
@@ -283,6 +362,7 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | `adapter.ts` | the seam; `builtin-adapter.ts` (Postgres) + `memory-adapter.ts` |
 | `rate-limit.ts` | per-ip, per-account and per-org buckets, lockout, scope check, `loginFailed()` |
 | `rate-limit-postgres.ts` | the SHARED limiter: two tables, a row per failure, over a structural `PgExecutor` |
+| `limiter-install.ts` | the host's one install point for that limiter — the factory, what it built, and the purge over it |
 | `oauth.ts` | `OAuthProvider`, PKCE, `beginOAuth`, the callback gate. No I/O, no env |
 | `oauth-builtins.ts` | the three shipped IdPs, as data. Imports only the type, so no cycle |
 | `oauth-registry.ts` | the registry: `registerOAuthProvider`, `providerFor`, `oauthProviderIds` |
@@ -300,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
 });
 
@@ -152,8 +152,38 @@ defineAuth({
 Both limiters share one table: the keys are prefixed (`account:`, `ip:`, `org:`) and every limit
 travels as a statement parameter, so the tenant bucket's wider allowance cannot leak into the
 account bucket's. It reports `maxKeys: undefined` — there is no in-process table to bound — and
-neither table forgets on its own: `limiter.purgeExpired()` from a `task` drops failures past the
-window and lockouts that have expired, both measured against the injected clock.
+neither table forgets on its own.
+
+**An app does not have to write any of that, `As of 2026-08-22`.** The boot fills a seam and every
+`defineAuth` in the process picks it up:
+
+```ts
+import { configureAuthLimiters, type PgExecutor, postgresAuthLimiter } from '@ultimat3/auth';
+import type { Clock } from '@ultimat3/core';
+
+declare const bootExecutor: PgExecutor;
+declare const bootClock: Clock;
+
+// In the HOST, before the app's modules import.
+configureAuthLimiters((policy) =>
+  postgresAuthLimiter({ executor: bootExecutor, clock: bootClock, policy }),
+);
+```
+
+A **factory** and not a limiter, because the host runs before the app: `defineAuth` compares what a
+limiter enforces against what the app declared, so a limiter built at boot on the framework
+defaults would be `X_AUTH_LIMITER_POLICY_MISMATCH` for every app that tuned its numbers. The
+factory is called once per bucket, with the resolved policy, so the two halves cannot disagree.
+Precedence is `defineAuth({ limiter })` → the installed factory → `createAuthLimiter`, and
+`resetAuthLimiters()` puts the per-process default back. `@ultimat3/cli`'s `startServices` calls it
+on every boot, so a scaffolded app gets a fleet-wide lockout with nothing to remember.
+
+Neither table forgets on its own, and `purgeAuthLimits()` is the framework's reader for that:
+it drops failures past the window and lockouts that have expired, measured against the clock the
+host handed the limiter, and it sweeps only the WIDEST window installed — a sweep on a narrower
+one deletes failures another limiter is still counting, which hands a sprayer its attempts back.
+`@ultimat3/jobs`' `purge()` job is what calls it hourly; `x dev` and every role container declare
+that sweep at boot.
 
 ## Providers are a registry, not a union
 
@@ -193,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
@@ -614,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": "8.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": "8.0.0",
-    "@ultimat3/db": "8.0.0",
-    "@ultimat3/schema": "8.0.0"
+    "@ultimat3/core": "10.0.0",
+    "@ultimat3/db": "10.0.0",
+    "@ultimat3/schema": "10.0.0"
   }
 }

package/src/auth.ts

@@ -8,8 +8,8 @@ import { t } from '@ultimat3/schema';
 import type { AuthAdapter, AuthSession, AuthUser } from './adapter';
 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,
@@ -146,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;
@@ -171,16 +176,28 @@ export function defineAuth(config: AuthConfigInput): Auth {
   const session: SessionPolicy = { ...DEFAULT_SESSION_POLICY, ...config.session };
   const password: PasswordPolicy = { ...DEFAULT_PASSWORD_POLICY, ...config.password };
   const rateLimit: AuthRateLimitPolicy = { ...DEFAULT_AUTH_RATE_LIMIT, ...config.rateLimit };
-  const limiter = config.limiter ?? createAuthLimiter(clock, rateLimit);
+  // Three answers in precedence order, and the middle one is why the seam exists: what this call
+  // passed, then what the HOST installed (`configureAuthLimiters`, filled by the boot that owns
+  // the database connection), then one process' worth of state. Without the middle arm a
+  // scaffolded app had to remember to build a shared limiter itself, which is the opposite of
+  // what this framework promises — and `x new` scaffolds two replicas.
+  const limiter =
+    config.limiter ?? installedAuthLimiter(rateLimit) ?? createAuthLimiter(clock, rateLimit);
   assertAuthLimiterPolicy(rateLimit, limiter);
   // The tenant bucket is a noisy-neighbour cap, not a credential-guessing allowance, so an app
   // that declares `scope: 'shared'` for its LOCKOUT is not also required to ship a shared limiter
   // for this one — per replica it approximates to `orgMaxAttempts × replicas`, which is a
-  // throughput ceiling and discloses nothing. An INJECTED org limiter is still compared, because
-  // then the app has made a claim about what it enforces and `Auth.orgRateLimit` reports it.
+  // throughput ceiling and discloses nothing. Only the LOCAL fallback is exempt, and exempting it
+  // is what buys that: `createAuthLimiter` always reports `'process'`, which is the one arm the
+  // scope check would refuse. A limiter somebody else supplied — injected by the app or built by
+  // the host's factory — is compared exactly as the general bucket's is, because a factory that
+  // ignores the policy it was handed otherwise enforces numbers the app never declared while
+  // `Auth.orgRateLimit` reports the app's. That asymmetry was the whole defect: the same factory
+  // is refused for one bucket and trusted for the other.
   const orgLimits = orgRateLimit(rateLimit);
-  const orgLimiter = config.orgLimiter ?? createAuthLimiter(clock, orgLimits);
-  if (config.orgLimiter !== undefined) assertAuthLimiterPolicy(orgLimits, config.orgLimiter);
+  const suppliedOrgLimiter = config.orgLimiter ?? installedAuthLimiter(orgLimits);
+  const orgLimiter = suppliedOrgLimiter ?? createAuthLimiter(clock, orgLimits);
+  if (suppliedOrgLimiter !== undefined) assertAuthLimiterPolicy(orgLimits, suppliedOrgLimiter);
   // Read through a widened local on purpose: the field's type is the literal `false`, so this
   // branch is unreachable from TypeScript and reachable from every JS caller and every config
   // parsed out of JSON — the same split `invariantColumns()` keeps its Proxy behind a compile
@@ -200,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',
   });
 }
@@ -273,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');
   }