@enclave-vm/core 2.18.0 → 2.19.1

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/SECURITY-AUDIT.md CHANGED
@@ -5,9 +5,11 @@
5
5
  **Test Suite:** 1255 security tests
6
6
  **Pass Rate:** 1255/1255 passing (100%)
7
7
 
8
+ > **How to read this report.** It was written for v2.4.0 and is kept as a record of what was tested then. A pass rate describes the tests that existed, not the absence of weaknesses: several were found and fixed afterwards, and tests were added for each. Statements below that no longer described the implementation have been corrected in place and are marked _Updated_. The maintained index of security properties and their tests is `SECURITY-TESTS.md` in the repository root; the runtime behaviour is described in `README.md` ("What the Script's Realm Holds", "Worker Pool Adapter", "How `timeout` Is Enforced"). The test files it names are no longer in this repository: the security tests live in a private repository, mounted here as the git submodule `security-tests` (see `SECURITY-TESTS.md`).
9
+
8
10
  ## Executive Summary
9
11
 
10
- The enclave-vm package provides a **defense-in-depth security architecture** for safe AgentScript execution. The package successfully blocks **all major attack vectors** including code injection, prototype pollution, sandbox escapes, resource exhaustion attacks, **AI Scoring Gate** for semantic security analysis, and now includes the optional **Worker Pool Adapter** for OS-level memory isolation.
12
+ The enclave-vm package provides a **defense-in-depth security architecture** for safe AgentScript execution: static validation, a reduced realm, a membrane between the script and the host, sanitized results and enforced limits, with an **AI Scoring Gate** for semantic analysis and an optional **Worker Pool Adapter** that adds a heap limit per worker and a hard stop. Each layer is tested on its own, with the other layers switched off.
11
13
 
12
14
  ## Security Test Results
13
15
 
@@ -138,18 +140,20 @@ The enclave-vm package provides a **defense-in-depth security architecture** for
138
140
 
139
141
  **Verdict:** AI Scoring Gate successfully detects semantic attack patterns with 8 detection rules.
140
142
 
141
- ### ✅ Worker Pool Adapter - OS-Level Isolation (NEW - 100% passing)
143
+ ### ✅ Worker Pool Adapter (_Updated_)
142
144
 
143
- When enabled with `adapter: 'worker_threads'`, execution runs in isolated worker threads:
145
+ When enabled with `adapter: 'worker_threads'`, each script runs in a worker thread. A worker thread is not a sandbox and not process isolation (it has the Node.js API and shares the process), so inside the worker the script runs in the same sandbox as in process:
144
146
 
145
- - **Worker thread isolation**: ✅ ENFORCED (separate V8 isolate per worker)
146
- - **Memory limit enforcement**: ✅ ENFORCED (--max-old-space-size)
147
- - **Hard halt capability**: ✅ ENFORCED (worker.terminate())
148
- - **Dangerous global removal**: ✅ ENFORCED (parentPort, workerData removed)
147
+ - **Sandbox inside the worker**: ✅ the double VM by default (a single VM when the double VM is disabled)
148
+ - **Memory limit enforcement**: ✅ a heap limit per worker (`resourceLimits`); a worker that exceeds it is terminated and replaced. When the process runs with `--max-old-space-size`, which replaces the limit of every worker thread, the pool enforces it from the host. ⚠️ Not a guarantee that the host process survives memory exhaustion in a worker (README, "The Worker Heap Limit")
149
+ - **Pool size and shutdown**: ✅ `maxWorkers` holds under concurrent executions; a disposed pool leaves no worker thread or timer behind
150
+ - **Hard halt capability**: ✅ `worker.terminate()` for a script nothing else can interrupt
151
+ - **Tool calls**: ✅ answered by the host's tool bridge, as for in-process execution
152
+ - **Untrusted worker messages**: ✅ every message is checked against the protocol schema on the host
149
153
  - **Message flood protection**: ✅ ENFORCED (rate limiting)
150
154
  - **Prototype-safe deserialization**: ✅ ENFORCED (JSON-only, no structured clone)
151
155
 
152
- **Verdict:** Worker Pool Adapter provides OS-level memory isolation with dual-layer sandbox (worker + VM).
156
+ **Verdict:** The Worker Pool Adapter adds a heap limit and a stop that does not depend on the script, around the same sandbox as in-process execution. Tests: `enclave.worker-isolation` and `enclave.worker-resources` (ATK-WORKER).
153
157
 
154
158
  ### ✅ Side Channel Attack Prevention (Documented Limitations)
155
159
 
@@ -177,12 +181,12 @@ Since all these prerequisites are blocked in the Enclave sandbox, Spectre-class
177
181
 
