chore: refactor node runitme

Author: NathanFlurry

CLAUDE.md

@@ -13,13 +13,18 @@
 
 - use `docs-internal/glossary.md` for canonical definitions of isolate, runtime, bridge, and driver
 
+## Node Architecture
+
+- read `docs-internal/arch/overview.md` for the component map (NodeProcess, SandboxDriver, NodeDriver, NodeExecutionDriver, ModuleAccessFileSystem, Permissions)
+- keep it up to date when adding, removing, or significantly changing components
+
 ## Specs Source of Truth
 
 - bridge/runtime/governance requirements are canonical in `openspec/specs/`
 - for secure-exec runtime behavior, target Node.js semantics as close to 1:1 as practical
 - any intentional deviation from Node.js behavior must be explicitly documented in OpenSpec deltas and reflected in compatibility/friction docs
 - use `openspec/specs/README.md` for how to reference baseline capabilities in new change proposals
-- track development friction in `docs-internal/friction/secure-exec.md` (mark resolved items with fix notes)
+- track development friction in `docs-internal/friction.md` (mark resolved items with fix notes)
 - OpenSpec proposals/design/tasks MUST explicitly list the concrete tests to add or update for the change
 
 ## Compatibility Project-Matrix Policy

README.md

@@ -1,6 +1,6 @@
 # Secure Exec SDK
 
-Run sandboxed Node.js code in both Node and the browser using a driver-based runtime.
+Run sandboxed Node.js code using a driver-based runtime.
 
 ## Features
 
@@ -10,8 +10,8 @@ Run sandboxed Node.js code in both Node and the browser using a driver-based run
 
 TODO:
 
-- **Node + Browser**: Same sandbox API on Node (isolated-vm) and browser (Worker isolate).
+- **Node runtime**: isolated-vm backed sandbox execution with driver-owned capability wiring.
+- **Browser runtime**: temporarily disabled during the driver-owned runtime refactor.
 - **Driver-based**: Provide a driver to map filesystem, network, and child_process.
 - **Permissions**: Gate syscalls with custom allow/deny functions.
 - **Opt-in system features**: Disable network/child_process/FS by omission.
-

docs-internal/node/ACTIVE_HANDLES.md docs-internal/arch/active-handles.mddocs-internal/node/ACTIVE_HANDLES.md renamed to docs-internal/arch/active-handles.md

@@ -0,0 +1,67 @@
+# Architecture Overview
+
+```
+NodeRuntime  →  RuntimeDriver  →  NodeExecutionDriver
+  (API)          (config)           (isolated-vm engine)
+```
+
+## NodeRuntime
+
+`src/index.ts`
+
+Public API. Thin facade — delegates everything to the execution driver.
+
+- `run(code)` — execute as module, get exports back
+- `exec(code)` — execute as script, get exit code + stdout/stderr
+- `dispose()` / `terminate()`
+
+## RuntimeDriver
+
+`src/runtime-driver.ts` (re-exported from `src/types.ts`)
+
+Config object that bundles what the sandbox can access. Deny-by-default.
+
+- `filesystem` — VFS adapter
+- `network` — fetch, DNS, HTTP
+- `commandExecutor` — child processes
+- `permissions` — per-adapter allow/deny checks
+- `runtimeHooks` — factories for isolate + execution driver
+
+### createNodeDriver()
+
+`src/node/driver.ts`
+
+Factory that builds a `RuntimeDriver` with Node-native adapters.
+
+- Wraps filesystem in `ModuleAccessFileSystem` (read-only `node_modules` overlay)
+- Optionally wires up network and command executor
+
+## NodeExecutionDriver
+
+`src/node/execution-driver.ts`
+
+The engine. Owns the `isolated-vm` isolate and bridges host capabilities in.
+
+- Creates contexts, compiles ESM/CJS, runs code
+- Bridges fs, network, child_process, crypto, timers into the isolate via `ivm.Reference`
+- Caches compiled modules and resolved formats per isolate
+- Enforces payload size limits on bridge transfers
+
+## ModuleAccessFileSystem
+
+`src/node/module-access.ts`
+
+Filesystem overlay that makes host `node_modules` available read-only at `/root/node_modules`.
+
+- Blocks `.node` native addons
+- Prevents symlink escapes (resolves pnpm virtual-store paths)
+- Non-module paths fall through to base VFS
+
+## Permissions
+
+`src/shared/permissions.ts`
+
+Wraps each adapter with allow/deny checks before calls reach the host.
+
+- `wrapFileSystem()`, `wrapNetworkAdapter()`, `wrapCommandExecutor()`
+- Missing adapters get deny-all stubs

