@ultimat3/auth 24.0.0 → 25.1.0

package/CLAUDE.md

@@ -12,7 +12,7 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | Better Auth | binds through `AuthAdapter`. It is an adapter, never a dependency. |
 | Errors | `AuthError` from `errors.ts`; never `throw new Error` |
 | Time | take a `Clock`. No `Date.now()` anywhere in this package. |
-| Secrets | compare with `timingSafeEqual` (from `@ultimat3/core`, re-exported off `tokens.ts` — same implementation `@ultimat3/storage` uses); store `sha256Hex`. Never `===` on a secret. |
+| Secrets | compare with `timingSafeEqual` (imported from `@ultimat3/core` — never re-exported here, same implementation `@ultimat3/storage` uses); store `sha256Hex`. Never `===` on a secret. |
 
 ## Non-negotiables
 
@@ -63,7 +63,7 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   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 → `createAuthLimiter`. `installedAuthLimiter` and
+  `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.
@@ -86,6 +86,9 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   `alg: none` are refused in `decodeJwtHeader`. It checks `nbf` and `azp` too.
 - **`resolveGrants` is a seam, never a group-to-role table**, called on EVERY login. Absent leaves
   the row alone. A user created with no roles and no org logs a warning.
+  Its second argument (`OAuthGrantContext`, `oauth-grant-context.ts`, #670) is the token set, the
+  whole verified id-token payload and a LAZY, once-per-login, `sub`-checked `userinfo()` — read
+  through `oauth-profile.ts`'s `userinfoBody`, never a second userinfo reader.
 - **`verifySession` writes at most once per `idleSlideMs`** (default `idleTtlMs / 20`). Never cache
   the USER row — `authenticate` re-reads it every request so a revoked role bites on the next one.
   In `observed`, `null` is an ANSWER (clears the stored value) and `undefined` is silence.
@@ -112,6 +115,8 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   `FIX_SHELL_ARG_PINS`). `${provider}` is registry-validated boot config, not foreign.
 - Cookies are read through `@ultimat3/core`'s `readCookie` (`readSessionCookie`, the oauth
   handshake), which never throws on a malformed value (`decodeURIComponent('%')`).
+  They are WRITTEN through its `serializeSetCookie`, never a literal (`bun run set-cookie-literals`,
+  `X_SET_COOKIE_HAND_BUILT`); `cookie-golden.test.ts` pins the bytes.
 - 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).
@@ -140,18 +145,20 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   changed underneath is `skipped` — and `x doctor` counts what is left. Whether a value is sealed is
   `isSealed`'s to say, never a `like` in an adapter (`listUsersWithMfaSecret` returns them all).
 - **`providerJwks` memoises only the DEFAULT client**; a caller supplying options gets its own.
-- **A JWKS refresh is single-flighted through core's `createSingleFlight` with
-  `deadlineMs = timeoutMs * 2`**; eviction frees the key, never the work, and a `createFence`
+- **A JWKS refresh is single-flighted through core's `singleFlight` with
+  `deadlineMs = timeoutMs * 2`**; eviction frees the key, never the work, and a `generationFence`
   generation check (read, never `guard`) stops a superseded refresh overwriting the cache.
   `schedule` is injectable.
 - **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.
-- **`MemoryAdapter.createUser` and `updateUser` enforce `x_users.id`, `email` and `external_id`
+- **`MemoryAuthAdapter.createUser` and `updateUser` enforce `x_users.id`, `email` and `external_id`
   uniqueness** (`authUniqueViolation`, `X_AUTH_WRITE_FAILED`), NULLS DISTINCT like Postgres;
-  `BuiltinAdapter` answers the same code through `builtin-adapter-violation.ts`.
-  **`MemoryAdapter` takes a `Clock`** (default `systemClock`) and stamps every instant from it.
+  `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.
+- **`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
@@ -160,19 +167,22 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   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. Roles are policy's to expand, so the default grants are the
+  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: `MemoryAdapter` IS an `ApiKeyStore`.
+  the database client). No second in-memory key store: `MemoryAuthAdapter` IS an `ApiKeyStore`.
 - 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 `createFlightGate`, the
+  (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`). `login()`
@@ -191,7 +201,7 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 - **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.
-- **`createTotpReplayGuard`'s table is bounded and the eviction ORDER is the guarantee**: subjects
+- **`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.
@@ -227,14 +237,15 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | `id-token.ts` | id token → claims this handshake may believe |
 | `id-token-fixture.ts` | the one string-input JWT builder the OAuth tests share. Off `index.ts` |
 | `auth-fixture.ts` | the KDF parameters, the password and the `AuthError` catcher the three `auth*.test.ts` suites share. Off `index.ts` |
-| `oauth-profile.ts` | claims or userinfo → one `OAuthProfile` |
+| `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-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 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 |
-| `kdf-gate.ts` | the one bound on concurrent argon2 work, and the `X_OVERLOADED` past it — core's `createFlightGate` with auth's own refusal injected |
+| `kdf-gate.ts` | the one bound on concurrent argon2 work, and the `X_OVERLOADED` past it — core's `flightGate` with auth's own refusal injected |
 | `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` |
 | `sign-out.ts` | `signOutHeaders({ session? })` — the expired session cookie plus `Clear-Site-Data: "cache", "storage"` (`SIGN_OUT_CLEAR_SITE_DATA`), never `"cookies"`. A PWA's offline cache does not survive a sign-out, by decision (a cached private page IS the previous principal's data); the page boot's rescope wipe is the second line. Secure contexts only |
