sandboxedjs 0.1.73 → 0.1.75

package/README.md

@@ -165,6 +165,17 @@ await session.run("echo $TOKEN in $(pwd)"); // → abc in /app
 
 ### Long-running processes
 
+A job put in the background with `&` keeps running after the command that started it returns,
+even from a stateless `exec`, and stops with `kill %N` in a session or when the container is
+disposed:
+
+```ts
+await box.exec("node server.js > /tmp/server.log 2>&1 &", { cwd: "/app" });
+await box.waitForPort(3000);
+```
+
+To hold the process yourself, spawn it:
+
 ```ts
 const proc = box.spawn("node server.js", { cwd: "/app" });
 
@@ -545,7 +556,10 @@ The container has no access to your filesystem, environment, or network unless y
 - The filesystem is entirely in memory. Code inside cannot read or write a host path — there is
   no `/Users`, no `/home/you`, no way to reach one.
 - Outbound network access is **off by default**; `curl https://…` fails until you pass
-  `network: { allowOutbound: true }`, optionally narrowed with `allowedHosts`.
+  `network: { allowOutbound: true }`, optionally narrowed with `allowedHosts`. The same policy
+  binds a program's own `fetch`, `http`, `https` and `WebSocket`: a refused request fails with
+  `ENETUNREACH`. `localhost` and `127.0.0.1` always mean the container's own servers — never the
+  host's.
 - Host files enter only through `files`, `mount()` or `copyIn()`, and leave only through
   `copyOut()` or `fs.readFile()`.
 - `timeoutMs` bounds runaway commands, and `exec` settles even when a process ignores its kill
@@ -1000,7 +1014,16 @@ Honest list of what does not work:
   through is to answer **No** to a prompt like `npm create vite`'s "Install with npm and start
   now?" and run `npm install && npm run dev` from the shell instead.
 - **No `net`, `tls`, `worker_threads` or `vm`.** `http` and `https` are served by a virtual stack
-  that `request()` talks to directly, so servers work; raw sockets do not.
+  that `request()` talks to directly, so servers work; raw sockets do not. A program can reach
+  servers anywhere in the container over HTTP (`http.get`, `fetch`), but not open a `WebSocket` to
+  one.
+- **`node:test` covers what test files use** — `test`/`it`, `describe`, hooks, subtests, `skip`,
+  `todo`, `only`, `mock.fn` and `mock.method`, with `spec` and `tap` reports — and `node --test`
+  finds and runs test files as Node 22 does. `run()`, coverage and mock timers are not
+  implemented. A test file exits when its tests finish, as under `--test-force-exit`.
+- **On the in-realm runtime, programs share one global object.** A global one program sets is
+  visible to the next. The worker runtime (the default where shared memory is available) gives
+  each program its own.
 - **Python is source-built CPython/WASM.** Each program gets its own interpreter
   process worker. Pure-Python wheels install normally; native extensions must
   be linked or published for Emscripten. The bundled wheel index includes the
@@ -1091,3 +1114,18 @@ agent sandbox, and a browser terminal.
 ## License
 
 MIT, with no dependency carrying a stricter licence.
+
+
+### Optional developer tool packs
+
+Host applications can add local Git operations through `createGitCommand`
+(isomorphic-git) and embedded PostgreSQL SQL through `createSqlCommand`
+(PGlite). These engines are optional and are not bundled into the core.
+`installWasmCommands` installs separately distributed, integrity-checked WASI
+commands. ELF files use registered compatibility, translation and emulation
+backends. Original experimental x86-64 engines are available as opt-in backends
+for a small freestanding instruction/syscall subset; see [Original engines](docs/original-x64.md).
+See [Developer tool packs](docs/developer-tool-packs.md) for examples and limits.
+`createFrontendPlaywright` adds Playwright-shaped, frontend-only automation of a
+same-origin iframe using the host browser; see
+[Frontend automation](docs/frontend-automation.md) for its supported subset.

package/dist/agent.d.cts

