hyperbrane 0.1.1 → 0.2.0

package/dist/sandbox/providers/boat/boatService.js

@@ -0,0 +1,321 @@
+import { randomUUID } from "node:crypto";
+import { posix } from "node:path";
+import { BoatApi, Configuration, ResponseError, waitUntilReady } from "@boatdev/sdk";
+import ssh2 from "ssh2";
+import { SandboxNotFoundError, SandboxStoppedError, } from "../../api.js";
+import { commandLine, quote } from "../../lib/shellCommand.js";
+import { commandFileOperations } from "../../lib/remoteFileOperations.js";
+import { createDescriptor, getDescriptor, openDescriptor } from "../../storage/descriptors.js";
+import { createEndpoints } from "../../data-endpoints/dataEndpoints.js";
+import { createSandboxStorage } from "../../storage/sandboxStorage.js";
+import { sshConnect, sshFetch } from "../ssh/sshTransport.js";
+const BOAT_API_URL = "https://boat.dev/api/v1";
+const COMMAND_TIMEOUT_S = 600;
+const READY_TIMEOUT_MS = 180_000;
+const RUNNING_STATES = ["ready", "idle", "running"];
+const UNDELIVERED = ["localhost_relay_failed", "sandbox_direct_failed"];
+const UNDELIVERED_RETRY_MS = [1000, 2000, 4000];
+const DEFAULT_PORTS = {
+    from: 8900,
+    to: 8999,
+};
+class BoatError extends Error {
+    status;
+    code;
+    name = "BoatError";
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+function apiKeyOf(ctx) {
+    const apiKey = ctx.apikey ?? process.env.BOAT_API_KEY;
+    if (!apiKey)
+        throw new Error("a Boat sandbox needs Boat's API key (apikey, or BOAT_API_KEY)");
+    return apiKey;
+}
+function apiOf(ctx) {
+    return new BoatApi(new Configuration({ basePath: BOAT_API_URL, accessToken: apiKeyOf(ctx) }));
+}
+function sandboxIdOf(ctx) {
+    if (!ctx.id)
+        throw new Error("the Boat sandbox has no id yet: it's set once it's created");
+    return ctx.id;
+}
+function where(ctx) {
+    return `Boat sandbox ${ctx.id ?? "(not created)"}`;
+}
+async function boatOnce(what, call) {
+    try {
+        return await call();
+    }
+    catch (error) {
+        if (!(error instanceof ResponseError))
+            throw error;
+        const text = await error.response.text().catch(() => "");
+        let body = {};
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            body = { message: text };
+        }
+        const code = body.code ?? "";
+        if (code === "machine_not_running")
+            throw new SandboxStoppedError(`${what}: the Boat sandbox is stopped`);
+        throw new BoatError(error.response.status, code, `${what} failed (${error.response.status}${code ? ` ${code}` : ""}): ${body.message ?? text}`);
+    }
+}
+async function boat(what, call) {
+    for (const wait of [...UNDELIVERED_RETRY_MS, null]) {
+        try {
+            return await boatOnce(what, call);
+        }
+        catch (error) {
+            if (wait === null || !(error instanceof BoatError) || !UNDELIVERED.includes(error.code))
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, wait));
+        }
+    }
+    throw new Error(`${what} failed`);
+}
+async function ensureRunning(ctx) {
+    const api = apiOf(ctx);
+    const sandboxId = sandboxIdOf(ctx);
+    const deadline = Date.now() + READY_TIMEOUT_MS;
+    for (;;) {
+        const { sandbox } = await boat(`reading ${where(ctx)}`, () => api.get({ sandboxId }));
+        if (RUNNING_STATES.includes(sandbox.state))
+            return sandbox;
+        if (sandbox.state === "archived") {
+            await boat(`resuming ${where(ctx)}`, () => api.resume({ sandboxId }));
+            return waitUntilReady(api, sandboxId, { timeoutMs: Math.max(1, deadline - Date.now()) });
+        }
+        if (sandbox.state === "error" || sandbox.state === "cancelled")
+            throw new Error(`${where(ctx)} is ${sandbox.state}${sandbox.error ? `: ${sandbox.error}` : ""}`);
+        if (Date.now() > deadline)
+            throw new Error(`${where(ctx)} stayed ${sandbox.state}`);
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+    }
+}
+async function resuming(ctx, call) {
+    try {
+        return await call();
+    }
+    catch (error) {
+        if (!(error instanceof SandboxStoppedError))
+            throw error;
+        await ensureRunning(ctx);
+        return call();
+    }
+}
+async function command(ctx, line, cwd) {
+    const api = apiOf(ctx);
+    const sandboxId = sandboxIdOf(ctx);
+    const result = await boat(`a command in ${where(ctx)}`, () => api.command({ sandboxId, command: line, cwd, timeoutSeconds: COMMAND_TIMEOUT_S }));
+    if (!("exitCode" in result))
+        throw new Error(`a command in ${where(ctx)} was started in the background`);
+    if (result.timedOut)
+        throw new Error(`a command in ${where(ctx)} ran past ${COMMAND_TIMEOUT_S}s`);
+    if (result.stdoutTruncated || result.stderrTruncated)
+        throw new Error(`Boat cut the output of a command in ${where(ctx)} short`);
+    return { exitCode: result.exitCode ?? -1, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+}
+async function upload(ctx, path, data) {
+    const api = apiOf(ctx);
+    const sandboxId = sandboxIdOf(ctx);
+    const content = Buffer.from(data).toString("base64");
+    await boat(`writing ${path} in ${where(ctx)}`, () => api.writeFile({ sandboxId, path, content, encoding: "base64" }));
+}
+async function runCommand(ctx, cmd, { cwd, env, stdin } = {}) {
+    const directory = cwd === undefined ? undefined : posix.resolve("/", cwd);
+    if (stdin === undefined)
+        return resuming(ctx, () => command(ctx, commandLine(cmd, { env }), directory));
+    return resuming(ctx, async () => {
+        const staged = `/tmp/.hyperbrane-stdin-${randomUUID()}`;
+        await upload(ctx, staged, typeof stdin === "string" ? new TextEncoder().encode(stdin) : stdin);
+        return command(ctx, `(${commandLine(cmd, { env })}) < ${quote(staged)}; code=$?; rm -f ${quote(staged)}; exit "$code"`, directory);
+    });
+}
+function boatMachine(ctx) {
+    async function readBytes(path, start, end) {
+        const api = apiOf(ctx);
+        const sandboxId = sandboxIdOf(ctx);
+        try {
+            const { content } = await boat(`reading ${path} in ${where(ctx)}`, () => api.readFile({ sandboxId, path, encoding: "base64" }));
+            const data = new Uint8Array(Buffer.from(content, "base64"));
+            return start === undefined ? data : data.subarray(start, end);
+        }
+        catch (error) {
+            if (error instanceof BoatError && error.status === 404)
+                throw new SandboxNotFoundError(`Not found: "${path}"`);
+            throw error;
+        }
+    }
+    async function putFile(path, data, exclusive) {
+        return resuming(ctx, async () => {
+            const staged = `${posix.dirname(path)}/.${posix.basename(path)}.${randomUUID()}.tmp`;
+            const made = await command(ctx, `mkdir -p ${quote(posix.dirname(path))}`);
+            if (made.exitCode !== 0)
+                throw new Error(`writing ${path} in ${where(ctx)} failed: ${made.stderr.trim()}`);
+            await upload(ctx, staged, data);
+            const placed = exclusive
+                ? await command(ctx, `ln ${quote(staged)} ${quote(path)} 2> /dev/null; code=$?; rm -f ${quote(staged)}; exit "$code"`)
+                : await command(ctx, `mv -f ${quote(staged)} ${quote(path)}`);
+            if (exclusive)
+                return placed.exitCode === 0;
+            if (placed.exitCode !== 0)
+                throw new Error(`writing ${path} in ${where(ctx)} failed: ${placed.stderr.trim()}`);
+            return true;
+        });
+    }
+    return {
+        runCommand: (cmd, options) => runCommand(ctx, cmd, options),
+        readBytes,
+        putFile,
+    };
+}
+async function sshTarget(ctx) {
+    const privateKey = ctx.sshKey;
+    if (!privateKey)
+        throw new Error(`${where(ctx)} has no shell: its context has no SSH key (sshKey)`);
+    const parsed = ssh2.utils.parseKey(privateKey);
+    const key = Array.isArray(parsed) ? parsed[0] : parsed;
+    if (!key || key instanceof Error)
+        throw new Error(`${where(ctx)}'s SSH key can't be read${key instanceof Error ? `: ${key.message}` : ""}`);
+    await ensureRunning(ctx);
+    const api = apiOf(ctx);
+    const sandboxId = sandboxIdOf(ctx);
+    const publicKey = `${key.type} ${key.getPublicSSH().toString("base64")}`;
+    const response = await boat(`adding an SSH key to ${where(ctx)}`, () => api.sshKey({ sandboxId, key: publicKey }));
+    const user = response.sshUser ?? "user";
+    const endpoint = /^(.+):(\d+)$/.exec(response.sshEndpoint ?? "");
+    if (endpoint)
+        return { host: endpoint[1], port: Number(endpoint[2]), user, privateKey };
+    if (response.machineIp)
+        return { host: response.machineIp, port: 22, user, privateKey };
+    throw new Error(`Boat gave no SSH endpoint for ${where(ctx)}`);
+}
+function groupsOf(ctx) {
+    const fileOps = commandFileOperations(boatMachine(ctx));
+    const cmdOps = {
+        runCommand: (cmd, options) => runCommand(ctx, cmd, options),
+    };
+    const netOps = {
+        fetch: async (url, init) => sshFetch(await sshTarget(ctx), url, init),
+        connect: async (path) => sshConnect(await sshTarget(ctx), path),
+    };
+    return { fileOps, cmdOps, netOps };
+}
+function storageOf(ctx) {
+    const { fileOps, cmdOps, netOps } = groupsOf(ctx);
+    return createSandboxStorage({ ...fileOps, ...cmdOps, ...netOps });
+}
+async function create(ctx, spec) {
+    const api = apiOf(ctx);
+    const created = await boat("creating a Boat sandbox", () => api.create({ idempotencyKey: randomUUID() }));
+    const sandboxId = created.sandbox.id;
+    try {
+        await boat(`naming Boat sandbox ${sandboxId}`, () => api.update({ sandboxId, name: spec.name }));
+        await waitUntilReady(api, sandboxId, { timeoutMs: READY_TIMEOUT_MS });
+        return await createDescriptor(ctx, storageOf({ ...ctx, id: sandboxId }), sandboxId, spec);
+    }
+    catch (error) {
+        await boat(`stopping Boat sandbox ${sandboxId}`, () => api.stop({ sandboxId })).catch(() => { });
+        throw error;
+    }
+}
+async function open(ctx, storage) {
+    return openDescriptor(ctx, storage, sandboxIdOf(ctx));
+}
+async function state(ctx) {
+    const api = apiOf(ctx);
+    const sandboxId = sandboxIdOf(ctx);
+    const { sandbox } = await boat(`reading ${where(ctx)}`, () => api.get({ sandboxId }));
+    return RUNNING_STATES.includes(sandbox.state) ? "running" : "stopped";
+}
+async function start(ctx) {
+    await ensureRunning(ctx);
+}
+async function destroy(ctx) {
+    const api = apiOf(ctx);
+    const sandboxId = sandboxIdOf(ctx);
+    await boat(`stopping ${where(ctx)}`, () => api.stop({ sandboxId }));
+}
+function boatPorts(ctx, storage) {
+    async function publish(port, isPublic) {
+        const api = apiOf(ctx);
+        const sandboxId = sandboxIdOf(ctx);
+        const response = await boat(`publishing port ${port} of ${where(ctx)}`, () => api.hostPort({ sandboxId, port, _public: isPublic }));
+        return response.url;
+    }
+    return {
+        ports: async () => (await storage.readDescriptor())?.dataEndpointOptions?.ports ?? DEFAULT_PORTS,
+        async expose(port) {
+            const url = await publish(port, true);
+            if (!url)
+                throw new Error(`Boat gave no URL for port ${port} of ${where(ctx)}`);
+            return url.replace(/\/$/, "");
+        },
+        async conceal(port) {
+            await publish(port, false);
+        },
+    };
+}
+function hasExpiration() {
+    return true;
+}
+async function getExpiration(ctx) {
+    const api = apiOf(ctx);
+    const sandboxId = sandboxIdOf(ctx);
+    const { sandbox } = await boat(`reading ${where(ctx)}`, () => api.get({ sandboxId }));
+    return sandbox.archiveAfter ? new Date(sandbox.archiveAfter) : null;
+}
+async function setExpiration(ctx, seconds) {
+    if (seconds !== null && !(Number.isInteger(seconds) && seconds > 0))
+        throw new Error(`not a number of seconds: ${seconds}`);
+    const api = apiOf(ctx);
+    const sandboxId = sandboxIdOf(ctx);
+    const { sandbox } = await boat(`setting when ${where(ctx)} stops`, () => api.update({ sandboxId, ttlSeconds: seconds }));
+    return sandbox.archiveAfter ? new Date(sandbox.archiveAfter) : null;
+}
+function hasShell(ctx) {
+    return ctx.sshKey !== undefined;
+}
+async function sshEndpoint(ctx) {
+    return sshTarget(ctx);
+}
+export function createBoatService(ctx) {
+    apiKeyOf(ctx);
+    const { fileOps, cmdOps, netOps } = groupsOf(ctx);
+    const machine = { ...fileOps, ...cmdOps, ...netOps };
+    const storage = createSandboxStorage(machine);
+    const lifecycleOps = {
+        create: (spec) => create(ctx, spec),
+        open: () => resuming(ctx, () => open(ctx, storage)),
+        get: () => getDescriptor(storage, where(ctx)),
+        state: () => state(ctx),
+        start: () => start(ctx),
+        destroy: () => destroy(ctx),
+    };
+    const dataOps = createEndpoints(machine, storage, boatPorts(ctx, storage));
+    const expirationOps = {
+        hasExpiration,
+        getExpiration: () => getExpiration(ctx),
+        setExpiration: (seconds) => setExpiration(ctx, seconds),
+    };
+    const shellOps = {
+        hasShell: () => hasShell(ctx),
+        sshEndpoint: () => sshEndpoint(ctx),
+    };
+    return {
+        ...fileOps,
+        ...lifecycleOps,
+        ...cmdOps,
+        ...dataOps,
+        ...expirationOps,
+        ...shellOps,
+        ...netOps,
+    };
+}

package/dist/sandbox/providers/exedev/exeDevService.d.ts

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

package/dist/sandbox/providers/exedev/exeDevService.js

@@ -0,0 +1,127 @@
+import { userInfo } from "node:os";
+import { commandFileOperations } from "../../lib/remoteFileOperations.js";
+import { createDescriptor, getDescriptor, openDescriptor } from "../../storage/descriptors.js";
+import { createEndpoints } from "../../data-endpoints/dataEndpoints.js";
+import { createSandboxStorage } from "../../storage/sandboxStorage.js";
+import { sshCommand, sshConnect, sshFetch, sshMachine } from "../ssh/sshTransport.js";
+import { signExeDevToken } from "./exeDevToken.js";
+const VM_NAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+const FORWARDED = {
+    from: 3000,
+    to: 9999,
+};
+const DEFAULT_PORTS = {
+    from: 9000,
+    to: 9099,
+};
+function vmOf(ctx) {
+    if (!ctx.id)
+        throw new Error("an exe.dev VM needs its name (id)");
+    if (!VM_NAME.test(ctx.id))
+        throw new Error(`not an exe.dev VM name: "${ctx.id}"`);
+    return ctx.id;
+}
+function target(ctx) {
+    if (!ctx.sshKey)
+        throw new Error(`exe.dev VM ${ctx.id ?? "(no name)"} needs the account's SSH key (sshKey)`);
+    if (ctx.sshHost)
+        return { host: ctx.sshHost, port: ctx.sshPort ?? 22, user: ctx.sshUser ?? userInfo().username, privateKey: ctx.sshKey };
+    return { host: "vm.exe.xyz", port: 22, user: `vm+${vmOf(ctx)}`, privateKey: ctx.sshKey };
+}
+function where(ctx) {
+    return `exe.dev VM ${ctx.id ?? "(no name)"}`;
+}
+function groupsOf(ctx) {
+    const fileOps = commandFileOperations(sshMachine(() => target(ctx)));
+    const cmdOps = {
+        runCommand: (cmd, options) => sshCommand(target(ctx), cmd, options),
+    };
+    const netOps = {
+        fetch: (url, init) => sshFetch(target(ctx), url, init),
+        connect: (path) => sshConnect(target(ctx), path),
+    };
+    return { fileOps, cmdOps, netOps };
+}
+function storageOf(ctx) {
+    const { fileOps, cmdOps, netOps } = groupsOf(ctx);
+    return createSandboxStorage({ ...fileOps, ...cmdOps, ...netOps });
+}
+async function create(ctx, spec) {
+    const id = ctx.id ?? spec.name;
+    return createDescriptor(ctx, storageOf({ ...ctx, id }), id, spec);
+}
+async function open(ctx, storage) {
+    return openDescriptor(ctx, storage, vmOf(ctx));
+}
+async function state() {
+    return "running";
+}
+async function start() { }
+async function destroy() { }
+function hasExpiration() {
+    return false;
+}
+async function getExpiration() {
+    return null;
+}
+async function setExpiration() {
+    return null;
+}
+function hasShell(ctx) {
+    return ctx.id !== undefined && ctx.sshKey !== undefined;
+}
+async function sshEndpoint(ctx) {
+    return target(ctx);
+}
+function exeDevPorts(ctx, storage) {
+    return {
+        async ports() {
+            const ports = (await storage.readDescriptor())?.dataEndpointOptions?.ports ?? DEFAULT_PORTS;
+            if (ports.from < FORWARDED.from || ports.to > FORWARDED.to)
+                throw new Error(`exe.dev forwards ports ${FORWARDED.from}-${FORWARDED.to}, not ${ports.from}-${ports.to}`);
+            return ports;
+        },
+        async expose(port) {
+            return `https://${vmOf(ctx)}.exe.xyz:${port}`;
+        },
+        async conceal() { },
+        async credentials(_endpoint, ttlSeconds) {
+            if (!ctx.sshKey)
+                throw new Error(`${where(ctx)} needs the account's SSH key (sshKey) to sign exe.dev tokens`);
+            const exp = Math.floor(Date.now() / 1000) + ttlSeconds;
+            return { exeDev: { token: signExeDevToken(ctx.sshKey, `v0@${vmOf(ctx)}.exe.xyz`, { exp }) } };
+        },
+    };
+}
+export function createExeDevService(ctx) {
+    const { fileOps, cmdOps, netOps } = groupsOf(ctx);
+    const machine = { ...fileOps, ...cmdOps, ...netOps };
+    const storage = createSandboxStorage(machine);
+    const lifecycleOps = {
+        create: (spec) => create(ctx, spec),
+        open: () => open(ctx, storage),
+        get: () => getDescriptor(storage, where(ctx)),
+        state,
+        start,
+        destroy,
+    };
+    const dataOps = createEndpoints(machine, storage, exeDevPorts(ctx, storage));
+    const expirationOps = {
+        hasExpiration,
+        getExpiration,
+        setExpiration,
+    };
+    const shellOps = {
+        hasShell: () => hasShell(ctx),
+        sshEndpoint: () => sshEndpoint(ctx),
+    };
+    return {
+        ...fileOps,
+        ...lifecycleOps,
+        ...cmdOps,
+        ...dataOps,
+        ...expirationOps,
+        ...shellOps,
+        ...netOps,
+    };
+}

package/dist/sandbox/providers/exedev/exeDevToken.d.ts

@@ -0,0 +1 @@
+export declare function signExeDevToken(privateKey: string, namespace: string, permissions: Record<string, unknown>): string;

package/dist/sandbox/providers/exedev/exeDevToken.js

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+import ssh2 from "ssh2";
+function sshString(value) {
+    const bytes = typeof value === "string" ? Buffer.from(value) : value;
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(bytes.length);
+    return Buffer.concat([length, bytes]);
+}
+function privateKeyOf(privateKey) {
+    const parsed = ssh2.utils.parseKey(privateKey);
+    const key = Array.isArray(parsed) ? parsed[0] : parsed;
+    if (!key || key instanceof Error || !key.isPrivateKey())
+        throw new Error(`the exe.dev key isn't a usable private key${key instanceof Error ? `: ${key.message}` : ""}`);
+    return key;
+}
+function ecdsaBlob(der) {
+    let offset = 2 + (der[1] & 0x80 ? der[1] & 0x7f : 0);
+    const integers = [];
+    for (let i = 0; i < 2; i++) {
+        const length = der[offset + 1];
+        integers.push(sshString(der.subarray(offset + 2, offset + 2 + length)));
+        offset += 2 + length;
+    }
+    return Buffer.concat(integers);
+}
+function signed(key, data) {
+    if (key.type === "ssh-ed25519")
+        return [key.type, key.sign(data)];
+    if (key.type === "ssh-rsa")
+        return ["rsa-sha2-512", key.sign(data, "sha512")];
+    if (key.type.startsWith("ecdsa-sha2-"))
+        return [key.type, ecdsaBlob(key.sign(data))];
+    throw new Error(`exe.dev tokens can't be signed with a ${key.type} key`);
+}
+function sshSignature(key, namespace, message) {
+    const magic = Buffer.from("SSHSIG");
+    const hash = createHash("sha512").update(message).digest();
+    const [algorithm, signature] = signed(key, Buffer.concat([magic, sshString(namespace), sshString(""), sshString("sha512"), sshString(hash)]));
+    const version = Buffer.alloc(4);
+    version.writeUInt32BE(1);
+    return Buffer.concat([
+        magic,
+        version,
+        sshString(key.getPublicSSH()),
+        sshString(namespace),
+        sshString(""),
+        sshString("sha512"),
+        sshString(Buffer.concat([sshString(algorithm), sshString(signature)])),
+    ]);
+}
+export function signExeDevToken(privateKey, namespace, permissions) {
+    const payload = Buffer.from(JSON.stringify(permissions));
+    return `exe0.${payload.toString("base64url")}.${sshSignature(privateKeyOf(privateKey), namespace, payload).toString("base64url")}`;
+}

package/dist/sandbox/providers/local/localService.d.ts

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