@linxiraos/pi-ai 1.2.1 → 1.3.1

package/src/auth/refresh.ts

@@ -1,4 +1,4 @@
-import { logger } from "@linxiraos/pi-utils";
+import { logger, postmortem } from "@linxiraos/pi-utils";
 import * as AIError from "../error";
 import { getOAuthProvider, normalizeOAuthCredentialExpiry, refreshOAuthToken } from "../registry/oauth";
 import type { OAuthCredentials, OAuthProvider } from "../registry/oauth/types";
@@ -101,6 +101,9 @@ export class OAuthRefresher {
 	#oauthCredentialRefreshInFlight: Map<number, Promise<OAuthCredentials>> = new Map();
 	/** Access token this process last minted per credential id. */
 	#recentMints = new Map<number, { provider: string; access: string; at: number }>();
+	#pendingRefreshes = new Set<Promise<unknown>>();
+	#cancelRefreshCleanup?: () => void;
+	#shuttingDown = false;
 
 	constructor(deps: OAuthRefresherDeps) {
 		this.#deps = deps;
@@ -148,7 +151,33 @@ export class OAuthRefresher {
 	/**
 	 * Refresh one stored OAuth credential under durable row ownership.
 	 */
-	async refreshStored<T extends OAuthCredential = OAuthCredential>(
+	refreshStored<T extends OAuthCredential = OAuthCredential>(
+		provider: string,
+		options: StoredOAuthRefreshOptions<T>,
+	): Promise<StoredOAuthRefreshResult<T>> {
+		if (this.#shuttingDown) return Promise.reject(new AIError.AbortError("OAuth refresh stopped during shutdown"));
+		this.#cancelRefreshCleanup ??= postmortem.register("oauth-refresh", () => this.#drainRefreshes(), {
+			exitOnly: true,
+		});
+		const pending = this.#refreshStored(provider, options);
+		this.#pendingRefreshes.add(pending);
+		const settled = () => {
+			this.#pendingRefreshes.delete(pending);
+			if (this.#pendingRefreshes.size === 0 && !this.#shuttingDown) {
+				this.#cancelRefreshCleanup?.();
+				this.#cancelRefreshCleanup = undefined;
+			}
+		};
+		void pending.then(settled, settled);
+		return pending;
+	}
+
+	async #drainRefreshes(): Promise<void> {
+		this.#shuttingDown = true;
+		await Promise.allSettled(this.#pendingRefreshes);
+	}
+
+	async #refreshStored<T extends OAuthCredential = OAuthCredential>(
 		provider: string,
 		options: StoredOAuthRefreshOptions<T>,
 	): Promise<StoredOAuthRefreshResult<T>> {
@@ -158,6 +187,7 @@ export class OAuthRefresher {
 		let leasedCredentialId: number | undefined;
 
 		while (leaseStore) {
+			if (this.#shuttingDown) throw new AIError.AbortError("OAuth refresh stopped during shutdown");
 			if (options.signal?.aborted) throw new AIError.AbortError("OAuth refresh ownership aborted by caller");
 			const rows = this.#deps.store.listAuthCredentials(provider);
 			this.#deps.pool.replace(
@@ -240,6 +270,9 @@ export class OAuthRefresher {
 			if (options.canRefresh && !options.canRefresh(current)) {
 				return { credential: current, refreshed: false, removed: false };
 			}
+			if (this.#shuttingDown || options.signal?.aborted) {
+				throw new AIError.AbortError("OAuth refresh stopped before token exchange");
+			}
 			const serialized = serializeCredential(provider, current);
 			if (!serialized) return { credential: current, refreshed: false, removed: false };
 
@@ -495,13 +528,7 @@ export class OAuthRefresher {
 				forceRefresh,
 				signal,
 				refresh: (current, refreshSignal) =>
-					this.#requestOAuthCredentialRefresh(
-						provider,
-						current,
-						credentialId,
-						signal && refreshSignal ? AbortSignal.any([signal, refreshSignal]) : (signal ?? refreshSignal),
-						reason,
-					),
+					this.#requestOAuthCredentialRefresh(provider, current, credentialId, refreshSignal, reason),
 				isDefinitiveFailure: error => AIError.isDefinitiveOAuthFailure(String(error)),
 				disabledCause: error => `oauth refresh failed: ${String(error)}`,
 			});
@@ -564,9 +591,9 @@ export class OAuthRefresher {
 				refreshPromise = refreshOAuthToken(provider as OAuthProvider, credential, signal);
 			}
 		}
-		// Bound the refresh so a slow/hanging token endpoint cannot stall credential selection.
-		// Caller-driven abort jumps the gun on the timeout — the agent's ESC must
-		// take priority over the floor timeout.
+		// The caller may stop awaiting a refresh, but the leased token exchange
+		// must finish and persist any rotated token. Only the operation timeout
+		// aborts the exchange itself.
 		const cancellation = Promise.withResolvers<never>();
 		let onAbort: (() => void) | undefined;
 		const timeout = setTimeout(

package/src/auth/select.ts

@@ -144,7 +144,11 @@ export class CredentialSelector {
 	/**
 	 * Selects a credential of the specified type for a provider.
 	 * Returns both the credential and its index in the original array (for updates/removal).
-	 * Uses deterministic hashing for session stickiness and skips blocked credentials when possible.
+	 * With `sessionId` the scan starts at the session's hashed index; without one it starts at the
+	 * first stored credential and never advances round-robin. Model discovery peeks through this,
+	 * and credential-scoped catalogs (e.g. GitHub Copilot) key their cache rows on the credential
+	 * picked, so a rotating pick would read another account's cache namespace on every pass.
+	 * Blocked credentials are skipped when possible.
 	 */
 	selectByType<T extends AuthCredential["type"]>(
 		provider: string,
@@ -171,7 +175,9 @@ export class CredentialSelector {
 		if (credentials.length === 1) return credentials[0];
 
 		const providerKey = providerTypeKey(provider, type);
-		const order = this.#getCredentialOrder(providerKey, sessionId, credentials.length);
+		const order = sessionId
+			? this.#getCredentialOrder(providerKey, sessionId, credentials.length)
+			: credentials.map((_, index) => index);
 		const fallback = credentials[order[0]];
 
 		for (const idx of order) {

package/src/auth/types.ts

@@ -112,7 +112,7 @@ export interface StoredCredentialBlock {
 /**
  * Identity slice of a disabled (soft-deleted) credential tombstone — cause and
  * account identity only, never token material. Surfaced so auto-disabled
- * accounts (e.g. an expired Anthropic OAuth grant) stay visible in `zeta-c usage`
+ * accounts (e.g. an expired Anthropic OAuth grant) stay visible in `zetacode usage`
  * instead of silently vanishing until the user notices missing quota.
  */
 export interface DisabledCredentialSummary {
@@ -707,6 +707,16 @@ export interface AuthSourceOptions {
 	env?: "dedicated" | "aliases" | "none";
 }
 
+/** Options for {@link KeysApi.peek}. */
+export interface AuthPeekOptions {
+	/**
+	 * Fall back to an expired OAuth access token when no stored account holds an
+	 * unexpired one. Only for reads that never send the token, e.g. keying an
+	 * offline model-cache lookup on the account it names.
+	 */
+	includeExpired?: boolean;
+}
+
 /** Where a provider's auth comes from ({@link CredentialOrigin}) plus whether any leg holds a concrete key. */
 export interface AuthSource extends CredentialOrigin {
 	/** False when the only auth is an ambient AUTHENTICATED_SENTINEL source (AWS profile, ADC). */
@@ -830,7 +840,7 @@ export interface CredentialsApi {
 	 * Force the backing store to revalidate its credential snapshot, then
 	 * reload. Remote broker stores re-fetch the snapshot; local stores are
 	 * always current, so only the reload runs. Callers that pair live
-	 * per-credential data with stored identities (`zeta-c usage`) use this so a
+	 * per-credential data with stored identities (`zetacode usage`) use this so a
 	 * disk-cached snapshot cannot misattribute fresh reports.
 	 */
 	revalidate(): Promise<void>;
@@ -889,7 +899,7 @@ export interface CredentialsApi {
 	 */
 	disable(id: number, disabledCause: string): Promise<boolean>;
 	/**
-	 * Disabled credential tombstones for display surfaces (`zeta-c usage`,
+	 * Disabled credential tombstones for display surfaces (`zetacode usage`,
 	 * broker `GET /v1/credentials/disabled`). Empty when the backing store
 	 * keeps no tombstones or the remote broker predates the endpoint.
 	 */
@@ -941,9 +951,10 @@ export interface KeysApi {
 	 * Peek at API key for a provider without refreshing OAuth tokens.
 	 * Used for model discovery where we only need to know if credentials exist
 	 * and get a best-effort token. For GitHub Copilot we preserve enterprise
-	 * routing metadata so discovery can hit the correct host.
+	 * routing metadata so discovery can hit the correct host. Repeated peeks
+	 * return the same stored credential; they never rotate accounts.
 	 */
-	peek(provider: string): Promise<string | undefined>;
+	peek(provider: string, options?: AuthPeekOptions): Promise<string | undefined>;
 	/** Resolve the first active auth source by precedence without refreshing credentials. */
 	source(provider: string, options?: AuthSourceOptions): AuthSource | undefined;
 	/**

package/src/auth/usage-cache.ts

@@ -3,6 +3,7 @@ import type { AuthCredential, OAuthCredential } from "./types";
 import type { CredentialPool } from "./pool";
 import type { Provider } from "../types";
 import type { UsageCredential, UsageProvider, UsageReport } from "../usage";
+import { isRecord } from "../utils";
 
 const USAGE_CACHE_PREFIX = "usage_cache:";
 const USAGE_FORCE_REFRESH_CACHE_PREFIX = "force-refresh:";
@@ -53,6 +54,17 @@ function withoutRawPayload(value: unknown): unknown {
 	return rest;
 }
 
+/**
+ * End of a cached value's durable retention. A report is retained for 24h past
+ * its last successful fetch, so re-storing it as a failure fallback never
+ * extends that window; other values are retained for 24h from now.
+ */
+function retentionDeadline(value: unknown): number {
+	const fetchedAt = isRecord(value) ? value.fetchedAt : undefined;
+	const start = typeof fetchedAt === "number" && Number.isFinite(fetchedAt) && fetchedAt > 0 ? fetchedAt : Date.now();
+	return start + USAGE_LAST_GOOD_RETENTION_MS;
+}
+
 /** Convert a stored credential for usage providers; used by usage and health services. */
 export function buildUsageCredential(credential: AuthCredential): UsageCredential {
 	if (credential.type === "api_key") {
@@ -203,15 +215,19 @@ export class UsageCache {
 		return parseUsageCacheEntry<T>(raw);
 	}
 
+	/** Last successful report under `key` while inside its retention window; the failure-path fallback. */
+	lastGood(key: string): UsageReport | null {
+		const report = this.getStale<UsageReport | null>(key)?.value;
+		return report && Date.now() < retentionDeadline(report) ? report : null;
+	}
+
 	set<T>(key: string, entry: UsageCacheEntry<T>): void {
 		const value = withoutRawPayload(entry.value);
-		const payload = JSON.stringify({
-			value,
-			expiresAt: entry.expiresAt,
-		});
-		const durableExpiresAt =
-			value === null ? entry.expiresAt : Math.max(entry.expiresAt, Date.now() + USAGE_LAST_GOOD_RETENTION_MS);
-		this.#store.setCache(`${USAGE_CACHE_PREFIX}${key}`, payload, Math.floor(durableExpiresAt / 1000));
+		const deadline = value === null ? undefined : retentionDeadline(value);
+		// Failure cooldowns must not make a last-good report fresh beyond retention.
+		const expiresAt = deadline === undefined ? entry.expiresAt : Math.min(entry.expiresAt, deadline);
+		const payload = JSON.stringify({ value, expiresAt });
+		this.#store.setCache(`${USAGE_CACHE_PREFIX}${key}`, payload, Math.floor((deadline ?? expiresAt) / 1000));
 	}
 
 	deletePrefix(prefix: string): boolean {

package/src/auth/usage.ts

@@ -334,7 +334,7 @@ export class UsageService implements UsageApi {
 
 		const failure = this.#deps.cache.get<null>(failureKey);
 		if (failure && failure.expiresAt > now) {
-			return this.#deps.cache.getStale<UsageReport | null>(cacheKey)?.value ?? null;
+			return this.#deps.cache.lastGood(cacheKey);
 		}
 
 		// Invalidation must not fork an already-running credential probe. Share it;
@@ -378,9 +378,7 @@ export class UsageService implements UsageApi {
 			// so an expired login does not display stale quota indefinitely.
 			const providerImpl = this.providerFor(request.provider);
 			const retainLastGood = !invalidated && providerImpl?.retainLastGoodOnFailure !== false;
-			const lastGood = retainLastGood
-				? (this.#deps.cache.getStale<UsageReport | null>(cacheKey)?.value ?? null)
-				: null;
+			const lastGood = retainLastGood ? this.#deps.cache.lastGood(cacheKey) : null;
 			const failureBackoffMs = providerImpl?.failureBackoffMs ?? USAGE_FAILURE_BACKOFF_MS;
 			const backoffJitter = failureBackoffMs * (Math.random() * 0.5 - 0.25);
 			const coolDown = Date.now() + failureBackoffMs + backoffJitter;

package/src/auth-broker/remote-store.ts

@@ -3,9 +3,9 @@
  * snapshot. Refresh tokens never leave the broker; mutating methods (`replace*`,
  * `upsert*`, `delete*ForProvider`) throw because login flows are server-side.
  *
- * Cache (`getCache`/`setCache`/`cleanExpiredCache`) is in-memory and ephemeral —
- * usage reports cache TTL is 5 minutes per credential, so durability across
- * runs isn't required.
+ * Cache (`getCache`/`setCache`/`cleanExpiredCache`) is in-memory and ephemeral.
+ * The bounded hot set preserves recently used session pins without keeping
+ * every gateway client's 30-day sticky row resident.
  */
 import * as os from "node:os";
 import { getAppName, getInstallId, logger, postmortem } from "@linxiraos/pi-utils";
@@ -36,6 +36,11 @@ import type {
 	SnapshotStreamEvent,
 } from "./types";
 
+// Bound both the number of distinct session pins and the size of caller-supplied
+// keys/values; an evicted session falls back to normal credential selection.
+const REMOTE_CACHE_MAX_ENTRIES = 4096;
+const REMOTE_CACHE_MAX_CHARACTERS = 4 * 1024 * 1024;
+
 /**
  * Per-provider OAuth identities visible to this trusted broker client.
  * Missing providers are unrestricted; an empty set excludes that provider's
@@ -289,6 +294,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	/** Present while the background loop is parked; resolved by `#noteActivity` or `close()`. */
 	#activityWakeup: PromiseWithResolvers<void> | null = null;
 	#cache: Map<string, CacheEntry> = new Map();
+	#cacheCharacters = 0;
 	#usageCache?: UsageCacheEntry;
 	#usageInflight?: Promise<UsageReport[] | null>;
 	#credentialBlockReconcileAfter: Map<string, number> = new Map();
@@ -1177,28 +1183,46 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		const entry = this.#cache.get(key);
 		if (!entry) return null;
 		if (entry.expiresAtSec * 1000 <= Date.now()) {
-			this.#cache.delete(key);
+			this.#deleteCache(key);
 			return null;
 		}
+		this.#cache.delete(key);
+		this.#cache.set(key, entry);
 		return entry.value;
 	}
 
 	setCache(key: string, value: string, expiresAtSec: number): void {
 		this.#noteActivity();
+		this.#deleteCache(key);
+		const size = key.length + value.length;
+		if (size > REMOTE_CACHE_MAX_CHARACTERS) return;
 		this.#cache.set(key, { value, expiresAtSec });
+		this.#cacheCharacters += size;
+		while (this.#cache.size > REMOTE_CACHE_MAX_ENTRIES || this.#cacheCharacters > REMOTE_CACHE_MAX_CHARACTERS) {
+			const oldest = this.#cache.keys().next().value;
+			if (oldest === undefined) break;
+			this.#deleteCache(oldest);
+		}
+	}
+
+	#deleteCache(key: string): void {
+		const entry = this.#cache.get(key);
+		if (!entry) return;
+		this.#cacheCharacters -= key.length + entry.value.length;
+		this.#cache.delete(key);
 	}
 
 	/** Drop all cache rows whose keys start with the supplied prefix. */
 	deleteCachePrefix(prefix: string): void {
 		for (const key of this.#cache.keys()) {
-			if (key.startsWith(prefix)) this.#cache.delete(key);
+			if (key.startsWith(prefix)) this.#deleteCache(key);
 		}
 	}
 
 	cleanExpiredCache(): void {
 		const nowSec = Math.floor(Date.now() / 1000);
 		for (const [key, entry] of this.#cache) {
-			if (entry.expiresAtSec <= nowSec) this.#cache.delete(key);
+			if (entry.expiresAtSec <= nowSec) this.#deleteCache(key);
 		}
 	}
 
@@ -1572,6 +1596,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		// process exiting right after close() still sends it; failures are dropped.
 		void this.#flushObservedUsage().finally(() => this.#cancelObservedUsageExitFlush?.());
 		this.#cache.clear();
+		this.#cacheCharacters = 0;
 		this.#usageOverlays.clear();
 	}
 }

package/src/auth-gateway/clients.ts

@@ -0,0 +1,318 @@
+/**
+ * Scoped auth-gateway clients.
+ *
+ * A holder of the gateway token may call every served model, and recovery may
+ * serve it from any broker credential. A scoped client authenticates with its
+ * own bearer, configured only as a SHA-256 digest, and is limited to:
+ *
+ * - `models`: the served models it may call, as exact `provider/id` grants or
+ *   `provider/*`. Absent allows every served model; `[]` allows none.
+ * - `accounts`: per provider, the broker OAuth accounts (identity keys, as in
+ *   account pools) its requests may use. A listed provider never falls back to
+ *   a sibling account or an API key; an empty list allows no account. When
+ *   present, it is also a provider allow-list: a provider it omits is refused,
+ *   so a binding can never be bypassed through another provider's accounts.
+ *
+ * Account binding reuses `AuthStorage.sessions.restrict`. Each admitted
+ * version of a client (its token, models and accounts) resolves a bound
+ * provider's credentials under a session id of its own, restricted before the
+ * token is admitted. A reload that changes any of them admits a new version
+ * under a new session; requests the old version admitted keep resolving under
+ * the old restriction until they finish, and only then is it lifted. A
+ * version's requests share that session's account pin.
+ */
+import { isRecord } from "@linxiraos/pi-utils";
+import type { SessionRestrictionLease, SessionsApi } from "../auth/types";
+import type { Api, Model } from "../types";
+
+/** One scoped client. */
+export interface AuthGatewayClient {
+	/** Operator-chosen name, logged with the client's requests. */
+	name: string;
+	/** Hex SHA-256 digest of the client's bearer token. */
+	tokenSha256: string;
+	/** `provider/id` or `provider/*` grants; absent allows every served model, `[]` none. */
+	models?: readonly string[];
+	/** Provider id → OAuth identity keys the client's requests to that provider may use. */
+	accounts?: Readonly<Record<string, readonly string[]>>;
+}
+
+/** An admitted scoped client, as the gateway's routes see it. */
+export interface AuthGatewayClientScope {
+	readonly name: string;
+	/** False when the client may call every served model. */
+	readonly limitsModels: boolean;
+	/** Whether the client may call `model`. */
+	allows(model: Model<Api>): boolean;
+	/**
+	 * Session id the client's credential lookups for `provider` resolve under:
+	 * its own restricted session when `accounts` lists the provider, otherwise
+	 * the request's `sessionId`. Throws for a provider `accounts` omits, and for
+	 * a bound provider once the restriction is lifted, so a lookup can never
+	 * resolve unrestricted on the client's behalf.
+	 */
+	credentialSessionId(provider: string, sessionId: string): string;
+	/**
+	 * Hold the client's account restriction while a request uses it; call the
+	 * returned release once the request can no longer resolve a credential. A
+	 * reload that retires the client lifts the restriction only after every
+	 * hold is released. Take the first hold in the same tick as
+	 * `authenticate`, before a reload can retire the client.
+	 */
+	retain(): () => void;
+}
+
+const CLIENT_FIELDS: Record<string, true> = { tokenSha256: true, models: true, accounts: true };
+const SHA256_HEX = /^[0-9a-f]{64}$/i;
+// C0 controls and DEL: a name is logged verbatim.
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/;
+
+function invalid(where: string, problem: string): Error {
+	return new Error(`Invalid auth-gateway clients: ${where}: ${problem}`);
+}
+
+/**
+ * Parse a clients file: a JSON object mapping each client name to
+ * `{ tokenSha256, models?, accounts? }`. Any malformed entry or unknown field
+ * rejects the whole file, since a misspelled `models` would otherwise allow
+ * every model. Errors name the offending field, never its value.
+ */
+export function parseAuthGatewayClients(text: string): AuthGatewayClient[] {
+	let value: unknown;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		throw new Error("Invalid auth-gateway clients: not valid JSON");
+	}
+	if (!isRecord(value)) {
+		throw new Error("Invalid auth-gateway clients: expected an object mapping each client name to its entry");
+	}
+	const clients: AuthGatewayClient[] = [];
+	for (const [name, entry] of Object.entries(value)) {
+		if (!isRecord(entry)) throw invalid(name, "expected an object");
+		for (const field of Object.keys(entry)) {
+			if (!Object.hasOwn(CLIENT_FIELDS, field)) throw invalid(name, `unknown field "${field}"`);
+		}
+		const { tokenSha256, models, accounts } = entry;
+		if (typeof tokenSha256 !== "string") throw invalid(`${name}.tokenSha256`, "expected a hex SHA-256 digest");
+		const client: AuthGatewayClient = { name, tokenSha256 };
+		if (models !== undefined) {
+			if (!Array.isArray(models) || !models.every((grant): grant is string => typeof grant === "string")) {
+				throw invalid(`${name}.models`, 'expected a list of "provider/id" or "provider/*" grants');
+			}
+			client.models = models;
+		}
+		if (accounts !== undefined) {
+			if (!isRecord(accounts))
+				throw invalid(`${name}.accounts`, "expected an object mapping provider to identity keys");
+			// Null prototype: a provider named `__proto__` stays an own entry.
+			const pools: Record<string, readonly string[]> = Object.create(null);
+			for (const [provider, keys] of Object.entries(accounts)) {
+				if (!Array.isArray(keys) || !keys.every((key): key is string => typeof key === "string")) {
+					throw invalid(`${name}.accounts.${provider}`, "expected a list of OAuth identity keys");
+				}
+				pools[provider] = keys;
+			}
+			client.accounts = pools;
+		}
+		clients.push(client);
+	}
+	// Validate every entry here too, so a bad file fails where it is read.
+	compileClients(clients);
+	return clients;
+}
+
+/** Hex SHA-256 digest of a bearer token, as `tokenSha256` records it. */
+export function hashAuthGatewayToken(token: string): string {
+	return new Bun.CryptoHasher("sha256").update(token).digest("hex");
+}
+
+type RestrictionSessions = Pick<SessionsApi, "restrict" | "unrestrict">;
+
+/** A validated client: its model grants compiled, its accounts restricted while it is admitted or still serving. */
+class ClientScope implements AuthGatewayClientScope {
+	readonly name: string;
+	readonly tokenSha256: string;
+	readonly limitsModels: boolean;
+	/** Equal for the same entry read again, so a reload that leaves it unchanged keeps the scope and its pin. */
+	readonly policy: string;
+	/** Exact `provider/id` grants. */
+	readonly #models = new Set<string>();
+	/** Providers granted with `provider/*`. */
+	readonly #providers = new Set<string>();
+	readonly #accounts = new Map<string, readonly string[]>();
+	/** Whether `models` was given; absent allows every served model `accounts` permits. */
+	readonly #grantsModels: boolean;
+	/** Whether `accounts` was given, which makes it a provider allow-list too. */
+	readonly #bindsAccounts: boolean;
+	readonly #sessionId = crypto.randomUUID();
+	#leases: Array<[provider: string, lease: SessionRestrictionLease]> = [];
+	#sessions: RestrictionSessions | undefined;
+	#holds = 0;
+	#retired = false;
+	#released = false;
+
+	constructor(client: AuthGatewayClient) {
+		const { name } = client;
+		if (typeof name !== "string" || name.length === 0 || CONTROL_CHARACTER.test(name)) {
+			throw new Error("Invalid auth-gateway clients: a client name must be non-empty text");
+		}
+		if (!SHA256_HEX.test(client.tokenSha256)) throw invalid(`${name}.tokenSha256`, "expected 64 hex digits");
+		this.name = name;
+		this.tokenSha256 = client.tokenSha256.toLowerCase();
+		this.#grantsModels = client.models !== undefined;
+		this.#bindsAccounts = client.accounts !== undefined;
+		this.limitsModels = this.#grantsModels || this.#bindsAccounts;
+		for (const grant of client.models ?? []) {
+			const slash = grant.indexOf("/");
+			const provider = grant.slice(0, slash);
+			const id = grant.slice(slash + 1);
+			if (
+				slash <= 0 ||
+				id.length === 0 ||
+				provider.trim() !== provider ||
+				id.trim() !== id ||
+				(id.includes("*") && id !== "*")
+			) {
+				throw invalid(`${name}.models`, 'each grant must be "provider/id" or "provider/*"');
+			}
+			if (id === "*") this.#providers.add(provider);
+			else this.#models.add(grant);
+		}
+		for (const [provider, keys] of Object.entries(client.accounts ?? {})) {
+			// A provider id that matches no request would leave that provider unbound, so it must be exact.
+			if (provider.length === 0 || provider.trim() !== provider) {
+				throw invalid(`${name}.accounts`, "a provider id must be non-empty with no surrounding whitespace");
+			}
+			if (!keys.every(key => key.length > 0 && key.trim() === key)) {
+				throw invalid(`${name}.accounts`, 'expected identity keys such as "email:you@example.com|org:<org-id>"');
+			}
+			this.#accounts.set(provider, keys);
+		}
+		if (this.#bindsAccounts) {
+			// A grant `accounts` cannot serve is a typo or a misunderstanding; refusing it at load beats a silent 404.
+			const granted = [...this.#providers, ...Array.from(this.#models, grant => grant.slice(0, grant.indexOf("/")))];
+			const unbound = granted.find(provider => !this.#accounts.has(provider));
+			if (unbound !== undefined) {
+				throw invalid(`${name}.models`, `grants provider "${unbound}", which "accounts" does not list`);
+			}
+		}
+		this.policy = JSON.stringify([name, this.tokenSha256, client.models ?? null, client.accounts ?? null]);
+	}
+
+	allows(model: Model<Api>): boolean {
+		if (this.#bindsAccounts && !this.#accounts.has(model.provider)) return false;
+		if (!this.#grantsModels) return true;
+		return this.#providers.has(model.provider) || this.#models.has(`${model.provider}/${model.id}`);
+	}
+
+	credentialSessionId(provider: string, sessionId: string): string {
+		if (!this.#bindsAccounts) return sessionId;
+		if (!this.#accounts.has(provider)) {
+			throw new Error(`auth-gateway client ${this.name} is not bound to provider ${provider}`);
+		}
+		if (this.#released) throw new Error(`auth-gateway client ${this.name} was retired`);
+		return this.#sessionId;
+	}
+
+	retain(): () => void {
+		this.#holds++;
+		let held = true;
+		return () => {
+			if (!held) return;
+			held = false;
+			this.#holds--;
+			this.#releaseIfDone();
+		};
+	}
+
+	/** Restrict this scope's session to its accounts. */
+	restrict(sessions: RestrictionSessions): void {
+		this.#sessions = sessions;
+		for (const [provider, keys] of this.#accounts) {
+			this.#leases.push([provider, sessions.restrict(provider, this.#sessionId, keys)]);
+		}
+	}
+
+	/** No longer admitted: lift the restriction once the last request holding it is done. */
+	retire(): void {
+		this.#retired = true;
+		this.#releaseIfDone();
+	}
+
+	#releaseIfDone(): void {
+		if (!this.#retired || this.#holds > 0) return;
+		this.#released = true;
+		for (const [provider, lease] of this.#leases) this.#sessions?.unrestrict(provider, this.#sessionId, lease);
+		this.#leases = [];
+	}
+}
+
+/** Validate `clients` as one table and compile it, keyed by token digest. */
+function compileClients(clients: readonly AuthGatewayClient[]): Map<string, ClientScope> {
+	const compiled = new Map<string, ClientScope>();
+	const names = new Set<string>();
+	for (const client of clients) {
+		const scope = new ClientScope(client);
+		if (names.has(scope.name)) throw invalid(scope.name, "duplicate client name");
+		if (compiled.has(scope.tokenSha256)) throw invalid(scope.name, "another client has the same tokenSha256");
+		names.add(scope.name);
+		compiled.set(scope.tokenSha256, scope);
+	}
+	return compiled;
+}
+
+/**
+ * The scoped clients one gateway admits, looked up by the digest of the
+ * presented bearer.
+ */
+export class AuthGatewayClientTable {
+	readonly #sessions: RestrictionSessions;
+	/** Digests of the gateway's own tokens, which no client may claim. */
+	readonly #reserved: ReadonlySet<string>;
+	#byDigest = new Map<string, ClientScope>();
+	#closed = false;
+
+	constructor(sessions: RestrictionSessions, gatewayTokens: Iterable<string>) {
+		this.#sessions = sessions;
+		this.#reserved = new Set(Array.from(gatewayTokens, hashAuthGatewayToken));
+	}
+
+	/**
+	 * Replace the admitted clients. An invalid table throws and changes
+	 * nothing. An unchanged client keeps its scope; a new or changed one is
+	 * restricted before its token is admitted; the scopes left out are retired.
+	 * Ignored once the table is closed.
+	 */
+	set(clients: readonly AuthGatewayClient[]): void {
+		if (this.#closed) return;
+		const next = compileClients(clients);
+		for (const scope of next.values()) {
+			if (this.#reserved.has(scope.tokenSha256)) {
+				throw invalid(scope.name, "tokenSha256 is the gateway token's digest; give the client its own token");
+			}
+		}
+		for (const [digest, scope] of next) {
+			const current = this.#byDigest.get(digest);
+			if (current?.policy === scope.policy) next.set(digest, current);
+			else scope.restrict(this.#sessions);
+		}
+		const previous = this.#byDigest;
+		this.#byDigest = next;
+		for (const [digest, scope] of previous) {
+			if (next.get(digest) !== scope) scope.retire();
+		}
+	}
+
+	/** The client `token` authenticates, if any. */
+	authenticate(token: string): AuthGatewayClientScope | undefined {
+		return this.#byDigest.get(hashAuthGatewayToken(token));
+	}
+
+	/** Admit no more clients and retire every scope. */
+	close(): void {
+		this.#closed = true;
+		for (const scope of this.#byDigest.values()) scope.retire();
+		this.#byDigest = new Map();
+	}
+}