hyperbrane 0.1.2 → 0.2.0

package/dist/sandbox/api.d.ts

@@ -1,221 +1,155 @@
-export type RunCommandOptions = {
-    /** Sandbox path; defaults to the sandbox root. */
-    cwd?: string;
-    env?: Record<string, string>;
-    stdin?: string | Uint8Array;
-};
-export type RunCommandResult = {
-    readonly exitCode: number;
-    readonly stdout: string;
-    readonly stderr: string;
-};
+/** @sealed */
+export interface SandboxFileOperations {
+    readFile(path: string): Promise<Uint8Array>;
+    readFileRange(path: string, start: number, end: number): Promise<Uint8Array>;
+    writeFile(path: string, data: string | Uint8Array): Promise<void>;
+    writeFileExclusive(path: string, data: string | Uint8Array): Promise<boolean>;
+    removeFile(path: string): Promise<void>;
+    createDirectory(path: string): Promise<void>;
+    removeDirectory(path: string): Promise<void>;
+    listDirectory(path: string): Promise<string[]>;
+    stat(path: string): Promise<SandboxFileInfo>;
+    homeDirectory(): Promise<string>;
+}
+/** @sealed */
+export interface SandboxLifecycle {
+    create(spec: SandboxSpec): Promise<[SandboxAuthContext, SandboxDescriptor]>;
+    open(): Promise<SandboxDescriptor>;
+    get(): Promise<SandboxDescriptor>;
+    state(): Promise<"running" | "stopped">;
+    start(): Promise<void>;
+    destroy(): Promise<void>;
+}
+/** @sealed */
+export interface SandboxCommands {
+    runCommand(cmd: string[], options?: RunCommandOptions): Promise<RunCommandResult>;
+}
+/** @sealed */
+export interface SandboxDataEndpoint {
+    openEndpoint(name: string): Promise<SandboxEndpoint>;
+    closeEndpoint(name: string): Promise<void>;
+    listEndpoints(): Promise<SandboxEndpoint[]>;
+    credentials(name: string, options?: {
+        ttlSeconds?: number;
+    }): Promise<SandboxCredentials>;
+}
+/** @sealed */
+export interface SandboxExpiration {
+    hasExpiration(): boolean;
+    getExpiration(): Promise<Date | null>;
+    setExpiration(seconds: number | null): Promise<Date | null>;
+}
+/** @sealed */
+export interface SandboxShell {
+    hasShell(): boolean;
+    sshEndpoint(): Promise<SandboxSshEndpoint>;
+}
+/** @sealed */
+export interface SandboxNetwork {
+    fetch(url: string, init?: SandboxFetchInit): Promise<Response>;
+    connect(path: string): Promise<SandboxConnection>;
+}
+/** @sealed */
+export interface SandboxClient extends SandboxFileOperations, SandboxCommands, SandboxNetwork, SandboxLifecycle, SandboxDataEndpoint, SandboxShell, SandboxExpiration {
+}
+/** @sealed */
+export interface SandboxService extends SandboxFileOperations, SandboxCommands, SandboxNetwork, SandboxLifecycle, SandboxDataEndpoint, SandboxShell, SandboxExpiration {
+}
 export type SandboxFileInfo = {
     readonly type: "file" | "directory" | "other";
     readonly uid: number;
     readonly gid: number;
-    /** In bytes; what the system reports for anything that isn't a file. */
     readonly size: number;
 };
 export type SandboxFetchInit = {
     method?: string;
     headers?: Record<string, string>;
     body?: string | Uint8Array<ArrayBuffer>;
-    /** Sandbox path of a unix socket to send the request over (e.g. the docker API socket). */
     unix?: string;
     signal?: AbortSignal;
-    /**
-     * Idle timeout in milliseconds: the request fails once nothing has been sent or received for this
-     * long. `false` disables it, for streams that can stay quiet indefinitely. Defaults to the backend's.
-     */
     timeout?: number | false;
 };
