chainlesschain 0.163.1 → 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-executable-identity.js

@@ -41,6 +41,10 @@ export const MCP_STDIO_EXECUTABLE_AUTHORITY_REPLAYED_CODE =
   "CC_MCP_STDIO_EXECUTABLE_AUTHORITY_REPLAYED";
 export const MCP_STDIO_EXECUTABLE_IDENTITY_ROLLBACK_CODE =
   "CC_MCP_STDIO_EXECUTABLE_IDENTITY_ROLLBACK";
+export const MCP_STDIO_RUNTIME_KIND_REQUIRED_CODE =
+  "CC_MCP_STDIO_RUNTIME_KIND_REQUIRED";
+export const MCP_STDIO_RUNTIME_KIND_INVALID_CODE =
+  "CC_MCP_STDIO_RUNTIME_KIND_INVALID";
 export const MCP_STDIO_CAPSULE_SANDBOX_CONTRACT_KIND =
   "strict-mcp-node-capsule";
 export const MCP_STDIO_CAPSULE_CODE_SNAPSHOT_BOUNDARY = "code-snapshot";
@@ -54,6 +58,17 @@ const HASH_CHUNK_BYTES = 1024 * 1024;
 const issuedLaunchAuthorities = new WeakMap();
 const issuedCapsuleSandboxContracts = new WeakMap();
 
