@nodetool-ai/sandbox-runtime 0.0.0-stage → 0.8.9-beta.2

package/dist/js-sandbox-worker/worker-entry.js

@@ -0,0 +1,308 @@
+/**
+ * Worker main for the off-thread QuickJS sandbox.
+ *
+ * One engine per worker, one run at a time. Everything the guest reaches that
+ * lives on the main thread — every bridge, every dispatcher, every
+ * function-valued caller global — is rebuilt here as a proxy that posts an RPC
+ * and awaits the reply, which is indistinguishable from an ordinary async host
+ * function to the library's `expose()`.
+ *
+ * Three things are deliberately *not* proxied, because the guest reads them
+ * synchronously and a round trip has no synchronous answer: `crypto.randomUUID`
+ * and `crypto.getRandomValues`, which are reimplemented over the worker's own
+ * WebCrypto, and `stream.open`, which is served from a mirror seeded at run
+ * start and push-updated when a handle closes.
+ *
+ * This module is never statically imported by `js-sandbox.ts` — it is loaded
+ * only as a worker entry.
+ */
+import { createLogger, importNodeBuiltin } from "@nodetool-ai/config";
+import { loadSandboxEngine } from "./engine.js";
+import { toGuestBytes } from "../sandbox-bytes.js";
+import { MAX_RANDOM_BYTES } from "../sandbox-constants.js";
+import { registerTypedArraySerializers, runInterpreter, SANDBOX_STREAM_OPEN_BINDING } from "./interpreter.js";
+import { interpreterResultMessage, isHostToWorkerMessage, SANDBOX_DISPATCHER_BINDINGS } from "./protocol.js";
+import * as quickJsVariantModule from "@jitl/quickjs-ng-wasmfile-release-sync";
+import { isFiniteNumber, isObjectLike } from "../utils/type-guards.js";
+/**
+ * The variant package is CJS with a `default` export, so `ns.default` is the
+ * variant at runtime.
+ */
+// SAFETY: TypeScript's CJS interop synthesizes `default` as the whole module
+// object, contradicting the package's own `.d.ts`, which declares it as the
+// `QuickJSSyncVariant` this reads.
+const quickJsVariant = quickJsVariantModule.default;
+const log = createLogger("nodetool.agents.sandbox-worker");
+const SLOW_SANDBOX_RUN_MS = 1_000;
+// ---------------------------------------------------------------------------
+// Engine
+// ---------------------------------------------------------------------------
+let enginePromise = null;
+/**
+ * One engine per worker.
+ *
+ * `registerTypedArraySerializers` mutates the library's module-global
+ * serializer table, and a worker holds its own module instance, so it registers
+ * its own before the first run.
+ */
+function getEngine() {
+    registerTypedArraySerializers();
+    if (!enginePromise)
+        enginePromise = loadSandboxEngine(quickJsVariant);
+    return enginePromise;
+}
+class RunSession {
+    port;
+    run;
+    pending = new Map();
+    nextRpcId = 0;
+    suspended = 0;
+    streamOpen;
+    constructor(port, run) {
+        this.port = port;
+        this.run = run;
+        this.streamOpen = new Map(Object.entries(run.streamOpenSeed ?? {}));
+    }
+    suspendedMs = () => this.suspended;
+    setSuspendedMs(value) {
+        this.suspended = value;
+    }
+    closeStream(handle) {
+        this.streamOpen.set(handle, false);
+    }
+    /**
+     * Answer `stream.open(handle)` from the mirror.
+     *
+     * `null` means the run carries no input stream at all — the prelude turns
+     * that into the no-input-stream throw, matching the in-process binding. A
+     * stale `true` is harmless: streams are close-only, so the worst case is
+     * one extra take that comes back done.
+     */
+    isStreamOpen = (handle) => this.run.streamOpenSeed === null
+        ? null
+        : this.streamOpen.get(String(handle)) === true;
+    settleRpc(id, ok, value, error) {
+        const pending = this.pending.get(id);
+        if (pending === undefined)
+            return;
+        this.pending.delete(id);
+        if (ok)
+            pending.resolve(value);
+        else
+            pending.reject(error ?? new Error("the sandbox bridge call failed"));
+    }
+    call(path, args) {
+        const id = this.nextRpcId++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.port.postMessage({ type: "rpc", id, path, args });
+        });
+    }
+    log(line) {
+        this.port.postMessage({ type: "log", line });
+    }
+    progress(percent, message) {
+        this.port.postMessage(message === undefined
+            ? { type: "progress", percent }
+            : { type: "progress", percent, message });
+    }
+}
+// ---------------------------------------------------------------------------
+// Bridge reconstruction
+// ---------------------------------------------------------------------------
+/** Random bytes, tagged the way the host bridge tags them. */
+function getRandomValues(requested) {
+    const size = isFiniteNumber(requested)
+        ? Math.min(Math.max(Math.floor(requested), 0), MAX_RANDOM_BYTES)
+        : 0;
+    const bytes = new Uint8Array(size);
+    if (size > 0)
+        globalThis.crypto.getRandomValues(bytes);
+    return toGuestBytes(bytes);
+}
+/** One RPC proxy, indistinguishable from an async host function to `expose()`. */
+function proxyFor(session, path) {
+    return (...args) => session.call(path, args);
+}
+/**
+ * Rebuild the record `buildSandbox` would have produced, from names alone.
+ *
+ * Every entry is an RPC proxy, a value that travelled by clone, or one of the
+ * three synchronous locals this worker owns. Those three are handed over
+ * unwrapped and the interpreter passes them through unwrapped: a round trip has
+ * no synchronous answer, and `stream.open` in particular is a function that
+ * must never be wrapped.
+ */
+function buildSandboxRecord(shape, session) {
+    const sandbox = {};
+    for (const name of shape.flat)
+        sandbox[name] = proxyFor(session, [name]);
+    for (const [name, value] of Object.entries(shape.values))
+        sandbox[name] = value;
+    for (const [name, members] of Object.entries(shape.objects)) {
+        const table = {};
+        for (const member of members)
+            table[member] = proxyFor(session, [name, member]);
+        sandbox[name] = table;
+    }
+    // `crypto.digest`/`hmac` stay proxied; the other two are worker-local.
+    const crypto = (sandbox.crypto ?? {});
+    crypto.randomUUID = () => globalThis.crypto.randomUUID();
+    crypto.getRandomValues = getRandomValues;
+    sandbox.crypto = crypto;
+    sandbox[SANDBOX_STREAM_OPEN_BINDING] = session.isStreamOpen;
+    return sandbox;
+}
+/**
+ * Caller globals, kept apart from the sandbox record.
+ *
+ * The interpreter applies them last so a global can shadow a non-reserved
+ * name, and it is the only place where "function → wrap, value → pass through"
+ * is the right rule. Merging them into the sandbox record would lose that.
+ */
+function buildGlobalsRecord(shape, session) {
+    const globals = {};
+    for (const [name, global] of Object.entries(shape.globals)) {
+        globals[name] =
+            global.kind === "fn" ? proxyFor(session, [name]) : global.value;
+    }
+    return globals;
+}
+/** Object-typed globals, whose contents are read back out of the guest. */
+function syncTargetNames(shape) {
+    return Object.entries(shape.globals)
+        .filter(([, global]) => global.kind === "value" &&
+        isObjectLike(global.value))
+        .map(([name]) => name);
+}
+/**
+ * A dispatcher proxy, present only when the run declared that kind.
+ *
+ * Presence is what decides the guest binding and the init prelude's
+ * conditional text, so the three travel as named optionals rather than as keys
+ * in an untyped record.
+ */
+function dispatcherCall(shape, session, kind) {
+    if (!shape.dispatchers.includes(kind))
+        return undefined;
+    const binding = SANDBOX_DISPATCHER_BINDINGS[kind];
+    const proxy = proxyFor(session, [binding]);
+    return (moduleKey, exportName, args) => proxy(moduleKey, exportName, args);
+}
+// ---------------------------------------------------------------------------
+// Worker main
+// ---------------------------------------------------------------------------
+/**
+ * An optional param, omitted rather than passed as `undefined`.
+ *
+ * The interpreter reads presence, not value: a `wasmCall` key that is there and
+ * undefined would still be a declared dispatcher.
+ */
+function spreadIfSet(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+async function executeRun(port, run, session) {
+    const startedAt = performance.now();
+    const engineStartedAt = performance.now();
+    const { runSandboxed } = await getEngine();
+    const engineMs = performance.now() - engineStartedAt;
+    const shape = run.bridgeShape;
+    let interpreterTiming;
+    let outcome;
+    let failed = false;
+    try {
+        outcome = await runInterpreter({
+            runSandboxed,
+            code: run.code,
+            sandbox: buildSandboxRecord(shape, session),
+            globals: buildGlobalsRecord(shape, session),
+            syncTargetNames: syncTargetNames(shape),
+            ...spreadIfSet("wasmCall", dispatcherCall(shape, session, "wasm")),
+            ...spreadIfSet("hostCall", dispatcherCall(shape, session, "host")),
+            ...spreadIfSet("capabilityCall", dispatcherCall(shape, session, "capability")),
+            ...spreadIfSet("modules", run.modules),
+            ...spreadIfSet("capabilityFacades", run.capabilityFacades),
+            timeoutMs: run.timeoutMs,
+            limits: run.limits,
+            suspendAllowanceMs: run.suspendAllowanceMs,
+            hasClock: run.hasClock,
+            // No isAborted: cancellation from the host is `worker.terminate()`, so the
+            // interrupt handler in here enforces only the deadline.
+            suspendedMs: session.suspendedMs,
+            onTiming: (timing) => {
+                interpreterTiming = timing;
+            }
+        });
+    }
+    catch (error) {
+        failed = true;
+        throw error;
+    }
+    finally {
+        const totalMs = performance.now() - startedAt;
+        if (totalMs >= SLOW_SANDBOX_RUN_MS) {
+            log.warn("Slow sandbox worker run", {
+                runId: run.runId,
+                engineMs,
+                interpreter: interpreterTiming,
+                failed,
+                totalMs
+            });
+        }
+    }
+    port.postMessage(interpreterResultMessage(run.runId, outcome));
+}
+export async function startWorker(port) {
+    let session;
+    port.on("message", (raw) => {
+        if (!isHostToWorkerMessage(raw))
+            return;
+        switch (raw.type) {
+            case "run": {
+                const active = new RunSession(port, raw);
+                session = active;
+                void executeRun(port, raw, active).catch((error) => {
+                    const failed = {
+                        type: "result",
+                        runId: raw.runId,
+                        evalOk: false,
+                        failure: "worker",
+                        errorName: error instanceof Error ? error.name : "Error",
+                        errorMessage: error instanceof Error ? error.message : String(error)
+                    };
+                    if (error instanceof Error && error.stack !== undefined) {
+                        failed.errorStack = error.stack;
+                    }
+                    port.postMessage(failed);
+                });
+                return;
+            }
+            case "suspend-update":
+                session?.setSuspendedMs(raw.suspendedMs);
+                return;
+            case "stream-closed":
+                session?.closeStream(raw.handle);
+                return;
+            case "rpc-reply":
+                if (raw.ok)
+                    session?.settleRpc(raw.id, true, raw.value);
+                else {
+                    const error = new Error(raw.message);
+                    error.name = raw.name;
+                    session?.settleRpc(raw.id, false, undefined, error);
+                }
+        }
+    });
+}
+/**
+ * Boot only under `worker_threads`.
+ *
+ * Importing this module on the main thread — a stray import, a bundler that
+ * pulled it into a graph — must do nothing rather than install a message
+ * handler on a port that is not a worker's.
+ */
+const threads = await importNodeBuiltin("node:worker_threads");
+if (threads?.parentPort != null) {
+    await startWorker(threads.parentPort);
+}
+//# sourceMappingURL=worker-entry.js.map

package/dist/js-sandbox-worker/worker-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-entry.js","sourceRoot":"","sources":["../../src/js-sandbox-worker/worker-entry.ts"],"names":[],"mappings":"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"}

package/dist/limits.d.ts

@@ -0,0 +1,77 @@
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const MAX_OUTPUT_SIZE = 100000;
+export declare const MAX_LOOP_ITERATIONS = 10000;
+export declare const MAX_FETCH_CALLS = 20;
+export declare const MAX_RESPONSE_BODY_SIZE = 1000000;
+/** Guest heap cap. QuickJS aborts if the guest tries to allocate beyond this. */
+export declare const GUEST_MEMORY_LIMIT: number;
+/** Guest stack cap — protects against deeply recursive code. */
+export declare const GUEST_STACK_LIMIT: number;
+/** Per-request wall-clock cap for the fetch bridge. */
+export declare const FETCH_TIMEOUT_MS = 15000;
+/** Redirect hops the fetch bridge follows before giving up. */
+export declare const MAX_FETCH_REDIRECTS = 5;
+/** Locale used by the `format` bridge when the caller names none. */
+export declare const DEFAULT_FORMAT_LOCALE = "en-US";
+export interface SandboxLimits {
+    maxFetchCalls?: number;
+    maxResponseBodyBytes?: number;
+    maxOutputSize?: number;
+    memoryLimitBytes?: number;
+    /**
+     * Total bytes of media one run may hold host-side for its handles. The
+     * aggregate the per-call image/media ceilings never bounded.
+     */
+    runMediaBytes?: number;
+    stackLimitBytes?: number;
+    fetchTimeoutMs?: number;
+    /**
+     * Permit fetches to loopback, link-local and private address ranges.
+     *
+     * Off by default: guest code is untrusted, so the SSRF guard is the norm and
+     * this is the exception. It exists because the trusted `lib.http` nodes have
+     * always been able to reach a local service, and a Code node replacing one
+     * must be able to do the same — a workflow pointing at `http://localhost:8000`
+     * would otherwise silently stop working.
+     *
+     * Host-set only: it is read from {@link RunSandboxOptions.limits} and never
+     * exposed to the guest, so sandboxed code cannot turn it on for itself.
+     */
+    allowPrivateNetwork?: boolean;
+    /** `User-Agent` for bridge fetches. Guest-set headers still win. */
+    userAgent?: string;
+    /**
+     * `"workspace"` (default) confines every `workspace.*` call to the workspace
+     * root, symlinks included. `"host"` lifts that to the whole filesystem the
+     * process can reach, with `~` expanded.
+     *
+     * Off by default for the same reason as {@link allowPrivateNetwork}, and the
+     * stakes are higher — host mode can read credential files. It exists because
+     * roughly half the `lib.os` nodes already operate on arbitrary host paths
+     * (`expandUser` + raw `node:fs`), so a Code node replacing one needs the same
+     * reach. Host-set only, and the graph migration sets it only on nodes
+     * rewritten from such a node — a hand-written or model-authored Code node
+     * stays confined.
+     */
+    filesystemAccess?: "workspace" | "host";
+    /**
+     * The secret names this run may read, or `null`/absent for every secret the
+     * store holds.
+     *
+     * A script that talks to an external service needs one credential, and
+     * nothing about `getSecret` used to say so: a node written to send a Slack
+     * message could read the AWS keys. Declaring the scope makes the credential
+     * a node reaches part of the node, visible in the graph and refused at the
+     * bridge rather than trusted to the code.
+     *
+     * Host-set only, like {@link allowPrivateNetwork}. A run reads its own scope
+     * through `nodetool.secrets.list()` but cannot widen it, and an empty array
+     * means no secret at all — a stricter thing than an absent scope, not a
+     * looser one.
+     */
+    secretScope?: readonly string[] | null;
+}
+export type ResolvedSandboxLimits = Required<SandboxLimits>;
+/** Apply defaults and ceilings to a caller-supplied {@link SandboxLimits}. */
+export declare function resolveSandboxLimits(limits?: SandboxLimits): ResolvedSandboxLimits;
+//# sourceMappingURL=limits.d.ts.map

package/dist/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,eAAO,MAAM,eAAe,SAAU,CAAC;AACvC,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,eAAO,MAAM,sBAAsB,UAAY,CAAC;AAChD,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,QAAmB,CAAC;AACnD,gEAAgE;AAChE,eAAO,MAAM,iBAAiB,QAAa,CAAC;AAC5C,uDAAuD;AACvD,eAAO,MAAM,gBAAgB,QAAS,CAAC;AACvC,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAE7C,MAAM,WAAW,aAAa;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;IACxC;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CACxC;AAED,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;AA0B5D,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAClC,MAAM,CAAC,EAAE,aAAa,GACrB,qBAAqB,CAmDvB"}

package/dist/limits.js

@@ -0,0 +1,56 @@
+import { isHostAccessEnabled } from "./host-access-gate.js";
+const MAX_RUN_MEDIA_BYTES = 256 * 1024 * 1024;
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const MAX_OUTPUT_SIZE = 100_000;
+export const MAX_LOOP_ITERATIONS = 10_000;
+export const MAX_FETCH_CALLS = 20;
+export const MAX_RESPONSE_BODY_SIZE = 1_000_000;
+/** Guest heap cap. QuickJS aborts if the guest tries to allocate beyond this. */
+export const GUEST_MEMORY_LIMIT = 64 * 1024 * 1024;
+/** Guest stack cap — protects against deeply recursive code. */
+export const GUEST_STACK_LIMIT = 512 * 1024;
+/** Per-request wall-clock cap for the fetch bridge. */
+export const FETCH_TIMEOUT_MS = 15_000;
+/** Redirect hops the fetch bridge follows before giving up. */
+export const MAX_FETCH_REDIRECTS = 5;
+/** Locale used by the `format` bridge when the caller names none. */
+export const DEFAULT_FORMAT_LOCALE = "en-US";
+/**
+ * Normalize a declared secret scope: a list of non-empty names, or `null` for
+ * an unscoped run. An empty declared list stays empty — it denies everything.
+ */
+function resolveSecretScope(scope) {
+    if (!Array.isArray(scope))
+        return null;
+    return scope
+        .filter((name) => typeof name === "string" && name !== "")
+        .map((name) => name.trim())
+        .filter((name) => name !== "");
+}
+function clampLimit(value, fallback, min, max) {
+    if (value == null || !Number.isFinite(value))
+        return fallback;
+    return Math.min(Math.max(Math.floor(value), min), max);
+}
+/** Apply defaults and ceilings to a caller-supplied {@link SandboxLimits}. */
+export function resolveSandboxLimits(limits) {
+    return {
+        maxFetchCalls: clampLimit(limits?.maxFetchCalls, MAX_FETCH_CALLS, 0, 100),
+        maxResponseBodyBytes: clampLimit(limits?.maxResponseBodyBytes, MAX_RESPONSE_BODY_SIZE, 1024, 50 * 1024 * 1024),
+        maxOutputSize: clampLimit(limits?.maxOutputSize, MAX_OUTPUT_SIZE, 1024, 10 * 1024 * 1024),
+        memoryLimitBytes: clampLimit(limits?.memoryLimitBytes, GUEST_MEMORY_LIMIT, 1024 * 1024, 512 * 1024 * 1024),
+        runMediaBytes: clampLimit(limits?.runMediaBytes, MAX_RUN_MEDIA_BYTES, 1024 * 1024, 2 * 1024 * 1024 * 1024),
+        stackLimitBytes: clampLimit(limits?.stackLimitBytes, GUEST_STACK_LIMIT, 16 * 1024, 8 * 1024 * 1024),
+        fetchTimeoutMs: clampLimit(limits?.fetchTimeoutMs, FETCH_TIMEOUT_MS, 100, 120_000),
+        // Not clamped — these are capability switches, not magnitudes. Both
+        // resolve to the restrictive value unless the host explicitly opts out,
+        // and the cloud profile never lets them out (see isHostAccessEnabled).
+        allowPrivateNetwork: limits?.allowPrivateNetwork === true && isHostAccessEnabled(),
+        userAgent: limits?.userAgent ?? "",
+        filesystemAccess: limits?.filesystemAccess === "host" && isHostAccessEnabled()
+            ? "host"
+            : "workspace",
+        secretScope: resolveSecretScope(limits?.secretScope)
+    };
+}
+//# sourceMappingURL=limits.js.map

package/dist/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"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"}

