@johnhenry/andbox 0.0.5 → 0.0.6

package/README.md

@@ -85,7 +85,7 @@ await sandbox.dispose();
 
 ## Sandbox Modes
 
-andbox supports five execution modes:
+andbox supports five execution modes (any other `mode` throws an error listing these):
 
 - **`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).
@@ -125,13 +125,42 @@ 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.
+**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 installs an in-thread module loader hook (`module.registerHooks`) that serves virtual modules from memory (see below). `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.
+
+**Virtual modules can import each other (0.0.6).** `defineModule()` modules are served under `andbox-vfs://` URLs, so they can import one another relatively (`./b`, `../lib/c.js`), by bare name (`import x from "lib/x"`), through the sandbox `importMap`, and cyclically. Extensions are optional (`./b`, `./b.js`, `./b/index.js` all find `b`). Redefining a module (or a dependency) takes effect on the next `sandboxImport()`. Difference from the browser: modules are cached per definition, so repeated `sandboxImport(name)` returns the same module instance until it is redefined. `createVirtualModuleRegistry()` uses the same mechanism under Node (see its section).
+
+**Process lifetime.** A live worker thread keeps the host process alive until `dispose()` (confirmed by test: no `dispose()` and the process never exits; after `dispose()` it exits). Pass `unref: true` to let the process exit while the sandbox is *idle*: the thread is unref'd between calls and ref'd again while a startup, `evaluate()` or `defineModule()` is in flight, so an `await sandbox.evaluate(...)` is never abandoned. Default `false`. (Ignored with a browser Worker.)
+
+**Hardening (opt-in): `nodeWorker`.** By default the thread behaves like any `worker_threads` thread: it gets a copy of `process.env`, no memory cap, and full access to `process`, `fs`, `child_process`, etc. These options tighten that:
+
+```js
+const sandbox = await createSandbox({
+  nodeWorker: {
+    permissions: true,        // see below
+    // env: { MODE: 'x' },    // explicit env; with permissions the default is {}
+    // maxMemoryMb: 128,      // heap cap (default 256 with permissions: true)
+    // resourceLimits: {...}, // raw worker_threads resourceLimits, merged on top
+    // execArgv: [...],       // extra thread flags, e.g. '--allow-fs-read=/data'
+    // captureStdio: true,    // route thread stdout/stderr to onConsole('stdout'|'stderr', text)
+  },
+});
+```
+
+`permissions: true` does all of the following to the thread:
+
+- **Permission model.** Spawns it with `execArgv: ['--permission']` (this works per-thread in Node 26 even though the flag is documented process-wide). Verified by test: `fs` reads and `child_process` are denied with `ERR_ACCESS_DENIED`, Nested workers and native addons are not granted (`--allow-worker` / `--allow-addons` are not passed), though only the `fs` and `child_process` denials are covered by tests. Grant specific paths with `execArgv: ['--allow-fs-read=/dir']`.
+- **Isolated `env`.** `{}` (or the object you pass) instead of a copy of the host's environment, so secrets in `process.env` are not visible.
+- **Memory cap.** `resourceLimits.maxOldGenerationSizeMb` (default 256, or `maxMemoryMb`). An allocation loop kills the thread with an out-of-memory error, the pending `evaluate()` rejects, and the next call starts a fresh thread. (andbox has no other memory-limit option, so `maxMemoryMb` is new here; `policy.limits` only governs capability calls.)
+- **Stripped `process`.** Deletes `process.binding`, `_linkedBinding`, `getBuiltinModule`, `dlopen`, `kill`, `abort`, `reallyExit`, `mainModule`.
+- **Blocked host imports.** A resolve hook rejects any `import()` / `sandboxImport()` that resolves to a `node:` or `file:` URL (`import('node:fs')`, `import('fs')`, `import('file:///...')`). `data:`, `http(s):` and virtual modules still work.
+- **Captured stdio.** Thread `process.stdout/stderr` writes go to `onConsole` instead of the host terminal.
+
+**What this does *not* prevent.** The thread is still in your process. `permissions` does not restrict the network (`fetch`, `WebSocket`, `net` via any route that remains), CPU use (use `timeoutMs`), or anything that exploits a bug in V8 or Node; the `process` stripping and import hook are denylists, not a proof, and a determined attacker may find another path to a host capability. It only reduces the blast radius of ordinary and semi-hostile code. See [Security model](#security-model). The options throw if combined with a browser Worker or a custom `workerFactory`, rather than silently doing nothing.
 
 **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.
+- **A worker thread is not a security boundary** -- not by default and not with `nodeWorker.permissions`. By default sandboxed code can reach `process` (including `process.env`, `process.binding`, `process.getBuiltinModule('fs')`) and can `import('node:child_process')`. For untrusted code on a server add OS-level isolation (a separate process or container with its own filesystem, network and resource limits).
 
 ## API
 
@@ -204,7 +233,7 @@ Resolves a module specifier against an import map, following the browser import
 
 ### `createVirtualModuleRegistry(files?, options?)`
 
-Takes a `path → source` map and mints one real `blob:` URL per entry (the same `new Blob([...]) + URL.createObjectURL()` pattern `data-uri` mode uses, generalized to a whole file table). Returns a registry for a multi-file tree that references itself by relative path -- an entry module `import`-ing `./util.js`, which itself imports `../shared/x.js`, and so on.
+Takes a `path → source` map and mints one importable URL per entry: a real `blob:` URL in a browser (the same `new Blob([...]) + URL.createObjectURL()` pattern `data-uri` mode uses, generalized to a whole file table), or, under Node (which cannot `import()` a `blob:` URL), an `andbox-vfs://<id>/<path>?v=<n>` URL served by an in-thread module hook. `options.backend` is `'auto'` (default), `'blob'` or `'node'`. Returns a registry for a multi-file tree that references itself by relative path -- an entry module `import`-ing `./util.js`, which itself imports `../shared/x.js`, and so on.
 
 ```js
 import { createVirtualModuleRegistry } from '@johnhenry/andbox';
@@ -214,15 +243,18 @@ const registry = createVirtualModuleRegistry({
   'util.js': 'export function add(a, b) { return a + b; }',
 });
 
-registry.resolve('index.js');                       // blob: URL, or null if unknown
+registry.resolve('index.js');                       // importable URL, or null if unknown
+registry.source('index.js');                        // the registered source text
 registry.resolveSpecifier('./util.js', 'index.js');  // resolves relative to the importing file
 registry.define('extra.js', 'export const x = 1;');  // register (or replace) a file at runtime
-registry.dispose();                                  // revokes every blob URL it ever minted
+registry.dispose();                                  // revokes blob URLs / drops the Node files
 ```
 
 `resolveSpecifier(specifier, parentPath?)` checks, in order: (1) import-map resolution via `resolveWithImportMap()` -- not reimplemented, just delegated, with `parentPath`'s own blob URL passed through as `parentURL` so `scopes` apply; (2) a relative-path (`./`, `../`) fallback looked up against the registry's own file table, which `resolveWithImportMap()` alone has no notion of; (3) `null` if neither matched, e.g. a genuine external bare specifier -- left for the caller to handle, not swallowed.
 
-**Honest caveat:** this only solves module *resolution* (the URL a given specifier should point at), not automatic rewriting of `import` statements inside the source text, and not general asset URLs (`<img src>`, CSS `url()`) or navigation. A `blob:` URL has no hierarchical path of its own, so a literal `import "./util.js"` statement inside blob-served source will **not** resolve on its own in a browser -- call `resolveSpecifier()` yourself with the specifier your loader saw and use the URL it returns (or rewrite the specifier to that URL before creating the blob). See [andbox#13](https://github.com/johnhenry/andbox/issues/13) for the full design discussion, and [andbox#14](https://github.com/johnhenry/andbox/issues/14) for the harder "make it behave like a real server" problem this deliberately does not attempt to solve.
+**Under Node, relative imports just work.** `await import(registry.resolve('index.js'))` runs `index.js`, whose `./util.js` import is resolved by the hook (relative, bare-name, import map, cycles, and extensionless/`index.js` lookups). Redefine a file with `define()` and import the new URL it returns.
+
+**Honest caveat (browser / `blob:` backend):** this only solves module *resolution* (the URL a given specifier should point at), not automatic rewriting of `import` statements inside the source text, and not general asset URLs (`<img src>`, CSS `url()`) or navigation. A `blob:` URL has no hierarchical path of its own, so a literal `import "./util.js"` statement inside blob-served source will **not** resolve on its own in a browser -- call `resolveSpecifier()` yourself with the specifier your loader saw and use the URL it returns (or rewrite the specifier to that URL before creating the blob). See [andbox#13](https://github.com/johnhenry/andbox/issues/13) for the full design discussion, and [andbox#14](https://github.com/johnhenry/andbox/issues/14) for the harder "make it behave like a real server" problem this deliberately does not attempt to solve.
 
 ### `createNetworkFetch(allowedHosts?, fetchFn?)`
 
@@ -311,6 +343,7 @@ andbox is **not** a boundary against code that is actively trying to escape it.
 
 - **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.
+- **(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).
 - **`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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/andbox",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "type": "module",
   "description": "Sandboxed JavaScript runtime with Worker isolation, RPC, import maps, and timeouts",
   "main": "./src/index.mjs",
@@ -43,6 +43,8 @@
     "node": ">=26.0.0"
   },
   "devDependencies": {
-    "esbuild": "^0.28.2"
+    "esbuild": "^0.28.2",
+    "vite": "^8.3.3",
+    "webpack": "^5.111.1"
   }
 }

package/src/index.d.ts

@@ -135,7 +135,11 @@ export declare function resolveWithImportMap(
 
 // ── virtual-module-registry ──
 
-/** A registry of in-memory files, each backed by its own `blob:` URL. */
+/**
+ * A registry of in-memory files: each backed by its own `blob:` URL in a
+ * browser, or an importable `andbox-vfs:` URL under Node (where files can
+ * import each other relatively).
+ */
 export interface VirtualModuleRegistry {
   /**
    * Get the `blob:` URL registered for a path.
@@ -165,6 +169,9 @@ export interface VirtualModuleRegistry {
    */
   define(path: string, source: string): string;
 
+  /** The source text registered for a path, or null. Works in every runtime. */
+  source(path: string): string | null;
+
   /** Whether a path is registered. */
   has(path: string): boolean;
 
@@ -188,7 +195,11 @@ export interface VirtualModuleRegistry {
  */
 export declare function createVirtualModuleRegistry(
   files?: Record<string, string>,
-  options?: { importMap?: ImportMap },
+  options?: {
+    importMap?: ImportMap;
+    /** `'auto'` (default): Node hooks under Node, `blob:` elsewhere. */
+    backend?: 'auto' | 'blob' | 'node';
+  },
 ): VirtualModuleRegistry;
 
 // ── network-policy ──
@@ -311,12 +322,52 @@ export interface SandboxOptions {
    * `Worker`. `'node-worker'` forces the Node implementation.
    */
   mode?: 'worker' | 'node-worker';
+  // Any other value throws: supported modes are 'worker', 'node-worker', 'inline', 'data-uri', 'service-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;
+  /**
+   * Node worker_threads options and opt-in hardening. Only valid with the
+   * built-in Node mode (throws with a browser Worker or custom workerFactory).
+   * A worker thread is NOT a security boundary even with `permissions: true`.
+   */
+  nodeWorker?: NodeWorkerOptions;
+  /**
+   * Node only (default false). When true the thread is unref'd while the
+   * sandbox is idle so a forgotten sandbox does not keep the process alive;
+   * it stays ref'd during startup, evaluate() and defineModule(). Without it
+   * a live sandbox keeps the process alive until dispose().
+   */
+  unref?: boolean;
+}
+
+/** Options for the built-in Node worker_threads mode (`nodeWorker`). */
+export interface NodeWorkerOptions {
+  /**
+   * Spawn the thread with Node's permission model (`--permission`), an
+   * isolated `env` (`{}` unless `env` is given), a default 256 MB heap cap,
+   * stripped `process` escapes, blocked `node:`/`file:` imports and captured
+   * stdio. Does not restrict network or CPU.
+   */
+  permissions?: boolean;
+  /** Environment for the thread. Default: a copy of `process.env` (or `{}` with `permissions`). */
+  env?: Record<string, string>;
+  /** Heap cap in megabytes (`resourceLimits.maxOldGenerationSizeMb`). */
+  maxMemoryMb?: number;
+  /** Raw `worker_threads` resourceLimits, merged over `maxMemoryMb`. */
+  resourceLimits?: {
+    maxOldGenerationSizeMb?: number;
+    maxYoungGenerationSizeMb?: number;
+    codeRangeSizeMb?: number;
+    stackSizeMb?: number;
+  };
+  /** Extra thread `execArgv`, e.g. `['--allow-fs-read=/data']`. */
+  execArgv?: string[];
+  /** Route thread stdout/stderr to `onConsole('stdout' | 'stderr', text)`. Default: true with `permissions`. */
+  captureStdio?: boolean;
 }
 
 /** The subset of the Web Worker interface andbox drives. */
@@ -333,7 +384,9 @@ export interface WorkerLike {
  * 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>;
+export declare function createNodeWorkerFactory(
+  options?: NodeWorkerOptions,
+): Promise<(source: string) => WorkerLike>;
 
 /** Sandbox statistics. */
 export interface SandboxStats {

package/src/node-vfs.mjs

@@ -0,0 +1,181 @@
+/**
+ * Node virtual filesystem for ES modules.
+ *
+ * Node's ESM loader cannot `import()` a `blob:` URL, and a `data:` URL has
+ * no hierarchical base, so two virtual modules can never import each other
+ * relatively through either. This installs in-thread module customization
+ * hooks (`module.registerHooks`, synchronous, same thread) that serve an
+ * in-memory file table under a hierarchical custom scheme:
+ *
+ *   andbox-vfs://<namespace>/<path>?v=<version>
+ *
+ * Relative specifiers (`./b.js`, `../c`) resolve against that base natively,
+ * bare specifiers are looked up as other virtual module names and then in a
+ * per-namespace import map, and cycles work as they do for real files.
+ *
+ * `installNodeVfs` is deliberately self-contained (no free variables) so the
+ * Node worker adapter can inline `installNodeVfs.toString()` into the thread
+ * prelude and share one implementation between the host and the thread.
+ *
+ * @param {(hooks: object) => unknown} registerHooks `module.registerHooks`
+ */
+export function installNodeVfs(registerHooks) {
+  const KEY = Symbol.for('andbox.vfs');
+  if (globalThis[KEY]) return globalThis[KEY];
+
+  const SCHEME = 'andbox-vfs:';
+  const spaces = new Map(); // ns -> { files: Map(name -> {v, src}), hist: Map, importMap }
+  let counter = 0;
+  let denyHostResources = false;
+
+  function space(ns, create) {
+    let s = spaces.get(ns);
+    if (!s && create) {
+      s = { files: new Map(), hist: new Map(), importMap: null };
+      spaces.set(ns, s);
+    }
+    return s;
+  }
+
+  function urlFor(ns, name, v) {
+    return `andbox-vfs://${ns}/${name.split('/').map(encodeURIComponent).join('/')}?v=${v}`;
+  }
+
+  function parse(url) {
+    const u = new URL(url);
+    return {
+      ns: u.host,
+      name: decodeURIComponent(u.pathname.slice(1)),
+      v: u.searchParams.get('v'),
+    };
+  }
+
+  function lookup(ns, name) {
+    const s = spaces.get(ns);
+    if (!s) return null;
+    const bare = name.replace(/\.m?js$/, '');
+    for (const cand of [name, name + '.js', name + '.mjs', name + '/index.js', bare]) {
+      const f = s.files.get(cand);
+      if (f) return { name: cand, v: f.v };
+    }
+    return null;
+  }
+
+  function matchSpec(specifier, mapping) {
+    if (mapping[specifier] !== undefined) return mapping[specifier];
+    let best = null;
+    for (const key of Object.keys(mapping)) {
+      if (key.endsWith('/') && specifier.startsWith(key) && (best === null || key.length > best.length)) best = key;
+    }
+    return best === null ? null : mapping[best] + specifier.slice(best.length);
+  }
+
+  function mapSpecifier(map, specifier, parentURL) {
+    if (!map) return null;
+    if (map.scopes) {
+      const scopes = Object.keys(map.scopes)
+        .filter((k) => parentURL.startsWith(k))
+        .sort((a, b) => b.length - a.length);
+      for (const k of scopes) {
+        const r = matchSpec(specifier, map.scopes[k]);
+        if (r !== null) return r;
+      }
+    }
+    return map.imports ? matchSpec(specifier, map.imports) : null;
+  }
+
+  function checkDenied(url, specifier) {
+    if (denyHostResources && (url.startsWith('node:') || url.startsWith('file:'))) {
+      const e = new Error(`Import of '${specifier}' is blocked in a hardened andbox sandbox`);
+      e.code = 'ERR_ANDBOX_BLOCKED';
+      throw e;
+    }
+  }
+
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      const parent = context.parentURL;
+      if (specifier.startsWith(SCHEME)) {
+        const p = parse(specifier);
+        const hit = lookup(p.ns, p.name);
+        if (!hit) throw new Error(`Cannot find virtual module '${p.name}'`);
+        return {
+          url: urlFor(p.ns, hit.name, hit.v),
+          format: 'module',
+          shortCircuit: true,
+        };
+      }
+      if (typeof parent === 'string' && parent.startsWith(SCHEME)) {
+        const pp = parse(parent);
+        const relative = /^(\.\.?)?\//.test(specifier);
+        if (relative) {
+          const name = decodeURIComponent(new URL(specifier, parent).pathname.slice(1));
+          const hit = lookup(pp.ns, name);
+          if (!hit) throw new Error(`Cannot resolve '${specifier}' from virtual module '${pp.name}'`);
+          return { url: urlFor(pp.ns, hit.name, hit.v), format: 'module', shortCircuit: true };
+        }
+        const hit = lookup(pp.ns, specifier);
+        if (hit) return { url: urlFor(pp.ns, hit.name, hit.v), format: 'module', shortCircuit: true };
+        const mapped = mapSpecifier(spaces.get(pp.ns)?.importMap, specifier, parent);
+        if (mapped !== null) {
+          checkDenied(mapped, specifier);
+          return nextResolve(mapped, context);
+        }
+      }
+      const r = nextResolve(specifier, context);
+      checkDenied(r.url, specifier);
+      return r;
+    },
+    load(url, context, nextLoad) {
+      if (!url.startsWith(SCHEME)) return nextLoad(url, context);
+      const p = parse(url);
+      const src = spaces.get(p.ns)?.hist.get(p.name + '\0' + p.v);
+      if (src === undefined) throw new Error(`Virtual module '${p.name}' is not available (disposed?)`);
+      return { format: 'module', source: src, shortCircuit: true };
+    },
+  });
+
+  const api = {
+    /** Define/replace a file; returns its current URL. Unchanged source keeps its version. */
+    define(ns, name, source) {
+      const s = space(ns, true);
+      const cur = s.files.get(name);
+      if (cur && cur.src === source) return urlFor(ns, name, cur.v);
+      const v = ++counter;
+      s.files.set(name, { v, src: source });
+      s.hist.set(name + '\0' + v, source);
+      return urlFor(ns, name, v);
+    },
+    urlOf(ns, name) {
+      const f = spaces.get(ns)?.files.get(name);
+      return f ? urlFor(ns, name, f.v) : null;
+    },
+    sourceOf(ns, name) {
+      return spaces.get(ns)?.files.get(name)?.src ?? null;
+    },
+    has: (ns, name) => !!spaces.get(ns)?.files.has(name),
+    names: (ns) => [...(spaces.get(ns)?.files.keys() ?? [])],
+    setImportMap(ns, map) {
+      space(ns, true).importMap = map || null;
+    },
+    dispose(ns) {
+      spaces.delete(ns);
+    },
+    /** From now on, imports resolving to `node:` or `file:` URLs throw. */
+    denyHostResources() {
+      denyHostResources = true;
+    },
+  };
+  globalThis[KEY] = api;
+  return api;
+}
+
+/**
+ * The host-thread VFS, installed lazily (and only under Node, via the
+ * synchronous `process.getBuiltinModule`, which keeps `node:module` out of
+ * bundler graphs). Returns null where hooks are unavailable (browsers).
+ */
+export function getHostNodeVfs() {
+  const registerHooks = globalThis.process?.getBuiltinModule?.('node:module')?.registerHooks;
+  return typeof registerHooks === 'function' ? installNodeVfs(registerHooks) : null;
+}

