Skip to content

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

13.9 KB
Raw Blame
/**
 * API Key Provenance — traces where an API key comes from across all resolution layers.
 *
 * Resolution order (first non-empty wins):
 *   1. process.env (shell profile, e.g. ~/.config/env-keys.sh sourced by .zshenv)
 *   2. .env file in CWD (loaded at startup through the allowlist in dotenv-allowlist.ts,
 *      does NOT override existing env vars; read here through the same allowlist)
 *   3. ~/.claudish/config.json apiKeys (loaded at startup, does NOT override existing env vars)
 *
 * Since dotenv and config.json never override, the value in process.env at runtime
 * always comes from whichever source set it first. This module inspects all three
 * sources independently so the user can see what WOULD have been used from each layer.
 *
 * Layer 3 follows the `--config <file>` override (config-override.ts): provenance
 * must read the SAME file the credential authority resolves from, and the layer is
 * labeled with the override's real path so the UI names the file actually in play.
 *
 * VAULT-HYDRATED VALUES: the macOS Keychain and 1Password both deliver their keys
 * by write-through into process.env, so by the time this inspects layer 3 they are
 * indistinguishable from a shell export. Neither can be re-read here cheaply (and
 * re-reading 1Password could prompt), so origin is recovered from the run-scoped
 * records the authority keeps — `isKeychainHydratedVar` / `isOpHydratedVar` — and
 * reported by name rather than as "shell environment".
 */

import { existsSync, readFileSync } from "node:fs";
import { homedir } from "node:os";
import { join, resolve } from "node:path";
import { isKeychainHydratedVar } from "../auth/credentials/keychain-source.js";
import {
  VERTEX_NO_PROJECT_REMEDY,
  VERTEX_PROJECT_ENV_VARS,
  adcCredentialsPath,
  describeVertexProjectSource,
  peekVertexAdcProject,
  peekVertexProjectOrigin,
} from "../auth/vertex-auth.js";
import { activeGlobalConfigFile, getConfigFileOverride } from "../config-override.js";
import { readAllowedDotenv } from "../dotenv-allowlist.js";
import { isOpHydratedVar } from "./onepassword.js";

/**
 * The global config file this run actually reads. Under a `--config` override
 * that is the override file, NOT the machine one — provenance must inspect the
 * same file the credential authority resolves from, or it mislabels an override
 * key as "shell environment".
 */
function activeConfigPath(): string {
  return activeGlobalConfigFile(join(homedir(), ".claudish", "config.json"));
}

/** Display label for the config layer: the real path when overridden, else the tilde form. */
function configLayerLabel(): string {
  return getConfigFileOverride() ? activeConfigPath() : "~/.claudish/config.json";
}

/**
 * A single resolution layer.
 *
 * SECURITY: `maskedValue` is the ONLY value-derived field. A raw secret must
 * never be stored here — `KeyLayer` is embedded in `KeyProvenance`, which is
 * serialized wholesale by `--probe --json`.
 */
export interface KeyLayer {
  source: string;
  maskedValue: string | null;
  isActive: boolean;
}

/**
 * Where an API key comes from — a REPORTING record, not a credential carrier.
 *
 * SECURITY: this object is serialized wholesale (`--probe --json` prints it via
 * `JSON.stringify`), so it must NEVER hold plaintext key material. It carries
 * presence (`hasValue`), a display mask (`effectiveMasked`), the env-var NAME,
 * and the source label — nothing else. Callers that genuinely need the secret
 * must read it from the credential authority (`auth/credentials/`) directly;
 * do not reintroduce a value field here under any name.
 */
export interface KeyProvenance {
  envVar: string;
  /** True when a key resolved from some layer. Presence only — never the value. */
  hasValue: boolean;
  effectiveMasked: string | null;
  effectiveSource: string;
  layers: KeyLayer[];
  /**
   * What to print INSTEAD of `$envVar` when the credential did not come from an
   * environment variable at all.
   *
   * Undefined for every provider whose credential is an env-var API key — which
   * is all but one — so their lines are unchanged. It exists because Vertex has
   * no API key: it authenticates with Application Default Credentials and
   * addresses a Google Cloud project that may come from the ADC file or
   * `gcloud config`, and a row reading `$VERTEX_PROJECT (not set)` about a
   * working install is worse than no row at all.
   *
   * SECURITY: display-safe by construction, like `effectiveMasked`. A builder
   * that sets it must put no key material in it. Vertex's is a GCP project id,
   * which is an identifier rather than a secret — it appears in every Vertex
   * request URL and in the proxy's own handler log line — so it is shown whole:
   * masking it would hide the one fact the row exists to report, WHICH project
   * this machine will bill.
   */
  effectiveLabel?: string;
}

