@johnhenry/andbox 0.0.3 → 0.0.5

package/README.md

@@ -85,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
@@ -111,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?)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/andbox",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "description": "Sandboxed JavaScript runtime with Worker isolation, RPC, import maps, and timeouts",
   "main": "./src/index.mjs",
@@ -41,5 +41,8 @@
   "homepage": "https://opensource.johnhenry.me/andbox/",
   "engines": {
     "node": ">=26.0.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2"
   }
 }

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,93 @@
+/**
+ * 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'.");
+  }
+  // Non-literal specifier: bundlers (webpack 5 fails on an unresolvable
+  // `node:` scheme) must not try to resolve this browser-irrelevant import.
+  const specifier = 'node:' + 'worker_threads';
+  const { Worker: ThreadWorker } = await import(/* @vite-ignore */ /* webpackIgnore: true */ specifier);
+  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':