chainlesschain 0.166.76 → 0.166.78

package/src/lib/process-execution-broker/linux-subreaper-helper.js

@@ -0,0 +1,344 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+import {
+  LINUX_SUBREAPER_SOURCE_DIGEST,
+  MAX_SUBREAPER_IMAGE_BYTES,
+  MAX_SUBREAPER_MANIFEST_BYTES,
+  validateLinuxSubreaperArtifact,
+  validateLinuxSubreaperElf,
+} from "./linux-subreaper-artifact.js";
+export { LINUX_SUBREAPER_SOURCE_DIGEST } from "./linux-subreaper-artifact.js";
+
+const MAX_SOURCE_BYTES = 128 * 1024;
+const MAX_IMAGE_BYTES = MAX_SUBREAPER_IMAGE_BYTES;
+const images = new Map();
+const leases = new WeakMap();
+const sha = (bytes) =>
+  "sha256:" + crypto.createHash("sha256").update(bytes).digest("hex");
+
+function failure(reason) {
+  const error = new Error(
+    `Linux process supervision helper unavailable: ${reason}`,
+  );
+  error.code = "EXTERNAL_AGENT_HELPER_UNAVAILABLE";
+  return error;
+}
+
+function readDescriptor(fd, maximum) {
+  const before = fs.fstatSync(fd, { bigint: true });
+  if (!before.isFile() || before.size < 1n || before.size > BigInt(maximum))
+    throw failure("invalid-file");
+  const bytes = Buffer.alloc(Number(before.size));
+  let offset = 0;
+  while (offset < bytes.length) {
+    const count = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+    if (count <= 0) throw failure("short-file-read");
+    offset += count;
+  }
+  const after = fs.fstatSync(fd, { bigint: true });
+  if (
+    before.dev !== after.dev ||
+    before.ino !== after.ino ||
+    before.size !== after.size ||
+    before.mtimeNs !== after.mtimeNs ||
+    before.ctimeNs !== after.ctimeNs
+  )
+    throw failure("file-changed");
+  return { bytes, stat: after };
+}
+
+function compilerPath() {
+  // Only the system toolchain is eligible. Do not consult PATH, CC, loader,
+  // include-path, or plugin-provided compiler settings.
+  const compiler = fs.realpathSync("/usr/bin/cc");
+  let current = compiler;
+  for (;;) {
+    const info = fs.lstatSync(current);
+    if (info.isSymbolicLink() || info.uid !== 0 || (info.mode & 0o022) !== 0)
+      throw failure("untrusted-system-compiler");
+    if (current === compiler && (!info.isFile() || (info.mode & 0o111) === 0))
+      throw failure("invalid-system-compiler");
+    if (current === "/") break;
+    current = path.dirname(current);
+  }
+  return compiler;
+}
+
+function packagedImage() {
+  const root = fileURLToPath(
+    new URL("../../assets/linux-subreaper/", import.meta.url),
+  );
+  // Only source checkouts with no packaged directory may use the development
+  // compiler path. A partial/corrupt installed payload must never fall back.
+  try {
+    if (!fs.lstatSync(root).isDirectory())
+      throw failure("invalid-packaged-directory");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+  let rootFd = null;
+  let dirFd = null;
+  const read = (name, maximum) => {
+    const fd = fs.openSync(
+      `/proc/self/fd/${dirFd}/${name}`,
+      fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW,
+    );
+    try {
+      const snapshot = readDescriptor(fd, maximum);
+      if (snapshot.stat.nlink !== 1n) throw failure("invalid-packaged-file");
+      return snapshot.bytes;
+    } finally {
+      fs.closeSync(fd);
+    }
+  };
+  try {
+    rootFd = fs.openSync(
+      root,
+      fs.constants.O_RDONLY |
+        fs.constants.O_DIRECTORY |
+        fs.constants.O_NOFOLLOW,
+    );
+    dirFd = fs.openSync(
+      `/proc/self/fd/${rootFd}/linux-${process.arch}`,
+      fs.constants.O_RDONLY |
+        fs.constants.O_DIRECTORY |
+        fs.constants.O_NOFOLLOW,
+    );
+    const manifest = read("manifest.json", MAX_SUBREAPER_MANIFEST_BYTES);
+    const bytes = read("supervisor", MAX_IMAGE_BYTES);
+    const identity = validateLinuxSubreaperArtifact(manifest, bytes, {
+      arch: process.arch,
+    });
+    return { bytes, identity };
+  } catch (error) {
+    if (error.code === "EXTERNAL_AGENT_HELPER_UNAVAILABLE") throw error;
+    throw failure("packaged-helper-unavailable");
+  } finally {
+    if (dirFd !== null) fs.closeSync(dirFd);
+    if (rootFd !== null) fs.closeSync(rootFd);
+  }
+}
+
+function compileImage(spawnSync) {
+  let sourceFd = null;
+  let directoryFd = null;
+  let imageFd = null;
+  let temporaryRoot = null;
+  let imagePath = null;
+  try {
+    // Vite may import the Broker through an http: module URL on non-Linux
+    // hosts. Resolve this Linux-only asset only when native supervision runs.
+    const source = fileURLToPath(
+      new URL("./linux-subreaper-supervisor.c", import.meta.url),
+    );
+    sourceFd = fs.openSync(
+      source,
+      fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW,
+    );
+    const snapshot = readDescriptor(sourceFd, MAX_SOURCE_BYTES);
+    // npm/git may transport text with CRLF. Compile the exact canonical bytes
+    // that the source digest commits to, passed on stdin rather than reopened.
+    const sourceBytes = Buffer.from(
+      snapshot.bytes.toString("utf8").replace(/\r\n/g, "\n"),
+    );
+    if (
+      snapshot.stat.nlink !== 1n ||
+      sha(sourceBytes) !== LINUX_SUBREAPER_SOURCE_DIGEST
+    )
+      throw failure("source-digest-mismatch");
+    fs.closeSync(sourceFd);
+    sourceFd = null;
+    const packaged = packagedImage();
+    const compiler = packaged ? null : compilerPath();
+    temporaryRoot = fs.mkdtempSync(
+      path.join(os.tmpdir(), "cc-linux-subreaper-build-"),
+    );
+    fs.chmodSync(temporaryRoot, 0o700);
+    directoryFd = fs.openSync(
+      temporaryRoot,
+      fs.constants.O_RDONLY |
+        fs.constants.O_DIRECTORY |
+        fs.constants.O_NOFOLLOW,
+    );
+    const directory = fs.fstatSync(directoryFd);
+    if (
+      !directory.isDirectory() ||
+      directory.uid !== process.getuid() ||
+      (directory.mode & 0o777) !== 0o700
+    )
+      throw failure("untrusted-build-directory");
+    imagePath = path.join(temporaryRoot, "supervisor");
+    // The compiler writes through its inherited directory handle. An ancestor
+    // rename cannot redirect the build to a caller-supplied executable path.
+    if (packaged) {
+      fs.writeFileSync(
+        `/proc/self/fd/${directoryFd}/supervisor`,
+        packaged.bytes,
+        { flag: "wx", mode: 0o500 },
+      );
+    } else {
+      const built = spawnSync(
+        compiler,
+        [
+          "-std=c11",
+          "-Wall",
+          "-Wextra",
+          "-Werror",
+          "-O2",
+          "-fstack-protector-strong",
+          "-D_FORTIFY_SOURCE=2",
+          "-x",
+          "c",
+          "-",
+          "-o",
+          "/proc/self/fd/3/supervisor",
+        ],
+        {
+          cwd: temporaryRoot,
+          env: { PATH: "/usr/bin:/bin", LC_ALL: "C" },
+          shell: false,
+          input: sourceBytes,
+          timeout: 30000,
+          maxBuffer: 1024 * 1024,
+          stdio: ["pipe", "pipe", "pipe", directoryFd],
+        },
+      );
+      if (built.error || built.status !== 0 || built.signal)
+        throw failure("native-build-failed");
+    }
+    imageFd = fs.openSync(
+      `/proc/self/fd/${directoryFd}/supervisor`,
+      fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW,
+    );
+    fs.fchmodSync(imageFd, 0o500);
+    const image = readDescriptor(imageFd, MAX_IMAGE_BYTES);
+    if (
+      image.stat.uid !== BigInt(process.getuid()) ||
+      image.stat.nlink !== 1n ||
+      (image.stat.mode & 0o777n) !== 0o500n
+    )
+      throw failure("untrusted-helper-image");
+    validateLinuxSubreaperElf(image.bytes, {
+      arch: process.arch,
+      staticOnly: Boolean(packaged),
+    });
+    if (packaged && sha(image.bytes) !== packaged.identity.imageDigest)
+      throw failure("packaged-copy-changed");
+    // Remove the name before granting a launch lease. The executable can only
+    // be reached through the held descriptor; a later pathname swap is inert.
+    fs.unlinkSync(`/proc/self/fd/${directoryFd}/supervisor`);
+    imagePath = null;
+    const held = fs.fstatSync(imageFd, { bigint: true });
+    if (
+      held.nlink !== 0n ||
+      held.dev !== image.stat.dev ||
+      held.ino !== image.stat.ino
+    )
+      throw failure("helper-unlink-unconfirmed");
+    const entry = {
+      fd: imageFd,
+      dev: held.dev,
+      ino: held.ino,
+      digest: sha(image.bytes),
+      distribution: packaged ? "packaged-static" : "local-build",
+    };
+    imageFd = null;
+    return entry;
+  } catch (error) {
+    if (error.code === "EXTERNAL_AGENT_HELPER_UNAVAILABLE") throw error;
+    // Do not expose compiler stdout/stderr, paths, environment, or native argv.
+    throw failure(
+      error.code === "ENOENT"
+        ? "system-compiler-or-source-missing"
+        : "native-build-setup-failed",
+    );
+  } finally {
+    if (sourceFd !== null) fs.closeSync(sourceFd);
+    if (imageFd !== null) fs.closeSync(imageFd);
+    if (imagePath && directoryFd !== null) {
+      try {
+        fs.unlinkSync(`/proc/self/fd/${directoryFd}/supervisor`);
+      } catch {
+        /* Preserve the admission failure. */
+      }
+    }
+    if (directoryFd !== null) fs.closeSync(directoryFd);
+    if (temporaryRoot) {
+      try {
+        fs.rmdirSync(temporaryRoot);
+      } catch {
+        /* Never recursively remove an unexpected build entry. */
+      }
+    }
+  }
+}
+
+/** Acquire a one-use descriptor lease from trusted packaged source. */
+export function acquireLinuxSubreaperHelper({ spawnSync }) {
+  if (process.platform !== "linux" || typeof spawnSync !== "function")
+    throw failure("unsupported-host");
+  let entry = images.get(spawnSync);
+  if (!entry) {
+    entry = compileImage(spawnSync);
+    images.set(spawnSync, entry);
+    // Outstanding leases hold their own duplicated descriptor. Bound cached
+    // native-seam variants without invalidating already-started children.
+    if (images.size > 4) {
+      const oldest = images.keys().next().value;
+      fs.closeSync(images.get(oldest).fd);
+      images.delete(oldest);
+    }
+  }
+  const held = readDescriptor(entry.fd, MAX_IMAGE_BYTES);
+  if (
+    held.stat.dev !== entry.dev ||
+    held.stat.ino !== entry.ino ||
+    held.stat.nlink !== 0n ||
+    sha(held.bytes) !== entry.digest
+  )
+    throw failure("cached-helper-changed");
+  const descriptor = fs.openSync(
+    `/proc/self/fd/${entry.fd}`,
+    fs.constants.O_RDONLY,
+  );
+  try {
+    const borrowed = fs.fstatSync(descriptor, { bigint: true });
+    if (
+      borrowed.dev !== entry.dev ||
+      borrowed.ino !== entry.ino ||
+      borrowed.nlink !== 0n
+    )
+      throw failure("helper-lease-changed");
+  } catch (error) {
+    fs.closeSync(descriptor);
+    throw error;
+  }
+  const lease = Object.freeze({ kind: "linux-subreaper-helper-lease/v1" });
+  leases.set(lease, {
+    descriptor,
+    sourceDigest: LINUX_SUBREAPER_SOURCE_DIGEST,
+    imageDigest: entry.digest,
+    distribution: entry.distribution,
+  });
+  return lease;
+}
+
+export function consumeLinuxSubreaperHelper(lease) {
+  const entry = leases.get(lease);
+  if (!entry) throw failure("invalid-or-consumed-helper-lease");
+  leases.delete(lease);
+  let released = false;
+  return Object.freeze({
+    ...entry,
+    release() {
+      if (!released) {
+        released = true;
+        fs.closeSync(entry.descriptor);
+      }
+    },
+  });
+}

package/src/lib/process-execution-broker/linux-subreaper-process.js

@@ -0,0 +1,326 @@
+import { isAbsolute } from "node:path";
+import { EventEmitter } from "node:events";
+import { constants } from "node:os";
+import { consumeLinuxSubreaperHelper } from "./linux-subreaper-helper.js";
+
+const MAGIC = Buffer.from("CCSUBR01");
+const MAX_FRAME = 1024 * 1024;
+
+export function encodeLinuxSubreaperLaunch(command, args, options) {
+  if (
+    typeof command !== "string" ||
+    !command ||
+    command.includes("\0") ||
+    !Array.isArray(args) ||
+    args.length >= 4096 ||
+    args.some((arg) => typeof arg !== "string" || arg.includes("\0")) ||
+    typeof options.cwd !== "string" ||
+    !isAbsolute(options.cwd) ||
+    options.cwd.includes("\0") ||
+    !options.env ||
+    typeof options.env !== "object" ||
+    Array.isArray(options.env)
+  )
+    throw new TypeError("Invalid Linux subreaper launch");
+  const entries = Object.entries(options.env);
+  if (
+    entries.length > 8192 ||
+    entries.some(
+      ([key, value]) =>
+        !key ||
+        key.includes("=") ||
+        key.includes("\0") ||
+        typeof value !== "string" ||
+        value.includes("\0"),
+    )
+  ) {
+    throw new TypeError("Invalid Linux subreaper environment");
+  }
+  const graceMs = options.graceMs ?? 250;
+  if (!Number.isSafeInteger(graceMs) || graceMs < 0 || graceMs > 2147483647)
+    throw new TypeError("Invalid Linux subreaper grace period");
+  const strings = [
+    options.cwd,
+    command,
+    ...args,
+    ...entries.map(([key, value]) => `${key}=${value}`),
+  ].map((value) => Buffer.from(value, "utf8"));
+  const length = 24 + strings.reduce((sum, value) => sum + 4 + value.length, 0);
+  if (length > MAX_FRAME)
+    throw new TypeError("Linux subreaper launch exceeds its byte limit");
+  const frame = Buffer.alloc(length);
+  MAGIC.copy(frame);
+  frame.writeUInt32BE(length, 8);
+  frame.writeUInt32BE(args.length + 1, 12);
+  frame.writeUInt32BE(entries.length, 16);
+  frame.writeUInt32BE(graceMs, 20);
+  let offset = 24;
+  for (const value of strings) {
+    frame.writeUInt32BE(value.length, offset);
+    offset += 4;
+    value.copy(frame, offset);
+    offset += value.length;
+  }
+  return frame;
+}
+
+/**
+ * Native lifecycle primitive for an admitted Broker launch plan. Production
+ * uses a one-use, privately branded helper descriptor. The explicit path seam
+ * remains for native build/verification tests, never Broker request options.
+ */
+export function spawnLinuxSubreaper(command, args, options, native) {
+  // Claim the lease before validating the launch so every rejection closes its
+  // descriptor. A bad plan must not strand an otherwise valid installation pin.
+  const helper = options.helper
+    ? consumeLinuxSubreaperHelper(options.helper)
+    : null;
+  let launch;
+  let child;
+  try {
+    if (
+      (native.platform ?? process.platform) !== "linux" ||
+      typeof native.spawn !== "function"
+    )
+      throw new TypeError("Linux Broker native spawn is required");
+    if (
+      !options.helper &&
+      (typeof options.helperPath !== "string" ||
+        !isAbsolute(options.helperPath))
+    )
+      throw new TypeError(
+        "An absolute Linux subreaper helper path is required",
+      );
+    if (options.helper && options.helperPath)
+      throw new TypeError("Ambiguous Linux subreaper helper identity");
+    if (
+      Object.keys(options).some(
+        (key) =>
+          !["cwd", "env", "graceMs", "helperPath", "helper"].includes(key),
+      )
+    )
+      throw new TypeError("Unsupported Linux subreaper option");
+    launch = encodeLinuxSubreaperLaunch(command, args, options);
+    child = native.spawn(helper ? "/proc/self/fd/4" : options.helperPath, [], {
+      cwd: options.cwd,
+      env: { PATH: "/usr/bin:/bin", LC_ALL: "C" },
+      shell: false,
+      detached: false,
+      stdio: [
+        "pipe",
+        "pipe",
+        "pipe",
+        "pipe",
+        ...(helper ? [helper.descriptor] : []),
+      ],
+    });
+  } finally {
+    // Native spawn duplicates stdio synchronously. Never reopen the verified
+    // executable path; the child's descriptor now owns that exact image.
+    helper?.release();
+  }
+  const control = child.stdio[3];
+  let closed = false;
+  let requestedSignal = null;
+  let buffer = "";
+  let bytes = 0;
+  let targetPid = null;
+  let target = null;
+  let cleanup = null;
+  let protocolError = null;
+  const terminate = (signal = "SIGTERM") => {
+    if (!["SIGTERM", "SIGKILL"].includes(signal))
+      throw new TypeError("Invalid Linux subreaper stop signal");
+    if (closed || control.destroyed || !control.writable) return false;
+    if (requestedSignal === "SIGKILL" || requestedSignal === signal)
+      return true;
+    requestedSignal = signal;
+    control.write(signal === "SIGKILL" ? "K" : "T");
+    return true;
+  };
+  control.on("error", () => {
+    protocolError ??= "control-channel-failed";
+    control.destroy();
+  });
+  control.on("data", (chunk) => {
+    bytes += chunk.length;
+    if (bytes > 16 * 1024) {
+      protocolError = "control-reply-limit";
+      control.destroy();
+      return;
+    }
+    buffer += chunk.toString("ascii");
+    let newline;
+    while ((newline = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, newline);
+      buffer = buffer.slice(newline + 1);
+      try {
+        const message = JSON.parse(line);
+        if (
+          message.type === "started" &&
+          targetPid === null &&
+          Number.isSafeInteger(message.pid) &&
+          message.pid > 0
+        ) {
+          targetPid = message.pid;
+        } else if (
+          message.type === "target-exit" &&
+          target === null &&
+          targetPid !== null &&
+          Number.isInteger(message.code) &&
+          message.code >= -1 &&
+          message.code <= 255 &&
+          Number.isInteger(message.signal) &&
+          message.signal >= 0 &&
+          message.signal <= 64 &&
+          Number.isInteger(message.spawnErrno) &&
+          message.spawnErrno >= -1 &&
+          message.spawnErrno <= 4095
+        ) {
+          target = {
+            code: message.code,
+            signal: message.signal,
+            spawnErrno: message.spawnErrno,
+          };
+        } else if (
+          message.type === "cleanup" &&
+          cleanup === null &&
+          target !== null &&
+          typeof message.confirmed === "boolean" &&
+          message.rootReaped === true &&
+          Number.isSafeInteger(message.reaped) &&
+          message.reaped >= 1
+        ) {
+          cleanup = message;
+        } else if (
+          message.type === "error" &&
+          ["subreaper-unavailable", "cleanup-unconfirmed"].includes(
+            message.code,
+          )
+        ) {
+          protocolError ??= message.code;
+        } else throw new Error("invalid reply");
+      } catch {
+        protocolError = "invalid-control-reply";
+        control.destroy();
+        return;
+      }
+    }
+  });
+  const completion = new Promise((resolve) => {
+    child.on("error", () => {
+      protocolError ??= "supervisor-spawn-failed";
+    });
+    child.once("close", (code, signal) => {
+      closed = true;
+      control.destroy();
+      if (buffer) protocolError ??= "truncated-control-reply";
+      if (!cleanup) protocolError ??= "missing-cleanup-receipt";
+      else if (!cleanup.confirmed)
+        protocolError ??= "unconfirmed-cleanup-receipt";
+      const confirmed =
+        cleanup?.confirmed === true &&
+        code === 0 &&
+        signal === null &&
+        !protocolError;
+      resolve({
+        targetPid,
+        target,
+        supervisor: { code, signal, closed: true },
+        cleanup: {
+          mode: "linux-subreaper",
+          confirmed,
+          descendantsReaped: confirmed,
+          reaped: cleanup?.reaped ?? null,
+          protocolError,
+          // The zero-child fence is a lifecycle fact, not hostile-code isolation.
+          processTreeContained: false,
+        },
+        ...(helper
+          ? {
+              helper: {
+                sourceDigest: helper.sourceDigest,
+                imageDigest: helper.imageDigest,
+                binding: "unlinked-inherited-fd",
+                distribution: helper.distribution,
+              },
+            }
+          : {}),
+      });
+    });
+  });
+  control.write(launch);
+  return Object.freeze({ child, terminate, completion });
+}
+
+/** Broker-facing process handle: close is fenced by the kernel tree receipt. */
+export function spawnLinuxSubreaperChild(command, args, options, native) {
+  const owner = spawnLinuxSubreaper(command, args, options, native);
+  const raw = owner.child;
+  const child = new EventEmitter();
+  Object.assign(child, {
+    pid: raw.pid,
+    sandboxWrapperPid: raw.pid,
+    stdin: raw.stdin,
+    stdout: raw.stdout,
+    stderr: raw.stderr,
+    stdio: raw.stdio,
+    exitCode: null,
+    signalCode: null,
+    killed: false,
+    ownedProcessTreeClosed: owner.completion,
+    kill(signal = "SIGTERM") {
+      const requested = owner.terminate(signal);
+      if (requested) child.killed = true;
+      return requested;
+    },
+    ref() {
+      raw.ref?.();
+      return child;
+    },
+    unref() {
+      raw.unref?.();
+      return child;
+    },
+  });
+  raw.once("spawn", () => child.emit("spawn"));
+  owner.completion.then((receipt) => {
+    child.ownedProcessTreeEvidence = receipt;
+    child.sandboxTargetPid = receipt.targetPid;
+    if (!receipt.cleanup.confirmed) {
+      const error = new Error(
+        "Linux external-agent process-tree cleanup is unconfirmed",
+      );
+      error.code = raw.pid
+        ? "EXTERNAL_AGENT_CLEANUP_UNCONFIRMED"
+        : "EXTERNAL_AGENT_SPAWN_FAILED";
+      // A failed native spawn never created an owner or target. All other
+      // losses retain the close fence: helper exit alone cannot release an
+      // agent while an unobserved adopted descendant may still be executing.
+      child.emit("error", error);
+      if (!raw.pid) {
+        child.exitCode = -1;
+        child.emit("exit", -1, null);
+        child.emit("close", -1, null);
+      } else {
+        child.emit("cleanup:unconfirmed", receipt);
+      }
+      return;
+    }
+    if (receipt.target.spawnErrno) {
+      const error = new Error("External agent executable could not be started");
+      error.code = "EXTERNAL_AGENT_SPAWN_FAILED";
+      child.emit("error", error);
+    }
+    child.exitCode = receipt.target.code < 0 ? null : receipt.target.code;
+    child.signalCode =
+      receipt.target.signal === 0
+        ? null
+        : (Object.keys(constants.signals).find(
+            (signal) => constants.signals[signal] === receipt.target.signal,
+          ) ?? "SIGUNKNOWN");
+    child.emit("exit", child.exitCode, child.signalCode);
+    child.emit("close", child.exitCode, child.signalCode);
+  });
+  return child;
+}