@ultimat3/auth 30.9.0 → 31.0.0

package/CLAUDE.md

@@ -1,6 +1,7 @@
 # @ultimat3/auth — agent notes
 
 Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3/policy`'s job.
+A rule marked `†` has its full text in [`docs/history/auth-rules.md`](../../docs/history/auth-rules.md).
 
 | Rule | |
 |---|---|
@@ -16,14 +17,8 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 
 ## Non-negotiables
 
-- **Every number this package bounds anything with is screened** (`policy-numbers.ts`): policy
-  numbers at `defineAuth` (`X_CONFIG_INVALID` — `session.absoluteTtlMs`, `idleTtlMs`,
-  `idleSlideMs`, `password.minLength`, the two argon2 costs, every `rateLimit` number), and every
-  runtime one through `assertFiniteAuthCount` — `jwks.ttlMs`, the three OAuth legs' `timeoutMs`
-  (screened OUTSIDE each leg's `try`), the limiter's `maxKeys`, `mfa.drift`,
-  `oauth.handshake.ttlMs`, `session.cookie.maxAgeSeconds`, `kdf.maxConcurrent`/`maxQueued`.
-  **`mfa.drift` and the KDF gate are the two that HANG** — mutate `verifyTotp` with the
-  `NaN` case, never by deleting the screen (that wedges `mfa.test.ts`).
+- **Every number this package bounds anything with is screened** (`policy-numbers.ts`,
+  `assertFiniteAuthCount`); `mfa.drift` and the KDF gate HANG if unscreened. †
 - **A number is screened ABOVE the write it feeds.** `issueVerification` screens its TTL before
   `putVerification` (which upserts on `(purpose, identifier)`); `verify.test.ts` asserts no row
   written, no mail sent, the earlier token still redeemable.
@@ -33,44 +28,21 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 - Every credential failure throws `loginFailed()` — one code, one cause, one fix. Adding a
   parameter to it re-opens account enumeration.
 - **`login()` takes an email or a handle** (`login-identity.ts`, `defineAuth({ handles })`).
-- **A stored hash Bun cannot read is the generic failure, and it burns the same KDF.**
-  `verifyAgainst` (`password.ts`) answers `null` for `Bun.password.verify`'s throw (unsupported
-  algorithm, malformed PHC) and `''`, joining the no-user branch; nothing is logged. An
-  `X_OVERLOADED` from the gate is RE-THROWN (a shed is load, not a verdict). Supported-but-old
-  (bcrypt) stays a verdict and `needsRehash` flags it. `password.test.ts` pins both halves.
+- **A stored hash Bun cannot read is the generic failure, and it burns the same KDF**
+  (`verifyAgainst`); an `X_OVERLOADED` is re-thrown. †
 - **The limiter's table is bounded, and the eviction order is the guarantee.** Every bucket carries
   `forgetAtMs`; `policy.maxKeys` (`DEFAULT_MAX_AUTH_LIMIT_KEYS`) is the backstop, and a **live
   lockout outranks its own deadline** in the comparator. Never reduce that sort to recency.
-- **`AuthLimiter` is async on every member, declares the policy it enforces, and is a
-  RESERVATION.** `reserve(key)` counts the attempt in the step that admits it (refused, counting
-  nothing, while locked); `refund(reservation)` gives ONE back and lifts a lockout the window no
-  longer justifies; `recordSuccess(key)` clears the key. There is no check-then-record pair: N
-  concurrent guesses all passed the check. `assertAuthLimiterPolicy` (once, in `defineAuth`)
-  refuses a per-process limiter under `scope: 'shared'` (`X_AUTH_LIMITER_NOT_SHARED`) and different
-  `maxAttempts`/`windowMs`/`lockoutMs` (`X_AUTH_LIMITER_POLICY_MISMATCH`). `maxKeys` is not
-  compared.
-- **Every credential check runs through `openLoginAttempt`** (`login-attempt.ts`): account → ip →
-  org reserved in that fixed order BEFORE the KDF or the TOTP compare. A failure calls nothing (the
-  reservations are the record); `release()` for no verdict (a shed KDF, a store that is down, a
-  bucket that refused) or a factor proven with another still owed; `succeed()` clears the account
-  and refunds the shared two.
-- **`postgresAuthLimiter` is the shared limiter: ONE row per key in `x_auth_lockouts`, holding the
-  instants still inside the window** (`attempts_ms bigint[]` — a sliding window). The take is one
-  `insert … on conflict do update` reading the window off `x_auth_lockouts.<column>`, never a CTE
-  and never a second table: only the row the statement locks is re-read after a wait. No row back is never an
-  admission; a live lockout is never rewritten. Full rule: `docs/history/auth.md`. `PgExecutor` (`@ultimat3/core`'s, re-exported) is structural:
-  the pool is the host's.
-- **`configureAuthLimiters` is the HOST's install point and takes a FACTORY**, called with the
-  RESOLVED policy once per bucket; the comparison still runs on what comes back. Precedence:
-  `config.limiter` → the installed factory → `memoryAuthLimiter`. `installedAuthLimiter` and
-  `installedLimiterCount()` are NOT in `src/index.ts`. `purgeAuthLimits()` sweeps only the
-  **widest** window among the built limiters (retained one per `windowMs` in a `Map`), on the
-  limiter's own clock. `AuthLimiter.purgeExpired` is optional.
-- **`normaliseEmail` is the ONE normalisation, it lives ABOVE the `AuthAdapter` seam, and no adapter
-  may fold case.** Every door now normalises before the adapter sees the address — `register`,
-  `login`, `profileEmail` in `oauth-login.ts`, `accountKey`, and `issueVerification`/
-  `consumeVerification`. Trim and lowercase only; never strip a `+tag` or a gmail dot.
-  `adapter-parity.test.ts` pins both adapters in one test.
+- **`AuthLimiter` is a RESERVATION** (`reserve`/`refund`/`recordSuccess`), never check-then-record;
+  `assertAuthLimiterPolicy` (`X_AUTH_LIMITER_NOT_SHARED`, `X_AUTH_LIMITER_POLICY_MISMATCH`). †
+- **Every credential check runs through `openLoginAttempt`**: account → ip → org reserved, in that
+  order, BEFORE the KDF or the TOTP compare. †
+- **`postgresAuthLimiter` is the shared limiter**: ONE `x_auth_lockouts` row per key, a sliding
+  window, a one-statement take; a live lockout is never rewritten. †
+- **`installAuthLimiters` (`@ultimat3/auth/adapter`) is the HOST's install point and takes a
+  FACTORY**: `config.limiter` → installed factory → `memoryAuthLimiter`. †
+- **`normaliseEmail` is the ONE normalisation, ABOVE the `AuthAdapter` seam**: trim + lowercase,
+  never a `+tag` or gmail dot; no adapter folds case. †
 - **`json.ts` owns `isRecord` and `decodeJwtSegment`; no second copy.** An array is not a record.
   `decodeJwtSegment` answers `null` for all three failures; each caller raises its own refusal.
 - Absolute and idle expiry are two separate computations in `sessionExpiry()`. Do not fold them.
@@ -95,9 +67,8 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   `deleteSessionsForOrg` joins through `x_users`; `x_sessions` does **not** gain an `org_id`.
 - The code flow carries `nonce` inside the id token. `assertOAuthCallback` checks an echoed one when
   present and never requires it; `verifyIdToken` is the real gate.
-- The handshake is sealed (`sealHandshake`); `openHandshake` takes the provider as an argument.
-  Expiry is the server's clock, not `Max-Age`. One handshake cookie **per provider**
-  (`handshakeCookieName`), and `clearHandshakeCookie(provider)`.
+- `sealHandshake`/`openHandshake` (a hand-built flow's cookie, not `oauthLogin`'s): the provider is
+  an argument, expiry the server's clock, one cookie per provider (`handshakeCookieName`).
 - `takeVerification(purpose, identifier, tokenHash)` consumes **only on a hash match**, in one
   conditional statement (`consumed_at is null` on the UPDATE and its subselect,
   `order by created_at desc limit 1`); `consumeVerification` still compares in constant time.
@@ -112,14 +83,8 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 - A token endpoint's HTTP 200 is not success — read `error`.
 - Link by address only when the provider **and** the local account both verified it
   (`link: 'verified-email'`, default; `'never'` is the only other value).
-- **The OAuth route paths are not configurable.** `oauth-paths.ts` imports nothing and is read by
-  both `oauth-errors.ts` and `oauth-route.ts`; every "start over" fix is `restartAt(provider)`.
-- The routes are **descriptors** (`AuthRouteDescriptor`), never mounted handlers.
-- The callback answers failure as **coded JSON** — a fixed body per code (`code`, `title`, `docs`,
-  one `cause`, `fix: x errors explain <CODE> --json`); the authored cause and fix are the
-  `auth.oauth.refused` log line — and success redirects to a fixed `successPath` —
-  never `?next=` (`nextAfterSignIn` in `@ultimat3/http` is the one open-redirect check).
-- The handshake cookie is cleared on **every** callback outcome.
+- **One sign-in route implementation** (`identity-provider-route-core.ts`) at
+  `/auth/sso/:provider[/callback]`; failure is coded JSON, success a 303 to `successPath`. †
 - Refresh is **not implemented**, so the framework **stores no provider token**: `accountFor`
   (`oauth-login.ts`) writes `accessToken: null, refreshToken: null`. The columns and `AuthAccount`
   fields stay; an app that stores tokens implements `linkAccount` itself.
@@ -130,9 +95,8 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   an uncoded adapter throw logs `auth.oauth.uncoded_failure`, a rejecting `OAuthFetch` logs
   `auth.oauth.token_fetch_failed`, and the `POST /token` body is read as
   `providerDetail(response, 'coded-only')` (that request carries `client_secret`).
-- **`x_users.mfa_secret` is SEALED** (`mfa-secret.ts`, purpose `auth:x_users.mfa_secret`):
-  `saveTotpSecret` writes, `openTotpSecret` reads and REFUSES a value core's `isSealed` does not
-  recognise (`X_MFA_SECRET_UNSEALED`, fix `x auth seal-mfa --json`). No plaintext fallback, ever. Full rule: `docs/history/auth.md`.
+- **`x_users.mfa_secret` is SEALED** (`mfa-secret.ts`); an unsealed value is
+  `X_MFA_SECRET_UNSEALED`. No plaintext fallback. †
 - **`providerJwks` memoises only the DEFAULT client**; a caller supplying options gets its own.
 - **A JWKS refresh is single-flighted through core's `singleFlight` with
   `deadlineMs = timeoutMs * 2`**; eviction frees the key, never the work, and a `generationFence`
@@ -143,74 +107,54 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 - **A success clears the ACCOUNT bucket and nothing else** — clearing the address bucket made the
   limiter inert against stuffing. A password proven with a second factor still owed clears
   NOTHING: `completeMfa` is what clears, or a repeat of the first leg wipes the wrong codes.
-- **`MemoryAuthAdapter.createUser` and `updateUser` enforce `x_users.id`, `email` and `external_id`
-  uniqueness** (`authUniqueViolation`, `X_AUTH_WRITE_FAILED`), NULLS DISTINCT like Postgres;
-  `PostgresAuthAdapter` answers the same code through `builtin-adapter-violation.ts`.
-  **`MemoryAuthAdapter` takes a `Clock`** (default `systemClock`) and stamps every instant from it.
-  `adapter-parity.test.ts` pins both.
+- **`MemoryAuthAdapter` enforces `x_users` uniqueness like Postgres and takes a `Clock`**
+  (`authAdapterConformance` pins both adapters). †
 - **`listUsersByOrg` orders by byte**: `collate "C"` in Postgres, a code-point compare in memory —
   never `localeCompare`, never UTF-16 `<` (`list-users-order.live.test.ts`, on an `en_US` db).
 - Every `AuthAdapter` member is REQUIRED — a missing one is a compile error at `defineAuth`, and
   no caller in this package refuses at runtime with `X_NOT_IMPLEMENTED`.
-- **An api key is its owner's credential.** `verifyApiKey` re-reads the owner (after the secret
-  matched, never before) and refuses a missing or disabled one as the same `X_API_KEY_INVALID`; a
-  key with `userId === null` has no owner and is unchanged. `disableUser` revokes the user's live
-  keys beside their sessions, and logs before its first write.
-- **A key's scopes only ever shrink** (`apiKeyScopes`, `policy-bridge.ts`): `*` and `<res>:*` are
-  refused at `issueApiKey` (`X_CONFIG_INVALID`) and dropped from a stored row; an OWNED key keeps
-  only what its owner's grants cover (core's `grantCovers`, never a local copy). Roles are policy's to expand, so the default grants are the
-  row's `permissions` + `scopes` (`directGrants`) and a role-based app passes
-  `apiKeyResolver(store, { grantsOf })`. Never union a key with the owner's roles.
-- **`apiKeyResolver(() => store)` is the ONE token → caller mapping** (`api-key-resolver.ts`):
-  `verifyApiKey` → `apiKeyActor`, `X_API_KEY_INVALID` → `null`, everything else rethrown. Its
-  `ApiKeyCaller` is structurally http's `BearerCaller` and mcp's `ResolvedToken` — declared here
-  because tier 2 imports neither. The store is a thunk (a mount is declared before boot installs
-  the database client). No second in-memory key store: `MemoryAuthAdapter` IS an `ApiKeyStore`.
+- **An api key is its owner's credential**: `verifyApiKey` re-reads the owner after the secret
+  matched; `disableUser` revokes their keys. †
+- **`verifyApiKey` refuses an `env` segment that is not the stored prefix's, and touches
+  `lastUsedAt` at most once per `API_KEY_TOUCH_MS`** — above the seam, so both adapters agree.
+- **An authorization code is checked on `getCode`, spent by `takeCode` only after client, PKCE,
+  redirect and resource held**; replay revocation needs the verifier. `pollDevice` takes the
+  `clientId` and stamps nothing for another client's poll.
+- **A key's scopes only ever shrink** (`apiKeyScopes`): wildcards refused, an owned key keeps only
+  what its owner's grants cover. Never union with the owner's roles. †
+- **`apiKeyResolver(() => store)` is the ONE token → caller mapping**; `X_API_KEY_INVALID` →
+  `null`, all else rethrown. No second in-memory key store. †
 - **`jwtBearerResolver` is its twin for an external JWT**: `checkWorkloadToken`'s checks, then
   scope, then `accept(raw)`. Every refusal — a throwing key source too — is `null` plus one
   `auth.jwt_bearer.refused` line naming the check, never a claim. `keys` is a thunk.
-- Rotate the session id on any privilege change (`rotateSession`, called by `updatePrivileges` in
-  `privileges.ts`), never patch the row. A `passwordHash` change also ends every OTHER session of
-  that user (`deleteOtherSessions`), or all of them when the caller passed no session of theirs.
-  **A new id, never a new lifetime**: rotation carries `createdAt` and `absoluteExpiresAt` over
-  (`createSession` clamps both, so they only shorten), and the rotated cookie's `Max-Age` is
-  `remainingMaxAgeSeconds` — `session-rotation.test.ts` pins both adapters.
-- **Every argon2 call goes through `kdfGate()`** — width 8, queue 64, `X_OVERLOADED` past it
-  (borrowed from http, in `AUTH_BORROWED_ERROR_CODES`). The pool is core's `flightGate`, the
-  refusal auth's own through core's `overflow:` seam. `configureKdfGate()` is the ONE install point
-  and deliberately not a `defineAuth` key.
-- **MFA's second leg is `completeMfa(auth, challenge, code)`** (`mfa-challenge.ts`). `X_MFA_REQUIRED`'s
-  `meta.challenge` is a `seal()` value, never a bare user id; the code is reserved against the three
-  buckets before it is compared; a recovery code is consumed by one conditional UPDATE. Full rule: `docs/history/auth.md`.
+- Rotate the session id on any privilege change (`rotateSession`); **a new id, never a new
+  lifetime**. A `passwordHash` change ends every other session. †
+- **Every argon2 call goes through `kdfGate()`** (width 8, queue 64, `X_OVERLOADED`);
+  `installKdfGate()` on `./adapter` is the ONE install point. †
+- **MFA's second leg is `completeMfa(auth, challenge, code)`**; `X_MFA_REQUIRED`'s challenge is a
+  `seal()` value. †
 - **`mfa.required` is the literal `false`, and `defineAuth` refuses a `true`** (`X_CONFIG_INVALID`).
   `mfa.issuer` is read by `enrolTotp(auth, { account })`.
 - **A TOTP secret that decodes to zero bytes is NO key**: `verifyTotp` returns the generic failure
   (`{ ok: false, step: null }`), `totpCode` and `enrolTotp` throw `X_MFA_SECRET_INVALID`. The secret
   never reaches `cause:`/`fix:`. No length floor beyond one byte.
-- **`TotpReplayGuard` is one atomic `claim(subject, step, at): Promise<boolean>`**; a rejection is
-  no verdict (`attempt.release()`, rethrown). Precedence: `config.totpReplay` →
-  `configureTotpReplay`'s factory → memory. `postgresTotpReplayGuard`: `x_totp_steps`, one
-  `on conflict do nothing`; `purgeExpired(nowMs)` keeps slack past the drift.
-- **`memoryTotpReplayGuard`'s table is bounded and the eviction ORDER is the guarantee**: subjects
-  whose steps are all below the drift floor are forgotten first; past `DEFAULT_MAX_TOTP_SUBJECTS`,
-  evict by newest spent step ascending, least-recently-seen tie-break. `maxSubjects` is normalised
-  first (`boundedSubjects`): anything not a positive finite integer takes the default.
-- **Passkeys are verified by hand** (`passkey-*.ts`, `cbor.ts`, `cose-key.ts`, `webauthn-data.ts`):
-  UV required, origin exact, the key's alg (never the assertion's), counter non-regression by
-  compare-and-set, challenges single-use in `x_passkey_challenges` (never a process map). A step-up
-  challenge is DERIVED (`stepUpChallenge`), never supplied. Browser half: `./client`, two modules
-  (`client-bundle.test.ts`); never import the barrel there. `docs/history/auth.md`.
-- SAML is out of scope permanently (XML-DSig canonicalisation has no Bun native). Put an
-  OIDC-speaking bridge in front and register that.
+- **`TotpReplayGuard` is one atomic `claim(subject, step, at): Promise<boolean>`**; a rejection is no verdict. Full rule: `docs/history/auth.md`.
+- **`memoryTotpReplayGuard`'s table is bounded and the eviction ORDER is the guarantee.** Full rule: `docs/history/auth.md`.
+- **Passkeys are verified by hand** (`passkey-*.ts`, `cbor.ts`, `cose-key.ts`): UV required, exact
+  origin, compare-and-set counter, single-use challenges. †
+- **SAML = `samlIdentityProvider`**, no dependency: assertion signature required, one assertion,
+  metadata keys only, replay via `auth.totpReplay`, `trustEmail: true` needs `emailDomains`.
 
 ## Files
 
 | File | Job |
 |---|---|
-| `auth.ts` | `defineAuth`, entity schemas, `login`/`register`/`authenticate`/`logout`. Three suites, split at the line ceiling along the three subjects: `auth.test.ts` (the credential flow), `auth-config.test.ts` (`defineAuth`'s defaults and refusals) and `auth-lockout.test.ts` (the tenant and address buckets) |
+| `auth.ts` | `defineAuth`, entity schemas, `login`/`register`/`authenticate`/`logout`. Suites: `auth.test.ts` (credential flow), `auth-config.test.ts` (defaults, refusals), `auth-lockout.test.ts` (tenant and address buckets) |
 | `policy-bridge.ts` | the one funnel: identity → `Actor`, all four `ActorKind`s |
 | `session.ts` | two expiries, rotation, revocation, device list, the cookie |
 | `adapter.ts` | the seam; `builtin-adapter.ts` (Postgres) + `memory-adapter.ts` |
+| `adapter-subpath.ts` | `@ultimat3/auth/adapter`: the `authLimiter`/`totpReplay`/`authServerStore` port types, their installers and resets, and `installKdfGate` |
+| `authorization-server-installed.ts` | the `authServerStore` slot: `authorizationServer()` with no `store` reads it per CALL (never captured: `runtime.ts` may build the server first); empty, Postgres over the ambient pool |
 | `builtin-adapter-violation.ts` | a Postgres unique violation on an auth table → `authUniqueViolation` |
 | `rate-limit.ts` | per-ip, per-account and per-org buckets as reservations, lockout, scope check, `loginFailed()` |
 | `login-attempt.ts` | one attempt's reservations across the three buckets, taken before the check and settled after it |
@@ -236,10 +180,9 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | `oauth-profile.ts` | claims or userinfo → one `OAuthProfile`; `userinfoBody`, the one userinfo reader |
 | `oauth-grant-context.ts` | `resolveGrants`' second argument: tokens, every id-token claim, a lazy subject-checked `userinfo()` |
 | `oauth-login.ts` | profile → account link → session. `completeOAuthLogin` is the entry point |
-| `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 refusals more than one OAuth module raises, and `restartAt`. A refusal with one thrower lives beside it; declares no code and registers nothing |
-| `oauth-route.ts` | `oauthLogin(auth)` — the redirect out and the callback back |
+| `oauth-route.ts` | `oauthLogin(auth)`, the OAuth policy over the sign-in route core |
 | `kdf-gate.ts` | the one bound on concurrent argon2 work: core's `flightGate`, auth's `X_OVERLOADED` |
 | `email.ts` | `normaliseEmail` — the one normalisation an address gets before it is an identity key |
 | `json.ts` | reading untrusted JSON: `isRecord`, and a base64url JWT segment as an object or `null` |