package/dist/sandbox-bootstrap-modules.d.ts

@@ -0,0 +1,54 @@
+/**
+ * What the guest's Node-compat bootstrap loads, in place of the wrapper's own
+ * polyfills.
+ *
+ * Before our sandboxed function is called, `@sebastianwessel/quickjs` evaluates
+ * a fixed preamble in the fresh context:
+ *
+ * ```js
+ * import 'node:buffer'; import 'node:util'; import 'node:url';
+ * import '@node_compatibility/headers'; import '@node_compatibility/request';
+ * import '@node_compatibility/response';
+ * ```
+ *
+ * Twelve kilobytes of JavaScript, compiled and evaluated into a new runtime on
+ * **every run** — 4.3 ms of a 12 ms empty run, against 0.34 ms for a bare
+ * QuickJS context. And most of it is thrown away immediately: the init prelude
+ * deletes `Buffer`, `Headers`, `Request` and `Response` before user code exists,
+ * because guest code has no business with host-shaped Node globals.
+ *
+ * Those imports resolve through the run's own module loader
+ * (`createGuestModuleHost`), which is ours, so the bootstrap can be served
+ * something cheaper instead of being fought. Four of the six become empty
+ * modules. `node:util` becomes the two classes the guest actually keeps, in
+ * place of promisify/callbackify/inherits/deprecate/types it never sees.
+ * `node:url` is served by the wrapper unchanged, because `URL` and
+ * `URLSearchParams` are guest capabilities and a hand-rolled URL parser is not
+ * a saving worth making.
+ *
+ * Measured on this repo's engine: wrapper setup 5.96 ms → 3.28 ms per run.
+ *
+ * The failure modes are deliberately lopsided. A wrapper release that renames
+ * or moves these modules makes the map miss, the real polyfill loads, and the
+ * only loss is the saving — pinned by "the compat bootstrap loads our stubs" in
+ * `tests/js-sandbox-modules.test.ts`, which fails loudly rather than silently
+ * costing 2.7 ms. A release that imports something our `node:util` does not
+ * export fails every sandbox run in the suite, which is as loud as it gets.
+ *
+ * Browser-safe: nothing here imports a Node builtin.
+ */
+/**
+ * Module id → the source served during the wrapper's bootstrap phase. The ids
+ * are what its own normalizer produces for the specifiers above; anything not
+ * listed loads from the wrapper as before.
+ */
+export declare const BOOTSTRAP_MODULE_SOURCES: ReadonlyMap<string, string>;
+/** Use one module-id shape across the wrapper's POSIX and Windows normalizers. */
+export declare function normalizeBootstrapModuleId(moduleId: string): string;
+/**
+ * The globals the bootstrap no longer installs, in the order a reader would
+ * check them. Exported so a test can assert they are gone at the source rather
+ * than after the prelude's `delete`, which would hide a missed stub.
+ */
+export declare const BOOTSTRAP_DROPPED_GLOBALS: readonly ["Buffer", "Headers", "Request", "Response"];
+//# sourceMappingURL=sandbox-bootstrap-modules.d.ts.map

