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

package/dist/js-sandbox-worker/interpreter.d.ts

@@ -0,0 +1,276 @@
+/**
+ * The interpreter half of the QuickJS sandbox: everything that happens *inside*
+ * one `runSandboxed` call.
+ *
+ * `runInSandbox` (../js-sandbox.ts) owns the host half — building the bridge
+ * record, the WASM/host/capability dispatchers, the cancellation race, the
+ * unhandled-rejection guard, and the result shape callers see. This module owns
+ * what runs against the guest context: the interrupt handler, the never-reject
+ * wrap layer, the init prelude, the entry module, and the sync-back extractor.
+ *
+ * The split exists so the guest can run on a `worker_threads` worker without a
+ * second copy of any of it. Both hosts call {@link runInterpreter}; the pieces
+ * that must live next to the guest (the module loader's closures, the
+ * serializers, the interrupt handler) live here, and the pieces that need live
+ * host objects reach this module as plain functions — {@link
+ * InterpreterParams.isAborted} and {@link InterpreterParams.suspendedMs} stand
+ * in for the `AbortSignal` and the `SandboxClock`, neither of which can cross a
+ * thread.
+ *
+ * Browser-safe: nothing here imports a Node builtin, statically or otherwise.
+ */
+import { loadQuickJs } from "../../vendor/quickjs/index.js";
+import type { SandboxModuleResolution } from "@nodetool-ai/protocol/sandbox-package";
+import type { ResolvedSandboxLimits } from "../limits.js";
+/** The engine entry point one interpreter run drives. */
+export type SandboxRunSandboxed = Awaited<ReturnType<typeof loadQuickJs>>["runSandboxed"];
+type SandboxRunOptions = NonNullable<Parameters<SandboxRunSandboxed>[1]>;
+/**
+ * The engine's wall-clock abort is a `setTimeout`, and Node fires a delay past
+ * this immediately instead of never — so this is the practical "no backstop".
+ */
+export declare const MAX_ENGINE_TIMEOUT_MS = 2147483647;
+/**
+ * What the guest is told when it calls `stream` in a run that has no input
+ * stream behind it. Shared by the host bridge and the guest prelude so both
+ * paths say the same thing.
+ */
+export declare const NO_INPUT_STREAM_MESSAGE = "stream() requires streaming-input mode; this run has no input stream";
+/**
+ * The library's serializer table is module-global, so this registers once —
+ * and a worker, holding its own module instance, registers its own.
+ */
+export declare function registerTypedArraySerializers(): void;
+/**
+ * Marker key placed on an object to signal a sandboxed error. A host async
+ * function that would normally `throw` instead resolves with one of these
+ * objects; a prelude inside the guest rewraps them as real guest-side errors.
+ *
+ * This indirection exists because the current `@sebastianwessel/quickjs`
+ * runtime leaks handles whenever a host-backed guest Promise is *rejected*,
+ * tripping an internal assertion (`list_empty(&rt->gc_obj_list)`) in
+ * quickjs-ng when the runtime is freed. Routing failures through a resolved
+ * tagged value sidesteps the leak while preserving the guest-visible
+ * behaviour (the user still gets a thrown Error with name + message).
+ */
+export declare const SANDBOX_ERROR_MARKER = "__nodetool_sandbox_error__";
+/**
+ * Names injected as bridge bindings into the QuickJS guest. The rest of the
+ * `buildSandbox` record (JSON, Math, Date, URL, etc.) is deliberately NOT
+ * marshaled — QuickJS already provides native implementations, and re-exposing
+ * host versions creates thousands of handles that slow execution and leak on
+ * teardown.
+ */
+export declare const EXPOSED_BRIDGE_NAMES: readonly ["console", "fetch", "crypto", "sleep", "getSecret", "workspace", "assetToSandbox", "sandboxToAsset", "progress", "emit", "output", "format", "image", "audio", "video", "canvas", "media", "__maxIter", "__secretScope"];
+export type ExposedBridgeName = (typeof EXPOSED_BRIDGE_NAMES)[number];
+/**
+ * Globals the init prelude removes. `eval` and `Function` go so the guest
+ * cannot re-enter code generation. The rest are stubs
+ * `@sebastianwessel/quickjs` installs unconditionally (its node-compatibility
+ * layer and `provideEnv` have no off switch): `Buffer`, `process`, `env`,
+ * `Headers`, `Request`, `Response`, `performance`. Nothing in the sandbox's
+ * own machinery uses them — the fetch bridge returns plain objects and the
+ * guest-to-host serializers dispatch on constructor names no guest code can
+ * reach once the classes are gone — so they are deleted to keep the guest
+ * surface minimal instead of documented as stubs.
+ */
+export declare const DELETED_GUEST_GLOBALS: readonly ["eval", "Function", "Buffer", "process", "env", "Headers", "Request", "Response", "performance"];
+/** Name the host parks the raw (never-rejecting) dispatcher bridge on. */
+export declare const SANDBOX_WASM_BRIDGE_BINDING = "__wasmCall";
+/** Name the host parks the raw (never-rejecting) host dispatcher bridge on. */
+export declare const SANDBOX_HOST_BRIDGE_BINDING = "__hostCall";
+/** Name the host parks the raw (never-rejecting) capability dispatcher on. */
+export declare const SANDBOX_CAPABILITY_BRIDGE_BINDING = "__capabilityCall";
+/**
+ * Names the host parks the input bridges on, which the prelude captures and
+ * then deletes — the guest reaches them only through `stream`.
+ */
+export declare const SANDBOX_INPUT_TAKE_BINDING = "__takeInput";
+export declare const SANDBOX_STREAM_OPEN_BINDING = "__streamOpen";
+/**
+ * Timer globals the guest must not see. The documented contract has always
+ * been "`sleep` is the only timer", but `@sebastianwessel/quickjs` installs
+ * host-backed `setTimeout`/`setInterval`/`setImmediate` into the context on
+ * every `evalCode` call — *after* the init prelude runs — so a prelude-time
+ * `delete` does not stick. {@link wrapCode} deletes them inside the user-code
+ * module itself, which evaluates after the library's re-install. They are
+ * blocked deliberately: their callbacks fire through `ctx.callFunction` with
+ * errors silently discarded, outside the never-reject and abort-guard
+ * conventions every bridge follows. Concurrency does not need them —
+ * bridge calls run in parallel under `Promise.all`/`parallelMap`.
+ */
+export declare const BLOCKED_TIMER_GLOBALS: readonly ["setTimeout", "clearTimeout", "setInterval", "clearInterval", "setImmediate", "clearImmediate"];
+/**
+ * Wrap user code as the default export of an ES module with a top-level-awaited
+ * async IIFE body, so `return <value>` inside the snippet becomes the module's
+ * default export and `await` at the top level works. The module first drops
+ * the timer globals the engine re-installs per evaluation (see
+ * {@link BLOCKED_TIMER_GLOBALS}).
+ */
+export declare function wrapCode(code: string, prelude?: string, encodeResult?: boolean): string;
+/**
+ * Build the entry module for user code, hoisting static `import` declarations
+ * out of the async IIFE {@link wrapCode} wraps the body in.
+ *
+ * An `import` is only legal at module top level, so the IIFE body cannot hold
+ * one. The imports are spliced out by source range and re-emitted on a single
+ * line above the wrapper; the ranges they vacate are blanked with spaces (never
+ * with fewer newlines), so every remaining line of user code keeps its content
+ * and its offset from the body's start. The whole body shifts down by exactly
+ * one line relative to {@link wrapCode}'s output.
+ *
+ * Import-free code takes the {@link wrapCode} path unchanged, and so does code
+ * acorn cannot parse — a syntax error must reach the guest exactly as the user
+ * wrote it, not as this transform's complaint about it.
+ *
+ * Dynamic `import()` expressions are left where they are. The module loader
+ * denies them at runtime (see {@link createGuestModuleHost}); rewriting them
+ * here would only move a runtime denial into a confusing compile-time one.
+ */
+export declare function buildEntryModule(source: string, prelude?: string, encodeResult?: boolean): string;
+/**
+ * How many module lines {@link buildEntryModule} (or {@link wrapCode}) place
+ * before the first line of the code it was given.
+ *
+ * QuickJS reports stack positions in the wrapped entry module, so an error on
+ * the guest's line N sits at `N + offset` in the source the user wrote. The
+ * hoisted-import path spends one extra leading line (the joined imports) over
+ * the plain wrapper, and which path applied is decided by the same acorn parse
+ * {@link buildEntryModule} runs — so the offset must come from here, not be
+ * guessed by callers.
+ */
+export declare function entryBodyLineOffset(code: string): number;
+export interface GuestModuleHost {
+    /** Loader and normalizer to hand `runSandboxed`. */
+    readonly options: Pick<SandboxRunOptions, "getModuleLoader" | "modulePathNormalizer">;
+    /** Stop delegating to the wrapper's own Node-compat resolution. */
+    enterGuestPhase(): void;
+    /** After the entry's static graph is linked, every further resolve is dynamic. */
+    lockStaticGraph(): void;
+}
+/**
+ * Install the run's declared sandbox modules as the *only* importable modules.
+ *
+ * The enforcement point is the **normalizer**, not the loader: QuickJS resolves
+ * an already-loaded module straight out of its cache without consulting the
+ * loader, but it normalizes every specifier first. A denial decided in the
+ * normalizer therefore also holds for `node:buffer` and friends, which the
+ * wrapper imports into the cache during its own bootstrap
+ * (`prepareNodeCompatibility`) before guest code exists.
+ *
+ * Three phases, in order:
+ *
+ * 1. **bootstrap** — the wrapper's `import 'node:buffer'` and the rest of its
+ *    compat preamble run before our sandboxed function is called. They resolve
+ *    through the library's own normalizer, and through its loader for anything
+ *    {@link BOOTSTRAP_MODULE_SOURCES} does not serve a cheaper source for, or
+ *    the runtime never starts.
+ * 2. **guest, linking** — only the run's declared specifiers and their
+ *    intra-pack siblings resolve. Everything else — `node:*`, the compat
+ *    modules the bootstrap warmed, absolute paths, `../` escapes, encoded
+ *    traversals, another pack's internal files — is denied by name.
+ * 3. **guest, locked** — the entry module's static graph is linked, so any
+ *    further resolution is a dynamic `import()`, and every one of those is
+ *    denied. A computed specifier is unknowable ahead of the call, and the
+ *    declaration is the whole contract, so the stricter rule is the honest one.
+ *
+ * Loaded module sources are prefixed with the timer deletions
+ * ({@link BLOCKED_TIMER_GLOBALS}) on the same line as their first statement:
+ * dependencies evaluate *before* the entry body, so the entry's own deletions
+ * come too late to harden them. `eval`/`Function` need no such treatment — the
+ * init prelude deletes them for the whole context before any user `evalCode`.
+ */
+export declare function createGuestModuleHost(modules: SandboxModuleResolution | undefined, capabilityFacades?: ReadonlyMap<string, string>): GuestModuleHost;
+/** One dispatcher call: WASM, host module, or platform capability. */
+export type SandboxDispatchCall = (moduleKey: unknown, exportName: unknown, args: unknown) => Promise<unknown>;
+export interface InterpreterParams {
+    /** The engine entry point. One process (or worker) keeps one. */
+    runSandboxed: SandboxRunSandboxed;
+    /** The user's code, unwrapped. */
+    code: string;
+    /**
+     * The bridge record `buildSandbox` produced, including the two input
+     * bindings. Only the names this module reaches for are read.
+     */
+    sandbox: Record<string, unknown>;
+    /**
+     * Caller-injected globals, already filtered against
+     * `RESERVED_SANDBOX_NAMES` and the identifier rule.
+     */
+    globals: Record<string, unknown>;
+    /**
+     * Names in {@link globals} that hold objects, so their contents are read back
+     * out of the guest and returned as {@link InterpreterOutcome.syncedGlobals}.
+     */
+    syncTargetNames: readonly string[];
+    /** Exposed only when the run declares WASM modules. */
+    wasmCall?: SandboxDispatchCall;
+    /** Exposed only when the run declares host modules. */
+    hostCall?: SandboxDispatchCall;
+    /** Exposed only when the host mounted platform capability modules. */
+    capabilityCall?: SandboxDispatchCall;
+    /** Sandbox modules this run may import. */
+    modules?: SandboxModuleResolution;
+    /** Platform modules this run mounts: guest specifier → generated facade. */
+    capabilityFacades?: ReadonlyMap<string, string>;
+    /** Guest execution budget, enforced by the interrupt handler. */
+    timeoutMs: number;
+    limits: ResolvedSandboxLimits;
+    /** Total suspension allowed before the engine's own backstop fires. */
+    suspendAllowanceMs: number;
+    /**
+     * Whether a clock is metering this run. With one, the engine's wall-clock
+     * abort moves out to cover {@link suspendAllowanceMs}; the interrupt handler
+     * keeps the exact bound on guest execution either way.
+     */
+    hasClock: boolean;
+    /**
+     * Has the run been cancelled? Stands in for the caller's `AbortSignal`.
+     * Absent when the caller passed none, which leaves every bridge unwrapped
+     * exactly as before.
+     */
+    isAborted?: () => boolean;
+    /** Milliseconds the run has spent suspended. Absent means none. */
+    suspendedMs?: () => number;
+    /** Internal slow-run diagnostics; never crosses the public sandbox API. */
+    onTiming?: (timing: InterpreterTiming) => void;
+}
+export interface InterpreterTiming {
+    readonly wrapperSetupMs: number;
+    readonly initMs: number;
+    readonly userCodeMs: number;
+    readonly syncMs: number;
+    readonly callbackRemainderMs: number;
+    readonly wrapperCleanupMs: number;
+    readonly totalMs: number;
+}
+/**
+ * What one interpreter run produced: the guest's own eval response, plus the
+ * object-globals read back out of the guest. The caller writes those back into
+ * its host objects — the guest's heap is isolated, and a thread boundary makes
+ * that separation literal.
+ */
+export type InterpreterOutcome = {
+    ok: true;
+    data: unknown;
+    syncedGlobals?: Record<string, unknown>;
+} | {
+    ok: false;
+    error: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    syncedGlobals?: Record<string, unknown>;
+};
+/**
+ * Run one piece of user code against a fresh guest context.
+ *
+ * Resolves with the guest's verdict — including a guest-side error, which is a
+ * result and not a failure. It rejects only when the engine itself fails
+ * (an Emscripten abort, a marshaling error, a module host that could not be
+ * built), which the caller translates.
+ */
+export declare function runInterpreter(params: InterpreterParams): Promise<InterpreterOutcome>;
+export {};
+//# sourceMappingURL=interpreter.d.ts.map

package/dist/js-sandbox-worker/interpreter.d.ts.map

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