docs(secure-exec): refine runtime doc comments

Author: NathanFlurry

packages/secure-exec/src/bridge-loader.ts

@@ -9,6 +9,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Cache the bridge code
 let bridgeCodeCache: string | null = null;
 
+/** Locate the bridge TypeScript source for on-demand compilation (dev only). */
 function findBridgeSourcePath(): string | null {
 	const candidates = [
 		path.join(__dirname, "bridge", "index.ts"),
@@ -20,6 +21,7 @@ function findBridgeSourcePath(): string | null {
 	return null;
 }
 
+/** Walk a directory tree and return the newest file modification time. */
 function getLatestMtimeMs(dir: string): number {
 	let latest = 0;
 	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -33,6 +35,10 @@ function getLatestMtimeMs(dir: string): number {
 	return latest;
 }
 
+/**
+ * Auto-compile the bridge IIFE bundle from TypeScript source if stale.
+ * Skips rebuilding when the existing bundle is newer than all source files.
+ */
 function ensureBridgeBundle(bridgePath: string): void {
 	const sourcePath = findBridgeSourcePath();
 

packages/secure-exec/src/bridge-setup.ts

@@ -1,5 +1,10 @@
 import { getIsolateRuntimeSource } from "./generated/isolate-runtime.js";
 
+/**
+ * Get the isolate-side script that initializes early mutable runtime globals
+ * (`_moduleCache`, `_pendingModules`, `_currentModule`) before module loading
+ * and require wiring run.
+ */
 export function getInitialBridgeGlobalsSetupCode(): string {
 	return getIsolateRuntimeSource("bridgeInitialGlobals");
 }

packages/secure-exec/src/bridge/child-process.ts

@@ -47,7 +47,11 @@ declare const _unregisterHandle: UnregisterHandleBridgeFn;
 // Active children registry - maps session ID to ChildProcess
 const activeChildren = new Map<number, ChildProcess>();
 
-// Global dispatcher - host calls this when data arrives
+/**
+ * Global dispatcher invoked by the host when child process data arrives.
+ * Routes stdout/stderr chunks and exit codes to the corresponding ChildProcess
+ * instance by session ID, and unregisters the active handle on exit.
+ */
 const childProcessDispatch = (
   sessionId: number,
   type: "stdout" | "stderr" | "exit",
@@ -106,7 +110,11 @@ interface OutputStreamStub {
   pipe<T extends NodeJS.WritableStream>(dest: T): T;
 }
 
-// ChildProcess class - simplified interface, not strictly satisfying nodeChildProcess.ChildProcess
+/**
+ * Polyfill of Node.js `ChildProcess`. Provides event-emitting stdin/stdout/stderr
+ * streams. In streaming mode, data arrives via the `_childProcessDispatch` global
+ * that the host calls with stdout/stderr/exit events keyed by session ID.
+ */
 class ChildProcess {
   private _listeners: Record<string, EventListener[]> = {};
   private _onceListeners: Record<string, EventListener[]> = {};

packages/secure-exec/src/bridge/module.ts

@@ -160,7 +160,9 @@ export function createRequire(filename: string | URL): RequireFunction {
 }
 
 /**
- * Module class constructor (for compatibility with promzard and similar)
+ * Polyfill of Node.js `Module` class for sandbox compatibility. Provides
+ * `_compile`, `_resolveFilename`, `_load`, `_extensions`, and `_cache` statics
+ * that npm tooling (promzard, resolve, etc.) relies on.
  */
 export class Module {
   id: string;

packages/secure-exec/src/bridge/network.ts

@@ -332,7 +332,12 @@ export const dns = {
 // Event listener type
 type EventListener = (...args: unknown[]) => void;
 
-// IncomingMessage class
+/**
+ * Polyfill of Node.js `http.IncomingMessage` (client-side response). Buffers
+ * the response body eagerly and emits `data`/`end` events on listener
+ * registration (flowing mode). Supports base64 binary decoding via
+ * `x-body-encoding` header.
+ */
 export class IncomingMessage {
   headers: Record<string, string>;
   rawHeaders: string[];
@@ -632,7 +637,11 @@ export class IncomingMessage {
   }
 }
 
-// ClientRequest class
+/**
+ * Polyfill of Node.js `http.ClientRequest`. Executes the request asynchronously
+ * via the `_networkHttpRequestRaw` bridge and emits a `response` event with
+ * an IncomingMessage.
+ */
 export class ClientRequest {
   private _options: nodeHttp.RequestOptions;
   private _callback?: (res: IncomingMessage) => void;
@@ -900,6 +909,10 @@ class ServerIncomingMessage {
   }
 }
 
+/**
+ * Sandbox-side response writer for HTTP server requests. Collects headers and
+ * body chunks, then serializes to JSON for transfer back to the host.
+ */
 class ServerResponseBridge {
   statusCode = 200;
   statusMessage = "OK";
@@ -1043,6 +1056,12 @@ class ServerResponseBridge {
   }
 }
 
+/**
+ * Polyfill of Node.js `http.Server`. Delegates actual listening to the host
+ * via the `_networkHttpServerListenRaw` bridge. Incoming requests are
+ * dispatched through `_httpServerDispatch` which invokes the request listener
+ * inside the isolate. Registers an active handle to keep the sandbox alive.
+ */
 class Server {
   listening = false;
   private _listeners: Record<string, EventListener[]> = {};
@@ -1193,6 +1212,7 @@ class Server {
   }
 }
 
+/** Route an incoming HTTP request to the server's request listener and return the serialized response. */
 async function dispatchServerRequest(
   serverId: number,
   requestJson: string

packages/secure-exec/src/bridge/process.ts

@@ -25,7 +25,10 @@ import {
 } from "../shared/global-exposure.js";
 
 
-// Configuration interface - values are set via globals before bridge loads
+/**
+ * Process configuration injected by the host before the bridge bundle loads.
+ * Values default to sensible Linux/x64 stubs when unset.
+ */
 export interface ProcessConfig {
   platform?: string;
   arch?: string;
@@ -87,6 +90,7 @@ const config = {
     typeof _processConfig !== "undefined" ? _processConfig.frozenTimeMs : undefined,
 };
 
+/** Get the current timestamp, returning a frozen value when timing mitigation is active. */
 function getNowMs(): number {
   if (
     config.timingMitigation === "freeze" &&
@@ -142,7 +146,10 @@ if (
 let _exitCode = 0;
 let _exited = false;
 
-// ProcessExitError class for controlled exits
+/**
+ * Thrown by `process.exit()` to unwind the sandbox call stack. The host
+ * catches this to extract the exit code without killing the isolate.
+ */
 export class ProcessExitError extends Error {
   code: number;
   constructor(code: number) {
@@ -848,7 +855,11 @@ const _queueMicrotask =
         Promise.resolve().then(fn);
       };
 
-// Timer handle class that mimics Node.js Timeout object
+/**
+ * Timer handle that mimics Node.js Timeout (ref/unref/Symbol.toPrimitive).
+ * Timers with delay > 0 use the host's `_scheduleTimer` bridge to sleep
+ * without blocking the isolate's event loop.
+ */
 class TimerHandle {
   _id: number;
   _destroyed: boolean;
@@ -1011,7 +1022,11 @@ function throwUnsupportedCryptoApi(api: "getRandomValues" | "randomUUID"): never
   throw new Error(`crypto.${api} is not supported in sandbox`);
 }
 
-// Crypto polyfill
+/**
+ * Crypto polyfill that delegates to the host for entropy. `getRandomValues`
+ * calls the host's `_cryptoRandomFill` bridge to get cryptographically secure
+ * random bytes. Subtle crypto operations are unsupported.
+ */
 export const cryptoPolyfill = {
   getRandomValues<T extends ArrayBufferView>(array: T): T {
     if (typeof _cryptoRandomFill === "undefined") {
@@ -1063,7 +1078,10 @@ export const cryptoPolyfill = {
   },
 };
 
-// Setup globals function - call this to install polyfills on globalThis
+/**
+ * Install all process/timer/URL/Buffer/crypto polyfills onto `globalThis`.
+ * Called once during bridge initialization before user code runs.
+ */
 export function setupGlobals(): void {
   const g = globalThis as Record<string, unknown>;
 

packages/secure-exec/src/browser/driver.ts

@@ -47,6 +47,11 @@ async function getRootHandle(): Promise<FileSystemDirectoryHandle> {
 	return navigator.storage.getDirectory();
 }
 
+/**
+ * VFS backed by the Origin Private File System (OPFS) API. Falls back to
+ * InMemoryFileSystem when OPFS is unavailable. Rename is not supported
+ * (throws ENOSYS) since OPFS doesn't provide atomic rename.
+ */
 export class OpfsFileSystem implements VirtualFileSystem {
 	private rootPromise: Promise<FileSystemDirectoryHandle>;
 
@@ -229,13 +234,15 @@ export interface BrowserDriverOptions {
 	useDefaultNetwork?: boolean;
 }
 
+/** Create an OPFS-backed filesystem, falling back to in-memory if OPFS is unavailable. */
 export async function createOpfsFileSystem(): Promise<VirtualFileSystem> {
 	if (!("storage" in navigator) || typeof navigator.storage.getDirectory !== "function") {
 		return createInMemoryFileSystem();
 	}
 	return new OpfsFileSystem();
 }
 
+/** Network adapter that delegates to the browser's native `fetch`. DNS and http2 are unsupported. */
 export function createBrowserNetworkAdapter(): NetworkAdapter {
 	return {
 		async fetch(url, options) {
@@ -301,6 +308,7 @@ export function createBrowserNetworkAdapter(): NetworkAdapter {
 	};
 }
 
+/** Assemble a browser-side SandboxDriver with permission-wrapped adapters. */
 export async function createBrowserDriver(
 	options: BrowserDriverOptions = {},
 ): Promise<SandboxDriver> {

packages/secure-exec/src/browser/index.ts

@@ -50,6 +50,12 @@ function serializePermissions(permissions?: Permissions): SerializedPermissions
 	};
 }
 
+/**
+ * Browser-side sandbox that runs code in a Web Worker. Communicates with the
+ * worker via `postMessage` using a request/response protocol keyed by
+ * monotonic IDs. The worker initializes its own runtime (permissions, fs,
+ * network, bridge modules) before accepting exec/run requests.
+ */
 export class BrowserSandbox {
 	private worker: Worker;
 	private nextId = 1;

packages/secure-exec/src/browser/worker.ts

@@ -92,6 +92,7 @@ function revivePermission(source?: string): ((req: unknown) => { allow: boolean
 	}
 }
 
+/** Deserialize permission callbacks that were stringified for transfer across the Worker boundary. */
 function revivePermissions(serialized?: SerializedPermissions): Permissions | undefined {
 	if (!serialized) return undefined;
 	const perms: Permissions = {};
@@ -102,6 +103,10 @@ function revivePermissions(serialized?: SerializedPermissions): Permissions | un
 	return perms;
 }
 
+/**
+ * Wrap a sync function in the bridge calling convention (`applySync`) so
+ * bridge code can call it the same way it calls isolated-vm References.
+ */
 function makeApplySync<TArgs extends unknown[], TResult>(
 	fn: (...args: TArgs) => TResult,
 ) {
@@ -132,6 +137,10 @@ function makeApplyPromise<TArgs extends unknown[], TResult>(
 	};
 }
 
+/**
+ * Initialize the worker-side runtime: set up filesystem, network, bridge
+ * globals, and load the bridge bundle. Called once before any exec/run.
+ */
 async function initRuntime(payload: InitPayload): Promise<void> {
 	if (initialized) return;
 
@@ -409,6 +418,10 @@ function updateProcessConfig(options?: ExecOptions): void {
 	}
 }
 
+/**
+ * Execute user code as a script (process-style). Transforms ESM/dynamic
+ * imports, sets up module/exports globals, and waits for active handles.
+ */
 async function execScript(
 	code: string,
 	options?: ExecOptions,

packages/secure-exec/src/esm-compiler.ts

@@ -1,9 +1,19 @@
+/**
+ * ESM wrapper generator for built-in modules inside the isolate.
+ *
+ * isolated-vm's ESM `import` can only resolve modules we explicitly provide.
+ * For Node built-ins (fs, path, etc.) we generate thin ESM wrappers that
+ * re-export the bridge-provided globalThis objects as proper ESM modules
+ * with both default and named exports.
+ */
+
 import { BUILTIN_NAMED_EXPORTS } from "./module-resolver.js";
 
 function isValidIdentifier(value: string): boolean {
 	return /^[$A-Z_][0-9A-Z_$]*$/i.test(value);
 }
 
+/** Generate `export const X = _builtin.X;` lines for each known named export. */
 function buildNamedExportLines(namedExports: string[]): string[] {
 	return Array.from(new Set(namedExports))
 		.filter(isValidIdentifier)
@@ -17,6 +27,10 @@ function buildNamedExportLines(namedExports: string[]): string[] {
 		);
 }
 
+/**
+ * Build a complete ESM wrapper that reads a bridge global via `bindingExpression`
+ * and re-exports it as `default` plus individual named exports.
+ */
 function buildWrapperSource(bindingExpression: string, namedExports: string[]): string {
 	const lines = [
 		"const _builtin = " + bindingExpression + ";",
@@ -72,17 +86,20 @@ const STATIC_BUILTIN_WRAPPER_SOURCES: Readonly<Record<string, string>> = {
 	v8: buildWrapperSource("globalThis._moduleCache?.v8 || {}", []),
 };
 
+/** Get a pre-built ESM wrapper for a bridge-backed built-in, or null if not bridge-handled. */
 export function getStaticBuiltinWrapperSource(moduleName: string): string | null {
 	return STATIC_BUILTIN_WRAPPER_SOURCES[moduleName] ?? null;
 }
 
+/** Build a custom ESM wrapper for a dynamically-resolved module (e.g. polyfills). */
 export function createBuiltinESMWrapper(
 	bindingExpression: string,
 	namedExports: string[],
 ): string {
 	return buildWrapperSource(bindingExpression, namedExports);
 }
 
+/** Wrapper for unsupported built-ins: exports an empty object as default. */
 export function getEmptyBuiltinESMWrapper(): string {
 	return buildWrapperSource("{}", []);
 }