feat: US-108 - Cap active handle map size

Author: NathanFlurry

packages/secure-exec-core/isolate-runtime/src/common/runtime-globals.d.ts

@@ -95,6 +95,7 @@ declare global {
 	var _childProcessSpawnSync: ChildProcessSpawnSyncBridgeRef;
 	var _log: ProcessLogBridgeRef;
 	var _error: ProcessErrorBridgeRef;
+	var _maxHandles: number | undefined;
 	var _registerHandle: RegisterHandleBridgeFn;
 	var _unregisterHandle: UnregisterHandleBridgeFn;
 	var require: ((request: string) => unknown) | undefined;

packages/secure-exec-core/src/bridge/active-handles.ts

@@ -11,6 +11,9 @@ import { exposeCustomGlobal } from "../shared/global-exposure.js";
  * See: docs-internal/node/ACTIVE_HANDLES.md
  */
 
+// _maxHandles is injected by the host when resourceBudgets.maxHandles is set.
+declare const _maxHandles: number | undefined;
+
 // Map of active handles: id -> description (for debugging)
 const _activeHandles = new Map<string, string>();
 
@@ -19,10 +22,15 @@ let _waitResolvers: Array<() => void> = [];
 
 /**
  * Register an active handle that keeps the sandbox alive.
+ * Throws if the handle cap (_maxHandles) would be exceeded.
  * @param id Unique identifier for the handle
  * @param description Human-readable description for debugging
  */
 export function _registerHandle(id: string, description: string): void {
+	// Enforce handle cap (skip check for re-registration of existing handle)
+	if (typeof _maxHandles !== "undefined" && !_activeHandles.has(id) && _activeHandles.size >= _maxHandles) {
+		throw new Error("ERR_RESOURCE_BUDGET_EXCEEDED: maximum active handles exceeded");
+	}
 	_activeHandles.set(id, description);
 }
 

packages/secure-exec-core/src/runtime-driver.ts

@@ -30,6 +30,8 @@ export interface ResourceBudgets {
 	maxTimers?: number;
 	/** Maximum child_process.spawn() invocations per execution. */
 	maxChildProcesses?: number;
+	/** Maximum concurrent active handles (child processes, timers, servers) in the bridge handle map. */
+	maxHandles?: number;
 }
 
 export interface RuntimeDriverOptions {

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

@@ -79,6 +79,7 @@ type BridgeDeps = Pick<
 	| "maxOutputBytes"
 	| "maxTimers"
 	| "maxChildProcesses"
+	| "maxHandles"
 	| "bridgeBase64TransferLimitBytes"
 	| "isolateJsonPayloadLimitBytes"
 	| "activeHttpServerIds"
@@ -240,6 +241,11 @@ export async function setupRequire(
 		await jail.set("_maxTimers", deps.maxTimers, { copy: true });
 	}
 
+	// Inject maxHandles limit for bridge-side active handle cap
+	if (deps.maxHandles !== undefined) {
+		await jail.set("_maxHandles", deps.maxHandles, { copy: true });
+	}
+
 	// Set up host crypto references for secure randomness.
 	// Cap matches Web Crypto API spec (65536 bytes) to prevent host OOM.
 	const cryptoRandomFillRef = new ivm.Reference((byteLength: number) => {

packages/secure-exec-node/src/execution-driver.ts

@@ -5,7 +5,7 @@ import { createCommandExecutorStub, createFsStub, createNetworkStub, filterEnv,
 import { executeWithRuntime } from "./execution.js";
 import type { NetworkAdapter, RuntimeDriver } from "@secure-exec/core";
 import type { StdioHook, ExecOptions, ExecResult, RunResult, TimingMitigation } from "@secure-exec/core/internal/shared/api-types";
-import { type DriverDeps, type NodeExecutionDriverOptions, createBudgetState, clearActiveHostTimers, killActiveChildProcesses, normalizePayloadLimit, getExecutionTimeoutMs, getTimingMitigation, DEFAULT_BRIDGE_BASE64_TRANSFER_BYTES, DEFAULT_ISOLATE_JSON_PAYLOAD_BYTES, DEFAULT_MAX_TIMERS, DEFAULT_SANDBOX_CWD, DEFAULT_SANDBOX_HOME, DEFAULT_SANDBOX_TMPDIR } from "./isolate-bootstrap.js";
+import { type DriverDeps, type NodeExecutionDriverOptions, createBudgetState, clearActiveHostTimers, killActiveChildProcesses, normalizePayloadLimit, getExecutionTimeoutMs, getTimingMitigation, DEFAULT_BRIDGE_BASE64_TRANSFER_BYTES, DEFAULT_ISOLATE_JSON_PAYLOAD_BYTES, DEFAULT_MAX_TIMERS, DEFAULT_MAX_HANDLES, DEFAULT_SANDBOX_CWD, DEFAULT_SANDBOX_HOME, DEFAULT_SANDBOX_TMPDIR } from "./isolate-bootstrap.js";
 import { shouldRunAsESM } from "./module-resolver.js";
 import { precompileDynamicImports, runESM, setupDynamicImport } from "./esm-compiler.js";
 import { setupConsole, setupRequire, setupESMGlobals } from "./bridge-setup.js";
@@ -78,6 +78,7 @@ export class NodeExecutionDriver implements RuntimeDriver {
 			maxBridgeCalls: budgets?.maxBridgeCalls,
 			maxTimers: budgets?.maxTimers ?? DEFAULT_MAX_TIMERS,
 			maxChildProcesses: budgets?.maxChildProcesses,
+			maxHandles: budgets?.maxHandles ?? DEFAULT_MAX_HANDLES,
 			budgetState: createBudgetState(),
 			activeHttpServerIds: new Set(),
 			activeChildProcesses: new Map(),

packages/secure-exec-node/src/isolate-bootstrap.ts

@@ -45,6 +45,7 @@ export interface DriverDeps {
 	maxBridgeCalls?: number;
 	maxTimers?: number;
 	maxChildProcesses?: number;
+	maxHandles?: number;
 	budgetState: BudgetState;
 	activeHttpServerIds: Set<number>;
 	activeChildProcesses: Map<number, SpawnedProcess>;
@@ -66,6 +67,7 @@ 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";

packages/secure-exec/tests/runtime-driver/node/resource-budgets.test.ts

@@ -558,6 +558,88 @@ describe("NodeRuntime resource budgets", () => {
 		});
 	});
 
+	// -----------------------------------------------------------------------
+	// maxHandles
+	// -----------------------------------------------------------------------
+
+	describe("maxHandles", () => {
+		it("register maxHandles+1 handles — last one throws", async () => {
+			const capture = createConsoleCapture();
+			proc = createTestNodeRuntime({
+				onStdio: capture.onStdio,
+				resourceBudgets: { maxHandles: 3 },
+			});
+
+			const result = await proc.exec(`
+				let succeeded = 0;
+				let errors = 0;
+				for (let i = 0; i < 5; i++) {
+					try {
+						_registerHandle('test:' + i, 'test handle ' + i);
+						succeeded++;
+					} catch (e) {
+						if (e.message.includes('ERR_RESOURCE_BUDGET_EXCEEDED')) errors++;
+					}
+				}
+				// Cleanup registered handles so sandbox can exit
+				for (let i = 0; i < 3; i++) _unregisterHandle('test:' + i);
+				console.log('succeeded:' + succeeded);
+				console.log('errors:' + errors);
+			`);
+
+			expect(result.code).toBe(0);
+			const out = capture.stdout();
+			expect(out).toContain("succeeded:3");
+			expect(out).toContain("errors:2");
+		});
+
+		it("register handles, remove some, register more — works up to cap", async () => {
+			const capture = createConsoleCapture();
+			proc = createTestNodeRuntime({
+				onStdio: capture.onStdio,
+				resourceBudgets: { maxHandles: 3 },
+			});
+
+			const result = await proc.exec(`
+				let firstBatch = 0;
+				let secondBatch = 0;
+				let errors = 0;
+
+				// First batch: register 3 handles (fills cap)
+				for (let i = 0; i < 3; i++) {
+					try {
+						_registerHandle('batch1:' + i, 'first batch ' + i);
+						firstBatch++;
+					} catch (e) { errors++; }
+				}
+
+				// Remove first batch handles (frees slots)
+				for (let i = 0; i < 3; i++) _unregisterHandle('batch1:' + i);
+
+				// Second batch: register 3 more (slots freed)
+				for (let i = 0; i < 3; i++) {
+					try {
+						_registerHandle('batch2:' + i, 'second batch ' + i);
+						secondBatch++;
+					} catch (e) { errors++; }
+				}
+
+				// Cleanup
+				for (let i = 0; i < 3; i++) _unregisterHandle('batch2:' + i);
+
+				console.log('firstBatch:' + firstBatch);
+				console.log('secondBatch:' + secondBatch);
+				console.log('errors:' + errors);
+			`);
+
+			expect(result.code).toBe(0);
+			const out = capture.stdout();
+			expect(out).toContain("firstBatch:3");
+			expect(out).toContain("secondBatch:3");
+			expect(out).toContain("errors:0");
+		});
+	});
+
 	describe("host timer cleanup", () => {
 		it("clears host timers on dispose after normal execution", async () => {
 			proc = createTestNodeRuntime({});