@johnhenry/andbox 0.0.1 → 0.0.3

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 three execution modes:
+andbox supports four 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.
 - **`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.
+- **`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
 // Inline mode (no Worker)
@@ -82,6 +100,15 @@ const result = await inline.execute('return math.sqrt(16)');
 // Data-URI mode
 const dataUri = createSandbox({ mode: 'data-uri', globals: { x: 42 } });
 const result = await dataUri.execute('print(x)');
+
+// Service-Worker mode (browser only -- see examples/06-service-worker-mode/)
+const site = await createSandbox({
+  mode: 'service-worker',
+  scriptURL: '/andbox-sw.js', // you serve makeServiceWorkerSource()'s output here
+  scope: '/virtual/',
+  files: { '/virtual/hello.html': '<h1>Hello</h1>' },
+});
+// Only navigate into scope *after* this resolves -- see Security model.
 ```
 
 ## API
@@ -153,6 +180,28 @@ const { gated, stats } = gateCapabilities(
 
 Resolves a module specifier against an import map, following the browser import map algorithm.
 
+### `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.
+
+```js
+import { createVirtualModuleRegistry } from '@johnhenry/andbox';
+
+const registry = createVirtualModuleRegistry({
+  'index.js': 'import { add } from "./util.js"; export const result = add(2, 3);',
+  'util.js': 'export function add(a, b) { return a + b; }',
+});
+
+registry.resolve('index.js');                       // blob: URL, or null if unknown
+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
+```
+
+`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.
+
 ### `createNetworkFetch(allowedHosts?, fetchFn?)`
 
 Creates a fetch function that checks the request hostname against an allowlist before calling through. Useful for keeping cooperative code pointed at the hosts you intend -- **not redirect-safe** (see [Security model](#security-model)): an allowlisted host that responds with a redirect is followed without re-checking the final URL.
@@ -177,6 +226,51 @@ Promise and error utilities used internally, also available for consumers.
 
 Returns the Worker script source code as a string (useful for custom Worker setups).
 
+### `createSandbox({ mode: 'service-worker', ... })`
+
+Registers a Service Worker that backs a `path → content` map with real, same-origin, HTTP-shaped fetch and navigation semantics -- see [andbox#14](https://github.com/johnhenry/andbox/issues/14). Unlike the other three modes, this isn't code execution: it's for hosting a small virtual multi-file site (an in-memory archive of HTML/CSS/JS/anything) so that relative links, absolute-path links, runtime-computed `fetch()` calls, and `pushState`-based routing all work exactly as they would against a real server, because it *is* real HTTP-shaped navigation, transparently intercepted.
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `scriptURL` | `string` | **Required.** A real same-origin `http(s)` URL where you are already serving `makeServiceWorkerSource()`'s output. Service Worker registration requires a real `http(s)` scriptURL -- unlike `worker`/`data-uri` mode, a `blob:` URL is not accepted by the platform. |
+| `scope` | `string` | Path prefix to register the Service Worker under. Defaults to `scriptURL`'s own directory. |
+| `files` | `Record<string, string \| { body, contentType?, status?, headers? }>` | Initial served-file map. |
+| `registry` | `VirtualModuleRegistry` | A [`createVirtualModuleRegistry()`](#createvirtualmoduleregistryfiles-options) instance to pull additional served content from -- its known paths' real blob content is fetched and merged in, reusing its path/blob bookkeeping instead of a second one. |
+| `timeoutMs` | `number` | Max time to wait for the registration to become active before rejecting. Defaults to `DEFAULT_TIMEOUT_MS`. |
+
+**Returns:** `Promise<{ scriptURL, scope, define(path, source, opts?), remove(path), dispose(), isDisposed() }>`. The promise resolves once the registration is **active**, rejects if it instead becomes `'redundant'` (its install/activate threw, or it failed to parse) or if `timeoutMs` elapses first -- see the ordering note in [Security model](#security-model) below before navigating anything into `scope`.
+
+```js
+import { createSandbox } from '@johnhenry/andbox';
+
+const site = await createSandbox({
+  mode: 'service-worker',
+  scriptURL: '/andbox-sw.js', // you serve makeServiceWorkerSource()'s output here
+  scope: '/virtual/',
+  files: {
+    '/virtual/hello.html': { body: '<h1>Hello</h1>', contentType: 'text/html' },
+  },
+});
+
+// Only now -- with the registration active -- point something at the scope:
+iframe.src = '/virtual/hello.html';
+
+await site.define('/virtual/about.html', '<h1>About</h1>');
+await site.dispose(); // unregisters the Service Worker
+```
+
+See `examples/06-service-worker-mode/` for a complete, runnable (browser-only) demo, including the dev server that serves the generated script.
+
+### `makeServiceWorkerSource()`
+
+Returns the Service Worker script source code as a string, for `mode: 'service-worker'`. Unlike `makeWorkerSource()`'s output (turned into a `blob:` URL for `new Worker(...)`), this string must be served as a real same-origin file -- Service Worker registration doesn't accept `blob:` scriptURLs.
+
+### `resolveServiceWorkerResponse(pathname, files)`
+
+Given a request pathname and a served-file map (`Map` or plain object), returns the `Response` the Service Worker's `fetch` handler would produce for an in-scope request, or `null` if it should fall through to the network. The pure logic factored out of the generated script, for testing and for embedding the same matching behavior elsewhere.
+
 ## Execution model
 
 Code runs inside a Web Worker created from a Blob URL. This gets you, for free, against code that isn't specifically trying to defeat it:
@@ -189,18 +283,41 @@ 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).
 - **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).
+- **`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.1",
+  "version": "0.0.3",
   "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",
