@johnhenry/andbox 0.1.1 → 0.1.2

package/README.md

@@ -21,6 +21,7 @@ Zero dependencies. Uses only Web Workers and standard browser APIs.
 - [Sandbox Modes](#sandbox-modes)
 - [Node](#node)
 - [`mode: 'wasm'`](#mode-wasm)
+- [`mode: 'iframe'`](#mode-iframe)
 - [API](#api)
 - [Execution model](#execution-model)
 - [Security model](#security-model)
@@ -88,11 +89,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 +244,64 @@ 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.
+- **`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.
+
 ## 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 +313,14 @@ 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 |
 
-**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 +344,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()`
 
@@ -426,6 +481,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 +493,20 @@ 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).
 - **`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).
 - **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 +516,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`. 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`). |
+| **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 +553,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.2",
   "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,291 @@
+/**
+ * `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. */
+export function makeIframeRuntimeSource() {
+  return makeRuntimeSource({ lockdown: false });
+}
+
+/**
+ * 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

@@ -341,7 +341,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
@@ -523,6 +524,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 +641,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 +652,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/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,7 @@ 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';
 
 const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
 
@@ -305,15 +306,21 @@ 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
  */
 
-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'];
 
 /**
  * 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) {
@@ -342,7 +349,7 @@ export function createSandbox(options = {}) {
   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 +415,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 = {},
@@ -433,6 +451,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;
@@ -494,7 +524,7 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
 
   function createWorker() {
     workerAbort = new AbortController();
-    const source = isWasm ? makeWasmWorkerSource() : makeWorkerSource();
+    const source = isWasm ? makeWasmWorkerSource() : isIframe ? makeIframeRuntimeSource() : makeWorkerSource();
     if (workerFactory) {
       worker = workerFactory(source);
       attachWorkerHandlers();
@@ -817,11 +847,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

@@ -26,6 +26,32 @@
  * @returns {string} The Worker script source code.
  */
 export function makeWorkerSource() {
+  return makeRuntimeSource({ lockdown: true });
+}
+
+/**
+ * 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 }} [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`.
+ * @returns {string}
+ */
+export function makeRuntimeSource({ lockdown = true } = {}) {
+  const lockedGlobals = lockdown
+    ? `[
+  'fetch', 'XMLHttpRequest', 'WebSocket', 'WebSocketStream', 'WebTransport', 'EventSource',
+  'Worker', 'SharedWorker', 'importScripts', 'indexedDB', 'caches', 'BroadcastChannel',
+  'postMessage', 'self',
+]`
+    : '[]';
+  const shadowed = lockdown ? "[...LOCKED_GLOBALS, 'window']" : '[]';
   return `
 'use strict';
 
@@ -48,11 +74,7 @@ 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) {
@@ -61,7 +83,7 @@ for (const k of LOCKED_GLOBALS) {
 }
 // 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) {