@@ -1,5 +1,5 @@
-import { C as Container } from './container-BxEoVOmX.cjs';
-import './contracts-CVgctitO.cjs';
+import { C as Container } from './container-NoLUp_fd.cjs';
+import './contracts-C2_dTgk3.cjs';
 
 /**
  * Structural copies of the LangChain Deep Agents backend contract.

package/dist/agent.d.ts

@@ -1,5 +1,5 @@
-import { C as Container } from './container-B5X6stfx.js';
-import './contracts-CVgctitO.js';
+import { C as Container } from './container-X8yZRFvW.js';
+import './contracts-C2_dTgk3.js';
 
 /**
  * Structural copies of the LangChain Deep Agents backend contract.

package/dist/{container-BxEoVOmX.d.cts → container-NoLUp_fd.d.cts}

@@ -1,4 +1,4 @@
-import { V as Vfs, C as Cred, f as RuntimePod, D as DirEntry, p as Stats } from './contracts-CVgctitO.cjs';
+import { V as Vfs, C as Cred, f as RuntimePod, O as OutboundPolicy, D as DirEntry, p as Stats } from './contracts-C2_dTgk3.cjs';
 
 /**
  * Byte streams for stdin/stdout/stderr, pipelines and redirections.
@@ -487,6 +487,8 @@ declare class NetworkStack {
         timeoutMs?: number;
         intervalMs?: number;
     }): Promise<boolean>;
+    /** The policy every way out of the container applies, not only the shell's. */
+    get policy(): OutboundPolicy;
     outboundAllowed(url: string): boolean;
     procNetDev(): string;
     procNetRoute(): string;
@@ -494,6 +496,83 @@ declare class NetworkStack {
     countRx(bytes: number, iface?: string): void;
 }
 
+type ExecutionTier = "compatibility" | "translation" | "emulation";
+interface BinaryInfo {
+    format: "elf";
+    bits: 32 | 64;
+    machine: number;
+    architecture: string;
+    littleEndian: boolean;
+}
+interface BinaryRequest {
+    path: string;
+    bytes: Uint8Array;
+    sha256: string;
+    info: BinaryInfo;
+}
+interface PreparedBinary {
+    /** Once execution begins, failure never retries another backend: effects may exist. */
+    run(ctx: ExecContext): Promise<number> | number;
+}
+type Preparation = {
+    supported: true;
+    program: PreparedBinary;
+} | {
+    supported: false;
+    reason: string;
+};
+interface BinaryBackend {
+    id: string;
+    tier: ExecutionTier;
+    /** Host-supplied trusted code. Preparation must not execute the guest or mutate its files. */
+    prepare(request: BinaryRequest, signal: AbortSignal): Promise<Preparation> | Preparation;
+}
+interface ExecutionDecision {
+    path: string;
+    backend: string;
+    tier: ExecutionTier;
+    supported: boolean;
+    reason?: string;
+}
+declare function binaryDigest(bytes: Uint8Array): string;
+declare function isElfBinary(bytes: Uint8Array): boolean;
+declare function inspectElf(bytes: Uint8Array): BinaryInfo;
+/** Per-container backend registry. No vendor packages or network services are built in. */
+declare class BinaryExecutionRegistry {
+    private readonly onDecision?;
+    private backends;
+    constructor(onDecision?: ((decision: ExecutionDecision) => void) | undefined);
+    register(backend: BinaryBackend): () => void;
+    clear(): void;
+    list(): {
+        id: string;
+        tier: ExecutionTier;
+    }[];
+    run(ctx: ExecContext, path: string): Promise<number>;
+}
+interface WasmCommandArtifact {
+    name: string;
+    bytes: Uint8Array;
+    /** Exact SHA-256 hex digest from the package's trusted manifest. */
+    sha256: string;
+}
+/** Install a host-loaded pack of WASI commands. Nothing is fetched implicitly. */
+declare function installWasmCommands(kernel: Kernel, artifacts: WasmCommandArtifact[]): void;
+/** Match exact Linux artifacts to their independently built, ABI-compatible WASI ports. */
+declare function createWasmCompatibilityBackend(id: string, entries: {
+    elfSha256: string;
+    wasm: WasmCommandArtifact;
+}[]): BinaryBackend;
+interface WasmTranslator {
+    /** Versioned compiler identity: change when flags, compiler or syscall ABI changes. */
+    id: string;
+    supports(info: BinaryInfo): boolean;
+    /** Supply a real compiler here. Null means unsupported, not a guest runtime failure. */
+    translate(request: BinaryRequest, signal: AbortSignal): Promise<Uint8Array | null>;
+}
+/** Bounded, content-addressed cache around a host-provided ELF → WASI translator. */
+declare function createTranslationBackend(translator: WasmTranslator, maxCacheBytes?: number): BinaryBackend;
+
 /**
  * The kernel: the object that owns the filesystem, the process table, the user
  * database and the executable namespace, and knows how to turn an `argv` into
@@ -540,7 +619,7 @@ interface RunResult {
     signal: string | null;
     timedOut: boolean;
 }
-type ExecutableKind = "builtin" | "script" | "unknown";
+type ExecutableKind = "builtin" | "script" | "native" | "unknown";
 interface ResolvedExecutable {
     kind: ExecutableKind;
     /** Absolute path of the file that was found. */