178
182
  **Verdict:** Most inputs handled safely, parser limitations noted.
179
183
 
180
- ### ✅ Multiple Execution Isolation (Partial)
184
+ ### ✅ Multiple Execution Isolation (_Updated_)
181
185
 
182
- - **Cross-execution isolation**: ⚠️ VM contexts may share state
186
+ - **Cross-execution isolation**: ✅ ISOLATED. Every `enclave.run()` gets new VM contexts and discards them afterwards; no realm state is shared between executions (see "VM Context State Sharing" below)
183
187
  - **Cross-instance isolation**: ✅ ISOLATED (separate enclaves)
184
188
 
185
- **Verdict:** Instances are isolated, execution isolation needs verification.
189
+ **Verdict:** Instances and executions are isolated.
186
190
 
187
191
  ## Known Limitations
188
192
 
@@ -200,12 +204,9 @@ Since all these prerequisites are blocked in the Enclave sandbox, Spectre-class
200
204
  **Mitigation:** Consider sanitizing stack traces before returning.
201
205
  **Priority:** Low
202
206
 
203
- ### 3. VM Context State Sharing
207
+ ### 3. VM Context State Sharing (_Updated: no longer applies_)
204
208
 
205
- **Issue:** Multiple `enclave.run()` calls may share VM context state.
206
- **Impact:** Potential state leakage between executions in same enclave instance.
207
- **Mitigation:** Create new VM context for each execution or properly reset context.
208
- **Priority:** Medium
209
+ Every `enclave.run()` creates new VM contexts (parent and inner realm, or the single VM's context) and discards them afterwards. Nothing a script leaves in its realm is visible to a later execution. Scripts also run in strict mode, so a script can only write to its realm's global object when both static layers are switched off.
209
210
 
210
211
  ## Security Architecture
211
212
 
@@ -512,6 +513,19 @@ All security mechanisms are functioning correctly with zero failures or skipped
512
513
 
513
514
  ## Version History
514
515
 
516
+ - **Unreleased** (2026-11): Runtime hardening
517
+ - The script's realm holds only the globals its validator allows (`realmGlobals: 'allowlist'`, the default for validated AgentScript); no name resolves through a prototype of the global object (ATK-GLOBALS)
518
+ - Scripts run in strict mode at every security level (ATK-THIS)
519
+ - Regular expressions cannot be executed in a realm with the allowlist (ATK-RXRT)
520
+ - The parent realm's intrinsics are frozen while a script runs, and the host console object is no longer in it (ATK-PLOCK)
521
+ - The worker adapter runs the double VM inside the worker, enforces a heap limit per worker, validates worker messages and recovers from dead workers (ATK-WORKER)
522
+ - The size check of returned values no longer calls into the value and counts unpaired surrogates at their serialized size (ATK-SIZE)
523
+ - Compiled sandbox code is not shared between realms on V8 13.x (Node.js 24), where that could crash the process (ATK-ENGINE)
524
+ - Execution time no longer grows with the number of earlier scripts of the same length: the script is the first thing in the double VM bootstrap, and the bootstrap is ASCII whatever the script contains (ATK-ENGINE, Sustained Load in the performance suite)
525
+ - Nothing a script can reach is a raw object of another realm, checked by a crawler that runs inside the sandbox (ATK-REACH)
526
+ - With composite handles disabled, a handle written by the script is refused like the operator that would have built it (ATK-SIDECAR)
527
+ - Static rules: syntax allowlist, lexical scope analysis, write and reflection rules (see `SECURITY-TESTS.md`, layer 1)
528
+
515
529
  - **v2.4.0** (2026-01-06): Attack Prevention Test Suite
516
530
  - Added comprehensive attack prevention tests (71 new tests)
517
531
  - New test categories with consistent ATK-XXX naming scheme:
@@ -624,12 +638,6 @@ The enclave-vm uses a **three-layer security approach**:
624
638
 
625
639
  **Issue:** When user-provided objects were passed as globals without wrapping, prototype chain attacks could access real `process.env`.
626
640
 
627
- **Attack Pattern:**
628
-
629
- ```javascript
630
- process.env['__p' + 'roto__']['con' + 'structor']['con' + 'structor']('return process.env.PATH')();
631
- ```
632
-
633
641
  **Fix:** All custom globals are now recursively wrapped with SecureProxy in both vm-adapter.ts and parent-vm-bootstrap.ts.
634
642
 
635
643
  #### 2. Constructor Functions as Globals (KNOWN LIMITATION)
@@ -709,63 +717,63 @@ The critical finding is that **even when attackers access the Function construct
709
717
 
710
718
  ### Attack Categories Tested (50 Tests)
711
719
 
712
- | Category | Vectors | Security Level | Result |
713
- | -------------------------------------- | ------------------------------ | ----------------- | ------------------- |
714
- | **1. Primitive Constructor Chains** | | | |
715
- | String constructor chain | `"".constructor.constructor` | VM Isolation | ✅ Sandbox Function |
716
- | Number constructor chain | `(0).constructor.constructor` | VM Isolation | ✅ Sandbox Function |
717
- | Boolean constructor chain | `true.constructor.constructor` | VM Isolation | ✅ Sandbox Function |
718
- | Array constructor chain | `[].constructor.constructor` | VM Isolation | ✅ Sandbox Function |
719
- | Object constructor chain | `{}.constructor.constructor` | VM Isolation | ✅ Sandbox Function |
720
- | RegExp constructor chain | `/x/.constructor.constructor` | VM Isolation | ✅ Sandbox Function |
721
- | **2. Callback Injection Attacks** | | | |
722
- | Array.prototype.map | Callback `this.constructor` | VM Isolation | ✅ Sandbox Function |
723
- | Array.prototype.filter | `arguments.callee` access | PERMISSIVE allows | ⚠️ Non-strict mode |
724
- | Array.prototype.reduce | Accumulator constructor | VM Isolation | ✅ Sandbox context |
725
- | Array.prototype.sort | Comparator globals | VM Isolation | ✅ Sandbox context |
726
- | Array.prototype.forEach | Prototype access | VM Isolation | ✅ Sandbox context |
727
- | **3. Type Coercion Gadgets** | | | |
728
- | `valueOf` exploitation | Coercion callback | VM Isolation | ✅ Sandbox Function |
729
- | `toString` exploitation | Coercion callback | VM Isolation | ✅ Sandbox context |
730
- | `toJSON` exploitation | Stringify callback | VM Isolation | ✅ Sandbox context |
731
- | `Symbol.toPrimitive` | Custom coercion | AST Blocked | ✅ Symbol blocked |
732
- | **4. Function.prototype Exploitation** | | | |
733
- | `Function.prototype.call` | Context injection | VM Isolation | ✅ Sandbox global |
734
- | `Function.prototype.apply` | Arguments injection | VM Isolation | ✅ Sandbox context |
735
- | `Function.prototype.bind` | Context binding | VM Isolation | ✅ Sandbox context |
736
- | **5. Tagged Template Attacks** | | | |
737
- | `String.raw` exploitation | Constructor access | SecureProxy | ✅ Blocked |
738
- | Custom tag functions | `strings.raw.constructor` | VM Isolation | ✅ Sandbox Function |
739
- | **6. JSON Reviver/Replacer** | | | |
740
- | `JSON.parse` reviver | `this.constructor` access | VM Isolation | ✅ Sandbox Function |
741
- | `JSON.stringify` replacer | Value transformation | VM Isolation | ✅ Sandbox context |
742
- | **7. Implicit Coercion** | | | |
743
- | Addition operator | `+` triggers valueOf | VM Isolation | ✅ Sandbox context |
744
- | Comparison operator | `==` triggers valueOf | VM Isolation | ✅ Sandbox context |
745
- | Property key coercion | `obj[key]` triggers toString | VM Isolation | ✅ Sandbox context |
746
- | **8. Getter/Setter Attacks** | | | |
747
- | Getter exploitation | `get prop()` context | PERMISSIVE | ✅ Sandbox context |
748
- | Setter exploitation | `set prop()` context | PERMISSIVE | ✅ Sandbox context |
749
- | `Object.defineProperty` | Dynamic getter/setter | PERMISSIVE | ✅ Sandbox context |
750
- | **9. Prototype Pollution** | | | |
751
- | `Object.prototype` pollution | Host isolation | VM Isolation | ✅ Host protected |
752
- | `Array.prototype` pollution | Host isolation | VM Isolation | ✅ Host protected |
753
- | Constructor prototype pollution | Host isolation | VM Isolation | ✅ Host protected |
754
- | **10. Chained/Combined Attacks** | | | |
755
- | Coercion + Constructor chain | Multi-step attack | VM Isolation | ✅ Sandbox Function |
756
- | Callback + Constructor chain | Multi-step attack | VM Isolation | ✅ Sandbox Function |
757
- | JSON.parse + Constructor chain | Multi-step attack | VM Isolation | ✅ Sandbox Function |
720
+ | Category | Vectors | Security Level | Result |
721
+ | -------------------------------------- | ------------------------------ | -------------- | ------------------------------------- |
722
+ | **1. Primitive Constructor Chains** | | | |
723
+ | String constructor chain | `"".constructor.constructor` | VM Isolation | ✅ Sandbox Function |
724
+ | Number constructor chain | `(0).constructor.constructor` | VM Isolation | ✅ Sandbox Function |
725
+ | Boolean constructor chain | `true.constructor.constructor` | VM Isolation | ✅ Sandbox Function |
726
+ | Array constructor chain | `[].constructor.constructor` | VM Isolation | ✅ Sandbox Function |
727
+ | Object constructor chain | `{}.constructor.constructor` | VM Isolation | ✅ Sandbox Function |
728
+ | RegExp constructor chain | `/x/.constructor.constructor` | VM Isolation | ✅ Sandbox Function |
729
+ | **2. Callback Injection Attacks** | | | |
730
+ | Array.prototype.map | Callback `this.constructor` | VM Isolation | ✅ Sandbox Function |
731
+ | Array.prototype.filter | `arguments.callee` access | Strict mode | ✅ Blocked at every level (_Updated_) |
732
+ | Array.prototype.reduce | Accumulator constructor | VM Isolation | ✅ Sandbox context |
733
+ | Array.prototype.sort | Comparator globals | VM Isolation | ✅ Sandbox context |
734
+ | Array.prototype.forEach | Prototype access | VM Isolation | ✅ Sandbox context |
735
+ | **3. Type Coercion Gadgets** | | | |
736
+ | `valueOf` exploitation | Coercion callback | VM Isolation | ✅ Sandbox Function |
737
+ | `toString` exploitation | Coercion callback | VM Isolation | ✅ Sandbox context |
738
+ | `toJSON` exploitation | Stringify callback | VM Isolation | ✅ Sandbox context |
739
+ | `Symbol.toPrimitive` | Custom coercion | AST Blocked | ✅ Symbol blocked |
740
+ | **4. Function.prototype Exploitation** | | | |
741
+ | `Function.prototype.call` | Context injection | VM Isolation | ✅ Sandbox global |
742
+ | `Function.prototype.apply` | Arguments injection | VM Isolation | ✅ Sandbox context |
743
+ | `Function.prototype.bind` | Context binding | VM Isolation | ✅ Sandbox context |
744
+ | **5. Tagged Template Attacks** | | | |
745
+ | `String.raw` exploitation | Constructor access | SecureProxy | ✅ Blocked |
746
+ | Custom tag functions | `strings.raw.constructor` | VM Isolation | ✅ Sandbox Function |
747
+ | **6. JSON Reviver/Replacer** | | | |
748
+ | `JSON.parse` reviver | `this.constructor` access | VM Isolation | ✅ Sandbox Function |
749
+ | `JSON.stringify` replacer | Value transformation | VM Isolation | ✅ Sandbox context |
750
+ | **7. Implicit Coercion** | | | |
751
+ | Addition operator | `+` triggers valueOf | VM Isolation | ✅ Sandbox context |
752
+ | Comparison operator | `==` triggers valueOf | VM Isolation | ✅ Sandbox context |
753
+ | Property key coercion | `obj[key]` triggers toString | VM Isolation | ✅ Sandbox context |
754
+ | **8. Getter/Setter Attacks** | | | |
755
+ | Getter exploitation | `get prop()` context | PERMISSIVE | ✅ Sandbox context |
756
+ | Setter exploitation | `set prop()` context | PERMISSIVE | ✅ Sandbox context |
757
+ | `Object.defineProperty` | Dynamic getter/setter | PERMISSIVE | ✅ Sandbox context |
758
+ | **9. Prototype Pollution** | | | |
759
+ | `Object.prototype` pollution | Host isolation | VM Isolation | ✅ Host protected |
760
+ | `Array.prototype` pollution | Host isolation | VM Isolation | ✅ Host protected |
761
+ | Constructor prototype pollution | Host isolation | VM Isolation | ✅ Host protected |
762
+ | **10. Chained/Combined Attacks** | | | |
763
+ | Coercion + Constructor chain | Multi-step attack | VM Isolation | ✅ Sandbox Function |
764
+ | Callback + Constructor chain | Multi-step attack | VM Isolation | ✅ Sandbox Function |
765
+ | JSON.parse + Constructor chain | Multi-step attack | VM Isolation | ✅ Sandbox Function |
758
766
 
759
767
  ### Security Mode Differences
760
768
 
761
- | Feature | AgentScript (Default) | PERMISSIVE |
762
- | ------------------------------------- | --------------------- | ------------------ |
763
- | Function expressions | ❌ Blocked | ✅ Allowed |
764
- | Getter/Setter syntax | ❌ Blocked | ✅ Allowed |
765
- | `arguments.callee` | ❌ Blocked (strict) | ✅ Available |
766
- | `function.call(null)` | Returns undefined | Returns globalThis |
767
- | Constructor access on wrapped globals | ❌ Blocked | ✅ Allowed |
768
- | Prototype pollution in sandbox | ✅ Host isolated | ✅ Host isolated |
769
+ | Feature | AgentScript (Default) | PERMISSIVE |
770
+ | ------------------------------------- | --------------------- | ------------------- |
771
+ | Function expressions | ❌ Blocked | ✅ Allowed |
772
+ | Getter/Setter syntax | ❌ Blocked | ✅ Allowed |
773
+ | `arguments.callee` | ❌ Blocked (strict) | ❌ Blocked (strict) |
774
+ | `function.call(null)` | `this` is `null` | `this` is `null` |
775
+ | Constructor access on wrapped globals | ❌ Blocked | ✅ Allowed |
776
+ | Prototype pollution in sandbox | ✅ Host isolated | ✅ Host isolated |
769
777
 
770
778
  ### Key Takeaways
771
779
 
@@ -773,7 +781,7 @@ The critical finding is that **even when attackers access the Function construct
773
781
 
774
782
  2. **AgentScript preset provides strong protection** - Blocks function expressions, getters/setters, and dangerous patterns statically
775
783
 
776
- 3. **PERMISSIVE mode trades security for flexibility** - Allows more JavaScript features but still maintains host isolation
784
+ 3. **PERMISSIVE mode trades security for flexibility** - Allows more JavaScript features but still maintains host isolation. (_Updated_: scripts run in strict mode at every level, so `this` is never the realm's global object and `arguments.callee` is never available.)
777
785
 
778
786
  4. **Constructor access through primitives works but is contained** - The constructed functions run in sandbox context with no host access
779
787
 
@@ -2,14 +2,50 @@ import type { ExecutionContext, ExecutionResult, SandboxAdapter } from '../types
2
2
  export interface InterpreterAdapterOptions {
3
3
  /** Override the instruction budget (default 5,000,000). */
4
4
  maxSteps?: number;
5
- /** Override the max interpreter call depth (default 256). */
5
+ /**
6
+ * How deep the calls of a script may nest (default 256). Counted along each chain of calls: a
7
+ * callback is a call of the function that invokes it, and the tasks of a `parallel` batch each
8
+ * continue the chain that started the batch, so a batch does not add up.
9
+ */
6
10
  maxCallDepth?: number;
11
+ /**
12
+ * How many calls of an execution may be unfinished at once, running or waiting, over all its
13
+ * chains (default 4096). It bounds what the waiting calls of nested `parallel` batches hold.
14
+ */
15
+ maxPendingCalls?: number;
16
+ /**
17
+ * The most a script may allocate, in bytes, as the interpreter estimates it (default 64 MB).
18
+ * An execution's own `memoryLimit` applies when it is lower.
19
+ */
20
+ maxAllocationBytes?: number;
7
21
  }
8
22
  export declare class InterpreterAdapter implements SandboxAdapter {
9
23
  private readonly options;
10
24
  constructor(options?: InterpreterAdapterOptions);
11
25
  execute<T = unknown>(code: string, context: ExecutionContext): Promise<ExecutionResult<T>>;
12
26
  dispose(): void;
27
+ /**
28
+ * What transformed AgentScript refers to beyond the standard globals: the helpers the
29
+ * transformer emits, and the console, tool namespaces and custom globals of this execution.
30
+ */
31
+ private runtimeGlobals;
32
+ /**
33
+ * `callTool(name, args, options)` for the script, through the host tool bridge: the request
34
+ * and the response cross as JSON, so the handler never receives a value of the script and the
35
+ * script never receives an object of the handler.
36
+ */
37
+ private createCallTool;
38
+ /**
39
+ * The value a script returned, as the caller gets it: plain host data, like from every other
40
+ * adapter. A function, or a result that would serialize to more than the memory limit, fails
41
+ * the execution.
42
+ */
43
+ private succeed;
13
44
  private stats;
45
+ /**
46
+ * What ended an execution, as a name and a message. A script can throw any value: a string is
47
+ * the message, an object contributes its `name`, `message` and `code` when they are strings.
48
+ */
49
+ private describe;
14
50
  private fail;
15
51
  }
@@ -21,8 +21,10 @@ export interface WorkerPoolConfig {
21
21
  */
22
22
  maxWorkers: number;
23
23
  /**
24
- * Memory limit per worker in bytes
25
- * Workers exceeding this limit will be recycled
24
+ * Heap limit of each worker in bytes (its old generation); 0 for none.
25
+ * Enforced by the engine, or by the pool when the process runs with `--max-old-space-size`,
26
+ * which replaces the heap limit of every worker thread. A worker over its limit is terminated
27
+ * and replaced.
26
28
  * @default 128 * 1024 * 1024 (128MB)
27
29
  */
28
30
  memoryLimitPerWorker: number;
@@ -40,13 +40,22 @@ export interface MemoryMonitorStats {
40
40
  memoryExceededCount: number;
41
41
  /** Number of check failures */
42
42
  checkFailureCount: number;
43
- /** Peak memory usage observed (bytes) */
43
+ /** Most that one worker held in any report (its heap plus its external memory, in bytes) */
44
44
  peakMemoryBytes: number;
45
- /** Average memory usage (bytes) */
45
+ /** Average of what a worker held over all reports (bytes) */
46
46
  avgMemoryBytes: number;
47
47
  /** Total samples collected */
48
48
  totalSamples: number;
49
49
  }
50
+ /**
51
+ * What a worker itself holds, from its memory report: its heap plus its external memory.
52
+ *
53
+ * Not `rss`: inside a worker thread `process.memoryUsage().rss` is the resident size of the
54
+ * whole process. Compared with a per-worker limit, it made every worker of a host larger than
55
+ * the limit look over it, at every check: idle workers were recycled, and an execution that was
56
+ * running (waiting for a tool call, say) lost its worker.
57
+ */
58
+ export declare function workerMemoryBytes(usage: ResourceUsage): number;
50
59
  /**
51
60
  * Monitors worker memory usage and enforces limits
52
61
  */
@@ -98,9 +107,14 @@ export declare class MemoryMonitor extends EventEmitter {
98
107
  * Get current memory usage summary
99
108
  */
100
109
  getCurrentUsageSummary(): {
110
+ /** Sum of the `rss` every worker reported: each report is the size of the WHOLE process */
101
111
  totalRss: number;
102
112
  avgRss: number;
103
113
  maxRss: number;
114
+ /** Sum of what the workers themselves hold (heap plus external memory) */
115
+ totalWorkerBytes: number;
116
+ avgWorkerBytes: number;
117
+ maxWorkerBytes: number;
104
118
  slotCount: number;
105
119
  };
106
120
  }
@@ -11,6 +11,9 @@ import { type NormalizedToolNamespace } from '@enclave-vm/ast';
11
11
  import type { ResourceUsage } from './config';
12
12
  import type { SpecialResultValue } from './result-encoding';
13
13
  import type { ConsoleLevel } from '../../console-handler';
14
+ import type { SerializableSuspiciousPattern } from '../../double-vm/types';
15
+ import type { SecureProxyLevelConfig } from '../../types';
16
+ import type { ReferenceConfig } from '../../sidecar/reference-config';
14
17
  /**
15
18
  * Serialized error format for cross-thread communication
16
19
  * Errors are serialized to prevent prototype pollution
@@ -24,6 +27,33 @@ export interface SerializedError {
24
27
  code?: string;
25
28
  /** Sanitized stack trace (only if sanitizeStackTraces is false) */
26
29
  stack?: string;
30
+ /** Structured details of the error (JSON data), as `ExecutionError.data` */
31
+ data?: Record<string, unknown>;
32
+ }
33
+ /** A regular expression as it crosses the thread boundary. */
34
+ export interface SerializedPattern {
35
+ source: string;
36
+ flags: string;
37
+ }
38
+ /**
39
+ * The double VM configuration as it crosses the thread boundary: regular expressions as source
40
+ * and flags, custom suspicious patterns as serialized detectors.
41
+ */
42
+ export interface SerializedDoubleVmConfig {
43
+ /** false runs the script in a single VM inside the worker (not recommended) */
44
+ enabled: boolean;
45
+ parentTimeoutBuffer: number;
46
+ parentValidation: {
47
+ validateOperationNames: boolean;
48
+ allowedOperationPattern?: SerializedPattern;
49
+ blockedOperationPatterns?: SerializedPattern[];
50
+ maxOperationsPerSecond: number;
51
+ blockSuspiciousSequences: boolean;
52
+ rapidEnumerationThreshold: number;
53
+ rapidEnumerationOverrides: Record<string, number>;
54
+ /** The host's custom suspicious patterns (the default ones are added inside the worker) */
55
+ suspiciousPatterns: SerializableSuspiciousPattern[];
56
+ };
27
57
  }
28
58
  /**
29
59
  * Execution statistics from the worker
@@ -78,6 +108,22 @@ export interface SerializedConfig {
78
108
  * security level, and each console message carries one formatted line as its only argument
79
109
  */
80
110
  hasConsoleHandler?: boolean;
111
+ /** Memory limit for the in-sandbox allocation tracking, in bytes (0 = no tracking) */
112
+ memoryLimit?: number;
113
+ /** Maximum size of a tool request or response, in bytes */
114
+ toolBridgeMaxPayloadBytes?: number;
115
+ /** Secure proxy (membrane) configuration of the enclave */
116
+ secureProxyConfig?: SecureProxyLevelConfig;
117
+ /** Cap on calls into host functions passed in `globals` */
118
+ maxGlobalFunctionCalls?: number;
119
+ /** Global names the script's realm may hold (`realmGlobals: 'allowlist'`); absent otherwise */
120
+ realmGlobalAllowlist?: string[];
121
+ /** Reference (sidecar) configuration: the worker needs it to treat reference ids correctly */
122
+ referenceConfig?: ReferenceConfig;
123
+ /**
124
+ * How the script is isolated inside the worker. Absent means the double VM with its defaults.
125
+ */
126
+ doubleVm?: SerializedDoubleVmConfig;
81
127
  }
82
128
  /**
83
129
  * Execute code in the worker
@@ -100,16 +146,12 @@ export interface ToolResponseMessage {
100
146
  requestId: string;
101
147
  /** Tool call identifier */
102
148
  callId: string;
103
- /** Tool result (if successful) */
104
- result?: unknown;
105
- /** Error (if failed) */
106
- error?: SerializedError;
107
149
  /**
108
- * Set when the error is a failure of the tool itself (its handler threw or rejected), as
109
- * opposed to the host refusing the call. A script's `callTool(..., { throwOnError: false })`
110
- * receives only such failures as a result object.
150
+ * The host's answer in the string tool-bridge format (see ../../tool-bridge): the sanitized
151
+ * result, or an error that says whether the tool itself failed or the host refused the call.
152
+ * It is produced by the same bridge as for an in-process execution.
111
153
  */
112
- toolError?: boolean;
154
+ response: string;
113
155
  }
