@vib-rato/ai 0.16.0

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

@@ -0,0 +1,1074 @@
+/**
+ * Credential storage for API keys and OAuth tokens.
+ * Handles loading, saving, refreshing credentials, and usage tracking.
+ *
+ * This module defines:
+ * - `AuthCredentialStore` interface: persistence abstraction (SQLite, remote vault, …)
+ * - `AuthStorage` class: credential management with round-robin, usage limits, OAuth refresh
+ * - `SqliteAuthCredentialStore`: concrete SQLite-backed implementation
+ */
+import { Database } from "bun:sqlite";
+import type { Provider } from "./types";
+import type { CredentialRankingStrategy, UsageLogger, UsageProvider, UsageReport } from "./usage";
+import type { OAuthController, OAuthCredentials, OAuthLoginOptions, OAuthProviderId } from "./utils/oauth/types";
+export type ApiKeyCredential = {
+    type: "api_key";
+    key: string;
+};
+/**
+ * Extracts the bearer token from the structured API-key form used by OAuth
+ * providers that need to carry token metadata alongside the access token.
+ */
+export declare function extractStructuredApiKeyToken(apiKey: string): string | undefined;
+export interface MCPOAuthBinding {
+    /** Exact HTTP(S) origin of the MCP resource endpoint. */
+    resourceOrigin: string;
+    /** Exact canonical HTTP(S) token endpoint used to create and refresh the credential. */
+    tokenEndpoint: string;
+}
+export declare function resolveMCPOAuthResourceOrigin(value: string): string | undefined;
+export declare function resolveMCPOAuthTokenEndpoint(value: string): string | undefined;
+export declare function isCanonicalMCPOAuthBinding(binding: MCPOAuthBinding): boolean;
+export declare function assertCanonicalMCPOAuthBinding(binding: MCPOAuthBinding | undefined): asserts binding is MCPOAuthBinding;
+export type OAuthCredential = {
+    type: "oauth";
+    /** Present only for credentials created by runtime MCP OAuth. */
+    mcpBinding?: MCPOAuthBinding;
+} & OAuthCredentials;
+export type AuthCredential = ApiKeyCredential | OAuthCredential;
+export interface MCPOAuthRefreshClient {
+    clientId?: string;
+    clientSecret?: string;
+}
+export type AuthCredentialEntry = AuthCredential | AuthCredential[];
+export type AuthStorageData = Record<string, AuthCredentialEntry>;
+/**
+ * Serialized representation of AuthStorage for passing to subagent workers.
+ * Contains only the essential credential data, not runtime state.
+ */
+export interface SerializedAuthStorage {
+    credentials: Record<string, Array<{
+        id: number;
+        type: "api_key" | "oauth";
+        data: Record<string, unknown>;
+    }>>;
+    runtimeOverrides?: Record<string, string>;
+    dbPath?: string;
+}
+/**
+ * Auth credential with database row ID for updates/deletes.
+ * Wraps AuthCredential with storage metadata.
+ */
+export interface StoredAuthCredential {
+    id: number;
+    provider: string;
+    credential: AuthCredential;
+    disabledCause: string | null;
+    /** Monotonic local row revision used by optimistic hard-removal actions. */
+    revision?: number;
+}
+/**
+ * Payload-free inventory projection used by account-management and presentation
+ * surfaces. This deliberately has no credential/token fields; `listAuthCredentials`
+ * remains the active full-fidelity selection contract.
+ */
+export interface CredentialInventoryRecord {
+    id: number;
+    provider: string;
+    credentialKind: "oauth" | "api_key";
+    identityLabel: string | null;
+    accountId?: string;
+    email?: string;
+    projectId?: string;
+    disabled: boolean;
+    disabledCause: string | null;
+}
+/** Safe usage observation supplied by a remote store's presentation cache. */
+export interface CachedUsagePresentation {
+    credentialId: number;
+    provider: string;
+    inventoryGeneration: number;
+    identityDigest: string;
+    usage: SafeUsageReport;
+    fetchedAt: number;
+    freshUntil: number;
+    retainUntil: number;
+}
+/** Opaque local action target for an all-or-nothing OAuth hard removal. */
+export interface CredentialRemovalTarget {
+    id: number;
+    provider: string;
+    expectedRevision: number;
+}
+export type AuthCredentialHardRemovalResult = {
+    kind: "removed";
+    ids: readonly number[];
+} | {
+    kind: "conflict";
+    currentIds: readonly number[];
+};
+/** Usage report projection safe to cross a presentation boundary. */
+export type SafeUsageReport = Omit<UsageReport, "raw">;
+export type CachedUsageFreshness = "fresh" | "stale-last-good";
+export interface CachedUsageReport {
+    report: SafeUsageReport;
+    fetchedAt: number;
+    freshUntil: number;
+    retainUntil: number;
+    freshness: CachedUsageFreshness;
+}
+export type CachedCredentialHealthStatus = "ok" | "failed" | "unverifiable" | "unknown";
+export interface CachedCredentialHealth {
+    status: CachedCredentialHealthStatus;
+    reason: string | null;
+    checkedAt?: number;
+    retainUntil?: number;
+}
+/** Safe result from an explicit API-key probe whose key bytes are invocation-only. */
+export interface ApiKeyCredentialCheckResult {
+    provider: string;
+    type: "api_key";
+    ok: boolean | null;
+    reason?: string;
+    report?: SafeUsageReport;
+}
+/** Typed failure raised when an OAuth-only selector cannot be applied. */
+export type OAuthCredentialSelectorFailureReason = "api-key-row" | "api-key-provider" | "override-active" | "not-found" | "disabled" | "ambiguous" | "gateway-managed";
+export declare class OAuthCredentialSelectorError extends Error {
+    readonly reason: OAuthCredentialSelectorFailureReason;
+    readonly provider: string;
+    readonly selector: AuthCredentialSelector;
+    readonly candidateIds: readonly number[];
+    constructor(reason: OAuthCredentialSelectorFailureReason, provider: string, selector: AuthCredentialSelector, message: string, candidateIds?: readonly number[]);
+}
+export interface OAuthPinTarget {
+    credentialId: number;
+    canonicalSelector: AuthCredentialSelector;
+}
+/**
+ * Per-credential health record returned by {@link AuthStorage.checkCredentials}.
+ *
+ * Use this to identify which credential in a multi-account pool is causing
+ * auth errors. `ok` is tri-state:
+ *
+ * - `true` — credential authenticated against the provider's auth-verifying
+ *   probe (today: the usage endpoint). For OAuth this also exercises refresh
+ *   when the access token was expired.
+ * - `false` — the probe rejected the credential (401/403/refresh failure/etc).
+ *   `reason` carries the upstream error string.
+ * - `null` — no probe is configured for this provider (or the configured
+ *   probe doesn't support this credential type). The credential's auth
+ *   status is unverifiable from here.
+ */
+export interface CredentialHealthResult {
+    /** Database row id (matches {@link StoredAuthCredential.id}). */
+    id: number;
+    provider: string;
+    type: AuthCredential["type"];
+    /** OAuth email if known on the stored credential or surfaced by the probe. */
+    email?: string;
+    /** OAuth account id / org id if known. */
+    accountId?: string;
+    /** `true` when the refresh token lives on a remote broker (sentinel was present). */
+    remoteRefresh?: true;
+    ok: boolean | null;
+    /** Failure / unverifiable reason; absent when `ok === true`. */
+    reason?: string;
+    report?: SafeUsageReport;
+}
+export interface CheckCredentialsOptions {
+    signal?: AbortSignal;
+    provider?: string;
+    /** Per-credential probe timeout (ms). Defaults to the configured usage request timeout. */
+    timeoutMs?: number;
+    /** Provider → base URL override, same shape as {@link AuthStorage.fetchUsageReports}. */
+    baseUrlResolver?: (provider: Provider) => string | undefined;
+}
+/** Options for the explicit, invocation-only API-key probe. */
+export interface ApiKeyCredentialCheckOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    baseUrl?: string;
+}
+/**
+ * Sentinel value placed in OAuth `refresh` fields when a credential is shared
+ * via {@link AuthStorage.exportSnapshot}. Refresh tokens never leave the broker;
+ * clients must call back to refresh.
+ */
+export declare const REMOTE_REFRESH_SENTINEL: "__remote__";
+export type RemoteRefreshSentinel = typeof REMOTE_REFRESH_SENTINEL;
+/** OAuth credential with refresh token replaced by the broker sentinel. */
+export type RemoteOAuthCredential = Omit<OAuthCredential, "refresh"> & {
+    refresh: RemoteRefreshSentinel;
+};
+/** Discriminated credential payload as published by the broker. */
+export type SnapshotCredential = ApiKeyCredential | RemoteOAuthCredential;
+export interface AuthCredentialSnapshotEntry {
+    id: number;
+    provider: string;
+    credential: SnapshotCredential;
+    identityKey: string | null;
+    revision?: number;
+}
+export type AuthCredentialIfAbsentReason = "inserted" | "updated-existing" | "skipped-existing" | "skipped-existing-runtime" | "skipped-existing-config" | "skipped-existing-env" | "skipped-existing-fallback" | "skipped-invalid";
+export interface AuthCredentialIfAbsentResult {
+    inserted: boolean;
+    reason: AuthCredentialIfAbsentReason;
+    provider: string;
+    entries: StoredAuthCredential[];
+}
+export interface AuthCredentialIfAbsentSnapshotResult {
+    inserted: boolean;
+    reason: AuthCredentialIfAbsentReason;
+    provider: string;
+    entries: AuthCredentialSnapshotEntry[];
+}
+/**
+ * Wire-shaped snapshot exported by {@link AuthStorage.exportSnapshot} and
+ * served by the auth-broker server on `GET /v1/snapshot`.
+ */
+export interface AuthCredentialSnapshot {
+    generation: number;
+    generatedAt: number;
+    credentials: AuthCredentialSnapshotEntry[];
+}
+/**
+ * Persistence abstraction consumed by {@link AuthStorage}.
+ *
+ * Concrete implementations:
+ * - {@link SqliteAuthCredentialStore} — local SQLite-backed store (default).
+ * - `RemoteAuthCredentialStore` from `./auth-broker` — client-side snapshot of
+ *   a remote broker; mutating methods (`replace*`, `upsert*`, `delete*ForProvider`)
+ *   throw because login flows route through the broker, not the client.
+ */
+export type OAuthRefreshLease = {
+    credentialId: number;
+    owner: string;
+    tokenFingerprint: string;
+};
+export type OAuthRefreshLeaseClaim = {
+    kind: "claimed";
+    credential: OAuthCredential;
+    lease: OAuthRefreshLease;
+} | {
+    kind: "adopted";
+    credential: OAuthCredential;
+} | {
+    kind: "busy";
+    expiresAt: number;
+} | {
+    kind: "missing";
+};
+/**
+ * Store-owned ticket that orders a provider admission against remote
+ * credential snapshot application. The ticket is intentionally released at
+ * provider admission, not response completion.
+ */
+export interface CredentialDispatchTicket {
+    release(): void;
+}
+export interface AuthCredentialStore {
+    close(): void;
+    refreshSnapshot?(signal?: AbortSignal): Promise<unknown>;
+    onSnapshotChanged?(listener: () => void): () => void;
+    /** Order provider admission with remote snapshot authority application. */
+    acquireCredentialDispatchTicket?(provider: Provider, signal?: AbortSignal): Promise<CredentialDispatchTicket>;
+    listAuthCredentials(provider?: string): StoredAuthCredential[];
+    /** Payload-free account inventory; active and soft-disabled rows are included. */
+    listCredentialInventory?(provider?: string): CredentialInventoryRecord[];
+    /** Local opaque removal targets; remote stores may omit this capability. */
+    listCredentialRemovalTargets?(provider?: string): CredentialRemovalTarget[];
+    /** Transactional local hard removal; remote stores must reject this capability. */
+    removeAuthCredentialsHard?(provider: string, targets: readonly CredentialRemovalTarget[]): AuthCredentialHardRemovalResult;
+    updateAuthCredential(id: number, credential: AuthCredential): void;
+    deleteAuthCredential(id: number, disabledCause: string): void;
+    tryDisableAuthCredentialIfMatches(id: number, expectedData: string, disabledCause: string): boolean;
+    tryDisableAuthCredentialIfRevision?(id: number, expectedRevision: number, disabledCause: string): boolean;
+    replaceAuthCredentialsForProvider(provider: string, credentials: AuthCredential[]): StoredAuthCredential[];
+    upsertAuthCredentialForProvider(provider: string, credential: AuthCredential): StoredAuthCredential[];
+    upsertAuthCredentialForProviderIfAbsent(provider: string, credential: AuthCredential): AuthCredentialIfAbsentResult;
+    deleteAuthCredentialsForProvider(provider: string, disabledCause: string): void;
+    getCache(key: string, options?: {
+        includeExpired?: boolean;
+    }): string | null;
+    setCache(key: string, value: string, expiresAtSec: number): void;
+    /** Atomically allocate a durable sequence for broker restart epochs. */
+    allocateMonotonicSequence(key: string, expiresAtSec: number): number;
+    deleteCachePrefix?(prefix: string): void;
+    cleanExpiredCache(): void;
+    /**
+     * Optional store-supplied OAuth refresh. When present, `AuthStorage` uses
+     * it before the per-provider local refresh path. `RemoteAuthCredentialStore`
+     * implements this against the broker; SQLite stores leave it undefined.
+     *
+     * Precedence: `AuthStorageOptions.refreshOAuthCredential` > this hook > local.
+     *
+     * `signal` propagates the agent's cancel (ESC, request abort, …) all the
+     * way to the broker fetch so a hung connection can't strand the caller
+     * for `timeoutMs * (maxRetries + 1)`.
+     */
+    refreshOAuthCredential?(provider: Provider, credentialId: number, credential: OAuthCredential, signal?: AbortSignal): Promise<OAuthCredentials>;
+    /** Broker-backed MCP refresh using the broker's stored token endpoint and refresh secret. */
+    refreshMCPOAuthCredential?(credentialId: number, credential: OAuthCredential, client: MCPOAuthRefreshClient, signal?: AbortSignal): Promise<OAuthCredential>;
+    /**
+     * Atomically adopts a fresh row or claims the current refresh token for one
+     * local provider dial. SQLite-backed stores use this to prevent another
+     * process from replaying a rotating refresh token between a pre-read and
+     * the provider request.
+     */
+    claimOAuthRefreshLease?(credentialId: number, expectedRefresh: string, force: boolean, owner: string, nowMs: number, leaseMs: number): OAuthRefreshLeaseClaim;
+    /** Atomically persists a successful claimed refresh and releases its lease. */
+    completeOAuthRefreshLease?(lease: OAuthRefreshLease, credential: OAuthCredential): boolean;
+    /** Releases an uncompleted refresh lease owned by this process. */
+    releaseOAuthRefreshLease?(lease: OAuthRefreshLease): void;
+    /**
+     * Optional async pre-read hook invoked after AuthStorage selects a stored
+     * credential but before it returns that credential for an outbound request.
+     * Remote broker stores use this to wait out imminent rotations and refresh
+     * their local snapshot before the caller sees a stale access token.
+     */
+    prepareForRequest?(credentialId: number, opts?: {
+        signal?: AbortSignal;
+    }): Promise<boolean | undefined>;
+    /**
+     * Optional store-supplied aggregate usage fetch. When present, `AuthStorage`
+     * routes `fetchUsageReports()` here instead of fanning out per-credential.
+     * `RemoteAuthCredentialStore` proxies to the broker (whose datacenter IP
+     * isn't rate-limited like a heavy residential client).
+     *
+     * Precedence: `AuthStorageOptions.fetchUsageReports` > this hook > local fan-out.
+     *
+     * `signal` propagates the agent's cancel down to the broker fetch.
+     */
+    fetchUsageReports?(signal?: AbortSignal): Promise<UsageReport[] | null>;
+    fetchUsageReportsForProvider?(provider: Provider, signal?: AbortSignal): Promise<UsageReport[] | null>;
+    /** Synchronous, zero-network usage presentation peek. */
+    peekCachedUsagePresentation?(provider: Provider, credentialId: number): CachedUsagePresentation | undefined;
+    /** Record a safe usage observation after an explicit fetch/check. */
+    recordUsagePresentation?(observation: CachedUsagePresentation): void;
+    /** Read a safe, durable health observation for one credential row. */
+    peekCachedCredentialHealth?(provider: Provider, credentialId: number): CachedCredentialHealth | undefined;
+    /** Persist a safe health observation for one credential row. */
+    recordCredentialHealth?(provider: Provider, credentialId: number, health: CachedCredentialHealth): void;
+    /** Persist a safe usage observation without exposing credential payloads. */
+    recordCredentialUsage?(provider: Provider, credentialId: number, report: SafeUsageReport): void;
+    /**
+     * Optional readiness hook for stores that must hydrate payload-free metadata
+     * before one-shot inventory consumers read their first snapshot.
+     */
+    waitForReady?(): Promise<void>;
+    /**
+     * Optional store-supplied per-credential usage report lookup. When present,
+     * `AuthStorage` consults this before its own per-credential upstream fetch
+     * (`#getUsageReport`). `RemoteAuthCredentialStore` implements this against
+     * the broker's aggregate `/v1/usage` (one coalesced round-trip shared across
+     * all callers) so multi-credential ranking on the client never hits the
+     * upstream provider's rate-limited usage endpoint from the laptop IP.
+     *
+     * Returning `null` is authoritative — `AuthStorage` does NOT fall back to
+     * the local fetch path. The store hook owns the decision, since falling
+     * back would re-introduce the per-IP rate-limit problem the broker exists
+     * to avoid.
+     *
+     * `signal` propagates the agent's cancel down to the broker fetch.
+     */
+    getUsageReport?(provider: Provider, credential: OAuthCredential, signal?: AbortSignal): Promise<UsageReport | null>;
+    /**
+     * Optional store hook to invalidate a specific credential after the upstream
+     * provider returned 401 on a supposedly-fresh key. Remote stores force the
+     * broker to re-issue the row; local stores can leave it undefined and let
+     * {@link AuthStorage.invalidateCredentialMatching} fall back to `reload()`.
+     */
+    markCredentialSuspect?(credentialId: number, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Optional async write hook to disable one credential through an authoritative
+     * remote store. Remote clients MUST use this hook instead of the synchronous
+     * local delete methods when an OAuth refresh fails definitively.
+     *
+     * Returns `false` when the row is already absent (for example, a peer
+     * disabled it first). Implementations MUST NOT treat a failed remote write as
+     * a successful local deletion.
+     */
+    disableAuthCredentialRemote?(credentialId: number, disabledCause: string, signal?: AbortSignal, expectedRevision?: number): Promise<boolean>;
+    /**
+     * Optional async write hook for upserting a single credential. When present,
+     * `AuthStorage.#upsertOAuthCredential` routes through this instead of the
+     * sync `upsertAuthCredentialForProvider`. `RemoteAuthCredentialStore` uses
+     * it to send the upsert to the broker via `POST /v1/credential`.
+     *
+     * Implementations MUST update the in-memory snapshot before returning so the
+     * post-write read path is consistent.
+     */
+    upsertAuthCredentialRemote?(provider: string, credential: AuthCredential): Promise<StoredAuthCredential[]>;
+    upsertAuthCredentialRemoteIfAbsent?(provider: string, credential: AuthCredential): Promise<AuthCredentialIfAbsentResult>;
+    /**
+     * Optional async write hook for replace-all semantics (e.g. API-key login
+     * overwriting any previous keys for the same provider). When present,
+     * `AuthStorage.set` routes through this instead of the sync
+     * `replaceAuthCredentialsForProvider`.
+     */
+    replaceAuthCredentialsRemote?(provider: string, credentials: AuthCredential[]): Promise<StoredAuthCredential[]>;
+    /**
+     * Optional async write hook for clearing every credential for a provider
+     * (logout or a provider-wide invalidation). Remote stores must perform this
+     * through their authoritative broker rather than mutating the client cache.
+     */
+    deleteAuthCredentialsRemote?(provider: string, disabledCause: string): Promise<void>;
+}
+/**
+ * Event payload describing a credential that was just soft-disabled.
+ *
+ * Today the only call site is OAuth refresh failures with a definitive cause
+ * (`invalid_grant`, `401/403` not from a network blip, etc.) — the
+ * disabled_cause string is the verbatim error captured for forensics.
+ *
+ * Subscribers can use this to surface a notification, banner, or auto-launch
+ * a re-login flow instead of letting the credential silently disappear.
+ */
+export interface CredentialDisabledEvent {
+    provider: string;
+    disabledCause: string;
+}
+/**
+ * How {@link AuthStorage} orders multiple healthy OAuth credentials of the same
+ * provider:type pool when selecting one for a (new) session.
+ *
+ * - `balanced` (default): prefer the least-used / lowest-drain-rate account.
+ *   Spreads load across accounts and keeps burst headroom on every account.
+ * - `earliest-reset`: prefer the non-blocked account whose usage window resets
+ *   soonest (earliest-expiry-first). Tumbling-window quota is perishable —
+ *   unused quota is lost at reset — so draining the soonest-to-reset account
+ *   first minimizes wasted quota. Drain/used metrics remain tiebreakers.
+ *
+ * Only affects ranking, which the `shouldRank` guard already limits to session
+ * start (or when the session's preferred credential is blocked), so this never
+ * thrashes accounts mid-session / cold-starts the server-side prompt cache.
+ */
+export type CredentialRankingMode = "balanced" | "earliest-reset";
+export type AuthStorageOptions = {
+    usageProviderResolver?: (provider: Provider) => UsageProvider | undefined;
+    rankingStrategyResolver?: (provider: Provider) => CredentialRankingStrategy | undefined;
+    credentialRankingMode?: CredentialRankingMode;
+    usageFetch?: typeof fetch;
+    usageRequestTimeoutMs?: number;
+    usageLogger?: UsageLogger;
+    /**
+     * Resolve a config value (API key, header value, etc.) to an actual value.
+     * - coding-agent injects its resolveConfigValue (supports "!command" syntax via pi-natives)
+     * - Default: checks environment variable first, then treats as literal
+     * `cacheScope` changes whenever the provider credential configuration changes.
+     */
+    configValueResolver?: (config: string, cacheScope?: string) => Promise<string | undefined>;
+    /**
+     * Optional callback fired when AuthStorage automatically disables a
+     * credential because something detected it as no longer usable — today
+     * that's the OAuth refresh-failure path in `getApiKey`. NOT fired for
+     * user-initiated `remove()` (the user already knows) or dedup of
+     * duplicate credentials (uninteresting hygiene).
+     */
+    onCredentialDisabled?: (event: CredentialDisabledEvent) => void | Promise<void>;
+    /**
+     * Override OAuth refresh. When set, `AuthStorage` calls this instead of the
+     * per-provider local refresh function. Receives the credential id so the
+     * implementation can address remote credentials.
+     *
+     * Must return updated {@link OAuthCredentials} with at least `access` and
+     * `expires`. `refresh` may be an opaque sentinel (e.g. `"__remote__"`) when
+     * the actual refresh token never leaves the broker.
+     */
+    refreshOAuthCredential?: (provider: Provider, credentialId: number, credential: OAuthCredential, signal?: AbortSignal) => Promise<OAuthCredentials>;
+    /**
+     * Human-readable description of the credential store backing this
+     * AuthStorage instance. Surfaced through {@link AuthStorage.describeCredentialSource}
+     * so the TUI can show where a token came from (broker URL or local SQLite path).
+     *
+     * Examples:
+     * - `"local ~/.vib/agent/agent.db"`
+     * - `"broker http://can.internal:8765"`
+     */
+    sourceLabel?: string;
+    /**
+     * Override `fetchUsageReports`. When set, `AuthStorage.fetchUsageReports`
+     * calls this instead of fanning out per-credential. The primary use case is
+     * routing through a broker that egresses from a less-throttled IP — e.g. a
+     * residential laptop trips Anthropic's per-IP rate limit on the usage
+     * endpoint and drops 2-of-5 credentials, while the VPS broker gets all 5.
+     *
+     * Implementations may return null when no usage data is available; the
+     * AuthStorage caller surfaces that to its own consumer unchanged.
+     */
+    fetchUsageReports?: (signal?: AbortSignal) => Promise<UsageReport[] | null>;
+    fetchUsageReportsForProvider?: (provider: Provider, signal?: AbortSignal) => Promise<UsageReport[] | null>;
+};
+export type AuthApiKeyOptions = {
+    baseUrl?: string;
+    modelId?: string;
+    /** Select config registrations owned by one caller (for example a ModelRegistry). */
+    owner?: object;
+    /**
+     * Caller's cancel signal. Threaded into any broker-bound OAuth refresh so
+     * `ESC` / request abort actually kills a hung broker fetch instead of
+     * stranding the caller for `timeoutMs * (maxRetries + 1)`.
+     */
+    signal?: AbortSignal;
+    /** Pin selection to one stored credential instead of using round-robin/ranking. */
+    credentialSelector?: AuthCredentialSelector;
+    /** Prefer one stored OAuth credential while preserving quota-triggered fallback. */
+    preferredCredentialSelector?: AuthCredentialSelector;
+};
+export type AuthCredentialSelectorKind = "id" | "email" | "account" | "project";
+export interface AuthCredentialSelector {
+    kind: AuthCredentialSelectorKind;
+    value: string;
+}
+/**
+ * Refreshed OAuth access plus identity metadata returned by
+ * {@link AuthStorage.getOAuthAccess}. Callers that authenticate via a bearer
+ * AND need the credential's identity (OpenAI code backend `chatgpt-account-id`, Google
+ * `projectId`, GitHub `enterpriseUrl`) consume this shape directly; the
+ * refresh slot is deliberately omitted because rotating refresh tokens never
+ * leave {@link AuthStorage}.
+ */
+export interface OAuthAccess {
+    accessToken: string;
+    accountId?: string;
+    email?: string;
+    projectId?: string;
+    enterpriseUrl?: string;
+}
+export interface InvalidateCredentialMatchingOptions {
+    signal?: AbortSignal;
+    sessionId?: string;
+    owner?: object;
+}
+/** Read optional broker error detail without allowing hostile objects to escape classification. */
+/** @internal Tested directly because hostile accessors must preserve the original error identity. */
+export declare function readBrokerErrorBody(error: unknown): string | undefined;
+/**
+ * Credential storage backed by an AuthCredentialStore.
+ * Reads from storage on reload(), manages round-robin credential selection,
+ * usage limit tracking, and OAuth token refresh.
+ */
+export declare class AuthStorage {
+    #private;
+    constructor(store: AuthCredentialStore, options?: AuthStorageOptions);
+    /**
+     * Create an AuthStorage instance backed by a AuthCredentialStore.
+     * Convenience factory for standalone use (e.g., pi-ai CLI).
+     * @param dbPath - Path to SQLite database
+     */
+    static create(dbPath: string, options?: AuthStorageOptions): Promise<AuthStorage>;
+    /**
+     * Close the underlying credential store.
+     *
+     * After calling this, the instance must not be reused.
+     */
+    close(): void;
+    getGeneration(): number;
+    getCache(key: string, options?: {
+        includeExpired?: boolean;
+    }): string | null;
+    setCache(key: string, value: string, expiresAtSec: number): void;
+    allocateMonotonicSequence(key: string, expiresAtSec: number): number;
+    getProviderConfigurationGeneration(provider: string): number;
+    getProviderOAuthRefreshGeneration(provider: string): number;
+    getProviderEvidenceGeneration(provider: string, resolvedApiKey?: string, owner?: object): string;
+    onGenerationChanged(listener: (generation: number) => void): () => void;
+    offGenerationChanged(listener: (generation: number) => void): void;
+    /**
+     * Subscribe to {@link CredentialDisabledEvent}s. Multiple subscribers are supported and
+     * each fires for every disable event; subscribers are invoked in registration order with
+     * exceptions and async rejections isolated per-listener so a misbehaving subscriber
+     * cannot break the disable path or starve the rest of the chain.
+     *
+     * If `credential_disabled` events were emitted while no listener was subscribed, they are
+     * replayed (in insertion order) to the listener that triggers the empty→non-empty
+     * transition. The drain is one-shot — listeners that subscribe after that no longer see
+     * past events.
+     *
+     * Returns an unsubscribe function. The function is idempotent: calling it more than once
+     * is a no-op. After every subscriber has unsubscribed, subsequent disable events buffer
+     * again until the next subscribe.
+     *
+     * @param listener Callback invoked with each disable event. May be sync or async.
+     * @returns A function that removes this listener from the subscriber set.
+     */
+    onCredentialDisabled(listener: (event: CredentialDisabledEvent) => void | Promise<void>): () => void;
+    /**
+     * Set a runtime API key override (not persisted to disk).
+     * Used for CLI --api-key flag.
+     */
+    setRuntimeApiKey(provider: string, apiKey: string): void;
+    /**
+     * Pin credential selection for a provider (not persisted to disk).
+     * Used for CLI --credential.
+     */
+    setRuntimeCredentialSelector(provider: string, selector: AuthCredentialSelector): void;
+    /** Acquire a reference-counted credential scope for a session or shared subagent scope. */
+    acquireCredentialScope(scopeId: string): void;
+    /** Whether a credential scope already has at least one live owner. */
+    hasCredentialScopeLease(scopeId: string): boolean;
+    /** Release one credential-scope lease; final release clears only that scope's derived state. */
+    releaseCredentialScope(scopeId: string): void;
+    /**
+     * Set the selector derived from a durable session pin or a session seed.
+     * `owner` scopes config-override validation to one ModelRegistry; omitted
+     * owners retain process-wide caller semantics.
+     */
+    setSessionCredentialSelector(scopeId: string, provider: string, selector: AuthCredentialSelector, owner?: object): void;
+    /** Explicitly mask persistent/process-global selection and return the provider to AUTO for one scope. */
+    setSessionCredentialAuto(provider: string, scopeId: string): void;
+    /** Clear a scope's explicit selector and AUTO mask, restoring normal precedence. */
+    clearSessionCredentialSelector(provider: string, scopeId: string): void;
+    /** Whether the effective selection for a scope is explicitly pinned (AUTO masks are not pins). */
+    hasSessionCredentialSelector(provider: string, scopeId?: string): boolean;
+    /** Whether this scope explicitly masks provider pins and uses AUTO ranking. */
+    hasSessionCredentialAuto(provider: string, scopeId?: string): boolean;
+    /** Resolve the effective selector precedence for a provider/scope. */
+    resolveEffectiveCredentialSelector(provider: string, scopeId?: string, explicitSelector?: AuthCredentialSelector): AuthCredentialSelector | undefined;
+    /** @internal Return cache provenance for an exact stored literal API-key row without resolving its value. */
+    getStoredLiteralApiKeyEvidenceGeneration(provider: string, selector: AuthCredentialSelector, owner?: object): string | undefined;
+    /**
+     * Validate and canonicalize an OAuth-only selector for account pinning.
+     * `owner` scopes config-override checks to one ModelRegistry; omitted owners
+     * retain process-wide caller semantics.
+     */
+    resolveOAuthPinTarget(provider: string, selector: AuthCredentialSelector, owner?: object): OAuthPinTarget;
+    /** Return all local inventory rows, including soft-disabled metadata, without payloads. */
+    listCredentialInventory(provider?: string): CredentialInventoryRecord[];
+    /** Return local credential hard-removal action targets, including disabled rows. */
+    listCredentialRemovalTargets(provider?: string): CredentialRemovalTarget[];
+    /** Remove selected local credential rows atomically; conflict leaves all rows intact. */
+    removeAuthCredentialsHard(provider: string, targets: readonly CredentialRemovalTarget[]): AuthCredentialHardRemovalResult;
+    /**
+     * Remove a runtime credential selector.
+     */
+    removeRuntimeCredentialSelector(provider: string): void;
+    /** Whether a provider currently has a soft runtime credential preference. */
+    hasRuntimePreferredCredentialSelector(provider: string): boolean;
+    /** Resolve an unqualified preferred selector to the single active OAuth provider it matches. */
+    resolveRuntimePreferredCredentialSelectorProvider(selector: AuthCredentialSelector): string;
+    /**
+     * Prefer one stored OAuth credential for a provider while retaining quota
+     * fallback to the rest of the pool (not persisted to disk). Used for CLI
+     * `--prefer-credential`. Unlike {@link setRuntimeCredentialSelector}, a
+     * quota/rate-limit failure on the preferred row still rotates to another
+     * active credential instead of failing the session.
+     */
+    setRuntimePreferredCredentialSelector(provider: string, selector: AuthCredentialSelector): void;
+    /**
+     * Remove a runtime preferred credential selector.
+     */
+    removeRuntimePreferredCredentialSelector(provider: string): void;
+    /**
+     * Remove a runtime API key override.
+     */
+    removeRuntimeApiKey(provider: string): void;
+    /** Whether a provider is currently authenticated by a runtime API-key override. */
+    hasRuntimeApiKey(provider: string): boolean;
+    /** Whether a provider is currently authenticated by a config API-key override. */
+    hasConfigApiKey(provider: string, owner?: object): boolean;
+    /**
+     * Whether credential selection for a provider is pinned to one stored row by
+     * a runtime selector (`--credential`).
+     *
+     * Distinct from {@link AuthStorage.hasRuntimeApiKey}: that reports the
+     * `--api-key` override, which lives in a different map and is mutually
+     * exclusive with a selector. Callers that must not rotate away from a pinned
+     * credential have to consult BOTH.
+     */
+    hasRuntimeCredentialSelector(provider: string): boolean;
+    /** Whether the effective selector for a session scope is pinned. */
+    hasEffectiveCredentialSelector(provider: string, sessionId?: string): boolean;
+    /**
+     * Opaque stored row id of the credential this session is currently using.
+     *
+     * Deliberately non-identifying: the persisted primary key, never an email,
+     * account id, project id, or key material. Callers that need to correlate a
+     * credential across a session boundary use this instead of projecting
+     * personal metadata.
+     *
+     * Returns `undefined` when the session has not been routed to a stored
+     * credential yet, or when it authenticated through an env key or fallback
+     * resolver rather than a stored row.
+     */
+    getSessionCredentialRowId(provider: string, sessionId?: string): number | undefined;
+    /**
+     * Force a running session's OAuth credential for a provider to a specific
+     * stored row, independent of quota/rate-limit state. Used for a mid-session
+     * `/credential <selector>` switch that has nothing to do with exhaustion —
+     * the user just wants a different account for the rest of the session.
+     *
+     * This mutates ONLY the session-scoped sticky pointer
+     * ({@link AuthStorage.#recordSessionCredential}), never a provider-wide
+     * runtime override, so it cannot bleed into other sessions in the same
+     * process whose credential identity differs. The sticky pointer is keyed by
+     * `sessionId`, and subagents/team workers inherit their parent's
+     * `credentialSessionId` by design so they keep using the same account as
+     * the parent — a switch therefore applies to the whole session family
+     * sharing that identity, not to unrelated sessions.
+     *
+     * Fails closed rather than silently no-op when a stronger override already
+     * decides this provider's credential every call: a hard pin
+     * ({@link AuthStorage.setRuntimeCredentialSelector}, `--credential`), a
+     * runtime API-key override (`--api-key`), or a config-sourced API key
+     * (`models.yml` `apiKey`) would each re-decide the credential on the very
+     * next {@link AuthStorage.getApiKey} call and make this switch appear to
+     * silently do nothing. `owner` scopes the config-override check to one
+     * ModelRegistry; omitted owners retain process-wide caller semantics.
+     *
+     * Deliberately does not touch credential-blocked state: if the target row
+     * is still backoff-blocked from a prior quota failure, the existing
+     * `#resolveOAuthSelection` ranking safely ignores this sticky pointer and
+     * falls back to a usable account instead of re-issuing a request that would
+     * just draw another 429/quota error.
+     */
+    switchSessionCredential(provider: string, sessionId: string, selector: AuthCredentialSelector, owner?: object): void;
+    /**
+     * Register a per-provider API key sourced from user configuration
+     * (e.g. `models.yml` `providers.<name>.apiKey`). Higher priority than
+     * stored credentials and OAuth tokens — when the user pins a key in
+     * config, that key is what authenticates outbound requests, regardless
+     * of whatever the broker happens to have loaded for that provider.
+     *
+     * Lower priority than {@link setRuntimeApiKey} so a CLI `--api-key`
+     * still wins for the duration of a single invocation.
+     *
+     * `options.owner` scopes the override to one registry or other caller. The
+     * unscoped form is process-wide and is retained for standalone callers.
+     *
+     * `options.envSourced` marks the value as resolved from a models.yml
+     * `apiKeyEnv` indirection. Unlike a literal pin, an env pointer only says
+     * where to look for a key; when the user has since run `auth login`, the
+     * stored api_key credential is the fresher, actively-managed secret and
+     * wins over the indirection (stored OAuth credentials still yield, so a
+     * custom-endpoint bearer is never replaced by an upstream OAuth token).
+     */
+    setConfigApiKey(provider: string, apiKey: string, options?: {
+        envSourced?: boolean;
+        owner?: object;
+    }): void;
+    /**
+     * Remove a single config-sourced API key override.
+     */
+    removeConfigApiKey(provider: string, owner?: object): void;
+    /**
+     * Drop config-sourced API keys. An owner removes only its own registrations;
+     * the unscoped form remains an explicit global reset for callers that own the
+     * entire AuthStorage instance.
+     */
+    clearConfigApiKeys(owner?: object): void;
+    /**
+     * Set a fallback resolver for API keys not found in storage or env vars.
+     * Used for custom provider keys from models.json.
+     */
+    setFallbackResolver(resolver: (provider: string) => string | undefined, owner?: object): () => void;
+    /**
+     * Reload credentials from storage.
+     */
+    reload(): Promise<void>;
+    /**
+     * Acquire a store-owned provider-admission ticket when the backing store
+     * provides one (for example, a remote broker snapshot store). Local stores
+     * need no additional ordering and return `undefined`.
+     */
+    acquireCredentialDispatchTicket(provider: Provider, signal?: AbortSignal): Promise<CredentialDispatchTicket | undefined>;
+    /** Returns the credential type selected for a provider/session, if one has been recorded. */
+    getSessionCredentialType(provider: string, sessionId?: string): AuthCredential["type"] | undefined;
+    /**
+     * Get credential for a provider (first entry if multiple).
+     */
+    get(provider: string): AuthCredential | undefined;
+    /**
+     * Set credential for a provider.
+     */
+    set(provider: string, credential: AuthCredentialEntry): Promise<void>;
+    importCredentialIfAbsent(provider: string, credential: AuthCredential, owner?: object): Promise<AuthCredentialIfAbsentSnapshotResult>;
+    /**
+     * Remove credential for a provider.
+     */
+    remove(provider: string): Promise<void>;
+    /**
+     * List all providers with credentials.
+     */
+    list(): string[];
+    /**
+     * Check if credentials exist for a provider in storage.
+     */
+    has(provider: string): boolean;
+    disableCredentialByIdIfRevision(id: number, expectedRevision: number, disabledCause: string): boolean;
+    hasAuth(provider: string, sessionId?: string, options?: Pick<AuthApiKeyOptions, "owner">): boolean;
+    /**
+     * Credential type that a provider/session will dispatch first without performing I/O.
+     * Mirrors getApiKey selector validation, overrides, session OAuth stickiness,
+     * cached command-key usability, OAuth retry, and environment fallback order.
+     */
+    getEffectiveCredentialType(provider: string, sessionId?: string, options?: Pick<AuthApiKeyOptions, "owner">): AuthCredential["type"] | undefined;
+    /**
+     * Check whether configured auth is currently usable without resolving credentials.
+     */
+    hasUsableAuth(provider: string, options?: Pick<AuthApiKeyOptions, "owner">): boolean;
+    /**
+     * Check if OAuth credentials are configured for a provider.
+     */
+    hasOAuth(provider: string): boolean;
+    /**
+     * Get OAuth credentials for a provider.
+     */
+    getOAuthCredential(provider: string, sessionId?: string, options?: Pick<AuthApiKeyOptions, "owner">): OAuthCredential | undefined;
+    /**
+     * Get the OAuth `accountId` for a provider, preferring the credential that is
+     * session-sticky for `sessionId` when multiple OAuth credentials are configured.
+     * Falls back to the first OAuth credential when no session preference exists (e.g.
+     * first call before any `getApiKey` has been issued, or single-credential setups).
+     * Returns `undefined` when no OAuth credential carries an `accountId`.
+     */
+    getOAuthAccountId(provider: string, sessionId?: string, options?: Pick<AuthApiKeyOptions, "owner">): string | undefined;
+    /**
+     * Get all credentials.
+     */
+    getAll(): AuthStorageData;
+    /**
+     * Login to an OAuth provider.
+     */
+    login(provider: OAuthProviderId, ctrl: OAuthController & {
+        /** onAuth is required by auth-storage but optional in OAuthController */
+        onAuth: (info: {
+            url: string;
+            instructions?: string;
+        }) => void;
+        /** onPrompt is required for some providers (github-copilot, OpenAI code provider) */
+        onPrompt: (prompt: {
+            message: string;
+            placeholder?: string;
+        }) => Promise<string>;
+    }, options?: OAuthLoginOptions): Promise<void>;
+    /**
+     * Logout from a provider.
+     */
+    logout(provider: string): Promise<void>;
+    fetchUsageReports(options?: {
+        provider?: Provider;
+        baseUrlResolver?: (provider: Provider) => string | undefined;
+        /** Caller's cancel signal; only rejects this caller, never the shared upstream fetch. */
+        signal?: AbortSignal;
+        /** Disable provider/account/error logging for secret-safe control surfaces. */
+        logDetails?: boolean;
+    }): Promise<UsageReport[] | null>;
+    /**
+     * Probe each stored credential against its provider's auth-verifying usage
+     * endpoint and report per-credential auth health.
+     *
+     * Surfaces the identity of failing credentials so callers running a
+     * multi-account pool (e.g. a broker-backed auth-gateway) can tell which
+     * row is producing 401s. The probe mirrors the per-credential fan-out
+     * inside {@link AuthStorage.fetchUsageReports} (OAuth refresh-on-expiry,
+     * then `UsageProvider.fetchUsage`) but does NOT swallow errors — every
+     * credential gets either `ok: true`, `ok: false` with `reason`, or
+     * `ok: null` when no probe is configured for the provider.
+     *
+     * Iterates sequentially to avoid synchronized N-account fan-out that
+     * upstream `/usage` rate limiters (per source IP) treat as a burst.
+     *
+     * Only inspects active rows from {@link AuthCredentialStore.listAuthCredentials};
+     * soft-disabled rows are already known-bad and don't need a network probe.
+     * Environment-variable API keys are not enumerated — the caller's intent
+     * here is "which of my stored credentials is broken".
+     */
+    /** Return a safe cache-only usage observation. */
+    getCachedUsageReport(provider: Provider, credentialId: number, baseUrl?: string): CachedUsageReport | undefined;
+    /** Cache-only health observation; unknown means no retained explicit check. */
+    getCachedCredentialHealth(credentialId: number): CachedCredentialHealth;
+    peekCachedCredentialHealthForSource(provider: string, source: "env" | "config" | "runtime"): CachedCredentialHealth;
+    recordCredentialHealthForSource(provider: string, source: "env" | "config" | "runtime", health: CachedCredentialHealth): void;
+    /** Explicit API-key probe; key bytes are not retained in the returned result. */
+    checkApiKeyCredential(provider: Provider, apiKey: string, options?: ApiKeyCredentialCheckOptions): Promise<ApiKeyCredentialCheckResult>;
+    checkCredentials(options?: CheckCredentialsOptions): Promise<CredentialHealthResult[]>;
+    /**
+     * Marks the current session's credential as temporarily blocked due to usage limits.
+     * Uses usage reports to determine accurate reset time when available.
+     * Returns true if a credential was blocked, enabling automatic fallback to the next credential.
+     */
+    markUsageLimitReached(provider: string, sessionId: string | undefined, options?: {
+        retryAfterMs?: number;
+        baseUrl?: string;
+        signal?: AbortSignal;
+        owner?: object;
+    }): Promise<boolean>;
+    /**
+     * Earliest instant at which any currently blocked stored credential for this
+     * provider becomes usable again. Undefined when nothing is blocked.
+     * When `sessionId` is provided, only the session's active credential type is
+     * considered — API-key and OAuth backoff pools are independent.
+     * Informational only: callers must not treat this as authorization to wait.
+     */
+    getEarliestUnblockAt(provider: string, sessionId?: string): number | undefined;
+    /**
+     * Peek at API key for a provider without refreshing OAuth tokens.
+     * Used for model discovery where we only need to know if credentials exist
+     * and get a best-effort token. For GitHub Copilot we preserve enterprise
+     * routing metadata so discovery can hit the correct host.
+     */
+    peekApiKey(provider: string, options?: Pick<AuthApiKeyOptions, "owner">): Promise<string | undefined>;
+    /**
+     * Get API key for a provider.
+     * Priority:
+     * 1. Runtime override (CLI --api-key)
+     * 2. Config override (models.yml `providers.<name>.apiKey` literal pin)
+     * 3. Stored api_key credential from `auth login`, when the config override
+     *    is only an `apiKeyEnv` indirection
+     * 4. Config override sourced from models.yml `providers.<name>.apiKeyEnv`
+     * 5. Session-selected OAuth credential, when present
+     * 6. Usable or unresolved API key from storage
+     * 7. OAuth token from storage (auto-refreshed)
+     * 8. Previously unusable command-backed API key retry
+     * 9. Environment variable
+     * 10. Fallback resolver (models.yml custom providers, last-resort)
+     */
+    getApiKey(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined>;
+    /**
+     * Resolve the OAuth credential for `provider`, refreshing through the same
+     * pipeline as {@link AuthStorage.getApiKey} but returning the refreshed
+     * {@link OAuthAccess} (raw access token + identity metadata) instead of
+     * the API-key bytes.
+     *
+     * Use this when the caller needs to inject identity headers alongside the
+     * bearer (OpenAI code backend `chatgpt-account-id`, Google `project`, GitHub
+     * `enterpriseUrl`). For pure "give me the bytes for `Authorization`"
+     * scenarios, prefer {@link AuthStorage.getApiKey}.
+     *
+     * Returns `undefined` when no OAuth credential is available, the
+     * credential fails to refresh, or runtime/config overrides have replaced
+     * OAuth with an explicit API key.
+     */
+    getOAuthAccess(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined>;
+    invalidateCredentialMatching(provider: string, apiKey: string, options?: InvalidateCredentialMatchingOptions): Promise<boolean>;
+    invalidateCredentialMatching(provider: string, apiKey: string, signal?: AbortSignal): Promise<boolean>;
+    /**
+     * Build a redacted snapshot of all loaded credentials for the auth-broker
+     * wire. OAuth refresh tokens are replaced with {@link REMOTE_REFRESH_SENTINEL}
+     * so clients never see the actual refresh token.
+     *
+     * Callers must {@link AuthStorage.reload} first when serving a stale snapshot
+     * (the broker server's HTTP handler does this).
+     */
+    exportSnapshot(): AuthCredentialSnapshot;
+    /**
+     * Refresh the OAuth credential with the given id through a per-credential
+     * single-flight. Concurrent callers for the same row await the same upstream
+     * refresh attempt, which is required for providers that rotate refresh tokens
+     * on every successful refresh.
+     */
+    refreshCredentialById(id: number, signal?: AbortSignal, mcpClient?: MCPOAuthRefreshClient): Promise<AuthCredentialSnapshotEntry>;
+    /**
+     * Force-refresh the OAuth credential with the given id, bypassing the
+     * not-yet-expired guard. Used by the auth-broker server to honour
+     * `POST /v1/credential/:id/refresh`.
+     *
+     * Returns the redacted snapshot entry for the refreshed row.
+     * Throws when no OAuth credential with that id is loaded.
+     */
+    forceRefreshCredentialById(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry>;
+    /** Force-refresh the first OAuth credential stored for a provider. */
+    forceRefreshOAuthCredential(provider: string, expected: OAuthCredential, client?: MCPOAuthRefreshClient, signal?: AbortSignal): Promise<OAuthCredential>;
+    /**
+     * Disable the credential with the given id and emit a
+     * {@link CredentialDisabledEvent}. Used by the auth-broker server to honour
+     * `POST /v1/credential/:id/disable`. Returns `false` when no such row exists.
+     */
+    disableCredentialById(id: number, disabledCause: string): boolean;
+    /**
+     * Upsert a credential into the underlying store, refresh the in-memory
+     * snapshot, and return the redacted snapshot entries for the provider.
+     *
+     * Used by the auth-broker server to honour `POST /v1/credential`. The
+     * persistence layer (`SqliteAuthCredentialStore.upsertAuthCredentialForProvider`)
+     * does identity-key matching, so re-uploading the same email/account replaces
+     * the existing row instead of inserting a duplicate.
+     */
+    upsertCredential(provider: string, credential: AuthCredential): AuthCredentialSnapshotEntry[];
+    /**
+     * Describe where the active credential for a provider came from.
+     *
+     * Surfaces four layers, highest precedence first:
+     *   1. Runtime override (`--api-key`).
+     *   2. Config override (`models.yml` `providers.<name>.apiKey` literal pin,
+     *      or an `apiKeyEnv` indirection when no stored api_key credential
+     *      outranks it).
+     *   3. Stored credential (the one this session is currently sticky to, or the
+     *      one round-robin would pick next when no session id is supplied).
+     *   4. Env var / fallback resolver — when no stored credential exists.
+     *
+     * The string is purely informational; consumers must not parse it.
+     */
+    describeCredentialSource(provider: string, sessionId?: string, options?: Pick<AuthApiKeyOptions, "owner">): string | undefined;
+}
+/**
+ * Default SQLite-backed implementation of {@link AuthCredentialStore}.
+ *
+ * Used by the pi-ai CLI and as the default store for `AuthStorage.create()`.
+ * Also exposes convenience methods (`saveOAuth`, `getOAuth`, `saveApiKey`,
+ * `getApiKey`, `listProviders`, `deleteProvider`) that callers can use directly
+ * without going through `AuthStorage`.
+ */
+export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
+    #private;
+    constructor(db: Database);
+    static open(dbPath?: string): Promise<SqliteAuthCredentialStore>;
+    listAuthCredentials(provider?: string): StoredAuthCredential[];
+    listCredentialInventory(provider?: string): CredentialInventoryRecord[];
+    listCredentialRemovalTargets(provider?: string): CredentialRemovalTarget[];
+    removeAuthCredentialsHard(provider: string, targets: readonly CredentialRemovalTarget[]): AuthCredentialHardRemovalResult;
+    claimOAuthRefreshLease(credentialId: number, expectedRefresh: string, force: boolean, owner: string, nowMs: number, leaseMs: number): OAuthRefreshLeaseClaim;
+    completeOAuthRefreshLease(lease: OAuthRefreshLease, credential: OAuthCredential): boolean;
+    releaseOAuthRefreshLease(lease: OAuthRefreshLease): void;
+    replaceAuthCredentialsForProvider(provider: string, credentials: AuthCredential[]): StoredAuthCredential[];
+    upsertAuthCredentialForProvider(provider: string, credential: AuthCredential): StoredAuthCredential[];
+    upsertAuthCredentialForProviderIfAbsent(provider: string, credential: AuthCredential): AuthCredentialIfAbsentResult;
+    updateAuthCredential(id: number, credential: AuthCredential): void;
+    deleteAuthCredential(id: number, disabledCause: string): void;
+    /**
+     * CAS-style disable: only soft-deletes the row when its `data` column still
+     * matches `expectedData` and the row has not already been disabled. Used by
+     * the OAuth refresh-failure path to avoid clobbering a peer that rotated the
+     * row between our pre-check and the disable.
+     */
+    tryDisableAuthCredentialIfMatches(id: number, expectedData: string, disabledCause: string): boolean;
+    tryDisableAuthCredentialIfRevision(id: number, expectedRevision: number, disabledCause: string): boolean;
+    deleteAuthCredentialsForProvider(provider: string, disabledCause: string): void;
+    getCache(key: string, options?: {
+        includeExpired?: boolean;
+    }): string | null;
+    setCache(key: string, value: string, expiresAtSec: number): void;
+    allocateMonotonicSequence(key: string, expiresAtSec: number): number;
+    deleteCachePrefix(prefix: string): void;
+    cleanExpiredCache(): void;
+    /**
+     * Save OAuth credentials for a provider.
+     * Preserves unrelated identities and replaces only the matching credential.
+     */
+    saveOAuth(provider: string, credentials: OAuthCredentials): void;
+    /**
+     * Get OAuth credentials for a provider.
+     */
+    getOAuth(provider: string): OAuthCredentials | null;
+    /**
+     * Save API key for a provider (replaces existing).
+     */
+    saveApiKey(provider: string, apiKey: string): void;
+    /**
+     * Get API key for a provider.
+     */
+    getApiKey(provider: string): string | null;
+    /**
+     * List all providers with credentials.
+     */
+    listProviders(): string[];
+    /**
+     * Delete all credentials for a provider.
+     */
+    deleteProvider(provider: string): void;
+    close(): void;
+}