chainlesschain 0.162.183 → 0.162.185

package/src/lib/hook-runner.cjs

@@ -26,9 +26,14 @@ const {
   loadShellConfig,
 } = require("./shell-selector.cjs");
 const { mergeHookDecisions } = require("./hook-event-bus.cjs");
+const { buildManagedHookEnvironment } = require("./hook-environment.cjs");
 const {
-  buildManagedHookEnvironment,
-} = require("./hook-environment.cjs");
+  buildExplicitHookShellInvocation,
+  issueTrustedHookSandboxContract,
+  requireTrustedHookRoot,
+  requiresExplicitHookShell,
+  sandboxBoundaryError,
+} = require("./hook-shell-command.cjs");
 
 const _deps = { runSync: null, run: null };
 Object.defineProperties(_deps, {
@@ -125,17 +130,13 @@ function hookSpawnFailure(error) {
   const sandboxDenied =
     error?.code === "ERR_PROCESS_SANDBOX_BOUNDARY_UNSATISFIED";
   return {
-    decision: sandboxDenied
-      ? HOOK_DECISIONS.BLOCK
-      : HOOK_DECISIONS.CONTINUE,
+    decision: sandboxDenied ? HOOK_DECISIONS.BLOCK : HOOK_DECISIONS.CONTINUE,
     reason: sandboxDenied
       ? `hook sandbox denied: ${error.message}`
       : `hook spawn failed: ${error.message}`,
     exitCode: null,
     error: error.message,
-    ...(sandboxDenied
-      ? { sandboxDenied: true }
-      : { nonBlockingError: true }),
+    ...(sandboxDenied ? { sandboxDenied: true } : { nonBlockingError: true }),
   };
 }
 
@@ -321,12 +322,17 @@ function _runCommandHookInner(command, input = {}, opts = {}) {
   let res;
   try {
     const sandboxPolicy = resolveHookSandboxPolicy({}, opts);
+    const explicitSandboxShell = requiresExplicitHookShell(sandboxPolicy);
+    const trustedRoot = explicitSandboxShell
+      ? requireTrustedHookRoot(cwd)
+      : null;
+    const workingDirectory = trustedRoot || cwd || process.cwd();
     const common = {
       input: JSON.stringify({
         ...input,
         schema_version: input.schema_version ?? HOOK_PAYLOAD_SCHEMA_VERSION,
       }),
-      cwd: cwd || process.cwd(),
+      cwd: workingDirectory,
       encoding: "utf-8",
       timeout,
       maxBuffer: 8 * 1024 * 1024,
@@ -346,6 +352,7 @@ function _runCommandHookInner(command, input = {}, opts = {}) {
       pluginId: opts.pluginId || null,
       pluginVersion: opts.pluginVersion || null,
       pluginSource: opts.pluginSource || null,
+      ...(explicitSandboxShell || usePowershell ? { shell: false } : {}),
       ...(sandboxPolicy ? { sandboxPolicy } : {}),
     };
     const brokerRunSync =
@@ -355,13 +362,42 @@ function _runCommandHookInner(command, input = {}, opts = {}) {
         ? opts.broker["spawnSync"].bind(opts.broker)
         : null;
     if (brokerRunSync) {
-      const invocation = usePowershell
-        ? buildPowershellArgv(command, shellKind, {
-            executionPolicy: loadShellConfig({ cwd: common.cwd })
-              .executionPolicy,
+      const powershellOptions = {
+        executionPolicy: loadShellConfig({ cwd: common.cwd }).executionPolicy,
+      };
+      const invocation = explicitSandboxShell
+        ? buildExplicitHookShellInvocation(command, {
+            shellKind,
+            buildPowershellArgv,
+            powershellOptions,
           })
-        : { file: command, argv: [] };
-      res = brokerRunSync(invocation.file, invocation.argv, processOptions);
+        : usePowershell
+          ? buildPowershellArgv(command, shellKind, powershellOptions)
+          : { file: command, argv: [] };
+      let brokerOptions = processOptions;
+      if (explicitSandboxShell) {
+        const issuer = opts.broker?.issueLinuxWorkspaceSandboxExecutionContract;
+        const sandboxExecutionContract = issueTrustedHookSandboxContract({
+          issuer,
+          receiver: opts.broker,
+          file: invocation.file,
+          args: invocation.argv,
+          options: processOptions,
+          trustedRoot,
+          sync: true,
+          label: "trusted plugin hook sandbox contract issuance failed",
+        });
+        if (process.platform === "linux" && !sandboxExecutionContract) {
+          throw sandboxBoundaryError(
+            "trusted Linux hook sandbox contract issuer is unavailable",
+          );
+        }
+        brokerOptions = {
+          ...processOptions,
+          ...(sandboxExecutionContract ? { sandboxExecutionContract } : {}),
+        };
+      }
+      res = brokerRunSync(invocation.file, invocation.argv, brokerOptions);
     } else if (usePowershell) {
       // Per-hook `shell: powershell|pwsh` (settings hook entry): explicit argv
       // instead of the default shell; the enterprise ExecutionPolicy override
@@ -374,6 +410,12 @@ function _runCommandHookInner(command, input = {}, opts = {}) {
         throw new Error("hook process runner unavailable");
       }
       res = _deps.runSync(inv.file, inv.argv, processOptions);
+    } else if (explicitSandboxShell) {
+      if (typeof _deps.runSync !== "function") {
+        throw new Error("hook process runner unavailable");
+      }
+      const invocation = buildExplicitHookShellInvocation(command);
+      res = _deps.runSync(invocation.file, invocation.argv, processOptions);
     } else {
       if (typeof _deps.runSync !== "function") {
         throw new Error("hook process runner unavailable");
@@ -396,7 +438,13 @@ function _runCommandHookInner(command, input = {}, opts = {}) {
 function interpretHookOutcome(res) {
   // A surfaced spawn error (timeout / ENOENT, status null) is non-blocking — a
   // broken hook must never wedge the agent; only an explicit block blocks.
-  if (res.error) {
+  // spawnSync can also report EPIPE after a fast-exiting hook closes stdin,
+  // even though the child has a real exit status and complete output. The
+  // async runner already treats that early stdin close as harmless; preserve
+  // the exit-code/stdout protocol on the sync path as well.
+  const inputClosedAfterExit =
+    res.error?.code === "EPIPE" && Number.isInteger(res.status);
+  if (res.error && !inputClosedAfterExit) {
     return {
       decision: HOOK_DECISIONS.CONTINUE,
       reason: `hook error: ${res.error.message}`,
@@ -467,7 +515,6 @@ async function _runCommandHookInnerAsync(command, input = {}, opts = {}) {
       : 60000;
   const shellKind = normalizeShellKind(opts.shell);
   const usePowershell = shellKind === "powershell" || shellKind === "pwsh";
-  const wd = cwd || process.cwd();
   const inputJson = JSON.stringify({
     ...input,
     schema_version: input.schema_version ?? HOOK_PAYLOAD_SCHEMA_VERSION,
@@ -485,6 +532,14 @@ async function _runCommandHookInnerAsync(command, input = {}, opts = {}) {
   } catch (error) {
     return hookSpawnFailure(error);
   }
+  const explicitSandboxShell = requiresExplicitHookShell(sandboxPolicy);
+  let trustedRoot;
+  try {
+    trustedRoot = explicitSandboxShell ? requireTrustedHookRoot(cwd) : null;
+  } catch (error) {
+    return hookSpawnFailure(error);
+  }
+  const wd = trustedRoot || cwd || process.cwd();
   const processOptions = {
     cwd: wd,
     env: spawnEnv,
@@ -494,6 +549,7 @@ async function _runCommandHookInnerAsync(command, input = {}, opts = {}) {
     pluginId: opts.pluginId || null,
     pluginVersion: opts.pluginVersion || null,
     pluginSource: opts.pluginSource || null,
+    ...(explicitSandboxShell || usePowershell ? { shell: false } : {}),
     ...(sandboxPolicy ? { sandboxPolicy } : {}),
   };
 
@@ -509,7 +565,38 @@ async function _runCommandHookInnerAsync(command, input = {}, opts = {}) {
     if (typeof run !== "function") {
       throw new Error("hook process runner unavailable");
     }
-    if (usePowershell) {
+    if (explicitSandboxShell) {
+      const invocation = buildExplicitHookShellInvocation(command, {
+        shellKind,
+        buildPowershellArgv,
+        powershellOptions: {
+          executionPolicy: loadShellConfig({ cwd: wd }).executionPolicy,
+        },
+      });
+      let brokerOptions = processOptions;
+      if (brokerRun) {
+        const issuer = opts.broker?.issueLinuxWorkspaceSandboxExecutionContract;
+        const sandboxExecutionContract = issueTrustedHookSandboxContract({
+          issuer,
+          receiver: opts.broker,
+          file: invocation.file,
+          args: invocation.argv,
+          options: processOptions,
+          trustedRoot,
+          label: "trusted plugin hook sandbox contract issuance failed",
+        });
+        if (process.platform === "linux" && !sandboxExecutionContract) {
+          throw sandboxBoundaryError(
+            "trusted Linux hook sandbox contract issuer is unavailable",
+          );
+        }
+        brokerOptions = {
+          ...processOptions,
+          ...(sandboxExecutionContract ? { sandboxExecutionContract } : {}),
+        };
+      }
+      child = run(invocation.file, invocation.argv, brokerOptions);
+    } else if (usePowershell) {
       const { executionPolicy } = loadShellConfig({ cwd: wd });
       const inv = buildPowershellArgv(command, shellKind, { executionPolicy });
       child = run(inv.file, inv.argv, processOptions);

package/src/lib/hook-runner.js

@@ -1,5 +1,13 @@
 import runner from "./hook-runner.cjs";
 import executionBroker from "./process-execution-broker/index.js";
+import hookShellCommand from "./hook-shell-command.cjs";
+
+const {
+  issueTrustedHookSandboxContract,
+  requireTrustedHookRoot,
+  requiresExplicitHookShell,
+  sandboxBoundaryError,
+} = hookShellCommand;
 
 const brokerRunner = executionBroker.spawn.bind(executionBroker);
 const brokerSyncRunner = executionBroker.spawnSync.bind(executionBroker);
@@ -17,25 +25,90 @@ function normalizeInvocation(argsOrOptions, maybeOptions) {
 
 function runHookProcess(file, argsOrOptions, maybeOptions) {
   const { args, options } = normalizeInvocation(argsOrOptions, maybeOptions);
-  return _processDeps.run(file, args, {
-    ...options,
-    origin: options.origin || "hook",
+  const callerOptions = { ...options };
+  delete callerOptions.sandboxExecutionContract;
+  const processOptions = {
+    ...callerOptions,
+    origin: callerOptions.origin || "hook",
     policy: "allow",
     scope: "hook",
+  };
+  const requiresContract = requiresExplicitHookShell(
+    processOptions.sandboxPolicy,
+  );
+  const trustedRoot = requiresContract
+    ? requireTrustedHookRoot(processOptions.cwd)
+    : null;
+  const sandboxExecutionContract = requiresContract
+    ? issueTrustedHookSandboxContract({
+        issuer: executionBroker.issueLinuxWorkspaceSandboxExecutionContract,
+        receiver: executionBroker,
+        file,
+        args,
+        options: processOptions,
+        trustedRoot,
+      })
+    : null;
+  if (
+    process.platform === "linux" &&
+    requiresContract &&
+    !sandboxExecutionContract
+  ) {
+    throw sandboxBoundaryError(
+      "trusted Linux hook sandbox contract could not be issued",
+    );
+  }
+  return _processDeps.run(file, args, {
+    ...processOptions,
+    ...(sandboxExecutionContract ? { sandboxExecutionContract } : {}),
   });
 }
 
 function runHookProcessSync(file, argsOrOptions, maybeOptions) {
   const { args, options } = normalizeInvocation(argsOrOptions, maybeOptions);
-  return _processDeps.runSync(file, args, {
-    ...options,
-    origin: options.origin || "hook",
+  const callerOptions = { ...options };
+  delete callerOptions.sandboxExecutionContract;
+  const processOptions = {
+    ...callerOptions,
+    origin: callerOptions.origin || "hook",
     policy: "allow",
     scope: "hook",
+  };
+  const requiresContract = requiresExplicitHookShell(
+    processOptions.sandboxPolicy,
+  );
+  const trustedRoot = requiresContract
+    ? requireTrustedHookRoot(processOptions.cwd)
+    : null;
+  const sandboxExecutionContract = requiresContract
+    ? issueTrustedHookSandboxContract({
+        issuer: executionBroker.issueLinuxWorkspaceSandboxExecutionContract,
+        receiver: executionBroker,
+        file,
+        args,
+        options: processOptions,
+        trustedRoot,
+        sync: true,
+      })
+    : null;
+  if (
+    process.platform === "linux" &&
+    requiresContract &&
+    !sandboxExecutionContract
+  ) {
+    throw sandboxBoundaryError(
+      "trusted Linux hook sandbox contract could not be issued",
+    );
+  }
+  return _processDeps.runSync(file, args, {
+    ...processOptions,
+    ...(sandboxExecutionContract ? { sandboxExecutionContract } : {}),
   });
 }
 
 export function _restoreProcessRunners() {
+  _processDeps.run = brokerRunner;
+  _processDeps.runSync = brokerSyncRunner;
   runner._deps.run = runHookProcess;
   runner._deps.runSync = runHookProcessSync;
 }

package/src/lib/hook-shell-command.cjs

@@ -0,0 +1,148 @@
+"use strict";
+
+const path = require("node:path");
+
+const STRONG_HOOK_BOUNDARIES = new Set(["filesystem", "network"]);
+
+function requiredHookBoundaries(sandboxPolicy) {
+  const configured = sandboxPolicy?.requiredBoundaries;
+  return Array.isArray(configured) ? configured : [];
+}
+
+function requiresExplicitHookShell(sandboxPolicy) {
+  return requiredHookBoundaries(sandboxPolicy).some((boundary) =>
+    STRONG_HOOK_BOUNDARIES.has(boundary),
+  );
+}
+
+function sandboxBoundaryError(message) {
+  const error = new Error(message);
+  error.code = "ERR_PROCESS_SANDBOX_BOUNDARY_UNSATISFIED";
+  error.sandboxFailClosed = true;
+  return error;
+}
+
+function asSandboxBoundaryError(error, prefix) {
+  if (error?.code === "ERR_PROCESS_SANDBOX_BOUNDARY_UNSATISFIED") {
+    return error;
+  }
+  const detail =
+    error && typeof error.message === "string" ? error.message : String(error);
+  return sandboxBoundaryError(`${prefix}: ${detail}`);
+}
+
+function issueTrustedHookSandboxContract({
+  issuer,
+  receiver = null,
+  file,
+  args,
+  options,
+  trustedRoot,
+  sync = false,
+  label = "trusted hook sandbox contract issuance failed",
+}) {
+  if (typeof issuer !== "function") return null;
+  try {
+    return issuer.call(
+      receiver,
+      file,
+      args,
+      options,
+      trustedRoot,
+      ...(sync ? [{ sync: true }] : []),
+    );
+  } catch (error) {
+    throw asSandboxBoundaryError(error, label);
+  }
+}
+
+function requireTrustedHookRoot(value, label = "hook working directory") {
+  if (
+    typeof value !== "string" ||
+    !value ||
+    value.includes("\0") ||
+    !path.isAbsolute(value)
+  ) {
+    throw sandboxBoundaryError(
+      `${label} must be an absolute trusted path for filesystem/network sandboxing`,
+    );
+  }
+  return path.resolve(value);
+}
+
+function isPathInside(root, candidate) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return (
+    relative === "" ||
+    (relative !== ".." &&
+      !relative.startsWith(`..${path.sep}`) &&
+      !path.isAbsolute(relative))
+  );
+}
+
+function quotePosixShellArgument(value) {
+  const text = String(value);
+  if (text.length === 0) return "''";
+  return `'${text.replace(/'/g, `'"'"'`)}'`;
+}
+
+function quoteCmdArgument(value) {
+  const text = String(value);
+  if (text.length === 0) return '""';
+  // The command and its arguments are all hook-controlled, but quote cmd.exe
+  // metacharacters anyway so an argv entry remains one argument.
+  return `"${text
+    .replace(/"/g, '""')
+    .replace(/([&|<>^])/g, "^$1")
+    .replace(/%/g, "%%")}"`;
+}
+
+function appendShellArguments(command, args, platform) {
+  if (!Array.isArray(args) || args.length === 0) return command;
+  const quote =
+    platform === "win32" ? quoteCmdArgument : quotePosixShellArgument;
+  return `${command} ${args.map((arg) => quote(arg)).join(" ")}`;
+}
+
+/**
+ * Turn a settings-style shell command into an explicit executable + argv.
+ * This is used only when filesystem/network boundaries are requested. Keeping
+ * shell selection explicit lets the Broker bind its one-shot contract to the
+ * actual launch tuple and guarantees the child spawn itself uses shell:false.
+ */
+function buildExplicitHookShellInvocation(
+  command,
+  {
+    args = [],
+    platform = process.platform,
+    shellKind = null,
+    buildPowershellArgv = null,
+    powershellOptions = {},
+  } = {},
+) {
+  const rendered = appendShellArguments(String(command), args, platform);
+  if (
+    (shellKind === "powershell" || shellKind === "pwsh") &&
+    typeof buildPowershellArgv === "function"
+  ) {
+    return buildPowershellArgv(rendered, shellKind, powershellOptions);
+  }
+  if (platform === "win32") {
+    return {
+      file: process.env.ComSpec || "cmd.exe",
+      argv: ["/d", "/s", "/c", rendered],
+    };
+  }
+  return { file: "/bin/sh", argv: ["-c", rendered] };
+}
+
+module.exports = {
+  buildExplicitHookShellInvocation,
+  issueTrustedHookSandboxContract,
+  isPathInside,
+  requireTrustedHookRoot,
+  requiredHookBoundaries,
+  requiresExplicitHookShell,
+  asSandboxBoundaryError,
+  sandboxBoundaryError,
+};