@johnhenry/andbox 0.0.8 → 0.0.10

package/README.md

@@ -427,7 +427,7 @@ andbox is **not** a boundary against code that is actively trying to escape it.
 - **No implicit host object references.** Only what you explicitly pass in (`capabilities`, `globals`, import map entries) is reachable from sandboxed code -- ordinary (non-adversarial) code cannot accidentally read or mutate host-side state it wasn't given a reference to.
 - **(Node) A worker thread is not a security boundary.** It shares the process with the host; by default it inherits `process.env` and can reach `process`, `fs`, and `child_process`. The opt-in `nodeWorker.permissions` hardening (see [Node](#node)) adds the permission model, an isolated env, a memory cap and import blocking, which raises the cost of casual abuse but does not make the thread a boundary.
 - **Hard kill on timeout.** `evaluate()` calls that exceed `timeoutMs` `terminate()` the Worker outright and start a fresh one for the next call -- this is a real process-level kill, not a cooperative cancellation the running code could ignore. See "still yours" below for what a kill does *not* undo.
-- **The capability gate cannot be walked around via the prototype chain.** `gateCapabilities()` builds the gated object with `Object.create(null)`, so `host.call('constructor', ...)` cannot resolve through `Object.prototype` to the real global `Object` constructor. Previously fixed; see [andbox#5](https://github.com/johnhenry/andbox/issues/5).
+- **The capability gate cannot be walked around via the prototype chain.** `gateCapabilities()` builds the gated object with `Object.create(null)`, so `host.call('constructor', ...)` cannot resolve through `Object.prototype` to the real global `Object` constructor; the host resolves names through a `Map` and rejects anything that was not explicitly granted. First fixed in 0.0.1, hardened in 0.0.9; see [andbox#5](https://github.com/johnhenry/andbox/issues/5).
 - **`createNetworkFetch()`'s allowlist is redirect-safe.** Requests are made with `redirect: 'manual'` and any redirect response is rejected outright, so an allowlisted host cannot silently redirect a caller to a non-allowlisted one. Previously fixed; see [andbox#6](https://github.com/johnhenry/andbox/issues/6).
 - **`gateCapabilities()` enforces call/argument-size/concurrency caps per capability**, for cooperative callers that stay within the capabilities you actually granted.
 
@@ -435,7 +435,7 @@ andbox is **not** a boundary against code that is actively trying to escape it.
 
 - **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).
+- **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).
 

package/package.json

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

@@ -21,11 +21,12 @@ import { DEFAULT_LIMITS, DEFAULT_CAPABILITY_LIMITS } from './constants.mjs';
  *
  * @param {Record<string, Function>} capabilities - Raw capability functions.
  * @param {GatePolicy} [policy] - Rate limit policy.
- * @returns {{ gated: Record<string, Function>, stats: () => object }}
+ * @returns {{ gated: Record<string, Function>, lookup: (name: unknown) => Function | undefined, stats: () => object }}
  */
 export function gateCapabilities(capabilities, policy = {}) {
   const limits = { ...DEFAULT_LIMITS, ...policy.limits };
   const capPolicies = policy.capabilities || {};
+  const hasOwn = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
 
   let totalCalls = 0;
   let totalArgBytes = 0;
@@ -41,11 +42,14 @@ export function gateCapabilities(capabilities, policy = {}) {
   // like 'constructor' or 'toString' cannot resolve through the prototype
   // to real global functions and bypass the allowlist/rate limiting below.
   const gated = Object.create(null);
+  // Authoritative table for lookup(): a Map has no prototype-chain property
+  // semantics at all, so a string key either was granted or is absent.
+  const table = new Map();
 
   for (const [name, fn] of Object.entries(capabilities)) {
-    const capLimits = { ...DEFAULT_CAPABILITY_LIMITS, ...capPolicies[name] };
+    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;
@@ -78,11 +82,23 @@ export function gateCapabilities(capabilities, policy = {}) {
       concurrent++;
 
       try {
-        return await fn(...args);
+        return await fn.apply(this, args);
       } finally {
         concurrent--;
       }
     };
+    table.set(name, gated[name]);
+  }
+
+  /**
+   * Resolve a capability by name. Only names the host explicitly granted
+   * resolve; non-strings and anything that exists only on Object.prototype
+   * (constructor, toString, __proto__, ...) return undefined.
+   * @param {unknown} name
+   * @returns {Function | undefined}
+   */
+  function lookup(name) {
+    return typeof name === 'string' ? table.get(name) : undefined;
   }
 
   function stats() {
@@ -94,5 +110,5 @@ export function gateCapabilities(capabilities, policy = {}) {
     };
   }
 
-  return { gated, stats };
+  return { gated, lookup, stats };
 }

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. */

package/src/sandbox.mjs

@@ -436,7 +436,7 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
   }
 
   // Gate capabilities with rate limits
-  const { gated: gatedCaps, stats: gateStats } = gateCapabilities(capabilities, policy);
+  const { lookup: lookupCapability, stats: gateStats } = gateCapabilities(capabilities, policy);
 
   // Console handler — mutable so evaluate() can swap per-call
   let activeConsoleHandler = onConsole || null;
@@ -446,6 +446,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 +469,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);
@@ -490,7 +493,7 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
 
         case 'result': {
           const entry = pending.get(msg.id);
-          if (entry) {
+          if (entry && entry.nonce === msg.nonce) {
             pending.delete(msg.id);
             if (entry.timer) clearTimeout(entry.timer);
             if (msg.stats) {
@@ -570,30 +573,45 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
   }
 
   async function handleCapabilityCall(rpcId, name, args) {
-    const fn = gatedCaps[name];
+    // 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;
@@ -637,6 +655,10 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
     // can't guess the id of a concurrent evaluate() on the same worker and
     // forge a matching message to interfere with it.
     const id = crypto.randomUUID();
+    // Per-call nonce: the worker echoes it in its `result`; a result whose
+    // nonce does not match is dropped. Held only by the host and the worker's
+    // message handler, never exposed to evaluated code.
+    const nonce = crypto.randomUUID() + crypto.randomUUID();
     const timeoutMs = opts.timeoutMs ?? defaultTimeoutMs;
     const { promise, resolve, reject } = makeDeferred();
 
@@ -691,8 +713,8 @@ async function createWorkerSandbox(options = {}, forceNode = false, isWasm = fal
       }, { once: true });
     }
 
-    pending.set(id, { resolve, reject, timer });
-    worker.postMessage({ type: 'evaluate', id, code, ...(wasmLimits ? { limits: wasmLimits } : {}) });
+    pending.set(id, { resolve, reject, timer, nonce });
+    worker.postMessage({ type: 'evaluate', id, nonce, code, ...(wasmLimits ? { limits: wasmLimits } : {}) });
 
     // Restore console handler when evaluation completes
     return promise.finally(() => {

package/src/wasm-worker-source.mjs

@@ -462,7 +462,7 @@ function wasmWorkerMain() {
       }
       case 'evaluate': {
         const res = await runEval(msg);
-        self.postMessage({ type: 'result', id: msg.id, ...res });
+        self.postMessage({ type: 'result', id: msg.id, nonce: msg.nonce, ...res });
         break;
       }
       case 'capabilityResult': {

package/src/worker-source.mjs

@@ -175,11 +175,12 @@ self.onmessage = async ({ data: msg }) => {
           \`return (async () => {\\n\${msg.code}\\n})();\`
         );
         const result = await asyncFn(sandboxImport, host, fwdConsole);
-        self.postMessage({ type: 'result', id: msg.id, success: true, value: serialize(result) });
+        self.postMessage({ type: 'result', id: msg.id, nonce: msg.nonce, success: true, value: serialize(result) });
       } catch (e) {
         self.postMessage({
           type: 'result',
           id: msg.id,
+          nonce: msg.nonce,
           success: false,
           error: { message: e.message || String(e), name: e.name || 'Error', stack: e.stack },
         });