chainlesschain 0.163.2 → 0.163.3

package/src/lib/mcp-headers-helper.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { isProxy } from "node:util/types";
 import executionBroker from "./process-execution-broker/index.js";
 import hookShellCommand from "./hook-shell-command.cjs";
 import {
@@ -9,6 +10,7 @@ import {
 import { checkLocalMcpHeadersHelperTrust } from "./mcp-headers-helper-trust.js";
 import { resolvePluginWorkspaceAuthority } from "./plugin-runtime/sandbox-policy.js";
 import { resolveProjectMcpWorkspaceAuthority } from "./project-mcp-trust.js";
+import { normalizeMcpSandboxPolicy } from "./mcp-sandbox-policy.js";
 
 const { buildExplicitHookShellInvocation } = hookShellCommand;
 
@@ -42,6 +44,45 @@ function helperError(code, message) {
   return error;
 }
 
+function declaredSandboxPolicy(config) {
+  if (!config || typeof config !== "object" || isProxy(config)) {
+    throw helperError(
+      "CC_MCP_SANDBOX_POLICY_INVALID",
+      "MCP headersHelper sandbox policy owner must be a non-Proxy object",
+    );
+  }
+  const descriptor = Object.getOwnPropertyDescriptor(config, "sandboxPolicy");
+  if (!descriptor) return null;
+  if (!("value" in descriptor)) {
+    throw helperError(
+      "CC_MCP_SANDBOX_POLICY_INVALID",
+      "MCP headersHelper sandboxPolicy must be an own data property",
+    );
+  }
+  return normalizeMcpSandboxPolicy(descriptor.value, {
+    label: "MCP headersHelper sandboxPolicy",
+  });
+}
+
+function sandboxExecution(config, sandboxPolicy, fallbackOrigin) {
+  if (!sandboxPolicy) return null;
+  return Object.freeze({
+    origin:
+      typeof config.origin === "string" && config.origin.length > 0
+        ? config.origin
+        : fallbackOrigin,
+    policy:
+      typeof config.policy === "string" && config.policy.length > 0
+        ? config.policy
+        : "allow",
+    scope:
+      typeof config.scope === "string" && config.scope.length > 0
+        ? config.scope
+        : "mcp",
+    sandboxPolicy,
+  });
+}
+
 function normalizeHelperCommand(value) {
   if (
     typeof value !== "string" ||
@@ -89,6 +130,16 @@ function canonicalHelperCwd(value, realpath = fs.realpathSync.native) {
   return canonical;
 }
 
+function hasInvalidHeaderValueCharacter(value) {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code <= 0x08 || (code >= 0x0a && code <= 0x1f) || code === 0x7f) {
+      return true;
+    }
+  }
+  return false;
+}
+
 function normalizeHeaderMap(value, source) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw helperError(
@@ -108,7 +159,7 @@ function normalizeHeaderMap(value, source) {
     if (
       !HEADER_NAME.test(name) ||
       typeof headerValue !== "string" ||
-      /[\0-\x08\x0a-\x1f\x7f]/.test(headerValue) ||
+      hasInvalidHeaderValueCharacter(headerValue) ||
       Buffer.byteLength(headerValue, "utf8") > MAX_HEADER_VALUE_BYTES ||
       (source === "dynamic" && TRANSPORT_OWNED_HEADERS.has(name.toLowerCase()))
     ) {
@@ -138,6 +189,7 @@ function isPathInside(root, candidate) {
  * plugin configs must carry the collector-issued opaque plugin authority.
  */
 export function resolveMcpHeadersHelperContext(config = {}, deps = {}) {
+  const sandboxPolicy = declaredSandboxPolicy(config);
   if (config.origin === "plugin:mcp") {
     const resolvePlugin =
       deps.resolvePluginWorkspaceAuthority || resolvePluginWorkspaceAuthority;
@@ -156,17 +208,15 @@ export function resolveMcpHeadersHelperContext(config = {}, deps = {}) {
     return {
       cwd: pluginRoot,
       pluginRoot,
-      execution: {
+      execution: Object.freeze({
         origin: config.origin,
         policy: config.policy || "allow",
         scope: config.scope || "mcp",
         pluginId: config.pluginId,
         pluginVersion: config.pluginVersion,
         pluginSource: config.pluginSource,
-        ...(config.sandboxPolicy
-          ? { sandboxPolicy: config.sandboxPolicy }
-          : {}),
-      },
+        ...(sandboxPolicy ? { sandboxPolicy } : {}),
+      }),
     };
   }
 
@@ -253,12 +303,30 @@ export function resolveMcpHeadersHelperContext(config = {}, deps = {}) {
         );
       }
     }
-    return { cwd: binding.workspaceRoot, pluginRoot: null, execution: null };
+    return {
+      cwd: binding.workspaceRoot,
+      pluginRoot: null,
+      execution: sandboxExecution(
+        config,
+        sandboxPolicy,
+        `mcp:headers-helper:${scope}`,
+      ),
+    };
+  }
+  if (sandboxPolicy && !binding?.workspaceRoot) {
+    throw helperError(
+      "CC_MCP_HEADERS_HELPER_UNTRUSTED_WORKSPACE",
+      "Policy-bearing MCP headersHelper requires a trusted host workspace",
+    );
   }
   return {
     cwd: binding?.workspaceRoot || path.resolve(deps.cwd || process.cwd()),
     pluginRoot: null,
-    execution: null,
+    execution: sandboxExecution(
+      config,
+      sandboxPolicy,
+      `mcp:headers-helper:${scope}`,
+    ),
   };
 }
 

package/src/lib/mcp-sandbox-policy.js

@@ -0,0 +1,155 @@
+import { isProxy } from "node:util/types";
+
+/**
+ * Declarative sandbox boundaries an external MCP source may require.
+ *
+ * Internal broker guarantees (for example process-tree and code-snapshot) are
+ * deliberately not part of this source-controlled contract. A trusted host
+ * may add its own non-removable requirements after this value is normalized.
+ */
+export const MCP_SANDBOX_BOUNDARIES = Object.freeze(["filesystem", "network"]);
+
+export const MCP_SANDBOX_POLICY_INVALID_CODE = "CC_MCP_SANDBOX_POLICY_INVALID";
+export const MCP_STDIO_CWD_INVALID_CODE = "CC_MCP_STDIO_SANDBOX_CWD_INVALID";
+
+const SUPPORTED_BOUNDARIES = new Set(MCP_SANDBOX_BOUNDARIES);
+const MAX_BOUNDARY_DECLARATIONS = 32;
+
+function invalidPolicy(message) {
+  const error = new TypeError(message);
+  error.code = MCP_SANDBOX_POLICY_INVALID_CODE;
+  return error;
+}
+
+function invalidCwd(message) {
+  const error = new TypeError(message);
+  error.code = MCP_STDIO_CWD_INVALID_CODE;
+  return error;
+}
+
+/**
+ * Read an optional stdio working directory without invoking accessors or Proxy
+ * traps. Absence means "retain/default" while null and the empty string are an
+ * explicit clear. Every other value must be a NUL-free string.
+ */
+export function readMcpStdioCwd(owner, options = {}) {
+  const label =
+    typeof options.label === "string" && options.label.length > 0
+      ? options.label
+      : "MCP stdio config";
+  if (!owner || typeof owner !== "object" || isProxy(owner)) {
+    throw invalidCwd(`${label} must be a non-Proxy object`);
+  }
+  const descriptor = Object.getOwnPropertyDescriptor(owner, "cwd");
+  if (!descriptor) return { present: false, cwd: null };
+  if (!("value" in descriptor)) {
+    throw invalidCwd(`${label}.cwd must be an own data property`);
+  }
+  const value = descriptor.value;
+  if (value == null || value === "") return { present: true, cwd: null };
+  if (typeof value !== "string" || value.includes("\0")) {
+    throw invalidCwd(`${label}.cwd must be a NUL-free path string`);
+  }
+  return { present: true, cwd: value };
+}
+
+function ownDataDescriptor(value, key, label) {
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  if (!descriptor || !("value" in descriptor)) {
+    throw invalidPolicy(`${label} must be an own data property`);
+  }
+  return descriptor;
+}
+
+function normalizeRequiredBoundaries(value, label) {
+  if (!Array.isArray(value) || isProxy(value)) {
+    throw invalidPolicy(`${label} must be a non-Proxy array`);
+  }
+
+  const lengthDescriptor = ownDataDescriptor(
+    value,
+    "length",
+    `${label}.length`,
+  );
+  const length = lengthDescriptor.value;
+  if (length > MAX_BOUNDARY_DECLARATIONS) {
+    throw invalidPolicy(
+      `${label} exceeds ${MAX_BOUNDARY_DECLARATIONS} boundary declarations`,
+    );
+  }
+  const allowedKeys = new Set(["length"]);
+  const requiredBoundaries = new Set();
+
+  for (let index = 0; index < length; index += 1) {
+    const key = String(index);
+    allowedKeys.add(key);
+    const descriptor = ownDataDescriptor(value, key, `${label}[${index}]`);
+    const boundary = descriptor.value;
+    if (typeof boundary !== "string" || !SUPPORTED_BOUNDARIES.has(boundary)) {
+      throw invalidPolicy(`${label} contains an unsupported boundary`);
+    }
+    requiredBoundaries.add(boundary);
+  }
+
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== "string" || !allowedKeys.has(key)) {
+      throw invalidPolicy(
+        `${label} contains unsupported property: ${String(key)}`,
+      );
+    }
+  }
+
+  return Object.freeze([...requiredBoundaries].sort());
+}
+
+/**
+ * Normalize an MCP source's small declarative sandbox contract.
+ *
+ * The input is treated as untrusted data: Proxy objects, inherited/accessor
+ * fields, non-plain objects, and unknown fields are rejected without invoking
+ * user-controlled code. `null` and an empty policy retain the legacy meaning
+ * of "no source-declared requirements".
+ *
+ * @param {unknown} value
+ * @param {{label?: string}} [options]
+ * @returns {{requiredBoundaries: readonly string[]}|null}
+ */
+export function normalizeMcpSandboxPolicy(value, options = {}) {
+  const label =
+    typeof options.label === "string" && options.label.length > 0
+      ? options.label
+      : "sandboxPolicy";
+
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "object" || Array.isArray(value) || isProxy(value)) {
+    throw invalidPolicy(`${label} must be a non-Proxy plain object`);
+  }
+
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw invalidPolicy(`${label} must be a plain object`);
+  }
+
+  const keys = Reflect.ownKeys(value);
+  for (const key of keys) {
+    if (key !== "requiredBoundaries") {
+      throw invalidPolicy(
+        `${label} contains unsupported field: ${String(key)}`,
+      );
+    }
+  }
+
+  if (!keys.includes("requiredBoundaries")) return null;
+  const descriptor = ownDataDescriptor(
+    value,
+    "requiredBoundaries",
+    `${label}.requiredBoundaries`,
+  );
+  const requiredBoundaries = normalizeRequiredBoundaries(
+    descriptor.value,
+    `${label}.requiredBoundaries`,
+  );
+  if (requiredBoundaries.length === 0) return null;
+
+  return Object.freeze({ requiredBoundaries });
+}

