@cortexkit/opencode-openai-auth 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -1,355 +1,150 @@
-import { SidebarMachineState, SidebarState } from "./sidebar-state.js";
+import { C as CustodyManifestIo, E as detectClaustrumConnection, S as acquireRefreshFileLock, T as QuotaManager, _ as loadAccounts, b as ClaustrumCredentialCache, c as IdTokenClaims, d as parseJwtClaims, f as AccountStorage, g as OAuthQuotaSnapshot, h as OAuthAccount, l as TokenResponse, m as FallbackAccount, n as ResetTargetIdentity, p as AccountStoreTransaction, t as CommandContext, u as extractAccountIdFromClaims, v as mutateAccounts, w as CustodyManifestReadResult, x as resolveFallbackAccess, y as withAccountStoreTransaction } from "./internal-Y7QNVDJT.js";
+import { Q as VaultCustodyState, Z as CustodyInertReason, b as SidebarState, m as SidebarAccountCustody, v as SidebarMachineState } from "./sidebar-state-B98sERYt.js";
 import { Hooks, Plugin, PluginInput } from "@opencode-ai/plugin";
-//#region ../core/dist/provider.d.ts
-type QuotaWindowName = string;
-type ProviderQuotaFn = (input: {
-  accessToken: string;
-  fetchImpl: typeof fetch;
-  now: () => number;
-}) => Promise<OAuthQuotaSnapshot>;
+//#region src/core/custody-manifest.d.ts
+declare function readCustodyManifest(path?: string, io?: CustodyManifestIo): Promise<CustodyManifestReadResult>;
 //#endregion
