feat: US-020 - Sandbox-side SecureExec.bindings injection

Author: NathanFlurry

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

@@ -73,7 +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";
+import { type FlattenedBinding, flattenBindingTree, BINDING_PREFIX } from "./bindings.js";
 
 export { NodeExecutionDriverOptions };
 
@@ -558,6 +558,9 @@ export class NodeExecutionDriver implements RuntimeDriver {
 			const bridgeCode = buildFullBridgeCode();
 
 			// Build post-restore script with per-execution config
+			const bindingKeys = this.flattenedBindings
+				? this.flattenedBindings.map((b) => b.key.slice(BINDING_PREFIX.length))
+				: [];
 			const postRestoreScript = buildPostRestoreScript(
 				execProcessConfig,
 				s.osConfig,
@@ -573,6 +576,7 @@ export class NodeExecutionDriver implements RuntimeDriver {
 				frozenTimeMs,
 				options.mode,
 				options.filePath,
+				bindingKeys,
 			);
 
 			// Execute in V8 session
@@ -726,6 +730,7 @@ function buildPostRestoreScript(
 	frozenTimeMs: number,
 	mode: "run" | "exec",
 	filePath?: string,
+	bindingKeys?: string[],
 ): string {
 	const parts: string[] = [];
 
@@ -803,6 +808,9 @@ function buildPostRestoreScript(
 	})};`);
 	parts.push(getIsolateRuntimeSource("applyCustomGlobalPolicy"));
 
+	// Inflate SecureExec.bindings from flattened __bind.* globals
+	parts.push(buildBindingsInflationSnippet(bindingKeys ?? []));
+
 	return parts.join("\n");
 }
 
@@ -819,3 +827,24 @@ function getHardenedGlobals(): string[] { return HARDENED_NODE_CUSTOM_GLOBALS; }
 function getMutableGlobals(): string[] { return MUTABLE_NODE_CUSTOM_GLOBALS; }
 function getProcessConfigGlobalKey(): string { return HOST_BRIDGE_GLOBAL_KEYS.processConfig; }
 function getOsConfigGlobalKey(): string { return HOST_BRIDGE_GLOBAL_KEYS.osConfig; }
+
+/** Build the JS snippet that inflates __bind.* globals into a frozen SecureExec.bindings tree. */
+function buildBindingsInflationSnippet(bindingKeys: string[]): string {
+	return `(function(){
+var __bindingKeys__=${JSON.stringify(bindingKeys)};
+var tree={};
+for(var i=0;i<__bindingKeys__.length;i++){
+var parts=__bindingKeys__[i].split(".");
+var node=tree;
+for(var j=0;j<parts.length-1;j++){node[parts[j]]=node[parts[j]]||{};node=node[parts[j]];}
+node[parts[parts.length-1]]=globalThis["__bind."+__bindingKeys__[i]];
+}
+function deepFreeze(obj){
+var vals=Object.values(obj);
+for(var k=0;k<vals.length;k++){if(typeof vals[k]==="object"&&vals[k]!==null)deepFreeze(vals[k]);}
+return Object.freeze(obj);
+}
+Object.defineProperty(globalThis,"SecureExec",{value:Object.freeze({bindings:deepFreeze(tree)}),writable:false,enumerable:true,configurable:false});
+for(var i=0;i<__bindingKeys__.length;i++){delete globalThis["__bind."+__bindingKeys__[i]];}
+})();`;
+}

scripts/ralph/prd.json

@@ -320,7 +320,7 @@
         "Typecheck passes"
       ],
       "priority": 20,
-      "passes": false,
+      "passes": true,
       "notes": "Custom bindings Phase 2. ~15-20 LOC for the inflation snippet. Depends on US-019."
     },
     {

scripts/ralph/progress.txt

@@ -34,6 +34,8 @@
 - Docs compatibility link slug is nodejs-compatibility (not node-compatability)
 - WasmVM native code (Rust, C, patches) canonical location is native/wasmvm/ (alongside native/v8-runtime/)
 - Test files in packages/secure-exec-wasmvm/test/ use ../../../native/wasmvm/target/ for WASM binary paths (3 levels up from test/ to repo root)
+- Custom bindings types/validation/flattening live in secure-exec-nodejs/src/bindings.ts — flattened __bind.* keys merge into bridgeHandlers Record
+- BridgeHandler = (...args: unknown[]) => unknown | Promise<unknown> — both sync and async handlers work through the same V8 IPC bridge
 
 # Ralph Progress Log
 Started: Sat Mar 21 02:49:43 AM PDT 2026
@@ -525,3 +527,46 @@ Started: Sat Mar 21 02:49:43 AM PDT 2026
   - CI workflow had a stale `cd wasmvm` that was missed in US-016's path update sweep — always verify CI with `grep -r` after path moves
   - packages/secure-exec-node/ (old name) still has a stale dist/ directory — harmless but cruft
 ---
+
+## 2026-03-21 06:25 - US-019
+- Implemented custom bindings core plumbing for host-to-sandbox function bridge
+- Created bindings.ts with BindingTree/BindingFunction types, validation, and flattenBindingTree()
+- Added bindings?: BindingTree to NodeRuntimeOptions (kernel-runtime.ts)
+- Added bindings?: BindingTree to NodeExecutionDriverOptions (isolate-bootstrap.ts)
+- Threaded bindings through NodeRuntimeDriver → NodeExecutionDriver constructor
+- Flattened bindings merged into bridgeHandlers with __bind. prefix in executeInternal()
+- Validation rejects: invalid JS identifiers, keys starting with _, nesting > 4, leaf count > 64
+- Sync/async detection via AsyncFunction instanceof check
+- Exported BindingTree, BindingFunction, BINDING_PREFIX from @secure-exec/nodejs and secure-exec barrel
+- Files changed:
+  - packages/secure-exec-nodejs/src/bindings.ts (new — types, validation, flattening)
+  - packages/secure-exec-nodejs/src/kernel-runtime.ts (bindings option + threading)
+  - packages/secure-exec-nodejs/src/isolate-bootstrap.ts (NodeExecutionDriverOptions.bindings)
+  - packages/secure-exec-nodejs/src/execution-driver.ts (flattenedBindings field, merge into bridgeHandlers)
+  - packages/secure-exec-nodejs/src/index.ts (re-exports)
+  - packages/secure-exec/src/index.ts (barrel re-exports)
+- **Learnings for future iterations:**
+  - bridgeHandlers is a simple Record<string, BridgeHandler> — any key added to this map becomes callable from sandbox via V8 IPC bridge (no Rust changes needed)
+  - Internal bridge names all start with single _ (e.g., _fsReadFile, _log) — custom bindings use __bind. prefix to avoid collision
+  - NodeExecutionDriverOptions extends RuntimeDriverOptions (from core), but bindings are Node-specific so extend at the node level only
+  - AsyncFunction detection: `Object.getPrototypeOf(async function () {}).constructor` — instanceof check works for all async functions
+  - Validation runs once at construction time, flattened result cached — merge into bridgeHandlers is per-execution
+---
+
+## 2026-03-21 06:36 - US-020
+- Implemented sandbox-side SecureExec.bindings injection in execution-driver.ts
+- Added buildBindingsInflationSnippet() function that generates the inflation JS snippet
+- Inflation snippet: builds nested object tree from __bind.* globals, deep-freezes it, sets as globalThis.SecureExec
+- SecureExec is non-writable, non-configurable via Object.defineProperty
+- Raw __bind.* globals deleted from globalThis after inflation
+- SecureExec.bindings is always present (empty frozen object when no bindings registered)
+- Binding keys extracted from flattenedBindings by stripping BINDING_PREFIX, passed as JSON literal to snippet
+- Files changed:
+  - packages/secure-exec-nodejs/src/execution-driver.ts (30 LOC added — buildBindingsInflationSnippet function, binding keys extraction, parameter threading)
+- **Learnings for future iterations:**
+  - buildPostRestoreScript() is the right injection point for per-execution sandbox setup code — it runs after bridge code snapshot phase so bridge calls work
+  - Inflation snippet must use var (not const/let) for broader V8 compatibility in the injected context
+  - BINDING_PREFIX ("__bind.") is the separator — binding keys stored without prefix in the inflation snippet, prefixed when looking up globals
+  - Object.defineProperty with writable:false, configurable:false ensures sandbox code cannot delete or overwrite SecureExec
+  - deepFreeze recursion only freezes objects, not functions — leaf binding functions remain callable but their container objects are frozen
+---