Skip to content

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

13.1 KB
Raw Blame
/**
 * keychain-source — the lazy macOS Keychain seam BEHIND the credential authority.
 *
 * The single place that knows how to pull a provider's API key out of the macOS
 * Keychain on demand. The authority calls `resolveKeychainKeyForEnvVars(wanted)`
 * only when env / aliases / config have all missed — so a user whose key is
 * already in the shell environment never spawns `security` at all.
 *
 * LAZINESS GATE: `hasKeychainSource()` is a cheap SYNC sniff — the platform,
 * plus one boolean in `config.json`. It returns false WITHOUT touching the
 * keychain when the backend was never opted into, which is the whole reason the
 * `keychain.enabled` flag exists. Deliberately parallel to `hasOpSources()`.
 *
 * ORDER: this source is consulted BEFORE 1Password. The keychain is local,
 * costs ~17ms, and once its ACL is established it never prompts; a 1Password
 * resolve is a desktop-app handshake that can be denied, and a burst of denials
 * trips a 15-second machine-wide suppression (see architecture/onepassword.md).
 * Cheap and quiet goes first. An explicit env var or a config-stored key still
 * wins over both — a user who exports a key means it.
 *
 * WRITE-THROUGH, AND WHY THERE IS NO NEW `CredentialSource` MEMBER:
 * a resolved keychain value is written into `process.env` by the authority, the
 * same mechanism 1Password already uses. The strings in `CredentialSource` are
 * a WIRE CONTRACT consumed by the external profiles app through
 * `claudish providers --json` (see source.ts), so a keychain key reports "env"
 * — which is literally true once it has been written through. Origin is tracked
 * separately here, for display only, via `isKeychainHydratedVar`.
 */

import { isKeychainEnabled } from "../../profile-config.js";
import {
  KeychainError,
  enumerateKeychainVars,
  isKeychainSupported,
  lookupKeychainVar,
  readKeychainSecret,
  readKeychainSecretAsync,
} from "../../providers/keychain.js";
import { resolveLocalApiKey } from "./local-api-key.js";

/**
 * Warn ONCE per process per distinct message.
 *
 * A bare model name credential-filters a routing CHAIN, so one process asks the
 * authority about several candidate providers. When the keychain is failing —
 * locked, or an ACL the user declined — every one of those asks fails
 * identically, and one line each reads as a cascade of distinct problems rather
 * than the single condition it is. Same rationale as op-source's warnOnce.
 *
 * Message text only; no key material is ever part of these strings.
 */
const warnedMessages = new Set<string>();

function warnOnce(message: string): void {
  if (warnedMessages.has(message)) return;
  warnedMessages.add(message);
  console.error(message);
}

/**
 * Env vars whose runtime value came from the keychain THIS run.
 *
 * Run-scoped and in-memory, mirroring `recordOpHydratedVars`. Reporting only —
 * it holds NAMES, never values — so provenance can say "keychain" instead of
 * mislabelling a hydrated variable as a shell export.
 */
const hydratedVars = new Set<string>();

/** Record that `envVar`'s runtime value was hydrated from the keychain. */
export function recordKeychainHydratedVar(envVar: string): void {
  hydratedVars.add(envVar);
}

/** Did `envVar`'s runtime value come from the keychain this run? */
export function isKeychainHydratedVar(envVar: string): boolean {
  return hydratedVars.has(envVar);
}

/** Test seam: forget this run's hydration record. */
export function resetKeychainHydrationRecord(): void {
  hydratedVars.clear();
}

/**
 * SYNC laziness gate: is there any point asking the keychain?
 *
 * Platform + one config boolean. No spawn, no I/O beyond the config read the
 * caller is doing anyway. False for every user who has not opted in.
 */
export function hasKeychainSource(): boolean {
  // Production escape hatch, mirroring CLAUDISH_DISABLE_OP for 1Password.
  //
  // It exists for the same reason: a test that reaches a real credential store
  // is not hermetic, and `mock.module` cannot be used to prevent it because
  // Bun's module registry is process-global and the stub bleeds into sibling
  // files. A flag the PRODUCTION code honours is the only stub that cannot leak.
  //
  // Needed here specifically because `isKeychainEnabled()` reads the real
  // ~/.claudish/config.json whenever no `--config` override is active — so a
  // test run without the guard would spawn `security` against the developer's
  // own login keychain. Set it in any suite that does not install a config
  // override.
  if (process.env.CLAUDISH_DISABLE_KEYCHAIN === "1") return false;
  if (!isKeychainSupported()) return false;
  return isKeychainEnabled();
}