@@ -247,9 +190,11 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | `subject-target.ts` | `authSubjectTarget({ executor, user })`: the identity tables as a `defineSubject({ targets })` entry, structural (`@ultimat3/jobs` imports nothing from here). Export = `AUTH_SUBJECT_COLUMNS` (never `password_hash`, `mfa_secret`, a recovery digest); erase = api keys, pending verifications, then the user (sessions, accounts cascade). Three idempotent statements, no transaction of its own |
 | `passkey-login.ts` / `passkey-step-up.ts` / `passkey-evidence.ts` | the factories; the offline re-check. `passkey-verify.ts` + `passkey-assertion.ts` are every check; `*-postgres`/`*-memory` the store; `soft-authenticator.ts` (`./soft-authenticator`) the WebCrypto authenticator tests sign with |
 | `client-scope.ts` | `clientScopeOf(actor)`, the OPAQUE id for `<meta name="ultimate-scope">`: keyed SHA-256 (`SESSION_SECRET`, else a per-process key and one warning) over kind, id, impersonator; `''` anonymous |
+| `identity-provider*.ts` | SSO port, `signInWithIdentity`, OIDC adapter, route core, state cookie, status table |
+| `saml-*.ts` | SAML adapter: strict XML reader, exc-c14n, XML-DSig, response checks, metadata, AuthnRequest |
 
 ```bash
-bun test packages/auth
+bun test ./packages/auth/
 bun run --filter @ultimat3/auth typecheck
 ```
 