@@ -252,7 +263,7 @@ Gotchas:
   this package **owns**, unconditionally, and lists the borrowed two in `AUTH_BORROWED_ERROR_CODES`
   without a title. A `hasErrorCode()` guard would suppress the `X_ERROR_CODE_DUPLICATE` that is
   supposed to fire when two packages claim one code.
-- Tests run against `MemoryAdapter`; the one ADAPTER test that boots a database is
+- Tests run against `MemoryAuthAdapter`; the one ADAPTER test that boots a database is
   `adapter-parity-identity.test.ts` (PGlite). The two other exceptions are
   `postgresAuthLimiter`'s, and they are exceptions in the shape the repo already has: the
   scripted-executor twin (`rate-limit-postgres.test.ts`) proves the protocol with no server,

package/README.md

@@ -5,10 +5,10 @@ authorizes on a session row, a user row or an api key — http, actions, jobs an
 `ctx.actor` and hand it to `@ultimat3/policy`. One authz system, never two.
 
 ```ts
-import { BuiltinAdapter, defineAuth, login, oauthLogin } from '@ultimat3/auth';
+import { defineAuth, login, oauthLogin, postgresAuthAdapter } from '@ultimat3/auth';
 
 export const auth = defineAuth({
-  adapter: new BuiltinAdapter(),          // or MemoryAdapter, or your Better Auth binding
+  adapter: postgresAuthAdapter(),          // or memoryAuthAdapter(), or your Better Auth binding
   session: { absoluteTtlMs: 30 * 864e5, idleTtlMs: 7 * 864e5 },
   password: { minLength: 12 },
   mfa: { issuer: 'Acme' },                // the authenticator app's name; `required` only as `false`
@@ -46,7 +46,7 @@ const { start, callback } = oauthLogin(auth);
 
 ## The lockout across replicas
 
-`createAuthLimiter` keeps its table in the process, so `maxAttempts: 5` at `replicas: 3` lets an
+`memoryAuthLimiter` keeps its table in the process, so `maxAttempts: 5` at `replicas: 3` lets an
 account survive 15 guesses and hides each replica's lockout from the other two. An app that runs
 more than one process says so and brings a limiter that says the same:
 
@@ -96,7 +96,7 @@ const { identity } = await verifyWorkloadToken({
   token,
   issuers: ['https://kubernetes.default.svc'],
   audience: 'https://ledger.internal',
-  keys: createJwksClient({ provider: 'k8s', jwksUri: 'https://kubernetes.default.svc/openid/v1/jwks' }),
+  keys: jwksClient({ provider: 'k8s', jwksUri: 'https://kubernetes.default.svc/openid/v1/jwks' }),
   clock,
 });
 const actor = actorFromService(identity);   // kind: 'service', id: the caller's own sub
@@ -193,7 +193,7 @@ A **factory** and not a limiter, because the host runs before the app: `defineAu
 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
