@linxiraos/pi-ai 1.2.0 → 1.3.0

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();
+	}
+}

package/src/auth-gateway/dispatch.ts

@@ -16,6 +16,7 @@ import { isUsageLimitOutcome } from "../error/rate-limit";
 import type { Api, FetchImpl, Model, Usage } from "../types";
 import type { ClientUsageIdentity } from "../usage";
 import { extractProviderRetryHint } from "../utils/retry-after";
+import type { AuthGatewayClientScope } from "./clients";
 import type { AuthGatewayServerOptions } from "./types";
 
 export type ModelResolver = (modelId: string) => Model<Api> | undefined;
@@ -36,8 +37,17 @@ export interface AuthGatewayRouteOptions {
 	excludeProviders?: ReadonlySet<string>;
 	/** Upstream transport for every provider call; defaults to global `fetch`. Test seam. */
 	fetch?: FetchImpl;
+	/**
+	 * The scoped client that sent this request, set per request by the HTTP
+	 * server: it narrows `resolveModel` / `listModels`, and every credential
+	 * lookup below resolves under its {@link AuthGatewayClientScope.credentialSessionId}.
+	 */
+	client?: AuthGatewayClientScope;
 }
 
+/** The route options a request's credential lookups read. */
+export type AuthGatewayCredentialOptions = Pick<AuthGatewayRouteOptions, "storage" | "client">;
+
 /** The HTTP server's options: the routes' plus its listener and inbound auth. */
 export interface AuthGatewayBootOptions extends AuthGatewayServerOptions, AuthGatewayRouteOptions {}
 
@@ -56,28 +66,28 @@ export function normalizeClientSessionKey(clientKey: string | undefined): string
  *
  * `markUsageLimitReached` and the auth-retry resolver switch a session to a
  * sibling credential, so the provider state retained for that session can
- * outlive the account that taught it. OAuth rows expose an account id / email
- * that survives token refresh — fingerprinting the bearer instead would look
+ * outlive the account that taught it. A stored credential keeps its durable
+ * row id across token refreshes — fingerprinting the bearer instead would look
  * like a rotation every time a token refreshes and discard the retained
- * lessons for nothing. Key-based rows fall back to a hash of the key, never
- * the key itself: this value is held for the lifetime of the entry.
+ * lessons for nothing. The id comes from the selection itself, not the
+ * session's current pin, which a concurrent request on the same session may
+ * have moved. Unstored keys fall back to a hash of the key, never the key
+ * itself: this value is held for the lifetime of the entry.
  */
