@ap3x/ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AP3X
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @ap3x/ai
+
+One typed interface over many LLM providers: streaming, tool calling, and a shared model catalog, so provider choice stays a config value rather than a rewrite.
+
+Part of [AP3X](https://github.com/AP3X-Dev/AP3X) — a TypeScript multi-agent framework.
+
+## Install
+
+```bash
+npm install @ap3x/ai
+```
+
+## What's inside
+
+- **Providers** — OpenAI (completions + responses), Anthropic, Google, Amazon Bedrock, Azure OpenAI, GitHub Copilot, OpenRouter, Vercel AI Gateway, Mistral, and more.
+- **Streaming** — incremental text and tool-call deltas with partial-JSON recovery.
+- **Tool calling** — TypeBox schemas in, validated and coerced arguments out, with provider-specific tool-call id rules handled in one place.
+- **Auth** — API keys from the environment, plus OAuth device/browser flows for subscription backends.
+- **Model catalog** — `MODELS` / `getModel` with generated per-provider catalogs and a runtime refresh seam.
+- **Transport** — retry, timeout, and proxy handling shared across providers.
+
+## Documentation
+
+See the [AP3X repository](https://github.com/AP3X-Dev/AP3X) for architecture notes, the full package map, and examples.
+
+## License
+
+MIT

package/dist/api-registry.d.ts

@@ -0,0 +1,23 @@
+import type { Api, ApiProvider, AssistantMessageEventStream, Context, Model, SimpleStreamOptions, StreamOptions } from "./types";
+export type { ApiProvider } from "./types";
+/** Non-generic full-stream signature stored in the registry. */
+export type ApiStreamFunction = (model: Model<Api>, context: Context, options?: StreamOptions) => AssistantMessageEventStream;
+/** Non-generic simple-stream signature stored in the registry. */
+export type ApiStreamSimpleFunction = (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+export interface ApiProviderInternal {
+    api: Api;
+    stream: ApiStreamFunction;
+    streamSimple: ApiStreamSimpleFunction;
+}
+/**
+ * Register a provider under its `api` id. Stored functions are wrapped with an
+ * api-mismatch guard. An optional `sourceId` tags the registration so a batch
+ * of registrations can later be removed together.
+ */
+export declare function registerApiProvider<TApi extends Api, TOptions extends StreamOptions>(provider: ApiProvider<TApi, TOptions>, sourceId?: string): void;
+export declare function getApiProvider(api: Api): ApiProviderInternal | undefined;
+export declare function getApiProviders(): ApiProviderInternal[];
+/** Remove every provider tagged with the given `sourceId`. */
+export declare function unregisterApiProviders(sourceId: string): void;
+export declare function clearApiProviders(): void;
+//# sourceMappingURL=api-registry.d.ts.map

package/dist/api-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-registry.d.ts","sourceRoot":"","sources":["../src/api-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,GAAG,EACH,WAAW,EACX,2BAA2B,EAC3B,OAAO,EACP,KAAK,EACL,mBAAmB,EAEnB,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,gEAAgE;AAChE,MAAM,MAAM,iBAAiB,GAAG,CAC9B,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EACjB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,aAAa,KACpB,2BAA2B,CAAC;AAEjC,kEAAkE;AAClE,MAAM,MAAM,uBAAuB,GAAG,CACpC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EACjB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,mBAAmB,KAC1B,2BAA2B,CAAC;AAEjC,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,GAAG,CAAC;IACT,MAAM,EAAE,iBAAiB,CAAC;IAC1B,YAAY,EAAE,uBAAuB,CAAC;CACvC;AAmCD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,SAAS,GAAG,EAAE,QAAQ,SAAS,aAAa,EAClF,QAAQ,EAAE,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,EACrC,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI,CASN;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,mBAAmB,GAAG,SAAS,CAExE;AAED,wBAAgB,eAAe,IAAI,mBAAmB,EAAE,CAEvD;AAED,8DAA8D;AAC9D,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAM7D;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/dist/auth/config-dir.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Resolve the AP3X config directory. Precedence: the `AP3X_CONFIG_DIR` env
+ * override, then `~/.ap3x`. Node builtins are imported lazily so browser/bundler
+ * builds don't pull them in unless the resolver is actually called.
+ */
+/** Synchronous node-fs accessor. Throws when builtins haven't been loaded yet. */
+declare function nodeFs(): {
+    mkdirSync: typeof import("node:fs").mkdirSync;
+    readFileSync: typeof import("node:fs").readFileSync;
+    writeFileSync: typeof import("node:fs").writeFileSync;
+    renameSync: typeof import("node:fs").renameSync;
+    rmSync: typeof import("node:fs").rmSync;
+    existsSync: typeof import("node:fs").existsSync;
+};
+/** Load the node builtins the auth layer needs. Safe to call repeatedly. */
+export declare function ensureNodeBuiltins(): Promise<void>;
+/**
+ * Resolve the AP3X config directory path. `AP3X_CONFIG_DIR` overrides the
+ * default `~/.ap3x`. Requires {@link ensureNodeBuiltins} to have run.
+ */
+export declare function resolveConfigDir(): string;
+/** Join a path segment under the resolved config dir. */
+export declare function configPath(...segments: string[]): string;
+export { nodeFs };
+//# sourceMappingURL=config-dir.d.ts.map

package/dist/auth/config-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-dir.d.ts","sourceRoot":"","sources":["../../src/auth/config-dir.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAgCH,kFAAkF;AAClF,iBAAS,MAAM,IAAI;IACjB,SAAS,EAAE,cAAc,SAAS,EAAE,SAAS,CAAC;IAC9C,YAAY,EAAE,cAAc,SAAS,EAAE,YAAY,CAAC;IACpD,aAAa,EAAE,cAAc,SAAS,EAAE,aAAa,CAAC;IACtD,UAAU,EAAE,cAAc,SAAS,EAAE,UAAU,CAAC;IAChD,MAAM,EAAE,cAAc,SAAS,EAAE,MAAM,CAAC;IACxC,UAAU,EAAE,cAAc,SAAS,EAAE,UAAU,CAAC;CACjD,CAmBA;AAED,4EAA4E;AAC5E,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAGxD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAOzC;AAED,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAGxD;AAED,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/auth/github-copilot.d.ts

@@ -0,0 +1,74 @@
+import type { AuthStorage } from "./storage";
+import type { FetchLike, OAuthProviderConfig, OAuthToken, ResolvedAuth } from "./types";
+/**
+ * The client-identity headers the Copilot service expects on both the token
+ * exchange and every subsequent API call. They advertise a Copilot-enabled
+ * editor/plugin and a registered integration id — vendor protocol constants.
+ */
+export declare const COPILOT_EDITOR_HEADERS: Record<string, string>;
+/** The API version pin Copilot expects via `X-GitHub-Api-Version`. */
+export declare const COPILOT_API_VERSION = "2026-06-01";
+/**
+ * Full static header set for an authenticated Copilot API request: the bearer
+ * plus the editor-identity headers and the API-version pin.
+ */
+export declare function copilotApiHeaders(copilotBearer: string): Record<string, string>;
+/**
+ * The Copilot token-exchange endpoint for a GitHub domain. For the default
+ * `github.com` this is `https://api.github.com/copilot_internal/v2/token`; an
+ * enterprise domain (e.g. `acme.ghe.com`) resolves to its `api.` host.
+ */
+export declare function copilotTokenEndpoint(enterpriseDomain?: string): string;
+/**
+ * Derive the Copilot API base URL embedded in a minted bearer. The bearer is a
+ * `;`-delimited list of `key=value` pairs; `proxy-ep` names the proxy host
+ * (e.g. `proxy.individual.githubcopilot.com`), whose `api.` sibling is the base
+ * URL. Returns `null` when the token carries no `proxy-ep`.
+ */
+export declare function getCopilotBaseUrlFromToken(token: string): string | null;
+/**
+ * Resolve the Copilot API base URL, preferring the endpoint encoded in the
+ * bearer, then an enterprise host, then the individual-account default.
+ */
+export declare function resolveCopilotBaseUrl(bearer?: string, enterpriseDomain?: string): string;
+/** Result of the GitHub -> Copilot token exchange. */
+export interface CopilotTokenExchange {
+    /** The short-lived Copilot API bearer. */
+    token: string;
+    /** Epoch milliseconds at which the bearer expires. */
+    expiresAt: number;
+}
+/**
+ * Exchange a durable GitHub OAuth token for a short-lived Copilot API bearer.
+ * GitHub authenticates the request with the GitHub token as a Bearer and
+ * returns `{ token, expires_at }` (expiry in epoch seconds).
+ */
+export declare function exchangeGitHubCopilotToken(githubToken: string, options?: {
+    fetchImpl?: FetchLike;
+    enterpriseDomain?: string;
+    signal?: AbortSignal;
+}): Promise<CopilotTokenExchange>;
+export interface ResolveCopilotAuthOptions {
+    /** Storage used to cache the minted Copilot bearer to its expiry. */
+    storage: AuthStorage;
+    /** Provider OAuth config supplying the refresh-skew window. */
+    config: Pick<OAuthProviderConfig, "refreshSkewSeconds">;
+    /** Clock, injectable for tests. */
+    now: () => number;
+    /** Injectable fetch for the token exchange (no real network in tests). */
+    fetchImpl?: FetchLike;
+    /** Optional enterprise domain the account is homed on. */
+    enterpriseDomain?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Resolve usable Copilot auth from a stored GitHub Copilot credential: mint (or
+ * reuse a cached) Copilot bearer, then return the bearer plus the required
+ * client headers and the per-account base URL.
+ *
+ * The minted bearer is cached back to `storage` keyed to the provider, with the
+ * GitHub token preserved in `refreshToken`, so a second resolution within the
+ * bearer's lifetime reuses it instead of re-exchanging.
+ */
+export declare function resolveGitHubCopilotAuth(stored: OAuthToken, options: ResolveCopilotAuthOptions): Promise<ResolvedAuth>;
+//# sourceMappingURL=github-copilot.d.ts.map

package/dist/auth/github-copilot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-copilot.d.ts","sourceRoot":"","sources":["../../src/auth/github-copilot.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAiBxF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAKzD,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAKhD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM/E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAGtE;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOvE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAQxF;AAED,sDAAsD;AACtD,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;CACnB;AAWD;;;;GAIG;AACH,wBAAsB,0BAA0B,CAC9C,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;CACjB,GACL,OAAO,CAAC,oBAAoB,CAAC,CA8B/B;AA6BD,MAAM,WAAW,yBAAyB;IACxC,qEAAqE;IACrE,OAAO,EAAE,WAAW,CAAC;IACrB,+DAA+D;IAC/D,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,oBAAoB,CAAC,CAAC;IACxD,mCAAmC;IACnC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,YAAY,CAAC,CA4BvB"}

package/dist/auth/index.d.ts

@@ -0,0 +1,10 @@
+export { configPath, ensureNodeBuiltins, resolveConfigDir } from "./config-dir";
+export { base64UrlEncode, deriveCodeChallenge, generateCodeVerifier, generatePkcePair, generateState, type PkcePair, } from "./pkce";
+export { decodeJwtPayload, extractChatgptAccountId, resolveChatgptAccountId } from "./jwt";
+export { AuthStorage } from "./storage";
+export { clientIdEnvVar, getOAuthProviderConfig, hasOAuthConfig, isPlaceholderClientId, type OAuthProviderConfigOverrides, oauthProviders, } from "./providers";
+export { type AuthorizeUrlResult, buildAuthorizationUrl, type DevicePollOptions, exchangeAuthorizationCode, isTokenExpired, parseAuthorizationInput, pollDeviceToken, refreshAccessToken, startDeviceAuthorization, } from "./oauth-flow";
+export { COPILOT_API_VERSION, COPILOT_EDITOR_HEADERS, copilotApiHeaders, copilotTokenEndpoint, type CopilotTokenExchange, exchangeGitHubCopilotToken, getCopilotBaseUrlFromToken, type ResolveCopilotAuthOptions, resolveCopilotBaseUrl, resolveGitHubCopilotAuth, } from "./github-copilot";
+export { getApiKeyAndHeaders, type ResolveAuthOptions } from "./unified";
+export type { FetchLike, OAuthGrantType, OAuthProviderConfig, OAuthToken, ResolvedAuth, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhF,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,KAAK,QAAQ,GACd,MAAM,QAAQ,CAAC;AAGhB,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,OAAO,CAAC;AAG3F,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAGxC,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,cAAc,EACd,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,KAAK,kBAAkB,EACvB,qBAAqB,EACrB,KAAK,iBAAiB,EACtB,yBAAyB,EACzB,cAAc,EACd,uBAAuB,EACvB,eAAe,EACf,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,0BAA0B,EAC1B,0BAA0B,EAC1B,KAAK,yBAAyB,EAC9B,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAGzE,YAAY,EACV,SAAS,EACT,cAAc,EACd,mBAAmB,EACnB,UAAU,EACV,YAAY,GACb,MAAM,SAAS,CAAC"}

package/dist/auth/jwt.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Minimal JWT payload decoding for OAuth id_tokens.
+ *
+ * NO signature verification is performed: the id_token is received directly from
+ * the provider's token endpoint over TLS, so its authenticity is already
+ * established by the transport. We only need to read claims out of the payload.
+ */
+/**
+ * Decode a JWT's payload (the middle, dot-delimited segment) into a plain
+ * object. Total function: returns `undefined` on any malformed input rather than
+ * throwing.
+ */
+export declare function decodeJwtPayload(jwt: string): Record<string, unknown> | undefined;
+/**
+ * Extract the ChatGPT account id from an OIDC id_token. The canonical location
+ * is the namespaced auth claim `"https://api.openai.com/auth".chatgpt_account_id`;
+ * fall back to a top-level `chatgpt_account_id`, then `account_id`.
+ */
+export declare function extractChatgptAccountId(idToken: string): string | undefined;
+/**
+ * Resolve the ChatGPT account id from a token set, preferring the ACCESS token —
+ * the Codex access token is itself a JWT carrying the `chatgpt_account_id` auth
+ * claim — and only then falling back to the id_token. Reading solely the
+ * id_token silently drops the required `chatgpt-account-id` header whenever the
+ * provider returns the claim on the access token but omits the id_token (e.g. on
+ * refresh). Returns `undefined` only when neither token carries the id.
+ */
+export declare function resolveChatgptAccountId(tokens: {
+    accessToken?: string;
+    idToken?: string;
+}): string | undefined;
+//# sourceMappingURL=jwt.d.ts.map

package/dist/auth/jwt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../src/auth/jwt.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAejF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiB3E;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,GAAG,SAAS,CAUrB"}

package/dist/auth/oauth-flow.d.ts

@@ -0,0 +1,84 @@
+import { type PkcePair } from "./pkce";
+import type { FetchLike, OAuthProviderConfig, OAuthToken } from "./types";
+/** Device-authorization response shape. */
+interface DeviceCodeResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    expires_in: number;
+    interval?: number;
+}
+export interface AuthorizeUrlResult {
+    url: string;
+    pkce: PkcePair;
+    state: string;
+}
+/**
+ * Build the authorization URL for the authorization-code + PKCE flow, returning
+ * the URL plus the PKCE pair and `state` the caller must retain to complete the
+ * exchange.
+ */
+export declare function buildAuthorizationUrl(config: OAuthProviderConfig): AuthorizeUrlResult;
+/**
+ * Parse a manually pasted OAuth authorization value into a `{ code, state }`
+ * pair. Accepts a full redirect URL, a bare code, a `code#state` fragment, or a
+ * `code=...&state=...` query fragment — the remote-browser paste fallback used
+ * when a loopback callback cannot be reached (headless / remote sign-in). Total
+ * function: an empty/whitespace input yields `{}`.
+ */
+export declare function parseAuthorizationInput(input: string): {
+    code?: string;
+    state?: string;
+};
+/**
+ * Exchange an authorization code (with the matching PKCE verifier) for a token
+ * set at the provider's token endpoint.
+ */
+export declare function exchangeAuthorizationCode(config: OAuthProviderConfig, params: {
+    code: string;
+    verifier: string;
+}, options?: {
+    fetchImpl?: FetchLike;
+    now?: () => number;
+    signal?: AbortSignal;
+}): Promise<OAuthToken>;
+/** Begin a device-authorization flow; returns the device + user codes. */
+export declare function startDeviceAuthorization(config: OAuthProviderConfig, options?: {
+    fetchImpl?: FetchLike;
+    signal?: AbortSignal;
+}): Promise<DeviceCodeResponse>;
+export interface DevicePollOptions {
+    fetchImpl?: FetchLike;
+    now?: () => number;
+    signal?: AbortSignal;
+    /** Sleep helper (ms). Default: setTimeout. Injectable for tests. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Override the poll interval (seconds). Defaults to device response value. */
+    intervalSeconds?: number;
+    /** Optional callback fired before each poll attempt. */
+    onPoll?: (attempt: number) => void;
+}
+/**
+ * Poll the token endpoint for a device-code grant until it resolves, the user
+ * denies, or it expires. Honors `authorization_pending` (keep polling),
+ * `slow_down` (back off), and terminal errors.
+ */
+export declare function pollDeviceToken(config: OAuthProviderConfig, device: DeviceCodeResponse, options?: DevicePollOptions): Promise<OAuthToken>;
+/**
+ * Exchange a refresh token for a new access token at the token endpoint.
+ *
+ * `previous` lets the caller carry forward identity fields (refresh token,
+ * account id, id_token) that a refresh response commonly omits, so a refreshed
+ * token stays fully usable.
+ */
+export declare function refreshAccessToken(config: OAuthProviderConfig, refreshToken: string, options?: {
+    fetchImpl?: FetchLike;
+    now?: () => number;
+    signal?: AbortSignal;
+    previous?: Pick<OAuthToken, "accountId" | "idToken">;
+}): Promise<OAuthToken>;
+/** Whether a token is expired or within the configured refresh skew window. */
+export declare function isTokenExpired(token: OAuthToken, config: Pick<OAuthProviderConfig, "refreshSkewSeconds">, now?: number): boolean;
+export {};
+//# sourceMappingURL=oauth-flow.d.ts.map

package/dist/auth/oauth-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-flow.d.ts","sourceRoot":"","sources":["../../src/auth/oauth-flow.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,QAAQ,EAAmC,MAAM,QAAQ,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAoB1E,2CAA2C;AAC3C,UAAU,kBAAkB;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA6ED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,mBAAmB,GAAG,kBAAkB,CAkBrF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CA4BxF;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAC1C,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,SAAS,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAChF,OAAO,CAAC,UAAU,CAAC,CAiBrB;AAED,0EAA0E;AAC1E,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,mBAAmB,EAC3B,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAC5D,OAAO,CAAC,kBAAkB,CAAC,CAY7B;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,oEAAoE;IACpE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAWD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,kBAAkB,EAC1B,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,UAAU,CAAC,CAwErB;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,mBAAmB,EAC3B,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,GAAG,SAAS,CAAC,CAAC;CACjD,GACL,OAAO,CAAC,UAAU,CAAC,CAqBrB;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAC5B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,oBAAoB,CAAC,EACvD,GAAG,GAAE,MAAmB,GACvB,OAAO,CAIT"}

package/dist/auth/pkce.d.ts

@@ -0,0 +1,20 @@
+/** A PKCE code_verifier / code_challenge pair (S256). */
+export interface PkcePair {
+    verifier: string;
+    challenge: string;
+    method: "S256";
+}
+/** RFC 7636 base64url: base64 with `+/` → `-_` and no `=` padding. */
+export declare function base64UrlEncode(bytes: Buffer): string;
+/**
+ * Generate a PKCE code_verifier: a high-entropy, URL-safe string. RFC 7636
+ * requires 43–128 chars; 32 random bytes base64url-encoded yields 43 chars.
+ */
+export declare function generateCodeVerifier(byteLength?: number): string;
+/** Derive the S256 code_challenge from a verifier: base64url(SHA-256(verifier)). */
+export declare function deriveCodeChallenge(verifier: string): string;
+/** Generate a complete S256 PKCE pair. */
+export declare function generatePkcePair(byteLength?: number): PkcePair;
+/** Generate an opaque, URL-safe `state` value for CSRF protection. */
+export declare function generateState(byteLength?: number): string;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/auth/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../src/auth/pkce.ts"],"names":[],"mappings":"AAEA,yDAAyD;AACzD,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,SAAK,GAAG,MAAM,CAE5D;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,0CAA0C;AAC1C,wBAAgB,gBAAgB,CAAC,UAAU,SAAK,GAAG,QAAQ,CAG1D;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,UAAU,SAAK,GAAG,MAAM,CAErD"}

package/dist/auth/providers.d.ts

@@ -0,0 +1,33 @@
+import type { Provider } from "../types";
+import type { OAuthProviderConfig } from "./types";
+/** The env var that overrides a provider's client id. */
+export declare function clientIdEnvVar(provider: Provider): string;
+/**
+ * Whether `clientId` is an AP3X-invented, non-functional placeholder for this
+ * provider (the `ap3x-<provider>-oauth` default) — as opposed to a vendor
+ * protocol value or a user-configured id. Callers use this to turn a raw
+ * vendor error into an actionable "set the env var" message; a real configured
+ * id never matches.
+ */
+export declare function isPlaceholderClientId(provider: Provider, clientId: string): boolean;
+export interface OAuthProviderConfigOverrides {
+    clientId?: string;
+    authorizationUrl?: string;
+    deviceAuthorizationUrl?: string;
+    tokenUrl?: string;
+    scopes?: string[];
+    redirectUri?: string;
+    refreshSkewSeconds?: number;
+}
+/** Provider slugs AP3X ships an OAuth config for. */
+export declare function oauthProviders(): Provider[];
+/** Whether a provider has a built-in OAuth config. */
+export declare function hasOAuthConfig(provider: Provider): boolean;
+/**
+ * Build the effective OAuth config for a provider, resolving the client id from
+ * (in precedence order) the explicit override, the
+ * `AP3X_<PROVIDER>_OAUTH_CLIENT_ID` env var, then the AP3X placeholder default.
+ * Returns `undefined` for providers without an OAuth config.
+ */
+export declare function getOAuthProviderConfig(provider: Provider, overrides?: OAuthProviderConfigOverrides): OAuthProviderConfig | undefined;
+//# sourceMappingURL=providers.d.ts.map

package/dist/auth/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/auth/providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AA8BnD,yDAAyD;AACzD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAKzD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEnF;AAyED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,qDAAqD;AACrD,wBAAgB,cAAc,IAAI,QAAQ,EAAE,CAE3C;AAED,sDAAsD;AACtD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,QAAQ,EAClB,SAAS,GAAE,4BAAiC,GAC3C,mBAAmB,GAAG,SAAS,CAejC"}

package/dist/auth/storage.d.ts

@@ -0,0 +1,55 @@
+import type { Provider } from "../types";
+import type { OAuthToken } from "./types";
+/**
+ * Persists OAuth tokens per provider under the AP3X config dir
+ * (`~/.ap3x/oauth.json` by default; `AP3X_CONFIG_DIR` overrides). All methods
+ * are async because they lazily load node builtins.
+ *
+ * An in-memory backing store can be injected for tests / non-node runtimes.
+ */
+export declare class AuthStorage {
+    /** Optional in-memory store; when set, the filesystem is never touched. */
+    private readonly memory;
+    /**
+     * Per-key serialization chains. A key's tasks run strictly one-at-a-time so a
+     * read→modify→write is never interleaved: {@link modify} serializes per
+     * provider (single-flight refresh) and the low-level file mutations serialize
+     * on {@link AuthStorage.FILE_LOCK} so the shared `readAll`/`writeAll` cycle is
+     * atomic across providers (no last-write-wins clobber).
+     */
+    private readonly chains;
+    /** Reserved chain key that serializes every whole-file mutation. */
+    private static readonly FILE_LOCK;
+    constructor(options?: {
+        inMemory?: boolean;
+    });
+    /**
+     * Run `task` after every previously enqueued task for `key` has settled,
+     * serializing access. The returned promise mirrors `task`'s own outcome; the
+     * stored chain tail swallows results so one failure never wedges the queue.
+     */
+    private enqueue;
+    /** A purely in-memory storage, for tests and ephemeral sessions. */
+    static inMemory(): AuthStorage;
+    private get path();
+    private readAll;
+    private writeAll;
+    /** Read the token set for a provider, or `undefined` when none is stored. */
+    read(provider: Provider): Promise<OAuthToken | undefined>;
+    /** Persist (replacing) the token set for a provider. */
+    write(provider: Provider, token: OAuthToken): Promise<void>;
+    /**
+     * Serialize a read-modify-write of one provider's token. The mutator receives
+     * the token re-read *under the lock* and returns the token to persist and
+     * return; returning the same instance (or `undefined`) skips the write. This
+     * enables a double-checked refresh: N concurrent expired resolves queue on the
+     * provider, exactly one refreshes + persists, and every later waiter re-reads
+     * the freshly refreshed token and reuses it — no duplicate refresh, no clobber.
+     */
+    modify(provider: Provider, mutator: (current: OAuthToken | undefined) => Promise<OAuthToken | undefined> | OAuthToken | undefined): Promise<OAuthToken | undefined>;
+    /** Remove a provider's stored token. */
+    clear(provider: Provider): Promise<void>;
+    /** Remove every stored token. */
+    clearAll(): Promise<void>;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/auth/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/auth/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAO1C;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAE7D;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAE9D,oEAAoE;IACpE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAwB;gBAE7C,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO;IAIhD;;;;OAIG;IACH,OAAO,CAAC,OAAO;IAaf,oEAAoE;IACpE,MAAM,CAAC,QAAQ,IAAI,WAAW;IAI9B,OAAO,KAAK,IAAI,GAEf;YAEa,OAAO;YAkBP,QAAQ;IAsBtB,6EAA6E;IACvE,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAM/D,wDAAwD;IAClD,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAQjE;;;;;;;OAOG;IACG,MAAM,CACV,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,CACP,OAAO,EAAE,UAAU,GAAG,SAAS,KAC5B,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,GAAG,UAAU,GAAG,SAAS,GAC5D,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAWlC,wCAAwC;IAClC,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAc9C,iCAAiC;IAC3B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAWhC"}

package/dist/auth/types.d.ts

@@ -0,0 +1,88 @@
+import type { Provider } from "../types";
+/** Injectable fetch so tests can mock token / device endpoints. */
+export type FetchLike = (input: string | URL, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    statusText?: string;
+    json: () => Promise<unknown>;
+    text: () => Promise<string>;
+}>;
+/** How a provider negotiates an OAuth grant. */
+export type OAuthGrantType = "authorization-code" | "device-code";
+/**
+ * Static, per-provider OAuth configuration. Client IDs are AP3X-owned
+ * placeholders by default and MUST be overridable via settings/env — AP3X never
+ * ships another vendor's registered client id.
+ */
+export interface OAuthProviderConfig {
+    /** Provider slug this config authenticates (e.g. "anthropic"). */
+    provider: Provider;
+    /** Which grant flow this provider uses. */
+    grantType: OAuthGrantType;
+    /** Authorization endpoint (authorization-code flow). */
+    authorizationUrl?: string;
+    /** Device-authorization endpoint (device-code flow). */
+    deviceAuthorizationUrl?: string;
+    /** Token endpoint (both flows). */
+    tokenUrl: string;
+    /** OAuth client id. AP3X placeholder default; override via env/settings. */
+    clientId: string;
+    /** Requested scopes. */
+    scopes: string[];
+    /** Redirect URI for the authorization-code flow. */
+    redirectUri?: string;
+    /** Treat a token as expired this many seconds before its real expiry. */
+    refreshSkewSeconds?: number;
+    /**
+     * Wire format for POSTs to the token / device endpoints (code exchange,
+     * refresh, device authorization). Most OAuth token endpoints accept
+     * `application/x-www-form-urlencoded` (the default when omitted); a few —
+     * notably Anthropic's `platform.claude.com` token endpoint — require a JSON
+     * body and reject form-encoding. Per-provider so the flow logic stays generic.
+     */
+    tokenRequestFormat?: "form" | "json";
+    /**
+     * Extra provider-specific query params appended verbatim to the authorization
+     * URL (e.g. ChatGPT's `id_token_add_organizations`, `codex_cli_simplified_flow`,
+     * `originator`). Kept generic so the flow logic stays provider-agnostic.
+     */
+    extraAuthParams?: Record<string, string>;
+}
+/** A persisted OAuth token set for one provider. */
+export interface OAuthToken {
+    accessToken: string;
+    refreshToken?: string;
+    /** Epoch milliseconds at which `accessToken` expires; omitted = never. */
+    expiresAt?: number;
+    tokenType?: string;
+    scope?: string;
+    /**
+     * Account identifier carried alongside the token (e.g. ChatGPT's
+     * `chatgpt_account_id`, decoded from the id_token). Sent as a per-provider
+     * header by the unified auth seam when present.
+     */
+    accountId?: string;
+    /** The raw OIDC id_token JWT, retained for account-id extraction / debugging. */
+    idToken?: string;
+}
+/** Result of resolving auth for a model: a single header set to send. */
+export interface ResolvedAuth {
+    /** Authentication mode that produced the headers. */
+    mode: "oauth" | "api-key" | "none";
+    /** Headers to merge onto the provider request. */
+    headers: Record<string, string>;
+    /** The raw bearer/api-key value, exposed for providers that build their own headers. */
+    apiKey?: string;
+    /**
+     * Per-account base URL derived during resolution, when the credential encodes
+     * one (e.g. a GitHub Copilot bearer names its API proxy endpoint). Callers may
+     * apply it over the model's catalog default; absent means use the default.
+     */
+    baseUrl?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/auth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,mEAAmE;AACnE,MAAM,MAAM,SAAS,GAAG,CACtB,KAAK,EAAE,MAAM,GAAG,GAAG,EACnB,IAAI,CAAC,EAAE;IACL,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KACE,OAAO,CAAC;IACX,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7B,CAAC,CAAC;AAEH,gDAAgD;AAChD,MAAM,MAAM,cAAc,GAAG,oBAAoB,GAAG,aAAa,CAAC;AAElE;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,QAAQ,EAAE,QAAQ,CAAC;IACnB,2CAA2C;IAC3C,SAAS,EAAE,cAAc,CAAC;IAC1B,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACnC,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/auth/unified.d.ts

@@ -0,0 +1,29 @@
+import type { Api, Model } from "../types";
+import { type OAuthProviderConfigOverrides } from "./providers";
+import { AuthStorage } from "./storage";
+import type { FetchLike, ResolvedAuth } from "./types";
+export interface ResolveAuthOptions {
+    /** Storage backing OAuth tokens. Defaults to the on-disk AuthStorage. */
+    storage?: AuthStorage;
+    /** Injectable fetch for the refresh call. */
+    fetchImpl?: FetchLike;
+    /** Clock, injectable for tests. */
+    now?: () => number;
+    /** Per-provider OAuth config overrides (client id, endpoints, scopes). */
+    oauthOverrides?: OAuthProviderConfigOverrides;
+    /** An explicit API key (e.g. from StreamOptions) takes precedence over env. */
+    apiKey?: string;
+    signal?: AbortSignal;
+}
+/**
+ * The unified auth seam (#38): given a model, return the headers a provider call
+ * should send. Resolution order per provider:
+ *   1. A stored OAuth token (auto-refreshed if expired/near-expiry).
+ *   2. An explicit API key, then an environment API key.
+ *   3. `none` when nothing is configured.
+ *
+ * OAuth refresh goes through the injectable `fetchImpl` and persists the new
+ * token via `storage`, so a provider call transparently receives a fresh bearer.
+ */
+export declare function getApiKeyAndHeaders<TApi extends Api>(model: Model<TApi>, options?: ResolveAuthOptions): Promise<ResolvedAuth>;
+//# sourceMappingURL=unified.d.ts.map

package/dist/auth/unified.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified.d.ts","sourceRoot":"","sources":["../../src/auth/unified.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAY,MAAM,UAAU,CAAC;AAGrD,OAAO,EAAE,KAAK,4BAA4B,EAA0B,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAc,YAAY,EAAE,MAAM,SAAS,CAAC;AAqBnE,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,mCAAmC;IACnC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,4BAA4B,CAAC;IAC9C,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,SAAS,GAAG,EACxD,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAClB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,YAAY,CAAC,CA8DvB"}

package/dist/env-api-keys.d.ts

@@ -0,0 +1,16 @@
+import type { KnownProvider } from "./types";
+/**
+ * Return the env var names actually set for the provider, or `undefined` when
+ * none are. Reports only explicit API-key variables (not ambient credentials).
+ */
+export declare function findEnvKeys(provider: KnownProvider): string[] | undefined;
+export declare function findEnvKeys(provider: string): string[] | undefined;
+/**
+ * Resolve an API key for a provider from the environment. Returns the value of
+ * the first set env var, or the sentinel `"<authenticated>"` for providers that
+ * authenticate via ambient credentials (Vertex ADC, AWS for Bedrock).
+ * Providers that require OAuth tokens are not resolved here.
+ */
+export declare function getEnvApiKey(provider: KnownProvider): string | undefined;
+export declare function getEnvApiKey(provider: string): string | undefined;
+//# sourceMappingURL=env-api-keys.d.ts.map

package/dist/env-api-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-api-keys.d.ts","sourceRoot":"","sources":["../src/env-api-keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AA6F7C;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;AAC3E,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;AAQpE;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAAC;AAC1E,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC"}