@ultimat3/auth 29.3.2 → 30.0.0

package/src/api-key-resolver.ts

@@ -32,9 +32,9 @@ 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 `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.
+ * its module is evaluated, and which store serves (memory or Postgres) is often decided at boot.
+ * `() => memoryAuthAdapter()` would be a new, empty store per request — hold the instance and
+ * return it.
  */
 export function apiKeyResolver(
   store: () => ApiKeyVerifyStore,

package/src/auth.ts

@@ -7,13 +7,18 @@ 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 { mfaRequiredUnenforceable, sessionUnknown, totpReplayGuardInvalid } from './errors';
+import { installedAuthLimiter, installedTotpReplay } from './limiter-install';
 import { openLoginAttempt } from './login-attempt';
 import { type HandleDirectory, loginIdentity } from './login-identity';
 import { memoryTotpReplayGuard, type TotpReplayGuard } from './mfa';
 import { mfaChallengeRequired } from './mfa-challenge';
 import type { OAuthProviderId } from './oauth';
+import {
+  type PasskeyPolicy,
+  type PasskeyPolicyInput,
+  resolvePasskeyPolicy,
+} from './passkey-config';
 import {
   checkPasswordStrength,
   DEFAULT_PASSWORD_POLICY,
@@ -82,7 +87,8 @@ export const AccountSchema = t.object({
 
 export const VerificationSchema = t.object({
   id: t.string,
-  purpose: t.enum(['email-verify', 'password-reset']),
+  // Open: any `defineVerificationPurpose` name, so a declared invite row parses as its own data.
+  purpose: t.string,
   identifier: t.email,
   expiresAt: t.date,
   consumedAt: t.optional(t.date),
@@ -149,9 +155,9 @@ export interface AuthConfigInput {
   readonly orgLimiter?: AuthLimiter | undefined;
   readonly mfa?: Partial<AuthMfaPolicy> | undefined;
   /**
-   * Which TOTP steps have been spent, read and written by `completeMfa`. Omitted means
-   * `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.
+   * Which TOTP steps have been spent, claimed by `completeMfa`. Omitted means the guard the host
+   * installed (`configureTotpReplay`; 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;
   /**
@@ -169,6 +175,13 @@ export interface AuthConfigInput {
    * by id — `register(auth, { id })` creates the auth user under the app's id.
    */
   readonly handles?: HandleDirectory | undefined;
+  /**
+   * The relying party passkeys are verified against: `{ rpId: 'example.com', origins:
+   * ['https://example.com'] }`. Absent means no passkeys — `passkeyLogin(auth)` and
+   * `passkeyStepUp(auth)` refuse at definition (`X_CONFIG_INVALID`), as does a block whose
+   * origins are not on its rp id.
+   */
+  readonly passkeys?: PasskeyPolicyInput | undefined;
 }
 
 export interface Auth {
@@ -186,6 +199,7 @@ export interface Auth {
   readonly providers: readonly OAuthProviderId[];
   readonly link: OAuthLinkPolicy;
   readonly handles?: HandleDirectory | undefined;
+  readonly passkeys?: PasskeyPolicy | undefined;
 }
 
 export function defineAuth(config: AuthConfigInput): Auth {
@@ -228,6 +242,13 @@ export function defineAuth(config: AuthConfigInput): Auth {
   const declaredMfa: { readonly required?: unknown } = config.mfa ?? {};
   if (declaredMfa.required === true) throw mfaRequiredUnenforceable();
   const mfa: AuthMfaPolicy = { issuer: config.mfa?.issuer ?? DEFAULT_MFA_ISSUER, required: false };
+  const totpReplay = config.totpReplay ?? installedTotpReplay() ?? memoryTotpReplayGuard();
+  // Unreachable from TypeScript and reachable from a guard written before `claim`, which would
+  // otherwise be found at the first second factor, as a TypeError, on a production sign-in.
+  const declaredReplay: { readonly claim?: unknown } = totpReplay;
+  if (typeof declaredReplay.claim !== 'function') throw totpReplayGuardInvalid();
+  const passkeys =
+    config.passkeys === undefined ? undefined : resolvePasskeyPolicy(config.passkeys);
   return Object.freeze({
     adapter: config.adapter,
     clock,
@@ -240,7 +261,7 @@ export function defineAuth(config: AuthConfigInput): Auth {
     orgRateLimit: orgLimiter.policy,
     orgLimiter,
     mfa,
-    totpReplay: config.totpReplay ?? memoryTotpReplayGuard(),
+    totpReplay,
     // BREAKING (majors only): the default is `[]`, never the live registry.
     //
     // It was `oauthProviderIds()`, so `defineAuth({ providers })`'s own documented purpose — the
@@ -254,6 +275,7 @@ export function defineAuth(config: AuthConfigInput): Auth {
     providers: config.providers ?? [],
     link: config.link ?? 'verified-email',
     ...(config.handles === undefined ? {} : { handles: config.handles }),
+    ...(passkeys === undefined ? {} : { passkeys }),
   });
 }
 

package/src/authorization-server-clients.ts

@@ -0,0 +1,169 @@
+// Single responsibility: who a `client_id` is — a registered client from the store, or an https
+// URL whose metadata document (MCP 2025-11-25) is fetched via `outbound({ dial: 'public' })`,
+// size-capped, metered per caller, cached oldest-first — and proving a confidential one's secret.
+// The secret is hashed at rest and compared hash to hash in constant time, never with `===`.
+
+import { logger, stringField, timingSafeEqual } from '@ultimat3/core';
+import { outbound } from '@ultimat3/core/outbound';
+import type { ResolvedAuthServerConfig } from './authorization-server-config';
+import type {
+  AuthServerClient,
+  AuthServerGrant,
+  ClientAuthMethod,
+} from './authorization-server-types';
+import { isRecord } from './json';
+import { randomToken, sha256Hex } from './tokens';
+
+/** A metadata document is a few hundred bytes; 5 KiB is RFC 7591 metadata with room to spare. */
+export const CLIENT_METADATA_MAX_BYTES = 5 * 1024;
+const CLIENT_METADATA_TTL_MS = 5 * 60 * 1000;
+const CLIENT_METADATA_CACHE_MAX = 1_000;
+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). */
+export function isRedirectUri(value: string): boolean {
+  const url = URL.parse(value);
+  if (url === null || url.hash !== '' || value.includes('#')) return false;
+  return url.protocol === 'https:' || (url.protocol === 'http:' && LOOPBACK.has(url.hostname));
+}
+
+const isMetadataClientId = (clientId: string): boolean => {
+  const url = URL.parse(clientId);
+  return url !== null && url.protocol === 'https:' && url.pathname !== '/' && url.hash === '';
+};
+
+const strings = (value: unknown): readonly string[] | null =>
+  Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : null;
+
+/** The document, read as a public client or not at all. A secret in it would be published. */
+function clientFromDocument(clientId: string, body: unknown, at: Date): AuthServerClient | null {
+  if (!isRecord(body) || body['client_id'] !== clientId) return null;
+  const redirects = strings(body['redirect_uris']);
+  if (redirects === null || redirects.length === 0 || !redirects.every(isRedirectUri)) return null;
+  const method = body['token_endpoint_auth_method'];
+  if (method !== undefined && method !== 'none') return null;
+  const name = body['client_name'];
+  return {
+    clientId,
+    name: typeof name === 'string' && name !== '' ? name : new URL(clientId).host,
+    secretHash: null,
+    authMethod: 'none',
+    redirectUris: redirects,
+    grantTypes: ['authorization_code', 'refresh_token'],
+    scopes: [],
+    resources: [],
+    createdAt: at,
+  };
+}
+
+export interface ClientDirectory {
+  /**
+   * `callerKey` (the caller's address) meters metadata fetches through `config.limiter`: an
+   * unauthenticated POST naming `https://<anyone>/<path>` would otherwise be one outbound GET per
+   * path. Rejects with `X_ACCOUNT_LOCKED` once the caller is over the limit.
+   */
+  find(clientId: string, callerKey?: string): Promise<AuthServerClient | null>;
+}
+
+export function clientDirectory(config: ResolvedAuthServerConfig): ClientDirectory {
+  const cache = new Map<string, { client: AuthServerClient | null; untilMs: number }>();
+  async function fetchDocument(
+    clientId: string,
+    callerKey: string | undefined,
+  ): Promise<AuthServerClient | null> {
+    const nowMs = config.clock.now().getTime();
+    const hit = cache.get(clientId);
+    if (hit !== undefined && hit.untilMs > nowMs) return hit.client;
+    if (callerKey !== undefined) await config.limiter.reserve(`oauth-client-metadata:${callerKey}`);
+    let client: AuthServerClient | null = null;
+    try {
+      const answer = await outbound(
+        {
+          url: clientId,
+          vendor: 'oauth-client-metadata',
+          dial: 'public',
+          deadlineMs: 5_000,
+          maxBytes: CLIENT_METADATA_MAX_BYTES,
+          redirect: 'error',
+          headers: { accept: 'application/json' },
+        },
+        { fetch: config.fetch, resolve: config.resolveHost },
+      );
+      client =
+        answer.status === 200
+          ? clientFromDocument(clientId, JSON.parse(answer.text()), config.clock.now())
+          : null;
+    } catch (error) {
+      // An unreachable, oversized or private-address document is an unknown client: the consent
+      // page shows the refusal and nothing redirects. The code, never the message — it names a host.
+      const code = stringField(error, 'code');
+      logger.warn('auth.server.client_metadata_unreadable', code === undefined ? {} : { code });
+    }
+    // Oldest first: a Map iterates in insertion order, so re-inserting keeps the order honest.
+    cache.delete(clientId);
+    const oldest = cache.keys().next();
+    if (cache.size >= CLIENT_METADATA_CACHE_MAX && oldest.done !== true) cache.delete(oldest.value);
+    cache.set(clientId, { client, untilMs: nowMs + CLIENT_METADATA_TTL_MS });
+    return client;
+  }
+  return {
+    find: (clientId, callerKey) =>
+      isMetadataClientId(clientId)
+        ? fetchDocument(clientId, callerKey)
+        : config.store.getClient(clientId),
+  };
+}
+
+export interface RegisterClientInput {
+  readonly name: string;
+  /** `'none'` (default) is public: PKCE only. A secret method is a confidential client. */
+  readonly authMethod?: ClientAuthMethod | undefined;
+  readonly redirectUris?: readonly string[] | undefined;
+  readonly grantTypes?: readonly AuthServerGrant[] | undefined;
+  readonly scopes?: readonly string[] | undefined;
+  readonly resources?: readonly string[] | undefined;
+}
+
+export interface RegisteredClient {
+  readonly client: AuthServerClient;
+  /** Shown ONCE, to whoever registered. Only its hash is stored. `null` for a public client. */
+  readonly clientSecret: string | null;
+}
+
+/** Screening is the caller's: the route answers RFC 7591 errors, the app's task trusts itself. */
+export async function storeClient(
+  config: ResolvedAuthServerConfig,
+  input: RegisterClientInput,
+): Promise<RegisteredClient> {
+  const method = input.authMethod ?? 'none';
+  const clientSecret = method === 'none' ? null : randomToken(32);
+  const client: AuthServerClient = {
+    clientId: `c_${randomToken(16)}`,
+    name: input.name,
+    secretHash: clientSecret === null ? null : sha256Hex(clientSecret),
+    authMethod: method,
+    redirectUris: [...(input.redirectUris ?? [])],
+    grantTypes: [...(input.grantTypes ?? ['authorization_code', 'refresh_token'])],
+    scopes: [...(input.scopes ?? [])],
+    resources: [...(input.resources ?? [])],
+    createdAt: config.clock.now(),
+  };
+  await config.store.putClient(client);
+  return { client, clientSecret };
+}
+
+/** What a token request presented about the client. */
+export interface ClientCredentials {
+  readonly clientId: string;
+  readonly secret: string | null;
+}
+
+/** A public client presents no secret; a confidential one must, and it must match. */
+export function clientAuthenticates(
+  client: AuthServerClient,
+  presented: ClientCredentials,
+): boolean {
+  if (client.secretHash === null) return presented.secret === null;
+  if (presented.secret === null) return false;
+  return timingSafeEqual(sha256Hex(presented.secret), client.secretHash);
+}

package/src/authorization-server-config.ts

@@ -0,0 +1,239 @@
+// Single responsibility: what `authorizationServer()` is configured with, screened once at
+// construction into the resolved form every grant reads. A bad field is `X_AUTH_SERVER_INVALID`
+// 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 type { DialResolve, OutboundFetch } from '@ultimat3/core/outbound';
+import type { AuthServerStore } from './authorization-server-store';
+import type { AuthServerGrant } from './authorization-server-types';
+import { DEVICE_GRANT } from './authorization-server-types';
+import { AuthError } from './errors';
+import { type AuthLimiter, memoryAuthLimiter } from './rate-limit';
+
+export interface AuthServerLifetimes {
+  /** Access-token life. Short: an access token is not revocable faster than a lookup. */
+  readonly accessSeconds: number;
+  /** A refresh token unused this long is dead. The app's retention window. */
+  readonly refreshIdleDays: number;
+  /** Required once `client_credentials` is enabled: a machine's token life. */
+  readonly clientSeconds?: number | undefined;
+  /** Device-code life. Defaults to 600, RFC 8628's own example. */
+  readonly deviceSeconds?: number | undefined;
+}
+
+/** One line per decision the server made — the wrapper turns these into `mcp.auth.*`. */
+export interface AuthServerEvent {
+  readonly kind:
+    | 'issued'
+    | 'refused'
+    | 'code-replayed'
+    | 'refresh-replayed'
+    | 'revoked'
+    | 'grant-disabled';
+  /** The RFC 6749 `error` the wire answered, on a refusal. */
+  readonly error?: string | undefined;
+  readonly clientId?: string | undefined;
+  readonly grantType?: string | undefined;
+}
+
+export interface AuthorizationServerOptions {
+  /** RFC 8414 issuer: https (http only on loopback), no query, no fragment. */
+  readonly issuer: string;
+  readonly store: AuthServerStore;
+  /** The app's consent PAGE: the advertised `authorization_endpoint`. */
+  readonly consentPath: string;
+  readonly lifetimes: AuthServerLifetimes;
+  /** Every scope this server may grant. A client and a person only ever narrow it. */
+  readonly scopes: readonly string[];
+  /**
+   * RFC 8707 resource indicators this server mints for. A request naming any other is
+   * `invalid_target`; one naming none gets an unbound grant, which a binding resolver refuses.
+   */
+  readonly resources?: readonly string[] | undefined;
+  /** The resource a request naming none is bound to. Must be one of `resources`. */
+  readonly defaultResource?: string | undefined;
+  /** `'metadata-document'` (default): https client ids are fetched. `'dynamic'` adds RFC 7591. */
+  readonly registration?: 'metadata-document' | 'dynamic' | undefined;
+  /** Defaults to `['authorization_code', 'refresh_token']`. Each further grant is named. */
+  readonly grants?: readonly AuthServerGrant[] | undefined;
+  /** The app's device verification PAGE. Required once the device grant is enabled. */
+  readonly devicePath?: string | undefined;
+  readonly clock?: Clock | undefined;
+  /** Counts registrations and user-code guesses per caller key. Defaults to per-process memory. */
+  readonly limiter?: AuthLimiter | undefined;
+  /** How metadata documents are fetched — injected by a test; production dials the internet. */
+  readonly fetch?: OutboundFetch | undefined;
+  readonly resolveHost?: DialResolve | undefined;
+  readonly onEvent?: ((event: AuthServerEvent) => void) | undefined;
+}
+
+export interface ResolvedAuthServerConfig {
+  readonly issuer: string;
+  /** The issuer's path, `''` at the root: every endpoint mounts under it. */
+  readonly basePath: string;
+  readonly origin: string;
+  readonly store: AuthServerStore;
+  readonly consentPath: string;
+  readonly devicePath: string | null;
+  readonly accessSeconds: number;
+  readonly refreshIdleMs: number;
+  readonly clientSeconds: number | null;
+  readonly deviceSeconds: number;
+  readonly scopes: ReadonlySet<string>;
+  readonly resources: ReadonlySet<string>;
+  readonly defaultResource: string | null;
+  readonly dynamic: boolean;
+  readonly grants: ReadonlySet<AuthServerGrant>;
+  readonly clock: Clock;
+  readonly limiter: AuthLimiter;
+  readonly fetch: OutboundFetch | undefined;
+  readonly resolveHost: DialResolve | undefined;
+  readonly emit: (event: AuthServerEvent) => void;
+}
+
+const KNOWN_GRANTS: ReadonlySet<string> = new Set<AuthServerGrant>([
+  'authorization_code',
+  'refresh_token',
+  'client_credentials',
+  DEVICE_GRANT,
+]);
+
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
+const PAGE_PATH = /^\/[A-Za-z0-9\-._~/]*$/;
+/** RFC 6749 §3.3 scope-token. */
+export const SCOPE_TOKEN = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const invalid = (field: string, why: string, fix: string): AuthError =>
+  new AuthError({
+    code: 'X_AUTH_SERVER_INVALID',
+    cause: `authorizationServer({ ${field} }) ${why}`,
+    fix,
+    meta: { field },
+  });
+
+/** A lifetime: a whole number of at least 1, so `NaN` and `Infinity` are refused, never stored. */
+const lifetimeSeconds = (field: string, value: number | undefined): number => {
+  if (value !== undefined && Number.isSafeInteger(value) && value >= 1) return value;
+  throw invalid(
+    field,
+    `is ${renderCauseValue(value)}, not a whole number of at least 1`,
+    `authorizationServer({ lifetimes: { ${field.replace('lifetimes.', '')}: 600 } })   # a positive whole number`,
+  );
+};
+
+const pagePath = (field: string, value: string): string => {
+  if (PAGE_PATH.test(value) && !value.includes('//')) return value;
+  throw invalid(
+    field,
+    `is ${renderCauseValue(value)}, not an absolute path on the issuer's origin`,
+    `authorizationServer({ ${field}: '/oauth/consent' })   # the path of the app's own page`,
+  );
+};
+
+function issuerUrl(value: string): URL {
+  const url = URL.parse(value);
+  const secure =
+    url !== null &&
+    (url.protocol === 'https:' || (url.protocol === 'http:' && LOOPBACK.has(url.hostname)));
+  if (url !== null && secure && url.search === '' && url.hash === '' && !value.endsWith('/')) {
+    return url;
+  }
+  throw invalid(
+    'issuer',
+    `is ${renderCauseValue(value)}; RFC 8414 needs https (http only on loopback), no query, no fragment, no trailing slash`,
+    "authorizationServer({ issuer: 'https://www.example.com' })   # the app's public origin",
+  );
+}
+
+/** RFC 8707 §2: an absolute URI with no fragment. */
+function resourceIndicator(value: string): string {
+  const url = URL.parse(value);
+  if (url !== null && url.hash === '' && !value.includes('#')) return value;
+  throw invalid(
+    'resources',
+    `holds ${renderCauseValue(value)}, not an absolute URI without a fragment`,
+    "authorizationServer({ resources: ['https://www.example.com/mcp'] })   # canonical URLs, no fragment",
+  );
+}
+
+function defaultResourceOf(options: AuthorizationServerOptions): string | null {
+  const fallback = options.defaultResource;
+  if (fallback === undefined) return null;
+  if ((options.resources ?? []).includes(fallback)) return fallback;
+  throw invalid(
+    'defaultResource',
+    `is ${renderCauseValue(fallback)}, which is not one of resources`,
+    'authorizationServer({ resources: [defaultResource], defaultResource })   # or drop defaultResource',
+  );
+}
+
+export function resolveAuthServerConfig(
+  options: AuthorizationServerOptions,
+): ResolvedAuthServerConfig {
+  const url = issuerUrl(options.issuer);
+  const grants = new Set<AuthServerGrant>(
+    options.grants ?? ['authorization_code', 'refresh_token'],
+  );
+  for (const grant of grants) {
+    if (!KNOWN_GRANTS.has(grant)) {
+      throw invalid(
+        'grants',
+        `names ${renderCauseValue(grant)}, which this server does not implement`,
+        `authorizationServer({ grants: [${[...KNOWN_GRANTS].map((g) => `'${g}'`).join(', ')}] })   # only these are implemented`,
+      );
+    }
+  }
+  for (const scope of options.scopes) {
+    if (!SCOPE_TOKEN.test(scope)) {
+      throw invalid(
+        'scopes',
+        `holds ${renderCauseValue(scope)}, not an RFC 6749 scope-token`,
+        "authorizationServer({ scopes: ['cases:read'] })   # printable ASCII, no space, quote or backslash",
+      );
+    }
+  }
+  const lifetimes = options.lifetimes;
+  const device = grants.has(DEVICE_GRANT);
+  if (device && options.devicePath === undefined) {
+    throw invalid(
+      'devicePath',
+      'is missing while the device grant is enabled, so verification_uri would name no page',
+      "authorizationServer({ grants, devicePath: '/oauth/device' })   # the app's verification page",
+    );
+  }
+  const clock = options.clock ?? systemClock;
+  return {
+    issuer: options.issuer,
+    basePath: url.pathname === '/' ? '' : url.pathname,
+    origin: url.origin,
+    store: options.store,
+    consentPath: pagePath('consentPath', options.consentPath),
+    devicePath:
+      options.devicePath === undefined ? null : pagePath('devicePath', options.devicePath),
+    accessSeconds: lifetimeSeconds('lifetimes.accessSeconds', lifetimes.accessSeconds),
+    refreshIdleMs: lifetimeSeconds('lifetimes.refreshIdleDays', lifetimes.refreshIdleDays) * DAY_MS,
+    clientSeconds: grants.has('client_credentials')
+      ? lifetimeSeconds('lifetimes.clientSeconds', lifetimes.clientSeconds)
+      : null,
+    deviceSeconds: lifetimeSeconds('lifetimes.deviceSeconds', lifetimes.deviceSeconds ?? 600),
+    scopes: new Set(options.scopes),
+    resources: new Set((options.resources ?? []).map(resourceIndicator)),
+    defaultResource: defaultResourceOf(options),
+    dynamic: options.registration === 'dynamic',
+    grants,
+    clock,
+    limiter:
+      options.limiter ??
+      memoryAuthLimiter(clock, {
+        maxAttempts: 10,
+        windowMs: 60_000,
+        lockoutMs: 60_000,
+        scope: 'process',
+      }),
+    fetch: options.fetch,
+    resolveHost: options.resolveHost,
+    emit: options.onEvent ?? (() => {}),
+  };
+}

package/src/authorization-server-errors.ts

@@ -0,0 +1,23 @@
+// Single responsibility: the authorization server's coded refusals — the ones an APP's code meets
+// (a consent approved for a request the server refuses, a grant it never enabled). What a remote
+// client meets is RFC 6749 JSON on the wire (`authorization-server-wire.ts`), never an `X_` code.
+
+import { renderCauseValue } from '@ultimat3/core';
+import { AuthError } from './errors';
+
+/** 422: the consent page approved what `readRequest` would have refused to show. */
+export const consentInvalid = (reason: string): AuthError =>
+  new AuthError({
+    code: 'X_AUTH_CONSENT_INVALID',
+    cause: `the consent was refused: ${reason}`,
+    fix: 'server.readRequest(url)   # on the consent page: render its refusal when it has one, and approve only the request it returned',
+    callerFix: 'start the sign-in again from the application that sent you here',
+  });
+
+/** Logged, never thrown at a client: the wire answers `unsupported_grant_type`. */
+export const grantDisabled = (grantType: string): AuthError =>
+  new AuthError({
+    code: 'X_AUTH_GRANT_DISABLED',
+    cause: `a client asked for grant_type ${renderCauseValue(grantType)}, which authorizationServer({ grants }) does not enable`,
+    fix: "authorizationServer({ grants: ['authorization_code', 'refresh_token', '<grant>'] })   # with its lifetime — or the client uses an enabled grant",
+  });

package/src/authorization-server-postgres-sql.ts

@@ -0,0 +1,107 @@
+// The statements `postgresAuthServerStore` runs, spelled out so an operator can run the exact one a
+// log line names. Every single-use transition is ONE conditional statement: the `where … is null`
+// is re-evaluated after a lock wait, so two racing redemptions cannot both see a live row.
+
+export const SQL_OAUTH_CLIENT_PUT = `
+insert into x_oauth_clients
+  (client_id, name, secret_hash, auth_method, redirect_uris, grant_types, scopes, resources, created_at)
+values ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+on conflict (client_id) do update set
+  name = excluded.name, secret_hash = excluded.secret_hash, auth_method = excluded.auth_method,
+  redirect_uris = excluded.redirect_uris, grant_types = excluded.grant_types,
+  scopes = excluded.scopes, resources = excluded.resources
+`;
+
+export const SQL_OAUTH_CLIENT_GET = 'select * from x_oauth_clients where client_id = $1';
+
+export const SQL_OAUTH_CODE_PUT = `
+insert into x_oauth_codes
+  (code_hash, grant_id, client_id, subject, scopes, resource, redirect_uri, code_challenge, expires_at)
+values ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+`;
+
+export const SQL_OAUTH_CODE_TAKE = `
+update x_oauth_codes set used_at = $2 where code_hash = $1 and used_at is null returning *
+`;
+
+export const SQL_OAUTH_CODE_GET = 'select * from x_oauth_codes where code_hash = $1';
+
+export const SQL_OAUTH_GRANT_PUT = `
+insert into x_oauth_grants (id, client_id, subject, scopes, resource, created_at, refreshed_at)
+values ($1, $2, $3, $4, $5, $6, $7)
+`;
+
+export const SQL_OAUTH_GRANT_GET = 'select * from x_oauth_grants where id = $1';
+
+export const SQL_OAUTH_GRANT_TOUCH = 'update x_oauth_grants set refreshed_at = $2 where id = $1';
+
+export const SQL_OAUTH_GRANT_REVOKE = `
+update x_oauth_grants set revoked_at = $2 where id = $1 and revoked_at is null
+`;
+
+export const SQL_OAUTH_GRANTS_REVOKE = `
+with revoked as (
+  update x_oauth_grants set revoked_at = $3
+  where subject = $1 and ($2::text is null or client_id = $2) and revoked_at is null
+  returning 1
+)
+select count(*)::int as n from revoked
+`;
+
+export const SQL_OAUTH_TOKEN_PUT = `
+insert into x_oauth_tokens (token_hash, kind, grant_id, created_at, expires_at)
+values ($1, $2, $3, $4, $5)
+`;
+
+export const SQL_OAUTH_TOKEN_GET = 'select * from x_oauth_tokens where token_hash = $1';
+
+/** Retire the live one and insert its successor in ONE statement: no successor without the retire. */
+export const SQL_OAUTH_REFRESH_ROTATE = `
+with retired as (
+  update x_oauth_tokens set retired_at = $2
+  where token_hash = $1 and kind = 'refresh' and retired_at is null
+  returning grant_id
+)
+insert into x_oauth_tokens (token_hash, kind, grant_id, created_at, expires_at)
+select $3, 'refresh', grant_id, $4, $5 from retired
+returning grant_id
+`;
+
+export const SQL_OAUTH_DEVICE_PUT = `
+insert into x_oauth_devices
+  (device_code_hash, user_code_hash, client_id, scopes, resource, interval_seconds, created_at, expires_at)
+values ($1, $2, $3, $4, $5, $6, $7, $8)
+`;
+
+export const SQL_OAUTH_DEVICE_BY_USER_CODE =
+  'select * from x_oauth_devices where user_code_hash = $1';
+
+export const SQL_OAUTH_DEVICE_GET = 'select * from x_oauth_devices where device_code_hash = $1';
+
+export const SQL_OAUTH_DEVICE_DECIDE = `
+update x_oauth_devices set status = $2, subject = $3, granted_scopes = $4
+where user_code_hash = $1 and status = 'pending' and expires_at > $5
+returning *
+`;
+
+export const SQL_OAUTH_DEVICE_POLLED = `
+update x_oauth_devices set last_polled_at = $2 where device_code_hash = $1
+`;
+
+export const SQL_OAUTH_DEVICE_CONSUME = `
+update x_oauth_devices set status = 'consumed'
+where device_code_hash = $1 and status = 'approved'
+returning 1
+`;
+
+/** Four deletes in one statement; the count is everything that went. */
+export const SQL_OAUTH_PURGE = `
+with codes as (delete from x_oauth_codes where expires_at < $1 returning 1),
+tokens as (delete from x_oauth_tokens where expires_at < $1 returning 1),
+devices as (delete from x_oauth_devices where expires_at < $1 returning 1),
+grants as (
+  delete from x_oauth_grants where revoked_at < $1 or refreshed_at < $2 returning 1
+)
+select ((select count(*) from codes) + (select count(*) from tokens)
+  + (select count(*) from devices) + (select count(*) from grants))::int as n
+`;