@enclave-vm/core 2.17.0 → 2.19.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +265 -38
- package/SECURITY-AUDIT.md +85 -77
- package/adapters/interpreter-adapter.d.ts +27 -0
- package/adapters/worker-pool/config.d.ts +4 -2
- package/adapters/worker-pool/memory-monitor.d.ts +16 -2
- package/adapters/worker-pool/protocol.d.ts +63 -11
- package/adapters/worker-pool/worker-pool-adapter.d.ts +45 -2
- package/adapters/worker-pool/worker-script.d.ts +14 -4
- package/adapters/worker-pool/worker-slot.d.ts +99 -2
- package/console-handler.d.ts +33 -0
- package/deadline-guard.d.ts +65 -0
- package/double-vm/double-vm-wrapper.d.ts +11 -2
- package/double-vm/parent-vm-bootstrap.d.ts +118 -0
- package/enclave.d.ts +31 -0
- package/esm/index.mjs +12581 -8226
- package/esm/worker.mjs +2935 -212
- package/execution-deadline.d.ts +69 -0
- package/global-function-gate.d.ts +22 -1
- package/globals-validator.d.ts +12 -0
- package/index.d.ts +2 -1
- package/index.js +12604 -8250
- package/interpreter/interpreter.d.ts +149 -5
- package/interpreter/safe-globals.d.ts +14 -0
- package/package.json +4 -4
- package/realm-airlock.d.ts +51 -0
- package/safe-error.d.ts +6 -0
- package/safe-runtime.d.ts +16 -0
- package/sandbox-console.d.ts +26 -0
- package/sandbox-rejections.d.ts +67 -0
- package/sandbox-script.d.ts +156 -0
- package/secure-proxy.d.ts +21 -0
- package/src/adapters/worker-pool/package.json +4 -4
- package/src/adapters/worker-pool/worker-script.js +8738 -625
- package/stack-reserve.d.ts +46 -0
- package/tool-bridge.d.ts +34 -2
- package/types.d.ts +105 -5
- package/worker.js +2935 -212
package/README.md
CHANGED
|
@@ -22,7 +22,7 @@ For the full security audit report, see [SECURITY-AUDIT.md](./SECURITY-AUDIT.md)
|
|
|
22
22
|
## Features
|
|
23
23
|
|
|
24
24
|
- **Defense-in-Depth**: 6 layers of security (Pre-Scanner → AST → transformation → AI Scoring → VM/Worker Pool → output sanitization)
|
|
25
|
-
- **Worker Pool Adapter
|
|
25
|
+
- **Worker Pool Adapter**: Optional worker threads around the sandbox, with a heap limit per worker and a hard stop
|
|
26
26
|
- **Safe Tool Calls**: Secure `callTool()` execution with iteration and call limits
|
|
27
27
|
- **Reference Sidecar**: Handle large data without embedding it in the script
|
|
28
28
|
- **Configurable Security Levels**: From STRICT to PERMISSIVE based on trust level
|
|
@@ -81,6 +81,7 @@ enclave.dispose();
|
|
|
81
81
|
interface CreateEnclaveOptions {
|
|
82
82
|
// Execution limits
|
|
83
83
|
timeout?: number; // Execution timeout in ms (default: 5000)
|
|
84
|
+
toolCallGraceMs?: number; // How long a tool call in progress at the timeout may still take (default: same as timeout)
|
|
84
85
|
maxToolCalls?: number; // Maximum tool calls allowed (default: 100)
|
|
85
86
|
maxIterations?: number; // Maximum loop iterations (default: 10000)
|
|
86
87
|
|
|
@@ -88,11 +89,21 @@ interface CreateEnclaveOptions {
|
|
|
88
89
|
securityLevel?: SecurityLevel; // STRICT | SECURE | STANDARD | PERMISSIVE
|
|
89
90
|
validate?: boolean; // Enable AST validation (default: true)
|
|
90
91
|
transform?: boolean; // Enable code transformation (default: true)
|
|
92
|
+
realmGlobals?: 'allowlist' | 'security-level'; // What exists in the script's realm (see "What the Script's Realm Holds")
|
|
93
|
+
|
|
94
|
+
// Where the sandbox runs
|
|
95
|
+
adapter?: 'vm' | 'worker_threads'; // In this process (default) or in a pool of worker threads (see "Worker Pool Adapter")
|
|
96
|
+
workerPoolConfig?: Partial<WorkerPoolConfig>;
|
|
91
97
|
|
|
92
98
|
// Tool execution
|
|
93
99
|
toolHandler?: ToolHandler; // Function to execute tool calls
|
|
94
100
|
toolNamespaces?: ToolNamespaces; // Expose tools as `ns.method(args)` (see "Tool Namespaces")
|
|
95
101
|
|
|
102
|
+
// Console
|
|
103
|
+
consoleHandler?: ConsoleHandler; // Receive console calls as (level, message) instead of the host console (see "Console Handler")
|
|
104
|
+
maxConsoleCalls?: number; // Maximum console calls (default: by security level)
|
|
105
|
+
maxConsoleOutputBytes?: number; // Maximum total console output (default: by security level)
|
|
106
|
+
|
|
96
107
|
// Custom globals
|
|
97
108
|
globals?: Record<string, unknown>; // Additional globals for the VM
|
|
98
109
|
allowFunctionsInGlobals?: boolean; // Allow functions in globals (default: false)
|
|
@@ -161,6 +172,8 @@ Both AST validation and runtime sandbox enforce the same allowed globals for def
|
|
|
161
172
|
| **Debugging** | | | | |
|
|
162
173
|
| `console` | ❌ | ❌ | ❌ | ✅ |
|
|
163
174
|
|
|
175
|
+
With a `consoleHandler`, `console` is allowed at every level (see [Console Handler](#console-handler)).
|
|
176
|
+
|
|
164
177
|
### Blocked Globals (All Security Levels)
|
|
165
178
|
|
|
166
179
|
These dangerous globals are **always blocked** regardless of security level:
|
|
@@ -180,6 +193,36 @@ These dangerous globals are **always blocked** regardless of security level:
|
|
|
180
193
|
| **Error Types** | `Error`, `TypeError`, `ReferenceError`, `SyntaxError`, `RangeError` |
|
|
181
194
|
| **Symbols/Regex** | `Symbol`, `RegExp` |
|
|
182
195
|
|
|
196
|
+
### What the Script's Realm Holds
|
|
197
|
+
|
|
198
|
+
The tables above are what the validator accepts. The realm the script runs in agrees with them:
|
|
199
|
+
|
|
200
|
+
- **Only the allowed globals exist.** With the `agentscript` or `babel` preset and validation on (the default), every other standard global is removed from the realm before the script runs: `Function`, `eval`, `globalThis`, `Proxy`, `Reflect`, `Symbol`, `Promise`, `RegExp`, `WebAssembly`, the engine's `console`, and so on. What is left is the allowed globals of the security level, the runtime helpers, your `globals` and your `toolNamespaces`. A gap in the static rules therefore does not hand a script a global. This is `realmGlobals: 'allowlist'`. With another preset, or with `validate: false`, a script may legitimately name other standard globals, so the default is `realmGlobals: 'security-level'`: only the dangerous globals listed for the level are removed. Either value can be set explicitly.
|
|
201
|
+
- **No name resolves through a prototype.** `constructor`, `toString`, `valueOf`, `hasOwnProperty` and the other members of `Object.prototype` are not reachable as bare names (in every mode).
|
|
202
|
+
- **Scripts run in strict mode.** `this` is `undefined` outside a method call, an assignment to an undeclared name is a `ReferenceError`, and a function has no `caller` or `arguments.callee`. A write that cannot happen throws a `TypeError` instead of being silently ignored: assigning over a built-in method (`obj.toString = ...`; the built-in prototypes are frozen) or changing a frozen object, such as an error the runtime threw.
|
|
203
|
+
- **Regular expressions cannot run.** AgentScript has none, and with the realm allowlist the realm refuses them too, including the ones the engine builds from a string argument of `match`, `matchAll` and `search`. String operations that take plain strings (`split(',')`, `replace('a', 'b')`, `includes`) are unaffected.
|
|
204
|
+
|
|
205
|
+
### Console Handler
|
|
206
|
+
|
|
207
|
+
Without a `consoleHandler`, `console` is allowed only at `PERMISSIVE` and writes to the host process console. With one, scripts may use `console` at every security level and each call goes to the handler instead:
|
|
208
|
+
|
|
209
|
+
```typescript
|
|
210
|
+
import { Enclave, type ConsoleHandler } from '@enclave-vm/core';
|
|
211
|
+
|
|
212
|
+
const consoleHandler: ConsoleHandler = (level, message) => logger[level](message);
|
|
213
|
+
const enclave = new Enclave({ securityLevel: 'STRICT', consoleHandler });
|
|
214
|
+
|
|
215
|
+
await enclave.run(`console.info('users', { count: 2 }); return 1;`); // logger.info('users {"count":2}')
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
- `level` is a `ConsoleLevel` (`'log' | 'info' | 'warn' | 'error' | 'debug'`); `message` is the formatted line (arguments joined by spaces, objects JSON-serialized).
|
|
219
|
+
- `maxConsoleCalls` and `maxConsoleOutputBytes` are checked before the handler runs; past a limit the script's call throws and the handler is not called.
|
|
220
|
+
- The handler's return value is ignored and anything it throws or rejects with is swallowed.
|
|
221
|
+
- The handler is not started for a console call a script makes with the stack nearly full (less than 128 KB left): that line is dropped. Without a handler, at `PERMISSIVE`, such a call throws a `RangeError` in the script instead of starting the host console. See [A script at a full stack](#a-script-at-a-full-stack).
|
|
222
|
+
- The script's `console` is a frozen, null-prototype object built inside the sandbox; it leads to neither the handler nor any host object.
|
|
223
|
+
- Supported by the double VM (default), the `vm` adapter and the `worker_threads` adapter. A custom `sandboxAdapter` receives the handler as `context.consoleHandler`; the built-in `InterpreterAdapter` passes it one line of text per call, like the other adapters.
|
|
224
|
+
- Combining a `consoleHandler` with a `console` entry in `globals` throws a `TypeError`.
|
|
225
|
+
|
|
183
226
|
### AST Presets
|
|
184
227
|
|
|
185
228
|
The `preset` option controls **AST-level validation** - what JavaScript constructs are allowed before code transformation. This is separate from `securityLevel` which controls runtime security.
|
|
@@ -218,13 +261,16 @@ const enclave = new Enclave({
|
|
|
218
261
|
|
|
219
262
|
## Worker Pool Adapter (Optional)
|
|
220
263
|
|
|
221
|
-
|
|
264
|
+
`adapter: 'worker_threads'` runs each script in a worker thread taken from a pool. Inside the worker the script runs in the **same sandbox** as in process: the double VM by default. The worker thread is a layer around that sandbox and adds what only a separate thread can:
|
|
265
|
+
|
|
266
|
+
- **A heap limit per worker.** A script that outgrows `memoryLimitPerWorker` loses its worker, and the pool starts a replacement. The engine enforces the limit, or the pool does when the engine cannot: see [The Worker Heap Limit](#the-worker-heap-limit), also for what the limit does not guarantee.
|
|
267
|
+
- **A stop that does not depend on the script.** A script that does not end is terminated together with its worker (`timeout` plus a grace period of five seconds). In process, a script that cannot be interrupted keeps the host's thread.
|
|
222
268
|
|
|
223
269
|
```typescript
|
|
224
270
|
import { Enclave } from '@enclave-vm/core';
|
|
225
271
|
|
|
226
272
|
const enclave = new Enclave({
|
|
227
|
-
adapter: 'worker_threads', //
|
|
273
|
+
adapter: 'worker_threads', // Run scripts in the worker pool
|
|
228
274
|
workerPoolConfig: {
|
|
229
275
|
minWorkers: 2,
|
|
230
276
|
maxWorkers: 8,
|
|
@@ -236,14 +282,24 @@ const enclave = new Enclave({
|
|
|
236
282
|
});
|
|
237
283
|
```
|
|
238
284
|
|
|
285
|
+
A worker thread is **not a sandbox by itself**: it has the whole Node.js API and shares the process with the host. It is also not process isolation. For tenants that must not share a process, run one enclave per process or container.
|
|
286
|
+
|
|
287
|
+
### What Is Different From In-Process Execution
|
|
288
|
+
|
|
289
|
+
- **Tool calls** are sent to the host thread and go through the same tool bridge as in-process tool calls (argument and result sanitization, sidecar references, the tool-call limit), so they behave the same. Tool names must start with a letter and contain only letters, digits, `:`, `.`, `_` and `-`; a call with another name fails with an error the script can catch.
|
|
290
|
+
- **Custom globals** reach a worker as JSON data. Functions in `globals` are not available there.
|
|
291
|
+
- **Console output** without a `consoleHandler` is printed by the host with a `[Worker]` prefix.
|
|
292
|
+
- **`toolBridge.mode: 'direct'`** does not apply: requests and responses always cross as strings.
|
|
293
|
+
|
|
239
294
|
### When to Use Worker Pool
|
|
240
295
|
|
|
241
|
-
| Scenario
|
|
242
|
-
|
|
|
243
|
-
| Trusted internal scripts
|
|
244
|
-
|
|
|
245
|
-
|
|
|
246
|
-
|
|
|
296
|
+
| Scenario | Recommendation |
|
|
297
|
+
| ------------------------------------- | ------------------------------------ |
|
|
298
|
+
| Trusted internal scripts | In process (lower overhead) |
|
|
299
|
+
| Untrusted AI-generated code | Worker Pool (hard stop) |
|
|
300
|
+
| Memory-sensitive workloads | Worker Pool (heap limit per worker) |
|
|
301
|
+
| Tenants that must not share a process | One enclave per process or container |
|
|
302
|
+
| A host that must survive any script | One enclave per process or container |
|
|
247
303
|
|
|
248
304
|
### Worker Pool Presets
|
|
249
305
|
|
|
@@ -256,42 +312,56 @@ const enclave = new Enclave({
|
|
|
256
312
|
|
|
257
313
|
### Worker Pool Configuration Options
|
|
258
314
|
|
|
259
|
-
| Option | Default | Description
|
|
260
|
-
| ------------------------ | --------- |
|
|
261
|
-
| `minWorkers` | 2 | Minimum warm workers
|
|
262
|
-
| `maxWorkers` | CPU count | Maximum concurrent workers
|
|
263
|
-
| `memoryLimitPerWorker` | 128MB |
|
|
264
|
-
| `maxMessagesPerSecond` | 1000 | Rate limit per worker
|
|
265
|
-
| `maxExecutionsPerWorker` | 1000 | Recycle after N executions
|
|
266
|
-
| `maxQueueSize` | 100 | Maximum pending executions
|
|
267
|
-
| `idleTimeoutMs` | 30000 | Time before idle worker release
|
|
315
|
+
| Option | Default | Description |
|
|
316
|
+
| ------------------------ | --------- | ------------------------------------------------------- |
|
|
317
|
+
| `minWorkers` | 2 | Minimum warm workers |
|
|
318
|
+
| `maxWorkers` | CPU count | Maximum concurrent workers |
|
|
319
|
+
| `memoryLimitPerWorker` | 128MB | Heap limit of each worker (its old generation); 0: none |
|
|
320
|
+
| `maxMessagesPerSecond` | 1000 | Rate limit per worker |
|
|
321
|
+
| `maxExecutionsPerWorker` | 1000 | Recycle after N executions |
|
|
322
|
+
| `maxQueueSize` | 100 | Maximum pending executions |
|
|
323
|
+
| `idleTimeoutMs` | 30000 | Time before idle worker release |
|
|
324
|
+
|
|
325
|
+
Executions beyond `maxWorkers` wait in a queue (`maxQueueSize`, `queueTimeoutMs`). The wait counts against the script's `timeout`, so size `maxWorkers` for the concurrency you expect.
|
|
326
|
+
|
|
327
|
+
### The Worker Heap Limit
|
|
268
328
|
|
|
269
|
-
|
|
329
|
+
`memoryLimitPerWorker` is the limit of the worker's old generation, passed to the engine as the worker's `resourceLimits`. The engine allows the young generation on top of it, and the pool sets that to 24 MB, so the most a worker can hold is the sum of the two: its budget. (Left to the engine the young generation of such a worker is 192 MB on Node.js 24 and 48 MB on Node.js 22, measured on a 64-bit machine.)
|
|
270
330
|
|
|
271
|
-
When
|
|
331
|
+
**A heap flag on the process replaces it.** When the host process runs with `--max-old-space-size`, on the command line or in `NODE_OPTIONS`, that value becomes the heap limit of every worker thread, whatever limit a worker was created with (this is Node.js behaviour; `worker.resourceLimits` goes on reporting the limit that was asked for). The pool therefore reads the actual limit of each new worker. When the engine does not apply the configured one, the pool logs a warning once and enforces the limit itself: while a worker executes, it reads the worker's heap every 100 ms and terminates the worker when its heap and external memory exceed the budget. The execution fails with `WorkerMemoryError`. This is approximate, because a script can allocate between two reads: with a 64 MB limit and `--max-old-space-size=4096`, a script that kept allocating was stopped when its worker held about 290 MB, with the process at 0.5 GB resident; without the check it went on until the process was at 4.4 GB. Reading a worker's heap from outside needs Node.js 22.16 or later; on an older 22.x the pool can only warn that the limit is not enforced.
|
|
332
|
+
|
|
333
|
+
**The memory monitor** (`memoryCheckIntervalMs`) asks every worker for its memory use and recycles a worker that holds more than its budget. It compares what the worker itself holds, its heap plus its external memory. (`rss` is no measure of a worker: inside a worker thread it is the resident size of the whole process.)
|
|
334
|
+
|
|
335
|
+
**What the limit does not guarantee** is that the host process survives. A worker thread shares the process, and Node.js says of these limits that the process may still abort. When a worker reaches its limit, Node.js ends the worker and lets the engine finish what it is doing; an allocation burst that outruns that is a fatal out-of-memory error for the whole process. A worker that runs plain JavaScript, limited to 64 MB and keeping 50 KB strings in a tight loop, aborted the process in 6 of 6 runs on Node.js 24.18. Inside the sandbox the same loop ended only its worker when the machine was idle (40 of 40 processes), but with the engine's default young generation it aborted 13 of 480 processes that ran 12 at a time: one garbage collection can move more into the old generation than the 16 MB Node.js allows the engine to finish with. That is why the pool sets the young generation to 24 MB; with it, 0 of 480 processes aborted under the same load. One allocation that is larger than that allowance still ends the process. With the default `memoryLimit` the sandbox's own accounting stops a script long before the worker's limit is reached. Treat the worker's limit as a backstop that usually works. A host that must survive whatever a script allocates needs the enclave in a child process or a container with a memory limit of the operating system.
|
|
336
|
+
|
|
337
|
+
### Layers
|
|
272
338
|
|
|
273
339
|
```
|
|
274
|
-
|
|
275
|
-
│ Worker
|
|
276
|
-
│
|
|
277
|
-
│ │ VM
|
|
278
|
-
│ │
|
|
279
|
-
│ │
|
|
280
|
-
│
|
|
281
|
-
│
|
|
282
|
-
│ - JSON
|
|
283
|
-
|
|
284
|
-
|
|
340
|
+
┌──────────────────────────────────────────────────────┐
|
|
341
|
+
│ Worker thread: heap limit, terminated on overrun │
|
|
342
|
+
│ ┌──────────────────────────────────────────────────┐│
|
|
343
|
+
│ │ Parent VM: membrane, tool gate, validation ││
|
|
344
|
+
│ │ ┌──────────────────────────────────────────────┐││
|
|
345
|
+
│ │ │ Inner VM: the script, allowed globals only │││
|
|
346
|
+
│ │ └──────────────────────────────────────────────┘││
|
|
347
|
+
│ └──────────────────────────────────────────────────┘│
|
|
348
|
+
│ - messages to the host are JSON text │
|
|
349
|
+
└──────────────────────────────────────────────────────┘
|
|
350
|
+
│ tool calls, console, result
|
|
351
|
+
▼
|
|
352
|
+
Host thread: checks every message against the protocol
|
|
353
|
+
schema, runs the tool bridge, owns the watchdog
|
|
285
354
|
```
|
|
286
355
|
|
|
287
356
|
### Security Features
|
|
288
357
|
|
|
289
|
-
-
|
|
290
|
-
-
|
|
291
|
-
-
|
|
292
|
-
- **
|
|
293
|
-
- **
|
|
294
|
-
- **
|
|
358
|
+
- **The double VM inside the worker**: the same realm, membrane and limits as an in-process execution (a single VM with `doubleVm: { enabled: false }`)
|
|
359
|
+
- **`worker.terminate()`**: hard stop for a script nothing else can interrupt
|
|
360
|
+
- **`resourceLimits`**: a heap limit per worker, enforced by V8, or by the pool when a heap flag of the process overrides it ([The Worker Heap Limit](#the-worker-heap-limit))
|
|
361
|
+
- **The host does not trust a worker**: every message is parsed without prototype pollution and checked against the protocol schema (types, identifier and tool-name patterns, sizes); a message that fails ends the execution and replaces the worker
|
|
362
|
+
- **JSON-only messages**: no structured clone of objects in either direction
|
|
363
|
+
- **Rate limiting**: message flood protection per worker
|
|
364
|
+
- **Pool recovery**: a worker that is terminated or dies is removed and replaced, so the pool is not left short. Running out of memory is the one way a worker can still take the process with it ([The Worker Heap Limit](#the-worker-heap-limit))
|
|
295
365
|
|
|
296
366
|
## Double VM Security Layer
|
|
297
367
|
|
|
@@ -658,6 +728,9 @@ through the enclave's gate:
|
|
|
658
728
|
|
|
659
729
|
- it is refused once the execution is aborted, and counts toward `maxGlobalFunctionCalls`
|
|
660
730
|
(default: 10 × `maxToolCalls`), not toward `maxToolCalls`;
|
|
731
|
+
- its arguments are copied into plain host data first, the way tool arguments are: the function
|
|
732
|
+
receives null-prototype objects, arrays, primitives and `Date`s, never a live script value, and a
|
|
733
|
+
call that passes a function or a symbol is refused. The script's `this` is not passed either;
|
|
661
734
|
- in the double VM (the default) it shares the operation rate limit
|
|
662
735
|
(`doubleVm.parentValidation.maxOperationsPerSecond`) with tool calls;
|
|
663
736
|
- its return value is sanitized like a tool result: the script receives a plain-data copy, and a
|
|
@@ -668,6 +741,47 @@ through the enclave's gate:
|
|
|
668
741
|
The suspicious-sequence detectors only look at tool calls, so expose tools with `toolNamespaces` or
|
|
669
742
|
`callTool()`, not as functions. The `worker_threads` adapter never passes functions into the sandbox.
|
|
670
743
|
|
|
744
|
+
A function is not started when the script calls it with the stack nearly full (less than 128 KB
|
|
745
|
+
left): the call throws a `RangeError` in the script, and the function has not run. The check only
|
|
746
|
+
decides whether a function starts: it is never started halfway. It says nothing about a function
|
|
747
|
+
that did start. An async function that is still in progress when `toolCallGraceMs` is over is left
|
|
748
|
+
behind like a tool call, and `run()` ends without its result reaching the script.
|
|
749
|
+
|
|
750
|
+
The validation of `globals` judges what a script can reach through a value, not only what the
|
|
751
|
+
value has itself. The methods of a class are functions in `globals`: an instance of a class with
|
|
752
|
+
methods needs `allowFunctionsInGlobals: true`, and so does a function in a property that is not
|
|
753
|
+
enumerable or is keyed by a symbol. Code that runs when a property is read is refused whatever is
|
|
754
|
+
allowed: a getter or setter, on the value or on its class, and a Proxy of an object. That
|
|
755
|
+
includes a `Buffer` (pass a `Uint8Array`) and an `Error` object (pass its message). A function
|
|
756
|
+
passed as a global is judged as a function; what hangs on it is not looked at.
|
|
757
|
+
An instance of a class without methods or accessors is plain data and is accepted, unless
|
|
758
|
+
`secureProxyConfig.blockConstructor` is off (as at `PERMISSIVE`): then a script can read its
|
|
759
|
+
`constructor`, which is a function.
|
|
760
|
+
|
|
761
|
+
Values passed in `globals` are **read-only** inside the sandbox. They are the host's own objects, shared
|
|
762
|
+
by every execution of the enclave, so a script cannot assign to them, add or delete properties, freeze
|
|
763
|
+
them, or call a built-in method that changes its receiver (`push`, `sort`, `Map.prototype.set`,
|
|
764
|
+
`Date.prototype.setTime`, ...): the attempt throws, or is ignored at `PERMISSIVE`. Reading works as
|
|
765
|
+
before, and an array returned by a built-in method (`map`, `filter`, `slice`, ...) is the script's own
|
|
766
|
+
copy, which it can sort or extend. To let scripts keep state, return it from a tool instead.
|
|
767
|
+
|
|
768
|
+
A **regular expression** passed in `globals` can be read (`source`, `flags`, `global`, ...) but not
|
|
769
|
+
run: `test`, `exec` and its use as the pattern of `match`, `matchAll`, `replace`, `search` or `split`
|
|
770
|
+
throw, at every security level. A match would run the host's pattern on a text the script chooses,
|
|
771
|
+
outside the rules that apply to the script's own expressions, and with the `g` or `y` flag it writes
|
|
772
|
+
`lastIndex` on the host's object. Pass a function that does the matching, or let the script build
|
|
773
|
+
the expression from `source` and `flags` where the preset allows `RegExp`. The same goes for
|
|
774
|
+
`match`, `matchAll` and `search` on a `String` object (`new String(...)`) passed in `globals`;
|
|
775
|
+
a plain string is not affected.
|
|
776
|
+
|
|
777
|
+
A custom global cannot be named `Object`: the sandbox provides its own. The constructor throws.
|
|
778
|
+
|
|
779
|
+
With the single VM, an object of the script's own that a host built-in hands back to a callback
|
|
780
|
+
(the object a script gave `reduce` to collect into) stays the script's and stays writable. The
|
|
781
|
+
runtime recognises it by its prototype chain, which ends in the sandbox's `Object.prototype`. An
|
|
782
|
+
object without a prototype (`Object.create(null)`) carries nothing that says who made it and is
|
|
783
|
+
treated as the host's, so it arrives read-only in the callback: collect into `{}` or an array.
|
|
784
|
+
|
|
671
785
|
Inside arrays, Maps and Sets only plain data is allowed (primitives, plain objects, arrays, Maps, Sets,
|
|
672
786
|
Dates, RegExps, typed arrays): the built-in methods of those collections (`forEach`, iteration, `get`)
|
|
673
787
|
hand elements to the script directly, so a function (or an object with methods) stored there would be
|
|
@@ -715,6 +829,45 @@ file locations in the remaining lines are redacted.
|
|
|
715
829
|
| `TOOL_ERROR` | Tool handler threw an error |
|
|
716
830
|
| `RUNTIME_ERROR` | General runtime error in script |
|
|
717
831
|
|
|
832
|
+
### How `timeout` Is Enforced
|
|
833
|
+
|
|
834
|
+
- The time is the script's: the clock starts when the sandbox is ready to run it. Validation, the
|
|
835
|
+
transform and the creation of the sandbox adapter (once per enclave; with the worker pool that
|
|
836
|
+
starts the worker threads) come before it. Waiting for a free worker counts, and a script whose
|
|
837
|
+
time has passed while it waited is not started: `run()` returns `ExecutionAbortedError`.
|
|
838
|
+
- Until the script's first `await`, Node's `vm` interrupts it at the deadline.
|
|
839
|
+
- After that, the script checks the clock itself: the transformer inserts a check at the start of
|
|
840
|
+
every function and loop body, so synchronous work, recursion and promise chains that never yield
|
|
841
|
+
are stopped at the deadline as well. A script that catches the timeout error cannot enter another
|
|
842
|
+
function or loop iteration.
|
|
843
|
+
- A tool call in progress at the deadline is not cut off, and its result is delivered. From then on
|
|
844
|
+
the next tool call or call into a host function is refused with `Execution aborted`. The same
|
|
845
|
+
holds for an async function from `globals`.
|
|
846
|
+
- That wait has an end: `toolCallGraceMs` after the deadline the execution ends with the timeout
|
|
847
|
+
error, whatever is still in progress, and `error.data.pendingHostCalls` says how many calls
|
|
848
|
+
were left running. The default is the value of `timeout`, so `run()` takes at most twice
|
|
849
|
+
`timeout`. `0` ends every execution at the deadline; `Infinity` waits for the handler however
|
|
850
|
+
long it takes, as versions up to 2.18 did (a handler that never settles then keeps `run()` from
|
|
851
|
+
settling).
|
|
852
|
+
- When `run()` has returned, for whatever reason, the script is finished for the host as well.
|
|
853
|
+
What it left behind (a tool call it did not await, with a `then` on it) can no longer call a
|
|
854
|
+
tool, a function from `globals` or the console.
|
|
855
|
+
- A script that only waits is ended as well. Waiting takes no code: a thenable that never calls
|
|
856
|
+
back (`return { then: () => 0 }`) is enough, and nothing runs that could look at the clock. So
|
|
857
|
+
the enclave keeps count of what the host has in flight for the script (tool calls, async
|
|
858
|
+
functions from `globals`), and from the deadline on `run()` returns the timeout error as soon as
|
|
859
|
+
that count is zero. A sandbox has no timers and no I/O, so nothing else could wake the script.
|
|
860
|
+
(With `adapter: 'worker_threads'` the pool ends such a script like a busy one: with its worker,
|
|
861
|
+
five seconds after the deadline.)
|
|
862
|
+
- Not covered: a single built-in call that does all its work natively (the memory limit bounds
|
|
863
|
+
those) and a script run with `transform: false`. And the enclave cannot stop your
|
|
864
|
+
`toolHandler`: a call it stops waiting for keeps running in the host, so a tool that changes
|
|
865
|
+
something should be safe to repeat, or have a time limit of its own. For a
|
|
866
|
+
stop the script cannot influence, use `adapter: 'worker_threads'`: a script that is still
|
|
867
|
+
running five seconds after its timeout is terminated with its worker (see
|
|
868
|
+
[Worker Pool Adapter](#worker-pool-adapter-optional)). A process you can terminate does the
|
|
869
|
+
same for everything else that runs in it.
|
|
870
|
+
|
|
718
871
|
## Defense-in-Depth Architecture
|
|
719
872
|
|
|
720
873
|
```
|
|
@@ -762,7 +915,7 @@ file locations in the remaining lines are redacted.
|
|
|
762
915
|
┌─────────────────────────────────────────────────────────────┐
|
|
763
916
|
│ Layer 4: Runtime Sandbox │
|
|
764
917
|
│ ├── Standard: Node.js vm (prototype isolation) │
|
|
765
|
-
│ ├── Optional: Worker Pool (
|
|
918
|
+
│ ├── Optional: Worker Pool (heap limit, hard stop) │
|
|
766
919
|
│ │ ├── Dual-layer: worker thread + VM context │
|
|
767
920
|
│ │ ├── Hard halt via worker.terminate() │
|
|
768
921
|
│ │ └── Per-worker memory limits │
|
|
@@ -785,6 +938,80 @@ file locations in the remaining lines are redacted.
|
|
|
785
938
|
└─────────────────────────────────────────────────────────────┘
|
|
786
939
|
```
|
|
787
940
|
|
|
941
|
+
## Runtime Notes
|
|
942
|
+
|
|
943
|
+
### Node.js 24 (V8 13.x)
|
|
944
|
+
|
|
945
|
+
V8 13.x, which every Node.js 24 release ships, can crash the process when the same compiled code is instantiated in a second context: once a function has baseline (Sparkplug) code, a garbage collection that starts while a fresh closure of it is being entered reads a stale register (`SIGSEGV` in `ClearStaleLeftTrimmedPointerVisitor`). Running one script repeatedly, in fresh contexts, is exactly that pattern. Node.js 22 does not have the defect and V8 14.1 (Node.js 25) fixed it.
|
|
946
|
+
|
|
947
|
+
On an affected engine the enclave therefore never shares compiled sandbox code: every source it compiles for a sandbox is made unique, so nothing comes out of the engine's compilation cache. Nothing needs to be configured. Details and the crash measurements are in `src/sandbox-script.ts`.
|
|
948
|
+
|
|
949
|
+
A process started with `node --no-sparkplug` has no baseline code and cannot hit the defect. The enclave reads that flag from the command line (`process.execArgv`) when it is loaded, and in such a process it shares compiled code as on an unaffected engine. Measured in the same batch as the table, the same script again took 3.0 ms per execution with the flag (5.5 ms without it), which is what Node.js 22 takes; a script the engine had not seen gained little (5.0 ms against 5.6 ms). The flag has a price of its own: everything in the process that is not optimized yet runs in the interpreter. It has to be on the command line (Node.js refuses it in `NODE_OPTIONS`), and a command line that mentions the baseline compiler in any other way, such as `--always-sparkplug`, keeps the workaround on.
|
|
950
|
+
|
|
951
|
+
What that costs, measured on Node.js 24.18.0 and 22.21.1 (arm64) with a small script, the double VM and default options:
|
|
952
|
+
|
|
953
|
+
| Time per execution | Node.js 24 | Node.js 22 | 2.18.0 (either) |
|
|
954
|
+
| --------------------------------------- | ---------- | ---------- | ----------------------------------------------------------------------- |
|
|
955
|
+
| The same script again | 5.5 ms | 3.0 ms | 2.0 ms |
|
|
956
|
+
| A script the engine has not seen before | 5.6 ms | 5.1 ms | 6.0 ms at first; 10.5 ms as the median over 1,500 scripts of one length |
|
|
957
|
+
|
|
958
|
+
The last column rose because the engine compares a new source with every source of the same length it still holds (V8 hashes a long string by its length alone), and the bootstraps of two scripts of one length used to differ only near their end. They now differ at their start, and on an affected engine they also differ in length.
|
|
959
|
+
|
|
960
|
+
### A script at a full stack
|
|
961
|
+
|
|
962
|
+
A script can recurse until the stack is full and, on the way back up, call everything it has at
|
|
963
|
+
every level. What the enclave guarantees there:
|
|
964
|
+
|
|
965
|
+
- **What the script catches is its own.** Every call into the runtime enters through a function of
|
|
966
|
+
the script's realm, so the `RangeError` of a stack overflow is an error of that realm whatever
|
|
967
|
+
was being called.
|
|
968
|
+
- **The runtime's code and yours start with room to finish.** V8 refuses to compile a function for
|
|
969
|
+
its first call when less than about 40 KB of stack is left (measured: 39.9 KB with Node.js 24,
|
|
970
|
+
46.4 KB with Node.js 22), so code that starts in that zone fails wherever it first calls
|
|
971
|
+
something new. A call into the runtime needs 64 KB; a function from `globals`, a
|
|
972
|
+
`consoleHandler` and the host console need 128 KB, checked on the host right before they start.
|
|
973
|
+
With less, the script gets a `RangeError` (a console line for a `consoleHandler` is dropped)
|
|
974
|
+
and nothing of the host has run. Without this, a write to `process.stdout` that is cut off
|
|
975
|
+
halfway leaves that stream waiting forever, and that is not specific to the sandbox.
|
|
976
|
+
- **A tool handler starts from an empty stack**, whatever the script's stack looks like when it
|
|
977
|
+
makes the call.
|
|
978
|
+
- The check costs about 2.7 microseconds per call into the runtime and about 5.5 per call into
|
|
979
|
+
your code. Reading a property is not checked, and has no need to be: `globals` cannot hold
|
|
980
|
+
getters or proxies, so no code of yours runs on a read (see [Custom Globals](#custom-globals)).
|
|
981
|
+
|
|
982
|
+
What it does not prevent: **Node.js writes to the process's stderr** when a promise is rejected
|
|
983
|
+
while the stack is full. Its own bookkeeping for the rejection is JavaScript and cannot run there,
|
|
984
|
+
and it prints a block (`Exception in PromiseRejectCallback`, with the source line that was
|
|
985
|
+
executing) from native code. A script can produce such blocks at a few megabytes per second for as
|
|
986
|
+
long as it runs, and the printed line is a line of the script. Nothing in JavaScript can intercept
|
|
987
|
+
that write, in a worker thread either. If your stderr is collected, give it a size limit and do not
|
|
988
|
+
parse it for decisions; a child process whose stderr you control is the complete answer.
|
|
989
|
+
|
|
990
|
+
### Promise rejections a script leaves behind
|
|
991
|
+
|
|
992
|
+
Node.js ends the process when a promise is rejected and nothing handles it, and the rule covers
|
|
993
|
+
the promises of a sandbox: an async function that throws and is not awaited, a failing tool call
|
|
994
|
+
nobody awaits. The enclave therefore answers the two process events `unhandledRejection` and
|
|
995
|
+
`rejectionHandled` itself for every promise that is not one of the host realm (it wraps
|
|
996
|
+
`process.emit` the first time a sandbox is used). The process goes on, none of your listeners is
|
|
997
|
+
called with a script's promise or reason, and your own rejections reach your listeners, or end the
|
|
998
|
+
process, exactly as before.
|
|
999
|
+
|
|
1000
|
+
- Under `--unhandled-rejections=strict` Node.js raises the exception before it emits anything, and
|
|
1001
|
+
under `=warn` it prints its warning first: use the default mode (`throw`) or `none`.
|
|
1002
|
+
- Promises of `vm` contexts your application created itself are covered as well.
|
|
1003
|
+
- `disableSandboxRejectionGuard()` turns this off. Your `unhandledRejection` listener then has to
|
|
1004
|
+
ignore every promise for which `isHostPromise(promise)` is false, without touching the reason.
|
|
1005
|
+
`disableSandboxRejectionGuard(false)` turns it back on from the next execution of an enclave.
|
|
1006
|
+
- Test runners that give tests a stand-in `process` object (Jest does) are not covered: there the
|
|
1007
|
+
runner reports a script's rejection as a failure of the test.
|
|
1008
|
+
- In the sandbox, `Symbol.for` refuses keys in the `nodejs.` namespace: Node.js looks up some of
|
|
1009
|
+
its own protocols in that registry, among them the method `util.inspect` calls on a value.
|
|
1010
|
+
|
|
1011
|
+
### Memory under sustained load
|
|
1012
|
+
|
|
1013
|
+
V8 keeps every script it compiled in its compilation cache until several major garbage collections have passed, whether or not anything still uses it. An execution of a script the engine has not seen before leaves about 0.4 MB there (0.26 MB in 2.18.0); on an affected engine every execution does, because no compiled code is shared. Under a steady stream of executions the heap therefore grows toward its limit before the engine starts dropping those entries: 2,000 executions took the heap to 1.4 GB with the default limit, and stayed at about 0.5 GB, at the same speed, with `--max-old-space-size=512`. Nothing is leaked: a heap snapshot, which clears that cache, shows 2 KB per execution. Give the process the heap limit you want it to stay within rather than relying on the default. With the worker pool, that flag also replaces the heap limit of every worker thread, and the pool then enforces `memoryLimitPerWorker` itself: see [The Worker Heap Limit](#the-worker-heap-limit).
|
|
1014
|
+
|
|
788
1015
|
## API Reference
|
|
789
1016
|
|
|
790
1017
|
### Enclave Class
|