withruntime 0.10.0 → 0.11.1

package/dist/vercel/sandbox-user.d.ts

@@ -0,0 +1,70 @@
+import type { Command, CommandFinished } from "./command.js";
+import type { RunCommandParams, Sandbox } from "./sandbox.js";
+/** A Linux user or group name Vercel accepts, which is also safe to pass to
+ * useradd, groupadd and sudo. */
+export declare function validateName(name: string, kind: string): void;
+/** Thrown when `sandbox.createUser` is called for an existing username. */
+export declare class SandboxUserAlreadyExistsError extends Error {
+    readonly username: string;
+    constructor(username: string);
+}
+type Signal = {
+    signal?: AbortSignal;
+};
+/** A user in a sandbox, made with `sandbox.createUser` or found with
+ * `sandbox.asUser`. Commands and file calls run as this user. */
+export declare class SandboxUser {
+    #private;
+    readonly username: string;
+    /** `/root` for root, else `/home/<username>`. */
+    readonly homeDir: string;
+    /** Use sandbox.createUser or sandbox.asUser. */
+    constructor({ sandbox, username }: {
+        sandbox: Sandbox;
+        username: string;
+    });
+    /** Runs a command as this user. `sudo: true` runs it as root instead. */
+    runCommand(command: string, args?: string[], opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<CommandFinished>;
+    runCommand(params: RunCommandParams & {
+        detached: true;
+    }): Promise<Command>;
+    runCommand(params: RunCommandParams): Promise<CommandFinished>;
+    /** Writes files into this user's home (or absolute paths), then gives them
+     * and the directories made for them to this user. */
+    writeFiles(files: {
+        path: string;
+        content: string | Uint8Array;
+        mode?: number;
+    }[], opts?: Signal): Promise<void>;
+    /** The file as this user may read it, as a stream; null when missing. */
+    readFile(file: {
+        path: string;
+        cwd?: string;
+    }, opts?: Signal): Promise<NodeJS.ReadableStream | null>;
+    /** The file as this user may read it; null when missing. */
+    readFileToBuffer(file: {
+        path: string;
+        cwd?: string;
+    }, opts?: Signal): Promise<Buffer | null>;
+    /** Copies a file this user may read to the local disk; null when missing. */
+    downloadFile(src: {
+        path: string;
+        cwd?: string;
+    }, dst: {
+        path: string;
+        cwd?: string;
+    }, opts?: {
+        mkdirRecursive?: boolean;
+        signal?: AbortSignal;
+    }): Promise<string | null>;
+    /** Makes a directory owned by this user. */
+    mkDir(path: string, opts?: Signal): Promise<void>;
+    addToGroup(groupname: string, opts?: Signal): Promise<void>;
+    removeFromGroup(groupname: string, opts?: Signal): Promise<void>;
+}
+/** Runs `cmd args` under sudo; a non-zero exit throws `what(): <stderr>`. */
+export declare function rootOrThrow(sandbox: Sandbox, cmd: string, args: string[], signal: AbortSignal | undefined, what: () => string): Promise<CommandFinished>;
+export {};

package/dist/vercel/sandbox-user.js

@@ -0,0 +1,206 @@
+import { dirname, resolve } from "node:path";
+/* Vercel's multi-user helpers over Runtime's sandbox owner, who has
+   passwordless sudo: a user is a real Linux user made with `sudo useradd`,
+   and every call as that user is `sudo -u <user>`, exactly as Vercel's own
+   SDK does it (checked against @vercel/sandbox 3.5.1). */
+const VALID_NAME = /^[a-z_][a-z0-9_-]*$/;
+const MAX_NAME_LENGTH = 32;
+/** A Linux user or group name Vercel accepts, which is also safe to pass to
+ * useradd, groupadd and sudo. */
+export function validateName(name, kind) {
+    if (!name)
+        throw new Error(`Invalid ${kind}: must not be empty`);
+    if (name.length > MAX_NAME_LENGTH)
+        throw new Error(`Invalid ${kind} "${name}": must be at most ${MAX_NAME_LENGTH} characters`);
+    if (!VALID_NAME.test(name))
+        throw new Error(`Invalid ${kind} "${name}": must match ${VALID_NAME} (lowercase letters, digits, hyphens, underscores)`);
+}
+/** Thrown when `sandbox.createUser` is called for an existing username. */
+export class SandboxUserAlreadyExistsError extends Error {
+    username;
+    constructor(username) {
+        super(`Failed to create user "${username}": user already exists`);
+        this.name = "SandboxUserAlreadyExistsError";
+        this.username = username;
+    }
+}
+/** A user in a sandbox, made with `sandbox.createUser` or found with
+ * `sandbox.asUser`. Commands and file calls run as this user. */
+export class SandboxUser {
+    username;
+    /** `/root` for root, else `/home/<username>`. */
+    homeDir;
+    #sandbox;
+    #primaryGroup;
+    /** Use sandbox.createUser or sandbox.asUser. */
+    constructor({ sandbox, username }) {
+        this.#sandbox = sandbox;
+        this.username = username;
+        this.homeDir = username === "root" ? "/root" : `/home/${username}`;
+    }
+    /** `sudo -u <user>`, in `cwd` (the user's home by default), with `env`
+     * given through `env` so it survives sudo. */
+    #wrap(params) {
+        const env = Object.entries(params.env ?? {}).map(([key, value]) => `${key}=${value}`);
+        return {
+            cmd: "sudo",
+            args: [
+                "-u",
+                this.username,
+                "--",
+                "bash",
+                "-c",
+                'cd "$1" || exit 1; shift; exec "$@"',
+                "bash",
+                params.cwd ?? this.homeDir,
+                ...(env.length ? ["env", ...env] : []),
+                params.cmd,
+                ...(params.args ?? []),
+            ],
+        };
+    }
+    #resolve(path) {
+        return path.startsWith("/") ? path : `${this.homeDir}/${path}`;
+    }
+    runCommand(commandOrParams, args, opts = {}) {
+        if (typeof commandOrParams === "string")
+            return this.#sandbox.runCommand({
+                ...this.#wrap({ cmd: commandOrParams, ...(args ? { args } : {}) }),
+                ...(opts.signal ? { signal: opts.signal } : {}),
+                ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+            });
+        const params = commandOrParams;
+        if (params.sudo)
+            return this.#sandbox.runCommand({ ...params });
+        const wrapped = this.#wrap(params);
+        return this.#sandbox.runCommand({
+            cmd: wrapped.cmd,
+            args: wrapped.args,
+            ...(params.detached ? { detached: true } : {}),
+            ...(params.stdout ? { stdout: params.stdout } : {}),
+            ...(params.stderr ? { stderr: params.stderr } : {}),
+            ...(params.signal ? { signal: params.signal } : {}),
+            ...(params.timeoutMs !== undefined ? { timeoutMs: params.timeoutMs } : {}),
+        });
+    }
+    /** Writes files into this user's home (or absolute paths), then gives them
+     * and the directories made for them to this user. */
+    async writeFiles(files, opts = {}) {
+        const absolute = files.map((file) => ({ ...file, path: this.#resolve(file.path) }));
+        await this.#sandbox.writeFiles(absolute, opts);
+        const paths = absolute.map((file) => file.path);
+        if (!paths.length)
+            return;
+        await this.#chown(paths, `${this.username}:${await this.#group(opts.signal)}`, opts.signal);
+        const dirs = this.#ancestorsUnderHome(paths);
+        if (dirs.length) {
+            const { group } = await this.#sandbox.getDefaultUser(opts);
+            await this.#chown(dirs, `${this.username}:${group}`, opts.signal);
+            await this.#chmod(dirs, "770", opts.signal);
+        }
+    }
+    /** The file as this user may read it, as a stream; null when missing. */
+    async readFile(file, opts = {}) {
+        const buffer = await this.#cat(file, opts);
+        if (buffer === null)
+            return null;
+        const { Readable } = await import("node:stream");
+        return Readable.from([buffer]);
+    }
+    /** The file as this user may read it; null when missing. */
+    readFileToBuffer(file, opts = {}) {
+        return this.#cat(file, opts);
+    }
+    /** Copies a file this user may read to the local disk; null when missing. */
+    async downloadFile(src, dst, opts = {}) {
+        const buffer = await this.#cat(src, opts);
+        if (buffer === null)
+            return null;
+        const { mkdir, writeFile } = await import("node:fs/promises");
+        const target = resolve(dst.cwd ?? "", dst.path);
+        if (opts.mkdirRecursive)
+            await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, buffer, opts.signal ? { signal: opts.signal } : {});
+        return target;
+    }
+    /** Reads as this user with `base64`, so the user's own permissions apply
+     * and binary files arrive whole. */
+    async #cat(file, opts) {
+        const path = file.path.startsWith("/") ? file.path : `${file.cwd ?? this.homeDir}/${file.path}`;
+        const result = await this.runCommand({
+            cmd: "base64",
+            args: [path],
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        });
+        if (result.exitCode !== 0) {
+            const stderr = await result.stderr();
+            if (/No such file or directory/i.test(stderr))
+                return null;
+            throw new Error(`Failed to read ${path}: ${stderr}`);
+        }
+        return Buffer.from(await result.stdout(), "base64");
+    }
+    /** Makes a directory owned by this user. */
+    async mkDir(path, opts = {}) {
+        const absolute = this.#resolve(path);
+        await this.#sandbox.mkDir(absolute, opts);
+        const dirs = [absolute, ...this.#ancestorsUnderHome([absolute])];
+        const { group } = await this.#sandbox.getDefaultUser(opts);
+        await this.#chown(dirs, `${this.username}:${group}`, opts.signal);
+        await this.#chmod(dirs, "770", opts.signal);
+    }
+    async addToGroup(groupname, opts = {}) {
+        validateName(groupname, "group name");
+        await this.#sandbox.addUserToGroup(this.username, groupname, opts);
+    }
+    async removeFromGroup(groupname, opts = {}) {
+        validateName(groupname, "group name");
+        await this.#sandbox.removeUserFromGroup(this.username, groupname, opts);
+    }
+    /** The user's primary group, read from the sandbox once. */
+    #group(signal) {
+        this.#primaryGroup ??= (async () => {
+            const result = await this.#sandbox.runCommand({
+                cmd: "id",
+                args: ["-gn", this.username],
+                ...(signal ? { signal } : {}),
+            });
+            if (result.exitCode !== 0)
+                throw new Error(`Failed to resolve the primary group of "${this.username}": ${await result.stderr()}`);
+            const group = (await result.stdout()).trim();
+            if (!group)
+                throw new Error(`Failed to resolve the primary group of "${this.username}"`);
+            return group;
+        })().catch((error) => {
+            this.#primaryGroup = undefined;
+            throw error;
+        });
+        return this.#primaryGroup;
+    }
+    async #chown(paths, owner, signal) {
+        await rootOrThrow(this.#sandbox, "chown", [owner, ...paths], signal, () => `Failed to set ownership on ${paths.join(", ")}`);
+    }
+    async #chmod(paths, mode, signal) {
+        await rootOrThrow(this.#sandbox, "chmod", [mode, ...paths], signal, () => `Failed to set permissions on ${paths.join(", ")}`);
+    }
+    /** The directories strictly between this user's home and each path. */
+    #ancestorsUnderHome(paths) {
+        const dirs = new Set();
+        const prefix = `${this.homeDir}/`;
+        for (const path of paths) {
+            let dir = path.slice(0, path.lastIndexOf("/"));
+            while (dir.length > this.homeDir.length && dir.startsWith(prefix)) {
+                dirs.add(dir);
+                dir = dir.slice(0, dir.lastIndexOf("/"));
+            }
+        }
+        return [...dirs];
+    }
+}
+/** Runs `cmd args` under sudo; a non-zero exit throws `what(): <stderr>`. */
+export async function rootOrThrow(sandbox, cmd, args, signal, what) {
+    const result = await sandbox.runCommand({ cmd, args, sudo: true, ...(signal ? { signal } : {}) });
+    if (result.exitCode !== 0)
+        throw new Error(`${what()}: ${await result.stderr()}`);
+    return result;
+}

