@enclave-vm/core 2.19.1 → 2.20.0-rc.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 +291 -105
- package/adapters/worker-pool/config.d.ts +15 -5
- package/adapters/worker-pool/protocol.d.ts +27 -1
- package/adapters/worker-pool/worker-pool-adapter.d.ts +24 -0
- package/adapters/worker-pool/worker-slot.d.ts +35 -6
- package/async-context.d.ts +34 -0
- package/babel/babel-wrapper.d.ts +21 -12
- package/babel/multi-file-transform.d.ts +3 -0
- package/babel/text-scan.d.ts +54 -0
- package/bounded-json.d.ts +33 -0
- package/deadline-guard.d.ts +16 -0
- package/dynamic-import.d.ts +25 -0
- package/enclave-options.d.ts +62 -0
- package/enclave.d.ts +35 -8
- package/esm/index.mjs +5520 -917
- package/esm/worker.mjs +2777 -195
- package/execution-deadline.d.ts +6 -0
- package/global-function-gate.d.ts +34 -1
- package/index.d.ts +3 -3
- package/index.js +5562 -959
- package/interpreter/interpreter.d.ts +207 -10
- package/memory-tracker.d.ts +7 -0
- package/package.json +3 -3
- package/portable-enclave.d.ts +51 -0
- package/portable-globals.d.ts +2 -0
- package/realm-airlock.d.ts +6 -1
- package/realm-memory.d.ts +89 -0
- package/realm-regex-backstop.d.ts +18 -0
- package/realm-stack.d.ts +25 -0
- package/safe-runtime.d.ts +2 -0
- package/sandbox-rejections.d.ts +3 -1
- package/scoring/feature-extractor.d.ts +52 -1
- package/scoring/index.d.ts +2 -1
- package/scoring/scorers/index.d.ts +2 -1
- package/scoring/scorers/local-llm.scorer.d.ts +9 -3
- package/scoring/scorers/progressive.scorer.d.ts +28 -1
- package/scoring/scorers/rule-based.scorer.d.ts +11 -1
- package/scoring/scoring-gate.d.ts +2 -0
- package/scoring/types.d.ts +36 -8
- package/secure-proxy.d.ts +17 -3
- package/session/session.d.ts +8 -1
- package/session-types.d.ts +6 -4
- package/sidecar/index.d.ts +1 -1
- package/sidecar/reference-config.d.ts +18 -1
- package/sidecar/reference-resolver.d.ts +26 -3
- package/sidecar/reference-sidecar.d.ts +37 -0
- package/src/adapters/worker-pool/package.json +3 -3
- package/src/adapters/worker-pool/worker-script.js +2835 -465
- package/thrown-value.d.ts +59 -0
- package/types.d.ts +85 -19
- package/value-sanitizer.d.ts +6 -1
- package/worker.d.ts +2 -0
- package/worker.js +2767 -195
package/README.md
CHANGED
|
@@ -17,7 +17,7 @@ The @enclave-vm/core package provides a hardened execution environment for runni
|
|
|
17
17
|
| CVE Protection | Covers known vm2, isolated-vm, node-vm exploits |
|
|
18
18
|
| Defense Layers | 6 (Pre-Scanner, AST, Transform, Scoring, VM/Worker Pool, Sanitization) |
|
|
19
19
|
|
|
20
|
-
For the full security audit report, see [SECURITY-AUDIT.md](./SECURITY-AUDIT.md).
|
|
20
|
+
For the full security audit report, see [SECURITY-AUDIT.md](./SECURITY-AUDIT.md). The invariants of the sandbox by layer, and the ones that are still open, are listed in [SECURITY-TESTS.md](../../SECURITY-TESTS.md): in process the time and memory limits are the enclave's own accounting, not the engine's (see [How `timeout` Is Enforced](#how-timeout-is-enforced) and [What `memoryLimit` Counts](#what-memorylimit-counts)).
|
|
21
21
|
|
|
22
22
|
## Features
|
|
23
23
|
|
|
@@ -26,8 +26,8 @@ For the full security audit report, see [SECURITY-AUDIT.md](./SECURITY-AUDIT.md)
|
|
|
26
26
|
- **Safe Tool Calls**: Secure `callTool()` execution with iteration and call limits
|
|
27
27
|
- **Reference Sidecar**: Handle large data without embedding it in the script
|
|
28
28
|
- **Configurable Security Levels**: From STRICT to PERMISSIVE based on trust level
|
|
29
|
-
- **Resource Limits**: Timeout, iteration limits, and tool call limits
|
|
30
|
-
- **AI Scoring Gate**:
|
|
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
31
|
- **Zero Dependencies on Vulnerable Packages**: Uses Node.js native `vm` module
|
|
32
32
|
|
|
33
33
|
## Installation
|
|
@@ -73,6 +73,33 @@ if (result.success) {
|
|
|
73
73
|
enclave.dispose();
|
|
74
74
|
```
|
|
75
75
|
|
|
76
|
+
### Portable AgentScript runner
|
|
77
|
+
|
|
78
|
+
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
|
+
|
|
80
|
+
```typescript
|
|
81
|
+
import { AgentScriptRunner } from '@enclave-vm/core/worker';
|
|
82
|
+
|
|
83
|
+
const runner = new AgentScriptRunner({
|
|
84
|
+
securityLevel: 'STANDARD',
|
|
85
|
+
timeout: 5000,
|
|
86
|
+
maxSteps: 1_000_000,
|
|
87
|
+
maxToolCalls: 20,
|
|
88
|
+
maxHostFunctionCalls: 200,
|
|
89
|
+
hostFunctions: { getTool: (name) => ({ name }) },
|
|
90
|
+
toolHandler: async (name, args) => ({ name, args }),
|
|
91
|
+
});
|
|
92
|
+
|
|
93
|
+
try {
|
|
94
|
+
const result = await runner.run("return getTool('example').name;");
|
|
95
|
+
console.log(result);
|
|
96
|
+
} finally {
|
|
97
|
+
runner.dispose();
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The runner supports Node and Cloudflare Workers with `nodejs_compat`. Tool and host-function arguments and results cross as bounded plain data. Steps, call depth, pending calls, allocation, tool calls, console output, bridge payloads and sidecar storage all have finite limits. `maxSteps` bounds interpreted CPU work, including work charged for built-in operations. `timeout` is checked between interpreter steps and at I/O boundaries; deployed Cloudflare Workers do not advance their clocks during CPU-only work, so it is not a hard wall-time cutoff there. Synchronous host callbacks cannot be preempted. Unsupported VM-only options and pre-scan overrides fail at construction.
|
|
102
|
+
|
|
76
103
|
## Configuration
|
|
77
104
|
|
|
78
105
|
### CreateEnclaveOptions
|
|
@@ -80,13 +107,15 @@ enclave.dispose();
|
|
|
80
107
|
```typescript
|
|
81
108
|
interface CreateEnclaveOptions {
|
|
82
109
|
// Execution limits
|
|
83
|
-
timeout?: number; // Execution timeout in ms (default:
|
|
110
|
+
timeout?: number; // Execution timeout in ms (default: 30000; by security level)
|
|
84
111
|
toolCallGraceMs?: number; // How long a tool call in progress at the timeout may still take (default: same as timeout)
|
|
85
|
-
maxToolCalls?: number; // Maximum tool calls allowed (default: 100)
|
|
86
|
-
maxIterations?: number; // Maximum loop iterations (default: 10000)
|
|
112
|
+
maxToolCalls?: number; // Maximum tool calls allowed (default: 100; by security level)
|
|
113
|
+
maxIterations?: number; // Maximum loop iterations (default: 10000; by security level)
|
|
114
|
+
memoryLimit?: number; // Memory limit in bytes, as the enclave counts it (default: 1048576, 1 MB; 0: off)
|
|
87
115
|
|
|
88
116
|
// Security
|
|
89
|
-
securityLevel?: SecurityLevel; // STRICT | SECURE | STANDARD | PERMISSIVE
|
|
117
|
+
securityLevel?: SecurityLevel; // 'STRICT' | 'SECURE' | 'STANDARD' | 'PERMISSIVE' (default: 'STANDARD')
|
|
118
|
+
preset?: AstPreset; // AST validation preset (default: 'agentscript')
|
|
90
119
|
validate?: boolean; // Enable AST validation (default: true)
|
|
91
120
|
transform?: boolean; // Enable code transformation (default: true)
|
|
92
121
|
realmGlobals?: 'allowlist' | 'security-level'; // What exists in the script's realm (see "What the Script's Realm Holds")
|
|
@@ -115,11 +144,41 @@ interface CreateEnclaveOptions {
|
|
|
115
144
|
// Sidecar (large data handling)
|
|
116
145
|
sidecar?: ReferenceSidecarOptions;
|
|
117
146
|
|
|
147
|
+
// Scoring gate
|
|
148
|
+
scoringGate?: ScoringGateConfig; // See "AI Scoring Gate" section
|
|
149
|
+
|
|
118
150
|
// Double VM security layer
|
|
119
151
|
doubleVm?: PartialDoubleVmConfig; // See "Double VM Security Layer" section
|
|
120
152
|
}
|
|
121
153
|
```
|
|
122
154
|
|
|
155
|
+
### Option Values
|
|
156
|
+
|
|
157
|
+
The constructor checks its options and throws a `TypeError` for a value outside the documented type or range:
|
|
158
|
+
|
|
159
|
+
- A limit is a finite integer in its range: `timeout` from 1 to 2147483647 (the longest delay a timer holds); `maxIterations`, `maxSanitizeDepth` and `maxSanitizeProperties` at least 1; `maxToolCalls`, `maxConsoleCalls`, `maxConsoleOutputBytes`, `maxGlobalFunctionCalls` and `memoryLimit` at least 0. `Infinity`, `NaN` and a value of another type (a numeric string, `null`) are refused. The one exception is `toolCallGraceMs`, a number of at least 0 for which `Infinity` means "wait without limit".
|
|
160
|
+
- A switch is a boolean: `validate`, `transform`, `sanitizeStackTraces`, `allowFunctionsInGlobals`, `allowBuiltins`, `doubleVm.enabled`, and the switches of `secureProxyConfig` and `doubleVm.parentValidation`.
|
|
161
|
+
- `securityLevel` is one of the four levels.
|
|
162
|
+
- An option passed as `undefined` is an option that was not set: it has its default, which is the security level's value where the level sets one. A wrapper can forward `{ maxIterations: opts.maxIterations }` whether or not its caller set it.
|
|
163
|
+
|
|
164
|
+
### Limits on the Script Itself
|
|
165
|
+
|
|
166
|
+
- **Size.** A script is at most 5,242,880 characters. A longer one, or a script that is not a string, fails with `VALIDATION_ERROR` before anything parses it.
|
|
167
|
+
- **Dynamic import.** A script that contains `import()` or `import.meta` is refused before it runs. Every preset refuses it during validation; with `validate: false` it fails with `SECURITY_VIOLATION`. The word in a string, a comment or a property name is not the construct.
|
|
168
|
+
- **Iteration limit.** A script that declares `__maxIterations`, the runtime's name for the limit, is refused. With validation off the limit still holds: each loop is compared with a number in its own code.
|
|
169
|
+
|
|
170
|
+
### What `memoryLimit` Counts
|
|
171
|
+
|
|
172
|
+
`memoryLimit` (default 1 MB; `0` switches it off) is the enclave's own accounting of the operations that make data grow. It is not a limit of the engine's heap.
|
|
173
|
+
|
|
174
|
+
- **Text**: concatenation (`a + b`, and `x += y`, which is charged like `x + y`) and the methods that multiply their input (`repeat`, `padStart`, `padEnd`, `join`).
|
|
175
|
+
- **Arrays**: no single array is larger than the limit holds, at 8 bytes per element, and what an operation adds is charged: `push`, `unshift`, `splice`, `fill`, the elements `concat`, `flat`, `flatMap` and a spread literal add, and what `Array.from` makes out of something that is not an array.
|
|
176
|
+
- **Not counted by the VM adapter**: a copy is free, so a script can hold many arrays that are each within the limit; object literals, Maps and Sets are not counted.
|
|
177
|
+
|
|
178
|
+
The portable interpreter additionally charges copied host-function results and tool responses by their serialized size to the cumulative allocation budget.
|
|
179
|
+
|
|
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-optional), whose workers have a heap limit of the engine, or a child process or container with a memory limit of the operating system.
|
|
181
|
+
|
|
123
182
|
### Security Levels
|
|
124
183
|
|
|
125
184
|
| Level | Description | Use Case |
|
|
@@ -130,10 +189,10 @@ interface CreateEnclaveOptions {
|
|
|
130
189
|
| `PERMISSIVE` | Adds console for debugging | Internal/development |
|
|
131
190
|
|
|
132
191
|
```typescript
|
|
133
|
-
import { Enclave
|
|
192
|
+
import { Enclave } from '@enclave-vm/core';
|
|
134
193
|
|
|
135
194
|
const enclave = new Enclave({
|
|
136
|
-
securityLevel:
|
|
195
|
+
securityLevel: 'STRICT',
|
|
137
196
|
toolHandler: async (name, args) => {
|
|
138
197
|
/* ... */
|
|
139
198
|
},
|
|
@@ -240,7 +299,7 @@ import { Enclave } from '@enclave-vm/core';
|
|
|
240
299
|
|
|
241
300
|
const enclave = new Enclave({
|
|
242
301
|
preset: 'agentscript', // AST validation preset (default)
|
|
243
|
-
securityLevel:
|
|
302
|
+
securityLevel: 'STRICT', // Runtime security level
|
|
244
303
|
toolHandler: async (name, args) => {
|
|
245
304
|
/* ... */
|
|
246
305
|
},
|
|
@@ -312,23 +371,49 @@ A worker thread is **not a sandbox by itself**: it has the whole Node.js API and
|
|
|
312
371
|
|
|
313
372
|
### Worker Pool Configuration Options
|
|
314
373
|
|
|
315
|
-
| Option | Default | Description
|
|
316
|
-
| ------------------------ | --------- |
|
|
317
|
-
| `minWorkers` | 2 | Minimum warm workers
|
|
318
|
-
| `maxWorkers` | CPU count | Maximum concurrent workers
|
|
319
|
-
| `memoryLimitPerWorker` | 128MB | Heap limit of each worker (its old generation); 0: none
|
|
320
|
-
| `maxMessagesPerSecond` | 1000 |
|
|
321
|
-
| `
|
|
322
|
-
| `
|
|
323
|
-
| `
|
|
374
|
+
| Option | Default | Description |
|
|
375
|
+
| ------------------------ | --------- | ---------------------------------------------------------------- |
|
|
376
|
+
| `minWorkers` | 2 | Minimum warm workers |
|
|
377
|
+
| `maxWorkers` | CPU count | Maximum concurrent workers |
|
|
378
|
+
| `memoryLimitPerWorker` | 128MB | Heap limit of each worker (its old generation); 0: none |
|
|
379
|
+
| `maxMessagesPerSecond` | 1000 | Messages a worker may send per second while it runs an execution |
|
|
380
|
+
| `maxPendingToolCalls` | 100 | Tool calls one execution may have in flight |
|
|
381
|
+
| `maxMessageSizeBytes` | 16MB | Largest single message a worker may send |
|
|
382
|
+
| `maxExecutionsPerWorker` | 1000 | Recycle after N executions |
|
|
383
|
+
| `maxQueueSize` | 100 | Maximum pending executions |
|
|
384
|
+
| `queueTimeoutMs` | 30000 | Longest wait for a free worker |
|
|
385
|
+
| `idleTimeoutMs` | 30000 | Time before idle worker release |
|
|
386
|
+
|
|
387
|
+
These are the defaults of `WorkerPoolConfig`. An enclave starts from the preset of its security level (the table above, exported as `WORKER_POOL_PRESETS`), and `workerPoolConfig` overrides single settings of it.
|
|
324
388
|
|
|
325
389
|
Executions beyond `maxWorkers` wait in a queue (`maxQueueSize`, `queueTimeoutMs`). The wait counts against the script's `timeout`, so size `maxWorkers` for the concurrency you expect.
|
|
326
390
|
|
|
391
|
+
`maxMessagesPerSecond` is counted per execution: what an earlier execution sent from the same worker is not held against the next one, and the result and the worker's confirmation that it is idle are not counted. `maxMessageSizeBytes` is applied before a message is parsed. The limit an execution gets is never below what the enclave's own limits let one message carry (a tool request of `toolBridge.maxPayloadBytes`, a result of `memoryLimit`), so it decides where those are larger than it or off: with `memoryLimit: 0` it is the only bound on the size of a result.
|
|
392
|
+
|
|
393
|
+
### How a Worker Execution Ends
|
|
394
|
+
|
|
395
|
+
A worker runs one execution at a time. After its result it confirms that it is idle, which it can only do when nothing of the script keeps its thread busy, and only then is it given to the next execution. A worker that does not confirm within one second is terminated and replaced; the result it sent stands.
|
|
396
|
+
|
|
397
|
+
An execution the pool ends itself ends its worker too, and the pool starts a new one. `run()` then returns `error.code` `EXECUTION_ERROR` with one of these in `error.name`:
|
|
398
|
+
|
|
399
|
+
| `error.name` | When |
|
|
400
|
+
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
401
|
+
| `WorkerTimeoutError` | The script was still running five seconds after its `timeout` |
|
|
402
|
+
| `WorkerMemoryError` | The worker held more than its memory budget while it executed (see [The Worker Heap Limit](#the-worker-heap-limit)) |
|
|
403
|
+
| `MessageFloodError` | The execution sent more than `maxMessagesPerSecond` messages |
|
|
404
|
+
| `MessageSizeError` | A message from the worker was larger than the limit |
|
|
405
|
+
| `TooManyPendingCallsError` | More than `maxPendingToolCalls` tool calls were in flight |
|
|
406
|
+
| `MessageValidationError` | A message from the worker did not pass the protocol schema |
|
|
407
|
+
| `ExecutionAbortedError` | The pool was disposed while the execution was in flight, or the script's time had passed before it started (it is not run) |
|
|
408
|
+
| `QueueFullError`, `QueueTimeoutError` | No worker became free: the queue was full, or the wait exceeded `queueTimeoutMs` |
|
|
409
|
+
|
|
410
|
+
`dispose()` ends the executions in flight with `ExecutionAbortedError` and terminates every worker.
|
|
411
|
+
|
|
327
412
|
### The Worker Heap Limit
|
|
328
413
|
|
|
329
414
|
`memoryLimitPerWorker` is the limit of the worker's old generation, passed to the engine as the worker's `resourceLimits`. The engine allows the young generation on top of it, and the pool sets that to 24 MB, so the most a worker can hold is the sum of the two: its budget. (Left to the engine the young generation of such a worker is 192 MB on Node.js 24 and 48 MB on Node.js 22, measured on a 64-bit machine.)
|
|
330
415
|
|
|
331
|
-
**A heap flag on the process replaces it.** When the host process runs with `--max-old-space-size`, on the command line or in `NODE_OPTIONS`, that value becomes the heap limit of every worker thread, whatever limit a worker was created with (this is Node.js behaviour; `worker.resourceLimits` goes on reporting the limit that was asked for). The pool therefore reads the actual limit of each new worker. When the engine does not apply the configured one, the pool logs a warning once and enforces the limit itself: while a worker executes, it reads the worker's heap every 100 ms and terminates the worker when its heap and external memory exceed the budget. The execution fails with `WorkerMemoryError`. This is approximate, because a script can allocate between two reads: with a 64 MB limit and `--max-old-space-size=4096`, a script that kept allocating was stopped when its worker held about 290 MB, with the process at 0.5 GB resident; without the check it went on until the process was at 4.4 GB. Reading a worker's heap from outside needs Node.js 22.16 or later; on an older 22.x the pool can only warn that the limit is not enforced.
|
|
416
|
+
**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.
|
|
332
417
|
|
|
333
418
|
**The memory monitor** (`memoryCheckIntervalMs`) asks every worker for its memory use and recycles a worker that holds more than its budget. It compares what the worker itself holds, its heap plus its external memory. (`rss` is no measure of a worker: inside a worker thread it is the resident size of the whole process.)
|
|
334
419
|
|
|
@@ -360,7 +445,8 @@ Executions beyond `maxWorkers` wait in a queue (`maxQueueSize`, `queueTimeoutMs`
|
|
|
360
445
|
- **`resourceLimits`**: a heap limit per worker, enforced by V8, or by the pool when a heap flag of the process overrides it ([The Worker Heap Limit](#the-worker-heap-limit))
|
|
361
446
|
- **The host does not trust a worker**: every message is parsed without prototype pollution and checked against the protocol schema (types, identifier and tool-name patterns, sizes); a message that fails ends the execution and replaces the worker
|
|
362
447
|
- **JSON-only messages**: no structured clone of objects in either direction
|
|
363
|
-
- **Rate
|
|
448
|
+
- **Rate and size limits**: the messages a worker may send per second, counted per execution, and the size of one message
|
|
449
|
+
- **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
|
|
364
450
|
- **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))
|
|
365
451
|
|
|
366
452
|
## Double VM Security Layer
|
|
@@ -473,7 +559,7 @@ const enclave = new Enclave({
|
|
|
473
559
|
|
|
474
560
|
## AI Scoring Gate
|
|
475
561
|
|
|
476
|
-
The AI Scoring Gate
|
|
562
|
+
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.
|
|
477
563
|
|
|
478
564
|
### Configuration
|
|
479
565
|
|
|
@@ -482,31 +568,54 @@ const enclave = new Enclave({
|
|
|
482
568
|
toolHandler: async (name, args) => {
|
|
483
569
|
/* ... */
|
|
484
570
|
},
|
|
485
|
-
|
|
571
|
+
scoringGate: {
|
|
486
572
|
scorer: 'rule-based', // 'disabled' | 'rule-based' | 'local-llm' | 'external-api'
|
|
487
|
-
blockThreshold: 70, //
|
|
488
|
-
warnThreshold: 40, //
|
|
573
|
+
blockThreshold: 70, // Do not run the script if score >= 70
|
|
574
|
+
warnThreshold: 40, // Set scoringResult.warned if score >= 40
|
|
575
|
+
failOpen: true, // Run the script when scoring fails (default)
|
|
489
576
|
},
|
|
490
577
|
});
|
|
491
578
|
```
|
|
492
579
|
|
|
580
|
+
| Option | Default | Description |
|
|
581
|
+
| ---------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
|
|
582
|
+
| `scorer` | `'disabled'` | Which scorer answers |
|
|
583
|
+
| `scoring` | - | Progressive scoring: the rule-based scorer first, a detailed scorer for scripts that score high |
|
|
584
|
+
| `blockThreshold` | 70 | A script with a score at or above it is not run |
|
|
585
|
+
| `warnThreshold` | 40 | A script with a score at or above it runs, with `scoringResult.warned` set |
|
|
586
|
+
| `failOpen` | `true` | Whether a script runs when the scorer cannot give its answer |
|
|
587
|
+
| `customRules` | - | Base scores of the rule-based scorer by rule id (0-100; 0 turns a rule off) |
|
|
588
|
+
| `toolNamespaces` | the enclave's `toolNamespaces` | The namespaces whose method calls are scored as tool calls |
|
|
589
|
+
| `localLlm` | - | Configuration of the `local-llm` scorer |
|
|
590
|
+
| `externalApi` | - | `endpoint`, `apiKey`, `timeoutMs`, `retries`, `headers` of the `external-api` scorer |
|
|
591
|
+
| `cache` | enabled, 5 minutes, 1,000 | Cache of scoring results by the SHA-256 digest of the script |
|
|
592
|
+
| `verbose` | `false` | Log scores and signals to the console |
|
|
593
|
+
|
|
594
|
+
A scoring failure is anything that keeps the configured scorer from giving its answer: a script the feature extractor cannot parse (`FeatureExtractionError`), a scorer that throws, and in progressive mode a detailed scorer that fails or is missing once the fast score called for it. With `failOpen: false` each of these refuses the script; with `failOpen: true` the script runs.
|
|
595
|
+
|
|
596
|
+
A refused script fails with `SCORING_BLOCKED`; `error.data` holds `totalScore`, `riskLevel` and `signals`. A result of a script the gate evaluated carries `scoringResult`.
|
|
597
|
+
|
|
598
|
+
A call through a tool namespace (`mail.send(args)`) is scored as the tool call it stands for (`callTool('mail.send', args)`): the gate of an enclave knows the enclave's `toolNamespaces`.
|
|
599
|
+
|
|
493
600
|
### Scorer Types
|
|
494
601
|
|
|
495
|
-
| Type |
|
|
496
|
-
| -------------- |
|
|
497
|
-
| `disabled` | No scoring
|
|
498
|
-
| `rule-based` |
|
|
499
|
-
| `local-llm` |
|
|
500
|
-
| `external-api` |
|
|
602
|
+
| Type | What the score is computed from |
|
|
603
|
+
| -------------- | --------------------------------------------------------------------------------------------------------- |
|
|
604
|
+
| `disabled` | No scoring |
|
|
605
|
+
| `rule-based` | Eight TypeScript rules over the extracted features, zero dependencies |
|
|
606
|
+
| `local-llm` | Your `customAnalyzer`, or a built-in keyword heuristic over the extracted features (no model computes it) |
|
|
607
|
+
| `external-api` | The answer of your scoring service, which receives the extracted features |
|
|
608
|
+
|
|
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.
|
|
501
610
|
|
|
502
611
|
### Custom Analyzer (Extensibility)
|
|
503
612
|
|
|
504
|
-
|
|
613
|
+
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:
|
|
505
614
|
|
|
506
615
|
```typescript
|
|
507
|
-
import { Enclave,
|
|
616
|
+
import { Enclave, type LocalLlmConfig } from '@enclave-vm/core';
|
|
508
617
|
|
|
509
|
-
const myAnalyzer:
|
|
618
|
+
const myAnalyzer: NonNullable<LocalLlmConfig['customAnalyzer']> = {
|
|
510
619
|
async analyze(prompt, features) {
|
|
511
620
|
// Call your external LLM or static analyzer
|
|
512
621
|
const response = await fetch('https://my-analyzer-api.com/score', {
|
|
@@ -559,17 +668,15 @@ interface CustomAnalyzer {
|
|
|
559
668
|
|
|
560
669
|
## Reference Sidecar
|
|
561
670
|
|
|
562
|
-
The Reference Sidecar
|
|
563
|
-
|
|
564
|
-
- Tool responses contain large datasets
|
|
565
|
-
- You need to pass large data between tool calls
|
|
566
|
-
- Script size must be kept small for security validation
|
|
671
|
+
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.
|
|
567
672
|
|
|
568
673
|
### How It Works
|
|
569
674
|
|
|
570
|
-
1. **
|
|
571
|
-
2. **
|
|
572
|
-
3. **
|
|
675
|
+
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
|
+
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
|
+
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
|
+
|
|
679
|
+
The sidecar belongs to one execution and is disposed when `run()` returns.
|
|
573
680
|
|
|
574
681
|
### Enabling Sidecar
|
|
575
682
|
|
|
@@ -582,23 +689,36 @@ const enclave = new Enclave({
|
|
|
582
689
|
enabled: true,
|
|
583
690
|
maxTotalSize: 10 * 1024 * 1024, // 10MB total storage
|
|
584
691
|
maxReferenceSize: 1 * 1024 * 1024, // 1MB per reference
|
|
585
|
-
extractionThreshold: 1024, //
|
|
586
|
-
maxResolvedSize: 5 * 1024 * 1024, // 5MB
|
|
587
|
-
allowComposites: false, //
|
|
692
|
+
extractionThreshold: 1024, // Store strings of 1KB and more
|
|
693
|
+
maxResolvedSize: 5 * 1024 * 1024, // 5MB resolved for one tool call
|
|
694
|
+
allowComposites: false, // Refuse string concatenation with refs
|
|
588
695
|
},
|
|
589
696
|
});
|
|
590
697
|
```
|
|
591
698
|
|
|
592
699
|
### Sidecar Options
|
|
593
700
|
|
|
594
|
-
| Option
|
|
595
|
-
|
|
|
596
|
-
| `enabled`
|
|
597
|
-
| `maxTotalSize`
|
|
598
|
-
| `maxReferenceSize`
|
|
599
|
-
| `extractionThreshold`
|
|
600
|
-
| `maxResolvedSize`
|
|
601
|
-
| `
|
|
701
|
+
| Option | Type | Default | Description |
|
|
702
|
+
| ---------------------- | --------- | -------------------- | ------------------------------------------------------------------------ |
|
|
703
|
+
| `enabled` | `boolean` | `false` | Enable the sidecar feature |
|
|
704
|
+
| `maxTotalSize` | `number` | by level | Maximum total size of all stored references |
|
|
705
|
+
| `maxReferenceSize` | `number` | by level | Maximum size of a single reference |
|
|
706
|
+
| `extractionThreshold` | `number` | by level | Size in bytes from which a string is stored |
|
|
707
|
+
| `maxResolvedSize` | `number` | by level | Maximum size the references in the arguments of one tool call resolve to |
|
|
708
|
+
| `maxTotalResolvedSize` | `number` | twice `maxTotalSize` | Maximum size of everything one execution resolves for its tool calls |
|
|
709
|
+
| `maxReferenceCount` | `number` | by level | Maximum number of references in one execution |
|
|
710
|
+
| `allowComposites` | `boolean` | by level | Allow string concatenation with reference tokens |
|
|
711
|
+
|
|
712
|
+
| Default | STRICT | SECURE | STANDARD | PERMISSIVE |
|
|
713
|
+
| --------------------- | ------- | ------- | -------- | ---------- |
|
|
714
|
+
| `maxTotalSize` | 16 MB | 64 MB | 256 MB | 1 GB |
|
|
715
|
+
| `maxReferenceSize` | 4 MB | 16 MB | 64 MB | 256 MB |
|
|
716
|
+
| `extractionThreshold` | 64 KB | 256 KB | 1 MB | 4 MB |
|
|
717
|
+
| `maxResolvedSize` | 8 MB | 32 MB | 128 MB | 512 MB |
|
|
718
|
+
| `maxReferenceCount` | 50 | 100 | 500 | 1,000 |
|
|
719
|
+
| `allowComposites` | `false` | `false` | `true` | `true` |
|
|
720
|
+
|
|
721
|
+
`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.
|
|
602
722
|
|
|
603
723
|
### Example with Sidecar
|
|
604
724
|
|
|
@@ -606,36 +726,38 @@ const enclave = new Enclave({
|
|
|
606
726
|
const enclave = new Enclave({
|
|
607
727
|
sidecar: {
|
|
608
728
|
enabled: true,
|
|
609
|
-
extractionThreshold: 100, //
|
|
610
|
-
allowComposites: false, //
|
|
729
|
+
extractionThreshold: 100, // Store strings of 100 bytes and more
|
|
730
|
+
allowComposites: false, // Refuse: ref + "suffix"
|
|
611
731
|
},
|
|
612
732
|
toolHandler: async (name, args) => {
|
|
613
|
-
if (name === '
|
|
614
|
-
//
|
|
615
|
-
return
|
|
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 };
|
|
616
740
|
}
|
|
617
741
|
},
|
|
618
742
|
});
|
|
619
743
|
|
|
620
744
|
const result = await enclave.run(`
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
// Access properties - resolved on demand
|
|
625
|
-
return { hasData: response.data.length > 0 };
|
|
745
|
+
const text = await callTool('getLargeText', {});
|
|
746
|
+
// text is a reference token here, not the data
|
|
747
|
+
return await callTool('saveText', { text });
|
|
626
748
|
`);
|
|
627
749
|
```
|
|
628
750
|
|
|
629
|
-
###
|
|
751
|
+
### Concatenation
|
|
630
752
|
|
|
631
|
-
|
|
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.
|
|
632
754
|
|
|
633
755
|
```javascript
|
|
634
|
-
//
|
|
635
|
-
const
|
|
756
|
+
// Throws when allowComposites is false
|
|
757
|
+
const combined = ref + '-suffix';
|
|
636
758
|
```
|
|
637
759
|
|
|
638
|
-
|
|
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.
|
|
639
761
|
|
|
640
762
|
## Tool Namespaces
|
|
641
763
|
|
|
@@ -801,33 +923,55 @@ interface ExecutionResult<T> {
|
|
|
801
923
|
error?: {
|
|
802
924
|
message: string;
|
|
803
925
|
name: string;
|
|
804
|
-
code?: string; // Error code (e.g., 'VALIDATION_ERROR'
|
|
805
|
-
stack?: string;
|
|
926
|
+
code?: string; // Error code (e.g., 'VALIDATION_ERROR'; see "Error Codes")
|
|
927
|
+
stack?: string; // Only for errors made outside the sandbox
|
|
806
928
|
data?: Record<string, unknown>;
|
|
807
929
|
};
|
|
808
930
|
stats: {
|
|
809
931
|
duration: number; // Execution time in ms
|
|
810
932
|
toolCallCount: number; // Number of tool calls made
|
|
811
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;
|
|
812
937
|
};
|
|
938
|
+
scoringResult?: ScoringGateResult; // When a scoring gate evaluated the script
|
|
813
939
|
}
|
|
814
940
|
```
|
|
815
941
|
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
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.
|
|
820
957
|
|
|
821
958
|
### Error Codes
|
|
822
959
|
|
|
823
|
-
| Code
|
|
824
|
-
|
|
|
825
|
-
| `VALIDATION_ERROR`
|
|
826
|
-
| `
|
|
827
|
-
| `
|
|
828
|
-
| `
|
|
829
|
-
| `
|
|
830
|
-
| `
|
|
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 ...`.
|
|
831
975
|
|
|
832
976
|
### How `timeout` Is Enforced
|
|
833
977
|
|
|
@@ -837,9 +981,10 @@ file locations in the remaining lines are redacted.
|
|
|
837
981
|
time has passed while it waited is not started: `run()` returns `ExecutionAbortedError`.
|
|
838
982
|
- Until the script's first `await`, Node's `vm` interrupts it at the deadline.
|
|
839
983
|
- After that, the script checks the clock itself: the transformer inserts a check at the start of
|
|
840
|
-
every function and loop body, so synchronous work, recursion
|
|
841
|
-
are stopped at the deadline as well. A script that catches
|
|
842
|
-
function or loop iteration.
|
|
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.
|
|
843
988
|
- A tool call in progress at the deadline is not cut off, and its result is delivered. From then on
|
|
844
989
|
the next tool call or call into a host function is refused with `Execution aborted`. The same
|
|
845
990
|
holds for an async function from `globals`.
|
|
@@ -851,7 +996,8 @@ file locations in the remaining lines are redacted.
|
|
|
851
996
|
settling).
|
|
852
997
|
- When `run()` has returned, for whatever reason, the script is finished for the host as well.
|
|
853
998
|
What it left behind (a tool call it did not await, with a `then` on it) can no longer call a
|
|
854
|
-
tool, a function from `globals` or the console
|
|
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`.
|
|
855
1001
|
- A script that only waits is ended as well. Waiting takes no code: a thenable that never calls
|
|
856
1002
|
back (`return { then: () => 0 }`) is enough, and nothing runs that could look at the clock. So
|
|
857
1003
|
the enclave keeps count of what the host has in flight for the script (tool calls, async
|
|
@@ -859,8 +1005,9 @@ file locations in the remaining lines are redacted.
|
|
|
859
1005
|
that count is zero. A sandbox has no timers and no I/O, so nothing else could wake the script.
|
|
860
1006
|
(With `adapter: 'worker_threads'` the pool ends such a script like a busy one: with its worker,
|
|
861
1007
|
five seconds after the deadline.)
|
|
862
|
-
- Not covered: a single built-in call that does all its work natively
|
|
863
|
-
|
|
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
|
|
864
1011
|
`toolHandler`: a call it stops waiting for keeps running in the host, so a tool that changes
|
|
865
1012
|
something should be safe to repeat, or have a time limit of its own. For a
|
|
866
1013
|
stop the script cannot influence, use `adapter: 'worker_threads'`: a script that is still
|
|
@@ -877,11 +1024,11 @@ file locations in the remaining lines are redacted.
|
|
|
877
1024
|
│
|
|
878
1025
|
▼
|
|
879
1026
|
┌─────────────────────────────────────────────────────────────┐
|
|
880
|
-
│ Layer 0: Pre-Scanner (ast-guard)
|
|
881
|
-
│ ├──
|
|
882
|
-
│ ├──
|
|
883
|
-
│ ├──
|
|
884
|
-
│ └──
|
|
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 │
|
|
885
1032
|
└─────────────────────────────────────────────────────────────┘
|
|
886
1033
|
│
|
|
887
1034
|
▼
|
|
@@ -889,8 +1036,9 @@ file locations in the remaining lines are redacted.
|
|
|
889
1036
|
│ Layer 1: AST Validation (ast-guard) │
|
|
890
1037
|
│ ├── NoEvalRule - Blocks eval(), Function() │
|
|
891
1038
|
│ ├── NoGlobalAccessRule - Blocks dangerous globals │
|
|
892
|
-
│ ├──
|
|
893
|
-
│
|
|
1039
|
+
│ ├── AllowedSyntaxRule - Syntax allowlist │
|
|
1040
|
+
│ ├── UnknownGlobalRule - Only the allowed globals │
|
|
1041
|
+
│ └── ReservedPrefixRule - Blocks reserved prefixes │
|
|
894
1042
|
└─────────────────────────────────────────────────────────────┘
|
|
895
1043
|
│
|
|
896
1044
|
▼
|
|
@@ -904,10 +1052,10 @@ file locations in the remaining lines are redacted.
|
|
|
904
1052
|
│
|
|
905
1053
|
▼
|
|
906
1054
|
┌─────────────────────────────────────────────────────────────┐
|
|
907
|
-
│ Layer 3: AI Scoring Gate
|
|
908
|
-
│ ├──
|
|
909
|
-
│ ├── Exfiltration
|
|
910
|
-
│ ├── Sensitive field
|
|
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 │
|
|
911
1059
|
│ └── Risk scoring (0-100) with thresholds │
|
|
912
1060
|
└─────────────────────────────────────────────────────────────┘
|
|
913
1061
|
│
|
|
@@ -927,9 +1075,9 @@ file locations in the remaining lines are redacted.
|
|
|
927
1075
|
▼
|
|
928
1076
|
┌─────────────────────────────────────────────────────────────┐
|
|
929
1077
|
│ Layer 5: Output Sanitization │
|
|
930
|
-
│ ├──
|
|
931
|
-
│ ├──
|
|
932
|
-
│ └──
|
|
1078
|
+
│ ├── Returned values copied into plain data │
|
|
1079
|
+
│ ├── Errors as bounded text, no stack from the sandbox │
|
|
1080
|
+
│ └── Refuses oversized return values │
|
|
933
1081
|
└─────────────────────────────────────────────────────────────┘
|
|
934
1082
|
│
|
|
935
1083
|
▼
|
|
@@ -938,6 +1086,44 @@ file locations in the remaining lines are redacted.
|
|
|
938
1086
|
└─────────────────────────────────────────────────────────────┘
|
|
939
1087
|
```
|
|
940
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.
|
|
1126
|
+
|
|
941
1127
|
## Runtime Notes
|
|
942
1128
|
|
|
943
1129
|
### Node.js 24 (V8 13.x)
|
|
@@ -1042,15 +1228,15 @@ the handler.
|
|
|
1042
1228
|
|
|
1043
1229
|
```bash
|
|
1044
1230
|
# Run tests
|
|
1045
|
-
nx test
|
|
1231
|
+
npx nx test core
|
|
1046
1232
|
|
|
1047
1233
|
# Run tests with coverage
|
|
1048
|
-
nx test
|
|
1234
|
+
npx nx test core --coverage
|
|
1049
1235
|
```
|
|
1050
1236
|
|
|
1051
1237
|
## Related Packages
|
|
1052
1238
|
|
|
1053
|
-
- [
|
|
1239
|
+
- [`@enclave-vm/ast`](../ast) - AST validation rules used by enclave
|
|
1054
1240
|
|
|
1055
1241
|
## License
|
|
1056
1242
|
|