chainlesschain 0.162.180 → 0.162.181

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

@@ -164,6 +164,22 @@ export function capabilityConsentRequired(managed, env) {
   );
 }
 
+/**
+ * Require every loadable plugin to opt into the capability model with an
+ * explicit `permissions` block. Mandatory consent implies this gate: otherwise
+ * a legacy plugin could bypass consent simply by omitting the declaration.
+ */
+export function capabilityDeclarationsRequired(managed, env) {
+  const runtimeEnv = env || process.env;
+  const raw = runtimeEnv.CC_REQUIRE_PLUGIN_CAPABILITIES;
+  if (raw != null && /^(1|true|yes|on)$/i.test(String(raw).trim())) return true;
+  return (
+    managed?.requirePluginCapabilityDeclarations === true ||
+    managed?.requirePluginCapabilityDeclarations === "require" ||
+    capabilityConsentRequired(managed, runtimeEnv)
+  );
+}
+
 /**
  * Drop plugins that DECLARE capabilities but whose current capability SET has
  * not been consented (first request or any widening). Fail-closed: a consent
@@ -175,12 +191,23 @@ export function capabilityConsentRequired(managed, env) {
  * @param {Array<{name, scope, manifest}>} plugins
  * @returns {{ kept: Array, dropped: Array<{name, reason}> }}
  */
