Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
mkdir,
mkdtemp,
readFile,
rm,
symlink,
writeFile,
} from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
createWorkspace,
WorkspaceFileError,
WorkspacePathError,
} from "../src/workspace";
/**
* The confinement, exercised against a real filesystem.
*
* Uses a real temporary directory rather than a mocked fs: two of the three layers of protection here
* only mean anything against real inodes. A symlink test with a fake filesystem tests the fake.
*
* The escape attempts below are the ones an actual attempt would use, in the order it would use them,
* and each one has to be tried with the guard in its shipping configuration. A deny-list test that
* never runs with the escape hatch on proves nothing about the configuration people actually use.
*/
let root: string;
let outside: string;
beforeEach(async () => {
const base = await mkdtemp(join(tmpdir(), "openbot-workspace-"));
root = join(base, "workspace");
outside = join(base, "outside");
await mkdir(root, { recursive: true });
await mkdir(outside, { recursive: true });
await writeFile(join(outside, "secret.txt"), "a private key", "utf8");
});
afterEach(async () => {
await rm(join(root, ".."), { recursive: true, force: true });
});
function workspace() {
return createWorkspace(root);
}
describe("reading and writing inside the workspace", () => {
test("writes a file and reads it back", async () => {
const ws = workspace();
const written = await ws.write("notes.md", "# Findings\nAll good.");
expect(written).toMatchObject({ path: "notes.md", appended: false });
const read = await ws.read("notes.md");
expect(read.text).toBe("# Findings\nAll good.");
expect(read.truncated).toBe(false);
});
test("creates parent directories inside the workspace", async () => {
const ws = workspace();
await ws.write("reports/august/summary.csv", "a,b\n1,2\n");
expect((await ws.read("reports/august/summary.csv")).text).toBe(
"a,b\n1,2\n",
);
});
test("appends when asked, and overwrites when not", async () => {
const ws = workspace();
await ws.write("log.txt", "one\n");
await ws.write("log.txt", "two\n", { append: true });
expect((await ws.read("log.txt")).text).toBe("one\ntwo\n");
await ws.write("log.txt", "fresh\n");
expect((await ws.read("log.txt")).text).toBe("fresh\n");
});
test("a read is bounded and says so", async () => {
const ws = createWorkspace(root, {
readBytes: 10,
writeBytes: 1000,
listEntries: 500,
downloadBytes: 1000,
});
await ws.write("long.txt", "0123456789ABCDEF");
const read = await ws.read("long.txt");
expect(read.text).toBe("0123456789");
expect(read.truncated).toBe(true);
// The true size is reported even though the contents were cut, so the Bot can say so rather
// than believing it has the whole file.
expect(read.bytes).toBe(16);
});
test("a write that exceeds the limit is refused before it touches the disk", async () => {
const ws = createWorkspace(root, {
readBytes: 1000,
writeBytes: 8,
listEntries: 500,
downloadBytes: 1000,
});
await expect(ws.write("big.txt", "far too long")).rejects.toThrow(
WorkspaceFileError,
);
await expect(ws.read("big.txt")).rejects.toThrow();
});
test("reading something that is not there says so plainly", async () => {
await expect(workspace().read("nope.txt")).rejects.toThrow(
WorkspaceFileError,
);
});
test("reading a directory is refused rather than returning nonsense", async () => {
const ws = workspace();
await ws.write("folder/file.txt", "x");
await expect(ws.read("folder")).rejects.toThrow(WorkspaceFileError);
});
});
describe("listing the workspace", () => {
test("lists files and folders, recursively, relative to the root", async () => {
const ws = workspace();
await ws.write("notes.md", "top level");
await ws.write("reports/august/summary.csv", "nested");
const listing = await ws.list();
const paths = listing.entries.map((e) => e.path).sort();
// Folders included, so a Bot can see the shape rather than only the leaves.
expect(paths).toEqual([
"notes.md",
"reports",
"reports/august",
"reports/august/summary.csv",
]);
expect(listing.truncated).toBe(false);
});
test("reports sizes for files and marks folders", async () => {
const ws = workspace();
await ws.write("a/b.txt", "12345");
const byPath = new Map((await ws.list()).entries.map((e) => [e.path, e]));
expect(byPath.get("a")).toMatchObject({ kind: "folder" });
expect(byPath.get("a/b.txt")).toMatchObject({ kind: "file", bytes: 5 });
});
test("an empty workspace lists nothing, rather than failing", async () => {
// The behaviour that matters: a Bot must be able to tell "no files" from "I could not look".
const listing = await workspace().list();
expect(listing.entries).toEqual([]);
});
test("can list a subfolder", async () => {
const ws = workspace();
await ws.write("reports/one.txt", "1");
await ws.write("elsewhere/two.txt", "2");
const paths = (await ws.list("reports")).entries.map((e) => e.path);
expect(paths).toEqual(["reports/one.txt"]);
});
test("listing is bounded and says when it was cut", async () => {
const ws = createWorkspace(root, {
readBytes: 1000,
writeBytes: 1000,
listEntries: 3,
});
for (const n of [1, 2, 3, 4, 5]) await ws.write(`f${n}.txt`, "x");
const listing = await ws.list();
expect(listing.entries).toHaveLength(3);
expect(listing.truncated).toBe(true);
});
test("listing cannot escape the workspace either", async () => {
await expect(workspace().list("../outside")).rejects.toThrow(
WorkspacePathError,
);
await expect(workspace().list("/etc")).rejects.toThrow(WorkspacePathError);
});
test("listing a file rather than a folder says so", async () => {
const ws = workspace();
await ws.write("notes.md", "x");
await expect(ws.list("notes.md")).rejects.toThrow(WorkspaceFileError);
});
});
describe("escaping the workspace", () => {
test.each([
["parent traversal", "../outside/secret.txt"],
["deep traversal", "../../../../etc/passwd"],
["traversal in the middle", "reports/../../outside/secret.txt"],
["absolute path", "/etc/passwd"],
["absolute path into the sibling", "/tmp"],
["backslash traversal", "..\\outside\\secret.txt"],
["bare parent", ".."],
])("refuses %s", async (_label, path) => {
await expect(workspace().read(path)).rejects.toThrow(WorkspacePathError);
await expect(workspace().write(path, "owned")).rejects.toThrow(
WorkspacePathError,
);
});
test("refuses to read THROUGH a symlink that points outside", async () => {
// The layer people miss. This path contains no "..", is not absolute, and resolves inside the
// workspace lexically. Only following the link reveals where it goes.
await symlink(join(outside, "secret.txt"), join(root, "innocent.txt"));
await expect(workspace().read("innocent.txt")).rejects.toThrow(
WorkspacePathError,
);
});
test("refuses to write THROUGH a symlinked directory that points outside", async () => {
await symlink(outside, join(root, "escape"));
await expect(workspace().write("escape/owned.txt", "x")).rejects.toThrow(
WorkspacePathError,
);
});
test("refuses to write THROUGH a symlinked FILE that points outside", async () => {
// The asymmetry between the two tests above. Resolving `dirname` catches a link standing in for a
// directory; a link standing in for the FILE has the workspace as its parent and passes, and then
// `writeFile` follows it. Refusing is only half of what this asserts: the file outside has to be
// untouched afterwards, because an error thrown after the bytes landed would still be an escape.
const secret = join(outside, "secret.txt");
await symlink(secret, join(root, "notes.txt"));
await expect(workspace().write("notes.txt", "owned")).rejects.toThrow(
WorkspacePathError,
);
expect(await readFile(secret, "utf8")).toBe("a private key");
});
test("refuses to append THROUGH a symlinked file that points outside", async () => {
// `append` is a separate flag reaching a separate `writeFile` mode, so it is a separate way in.
const secret = join(outside, "secret.txt");
await symlink(secret, join(root, "log.txt"));
await expect(
workspace().write("log.txt", "owned", { append: true }),
).rejects.toThrow(WorkspacePathError);
expect(await readFile(secret, "utf8")).toBe("a private key");
});
test("refuses to write through a DANGLING link that points outside", async () => {
// The harder half. `realpath` throws on a link whose destination does not exist, so a check built
// on it treats this as "no such file" and lets the write through the failure path, while
// `writeFile` creates the destination regardless. Nothing exists here to prove the escape with,
// so the assertion is that the file was never created outside.
const notThere = join(outside, "planted.txt");
await symlink(notThere, join(root, "fresh.txt"));
await expect(workspace().write("fresh.txt", "owned")).rejects.toThrow(
WorkspacePathError,
);
await expect(readFile(notThere, "utf8")).rejects.toThrow();
});
test("refuses a chain of links that ends up outside", async () => {
// One hop is the obvious case and the only one a single `readlink` would catch.
await symlink(join(outside, "secret.txt"), join(root, "second.txt"));
await symlink(join(root, "second.txt"), join(root, "first.txt"));
await expect(workspace().write("first.txt", "owned")).rejects.toThrow(
WorkspacePathError,
);
expect(await readFile(join(outside, "secret.txt"), "utf8")).toBe(
"a private key",
);
});
test("refuses a cycle of links rather than following it forever", async () => {
// Two links pointing at each other never reach something that is not a link. The walk has to stop
// on its own and say why, instead of spinning or surfacing an ELOOP from the write.
await symlink(join(root, "b.txt"), join(root, "a.txt"));
await symlink(join(root, "a.txt"), join(root, "b.txt"));
await expect(workspace().write("a.txt", "owned")).rejects.toThrow(
WorkspacePathError,
);
});
test("writing THROUGH a link that points back inside still works", async () => {
// Confining, not forbidding, on the write side too. Refusing every link would pass the tests
// above and quietly break a Bot that keeps `latest.csv` pointing at the newest report.
const ws = workspace();
await ws.write("real/data.txt", "before");
await symlink(join(root, "real/data.txt"), join(root, "alias.txt"));
await ws.write("alias.txt", "after");
expect((await ws.read("real/data.txt")).text).toBe("after");
});
test("a symlink pointing back INSIDE the workspace still works", async () => {
// The guard must confine, not merely forbid symlinks: refusing every link would be easier and
// would break legitimate use.
const ws = workspace();
await ws.write("real/data.txt", "inside");
await symlink(join(root, "real"), join(root, "alias"));
expect((await ws.read("alias/data.txt")).text).toBe("inside");
});
test("a sibling directory sharing the root's name prefix is still outside", async () => {
// `/tmp/x/workspace-evil` shares a string prefix with `/tmp/x/workspace`, so a containment check
// written with startsWith would let it through.
const evil = `${root}-evil`;
await mkdir(evil, { recursive: true });
await writeFile(join(evil, "loot.txt"), "nope", "utf8");
await expect(
workspace().read("../workspace-evil/loot.txt"),
).rejects.toThrow(WorkspacePathError);
});
test("an empty or blank path is refused", async () => {
await expect(workspace().read("")).rejects.toThrow(WorkspacePathError);
await expect(workspace().write(" ", "x")).rejects.toThrow(
WorkspacePathError,
);
});
});