Skip to content

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

8.8 KB
Raw Blame
/**
 * The pure half of the backend: how a Windows path is spelled inside the distro, which Linux
 * program a Windows argv names, and the bubblewrap profile one policy becomes. No process is
 * started here, so all of it is tested on any host.
 *
 * The profile, in order (bwrap applies mounts in order, and a later one shadows an earlier):
 *
 *   --die-with-parent --unshare-all [--share-net]     namespaces; the network only when allowed
 *   --ro-bind / /  (--bind / / under full access)     the distro itself
 *   --dev /dev --proc /proc
 *   --tmpfs /run                                      WSL's interop sockets are not reachable
 *   --ro-bind-try /run/resolvconf/resolv.conf …       … but name resolution still is (see below)
 *   [writable temp]      --tmpfs /tmp
 *   [confining modes]    --tmpfs /mnt                 every Windows drive hidden …
 *   [exposeWindowsDrives]  --ro-bind /mnt/<d> …       … or shown read-only
 *   [workspace]          --bind | --ro-bind <ws>      the Workspace, at its own /mnt path
 *   [writable roots]     --bind <root> <root>…         the policy's further roots (the scratchpad)
 *   --ro-bind-try /mnt/wsl/resolv.conf …              the file /etc/resolv.conf points at
 *   --remount-ro /mnt                                 the covering tmpfs itself is read-only
 *   [mask-paths]         --tmpfs <dir> | --ro-bind /dev/null <file>
 *
 * Why /mnt is hidden rather than left read-only: under WSL the whole Windows profile arrives at
 * /mnt/c/Users/<name>, credentials and browser data included. A policy that says "write the
 * Workspace" never meant "read the rest of the person's disk", and on Linux the equivalent
 * files belong to the host, not to a mount the distro adds. The setting that shows them
 * read-only exists for a toolchain that has to read something outside the Workspace.
 *
 * Why the tmpfs is remounted read-only: a tmpfs is writable, and bwrap creates the Workspace's
 * parent directories inside it. A write to `/mnt/c/Users/anything` therefore SUCCEEDED, in a
 * file that existed only for that one command and never reached Windows — a denial reported as
 * success, which is worse than a denial. Remounting after the binds makes the covering mount
 * refuse writes (EROFS) while the Workspace bound under it stays writable.
 *
 * Why resolv.conf is bound back: WSL keeps the generated one outside the distro's own root
 * (/mnt/wsl/resolv.conf, or /run/resolvconf/resolv.conf), and /etc/resolv.conf is a symlink to
 * it. Covering /mnt and /run therefore took DNS away — every name failed to resolve while the
 * network itself was reachable. The two candidates are bound back read-only; `-try` because a
 * distro uses one of them, not both.
 */
import path from "node:path";
import type { SandboxPolicy } from "@adelie/core/plugin";

/** Where WSL mounts the Windows drives inside a distro (its default automount root). */
export const MOUNT_ROOT = "/mnt";

/** The generated resolv.conf, bound back through the tmpfs that would otherwise hide it. */
export const RESOLV_MNT = ["--ro-bind-try", "/mnt/wsl/resolv.conf", "/mnt/wsl/resolv.conf"];
export const RESOLV_RUN = [
  "--ro-bind-try",
  "/run/resolvconf/resolv.conf",
  "/run/resolvconf/resolv.conf",
];

/**
 * A Windows path as the distro sees it: `C:\Users\k\ws` → `/mnt/c/Users/k/ws`, and a path into
 * this distro's own filesystem (`\\wsl.localhost\<distro>\home\x`) → `/home/x`. Null for what
 * has no spelling in the distro: a relative path, another distro's files, a network share.
 */
export function toLinuxPath(windowsPath: string, distro?: string): string | null {
  const p = windowsPath.trim();
  if (p.startsWith("/")) return path.posix.normalize(p);
  const drive = /^([A-Za-z]):(?:[\\/](.*))?$/.exec(p);
  if (drive) {
    const rest = (drive[2] ?? "").split(/[\\/]+/).filter((s) => s !== "");
    return [`${MOUNT_ROOT}/${drive[1]!.toLowerCase()}`, ...rest].join("/");
  }
  const unc =
    /^[\\/]{2}(?:\?[\\/]UNC[\\/])?(wsl\.localhost|wsl\$)[\\/]([^\\/]+)(?:[\\/](.*))?$/i.exec(p);
  if (unc && distro !== undefined && unc[2]!.toLowerCase() === distro.toLowerCase()) {
    const rest = (unc[3] ?? "").split(/[\\/]+/).filter((s) => s !== "");
    return `/${rest.join("/")}`;
  }
  return null;
}

