@enclave-vm/core 2.18.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 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** (NEW): Optional OS-level memory isolation via worker threads with hard halt capability
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,6 +89,11 @@ 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
@@ -187,6 +193,15 @@ These dangerous globals are **always blocked** regardless of security level:
187
193
  | **Error Types** | `Error`, `TypeError`, `ReferenceError`, `SyntaxError`, `RangeError` |
188
194
  | **Symbols/Regex** | `Symbol`, `RegExp` |
189
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
+
190
205
  ### Console Handler
191
206
 
192
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:
@@ -203,8 +218,9 @@ await enclave.run(`console.info('users', { count: 2 }); return 1;`); // logger.i
203
218
  - `level` is a `ConsoleLevel` (`'log' | 'info' | 'warn' | 'error' | 'debug'`); `message` is the formatted line (arguments joined by spaces, objects JSON-serialized).
204
219
  - `maxConsoleCalls` and `maxConsoleOutputBytes` are checked before the handler runs; past a limit the script's call throws and the handler is not called.
205
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).
206
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.
207
- - 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` has no `console`, so a script that uses it fails there.
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.
208
224
  - Combining a `consoleHandler` with a `console` entry in `globals` throws a `TypeError`.
209
225
 
210
226
  ### AST Presets
@@ -245,13 +261,16 @@ const enclave = new Enclave({
245
261
 
246
262
  ## Worker Pool Adapter (Optional)
247
263
 
248
- For environments requiring **OS-level memory isolation**, enable the Worker Pool Adapter. This provides a dual-layer sandbox with hard halt capability:
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.
249
268
 
250
269
  ```typescript
251
270
  import { Enclave } from '@enclave-vm/core';
252
271
 
253
272
  const enclave = new Enclave({
254
- adapter: 'worker_threads', // Enable Worker Pool
273
+ adapter: 'worker_threads', // Run scripts in the worker pool
255
274
  workerPoolConfig: {
256
275
  minWorkers: 2,
257
276
  maxWorkers: 8,
@@ -263,14 +282,24 @@ const enclave = new Enclave({
263
282
  });
264
283
  ```
265
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
+
266
294
  ### When to Use Worker Pool
267
295
 
268
- | Scenario | Recommendation |
269
- | --------------------------- | ------------------------------- |
270
- | Trusted internal scripts | Standard VM (lower overhead) |
271
- | Multi-tenant execution | Worker Pool (OS isolation) |
272
- | Untrusted AI-generated code | Worker Pool (hard halt) |
273
- | Memory-sensitive workloads | Worker Pool (per-worker limits) |
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 |
274
303
 
275
304
  ### Worker Pool Presets
276
305
 
@@ -283,42 +312,56 @@ const enclave = new Enclave({
283
312
 
284
313
  ### Worker Pool Configuration Options
285
314
 
286
- | Option | Default | Description |
287
- | ------------------------ | --------- | ------------------------------- |
288
- | `minWorkers` | 2 | Minimum warm workers |
289
- | `maxWorkers` | CPU count | Maximum concurrent workers |
290
- | `memoryLimitPerWorker` | 128MB | Per-worker memory limit |
291
- | `maxMessagesPerSecond` | 1000 | Rate limit per worker |
292
- | `maxExecutionsPerWorker` | 1000 | Recycle after N executions |
293
- | `maxQueueSize` | 100 | Maximum pending executions |
294
- | `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 |
295
324
 
296
- ### Dual-Layer Sandbox
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.
297
326
 
298
- When using Worker Pool, code runs in a **dual-layer sandbox**:
327
+ ### The Worker Heap Limit
328
+
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.)
330
+
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
299
338
 
300
339
  ```
301
- ┌─────────────────────────────────────────────────┐
302
- │ Worker Thread (OS-level isolation) │
303
- │ ┌─────────────────────────────────────────────┐│
304
- │ │ VM Context (prototype isolation) ││
305
- │ │ - Whitelist-only globals ││
306
- │ │ - __safe_* runtime functions ││
307
- │ └─────────────────────────────────────────────┘│
308
- │ - parentPort removed from globals │
309
- │ - JSON-only message serialization │
310
- │ - Hard halt via worker.terminate() │
311
- └─────────────────────────────────────────────────┘
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
312
354
  ```
313
355
 
314
356
  ### Security Features
315
357
 
316
- - **`worker.terminate()`**: Hard halt runaway scripts when VM timeout fails
317
- - **`--max-old-space-size`**: Per-worker memory limits enforced by V8
318
- - **JSON-only serialization**: Prevents structured clone gadget attacks
319
- - **Dangerous global removal**: parentPort, workerData inaccessible in worker
320
- - **Rate limiting**: Message flood protection per worker
321
- - **Safe deserialize**: Prototype pollution prevention via JSON-only parsing
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))
322
365
 
323
366
  ## Double VM Security Layer
324
367
 
@@ -685,6 +728,9 @@ through the enclave's gate:
685
728
 
686
729
  - it is refused once the execution is aborted, and counts toward `maxGlobalFunctionCalls`
687
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;
688
734
  - in the double VM (the default) it shares the operation rate limit
689
735
  (`doubleVm.parentValidation.maxOperationsPerSecond`) with tool calls;
690
736
  - its return value is sanitized like a tool result: the script receives a plain-data copy, and a
@@ -695,6 +741,47 @@ through the enclave's gate:
695
741
  The suspicious-sequence detectors only look at tool calls, so expose tools with `toolNamespaces` or
696
742
  `callTool()`, not as functions. The `worker_threads` adapter never passes functions into the sandbox.
697
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
+
698
785
  Inside arrays, Maps and Sets only plain data is allowed (primitives, plain objects, arrays, Maps, Sets,
699
786
  Dates, RegExps, typed arrays): the built-in methods of those collections (`forEach`, iteration, `get`)
700
787
  hand elements to the script directly, so a function (or an object with methods) stored there would be
@@ -742,6 +829,45 @@ file locations in the remaining lines are redacted.
742
829
  | `TOOL_ERROR` | Tool handler threw an error |
743
830
  | `RUNTIME_ERROR` | General runtime error in script |
744
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
+
745
871
  ## Defense-in-Depth Architecture
746
872
 
747
873
  ```
@@ -789,7 +915,7 @@ file locations in the remaining lines are redacted.
789
915
  ┌─────────────────────────────────────────────────────────────┐
790
916
  │ Layer 4: Runtime Sandbox │
791
917
  │ ├── Standard: Node.js vm (prototype isolation) │
792
- │ ├── Optional: Worker Pool (OS-level isolation) │
918
+ │ ├── Optional: Worker Pool (heap limit, hard stop) │
793
919
  │ │ ├── Dual-layer: worker thread + VM context │
794
920
  │ │ ├── Hard halt via worker.terminate() │
795
921
  │ │ └── Per-worker memory limits │
@@ -812,6 +938,80 @@ file locations in the remaining lines are redacted.
812
938
  └─────────────────────────────────────────────────────────────┘
813
939
  ```
814
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
+
815
1015
  ## API Reference
816
1016
 
817
1017
  ### Enclave Class