+export const MCP_STDIO_RUNTIME_KINDS = Object.freeze([
+  "native",
+  "node",
+  "python",
+  "posix-shell",
+  "powershell",
+  "java",
+  "dotnet",
+]);
+const MCP_STDIO_RUNTIME_KIND_SET = new Set(MCP_STDIO_RUNTIME_KINDS);
+
 const DYNAMIC_LAUNCHERS = new Set([
   "bunx",
   "corepack",
@@ -391,6 +406,46 @@ function executableBasename(value) {
     .toLowerCase();
 }
 
+function inferredRuntimeKind(commandPath) {
+  const name = executableBasename(commandPath);
+  if (["node", "nodejs"].includes(name)) return "node";
+  if (/^python(?:w)?(?:\d+(?:\.\d+)*)?$/.test(name)) return "python";
+  if (["bash", "dash", "ksh", "sh", "zsh"].includes(name)) {
+    return "posix-shell";
+  }
+  if (["powershell", "pwsh"].includes(name)) return "powershell";
+  if (name === "java") return "java";
+  if (name === "dotnet") return "dotnet";
+  return null;
+}
+
+export function resolveMcpStdioRuntimeKind(commandPath, requestedKind = null) {
+  const inferred = inferredRuntimeKind(commandPath);
+  if (requestedKind != null) {
+    if (
+      typeof requestedKind !== "string" ||
+      !MCP_STDIO_RUNTIME_KIND_SET.has(requestedKind)
+    ) {
+      throw identityError(
+        MCP_STDIO_RUNTIME_KIND_INVALID_CODE,
+        `MCP stdio runtimeKind must be one of: ${MCP_STDIO_RUNTIME_KINDS.join(", ")}`,
+      );
+    }
+    if (inferred && requestedKind !== inferred) {
+      throw identityError(
+        MCP_STDIO_RUNTIME_KIND_INVALID_CODE,
+        `MCP stdio runtimeKind "${requestedKind}" conflicts with recognized ${inferred} executable "${executableBasename(commandPath)}"`,
+      );
+    }
+    return requestedKind;
+  }
+  if (inferred) return inferred;
+  throw identityError(
+    MCP_STDIO_RUNTIME_KIND_REQUIRED_CODE,
+    `MCP stdio executable "${executableBasename(commandPath)}" has no recognized runtime semantics; set runtimeKind explicitly before trusting it`,
+  );
+}
+
 function materializeLaunchEnvironment(hostEnv, configEnv) {
   const launch = sanitizeMcpStdioHostEnvironment(hostEnv);
   for (const [key, value] of Object.entries(configEnv || {})) {
@@ -617,8 +672,7 @@ function localEntrypoint(value, cwd, label) {
     : path.resolve(cwd, value);
 }
 
-function interpreterEntrypoints(commandPath, args, cwd) {
-  const name = executableBasename(commandPath);
+function interpreterEntrypoints(runtimeKind, args, cwd) {
   const values = [...args];
   const entry = (index, role = "entrypoint") => [
     {
@@ -627,7 +681,7 @@ function interpreterEntrypoints(commandPath, args, cwd) {
       role,
     },
   ];
-  if (["node", "nodejs"].includes(name)) {
+  if (runtimeKind === "node") {
     for (let index = 0; index < values.length; index += 1) {
       const value = values[index];
       if (["-e", "--eval", "-p", "--print"].includes(value)) return [];
@@ -655,7 +709,7 @@ function interpreterEntrypoints(commandPath, args, cwd) {
       "MCP stdio Node launch must provide a script or inline program",
     );
   }
-  if (["python", "python3", "pythonw", "pythonw3"].includes(name)) {
+  if (runtimeKind === "python") {
     for (let index = 0; index < values.length; index += 1) {
       const value = values[index];
       if (value === "-c") return [];
@@ -673,7 +727,7 @@ function interpreterEntrypoints(commandPath, args, cwd) {
       "MCP stdio Python launch must provide a script or inline program",
     );
   }
-  if (["bash", "dash", "ksh", "sh", "zsh"].includes(name)) {
+  if (runtimeKind === "posix-shell") {
     const inline = values.findIndex((value) => value === "-c");
     if (inline >= 0) return [];
     const index = values.findIndex((value) => !value.startsWith("-"));
@@ -683,7 +737,7 @@ function interpreterEntrypoints(commandPath, args, cwd) {
       "MCP stdio shell launch must provide a script or inline command",
     );
   }
-  if (["powershell", "pwsh"].includes(name)) {
+  if (runtimeKind === "powershell") {
     const fileIndex = values.findIndex((value) => /^-file$/i.test(value));
     if (fileIndex >= 0) return entry(fileIndex + 1, "powershell-script");
     if (values.some((value) => /^-(?:command|encodedcommand)$/i.test(value))) {
@@ -694,7 +748,7 @@ function interpreterEntrypoints(commandPath, args, cwd) {
       "MCP stdio PowerShell launch must use -File or an inline command",
     );
   }
-  if (name === "java") {
+  if (runtimeKind === "java") {
     const jarIndex = values.findIndex((value) => value === "-jar");
     if (jarIndex >= 0) return entry(jarIndex + 1, "java-jar");
     throw identityError(
@@ -702,7 +756,7 @@ function interpreterEntrypoints(commandPath, args, cwd) {
       "MCP stdio Java classpath launches are not bound to one entrypoint file",
     );
   }
-  if (name === "dotnet") {
+  if (runtimeKind === "dotnet") {
     const index = values.findIndex((value) => !value.startsWith("-"));
     if (index >= 0 && /\.dll$/i.test(values[index])) {
       return entry(index, "dotnet-assembly");
@@ -844,6 +898,7 @@ export function attestMcpStdioExecutableIdentity({
   env = {},
   cwd = process.cwd(),
   platform = process.platform,
+  runtimeKind: requestedRuntimeKind = null,
 }) {
   const name = executableBasename(command);
   if (DYNAMIC_LAUNCHERS.has(name)) {
@@ -868,8 +923,12 @@ export function attestMcpStdioExecutableIdentity({
       "MCP stdio direct shebang commands do not bind the interpreter bytes; configure the interpreter and script as command + args",
     );
   }
+  const runtimeKind = resolveMcpStdioRuntimeKind(
+    commandIdentity.realPath,
+    requestedRuntimeKind,
+  );
   const launchArgs = [...args];
-  const entrypoints = interpreterEntrypoints(commandPath, launchArgs, cwd).map(
+  const entrypoints = interpreterEntrypoints(runtimeKind, launchArgs, cwd).map(
     ({ argIndex, path: entryPath, role }) => {
       const identity = attestFile(
         entryPath,
@@ -882,7 +941,8 @@ export function attestMcpStdioExecutableIdentity({
     },
   );
   const identity = Object.freeze({
-    version: 1,
+    version: 2,
+    runtimeKind,
     command: commandIdentity,
     entrypoints: Object.freeze(entrypoints),
   });
@@ -919,7 +979,8 @@ function trustMessage(serverName, attestation, status) {
 function materializedAttestation(attestation, materialization) {
   if (!materialization) return attestation;
   const identity = Object.freeze({
-    version: 2,
+    version: 3,
+    runtimeKind: attestation.identity.runtimeKind,
     command: attestation.identity.command,
     entrypoints: attestation.identity.entrypoints,
     materialization: materialization.identity,
@@ -1038,6 +1099,7 @@ export function prepareMcpStdioExecutableIdentity({
       args: effectiveArgs,
       env: config.env || {},
       cwd,
+      runtimeKind: materialization ? "node" : config.runtimeKind,
     }),
     materialization,
   );
@@ -1063,6 +1125,7 @@ export function prepareMcpStdioExecutableIdentity({
       identity: attestation.identity,
       identityDigest: attestation.identityDigest,
       materialization,
+      runtimeKind: attestation.identity.runtimeKind,
     }),
   );
   return Object.freeze({
@@ -1107,6 +1170,7 @@ export function consumeMcpStdioExecutableIdentityAuthority(
     command,
     args,
     cwd: process.cwd(),
+    runtimeKind: issued.runtimeKind,
   });
   if (issued.materialization) {
     const verified = reattestMcpStdioPackageMaterialization(