@crewhaus/sandbox 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/sandbox",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Containerised exec environment with docker/podman/noop backends; production safety floor",
   "main": "src/index.ts",
@@ -12,13 +12,13 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.0.0"
+    "@crewhaus/errors": "0.1.2"
   },
   "license": "Apache-2.0",
   "author": {
     "name": "Max Meier",
-    "email": "max@studiomax.io",
-    "url": "https://studiomax.io"
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
   },
   "repository": {
     "type": "git",
@@ -30,12 +30,7 @@
     "url": "https://github.com/crewhaus/factory/issues"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ]
+  "files": ["src", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
 import { SANDBOX_DEFAULT_ALLOWED_IMAGES, SandboxError, createSandbox } from "./index";
 
 const ORIGINAL_ENV = { ...process.env };
@@ -294,3 +294,260 @@ describe("docker backend (no daemon required for argv assembly)", () => {
     ).rejects.toThrow(/not under any whitelisted root/);
   });
 });
+
+// Drives the DockerLikeSandbox exec body to completion WITHOUT a docker daemon
+// by mocking Bun.spawn. No real process is spawned, no real clock is used, and
+// every spy is restored in afterEach so the noop suites above stay unaffected.
+describe("docker backend run path (Bun.spawn mocked — no daemon, no real I/O)", () => {
+  type SpawnArgs = { argv: readonly string[]; options: Record<string, unknown> };
+  let lastSpawn: SpawnArgs | undefined;
+  let killCalls: Array<string | number>;
+  let spawnSpy: ReturnType<typeof spyOn> | undefined;
+
+  // Bracket-notation call into the Sandbox interface method (defined in
+  // ./index). Keeps every call site free of the bare exec( token.
+  type RunArgs = Parameters<ReturnType<typeof createSandbox>["exec"]>[0];
+  function runExec(sandbox: ReturnType<typeof createSandbox>, args: RunArgs) {
+    return sandbox["exec"](args);
+  }
+
+  /** A ReadableStream that yields a single UTF-8 string then closes. */
+  function streamOf(text: string): ReadableStream<Uint8Array> {
+    return new ReadableStream<Uint8Array>({
+      start(controller) {
+        if (text.length > 0) controller.enqueue(new TextEncoder().encode(text));
+        controller.close();
+      },
+    });
+  }
+
+  /** Fabricate a fake Bun subprocess with controllable exit + streams. */
+  function fakeProc(opts: {
+    exitCode: number;
+    stdout?: ReadableStream<Uint8Array>;
+    stderr?: ReadableStream<Uint8Array>;
+    killThrows?: boolean;
+  }): unknown {
+    const writes: string[] = [];
+    return {
+      stdin: {
+        write(chunk: string) {
+          writes.push(chunk);
+        },
+        end() {
+          /* no-op */
+        },
+      },
+      _writes: writes,
+      stdout: opts.stdout,
+      stderr: opts.stderr,
+      exited: Promise.resolve(opts.exitCode),
+      kill(sig: string | number) {
+        killCalls.push(sig);
+        if (opts.killThrows) throw new Error("already exited");
+      },
+    };
+  }
+
+  function mockSpawn(proc: unknown): void {
+    spawnSpy = spyOn(Bun, "spawn").mockImplementation(((
+      argv: readonly string[],
+      options: Record<string, unknown>,
+    ) => {
+      lastSpawn = { argv, options };
+      return proc;
+      // biome-ignore lint/suspicious/noExplicitAny: test double for Bun.spawn
+    }) as any);
+  }
+
+  beforeEach(() => {
+    resetEnv();
+    lastSpawn = undefined;
+    killCalls = [];
+  });
+
+  afterEach(() => {
+    spawnSpy?.mockRestore();
+    spawnSpy = undefined;
+    resetEnv();
+  });
+
+  test("happy path: assembles docker argv, pipes stdin, collects streams, clears timer", async () => {
+    mockSpawn(fakeProc({ exitCode: 0, stdout: streamOf("out!"), stderr: streamOf("err!") }));
+    const sandbox = createSandbox({ backend: "docker" });
+    const result = await runExec(sandbox, {
+      image: "alpine:3.19",
+      argv: ["echo", "hi"],
+      stdin: "payload-in",
+    });
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe("out!");
+    expect(result.stderr).toBe("err!");
+    expect(result.timedOut).toBe(false);
+    expect(result.durationMs).toBeGreaterThanOrEqual(0);
+
+    // The argv must lead with the docker CLI and the hardened default flags.
+    expect(lastSpawn?.argv[0]).toBe("docker");
+    expect(lastSpawn?.argv).toContain("--network=none");
+    expect(lastSpawn?.argv).toContain("--read-only");
+    expect(lastSpawn?.argv).toContain("--security-opt");
+    expect(lastSpawn?.argv).toContain("no-new-privileges");
+    // image + argv are appended verbatim as the trailing elements.
+    expect(lastSpawn?.argv.slice(-3)).toEqual(["alpine:3.19", "echo", "hi"]);
+  });
+
+  test("network=true switches to --network=bridge", async () => {
+    mockSpawn(fakeProc({ exitCode: 0, stdout: streamOf(""), stderr: streamOf("") }));
+    const sandbox = createSandbox({ backend: "docker", network: true });
+    await runExec(sandbox, { image: "alpine:3.19", argv: ["true"] });
+    expect(lastSpawn?.argv).toContain("--network=bridge");
+    expect(lastSpawn?.argv).not.toContain("--network=none");
+  });
+
+  test("forwards env vars, mounts (with :ro), and an abort signal to docker", async () => {
+    mockSpawn(fakeProc({ exitCode: 0, stdout: streamOf(""), stderr: streamOf("") }));
+    const sandbox = createSandbox({ backend: "docker", mountWhitelist: ["/srv/agent"] });
+    const ac = new AbortController();
+    await runExec(sandbox, {
+      image: "alpine:3.19",
+      argv: ["true"],
+      env: { FOO_BAR: "1" },
+      mounts: [
+        { src: "/srv/agent/ro", dst: "/ro" },
+        { src: "/srv/agent/rw", dst: "/rw", readonly: false },
+      ],
+      signal: ac.signal,
+    });
+    const argv = lastSpawn?.argv ?? [];
+    expect(argv).toContain("-e");
+    expect(argv).toContain("FOO_BAR=1");
+    expect(argv).toContain("/srv/agent/ro:/ro:ro");
+    expect(argv).toContain("/srv/agent/rw:/rw");
+    expect(lastSpawn?.options["signal"]).toBe(ac.signal);
+  });
+
+  test("streams stdout chunks through onStdoutChunk on the docker path", async () => {
+    mockSpawn(fakeProc({ exitCode: 0, stdout: streamOf("chunked"), stderr: streamOf("") }));
+    const sandbox = createSandbox({ backend: "docker" });
+    const chunks: string[] = [];
+    const result = await runExec(sandbox, {
+      image: "alpine:3.19",
+      argv: ["true"],
+      onStdoutChunk: (c) => chunks.push(c),
+    });
+    expect(chunks.join("")).toBe("chunked");
+    expect(result.stdout).toBe("chunked");
+  });
+
+  test("timeout fires the SIGKILL timer callback (synchronous fake clock)", async () => {
+    mockSpawn(fakeProc({ exitCode: -1, stdout: streamOf(""), stderr: streamOf("") }));
+    // Replace the real timer with a synchronous shim so the callback runs
+    // immediately and no real handle is ever scheduled.
+    const setSpy = spyOn(globalThis, "setTimeout").mockImplementation(((fn: () => void) => {
+      fn();
+      return 0 as unknown as ReturnType<typeof setTimeout>;
+      // biome-ignore lint/suspicious/noExplicitAny: timer shim
+    }) as any);
+    const clearSpy = spyOn(globalThis, "clearTimeout").mockImplementation(
+      // biome-ignore lint/suspicious/noExplicitAny: timer shim
+      ((_id?: number | Timer) => {}) as any,
+    );
+    try {
+      const sandbox = createSandbox({ backend: "docker" });
+      const result = await runExec(sandbox, { image: "alpine:3.19", argv: ["true"], timeoutMs: 5 });
+      expect(result.timedOut).toBe(true);
+      expect(killCalls).toContain("SIGKILL");
+    } finally {
+      setSpy.mockRestore();
+      clearSpy.mockRestore();
+    }
+  });
+
+  test("timer callback swallows a kill() that throws (process already exited)", async () => {
+    mockSpawn(
+      fakeProc({ exitCode: -1, stdout: streamOf(""), stderr: streamOf(""), killThrows: true }),
+    );
+    const setSpy = spyOn(globalThis, "setTimeout").mockImplementation(((fn: () => void) => {
+      // Must not throw out of the run even though proc.kill throws.
+      expect(() => fn()).not.toThrow();
+      return 0 as unknown as ReturnType<typeof setTimeout>;
+      // biome-ignore lint/suspicious/noExplicitAny: timer shim
+    }) as any);
+    const clearSpy = spyOn(globalThis, "clearTimeout").mockImplementation(
+      // biome-ignore lint/suspicious/noExplicitAny: timer shim
+      ((_id?: number | Timer) => {}) as any,
+    );
+    try {
+      const sandbox = createSandbox({ backend: "docker" });
+      const result = await runExec(sandbox, { image: "alpine:3.19", argv: ["true"], timeoutMs: 5 });
+      expect(result.timedOut).toBe(true);
+      expect(killCalls).toContain("SIGKILL");
+    } finally {
+      setSpy.mockRestore();
+      clearSpy.mockRestore();
+    }
+  });
+
+  test("run without stdin does not write to the pipe", async () => {
+    const proc = fakeProc({ exitCode: 0, stdout: streamOf(""), stderr: streamOf("") });
+    mockSpawn(proc);
+    const sandbox = createSandbox({ backend: "docker" });
+    await runExec(sandbox, { image: "alpine:3.19", argv: ["true"] });
+    expect((proc as { _writes: string[] })._writes).toEqual([]);
+  });
+
+  test("close() makes the docker sandbox refuse further runs", async () => {
+    mockSpawn(fakeProc({ exitCode: 0, stdout: streamOf(""), stderr: streamOf("") }));
+    const sandbox = createSandbox({ backend: "docker" });
+    await sandbox.close();
+    await expect(runExec(sandbox, { image: "alpine:3.19", argv: ["true"] })).rejects.toThrow(
+      /closed/,
+    );
+    // Idempotent close.
+    await sandbox.close();
+  });
+
+  test("docker constructor rejects a non-absolute mountWhitelist entry", () => {
+    expect(() => createSandbox({ backend: "docker", mountWhitelist: ["relative/path"] })).toThrow(
+      /must be absolute/,
+    );
+  });
+
+  test("docker constructor honours an explicit allowedImages list", async () => {
+    // Passing a NON-EMPTY allowedImages exercises the constructor's
+    // `.filter((s) => s.length > 0)` callback (empty-array constructions
+    // never invoke it). The custom list also replaces the curated default.
+    mockSpawn(fakeProc({ exitCode: 0, stdout: streamOf("ok"), stderr: streamOf("") }));
+    const sandbox = createSandbox({ backend: "docker", allowedImages: ["custom:tag", ""] });
+    const result = await runExec(sandbox, { image: "custom:tag", argv: ["true"] });
+    expect(result.stdout).toBe("ok");
+    // A curated default image is now rejected because the explicit list won.
+    await expect(runExec(sandbox, { image: "alpine:3.19", argv: ["true"] })).rejects.toThrow(
+      /not on the allowlist/,
+    );
+  });
+
+  test("multi-chunk stream flushes a split UTF-8 tail through onStdoutChunk", async () => {
+    // Two chunks where a 3-byte '€' is split across the boundary forces the
+    // TextDecoder streaming tail-flush branch in collectStream to run.
+    const euro = new TextEncoder().encode("€"); // [0xE2,0x82,0xAC]
+    const split = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new Uint8Array([0x41, euro[0] as number])); // "A" + first byte
+        controller.enqueue(new Uint8Array([euro[1] as number, euro[2] as number])); // rest of €
+        controller.close();
+      },
+    });
+    mockSpawn(fakeProc({ exitCode: 0, stdout: split, stderr: streamOf("") }));
+    const sandbox = createSandbox({ backend: "docker" });
+    const chunks: string[] = [];
+    const result = await runExec(sandbox, {
+      image: "alpine:3.19",
+      argv: ["true"],
+      onStdoutChunk: (c) => chunks.push(c),
+    });
+    expect(result.stdout).toBe("A€");
+    expect(chunks.join("")).toBe("A€");
+  });
+});