@oh-my-pi/pi-ai 15.1.2 → 15.1.3

package/CHANGELOG.md

@@ -2,6 +2,91 @@
 
 ## [Unreleased]
 
+## [15.1.3] - 2026-05-17
+### Breaking Changes
+
+- Changed `AuthBrokerClient.fetchSnapshot()` to return status-based results (`200` or `304`) instead of always returning a raw snapshot body, so callers now need to branch on `status`
+- Renamed public schema utilities in `@oh-my-pi/pi-ai/utils/schema` by replacing `sanitizeSchemaForGoogle`, `sanitizeSchemaForCCA`, `prepareSchemaForCCA`, and `sanitizeSchemaForMCP` with `normalizeSchemaForGoogle`, `normalizeSchemaForCCA`, and `normalizeSchemaForMCP`
+- Added MCP schema normalization via `normalizeSchemaForMCP` for compatibility checks
+- Removed the `StringEnum` helper from `@oh-my-pi/pi-ai/utils/schema`. Use `z.enum([...])` directly; Zod's emitted JSON Schema is already wire-compatible with Google and other providers.
+- Renamed the concrete SQLite credential store class from `AuthCredentialStore` to `SqliteAuthCredentialStore`. `AuthCredentialStore` is now the persistence interface implemented by both the SQLite store and the new `RemoteAuthCredentialStore`. Update `new AuthCredentialStore(db)` / `AuthCredentialStore.open(...)` call-sites to `SqliteAuthCredentialStore`; type-position uses (`store: AuthCredentialStore`) continue to work unchanged.
+
+### Added
+
+- Added `onAuthError` to `StreamOptions` and wired `streamSimple()` to retry once with a replacement API key when the first provider response is a 401 before any assistant events are emitted
+- Added generation-aware snapshot metadata (`generation`, `serverNowMs`, `refresher`, and `rotatesInMs`) to auth-broker snapshot responses to support client-side credential-rotation planning
+- Added `transport: "pi-native"` on `Model` and the matching `streamPiNative` client. When `model.transport === "pi-native"`, `streamSimple` short-circuits the per-provider dispatch and POSTs the canonical `Context` to the auth-gateway's `POST /v1/pi/stream` endpoint. The response is SSE-framed `AssistantMessageEvent`s parsed by `readSseJson` and pushed verbatim into the local `AssistantMessageEventStream` — no wire-format translation, no partial-stripping reconstruction. Used by containerized omp installs (robomp slots, swarm extension, etc.) to route every LLM call through a credential-holding sidecar; the slot itself never sees the real provider tokens. Server-controlled fields (`apiKey`, `signal`, `fetch`, lifecycle callbacks, the provider-session map) are stripped from the wire body — `apiKey` rides in the `Authorization` header as the gateway bearer.
+- Added `POST /v1/pi/stream` to the auth-gateway. Same auth + abort + model-resolution + codex-compat + prefix-cache plumbing as the foreign-wire routes; only the wire-format translation is skipped. Request body is `{ modelId, context, options?, stream? }` where `context` is the canonical pi-ai `Context` and `options` is `SimpleStreamOptions` with non-serializable fields stripped. Response is SSE-framed `AssistantMessageEvent` (terminated by `data: [DONE]`) when streaming, or `{ message: AssistantMessage }` JSON when `stream: false`.
+- Added Vertex AI authentication via Google Application Default Credentials from `GOOGLE_APPLICATION_CREDENTIALS`, `~/.config/gcloud/application_default_credentials.json`, or metadata server tokens, with token caching and refresh skew control via `GOOGLE_VERTEX_REFRESH_SKEW_MS`
+- Added support for Anthropic image message parts with `type: "url"` and `type: "file"` sources
+- Added `stopSequences` and `frequencyPenalty` to shared stream options and wired them through to OpenAI request translation
+- Added optional request cancellation support to auth-broker interactions by propagating `AbortSignal` into health, snapshot, usage, and refresh calls
+- Added `AuthStorage.setConfigApiKey` / `removeConfigApiKey` / `clearConfigApiKeys` for config-sourced per-provider bearers (e.g. `models.yml` `providers.<name>.apiKey`). The new tier sits between runtime `--api-key` and stored credentials in `getApiKey`/`peekApiKey` resolution, so a bearer pinned in config now beats the broker's OAuth access token. Also suppresses OAuth `account_uuid` attribution when active, since outbound auth is the explicit config bearer, not OAuth. `describeCredentialSource` reports `"config override (models.yml)"` for visibility.
+- Added per-model `additional_rate_limits` parsing to `openaiCodexUsageProvider`. The Codex `wham/usage` endpoint surfaces a separate `GPT-5.3-Codex-Spark` rate limit (`metered_feature: codex_bengalfox`) on Pro accounts; these now emit dedicated `openai-codex:spark:{primary,secondary}` `UsageLimit` entries with `scope.tier = "spark"`, mirroring how Anthropic exposes `anthropic:7d:sonnet` separately from the umbrella `anthropic:7d` bucket. The osx-widgets client already keyed spark detection off `limit.id.includes("spark")`; this populates that contract end-to-end.
+- Added `GET /v1/usage` to the auth-broker API to expose aggregated usage reports from `AuthStorage.fetchUsageReports`
+- Added auth-broker usage polling response handling that returns normalized usage reports plus generation timestamp for clients (5-min per-credential cache via `AuthStorage`)
+- Added the auth-broker subsystem (`@oh-my-pi/pi-ai/auth-broker`) for sharing OAuth credentials across machines without leaking refresh tokens.
+- `startAuthBroker(...)` boots a `Bun.serve` HTTP server exposing `GET /v1/healthz`, `GET /v1/snapshot`, `POST /v1/credential` (upsert), `POST /v1/credential/:id/refresh`, and `POST /v1/credential/:id/disable`.
+- `AuthBrokerClient` is the matching HTTP client used by remote clients.
+- `RemoteAuthCredentialStore` is a client-side `AuthCredentialStore` that mirrors a broker snapshot in memory; mutating methods (`replace*`, `upsert*`, `delete*ForProvider`) throw because writes are server-side only.
+- `AuthBrokerRefresher` is the background refresh loop that pre-refreshes credentials within `refreshSkewMs` and disables on definitive failure (`invalid_grant` / non-network 401-403).
+- Added `AuthStorage.exportSnapshot()`, `AuthStorage.upsertCredential(provider, credential)`, `AuthStorage.forceRefreshCredentialById(id)`, and `AuthStorage.disableCredentialById(id, cause)` public methods consumed by the auth-broker server.
+- Added `AuthStorageOptions.refreshOAuthCredential` override so a remote-store client can route every OAuth refresh through the broker instead of the local OAuth endpoint.
+- Added `REMOTE_REFRESH_SENTINEL` (`"__remote__"`) — the wire placeholder substituted for OAuth refresh tokens in broker snapshots; clients never see the real refresh token.
+- Exposed the OAuth provider catalog (`getOAuthProviders`, `OAuthProvider`, `OAuthProviderInfo`) and `refreshOAuthToken` through the package barrel so the coding-agent CLI can target them without reaching into `utils/oauth`.
+- Added the auth-gateway subsystem (`@oh-my-pi/pi-ai/auth-gateway`) — a forward-proxy that sits between unauthenticated clients (the macOS usage widget, llm-git, robomp containers, …) and the broker. Clients send standard provider-format requests; the gateway parses them into omp's canonical `Context`, dispatches through pi-ai's `streamSimple()`, and translates the canonical event stream back to the matching wire format. `Authorization` is injected server-side so access tokens never leave the gateway host. Wire surface:
+- `GET  /healthz` — unauth liveness.
+- `GET  /v1/usage` — aggregated provider usage; 5-min per-credential cache via `AuthStorage.fetchUsageReports`.
+- `GET  /v1/models` — model catalog (scoped to providers with credentials).
+- `POST /v1/chat/completions` — OpenAI chat-completions in/out.
+- `POST /v1/messages` — Anthropic messages in/out (text + thinking + tool_use blocks, SSE event taxonomy preserved).
+- `POST /v1/responses` — OpenAI Responses in/out (reasoning items + function_call output items, SSE pass-through).
+- Added exports from `@oh-my-pi/pi-ai/auth-gateway`: `startAuthGateway`, `AuthGatewayServerOptions`, `AuthGatewayBootOptions`, `AuthGatewayServerHandle`, `ModelResolver`, `DEFAULT_AUTH_GATEWAY_BIND`. Per-format `parseRequest` / `encodeResponse` / `encodeStream` triples are reachable via the `./providers/*` subpath as `openai-chat-server`, `anthropic-messages-server`, and `openai-responses-server`.
+- Added `listProvidersWithEnvKey()` to enumerate every provider with an env-var fallback (used by the new migrate command in coding-agent).
+
+### Changed
+
+- Changed `GET /v1/snapshot` to support generation-based polling with `If-None-Match` and `wait` for long-poll updates and to return `304` when no snapshot changes are available
+- Changed Bedrock credential resolution for streaming calls to prefer environment keys, AWS profile/SSO credentials, and IMDSv2 fallback when available
+- Changed auth-gateway parsing for OpenAI chat-completions and Responses to ignore unsupported SDK-only fields instead of rejecting requests
+- Changed auth-gateway protocol handling to include CORS headers on responses and support browser-origin requests
+- Changed prompt-cache handling to resolve cache keys from request metadata and headers and preserve them through protocol translation
+- Changed Anthropic messages parsing to forward request `metadata` through to downstream execution
+- Changed usage report caching to use a 5-minute per-credential TTL with jittered refresh timing to reduce usage endpoint rate-limit collisions
+- Changed usage polling failure handling so transient errors continue serving the last known report instead of returning null and dropping the credential from usage aggregates after cache expiry
+- Changed `sanitizeSchemaForGoogle` to normalize snake_case schema keys (such as `any_of` and `additional_properties`) to camelCase and auto-generate `propertyOrdering` for multi-property objects
+- Changed strict-mode sanitization to resolve `$ref` nodes with sibling keys by inlining and merging referenced local definitions
+- Changed strict-mode sanitization to flatten single-entry `allOf` nodes and remove the `allOf` wrapper
+- Changed Anthropic tool schema normalization to preserve supported metadata keywords such as `$ref`, `$defs`, `$schema`, `enum`, `const`, `default`, `title`, and `nullable` instead of stripping them
+- Changed string schema processing to retain only supported `format` values (`date-time`, `time`, `date`, `duration`, `email`, `hostname`, `uri`, `ipv4`, `ipv6`, `uuid`) and demote unsupported `format` values to `description` hints
+
+### Fixed
+
+- Fixed OAuth credential refresh flow so concurrent manual and background refreshes now share one in-flight attempt per credential, and `RemoteAuthCredentialStore` now re-synchronizes before using near-expiring OAuth credentials
+- Fixed stale-credential handling after auth failures by waiting for updated broker snapshots and refreshing suspect credentials through broker endpoints before continuing
+- Fixed Google Generative AI startup behavior to throw a clear API-key-required error when no key is configured
+- Fixed AWS Bedrock image message serialization to preserve base64 `source.bytes` payloads instead of decoding and rebuilding them
+- Fixed Google provider error handling to extract the API-reported `error.message` from JSON response bodies when available
+- Fixed `RemoteAuthCredentialStore.getUsageReport` to return the matching credential-specific usage report and coalesce parallel callers into one broker `/v1/usage` fetch
+- Fixed auth-broker credential upload validation to reject the remote refresh-token sentinel and prevent storing a non-refresh value
+- Fixed OpenAI Responses streaming output to emit `reasoning_summary_text` events and parse/send `summary_text` reasoning payloads
+- Fixed Anthropic stop-sequence handling by trimming requests to the API limit of four entries before forwarding
+- Fixed prompt caching behavior across protocol translations so cached-token usage is preserved when Anthropic and OpenAI requests are routed through each other
+- Fixed Claude usage fetching to retry transient `429` and `5xx` responses with exponential backoff, respecting `Retry-After` before returning failure
+- Fixed auth-gateway request translation to preserve OpenAI Responses string/system message content, reasoning replay payloads, completed item text in stream item-done events, Anthropic tool-result ordering, and OpenAI Chat/Responses cached-token usage totals
+- Fixed auth-gateway failure handling so unsupported request controls, upstream terminal errors, non-streaming aborts, and already-aborted client requests fail explicitly instead of being accepted, ignored, or encoded as successful HTTP 200 responses
+- Fixed Gemini CLI / Antigravity tool schema normalization to run the full Cloud Code Assist pipeline, matching shared Google schema handling for union/object merging and nullable extraction
+- Fixed stripped validation hints to be preserved as description spill text (`{key: value}` blocks) when `normalizeSchemaForGoogle` and `normalizeSchemaForCCA` drop unsupported schema keywords
+- Fixed `sanitizeSchemaForGoogle` to collapse nullability forms (`type:'null'` and null-bearing `anyOf` variants) into `nullable` while preserving remaining variants
+- Fixed `sanitizeSchemaForGoogle` to inline local `$defs` references instead of dropping `$ref`/`$defs` structure during Google schema sanitization
+- Fixed `normalizeAnthropicToolSchema` to handle self-referential schemas without infinite recursion
+- Fixed object schema normalization so explicit open-map declarations (`additionalProperties: true` and schema-valued `additionalProperties`) are preserved instead of being converted to closed objects
+- Fixed unsupported schema constraints on arrays and strings (`maxItems`, `uniqueItems`, `pattern`, `minLength`, `maxLength`, and `minItems` when greater than 1) by demoting them into `description` rather than dropping them
+
+### Security
+
+- Hardened auth-gateway bearer-token checks with constant-time comparison to avoid timing-side-channel leaks
+
 ## [15.1.2] - 2026-05-15
 ### Breaking Changes
 