@@ -18,7 +22,8 @@
     "example:02": "node examples/02-capability-limits-cut-off-abuse.mjs",
     "example:03": "node examples/03-network-allowlist-blocks-unapproved-hosts.mjs",
     "example:04": "node examples/04-runaway-code-gets-timed-out.mjs",
-    "examples": "npm run example:01 && npm run example:02 && npm run example:03 && npm run example:04"
+    "example:05": "node examples/05-virtual-module-registry-resolves-a-multi-file-tree.mjs",
+    "examples": "npm run example:01 && npm run example:02 && npm run example:03 && npm run example:04 && npm run example:05"
   },
   "keywords": [
     "sandbox",
@@ -35,6 +40,6 @@
   },
   "homepage": "https://opensource.johnhenry.me/andbox/",
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=26.0.0"
   }
 }

package/src/index.d.ts

@@ -133,6 +133,64 @@ export declare function resolveWithImportMap(
   parentURL?: string,
 ): string | null;
 
+// ── virtual-module-registry ──
+
+/** A registry of in-memory files, each backed by its own `blob:` URL. */
+export interface VirtualModuleRegistry {
+  /**
+   * Get the `blob:` URL registered for a path.
+   *
+   * @param path
+   * @returns the blob URL, or null if the path is unknown
+   */
+  resolve(path: string): string | null;
+
+  /**
+   * Resolve a module specifier the way `import` would need to, from the
+   * point of view of a given importing file: import-map resolution first,
+   * then a relative-path (`./x.js`, `../x.js`) fallback against the known
+   * file table, then null if neither matched.
+   *
+   * @param specifier
+   * @param parentPath  path of the file doing the importing
+   * @returns a resolved URL, or null if nothing matched
+   */
+  resolveSpecifier(specifier: string, parentPath?: string): string | null;
+
+  /**
+   * Register (or replace) a file at runtime. Replacing an existing path
+   * revokes its previous blob URL before minting a new one.
+   *
+   * @returns the new blob URL
+   */
+  define(path: string, source: string): string;
+
+  /** Whether a path is registered. */
+  has(path: string): boolean;
+
+  /** All registered paths. */
+  paths(): string[];
+
+  /** Revoke every blob URL this registry has ever minted. */
+  dispose(): void;
+
+  /** Whether dispose() has been called. */
+  isDisposed(): boolean;
+}
+
+/**
+ * Create a registry of in-memory files, each backed by its own `blob:`
+ * URL, with specifier resolution that combines import-map resolution
+ * with a relative-path fallback against the known file table.
+ *
+ * @param files      path → source text
+ * @param options    optional import map used for bare-specifier resolution
+ */
+export declare function createVirtualModuleRegistry(
+  files?: Record<string, string>,
+  options?: { importMap?: ImportMap },
+): VirtualModuleRegistry;
+
 // ── network-policy ──
 
 /**
@@ -178,6 +236,49 @@ export declare function createStdio(): StdioStream;
  */
 export declare function makeWorkerSource(): string;
 
