feat: US-019 - Custom bindings core plumbing

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: NathanFlurry

packages/secure-exec-nodejs/src/bindings.ts

@@ -0,0 +1,106 @@
+/**
+ * Custom bindings: host-to-sandbox function bridge.
+ *
+ * Users register a BindingTree of host-side functions via the `bindings`
+ * option. The tree is validated, flattened to __bind.* prefixed keys, and
+ * merged into bridgeHandlers so sandbox code can call them through the bridge.
+ */
+
+import type { BridgeHandler } from "./bridge-handlers.js";
+import { BRIDGE_GLOBAL_KEY_LIST } from "./bridge-contract.js";
+
+/** A user-defined host-side function callable from the sandbox. */
+export type BindingFunction = (...args: unknown[]) => unknown | Promise<unknown>;
+
+/** A nested tree of binding functions. Nesting depth limited to 4. */
+export interface BindingTree {
+	[key: string]: BindingFunction | BindingTree;
+}
+
+/** Prefix for flattened binding keys in the bridge handler map. */
+export const BINDING_PREFIX = "__bind.";
+
+const MAX_DEPTH = 4;
+const MAX_LEAVES = 64;
+const JS_IDENTIFIER_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
+
+export interface FlattenedBinding {
+	key: string;
+	handler: BridgeHandler;
+	isAsync: boolean;
+}
+
+/**
+ * Validate and flatten a BindingTree into prefixed bridge handler entries.
+ *
+ * Throws on:
+ * - Invalid JS identifiers as keys
+ * - Nesting depth > 4
+ * - More than 64 leaf functions
+ * - Binding keys starting with `_` (reserved for internal bridge names)
+ */
+export function flattenBindingTree(tree: BindingTree): FlattenedBinding[] {
+	const result: FlattenedBinding[] = [];
+	const internalKeys = new Set<string>(BRIDGE_GLOBAL_KEY_LIST as readonly string[]);
+
+	function walk(node: BindingTree, path: string[], depth: number): void {
+		if (depth > MAX_DEPTH) {
+			throw new Error(
+				`Binding tree exceeds maximum nesting depth of ${MAX_DEPTH} at path: ${path.join(".")}`,
+			);
+		}
+
+		for (const key of Object.keys(node)) {
+			if (!JS_IDENTIFIER_RE.test(key)) {
+				throw new Error(
+					`Invalid binding key "${key}": must be a valid JavaScript identifier`,
+				);
+			}
+
+			// Reject keys starting with _ to avoid collision with internal bridge names
+			if (key.startsWith("_")) {
+				throw new Error(
+					`Binding key "${key}" starts with "_" which is reserved for internal bridge names`,
+				);
+			}
+
+			const fullPath = [...path, key];
+			const value = node[key];
+
+			if (typeof value === "function") {
+				const flatKey = BINDING_PREFIX + fullPath.join(".");
+
+				// Double-check flattened key doesn't collide with known internals
+				if (internalKeys.has(flatKey)) {
+					throw new Error(
+						`Binding "${fullPath.join(".")}" collides with internal bridge name "${flatKey}"`,
+					);
+				}
+
+				result.push({
+					key: flatKey,
+					handler: value as BridgeHandler,
+					isAsync: value instanceof AsyncFunction,
+				});
+
+				if (result.length > MAX_LEAVES) {
+					throw new Error(
+						`Binding tree exceeds maximum of ${MAX_LEAVES} leaf functions`,
+					);
+				}
+			} else if (typeof value === "object" && value !== null) {
+				walk(value as BindingTree, fullPath, depth + 1);
+			} else {
+				throw new Error(
+					`Invalid binding value at "${fullPath.join(".")}": expected function or object, got ${typeof value}`,
+				);
+			}
+		}
+	}
+
+	walk(tree, [], 1);
+	return result;
+}

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

@@ -73,6 +73,7 @@ import type {
 	ProcessConfig,
 } from "@secure-exec/core/internal/shared/api-types";
 import type { BudgetState } from "./isolate-bootstrap.js";
+import { type FlattenedBinding, flattenBindingTree } from "./bindings.js";
 
 export { NodeExecutionDriverOptions };
 
