Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

11.7 KB
Raw Blame
/**
 * Unit tests for penguin-bwrap: the exact profile it builds for each dimension, and
 * its fail-closed behavior when bubblewrap is unusable. The probe is injected, so both
 * paths are deterministic on any host (a real-bwrap host also runs sandbox-live).
 */
import { describe, expect, it } from "vitest";
import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import path from "node:path";
import {
  bwrapProfileArgs,
  bwrapSettingsOf,
  createPenguinBwrapProvider,
  loadPenguinBwrapProvider,
  vendoredRunner,
} from "../src/index.js";

const ARGV = ["bash", "-lc", "echo hi"] as const;
const WS = "/work/project";

/** argv slice between two markers, for asserting order without pinning the whole array. */
function after(argv: readonly string[], marker: string): readonly string[] {
  return argv.slice(argv.indexOf(marker));
}

describe("penguin-bwrap profile", () => {
  it("read-only: the world is read-only, nothing is writable, no network flag", () => {
    const args = bwrapProfileArgs({ mode: "read-only", workspaceRoot: WS });
    expect(args).toEqual([
      "--ro-bind",
      "/",
      "/",
      "--dev",
      "/dev",
      "--proc",
      "/proc",
      "--die-with-parent",
    ]);
  });

  // skipIf(win32): the profile echoes host path resolution, which turns the POSIX
  // workspace literal into a drive path — and bwrap never runs there anyway.
  it.skipIf(process.platform === "win32")(
    "workspace-write: the workspace becomes writable, and /tmp only when temp is",
    () => {
      const args = bwrapProfileArgs({ mode: "workspace-write", workspaceRoot: WS });
      expect(args.join(" ")).toContain(`--bind ${WS} ${WS}`);
      expect(args).not.toContain("--tmpfs");

      const withTemp = bwrapProfileArgs({
        mode: "workspace-write",
        workspaceRoot: WS,
        writableTemp: true,
      });
      expect(withTemp.join(" ")).toContain("--tmpfs /tmp");
      expect(withTemp.join(" ")).toContain(`--bind ${WS} ${WS}`);
      // /tmp is the tmpfs, never also a bind of the host's /tmp.
      expect(withTemp.join(" ")).not.toContain("--bind /tmp /tmp");
    },
  );

  // skipIf(win32): as above, host path resolution would rewrite the POSIX literals.
  it.skipIf(process.platform === "win32")(
    "workspace-write binds the policy's further roots (the Session's scratchpad) writable; read-only ignores them",
    () => {
      const scratchpad = "/data/agent/scratchpad/session-1";
      const args = bwrapProfileArgs({
        mode: "workspace-write",
        workspaceRoot: WS,
        writableRoots: [scratchpad],
      });
      expect(args.join(" ")).toContain(`--bind ${WS} ${WS}`);
      expect(args.join(" ")).toContain(`--bind ${scratchpad} ${scratchpad}`);

      const readOnly = bwrapProfileArgs({
        mode: "read-only",
        workspaceRoot: WS,
        writableRoots: [scratchpad],
      });
      expect(readOnly).toEqual(bwrapProfileArgs({ mode: "read-only", workspaceRoot: WS }));
    },
  );

  it("read-only with writable temp: a tmpfs /tmp is the only writable place", () => {
    const args = bwrapProfileArgs({ mode: "read-only", workspaceRoot: WS, writableTemp: true });
    expect(args.join(" ")).toContain("--tmpfs /tmp");
    expect(args.join(" ")).not.toContain(`--bind ${WS}`);
  });

  it("refuses the local network level rather than reading it as an open network", () => {
    expect(() =>
      bwrapProfileArgs({ mode: "read-only", workspaceRoot: WS, network: "local" }),
    ).toThrow(/local network/);
  });

  it("full access binds the root read-WRITE, but still cuts the network when asked", () => {
    const args = bwrapProfileArgs({
      mode: "danger-full-access",
      workspaceRoot: WS,
      network: "none",
    });
    // The whole filesystem is writable: --bind / /, never --ro-bind / /.
    expect(args.slice(0, 3)).toEqual(["--bind", "/", "/"]);
    expect(args.join(" ")).not.toContain("--ro-bind / /");
    // The network cut still applies — that is why the policy reached a backend at all.
    expect(args).toContain("--unshare-net");
  });

  it("network: none adds --unshare-net; absent leaves the network alone", () => {
    expect(bwrapProfileArgs({ mode: "read-only", workspaceRoot: WS, network: "none" })).toContain(
      "--unshare-net",
    );
    expect(bwrapProfileArgs({ mode: "read-only", workspaceRoot: WS })).not.toContain(
      "--unshare-net",
    );
  });

  it("mask-paths: a directory becomes an empty tmpfs, a file is shadowed by /dev/null", () => {
    const dir = mkdtempSync(path.join(tmpdir(), "penguin-mask-"));
    const file = path.join(dir, "secret.txt");
    writeFileSync(file, "shh");
    const sub = path.join(dir, "sub");
    mkdirSync(sub);
    try {
      const args = bwrapProfileArgs({
        mode: "read-only",
        workspaceRoot: WS,
        maskPaths: [sub, file],
      });
      expect(args.join(" ")).toContain(`--tmpfs ${sub}`);
      expect(args.join(" ")).toContain(`--ro-bind /dev/null ${file}`);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("mask-paths: a path that does not exist is skipped (nothing to hide)", () => {
    const args = bwrapProfileArgs({
      mode: "read-only",
      workspaceRoot: WS,
      maskPaths: [path.join(tmpdir(), "penguin-definitely-absent-path")],
    });
    expect(args.join(" ")).not.toContain("penguin-definitely-absent-path");
  });

  it("masks come AFTER the read-only bind of / that would otherwise expose them", () => {
    const dir = mkdtempSync(path.join(tmpdir(), "penguin-mask-order-"));
    try {
      const args = bwrapProfileArgs({ mode: "read-only", workspaceRoot: WS, maskPaths: [dir] });
      // bwrap applies mounts in order: the mask must be in the tail after `--ro-bind / /`.
      expect(after(args, "--ro-bind").join(" ")).toContain(`--tmpfs ${dir}`);
      expect(args.indexOf(dir)).toBeGreaterThan(args.indexOf("--die-with-parent"));
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });
});

describe("penguin-bwrap provider", () => {
  it("implements every dimension of the built-in interface", () => {
    expect(createPenguinBwrapProvider({ probe: () => true }).dimensions).toEqual([
      "fs-write",
      "network",
      "mask-paths",
      "closed-temp",
    ]);
  });

  it("wraps the caller's argv behind the profile and a -- separator", () => {
    const provider = createPenguinBwrapProvider({ probe: () => true, runner: "bwrap" });
    const confined = provider.confine([...ARGV], {
      mode: "workspace-write",
      workspaceRoot: WS,
      network: "none",
    });
    expect(confined.argv[0]).toBe("bwrap");
    expect(confined.argv.slice(-3)).toEqual([...ARGV]);
    expect(confined.argv[confined.argv.length - 4]).toBe("--");
    expect(confined.argv).toContain("--unshare-net");
    expect(confined.enforcement).toBe("full");
  });

  it("an unusable bwrap fails closed, and the probe runs once", () => {
    let probes = 0;
    const provider = createPenguinBwrapProvider({
      probe: () => {
        probes++;
        return false;
      },
    });
    const policy = { mode: "read-only", workspaceRoot: WS } as const;
    expect(() => provider.confine([...ARGV], policy)).toThrow(/cannot confine on this host/);
    expect(() => provider.confine([...ARGV], policy)).toThrow(/cannot confine on this host/);
    expect(probes).toBe(1);
  });

  it("reads its settings at each confine, probing each runner once with the timeout set", () => {
    const probed: Array<[number, string]> = [];
    let doc: Record<string, unknown> = {};
    const provider = createPenguinBwrapProvider({
      probe: (timeoutMs, runner) => {
        probed.push([timeoutMs, runner]);
        return runner !== "/missing/bwrap";
      },
      // "" for the shipped binary: this is about the settings, not about what the package carries.
      settings: () => bwrapSettingsOf(doc, ""),
    });
    const policy = { mode: "read-only", workspaceRoot: WS } as const;
    expect(provider.confine([...ARGV], policy).argv[0]).toBe("bwrap");
    doc = { runner: " /opt/bwrap ", probeTimeoutSeconds: 2 };
    expect(provider.confine([...ARGV], policy).argv[0]).toBe("/opt/bwrap");
    expect(provider.confine([...ARGV], policy).argv[0]).toBe("/opt/bwrap");
    doc = { runner: "/missing/bwrap" };
    expect(() => provider.confine([...ARGV], policy)).toThrow(/'\/missing\/bwrap' is missing/);
    expect(probed).toEqual([
      [5000, "bwrap"],
      [2000, "/opt/bwrap"],
      [5000, "/missing/bwrap"],
    ]);
  });
});

describe("bwrap on another platform", () => {
  it("declines off Linux (not a failure), and fails with a reason on Linux it cannot serve", async () => {
    const other = "win32" as const;
    await expect(
      loadPenguinBwrapProvider({ platform: other, probe: () => true }),
    ).resolves.toBeNull();
    await expect(
      loadPenguinBwrapProvider({ platform: "linux", probe: () => false }),
    ).rejects.toThrow(/is missing or refuses/);
    await expect(
      loadPenguinBwrapProvider({ platform: "linux", probe: () => true }),
    ).resolves.toBeDefined();
  });

  it("names the switch of each distribution that gates user namespaces, Ubuntu's included", async () => {
    const rejection = loadPenguinBwrapProvider({ platform: "linux", probe: () => false });
    await expect(rejection).rejects.toThrow(/kernel\.unprivileged_userns_clone/);
    await expect(rejection).rejects.toThrow(/kernel\.apparmor_restrict_unprivileged_userns/);
    // The root step is optional: sandbox-dsh confines files without it.
    await expect(rejection).rejects.toThrow(/sandbox-dsh confines file writes without them/);
    await expect(rejection).rejects.toThrow(/Optional: a one-time root step lets bubblewrap run/);
  });

  it("carries what the runner said, and that it did not start at all", async () => {
    await expect(
      loadPenguinBwrapProvider({
        platform: "linux",
        settings: () => ({ runner: "/nonexistent/bwrap", probeTimeoutMs: 5000 }),
      }),
    ).rejects.toThrow(/'\/nonexistent\/bwrap' is missing or refuses the base profile \(.*ENOENT/);
  });

  it("names itself bubblewrap on the settings card", () => {
    expect(createPenguinBwrapProvider({ probe: () => true }).mechanism).toBe("bubblewrap");
  });

  it("points at the documented step, which is the actionable half on Ubuntu", async () => {
    // Ubuntu's switch alone leaves an operator with nothing to do where no root step has run:
    // the reason has to name where that step is written down (the CLI quickstart's section).
    const rejection = loadPenguinBwrapProvider({ platform: "linux", probe: () => false });
    await expect(rejection).rejects.toThrow(/Sandbox on Ubuntu/);
  });
});

describe("the bwrap it runs", () => {
  it("ships its own, so a host without bubblewrap still confines", () => {
    // The real thing: the package carries a binary for THIS host (scripts/vendor-bwrap.mjs) —
    // on Linux only, the one platform bubblewrap runs on. Elsewhere there is none to carry.
    const shipped = vendoredRunner();
    if (process.platform !== "linux") {
      expect(shipped).toBe("");
      return;
    }
    expect(shipped).toMatch(/vendor[\\/]linux-(x64|arm64)[\\/]bin[\\/]bwrap$/);
    expect(existsSync(shipped)).toBe(true);
  });

  it("carries none for a host it has no binary for, and says so with an empty path", () => {
    expect(vendoredRunner("win32", "x64", () => false)).toBe("");
  });

  it("what the deployment names wins; then the shipped one; then a bwrap on PATH", () => {
    const shipped = "/pkg/vendor/linux-x64/bin/bwrap";
    expect(bwrapSettingsOf({ runner: "/usr/bin/bwrap" }, shipped).runner).toBe("/usr/bin/bwrap");
    expect(bwrapSettingsOf({}, shipped).runner).toBe(shipped);
    expect(bwrapSettingsOf({ runner: "  " }, shipped).runner).toBe(shipped);
    expect(bwrapSettingsOf({}, "").runner).toBe("bwrap");
  });
});