@workerdeck/sandbox 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tobias Strebitzer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @workerdeck/sandbox
+
+Execution sandbox for untrusted, LLM-generated scripts: a QuickJS-NG guest compiled to
+WebAssembly, an in-memory scratch filesystem, and a hardened by-value host bridge. Deny-by-default
+— the guest has no filesystem, network, timers, or host access except the capabilities you grant.
+
+Part of [WorkerDeck](https://github.com/workerdeck/workerdeck). Leaf package: it
+depends on neither `core`/`server` nor any model SDK, so the same guest engine runs server-side
+(Node) and in a browser tab.
+
+## Install
+
+```bash
+npm install @workerdeck/sandbox @jitl/quickjs-ng-wasmfile-release-asyncify
+```
+
+The WASM engine variant is injected rather than bundled, so you pick the build that fits your
+target: `@jitl/quickjs-ng-wasmfile-release-asyncify` on the server,
+`@jitl/quickjs-singlefile-browser-release-asyncify` in the browser (no separate `.wasm` fetch).
+Use an **asyncify** variant — it lets guest code `await` a host function.
+
+## Usage
+
+```ts
+import variant from '@jitl/quickjs-ng-wasmfile-release-asyncify'
+import { createVfs, loadEngine, runScript } from '@workerdeck/sandbox'
+
+// Load once and reuse; the module is stateless.
+const engine = await loadEngine(variant)
+
+const vfs = createVfs({ '/docs/report.txt': 'revenue: 12' })
+
+const result = await runScript(engine, {
+  script: `
+    const doc = vfs.read('/docs/report.txt')
+    const revenue = Number(doc.split(':')[1])
+    vfs.write('/out/score.json', JSON.stringify({ revenue }))
+    revenue > 10 ? 'qualified' : 'skip'
+  `,
+  vfs,
+  memoryLimitBytes: 64 * 1024 * 1024,
+  timeoutMs: 5000,
+})
+
+if (result.ok) console.log(result.value, vfs.snapshot())
+else console.error(result.reason, result.error)
+```
+
+`runScript` never throws for guest misbehavior: exceptions, timeouts, and out-of-memory all come
+back as `{ ok: false, reason }` so an agent loop can adapt to them.
+
+## What the guest can reach
+
+Everything is granted explicitly; there is no ambient authority.
+
+| Guest global | Backed by | Notes |
+| --- | --- | --- |
+| `console.log/warn/error` | captured | returned as `result.logs`, never written to the host console |
+| `vfs.read/write/list` | the `vfs` option | absent-file reads return `undefined`; omit the option and writes throw |
+| `fetchText(url)` | the `fetchText` option | omit it and the guest throws; **you** own the allowlist |
+
+Absent by construction: `process`, `require`, `fetch`, `XMLHttpRequest`, `setTimeout`,
+`setInterval`, `WebAssembly`, and any module loader.
+
+## Limits
+
+`memoryLimitBytes` (default 64 MiB) caps the QuickJS allocator, and `timeoutMs` (default 5000) is
+enforced by an interrupt handler that runs between bytecode operations — so an infinite loop is
+preempted in-thread, with no worker and no cross-origin isolation. Each call gets a fresh runtime
+and context; nothing carries over between runs.
+
+**The deadline does not cover time spent inside your host functions.** The interpreter is not
+executing while a host call is in flight, so put an independent timeout on every capability you
+grant — especially `fetchText`.
+
+## Security model
+
+The WebAssembly boundary is the easy part; the host bridge is the attack surface. Values cross it
+**by value only** (strings and JSON), and a host object is never handed to the guest by reference.
+That rule is what the guest-realm escape test exercises: walking `({}).constructor.constructor`
+to `globalThis` succeeds, and lands in the guest's own realm with nothing of the host's in it.
+This is the failure mode behind CVE-2026-5752, where a mock object's prototype chain leaked a
+path to the host's `require()`.
+
+If you extend the bridge, keep to it: marshal by value, freeze or null-prototype anything you
+construct for the guest, and give every capability its own timeout.
+
+## License
+
+MIT

package/build/index.d.mts

@@ -0,0 +1,81 @@
+import { QuickJSAsyncVariant, QuickJSAsyncWASMModule } from "quickjs-emscripten-core";
+
+//#region src/vfs.d.ts
+/**
+ * Per-call in-memory scratch filesystem. Seeded from the task's documents,
+ * discarded after the call — never backed by host paths. The guest only ever
+ * touches it through the by-value host bridge (vfs_read/vfs_write/vfs_list).
+ *
+ * A plain path→content map on purpose: this package must run unpolyfilled in
+ * the browser (the tab-side tool host seeds a VFS per bridged call), and a
+ * node-flavored fs emulation drags `node:buffer` in with it.
+ */
+type SandboxVfs = {
+  read(path: string): string | undefined;
+  write(path: string, content: string): void; /** File paths under `dir` (recursive), sorted. */
+  list(dir?: string): string[]; /** Full path → content map (e.g. to collect results after a run). */
+  snapshot(): Record<string, string>;
+};
+/** Collapse '.', '..' and empty segments into a rooted absolute path — the VFS
+ * has no host backing to escape into, this is pure path hygiene. */
+declare function normalizeVfsPath(path: string): string;
+declare function createVfs(seed?: Record<string, string>): SandboxVfs;
+//#endregion
+//#region src/run-script.d.ts
+/**
+ * The guest engine, loaded from an injected WASM variant so server (Node
+ * asyncify) and browser (singlefile asyncify) share this package unchanged.
+ * Load once and reuse — the module is stateless; runtimes/contexts are per call.
+ */
+type SandboxEngine = {
+  module: QuickJSAsyncWASMModule;
+};
+/** Accepts the variant itself, a `{ default }` module namespace, or a promise of
+ * either — so callers can pass `import('...')` or a plain default import without
+ * caring how their bundler/runtime resolved the interop. */
+type SandboxVariantInput = QuickJSAsyncVariant | {
+  default: QuickJSAsyncVariant;
+} | Promise<QuickJSAsyncVariant | {
+  default: QuickJSAsyncVariant;
+}>;
+declare function loadEngine(variant: SandboxVariantInput): Promise<SandboxEngine>;
+type SandboxLog = {
+  level: 'log' | 'warn' | 'error';
+  text: string;
+};
+type RunScriptOptions = {
+  /** Untrusted, typically LLM-generated source. Evaluated as global code. */script: string; /** Scratch filesystem exposed to the guest as `vfs.read/write/list`. */
+  vfs?: SandboxVfs;
+  /**
+   * Host-gated network capability, exposed to the guest as `fetchText(url)`.
+   * The CALLER owns the allowlist, credential injection, and a per-call
+   * timeout — the guest never holds a credential and this module never
+   * touches the network itself. Unset = `fetchText` throws in the guest.
+   */
+  fetchText?: (url: string) => Promise<string>; /** QuickJS allocator cap. Guest OOM is a failed result, not a host crash. Default 64 MiB. */
+  memoryLimitBytes?: number;
+  /** Wall-clock deadline enforced by the interrupt handler between bytecode ops.
+   * Does NOT cover time inside host functions — bound those caller-side. Default 5000. */
+  timeoutMs?: number; /** Guest stack cap. Default 1 MiB. */
+  maxStackSizeBytes?: number;
+  signal?: AbortSignal;
+};
+type RunScriptResult = {
+  ok: true;
+  value: unknown;
+  logs: SandboxLog[];
+} | {
+  ok: false;
+  reason: 'exception' | 'timeout' | 'oom' | 'aborted';
+  error: string;
+  logs: SandboxLog[];
+};
+/**
+ * Evaluate one untrusted script in a fresh QuickJS context: deny-by-default
+ * (no ambient fs/network/host access — only the granted bridge), interpreter-
+ * enforced memory and time limits, everything disposed afterwards.
+ */
+declare function runScript(engine: SandboxEngine, options: RunScriptOptions): Promise<RunScriptResult>;
+//#endregion
+export { type RunScriptOptions, type RunScriptResult, type SandboxEngine, type SandboxLog, type SandboxVariantInput, type SandboxVfs, createVfs, loadEngine, normalizeVfsPath, runScript };
+//# sourceMappingURL=index.d.mts.map

package/build/index.mjs

@@ -0,0 +1,203 @@
+import { newQuickJSAsyncWASMModuleFromVariant } from "quickjs-emscripten-core";
+//#region src/vfs.ts
+/** Collapse '.', '..' and empty segments into a rooted absolute path — the VFS
+* has no host backing to escape into, this is pure path hygiene. */
+function normalizeVfsPath(path) {
+	const out = [];
+	for (const part of path.split("/")) {
+		if (part === "" || part === ".") continue;
+		if (part === "..") {
+			out.pop();
+			continue;
+		}
+		out.push(part);
+	}
+	return "/" + out.join("/");
+}
+function createVfs(seed) {
+	const files = /* @__PURE__ */ new Map();
+	const write = (path, content) => {
+		files.set(normalizeVfsPath(path), content);
+	};
+	for (const [path, content] of Object.entries(seed ?? {})) write(path, content);
+	return {
+		read(path) {
+			return files.get(normalizeVfsPath(path));
+		},
+		write,
+		list(dir = "/") {
+			const prefix = normalizeVfsPath(dir);
+			return [...files.keys()].filter((file) => prefix === "/" || file === prefix || file.startsWith(prefix + "/")).sort();
+		},
+		snapshot() {
+			return Object.fromEntries(files);
+		}
+	};
+}
+//#endregion
+//#region src/run-script.ts
+async function loadEngine(variant) {
+	const resolved = await variant;
+	return { module: await newQuickJSAsyncWASMModuleFromVariant("default" in resolved ? resolved.default : resolved) };
+}
+/** Trusted prelude, evaluated before the untrusted script: ergonomic frozen
+* wrappers over the raw host functions. Everything crossing the boundary is a
+* string (by-value marshalling — never a host object reference). */
+const PRELUDE = `
+"use strict";
+(() => {
+  const fmt = (v) => {
+    if (typeof v === 'string') return v
+    if (v === undefined) return 'undefined'
+    try { return JSON.stringify(v) } catch { return String(v) }
+  }
+  globalThis.console = Object.freeze({
+    log: (...a) => __host_log('log', a.map(fmt).join(' ')),
+    warn: (...a) => __host_log('warn', a.map(fmt).join(' ')),
+    error: (...a) => __host_log('error', a.map(fmt).join(' ')),
+  })
+  globalThis.vfs = Object.freeze({
+    read: (p) => __host_vfs_read(String(p)),
+    write: (p, c) => { __host_vfs_write(String(p), String(c)) },
+    list: (d) => JSON.parse(__host_vfs_list(d === undefined ? '/' : String(d))),
+  })
+  globalThis.fetchText = (u) => __host_fetch_text(String(u))
+})();
+`;
+/**
+* Evaluate one untrusted script in a fresh QuickJS context: deny-by-default
+* (no ambient fs/network/host access — only the granted bridge), interpreter-
+* enforced memory and time limits, everything disposed afterwards.
+*/
+async function runScript(engine, options) {
+	const logs = [];
+	const deadline = Date.now() + (options.timeoutMs ?? 5e3);
+	let interruptedBy;
+	const runtime = engine.module.newRuntime();
+	runtime.setMemoryLimit(options.memoryLimitBytes ?? 64 * 1024 * 1024);
+	runtime.setMaxStackSize(options.maxStackSizeBytes ?? 1024 * 1024);
+	runtime.setInterruptHandler(() => {
+		if (options.signal?.aborted) {
+			interruptedBy = "aborted";
+			return true;
+		}
+		if (Date.now() > deadline) {
+			interruptedBy = "timeout";
+			return true;
+		}
+		return false;
+	});
+	const context = runtime.newContext();
+	const defineHostFn = (name, fn) => {
+		const handle = context.newFunction(name, (...args) => fn(...args) ?? context.undefined);
+		context.setProp(context.global, name, handle);
+		handle.dispose();
+	};
+	try {
+		defineHostFn("__host_log", (levelHandle, textHandle) => {
+			const level = context.getString(levelHandle);
+			logs.push({
+				level: level === "warn" || level === "error" ? level : "log",
+				text: context.getString(textHandle)
+			});
+		});
+		defineHostFn("__host_vfs_read", (pathHandle) => {
+			const content = options.vfs?.read(context.getString(pathHandle));
+			return content === void 0 ? void 0 : context.newString(content);
+		});
+		defineHostFn("__host_vfs_write", (pathHandle, contentHandle) => {
+			if (!options.vfs) throw new Error("vfs is not enabled for this execution");
+			options.vfs.write(context.getString(pathHandle), context.getString(contentHandle));
+		});
+		defineHostFn("__host_vfs_list", (dirHandle) => {
+			const files = options.vfs?.list(context.getString(dirHandle)) ?? [];
+			return context.newString(JSON.stringify(files));
+		});
+		{
+			const fetchText = options.fetchText;
+			const handle = context.newAsyncifiedFunction("__host_fetch_text", async (urlHandle) => {
+				const url = context.getString(urlHandle);
+				if (!fetchText) throw new Error("network access is not enabled for this execution");
+				return context.newString(await fetchText(url));
+			});
+			context.setProp(context.global, "__host_fetch_text", handle);
+			handle.dispose();
+		}
+		const prelude = await context.evalCodeAsync(PRELUDE, "prelude.js");
+		context.unwrapResult(prelude).dispose();
+		const evaluated = await context.evalCodeAsync(options.script, "script.js");
+		if (evaluated.error) {
+			const error = context.dump(evaluated.error);
+			evaluated.error.dispose();
+			return failure(error, interruptedBy, logs);
+		}
+		runtime.executePendingJobs();
+		const evaluatedValue = evaluated.value;
+		const state = context.getPromiseState(evaluatedValue);
+		if (state.type === "pending") {
+			const settledPromise = context.resolvePromise(evaluatedValue);
+			runtime.executePendingJobs();
+			const settled = await settledPromise;
+			evaluatedValue.dispose();
+			if (settled.error) {
+				const error = context.dump(settled.error);
+				settled.error.dispose();
+				return failure(error, interruptedBy, logs);
+			}
+			const value = context.dump(settled.value);
+			settled.value.dispose();
+			return {
+				ok: true,
+				value,
+				logs
+			};
+		}
+		if (state.type === "rejected") {
+			const error = context.dump(state.error);
+			evaluatedValue.dispose();
+			return failure(error, interruptedBy, logs);
+		}
+		const resultHandle = state.type === "fulfilled" && !state.notAPromise ? state.value : evaluatedValue;
+		const value = context.dump(resultHandle);
+		if (resultHandle !== evaluatedValue) resultHandle.dispose();
+		evaluatedValue.dispose();
+		return {
+			ok: true,
+			value,
+			logs
+		};
+	} catch (error) {
+		return failure(error instanceof Error ? error.message : String(error), interruptedBy, logs);
+	} finally {
+		context.dispose();
+		runtime.dispose();
+	}
+}
+function failure(error, interruptedBy, logs) {
+	const text = describeGuestError(error);
+	return {
+		ok: false,
+		reason: interruptedBy ?? (/out of memory/i.test(text) ? "oom" : "exception"),
+		error: text,
+		logs
+	};
+}
+function describeGuestError(error) {
+	if (typeof error === "string") return error;
+	if (error && typeof error === "object") {
+		const e = error;
+		const name = typeof e.name === "string" ? e.name : void 0;
+		const message = typeof e.message === "string" ? e.message : void 0;
+		if (name || message) return [name, message].filter(Boolean).join(": ");
+		try {
+			return JSON.stringify(error);
+		} catch {
+			return String(error);
+		}
+	}
+	return String(error);
+}
+//#endregion
+export { createVfs, loadEngine, normalizeVfsPath, runScript };
+
+//# sourceMappingURL=index.mjs.map

package/build/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/vfs.ts","../src/run-script.ts"],"sourcesContent":["/**\n * Per-call in-memory scratch filesystem. Seeded from the task's documents,\n * discarded after the call — never backed by host paths. The guest only ever\n * touches it through the by-value host bridge (vfs_read/vfs_write/vfs_list).\n *\n * A plain path→content map on purpose: this package must run unpolyfilled in\n * the browser (the tab-side tool host seeds a VFS per bridged call), and a\n * node-flavored fs emulation drags `node:buffer` in with it.\n */\nexport type SandboxVfs = {\n  read(path: string): string | undefined\n  write(path: string, content: string): void\n  /** File paths under `dir` (recursive), sorted. */\n  list(dir?: string): string[]\n  /** Full path → content map (e.g. to collect results after a run). */\n  snapshot(): Record<string, string>\n}\n\n/** Collapse '.', '..' and empty segments into a rooted absolute path — the VFS\n * has no host backing to escape into, this is pure path hygiene. */\nexport function normalizeVfsPath(path: string): string {\n  const out: string[] = []\n  for (const part of path.split('/')) {\n    if (part === '' || part === '.') continue\n    if (part === '..') {\n      out.pop()\n      continue\n    }\n    out.push(part)\n  }\n  return '/' + out.join('/')\n}\n\nexport function createVfs(seed?: Record<string, string>): SandboxVfs {\n  const files = new Map<string, string>()\n  const write = (path: string, content: string): void => {\n    files.set(normalizeVfsPath(path), content)\n  }\n  for (const [path, content] of Object.entries(seed ?? {})) write(path, content)\n  return {\n    read(path) {\n      return files.get(normalizeVfsPath(path))\n    },\n    write,\n    list(dir = '/') {\n      const prefix = normalizeVfsPath(dir)\n      return [...files.keys()]\n        .filter((file) => prefix === '/' || file === prefix || file.startsWith(prefix + '/'))\n        .sort()\n    },\n    snapshot() {\n      return Object.fromEntries(files)\n    },\n  }\n}\n","import {\n  newQuickJSAsyncWASMModuleFromVariant,\n  type QuickJSAsyncVariant,\n  type QuickJSAsyncWASMModule,\n  type QuickJSHandle,\n} from 'quickjs-emscripten-core'\nimport type { SandboxVfs } from './vfs.ts'\n\n/**\n * The guest engine, loaded from an injected WASM variant so server (Node\n * asyncify) and browser (singlefile asyncify) share this package unchanged.\n * Load once and reuse — the module is stateless; runtimes/contexts are per call.\n */\nexport type SandboxEngine = { module: QuickJSAsyncWASMModule }\n\n/** Accepts the variant itself, a `{ default }` module namespace, or a promise of\n * either — so callers can pass `import('...')` or a plain default import without\n * caring how their bundler/runtime resolved the interop. */\nexport type SandboxVariantInput =\n  | QuickJSAsyncVariant\n  | { default: QuickJSAsyncVariant }\n  | Promise<QuickJSAsyncVariant | { default: QuickJSAsyncVariant }>\n\nexport async function loadEngine(variant: SandboxVariantInput): Promise<SandboxEngine> {\n  const resolved = await variant\n  const unwrapped = 'default' in resolved ? resolved.default : resolved\n  return { module: await newQuickJSAsyncWASMModuleFromVariant(unwrapped) }\n}\n\nexport type SandboxLog = { level: 'log' | 'warn' | 'error'; text: string }\n\nexport type RunScriptOptions = {\n  /** Untrusted, typically LLM-generated source. Evaluated as global code. */\n  script: string\n  /** Scratch filesystem exposed to the guest as `vfs.read/write/list`. */\n  vfs?: SandboxVfs\n  /**\n   * Host-gated network capability, exposed to the guest as `fetchText(url)`.\n   * The CALLER owns the allowlist, credential injection, and a per-call\n   * timeout — the guest never holds a credential and this module never\n   * touches the network itself. Unset = `fetchText` throws in the guest.\n   */\n  fetchText?: (url: string) => Promise<string>\n  /** QuickJS allocator cap. Guest OOM is a failed result, not a host crash. Default 64 MiB. */\n  memoryLimitBytes?: number\n  /** Wall-clock deadline enforced by the interrupt handler between bytecode ops.\n   * Does NOT cover time inside host functions — bound those caller-side. Default 5000. */\n  timeoutMs?: number\n  /** Guest stack cap. Default 1 MiB. */\n  maxStackSizeBytes?: number\n  signal?: AbortSignal\n}\n\nexport type RunScriptResult =\n  | { ok: true; value: unknown; logs: SandboxLog[] }\n  | {\n      ok: false\n      reason: 'exception' | 'timeout' | 'oom' | 'aborted'\n      error: string\n      logs: SandboxLog[]\n    }\n\n/** Trusted prelude, evaluated before the untrusted script: ergonomic frozen\n * wrappers over the raw host functions. Everything crossing the boundary is a\n * string (by-value marshalling — never a host object reference). */\nconst PRELUDE = `\n\"use strict\";\n(() => {\n  const fmt = (v) => {\n    if (typeof v === 'string') return v\n    if (v === undefined) return 'undefined'\n    try { return JSON.stringify(v) } catch { return String(v) }\n  }\n  globalThis.console = Object.freeze({\n    log: (...a) => __host_log('log', a.map(fmt).join(' ')),\n    warn: (...a) => __host_log('warn', a.map(fmt).join(' ')),\n    error: (...a) => __host_log('error', a.map(fmt).join(' ')),\n  })\n  globalThis.vfs = Object.freeze({\n    read: (p) => __host_vfs_read(String(p)),\n    write: (p, c) => { __host_vfs_write(String(p), String(c)) },\n    list: (d) => JSON.parse(__host_vfs_list(d === undefined ? '/' : String(d))),\n  })\n  globalThis.fetchText = (u) => __host_fetch_text(String(u))\n})();\n`\n\n/**\n * Evaluate one untrusted script in a fresh QuickJS context: deny-by-default\n * (no ambient fs/network/host access — only the granted bridge), interpreter-\n * enforced memory and time limits, everything disposed afterwards.\n */\nexport async function runScript(engine: SandboxEngine, options: RunScriptOptions): Promise<RunScriptResult> {\n  const logs: SandboxLog[] = []\n  const deadline = Date.now() + (options.timeoutMs ?? 5000)\n  let interruptedBy: 'timeout' | 'aborted' | undefined\n\n  const runtime = engine.module.newRuntime()\n  runtime.setMemoryLimit(options.memoryLimitBytes ?? 64 * 1024 * 1024)\n  runtime.setMaxStackSize(options.maxStackSizeBytes ?? 1024 * 1024)\n  runtime.setInterruptHandler(() => {\n    if (options.signal?.aborted) {\n      interruptedBy = 'aborted'\n      return true\n    }\n    if (Date.now() > deadline) {\n      interruptedBy = 'timeout'\n      return true\n    }\n    return false\n  })\n  const context = runtime.newContext()\n\n  const defineHostFn = (name: string, fn: (...args: QuickJSHandle[]) => QuickJSHandle | undefined): void => {\n    const handle = context.newFunction(name, (...args) => fn(...args) ?? context.undefined)\n    context.setProp(context.global, name, handle)\n    handle.dispose()\n  }\n\n  try {\n    defineHostFn('__host_log', (levelHandle, textHandle) => {\n      const level = context.getString(levelHandle)\n      logs.push({\n        level: level === 'warn' || level === 'error' ? level : 'log',\n        text: context.getString(textHandle),\n      })\n      return undefined\n    })\n    defineHostFn('__host_vfs_read', (pathHandle) => {\n      const content = options.vfs?.read(context.getString(pathHandle))\n      return content === undefined ? undefined : context.newString(content)\n    })\n    defineHostFn('__host_vfs_write', (pathHandle, contentHandle) => {\n      if (!options.vfs) throw new Error('vfs is not enabled for this execution')\n      options.vfs.write(context.getString(pathHandle), context.getString(contentHandle))\n      return undefined\n    })\n    defineHostFn('__host_vfs_list', (dirHandle) => {\n      const files = options.vfs?.list(context.getString(dirHandle)) ?? []\n      return context.newString(JSON.stringify(files))\n    })\n    {\n      const fetchText = options.fetchText\n      const handle = context.newAsyncifiedFunction('__host_fetch_text', async (urlHandle) => {\n        const url = context.getString(urlHandle)\n        if (!fetchText) throw new Error('network access is not enabled for this execution')\n        return context.newString(await fetchText(url))\n      })\n      context.setProp(context.global, '__host_fetch_text', handle)\n      handle.dispose()\n    }\n\n    const prelude = await context.evalCodeAsync(PRELUDE, 'prelude.js')\n    context.unwrapResult(prelude).dispose()\n\n    const evaluated = await context.evalCodeAsync(options.script, 'script.js')\n    if (evaluated.error) {\n      const error = context.dump(evaluated.error)\n      evaluated.error.dispose()\n      return failure(error, interruptedBy, logs)\n    }\n    // Drain the microtask queue so a returned promise can settle. resolvePromise()\n    // takes ownership of the handle it is given — never dispose that one again.\n    runtime.executePendingJobs()\n    const evaluatedValue = evaluated.value\n    const state = context.getPromiseState(evaluatedValue)\n    if (state.type === 'pending') {\n      const settledPromise = context.resolvePromise(evaluatedValue)\n      runtime.executePendingJobs()\n      const settled = await settledPromise\n      evaluatedValue.dispose()\n      if (settled.error) {\n        const error = context.dump(settled.error)\n        settled.error.dispose()\n        return failure(error, interruptedBy, logs)\n      }\n      const value = context.dump(settled.value)\n      settled.value.dispose()\n      return { ok: true, value, logs }\n    }\n    if (state.type === 'rejected') {\n      const error = context.dump(state.error)\n      evaluatedValue.dispose()\n      return failure(error, interruptedBy, logs)\n    }\n    const resultHandle = state.type === 'fulfilled' && !state.notAPromise ? state.value : evaluatedValue\n    const value = context.dump(resultHandle)\n    if (resultHandle !== evaluatedValue) resultHandle.dispose()\n    evaluatedValue.dispose()\n    return { ok: true, value, logs }\n  } catch (error) {\n    return failure(error instanceof Error ? error.message : String(error), interruptedBy, logs)\n  } finally {\n    context.dispose()\n    runtime.dispose()\n  }\n}\n\nfunction failure(\n  error: unknown,\n  interruptedBy: 'timeout' | 'aborted' | undefined,\n  logs: SandboxLog[],\n): RunScriptResult {\n  const text = describeGuestError(error)\n  const reason = interruptedBy ?? (/out of memory/i.test(text) ? 'oom' : 'exception')\n  return { ok: false, reason, error: text, logs }\n}\n\nfunction describeGuestError(error: unknown): string {\n  if (typeof error === 'string') return error\n  if (error && typeof error === 'object') {\n    const e = error as { name?: unknown; message?: unknown }\n    const name = typeof e.name === 'string' ? e.name : undefined\n    const message = typeof e.message === 'string' ? e.message : undefined\n    if (name || message) return [name, message].filter(Boolean).join(': ')\n    try {\n      return JSON.stringify(error)\n    } catch {\n      return String(error)\n    }\n  }\n  return String(error)\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@workerdeck/sandbox",
+  "version": "0.6.0",
+  "type": "module",
+  "description": "The WorkerDeck execution sandbox: QuickJS-NG-in-WASM guest for untrusted, LLM-generated scripts with an in-memory scratch VFS, a hardened by-value host bridge (capability host functions only — no ambient fs/network), and interpreter-enforced memory + wall-clock limits. Engine-variant-injected so server (Node asyncify) and browser (singlefile asyncify) share one guest engine. Leaf package: depends on neither core/server nor any model SDK.",
+  "license": "MIT",
+  "main": "./build/index.mjs",
+  "types": "./build/index.d.mts",
+  "files": [
+    "build"
+  ],
+  "exports": {
+    ".": {
+      "@workerdeck/source": "./src/index.ts",
+      "types": "./build/index.d.mts",
+      "default": "./build/index.mjs"
+    }
+  },
+  "dependencies": {
+    "quickjs-emscripten-core": "^0.31.0"
+  },
+  "devDependencies": {
+    "@jitl/quickjs-ng-wasmfile-release-asyncify": "^0.31.0",
+    "@types/node": "^22.10.0",
+    "rimraf": "^6.1.3",
+    "tsdown": "^0.21.10",
+    "vitest": "^3.2.0"
+  },
+  "author": "Tobias Strebitzer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/workerdeck/workerdeck.git",
+    "directory": "packages/sandbox"
+  },
+  "homepage": "https://workerdeck.github.io/workerdeck/",
+  "bugs": "https://github.com/workerdeck/workerdeck/issues",
+  "keywords": [
+    "claude",
+    "sandbox",
+    "quickjs",
+    "wasm",
+    "untrusted-code",
+    "agent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rimraf build",
+    "build": "tsdown",
+    "typecheck": "tsgo -p tsconfig.json",
+    "test": "vitest run"
+  }
+}