@johnhenry/andbox 0.0.9 → 0.0.10

package/README.md

@@ -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.9",
+  "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

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

package/src/sandbox.mjs

@@ -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);
@@ -570,30 +573,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;