hyperbrane 0.1.0

package/dist/sandbox/exeDevAuth.d.ts

@@ -0,0 +1,16 @@
+import { type SandboxEndpointAuth } from "./endpointProxy.ts";
+export type ExeDevAuthOptions = {
+    /**
+     * The VM's public port (`ssh exe.dev share port`), which anyone reaches without logging in; null if
+     * the VM isn't public. Required: the VM can't tell from inside, and no endpoint may listen on it.
+     */
+    publicPort: number | null;
+};
+/**
+ * Endpoints on an exe.dev VM, behind exe.dev's proxy: it lets through only users logged in with
+ * exe.dev that the VM is shared with, so the endpoint proxy checks nothing itself. The sandbox's
+ * accessible host must be the VM's <vm>.exe.xyz, with or without a port of 3000-9999 other than the
+ * public one. exe.dev's login is per port, so a fixed port means logging in once. Its ports are never
+ * opened in the firewall: reached directly, they would skip exe.dev's login.
+ */
+export declare function exeDevProxyAuth({ publicPort }: ExeDevAuthOptions): SandboxEndpointAuth;

package/dist/sandbox/exeDevAuth.js

@@ -0,0 +1,49 @@
+import { SandboxEndpointError } from "./api.js";
+import { checkPort, pinnedPort } from "./endpointProxy.js";
+/** The ports exe.dev's proxy forwards, as https://<vm>.exe.xyz:<port>/ (https://exe.dev/docs/proxy.md). */
+const FORWARDED_PORTS = [3000, 9999];
+const HOST_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?\.exe\.xyz$/i;
+/**
+ * Endpoints on an exe.dev VM, behind exe.dev's proxy: it lets through only users logged in with
+ * exe.dev that the VM is shared with, so the endpoint proxy checks nothing itself. The sandbox's
+ * accessible host must be the VM's <vm>.exe.xyz, with or without a port of 3000-9999 other than the
+ * public one. exe.dev's login is per port, so a fixed port means logging in once. Its ports are never
+ * opened in the firewall: reached directly, they would skip exe.dev's login.
+ */
+export function exeDevProxyAuth({ publicPort }) {
+    const [low, high] = FORWARDED_PORTS;
+    function checkForwarded(port) {
+        checkPort(port);
+        if (port < low || port > high)
+            throw new SandboxEndpointError(`exe.dev forwards ports ${low}-${high}, not ${port}`);
+        if (port === publicPort)
+            throw new SandboxEndpointError(`port ${port} is the VM's public port: anyone could reach it without logging in`);
+    }
+    return {
+        bind({ host, port: pinned }) {
+            if (!HOST_PATTERN.test(host))
+                throw new SandboxEndpointError(`exe.dev endpoints need the VM's <vm>.exe.xyz host, not "${host}"`);
+            if (pinned !== null)
+                checkForwarded(pinned);
+            return {
+                firewall: false,
+                plan({ scheme, port }) {
+                    if (scheme !== "exe.dev")
+                        throw new SandboxEndpointError(`exe.dev endpoints are checked by exe.dev's login, not "${scheme}"`);
+                    const listen = pinnedPort(pinned, port);
+                    if (listen !== null)
+                        checkForwarded(listen);
+                    return {
+                        check: null,
+                        ports: listen === null ? [low, high] : [listen, listen],
+                        except: publicPort === null ? [] : [publicPort],
+                        publish: async (listening) => ({
+                            url: `https://${host}:${listening}`,
+                            credentials: { scheme: "exe.dev", loginUrl: `https://${host}:${listening}/__exe.dev/login` },
+                        }),
+                    };
+                },
+            };
+        },
+    };
+}

package/dist/sandbox/localService.d.ts

