@johnhenry/andbox 0.0.10 → 0.1.0

package/README.md

@@ -257,6 +257,7 @@ 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[]` | `[]` | Hostnames `sandboxImport()` may load remote `http(s)` modules from (besides `baseURL`'s own host). Import-map targets are host-authored and always allowed. Default: no remote imports. |
 | `policy` | `GatePolicy` | -- | Rate limiting policy |
 | `onConsole` | `(level, ...args) => void` | -- | Console output handler |
 | `globals` | `Record<string, any>` | `{}` | Global variables (inline/data-uri modes) |
@@ -433,8 +434,8 @@ 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 are deny-by-default (0.1.0), and only `sandboxImport()` is governed.** An absolute or protocol-relative `http(s)` specifier is refused (`Import denied: <host> is not in allowedImportHosts`) unless its hostname is in `allowedImportHosts` or is `baseURL`'s own host. 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).
@@ -448,9 +449,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 refused unless listed in `allowedImportHosts`; 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.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

@@ -397,6 +397,13 @@ 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`. Default `[]`: remote imports are
+   * refused. Import-map targets and virtual modules are not affected. Does
+   * not restrict the platform `import()` operator in worker mode.
+   */
+  allowedImportHosts?: string[];
 }
 
 /** Options for the built-in Node worker_threads mode (`nodeWorker`). */

package/src/sandbox.mjs

@@ -402,8 +402,14 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
     onConsole,
     nodeWorker,
     unref = false,
+    allowedImportHosts = [],
   } = options;
 
+  if (!Array.isArray(allowedImportHosts) || !allowedImportHosts.every((h) => typeof h === 'string')) {
+    throw new TypeError('allowedImportHosts must be an array of hostname strings');
+  }
+  const importHosts = 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 +567,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,49 @@ export function makeWorkerSource() {
 // ── State ──
 let importMap = { imports: {}, scopes: {} };
 let baseURL = 'https://andbox.local/';
+let allowedImportHosts = [];
 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) {
+  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 +130,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 +152,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 +174,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 +183,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 +211,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 +248,7 @@ self.onmessage = async ({ data: msg }) => {
         reject(new Error('Sandbox disposed'));
       }
       pendingRpc.clear();
-      self.close();
+      closeSelf();
       break;
     }
   }