@johnhenry/andbox 0.1.1 → 0.1.3

package/README.md

@@ -21,6 +21,8 @@ Zero dependencies. Uses only Web Workers and standard browser APIs.
 - [Sandbox Modes](#sandbox-modes)
 - [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)
@@ -88,11 +90,12 @@ await sandbox.dispose();
 
 ## Sandbox Modes
 
-andbox supports six execution modes (any other `mode` throws an error listing these):
+andbox supports seven execution modes (any other `mode` throws an error listing these):
 
 - **`worker`** (default) -- Runs in a dedicated Worker with an RPC bridge, import maps, virtual modules, and hard-kill timeout semantics. See [Security model](#security-model) for what this does and doesn't protect against.
 - **`node-worker`** -- The `worker` mode on `node:worker_threads`. Selected automatically under Node when there is no global `Worker`; see [Node](#node).
 - **`wasm`** -- Optional. Runs the code in QuickJS-ng compiled to WebAssembly *inside* the Worker (or worker thread), with `host.call` as the only authority and real memory, stack, fuel and deadline limits. The only mode that withholds the Worker's own globals (`fetch`, `WebSocket`, `importScripts`, ...). See [`mode: 'wasm'`](#mode-wasm).
+- **`iframe`** -- Browser only. Runs the code in a sandboxed `<iframe sandbox="allow-scripts" srcdoc>`: an opaque origin with its own realm, `window` and `document`, so the code can render real DOM (charts, canvas animations, HTML) that you mount in your page. Same API as `worker`. The first mode with a browser-enforced origin boundary; see [`mode: 'iframe'`](#mode-iframe) for what that does and does not cover.
 - **`inline`** -- Same-thread execution via AsyncFunction. Lighter weight, no Worker overhead, no isolation at all -- code runs with full access to the calling context. Only for code you already trust.
 - **`data-uri`** -- Dynamic `import()` via Blob URL (a `data:` URL under Node). Module-level separation without a Worker. Supports globals injection.
 - **`service-worker`** -- Not code execution at all: registers a Service Worker that serves an in-memory `path → content` map with real HTTP-shaped fetch/navigation semantics. For hosting a small virtual multi-file site (HTML/CSS/JS, arbitrary paths), not for running JS in isolation. See [andbox#14](https://github.com/johnhenry/andbox/issues/14) and [Security model](#security-model) -- this mode does **not** provide isolation by merely existing.
@@ -242,17 +245,104 @@ Or give them through the sandbox import map, so a page that already has one need
 - A guest can catch the engine's out-of-memory error and keep running inside the cap; it cannot exceed the cap.
 - `Date`, `Math.random` and `performance` exist in the guest (QuickJS provides them from the host clock); see the threat model.
 
+## `mode: 'iframe'`
+
+`mode: 'iframe'` (0.1.2) runs evaluated code in a sandboxed `<iframe>` instead of a Worker, for code that needs a real DOM: a notebook pane that draws a chart, plays a canvas animation, or renders HTML. It is the cross-origin-iframe option [andbox#10](https://github.com/johnhenry/andbox/issues/10) named next to `mode: 'wasm'`. The frame is created from `srcdoc` with `sandbox="allow-scripts"` and **no** `allow-same-origin`, so the browser gives it an opaque origin: it cannot read your page, your cookies or your storage.
+
+```js
+import { createSandbox } from '@johnhenry/andbox';
+
+const pane = await createSandbox({
+  mode: 'iframe',
+  container: document.querySelector('#pane'),    // where the frame goes (default: offscreen in <body>)
+  html: '<style>body { margin: 0 }</style>',      // initial body markup
+  capabilities: { data: () => [3, 7, 4, 9] },
+  onConsole: (level, ...args) => console.log(`[pane:${level}]`, ...args),
+  onFrame: (iframe) => { iframe.className = 'pane-frame'; }, // every new frame, before it is attached
+});
+
+await pane.evaluate(`
+  const canvas = document.createElement('canvas');   // the frame's own document
+  document.body.append(canvas);
+  const values = await host.call('data');
+  // ... draw, animate, play(Scene, { canvas }) ...
+  return values.length;
+`);
+
+pane.iframe.style.height = '300px'; // the live element; size it like any other
+```
+
+**Same contract as worker mode.** `evaluate(code, opts)` wraps the code in an async IIFE and resolves with what it `return`s, by structured clone (`Map`, `Date`, typed arrays survive; a DOM node rejects with `DataCloneError`). `host.call(name, ...args)` goes through the same capability gate and `policy`, and capabilities get the same `this.signal`. `sandboxImport()` resolves virtual modules (`defineModule()`), the `importMap`, and remote URLs under the same `allowedImportHosts` rules. `console.*` is forwarded to `onConsole` (sandbox-level or per call). `timeoutMs`/`defaultTimeoutMs` and an `AbortSignal` hard-kill the frame (it is removed and a fresh one created) and reject with the same `TimeoutError` / `AbortError` as worker mode. `stats()`, `dispose()` and `isDisposed()` are unchanged.
+
+**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. 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.
+- **`csp`** is injected as `<meta http-equiv="Content-Security-Policy">` after andbox's bootstrap script. `evaluate()` compiles code with `new Function`, so a policy that restricts scripts must allow `'unsafe-eval'`, plus `blob:` for `defineModule()` modules and the hosts you import from. Example: `"default-src 'none'; script-src 'unsafe-eval' blob: https://esm.sh; img-src data:"` leaves the frame no network except module imports from esm.sh.
+- **`iframeSandbox: ['allow-forms', 'allow-popups', ...]`** adds sandbox tokens. `'allow-same-origin'` is refused: combined with `allow-scripts` it puts the frame in your origin, where it can reach your page and storage and delete its own `sandbox` attribute. `dangerouslyAllowSameOrigin: true` permits it for code you trust completely.
+- **Browser only.** Without a DOM (Node, a Worker) `createSandbox({ mode: 'iframe' })` rejects. `workerFactory`, `nodeWorker` and the wasm limits do not apply; `untrusted: true` still means `mode: 'wasm'`.
+- **Startup is bounded** by `defaultTimeoutMs`: a frame that never completes its handshake (for example a `container` that is not in a document) rejects `createSandbox()` and is removed.
+
+**Synchronous infinite loops depend on the browser's process model.** An `await`-based hang (a promise that never settles, a long `setInterval`) is always killed on time. A synchronous `while (true) {}` can only be killed when the browser runs the frame on another thread:
+
+- **Desktop Chrome** (site isolation on, the default; checked with Chrome 154) runs a sandboxed frame in its own renderer process. The timeout fires on time, the frame is removed, and the next call gets a new frame in milliseconds, **provided no other sandboxed frame from your site shares that process**. Chrome groups them by site, so while another andbox iframe (or any other opaque-origin frame from your site) is alive, the looping process cannot be shut down: the replacement frame lands in it and its startup times out, and those other frames stop responding too.
+- **WebKit (Safari's engine) and Chromium without full site isolation** (measured: Playwright's WebKit, and Playwright's Chromium without `--site-per-process`) run the frame on the host page's main thread. A synchronous infinite loop freezes your page, the timeout cannot fire, and the browser's own "page unresponsive" handling is the only way out. Chrome on Android, which does not isolate every site, is expected to behave the same; Firefox was not measured for this release.
+
+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?)`
 
-Creates a new sandboxed runtime. Returns a promise (Worker mode) or object (inline/data-uri mode).
+Creates a new sandboxed runtime. Returns a promise (Worker, wasm and iframe modes) or object (inline/data-uri mode).
 
 **Options:**
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `mode` | `'worker' \| 'node-worker' \| 'wasm' \| 'inline' \| 'data-uri'` | `'worker'` | Execution mode |
+| `mode` | `'worker' \| 'node-worker' \| 'wasm' \| 'iframe' \| 'inline' \| 'data-uri' \| 'service-worker'` | `'worker'` | Execution mode |
 | `importMap` | `{ imports?, scopes? }` | `{}` | Import map for package resolution (Worker mode) |
 | `capabilities` | `Record<string, Function>` | `{}` | Host functions callable via `host.call()` (Worker mode) |
 | `defaultTimeoutMs` | `number` | `30000` | Default timeout for `evaluate()` |
@@ -264,8 +354,15 @@ Creates a new sandboxed runtime. Returns a promise (Worker mode) or object (inli
 | `globals` | `Record<string, any>` | `{}` | Global variables (inline/data-uri modes) |
 | `engineURL`, `wasmURL` | `string` | -- | `mode: 'wasm'`: same-origin URLs of the bundled engine module and the `.wasm` (optional under Node) |
 | `fuel`, `memoryBytes`, `stackBytes`, `deadlineMs` | `number` | see [Limits](#limits) | `mode: 'wasm'` limits (also accepted per `evaluate()` call) |
+| `container` | `Element` | offscreen in `document.body` | `mode: 'iframe'`: element the frame is appended to. A restarted frame takes its predecessor's place instead. |
+| `html` | `string` | `''` | `mode: 'iframe'`: initial `<body>` markup of every new frame |
+| `csp` | `string` | -- | `mode: 'iframe'`: Content-Security-Policy for the frame (`<meta http-equiv>`); must allow `'unsafe-eval'` if it restricts scripts |
+| `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 }>`
+**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)).
 
 ### `sandbox.evaluate(code, opts?)`
 
@@ -289,7 +386,7 @@ Defines a virtual module that sandbox code can import via `sandboxImport(name)`.
 
 ### `sandbox.dispose()`
 
-Terminates the Worker and rejects all pending evaluations.
+Terminates the Worker (removes the frame in `mode: 'iframe'`) and rejects all pending evaluations.
 
 ### `sandbox.stats()`
 
@@ -342,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';
@@ -360,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', ... })`
 
@@ -426,6 +523,7 @@ andbox is **not** a boundary against code that is actively trying to escape it.
 **Pick the mode by how much you trust the code:**
 
 - **`worker` and `node-worker` are for trusted or semi-trusted code** (your own scripts, plugins from known authors, LLM output you review). They organise and throttle what the code does; they do not contain a determined attacker. Still reachable from code in these modes: the platform `import()` operator (fetches and runs remote code, an exfiltration channel; `allowedImportHosts` only governs `sandboxImport()`), timing and `SharedArrayBuffer`/`Atomics` side channels, the Worker's shared realm and heap, any global a future platform adds that is not on the deny-list, and under Node `process`, `require` and the rest of the Node API.
+- **`iframe` is for code that needs the DOM**, trusted or semi-trusted, that you want kept away from your page. The browser enforces an origin boundary: the frame runs in an opaque origin and a separate realm, so it cannot read your document, cookies, storage or JavaScript objects, and it reaches you only through `host.call()` and the values it returns. It does not limit what the code does with its own window: network, CPU, memory, and (with the matching `iframeSandbox` tokens) popups and forms are its own. See "still yours" below and [`mode: 'iframe'`](#mode-iframe).
 - **`wasm` is the mode for untrusted code**, and `createSandbox({ untrusted: true })` selects it (and throws or rejects instead of falling back if it is unavailable, or if combined with another `mode`). The code runs in QuickJS compiled to WebAssembly with no ambient authority: no `fetch`, `import()` of URLs, timers, `process` or `require` exist in that engine, and its only way out is `host.call()` through `capabilities`, `policy` and the gate. It has real limits (`fuel`, `memoryBytes`, `stackBytes`, `deadlineMs`) and a hard `terminate()` backstop. It does **not** guarantee: that your own capabilities are safe (whatever you grant is reachable, so keep them narrow), protection from engine or WebAssembly-runtime bugs (still shared process memory; for hostile multi-tenant workloads add OS-level isolation), that an in-flight capability is cancelled when the cooperative deadline fires ([andbox#35](https://github.com/johnhenry/andbox/issues/35)), or Node-level hardening (`nodeWorker.permissions` is not supported in this mode). See [`mode: 'wasm'`](#mode-wasm) and [andbox#10](https://github.com/johnhenry/andbox/issues/10).
 
 **What andbox guarantees:**
@@ -437,12 +535,21 @@ andbox is **not** a boundary against code that is actively trying to escape it.
 - **The capability gate cannot be walked around via the prototype chain.** `gateCapabilities()` builds the gated object with `Object.create(null)`, so `host.call('constructor', ...)` cannot resolve through `Object.prototype` to the real global `Object` constructor; the host resolves names through a `Map` and rejects anything that was not explicitly granted. First fixed in 0.0.1, hardened in 0.0.9; see [andbox#5](https://github.com/johnhenry/andbox/issues/5).
 - **`createNetworkFetch()`'s allowlist is redirect-safe.** Requests are made with `redirect: 'manual'` and any redirect response is rejected outright, so an allowlisted host cannot silently redirect a caller to a non-allowlisted one. Previously fixed; see [andbox#6](https://github.com/johnhenry/andbox/issues/6).
 - **`gateCapabilities()` enforces call/argument-size/concurrency caps per capability**, for cooperative callers that stay within the capabilities you actually granted.
+- **(`mode: 'iframe'`) An opaque origin and a separate realm, enforced by the browser.** The frame is `sandbox="allow-scripts"` without `allow-same-origin` (refused unless `dangerouslyAllowSameOrigin: true`). Its code gets `SecurityError` for `parent.document`, `top.location`, `parent.localStorage` and its own `localStorage`, has no access to your cookies, and shares no objects with your page: everything crossing the boundary is structured-cloned over a `MessagePort`. The port is handed over only after a handshake bound to that frame's own `contentWindow` and a per-frame random token (an `event.origin` of `'null'` alone proves nothing, since every opaque frame has it). Asserted by `test/browser/iframe-mode.spec.mjs`, which runs in Chromium, Firefox and WebKit.
 
 **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.
+  - **CPU and memory.** An `await`-based hang is killed on time; a synchronous loop is killable only where the browser runs the frame out of process, and in Chrome only while no other frame from your site shares that process. WebKit/Safari (and Chromium without full site isolation) run the frame on your page's thread, where a busy loop freezes your page. No memory cap. See [`mode: 'iframe'`](#mode-iframe).
+  - **Same process in some browsers.** Where the frame is not site-isolated (WebKit/Safari, Chromium without full site isolation such as Android Chrome, possibly Firefox) it shares a process and address space with your page: the origin boundary still holds for JavaScript, but a browser memory-safety bug or a Spectre-style read is not stopped by a process boundary. Timing side channels (`performance.now()`, `SharedArrayBuffer` where cross-origin isolation enables it) are available to the frame either way.
+  - **What you enable.** Every `iframeSandbox` token is a capability: `allow-popups` lets it open windows, `allow-forms` submit forms, `allow-top-navigation` navigate your page, `allow-modals` show dialogs. `dangerouslyAllowSameOrigin` removes the boundary entirely.
+  - **The UI it draws.** You chose to show the frame; it controls those pixels and can draw a convincing fake login form inside them. Keep frames visibly framed as untrusted content.
+  - **What you grant and what you accept.** Capabilities are as reachable as in any other mode, and results are values from untrusted code.
 - **`mode: 'service-worker'` does not provide isolation by merely existing.** It's a hosting mechanism -- a real Service Worker, same-origin by default, serving your `files` map with real fetch/navigation interception. Content served through it can see and touch its own origin exactly like any other same-origin page can; nothing about registering a Service Worker sandboxes what runs inside the pages it serves. If you're hosting content you don't fully trust, point this mode at a genuinely separate origin from day one -- the same recommendation the `fetch`/`WebSocket`/`Worker` item above makes for `worker` mode (a cross-origin iframe with a strict CSP), not something bolted on after the fact. See [andbox#14](https://github.com/johnhenry/andbox/issues/14).
 - **The Service Worker does not control the very first navigation into its scope.** A page/iframe navigation into `scope` that happens *before* the registration has finished activating is a normal, unintercepted network request -- Service Workers never retroactively intercept a request that already went out. `createSandbox({ mode: 'service-worker' })`'s returned promise only resolves once the registration is active (its generated script also calls `clients.claim()` on activate, which helps *already-open* clients but not fresh navigations); the documented, load-bearing contract is: don't navigate anything into `scope` until that promise resolves. Do that and every request is intercepted from the first byte, because the registration already matches `scope` before the navigation request is made. See [andbox#14](https://github.com/johnhenry/andbox/issues/14).
 
@@ -452,17 +559,17 @@ If you need to run untrusted/adversarial code, use `createSandbox({ untrusted: t
 
 What each mode is built to stop, and what it is not. "Hostile" means code actively trying to escape or abuse the host.
 
-| | `worker` / `node-worker` | `wasm` |
-|---|---|---|
-| **Runs in** | The Worker's own JS engine (`new Function`) | QuickJS-ng compiled to WebAssembly, inside the Worker / worker thread |
-| **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. |
-| **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`. |
-| **`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. |
-| **Prototype-chain names via `host.call`** | Closed by the capability gate (`Object.create(null)`). | Same gate, plus the guest never sees host objects. |
-| **Infinite loops** | `terminate()` after `timeoutMs`, then a new Worker. | Deterministic `fuel` and a wall-clock `deadlineMs` stop it without a respawn; `terminate()` remains the backstop. |
-| **Memory exhaustion** | Browser: nothing but the tab limit. Node: opt-in `nodeWorker.maxMemoryMb`. | Guest heap cap plus a hard cap on the engine's linear memory. |
-| **Deep recursion** | Engine stack limit of the host JS engine. | `stackBytes`; overflow is a catchable `RangeError`. |
-| **Capability abuse** | `gateCapabilities()` rate and size limits (cooperative callers). | Same. |
+| | `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`; 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. |
+| **Infinite loops** | `terminate()` after `timeoutMs`, then a new Worker. | Deterministic `fuel` and a wall-clock `deadlineMs` stop it without a respawn; `terminate()` remains the backstop. | Async hangs: frame removed after `timeoutMs`, then a new frame. Synchronous loops: only where the frame is out of process (desktop Chrome, with no other same-site sandboxed frame alive); elsewhere they freeze the page. |
+| **Memory exhaustion** | Browser: nothing but the tab limit. Node: opt-in `nodeWorker.maxMemoryMb`. | Guest heap cap plus a hard cap on the engine's linear memory. | Nothing but the browser's per-process/tab limit. |
+| **Deep recursion** | Engine stack limit of the host JS engine. | `stackBytes`; overflow is a catchable `RangeError`. | Engine stack limit. |
+| **Capability abuse** | `gateCapabilities()` rate and size limits (cooperative callers). | Same. | Same. |
 
 **What `wasm` mode does not defend against**
 
@@ -489,6 +596,15 @@ 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.1",
+  "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",
@@ -22,6 +22,7 @@
   ],
   "scripts": {
     "test": "node --test test/*.test.mjs",
+    "test:browser": "playwright test",
     "example:01": "node examples/01-untrusted-code-runs-isolated.mjs",
     "example:02": "node examples/02-capability-limits-cut-off-abuse.mjs",
     "example:03": "node examples/03-network-allowlist-blocks-unapproved-hosts.mjs",
@@ -30,7 +31,8 @@
     "examples": "npm run example:01 && npm run example:02 && npm run example:03 && npm run example:04 && npm run example:05 && npm run example:07",
     "example:07": "node examples/07-wasm-mode-contains-hostile-code.mjs",
     "example:08:build": "node examples/08-wasm-browser/build.mjs",
-    "example:08:headless": "node examples/08-wasm-browser/build.mjs && node examples/08-wasm-browser/run-headless.mjs"
+    "example:08:headless": "node examples/08-wasm-browser/build.mjs && node examples/08-wasm-browser/run-headless.mjs",
+    "example:09:headless": "node examples/09-iframe-browser/run-headless.mjs"
   },
   "keywords": [
     "sandbox",
@@ -53,6 +55,7 @@
   },
   "devDependencies": {
     "@jitl/quickjs-ng-wasmfile-release-sync": "0.32.0",
+    "@playwright/test": "^1.63.0",
     "esbuild": "^0.28.2",
     "quickjs-emscripten-core": "0.32.0",
     "vite": "^8.3.3",

package/src/iframe-host.mjs

@@ -0,0 +1,295 @@
+/**
+ * `mode: 'iframe'` -- the host side.
+ *
+ * Each "worker" is a `<iframe sandbox="allow-scripts" srcdoc="...">`: an
+ * opaque origin with its own realm, `window` and `document`. The srcdoc holds
+ * a small bootstrap plus the same runtime script Worker mode uses (without
+ * the Worker-global lockdown). The host talks to it over a MessageChannel
+ * whose second port is transferred to the frame after a token-checked
+ * handshake; after that nothing travels over `window.postMessage`.
+ *
+ * `createIframeFactory()` returns a `workerFactory`-compatible function whose
+ * result is Worker-shaped (`postMessage`, `onmessage`, `onerror`,
+ * `add/removeEventListener('message')`, `terminate()`, `dead`), so the rest of
+ * the sandbox (RPC, timeouts, restarts, capability abort) is shared with
+ * Worker mode unchanged.
+ */
+
+import { makeRuntimeSource } from './worker-source.mjs';
+
+/** The sandbox token andbox always sets; the frame cannot run code without it. */
+const BASE_TOKEN = 'allow-scripts';
+
+/** Inline style for the default, evaluation-only placement (no `container`). */
+const OFFSCREEN_STYLE =
+  'position:absolute;left:-10000px;top:0;width:1px;height:1px;border:0;opacity:0;pointer-events:none;';
+
+/** 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.
+ * @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 });
+}
+
+/**
+ * Make text safe to place inside an inline `<script>` element. `</script` would
+ * end the element early and `<!--` can switch the tokenizer into the
+ * "script data escaped" state; both only occur inside string literals here.
+ */
+function escapeInlineScript(text) {
+  return text.replace(/<\/(script)/gi, '<\\/$1').replace(/<!--/g, '<\\!--');
+}
+
+function escapeAttribute(text) {
+  return text.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+}
+
+/**
+ * Build the frame's `srcdoc`.
+ *
+ * Order matters: the bootstrap runs first, then the optional CSP `<meta>`
+ * (a meta policy applies to what comes after it, so the bootstrap is never
+ * blocked by it, while `eval`/`new Function`, imports, fetches and any
+ * scripts in `html` are), then the caller's `html` in `<body>`.
+ *
+ * @param {{ source: string, token: string, csp?: string, html?: string }} parts
+ * @returns {string}
+ */
+export function makeIframeDocument({ source, token, csp, html = '' }) {
+  const bootstrap = `
+(function () {
+  'use strict';
+  var TOKEN = ${JSON.stringify(token)};
+  var parentWindow = window.parent;
+  var started = false;
+  function onInit(e) {
+    if (started || e.source !== parentWindow) return;
+    var d = e.data;
+    if (!d || d.type !== 'andbox:init' || d.token !== TOKEN || !e.ports || !e.ports[0]) return;
+    started = true;
+    window.removeEventListener('message', onInit);
+    var port = e.ports[0];
+    var send = port.postMessage.bind(port);
+    // No pagehide/unload listener here on purpose: in Chromium one blocks fast
+    // shutdown of the frame's process, so a frame stuck in a busy loop would
+    // keep its (shared) process hung for seconds after the host removed it.
+    // The host detects navigation from the element's load events instead.
+    var portScope = {
+      postMessage: send,
+      close: function () { port.close(); },
+      set onmessage(fn) { port.onmessage = fn; },
+    };
+    (function (self) {
+${escapeInlineScript(source)}
+    })(portScope);
+  }
+  window.addEventListener('message', onInit);
+  function hello() { parentWindow.postMessage({ type: 'andbox:hello', token: TOKEN }, '*'); }
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', hello, { once: true });
+  else hello();
+})();
+`;
+  const cspMeta = csp ? `<meta http-equiv="Content-Security-Policy" content="${escapeAttribute(csp)}">` : '';
+  return `<!doctype html><html><head><meta charset="utf-8"><script>${bootstrap}</script>${cspMeta}</head><body>${html}</body></html>`;
+}
+
+/**
+ * Validate the iframe-only options. Throws on anything that would silently
+ * weaken the boundary.
+ *
+ * @returns {{ tokens: string[], allowSameOrigin: boolean, csp: string | undefined, html: string, container: Element | null, onFrame: ((f: HTMLIFrameElement) => void) | null }}
+ */
+export function normalizeIframeOptions(options = {}) {
+  const {
+    iframeSandbox = [],
+    dangerouslyAllowSameOrigin = false,
+    csp,
+    html = '',
+    container = null,
+    onFrame = null,
+  } = options;
+
+  if (!Array.isArray(iframeSandbox) || !iframeSandbox.every((t) => typeof t === 'string')) {
+    throw new TypeError("iframeSandbox must be an array of sandbox token strings, e.g. ['allow-forms']");
+  }
+  const tokens = [BASE_TOKEN];
+  for (const raw of iframeSandbox) {
+    const t = raw.trim().toLowerCase();
+    if (!/^allow-[a-z-]+$/.test(t)) {
+      throw new TypeError(`iframeSandbox: '${raw}' is not a sandbox token (expected 'allow-...')`);
+    }
+    if (!tokens.includes(t)) tokens.push(t);
+  }
+  const allowSameOrigin = tokens.includes('allow-same-origin');
+  if (allowSameOrigin && dangerouslyAllowSameOrigin !== true) {
+    throw new Error(
+      "iframeSandbox: 'allow-same-origin' together with 'allow-scripts' (always set in mode: 'iframe') lets the " +
+      'framed code reach your page, its cookies and storage, and remove its own sandbox attribute -- there is no ' +
+      'boundary left. Pass dangerouslyAllowSameOrigin: true only if the code is fully trusted.'
+    );
+  }
+  if (csp !== undefined && typeof csp !== 'string') throw new TypeError('csp must be a Content-Security-Policy string');
+  if (typeof html !== 'string') throw new TypeError('html must be a string of body markup');
+  if (onFrame !== null && typeof onFrame !== 'function') throw new TypeError('onFrame must be a function');
+  if (container !== null && (typeof container !== 'object' || typeof container.appendChild !== 'function')) {
+    throw new TypeError('container must be a DOM element');
+  }
+  return { tokens, allowSameOrigin, csp: csp || undefined, html, container, onFrame };
+}
+
+/**
+ * Create the iframe "worker" factory for one sandbox.
+ *
+ * @param {ReturnType<typeof normalizeIframeOptions>} opts
+ * @param {number} startupTimeoutMs  how long to wait for a new frame's handshake
+ * @returns {{ factory: (source: string) => object, current: () => HTMLIFrameElement | null }}
+ */
+export function createIframeFactory(opts, startupTimeoutMs) {
+  const win = globalThis;
+  const doc = globalThis.document;
+  if (!doc || typeof doc.createElement !== 'function' || typeof win.addEventListener !== 'function') {
+    throw new Error(
+      "mode: 'iframe' needs a DOM (a browser page with `document`); it is not available under Node or inside a Worker."
+    );
+  }
+  // Where the last frame was, so a restart puts its replacement in the same
+  // spot with the same attributes (class, style, width, ...).
+  let slot = null;
+  let current = null;
+
+  function factory(source) {
+    const token = crypto.randomUUID() + crypto.randomUUID();
+    const frame = doc.createElement('iframe');
+    if (slot) {
+      for (const [name, value] of slot.attributes) frame.setAttribute(name, value);
+    } else {
+      if (!opts.container) {
+        frame.setAttribute('style', OFFSCREEN_STYLE);
+        frame.setAttribute('aria-hidden', 'true');
+        frame.setAttribute('tabindex', '-1');
+      }
+      frame.setAttribute('title', 'andbox sandbox');
+    }
+    frame.setAttribute('sandbox', opts.tokens.join(' '));
+    frame.srcdoc = makeIframeDocument({ source, token, csp: opts.csp, html: opts.html });
+
+    const channel = new MessageChannel();
+    const port = channel.port1;
+    const listeners = new Set();
+    const expectedOrigin = opts.allowSameOrigin ? win.location?.origin : 'null';
+    let terminated = false;
+    let startTimer = null;
+
+    const adapter = {
+      iframe: frame,
+      dead: false,
+      onmessage: null,
+      onerror: null,
+      // Messages posted before the handshake wait in the port's queue and
+      // travel with the transferred port, like messages to a starting Worker.
+      postMessage(message) {
+        if (!terminated) port.postMessage(message);
+      },
+      addEventListener(type, fn) {
+        if (type === 'message') listeners.add(fn);
+      },
+      removeEventListener(type, fn) {
+        if (type === 'message') listeners.delete(fn);
+      },
+      terminate() {
+        if (terminated) return;
+        terminated = true;
+        adapter.dead = true;
+        cleanupHandshake();
+        try { port.close(); } catch {}
+        slot = {
+          parent: frame.parentNode,
+          next: frame.nextSibling,
+          attributes: [...frame.attributes]
+            .filter((a) => !OWNED_ATTRIBUTES.has(a.name))
+            .map((a) => [a.name, a.value]),
+        };
+        frame.remove();
+        if (current === adapter) current = null;
+      },
+    };
+
+    function fail(message) {
+      if (terminated || adapter.dead) return;
+      adapter.dead = true;
+      cleanupHandshake();
+      adapter.onerror?.({ message });
+    }
+
+    port.onmessage = (event) => {
+      if (terminated) return;
+      adapter.onmessage?.(event);
+      for (const fn of [...listeners]) fn(event);
+    };
+
+    // Bind the handshake to this frame's own WindowProxy and its secret token.
+    // `event.origin` is checked too, but on its own it would prove nothing:
+    // every opaque-origin frame reports 'null'.
+    function onHello(event) {
+      if (terminated || event.source === null || event.source !== frame.contentWindow) return;
+      const data = event.data;
+      if (!data || data.type !== 'andbox:hello' || data.token !== token) return;
+      if (expectedOrigin && event.origin !== expectedOrigin) return;
+      cleanupHandshake();
+      frame.contentWindow.postMessage({ type: 'andbox:init', token }, '*', [channel.port2]);
+    }
+
+    function cleanupHandshake() {
+      win.removeEventListener('message', onHello);
+      if (startTimer !== null) { clearTimeout(startTimer); startTimer = null; }
+    }
+
+    // The element's first load event is the srcdoc document; any later one
+    // means a different document now lives in the frame (the code navigated
+    // or reloaded it, or the element was moved in the DOM), and the runtime
+    // that held our port is gone.
+    let loads = 0;
+    frame.addEventListener('load', () => {
+      if (++loads > 1) fail('Sandbox iframe unloaded (it navigated, was reloaded, or was moved in the DOM)');
+    });
+
+    win.addEventListener('message', onHello);
+    if (startupTimeoutMs > 0) {
+      startTimer = setTimeout(() => {
+        startTimer = null;
+        fail(
+          `Sandbox iframe did not start within ${startupTimeoutMs}ms ` +
+          '(is its container attached to a document, and does csp/html leave its bootstrap intact?)'
+        );
+      }, startupTimeoutMs);
+    }
+
+    try {
+      opts.onFrame?.(frame);
+      if (!frame.isConnected) {
+        const prev = slot;
+        if (prev?.parent?.isConnected) {
+          prev.parent.insertBefore(frame, prev.next && prev.next.parentNode === prev.parent ? prev.next : null);
+        } else {
+          (opts.container || doc.body || doc.documentElement).appendChild(frame);
+        }
+      }
+    } catch (e) {
+      adapter.terminate();
+      throw e;
+    }
+    slot = null;
+    current = adapter;
+    return adapter;
+  }
+
+  return {
+    factory,
+    current: () => current?.iframe ?? null,
+  };
+}

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 ──
 
@@ -341,7 +400,8 @@ export interface SandboxOptions {
    * `Worker`. `'node-worker'` forces the Node implementation.
    */
   mode?: 'worker' | 'node-worker' | 'wasm';
-  // Any other value throws: supported modes are 'worker', 'node-worker', 'wasm', 'inline', 'data-uri', 'service-worker'.
+  // Any other value throws: supported modes are 'worker', 'node-worker', 'wasm', 'iframe', 'inline', 'data-uri', 'service-worker'.
+  // 'iframe' takes IframeSandboxOptions (below).
   /**
    * `mode: 'wasm'` only. URL of an ES module built from
    * `@johnhenry/andbox/wasm-engine` (the QuickJS engine entry), served from
@@ -411,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`). */
@@ -523,6 +593,64 @@ export interface Sandbox {
   isDisposed(): boolean;
 }
 
+/**
+ * Options for `createSandbox({ mode: 'iframe' })`: a sandboxed
+ * `<iframe sandbox="allow-scripts" srcdoc>` with an opaque origin, its own
+ * realm, `window` and `document`. Browser only (rejects without a DOM).
+ * All the Worker-mode options apply except `workerFactory`, `nodeWorker`,
+ * `unref` and the `mode: 'wasm'` limits.
+ */
+export interface IframeSandboxOptions
+  extends Omit<SandboxOptions, 'mode' | 'workerFactory' | 'nodeWorker' | 'unref' | 'untrusted' | 'engineURL' | 'wasmURL' | 'fuel' | 'memoryBytes' | 'stackBytes' | 'deadlineMs'> {
+  /** Mode discriminant. */
+  mode: 'iframe';
+  /**
+   * Element each frame is appended to. Default: `document.body`, placed
+   * offscreen (1x1 px at -10000px, `aria-hidden`) for evaluation-only use.
+   * A restarted frame takes its predecessor's place and attributes instead.
+   */
+  container?: Element;
+  /** Initial `<body>` markup of every new frame (also after a restart). Subject to `csp`. */
+  html?: string;
+  /**
+   * Content-Security-Policy injected as a `<meta http-equiv>` after andbox's
+   * bootstrap. evaluate() compiles code with `new Function`, so a policy that
+   * restricts scripts must allow `'unsafe-eval'` (and `blob:` for
+   * `defineModule()` modules, plus any hosts you `sandboxImport()` from).
+   */
+  csp?: string;
+  /**
+   * Extra sandbox tokens, e.g. `['allow-forms', 'allow-popups']`.
+   * `allow-scripts` is always set. `'allow-same-origin'` is refused unless
+   * `dangerouslyAllowSameOrigin` is true.
+   */
+  iframeSandbox?: string[];
+  /**
+   * Permit `'allow-same-origin'` in `iframeSandbox`. Together with
+   * `allow-scripts` that removes the boundary entirely: the frame runs in your
+   * origin and can reach your page, cookies and storage, and un-sandbox itself.
+   */
+  dangerouslyAllowSameOrigin?: boolean;
+  /**
+   * Called synchronously with every new frame (the first and each one created
+   * by a timeout/abort/unload restart) before andbox attaches it. Style it,
+   * set attributes such as `allow`, or insert it yourself; if it is still
+   * detached when this returns, andbox attaches it.
+   */
+  onFrame?: (iframe: HTMLIFrameElement) => void;
+}
+
+/** A sandbox created with `mode: 'iframe'`. */
+export interface IframeSandbox extends Sandbox {
+  /**
+   * The live frame element. It is replaced by a new element after a timeout,
+   * an abort, or the frame navigating/reloading (use `onFrame` to follow
+   * replacements), and is `null` after dispose(). Do not move it in the DOM:
+   * that reloads the document and loses the sandbox state.
+   */
+  readonly iframe: HTMLIFrameElement | null;
+}
+
 /** Options for createSandbox({ mode: 'service-worker' }). */
 export interface ServiceWorkerSandboxOptions {
   /** Mode discriminant. */
@@ -582,6 +710,9 @@ export interface ServiceWorkerSandbox {
  * - Console forwarding
  * - Capability gating with rate limits
  *
+ * `mode: 'iframe'` runs the code in a sandboxed, opaque-origin `<iframe>`
+ * with a real DOM, and adds `iframe` to the returned object.
+ *
  * `mode: 'service-worker'` is a different shape entirely: it hosts a
  * path → content map behind a real, same-origin, HTTP-shaped scope
  * instead of evaluating code — see andbox#14 and README's Security model
@@ -590,6 +721,7 @@ export interface ServiceWorkerSandbox {
  * @param options  Sandbox configuration options.
  * @returns A promise that resolves to the sandbox instance.
  */
+export declare function createSandbox(options: IframeSandboxOptions): Promise<IframeSandbox>;
 export declare function createSandbox(options?: SandboxOptions): Promise<Sandbox>;
 export declare function createSandbox(
   options: ServiceWorkerSandboxOptions,

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

@@ -1,7 +1,7 @@
 /**
  * andbox — Sandboxed JavaScript runtime.
  *
- * Creates an isolated Web Worker sandbox with:
+ * Creates an isolated Web Worker (or, with mode: 'iframe', sandboxed iframe) sandbox with:
  * - RPC-based capability calls (host.call)
  * - Import map resolution
  * - Virtual module definitions
@@ -17,6 +17,8 @@ import { gateCapabilities } from './capability-gate.mjs';
 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;
 
@@ -305,15 +307,24 @@ async function createServiceWorkerSandbox(options = {}) {
  * @property {string} [baseURL] - Base URL for relative imports
  * @property {import('./capability-gate.mjs').GatePolicy} [policy] - Rate limiting policy
  * @property {(level: string, ...args: string[]) => void} [onConsole] - Console output handler
+ * @property {Element} [container] - mode: 'iframe': element the frame is appended to (default: offscreen in document.body)
+ * @property {string} [html] - mode: 'iframe': initial body markup
+ * @property {string} [csp] - mode: 'iframe': Content-Security-Policy for the frame
+ * @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', 'inline', 'data-uri', 'service-worker'];
+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.
  *
  * @param {SandboxOptions | ServiceWorkerSandboxOptions} [options]
- * @returns {{ execute: Function, terminate: Function } | Promise<{ evaluate: Function, defineModule: Function, dispose: Function, isDisposed: () => boolean }> | Promise<{ scriptURL: string, scope: string, define: Function, remove: Function, dispose: Function, isDisposed: () => boolean }>}
+ * @returns {{ execute: Function, terminate: Function } | Promise<{ evaluate: Function, defineModule: Function, dispose: Function, isDisposed: () => boolean, iframe?: HTMLIFrameElement | null }> | Promise<{ scriptURL: string, scope: string, define: Function, remove: Function, dispose: Function, isDisposed: () => boolean }>}
  */
 export function createSandbox(options = {}) {
   if (options.untrusted === true) {
@@ -339,10 +350,17 @@ 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);
-  return createWorkerSandbox(options, mode === 'node-worker', mode === 'wasm');
+  return createWorkerSandbox(options, mode);
 }
 
 /** Default limits for `mode: 'wasm'` (0 = unlimited / not enforced). */
@@ -408,7 +426,18 @@ async function resolveWasmConfig(options, baseURL, usingNode) {
   };
 }
 
-async function createWorkerSandbox(options = {}, forceNode = false, isWasm = false) {
+/**
+ * Worker-shaped sandboxes: `worker`, `node-worker`, `wasm` and `iframe`. They
+ * share one host implementation; `iframe` swaps the Worker for a sandboxed
+ * `<iframe>` adapter (src/iframe-host.mjs) behind the same interface.
+ *
+ * @param {object} options
+ * @param {'worker' | 'node-worker' | 'wasm' | 'iframe'} [kind]
+ */
+async function createWorkerSandbox(options = {}, kind = 'worker') {
+  const forceNode = kind === 'node-worker';
+  const isWasm = kind === 'wasm';
+  const isIframe = kind === 'iframe';
   const {
     importMap = { imports: {}, scopes: {} },
     capabilities = {},
@@ -419,6 +448,7 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
     nodeWorker,
     unref = false,
     allowedImportHosts,
+    network,
   } = options;
 
   // undefined = unset: remote imports allowed. An array (even empty) restricts.
@@ -433,6 +463,18 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
   // default selects it only when there is no global Worker under Node.
   let workerFactory = options.workerFactory || null;
   let usingNode = false;
+  // mode: 'iframe' -- a sandboxed, opaque-origin <iframe> instead of a Worker.
+  let iframeHost = null;
+  if (isIframe) {
+    if (options.workerFactory || nodeWorker) {
+      throw new Error("workerFactory and nodeWorker do not apply to mode: 'iframe'.");
+    }
+    iframeHost = createIframeFactory(
+      normalizeIframeOptions(options),
+      defaultTimeoutMs > 0 ? defaultTimeoutMs : DEFAULT_TIMEOUT_MS
+    );
+    workerFactory = iframeHost.factory;
+  }
   if (!workerFactory && (forceNode || (typeof Worker === 'undefined' && isNodeRuntime()))) {
     workerFactory = await createNodeWorkerFactory(nodeWorker);
     usingNode = true;
@@ -459,8 +501,22 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
     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;
@@ -494,7 +550,9 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
 
   function createWorker() {
     workerAbort = new AbortController();
-    const source = isWasm ? makeWasmWorkerSource() : makeWorkerSource();
+    const source = isWasm
+      ? makeWasmWorkerSource()
+      : isIframe ? makeIframeRuntimeSource({ networkFetch }) : makeWorkerSource({ networkFetch });
     if (workerFactory) {
       worker = workerFactory(source);
       attachWorkerHandlers();
@@ -817,11 +875,21 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
     endOp();
   }
 
-  return {
+  const sandbox = {
     evaluate,
     defineModule,
     dispose,
     stats,
     isDisposed: () => disposed,
   };
+  if (iframeHost) {
+    // The live frame. A timeout, abort or unload replaces it with a new
+    // element (same container position and attributes; `onFrame` is called
+    // for every new one), and it is null after dispose().
+    Object.defineProperty(sandbox, 'iframe', {
+      enumerable: true,
+      get: () => (disposed ? null : iframeHost.current()),
+    });
+  }
+  return sandbox;
 }

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,9 +134,43 @@
  * - `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() {
+export function makeWorkerSource({ networkFetch = false } = {}) {
+  return makeRuntimeSource({ lockdown: true, networkFetch });
+}
+
+/**
+ * The shared runtime behind `makeWorkerSource()` (Worker) and `mode: 'iframe'`.
+ *
+ * The script talks to the host through a `self`-shaped object with
+ * `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, 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, networkFetch = false } = {}) {
+  const lockedGlobals = lockdown
+    ? `[
+  ${networkFetch ? '' : "'fetch', "}'XMLHttpRequest', 'WebSocket', 'WebSocketStream', 'WebTransport', 'EventSource',
+  'Worker', 'SharedWorker', 'importScripts', 'indexedDB', 'caches', 'BroadcastChannel',
+  'postMessage', 'self',
+]`
+    : '[]';
+  const shadowed = lockdown ? "[...LOCKED_GLOBALS, 'window']" : '[]';
   return `
 'use strict';
 
@@ -48,20 +193,20 @@ try { delete globalThis.__andboxNodeVirtual; } catch {}
 const scope = self;
 const post = self.postMessage.bind(self);
 const closeSelf = typeof self.close === 'function' ? self.close.bind(self) : () => {};
-const LOCKED_GLOBALS = [
-  'fetch', 'XMLHttpRequest', 'WebSocket', 'WebSocketStream', 'WebTransport', 'EventSource',
-  'Worker', 'SharedWorker', 'importScripts', 'indexedDB', 'caches', 'BroadcastChannel',
-  'postMessage', 'self',
-];
+const LOCKED_GLOBALS = ${lockedGlobals};
 for (const k of LOCKED_GLOBALS) {
   try { delete globalThis[k]; } catch {}
   if (k in globalThis) {
     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 = [...LOCKED_GLOBALS, 'window'];
+const SHADOWED = ${shadowed};
 
 // ── Remote import policy (andbox#7) ──
 function assertImportAllowed(href) {