@descryy/runtime-controller 0.3.8 → 0.3.9

package/dist/readiness.js

@@ -0,0 +1,214 @@
+/**
+ * Readiness (§6): "readiness must not equal 'process exists.'" Mechanisms: HTTP
+ * check, TCP/port check, log pattern, subprocess command, or a caller hook
+ * (consolidates the plan's "framework readiness hook" and "user-defined readiness"
+ * into one predicate shape).
+ *
+ * **`command` is not `custom-hook` (RT-193).** `custom-hook` runs a caller's
+ * in-process predicate; `command` runs a real subprocess and reads its exit code --
+ * built once so a caller with a real CLI health check (`pg_isready`) doesn't have to
+ * shell out from inside a hand-written hook.
+ *
+ * **What `ready: true` does not claim (RT-024).** All mechanisms answer "is
+ * something listening/responding," none confirm it's the process *this* spawn
+ * produced -- a stale listener from an already-dead run satisfies `http`/`tcp-port`
+ * identically. `log-pattern` only carries the stronger this-run guarantee if `read`
+ * is wired to this execution's own `readOutput()` (caller discipline, not enforced
+ * by the type). An ephemeral port closes this gap by construction; a fixed,
+ * guessable port doesn't. Found via a real 30s collector timeout that looked like a
+ * Playwright bug and was actually a wait on an orphaned process from a dead session
+ * (RT-024).
+ *
+ * **A single probe attempt cannot outlive `timeoutMs` (RT-030).** `http`/`tcp-port`
+ * bind I/O to the remaining time until `deadline`, not a fresh per-attempt budget --
+ * measured: an unbound `fetch` here let `awaitReadiness` run 8s+ past a 3s budget.
+ * `command` gets the same treatment via `execFile`'s `timeout`. `custom-hook` is not
+ * wrapped this way -- a caller predicate owns its own timeout, same as every other
+ * `Collector` callback contract here.
+ */
+import { createConnection } from "node:net";
+import { execFile } from "node:child_process";
+import { verifyListeningSocketOwner } from "./process-identity.js";
+export const READINESS_MECHANISMS = ["http", "tcp-port", "log-pattern", "command", "custom-hook"];
+/**
+ * How strongly a successful readiness result establishes that the answering
+ * process is THIS run's own -- RT-024. `"verified"`: a real kernel-state
+ * check (`process-identity.ts`) or a mechanism that is this-run-bound by
+ * construction (a directly-executed `command`, or `log-pattern` reading a
+ * branded `ProcessOutputReader`) confirmed it. `"unverified"`: the mechanism
+ * succeeded but nothing confirmed identity -- disclosed, not hidden.
+ * `"not-applicable"`: nothing succeeded, so no identity claim is being made.
+ */
+export const READINESS_IDENTITY_LEVELS = ["verified", "unverified", "not-applicable"];
+// Unexported on purpose: a real, module-private `unique symbol` (TS infers
+// that type for a `const` initialised with `Symbol()`) that only this module
+// can name. Nothing outside `readiness.ts` can construct a
+// structurally-compatible value even though TS is structurally typed
+// elsewhere -- the brand is the enforcement. See `ProcessOutputReader` below.
+const PROCESS_OUTPUT_READER_BRAND = Symbol("ProcessOutputReader");
+/** The only way to mint a `ProcessOutputReader` -- wrap the real output source this execution owns (`ManagedProcess.readOutput`, or an equivalent). */
+export function createProcessOutputReader(readOutput) {
+    return { [PROCESS_OUTPUT_READER_BRAND]: true, read: readOutput };
+}
+const DEFAULT_POLL_INTERVAL_MS = 200;
+export async function awaitReadiness(checks, options) {
+    const startedAt = Date.now();
+    const deadline = startedAt + options.timeoutMs;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    if (checks.length === 0) {
+        return { ready: false, mechanism: null, elapsedMs: 0, reason: "no readiness checks configured", identity: "not-applicable" };
+    }
+    // C-F4: last real diagnostic any probe captured before giving up (chiefly
+    // `command`'s stderr/exit code -- http/tcp-port have nothing richer than
+    // "connection refused"). Kept as "last seen", most likely to explain the timeout.
+    let lastDetail = null;
+    do {
+        for (const check of checks) {
+            const result = await probe(check, deadline);
+            if (result.ok) {
+                return { ready: true, mechanism: check.kind, elapsedMs: Date.now() - startedAt, reason: null, identity: result.identity };
+            }
+            if (result.detail !== null)
+                lastDetail = `${check.kind}: ${result.detail}`;
+        }
+        await sleep(pollIntervalMs);
+    } while (Date.now() < deadline);
+    // Names what was actually probed, not just that nothing answered -- the only
+    // cheap mitigation for the ephemeral-port race in `allocateEphemeralPort`
+    // (bind 0, read, close, spawn): if another process grabs the port first, the
+    // child never comes up and this message is the only symptom. Naming the exact
+    // address probed sends the reader to the port, not the application.
+    return {
+        ready: false,
+        mechanism: null,
+        elapsedMs: Date.now() - startedAt,
+        // "timeout" stays in the wording deliberately -- §41's hung-process test
+        // matches on that word.
+        reason: `no readiness mechanism succeeded within the ${options.timeoutMs}ms timeout — probed ${checks.map(describeCheck).join(", ")}` +
+            (lastDetail !== null ? `; last observed failure — ${lastDetail}` : ""),
+        identity: "not-applicable",
+    };
+}
+function describeCheck(check) {
+    switch (check.kind) {
+        case "http":
+            return check.url;
+        case "tcp-port":
+            return `tcp ${check.host}:${check.port}`;
+        case "log-pattern":
+            return `log pattern ${String(check.pattern)}`;
+        case "command":
+            return `command ${[check.command, ...(check.args ?? [])].join(" ")}`;
+        case "custom-hook":
+            return "custom hook";
+    }
+}
+function ok(identity = "not-applicable") {
+    return { ok: true, detail: null, identity };
+}
+function notReady(detail = null) {
+    return { ok: false, detail, identity: "not-applicable" };
+}
+/**
+ * Applies RT-024's identity check to a successful TCP-level connection
+ * (shared by `http` and `tcp-port`, which are both "something answered on
+ * this host:port"). No `expectedPid` supplied: succeeds, disclosed as
+ * `"unverified"` -- the caller gave this module nothing to check against, so
+ * it makes no claim either way rather than a silent pass reading as a
+ * guarantee. `expectedPid` supplied: only a real, kernel-confirmed
+ * `"verified"` is accepted as ready; `"mismatch"` is refused outright — a
+ * connection accepted by someone else's listener is not this run being
+ * ready; `"unsupported"` (non-Linux, or the pid can't be inspected) degrades
+ * to `"unverified"` rather than blocking a run this module simply cannot
+ * check on this platform.
+ */
+function identityCheckedConnection(port, expectedPid) {
+    if (expectedPid === undefined)
+        return ok("unverified");
+    const verification = verifyListeningSocketOwner(port, expectedPid);
+    if (verification === "verified")
+        return ok("verified");
+    if (verification === "unsupported")
+        return ok("unverified");
+    return notReady(`connected, but the listening socket on port ${String(port)} is not owned by pid ${String(expectedPid)} ` +
+        "(process-identity check via /proc) -- likely a stale listener from a different process, not this run's own");
+}
+async function probe(check, deadline) {
+    switch (check.kind) {
+        case "http":
+            return probeHttp(check, deadline);
+        case "tcp-port":
+            return probeTcpPort(check, deadline);
+        case "log-pattern":
+            // `read` is a branded ProcessOutputReader -- sourced from this
+            // execution's own output by construction, so a match is `"verified"`.
+            return check.pattern.test(check.read.read()) ? ok("verified") : notReady();
+        case "command":
+            return probeCommand(check, deadline);
+        case "custom-hook":
+            // An arbitrary caller predicate -- this module has no way to know
+            // whether it actually checks this run's own process, so it never
+            // claims more than "unverified" for a caller that passes.
+            return (await check.check()) ? ok("unverified") : notReady();
+    }
+}
+async function probeHttp(check, deadline) {
+    try {
+        const response = await fetch(check.url, { signal: AbortSignal.timeout(Math.max(0, deadline - Date.now())) });
+        if (response.status !== (check.expectedStatus ?? 200)) {
+            return notReady(`responded with status ${String(response.status)}, expected ${String(check.expectedStatus ?? 200)}`);
+        }
+        const url = new URL(check.url);
+        const port = url.port !== "" ? Number(url.port) : url.protocol === "https:" ? 443 : 80;
+        return identityCheckedConnection(port, check.expectedPid);
+    }
+    catch (error) {
+        return notReady(error instanceof Error ? error.message : String(error));
+    }
+}
+function probeTcpPort(check, deadline) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ host: check.host, port: check.port });
+        socket.setTimeout(Math.max(0, deadline - Date.now()));
+        const finish = (result) => {
+            socket.destroy();
+            resolve(result);
+        };
+        socket.once("connect", () => finish(identityCheckedConnection(check.port, check.expectedPid)));
+        socket.once("error", (error) => finish(notReady(error.message)));
+        socket.once("timeout", () => finish(notReady("connection attempt timed out")));
+    });
+}
+/**
+ * Ready when `check.command` exits 0 within the remaining time until `deadline`
+ * (RT-030). Non-zero exit, spawn failure, and timeout kill are all "not ready yet" --
+ * same as every other mechanism's `false`.
+ *
+ * C-F4: stdout/stderr are the actual health-check output, the richest diagnostic
+ * available here. Preferring stderr, then stdout, then the bare error message
+ * mirrors `runAttacher`'s ordering in `attach-to-running-jvm-process.ts`.
+ */
+function probeCommand(check, deadline) {
+    return new Promise((resolve) => {
+        const remainingMs = Math.max(0, deadline - Date.now());
+        if (remainingMs === 0) {
+            resolve(notReady("no time remaining before the readiness deadline"));
+            return;
+        }
+        execFile(check.command, check.args ?? [], { cwd: check.cwd, timeout: remainingMs }, (error, stdout, stderr) => {
+            if (error === null) {
+                // A directly `execFile`d subprocess is this-run-bound by
+                // construction -- there is no "which process answered" ambiguity
+                // the way a network probe has.
+                resolve(ok("verified"));
+                return;
+            }
+            const detail = stderr.trim() || stdout.trim() || error.message;
+            resolve(notReady(detail));
+        });
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=readiness.js.map

package/dist/readiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.js","sourceRoot":"","sources":["../src/readiness.ts"],"names":[],"mappings":"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"}

package/dist/sandbox.d.ts

@@ -0,0 +1,94 @@
+/**
+ * §21's execution boundary, real isolation half. RT-070/RT-193 gave this runtime a
+ * *named* boundary (trusted-local, resource limits, privilege reporting) but not an
+ * *isolating* one -- nothing stopped a spawned process from reading any file, or
+ * reaching any host, the invoking user could. This module closes that gap for real,
+ * on Linux, for processes this runtime SPAWNS.
+ *
+ * **Architectural constraint this module cannot solve around:** isolation can only
+ * wrap a process Descry itself launches. Attach-mode reaches a process already
+ * running, unconfined, before Descry touched it -- there is no honest way to
+ * retroactively contain it (ptrace-based interception was investigated and rejected
+ * elsewhere as not honestly generalizable). Attach-mode stays permanently and
+ * explicitly unsandboxed -- `SANDBOX_BOUNDARY_DISCLOSURE` in `execution-safety.ts`
+ * discloses this in-product; this module does not and structurally cannot change it.
+ *
+ * **Mechanism: bubblewrap (bwrap), not raw `unshare`/`clone`.** bwrap is the
+ * unprivileged sandboxing helper behind Flatpak -- small, auditable, actively
+ * maintained, not a bespoke native module this repo builds per-platform. Runs
+ * setuid-free on any kernel with unprivileged user namespaces enabled (checked
+ * below, never assumed) and gives one process a new mount namespace (real
+ * filesystem visibility control) and network namespace (real network denial) in one
+ * exec. Composes with `applyResourceLimits`'s `prlimit` wrap and with
+ * `process-manager.ts`'s process-group kill -- verified directly: bwrap does not
+ * create a new process group unless asked, so the existing group-kill reaches it
+ * unchanged. The one dependency this buys: `bwrap` must be on PATH, reported as a
+ * capability exactly like `prlimit` -- refused, never silently unconstrained, when
+ * requested and absent.
+ *
+ * **NOT attempted, deliberately: a native macOS or Windows sandbox.** `sandbox-exec`/
+ * Seatbelt is deprecated with no public API replacement; the Endpoint Security
+ * Framework needs an Apple entitlement this project doesn't have; Windows Job
+ * Objects + AppContainer + WFP would be a second and third bespoke native sandbox.
+ * This is an explicit decision not to build native sandboxes for those platforms at
+ * all -- `../container-sandbox.ts` closes the gap instead, routing macOS/Windows
+ * through a real Docker container that reuses this module's proven Linux mechanism
+ * (see that module's doc for what's real-tested there vs unverified on real
+ * hardware). `filesystemIsolationCapability`/`networkIsolationCapability` below
+ * still report `unavailable` with a reason on non-Linux -- never silently claimed
+ * as covered.
+ */
+import type { CapabilityStatus, FilesystemPolicy, NetworkPolicy } from "@descryy/runtime-contracts";
+/** Real capability check, same shape as `resourceLimitCapability`: PATH existence first, then the Linux-specific precondition existence alone doesn't prove -- unprivileged user namespaces actually usable, not just bwrap installed. */
+export declare function filesystemIsolationCapability(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): CapabilityStatus;
+/** Same underlying mechanism as `filesystemIsolationCapability` (one bwrap namespace set covers both) -- delegates rather than duplicating. Kept as its own function because the two policies are declared and reasoned about independently. */
+export declare function networkIsolationCapability(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): CapabilityStatus;
+/**
+ * `NetworkPolicy`'s general shape (arbitrary allow/deny host lists) is not what
+ * this mechanism enforces -- only full denial. Returns the reason a policy can't be
+ * applied, or `null` if it's the one shape that can. Checked independently of
+ * `networkIsolationCapability`: "nothing here can enforce any policy" and "this
+ * specific policy asks for something not built yet" are different claims.
+ */
+export declare function unsupportedNetworkPolicyReason(policy: NetworkPolicy): string | null;
+/**
+ * Resolves the real, symlink-followed directory containing the executable
+ * `command` would run as -- the one extra host path a sandboxed process needs
+ * beyond standard OS dirs and whatever the caller declared. Computed generically,
+ * not per-language: an interpreter installed outside `/usr` (nvm, rbenv, pyenv,
+ * sdkman) would otherwise be invisible inside the sandbox regardless of language.
+ * Returns `null` when unresolvable -- the caller proceeds without an extra bind;
+ * the exec fails inside the sandbox the same honest way it would outside one.
+ */
+export declare function resolveExecutableDirectory(command: string, cwd: string, env: NodeJS.ProcessEnv): string | null;
+export interface SandboxOptions {
+    /** Original, un-resource-limit-wrapped command (e.g. "node") -- used only to resolve which extra directory the interpreter needs bound in. */
+    readonly interpreterCommand: string;
+    /** Command to actually exec inside the sandbox -- already passed through `applyResourceLimits`, so may be "prlimit" with the real command in `args`. */
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly filesystemPolicy?: FilesystemPolicy;
+    readonly networkPolicy?: NetworkPolicy;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+}
+/**
+ * Wraps `command`/`args` with `bwrap` so the OS enforces `filesystemPolicy`/
+ * `networkPolicy`. Neither declared returns them unchanged -- same non-regression
+ * contract as `applyResourceLimits`.
+ *
+ * **Throws rather than silently spawning unconstrained** when a policy is
+ * requested and the real mechanism can't back it -- no mechanism on this platform,
+ * or a declared shape this mechanism doesn't implement.
+ *
+ * Composes with `applyResourceLimits` by wrapping *outside* it (`bwrap … --
+ * prlimit … -- realCommand`) -- the mount namespace must exist before `prlimit` or
+ * the real command run inside it; `prlimit` (in `/usr/bin`) is reachable through
+ * the same base OS binding every sandboxed process gets.
+ */
+export declare function applySandbox(options: SandboxOptions): {
+    readonly command: string;
+    readonly args: readonly string[];
+};
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAkCpG,0OAA0O;AAC1O,wBAAgB,6BAA6B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,gBAAgB,CAoBlJ;AAED,gPAAgP;AAChP,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,gBAAgB,CAE/I;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAOnF;AAOD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,GAAG,IAAI,CAwB9G;AAED,MAAM,WAAW,cAAc;IAC7B,8IAA8I;IAC9I,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,wJAAwJ;IACxJ,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CACrC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAkFpH"}

package/dist/sandbox.js

@@ -0,0 +1,228 @@
+/**
+ * §21's execution boundary, real isolation half. RT-070/RT-193 gave this runtime a
+ * *named* boundary (trusted-local, resource limits, privilege reporting) but not an
+ * *isolating* one -- nothing stopped a spawned process from reading any file, or
+ * reaching any host, the invoking user could. This module closes that gap for real,
+ * on Linux, for processes this runtime SPAWNS.
+ *
+ * **Architectural constraint this module cannot solve around:** isolation can only
+ * wrap a process Descry itself launches. Attach-mode reaches a process already
+ * running, unconfined, before Descry touched it -- there is no honest way to
+ * retroactively contain it (ptrace-based interception was investigated and rejected
+ * elsewhere as not honestly generalizable). Attach-mode stays permanently and
+ * explicitly unsandboxed -- `SANDBOX_BOUNDARY_DISCLOSURE` in `execution-safety.ts`
+ * discloses this in-product; this module does not and structurally cannot change it.
+ *
+ * **Mechanism: bubblewrap (bwrap), not raw `unshare`/`clone`.** bwrap is the
+ * unprivileged sandboxing helper behind Flatpak -- small, auditable, actively
+ * maintained, not a bespoke native module this repo builds per-platform. Runs
+ * setuid-free on any kernel with unprivileged user namespaces enabled (checked
+ * below, never assumed) and gives one process a new mount namespace (real
+ * filesystem visibility control) and network namespace (real network denial) in one
+ * exec. Composes with `applyResourceLimits`'s `prlimit` wrap and with
+ * `process-manager.ts`'s process-group kill -- verified directly: bwrap does not
+ * create a new process group unless asked, so the existing group-kill reaches it
+ * unchanged. The one dependency this buys: `bwrap` must be on PATH, reported as a
+ * capability exactly like `prlimit` -- refused, never silently unconstrained, when
+ * requested and absent.
+ *
+ * **NOT attempted, deliberately: a native macOS or Windows sandbox.** `sandbox-exec`/
+ * Seatbelt is deprecated with no public API replacement; the Endpoint Security
+ * Framework needs an Apple entitlement this project doesn't have; Windows Job
+ * Objects + AppContainer + WFP would be a second and third bespoke native sandbox.
+ * This is an explicit decision not to build native sandboxes for those platforms at
+ * all -- `../container-sandbox.ts` closes the gap instead, routing macOS/Windows
+ * through a real Docker container that reuses this module's proven Linux mechanism
+ * (see that module's doc for what's real-tested there vs unverified on real
+ * hardware). `filesystemIsolationCapability`/`networkIsolationCapability` below
+ * still report `unavailable` with a reason on non-Linux -- never silently claimed
+ * as covered.
+ */
+import { execFileSync } from "node:child_process";
+import { accessSync, constants as fsConstants, readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
+/**
+ * Whether unprivileged user namespaces -- the kernel feature bwrap needs to build a
+ * mount/network namespace without running setuid-root -- are actually enabled on
+ * this host, never merely assumed from "the kernel supports namespaces in general."
+ * Two independent sysctls can each disable it. IMPORTANT: a sysctl file not existing
+ * is NOT evidence it's unrestricted -- only Debian/Ubuntu-derived kernels gate it
+ * through `unprivileged_userns_clone` at all, so a missing file proves nothing
+ * either way. We can't tell from absence, so we don't read it as a positive signal:
+ * `ok: true` here means "neither sysctl was found to explicitly disable it," not
+ * "isolation is confirmed available" -- it only rules out these two specific,
+ * explicit-disable signals.
+ */
+function unprivilegedUserNamespaceStatus() {
+    try {
+        const clone = readFileSync("/proc/sys/kernel/unprivileged_userns_clone", "utf8").trim();
+        if (clone === "0") {
+            return { ok: false, reason: "kernel.unprivileged_userns_clone=0 -- unprivileged user namespaces are disabled on this host" };
+        }
+    }
+    catch {
+        // Sysctl absent -- not evidence either way, not just non-Debian kernels.
+    }
+    try {
+        const max = readFileSync("/proc/sys/user/max_user_namespaces", "utf8").trim();
+        if (max === "0") {
+            return { ok: false, reason: "user.max_user_namespaces=0 -- unprivileged user namespaces are disabled on this host" };
+        }
+    }
+    catch {
+        // Same reasoning: absent is not evidence of a restriction.
+    }
+    return { ok: true, reason: null };
+}
+/** Real capability check, same shape as `resourceLimitCapability`: PATH existence first, then the Linux-specific precondition existence alone doesn't prove -- unprivileged user namespaces actually usable, not just bwrap installed. */
+export function filesystemIsolationCapability(env = process.env, platform = process.platform) {
+    if (platform !== "linux") {
+        return {
+            availability: "unavailable",
+            reason: `no filesystem isolation mechanism is wired up on "${platform}" for bwrap -- by design, not by omission (native sandbox-exec/Seatbelt and Job Objects/AppContainer were researched and rejected); see container-sandbox.ts, which routes "${platform}" through a real Docker container instead`,
+        };
+    }
+    try {
+        execFileSync("bwrap", ["--version"], { env, stdio: "ignore" });
+    }
+    catch {
+        return {
+            availability: "unavailable",
+            reason: "bubblewrap (bwrap) is not on PATH -- filesystem isolation cannot be enforced without it",
+        };
+    }
+    const userns = unprivilegedUserNamespaceStatus();
+    if (!userns.ok) {
+        return { availability: "unavailable", reason: `bubblewrap is installed but unprivileged user namespaces are unavailable: ${userns.reason}` };
+    }
+    return { availability: "available", reason: null };
+}
+/** Same underlying mechanism as `filesystemIsolationCapability` (one bwrap namespace set covers both) -- delegates rather than duplicating. Kept as its own function because the two policies are declared and reasoned about independently. */
+export function networkIsolationCapability(env = process.env, platform = process.platform) {
+    return filesystemIsolationCapability(env, platform);
+}
+/**
+ * `NetworkPolicy`'s general shape (arbitrary allow/deny host lists) is not what
+ * this mechanism enforces -- only full denial. Returns the reason a policy can't be
+ * applied, or `null` if it's the one shape that can. Checked independently of
+ * `networkIsolationCapability`: "nothing here can enforce any policy" and "this
+ * specific policy asks for something not built yet" are different claims.
+ */
+export function unsupportedNetworkPolicyReason(policy) {
+    if (policy.mode === "allow" && policy.hosts.length === 0)
+        return null;
+    return ('only full network denial ({ mode: "allow", hosts: [] }) is enforced -- selective allow- or deny-listing of ' +
+        "specific hosts needs DNS interception and IP filtering inside the sandbox's network namespace (a veth pair, " +
+        "NAT, iptables/nftables rules), not built in this iteration");
+}
+function isWithin(root, target) {
+    const rel = relative(root, target);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/**
+ * Resolves the real, symlink-followed directory containing the executable
+ * `command` would run as -- the one extra host path a sandboxed process needs
+ * beyond standard OS dirs and whatever the caller declared. Computed generically,
+ * not per-language: an interpreter installed outside `/usr` (nvm, rbenv, pyenv,
+ * sdkman) would otherwise be invisible inside the sandbox regardless of language.
+ * Returns `null` when unresolvable -- the caller proceeds without an extra bind;
+ * the exec fails inside the sandbox the same honest way it would outside one.
+ */
+export function resolveExecutableDirectory(command, cwd, env) {
+    let candidate = null;
+    if (command.includes("/")) {
+        candidate = isAbsolute(command) ? command : join(cwd, command);
+    }
+    else {
+        const pathVar = env.PATH ?? "";
+        for (const dir of pathVar.split(":")) {
+            if (dir === "")
+                continue;
+            const full = join(dir, command);
+            try {
+                accessSync(full, fsConstants.X_OK);
+                candidate = full;
+                break;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    if (candidate === null)
+        return null;
+    try {
+        return dirname(realpathSync(candidate));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Wraps `command`/`args` with `bwrap` so the OS enforces `filesystemPolicy`/
+ * `networkPolicy`. Neither declared returns them unchanged -- same non-regression
+ * contract as `applyResourceLimits`.
+ *
+ * **Throws rather than silently spawning unconstrained** when a policy is
+ * requested and the real mechanism can't back it -- no mechanism on this platform,
+ * or a declared shape this mechanism doesn't implement.
+ *
+ * Composes with `applyResourceLimits` by wrapping *outside* it (`bwrap … --
+ * prlimit … -- realCommand`) -- the mount namespace must exist before `prlimit` or
+ * the real command run inside it; `prlimit` (in `/usr/bin`) is reachable through
+ * the same base OS binding every sandboxed process gets.
+ */
+export function applySandbox(options) {
+    const { filesystemPolicy, networkPolicy } = options;
+    if (filesystemPolicy === undefined && networkPolicy === undefined) {
+        return { command: options.command, args: options.args };
+    }
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    if (networkPolicy !== undefined) {
+        const shapeReason = unsupportedNetworkPolicyReason(networkPolicy);
+        if (shapeReason !== null) {
+            throw new Error(`networkPolicy was configured but cannot be enforced: ${shapeReason}`);
+        }
+        const capability = networkIsolationCapability(env, platform);
+        if (capability.availability !== "available") {
+            throw new Error(`networkPolicy was configured but cannot be enforced on this platform: ${capability.reason}`);
+        }
+    }
+    if (filesystemPolicy !== undefined) {
+        const capability = filesystemIsolationCapability(env, platform);
+        if (capability.availability !== "available") {
+            throw new Error(`filesystemPolicy was configured but cannot be enforced on this platform: ${capability.reason}`);
+        }
+    }
+    const bwrapArgs = [];
+    if (filesystemPolicy !== undefined) {
+        bwrapArgs.push("--ro-bind", "/usr", "/usr", "--symlink", "/usr/bin", "/bin", "--symlink", "/usr/lib", "/lib", "--symlink", "/usr/lib64", "/lib64", "--proc", "/proc", "--dev", "/dev", "--tmpfs", "/tmp", "--bind", options.cwd, options.cwd);
+        const boundRoots = ["/usr", options.cwd, ...filesystemPolicy.allowedRoots];
+        for (const root of filesystemPolicy.allowedRoots) {
+            bwrapArgs.push("--bind", root, root);
+        }
+        const interpreterDir = resolveExecutableDirectory(options.interpreterCommand, options.cwd, env);
+        if (interpreterDir !== null && !boundRoots.some((root) => isWithin(root, interpreterDir))) {
+            bwrapArgs.push("--ro-bind", interpreterDir, interpreterDir);
+        }
+    }
+    else {
+        // No filesystem restriction declared -- mirror the host root exactly (matches
+        // FilesystemPolicy's "absent means unconstrained" default). A mount namespace
+        // is still created (bwrap always builds one; --unshare-net below needs it), so
+        // /proc, /dev, /tmp are remounted explicitly -- a plain `--bind / /` is not
+        // recursive and would leave them looking empty inside otherwise.
+        bwrapArgs.push("--bind", "/", "/", "--dev", "/dev", "--proc", "/proc", "--bind", "/tmp", "/tmp");
+    }
+    bwrapArgs.push("--chdir", options.cwd);
+    if (networkPolicy !== undefined) {
+        bwrapArgs.push("--unshare-net");
+    }
+    // Kills the sandboxed tree if bwrap's parent (this Node process) dies
+    // unexpectedly -- a second, independent backstop alongside process-manager.ts's
+    // group-kill, not a replacement for it.
+    bwrapArgs.push("--die-with-parent", "--", options.command, ...options.args);
+    return { command: "bwrap", args: bwrapArgs };
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descryy/runtime-controller",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "type": "module",
   "description": "Runtime controller: process manager, readiness, timeout/cancellation, execution IDs, cleanup. Deliverable 2 of the runtime phase — depends on @descryy/runtime-contracts, builds no collectors.",
   "license": "UNLICENSED",