chainlesschain 0.162.159 → 0.162.161

package/src/lib/capability-negotiation.js

@@ -0,0 +1,212 @@
+/**
+ * Bidirectional capability negotiation with N / N-1 downgrade for Agent
+ * Protocol (agent-sdk docs/PROTOCOL.md §1.3).
+ *
+ * The CLI advertises what it can speak one-directionally (buildAgentCapabilities
+ * → `cc agent --capabilities`, and the `system/init` line's protocol_version).
+ * That is not negotiation: a client (VS Code / JetBrains panel) had no way to
+ * announce what IT understands, and the CLI had no rule to pick a common level
+ * or step DOWN when the two disagree. When the protocol later grows a v2 line
+ * shape, a v1-only client would silently mis-parse it.
+ *
+ * This module is the missing algorithm. A client MAY send a `hello` as its
+ * first stream-json input line:
+ *   {"type":"hello","protocol_version":2,"min_protocol_version":1,
+ *    "features":["event_seq","trace_id"]}
+ * The CLI negotiates it against its own offer and echoes the agreed level as a
+ * `system/negotiated` line, then honors it for the rest of the run.
+ *
+ * Rules:
+ *   - agreedVersion = min(server.max, client.max)  — never above what either
+ *     can parse.
+ *   - Incompatible when agreedVersion < max(server.min, client.min): the two
+ *     version ranges don't overlap. ok:false — the caller keeps a safe baseline
+ *     or errors out; it never speaks a version the peer can't read.
+ *   - effective features = the server-offered features the client also accepts
+ *     (intersection), minus any whose minimum protocol version is above the
+ *     agreed version (an N-only field is dropped for an N-1 session).
+ *   - No client offer at all → legacy client that predates negotiation. The
+ *     additive fields are defined "consumers MUST tolerate absence AND
+ *     presence" (docs/PROTOCOL.md §1.2.1), so we keep FULL behavior unchanged
+ *     (byte-for-byte) and mark clientAware:false. Negotiation only ever
+ *     RESTRICTS when a client explicitly narrows the set.
+ *
+ * Pure: no fs / process / clock. The same algorithm is mirrored in the Java
+ * twin (jetbrains-plugin CapabilityNegotiation.java); both read the shared
+ * fixture __tests__/fixtures/capability-negotiation-cases.json.
+ */
+
+/** The current protocol version the CLI speaks (mirror of PROTOCOL_VERSION). */
+export const PROTOCOL_VERSION = 1;
+
+/**
+ * The oldest protocol version the CLI can still speak end-to-end (the N-1 in
+ * "N / N-1"). At v1 there is no older line shape, so min === current; once v2
+ * ships this drops to 1 so a v1-only client negotiates a v1 session.
+ */
+export const PROTOCOL_MIN_VERSION = 1;
+
+/**
+ * The wire-protocol features subject to negotiation — the additive per-line
+ * fields a client may or may not understand. Runtime capabilities (bare,
+ * worktree, mcp, …) are NOT negotiated: they change what the CLI can do, not
+ * the shape of a line the client must parse.
+ */
+export const PROTOCOL_FEATURES = ["event_seq", "tool_use_id", "trace_id"];
+
+/**
+ * Minimum protocol version a feature requires. Empty today (every current
+ * feature is a v1 additive field). When a v2 field lands, add it here so an
+ * N-1 (v1) session drops it automatically.
+ * @type {Record<string, number>}
+ */
+export const FEATURE_MIN_VERSION = {};
+
+function intOr(value, fallback) {
+  const n = Number(value);
+  return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+
+/**
+ * Coerce a features declaration into a sorted, de-duplicated array of keys.
+ * Accepts an array of strings, or an object whose truthy keys are the features
+ * (the nested manifest shape). Anything else → [].
+ * @returns {string[]}
+ */
+export function normalizeFeatureList(input) {
+  let keys;
+  if (Array.isArray(input)) {
+    keys = input.filter((k) => typeof k === "string" && k);
+  } else if (input && typeof input === "object") {
+    keys = Object.keys(input).filter((k) => input[k]);
+  } else {
+    return [];
+  }
+  return [...new Set(keys)].sort();
+}
+
+/**
+ * Extract the server's negotiation offer from a `cc agent --capabilities`
+ * manifest (buildAgentCapabilities output). Only the negotiable wire features
+ * the manifest advertises truthy are offered.
+ * @param {object} manifest
+ * @returns {{protocolVersion:number, minProtocolVersion:number, features:string[]}}
+ */
+export function buildServerOffer(manifest = {}) {
+  const protocolVersion = intOr(manifest.protocol_version, PROTOCOL_VERSION);
+  const minProtocolVersion = intOr(
+    manifest.min_protocol_version,
+    Math.min(PROTOCOL_MIN_VERSION, protocolVersion),
+  );
+  const advertised = normalizeFeatureList(manifest.features);
+  const features = PROTOCOL_FEATURES.filter((f) => advertised.includes(f));
+  return { protocolVersion, minProtocolVersion, features };
+}
+
+/**
+ * Negotiate the effective protocol version + feature set between a server offer
+ * and a client offer.
+ *
+ * @param {{protocolVersion:number, minProtocolVersion?:number, features:string[]}} server
+ * @param {null|{protocolVersion?:number, minProtocolVersion?:number, features?:string[]}} clientOffer
+ * @param {object} [opts]
+ * @param {Record<string,number>} [opts.featureMinVersion=FEATURE_MIN_VERSION]
+ * @returns {{
+ *   ok:boolean, agreedVersion:(number|null), features:string[],
+ *   downgraded:boolean, disabledFeatures:string[], clientAware:boolean,
+ *   reason:(string|null)
+ * }}
+ */
+export function negotiateProtocol(server = {}, clientOffer = null, opts = {}) {
+  const featureMinVersion = opts.featureMinVersion || FEATURE_MIN_VERSION;
+  const serverMax = intOr(server.protocolVersion, PROTOCOL_VERSION);
+  const serverMin = intOr(server.minProtocolVersion, serverMax);
+  const serverFeatures = normalizeFeatureList(server.features);
+
+  const versionOk = (f, v) => (featureMinVersion[f] || 0) <= v;
+
+  // No client offer → legacy peer. Keep full behavior (only version-gate the
+  // server's own features against its own max), byte-for-byte unchanged.
+  if (clientOffer == null) {
+    return {
+      ok: true,
+      agreedVersion: serverMax,
+      features: serverFeatures.filter((f) => versionOk(f, serverMax)),
+      downgraded: false,
+      disabledFeatures: [],
+      clientAware: false,
+      reason: null,
+    };
+  }
+
+  const clientMax = intOr(clientOffer.protocolVersion, serverMax);
+  const clientMin = intOr(clientOffer.minProtocolVersion, clientMax);
+  const agreedVersion = Math.min(serverMax, clientMax);
+  const floor = Math.max(serverMin, clientMin);
+
+  if (agreedVersion < floor) {
+    return {
+      ok: false,
+      agreedVersion: null,
+      features: [],
+      downgraded: true,
+      disabledFeatures: [...serverFeatures].sort(),
+      clientAware: true,
+      reason:
+        `no common protocol version (server ${serverMin}-${serverMax}, ` +
+        `client ${clientMin}-${clientMax})`,
+    };
+  }
+
+  // A client that omits `features` accepts whatever the agreed version offers;
+  // a client that sends the array narrows to the intersection.
+  const clientFeatures =
+    clientOffer.features === undefined
+      ? null
+      : new Set(normalizeFeatureList(clientOffer.features));
+
+  const enabled = [];
+  const disabled = [];
+  for (const f of serverFeatures) {
+    const okVersion = versionOk(f, agreedVersion);
+    const okClient = clientFeatures == null || clientFeatures.has(f);
+    if (okVersion && okClient) enabled.push(f);
+    else disabled.push(f);
+  }
+
+  return {
+    ok: true,
+    agreedVersion,
+    features: enabled.sort(),
+    downgraded: agreedVersion < serverMax || disabled.length > 0,
+    disabledFeatures: disabled.sort(),
+    clientAware: true,
+    reason: null,
+  };
+}
+
+/** Feature key → the stream line field it gates. */
+const FEATURE_TO_FIELD = {
+  event_seq: "seq",
+  trace_id: "trace_id",
+  tool_use_id: "tool_use_id",
+};
+
+/**
+ * Fold a negotiation result into a live field-gate the emitter reads per line:
+ * a field stays stamped only if its feature survived negotiation. On an
+ * incompatible (ok:false) result nothing is changed (the caller keeps its safe
+ * baseline). Mutates `gate` in place and returns it.
+ *
+ * @param {{features:string[], ok:boolean}} result
+ * @param {{seq?:boolean, trace_id?:boolean, tool_use_id?:boolean}} gate
+ */
+export function applyNegotiationToGate(result, gate = {}) {
+  if (!result || result.ok === false) return gate;
+  const enabled = new Set(result.features || []);
+  for (const feature of PROTOCOL_FEATURES) {
+    const field = FEATURE_TO_FIELD[feature];
+    if (field) gate[field] = enabled.has(feature);
+  }
+  return gate;
+}

package/src/lib/credential-guard.js

@@ -213,6 +213,17 @@ const PRINT_COMMANDS = new Set([
 const SECRET_VAR_RE =
   /(?:^|_)(KEY|KEYS|TOKEN|SECRET|SECRETS|PASSWORD|PASSWD|PASSPHRASE|CREDENTIAL|CREDENTIALS|PRIVATE|APIKEY|ACCESSKEY)(?:_|$)/i;
 
+/**
+ * True when an environment-variable NAME looks like it holds a secret
+ * (ANTHROPIC_API_KEY, GITHUB_TOKEN, DB_PASSWORD, …). Shared single source of
+ * truth so the credential READ guard and the credential PROXY
+ * ([[credential-proxy.js]] — which keeps secrets out of subprocess envs)
+ * classify identically. `MONKEY`/`KEYBOARD`/`TOKENIZER` do NOT match.
+ */
+export function isSecretEnvName(name) {
+  return typeof name === "string" && SECRET_VAR_RE.test(name);
+}
+
 // Ways a secret var is referenced inside a shell segment.
 const SECRET_REF_PATTERNS = [
   /\$env:([A-Za-z_][A-Za-z0-9_]*)/gi, // PowerShell  $env:NAME

package/src/lib/credential-proxy.js

@@ -0,0 +1,182 @@
+/**
+ * Credential proxy — keep the agent's real, long-lived credentials out of the
+ * environment that run_shell / run_code / hook / plugin subprocesses inherit
+ * (P0 §"跨平台沙箱与凭据代理").
+ *
+ * By default a spawned command inherits the WHOLE parent environment — including
+ * the agent's ANTHROPIC_API_KEY, cloud keys and tokens. A compromised or
+ * careless command can then echo, log, or exfiltrate them. This module replaces
+ * credential-named vars with an opaque SENTINEL before the child starts and
+ * keeps the real values in a parent-held vault, to be injected only for an
+ * approved host (via the egress proxy) — never handed to the child wholesale.
+ * The audit log only ever sees redacted values, never a restored secret.
+ *
+ * Pairs with credential-guard.js: that guard stops the AGENT reading secrets
+ * into model context; this stops the SUBPROCESS inheriting them. Both classify
+ * secret var names through the same `isSecretEnvName` so they never drift.
+ *
+ * Opt-in for now (`CC_CREDENTIAL_PROXY=1` or `config.credentialProxy.enabled`)
+ * so existing workflows that legitimately read a token from env keep working;
+ * default-on is the eventual goal once per-host injection is wired everywhere.
+ * Pure + dependency-light so every spawn seam can share it.
+ */
+
+import { isSecretEnvName } from "./credential-guard.js";
+
+/** Opaque replacement a masked credential var carries into the child env. */
+export const CREDENTIAL_SENTINEL_PREFIX = "cc-cred-redacted:";
+
+/**
+ * Well-known credential vars whose NAME does not obviously match the generic
+ * KEY/TOKEN/SECRET/PASSWORD pattern. Most real ones already match; this is a
+ * small safety net, extendable per-project via `deny`.
+ */
+const EXTRA_CREDENTIAL_NAMES = new Set([
+  "AWS_SESSION_TOKEN", // matches TOKEN, kept explicit
+  "GOOGLE_APPLICATION_CREDENTIALS", // path to a key file
+  "CLOUDSDK_AUTH_ACCESS_TOKEN",
+  "DIGITALOCEAN_ACCESS_TOKEN",
+]);
+
+function toSet(value) {
+  if (value instanceof Set) return value;
+  return new Set(Array.isArray(value) ? value : value ? [value] : []);
+}
+
+/**
+ * Classify an env var NAME as credential-bearing. `opts.allow` forces
+ * pass-through (never masked); `opts.deny` forces masking; otherwise the shared
+ * secret-name classifier + the curated extra set decide.
+ */
+export function isCredentialEnvName(name, opts = {}) {
+  if (typeof name !== "string" || !name) return false;
+  if (toSet(opts.allow).has(name)) return false;
+  if (toSet(opts.deny).has(name)) return true;
+  return isSecretEnvName(name) || EXTRA_CREDENTIAL_NAMES.has(name);
+}
+
+/** The sentinel a child sees in place of a credential's real value. */
+export function makeSentinel(name) {
+  return CREDENTIAL_SENTINEL_PREFIX + String(name ?? "");
+}
+
+/** True when a value is a proxy sentinel (carries no secret). */
+export function isSentinel(value) {
+  return (
+    typeof value === "string" && value.startsWith(CREDENTIAL_SENTINEL_PREFIX)
+  );
+}
+
+/**
+ * Mask credential-named vars in `env`. Returns a NEW object (never mutates the
+ * input):
+ *   - `env`    — credential vars replaced with a sentinel (mode "mask", the
+ *                default) or removed entirely (mode "deny"); everything else
+ *                copied through verbatim.
+ *   - `masked` — sorted list of the var names that were masked/removed.
+ *   - `vault`  — Map<name, realValue> the PARENT keeps for approved injection;
+ *                the child never receives it.
+ * Values that are already sentinels, null, or undefined are left as-is (a
+ * sentinel is never double-masked; an absent var is not invented).
+ */
+export function maskCredentialEnv(env = {}, opts = {}) {
+  const mode = opts.mode === "deny" ? "deny" : "mask";
+  const out = {};
+  const masked = [];
+  const vault = new Map();
+  for (const [name, value] of Object.entries(env || {})) {
+    if (
+      value != null &&
+      !isSentinel(value) &&
+      isCredentialEnvName(name, opts)
+    ) {
+      masked.push(name);
+      vault.set(name, String(value));
+      if (mode === "mask") out[name] = makeSentinel(name);
+      // mode "deny": drop the var so the child does not even see a sentinel
+    } else {
+      out[name] = value;
+    }
+  }
+  masked.sort();
+  return { env: out, masked, vault };
+}
+
+/** Replace a secret value with a fixed marker — never the real value. */
+export function redactSecretValue(value) {
+  if (value == null) return value;
+  return String(value) ? "***" : "";
+}
+
+/**
+ * A log-safe projection of an env for the audit trail: credential values →
+ * "***", sentinels kept verbatim (they hold no secret), everything else
+ * untouched. NEVER emits a restored/real credential value.
+ */
+export function redactEnvForAudit(env = {}, opts = {}) {
+  const out = {};
+  for (const [name, value] of Object.entries(env || {})) {
+    if (isSentinel(value)) out[name] = value;
+    else if (isCredentialEnvName(name, opts))
+      out[name] = redactSecretValue(value);
+    else out[name] = value;
+  }
+  return out;
+}
+
+/**
+ * Resolve the real value for a masked credential — but ONLY when the target
+ * host is on the approved list. The whole point of the proxy is that the child
+ * never gets the raw secret; the parent injects it just-in-time for an approved
+ * destination (e.g. the egress proxy adding Authorization for an allowed API
+ * host). Returns null (fail closed) for an unknown var, an empty host, or a
+ * non-approved host.
+ */
+export function resolveApprovedInjection(vault, name, opts = {}) {
+  if (!(vault instanceof Map) || !vault.has(name)) return null;
+  const host = String(opts.host || "").toLowerCase();
+  if (!host) return null;
+  const approved = (opts.approvedHosts || []).map((h) =>
+    String(h || "").toLowerCase(),
+  );
+  return approved.includes(host) ? vault.get(name) : null;
+}
+
+/**
+ * Resolve whether the credential proxy is enabled. Env var wins so a spawn
+ * seam without config access can still honor it; otherwise the config flag.
+ */
+export function credentialProxyEnabled(config = {}, env = process.env) {
+  const raw = env && env.CC_CREDENTIAL_PROXY;
+  if (raw != null) {
+    const v = String(raw).toLowerCase();
+    return v === "1" || v === "true" || v === "on" || v === "yes";
+  }
+  return config?.credentialProxy?.enabled === true;
+}
+
+/**
+ * Apply the credential proxy to a child env when enabled; otherwise return the
+ * env UNCHANGED (same reference — the default path stays byte-identical). The
+ * returned `vault` lets the caller inject approved creds later.
+ *
+ * @returns {{env:object, masked:string[], vault:Map, enabled:boolean}}
+ */
+export function applyCredentialProxy(env, options = {}) {
+  const procEnv = options.env || process.env;
+  const config = options.config || {};
+  if (!credentialProxyEnabled(config, procEnv)) {
+    return { env, masked: [], vault: new Map(), enabled: false };
+  }
+  const allow = new Set([
+    ...toSet(options.allow),
+    ...(config?.credentialProxy?.allow || []),
+  ]);
+  const deny = new Set([
+    ...toSet(options.deny),
+    ...(config?.credentialProxy?.deny || []),
+  ]);
+  const mode = options.mode || config?.credentialProxy?.mode || "mask";
+  const result = maskCredentialEnv(env, { allow, deny, mode });
+  return { ...result, enabled: true };
+}

package/src/lib/dependency-install-policy.js

@@ -0,0 +1,130 @@
+/**
+ * Dependency-install policy for `run_code` (gap-analysis 2026-07-11,
+ * docs/CLAUDE_CODE_CLI_GAP_ANALYSIS.md P0 "依赖安装与凭据").
+ *
+ * Auto `pip install` on a Python import error used to be unconditional. It is
+ * now OPT-IN:
+ *   - env `CC_RUN_CODE_AUTO_INSTALL=1|0` wins outright (kill-switch friendly)
+ *   - settings.json `runCode.autoInstall: true` opts in per project/user
+ *   - default: DISABLED — the tool result explains how to enable it
+ *
+ * When enabled, an optional `runCode.installAllowlist` (array of package
+ * names, PEP 503-normalized) restricts WHICH packages may be installed, and
+ * every attempt — including blocked/disabled ones — is appended to an audit
+ * log at ~/.chainlesschain/audit/dependency-install.jsonl.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+const _require = createRequire(import.meta.url);
+
+/** PEP 503 name normalization: lowercase, runs of -_. collapse to "-". */
+export function normalizePackageName(name) {
+  return String(name || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[-_.]+/g, "-");
+}
+
+/**
+ * Resolve the effective auto-install policy.
+ * @param {{cwd?:string, env?:object, settingsFile?:string|null}} opts
+ * @returns {{enabled:boolean, allowlist:string[]|null, source:string}}
+ */
+export function resolveAutoInstallPolicy({
+  cwd = process.cwd(),
+  env = process.env,
+  settingsFile = null,
+} = {}) {
+  const raw = env.CC_RUN_CODE_AUTO_INSTALL;
+  if (raw === "1" || raw === "0") {
+    return {
+      enabled: raw === "1",
+      allowlist: raw === "1" ? readAllowlist({ cwd, settingsFile }) : null,
+      source: "env",
+    };
+  }
+  let enabled = false;
+  try {
+    const { readBooleanSetting } = _require("./settings-loader.cjs");
+    enabled =
+      readBooleanSetting("runCode.autoInstall", { cwd, settingsFile }) === true;
+  } catch {
+    enabled = false; // fail-closed: no settings → stay disabled
+  }
+  return {
+    enabled,
+    allowlist: enabled ? readAllowlist({ cwd, settingsFile }) : null,
+    source: enabled ? "settings" : "default",
+  };
+}
+
+function readAllowlist({ cwd = process.cwd(), settingsFile }) {
+  try {
+    const { settingsPaths, readSettingsFile, loadManagedSettings } = _require(
+      "./settings-loader.cjs",
+    );
+    let value;
+    for (const file of settingsPaths(cwd, settingsFile)) {
+      const node = readSettingsFile(file)?.runCode?.installAllowlist;
+      if (Array.isArray(node)) value = node; // closest layer wins
+    }
+    const managed = loadManagedSettings({});
+    const mNode = managed?.settings?.runCode?.installAllowlist;
+    if (Array.isArray(mNode)) value = mNode; // managed policy wins outright
+    if (!Array.isArray(value)) return null;
+    const list = value.map(normalizePackageName).filter(Boolean);
+    return list.length ? list : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether a package may be installed under the policy's allowlist.
+ * No allowlist configured → any (validity is checked separately).
+ */
+export function isPackageAllowed(name, allowlist) {
+  if (!allowlist) return true;
+  return allowlist.includes(normalizePackageName(name));
+}
+
+/** Human hint for the disabled-by-default path (returned in the tool result). */
+export function autoInstallDisabledHint(packageName) {
+  return (
+    `Missing Python package "${packageName}". Auto-install is disabled by ` +
+    `default; install it yourself (pip install ${packageName}), or opt in via ` +
+    `settings.json {"runCode":{"autoInstall":true}} or CC_RUN_CODE_AUTO_INSTALL=1.`
+  );
+}
+
+/**
+ * Append an install-attempt audit record (best-effort, never throws).
+ * @param {{package:string, interpreter?:string, cwd?:string,
+ *          outcome:"installed"|"failed"|"blocked"|"disabled", detail?:string}} entry
+ * @param {{baseDir?:string, now?:()=>number}} [opts]  injection seams
+ */
+export function recordInstallAudit(entry, opts = {}) {
+  try {
+    const baseDir =
+      opts.baseDir ||
+      process.env.CC_AUDIT_DIR ||
+      path.join(os.homedir(), ".chainlesschain", "audit");
+    fs.mkdirSync(baseDir, { recursive: true });
+    const line = JSON.stringify({
+      ts: new Date(opts.now ? opts.now() : Date.now()).toISOString(),
+      kind: "dependency-install",
+      ...entry,
+    });
+    fs.appendFileSync(
+      path.join(baseDir, "dependency-install.jsonl"),
+      line + "\n",
+      "utf-8",
+    );
+  } catch {
+    /* audit is best-effort — never affect the run */
+  }
+}