Skip to content

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.

16.8 KB
Raw Blame
/**
 * The Bot's files, and the boundary they must not escape.
 *
 * The computer has a `/workspace` volume so that anything a Bot should still have next week
 * survives the container. A Bot can read and write in it, which turns a durable directory into an
 * attack surface: the process runs as root inside its container, so `write_file("../../etc/passwd")`
 * is the obvious first thing to try and `read_file("../../root/.ssh/id_rsa")` the second.
 *
 * Path confinement is enforced in three layers:
 *
 *  1. Absolute paths are refused outright. A Bot names a file relative to its own workspace; there is
 *     no legitimate request that begins with `/`.
 *  2. The resolved path must be inside the root lexically. This catches `..` traversal.
 *  3. The resolved path must still be inside the root after symlinks are followed. This is the layer
 *     people miss: a symlink placed inside the workspace (by an earlier write, or by a page the Bot
 *     downloaded something from) passes the lexical check and then points anywhere on the filesystem.
 *     For a write, the file may not exist yet, so the deepest existing ancestor gets resolved, which
 *     is the directory the write will land in, AND the name itself is resolved when something is
 *     already there, because `writeFile` follows a link at the last component too.
 *
 * A factory taking its root as an argument rather than reading the environment, so the confinement
 * can be tested against a temporary directory instead of being taken on trust.
 */
import {
  lstat,
  mkdir,
  readdir,
  readFile,
  readlink,
  realpath,
  stat,
  writeFile,
} from "node:fs/promises";
import {
  basename,
  dirname,
  isAbsolute,
  join,
  relative,
  resolve,
  sep,
} from "node:path";

export class WorkspacePathError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "WorkspacePathError";
  }
}

export class WorkspaceFileError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "WorkspaceFileError";
  }
}

export class WorkspaceFileNotFoundError extends WorkspaceFileError {}

export class WorkspaceFileTooLargeError extends WorkspaceFileError {}

export type WorkspaceLimits = {
  /**
   * Most bytes a read hands back.
   *
   * Bounded for the same reason page text is: the contents go into a model's context, and one large
   * file would push the rest of the conversation out of it.
   */
  readBytes: number;
  /** Most bytes a single write accepts, so a loop cannot fill the volume. */
  writeBytes: number;
  /** Most entries a listing describes, so a Bot cannot paste a whole disk into its own context. */
  listEntries: number;
  /** Most bytes one download may stream, so a large artifact cannot exhaust the connection. */
  downloadBytes: number;
};

/**
 * One thing in the workspace. Folders included so a Bot can see the shape, not just the leaves.
 *
 * Mirrors `WorkspaceEntry` in the server's published contract (`server/src/computer/schema.ts`), the
 * same way `SnapshotElement` does. Duplicated rather than shared because this process is a separate
 * deployable with no code in common with the server; the two must be changed together, and a field
 * added here and not there is invisible until a Bot asks for it.
 */
export type WorkspaceEntry = {
  /** Relative to the workspace root, which is the only form a request may use. */
  path: string;
  kind: "file" | "folder";
  bytes?: number;
};

export const DEFAULT_WORKSPACE_LIMITS: WorkspaceLimits = {
  readBytes: 64_000,
  writeBytes: 1_000_000,
  listEntries: 500,
  downloadBytes: 100 * 1024 * 1024,
};

