Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

18.1 KB
Raw Blame
/**
 * ApiKeyCredentialProvider — the credential authority for API-key providers.
 *
 * Resolution order (ASYNC, memoized per provider):
 *   1. process.env[envVar]
 *   2. process.env[alias] for each alias
 *   3. getApiKey(envVar) — config.json apiKeys map
 *   4. macOS Keychain (lazy `security`, only when 1-3 missed AND the backend is on)
 *   5. 1Password (op:// — lazy SDK, only when 1-4 missed AND an op source exists)
 *
 * Keychain precedes 1Password because it is local, prompt-free once its ACL is
 * established, and ~17ms — where a 1Password resolve is a desktop-app handshake
 * that can be denied, and whose denials trip a 15-second machine-wide
 * suppression. Both remain BELOW env and config: a user who exports a key, or
 * types one into the config, means it.
 *
 * When step 4 or 5 resolves a key, the value is written THROUGH into process.env
 * so spawned child processes (MCP team/session) inherit it and never touch the
 * SDK or the keychain. The authority is the ONLY code that pushes keys from
 * either vault into process.env.
 *
 * `describeReadiness()` reports `present` / `absent` / `failed`, and
 * `isAvailable()` is its `=== "present"` projection. Steps 4 and 5 are the two
 * measured ways a REAL credential resolves to nothing — a locked or declined
 * keychain, a denied 1Password handshake — and both used to arrive here as a
 * bare `""`, indistinguishable from "this user has no key". That is what let a
 * flat-rate subscription be dropped from the routing chain and replaced by a
 * metered provider with nothing printed. The reason now survives; what routing
 * DOES with it is unchanged, since `failed` still projects to unavailable.
 *
 * `describeReadiness()` additionally honors one affordance the legacy oracle
 * granted:
 *   - `oauthFallback`: a `<file>` under ~/.claudish/ — if that OAuth credential
 *     file exists, the provider is available even without an env/config/op key.
 *
 * There used to be a second, `publicKeyFallback`, which made a provider report
 * available on the strength of a hardcoded literal token. It is gone: a keyless
 * provider declares `authScheme: "none"` instead, which is handled below and
 * says no credential is expected rather than inventing one.
 *
 * Resolution is memoized: the first await pays the env/config/op cost; later
 * reads return the cached result. `invalidate()` clears it (TUI hydrate-on-add).
 * An empty/failed op resolve is NOT cached as "" — it's cached as "unavailable"
 * only after the op source is consulted, and `invalidate()` re-opens it.
 */

import { existsSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { realValue } from "../../env-placeholder.js";
import {
  hasKeychainSource,
  recordKeychainHydratedVar,
  resolveKeychainKeyForEnvVars,
} from "./keychain-source.js";
import { resolveLocalApiKey } from "./local-api-key.js";
import { hasOpSources, resolveOpKeyForEnvVars } from "./op-source.js";
import type {
  CredentialProvider,
  ReadinessResult,
  RequestAuth,
  RequestAuthContext,
} from "./types.js";

/**
 * The outcome of one async key resolution: the key (possibly ""), plus WHY it
 * is empty when a credential STORE could not be consulted.
 *
 * `failure` is set only for "could not ask" — a keychain that would not answer,
 * a 1Password handshake that was denied or unavailable. It is deliberately NOT
 * set for "every source answered and none holds this key", which is an ordinary,
 * stable `absent` and must stay one: marking that `failed` would make every
 * provider the user has not configured report an error.
 */
interface KeyResolution {
  key: string;
  failure?: string;
}

export interface ApiKeyDescriptor {
  catalogName: string;
  envVar: string;
  aliases?: string[];
  /**
   * How to sign a request. `"none"` means this provider takes no credential at
   * all — see the class field of the same name for why that is distinct from
   * "the key happens to be empty".
   */
  authScheme?: "bearer" | "x-api-key" | "none";
  staticHeaders?: Record<string, string>;
  /**
   * OAuth credential filename under ~/.claudish/ (e.g. "codex-oauth.json"). If
   * the file exists, the provider counts as available even with no API key.
   * Mirrors ProviderDefinition.oauthFallback.
   */
  oauthFallback?: string;
  /**
   * SYNC resolver for a key the provider DECLARES in config rather than in an
   * env var — currently custom endpoints, whose `apiKey` field is a literal or
   * a `${VAR}` reference (config-schema.ts CustomEndpoint).
   *
   * Consulted LAST in the sync chain (after env → aliases → config.apiKeys) so
   * an explicit env/config value still overrides the declaration, and so the
   * op:// write-through mirror (process.env[CUSTOM_<NAME>_KEY]) keeps winning.
   *
   * MUST return undefined for an `op://` declaration: those are resolved by the
   * async op-source step below, and returning the literal ref here would short-
   * circuit it and sign requests with the string "op://…".
   */
  declaredKey?: () => string | undefined;
}

/**
 * An UNEXPANDED `${VAR}` placeholder is not a key — see `env-placeholder.ts` for
 * the rule and why it lives in its own module.
 *
 * Re-exported here because this was its original home and several call sites
 * (notably the sync readiness classifier in `tui/providers.ts`) import it from
 * this path. Keeping the re-export means the rule moved without a rename sweep,
 * and there is still exactly ONE implementation.
 */
export { realValue };

export class ApiKeyCredentialProvider implements CredentialProvider {
  readonly catalogName: string;
  private readonly envVar: string;
  private readonly aliases: string[];
  /**
   * `"none"` is NOT the same as "resolved an empty key", and conflating them is
   * what made keyless endpoints unreachable.
   *
   * An empty key means "a credential was expected and is missing" — the routing
   * pre-flight is right to reject that, because the request would 401. `"none"`
   * means "no credential was ever expected", so the provider is AVAILABLE with
   * nothing configured and its requests carry no auth header. The two need
   * different answers from `isAvailable()`, which is why this is a scheme rather
   * than a sentinel key value.
   */
  private readonly authScheme: "bearer" | "x-api-key" | "none";
  private readonly staticHeaders: Record<string, string>;
  private readonly oauthFallback?: string;
  private readonly declaredKey?: () => string | undefined;

  /** Memoized resolved key ("" = resolved-and-empty). undefined = not yet resolved. */
  private cachedKey: string | undefined;
  /**
   * In-flight resolution, so concurrent callers share one op pull.
   *
   * It carries the FAILURE alongside the key rather than leaving the reason in
   * an instance field: several callers share one resolution (a bare model name
   * credential-filters a whole chain, and the config TUI resolves ~16 providers
   * at once), so a field would be read by whichever caller happened to land
   * after the next resolution had already overwritten it.
   */
  private resolving: Promise<KeyResolution> | undefined;

  constructor(descriptor: ApiKeyDescriptor) {
    this.catalogName = descriptor.catalogName;
    this.envVar = descriptor.envVar;
    this.aliases = descriptor.aliases ?? [];
    this.authScheme = descriptor.authScheme ?? "bearer";
    this.staticHeaders = descriptor.staticHeaders ?? {};
    this.oauthFallback = descriptor.oauthFallback;
    this.declaredKey = descriptor.declaredKey;
  }

  /**
   * SYNC: env → aliases → config.json apiKeys → declared key (custom endpoints).
   * Does NOT touch 1Password.
   *
   * The first three steps are `resolveLocalApiKey` — shared verbatim with the
   * predefined-endpoint registration gate, which must answer "is this key
   * already here?" synchronously. Two implementations of that question is the
   * duplicate-oracle pattern the credential refactor deleted, so there is one.
   * The 4th step stays here because a config-DECLARED key is a custom-endpoint
   * concept with no meaning outside this class. realValue() applies at every
   * step (see local-api-key.ts): a placeholder must never shadow 1Password.
   */
  private resolveFromEnvConfig(): string | undefined {
    return (
      resolveLocalApiKey({ envVar: this.envVar, aliases: this.aliases }) ||
      realValue(this.resolveDeclared())
    );
  }

  /** The config-declared key (custom endpoints). Never throws. */
  private resolveDeclared(): string | undefined {
    try {
      return this.declaredKey?.() || undefined;
    } catch {
      return undefined;
    }
  }

  /** SYNC: does the oauthFallback credential file exist under ~/.claudish/? */
  private hasOauthFallbackFile(): boolean {
    if (!this.oauthFallback) return false;
    try {
      return existsSync(join(homedir(), ".claudish", this.oauthFallback));
    } catch {
      return false;
    }
  }

  /**
   * ASYNC resolved key: env → aliases → config → keychain → op:// (both lazy).
   * Memoized; each vault is consulted at most once. Writes a resolved key
   * THROUGH to process.env so spawned children inherit it.
   */
  private async resolveKey(opts?: { allowOpPrompt?: boolean }): Promise<string> {
    return (await this.resolveKeyDetailed(opts)).key;
  }

  /**
   * The same resolution, keeping the REASON an empty result is empty.
   *
   * Both vault steps below can come back with nothing for two different
   * reasons, and the old `Promise<string>` had one slot for both. "The keychain
   * is locked" and "there is no item for this variable" arrived as the same
   * `""`, so `isAvailable()` reported a subscriber with a perfectly good key as
   * uncredentialed, routing dropped the provider, and a metered vendor served
   * the request. The stores already distinguish the two — `{value?, failed}`
   * from the keychain, and now `onFailure` from the op source — so this method
   * carries the distinction up instead of flattening it.
   *
   * The failure is reported WITHOUT ever being cached: transience is the whole
   * point, and the existing "do not memoize a miss that might have been a
   * failure" rules below are what make the next call retry.
   */
  private async resolveKeyDetailed(opts?: { allowOpPrompt?: boolean }): Promise<KeyResolution> {
    // A cached key is a SETTLED answer — either a real value or a stable,
    // deliberately-memoized absence. Neither carries a failure, because the
    // rules below refuse to cache anything that might have been one.
    if (this.cachedKey !== undefined) return { key: this.cachedKey };
    if (this.resolving) return this.resolving;

    this.resolving = (async (): Promise<KeyResolution> => {
      // Steps 1-3: env / aliases / config — no SDK.
      const local = this.resolveFromEnvConfig();
      if (local) {
        this.cachedKey = local;
        return { key: local };
      }
      // Step 4: macOS Keychain, only if the backend is on (the sync sniff gates
      // the `security` spawn). Local and quiet, so it is tried before 1Password.
      let keychainFailure: string | undefined;
      if (hasKeychainSource()) {
        const kc = resolveKeychainKeyForEnvVars([this.envVar, ...this.aliases]);
        if (kc.value) {
          // Write-through mirror: child processes inherit this and re-resolve
          // nothing — the same contract the op step below honours.
          process.env[this.envVar] = kc.value;
          recordKeychainHydratedVar(this.envVar);
          this.cachedKey = kc.value;
          return { key: kc.value };
        }
        // A keychain MISS is stable (the item is genuinely absent) and may be
        // cached below. A keychain FAILURE — locked, or a declined ACL — is
        // transient and must not be, or one early stumble would mark this
        // provider unavailable for the rest of the process.
        if (kc.failed) {
          keychainFailure = kc.error
            ? `macOS Keychain could not be read: ${kc.error}`
            : "macOS Keychain could not be read";
        }
      }
      // Step 5: 1Password, only if a source exists (the sync sniff gates the SDK).
      if (hasOpSources()) {
        const wanted = new Set<string>([this.envVar, ...this.aliases]);
        // Capture the first swallowed reason. `onAuthFailure:"skip"` is right —
        // a credential backend having a bad day must not take down an MCP or
        // serve process — but skipping the ERROR is not the same as skipping
        // the exception, and this is where the two were conflated.
        let opFailure: string | undefined;
        const resolved = await resolveOpKeyForEnvVars(wanted, {
          onAuthFailure: "skip",
          allowPrompt: opts?.allowOpPrompt ?? false,
          onFailure: (reason) => {
            opFailure ??= reason;
          },
        });
        const value =
          resolved[this.envVar] ?? this.aliases.map((a) => resolved[a]).find((v) => !!v);
        if (value) {
          // Write-through mirror: child processes inherit this, no re-resolve.
          process.env[this.envVar] = value;
          this.cachedKey = value;
          return { key: value };
        }
        // op source EXISTS but resolution came back empty — this can be a
        // TRANSIENT op-auth failure (onAuthFailure:"skip" swallows it). Do NOT
        // cache the miss, or a single early failure would mark the provider
        // permanently unavailable. Return "" WITHOUT caching so the next call
        // retries (e.g. once the 1Password desktop handshake completes).
        //
        // The keychain failure is reported only when 1Password did not fail
        // too: one reason is a remedy the user can act on, two are a list to
        // triage. 1Password wins because it is the step that actually answered
        // last for this key.
        return { key: "", failure: opFailure ?? keychainFailure };
      }
      // No op source at all → the empty result is stable and safe to cache,
      // UNLESS the keychain step above failed rather than simply missing: that
      // failure is transient, so leave the result uncached and let the next
      // call retry once the keychain is unlocked.
      if (!keychainFailure) this.cachedKey = "";
      return { key: "", failure: keychainFailure };
    })();

    try {
      return await this.resolving;
    } finally {
      this.resolving = undefined;
    }
  }

  /**
   * Three-valued readiness. `isAvailable()` below is its `=== "present"`
   * projection, so the two cannot disagree about whether this provider routes.
   *
   * The ORDER of the cheap checks is the same as it always was, and it matters
   * for more than speed: a key already in env/config, or an oauth file on disk,
   * makes the provider `present` without ever touching a vault — so a broken
   * keychain or a denied 1Password cannot downgrade a provider that was never
   * going to ask them.
   */
  async describeReadiness(opts?: { allowOpPrompt?: boolean }): Promise<ReadinessResult> {
    // A provider that takes no credential is always available. Checked FIRST and
    // before any resolution, because there is nothing to resolve: reaching the
    // env/config/oauth/1Password chain for it would be pure cost, and on the
    // 1Password step a real prompt for a key that does not exist.
    if (this.authScheme === "none") return { readiness: "present" };
    // Cheap checks first — avoid the op pull when an oauth file already qualifies.
    if (this.resolveFromEnvConfig()) return { readiness: "present" };
    if (this.hasOauthFallbackFile()) return { readiness: "present" };
    const { key, failure } = await this.resolveKeyDetailed(opts);
    if (key) return { readiness: "present" };
    // No key AND no failure means every store answered and none holds one —
    // which is the ordinary state of every provider the user has not set up,
    // and must stay `absent`.
    return failure ? { readiness: "failed", detail: failure } : { readiness: "absent" };
  }

  async isAvailable(opts?: { allowOpPrompt?: boolean }): Promise<boolean> {
    return (await this.describeReadiness(opts)).readiness === "present";
  }

  invalidate(): void {
    this.cachedKey = undefined;
    this.resolving = undefined;
  }

  async getRequestAuth(ctx: RequestAuthContext): Promise<RequestAuth> {
    // No credential expected → send the static headers and nothing else. Returns
    // before any resolution for the same reason isAvailable does.
    //
    // This is also why `"none"` could not be expressed by leaving the key empty:
    // the `x-api-key` branch below emits the header UNCONDITIONALLY, so an empty
    // key under that scheme would put a literal `x-api-key: ` on the wire — worse
    // than no header, since a gateway that ignores unknown auth may still reject
    // a malformed one.
    if (this.authScheme === "none") {
      // Deliberately UNMARKED (no `arm`). No credential arm answered here — the
      // provider declares it needs none — and "unknown" is the honest value. A
      // consumer that maps arms to money reads unknown as the paid answer, which
      // is the safe direction.
      return { headers: { ...this.staticHeaders } };
    }
    // No invented fallback: a provider that resolves nothing signs with nothing,
    // and the routing pre-flight is right to reject that as "no credential"
    // rather than send a guessed token and collect a 401 downstream. A provider
    // that genuinely needs no credential says so with `authScheme: "none"`,
    // which returned above.
    const key = await this.resolveKey({ allowOpPrompt: ctx.allowOpPrompt });
    let headers: Record<string, string>;
    if (this.authScheme === "x-api-key") {
      headers = { "x-api-key": key, ...this.staticHeaders };
    } else if (key) {
      headers = { Authorization: `Bearer ${key}`, ...this.staticHeaders };
    } else {
      headers = { ...this.staticHeaders };
    }
    // Stamped on EVERY return of this branch, including the keyless one above
    // (`headers = {...staticHeaders}` — an artifact with no Authorization at all).
    // That is the point: this method never returns null and never throws, so
    // "something came back" says nothing about which arm won. Only this marker
    // does. See CompositeCredentialProvider.getRequestAuth and
    // OpenAICodexTransport.refreshAuth.
    return { arm: "api-key", headers };
  }
}