@utdk/isolate 0.1.0-dev.646adf4

package/dist/src/bridge.js

@@ -0,0 +1,151 @@
+/**
+ * Credential bridge for the Isolate runtime.
+ *
+ * The bridge is the ONLY channel through which credentials and provider
+ * operations enter the sandboxed vm context. It is created in the host context
+ * (where Node.js module loading works normally) and exposed as `__bridge__`
+ * inside the sandbox.
+ *
+ * Design:
+ *   - The provider module is dynamically imported in the HOST context, so it
+ *     can resolve its own dependencies normally.
+ *   - Credentials are mapped to an `AuthProvider` from `@utdk/common`, which
+ *     injects them into HTTP request headers at call time.
+ *   - The operation function is resolved via dot-notation path on the client.
+ *   - The sandbox script calls `await __bridge__.call(args)` — it never
+ *     touches `process.env` or any host filesystem API.
+ */
+import { ApiKey, BearerToken } from "@utdk/common";
+// ---------------------------------------------------------------------------
+// Credential resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolves an `AuthProvider` from a flat credentials map and the provider's
+ * `utdk.auth` config array (from its `package.json`).
+ *
+ * Supported patterns:
+ *   api_key   – Bearer header:  `api_key: "Bearer ${TOKEN_NAME}"`
+ *   api_key   – Raw header:     `api_key: "${TOKEN_NAME}"`
+ *   oauth2    – Pre-resolved:   looks for `PROVIDER_ACCESS_TOKEN` key
+ *
+ * Falls back to `BearerToken(firstValue)` when the auth config is absent or
+ * the pattern is not recognised.
+ */
+export function resolveAuthProvider(credentials, authConfigs = []) {
+    if (Object.keys(credentials).length === 0) {
+        return undefined;
+    }
+    for (const config of authConfigs) {
+        if (config.auth_type === "api_key" && config.api_key) {
+            // Pattern: "Bearer ${TOKEN_NAME}"
+            const bearerMatch = config.api_key.match(/^Bearer \$\{([^}]+)\}$/);
+            if (bearerMatch) {
+                const varName = bearerMatch[1];
+                if (varName && credentials[varName]) {
+                    return new BearerToken(credentials[varName]);
+                }
+            }
+            // Pattern: "${TOKEN_NAME}"  (raw header value)
+            const rawMatch = config.api_key.match(/^\$\{([^}]+)\}$/);
+            if (rawMatch) {
+                const varName = rawMatch[1];
+                if (varName && credentials[varName]) {
+                    return new ApiKey({
+                        headerName: config.var_name ?? "X-Api-Key",
+                        value: credentials[varName],
+                    });
+                }
+            }
+        }
+        if (config.auth_type === "oauth2") {
+            // Gateway pre-resolves OAuth2 tokens and passes them as ACCESS_TOKEN
+            // e.g. credentials = { SPOTIFY_ACCESS_TOKEN: 'eyJ...' }
+            const tokenKey = Object.keys(credentials).find((k) => k.endsWith("_ACCESS_TOKEN") ||
+                k.endsWith("_TOKEN"));
+            const tokenValue = tokenKey ? credentials[tokenKey] : undefined;
+            if (tokenKey && tokenValue) {
+                return new BearerToken(tokenValue);
+            }
+        }
+    }
+    // Fallback: treat the first credential value as a Bearer token
+    const firstValue = Object.values(credentials)[0];
+    if (firstValue !== undefined) {
+        return new BearerToken(firstValue);
+    }
+    return undefined;
+}
+/**
+ * Extracts the `utdk.auth` array from a provider module's package.json.
+ * Returns an empty array if the module does not export a `packageJson`
+ * property or if the config is absent.
+ */
+export function extractAuthConfigs(providerModule) {
+    const pkg = providerModule["packageJson"];
+    return pkg?.utdk?.auth ?? [];
+}
+// ---------------------------------------------------------------------------
+// Operation resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolves a dot-notation operation path on a client object.
+ *
+ * @example
+ * resolveOperation(client, 'users.getByUsername')
+ * // → client.users.getByUsername (as a bound function)
+ */
+export function resolveOperation(client, operationPath) {
+    const segments = operationPath.split(".");
+    let current = client;
+    for (const segment of segments) {
+        if (current === null || current === undefined || typeof current !== "object") {
+            throw new TypeError(`Cannot resolve operation path "${operationPath}": "${segment}" is not an object`);
+        }
+        current = current[segment];
+    }
+    if (typeof current !== "function") {
+        throw new TypeError(`Operation "${operationPath}" resolved to ${typeof current}, expected a function`);
+    }
+    return current;
+}
+/**
+ * Creates a bridge object that is safe to expose inside a vm context.
+ *
+ * The bridge has a single method, `call(args)`, which invokes the pre-resolved
+ * provider operation with the given arguments. Credentials are already baked
+ * into the operation via the auth provider — the sandbox script never sees
+ * them.
+ */
+export function createBridge(options) {
+    return {
+        async call(args) {
+            return options.operation(args);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Provider loading
+// ---------------------------------------------------------------------------
+/** Name of the factory function pattern in provider modules. */
+const CREATE_CLIENT_PATTERN = /^create[A-Z].+Client$/;
+/**
+ * Locates and invokes the `create*Client` factory in a provider module.
+ *
+ * Provider modules export a `create<Name>Client(options?)` function that
+ * returns a `Promise<Client>`. This helper finds it and calls it with the
+ * supplied auth provider.
+ *
+ * @throws if no factory function matching `create*Client` is found.
+ */
+export async function loadProviderClient(providerModule, auth) {
+    // Find the first create*Client export
+    const factoryEntry = Object.entries(providerModule).find(([name, value]) => CREATE_CLIENT_PATTERN.test(name) && typeof value === "function");
+    if (!factoryEntry) {
+        throw new Error("Provider module does not export a create*Client function. " +
+            `Exports found: ${Object.keys(providerModule).join(", ")}`);
+    }
+    const [, factory] = factoryEntry;
+    const client = await factory(auth ? { auth } : {});
+    return client;
+}
+//# sourceMappingURL=bridge.js.map

package/dist/src/bridge.js.map

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

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export { Isolate } from "./isolate.js";
+export { createSandboxContext } from "./sandbox.js";
+export { createBridge, extractAuthConfigs, loadProviderClient, resolveAuthProvider, resolveOperation, } from "./bridge.js";
+export type { ExecuteOptions, ExecuteResult, TimeoutError, UtdkAuthConfig } from "./types.js";
+export { TimeoutError as IsolateTimeoutError } from "./types.js";

package/dist/src/index.js

@@ -0,0 +1,5 @@
+export { Isolate } from "./isolate.js";
+export { createSandboxContext } from "./sandbox.js";
+export { createBridge, extractAuthConfigs, loadProviderClient, resolveAuthProvider, resolveOperation, } from "./bridge.js";
+export { TimeoutError as IsolateTimeoutError } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,YAAY,IAAI,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/src/isolate.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Isolate — sandboxed Node.js vm execution runtime for @utdk tool calls.
+ *
+ * Each call to `execute()` runs in a fresh `vm.createContext()` sandbox:
+ *   - No access to `process.env`, `fs`, `child_process`, `require`, or any
+ *     other Node.js host API that could leak credentials or touch the disk.
+ *   - Credentials are injected by the gateway at call time via a controlled
+ *     bridge object (`__bridge__`). The sandbox script only calls the bridge;
+ *     it never receives raw credential strings.
+ *   - Module cache is isolated per call (new context each time, no
+ *     cross-call state leakage).
+ *   - Timeout is enforced via `Promise.race`; runaway async operations are
+ *     rejected with a `TimeoutError`.
+ *
+ * For synchronous CPU spin-loops an additional `vm.Script` timeout guard is
+ * applied; the async watchdog covers everything else.
+ *
+ * ## Architecture
+ *
+ * ```
+ *  caller
+ *    │
+ *    ▼
+ *  Isolate.execute(options)
+ *    │
+ *    ├─ [host]  dynamically import provider module
+ *    ├─ [host]  resolve auth provider from credentials + utdk.auth config
+ *    ├─ [host]  create provider client with auth provider
+ *    ├─ [host]  resolve operation function (dot-notation path)
+ *    ├─ [host]  create bridge  { call(args) => operationFn(args) }
+ *    │
+ *    ├─ [vm]   createContext(minimal globals + __bridge__ + __args__)
+ *    └─ [vm]   run `__bridge__.call(__args__)` inside sandbox
+ *                 └─ [host, via bridge] call provider with credentials
+ *                       └─ [network] HTTP request with injected auth headers
+ * ```
+ *
+ * ## ESM / vm.Module note
+ *
+ * Node.js 20+ supports `vm.SourceTextModule` (ESM) with the
+ * `--experimental-vm-modules` flag. The current implementation uses the
+ * stable `vm.Script` API for the thin orchestration script, which is
+ * sufficient because:
+ *   - The script is one line (`__bridge__.call(__args__)`).
+ *   - Full provider code runs outside the sandbox (in host context) behind
+ *     the bridge abstraction.
+ *
+ * If future requirements call for running provider code itself inside an ESM
+ * module sandbox, upgrade to `vm.SourceTextModule` with a custom linker
+ * (see `upgrade notes` in the README).
+ */
+import { type ExecuteOptions, type ExecuteResult } from "./types.js";
+/**
+ * Sandboxed execution runtime for @utdk tool calls.
+ *
+ * @example
+ * ```typescript
+ * const isolate = new Isolate();
+ * const result = await isolate.execute({
+ *   module: '@utdk/github',
+ *   operation: 'users.getByUsername',
+ *   args: { username: 'octocat' },
+ *   credentials: { GITHUB_TOKEN: '<injected-by-gateway>' },
+ *   timeout: 10_000,
+ * });
+ * console.log(result.data, `(${result.durationMs}ms)`);
+ * ```
+ */
+export declare class Isolate {
+    /**
+     * Executes a single @utdk tool call inside a fresh vm sandbox.
+     *
+     * Steps:
+     * 1. Dynamically import the provider module (host context, cached by Node.js).
+     * 2. Resolve an `AuthProvider` from the supplied credentials and the
+     *    provider's `utdk.auth` config. Credentials are NEVER written to
+     *    `process.env`.
+     * 3. Instantiate the provider client with the auth provider.
+     * 4. Resolve the operation function via dot-notation path.
+     * 5. Create a bridge and a fresh vm context.
+     * 6. Run the sandbox script `__bridge__.call(__args__)` inside the context.
+     * 7. Race the execution against the timeout.
+     *
+     * @throws `TimeoutError` if execution exceeds `options.timeout`.
+     * @throws `TypeError`    if the operation path does not resolve to a function.
+     * @throws `Error`        on provider loading or HTTP failures.
+     */
+    execute(options: ExecuteOptions): Promise<ExecuteResult>;
+    /**
+     * Runs `SANDBOX_SCRIPT` in the given context and races against a timeout.
+     *
+     * The synchronous `vm.Script` timeout (`timeout` option in runInContext)
+     * guards against infinite synchronous loops. The async watchdog (Promise.race)
+     * guards against long-running await chains.
+     */
+    private _runWithTimeout;
+}

package/dist/src/isolate.js

@@ -0,0 +1,174 @@
+/**
+ * Isolate — sandboxed Node.js vm execution runtime for @utdk tool calls.
+ *
+ * Each call to `execute()` runs in a fresh `vm.createContext()` sandbox:
+ *   - No access to `process.env`, `fs`, `child_process`, `require`, or any
+ *     other Node.js host API that could leak credentials or touch the disk.
+ *   - Credentials are injected by the gateway at call time via a controlled
+ *     bridge object (`__bridge__`). The sandbox script only calls the bridge;
+ *     it never receives raw credential strings.
+ *   - Module cache is isolated per call (new context each time, no
+ *     cross-call state leakage).
+ *   - Timeout is enforced via `Promise.race`; runaway async operations are
+ *     rejected with a `TimeoutError`.
+ *
+ * For synchronous CPU spin-loops an additional `vm.Script` timeout guard is
+ * applied; the async watchdog covers everything else.
+ *
+ * ## Architecture
+ *
+ * ```
+ *  caller
+ *    │
+ *    ▼
+ *  Isolate.execute(options)
+ *    │
+ *    ├─ [host]  dynamically import provider module
+ *    ├─ [host]  resolve auth provider from credentials + utdk.auth config
+ *    ├─ [host]  create provider client with auth provider
+ *    ├─ [host]  resolve operation function (dot-notation path)
+ *    ├─ [host]  create bridge  { call(args) => operationFn(args) }
+ *    │
+ *    ├─ [vm]   createContext(minimal globals + __bridge__ + __args__)
+ *    └─ [vm]   run `__bridge__.call(__args__)` inside sandbox
+ *                 └─ [host, via bridge] call provider with credentials
+ *                       └─ [network] HTTP request with injected auth headers
+ * ```
+ *
+ * ## ESM / vm.Module note
+ *
+ * Node.js 20+ supports `vm.SourceTextModule` (ESM) with the
+ * `--experimental-vm-modules` flag. The current implementation uses the
+ * stable `vm.Script` API for the thin orchestration script, which is
+ * sufficient because:
+ *   - The script is one line (`__bridge__.call(__args__)`).
+ *   - Full provider code runs outside the sandbox (in host context) behind
+ *     the bridge abstraction.
+ *
+ * If future requirements call for running provider code itself inside an ESM
+ * module sandbox, upgrade to `vm.SourceTextModule` with a custom linker
+ * (see `upgrade notes` in the README).
+ */
+import vm from "node:vm";
+import { createBridge, extractAuthConfigs, loadProviderClient, resolveAuthProvider, resolveOperation, } from "./bridge.js";
+import { createSandboxContext } from "./sandbox.js";
+import { TimeoutError } from "./types.js";
+/** Script executed inside the sandbox for every tool call. */
+const SANDBOX_SCRIPT = new vm.Script("__bridge__.call(__args__)");
+/**
+ * Sandboxed execution runtime for @utdk tool calls.
+ *
+ * @example
+ * ```typescript
+ * const isolate = new Isolate();
+ * const result = await isolate.execute({
+ *   module: '@utdk/github',
+ *   operation: 'users.getByUsername',
+ *   args: { username: 'octocat' },
+ *   credentials: { GITHUB_TOKEN: '<injected-by-gateway>' },
+ *   timeout: 10_000,
+ * });
+ * console.log(result.data, `(${result.durationMs}ms)`);
+ * ```
+ */
+export class Isolate {
+    /**
+     * Executes a single @utdk tool call inside a fresh vm sandbox.
+     *
+     * Steps:
+     * 1. Dynamically import the provider module (host context, cached by Node.js).
+     * 2. Resolve an `AuthProvider` from the supplied credentials and the
+     *    provider's `utdk.auth` config. Credentials are NEVER written to
+     *    `process.env`.
+     * 3. Instantiate the provider client with the auth provider.
+     * 4. Resolve the operation function via dot-notation path.
+     * 5. Create a bridge and a fresh vm context.
+     * 6. Run the sandbox script `__bridge__.call(__args__)` inside the context.
+     * 7. Race the execution against the timeout.
+     *
+     * @throws `TimeoutError` if execution exceeds `options.timeout`.
+     * @throws `TypeError`    if the operation path does not resolve to a function.
+     * @throws `Error`        on provider loading or HTTP failures.
+     */
+    async execute(options) {
+        const { module: moduleName, operation, args = {}, credentials = {}, timeout = 30_000, } = options;
+        const startMs = performance.now();
+        // ------------------------------------------------------------------
+        // Step 1: Load the provider module in HOST context
+        // ------------------------------------------------------------------
+        // Dynamic import is Node.js-cached so repeated calls to the same
+        // provider do not re-parse the module. The provider runs in host
+        // context (not in the sandbox) — it is trusted code.
+        const providerModule = (await import(moduleName));
+        // ------------------------------------------------------------------
+        // Step 2: Resolve auth provider from credentials
+        // ------------------------------------------------------------------
+        const authConfigs = extractAuthConfigs(providerModule);
+        const auth = resolveAuthProvider(credentials, authConfigs);
+        // ------------------------------------------------------------------
+        // Step 3: Create the provider client with credential injection
+        // ------------------------------------------------------------------
+        const client = await loadProviderClient(providerModule, auth);
+        // ------------------------------------------------------------------
+        // Step 4: Resolve the operation function
+        // ------------------------------------------------------------------
+        const operationFn = resolveOperation(client, operation);
+        // ------------------------------------------------------------------
+        // Step 5: Create the credential bridge and sandboxed vm context
+        // ------------------------------------------------------------------
+        // The bridge is created in host context and passed into the sandbox.
+        // The sandbox script can only call bridge.call(args) — it cannot
+        // reach process.env, require, fs, or any host API.
+        const bridge = createBridge({ operation: operationFn });
+        const context = createSandboxContext({
+            extraGlobals: {
+                __bridge__: bridge,
+                __args__: args,
+            },
+        });
+        // ------------------------------------------------------------------
+        // Step 6 + 7: Run inside sandbox, race against timeout
+        // ------------------------------------------------------------------
+        const data = await this._runWithTimeout(context, timeout);
+        const durationMs = performance.now() - startMs;
+        return { data, durationMs };
+    }
+    /**
+     * Runs `SANDBOX_SCRIPT` in the given context and races against a timeout.
+     *
+     * The synchronous `vm.Script` timeout (`timeout` option in runInContext)
+     * guards against infinite synchronous loops. The async watchdog (Promise.race)
+     * guards against long-running await chains.
+     */
+    _runWithTimeout(context, timeoutMs) {
+        // The synchronous portion of the script (if any) is bounded by the vm timeout.
+        // For the async portion we use Promise.race.
+        let resultPromise;
+        try {
+            // runInContext returns whatever the script evaluates to.
+            // For our one-liner that calls an async bridge method, this is a Promise.
+            const scriptResult = SANDBOX_SCRIPT.runInContext(context, {
+                // Guard against synchronous infinite loops / busy spins.
+                // This only applies to the synchronous execution phase; async
+                // continuations are handled by the Promise.race below.
+                timeout: timeoutMs,
+            });
+            resultPromise = Promise.resolve(scriptResult);
+        }
+        catch (err) {
+            return Promise.reject(err);
+        }
+        // Async watchdog
+        const timeoutPromise = new Promise((_, reject) => {
+            const timer = setTimeout(() => {
+                reject(new TimeoutError(timeoutMs));
+            }, timeoutMs);
+            // Don't keep the process alive if only the timer is pending
+            if (typeof timer.unref === "function") {
+                timer.unref();
+            }
+        });
+        return Promise.race([resultPromise, timeoutPromise]);
+    }
+}
+//# sourceMappingURL=isolate.js.map

package/dist/src/isolate.js.map

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

package/dist/src/sandbox.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Sandbox context creation for the Isolate runtime.
+ *
+ * A sandboxed vm context is created per tool call. The context provides a
+ * minimal set of safe globals and explicitly excludes `process`, `require`,
+ * `fs`, `child_process`, and other Node.js host APIs that could leak
+ * environment variables or allow filesystem/subprocess access.
+ *
+ * The credential bridge (`__bridge__`) and call arguments (`__args__`) are
+ * the only channels through which external state enters the sandbox.
+ */
+import vm from "node:vm";
+export interface SandboxOptions {
+    /**
+     * Additional globals to expose inside the vm context.
+     * Use sparingly; every addition is a potential escape hatch.
+     */
+    extraGlobals?: Record<string, unknown>;
+}
+/**
+ * Creates a fresh, restricted vm context.
+ *
+ * Accessible globals:
+ *   console, JSON, Math, Date, Promise, Array, Object, String, Number,
+ *   Boolean, Error, TypeError, RangeError, Map, Set, WeakMap, WeakSet,
+ *   Symbol, typed arrays, ArrayBuffer, URL, URLSearchParams,
+ *   TextEncoder, TextDecoder, setTimeout, clearTimeout, setInterval,
+ *   clearInterval, parseInt, parseFloat, isNaN, isFinite, encodeURI,
+ *   decodeURI, encodeURIComponent, decodeURIComponent, Infinity, NaN,
+ *   undefined.
+ *
+ * Deliberately excluded:
+ *   process, require, global, Buffer, __dirname, __filename,
+ *   fs, child_process, net, http, https, os, crypto (node:crypto),
+ *   and any other Node.js built-in that exposes host resources.
+ *
+ * @param options - Optional extra globals to inject.
+ * @returns A contextified vm sandbox object.
+ */
+export declare function createSandboxContext(options?: SandboxOptions): vm.Context;

package/dist/src/sandbox.js

@@ -0,0 +1,116 @@
+/**
+ * Sandbox context creation for the Isolate runtime.
+ *
+ * A sandboxed vm context is created per tool call. The context provides a
+ * minimal set of safe globals and explicitly excludes `process`, `require`,
+ * `fs`, `child_process`, and other Node.js host APIs that could leak
+ * environment variables or allow filesystem/subprocess access.
+ *
+ * The credential bridge (`__bridge__`) and call arguments (`__args__`) are
+ * the only channels through which external state enters the sandbox.
+ */
+import vm from "node:vm";
+const PREFIXED_METHODS = ["log", "error", "warn", "info", "debug"];
+function createPrefixedConsole(prefix) {
+    const console_ = console;
+    return Object.fromEntries(PREFIXED_METHODS.map((method) => [method, (...args) => console_[method](prefix, ...args)]));
+}
+const sandboxConsole = createPrefixedConsole("[sandbox]");
+/**
+ * Creates a fresh, restricted vm context.
+ *
+ * Accessible globals:
+ *   console, JSON, Math, Date, Promise, Array, Object, String, Number,
+ *   Boolean, Error, TypeError, RangeError, Map, Set, WeakMap, WeakSet,
+ *   Symbol, typed arrays, ArrayBuffer, URL, URLSearchParams,
+ *   TextEncoder, TextDecoder, setTimeout, clearTimeout, setInterval,
+ *   clearInterval, parseInt, parseFloat, isNaN, isFinite, encodeURI,
+ *   decodeURI, encodeURIComponent, decodeURIComponent, Infinity, NaN,
+ *   undefined.
+ *
+ * Deliberately excluded:
+ *   process, require, global, Buffer, __dirname, __filename,
+ *   fs, child_process, net, http, https, os, crypto (node:crypto),
+ *   and any other Node.js built-in that exposes host resources.
+ *
+ * @param options - Optional extra globals to inject.
+ * @returns A contextified vm sandbox object.
+ */
+export function createSandboxContext(options = {}) {
+    const sandbox = {
+        // Safe builtins
+        console: sandboxConsole,
+        JSON,
+        Math,
+        Date,
+        Promise,
+        Array,
+        Object,
+        String,
+        Number,
+        Boolean,
+        Error,
+        EvalError,
+        RangeError,
+        ReferenceError,
+        SyntaxError,
+        TypeError,
+        URIError,
+        Map,
+        Set,
+        WeakMap,
+        WeakSet,
+        WeakRef,
+        Symbol,
+        BigInt,
+        // Typed arrays
+        ArrayBuffer,
+        SharedArrayBuffer,
+        DataView,
+        Int8Array,
+        Uint8Array,
+        Uint8ClampedArray,
+        Int16Array,
+        Uint16Array,
+        Int32Array,
+        Uint32Array,
+        Float32Array,
+        Float64Array,
+        BigInt64Array,
+        BigUint64Array,
+        // Web-compatible globals
+        URL,
+        URLSearchParams,
+        TextEncoder,
+        TextDecoder,
+        // Timers (these are host-side and safe to expose)
+        setTimeout,
+        clearTimeout,
+        setInterval,
+        clearInterval,
+        // Standard globals
+        parseInt,
+        parseFloat,
+        isNaN,
+        isFinite,
+        encodeURI,
+        decodeURI,
+        encodeURIComponent,
+        decodeURIComponent,
+        Infinity,
+        NaN,
+        undefined,
+        // Explicitly do NOT add:
+        //   process        — would expose process.env (credential leak)
+        //   require        — would allow arbitrary module imports
+        //   global         — alias for Node.js global; exposes process
+        //   Buffer         — not needed in sandboxed operations
+        //   __dirname      — filesystem information leak
+        //   __filename     — filesystem information leak
+        //   fetch          — injected separately per-operation via bridge (see bridge.ts)
+        //   crypto         — would allow subtle attacks; excluded for now
+        ...options.extraGlobals,
+    };
+    return vm.createContext(sandbox);
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/src/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AAIzB,MAAM,gBAAgB,GAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpF,SAAS,qBAAqB,CAAC,MAAc;IAC3C,MAAM,QAAQ,GAAiC,OAAO,CAAC;IACvD,OAAO,MAAM,CAAC,WAAW,CACvB,gBAAgB,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAC/C,CAAC;AAC3D,CAAC;AAED,MAAM,cAAc,GAAG,qBAAqB,CAAC,WAAW,CAAC,CAAC;AAU1D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAA0B,EAAE;IAC/D,MAAM,OAAO,GAA4B;QACvC,gBAAgB;QAChB,OAAO,EAAE,cAAc;QACvB,IAAI;QACJ,IAAI;QACJ,IAAI;QACJ,OAAO;QACP,KAAK;QACL,MAAM;QACN,MAAM;QACN,MAAM;QACN,OAAO;QACP,KAAK;QACL,SAAS;QACT,UAAU;QACV,cAAc;QACd,WAAW;QACX,SAAS;QACT,QAAQ;QACR,GAAG;QACH,GAAG;QACH,OAAO;QACP,OAAO;QACP,OAAO;QACP,MAAM;QACN,MAAM;QAEN,eAAe;QACf,WAAW;QACX,iBAAiB;QACjB,QAAQ;QACR,SAAS;QACT,UAAU;QACV,iBAAiB;QACjB,UAAU;QACV,WAAW;QACX,UAAU;QACV,WAAW;QACX,YAAY;QACZ,YAAY;QACZ,aAAa;QACb,cAAc;QAEd,yBAAyB;QACzB,GAAG;QACH,eAAe;QACf,WAAW;QACX,WAAW;QAEX,kDAAkD;QAClD,UAAU;QACV,YAAY;QACZ,WAAW;QACX,aAAa;QAEb,mBAAmB;QACnB,QAAQ;QACR,UAAU;QACV,KAAK;QACL,QAAQ;QACR,SAAS;QACT,SAAS;QACT,kBAAkB;QAClB,kBAAkB;QAClB,QAAQ;QACR,GAAG;QACH,SAAS;QAET,yBAAyB;QACzB,gEAAgE;QAChE,0DAA0D;QAC1D,+DAA+D;QAC/D,wDAAwD;QACxD,iDAAiD;QACjD,iDAAiD;QACjD,kFAAkF;QAClF,kEAAkE;QAElE,GAAG,OAAO,CAAC,YAAY;KACxB,CAAC;IAEF,OAAO,EAAE,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;AACnC,CAAC"}