@johnhenry/andbox 0.1.2 → 0.1.3

package/README.md

@@ -22,6 +22,7 @@ Zero dependencies. Uses only Web Workers and standard browser APIs.
 - [Node](#node)
 - [`mode: 'wasm'`](#mode-wasm)
 - [`mode: 'iframe'`](#mode-iframe)
+- [Mediated network: `network`](#mediated-network-network)
 - [API](#api)
 - [Execution model](#execution-model)
 - [Security model](#security-model)
@@ -275,7 +276,7 @@ pane.iframe.style.height = '300px'; // the live element; size it like any other
 
 **Differences from worker mode.**
 
-- **The code has a full browser window.** `window`, `document`, `fetch`, timers and `requestAnimationFrame` are the frame's own; nothing is deleted or shadowed (the worker-mode lockdown does not apply, the origin boundary does). `document.body.append(...)` renders where you mounted the frame.
+- **The code has a full browser window.** `window`, `document`, `fetch`, timers and `requestAnimationFrame` are the frame's own; nothing is deleted or shadowed (the worker-mode lockdown does not apply, the origin boundary does). `document.body.append(...)` renders where you mounted the frame. With [`network`](#mediated-network-network), `fetch` is replaced by the host-backed one.
 - **`sandbox.iframe` is the live element, and it changes.** A timeout, an abort, or the frame navigating/reloading itself replaces it with a new element in the same place, with the same attributes (`class`, `style`, `width`, ...); everything the old document held is gone. `onFrame(iframe)` is called for every new frame before it is attached, so set things up there if you need them on every frame, or insert the frame yourself there. `sandbox.iframe` is `null` after `dispose()`.
 - **Do not move the element in the DOM.** Re-parenting an iframe reloads its document. andbox notices (the pending call rejects with `Sandbox iframe unloaded ...`) and the next call gets a fresh frame, but state is lost. Pass `container` (or place it in `onFrame`) instead.
 - **Remote modules are cross-origin requests.** The frame's origin is `null`, so a module URL must be served with `Access-Control-Allow-Origin` (CDNs such as esm.sh do). A relative `sandboxImport('./x.js')` resolves against `baseURL` (default: your page URL) and needs the same header.
@@ -291,6 +292,46 @@ pane.iframe.style.height = '300px'; // the live element; size it like any other
 
 Use `mode: 'wasm'` (fuel and deadline inside the engine) or `worker` mode for code that may spin, and `iframe` mode for code that needs the DOM. `examples/09-iframe-browser/` is a working two-pane notebook demo; `test/browser/iframe-mode.spec.mjs` runs the contract in Chromium, Firefox and WebKit.
 
+## Mediated network: `network`
+
+Worker mode removes `fetch` from the sandbox. Code you hand a capability to can call `host.call(...)`, but a library imported into the sandbox (`d3.json()`, `ky`, an API client) calls the **global** `fetch` and fails. The `network` option (0.1.3, [andbox#39](https://github.com/johnhenry/andbox/issues/39)) installs a global `fetch` in the sandbox that sends every request to a function on the host, which decides what happens:
+
+```js
+import { createSandbox } from '@johnhenry/andbox';
+
+const sandbox = await createSandbox({
+  network: {
+    // Runs on the host for every request the sandbox makes. Same signature as fetch.
+    async fetch(url, init) {
+      console.log(init.method, url);              // you see every request
+      return fetch(url, { ...init, referrerPolicy: 'no-referrer' }); // init.credentials is 'omit'
+    },
+    // allowedHosts: ['api.example.com'],         // optional: createNetworkFetch() allowlist in front of it
+  },
+  policy: { capabilities: { fetch: { maxCalls: 100 } } }, // the usual gate applies
+});
+
+await sandbox.defineModule('lib', `export const getJSON = async (u) => (await fetch(u)).json();`);
+await sandbox.evaluate(`
+  const { getJSON } = await sandboxImport('lib'); // knows nothing about andbox
+  return getJSON('https://api.example.com/items');
+`);
+```
+
+**Inside the sandbox**, `fetch(input, init)` resolves relative URLs against `baseURL`, refuses anything that is not `http:`/`https:` with a `TypeError`, lets the platform normalise the method, headers and body (strings, typed arrays, `Blob`, `FormData`, `URLSearchParams`, a `Request`), and sends only the URL, method, header pairs, body and `redirect` mode to the host. `credentials`, `mode`, `cache`, `referrer` and the other `RequestInit` fields are dropped. It resolves with a real `Response` (`status`, `statusText`, `headers`, `url`, `redirected`, `json()`/`text()`/`arrayBuffer()`/`body`). A host error rejects with `TypeError('fetch failed: ...')`, and `init.signal` rejects the call with `AbortError`. Everything else on the lockdown list (`XMLHttpRequest`, `WebSocket`, `EventSource`, `WebTransport`, `importScripts`, ...) stays removed.
+
+**On the host**, the request becomes an ordinary capability named `fetch`, so it goes through the capability gate and `policy` like any other (`policy.capabilities.fetch` limits it; `stats().gate.perCapability.fetch` counts it; binary bodies travel as base64, so `maxArgBytes` counts them). The host side treats it as untrusted input, because evaluated code can also call `host.call('fetch', url, init)` directly: it checks the URL again (http(s) only), validates the method, header pairs, body and `redirect`, and then calls your function as `fetch(url, init)` with `init.headers` a `Headers`, `init.body` a string or `Uint8Array`, `init.credentials` set by the host, and `init.signal` aborted when the sandbox is terminated (it is called without a `this`, so `network: { fetch }` with the platform's own `fetch` works). Return a `Response`, or a plain `{ status, statusText, headers, body, url, redirected }` (`body` a string, `ArrayBuffer`, typed array or `Blob`). `Set-Cookie` is never passed to the sandbox, and opaque or error responses (`status` outside 200-599) reject.
+
+| `network` field | Type | Default | Description |
+|---|---|---|---|
+| `fetch` | `(url, init) => Response \| { status, headers, body, ... }` | -- | Host function for every sandbox request. Required unless `allowedHosts` is given. |
+| `allowedHosts` | `string[]` | -- | Put [`createNetworkFetch(allowedHosts, fetch)`](#createnetworkfetchallowedhosts-fetchfn) in front: other hosts and any redirect are refused. Without `fetch` it wraps the host's own `fetch`. Must not be empty. |
+| `credentials` | `'omit' \| 'same-origin' \| 'include'` | `'omit'` | What the host passes as `init.credentials`. The sandbox cannot change it. |
+
+**Modes.** `worker` and `node-worker`: the shim is the only `fetch` the code can reach by name. `iframe`: it replaces the frame's own `fetch`, but the frame still has its other network APIs (`XMLHttpRequest`, `WebSocket`, `<img>`, `import()`); add `csp: "connect-src 'none'"` (and `default-src` as needed) to leave the host function as the only way to fetch, since the shim talks to the host over a `MessagePort` that CSP does not affect. `wasm`, `inline`, `data-uri` and `service-worker` throw if `network` is given (in `wasm`, expose a capability and use `host.call()`). Passing both `network` and a capability named `fetch` throws.
+
+**Limits.** The response body is buffered on the host and copied into the sandbox (no streaming; enforce size limits in your function, for example from `content-length` and `arrayBuffer().byteLength`). Aborting the sandbox-side `signal` rejects the call immediately but does not cancel the host request; terminating the sandbox does (`init.signal`). The rebuilt `Response` has `type: 'default'`. What this does and does not narrow is in the [Security model](#security-model).
+
 ## API
 
 ### `createSandbox(options?)`
@@ -319,6 +360,7 @@ Creates a new sandboxed runtime. Returns a promise (Worker, wasm and iframe mode
 | `iframeSandbox` | `string[]` | `[]` | `mode: 'iframe'`: extra sandbox tokens (`allow-scripts` is always set); `'allow-same-origin'` throws unless `dangerouslyAllowSameOrigin` |
 | `dangerouslyAllowSameOrigin` | `boolean` | `false` | `mode: 'iframe'`: permit `'allow-same-origin'`, which removes the origin boundary |
 | `onFrame` | `(iframe) => void` | -- | `mode: 'iframe'`: called with every new frame (first and after each restart) before it is attached |
+| `network` | `{ fetch?, allowedHosts?, credentials? }` | unset | `worker`, `node-worker`, `iframe`: install a global `fetch` in the sandbox that sends every request through the host function (the gated `fetch` capability). **Unset: no `fetch` in worker modes** (unchanged). See [Mediated network](#mediated-network-network). |
 
 **Returns (Worker mode):** `Promise<{ evaluate, defineModule, dispose, stats, isDisposed }>`. `mode: 'iframe'` adds `iframe`, the live `HTMLIFrameElement` (`null` after `dispose()`, replaced after a restart; see [`mode: 'iframe'`](#mode-iframe)).
 
@@ -397,7 +439,7 @@ registry.dispose();                                  // revokes blob URLs / drop
 
 ### `createNetworkFetch(allowedHosts?, fetchFn?)`
 
-Creates a fetch function that checks the request hostname against an allowlist before calling through. Useful for keeping cooperative code pointed at the hosts you intend -- **not redirect-safe** (see [Security model](#security-model)): an allowlisted host that responds with a redirect is followed without re-checking the final URL.
+Creates a fetch function that checks the request hostname against an allowlist before calling through. Requests are made with `redirect: 'manual'` and any redirect response is rejected, so an allowlisted host cannot send the caller elsewhere (see [Security model](#security-model)). It is what `network: { allowedHosts }` puts in front of the sandbox's `fetch`.
 
 ```js
 import { createNetworkFetch } from '@johnhenry/andbox';
@@ -415,9 +457,9 @@ Creates an async iterable stream for console output capture.
 
 Promise and error utilities used internally, also available for consumers.
 
-### `makeWorkerSource()`
+### `makeWorkerSource(options?)`
 
-Returns the Worker script source code as a string (useful for custom Worker setups).
+Returns the Worker script source code as a string (useful for custom Worker setups). `makeWorkerSource({ networkFetch: true })` is the variant `network` uses: `fetch` is the host-backed shim, which calls the host's `fetch` capability (your host must answer `capabilityCall` messages for it, as `createSandbox()` does).
 
 ### `createSandbox({ mode: 'service-worker', ... })`
 
@@ -497,8 +539,9 @@ andbox is **not** a boundary against code that is actively trying to escape it.
 
 **What is still yours:**
 
-- **Worker-global APIs: partly removed, not contained.** Since 0.1.0 the worker prelude deletes `fetch`, `WebSocket`, `WebSocketStream`, `WebTransport`, `EventSource`, `XMLHttpRequest`, `Worker`, `SharedWorker`, `importScripts`, `indexedDB`, `caches`, `BroadcastChannel`, `postMessage` and `self` from the global scope before any evaluated code runs (after the runtime has captured what it needs), shadows those names for evaluated code, and gives evaluated code a throwaway `this`. A script no longer gets them by name, through `globalThis`, indirect `eval` or `Function`. **This is hardening, not a boundary, and a Worker is not a security boundary.** Still reachable: the platform `import()` operator (syntax, it cannot be deleted or shadowed: it can fetch and execute remote code and is an exfiltration channel; `allowedImportHosts` only governs `sandboxImport()`), timing and `SharedArrayBuffer`/`Atomics` side channels, anything the engine or platform adds later that is not on the list above (a deny-list can only ever be incomplete), and under Node `process`, `require` and the rest of the Node API (use `nodeWorker.permissions`, and see [Node](#node)). Everything shares the Worker's realm and heap, so any prototype or intrinsic the code mutates is shared with the runtime. A different isolation primitive is required for hostile code: [`mode: 'wasm'`](#mode-wasm) (QuickJS in WebAssembly, no ambient authority) or a cross-origin iframe with a strict CSP. See [andbox#10](https://github.com/johnhenry/andbox/issues/10).
+- **Worker-global APIs: partly removed, not contained.** Since 0.1.0 the worker prelude deletes `fetch`, `WebSocket`, `WebSocketStream`, `WebTransport`, `EventSource`, `XMLHttpRequest`, `Worker`, `SharedWorker`, `importScripts`, `indexedDB`, `caches`, `BroadcastChannel`, `postMessage` and `self` from the global scope before any evaluated code runs (after the runtime has captured what it needs; with `network` set, `fetch` is replaced by the host-backed shim instead), shadows those names for evaluated code, and gives evaluated code a throwaway `this`. A script no longer gets them by name, through `globalThis`, indirect `eval` or `Function`. **This is hardening, not a boundary, and a Worker is not a security boundary.** Still reachable: the platform `import()` operator (syntax, it cannot be deleted or shadowed: it can fetch and execute remote code and is an exfiltration channel; `allowedImportHosts` only governs `sandboxImport()`), timing and `SharedArrayBuffer`/`Atomics` side channels, anything the engine or platform adds later that is not on the list above (a deny-list can only ever be incomplete), and under Node `process`, `require` and the rest of the Node API (use `nodeWorker.permissions`, and see [Node](#node)). Everything shares the Worker's realm and heap, so any prototype or intrinsic the code mutates is shared with the runtime. A different isolation primitive is required for hostile code: [`mode: 'wasm'`](#mode-wasm) (QuickJS in WebAssembly, no ambient authority) or a cross-origin iframe with a strict CSP. See [andbox#10](https://github.com/johnhenry/andbox/issues/10).
 - **`sandboxImport()` remote imports: allowed unless `allowedImportHosts` is provided, and only `sandboxImport()` is governed.** With `allowedImportHosts` unset, absolute and protocol-relative `http(s)` specifiers load from any host (0.1.0 denied them by default; 0.1.1 reverted that). Pass `allowedImportHosts: [...]` to restrict to those hostnames plus `baseURL`'s own host (refused with `Import denied: <host> is not in allowedImportHosts`), or `allowedImportHosts: []` to deny all remote imports. Import-map targets and virtual modules are host-authored and unaffected. The check cannot see inside a module once loaded (its own static `import`s) and cannot stop the platform `import()` operator (see the previous item). `mode: 'wasm'` never fetches URLs at all. See [andbox#7](https://github.com/johnhenry/andbox/issues/7).
+- **`network` narrows `fetch` to what your host function allows; it does not close the other routes out.** With `network` set, the sandbox's global `fetch` is a shim: each request goes to your function through the gated `fetch` capability, http(s) only, with `credentials` (default `'omit'`) chosen by the host and `Set-Cookie` withheld. That is a policy point for well-behaved code and the libraries it imports, not a wall: in worker mode the platform `import()` operator can still fetch (and run) arbitrary URLs and carry data out in them, as can `sandboxImport()` unless `allowedImportHosts` restricts it; in iframe mode the frame's own `XMLHttpRequest`, `WebSocket`, `<img>`, `<form>` and `import()` remain unless `csp` blocks them. Your function is what talks to the network on the sandbox's behalf with the host's network position (a server-side host can reach your internal network): validate URLs there, or use `allowedHosts`, and do not forward the sandbox's headers to hosts that trust them blindly. See [Mediated network](#mediated-network-network) and [andbox#39](https://github.com/johnhenry/andbox/issues/39).
 - **A timeout cannot undo in-flight host-side effects; it can ask them to stop.** When the Worker is terminated (timeout, an aborted `evaluate()`, `dispose()`, a crash) every capability call still in flight sees `this.signal` abort, and its late result is dropped rather than delivered. Cancellation is cooperative: a capability that ignores `this.signal` still runs to completion on the host. Write effectful capabilities as `function`s (not arrows) and pass the signal on (`fetch(url, { signal: this.signal })`), and keep them idempotent. In `mode: 'wasm'`, a cooperative `deadlineMs` ends the evaluation without terminating the Worker, so the signal does not abort in that case. See [andbox#8](https://github.com/johnhenry/andbox/issues/8).
 - **`mode: 'iframe'`: the origin boundary is the whole guarantee.** Still yours:
   - **Network.** The frame has `fetch`, `WebSocket`, `import()`, `<img>`, `<form>` and so on, as a `null`-origin client: it can exfiltrate anything it was given or computed, and reach any server that answers cross-origin requests. Pass a `csp` (`default-src 'none'` plus what the code needs) to restrict it.
@@ -519,7 +562,7 @@ What each mode is built to stop, and what it is not. "Hostile" means code active
 | | `worker` / `node-worker` | `wasm` | `iframe` |
 |---|---|---|---|
 | **Runs in** | The Worker's own JS engine (`new Function`) | QuickJS-ng compiled to WebAssembly, inside the Worker / worker thread | The browser's JS engine, in a sandboxed opaque-origin frame (`new Function` in the frame's realm) |
-| **Reaching `fetch`, `WebSocket`, `importScripts`, `indexedDB`, `postMessage`** | Removed from the global scope by the prelude (0.1.0), so not reachable by name or via `globalThis`/`eval`/`Function`. Deny-list hardening only: `import()`, timing channels and (Node) `process`/`require` remain. | Not possible. The engine has no such globals, and `constructor`/`eval`/`Function` chains only reach the guest realm. | Available, as the frame's own (`null`-origin) APIs; restrict the network with `csp`. Your page, cookies and storage are not reachable (`SecurityError`). |
+| **Reaching `fetch`, `WebSocket`, `importScripts`, `indexedDB`, `postMessage`** | Removed from the global scope by the prelude (0.1.0), so not reachable by name or via `globalThis`/`eval`/`Function`; with `network`, `fetch` is a shim that goes through your host function. Deny-list hardening only: `import()`, timing channels and (Node) `process`/`require` remain. | Not possible. The engine has no such globals, and `constructor`/`eval`/`Function` chains only reach the guest realm. | Available, as the frame's own (`null`-origin) APIs (with `network`, `fetch` is the host-backed shim); restrict the network with `csp`. Your page, cookies and storage are not reachable (`SecurityError`). |
 | **Forging protocol messages to the host** | `postMessage`/`self` are removed; ids are random UUIDs and each `result` must echo a per-evaluate nonce. | Not possible. The guest has no `postMessage` or `self`. | Only over its own `MessagePort`, with the same random ids and nonce; the host accepts nothing else from the frame. |
 | **`sandboxImport` of arbitrary URLs / Node builtins** | Remote `http(s)` URLs allowed unless `allowedImportHosts` is provided (then only listed hosts; `[]` denies all); the raw `import()` operator is still unrestricted (browser), and Node builtins are blocked only with `nodeWorker.permissions` (Node). | Refused: only virtual modules resolve; no URL is fetched. | As worker mode (`allowedImportHosts` governs `sandboxImport()` only); requests are cross-origin from `null`. `csp` can restrict `import()` too. |
 | **Prototype-chain names via `host.call`** | Closed by the capability gate (`Object.create(null)`). | Same gate, plus the guest never sees host objects. | Same gate; separate realm, so no shared intrinsics. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/andbox",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "Sandboxed JavaScript runtime with Worker isolation, RPC, import maps, timeouts, and an optional QuickJS-in-WebAssembly mode",
   "main": "./src/index.mjs",

package/src/iframe-host.mjs

@@ -27,9 +27,13 @@ const OFFSCREEN_STYLE =
 /** Attributes andbox owns on the frame; never copied onto a replacement frame. */
 const OWNED_ATTRIBUTES = new Set(['srcdoc', 'src', 'sandbox']);
 
-/** The runtime script the frame runs: Worker mode's, minus the global lockdown. */
-export function makeIframeRuntimeSource() {
-  return makeRuntimeSource({ lockdown: false });
+/**
+ * The runtime script the frame runs: Worker mode's, minus the global lockdown.
+ * @param {{ networkFetch?: boolean }} [options]  `networkFetch`: replace the
+ *   frame's `fetch` with the host-backed one (`createSandbox({ network })`).
+ */
+export function makeIframeRuntimeSource({ networkFetch = false } = {}) {
+  return makeRuntimeSource({ lockdown: false, networkFetch });
 }
 
 /**

package/src/index.d.ts

@@ -216,6 +216,62 @@ export declare function createNetworkFetch(
   fetchFn?: typeof globalThis.fetch,
 ): (url: string, init?: RequestInit) => Promise<Response>;
 
+// ── network (createSandbox({ network }), andbox#39) ──
+
+/**
+ * What the host function in `network.fetch` receives as `init`. Built by
+ * andbox from the sandbox's request after validation; `credentials` and
+ * `signal` are always the host's.
+ */
+export interface SandboxFetchInit {
+  method: string;
+  headers: Headers;
+  /**
+   * A string body as given; any other body as a `Uint8Array` (typed as
+   * `BufferSource` so `init` can be passed straight to `fetch`). Absent for
+   * GET/HEAD and empty bodies.
+   */
+  body?: string | BufferSource;
+  redirect?: RequestRedirect;
+  /** `network.credentials` (default `'omit'`); the sandbox cannot change it. */
+  credentials: RequestCredentials;
+  /** Aborts when the sandbox's Worker/frame is terminated (timeout, abort, dispose). */
+  signal?: AbortSignal;
+}
+
+/** A plain-object reply a `network.fetch` host function may return instead of a `Response`. */
+export interface SandboxFetchReply {
+  /** 200-599. Default 200. */
+  status?: number;
+  statusText?: string;
+  headers?: HeadersInit;
+  body?: string | ArrayBuffer | ArrayBufferView | Blob | null;
+  /** Default: the request URL. */
+  url?: string;
+  redirected?: boolean;
+}
+
+/** `createSandbox({ network })`: a host-backed global `fetch` inside the sandbox. */
+export interface SandboxNetworkOptions {
+  /**
+   * Called on the host for every request the sandbox's `fetch` makes, through
+   * the gated `fetch` capability (`policy.capabilities.fetch` applies). The
+   * URL is always absolute http(s). Return a `Response` or a plain reply.
+   * Called without a `this`, so the platform `fetch` itself can be passed.
+   * Required unless `allowedHosts` is given.
+   */
+  fetch?: (url: string, init: SandboxFetchInit) =>
+    Response | SandboxFetchReply | Promise<Response | SandboxFetchReply>;
+  /**
+   * Put `createNetworkFetch(allowedHosts, fetch)` in front: other hosts and
+   * any redirect are refused. Without `fetch` it wraps the host's global
+   * `fetch`. Must not be empty.
+   */
+  allowedHosts?: string[];
+  /** `init.credentials` for every request. Default `'omit'`. */
+  credentials?: RequestCredentials;
+}
+
 // ── stdio ──
 
 /** An async iterable stdio stream with push/end controls. */
@@ -243,9 +299,12 @@ export declare function createStdio(): StdioStream;
  * from the host, and sends configured, moduleDefined, result, capabilityCall,
  * and console messages back.
  *
+ * @param options.networkFetch  Install the host-backed global `fetch` shim
+ *   (what `createSandbox({ network })` uses). It calls the host's `fetch`
+ *   capability. Default false: `fetch` is removed like the other network globals.
  * @returns The complete Worker script source code as a string.
  */
-export declare function makeWorkerSource(): string;
+export declare function makeWorkerSource(options?: { networkFetch?: boolean }): string;
 
 // ── service-worker-source ──
 
@@ -412,6 +471,16 @@ export interface SandboxOptions {
    * wasm mode is unavailable.
    */
   untrusted?: boolean;
+  /**
+   * `worker`, `node-worker` and `iframe` modes (throws in `wasm`): install a
+   * global `fetch` in the sandbox that sends each request to `network.fetch`
+   * on the host, through the gated `fetch` capability (andbox#39). http(s)
+   * only; `credentials` is the host's choice. Other network globals stay
+   * locked in worker modes; the platform `import()` operator is not affected.
+   * Unset (default): worker modes have no `fetch`. Conflicts with a
+   * capability named `fetch`.
+   */
+  network?: SandboxNetworkOptions;
 }
 
 /** Options for the built-in Node worker_threads mode (`nodeWorker`). */

package/src/network-policy.mjs

@@ -46,3 +46,152 @@ export function createNetworkFetch(allowedHosts, fetchFn) {
     return response;
   };
 }
+
+// ── createSandbox({ network }) (andbox#39) ──
+
+const NETWORK_KEYS = new Set(['fetch', 'allowedHosts', 'credentials']);
+const CREDENTIALS = ['omit', 'same-origin', 'include'];
+const REDIRECTS = ['follow', 'error', 'manual'];
+const METHOD_TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+/** Response header names the sandbox never sees (a browser's fetch hides them too). */
+const HIDDEN_RESPONSE_HEADERS = new Set(['set-cookie', 'set-cookie2']);
+
+function decodeBase64(text) {
+  const binary = atob(text);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+function headerPairs(headers) {
+  const out = [];
+  for (const [name, value] of headers) {
+    if (!HIDDEN_RESPONSE_HEADERS.has(name.toLowerCase())) out.push([name, value]);
+  }
+  return out;
+}
+
+async function bodyToArrayBuffer(body) {
+  if (body == null) return null;
+  if (typeof body === 'string') return new TextEncoder().encode(body).buffer;
+  if (body instanceof ArrayBuffer) return body;
+  if (ArrayBuffer.isView(body)) return body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength);
+  if (typeof body.arrayBuffer === 'function') return body.arrayBuffer(); // Blob
+  throw new TypeError('network.fetch: a returned body must be a string, ArrayBuffer, typed array or Blob');
+}
+
+/**
+ * Turn what the host function returned (a `Response`, or a plain
+ * `{ status, statusText, headers, body, url, redirected }`) into the reply the
+ * sandbox rebuilds its `Response` from.
+ */
+async function toWireResponse(res, requestURL) {
+  if (res === null || typeof res !== 'object') {
+    throw new TypeError('network.fetch must return a Response or { status, statusText, headers, body }');
+  }
+  const isResponse = typeof res.arrayBuffer === 'function' && res.headers && typeof res.headers.get === 'function';
+  if (isResponse && (res.type === 'opaqueredirect' || res.type === 'error' || res.type === 'opaque')) {
+    throw new TypeError(`the host's fetch returned an unreadable '${res.type}' response`);
+  }
+  const status = res.status ?? 200;
+  if (!Number.isInteger(status) || status < 200 || status > 599) {
+    throw new TypeError(`the host's fetch returned status ${String(status)}; a response needs 200-599`);
+  }
+  return {
+    status,
+    statusText: typeof res.statusText === 'string' ? res.statusText : '',
+    headers: headerPairs(isResponse ? res.headers : new Headers(res.headers ?? undefined)),
+    body: isResponse ? await res.arrayBuffer() : await bodyToArrayBuffer(res.body),
+    url: typeof res.url === 'string' && res.url ? res.url : requestURL,
+    redirected: res.redirected === true,
+  };
+}
+
+/**
+ * Validate `createSandbox({ network })` and build the host-side `fetch`
+ * capability behind the sandbox's global `fetch` shim.
+ *
+ * Everything that arrives from the sandbox is treated as untrusted input
+ * (evaluated code can also call `host.call('fetch', url, init)` directly):
+ * the URL must be http(s), only method/headers/body/redirect are taken from
+ * the request, and `credentials` and `signal` are always set by the host.
+ *
+ * @param {{ fetch?: Function, allowedHosts?: string[], credentials?: RequestCredentials }} network
+ * @returns {(this: { signal?: AbortSignal }, url: unknown, init?: unknown) => Promise<object>}
+ */
+export function createFetchCapability(network) {
+  if (network === null || typeof network !== 'object' || Array.isArray(network)) {
+    throw new TypeError('network must be an object: { fetch?, allowedHosts?, credentials? }');
+  }
+  for (const key of Object.keys(network)) {
+    if (!NETWORK_KEYS.has(key)) {
+      throw new TypeError(`network.${key} is not a known option (expected fetch, allowedHosts, credentials)`);
+    }
+  }
+  const { fetch: hostFetch, allowedHosts, credentials = 'omit' } = network;
+  if (hostFetch !== undefined && typeof hostFetch !== 'function') {
+    throw new TypeError('network.fetch must be a function (url, init) => Response');
+  }
+  if (allowedHosts !== undefined) {
+    if (!Array.isArray(allowedHosts) || !allowedHosts.every((h) => typeof h === 'string' && h.length > 0)) {
+      throw new TypeError('network.allowedHosts must be an array of hostname strings');
+    }
+    if (allowedHosts.length === 0) {
+      throw new TypeError('network.allowedHosts must list at least one host; to give the sandbox no network, omit `network`');
+    }
+  }
+  if (hostFetch === undefined && allowedHosts === undefined) {
+    throw new TypeError('network needs `fetch` (a host function) and/or `allowedHosts`');
+  }
+  if (!CREDENTIALS.includes(credentials)) {
+    throw new TypeError(`network.credentials must be one of ${CREDENTIALS.map((c) => `'${c}'`).join(', ')}`);
+  }
+
+  const send = allowedHosts ? createNetworkFetch(allowedHosts, hostFetch) : hostFetch;
+
+  return async function fetchCapability(url, init) {
+    if (typeof url !== 'string') throw new TypeError('fetch: the URL must be a string');
+    let target;
+    try {
+      target = new URL(url);
+    } catch {
+      throw new TypeError(`fetch: invalid URL: ${url}`);
+    }
+    if (target.protocol !== 'http:' && target.protocol !== 'https:') {
+      throw new TypeError(`fetch: only http(s) URLs are allowed (got ${target.protocol})`);
+    }
+    const req = init === undefined || init === null ? {} : init;
+    if (typeof req !== 'object') throw new TypeError('fetch: init must be an object');
+
+    const method = req.method ?? 'GET';
+    if (typeof method !== 'string' || !METHOD_TOKEN.test(method)) throw new TypeError('fetch: invalid method');
+    const pairs = req.headers ?? [];
+    if (!Array.isArray(pairs) || !pairs.every((p) => Array.isArray(p) && p.length === 2 && p.every((v) => typeof v === 'string'))) {
+      throw new TypeError('fetch: headers must be an array of [name, value] string pairs');
+    }
+    let body;
+    if (req.body !== undefined && req.bodyBase64 !== undefined) throw new TypeError('fetch: body and bodyBase64 are exclusive');
+    if (req.body !== undefined) {
+      if (typeof req.body !== 'string') throw new TypeError('fetch: body must be a string (binary goes in bodyBase64)');
+      body = req.body;
+    } else if (req.bodyBase64 !== undefined) {
+      if (typeof req.bodyBase64 !== 'string') throw new TypeError('fetch: bodyBase64 must be a string');
+      body = decodeBase64(req.bodyBase64);
+    }
+    if (req.redirect !== undefined && !REDIRECTS.includes(req.redirect)) throw new TypeError('fetch: invalid redirect mode');
+
+    const hostInit = {
+      method,
+      headers: new Headers(pairs),
+      ...(body !== undefined ? { body } : {}),
+      ...(req.redirect !== undefined ? { redirect: req.redirect } : {}),
+      // Always the host's choice; nothing from the sandbox can change it.
+      credentials,
+      ...(this?.signal ? { signal: this.signal } : {}),
+    };
+    // Called without a `this`, so the platform's own fetch can be passed as
+    // network.fetch (it throws "Illegal invocation" on any other receiver).
+    const res = await send(target.href, hostInit);
+    return toWireResponse(res, target.href);
+  };
+}

package/src/sandbox.mjs

@@ -18,6 +18,7 @@ import { makeDeferred, makeTimeoutError, makeAbortError } from './deferred.mjs';
 import { DEFAULT_TIMEOUT_MS } from './constants.mjs';
 import { isNodeRuntime, createNodeWorkerFactory } from './node-worker.mjs';
 import { normalizeIframeOptions, createIframeFactory, makeIframeRuntimeSource } from './iframe-host.mjs';
+import { createFetchCapability } from './network-policy.mjs';
 
 const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
 
@@ -312,9 +313,12 @@ async function createServiceWorkerSandbox(options = {}) {
  * @property {string[]} [iframeSandbox] - mode: 'iframe': extra sandbox tokens ('allow-same-origin' needs dangerouslyAllowSameOrigin)
  * @property {boolean} [dangerouslyAllowSameOrigin] - mode: 'iframe': permit 'allow-same-origin' (removes the origin boundary)
  * @property {(iframe: HTMLIFrameElement) => void} [onFrame] - mode: 'iframe': called with every new frame before it is attached
+ * @property {{ fetch?: Function, allowedHosts?: string[], credentials?: RequestCredentials }} [network] - worker, node-worker and iframe modes: install a global `fetch` in the sandbox that goes through the host (andbox#39)
  */
 
 const SUPPORTED_MODES = ['worker', 'node-worker', 'wasm', 'iframe', 'inline', 'data-uri', 'service-worker'];
+/** Modes whose runtime can install the host-backed `fetch` (`network`, andbox#39). */
+const NETWORK_MODES = ['worker', 'node-worker', 'iframe'];
 
 /**
  * Create a new sandboxed runtime.
@@ -346,6 +350,13 @@ export function createSandbox(options = {}) {
       `Supported modes: ${SUPPORTED_MODES.map((m) => `'${m}'`).join(', ')}.`
     );
   }
+  if (options.network !== undefined && !NETWORK_MODES.includes(mode)) {
+    // An option that silently does nothing is worse than an error.
+    throw new Error(
+      `The network option applies to ${NETWORK_MODES.map((m) => `mode: '${m}'`).join(', ')}, not mode: '${mode}'.` +
+      (mode === 'wasm' ? " The wasm engine has no fetch; expose a capability and call it with host.call()." : '')
+    );
+  }
   if (mode === 'inline') return createInlineSandbox(options);
   if (mode === 'data-uri') return createDataUriSandbox(options);
   if (mode === 'service-worker') return createServiceWorkerSandbox(options);
@@ -437,6 +448,7 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
     nodeWorker,
     unref = false,
     allowedImportHosts,
+    network,
   } = options;
 
   // undefined = unset: remote imports allowed. An array (even empty) restricts.
@@ -489,8 +501,22 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
     wasmConfig = await resolveWasmConfig(options, baseURL, usingNode);
   }
 
+  // `network` (andbox#39): the sandbox's global fetch calls the host's `fetch`
+  // capability, which goes through the same gate and `policy` as the others.
+  let gatedCapabilities = capabilities;
+  if (network !== undefined) {
+    if (Object.prototype.hasOwnProperty.call(capabilities, 'fetch')) {
+      throw new Error(
+        "capabilities.fetch and the network option both define the 'fetch' capability; " +
+        'pass your function as network.fetch instead.'
+      );
+    }
+    gatedCapabilities = { ...capabilities, fetch: createFetchCapability(network) };
+  }
+  const networkFetch = network !== undefined;
+
   // Gate capabilities with rate limits
-  const { lookup: lookupCapability, stats: gateStats } = gateCapabilities(capabilities, policy);
+  const { lookup: lookupCapability, stats: gateStats } = gateCapabilities(gatedCapabilities, policy);
 
   // Console handler — mutable so evaluate() can swap per-call
   let activeConsoleHandler = onConsole || null;
@@ -524,7 +550,9 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
 
   function createWorker() {
     workerAbort = new AbortController();
-    const source = isWasm ? makeWasmWorkerSource() : isIframe ? makeIframeRuntimeSource() : makeWorkerSource();
+    const source = isWasm
+      ? makeWasmWorkerSource()
+      : isIframe ? makeIframeRuntimeSource({ networkFetch }) : makeWorkerSource({ networkFetch });
     if (workerFactory) {
       worker = workerFactory(source);
       attachWorkerHandlers();

package/src/worker-source.mjs

@@ -7,6 +7,117 @@
  * host capabilities.
  */
 
+/**
+ * The in-sandbox half of `createSandbox({ network })` (andbox#39): installs a
+ * global `fetch` that serializes the request, sends it to the host's `fetch`
+ * capability and rebuilds a real `Response` from the reply.
+ *
+ * Stringified into the runtime with `toString()`, so it must not reference
+ * anything outside its own body; the runtime passes in what it needs.
+ *
+ * @param {(name: string, args: unknown[]) => Promise<any>} callHost
+ * @param {() => string} getBaseURL  resolves relative URLs (the Worker's own
+ *   location is a `blob:` URL, which relative URLs cannot resolve against)
+ */
+function installNetworkFetch(callHost, getBaseURL) {
+  // Captured once, before evaluated code runs, so later changes to these
+  // globals do not change what the shim does.
+  const G = globalThis;
+  const RequestCtor = G.Request;
+  const ResponseCtor = G.Response;
+  const URLCtor = G.URL;
+  const DOMExceptionCtor = G.DOMException;
+  const toBase64 = G.btoa.bind(G);
+  const fromCharCode = String.fromCharCode;
+  const defineProperty = Object.defineProperty;
+  const NULL_BODY_STATUS = [101, 103, 204, 205, 304];
+
+  function abortReason(signal) {
+    if (signal.reason !== undefined) return signal.reason;
+    return typeof DOMExceptionCtor === 'function'
+      ? new DOMExceptionCtor('This operation was aborted', 'AbortError')
+      : Object.assign(new Error('This operation was aborted'), { name: 'AbortError' });
+  }
+
+  function bytesToBase64(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let binary = '';
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+      binary += fromCharCode.apply(null, bytes.subarray(i, i + 0x8000));
+    }
+    return toBase64(binary);
+  }
+
+  async function fetch(input, init) {
+    const options = init == null ? {} : init;
+    const isRequest = input instanceof RequestCtor;
+    const signal = options.signal != null ? options.signal : isRequest ? input.signal : null;
+    if (signal && signal.aborted) throw abortReason(signal);
+
+    const raw = isRequest ? input.url : String(input);
+    let url;
+    try {
+      url = new URLCtor(raw, getBaseURL());
+    } catch {
+      throw new TypeError(`fetch: invalid URL: ${raw}`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+      throw new TypeError(`fetch: only http(s) URLs are allowed (got ${url.protocol})`);
+    }
+
+    // Let the platform normalise method, headers and body (FormData,
+    // URLSearchParams, Blob, typed arrays, streams). Only these fields reach
+    // the host; credentials, mode, cache, referrer and the rest are the
+    // host's decision, not the sandbox's.
+    const picked = {};
+    for (const k of ['method', 'headers', 'body', 'redirect', 'duplex']) {
+      if (options[k] !== undefined) picked[k] = options[k];
+    }
+    const request = new RequestCtor(isRequest ? input : url.href, picked);
+    const wire = { method: request.method, headers: [...request.headers], redirect: request.redirect };
+    if (request.method !== 'GET' && request.method !== 'HEAD') {
+      if (typeof options.body === 'string') {
+        wire.body = options.body;
+      } else {
+        // Binary travels as base64 so the capability gate's argument-size
+        // limits (policy.capabilities.fetch.maxArgBytes) count it.
+        const buffer = await request.arrayBuffer();
+        if (buffer.byteLength > 0) wire.bodyBase64 = bytesToBase64(buffer);
+      }
+    }
+
+    const pending = callHost('fetch', [url.href, wire]);
+    let reply;
+    try {
+      reply = signal
+        ? await new Promise((resolve, reject) => {
+            const onAbort = () => reject(abortReason(signal));
+            signal.addEventListener('abort', onAbort, { once: true });
+            pending.then(
+              (v) => { signal.removeEventListener('abort', onAbort); resolve(v); },
+              (e) => { signal.removeEventListener('abort', onAbort); reject(e); },
+            );
+          })
+        : await pending;
+    } catch (e) {
+      if (signal && signal.aborted) throw e;
+      throw new TypeError(`fetch failed: ${e && e.message ? e.message : String(e)}`, { cause: e });
+    }
+
+    const response = new ResponseCtor(NULL_BODY_STATUS.includes(reply.status) ? null : reply.body, {
+      status: reply.status,
+      statusText: reply.statusText,
+      headers: reply.headers,
+    });
+    defineProperty(response, 'url', { value: reply.url, enumerable: true });
+    defineProperty(response, 'redirected', { value: reply.redirected === true, enumerable: true });
+    return response;
+  }
+
+  try { delete G.fetch; } catch {}
+  defineProperty(G, 'fetch', { value: fetch, writable: true, configurable: true, enumerable: false });
+}
+
 /**
  * Generate the Worker source code as a string.
  *
@@ -23,10 +134,14 @@
  * - `capabilityCall`: RPC request to host capability
  * - `console`: Forwarded console output
  *
+ * @param {{ networkFetch?: boolean }} [options]
+ *   `networkFetch` (default false) installs a global `fetch` that forwards
+ *   every request to the host's `fetch` capability (`createSandbox({ network })`,
+ *   andbox#39) instead of leaving `fetch` locked.
  * @returns {string} The Worker script source code.
  */
-export function makeWorkerSource() {
-  return makeRuntimeSource({ lockdown: true });
+export function makeWorkerSource({ networkFetch = false } = {}) {
+  return makeRuntimeSource({ lockdown: true, networkFetch });
 }
 
 /**
@@ -36,17 +151,21 @@ export function makeWorkerSource() {
  * `postMessage`, `close` and an `onmessage` setter: the real Worker global
  * scope, or (iframe mode) a wrapper around a MessagePort the frame was handed.
  *
- * @param {{ lockdown?: boolean }} [options]
+ * @param {{ lockdown?: boolean, networkFetch?: boolean }} [options]
  *   `lockdown` (default true) deletes and shadows the Worker's ambient
  *   network/worker globals (andbox#10). The iframe runtime turns it off: there
  *   the browser's opaque-origin boundary is the isolation, and evaluated code is
  *   meant to have its frame's `window`/`document`.
+ *   `networkFetch` (default false) replaces the global `fetch` with a shim that
+ *   sends each request to the host's `fetch` capability (andbox#39). With
+ *   `lockdown` it is the only `fetch` the code can reach; everything else on
+ *   the lockdown list stays removed.
  * @returns {string}
  */
-export function makeRuntimeSource({ lockdown = true } = {}) {
+export function makeRuntimeSource({ lockdown = true, networkFetch = false } = {}) {
   const lockedGlobals = lockdown
     ? `[
-  'fetch', 'XMLHttpRequest', 'WebSocket', 'WebSocketStream', 'WebTransport', 'EventSource',
+  ${networkFetch ? '' : "'fetch', "}'XMLHttpRequest', 'WebSocket', 'WebSocketStream', 'WebTransport', 'EventSource',
   'Worker', 'SharedWorker', 'importScripts', 'indexedDB', 'caches', 'BroadcastChannel',
   'postMessage', 'self',
 ]`
@@ -81,7 +200,11 @@ for (const k of LOCKED_GLOBALS) {
     try { Object.defineProperty(globalThis, k, { value: undefined, writable: false, configurable: false }); } catch {}
   }
 }
-// Names shadowed lexically for evaluated code as well (covers environments
+${networkFetch ? `// ── Host-backed fetch (andbox#39) ──
+// Replaces the global fetch: every request goes to the host's
+// gated \`fetch\` capability, which decides policy and credentials.
+(${installNetworkFetch.toString()})((name, args) => callCapability(name, args), () => baseURL);
+` : ''}// Names shadowed lexically for evaluated code as well (covers environments
 // where a global could not be deleted).
 const SHADOWED = ${shadowed};