package/src/lib/mcp-stdio-execution-authority.js

@@ -11,7 +11,14 @@
  */
 
 import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
 import { isProxy } from "node:util/types";
+import {
+  currentHostHooksV2WorkspaceBinding,
+  resolveHostHooksV2WorkspaceBinding,
+} from "./hooks-v2-workspace-context.js";
+import { resolvePluginWorkspaceAuthority } from "./plugin-runtime/sandbox-policy.js";
 
 export const MCP_STDIO_LOCAL_CODE_TRUST_REQUIRED_CODE =
   "CC_MCP_STDIO_LOCAL_CODE_TRUST_REQUIRED";
@@ -175,6 +182,7 @@ function invocationSnapshot(serverName, config) {
       dataProperty(config, "projectPath", null),
       "projectPath",
     ),
+    cwd: scalar(dataProperty(config, "cwd", null), "cwd"),
     pluginId: scalar(dataProperty(config, "pluginId", null), "pluginId"),
     pluginVersion: scalar(
       dataProperty(config, "pluginVersion", null),
@@ -205,6 +213,8 @@ function comparableSnapshot(snapshot) {
     projectMcpWorkspaceAuthority: _projectAuthority,
     ...plain
   } = snapshot;
+  void _pluginAuthority;
+  void _projectAuthority;
   return plain;
 }
 
