@johnhenry/andbox 0.1.2 → 0.2.0

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,71 @@ 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. **No network unless you list hosts:** since 0.2.0 ([andbox#43](https://github.com/johnhenry/andbox/issues/43)) `network.allowedHosts` is required, so setting `network` never means "every host" by accident:
+
+```js
+import { createSandbox } from '@johnhenry/andbox';
+
+const sandbox = await createSandbox({
+  network: {
+    allowedHosts: ['api.example.com'],            // required: checked on the host before fetch is called
+    // Optional. Runs on the host for every allowed request. 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'
+    },
+  },
+  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`, checks the host against `allowedHosts`, 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: { allowedHosts, 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 |
+|---|---|---|---|
+| `allowedHosts` | `string[] \| (url: URL) => boolean \| '*'` | **required** | Which hosts the sandbox may reach, checked on the host before `fetch` is called (forms below). Leaving it out throws at `createSandbox()`. |
+| `fetch` | `(url, init) => Response \| { status, headers, body, ... }` | the platform's global `fetch` | Host function for every request `allowedHosts` lets through. |
+| `credentials` | `'omit' \| 'same-origin' \| 'include'` | `'omit'` | What the host passes as `init.credentials`. The sandbox cannot change it. |
+
+**`allowedHosts` takes one of three forms:**
+
+```js
+// 1. A list of hostnames: the sandbox reaches these and nothing else.
+network: { allowedHosts: ['api.example.com', 'cdn.example.com'] }
+
+// 2. A function, asked on the host for every request (and every redirect hop):
+//    for an allowlist that changes while the sandbox runs, like a notebook
+//    that asks the user per host. Only `true` (or a promise of it) allows.
+const approved = new Set(['api.example.com']);
+network: { allowedHosts: (url) => approved.has(url.hostname) }
+
+// 3. The explicit opt-in to any http(s) host. Your fetch is then the whole
+//    policy, so write it next to one that enforces its own rules.
+network: { allowedHosts: '*', fetch: myPolicyFetch }
+```
+
+- **A list** matches the request URL's hostname exactly: case-insensitive, normalised the way `URL` does it (IDN to punycode, IPv4 forms to dotted decimal), on any port and either scheme. There is no subdomain or wildcard matching: `'example.com'` does not allow `api.example.com`, and `'api.example.com'` does not allow `example.com`. Write IPv6 in brackets (`'[::1]'`). An entry with a scheme, port, path or `*` throws instead of silently never matching, and an empty list throws (to give the sandbox no network, leave `network` out). It is [`createNetworkFetch()`](#createnetworkfetchallowedhosts-fetchfn) in front of your `fetch`.
+- **A function** gets a fresh `URL` (changing it does not change the request). Anything other than `true` refuses with `Network access denied: <host> is not allowed by network.allowedHosts`; if it throws, the sandbox's `fetch` rejects with that error's message, which is a good place for "allow this host in settings". It may be `async`.
+- **`'*'`** skips the host check (the URL must still be http(s)) and leaves everything else, redirects included, to your `fetch`. Without a `fetch`, it is the platform's `fetch` for any host.
+
+**Redirects.** With a list, every request is made with `redirect: 'manual'` and any redirect response is refused, so an allowlisted host cannot send the request elsewhere. With a function, andbox follows redirects itself: each request is made with `redirect: 'manual'`, and for every `Location` it asks your function again before requesting it (at most 20 hops; 301/302 after a `POST` and 303 become a `GET` without a body, as the Fetch standard does; `Authorization` is dropped when the hop changes origin). The sandbox sees the final `url` and `redirected: true`; `redirect: 'error'` from the sandbox rejects on a redirect and `redirect: 'manual'` returns it unfollowed. A browser's own `fetch` hides a manual redirect's target (an `opaqueredirect` response), so over the page's `fetch` a function policy cannot check the next hop and the request **fails** rather than following it blindly; on Node, Deno and Bun, or with a `network.fetch` that returns the 3xx response, redirects are followed and checked. With `'*'`, your `fetch` receives the sandbox's `redirect` mode and decides; the platform `fetch` follows redirects to any host.
+
+**On a server, the host function has the server's network position.** With `node-worker` (or any server-side host), whatever `allowedHosts` lets through is fetched from inside your network: `localhost`, private addresses, and cloud metadata endpoints such as `169.254.169.254` are reachable if the policy allows them. Prefer a list; with a function or `'*'`, refuse private and link-local addresses yourself (and remember DNS can point a public name at one).
+
+**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 +385,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` | `{ allowedHosts, fetch?, 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). `allowedHosts` is required (a hostname list, a `(url) => boolean` function, or `'*'`); without it `createSandbox()` throws. **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 +464,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`. Unlike `network.allowedHosts`, a missing or empty list here still allows every host ([andbox#44](https://github.com/johnhenry/andbox/issues/44)).
 
 ```js
 import { createNetworkFetch } from '@johnhenry/andbox';
@@ -415,9 +482,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 +564,10 @@ 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`: no network unless you list hosts.** `network.allowedHosts` is required (0.2.0, [andbox#43](https://github.com/johnhenry/andbox/issues/43)): a list of hostnames, a function asked about every request and redirect hop, or the explicit `'*'`, which hands the whole decision to your `fetch`. Setting `network` without it throws, so it can no longer mean "every host your function will fetch" by omission.
+- **`network` narrows `fetch` to what `allowedHosts` and your host function allow; it does not close the other routes out.** With `network` set, the sandbox's global `fetch` is a shim: each request goes through the gated `fetch` capability, http(s) only, is checked against `allowedHosts` on the host, and reaches your function 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 and cloud metadata endpoints): prefer an `allowedHosts` list, refuse private addresses in a function or `'*'` policy, and do not forward the sandbox's headers to hosts that trust them blindly. With `'*'`, redirects are whatever your `fetch` does. 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 +588,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. |
@@ -553,15 +622,6 @@ code-based tool execution.
   is the source of truth for what that capability gate does and does not
   guarantee -- the middleware's Security model section points back here
   rather than repeating it.
-- **[`@johnhenry/prism`](https://github.com/johnhenry/prism)** -- a live
-  HTTP request inspector/proxy whose custom script-route feature runs
-  user-provided route handlers via `createSandbox({ mode: 'inline' })`.
-  Deliberately uses `inline` mode, not the default `worker` mode: the
-  handler needs a live `Request` object (with its body stream) directly in
-  scope, which can't cross a Worker's structured-clone boundary, and the
-  feature's predecessor (a package called `vimble`) never provided real
-  isolation either -- `inline`'s explicit "no isolation, code you already
-  trust" framing is the honest match, not a downgrade from what came before.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/andbox",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "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,85 @@ 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;
+}
+
+/**
+ * `network.allowedHosts` as a function: asked on the host, with a fresh `URL`,
+ * before every request the sandbox makes and before every redirect hop andbox
+ * follows. Only `true` (or a promise of `true`) allows; anything else refuses,
+ * and a thrown error is the message the sandbox's `fetch` rejects with.
+ */
+export type SandboxHostPolicy = (url: URL) => boolean | Promise<boolean>;
+
+/** `createSandbox({ network })`: a host-backed global `fetch` inside the sandbox. */
+export interface SandboxNetworkOptions {
+  /**
+   * Required (0.2.0, andbox#43): which hosts the sandbox may reach. Checked on
+   * the host before `fetch` is called, so leaving it out is an error rather
+   * than "every host".
+   *
+   * - `string[]`: hostnames, matched exactly against the request URL's
+   *   hostname (case-insensitive, IDN and IPv4 normalised like `URL`, any
+   *   port, http or https). No subdomain matching: `'example.com'` does not
+   *   allow `'api.example.com'`. IPv6 in brackets (`'[::1]'`). Entries with a
+   *   scheme, port, path or `*` throw. Must not be empty. Any redirect is
+   *   refused (the request is made with `redirect: 'manual'`).
+   * - `(url: URL) => boolean | Promise<boolean>`: a policy asked for every
+   *   request, so the allowlist can change while the sandbox runs. andbox
+   *   follows redirects itself (`redirect: 'manual'` underneath) and asks it
+   *   again for each hop; where the platform hides the target (a browser's
+   *   opaque redirect) the request fails.
+   * - `'*'`: any http(s) host. Your `fetch` is the whole policy, and the
+   *   sandbox's redirect mode is passed to it unchanged.
+   */
+  allowedHosts: readonly string[] | '*' | SandboxHostPolicy;
+  /**
+   * Called on the host for every request the sandbox's `fetch` makes that
+   * `allowedHosts` allows, 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. Default: the platform's
+   * global `fetch` (on a server, that has the server's network position).
+   */
+  fetch?: (url: string, init: SandboxFetchInit) =>
+    Response | SandboxFetchReply | Promise<Response | SandboxFetchReply>;
+  /** `init.credentials` for every request. Default `'omit'`. */
+  credentials?: RequestCredentials;
+}
+
 // ── stdio ──
 
 /** An async iterable stdio stream with push/end controls. */
@@ -243,9 +322,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 +494,17 @@ 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, and only to the hosts `network.allowedHosts` allows (required,
+   * andbox#43); `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,337 @@ 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,
+  };
+}
+
+// ── allowedHosts: required, three forms (andbox#43) ──
+
+/** The explicit opt-in for "any http(s) host; my `fetch` is the whole policy". */
+const ANY_HOST = '*';
+
+const MAX_REDIRECTS = 20;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/** Request headers that describe the body; dropped when a redirect turns the request into a GET. */
+const BODY_HEADERS = ['content-encoding', 'content-language', 'content-location', 'content-type'];
+
+const ALLOWED_HOSTS_EXAMPLE =
+  "  network: { allowedHosts: ['api.example.com'] }                     // only these hosts\n" +
+  '  network: { fetch, allowedHosts: (url) => policy.allows(url.host) } // decided per request\n' +
+  "  network: { fetch, allowedHosts: '*' }                              // any host: your fetch is the whole policy";
+
+const ENTRY_HINT =
+  "entries are hostnames without a scheme, port, path or wildcard, e.g. 'api.example.com', '127.0.0.1', '[::1]'";
+
+/**
+ * Normalise one `allowedHosts` array entry to the form `URL#hostname` has
+ * (lowercase, punycode, canonical IPv4, bracketed IPv6), so it can be
+ * compared with a request URL's hostname. Throws on anything that would
+ * silently never match (a port, a scheme, a path, a wildcard).
+ */
+function normalizeHostEntry(entry) {
+  if (typeof entry !== 'string' || entry.length === 0) {
+    throw new TypeError(`network.allowedHosts: ${ENTRY_HINT} (got ${JSON.stringify(entry)})`);
+  }
+  if (entry === ANY_HOST) {
+    throw new TypeError("network.allowedHosts: to allow any host pass the string '*' itself, not inside an array");
+  }
+  const bare = entry.startsWith('[') ? entry.replace(/^\[[^\]]*\]/, '') : entry;
+  if (/[/?#@\s*\\]/.test(entry) || bare.includes(':')) {
+    throw new TypeError(`network.allowedHosts: ${ENTRY_HINT} (got '${entry}')`);
+  }
+  let hostname;
+  try {
+    hostname = new URL(`http://${entry}/`).hostname;
+  } catch {
+    throw new TypeError(`network.allowedHosts: '${entry}' is not a valid hostname; ${ENTRY_HINT}`);
+  }
+  return hostname;
+}
+
+/**
+ * Validate `createSandbox({ network })` without building anything, so
+ * `createSandbox()` can refuse a bad option before it starts a Worker.
+ *
+ * @returns {{ hostFetch?: Function, allowedHosts: string[] | '*' | ((url: URL) => unknown), credentials: RequestCredentials }}
+ */
+export function validateNetworkOptions(network) {
+  if (network === null || typeof network !== 'object' || Array.isArray(network)) {
+    throw new TypeError('network must be an object: { allowedHosts, fetch?, credentials? }');
+  }
+  for (const key of Object.keys(network)) {
+    if (!NETWORK_KEYS.has(key)) {
+      throw new TypeError(`network.${key} is not a known option (expected allowedHosts, fetch, 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) {
+    throw new TypeError(
+      'network.allowedHosts is required: the sandbox gets no network unless you say which hosts it may reach. ' +
+      `For example:\n${ALLOWED_HOSTS_EXAMPLE}`
+    );
+  }
+  let hosts;
+  if (allowedHosts === ANY_HOST || typeof allowedHosts === 'function') {
+    hosts = allowedHosts;
+  } else if (Array.isArray(allowedHosts)) {
+    if (allowedHosts.length === 0) {
+      throw new TypeError(
+        'network.allowedHosts must list at least one host; to give the sandbox no network, omit `network`. ' +
+        `For example:\n${ALLOWED_HOSTS_EXAMPLE}`
+      );
+    }
+    hosts = [...new Set(allowedHosts.map(normalizeHostEntry))];
+  } else {
+    throw new TypeError(
+      "network.allowedHosts must be an array of hostnames, a function (url: URL) => boolean, or '*' " +
+      `(got ${typeof allowedHosts === 'string' ? `'${allowedHosts}'` : typeof allowedHosts}). For example:\n${ALLOWED_HOSTS_EXAMPLE}`
+    );
+  }
+  if (!CREDENTIALS.includes(credentials)) {
+    throw new TypeError(`network.credentials must be one of ${CREDENTIALS.map((c) => `'${c}'`).join(', ')}`);
+  }
+  return { hostFetch, allowedHosts: hosts, credentials };
+}
+
+/** The host's fetch, or the platform's, called without a `this`. */
+function resolveFetch(hostFetch) {
+  if (hostFetch) return (url, init) => hostFetch(url, init);
+  return (url, init) => {
+    const platformFetch = globalThis.fetch;
+    if (typeof platformFetch !== 'function') throw new Error('fetch is not available');
+    return platformFetch.call(globalThis, url, init);
+  };
+}
+
+async function askPolicy(policy, href) {
+  // A fresh URL each time: the policy cannot change the URL andbox requests.
+  const verdict = await policy(new URL(href));
+  if (verdict !== true) {
+    throw new Error(`Network access denied: ${new URL(href).host} is not allowed by network.allowedHosts`);
+  }
+}
+
+function responseHeaders(res) {
+  if (res?.headers && typeof res.headers.get === 'function') return res.headers;
+  try {
+    return new Headers(res?.headers ?? undefined);
+  } catch {
+    return new Headers();
+  }
+}
+
+function discardBody(res) {
+  try {
+    res?.body?.cancel?.().catch(() => {});
+  } catch {
+    // nothing to release
+  }
+}
+
+/**
+ * `allowedHosts` as a function: ask it about every URL andbox is about to
+ * request, the first one and every redirect hop. Redirects are followed by
+ * andbox itself (`redirect: 'manual'` underneath), re-asking the function for
+ * each `Location`, with the Fetch standard's method/body rewriting and
+ * `Authorization` dropped on a cross-origin hop. Where the platform hides the
+ * target (a browser's `opaqueredirect`), the request fails closed.
+ */
+function createPolicyFetch(policy, hostFetch) {
+  const send = resolveFetch(hostFetch);
+  return async function policyFetch(url, init) {
+    const { body: firstBody, headers: firstHeaders, method: firstMethod, ...rest } = init;
+    const mode = init.redirect ?? 'follow';
+    let href = url;
+    let method = firstMethod;
+    let headers = new Headers(firstHeaders);
+    let body = firstBody;
+    for (let hop = 0; ; hop++) {
+      await askPolicy(policy, href);
+      const res = await send(href, {
+        ...rest,
+        method,
+        headers,
+        ...(body !== undefined ? { body } : {}),
+        redirect: 'manual',
+      });
+      if (mode === 'manual') return res;
+      if (res?.type === 'opaqueredirect') {
+        throw new Error(
+          `Network access denied: ${new URL(href).host} answered with a redirect whose target this platform's fetch hides, ` +
+          "so network.allowedHosts cannot check it; pass a network.fetch that returns the redirect response, or use allowedHosts: '*'"
+        );
+      }
+      const location = REDIRECT_STATUSES.has(res?.status) ? responseHeaders(res).get('location') : null;
+      if (location === null) {
+        if (hop === 0) return res;
+        return { status: res.status, statusText: res.statusText, headers: responseHeaders(res), body: await readBody(res), url: href, redirected: true };
+      }
+      discardBody(res);
+      if (mode === 'error') throw new Error(`fetch: ${new URL(href).host} redirected and the request's redirect mode is 'error'`);
+      if (hop + 1 > MAX_REDIRECTS) throw new Error(`fetch: more than ${MAX_REDIRECTS} redirects`);
+      let next;
+      try {
+        next = new URL(location, href);
+      } catch {
+        throw new Error(`fetch: ${new URL(href).host} redirected to an invalid URL`);
+      }
+      if (next.protocol !== 'http:' && next.protocol !== 'https:') {
+        throw new Error(`Network access denied: ${new URL(href).host} redirected to a ${next.protocol} URL`);
+      }
+      const status = res.status;
+      if ((status === 303 && method !== 'GET' && method !== 'HEAD') || ((status === 301 || status === 302) && method === 'POST')) {
+        method = 'GET';
+        body = undefined;
+        headers = new Headers(headers);
+        for (const name of BODY_HEADERS) headers.delete(name);
+      }
+      if (next.origin !== new URL(href).origin) {
+        headers = new Headers(headers);
+        headers.delete('authorization');
+      }
+      href = next.href;
+    }
+  };
+}
+
+async function readBody(res) {
+  if (res == null) return null;
+  if (typeof res.arrayBuffer === 'function') return res.arrayBuffer();
+  return res.body ?? null;
+}
+
+/**
+ * The host-side sender for a validated `network`: the policy in front of the
+ * host's (or the platform's) fetch.
+ */
+function createNetworkSender({ hostFetch, allowedHosts }) {
+  if (allowedHosts === ANY_HOST) return resolveFetch(hostFetch);
+  if (typeof allowedHosts === 'function') return createPolicyFetch(allowedHosts, hostFetch);
+  return createNetworkFetch(allowedHosts, hostFetch);
+}
+
+/**
+ * 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) and pass `allowedHosts` before the host's `fetch`
+ * is called, only method/headers/body/redirect are taken from the request,
+ * and `credentials` and `signal` are always set by the host.
+ *
+ * @param {{ allowedHosts: string[] | '*' | ((url: URL) => boolean | Promise<boolean>), fetch?: Function, credentials?: RequestCredentials }} network
+ * @returns {(this: { signal?: AbortSignal }, url: unknown, init?: unknown) => Promise<object>}
+ */
+export function createFetchCapability(network) {
+  const options = validateNetworkOptions(network);
+  const { credentials } = options;
+  const send = createNetworkSender(options);
+
+  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, validateNetworkOptions } 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 {{ allowedHosts: string[] | '*' | ((url: URL) => boolean | Promise<boolean>), fetch?: Function, credentials?: RequestCredentials }} [network] - worker, node-worker and iframe modes: install a global `fetch` in the sandbox that goes through the host (andbox#39); `allowedHosts` is required (andbox#43)
  */
 
 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,15 @@ 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()." : '')
+    );
+  }
+  // Refuse a bad `network` (no allowedHosts, andbox#43) before starting anything.
+  if (options.network !== undefined) validateNetworkOptions(options.network);
   if (mode === 'inline') return createInlineSandbox(options);
   if (mode === 'data-uri') return createDataUriSandbox(options);
   if (mode === 'service-worker') return createServiceWorkerSandbox(options);
@@ -437,6 +450,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 +503,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 +552,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};