sandboxedjs 0.1.28 → 0.1.30

package/dist/index.d.cts

@@ -25,9 +25,41 @@ interface ChildSpawnConfig {
     cwd?: string;
     env?: Record<string, string>;
     parentPid?: number;
+    /**
+     * The child was given the parent's streams (`stdio: "inherit"`).
+     *
+     * Its input is then the parent's terminal rather than a pipe that will end,
+     * which is the difference between a program that waits for what the user
+     * types and one that reads to end-of-input and stops.
+     */
+    inheritStdio?: boolean;
 }
 type SpawnChild = (config: ChildSpawnConfig) => ChildHandle;
-declare function createChildProcessModule(spawnChild: SpawnChild, defaultCwd: () => string): Record<string, unknown>;
+/**
+ * Run a child to completion without returning to the event loop.
+ *
+ * Supplied only by a pod that can actually block — one whose guest runs on its
+ * own thread. Where it is absent the synchronous entry points keep reporting
+ * that they are unavailable, which is the honest answer for an in-realm pod.
+ */
+type SyncSpawn = (request: {
+    command: string;
+    args: string[];
+    cwd: string;
+    env?: Record<string, string>;
+    input?: string;
+    inheritStdio?: boolean;
+}) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    signal: string | null;
+    error?: {
+        code?: string;
+        message: string;
+    };
+};
+declare function createChildProcessModule(spawnChild: SpawnChild, defaultCwd: () => string, syncSpawn?: SyncSpawn, defaultEnv?: () => Record<string, string>): Record<string, unknown>;
 
 /**
  * Clean-room contracts between SandboxedJS and its JavaScript runtime.
@@ -1639,6 +1671,24 @@ interface ContainerOptions {
      * ```
      */
     pod?: RuntimePod;
+    /**
+     * Where guest programs run.
+     *
+     * `"worker"` (the default) gives each program its own thread, which is what
+     * makes synchronous child processes work and keeps guest code out of the
+     * host's realm; it falls back automatically where the host cannot support it.
+     * `"realm"` forces the in-realm runtime.
+     */
+    isolation?: "worker" | "realm";
+    /**
+     * Where to load the guest worker bundle from.
+     *
+     * Defaults to the copy shipped beside the main bundle, which is what a
+     * published package wants. Worth setting when a bundler has moved or
+     * rewritten it — or when running from source, where the built file is the
+     * only one a Worker can load.
+     */
+    workerUrl?: string | URL;
     /** Python runtime settings; a browser host uses this to locate the wasm. */
     python?: PythonOptions;
 }
@@ -2457,6 +2507,14 @@ interface CoreModulesOptions {
     };
     /** Backs `child_process`; without it the module reports as unavailable. */
     spawnChild?: SpawnChild;
+    /**
+     * Backs the `*Sync` half of `child_process`.
+     *
+     * Only a pod whose guest runs on its own thread can supply this — blocking
+     * requires somewhere else for the child's work to happen. Without it the
+     * synchronous entry points keep reporting that they are unavailable.
+     */
+    syncSpawn?: SyncSpawn;
     /** File holding the process's standard input, exposed as descriptor 0. */
     stdinPath?: string;
     /** Keep `process.stdin` open and fed by {@link writeStdin} rather than ending it. */
