Node.js Compatibility

​

Target Node Version

​

Architecture

┌─────────────────────────────────────────────────┐
│  Sandbox (V8 Isolate)                           │
│                                                 │
│  User Code (require, fs, http, etc.)            │
│       │                                         │
│       ▼                                         │
│  Bridge Layer (polyfills + bridge modules)      │
│       │                                         │
│       ▼                                         │
│  Virtual Kernel                                 │
│  ├── VFS (virtual file system)                  │
│  ├── Process table (spawn, signals, exit)       │
│  ├── Network stack (TCP, HTTP, DNS, UDP)         │
│  └── Permissions engine (deny-by-default)       │
│       │                                         │
│       ▼                                         │
│  Host Adapters (embedder-provided)              │
└─────────────────────────────────────────────────┘
       │
       ▼
  Host OS (file system, network, etc.)

• All I/O routes through the virtual kernel. fs.readFile() goes through the VFS, http.request() goes through the network stack, child_process.spawn() goes through the process table. The kernel enforces permissions at every boundary.
• Network calls are kernel-mediated. http.createServer() registers a virtual listener in the kernel’s network stack. http.request() to localhost routes through the kernel without touching real TCP — the kernel connects the virtual server to the virtual client directly. External requests go through the host adapter after permission checks.
• The VFS is not the host file system. Files written by sandbox code live in the VFS (in-memory by default). The host file system is accessible only through explicit read-only overlays (e.g., node_modules) configured by the embedder.
• Embedders provide host adapters that implement the actual I/O. A Node.js embedder provides real fs and net; a browser embedder provides fetch-based networking and no file system. The sandbox code doesn’t know or care which adapter backs the kernel.

​

Support Tiers

​

Compatibility Matrix

​

ESM Execution Notes

• exec(code, { filePath }) honors Node-style ESM classification for .mjs entrypoints and .js files under package.json "type": "module".
• ESM package resolution uses import conditions, while require() and createRequire() keep require condition semantics in the same execution.
• Built-in ESM imports such as node:fs and node:path support both default exports and named exports for supported APIs.
• Dynamic import() preserves underlying missing-module, syntax, and evaluation failures instead of collapsing them into successful execution results.

​

Permanently Unsupported Features

​

Modules

​

APIs

​

Behaviors

​

Tested Packages

​

Logging Behavior

• console.log/warn/error are supported and serialize arguments with circular-safe bounded formatting.
• exec()/run() results do not expose buffered stdout/stderr fields.
• By default, secure-exec drops console emissions instead of buffering runtime-managed output.
• Consumers that need logs should use the explicit onStdio hook to stream stdout/stderr events in emission order.

​

TypeScript Workflows

• Core secure-exec runtimes execute JavaScript only.
• Sandboxed TypeScript type checking and compilation belong in the separate @secure-exec/typescript package.

​

Node-Modules Overlay Behavior

• Node runtime composes a read-only /app/node_modules overlay from <cwd>/node_modules (default cwd is host process.cwd(), configurable via moduleAccess.cwd).
• Overlay reads are constrained to canonical paths under <cwd>/node_modules and fail closed on out-of-scope symlink/canonical escapes.
• Writes and mutations under /app/node_modules/** are denied with EACCES.
• Native addons (.node) are rejected in overlay-backed module loading.

​

Permission Model (Runtime/Bridge Scope)

• This section describes the core runtime/bridge contract only.
• Runtime permissions are deny-by-default for fs, network, childProcess, and env.
• If a domain checker is not configured, operations fail with EACCES.
• filterEnv strips environment variables unless permissions.env explicitly allows them.
• Embedders can opt in via explicit permission policies such as allowAll, allowAllFs, allowAllNetwork, allowAllChildProcess, and allowAllEnv.
• Driver-specific convenience defaults (for example, direct createNodeDriver(...) usage when adapters are provided without an explicit permissions policy) are implementation details and are not the canonical runtime/bridge security contract.