@@ -293,6 +294,7 @@ export class NodeExecutionDriver implements RuntimeDriver {
 	private state: DriverState;
 	private memoryLimit: number;
 	private disposed: boolean = false;
+	private flattenedBindings: FlattenedBinding[] | null = null;
 
 	constructor(options: NodeExecutionDriverOptions) {
 		this.memoryLimit = options.memoryLimit ?? 128;
@@ -352,6 +354,11 @@ export class NodeExecutionDriver implements RuntimeDriver {
 			activeHostTimers: new Set(),
 			resolutionCache: createResolutionCache(),
 		};
+
+		// Validate and flatten bindings once at construction time
+		if (options.bindings) {
+			this.flattenedBindings = flattenBindingTree(options.bindings);
+		}
 	}
 
 	get network(): Pick<NetworkAdapter, "fetch" | "dnsLookup" | "httpRequest"> {
@@ -527,6 +534,13 @@ export class NodeExecutionDriver implements RuntimeDriver {
 				}),
 			};
 
+			// Merge custom bindings into bridge handlers
+			if (this.flattenedBindings) {
+				for (const binding of this.flattenedBindings) {
+					bridgeHandlers[binding.key] = binding.handler;
+				}
+			}
+
 			// Build process/os config for V8 execution
 			const execProcessConfig = createProcessConfigForExecution(
 				options.env || options.cwd

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

@@ -38,6 +38,10 @@ export {
 	createProcessConfigForExecution,
 } from "./bridge-handlers.js";
 
+// Custom bindings
+export type { BindingTree, BindingFunction } from "./bindings.js";
+export { BINDING_PREFIX, flattenBindingTree } from "./bindings.js";
+
 // Kernel runtime driver (RuntimeDriver for kernel.mount())
 export { createNodeRuntime } from "./kernel-runtime.js";
 export type { NodeRuntimeOptions } from "./kernel-runtime.js";

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

@@ -16,9 +16,11 @@ import type {
 	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;
 }
 
 export interface BudgetState {

packages/secure-exec-nodejs/src/kernel-runtime.ts

@@ -21,6 +21,7 @@ import type {
 } from '@secure-exec/core';
 import { NodeExecutionDriver } from './execution-driver.js';
 import { createNodeDriver } from './driver.js';
+import type { BindingTree } from './bindings.js';
 import {
   allowAllChildProcess,
   allowAllFs,
@@ -43,6 +44,11 @@ export interface NodeRuntimeOptions {
    * (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;
 }
 
 /**
@@ -318,11 +324,13 @@ class NodeRuntimeDriver implements RuntimeDriver {
   private _kernel: KernelInterface | null = null;
   private _memoryLimit: number;
   private _permissions: Partial<Permissions>;
+  private _bindings?: BindingTree;
   private _activeDrivers = new Map<number, NodeExecutionDriver>();
 
   constructor(options?: NodeRuntimeOptions) {
     this._memoryLimit = options?.memoryLimit ?? 128;
     this._permissions = options?.permissions ?? { ...allowAllChildProcess };
+    this._bindings = options?.bindings;
   }
 
   async init(kernel: KernelInterface): Promise<void> {
@@ -453,6 +461,7 @@ class NodeRuntimeDriver implements RuntimeDriver {
         system: systemDriver,
         runtime: systemDriver.runtime,
         memoryLimit: this._memoryLimit,
+        bindings: this._bindings,
       });
       this._activeDrivers.set(ctx.pid, executionDriver);
 

packages/secure-exec/src/index.ts

@@ -43,6 +43,7 @@ export type { Kernel, KernelInterface } from "@secure-exec/core";
 
 // Re-export kernel Node runtime factory.
 export { createNodeRuntime } from "@secure-exec/nodejs";
+export type { BindingTree, BindingFunction } from "@secure-exec/nodejs";
 
 export { createInMemoryFileSystem } from "./shared/in-memory-fs.js";
 export {

scripts/ralph/prd.json

@@ -301,7 +301,7 @@
         "Typecheck passes"
       ],
       "priority": 19,
-      "passes": false,
+      "passes": true,
       "notes": "Custom bindings Phase 1. ~40-50 LOC. No Rust changes needed — bridgeHandlers already accepts dynamic entries."
     },
     {