docs-internal/arch/overview.md

@@ -2,18 +2,26 @@
 
 ## 2026-03-01
 
-1. **[resolved]** Default console capture buffered unbounded host memory.
+1. **[resolved]** `NodeRuntime` constructor ownership drifted between driver and direct adapter options.
+   - Symptom: runtime capability and config ownership was split across `NodeRuntime` fallbacks and `createNodeDriver`, which made permission defaults and runtime injection behavior harder to reason about.
+   - Fix: `NodeRuntime` now requires a `driver`, reads `processConfig`/`osConfig` from `driver.runtime`, and no longer accepts direct constructor adapters/permissions.
+   - Follow-up: a dedicated pass should continue moving remaining `isolated-vm` execution internals from `NodeRuntime` into the Node driver implementation.
+2. **[resolved]** Browser runtime surface needed temporary de-scope during driver boundary refactor.
+   - Symptom: maintaining Worker/browser runtime paths during Node driver ownership changes increased refactor risk and cross-runtime drift.
+   - Fix: browser package exports were removed for this phase and browser entrypoints now return deterministic unsupported errors until follow-up restoration.
+
+3. **[resolved]** Default console capture buffered unbounded host memory.
    - Symptom: runtime execution accumulated console output in host-managed `stdout`/`stderr` arrays by default, enabling memory amplification under high-volume logs.
    - Fix: runtime now drops console output by default and exposes an explicit streaming hook (`onConsoleLog`) for host-controlled log handling.
    - Compatibility trade-off: `exec()`/`run()` no longer mirror Node stdout/stderr buffering by default; result payloads no longer expose `stdout`/`stderr` fields, so consumers that need logs must opt into hook-based streaming.
    - Migration note: switch any `result.stderr` checks to `result.errorMessage` for runtime error assertions.
-2. **[resolved]** Node module loading depended on allowlist projection setup and split filesystem paths.
+4. **[resolved]** Node module loading depended on allowlist projection setup and split filesystem paths.
    - Symptom: sandbox `node_modules` availability varied by `moduleAccess.allowPackages` setup and base filesystem mount location, which added resolver complexity and setup fragility.
    - Fix: Node driver now always composes a read-only `/app/node_modules` overlay from `<cwd>/node_modules`, even without a base filesystem adapter. Overlay reads are canonical-path scoped to `<cwd>/node_modules`; writes/mutations remain denied; `.node` native addons are rejected.
    - Compatibility trade-off: allowlist-scoped dependency visibility was removed in favor of scoped full-overlay readability under `<cwd>/node_modules`; callers needing stricter package-level exposure must enforce it outside runtime for now.
-3. TODO: document extension attack vectors and hardening guidance.
+5. TODO: document extension attack vectors and hardening guidance.
    - Symptom: extension-oriented threat scenarios are not documented as a consolidated runtime/bridge/driver risk model.
-   - Next step: add extension-focused vectors and mitigations to `docs-internal/todo/attack-vectors.md`, including memory amplification/buffering abuse, CPU amplification, timer/event-rate amplification, and extension host-hook abuse paths.
+   - Next step: add extension-focused vectors and mitigations to `docs-internal/attack-vectors.md`, including memory amplification/buffering abuse, CPU amplification, timer/event-rate amplification, and extension host-hook abuse paths.
 
 ## 2026-02-28
 
