You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
| 3 | Stub | Minimal compatibility surface for lightweight usage and type/instance checks. |
18
+
| 4 | Deferred |`require()` succeeds, but APIs throw deterministic unsupported errors on call. |
19
+
| 5 | Unsupported | Not implemented by design; `require()` throws immediately. |
61
20
62
-
| Module | Status | Notes |
63
-
| --- | --- | --- |
64
-
|**`buffer`**| 🟢 ||
65
-
|**`stream`**| 🟢 ||
66
-
|**`string_decoder`**| 🟢 ||
67
-
|**`zlib`**| 🟢 ||
68
-
|**`querystring`**| 🟢 ||
21
+
Unsupported API errors follow this format: `"<module>.<api> is not supported in sandbox"`.
22
+
Unsupported modules use: `"<module> is not supported in sandbox"`.
69
23
70
-
### Utilities and Diagnostics
24
+
##Compatibility Matrix
71
25
72
-
| Module |Status|Notes|
26
+
| Module |Tier|Status|
73
27
| --- | --- | --- |
74
-
|**`path`**| 🟢 ||
75
-
|**`url`**| 🟢 ||
76
-
|**`util`**| 🟢 ||
77
-
|**`assert`**| 🟢 ||
78
-
|**`events`**| 🟢 ||
79
-
|**`console`**| 🟢 | Circular-safe bounded formatting. Drop-by-default; use `onStdio` hook for streaming. |
80
-
|**`constants`**| 🟢 ||
81
-
|**`tty`**| 🔴 |`isatty()` returns `false`; `ReadStream`/`WriteStream` are compatibility constructors. |
82
-
|**`async_hooks`**| ⚪ ||
83
-
|**`perf_hooks`**| ⚪ ||
84
-
|**`diagnostics_channel`**| ⚪ ||
85
-
|**`readline`**| ⚪ ||
86
-
87
-
### Unsupported
88
-
89
-
| Module | Status |
90
-
| --- | --- |
91
-
|**`dgram`**| ⛔ |
92
-
|**`wasi`**| ⛔ |
93
-
|**`inspector`**| ⛔ |
94
-
|**`repl`**| ⛔ |
95
-
|**`trace_events`**| ⛔ |
96
-
|**`domain`**| ⛔ |
97
-
98
-
---
99
-
100
-
## Error Format
101
-
102
-
Unsupported API calls follow this format:
103
-
104
-
```
105
-
<module>.<api> is not supported in sandbox
106
-
```
107
-
108
-
Unsupported modules use:
109
-
110
-
```
111
-
<module> is not supported in sandbox
112
-
```
113
-
114
-
---
115
-
116
-
## Additional Notes
117
-
118
-
### Node-Modules Overlay
119
-
120
-
The Node runtime composes a read-only `/app/node_modules` overlay from `<cwd>/node_modules` (default `cwd` is host `process.cwd()`, configurable via `moduleAccess.cwd`). Writes under `/app/node_modules/**` are denied with `EACCES`. Native addons (`.node`) are rejected.
121
-
122
-
### Permission Model
123
-
124
-
Runtime permissions are deny-by-default for `fs`, `network`, `childProcess`, and `env`. If a domain checker is not configured, operations fail with `EACCES`. Embedders opt in via explicit permission policies (`allowAll`, `allowAllFs`, `allowAllNetwork`, `allowAllChildProcess`, `allowAllEnv`).
|`http`| 1 (Bridge) | Implemented: `request`, `get`, `createServer`; bridged request/response/server classes and constants. Includes `Agent` with connection pooling (`maxSockets`, `keepAlive`), HTTP upgrade (101 Switching Protocols) handling, and trailer headers support. |
33
+
|`https`| 1 (Bridge) | Implemented: `request`, `get`, `createServer` with the same contract as `http`, including `Agent` pooling, upgrade handling, and trailer headers. |
34
+
|`http2`| 3 (Stub) + 5 (Full support) | Provides compatibility classes (`Http2ServerRequest`, `Http2ServerResponse`); `createServer` and `createSecureServer` are unsupported. |
The [project-matrix test suite](https://github.com/rivet-dev/secure-exec/tree/main/packages/secure-exec/tests/projects) validates that real-world npm packages produce identical output in secure-exec and host Node.js. Each fixture is a black-box Node project with no sandbox-specific code.
63
+
64
+
| Package | Category | What It Tests |
65
+
| --- | --- | --- |
66
+
|[express](https://npmjs.com/package/express)| Web Framework | HTTP server, middleware, routing |
67
+
|[fastify](https://npmjs.com/package/fastify)| Web Framework | Async middleware, schema validation, plugins |
To request a new package be added to the test suite, [open an issue](https://github.com/rivet-dev/secure-exec/issues/new?labels=package-request&title=Package+request:+%5Bpackage-name%5D).
91
+
92
+
## Logging Behavior
93
+
94
+
-`console.log`/`warn`/`error` are supported and serialize arguments with circular-safe bounded formatting.
95
+
-`exec()`/`run()` results do not expose buffered `stdout`/`stderr` fields.
96
+
- By default, secure-exec drops console emissions instead of buffering runtime-managed output.
97
+
- Consumers that need logs should use the explicit `onStdio` hook to stream `stdout`/`stderr` events in emission order.
- Sandboxed TypeScript type checking and compilation belong in the separate `@secure-exec/typescript` package.
103
+
104
+
## Node-Modules Overlay Behavior
105
+
106
+
- Node runtime composes a read-only `/app/node_modules` overlay from `<cwd>/node_modules` (default `cwd` is host `process.cwd()`, configurable via `moduleAccess.cwd`).
107
+
- Overlay reads are constrained to canonical paths under `<cwd>/node_modules` and fail closed on out-of-scope symlink/canonical escapes.
108
+
- Writes and mutations under `/app/node_modules/**` are denied with `EACCES`.
109
+
- Native addons (`.node`) are rejected in overlay-backed module loading.
110
+
111
+
## Permission Model (Runtime/Bridge Scope)
112
+
113
+
- This section describes the core runtime/bridge contract only.
114
+
- Runtime permissions are deny-by-default for `fs`, `network`, `childProcess`, and `env`.
115
+
- If a domain checker is not configured, operations fail with `EACCES`.
- Embedders can opt in via explicit permission policies such as `allowAll`, `allowAllFs`, `allowAllNetwork`, `allowAllChildProcess`, and `allowAllEnv`.
118
+
- 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.
0 commit comments