hyperbrane 0.1.2 → 0.2.0

package/dist/sandbox/boatService.js

@@ -1,343 +0,0 @@
-import { createHash } from "node:crypto";
-import { posix } from "node:path";
-import { BoatApi, Configuration, ResponseError, waitUntilReady } from "@boatdev/sdk";
-import { SandboxEndpointError, SandboxNotFoundError, } from "./api.js";
-import { createProxyEndpoints, proxyCredentialsAuth } from "./endpointProxy.js";
-import { endpointRequest, openSseConnection } from "./sseConnection.js";
-/** What the scripts below exit with for a missing path, and for one that exists already. */
-const NOT_FOUND = 44;
-const EXISTS = 45;
-/** Boat's cap on a command. */
-const COMMAND_TIMEOUT_S = 600;
-/** The port the sandbox's endpoint proxy listens on, published by Boat. */
-const DEFAULT_PROXY_PORT = 8900;
-/** States a sandbox runs commands in; stopped and archived ones are resumed. */
-const RUNNING_STATES = ["ready", "idle", "running"];
-export const BOAT_API_URL = "https://boat.dev/api/v1";
-/** Each sandbox's own endpoints (createBoatSandbox's socketEndpoint), by sandbox id, for the life of the process. */
-const OWN_ENDPOINTS = new Map();
-export function createBoatApi(apiKey, basePath = BOAT_API_URL) {
-    return new BoatApi(new Configuration({ basePath, accessToken: apiKey }));
-}
-/** A call to Boat that failed: its HTTP status and Boat's error code. */
-export class BoatError extends Error {
-    status;
-    code;
-    name = "BoatError";
-    constructor(status, code, message) {
-        super(message);
-        this.status = status;
-        this.code = code;
-    }
-}
-async function boat(what, call) {
-    try {
-        return await call();
-    }
-    catch (error) {
-        if (!(error instanceof ResponseError))
-            throw error;
-        const text = await error.response.text().catch(() => "");
-        let code = "";
-        let message = text;
-        try {
-            const body = JSON.parse(text);
-            code = body.code ?? "";
-            message = body.message ?? text;
-        }
-        catch { }
-        throw new BoatError(error.response.status, code, `${what} failed (${error.response.status}${code ? ` ${code}` : ""}): ${message}`);
-    }
-}
-/**
- * A Boat sandbox (https://boat.dev), driven through Boat's API alone (its SDK): files through its
- * file calls, commands through its command call (one shell line, up to 600s), and what needs a
- * stream into the sandbox through the sandbox's own endpoints: `connect` is an "sse" endpoint to
- * the socket, `fetch` an "http" one (so docker's responses stream). Those endpoints, like any the
- * sandbox exposes, sit behind one proxy that Boat publishes on a URL of its own (boatHostPortAuth).
- * Sandbox paths are paths in the sandbox; the sandbox must be running (ensureBoatRunning).
- */
-export function createBoatSandbox(api, sandboxId, { proxyPort = DEFAULT_PROXY_PORT, stateDirectory } = {}) {
-    const where = `Boat sandbox ${sandboxId}`;
-    function full(path) {
-        return posix.resolve("/", path);
-    }
-    /** Runs `command` (one shell line) and returns what it printed; throws if Boat cut its output. */
-    async function run(command) {
-        const result = await boat(`a command in ${where}`, () => api.command({ sandboxId, command, timeoutSeconds: COMMAND_TIMEOUT_S }));
-        if (!("exitCode" in result))
-            throw new Error(`a command in ${where} was started in the background`);
-        if (result.timedOut)
-            throw new Error(`a command in ${where} ran past ${COMMAND_TIMEOUT_S}s`);
-        if (result.stdoutTruncated || result.stderrTruncated)
-            throw new Error(`Boat cut the output of a command in ${where} short`);
-        return { exitCode: result.exitCode ?? -1, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
-    }
-    /** `script` in sh, with `args` as $1, $2, ... */
-    function sh(script, ...args) {
-        return run(["sh", "-c", script, "sh", ...args].map(quote).join(" "));
-    }
-    function check(result, what, path) {
-        if (result.exitCode === NOT_FOUND)
-            throw new SandboxNotFoundError(`Not found: "${path}"`);
-        if (result.exitCode !== 0)
-            throw new Error(`${what} ${path} in ${where} failed (exit ${result.exitCode}): ${result.stderr.trim()}`);
-    }
-    /** Puts `data` in a new file under /tmp through Boat's file call and returns its path. */
-    async function upload(data) {
-        const path = `/tmp/.hyb-${crypto.randomUUID()}`;
-        const content = Buffer.from(typeof data === "string" ? new TextEncoder().encode(data) : data).toString("base64");
-        await boat(`writing to ${where}`, () => api.writeFile({ sandboxId, path, content, encoding: "base64" }));
-        return path;
-    }
-    async function readFile(path) {
-        const target = full(path);
-        try {
-            const read = await boat(`reading ${target} in ${where}`, () => api.readFile({ sandboxId, path: target, encoding: "base64" }));
-            return new Uint8Array(Buffer.from(read.content ?? "", "base64"));
-        }
-        catch (error) {
-            // Boat passes the sandbox's own error on: 400 sandbox_direct_failed, "ENOENT: ...".
-            if (error instanceof BoatError && /ENOENT/.test(error.message))
-                throw new SandboxNotFoundError(`Not found: "${path}"`);
-            throw error;
-        }
-    }
-    // Boat's file call reads whole files only.
-    async function readFileRange(path, start, end) {
-        const target = full(path);
-        const result = await sh(`[ -e "$1" ] || exit ${NOT_FOUND}; tail -c +$(($2 + 1)) -- "$1" | head -c "$3" | base64 -w0`, target, String(start), String(Math.max(0, end - start)));
-        check(result, "read", target);
-        return new Uint8Array(Buffer.from(result.stdout, "base64"));
-    }
-    /**
-     * Uploads `data`, copies it beside `target` (creating its directory) and runs `publish` on the copy
-     * ($3) and the target ($2), so readers never see part of it.
-     */
-    async function place(target, data, publish) {
-        const uploaded = await upload(data);
-        const beside = posix.join(posix.dirname(target), `.${posix.basename(target)}.${crypto.randomUUID()}.tmp`);
-        return sh(`mkdir -p -- "$(dirname -- "$2")" && cp -- "$1" "$3" || { rm -f -- "$1" "$3"; exit 1; }\nrm -f -- "$1"\n${publish}`, uploaded, target, beside);
-    }
-    async function writeFile(path, data) {
-        const target = full(path);
-        check(await place(target, data, 'mv -f -- "$3" "$2" || { rm -f -- "$3"; exit 1; }'), "write", target);
-    }
-    // A hard link refuses to replace an existing file.
-    async function writeFileExclusive(path, data) {
-        const target = full(path);
-        const result = await place(target, data, `if ln -- "$3" "$2" 2>/dev/null; then rm -f -- "$3"; exit 0; fi; rm -f -- "$3"; [ -e "$2" ] && exit ${EXISTS}; exit 1`);
-        if (result.exitCode === EXISTS)
-            return false;
-        check(result, "write", target);
-        return true;
-    }
-    async function removeFile(path) {
-        check(await sh('rm -f -- "$1"', full(path)), "remove", full(path));
-    }
-    async function createDirectory(path) {
-        check(await sh('mkdir -p -- "$1"', full(path)), "mkdir", full(path));
-    }
-    async function removeDirectory(path) {
-        check(await sh('rm -rf -- "$1"', full(path)), "remove", full(path));
-    }
-    async function listDirectory(path) {
-        const result = await sh(`[ -e "$1" ] || exit ${NOT_FOUND}; ls -A1 -- "$1"`, full(path));
-        check(result, "list", full(path));
-        return result.stdout.split("\n").filter(Boolean);
-    }
-    async function stat(path) {
-        const result = await sh(`[ -e "$1" ] || exit ${NOT_FOUND}; stat -c '%u:%g:%s:%F' -- "$1"`, full(path));
-        check(result, "stat", full(path));
-        const [uid = "", gid = "", size = "", kind = ""] = result.stdout.trim().split(":");
-        const type = kind === "directory" ? "directory" : kind.startsWith("regular") ? "file" : "other";
-        return { type, uid: Number(uid), gid: Number(gid), size: Number(size) };
-    }
-    let home = null;
-    function homeDirectory() {
-        home ??= sh('printf %s "$HOME"').then((result) => {
-            check(result, "home of", "the user");
-            return result.stdout || "/";
-        });
-        home.catch(() => (home = null));
-        return home;
-    }
-    // stdin goes up as a file first: Boat's command call takes none.
-    async function runCommand(cmd, { cwd, env = {}, stdin } = {}) {
-        const input = stdin === undefined ? null : await upload(stdin);
-        const words = ["env", ...Object.entries(env).map(([name, value]) => `${name}=${value}`), ...cmd].map(quote).join(" ");
-        const enter = cwd === undefined ? "" : `cd ${quote(full(cwd))} && `;
-        const line = `${enter}${words} < ${input === null ? "/dev/null" : quote(input)}`;
-        return run(["sh", "-c", input === null ? line : `${line}; status=$?; rm -f -- ${quote(input)}; exit $status`].map(quote).join(" "));
-    }
-    const endpoints = createProxyEndpoints({ runCommand }, { accessibleHost: `${sandboxId}.on.boat.dev:${proxyPort}`, auth: boatHostPortAuth(api, sandboxId), stateDirectory }, where);
-    // The sandbox's own endpoints to its sockets, by socket and transport: the same record (and URL)
-    // whichever sandbox object asks, so they don't pile up, and held by the process (OWN_ENDPOINTS) so
-    // a sandbox object made for each request doesn't set them up again; exposed again when they stop
-    // answering.
-    function socketEndpoint(path, transport, fresh = false) {
-        const key = `${transport}:${path}`;
-        const ownEndpoints = OWN_ENDPOINTS.get(sandboxId) ?? new Map();
-        OWN_ENDPOINTS.set(sandboxId, ownEndpoints);
-        if (fresh)
-            ownEndpoints.delete(key);
-        let endpoint = ownEndpoints.get(key);
-        if (!endpoint) {
-            const request = { target: { unix: path }, scheme: "bearer", transport };
-            endpoint = endpoints.exposeEndpointAs(nameFor(key), request);
-            endpoint.catch(() => ownEndpoints.delete(key));
-            ownEndpoints.set(key, endpoint);
-        }
-        return endpoint;
-    }
-    /**
-     * The endpoint to retry exposing: Boat's front answers 502-504 for a proxy that isn't listening (a
-     * resume restarted the machine), the proxy 401 for credentials since replaced (docker never does).
-     */
-    const stale = (status) => status === 401 || status === 502 || status === 503 || status === 504;
-    async function fetchInside(url, { unix, signal, timeout: _timeout, ...init } = {}) {
-        if (unix === undefined)
-            throw new Error("the Boat sandbox fetches only over unix sockets (init.unix)");
-        const target = new URL(url);
-        const path = full(unix);
-        const attempt = async (fresh) => {
-            const [requestUrl, requestInit] = endpointRequest(await socketEndpoint(path, "http", fresh), `${target.pathname}${target.search}`, { ...init, signal });
-            return fetch(requestUrl, requestInit);
-        };
-        try {
-            const response = await attempt(false);
-            if (!stale(response.status))
-                return response;
-            await response.body?.cancel();
-        }
-        catch (error) {
-            if (signal?.aborted)
-                throw error;
-        }
-        return attempt(true);
-    }
-    async function connect(path) {
-        const socket = full(path);
-        try {
-            return await openSseConnection(await socketEndpoint(socket, "sse"));
-        }
-        catch {
-            return openSseConnection(await socketEndpoint(socket, "sse", true));
-        }
-    }
-    // Boat archives the sandbox when its TTL runs out (60 minutes after creation unless set).
-    async function getExpiration() {
-        const { sandbox } = await boat(`reading ${where}`, () => api.get({ sandboxId }));
-        return sandbox.archiveAfter ? new Date(sandbox.archiveAfter) : null;
-    }
-    async function setExpiration(seconds) {
-        if (seconds !== null && !(Number.isInteger(seconds) && seconds > 0))
-            throw new Error(`not a number of seconds: ${seconds}`);
-        const { sandbox } = await boat(`setting when ${where} stops`, () => api.update({ sandboxId, ttlSeconds: seconds }));
-        return sandbox.archiveAfter ? new Date(sandbox.archiveAfter) : null;
-    }
-    return {
-        getExpiration,
-        setExpiration,
-        readFile,
-        readFileRange,
-        writeFile,
-        writeFileExclusive,
-        removeFile,
-        createDirectory,
-        removeDirectory,
-        listDirectory,
-        stat,
-        homeDirectory,
-        runCommand,
-        fetch: fetchInside,
-        connect,
-        ...endpoints,
-    };
-}
-/**
- * Endpoints published by Boat: the proxy listens on the accessible host's port inside the sandbox
- * and checks the bearer or basic credentials it mints per endpoint (proxyCredentialsAuth), and
- * Boat's hostPort makes that port public, with Boat's TLS, on a URL of its own:
- * https://<sandbox>-<port>.on.boat.dev. Boat's own guard for a port (a token it trades for a
- * cookie) isn't used: a client can't carry it through a POST, nor a browser keep it across sites.
- */
-export function boatHostPortAuth(api, sandboxId) {
-    return {
-        bind(accessible) {
-            if (accessible.port === null)
-                throw new SandboxEndpointError("Boat endpoints need a fixed port: the one Boat publishes");
-            const own = proxyCredentialsAuth().bind(accessible);
-            let published = null;
-            const publish = (port) => {
-                published ??= boat(`publishing port ${port} of Boat sandbox ${sandboxId}`, () => api.hostPort({ sandboxId, port, _public: true })).then((hosted) => new URL(hosted.url ?? "").origin);
-                published.catch(() => (published = null));
-                return published;
-            };
-            return {
-                // Boat opens the sandbox's firewall for the port itself.
-                firewall: false,
-                plan(request) {
-                    const plan = own.plan(request);
-                    return {
-                        ...plan,
-                        publish: async (port) => ({ url: await publish(port), credentials: (await plan.publish(port)).credentials }),
-                    };
-                },
-            };
-        },
-    };
-}
-/** A UUID-shaped name of `key`'s own, for an endpoint the sandbox keeps for itself. */
-function nameFor(key) {
-    const hex = createHash("sha256").update(key).digest("hex");
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
-}
-/** Quotes a word for a POSIX shell. */
-function quote(word) {
-    return `'${word.replaceAll("'", `'\\''`)}'`;
-}
-/** Creates a sandbox, names it, and waits until it runs commands. */
-export async function createBoatMachine(api, { name }) {
-    const created = await boat("creating a Boat sandbox", () => api.create({}));
-    const sandboxId = created.sandbox.id;
-    await boat(`naming Boat sandbox ${sandboxId}`, () => api.update({ sandboxId, name }));
-    return waitUntilReady(api, sandboxId, { timeoutMs: 180_000 });
-}
-/** The sandbox, running: one that was stopped (archived) is resumed, its disk as it was, first. */
-export async function ensureBoatRunning(api, sandboxId) {
-    const deadline = Date.now() + 180_000;
-    for (;;) {
-        const { sandbox } = await boat(`reading Boat sandbox ${sandboxId}`, () => api.get({ sandboxId }));
-        if (RUNNING_STATES.includes(sandbox.state))
-            return sandbox;
-        if (sandbox.state === "archived") {
-            await boat(`resuming Boat sandbox ${sandboxId}`, () => api.resume({ sandboxId }));
-            return waitUntilReady(api, sandboxId, { timeoutMs: Math.max(1, deadline - Date.now()) });
-        }
-        if (sandbox.state === "error" || sandbox.state === "cancelled") {
-            throw new Error(`Boat sandbox ${sandboxId} is ${sandbox.state}${sandbox.error ? `: ${sandbox.error}` : ""}`);
-        }
-        // Starting, or still being archived: it's resumed once that's done.
-        if (Date.now() > deadline)
-            throw new Error(`Boat sandbox ${sandboxId} stayed ${sandbox.state}`);
-        await new Promise((resolve) => setTimeout(resolve, 2000));
-    }
-}
-/** Stops the sandbox, saving its disk first (Boat archives it), for a later ensureBoatRunning. */
-export async function archiveBoatMachine(api, sandboxId) {
-    await boat(`stopping Boat sandbox ${sandboxId}`, () => api.stop({ sandboxId }));
-}
-/**
- * Lets `publicKey` (OpenSSH) log in to the running sandbox, and says where: Boat's SSH endpoint for
- * it and its user. The endpoint may change when the sandbox is resumed on another machine.
- */
-export async function authorizeBoatSshKey(api, sandboxId, publicKey) {
-    const response = await boat(`adding an SSH key to Boat sandbox ${sandboxId}`, () => api.sshKey({ sandboxId, key: publicKey }));
-    const endpoint = /^(.+):(\d+)$/.exec(response.sshEndpoint ?? "");
-    if (endpoint)
-        return { host: endpoint[1], port: Number(endpoint[2]), user: response.sshUser ?? "user" };
-    if (response.machineIp)
-        return { host: response.machineIp, port: 22, user: response.sshUser ?? "user" };
-    throw new Error(`Boat gave no SSH endpoint for sandbox ${sandboxId}`);
-}

package/dist/sandbox/containerService.d.ts

@@ -1,15 +0,0 @@
-import type { DockerClient } from "../lib/docker.ts";
-import { type Sandbox } from "./api.ts";
-export type ContainerSandboxOptions = {
-    /** "uid:gid", a user name or "root"; defaults to the container's own user. */
-    user?: string;
-};
-/**
- * Runs inside a running container through the docker API: every operation is a `docker exec` as
- * `user`, and files are written by extracting an archive, so the container needs nothing but a
- * POSIX shell and coreutils (fetch also needs curl). Sandbox paths are container paths.
- *
- * `fetch` runs curl in the container and returns once the whole response has arrived: fine for
- * requests and long polls, not for streams. Its `signal` is only checked before the request starts.
- */
-export declare function createContainerSandbox(docker: DockerClient, container: string, { user }?: ContainerSandboxOptions): Sandbox;

package/dist/sandbox/containerService.js

@@ -1,184 +0,0 @@
-import { posix } from "node:path";
-import { SandboxNotFoundError, } from "./api.js";
-/** What the scripts below exit with for a missing path. */
-const NOT_FOUND = 44;
-/** writeFileExclusive's script: the file already exists. */
-const EXISTS = 45;
-/**
- * Runs inside a running container through the docker API: every operation is a `docker exec` as
- * `user`, and files are written by extracting an archive, so the container needs nothing but a
- * POSIX shell and coreutils (fetch also needs curl). Sandbox paths are container paths.
- *
- * `fetch` runs curl in the container and returns once the whole response has arrived: fine for
- * requests and long polls, not for streams. Its `signal` is only checked before the request starts.
- */
-export function createContainerSandbox(docker, container, { user } = {}) {
-    let owner;
-    function containerPath(path) {
-        return posix.resolve("/", path);
-    }
-    async function sh(script, env = {}, options = {}) {
-        return docker.exec(container, { cmd: ["sh", "-c", script], user: options.user ?? user, env, workdir: options.workdir });
-    }
-    /** Throws SandboxNotFoundError for the scripts' NOT_FOUND, and an Error for any other failure. */
-    function check(result, what, path) {
-        if (result.exitCode === NOT_FOUND)
-            throw new SandboxNotFoundError(`Not found: "${path}"`);
-        if (result.exitCode !== 0)
-            throw new Error(`${what} ${path} in ${container} failed: ${result.stderr.trim()}`);
-        return result;
-    }
-    /** "uid:gid" of the sandbox user, which files written through an archive are handed to. */
-    function fileOwner() {
-        owner ??= sh('printf "%s:%s" "$(id -u)" "$(id -g)"').then((result) => check(result, "id", "").stdout.trim());
-        return owner;
-    }
-    async function readFile(path) {
-        const full = containerPath(path);
-        const result = check(await sh(`[ -e "$P" ] || exit ${NOT_FOUND}; base64 -w0 -- "$P"`, { P: full }), "read", full);
-        return new Uint8Array(Buffer.from(result.stdout, "base64"));
-    }
-    async function readFileRange(path, start, end) {
-        const full = containerPath(path);
-        const script = `[ -e "$P" ] || exit ${NOT_FOUND}; tail -c +$(($S + 1)) -- "$P" | head -c "$L" | base64 -w0`;
-        const result = check(await sh(script, { P: full, S: String(start), L: String(Math.max(0, end - start)) }), "read", full);
-        return new Uint8Array(Buffer.from(result.stdout, "base64"));
-    }
-    /**
-     * Extracts `data` next to `full` under a unique hidden name, handed to the sandbox user, and runs
-     * `publish` (as root, with $T the temp file and $F the target) to move it into place.
-     */
-    async function writeVia(full, data, publish) {
-        const dir = posix.dirname(full);
-        const tmp = `.${posix.basename(full)}.${crypto.randomUUID()}.tmp`;
-        check(await sh('mkdir -p -- "$D"', { D: dir }), "mkdir", dir);
-        await docker.putArchive(container, dir, { [tmp]: data });
-        return sh(`chown "$OWNER" -- "$T" && ${publish}`, { OWNER: await fileOwner(), T: `${dir}/${tmp}`, F: full }, { user: "root" });
-    }
-    async function writeFile(path, data) {
-        const full = containerPath(path);
-        check(await writeVia(full, data, 'mv -f -- "$T" "$F"'), "write", full);
-    }
-    // ln refuses to replace an existing file, and publishes the fully written temp file.
-    async function writeFileExclusive(path, data) {
-        const full = containerPath(path);
-        const result = await writeVia(full, data, `if ln -- "$T" "$F" 2>/dev/null; then rm -f -- "$T"; exit 0; fi; rm -f -- "$T"; [ -e "$F" ] && exit ${EXISTS}; exit 1`);
-        if (result.exitCode === EXISTS)
-            return false;
-        check(result, "write", full);
-        return true;
-    }
-    async function removeFile(path) {
-        const full = containerPath(path);
-        check(await sh('rm -f -- "$P"', { P: full }), "remove", full);
-    }
-    async function createDirectory(path) {
-        const full = containerPath(path);
-        check(await sh('mkdir -p -- "$P"', { P: full }), "mkdir", full);
-    }
-    async function removeDirectory(path) {
-        const full = containerPath(path);
-        check(await sh('rm -rf -- "$P"', { P: full }), "remove", full);
-    }
-    async function listDirectory(path) {
-        const full = containerPath(path);
-        const result = check(await sh(`[ -e "$P" ] || exit ${NOT_FOUND}; ls -A1 -- "$P"`, { P: full }), "list", full);
-        return result.stdout.split("\n").filter(Boolean);
-    }
-    async function stat(path) {
-        const full = containerPath(path);
-        const result = check(await sh(`[ -e "$P" ] || exit ${NOT_FOUND}; stat -c '%u:%g:%s:%F' -- "$P"`, { P: full }), "stat", full);
-        const [uid = "", gid = "", size = "", kind = ""] = result.stdout.trim().split(":");
-        const type = kind === "directory" ? "directory" : kind.startsWith("regular") ? "file" : "other";
-        return { type, uid: Number(uid), gid: Number(gid), size: Number(size) };
-    }
-    // docker exec doesn't always set HOME for a numeric user, so ask the user database.
-    async function homeDirectory() {
-        const result = check(await sh('getent passwd "$(id -u)" | cut -d: -f6'), "home of", user ?? "the container user");
-        return result.stdout.trim() || "/";
-    }
-    // docker exec has no stdin here, so input travels base64-encoded in the environment.
-    async function runCommand(cmd, { cwd, env = {}, stdin } = {}) {
-        const workdir = cwd === undefined ? undefined : containerPath(cwd);
-        if (stdin === undefined)
-            return docker.exec(container, { cmd, user, env, workdir });
-        return docker.exec(container, {
-            cmd: ["sh", "-c", 'printf %s "$HYB_STDIN" | base64 -d | "$@"', "sh", ...cmd],
-            user,
-            env: { ...env, HYB_STDIN: Buffer.from(stdin).toString("base64") },
-            workdir,
-        });
-    }
-    async function fetchInContainer(url, init = {}) {
-        if (init.signal?.aborted)
-            throw init.signal.reason;
-        const args = ["-sS", "-i", "-X", init.method ?? "GET", "-H", "Expect:"];
-        for (const [name, value] of Object.entries(init.headers ?? {}))
-            args.push("-H", `${name}: ${value}`);
-        if (init.unix !== undefined)
-            args.push("--unix-socket", containerPath(init.unix));
-        // An idle timeout: give up once fewer than 1 byte a second has moved for that long.
-        if (typeof init.timeout === "number")
-            args.push("--speed-limit", "1", "--speed-time", String(Math.ceil(init.timeout / 1000)));
-        if (init.body !== undefined)
-            args.push("--data-binary", "@-");
-        args.push(url);
-        // The response goes through a file and out as base64, so binary bodies survive and curl's own
-        // exit code is still the script's.
-        const script = [
-            't="$(mktemp)"',
-            `${init.body === undefined ? "" : 'printf %s "$HYB_STDIN" | base64 -d | '}curl "$@" > "$t"`,
-            "code=$?",
-            'base64 -w0 "$t"',
-            'rm -f "$t"',
-            'exit "$code"',
-        ].join("\n");
-        const env = init.body === undefined ? {} : { HYB_STDIN: Buffer.from(init.body).toString("base64") };
-        const result = await docker.exec(container, { cmd: ["sh", "-c", script, "sh", ...args], user, env });
-        if (result.exitCode !== 0) {
-            throw new Error(`fetch ${url} in ${container} failed (curl exit ${result.exitCode}): ${result.stderr.trim()}`);
-        }
-        return parseResponse(Buffer.from(result.stdout, "base64"));
-    }
-    return {
-        readFile,
-        readFileRange,
-        writeFile,
-        writeFileExclusive,
-        removeFile,
-        createDirectory,
-        removeDirectory,
-        listDirectory,
-        stat,
-        homeDirectory,
-        runCommand,
-        fetch: fetchInContainer,
-        // A container's sockets are reached from its host (agents mount theirs there), not through exec.
-        connect: async (path) => {
-            throw new Error(`connecting to ${path} inside ${container} is not supported; connect through the host sandbox`);
-        },
-    };
-}
-/** Parses curl -i output: header blocks (interim 1xx ones skipped), then the body. */
-function parseResponse(raw) {
-    let offset = 0;
-    for (;;) {
-        const end = raw.indexOf("\r\n\r\n", offset);
-        if (end < 0)
-            throw new Error("malformed HTTP response from curl");
-        const [statusLine = "", ...headerLines] = raw.subarray(offset, end).toString("latin1").split("\r\n");
-        offset = end + 4;
-        const status = Number(statusLine.split(" ")[1]);
-        if (status >= 100 && status < 200)
-            continue;
-        const headers = new Headers();
-        for (const line of headerLines) {
-            const colon = line.indexOf(":");
-            if (colon > 0)
-                headers.append(line.slice(0, colon).trim(), line.slice(colon + 1).trim());
-        }
-        // A null-body status can't be given a body, even an empty one.
-        const body = status === 204 || status === 304 ? null : new Uint8Array(raw.subarray(offset));
-        return new Response(body, { status, headers });
-    }
-}

package/dist/sandbox/endpointProxy.d.ts

@@ -1,90 +0,0 @@
-import { type SandboxAccessibleEndpoint, type SandboxCommands, type SandboxEndpoint, type SandboxEndpointCredentials, type SandboxEndpointRequest } from "./api.ts";
-/** Declares the accessible-endpoint capability when a sandbox is created (local and SSH). */
-export type SandboxEndpointsOptions = {
-    /**
-     * How clients reach the machine over the network ("host" or "host:port"); often not the address
-     * the sandbox itself uses. With a port, every endpoint listens on it, one proxy serving them all;
-     * without, each gets a free port of its own (its auth may limit which).
-     */
-    accessibleHost: string;
-    /**
-     * The machine's firewall is ufw and drops ports by default: a proxy's port is opened with
-     * `sudo -n ufw allow` (so the user needs passwordless sudo) and closed again with it.
-     */
-    needsFirewall?: boolean;
-    /** Defaults to proxyCredentialsAuth(); exeDevProxyAuth() for an exe.dev VM. */
-    auth?: SandboxEndpointAuth;
-    /**
-     * Sandbox path the proxies keep their endpoints in (their secrets: files only the user can read);
-     * defaults to ~/.local/state/hyperbrane/endpoints.
-     */
-    stateDirectory?: string;
-};
-/** An accessible host, split: `port` is null when endpoints pick their own. */
-export type AccessibleHost = {
-    host: string;
-    port: number | null;
-};
-/** "host", "host:port", "[v6]:port" or a bare IPv6 address; throws SandboxEndpointError for a bad port. */
-export declare function parseAccessibleHost(value: string): AccessibleHost;
-/**
- * How a sandbox's endpoints are authenticated. Bound once, when the sandbox is created, to the host
- * clients reach it at (throws if it can't serve that host or port); then plans each endpoint.
- */
-export type SandboxEndpointAuth = {
-    bind(accessible: AccessibleHost): BoundEndpointAuth;
-};
-export type BoundEndpointAuth = {
-    /** Whether the backend may open the proxy's port in the host firewall: not when only a proxy in front of it may reach it. */
-    firewall: boolean;
-    /** Throws SandboxEndpointError for a request this auth doesn't allow. */
-    plan(request: SandboxEndpointRequest): EndpointPlan;
-};
-export type EndpointPlan = {
-    /** What the proxy checks on every request; null when something in front of it checks instead. */
-    check: {
-        scheme: "bearer" | "basic";
-        credentials: string;
-    } | null;
-    /** Ports to listen on, inclusive; [0, 0] for any free one. */
-    ports: [number, number];
-    /** Ports in that range it must never listen on. */
-    except?: number[];
-    /**
-     * Where clients reach the proxy on the port the endpoint ends up on (its base URL; the endpoint is
-     * a path under it), and what they present: made public there first if that takes doing (Boat).
-     */
-    publish(port: number): Promise<{
-        url: string;
-        credentials: SandboxEndpointCredentials;
-    }>;
-};
-/**
- * The default: the proxy itself checks credentials it mints per endpoint (bearer or basic). The
- * proxy speaks plain HTTP; the accessible host is assumed to terminate TLS in front of it, on the
- * same port, so clients are given https URLs.
- */
-export declare function proxyCredentialsAuth(): SandboxEndpointAuth;
-/** The port a request must listen on: the accessible host's, or its own; null for any. */
-export declare function pinnedPort(pinned: number | null, requested: number | undefined): number | null;
-export declare function checkPort(port: number): void;
-/** The port an endpoint listens on and its name there, from its id; throws for anything that isn't an endpoint id. */
-export declare function parseEndpointId(endpointId: string): {
-    port: number;
-    name: string;
-};
-/**
- * The capability for a sandbox whose commands run on the machine (`where`, for errors). Endpoints
- * are records there, served by proxies started there, detached, one per port: a port of the
- * accessible host's is shared by all, otherwise each endpoint starts one on a port of its own. A
- * proxy that stopped is started again by ensureEndpoint, serving the same records. With a firewall, a
- * proxy's port is opened once it listens (it is stopped again if that fails) and closed when it stops.
- */
-export type ProxyEndpoints = SandboxAccessibleEndpoint & {
-    /**
-     * exposeEndpoint under a name of the caller's (a UUID), replacing what that name held: the same
-     * URL every time, for endpoints the sandbox keeps for itself (boatService.ts).
-     */
-    exposeEndpointAs(name: string, request: SandboxEndpointRequest): Promise<SandboxEndpoint>;
-};
-export declare function createProxyEndpoints(commands: SandboxCommands, options: SandboxEndpointsOptions, where: string): ProxyEndpoints;