withruntime 0.9.0 → 0.11.0

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,6 +3,7 @@ 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. */
@@ -39,7 +40,9 @@ 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. Default 300 000, at least 60 s. Over an hour, the
+     * sandbox's hour-long lease is extended while this object lives, up to the
+     * timeout (`sandbox.timeout`). */
     timeout?: number;
     resources?: {
         vcpus: number;
@@ -60,7 +63,7 @@ export interface CreateSandboxParams extends Credentials {
     /** Milliseconds a stopped persistent sandbox is kept, as Runtime's
      * retention (whole days, 1 to 365; 0 is 365). */
     snapshotExpiration?: number;
-    /** Accepted: a paused Runtime sandbox keeps exactly its latest state. */
+    /** Refused: Runtime does not enforce snapshot count or eviction policies. */
     keepLastSnapshots?: {
         count: number;
         expiration?: number;
@@ -131,7 +134,8 @@ 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 lease of a sandbox found by name. */
     get timeout(): number;
     get expiresAt(): Date;
     get tags(): Record<string, string>;
@@ -162,14 +166,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;
@@ -198,10 +211,10 @@ export declare class Sandbox {
     }): Promise<Command>;
     runCommand(params: RunCommandParams): Promise<CommandFinished>;
     /** A command started earlier, by its cmdId. */
-    getCommand(cmdId: string, _opts?: {
+    getCommand(cmdId: string, opts?: {
         signal?: AbortSignal;
     }): Promise<Command>;
-    mkDir(path: string, _opts?: {
+    mkDir(path: string, opts?: {
         signal?: AbortSignal;
     }): Promise<void>;
     /** The file's bytes as a Node stream, or null when there is no file. */
@@ -235,7 +248,7 @@ export declare class Sandbox {
         path: string;
         content: string | Uint8Array;
         mode?: number;
-    }[], _opts?: {
+    }[], opts?: {
         signal?: AbortSignal;
     }): Promise<void>;
     /** The public address of a port listed in `ports`, such as
@@ -256,13 +269,14 @@ 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 lease moves at once
+     * as far as it may (an hour ahead of now); past that it is extended while
+     * this object lives. */
     extendTimeout(duration: number, opts?: {
         signal?: AbortSignal;
     }): Promise<void>;
     /** Replaces the network rules; returns the policy given. */
-    updateNetworkPolicy(networkPolicy: NetworkPolicy, _opts?: {
+    updateNetworkPolicy(networkPolicy: NetworkPolicy, opts?: {
         signal?: AbortSignal;
     }): Promise<NetworkPolicy>;
     /** Changes what Runtime can change on a sandbox: `timeout`, `ports`,
@@ -273,26 +287,47 @@ export declare class Sandbox {
         ports?: number[];
         networkPolicy?: NetworkPolicy;
         snapshotExpiration?: number;
-    } & Record<string, unknown>, _opts?: {
+    } & Record<string, unknown>, opts?: {
         signal?: AbortSignal;
     }): Promise<void>;
-    /** Keeps the sandbox's whole machine as a Runtime snapshot (files, memory
-     * and running processes), then stops the sandbox, as Vercel does. Start
+    /** Keeps the sandbox's filesystem as a disk-only snapshot, then stops
+     * the source. Restoring it starts fresh processes, as Vercel does. Start
      * from it with `Sandbox.create({ source: { type: "snapshot", snapshotId } })`. */
     snapshot(opts?: {
         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>;