@@ -259,7 +204,8 @@ Gotchas:
 - `errors.ts` registers only the codes this package **owns**, unconditionally; borrowed ones
   (`X_FORBIDDEN`, `X_NOT_IMPLEMENTED`, …) sit untitled in `AUTH_BORROWED_ERROR_CODES`. Never a
   `hasErrorCode()` guard.
-- Tests run against `MemoryAuthAdapter`; `adapter-parity-identity.test.ts` boots PGlite. The two
+- Tests run against `MemoryAuthAdapter`; `authAdapterConformance` and `authServerStoreConformance`
+  (`@ultimat3/testing/conformance`) run memory and Postgres through one suite each. The two
   Postgres guards pair a scripted twin with a `*.live.test.ts` (skips without `TEST_DATABASE_URL`).
 
 Why each rule above is shaped the way it is: [`docs/history/auth.md`](../../docs/history/auth.md).

package/README.md

@@ -24,7 +24,7 @@ const { actor, token, cookie } = await login(auth, { email, password, ip });
 // a normalised handle to the auth user's id, and `register(auth, { id, ... })` links the two rows.
 const byHandle = await login(auth, { handle: 'ada', password, ip });
 
-// "Log in with GitHub" is a link to /auth/oauth/github. These two routes are what serves it.
+// "Log in with GitHub" is a link to /auth/sso/github. These two routes are what serves it.
 const { start, callback } = oauthLogin(auth);
 ```
 
@@ -217,14 +217,17 @@ A limiter of your own implements the same five members:
 `defineAuth` in the process picks it up:
 
 ```ts