@@ -2496,6 +2554,13 @@ declare function createCoreModules(options: CoreModulesOptions): {
     pendingHandles(): number;
     /** Active timers which called `unref()` and therefore only merit startup grace. */
     pendingUnrefed(): number;
+    /**
+     * Cancel every timer this process still holds.
+     *
+     * Called when a process is killed: the process is finished, but its
+     * scheduled work would otherwise keep running on the host's event loop.
+     */
+    cancelTimers(): void;
     /**
      * Client requests sent but not yet read to completion.
      *
@@ -2533,6 +2598,99 @@ declare function looksLikeEsm(source: string): boolean;
  */
 declare function transformEsm(source: string, filename?: string): EsmTransformResult | null;
 
+/**
+ * A volume that keeps a second, foreign filesystem in step with itself.
+ *
+ * Rolldown's browser WebAssembly binding owns a `memfs` volume of its own —
+ * its Rust resolver reads through WASI, not through anything JavaScript can
+ * hand it. So the sandbox project has to exist in two places at once, and the
+ * copy has to stay current: a dev server reads `index.html` when the request
+ * arrives, not when the process started.
+ *
+ * Mirroring on write rather than copying up-front is what makes that true. The
+ * previous approach took one deep snapshot per spawn, which was both expensive
+ * — every `npm run dev` re-copied `node_modules` — and already stale by the
+ * time it mattered, so an edit during a session was served from the old tree.
+ *
+ * The mirror is deliberately one-way and best-effort. It is a cache for a
+ * consumer that only reads; a write that fails to reach it must never fail the
+ * write that the container itself made.
+ */
+
+/** The slice of a `memfs`-style filesystem the mirror writes through. */
+interface MirrorFs {
+    mkdirSync(path: string, options?: {
+        recursive?: boolean;
+    }): void;
+    writeFileSync(path: string, data: Uint8Array): void;
+    symlinkSync(target: string, path: string): void;
+    rmSync?(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): void;
+    unlinkSync?(path: string): void;
+    rmdirSync?(path: string): void;
+}
+/**
+ * A `RuntimeVolume` that forwards every mutation to an optional mirror.
+ *
+ * Wrapping rather than modifying `MemoryVolume` keeps the mirroring concern out
+ * of the filesystem, and keeps this transparent to the kernel, whose `Vfs`
+ * takes any `RuntimeVolume`.
+ */
+declare class MirroringVolume implements RuntimeVolume {
+    private readonly inner;
+    private mirror;
+    private root;
+    constructor(inner?: MemoryVolume);
+    /**
+     * Start mirroring the tree under `root`, seeding it with what is there now.
+     *
+     * Called once the Rolldown binding is known to be in play; before that a
+     * container pays nothing for this.
+     */
+    attach(mirror: MirrorFs, root: string): void;
+    detach(): void;
+    /** Copy the whole subtree across. The only bulk operation that remains. */
+    private seed;
+    /** Is this path inside the mirrored subtree? */
+    private mirrored;
+    /**
+     * Run a mirror update, swallowing failure.
+     *
+     * The mirror is a read-only cache for another engine. If it rejects
+     * something — an unsupported operation, a path it has not seen — the
+     * container's own write has still happened and must still succeed.
+     */
+    private safely;
+    /** Push a path's current state across, whatever it is now. */
+    private sync;
+    readFileSync(path: string): Uint8Array;
+    readdirSync(path: string): string[];
+    lstatSync(path: string): VolumeStat;
+    readlinkSync(path: string): string;
+    getStats(): VolumeStats;
+    writeFileSync(path: string, data: string | Uint8Array): void;
+    appendFileSync(path: string, data: string | Uint8Array): void;
+    mkdirSync(path: string, options?: {
+        mode?: number;
+    }): void;
+    rmdirSync(path: string): void;
+    unlinkSync(path: string): void;
+    renameSync(from: string, to: string): void;
+    symlinkSync(target: string, path: string): void;
+    linkSync(existing: string, path: string): void;
+    truncateSync(path: string, length?: number): void;
+    chmodSync(path: string, mode: number): void;
+    lchmodSync(path: string, mode: number): void;
+    chownSync(path: string, uid: number, gid: number): void;
+    lchownSync(path: string, uid: number, gid: number): void;
+    utimesSync(path: string, atime: Date, mtime: Date): void;
+    snapshot(): MemoryVolumeSnapshotEntry[];
+    /** A restore replaces everything, so the mirror is rebuilt rather than patched. */
+    restore(entries: MemoryVolumeSnapshotEntry[]): void;
+}
+
 interface LocalRuntimeOptions {
     workdir?: string;
     env?: Record<string, string>;
@@ -2569,10 +2727,10 @@ declare const WASM_ALIASES: Record<string, string>;
  * dedicated Worker before this becomes the default untrusted-code path.
  */
 declare class LocalRuntimePod implements RuntimePod {
-    readonly volume: MemoryVolume;
+    readonly volume: MirroringVolume;
     readonly packages: RuntimePackageInstaller;
     readonly instanceId: string;
-    private readonly router;
+    protected readonly router: VirtualHttpRouter;
     readonly proxy: {
         activePorts: (_instanceId?: string) => number[];
     };
@@ -2585,15 +2743,15 @@ declare class LocalRuntimePod implements RuntimePod {
         spawn(config: ChildSpawnConfig): ChildHandle;
     };
     private disposed;
-    private readonly workdir;
-    private readonly env;
-    private readonly aliases;
+    protected readonly workdir: string;
+    protected readonly env: Record<string, string>;
+    protected readonly aliases: Record<string, string>;
     private readonly modules;
     private readonly esbuild;
     private rolldownBinding;
     /** Backs outbound `http`/`https` client requests from inside the sandbox. */
     private readonly fetch;
-    private constructor();
+    protected constructor(options: LocalRuntimeOptions);
     static boot(options?: LocalRuntimeOptions): Promise<LocalRuntimePod>;
     spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
     /**
@@ -2628,6 +2786,68 @@ declare class LocalRuntimePod implements RuntimePod {
     private assertActive;
 }
 
+/**
+ * A pod that evaluates each guest program on its own thread.
+ *
+ * Everything shared stays here: the volume, the HTTP router, the package
+ * installer and the process table. Only the program's own evaluation moves,
+ * and it reaches back for the rest through a {@link SyncChannelServer}.
+ *
+ * That arrangement is forced rather than chosen. A synchronous call has to
+ * block the caller while the work it is waiting on still makes progress, so
+ * the blocking side cannot be the side that owns the resources — otherwise a
+ * child process needing the filesystem would have to call into a thread that
+ * is frozen waiting for that child. The guest blocks; the host never does.
+ *
+ * It inherits from {@link LocalRuntimePod} because every other part of the
+ * contract is identical, and overriding one method is a smaller and more
+ * honest claim than reimplementing nine. Both are held to the same contract
+ * suite (`test/pod-contract.ts`).
+ */
+
+interface WorkerRuntimeOptions extends LocalRuntimeOptions {
+    /** Where the guest bundle lives; defaults to the copy shipped beside this one. */
+    workerUrl?: string | URL;
+}
+declare class WorkerRuntimePod extends LocalRuntimePod {
+    private readonly workerUrl;
+    /** Live workers, so teardown can stop them all. */
+    private readonly live;
+    protected constructor(options: WorkerRuntimeOptions);
+    /**
+     * Boot a Worker-backed pod, or return null when this host cannot support one.
+     *
+     * Declining is a first-class outcome. `SharedArrayBuffer` needs cross-origin
+     * isolation, a bundler may have made the guest script unreachable, and a host
+     * that supplied its own module objects has handed over things no thread
+     * boundary can carry. In every case the caller falls back to the in-realm pod
+     * and keeps working.
+     */
+    static tryBoot(options?: WorkerRuntimeOptions): Promise<WorkerRuntimePod | null>;
+    spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
+    private spawnInWorker;
+    /** Start an asynchronous child on the host's behalf and relay its events. */
+    private startChild;
+    /** Run a child to completion and collect it, for the guest's `spawnSync`. */
+    private runChildToCompletion;
+    private readonly proxies;
+    private readonly waiting;
+    private nextRequestId;
+    /**
+     * Register a stand-in for a server that is actually running in the Worker.
+     *
+     * The router only knows how to reach servers on this thread, so each bound
+     * port gets a local server whose whole job is to forward and wait.
+     */
+    private proxyPort;
+    private forward;
+    private settleProxied;
+    private closeProxies;
+    teardown(): void;
+    /** Does anything under `cwd` need a module only the host can supply? */
+    private needsHostModules;
+}
+
 interface RegistryManifest {
     name: string;
     version: string;
@@ -2678,6 +2898,99 @@ declare class CleanPackageInstaller implements RuntimePackageInstaller {
 }
 declare function extractNpmTarball(volume: RuntimeVolume, compressed: Uint8Array, destination: string): void;
 
+/**
+ * Starting the guest Worker, in whichever environment the host happens to be.
+ *
+ * The awkward part of shipping a Worker from a library is not creating it, but
+ * naming it. `new URL("./worker-entry.js", import.meta.url)` is the form every
+ * bundler recognises, and it resolves correctly from `dist/` — but a bundler
+ * that *pre-bundles* this package rewrites `import.meta.url` to point into its
+ * own dependency cache, where no such file exists. That is the same trap
+ * Rolldown's WASI binding falls into, and it surfaces just as obliquely.
+ *
+ * So this never assumes it worked. The caller treats a failure to start as
+ * "this host cannot run the Worker pod" and uses the in-realm pod instead.
+ */
+interface RuntimeWorker {
+    postMessage(message: unknown): void;
+    onMessage(listener: (message: unknown) => void): void;
+    onError(listener: (error: unknown) => void): void;
+    terminate(): unknown;
+}
+/**
+ * Start the guest Worker and wait for it to say it is alive.
+ *
+ * Rejects rather than hanging when the script cannot be loaded: a Worker whose
+ * script 404s reports an `error` event and would otherwise leave the caller
+ * waiting for a ready message that can never arrive.
+ */
+declare function startRuntimeWorker(options?: {
+    url?: string | URL;
+    workerData?: Record<string, unknown>;
+    timeoutMs?: number;
+}): Promise<RuntimeWorker>;
+
+/**
+ * Can this environment support a blocking client at all?
+ *
+ * `SharedArrayBuffer` needs cross-origin isolation in a browser, and
+ * `Atomics.wait` is forbidden on a browser's main thread — which is why the
+ * client is always the Worker.
+ */
+declare function syncChannelSupported(): boolean;
+
+/**
+ * Wiring a container's HTTP servers up to real URLs in the page.
+ *
+ * The service worker does the routing; this is the half that lives in the page
+ * and actually knows about the container.
+ *
+ * **Read the origin note before using this.** A preview served this way runs on
+ * *your* origin, so scripts inside it can reach `window.parent`, your cookies
+ * and your `localStorage` — the sandbox contains the program's *filesystem and
+ * process table*, not the page it serves. For code you did not write, either
+ * host the preview on a separate origin, or use {@link renderInto}, which puts
+ * the response in an iframe with no origin at all.
+ */
+
+interface PreviewOptions {
+    /** Where the worker script lives; defaults to the copy shipped beside the bundle. */
+    scriptUrl?: string | URL;
+    /** Registration scope. Must be able to see the paths a preview will request. */
+    scope?: string;
+}
+interface Preview {
+    /** The URL an iframe should be pointed at to see `port`. */
+    urlFor(port: number): string;
+    /** Stop answering requests and unregister the worker. */
+    dispose(): Promise<void>;
+}
+/**
+ * Register the preview worker and start answering its requests from `box`.
+ *
+ * Resolves to null where service workers are unavailable — a non-secure origin,
+ * a browser with them disabled, or any non-browser host. Callers should treat
+ * that as "no preview URLs here" and fall back to `box.request`.
+ */
+declare function createPreview(box: Container, options?: PreviewOptions): Promise<Preview | null>;
+/**
+ * Show one response from the container inside an element, without letting it
+ * touch the page.
+ *
+ * The iframe is sandboxed with `allow-scripts` and deliberately *without*
+ * `allow-same-origin`, which puts the document in an opaque origin: its scripts
+ * run, and they can reach neither this page's DOM nor its cookies and storage.
+ * That combination is what makes it safe to render output you do not trust.
+ *
+ * The trade-off is that only this one response exists — a page that asks for
+ * `/main.js` gets nothing, because there is no origin to serve it from. For a
+ * whole site, use {@link createPreview}, and read its note about origins first.
+ */
+declare function renderInto(box: Container, element: HTMLElement, options?: {
+    port: number;
+    path?: string;
+}): Promise<HTMLIFrameElement>;
+
 /**
  * sandboxedjs — a Linux-like container that runs entirely inside Node.js.
  *
@@ -2696,4 +3009,4 @@ declare function extractNpmTarball(volume: RuntimeVolume, compressed: Uint8Array
  * ```
  */
 
-export { ArithError, BufferSink, type CPythonOptions, CallbackSink, type ChildHandle, type ChildSpawnConfig, type CleanInstallerOptions, CleanPackageInstaller, type Command, CommandRegistry, CommonJsEngine, type CommonJsEngineOptions, type CommonJsModule, Container, ContainerFs, type ContainerOptions, type ContextInit, type CoreModulesOptions, type Cred, type DirEntry, ERRNO, type Env, type ErrnoCode, type EsmTransformResult, type ExecContext, type ExecOptions, type ExecResult, type FileData, FileInput, FileOutput, type GroupEntry, type HttpResponse, IncompleteInputError, type InputStream, type InstallOptions, type Job, KERNEL_NAME, KERNEL_RELEASE, Kernel, type KernelOptions, type ListeningPort, type LocalRuntimeOptions, LocalRuntimePod, MemoryVolume, type MountEntry, NODE_VERSION, NPM_VERSION, type NetInterface, type NetworkOptions, NetworkStack, NullInput, NullOutput, OS_RELEASE, type OutputStream, PYTHON_VERSION, type PasswdEntry, Pipe, Process, type ProcessKind, type ProcessOptions, type ProcessState, ProcessTable, type PythonOptions, ROOT_CRED, type ResolvedExecutable, type RootfsOptions, type RunOptions, type RunResult, type RuntimePackageInstaller, type RuntimePod, type RuntimeProcess, type RuntimeProcessManager, type RuntimeProcessResult, type RuntimeVolume, SIGNALS, SIGNAL_NAMES, Session, type SessionInit, type SessionResult, type SessionRunOptions, Shell, ShellExit, type ShellIO, type ShellInit, Lexer as ShellLexer, type ShellOptions, ShellSyntaxError, type SpawnChild, type SpawnHandle, Stats, type Stdio, SysError, TeeOutput, Terminal, type TerminalOptions, UserDatabase, Variables, Vfs, VirtualHttpRouter, VirtualHttpServer, VirtualIncomingMessage, type VirtualNode, type VirtualProvider, VirtualServerResponse, WASM_ALIASES, type WriteOptions, allCommands, applyChmod, braceExpand, buildRootfs, builtinNames, captureStdio, configureCPython, configurePython, createChildProcessModule, createContainer, createContext, createCoreModules, createContainer as default, defineCommand, evalArith, exitCodeForSignal, expandPrompt, expandWord, expandWords, extractNpmTarball, fnmatch, formatMode, getBuiltin, glob, globToRegex, hasMagic, installUserland, isBuiltinName, isCPythonAvailable, isPythonAvailable, isSysError, looksLikeEsm, makeCred, normalizeSignal, octalMode, parse as parseShell, parseUmask, path as posixPath, resetPidCounter, shellQuote, strerror, transformEsm, unameInfo };
+export { ArithError, BufferSink, type CPythonOptions, CallbackSink, type ChildHandle, type ChildSpawnConfig, type CleanInstallerOptions, CleanPackageInstaller, type Command, CommandRegistry, CommonJsEngine, type CommonJsEngineOptions, type CommonJsModule, Container, ContainerFs, type ContainerOptions, type ContextInit, type CoreModulesOptions, type Cred, type DirEntry, ERRNO, type Env, type ErrnoCode, type EsmTransformResult, type ExecContext, type ExecOptions, type ExecResult, type FileData, FileInput, FileOutput, type GroupEntry, type HttpResponse, IncompleteInputError, type InputStream, type InstallOptions, type Job, KERNEL_NAME, KERNEL_RELEASE, Kernel, type KernelOptions, type ListeningPort, type LocalRuntimeOptions, LocalRuntimePod, MemoryVolume, type MountEntry, NODE_VERSION, NPM_VERSION, type NetInterface, type NetworkOptions, NetworkStack, NullInput, NullOutput, OS_RELEASE, type OutputStream, PYTHON_VERSION, type PasswdEntry, Pipe, type Preview, type PreviewOptions, Process, type ProcessKind, type ProcessOptions, type ProcessState, ProcessTable, type PythonOptions, ROOT_CRED, type ResolvedExecutable, type RootfsOptions, type RunOptions, type RunResult, type RuntimePackageInstaller, type RuntimePod, type RuntimeProcess, type RuntimeProcessManager, type RuntimeProcessResult, type RuntimeVolume, SIGNALS, SIGNAL_NAMES, Session, type SessionInit, type SessionResult, type SessionRunOptions, Shell, ShellExit, type ShellIO, type ShellInit, Lexer as ShellLexer, type ShellOptions, ShellSyntaxError, type SpawnChild, type SpawnHandle, Stats, type Stdio, SysError, TeeOutput, Terminal, type TerminalOptions, UserDatabase, Variables, Vfs, VirtualHttpRouter, VirtualHttpServer, VirtualIncomingMessage, type VirtualNode, type VirtualProvider, VirtualServerResponse, WASM_ALIASES, type WorkerRuntimeOptions, WorkerRuntimePod, type WriteOptions, allCommands, applyChmod, braceExpand, buildRootfs, builtinNames, captureStdio, configureCPython, configurePython, createChildProcessModule, createContainer, createContext, createCoreModules, createPreview, createContainer as default, defineCommand, evalArith, exitCodeForSignal, expandPrompt, expandWord, expandWords, extractNpmTarball, fnmatch, formatMode, getBuiltin, glob, globToRegex, hasMagic, installUserland, isBuiltinName, isCPythonAvailable, isPythonAvailable, isSysError, looksLikeEsm, makeCred, normalizeSignal, octalMode, parse as parseShell, parseUmask, path as posixPath, renderInto, resetPidCounter, shellQuote, startRuntimeWorker, strerror, syncChannelSupported, transformEsm, unameInfo };