@openparachute/agent 0.1.2 → 0.2.0

package/src/sandbox/mounts.test.ts

@@ -0,0 +1,154 @@
+import { describe, test, expect } from "bun:test";
+import {
+  composeFilesystemView,
+  homeTreeDenyRoot,
+  sharedMounts,
+} from "./mounts.ts";
+import type { AgentMount, BaseBinds } from "./types.ts";
+
+const BASE: BaseBinds = {
+  workspace: "/state/sessions/arm",
+  runtimeReadOnly: ["/home/op/.claude"],
+};
+
+describe("homeTreeDenyRoot — platform nuance", () => {
+  test("macOS denies /Users", () => {
+    expect(homeTreeDenyRoot("darwin")).toBe("/Users");
+  });
+  test("Linux denies /home", () => {
+    expect(homeTreeDenyRoot("linux")).toBe("/home");
+  });
+});
+
+describe("composeFilesystemView — scoped reads + write confinement", () => {
+  test("with no mounts: reads = workspace + runtime, writes = workspace only", () => {
+    const fs = composeFilesystemView(BASE, undefined, "darwin");
+    expect(fs.allowRead).toContain("/state/sessions/arm");
+    expect(fs.allowRead).toContain("/home/op/.claude");
+    expect(fs.allowWrite).toEqual(["/state/sessions/arm"]);
+  });
+
+  test("the home tree is denied for reads (scoped-read policy, §4.5)", () => {
+    const fs = composeFilesystemView(BASE, undefined, "darwin");
+    expect(fs.denyRead).toContain("/Users");
+  });
+
+  test("the home tree denied is platform-correct on Linux", () => {
+    const fs = composeFilesystemView(BASE, undefined, "linux");
+    expect(fs.denyRead).toContain("/home");
+  });
+
+  test("an ro mount is readable but NOT writable", () => {
+    const mounts: AgentMount[] = [{ hostPath: "/refs/tree", mountPath: "/ref", mode: "ro" }];
+    const fs = composeFilesystemView(BASE, mounts, "darwin");
+    expect(fs.allowRead).toContain("/refs/tree");
+    expect(fs.allowWrite).not.toContain("/refs/tree");
+  });
+
+  test("an rw mount is BOTH readable and writable", () => {
+    const mounts: AgentMount[] = [{ hostPath: "/proj/foo", mountPath: "/work/foo", mode: "rw" }];
+    const fs = composeFilesystemView(BASE, mounts, "darwin");
+    expect(fs.allowRead).toContain("/proj/foo");
+    expect(fs.allowWrite).toContain("/proj/foo");
+  });
+
+  test("SECURITY: a path OUTSIDE all binds is not in the read surface (scoped, not broad)", () => {
+    const mounts: AgentMount[] = [{ hostPath: "/proj/foo", mountPath: "/work/foo", mode: "rw" }];
+    const fs = composeFilesystemView(BASE, mounts, "darwin");
+    // The operator's SSH dir / other vaults are NOT re-allowed within the denied home tree.
+    expect(fs.allowRead).not.toContain("/Users/op/.ssh");
+    expect(fs.allowRead).not.toContain("/Users/op/other-vault");
+    // And nothing widened the deny away.
+    expect(fs.denyRead).toEqual(["/Users"]);
+  });
+
+  test("SECURITY: writes are confined — only workspace + rw mounts, never an ro mount or arbitrary path", () => {
+    const mounts: AgentMount[] = [
+      { hostPath: "/refs/tree", mountPath: "/ref", mode: "ro" },
+      { hostPath: "/proj/foo", mountPath: "/work/foo", mode: "rw" },
+    ];
+    const fs = composeFilesystemView(BASE, mounts, "darwin");
+    expect(new Set(fs.allowWrite)).toEqual(new Set(["/state/sessions/arm", "/proj/foo"]));
+  });
+
+  test("the base binds are always present even if the spec declares none", () => {
+    const fs = composeFilesystemView(BASE, [], "linux");
+    expect(fs.allowRead).toContain("/state/sessions/arm");
+    expect(fs.allowRead).toContain("/home/op/.claude");
+    expect(fs.allowWrite).toContain("/state/sessions/arm");
+  });
+
+  test("dedupes a mount equal to the workspace", () => {
+    const mounts: AgentMount[] = [
+      { hostPath: "/state/sessions/arm", mountPath: "/work", mode: "rw" },
+    ];
+    const fs = composeFilesystemView(BASE, mounts, "darwin");
+    expect(fs.allowWrite.filter((p) => p === "/state/sessions/arm")).toHaveLength(1);
+  });
+
+  // The working-directory axis (design 2026-06-16-agent-filesystem-and-sharing.md):
+  // the spec's `workspace` (a shared real dir) is bound rw — readable + writable —
+  // decoupled from the private home (which stays the per-agent session dir).
+  describe("the working dir (workspace) as an rw working-root", () => {
+    test("a working dir is BOTH readable and writable (an rw working-root)", () => {
+      const fs = composeFilesystemView(BASE, undefined, "darwin", true, "/Users/op/Code/repo");
+      expect(fs.allowRead).toContain("/Users/op/Code/repo");
+      expect(fs.allowWrite).toContain("/Users/op/Code/repo");
+    });
+
+    test("the PRIVATE home is ALSO writable alongside the working dir (decoupled, both rw)", () => {
+      const fs = composeFilesystemView(BASE, undefined, "darwin", true, "/Users/op/Code/repo");
+      // The private session dir stays in the write surface (it holds .mcp.json/home/tmp).
+      expect(fs.allowWrite).toContain("/state/sessions/arm");
+      expect(fs.allowWrite).toContain("/Users/op/Code/repo");
+    });
+
+    test("unset working dir → only the private home is writable (today's behavior)", () => {
+      const fs = composeFilesystemView(BASE, undefined, "darwin", true, undefined);
+      expect(fs.allowWrite).toEqual(["/state/sessions/arm"]);
+    });
+
+    test("a blank working dir is ignored (treated as unset)", () => {
+      const fs = composeFilesystemView(BASE, undefined, "darwin", true, "");
+      expect(fs.allowWrite).toEqual(["/state/sessions/arm"]);
+    });
+
+    test("under filesystem 'full' (broad reads) the working dir is still in the write surface", () => {
+      const fs = composeFilesystemView(BASE, undefined, "darwin", false, "/Users/op/Code/repo");
+      expect(fs.denyRead).toEqual([]); // broad reads — no home-tree deny
+      expect(fs.allowWrite).toContain("/Users/op/Code/repo");
+      expect(fs.allowWrite).toContain("/state/sessions/arm");
+    });
+
+    test("a working dir equal to a declared mount dedupes in the write surface", () => {
+      const mounts: AgentMount[] = [{ hostPath: "/Users/op/Code/repo", mountPath: "/repo", mode: "rw" }];
+      const fs = composeFilesystemView(BASE, mounts, "darwin", true, "/Users/op/Code/repo");
+      expect(fs.allowWrite.filter((p) => p === "/Users/op/Code/repo")).toHaveLength(1);
+    });
+  });
+});
+
+describe("sharedMounts — the named cross-session relaxation", () => {
+  test("surfaces only mounts carrying a non-empty `shared` tag", () => {
+    const mounts: AgentMount[] = [
+      { hostPath: "/a", mountPath: "/a", mode: "ro" },
+      { hostPath: "/cache", mountPath: "/cache", mode: "ro", shared: "build-cache" },
+      { hostPath: "/b", mountPath: "/b", mode: "rw", shared: "" },
+    ];
+    const shared = sharedMounts(mounts);
+    expect(shared).toHaveLength(1);
+    expect(shared[0]!.shared).toBe("build-cache");
+  });
+
+  test("a shared mount is still bound like any other (honored in the fs view)", () => {
+    const mounts: AgentMount[] = [
+      { hostPath: "/cache", mountPath: "/cache", mode: "ro", shared: "build-cache" },
+    ];
+    const fs = composeFilesystemView(BASE, mounts, "darwin");
+    expect(fs.allowRead).toContain("/cache");
+  });
+
+  test("empty input → no shared mounts", () => {
+    expect(sharedMounts(undefined)).toEqual([]);
+  });
+});