function maskKey(key: string | undefined | null): string | null {
  if (!key) return null;
  if (key.length <= 8) return "***";
  return `${key.substring(0, 8)}...`;
}

/**
 * Resolve the provenance of an API key by checking all possible sources.
 *
 * @param envVar - Primary env var name (e.g. "GEMINI_API_KEY")
 * @param aliases - Alternative env var names to check
 */
export function resolveApiKeyProvenance(envVar: string, aliases?: string[]): KeyProvenance {
  const layers: KeyLayer[] = [];
  let effectiveSource = "not set";

  // Check all env var names (primary + aliases)
  const allVars = [envVar, ...(aliases || [])];

  // Layer 1: .env file in CWD
  const dotenvValue = readDotenvKey(allVars);
  layers.push({
    source: `.env (${resolve(".env")})`,
    maskedValue: maskKey(dotenvValue),
    isActive: false, // determined below
  });

  // Layer 2: the active global config (the --config override file when set)
  const configValue = readConfigKey(envVar);
  layers.push({
    source: configLayerLabel(),
    maskedValue: maskKey(configValue),
    isActive: false,
  });

  // Layer 3: process.env (final runtime value — includes shell profile, dotenv, config.json)
  // Check aliases too
  let runtimeVar = envVar;
  let runtimeValue = process.env[envVar] || null;
  if (!runtimeValue && aliases) {
    for (const alias of aliases) {
      if (process.env[alias]) {
        runtimeVar = alias;
        runtimeValue = process.env[alias]!;
        break;
      }
    }
  }

  layers.push({
    source: `process.env[${runtimeVar}]`,
    maskedValue: maskKey(runtimeValue),
    isActive: !!runtimeValue,
  });

  // Determine which source is active
  if (runtimeValue) {
    if (dotenvValue && dotenvValue === runtimeValue) {
      effectiveSource = ".env";
      layers[0].isActive = true;
      layers[2].isActive = false;
    } else if (configValue && configValue === runtimeValue) {
      effectiveSource = configLayerLabel();
      layers[1].isActive = true;
      layers[2].isActive = false;
    } else if (isKeychainHydratedVar(runtimeVar)) {
      // In process.env, but put there by the keychain step of the credential
      // authority (or the TUI's startup hydration) — not a genuine shell export.
      // Checked BEFORE the 1Password branch because the keychain is resolved
      // first, so a variable both stores could supply was supplied by this one.
      effectiveSource = "macOS Keychain";
      layers[2].source = `process.env[${runtimeVar}] (from macOS Keychain)`;
    } else if (isOpHydratedVar(runtimeVar)) {
      // The value sits in process.env, but it was hydrated from 1Password at
      // startup (op:// ref, glob import, or Environment) — not a genuine shell
      // env var. Report the true origin so the UI doesn't mislabel it "env".
      effectiveSource = "1Password";
      layers[2].source = `process.env[${runtimeVar}] (from 1Password)`;
      // layers[2] already marked active
    } else {
      effectiveSource = "shell environment";
      // layers[2] already marked active
    }
  }

  // NOTE: `runtimeValue` stays local. It is deliberately NOT placed on the
  // returned record — see the KeyProvenance doc comment.
  return {
    envVar: runtimeVar,
    hasValue: !!runtimeValue,
    effectiveMasked: maskKey(runtimeValue),
    effectiveSource,
    layers,
  };
}

/**
 * Provenance for ONE provider's credential — the entry point every display
 * surface should call.
 *
 * Identical to {@link resolveApiKeyProvenance} for every provider whose
 * credential is an env-var API key. It exists for the one that is not: Vertex
 * resolves a PROJECT (not a key) from the environment, the ADC file's
 * `quota_project_id`, or `gcloud config`, so the env/config layers alone report
 * "not set" about an install that works perfectly.
 *
 * The branch lives here, in the module that owns provenance, rather than in each
 * of the four call sites (`--probe`'s three chain builders and the handler log).
 * Four copies of one provider rule is the second-table coupling this codebase
 * keeps paying for.
 */
export function resolveCredentialProvenance(
  provider: string,
  envVar: string,
  aliases?: string[]
): KeyProvenance {
  if (provider === "vertex") return vertexProjectProvenance(envVar, aliases);
  return resolveApiKeyProvenance(envVar, aliases);
}

/**
 * Vertex's provenance: the env/config layers, PLUS the two tiers
 * `resolveVertexConfig` consults that no environment inspection can see.
 *
 * `GOOGLE_CLOUD_PROJECT` is passed as an alias because `resolveVertexConfig`
 * reads it — not because `API_KEY_MAP` lists it. The variable list comes from
 * `VERTEX_PROJECT_ENV_VARS`, the same constant the resolution uses, so this
 * cannot drift from what actually decides the project.
 *
 * The non-env tiers are read through `peekVertexProjectOrigin`, which is sync
 * and never shells out; a project that only `gcloud config` knows therefore
 * shows up here once anything async (the credential authority, a probe, a real
 * request) has resolved it. Until then this reports the honest "no project yet"
 * with both remedies, never a missing API key.
 */
