@enclave-vm/core 2.20.0 → 2.20.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/README.md +416 -671
- package/SECURITY-AUDIT.md +1 -1
- package/package.json +3 -3
- package/src/adapters/worker-pool/package.json +3 -3
- package/types.d.ts +1 -1
package/README.md
CHANGED
|
@@ -1,79 +1,75 @@
|
|
|
1
1
|
# @enclave-vm/core
|
|
2
2
|
|
|
3
|
+
A sandbox for running AgentScript, the JavaScript subset that language models write to call tools, in Node.js. It validates a script, transforms it, runs it in a reduced realm behind a membrane with limits on time, iterations, tool calls and memory, and returns a plain-data result.
|
|
4
|
+
|
|
3
5
|
[](https://www.npmjs.com/package/@enclave-vm/core)
|
|
4
|
-
[](LICENSE)
|
|
5
|
-
[](https://www.typescriptlang.org/)
|
|
6
|
+
[](https://github.com/agentfront/enclave/blob/main/LICENSE)
|
|
6
7
|
|
|
7
|
-
|
|
8
|
+
It is the runtime of [Enclave](https://github.com/agentfront/enclave). The static checks come from [`@enclave-vm/ast`](https://www.npmjs.com/package/@enclave-vm/ast); [`@enclave-vm/broker`](https://www.npmjs.com/package/@enclave-vm/broker) runs this package behind HTTP routes; [`@enclave-vm/browser`](https://www.npmjs.com/package/@enclave-vm/browser) is the counterpart for the browser.
|
|
8
9
|
|
|
9
|
-
|
|
10
|
+
## How the Layers Fit Together
|
|
10
11
|
|
|
11
|
-
|
|
12
|
+
A script goes through these steps, in this order:
|
|
12
13
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
14
|
+
1. **Pre-scanner** (`@enclave-vm/ast`): the source text, before anything parses it: size, lines, string literals, nesting, regex literals, bidirectional, invisible and look-alike characters.
|
|
15
|
+
2. **AgentScript transform** (`transformAgentScript` of `@enclave-vm/ast`): the script is wrapped in `async function __ag_main()`, `callTool` becomes `__safe_callTool`, and loops get iteration checks. The validator receives the script as this step returns it.
|
|
16
|
+
3. **AST validation** (`@enclave-vm/ast`): the AgentScript preset by default, an allowlist of syntax, globals and property keys.
|
|
17
|
+
4. **Transformation after validation**: the deadline is checked in every function and loop body, concatenation is counted, and every computed key that is not a literal is checked at run time (`guardComputedMemberKeys`). What a static rule cannot decide, such as a property name the script builds while it runs, is decided here.
|
|
18
|
+
5. **Scoring gate** (optional, off by default): a heuristic risk score from the script's tool calls.
|
|
19
|
+
6. **Runtime sandbox**: by default a double VM in this process: the script runs in an inner realm that holds only the allowed globals, inside a parent realm that checks every tool call. Optionally the whole sandbox runs in a worker thread with a heap limit and a hard stop.
|
|
20
|
+
7. **Output**: the returned value is copied into plain data, errors become bounded text without a stack from the sandbox, and oversized values are refused.
|
|
19
21
|
|
|
20
|
-
|
|
22
|
+
### What it does not do
|
|
21
23
|
|
|
22
|
-
|
|
24
|
+
- **It is not process isolation.** The default sandbox runs in your process and thread. A script that computes is stopped by checks in its own code; a single built-in call that does all its work natively is not interrupted (see [How `timeout` Is Enforced](#how-timeout-is-enforced)). For a stop the script cannot influence, use the [worker pool](#worker-pool-adapter); for tenants that must not share a process, or a host that must survive whatever a script allocates, run one enclave per process or container.
|
|
25
|
+
- **`memoryLimit` is the enclave's own accounting**, not a limit of the engine's heap (see [What `memoryLimit` Counts](#what-memorylimit-counts)).
|
|
26
|
+
- **It does not stop your `toolHandler`.** A tool call it stops waiting for keeps running in the host.
|
|
27
|
+
- **The scoring gate is a heuristic.** A low score is not evidence that a script is safe.
|
|
23
28
|
|
|
24
|
-
|
|
25
|
-
- **Worker Pool Adapter**: Optional worker threads around the sandbox, with a heap limit per worker and a hard stop
|
|
26
|
-
- **Safe Tool Calls**: Secure `callTool()` execution with iteration and call limits
|
|
27
|
-
- **Reference Sidecar**: Handle large data without embedding it in the script
|
|
28
|
-
- **Configurable Security Levels**: From STRICT to PERMISSIVE based on trust level
|
|
29
|
-
- **Resource Limits**: Timeout, memory accounting, iteration limits, and tool call limits
|
|
30
|
-
- **AI Scoring Gate**: Optional heuristic risk score for a script, from its tool calls and argument names
|
|
31
|
-
- **Zero Dependencies on Vulnerable Packages**: Uses Node.js native `vm` module
|
|
29
|
+
The invariants of the sandbox by layer, and the ones that are still open, are listed in [SECURITY-TESTS.md](https://github.com/agentfront/enclave/blob/main/SECURITY-TESTS.md). [SECURITY-AUDIT.md](https://github.com/agentfront/enclave/blob/main/libs/core/SECURITY-AUDIT.md) is the audit report written for v2.4.0, kept as a record.
|
|
32
30
|
|
|
33
31
|
## Installation
|
|
34
32
|
|
|
35
33
|
```bash
|
|
36
34
|
npm install @enclave-vm/core
|
|
37
|
-
# or
|
|
38
|
-
yarn add @enclave-vm/core
|
|
39
|
-
# or
|
|
40
|
-
pnpm add @enclave-vm/core
|
|
41
35
|
```
|
|
42
36
|
|
|
37
|
+
`@huggingface/transformers` and `vectoriadb` are optional peer dependencies, used only by the `local-llm` scorer of the [scoring gate](#ai-scoring-gate).
|
|
38
|
+
|
|
43
39
|
## Quick Start
|
|
44
40
|
|
|
45
41
|
```typescript
|
|
46
42
|
import { Enclave } from '@enclave-vm/core';
|
|
47
43
|
|
|
48
|
-
// Create enclave with a tool handler
|
|
49
44
|
const enclave = new Enclave({
|
|
50
45
|
timeout: 5000,
|
|
51
46
|
maxToolCalls: 10,
|
|
52
47
|
maxIterations: 1000,
|
|
53
48
|
toolHandler: async (toolName, args) => {
|
|
54
|
-
|
|
55
|
-
return {
|
|
49
|
+
if (toolName === 'getUser') return { id: args.id, name: 'Alice' };
|
|
50
|
+
if (toolName === 'getOrders') return [{ id: 1 }, { id: 2 }];
|
|
51
|
+
throw new Error(`Unknown tool: ${toolName}`);
|
|
56
52
|
},
|
|
57
53
|
});
|
|
58
54
|
|
|
59
|
-
// Execute AgentScript code
|
|
60
55
|
const result = await enclave.run(`
|
|
61
56
|
const user = await callTool('getUser', { id: 123 });
|
|
62
57
|
const orders = await callTool('getOrders', { userId: user.id });
|
|
63
|
-
return { user, orderCount: orders.length };
|
|
58
|
+
return { user: user.name, orderCount: orders.length };
|
|
64
59
|
`);
|
|
65
60
|
|
|
66
61
|
if (result.success) {
|
|
67
|
-
console.log(
|
|
62
|
+
console.log(result.value); // { user: 'Alice', orderCount: 2 }
|
|
68
63
|
} else {
|
|
69
|
-
console.error(
|
|
64
|
+
console.error(result.error);
|
|
70
65
|
}
|
|
71
66
|
|
|
72
|
-
// Always dispose when done
|
|
73
67
|
enclave.dispose();
|
|
74
68
|
```
|
|
75
69
|
|
|
76
|
-
|
|
70
|
+
`runAgentScript(code, options)` creates an enclave, runs one script and disposes of it.
|
|
71
|
+
|
|
72
|
+
### Portable AgentScript Runner
|
|
77
73
|
|
|
78
74
|
Use the Worker entry when the host cannot load Node's `vm` or worker-thread modules. `AgentScriptRunner` pre-scans raw source, transforms AgentScript, validates the AST, and then runs it in the bounded interpreter. `InterpreterAdapter` is a lower-level adapter and does not perform those validation steps by itself.
|
|
79
75
|
|
|
@@ -107,26 +103,30 @@ The runner supports Node and Cloudflare Workers with `nodejs_compat`. Tool and h
|
|
|
107
103
|
```typescript
|
|
108
104
|
interface CreateEnclaveOptions {
|
|
109
105
|
// Execution limits
|
|
110
|
-
timeout?: number; // Execution timeout in ms (default:
|
|
106
|
+
timeout?: number; // Execution timeout in ms (default: by security level, 30000 at STANDARD)
|
|
111
107
|
toolCallGraceMs?: number; // How long a tool call in progress at the timeout may still take (default: same as timeout)
|
|
112
|
-
maxToolCalls?: number; // Maximum tool calls allowed (default:
|
|
113
|
-
maxIterations?: number; // Maximum loop iterations (default:
|
|
108
|
+
maxToolCalls?: number; // Maximum tool calls allowed (default: by security level, 100 at STANDARD)
|
|
109
|
+
maxIterations?: number; // Maximum loop iterations (default: by security level, 10000 at STANDARD)
|
|
114
110
|
memoryLimit?: number; // Memory limit in bytes, as the enclave counts it (default: 1048576, 1 MB; 0: off)
|
|
115
111
|
|
|
116
112
|
// Security
|
|
117
113
|
securityLevel?: SecurityLevel; // 'STRICT' | 'SECURE' | 'STANDARD' | 'PERMISSIVE' (default: 'STANDARD')
|
|
118
114
|
preset?: AstPreset; // AST validation preset (default: 'agentscript')
|
|
115
|
+
preScan?: { preset?; config? }; // Pre-scanner preset or single limits (see "What the Pre-Scanner Checks")
|
|
119
116
|
validate?: boolean; // Enable AST validation (default: true)
|
|
120
117
|
transform?: boolean; // Enable code transformation (default: true)
|
|
121
118
|
realmGlobals?: 'allowlist' | 'security-level'; // What exists in the script's realm (see "What the Script's Realm Holds")
|
|
119
|
+
secureProxyConfig?: Partial<SecureProxyLevelConfig>; // Override the membrane settings of the level
|
|
122
120
|
|
|
123
121
|
// Where the sandbox runs
|
|
124
|
-
adapter?: 'vm' | 'worker_threads'; // In this process (default) or in a pool of worker threads (
|
|
122
|
+
adapter?: 'vm' | 'worker_threads'; // In this process (default) or in a pool of worker threads ('isolated-vm' is reserved, not implemented)
|
|
125
123
|
workerPoolConfig?: Partial<WorkerPoolConfig>;
|
|
124
|
+
sandboxAdapter?: SandboxAdapter; // An adapter of your own
|
|
126
125
|
|
|
127
126
|
// Tool execution
|
|
128
127
|
toolHandler?: ToolHandler; // Function to execute tool calls
|
|
129
128
|
toolNamespaces?: ToolNamespaces; // Expose tools as `ns.method(args)` (see "Tool Namespaces")
|
|
129
|
+
toolBridge?: { mode?: 'string' | 'direct'; maxPayloadBytes?: number; acknowledgeInsecureDirect?: boolean }; // default: 'string', 5 MB, false
|
|
130
130
|
|
|
131
131
|
// Console
|
|
132
132
|
consoleHandler?: ConsoleHandler; // Receive console calls as (level, message) instead of the host console (see "Console Handler")
|
|
@@ -137,21 +137,26 @@ interface CreateEnclaveOptions {
|
|
|
137
137
|
globals?: Record<string, unknown>; // Additional globals for the VM
|
|
138
138
|
allowFunctionsInGlobals?: boolean; // Allow functions in globals (default: false)
|
|
139
139
|
maxGlobalFunctionCalls?: number; // Cap on calls into functions from globals (default: 10 × maxToolCalls)
|
|
140
|
+
allowBuiltins?: boolean; // default: false
|
|
140
141
|
|
|
141
|
-
//
|
|
142
|
+
// Results and errors
|
|
142
143
|
sanitizeStackTraces?: boolean; // Redact paths/frames in every returned error (default: by security level)
|
|
144
|
+
maxSanitizeDepth?: number; // Deepest returned value (default: by security level)
|
|
145
|
+
maxSanitizeProperties?: number; // Most properties in a returned value (default: by security level)
|
|
143
146
|
|
|
144
147
|
// Sidecar (large data handling)
|
|
145
148
|
sidecar?: ReferenceSidecarOptions;
|
|
146
149
|
|
|
147
150
|
// Scoring gate
|
|
148
|
-
scoringGate?: ScoringGateConfig; // See "AI Scoring Gate"
|
|
151
|
+
scoringGate?: ScoringGateConfig; // See "AI Scoring Gate"
|
|
149
152
|
|
|
150
153
|
// Double VM security layer
|
|
151
|
-
doubleVm?: PartialDoubleVmConfig; // See "Double VM
|
|
154
|
+
doubleVm?: PartialDoubleVmConfig; // See "Double VM"
|
|
152
155
|
}
|
|
153
156
|
```
|
|
154
157
|
|
|
158
|
+
`toolBridge.mode: 'direct'` throws at construction unless `acknowledgeInsecureDirect: true` is set as well.
|
|
159
|
+
|
|
155
160
|
### Option Values
|
|
156
161
|
|
|
157
162
|
The constructor checks its options and throws a `TypeError` for a value outside the documented type or range:
|
|
@@ -177,16 +182,26 @@ The constructor checks its options and throws a `TypeError` for a value outside
|
|
|
177
182
|
|
|
178
183
|
The portable interpreter additionally charges copied host-function results and tool responses by their serialized size to the cumulative allocation budget.
|
|
179
184
|
|
|
180
|
-
A script that goes over the limit fails with `MEMORY_LIMIT_EXCEEDED`, and a script cannot switch the accounting off or reset it. With a limit set, a returned value whose serialized size is estimated above the limit (above 50 MB where the limit is larger) fails with `SERIALIZATION_LIMIT_EXCEEDED`. The limit is an estimate: where the host must survive whatever a script allocates, use the [worker pool](#worker-pool-adapter
|
|
185
|
+
A script that goes over the limit fails with `MEMORY_LIMIT_EXCEEDED`, and a script cannot switch the accounting off or reset it. With a limit set, a returned value whose serialized size is estimated above the limit (above 50 MB where the limit is larger) fails with `SERIALIZATION_LIMIT_EXCEEDED`. The limit is an estimate: where the host must survive whatever a script allocates, use the [worker pool](#worker-pool-adapter), whose workers have a heap limit of the engine, or a child process or container with a memory limit of the operating system.
|
|
181
186
|
|
|
182
|
-
|
|
187
|
+
## Security Levels
|
|
183
188
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
| `STRICT`
|
|
187
|
-
|
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
189
|
+
The security level sets the defaults of the limits, the globals a script may use, and how the membrane answers a refused property.
|
|
190
|
+
|
|
191
|
+
| Setting | `STRICT` | `SECURE` | `STANDARD` (default) | `PERMISSIVE` |
|
|
192
|
+
| -------------------------------------------- | -------- | -------- | -------------------- | ------------------- |
|
|
193
|
+
| `timeout` | 5 s | 15 s | 30 s | 60 s |
|
|
194
|
+
| `maxIterations` | 1,000 | 5,000 | 10,000 | 100,000 |
|
|
195
|
+
| `maxToolCalls` | 10 | 50 | 100 | 1,000 |
|
|
196
|
+
| `maxConsoleCalls` | 100 | 500 | 1,000 | 10,000 |
|
|
197
|
+
| `maxConsoleOutputBytes` | 64 KB | 256 KB | 1 MB | 10 MB |
|
|
198
|
+
| `maxSanitizeDepth` / `maxSanitizeProperties` | 5 / 50 | 10 / 100 | 20 / 500 | 50 / 1,000 |
|
|
199
|
+
| `sanitizeStackTraces` | on | on | off | off |
|
|
200
|
+
| `allowFunctionsInGlobals` | off | off | off | on |
|
|
201
|
+
| A refused `constructor` | throws | throws | throws | allowed |
|
|
202
|
+
| Other refused properties | throw | throw | throw | read as `undefined` |
|
|
203
|
+
|
|
204
|
+
The values are exported as `SECURITY_LEVEL_CONFIGS`.
|
|
190
205
|
|
|
191
206
|
```typescript
|
|
192
207
|
import { Enclave } from '@enclave-vm/core';
|
|
@@ -201,53 +216,34 @@ const enclave = new Enclave({
|
|
|
201
216
|
|
|
202
217
|
### Allowed Globals by Security Level
|
|
203
218
|
|
|
204
|
-
Both AST validation and runtime sandbox
|
|
205
|
-
|
|
206
|
-
| Global
|
|
207
|
-
|
|
|
208
|
-
|
|
|
209
|
-
| `
|
|
210
|
-
|
|
|
211
|
-
| `
|
|
212
|
-
| `
|
|
213
|
-
| `
|
|
214
|
-
| `Object` | ✅ | ✅ | ✅ | ✅ |
|
|
215
|
-
| `String` | ✅ | ✅ | ✅ | ✅ |
|
|
216
|
-
| `Number` | ✅ | ✅ | ✅ | ✅ |
|
|
217
|
-
| `Date` | ✅ | ✅ | ✅ | ✅ |
|
|
218
|
-
| **Constants** | | | | |
|
|
219
|
-
| `undefined` | ✅ | ✅ | ✅ | ✅ |
|
|
220
|
-
| `NaN` | ✅ | ✅ | ✅ | ✅ |
|
|
221
|
-
| `Infinity` | ✅ | ✅ | ✅ | ✅ |
|
|
222
|
-
| **Utility Functions** | | | | |
|
|
223
|
-
| `parseInt` | ❌ | ✅ | ✅ | ✅ |
|
|
224
|
-
| `parseFloat` | ❌ | ✅ | ✅ | ✅ |
|
|
225
|
-
| `isNaN` | ❌ | ✅ | ✅ | ✅ |
|
|
226
|
-
| `isFinite` | ❌ | ✅ | ✅ | ✅ |
|
|
227
|
-
| `encodeURI` | ❌ | ✅ | ✅ | ✅ |
|
|
228
|
-
| `decodeURI` | ❌ | ✅ | ✅ | ✅ |
|
|
229
|
-
| `encodeURIComponent` | ❌ | ✅ | ✅ | ✅ |
|
|
230
|
-
| `decodeURIComponent` | ❌ | ✅ | ✅ | ✅ |
|
|
231
|
-
| **Debugging** | | | | |
|
|
232
|
-
| `console` | ❌ | ❌ | ❌ | ✅ |
|
|
219
|
+
Both AST validation and the runtime sandbox use the same allowed globals:
|
|
220
|
+
|
|
221
|
+
| Global | STRICT | SECURE | STANDARD | PERMISSIVE |
|
|
222
|
+
| -------------------------------------------------------------------- | ------ | ------ | -------- | ---------- |
|
|
223
|
+
| `callTool` | Yes | Yes | Yes | Yes |
|
|
224
|
+
| `Math`, `JSON`, `Array`, `Object`, `String`, `Number`, `Date` | Yes | Yes | Yes | Yes |
|
|
225
|
+
| `undefined`, `NaN`, `Infinity` | Yes | Yes | Yes | Yes |
|
|
226
|
+
| `parseInt`, `parseFloat`, `isNaN`, `isFinite` | No | Yes | Yes | Yes |
|
|
227
|
+
| `encodeURI`, `decodeURI`, `encodeURIComponent`, `decodeURIComponent` | No | Yes | Yes | Yes |
|
|
228
|
+
| `console` | No | No | No | Yes |
|
|
233
229
|
|
|
234
230
|
With a `consoleHandler`, `console` is allowed at every level (see [Console Handler](#console-handler)).
|
|
235
231
|
|
|
236
|
-
###
|
|
232
|
+
### Refused Globals
|
|
237
233
|
|
|
238
|
-
|
|
234
|
+
With the default `agentscript` preset, every global that is not in the table above is refused, at every security level. Among them:
|
|
239
235
|
|
|
240
|
-
| Category |
|
|
236
|
+
| Category | Globals |
|
|
241
237
|
| ------------------ | ------------------------------------------------------------------------------ |
|
|
242
238
|
| **Code Execution** | `eval`, `Function`, `AsyncFunction`, `GeneratorFunction` |
|
|
243
239
|
| **System Access** | `process`, `require`, `module`, `exports`, `__dirname`, `__filename`, `Buffer` |
|
|
244
240
|
| **Global Objects** | `window`, `globalThis`, `self`, `global`, `this` |
|
|
245
241
|
| **Prototype** | `constructor`, `__proto__`, `prototype` |
|
|
246
242
|
| **Reflection** | `Proxy`, `Reflect` |
|
|
247
|
-
| **Async
|
|
243
|
+
| **Async** | `Promise`, `setTimeout`, `setInterval`, `setImmediate`, `queueMicrotask` |
|
|
248
244
|
| **Network** | `fetch`, `XMLHttpRequest`, `WebSocket` |
|
|
249
245
|
| **Workers** | `Worker`, `SharedWorker`, `ServiceWorker` |
|
|
250
|
-
| **
|
|
246
|
+
| **Collections** | `Map`, `Set`, `WeakMap`, `WeakSet`, `WeakRef`, `FinalizationRegistry` |
|
|
251
247
|
| **Binary/Wasm** | `WebAssembly`, `ArrayBuffer`, `SharedArrayBuffer`, `Atomics` |
|
|
252
248
|
| **Error Types** | `Error`, `TypeError`, `ReferenceError`, `SyntaxError`, `RangeError` |
|
|
253
249
|
| **Symbols/Regex** | `Symbol`, `RegExp` |
|
|
@@ -261,6 +257,87 @@ The tables above are what the validator accepts. The realm the script runs in ag
|
|
|
261
257
|
- **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.
|
|
262
258
|
- **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.
|
|
263
259
|
|
|
260
|
+
### AST Presets
|
|
261
|
+
|
|
262
|
+
The `preset` option selects the **AST validation**. With `transform` on (the default), it is applied to the script as `transformAgentScript` returns it (the `__ag_main` wrapper, `__safe_callTool`, the loop checks), and before the transforms that follow validation (see [How the Layers Fit Together](#how-the-layers-fit-together)). It is separate from `securityLevel`, which sets the runtime limits and, for the `agentscript` and `babel` presets, the allowed globals.
|
|
263
|
+
|
|
264
|
+
| Preset | Description | Custom globals in validation |
|
|
265
|
+
| ------------- | ------------------------------------------------------------------------------ | ---------------------------- |
|
|
266
|
+
| `agentscript` | Default. The AgentScript allowlist | Yes |
|
|
267
|
+
| `babel` | AgentScript plus `Babel.transform()` for TSX/JSX (see `createRestrictedBabel`) | Yes |
|
|
268
|
+
| `strict` | The STRICT preset of `@enclave-vm/ast` | No |
|
|
269
|
+
| `secure` | The SECURE preset | No |
|
|
270
|
+
| `standard` | The STANDARD preset | No |
|
|
271
|
+
| `permissive` | The PERMISSIVE preset | No |
|
|
272
|
+
|
|
273
|
+
Only the `agentscript` and `babel` presets take your custom globals into their allowlist; the other presets use their own fixed rule sets, and custom globals are still available at run time. With these four presets the realm keeps the standard globals that the level does not remove (`realmGlobals: 'security-level'`), so choose them only for code you trust more than generated code.
|
|
274
|
+
|
|
275
|
+
```typescript
|
|
276
|
+
import { Enclave } from '@enclave-vm/core';
|
|
277
|
+
|
|
278
|
+
const enclave = new Enclave({
|
|
279
|
+
preset: 'agentscript', // AST validation preset (default)
|
|
280
|
+
securityLevel: 'STRICT', // Runtime security level
|
|
281
|
+
toolHandler: async (name, args) => {
|
|
282
|
+
/* ... */
|
|
283
|
+
},
|
|
284
|
+
});
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
## Tools
|
|
288
|
+
|
|
289
|
+
### Tool Handler
|
|
290
|
+
|
|
291
|
+
```typescript
|
|
292
|
+
type ToolHandler = (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
Called for every `callTool()` and `toolNamespaces` method call that passes the enclave's checks. Arguments reach it as copied plain data, and its result is sanitized before the script sees it. The script's `callTool` options (`CallToolOptions`) are applied inside the sandbox and are not passed to the handler.
|
|
296
|
+
|
|
297
|
+
### Tool Namespaces
|
|
298
|
+
|
|
299
|
+
Expose tools to scripts as namespaced functions instead of (or alongside) `callTool()`:
|
|
300
|
+
|
|
301
|
+
```typescript
|
|
302
|
+
const enclave = new Enclave({
|
|
303
|
+
toolHandler: async (name, args) => callMyTool(name, args),
|
|
304
|
+
toolNamespaces: {
|
|
305
|
+
mail: ['list', 'send'], // mail.list(args) calls the tool 'mail.list'
|
|
306
|
+
users: { get: 'users:get' }, // users.get(args) calls the tool 'users:get'
|
|
307
|
+
},
|
|
308
|
+
});
|
|
309
|
+
|
|
310
|
+
const result = await enclave.run(`
|
|
311
|
+
const inbox = await mail.list({ unread: true });
|
|
312
|
+
const sender = await users.get({ id: inbox[0].from });
|
|
313
|
+
return sender.name;
|
|
314
|
+
`);
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
A namespace method call **is** a `callTool()` call: `mail.list(args, options)` behaves exactly like `callTool('mail.list', args, options)`. It counts toward `maxToolCalls`, goes through the double VM's rate limit, operation-name and suspicious-sequence checks, its result is sanitized, and it reaches your `toolHandler`. `args` defaults to `{}`. Each namespace is a frozen, null-prototype object created inside the sandbox, so aliasing (`const m = mail; m.list()`) and destructuring work and no host object is exposed.
|
|
318
|
+
|
|
319
|
+
The constructor throws a `TypeError` (`Invalid toolNamespaces: ...`) for names that are not identifiers, prototype keys (`__proto__`, `constructor`, `prototype`), names starting with `__`, reserved words and sandbox globals used as namespaces (`callTool`, `Math`, `console`, ...), identifiers the AgentScript validator refuses (`process`, `fetch`, ...), namespaces that collide with a custom global, duplicated methods, and tool names every adapter cannot carry (empty, over 256 characters, or outside letters, digits, `:`, `.`, `_` and `-` starting with a letter, including a generated `<namespace>.<method>` name).
|
|
320
|
+
|
|
321
|
+
Prefer namespaces over exposing tools as functions in `globals`: functions in `globals` are gated and sanitized (see [Custom Globals](#custom-globals)), but the suspicious-sequence detectors only see tool calls.
|
|
322
|
+
|
|
323
|
+
### callTool Options
|
|
324
|
+
|
|
325
|
+
Scripts can pass options as the third argument of `callTool` (or the second argument of a namespace method):
|
|
326
|
+
|
|
327
|
+
```javascript
|
|
328
|
+
const r = await callTool('users:get', { id }, { throwOnError: false });
|
|
329
|
+
if (r.success) {
|
|
330
|
+
return r.data;
|
|
331
|
+
}
|
|
332
|
+
return { failed: r.error.message }; // r.error: { name, message, code?, toolName }
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
| Option | Default | Description |
|
|
336
|
+
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
337
|
+
| `throwOnError` | `true` | `false`: resolve to `{ success: true, data }` or, when the tool fails, `{ success: false, error }` instead of throwing |
|
|
338
|
+
|
|
339
|
+
Only failures of the tool itself (the handler threw or rejected, or its result could not be delivered) are returned this way; the error object is plain data with no stack. Refusals by the enclave (abort, `maxToolCalls`, rate limit, operation-name and suspicious-sequence checks, invalid arguments) always throw. Options are applied inside the sandbox and are not passed to the `toolHandler`.
|
|
340
|
+
|
|
264
341
|
### Console Handler
|
|
265
342
|
|
|
266
343
|
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:
|
|
@@ -282,43 +359,159 @@ await enclave.run(`console.info('users', { count: 2 }); return 1;`); // logger.i
|
|
|
282
359
|
- 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.
|
|
283
360
|
- Combining a `consoleHandler` with a `console` entry in `globals` throws a `TypeError`.
|
|
284
361
|
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
The `preset` option controls **AST-level validation** - what JavaScript constructs are allowed before code transformation. This is separate from `securityLevel` which controls runtime security.
|
|
362
|
+
## Custom Globals
|
|
288
363
|
|
|
289
|
-
|
|
290
|
-
| ------------- | --------------------------------------------- | ---------------- |
|
|
291
|
-
| `agentscript` | Default. Safe subset for LLM-generated code | ✅ Supported |
|
|
292
|
-
| `strict` | Maximum restrictions, blocks most JS features | ❌ Not supported |
|
|
293
|
-
| `secure` | High security with essential features | ❌ Not supported |
|
|
294
|
-
| `standard` | Balanced security for general use | ❌ Not supported |
|
|
295
|
-
| `permissive` | Minimal AST restrictions | ❌ Not supported |
|
|
364
|
+
You can provide custom globals to the VM:
|
|
296
365
|
|
|
297
366
|
```typescript
|
|
298
|
-
import { Enclave } from '@enclave-vm/core';
|
|
299
|
-
|
|
300
367
|
const enclave = new Enclave({
|
|
301
|
-
|
|
302
|
-
|
|
368
|
+
globals: {
|
|
369
|
+
config: { apiUrl: 'https://api.example.com' },
|
|
370
|
+
helpers: {
|
|
371
|
+
formatDate: (date: Date) => date.toISOString(),
|
|
372
|
+
},
|
|
373
|
+
},
|
|
374
|
+
allowFunctionsInGlobals: true, // Required when globals contain functions
|
|
303
375
|
toolHandler: async (name, args) => {
|
|
304
376
|
/* ... */
|
|
305
377
|
},
|
|
306
378
|
});
|
|
379
|
+
|
|
380
|
+
const result = await enclave.run(`
|
|
381
|
+
const url = config.apiUrl;
|
|
382
|
+
const formatted = helpers.formatDate(new Date());
|
|
383
|
+
return { url, formatted };
|
|
384
|
+
`);
|
|
307
385
|
```
|
|
308
386
|
|
|
309
|
-
|
|
387
|
+
Set `allowFunctionsInGlobals: true` only when you intentionally provide functions: a function in `globals` is code of your host that a script can call, and what it can reach through its closure is yours to judge.
|
|
388
|
+
|
|
389
|
+
Every call from the script into a function from `globals` (including functions nested in objects) goes through the enclave's gate:
|
|
390
|
+
|
|
391
|
+
- it is refused once the execution is aborted, and counts toward `maxGlobalFunctionCalls` (default: 10 × `maxToolCalls`), not toward `maxToolCalls`;
|
|
392
|
+
- its arguments are copied into plain host data first, the way tool arguments are: the function receives null-prototype objects, arrays, primitives and `Date`s, never a live script value, and a call that passes a function or a symbol is refused. The script's `this` is not passed either;
|
|
393
|
+
- in the double VM (the default) it shares the operation rate limit (`doubleVm.parentValidation.maxOperationsPerSecond`) with tool calls;
|
|
394
|
+
- its return value is sanitized like a tool result: the script receives a plain-data copy, and a value containing functions or symbols, or exceeding the sanitize depth/size limits, is refused;
|
|
395
|
+
- an error it throws reaches the script as a plain error without the host stack;
|
|
396
|
+
- calling it with `new` is refused.
|
|
397
|
+
|
|
398
|
+
The suspicious-sequence detectors only look at tool calls, so expose tools with `toolNamespaces` or `callTool()`, not as functions. The `worker_threads` adapter never passes functions into the sandbox.
|
|
399
|
+
|
|
400
|
+
Values passed in `globals` are **read-only** inside the sandbox. They are the host's own objects, shared by every execution of the enclave, so a script cannot assign to them, add or delete properties, freeze them, or call a built-in method that changes its receiver (`push`, `sort`, `Map.prototype.set`, `Date.prototype.setTime`, ...): the attempt throws, or is ignored at `PERMISSIVE`. Reading works as before, and an array returned by a built-in method (`map`, `filter`, `slice`, ...) is the script's own copy, which it can sort or extend. To let scripts keep state, return it from a tool instead.
|
|
401
|
+
|
|
402
|
+
A custom global cannot be named `Object`: the sandbox provides its own. The constructor throws.
|
|
403
|
+
|
|
404
|
+
<details>
|
|
405
|
+
<summary>What the constructor accepts in <code>globals</code>, and further details</summary>
|
|
310
406
|
|
|
311
|
-
|
|
312
|
-
| ------------------------ | ---------------------------- | --------------------------- |
|
|
313
|
-
| When applied | Before execution | During execution |
|
|
314
|
-
| What it controls | JavaScript syntax/constructs | Resource limits, timeouts |
|
|
315
|
-
| Function expressions | Blocked in `agentscript` | N/A |
|
|
316
|
-
| Getter/setter syntax | Blocked in `agentscript` | N/A |
|
|
317
|
-
| Custom globals whitelist | Only `agentscript` preset | Always available at runtime |
|
|
407
|
+
A function is not started when the script calls it with the stack nearly full (less than 128 KB left): the call throws a `RangeError` in the script, and the function has not run. The check only decides whether a function starts: it is never started halfway. It says nothing about a function that did start. An async function that is still in progress when `toolCallGraceMs` is over is left behind like a tool call, and `run()` ends without its result reaching the script.
|
|
318
408
|
|
|
319
|
-
|
|
409
|
+
The validation of `globals` judges what a script can reach through a value, not only what the value has itself. The methods of a class are functions in `globals`: an instance of a class with methods needs `allowFunctionsInGlobals: true`, and so does a function in a property that is not enumerable or is keyed by a symbol. Code that runs when a property is read is refused whatever is allowed: a getter or setter, on the value or on its class, and a Proxy of an object. That includes a `Buffer` (pass a `Uint8Array`) and an `Error` object (pass its message). A function passed as a global is judged as a function; what hangs on it is not looked at. An instance of a class without methods or accessors is plain data and is accepted, unless `secureProxyConfig.blockConstructor` is off (as at `PERMISSIVE`): then a script can read its `constructor`, which is a function.
|
|
320
410
|
|
|
321
|
-
|
|
411
|
+
A **regular expression** passed in `globals` can be read (`source`, `flags`, `global`, ...) but not run: `test`, `exec` and its use as the pattern of `match`, `matchAll`, `replace`, `search` or `split` throw, at every security level. A match would run the host's pattern on a text the script chooses, outside the rules that apply to the script's own expressions, and with the `g` or `y` flag it writes `lastIndex` on the host's object. Pass a function that does the matching, or let the script build the expression from `source` and `flags` where the preset allows `RegExp`. The same goes for `match`, `matchAll` and `search` on a `String` object (`new String(...)`) passed in `globals`; a plain string is not affected.
|
|
412
|
+
|
|
413
|
+
With the single VM, an object of the script's own that a host built-in hands back to a callback (the object a script gave `reduce` to collect into) stays the script's and stays writable. The runtime recognises it by its prototype chain, which ends in the sandbox's `Object.prototype`. An object without a prototype (`Object.create(null)`) carries nothing that says who made it and is treated as the host's, so it arrives read-only in the callback: collect into `{}` or an array.
|
|
414
|
+
|
|
415
|
+
Inside arrays, Maps and Sets only plain data is allowed (primitives, plain objects, arrays, Maps, Sets, Dates, RegExps, typed arrays): the built-in methods of those collections (`forEach`, iteration, `get`) hand elements to the script directly, so a function (or an object with methods) stored there would be called without the gate. The constructor refuses it with an error naming the path, e.g. `Custom global "cfg" contains a function inside a collection at hooks.0.run`. Every own entry counts there, enumerable or not, and Map and Set subclasses are refused inside collections. Arrays anywhere in `globals` must be plain arrays (no Proxy, no custom prototype), since those can hide entries from validation. Promises, WeakMaps, iterators and generators are refused anywhere in `globals`, since their contents cannot be validated.
|
|
416
|
+
|
|
417
|
+
</details>
|
|
418
|
+
|
|
419
|
+
## Execution Result
|
|
420
|
+
|
|
421
|
+
```typescript
|
|
422
|
+
interface ExecutionResult<T> {
|
|
423
|
+
success: boolean;
|
|
424
|
+
value?: T; // Result when success is true
|
|
425
|
+
error?: {
|
|
426
|
+
message: string;
|
|
427
|
+
name: string;
|
|
428
|
+
code?: string; // Error code (e.g., 'VALIDATION_ERROR'; see "Error Codes")
|
|
429
|
+
stack?: string; // Only for errors made outside the sandbox
|
|
430
|
+
data?: Record<string, unknown>;
|
|
431
|
+
};
|
|
432
|
+
stats: {
|
|
433
|
+
duration: number; // Execution time in ms
|
|
434
|
+
toolCallCount: number; // Number of tool calls made
|
|
435
|
+
iterationCount: number; // Number of loop iterations
|
|
436
|
+
memoryUsage?: number; // Peak tracked memory in bytes (when memoryLimit is set)
|
|
437
|
+
startTime: number;
|
|
438
|
+
endTime: number;
|
|
439
|
+
};
|
|
440
|
+
scoringResult?: ScoringGateResult; // When a scoring gate evaluated the script
|
|
441
|
+
}
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
**`result.error` is plain, bounded text.** Whatever a script threw, `name` and `message` are strings: `name` of at most 256 characters, `message` of at most 16,384. A thrown string is the message; a thrown `null`, `undefined` or other primitive is named in the message (`The script threw null`); an object without a string `message` is reported as `The script threw a value that is not an error`. An object a script makes to look like the memory-limit error is not reported as one. The message of a validation failure is cut to 500 characters per issue and 32,768 in total; `error.data.issues` holds the issues.
|
|
445
|
+
|
|
446
|
+
**Errors made inside the sandbox have no `stack`.** No sandbox realm captures a stack trace, so `error.stack` is `undefined` for the script and absent from `result.error` for what a script throws and for what the runtime raises inside the sandbox (a limit, a failed tool call). This holds for the double VM and the single VM, in process and in a worker. Errors the host makes outside a sandbox realm (an adapter that fails, a worker pool error, an error of the `InterpreterAdapter`, which has no realm of its own) keep their stack. With `sanitizeStackTraces` on (the default for `STRICT` and `SECURE`), such a stack is sanitized, whichever stage raised the error: stack frames become `at [REDACTED]` and paths, URLs and file locations in the remaining lines are redacted.
|
|
447
|
+
|
|
448
|
+
### Error Codes
|
|
449
|
+
|
|
450
|
+
| Code | Description |
|
|
451
|
+
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
452
|
+
| `VALIDATION_ERROR` | AST validation failed, or the script is too large or not a string |
|
|
453
|
+
| `SECURITY_VIOLATION` | The script contains a dynamic import (also with `validate: false`), or a blocked operation was recorded at `STRICT` or `SECURE` |
|
|
454
|
+
| `SCORING_BLOCKED` | Refused by the scoring gate |
|
|
455
|
+
| `DOUBLE_VM_EXECUTION_ERROR` | The script failed in the double VM (the default): an error it did not catch, a failed tool call, the tool-call or iteration limit, a timeout |
|
|
456
|
+
| `VM_EXECUTION_ERROR` | The same with `doubleVm: { enabled: false }`; with either VM, the timeout of a script that was only waiting |
|
|
457
|
+
| `MEMORY_LIMIT_EXCEEDED` | `memoryLimit` exceeded |
|
|
458
|
+
| `SERIALIZATION_LIMIT_EXCEEDED` | The returned value is larger than the memory limit allows |
|
|
459
|
+
| `EXECUTION_ERROR` | The adapter itself failed; with the worker pool `error.name` is the pool's error (`WorkerTimeoutError`, ...) |
|
|
460
|
+
| `ENCLAVE_ERROR` | Any other failure outside the sandbox, such as a script with a syntax error |
|
|
461
|
+
| `EXECUTION_TIMEOUT`, `STEP_LIMIT_EXCEEDED` | The timeout and the step budget of the `InterpreterAdapter` |
|
|
462
|
+
|
|
463
|
+
For the limits `error.message` says which one ended the script: `Script execution timed out ...`, `Maximum iteration limit exceeded ...`, `Maximum tool call limit exceeded ...`.
|
|
464
|
+
|
|
465
|
+
### How `timeout` Is Enforced
|
|
466
|
+
|
|
467
|
+
- The time is the script's: the clock starts when the sandbox is ready to run it. Validation, the transform and the creation of the sandbox adapter (once per enclave; with the worker pool that starts the worker threads) come before it. Waiting for a free worker counts, and a script whose time has passed while it waited is not started: `run()` returns `ExecutionAbortedError`.
|
|
468
|
+
- Until the script's first `await`, Node's `vm` interrupts it at the deadline.
|
|
469
|
+
- After that, the script checks the clock itself: the transformer inserts a check at the start of every function and loop body and in front of a parameter default, so synchronous work, recursion and promise chains that never yield are stopped at the deadline as well. A script that catches the timeout error cannot enter another function or loop iteration. The deadline is cooperative: it is looked at between the steps of the script's own code.
|
|
470
|
+
- A tool call in progress at the deadline is not cut off, and its result is delivered. This does not hold with `adapter: 'worker_threads'`: there the deadline fails a tool call still in progress with `Execution aborted` (`EXECUTION_ABORTED`) at once, without waiting for `toolCallGraceMs`, and the handler's later result is not delivered to the script. From then on the next tool call or call into a host function is refused with `Execution aborted`. The same holds for an async function from `globals`.
|
|
471
|
+
- That wait has an end: `toolCallGraceMs` after the deadline the execution ends with the timeout error, whatever is still in progress, and `error.data.pendingHostCalls` says how many calls were left running. The default is the value of `timeout`, so `run()` takes at most twice `timeout`. `0` ends every execution at the deadline; `Infinity` waits for the handler however long it takes, as versions up to 2.18 did (a handler that never settles then keeps `run()` from settling).
|
|
472
|
+
- When `run()` has returned, for whatever reason, the script is finished for the host as well. What it left behind (a tool call it did not await, with a `then` on it) can no longer call a tool, a function from `globals` or the console, and it ends within a bounded number of steps: its next checks throw `Script execution has ended`.
|
|
473
|
+
- A script that only waits is ended as well. Waiting takes no code: a thenable that never calls back (`return { then: () => 0 }`) is enough, and nothing runs that could look at the clock. So the enclave keeps count of what the host has in flight for the script (tool calls, async functions from `globals`), and from the deadline on `run()` returns the timeout error as soon as that count is zero. A sandbox has no timers and no I/O, so nothing else could wake the script. (With `adapter: 'worker_threads'` the pool ends such a script like a busy one: with its worker, five seconds after the deadline.)
|
|
474
|
+
- Not covered: a single built-in call that does all its work natively, and a script run with `transform: false`. The engine finishes one call into a built-in before the next check, so `timeout` does not bound its duration. And the enclave cannot stop your `toolHandler`: a call it stops waiting for keeps running in the host, so a tool that changes something should be safe to repeat, or have a time limit of its own. For a stop the script cannot influence, use `adapter: 'worker_threads'`: a script that is still running five seconds after its timeout is terminated with its worker (see [Worker Pool Adapter](#worker-pool-adapter)). A process you can terminate does the same for everything else that runs in it.
|
|
475
|
+
|
|
476
|
+
## What the Pre-Scanner Checks
|
|
477
|
+
|
|
478
|
+
`Enclave` runs the pre-scanner on the script as it was written, before anything parses it, with the pre-scanner preset named like the AST `preset`:
|
|
479
|
+
|
|
480
|
+
| AST preset | Pre-scanner preset | Script | Lines | String literals | Regex literals | Bidirectional controls | Invisible characters |
|
|
481
|
+
| ----------------------- | ------------------ | ---------------------------------------------------- | ------------------------------- | --------------------------- | ------------------------------------------- | ---------------------- | -------------------- |
|
|
482
|
+
| `agentscript` (default) | `agentscript` | 100 KB, nesting 20 | 1,000 of at most 2,000 chars | 10 KB each, 100 KB in total | refused | refused | refused |
|
|
483
|
+
| `strict` | `strict` | 500 KB, nesting 30 | 2,000 of at most 5,000 chars | 50 KB each, 500 KB in total | 10 of at most 100 chars, analyzed for ReDoS | refused | refused |
|
|
484
|
+
| `secure` | `secure` | 1 MB, nesting 40 | 5,000 of at most 8,000 chars | 100 KB each, 1 MB in total | 20 of at most 200 chars, analyzed | refused | allowed |
|
|
485
|
+
| `standard`, `babel` | `standard` | 5 MB, nesting 50 | 10,000 of at most 10,000 chars | 500 KB each, 5 MB in total | 30 of at most 500 chars, analyzed | allowed | allowed |
|
|
486
|
+
| `permissive` | `permissive` | 5,242,880 chars (the enclave's maximum), nesting 100 | 100,000 of at most 50,000 chars | 1 MB each, 10 MB in total | allowed | allowed | allowed |
|
|
487
|
+
|
|
488
|
+
Every preset except `permissive` also refuses a null byte, more consecutive operators than its limit, and one of a fixed list of letters that look like ASCII letters (Cyrillic and Greek look-alikes of `a`, `c`, `e`, `o`, `p`, `x`, `y`, and the full-width `a` and `e`), anywhere in the text.
|
|
489
|
+
|
|
490
|
+
The `preScan` option picks another preset or changes single limits of the one in force; the pre-scanner's own absolute maximums still hold:
|
|
491
|
+
|
|
492
|
+
```typescript
|
|
493
|
+
// The limits enclaves had before 2.19.2, whatever the AST preset
|
|
494
|
+
const enclave = new Enclave({ preScan: { preset: 'standard' } });
|
|
495
|
+
|
|
496
|
+
// The agentscript pre-scanner with room for larger string literals (for the reference sidecar, say).
|
|
497
|
+
// The limit on one literal and the limit on all literals together are separate: raise both.
|
|
498
|
+
const enclave = new Enclave({
|
|
499
|
+
preScan: {
|
|
500
|
+
config: {
|
|
501
|
+
maxInputSize: 1024 * 1024,
|
|
502
|
+
maxLineLength: 100000,
|
|
503
|
+
maxStringLength: 512 * 1024,
|
|
504
|
+
maxTotalStringContent: 1024 * 1024,
|
|
505
|
+
},
|
|
506
|
+
},
|
|
507
|
+
});
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
A line is at most 100,000 characters under any configuration (the pre-scanner's absolute maximum), so a literal longer than that has to be a template literal over several lines.
|
|
511
|
+
|
|
512
|
+
With `validate: false` the pre-scanner does not run; a script is limited to 5,242,880 characters in any case.
|
|
513
|
+
|
|
514
|
+
## Worker Pool Adapter
|
|
322
515
|
|
|
323
516
|
`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:
|
|
324
517
|
|
|
@@ -350,7 +543,7 @@ A worker thread is **not a sandbox by itself**: it has the whole Node.js API and
|
|
|
350
543
|
- **Console output** without a `consoleHandler` is printed by the host with a `[Worker]` prefix.
|
|
351
544
|
- **`toolBridge.mode: 'direct'`** does not apply: requests and responses always cross as strings.
|
|
352
545
|
|
|
353
|
-
### When to Use Worker Pool
|
|
546
|
+
### When to Use the Worker Pool
|
|
354
547
|
|
|
355
548
|
| Scenario | Recommendation |
|
|
356
549
|
| ------------------------------------- | ------------------------------------ |
|
|
@@ -360,22 +553,14 @@ A worker thread is **not a sandbox by itself**: it has the whole Node.js API and
|
|
|
360
553
|
| Tenants that must not share a process | One enclave per process or container |
|
|
361
554
|
| A host that must survive any script | One enclave per process or container |
|
|
362
555
|
|
|
363
|
-
### Worker Pool
|
|
364
|
-
|
|
365
|
-
| Level | minWorkers | maxWorkers | memoryLimit | messagesPerSec |
|
|
366
|
-
| ---------- | ---------- | ---------- | ----------- | -------------- |
|
|
367
|
-
| STRICT | 2 | 4 | 64MB | 100 |
|
|
368
|
-
| SECURE | 2 | 8 | 128MB | 500 |
|
|
369
|
-
| STANDARD | 2 | 16 | 256MB | 1000 |
|
|
370
|
-
| PERMISSIVE | 4 | 32 | 512MB | 5000 |
|
|
371
|
-
|
|
372
|
-
### Worker Pool Configuration Options
|
|
556
|
+
### Worker Pool Configuration
|
|
373
557
|
|
|
374
558
|
| Option | Default | Description |
|
|
375
559
|
| ------------------------ | --------- | ---------------------------------------------------------------- |
|
|
376
560
|
| `minWorkers` | 2 | Minimum warm workers |
|
|
377
561
|
| `maxWorkers` | CPU count | Maximum concurrent workers |
|
|
378
562
|
| `memoryLimitPerWorker` | 128MB | Heap limit of each worker (its old generation); 0: none |
|
|
563
|
+
| `memoryCheckIntervalMs` | 1000 | Interval of the memory monitor |
|
|
379
564
|
| `maxMessagesPerSecond` | 1000 | Messages a worker may send per second while it runs an execution |
|
|
380
565
|
| `maxPendingToolCalls` | 100 | Tool calls one execution may have in flight |
|
|
381
566
|
| `maxMessageSizeBytes` | 16MB | Largest single message a worker may send |
|
|
@@ -384,7 +569,14 @@ A worker thread is **not a sandbox by itself**: it has the whole Node.js API and
|
|
|
384
569
|
| `queueTimeoutMs` | 30000 | Longest wait for a free worker |
|
|
385
570
|
| `idleTimeoutMs` | 30000 | Time before idle worker release |
|
|
386
571
|
|
|
387
|
-
These are the defaults of `WorkerPoolConfig
|
|
572
|
+
These are the defaults of `WorkerPoolConfig` (`DEFAULT_WORKER_POOL_CONFIG`). An enclave starts from the preset of its security level, exported as `WORKER_POOL_PRESETS`, and `workerPoolConfig` overrides single settings of it:
|
|
573
|
+
|
|
574
|
+
| Level | minWorkers | maxWorkers | memoryLimitPerWorker | maxMessagesPerSecond | maxMessageSizeBytes | maxExecutionsPerWorker |
|
|
575
|
+
| ---------- | ---------- | ---------- | -------------------- | -------------------- | ------------------- | ---------------------- |
|
|
576
|
+
| STRICT | 2 | 4 | 64MB | 100 | 1MB | 100 |
|
|
577
|
+
| SECURE | 2 | 8 | 128MB | 500 | 4MB | 500 |
|
|
578
|
+
| STANDARD | 2 | 16 | 256MB | 1000 | 16MB | 1000 |
|
|
579
|
+
| PERMISSIVE | 4 | 32 | 512MB | 5000 | 64MB | 5000 |
|
|
388
580
|
|
|
389
581
|
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.
|
|
390
582
|
|
|
@@ -413,11 +605,18 @@ An execution the pool ends itself ends its worker too, and the pool starts a new
|
|
|
413
605
|
|
|
414
606
|
`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.)
|
|
415
607
|
|
|
608
|
+
**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. 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.
|
|
609
|
+
|
|
610
|
+
<details>
|
|
611
|
+
<summary>Heap flags of the process, the memory monitor, and measurements</summary>
|
|
612
|
+
|
|
416
613
|
**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`. Where the engine does enforce the heap limit, the same read bounds what the engine does not count: memory the worker holds outside its heap counts against the budget while it executes. 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.
|
|
417
614
|
|
|
418
615
|
**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.)
|
|
419
616
|
|
|
420
|
-
**
|
|
617
|
+
**Why the process can 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.
|
|
618
|
+
|
|
619
|
+
</details>
|
|
421
620
|
|
|
422
621
|
### Layers
|
|
423
622
|
|
|
@@ -438,8 +637,6 @@ An execution the pool ends itself ends its worker too, and the pool starts a new
|
|
|
438
637
|
schema, runs the tool bridge, owns the watchdog
|
|
439
638
|
```
|
|
440
639
|
|
|
441
|
-
### Security Features
|
|
442
|
-
|
|
443
640
|
- **The double VM inside the worker**: the same realm, membrane and limits as an in-process execution (a single VM with `doubleVm: { enabled: false }`)
|
|
444
641
|
- **`worker.terminate()`**: hard stop for a script nothing else can interrupt
|
|
445
642
|
- **`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))
|
|
@@ -449,11 +646,9 @@ An execution the pool ends itself ends its worker too, and the pool starts a new
|
|
|
449
646
|
- **Idle confirmation**: a worker is given to the next execution only when it has confirmed that nothing of the last script is left in it
|
|
450
647
|
- **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))
|
|
451
648
|
|
|
452
|
-
## Double VM
|
|
453
|
-
|
|
454
|
-
The Double VM provides defense-in-depth by running user code in a nested VM structure. User code runs in an **Inner VM** which is isolated inside a **Parent VM**, providing enhanced protection against VM escape attacks.
|
|
649
|
+
## Double VM
|
|
455
650
|
|
|
456
|
-
|
|
651
|
+
By default the script runs in an **inner VM** created inside a **parent VM**. The inner realm holds the script and its allowed globals; the parent realm sits between it and the host and checks every tool call before it leaves: operation names, a rate limit, and patterns of calls. `doubleVm: { enabled: false }` runs the script in a single VM.
|
|
457
652
|
|
|
458
653
|
```typescript
|
|
459
654
|
const enclave = new Enclave({
|
|
@@ -465,13 +660,12 @@ const enclave = new Enclave({
|
|
|
465
660
|
parentTimeoutBuffer: 1000, // Extra timeout buffer for parent VM (ms)
|
|
466
661
|
parentValidation: {
|
|
467
662
|
validateOperationNames: true, // Validate tool names against patterns
|
|
468
|
-
allowedOperationPattern: /^(db|api):[a-z]+$/i, //
|
|
469
|
-
blockedOperationPatterns: [/^shell:/i, /^system:/i], //
|
|
663
|
+
allowedOperationPattern: /^(db|api):[a-z]+$/i, // Allowlist pattern
|
|
664
|
+
blockedOperationPatterns: [/^shell:/i, /^system:/i], // Blocklist patterns
|
|
470
665
|
maxOperationsPerSecond: 100, // Rate limiting
|
|
471
666
|
blockSuspiciousSequences: true, // Enable suspicious pattern detection
|
|
472
667
|
rapidEnumerationThreshold: 30, // Max same-operation calls in 5s
|
|
473
668
|
rapidEnumerationOverrides: {
|
|
474
|
-
// Per-operation overrides for rapidEnumerationThreshold
|
|
475
669
|
search: 100, // Allow 100 search calls
|
|
476
670
|
'users.list': 50, // Allow 50 user list calls
|
|
477
671
|
},
|
|
@@ -482,57 +676,30 @@ const enclave = new Enclave({
|
|
|
482
676
|
|
|
483
677
|
### Parent Validation Options
|
|
484
678
|
|
|
485
|
-
| Option | Type | Default | Description
|
|
486
|
-
| --------------------------- | ----------------------- | ------- |
|
|
487
|
-
| `validateOperationNames` | `boolean` | `true` | Enable operation name validation
|
|
488
|
-
| `allowedOperationPattern` | `RegExp` | - |
|
|
489
|
-
| `blockedOperationPatterns` | `RegExp[]` | - |
|
|
490
|
-
| `maxOperationsPerSecond` | `number` | `100` | Rate limit for operations per second
|
|
491
|
-
| `blockSuspiciousSequences` | `boolean` | `true` | Enable suspicious pattern detection
|
|
492
|
-
| `rapidEnumerationThreshold` | `number` | `30` | Max same-operation calls in 5 seconds
|
|
493
|
-
| `rapidEnumerationOverrides` | `Record<string,number>` | `{}` | Per-operation thresholds (overrides default)
|
|
494
|
-
| `suspiciousPatterns` | `SuspiciousPattern[]` | `[]` | Custom
|
|
679
|
+
| Option | Type | Default | Description |
|
|
680
|
+
| --------------------------- | ----------------------- | ------- | --------------------------------------------------- |
|
|
681
|
+
| `validateOperationNames` | `boolean` | `true` | Enable operation name validation |
|
|
682
|
+
| `allowedOperationPattern` | `RegExp` | - | Allowlist pattern for operation names |
|
|
683
|
+
| `blockedOperationPatterns` | `RegExp[]` | - | Blocklist patterns for operation names |
|
|
684
|
+
| `maxOperationsPerSecond` | `number` | `100` | Rate limit for operations per second |
|
|
685
|
+
| `blockSuspiciousSequences` | `boolean` | `true` | Enable suspicious pattern detection |
|
|
686
|
+
| `rapidEnumerationThreshold` | `number` | `30` | Max same-operation calls in 5 seconds |
|
|
687
|
+
| `rapidEnumerationOverrides` | `Record<string,number>` | `{}` | Per-operation thresholds (overrides default) |
|
|
688
|
+
| `suspiciousPatterns` | `SuspiciousPattern[]` | `[]` | Custom pattern detectors, next to the built-in ones |
|
|
495
689
|
|
|
496
|
-
### Built-in Suspicious
|
|
690
|
+
### Built-in Suspicious Patterns
|
|
497
691
|
|
|
498
|
-
|
|
692
|
+
With `blockSuspiciousSequences: true`, a tool call that matches one of these patterns is refused. They are heuristics over tool names and the order of calls:
|
|
499
693
|
|
|
500
694
|
| Pattern ID | Description |
|
|
501
695
|
| --------------------- | --------------------------------------------------- |
|
|
502
|
-
| `EXFIL_LIST_SEND` | List/query followed by send/export
|
|
696
|
+
| `EXFIL_LIST_SEND` | List/query followed by send/export |
|
|
503
697
|
| `RAPID_ENUMERATION` | Same operation called too many times (configurable) |
|
|
504
698
|
| `CREDENTIAL_EXFIL` | Credential access followed by external operation |
|
|
505
|
-
| `BULK_OPERATION` | Bulk/batch operations
|
|
506
|
-
| `DELETE_AFTER_ACCESS` | Delete operation after data access
|
|
699
|
+
| `BULK_OPERATION` | Bulk/batch operations |
|
|
700
|
+
| `DELETE_AFTER_ACCESS` | Delete operation after data access |
|
|
507
701
|
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
The `RAPID_ENUMERATION` pattern blocks excessive repeated calls to the same operation. Use `rapidEnumerationThreshold` and `rapidEnumerationOverrides` to tune this:
|
|
511
|
-
|
|
512
|
-
```typescript
|
|
513
|
-
const enclave = new Enclave({
|
|
514
|
-
toolHandler: async (name, args) => {
|
|
515
|
-
/* ... */
|
|
516
|
-
},
|
|
517
|
-
doubleVm: {
|
|
518
|
-
parentValidation: {
|
|
519
|
-
// Default: Block if same operation called >30 times in 5 seconds
|
|
520
|
-
rapidEnumerationThreshold: 30,
|
|
521
|
-
|
|
522
|
-
// Per-operation overrides
|
|
523
|
-
rapidEnumerationOverrides: {
|
|
524
|
-
search: 100, // Search can be called 100 times (pagination)
|
|
525
|
-
'db.query': 50, // Database queries up to 50 times
|
|
526
|
-
'users.filter': 200, // High-volume filtering allowed
|
|
527
|
-
},
|
|
528
|
-
},
|
|
529
|
-
},
|
|
530
|
-
});
|
|
531
|
-
```
|
|
532
|
-
|
|
533
|
-
### Custom Suspicious Patterns
|
|
534
|
-
|
|
535
|
-
You can add custom pattern detectors:
|
|
702
|
+
A custom detector receives the operation name, its arguments and the history of earlier calls:
|
|
536
703
|
|
|
537
704
|
```typescript
|
|
538
705
|
const enclave = new Enclave({
|
|
@@ -561,8 +728,6 @@ const enclave = new Enclave({
|
|
|
561
728
|
|
|
562
729
|
The AI Scoring Gate gives a script a risk score from 0 to 100 before it runs and refuses the script when the score reaches a threshold. The score is a heuristic over features of the script's text: the tools it calls, their argument names and literal values, their order, and the loops they are in. It flags patterns that look like exfiltration, bulk access or access to sensitive fields; a low score is not evidence that a script is safe. The gate runs after AST validation and before execution, and is off unless configured.
|
|
563
730
|
|
|
564
|
-
### Configuration
|
|
565
|
-
|
|
566
731
|
```typescript
|
|
567
732
|
const enclave = new Enclave({
|
|
568
733
|
toolHandler: async (name, args) => {
|
|
@@ -602,13 +767,13 @@ A call through a tool namespace (`mail.send(args)`) is scored as the tool call i
|
|
|
602
767
|
| Type | What the score is computed from |
|
|
603
768
|
| -------------- | --------------------------------------------------------------------------------------------------------- |
|
|
604
769
|
| `disabled` | No scoring |
|
|
605
|
-
| `rule-based` | Eight TypeScript rules over the extracted features,
|
|
770
|
+
| `rule-based` | Eight TypeScript rules over the extracted features, no dependencies |
|
|
606
771
|
| `local-llm` | Your `customAnalyzer`, or a built-in keyword heuristic over the extracted features (no model computes it) |
|
|
607
772
|
| `external-api` | The answer of your scoring service, which receives the extracted features |
|
|
608
773
|
|
|
609
|
-
The `local-llm` scorer loads a Hugging Face model at initialization when the optional dependency `@huggingface/transformers` is installed, but it never calls it: no score is computed from the model. Set `ENCLAVE_DISABLE_LOCAL_LLM_MODEL=1` to skip the load. Its `mode: 'similarity'` searches a VectoriaDB index that is created empty and that the configuration cannot fill, so it scores like the default mode.
|
|
774
|
+
The `local-llm` scorer loads a Hugging Face model at initialization when the optional dependency `@huggingface/transformers` is installed, but it never calls it: no score is computed from the model. Set `ENCLAVE_DISABLE_LOCAL_LLM_MODEL=1` to skip the load. Its `mode: 'similarity'` searches a VectoriaDB index that is created empty and that the configuration cannot fill, so it scores like the default mode. Call `await enclave.initialize()` before the first `run()` when a scorer needs initialization.
|
|
610
775
|
|
|
611
|
-
### Custom Analyzer
|
|
776
|
+
### Custom Analyzer
|
|
612
777
|
|
|
613
778
|
A custom analyzer replaces the keyword heuristic of the `local-llm` scorer, for example with a call to a model or a static analyzer of your own:
|
|
614
779
|
|
|
@@ -617,16 +782,12 @@ import { Enclave, type LocalLlmConfig } from '@enclave-vm/core';
|
|
|
617
782
|
|
|
618
783
|
const myAnalyzer: NonNullable<LocalLlmConfig['customAnalyzer']> = {
|
|
619
784
|
async analyze(prompt, features) {
|
|
620
|
-
// Call your external LLM or static analyzer
|
|
621
785
|
const response = await fetch('https://my-analyzer-api.com/score', {
|
|
622
786
|
method: 'POST',
|
|
623
787
|
body: JSON.stringify({ prompt, features }),
|
|
624
788
|
});
|
|
625
789
|
const result = await response.json();
|
|
626
|
-
return {
|
|
627
|
-
score: result.riskScore,
|
|
628
|
-
signals: result.signals,
|
|
629
|
-
};
|
|
790
|
+
return { score: result.riskScore, signals: result.signals };
|
|
630
791
|
},
|
|
631
792
|
// Optional lifecycle methods
|
|
632
793
|
async initialize() {
|
|
@@ -651,17 +812,10 @@ const enclave = new Enclave({
|
|
|
651
812
|
});
|
|
652
813
|
```
|
|
653
814
|
|
|
654
|
-
### CustomAnalyzer Interface
|
|
655
|
-
|
|
656
815
|
```typescript
|
|
657
816
|
interface CustomAnalyzer {
|
|
658
|
-
// Analyze prompt and features, return risk score and signals
|
|
659
817
|
analyze(prompt: string, features: ExtractedFeatures): Promise<{ score: number; signals: RiskSignal[] }>;
|
|
660
|
-
|
|
661
|
-
// Optional: Initialize resources (e.g., connect to external service)
|
|
662
818
|
initialize?(): Promise<void>;
|
|
663
|
-
|
|
664
|
-
// Optional: Cleanup resources
|
|
665
819
|
dispose?(): void;
|
|
666
820
|
}
|
|
667
821
|
```
|
|
@@ -670,33 +824,38 @@ interface CustomAnalyzer {
|
|
|
670
824
|
|
|
671
825
|
The Reference Sidecar keeps large strings outside the sandbox. The script holds a short reference token in place of the data and can pass it on to another tool. This is for scripts that move large data from one tool to another, not for scripts that read it.
|
|
672
826
|
|
|
673
|
-
### How It Works
|
|
674
|
-
|
|
675
827
|
1. **Storing**: A string of at least `extractionThreshold` bytes is stored in the sidecar and replaced by a reference token (`__REF_<uuid>__`). This applies to a string literal in the script's source and to a tool result that is a string as a whole. A tool that returns an object or an array is returned as it is, with every string in it.
|
|
676
828
|
2. **The script holds a token**: Nothing is resolved for the script, lazily or otherwise. The token is an ordinary short string, and the script has no way to read the stored data.
|
|
677
829
|
3. **Resolving at the tool boundary**: A token in the arguments of a tool call, at any depth, is replaced with the stored data before the `toolHandler` is called.
|
|
678
830
|
|
|
679
831
|
The sidecar belongs to one execution and is disposed when `run()` returns.
|
|
680
832
|
|
|
681
|
-
### Enabling Sidecar
|
|
682
|
-
|
|
683
833
|
```typescript
|
|
684
834
|
const enclave = new Enclave({
|
|
685
|
-
toolHandler: async (name, args) => {
|
|
686
|
-
/* ... */
|
|
687
|
-
},
|
|
688
835
|
sidecar: {
|
|
689
836
|
enabled: true,
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
837
|
+
extractionThreshold: 100, // Store strings of 100 bytes and more
|
|
838
|
+
allowComposites: false, // Refuse: ref + "suffix"
|
|
839
|
+
},
|
|
840
|
+
toolHandler: async (name, args) => {
|
|
841
|
+
if (name === 'getLargeText') {
|
|
842
|
+
// A 1MB string: stored in the sidecar, the script gets a token
|
|
843
|
+
return 'x'.repeat(1024 * 1024);
|
|
844
|
+
}
|
|
845
|
+
if (name === 'saveText') {
|
|
846
|
+
// args.text is the 1MB string again: the token was resolved
|
|
847
|
+
return { saved: args.text.length };
|
|
848
|
+
}
|
|
695
849
|
},
|
|
696
850
|
});
|
|
697
|
-
```
|
|
698
851
|
|
|
699
|
-
|
|
852
|
+
const result = await enclave.run(`
|
|
853
|
+
const text = await callTool('getLargeText', {});
|
|
854
|
+
// text is a reference token here, not the data
|
|
855
|
+
return await callTool('saveText', { text });
|
|
856
|
+
`);
|
|
857
|
+
// result.value: { saved: 1048576 }
|
|
858
|
+
```
|
|
700
859
|
|
|
701
860
|
| Option | Type | Default | Description |
|
|
702
861
|
| ---------------------- | --------- | -------------------- | ------------------------------------------------------------------------ |
|
|
@@ -720,413 +879,12 @@ const enclave = new Enclave({
|
|
|
720
879
|
|
|
721
880
|
`maxTotalResolvedSize` bounds what one execution resolves in total: a stored value counts once, the first time it is resolved, and a concatenation of references counts every time it is built. A tool call whose arguments would go over it, or over `maxResolvedSize`, is refused (`REFERENCE_RESOLUTION_LIMIT`) and the handler is not called.
|
|
722
881
|
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
```typescript
|
|
726
|
-
const enclave = new Enclave({
|
|
727
|
-
sidecar: {
|
|
728
|
-
enabled: true,
|
|
729
|
-
extractionThreshold: 100, // Store strings of 100 bytes and more
|
|
730
|
-
allowComposites: false, // Refuse: ref + "suffix"
|
|
731
|
-
},
|
|
732
|
-
toolHandler: async (name, args) => {
|
|
733
|
-
if (name === 'getLargeText') {
|
|
734
|
-
// A 1MB string: stored in the sidecar, the script gets a token
|
|
735
|
-
return 'x'.repeat(1024 * 1024);
|
|
736
|
-
}
|
|
737
|
-
if (name === 'saveText') {
|
|
738
|
-
// args.text is the 1MB string again: the token was resolved
|
|
739
|
-
return { saved: args.text.length };
|
|
740
|
-
}
|
|
741
|
-
},
|
|
742
|
-
});
|
|
743
|
-
|
|
744
|
-
const result = await enclave.run(`
|
|
745
|
-
const text = await callTool('getLargeText', {});
|
|
746
|
-
// text is a reference token here, not the data
|
|
747
|
-
return await callTool('saveText', { text });
|
|
748
|
-
`);
|
|
749
|
-
```
|
|
750
|
-
|
|
751
|
-
### Concatenation
|
|
752
|
-
|
|
753
|
-
With `allowComposites: false` (the default at `STRICT` and `SECURE`), concatenating a reference token with anything throws inside the script: a token can only be passed on as it is.
|
|
754
|
-
|
|
755
|
-
```javascript
|
|
756
|
-
// Throws when allowComposites is false
|
|
757
|
-
const combined = ref + '-suffix';
|
|
758
|
-
```
|
|
759
|
-
|
|
760
|
-
With `allowComposites: true` (the default at `STANDARD` and `PERMISSIVE`), the concatenation yields a composite handle, and a tool that is passed the handle receives the concatenated text.
|
|
761
|
-
|
|
762
|
-
## Tool Namespaces
|
|
763
|
-
|
|
764
|
-
Expose tools to scripts as namespaced functions instead of (or alongside) `callTool()`:
|
|
765
|
-
|
|
766
|
-
```typescript
|
|
767
|
-
const enclave = new Enclave({
|
|
768
|
-
toolHandler: async (name, args) => callMyTool(name, args),
|
|
769
|
-
toolNamespaces: {
|
|
770
|
-
mail: ['list', 'send'], // mail.list(args) calls the tool 'mail.list'
|
|
771
|
-
users: { get: 'users:get' }, // users.get(args) calls the tool 'users:get'
|
|
772
|
-
},
|
|
773
|
-
});
|
|
774
|
-
|
|
775
|
-
const result = await enclave.run(`
|
|
776
|
-
const inbox = await mail.list({ unread: true });
|
|
777
|
-
const sender = await users.get({ id: inbox[0].from });
|
|
778
|
-
return sender.name;
|
|
779
|
-
`);
|
|
780
|
-
```
|
|
781
|
-
|
|
782
|
-
A namespace method call **is** a `callTool()` call: `mail.list(args, options)` behaves exactly like
|
|
783
|
-
`callTool('mail.list', args, options)`. It counts toward `maxToolCalls`, goes through the double VM's
|
|
784
|
-
rate limit, operation-name and suspicious-sequence checks, its result is sanitized, and it reaches your
|
|
785
|
-
`toolHandler`. `args` defaults to `{}`. Each namespace is a frozen, null-prototype object created
|
|
786
|
-
inside the sandbox, so aliasing (`const m = mail; m.list()`) and destructuring work and no host object
|
|
787
|
-
is exposed.
|
|
788
|
-
|
|
789
|
-
The constructor throws a `TypeError` (`Invalid toolNamespaces: ...`) for names that are not identifiers,
|
|
790
|
-
prototype keys (`__proto__`, `constructor`, `prototype`), names starting with `__`, reserved words and
|
|
791
|
-
sandbox globals used as namespaces (`callTool`, `Math`, `console`, ...), identifiers the AgentScript
|
|
792
|
-
validator refuses (`process`, `fetch`, ...), namespaces that collide with a custom global, duplicated
|
|
793
|
-
methods, and tool names every adapter cannot carry (empty, over 256 characters, or outside letters, digits,
|
|
794
|
-
`:`, `.`, `_` and `-` starting with a letter, including a generated `<namespace>.<method>` name).
|
|
795
|
-
|
|
796
|
-
Prefer namespaces over exposing tools as functions in `globals`: functions in `globals` are gated and
|
|
797
|
-
sanitized (see "Custom Globals"), but the suspicious-sequence detectors only see tool calls.
|
|
798
|
-
|
|
799
|
-
## callTool Options
|
|
800
|
-
|
|
801
|
-
Scripts can pass options as the third argument of `callTool` (or the second argument of a namespace
|
|
802
|
-
method):
|
|
803
|
-
|
|
804
|
-
```javascript
|
|
805
|
-
const r = await callTool('users:get', { id }, { throwOnError: false });
|
|
806
|
-
if (r.success) {
|
|
807
|
-
return r.data;
|
|
808
|
-
}
|
|
809
|
-
return { failed: r.error.message }; // r.error: { name, message, code?, toolName }
|
|
810
|
-
```
|
|
811
|
-
|
|
812
|
-
| Option | Default | Description |
|
|
813
|
-
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
814
|
-
| `throwOnError` | `true` | `false`: resolve to `{ success: true, data }` or, when the tool fails, `{ success: false, error }` instead of throwing |
|
|
815
|
-
|
|
816
|
-
Only failures of the tool itself (the handler threw or rejected, or its result could not be delivered)
|
|
817
|
-
are returned this way; the error object is plain data with no stack. Refusals by the enclave (abort,
|
|
818
|
-
`maxToolCalls`, rate limit, operation-name and suspicious-sequence checks, invalid arguments) always
|
|
819
|
-
throw. Options are applied inside the sandbox and are not passed to the `toolHandler`.
|
|
820
|
-
|
|
821
|
-
## Custom Globals
|
|
822
|
-
|
|
823
|
-
You can provide custom globals to the VM:
|
|
824
|
-
|
|
825
|
-
```typescript
|
|
826
|
-
const enclave = new Enclave({
|
|
827
|
-
globals: {
|
|
828
|
-
config: { apiUrl: 'https://api.example.com' },
|
|
829
|
-
helpers: {
|
|
830
|
-
formatDate: (date: Date) => date.toISOString(),
|
|
831
|
-
},
|
|
832
|
-
},
|
|
833
|
-
allowFunctionsInGlobals: true, // Required when globals contain functions
|
|
834
|
-
toolHandler: async (name, args) => {
|
|
835
|
-
/* ... */
|
|
836
|
-
},
|
|
837
|
-
});
|
|
838
|
-
|
|
839
|
-
const result = await enclave.run(`
|
|
840
|
-
const url = config.apiUrl;
|
|
841
|
-
const formatted = helpers.formatDate(new Date());
|
|
842
|
-
return { url, formatted };
|
|
843
|
-
`);
|
|
844
|
-
```
|
|
845
|
-
|
|
846
|
-
**Security Note**: Set `allowFunctionsInGlobals: true` only when you intentionally provide functions. Functions in globals can potentially leak host scope via closures.
|
|
847
|
-
|
|
848
|
-
Every call from the script into a function from `globals` (including functions nested in objects) goes
|
|
849
|
-
through the enclave's gate:
|
|
850
|
-
|
|
851
|
-
- it is refused once the execution is aborted, and counts toward `maxGlobalFunctionCalls`
|
|
852
|
-
(default: 10 × `maxToolCalls`), not toward `maxToolCalls`;
|
|
853
|
-
- its arguments are copied into plain host data first, the way tool arguments are: the function
|
|
854
|
-
receives null-prototype objects, arrays, primitives and `Date`s, never a live script value, and a
|
|
855
|
-
call that passes a function or a symbol is refused. The script's `this` is not passed either;
|
|
856
|
-
- in the double VM (the default) it shares the operation rate limit
|
|
857
|
-
(`doubleVm.parentValidation.maxOperationsPerSecond`) with tool calls;
|
|
858
|
-
- its return value is sanitized like a tool result: the script receives a plain-data copy, and a
|
|
859
|
-
value containing functions or symbols, or exceeding the sanitize depth/size limits, is refused;
|
|
860
|
-
- an error it throws reaches the script as a plain error without the host stack;
|
|
861
|
-
- calling it with `new` is refused.
|
|
862
|
-
|
|
863
|
-
The suspicious-sequence detectors only look at tool calls, so expose tools with `toolNamespaces` or
|
|
864
|
-
`callTool()`, not as functions. The `worker_threads` adapter never passes functions into the sandbox.
|
|
865
|
-
|
|
866
|
-
A function is not started when the script calls it with the stack nearly full (less than 128 KB
|
|
867
|
-
left): the call throws a `RangeError` in the script, and the function has not run. The check only
|
|
868
|
-
decides whether a function starts: it is never started halfway. It says nothing about a function
|
|
869
|
-
that did start. An async function that is still in progress when `toolCallGraceMs` is over is left
|
|
870
|
-
behind like a tool call, and `run()` ends without its result reaching the script.
|
|
871
|
-
|
|
872
|
-
The validation of `globals` judges what a script can reach through a value, not only what the
|
|
873
|
-
value has itself. The methods of a class are functions in `globals`: an instance of a class with
|
|
874
|
-
methods needs `allowFunctionsInGlobals: true`, and so does a function in a property that is not
|
|
875
|
-
enumerable or is keyed by a symbol. Code that runs when a property is read is refused whatever is
|
|
876
|
-
allowed: a getter or setter, on the value or on its class, and a Proxy of an object. That
|
|
877
|
-
includes a `Buffer` (pass a `Uint8Array`) and an `Error` object (pass its message). A function
|
|
878
|
-
passed as a global is judged as a function; what hangs on it is not looked at.
|
|
879
|
-
An instance of a class without methods or accessors is plain data and is accepted, unless
|
|
880
|
-
`secureProxyConfig.blockConstructor` is off (as at `PERMISSIVE`): then a script can read its
|
|
881
|
-
`constructor`, which is a function.
|
|
882
|
-
|
|
883
|
-
Values passed in `globals` are **read-only** inside the sandbox. They are the host's own objects, shared
|
|
884
|
-
by every execution of the enclave, so a script cannot assign to them, add or delete properties, freeze
|
|
885
|
-
them, or call a built-in method that changes its receiver (`push`, `sort`, `Map.prototype.set`,
|
|
886
|
-
`Date.prototype.setTime`, ...): the attempt throws, or is ignored at `PERMISSIVE`. Reading works as
|
|
887
|
-
before, and an array returned by a built-in method (`map`, `filter`, `slice`, ...) is the script's own
|
|
888
|
-
copy, which it can sort or extend. To let scripts keep state, return it from a tool instead.
|
|
889
|
-
|
|
890
|
-
A **regular expression** passed in `globals` can be read (`source`, `flags`, `global`, ...) but not
|
|
891
|
-
run: `test`, `exec` and its use as the pattern of `match`, `matchAll`, `replace`, `search` or `split`
|
|
892
|
-
throw, at every security level. A match would run the host's pattern on a text the script chooses,
|
|
893
|
-
outside the rules that apply to the script's own expressions, and with the `g` or `y` flag it writes
|
|
894
|
-
`lastIndex` on the host's object. Pass a function that does the matching, or let the script build
|
|
895
|
-
the expression from `source` and `flags` where the preset allows `RegExp`. The same goes for
|
|
896
|
-
`match`, `matchAll` and `search` on a `String` object (`new String(...)`) passed in `globals`;
|
|
897
|
-
a plain string is not affected.
|
|
898
|
-
|
|
899
|
-
A custom global cannot be named `Object`: the sandbox provides its own. The constructor throws.
|
|
900
|
-
|
|
901
|
-
With the single VM, an object of the script's own that a host built-in hands back to a callback
|
|
902
|
-
(the object a script gave `reduce` to collect into) stays the script's and stays writable. The
|
|
903
|
-
runtime recognises it by its prototype chain, which ends in the sandbox's `Object.prototype`. An
|
|
904
|
-
object without a prototype (`Object.create(null)`) carries nothing that says who made it and is
|
|
905
|
-
treated as the host's, so it arrives read-only in the callback: collect into `{}` or an array.
|
|
906
|
-
|
|
907
|
-
Inside arrays, Maps and Sets only plain data is allowed (primitives, plain objects, arrays, Maps, Sets,
|
|
908
|
-
Dates, RegExps, typed arrays): the built-in methods of those collections (`forEach`, iteration, `get`)
|
|
909
|
-
hand elements to the script directly, so a function (or an object with methods) stored there would be
|
|
910
|
-
called without the gate. The constructor refuses it with an error naming the path, e.g.
|
|
911
|
-
`Custom global "cfg" contains a function inside a collection at hooks.0.run`. Every own entry counts there,
|
|
912
|
-
enumerable or not, and Map and Set subclasses are refused inside collections. Arrays anywhere in `globals`
|
|
913
|
-
must be plain arrays (no Proxy, no custom prototype), since those can hide entries from validation.
|
|
914
|
-
Promises, WeakMaps, iterators and generators are refused anywhere in `globals`, since their contents cannot
|
|
915
|
-
be validated.
|
|
916
|
-
|
|
917
|
-
## Execution Result
|
|
918
|
-
|
|
919
|
-
```typescript
|
|
920
|
-
interface ExecutionResult<T> {
|
|
921
|
-
success: boolean;
|
|
922
|
-
value?: T; // Result when success is true
|
|
923
|
-
error?: {
|
|
924
|
-
message: string;
|
|
925
|
-
name: string;
|
|
926
|
-
code?: string; // Error code (e.g., 'VALIDATION_ERROR'; see "Error Codes")
|
|
927
|
-
stack?: string; // Only for errors made outside the sandbox
|
|
928
|
-
data?: Record<string, unknown>;
|
|
929
|
-
};
|
|
930
|
-
stats: {
|
|
931
|
-
duration: number; // Execution time in ms
|
|
932
|
-
toolCallCount: number; // Number of tool calls made
|
|
933
|
-
iterationCount: number; // Number of loop iterations
|
|
934
|
-
memoryUsage?: number; // Peak tracked memory in bytes (when memoryLimit is set)
|
|
935
|
-
startTime: number;
|
|
936
|
-
endTime: number;
|
|
937
|
-
};
|
|
938
|
-
scoringResult?: ScoringGateResult; // When a scoring gate evaluated the script
|
|
939
|
-
}
|
|
940
|
-
```
|
|
941
|
-
|
|
942
|
-
**`result.error` is plain, bounded text.** Whatever a script threw, `name` and `message` are strings: `name`
|
|
943
|
-
of at most 256 characters, `message` of at most 16,384. A thrown string is the message; a thrown `null`,
|
|
944
|
-
`undefined` or other primitive is named in the message (`The script threw null`); an object without a
|
|
945
|
-
string `message` is reported as `The script threw a value that is not an error`. An object a script makes
|
|
946
|
-
to look like the memory-limit error is not reported as one. The message of a validation failure is cut to
|
|
947
|
-
500 characters per issue and 32,768 in total; `error.data.issues` holds the issues.
|
|
948
|
-
|
|
949
|
-
**Errors made inside the sandbox have no `stack`.** No sandbox realm captures a stack trace, so
|
|
950
|
-
`error.stack` is `undefined` for the script and absent from `result.error` for what a script throws and
|
|
951
|
-
for what the runtime raises inside the sandbox (a limit, a failed tool call). This holds for the double VM
|
|
952
|
-
and the single VM, in process and in a worker. Errors the host makes outside a sandbox realm (an adapter
|
|
953
|
-
that fails, a worker pool error, an error of the `InterpreterAdapter`, which has no realm of its own) keep
|
|
954
|
-
their stack. With `sanitizeStackTraces` on (the default for `STRICT` and `SECURE`), such a stack is
|
|
955
|
-
sanitized, whichever stage raised the error: stack frames become `at [REDACTED]` and paths, URLs and file
|
|
956
|
-
locations in the remaining lines are redacted.
|
|
957
|
-
|
|
958
|
-
### Error Codes
|
|
959
|
-
|
|
960
|
-
| Code | Description |
|
|
961
|
-
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
962
|
-
| `VALIDATION_ERROR` | AST validation failed, or the script is too large or not a string |
|
|
963
|
-
| `SECURITY_VIOLATION` | The script contains a dynamic import (also with `validate: false`), or a blocked operation was recorded at `STRICT` or `SECURE` |
|
|
964
|
-
| `SCORING_BLOCKED` | Refused by the scoring gate |
|
|
965
|
-
| `DOUBLE_VM_EXECUTION_ERROR` | The script failed in the double VM (the default): an error it did not catch, a failed tool call, the tool-call or iteration limit, a timeout |
|
|
966
|
-
| `VM_EXECUTION_ERROR` | The same with `doubleVm: { enabled: false }`; with either VM, the timeout of a script that was only waiting |
|
|
967
|
-
| `MEMORY_LIMIT_EXCEEDED` | `memoryLimit` exceeded |
|
|
968
|
-
| `SERIALIZATION_LIMIT_EXCEEDED` | The returned value is larger than the memory limit allows |
|
|
969
|
-
| `EXECUTION_ERROR` | The adapter itself failed; with the worker pool `error.name` is the pool's error (`WorkerTimeoutError`, ...) |
|
|
970
|
-
| `ENCLAVE_ERROR` | Any other failure outside the sandbox, such as a script with a syntax error |
|
|
971
|
-
| `EXECUTION_TIMEOUT`, `STEP_LIMIT_EXCEEDED` | The timeout and the step budget of the `InterpreterAdapter` |
|
|
972
|
-
|
|
973
|
-
For the limits `error.message` says which one ended the script: `Script execution timed out ...`,
|
|
974
|
-
`Maximum iteration limit exceeded ...`, `Maximum tool call limit exceeded ...`.
|
|
975
|
-
|
|
976
|
-
### How `timeout` Is Enforced
|
|
977
|
-
|
|
978
|
-
- The time is the script's: the clock starts when the sandbox is ready to run it. Validation, the
|
|
979
|
-
transform and the creation of the sandbox adapter (once per enclave; with the worker pool that
|
|
980
|
-
starts the worker threads) come before it. Waiting for a free worker counts, and a script whose
|
|
981
|
-
time has passed while it waited is not started: `run()` returns `ExecutionAbortedError`.
|
|
982
|
-
- Until the script's first `await`, Node's `vm` interrupts it at the deadline.
|
|
983
|
-
- After that, the script checks the clock itself: the transformer inserts a check at the start of
|
|
984
|
-
every function and loop body and in front of a parameter default, so synchronous work, recursion
|
|
985
|
-
and promise chains that never yield are stopped at the deadline as well. A script that catches
|
|
986
|
-
the timeout error cannot enter another function or loop iteration. The deadline is cooperative:
|
|
987
|
-
it is looked at between the steps of the script's own code.
|
|
988
|
-
- A tool call in progress at the deadline is not cut off, and its result is delivered. From then on
|
|
989
|
-
the next tool call or call into a host function is refused with `Execution aborted`. The same
|
|
990
|
-
holds for an async function from `globals`.
|
|
991
|
-
- That wait has an end: `toolCallGraceMs` after the deadline the execution ends with the timeout
|
|
992
|
-
error, whatever is still in progress, and `error.data.pendingHostCalls` says how many calls
|
|
993
|
-
were left running. The default is the value of `timeout`, so `run()` takes at most twice
|
|
994
|
-
`timeout`. `0` ends every execution at the deadline; `Infinity` waits for the handler however
|
|
995
|
-
long it takes, as versions up to 2.18 did (a handler that never settles then keeps `run()` from
|
|
996
|
-
settling).
|
|
997
|
-
- When `run()` has returned, for whatever reason, the script is finished for the host as well.
|
|
998
|
-
What it left behind (a tool call it did not await, with a `then` on it) can no longer call a
|
|
999
|
-
tool, a function from `globals` or the console, and it ends within a bounded number of steps:
|
|
1000
|
-
its next checks throw `Script execution has ended`.
|
|
1001
|
-
- A script that only waits is ended as well. Waiting takes no code: a thenable that never calls
|
|
1002
|
-
back (`return { then: () => 0 }`) is enough, and nothing runs that could look at the clock. So
|
|
1003
|
-
the enclave keeps count of what the host has in flight for the script (tool calls, async
|
|
1004
|
-
functions from `globals`), and from the deadline on `run()` returns the timeout error as soon as
|
|
1005
|
-
that count is zero. A sandbox has no timers and no I/O, so nothing else could wake the script.
|
|
1006
|
-
(With `adapter: 'worker_threads'` the pool ends such a script like a busy one: with its worker,
|
|
1007
|
-
five seconds after the deadline.)
|
|
1008
|
-
- Not covered: a single built-in call that does all its work natively, and a script run with
|
|
1009
|
-
`transform: false`. The engine finishes one call into a built-in before the next check, so
|
|
1010
|
-
`timeout` does not bound its duration. And the enclave cannot stop your
|
|
1011
|
-
`toolHandler`: a call it stops waiting for keeps running in the host, so a tool that changes
|
|
1012
|
-
something should be safe to repeat, or have a time limit of its own. For a
|
|
1013
|
-
stop the script cannot influence, use `adapter: 'worker_threads'`: a script that is still
|
|
1014
|
-
running five seconds after its timeout is terminated with its worker (see
|
|
1015
|
-
[Worker Pool Adapter](#worker-pool-adapter-optional)). A process you can terminate does the
|
|
1016
|
-
same for everything else that runs in it.
|
|
1017
|
-
|
|
1018
|
-
## Defense-in-Depth Architecture
|
|
1019
|
-
|
|
1020
|
-
```
|
|
1021
|
-
┌─────────────────────────────────────────────────────────────┐
|
|
1022
|
-
│ User Code Input │
|
|
1023
|
-
└─────────────────────────────────────────────────────────────┘
|
|
1024
|
-
│
|
|
1025
|
-
▼
|
|
1026
|
-
┌─────────────────────────────────────────────────────────────┐
|
|
1027
|
-
│ Layer 0: Pre-Scanner (ast-guard, preset of the AST preset) │
|
|
1028
|
-
│ ├── Input size, line and string limits │
|
|
1029
|
-
│ ├── Nesting depth limits │
|
|
1030
|
-
│ ├── Regex literals refused (agentscript) or analyzed │
|
|
1031
|
-
│ └── Bidirectional, invisible and look-alike characters │
|
|
1032
|
-
└─────────────────────────────────────────────────────────────┘
|
|
1033
|
-
│
|
|
1034
|
-
▼
|
|
1035
|
-
┌─────────────────────────────────────────────────────────────┐
|
|
1036
|
-
│ Layer 1: AST Validation (ast-guard) │
|
|
1037
|
-
│ ├── NoEvalRule - Blocks eval(), Function() │
|
|
1038
|
-
│ ├── NoGlobalAccessRule - Blocks dangerous globals │
|
|
1039
|
-
│ ├── AllowedSyntaxRule - Syntax allowlist │
|
|
1040
|
-
│ ├── UnknownGlobalRule - Only the allowed globals │
|
|
1041
|
-
│ └── ReservedPrefixRule - Blocks reserved prefixes │
|
|
1042
|
-
└─────────────────────────────────────────────────────────────┘
|
|
1043
|
-
│
|
|
1044
|
-
▼
|
|
1045
|
-
┌─────────────────────────────────────────────────────────────┐
|
|
1046
|
-
│ Layer 2: Code Transformation │
|
|
1047
|
-
│ ├── Wraps in async function __ag_main() │
|
|
1048
|
-
│ ├── callTool → __safe_callTool (tracked) │
|
|
1049
|
-
│ ├── Loops → __safe_for, __safe_forOf (guarded) │
|
|
1050
|
-
│ └── String literals → extracted to sidecar (if enabled) │
|
|
1051
|
-
└─────────────────────────────────────────────────────────────┘
|
|
1052
|
-
│
|
|
1053
|
-
▼
|
|
1054
|
-
┌─────────────────────────────────────────────────────────────┐
|
|
1055
|
-
│ Layer 3: AI Scoring Gate (optional, heuristic) │
|
|
1056
|
-
│ ├── Features of the script's tool calls │
|
|
1057
|
-
│ ├── Exfiltration-like tool sequences │
|
|
1058
|
-
│ ├── Sensitive field names │
|
|
1059
|
-
│ └── Risk scoring (0-100) with thresholds │
|
|
1060
|
-
└─────────────────────────────────────────────────────────────┘
|
|
1061
|
-
│
|
|
1062
|
-
▼
|
|
1063
|
-
┌─────────────────────────────────────────────────────────────┐
|
|
1064
|
-
│ Layer 4: Runtime Sandbox │
|
|
1065
|
-
│ ├── Standard: Node.js vm (prototype isolation) │
|
|
1066
|
-
│ ├── Optional: Worker Pool (heap limit, hard stop) │
|
|
1067
|
-
│ │ ├── Dual-layer: worker thread + VM context │
|
|
1068
|
-
│ │ ├── Hard halt via worker.terminate() │
|
|
1069
|
-
│ │ └── Per-worker memory limits │
|
|
1070
|
-
│ ├── __safe_callTool - Enforces maxToolCalls │
|
|
1071
|
-
│ ├── __safe_forOf - Enforces maxIterations │
|
|
1072
|
-
│ └── Timeout enforcement │
|
|
1073
|
-
└─────────────────────────────────────────────────────────────┘
|
|
1074
|
-
│
|
|
1075
|
-
▼
|
|
1076
|
-
┌─────────────────────────────────────────────────────────────┐
|
|
1077
|
-
│ Layer 5: Output Sanitization │
|
|
1078
|
-
│ ├── Returned values copied into plain data │
|
|
1079
|
-
│ ├── Errors as bounded text, no stack from the sandbox │
|
|
1080
|
-
│ └── Refuses oversized return values │
|
|
1081
|
-
└─────────────────────────────────────────────────────────────┘
|
|
1082
|
-
│
|
|
1083
|
-
▼
|
|
1084
|
-
┌─────────────────────────────────────────────────────────────┐
|
|
1085
|
-
│ Safe Execution Result │
|
|
1086
|
-
└─────────────────────────────────────────────────────────────┘
|
|
1087
|
-
```
|
|
1088
|
-
|
|
1089
|
-
### What the Pre-Scanner Checks
|
|
1090
|
-
|
|
1091
|
-
`Enclave` runs the pre-scanner on the script as it was written, before anything parses it, with the pre-scanner preset named like the AST `preset`:
|
|
1092
|
-
|
|
1093
|
-
| AST preset | Pre-scanner preset | Script | Lines | String literals | Regex literals | Bidirectional controls | Invisible characters |
|
|
1094
|
-
| ----------------------- | ------------------ | ---------------------------------------------------- | ------------------------------- | --------------------------- | ------------------------------------------- | ---------------------- | -------------------- |
|
|
1095
|
-
| `agentscript` (default) | `agentscript` | 100 KB, nesting 20 | 1,000 of at most 2,000 chars | 10 KB each, 100 KB in total | refused | refused | refused |
|
|
1096
|
-
| `strict` | `strict` | 500 KB, nesting 30 | 2,000 of at most 5,000 chars | 50 KB each, 500 KB in total | 10 of at most 100 chars, analyzed for ReDoS | refused | refused |
|
|
1097
|
-
| `secure` | `secure` | 1 MB, nesting 40 | 5,000 of at most 8,000 chars | 100 KB each, 1 MB in total | 20 of at most 200 chars, analyzed | refused | allowed |
|
|
1098
|
-
| `standard`, `babel` | `standard` | 5 MB, nesting 50 | 10,000 of at most 10,000 chars | 500 KB each, 5 MB in total | 30 of at most 500 chars, analyzed | allowed | allowed |
|
|
1099
|
-
| `permissive` | `permissive` | 5,242,880 chars (the enclave's maximum), nesting 100 | 100,000 of at most 50,000 chars | 1 MB each, 10 MB in total | allowed | allowed | allowed |
|
|
1100
|
-
|
|
1101
|
-
Every preset except `permissive` also refuses a null byte, more consecutive operators than its limit, and one of a fixed list of letters that look like ASCII letters (Cyrillic and Greek look-alikes of `a`, `c`, `e`, `o`, `p`, `x`, `y`, and the full-width `a` and `e`), anywhere in the text.
|
|
1102
|
-
|
|
1103
|
-
The `preScan` option picks another preset or changes single limits of the one in force; the pre-scanner's own absolute maximums still hold:
|
|
1104
|
-
|
|
1105
|
-
```typescript
|
|
1106
|
-
// The limits enclaves had before 2.19.2, whatever the AST preset
|
|
1107
|
-
const enclave = new Enclave({ preScan: { preset: 'standard' } });
|
|
1108
|
-
|
|
1109
|
-
// The agentscript pre-scanner with room for larger string literals (for the reference sidecar, say).
|
|
1110
|
-
// The limit on one literal and the limit on all literals together are separate: raise both.
|
|
1111
|
-
const enclave = new Enclave({
|
|
1112
|
-
preScan: {
|
|
1113
|
-
config: {
|
|
1114
|
-
maxInputSize: 1024 * 1024,
|
|
1115
|
-
maxLineLength: 100000,
|
|
1116
|
-
maxStringLength: 512 * 1024,
|
|
1117
|
-
maxTotalStringContent: 1024 * 1024,
|
|
1118
|
-
},
|
|
1119
|
-
},
|
|
1120
|
-
});
|
|
1121
|
-
```
|
|
1122
|
-
|
|
1123
|
-
A line is at most 100,000 characters under any configuration (the pre-scanner's absolute maximum), so a literal longer than that has to be a template literal over several lines.
|
|
1124
|
-
|
|
1125
|
-
With `validate: false` the pre-scanner does not run; a script is limited to 5,242,880 characters in any case.
|
|
882
|
+
With `allowComposites: false` (the default at `STRICT` and `SECURE`), concatenating a reference token with anything throws inside the script: a token can only be passed on as it is. With `allowComposites: true` (the default at `STANDARD` and `PERMISSIVE`), the concatenation yields a composite handle, and a tool that is passed the handle receives the concatenated text.
|
|
1126
883
|
|
|
1127
884
|
## Runtime Notes
|
|
1128
885
|
|
|
1129
|
-
|
|
886
|
+
<details>
|
|
887
|
+
<summary>Node.js 24 (V8 13.x): compiled code is not shared between sandboxes</summary>
|
|
1130
888
|
|
|
1131
889
|
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.
|
|
1132
890
|
|
|
@@ -1143,56 +901,28 @@ What that costs, measured on Node.js 24.18.0 and 22.21.1 (arm64) with a small sc
|
|
|
1143
901
|
|
|
1144
902
|
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.
|
|
1145
903
|
|
|
904
|
+
</details>
|
|
905
|
+
|
|
1146
906
|
### A script at a full stack
|
|
1147
907
|
|
|
1148
|
-
A script can recurse until the stack is full and, on the way back up, call everything it has at
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
- **
|
|
1152
|
-
|
|
1153
|
-
|
|
1154
|
-
|
|
1155
|
-
|
|
1156
|
-
46.4 KB with Node.js 22), so code that starts in that zone fails wherever it first calls
|
|
1157
|
-
something new. A call into the runtime needs 64 KB; a function from `globals`, a
|
|
1158
|
-
`consoleHandler` and the host console need 128 KB, checked on the host right before they start.
|
|
1159
|
-
With less, the script gets a `RangeError` (a console line for a `consoleHandler` is dropped)
|
|
1160
|
-
and nothing of the host has run. Without this, a write to `process.stdout` that is cut off
|
|
1161
|
-
halfway leaves that stream waiting forever, and that is not specific to the sandbox.
|
|
1162
|
-
- **A tool handler starts from an empty stack**, whatever the script's stack looks like when it
|
|
1163
|
-
makes the call.
|
|
1164
|
-
- The check costs about 2.7 microseconds per call into the runtime and about 5.5 per call into
|
|
1165
|
-
your code. Reading a property is not checked, and has no need to be: `globals` cannot hold
|
|
1166
|
-
getters or proxies, so no code of yours runs on a read (see [Custom Globals](#custom-globals)).
|
|
1167
|
-
|
|
1168
|
-
What it does not prevent: **Node.js writes to the process's stderr** when a promise is rejected
|
|
1169
|
-
while the stack is full. Its own bookkeeping for the rejection is JavaScript and cannot run there,
|
|
1170
|
-
and it prints a block (`Exception in PromiseRejectCallback`, with the source line that was
|
|
1171
|
-
executing) from native code. A script can produce such blocks at a few megabytes per second for as
|
|
1172
|
-
long as it runs, and the printed line is a line of the script. Nothing in JavaScript can intercept
|
|
1173
|
-
that write, in a worker thread either. If your stderr is collected, give it a size limit and do not
|
|
1174
|
-
parse it for decisions; a child process whose stderr you control is the complete answer.
|
|
908
|
+
A script can recurse until the stack is full and, on the way back up, call everything it has at every level. What the enclave guarantees there:
|
|
909
|
+
|
|
910
|
+
- **What the script catches is its own.** Every call into the runtime enters through a function of the script's realm, so the `RangeError` of a stack overflow is an error of that realm whatever was being called.
|
|
911
|
+
- **The runtime's code and yours start with room to finish.** V8 refuses to compile a function for its first call when less than about 40 KB of stack is left (measured: 39.9 KB with Node.js 24, 46.4 KB with Node.js 22), so code that starts in that zone fails wherever it first calls something new. A call into the runtime needs 64 KB; a function from `globals`, a `consoleHandler` and the host console need 128 KB, checked on the host right before they start. With less, the script gets a `RangeError` (a console line for a `consoleHandler` is dropped) and nothing of the host has run. Without this, a write to `process.stdout` that is cut off halfway leaves that stream waiting forever, and that is not specific to the sandbox.
|
|
912
|
+
- **A tool handler starts from an empty stack**, whatever the script's stack looks like when it makes the call.
|
|
913
|
+
- The check costs about 2.7 microseconds per call into the runtime and about 5.5 per call into your code. Reading a property is not checked, and has no need to be: `globals` cannot hold getters or proxies, so no code of yours runs on a read (see [Custom Globals](#custom-globals)).
|
|
914
|
+
|
|
915
|
+
What it does not prevent: **Node.js writes to the process's stderr** when a promise is rejected while the stack is full. Its own bookkeeping for the rejection is JavaScript and cannot run there, and it prints a block (`Exception in PromiseRejectCallback`, with the source line that was executing) from native code. A script can produce such blocks at a few megabytes per second for as long as it runs, and the printed line is a line of the script. Nothing in JavaScript can intercept that write, in a worker thread either. If your stderr is collected, give it a size limit and do not parse it for decisions; a child process whose stderr you control is the complete answer.
|
|
1175
916
|
|
|
1176
917
|
### Promise rejections a script leaves behind
|
|
1177
918
|
|
|
1178
|
-
Node.js ends the process when a promise is rejected and nothing handles it, and the rule covers
|
|
1179
|
-
the promises of a sandbox: an async function that throws and is not awaited, a failing tool call
|
|
1180
|
-
nobody awaits. The enclave therefore answers the two process events `unhandledRejection` and
|
|
1181
|
-
`rejectionHandled` itself for every promise that is not one of the host realm (it wraps
|
|
1182
|
-
`process.emit` the first time a sandbox is used). The process goes on, none of your listeners is
|
|
1183
|
-
called with a script's promise or reason, and your own rejections reach your listeners, or end the
|
|
1184
|
-
process, exactly as before.
|
|
919
|
+
Node.js ends the process when a promise is rejected and nothing handles it, and the rule covers the promises of a sandbox: an async function that throws and is not awaited, a failing tool call nobody awaits. The enclave therefore answers the two process events `unhandledRejection` and `rejectionHandled` itself for every promise that is not one of the host realm (it wraps `process.emit` the first time a sandbox is used). The process goes on, none of your listeners is called with a script's promise or reason, and your own rejections reach your listeners, or end the process, exactly as before.
|
|
1185
920
|
|
|
1186
|
-
- Under `--unhandled-rejections=strict` Node.js raises the exception before it emits anything, and
|
|
1187
|
-
under `=warn` it prints its warning first: use the default mode (`throw`) or `none`.
|
|
921
|
+
- Under `--unhandled-rejections=strict` Node.js raises the exception before it emits anything, and under `=warn` it prints its warning first: use the default mode (`throw`) or `none`.
|
|
1188
922
|
- Promises of `vm` contexts your application created itself are covered as well.
|
|
1189
|
-
- `disableSandboxRejectionGuard()` turns this off. Your `unhandledRejection` listener then has to
|
|
1190
|
-
|
|
1191
|
-
|
|
1192
|
-
- Test runners that give tests a stand-in `process` object (Jest does) are not covered: there the
|
|
1193
|
-
runner reports a script's rejection as a failure of the test.
|
|
1194
|
-
- In the sandbox, `Symbol.for` refuses keys in the `nodejs.` namespace: Node.js looks up some of
|
|
1195
|
-
its own protocols in that registry, among them the method `util.inspect` calls on a value.
|
|
923
|
+
- `disableSandboxRejectionGuard()` turns this off. Your `unhandledRejection` listener then has to ignore every promise for which `isHostPromise(promise)` is false, without touching the reason. `disableSandboxRejectionGuard(false)` turns it back on from the next execution of an enclave.
|
|
924
|
+
- Test runners that give tests a stand-in `process` object (Jest does) are not covered: there the runner reports a script's rejection as a failure of the test.
|
|
925
|
+
- In the sandbox, `Symbol.for` refuses keys in the `nodejs.` namespace: Node.js looks up some of its own protocols in that registry, among them the method `util.inspect` calls on a value.
|
|
1196
926
|
|
|
1197
927
|
### Memory under sustained load
|
|
1198
928
|
|
|
@@ -1200,44 +930,59 @@ V8 keeps every script it compiled in its compilation cache until several major g
|
|
|
1200
930
|
|
|
1201
931
|
## API Reference
|
|
1202
932
|
|
|
1203
|
-
### Enclave
|
|
933
|
+
### Enclave
|
|
1204
934
|
|
|
1205
935
|
```typescript
|
|
1206
936
|
class Enclave {
|
|
1207
937
|
constructor(options?: CreateEnclaveOptions);
|
|
1208
938
|
|
|
1209
|
-
// Execute AgentScript code
|
|
1210
|
-
run<T = unknown>(code: string): Promise<ExecutionResult<T>>;
|
|
939
|
+
// Execute AgentScript code; a toolHandler passed here replaces the one of the options
|
|
940
|
+
run<T = unknown>(code: string, toolHandler?: ToolHandler): Promise<ExecutionResult<T>>;
|
|
941
|
+
|
|
942
|
+
// Initialize the scoring gate's scorer, for scorers that need it
|
|
943
|
+
initialize(): Promise<void>;
|
|
944
|
+
|
|
945
|
+
getSecurityLevel(): SecurityLevel;
|
|
946
|
+
getEffectiveConfig(): {
|
|
947
|
+
securityLevel;
|
|
948
|
+
timeout;
|
|
949
|
+
maxIterations;
|
|
950
|
+
maxToolCalls;
|
|
951
|
+
sanitizeStackTraces;
|
|
952
|
+
maxSanitizeDepth;
|
|
953
|
+
maxSanitizeProperties;
|
|
954
|
+
memoryLimit;
|
|
955
|
+
realmGlobals;
|
|
956
|
+
};
|
|
957
|
+
// Cache statistics of the scoring gate: { size, maxEntries, totalHits, totalMisses, hitRate, enabled }, or null
|
|
958
|
+
getScoringStats(): object | null;
|
|
1211
959
|
|
|
1212
960
|
// Clean up resources
|
|
1213
961
|
dispose(): void;
|
|
1214
962
|
}
|
|
1215
|
-
```
|
|
1216
|
-
|
|
1217
|
-
### ToolHandler Type
|
|
1218
963
|
|
|
1219
|
-
|
|
1220
|
-
type ToolHandler = (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
|
|
964
|
+
function runAgentScript<T = unknown>(code: string, options?: CreateEnclaveOptions): Promise<ExecutionResult<T>>;
|
|
1221
965
|
```
|
|
1222
966
|
|
|
1223
|
-
|
|
1224
|
-
script's `callTool` options (`CallToolOptions`) are applied inside the sandbox and are not passed to
|
|
1225
|
-
the handler.
|
|
967
|
+
### Entry points
|
|
1226
968
|
|
|
1227
|
-
|
|
969
|
+
| Import | Contents |
|
|
970
|
+
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
971
|
+
| `@enclave-vm/core` | `Enclave`, `runAgentScript`, the adapters (`WorkerPoolAdapter`, `InterpreterAdapter`), scoring, sidecar, session, Babel and secure-proxy utilities, and the types |
|
|
972
|
+
| `@enclave-vm/core/worker` | `AgentScriptRunner`, `PortableEnclave`, `InterpreterAdapter`, `Interpreter`: no Node `vm`, worker-thread or child-process modules |
|
|
1228
973
|
|
|
1229
|
-
|
|
1230
|
-
# Run tests
|
|
1231
|
-
npx nx test core
|
|
974
|
+
## Related Packages
|
|
1232
975
|
|
|
1233
|
-
|
|
1234
|
-
|
|
1235
|
-
|
|
976
|
+
- [`@enclave-vm/ast`](https://www.npmjs.com/package/@enclave-vm/ast): the validator, presets, pre-scanner and transforms used here
|
|
977
|
+
- [`@enclave-vm/browser`](https://www.npmjs.com/package/@enclave-vm/browser): the sandbox for browsers, in nested iframes
|
|
978
|
+
- [`@enclave-vm/broker`](https://www.npmjs.com/package/@enclave-vm/broker): tool registry, secrets and session routes around this package
|
|
1236
979
|
|
|
1237
|
-
##
|
|
980
|
+
## Documentation
|
|
1238
981
|
|
|
1239
|
-
-
|
|
982
|
+
- Guides and reference: https://agentfront.dev/docs/guides/enclave
|
|
983
|
+
- Repository: https://github.com/agentfront/enclave
|
|
984
|
+
- Reporting a vulnerability: [SECURITY.md](https://github.com/agentfront/enclave/blob/main/SECURITY.md)
|
|
1240
985
|
|
|
1241
986
|
## License
|
|
1242
987
|
|
|
1243
|
-
Apache-2.0
|
|
988
|
+
Apache-2.0. See [LICENSE](https://github.com/agentfront/enclave/blob/main/LICENSE).
|