@ultimat3/auth 29.3.2 → 30.0.0

package/src/authorization-server-schema.ts

@@ -0,0 +1,82 @@
+// The DDL of the authorization server's five framework tables, and nothing else: a leaf, so the
+// boot's `FRAMEWORK_SCHEMA` reads it beside `AUTH_TABLES` without the server's logic. Every secret
+// column holds a SHA-256 digest, never the credential. Lists are SPACE-joined text: scope-tokens
+// and URIs hold no space. Imports nothing.
+
+export const AUTH_SERVER_TABLES = [
+  'x_oauth_clients',
+  'x_oauth_codes',
+  'x_oauth_grants',
+  'x_oauth_tokens',
+  'x_oauth_devices',
+] as const;
+
+/**
+ * Applied by the boot, never by an app migration. `create … if not exists` throughout; a new
+ * column is an `alter table … add column if not exists`, never an edit to a `create`.
+ */
+export const SQL_AUTH_SERVER_TABLES = `
+create table if not exists x_oauth_clients (
+  client_id     text        primary key,
+  name          text        not null,
+  secret_hash   text,
+  auth_method   text        not null,
+  redirect_uris text        not null default '',
+  grant_types   text        not null default '',
+  scopes        text        not null default '',
+  resources     text        not null default '',
+  created_at    timestamptz not null
+);
+
+create table if not exists x_oauth_grants (
+  id           text        primary key,
+  client_id    text        not null,
+  subject      text        not null,
+  scopes       text        not null,
+  resource     text,
+  created_at   timestamptz not null,
+  refreshed_at timestamptz not null,
+  revoked_at   timestamptz
+);
+
+create index if not exists x_oauth_grants_subject_idx on x_oauth_grants (subject, client_id);
+
+create table if not exists x_oauth_codes (
+  code_hash      text        primary key,
+  grant_id       text        not null,
+  client_id      text        not null,
+  subject        text        not null,
+  scopes         text        not null,
+  resource       text,
+  redirect_uri   text        not null,
+  code_challenge text        not null,
+  expires_at     timestamptz not null,
+  used_at        timestamptz
+);
+
+create table if not exists x_oauth_tokens (
+  token_hash text        primary key,
+  kind       text        not null,
+  grant_id   text        not null,
+  created_at timestamptz not null,
+  expires_at timestamptz not null,
+  retired_at timestamptz
+);
+
+create index if not exists x_oauth_tokens_grant_idx on x_oauth_tokens (grant_id);
+
+create table if not exists x_oauth_devices (
+  device_code_hash text        primary key,
+  user_code_hash   text        not null unique,
+  client_id        text        not null,
+  scopes           text        not null,
+  resource         text,
+  status           text        not null default 'pending',
+  subject          text,
+  granted_scopes   text,
+  interval_seconds integer     not null,
+  last_polled_at   timestamptz,
+  created_at       timestamptz not null,
+  expires_at       timestamptz not null
+);
+`;

package/src/authorization-server-store.ts