package/src/node-worker.mjs

@@ -12,15 +12,39 @@
  * `data:` URLs (which Node can `import()`) instead of `blob:` URLs. The
  * worker source itself is the same string the browser uses.
  *
+ * Virtual modules in the thread are served by `node-vfs.mjs` (in-thread
+ * `module.registerHooks`), so they can import each other relatively, by
+ * bare name, and through the sandbox import map. The VFS source is inlined
+ * into the prelude via `Function.prototype.toString`.
+ *
+ * Opt-in hardening (`nodeWorker.permissions`) spawns the thread with Node's
+ * permission model, an isolated `env`, a heap cap, captured stdio, and a
+ * stripped `process`. None of this makes a worker thread a security boundary;
+ * see the README's Security model.
+ *
  * `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 = `
+import { installNodeVfs } from './node-vfs.mjs';
+
+function makePrelude({ harden }) {
+  return `
 const { parentPort } = require('node:worker_threads');
+const __exit = process.exit.bind(process);
+const __vfs = (${installNodeVfs.toString()})(require('node:module').registerHooks);
+delete globalThis[Symbol.for('andbox.vfs')];
+Object.defineProperty(globalThis, '__andboxNodeVirtual', {
+  configurable: true,
+  value(name, modules, importMap) {
+    __vfs.setImportMap('sb', importMap);
+    for (const [n, src] of modules) __vfs.define('sb', n, src);
+    return import(__vfs.urlOf('sb', name));
+  },
+});
 globalThis.self = globalThis;
 globalThis.postMessage = (m) => parentPort.postMessage(m);
-globalThis.close = () => process.exit(0);
+globalThis.close = () => __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) }); }
@@ -31,7 +55,15 @@ globalThis.Blob = class AndboxNodeBlob {
 };
 URL.createObjectURL = (b) => 'data:text/javascript;base64,' + Buffer.from(b.text).toString('base64');
 URL.revokeObjectURL = () => {};
+
+${harden ? `
+__vfs.denyHostResources();
+for (const k of ['binding', '_linkedBinding', 'getBuiltinModule', 'dlopen', 'kill', 'abort', '_kill', 'reallyExit', 'mainModule', 'moduleLoadList']) {
+  try { delete process[k]; } catch {}
+}
+` : ''}
 `;
+}
 
 class NodeWebWorker {
   #thread;
@@ -40,8 +72,13 @@ class NodeWebWorker {
   onmessage = null;
   onerror = null;
 
-  constructor(ThreadWorker, source) {
-    const w = new ThreadWorker(PRELUDE + '\n' + source, { eval: true });
+  dead = false;
+  onstdio = null;
+
+  constructor(ThreadWorker, source, config) {
+    const w = new ThreadWorker(makePrelude({ harden: config.harden }) + '\n' + source, config.workerOptions);
+    if (config.workerOptions.stdout) w.stdout.on('data', (d) => this.onstdio?.('stdout', String(d)));
+    if (config.workerOptions.stderr) w.stderr.on('data', (d) => this.onstdio?.('stderr', String(d)));
     w.on('message', (data) => {
       const ev = { data };
       this.onmessage?.(ev);
@@ -49,6 +86,7 @@ class NodeWebWorker {
     });
     w.on('error', (e) => this.onerror?.({ message: e?.message ?? String(e) }));
     w.on('exit', (code) => {
+      this.dead = true;
       if (!this.#terminated && code !== 0) {
         this.onerror?.({ message: `worker exited with code ${code}` });
       }
@@ -61,6 +99,9 @@ class NodeWebWorker {
   }
   addEventListener(type, fn) { if (type === 'message') this.#listeners.add(fn); }
   removeEventListener(type, fn) { if (type === 'message') this.#listeners.delete(fn); }
+  /** Let the process exit while the thread is idle / keep it alive. */
+  ref() { if (!this.dead) this.#thread.ref(); }
+  unref() { if (!this.dead) this.#thread.unref(); }
   terminate() {
     this.#terminated = true;
     this.#listeners.clear();
@@ -81,7 +122,7 @@ export function isNodeRuntime() {
  *
  * @returns {Promise<(source: string) => object>}
  */
-export async function createNodeWorkerFactory() {
+export async function createNodeWorkerFactory(options = {}) {
   if (!isNodeRuntime()) {
     throw new Error("createNodeWorkerFactory() requires Node (node:worker_threads); in a browser use mode: 'worker'.");
   }
@@ -89,5 +130,36 @@ export async function createNodeWorkerFactory() {
   // `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);
+  const config = resolveNodeWorkerConfig(options);
+  return (source) => new NodeWebWorker(ThreadWorker, source, config);
+}
+
+const DEFAULT_HARDENED_MEMORY_MB = 256;
+
+/**
+ * Turn the public `nodeWorker` options into `Worker` constructor
+ * options.
+ */
+export function resolveNodeWorkerConfig(options = {}) {
+  const { permissions = false, env, maxMemoryMb, resourceLimits, execArgv, captureStdio } = options;
+  if (maxMemoryMb !== undefined && !(Number.isFinite(maxMemoryMb) && maxMemoryMb > 0)) {
+    throw new Error('nodeWorker.maxMemoryMb must be a positive number (megabytes)');
+  }
+  const workerOptions = { eval: true };
+  const memory = maxMemoryMb ?? (permissions ? DEFAULT_HARDENED_MEMORY_MB : undefined);
+  if (memory !== undefined || resourceLimits) {
+    workerOptions.resourceLimits = {
+      ...(memory !== undefined ? { maxOldGenerationSizeMb: memory } : {}),
+      ...resourceLimits,
+    };
+  }
+  if (env !== undefined) workerOptions.env = env;
+  else if (permissions) workerOptions.env = {};
+  const argv = [...(permissions ? ['--permission'] : []), ...(execArgv ?? [])];
+  if (argv.length) workerOptions.execArgv = argv;
+  if (captureStdio ?? permissions) {
+    workerOptions.stdout = true;
+    workerOptions.stderr = true;
+  }
+  return { workerOptions, harden: permissions };
 }

package/src/sandbox.mjs

@@ -231,9 +231,7 @@ async function createServiceWorkerSandbox(options = {}) {
   const initialFiles = { ...files };
   if (registry) {
     for (const path of registry.paths()) {
-      const url = registry.resolve(path);
-      const res = await fetch(url);
-      initialFiles[path] = { body: await res.text(), contentType: guessContentType(path) };
+      initialFiles[path] = { body: registry.source(path), contentType: guessContentType(path) };
     }
   }
 
@@ -307,6 +305,8 @@ async function createServiceWorkerSandbox(options = {}) {
  * @property {(level: string, ...args: string[]) => void} [onConsole] - Console output handler
  */
 
+const SUPPORTED_MODES = ['worker', 'node-worker', 'inline', 'data-uri', 'service-worker'];
+
 /**
  * Create a new sandboxed runtime.
  *
@@ -314,7 +314,13 @@ async function createServiceWorkerSandbox(options = {}) {
  * @returns {{ execute: Function, terminate: Function } | Promise<{ evaluate: Function, defineModule: Function, dispose: Function, isDisposed: () => boolean }> | Promise<{ scriptURL: string, scope: string, define: Function, remove: Function, dispose: Function, isDisposed: () => boolean }>}
  */
 export function createSandbox(options = {}) {
-  const mode = options.mode || 'worker';
+  const mode = options.mode ?? 'worker';
+  if (!SUPPORTED_MODES.includes(mode)) {
+    throw new Error(
+      `Unknown sandbox mode ${typeof mode === 'string' ? `'${mode}'` : String(mode)}. ` +
+      `Supported modes: ${SUPPORTED_MODES.map((m) => `'${m}'`).join(', ')}.`
+    );
+  }
   if (mode === 'inline') return createInlineSandbox(options);
   if (mode === 'data-uri') return createDataUriSandbox(options);
   if (mode === 'service-worker') return createServiceWorkerSandbox(options);
@@ -329,14 +335,25 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
     baseURL = typeof location !== 'undefined' ? location.href : 'https://andbox.local/',
     policy,
     onConsole,
+    nodeWorker,
+    unref = false,
   } = 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;
+  let usingNode = false;
   if (!workerFactory && (forceNode || (typeof Worker === 'undefined' && isNodeRuntime()))) {
-    workerFactory = await createNodeWorkerFactory();
+    workerFactory = await createNodeWorkerFactory(nodeWorker);
+    usingNode = true;
+  }
+  if (nodeWorker && !usingNode) {
+    // A security option that silently does nothing is worse than an error.
+    throw new Error(
+      'The nodeWorker option only applies to the built-in Node worker_threads mode; ' +
+      'it cannot be honoured with a browser Worker or a custom workerFactory.'
+    );
   }
 
   // Gate capabilities with rate limits
@@ -351,6 +368,17 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
   let worker = null;
   let workerBlobURL = null;
 
+  // `unref`: the thread only keeps the host process alive while work is in
+  // flight (startup, evaluate, defineModule); idle, it lets the process exit.
+  let activeOps = 0;
+  function beginOp() {
+    activeOps++;
+    worker?.ref?.();
+  }
+  function endOp() {
+    if (--activeOps === 0 && unref) worker?.unref?.();
+  }
+
   // Pending evaluations
   const pending = new Map(); // id -> { resolve, reject, timer }
 
@@ -361,6 +389,7 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
     if (workerFactory) {
       worker = workerFactory(source);
       attachWorkerHandlers();
+      worker.onstdio = (stream, text) => activeConsoleHandler?.(stream, text);
       return;
     }
     const blob = new Blob([source], { type: 'application/javascript' });
@@ -471,9 +500,15 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
   }
 
   async function restartWorker() {
-    terminateWorker();
-    createWorker();
-    await configureWorker();
+    beginOp();
+    try {
+      terminateWorker();
+      createWorker();
+      worker.ref?.();
+      await configureWorker();
+    } finally {
+      endOp();
+    }
   }
 
   // ── Public API ──
@@ -487,7 +522,8 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
    */
   async function evaluate(code, opts = {}) {
     if (disposed) throw new Error('Sandbox is disposed');
-    if (!worker) await restartWorker();
+    if (!worker || worker.dead) await restartWorker();
+    beginOp();
 
     // Random (not sequential) id so code running during one evaluate() call
     // can't guess the id of a concurrent evaluate() on the same worker and
@@ -516,6 +552,7 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
     if (opts.signal) {
       if (opts.signal.aborted) {
         if (timer) clearTimeout(timer);
+        endOp();
         throw makeAbortError();
       }
       opts.signal.addEventListener('abort', () => {
@@ -533,10 +570,10 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
     worker.postMessage({ type: 'evaluate', id, code });
 
     // Restore console handler when evaluation completes
-    if (opts.onConsole) {
-      return promise.finally(() => { activeConsoleHandler = prevConsoleHandler; });
-    }
-    return promise;
+    return promise.finally(() => {
+      if (opts.onConsole) activeConsoleHandler = prevConsoleHandler;
+      endOp();
+    });
   }
 
   /**
@@ -551,6 +588,7 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
     virtualModules.set(name, source);
 
     if (worker) {
+      beginOp();
       const { promise, resolve } = makeDeferred();
       const handler = ({ data }) => {
         if (data.type === 'moduleDefined' && data.name === name) {
@@ -560,7 +598,7 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
       };
       worker.addEventListener('message', handler);
       worker.postMessage({ type: 'defineModule', name, source });
-      await promise;
+      try { await promise; } finally { endOp(); }
     }
   }
 
@@ -594,8 +632,13 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
   }
 
   // ── Initialize ──
-  createWorker();
-  await configureWorker();
+  beginOp();
+  try {
+    createWorker();
+    await configureWorker();
+  } finally {
+    endOp();
+  }
 
   return {
     evaluate,

package/src/virtual-module-registry.mjs

@@ -10,12 +10,14 @@
  */
 
 import { resolveWithImportMap } from './import-map-resolver.mjs';
+import { getHostNodeVfs } from './node-vfs.mjs';
 
 /**
  * @typedef {Object} VirtualModuleRegistry
  * @property {(path: string) => string | null} resolve
  * @property {(specifier: string, parentPath?: string) => string | null} resolveSpecifier
  * @property {(path: string, source: string) => string} define
+ * @property {(path: string) => string | null} source
  * @property {(path: string) => boolean} has
  * @property {() => string[]} paths
  * @property {() => void} dispose
@@ -23,18 +25,43 @@ import { resolveWithImportMap } from './import-map-resolver.mjs';
  */
 
 /**
- * Create a registry of in-memory files, each backed by its own `blob:` URL.
+ * Create a registry of in-memory files.
+ *
+ * In a browser each file is backed by its own `blob:` URL. Under Node, whose
+ * ESM loader cannot `import()` a `blob:` URL, the registry is backed by an
+ * in-thread module hook instead (see `node-vfs.mjs`): `resolve(path)`
+ * returns an `andbox-vfs://<id>/<path>?v=<n>` URL that Node *can* `import()`,
+ * and files in the registry can import each other by relative path
+ * (`./util.js`), by bare name, and through the registry's import map.
+ * Call `dispose()` to drop the files.
+ * `options.backend` is `'auto'` (default: Node hooks under Node, blob
+ * elsewhere), `'blob'` or `'node'`.
  *
  * @param {Record<string, string>} [files] - path → source text
- * @param {{ importMap?: { imports?: Record<string,string>, scopes?: Record<string,Record<string,string>> } }} [options]
+ * @param {{ backend?: 'auto' | 'blob' | 'node', importMap?: { imports?: Record<string,string>, scopes?: Record<string,Record<string,string>> } }} [options]
  * @returns {VirtualModuleRegistry}
  */
 export function createVirtualModuleRegistry(files = {}, options = {}) {
   const importMap = options.importMap || null;
-  const urls = new Map(); // path -> blob: URL
+  const urls = new Map(); // path -> blob: / andbox-vfs: URL
+  const sources = new Map(); // path -> source text
+  const backend = options.backend ?? 'auto';
+  if (!['auto', 'blob', 'node'].includes(backend)) {
+    throw new Error(`Unknown registry backend '${backend}'; use 'auto', 'blob' or 'node'`);
+  }
+  const vfs = backend === 'blob' ? null : getHostNodeVfs();
+  if (backend === 'node' && !vfs) throw new Error("backend: 'node' requires Node (module.registerHooks)");
+  const ns = vfs ? Math.random().toString(36).slice(2, 10) + Date.now().toString(36) : null;
   let disposed = false;
+  if (vfs) vfs.setImportMap(ns, importMap);
 
   function blobify(path, source) {
+    sources.set(path, source);
+    if (vfs) {
+      const url = vfs.define(ns, path, source);
+      urls.set(path, url);
+      return url;
+    }
     const blob = new Blob([source], { type: 'text/javascript' });
     const url = URL.createObjectURL(blob);
     urls.set(path, url);
@@ -70,10 +97,22 @@ export function createVirtualModuleRegistry(files = {}, options = {}) {
    */
   function define(path, source) {
     assertNotDisposed();
-    if (urls.has(path)) URL.revokeObjectURL(urls.get(path));
+    if (!vfs && urls.has(path)) URL.revokeObjectURL(urls.get(path));
     return blobify(path, source);
   }
 
+  /**
+   * The source text registered for a path (works in every runtime, including
+   * Node where the URL is not fetchable).
+   *
+   * @param {string} path
+   * @returns {string | null}
+   */
+  function source(path) {
+    assertNotDisposed();
+    return sources.get(path) ?? null;
+  }
+
   /** @param {string} path */
   function has(path) {
     return urls.has(path);
@@ -129,14 +168,17 @@ export function createVirtualModuleRegistry(files = {}, options = {}) {
   function dispose() {
     if (disposed) return;
     disposed = true;
-    for (const url of urls.values()) URL.revokeObjectURL(url);
+    if (vfs) vfs.dispose(ns);
+    else for (const url of urls.values()) URL.revokeObjectURL(url);
     urls.clear();
+    sources.clear();
   }
 
   return {
     resolve,
     resolveSpecifier,
     define,
+    source,
     has,
     paths,
     dispose,

package/src/worker-source.mjs

@@ -33,6 +33,10 @@ export function makeWorkerSource() {
 let importMap = { imports: {}, scopes: {} };
 let baseURL = 'https://andbox.local/';
 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 {}
 
 // ── Import Map Resolver (inlined) ──
 function resolveWithImportMap(specifier, map, parentURL) {
@@ -69,6 +73,7 @@ function matchSpec(specifier, mapping) {
 async function sandboxImport(specifier) {
   // 1. Virtual module
   if (virtualModules.has(specifier)) {
+    if (nodeVirtual) return await nodeVirtual(specifier, virtualModules, importMap);
     const src = virtualModules.get(specifier);
     const blob = new Blob([src], { type: 'application/javascript' });
     const url = URL.createObjectURL(blob);