@ultimat3/auth 30.9.0 → 31.0.0

package/src/api-keys.ts

@@ -13,6 +13,13 @@ import { randomToken, sha256Hex } from './tokens';
 
 export const API_KEY_NAMESPACE = 'ult';
 
+/**
+ * `lastUsedAt` is a dashboard's "last used", not an audit trail: a verify writes it at most once
+ * per minute, so N requests a second on one key are N reads, not N row-locked UPDATEs. The same
+ * trade sessions make with `idleSlideMs`.
+ */
+export const API_KEY_TOUCH_MS = 60_000;
+
 /** `ult_<env>_<id>_<secret>` — the first three segments are the displayable prefix. */
 export const API_KEY_PREFIX_SEGMENTS = 3;
 
@@ -115,6 +122,9 @@ export async function verifyApiKey(
   if (parsed === null) throw apiKeyInvalid();
   const record = await store.findApiKeyById(parsed.id);
   if (record === null) throw apiKeyInvalid();
+  // The env label is part of what was issued: a `dev` key relabelled `ult_prod_…` is a forgery of
+  // the triage signal, refused like any other bad key.
+  if (parsed.prefix !== record.prefix) throw apiKeyInvalid();
   if (record.revokedAt !== null) throw apiKeyInvalid();
   const now = clock.now();
   if (record.expiresAt !== null && now.getTime() >= record.expiresAt.getTime()) {
@@ -125,7 +135,10 @@ export async function verifyApiKey(
   if (record.userId !== null && (owner === null || owner.disabledAt !== null)) {
     throw apiKeyInvalid();
   }
-  await store.touchApiKey(record.id, now);
+  const last = record.lastUsedAt;
+  if (last === null || now.getTime() - last.getTime() >= API_KEY_TOUCH_MS) {
+    await store.touchApiKey(record.id, now);
+  }
   return { record, owner };
 }
 

package/src/auth.ts

@@ -156,13 +156,13 @@ export interface AuthConfigInput {
   readonly mfa?: Partial<AuthMfaPolicy> | undefined;
   /**
    * Which TOTP steps have been spent, claimed by `completeMfa`. Omitted means the guard the host
-   * installed (`configureTotpReplay`; a framework boot's is `postgresTotpReplayGuard`), then
+   * installed (`installTotpReplay`; a framework boot's is `postgresTotpReplayGuard`), then
    * `memoryTotpReplayGuard()` — one process' worth of memory, so a code is single-use per replica.
    */
   readonly totpReplay?: TotpReplayGuard | undefined;
   /**
    * The OAuth providers this app serves login routes for. Defaults to `[]` — an empty list is
-   * "no OAuth", and every `/auth/oauth/<id>` answers `X_OAUTH_PROVIDER_UNKNOWN`. Never the live
+   * "no OAuth", and every `/auth/sso/<id>` answers `X_OAUTH_PROVIDER_UNKNOWN`. Never the live
    * registry, which a dependency can write into.
    */
   readonly providers?: readonly OAuthProviderId[] | undefined;
@@ -214,7 +214,7 @@ export function defineAuth(config: AuthConfigInput): Auth {
   assertPasswordPolicy(password);
   assertRateLimitPolicy(rateLimit);
   // Three answers in precedence order, and the middle one is why the seam exists: what this call
-  // passed, then what the HOST installed (`configureAuthLimiters`, filled by the boot that owns
+  // passed, then what the HOST installed (`installAuthLimiters`, filled by the boot that owns
   // the database connection), then one process' worth of state. Without the middle arm a
   // scaffolded app had to remember to build a shared limiter itself, which is the opposite of
   // what this framework promises — and `x new` scaffolds two replicas.

package/src/authorization-server-clients.ts

@@ -18,6 +18,11 @@ import { randomToken, sha256Hex } from './tokens';
 export const CLIENT_METADATA_MAX_BYTES = 5 * 1024;
 const CLIENT_METADATA_TTL_MS = 5 * 60 * 1000;
 const CLIENT_METADATA_CACHE_MAX = 1_000;
+/**
+ * One attempt: a document that failed is an unknown client NOW, and the person on the consent page
+ * is waiting. A retry would also multiply every metered fetch by the vendor's attempt count.
+ */
+const ONE_ATTEMPT = Object.freeze({ attempts: 1, base: 0, max: 0, jitter: 'none' as const });
 const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
 
 /** https anywhere, http only on loopback (RFC 8252 §7.3), never a fragment (RFC 6749 §3.1.2). */
@@ -67,6 +72,18 @@ export interface ClientDirectory {
 
 export function clientDirectory(config: ResolvedAuthServerConfig): ClientDirectory {
   const cache = new Map<string, { client: AuthServerClient | null; untilMs: number }>();
+  /** Misses in flight, by client id: concurrent reads of one uncached document share one GET. */
+  const inflight = new Map<string, Promise<AuthServerClient | null>>();
+  function fetchShared(clientId: string, callerKey: string | undefined) {
+    const nowMs = config.clock.now().getTime();
+    const hit = cache.get(clientId);
+    if (hit !== undefined && hit.untilMs > nowMs) return Promise.resolve(hit.client);
+    const joined = inflight.get(clientId);
+    if (joined !== undefined) return joined;
+    const started = fetchDocument(clientId, callerKey).finally(() => inflight.delete(clientId));
+    inflight.set(clientId, started);
+    return started;
+  }
   async function fetchDocument(
     clientId: string,
     callerKey: string | undefined,
@@ -86,6 +103,7 @@ export function clientDirectory(config: ResolvedAuthServerConfig): ClientDirecto
           maxBytes: CLIENT_METADATA_MAX_BYTES,
           redirect: 'error',
           headers: { accept: 'application/json' },
+          retry: ONE_ATTEMPT,
         },
         { fetch: config.fetch, resolve: config.resolveHost },
       );
@@ -109,7 +127,7 @@ export function clientDirectory(config: ResolvedAuthServerConfig): ClientDirecto
   return {
     find: (clientId, callerKey) =>
       isMetadataClientId(clientId)
-        ? fetchDocument(clientId, callerKey)
+        ? fetchShared(clientId, callerKey)
         : config.store.getClient(clientId),
   };
 }

package/src/authorization-server-config.ts

@@ -3,8 +3,9 @@
 // naming it — at boot, never on the first token request a partner makes.
 
 import type { Clock } from '@ultimat3/core';
-import { renderCauseValue, systemClock } from '@ultimat3/core';
+import { liveClock, renderCauseValue } from '@ultimat3/core';
 import type { DialResolve, OutboundFetch } from '@ultimat3/core/outbound';
+import { installedAuthServerStore } from './authorization-server-installed';
 import type { AuthServerStore } from './authorization-server-store';
 import type { AuthServerGrant } from './authorization-server-types';
 import { DEVICE_GRANT } from './authorization-server-types';
@@ -40,7 +41,11 @@ export interface AuthServerEvent {
 export interface AuthorizationServerOptions {
   /** RFC 8414 issuer: https (http only on loopback), no query, no fragment. */
   readonly issuer: string;
-  readonly store: AuthServerStore;
+  /**
+   * Where clients, codes, grants and tokens live. Omitted: the `authServerStore` port — what
+   * `runtime.ts` installed, else Postgres over the app's pool (`installedAuthServerStore`).
+   */
+  readonly store?: AuthServerStore | undefined;
   /** The app's consent PAGE: the advertised `authorization_endpoint`. */
   readonly consentPath: string;
   readonly lifetimes: AuthServerLifetimes;
@@ -203,12 +208,16 @@ export function resolveAuthServerConfig(
       "authorizationServer({ grants, devicePath: '/oauth/device' })   # the app's verification page",
     );
   }
-  const clock = options.clock ?? systemClock;
+  const clock = options.clock ?? liveClock;
   return {
     issuer: options.issuer,
     basePath: url.pathname === '/' ? '' : url.pathname,
     origin: url.origin,
-    store: options.store,
+    // A getter, read per call: `runtime.ts` may import the module that builds this server BEFORE
+    // the boot installs `runtime.authServerStore`, and a captured default would ignore it.
+    get store(): AuthServerStore {
+      return options.store ?? installedAuthServerStore();
+    },
     consentPath: pagePath('consentPath', options.consentPath),
     devicePath:
       options.devicePath === undefined ? null : pagePath('devicePath', options.devicePath),

package/src/authorization-server-installed.ts

@@ -0,0 +1,34 @@
+// Single responsibility: the `authServerStore` port's slot — where `authorizationServer()` keeps its
+// clients, codes, grants and tokens when the app names no store. The boot installs `runtime.ts`'s;
+// with none installed it is the env default, `postgresAuthServerStore` over the app's pool.
+
+import { adapterSlot } from '@ultimat3/core/adapter';
+import { dbExecutor } from '@ultimat3/db';
+import { postgresAuthServerStore } from './authorization-server-postgres';
+import type { AuthServerStore } from './authorization-server-store';
+
+/** Core's one slot shape (`adapter-slot.ts`): installs stack, each release removes its own frame. */
+const stores = /* @__PURE__ */ adapterSlot<AuthServerStore | undefined>(() => undefined);
+
+/**
+ * The `authServerStore` port's installer — on `@ultimat3/auth/adapter` only: the boot calls it with
+ * `runtime.ts`'s `authServerStore`. Answers the release that removes THIS install and no other.
+ */
+export function installAuthServerStore(store: AuthServerStore): () => void {
+  return stores.install(store);
+}
+
+/**
+ * What a server declaring no `store` reads at EACH call — never captured, because `runtime.ts`
+ * may import the module that builds the server before the boot installs this port. Nothing installed: Postgres over the ambient
+ * pool, the store every app wrote by hand before 31.0.0 (`postgresAuthServerStore({ executor:
+ * dbExecutor() })`); building it dials nothing.
+ */
+export function installedAuthServerStore(): AuthServerStore {
+  return stores.current() ?? postgresAuthServerStore({ executor: dbExecutor() });
+}
+
+/** Test seam: every install dropped. On `./adapter`, beside the installer. */
+export function resetAuthServerStore(): void {
+  stores.reset();
+}

package/src/authorization-server-postgres.ts

@@ -137,6 +137,7 @@ export function postgresAuthServerStore(options: PostgresAuthServerStoreOptions)
         c.expiresAt,
       ]);
     },
+    getCode: (hash) => first(SQL.SQL_OAUTH_CODE_GET, [hash], toCode),
     async takeCode(hash, at) {
       const taken = await first(SQL.SQL_OAUTH_CODE_TAKE, [hash, at], toCode);
       if (taken !== null) return { code: { ...taken, usedAt: null }, fresh: true };
@@ -208,10 +209,11 @@ export function postgresAuthServerStore(options: PostgresAuthServerStoreOptions)
           : [hash, 'denied', null, null, at],
         toDevice,
       ),
-    async pollDevice(hash, at) {
+    async pollDevice(hash, clientId, at) {
       // Two polls racing may both read the old stamp: harmless, `consumeDevice` is the single use.
       const device = await first(SQL.SQL_OAUTH_DEVICE_GET, [hash], toDevice);
-      if (device !== null) await rows(SQL.SQL_OAUTH_DEVICE_POLLED, [hash, at]);
+      if (device === null || device.clientId !== clientId) return null;
+      await rows(SQL.SQL_OAUTH_DEVICE_POLLED, [hash, at]);
       return device;
     },
     async consumeDevice(hash) {

package/src/authorization-server-store.ts

@@ -26,6 +26,11 @@ export interface AuthServerStore {
   putClient(client: AuthServerClient): Promise<void>;
   getClient(clientId: string): Promise<AuthServerClient | null>;
   putCode(code: AuthCodeRecord): Promise<void>;
+  /**
+   * The code as stored, used or not, WITHOUT spending it: the grant checks client, PKCE and
+   * redirect on this read so a request that could not redeem the code never burns it.
+   */
+  getCode(codeHash: string): Promise<AuthCodeRecord | null>;
   /** Marks the code used at `at` in the step that reads it. `fresh: false` is a replay. */
   takeCode(
     codeHash: string,
@@ -53,8 +58,12 @@ export interface AuthServerStore {
     decision: DeviceDecision,
     at: Date,
   ): Promise<DeviceCodeRecord | null>;
-  /** Stamps `lastPolledAt = at` and answers the row as it was BEFORE the stamp. */
-  pollDevice(deviceCodeHash: string, at: Date): Promise<DeviceCodeRecord | null>;
+  /**
+   * The device code of `clientId`: stamps `lastPolledAt = at` and answers the row as it was BEFORE
+   * the stamp. Another client's poll is `null` and stamps nothing, so it cannot `slow_down` the
+   * device the code was issued to.
+   */
+  pollDevice(deviceCodeHash: string, clientId: string, at: Date): Promise<DeviceCodeRecord | null>;
   /** Approved → consumed. `false` when another poll took it first. */
   consumeDevice(deviceCodeHash: string, at: Date): Promise<boolean>;
   /**
@@ -90,6 +99,7 @@ export function memoryAuthServerStore(): AuthServerStore {
     async putCode(code) {
       codes.set(code.codeHash, code);
     },
+    getCode: async (hash) => codes.get(hash) ?? null,
     async takeCode(hash, at) {
       const code = codes.get(hash);
       if (code === undefined) return null;
@@ -153,9 +163,9 @@ export function memoryAuthServerStore(): AuthServerStore {
       devices.set(device.deviceCodeHash, decided);
       return decided;
     },
-    async pollDevice(hash, at) {
+    async pollDevice(hash, clientId, at) {
       const device = devices.get(hash);
-      if (device === undefined) return null;
+      if (device === undefined || device.clientId !== clientId) return null;
       devices.set(hash, { ...device, lastPolledAt: at });
       return device;
     },

package/src/authorization-server.ts

@@ -35,17 +35,26 @@ export interface AuthorizationServer {
   readonly routes: readonly AuthServerRoute[];
   /** The RFC 8414 document the metadata route serves. */
   readonly metadata: Readonly<Record<string, unknown>>;
-  /** The consent page's read of its own URL: what to show, or the refusal to show instead. */
-  readRequest(url: string | URL): Promise<ReadRequestResult>;
+  /**
+   * The consent page's read of its own URL: what to show, or the refusal to show instead.
+   * `callerKey` (the request's address) meters a metadata-document fetch per caller, as the token
+   * route does — a page load naming `https://<anyone>/<path>` is otherwise one outbound GET each.
+   */
+  readRequest(url: string | URL, options?: ReadRequestOptions): Promise<ReadRequestResult>;
   /** The consent action's approval: the redirect URL carrying `code`, `state` and `iss`. */
   approve(input: {
     readonly subject: string;
+    /** The deciding request's address, for the re-read's metadata fetch — see `readRequest`. */
+    readonly callerKey?: string | undefined;
     readonly request: AuthorizationRequest;
     /** What the person granted — the request's scopes or fewer. Defaults to all of them. */
     readonly scopes?: readonly string[] | undefined;
   }): Promise<string>;
   /** The redirect URL carrying `error=access_denied`. */
-  deny(input: { readonly request: AuthorizationRequest }): Promise<string>;
+  deny(input: {
+    readonly request: AuthorizationRequest;
+    readonly callerKey?: string | undefined;
+  }): Promise<string>;
   /** `key` is the caller's bucket for user-code guesses: their address or session id. */
   readDevice(input: { readonly userCode: string; readonly key: string }): Promise<DeviceReading>;
   approveDevice(input: {
@@ -68,6 +77,11 @@ export interface AuthorizationServer {
   purge(input: { readonly before: Date }): Promise<number>;
 }
 
+export interface ReadRequestOptions {
+  /** The caller's address: the limiter key for a metadata-document fetch. */
+  readonly callerKey?: string | undefined;
+}
+
 /** The request as the query a client would have sent — what `approve` screens a second time. */
 function requestParams(request: AuthorizationRequest): URLSearchParams {
   const params = new URLSearchParams({
@@ -86,14 +100,20 @@ function requestParams(request: AuthorizationRequest): URLSearchParams {
 export function authorizationServer(options: AuthorizationServerOptions): AuthorizationServer {
   const config = resolveAuthServerConfig(options);
   const directory = clientDirectory(config);
-  const read = async (params: URLSearchParams): Promise<ReadRequestResult> => {
+  const read = async (
+    params: URLSearchParams,
+    callerKey: string | undefined,
+  ): Promise<ReadRequestResult> => {
     const clientId = params.get('client_id');
-    const client = clientId === null ? null : await directory.find(clientId);
+    const client = clientId === null ? null : await directory.find(clientId, callerKey);
     return screenAuthorization(config, client, params);
   };
   /** The request handed back is re-screened against the store: a forged object proves nothing. */
-  const rescreen = async (request: AuthorizationRequest): Promise<AuthorizationRequest> => {
-    const again = await read(requestParams(request));
+  const rescreen = async (
+    request: AuthorizationRequest,
+    callerKey: string | undefined,
+  ): Promise<AuthorizationRequest> => {
+    const again = await read(requestParams(request), callerKey);
     if (!again.ok) throw consentInvalid(again.description);
     return again.request;
   };
@@ -105,10 +125,10 @@ export function authorizationServer(options: AuthorizationServerOptions): Author
     issuer: config.issuer,
     routes: authServerRoutes(config, directory),
     metadata: authServerMetadata(config),
-    readRequest: (url) => read(new URL(url).searchParams),
+    readRequest: (url, options) => read(new URL(url).searchParams, options?.callerKey),
     async approve(input) {
       const subject = subjectOf(input.subject);
-      const request = await rescreen(input.request);
+      const request = await rescreen(input.request, input.callerKey);
       const scopes = [...new Set(input.scopes ?? request.scopes)];
       if (scopes.length === 0 || !scopes.every((scope) => request.scopes.includes(scope))) {
         throw consentInvalid('the approved scopes are empty or not a subset of the requested ones');
@@ -146,7 +166,7 @@ export function authorizationServer(options: AuthorizationServerOptions): Author
       });
     },
     async deny(input) {
-      const request = await rescreen(input.request);
+      const request = await rescreen(input.request, input.callerKey);
       return redirectWith(request.redirectUri, {
         error: 'access_denied',
         iss: config.issuer,

package/src/client-scope.ts

@@ -47,7 +47,7 @@ function scopeKey(options: ClientScopeOptions): string {
       throw new AuthError({
         code: 'X_CONFIG_INVALID',
         cause: `clientScopeOf({ secret }) was passed a key shorter than the ${String(MIN_SECRET_LENGTH)} characters required, so the scope id would be keyed by a guessable secret`,
-        fix: 'omit secret so clientScopeOf reads SESSION_SECRET, or pass one generated with: openssl rand -hex 32',
+        fix: 'openssl rand -hex 32   # pass the output as clientScopeOf({ secret }), or omit secret to read SESSION_SECRET',
         meta: { option: 'secret', minLength: MIN_SECRET_LENGTH },
       });
     }

package/src/errors.ts

@@ -39,6 +39,9 @@ export const AUTH_OWNED_ERROR_CODES = [
   'X_PASSKEY_INVALID',
   'X_PASSKEY_CHALLENGE_EXPIRED',
   'X_PASSKEY_STEP_UP_REQUIRED',
+  'X_SAML_RESPONSE_INVALID',
+  'X_SAML_METADATA_INVALID',
+  'X_IDENTITY_PROVIDER_UNKNOWN',
 ] as const;
 
 /**
@@ -99,6 +102,11 @@ export const AUTH_ERROR_TITLES: Readonly<Record<AuthOwnedErrorCode, string>> = {
     'a passkey ceremony named a challenge that is unknown, already used or past its ttl',
   X_PASSKEY_STEP_UP_REQUIRED:
     'a sensitive action ran without a fresh user-verified passkey proof for its digest',
+  X_SAML_RESPONSE_INVALID:
+    'a saml response failed its signature, wrapping, audience, recipient, time, InResponseTo or replay check',
+  X_SAML_METADATA_INVALID:
+    'saml IdP metadata has no entity id, HTTP-Redirect sign-on endpoint or signing certificate',
+  X_IDENTITY_PROVIDER_UNKNOWN: 'the URL named an identity provider the sso routes were not given',
 };
 
 // Registered unconditionally, in one call: a second package claiming a code auth owns has to fail
@@ -182,7 +190,7 @@ export const kdfOverloaded = (active: number, queued: number): AuthError =>
   new AuthError({
     code: 'X_OVERLOADED',
     cause: `${active} password hashes are already running and ${queued} more are queued`,
-    fix: 'retry after the Retry-After header; widen the ceiling with configureKdfGate({ maxConcurrent, maxQueued }) only if the box has the memory — every argon2id hash holds ~19 MiB while it runs',
+    fix: 'retry after the Retry-After header; widen the ceiling with installKdfGate({ maxConcurrent, maxQueued }) from @ultimat3/auth/adapter, in apps/web/runtime.ts, only if the box has the memory — every argon2id hash holds ~19 MiB while it runs',
     meta: { active, queued, retryAfterSeconds: 1 },
   });
 

package/src/grant-authorization-code.ts

@@ -1,7 +1,7 @@
 // Single responsibility: the two person-grant legs of `POST /oauth/token` — a code for tokens
-// (RFC 6749 §4.1.3 + PKCE) and a refresh token for new ones (§6, OAuth 2.1 rotation). The rules:
-// a code is single use and its replay revokes what it minted; a retired refresh token's replay
-// revokes the whole grant; the redirect and the resource must be the ones the code was bound to.
+// (RFC 6749 §4.1.3 + PKCE) and a refresh token for new ones (§6, OAuth 2.1 rotation). A code is
+// spent only by a request that could redeem it, and its replay revokes what it minted; a retired
+// refresh token's replay revokes the whole grant.
 
 import type { ResolvedAuthServerConfig } from './authorization-server-config';
 import {
@@ -30,28 +30,33 @@ export async function exchangeCode(
     return refused('invalid_request', 'code and code_verifier are required');
   }
   const now = config.clock.now();
-  const taken = await config.store.takeCode(sha256Hex(code), now);
-  if (taken === null) return invalidGrant('the code is unknown');
-  const record = taken.code;
-  if (!taken.fresh) {
-    // Somebody holds a copy of a code that was already redeemed: whatever it minted is suspect.
-    await config.store.revokeGrant(record.grantId, now);
-    config.emit({ kind: 'code-replayed', clientId: record.clientId });
-    return invalidGrant('the code was already used; the grant it minted is revoked');
-  }
-  if (record.clientId !== client.clientId)
+  const hash = sha256Hex(code);
+  // Read, check, THEN spend: a request that could not have redeemed the code — another client, no
+  // verifier, another redirect — must neither burn it nor trip the replay revocation below.
+  const record = await config.store.getCode(hash);
+  if (record === null) return invalidGrant('the code is unknown');
+  if (record.clientId !== client.clientId) {
     return invalidGrant('the code was issued to another client');
-  if (record.expiresAt.getTime() <= now.getTime()) return invalidGrant('the code expired');
-  if (form.get('redirect_uri') !== record.redirectUri) {
-    return invalidGrant('redirect_uri is not the one the code was issued for');
   }
   if (!pkceMatches(verifier, record.codeChallenge)) {
     return invalidGrant('the code_verifier does not match the code_challenge');
   }
+  if (form.get('redirect_uri') !== record.redirectUri) {
+    return invalidGrant('redirect_uri is not the one the code was issued for');
+  }
   const resource = form.get('resource');
   if (resource !== undefined && resource !== record.resource) {
     return refused('invalid_target', 'the resource is not the one the grant is bound to');
   }
+  const taken = await config.store.takeCode(hash, now);
+  if (taken === null) return invalidGrant('the code is unknown');
+  if (!taken.fresh) {
+    // A second holder of the code AND its verifier: whatever it minted is suspect.
+    await config.store.revokeGrant(record.grantId, now);
+    config.emit({ kind: 'code-replayed', clientId: record.clientId });
+    return invalidGrant('the code was already used; the grant it minted is revoked');
+  }
+  if (record.expiresAt.getTime() <= now.getTime()) return invalidGrant('the code expired');
   const grant = await config.store.getGrant(record.grantId);
   if (grant === null || grant.revokedAt !== null) return invalidGrant('the grant is revoked');
   const refresh = await firstRefresh(config, grant.id);

package/src/grant-device.ts

@@ -154,8 +154,8 @@ export async function pollDevice(
   if (deviceCode === undefined) return refused('invalid_request', 'device_code is required');
   const now = config.clock.now();
   const hash = sha256Hex(deviceCode);
-  const device = await config.store.pollDevice(hash, now);
-  if (device === null || device.clientId !== client.clientId) {
+  const device = await config.store.pollDevice(hash, client.clientId, now);
+  if (device === null) {
     return refused('invalid_grant', 'the device code is unknown');
   }
   if (device.expiresAt.getTime() <= now.getTime()) {

package/src/identity-provider-cookie.ts

@@ -0,0 +1,89 @@
+// Single responsibility: where an `IdentityRedirect.state` lives between the two legs — HMAC-
+// signed with `SESSION_SECRET`, bound to its provider, aged on the server's clock, one cookie per
+// provider. SAML answers with a cross-site POST no `SameSite=Lax` cookie rides, so a POST-callback
+// provider's cookie is `SameSite=None`; `Secure` and `__Host-` keep it off every other site.
+
+import { type Clock, hmac, readCookie, serializeSetCookie, timingSafeEqual } from '@ultimat3/core';
+import type { IdentityProvider } from './identity-provider';
+import { DEFAULT_HANDSHAKE_TTL_MS, handshakeSecret } from './oauth-cookie';
+import { oauthStateInvalid } from './oauth-errors';
+import { base64Url, base64UrlBytes } from './tokens';
+
+export const IDENTITY_STATE_COOKIE_PREFIX = '__Host-x_sso';
+
+export const identityStateCookieName = (provider: string): string =>
+  `${IDENTITY_STATE_COOKIE_PREFIX}_${provider}`;
+
+export interface IdentityStateOptions {
+  readonly clock: Clock;
+  /** Defaults to `SESSION_SECRET`. */
+  readonly secret?: string | undefined;
+}
+
+const sign = (body: string, secret: string): string => hmac('sha256', secret, body, 'hex');
+
+export function identityStateCookie(
+  provider: IdentityProvider,
+  state: string,
+  options: IdentityStateOptions,
+): string {
+  const body = base64Url(
+    new TextEncoder().encode(JSON.stringify([provider.id, state, options.clock.now().getTime()])),
+  );
+  const sealed = `${body}.${sign(body, options.secret ?? handshakeSecret())}`;
+  return serializeSetCookie(identityStateCookieName(provider.id), sealed, {
+    maxAge: Math.floor(DEFAULT_HANDSHAKE_TTL_MS / 1000),
+    sameSite: provider.callbackMethod === 'POST' ? 'None' : 'Lax',
+  });
+}
+
+/**
+ * Sent with every callback answer: the state it carried is spent whatever the outcome. Takes the id
+ * and method rather than a provider, so a refusal before the provider resolved can still clear it.
+ */
+export const clearIdentityStateCookie = (
+  id: string,
+  callbackMethod: IdentityProvider['callbackMethod'],
+): string =>
+  serializeSetCookie(identityStateCookieName(id), '', {
+    maxAge: 0,
+    sameSite: callbackMethod === 'POST' ? 'None' : 'Lax',
+  });
+
+/** The state `begin` returned, or `X_OAUTH_STATE_INVALID` — one refusal for every way it fails. */
+export function readIdentityState(
+  request: Request,
+  provider: IdentityProvider,
+  options: IdentityStateOptions,
+): string {
+  const sealed = readCookie(request.headers.get('cookie'), identityStateCookieName(provider.id));
+  if (sealed === null) throw oauthStateInvalid(provider.id, 'no sign-in state cookie arrived');
+  const dot = sealed.lastIndexOf('.');
+  const body = sealed.slice(0, Math.max(dot, 0));
+  if (
+    dot <= 0 ||
+    !timingSafeEqual(sign(body, options.secret ?? handshakeSecret()), sealed.slice(dot + 1))
+  ) {
+    throw oauthStateInvalid(
+      provider.id,
+      'the sign-in state was tampered with, or the secret rotated',
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(base64UrlBytes(body) ?? new Uint8Array()));
+  } catch {
+    parsed = null;
+  }
+  if (!Array.isArray(parsed) || parsed.length !== 3) {
+    throw oauthStateInvalid(provider.id, 'the sign-in state is not readable');
+  }
+  const [id, state, issuedAt] = parsed as readonly unknown[];
+  if (id !== provider.id || typeof state !== 'string' || typeof issuedAt !== 'number') {
+    throw oauthStateInvalid(provider.id, 'the sign-in state belongs to another provider');
+  }
+  if (options.clock.now().getTime() - issuedAt > DEFAULT_HANDSHAKE_TTL_MS) {
+    throw oauthStateInvalid(provider.id, 'the sign-in state expired before the IdP answered');
+  }
+  return state;
+}