/**
 * The Linux program a Windows argv's first element means. The harness resolves its shell on
 * Windows as `bash` (Git Bash on PATH) or a full path to `bash.exe`; inside the distro that is
 * the distro's own bash. Anything else is looked up by its bare name on the distro's PATH —
 * a Windows program cannot run there at all, since interop is off.
 */
export function linuxProgram(command: string): string {
  const base = path.win32.basename(command).replace(/\.exe$/i, "");
  const lower = base.toLowerCase();
  if (lower === "bash") return "/bin/bash";
  if (lower === "sh") return "/bin/sh";
  return base;
}

/** What the profile needs to know about the host besides the policy. */
export interface ProfileHost {
  /** The distro's name, for a Workspace inside its own filesystem. */
  distro: string;
  /** Show every Windows drive read-only instead of hiding them. */
  exposeWindowsDrives: boolean;
  /** The drive letters that exist on this machine (lowercase), for exposing them. */
  drives: readonly string[];
  /** Whether a Windows path is a directory, a file, or nothing (a mask on nothing is skipped). */
  kind: (windowsPath: string) => "dir" | "file" | null;
}

/** The bubblewrap arguments for one policy: everything before `--` and the command. */
export function bwrapArgs(policy: SandboxPolicy, host: ProfileHost): string[] {
  const full = policy.mode === "danger-full-access";
  if (policy.network === "local") {
    // bwrap's empty network namespace also loses the host's loopback, so "localhost only" has
    // no spelling here. The service never routes it here (no network-local dimension); refuse
    // rather than read it as an open network.
    throw new Error("penguin-wsl cannot confine to the local network (localhost only)");
  }
  const args = ["--die-with-parent", "--unshare-all"];
  if (policy.network !== "none") args.push("--share-net");
  args.push(full ? "--bind" : "--ro-bind", "/", "/", "--dev", "/dev", "--proc", "/proc");
  args.push("--tmpfs", "/run", ...RESOLV_RUN);
  if (policy.writableTemp === true) args.push("--tmpfs", "/tmp");
  if (!full) {
    const workspace = toLinuxPath(policy.workspaceRoot, host.distro);
    if (workspace === null) {
      throw new Error(
        `penguin-wsl: the Workspace ${policy.workspaceRoot} has no path inside the WSL distro ` +
          "(it must be on a local drive), so it cannot be confined there.",
      );
    }
    args.push("--tmpfs", MOUNT_ROOT);
    if (host.exposeWindowsDrives) {
      for (const d of host.drives)
        args.push("--ro-bind", `${MOUNT_ROOT}/${d}`, `${MOUNT_ROOT}/${d}`);
    }
    args.push(policy.mode === "workspace-write" ? "--bind" : "--ro-bind", workspace, workspace);
    // The policy's further writable roots (the Session's scratchpad), where the distro can
    // reach them: one that cannot be reached is left out, which confines more narrowly
    // rather than more widely.
    if (policy.mode === "workspace-write") {
      for (const root of policy.writableRoots ?? []) {
        const linux = toLinuxPath(root, host.distro);
        if (linux !== null && !within(linux, [workspace])) args.push("--bind", linux, linux);
      }
    }
    // Last over /mnt, and only now: the binds above need a writable tmpfs to create their
    // mountpoints in, and the remount is what stops a write outside the Workspace from
    // "succeeding" into a tmpfs nobody ever reads.
    args.push(...RESOLV_MNT, "--remount-ro", MOUNT_ROOT);
  }
  for (const target of policy.maskPaths ?? []) {
    const kind = host.kind(target);
    const linux = toLinuxPath(target, host.distro);
    if (kind === null || linux === null) continue;
    if (kind === "dir") args.push("--tmpfs", linux);
    else args.push("--ro-bind", "/dev/null", linux);
  }
  return args;
}

/**
 * The directories a confined command may start in: a cwd outside every one of them does not
 * exist inside the sandbox, and bwrap refuses a `--chdir` there.
 */
export function chdirRoots(policy: SandboxPolicy, host: ProfileHost): string[] {
  if (policy.mode === "danger-full-access") return ["/"];
  if (host.exposeWindowsDrives) return host.drives.map((d) => `${MOUNT_ROOT}/${d}`);
  const workspace = toLinuxPath(policy.workspaceRoot, host.distro);
  return workspace === null ? [] : [workspace];
}

/** Whether a Linux path is one of the roots or inside one. */
export function within(linuxPath: string, roots: readonly string[]): boolean {
  return roots.some(
    (root) => root === "/" || linuxPath === root || linuxPath.startsWith(`${root}/`),
  );
}

/** A line WSL itself writes to stderr before the command runs, which is not the command's. */
export function isWslNotice(line: string): boolean {
  return /^wsl: /i.test(line) && /(proxy|localhost|代理)/i.test(line);
}