@johnhenry/andbox 0.0.2 → 0.0.4

package/README.md

@@ -1,5 +1,11 @@
 # andbox
 
+[![npm version](https://img.shields.io/npm/v/%40johnhenry%2Fandbox.svg)](https://www.npmjs.com/package/@johnhenry/andbox)
+[![CI](https://github.com/johnhenry/andbox/actions/workflows/ci.yml/badge.svg)](https://github.com/johnhenry/andbox/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/%40johnhenry%2Fandbox.svg)](LICENSE)
+
+Full documentation: [opensource.johnhenry.me/andbox](https://opensource.johnhenry.me/andbox/)
+
 A separate-context JavaScript runtime with Worker isolation, RPC capabilities, import maps, and timeouts.
 
 andbox runs JavaScript in a dedicated Web Worker with a structured bridge back to the host. Code in that Worker can call host-provided "capabilities" via RPC, use import-mapped packages, and define virtual modules -- all with configurable rate limits, timeouts, and hard-kill semantics.
@@ -8,6 +14,17 @@ andbox runs JavaScript in a dedicated Web Worker with a structured bridge back t
 
 Zero dependencies. Uses only Web Workers and standard browser APIs.
 
+## Contents
+
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Sandbox Modes](#sandbox-modes)
+- [API](#api)
+- [Execution model](#execution-model)
+- [Security model](#security-model)
+- [Family](#family)
+- [License](#license)
+
 ## Install
 
 ```bash
@@ -68,11 +85,12 @@ await sandbox.dispose();
 
 ## Sandbox Modes
 
-andbox supports four execution modes:
+andbox supports five execution modes:
 
 - **`worker`** (default) -- Runs in a dedicated Worker with an RPC bridge, import maps, virtual modules, and hard-kill timeout semantics. See [Security model](#security-model) for what this does and doesn't protect against.
+- **`node-worker`** -- The `worker` mode on `node:worker_threads`. Selected automatically under Node when there is no global `Worker`; see [Node](#node).
 - **`inline`** -- Same-thread execution via AsyncFunction. Lighter weight, no Worker overhead, no isolation at all -- code runs with full access to the calling context. Only for code you already trust.
-- **`data-uri`** -- Dynamic `import()` via Blob URL. Module-level separation without a Worker. Supports globals injection.
+- **`data-uri`** -- Dynamic `import()` via Blob URL (a `data:` URL under Node). Module-level separation without a Worker. Supports globals injection.
 - **`service-worker`** -- Not code execution at all: registers a Service Worker that serves an in-memory `path → content` map with real HTTP-shaped fetch/navigation semantics. For hosting a small virtual multi-file site (HTML/CSS/JS, arbitrary paths), not for running JS in isolation. See [andbox#14](https://github.com/johnhenry/andbox/issues/14) and [Security model](#security-model) -- this mode does **not** provide isolation by merely existing.
 
 ```js
@@ -94,6 +112,27 @@ const site = await createSandbox({
 // Only navigate into scope *after* this resolves -- see Security model.
 ```
 
+## Node
+
+From 0.0.4 no shim is needed. Under Node (`engines >= 26`), `createSandbox()` just works:
+
+```js
+import { createSandbox } from '@johnhenry/andbox';
+const sandbox = await createSandbox({ capabilities: { now: () => Date.now() } });
+await sandbox.evaluate('return await host.call("now")');
+await sandbox.dispose(); // worker threads keep the process alive until disposed
+```
+
+**Mode selection.** `mode: 'worker'` (the default) picks `node:worker_threads` when `typeof Worker === 'undefined'` and the runtime is Node; if a global `Worker` exists (browser, or a shim you installed) that is used as before. `mode: 'node-worker'` forces the Node implementation. `workerFactory: (source) => WorkerLike` overrides both; `createNodeWorkerFactory()` is exported for that purpose.
+
+**How it works.** The same worker script the browser uses is passed to `new worker_threads.Worker(prelude + source, { eval: true })`. No blob URLs are created. The prelude maps `parentPort` to `self.postMessage`/`onmessage`/`close`, and makes the worker's virtual-module loader mint `data:` URLs (Node cannot `import()` a `blob:` URL). `node:worker_threads` is loaded with a dynamic `import()` so browser bundles never see a `node:` specifier. Timeouts, `AbortSignal`, and `dispose()` hard-kill the thread with `terminate()` and a fresh one is started on the next call.
+
+**Not supported / differences.**
+
+- `mode: 'service-worker'` needs a browser and rejects under Node.
+- Virtual modules are `data:` modules, so they cannot use *relative* imports of each other; use import maps or `sandboxImport()`. `createVirtualModuleRegistry()` still works as a path table in Node, but its `blob:` URLs cannot be `import()`ed there.
+- A worker thread is not a security boundary: it shares the process, and sandboxed code can reach `process` and `require`. Treat it like the browser Worker mode, which also is not a defense against hostile code (see [Security model](#security-model)); for untrusted code on a server add OS-level isolation.
+
 ## API
 
 ### `createSandbox(options?)`
@@ -266,7 +305,18 @@ Code runs inside a Web Worker created from a Blob URL. This gets you, for free,
 
 ## Security model
 
-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 -- every item below is a confirmed way sandboxed code can act outside what `capabilities`/`policy`/`createNetworkFetch` appear to allow:
+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.
+
+**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.
+- **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.
+- **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).
+- **`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.
+
+**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 (e.g. a cross-origin iframe with a strict CSP, or a Realms/Compartments-based approach). 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).
@@ -274,12 +324,22 @@ andbox is **not** a boundary against code that is actively trying to escape it.
 - **`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).
 
-Fixed as of this audit (kept here for history -- see the linked issues for details):
+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.
 
-- ~~`gateCapabilities()`'s check could be bypassed via the prototype chain~~ (`host.call('constructor', ...)` resolved through `Object.prototype` to the real global `Object` constructor). Fixed by building the gated object with `Object.create(null)`. See [andbox#5](https://github.com/johnhenry/andbox/issues/5).
-- ~~`createNetworkFetch()`'s allowlist was not redirect-safe~~ (it checked the request hostname before the fetch, not the final response URL). Fixed by fetching with `redirect: 'manual'` and rejecting any redirect response outright. See [andbox#6](https://github.com/johnhenry/andbox/issues/6).
+## Family
 
-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.
+andbox isn't just a standalone sandbox runtime -- it's the sandboxing engine
+that [aimatey](https://github.com/johnhenry/aimatey) middleware wires in for
+code-based tool execution.
+
+- **[`@johnhenry/aimatey-middleware-andbox`](https://github.com/johnhenry/aimatey-middleware-andbox)** --
+  wires andbox's `createSandbox()` factory (or a pre-built sandbox) into an
+  [aimatey](https://github.com/johnhenry/aimatey) bridge middleware, via
+  `toolsToCapabilities()` to convert the middleware's `tools`/`executeToolFn`
+  into andbox `capabilities`. This package's own [Security model](#security-model)
+  is the source of truth for what that capability gate does and does not
+  guarantee -- the middleware's Security model section points back here
+  rather than repeating it.
 
 ## License
 

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@johnhenry/andbox",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "type": "module",
   "description": "Sandboxed JavaScript runtime with Worker isolation, RPC, import maps, and timeouts",
   "main": "./src/index.mjs",
+  "types": "./src/index.d.ts",
   "exports": {
-    ".": "./src/index.mjs"
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs"
+    }
   },
   "files": [
     "src",
@@ -36,6 +40,6 @@
   },
   "homepage": "https://opensource.johnhenry.me/andbox/",
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=26.0.0"
   }
 }

package/src/index.d.ts

@@ -305,8 +305,36 @@ export interface SandboxOptions {
   policy?: GatePolicy;
   /** Console output handler. Called when sandboxed code uses console.log/warn/error/etc. */
   onConsole?: (level: string, ...args: string[]) => void;
+  /**
+   * Worker mode selection. Omitted/`'worker'` uses a Web Worker, or
+   * `node:worker_threads` automatically when run under Node with no global
+   * `Worker`. `'node-worker'` forces the Node implementation.
+   */
+  mode?: 'worker' | 'node-worker';
+  /**
+   * Supply the Worker implementation: given the worker script source, return
+   * a Web-Worker-shaped object. Overrides automatic selection. See
+   * `createNodeWorkerFactory()`.
+   */
+  workerFactory?: (source: string) => WorkerLike;
 }
 
+/** The subset of the Web Worker interface andbox drives. */
+export interface WorkerLike {
+  onmessage: ((ev: { data: any }) => void) | null;
+  onerror: ((ev: { message?: string }) => void) | null;
+  postMessage(message: unknown): void;
+  addEventListener(type: 'message', fn: (ev: { data: any }) => void): void;
+  removeEventListener(type: 'message', fn: (ev: { data: any }) => void): void;
+  terminate(): void;
+}
+
+/**
+ * Node only: load `node:worker_threads` and return a synchronous factory that
+ * runs andbox's worker source in a thread. Suitable for `workerFactory`.
+ */
+export declare function createNodeWorkerFactory(): Promise<(source: string) => WorkerLike>;
+
 /** Sandbox statistics. */
 export interface SandboxStats {
   disposed: boolean;

package/src/index.mjs

@@ -15,3 +15,4 @@ export { DEFAULT_TIMEOUT_MS, DEFAULT_LIMITS, DEFAULT_CAPABILITY_LIMITS } from '.
 export { makeWorkerSource } from './worker-source.mjs';
 export { makeServiceWorkerSource } from './service-worker-source.mjs';
 export { resolveServiceWorkerResponse } from './service-worker-response.mjs';
+export { createNodeWorkerFactory } from './node-worker.mjs';

package/src/node-worker.mjs

@@ -0,0 +1,90 @@
+/**
+ * Node adapter: a Web-Worker-shaped object on top of `node:worker_threads`.
+ *
+ * The browser path builds a Blob URL and passes it to `new Worker(url)`.
+ * Node has no global `Worker`, `worker_threads` cannot start from a `blob:`
+ * URL, and the ESM loader cannot `import()` one. So in Node the worker
+ * source is passed as text with `{ eval: true }` (the thread starts as a
+ * CommonJS script, which is all the worker source needs), preceded by a
+ * small prelude that maps `parentPort` onto `self.postMessage` /
+ * `self.onmessage` / `self.close`, and shims `Blob` + `URL.createObjectURL`
+ * *inside the thread only* so the worker's virtual-module loader mints
+ * `data:` URLs (which Node can `import()`) instead of `blob:` URLs. The
+ * worker source itself is the same string the browser uses.
+ *
+ * `node:worker_threads` is loaded with a dynamic `import()` so the browser
+ * entry never pulls a `node:` specifier into a bundle's static graph.
+ */
+
+const PRELUDE = `
+const { parentPort } = require('node:worker_threads');
+globalThis.self = globalThis;
+globalThis.postMessage = (m) => parentPort.postMessage(m);
+globalThis.close = () => process.exit(0);
+parentPort.on('message', (data) => {
+  try { const r = globalThis.onmessage?.({ data }); r?.catch?.((e) => { throw e; }); }
+  catch (e) { parentPort.postMessage({ type: 'error', message: String(e?.message ?? e) }); }
+});
+// import(blob:) is unsupported by Node's ESM loader; data: works.
+globalThis.Blob = class AndboxNodeBlob {
+  constructor(parts) { this.text = parts.map(String).join(''); }
+};
+URL.createObjectURL = (b) => 'data:text/javascript;base64,' + Buffer.from(b.text).toString('base64');
+URL.revokeObjectURL = () => {};
+`;
+
+class NodeWebWorker {
+  #thread;
+  #listeners = new Set();
+  #terminated = false;
+  onmessage = null;
+  onerror = null;
+
+  constructor(ThreadWorker, source) {
+    const w = new ThreadWorker(PRELUDE + '\n' + source, { eval: true });
+    w.on('message', (data) => {
+      const ev = { data };
+      this.onmessage?.(ev);
+      for (const fn of [...this.#listeners]) fn(ev);
+    });
+    w.on('error', (e) => this.onerror?.({ message: e?.message ?? String(e) }));
+    w.on('exit', (code) => {
+      if (!this.#terminated && code !== 0) {
+        this.onerror?.({ message: `worker exited with code ${code}` });
+      }
+    });
+    this.#thread = w;
+  }
+
+  postMessage(m) {
+    if (!this.#terminated) this.#thread.postMessage(m);
+  }
+  addEventListener(type, fn) { if (type === 'message') this.#listeners.add(fn); }
+  removeEventListener(type, fn) { if (type === 'message') this.#listeners.delete(fn); }
+  terminate() {
+    this.#terminated = true;
+    this.#listeners.clear();
+    this.#thread.terminate();
+  }
+}
+
+/** True when running under Node (including with no global `Worker`). */
+export function isNodeRuntime() {
+  return typeof process !== 'undefined' && typeof process?.versions?.node === 'string';
+}
+
+/**
+ * Load `node:worker_threads` and return a synchronous factory
+ * `(workerSource: string) => Worker-like` (onmessage/onerror/postMessage/
+ * addEventListener/removeEventListener/terminate). Pass it as the
+ * `workerFactory` option of `createSandbox()` to force it explicitly.
+ *
+ * @returns {Promise<(source: string) => object>}
+ */
+export async function createNodeWorkerFactory() {
+  if (!isNodeRuntime()) {
+    throw new Error("createNodeWorkerFactory() requires Node (node:worker_threads); in a browser use mode: 'worker'.");
+  }
+  const { Worker: ThreadWorker } = await import('node:worker_threads');
+  return (source) => new NodeWebWorker(ThreadWorker, source);
+}

package/src/sandbox.mjs

@@ -14,6 +14,7 @@ import { makeWorkerSource } from './worker-source.mjs';
 import { gateCapabilities } from './capability-gate.mjs';
 import { makeDeferred, makeTimeoutError, makeAbortError } from './deferred.mjs';
 import { DEFAULT_TIMEOUT_MS } from './constants.mjs';
+import { isNodeRuntime, createNodeWorkerFactory } from './node-worker.mjs';
 
 const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
 
@@ -62,7 +63,7 @@ function createDataUriSandbox(opts = {}) {
       const output = [];
       const globalEntries = Object.entries(globals);
       const preamble = globalEntries.length > 0
-        ? `const { ${globalEntries.map(([k]) => k).join(', ')} } = globalThis.__andbox_globals__;\n`
+        ? `const { ${globalEntries.map(([k]) => k).join(', ')} } = __globals__;\n`
         : '';
       const wrappedCode = `
 const __globals__ = globalThis.__andbox_globals__;
@@ -70,8 +71,11 @@ const print = globalThis.__andbox_print__;
 delete globalThis.__andbox_globals__;
 delete globalThis.__andbox_print__;
 ${preamble}${code}`;
-      const blob = new Blob([wrappedCode], { type: 'text/javascript' });
-      const url = URL.createObjectURL(blob);
+      // Node's ESM loader cannot import() a blob: URL; it can a data: URL.
+      const nodeRuntime = isNodeRuntime();
+      const url = nodeRuntime
+        ? 'data:text/javascript;base64,' + Buffer.from(wrappedCode).toString('base64')
+        : URL.createObjectURL(new Blob([wrappedCode], { type: 'text/javascript' }));
       const print = (...args) => {
         output.push(args.map(a => typeof a === 'string' ? a : JSON.stringify(a)).join(' '));
       };
@@ -92,7 +96,7 @@ ${preamble}${code}`;
         return { success: false, output: output.join('\n'), error: e.message || String(e) };
       } finally {
         clearTimeout(timer);
-        URL.revokeObjectURL(url);
+        if (!nodeRuntime) URL.revokeObjectURL(url);
         delete globalThis.__andbox_globals__;
         delete globalThis.__andbox_print__;
       }
@@ -314,10 +318,10 @@ export function createSandbox(options = {}) {
   if (mode === 'inline') return createInlineSandbox(options);
   if (mode === 'data-uri') return createDataUriSandbox(options);
   if (mode === 'service-worker') return createServiceWorkerSandbox(options);
-  return createWorkerSandbox(options);
+  return createWorkerSandbox(options, mode === 'node-worker');
 }
 
-async function createWorkerSandbox(options = {}) {
+async function createWorkerSandbox(options = {}, forceNode = false) {
   const {
     importMap = { imports: {}, scopes: {} },
     capabilities = {},
@@ -327,6 +331,14 @@ async function createWorkerSandbox(options = {}) {
     onConsole,
   } = options;
 
+  // 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.
+  let workerFactory = options.workerFactory || null;
+  if (!workerFactory && (forceNode || (typeof Worker === 'undefined' && isNodeRuntime()))) {
+    workerFactory = await createNodeWorkerFactory();
+  }
+
   // Gate capabilities with rate limits
   const { gated: gatedCaps, stats: gateStats } = gateCapabilities(capabilities, policy);
 
@@ -346,10 +358,18 @@ async function createWorkerSandbox(options = {}) {
 
   function createWorker() {
     const source = makeWorkerSource();
+    if (workerFactory) {
+      worker = workerFactory(source);
+      attachWorkerHandlers();
+      return;
+    }
     const blob = new Blob([source], { type: 'application/javascript' });
     workerBlobURL = URL.createObjectURL(blob);
     worker = new Worker(workerBlobURL, { type: 'classic' });
+    attachWorkerHandlers();
+  }
 
+  function attachWorkerHandlers() {
     worker.onmessage = ({ data: msg }) => {
       switch (msg.type) {
         case 'configured':