export function createWorkspace(
  rootPath: string,
  limits: WorkspaceLimits = DEFAULT_WORKSPACE_LIMITS,
) {
  /**
   * Turn a Bot's requested path into a real one inside the workspace, or refuse.
   *
   * `forWrite` changes only which part of the path must already exist: a read resolves the file
   * itself, a write resolves the directory it would be created in.
   */
  async function resolvePath(
    requested: string,
    forWrite: boolean,
  ): Promise<string> {
    if (typeof requested !== "string" || !requested.trim()) {
      throw new WorkspacePathError("A file path is required.");
    }
    const wanted = requested.trim();

    if (isAbsolute(wanted)) {
      throw new WorkspacePathError(
        "Use a path relative to your workspace, not an absolute one.",
      );
    }
    // Refused explicitly rather than left to the containment check, so the Bot is told what it did
    // wrong and can correct it, instead of receiving a generic denial it may retry verbatim.
    if (wanted.split(/[\\/]/).includes("..")) {
      throw new WorkspacePathError(
        "A file path may not contain '..'. You can only reach files inside your own workspace.",
      );
    }

    const root = await realpath(rootPath);
    const target = resolve(root, wanted);
    assertInside(root, target);

    // Layer three. Resolve what exists on disk and check again, because everything above
    // reasons about the path as text and a symlink makes the text a lie.
    const anchor = forWrite ? dirname(target) : target;
    let realAnchor: string;
    try {
      realAnchor = await realpath(anchor);
    } catch {
      if (!forWrite) {
        throw new WorkspaceFileNotFoundError(`There is no file at ${wanted}.`);
      }
      // The parent directory does not exist yet. Walk up to the nearest one that does and verify it,
      // so a write into a new subdirectory is allowed but cannot be aimed through a symlink.
      realAnchor = await nearestExistingAncestor(root, anchor);
    }
    assertInside(root, realAnchor, wanted);

    if (!forWrite) return realAnchor;

    /*
     * Layer three again, for the last component rather than the directory holding it.
     *
     * Containing `dirname(target)` proves where a NEW file would be created. It proves nothing about
     * a name that already exists, and `writeFile` follows a symlink at the last component the same
     * way `readFile` does. A link at `notes.txt` pointing at `/root/.ssh/authorized_keys` passes
     * every check above, having no `..`, not being absolute, and sitting directly in the workspace,
     * and the bytes land outside the volume. The read side already refuses the identical link; the
     * write side was the asymmetry.
     *
     * The link has to get there first, which takes a shell or an archive that was unpacked with one,
     * so this is not a fresh escape for a Bot that already has `run_command`: that Bot can write
     * outside directly. What it is, is a hole in what the gateway can still see. The decision and the
     * audit row are both made against the path as the Bot asked for it, so a rule written for
     * `credentials/` or `*.env` is evaluated against `notes.txt` and never sees the file that gets
     * written, and the row names a file in the workspace that nothing touched. A deployment that
     * denies `run_command` and allows writes is relying on exactly that, and so is one reading the
     * trail afterwards. A permissive workspace is a decision a deployment can make. A trail that
     * describes a different file from the one on disk is not.
     */
    const landing = await writeDestination(target, wanted);
    if (landing === target) return target;

    // A link was followed, so the destination gets the checks the requested path already passed:
    // inside lexically, and inside after the directory holding it is resolved.
    /*
     * The holder is resolved BEFORE either check. `root` is a real path, so comparing it against a
     * destination that still runs through a symlinked ancestor refuses a link that points straight
     * back inside, which is what happens wherever the workspace sits behind one.
     */
    const holder = await realpath(dirname(landing)).catch(() => null);
    if (holder === null) {
      throw new WorkspacePathError(
        `${wanted} points at somewhere that does not exist, so where a write would land cannot be established.`,
      );
    }
    assertInside(root, holder, wanted);
    const resolved = join(holder, basename(landing));
    assertInside(root, resolved, wanted);
    return resolved;
  }

  return {
    resolvePath,

    /**
     * What is in the workspace.
     *
     * Recursive, because a Bot that saved `reports/august/summary.csv` needs to find it again, and a
     * listing that stops at the first level would show a `reports` directory and no way in. Bounded by
     * entry count for the same reason everything else here is bounded.
     */
    async list(requested = "."): Promise<{
      path: string;
      entries: WorkspaceEntry[];
      truncated: boolean;
    }> {
      const root = await realpath(rootPath);
      // "." and "" both mean the workspace itself, which `resolvePath` would reject as a bare relative
      // path with nothing in it. Anything else goes through the same confinement as a read.
      const start =
        requested === "." || requested.trim() === ""
          ? root
          : await resolvePath(requested, false);

      const info = await stat(start).catch(() => null);
      if (!info) {
        throw new WorkspaceFileError(`There is no folder at ${requested}.`);
      }
      if (!info.isDirectory()) {
        throw new WorkspaceFileError(`${requested} is a file, not a folder.`);
      }

      const entries: WorkspaceEntry[] = [];
      let truncated = false;

      const walk = async (dir: string): Promise<void> => {
        if (truncated) return;
        const found = await readdir(dir, { withFileTypes: true });
        for (const item of found) {
          if (entries.length >= limits.listEntries) {
            truncated = true;
            return;
          }
          const full = `${dir}/${item.name}`;
          // Relative to the workspace root, because that is the only form a Bot may name in a request.
          const shown = full.slice(root.length + 1);
          if (item.isDirectory()) {
            entries.push({ path: shown, kind: "folder" });
            await walk(full);
            continue;
          }
          if (!item.isFile()) continue;
          const size = await stat(full).catch(() => null);
          entries.push({
            path: shown,
            kind: "file",
            ...(size ? { bytes: size.size } : {}),
          });
        }
      };

      await walk(start);
      return { path: requested, entries, truncated };
    },

    /** Read a text file. Bounded, and it says when it gave you less than the whole thing. */
    async read(requested: string): Promise<{
      path: string;
      text: string;
      truncated: boolean;
      bytes: number;
    }> {
      const full = await resolvePath(requested, false);
      const info = await stat(full).catch(() => null);
      if (!info) {
        throw new WorkspaceFileError(`There is no file at ${requested}.`);
      }
      if (info.isDirectory()) {
        throw new WorkspaceFileError(
          `${requested} is a directory, not a file.`,
        );
      }

      const buffer = await readFile(full);
      const slice = buffer.subarray(0, limits.readBytes);
      return {
        path: requested,
        // Decoded as UTF-8. A binary file therefore comes back as replacement characters rather
        // than as a base64 blob nothing can read: this tool is for the notes, CSVs and JSON a Bot
        // actually works with, and pretending otherwise would invite it to try images.
        text: slice.toString("utf8"),
        truncated: buffer.byteLength > slice.byteLength,
        bytes: buffer.byteLength,
      };
    },

    /**
     * Open a file as raw bytes for a download.
     *
     * The same `resolvePath` used by text reads enforces the workspace boundary, including symlink
     * resolution. The file is streamed from disk rather than read into a string, so PDFs, images and
     * archives are returned byte-for-byte and the text read limit does not apply.
     */
    async download(requested: string): Promise<{
      path: string;
      name: string;
      bytes: number;
      body: Blob;
    }> {
      const full = await resolvePath(requested, false);
      const info = await stat(full).catch(() => null);
      if (!info) {
        throw new WorkspaceFileNotFoundError(
          `There is no file at ${requested}.`,
        );
      }
      if (!info.isFile()) {
        throw new WorkspaceFileError(`${requested} is not a file.`);
      }
      if (info.size > limits.downloadBytes) {
        throw new WorkspaceFileTooLargeError(
          `That file is ${info.size} bytes and the download limit is ${limits.downloadBytes}.`,
        );
      }

      return {
        path: requested,
        name: basename(requested.replace(/\\/g, "/")) || "download",
        bytes: info.size,
        // Bun serves this file without reading it into memory, and preserves the byte length a
        // ReadableStream response loses. The caller still receives the raw bytes unchanged.
        body: Bun.file(full),
      };
    },

    /** Write a text file, creating parent directories inside the workspace as needed. */
    async write(
      requested: string,
      contents: string,
      options: { append?: boolean } = {},
    ): Promise<{ path: string; bytes: number; appended: boolean }> {
      if (typeof contents !== "string") {
        throw new WorkspaceFileError("The contents to write must be text.");
      }
      const bytes = Buffer.byteLength(contents, "utf8");
      if (bytes > limits.writeBytes) {
        throw new WorkspaceFileError(
          `That is ${bytes} bytes and the limit is ${limits.writeBytes}.`,
        );
      }

      const full = await resolvePath(requested, true);
      await mkdir(dirname(full), { recursive: true });
      await writeFile(full, contents, {
        encoding: "utf8",
        flag: options.append ? "a" : "w",
      });
      return { path: requested, bytes, appended: options.append === true };
    },
  };
}