/**
 * Outcome of a keychain resolve.
 *
 * `failed` is what separates "there is no item for this variable" from "the
 * keychain could not be asked" — a locked keychain, or an ACL the user
 * declined. The distinction is load-bearing for CACHING: an absent item is a
 * stable answer worth remembering, while a failure is transient and must be
 * retried, or one early stumble would mark a provider unavailable for the rest
 * of the process. The op source draws the same line for denied handshakes.
 */
export interface KeychainResolveResult {
  value?: string;
  /** True when the keychain could not be consulted (NOT when it simply had no item). */
  failed: boolean;
  /**
   * One-line diagnostic for `failed`, taken from the engine's own
   * `KeychainEnumeration.error` (`security`'s stderr, or the exit code when it
   * said nothing). Present only when `failed` is true, and never key material —
   * enumeration runs `dump-keychain` WITHOUT `-d`, so it never reads item data.
   *
   * It exists so the caller can say WHICH store was unreachable rather than
   * "unavailable". The authority turns this into a `failed` readiness detail,
   * which is the difference between telling a user to unlock their keychain and
   * telling them to buy a subscription they already have.
   */
  error?: string;
}

/**
 * The first stored value among `wanted` (primary env var, then aliases).
 *
 * Presence is checked through `keychainHasVar` — ONE `dump-keychain` for the
 * whole item list — before any value read, so a provider with nothing stored
 * costs no per-variable spawn at all. Only a name that IS present pays the
 * ~17ms value lookup.
 *
 * NEVER THROWS, AND IT NEVER HAD TO. A failure is DATA here — `failed` plus
 * `error` — not an exception and not a silent `undefined`. That distinction is
 * the whole point: throwing would force every caller into a try/catch whose
 * only honest outcome is the same flag, and returning a bare "no value" is what
 * turned a locked keychain into "this user has no credential" and moved a
 * flat-rate subscriber onto a metered provider without a word. A keychain
 * failure still degrades this provider to "no credential" for THIS resolve, so
 * the caller falls through to 1Password and a proxy or MCP server keeps running
 * — the same policy op-source applies under `onAuthFailure: "skip"`. What
 * changes is that the caller can now tell the two apart and say so.
 */
export function resolveKeychainKeyForEnvVars(wanted: Iterable<string>): KeychainResolveResult {
  if (!hasKeychainSource()) return { failed: false };
  let failed = false;
  try {
    for (const name of wanted) {
      if (!name) continue;
      const { present, failed: lookupFailed } = lookupKeychainVar(name);
      // An enumeration that could NOT run is not evidence of absence. Remember
      // it and report it, or the authority caches this provider as permanently
      // credential-less on the strength of a keychain we never managed to read.
      if (lookupFailed) failed = true;
      if (!present) continue;
      const value = readKeychainSecret(name);
      if (value) return { value, failed: false };
    }
  } catch (err) {
    const detail = err instanceof KeychainError ? err.message : String(err);
    warnOnce(`[claudish] macOS Keychain lookup skipped: ${detail}`);
    return { failed: true, error: detail };
  }
  if (failed) {
    warnOnce(
      "[claudish] macOS Keychain could not be enumerated — treating this provider as unresolved rather than uncredentialed."
    );
    // The engine already recorded WHY, and this read is normally a memo hit: the
    // same `enumerateKeychainVars()` call `lookupKeychainVar` just made is inside
    // the 3-second burst window, so asking for its diagnostic costs no extra spawn.
    // Taking the reason from the engine rather than re-deriving it here keeps
    // one description of the failure instead of two that can disagree.
    return { failed: true, error: keychainFailureDetail() };
  }
  return { failed };
}

/**
 * The engine's own reason the keychain could not be enumerated, if it still has
 * one. Never throws. Called straight after `lookupKeychainVar` enumerated, so it
 * is a memo hit inside the 3-second burst window; only if that window closed in
 * between does it re-run the one `dump-keychain` the lookup already made. A
 * re-read that now succeeds yields `undefined`, and a `failed` readiness without
 * a detail is still a correct `failed`.
 */