package/src/sandbox/mounts.ts

@@ -0,0 +1,133 @@
+/**
+ * Filesystem-view composition: scoped reads + write confinement (design §3.1
+ * item 2, §4.5).
+ *
+ * The contract:
+ *
+ *   - WRITES are confined to the private per-session workspace plus any `rw`
+ *     mount the spec declares. The sandbox-runtime's write model is allow-only:
+ *     `allowWrite: [...binds]`, empty = no writes.
+ *
+ *   - READS are scoped to declared binds — a DELIBERATE divergence from
+ *     Anthropic's broad-read default (design §4.5). The runtime's read model is
+ *     deny-then-allow: by default everything is readable. To confine reads we
+ *     DENY the home tree (`/Users` on macOS, `/home` on Linux) and then RE-ALLOW
+ *     exactly the binds (workspace + runtime/config + declared mounts). System
+ *     paths (`/usr`, `/lib`, …) stay readable so `claude` + its toolchain run.
+ *     `allowRead` overrides `denyRead` in the runtime, so the re-allow wins.
+ *
+ * Platform nuance (verified against the runtime README "Path Syntax"):
+ *   - macOS: paths support git-style globs.
+ *   - Linux: literal paths only — no glob matching.
+ * We never synthesize globs; we bind the literal host paths the caller passes,
+ * which is correct on both platforms. The `platform` arg only selects the
+ * home-tree deny root.
+ */
+
+import type { AgentMount, BaseBinds, SandboxPlatform } from "./types.ts";
+
+/** The home-tree root denied for scoped reads, per platform. */
+export function homeTreeDenyRoot(platform: SandboxPlatform): string {
+  return platform === "darwin" ? "/Users" : "/home";
+}
+
+export interface FilesystemView {
+  /** Paths to deny reads under (the home tree) — scoped-read enforcement. */
+  denyRead: string[];
+  /** Paths to re-allow reads within the denied region (the binds). */
+  allowRead: string[];
+  /** Paths writes are confined to (workspace + rw mounts). */
+  allowWrite: string[];
+  /** Paths to deny writes within allowed regions. Empty in v1. */
+  denyWrite: string[];
+}
+
+/**
+ * Compose the filesystem view for an arm from the always-present base binds and
+ * the spec's additive mounts.
+ *
+ * Read surface  = private home (rw) + the working dir (rw, when set) + runtime/
+ *                 config (ro) + every declared mount (ro and rw alike — you can
+ *                 read what you can write).
+ * Write surface = private home (rw) + the working dir (rw, when set) + every
+ *                 `rw` mount.
+ *
+ * `base.workspace` is the agent's PRIVATE per-session home (always rw — it holds
+ * `.mcp.json`/`tmp`/seeded `CLAUDE_CONFIG_DIR`). `workingRoot` is the OPTIONAL
+ * shared real dir the agent works from (the `workspace` spec field, design
+ * 2026-06-16-agent-filesystem-and-sharing.md): when set it's bound rw + readable,
+ * so writes are confined to (private home + working dir + rw mounts). Both are
+ * decoupled — the private home is never the shared dir, so `.mcp.json`'s secrets
+ * stay per-agent even when the working dir is shared.
+ *
+ * The home tree is denied and the read surface re-allowed within it, giving the
+ * scoped-read policy (§4.5). The base binds are always included regardless of
+ * the spec, so a spec cannot strip its own private home or the runtime/config.
+ */
+export function composeFilesystemView(
+  base: BaseBinds,
+  mounts: readonly AgentMount[] | undefined,
+  platform: SandboxPlatform,
+  scopedReads = true,
+  workingRoot?: string,
+): FilesystemView {
+  const declared = mounts ?? [];
+
+  // The private home + the (optional) working dir are readable AND writable;
+  // every other bind is readable, and only rw mounts add to the write surface.
+  const readPaths: string[] = [base.workspace, ...base.runtimeReadOnly];
+  const writePaths: string[] = [base.workspace];
+  if (workingRoot && workingRoot.length > 0) {
+    // The shared working dir is bound rw — the agent's cwd lives here AND it can
+    // write to it (it's effectively an rw mount that is also the cwd). dedupe
+    // below handles the case where it coincides with the private home / a mount.
+    readPaths.push(workingRoot);
+    writePaths.push(workingRoot);
+  }
+
+  for (const m of declared) {
+    readPaths.push(m.hostPath);
+    if (m.mode === "rw") writePaths.push(m.hostPath);
+  }
+
+  // WRITES are confined in BOTH cases (workspace + rw mounts) — the agent never
+  // escapes its workspace or corrupts the operator's files, regardless of read
+  // scope. READS depend on `filesystem`:
+  //   - scopedReads (filesystem "workspace", the DEFAULT): deny the home tree,
+  //     re-allow the read surface within it (workspace + runtime/config + mounts).
+  //     Keeps the operator's secrets (e.g. ~/.parachute/operator.token) unreadable.
+  //   - broad (filesystem "full", explicit opt-in): no deny — claude reads the
+  //     whole disk. (System paths are readable in both.)
+  if (!scopedReads) {
+    return { denyRead: [], allowRead: [], allowWrite: dedupePreserveOrder(writePaths), denyWrite: [] };
+  }
+  return {
+    denyRead: [homeTreeDenyRoot(platform)],
+    allowRead: dedupePreserveOrder(readPaths),
+    allowWrite: dedupePreserveOrder(writePaths),
+    denyWrite: [],
+  };
+}
+
+/**
+ * The cross-session `shared` mounts declared by a spec (design §4.5). v1 honors
+ * them by binding them like any other mount (composeFilesystemView already does);
+ * this helper surfaces them by name so a caller can log/audit the deliberate
+ * cross-session channel. The trust caveat (prefer shared-`ro` from the producer,
+ * never shared-`rw` across a trust boundary) is doc-level for v1.
+ */
+export function sharedMounts(mounts: readonly AgentMount[] | undefined): AgentMount[] {
+  return (mounts ?? []).filter((m) => typeof m.shared === "string" && m.shared.length > 0);
+}
+
+function dedupePreserveOrder(xs: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const x of xs) {
+    if (!seen.has(x)) {
+      seen.add(x);
+      out.push(x);
+    }
+  }
+  return out;
+}