114
156
  /**
115
157
  * Request memory usage report from worker
@@ -233,6 +275,7 @@ export declare const executionResultMessageSchema: z.ZodObject<{
233
275
  message: z.ZodString;
234
276
  code: z.ZodOptional<z.ZodString>;
235
277
  stack: z.ZodOptional<z.ZodString>;
278
+ data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
236
279
  }, z.core.$strip>>;
237
280
  stats: z.ZodObject<{
238
281
  duration: z.ZodNumber;
@@ -308,6 +351,7 @@ export declare const workerToMainMessageSchema: z.ZodDiscriminatedUnion<[z.ZodOb
308
351
  message: z.ZodString;
309
352
  code: z.ZodOptional<z.ZodString>;
310
353
  stack: z.ZodOptional<z.ZodString>;
354
+ data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
311
355
  }, z.core.$strip>>;
312
356
  stats: z.ZodObject<{
313
357
  duration: z.ZodNumber;
@@ -8,25 +8,41 @@
8
8
  */
9
9
  import type { SandboxAdapter, ExecutionContext, ExecutionResult, SecurityLevel } from '../../types';
10
10
  import type { WorkerPoolConfig, WorkerPoolMetrics } from './config';
11
+ import type { DoubleVmConfig } from '../../double-vm/types';
11
12
  /**
12
13
  * Worker Pool Adapter
13
14
  *
14
15
  * Provides a worker thread-based sandbox adapter with:
15
- * - OS-level memory isolation
16
+ * - A heap limit per worker, enforced by the engine (by the pool when a heap flag of the process
17
+ * overrides it, see WorkerSlot)
16
18
  * - Hard halt capability via worker.terminate()
17
19
  * - Pool management with min/max workers
18
20
  * - Memory monitoring and enforcement
19
21
  * - Rate limiting for message flood protection
22
+ *
23
+ * Inside the worker the script runs in the same sandbox as an in-process execution: the double VM
24
+ * by default (or a single VM when the double VM is disabled). The worker thread is an additional
25
+ * layer around that sandbox, not a replacement for it. Tool calls come back to this thread and
26
+ * go through the same tool bridge as in-process tool calls.
20
27
  */