-export function filterByCapabilityConsent(plugins) {
+export function filterByCapabilityConsent(
+  plugins,
+  { requireDeclarations = false } = {},
+) {
   const kept = [];
   const dropped = [];
   for (const p of plugins) {
     if (!p.manifest?.capabilitiesDeclared) {
-      kept.push(p); // legacy plugin, no declaration → not gated
+      if (requireDeclarations) {
+        dropped.push({
+          name: p.name,
+          reason:
+            "capability declaration required: add an explicit `permissions` block to plugin.json",
+        });
+      } else {
+        kept.push(p); // migration window: legacy declaration remains compatible
+      }
       continue;
     }
     let consented = false;

package/src/lib/plugin-runtime/sandbox-policy.js

@@ -0,0 +1,84 @@
+/**
+ * Normalize the small, declarative sandbox contract exposed to plugins.
+ *
+ * Plugins may require filesystem and/or network isolation for processes they
+ * cause the CLI to spawn. They may not select a sandbox profile or claim other
+ * broker guarantees. Keeping this layer narrower than ProcessExecutionBroker's
+ * internal contract prevents plugin-controlled policy from weakening managed
+ * defaults while still allowing an explicit requirement to fail closed.
+ */
+
+export const PLUGIN_SANDBOX_BOUNDARIES = Object.freeze([
+  "filesystem",
+  "network",
+]);
+
+const SUPPORTED_BOUNDARIES = new Set(PLUGIN_SANDBOX_BOUNDARIES);
+
+function invalidPolicy(message) {
+  const error = new Error(message);
+  error.code = "ERR_PLUGIN_SANDBOX_POLICY_INVALID";
+  return error;
+}
+
+/**
+ * @param {unknown} raw
+ * @param {{ label?: string }} [opts]
+ * @returns {{requiredBoundaries: string[]}|null}
+ */
+export function normalizePluginSandboxPolicy(raw, opts = {}) {
+  const label = opts.label || "sandboxPolicy";
+  if (raw === undefined || raw === null) return null;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw invalidPolicy(`${label} must be an object`);
+  }
+  const unsupportedKeys = Object.keys(raw).filter(
+    (key) => key !== "requiredBoundaries",
+  );
+  if (unsupportedKeys.length > 0) {
+    throw invalidPolicy(
+      `${label} contains unsupported field: ${unsupportedKeys[0]}`,
+    );
+  }
+
+  const boundaries = raw.requiredBoundaries;
+  if (boundaries === undefined) return null;
+  if (!Array.isArray(boundaries)) {
+    throw invalidPolicy(`${label}.requiredBoundaries must be an array`);
+  }
+
+  const requiredBoundaries = [];
+  for (const boundary of boundaries) {
+    if (
+      typeof boundary !== "string" ||
+      !SUPPORTED_BOUNDARIES.has(boundary)
+    ) {
+      throw invalidPolicy(
+        `${label}.requiredBoundaries contains unsupported boundary: ${String(boundary)}`,
+      );
+    }
+    if (!requiredBoundaries.includes(boundary)) {
+      requiredBoundaries.push(boundary);
+    }
+  }
+
+  return requiredBoundaries.length > 0 ? { requiredBoundaries } : null;
+}
+
+/**
+ * Merge manifest/component/descriptor requirements additively. A child
+ * descriptor can require more isolation, but cannot remove a manifest-level
+ * requirement.
+ */
+export function mergePluginSandboxPolicies(...policies) {
+  const requiredBoundaries = [];
+  for (const raw of policies) {
+    const policy = normalizePluginSandboxPolicy(raw);
+    for (const boundary of policy?.requiredBoundaries || []) {
+      if (!requiredBoundaries.includes(boundary)) {
+        requiredBoundaries.push(boundary);
+      }
+    }
+  }
+  return requiredBoundaries.length > 0 ? { requiredBoundaries } : null;
+}

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

@@ -29,6 +29,7 @@ import {
   filterByManagedPolicy,
   filterByCapabilityConsent,
   capabilityConsentRequired,
+  capabilityDeclarationsRequired,
   warnDroppedOnce,
 } from "./policy.js";
 
@@ -163,9 +164,10 @@ export function discoverPlugins(opts = {}) {
     managedSettingsFile: opts.managedSettingsFile,
   });
   const consentGate = capabilityConsentRequired(managed, opts.env);
+  const declarationsGate = capabilityDeclarationsRequired(managed, opts.env);
   // Default (no managed policy AND consent enforcement off): byte-identical —
   // return every discovered plugin, exactly as before.
-  if (!managed && !consentGate) return all;
+  if (!managed && !consentGate && !declarationsGate) return all;
   let list = all;
   if (managed) {
     const { kept, dropped } = filterByManagedPolicy(list, managed);
@@ -174,8 +176,10 @@ export function discoverPlugins(opts = {}) {
   }
   // Capability-consent enforcement funnels through the SAME chokepoint, so an
   // un-consented plugin loads NONE of its six component types (opt-in).
-  if (consentGate) {
-    const { kept, dropped } = filterByCapabilityConsent(list);
+  if (consentGate || declarationsGate) {
+    const { kept, dropped } = filterByCapabilityConsent(list, {
+      requireDeclarations: declarationsGate,
+    });
     if (dropped.length > 0) warnDroppedOnce(dropped);
     list = kept;
   }

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

@@ -21,16 +21,17 @@
  * running untrusted SHELL/binaries behind the user's back.
  */
 
-import fs from "fs";
 import path from "path";
 import { getElectronUserDataDir } from "../paths.js";
+import { withFileLock } from "../with-file-lock.js";
+import {
+  mutateSecurityStore,
+  readSecurityStore,
+} from "../durable-security-store.js";
 
 export const _deps = {
-  existsSync: fs.existsSync,
-  readFileSync: fs.readFileSync,
-  writeFileSync: fs.writeFileSync,
-  mkdirSync: fs.mkdirSync,
   now: () => new Date().toISOString(),
+  withFileLock,
   // Path of the trust store; injectable so unit tests never touch the real
   // user-data dir.
   storePath: () => path.join(getElectronUserDataDir(), "plugin-trust.json"),
@@ -39,20 +40,7 @@ export const _deps = {
 const AUTO_TRUSTED_SCOPES = new Set(["user", "local"]);
 
 export function loadTrustStore() {
-  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 saveTrustStore(store) {
-  const p = _deps.storePath();
-  _deps.mkdirSync(path.dirname(p), { recursive: true });
-  _deps.writeFileSync(p, JSON.stringify(store, null, 2), "utf8");
+  return readSecurityStore(_deps.storePath(), "plugin trust");
 }
 
 function trustKey(scope, name) {
@@ -66,27 +54,44 @@ function trustKey(scope, name) {
 export function isPluginTrusted(plugin) {
   if (!plugin || !plugin.name) return false;
   if (AUTO_TRUSTED_SCOPES.has(plugin.scope)) return true;
-  const entry = loadTrustStore()[trustKey(plugin.scope, plugin.name)];
-  return Boolean(entry && entry.version === plugin.version);
+  try {
+    const entry = loadTrustStore()[trustKey(plugin.scope, plugin.name)];
+    return Boolean(entry && entry.version === plugin.version);
+  } catch {
+    // Project code must stay disabled when the trust store is unavailable.
+    return false;
+  }
 }
 
 /** Trust a plugin (records the exact version). */
 export function trustPlugin(name, { scope = "project", version } = {}) {
   if (!version) throw new Error("trustPlugin requires a version");
-  const store = loadTrustStore();
-  store[trustKey(scope, name)] = { version, trustedAt: _deps.now() };
-  saveTrustStore(store);
-  return { name, scope, version };
+  const file = _deps.storePath();
+  return mutateSecurityStore(
+    file,
+    "plugin trust",
+    (store) => {
+      store[trustKey(scope, name)] = { version, trustedAt: _deps.now() };
+      return { name, scope, version };
+    },
+    { lock: _deps.withFileLock },
+  );
 }
 
 /** Revoke trust for a plugin at a scope. */
 export function untrustPlugin(name, { scope = "project" } = {}) {
-  const store = loadTrustStore();
-  const key = trustKey(scope, name);
-  const existed = Object.prototype.hasOwnProperty.call(store, key);
-  delete store[key];
-  saveTrustStore(store);
-  return { name, scope, removed: existed };
+  const file = _deps.storePath();
+  return mutateSecurityStore(
+    file,
+    "plugin trust",
+    (store) => {
+      const key = trustKey(scope, name);
+      const existed = Object.prototype.hasOwnProperty.call(store, key);
+      delete store[key];
+      return { name, scope, removed: existed };
+    },
+    { lock: _deps.withFileLock },
+  );
 }
 
 /** All trust entries (for `cc plugin trust --list`). */

package/src/lib/process-execution-broker/credential-agent.js

@@ -6,12 +6,14 @@
  * receives short-lived opaque references. Resolving a reference requires an
  * attested agent id and the exact process/host target recorded at issuance.
  *
- * This module deliberately does not claim to provide an OS IPC transport. A
- * future broker-owned IPC implementation can call resolveCredentialRef() after
- * it has authenticated the requesting process and destination host.
+ * The production singleton also mirrors issued references into a broker-owned
+ * authenticated local transport. Per-launch capability tokens bind resolution
+ * to the approved process and destination host without putting credential
+ * values in the child environment or argv.
  */
 
 import crypto from "node:crypto";
+import { CredentialTransport } from "./credential-transport.js";
 
 const REDACTED_VALUE = "***REDACTED***";
 const DEFAULT_TTL_MS = 60_000;
@@ -33,6 +35,7 @@ const CREDENTIAL_ERROR_CODES = Object.freeze({
   REVOKED: "CC_CREDENTIAL_REF_REVOKED",
   AGENT_MISMATCH: "CC_CREDENTIAL_AGENT_MISMATCH",
   TARGET_MISMATCH: "CC_CREDENTIAL_TARGET_MISMATCH",
+  TRANSPORT_UNAVAILABLE: "CC_CREDENTIAL_TRANSPORT_UNAVAILABLE",
 });
 
 // Patterns for environment variables that contain secrets.
@@ -126,6 +129,10 @@ const RESERVED_AGENT_ENV_KEYS = new Set([
   "CC_CREDENTIAL_AGENT_ID",
   "CC_CREDENTIAL_PROXY",
   "CC_CREDENTIAL_TRANSPORT",
+  "CC_CREDENTIAL_ENDPOINT",
+  "CC_CREDENTIAL_AUTH_TOKEN",
+  "CC_CREDENTIAL_TARGET_PROCESS",
+  "CC_CREDENTIAL_TARGET_HOST",
 ]);
 
 function credentialError(code, message) {
@@ -251,9 +258,21 @@ class CredentialAgent {
       Number.MAX_SAFE_INTEGER,
     );
 
-    // "broker-api" is an in-process primitive, not a socket/pipe endpoint.
-    this._transport = "broker-api";
-    this._proxyReady = false;
+    this._transportMode = "broker-api";
+    this._credentialTransport = null;
+    if (options.transport) {
+      this._credentialTransport =
+        options.transport === true
+          ? new CredentialTransport({
+              agentId: this._agentId,
+              onAudit: (entry) => this._recordAudit(entry),
+              onSettlement: (settlement) =>
+                this._applyTransportSettlement(settlement),
+            })
+          : options.transport;
+      this._transportMode =
+        this._credentialTransport?.version || "local-ipc-v1";
+    }
     this._lastEnabledState = this._computeEnabled();
   }
 
@@ -270,10 +289,11 @@ class CredentialAgent {
 
     if (!enabled) {
       let revoked = 0;
-      for (const record of this._credentialStore.values()) {
+      for (const [refId, record] of this._credentialStore) {
         if (record.status === "active") {
           record.value = null;
           record.status = "disabled";
+          this._credentialTransport?.revokeCredential(refId);
           revoked += 1;
         }
       }
@@ -387,6 +407,19 @@ class CredentialAgent {
     }
   }
 
+  _applyTransportSettlement(settlement) {
+    const record = this._credentialStore.get(settlement?.refId);
+    if (!record || record.status !== "active") return;
+    const useCount = Number(settlement.useCount);
+    if (Number.isFinite(useCount) && useCount > record.useCount) {
+      record.useCount = useCount;
+    }
+    if (settlement.status && settlement.status !== "active") {
+      record.status = settlement.status;
+      record.value = null;
+    }
+  }
+
   _ensureStoreCapacity() {
     this._expireStaleCredentials();
     if (this._credentialStore.size < this._maxCredentials) return;
@@ -447,6 +480,9 @@ class CredentialAgent {
         "Credential maxUses",
       ),
       origin: String(request.origin ?? "unknown"),
+      capabilityToken: request.capabilityToken
+        ? String(request.capabilityToken)
+        : null,
     };
   }
 
@@ -556,6 +592,38 @@ class CredentialAgent {
       target: normalized.target,
       approvalFingerprint: this._fingerprint(normalized.approvalId),
     });
+    if (this._credentialTransport && normalized.capabilityToken) {
+      try {
+        this._credentialTransport.registerCredential({
+          refId,
+          key: normalized.key,
+          value: normalized.value,
+          target: normalized.target,
+          createdAt,
+          expiresAt: createdAt + normalized.ttlMs,
+          maxUses: normalized.maxUses,
+          useCount: 0,
+          status: "active",
+          capabilityToken: normalized.capabilityToken,
+        });
+      } catch (error) {
+        const record = this._credentialStore.get(refId);
+        record.value = null;
+        record.status = "revoked";
+        this._recordAudit({
+          event: "credential_ref_issue",
+          outcome: "denied",
+          reason: CREDENTIAL_ERROR_CODES.TRANSPORT_UNAVAILABLE,
+          key: normalized.key,
+          target: normalized.target,
+          refFingerprint: this._fingerprint(refId),
+        });
+        throw credentialError(
+          CREDENTIAL_ERROR_CODES.TRANSPORT_UNAVAILABLE,
+          error?.message || "Credential transport is unavailable",
+        );
+      }
+    }
     this._recordAudit({
       event: "credential_ref_issue",
       outcome: "allowed",
@@ -695,6 +763,7 @@ class CredentialAgent {
       record.value = null;
       record.status = "exhausted";
     }
+    this._credentialTransport?.updateCredential(refId, record);
     this._recordAudit({
       event: "credential_ref_resolve",
       outcome: "allowed",
@@ -717,6 +786,7 @@ class CredentialAgent {
     if (!record) return false;
     record.value = null;
     record.status = "revoked";
+    this._credentialTransport?.revokeCredential(refId);
     this._recordAudit({
       event: "credential_ref_revoke",
       outcome: "allowed",
@@ -786,9 +856,18 @@ class CredentialAgent {
     );
   }
 
-  _setReferenceMarkers(safeEnv) {
+  _setReferenceMarkers(safeEnv, context) {
     safeEnv.CC_CREDENTIAL_AGENT_ID = this._agentId;
-    safeEnv.CC_CREDENTIAL_TRANSPORT = this._transport;
+    safeEnv.CC_CREDENTIAL_TRANSPORT = this._transportMode;
+    if (this._credentialTransport && context?.capabilityToken) {
+      safeEnv.CC_CREDENTIAL_ENDPOINT = this._credentialTransport.endpoint;
+      safeEnv.CC_CREDENTIAL_AUTH_TOKEN = context.capabilityToken;
+      safeEnv.CC_CREDENTIAL_TARGET_PROCESS = normalizeProcessTarget(
+        context.target?.process ?? context.process,
+      );
+      const host = normalizeHostTarget(context.target?.host ?? context.host);
+      if (host) safeEnv.CC_CREDENTIAL_TARGET_HOST = host;
+    }
   }
 
   /**
@@ -830,7 +909,7 @@ class CredentialAgent {
       redacted.push(entry);
     }
 
-    if (refsIssued > 0) this._setReferenceMarkers(safeEnv);
+    if (refsIssued > 0) this._setReferenceMarkers(safeEnv, context);
     return {
       safeEnv,
       redacted,
@@ -984,7 +1063,17 @@ class CredentialAgent {
       );
     }
 
-    const context = this._contextForSpawn(spawnOptions);
+    let context = this._contextForSpawn(spawnOptions);
+    if (
+      this._credentialTransport &&
+      this.isEnabled() &&
+      this._canIssueForContext(context)
+    ) {
+      context = {
+        ...context,
+        capabilityToken: this._credentialTransport.createCapabilityToken(),
+      };
+    }
     const env = spawnOptions.env || process.env;
     const {
       safeEnv,
@@ -1019,7 +1108,7 @@ class CredentialAgent {
     }
 
     const refsIssued = envRefsIssued + argRefsIssued;
-    if (refsIssued > 0) this._setReferenceMarkers(safeEnv);
+    if (refsIssued > 0) this._setReferenceMarkers(safeEnv, context);
     spawnOptions.env = safeEnv;
     spawnOptions.args = sanitizedArgs;
 
@@ -1094,6 +1183,14 @@ class CredentialAgent {
     this._accessLog = [];
   }
 
+  waitForTransportReady() {
+    return this._credentialTransport?.waitUntilReady() ?? Promise.resolve(null);
+  }
+
+  closeTransport() {
+    return this._credentialTransport?.close() ?? Promise.resolve();
+  }
+
   /**
    * Get credential agent info for status reporting. No raw references or
    * credential values are included.
@@ -1111,9 +1208,10 @@ class CredentialAgent {
       mode: this._lastEnabledState
         ? "broker-reference"
         : "redact-only-disabled",
-      transport: this._transport,
-      proxyReady: this._proxyReady,
-      ipcAvailable: false,
+      transport: this._transportMode,
+      proxyReady: this._credentialTransport?.ready === true,
+      ipcAvailable: this._credentialTransport?.isAvailable() === true,
+      transportInfo: this._credentialTransport?.getInfo() || null,
       credentialsTracked: this._credentialStore.size,
       activeCredentials: statusCounts.active || 0,
       accessCount: this._accessLog.length,
@@ -1126,7 +1224,7 @@ class CredentialAgent {
   }
 }
 
-const credentialAgent = new CredentialAgent();
+const credentialAgent = new CredentialAgent({ transport: true });
 
 export {
   credentialAgent,