package/README.md

@@ -89,7 +89,7 @@ npm install @oh-my-pi/pi-ai
 ## Quick Start
 
 ```typescript
-import { z, getModel, stream, complete, Context, Tool, StringEnum } from "@oh-my-pi/pi-ai";
+import { z, getModel, stream, complete, Context, Tool } from "@oh-my-pi/pi-ai";
 
 // Fully typed with auto-complete support for both providers and models
 const model = getModel("openai", "gpt-4o-mini");
@@ -221,7 +221,7 @@ Tools enable LLMs to interact with external systems. This library uses **Zod** s
 ### Defining Tools
 
 ```typescript
-import { z, Tool, StringEnum } from "@oh-my-pi/pi-ai";
+import { z, Tool } from "@oh-my-pi/pi-ai";
 
 // Define tool parameters with Zod
 const weatherTool: Tool = {
@@ -229,13 +229,10 @@ const weatherTool: Tool = {
 	description: "Get current weather for a location",
 	parameters: z.object({
 		location: z.string().describe("City name or coordinates"),
-		units: StringEnum(["celsius", "fahrenheit"], { default: "celsius" }),
+		units: z.enum(["celsius", "fahrenheit"]).default("celsius"),
 	}),
 };
 
-// Note: For Google API compatibility, use the StringEnum helper instead of z.enum alone
-// when you need wire-compatible { type: "string", enum: [...] } shapes.
-
 const bookMeetingTool: Tool = {
 	name: "book_meeting",
 	description: "Schedule a meeting",

package/dist/types/auth-broker/client.d.ts

@@ -0,0 +1,46 @@
+import type { AuthCredential } from "../auth-storage";
+import type { CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, UsageResponse } from "./types";
+export interface AuthBrokerClientOptions {
+    /** Base URL (e.g. `https://broker.tailnet:8765`). Trailing slashes are trimmed. */
+    url: string;
+    /** Bearer token used for everything except `healthz`. */
+    token: string;
+    /** Per-request timeout in milliseconds. Default 10s. */
+    timeoutMs?: number;
+    /** Retry connection errors this many times. Default 1. */
+    maxRetries?: number;
+    /** Override fetch (used in tests). Default global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+export declare class AuthBrokerError extends Error {
+    readonly status: number | undefined;
+    readonly body: string | undefined;
+    constructor(message: string, opts?: {
+        status?: number;
+        body?: string;
+        cause?: unknown;
+    });
+}
+export interface FetchSnapshotOptions {
+    ifGenerationGt?: number;
+    waitMs?: number;
+    signal?: AbortSignal;
+}
+export type FetchSnapshotResult = {
+    status: 200;
+    snapshot: SnapshotResponse;
+    generation: number;
+} | {
+    status: 304;
+    generation: number;
+};
+export declare class AuthBrokerClient {
+    #private;
+    constructor(opts: AuthBrokerClientOptions);
+    healthz(signal?: AbortSignal): Promise<HealthzResponse>;
+    fetchSnapshot(opts?: FetchSnapshotOptions): Promise<FetchSnapshotResult>;
+    fetchUsage(signal?: AbortSignal): Promise<UsageResponse>;
+    refreshCredential(id: number, signal?: AbortSignal): Promise<CredentialRefreshResponse>;
+    disableCredential(id: number, cause: string, signal?: AbortSignal): Promise<CredentialDisableResponse>;
+    uploadCredential(provider: string, credential: AuthCredential, signal?: AbortSignal): Promise<CredentialUploadResponse>;
+}

package/dist/types/auth-broker/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./client";
+export * from "./refresher";
+export * from "./remote-store";
+export * from "./server";
+export * from "./types";

package/dist/types/auth-broker/refresher.d.ts

@@ -0,0 +1,25 @@
+import type { AuthStorage } from "../auth-storage";
+export interface AuthBrokerRefresherOptions {
+    storage: AuthStorage;
+    /** Refresh credentials expiring within this window. Default 5 min. */
+    refreshSkewMs?: number;
+    /** Loop cadence. Default 60s. */
+    refreshIntervalMs?: number;
+    /** Override clock (tests). */
+    now?: () => number;
+}
+export interface AuthBrokerRefresherSchedule {
+    enabled: boolean;
+    intervalMs: number;
+    skewMs: number;
+    nextSweepAt: number;
+}
+export declare class AuthBrokerRefresher {
+    #private;
+    constructor(opts: AuthBrokerRefresherOptions);
+    start(): void;
+    stop(): void;
+    getSchedule(): AuthBrokerRefresherSchedule;
+    /** Run one sweep. Exposed for tests. */
+    tick(): Promise<void>;
+}

package/dist/types/auth-broker/remote-store.d.ts

@@ -0,0 +1,71 @@
+import { type AuthCredential, type AuthCredentialStore, type OAuthCredential, type StoredAuthCredential } from "../auth-storage";
+import type { Provider } from "../types";
+import type { UsageReport } from "../usage";
+import type { OAuthCredentials } from "../utils/oauth/types";
+import type { AuthBrokerClient } from "./client";
+import type { SnapshotResponse } from "./types";
+export interface RemoteAuthCredentialStoreOptions {
+    client: AuthBrokerClient;
+    /**
+     * Initial snapshot. When omitted, callers must call
+     * {@link RemoteAuthCredentialStore.refreshSnapshot} before the first read.
+     */
+    initialSnapshot?: SnapshotResponse;
+}
+export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
+    #private;
+    constructor(opts: RemoteAuthCredentialStoreOptions);
+    get client(): AuthBrokerClient;
+    get snapshot(): SnapshotResponse;
+    /** Re-hydrate the in-memory snapshot from the broker. */
+    refreshSnapshot(): Promise<SnapshotResponse>;
+    listAuthCredentials(provider?: string): StoredAuthCredential[];
+    /**
+     * In-memory update from a successful refresh through the broker. AuthStorage
+     * calls this after `#replaceCredentialAt`; the broker already persisted the
+     * authoritative row, so we just mirror it.
+     */
+    updateAuthCredential(id: number, credential: AuthCredential): void;
+    deleteAuthCredential(id: number, disabledCause: string): void;
+    tryDisableAuthCredentialIfMatches(id: number, _expectedData: string, disabledCause: string): boolean;
+    waitForFreshSnapshot(maxWaitMs: number, opts?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    prepareForRequest(credentialId: number, opts?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    markCredentialSuspect(credentialId: number, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    replaceAuthCredentialsForProvider(_provider: string, _credentials: AuthCredential[]): StoredAuthCredential[];
+    upsertAuthCredentialForProvider(_provider: string, _credential: AuthCredential): StoredAuthCredential[];
+    deleteAuthCredentialsForProvider(_provider: string, _disabledCause: string): void;
+    getCache(key: string): string | null;
+    setCache(key: string, value: string, expiresAtSec: number): void;
+    cleanExpiredCache(): void;
+    /**
+     * Store-level hook consumed by `AuthStorage` — routes refresh through the
+     * broker so the actual refresh token never leaves the broker host. Returns
+     * the broker-redacted credential with {@link REMOTE_REFRESH_SENTINEL} in
+     * the `refresh` slot.
+     */
+    refreshOAuthCredential(_provider: Provider, credentialId: number, _credential: OAuthCredential, signal?: AbortSignal): Promise<OAuthCredentials>;
+    /**
+     * Store-level hook consumed by `AuthStorage.fetchUsageReports()` — proxies
+     * to the broker's `/v1/usage` endpoint. The broker's egress IP isn't
+     * rate-limited by Anthropic's per-IP `/usage` cap the way a heavy
+     * residential laptop is, so all credentials surface every cycle.
+     */
+    fetchUsageReports(signal?: AbortSignal): Promise<UsageReport[] | null>;
+    /**
+     * Per-credential usage hook consumed by `AuthStorage.#getUsageReport`. Pulls
+     * the aggregate broker `/v1/usage` once and serves all callers from the
+     * same response (coalesced + cached), then matches the credential to a
+     * report by provider + identity (accountId / email / projectId).
+     *
+     * The broker already aggregates with its own 30s TTL on the server side; our
+     * 15s client TTL is below that so we usually re-use the broker's cache too.
+     */
+    getUsageReport(provider: Provider, credential: OAuthCredential, signal?: AbortSignal): Promise<UsageReport | null>;
+    close(): void;
+}

package/dist/types/auth-broker/server.d.ts

@@ -0,0 +1,26 @@
+import type { AuthStorage } from "../auth-storage";
+export interface AuthBrokerServerOptions {
+    /** Underlying credential storage (wraps the local SQLite store on the broker). */
+    storage: AuthStorage;
+    /** Listen address; accepts `host:port` or just `port`. */
+    bind?: string;
+    /** Accept any of these bearer tokens. Empty disables auth (loopback only). */
+    bearerTokens: string[];
+    /** Broker version string surfaced on `/v1/healthz`. */
+    version?: string;
+    /** Refresh credentials expiring within this window. Default 5 min. */
+    refreshSkewMs?: number;
+    /** Background refresh cadence. Default 60s. */
+    refreshIntervalMs?: number;
+    /** Disable the background refresher (e.g. for tests). */
+    disableRefresher?: boolean;
+}
+export interface AuthBrokerServerHandle {
+    /** Bound URL (`http://host:port`). */
+    url: string;
+    port: number;
+    hostname: string;
+    close(): Promise<void>;
+}
+/** Boot the broker. Caller owns lifecycle; `handle.close()` to stop. */
+export declare function startAuthBroker(opts: AuthBrokerServerOptions): AuthBrokerServerHandle;

package/dist/types/auth-broker/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Wire types shared between the auth-broker server and clients.
+ *
+ * The broker holds OAuth refresh tokens and exposes a redacted snapshot;
+ * clients use `access` tokens directly and call back to the broker when a
+ * credential expires or a 401 surfaces on a supposedly-fresh credential.
+ */
+import type { AuthCredential, AuthCredentialSnapshot, AuthCredentialSnapshotEntry } from "../auth-storage";
+import type { UsageReport } from "../usage";
+/** GET /v1/healthz response body. */
+export interface HealthzResponse {
+    ok: boolean;
+    version?: string;
+}
+export interface RefresherSchedule {
+    enabled: boolean;
+    intervalMs: number;
+    skewMs: number;
+    nextSweepInMs: number;
+}
+export type SnapshotEntry = AuthCredentialSnapshotEntry & {
+    rotatesInMs: number | null;
+};
+/** GET /v1/snapshot response body. */
+export interface SnapshotResponse extends Omit<AuthCredentialSnapshot, "credentials"> {
+    serverNowMs: number;
+    refresher: RefresherSchedule;
+    credentials: SnapshotEntry[];
+}
+/** GET /v1/usage response body — matches the local `AuthStorage.fetchUsageReports` shape. */
+export interface UsageResponse {
+    generatedAt: number;
+    reports: UsageReport[];
+}
+/** POST /v1/credential/:id/refresh response body. */
+export interface CredentialRefreshResponse {
+    entry: AuthCredentialSnapshotEntry;
+}
+/** POST /v1/credential/:id/disable request body. */
+export interface CredentialDisableRequest {
+    cause: string;
+}
+/** POST /v1/credential/:id/disable response body. */
+export interface CredentialDisableResponse {
+    ok: boolean;
+}
+/**
+ * POST /v1/credential request body. The OAuth `refresh` must be the *real*
+ * refresh token (not the sentinel) — the broker is the canonical writer.
+ */
+export interface CredentialUploadRequest {
+    provider: string;
+    credential: AuthCredential;
+}
+/** POST /v1/credential response body — redacted snapshot of the provider's rows after upsert. */
+export interface CredentialUploadResponse {
+    entries: AuthCredentialSnapshotEntry[];
+}
+/**
+ * Default bearer-protected route prefix. The broker exposes `/v1/healthz`
+ * unauthenticated for liveness probes; everything else requires a bearer.
+ */
+export declare const AUTH_BROKER_API_PREFIX = "/v1";
+/** Default port when none is configured. Loopback-only, no external exposure. */
+export declare const DEFAULT_AUTH_BROKER_BIND = "127.0.0.1:8765";
+/** Default broker→provider refresh skew. Refresh credentials this close to expiry. */
+export declare const DEFAULT_REFRESH_SKEW_MS: number;
+/** Default broker refresh-loop cadence. */
+export declare const DEFAULT_REFRESH_INTERVAL_MS = 60000;

package/dist/types/auth-broker/wire-schemas.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Zod schemas for the auth-broker wire protocol.
+ *
+ * Shared between the server (validates inbound request bodies) and the client
+ * (validates responses from the broker). Schemas mirror the TypeScript types
+ * in `./types.ts` 1:1; the types remain the source of truth for static typing,
+ * and `z.infer<typeof Schema>` is asserted-compatible with them where possible.
+ *
+ * Schemas use `.strict()` on objects with a closed set of fields so unknown
+ * keys are rejected — the previous implementation used a hand-rolled
+ * `hasOnlyFields` allowlist for the same effect.
+ */
+import * as z from "zod/v4";
+/** Real OAuth credential (broker-side) — refresh token is the actual upstream value. */
+export declare const oauthCredentialSchema: z.ZodObject<{
+    type: z.ZodLiteral<"oauth">;
+    refresh: z.ZodString;
+    access: z.ZodString;
+    expires: z.ZodNumber;
+    enterpriseUrl: z.ZodOptional<z.ZodString>;
+    projectId: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    accountId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** OAuth credential as it appears in broker snapshots — refresh replaced with sentinel. */
+export declare const remoteOauthCredentialSchema: z.ZodObject<{
+    type: z.ZodLiteral<"oauth">;
+    access: z.ZodString;
+    expires: z.ZodNumber;
+    enterpriseUrl: z.ZodOptional<z.ZodString>;
+    projectId: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    accountId: z.ZodOptional<z.ZodString>;
+    refresh: z.ZodLiteral<"__remote__">;
+}, z.core.$strict>;
+export declare const apiKeyCredentialSchema: z.ZodObject<{
+    type: z.ZodLiteral<"api_key">;
+    key: z.ZodString;
+}, z.core.$strict>;
+/** Discriminated union accepted on POST /v1/credential (writes). */
+export declare const writableAuthCredentialSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"oauth">;
+    refresh: z.ZodString;
+    access: z.ZodString;
+    expires: z.ZodNumber;
+    enterpriseUrl: z.ZodOptional<z.ZodString>;
+    projectId: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    accountId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"api_key">;
+    key: z.ZodString;
+}, z.core.$strict>], "type">;
+/** Discriminated union returned in snapshots (refresh is sentinel for OAuth). */
+export declare const snapshotCredentialSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"oauth">;
+    access: z.ZodString;
+    expires: z.ZodNumber;
+    enterpriseUrl: z.ZodOptional<z.ZodString>;
+    projectId: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    accountId: z.ZodOptional<z.ZodString>;
+    refresh: z.ZodLiteral<"__remote__">;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"api_key">;
+    key: z.ZodString;
+}, z.core.$strict>], "type">;
+export declare const credentialSnapshotEntrySchema: z.ZodObject<{
+    id: z.ZodNumber;
+    provider: z.ZodString;
+    credential: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"oauth">;
+        access: z.ZodString;
+        expires: z.ZodNumber;
+        enterpriseUrl: z.ZodOptional<z.ZodString>;
+        projectId: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        accountId: z.ZodOptional<z.ZodString>;
+        refresh: z.ZodLiteral<"__remote__">;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"api_key">;
+        key: z.ZodString;
+    }, z.core.$strict>], "type">;
+    identityKey: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const snapshotEntrySchema: z.ZodObject<{
+    id: z.ZodNumber;
+    provider: z.ZodString;
+    credential: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"oauth">;
+        access: z.ZodString;
+        expires: z.ZodNumber;
+        enterpriseUrl: z.ZodOptional<z.ZodString>;
+        projectId: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        accountId: z.ZodOptional<z.ZodString>;
+        refresh: z.ZodLiteral<"__remote__">;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"api_key">;
+        key: z.ZodString;
+    }, z.core.$strict>], "type">;
+    identityKey: z.ZodNullable<z.ZodString>;
+    rotatesInMs: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const refresherScheduleSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    intervalMs: z.ZodNumber;
+    skewMs: z.ZodNumber;
+    nextSweepInMs: z.ZodNumber;
+}, z.core.$strict>;
+export declare const snapshotResponseSchema: z.ZodObject<{
+    generation: z.ZodNumber;
+    generatedAt: z.ZodNumber;
+    serverNowMs: z.ZodNumber;
+    refresher: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        intervalMs: z.ZodNumber;
+        skewMs: z.ZodNumber;
+        nextSweepInMs: z.ZodNumber;
+    }, z.core.$strict>;
+    credentials: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        provider: z.ZodString;
+        credential: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"oauth">;
+            access: z.ZodString;
+            expires: z.ZodNumber;
+            enterpriseUrl: z.ZodOptional<z.ZodString>;
+            projectId: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+            accountId: z.ZodOptional<z.ZodString>;
+            refresh: z.ZodLiteral<"__remote__">;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"api_key">;
+            key: z.ZodString;
+        }, z.core.$strict>], "type">;
+        identityKey: z.ZodNullable<z.ZodString>;
+        rotatesInMs: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const healthzResponseSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Broker `/v1/usage` response. Reports are full {@link UsageReport}s minus the
+ * heavy provider-specific `raw` field (the server strips it before send) — we
+ * keep `raw` optional in the underlying schema so a misconfigured broker that
+ * forgot to strip still validates.
+ */
+export declare const usageResponseSchema: z.ZodObject<{
+    generatedAt: z.ZodNumber;
+    reports: z.ZodArray<z.ZodObject<{
+        provider: z.ZodString;
+        fetchedAt: z.ZodNumber;
+        limits: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            scope: z.ZodObject<{
+                provider: z.ZodString;
+                accountId: z.ZodOptional<z.ZodString>;
+                projectId: z.ZodOptional<z.ZodString>;
+                orgId: z.ZodOptional<z.ZodString>;
+                modelId: z.ZodOptional<z.ZodString>;
+                tier: z.ZodOptional<z.ZodString>;
+                windowId: z.ZodOptional<z.ZodString>;
+                shared: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>;
+            window: z.ZodOptional<z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                durationMs: z.ZodOptional<z.ZodNumber>;
+                resetsAt: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            amount: z.ZodObject<{
+                used: z.ZodOptional<z.ZodNumber>;
+                limit: z.ZodOptional<z.ZodNumber>;
+                remaining: z.ZodOptional<z.ZodNumber>;
+                usedFraction: z.ZodOptional<z.ZodNumber>;
+                remainingFraction: z.ZodOptional<z.ZodNumber>;
+                unit: z.ZodEnum<{
+                    bytes: "bytes";
+                    minutes: "minutes";
+                    percent: "percent";
+                    requests: "requests";
+                    tokens: "tokens";
+                    unknown: "unknown";
+                    usd: "usd";
+                }>;
+            }, z.core.$strip>;
+            status: z.ZodOptional<z.ZodEnum<{
+                exhausted: "exhausted";
+                ok: "ok";
+                unknown: "unknown";
+                warning: "warning";
+            }>>;
+            notes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        raw: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+export declare const credentialRefreshResponseSchema: z.ZodObject<{
+    entry: z.ZodObject<{
+        id: z.ZodNumber;
+        provider: z.ZodString;
+        credential: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"oauth">;
+            access: z.ZodString;
+            expires: z.ZodNumber;
+            enterpriseUrl: z.ZodOptional<z.ZodString>;
+            projectId: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+            accountId: z.ZodOptional<z.ZodString>;
+            refresh: z.ZodLiteral<"__remote__">;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"api_key">;
+            key: z.ZodString;
+        }, z.core.$strict>], "type">;
+        identityKey: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const credentialDisableRequestSchema: z.ZodObject<{
+    cause: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const credentialDisableResponseSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const credentialUploadRequestSchema: z.ZodObject<{
+    provider: z.ZodString;
+    credential: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"oauth">;
+        refresh: z.ZodString;
+        access: z.ZodString;
+        expires: z.ZodNumber;
+        enterpriseUrl: z.ZodOptional<z.ZodString>;
+        projectId: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        accountId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"api_key">;
+        key: z.ZodString;
+    }, z.core.$strict>], "type">;
+}, z.core.$strict>;
+export declare const credentialUploadResponseSchema: z.ZodObject<{
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        provider: z.ZodString;
+        credential: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"oauth">;
+            access: z.ZodString;
+            expires: z.ZodNumber;
+            enterpriseUrl: z.ZodOptional<z.ZodString>;
+            projectId: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+            accountId: z.ZodOptional<z.ZodString>;
+            refresh: z.ZodLiteral<"__remote__">;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"api_key">;
+            key: z.ZodString;
+        }, z.core.$strict>], "type">;
+        identityKey: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;