21
28
  export declare class WorkerPoolAdapter implements SandboxAdapter {
22
29
  private readonly config;
23
30
  private readonly securityLevel;
31
+ private readonly doubleVm;
24
32
  private readonly slots;
33
+ /**
34
+ * Workers that are starting. A worker is in `slots` only once it is ready, so everything that
35
+ * compares the pool with its size has to count these as well: a burst of executions that each
36
+ * found "room" started a worker each, however small `maxWorkers` was.
37
+ */
38
+ private startingWorkers;
25
39
  private readonly executionQueue;
26
40
  private readonly memoryMonitor;
27
41
  private readonly rateLimiter;
28
42
  private disposed;
29
43
  private initialized;
44
+ /** The initialization in progress: concurrent callers share it */
45
+ private initialization;
30
46
  private readonly boundMemoryExceededHandler;
31
47
  private _totalExecutions;
32
48
  private _successfulExecutions;
@@ -34,12 +50,22 @@ export declare class WorkerPoolAdapter implements SandboxAdapter {
34
50
  private _timeoutExecutions;
35
51
  private _workerRecycles;
36
52
  private _forcedTerminations;
37
- constructor(config?: Partial<WorkerPoolConfig>, securityLevel?: SecurityLevel);
53
+ private _heapLimitKills;
54
+ /** Workers already counted as a memory kill (by the memory monitor or as a heap-limit kill) */
55
+ private readonly memoryKilledSlots;
56
+ /**
57
+ * @param config Worker pool configuration
58
+ * @param securityLevel Security level of the enclave
59
+ * @param doubleVmConfig How the script is isolated inside each worker. Default: the double VM
60
+ * with its default validation.
61
+ */
62
+ constructor(config?: Partial<WorkerPoolConfig>, securityLevel?: SecurityLevel, doubleVmConfig?: DoubleVmConfig);
38
63
  /**
39
64
  * Initialize the worker pool
40
65
  * Must be called before execute()
41
66
  */
42
67
  initialize(): Promise<void>;
68
+ private warmUp;
43
69
  /**
44
70
  * Execute code in a worker
45
71
  */
@@ -48,8 +74,25 @@ export declare class WorkerPoolAdapter implements SandboxAdapter {
48
74
  * Dispose the adapter and all workers
49
75
  */
50
76
  dispose(): void;
77
+ /** Workers the pool has, or is about to have */
78
+ private get workerCount();
79
+ /**
80
+ * Start a worker and add it to the pool.
81
+ *
82
+ * @param executionId When given, the new worker is acquired for this execution before anyone
83
+ * else can see it idle (the caller asked for a worker because none was free).
84
+ */
51
85
  private createAndAddSlot;
86
+ /** One worker ended at its memory limit is one memory kill, whichever check saw it */
87
+ private countHeapLimitKill;
52
88
  private acquireSlot;
89
+ /**
90
+ * Take a worker that is gone (terminated by the watchdog, by the memory monitor, or by itself)
91
+ * out of the pool, and let a queued execution proceed: it finds the pool below its size and
92
+ * gets a new worker. A dead slot that stayed in the pool would count against `maxWorkers`
93
+ * forever, and with one worker every later execution would wait in the queue until it timed out.
94
+ */
95
+ private removeDeadSlot;
53
96
  private releaseSlot;
54
97
  private handleSlotRecycling;
55
98
  private handleMemoryExceeded;
@@ -1,11 +1,21 @@
1
1
  /**
2
2
  * Worker Script
3
3
  *
4
- * This script runs inside a worker thread and provides a dual-layer sandbox:
5
- * 1. Worker thread isolation (OS-level)
6
- * 2. VM context isolation (prototype isolation)
4
+ * Runs inside a worker thread of the pool.
7
5
  *
8
- * Tool calls are proxied to the main thread via message passing.
6
+ * What a worker adds to an execution: a heap limit that the engine enforces, and a way for the
7
+ * host to stop the execution whatever the script is doing (`worker.terminate()`).
8
+ *
9
+ * What it does NOT add is a sandbox. A worker thread has the whole Node.js API (`process`,
10
+ * `require`, the file system), and a `vm` context created here from this thread's own objects
11
+ * hands the script this thread's `Function` constructor one property read away. So the script
12
+ * runs here in the SAME sandbox as an in-process execution: the double VM (parent realm with the
13
+ * membrane and the tool gate, inner realm for the script), or a single VM when the double VM is
14
+ * disabled. The worker is a layer around that sandbox.
15
+ *
16
+ * Tool calls leave the sandbox through the string tool bridge, are sent to the host thread as
17
+ * messages, and are answered there by the host's tool bridge (see ../../tool-bridge): the same
18
+ * checks, sidecar handling and sanitization as for an in-process tool call.
9
19
  *
10
20
  * @packageDocumentation
11
21
  */