withruntime 0.8.2 → 0.8.3

package/dist/products/secrets.js

@@ -1,24 +1,219 @@
+import { NotFoundError, RuntimeError } from "../errors.js";
+import { switchedOff } from "./jobs.js";
+/** A write that reached one copy of a secret and not the other: `stored`
+ * names what took effect. Calling again with the same arguments is safe. */
+export class SecretPartlyStoredError extends RuntimeError {
+}
+const unavailable = (error) => error instanceof RuntimeError && (error.code === "unavailable" || error.status === 503);
 export function secrets(t) {
+    const off = switchedOff("Secrets for jobs");
+    const store = (call) => t.json(call).catch(off);
     const path = (name) => `/v1/egress-secrets/${encodeURIComponent(name)}`;
-    return {
-        /** Store or replace a secret. Replacing keeps its placeholder. */
-        set: (name, input, options) => t.json({
-            method: "PUT",
-            path: path(name),
-            body: input,
-            ...options,
-        }),
-        /** Names, hosts and placeholders. Never values. */
-        list: async (options) => (await t.json({
-            method: "GET",
-            path: "/v1/egress-secrets",
+    const jobPath = (id) => `/v1/secrets/${encodeURIComponent(id)}`;
+    /** Every jobs copy this key's person owns, deleted ones included. */
+    async function jobCopies(options) {
+        const all = [];
+        let after;
+        for (;;) {
+            const page = await store({
+                method: "GET",
+                path: "/v1/secrets",
+                query: { limit: 100, ...(after ? { after } : {}) },
+                ...options,
+            });
+            all.push(...page);
+            if (page.length < 100)
+                return all;
+            after = page.at(-1).id;
+        }
+    }
+    const liveCopy = async (name, options) => (await jobCopies(options)).find((s) => s.name === name && s.deletedAt === null);
+    const list = async (options) => (await t.json({
+        method: "GET",
+        path: "/v1/egress-secrets",
+        ...options,
+    })).secrets;
+    const key = (options, part) => options?.idempotencyKey
+        ? { ...options, idempotencyKey: `${options.idempotencyKey}:${part}`.slice(0, 128) }
+        : options;
+    async function setJobCopy(name, value, options) {
+        const copies = await jobCopies(options);
+        const live = copies.find((s) => s.name === name && s.deletedAt === null);
+        if (live)
+            return store({
+                method: "POST",
+                path: `${jobPath(live.id)}:rotate`,
+                body: { value, expectedVersion: live.version },
+                ...options,
+            });
+        if (copies.some((s) => s.name === name))
+            throw new RuntimeError({
+                message: `A jobs secret named ${name} was deleted, and a deleted name cannot be used again.`,
+                code: "name_conflict",
+                status: 409,
+                hint: "Store it under another name.",
+                details: { field: "name" },
+            });
+        return store({
+            method: "POST",
+            path: "/v1/secrets",
+            body: { name, value },
             ...options,
-        })).secrets,
-        /** Delete a secret: its value is erased and its placeholder stops working. */
-        delete: (name, options) => t.json({
-            method: "DELETE",
-            path: path(name),
-            ...options,
-        }),
+        });
+    }
+    async function all(options) {
+        const [forSandboxes, forJobs] = await Promise.all([
+            list(options),
+            jobCopies(options).catch((error) => {
+                if (unavailable(error))
+                    return [];
+                throw error;
+            }),
+        ]);
+        const byName = new Map();
+        for (const s of forSandboxes)
+            byName.set(s.name, { name: s.name, sandboxes: s, jobs: null });
+        for (const j of forJobs.filter((j) => j.deletedAt === null))
+            byName.set(j.name, {
+                name: j.name,
+                sandboxes: byName.get(j.name)?.sandboxes ?? null,
+                jobs: j,
+            });
+        return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async function set(name, input, options) {
+        const { jobs, value, ...egress } = input;
+        if (!egress.hosts?.length && !jobs)
+            throw new RuntimeError({
+                message: "Say where the value may go: hosts for sandboxes, jobs: true for scheduled jobs, or both.",
+                code: "invalid_request",
+                status: 0,
+                details: { field: "hosts" },
+            });
+        let sandboxes;
+        if (egress.hosts?.length)
+            sandboxes = await t.json({
+                method: "PUT",
+                path: path(name),
+                body: { value, ...egress },
+                ...(jobs ? key(options, "sandboxes") : options),
+            });
+        if (!jobs)
+            return sandboxes;
+        try {
+            const copy = await setJobCopy(name, value, key(options, "jobs"));
+            return { ...(sandboxes ?? { name }), jobs: copy };
+        }
+        catch (error) {
+            if (!sandboxes)
+                throw error;
+            const cause = error instanceof RuntimeError ? error : undefined;
+            throw new SecretPartlyStoredError({
+                message: `Stored ${name} for sandboxes, but not for jobs: ${cause?.message ?? String(error)}`,
+                code: cause?.code ?? "partly_stored",
+                status: cause?.status ?? 0,
+                hint: "Run the same call again: storing it for sandboxes again changes nothing, and the jobs copy is stored or rotated.",
+                details: { stored: ["sandboxes"], field: "jobs" },
+                ...(cause?.requestId ? { requestId: cause.requestId } : {}),
+                cause: error,
+            });
+        }
+    }
+    return {
+        /** Store or replace a secret. With `hosts`, sandboxes see a placeholder
+         * and the egress proxy puts the value into HTTPS requests to them
+         * (replacing keeps the placeholder). With `jobs: true`, a copy scheduled
+         * jobs can put into their environment; setting it again rotates it. Both
+         * at once store both; if only the first lands, `SecretPartlyStoredError`
+         * says so and the same call again finishes it. */
+        set,
+        /** The sandboxes' secrets: names, hosts and placeholders. Never values.
+         * `all()` includes the jobs copies. */
+        list,
+        /** Every secret by name, with where its value may go. */
+        all,
+        /** One secret by name, with where its value may go. */
+        get: async (name, options) => {
+            const found = (await all(options)).find((s) => s.name === name);
+            if (!found)
+                throw new NotFoundError({
+                    message: `No secret named ${name}.`,
+                    code: "not_found",
+                    status: 404,
+                    hint: "List them with runtime.secrets.all().",
+                });
+            return found;
+        },
+        /** Replace the jobs copy's value with a new version. Runs already bound to
+         * the old version are refused it. Only the jobs copy has versions; to
+         * change the sandboxes' copy, `set` it again. */
+        rotate: async (name, value, options) => {
+            const live = await liveCopy(name, options);
+            if (!live)
+                throw new NotFoundError({
+                    message: `${name} has no copy for jobs to rotate.`,
+                    code: "not_found",
+                    status: 404,
+                    hint: "Store one with set(name, { value, jobs: true }). The sandboxes' copy is replaced by set, not rotated.",
+                });
+            return store({
+                method: "POST",
+                path: `${jobPath(live.id)}:rotate`,
+                body: { value, expectedVersion: live.version },
+                ...options,
+            });
+        },
+        /** Read the jobs copy's value back (needs the key's secrets_reveal
+         * permission). The sandboxes' copy can never be read back. */
+        reveal: async (name, query = {}, options) => {
+            const live = await liveCopy(name, options);
+            if (!live)
+                throw new NotFoundError({
+                    message: `${name} has no copy for jobs; the sandboxes' copy of a secret can never be read back.`,
+                    code: "not_found",
+                    status: 404,
+                });
+            return store({
+                method: "POST",
+                path: `${jobPath(live.id)}:reveal`,
+                body: query,
+                ...options,
+            });
+        },
+        /** Delete a secret everywhere it is kept: the sandboxes' value is erased
+         * and its placeholder stops working, and the jobs copy stops being given
+         * to runs (its name stays taken). */
+        delete: async (name, options) => {
+            const live = await liveCopy(name, options).catch((error) => {
+                if (unavailable(error))
+                    return undefined;
+                throw error;
+            });
+            let removed;
+            try {
+                removed = await t.json({
+                    method: "DELETE",
+                    path: path(name),
+                    ...(live ? key(options, "sandboxes") : options),
+                });
+            }
+            catch (error) {
+                if (!(live && error instanceof NotFoundError))
+                    throw error;
+            }
+            if (live)
+                await store({
+                    method: "POST",
+                    path: `${jobPath(live.id)}:delete`,
+                    body: { expectedVersion: live.version },
+                    ...key(options, "jobs"),
+                });
+            return {
+                name,
+                deleted: true,
+                enforced: removed?.enforced ?? true,
+                from: [...(removed ? ["sandboxes"] : []), ...(live ? ["jobs"] : [])],
+            };
+        },
     };
 }

package/dist/sandbox.d.ts

@@ -1,6 +1,6 @@
 import { Page } from "./page.js";
 import { type FileEvent, type WatchHandle, type WatchOptions } from "./products/watch.js";
-import type { RequestOptions, Transport } from "./transport.js";
+import { Transport, type RequestOptions } from "./transport.js";
 import type { CommandResult, ExecOptions, FileEntry, OutputEvent, KeepAliveOptions, ProcessInfo, SandboxInfo, SandboxSettings } from "./types.js";
 import { type SandboxExtensions } from "./products/index.js";
 import type { Snapshot, SnapshotOptions } from "./snapshots.js";
@@ -14,8 +14,27 @@ export declare class Sandbox implements AsyncDisposable {
     #private;
     readonly files: Files;
     readonly processes: Processes;
+    /** Short-lived tokens that let a browser reach this sandbox directly. */
+    readonly sessions: SandboxSessions;
     constructor(transport: Transport, info: SandboxInfo);
     get id(): string;
+    /** A sandbox reached with a session token instead of an API key, for code in
+     * a browser: commands and their streams, processes, files and previews of
+     * this one sandbox. Makes no call; `info` holds only the id until
+     * `refresh()`. Your backend makes the session with `sbx.sessions.create()`
+     * and hands the page `token` and `sandboxId`.
+     *
+     *   const sbx = Sandbox.fromSession({ token, sandboxId });
+     *   const { stdout } = await sbx.exec("ls /workspace");
+     */
+    static fromSession(session: {
+        token: string;
+        sandboxId: string;
+        /** The API's origin, `apiUrl` in the session; https://api.withruntime.com
+         * unless you run your own. */
+        apiUrl?: string;
+        fetch?: typeof fetch;
+    }): Sandbox;
     /** What the API last said about this sandbox. `refresh()` asks again. */
     get info(): SandboxInfo;
     get state(): SandboxInfo["state"];
@@ -124,6 +143,49 @@ export declare class Sandbox implements AsyncDisposable {
     [Symbol.asyncDispose](): Promise<void>;
     toJSON(): SandboxInfo;
 }
+/** A sandbox session, as the API answers it. `token` is set only in the
+ * answer to `create`. */
+export type SandboxSession = {
+    id: string;
+    sandboxId: string;
+    name: string | null;
+    origins: string[];
+    /** The agent whose key made it; the session acts as it. */
+    createdBy: string;
+    createdAt: string;
+    expiresAt: string;
+    revokedAt: string | null;
+    state: "active" | "expired" | "revoked";
+};
+export type CreatedSandboxSession = SandboxSession & {
+    /** The bearer token, `rtsess_...`: hand it to the page, never log it. */
+    token: string;
+    /** The API's origin, for `Sandbox.fromSession({ apiUrl })`. */
+    apiUrl: string;
+};
+/** Sessions: a token your backend makes and hands to your own frontend, which
+ * then runs commands, reads and writes files and reaches previews in this one
+ * sandbox directly, without proxying through your servers. A session cannot
+ * stop, pause, extend, fork, snapshot or change the sandbox, create anything,
+ * or reach anything else. It lasts an hour unless asked (a day at most), ends
+ * when the key that made it is revoked, and is revocable at once. */
+export declare class SandboxSessions {
+    private readonly t;
+    private readonly sandboxId;
+    constructor(t: Transport, sandboxId: string);
+    /** A new session. `origins` are the exact pages that will use it
+     * (`https://app.example.com`, or `http://localhost:5173` while developing):
+     * the API answers CORS for them and refuses any other page. */
+    create(input?: {
+        ttlSeconds?: number;
+        origins?: string[];
+        name?: string;
+    }, options?: RequestOptions): Promise<CreatedSandboxSession>;
+    /** Sessions still active, and those that ended in the last day, newest first. */
+    list(options?: RequestOptions): Promise<SandboxSession[]>;
+    /** Ends a session now; its next request is refused. */
+    revoke(sessionId: string, options?: RequestOptions): Promise<SandboxSession>;
+}
 export declare class Processes {
     private readonly t;
     private readonly sandboxId;

package/dist/sandbox.js

@@ -1,6 +1,7 @@
 import { CommandError, ConnectionError, NotFoundError, RuntimeError } from "./errors.js";
 import { Page } from "./page.js";
 import { sandboxWatches, watchDirectory, } from "./products/watch.js";
+import { Transport } from "./transport.js";
 import { sandboxFactories } from "./products/index.js";
 import { Tunnel } from "./tunnel.js";
 const CHUNK = 1_048_576;
@@ -11,7 +12,21 @@ const CHUNK = 1_048_576;
  * connections at once. */
 const PARALLEL = 8;
 const enc = (id) => encodeURIComponent(id);
-const toBase64 = (data) => (typeof data === "string" ? Buffer.from(data) : Buffer.from(data)).toString("base64");
+/* Web APIs only, so the sandbox's commands, processes and files work in a
+   browser with a session token (Sandbox.fromSession): no Buffer, no
+   node:crypto. */
+const utf8 = (data) => typeof data === "string" ? new TextEncoder().encode(data) : data;
+function base64(bytes) {
+    let text = "";
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        text += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(text);
+}
+const toBase64 = (data) => base64(utf8(data));
+async function sha256Hex(data) {
+    const digest = await crypto.subtle.digest("SHA-256", utf8(data));
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
+}
 function commandBody(command, options) {
     return {
         ...(typeof command === "string" ? { command } : { argv: [...command] }),
@@ -32,17 +47,44 @@ export class Sandbox {
     #t;
     files;
     processes;
+    /** Short-lived tokens that let a browser reach this sandbox directly. */
+    sessions;
     constructor(transport, info) {
         this.#t = transport;
         this.#info = info;
         this.files = new Files(transport, info.id);
         this.processes = new Processes(transport, info.id);
+        this.sessions = new SandboxSessions(transport, info.id);
         for (const [name, make] of sandboxFactories())
             Object.defineProperty(this, name, { value: make(transport, this), enumerable: false });
     }
     get id() {
         return this.#info.id;
     }
+    /** A sandbox reached with a session token instead of an API key, for code in
+     * a browser: commands and their streams, processes, files and previews of
+     * this one sandbox. Makes no call; `info` holds only the id until
+     * `refresh()`. Your backend makes the session with `sbx.sessions.create()`
+     * and hands the page `token` and `sandboxId`.
+     *
+     *   const sbx = Sandbox.fromSession({ token, sandboxId });
+     *   const { stdout } = await sbx.exec("ls /workspace");
+     */
+    static fromSession(session) {
+        if (!/^rtsess_/.test(session.token))
+            throw new RuntimeError({
+                message: "That is not a sandbox session token (they start rtsess_).",
+                code: "invalid_request",
+                status: 0,
+                hint: "Make one on your backend with sbx.sessions.create() and pass its token.",
+            });
+        const transport = new Transport({
+            apiKey: session.token,
+            ...(session.apiUrl ? { baseUrl: session.apiUrl } : {}),
+            ...(session.fetch ? { fetch: session.fetch } : {}),
+        });
+        return new Sandbox(transport, { id: session.sandboxId });
+    }
     /** What the API last said about this sandbox. `refresh()` asks again. */
     get info() {
         return this.#info;
@@ -439,7 +481,7 @@ class OutputCursor {
                     droppedBytes: event.offset - this.cursor,
                     resumeAt: event.offset,
                 };
-            this.cursor = Math.max(this.cursor, event.offset + Buffer.byteLength(event.data));
+            this.cursor = Math.max(this.cursor, event.offset + utf8(event.data).byteLength);
         }
         yield event;
     }
@@ -463,6 +505,69 @@ function pick(options) {
         ...(options.timeoutMs ? { timeoutMs: options.timeoutMs + 60_000 } : {}),
     };
 }
+/** Sessions: a token your backend makes and hands to your own frontend, which
+ * then runs commands, reads and writes files and reaches previews in this one
+ * sandbox directly, without proxying through your servers. A session cannot
+ * stop, pause, extend, fork, snapshot or change the sandbox, create anything,
+ * or reach anything else. It lasts an hour unless asked (a day at most), ends
+ * when the key that made it is revoked, and is revocable at once. */
+export class SandboxSessions {
+    t;
+    sandboxId;
+    constructor(t, sandboxId) {
+        this.t = t;
+        this.sandboxId = sandboxId;
+    }
+    /** A new session. `origins` are the exact pages that will use it
+     * (`https://app.example.com`, or `http://localhost:5173` while developing):
+     * the API answers CORS for them and refuses any other page. */
+    async create(input = {}, options = {}) {
+        const path = `/v1/sandboxes/${enc(this.sandboxId)}/sessions`;
+        const made = await this.t.json({
+            method: "POST",
+            path,
+            body: input,
+            ...options,
+        });
+        if (made.token)
+            return made;
+        /* The answer replayed an earlier create whose reply was lost, and a token
+           is shown only once: end that session and make a fresh one. */
+        await this.revoke(made.id).catch(() => undefined);
+        const fresh = await this.t.json({
+            method: "POST",
+            path,
+            body: input,
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(options.timeoutMs ? { timeoutMs: options.timeoutMs } : {}),
+        });
+        if (!fresh.token)
+            throw new RuntimeError({
+                message: "The session was made but its token did not arrive.",
+                code: "session_token_lost",
+                status: 0,
+                hint: `Revoke session ${fresh.id} and create another.`,
+            });
+        return fresh;
+    }
+    /** Sessions still active, and those that ended in the last day, newest first. */
+    async list(options = {}) {
+        return (await this.t.json({
+            method: "GET",
+            path: `/v1/sandboxes/${enc(this.sandboxId)}/sessions`,
+            ...options,
+        })).data;
+    }
+    /** Ends a session now; its next request is refused. */
+    async revoke(sessionId, options = {}) {
+        return this.t.json({
+            method: "POST",
+            path: `/v1/sandboxes/${enc(this.sandboxId)}/sessions/${enc(sessionId)}:revoke`,
+            body: {},
+            ...options,
+        });
+    }
+}
 export class Processes {
     t;
     sandboxId;
@@ -568,14 +673,14 @@ export class Process {
     }
     /** Sends input. Offsets are tracked for you, so a retried write is never typed twice. */
     async write(data, options = {}) {
-        const bytes = typeof data === "string" ? Buffer.from(data) : Buffer.from(data);
+        const bytes = utf8(data);
         let sent = 0;
         do {
             const reply = await this.t.json({
                 method: "POST",
                 path: `/v1/sandboxes/${enc(this.sandboxId)}/processes/${enc(this.id)}:write`,
                 body: {
-                    base64: bytes.subarray(sent).toString("base64"),
+                    base64: base64(bytes.subarray(sent)),
                     offset: this.#inputOffset,
                     ...(options.eof ? { eof: true } : {}),
                 },
@@ -743,16 +848,16 @@ export class Files {
             });
             return { path, size: bytes.length };
         }
-        const { createHash } = await import("node:crypto");
-        const sha256 = createHash("sha256").update(bytes).digest("hex");
+        const sha256 = await sha256Hex(bytes);
         // A guest journals mutations across operations, not per URL. One logical
         // write therefore owns separate stable keys for each mutation phase.
         const uploadKey = options.idempotencyKey ?? crypto.randomUUID();
+        const phaseKeys = new Map();
+        for (const phase of ["begin", "legacy-begin", "commit", "chmod", "abort"])
+            phaseKeys.set(phase, await sha256Hex(JSON.stringify(["files.write", uploadKey, phase])));
         const phaseOptions = (phase) => ({
             ...options,
-            idempotencyKey: createHash("sha256")
-                .update(JSON.stringify(["files.write", uploadKey, phase]))
-                .digest("hex"),
+            idempotencyKey: phaseKeys.get(phase),
         });
         let begin;
         try {

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.8.2";
+export declare const VERSION = "0.8.3";
 export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
 export type RequestOptions = {
     /** Sent as Idempotency-Key. Omit it: the SDK makes one per call and keeps

package/dist/transport.js

@@ -1,6 +1,6 @@
 import { ConnectionError, errorFor, RuntimeError, WAITS_FOR_ROOM } from "./errors.js";
 import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
-export const VERSION = "0.8.2";
+export const VERSION = "0.8.3";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
 export function apiOrigin(value) {
     const url = new URL(value);

package/dist/vercel/sandbox.js

@@ -59,7 +59,7 @@ export function networkRules(policy) {
     else if (allow) {
         for (const [domain, rules] of Object.entries(allow)) {
             if (rules.length)
-                throw new NotSupportedError(`Network rules that transform or forward requests (for ${domain})`, "Allow the domain with an empty rule list and pass credentials to the command as env instead.");
+                throw new NotSupportedError(`Network rules that transform or forward requests (for ${domain})`, `Allow the domain with an empty rule list and store the credential as a Runtime secret for it: \`npx withruntime secrets set NAME --host ${domain}\`. The sandbox sees a placeholder, and the egress proxy adds the value.`);
             domains.push(domain);
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "withruntime",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "license": "Apache-2.0",
   "mcpName": "com.withruntime/runtime",
   "type": "module",
@@ -126,6 +126,12 @@
   },
   "bugs": "https://github.com/withruntime/runtime/issues",
   "sideEffects": false,
+  "browser": {
+    "./dist/tar.js": "./dist/browser-stub.js",
+    "./dist/image-context.js": "./dist/browser-stub.js",
+    "./dist/credentials.js": "./dist/browser-stub.js",
+    "undici": false
+  },
   "keywords": [
     "sandbox",
     "cloud",