function vertexProjectProvenance(envVar: string, aliases?: string[]): KeyProvenance {
  const envNames = [...new Set([envVar, ...(aliases ?? []), ...VERTEX_PROJECT_ENV_VARS])];
  const base = resolveApiKeyProvenance(envNames[0], envNames.slice(1));
  const origin = peekVertexProjectOrigin();
  // Always shown, value included when known, so a project the ADC file holds is
  // visible even while an env var shadows it — the same "(shadowed)" honesty the
  // config layer already gets.
  const adc = peekVertexAdcProject();
  const adcLayer: KeyLayer = {
    source: `${adcCredentialsPath()} (quota_project_id)`,
    maskedValue: adc?.projectId ?? null,
    isActive: origin?.source === "adc-file",
  };
  const gcloudLayer: KeyLayer = {
    source: "`gcloud config get project`",
    maskedValue: origin?.source === "gcloud-config" ? origin.projectId : null,
    isActive: origin?.source === "gcloud-config",
  };

  if (!origin) {
    return {
      ...base,
      hasValue: false,
      effectiveMasked: null,
      effectiveLabel: "no project",
      effectiveSource: VERTEX_NO_PROJECT_REMEDY,
      layers: [...base.layers, adcLayer, gcloudLayer],
    };
  }
  if (origin.source === "env") {
    // The env tiers are exactly what `resolveApiKeyProvenance` already models —
    // including .env and the config file, which reach Vertex the same way they
    // reach any other provider. Only the two extra layers are appended.
    return { ...base, layers: [...base.layers, adcLayer, gcloudLayer] };
  }
  return {
    ...base,
    hasValue: true,
    // The project id, whole and unmasked — see `KeyProvenance.effectiveLabel`.
    effectiveMasked: origin.projectId,
    effectiveLabel: `project ${origin.projectId}`,
    effectiveSource: describeVertexProjectSource(origin),
    // Nothing in the environment supplied the value, so no env layer is active.
    layers: [...base.layers.map((l) => ({ ...l, isActive: false })), adcLayer, gcloudLayer],
  };
}

/**
 * Format provenance for debug log output (single line).
 */
export function formatProvenanceLog(p: KeyProvenance): string {
  if (!p.hasValue) {
    return p.effectiveLabel ? `${p.effectiveLabel}: ${p.effectiveSource}` : `${p.envVar}=(not set)`;
  }
  if (p.effectiveLabel) {
    return `${p.effectiveLabel} [from: ${p.effectiveSource}]`;
  }
  return `${p.envVar}=${p.effectiveMasked} [from: ${p.effectiveSource}]`;
}

/**
 * Format provenance for --probe TUI output (multi-line with all layers).
 */
export function formatProvenanceProbe(p: KeyProvenance, indent = "    "): string[] {
  const lines: string[] = [];

  if (!p.hasValue) {
    // `effectiveLabel` carries the remedy for a provider with no env-var key at
    // all (Vertex), where "VERTEX_PROJECT: not set" is the wrong instruction.
    lines.push(
      p.effectiveLabel
        ? `${indent}${p.effectiveLabel}: ${p.effectiveSource}`
        : `${indent}${p.envVar}: not set`
    );
    return lines;
  }

  lines.push(
    p.effectiveLabel
      ? `${indent}${p.effectiveLabel}  [from: ${p.effectiveSource}]`
      : `${indent}${p.envVar} = ${p.effectiveMasked}  [from: ${p.effectiveSource}]`
  );

  for (const layer of p.layers) {
    const marker = layer.isActive ? ">>>" : "   ";
    const value = layer.maskedValue || "(not set)";
    lines.push(`${indent}  ${marker} ${layer.source}: ${value}`);
  }

  return lines;
}

// ---------------------------------------------------------------------------
// Internal helpers
// ---------------------------------------------------------------------------

function readDotenvKey(envVars: string[]): string | null {
  try {
    const dotenvPath = resolve(".env");
    if (!existsSync(dotenvPath)) return null;
    const parsed = readAllowedDotenv(readFileSync(dotenvPath, "utf-8"));
    for (const v of envVars) {
      if (parsed[v]) return parsed[v];
    }
    return null;
  } catch {
    return null;
  }
}

function readConfigKey(envVar: string): string | null {
  try {
    const configPath = activeConfigPath();
    if (!existsSync(configPath)) return null;
    const cfg = JSON.parse(readFileSync(configPath, "utf-8")) as {
      apiKeys?: Record<string, string>;
    };
    return cfg.apiKeys?.[envVar] || null;
  } catch {
    return null;
  }
}