@ultimat3/auth 1.2.0 → 3.0.0

package/README.md

@@ -5,17 +5,21 @@ 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 } from '@ultimat3/auth';
+import { BuiltinAdapter, defineAuth, login, oauthLogin } from '@ultimat3/auth';
 
 export const auth = defineAuth({
   adapter: new BuiltinAdapter(),          // or MemoryAdapter, or your Better Auth binding
   session: { absoluteTtlMs: 30 * 864e5, idleTtlMs: 7 * 864e5 },
   password: { minLength: 12 },
-  mfa: { issuer: 'Acme' },
+  mfa: { issuer: 'Acme' },                // the authenticator app's name; `required` only as `false`
   providers: ['github', 'google'],
+  link: 'verified-email',                 // the default; `'never'` is the only other value
 });
 
 const { actor, token, cookie } = await login(auth, { email, password, ip });
+
+// "Log in with GitHub" is a link to /auth/oauth/github. These two routes are what serves it.
+const { start, callback } = oauthLogin(auth);
 ```
 
 ## Rules
@@ -23,9 +27,327 @@ const { actor, token, cookie } = await login(auth, { email, password, ip });
 - Every login failure throws `loginFailed()` from `rate-limit.ts`. Never a specific message.
 - Session ids are opaque random tokens; only `sha256(secret)` reaches the database.
 - Absolute and idle expiry are evaluated **independently**. Activity never moves the ceiling.
-- PKCE is mandatory on every provider. A missing verifier fails the callback.
+- PKCE is mandatory on every provider — `OAuthProvider.usesPkce` is the literal `true`, so
+  `usesPkce: false` does not typecheck and there is no branch that skips the verifier.
 - Recovery codes, verification tokens and api keys are hashed at rest and single-use.
+- A verification token is consumed **only when its hash matches**, in the same statement — the
+  store takes `(purpose, identifier, tokenHash)`. Consuming first and comparing afterwards made an
+  unauthenticated wrong guess destroy the victim's live reset link.
 - Guards assert on the actor. They never evaluate a policy.
+- A user's `scopes` column reaches `Actor.scopes`, so a human can hold a scope. `permissions` is a
+  different field and `hasScope()` does not read it.
+- `verifySession` writes at most once per `idleSlideMs`, not once per request.
+- The lockout counts attempts against one identity, so it has to be **one** count. `AuthLimiter`
+  is async on every member and declares the policy it enforces; `defineAuth` refuses a limiter
+  that disagrees with the app's declaration.
+
+## The lockout across replicas
+
+`createAuthLimiter` 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:
+
+```ts
+defineAuth({
+  adapter,
+  rateLimit: { maxAttempts: 5, scope: 'shared' },  // the whole fleet's allowance
+  limiter: myLimiter,                              // whose policy says exactly the same
+});
+```
+
+`Auth.rateLimit` is what an operator reads as "what this deployment enforces", so `defineAuth`
+refuses any pairing that would make it a lie:
+
+| Declared | Limiter's own `policy` | Result |
+|---|---|---|
+| `scope: 'process'` (default) | anything, same numbers | boots; the lockout is per replica |
+| `scope: 'shared'` | `scope: 'shared'`, same numbers | boots; one count for the fleet |
+| `scope: 'shared'` | `scope: 'process'` | `X_AUTH_LIMITER_NOT_SHARED` |
+| `maxAttempts`/`windowMs`/`lockoutMs` | any of the three different | `X_AUTH_LIMITER_POLICY_MISMATCH` |
+
+### The third bucket: one tenant
+
+`account:<email>` and `ip:<addr>` were the only key shapes, so one tenant's misconfigured
+integration hammering login from 400 addresses was capped by neither — each IP bucket allowed its
+own quota, the account buckets protected individuals, and the shared limiter saturated behind
+them. `orgKey(orgId)` is the third shape, checked in `login()` once the address resolves to an org
+and still before the KDF runs.
+
+`rateLimit.orgMaxAttempts` is its own number, defaulting to `maxAttempts * 20`: a whole tenant
+sharing five attempts is a denial of service against that tenant. A success on one member's
+account clears the **account** window and deliberately not the tenant one — otherwise the traffic
+that proves the tenant is alive is also the traffic that resets its cap. Pass `orgLimiter` to
+`defineAuth` to share those counters across replicas; unlike `limiter`, it is not required under
+`scope: 'shared'`, because a tenant cap is a throughput ceiling and not a guessing allowance.
+
+## Service-to-service
+
+`verifyWorkloadToken` is the one function, and it reads all three shapes because they are all the
+same JWT: a Kubernetes projected service-account token, a SPIFFE JWT-SVID, and a cloud IMDS token.
+It is also the shape RFC 8693's `subject_token` takes.
+
+```ts
+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' }),
+  clock,
+});
+const actor = actorFromService(identity);   // kind: 'service', id: the caller's own sub
+```
+
+Signature first, then issuer, audience, `exp` and `nbf`. `scope` (space-delimited) or `scp` (an
+array) become the actor's scopes; a token with neither carries none. There is no trusted-channel
+exemption here — the token arrived in a header.
+
+**mTLS is out of scope.** TLS termination is the mesh's job ([axiom
+7](../../docs/idea/README.md)); the framework's part is reading a trusted
+`x-forwarded-client-cert` through `@ultimat3/http`'s trusted-proxy seam, which that package owns.
+
+`maxKeys` is not compared — it bounds one process' table, not a limit. A custom limiter therefore
+does **not** own its own configuration: the policy stays the app's single statement of the limits,
+and the boot check is what keeps it true. **No shared limiter ships yet, `As of 2026-08`** —
+`createAuthLimiter` is the only implementation in the framework.
+
+## Providers are a registry, not a union
+
+`OAuthProviderId` is `string`, and `registerOAuthProvider()` is the one way a provider gets in —
+the three built-ins go through the same call. Before 1.3.0 the id was `keyof typeof
+OAUTH_PROVIDERS` over `github | google | apple`, so an enterprise OP was **unrepresentable**: the
+constraint was a type, there was no runtime escape, and the only ways out were forking the package
+or bypassing OAuth entirely and losing PKCE, the sealed handshake, issuer pinning and account
+linking with it.
+
+```ts
+import { discoverOAuthProvider, registerOAuthProvider } from '@ultimat3/auth';
+
+// By hand, when you know the four endpoints:
+registerOAuthProvider({
+  id: 'bigco-sso',
+  authorizeUrl: 'https://sso.bigco.test/oauth2/v1/authorize',
+  tokenUrl: 'https://sso.bigco.test/oauth2/v1/token',
+  userInfoUrl: 'https://sso.bigco.test/oauth2/v1/userinfo',
+  userEmailsUrl: null,
+  issuers: ['https://sso.bigco.test'],
+  jwksUri: 'https://sso.bigco.test/oauth2/v1/keys',
+  scopes: ['openid', 'email', 'profile'],
+  usesPkce: true,          // the literal `true`; `false` does not typecheck, for anyone
+  usesNonce: true,
+  clientIdEnv: 'BIGCO_SSO_CLIENT_ID',
+  clientSecretEnv: 'BIGCO_SSO_CLIENT_SECRET',
+});
+
+// Or read them once at boot, from the issuer's own discovery document:
+registerOAuthProvider(await discoverOAuthProvider({ id: 'bigco-sso', issuer: 'https://sso.bigco.test' }));
+```
+
+| Call | Answers |
+|---|---|
+| `registerOAuthProvider(provider)` | the frozen provider; `X_OAUTH_PROVIDER_DUPLICATE` on a second claim of one id |
+| `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 |
+
+`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
+caller declares, not one a provider inherits by omission.
+
+**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.
+
+## Id token signatures
+
+`verifyIdToken({ keys })` is **required** to say where its trust comes from. There is no default,
+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 })` |
+
+```ts
+const keys = providerJwks(providerFor('bigco-sso'));
+const claims = await verifyIdToken({ provider: 'bigco-sso', idToken, clientId, nonce, clock, keys });
+```
+
+`crypto.subtle` covers RS256 and ES256, so this costs no dependency. `HS256` and `alg: none` are
+refused before a key is even looked up — a symmetric algorithm verified against a *public* key set
+is the classic algorithm-confusion forgery. Keys are cached by `kid` with a TTL and one unknown
+`kid` triggers exactly one refetch, so a rotation heals itself.
+
+Wire an unsolicited token — IdP-initiated login, `response_mode=form_post`, back-channel logout,
+token exchange — to anything that does **not** check the signature and an attacker posts a
+self-minted JWT with the right `iss`, your `aud`, a VP's `sub` and tomorrow's `exp`, and gets a
+session. That is account takeover with no credential, and it is what this exists to stop.
+
+## What an SSO user is allowed to do
+
+`oauthLogin(auth, { resolveGrants })`. **Omit it and a first-time SSO user is created with
+`roles: []` and `orgId: null`** — an actor every `can()` denies, and a tenant-scoped read that
+throws before the query is built. SSO "works" and the person can do nothing until somebody runs
+SQL, so the omission logs `auth.oauth.user_created_without_grants` rather than passing silently.
+
+```ts
+oauthLogin(auth, {
+  resolveGrants: async (profile) => {
+    const member = await directory.lookup(profile.email);
+    return { orgId: member.orgId, roles: member.groups.map(toRole), scopes: [] };
+  },
+});
+```
+
+It is a **seam and not a group-to-role table**: which IdP group means which role is business
+convention and business convention never ships ([axiom
+8](../../docs/idea/19-mechanism-not-convention.md)). What the framework owns is calling it on
+**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.
+
+## MFA — TOTP and recovery codes
+
+Pure functions over a secret and a clock. This package mints, checks and de-duplicates a code;
+**it persists nothing** — the secret, the recovery-code hashes and the spent steps are the app's
+rows, because `AuthAdapter` has no MFA member and adding one would break every third-party
+adapter.
+
+```ts
+import type { Auth } from '@ultimat3/auth';
+import { createTotpReplayGuard, enrolTotp, generateRecoveryCodes, verifyTotp } from '@ultimat3/auth';
+import { systemClock } from '@ultimat3/core';
+
+declare const auth: Auth;   // the `defineAuth` at the top — `enrolTotp` reads `auth.mfa.issuer`
+
+const enrolment = enrolTotp(auth, { account: 'ada@example.com' });   // issuer: auth.mfa.issuer
+// enrolment.uri  -> otpauth://…  the QR code
+// enrolment.secret -> base32, store it against the user
+
+const recovery = generateRecoveryCodes();   // { codes, hashes } — show `codes` ONCE, store `hashes`
+const guard = createTotpReplayGuard();
+
+export function secondFactorHolds(userId: string, secret: string, code: string): boolean {
+  const at = systemClock.now();
+  const { ok, step } = verifyTotp({ secret, code, at });
+  if (!ok || step === null || guard.isUsed(userId, step)) return false;
+  guard.remember(userId, step, at);
+  return true;
+}
+```
+
+| Call | Answers |
+|---|---|
+| `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 |
+| `generateRecoveryCodes(count = 10)` | `{ codes, hashes }`. `codes` is shown once and is never re-derivable |
+| `redeemRecoveryCode(code, hashes)` | the **remaining** hashes, or `null`. Persisting that array is what makes a code single-use |
+| `totpStep(at, stepSeconds?)` / `totpCode(secret, step, digits?)` | the RFC 6238 halves, for a test that has to mint a valid code |
+
+`TOTP_DIGITS` (6), `TOTP_STEP_SECONDS` (30) and `TOTP_DRIFT_STEPS` (±1 window) are exported so an
+app's own copy of the parameters cannot disagree with the verifier's.
+
+A step is remembered per **subject**, not globally: a code is valid for `drift` windows either
+side of now, so without the guard the same six digits log in twice inside a minute. `verifyTotp`
+answers `{ ok: false, step }` — the step still named — when `usedSteps` already holds it, which is
+how a replay is told apart from a wrong code.
+
+The guard's table is **bounded** (`DEFAULT_MAX_TOTP_SUBJECTS`, 10,000), because a per-subject map
+that only ever grows is one process' lifetime away from an OOM. A subject whose every remembered
+step has fallen below the drift floor is *forgotten* — `verifyTotp` can never offer that step
+again, so the entry answers exactly as a missing one — and only if that is not enough does the cap
+evict live state, furthest from the live window first. The order is the guarantee: evicting a
+subject makes a step they have already spent replayable, so the subject who just authenticated is
+always the last one out.
+
+**`mfa.required` is accepted only as `false`, and that is deliberate.** The field exists and is
+typed as the literal `false`, so `required: true` is a compile error; a `true` that reaches
+`defineAuth` from JavaScript or from JSON — where the type cannot — is refused at boot with
+`X_CONFIG_INVALID` naming the key, never an unknown-key error and never a silent accept. Nothing
+read it: both credential paths branch on `user.mfaSecret` alone, so an un-enrolled user was handed
+a full session under a config that read as "this deployment requires a second factor". Enforcing it
+at `login()` instead is a lockout — `actorFromUser` degrades only a user who HAS a secret, and this
+package ships no enrolment route to send the rest to. Gate it in your own sign-in handler —
+`if (user.mfaSecret === null)` send them to `enrolTotp` before you call `createSession`.
+
+**The second leg of login is the app's, `As of 2026-08`.** `login()` and `completeOAuthLogin()`
+throw `X_MFA_REQUIRED` before any session exists; finishing the flow is `verifyTotp` followed by
+`createSession({ mfaSatisfied: true })` in the app's own route. The framework ships no
+`POST /auth/mfa/verify`, deliberately — see [`CLAUDE.md`](CLAUDE.md) for the three things that
+would have to land together, and why fewer is worse than none.
+
+## Email verification and password reset
+
+One issue/consume pair, two purposes. The token is mailed and only its `sha256` is stored, and
+consuming it is a single conditional statement — the hash is an **argument to** the consume, never
+a comparison after one.
+
+```ts
+import {
+  consumeVerification,
+  issueVerification,
+  type MailSender,
+  MemoryAdapter,
+  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 issued = await issueVerification(runtime, {
+  purpose: 'password-reset',
+  identifier: 'ada@example.com',       // the address; also the store key
+  locale: 'en',
+  link: (token) => `https://acme.test/reset?token=${token}`,
+});
+
+const verification = await consumeVerification(runtime, {
+  purpose: 'password-reset',
+  identifier: 'ada@example.com',
+  token: issued.token,                 // in production this arrives off the link
+});
+```
+
+| Name | Is |
+|---|---|
+| `VERIFICATION_PURPOSES` | `['email-verify', 'password-reset']` — the whole set, and `VerificationPurpose` is derived from it |
+| `VERIFICATION_TEMPLATES` | purpose → **catalog key** (`auth.email-verify`, `auth.password-reset`), never copy: the body lives in the app's i18n catalog |
+| `DEFAULT_VERIFICATION_TTL_MS` | 24 h for `email-verify`, 1 h for `password-reset` — a reset link is a password |
+| `MailSender` | the injected port: `send(template, to, data, locale)`. `@ultimat3/mail` is tier 4 and this package is tier 2, so the app wires it |
+| `issueVerification(runtime, input)` | `{ token, expiresAt }`. The token comes back for a test or a CLI; production only ever mails it |
+| `consumeVerification(runtime, input)` | the `AuthVerification` row, or `X_UNAUTHENTICATED`. Unknown, spent, expired and mismatched are one answer |
+
+One live token per `(purpose, identifier)`. A wrong guess destroys nothing: the store's
+`takeVerification(purpose, identifier, tokenHash)` matches before it consumes, so an
+unauthenticated POST with any token cannot kill the victim's live link.
+
+## Revocation, offboarding and access review
+
+| Call | Blast radius |
+|---|---|
+| `revokeSession(runtime, id)` | one session |
+| `revokeOtherSessions(runtime, userId, keep)` | every session but the caller's |
+| `revokeUserSessions(auth, userId, reason)` | one person, their current session included |
+| `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` **and** kills the sessions |
+| `listOrgUsers(auth, orgId, { role })` | the quarterly access review, as safe summaries |
+| `updatePrivileges(auth, userId, patch, session?)` | the grant, plus the session rotation it requires |
+
+`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.
+
+`deleteSessionsForOrg` joins through `x_users` and `x_sessions` deliberately does **not** gain an
+`org_id`: a denormalised copy of the membership goes stale the moment somebody moves org, and a
+stale row means the sweep leaves live exactly the sessions it was run to kill.
+
+`describeUser` is an allow-list, never a delete-list — a column added to `AuthUser` later must not
+appear in an admin response by default. No password hash, no TOTP secret, no recovery-code hash.
 
 ## Adapter seam
 
@@ -38,9 +360,46 @@ an adapter implementation, not a dependency of this package.
 | `MemoryAdapter` | `x new` before a database exists, and every test in this package |
 | your own | implement `AuthAdapter`; DDL in `tables.ts` shows what the columns mean |
 
-```bash
-x db gen "auth tables"     # emits AUTH_TABLES into a migration
-```
+**An adapter stores and matches the address it is handed — it never folds case.** `x_users.email`
+is a plain case-sensitive `text ... unique`, so an adapter that lowercased found accounts Postgres
+would not. Normalisation happens once, above the seam, in `normaliseEmail` (`email.ts`): trim and
+lowercase, nothing else. Call it before `findUserByEmail`/`createUser` in any login route of your
+own, and key any bucket of your own with it — `accountKey` does.
+
+The seam's newer members — `findUserByExternalId`, `listUsersByOrg`, `deleteSessionsForUser`,
+`deleteSessionsForOrg`, `deleteSessionsCreatedBefore` — are **optional**, so a 1.2-era adapter
+still satisfies the interface. Calling one an adapter has not implemented is `X_NOT_IMPLEMENTED`
+with the method named, not a silent no-op.
+
+`x_users` gained two columns in 1.3.0 — `scopes text[]` and `external_id text unique` — plus an
+`org_id` index. `X_USERS_MIGRATION_1_3` is those statements for an app already on 1.2; both
+columns are additive with a default, so the migration takes no table rewrite.
+
+**Nothing wires those statements into a migration for you, `As of 2026-08`.** `AUTH_TABLES` is the
+DDL as plain strings (`AUTH_TABLE_NAMES` is what they create, and `X_USERS_TABLE`,
+`X_SESSIONS_TABLE`, `X_ACCOUNTS_TABLE`, `X_API_KEYS_TABLE`, `X_VERIFICATIONS_TABLE` are the
+individual ones). `x db gen <name>` diffs `describeEntities()` against the newest migration's
+snapshot — these tables are not `entity()` declarations, so nothing outside `tables.ts` reads the
+constant and the command cannot see them. Paste each statement into its own file under
+`packages/db/migrations/`, one statement per migration, then `x db migrate`.
+
+## Sessions are not a write path
+
+`verifySession` used to `UPDATE x_sessions … RETURNING *` on **every** authenticated request: one
+request was a SELECT, a write and a second SELECT before the app's own first query. At 20k rps
+that is 20k writes a second on one hot table, autovacuum falls behind, and the incident reads as
+"the database is slow".
+
+`SessionPolicy.idleSlideMs` — defaulting to `idleTtlMs / 20` — is how far `lastSeenAt` may drift
+before a request writes it forward. A second request inside that window issues no write at all. A
+changed IP or user agent is still written immediately, because that is the row a device list and
+an incident review read. The trade is bounded and explicit: idle expiry is now precise to within
+one `idleSlideMs`.
+
+**Revocation is unaffected, and deliberately so.** `authenticate` re-reads the *user* row on every
+request, so a revoked role takes effect on the very next one with no token-expiry lag — a better
+property than any claims-in-a-JWT design. Throttling the session write is safe; caching the user
+row would not be, and nothing does.
 
 ## Cookie
 
@@ -54,38 +413,78 @@ x db gen "auth tables"     # emits AUTH_TABLES into a migration
 | `__Host-` + `Path=/` + no `Domain` | a sibling subdomain overwriting it (session fixation) |
 | `Max-Age` | a client keeping it past the server's absolute ceiling |
 
-## OAuth
+## OAuth — log in with GitHub
 
-Two calls: one to leave, one to come back. Provider configs are pure data — importing
-`oauth.ts` performs no network I/O and reads no env.
+`oauthLogin(auth)` **is** the flow. Two route descriptors, mounted at two fixed paths, composing
+`beginOAuth`, the handshake cookie and `completeOAuthLogin`. Provider configs stay pure data —
+importing `oauth.ts` performs no network I/O and reads no env.
 
 ```ts
-// GET /auth/oauth/:provider — redirect, keeping nothing on the server
-export async function GET(request: Request): Promise<Response> {
-  const handshake = beginOAuth({ provider: 'github', clientId, redirectUri });
-  return new Response(null, {
-    status: 302,
-    headers: { location: handshake.authorizeUrl, 'set-cookie': handshakeCookie(handshake) },
-  });
-}
+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 });
+  },
+});
 ```
 
+| | `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 |
+| failure | the coded JSON body, status per code | the same, handshake cleared either way |
+
+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.
+
+**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.
+
+**Failure is JSON, not a redirect carrying `?error=`.** The callback is the one request whose
+failure a developer must read, and there is no `?next=` on the success hop either: an
+attacker-supplied return target on the endpoint that hands out a session is the classic open
+redirect, and `nextAfterSignIn` in `@ultimat3/http` is the one implementation of that check.
+
+`beginOAuth` / `handshakeCookie` / `completeOAuthLogin` stay exported for a flow that needs the
+seams — but they are the seams, not the path.
+
+### Account linking
+
 ```ts
-// GET /auth/oauth/:provider/callback — a separate request; the cookie is all that crossed
-export async function GET(request: Request): Promise<Response> {
-  const url = new URL(request.url);
-  const { cookie } = await completeOAuthLogin(auth, {
-    handshake: readHandshakeCookie(request, 'github'),
-    callback: { state: url.searchParams.get('state') ?? '', code: url.searchParams.get('code') ?? '' },
-  });
-  const headers = new Headers({ location: '/' });
-  // Both, always: a code is single-use, so the handshake that authorised it must not outlive it.
-  headers.append('set-cookie', cookie);
-  headers.append('set-cookie', clearHandshakeCookie('github'));
-  return new Response(null, { status: 302, headers });
-}
+defineAuth({ adapter, providers: ['github'], link: 'verified-email' })  // the default
 ```
 
+| `link` | a provider identity becomes an **existing** user when |
+|---|---|
+| `'verified-email'` (default) | the provider asserted the address verified **and** that account had verified it too |
+| `'never'` | never — a collision is `X_UNAUTHENTICATED` and the caller uses their own credentials |
+
+There is deliberately **no third value**. "Link on whatever address the provider sent" is not
+spelled here at all: a provider that does not verify addresses turns it into account takeover —
+register the victim's address there, press the button, inherit the account. Unrepresentable beats
+explicit, the same way `PkcePair.method` is the literal `'S256'` and never `'plain'`. An app that
+truly wants something looser wraps `signInWithOAuth` and resolves the user itself.
+
 The handshake carries `state`, `nonce` and the PKCE verifier across two requests, so it needs a
 home. `handshakeCookie` is that home — sealed with `SESSION_SECRET`, `HttpOnly; Secure;
 SameSite=Lax` under a `__Host-` name, and expired against the server's clock rather than the
@@ -119,6 +518,7 @@ JWT signed with the `.p8` key, which Apple expires every six months.
 
 | Step | Does | Fails with |
 |---|---|---|
+| `oauthLogin(auth)` | the two routes: redirect out, session back | `X_OAUTH_PROVIDER_UNKNOWN`, `X_OAUTH_DENIED` |
 | `handshakeCookie` / `readHandshakeCookie` | seals the handshake onto the redirect, opens it on the callback | `X_OAUTH_STATE_INVALID`, `X_ENV_MISSING` |
 | `exchangeOAuthCode` | POSTs the code + PKCE verifier, verifies the id token | `X_OAUTH_EXCHANGE_FAILED`, `X_OAUTH_TOKEN_INVALID` |
 | `oauthProfile` | id-token claims, else userinfo → one normalised identity | `X_OAUTH_EXCHANGE_FAILED` |
@@ -130,8 +530,8 @@ JWT signed with the `.p8` key, which Apple expires every six months.
   token, because that is where the code flow actually carries it.
 - GitHub reports a bad, reused or expired code as **HTTP 200 with an `error` field**. Trusting
   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. Otherwise
-  whoever registered the address first inherits the login.
+- 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.
 
 ## API keys — how an agent authenticates
 
@@ -155,12 +555,15 @@ An api key's scopes become **exactly** the agent actor's scopes — never the ow
 | `X_MFA_REQUIRED` | password proven, second factor outstanding |
 | `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 issuer, audience or expiry check |
+| `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_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` | per-ip or per-account bucket is inside its lockout |
+| `X_ACCOUNT_LOCKED` | the per-ip, per-account or per-org bucket is inside its lockout |
 | `X_API_KEY_INVALID` | key unknown, revoked, expired or wrong |
 | `X_ENV_MISSING` | `oauthCredentials()` found no client id or secret for an enabled provider |
-| `X_NOT_IMPLEMENTED` | an `AuthAdapter` refused a method (`authNotImplemented(feature, fix)`), or lost a write it accepted — `emailVerifiedNotStored(provider, userId)` when `updateUser` drops the OAuth verified stamp |
+| `X_NOT_IMPLEMENTED` | an `AuthAdapter` has not implemented an optional seam member (`revokeOrgSessions`, `listOrgUsers`, …), or lost a write it accepted — `emailVerifiedNotStored(provider, userId)` when `updateUser` drops the OAuth verified stamp |
 
 ```bash
 bun test packages/auth

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "1.2.0",
+  "version": "3.0.0",
   "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,8 +31,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "1.2.0",
-    "@ultimat3/db": "1.2.0",
-    "@ultimat3/schema": "1.2.0"
+    "@ultimat3/core": "3.0.0",
+    "@ultimat3/db": "3.0.0",
+    "@ultimat3/schema": "3.0.0"
   }
 }