-//#region ../core/dist/quota-manager.d.ts
-type QuotaEntry = {
-  quota: OAuthQuotaSnapshot;
-  refreshAfter: number;
-  checkedAt: number;
-  accountId?: string;
+//#region src/core/custody-transition.d.ts
+type TransitionOutcome = 'ready' | 'tombstoned' | Extract<CustodyInertReason, 'new-local-family-under-claustrum' | 'vault-cold' | 'vault-reauth' | 'identity-mismatch' | 'no-handle'> | 'torn-read-deferred' | `aborted:${string}`;
+type TransitionResult = {
+  status: 'completed' | 'incomplete' | 'aborted';
+  outcomes: Record<string, TransitionOutcome>;
+  reason?: string;
 };
-type QuotaManagerOptions = {
-  storage: AccountStorage | null;
-  fetchImpl?: typeof fetch;
-  /**
-   * Account config file this manager's cross-process refresh locks are named
-   * after. Host-resolved and required, so two hosts pointing at different
-   * stores never contend on one another's lock.
-   */
-  configPath: string;
-  now?: () => number;
-  /** Injected quota-fetch function — replaces the hard-imported Anthropic fetchOAuthQuotaSnapshot */
-  fetchQuotaFn?: ProviderQuotaFn;
-  onMainQuotaFetched?: (quota: OAuthQuotaSnapshot, checkedAt: number, fingerprint: string, fetchStartedAt: number) => void;
-  onApiError?: (error: AccountOperationError) => void;
+type CustodyHostAuth = EnterClaustrumModeDeps['auth'];
+type Release = {
+  release(): Promise<void>;
 };
-declare class QuotaManager {
-  private main;
-  private mainTokenFp;
-  private mainQuotaAccountId;
-  private fallbacks;
-  private fallbackTokenFps;
-  private inflightMain;
-  private inflightMainFp;
-  private inflightFallbacks;
-  private mainLastApiError;
-  private fallbackApiErrors;
-  private fallbackErrorTokenFps;
-  private rateLimitedUntilMap;
-  private apiGate;
-  private lastApiCallAt;
-  private storage;
-  private readonly fetchImpl;
-  private readonly now;
-  private readonly fetchQuotaFn;
-  private readonly onMainQuotaFetched;
-  private readonly onApiError;
-  private readonly configPath;
-  constructor(opts: QuotaManagerOptions);
-  /**
-   * Cached main quota entry. Pass the live access token to enforce token
-   * binding: if the cached entry was produced by a different token (main
-   * account switched), it is dropped and null is returned so the caller
-   * refetches for the current account. Called without a token (e.g. for
-   * display) it returns whatever is cached.
-   */
-  getMain(accessToken?: string): QuotaEntry | null;
-  /**
-   * Cached fallback quota entry. Pass the live access token to enforce token
-   * binding: if the entry was produced by a different token (account re-login),
-   * it is dropped and null is returned so the caller refetches.
-   */
-  getFallback(accountId: string, accessToken?: string): QuotaEntry | null;
-  getAllFallbacks(): Map<string, QuotaEntry>;
-  setMain(accessToken: string, entry: QuotaEntry, accountId?: string, completeSnapshot?: boolean): void;
-  /**
-   * Non-invalidating read of the cached main quota for POLICY decisions
-   * (killswitch). Unlike getMain(token), a token mismatch does NOT drop the
-   * cache — an access-token refresh is a same-account event and must not turn a
-   * known-exhausted account into "unknown" (which would fail open and spend).
-   *
-   * Pass the live ChatGPT accountId to still drop on a genuine account SWITCH:
-   * if the cached entry's account identity is known and differs, return null so
-   * the killswitch treats it as unknown rather than judging account A by account
-   * B's quota. When identity is unknown on either side, the cached snapshot is
-   * returned (best-effort) — the same fail-open-on-unknown stance as elsewhere.
-   */
-  peekMainForPolicy(accountId?: string): QuotaEntry | null;
-  /**
-   * Non-invalidating read of a cached fallback quota for POLICY decisions
-   * (killswitch, admission). Keyed by the stable internal account id, so a
-   * token refresh for the same account does not drop it (getFallback(id, token)
-   * would).
-   *
-   * Pass the live ChatGPT identity to still drop on a genuine re-login: if the
-   * cached entry's identity is known and differs, return null so the previous
-   * identity's (possibly exhausted) quota is never judged against its
-   * replacement. Unknown on either side fails open, matching peekMainForPolicy.
-   */
-  peekFallbackForPolicy(accountId: string, identity?: string): QuotaEntry | null;
-  setFallback(accountId: string, entry: QuotaEntry, accessToken?: string, completeSnapshot?: boolean, identity?: string): void;
-  /**
-   * Mark accountId ('main' or a fallback id) rate-limited until resetAtMs.
-   * Keeps the LATER reset: skips only when an existing mark is strictly
-   * later than resetAtMs, so an equal-reset re-mark still applies (idempotent)
-   * instead of being silently dropped by a stale `>=` comparison.
-   */
-  markRateLimited(accountId: string, resetAtMs: number): void;
-  /** True iff accountId has a mark whose reset has not yet passed. */
-  isRateLimited(accountId: string): boolean;
-  /**
-   * Raw stored reset for accountId's mark, or undefined if none. Unlike
-   * isRateLimited, this does NOT apply read-time expiry — callers on the
-   * block path already know the mark is live (isRateLimited just returned
-   * true) and want its exact reset estimate for a Retry-After computation.
-   */
-  rateLimitedUntil(accountId: string): number | undefined;
-  /** Explicit early clear — read-time expiry in isRateLimited is primary. */
-  clearRateLimited(accountId: string): void;
-  refreshMain(accessToken: string): Promise<OAuthQuotaSnapshot>;
-  refreshFallback(accountId: string, accessToken: string): Promise<OAuthQuotaSnapshot>;
-  refreshAllFallbacks(accounts: OAuthAccount[]): Promise<void>;
-  /**
-   * Fire-and-forget refresh. Does not await, swallows errors.
-   */
-  refreshMainInBackground(accessToken: string): void;
-  isMainStale(): boolean;
-  isFallbackStale(accountId: string, accessToken?: string): boolean;
-  shouldRefreshOnRequestCount(requestCount: number): boolean;
-  /**
-   * Combined check: should a refresh happen right now?
-   * True if main is stale by time OR triggered by request count.
-   */
-  needsRefresh(requestCount: number): boolean;
-  updateStorage(storage: AccountStorage | null): void;
-  /**
-   * Seed/update the main quota cache from persisted state. This is deliberately
-   * callable after every disk load so another plugin process's fresh quota write
-   * can stop this process from showing "checking…" or making a redundant quota
-   * API call.
-   */
-  seedMainFromStorage(storage: AccountStorage | null, accessToken?: string): void;
-  private seedMainBackoffFromStorage;
-  /**
-   * Seed fallback cache entries from persisted account.quota data.
-   * Updates older in-memory entries so a fresh quota write from another plugin
-   * process prevents redundant checks and stale sidebar writes.
-   */
-  seedFallbacksFromAccounts(accounts: OAuthAccount[]): void;
-  /**
-   * Whether the MAIN quota API is currently in backoff. Scoped to the main
-   * account — a fallback account's 429 never reports here.
-   */
-  isBackedOff(): boolean;
-  /**
-   * Whether a specific fallback account's quota API is in backoff.
-   */
-  isFallbackBackedOff(accountId: string, accessToken?: string): boolean;
-  getLastApiError(): AccountOperationError | undefined;
-  /** Minimum gap between consecutive quota API calls (ms). */
-  private static readonly API_CALL_GAP_MS;
-  private static fallbackInflightKey;
-  private static quotaLockName;
-  /**
-   * Serialize API calls through a shared gate so only one
-   * quota API request runs at a time, with a minimum gap
-   * between calls. Prevents concurrent and rapid-fire calls
-   * from triggering rate limits.
-   */
-  private _enqueueApiFetch;
-  private _fetchMain;
-  private _fetchFallback;
-  /** Route through injected fetchQuotaFn, or throw if unset. */
-  private _fetchQuota;
-  private static isAuthError;
-  /** Main quota failure: arms main-only backoff and persists via onApiError. */
-  private _handleMainFetchError;
-  /**
-   * Fallback quota failure: arms backoff for THIS account only. Never touches
-   * main backoff state and never calls onApiError (which persists the main
-   * quota error) — the per-account error is recorded by the caller via the
-   * account's lastQuotaRefreshError.
-   */
-  private _handleFallbackFetchError;
-}
-//#endregion
-//#region ../core/dist/paths.d.ts
-/**
- * The config file and the runtime-state file a store operation reads and writes.
- *
- * Both are required. A store function never derives one from the other, because
- * a host may point its state file somewhere the derivation would not reach and
- * a silently derived path would lock one file while writing another.
- */
-interface AccountPaths {
-  configPath: string;
-  statePath: string;
-}
-//#endregion
-//#region ../core/dist/accounts.d.ts
-type AccountQuotaWindow = {
-  usedPercent: number;
-  remainingPercent: number;
-  resetsAt?: string;
-  checkedAt: number;
-  windowMinutes?: number;
-};
-interface OAuthQuotaSnapshot {
-  primary?: AccountQuotaWindow;
-  secondary?: AccountQuotaWindow;
-  resetCreditsAvailable?: number;
-  resetCreditsApplicable?: number;
-}
-type AccountBase = {
-  id: string;
-  label?: string;
-  enabled?: boolean;
-  addedAt?: number;
-  lastUsed?: number;
-  /** Stable ChatGPT account identifier extracted from the OAuth token claims. */
-  accountId?: string;
-};
-type AccountOperationError = {
-  message: string;
-  checkedAt: number;
-  nextRetryAt?: number;
-  retryCount?: number;
-  tokenHash?: string;
+type EnterClaustrumModeDeps = {
+  accountIds: readonly string[];
+  acquireLock(options: {
+    name: string;
+    renew: boolean;
+  }): Promise<Release | null>;
+  withStoreTransaction(action: (transaction: AccountStoreTransaction) => Promise<TransitionResult>): Promise<TransitionResult>;
+  readManifest(): Promise<CustodyManifestReadResult>;
+  preflight(input: {
+    id: string;
+    accountId?: string;
+    handle: string;
+  }): Promise<Exclude<TransitionOutcome, `aborted:${string}` | 'tombstoned' | 'new-local-family-under-claustrum' | 'torn-read-deferred'>>;
+  auth: {
+    all(): Promise<Record<string, unknown>>;
+    get(input: {
+      path: {
+        id: string;
+      };
+    }): Promise<unknown>;
+    set(input: {
+      path: {
+        id: string;
+      };
+      body: {
+        type: 'oauth';
+        access: string;
+        refresh: string;
+        expires: number;
+      };
+    }): Promise<unknown>;
+  };
+  onStep?(step: string): void | Promise<void>;
+  warn?(message: string): void;
 };
-type OAuthAccount = AccountBase & {
-  type: 'oauth';
-  access?: string;
-  refresh: string;
-  expires?: number;
-  lastRefreshedAt?: number;
-  lastRefreshError?: AccountOperationError;
-  lastQuotaRefreshError?: AccountOperationError;
-  quota?: OAuthQuotaSnapshot;
+//#endregion
+//#region src/core/custody-runtime.d.ts
+type RuntimeLogger = {
+  info: (message: string, meta?: Record<string, unknown>) => void;
+  warn: (message: string, meta?: Record<string, unknown>) => void;
+  debug: (message: string, meta?: Record<string, unknown>) => void;
+  error: (message: string, meta?: Record<string, unknown>) => void;
 };
-type ApiKeyAccount = AccountBase & {
-  type: 'api';
-  apiKey?: string;
-  baseURL: string;
-  authHeader?: 'authorization-bearer' | 'x-api-key';
+type CustodyRuntimeOptions = {
+  /** Storage snapshot at loader time — used for the boot sweep pass. */
+  storage: AccountStorage | null;
+  configPath: string;
+  manifestPath?: string;
+  /** Test seam: the vendored detector. Production passes the real function. */
+  detectClaustrumConnection?: typeof detectClaustrumConnection;
+  /** Test seam: transport factory passed to `ClaustrumCredentialCache`. */
+  cacheConnector?: (options: {
+    connectionFile: string;
+    handshakeTimeoutMs?: number;
+  }) => Promise<ClaustrumCacheTransportLike>;
+  loadAccounts: typeof loadAccounts;
+  mutateAccounts: typeof mutateAccounts;
+  withAccountStoreTransaction: typeof withAccountStoreTransaction;
+  readCustodyManifest: typeof readCustodyManifest;
+  acquireRefreshFileLock: typeof acquireRefreshFileLock;
+  auth?: CustodyHostAuth;
+  resolveFallbackVaultState?: (input: {
+    accountId: string;
+    handle: string;
+  }) => Promise<VaultCustodyState>;
+  now?: () => number;
+  setIntervalFn?: (callback: () => void, intervalMs: number) => ReturnType<typeof setInterval>;
+  clearIntervalFn?: (handle: ReturnType<typeof setInterval>) => void;
+  onReconcileStep?: (step: 'discovery-lock-acquired' | 'enabled-manifest-join', accountId?: string) => void | Promise<void>;
+  logger: RuntimeLogger;
 };
-type FallbackAccount = OAuthAccount | ApiKeyAccount;
-type RoutingMode = 'main-first' | 'fallback-first' | 'sticky-balanced';
-type KillswitchThresholds = Partial<Record<QuotaWindowName | '5h' | '1w', number>>;
-type KillswitchConfig = {
-  enabled?: boolean;
-  main?: KillswitchThresholds;
-  accounts?: Record<string, KillswitchThresholds>;
+type ClaustrumCacheTransportLike = {
+  getCredential(handle: string, minTtlMs?: number): Promise<{
+    material: string;
+    recordVersion: number;
+    expiresAtMs: number | null;
+    accountId?: string;
+  }>;
+  statusCredential(handle: string): Promise<{
+    ready: boolean;
+    lastErrorCode: string | null;
+    leaseHeld: boolean;
+    recordVersion: number;
+  }>;
+  reportAuthFailure(params: {
+    handle: string;
+    providerStatus: number;
+    recordVersion: number;
+    reporterSource: 'direct' | 'relay_status_field' | 'relay_message_parse';
+  }): Promise<void>;
+  close(): void;
 };
-interface ResetInFlight {
-  redeemRequestId: string;
-  creditId: string;
-  startedAt: number;
-}
-interface ResetLastOutcome {
-  code: string;
-  at: number;
-  previousOutcome?: {
-    code: string;
-    at: number;
-  };
-}
-interface ResetAccountState {
-  inFlight?: ResetInFlight | Record<string, unknown>;
-  lastOutcome?: ResetLastOutcome;
-  cooldownUntil?: number;
-}
-type ResetStateByAccount = Record<string, ResetAccountState>;
-type AccountStorage = {
-  version: 1;
-  main?: {
-    type: 'opencode';
-    provider: 'openai';
-  };
-  routing?: {
-    mode?: RoutingMode;
-  };
-  fallbackOn?: number[];
-  refresh?: {
-    enabled?: boolean;
-    intervalMinutes?: number;
-    refreshBeforeExpiryMinutes?: number;
-    mainLastRefreshError?: AccountOperationError;
-    mainRefreshLeaseId?: string;
-    mainRefreshLeaseUntil?: number;
-    mainRefreshLeaseTokenHash?: string;
-  };
-  quota?: {
-    enabled?: boolean;
-    checkIntervalMinutes?: number;
-    refreshEveryNRequests?: number;
-    minimumRemaining?: Partial<Record<QuotaWindowName | '5h' | '1w', number>>;
-    failClosedOnUnknownQuota?: boolean;
-    showToasts?: boolean;
-    mainQuota?: OAuthQuotaSnapshot;
-    mainQuotaCheckedAt?: number;
-    mainQuotaToken?: string;
-    mainLastQuotaApiError?: AccountOperationError;
-  };
-  reset?: ResetStateByAccount;
-  dump?: {
-    enabled?: boolean;
-  };
-  costZeroing?: {
-    enabled?: boolean;
-  };
-  killswitch?: KillswitchConfig;
-  logging?: {
-    level?: string;
-  };
-  cachekeep?: {
-    enabled?: boolean;
-    subagents?: boolean;
-    sustain?: boolean;
-    /** Clock-hour window start (0-23, inclusive) — keeps cachekeep idle warming
-     *  inside `[startHour, endHour)` local hours. Omit to warm unconditionally. */
-    startHour?: number;
-    /** Clock-hour window end (0-23, exclusive) — must differ from startHour
-     *  to be honored; an unset or equal hour falls back to "always warm". */
-    endHour?: number;
-  };
-  /** Stable ChatGPT account identifier of the main account (extracted from OAuth token). */
-  mainAccountId?: string;
-  accounts: FallbackAccount[];
+type CustodyRuntime = {
+  /** Run the initial completion sweep. Resolves BEFORE the background refresh is armed. */
+  boot(): Promise<void>;
+  /** Clear the timer and close the cache + transport. Idempotent. */
+  dispose(): void;
+  /** Force one tick pass (used by the timer and tests). */
+  runTick(): Promise<void>;
+  /** Sync projection read for the sidebar writer. */
+  getCustodyProjection(account: OAuthAccount, now: number): SidebarAccountCustody | undefined;
+  /** Whether the custody runtime is enabled for this process. */
+  isEnabled(): boolean;
+  /** Cache handle (undefined when custody is disabled). */
+  getCache(): ClaustrumCredentialCache | undefined;
+  /** Connect the cache on demand and return it. */
+  ensureCache(): Promise<ClaustrumCredentialCache | undefined>;
+  /** Transport handle (undefined when custody is disabled). */
+  getTransport(): ClaustrumCacheTransportLike | undefined;
+  /** True if the detection step produced an `available` connection file. */
+  wasDetected(): boolean;
 };
-declare function loadAccounts(paths: AccountPaths): Promise<AccountStorage | null>;
-//#endregion
-//#region ../core/dist/oauth.d.ts
-interface IdTokenClaims {
-  chatgpt_account_id?: string;
-  email?: string;
-  organizations?: Array<{
-    id: string;
-  }>;
-  'https://api.openai.com/auth'?: {
-    chatgpt_account_id?: string;
-  };
-}
-export declare function parseJwtClaims(token: string): IdTokenClaims | undefined;
-export declare function extractAccountIdFromClaims(claims: IdTokenClaims): string | undefined;
-//#endregion
-//#region ../core/dist/commands.d.ts
-interface ResetTargetIdentity {
-  accountKey: string;
-  label: string;
-  accessToken: string;
-  chatgptAccountId?: string;
-}
+export declare function __createCustodyRuntimeForTest(options: CustodyRuntimeOptions): CustodyRuntime;
+export declare function __resetSweepFailureLogDedupeForTest(): void;
 //#endregion
 //#region src/index.d.ts
+/**
+ * Surfaced when a request would go to the wire with no credential.
+ *
+ * Fixed text on purpose. The host decides retries by matching this string
+ * (opencode v1.18.30, session/retry.ts), so no account label, provider wording
+ * or number may reach it - an operator-chosen id like `acct-429` would read as
+ * retryable and hide a local defect behind a retry loop. Details go to the
+ * transport log.
+ */
+export declare const EMPTY_BEARER_MESSAGE = "Refusing to send a request with no access token. This is a defect in the plugin, not a problem with the provider or the account; the transport log names the account and the path that produced it.";
+export declare const getMainRefreshLockName: () => string;
 export declare const MAIN_REFRESH_LOCK_TTL_MS: number;
 export declare const MAIN_REFRESH_LEASE_TTL_MS = 90000;
+export declare function __resetBootQuotaSeedForTest(): void;
 export declare class AuthPersistError extends Error {
   readonly code = "OPENAI_AUTH_PERSIST_FAILED";
   constructor(cause: unknown);
@@ -376,6 +171,13 @@ interface ResetTargetResolverDeps {
   accountStoragePath: string;
   accountStatePath: string;
   now: () => number;
+  isFallbackRefreshInert?: (account: OAuthAccount, storage: AccountStorage) => Promise<boolean>;
+  resolveFallbackAccess?: (account: OAuthAccount, storage: AccountStorage) => ReturnType<typeof resolveFallbackAccess>;
+  reportAuthFailure?: (params: {
+    handle: string;
+    providerStatus: number;
+    recordVersion: number;
+  }) => Promise<void>;
 }
 export declare function createResetTargetResolver(deps: ResetTargetResolverDeps): (accountKey: string) => Promise<ResetTargetIdentity>;
 export declare function buildResetRedemptionDeps(): {
@@ -388,10 +190,39 @@ interface CodexAuthPluginOptions {
   codexApiEndpoint?: string;
   experimentalWebSockets?: boolean;
   responsesLite?: boolean;
+  custody?: {
+    /** Test seam: the transport backing the loader-owned runtime. */
+    transport: ClaustrumCacheTransportLike;
+    /** Test seam: override the connection-file detection result. */
+    detection?: 'available' | 'absent';
+    /** Test seam: observes the loader-owned runtime for explicit ticks. */
+    onRuntime?: (runtime: CustodyRuntime) => void;
+    /** Test seam: controls the runtime clock for expiry-bound scenarios. */
+    now?: () => number;
+    /** Test seam: controls bounded host-write observation without real timers. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Test seam: observes a host-write observation deadline warning. */
+    warn?: (message: string) => void;
+    /** Test seam: observes the account lock around custody binding checks. */
+    withFallbackAccountLock?: CommandContext['withFallbackAccountLock'];
+    /** Test seam: replaces external OAuth I/O while preserving the hook callback. */
+    authorize?: {
+      browser?: () => Promise<{
+        url: string;
+        tokens: Promise<TokenResponse>;
+        cleanup?: () => void;
+      }>;
+      headless?: () => Promise<{
+        url: string;
+        instructions: string;
+        tokens: Promise<TokenResponse>;
+      }>;
+    };
+  };
 }
 export declare function findCachekeepFallbackAccount(accounts: FallbackAccount[], accountId: string): OAuthAccount | undefined;
 export declare function mergePushedQuotaMetadata(incoming: OAuthQuotaSnapshot, previous: OAuthQuotaSnapshot | undefined): OAuthQuotaSnapshot;
-export declare function buildSidebarMachineState(qm: QuotaManager, store: AccountStorage, now?: number, mainAccountIdentity?: string | undefined): SidebarMachineState;
+export declare function buildSidebarMachineState(qm: QuotaManager, store: AccountStorage, now?: number, mainAccountIdentity?: string | undefined, projectCustody?: (account: FallbackAccount, now: number) => SidebarAccountCustody | undefined): SidebarMachineState;
 export declare function buildSidebarState(qm: QuotaManager, store: AccountStorage, activeId: string, now?: number): SidebarState;
 export declare function resolveSidebarSessionId(headers: Headers): string | undefined;
 export declare function CodexAuthPlugin(input: PluginInput, options?: CodexAuthPluginOptions): Promise<Hooks>;
@@ -401,4 +232,4 @@ declare const _default: {
   server: Plugin;
 };
 //#endregion
-export { type IdTokenClaims, _default as default };
+export { type ClaustrumCacheTransportLike, type CustodyRuntime, type CustodyRuntimeOptions, type IdTokenClaims, _default as default, extractAccountIdFromClaims, parseJwtClaims };