@secure-exec/nodejs 0.2.0-rc.1

package/dist/host-network-adapter.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Concrete HostNetworkAdapter for Node.js, delegating to node:net,
+ * node:dgram, and node:dns for real external I/O.
+ */
+import type { HostNetworkAdapter } from "@secure-exec/core";
+/** Create a Node.js HostNetworkAdapter that uses real OS networking. */
+export declare function createNodeHostNetworkAdapter(): HostNetworkAdapter;

package/dist/host-network-adapter.js

@@ -0,0 +1,279 @@
+/**
+ * Concrete HostNetworkAdapter for Node.js, delegating to node:net,
+ * node:dgram, and node:dns for real external I/O.
+ */
+import * as net from "node:net";
+import * as dgram from "node:dgram";
+import * as dns from "node:dns";
+/**
+ * Queued-read adapter: incoming data/EOF/errors are buffered so that
+ * each read() call returns the next chunk or null for EOF.
+ */
+class NodeHostSocket {
+    socket;
+    readQueue = [];
+    waiters = [];
+    ended = false;
+    errored = null;
+    constructor(socket) {
+        this.socket = socket;
+        socket.on("data", (chunk) => {
+            const data = new Uint8Array(chunk);
+            const waiter = this.waiters.shift();
+            if (waiter) {
+                waiter(data);
+            }
+            else {
+                this.readQueue.push(data);
+            }
+        });
+        socket.on("end", () => {
+            this.ended = true;
+            const waiter = this.waiters.shift();
+            if (waiter) {
+                waiter(null);
+            }
+            else {
+                this.readQueue.push(null);
+            }
+        });
+        socket.on("error", (err) => {
+            this.errored = err;
+            // Wake all pending readers with EOF
+            for (const waiter of this.waiters.splice(0)) {
+                waiter(null);
+            }
+            if (!this.ended) {
+                this.ended = true;
+                this.readQueue.push(null);
+            }
+        });
+    }
+    async write(data) {
+        return new Promise((resolve, reject) => {
+            this.socket.write(data, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+    async read() {
+        const queued = this.readQueue.shift();
+        if (queued !== undefined)
+            return queued;
+        if (this.ended)
+            return null;
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+    async close() {
+        return new Promise((resolve) => {
+            if (this.socket.destroyed) {
+                resolve();
+                return;
+            }
+            this.socket.once("close", () => resolve());
+            this.socket.destroy();
+        });
+    }
+    setOption(level, optname, optval) {
+        // Forward common options to the real socket
+        this.socket.setNoDelay(optval !== 0);
+    }
+    shutdown(how) {
+        if (how === "write" || how === "both") {
+            this.socket.end();
+        }
+        if (how === "read" || how === "both") {
+            this.socket.pause();
+            this.socket.removeAllListeners("data");
+            if (!this.ended) {
+                this.ended = true;
+                const waiter = this.waiters.shift();
+                if (waiter)
+                    waiter(null);
+                else
+                    this.readQueue.push(null);
+            }
+        }
+    }
+}
+/**
+ * TCP listener backed by node:net.Server. Incoming connections are
+ * queued so each accept() call returns the next one.
+ */
+class NodeHostListener {
+    server;
+    _port;
+    connQueue = [];
+    waiters = [];
+    closed = false;
+    constructor(server, port) {
+        this.server = server;
+        this._port = port;
+        server.on("connection", (socket) => {
+            const waiter = this.waiters.shift();
+            if (waiter) {
+                waiter(socket);
+            }
+            else {
+                this.connQueue.push(socket);
+            }
+        });
+    }
+    get port() {
+        return this._port;
+    }
+    async accept() {
+        const queued = this.connQueue.shift();
+        if (queued)
+            return new NodeHostSocket(queued);
+        if (this.closed)
+            throw new Error("Listener closed");
+        return new Promise((resolve, reject) => {
+            if (this.closed) {
+                reject(new Error("Listener closed"));
+                return;
+            }
+            this.waiters.push((socket) => {
+                resolve(new NodeHostSocket(socket));
+            });
+        });
+    }
+    async close() {
+        this.closed = true;
+        // Reject pending accept waiters
+        for (const waiter of this.waiters.splice(0)) {
+            // Resolve with a destroyed socket to signal closure — caller handles
+            // the error via the socket's error/close events
+        }
+        return new Promise((resolve, reject) => {
+            this.server.close((err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+}
+/**
+ * UDP socket backed by node:dgram.Socket. Messages are queued
+ * so each recv() call returns the next datagram.
+ */
+class NodeHostUdpSocket {
+    socket;
+    msgQueue = [];
+    waiters = [];
+    closed = false;
+    constructor(socket) {
+        this.socket = socket;
+        socket.on("message", (msg, rinfo) => {
+            const entry = {
+                data: new Uint8Array(msg),
+                remoteAddr: { host: rinfo.address, port: rinfo.port },
+            };
+            const waiter = this.waiters.shift();
+            if (waiter) {
+                waiter(entry);
+            }
+            else {
+                this.msgQueue.push(entry);
+            }
+        });
+    }
+    async recv() {
+        const queued = this.msgQueue.shift();
+        if (queued)
+            return queued;
+        if (this.closed)
+            throw new Error("UDP socket closed");
+        return new Promise((resolve, reject) => {
+            if (this.closed) {
+                reject(new Error("UDP socket closed"));
+                return;
+            }
+            this.waiters.push(resolve);
+        });
+    }
+    async close() {
+        this.closed = true;
+        return new Promise((resolve) => {
+            this.socket.close(() => resolve());
+        });
+    }
+}
+/** Create a Node.js HostNetworkAdapter that uses real OS networking. */
+export function createNodeHostNetworkAdapter() {
+    return {
+        async tcpConnect(host, port) {
+            return new Promise((resolve, reject) => {
+                const socket = net.connect({ host, port });
+                socket.once("connect", () => {
+                    socket.removeListener("error", reject);
+                    resolve(new NodeHostSocket(socket));
+                });
+                socket.once("error", (err) => {
+                    socket.removeListener("connect", resolve);
+                    reject(err);
+                });
+            });
+        },
+        async tcpListen(host, port) {
+            return new Promise((resolve, reject) => {
+                const server = net.createServer();
+                server.once("listening", () => {
+                    server.removeListener("error", reject);
+                    const addr = server.address();
+                    resolve(new NodeHostListener(server, addr.port));
+                });
+                server.once("error", (err) => {
+                    server.removeListener("listening", resolve);
+                    reject(err);
+                });
+                server.listen(port, host);
+            });
+        },
+        async udpBind(host, port) {
+            return new Promise((resolve, reject) => {
+                const socket = dgram.createSocket("udp4");
+                socket.once("listening", () => {
+                    socket.removeListener("error", reject);
+                    resolve(new NodeHostUdpSocket(socket));
+                });
+                socket.once("error", (err) => {
+                    socket.removeListener("listening", resolve);
+                    reject(err);
+                });
+                socket.bind(port, host);
+            });
+        },
+        async udpSend(socket, data, host, port) {
+            // Access the underlying dgram socket via the wrapper
+            const udp = socket;
+            const inner = udp.socket;
+            return new Promise((resolve, reject) => {
+                inner.send(data, 0, data.length, port, host, (err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+            });
+        },
+        async dnsLookup(hostname, rrtype) {
+            const family = rrtype === "AAAA" ? 6 : 4;
+            return new Promise((resolve, reject) => {
+                dns.lookup(hostname, { family }, (err, address, resultFamily) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve({ address, family: resultFamily });
+                });
+            });
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { getRawBridgeCode, getBridgeAttachCode } from "./bridge-loader.js";
+export { bundlePolyfill, getAvailableStdlib, hasPolyfill, prebundleAllPolyfills, } from "./polyfills.js";
+export { NodeExecutionDriver } from "./execution-driver.js";
+export type { NodeExecutionDriverOptions } from "./isolate-bootstrap.js";
+export { createDefaultNetworkAdapter, createNodeDriver, createNodeRuntimeDriverFactory, NodeFileSystem, filterEnv, isPrivateIp, } from "./driver.js";
+export type { NodeDriverOptions, NodeRuntimeDriverFactoryOptions, } from "./driver.js";
+export { ModuleAccessFileSystem } from "./module-access.js";
+export type { ModuleAccessOptions } from "./module-access.js";
+export { emitConsoleEvent, stripDangerousEnv, createProcessConfigForExecution, } from "./bridge-handlers.js";
+export type { BindingTree, BindingFunction } from "./bindings.js";
+export { BINDING_PREFIX, flattenBindingTree } from "./bindings.js";
+export { createNodeRuntime } from "./kernel-runtime.js";
+export type { NodeRuntimeOptions } from "./kernel-runtime.js";
+export { createKernelCommandExecutor, createKernelVfsAdapter, createHostFallbackVfs, } from "./kernel-runtime.js";
+export { HostNodeFileSystem } from "./os-filesystem.js";
+export type { HostNodeFileSystemOptions } from "./os-filesystem.js";
+export { NodeWorkerAdapter } from "./worker-adapter.js";
+export type { WorkerHandle } from "./worker-adapter.js";
+export { createNodeHostNetworkAdapter } from "./host-network-adapter.js";
+export { TIMEOUT_EXIT_CODE, TIMEOUT_ERROR_MESSAGE, } from "@secure-exec/core";

package/dist/index.js

@@ -0,0 +1,23 @@
+// Bridge compilation
+export { getRawBridgeCode, getBridgeAttachCode } from "./bridge-loader.js";
+// Stdlib polyfill bundling
+export { bundlePolyfill, getAvailableStdlib, hasPolyfill, prebundleAllPolyfills, } from "./polyfills.js";
+// Node execution driver
+export { NodeExecutionDriver } from "./execution-driver.js";
+// Node system driver
+export { createDefaultNetworkAdapter, createNodeDriver, createNodeRuntimeDriverFactory, NodeFileSystem, filterEnv, isPrivateIp, } from "./driver.js";
+// Module access filesystem
+export { ModuleAccessFileSystem } from "./module-access.js";
+// Bridge handlers
+export { emitConsoleEvent, stripDangerousEnv, createProcessConfigForExecution, } from "./bridge-handlers.js";
+export { BINDING_PREFIX, flattenBindingTree } from "./bindings.js";
+// Kernel runtime driver (RuntimeDriver for kernel.mount())
+export { createNodeRuntime } from "./kernel-runtime.js";
+export { createKernelCommandExecutor, createKernelVfsAdapter, createHostFallbackVfs, } from "./kernel-runtime.js";
+// OS platform adapters (host filesystem with root, worker threads)
+export { HostNodeFileSystem } from "./os-filesystem.js";
+export { NodeWorkerAdapter } from "./worker-adapter.js";
+// Host network adapter (HostNetworkAdapter for kernel delegation)
+export { createNodeHostNetworkAdapter } from "./host-network-adapter.js";
+// Timeout utilities (re-exported from core)
+export { TIMEOUT_EXIT_CODE, TIMEOUT_ERROR_MESSAGE, } from "@secure-exec/core";

package/dist/isolate-bootstrap.d.ts

@@ -0,0 +1,86 @@
+import type { Permissions, VirtualFileSystem } from "@secure-exec/core";
+import type { CommandExecutor, NetworkAdapter, RuntimeDriverOptions, SpawnedProcess } from "@secure-exec/core";
+import type { StdioHook, OSConfig, ProcessConfig, TimingMitigation } from "@secure-exec/core/internal/shared/api-types";
+import type { ResolutionCache } from "./package-bundler.js";
+import type { BindingTree } from "./bindings.js";
+export interface NodeExecutionDriverOptions extends RuntimeDriverOptions {
+    createIsolate?(memoryLimit: number): unknown;
+    bindings?: BindingTree;
+    /** Callback to toggle PTY raw mode — wired by kernel runtime when PTY is attached. */
+    onPtySetRawMode?: (mode: boolean) => void;
+    /** Kernel socket table — routes net.connect through kernel instead of host TCP. */
+    socketTable?: import("@secure-exec/core").SocketTable;
+    /** Kernel process table — registers child processes for cross-runtime visibility. */
+    processTable?: import("@secure-exec/core").ProcessTable;
+    /** Kernel timer table — tracks sandbox timers for budget enforcement and cleanup. */
+    timerTable?: import("@secure-exec/core").TimerTable;
+    /** Process ID for kernel socket/process ownership. Required when socketTable/processTable is set. */
+    pid?: number;
+}
+export interface BudgetState {
+    outputBytes: number;
+    bridgeCalls: number;
+    activeTimers: number;
+    childProcesses: number;
+}
+/** Shared mutable state owned by NodeExecutionDriver, passed to extracted modules. */
+export interface DriverDeps {
+    filesystem: VirtualFileSystem;
+    commandExecutor: CommandExecutor;
+    networkAdapter: NetworkAdapter;
+    permissions?: Permissions;
+    processConfig: ProcessConfig;
+    osConfig: OSConfig;
+    onStdio?: StdioHook;
+    cpuTimeLimitMs?: number;
+    timingMitigation: TimingMitigation;
+    bridgeBase64TransferLimitBytes: number;
+    isolateJsonPayloadLimitBytes: number;
+    maxOutputBytes?: number;
+    maxBridgeCalls?: number;
+    maxTimers?: number;
+    maxChildProcesses?: number;
+    maxHandles?: number;
+    budgetState: BudgetState;
+    activeHttpServerIds: Set<number>;
+    activeHttpServerClosers: Map<number, () => Promise<void>>;
+    activeChildProcesses: Map<number, SpawnedProcess>;
+    activeHostTimers: Set<ReturnType<typeof setTimeout>>;
+    moduleFormatCache: Map<string, "esm" | "cjs" | "json">;
+    packageTypeCache: Map<string, "module" | "commonjs" | null>;
+    resolutionCache: ResolutionCache;
+    /** Optional callback for PTY setRawMode — wired by kernel when PTY is attached. */
+    onPtySetRawMode?: (mode: boolean) => void;
+}
+export declare const DEFAULT_BRIDGE_BASE64_TRANSFER_BYTES: number;
+export declare const DEFAULT_ISOLATE_JSON_PAYLOAD_BYTES: number;
+export declare const MIN_CONFIGURED_PAYLOAD_BYTES = 1024;
+export declare const MAX_CONFIGURED_PAYLOAD_BYTES: number;
+export declare const PAYLOAD_LIMIT_ERROR_CODE = "ERR_SANDBOX_PAYLOAD_TOO_LARGE";
+export declare const RESOURCE_BUDGET_ERROR_CODE = "ERR_RESOURCE_BUDGET_EXCEEDED";
+export declare const DEFAULT_MAX_TIMERS = 10000;
+export declare const DEFAULT_MAX_HANDLES = 10000;
+export declare const DEFAULT_SANDBOX_CWD = "/root";
+export declare const DEFAULT_SANDBOX_HOME = "/root";
+export declare const DEFAULT_SANDBOX_TMPDIR = "/tmp";
+export declare class PayloadLimitError extends Error {
+    constructor(payloadLabel: string, maxBytes: number, actualBytes: number);
+}
+export declare function normalizePayloadLimit(configuredValue: number | undefined, defaultValue: number, optionName: string): number;
+export declare function getUtf8ByteLength(text: string): number;
+export declare function getBase64EncodedByteLength(rawByteLength: number): number;
+export declare function assertPayloadByteLength(payloadLabel: string, actualBytes: number, maxBytes: number): void;
+export declare function assertTextPayloadSize(payloadLabel: string, text: string, maxBytes: number): void;
+export declare function createBudgetState(): BudgetState;
+export declare function clearActiveHostTimers(deps: Pick<DriverDeps, "activeHostTimers">): void;
+export declare function killActiveChildProcesses(deps: Pick<DriverDeps, "activeChildProcesses">): void;
+export declare function checkBridgeBudget(deps: Pick<DriverDeps, "maxBridgeCalls" | "budgetState">): void;
+export declare function parseJsonWithLimit<T>(payloadLabel: string, jsonText: string, maxBytes: number): T;
+export declare function getExecutionTimeoutMs(override: number | undefined, cpuTimeLimitMs: number | undefined): number | undefined;
+export declare function getTimingMitigation(override: TimingMitigation | undefined, defaultMitigation: TimingMitigation): TimingMitigation;
+export declare const polyfillCodeCache: Map<string, string>;
+export declare const polyfillNamedExportsCache: Map<string, string[]>;
+export declare const hostBuiltinNamedExportsCache: Map<string, string[]>;
+export declare const hostRequire: NodeJS.Require;
+export declare function isValidExportName(name: string): boolean;
+export declare function getHostBuiltinNamedExports(moduleName: string): string[];

package/dist/isolate-bootstrap.js

@@ -0,0 +1,125 @@
+import { createRequire } from "node:module";
+// Constants
+export const DEFAULT_BRIDGE_BASE64_TRANSFER_BYTES = 16 * 1024 * 1024;
+export const DEFAULT_ISOLATE_JSON_PAYLOAD_BYTES = 4 * 1024 * 1024;
+export const MIN_CONFIGURED_PAYLOAD_BYTES = 1024;
+export const MAX_CONFIGURED_PAYLOAD_BYTES = 64 * 1024 * 1024;
+export const PAYLOAD_LIMIT_ERROR_CODE = "ERR_SANDBOX_PAYLOAD_TOO_LARGE";
+export const RESOURCE_BUDGET_ERROR_CODE = "ERR_RESOURCE_BUDGET_EXCEEDED";
+export const DEFAULT_MAX_TIMERS = 10_000;
+export const DEFAULT_MAX_HANDLES = 10_000;
+export const DEFAULT_SANDBOX_CWD = "/root";
+export const DEFAULT_SANDBOX_HOME = "/root";
+export const DEFAULT_SANDBOX_TMPDIR = "/tmp";
+export class PayloadLimitError extends Error {
+    constructor(payloadLabel, maxBytes, actualBytes) {
+        super(`${PAYLOAD_LIMIT_ERROR_CODE}: ${payloadLabel} exceeds ${maxBytes} bytes (got ${actualBytes})`);
+        this.name = "PayloadLimitError";
+    }
+}
+export function normalizePayloadLimit(configuredValue, defaultValue, optionName) {
+    if (configuredValue === undefined) {
+        return defaultValue;
+    }
+    if (!Number.isFinite(configuredValue) || configuredValue <= 0) {
+        throw new RangeError(`${optionName} must be a positive finite number`);
+    }
+    const normalizedValue = Math.floor(configuredValue);
+    if (normalizedValue < MIN_CONFIGURED_PAYLOAD_BYTES) {
+        throw new RangeError(`${optionName} must be at least ${MIN_CONFIGURED_PAYLOAD_BYTES} bytes`);
+    }
+    if (normalizedValue > MAX_CONFIGURED_PAYLOAD_BYTES) {
+        throw new RangeError(`${optionName} must be at most ${MAX_CONFIGURED_PAYLOAD_BYTES} bytes`);
+    }
+    return normalizedValue;
+}
+export function getUtf8ByteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+export function getBase64EncodedByteLength(rawByteLength) {
+    return Math.ceil(rawByteLength / 3) * 4;
+}
+export function assertPayloadByteLength(payloadLabel, actualBytes, maxBytes) {
+    if (actualBytes <= maxBytes) {
+        return;
+    }
+    throw new PayloadLimitError(payloadLabel, maxBytes, actualBytes);
+}
+export function assertTextPayloadSize(payloadLabel, text, maxBytes) {
+    assertPayloadByteLength(payloadLabel, getUtf8ByteLength(text), maxBytes);
+}
+export function createBudgetState() {
+    return { outputBytes: 0, bridgeCalls: 0, activeTimers: 0, childProcesses: 0 };
+}
+export function clearActiveHostTimers(deps) {
+    for (const id of deps.activeHostTimers) {
+        clearTimeout(id);
+    }
+    deps.activeHostTimers.clear();
+}
+export function killActiveChildProcesses(deps) {
+    for (const proc of deps.activeChildProcesses.values()) {
+        try {
+            proc.kill(9); // SIGKILL
+        }
+        catch {
+            // Process may already be dead
+        }
+    }
+    deps.activeChildProcesses.clear();
+}
+export function checkBridgeBudget(deps) {
+    if (deps.maxBridgeCalls === undefined)
+        return;
+    deps.budgetState.bridgeCalls++;
+    if (deps.budgetState.bridgeCalls > deps.maxBridgeCalls) {
+        throw new Error(`${RESOURCE_BUDGET_ERROR_CODE}: maximum bridge calls exceeded`);
+    }
+}
+export function parseJsonWithLimit(payloadLabel, jsonText, maxBytes) {
+    assertTextPayloadSize(payloadLabel, jsonText, maxBytes);
+    return JSON.parse(jsonText);
+}
+export function getExecutionTimeoutMs(override, cpuTimeLimitMs) {
+    const timeoutMs = override ?? cpuTimeLimitMs;
+    if (timeoutMs === undefined) {
+        return undefined;
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new RangeError("cpuTimeLimitMs must be a positive finite number");
+    }
+    return Math.floor(timeoutMs);
+}
+export function getTimingMitigation(override, defaultMitigation) {
+    return override ?? defaultMitigation;
+}
+// Module-level caches for polyfill and host builtin named exports
+export const polyfillCodeCache = new Map();
+export const polyfillNamedExportsCache = new Map();
+export const hostBuiltinNamedExportsCache = new Map();
+export const hostRequire = createRequire(import.meta.url);
+export function isValidExportName(name) {
+    return /^[A-Za-z_$][\w$]*$/.test(name);
+}
+export function getHostBuiltinNamedExports(moduleName) {
+    const cached = hostBuiltinNamedExportsCache.get(moduleName);
+    if (cached) {
+        return cached;
+    }
+    try {
+        const loaded = hostRequire(`node:${moduleName}`);
+        const names = Array.from(new Set([
+            ...Object.keys(loaded ?? {}),
+            ...Object.getOwnPropertyNames(loaded ?? {}),
+        ]))
+            .filter((name) => name !== "default")
+            .filter(isValidExportName)
+            .sort();
+        hostBuiltinNamedExportsCache.set(moduleName, names);
+        return names;
+    }
+    catch {
+        hostBuiltinNamedExportsCache.set(moduleName, []);
+        return [];
+    }
+}

package/dist/ivm-compat.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generate JS source for the ivm-compat shim.
+ *
+ * Must run AFTER the Rust side registers bridge functions on the global,
+ * and BEFORE the bridge bundle IIFE executes.
+ */
+export declare function getIvmCompatShimSource(): string;

package/dist/ivm-compat.js

@@ -0,0 +1,31 @@
+// Compatibility shim for bridge calling conventions.
+//
+// The bridge bundle code calls host functions via ivm.Reference methods:
+//   .applySync(ctx, args)       — sync call
+//   .applySyncPromise(ctx, args) — sync call (host may be async)
+//   .apply(ctx, args, opts)     — async call (opts ignored, Function.prototype.apply works)
+//
+// The Rust V8 runtime registers host functions as plain FunctionTemplate functions.
+// This shim adds the missing .applySync() and .applySyncPromise() methods.
+// .apply() already works via Function.prototype.apply (third arg is ignored).
+import { HOST_BRIDGE_GLOBAL_KEY_LIST, } from "./bridge-contract.js";
+/**
+ * Generate JS source for the ivm-compat shim.
+ *
+ * Must run AFTER the Rust side registers bridge functions on the global,
+ * and BEFORE the bridge bundle IIFE executes.
+ */
+export function getIvmCompatShimSource() {
+    const keyListJson = JSON.stringify(HOST_BRIDGE_GLOBAL_KEY_LIST.filter(
+    // _processConfig and _osConfig are config objects, not callable functions
+    (k) => k !== "_processConfig" && k !== "_osConfig"));
+    return `(function(){
+  var keys = ${keyListJson};
+  for (var i = 0; i < keys.length; i++) {
+    var fn = globalThis[keys[i]];
+    if (typeof fn !== 'function') continue;
+    fn.applySync = function(ctx, args) { return this.call(null, ...(args || [])); };
+    fn.applySyncPromise = function(ctx, args) { return this.call(null, ...(args || [])); };
+  }
+})();`;
+}

package/dist/kernel-runtime.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Node.js runtime driver for kernel integration.
+ *
+ * Wraps the existing NodeExecutionDriver behind the kernel RuntimeDriver
+ * interface. Each spawn() creates a fresh V8 isolate via NodeExecutionDriver
+ * and executes the target script. The bridge child_process.spawn routes
+ * through KernelInterface.spawn() so shell commands dispatch to WasmVM
+ * or other mounted runtimes.
+ */
+import type { KernelRuntimeDriver as RuntimeDriver, KernelInterface, Permissions, VirtualFileSystem } from '@secure-exec/core';
+import type { BindingTree } from './bindings.js';
+import type { CommandExecutor } from '@secure-exec/core';
+export interface NodeRuntimeOptions {
+    /** Memory limit in MB for each V8 isolate (default: 128). */
+    memoryLimit?: number;
+    /**
+     * Host filesystem paths that the isolate may read for module resolution
+     * (e.g. npm's own install directory). By default, the driver discovers
+     * the host npm location automatically.
+     */
+    moduleAccessPaths?: string[];
+    /**
+     * Bridge permissions for isolate processes. Defaults to allowAllChildProcess
+     * (fs/network/env deny-by-default). Use allowAll for full sandbox access.
+     */
+    permissions?: Partial<Permissions>;
+    /**
+     * Host-side functions exposed to sandbox code via SecureExec.bindings.
+     * Nested objects become dot-separated paths (max depth 4, max 64 leaves).
+     */
+    bindings?: BindingTree;
+}
+/**
+ * Create a Node.js RuntimeDriver that can be mounted into the kernel.
+ */
+export declare function createNodeRuntime(options?: NodeRuntimeOptions): RuntimeDriver;
+/**
+ * CommandExecutor adapter that wraps KernelInterface.spawn().
+ * This is the critical integration point: when code inside the V8 isolate
+ * calls child_process.spawn('sh', ['-c', 'echo hello']), the bridge
+ * delegates here, which calls kernel.spawn() to route 'sh' to WasmVM.
+ */
+export declare function createKernelCommandExecutor(kernel: KernelInterface, parentPid: number): CommandExecutor;
+/**
+ * Thin adapter from kernel VFS to secure-exec VFS interface.
+ * The kernel VFS is a superset, so this just narrows the type.
+ */
+export declare function createKernelVfsAdapter(kernelVfs: KernelInterface['vfs']): VirtualFileSystem;
+/**
+ * Wrap a VFS with host filesystem fallback for read operations.
+ *
+ * When npm/npx runs inside the V8 isolate, require() must resolve npm's own
+ * internal modules (e.g. '../lib/cli/entry'). These live on the host
+ * filesystem, not in the kernel VFS. This wrapper tries the kernel VFS first
+ * and falls back to the host filesystem for reads. Writes always go to the
+ * kernel VFS.
+ */
+export declare function createHostFallbackVfs(base: VirtualFileSystem): VirtualFileSystem;