-import { configureAuthLimiters, type PgExecutor, postgresAuthLimiter } from '@ultimat3/auth';
+// The HOST's code, not an app's: `@ultimat3/cli`'s boot does exactly this. The installer is on
+// `@ultimat3/auth/adapter` only (31.0.0) — the `.` barrel carries no setter.
+import { type PgExecutor, postgresAuthLimiter } from '@ultimat3/auth';
+import { installAuthLimiters } from '@ultimat3/auth/adapter';
 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) =>
+installAuthLimiters((policy) =>
   postgresAuthLimiter({ executor: bootExecutor, clock: bootClock, policy }),
 );
 ```
@@ -234,7 +237,7 @@ limiter enforces against what the app declared, so a limiter built at boot on th
 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 → `memoryAuthLimiter`, and
-`resetAuthLimiters()` puts the per-process default back. `@ultimat3/cli`'s `startServices` calls it
+`resetAuthLimiters()` (also `@ultimat3/auth/adapter`) 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.
 
 The table does not forget on its own, and `purgeAuthLimits()` is the framework's reader for that:
@@ -314,11 +317,9 @@ registerOAuthProvider(
 PKCE stays mandatory for all three: for a public client it is the only thing binding the code to
 the browser that started the flow.
 
-**SAML is out of scope and will stay out of scope.** XML-DSig canonicalisation has no Bun native
-and implementing it would mean a real dependency in the primitive vocabulary, which
-[`docs/idea/18-build-vs-wrap.md`](../../docs/idea/18-build-vs-wrap.md) does not permit. The honest
-answer is to put an OIDC-speaking SAML bridge (Okta, Entra, Keycloak, Dex, a SAML-to-OIDC proxy) in
-front and register **that** as a provider.
+**SAML 2.0 is supported natively since 31.0.0** — see [SSO: one IdentityProvider port, OIDC and
+SAML](#sso-one-identityprovider-port-oidc-and-saml). No dependency: the XML reader, exclusive c14n
+and XML-DSig verification are this package's own, held to xmlsec-signed vectors.
 
 ## Id token signatures
 
@@ -463,7 +464,7 @@ every enrolled user's second factor.
 | `TotpReplayGuard` | one atomic method, `claim(subject, step, at): Promise<boolean>`: `true` the first time, `false` for a replay. A store that cannot answer rejects: a down database is a fault, never a wrong code |
 | `memoryTotpReplayGuard(drift?, maxSubjects?)` | the in-process guard, `{ claim, isUsed, size }`; `isUsed` is for a test. The default only where no host installed one |
 | `postgresTotpReplayGuard({ executor })` | the shared guard: `x_totp_steps` (`SQL_TOTP_REPLAY_TABLE`), one `insert … on conflict do nothing` per claim, `purgeExpired(nowMs)` for the sweep. A framework boot installs it |
-| `configureTotpReplay(() => guard)` / `resetTotpReplay()` | the host's install point, beside `configureAuthLimiters`. Precedence: `defineAuth({ totpReplay })` → the installed factory → memory |
+| `installTotpReplay(() => guard)` (`@ultimat3/auth/adapter`) / `resetTotpReplay()` (both `@ultimat3/auth/adapter`) | the host's install point, beside `installAuthLimiters`. Precedence: `defineAuth({ totpReplay })` → the installed factory → memory |
 | `generateRecoveryCodes(count = 10)` | `{ codes, hashes }`. `codes` is shown once and is never re-derivable |
 | `recoveryCodeHash(code)` | what a code is stored and looked up as — dashes, spaces and case removed first. `auth.adapter.consumeRecoveryCode(userId, hash)` removes it in ONE statement and answers whether it was there, so two requests carrying one code cannot both redeem it |
 | `totpStep(at, stepSeconds?)` / `totpCode(secret, step, digits?)` | the RFC 6238 halves, for a test that has to mint a valid code. `totpCode` throws `X_MFA_SECRET_INVALID` on a secret that decodes to zero bytes |
@@ -659,7 +660,10 @@ OAuth 2.1 server: authorization code + PKCE (S256 only), refresh rotation with r
 `runtime.routes`; the consent and device pages are the app's (`readRequest`/`approve`/`deny`,
 `readDevice`/`approveDevice`/`denyDevice`). `oauthBearerResolver(server, { actor, resource? })` is
 the `resolveToken`. Stores: `memoryAuthServerStore()`, `postgresAuthServerStore({ executor })`
-over `SQL_AUTH_SERVER_TABLES`, which the boot applies. Full table and the rule each test holds:
+over `SQL_AUTH_SERVER_TABLES`, which the boot applies. A code is spent only by a request that could
+redeem it: client, PKCE verifier, `redirect_uri` and `resource` are checked on `getCode` before
+`takeCode` marks it used, so a request without the verifier neither burns a login nor trips the
+replay revocation. `pollDevice(hash, clientId, at)` stamps only the issuing client's poll. Full table and the rule each test holds:
 [wiki Auth](https://github.com/developerz-ai/ultimate/wiki/Auth#authorization-server).
 
 | File | Job |
@@ -839,7 +843,9 @@ const mounted = (leg: AuthRouteDescriptor): Route => ({
   method: leg.method,
   path: leg.path,
   handler: (request) => leg.handle(request.raw),
-  meta: { name: leg.name, auth: leg.auth },
+  // Verbatim: the SAML ACS (POST) declares `csrf: 'cookieless'` + `authenticate: () => null`,
+  // because the IdP answers with a cross-site form. Hand-copy `name`/`auth` and it is a 403.
+  meta: leg.meta,
 });
 
 export const runtime: NonNullable<ServeOptions['runtime']> = {
@@ -849,8 +855,8 @@ export const runtime: NonNullable<ServeOptions['runtime']> = {
 
 | | `start` | `callback` |
 |---|---|---|
-| path | `/auth/oauth/:provider` | `/auth/oauth/:provider/callback` |
-| success | `302` to the provider, `Set-Cookie: __Host-x_oauth_<provider>` | `303` to `successPath`, `Set-Cookie: __Host-x_session` **and** the handshake cleared |
+| path | `/auth/sso/:provider` | `/auth/sso/:provider/callback` |
+| success | `302` to the provider, `Set-Cookie: __Host-x_sso_<provider>` | `303` to `successPath`, `Set-Cookie: __Host-x_session` **and** the handshake cleared |
 | failure | coded JSON, status per code: `code` + `title` + `docs`, one fixed `cause`, `fix: x errors explain <CODE> --json` | the same, handshake cleared either way |
 
 A **descriptor**, never a mounted handler — the same category as `mcpHttpRoute()`. `@ultimat3/http`
@@ -860,9 +866,11 @@ router that can match a `:param` — and `runtime.routes` is the one an app has.
 framework's own routes and before the pages; every field it shares the file with is in
 [`wiki/Configuration.md`](../../wiki/Configuration.md#runtime-overrides--appsappruntimets).
 
-**The paths are not configurable.** `X_OAUTH_STATE_INVALID` has always told the caller to restart
-at `GET /auth/oauth/<provider>`; it now quotes `oauthStartPath()`, the same declaration the mount
-reads. A movable base path is that sentence going stale again.
+**The paths are not configurable.** `X_OAUTH_STATE_INVALID` quotes `oauthStartPath()`, the same
+declaration the mount reads. A movable base path is that sentence going stale again. Since 31.0.0
+the base is `/auth/sso`: `oauthLogin` is a front door over `identityProviderRoutes`' legs, so OAuth
+and SAML share the paths, the sealed state cookie and the refusal body (re-register the callback
+URL at each IdP — `wiki/Upgrading.md`).
 
 `oauthLogin` needs an origin to build the provider's `redirect_uri` from: `baseUrl`, or `APP_URL`.
 With neither, the start leg refuses with `X_ENV_MISSING` rather than trust a request header.
@@ -899,6 +907,10 @@ SameSite=Lax` under a `__Host-` name, and expired against the server's clock rat
 client's copy of `Max-Age`. `sealHandshake` / `openHandshake` are the same codec without the
 cookie, for an app that would rather keep it server-side.
 