export type Workspace = ReturnType<typeof createWorkspace>;

/** Containment, as a path comparison that cannot be fooled by a shared prefix. */
function assertInside(root: string, candidate: string, shown?: string): void {
  const rel = relative(root, candidate);
  // `relative` returns "" for the root itself, which is inside. It returns something starting with
  // ".." for anything outside, and an absolute path when the two are on different roots. Comparing
  // with startsWith on the raw strings instead would let "/workspace-evil" pass as "/workspace".
  const outside =
    rel !== "" &&
    (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel));
  if (outside) {
    throw new WorkspacePathError(
      `${shown ?? candidate} is outside your workspace, so it cannot be reached.`,
    );
  }
}

/**
 * How many links a chain may pass through before it is treated as a cycle rather than a path.
 *
 * Linux gives up at 40. Anything approaching this is a loop or a deliberate attempt to make the walk
 * expensive, and neither is a file a Bot needs to write.
 */
const MAX_LINK_HOPS = 32;

/**
 * Where a write to `target` would actually put the bytes.
 *
 * Returns `target` unchanged when nothing is there or what is there is not a link, which is every
 * ordinary write. Only a name that is already a symlink walks.
 *
 * Walked with `lstat` and `readlink` rather than resolved with `realpath`, because `realpath` throws
 * on a DANGLING link and `writeFile` creates the file at its destination regardless. A link aimed at
 * a name that does not exist yet would otherwise escape through the failure path rather than the
 * success one, which is the harder version of the bug to notice.
 *
 * Confining rather than forbidding, the same as the read side. A link that points back inside the
 * workspace keeps working: refusing every link would be easier and would break legitimate use.
 */
async function writeDestination(
  target: string,
  shown: string,
): Promise<string> {
  let current = target;
  for (let hop = 0; hop <= MAX_LINK_HOPS; hop += 1) {
    const entry = await lstat(current).catch(() => null);
    // Nothing there, or something that is not a link. This is where the write lands.
    if (entry === null || !entry.isSymbolicLink()) return current;
    // A relative link is relative to the directory the link sits in, not to the workspace root.
    current = resolve(dirname(current), await readlink(current));
  }
  throw new WorkspacePathError(
    `${shown} is a chain of links that does not settle, so where a write would land cannot be established.`,
  );
}

/** The closest ancestor of `target` that exists, never above `root`. */
async function nearestExistingAncestor(
  root: string,
  target: string,
): Promise<string> {
  let current = target;
  for (;;) {
    try {
      return await realpath(current);
    } catch {
      const parent = dirname(current);
      if (parent === current) {
        // Ran out of path without finding anything. Only reachable if the root itself vanished.
        throw new WorkspacePathError("The workspace directory is missing.");
      }
      assertInside(root, parent);
      current = parent;
    }
  }
}