@johnhenry/andbox 0.0.9 → 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,9 +434,9 @@ 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).
-- **A timeout stops message delivery, not in-flight host-side effects.** If a capability call with a real side effect (a write, an API call) is in flight when the timeout fires, that side effect still completes on the host even though the Worker is killed. Capabilities with real side effects should be designed to be idempotent and/or cancellable via `AbortSignal`. See [andbox#8](https://github.com/johnhenry/andbox/issues/8).
+- **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.9",
+  "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/capability-gate.mjs

@@ -49,7 +49,7 @@ export function gateCapabilities(capabilities, policy = {}) {
   for (const [name, fn] of Object.entries(capabilities)) {
     const capLimits = { ...DEFAULT_CAPABILITY_LIMITS, ...(hasOwn(capPolicies, name) ? capPolicies[name] : undefined) };
 
-    gated[name] = async (...args) => {
+    gated[name] = async function (...args) {
       // Measure argument bytes
       const argStr = JSON.stringify(args);
       const argBytes = new TextEncoder().encode(argStr).byteLength;
@@ -82,7 +82,7 @@ export function gateCapabilities(capabilities, policy = {}) {
       concurrent++;
 
       try {
-        return await fn(...args);
+        return await fn.apply(this, args);
       } finally {
         concurrent--;
       }

package/src/index.d.ts

@@ -310,12 +310,23 @@ export interface EvaluateOptions {
   deadlineMs?: number;
 }
 
+/**
+ * `this` inside a capability function (use a `function`, not an arrow).
+ * `signal` aborts when the sandbox's Worker is terminated (timeout, an
+ * aborted `evaluate()`, `dispose()`, crash); cooperative capabilities should
+ * pass it to whatever they are doing (`fetch(url, { signal })`, ...).
+ */
+export interface CapabilityContext {
+  signal: AbortSignal;
+  name: string;
+}
+
 /** Options for createSandbox(). */
 export interface SandboxOptions {
   /** Import map for module resolution inside the sandbox. */
   importMap?: ImportMap;
   /** Host functions callable from sandbox code via host.call(name, ...args). */
-  capabilities?: Record<string, (...args: any[]) => any>;
+  capabilities?: Record<string, (this: CapabilityContext, ...args: any[]) => any>;
   /** Default timeout in milliseconds for evaluate() calls. */
   defaultTimeoutMs?: number;
   /** Base URL for resolving relative imports inside the sandbox. */
@@ -386,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.
@@ -446,6 +452,8 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
   let disposed = false;
   let worker = null;
   let workerBlobURL = null;
+  // Lifetime of the current Worker; aborted when it is terminated.
+  let workerAbort = null;
 
   // `unref`: the thread only keeps the host process alive while work is in
   // flight (startup, evaluate, defineModule); idle, it lets the process exit.
@@ -467,6 +475,7 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
   // ── Worker lifecycle ──
 
   function createWorker() {
+    workerAbort = new AbortController();
     const source = isWasm ? makeWasmWorkerSource() : makeWorkerSource();
     if (workerFactory) {
       worker = workerFactory(source);
@@ -558,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 } } : {}),
     });
@@ -570,30 +580,45 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
   }
 
   async function handleCapabilityCall(rpcId, name, args) {
+    // Bind to the worker that made the call. If it is killed (timeout, abort,
+    // dispose, crash) while the capability is still running, the late result
+    // must be dropped: `worker` is then null or a *different* replacement
+    // thread that never asked for it (andbox#30).
+    const callerWorker = worker;
+    const callerSignal = workerAbort?.signal;
+    if (!callerWorker || !callerSignal) return;
+    const reply = (payload) => {
+      if (worker !== callerWorker || callerSignal.aborted) return;
+      try {
+        callerWorker.postMessage({ type: 'capabilityResult', id: rpcId, ...payload });
+      } catch {
+        // the thread went away between the check and the post: nothing to tell
+      }
+    };
+
     const fn = lookupCapability(name);
     if (!fn) {
-      worker.postMessage({
-        type: 'capabilityResult',
-        id: rpcId,
-        success: false,
-        error: `Unknown capability: ${name}`,
-      });
+      reply({ success: false, error: `Unknown capability: ${name}` });
       return;
     }
     try {
-      const value = await fn(...args);
-      worker.postMessage({ type: 'capabilityResult', id: rpcId, success: true, value });
+      // The signal travels as `this`, not as an argument, so capabilities
+      // with their own arity (Math.max, rest params, ...) are unaffected.
+      // It aborts when this Worker is terminated (andbox#8).
+      const value = await fn.call({ signal: callerSignal, name }, ...args);
+      reply({ success: true, value });
     } catch (e) {
-      worker.postMessage({
-        type: 'capabilityResult',
-        id: rpcId,
-        success: false,
-        error: e.message || String(e),
-      });
+      reply({ success: false, error: e?.message || String(e) });
     }
   }
 
   function terminateWorker() {
+    if (workerAbort) {
+      // Tell in-flight capability calls their caller is gone so cooperative
+      // ones can cancel the underlying effect (andbox#8).
+      workerAbort.abort(new Error('Sandbox worker terminated'));
+      workerAbort = null;
+    }
     if (worker) {
       worker.terminate();
       worker = null;

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;
     }
   }