hyperbrane 0.1.0 → 0.1.2

package/dist/portal-gateway/portalService.js

@@ -180,17 +180,25 @@ export function createPortalService(storage, gateways, docker, image, host) {
             return;
         if (record.state !== "destroying")
             await storage.savePortal({ ...record, state: "destroying" });
+        // A restore under way finishes first (seeing the mark, it undoes what it wired), so nothing it
+        // does lands after this returns; one that starts from now on sees the mark and does nothing.
+        while (restoring.has(portalName))
+            await restoring.get(portalName).catch(() => { });
         if (record.subnet !== undefined) {
             await ignoringStopped(() => unwire(record.gatewayName, portalLink(portalName, record.subnet)));
             await storage.releaseSubnet(record.subnet);
         }
-        const sameGateway = (await storage.listPortals()).some((other) => other.name !== portalName &&
+        await untrustUnlessShared(record);
+        await storage.removePortal(portalName);
+    }
+    /** Takes the gateway's CA out of the dimension, unless another of its portals goes to that gateway. */
+    async function untrustUnlessShared(record) {
+        const sameGateway = (await storage.listPortals()).some((other) => other.name !== record.name &&
             other.dimensionName === record.dimensionName &&
             other.gatewayName === record.gatewayName);
         if (!sameGateway) {
             await ignoringStopped(() => trustGateway(dimensionContainerName(record.dimensionName), record.gatewayName, false));
         }
-        await storage.removePortal(portalName);
     }
     async function unwire(gatewayName, link) {
         const result = await docker.exec(gatewayContainerName(gatewayName), {
@@ -217,38 +225,62 @@ export function createPortalService(storage, gateways, docker, image, host) {
         await Promise.all(records.map(async (record) => {
             if ((await gatewayInterfaces(record.gatewayName))?.has(portalLink(record.name, record.subnet).gatewayIf))
                 return;
-            let pids;
+            await restoreOnce(record);
+        }));
+    }
+    // One restore of a portal at a time, however many ask (a restart's own and the watcher's): two
+    // wiring the same link at once fail each other, and the retry could land after a destroy. Each
+    // waits for the one before rather than joining it: that one may have given up on a container that
+    // has since restarted, so once it's done the link is looked at again.
+    const restoring = new Map();
+    async function restoreOnce(record) {
+        while (restoring.has(record.name)) {
+            await restoring.get(record.name).catch(() => { });
+            const link = portalLink(record.name, record.subnet);
+            if ((await listInterfaces(gatewayContainerName(record.gatewayName)))?.has(link.gatewayIf))
+                return;
+        }
+        const restored = restore(record).finally(() => restoring.delete(record.name));
+        restoring.set(record.name, restored);
+        return restored;
+    }
+    async function restore(listed) {
+        // As it is now: one being destroyed is left alone.
+        const record = await storage.readPortal(listed.name);
+        if (record?.state !== "ready")
+            return;
+        let pids;
+        try {
+            pids = await runningPids(record);
+        }
+        catch (error) {
+            // A stopped or removed container gets wired when it starts again, or never.
+            if (error instanceof GatewayConflictError || error instanceof GatewayNotFoundError)
+                return;
+            throw error;
+        }
+        for (let attempt = 1;; attempt++) {
             try {
-                pids = await runningPids(record);
+                await connect(record, pids);
+                // Destroyed meanwhile: neither the link nor the trust just made may outlive it (see destroyPortal).
+                if ((await storage.readPortal(record.name))?.state !== "ready") {
+                    await ignoringStopped(() => unwire(record.gatewayName, portalLink(record.name, record.subnet)));
+                    await untrustUnlessShared(record);
+                }
+                return;
             }
             catch (error) {
-                // A stopped or removed container gets wired when it starts again, or never.
-                if (error instanceof GatewayConflictError || error instanceof GatewayNotFoundError)
+                // A container that stopped or restarted meanwhile (killing what ran in it) is restored by
+                // its own start event. Docker kills a restarting container's processes before its state
+                // changes, so give it a moment before deciding it's still the same container.
+                await sleep(RESTORE_RECHECK_MS);
+                const now = await runningPids(record).catch(() => null);
+                if (now?.gateway !== pids.gateway || now?.dimension !== pids.dimension)
                     return;
-                throw error;
+                if (attempt === 2)
+                    return console.warn(`restoring portal ${record.name} failed:`, error);
             }
-            for (let attempt = 1;; attempt++) {
-                try {
-                    await connect(record, pids);
-                    // Destroyed meanwhile: the link just made must not outlive it (see destroyPortal).
-                    if ((await storage.readPortal(record.name))?.state !== "ready") {
-                        await ignoringStopped(() => unwire(record.gatewayName, portalLink(record.name, record.subnet)));
-                    }
-                    return;
-                }
-                catch (error) {
-                    // A container that stopped or restarted meanwhile (killing what ran in it) is restored by
-                    // its own start event. Docker kills a restarting container's processes before its state
-                    // changes, so give it a moment before deciding it's still the same container.
-                    await sleep(RESTORE_RECHECK_MS);
-                    const now = await runningPids(record).catch(() => null);
-                    if (now?.gateway !== pids.gateway || now?.dimension !== pids.dimension)
-                        return;
-                    if (attempt === 2)
-                        return console.warn(`restoring portal ${record.name} failed:`, error);
-                }
-            }
-        }));
+        }
     }
     /** Null when the container isn't running. */
     async function listInterfaces(container) {

package/dist/portal-gateway/upstream.d.ts

@@ -19,8 +19,20 @@ export type UpstreamDefinition = {
     modes: {
         oauth?: OAuthMode;
         apiKey?: ApiKeyMode;
+        forced?: ForcedMode;
     };
 };
+/** What to force onto every matching request, whatever the client sent. */
+export type UpstreamForce = {
+    /** Retarget the request, e.g. "https://api.internal:8443". */
+    target?: string;
+    /** Prefix prepended to the request path, so dimensions needn't know where the API is mounted. */
+    path?: string;
+    /** Query params the client doesn't get to choose. */
+    query?: Record<string, string>;
+    /** Headers whose values the dimension never sees. */
+    headers?: Record<string, string>;
+};
 type ModeBase = {
     /**
      * Requests to these hosts get the credential. Matched on host alone: v1 also matched the
@@ -34,17 +46,16 @@ type ModeBase = {
     } | {
         query: string;
     };
-    /** What to force onto every matching request, whatever the client sent. */
-    force?: {
-        /** Retarget the request, e.g. "https://api.internal:8443". */
-        target?: string;
-        /** Prefix prepended to the request path, so dimensions needn't know where the API is mounted. */
-        path?: string;
-        /** Query params the client doesn't get to choose. */
-        query?: Record<string, string>;
-        /** Headers the client never sees the values of. */
-        headers?: Record<string, string>;
-    };
+    force?: UpstreamForce;
+};
+/**
+ * No credential of the gateway's own, so nothing to present and no fakes: only what `force` writes
+ * onto every request to `hosts`, e.g. a service's own auth header, set here and never seen by the
+ * dimension. Applies as soon as it's registered.
+ */
+export type ForcedMode = {
+    hosts: string[];
+    force: UpstreamForce;
 };
 export type OAuthMode = ModeBase & {
     /**

package/dist/sandbox/api.d.ts

@@ -5,14 +5,16 @@ export type RunCommandOptions = {
     stdin?: string | Uint8Array;
 };
 export type RunCommandResult = {
-    exitCode: number;
-    stdout: string;
-    stderr: string;
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
 };
 export type SandboxFileInfo = {
-    type: "file" | "directory" | "other";
-    uid: number;
-    gid: number;
+    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;
@@ -27,7 +29,11 @@ export type SandboxFetchInit = {
      */
     timeout?: number | false;
 };
-/** A stream connection to a unix socket inside a sandbox (see Sandbox.connect). */
+/**
+ * A stream connection to a unix socket inside a sandbox (see Sandbox.connect).
+ *
+ * @sealed
+ */
 export type SandboxConnection = {
     write(data: Uint8Array): void;
     /** Receives every chunk read from the socket, in order. */
@@ -49,14 +55,14 @@ export type SandboxEndpointTarget = {
 export type SandboxEndpointCredentials = 
 /** `Authorization: Bearer <token>`. */
 {
-    scheme: "bearer";
-    token: string;
+    readonly scheme: "bearer";
+    readonly token: string;
 }
 /** `Authorization: Basic ...`; browsers prompt for it on their own. */
  | {
-    scheme: "basic";
-    username: string;
-    password: string;
+    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).
@@ -64,8 +70,8 @@ export type SandboxEndpointCredentials =
  * first (exeDevLoginUrl in agent/session/workerSseConnection.ts).
  */
  | {
-    scheme: "exe.dev";
-    loginUrl: string;
+    readonly scheme: "exe.dev";
+    readonly loginUrl: string;
 };
 export type SandboxEndpointScheme = SandboxEndpointCredentials["scheme"];
 export type SandboxEndpointRequest = {
@@ -88,24 +94,33 @@ export type SandboxEndpointRequest = {
     allowedOrigins?: string[];
 };
 export type SandboxEndpoint = {
-    id: string;
+    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.
+     * 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.
      */
-    url: string;
+    readonly url: string;
     /** What the client presents; requests without it are refused before reaching the target. */
-    credentials: SandboxEndpointCredentials;
-    /** As requested: fixed for the endpoint's life. */
-    allowedOrigins: string[];
+    readonly credentials: SandboxEndpointCredentials;
+    /** As requested, or as updateEndpoint changed them since. */
+    readonly allowedOrigins: 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>;
     /**
@@ -126,10 +141,15 @@ export interface SandboxFileOperations {
     /** 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. */
+/**
+ * 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>;
@@ -142,6 +162,8 @@ export interface SandboxNetwork {
  * 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 {
     /**
@@ -157,8 +179,19 @@ export interface SandboxAccessibleEndpoint {
      * 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). */
+/**
+ * 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>;
@@ -167,7 +200,11 @@ export interface SandboxExpiration {
 }
 /** Whether the sandbox has the SandboxExpiration capability. */
 export declare function hasExpiration<T extends object>(sandbox: T): sandbox is T & SandboxExpiration;
-/** What every backend provides. */
+/**
+ * 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;

package/dist/sandbox/boatService.js

@@ -103,6 +103,13 @@ export function createBoatSandbox(api, sandboxId, { proxyPort = DEFAULT_PROXY_PO
             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.
@@ -140,11 +147,11 @@ export function createBoatSandbox(api, sandboxId, { proxyPort = DEFAULT_PROXY_PO
         return result.stdout.split("\n").filter(Boolean);
     }
     async function stat(path) {
-        const result = await sh(`[ -e "$1" ] || exit ${NOT_FOUND}; stat -c '%u:%g:%F' -- "$1"`, full(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 = "", kind = ""] = result.stdout.trim().split(":");
+        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) };
+        return { type, uid: Number(uid), gid: Number(gid), size: Number(size) };
     }
     let home = null;
     function homeDirectory() {
@@ -233,6 +240,7 @@ export function createBoatSandbox(api, sandboxId, { proxyPort = DEFAULT_PROXY_PO
         getExpiration,
         setExpiration,
         readFile,
+        readFileRange,
         writeFile,
         writeFileExclusive,
         removeFile,

package/dist/sandbox/containerService.js

@@ -38,6 +38,12 @@ export function createContainerSandbox(docker, container, { user } = {}) {
         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.
@@ -81,10 +87,10 @@ export function createContainerSandbox(docker, container, { user } = {}) {
     }
     async function stat(path) {
         const full = containerPath(path);
-        const result = check(await sh(`[ -e "$P" ] || exit ${NOT_FOUND}; stat -c '%u:%g:%F' -- "$P"`, { P: full }), "stat", full);
-        const [uid = "", gid = "", kind = ""] = result.stdout.trim().split(":");
+        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) };
+        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() {
@@ -136,6 +142,7 @@ export function createContainerSandbox(docker, container, { user } = {}) {
     }
     return {
         readFile,
+        readFileRange,
         writeFile,
         writeFileExclusive,
         removeFile,

package/dist/sandbox/endpointProxy.js

@@ -185,6 +185,21 @@ export function createProxyEndpoints(commands, options, where) {
         if (result.exitCode === 10 && firewall)
             await ufw("delete", "allow", `${port}/tcp`);
     }
+    // The proxy reads the record on every request, so the change applies to the next one.
+    async function updateEndpoint(endpointId, { allowedOrigins }) {
+        const { port, name } = parseEndpointId(endpointId);
+        const read = await sh(READ_SCRIPT, { P: port, N: name });
+        if (read.exitCode !== 0)
+            return false;
+        const record = { ...JSON.parse(read.stdout), origins: allowedOrigins };
+        const written = await sh(WRITE_SCRIPT, { P: port, N: name }, JSON.stringify(record));
+        if (written.exitCode === 44)
+            return false; // its proxy's directory went with its last endpoint
+        if (written.exitCode !== 0) {
+            throw new Error(`updating endpoint ${endpointId} on ${where} failed (exit ${written.exitCode}): ${written.stderr.trim()}`);
+        }
+        return true;
+    }
     // Its record says what to serve; the proxy is started again on the port the endpoint's URL names.
     async function ensureEndpoint(endpointId) {
         const { port, name } = parseEndpointId(endpointId);
@@ -202,7 +217,7 @@ export function createProxyEndpoints(commands, options, where) {
         await closeEndpoint(endpointId);
         return false;
     }
-    return { accessibleHost: options.accessibleHost, exposeEndpoint, exposeEndpointAs, closeEndpoint, ensureEndpoint };
+    return { accessibleHost: options.accessibleHost, exposeEndpoint, exposeEndpointAs, closeEndpoint, ensureEndpoint, updateEndpoint };
 }
 /** The credentials a client presents for a recorded check; `none` when the endpoint checks nothing itself. */
 function credentialsOf(check, none) {

package/dist/sandbox/localService.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { link, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { link, mkdir, open, 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";
@@ -36,6 +36,23 @@ export function createLocalSandbox(root, { endpoints } = {}) {
     async function readFileLocal(path) {
         return new Uint8Array(await notFoundAs(path, readFile(hostPath(path))));
     }
+    async function readFileRangeLocal(path, start, end) {
+        const file = await notFoundAs(path, open(hostPath(path), "r"));
+        try {
+            const buffer = new Uint8Array(Math.max(0, end - start));
+            let filled = 0;
+            while (filled < buffer.length) {
+                const { bytesRead } = await file.read(buffer, filled, buffer.length - filled, start + filled);
+                if (bytesRead === 0)
+                    break;
+                filled += bytesRead;
+            }
+            return buffer.subarray(0, filled);
+        }
+        finally {
+            await file.close();
+        }
+    }
     async function writeFileLocal(path, data) {
         const full = hostPath(path);
         await rename(await writeTemp(full, data), full);
@@ -72,7 +89,7 @@ export function createLocalSandbox(root, { endpoints } = {}) {
     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 };
+        return { type, uid: stats.uid, gid: stats.gid, size: stats.size };
     }
     async function homeDirectory() {
         const rel = relative(base, homedir());
@@ -112,6 +129,7 @@ export function createLocalSandbox(root, { endpoints } = {}) {
     }
     const sandbox = {
         readFile: readFileLocal,
+        readFileRange: readFileRangeLocal,
         writeFile: writeFileLocal,
         writeFileExclusive,
         removeFile,

package/dist/sandbox/sshService.js

@@ -5,6 +5,7 @@ import { createProxyEndpoints } from "./endpointProxy.js";
 import { socketConnection } from "./localService.js";
 /** SFTP status codes (draft-ietf-secsh-filexfer-02). */
 const SFTP_NO_SUCH_FILE = 2;
+const SFTP_EOF = 1;
 /**
  * Commands running at once on the connection. sshd refuses sessions past its MaxSessions (10 by
  * default) per connection, and counts a closed one until it has cleaned up after it, so this stays
@@ -181,6 +182,30 @@ export function createSshSandbox(host, options) {
         const data = await sftpCall("read", full, (channel, done) => channel.readFile(full, done));
         return new Uint8Array(data);
     }
+    async function sftpReadFileRange(path, start, end) {
+        const full = remotePath(path);
+        const channel = await sftp();
+        const handle = await sftpCall("read", full, (sftpChannel, done) => sftpChannel.open(full, "r", done));
+        try {
+            const buffer = Buffer.alloc(Math.max(0, end - start));
+            let filled = 0;
+            while (filled < buffer.length) {
+                const read = await new Promise((resolve, reject) => channel.read(handle, buffer, filled, buffer.length - filled, start + filled, (error, bytesRead) => {
+                    // The end of the file comes as an EOF status rather than a short read.
+                    if (error && error.code !== SFTP_EOF)
+                        return reject(new Error(`read ${full} on ${host} failed: ${error.message}`));
+                    resolve(error ? 0 : bytesRead);
+                }));
+                if (read === 0)
+                    break;
+                filled += read;
+            }
+            return new Uint8Array(buffer.subarray(0, filled));
+        }
+        finally {
+            channel.close(handle, () => { });
+        }
+    }
     /** Writes `data` to a unique hidden file next to `full` (creating its directory) and returns its path. */
     async function writeTemp(full, data) {
         await createDirectory(posix.dirname(full));
@@ -268,7 +293,7 @@ export function createSshSandbox(host, options) {
     async function sftpStat(path) {
         const info = await statOf(remotePath(path));
         const type = info.isDirectory() ? "directory" : info.isFile() ? "file" : "other";
-        return { type, uid: info.uid, gid: info.gid };
+        return { type, uid: info.uid, gid: info.gid, size: info.size };
     }
     // SFTP starts in the user's home directory. Asked once: storage paths start from it on every call.
     let home = null;
@@ -301,6 +326,12 @@ export function createSshSandbox(host, options) {
             checkShell(result, "read", full);
             return new Uint8Array(result.stdout);
         },
+        async readFileRange(full, start, end) {
+            const script = `[ -e "$P" ] || exit ${NOT_FOUND}; tail -c +$(($S + 1)) -- "$P" | head -c "$L"`;
+            const result = await runBytes(commandLine(["sh", "-c", script], { P: full, S: String(start), L: String(Math.max(0, end - start)) }));
+            checkShell(result, "read", full);
+            return new Uint8Array(result.stdout);
+        },
         /** Streams `data` into a temp file beside `full`, then runs `publish` ($T the temp file, $F the target). */
         writeVia(full, data, publish) {
             const tmp = posix.join(posix.dirname(full), `.${posix.basename(full)}.${crypto.randomUUID()}.tmp`);
@@ -329,11 +360,11 @@ export function createSshSandbox(host, options) {
             return result.stdout.split("\n").filter(Boolean);
         },
         async stat(full) {
-            const result = await sh(`[ -e "$P" ] || exit ${NOT_FOUND}; stat -c '%u:%g:%F' -- "$P"`, { P: full });
+            const result = await sh(`[ -e "$P" ] || exit ${NOT_FOUND}; stat -c '%u:%g:%s:%F' -- "$P"`, { P: full });
             checkShell(result, "stat", full);
-            const [uid = "", gid = "", kind = ""] = result.stdout.trim().split(":");
+            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) };
+            return { type, uid: Number(uid), gid: Number(gid), size: Number(size) };
         },
         // sshd always sets HOME for the session.
         async homeDirectory() {
@@ -343,6 +374,7 @@ export function createSshSandbox(host, options) {
         },
     };
     const readFile = async (path) => ((await sftpAvailable()) ? sftpReadFile(path) : shell.readFile(remotePath(path)));
+    const readFileRange = async (path, start, end) => (await sftpAvailable()) ? sftpReadFileRange(path, start, end) : shell.readFileRange(remotePath(path), start, end);
     const writeFile = async (path, data) => (await sftpAvailable()) ? sftpWriteFile(path, data) : shell.writeFile(remotePath(path), data);
     const writeFileExclusive = async (path, data) => (await sftpAvailable()) ? sftpWriteFileExclusive(path, data) : shell.writeFileExclusive(remotePath(path), data);
     const removeFile = async (path) => ((await sftpAvailable()) ? sftpRemoveFile(path) : shell.removeFile(remotePath(path)));
@@ -592,6 +624,7 @@ export function createSshSandbox(host, options) {
     }
     const sandbox = {
         readFile,
+        readFileRange,
         writeFile,
         writeFileExclusive,
         removeFile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperbrane",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Dimensions, gateways and agents on a machine reached locally, over SSH or on Boat: SDK and CLI.",
   "license": "Apache-2.0",
   "type": "module",
@@ -11,11 +11,27 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./package.json": "./package.json",
-    "./*": {
-      "types": "./dist/*.d.ts",
-      "import": "./dist/*.js"
-    }
+    "./sandbox/api": {
+      "types": "./dist/sandbox/api.d.ts",
+      "import": "./dist/sandbox/api.js"
+    },
+    "./dimension/api": {
+      "types": "./dist/dimension/api.d.ts",
+      "import": "./dist/dimension/api.js"
+    },
+    "./portal-gateway/api": {
+      "types": "./dist/portal-gateway/api.d.ts",
+      "import": "./dist/portal-gateway/api.js"
+    },
+    "./agent/api": {
+      "types": "./dist/agent/api.d.ts",
+      "import": "./dist/agent/api.js"
+    },
+    "./agent/client": {
+      "types": "./dist/agent/client.d.ts",
+      "import": "./dist/agent/client.js"
+    },
+    "./package.json": "./package.json"
   },
   "bin": {
     "hyperbrane": "./dist/cli/main.js"
@@ -36,9 +52,10 @@
     "embed:images": "bun run scripts/embed-image-files.ts",
     "bundle:worker": "bun run scripts/bundle-worker.ts",
     "build": "bun run build:vendor && bun run bundle:worker && bun run embed:images && rm -rf dist && tsc -p tsconfig.build.json && bun run scripts/finish-build.ts",
-    "build:vendor": "test -d agent/vendor-types/claude || bun run scripts/pull-vendor-types.ts claude",
+    "build:vendor": "test -d agent/vendor-types/claude && test -d agent/vendor-types/codex || bun run scripts/pull-vendor-types.ts claude codex",
     "prepack": "bun run build",
-    "check:package": "bun run scripts/check-package.ts"
+    "check:package": "bun run scripts/check-package.ts",
+    "api:diff": "bun run scripts/api-diff.ts"
   },
   "dependencies": {
     "@boatdev/sdk": "1.5.0",