@illuminis/comprism 0.1.2 → 0.1.4

package/out/executor/sandbox.js

@@ -0,0 +1,299 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Sandbox = void 0;
+exports.availability = availability;
+exports.hostAllowed = hostAllowed;
+/**
+ * Commands run inside the operating system's sandbox (manual 4.12).
+ *
+ * The service decides whether a job is sandboxed and which internet addresses
+ * are allowed; this file only adapts the facility the operating system
+ * provides, which the service cannot reach:
+ *
+ * - macOS: `sandbox-exec` with a generated profile. Writes are allowed only in
+ *   the project, the added folders and the temporary folders. The network is
+ *   closed except to this machine, where a small gatekeeper answers as the
+ *   command's web proxy and lets through only the allowed addresses.
+ * - Linux: bubblewrap (`bwrap`). The whole machine is mounted read only except
+ *   the project, the added folders and the temporary folder, and the command
+ *   gets a network of its own with nothing on it. A small relay inside that
+ *   network passes web traffic to the same gatekeeper, through a socket file,
+ *   so only the allowed addresses are reached there too.
+ *
+ * Anywhere else `--sandbox` refuses to start rather than running without it.
+ * A blocked attempt is reported as blocked by the sandbox, which is different
+ * from refused by the person or by a rule.
+ */
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const http = __importStar(require("http"));
+const net = __importStar(require("net"));
+const os = __importStar(require("os"));
+const self_1 = require("../lib/self");
+/** Which sandbox this machine offers, or why none. */
+function availability() {
+    const has = (file, args) => {
+        try {
+            (0, child_process_1.execFileSync)(file, args, { stdio: "ignore", timeout: 5000 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (process.platform === "darwin") {
+        return fs.existsSync("/usr/bin/sandbox-exec")
+            ? { system: "macOS", why: "" }
+            : { system: null, why: "the macOS sandbox (sandbox-exec) is not on this machine" };
+    }
+    if (process.platform === "linux") {
+        if (!has("bwrap", ["--version"])) {
+            return { system: null, why: "bubblewrap (bwrap) is not installed; install it to use --sandbox" };
+        }
+        // A working sandbox, not merely an installed one: some systems forbid the
+        // namespaces bubblewrap needs.
+        return has("bwrap", ["--ro-bind", "/", "/", "--unshare-net", "true"])
+            ? { system: "Linux", why: "" }
+            : { system: null, why: "bubblewrap is installed but this system does not let it start" };
+    }
+    return { system: null, why: `there is no supported sandbox on ${process.platform}` };
+}
+function real(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+function quote(p) {
+    return `"${p.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+/** Does this host match an allowed address: exact, or `*.example.com`. */
+function hostAllowed(host, allow) {
+    const h = host.toLowerCase().replace(/\.$/, "");
+    return allow.some((raw) => {
+        const a = raw.toLowerCase().trim();
+        if (!a)
+            return false;
+        if (a === "*")
+            return true;
+        if (a.startsWith("*."))
+            return h.endsWith(a.slice(1)) || h === a.slice(2);
+        return h === a;
+    });
+}
+/** The port the relay listens on inside a Linux sandbox's own network. Any
+ *  port would do: that network holds nothing else. */
+const LINUX_RELAY_PORT = 18080;
+/** The relay, run by the same Node inside the sandbox: every connection to
+ *  its port is passed to the gatekeeper's socket file, and it marks itself
+ *  ready once listening. It decides nothing. */
+const RELAY = [
+    'const net=require("net"),fs=require("fs");',
+    "net.createServer((c)=>{const u=net.connect(process.env.COMPRISM_GATE);",
+    'c.pipe(u);u.pipe(c);u.on("error",()=>c.destroy());c.on("error",()=>u.destroy());})',
+    `.listen(${LINUX_RELAY_PORT},"127.0.0.1",()=>fs.writeFileSync(process.env.COMPRISM_READY,""));`,
+].join("");
+class Sandbox {
+    system;
+    writable;
+    allow = [];
+    proxy = null;
+    port = 0;
+    /** Hosts refused since the last `takeBlocked`, for the result to name. */
+    blocked = [];
+    constructor(system, root, added) {
+        this.system = system;
+        // This user's own temporary folder and the system one, and no wider: the
+        // parent of a user's temporary folder holds other programs' caches.
+        const tmp = [os.tmpdir(), "/tmp", "/var/tmp"];
+        this.writable = [...new Set([root, ...added, ...tmp].map(real))];
+    }
+    /** The allowed internet addresses, as the service sent them. */
+    setAllowed(allow) {
+        this.allow = allow.filter((a) => typeof a === "string" && a.trim());
+    }
+    /** Where the gatekeeper listens on Linux: a socket file the relay inside
+     *  the sandbox connects to, and a folder for the relay's ready marks. */
+    socketPath = "";
+    marks = "";
+    calls = 0;
+    /** Start the gatekeeper. Idempotent. */
+    async start() {
+        if (this.proxy)
+            return;
+        const server = http.createServer((req, res) => {
+            // A plain http:// request through the proxy.
+            let target;
+            try {
+                target = new URL(req.url ?? "");
+            }
+            catch {
+                res.writeHead(400);
+                res.end();
+                return;
+            }
+            if (!hostAllowed(target.hostname, this.allow)) {
+                this.blocked.push(target.hostname);
+                res.writeHead(403, { "content-type": "text/plain" });
+                res.end(`blocked by the sandbox: network access to ${target.hostname} is not allowed\n`);
+                return;
+            }
+            const upstream = http.request(target, { method: req.method, headers: req.headers }, (up) => {
+                res.writeHead(up.statusCode ?? 502, up.headers);
+                up.pipe(res);
+            });
+            upstream.on("error", () => { res.writeHead(502); res.end(); });
+            req.pipe(upstream);
+        });
+        server.on("connect", (req, client, head) => {
+            // https:// and anything else tunnelled with CONNECT host:port.
+            const [host, portText] = String(req.url ?? "").split(":");
+            if (!host || !hostAllowed(host, this.allow)) {
+                if (host)
+                    this.blocked.push(host);
+                client.end("HTTP/1.1 403 Forbidden\r\n\r\n");
+                return;
+            }
+            const upstream = net.connect(Number(portText) || 443, host, () => {
+                client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+                if (head.length)
+                    upstream.write(head);
+                upstream.pipe(client);
+                client.pipe(upstream);
+            });
+            upstream.on("error", () => client.destroy());
+            client.on("error", () => upstream.destroy());
+        });
+        if (this.system === "Linux") {
+            // A socket file in the temporary folder, which the sandbox can see.
+            this.marks = fs.mkdtempSync(`${real(os.tmpdir())}/comprism-gate-`);
+            this.socketPath = `${this.marks}/gate.sock`;
+            await new Promise((resolve) => server.listen(this.socketPath, () => resolve()));
+        }
+        else {
+            await new Promise((resolve) => server.listen(0, "127.0.0.1", () => resolve()));
+            this.port = server.address().port;
+        }
+        this.proxy = server;
+        server.unref();
+    }
+    close() {
+        this.proxy?.close();
+        this.proxy = null;
+        if (this.marks)
+            fs.rmSync(this.marks, { recursive: true, force: true });
+        this.marks = "";
+    }
+    /** The hosts refused since the last call. */
+    takeBlocked() {
+        const out = [...new Set(this.blocked)];
+        this.blocked = [];
+        return out;
+    }
+    profile() {
+        const writes = this.writable.map((p) => `  (subpath ${quote(p)})`).join("\n");
+        return [
+            "(version 1)",
+            "(allow default)",
+            "(deny file-write*)",
+            "(allow file-write*",
+            writes,
+            '  (literal "/dev/null") (literal "/dev/zero") (literal "/dev/stdout")',
+            '  (literal "/dev/stderr") (literal "/dev/dtracehelper")',
+            '  (regex #"^/dev/tty") (regex #"^/dev/fd/"))',
+            "(deny network*)",
+            '(allow network* (remote ip "localhost:*"))',
+            '(allow network* (local ip "localhost:*"))',
+        ].join("\n");
+    }
+    /** The program and arguments that run `command` inside the sandbox, and
+     *  the variables that send its web traffic to the gatekeeper. */
+    wrap(command, cwd) {
+        if (this.system === "macOS") {
+            const proxy = `http://127.0.0.1:${this.port}`;
+            return {
+                file: "/usr/bin/sandbox-exec",
+                args: ["-p", this.profile(), "/bin/sh", "-c", command],
+                env: {
+                    HTTP_PROXY: proxy, HTTPS_PROXY: proxy, http_proxy: proxy, https_proxy: proxy,
+                    ALL_PROXY: proxy, all_proxy: proxy, NO_PROXY: "", no_proxy: "",
+                },
+            };
+        }
+        const binds = this.writable.filter((p) => fs.existsSync(p)).flatMap((p) => ["--bind", p, p]);
+        // Inside the sandbox's own network, a relay on this port passes every
+        // connection to the gatekeeper's socket file, which decides.
+        const proxy = `http://127.0.0.1:${LINUX_RELAY_PORT}`;
+        const ready = this.marks ? `${this.marks}/ready-${++this.calls}` : "";
+        const script = this.socketPath
+            ? `${(0, self_1.isStandalone)() ? '"$COMPRISM_NODE" __relay' : '"$COMPRISM_NODE" -e "$COMPRISM_RELAY"'} & relay=$!; i=0; `
+                + `while [ ! -e "$COMPRISM_READY" ] && [ $i -lt 150 ]; do sleep 0.02; i=$((i+1)); done; `
+                + `/bin/sh -c "$COMPRISM_CMD"; rc=$?; kill $relay 2>/dev/null; exit $rc`
+            : `/bin/sh -c "$COMPRISM_CMD"`;
+        return {
+            file: "bwrap",
+            args: ["--ro-bind", "/", "/", "--dev", "/dev", "--proc", "/proc", ...binds,
+                "--unshare-net", "--die-with-parent", "--chdir", cwd, "/bin/sh", "-c", script],
+            env: {
+                COMPRISM_CMD: command, COMPRISM_NODE: process.execPath, COMPRISM_RELAY: RELAY,
+                COMPRISM_GATE: this.socketPath, COMPRISM_READY: ready,
+                ...(this.socketPath ? {
+                    HTTP_PROXY: proxy, HTTPS_PROXY: proxy, http_proxy: proxy, https_proxy: proxy,
+                    ALL_PROXY: proxy, all_proxy: proxy, NO_PROXY: "", no_proxy: "",
+                } : {}),
+            },
+        };
+    }
+    /** What was blocked, in the manual's words, or null (manual 4.12). */
+    explain(output, hosts) {
+        if (hosts.length)
+            return `blocked by the sandbox: network access to ${hosts.join(", ")} is not allowed`;
+        const write = /(?:touch: |cannot touch )?'?([^'\n:]+?)'?: (?:Operation not permitted|Read-only file system)/.exec(output);
+        if (write) {
+            return `blocked by the sandbox: writing to ${write[1].trim()} is not allowed, `
+                + "only the project and temporary folders can be written";
+        }
+        const offline = /Could not resolve host: (\S+)|getaddrinfo \w+ (\S+)|Network is unreachable/.exec(output);
+        if (offline) {
+            const host = offline[1] ?? offline[2] ?? "the internet";
+            return `blocked by the sandbox: network access to ${host} is not allowed`;
+        }
+        return null;
+    }
+}
+exports.Sandbox = Sandbox;

package/out/executor/shell.d.ts

@@ -2,8 +2,18 @@ export interface RunResult {
     content: string;
     isError?: boolean;
     summary?: string;
+    /** Counts the service turns into the action line: the lines read, the
+     *  matches found and how many were left out (manual 5.3, 5.4). Numbers only;
+     *  the wording is the service's. */
+    facts?: Record<string, number | string>;
 }
 export declare function safeEnvironment(from?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** The default time limit on a command (manual 5.12). */
+export declare const DEFAULT_TIMEOUT_MS = 120000;
+export declare function keptOutput(n: number): {
+    command: string;
+    text: string;
+} | undefined;
 export interface ShellOptions {
     root: string;
     cwd?: string;
@@ -16,6 +26,14 @@ export interface ShellOptions {
      *  Still filtered by `safeEnvironment`, so a hook cannot be handed a
      *  credential this way either. */
     extraEnv?: Record<string, string>;
+    /** What the command is called in `output N`. */
+    label?: string;
+    /** Written to the command's standard input, then closed. Hooks read their
+     *  details this way (manual 10.9). Absent, standard input is closed. */
+    input?: string;
+    /** The operating system's sandbox, when the service turned it on for this
+     *  job (manual 4.12). Every command then runs inside it. */
+    sandbox?: import("./sandbox").Sandbox;
 }
 /** Run a command and wait for it.
  *
@@ -23,14 +41,41 @@ export interface ShellOptions {
  *  RESULT: it is usually the most useful thing that can happen, because it is
  *  how the agent learns what is wrong.
  */
+/**
+ * The shell a command runs in: the system shell on macOS and Linux, and
+ * PowerShell on Windows (manual 1.2), which is what a Windows developer types
+ * into and what the agent is told it is writing for.
+ */
+export declare function shellFor(command: string): [string, string[], boolean];
 export declare function runCommand(command: string, opts: ShellOptions): Promise<RunResult>;
+/** Run one program with its arguments as a list, and no shell in between.
+ *
+ *  For commands this tool builds itself, such as git. A shell would have to be
+ *  told how to quote each argument, and the quoting differs by shell: the POSIX
+ *  single quotes that kept a commit message whole on macOS and Linux reached
+ *  git on Windows as literal characters, so a commit read `'fix` and a branch
+ *  name no longer matched. With no shell there is nothing to quote, on any
+ *  system, and a model written message cannot become a second command. */
+export declare function runProgram(file: string, args: string[], opts: ShellOptions): Promise<RunResult>;
+/** Stop every foreground command and everything it started. */
+export declare function stopForeground(): void;
 export declare function startBackground(command: string, opts: ShellOptions): RunResult;
 export declare function readOutput(id: string): RunResult;
+/** Stop one process this tool started, and everything it started, by the
+ *  number it was given. Never by name or by port (manual 5.13). */
 export declare function stopProcess(id: string): RunResult;
-/** Everything still running, stopped. Called when a session ends, so a job that
- *  started a dev server does not leave it holding a port after the person has
- *  closed the terminal. */
-export declare function stopEverything(): void;
+/** What this session started and is still tracking, for `processes`. */
+export declare function listProcesses(): Array<{
+    id: string;
+    command: string;
+    running: boolean;
+    seconds: number;
+    port?: number;
+}>;
+/** Everything still running, stopped, and what was stopped. Called when a
+ *  session ends, so a job that started a dev server does not leave it holding
+ *  a port after the person has closed the terminal (manual 5.13). */
+export declare function stopEverything(): string[];
 export declare function guessTestCommand(root: string): string | null;
 export declare function runTests(opts: ShellOptions & {
     command?: string;