@johnhenry/andbox 0.1.3 → 0.2.0

package/README.md

@@ -294,19 +294,19 @@ Use `mode: 'wasm'` (fuel and deadline inside the engine) or `worker` mode for co
 
 ## 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:
+Worker mode removes `fetch` from the sandbox. Code you hand a capability to can call `host.call(...)`, but a library imported into the sandbox (`d3.json()`, `ky`, an API client) calls the **global** `fetch` and fails. The `network` option (0.1.3, [andbox#39](https://github.com/johnhenry/andbox/issues/39)) installs a global `fetch` in the sandbox that sends every request to a function on the host, which decides what happens. **No network unless you list hosts:** since 0.2.0 ([andbox#43](https://github.com/johnhenry/andbox/issues/43)) `network.allowedHosts` is required, so setting `network` never means "every host" by accident:
 
 ```js
 import { createSandbox } from '@johnhenry/andbox';
 
 const sandbox = await createSandbox({
   network: {
-    // Runs on the host for every request the sandbox makes. Same signature as fetch.
+    allowedHosts: ['api.example.com'],            // required: checked on the host before fetch is called
+    // Optional. Runs on the host for every allowed request. Same signature as fetch.
     async fetch(url, init) {
       console.log(init.method, url);              // you see every request
       return fetch(url, { ...init, referrerPolicy: 'no-referrer' }); // init.credentials is 'omit'
     },
-    // allowedHosts: ['api.example.com'],         // optional: createNetworkFetch() allowlist in front of it
   },
   policy: { capabilities: { fetch: { maxCalls: 100 } } }, // the usual gate applies
 });
@@ -320,14 +320,39 @@ await sandbox.evaluate(`
 
 **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.
+**On the host**, the request becomes an ordinary capability named `fetch`, so it goes through the capability gate and `policy` like any other (`policy.capabilities.fetch` limits it; `stats().gate.perCapability.fetch` counts it; binary bodies travel as base64, so `maxArgBytes` counts them). The host side treats it as untrusted input, because evaluated code can also call `host.call('fetch', url, init)` directly: it checks the URL again (http(s) only), validates the method, header pairs, body and `redirect`, checks the host against `allowedHosts`, and then calls your function as `fetch(url, init)` with `init.headers` a `Headers`, `init.body` a string or `Uint8Array`, `init.credentials` set by the host, and `init.signal` aborted when the sandbox is terminated (it is called without a `this`, so `network: { allowedHosts, fetch }` with the platform's own `fetch` works). Return a `Response`, or a plain `{ status, statusText, headers, body, url, redirected }` (`body` a string, `ArrayBuffer`, typed array or `Blob`). `Set-Cookie` is never passed to the sandbox, and opaque or error responses (`status` outside 200-599) reject.
 
 | `network` field | Type | Default | Description |
 |---|---|---|---|
-| `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. |
+| `allowedHosts` | `string[] \| (url: URL) => boolean \| '*'` | **required** | Which hosts the sandbox may reach, checked on the host before `fetch` is called (forms below). Leaving it out throws at `createSandbox()`. |
+| `fetch` | `(url, init) => Response \| { status, headers, body, ... }` | the platform's global `fetch` | Host function for every request `allowedHosts` lets through. |
 | `credentials` | `'omit' \| 'same-origin' \| 'include'` | `'omit'` | What the host passes as `init.credentials`. The sandbox cannot change it. |
 
+**`allowedHosts` takes one of three forms:**
+
+```js
+// 1. A list of hostnames: the sandbox reaches these and nothing else.
+network: { allowedHosts: ['api.example.com', 'cdn.example.com'] }
+
+// 2. A function, asked on the host for every request (and every redirect hop):
+//    for an allowlist that changes while the sandbox runs, like a notebook
+//    that asks the user per host. Only `true` (or a promise of it) allows.
+const approved = new Set(['api.example.com']);
+network: { allowedHosts: (url) => approved.has(url.hostname) }
+
+// 3. The explicit opt-in to any http(s) host. Your fetch is then the whole
+//    policy, so write it next to one that enforces its own rules.
+network: { allowedHosts: '*', fetch: myPolicyFetch }
+```
+
+- **A list** matches the request URL's hostname exactly: case-insensitive, normalised the way `URL` does it (IDN to punycode, IPv4 forms to dotted decimal), on any port and either scheme. There is no subdomain or wildcard matching: `'example.com'` does not allow `api.example.com`, and `'api.example.com'` does not allow `example.com`. Write IPv6 in brackets (`'[::1]'`). An entry with a scheme, port, path or `*` throws instead of silently never matching, and an empty list throws (to give the sandbox no network, leave `network` out). It is [`createNetworkFetch()`](#createnetworkfetchallowedhosts-fetchfn) in front of your `fetch`.
+- **A function** gets a fresh `URL` (changing it does not change the request). Anything other than `true` refuses with `Network access denied: <host> is not allowed by network.allowedHosts`; if it throws, the sandbox's `fetch` rejects with that error's message, which is a good place for "allow this host in settings". It may be `async`.
+- **`'*'`** skips the host check (the URL must still be http(s)) and leaves everything else, redirects included, to your `fetch`. Without a `fetch`, it is the platform's `fetch` for any host.
+
+**Redirects.** With a list, every request is made with `redirect: 'manual'` and any redirect response is refused, so an allowlisted host cannot send the request elsewhere. With a function, andbox follows redirects itself: each request is made with `redirect: 'manual'`, and for every `Location` it asks your function again before requesting it (at most 20 hops; 301/302 after a `POST` and 303 become a `GET` without a body, as the Fetch standard does; `Authorization` is dropped when the hop changes origin). The sandbox sees the final `url` and `redirected: true`; `redirect: 'error'` from the sandbox rejects on a redirect and `redirect: 'manual'` returns it unfollowed. A browser's own `fetch` hides a manual redirect's target (an `opaqueredirect` response), so over the page's `fetch` a function policy cannot check the next hop and the request **fails** rather than following it blindly; on Node, Deno and Bun, or with a `network.fetch` that returns the 3xx response, redirects are followed and checked. With `'*'`, your `fetch` receives the sandbox's `redirect` mode and decides; the platform `fetch` follows redirects to any host.
+
+**On a server, the host function has the server's network position.** With `node-worker` (or any server-side host), whatever `allowedHosts` lets through is fetched from inside your network: `localhost`, private addresses, and cloud metadata endpoints such as `169.254.169.254` are reachable if the policy allows them. Prefer a list; with a function or `'*'`, refuse private and link-local addresses yourself (and remember DNS can point a public name at one).
+
 **Modes.** `worker` and `node-worker`: the shim is the only `fetch` the code can reach by name. `iframe`: it replaces the frame's own `fetch`, but the frame still has its other network APIs (`XMLHttpRequest`, `WebSocket`, `<img>`, `import()`); add `csp: "connect-src 'none'"` (and `default-src` as needed) to leave the host function as the only way to fetch, since the shim talks to the host over a `MessagePort` that CSP does not affect. `wasm`, `inline`, `data-uri` and `service-worker` throw if `network` is given (in `wasm`, expose a capability and use `host.call()`). Passing both `network` and a capability named `fetch` throws.
 
 **Limits.** The response body is buffered on the host and copied into the sandbox (no streaming; enforce size limits in your function, for example from `content-length` and `arrayBuffer().byteLength`). Aborting the sandbox-side `signal` rejects the call immediately but does not cancel the host request; terminating the sandbox does (`init.signal`). The rebuilt `Response` has `type: 'default'`. What this does and does not narrow is in the [Security model](#security-model).
@@ -360,7 +385,7 @@ Creates a new sandboxed runtime. Returns a promise (Worker, wasm and iframe mode
 | `iframeSandbox` | `string[]` | `[]` | `mode: 'iframe'`: extra sandbox tokens (`allow-scripts` is always set); `'allow-same-origin'` throws unless `dangerouslyAllowSameOrigin` |
 | `dangerouslyAllowSameOrigin` | `boolean` | `false` | `mode: 'iframe'`: permit `'allow-same-origin'`, which removes the origin boundary |
 | `onFrame` | `(iframe) => void` | -- | `mode: 'iframe'`: called with every new frame (first and after each restart) before it is attached |
-| `network` | `{ 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). |
+| `network` | `{ allowedHosts, fetch?, credentials? }` | unset | `worker`, `node-worker`, `iframe`: install a global `fetch` in the sandbox that sends every request through the host function (the gated `fetch` capability). `allowedHosts` is required (a hostname list, a `(url) => boolean` function, or `'*'`); without it `createSandbox()` throws. **Unset: no `fetch` in worker modes** (unchanged). See [Mediated network](#mediated-network-network). |
 
 **Returns (Worker mode):** `Promise<{ evaluate, defineModule, dispose, stats, isDisposed }>`. `mode: 'iframe'` adds `iframe`, the live `HTMLIFrameElement` (`null` after `dispose()`, replaced after a restart; see [`mode: 'iframe'`](#mode-iframe)).
 
@@ -439,7 +464,7 @@ registry.dispose();                                  // revokes blob URLs / drop
 
 ### `createNetworkFetch(allowedHosts?, fetchFn?)`
 
-Creates a fetch function that checks the request hostname against an allowlist before calling through. 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`.
+Creates a fetch function that checks the request hostname against an allowlist before calling through. Requests are made with `redirect: 'manual'` and any redirect response is rejected, so an allowlisted host cannot send the caller elsewhere (see [Security model](#security-model)). It is what `network: { allowedHosts: [...] }` puts in front of the sandbox's `fetch`. Unlike `network.allowedHosts`, a missing or empty list here still allows every host ([andbox#44](https://github.com/johnhenry/andbox/issues/44)).
 
 ```js
 import { createNetworkFetch } from '@johnhenry/andbox';
@@ -541,7 +566,8 @@ andbox is **not** a boundary against code that is actively trying to escape it.
 
 - **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).
+- **`network`: no network unless you list hosts.** `network.allowedHosts` is required (0.2.0, [andbox#43](https://github.com/johnhenry/andbox/issues/43)): a list of hostnames, a function asked about every request and redirect hop, or the explicit `'*'`, which hands the whole decision to your `fetch`. Setting `network` without it throws, so it can no longer mean "every host your function will fetch" by omission.
+- **`network` narrows `fetch` to what `allowedHosts` and your host function allow; it does not close the other routes out.** With `network` set, the sandbox's global `fetch` is a shim: each request goes through the gated `fetch` capability, http(s) only, is checked against `allowedHosts` on the host, and reaches your function with `credentials` (default `'omit'`) chosen by the host and `Set-Cookie` withheld. That is a policy point for well-behaved code and the libraries it imports, not a wall: in worker mode the platform `import()` operator can still fetch (and run) arbitrary URLs and carry data out in them, as can `sandboxImport()` unless `allowedImportHosts` restricts it; in iframe mode the frame's own `XMLHttpRequest`, `WebSocket`, `<img>`, `<form>` and `import()` remain unless `csp` blocks them. Your function is what talks to the network on the sandbox's behalf with the host's network position (a server-side host can reach your internal network and cloud metadata endpoints): prefer an `allowedHosts` list, refuse private addresses in a function or `'*'` policy, and do not forward the sandbox's headers to hosts that trust them blindly. With `'*'`, redirects are whatever your `fetch` does. See [Mediated network](#mediated-network-network) and [andbox#39](https://github.com/johnhenry/andbox/issues/39).
 - **A timeout cannot undo in-flight host-side effects; it can ask them to stop.** When the Worker is terminated (timeout, an aborted `evaluate()`, `dispose()`, a crash) every capability call still in flight sees `this.signal` abort, and its late result is dropped rather than delivered. Cancellation is cooperative: a capability that ignores `this.signal` still runs to completion on the host. Write effectful capabilities as `function`s (not arrows) and pass the signal on (`fetch(url, { signal: this.signal })`), and keep them idempotent. In `mode: 'wasm'`, a cooperative `deadlineMs` ends the evaluation without terminating the Worker, so the signal does not abort in that case. See [andbox#8](https://github.com/johnhenry/andbox/issues/8).
 - **`mode: 'iframe'`: the origin boundary is the whole guarantee.** Still yours:
   - **Network.** The frame has `fetch`, `WebSocket`, `import()`, `<img>`, `<form>` and so on, as a `null`-origin client: it can exfiltrate anything it was given or computed, and reach any server that answers cross-origin requests. Pass a `csp` (`default-src 'none'` plus what the code needs) to restrict it.
@@ -596,15 +622,6 @@ code-based tool execution.
   is the source of truth for what that capability gate does and does not
   guarantee -- the middleware's Security model section points back here
   rather than repeating it.
-- **[`@johnhenry/prism`](https://github.com/johnhenry/prism)** -- a live
-  HTTP request inspector/proxy whose custom script-route feature runs
-  user-provided route handlers via `createSandbox({ mode: 'inline' })`.
-  Deliberately uses `inline` mode, not the default `worker` mode: the
-  handler needs a live `Request` object (with its body stream) directly in
-  scope, which can't cross a Worker's structured-clone boundary, and the
-  feature's predecessor (a package called `vimble`) never provided real
-  isolation either -- `inline`'s explicit "no isolation, code you already
-  trust" framing is the honest match, not a downgrade from what came before.
 
 ## License
 

package/package.json

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

package/src/index.d.ts

@@ -251,23 +251,46 @@ export interface SandboxFetchReply {
   redirected?: boolean;
 }
 
+/**
+ * `network.allowedHosts` as a function: asked on the host, with a fresh `URL`,
+ * before every request the sandbox makes and before every redirect hop andbox
+ * follows. Only `true` (or a promise of `true`) allows; anything else refuses,
+ * and a thrown error is the message the sandbox's `fetch` rejects with.
+ */
+export type SandboxHostPolicy = (url: URL) => boolean | Promise<boolean>;
+
 /** `createSandbox({ network })`: a host-backed global `fetch` inside the sandbox. */
 export interface SandboxNetworkOptions {
   /**
-   * 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.
+   * Required (0.2.0, andbox#43): which hosts the sandbox may reach. Checked on
+   * the host before `fetch` is called, so leaving it out is an error rather
+   * than "every host".
+   *
+   * - `string[]`: hostnames, matched exactly against the request URL's
+   *   hostname (case-insensitive, IDN and IPv4 normalised like `URL`, any
+   *   port, http or https). No subdomain matching: `'example.com'` does not
+   *   allow `'api.example.com'`. IPv6 in brackets (`'[::1]'`). Entries with a
+   *   scheme, port, path or `*` throw. Must not be empty. Any redirect is
+   *   refused (the request is made with `redirect: 'manual'`).
+   * - `(url: URL) => boolean | Promise<boolean>`: a policy asked for every
+   *   request, so the allowlist can change while the sandbox runs. andbox
+   *   follows redirects itself (`redirect: 'manual'` underneath) and asks it
+   *   again for each hop; where the platform hides the target (a browser's
+   *   opaque redirect) the request fails.
+   * - `'*'`: any http(s) host. Your `fetch` is the whole policy, and the
+   *   sandbox's redirect mode is passed to it unchanged.
+   */
+  allowedHosts: readonly string[] | '*' | SandboxHostPolicy;
+  /**
+   * Called on the host for every request the sandbox's `fetch` makes that
+   * `allowedHosts` allows, through the gated `fetch` capability
+   * (`policy.capabilities.fetch` applies). The URL is always absolute
+   * http(s). Return a `Response` or a plain reply. Called without a `this`,
+   * so the platform `fetch` itself can be passed. Default: the platform's
+   * global `fetch` (on a server, that has the server's network position).
    */
   fetch?: (url: string, init: SandboxFetchInit) =>
     Response | SandboxFetchReply | Promise<Response | SandboxFetchReply>;
-  /**
-   * 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;
 }
@@ -475,7 +498,8 @@ export interface SandboxOptions {
    * `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
+   * only, and only to the hosts `network.allowedHosts` allows (required,
+   * andbox#43); `credentials` is the host's choice. Other network globals stay
    * locked in worker modes; the platform `import()` operator is not affected.
    * Unset (default): worker modes have no `fetch`. Conflicts with a
    * capability named `fetch`.

package/src/network-policy.mjs

@@ -107,47 +107,232 @@ async function toWireResponse(res, requestURL) {
   };
 }
 
+// ── allowedHosts: required, three forms (andbox#43) ──
+
+/** The explicit opt-in for "any http(s) host; my `fetch` is the whole policy". */
+const ANY_HOST = '*';
+
+const MAX_REDIRECTS = 20;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/** Request headers that describe the body; dropped when a redirect turns the request into a GET. */
+const BODY_HEADERS = ['content-encoding', 'content-language', 'content-location', 'content-type'];
+
+const ALLOWED_HOSTS_EXAMPLE =
+  "  network: { allowedHosts: ['api.example.com'] }                     // only these hosts\n" +
+  '  network: { fetch, allowedHosts: (url) => policy.allows(url.host) } // decided per request\n' +
+  "  network: { fetch, allowedHosts: '*' }                              // any host: your fetch is the whole policy";
+
+const ENTRY_HINT =
+  "entries are hostnames without a scheme, port, path or wildcard, e.g. 'api.example.com', '127.0.0.1', '[::1]'";
+
 /**
- * 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.
+ * Normalise one `allowedHosts` array entry to the form `URL#hostname` has
+ * (lowercase, punycode, canonical IPv4, bracketed IPv6), so it can be
+ * compared with a request URL's hostname. Throws on anything that would
+ * silently never match (a port, a scheme, a path, a wildcard).
+ */
+function normalizeHostEntry(entry) {
+  if (typeof entry !== 'string' || entry.length === 0) {
+    throw new TypeError(`network.allowedHosts: ${ENTRY_HINT} (got ${JSON.stringify(entry)})`);
+  }
+  if (entry === ANY_HOST) {
+    throw new TypeError("network.allowedHosts: to allow any host pass the string '*' itself, not inside an array");
+  }
+  const bare = entry.startsWith('[') ? entry.replace(/^\[[^\]]*\]/, '') : entry;
+  if (/[/?#@\s*\\]/.test(entry) || bare.includes(':')) {
+    throw new TypeError(`network.allowedHosts: ${ENTRY_HINT} (got '${entry}')`);
+  }
+  let hostname;
+  try {
+    hostname = new URL(`http://${entry}/`).hostname;
+  } catch {
+    throw new TypeError(`network.allowedHosts: '${entry}' is not a valid hostname; ${ENTRY_HINT}`);
+  }
+  return hostname;
+}
+
+/**
+ * Validate `createSandbox({ network })` without building anything, so
+ * `createSandbox()` can refuse a bad option before it starts a Worker.
  *
- * @param {{ fetch?: Function, allowedHosts?: string[], credentials?: RequestCredentials }} network
- * @returns {(this: { signal?: AbortSignal }, url: unknown, init?: unknown) => Promise<object>}
+ * @returns {{ hostFetch?: Function, allowedHosts: string[] | '*' | ((url: URL) => unknown), credentials: RequestCredentials }}
  */
-export function createFetchCapability(network) {
+export function validateNetworkOptions(network) {
   if (network === null || typeof network !== 'object' || Array.isArray(network)) {
-    throw new TypeError('network must be an object: { fetch?, allowedHosts?, credentials? }');
+    throw new TypeError('network must be an object: { allowedHosts, fetch?, credentials? }');
   }
   for (const key of Object.keys(network)) {
     if (!NETWORK_KEYS.has(key)) {
-      throw new TypeError(`network.${key} is not a known option (expected fetch, allowedHosts, credentials)`);
+      throw new TypeError(`network.${key} is not a known option (expected allowedHosts, fetch, credentials)`);
     }
   }
   const { fetch: hostFetch, allowedHosts, credentials = 'omit' } = network;
   if (hostFetch !== undefined && typeof hostFetch !== 'function') {
     throw new TypeError('network.fetch must be a function (url, init) => Response');
   }
-  if (allowedHosts !== undefined) {
-    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 === undefined) {
+    throw new TypeError(
+      'network.allowedHosts is required: the sandbox gets no network unless you say which hosts it may reach. ' +
+      `For example:\n${ALLOWED_HOSTS_EXAMPLE}`
+    );
+  }
+  let hosts;
+  if (allowedHosts === ANY_HOST || typeof allowedHosts === 'function') {
+    hosts = allowedHosts;
+  } else if (Array.isArray(allowedHosts)) {
     if (allowedHosts.length === 0) {
-      throw new TypeError('network.allowedHosts must list at least one host; to give the sandbox no network, omit `network`');
+      throw new TypeError(
+        'network.allowedHosts must list at least one host; to give the sandbox no network, omit `network`. ' +
+        `For example:\n${ALLOWED_HOSTS_EXAMPLE}`
+      );
     }
-  }
-  if (hostFetch === undefined && allowedHosts === undefined) {
-    throw new TypeError('network needs `fetch` (a host function) and/or `allowedHosts`');
+    hosts = [...new Set(allowedHosts.map(normalizeHostEntry))];
+  } else {
+    throw new TypeError(
+      "network.allowedHosts must be an array of hostnames, a function (url: URL) => boolean, or '*' " +
+      `(got ${typeof allowedHosts === 'string' ? `'${allowedHosts}'` : typeof allowedHosts}). For example:\n${ALLOWED_HOSTS_EXAMPLE}`
+    );
   }
   if (!CREDENTIALS.includes(credentials)) {
     throw new TypeError(`network.credentials must be one of ${CREDENTIALS.map((c) => `'${c}'`).join(', ')}`);
   }
+  return { hostFetch, allowedHosts: hosts, credentials };
+}
 
-  const send = allowedHosts ? createNetworkFetch(allowedHosts, hostFetch) : hostFetch;
+/** The host's fetch, or the platform's, called without a `this`. */
+function resolveFetch(hostFetch) {
+  if (hostFetch) return (url, init) => hostFetch(url, init);
+  return (url, init) => {
+    const platformFetch = globalThis.fetch;
+    if (typeof platformFetch !== 'function') throw new Error('fetch is not available');
+    return platformFetch.call(globalThis, url, init);
+  };
+}
+
+async function askPolicy(policy, href) {
+  // A fresh URL each time: the policy cannot change the URL andbox requests.
+  const verdict = await policy(new URL(href));
+  if (verdict !== true) {
+    throw new Error(`Network access denied: ${new URL(href).host} is not allowed by network.allowedHosts`);
+  }
+}
+
+function responseHeaders(res) {
+  if (res?.headers && typeof res.headers.get === 'function') return res.headers;
+  try {
+    return new Headers(res?.headers ?? undefined);
+  } catch {
+    return new Headers();
+  }
+}
+
+function discardBody(res) {
+  try {
+    res?.body?.cancel?.().catch(() => {});
+  } catch {
+    // nothing to release
+  }
+}
+
+/**
+ * `allowedHosts` as a function: ask it about every URL andbox is about to
+ * request, the first one and every redirect hop. Redirects are followed by
+ * andbox itself (`redirect: 'manual'` underneath), re-asking the function for
+ * each `Location`, with the Fetch standard's method/body rewriting and
+ * `Authorization` dropped on a cross-origin hop. Where the platform hides the
+ * target (a browser's `opaqueredirect`), the request fails closed.
+ */
+function createPolicyFetch(policy, hostFetch) {
+  const send = resolveFetch(hostFetch);
+  return async function policyFetch(url, init) {
+    const { body: firstBody, headers: firstHeaders, method: firstMethod, ...rest } = init;
+    const mode = init.redirect ?? 'follow';
+    let href = url;
+    let method = firstMethod;
+    let headers = new Headers(firstHeaders);
+    let body = firstBody;
+    for (let hop = 0; ; hop++) {
+      await askPolicy(policy, href);
+      const res = await send(href, {
+        ...rest,
+        method,
+        headers,
+        ...(body !== undefined ? { body } : {}),
+        redirect: 'manual',
+      });
+      if (mode === 'manual') return res;
+      if (res?.type === 'opaqueredirect') {
+        throw new Error(
+          `Network access denied: ${new URL(href).host} answered with a redirect whose target this platform's fetch hides, ` +
+          "so network.allowedHosts cannot check it; pass a network.fetch that returns the redirect response, or use allowedHosts: '*'"
+        );
+      }
+      const location = REDIRECT_STATUSES.has(res?.status) ? responseHeaders(res).get('location') : null;
+      if (location === null) {
+        if (hop === 0) return res;
+        return { status: res.status, statusText: res.statusText, headers: responseHeaders(res), body: await readBody(res), url: href, redirected: true };
+      }
+      discardBody(res);
+      if (mode === 'error') throw new Error(`fetch: ${new URL(href).host} redirected and the request's redirect mode is 'error'`);
+      if (hop + 1 > MAX_REDIRECTS) throw new Error(`fetch: more than ${MAX_REDIRECTS} redirects`);
+      let next;
+      try {
+        next = new URL(location, href);
+      } catch {
+        throw new Error(`fetch: ${new URL(href).host} redirected to an invalid URL`);
+      }
+      if (next.protocol !== 'http:' && next.protocol !== 'https:') {
+        throw new Error(`Network access denied: ${new URL(href).host} redirected to a ${next.protocol} URL`);
+      }
+      const status = res.status;
+      if ((status === 303 && method !== 'GET' && method !== 'HEAD') || ((status === 301 || status === 302) && method === 'POST')) {
+        method = 'GET';
+        body = undefined;
+        headers = new Headers(headers);
+        for (const name of BODY_HEADERS) headers.delete(name);
+      }
+      if (next.origin !== new URL(href).origin) {
+        headers = new Headers(headers);
+        headers.delete('authorization');
+      }
+      href = next.href;
+    }
+  };
+}
+
+async function readBody(res) {
+  if (res == null) return null;
+  if (typeof res.arrayBuffer === 'function') return res.arrayBuffer();
+  return res.body ?? null;
+}
+
+/**
+ * The host-side sender for a validated `network`: the policy in front of the
+ * host's (or the platform's) fetch.
+ */
+function createNetworkSender({ hostFetch, allowedHosts }) {
+  if (allowedHosts === ANY_HOST) return resolveFetch(hostFetch);
+  if (typeof allowedHosts === 'function') return createPolicyFetch(allowedHosts, hostFetch);
+  return createNetworkFetch(allowedHosts, hostFetch);
+}
+
+/**
+ * Validate `createSandbox({ network })` and build the host-side `fetch`
+ * capability behind the sandbox's global `fetch` shim.
+ *
+ * Everything that arrives from the sandbox is treated as untrusted input
+ * (evaluated code can also call `host.call('fetch', url, init)` directly):
+ * the URL must be http(s) and pass `allowedHosts` before the host's `fetch`
+ * is called, only method/headers/body/redirect are taken from the request,
+ * and `credentials` and `signal` are always set by the host.
+ *
+ * @param {{ allowedHosts: string[] | '*' | ((url: URL) => boolean | Promise<boolean>), fetch?: Function, credentials?: RequestCredentials }} network
+ * @returns {(this: { signal?: AbortSignal }, url: unknown, init?: unknown) => Promise<object>}
+ */
+export function createFetchCapability(network) {
+  const options = validateNetworkOptions(network);
+  const { credentials } = options;
+  const send = createNetworkSender(options);
 
   return async function fetchCapability(url, init) {
     if (typeof url !== 'string') throw new TypeError('fetch: the URL must be a string');

package/src/sandbox.mjs

@@ -18,7 +18,7 @@ import { makeDeferred, makeTimeoutError, makeAbortError } from './deferred.mjs';
 import { DEFAULT_TIMEOUT_MS } from './constants.mjs';
 import { isNodeRuntime, createNodeWorkerFactory } from './node-worker.mjs';
 import { normalizeIframeOptions, createIframeFactory, makeIframeRuntimeSource } from './iframe-host.mjs';
-import { createFetchCapability } from './network-policy.mjs';
+import { createFetchCapability, validateNetworkOptions } from './network-policy.mjs';
 
 const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
 
@@ -313,7 +313,7 @@ async function createServiceWorkerSandbox(options = {}) {
  * @property {string[]} [iframeSandbox] - mode: 'iframe': extra sandbox tokens ('allow-same-origin' needs dangerouslyAllowSameOrigin)
  * @property {boolean} [dangerouslyAllowSameOrigin] - mode: 'iframe': permit 'allow-same-origin' (removes the origin boundary)
  * @property {(iframe: HTMLIFrameElement) => void} [onFrame] - mode: 'iframe': called with every new frame before it is attached
- * @property {{ fetch?: Function, allowedHosts?: string[], credentials?: RequestCredentials }} [network] - worker, node-worker and iframe modes: install a global `fetch` in the sandbox that goes through the host (andbox#39)
+ * @property {{ allowedHosts: string[] | '*' | ((url: URL) => boolean | Promise<boolean>), fetch?: Function, credentials?: RequestCredentials }} [network] - worker, node-worker and iframe modes: install a global `fetch` in the sandbox that goes through the host (andbox#39); `allowedHosts` is required (andbox#43)
  */
 
 const SUPPORTED_MODES = ['worker', 'node-worker', 'wasm', 'iframe', 'inline', 'data-uri', 'service-worker'];
@@ -357,6 +357,8 @@ export function createSandbox(options = {}) {
       (mode === 'wasm' ? " The wasm engine has no fetch; expose a capability and call it with host.call()." : '')
     );
   }
+  // Refuse a bad `network` (no allowedHosts, andbox#43) before starting anything.
+  if (options.network !== undefined) validateNetworkOptions(options.network);
   if (mode === 'inline') return createInlineSandbox(options);
   if (mode === 'data-uri') return createDataUriSandbox(options);
   if (mode === 'service-worker') return createServiceWorkerSandbox(options);