function keychainFailureDetail(): string | undefined {
  try {
    const listed = enumerateKeychainVars();
    return listed.failed ? listed.error : undefined;
  } catch {
    return undefined;
  }
}

/**
 * Load every stored keychain secret into `process.env`, gap-filling only.
 *
 * WHY THIS EXISTS: `describeSourceSync` cannot await, so the config TUI's
 * readiness dots, "configured first" sort and not-configured divider would all
 * report a keychain-only provider as unconfigured until something happened to
 * resolve it. Hydrating up front is exactly how 1Password's keys become visible
 * to the same sync rules — the classifier sees a real `process.env` entry, and
 * reports "env", which by then it is.
 *
 * GAP-FILL, NEVER OVERWRITE: a variable already present in the environment was
 * put there by the user's shell (or by an earlier, higher-priority source), and
 * silently replacing it would invert the documented precedence — env beats
 * keychain, always.
 *
 * IT MUST SKIP CONFIG-STORED KEYS TOO, and that is less obvious. `config.json`
 * outranks the keychain in the resolution chain, but it is NOT in `process.env`
 * — so hydrating on "absent from env" alone would push the keychain value into
 * env, where step 1 of the chain finds it FIRST and the config key that should
 * have won is never consulted. The config TUI would then sign requests with a
 * different credential than the same machine uses outside the TUI. Filtering on
 * `resolveLocalApiKey` rather than on `process.env` keeps the two identical.
 *
 * PARALLEL: reads run concurrently, so ten stored keys cost roughly one read's
 * wall clock (~30ms) rather than ten (~170ms).
 *
 * @returns the number of variables actually hydrated.
 */
export async function hydrateKeychainIntoEnv(): Promise<number> {
  if (!hasKeychainSource()) return 0;
  let names: string[];
  try {
    const listed = enumerateKeychainVars();
    if (listed.failed) {
      warnOnce(`[claudish] macOS Keychain enumeration skipped: ${listed.error ?? "unknown error"}`);
      return 0;
    }
    names = listed.names;
  } catch (err) {
    warnOnce(`[claudish] macOS Keychain enumeration skipped: ${String(err)}`);
    return 0;
  }

  // `resolveLocalApiKey` is steps 1-3 of the authority's own chain (env →
  // aliases → config.apiKeys) — the exact set of sources that outrank the
  // keychain. Anything it can already answer must be left alone.
  const missing = names.filter((n) => !resolveLocalApiKey({ envVar: n }));
  if (missing.length === 0) return 0;

  const results = await Promise.all(
    missing.map(async (name) => {
      try {
        return { name, value: await readKeychainSecretAsync(name) };
      } catch (err) {
        warnOnce(
          `[claudish] macOS Keychain read for ${name} skipped: ${err instanceof KeychainError ? err.message : String(err)}`
        );
        return { name, value: null };
      }
    })
  );

  let hydrated = 0;
  for (const { name, value } of results) {
    // Re-check against the SAME higher-priority sources, not just process.env:
    // another source may have filled it while we awaited, and config still
    // outranks us.
    if (!value || resolveLocalApiKey({ envVar: name })) continue;
    process.env[name] = value;
    recordKeychainHydratedVar(name);
    hydrated++;
  }
  return hydrated;
}

/**
 * SYNC presence check for the predefined-endpoint registration gate.
 *
 * Registration cannot await, and it must decide whether a bundled vendor row is
 * worth registering at all. `keychainHasVar` answers from the single enumerate
 * call, so this stays affordable however many providers ask.
 *
 * Presence ONLY — deliberately not a value. `resolveLocalApiKey` remains the
 * one oracle for what a request is actually signed with, and widening THAT
 * would change key resolution for every provider in the authority at once.
 */
export function keychainHasAnyOf(names: Iterable<string>): boolean {
  if (!hasKeychainSource()) return false;
  try {
    for (const name of names) {
      if (name && lookupKeychainVar(name).present) return true;
    }
  } catch {
    // Enumeration failure → "nothing stored". Never blocks registration.
  }
  return false;
}