@chengchenccc/sandbox 0.1.1-rc.2 → 0.2.0-rc.1

package/dist/index.d.ts

@@ -24,6 +24,21 @@ export interface SandboxInput {
     cwd?: string;
     /** Keep the working dir after the run (default: removed). */
     keepCwd?: boolean;
+    /** H2: OS-level isolation knobs. When requested and a wrapper tool is
+     *  available (Linux: bwrap, macOS: sandbox-exec) the subprocess runs
+     *  inside it; without a tool the run falls back to process isolation
+     *  only, with a warning naming the ceiling. */
+    isolation?: {
+        /** Cut all network access (unshare-net / deny network*). */
+        noNetwork?: boolean;
+        /** Directories the script must not read: overlaid with an empty tmpfs
+         *  (bwrap) or denied by profile (sandbox-exec). Non-existent dirs are
+         *  skipped. */
+        denyReadDirs?: readonly string[];
+    };
+    /** Abort kills the process tree immediately (the run resolves with a
+     *  non-zero exit, timedOut stays false). */
+    signal?: AbortSignal;
 }
 export interface SandboxResult {
     /** The script's returned value (parsed JSON), or null when it returned nothing. */
@@ -35,6 +50,10 @@ export interface SandboxResult {
     exitCode: number;
     timedOut: boolean;
 }
+/** Compose the spawn argv for one sandboxed process: platform wrapper
+ *  (setsid/bwrap/sandbox-exec) around the base command. Shared by the
+ *  one-shot runner and persistent sessions. */
+export declare function buildWrappedArgv(baseArgv: readonly string[], isolation: SandboxInput["isolation"] | undefined, dir: string): string[];
 export declare function runInSandbox(input: SandboxInput): Promise<SandboxResult>;
 export declare class SandboxTimeoutError extends Error {
     constructor(timeoutMs: number);

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;wEAYwE;AAMxE,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACvC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAoCD,wBAAsB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAgD9E;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,SAAS,EAAE,MAAM;CAI9B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;wEAYwE;AAKxE,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;mDAG+C;IAC/C,SAAS,CAAC,EAAE;QACV,4DAA4D;QAC5D,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB;;uBAEe;QACf,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KAClC,CAAC;IACF;gDAC4C;IAC5C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACvC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAuHD;;+CAE+C;AAC/C,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,SAAS,EAAE,YAAY,CAAC,WAAW,CAAC,GAAG,SAAS,EAChD,GAAG,EAAE,MAAM,GACV,MAAM,EAAE,CAsBV;AAED,wBAAsB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CA8G9E;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,SAAS,EAAE,MAAM;CAI9B"}

package/dist/index.js

@@ -11,9 +11,9 @@
  *  no access to host objects). It is NOT a filesystem/network jail — a
  *  hostile script can still touch the host filesystem like any spawned
  *  process. Container-level isolation is a deliberate non-goal here. */
-import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 const BASE_ENV = {
     PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
     HOME: tmpdir(),
@@ -46,33 +46,198 @@ try {
   process.exit(1);
 }
 `;
+function bwrapArgv(base, isolation, selfBinDir) {
+    const args = [
+        "bwrap",
+        "--dev-bind",
+        "/",
+        "/",
+        // Fresh PID namespace + procfs: the script cannot see, signal, or
+        // enumerate host processes (the backend included).
+        "--unshare-pid",
+        "--proc",
+        "/proc",
+    ];
+    if (isolation?.noNetwork)
+        args.push("--unshare-net");
+    // Hide the sandbox user's home dirs: the script runs as the SAME user,
+    // so home is the highest-value read/write surface. The bun binary often
+    // lives under the home — re-expose its bin dir read-only so PATH lookup
+    // and exec keep working.
+    args.push("--tmpfs", "/root", "--tmpfs", "/home", "--ro-bind", selfBinDir, selfBinDir);
+    for (const d of isolation?.denyReadDirs ?? []) {
+        if (!existsSync(d))
+            continue;
+        // Directory: empty tmpfs shadows content (reads AND writes). File
+        // (e.g. the deployment .env): /dev/null overlay empties its reads.
+        if (statSync(d).isDirectory())
+            args.push("--tmpfs", d);
+        else
+            args.push("--ro-bind", "/dev/null", d);
+    }
+    args.push(...base);
+    return args;
+}
+function sandboxExecArgv(base, dir, isolation) {
+    const denies = (isolation?.denyReadDirs ?? [])
+        .map((d) => `(deny file-read-data (subpath "${d}"))`)
+        .join("");
+    const net = isolation?.noNetwork ? "(deny network*)" : "";
+    const profilePath = join(dir, "__sandbox_profile.sb");
+    writeFileSync(profilePath, `(version 1)(allow default)${net}${denies}`);
+    return ["sandbox-exec", "-f", profilePath, ...base];
+}
+/** Post-exit drain grace: fires only when the pipe is still open (an
+ *  orphaned grandchild holds it) — buffered data resolves instantly. */
+function stallAfter(ms) {
+    const { promise, resolve } = Promise.withResolvers();
+    const t = setTimeout(() => resolve("stalled"), ms);
+    t.unref?.();
+    return promise;
+}
+/** Depth-first descendant reap for platforms without setsid (H3): pgrep -P
+ *  per generation, grandchildren killed before their parents so nothing
+ *  re-parents and survives. Best effort — a missing pgrep degrades to the
+ *  direct-child kill only. */
+function killDescendants(pid, signal) {
+    let kids;
+    try {
+        kids = Bun.spawnSync(["pgrep", "-P", String(pid)])
+            .stdout.toString()
+            .split("\n")
+            .flatMap((line) => {
+            const n = Number(line.trim());
+            return Number.isInteger(n) && n > 0 ? [n] : [];
+        });
+    }
+    catch {
+        return;
+    }
+    for (const kid of kids)
+        killDescendants(kid, signal);
+    for (const kid of kids) {
+        try {
+            process.kill(kid, signal);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+/** Compose the spawn argv for one sandboxed process: platform wrapper
+ *  (setsid/bwrap/sandbox-exec) around the base command. Shared by the
+ *  one-shot runner and persistent sessions. */
+export function buildWrappedArgv(baseArgv, isolation, dir) {
+    const hasSetsid = Bun.which("setsid") !== null;
+    const wantsNetworkCut = isolation?.noNetwork === true;
+    const wantsDenyRead = (isolation?.denyReadDirs?.length ?? 0) > 0;
+    const isolationRequested = wantsNetworkCut || wantsDenyRead;
+    const onLinux = process.platform === "linux";
+    const onMacos = process.platform === "darwin";
+    const hasBwrap = Bun.which("bwrap") !== null;
+    const hasSandboxExec = Bun.which("sandbox-exec") !== null;
+    let argv = [...baseArgv];
+    if (isolationRequested) {
+        if (onLinux && hasBwrap) {
+            argv = bwrapArgv(argv, isolation, dirname(process.execPath));
+        }
+        else if (onMacos && hasSandboxExec) {
+            argv = sandboxExecArgv(argv, dir, isolation);
+        }
+        else {
+            console.warn("[sandbox] isolation requested but no bwrap/sandbox-exec available — running with process isolation only");
+        }
+    }
+    return hasSetsid ? ["setsid", ...argv] : argv;
+}
 export async function runInSandbox(input) {
-    const timeoutMs = input.timeoutMs ?? 30_000;
+    // pi semantics: 0 disables the deadline entirely (a cell may legitimately
+    // run long); undefined keeps the historical 30s default.
+    const timeoutMs = input.timeoutMs === 0 ? 0 : (input.timeoutMs ?? 30_000);
+    const hasDeadline = timeoutMs > 0;
     const dir = input.cwd ?? mkTempDir();
     mkdirSync(dir, { recursive: true });
     writeFileSync(join(dir, "script.ts"), input.code);
     writeFileSync(join(dir, "__sandbox_main.ts"), WRAPPER);
     let timedOut = false;
+    // Cap buffered output: a hostile `while(true) console.log(...)` would
+    // otherwise OOM the backend before the timeout fires.
+    const MAX_STREAM_BYTES = 10 * 1024 * 1024;
+    async function cappedText(stream) {
+        const reader = stream.getReader();
+        const chunks = [];
+        let total = 0;
+        let exitedSeen = false;
+        for (;;) {
+            const read = reader.read();
+            // During the run: wait on data OR process exit. Losing to exit means
+            // EOF is pending (H3: an orphaned grandchild inheriting the pipe can
+            // hold it open forever) — switch to the bounded drain below.
+            const res = exitedSeen
+                ? await Promise.race([read, stallAfter(1_000)])
+                : await Promise.race([read, exited.then(() => "exited")]);
+            if (res === "exited") {
+                exitedSeen = true;
+                continue;
+            }
+            if (res === "stalled" || res.done) {
+                // Post-exit the kernel buffer delivers instantly; stalling past the
+                // grace means an orphan still holds the pipe — cancel and use what
+                // we got instead of hanging on EOF.
+                if (res === "stalled")
+                    reader.cancel().catch(() => { });
+                break;
+            }
+            total += res.value.byteLength;
+            if (total <= MAX_STREAM_BYTES)
+                chunks.push(res.value);
+        }
+        const buf = Buffer.concat(chunks).toString("utf8");
+        return total > MAX_STREAM_BYTES
+            ? `${buf.slice(0, MAX_STREAM_BYTES)}\n[sandbox: output truncated at ${MAX_STREAM_BYTES} bytes]`
+            : buf;
+    }
+    const argv = buildWrappedArgv(["bun", "run", join(dir, "__sandbox_main.ts")], input.isolation, dir);
+    const proc = Bun.spawn(argv, {
+        cwd: dir,
+        env: { ...BASE_ENV, ...(input.env ?? {}) },
+        stdin: "pipe",
+        stdout: "pipe",
+        stderr: "pipe",
+    });
+    proc.stdin.write(JSON.stringify(input.input ?? {}));
+    proc.stdin.end();
+    const exited = proc.exited;
     try {
-        const proc = Bun.spawn(["bun", "run", join(dir, "__sandbox_main.ts")], {
-            cwd: dir,
-            env: { ...BASE_ENV, ...(input.env ?? {}) },
-            stdin: "pipe",
-            stdout: "pipe",
-            stderr: "pipe",
-        });
-        proc.stdin.write(JSON.stringify(input.input ?? {}));
-        proc.stdin.end();
-        const timer = setTimeout(() => {
-            timedOut = true;
-            proc.kill();
-        }, timeoutMs);
-        const [stdout, stderr, exitCode] = await Promise.all([
-            new Response(proc.stdout).text(),
-            new Response(proc.stderr).text(),
-            proc.exited,
-        ]);
+        const killTree = (signal) => {
+            // Group kill first (setsid made the child a leader); fall back to
+            // direct child + a depth-first descendant reap when no group exists
+            // (macOS has no setsid).
+            try {
+                process.kill(-proc.pid, signal);
+            }
+            catch {
+                proc.kill(signal);
+                killDescendants(proc.pid, signal);
+            }
+        };
+        let escalation;
+        const timer = hasDeadline
+            ? setTimeout(() => {
+                timedOut = true;
+                killTree("SIGTERM");
+                escalation = setTimeout(() => killTree("SIGKILL"), 2_000);
+                escalation.unref?.();
+            }, timeoutMs)
+            : undefined;
+        // H3: completion is gated on proc.exited, NEVER on pipe EOF.
+        const exitCode = await exited;
         clearTimeout(timer);
+        clearTimeout(escalation);
+        const [stdout, stderr] = await Promise.all([
+            cappedText(proc.stdout),
+            cappedText(proc.stderr),
+        ]);
         const marker = stdout.lastIndexOf("__SANDBOX_OUTPUT__:");
         let output = null;
         let cleanStdout = stdout;

package/dist/index.test.js

@@ -1,4 +1,7 @@
 import { expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { runInSandbox } from "./index.js";
 test("runs a script and returns its output", async () => {
     const r = await runInSandbox({
@@ -34,6 +37,26 @@ test("timeout kills the process", async () => {
         timeoutMs: 1_000,
     })).rejects.toThrow(/timed out/);
 });
+const HAS_SETSID = Bun.which("setsid") !== null;
+test.skipIf(!HAS_SETSID)("timeout throws even when a detached grandchild holds stdout (H3)", async () => {
+    // `setsid sleep` escapes the process group and inherits our stdout
+    // pipe: EOF never arrives after the tree kill, so the old EOF-gated
+    // Promise.all hung until the daemon exited. Completion is now gated
+    // on proc.exited with a bounded post-exit drain.
+    const start = Date.now();
+    await expect(runInSandbox({
+        // Explicit inherit: the daemon's stdout IS the sandbox's pipe (a
+        // default-stdio spawn gets its own pipe and holds nothing).
+        code: `export default async () => {
+  const daemon = Bun.spawn(["setsid", "sleep", "5"], { stdout: "inherit", stderr: "inherit" });
+  await daemon.exited;
+  return { ok: true };
+};`,
+        input: {},
+        timeoutMs: 1_500,
+    })).rejects.toThrow(/timed out/);
+    expect(Date.now() - start).toBeLessThan(5_000);
+}, 30_000);
 test("minimal env — no host env leakage by default", async () => {
     const r = await runInSandbox({
         code: `export default async () => ({ hasSecret: typeof process.env.SANDBOX_LEAK_TEST !== "undefined" });`,
@@ -42,3 +65,43 @@ test("minimal env — no host env leakage by default", async () => {
     });
     expect(r.output).toEqual({ hasSecret: false });
 });
+const HAS_BWRAP = Bun.which("bwrap") !== null;
+test("isolation cuts network and hides denied dirs (H2)", async () => {
+    if (!HAS_BWRAP)
+        return;
+    const secretDir = mkdtempSync(join(tmpdir(), "sbx-secret-"));
+    writeFileSync(join(secretDir, "secret.txt"), "topsecret");
+    const r = await runInSandbox({
+        code: `export default async () => {
+  let netBlocked = false;
+  try {
+    await fetch("http://example.com/", { signal: AbortSignal.timeout(2_000) });
+  } catch {
+    netBlocked = true;
+  }
+  let readBlocked = false;
+  try {
+    await Bun.file(${JSON.stringify(join(secretDir, "secret.txt"))}).text();
+  } catch {
+    readBlocked = true;
+  }
+  return { netBlocked, readBlocked };
+};`,
+        isolation: { noNetwork: true, denyReadDirs: [secretDir] },
+        timeoutMs: 20_000,
+    });
+    expect(r.exitCode).toBe(0);
+    expect(r.output).toEqual({ netBlocked: true, readBlocked: true });
+    rmSync(secretDir, { recursive: true, force: true });
+}, 30_000);
+test("isolation wrapper does not disturb normal execution (H2)", async () => {
+    if (!HAS_BWRAP)
+        return;
+    const r = await runInSandbox({
+        code: `export default async () => ({ echo: 41 + 1 });`,
+        isolation: { noNetwork: true, denyReadDirs: ["/nonexistent-h2"] },
+        timeoutMs: 20_000,
+    });
+    expect(r.exitCode).toBe(0);
+    expect(r.output).toEqual({ echo: 42 });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chengchenccc/sandbox",
-  "version": "0.1.1-rc.2",
+  "version": "0.2.0-rc.1",
   "description": "Process-isolated sandbox for executing untrusted workflow/eval scripts (Bun subprocess, timeout kill, JSON stdio)",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,7 +11,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "lint": "biome check . && eslint .",
-    "test": "bun test --pass-with-no-tests",
+    "test": "bun test src --pass-with-no-tests",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "devDependencies": {},