@@ -87,7 +95,7 @@
 
 2. **[resolved]** Needed host-driven verification path for sandbox HTTP servers.
    - Symptom: Hono runner self-tested using in-sandbox `fetch`, which did not verify host-to-sandbox request path.
-   - Fix: added host-side `NodeProcess.network.fetch(...)` facade and updated `examples/hono/loader` to issue requests and terminate from loader.
+   - Fix: added host-side `NodeRuntime.network.fetch(...)` facade and updated `examples/hono/loader` to issue requests and terminate from loader.
 
 3. **[resolved]** Bridge bundle could go stale when non-entry bridge files changed.
    - Symptom: runtime still used old `dist/bridge.js` behavior (for example `http.createServer` still throwing) after editing `src/bridge/network.ts`.

docs-internal/todo/attack-vectors.md docs-internal/attack-vectors.mddocs-internal/todo/attack-vectors.md renamed to docs-internal/attack-vectors.md

@@ -25,7 +25,7 @@
   - Add Node driver implementation backed by `node:http` (`packages/secure-exec/src/node/driver.ts`, `packages/secure-exec/src/types.ts`, `packages/secure-exec/src/shared/permissions.ts`).
 
 - [x] Expose host-side request path to sandbox servers via `sandbox.network.fetch(...)`.
-  - Provide a NodeProcess-level network facade and document concurrent run/fetch pattern (`packages/secure-exec/src/index.ts`, `README.md`, `examples/hono/README.md`).
+  - Provide a NodeRuntime-level network facade and document concurrent run/fetch pattern (`packages/secure-exec/src/index.ts`, `README.md`, `examples/hono/README.md`).
   - Validate end-to-end from loader to runner (`examples/hono/loader/src/index.ts`, `examples/hono/runner/src/index.ts`).
 
 - [x] Fix `run()` ESM semantics to match docs (return module exports/default instead of evaluation result).

docs-internal/arch/comarison.mdx docs-internal/comarison.mdxdocs-internal/arch/comarison.mdx renamed to docs-internal/comarison.mdx

@@ -7,7 +7,7 @@ This example uses a loader/runner split:
   - `src/fetch-handler.ts` exports only `fetch`.
   - `src/server.ts` boots a real HTTP server using `@hono/node-server`.
 - `loader/` verifies the running sandbox server by calling `sandbox.network.fetch(...)`
-  (`NodeProcess.network.fetch(...)`) and then terminates the sandbox from the host.
+  (`NodeRuntime.network.fetch(...)`) and then terminates the sandbox from the host.
   - It also executes a probe that imports the exported fetch handler directly.
 - shared loader helpers live in `examples/shared/src/sandbox-runner-utils.ts`.
 

docs-internal/friction/secure-exec.md docs-internal/friction.mddocs-internal/friction/secure-exec.md renamed to docs-internal/friction.md

@@ -6,7 +6,7 @@ import {
   allowAllFs,
   allowAllNetwork,
   NodeFileSystem,
-  NodeProcess,
+  NodeRuntime,
   createNodeDriver,
 } from "../../../../packages/secure-exec/src/index.ts";
 import {
@@ -16,23 +16,23 @@ import {
   waitForServer,
 } from "../../../shared/src/sandbox-runner-utils.ts";
 
-function createProcess(runnerRoot: string, runnerEntry: string): NodeProcess {
+function createProcess(runnerRoot: string, runnerEntry: string): NodeRuntime {
   const driver = createNodeDriver({
     filesystem: new NodeFileSystem(),
     useDefaultNetwork: true,
+    processConfig: {
+      cwd: runnerRoot,
+      argv: ["node", runnerEntry],
+    },
     permissions: {
       ...allowAllFs,
       ...allowAllNetwork,
       ...allowAllEnv,
     },
   });
 
-  return new NodeProcess({
+  return new NodeRuntime({
     driver,
-    processConfig: {
-      cwd: runnerRoot,
-      argv: ["node", runnerEntry],
-    },
   });
 }