-export function resolveGatewayAccount(
-	storage: AuthStorage,
-	provider: string,
-	sessionId: string,
-	apiKey: string,
-): string {
-	const identity = storage.oauth.identity(provider, sessionId);
-	if (identity) {
-		return `oauth:${JSON.stringify([
-			identity.accountId ?? "",
-			identity.email ?? "",
-			identity.projectId ?? "",
-			identity.orgId ?? "",
-		])}`;
-	}
-	return `key:${Bun.hash(apiKey).toString(36)}`;
+export function resolveGatewayAccount(resolved: ResolvedApiKey): string {
+	if (resolved.credentialId !== undefined) return `credential:${resolved.credentialId}`;
+	return `key:${Bun.hash(resolved.apiKey).toString(36)}`;
+}
+
+/** Who sent a request and which stored credential it started on, for the `auth-gateway request` log line. */
+export function gatewayRequestLogFields(
+	opts: AuthGatewayCredentialOptions,
+	resolved: ResolvedApiKey,
+): { client?: string; credentialId?: number } {
+	const fields: { client?: string; credentialId?: number } = {};
+	if (opts.client) fields.client = opts.client.name;
+	if (resolved.credentialId !== undefined) fields.credentialId = resolved.credentialId;
+	return fields;
 }
 
 /**
@@ -90,7 +100,7 @@ export function resolveGatewayAccount(
  * {@link classifyGatewayError}; a provider without any credential is a 401.
  */
 export async function resolveGatewayApiKey(
-	storage: AuthStorage,
+	opts: AuthGatewayCredentialOptions,
 	model: Model<Api>,
 	sessionId: string,
 	signal: AbortSignal,
@@ -98,7 +108,11 @@ export async function resolveGatewayApiKey(
 ): Promise<ResolvedApiKey | GatewayErrorClassification> {
 	let apiKey: ResolvedApiKey | undefined;
 	try {
-		apiKey = await storage.keys.getWithCredential(model.provider, sessionId, modelKeyOptions(model, signal));
+		apiKey = await opts.storage.keys.getWithCredential(
+			model.provider,
+			gatewayCredentialSessionId(opts, model, sessionId),
+			modelKeyOptions(model, signal),
+		);
 	} catch (error) {
 		const classified = classifyGatewayError(error);
 		logger.warn("auth-gateway getApiKey threw", { provider: model.provider, peer, error: classified.message });
@@ -197,20 +211,23 @@ function modelKeyOptions(model: Model<Api>, signal: AbortSignal): AuthApiKeyOpti
  * `lastKey` tracks the most recent bearer so the switch step invalidates the
  * credential that actually failed; a retry context's `previousKey` wins, since
  * concurrent operations sharing one resolver (split judgment chunks) each know
- * the bearer they sent. `onResolvedKey` observes every rotation; routes that
- * retain provider session state use it to re-key the account lease, one-shot
- * routes pass `undefined`.
+ * the bearer they sent. Every step resolves under the scoped client's
+ * credential session when `opts.client` binds the provider, so refresh,
+ * blocking and sibling rotation stay inside its accounts. `onResolvedKey`
+ * observes every rotation; routes that retain provider session state use it
+ * to re-key the account lease, one-shot routes pass `undefined`.
  */
 export function buildGatewayApiKeyResolver(
-	storage: AuthStorage,
+	opts: AuthGatewayCredentialOptions,
 	model: Model<Api>,
 	sessionId: string,
 	initialKey: ResolvedApiKey,
 	requestSignal: AbortSignal,
 	format: string,
 	peer: string,
-	onResolvedKey?: (apiKey: string) => void,
+	onResolvedKey?: (resolved: ResolvedApiKey) => void,
 ): ApiKeyResolver {
+	const { storage } = opts;
 	let lastKey = initialKey.apiKey;
 	return async ({ lastChance, error, signal, previousKey }) => {
 		const sig = signal ?? requestSignal;
@@ -219,19 +236,23 @@ export function buildGatewayApiKeyResolver(
 			return initialKey;
 		}
 		if (!lastChance) {
-			const refreshed = await storage.keys.getWithCredential(model.provider, sessionId, {
-				...modelKeyOptions(model, sig),
-				forceRefresh: true,
-				refreshReason: AIError.status(error) === 401 ? "auth-recovery" : undefined,
-			});
+			const refreshed = await storage.keys.getWithCredential(
+				model.provider,
+				gatewayCredentialSessionId(opts, model, sessionId),
+				{
+					...modelKeyOptions(model, sig),
+					forceRefresh: true,
+					refreshReason: AIError.status(error) === 401 ? "auth-recovery" : undefined,
+				},
+			);
 			lastKey = refreshed?.apiKey ?? lastKey;
-			if (refreshed) onResolvedKey?.(refreshed.apiKey);
+			if (refreshed) onResolvedKey?.(refreshed);
 			return refreshed;
 		}
 		const next = await refreshGatewayApiKeyAfterAuthError(
 			storage,
 			model,
-			sessionId,
+			gatewayCredentialSessionId(opts, model, sessionId),
 			model.provider,
 			previousKey ?? lastKey,
 			error,
@@ -240,11 +261,21 @@ export function buildGatewayApiKeyResolver(
 			peer,
 		);
 		lastKey = next?.apiKey ?? lastKey;
-		if (next) onResolvedKey?.(next.apiKey);
+		if (next) onResolvedKey?.(next);
 		return next;
 	};
 }
 
+/**
+ * The session a request's credential lookup resolves under: a scoped client's
+ * own restricted session for a provider it binds. Asked on every lookup, not
+ * once per request, so a retry after the client's restriction is lifted fails
+ * instead of resolving unrestricted.
+ */
+function gatewayCredentialSessionId(opts: AuthGatewayCredentialOptions, model: Model<Api>, sessionId: string): string {
+	return opts.client?.credentialSessionId(model.provider, sessionId) ?? sessionId;
+}
+
 /**
  * Attribute one settled upstream request to the originating client via the
  * broker's observed-usage channel (`AuthStorage.usage.observe`, batched