@@ -0,0 +1,189 @@
+// Single responsibility: the contract an authorization server's storage answers, and the memory
+// driver. Every single-use rule is a STORAGE guarantee — a code taken once, a refresh token rotated
+// once, a device code consumed once — so each is one atomic method, never a read then a write.
+// Postgres is `authorization-server-postgres.ts`; the contract test holds the two to one answer.
+
+import { timingSafeEqual } from '@ultimat3/core';
+import type {
+  AuthCodeRecord,
+  AuthGrantRecord,
+  AuthServerClient,
+  AuthTokenRecord,
+  DeviceCodeRecord,
+} from './authorization-server-types';
+
+export type RefreshRotation =
+  | { readonly outcome: 'rotated'; readonly grantId: string }
+  /** The token was already retired: somebody holds a copy. The caller revokes `grantId`. */
+  | { readonly outcome: 'replayed'; readonly grantId: string }
+  | { readonly outcome: 'unknown' };
+
+export type DeviceDecision =
+  | { readonly status: 'approved'; readonly subject: string; readonly scopes: readonly string[] }
+  | { readonly status: 'denied' };
+
+export interface AuthServerStore {
+  putClient(client: AuthServerClient): Promise<void>;
+  getClient(clientId: string): Promise<AuthServerClient | null>;
+  putCode(code: AuthCodeRecord): Promise<void>;
+  /** Marks the code used at `at` in the step that reads it. `fresh: false` is a replay. */
+  takeCode(
+    codeHash: string,
+    at: Date,
+  ): Promise<{ readonly code: AuthCodeRecord; readonly fresh: boolean } | null>;
+  putGrant(grant: AuthGrantRecord): Promise<void>;
+  getGrant(id: string): Promise<AuthGrantRecord | null>;
+  /** Restarts the idle window. */
+  touchGrant(id: string, at: Date): Promise<void>;
+  revokeGrant(id: string, at: Date): Promise<void>;
+  /** Every live grant of `subject` (of one client when named). Answers how many. */
+  revokeGrants(
+    filter: { subject: string; clientId?: string | undefined },
+    at: Date,
+  ): Promise<number>;
+  putToken(token: AuthTokenRecord): Promise<void>;
+  getToken(tokenHash: string): Promise<AuthTokenRecord | null>;
+  /** Retire the live refresh token `tokenHash` and store `next`, atomically. */
+  rotateRefresh(tokenHash: string, next: AuthTokenRecord, at: Date): Promise<RefreshRotation>;
+  putDevice(device: DeviceCodeRecord): Promise<void>;
+  deviceByUserCode(userCodeHash: string): Promise<DeviceCodeRecord | null>;
+  /** Pending and unexpired at `at` → decided. `null` when it was not in that state. */
+  decideDevice(
+    userCodeHash: string,
+    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>;
+  /** Approved → consumed. `false` when another poll took it first. */
+  consumeDevice(deviceCodeHash: string, at: Date): Promise<boolean>;
+  /**
+   * Deletes codes, tokens and device codes expired before `before`, grants revoked before it, and
+   * grants last refreshed before `idleBefore` (past the idle window, so unrefreshable).
+   */
+  purge(before: Date, idleBefore: Date): Promise<number>;
+}
+
+/**
+ * Per PROCESS: right for a test and `x dev`, wrong for a fleet — a code minted on one replica is
+ * redeemed on another. A deployment passes `postgresAuthServerStore({ executor })`.
+ */
+export function memoryAuthServerStore(): AuthServerStore {
+  const clients = new Map<string, AuthServerClient>();
+  const codes = new Map<string, AuthCodeRecord>();
+  const grants = new Map<string, AuthGrantRecord>();
+  const tokens = new Map<string, AuthTokenRecord>();
+  const devices = new Map<string, DeviceCodeRecord>();
+  const deviceOfUserCode = (hash: string): DeviceCodeRecord | undefined => {
+    for (const device of devices.values()) {
+      if (timingSafeEqual(device.userCodeHash, hash)) return device;
+    }
+    return undefined;
+  };
+  const expired = (row: { readonly expiresAt: Date }, before: Date): boolean =>
+    row.expiresAt.getTime() < before.getTime();
+  return {
+    async putClient(client) {
+      clients.set(client.clientId, client);
+    },
+    getClient: async (id) => clients.get(id) ?? null,
+    async putCode(code) {
+      codes.set(code.codeHash, code);
+    },
+    async takeCode(hash, at) {
+      const code = codes.get(hash);
+      if (code === undefined) return null;
+      if (code.usedAt !== null) return { code, fresh: false };
+      codes.set(hash, { ...code, usedAt: at });
+      return { code, fresh: true };
+    },
+    async putGrant(grant) {
+      grants.set(grant.id, grant);
+    },
+    getGrant: async (id) => grants.get(id) ?? null,
+    async touchGrant(id, at) {
+      const grant = grants.get(id);
+      if (grant !== undefined) grants.set(id, { ...grant, refreshedAt: at });
+    },
+    async revokeGrant(id, at) {
+      const grant = grants.get(id);
+      if (grant !== undefined && grant.revokedAt === null) {
+        grants.set(id, { ...grant, revokedAt: at });
+      }
+    },
+    async revokeGrants(filter, at) {
+      let revoked = 0;
+      for (const grant of grants.values()) {
+        if (grant.revokedAt !== null || grant.subject !== filter.subject) continue;
+        if (filter.clientId !== undefined && grant.clientId !== filter.clientId) continue;
+        grants.set(grant.id, { ...grant, revokedAt: at });
+        revoked += 1;
+      }
+      return revoked;
+    },
+    async putToken(token) {
+      tokens.set(token.tokenHash, token);
+    },
+    getToken: async (hash) => tokens.get(hash) ?? null,
+    async rotateRefresh(hash, next, at) {
+      const token = tokens.get(hash);
+      if (token === undefined || token.kind !== 'refresh') return { outcome: 'unknown' };
+      if (token.retiredAt !== null) return { outcome: 'replayed', grantId: token.grantId };
+      tokens.set(hash, { ...token, retiredAt: at });
+      tokens.set(next.tokenHash, next);
+      return { outcome: 'rotated', grantId: token.grantId };
+    },
+    async putDevice(device) {
+      devices.set(device.deviceCodeHash, device);
+    },
+    deviceByUserCode: async (hash) => deviceOfUserCode(hash) ?? null,
+    async decideDevice(hash, decision, at) {
+      const device = deviceOfUserCode(hash);
+      if (device === undefined || device.status !== 'pending') return null;
+      if (device.expiresAt.getTime() <= at.getTime()) return null;
+      const decided: DeviceCodeRecord =
+        decision.status === 'approved'
+          ? {
+              ...device,
+              status: 'approved',
+              subject: decision.subject,
+              grantedScopes: decision.scopes,
+            }
+          : { ...device, status: 'denied' };
+      devices.set(device.deviceCodeHash, decided);
+      return decided;
+    },
+    async pollDevice(hash, at) {
+      const device = devices.get(hash);
+      if (device === undefined) return null;
+      devices.set(hash, { ...device, lastPolledAt: at });
+      return device;
+    },
+    async consumeDevice(hash, _at) {
+      const device = devices.get(hash);
+      if (device === undefined || device.status !== 'approved') return false;
+      devices.set(hash, { ...device, status: 'consumed' });
+      return true;
+    },
+    async purge(before, idleBefore) {
+      let purged = 0;
+      const sweep = <T>(rows: Map<string, T>, gone: (row: T) => boolean): void => {
+        for (const [key, row] of [...rows]) {
+          if (!gone(row)) continue;
+          rows.delete(key);
+          purged += 1;
+        }
+      };
+      sweep(codes, (row) => expired(row, before));
+      sweep(tokens, (row) => expired(row, before));
+      sweep(devices, (row) => expired(row, before));
+      sweep(
+        grants,
+        (row) =>
+          (row.revokedAt !== null && row.revokedAt.getTime() < before.getTime()) ||
+          row.refreshedAt.getTime() < idleBefore.getTime(),
+      );
+      return purged;
+    },
+  };
+}

package/src/authorization-server-tokens.ts

@@ -0,0 +1,118 @@
+// Single responsibility: mint, answer and resolve the server's tokens. Opaque and stored hashed —
+// never a JWT — so a revocation holds on the very next lookup, and a database read leaks no
+// usable credential. PKCE's S256 check lives here too, compared in constant time.
+
+import { timingSafeEqual } from '@ultimat3/core';
+import type { ResolvedAuthServerConfig } from './authorization-server-config';
+import type { AuthGrantRecord, AuthTokenRecord, ResolvedGrant } from './authorization-server-types';
+import { base64Url, randomToken, sha256Hex } from './tokens';
+
+/** Prefixes a secret scanner can match. Carry nothing; the token is 32 random bytes after them. */
+export const ACCESS_TOKEN_PREFIX = 'xat_';
+export const REFRESH_TOKEN_PREFIX = 'xrt_';
+
+export type TokenOutcome =
+  | { readonly ok: true; readonly body: Readonly<Record<string, unknown>> }
+  | {
+      readonly ok: false;
+      /** RFC 6749 §5.2 (or RFC 8628 §3.5) error. */
+      readonly error: string;
+      readonly description: string;
+      /** 400 unless the client failed to authenticate (401). */
+      readonly status: 400 | 401;
+    };
+
+export const refused = (
+  error: string,
+  description: string,
+  status: 400 | 401 = 400,
+): TokenOutcome => ({
+  ok: false,
+  error,
+  description,
+  status,
+});
+
+/** RFC 7636 §4.6: `BASE64URL(SHA256(ASCII(code_verifier))) == code_challenge`. */
+export function pkceMatches(verifier: string, challenge: string): boolean {
+  if (!/^[A-Za-z0-9\-._~]{43,128}$/.test(verifier)) return false;
+  const digest = new Bun.CryptoHasher('sha256').update(verifier).digest();
+  return timingSafeEqual(base64Url(new Uint8Array(digest)), challenge);
+}
+
+const tokenRecord = (
+  config: ResolvedAuthServerConfig,
+  kind: AuthTokenRecord['kind'],
+  grantId: string,
+  lifeMs: number,
+): { readonly token: string; readonly record: AuthTokenRecord } => {
+  const token = `${kind === 'access' ? ACCESS_TOKEN_PREFIX : REFRESH_TOKEN_PREFIX}${randomToken(32)}`;
+  const now = config.clock.now();
+  return {
+    token,
+    record: {
+      tokenHash: sha256Hex(token),
+      kind,
+      grantId,
+      createdAt: now,
+      expiresAt: new Date(now.getTime() + lifeMs),
+      retiredAt: null,
+    },
+  };
+};
+
+/** A refresh token's row: it lives as long as the idle window, which a rotation restarts. */
+export const refreshRecord = (config: ResolvedAuthServerConfig, grantId: string) =>
+  tokenRecord(config, 'refresh', grantId, config.refreshIdleMs);
+
+/** An access token (stored), plus the refresh token when one was already minted for the answer. */
+export async function tokenAnswer(
+  config: ResolvedAuthServerConfig,
+  grant: AuthGrantRecord,
+  accessSeconds: number,
+  refreshToken: string | null,
+): Promise<TokenOutcome> {
+  const access = tokenRecord(config, 'access', grant.id, accessSeconds * 1000);
+  await config.store.putToken(access.record);
+  return {
+    ok: true,
+    body: {
+      access_token: access.token,
+      token_type: 'Bearer',
+      expires_in: accessSeconds,
+      scope: grant.scopes.join(' '),
+      ...(refreshToken === null ? {} : { refresh_token: refreshToken }),
+    },
+  };
+}
+
+/** A new refresh token, stored, for a grant that has none yet. */
+export async function firstRefresh(
+  config: ResolvedAuthServerConfig,
+  grantId: string,
+): Promise<string | null> {
+  if (!config.grants.has('refresh_token')) return null;
+  const refresh = refreshRecord(config, grantId);
+  await config.store.putToken(refresh.record);
+  return refresh.token;
+}
+
+/** A live access token's grant. `null` for unknown, expired, a refresh token, or revoked. */
+export async function resolveAccess(
+  config: ResolvedAuthServerConfig,
+  token: string,
+): Promise<{ readonly grant: AuthGrantRecord; readonly token: AuthTokenRecord } | null> {
+  const record = await config.store.getToken(sha256Hex(token));
+  if (record === null || record.kind !== 'access') return null;
+  if (record.expiresAt.getTime() <= config.clock.now().getTime()) return null;
+  const grant = await config.store.getGrant(record.grantId);
+  if (grant === null || grant.revokedAt !== null) return null;
+  return { grant, token: record };
+}
+
+export const resolvedGrant = (grant: AuthGrantRecord): ResolvedGrant => ({
+  subject: grant.subject,
+  scopes: new Set(grant.scopes),
+  clientId: grant.clientId,
+  resource: grant.resource,
+});

package/src/authorization-server-types.ts

@@ -0,0 +1,108 @@
+// Single responsibility: the records an authorization server keeps — clients, codes, grants, tokens
+// and device codes — and the screened request a consent page shows. Data only; the store contract
+// is `authorization-server-store.ts`, the rules that fill these are the grant modules.
+
+/** The grants a server may enable. `authorization_code` and `refresh_token` are the default pair. */
+export type AuthServerGrant =
+  | 'authorization_code'
+  | 'refresh_token'
+  | 'client_credentials'
+  | 'urn:ietf:params:oauth:grant-type:device_code';
+
+export const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+
+/** `none` is a public client (PKCE is its proof); the two secret methods are a confidential one. */
+export type ClientAuthMethod = 'none' | 'client_secret_basic' | 'client_secret_post';
+
+export interface AuthServerClient {
+  /** Opaque for a registered client; the https URL itself for a metadata-document client. */
+  readonly clientId: string;
+  readonly name: string;
+  /** `sha256Hex` of the secret, `null` for a public client. The secret itself is never stored. */
+  readonly secretHash: string | null;
+  readonly authMethod: ClientAuthMethod;
+  /** Compared byte for byte. Never a prefix, never a pattern, never normalised. */
+  readonly redirectUris: readonly string[];
+  readonly grantTypes: readonly AuthServerGrant[];
+  /** What the client may ever be granted; a request narrows within it. Empty = the server's set. */
+  readonly scopes: readonly string[];
+  /** Resource indicators this client SERVES — what its introspection may see. */
+  readonly resources: readonly string[];
+  readonly createdAt: Date;
+}
+
+/** What `readRequest` screened and `approve` re-screens: the consent page's whole input. */
+export interface AuthorizationRequest {
+  readonly client: AuthServerClient;
+  readonly redirectUri: string;
+  readonly scopes: readonly string[];
+  /** RFC 8707 resource indicator, `null` when the client named none. */
+  readonly resource: string | null;
+  readonly state: string | null;
+  readonly codeChallenge: string;
+}
+
+export interface AuthCodeRecord {
+  readonly codeHash: string;
+  /** Pre-assigned: a replayed code revokes the grant this id names, whatever it minted. */
+  readonly grantId: string;
+  readonly clientId: string;
+  readonly subject: string;
+  readonly scopes: readonly string[];
+  readonly resource: string | null;
+  readonly redirectUri: string;
+  readonly codeChallenge: string;
+  readonly expiresAt: Date;
+  readonly usedAt: Date | null;
+}
+
+export interface AuthGrantRecord {
+  readonly id: string;
+  readonly clientId: string;
+  /** A person for the code and device grants, the client itself for `client_credentials`. */
+  readonly subject: string;
+  readonly scopes: readonly string[];
+  readonly resource: string | null;
+  readonly createdAt: Date;
+  /** The last refresh; the idle window runs from here. */
+  readonly refreshedAt: Date;
+  readonly revokedAt: Date | null;
+}
+
+export type AuthTokenKind = 'access' | 'refresh';
+
+export interface AuthTokenRecord {
+  readonly tokenHash: string;
+  readonly kind: AuthTokenKind;
+  readonly grantId: string;
+  readonly createdAt: Date;
+  readonly expiresAt: Date;
+  /** A rotated refresh token: kept so its replay is recognised, never honoured. */
+  readonly retiredAt: Date | null;
+}
+
+export type DeviceStatus = 'pending' | 'approved' | 'denied' | 'consumed';
+
+export interface DeviceCodeRecord {
+  readonly deviceCodeHash: string;
+  readonly userCodeHash: string;
+  readonly clientId: string;
+  readonly scopes: readonly string[];
+  readonly resource: string | null;
+  readonly status: DeviceStatus;
+  /** Set on approval: who consented and to what, narrowed. */
+  readonly subject: string | null;
+  readonly grantedScopes: readonly string[] | null;
+  readonly intervalSeconds: number;
+  readonly lastPolledAt: Date | null;
+  readonly createdAt: Date;
+  readonly expiresAt: Date;
+}
+
+/** What `resolve(token)` answers for a live access token. */
+export interface ResolvedGrant {
+  readonly subject: string;
+  readonly scopes: ReadonlySet<string>;
+  readonly clientId: string;
+  readonly resource: string | null;
+}

package/src/authorization-server-wire.ts

@@ -0,0 +1,135 @@
+// Single responsibility: the HTTP edge of the authorization server — the structural route shape
+// (`@ultimat3/http` is tier 2 like this package, so its `Route` is matched by structure, never
+// imported), reading a form body, reading client credentials, and answering RFC 6749 JSON.
+// `no-store` on every answer: a token response cached anywhere is a token handed to a stranger.
+
+import { isUltimateError } from '@ultimat3/core';
+import type { ClientCredentials } from './authorization-server-clients';
+import type { TokenOutcome } from './authorization-server-tokens';
+
+/** The part of http's `UltimateRequest` these routes read: the request, and its capped body. */
+export interface AuthServerHttpRequest {
+  readonly raw: Request;
+  bodyBytes(): Promise<Uint8Array>;
+}
+
+/** The part of http's `RequestContext` they read: the pipeline-resolved caller address. */
+export interface AuthServerHttpContext {
+  readonly ip: string | null;
+}
+
+/**
+ * Assignable to `@ultimat3/http`'s `Route` — the shape `runtime.routes` takes — by structure.
+ * Public by definition: they are how a client without a token gets one. No cookie authenticates
+ * here; a client authenticates in the body or the `Authorization: Basic` header.
+ */
+export interface AuthServerRoute {
+  readonly method: 'GET' | 'POST';
+  readonly path: string;
+  readonly handler: (
+    request: AuthServerHttpRequest,
+    ctx: AuthServerHttpContext,
+  ) => Promise<Response>;
+  readonly meta: {
+    readonly name: string;
+    readonly auth: 'public';
+    /**
+     * On every POST: http's `csrf` stage passes a cross-origin client here (the endpoint's whole
+     * purpose), and `authenticate` answering `null` keeps the session cookie from deciding anything.
+     */
+    readonly csrf?: 'cookieless';
+    readonly authenticate?: () => null;
+  };
+}
+
+const NO_STORE = { 'cache-control': 'no-store', pragma: 'no-cache' } as const;
+
+export const jsonAnswer = (
+  status: number,
+  body: unknown,
+  headers: Readonly<Record<string, string>> = {},
+): Response =>
+  Response.json(body, {
+    status,
+    headers: { ...NO_STORE, ...headers },
+  });
+
+/** RFC 6749 §5.2's body. A 401 names the scheme the client should retry with (§5.2). */
+export function outcomeAnswer(outcome: TokenOutcome, success = 200): Response {
+  if (outcome.ok) return jsonAnswer(success, outcome.body);
+  const { status } = outcome;
+  return jsonAnswer(
+    status,
+    { error: outcome.error, error_description: outcome.description },
+    status === 401 ? { 'www-authenticate': 'Basic realm="oauth"' } : {},
+  );
+}
+
+/** The limiter's `X_ACCOUNT_LOCKED` as RFC 6749 `429 temporarily_unavailable`; `null` otherwise. */
+export function throttledAnswer(error: unknown, description: string): Response | null {
+  if (!isUltimateError(error) || error.code !== 'X_ACCOUNT_LOCKED') return null;
+  const after = error.meta?.['retryAfterSeconds'];
+  return jsonAnswer(
+    429,
+    { error: 'temporarily_unavailable', error_description: description },
+    typeof after === 'number' ? { 'retry-after': String(after) } : {},
+  );
+}
+
+/** A form body, one value per name, or the name that repeats / `null` when it is not a form. */
+export async function readForm(
+  request: AuthServerHttpRequest,
+): Promise<Map<string, string> | { readonly refused: string }> {
+  const type = (request.raw.headers.get('content-type') ?? '').split(';')[0]?.trim().toLowerCase();
+  if (type !== 'application/x-www-form-urlencoded') {
+    return { refused: 'the body must be application/x-www-form-urlencoded' };
+  }
+  const params = new URLSearchParams(new TextDecoder().decode(await request.bodyBytes()));
+  const form = new Map<string, string>();
+  for (const [key, value] of params) {
+    if (form.has(key)) return { refused: `the ${key} parameter is repeated` };
+    form.set(key, value);
+  }
+  return form;
+}
+
+/**
+ * RFC 6749 §2.3.1: `Basic` (each half form-urlencoded first) or `client_id`/`client_secret` in
+ * the body — one method per request. `null` with a reason when the request is malformed.
+ */
+export function readClientCredentials(
+  request: AuthServerHttpRequest,
+  form: ReadonlyMap<string, string>,
+): ClientCredentials | { readonly refused: string } {
+  const header = request.raw.headers.get('authorization');
+  if (header !== null && /^basic /i.test(header)) {
+    if (form.has('client_secret')) return { refused: 'use one client authentication method' };
+    let decoded: string;
+    try {
+      decoded = atob(header.slice(6).trim());
+    } catch {
+      return { refused: 'the Basic credentials are not base64' };
+    }
+    const colon = decoded.indexOf(':');
+    if (colon < 1) return { refused: 'the Basic credentials carry no client id' };
+    const decode = (part: string): string | null => {
+      try {
+        return decodeURIComponent(part.replaceAll('+', ' '));
+      } catch {
+        return null;
+      }
+    };
+    const clientId = decode(decoded.slice(0, colon));
+    const secret = decode(decoded.slice(colon + 1));
+    if (clientId === null || secret === null)
+      return { refused: 'the Basic credentials are malformed' };
+    const named = form.get('client_id');
+    if (named !== undefined && named !== clientId)
+      return { refused: 'client_id disagrees with Basic' };
+    return { clientId, secret: secret === '' ? null : secret };
+  }
+  const clientId = form.get('client_id');
+  if (clientId === undefined || clientId === '') return { refused: 'client_id is required' };
+  const secret = form.get('client_secret');
+  return { clientId, secret: secret === undefined || secret === '' ? null : secret };
+}