chainlesschain 0.166.76 → 0.166.78

package/src/lib/process-execution-broker/owned-posix-process-group.js

@@ -0,0 +1,267 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const WORKER = fileURLToPath(
+  new URL("./owned-posix-process-group-worker.mjs", import.meta.url),
+);
+const MAX_REQUEST_BYTES = 1024 * 1024;
+const MAX_REPLY_BYTES = 16 * 1024;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function milliseconds(value, fallback, maximum) {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+    throw new TypeError("Invalid owned process group deadline");
+  }
+  return value;
+}
+
+/** Read-only observation. Never use this numeric identity to send a signal. */
+export function inspectPosixProcessGroup(pgid, { platform, spawnSync }) {
+  if (!Number.isSafeInteger(pgid) || pgid < 1) return null;
+  try {
+    if (platform === "linux") {
+      const states = [];
+      for (const entry of readdirSync("/proc")) {
+        if (!/^\d+$/.test(entry)) continue;
+        let raw;
+        try {
+          raw = readFileSync(`/proc/${entry}/stat`, "utf8");
+        } catch (error) {
+          if (error.code === "ENOENT" || error.code === "ESRCH") continue;
+          return null;
+        }
+        // comm may itself contain spaces or parentheses.
+        const fields = raw
+          .slice(raw.lastIndexOf(")") + 2)
+          .trim()
+          .split(/\s+/);
+        if (fields.length < 4 || !/^[A-Zt]$/.test(fields[0])) return null;
+        if (Number(fields[2]) === pgid) states.push(fields[0]);
+      }
+      return states;
+    }
+    if (platform === "darwin") {
+      const result = spawnSync("/bin/ps", ["-axo", "pgid=,stat="], {
+        encoding: "utf8",
+        shell: false,
+        timeout: 2000,
+        maxBuffer: 4 * 1024 * 1024,
+        env: { PATH: "/usr/bin:/bin", LC_ALL: "C" },
+      });
+      if (result.error || result.status !== 0 || !result.stdout?.trim()) {
+        return null;
+      }
+      const states = [];
+      for (const line of result.stdout.trim().split("\n")) {
+        const match = /^\s*(\d+)\s+([A-Z?][A-Za-z+<>sNXEVL-]*)\s*$/.exec(line);
+        if (!match) return null;
+        if (Number(match[1]) === pgid) states.push(match[2][0]);
+      }
+      return states;
+    }
+  } catch {
+    // Missing visibility is not proof of group exit.
+  }
+  return null;
+}
+
+/**
+ * Low-level lifecycle primitive for an already admitted Broker launch plan.
+ * Callers supply the Broker's native seams; this module grants no execution
+ * permission and does not add a sandbox guarantee. Production wiring is kept
+ * separate so policy/credential/descriptor plans cannot silently be bypassed.
+ *
+ * The detached worker remains the group leader after the target exits. Only
+ * that living worker sends TERM/KILL to its own group. The caller sends control
+ * messages over a private inherited socket, never a delayed numeric signal.
+ * A POSIX group is escapable with setsid; confirmation covers group members,
+ * not arbitrary descendants or containment against a hostile executable.
+ */
+export function spawnOwnedPosixProcessGroup(command, args, options, native) {
+  const platform = native.platform ?? process.platform;
+  if (!["linux", "darwin"].includes(platform)) {
+    throw new TypeError("Owned POSIX process groups require Linux or macOS");
+  }
+  if (
+    typeof native.spawn !== "function" ||
+    typeof native.spawnSync !== "function"
+  ) {
+    throw new TypeError("Broker native process seams are required");
+  }
+  const allowed = new Set(["cwd", "env", "graceMs", "confirmMs"]);
+  if (Object.keys(options).some((key) => !allowed.has(key))) {
+    throw new TypeError("Unsupported owned process group option");
+  }
+  if (
+    typeof command !== "string" ||
+    !command ||
+    command.includes("\0") ||
+    !Array.isArray(args) ||
+    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) ||
+    Object.entries(options.env).some(
+      ([key, value]) =>
+        !key ||
+        key.includes("=") ||
+        key.includes("\0") ||
+        typeof value !== "string" ||
+        value.includes("\0"),
+    )
+  ) {
+    throw new TypeError("Invalid owned process group invocation");
+  }
+  const graceMs = milliseconds(options.graceMs, 250, 5000);
+  const confirmMs = milliseconds(options.confirmMs, 2000, 10000);
+  const request =
+    JSON.stringify({
+      type: "launch",
+      command,
+      args,
+      cwd: options.cwd,
+      env: options.env,
+      graceMs,
+    }) + "\n";
+  if (Buffer.byteLength(request) > MAX_REQUEST_BYTES) {
+    throw new TypeError("Owned process group launch exceeds its byte limit");
+  }
+  const child = native.spawn(process.execPath, [WORKER], {
+    cwd: options.cwd,
+    // The target receives the admitted environment over the control socket.
+    // NODE_OPTIONS/loader injection must not run in the unsandboxed supervisor.
+    env: { PATH: "/usr/bin:/bin", LC_ALL: "C" },
+    shell: false,
+    detached: true,
+    stdio: ["pipe", "pipe", "pipe", "pipe"],
+  });
+  const control = child.stdio[3];
+  let supervisorClosed = false;
+  let target = null;
+  let targetPid = null;
+  let terminating = false;
+  let protocolError = null;
+  let reply = "";
+  let replyBytes = 0;
+  let requestedSignal = null;
+  const terminate = (signal = "SIGTERM") => {
+    if (!["SIGTERM", "SIGKILL"].includes(signal)) {
+      throw new TypeError("Unsupported owned process group signal");
+    }
+    if (supervisorClosed || control.destroyed || !control.writable)
+      return false;
+    if (requestedSignal === "SIGKILL" || requestedSignal === signal)
+      return true;
+    requestedSignal = signal;
+    control.write(JSON.stringify({ type: "stop", signal }) + "\n");
+    return true;
+  };
+  control.on("error", () => {
+    protocolError ??= "control-channel-failed";
+    // Closing the lifeline asks the living worker to clean its own group.
+    control.destroy();
+  });
+  control.on("data", (chunk) => {
+    replyBytes += chunk.length;
+    if (replyBytes > MAX_REPLY_BYTES) {
+      protocolError = "control-reply-limit";
+      control.destroy();
+      return;
+    }
+    reply += chunk.toString("utf8");
+    let newline;
+    while ((newline = reply.indexOf("\n")) >= 0) {
+      const line = reply.slice(0, newline);
+      reply = reply.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 &&
+          (message.code === null || Number.isInteger(message.code)) &&
+          (message.signal === null || typeof message.signal === "string")
+        ) {
+          target = {
+            code: message.code,
+            signal: message.signal,
+            spawnError: message.spawnError ?? null,
+          };
+        } else if (message.type === "terminating" && !terminating) {
+          terminating = true;
+        } else {
+          throw new Error("invalid reply");
+        }
+      } catch {
+        protocolError = "invalid-control-reply";
+        control.destroy();
+        return;
+      }
+    }
+  });
+  const completion = new Promise((resolveCompletion) => {
+    child.on("error", () => {
+      protocolError ??= "supervisor-spawn-failed";
+    });
+    child.once("close", async (code, signal) => {
+      supervisorClosed = true;
+      if (reply.length > 0) protocolError ??= "truncated-control-reply";
+      control.destroy();
+      const inspect =
+        native.inspectGroup ??
+        ((pid) =>
+          inspectPosixProcessGroup(pid, {
+            platform,
+            spawnSync: native.spawnSync,
+          }));
+      const deadline = performance.now() + confirmMs;
+      let states = null;
+      do {
+        try {
+          states = inspect(child.pid);
+        } catch {
+          states = null;
+        }
+        if (
+          Array.isArray(states) &&
+          states.every((state) => state === "Z" || state === "X")
+        )
+          break;
+        await delay(25);
+      } while (performance.now() < deadline);
+      const groupStopped =
+        Array.isArray(states) &&
+        states.every((state) => state === "Z" || state === "X");
+      resolveCompletion({
+        targetPid,
+        target,
+        supervisor: { code, signal, closed: true },
+        cleanup: {
+          mode: "posix-process-group",
+          confirmed:
+            groupStopped &&
+            terminating &&
+            !protocolError &&
+            signal === "SIGKILL",
+          groupStopped,
+          states,
+          protocolError,
+          processTreeContained: false,
+        },
+      });
+    });
+  });
+  control.write(request);
+  return Object.freeze({ child, terminate, completion });
+}