@@ -0,0 +1,19 @@
+import { type Sandbox, type SandboxAccessibleEndpoint, type SandboxConnection } from "./api.ts";
+import { type SandboxEndpointsOptions } from "./endpointProxy.ts";
+export type LocalSandboxOptions = {
+    /** Declares the accessible-endpoint capability (SandboxAccessibleEndpoint): proxies on this machine. */
+    endpoints?: SandboxEndpointsOptions;
+};
+/** Runs directly on this machine under `root`: no container, no auth proxy. */
+export declare function createLocalSandbox(root: string, options: LocalSandboxOptions & {
+    endpoints: SandboxEndpointsOptions;
+}): Sandbox & SandboxAccessibleEndpoint;
+export declare function createLocalSandbox(root: string, options?: LocalSandboxOptions): Sandbox;
+/** A SandboxConnection over a node stream (a local socket, or an SSH-forwarded one) once it is open. */
+export declare function socketConnection(stream: NodeJS.ReadWriteStream & {
+    end(): void;
+    destroy(): void;
+    once(event: string, listener: (...args: unknown[]) => void): unknown;
+}, path: string, { opened }?: {
+    opened?: boolean;
+}): Promise<SandboxConnection>;

package/dist/sandbox/localService.js

@@ -0,0 +1,182 @@
+import { spawn } from "node:child_process";
+import { link, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { request as httpRequest } from "node:http";
+import { createConnection } from "node:net";
+import { homedir } from "node:os";
+import { Readable } from "node:stream";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { SandboxNotFoundError, SandboxPathError, } from "./api.js";
+import { createProxyEndpoints } from "./endpointProxy.js";
+export function createLocalSandbox(root, { endpoints } = {}) {
+    const base = resolve(root);
+    function hostPath(path) {
+        const full = resolve(base, isAbsolute(path) ? `.${path}` : path);
+        const rel = relative(base, full);
+        if (rel.startsWith("..") || isAbsolute(rel))
+            throw new SandboxPathError(`Path escapes sandbox: "${path}"`);
+        return full;
+    }
+    async function notFoundAs(path, operation) {
+        try {
+            return await operation;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                throw new SandboxNotFoundError(`Not found: "${path}"`);
+            throw error;
+        }
+    }
+    /** Writes `data` next to `full` under a unique hidden name, so it can be renamed or linked into place. */
+    async function writeTemp(full, data) {
+        await mkdir(dirname(full), { recursive: true });
+        const tmp = join(dirname(full), `.${basename(full)}.${crypto.randomUUID()}.tmp`);
+        await writeFile(tmp, data);
+        return tmp;
+    }
+    async function readFileLocal(path) {
+        return new Uint8Array(await notFoundAs(path, readFile(hostPath(path))));
+    }
+    async function writeFileLocal(path, data) {
+        const full = hostPath(path);
+        await rename(await writeTemp(full, data), full);
+    }
+    async function writeFileExclusive(path, data) {
+        const full = hostPath(path);
+        const tmp = await writeTemp(full, data);
+        try {
+            // link() refuses to replace an existing file, and publishes the fully written temp file.
+            await link(tmp, full);
+            return true;
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                return false;
+            throw error;
+        }
+        finally {
+            await unlink(tmp);
+        }
+    }
+    async function removeFile(path) {
+        await rm(hostPath(path), { force: true });
+    }
+    async function createDirectory(path) {
+        await mkdir(hostPath(path), { recursive: true });
+    }
+    async function removeDirectory(path) {
+        await rm(hostPath(path), { recursive: true, force: true });
+    }
+    async function listDirectory(path) {
+        return notFoundAs(path, readdir(hostPath(path)));
+    }
+    async function statLocal(path) {
+        const stats = await notFoundAs(path, stat(hostPath(path)));
+        const type = stats.isFile() ? "file" : stats.isDirectory() ? "directory" : "other";
+        return { type, uid: stats.uid, gid: stats.gid };
+    }
+    async function homeDirectory() {
+        const rel = relative(base, homedir());
+        if (rel.startsWith("..") || isAbsolute(rel))
+            throw new SandboxPathError(`Home directory is outside the sandbox`);
+        return `/${rel}`;
+    }
+    // node:child_process rather than Bun.spawn: the library runs under Node too.
+    function runCommand(cmd, { cwd, env = {}, stdin } = {}) {
+        return new Promise((resolve, reject) => {
+            const [command, ...args] = cmd;
+            if (!command)
+                return reject(new Error("no command to run"));
+            const child = spawn(command, args, {
+                cwd: hostPath(cwd ?? "."),
+                env: { ...process.env, ...env },
+                stdio: [stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+            });
+            const stdout = [];
+            const stderr = [];
+            child.stdout.on("data", (chunk) => stdout.push(chunk));
+            child.stderr.on("data", (chunk) => stderr.push(chunk));
+            child.once("error", reject);
+            // After its output closes too: a command that leaves a detached child (the endpoint proxy) is done then.
+            child.once("close", (code) => resolve({ exitCode: code ?? -1, stdout: Buffer.concat(stdout).toString(), stderr: Buffer.concat(stderr).toString() }));
+            if (stdin !== undefined)
+                child.stdin.end(stdin);
+        });
+    }
+    async function connect(path) {
+        return socketConnection(createConnection({ path: hostPath(path) }), path);
+    }
+    async function fetchLocal(url, { unix, ...init } = {}) {
+        if (unix === undefined || "Bun" in globalThis)
+            return fetch(url, { ...init, unix: unix === undefined ? undefined : hostPath(unix) });
+        return fetchOverSocket(url, hostPath(unix), init);
+    }
+    const sandbox = {
+        readFile: readFileLocal,
+        writeFile: writeFileLocal,
+        writeFileExclusive,
+        removeFile,
+        createDirectory,
+        removeDirectory,
+        listDirectory,
+        stat: statLocal,
+        homeDirectory,
+        runCommand,
+        fetch: fetchLocal,
+        connect,
+    };
+    if (!endpoints)
+        return sandbox;
+    return { ...sandbox, ...createProxyEndpoints({ runCommand }, endpoints, "this machine") };
+}
+/**
+ * HTTP/1.1 over the unix socket at `socketPath`, for Node, whose fetch can't use one (Bun's can).
+ * The response streams as it arrives; `timeout` is the idle timeout, as with Bun's fetch.
+ */
+function fetchOverSocket(url, socketPath, { method = "GET", headers = {}, body, signal, timeout }) {
+    return new Promise((resolve, reject) => {
+        const target = new URL(url);
+        const request = httpRequest({ socketPath, path: `${target.pathname}${target.search}`, method, headers: { host: target.host, ...headers }, signal }, (response) => {
+            const responseHeaders = new Headers();
+            for (let i = 0; i + 1 < response.rawHeaders.length; i += 2)
+                responseHeaders.append(response.rawHeaders[i], response.rawHeaders[i + 1]);
+            const status = response.statusCode ?? 502;
+            // A null-body status can't be given a body, even an empty one.
+            const nullBody = status === 204 || status === 304 || method === "HEAD";
+            if (nullBody)
+                response.resume();
+            resolve(new Response(nullBody ? null : Readable.toWeb(response), { status, headers: responseHeaders }));
+        });
+        request.once("error", reject);
+        if (typeof timeout === "number")
+            request.setTimeout(timeout, () => request.destroy(new Error(`fetch ${url}: no data for ${timeout}ms`)));
+        request.end(body === undefined ? undefined : typeof body === "string" ? body : Buffer.from(body));
+    });
+}
+/** A SandboxConnection over a node stream (a local socket, or an SSH-forwarded one) once it is open. */
+export function socketConnection(stream, path, { opened = false } = {}) {
+    return new Promise((resolve, reject) => {
+        let markClosed;
+        const closed = new Promise((done) => (markClosed = done));
+        const listeners = [];
+        stream.on("data", (chunk) => {
+            for (const listener of listeners)
+                listener(new Uint8Array(chunk));
+        });
+        stream.once("close", () => markClosed());
+        stream.once("end", () => markClosed());
+        const connection = {
+            write: (data) => void stream.write(data),
+            onData: (listener) => void listeners.push(listener),
+            closed,
+            close: () => stream.end(),
+        };
+        stream.once("error", (error) => {
+            markClosed();
+            reject(new Error(`connecting to ${path} failed: ${error.message}`));
+        });
+        if (opened)
+            resolve(connection);
+        else
+            stream.once("connect", () => resolve(connection));
+    });
+}

package/dist/sandbox/sseConnection.d.ts

@@ -0,0 +1,41 @@
+import type { SandboxConnection, SandboxEndpoint } from "./api.ts";
+/** Where an endpoint is reached, and how. */
+export type EndpointAccess = Pick<SandboxEndpoint, "url" | "credentials">;
+/**
+ * The URL and fetch options for a request to `path` (e.g. "/", "/<connection>", "/v1/x?y=1") under
+ * the endpoint, carrying its credentials as their scheme wants: an Authorization header, or the
+ * browser's exe.dev login (its cookie).
+ */
+export declare function endpointRequest(endpoint: EndpointAccess, path: string, init?: RequestInit): [string, RequestInit];
+/**
+ * A stream connection through an endpoint of the proxy's "sse" transport (endpointProxy.ts): the
+ * target's lines arrive as events (handed on with their newline), and each write goes as a POST of
+ * its own, concurrently: writes are whole messages (JSON-RPC lines), whose order between each other
+ * doesn't matter. Text lines only, which is what the transport
+ * carries. Only fetch, so it runs in a browser as well as on a server; in a browser the page's origin
+ * must be one of the endpoint's allowedOrigins. Aborting `signal` closes it.
+ */
+export declare function openSseConnection(endpoint: EndpointAccess, { signal }?: {
+    signal?: AbortSignal;
+}): Promise<SandboxConnection>;
+/** The events of a server-sent event stream as they arrive (comments skipped, data lines joined). */
+export declare function sseEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<{
+    event: string;
+    data: string;
+}>;
+/**
+ * The endpoint couldn't be reached, which for an exe.dev endpoint usually means the browser isn't
+ * logged in with exe.dev on its port yet (the proxy being down looks the same to a page). Send the
+ * page through exeDevLoginUrl to log in and come back.
+ */
+export declare class EndpointLoginRequiredError extends Error {
+    readonly loginUrl: string;
+    name: string;
+    constructor(loginUrl: string, cause?: unknown);
+}
+/**
+ * Where to send the page so the user logs in with exe.dev on the endpoint's port and then comes back
+ * to `returnTo`: exe.dev's login returns to a path on that port, where the endpoint proxy redirects
+ * on to `returnTo` (whose origin must be one of the endpoint's allowedOrigins).
+ */
+export declare function exeDevLoginUrl(loginUrl: string, returnTo: string): string;

package/dist/sandbox/sseConnection.js

@@ -0,0 +1,166 @@
+/**
+ * The URL and fetch options for a request to `path` (e.g. "/", "/<connection>", "/v1/x?y=1") under
+ * the endpoint, carrying its credentials as their scheme wants: an Authorization header, or the
+ * browser's exe.dev login (its cookie).
+ */
+export function endpointRequest(endpoint, path, init = {}) {
+    const url = new URL(`${endpoint.url.replace(/\/+$/, "")}${path}`);
+    const headers = new Headers(init.headers);
+    const { credentials } = endpoint;
+    if (credentials.scheme === "bearer")
+        headers.set("authorization", `Bearer ${credentials.token}`);
+    if (credentials.scheme === "basic")
+        headers.set("authorization", `Basic ${btoa(`${credentials.username}:${credentials.password}`)}`);
+    return [url.toString(), { ...init, headers, credentials: credentials.scheme === "exe.dev" ? "include" : "same-origin" }];
+}
+/**
+ * A stream connection through an endpoint of the proxy's "sse" transport (endpointProxy.ts): the
+ * target's lines arrive as events (handed on with their newline), and each write goes as a POST of
+ * its own, concurrently: writes are whole messages (JSON-RPC lines), whose order between each other
+ * doesn't matter. Text lines only, which is what the transport
+ * carries. Only fetch, so it runs in a browser as well as on a server; in a browser the page's origin
+ * must be one of the endpoint's allowedOrigins. Aborting `signal` closes it.
+ */
+export async function openSseConnection(endpoint, { signal } = {}) {
+    signal?.throwIfAborted();
+    const leave = new AbortController();
+    signal?.addEventListener("abort", () => leave.abort(), { once: true, signal: leave.signal });
+    const [url, init] = endpointRequest(endpoint, "/", { headers: { accept: "text/event-stream" }, signal: leave.signal });
+    let response;
+    try {
+        response = await fetch(url, init);
+    }
+    catch (error) {
+        // exe.dev answers a browser that isn't logged in on this port with a redirect to its login,
+        // which a cross-origin fetch can't follow: it fails like the network did.
+        const { credentials } = endpoint;
+        if (credentials.scheme === "exe.dev" && !leave.signal.aborted)
+            throw new EndpointLoginRequiredError(credentials.loginUrl, error);
+        throw error;
+    }
+    const where = endpoint.url.replace(/\/+$/, "");
+    if (!response.ok || !response.body) {
+        leave.abort();
+        throw new Error(`connecting to ${where} failed: ${response.status} ${response.statusText}`);
+    }
+    const events = sseEvents(response.body);
+    const first = await events.next().catch((error) => ({ done: true, value: error }));
+    if (first.done || first.value.event !== "open") {
+        leave.abort();
+        throw new Error(`connecting to ${where} failed: no connection opened`);
+    }
+    const connection = JSON.parse(first.value.data).connection;
+    const encoder = new TextEncoder();
+    const listeners = [];
+    // Lines that arrive before anyone listens wait for the first listener.
+    const early = [];
+    let markClosed;
+    const closed = new Promise((resolve) => (markClosed = resolve));
+    // Each write is a whole message (a line) in a POST of its own, written to the target whole (the
+    // proxy holds the connection's lock for it), so they go out at once rather than one by one: calls
+    // made together take a round trip together. One that fails ends the connection, which fails
+    // whatever waits on it.
+    void (async () => {
+        try {
+            for await (const event of events) {
+                if (event.event === "close")
+                    break;
+                if (event.event !== "message")
+                    continue;
+                const data = encoder.encode(`${event.data}\n`);
+                if (listeners.length === 0)
+                    early.push(data);
+                for (const listener of listeners)
+                    listener(data);
+            }
+        }
+        catch {
+            // Aborted, or the stream broke: either way the connection is over.
+        }
+        finally {
+            leave.abort();
+            markClosed();
+        }
+    })();
+    return {
+        write(data) {
+            const [postUrl, postInit] = endpointRequest(endpoint, `/${connection}`, {
+                method: "POST",
+                // text/plain keeps it a "simple" request: no preflight where the endpoint has no credentials of its own.
+                headers: { "content-type": "text/plain" },
+                body: new Uint8Array(data),
+            });
+            fetch(postUrl, postInit)
+                .then((posted) => {
+                if (posted.status !== 204)
+                    throw new Error(`writing to ${where} failed: ${posted.status}`);
+            })
+                .catch(() => leave.abort());
+        },
+        onData(listener) {
+            listeners.push(listener);
+            for (const data of early.splice(0))
+                listener(data);
+        },
+        closed,
+        close: () => leave.abort(),
+    };
+}
+/** The events of a server-sent event stream as they arrive (comments skipped, data lines joined). */
+export async function* sseEvents(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let text = "";
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                return;
+            text += decoder.decode(value, { stream: true }).replaceAll("\r\n", "\n");
+            let end;
+            while ((end = text.indexOf("\n\n")) >= 0) {
+                const block = text.slice(0, end);
+                text = text.slice(end + 2);
+                let event = "message";
+                const data = [];
+                for (const line of block.split("\n")) {
+                    if (line.startsWith(":"))
+                        continue;
+                    const colon = line.indexOf(":");
+                    const field = colon < 0 ? line : line.slice(0, colon);
+                    const value = colon < 0 ? "" : line.slice(colon + 1).replace(/^ /, "");
+                    if (field === "event")
+                        event = value;
+                    else if (field === "data")
+                        data.push(value);
+                }
+                if (data.length || event !== "message")
+                    yield { event, data: data.join("\n") };
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/**
+ * The endpoint couldn't be reached, which for an exe.dev endpoint usually means the browser isn't
+ * logged in with exe.dev on its port yet (the proxy being down looks the same to a page). Send the
+ * page through exeDevLoginUrl to log in and come back.
+ */
+export class EndpointLoginRequiredError extends Error {
+    loginUrl;
+    name = "EndpointLoginRequiredError";
+    constructor(loginUrl, cause) {
+        super("logging in with exe.dev is needed to reach the endpoint", { cause });
+        this.loginUrl = loginUrl;
+    }
+}
+/**
+ * Where to send the page so the user logs in with exe.dev on the endpoint's port and then comes back
+ * to `returnTo`: exe.dev's login returns to a path on that port, where the endpoint proxy redirects
+ * on to `returnTo` (whose origin must be one of the endpoint's allowedOrigins).
+ */
+export function exeDevLoginUrl(loginUrl, returnTo) {
+    return `${loginUrl}?redirect=${encodeURIComponent(`/__hyb/return?to=${encodeURIComponent(returnTo)}`)}`;
+}

package/dist/sandbox/sshService.d.ts

@@ -0,0 +1,30 @@
+import { type Sandbox, type SandboxAccessibleEndpoint } from "./api.ts";
+import { type SandboxEndpointsOptions } from "./endpointProxy.ts";
+export type SshSandboxOptions = {
+    user: string;
+    port?: number;
+    /** The private key itself (PEM or OpenSSH), not a path: nothing is read from or written to disk. */
+    privateKey: string | Buffer;
+    passphrase?: string;
+    /** Checks the server's host key (raw bytes); return false to refuse it. Defaults to accepting any. */
+    hostVerifier?: (key: Buffer) => boolean;
+    /** How long connecting may take. Defaults to 15 seconds. */
+    readyTimeout?: number;
+    /** Declares the accessible-endpoint capability (SandboxAccessibleEndpoint): proxies on the remote host. */
+    endpoints?: SandboxEndpointsOptions;
+};
+/**
+ * Runs on a remote host over SSH, with the ssh2 library — no `ssh` binary needed, so it works in
+ * environments that have none (serverless functions). Everything goes over a single connection,
+ * opened on first use and reopened if it drops; close() releases it. Sandbox paths are remote paths.
+ *
+ * Files go through one SFTP channel, and `fetch` and `connect` through OpenSSH's stream-local
+ * forwarding to the remote unix socket (both on by default in sshd); only runCommand and
+ * removeDirectory run commands, each on a channel of its own. Commands are kept few on purpose:
+ * sshd limits the sessions on a connection (MaxSessions), counts a closed one until it has cleaned
+ * up after it, and under load may close a command's channel without its exit status.
+ */
+export declare function createSshSandbox(host: string, options: SshSandboxOptions & {
+    endpoints: SandboxEndpointsOptions;
+}): Sandbox & SandboxAccessibleEndpoint;
+export declare function createSshSandbox(host: string, options: SshSandboxOptions): Sandbox;