+`oauthLogin` itself no longer uses this cookie (31.0.0): its state rides the sign-in routes' own
+`__Host-x_sso_<provider>`, sealed the same way and claimed once in `auth.totpReplay`. The
+`handshakeCookie` family stays for a hand-built flow over `beginOAuth` / `completeOAuthLogin`.
+
 **One cookie per provider:** `handshakeCookieName(provider)` → `__Host-x_oauth_github`. A browser
 is one cookie jar and a user is allowed two tabs, so a single shared name means the `google`
 redirect overwrites a `github` handshake still in flight — and the github callback then opens
@@ -943,6 +955,64 @@ both callback routes are GET. An app that needs it registers its own with `regis
   `loginFailed()` the taken-address case answers. Minting one is a pre-hijack: the owner's
   `register()` then collides and their verified login is refused, with the attacker still linked.
 
+## SSO: one IdentityProvider port, OIDC and SAML
+
+Every federated sign-in is an `IdentityProvider`: `begin` sends the browser out, `complete` takes
+the answer back and proves one `OAuthProfile`. Two adapters, one set of routes, one session path.
+
+```ts
+import {
+  defineAuth,
+  identityProviderRoutes,
+  memoryAuthAdapter,
+  oidcIdentityProvider,
+  parseSamlMetadata,
+  samlIdentityProvider,
+} from '@ultimat3/auth';
+
+// The app's group → role mapping: business convention, so it is yours (axiom 8).
+declare function groupsToRoles(claims: Readonly<Record<string, unknown>>): string[];
+
+const auth = defineAuth({ adapter: memoryAuthAdapter(), providers: ['corp', 'github'] });
+const routes = identityProviderRoutes(auth, {
+  providers: [
+    samlIdentityProvider({
+      id: 'corp',
+      idp: parseSamlMetadata(await Bun.file('config/corp-idp-metadata.xml').text()),
+      spEntityId: 'https://app.example.com/saml/metadata',
+      trustEmail: true, // required: does this IdP vouch for the addresses it asserts?
+      emailDomains: ['corp.example'], // required with true: only these domains are believed
+    }),
+    oidcIdentityProvider({ provider: 'github' }),
+  ],
+  resolveGrants: (identity) => ({ roles: groupsToRoles(identity.claims) }), // yours, never shipped
+});
+// routes.start  GET  /auth/sso/:provider           → 302 to the IdP
+// routes.acs    POST /auth/sso/:provider/callback  → SAML ACS (register this URL at the IdP)
+// routes.callback GET /auth/sso/:provider/callback → OIDC redirect_uri
+```
+
+| Rule | Why |
+|---|---|
+| The assertion **itself** must be signed; a signed response around an unsigned assertion is refused | the node that is read is the node that was verified — no wrapping |
+| Exactly one `saml:Assertion` in the whole document, a direct child of the Response; no ID twice; no `ds:Object` | the signature-wrapping (XSW) attacks all need a second candidate |
+| The `Reference` must name the enveloping element's own `ID`; transforms exactly enveloped-signature + exc-c14n | no XPath/XSLT, no detached reference |
+| RSA-SHA256 with SHA-256 digests, RSA ≥ 2048 | SHA-1 is refused |
+| Keys come from metadata only; `KeyInfo` is never read | a self-signed cert in the response proves nothing |
+| NameID text is every text node concatenated | `a@corp.com<!---->.evil.com` reads as what was signed |
+| Recipient, Destination, InResponseTo, Audience, NotBefore/NotOnOrAfter (±`skewMs`, 60 s) | SP-initiated only: an unsolicited response has no InResponseTo to match |
+| One answer completes once: claimed in `auth.totpReplay` (the shared replay store) until it expires | replay across replicas |
+| DOCTYPE, entities, processing instructions refused by the reader | XXE, billion laughs |
+| An address is verified only inside `emailDomains` (exact; list subdomains); outside, it can neither link nor create an account. `trustEmail: true` with no domains does not compile, and refuses at construction (`X_CONFIG_INVALID`) | an IdP's admin can assert ANY address — unbound, one tenant's IdP signs in as another tenant's verified user |
+| Transient NameIDs refused | linked by a per-login id, every sign-in is a stranger |
+| Encrypted assertions refused (`meta.check: 'encrypted'`) | not supported |
+
+Every SAML refusal is `X_SAML_RESPONSE_INVALID` with the failed check in `meta.check` and a fix per
+check, logged as `auth.sso.refused`; the anonymous caller gets the code and title only. Bad metadata
+is `X_SAML_METADATA_INVALID` at boot. An id the routes do not serve is `X_IDENTITY_PROVIDER_UNKNOWN`.
+An adapter of your own is held to the same contract by
+`identityProviderConformance` (`@ultimat3/testing/conformance`).
+
 ## API keys — how an agent authenticates
 
 `ult_<env>_<id>_<secret>`. The plaintext is shown once; the row holds `sha256(secret)` and is
@@ -966,6 +1036,12 @@ export const actor = apiKeyActor(await verifyApiKey(auth.adapter, plaintext));
 | names no `userId` | nothing more — a key no user owns is cut by its scopes and its org alone |
 | names a `userId` | re-reads that user from the store. Missing or disabled is the same `X_API_KEY_INVALID` every other rejection is, on the very next use; `disableUser` also revokes the key outright |
 
+The `env` segment is part of the credential: a key issued `dev` and presented as `ult_prod_…` is
+the same `X_API_KEY_INVALID`, so the triage label cannot be forged. `lastUsedAt` is written at most
+once per `API_KEY_TOUCH_MS` (60 s), `As of 2026-11`: a dashboard's "last used", never an audit
+trail — N requests a second on one key are N reads, not N row-locked `UPDATE`s, the trade a
+session's `idleSlideMs` makes.
+
 A key's scopes only ever shrink on the way to the actor — never the owning user's roles, never a
 default set:
 
@@ -1026,7 +1102,7 @@ be built before boot installs the client, and joins an open `withTransaction`. I
 `authSubjectTarget({ executor, user })` is the identity tables as a `defineSubject({ targets })`
 entry (`@ultimat3/jobs`). `user(subject)` names the `x_users.id` the subject is
 (`({ row }) => String(row.userId)`), or `undefined` for none. The export carries the `x_users` row
-(`AUTH_SUBJECT_COLUMNS`) — never `password_hash`, `mfa_secret` or a recovery digest; the erase
+(its named columns) — never `password_hash`, `mfa_secret` or a recovery digest; the erase
 deletes the user (sessions and accounts cascade), their API keys and pending verifications. A
 user in several orgs is erased from all of them: list it `{ target, retain }` when that is wrong.
 
@@ -1045,7 +1121,7 @@ user in several orgs is erased from all of them: list it `{ target, retain }` wh
 | `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 |