package/src/sandbox/sandbox.test.ts

@@ -0,0 +1,168 @@
+import { describe, test, expect } from "bun:test";
+import { Sandbox, configForSpec, type SandboxEngine } from "./index.ts";
+import type { SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
+import type { AgentSpec, BaseBinds } from "./types.ts";
+import type { EgressBaseInput } from "./egress.ts";
+
+const BASE_BINDS: BaseBinds = { workspace: "/state/sessions/arm", runtimeReadOnly: ["/cfg"] };
+const EGRESS_BASE: EgressBaseInput = { hubOrigin: "https://hub.example.com" };
+
+/** A fake engine that records what it was initialized with + what it wrapped. */
+function fakeEngine(): SandboxEngine & {
+  initializedWith: SandboxRuntimeConfig | null;
+  wrappedCommands: string[];
+  resets: number;
+  calls: string[];
+} {
+  const rec = {
+    initializedWith: null as SandboxRuntimeConfig | null,
+    wrappedCommands: [] as string[],
+    resets: 0,
+    calls: [] as string[],
+    isSupportedPlatform: () => true,
+    isSandboxingEnabled: () => true,
+    async initialize(cfg: SandboxRuntimeConfig) {
+      rec.initializedWith = cfg;
+      rec.calls.push("initialize");
+    },
+    async wrapWithSandboxArgv(command: string) {
+      rec.wrappedCommands.push(command);
+      rec.calls.push("wrap");
+      return {
+        argv: ["/bin/bash", "-c", `SANDBOXED ${command}`],
+        env: { SANDBOX_RUNTIME: "1", HTTP_PROXY: "http://localhost:9999" },
+      };
+    },
+    async reset() {
+      rec.resets += 1;
+      rec.calls.push("reset");
+    },
+  };
+  return rec;
+}
+
+// network "restricted" so the allowedDomains-floor assertion applies; the /Users
+// read-deny applies via the DEFAULT filesystem "workspace" (scoped reads). The
+// open-network default is covered in config.test.ts.
+const SPEC: AgentSpec = {
+  name: "arm",
+  channels: ["ch"],
+  network: "restricted",
+  egress: ["registry.npmjs.org"],
+  mounts: [{ hostPath: "/proj", mountPath: "/work", mode: "rw" }],
+};
+
+describe("Sandbox adapter", () => {
+  test("initializes the engine with the spec-derived config, then wraps the command", async () => {
+    const engine = fakeEngine();
+    const sandbox = new Sandbox(engine);
+    const wrapped = await sandbox.wrap({
+      spec: SPEC,
+      baseBinds: BASE_BINDS,
+      egressBase: EGRESS_BASE,
+      command: "claude --strict-mcp-config",
+      platform: "darwin",
+    });
+
+    // It initialized with the right config (egress floor + scoped reads).
+    expect(engine.initializedWith).not.toBeNull();
+    expect(engine.initializedWith!.network.allowedDomains).toContain("api.anthropic.com");
+    expect(engine.initializedWith!.network.allowedDomains).toContain("registry.npmjs.org");
+    expect(engine.initializedWith!.filesystem.denyRead).toContain("/Users");
+    expect(engine.initializedWith!.filesystem.allowWrite).toContain("/proj");
+
+    // It wrapped exactly the command we passed.
+    expect(engine.wrappedCommands).toEqual(["claude --strict-mcp-config"]);
+
+    // It returns argv + env + the config used.
+    expect(wrapped.argv[0]).toBe("/bin/bash");
+    expect(wrapped.argv[2]).toContain("SANDBOXED claude");
+    expect(wrapped.env.SANDBOX_RUNTIME).toBe("1");
+    expect(wrapped.config).toBe(engine.initializedWith!);
+  });
+
+  test("wrap() RESETS the singleton before initializing (no stale proxy/config leak across spawns)", async () => {
+    const engine = fakeEngine();
+    const sandbox = new Sandbox(engine);
+    await sandbox.wrap({
+      spec: SPEC,
+      baseBinds: BASE_BINDS,
+      egressBase: EGRESS_BASE,
+      command: "claude",
+    });
+    // The order matters: reset → initialize → wrap. Without the leading reset, a
+    // prior spawn's network config (e.g. HTTP_PROXY from a restricted session)
+    // leaks into this wrap and an open session routes to a dead proxy → dies.
+    expect(engine.calls).toEqual(["reset", "initialize", "wrap"]);
+  });
+
+  test("a RESTRICTED-network spawn's proxy env does NOT leak into a later OPEN spawn (the real-bug scenario)", async () => {
+    // A leak-MODELING engine, mirroring the real singleton: `initialize` turns the
+    // proxy on iff the config has an allowlist (restricted network); `wrap` emits
+    // HTTP_PROXY iff the proxy is on; `reset` turns it off. Without the
+    // reset-before-init in Sandbox.wrap, the proxy would still be on from the
+    // restricted spawn and leak into the open spawn's env — exactly the live failure.
+    let proxyOn = false;
+    const engine: SandboxEngine = {
+      isSupportedPlatform: () => true,
+      isSandboxingEnabled: () => true,
+      async initialize(cfg: SandboxRuntimeConfig) {
+        if ((cfg.network as { allowedDomains?: string[] }).allowedDomains) proxyOn = true;
+      },
+      async wrapWithSandboxArgv(command: string) {
+        return { argv: ["/bin/bash", "-c", command], env: proxyOn ? { HTTP_PROXY: "http://localhost:1" } : {} };
+      },
+      async reset() {
+        proxyOn = false;
+      },
+    };
+    const sandbox = new Sandbox(engine);
+    // 1) restricted-network spawn → allowlist present → proxy on, HTTP_PROXY present.
+    const restricted = await sandbox.wrap({ spec: { name: "r", channels: ["c"], network: "restricted" }, baseBinds: BASE_BINDS, egressBase: EGRESS_BASE, command: "claude" });
+    expect(restricted.env.HTTP_PROXY).toBeDefined();
+    // 2) open-network spawn right after (the default) → the per-wrap reset clears the
+    //    proxy, so NO stale HTTP_PROXY leaks in (the bug: claude would route to the
+    //    dead proxy + die).
+    const open = await sandbox.wrap({ spec: { name: "o", channels: ["c"] }, baseBinds: BASE_BINDS, egressBase: EGRESS_BASE, command: "claude" });
+    expect(open.env.HTTP_PROXY).toBeUndefined();
+  });
+
+  test("reset() tears the engine down", async () => {
+    const engine = fakeEngine();
+    const sandbox = new Sandbox(engine);
+    await sandbox.reset();
+    expect(engine.resets).toBe(1);
+  });
+
+  test("isSupportedPlatform delegates to the engine", () => {
+    const engine = fakeEngine();
+    expect(new Sandbox(engine).isSupportedPlatform()).toBe(true);
+  });
+
+  test("SECURITY: a restricted-network spec omitting egress still gets the base floor in the engine config", async () => {
+    const engine = fakeEngine();
+    const sandbox = new Sandbox(engine);
+    await sandbox.wrap({
+      spec: { name: "x", channels: ["c"], network: "restricted" }, // restricted, no egress declared
+      baseBinds: BASE_BINDS,
+      egressBase: EGRESS_BASE,
+      command: "claude",
+      platform: "darwin",
+    });
+    expect(engine.initializedWith!.network.allowedDomains).toContain("api.anthropic.com");
+    expect(engine.initializedWith!.network.allowedDomains).toContain("hub.example.com");
+  });
+});
+
+describe("configForSpec helper", () => {
+  test("builds the config without touching an engine", () => {
+    const cfg = configForSpec({
+      spec: SPEC,
+      baseBinds: BASE_BINDS,
+      egressBase: EGRESS_BASE,
+      platform: "darwin",
+    });
+    expect(cfg.network.allowedDomains).toContain("registry.npmjs.org");
+    expect(cfg.filesystem.allowWrite).toContain("/proj");
+  });
+});