@secure-exec/nodejs 0.2.0-rc.1

package/dist/bridge-contract.js

@@ -0,0 +1,172 @@
+/**
+ * Bridge contract: typed declarations for the globals shared between the
+ * host (Node.js) and the isolate (sandbox V8 context).
+ *
+ * Two categories:
+ * - Host bridge globals: set by the host before bridge code runs (fs refs, timers, etc.)
+ * - Runtime bridge globals: installed by the bridge bundle itself (active handles, modules, etc.)
+ *
+ * The typed `Ref` aliases describe the bridge calling convention for each global.
+ */
+function valuesOf(object) {
+    return Object.values(object);
+}
+/** Globals injected by the host before the bridge bundle executes. */
+export const HOST_BRIDGE_GLOBAL_KEYS = {
+    dynamicImport: "_dynamicImport",
+    loadPolyfill: "_loadPolyfill",
+    resolveModule: "_resolveModule",
+    loadFile: "_loadFile",
+    scheduleTimer: "_scheduleTimer",
+    cryptoRandomFill: "_cryptoRandomFill",
+    cryptoRandomUuid: "_cryptoRandomUUID",
+    cryptoHashDigest: "_cryptoHashDigest",
+    cryptoHmacDigest: "_cryptoHmacDigest",
+    cryptoPbkdf2: "_cryptoPbkdf2",
+    cryptoScrypt: "_cryptoScrypt",
+    cryptoCipheriv: "_cryptoCipheriv",
+    cryptoDecipheriv: "_cryptoDecipheriv",
+    cryptoCipherivCreate: "_cryptoCipherivCreate",
+    cryptoCipherivUpdate: "_cryptoCipherivUpdate",
+    cryptoCipherivFinal: "_cryptoCipherivFinal",
+    cryptoSign: "_cryptoSign",
+    cryptoVerify: "_cryptoVerify",
+    cryptoAsymmetricOp: "_cryptoAsymmetricOp",
+    cryptoCreateKeyObject: "_cryptoCreateKeyObject",
+    cryptoGenerateKeyPairSync: "_cryptoGenerateKeyPairSync",
+    cryptoGenerateKeySync: "_cryptoGenerateKeySync",
+    cryptoGeneratePrimeSync: "_cryptoGeneratePrimeSync",
+    cryptoDiffieHellman: "_cryptoDiffieHellman",
+    cryptoDiffieHellmanGroup: "_cryptoDiffieHellmanGroup",
+    cryptoDiffieHellmanSessionCreate: "_cryptoDiffieHellmanSessionCreate",
+    cryptoDiffieHellmanSessionCall: "_cryptoDiffieHellmanSessionCall",
+    cryptoSubtle: "_cryptoSubtle",
+    fsReadFile: "_fsReadFile",
+    fsWriteFile: "_fsWriteFile",
+    fsReadFileBinary: "_fsReadFileBinary",
+    fsWriteFileBinary: "_fsWriteFileBinary",
+    fsReadDir: "_fsReadDir",
+    fsMkdir: "_fsMkdir",
+    fsRmdir: "_fsRmdir",
+    fsExists: "_fsExists",
+    fsStat: "_fsStat",
+    fsUnlink: "_fsUnlink",
+    fsRename: "_fsRename",
+    fsChmod: "_fsChmod",
+    fsChown: "_fsChown",
+    fsLink: "_fsLink",
+    fsSymlink: "_fsSymlink",
+    fsReadlink: "_fsReadlink",
+    fsLstat: "_fsLstat",
+    fsTruncate: "_fsTruncate",
+    fsUtimes: "_fsUtimes",
+    childProcessSpawnStart: "_childProcessSpawnStart",
+    childProcessStdinWrite: "_childProcessStdinWrite",
+    childProcessStdinClose: "_childProcessStdinClose",
+    childProcessKill: "_childProcessKill",
+    childProcessSpawnSync: "_childProcessSpawnSync",
+    networkFetchRaw: "_networkFetchRaw",
+    networkDnsLookupRaw: "_networkDnsLookupRaw",
+    networkHttpRequestRaw: "_networkHttpRequestRaw",
+    networkHttpServerListenRaw: "_networkHttpServerListenRaw",
+    networkHttpServerCloseRaw: "_networkHttpServerCloseRaw",
+    networkHttpServerRespondRaw: "_networkHttpServerRespondRaw",
+    networkHttpServerWaitRaw: "_networkHttpServerWaitRaw",
+    networkHttp2ServerListenRaw: "_networkHttp2ServerListenRaw",
+    networkHttp2ServerCloseRaw: "_networkHttp2ServerCloseRaw",
+    networkHttp2ServerWaitRaw: "_networkHttp2ServerWaitRaw",
+    networkHttp2SessionConnectRaw: "_networkHttp2SessionConnectRaw",
+    networkHttp2SessionRequestRaw: "_networkHttp2SessionRequestRaw",
+    networkHttp2SessionSettingsRaw: "_networkHttp2SessionSettingsRaw",
+    networkHttp2SessionSetLocalWindowSizeRaw: "_networkHttp2SessionSetLocalWindowSizeRaw",
+    networkHttp2SessionGoawayRaw: "_networkHttp2SessionGoawayRaw",
+    networkHttp2SessionCloseRaw: "_networkHttp2SessionCloseRaw",
+    networkHttp2SessionDestroyRaw: "_networkHttp2SessionDestroyRaw",
+    networkHttp2SessionWaitRaw: "_networkHttp2SessionWaitRaw",
+    networkHttp2ServerPollRaw: "_networkHttp2ServerPollRaw",
+    networkHttp2SessionPollRaw: "_networkHttp2SessionPollRaw",
+    networkHttp2StreamRespondRaw: "_networkHttp2StreamRespondRaw",
+    networkHttp2StreamPushStreamRaw: "_networkHttp2StreamPushStreamRaw",
+    networkHttp2StreamWriteRaw: "_networkHttp2StreamWriteRaw",
+    networkHttp2StreamEndRaw: "_networkHttp2StreamEndRaw",
+    networkHttp2StreamPauseRaw: "_networkHttp2StreamPauseRaw",
+    networkHttp2StreamResumeRaw: "_networkHttp2StreamResumeRaw",
+    networkHttp2StreamRespondWithFileRaw: "_networkHttp2StreamRespondWithFileRaw",
+    networkHttp2ServerRespondRaw: "_networkHttp2ServerRespondRaw",
+    upgradeSocketWriteRaw: "_upgradeSocketWriteRaw",
+    upgradeSocketEndRaw: "_upgradeSocketEndRaw",
+    upgradeSocketDestroyRaw: "_upgradeSocketDestroyRaw",
+    netSocketConnectRaw: "_netSocketConnectRaw",
+    netSocketWaitConnectRaw: "_netSocketWaitConnectRaw",
+    netSocketReadRaw: "_netSocketReadRaw",
+    netSocketSetNoDelayRaw: "_netSocketSetNoDelayRaw",
+    netSocketSetKeepAliveRaw: "_netSocketSetKeepAliveRaw",
+    netSocketWriteRaw: "_netSocketWriteRaw",
+    netSocketEndRaw: "_netSocketEndRaw",
+    netSocketDestroyRaw: "_netSocketDestroyRaw",
+    netSocketUpgradeTlsRaw: "_netSocketUpgradeTlsRaw",
+    netSocketGetTlsClientHelloRaw: "_netSocketGetTlsClientHelloRaw",
+    netSocketTlsQueryRaw: "_netSocketTlsQueryRaw",
+    tlsGetCiphersRaw: "_tlsGetCiphersRaw",
+    netServerListenRaw: "_netServerListenRaw",
+    netServerAcceptRaw: "_netServerAcceptRaw",
+    netServerCloseRaw: "_netServerCloseRaw",
+    dgramSocketCreateRaw: "_dgramSocketCreateRaw",
+    dgramSocketBindRaw: "_dgramSocketBindRaw",
+    dgramSocketRecvRaw: "_dgramSocketRecvRaw",
+    dgramSocketSendRaw: "_dgramSocketSendRaw",
+    dgramSocketCloseRaw: "_dgramSocketCloseRaw",
+    dgramSocketAddressRaw: "_dgramSocketAddressRaw",
+    dgramSocketSetBufferSizeRaw: "_dgramSocketSetBufferSizeRaw",
+    dgramSocketGetBufferSizeRaw: "_dgramSocketGetBufferSizeRaw",
+    resolveModuleSync: "_resolveModuleSync",
+    loadFileSync: "_loadFileSync",
+    ptySetRawMode: "_ptySetRawMode",
+    processConfig: "_processConfig",
+    osConfig: "_osConfig",
+    log: "_log",
+    error: "_error",
+    // Kernel FD table operations — dispatched through _loadPolyfill bridge
+    fdOpen: "_fdOpen",
+    fdClose: "_fdClose",
+    fdRead: "_fdRead",
+    fdWrite: "_fdWrite",
+    fdFstat: "_fdFstat",
+    fdFtruncate: "_fdFtruncate",
+    fdFsync: "_fdFsync",
+    fdGetPath: "_fdGetPath",
+};
+/** Globals exposed by the bridge bundle and runtime scripts inside the isolate. */
+export const RUNTIME_BRIDGE_GLOBAL_KEYS = {
+    registerHandle: "_registerHandle",
+    unregisterHandle: "_unregisterHandle",
+    waitForActiveHandles: "_waitForActiveHandles",
+    getActiveHandles: "_getActiveHandles",
+    childProcessDispatch: "_childProcessDispatch",
+    childProcessModule: "_childProcessModule",
+    moduleModule: "_moduleModule",
+    osModule: "_osModule",
+    httpModule: "_httpModule",
+    httpsModule: "_httpsModule",
+    http2Module: "_http2Module",
+    dnsModule: "_dnsModule",
+    dgramModule: "_dgramModule",
+    httpServerDispatch: "_httpServerDispatch",
+    httpServerUpgradeDispatch: "_httpServerUpgradeDispatch",
+    httpServerConnectDispatch: "_httpServerConnectDispatch",
+    http2Dispatch: "_http2Dispatch",
+    timerDispatch: "_timerDispatch",
+    upgradeSocketData: "_upgradeSocketData",
+    upgradeSocketEnd: "_upgradeSocketEnd",
+    netSocketDispatch: "_netSocketDispatch",
+    fsFacade: "_fs",
+    requireFrom: "_requireFrom",
+    moduleCache: "_moduleCache",
+    processExitError: "ProcessExitError",
+};
+export const HOST_BRIDGE_GLOBAL_KEY_LIST = valuesOf(HOST_BRIDGE_GLOBAL_KEYS);
+export const RUNTIME_BRIDGE_GLOBAL_KEY_LIST = valuesOf(RUNTIME_BRIDGE_GLOBAL_KEYS);
+export const BRIDGE_GLOBAL_KEY_LIST = [
+    ...HOST_BRIDGE_GLOBAL_KEY_LIST,
+    ...RUNTIME_BRIDGE_GLOBAL_KEY_LIST,
+];