-/**
- * A stream connection to a unix socket inside a sandbox (see Sandbox.connect).
- *
- * @sealed
- */
+/** @sealed */
 export type SandboxConnection = {
     write(data: Uint8Array): void;
-    /** Receives every chunk read from the socket, in order. */
     onData(listener: (data: Uint8Array) => void): void;
-    /** Resolves once the connection is closed, by either side or by an error. */
     closed: Promise<void>;
     close(): void;
 };
-/** What an accessible endpoint forwards to, inside the sandbox. */
-export type SandboxEndpointTarget = {
-    port: number;
-} | {
-    unix: string;
-};
-/**
- * What a client must present to an accessible endpoint. There is deliberately no unauthenticated
- * variant: every endpoint requires one of these.
- */
-export type SandboxEndpointCredentials = 
-/** `Authorization: Bearer <token>`. */
-{
-    readonly scheme: "bearer";
+/** @sealed */
+export type SandboxCredentials = {
     readonly token: string;
-}
-/** `Authorization: Basic ...`; browsers prompt for it on their own. */
- | {
-    readonly scheme: "basic";
-    readonly username: string;
-    readonly password: string;
-}
-/**
- * Logged in with exe.dev, as a user the VM is shared with; exe.dev's proxy checks it (exeDevAuth.ts).
- * The login is per port: a browser that isn't logged in on the endpoint's goes through `loginUrl`
- * first (exeDevLoginUrl in agent/session/workerSseConnection.ts).
- */
- | {
-    readonly scheme: "exe.dev";
-    readonly loginUrl: string;
-};
-export type SandboxEndpointScheme = SandboxEndpointCredentials["scheme"];
-export type SandboxEndpointRequest = {
-    target: SandboxEndpointTarget;
-    /** Required: the endpoint is never open to unauthenticated clients. */
-    scheme: SandboxEndpointScheme;
-    /** Port the endpoint listens on; a free one (that its auth allows) if omitted. */
-    port?: number;
-    /**
-     * "http" (the default): the target speaks HTTP, and requests go through to it. "sse": the target
-     * is a stream socket speaking lines of text (an agent worker's JSON-RPC); each `GET /` opens a
-     * connection to it and streams its lines back as server-sent events, and `POST /<connection>`
-     * writes the request body to it (see endpointProxy.ts).
-     */
-    transport?: "http" | "sse";
-    /**
-     * Web origins (e.g. "https://app.example.com") whose pages may call the endpoint from a browser:
-     * the proxy answers their CORS preflights and lets them read "sse" responses. None by default.
-     */
-    allowedOrigins?: string[];
+    readonly exeDev?: {
+        readonly token: string;
+    };
 };
 export type SandboxEndpoint = {
-    readonly id: string;
-    /**
-     * Where the client reaches the endpoint, directly over the network (not through the backend's own
-     * connection), at the host the sandbox was created with. It lasts until the endpoint is closed,
-     * but what serves it may stop (a reboot, an archived Boat sandbox): ensureEndpoint starts it again.
-     * Until then a browser reports a request to it as a CORS error, since nothing of the endpoint's answers.
-     */
+    readonly name: string;
     readonly url: string;
-    /** What the client presents; requests without it are refused before reaching the target. */
-    readonly credentials: SandboxEndpointCredentials;
-    /** As requested, or as updateEndpoint changed them since. */
-    readonly allowedOrigins: string[];
+    readonly port: number;
+    readonly secret: string;
 };
-/**
- * Paths are sandbox paths: relative or absolute, both resolved against the sandbox root.
- * Operations that report a missing path throw SandboxNotFoundError, whatever the backend.
- *
- * @sealed
- */
-export interface SandboxFileOperations {
-    /** Throws SandboxNotFoundError if missing. */
-    readFile(path: string): Promise<Uint8Array>;
-    /**
-     * Bytes `start` up to `end` (exclusive) of the file, fewer where the file ends sooner, so a large
-     * file can be read a part at a time. Throws SandboxNotFoundError if missing.
-     */
-    readFileRange(path: string, start: number, end: number): Promise<Uint8Array>;
-    /** Atomically replaces the file (readers never see partial content). Creates missing parent directories. */
-    writeFile(path: string, data: string | Uint8Array): Promise<void>;
-    /**
-     * Writes the file only if it doesn't exist yet; returns false if it does. Atomic across concurrent
-     * callers and never exposes partial content. Creates missing parent directories.
-     */
-    writeFileExclusive(path: string, data: string | Uint8Array): Promise<boolean>;
-    /** No-op if missing. */
-    removeFile(path: string): Promise<void>;
-    /** Creates missing parents; no-op if it exists. */
-    createDirectory(path: string): Promise<void>;
-    /** Removes the directory and everything in it. No-op if missing. */
-    removeDirectory(path: string): Promise<void>;
-    /** Entry names, unsorted. Throws SandboxNotFoundError if missing. */
-    listDirectory(path: string): Promise<string[]>;
-    /** Throws SandboxNotFoundError if missing. */
-    stat(path: string): Promise<SandboxFileInfo>;
-    /** Sandbox path of the home directory of the user operations run as. */
-    homeDirectory(): Promise<string>;
-}
-/** @sealed */
-export interface SandboxCommands {
-    runCommand(cmd: string[], options?: RunCommandOptions): Promise<RunCommandResult>;
-}
-/**
- * Reaching into the sandbox from the caller's side.
- *
- * @sealed
- */
-export interface SandboxNetwork {
-    /** HTTP request made from inside the sandbox. */
-    fetch(url: string, init?: SandboxFetchInit): Promise<Response>;
-    /** Opens a stream connection to the unix socket at `path` (e.g. an agent worker's). */
-    connect(path: string): Promise<SandboxConnection>;
-}
-/**
- * Makes something listening in the sandbox reachable from the SDK's client over the network, without
- * going through the backend's own connection. Declared when the sandbox is created (with the host
- * clients reach it at), by the backends that can. Always authenticated: a scheme the sandbox's auth
- * can't enforce is refused with SandboxEndpointError. An endpoint lasts until it is closed, past the
- * sandbox object that exposed it.
- *
- * @sealed
- */
-export interface SandboxAccessibleEndpoint {
-    /**
-     * How clients reach the machine, as the sandbox was created with ("host" or "host:port"). Several
-     * sandboxes may drive the same machine, each reached its own way: their endpoints are their own.
-     */
-    readonly accessibleHost: string;
-    exposeEndpoint(request: SandboxEndpointRequest): Promise<SandboxEndpoint>;
-    /** Stops accepting connections and revokes its credentials. No-op if already closed. */
-    closeEndpoint(endpointId: string): Promise<void>;
-    /**
-     * Makes sure it is served, starting its proxy again if that stopped (a reboot), with the same URL
-     * and credentials; false if it was closed, or its port has since been taken (expose another).
-     */
-    ensureEndpoint(endpointId: string): Promise<boolean>;
-    /**
-     * Changes which web origins may call the endpoint, in place: its URL and credentials stay, and so
-     * do connections already open. False if it was closed.
-     */
-    updateEndpoint(endpointId: string, update: {
-        allowedOrigins: string[];
-    }): Promise<boolean>;
-}
-/**
- * A sandbox that stops itself on a timer (Boat).
- *
- * @sealed
- */
-export interface SandboxExpiration {
-    /** When it stops itself; null if it never does. */
-    getExpiration(): Promise<Date | null>;
-    /** Makes it stop itself `seconds` from now; null: never. Returns when it now will. */
-    setExpiration(seconds: number | null): Promise<Date | null>;
-}
-/** Whether the sandbox has the SandboxExpiration capability. */
-export declare function hasExpiration<T extends object>(sandbox: T): sandbox is T & SandboxExpiration;
-/**
- * What every backend provides.
- *
- * @sealed
- */
-export type Sandbox = SandboxFileOperations & SandboxCommands & SandboxNetwork & {
-    /** Releases what the sandbox holds open (a remote connection). Optional: most hold nothing. */
-    close?(): void;
+export type SandboxAccess = {
+    readonly url: string;
+    readonly credentials: SandboxCredentials;
+};
+export type RunCommandOptions = {
+    cwd?: string;
+    env?: Record<string, string>;
+    stdin?: string | Uint8Array;
+};
+export type RunCommandResult = {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+};
+export type SandboxSshEndpoint = {
+    readonly host: string;
+    readonly port: number;
+    readonly user: string;
+    readonly privateKey: string;
+};
+export type SandboxAuthContext = {
+    kind: "boat" | "exe.dev" | "ssh" | "local";
+    id?: string;
+    sshHost?: string;
+    sshUser?: string;
+    sshPort?: number;
+    sshKey?: string;
+    apikey?: string;
+};
+export type SandboxDataEndpointOptions = {
+    url?: string;
+    ports?: {
+        from: number;
+        to: number;
+    };
+    needsFirewall?: boolean;
+};
+export type SandboxSpec = {
+    name: string;
+    dataEndpointOptions?: SandboxDataEndpointOptions;
+};
+export type SandboxDescriptor = {
+    id: string;
+    kind: SandboxAuthContext["kind"];
+    name: string;
+    sshHost?: string;
+    sshUser?: string;
+    sshPort?: number;
+    dataEndpointOptions?: SandboxDataEndpointOptions;
 };
+/** @sealed */
+export type Sandbox = SandboxFileOperations & SandboxCommands & SandboxNetwork & {};
 export declare class SandboxPathError extends Error {
     name: string;
 }
 export declare class SandboxNotFoundError extends Error {
     name: string;
 }
-/** The endpoint can't be exposed as asked (a scheme or port its auth doesn't allow, ...). */
-export declare class SandboxEndpointError extends Error {
+export declare class SandboxStoppedError extends Error {
+    name: string;
+}
+export declare class SandboxConnectionRefusedError extends Error {
     name: string;
 }

package/dist/sandbox/api.js

@@ -1,14 +1,12 @@
-/** Whether the sandbox has the SandboxExpiration capability. */
-export function hasExpiration(sandbox) {
-    return "getExpiration" in sandbox && "setExpiration" in sandbox;
-}
 export class SandboxPathError extends Error {
     name = "SandboxPathError";
 }
 export class SandboxNotFoundError extends Error {
     name = "SandboxNotFoundError";
 }
-/** The endpoint can't be exposed as asked (a scheme or port its auth doesn't allow, ...). */
-export class SandboxEndpointError extends Error {
-    name = "SandboxEndpointError";
+export class SandboxStoppedError extends Error {
+    name = "SandboxStoppedError";
+}
+export class SandboxConnectionRefusedError extends Error {
+    name = "SandboxConnectionRefusedError";
 }

package/dist/sandbox/client.d.ts

@@ -0,0 +1,2 @@
+import type { SandboxAuthContext, SandboxClient } from "./api.ts";
+export declare function createSandboxClient(ctx: SandboxAuthContext): SandboxClient;

package/dist/sandbox/client.js

@@ -0,0 +1,4 @@
+import { createSandboxService } from "./service.js";
+export function createSandboxClient(ctx) {
+    return createSandboxService(ctx);
+}

package/dist/sandbox/data-endpoints/dataEndpoints.d.ts

@@ -0,0 +1,13 @@
+import { type Sandbox, type SandboxCredentials, type SandboxDataEndpoint, type SandboxEndpoint } from "../api.ts";
+import type { SandboxStorage } from "../storage/sandboxStorage.ts";
+export type EndpointPorts = {
+    ports(): Promise<{
+        from: number;
+        to: number;
+    }>;
+    expose(port: number): Promise<string>;
+    conceal(port: number): Promise<void>;
+    credentials?(endpoint: SandboxEndpoint, ttlSeconds: number): Promise<Omit<SandboxCredentials, "token">>;
+};
+export declare function signToken(secret: string, ttlSeconds: number): Promise<string>;
+export declare function createEndpoints(sandbox: Sandbox, storage: SandboxStorage, ports: EndpointPorts): SandboxDataEndpoint;

package/dist/sandbox/data-endpoints/dataEndpoints.js

@@ -0,0 +1,100 @@
+import { randomBytes } from "node:crypto";
+import { SignJWT } from "jose";
+import { sh } from "../../lib/sh.js";
+import { SandboxNotFoundError } from "../api.js";
+const DEFAULT_TTL_S = 12 * 3600;
+export function signToken(secret, ttlSeconds) {
+    return new SignJWT()
+        .setProtectedHeader({ alg: "HS256" })
+        .setExpirationTime(`${ttlSeconds}s`)
+        .sign(new TextEncoder().encode(secret));
+}
+async function listeningPorts(sandbox) {
+    const listed = await sandbox.runCommand(["sh", "-c", LISTENING_PORTS]);
+    if (listed.exitCode !== 0)
+        throw new Error(`listing the ports in use failed: ${listed.stderr.trim()}`);
+    return listed.stdout.split("\n").filter(Boolean).map(Number);
+}
+async function withLock(sandbox, body) {
+    const lock = `${await sandbox.homeDirectory()}/.local/state/hyperbrane/endpoints.lock`;
+    const taken = await sandbox.runCommand(["sh", "-c", TAKE_LOCK, "sh", lock]);
+    if (taken.exitCode !== 0)
+        throw new Error(`${lock} stayed locked: ${taken.stderr.trim()}`);
+    try {
+        return await body();
+    }
+    finally {
+        await sandbox.runCommand(["rm", "-rf", lock]);
+    }
+}
+function under(base, endpoint) {
+    if (base === undefined || new URL(base).pathname === "/")
+        return endpoint;
+    return { ...endpoint, url: `${base.replace(/\/+$/, "")}/${endpoint.name}` };
+}
+export function createEndpoints(sandbox, storage, ports) {
+    const located = async (endpoints) => {
+        const base = (await storage.readDescriptor())?.dataEndpointOptions?.url;
+        return endpoints.map((endpoint) => under(base, endpoint));
+    };
+    async function openEndpoint(name) {
+        const [endpoint] = await located([await openStored(name)]);
+        return endpoint;
+    }
+    async function openStored(name) {
+        return withLock(sandbox, async () => {
+            const existing = await storage.readEndpoint(name);
+            if (existing)
+                return existing;
+            const { from, to } = await ports.ports();
+            const used = new Set([...(await storage.listEndpoints()).map((endpoint) => endpoint.port), ...(await listeningPorts(sandbox))]);
+            let port = from;
+            while (port <= to && used.has(port))
+                port++;
+            if (port > to)
+                throw new Error(`no data endpoint ports are left in ${from}-${to}`);
+            const endpoint = { name, url: await ports.expose(port), port, secret: randomBytes(32).toString("base64url") };
+            await storage.saveEndpoint(endpoint);
+            return endpoint;
+        });
+    }
+    async function closeEndpoint(name) {
+        await withLock(sandbox, async () => {
+            const endpoint = await storage.readEndpoint(name);
+            if (!endpoint)
+                return;
+            await ports.conceal(endpoint.port);
+            await storage.removeEndpoint(name);
+        });
+    }
+    async function credentials(name, { ttlSeconds = DEFAULT_TTL_S, } = {}) {
+        const endpoint = await storage.readEndpoint(name);
+        if (!endpoint)
+            throw new SandboxNotFoundError(`there is no data endpoint ${name}`);
+        return { token: await signToken(endpoint.secret, ttlSeconds), ...(await ports.credentials?.(endpoint, ttlSeconds)) };
+    }
+    return {
+        openEndpoint,
+        closeEndpoint,
+        listEndpoints: async () => located(await storage.listEndpoints()),
+        credentials,
+    };
+}
+const LISTENING_PORTS = sh `
+awk 'FNR > 1 && $4 == "0A" { n = split($2, local, ":"); print local[n] }' /proc/net/tcp /proc/net/tcp6 2> /dev/null | while read -r hex; do
+  printf '%d\n' "0x$hex"
+done
+`;
+const TAKE_LOCK = sh `
+mkdir -p "$(dirname "$1")"
+waited=0
+until mkdir "$1" 2> /dev/null; do
+  if [ -n "$(find "$1" -maxdepth 0 -mmin +2 2> /dev/null)" ]; then
+    rm -rf "$1"
+    continue
+  fi
+  [ "$waited" -lt 1200 ] || exit 1
+  sleep 0.1
+  waited=$((waited + 1))
+done
+`;

package/dist/sandbox/data-endpoints/firewalledPorts.d.ts

@@ -0,0 +1,4 @@
+import type { Sandbox } from "../api.ts";
+import type { SandboxStorage } from "../storage/sandboxStorage.ts";
+import type { EndpointPorts } from "./dataEndpoints.ts";
+export declare function firewalledPorts(sandbox: Sandbox, storage: SandboxStorage): EndpointPorts;

package/dist/sandbox/data-endpoints/firewalledPorts.js

@@ -0,0 +1,28 @@
+export function firewalledPorts(sandbox, storage) {
+    const options = async () => (await storage.readDescriptor())?.dataEndpointOptions;
+    async function firewall(rule) {
+        const result = await sandbox.runCommand(["sudo", "-n", "ufw", ...rule]);
+        if (result.exitCode !== 0)
+            throw new Error(`ufw ${rule.join(" ")} failed: ${result.stderr.trim()}`);
+    }
+    return {
+        async ports() {
+            const ports = (await options())?.ports;
+            if (!ports)
+                throw new Error("this machine has no data endpoints: it's created with dataEndpointOptions.ports");
+            return ports;
+        },
+        async expose(port) {
+            const found = await options();
+            if (found?.needsFirewall)
+                await firewall(["allow", `${port}/tcp`]);
+            const url = new URL(found?.url ?? "http://127.0.0.1");
+            url.port = String(port);
+            return url.toString().replace(/\/$/, "");
+        },
+        async conceal(port) {
+            if ((await options())?.needsFirewall)
+                await firewall(["delete", "allow", `${port}/tcp`]);
+        },
+    };
+}

package/dist/sandbox/lib/httpOverStream.d.ts

@@ -0,0 +1,3 @@
+import { type Duplex } from "node:stream";
+import type { SandboxFetchInit } from "../api.ts";
+export declare function httpOver(url: string, connection: () => Duplex, { method, headers, body, signal, timeout }: Omit<SandboxFetchInit, "unix">): Promise<Response>;

package/dist/sandbox/lib/httpOverStream.js

@@ -0,0 +1,21 @@
+import { request as httpRequest } from "node:http";
+import { Readable } from "node:stream";
+export function httpOver(url, connection, { method = "GET", headers = {}, body, signal, timeout }) {
+    return new Promise((resolve, reject) => {
+        const target = new URL(url);
+        const request = httpRequest({ createConnection: connection, 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;
+            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));
+    });
+}

package/dist/sandbox/lib/remoteFileOperations.d.ts

@@ -0,0 +1,10 @@
+import { type RunCommandOptions, type RunCommandResult, type SandboxFileOperations } from "../api.ts";
+export declare const MISSING = 44;
+export type CommandMachine = {
+    runCommand(cmd: string[], options?: RunCommandOptions): Promise<RunCommandResult>;
+    readBytes(path: string, start?: number, end?: number): Promise<Uint8Array>;
+    putFile(path: string, data: Uint8Array, exclusive: boolean): Promise<boolean>;
+};
+export declare function commandFileOperations(machine: CommandMachine): SandboxFileOperations;
+export declare const PUT_FILE: string;
+export declare const READ_BYTES: string;

package/dist/sandbox/lib/remoteFileOperations.js

@@ -0,0 +1,70 @@
+import { posix } from "node:path";
+import { sh } from "../../lib/sh.js";
+import { SandboxNotFoundError } from "../api.js";
+export const MISSING = 44;
+function remote(path) {
+    return posix.resolve("/", path);
+}
+function bytes(data) {
+    return typeof data === "string" ? new TextEncoder().encode(data) : data;
+}
+async function script(machine, what, path, body) {
+    const result = await machine.runCommand(["sh", "-c", body, "sh", path], { env: { MISSING: String(MISSING) } });
+    if (result.exitCode === MISSING)
+        throw new SandboxNotFoundError(`Not found: "${path}"`);
+    if (result.exitCode !== 0)
+        throw new Error(`${what} ${path} failed: ${result.stderr.trim()}`);
+    return result.stdout;
+}
+export function commandFileOperations(machine) {
+    return {
+        readFile: (path) => machine.readBytes(remote(path)),
+        readFileRange: (path, start, end) => machine.readBytes(remote(path), start, end),
+        writeFile: async (path, data) => void (await machine.putFile(remote(path), bytes(data), false)),
+        writeFileExclusive: (path, data) => machine.putFile(remote(path), bytes(data), true),
+        removeFile: async (path) => void (await script(machine, "removing", remote(path), REMOVE_FILE)),
+        createDirectory: async (path) => void (await script(machine, "creating", remote(path), CREATE_DIRECTORY)),
+        removeDirectory: async (path) => void (await script(machine, "removing", remote(path), REMOVE_DIRECTORY)),
+        listDirectory: async (path) => (await script(machine, "listing", remote(path), LIST_DIRECTORY)).split("\0").filter(Boolean),
+        async stat(path) {
+            const [type, uid, gid, size] = (await script(machine, "reading", remote(path), STAT)).trim().split(" ");
+            return { type: type, uid: Number(uid), gid: Number(gid), size: Number(size) };
+        },
+        homeDirectory: async () => (await script(machine, "reading", "~", HOME)).trim(),
+    };
+}
+export const PUT_FILE = sh `
+set -eu
+mkdir -p "$(dirname "$1")"
+staged="$(dirname "$1")/.$(basename "$1").$$.tmp"
+trap 'rm -f "$staged"' EXIT
+cat > "$staged"
+if [ "$EXCLUSIVE" = 1 ]; then
+  ln "$staged" "$1" 2> /dev/null || exit "$EXISTS"
+else
+  mv -f "$staged" "$1"
+fi
+`;
+export const READ_BYTES = sh `
+[ -f "$1" ] || exit "$MISSING"
+if [ -z "$START" ]; then exec cat "$1"; fi
+tail -c "+$((START + 1))" "$1" | head -c "$((END - START))"
+`;
+const REMOVE_FILE = sh `rm -f "$1"`;
+const CREATE_DIRECTORY = sh `mkdir -p "$1"`;
+const REMOVE_DIRECTORY = sh `rm -rf "$1"`;
+const LIST_DIRECTORY = sh `
+[ -e "$1" ] || exit "$MISSING"
+cd "$1" || exit 1
+for name in .* *; do
+  case "$name" in . | ..) continue ;; esac
+  [ -e "$name" ] || [ -L "$name" ] || continue
+  printf '%s\0' "$name"
+done
+`;
+const STAT = sh `
+[ -e "$1" ] || exit "$MISSING"
+if [ -f "$1" ]; then kind="file"; elif [ -d "$1" ]; then kind="directory"; else kind="other"; fi
+printf '%s %s\n' "$kind" "$(stat -c '%u %g %s' "$1")"
+`;
+const HOME = sh `printf '%s\n' "$HOME"`;

package/dist/sandbox/lib/shellCommand.d.ts

@@ -0,0 +1,3 @@
+import type { RunCommandOptions } from "../api.ts";
+export declare function quote(word: string): string;
+export declare function commandLine(cmd: string[], { cwd, env }?: Pick<RunCommandOptions, "cwd" | "env">): string;

package/dist/sandbox/lib/shellCommand.js

@@ -0,0 +1,7 @@
+export function quote(word) {
+    return `'${word.replaceAll("'", `'\\''`)}'`;
+}
+export function commandLine(cmd, { cwd, env = {} } = {}) {
+    const words = ["env", ...Object.entries(env).map(([name, value]) => `${name}=${value}`), ...cmd].map(quote).join(" ");
+    return cwd === undefined ? `exec ${words}` : `cd ${quote(cwd)} && exec ${words}`;
+}

package/dist/sandbox/providers/boat/boatService.d.ts

@@ -0,0 +1,2 @@
+import { type SandboxAuthContext, type SandboxService } from "../../api.ts";
+export declare function createBoatService(ctx: SandboxAuthContext): SandboxService;