+Precedence is `defineAuth({ limiter })` → the installed factory → `memoryAuthLimiter`, 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.
 
@@ -263,7 +263,7 @@ because a default is what silently makes a second door as trusting as the first.
 | `keys` | Means |
 |---|---|
 | `'token-endpoint-tls'` | this token came off a TLS response from the provider's own token endpoint — the one case OIDC Core 3.1.3.7 exempts. `exchangeOAuthCode` passes it, and that is the only shipped call site that may |
-| a `JwksKeySource` | the signature is checked. `providerJwks(providerFor(id))`, or `createJwksClient({ provider, jwksUri })` |
+| a `JwksKeySource` | the signature is checked. `providerJwks(providerFor(id))`, or `jwksClient({ provider, jwksUri })` |
 
 ```ts
 const keys = providerJwks(providerFor('bigco-sso'));
@@ -302,6 +302,31 @@ convention and business convention never ships ([axiom
 **every** login — so removing somebody from a group in the IdP takes effect at their next sign-in,
 rather than never. A seam that returns the stored answer writes nothing.
 
+**The profile is not all the IdP said.** `resolveGrants(profile, context)` takes a second argument
+(`OAuthGrantContext`) for an IdP that keeps authorization facts off the id token — groups,
+entitlements, an `allowed_oauth_apps` claim served on `/userinfo` only:
+
+```ts
+import { defineAuth, memoryAuthAdapter, oauthLogin } from '@ultimat3/auth';
+
+const auth = defineAuth({ adapter: memoryAuthAdapter(), providers: ['google'] });
+
+export const { start, callback } = oauthLogin(auth, {
+  resolveGrants: async (_profile, context) => {
+    const claims = await context.userinfo();
+    const apps = Array.isArray(claims['allowed_oauth_apps']) ? claims['allowed_oauth_apps'] : [];
+    return apps.includes('bank-integrations') ? { roles: ['member'] } : { roles: [] };
+  },
+});
+```
+
+| `context.` | What it is |
+|---|---|
+| `provider` | the provider id this login came through |
+| `tokens` | the exchange's `OAuthTokens`, in flight — the framework stores none of them; keeping one is the app storing a credential |
+| `idTokenClaims` | every claim of the VERIFIED id token, the ones `OAuthProfile` drops included (`hd`, `groups`); `null` without one |
+| `userinfo()` | the provider's userinfo body, every claim, read with the access token — lazily (no call, no request) and at most once per login; none at all when the profile was already read off userinfo (GitHub), whose body it hands back. A body naming another `sub` is `X_OAUTH_EXCHANGE_FAILED`; so is a provider with no userinfo endpoint, and a failed read, which is not remembered |
+
 ## MFA — TOTP and recovery codes
 
 TOTP is pure functions over a secret and a clock; what is STORED goes through two writers and one
@@ -339,7 +364,7 @@ every enrolled user's second factor.
 |---|---|
 | `enrolTotp(auth, { account, issuer?, secret? })` | `{ secret, uri, digits, periodSeconds }` — `issuer` omitted is `auth.mfa.issuer`, `secret` omitted mints one |
 | `verifyTotp({ secret, code, at, drift?, usedSteps? })` | `{ ok, step }`. `step` is the window the code belonged to, `null` on no match |
-| `createTotpReplayGuard(drift?, maxSubjects?)` | the in-process `{ isUsed, remember, size }`; a fleet passes a Redis-backed pair of the same two methods |
+| `memoryTotpReplayGuard(drift?, maxSubjects?)` | the in-process `{ isUsed, remember, size }`; a fleet passes a Redis-backed pair of the same two methods |
 | `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 |