@@ -224,6 +234,116 @@ function sameSnapshot(expected, actual) {
   );
 }
 
+function directoryGeneration(stat) {
+  return stat.birthtimeNs > 0n
+    ? `birth:${stat.birthtimeNs.toString()}`
+    : `ctime:${stat.ctimeNs.toString()}`;
+}
+
+function captureDirectoryIdentity(value, base, label) {
+  if (typeof value !== "string" || value.length === 0 || value.includes("\0")) {
+    throw new TypeError(`${label} must be a non-empty directory path`);
+  }
+  const requestedPath = path.isAbsolute(value)
+    ? path.resolve(value)
+    : path.resolve(base, value);
+  let canonicalRoot;
+  let stat;
+  try {
+    const implementation = fs.realpathSync.native || fs.realpathSync;
+    canonicalRoot = implementation.call(fs.realpathSync, requestedPath);
+    stat = fs.statSync(canonicalRoot, { bigint: true });
+  } catch (cause) {
+    throw new TypeError(`${label} must resolve to an existing directory`, {
+      cause,
+    });
+  }
+  if (!stat.isDirectory()) {
+    throw new TypeError(`${label} must resolve to a directory`);
+  }
+  return Object.freeze({
+    requestedPath,
+    canonicalRoot,
+    device: stat.dev,
+    inode: stat.ino,
+    generation: directoryGeneration(stat),
+  });
+}
+
+function sameDirectoryIdentity(expected, actual) {
+  return (
+    expected.canonicalRoot === actual.canonicalRoot &&
+    expected.device === actual.device &&
+    expected.inode === actual.inode &&
+    expected.generation === actual.generation
+  );
+}
+
+function verifyDirectoryIdentity(binding) {
+  try {
+    return sameDirectoryIdentity(
+      binding,
+      captureDirectoryIdentity(
+        binding.requestedPath,
+        process.cwd(),
+        "approved MCP stdio cwd",
+      ),
+    );
+  } catch {
+    return false;
+  }
+}
+
+function approvedWorkspaceRoot(snapshot, workspaceRoot, workspaceBinding) {
+  if (snapshot.origin === "plugin:mcp") {
+    const pluginRoot = resolvePluginWorkspaceAuthority(
+      snapshot.pluginWorkspaceAuthority,
+      {
+        origin: snapshot.origin,
+        pluginId: snapshot.pluginId,
+        pluginVersion: snapshot.pluginVersion,
+        pluginSource: snapshot.pluginSource,
+      },
+    );
+    if (pluginRoot) return pluginRoot;
+  }
+  if (workspaceBinding != null) {
+    const resolvedBinding =
+      resolveHostHooksV2WorkspaceBinding(workspaceBinding);
+    if (!resolvedBinding?.workspaceRoot) {
+      throw new TypeError(
+        "approved MCP stdio workspace binding is invalid or stale",
+      );
+    }
+    return resolvedBinding.workspaceRoot;
+  }
+  if (typeof workspaceRoot === "string" && workspaceRoot.length > 0) {
+    return workspaceRoot;
+  }
+  const hostRoot = currentHostHooksV2WorkspaceBinding()?.workspaceRoot;
+  if (hostRoot) return hostRoot;
+  if (typeof snapshot.projectPath === "string" && snapshot.projectPath) {
+    return snapshot.projectPath;
+  }
+  return process.cwd();
+}
+
+function captureApprovedCwd(snapshot, workspaceRoot, workspaceBinding) {
+  if (snapshot.sandboxPolicy == null || snapshot.cwd == null) return null;
+  return captureDirectoryIdentity(
+    snapshot.cwd,
+    approvedWorkspaceRoot(snapshot, workspaceRoot, workspaceBinding),
+    "approved MCP stdio cwd",
+  );
+}
+
+function staleDirectoryError(serverName) {
+  return authorityError(
+    MCP_STDIO_EXECUTION_AUTHORITY_STALE_CODE,
+    `MCP stdio working directory for "${String(serverName)}" changed after approval`,
+  );
+}
+
 function materializeSnapshot(snapshot) {
   return {
     command: snapshot.command,
@@ -237,6 +357,7 @@ function materializeSnapshot(snapshot) {
     configScope: snapshot.configScope,
     configSource: snapshot.configSource,
     projectPath: snapshot.projectPath,
+    cwd: snapshot.cwd,
     pluginId: snapshot.pluginId,
     pluginVersion: snapshot.pluginVersion,
     pluginSource: snapshot.pluginSource,
@@ -254,6 +375,8 @@ export function issueMcpStdioExecutionAuthority({
   config,
   approvalKind,
   approvalSource,
+  workspaceRoot,
+  workspaceBinding,
 }) {
   if (!APPROVAL_KINDS.has(approvalKind)) {
     throw new TypeError("MCP stdio approval kind is not recognized");
@@ -261,6 +384,11 @@ export function issueMcpStdioExecutionAuthority({
   const source = scalar(approvalSource, "approvalSource", { nullable: false });
   if (!source.trim()) throw new TypeError("approvalSource must not be empty");
   const snapshot = invocationSnapshot(serverName, config);
+  const cwdIdentity = captureApprovedCwd(
+    snapshot,
+    workspaceRoot,
+    workspaceBinding,
+  );
   const token = Object.freeze({});
   issuedAuthorities.set(
     token,
@@ -269,6 +397,7 @@ export function issueMcpStdioExecutionAuthority({
       approvalSource: source,
       fingerprint: snapshotDigest(snapshot),
       snapshot,
+      cwdIdentity,
     }),
   );
   return token;
@@ -309,6 +438,9 @@ export function consumeMcpStdioExecutionAuthority(
       `MCP stdio invocation for "${String(serverName)}" changed after approval`,
     );
   }
+  if (issued.cwdIdentity && !verifyDirectoryIdentity(issued.cwdIdentity)) {
+    throw staleDirectoryError(serverName);
+  }
   const approval = Object.freeze({
     approvalKind: issued.approvalKind,
     approvalSource: issued.approvalSource,
@@ -336,6 +468,9 @@ export function renewMcpStdioExecutionAuthority(
       `MCP stdio reconnect invocation for "${String(serverName)}" changed after approval`,
     );
   }
+  if (issued.cwdIdentity && !verifyDirectoryIdentity(issued.cwdIdentity)) {
+    throw staleDirectoryError(serverName);
+  }
   const token = Object.freeze({});
   issuedAuthorities.set(token, issued);
   return token;
@@ -352,6 +487,34 @@ export function materializeApprovedMcpStdioInvocation(approval) {
   return materializeSnapshot(issued.snapshot);
 }
 
+export function verifyMcpStdioApprovedWorkingDirectory(
+  approval,
+  workingDirectory,
+) {
+  const issued = renewableApprovals.get(approval);
+  if (!issued) {
+    throw authorityError(
+      MCP_STDIO_LOCAL_CODE_TRUST_REQUIRED_CODE,
+      "MCP stdio working directory requires a consumed execution approval",
+    );
+  }
+  if (!issued.cwdIdentity) return true;
+  let actual;
+  try {
+    actual = captureDirectoryIdentity(
+      workingDirectory,
+      process.cwd(),
+      "materialized MCP stdio cwd",
+    );
+  } catch {
+    throw staleDirectoryError(issued.snapshot.serverName);
+  }
+  if (!sameDirectoryIdentity(issued.cwdIdentity, actual)) {
+    throw staleDirectoryError(issued.snapshot.serverName);
+  }
+  return true;
+}
+
 /**
  * Return only the content-free provenance needed to key a durable executable
  * identity. The approval object itself remains an unforgeable WeakMap-backed