/** * Per-request plumbing shared by every auth-gateway route. * * A route module (`server.ts` chat/pi-native handlers, `routes/*.ts` for * judgments, images, speech, transcription, …) owns only its wire format: * parse the body, pick a model, call the pi-ai client, encode the reply. * Everything credential-shaped lives here so each route drives the same * broker-backed rotation policy and the same usage ledger. */ import { logger } from "@oh-my-pi-zen/pi-utils"; import { type ApiKeyResolver, createOAuthProvenance, NO_AUTH_SENTINEL, type ResolvedApiKey, resolveAfterRotation, } from "../auth-retry"; import type { AuthApiKeyOptions, AuthStorage } from "../auth-storage"; import * as AIError from "../error"; import { classifyGatewayError, type GatewayErrorClassification } from "../error/gateway"; import { getProviderDefinition } from "../registry"; import type { Api, FetchImpl, Model, Usage } from "../types"; import type { ClientUsageIdentity } from "../usage"; import type { AuthGatewayClientScope } from "./clients"; import type { AuthGatewayServerOptions } from "./types"; /** What a route knows about a request beyond the model id it names. */ export interface ModelResolveOptions { /** * The api the route's wire format speaks natively (`anthropic-messages` for * `/v1/messages`). A bare id served by several equally ranked providers * prefers a model on this api. */ api?: Api; /** * Models the caller may use. A bare id resolves to its best candidate this * admits; a refused `provider/id` resolves to nothing, never to another * provider's bare id spelled the same way. */ accepts?: (model: Model) => boolean; } /** Resolves a client-requested model id, `provider/id` or bare `id`, to the model a route dispatches to. */ export type ModelResolver = (modelId: string, options?: ModelResolveOptions) => Model | undefined; /** What the gateway's routes need, whatever transport carries the requests. */ export interface AuthGatewayRouteOptions { /** Source of credentials: broker-backed for `serve`, the CLI's own for `stdio`. */ storage: AuthStorage; /** * Resolve a client-requested model id to a pi-ai Model. Caller supplies * this from a ModelRegistry (lives in `coding-agent` to avoid an inverse * dependency in `pi-ai`). */ resolveModel: ModelResolver; /** Optional supplier for `/v1/models` listing. Returns the full model array. */ listModels?: () => Iterable>; /** Providers the host does not serve; `/v1/usage` and `/v1/credentials/check` leave their accounts out. */ excludeProviders?: ReadonlySet; /** 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; /** The HTTP server's options: the routes' plus its listener and inbound auth. */ export interface AuthGatewayBootOptions extends AuthGatewayServerOptions, AuthGatewayRouteOptions {} /** * The client's own session key, or `undefined` when it sent none. A blank key * counts as none: honouring it would collapse every caller that sends an empty * key into one shared credential-sticky, prefix-cache and provider-session * bucket. */ export function normalizeClientSessionKey(clientKey: string | undefined): string | undefined { return clientKey !== undefined && clientKey.trim().length > 0 ? clientKey : undefined; } /** * Stable identity of the account a request's credential belongs to. * * `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. 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. 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(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; } /** * Resolve the credential for one request from broker-backed storage. * * pi-ai clients never consult `AuthStorage`; the gateway resolves the bearer * and its OAuth identity together (refreshing through the broker when needed). * Keep this selection snapshot intact even if another request replaces the * stored token before dispatch. Storage failures map through * {@link classifyGatewayError}; a provider without any credential is a 401 * unless its catalog policy allows keyless requests. */ export async function resolveGatewayApiKey( opts: AuthGatewayCredentialOptions, model: Model, sessionId: string, signal: AbortSignal, peer: string, ): Promise { let apiKey: ResolvedApiKey | undefined; try { 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 }); return classified; } if (apiKey) return apiKey; if (getProviderDefinition(model.provider)?.allowsMissingApiKey) return { apiKey: NO_AUTH_SENTINEL }; return { status: 401, type: "authentication_error", message: `No credential available for provider ${model.provider}`, }; } /** * Step (c) for a gateway request: hand the failure to * {@link AuthStorage.limits.rotate}, the same policy local resolvers use. It * blocks a usage-limited credential until its reset, blocks only the requested * model after a model-entitlement denial, blocks an account-policy denial * without suspecting the credential, and invalidates hard auth failures. * The next `getWithCredential` result (sticky on the same `sessionId`) lets the * client retry the pre-emit failure; `undefined` surfaces the original error. */ async function refreshGatewayApiKeyAfterAuthError( storage: AuthStorage, model: Model, sessionId: string, provider: string, oldKey: string, error: unknown, signal: AbortSignal, format: string, peer: string, ): Promise { const rotation = await storage.limits.rotate(provider, sessionId, { error, modelId: model.id, baseUrl: model.baseUrl, apiKey: oldKey, signal, }); logger.debug("auth-gateway rotated credential after provider error", { format, provider, peer, modelId: model.id, switched: rotation.switched, afterSiblingWait: rotation.afterSiblingWait, error: error instanceof Error ? error.message : String(error), }); return resolveAfterRotation(rotation, error, () => storage.keys.getWithCredential(provider, sessionId, modelKeyOptions(model, signal)), ); } /** Model-scoped key options: usage ranking by model id, routing to accounts discovery saw serve it. */ function modelKeyOptions(model: Model, signal: AbortSignal): AuthApiKeyOptions { return { modelId: model.id, accountIds: model.accountAccess && Object.keys(model.accountAccess), signal }; } /** * Build the {@link ApiKeyResolver} handed to a pi-ai client for a gateway * request. Drives the central a/b/c auth-retry policy server-side: * * - initial resolve → the credential already resolved for this request. * - step (b) `!lastChance` → force-refresh the SAME session-sticky credential * (a peer/broker may have rotated its token out from under our cached copy). * - step (c) `lastChance` → {@link refreshGatewayApiKeyAfterAuthError} rotates * to a sibling through `limits.rotate`. * * `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. 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( opts: AuthGatewayCredentialOptions, model: Model, sessionId: string, initialKey: ResolvedApiKey, requestSignal: AbortSignal, format: string, peer: string, onResolvedKey?: (resolved: ResolvedApiKey) => void, ): ApiKeyResolver { const { storage } = opts; let lastKey = initialKey.apiKey; // One resolver serves many requests, and they fail out of order, so the // token a 401 rejected is looked up from the bearer that request sent. const provenance = createOAuthProvenance(); provenance.record(initialKey); return async ({ lastChance, error, signal, previousKey }) => { if (initialKey.apiKey === NO_AUTH_SENTINEL && initialKey.credentialId === undefined) { return error === undefined ? initialKey : undefined; } const sig = signal ?? requestSignal; // Only the bearer the failed request actually sent names the rejected // token; a caller that cannot report it keeps the previous behaviour. const rejectedAccessToken = provenance.accessFor(previousKey); if (error === undefined) { lastKey = initialKey.apiKey; return initialKey; } if (!lastChance) { 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, rejectedAccessToken, }, ); provenance.record(refreshed); lastKey = refreshed?.apiKey ?? lastKey; if (refreshed) onResolvedKey?.(refreshed); return refreshed; } const next = await refreshGatewayApiKeyAfterAuthError( storage, model, gatewayCredentialSessionId(opts, model, sessionId), model.provider, previousKey ?? lastKey, error, sig, format, peer, ); provenance.record(next); lastKey = next?.apiKey ?? lastKey; 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, 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 * by the remote store). Error/aborted turns still record — the provider * billed whatever tokens the partial turn consumed; zero-usage results * (pre-flight failures) are skipped. `at` defaults to now. */ export function recordGatewayUsage( storage: AuthStorage, model: Model, client: ClientUsageIdentity, usage: Usage, at?: number, ): void { if (usage.input + usage.output + usage.cacheRead + usage.cacheWrite === 0) return; storage.usage.observe({ provider: model.provider, model: model.id, at, usage: { input: usage.input, output: usage.output, cacheRead: usage.cacheRead, cacheWrite: usage.cacheWrite }, costUsd: usage.cost.total, client, }); } /** * An `AbortController` that follows the inbound request's abort signal. Routes * abort it themselves when the response body is cancelled mid-stream, which * `req.signal` alone does not observe. */ export function mirrorRequestAbort(req: Request): AbortController { const controller = new AbortController(); if (req.signal.aborted) { controller.abort(req.signal.reason); } else { req.signal.addEventListener("abort", () => controller.abort(req.signal.reason), { once: true }); } return controller; }