+// ── service-worker-source ──
+
+/**
+ * Generate the Service Worker source code as a string, for `mode:
+ * 'service-worker'`.
+ *
+ * Unlike makeWorkerSource() (whose output becomes a `blob:` URL passed to
+ * `new Worker(...)`), Service Worker registration requires a real
+ * same-origin http(s) scriptURL — a `blob:` URL is not accepted by the
+ * platform. The caller is responsible for serving this string's content at
+ * whatever path it passes as `scriptURL` to `createSandbox()`.
+ *
+ * @returns The complete Service Worker script source code as a string.
+ */
+export declare function makeServiceWorkerSource(): string;
+
+// ── service-worker-response ──
+
+/** A file served by `mode: 'service-worker'`. */
+export interface ServedFile {
+  body: string | ArrayBuffer;
+  contentType?: string;
+  status?: number;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Given a request pathname and the known served-file map, produce the
+ * Response the Service Worker's `fetch` handler would return for an
+ * in-scope request, or null if it should fall through to the network.
+ *
+ * Pure logic factored out of the generated Service Worker script so it's
+ * testable under plain Node (which has no `ServiceWorkerGlobalScope` at
+ * all, but does have real `Response`/`Headers` globals).
+ *
+ * @param pathname
+ * @param files  path → served-file map (Map or plain object)
+ */
+export declare function resolveServiceWorkerResponse(
+  pathname: string,
+  files: Map<string, ServedFile> | Record<string, ServedFile>,
+): Response | null;
+
 // ── sandbox ──
 
 /** Options for evaluate(). */
@@ -251,10 +352,58 @@ export interface Sandbox {
   isDisposed(): boolean;
 }
 
+/** Options for createSandbox({ mode: 'service-worker' }). */
+export interface ServiceWorkerSandboxOptions {
+  /** Mode discriminant. */
+  mode: 'service-worker';
+  /**
+   * Real same-origin http(s) URL serving makeServiceWorkerSource()'s
+   * output. A blob: URL is not accepted by the platform for Service
+   * Worker registration.
+   */
+  scriptURL: string;
+  /** Scope to register the Service Worker under. Defaults to scriptURL's own directory. */
+  scope?: string;
+  /** Initial path → content map. */
+  files?: Record<string, string | ServedFile>;
+  /**
+   * A #13 virtual module registry to pull additional served content from
+   * (its known paths' real blob content), reusing its path/blob
+   * bookkeeping instead of a second one.
+   */
+  registry?: VirtualModuleRegistry;
+}
+
+/** A registered Service Worker instance backing a path → content map. */
+export interface ServiceWorkerSandbox {
+  /** The scriptURL this Service Worker was registered from. */
+  scriptURL: string;
+  /** The registration's actual scope. */
+  scope: string;
+  /**
+   * Register (or replace) one served file.
+   *
+   * @param path
+   * @param source
+   * @param entryOpts  contentType/status/headers overrides
+   */
+  define(
+    path: string,
+    source: string,
+    entryOpts?: { contentType?: string; status?: number; headers?: Record<string, string> },
+  ): Promise<void>;
+  /** Remove a served file; requests for it fall through to the network. */
+  remove(path: string): Promise<void>;
+  /** Unregister the Service Worker. */
+  dispose(): Promise<void>;
+  /** Returns true if dispose() has been called. */
+  isDisposed(): boolean;
+}
+
 /**
  * Create a new sandboxed JavaScript runtime.
  *
- * The sandbox runs in an isolated Web Worker with:
+ * The default (Worker) mode runs in an isolated Web Worker with:
  * - RPC-based capability calls (host.call)
  * - Import map resolution
  * - Virtual module definitions
@@ -262,7 +411,15 @@ export interface Sandbox {
  * - Console forwarding
  * - Capability gating with rate limits
  *
+ * `mode: 'service-worker'` is a different shape entirely: it hosts a
+ * path → content map behind a real, same-origin, HTTP-shaped scope
+ * instead of evaluating code — see andbox#14 and README's Security model
+ * section before using it for untrusted content.
+ *
  * @param options  Sandbox configuration options.
  * @returns A promise that resolves to the sandbox instance.
  */
 export declare function createSandbox(options?: SandboxOptions): Promise<Sandbox>;
+export declare function createSandbox(
+  options: ServiceWorkerSandboxOptions,
+): Promise<ServiceWorkerSandbox>;

package/src/index.mjs

@@ -6,9 +6,12 @@
 
 export { createSandbox } from './sandbox.mjs';
 export { resolveWithImportMap } from './import-map-resolver.mjs';
+export { createVirtualModuleRegistry } from './virtual-module-registry.mjs';
 export { gateCapabilities } from './capability-gate.mjs';
 export { createStdio } from './stdio.mjs';
 export { createNetworkFetch } from './network-policy.mjs';
 export { makeDeferred, makeAbortError, makeTimeoutError } from './deferred.mjs';
 export { DEFAULT_TIMEOUT_MS, DEFAULT_LIMITS, DEFAULT_CAPABILITY_LIMITS } from './constants.mjs';
 export { makeWorkerSource } from './worker-source.mjs';
+export { makeServiceWorkerSource } from './service-worker-source.mjs';
+export { resolveServiceWorkerResponse } from './service-worker-response.mjs';

package/src/sandbox.mjs

@@ -101,6 +101,198 @@ ${preamble}${code}`;
   };
 }
 
+// ── Service-Worker sandbox (path→content hosting, real URL/navigation semantics) ──
+
+const CONTENT_TYPE_BY_EXTENSION = {
+  html: 'text/html;charset=utf-8',
+  css: 'text/css;charset=utf-8',
+  js: 'text/javascript;charset=utf-8',
+  mjs: 'text/javascript;charset=utf-8',
+  json: 'application/json;charset=utf-8',
+  svg: 'image/svg+xml',
+  txt: 'text/plain;charset=utf-8',
+};
+
+function guessContentType(path) {
+  const ext = path.split('.').pop();
+  return CONTENT_TYPE_BY_EXTENSION[ext] || 'application/octet-stream';
+}
+
+function normalizeServedEntry(path, value, defaults = {}) {
+  if (typeof value === 'string') {
+    return {
+      body: value,
+      contentType: defaults.contentType || guessContentType(path),
+      status: defaults.status || 200,
+      headers: defaults.headers || {},
+    };
+  }
+  return {
+    body: value.body,
+    contentType: value.contentType || defaults.contentType || guessContentType(path),
+    status: value.status || defaults.status || 200,
+    headers: value.headers || defaults.headers || {},
+  };
+}
+
+function normalizeServedFileMap(map) {
+  const out = {};
+  for (const [path, value] of Object.entries(map)) {
+    out[path] = normalizeServedEntry(path, value);
+  }
+  return out;
+}
+
+/**
+ * Resolve once the registration's worker has activated (or already has).
+ * Rejects if the worker instead reaches `'redundant'` (its install/activate
+ * threw, failed to parse, or was superseded before activating) -- without
+ * this check the returned promise would otherwise hang forever, since
+ * `'redundant'` is a valid terminal state `statechange` fires for that
+ * is neither `'activated'` nor another `statechange` event to wait on.
+ * Also bounded by `timeoutMs` as defense in depth for any lifecycle path
+ * that reaches neither terminal state.
+ */
+export function waitForActive(registration, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  if (registration.active) return Promise.resolve();
+  const worker = registration.installing || registration.waiting;
+  if (!worker) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      worker.removeEventListener('statechange', onChange);
+      reject(makeTimeoutError(timeoutMs));
+    }, timeoutMs);
+    function onChange() {
+      if (worker.state === 'activated') {
+        clearTimeout(timer);
+        worker.removeEventListener('statechange', onChange);
+        resolve();
+      } else if (worker.state === 'redundant') {
+        clearTimeout(timer);
+        worker.removeEventListener('statechange', onChange);
+        reject(new Error(
+          "Service Worker registration became 'redundant' before activating -- " +
+          'its install/activate handler likely threw, or it failed to parse. ' +
+          'Check the browser console for the actual Service Worker error.'
+        ));
+      }
+    }
+    worker.addEventListener('statechange', onChange);
+  });
+}
+
+/**
+ * @typedef {Object} ServiceWorkerSandboxOptions
+ * @property {string} scriptURL - Real same-origin http(s) URL serving makeServiceWorkerSource()'s output. A blob: URL is not accepted by the platform for Service Worker registration.
+ * @property {string} [scope] - Scope to register the Service Worker under. Defaults to scriptURL's own directory.
+ * @property {Record<string, string | { body: string, contentType?: string, status?: number, headers?: Record<string,string> }>} [files] - Initial path→content map.
+ * @property {import('./virtual-module-registry.mjs').VirtualModuleRegistry} [registry] - A #13 virtual module registry to pull additional served content from, reusing its path/blob bookkeeping instead of a second one.
+ * @property {number} [timeoutMs] - Max time to wait for the registration to activate before rejecting. Defaults to DEFAULT_TIMEOUT_MS.
+ */
+
+/**
+ * Register a Service Worker that backs a path→content map with real
+ * HTTP-shaped fetch/navigation semantics -- see andbox#14.
+ *
+ * Requires `navigator.serviceWorker` (a real browser). The generated
+ * script (`makeServiceWorkerSource()`) cannot be registered from a
+ * `blob:` URL -- the caller must already be serving it at a real
+ * same-origin `scriptURL`.
+ *
+ * @param {ServiceWorkerSandboxOptions} [options]
+ */
+async function createServiceWorkerSandbox(options = {}) {
+  const { scriptURL, scope, files = {}, registry, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+
+  if (!scriptURL) {
+    throw new Error(
+      "createSandbox({ mode: 'service-worker' }) requires a scriptURL: the real " +
+      "same-origin http(s) URL where you are already serving makeServiceWorkerSource()'s " +
+      'output. Service Worker registration requires a real http(s) scriptURL -- unlike ' +
+      "worker/data-uri mode, a blob: URL is not accepted by the platform. See andbox#14."
+    );
+  }
+  if (typeof navigator === 'undefined' || !navigator.serviceWorker) {
+    throw new Error(
+      "mode: 'service-worker' requires navigator.serviceWorker (a real browser); " +
+      'it is not available under Node. See andbox#14.'
+    );
+  }
+
+  let disposed = false;
+
+  // Build the initial served-file map. Reuse a #13 virtual module registry's
+  // own path/blob bookkeeping when given one, rather than a second table:
+  // pull each of its known paths' real content straight from its blob URLs.
+  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) };
+    }
+  }
+
+  const registration = await navigator.serviceWorker.register(
+    scriptURL,
+    scope ? { scope } : undefined
+  );
+
+  // Only resolve once this registration is active. This -- combined with
+  // the documented contract "don't navigate anything into scope until this
+  // promise resolves" -- is what actually avoids the first-navigation race
+  // described in andbox#14 and in makeServiceWorkerSource()'s doc comment:
+  // clients.claim() (called in the generated script's activate handler)
+  // only takes over clients that are *already open*; it doesn't retroactively
+  // intercept a navigation into scope that started before activation.
+  await waitForActive(registration, timeoutMs);
+
+  async function send(message) {
+    if (disposed) throw new Error('Sandbox is disposed');
+    const target = registration.active;
+    if (!target) throw new Error('Service Worker is not active');
+    const { promise, resolve } = makeDeferred();
+    const channel = new MessageChannel();
+    channel.port1.onmessage = ({ data }) => resolve(data);
+    target.postMessage(message, [channel.port2]);
+    return promise;
+  }
+
+  await send({ type: 'configure', files: normalizeServedFileMap(initialFiles) });
+
+  /**
+   * Register (or replace) one served file.
+   * @param {string} path
+   * @param {string} source
+   * @param {{ contentType?: string, status?: number, headers?: Record<string,string> }} [entryOpts]
+   */
+  async function define(path, source, entryOpts = {}) {
+    const entry = normalizeServedEntry(path, source, entryOpts);
+    await send({ type: 'define', path, entry });
+  }
+
+  /** Remove a served file; requests for it fall through to the network. */
+  async function remove(path) {
+    await send({ type: 'remove', path });
+  }
+
+  /** Unregister the Service Worker. */
+  async function dispose() {
+    if (disposed) return;
+    disposed = true;
+    await registration.unregister();
+  }
+
+  return {
+    scriptURL,
+    scope: registration.scope,
+    define,
+    remove,
+    dispose,
+    isDisposed: () => disposed,
+  };
+}
+
 /**
  * @typedef {Object} SandboxOptions
  * @property {{ imports?: Record<string,string>, scopes?: Record<string,Record<string,string>> }} [importMap]
@@ -114,13 +306,14 @@ ${preamble}${code}`;
 /**
  * Create a new sandboxed runtime.
  *
- * @param {SandboxOptions} [options]
- * @returns {{ execute: Function, terminate: Function } | Promise<{ evaluate: Function, defineModule: Function, dispose: Function, isDisposed: () => boolean }>}
+ * @param {SandboxOptions | ServiceWorkerSandboxOptions} [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';
   if (mode === 'inline') return createInlineSandbox(options);
   if (mode === 'data-uri') return createDataUriSandbox(options);
+  if (mode === 'service-worker') return createServiceWorkerSandbox(options);
   return createWorkerSandbox(options);
 }
 

package/src/service-worker-response.mjs

@@ -0,0 +1,90 @@
+/**
+ * Pure request-matching / response-synthesis logic for the `service-worker`
+ * sandbox mode.
+ *
+ * Factored out on its own so it's testable under plain Node without a real
+ * `ServiceWorkerGlobalScope` (Node has neither `self.clients`,
+ * `navigator.serviceWorker`, nor any part of the Service Worker API — see
+ * andbox#14). `Response`/`Headers` themselves *are* real Node globals
+ * (Node's built-in fetch implementation), so the "given a path and a file
+ * map, what Response would the SW's fetch handler return" question is pure
+ * logic and gets real coverage here.
+ *
+ * The generated Service Worker script (`makeServiceWorkerSource()`, in
+ * service-worker-source.mjs) inlines an equivalent copy of this matching
+ * logic as a self-contained string — the same way worker-source.mjs
+ * inlines a copy of resolveWithImportMap() rather than importing it, since
+ * the generated script must have zero file dependencies at runtime (it's
+ * registered directly as a Service Worker scriptURL, it can't `import`
+ * this module across origins/paths the way a bundler-built app could).
+ */
+
+/**
+ * @typedef {Object} ServedFile
+ * @property {string | ArrayBuffer} body
+ * @property {string} [contentType]
+ * @property {number} [status]
+ * @property {Record<string,string>} [headers]
+ */
+
+/** Normalize a path to a leading-slash pathname, the way a URL's pathname reads. */
+export function normalizeScopePath(path) {
+  return path.startsWith('/') ? path : `/${path}`;
+}
+
+/**
+ * Find the served-file entry for a request pathname, with a directory-index
+ * convenience fallback (`/foo/` or `/foo` -> `/foo/index.html`) matching how
+ * a real static file server commonly behaves.
+ *
+ * @param {string} pathname
+ * @param {Map<string, ServedFile> | Record<string, ServedFile>} files
+ * @returns {ServedFile | null}
+ */
+export function matchFile(pathname, files) {
+  const get = files instanceof Map
+    ? (p) => files.get(p)
+    : (p) => (Object.prototype.hasOwnProperty.call(files, p) ? files[p] : undefined);
+
+  const direct = get(pathname);
+  if (direct !== undefined) return direct;
+
+  if (pathname.endsWith('/')) {
+    const indexed = get(pathname + 'index.html');
+    if (indexed !== undefined) return indexed;
+  } else {
+    const indexed = get(pathname + '/index.html');
+    if (indexed !== undefined) return indexed;
+  }
+
+  return null;
+}
+
+/**
+ * Synthesize the Response a matched file entry should produce.
+ *
+ * @param {ServedFile | null} entry
+ * @returns {Response | null} null if entry is null (caller should fall through to network)
+ */
+export function makeResponseForFile(entry) {
+  if (!entry) return null;
+  const headers = new Headers(entry.headers || {});
+  if (!headers.has('content-type')) {
+    headers.set('content-type', entry.contentType || 'application/octet-stream');
+  }
+  return new Response(entry.body, { status: entry.status || 200, headers });
+}
+
+/**
+ * End-to-end: given a request pathname and the known file map, produce the
+ * Response the Service Worker's `fetch` handler would return for an
+ * in-scope request, or null if it should fall through to the network.
+ *
+ * @param {string} pathname
+ * @param {Map<string, ServedFile> | Record<string, ServedFile>} files
+ * @returns {Response | null}
+ */
+export function resolveServiceWorkerResponse(pathname, files) {
+  const entry = matchFile(normalizeScopePath(pathname), files);
+  return makeResponseForFile(entry);
+}

package/src/service-worker-source.mjs

@@ -0,0 +1,139 @@
+/**
+ * Service Worker source code template for andbox's `service-worker` mode.
+ *
+ * Returns a string containing the entire Service Worker script. Zero file
+ * dependencies at runtime, same rationale as worker-source.mjs's
+ * makeWorkerSource(): the script is registered directly as a Service
+ * Worker scriptURL, so it can't `import` sibling andbox modules and
+ * inlines its own copy of the matching logic in service-worker-response.mjs
+ * instead.
+ *
+ * Unlike makeWorkerSource() (whose output is turned into a `blob:` URL and
+ * handed to `new Worker(...)`), this script CANNOT be served from a
+ * `blob:` URL -- Service Worker registration requires a real http(s)
+ * scriptURL (see andbox#14). The host application is responsible for
+ * serving this string's content as a real same-origin file at whatever
+ * path it passes as `scriptURL` to `createSandbox({ mode: 'service-worker' })`.
+ */
+
+/**
+ * Generate the Service Worker source code as a string.
+ *
+ * The Service Worker supports the following message types from the host
+ * (each sent with a `MessagePort` for an ack reply):
+ * - `configure`: Replace the entire served-file map
+ * - `define`: Add or replace one file
+ * - `remove`: Remove one file
+ *
+ * Lifecycle:
+ * - `install`: calls `skipWaiting()` so a new version activates promptly
+ *   instead of waiting for all controlled clients to close.
+ * - `activate`: calls `clients.claim()` so already-open clients in scope
+ *   are taken over without needing a reload. This does NOT by itself fix
+ *   the "first navigation" gotcha (see andbox#14) -- a navigation into
+ *   `scope` that happens *before* this Service Worker has finished
+ *   activating is a normal, unintercepted network request, full stop.
+ *   The host-side registration helper (`createSandbox({ mode:
+ *   'service-worker' })` in sandbox.mjs) handles this by resolving its
+ *   returned promise only once `activate` has completed, and the documented
+ *   contract is: don't navigate anything into `scope` until that promise
+ *   resolves. Do that, and every request from the very first one is
+ *   intercepted, because the registration is already active and matches
+ *   `scope` before the navigation request is even made.
+ * - `fetch`: in-scope requests matching a known path get a synthesized
+ *   Response; everything else (including cross-origin requests, which a
+ *   Service Worker can technically see but should not opaquely rewrite)
+ *   falls through to the network untouched.
+ *
+ * @returns {string} The Service Worker script source code.
+ */
+export function makeServiceWorkerSource() {
+  return `
+'use strict';
+
+// ── State ──
+const files = new Map(); // pathname ('/foo/bar.js') -> { body, contentType, status, headers }
+
+// ── Matching / response synthesis (inlined copy of service-worker-response.mjs) ──
+function normalizeScopePath(path) {
+  return path.startsWith('/') ? path : '/' + path;
+}
+
+function matchFile(pathname) {
+  if (files.has(pathname)) return files.get(pathname);
+  if (pathname.endsWith('/') && files.has(pathname + 'index.html')) {
+    return files.get(pathname + 'index.html');
+  }
+  if (!pathname.endsWith('/') && files.has(pathname + '/index.html')) {
+    return files.get(pathname + '/index.html');
+  }
+  return null;
+}
+
+function makeResponseForFile(entry) {
+  if (!entry) return null;
+  const headers = new Headers(entry.headers || {});
+  if (!headers.has('content-type')) {
+    headers.set('content-type', entry.contentType || 'application/octet-stream');
+  }
+  return new Response(entry.body, { status: entry.status || 200, headers });
+}
+
+// ── Lifecycle ──
+self.addEventListener('install', (event) => {
+  event.waitUntil(self.skipWaiting());
+});
+
+self.addEventListener('activate', (event) => {
+  // Claims already-open clients so they're controlled without a reload.
+  // Does NOT retroactively intercept a navigation that already completed
+  // as a plain network request before this finished -- see the doc
+  // comment on makeServiceWorkerSource() in service-worker-source.mjs for
+  // the ordering that actually avoids that race.
+  event.waitUntil(self.clients.claim());
+});
+
+// ── Host <-> SW config protocol ──
+self.addEventListener('message', (event) => {
+  const msg = event.data;
+  if (!msg || typeof msg.type !== 'string') return;
+  const reply = (payload) => {
+    if (event.ports && event.ports[0]) event.ports[0].postMessage(payload);
+  };
+
+  switch (msg.type) {
+    case 'configure': {
+      files.clear();
+      for (const [path, entry] of Object.entries(msg.files || {})) {
+        files.set(normalizeScopePath(path), entry);
+      }
+      reply({ type: 'configured' });
+      break;
+    }
+    case 'define': {
+      files.set(normalizeScopePath(msg.path), msg.entry);
+      reply({ type: 'defined', path: msg.path });
+      break;
+    }
+    case 'remove': {
+      files.delete(normalizeScopePath(msg.path));
+      reply({ type: 'removed', path: msg.path });
+      break;
+    }
+    default:
+      break;
+  }
+});
+
+// ── Request interception ──
+self.addEventListener('fetch', (event) => {
+  const url = new URL(event.request.url);
+  if (url.origin !== self.location.origin) return; // never touch cross-origin requests
+
+  const response = makeResponseForFile(matchFile(url.pathname));
+  if (!response) return; // not a known path -- fall through to the network
+
+  event.respondWith(response);
+});
+`;
+}

package/src/virtual-module-registry.mjs

@@ -0,0 +1,175 @@
+/**
+ * Virtual module registry — path → blob URL bookkeeping for a set of
+ * in-memory files that reference each other by relative path.
+ *
+ * Generalizes the single-file `new Blob([...]) + URL.createObjectURL()`
+ * pattern `createDataUriSandbox()` (src/sandbox.mjs) already uses for its
+ * one-file case into a `path → content` table, and reuses
+ * `resolveWithImportMap()` (src/import-map-resolver.mjs) for import-map
+ * resolution rather than reimplementing it.
+ */
+
+import { resolveWithImportMap } from './import-map-resolver.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) => boolean} has
+ * @property {() => string[]} paths
+ * @property {() => void} dispose
+ * @property {() => boolean} isDisposed
+ */
+
+/**
+ * Create a registry of in-memory files, each backed by its own `blob:` URL.
+ *
+ * @param {Record<string, string>} [files] - path → source text
+ * @param {{ 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
+  let disposed = false;
+
+  function blobify(path, source) {
+    const blob = new Blob([source], { type: 'text/javascript' });
+    const url = URL.createObjectURL(blob);
+    urls.set(path, url);
+    return url;
+  }
+
+  for (const [path, source] of Object.entries(files)) {
+    blobify(path, source);
+  }
+
+  function assertNotDisposed() {
+    if (disposed) throw new Error('Virtual module registry has been disposed');
+  }
+
+  /**
+   * Get the `blob:` URL registered for a path.
+   *
+   * @param {string} path
+   * @returns {string | null} the blob URL, or null if the path is unknown
+   */
+  function resolve(path) {
+    assertNotDisposed();
+    return urls.get(path) ?? null;
+  }
+
+  /**
+   * Register (or replace) a file at runtime. Replacing an existing path
+   * revokes its previous blob URL before minting a new one.
+   *
+   * @param {string} path
+   * @param {string} source
+   * @returns {string} the new blob URL
+   */
+  function define(path, source) {
+    assertNotDisposed();
+    if (urls.has(path)) URL.revokeObjectURL(urls.get(path));
+    return blobify(path, source);
+  }
+
+  /** @param {string} path */
+  function has(path) {
+    return urls.has(path);
+  }
+
+  /** @returns {string[]} */
+  function paths() {
+    return [...urls.keys()];
+  }
+
+  /**
+   * Resolve a module specifier the way `import` would need to, from the
+   * point of view of a given importing file. Checks three cases in order:
+   *
+   * 1. Import-map resolution (`imports`/`scopes`), delegated entirely to
+   *    `resolveWithImportMap()` — the same algorithm the worker-mode
+   *    sandbox's `sandboxImport()` uses. `parentPath`'s own blob URL (if
+   *    known) is passed through as `parentURL` so scoped rules apply.
+   * 2. A plain relative-path fallback (`./x.js`, `../x.js`) resolved
+   *    against `parentPath`'s directory and looked up in this registry's
+   *    path table. `resolveWithImportMap()` has no notion of "known
+   *    files" and returns null for these — this is the actual gap this
+   *    registry closes.
+   * 3. Unresolved — null. A bare specifier that isn't in the import map
+   *    and isn't a known relative path (a real npm/CDN specifier, say)
+   *    is left for the caller to handle; this registry does not swallow
+   *    it or guess.
+   *
+   * @param {string} specifier
+   * @param {string} [parentPath] - path of the file doing the importing
+   * @returns {string | null} a resolved URL, or null if nothing matched
+   */
+  function resolveSpecifier(specifier, parentPath) {
+    assertNotDisposed();
+
+    // 1. Import-map resolution (bare specifiers, prefix matches, scopes).
+    const parentURL = parentPath !== undefined ? urls.get(parentPath) : undefined;
+    const mapped = resolveWithImportMap(specifier, importMap, parentURL);
+    if (mapped !== null) return mapped;
+
+    // 2. Relative-path fallback against the known file table.
+    if (specifier.startsWith('./') || specifier.startsWith('../')) {
+      const targetPath = resolveRelativePath(parentPath || '', specifier);
+      const url = urls.get(targetPath);
+      if (url) return url;
+    }
+
+    // 3. Genuinely unresolved (e.g. a real external bare specifier).
+    return null;
+  }
+
+  /** Revoke every blob URL this registry has ever minted. */
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    for (const url of urls.values()) URL.revokeObjectURL(url);
+    urls.clear();
+  }
+
+  return {
+    resolve,
+    resolveSpecifier,
+    define,
+    has,
+    paths,
+    dispose,
+    isDisposed: () => disposed,
+  };
+}
+
+/**
+ * Resolve a relative specifier against the path of the importing file.
+ *
+ * Virtual module paths aren't real URLs, so this borrows the URL parser's
+ * relative-reference algorithm rather than hand-rolling one: parse
+ * `parentPath` under a synthetic hierarchical scheme (`vfs:///...`, which,
+ * unlike `blob:`, has an explicit — if empty — authority component and so
+ * is *not* treated as opaque/"cannot be a base URL"), resolve `specifier`
+ * against that, and strip the scheme back off.
+ *
+ * `parentPath` is a registered map key, not a URL -- it may legitimately
+ * contain `#`/`?`/other URL-delimiter characters as literal path text, so
+ * each segment is percent-encoded before being embedded in the synthetic
+ * base URL (otherwise a `#`/`?` in `parentPath` would be parsed as the
+ * *base URL's own* fragment/query, silently truncating everything after it
+ * before relative resolution even runs). `specifier` is left as-is: it's
+ * resolved with real URL relative-reference semantics on purpose, so a
+ * literal `#`/`?` in a specifier is treated as a fragment/query exactly as
+ * it would be in a real module specifier or href.
+ *
+ * @param {string} parentPath
+ * @param {string} specifier
+ * @returns {string}
+ */
+function resolveRelativePath(parentPath, specifier) {
+  const encodedParent = parentPath.split('/').map(encodeURIComponent).join('/');
+  const resolved = new URL(specifier, `vfs:///${encodedParent}`);
+  return decodeURIComponent(resolved.pathname.slice(1));
+}