Skip to main content

​
Target Node Version

22.x (derived from the @types/node 22.x validation baseline used by tests and type checks).

​
Support Tiers

TierLabelMeaning
1BridgeRuntime implementation in secure-exec bridge modules.
2PolyfillBrowser-compatible polyfill package implementation.
3StubMinimal compatibility surface for lightweight usage and type/instance checks.
4Deferredrequire() succeeds, but APIs throw deterministic unsupported errors on call.
5UnsupportedNot implemented by design; require() throws immediately.
Unsupported API errors follow this format: "<module>.<api> is not supported in sandbox". Unsupported modules use: "<module> is not supported in sandbox".

​
Compatibility Matrix

ModuleTierStatus
fs1 (Bridge) + 4 (Deferred APIs)Implemented: readFile, writeFile, appendFile, open, read, write, close, readdir, mkdir, rmdir, rm, unlink, stat, lstat, rename, copyFile, exists, createReadStream, createWriteStream, writev, access, realpath. Metadata-sensitive operations (stat, exists, readdir with withFileTypes) use metadata-native driver paths instead of content probing. rename delegates to driver semantics (atomic where supported; explicit limitation errors where not). Deferred deterministic errors remain for watch, watchFile, chmod, chown, link, symlink, readlink, truncate, utimes.
process1 (Bridge)Env access (permission-gated), cwd/chdir, exit semantics, timers, stdio, eventing, and basic usage/system metadata APIs.
os1 (Bridge)Platform/arch/version, user/system info, and os.constants.
child_process1 (Bridge) + 5 (fork)Implemented: spawn, spawnSync, exec, execSync, execFile, execFileSync; fork is intentionally unsupported.
http1 (Bridge)Implemented: request, get, createServer; bridged request/response/server classes and constants.
https1 (Bridge)Implemented: request, get, createServer with the same contract as http.
http23 (Stub) + 5 (Full support)Provides compatibility classes (Http2ServerRequest, Http2ServerResponse); createServer and createSecureServer are unsupported.
dns1 (Bridge)Implemented: lookup, resolve, resolve4, resolve6, plus dns.promises variants.
module1 (Bridge)Implements createRequire, Module basics, and builtin resolution (require.resolve("fs") returns builtin identifiers).
timers1 (Bridge)setTimeout, clearTimeout, setInterval, clearInterval, setImmediate, clearImmediate.
path2 (Polyfill)path-browserify; supports default and named ESM imports.
buffer2 (Polyfill)Polyfill via buffer.
url2 (Polyfill)Polyfill via whatwg-url and node-stdlib-browser shims.
events2 (Polyfill)Polyfill via events.
stream2 (Polyfill)Polyfill via readable-stream.
util2 (Polyfill)Polyfill via node-stdlib-browser.
assert2 (Polyfill)Polyfill via node-stdlib-browser.
querystring2 (Polyfill)Polyfill via node-stdlib-browser.
string_decoder2 (Polyfill)Polyfill via node-stdlib-browser.
zlib2 (Polyfill)Polyfill via node-stdlib-browser.
vm2 (Polyfill)Polyfill via node-stdlib-browser.
crypto3 (Stub)Limited bridge/polyfill blend; getRandomValues() and randomUUID() use host node:crypto secure randomness, or throw deterministic unsupported errors if host entropy is unavailable; subtle.* methods throw deterministic unsupported errors.
tty2 (Polyfill)tty-browserify; isatty() returns false; ReadStream/WriteStream are compatibility constructors.
v83 (Stub)Pre-registered stub with mock heap stats and JSON-based serialize/deserialize.
constants2 (Polyfill)constants-browserify; os.constants remains available via os.
Fetch globals (fetch, Headers, Request, Response)1 (Bridge)Bridged via network bridge implementation.
Deferred modules (net, tls, readline, perf_hooks, async_hooks, worker_threads)4 (Deferred)require() returns stubs; APIs throw deterministic unsupported errors when called.
Unsupported modules (dgram, cluster, wasi, diagnostics_channel, inspector, repl, trace_events, domain)5 (Unsupported)require() fails immediately with deterministic unsupported-module errors.

​
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.