@johnhenry/andbox 0.0.10 → 0.1.1

package/README.md

@@ -257,6 +257,8 @@ Creates a new sandboxed runtime. Returns a promise (Worker mode) or object (inli
 | `capabilities` | `Record<string, Function>` | `{}` | Host functions callable via `host.call()` (Worker mode) |
 | `defaultTimeoutMs` | `number` | `30000` | Default timeout for `evaluate()` |
 | `baseURL` | `string` | `location.href` | Base URL for relative imports |
+| `allowedImportHosts` | `string[]` | unset | Restricts `sandboxImport()` of remote `http(s)` modules to these hostnames (plus `baseURL`'s own host). **Unset: remote imports are allowed.** Provided: only listed hosts; `[]` denies all remote imports. Import-map targets are host-authored and always allowed. |
+| `untrusted` | `boolean` | `false` | Convenience for untrusted code: selects `mode: 'wasm'`. Throws if combined with another `mode`, and rejects (never falls back to a Worker) if wasm mode is unavailable. See [Security model](#security-model). |
 | `policy` | `GatePolicy` | -- | Rate limiting policy |
 | `onConsole` | `(level, ...args) => void` | -- | Console output handler |
 | `globals` | `Record<string, any>` | `{}` | Global variables (inline/data-uri modes) |
@@ -421,6 +423,11 @@ Code runs inside a Web Worker created from a Blob URL. This gets you, for free,
 
 andbox is **not** a boundary against code that is actively trying to escape it. If you're running code you don't fully trust, read this section before you rely on `capabilities`/`policy`/`createNetworkFetch` for anything.
 
+**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.
+- **`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:**
 
 - **No DOM access.** Worker-mode code executes in a real Worker global scope, which has no `document`, `window`, or other DOM references -- this is a platform property of Workers, not something andbox has to enforce itself.
@@ -433,13 +440,13 @@ andbox is **not** a boundary against code that is actively trying to escape it.
 
 **What is still yours:**
 
-- **Worker-global APIs are directly reachable, regardless of `capabilities`.** Sandboxed code executes in a real Worker global scope, so `fetch`, `WebSocket`, `Worker` (nested workers), `importScripts`, `indexedDB`, and `self.postMessage` are all callable directly -- omitting a `fetch` capability does not block network access. This is fundamental to how `Function`-based evaluation works and isn't fixable without a different execution strategy: [`mode: 'wasm'`](#mode-wasm) is that strategy (QuickJS in WebAssembly, no ambient authority), and a cross-origin iframe with a strict CSP is another. See [andbox#10](https://github.com/johnhenry/andbox/issues/10).
-- **`sandboxImport()` will load and execute an arbitrary remote URL.** Any `http(s)://` specifier is passed straight to `import()` with no allowlist, independent of any network policy configured for capabilities. See [andbox#7](https://github.com/johnhenry/andbox/issues/7).
+- **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: '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).
 
-If you need to run untrusted/adversarial code safely, andbox alone is not sufficient -- pair it with OS-level isolation (a separate process/container with its own network and filesystem restrictions) or use a purpose-built sandboxing runtime. Capability gating and rate limits here are for organizing and throttling code you already trust, not for containing code you don't.
+If you need to run untrusted/adversarial code, use `createSandbox({ untrusted: true })` (`mode: 'wasm'`) and, for hostile multi-tenant workloads, pair it with OS-level isolation (a separate process/container with its own network and filesystem restrictions) or use a purpose-built sandboxing runtime. Capability gating and rate limits here are for organizing and throttling code you already trust, not for containing code you don't.
 
 ## Threat model by mode
 
@@ -448,9 +455,9 @@ What each mode is built to stop, and what it is not. "Hostile" means code active
 | | `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`** | Possible. They are Worker globals the code can call. | Not possible. The engine has no such globals, and `constructor`/`eval`/`Function` chains only reach the guest realm. |
-| **Forging protocol messages to the host** | Possible in principle (`self.postMessage`); ids are random, which only slows a guess. | Not possible. The guest has no `postMessage` or `self`. |
-| **`sandboxImport` of arbitrary URLs / Node builtins** | Loaded and executed (browser) or blocked only with `nodeWorker.permissions` (Node). | Refused: only virtual modules resolve; no URL is fetched. |
+| **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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/andbox",
-  "version": "0.0.10",
+  "version": "0.1.1",
   "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

@@ -397,6 +397,20 @@ export interface SandboxOptions {
    * a live sandbox keeps the process alive until dispose().
    */
   unref?: boolean;
+  /**
+   * Hostnames `sandboxImport()` may load remote http(s) modules from, in
+   * addition to the host of `baseURL`. Unset (default): remote imports are
+   * allowed. Provided: only these hosts; `[]` denies all remote imports.
+   * Import-map targets and virtual modules are not affected. Does not
+   * restrict the platform `import()` operator in worker mode.
+   */
+  allowedImportHosts?: string[];
+  /**
+   * Convenience for untrusted code: selects `mode: 'wasm'`. Throws if `mode`
+   * is set to anything else; rejects (never falls back to a Worker) when
+   * wasm mode is unavailable.
+   */
+  untrusted?: boolean;
 }
 
 /** Options for the built-in Node worker_threads mode (`nodeWorker`). */

package/src/sandbox.mjs

@@ -316,6 +316,22 @@ const SUPPORTED_MODES = ['worker', 'node-worker', 'wasm', 'inline', 'data-uri',
  * @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 }>}
  */
 export function createSandbox(options = {}) {
+  if (options.untrusted === true) {
+    // Convenience for untrusted code: always the WebAssembly engine, never a
+    // silent downgrade to a Worker (andbox#10).
+    if (options.mode !== undefined && options.mode !== 'wasm') {
+      throw new Error(
+        `createSandbox({ untrusted: true }) requires mode: 'wasm' (got '${String(options.mode)}'); ` +
+        'worker and inline modes are not a boundary for untrusted code.'
+      );
+    }
+    return Promise.resolve(createSandbox({ ...options, untrusted: false, mode: 'wasm' })).catch((err) => {
+      throw new Error(
+        `createSandbox({ untrusted: true }) needs mode: 'wasm', which is unavailable here: ${err?.message ?? err}`,
+        { cause: err }
+      );
+    });
+  }
   const mode = options.mode ?? 'worker';
   if (!SUPPORTED_MODES.includes(mode)) {
     throw new Error(
@@ -402,8 +418,16 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
     onConsole,
     nodeWorker,
     unref = false,
+    allowedImportHosts,
   } = options;
 
+  // undefined = unset: remote imports allowed. An array (even empty) restricts.
+  if (allowedImportHosts !== undefined &&
+      (!Array.isArray(allowedImportHosts) || !allowedImportHosts.every((h) => typeof h === 'string'))) {
+    throw new TypeError('allowedImportHosts must be an array of hostname strings');
+  }
+  const importHosts = allowedImportHosts === undefined ? null : allowedImportHosts.map((h) => h.toLowerCase());
+
   // Node mode: no global Worker (and no blob: worker URLs) -> node:worker_threads.
   // An explicit workerFactory always wins; 'node-worker' forces Node; the
   // default selects it only when there is no global Worker under Node.
@@ -561,6 +585,7 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
       type: 'configure',
       importMap,
       baseURL,
+      allowedImportHosts: importHosts,
       virtualModules: Object.fromEntries(virtualModules),
       ...(wasmConfig ? { wasm: { ...wasmConfig.engine, memoryBytes: wasmConfig.limits.memoryBytes } } : {}),
     });

package/src/worker-source.mjs

@@ -32,12 +32,50 @@ export function makeWorkerSource() {
 // ── State ──
 let importMap = { imports: {}, scopes: {} };
 let baseURL = 'https://andbox.local/';
+let allowedImportHosts = null; // null = unset: remote imports allowed
 const virtualModules = new Map();
 // Node mode only: the adapter provides a loader that lets virtual modules
 // import each other. Captured once and removed from the global scope.
 const nodeVirtual = globalThis.__andboxNodeVirtual;
 try { delete globalThis.__andboxNodeVirtual; } catch {}
 
+// ── Worker-global lockdown (andbox#10, hardening only) ──
+// Capture what the runtime needs, then remove the ambient network/worker APIs
+// so evaluated code does not get them by name, via globalThis, via indirect
+// eval or via Function. This is NOT a security boundary: the platform \`import()\`
+// operator, Atomics/timing channels and, under Node, \`process\`/\`require\` stay
+// reachable. Use mode: 'wasm' (or an OS-level boundary) for hostile code.
+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',
+];
+for (const k of LOCKED_GLOBALS) {
+  try { delete globalThis[k]; } catch {}
+  if (k in globalThis) {
+    try { Object.defineProperty(globalThis, k, { value: undefined, writable: false, configurable: false }); } catch {}
+  }
+}
+// Names shadowed lexically for evaluated code as well (covers environments
+// where a global could not be deleted).
+const SHADOWED = [...LOCKED_GLOBALS, 'window'];
+
+// ── Remote import policy (andbox#7) ──
+function assertImportAllowed(href) {
+  if (allowedImportHosts === null) return;
+  let u;
+  try { u = new URL(href); } catch { return; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return;
+  const host = u.hostname.toLowerCase();
+  let baseHost = '';
+  try { baseHost = new URL(baseURL).hostname.toLowerCase(); } catch {}
+  if (host === baseHost || allowedImportHosts.includes(host)) return;
+  throw new Error(\`Import denied: \${host} is not in allowedImportHosts\`);
+}
+
 // ── Import Map Resolver (inlined) ──
 function resolveWithImportMap(specifier, map, parentURL) {
   if (!map) return null;
@@ -93,11 +131,13 @@ async function sandboxImport(specifier) {
   // 3. Relative/absolute URL — resolve against baseURL
   if (specifier.startsWith('./') || specifier.startsWith('../') || specifier.startsWith('/')) {
     const resolved = new URL(specifier, baseURL).href;
+    assertImportAllowed(resolved);
     return await import(resolved);
   }
 
   // 4. Absolute URL passthrough
   if (specifier.startsWith('http://') || specifier.startsWith('https://')) {
+    assertImportAllowed(specifier);
     return await import(specifier);
   }
 
@@ -113,7 +153,7 @@ function callCapability(name, args) {
   const id = crypto.randomUUID();
   return new Promise((resolve, reject) => {
     pendingRpc.set(id, { resolve, reject });
-    self.postMessage({ type: 'capabilityCall', id, name, args });
+    post({ type: 'capabilityCall', id, name, args });
   });
 }
 
@@ -135,7 +175,7 @@ function makeForwardingConsole(evalId) {
             try { return typeof a === 'object' ? JSON.stringify(a) : String(a); }
             catch { return String(a); }
           });
-          self.postMessage({ type: 'console', evalId, level: prop, args: serialized });
+          post({ type: 'console', evalId, level: prop, args: serialized });
         };
       }
       return target[prop];
@@ -144,23 +184,24 @@ function makeForwardingConsole(evalId) {
 }
 
 // ── Message Handler ──
-self.onmessage = async ({ data: msg }) => {
+scope.onmessage = async ({ data: msg }) => {
   switch (msg.type) {
     case 'configure': {
       if (msg.importMap) importMap = msg.importMap;
       if (msg.baseURL) baseURL = msg.baseURL;
+      if (Array.isArray(msg.allowedImportHosts)) allowedImportHosts = msg.allowedImportHosts;
       if (msg.virtualModules) {
         for (const [name, src] of Object.entries(msg.virtualModules)) {
           virtualModules.set(name, src);
         }
       }
-      self.postMessage({ type: 'configured' });
+      post({ type: 'configured' });
       break;
     }
 
     case 'defineModule': {
       virtualModules.set(msg.name, msg.source);
-      self.postMessage({ type: 'moduleDefined', name: msg.name });
+      post({ type: 'moduleDefined', name: msg.name });
       break;
     }
 
@@ -171,13 +212,14 @@ self.onmessage = async ({ data: msg }) => {
         // after the user code matter: without the trailing one, code ending in
         // a // line comment swallows the closing brace (andbox#23).
         const asyncFn = new Function(
-          'sandboxImport', 'host', 'console',
+          'sandboxImport', 'host', 'console', ...SHADOWED,
           \`return (async () => {\\n\${msg.code}\\n})();\`
         );
-        const result = await asyncFn(sandboxImport, host, fwdConsole);
-        self.postMessage({ type: 'result', id: msg.id, nonce: msg.nonce, success: true, value: serialize(result) });
+        // \`this\` is a throwaway object so a bare \`this\` is not the global.
+        const result = await asyncFn.call(Object.freeze(Object.create(null)), sandboxImport, host, fwdConsole);
+        post({ type: 'result', id: msg.id, nonce: msg.nonce, success: true, value: serialize(result) });
       } catch (e) {
-        self.postMessage({
+        post({
           type: 'result',
           id: msg.id,
           nonce: msg.nonce,
@@ -207,7 +249,7 @@ self.onmessage = async ({ data: msg }) => {
         reject(new Error('Sandbox disposed'));
       }
       pendingRpc.clear();
-      self.close();
+      closeSelf();
       break;
     }
   }