package/src/lib/process-execution-broker/process-ownership-journal.js

@@ -0,0 +1,297 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { withFileLock } from "../with-file-lock.js";
+import { writeSecurityStore } from "../durable-security-store.js";
+import { ensurePrivateDirectory } from "../secure-fs.js";
+
+export const PROCESS_OWNERSHIP_PENDING = "BROKER_PROCESS_OWNERSHIP_PENDING";
+export const PROCESS_OWNERSHIP_JOURNAL_UNAVAILABLE =
+  "BROKER_PROCESS_OWNERSHIP_JOURNAL_UNAVAILABLE";
+const SCHEMA = "chainlesschain.process-ownership-journal/v1";
+const MAX_BYTES = 1024 * 1024;
+const MAX_PENDING = 1024;
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+
+function unavailable(cause) {
+  const error = new Error(
+    "Process ownership journal is unavailable; execution is denied",
+    { cause },
+  );
+  error.code = PROCESS_OWNERSHIP_JOURNAL_UNAVAILABLE;
+  error.executionStarted = false;
+  error.recoveryRequired = true;
+  return error;
+}
+
+function validate(state) {
+  if (
+    !state ||
+    Object.keys(state).sort().join() !== "pending,schema" ||
+    state.schema !== SCHEMA ||
+    !Array.isArray(state.pending) ||
+    state.pending.length > MAX_PENDING
+  )
+    throw new Error("Invalid ownership journal schema");
+  const ids = new Set();
+  for (const entry of state.pending) {
+    if (
+      !entry ||
+      Object.keys(entry).sort().join() !== "executionId,ownerPid,token" ||
+      !UUID.test(entry.executionId) ||
+      !UUID.test(entry.token) ||
+      !Number.isSafeInteger(entry.ownerPid) ||
+      entry.ownerPid < 1 ||
+      ids.has(entry.executionId)
+    )
+      throw new Error("Invalid ownership journal entry");
+    ids.add(entry.executionId);
+  }
+  return state;
+}
+
+function privateEntry(entry, directory) {
+  return (
+    (directory ? entry.isDirectory() : entry.isFile() && entry.nlink === 1) &&
+    entry.uid === process.getuid() &&
+    (entry.mode & 0o077) === 0
+  );
+}
+
+/**
+ * Linux cooperative restart fence. Uses the existing strict file lock and
+ * atomic security-store writer; this is not a workspace lock or a sandbox.
+ * Peers must wait for outstanding supervised launches to close. PID liveness,
+ * age, owner death and reboot are never authorities to erase a pending launch.
+ */
+export class ProcessOwnershipJournal {
+  #directory;
+  #local = new Map();
+  #fault = null;
+  #initialized = false;
+
+  constructor(directory) {
+    if (process.platform !== "linux" || !path.isAbsolute(directory))
+      throw new TypeError(
+        "Linux ownership journal requires an absolute directory",
+      );
+    this.#directory = path.resolve(directory);
+  }
+
+  #withDirectory(create, operation) {
+    let descriptor;
+    try {
+      let before;
+      try {
+        before = fs.lstatSync(this.#directory);
+      } catch (error) {
+        if (error.code !== "ENOENT" || this.#initialized) throw error;
+        if (!create) return operation(null);
+        ensurePrivateDirectory(this.#directory, { failIfUnavailable: true });
+        // Publish the new authority directory before admitting its first launch.
+        const parent = fs.openSync(
+          path.dirname(this.#directory),
+          fs.constants.O_RDONLY | fs.constants.O_DIRECTORY,
+        );
+        try {
+          fs.fsyncSync(parent);
+        } finally {
+          fs.closeSync(parent);
+        }
+        before = fs.lstatSync(this.#directory);
+      }
+      if (!privateEntry(before, true))
+        throw new Error("Unsafe ownership directory");
+      if (fs.realpathSync(this.#directory) !== this.#directory)
+        throw new Error("Ownership directory contains a link");
+      descriptor = fs.openSync(
+        this.#directory,
+        fs.constants.O_RDONLY |
+          fs.constants.O_DIRECTORY |
+          fs.constants.O_NOFOLLOW,
+      );
+      const opened = fs.fstatSync(descriptor);
+      if (
+        before.dev !== opened.dev ||
+        before.ino !== opened.ino ||
+        !privateEntry(opened, true)
+      )
+        throw new Error("Ownership directory changed");
+      const result = operation(`/proc/self/fd/${descriptor}/journal.json`);
+      const after = fs.lstatSync(this.#directory);
+      if (
+        after.dev !== opened.dev ||
+        after.ino !== opened.ino ||
+        !privateEntry(after, true)
+      )
+        throw new Error("Ownership directory replaced");
+      return result;
+    } catch (error) {
+      if (error.code === PROCESS_OWNERSHIP_PENDING) throw error;
+      this.#fault = unavailable(error);
+      throw this.#fault;
+    } finally {
+      if (descriptor !== undefined) fs.closeSync(descriptor);
+    }
+  }
+
+  #read(file) {
+    if (file === null) return { schema: SCHEMA, pending: [] };
+    let descriptor;
+    try {
+      try {
+        descriptor = fs.openSync(
+          file,
+          fs.constants.O_RDONLY |
+            fs.constants.O_NOFOLLOW |
+            fs.constants.O_NONBLOCK,
+        );
+      } catch (error) {
+        if (error.code === "ENOENT" && !this.#initialized)
+          return { schema: SCHEMA, pending: [] };
+        throw error;
+      }
+      const before = fs.fstatSync(descriptor);
+      if (!privateEntry(before, false) || before.size > MAX_BYTES)
+        throw new Error("Unsafe ownership journal");
+      const bytes = Buffer.alloc(before.size + 1);
+      let length = 0;
+      while (length < bytes.length) {
+        const count = fs.readSync(
+          descriptor,
+          bytes,
+          length,
+          bytes.length - length,
+          null,
+        );
+        if (count === 0) break;
+        length += count;
+      }
+      const after = fs.fstatSync(descriptor);
+      if (
+        length !== before.size ||
+        before.size !== after.size ||
+        before.mtimeMs !== after.mtimeMs ||
+        before.ctimeMs !== after.ctimeMs
+      )
+        throw new Error("Ownership journal changed during read");
+      const state = validate(
+        JSON.parse(bytes.subarray(0, length).toString("utf8")),
+      );
+      this.#initialized = true;
+      return state;
+    } finally {
+      if (descriptor !== undefined) fs.closeSync(descriptor);
+    }
+  }
+
+  #assertState(state) {
+    const blocked = state.pending.filter(
+      (entry) => this.#local.get(entry.executionId)?.token !== entry.token,
+    );
+    if (blocked.length) {
+      const error = new Error(
+        "Process ownership is pending in another runtime; confirmed cleanup is required before execution",
+      );
+      error.code = PROCESS_OWNERSHIP_PENDING;
+      error.executionStarted = false;
+      error.recoveryRequired = true;
+      throw error;
+    }
+    // Removal/replacement of our admitted record must not make this process
+    // forget a live launch. Cross-restart deletion of the whole anchor is
+    // outside this cooperative same-user persistence boundary.
+    for (const [id, local] of this.#local) {
+      if (
+        !state.pending.some(
+          (entry) => entry.executionId === id && entry.token === local.token,
+        )
+      )
+        throw new Error("Admitted ownership record disappeared");
+    }
+  }
+
+  assertAvailable() {
+    if (this.#fault) throw this.#fault;
+    this.#withDirectory(false, (file) => this.#assertState(this.#read(file)));
+  }
+
+  inspect() {
+    if (this.#fault) throw this.#fault;
+    return this.#withDirectory(false, (file) => {
+      const state = this.#read(file);
+      return {
+        pendingExecutionIds: state.pending.map((entry) => entry.executionId),
+        blocked: state.pending.some(
+          (entry) => this.#local.get(entry.executionId)?.token !== entry.token,
+        ),
+      };
+    });
+  }
+
+  prepare(executionId) {
+    if (!UUID.test(executionId))
+      throw new TypeError("Invalid ownership execution id");
+    if (this.#fault) throw this.#fault;
+    const entry = { executionId, ownerPid: process.pid, token: randomUUID() };
+    this.#withDirectory(true, (file) =>
+      withFileLock(
+        file,
+        () => {
+          const state = this.#read(file);
+          this.#assertState(state);
+          if (
+            state.pending.length >= MAX_PENDING ||
+            state.pending.some((item) => item.executionId === executionId)
+          )
+            throw new Error("Ownership journal admission limit");
+          state.pending.push(entry);
+          writeSecurityStore(file, "Process ownership", state);
+          this.#initialized = true;
+          this.#local.set(executionId, entry);
+        },
+        { failIfUnavailable: true, timeoutMs: 2000 },
+      ),
+    );
+    let settled = false;
+    let retained = false;
+    return Object.freeze({
+      retain: () => {
+        retained = true;
+        this.#local.delete(executionId);
+      },
+      // Broker calls this only before entering native spawn or after its
+      // authentic child close fence. No public reset/reclaim-by-PID endpoint.
+      settle: () => {
+        if (settled) return;
+        if (retained)
+          throw unavailable(
+            new Error("Retained ownership cannot be settled without recovery"),
+          );
+        this.#withDirectory(false, (file) =>
+          withFileLock(
+            file,
+            () => {
+              const state = this.#read(file);
+              if (
+                !state.pending.some(
+                  (item) =>
+                    item.executionId === executionId &&
+                    item.token === entry.token,
+                )
+              )
+                throw new Error("Ownership settlement lost its record");
+              state.pending = state.pending.filter(
+                (item) => item.executionId !== executionId,
+              );
+              writeSecurityStore(file, "Process ownership", state);
+              this.#local.delete(executionId);
+              settled = true;
+            },
+            { failIfUnavailable: true, timeoutMs: 2000 },
+          ),
+        );
+      },
+    });
+  }
+}

package/src/lib/process-execution-broker/process-ownership-quarantine.js

@@ -0,0 +1,91 @@
+import path from "node:path";
+import { getMachineSecurityAnchorDir } from "../paths.js";
+import { ProcessOwnershipJournal } from "./process-ownership-journal.js";
+
+// Shared by every Broker in this JS runtime. A new Broker, different cwd or
+// cleared audit history cannot turn a lost process owner into cleanup evidence.
+// Linux additionally records ownership before the native launch. Retaining
+// that record across restart is a fence, not proof of descendant cleanup.
+const unresolvedOwners = new Map();
+let journal = null;
+
+function durableJournal() {
+  if (process.platform !== "linux") return null;
+  journal ??= new ProcessOwnershipJournal(
+    path.join(getMachineSecurityAnchorDir(), "process-ownership-v1"),
+  );
+  return journal;
+}
+
+export function prepareProcessOwnership(executionId) {
+  return durableJournal()?.prepare(executionId) ?? null;
+}
+
+export const PROCESS_OWNERSHIP_UNCONFIRMED =
+  "BROKER_PROCESS_OWNERSHIP_UNCONFIRMED";
+
+export function observeProcessOwnership(proc, executionId, lease = null) {
+  // The facade emits close only after actual tree cleanup, or after a native
+  // spawn that created no supervisor at all. Persist that fact before Bridge
+  // callers receive close. An error/exit/PID probe cannot settle this record.
+  if (lease)
+    proc.prependOnceListener("close", () => {
+      if (
+        proc.pid &&
+        proc.ownedProcessTreeEvidence?.cleanup?.confirmed !== true
+      )
+        return;
+      try {
+        lease.settle();
+      } catch (error) {
+        proc.emit("error", error);
+      }
+    });
+  if (!proc?.ownedProcessTreeClosed || !proc.pid) return;
+  const retain = (receipt) => {
+    if (receipt?.cleanup?.confirmed !== false) return;
+    lease?.retain();
+    if (!unresolvedOwners.has(executionId)) {
+      unresolvedOwners.set(executionId, { proc, durable: lease !== null });
+    }
+  };
+  // Install before post-spawn bookkeeping and caller listeners. The error
+  // precedes cleanup:unconfirmed, so reentrant callers must already be fenced.
+  proc.on("error", (error) => {
+    if (error.code === "EXTERNAL_AGENT_CLEANUP_UNCONFIRMED")
+      retain(proc.ownedProcessTreeEvidence);
+  });
+  proc.once("cleanup:unconfirmed", retain);
+}
+
+export function getProcessOwnershipStatus() {
+  const durable = durableJournal()?.inspect();
+  return {
+    blocked: unresolvedOwners.size > 0 || durable?.blocked === true,
+    unresolvedExecutionIds: [
+      ...new Set([
+        ...unresolvedOwners.keys(),
+        ...(durable?.blocked ? durable.pendingExecutionIds : []),
+      ]),
+    ],
+    recoveryRequired: unresolvedOwners.size > 0 || durable?.blocked === true,
+    durable:
+      !!durable &&
+      [...unresolvedOwners.values()].every((owner) => owner.durable),
+    restartSafe: false,
+  };
+}
+
+export function assertProcessOwnershipAvailable() {
+  if (unresolvedOwners.size === 0) {
+    durableJournal()?.assertAvailable();
+    return;
+  }
+  const error = new Error(
+    "Managed process execution is blocked because an earlier process tree has unconfirmed cleanup; restarting does not prove cleanup",
+  );
+  error.code = PROCESS_OWNERSHIP_UNCONFIRMED;
+  error.recoveryRequired = true;
+  error.executionStarted = false;
+  throw error;
+}

package/src/lib/runtime-usage-ledger.js

@@ -1,3 +1,5 @@
+import { projectUsagePricingContext } from "./usage-pricing-context.js";
+
 const MAX_LABEL_LENGTH = 160;
 const MAX_CALL_ID_LENGTH = 128;
 const MAX_OPERATION_ID_LENGTH = 160;
@@ -115,6 +117,7 @@ export function projectRuntimeTokenUsage(event = {}) {
     throw new TypeError("runtime token usage requires an object");
   }
   const usage = {};
+  Object.assign(usage, projectUsagePricingContext(event.usage));
   for (const [index, [canonical, alias]] of USAGE_FIELDS.entries()) {
     usage[canonical] = tokenCount(event.usage, canonical, alias, {
       // A known settlement must prove both billable input and output counts.