package/dist/bridge-handlers.d.ts

@@ -0,0 +1,199 @@
+import type { CommandExecutor, NetworkAdapter, SpawnedProcess } from "@secure-exec/core";
+import type { VirtualFileSystem } from "@secure-exec/core";
+import type { ResolutionCache } from "./package-bundler.js";
+import type { StdioEvent, StdioHook, ProcessConfig } from "@secure-exec/core/internal/shared/api-types";
+import type { BudgetState } from "./isolate-bootstrap.js";
+/** A bridge handler function invoked when sandbox code calls a bridge global. */
+export type BridgeHandler = (...args: unknown[]) => unknown | Promise<unknown>;
+/** Map of bridge global names to their handler functions. */
+export type BridgeHandlers = Record<string, BridgeHandler>;
+/** Result of building crypto bridge handlers — includes dispose for session cleanup. */
+export interface CryptoBridgeResult {
+    handlers: BridgeHandlers;
+    dispose: () => void;
+}
+/**
+ * Build crypto bridge handlers.
+ *
+ * All handler functions are plain functions (no ivm.Reference wrapping).
+ * The V8 runtime registers these by name on the V8 global.
+ * Call dispose() when the execution ends to clear stateful cipher sessions.
+ */
+export declare function buildCryptoBridgeHandlers(): CryptoBridgeResult;
+/** Dependencies for building net socket bridge handlers. */
+export interface NetSocketBridgeDeps {
+    /** Dispatch a socket event back to the guest (socketId, event, data?). */
+    dispatch: (socketId: number, event: string, data?: string) => void;
+    /** Kernel socket table — when provided, routes through kernel instead of host TCP. */
+    socketTable?: import("@secure-exec/core").SocketTable;
+    /** Process ID for kernel socket ownership. Required when socketTable is set. */
+    pid?: number;
+}
+/** Result of building net socket bridge handlers — includes dispose for cleanup. */
+export interface NetSocketBridgeResult {
+    handlers: BridgeHandlers;
+    dispose: () => void;
+}
+/**
+ * Build net socket bridge handlers.
+ *
+ * All TCP operations route through kernel sockets (loopback or external via
+ * the host adapter).
+ * Call dispose() when the execution ends to destroy all open sockets.
+ */
+export declare function buildNetworkSocketBridgeHandlers(deps: NetSocketBridgeDeps): NetSocketBridgeResult;
+/** Dependencies for building sync module resolution bridge handlers. */
+export interface ModuleResolutionBridgeDeps {
+    /** Translate sandbox path (e.g. /root/node_modules/...) to host path. */
+    sandboxToHostPath: (sandboxPath: string) => string | null;
+    /** Translate host path back to sandbox path. */
+    hostToSandboxPath: (hostPath: string) => string;
+}
+/**
+ * Build sync module resolution bridge handlers.
+ *
+ * These use Node.js require.resolve() and readFileSync() directly,
+ * avoiding the async VirtualFileSystem path. Needed because the async
+ * applySyncPromise pattern can't nest inside synchronous bridge
+ * callbacks (e.g. net socket data events that trigger require()).
+ */
+export declare function buildModuleResolutionBridgeHandlers(deps: ModuleResolutionBridgeDeps): BridgeHandlers;
+/** Strip env vars that allow library injection or node flag smuggling. */
+export declare function stripDangerousEnv(env: Record<string, string> | undefined): Record<string, string> | undefined;
+export declare function emitConsoleEvent(onStdio: StdioHook | undefined, event: StdioEvent): void;
+/** Dependencies for console bridge handlers. */
+export interface ConsoleBridgeDeps {
+    onStdio?: StdioHook;
+    budgetState: BudgetState;
+    maxOutputBytes?: number;
+}
+/** Build console/logging bridge handlers. */
+export declare function buildConsoleBridgeHandlers(deps: ConsoleBridgeDeps): BridgeHandlers;
+/** Dependencies for module loading bridge handlers. */
+export interface ModuleLoadingBridgeDeps {
+    filesystem: VirtualFileSystem;
+    resolutionCache: ResolutionCache;
+    resolveMode?: "require" | "import";
+    /** Convert sandbox path to host path for pnpm/symlink resolution fallback. */
+    sandboxToHostPath?: (sandboxPath: string) => string | null;
+}
+/** Build module loading bridge handlers (loadPolyfill, resolveModule, loadFile). */
+export declare function buildModuleLoadingBridgeHandlers(deps: ModuleLoadingBridgeDeps, 
+/** Extra handlers to dispatch through _loadPolyfill for V8 runtime compatibility. */
+dispatchHandlers?: BridgeHandlers): BridgeHandlers;
+/** Dependencies for timer bridge handlers. */
+export interface TimerBridgeDeps {
+    budgetState: BudgetState;
+    maxBridgeCalls?: number;
+    activeHostTimers: Set<ReturnType<typeof setTimeout>>;
+}
+/** Build timer bridge handler. */
+export declare function buildTimerBridgeHandlers(deps: TimerBridgeDeps): BridgeHandlers;
+export interface KernelTimerDispatchDeps {
+    timerTable: import("@secure-exec/core").TimerTable;
+    pid: number;
+    budgetState: BudgetState;
+    maxBridgeCalls?: number;
+    activeHostTimers: Set<ReturnType<typeof setTimeout>>;
+    sendStreamEvent(eventType: string, payload: Uint8Array): void;
+}
+export declare function buildKernelTimerDispatchHandlers(deps: KernelTimerDispatchDeps): BridgeHandlers;
+export interface KernelHandleDispatchDeps {
+    processTable?: import("@secure-exec/core").ProcessTable;
+    pid: number;
+    budgetState: BudgetState;
+    maxBridgeCalls?: number;
+}
+export declare function buildKernelHandleDispatchHandlers(deps: KernelHandleDispatchDeps): BridgeHandlers;
+/** Dependencies for filesystem bridge handlers. */
+export interface FsBridgeDeps {
+    filesystem: VirtualFileSystem;
+    budgetState: BudgetState;
+    maxBridgeCalls?: number;
+    bridgeBase64TransferLimitBytes: number;
+    isolateJsonPayloadLimitBytes: number;
+}
+/** Build filesystem bridge handlers (readFile, writeFile, stat, etc.). */
+export declare function buildFsBridgeHandlers(deps: FsBridgeDeps): BridgeHandlers;
+/** Dependencies for child process bridge handlers. */
+export interface ChildProcessBridgeDeps {
+    commandExecutor: CommandExecutor;
+    processConfig: ProcessConfig;
+    budgetState: BudgetState;
+    maxBridgeCalls?: number;
+    maxChildProcesses?: number;
+    isolateJsonPayloadLimitBytes: number;
+    activeChildProcesses: Map<number, SpawnedProcess>;
+    /** Push child process events into the V8 isolate. */
+    sendStreamEvent: (eventType: string, payload: Uint8Array) => void;
+    /** Kernel process table — when provided, child processes are registered for cross-runtime visibility. */
+    processTable?: import("@secure-exec/core").ProcessTable;
+    /** Parent process PID for kernel process table registration. */
+    parentPid?: number;
+}
+/** Build child process bridge handlers. */
+export declare function buildChildProcessBridgeHandlers(deps: ChildProcessBridgeDeps): BridgeHandlers;
+/** Dependencies for network bridge handlers. */
+export interface NetworkBridgeDeps {
+    networkAdapter: NetworkAdapter;
+    budgetState: BudgetState;
+    maxBridgeCalls?: number;
+    isolateJsonPayloadLimitBytes: number;
+    activeHttpServerIds: Set<number>;
+    activeHttpServerClosers: Map<number, () => Promise<void>>;
+    pendingHttpServerStarts: {
+        count: number;
+    };
+    /** Push HTTP server/upgrade events into the V8 isolate. */
+    sendStreamEvent: (eventType: string, payload: Uint8Array) => void;
+    /** Kernel socket table for all bridge-managed HTTP server routing. */
+    socketTable?: import("@secure-exec/core").SocketTable;
+    /** Process ID for kernel socket ownership. */
+    pid?: number;
+}
+/** Result of building network bridge handlers — includes dispose for cleanup. */
+export interface NetworkBridgeResult {
+    handlers: BridgeHandlers;
+    dispose: () => Promise<void>;
+}
+/** Build network bridge handlers (fetch, httpRequest, dnsLookup, httpServer). */
+export declare function buildNetworkBridgeHandlers(deps: NetworkBridgeDeps): NetworkBridgeResult;
+/** Resolve a pending HTTP server response (called from stream callback handler). */
+export declare function resolveHttpServerResponse(options: {
+    requestId?: number;
+    serverId?: number;
+    responseJson: string;
+}): void;
+export declare function resolveHttp2CompatResponse(options: {
+    requestId?: number;
+    serverId?: number;
+    responseJson: string;
+}): void;
+/** Dependencies for PTY bridge handlers. */
+export interface PtyBridgeDeps {
+    onPtySetRawMode?: (mode: boolean) => void;
+    stdinIsTTY?: boolean;
+}
+/** Build PTY bridge handlers. */
+export declare function buildPtyBridgeHandlers(deps: PtyBridgeDeps): BridgeHandlers;
+/** Dependencies for kernel FD table bridge handlers. */
+export interface KernelFdBridgeDeps {
+    filesystem: VirtualFileSystem;
+    budgetState: BudgetState;
+    maxBridgeCalls?: number;
+}
+/** Result of building kernel FD bridge handlers — includes dispose for cleanup. */
+export interface KernelFdBridgeResult {
+    handlers: BridgeHandlers;
+    dispose: () => void;
+}
+/**
+ * Build kernel FD table bridge handlers.
+ *
+ * Creates a ProcessFDTable per execution and routes all FD operations
+ * (open, close, read, write, fstat, ftruncate, fsync) through it.
+ * The FD table tracks file descriptors, cursor positions, and flags.
+ * Actual file I/O is delegated to the VirtualFileSystem.
+ */
+export declare function buildKernelFdBridgeHandlers(deps: KernelFdBridgeDeps): KernelFdBridgeResult;
+export declare function createProcessConfigForExecution(processConfig: ProcessConfig, timingMitigation: string, frozenTimeMs: number): ProcessConfig;