@@ -561,6 +640,7 @@ declare class Kernel {
     readonly vfs: Vfs;
     readonly procs: ProcessTable;
     readonly commands: CommandRegistry;
+    readonly binaries: BinaryExecutionRegistry;
     readonly users: UserDatabase;
     readonly pod: RuntimePod;
     readonly bootTime: number;
@@ -979,8 +1059,13 @@ declare class Shell {
     captureSubshell(command: string): Promise<string>;
     /** `<(cmd)` — run the command now and hand back a path holding its output. */
     private makeProcessSubstitution;
-    /** A copy that shares nothing mutable with this shell. */
-    fork(): Shell;
+    /**
+     * A copy that shares nothing mutable with this shell.
+     *
+     * Subshells and pipeline stages run as part of this shell's process. A
+     * background job passes a process of its own, the way fork(2) gives one.
+     */
+    fork(proc?: Process): Shell;
     private currentIO;
     run(node: Node, io: ShellIO): Promise<number>;
     private runList;
@@ -1543,6 +1628,14 @@ declare class Container {
     }): Session;
     /** The container-wide session used by `shell()` shorthand helpers. */
     get shell(): Session;
+    /**
+     * The streams one call collects into.
+     *
+     * They are detachable because a background job started by the command keeps
+     * writing after the call has returned. Nothing reads the result any more by
+     * then, so without `detach` a chatty server would grow the buffer for as long
+     * as it ran; afterwards its output still reaches the container-wide taps.
+     */
     private makeStdio;
     /** Send an HTTP request to a server running inside the container. */
     request(port: number, init?: {
@@ -1620,4 +1713,4 @@ declare class Container {
 /** Boot a container. The one function most callers need. */
 declare function createContainer(opts?: ContainerOptions): Promise<Container>;
 
-export { type SessionResult as $, type ProcessKind as A, BufferSink as B, Container as C, type ProcessOptions as D, type ExecContext as E, type FileData as F, type GroupEntry as G, type HttpResponse as H, type InputStream as I, type Job as J, Kernel as K, type ListeningPort as L, MANIFEST_FORMAT as M, type Node as N, type OutputStream as O, PYTHON_VERSION as P, type ProcessState as Q, ProcessTable as R, Shell as S, type PythonCapabilities as T, type PythonOptions as U, type PythonProfile as V, type PythonRuntimeManifest as W, type ResolvedExecutable as X, type RunOptions as Y, type RunResult as Z, type SessionInit as _, type ShellIO as a, type SessionRunOptions as a0, ShellExit as a1, type ShellInit as a2, type ShellOptions as a3, type SpawnHandle as a4, type Stdio as a5, TeeOutput as a6, UserDatabase as a7, Variables as a8, braceExpand as a9, captureStdio as aa, configureCPython as ab, configurePython as ac, createContext as ad, defineCommand as ae, expandWord as af, expandWords as ag, isCPythonAvailable as ah, isPythonAvailable as ai, resetPidCounter as aj, shellQuote as ak, validateManifest as al, Session as b, type Command as c, createContainer as d, type CPythonOptions as e, CallbackSink as f, CommandRegistry as g, ContainerFs as h, type ContainerOptions as i, type ContextInit as j, type Env as k, type ExecOptions as l, type ExecResult as m, FileInput as n, FileOutput as o, type KernelOptions as p, MANIFEST_SCHEMA_VERSION as q, type MountEntry as r, type NetInterface as s, type NetworkOptions as t, NetworkStack as u, NullInput as v, NullOutput as w, type PasswdEntry as x, Pipe as y, Process as z };
+export { type PythonCapabilities as $, NetworkStack as A, type BinaryBackend as B, Container as C, NullInput as D, type ExecContext as E, type FileData as F, type GroupEntry as G, type HttpResponse as H, type InputStream as I, type Job as J, Kernel as K, type ListeningPort as L, MANIFEST_FORMAT as M, type Node as N, type OutputStream as O, NullOutput as P, PYTHON_VERSION as Q, type PasswdEntry as R, Shell as S, Pipe as T, type Preparation as U, type PreparedBinary as V, Process as W, type ProcessKind as X, type ProcessOptions as Y, type ProcessState as Z, ProcessTable as _, type ShellIO as a, type PythonOptions as a0, type PythonProfile as a1, type PythonRuntimeManifest as a2, type ResolvedExecutable as a3, type RunOptions as a4, type RunResult as a5, type SessionInit as a6, type SessionResult as a7, type SessionRunOptions as a8, ShellExit as a9, shellQuote as aA, validateManifest as aB, type ShellInit as aa, type ShellOptions as ab, type SpawnHandle as ac, type Stdio as ad, TeeOutput as ae, UserDatabase as af, Variables as ag, type WasmCommandArtifact as ah, type WasmTranslator as ai, binaryDigest as aj, braceExpand as ak, captureStdio as al, configureCPython as am, configurePython as an, createContext as ao, createTranslationBackend as ap, createWasmCompatibilityBackend as aq, defineCommand as ar, expandWord as as, expandWords as at, inspectElf as au, installWasmCommands as av, isCPythonAvailable as aw, isElfBinary as ax, isPythonAvailable as ay, resetPidCounter as az, Session as b, type Command as c, createContainer as d, BinaryExecutionRegistry as e, type BinaryInfo as f, type BinaryRequest as g, BufferSink as h, type CPythonOptions as i, CallbackSink as j, CommandRegistry as k, ContainerFs as l, type ContainerOptions as m, type ContextInit as n, type Env as o, type ExecOptions as p, type ExecResult as q, type ExecutionDecision as r, type ExecutionTier as s, FileInput as t, FileOutput as u, type KernelOptions as v, MANIFEST_SCHEMA_VERSION as w, type MountEntry as x, type NetInterface as y, type NetworkOptions as z };

package/dist/{container-B5X6stfx.d.ts → container-X8yZRFvW.d.ts}

@@ -1,4 +1,4 @@
-import { V as Vfs, C as Cred, f as RuntimePod, D as DirEntry, p as Stats } from './contracts-CVgctitO.js';
+import { V as Vfs, C as Cred, f as RuntimePod, O as OutboundPolicy, D as DirEntry, p as Stats } from './contracts-C2_dTgk3.js';
 
 /**
  * Byte streams for stdin/stdout/stderr, pipelines and redirections.
@@ -487,6 +487,8 @@ declare class NetworkStack {
         timeoutMs?: number;
         intervalMs?: number;
     }): Promise<boolean>;
+    /** The policy every way out of the container applies, not only the shell's. */
+    get policy(): OutboundPolicy;
     outboundAllowed(url: string): boolean;
     procNetDev(): string;
     procNetRoute(): string;
@@ -494,6 +496,83 @@ declare class NetworkStack {
     countRx(bytes: number, iface?: string): void;
 }
 
+type ExecutionTier = "compatibility" | "translation" | "emulation";
+interface BinaryInfo {
+    format: "elf";
+    bits: 32 | 64;
+    machine: number;
+    architecture: string;
+    littleEndian: boolean;
+}
+interface BinaryRequest {
+    path: string;
+    bytes: Uint8Array;
+    sha256: string;
+    info: BinaryInfo;
+}
+interface PreparedBinary {
+    /** Once execution begins, failure never retries another backend: effects may exist. */
+    run(ctx: ExecContext): Promise<number> | number;
+}
+type Preparation = {
+    supported: true;
+    program: PreparedBinary;
+} | {
+    supported: false;
+    reason: string;
+};
+interface BinaryBackend {
+    id: string;
+    tier: ExecutionTier;
+    /** Host-supplied trusted code. Preparation must not execute the guest or mutate its files. */
+    prepare(request: BinaryRequest, signal: AbortSignal): Promise<Preparation> | Preparation;
+}
+interface ExecutionDecision {
+    path: string;
+    backend: string;
+    tier: ExecutionTier;
+    supported: boolean;
+    reason?: string;
+}
+declare function binaryDigest(bytes: Uint8Array): string;
+declare function isElfBinary(bytes: Uint8Array): boolean;
+declare function inspectElf(bytes: Uint8Array): BinaryInfo;
+/** Per-container backend registry. No vendor packages or network services are built in. */
+declare class BinaryExecutionRegistry {
+    private readonly onDecision?;
+    private backends;
+    constructor(onDecision?: ((decision: ExecutionDecision) => void) | undefined);
+    register(backend: BinaryBackend): () => void;
+    clear(): void;
+    list(): {
+        id: string;
+        tier: ExecutionTier;
+    }[];
+    run(ctx: ExecContext, path: string): Promise<number>;
+}
+interface WasmCommandArtifact {
+    name: string;
+    bytes: Uint8Array;
+    /** Exact SHA-256 hex digest from the package's trusted manifest. */
+    sha256: string;
+}
+/** Install a host-loaded pack of WASI commands. Nothing is fetched implicitly. */
+declare function installWasmCommands(kernel: Kernel, artifacts: WasmCommandArtifact[]): void;
+/** Match exact Linux artifacts to their independently built, ABI-compatible WASI ports. */
+declare function createWasmCompatibilityBackend(id: string, entries: {
+    elfSha256: string;
+    wasm: WasmCommandArtifact;
+}[]): BinaryBackend;
+interface WasmTranslator {
+    /** Versioned compiler identity: change when flags, compiler or syscall ABI changes. */
+    id: string;
+    supports(info: BinaryInfo): boolean;
+    /** Supply a real compiler here. Null means unsupported, not a guest runtime failure. */
+    translate(request: BinaryRequest, signal: AbortSignal): Promise<Uint8Array | null>;
+}
+/** Bounded, content-addressed cache around a host-provided ELF → WASI translator. */
+declare function createTranslationBackend(translator: WasmTranslator, maxCacheBytes?: number): BinaryBackend;
+
 /**
  * The kernel: the object that owns the filesystem, the process table, the user
  * database and the executable namespace, and knows how to turn an `argv` into
@@ -540,7 +619,7 @@ interface RunResult {
     signal: string | null;
     timedOut: boolean;
 }
-type ExecutableKind = "builtin" | "script" | "unknown";
+type ExecutableKind = "builtin" | "script" | "native" | "unknown";
 interface ResolvedExecutable {
     kind: ExecutableKind;
     /** Absolute path of the file that was found. */
@@ -561,6 +640,7 @@ declare class Kernel {
     readonly vfs: Vfs;
     readonly procs: ProcessTable;
     readonly commands: CommandRegistry;
+    readonly binaries: BinaryExecutionRegistry;
     readonly users: UserDatabase;
     readonly pod: RuntimePod;
     readonly bootTime: number;
@@ -979,8 +1059,13 @@ declare class Shell {
     captureSubshell(command: string): Promise<string>;
     /** `<(cmd)` — run the command now and hand back a path holding its output. */
     private makeProcessSubstitution;
-    /** A copy that shares nothing mutable with this shell. */
-    fork(): Shell;
+    /**
+     * A copy that shares nothing mutable with this shell.
+     *
+     * Subshells and pipeline stages run as part of this shell's process. A
+     * background job passes a process of its own, the way fork(2) gives one.
+     */
+    fork(proc?: Process): Shell;
     private currentIO;
     run(node: Node, io: ShellIO): Promise<number>;
     private runList;
@@ -1543,6 +1628,14 @@ declare class Container {
     }): Session;
     /** The container-wide session used by `shell()` shorthand helpers. */
     get shell(): Session;
+    /**
+     * The streams one call collects into.
+     *
+     * They are detachable because a background job started by the command keeps
+     * writing after the call has returned. Nothing reads the result any more by
+     * then, so without `detach` a chatty server would grow the buffer for as long
+     * as it ran; afterwards its output still reaches the container-wide taps.
+     */
     private makeStdio;
     /** Send an HTTP request to a server running inside the container. */
     request(port: number, init?: {
@@ -1620,4 +1713,4 @@ declare class Container {
 /** Boot a container. The one function most callers need. */
 declare function createContainer(opts?: ContainerOptions): Promise<Container>;
 
-export { type SessionResult as $, type ProcessKind as A, BufferSink as B, Container as C, type ProcessOptions as D, type ExecContext as E, type FileData as F, type GroupEntry as G, type HttpResponse as H, type InputStream as I, type Job as J, Kernel as K, type ListeningPort as L, MANIFEST_FORMAT as M, type Node as N, type OutputStream as O, PYTHON_VERSION as P, type ProcessState as Q, ProcessTable as R, Shell as S, type PythonCapabilities as T, type PythonOptions as U, type PythonProfile as V, type PythonRuntimeManifest as W, type ResolvedExecutable as X, type RunOptions as Y, type RunResult as Z, type SessionInit as _, type ShellIO as a, type SessionRunOptions as a0, ShellExit as a1, type ShellInit as a2, type ShellOptions as a3, type SpawnHandle as a4, type Stdio as a5, TeeOutput as a6, UserDatabase as a7, Variables as a8, braceExpand as a9, captureStdio as aa, configureCPython as ab, configurePython as ac, createContext as ad, defineCommand as ae, expandWord as af, expandWords as ag, isCPythonAvailable as ah, isPythonAvailable as ai, resetPidCounter as aj, shellQuote as ak, validateManifest as al, Session as b, type Command as c, createContainer as d, type CPythonOptions as e, CallbackSink as f, CommandRegistry as g, ContainerFs as h, type ContainerOptions as i, type ContextInit as j, type Env as k, type ExecOptions as l, type ExecResult as m, FileInput as n, FileOutput as o, type KernelOptions as p, MANIFEST_SCHEMA_VERSION as q, type MountEntry as r, type NetInterface as s, type NetworkOptions as t, NetworkStack as u, NullInput as v, NullOutput as w, type PasswdEntry as x, Pipe as y, Process as z };
+export { type PythonCapabilities as $, NetworkStack as A, type BinaryBackend as B, Container as C, NullInput as D, type ExecContext as E, type FileData as F, type GroupEntry as G, type HttpResponse as H, type InputStream as I, type Job as J, Kernel as K, type ListeningPort as L, MANIFEST_FORMAT as M, type Node as N, type OutputStream as O, NullOutput as P, PYTHON_VERSION as Q, type PasswdEntry as R, Shell as S, Pipe as T, type Preparation as U, type PreparedBinary as V, Process as W, type ProcessKind as X, type ProcessOptions as Y, type ProcessState as Z, ProcessTable as _, type ShellIO as a, type PythonOptions as a0, type PythonProfile as a1, type PythonRuntimeManifest as a2, type ResolvedExecutable as a3, type RunOptions as a4, type RunResult as a5, type SessionInit as a6, type SessionResult as a7, type SessionRunOptions as a8, ShellExit as a9, shellQuote as aA, validateManifest as aB, type ShellInit as aa, type ShellOptions as ab, type SpawnHandle as ac, type Stdio as ad, TeeOutput as ae, UserDatabase as af, Variables as ag, type WasmCommandArtifact as ah, type WasmTranslator as ai, binaryDigest as aj, braceExpand as ak, captureStdio as al, configureCPython as am, configurePython as an, createContext as ao, createTranslationBackend as ap, createWasmCompatibilityBackend as aq, defineCommand as ar, expandWord as as, expandWords as at, inspectElf as au, installWasmCommands as av, isCPythonAvailable as aw, isElfBinary as ax, isPythonAvailable as ay, resetPidCounter as az, Session as b, type Command as c, createContainer as d, BinaryExecutionRegistry as e, type BinaryInfo as f, type BinaryRequest as g, BufferSink as h, type CPythonOptions as i, CallbackSink as j, CommandRegistry as k, ContainerFs as l, type ContainerOptions as m, type ContextInit as n, type Env as o, type ExecOptions as p, type ExecResult as q, type ExecutionDecision as r, type ExecutionTier as s, FileInput as t, FileOutput as u, type KernelOptions as v, MANIFEST_SCHEMA_VERSION as w, type MountEntry as x, type NetInterface as y, type NetworkOptions as z };

package/dist/{contracts-CVgctitO.d.cts → contracts-C2_dTgk3.d.cts}

@@ -347,6 +347,27 @@ declare class VirtualTcpNetwork {
     closeAll(): void;
 }
 
+/**
+ * The outbound network policy, as plain functions every client consults.
+ *
+ * The container has several ways out — `curl` and `wget` in the shell, `http`,
+ * `https`, `fetch` and `WebSocket` in a Node program, sockets in Python — and
+ * they used to decide separately. Only the shell asked: a Node program's
+ * `fetch("https://…")` reached the internet from a container booted with
+ * outbound access off. One policy, applied at each exit, is what makes
+ * `network: { allowOutbound: false }` mean what it says.
+ *
+ * Loopback is not "outbound" at all. `127.0.0.1` inside the container is the
+ * container, so those requests are routed to its own servers and never handed
+ * to the host's network stack, whatever the policy allows.
+ */
+interface OutboundPolicy {
+    /** Whether requests may leave the container at all. */
+    allowOutbound: boolean;
+    /** When outbound is on, the hosts it may reach (subdomains included). `null` means any. */
+    allowedHosts: string[] | null;
+}
+
 /**
  * Clean-room contracts between SandboxedJS and its JavaScript runtime.
  *
@@ -479,9 +500,17 @@ interface RuntimePod {
         headers: Record<string, string>;
         body: Uint8Array;
     }) => Promise<RuntimeHttpResponse>): () => void;
+    /**
+     * Apply the container's outbound policy to programs this pod runs.
+     *
+     * Optional so a pod written elsewhere still satisfies the contract, but a pod
+     * without it cannot keep a program's own `fetch` inside the policy — only
+     * the shell's `curl` would honour it.
+     */
+    setNetworkPolicy?(policy: OutboundPolicy): void;
     snapshot(options?: Record<string, unknown>): unknown;
     restore(snapshot: unknown, options?: Record<string, unknown>): Promise<void>;
     teardown(): void;
 }
 
-export { type Cred as C, type DirEntry as D, type RuntimeVolume as R, type SpawnChild as S, Vfs as V, type WriteOptions as W, VirtualTcpNetwork as a, type RuntimeHttpResponse as b, type SyncSpawn as c, type VolumeStat as d, type VolumeStats as e, type RuntimePod as f, type RuntimePackageInstaller as g, type ChildSpawnConfig as h, type ChildHandle as i, type RuntimeProcess as j, type RuntimeSocketPeer as k, type RuntimeConnection as l, ROOT_CRED as m, type RuntimeProcessManager as n, type RuntimeProcessResult as o, Stats as p, type VirtualNode as q, type VirtualProvider as r, applyChmod as s, createChildProcessModule as t, formatMode as u, makeCred as v, octalMode as w, parseUmask as x };
+export { type Cred as C, type DirEntry as D, type OutboundPolicy as O, type RuntimeVolume as R, type SpawnChild as S, Vfs as V, type WriteOptions as W, VirtualTcpNetwork as a, type RuntimeHttpResponse as b, type SyncSpawn as c, type VolumeStat as d, type VolumeStats as e, type RuntimePod as f, type RuntimePackageInstaller as g, type ChildSpawnConfig as h, type ChildHandle as i, type RuntimeProcess as j, type RuntimeSocketPeer as k, type RuntimeConnection as l, ROOT_CRED as m, type RuntimeProcessManager as n, type RuntimeProcessResult as o, Stats as p, type VirtualNode as q, type VirtualProvider as r, applyChmod as s, createChildProcessModule as t, formatMode as u, makeCred as v, octalMode as w, parseUmask as x };

package/dist/{contracts-CVgctitO.d.ts → contracts-C2_dTgk3.d.ts}

@@ -347,6 +347,27 @@ declare class VirtualTcpNetwork {
     closeAll(): void;
 }
 
+/**
+ * The outbound network policy, as plain functions every client consults.
+ *
+ * The container has several ways out — `curl` and `wget` in the shell, `http`,
+ * `https`, `fetch` and `WebSocket` in a Node program, sockets in Python — and
+ * they used to decide separately. Only the shell asked: a Node program's
+ * `fetch("https://…")` reached the internet from a container booted with
+ * outbound access off. One policy, applied at each exit, is what makes
+ * `network: { allowOutbound: false }` mean what it says.
+ *
+ * Loopback is not "outbound" at all. `127.0.0.1` inside the container is the
+ * container, so those requests are routed to its own servers and never handed
+ * to the host's network stack, whatever the policy allows.
+ */
+interface OutboundPolicy {
+    /** Whether requests may leave the container at all. */
+    allowOutbound: boolean;
+    /** When outbound is on, the hosts it may reach (subdomains included). `null` means any. */
+    allowedHosts: string[] | null;
+}
+
 /**
  * Clean-room contracts between SandboxedJS and its JavaScript runtime.
  *
@@ -479,9 +500,17 @@ interface RuntimePod {
         headers: Record<string, string>;
         body: Uint8Array;
     }) => Promise<RuntimeHttpResponse>): () => void;
+    /**
+     * Apply the container's outbound policy to programs this pod runs.
+     *
+     * Optional so a pod written elsewhere still satisfies the contract, but a pod
+     * without it cannot keep a program's own `fetch` inside the policy — only
+     * the shell's `curl` would honour it.
+     */
+    setNetworkPolicy?(policy: OutboundPolicy): void;
     snapshot(options?: Record<string, unknown>): unknown;
     restore(snapshot: unknown, options?: Record<string, unknown>): Promise<void>;
     teardown(): void;
 }
 
-export { type Cred as C, type DirEntry as D, type RuntimeVolume as R, type SpawnChild as S, Vfs as V, type WriteOptions as W, VirtualTcpNetwork as a, type RuntimeHttpResponse as b, type SyncSpawn as c, type VolumeStat as d, type VolumeStats as e, type RuntimePod as f, type RuntimePackageInstaller as g, type ChildSpawnConfig as h, type ChildHandle as i, type RuntimeProcess as j, type RuntimeSocketPeer as k, type RuntimeConnection as l, ROOT_CRED as m, type RuntimeProcessManager as n, type RuntimeProcessResult as o, Stats as p, type VirtualNode as q, type VirtualProvider as r, applyChmod as s, createChildProcessModule as t, formatMode as u, makeCred as v, octalMode as w, parseUmask as x };
+export { type Cred as C, type DirEntry as D, type OutboundPolicy as O, type RuntimeVolume as R, type SpawnChild as S, Vfs as V, type WriteOptions as W, VirtualTcpNetwork as a, type RuntimeHttpResponse as b, type SyncSpawn as c, type VolumeStat as d, type VolumeStats as e, type RuntimePod as f, type RuntimePackageInstaller as g, type ChildSpawnConfig as h, type ChildHandle as i, type RuntimeProcess as j, type RuntimeSocketPeer as k, type RuntimeConnection as l, ROOT_CRED as m, type RuntimeProcessManager as n, type RuntimeProcessResult as o, Stats as p, type VirtualNode as q, type VirtualProvider as r, applyChmod as s, createChildProcessModule as t, formatMode as u, makeCred as v, octalMode as w, parseUmask as x };