@@ -438,14 +463,14 @@ import {
   consumeVerification,
   issueVerification,
   type MailSender,
-  MemoryAdapter,
+  memoryAuthAdapter,
   type VerificationRuntime,
 } from '@ultimat3/auth';
 import { systemClock } from '@ultimat3/core';
 
 declare const mail: MailSender;   // the app wires @ultimat3/mail's `send` here
 
-const runtime: VerificationRuntime = { store: new MemoryAdapter(), clock: systemClock, mail };
+const runtime: VerificationRuntime = { store: memoryAuthAdapter(), clock: systemClock, mail };
 
 const issued = await issueVerification(runtime, {
   purpose: 'password-reset',
@@ -484,9 +509,15 @@ unauthenticated POST with any token cannot kill the victim's live link.
 | `revokeOrgSessions(auth, orgId, reason)` | one tenant, at 03:00, without touching another |
 | `revokeSessionsCreatedBefore(auth, at, reason)` | everything minted under a rotated secret |
 | `disableUser(auth, userId, reason)` | stamps `disabledAt`, kills the sessions **and** revokes the user's live api keys — `{ user, sessionsRevoked, apiKeysRevoked }`. Re-enabling restores neither |
-| `listOrgUsers(auth, orgId, { role })` | the quarterly access review, as safe summaries |
+| `listOrgUsers(auth, orgId, { role })` | the quarterly access review, as safe summaries — in byte (code-point) order of `email` on both adapters, whatever the database collation |
 | `updatePrivileges(auth, userId, patch, session?)` | the grant, plus the session rotation it requires. A `passwordHash` change ends every OTHER session of that user (`sessionsRevoked`) — all of them when no session of theirs was passed, as in a reset |
 
+Rotation (`rotateSession`, and `updatePrivileges` through it) mints a new **id**, never a new
+lifetime: `createdAt` and `absoluteExpiresAt` carry over, so repeated grants cannot outlive the
+original ceiling and `revokeSessionsCreatedBefore` still catches a rotated session. The rotated
+cookie's `Max-Age` counts down to that ceiling. `createSession` accepts the same two instants and
+clamps them — `createdAt` to now, the ceiling to `createdAt + absoluteTtlMs` — so they only shorten.
+
 `reason` is a required argument on every revocation, for the reason `crossTenant()` requires one:
 an incident review asks who killed these sessions and why, and a `delete` with no line answers
 neither. Each one logs `auth.revocation` before it runs.
@@ -505,8 +536,8 @@ an adapter implementation, not a dependency of this package.
 
 | Driver | Use |
 |---|---|
-| `BuiltinAdapter` | Postgres via `@ultimat3/db`. `new BuiltinAdapter(client?, clock?)` — the process client and `systemClock` by default; the clock stamps `x_verifications.consumed_at` |
-| `MemoryAdapter` | `x new` before a database exists, and every test in this package. `new MemoryAdapter(clock)` — `systemClock` by default — stamps every instant it writes |
+| `postgresAuthAdapter(client?, clock?)` | Postgres via `@ultimat3/db` (the `PostgresAuthAdapter` type) — the process client and `systemClock` by default; the clock stamps `x_verifications.consumed_at` |
+| `memoryAuthAdapter(clock?)` | `x new` before a database exists, and every test in this package (the `MemoryAuthAdapter` type). Its clock — `systemClock` by default — stamps every instant it writes |
 | your own | implement `AuthAdapter`; DDL in `tables.ts` shows what the columns mean |
 
 **An adapter stores and matches the address it is handed — it never folds case.** `x_users.email`
@@ -549,7 +580,10 @@ row would not be, and nothing does.
 
 ## Cookie
 
-`__Host-x_session`, set by `sessionCookie(token, policy)`.
+`__Host-x_session`, set by `sessionCookie(token, policy)`. A **rotated** session keeps its
+original ceiling, so its cookie takes the time left, not the full TTL:
+`sessionCookie(issued.token, policy, { maxAgeSeconds: remainingMaxAgeSeconds(issued.session, clock.now()) })`
+— what `updatePrivileges` already does for you.
 
 | Attribute | Attack it closes |
 |---|---|
@@ -559,6 +593,13 @@ row would not be, and nothing does.
 | `__Host-` + `Path=/` + no `Domain` | a sibling subdomain overwriting it (session fixation) |
 | `Max-Age` | a client keeping it past the server's absolute ceiling |
 
+Every cookie this package writes — the session, its clearing line, the OAuth handshake and its
+clearing line — is built by `@ultimat3/core`'s `serializeSetCookie`, never spelled by hand
+(`bun run set-cookie-literals`). `As of 2026-10-06` the attributes are written `Max-Age=…; Path=/`
+rather than `Path=/; Max-Age=…` — the same cookie to a browser, which gives attribute order no
+meaning — and a cookie `name` that is not an RFC 6265 token is `X_COOKIE_INVALID` instead of a
+line a browser would mangle.
+
 ## Signing out
 
 `logout(auth, token)` ends the session row. The **response** does the rest: append
@@ -595,17 +636,39 @@ the previous scope's persisted rows and queued writes).
 `beginOAuth`, the handshake cookie and `completeOAuthLogin`. Provider configs stay pure data —
 importing `oauth.ts` performs no network I/O and reads no env.
 
+Mount both in the app's own server through **`runtime.routes`**: `apps/<app>/runtime.ts`
+exporting `runtime` (`RuntimeOverrides`). `x dev` and `runRole` both read that file and mount its
+routes through the whole pipeline — `configureAuthenticator`, the rate limiter, the security
+headers, the SIGTERM drain. Never a second `Bun.serve` beside the app: it stands on its own
+socket, outside every one of those, and a login flow is the last surface that should run
+unthrottled and unheadered.
+
 ```ts
+// apps/web/runtime.ts
+import {
+  type AuthRouteDescriptor,
+  defineAuth,
+  oauthLogin,
+  postgresAuthAdapter,
+} from '@ultimat3/auth';
+import type { ServeOptions } from '@ultimat3/cli/serve';
+import type { Route } from '@ultimat3/http';
+
+// The app's one `auth` — imported from wherever it declares it.
+const auth = defineAuth({ adapter: postgresAuthAdapter(), providers: ['github'] });
 const { start, callback } = oauthLogin(auth);
 
-Bun.serve({
-  fetch(request) {
-    const { pathname } = new URL(request.url);
-    if (pathname.endsWith('/callback')) return callback.handle(request);
-    if (pathname.startsWith('/auth/oauth/')) return start.handle(request);
-    return new Response(null, { status: 404 });
-  },
+// A descriptor takes a bare `Request`: the pipeline's `UltimateRequest` carries it as `raw`.
+const mounted = (leg: AuthRouteDescriptor): Route => ({
+  method: leg.method,
+  path: leg.path,
+  handler: (request) => leg.handle(request.raw),
+  meta: { name: leg.name, auth: leg.auth },
 });
+
+export const runtime: NonNullable<ServeOptions['runtime']> = {
+  routes: [start, callback].map(mounted),
+};
 ```
 
 | | `start` | `callback` |
@@ -617,20 +680,9 @@ Bun.serve({
 A **descriptor**, never a mounted handler — the same category as `mcpHttpRoute()`. `@ultimat3/http`
 is tier 2 like this package, so auth may not import it, and `defineRoute` is tier 4 and describes
 a rendered page. A bare `Request` in, a `Response` out: drivable from a test, mountable by any
-router that can match a `:param`.
-
-**The `Bun.serve` above is library usage, not app usage.** An Ultimate app's server is `runRole`
-(`apps/web/server.ts` is three lines that call it), and `As of 2026-08` `ServeOptions` has no
-routes seam — the route list is built inside `serveApp` and closed. So a second `Bun.serve` in an
-app does not extend that server, it stands beside it: on its own socket, outside the pipeline, and
-therefore outside `configureAuthenticator`, the rate limiter, the security headers and the
-SIGTERM drain. A login flow is the last surface that should be the one running unthrottled and
-unheadered.
-
-Until the seam exists, an app serving these descriptors serves them itself and pays for all of
-that itself — a second port to publish and health-check, its own throttle in front of `callback`,
-its own security headers, and a drain that does not strand a handshake mid-flight. There is no
-mounting API to call today; do not write one, and do not read this section as promising one.
+router that can match a `:param` — and `runtime.routes` is the one an app has. It mounts after the
+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
@@ -712,6 +764,9 @@ JWT signed with the `.p8` key, which Apple expires every six months.
   the status alone there mints a session from a failed exchange.
 - An address is only linked to an existing account when **both** sides verified it (`link:
   'verified-email'`). Otherwise whoever registered the address first inherits the login.
+- An address the provider did **not** verify never creates an account either — it is the same
+  `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.
 
 ## API keys — how an agent authenticates
 
@@ -741,7 +796,9 @@ default set:
 
 - `*` and `<resource>:*` are refused at `issueApiKey` (`X_CONFIG_INVALID`), and dropped from a row
   that already holds one.
-- A key a user owns keeps only the scopes that owner's grants cover. This package can read the
+- A key a user owns keeps only the scopes that owner's grants cover — `@ultimat3/core`'s
+  `grantCovers`, the reading `can()` uses: an owner with `billing:invoice:*` covers
+  `billing:invoice:read`, never `billing:refund:issue`. This package can read the
   row's `permissions` and `scopes` (`directGrants`) and cannot expand a role — that is
   `@ultimat3/policy`'s — so an app whose users hold roles says what they grant:
 
@@ -766,13 +823,13 @@ for both doors.
 
 ```ts
 import type { ApiKeyVerifyStore } from '@ultimat3/auth';
-import { apiKeyResolver, BuiltinAdapter } from '@ultimat3/auth';
+import { apiKeyResolver, postgresAuthAdapter } from '@ultimat3/auth';
 
 let keys: ApiKeyVerifyStore | undefined;
 
 /** `resolveToken: resolveKey` — on the mount, and on `defineAppMcp()`. */
 export const resolveKey = apiKeyResolver(() => {
-  keys ??= new BuiltinAdapter();
+  keys ??= postgresAuthAdapter();
   return keys;
 });
 ```
@@ -784,8 +841,8 @@ export const resolveKey = apiKeyResolver(() => {
 | a store that FAILS | the throw, untouched — a database that is down is not a wrong key |
 
 The store is a THUNK, read when a token is presented: a mount is declared when its module is
-evaluated, and `new BuiltinAdapter()` takes the process's database client, which boot installs
-later. In a test the store is `new MemoryAdapter()` — every `AuthAdapter` is an
+evaluated, and `postgresAuthAdapter()` takes the process's database client, which boot installs
+later. In a test the store is `memoryAuthAdapter()` — every `AuthAdapter` is an
 `ApiKeyVerifyStore` (an `ApiKeyStore` that can also `findUserById`).
 
 ## Errors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "24.0.0",
+  "version": "25.1.0",
   "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
   "license": "MIT",
   "type": "module",
@@ -25,15 +25,15 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "24.0.0",
-    "@ultimat3/db": "24.0.0",
-    "@ultimat3/schema": "24.0.0"
+    "@ultimat3/core": "25.1.0",
+    "@ultimat3/db": "25.1.0",
+    "@ultimat3/schema": "25.1.0"
   }
 }

package/src/adapter.ts

@@ -1,7 +1,7 @@
 // Single responsibility: the persistence seam. `AuthAdapter` is the one interface auth talks
 // to, split into per-concern stores so a test (or a caller) can satisfy just the slice it uses.
 // Better Auth binds here — it is an adapter implementation, not a dependency. The blessed
-// default is `BuiltinAdapter` in `builtin-adapter.ts`; the DDL it expects is in `tables.ts`.
+// default is `PostgresAuthAdapter` in `builtin-adapter.ts`; the DDL it expects is in `tables.ts`.
 
 export interface AuthUser {
   readonly id: string;
@@ -137,6 +137,10 @@ export interface SessionStore {
   getSession(id: string): Promise<AuthSession | null>;
   createSession(session: AuthSession): Promise<AuthSession>;
   updateSession(id: string, patch: SessionPatch): Promise<AuthSession | null>;
+  /**
+   * Remove one session and answer whether THIS call removed it, in one atomic step: `rotateSession`
+   * treats `true` as its claim on the id, so two concurrent deletes must not both answer `true`.
+   */
   deleteSession(id: string): Promise<boolean>;
   /** Returns how many were killed — the "sign out everywhere else" number shown to the user. */
   deleteOtherSessions(userId: string, keepSessionId: string): Promise<number>;
@@ -227,7 +231,7 @@ export interface ApiKeyStore {
 }
 
 /**
- * The full seam. One blessed implementation ships (`BuiltinAdapter`); Better Auth, or any
+ * The full seam. One blessed implementation ships (`PostgresAuthAdapter`); Better Auth, or any
  * other identity backend, binds by implementing this and nothing else changes upstream.
  */
 export interface AuthAdapter

package/src/api-key-resolver.ts

@@ -32,8 +32,8 @@ export interface ApiKeyResolverOptions extends ApiKeyActorOptions {
  * `defineAppMcp()` — one resolver for both.
  *
  * `store` is a THUNK, read when a token is presented and never captured: a mount is declared when
- * its module is evaluated, and `new BuiltinAdapter()` takes the process's database client, which
- * boot installs later. `() => new MemoryAdapter()` would be a new, empty store per request — hold
+ * its module is evaluated, and `postgresAuthAdapter()` takes the process's database client, which
+ * boot installs later. `() => memoryAuthAdapter()` would be a new, empty store per request — hold
  * the instance and return it.
  */
 export function apiKeyResolver(

package/src/api-keys.ts

@@ -4,12 +4,12 @@
 // evaluation a human does. The plaintext is shown once; only its SHA-256 is ever stored, and
 // lookup happens by the non-secret id so the secret never appears in a query, an index or a log.
 
-import { type Clock, randomHex, systemClock } from '@ultimat3/core';
+import { type Clock, randomHex, systemClock, timingSafeEqual } from '@ultimat3/core';
 import type { ApiKeyStore, AuthApiKeyRecord, AuthUser, UserStore } from './adapter';
 import { apiKeyEnvInvalid, apiKeyInvalid, apiKeyScopeWildcard } from './errors';
 import type { PolicyActor } from './policy-bridge';
 import { actorFromApiKey, isWildcardScope } from './policy-bridge';
-import { randomToken, sha256Hex, timingSafeEqual } from './tokens';
+import { randomToken, sha256Hex } from './tokens';
 
 export const API_KEY_NAMESPACE = 'ult';
 

package/src/auth.ts

@@ -3,14 +3,14 @@
 // (http, actions, jobs, MCP) authorizes on that and never on a session row, so there is one
 // identity shape in the framework and `@ultimat3/policy` is the only thing that reads it.
 
-import { type Clock, systemClock, uuid } from '@ultimat3/core';
+import { type Clock, systemClock, timingSafeEqual, uuidV7 } from '@ultimat3/core';
 import { t } from '@ultimat3/schema';
 import type { AuthAdapter, AuthSession, AuthUser } from './adapter';
 import { normaliseEmail } from './email';
 import { mfaRequiredUnenforceable, sessionUnknown } from './errors';
 import { installedAuthLimiter } from './limiter-install';
 import { openLoginAttempt } from './login-attempt';
-import { createTotpReplayGuard, type TotpReplayGuard } from './mfa';
+import { memoryTotpReplayGuard, type TotpReplayGuard } from './mfa';
 import { mfaChallengeRequired } from './mfa-challenge';
 import type { OAuthProviderId } from './oauth';
 import {
@@ -27,9 +27,9 @@ import {
   type AuthRateLimitPolicy,
   accountKey,
   assertAuthLimiterPolicy,
-  createAuthLimiter,
   DEFAULT_AUTH_RATE_LIMIT,
   loginFailed,
+  memoryAuthLimiter,
   orgRateLimit,
 } from './rate-limit';
 import {
@@ -41,7 +41,7 @@ import {
   sessionCookie,
   verifySession,
 } from './session';
-import { sha256Hex, timingSafeEqual } from './tokens';
+import { sha256Hex } from './tokens';
 
 // The projections safe to hand to a client or an MCP tool: no password hash, no TOTP secret,
 // no token hash. The private columns live in `adapter.ts` and never leave the server.
@@ -136,7 +136,7 @@ export interface AuthConfigInput {
   readonly password?: Partial<PasswordPolicy> | undefined;
   readonly rateLimit?: Partial<AuthRateLimitPolicy> | undefined;
   /**
-   * Where failed attempts are counted. Omitted means `createAuthLimiter`, which is one process'
+   * Where failed attempts are counted. Omitted means `memoryAuthLimiter`, which is one process'
    * worth of state — correct for dev and tests, and `maxAttempts × N` for N replicas. An app that
    * runs more than one declares `rateLimit.scope: 'shared'` and passes a limiter that says the
    * same, or `defineAuth` refuses here rather than at 3am on the first spray.
@@ -150,7 +150,7 @@ export interface AuthConfigInput {
   readonly mfa?: Partial<AuthMfaPolicy> | undefined;
   /**
    * Which TOTP steps have been spent, read and written by `completeMfa`. Omitted means
-   * `createTotpReplayGuard()` — one process' worth of memory, so a code is single-use per replica;
+   * `memoryTotpReplayGuard()` — one process' worth of memory, so a code is single-use per replica;
    * a fleet that needs it single-use everywhere passes a shared guard with the same two methods.
    */
   readonly totpReplay?: TotpReplayGuard | undefined;
@@ -197,13 +197,13 @@ export function defineAuth(config: AuthConfigInput): Auth {
   // 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);
+    config.limiter ?? installedAuthLimiter(rateLimit) ?? memoryAuthLimiter(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. Only the LOCAL fallback is exempt, and exempting it
-  // is what buys that: `createAuthLimiter` always reports `'process'`, which is the one arm the
+  // is what buys that: `memoryAuthLimiter` 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
@@ -211,7 +211,7 @@ export function defineAuth(config: AuthConfigInput): Auth {
   // is refused for one bucket and trusted for the other.
   const orgLimits = orgRateLimit(rateLimit);
   const suppliedOrgLimiter = config.orgLimiter ?? installedAuthLimiter(orgLimits);
-  const orgLimiter = suppliedOrgLimiter ?? createAuthLimiter(clock, orgLimits);
+  const orgLimiter = suppliedOrgLimiter ?? memoryAuthLimiter(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
@@ -232,7 +232,7 @@ export function defineAuth(config: AuthConfigInput): Auth {
     orgRateLimit: orgLimiter.policy,
     orgLimiter,
     mfa,
-    totpReplay: config.totpReplay ?? createTotpReplayGuard(),
+    totpReplay: config.totpReplay ?? memoryTotpReplayGuard(),
     // BREAKING (majors only): the default is `[]`, never the live registry.
     //
     // It was `oauthProviderIds()`, so `defineAuth({ providers })`'s own documented purpose — the
@@ -259,7 +259,7 @@ export interface RegisterInput {
 export async function register(auth: Auth, input: RegisterInput): Promise<AuthUser> {
   checkPasswordStrength(input.password, { policy: auth.password });
   return await auth.adapter.createUser({
-    id: uuid(auth.clock),
+    id: uuidV7(auth.clock),
     email: normaliseEmail(input.email),
     passwordHash: await hashPassword(input.password, auth.password.params),
     orgId: input.orgId ?? null,

package/src/builtin-adapter-violation.ts

@@ -1,4 +1,4 @@
-// Single responsibility: an `x_users` unique violation as the code `MemoryAdapter` answers. One
+// Single responsibility: an `x_users` unique violation as the code `MemoryAuthAdapter` answers. One
 // duplicate signup must not be `X_AUTH_WRITE_FAILED` under `x dev` and `X_DB_UNIQUE_VIOLATION` in
 // production: an app that branches on the code passes its tests and misses on Postgres.