chainlesschain 0.162.162 → 0.162.164

package/src/lib/plugin-runtime/bin.js

@@ -19,6 +19,33 @@
 import path from "path";
 import { discoverPlugins } from "./scopes.js";
 import { partitionByTrust, warnUntrustedOnce } from "./trust.js";
+import { componentCapabilityDenial } from "./capabilities.js";
+
+// One-time stderr notice when a plugin's bin dir is refused at the COMPONENT
+// level because the plugin opted into the capability model but did not declare
+// the `process` capability its executables need. Distinct from the trust gate:
+// these plugins ARE trusted, but their bin component is denied.
+const _capabilityDenied = new Set();
+function warnBinCapabilityDeniedOnce(entries) {
+  if (!entries || entries.length === 0) return;
+  if (_capabilityDenied.has("bin-capability")) return;
+  _capabilityDenied.add("bin-capability");
+  const list = entries.map((e) => `${e.name} (${e.reason})`).join("; ");
+  try {
+    process.stderr.write(
+      `[plugins] refused bin dir(s) from plugin(s) that declared a permissions ` +
+        `block but did not declare the 'process' capability: ${list}\n` +
+        `          add 'process' to the plugin's permissions block to enable them.\n`,
+    );
+  } catch {
+    /* stderr notice is best-effort */
+  }
+}
+
+/** Test hook: reset the one-time capability-denied warning guard. */
+export function _resetBinWarnings() {
+  _capabilityDenied.clear();
+}
 
 /**
  * Collect trusted, installed plugins' `bin/` directories.
@@ -40,10 +67,19 @@ export function collectPluginBinDirs(opts = {}) {
     "bin",
   );
   const out = [];
+  const denied = [];
   for (const p of trusted) {
     if (!p.manifest || p.manifest.ok !== true) continue;
     const bins = p.manifest.components?.bin;
     if (!Array.isArray(bins) || bins.length === 0) continue;
+    // Component-level capability gate: a plugin that declared a permissions
+    // block but did not declare the `process` capability its executables need
+    // gets its bin dir refused here (mirrors the MCP collector's denial).
+    const denial = componentCapabilityDenial(p.manifest, ["process"]);
+    if (denial) {
+      denied.push({ name: p.name, reason: denial.reason });
+      continue;
+    }
     // Every bin entry's absPath is a file inside the plugin's bin dir; collect
     // the unique parent directories (usually just `<root>/bin`).
     const dirs = new Set(bins.map((b) => path.dirname(b.absPath)));
@@ -56,6 +92,7 @@ export function collectPluginBinDirs(opts = {}) {
       });
     }
   }
+  warnBinCapabilityDeniedOnce(denied);
   return out;
 }
 

package/src/lib/plugin-runtime/capabilities.js

@@ -220,6 +220,25 @@ export function auditDeclaredCapabilities(manifest) {
   return findings;
 }
 
+/**
+ * Component-level capability denial. A plugin that opted into the capability
+ * model (declared a `permissions` block, so `capabilitiesDeclared === true`) but
+ * ships a component whose required capability it did NOT declare should have that
+ * single component refused — not just flagged by the whole-plugin consent notice.
+ * `capabilityNames` is the set of capability names whose absence denies this
+ * component (e.g. `["process"]` for a hook/bin/lsp, `["monitor"]` for a monitor,
+ * `["mcp","network"]` for an MCP server). Legacy plugins (no permissions block)
+ * are unrestricted by design and never denied. Returns `{reason}` or null.
+ */
+export function componentCapabilityDenial(manifest, capabilityNames) {
+  if (!manifest || manifest.capabilitiesDeclared !== true) return null;
+  const wanted = new Set(capabilityNames || []);
+  const finding = auditDeclaredCapabilities(manifest).find((f) =>
+    wanted.has(f.capability),
+  );
+  return finding ? { reason: finding.reason } : null;
+}
+
 // ─── options schema ─────────────────────────────────────────────────────────
 
 export const OPTION_TYPES = Object.freeze([

package/src/lib/plugin-runtime/capability-consent.js

@@ -0,0 +1,203 @@
+/**
+ * Plugin capability CONSENT (Phase 3 gap: capability declaration + re-consent).
+ *
+ * Complements version trust ([[trust.js]]): trust pins the exact CODE a plugin
+ * ships (re-consent on version bump); this pins the CAPABILITY SET the plugin is
+ * allowed to request (process / network / filesystem / mcp / monitor /
+ * credential). The two are orthogonal — a plugin can be trusted-to-run yet still
+ * WIDEN what it wants (add `network:*`, a new credential), which must re-prompt.
+ *
+ * Consent is keyed by the SET, not the version: once the user consents, later
+ * versions that keep the same (or a narrower) capability set stay consented; any
+ * WIDENING (a new grant) revokes consent until re-granted. This mirrors
+ * `consentRequiredForUpgrade` in [[capabilities.js]] exactly.
+ *
+ * Recorded in the USER data dir (never in the repo — a checked-in project file
+ * must not be able to pre-grant itself capabilities), keyed `<scope>:<name>` →
+ * { version, capabilities, consentedAt }. Pure over injected IO so unit tests
+ * never touch the real user-data dir.
+ */
+
+import fs from "fs";
+import path from "path";
+import { getElectronUserDataDir } from "../paths.js";
+import {
+  normalizeCapabilities,
+  diffCapabilities,
+  describeCapabilities,
+} from "./capabilities.js";
+
+export const _deps = {
+  existsSync: fs.existsSync,
+  readFileSync: fs.readFileSync,
+  writeFileSync: fs.writeFileSync,
+  mkdirSync: fs.mkdirSync,
+  now: () => new Date().toISOString(),
+  // Injectable so unit tests never touch the real user-data dir.
+  storePath: () =>
+    path.join(getElectronUserDataDir(), "plugin-capability-consent.json"),
+};
+
+function consentKey(scope, name) {
+  return `${scope}:${name}`;
+}
+
+export function loadConsentStore() {
+  try {
+    const p = _deps.storePath();
+    if (!_deps.existsSync(p)) return {};
+    const data = JSON.parse(_deps.readFileSync(p, "utf8"));
+    return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+function saveConsentStore(store) {
+  const p = _deps.storePath();
+  _deps.mkdirSync(path.dirname(p), { recursive: true });
+  _deps.writeFileSync(p, JSON.stringify(store, null, 2), "utf8");
+}
+
+/**
+ * Coerce a capability set to the canonical shape diffCapabilities needs.
+ * `normalizeCapabilities` is NOT idempotent — it re-parses `filesystem`/
+ * `credential` through `toList`, so feeding it an already-normalized set (e.g.
+ * one read back from the store) corrupts those lists. Detect an already-
+ * canonical set and pass it through unchanged; only normalize raw input.
+ */
+function canonicalCaps(caps) {
+  if (
+    caps &&
+    typeof caps === "object" &&
+    caps.network &&
+    typeof caps.network === "object" &&
+    "domains" in caps.network &&
+    caps.filesystem &&
+    "roots" in caps.filesystem &&
+    caps.credential &&
+    "names" in caps.credential
+  ) {
+    return caps;
+  }
+  return normalizeCapabilities(caps);
+}
+
+/** True when a capability set grants nothing (all-deny) — nothing to consent. */
+export function capabilitiesAreEmpty(caps) {
+  return !diffCapabilities(null, canonicalCaps(caps)).widened;
+}
+
+/**
+ * PURE consent status: given a plugin's DECLARED capabilities and its stored
+ * consent entry, decide whether consent covers them. Re-consent is required on
+ * a first request or any WIDENING (new grant) — not on a version bump alone
+ * (trust handles versions).
+ *
+ * @param {object} declaredCaps  raw or normalized capabilities
+ * @param {object|null} entry    stored `{ version, capabilities }` (or null)
+ * @returns {{consented:boolean, reason:string, added:string[]}}
+ */
+export function capabilityConsentStatus(declaredCaps, entry) {
+  const declared = canonicalCaps(declaredCaps);
+  if (!diffCapabilities(null, declared).widened) {
+    return { consented: true, reason: "no capabilities declared", added: [] };
+  }
+  if (!entry) {
+    return {
+      consented: false,
+      reason: "capabilities never consented",
+      added: diffCapabilities(null, declared).added,
+    };
+  }
+  // Coerce the stored set to canonical too (raw hand-written entry, or an
+  // already-normalized one read from the store) before diffing.
+  const diff = diffCapabilities(canonicalCaps(entry.capabilities), declared);
+  if (diff.widened) {
+    return {
+      consented: false,
+      reason: "capabilities widened since last consent",
+      added: diff.added,
+    };
+  }
+  return {
+    consented: true,
+    reason: "consent covers declared capabilities",
+    added: [],
+  };
+}
+
+/**
+ * Decide how an install/upgrade command should handle capability consent at the
+ * point of installation (pure — no I/O). `notice` is the shape returned by the
+ * command layer's capability resolver: `{ consented, added, ... }` or null when
+ * the plugin declares no capabilities.
+ *
+ * Returns one of:
+ *   - "advisory" — nothing to consent (no caps, or already consented), OR the
+ *     caller is non-interactive and did not pass an explicit grant flag: print
+ *     the notice and require a later `cc plugin consent --grant`.
+ *   - "grant"    — an explicit grant flag was given: record consent immediately
+ *     (scriptable / CI path).
+ *   - "prompt"   — consent is required and the session is interactive: ask the
+ *     user, then grant on confirmation.
+ *
+ * Precedence: an explicit grant flag always wins over an interactive prompt, so
+ * `--grant-capabilities` is honored even under a TTY without a second question.
+ */
+export function resolveConsentAction(
+  notice,
+  { grant = false, interactive = false } = {},
+) {
+  if (!notice || notice.consented) return "advisory";
+  if (grant) return "grant";
+  if (interactive) return "prompt";
+  return "advisory";
+}
+
+/** Load the store and report whether one plugin's declared caps are consented. */
+export function isPluginCapabilityConsented(plugin, declaredCaps) {
+  if (!plugin || !plugin.name) return false;
+  const entry = loadConsentStore()[consentKey(plugin.scope, plugin.name)];
+  return capabilityConsentStatus(declaredCaps, entry).consented;
+}
+
+/** Record consent for a plugin's currently-declared capability set. */
+export function consentPluginCapabilities(
+  name,
+  { scope = "project", version, capabilities } = {},
+) {
+  if (!version) throw new Error("consentPluginCapabilities requires a version");
+  const store = loadConsentStore();
+  store[consentKey(scope, name)] = {
+    version,
+    capabilities: canonicalCaps(capabilities),
+    consentedAt: _deps.now(),
+  };
+  saveConsentStore(store);
+  return { name, scope, version };
+}
+
+/** Revoke capability consent for a plugin at a scope. */
+export function revokeCapabilityConsent(name, { scope = "project" } = {}) {
+  const store = loadConsentStore();
+  const key = consentKey(scope, name);
+  const existed = Object.prototype.hasOwnProperty.call(store, key);
+  delete store[key];
+  saveConsentStore(store);
+  return { name, scope, removed: existed };
+}
+
+/** All consent entries (for `cc plugin consent --list`). */
+export function listCapabilityConsent() {
+  return Object.entries(loadConsentStore()).map(([key, v]) => {
+    const idx = key.indexOf(":");
+    return {
+      scope: key.slice(0, idx),
+      name: key.slice(idx + 1),
+      version: v?.version || null,
+      consentedAt: v?.consentedAt || null,
+      capabilities: describeCapabilities(v?.capabilities),
+    };
+  });
+}

package/src/lib/plugin-runtime/hooks.js

@@ -17,9 +17,36 @@
 import fs from "fs";
 import { discoverPlugins } from "./scopes.js";
 import { partitionByTrust, warnUntrustedOnce } from "./trust.js";
+import { componentCapabilityDenial } from "./capabilities.js";
 
 export const _deps = { readFileSync: fs.readFileSync };
 
+// One-time stderr notice when a plugin's hooks are refused at the COMPONENT
+// level because the plugin opted into the capability model but did not declare
+// the `process` capability its shell hooks need. Distinct from the trust gate:
+// these plugins ARE trusted, but their hook component is denied.
+const _capabilityDenied = new Set();
+function warnHookCapabilityDeniedOnce(entries) {
+  if (!entries || entries.length === 0) return;
+  if (_capabilityDenied.has("hook-capability")) return;
+  _capabilityDenied.add("hook-capability");
+  const list = entries.map((e) => `${e.name} (${e.reason})`).join("; ");
+  try {
+    process.stderr.write(
+      `[plugins] refused hook(s) from plugin(s) that declared a permissions ` +
+        `block but did not declare the 'process' capability their hooks need: ${list}\n` +
+        `          add 'process' to the plugin's permissions block to enable them.\n`,
+    );
+  } catch {
+    /* stderr notice is best-effort */
+  }
+}
+
+/** Test hook: reset the one-time capability-denied warning guard. */
+export function _resetHookWarnings() {
+  _capabilityDenied.clear();
+}
+
 /** Accept either `{ hooks: {Event:[...]} }` (plugin wrap) or `{Event:[...]}`. */
 function normalizeHookMap(parsed) {
   if (
@@ -57,10 +84,19 @@ export function collectPluginHooks(opts = {}) {
     "hooks",
   );
   const merged = {};
+  const denied = [];
   for (const p of trusted) {
     if (!p.manifest || p.manifest.ok !== true) continue;
     const h = p.manifest.components?.hooks;
     if (!h) continue;
+    // Component-level capability gate: a plugin that declared a permissions
+    // block but under-declared the `process` capability its shell hooks need
+    // gets its hooks refused here (mirrors the MCP collector's denial).
+    const denial = componentCapabilityDenial(p.manifest, ["process"]);
+    if (denial) {
+      denied.push({ name: p.name, reason: denial.reason });
+      continue;
+    }
     let parsed;
     if (h.absPath) {
       try {
@@ -89,6 +125,7 @@ export function collectPluginHooks(opts = {}) {
       merged[event] = (merged[event] || []).concat(entries);
     }
   }
+  warnHookCapabilityDeniedOnce(denied);
   return merged;
 }
 

package/src/lib/plugin-runtime/lsp.js

@@ -16,9 +16,31 @@ import path from "path";
 import { discoverPlugins } from "./scopes.js";
 import { registerLanguageServer } from "../lsp/lsp-server-registry.js";
 import { partitionByTrust, warnUntrustedOnce } from "./trust.js";
+import { componentCapabilityDenial } from "./capabilities.js";
 
 const _loadedRoots = new Set();
 
+// One-time stderr notice when a plugin's LSP servers are refused at the
+// COMPONENT level because the plugin opted into the capability model but did not
+// declare the `process` capability the servers need. Distinct from the trust
+// gate: these plugins ARE trusted, but their LSP component is denied.
+const _capabilityDenied = new Set();
+function warnLspCapabilityDeniedOnce(entries) {
+  if (!entries || entries.length === 0) return;
+  if (_capabilityDenied.has("lsp-capability")) return;
+  _capabilityDenied.add("lsp-capability");
+  const list = entries.map((e) => `${e.name} (${e.reason})`).join("; ");
+  try {
+    process.stderr.write(
+      `[plugins] refused language server(s) from plugin(s) that declared a ` +
+        `permissions block but did not declare the 'process' capability: ${list}\n` +
+        `          add 'process' to the plugin's permissions block to enable them.\n`,
+    );
+  } catch {
+    /* stderr notice is best-effort */
+  }
+}
+
 /**
  * Register every installed plugin's LSP servers for `cwd` (once per root).
  * Never throws — a broken plugin manifest must not break code navigation.
@@ -49,8 +71,18 @@ export function ensurePluginLspServers(opts = {}) {
     "language servers",
   );
 
+  const denied = [];
   for (const p of trusted) {
     const servers = p.manifest?.components?.lsp || [];
+    if (servers.length === 0) continue;
+    // Component-level capability gate: a plugin that declared a permissions
+    // block but did not declare the `process` capability its language servers
+    // need gets them refused here (mirrors the MCP collector's denial).
+    const denial = componentCapabilityDenial(p.manifest, ["process"]);
+    if (denial) {
+      denied.push({ name: p.name, reason: denial.reason });
+      continue;
+    }
     for (const s of servers) {
       try {
         registerLanguageServer({
@@ -66,6 +98,7 @@ export function ensurePluginLspServers(opts = {}) {
       }
     }
   }
+  warnLspCapabilityDeniedOnce(denied);
   return { registered };
 }
 
@@ -73,3 +106,8 @@ export function ensurePluginLspServers(opts = {}) {
 export function _resetPluginLspLoadState() {
   _loadedRoots.clear();
 }
+
+/** Test hook: reset the one-time capability-denied warning guard. */
+export function _resetLspWarnings() {
+  _capabilityDenied.clear();
+}

package/src/lib/plugin-runtime/mcp.js

@@ -17,9 +17,38 @@
 import fs from "fs";
 import { discoverPlugins } from "./scopes.js";
 import { partitionByTrust, warnUntrustedOnce } from "./trust.js";
+import { componentCapabilityDenial } from "./capabilities.js";
 
 export const _deps = { readFileSync: fs.readFileSync };
 
+// One-time stderr notice when a plugin's MCP server is refused at the COMPONENT
+// level because the plugin opted into the capability model but did not declare
+// the `mcp` capability its server needs. Distinct from the trust gate: these
+// plugins ARE trusted, but their MCP component is denied. (Network is enforced
+// separately at connection time by the egress/network policy, so a local stdio
+// server is not denied for lacking a `network` declaration.)
+const _capabilityDenied = new Set();
+function warnMcpCapabilityDeniedOnce(entries) {
+  if (!entries || entries.length === 0) return;
+  if (_capabilityDenied.has("mcp-capability")) return;
+  _capabilityDenied.add("mcp-capability");
+  const list = entries.map((e) => `${e.name} (${e.reason})`).join("; ");
+  try {
+    process.stderr.write(
+      `[plugins] refused MCP server(s) from plugin(s) that declared a permissions ` +
+        `block but did not declare the 'mcp' capability their server needs: ${list}\n` +
+        `          add 'mcp' to the plugin's permissions block to enable them.\n`,
+    );
+  } catch {
+    /* stderr notice is best-effort */
+  }
+}
+
+/** Test hook: reset the one-time capability-denied warning guard. */
+export function _resetMcpWarnings() {
+  _capabilityDenied.clear();
+}
+
 /** Accept `{ mcpServers: {...} }`, `{ servers: {...} }`, or a bare map. */
 function normalizeServerMap(parsed) {
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
@@ -52,10 +81,20 @@ export function collectPluginMcpServers(opts = {}) {
   );
   const servers = {};
   const sources = [];
+  const denied = [];
   for (const p of trusted) {
     if (!p.manifest || p.manifest.ok !== true) continue;
     const m = p.manifest.components?.mcp;
     if (!m) continue;
+    // Component-level capability gate: a plugin that declared a permissions
+    // block but under-declared the `mcp` capability its server needs gets its
+    // MCP component refused here (mirrors the hooks/monitors/bin/lsp denial).
+    // Legacy plugins (no permissions block) are unrestricted and never denied.
+    const denial = componentCapabilityDenial(p.manifest, ["mcp"]);
+    if (denial) {
+      denied.push({ name: p.name, reason: denial.reason });
+      continue;
+    }
     let parsed = null;
     if (m.absPath) {
       try {
@@ -85,5 +124,6 @@ export function collectPluginMcpServers(opts = {}) {
     }
     if (added > 0 && m.absPath) sources.push(m.absPath);
   }
+  warnMcpCapabilityDeniedOnce(denied);
   return { servers, sources };
 }

package/src/lib/plugin-runtime/monitors.js

@@ -21,11 +21,38 @@
 import fs from "fs";
 import { discoverPlugins } from "./scopes.js";
 import { partitionByTrust, warnUntrustedOnce } from "./trust.js";
+import { componentCapabilityDenial } from "./capabilities.js";
 
 export const _deps = { readFileSync: fs.readFileSync };
 
 const VALID_MODES = new Set(["interval", "longRunning"]);
 
+// One-time stderr notice when a plugin's monitors are refused at the COMPONENT
+// level because the plugin opted into the capability model but did not declare
+// the `monitor` capability. Distinct from the trust gate: these plugins ARE
+// trusted, but their monitor component is denied.
+const _capabilityDenied = new Set();
+function warnMonitorCapabilityDeniedOnce(entries) {
+  if (!entries || entries.length === 0) return;
+  if (_capabilityDenied.has("monitor-capability")) return;
+  _capabilityDenied.add("monitor-capability");
+  const list = entries.map((e) => `${e.name} (${e.reason})`).join("; ");
+  try {
+    process.stderr.write(
+      `[plugins] refused monitor(s) from plugin(s) that declared a permissions ` +
+        `block but did not declare the 'monitor' capability: ${list}\n` +
+        `          add 'monitor' to the plugin's permissions block to enable them.\n`,
+    );
+  } catch {
+    /* stderr notice is best-effort */
+  }
+}
+
+/** Test hook: reset the one-time capability-denied warning guard. */
+export function _resetMonitorWarnings() {
+  _capabilityDenied.clear();
+}
+
 /** Normalize one raw monitor entry into a validated descriptor, or null. */
 function normalizeMonitor(plugin, raw) {
   if (!raw || typeof raw !== "object") return null;
@@ -76,10 +103,19 @@ export function collectPluginMonitors(opts = {}) {
     "monitors",
   );
   const out = [];
+  const denied = [];
   for (const p of trusted) {
     if (!p.manifest || p.manifest.ok !== true) continue;
     const m = p.manifest.components?.monitors;
     if (!m) continue;
+    // Component-level capability gate: a plugin that declared a permissions
+    // block but did not declare the `monitor` capability gets its monitors
+    // refused here (mirrors the MCP collector's denial).
+    const denial = componentCapabilityDenial(p.manifest, ["monitor"]);
+    if (denial) {
+      denied.push({ name: p.name, reason: denial.reason });
+      continue;
+    }
     let parsed;
     if (m.absPath) {
       try {
@@ -112,5 +148,6 @@ export function collectPluginMonitors(opts = {}) {
       if (desc) out.push(desc);
     }
   }
+  warnMonitorCapabilityDeniedOnce(denied);
   return out;
 }