package/dist/vercel/sandbox.d.ts

@@ -3,12 +3,15 @@ import type { Runtime } from "../client.js";
 import { type Credentials, type RuntimeCreate, type RuntimeSandbox, type WithRuntime } from "./client.js";
 import { Command, CommandFinished } from "./command.js";
 import { FileSystem } from "./filesystem.js";
+import { SandboxUser } from "./sandbox-user.js";
 import { Snapshot } from "./snapshot.js";
 /** Vercel's default machine: 2 vCPUs with 2048 MB each (checked 23 September
  * 2026). Runtime gives 2 vCPU and 4096 MiB. */
 export declare const DEFAULT_VCPUS = 2;
 export declare const MEMORY_MIB_PER_VCPU = 2048;
-/** Vercel's default timeout, 5 minutes. */
+/** Vercel's default timeout, 5 minutes. Not sent: a sandbox created with no
+ * timeout has no time limit on Runtime, running while it works and pausing
+ * when idle (0300). Kept for code that imports it. */
 export declare const DEFAULT_TIMEOUT_MS = 300000;
 /** Vercel's working directory; `/workspace` on Runtime. */
 export declare const HOME = "/vercel/sandbox";
@@ -39,7 +42,10 @@ export interface CreateSandboxParams extends Credentials {
     /** Shared at public HTTPS addresses (Runtime previews); `domain(port)`
      * answers from them. */
     ports?: number[];
-    /** Milliseconds. Default 300 000; 60 s to 1 hour on Runtime. */
+    /** Milliseconds, at least 60 s: when it stops. Leave it out for no time
+     * limit: it runs while it works and pauses when idle. Over an hour, the
+     * hour-long limit is extended while this object lives, up to the timeout
+     * (`sandbox.timeout`). */
     timeout?: number;
     resources?: {
         vcpus: number;
@@ -131,13 +137,16 @@ export declare class Sandbox {
     get updatedAt(): Date;
     get cwd(): string;
     get status(): "pending" | "running" | "stopping" | "stopped";
-    /** Milliseconds. */
+    /** Milliseconds from the start of the session: the timeout given at
+     * create, with every extension, or the time limit of a sandbox found by
+     * name. 0 for one with no time limit, which runs while it works. */
     get timeout(): number;
     get expiresAt(): Date;
     get tags(): Record<string, string>;
     get sourceSnapshotId(): string | undefined;
     /** Creates a sandbox and waits until it runs. Vercel's defaults: 2 vCPUs,
-     * 2048 MiB per vCPU, a 5-minute timeout, persistent. Funding is left to
+     * 2048 MiB per vCPU, persistent. With no `timeout` it has no time limit: it
+     * runs while it works and pauses when idle. A `timeout` is kept as given. Funding is left to
      * Runtime: the free trial while the account has trial time, then prepaid
      * credit, exactly as withruntime's own create. */
     static create(params?: CreateSandboxParams): Promise<Sandbox & AsyncDisposable>;
@@ -162,14 +171,23 @@ export declare class Sandbox {
         sourceSandbox: string;
     }): Promise<Sandbox & AsyncDisposable>;
     /** Running and stopped (paused) sandboxes, oldest first, with Vercel's
-     * paginator: `for await (const s of await Sandbox.list())`. */
+     * paginator: `for await (const s of await Sandbox.list())`. A name prefix,
+     * creation-time bounds (`since`, `until`, epoch ms), `sortBy` and
+     * `sortOrder`, and a `cursor` from an earlier page are applied here, over
+     * every sandbox the key sees. */
     static list(params?: {
         tags?: Record<string, string>;
         limit?: number;
+        namePrefix?: string;
+        sortBy?: "createdAt" | "name" | "statusUpdatedAt";
+        sortOrder?: "asc" | "desc";
+        cursor?: string;
+        since?: number | Date;
+        until?: number | Date;
         signal?: AbortSignal;
     } & Credentials & {
         withruntime?: WithRuntime;
-    } & Record<string, unknown>): Promise<{
+    }): Promise<{
         sandboxes: ListItem[];
         pagination: {
             count: number;
@@ -256,8 +274,10 @@ export declare class Sandbox {
         signal?: AbortSignal;
     }): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
-    /** Moves the end `duration` milliseconds later (at most an hour ahead of
-     * now on Runtime). */
+    /** Moves the end `duration` milliseconds later. The time limit moves at
+     * once as far as it may (an hour ahead of now); past that it is extended
+     * while this object lives. A sandbox with no time limit has no end to
+     * move, and nothing changes. */
     extendTimeout(duration: number, opts?: {
         signal?: AbortSignal;
     }): Promise<void>;
@@ -267,7 +287,8 @@ export declare class Sandbox {
     }): Promise<NetworkPolicy>;
     /** Changes what Runtime can change on a sandbox: `timeout`, `ports`,
      * `networkPolicy` and `snapshotExpiration`. Anything else is refused before
-     * anything changes. */
+     * anything changes. A `timeout` on a sandbox with no time limit changes
+     * nothing: it runs while it works. */
     update(params: {
         timeout?: number;
         ports?: number[];
@@ -283,16 +304,37 @@ export declare class Sandbox {
         expiration?: number;
         signal?: AbortSignal;
     }): Promise<Snapshot>;
+    /** Refused: Vercel hands back a token scoped to this one shell, and
+     * Runtime's terminal opens with the account key, which must not leave the
+     * server. */
     openInteractive(): Promise<never>;
-    getDefaultUser(): Promise<{
+    /** The user commands run as, `runtime`, and its group. */
+    getDefaultUser(_opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
         username: string;
         group: string;
     }>;
-    createUser(): Promise<never>;
-    asUser(): never;
-    createGroup(): Promise<never>;
-    addUserToGroup(): Promise<never>;
-    removeUserFromGroup(): Promise<never>;
+    /** Makes a Linux user with its own home, as Vercel does: `useradd -m`,
+     * then the home given to the user and the sandbox's group, mode 770. */
+    createUser(username: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SandboxUser>;
+    /** A handle for an existing user, such as `root`. */
+    asUser(username: "root" | (string & {})): SandboxUser;
+    /** Makes a group and its shared directory, `/shared/<group>`, setgid 2770. */
+    createGroup(groupname: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        groupname: string;
+        sharedDir: string;
+    }>;
+    addUserToGroup(username: string, groupname: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    removeUserFromGroup(username: string, groupname: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
     currentSession(): never;
     listSessions(): Promise<never>;
     listSnapshots(): Promise<never>;