-| `X_ACCOUNT_LOCKED` | the per-ip, per-account or per-org bucket is inside its lockout. The cause names the caller's own address or email, never an org |
+| `X_ACCOUNT_LOCKED` | the per-ip, per-account or per-org bucket is inside its lockout. The per-ip bucket counts a network (`ipKey` over core's `addressNetwork`: IPv4 whole, IPv6 by its /64). The cause names the caller's own network or email, never an org |
 | `X_API_KEY_INVALID` | key unknown, revoked, expired, wrong, or owned by a user who is gone or disabled |
 | `X_ENV_MISSING` | `oauthCredentials()` found no client id or secret for an enabled provider |
 | `X_AUTH_WRITE_FAILED` | an `AuthAdapter` lost a write it accepted — `emailVerifiedNotStored(provider, userId)` when `updateUser` drops the OAuth verified stamp |
@@ -1055,7 +1131,7 @@ user in several orgs is erased from all of them: list it `{ target, retain }` wh
 | `X_AUTH_SIGN_IN_UNCONFIGURED` | `signInUnconfigured(role, missing)`, thrown by the boot guard `x g sign-in` writes into the app: a `web` or `sync` role outside development and test with sign-in keys unset. Off the socket — a boot refusal, never a response |
 
 ```bash
-bun test packages/auth
+bun test ./packages/auth/
 bun run --filter @ultimat3/auth typecheck
 ```
 
@@ -1066,7 +1142,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 | Class | Code | Declared in |
 |---|---|---|
-| `AuthError` | any `AuthErrorCode` — `AUTH_ERROR_CODES` | `src/errors.ts` |
+| `AuthError` | any `AuthErrorCode` | `src/errors.ts` |
 
 ## Supporting exports
 
@@ -1076,12 +1152,11 @@ a job boundary the class is gone and the `code` is what survives — match on th
 |---|---|
 | `JwtBearerCaller` | what `jwtBearerResolver` answers: `{ actor, scopes }`, structurally `ApiKeyCaller` |
 | `JwtBearerResolverOptions` | what `jwtBearerResolver` takes |
-| `JwtBearerCheck` | the check a refusal's log line names: a `WorkloadCheck`, or `key-set`, `scope`, `accept` |
 | `WorkloadCheck` · `WorkloadTokenCheck` | `checkWorkloadToken`'s verdict: the token, or the check that refused it |
 | `PostgresTotpReplayGuard` | the `TotpReplayGuard` `postgresTotpReplayGuard` returns |
 | `PostgresTotpReplayGuardOptions` | what `postgresTotpReplayGuard` takes |
-| `TotpReplayFactory` | `() => TotpReplayGuard`: what `configureTotpReplay` takes |
-| `PasskeyPolicy` · `PasskeyPolicyInput` · `PasskeyRelyingParty` · `DEFAULT_PASSKEY_CHALLENGE_TTL_MS` | the `passkeys` block, resolved and as written; the `{ rpId, origins }` a verifier needs |
+| `TotpReplayFactory` | `() => TotpReplayGuard`: what `installTotpReplay` takes (`@ultimat3/auth/adapter`) |
+| `PasskeyPolicy` · `PasskeyPolicyInput` · `PasskeyRelyingParty` | the `passkeys` block, resolved and as written; the `{ rpId, origins }` a verifier needs |
 | `PasskeyCredential` · `PasskeyChallengeRecord` · `PasskeyEvidence` · `PasskeyCeremony` · `PasskeyStore` | the passkey rows and the adapter slice that stores them |
-| `PasskeyCreationOptions` · `PasskeyRequestOptions` · `PasskeyRegistrationResponse` · `PasskeyAssertionResponse` · `PasskeyCredentialDescriptor` | the JSON wire of a ceremony (WebAuthn L3's `*JSON` dictionaries) |
+| `PasskeyCreationOptions` · `PasskeyRequestOptions` · `PasskeyCredentialDescriptor` (the two responses: `@ultimat3/auth/client`) | the JSON wire of a ceremony (WebAuthn L3's `*JSON` dictionaries) |
 | `PasskeyLogin` · `PasskeyStepUp` · `PasskeyStepUpOptions` | what the two factories answer and take |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "30.9.0",
+  "version": "31.0.0",
   "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
   "keywords": [
     "ultimate",
@@ -28,6 +28,7 @@
   },
   "exports": {
     ".": "./src/index.ts",
+    "./adapter": "./src/adapter-subpath.ts",
     "./client": "./src/client.ts",
     "./soft-authenticator": "./src/soft-authenticator.ts"
   },
@@ -47,8 +48,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "30.9.0",
-    "@ultimat3/db": "30.9.0",
-    "@ultimat3/schema": "30.9.0"
+    "@ultimat3/core": "31.0.0",
+    "@ultimat3/db": "31.0.0",
+    "@ultimat3/schema": "31.0.0"
   }
 }

package/src/adapter-subpath.ts

@@ -0,0 +1,34 @@
+// `@ultimat3/auth/adapter` — auth's three `ADAPTER_PORTS` rows (`authLimiter`, `totpReplay`,
+// `authServerStore`) and the KDF gate's width: interfaces, installers and resets, never on the `.`
+// barrel, so an app swaps each one way — `apps/<app>/runtime.ts`. Not `src/adapter.ts`: that is
+// the `AuthAdapter` seam's.
+
+export {
+  installAuthServerStore,
+  installedAuthServerStore,
+  resetAuthServerStore,
+} from './authorization-server-installed';
+export type {
+  AuthServerStore,
+  DeviceDecision,
+  RefreshRotation,
+} from './authorization-server-store';
+export type {
+  AuthCodeRecord,
+  AuthGrantRecord,
+  AuthServerClient,
+  AuthTokenKind,
+  AuthTokenRecord,
+  DeviceCodeRecord,
+  DeviceStatus,
+} from './authorization-server-types';
+export { installKdfGate, resetKdfGate } from './kdf-gate';
+export type { AuthLimiterFactory, TotpReplayFactory } from './limiter-install';
+export {
+  installAuthLimiters,
+  installTotpReplay,
+  resetAuthLimiters,
+  resetTotpReplay,
+} from './limiter-install';
+export type { TotpReplayGuard } from './mfa';
+export type { AuthLimiter, AuthLimiterScope, AuthRateLimitPolicy } from './rate-limit';