package/dist/sandbox-bootstrap-modules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-bootstrap-modules.d.ts","sourceRoot":"","sources":["../src/sandbox-bootstrap-modules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAuCH;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAQ/D,CAAC;AAEH,kFAAkF;AAClF,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,YACpC,QAAQ,EACR,SAAS,EACT,SAAS,EACT,UAAU,CACF,CAAC"}

package/dist/sandbox-bootstrap-modules.js

@@ -0,0 +1,104 @@
+/**
+ * What the guest's Node-compat bootstrap loads, in place of the wrapper's own
+ * polyfills.
+ *
+ * Before our sandboxed function is called, `@sebastianwessel/quickjs` evaluates
+ * a fixed preamble in the fresh context:
+ *
+ * ```js
+ * import 'node:buffer'; import 'node:util'; import 'node:url';
+ * import '@node_compatibility/headers'; import '@node_compatibility/request';
+ * import '@node_compatibility/response';
+ * ```
+ *
+ * Twelve kilobytes of JavaScript, compiled and evaluated into a new runtime on
+ * **every run** — 4.3 ms of a 12 ms empty run, against 0.34 ms for a bare
+ * QuickJS context. And most of it is thrown away immediately: the init prelude
+ * deletes `Buffer`, `Headers`, `Request` and `Response` before user code exists,
+ * because guest code has no business with host-shaped Node globals.
+ *
+ * Those imports resolve through the run's own module loader
+ * (`createGuestModuleHost`), which is ours, so the bootstrap can be served
+ * something cheaper instead of being fought. Four of the six become empty
+ * modules. `node:util` becomes the two classes the guest actually keeps, in
+ * place of promisify/callbackify/inherits/deprecate/types it never sees.
+ * `node:url` is served by the wrapper unchanged, because `URL` and
+ * `URLSearchParams` are guest capabilities and a hand-rolled URL parser is not
+ * a saving worth making.
+ *
+ * Measured on this repo's engine: wrapper setup 5.96 ms → 3.28 ms per run.
+ *
+ * The failure modes are deliberately lopsided. A wrapper release that renames
+ * or moves these modules makes the map miss, the real polyfill loads, and the
+ * only loss is the saving — pinned by "the compat bootstrap loads our stubs" in
+ * `tests/js-sandbox-modules.test.ts`, which fails loudly rather than silently
+ * costing 2.7 ms. A release that imports something our `node:util` does not
+ * export fails every sandbox run in the suite, which is as loud as it gets.
+ *
+ * Browser-safe: nothing here imports a Node builtin.
+ */
+/** A module whose only job is to exist, for an `import` that wants no export. */
+const EMPTY_MODULE = "export default {};";
+/**
+ * `TextEncoder`/`TextDecoder`, which the wrapper's `node:util` installs as
+ * globals and which the guest surface documents.
+ *
+ * The `encodeURIComponent`/`unescape` pair is UTF-8 the way the wrapper's own
+ * polyfill does it, so the bytes a guest sees are the bytes it saw before. Both
+ * classes are also exported by name: the wrapper's `node:buffer` imports them
+ * that way, and although that module is empty here, a future one may not be.
+ */
+const UTIL_MODULE = `
+class TextEncoder {
+  encode(input = "") {
+    const utf8 = unescape(encodeURIComponent(input));
+    const out = new Uint8Array(utf8.length);
+    for (let i = 0; i < utf8.length; i++) out[i] = utf8.charCodeAt(i);
+    return out;
+  }
+}
+class TextDecoder {
+  constructor(encoding = "utf-8") {
+    if (encoding !== "utf-8") throw new Error("Only utf-8 encoding is supported");
+  }
+  decode(input = new Uint8Array()) {
+    let text = "";
+    for (let i = 0; i < input.length; i++) text += String.fromCharCode(input[i]);
+    return decodeURIComponent(escape(text));
+  }
+}
+globalThis.TextEncoder = TextEncoder;
+globalThis.TextDecoder = TextDecoder;
+export { TextEncoder, TextDecoder };
+export default { TextEncoder, TextDecoder };
+`;
+/**
+ * Module id → the source served during the wrapper's bootstrap phase. The ids
+ * are what its own normalizer produces for the specifiers above; anything not
+ * listed loads from the wrapper as before.
+ */
+export const BOOTSTRAP_MODULE_SOURCES = new Map([
+    // Deleted by the init prelude the moment the bootstrap finishes.
+    ["/node_modules/buffer", EMPTY_MODULE],
+    ["/node_modules/@node_compatibility/headers", EMPTY_MODULE],
+    ["/node_modules/@node_compatibility/request", EMPTY_MODULE],
+    ["/node_modules/@node_compatibility/response", EMPTY_MODULE],
+    // Kept, minus everything the guest cannot reach.
+    ["/node_modules/util", UTIL_MODULE]
+]);
+/** Use one module-id shape across the wrapper's POSIX and Windows normalizers. */
+export function normalizeBootstrapModuleId(moduleId) {
+    return moduleId.replaceAll("\\", "/");
+}
+/**
+ * The globals the bootstrap no longer installs, in the order a reader would
+ * check them. Exported so a test can assert they are gone at the source rather
+ * than after the prelude's `delete`, which would hide a missed stub.
+ */
+export const BOOTSTRAP_DROPPED_GLOBALS = [
+    "Buffer",
+    "Headers",
+    "Request",
+    "Response"
+];
+//# sourceMappingURL=sandbox-bootstrap-modules.js.map

package/dist/sandbox-bootstrap-modules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-bootstrap-modules.js","sourceRoot":"","sources":["../src/sandbox-bootstrap-modules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,iFAAiF;AACjF,MAAM,YAAY,GAAG,oBAAoB,CAAC;AAE1C;;;;;;;;GAQG;AACH,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;CAuBnB,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAgC,IAAI,GAAG,CAAC;IAC3E,iEAAiE;IACjE,CAAC,sBAAsB,EAAE,YAAY,CAAC;IACtC,CAAC,2CAA2C,EAAE,YAAY,CAAC;IAC3D,CAAC,2CAA2C,EAAE,YAAY,CAAC;IAC3D,CAAC,4CAA4C,EAAE,YAAY,CAAC;IAC5D,iDAAiD;IACjD,CAAC,oBAAoB,EAAE,WAAW,CAAC;CACpC,CAAC,CAAC;AAEH,kFAAkF;AAClF,MAAM,UAAU,0BAA0B,CAAC,QAAgB;IACzD,OAAO,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AACxC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,QAAQ;IACR,SAAS;IACT,SAAS;IACT,UAAU;CACF,CAAC"}