@enclave-vm/core 2.15.2 → 2.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +98 -0
- package/adapters/worker-pool/protocol.d.ts +38 -1
- package/adapters/worker-pool/result-encoding.d.ts +33 -0
- package/adapters/worker-pool/worker-pool-adapter.d.ts +3 -4
- package/double-vm/parent-vm-bootstrap.d.ts +8 -0
- package/enclave.d.ts +16 -1
- package/esm/index.mjs +1308 -352
- package/esm/worker.mjs +158 -4
- package/global-function-gate.d.ts +74 -0
- package/globals-validator.d.ts +8 -1
- package/index.d.ts +1 -1
- package/index.js +1326 -371
- package/node-vm.d.ts +13 -0
- package/package.json +3 -3
- package/safe-error.d.ts +5 -1
- package/safe-runtime.d.ts +13 -2
- package/secure-proxy.d.ts +19 -0
- package/src/adapters/worker-pool/package.json +3 -3
- package/src/adapters/worker-pool/worker-script.js +318 -4
- package/stack-trace.d.ts +38 -0
- package/tool-namespaces.d.ts +38 -0
- package/types.d.ts +142 -4
- package/value-sanitizer.d.ts +6 -0
- package/worker.js +158 -4
package/README.md
CHANGED
|
@@ -91,10 +91,15 @@ interface CreateEnclaveOptions {
|
|
|
91
91
|
|
|
92
92
|
// Tool execution
|
|
93
93
|
toolHandler?: ToolHandler; // Function to execute tool calls
|
|
94
|
+
toolNamespaces?: ToolNamespaces; // Expose tools as `ns.method(args)` (see "Tool Namespaces")
|
|
94
95
|
|
|
95
96
|
// Custom globals
|
|
96
97
|
globals?: Record<string, unknown>; // Additional globals for the VM
|
|
97
98
|
allowFunctionsInGlobals?: boolean; // Allow functions in globals (default: false)
|
|
99
|
+
maxGlobalFunctionCalls?: number; // Cap on calls into functions from globals (default: 10 × maxToolCalls)
|
|
100
|
+
|
|
101
|
+
// Errors
|
|
102
|
+
sanitizeStackTraces?: boolean; // Redact paths/frames in every returned error (default: by security level)
|
|
98
103
|
|
|
99
104
|
// Sidecar (large data handling)
|
|
100
105
|
sidecar?: ReferenceSidecarOptions;
|
|
@@ -562,6 +567,65 @@ const malicious = ref + '__proto__'; // Attempting prototype pollution
|
|
|
562
567
|
|
|
563
568
|
Set `allowComposites: true` only if you need to concatenate strings and understand the security implications.
|
|
564
569
|
|
|
570
|
+
## Tool Namespaces
|
|
571
|
+
|
|
572
|
+
Expose tools to scripts as namespaced functions instead of (or alongside) `callTool()`:
|
|
573
|
+
|
|
574
|
+
```typescript
|
|
575
|
+
const enclave = new Enclave({
|
|
576
|
+
toolHandler: async (name, args) => callMyTool(name, args),
|
|
577
|
+
toolNamespaces: {
|
|
578
|
+
mail: ['list', 'send'], // mail.list(args) calls the tool 'mail.list'
|
|
579
|
+
users: { get: 'users:get' }, // users.get(args) calls the tool 'users:get'
|
|
580
|
+
},
|
|
581
|
+
});
|
|
582
|
+
|
|
583
|
+
const result = await enclave.run(`
|
|
584
|
+
const inbox = await mail.list({ unread: true });
|
|
585
|
+
const sender = await users.get({ id: inbox[0].from });
|
|
586
|
+
return sender.name;
|
|
587
|
+
`);
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
A namespace method call **is** a `callTool()` call: `mail.list(args, options)` behaves exactly like
|
|
591
|
+
`callTool('mail.list', args, options)`. It counts toward `maxToolCalls`, goes through the double VM's
|
|
592
|
+
rate limit, operation-name and suspicious-sequence checks, its result is sanitized, and it reaches your
|
|
593
|
+
`toolHandler`. `args` defaults to `{}`. Each namespace is a frozen, null-prototype object created
|
|
594
|
+
inside the sandbox, so aliasing (`const m = mail; m.list()`) and destructuring work and no host object
|
|
595
|
+
is exposed.
|
|
596
|
+
|
|
597
|
+
The constructor throws a `TypeError` (`Invalid toolNamespaces: ...`) for names that are not identifiers,
|
|
598
|
+
prototype keys (`__proto__`, `constructor`, `prototype`), names starting with `__`, reserved words and
|
|
599
|
+
sandbox globals used as namespaces (`callTool`, `Math`, `console`, ...), identifiers the AgentScript
|
|
600
|
+
validator refuses (`process`, `fetch`, ...), namespaces that collide with a custom global, duplicated
|
|
601
|
+
methods, and tool names every adapter cannot carry (empty, over 256 characters, or outside letters, digits,
|
|
602
|
+
`:`, `.`, `_` and `-` starting with a letter, including a generated `<namespace>.<method>` name).
|
|
603
|
+
|
|
604
|
+
Prefer namespaces over exposing tools as functions in `globals`: functions in `globals` are gated and
|
|
605
|
+
sanitized (see "Custom Globals"), but the suspicious-sequence detectors only see tool calls.
|
|
606
|
+
|
|
607
|
+
## callTool Options
|
|
608
|
+
|
|
609
|
+
Scripts can pass options as the third argument of `callTool` (or the second argument of a namespace
|
|
610
|
+
method):
|
|
611
|
+
|
|
612
|
+
```javascript
|
|
613
|
+
const r = await callTool('users:get', { id }, { throwOnError: false });
|
|
614
|
+
if (r.success) {
|
|
615
|
+
return r.data;
|
|
616
|
+
}
|
|
617
|
+
return { failed: r.error.message }; // r.error: { name, message, code?, toolName }
|
|
618
|
+
```
|
|
619
|
+
|
|
620
|
+
| Option | Default | Description |
|
|
621
|
+
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
622
|
+
| `throwOnError` | `true` | `false`: resolve to `{ success: true, data }` or, when the tool fails, `{ success: false, error }` instead of throwing |
|
|
623
|
+
|
|
624
|
+
Only failures of the tool itself (the handler threw or rejected, or its result could not be delivered)
|
|
625
|
+
are returned this way; the error object is plain data with no stack. Refusals by the enclave (abort,
|
|
626
|
+
`maxToolCalls`, rate limit, operation-name and suspicious-sequence checks, invalid arguments) always
|
|
627
|
+
throw. Options are applied inside the sandbox and are not passed to the `toolHandler`.
|
|
628
|
+
|
|
565
629
|
## Custom Globals
|
|
566
630
|
|
|
567
631
|
You can provide custom globals to the VM:
|
|
@@ -589,6 +653,31 @@ const result = await enclave.run(`
|
|
|
589
653
|
|
|
590
654
|
**Security Note**: Set `allowFunctionsInGlobals: true` only when you intentionally provide functions. Functions in globals can potentially leak host scope via closures.
|
|
591
655
|
|
|
656
|
+
Every call from the script into a function from `globals` (including functions nested in objects) goes
|
|
657
|
+
through the enclave's gate:
|
|
658
|
+
|
|
659
|
+
- it is refused once the execution is aborted, and counts toward `maxGlobalFunctionCalls`
|
|
660
|
+
(default: 10 × `maxToolCalls`), not toward `maxToolCalls`;
|
|
661
|
+
- in the double VM (the default) it shares the operation rate limit
|
|
662
|
+
(`doubleVm.parentValidation.maxOperationsPerSecond`) with tool calls;
|
|
663
|
+
- its return value is sanitized like a tool result: the script receives a plain-data copy, and a
|
|
664
|
+
value containing functions or symbols, or exceeding the sanitize depth/size limits, is refused;
|
|
665
|
+
- an error it throws reaches the script as a plain error without the host stack;
|
|
666
|
+
- calling it with `new` is refused.
|
|
667
|
+
|
|
668
|
+
The suspicious-sequence detectors only look at tool calls, so expose tools with `toolNamespaces` or
|
|
669
|
+
`callTool()`, not as functions. The `worker_threads` adapter never passes functions into the sandbox.
|
|
670
|
+
|
|
671
|
+
Inside arrays, Maps and Sets only plain data is allowed (primitives, plain objects, arrays, Maps, Sets,
|
|
672
|
+
Dates, RegExps, typed arrays): the built-in methods of those collections (`forEach`, iteration, `get`)
|
|
673
|
+
hand elements to the script directly, so a function (or an object with methods) stored there would be
|
|
674
|
+
called without the gate. The constructor refuses it with an error naming the path, e.g.
|
|
675
|
+
`Custom global "cfg" contains a function inside a collection at hooks.0.run`. Every own entry counts there,
|
|
676
|
+
enumerable or not, and Map and Set subclasses are refused inside collections. Arrays anywhere in `globals`
|
|
677
|
+
must be plain arrays (no Proxy, no custom prototype), since those can hide entries from validation.
|
|
678
|
+
Promises, WeakMaps, iterators and generators are refused anywhere in `globals`, since their contents cannot
|
|
679
|
+
be validated.
|
|
680
|
+
|
|
592
681
|
## Execution Result
|
|
593
682
|
|
|
594
683
|
```typescript
|
|
@@ -610,6 +699,11 @@ interface ExecutionResult<T> {
|
|
|
610
699
|
}
|
|
611
700
|
```
|
|
612
701
|
|
|
702
|
+
With `sanitizeStackTraces` on (the default for `STRICT` and `SECURE`), every returned `error.stack` is
|
|
703
|
+
sanitized, whichever stage raised the error (validation, transformation, compilation, execution, tool
|
|
704
|
+
calls) and whichever adapter ran the script: stack frames become `at [REDACTED]` and paths, URLs and
|
|
705
|
+
file locations in the remaining lines are redacted.
|
|
706
|
+
|
|
613
707
|
### Error Codes
|
|
614
708
|
|
|
615
709
|
| Code | Description |
|
|
@@ -713,6 +807,10 @@ class Enclave {
|
|
|
713
807
|
type ToolHandler = (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
|
|
714
808
|
```
|
|
715
809
|
|
|
810
|
+
Called for every `callTool()` and `toolNamespaces` method call that passes the enclave's checks. The
|
|
811
|
+
script's `callTool` options (`CallToolOptions`) are applied inside the sandbox and are not passed to
|
|
812
|
+
the handler.
|
|
813
|
+
|
|
716
814
|
## Testing
|
|
717
815
|
|
|
718
816
|
```bash
|
|
@@ -7,7 +7,9 @@
|
|
|
7
7
|
* @packageDocumentation
|
|
8
8
|
*/
|
|
9
9
|
import { z } from 'zod';
|
|
10
|
+
import { type NormalizedToolNamespace } from '@enclave-vm/ast';
|
|
10
11
|
import type { ResourceUsage } from './config';
|
|
12
|
+
import type { SpecialResultValue } from './result-encoding';
|
|
11
13
|
/**
|
|
12
14
|
* Serialized error format for cross-thread communication
|
|
13
15
|
* Errors are serialized to prevent prototype pollution
|
|
@@ -65,6 +67,11 @@ export interface SerializedConfig {
|
|
|
65
67
|
* Used for defense-in-depth with AST guard
|
|
66
68
|
*/
|
|
67
69
|
securityLevel: 'STRICT' | 'SECURE' | 'STANDARD' | 'PERMISSIVE';
|
|
70
|
+
/**
|
|
71
|
+
* Validated tool namespaces to bind in the sandbox (`mail.list(args)` calls the tool
|
|
72
|
+
* `mail.list` through the worker's callTool)
|
|
73
|
+
*/
|
|
74
|
+
toolNamespaces?: NormalizedToolNamespace[];
|
|
68
75
|
}
|
|
69
76
|
/**
|
|
70
77
|
* Execute code in the worker
|
|
@@ -91,6 +98,12 @@ export interface ToolResponseMessage {
|
|
|
91
98
|
result?: unknown;
|
|
92
99
|
/** Error (if failed) */
|
|
93
100
|
error?: SerializedError;
|
|
101
|
+
/**
|
|
102
|
+
* Set when the error is a failure of the tool itself (its handler threw or rejected), as
|
|
103
|
+
* opposed to the host refusing the call. A script's `callTool(..., { throwOnError: false })`
|
|
104
|
+
* receives only such failures as a result object.
|
|
105
|
+
*/
|
|
106
|
+
toolError?: boolean;
|
|
94
107
|
}
|
|
95
108
|
/**
|
|
96
109
|
* Request memory usage report from worker
|
|
@@ -147,8 +160,10 @@ export interface ExecutionResultMessage {
|
|
|
147
160
|
requestId: string;
|
|
148
161
|
/** Whether execution succeeded */
|
|
149
162
|
success: boolean;
|
|
150
|
-
/** Return value (if successful) */
|
|
163
|
+
/** Return value (if successful), as JSON data */
|
|
151
164
|
value?: unknown;
|
|
165
|
+
/** Values in `value` JSON cannot carry (Date, NaN, Infinity, undefined), restored by the pool */
|
|
166
|
+
specialValues?: SpecialResultValue[];
|
|
152
167
|
/** Error (if failed) */
|
|
153
168
|
error?: SerializedError;
|
|
154
169
|
/** Execution statistics */
|
|
@@ -196,6 +211,17 @@ export declare const executionResultMessageSchema: z.ZodObject<{
|
|
|
196
211
|
requestId: z.ZodString;
|
|
197
212
|
success: z.ZodBoolean;
|
|
198
213
|
value: z.ZodOptional<z.ZodUnknown>;
|
|
214
|
+
specialValues: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
215
|
+
path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
|
|
216
|
+
kind: z.ZodEnum<{
|
|
217
|
+
undefined: "undefined";
|
|
218
|
+
date: "date";
|
|
219
|
+
nan: "nan";
|
|
220
|
+
infinity: "infinity";
|
|
221
|
+
"-infinity": "-infinity";
|
|
222
|
+
}>;
|
|
223
|
+
time: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
|
|
224
|
+
}, z.core.$strict>>>;
|
|
199
225
|
error: z.ZodOptional<z.ZodObject<{
|
|
200
226
|
name: z.ZodString;
|
|
201
227
|
message: z.ZodString;
|
|
@@ -259,6 +285,17 @@ export declare const workerToMainMessageSchema: z.ZodDiscriminatedUnion<[z.ZodOb
|
|
|
259
285
|
requestId: z.ZodString;
|
|
260
286
|
success: z.ZodBoolean;
|
|
261
287
|
value: z.ZodOptional<z.ZodUnknown>;
|
|
288
|
+
specialValues: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
289
|
+
path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
|
|
290
|
+
kind: z.ZodEnum<{
|
|
291
|
+
undefined: "undefined";
|
|
292
|
+
date: "date";
|
|
293
|
+
nan: "nan";
|
|
294
|
+
infinity: "infinity";
|
|
295
|
+
"-infinity": "-infinity";
|
|
296
|
+
}>;
|
|
297
|
+
time: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
|
|
298
|
+
}, z.core.$strict>>>;
|
|
262
299
|
error: z.ZodOptional<z.ZodObject<{
|
|
263
300
|
name: z.ZodString;
|
|
264
301
|
message: z.ZodString;
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Worker Result Encoding
|
|
3
|
+
*
|
|
4
|
+
* Worker messages are JSON (see safe-deserialize), which has no Date, NaN, Infinity or
|
|
5
|
+
* undefined. The worker sends the sanitized script result as JSON plus the list of values JSON
|
|
6
|
+
* would lose, each with its path; the pool puts them back, so a worker result matches what the
|
|
7
|
+
* in-process adapters return.
|
|
8
|
+
*
|
|
9
|
+
* @packageDocumentation
|
|
10
|
+
*/
|
|
11
|
+
/** Keys and indices from the result's root to a value. */
|
|
12
|
+
export type ResultPath = Array<string | number>;
|
|
13
|
+
/** A value JSON cannot carry, sent next to the result and restored on the main thread. */
|
|
14
|
+
export interface SpecialResultValue {
|
|
15
|
+
path: ResultPath;
|
|
16
|
+
kind: 'date' | 'nan' | 'infinity' | '-infinity' | 'undefined';
|
|
17
|
+
/** Milliseconds since the epoch for a Date; null for an invalid Date. */
|
|
18
|
+
time?: number | null;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Split a sanitized result (plain data, no cycles) into JSON data, with `null` in place of each
|
|
22
|
+
* special value, and the list of special values. Keys the transport strips are left out.
|
|
23
|
+
*/
|
|
24
|
+
export declare function encodeResult(value: unknown): {
|
|
25
|
+
value: unknown;
|
|
26
|
+
specialValues: SpecialResultValue[];
|
|
27
|
+
};
|
|
28
|
+
/**
|
|
29
|
+
* Put the special values back into a deserialized result. Every entry must point at a `null`
|
|
30
|
+
* placeholder inside the result's arrays and plain objects; anything else means the message was
|
|
31
|
+
* not produced by `encodeResult`, and the result is refused.
|
|
32
|
+
*/
|
|
33
|
+
export declare function decodeResult(value: unknown, specialValues: unknown): unknown;
|
|
@@ -60,10 +60,9 @@ export declare class WorkerPoolAdapter implements SandboxAdapter {
|
|
|
60
60
|
/**
|
|
61
61
|
* Build result from worker message.
|
|
62
62
|
*
|
|
63
|
-
* Note: The `
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
* definitions which are not available at this layer.
|
|
63
|
+
* Note: The `as T` assertion is inherent to cross-thread serialization boundaries. The
|
|
64
|
+
* worker sanitizes the result with sanitizeValue() and sends the values JSON cannot carry
|
|
65
|
+
* (Dates, NaN, ...) separately; decodeResult() puts them back and refuses a malformed list.
|
|
67
66
|
*/
|
|
68
67
|
private buildResult;
|
|
69
68
|
/**
|
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
*
|
|
11
11
|
* @packageDocumentation
|
|
12
12
|
*/
|
|
13
|
+
import type { NormalizedToolNamespace } from '@enclave-vm/ast';
|
|
13
14
|
import type { SerializableParentValidationConfig, SerializableSuspiciousPattern } from './types';
|
|
14
15
|
import type { SecurityLevel } from '../types';
|
|
15
16
|
/**
|
|
@@ -53,6 +54,13 @@ export interface ParentVmBootstrapOptions {
|
|
|
53
54
|
memoryLimit?: number;
|
|
54
55
|
/** Whether to throw errors instead of returning undefined for blocked properties */
|
|
55
56
|
throwOnBlocked?: boolean;
|
|
57
|
+
/**
|
|
58
|
+
* Maximum number of calls into host functions passed in `globals`
|
|
59
|
+
* @default 1000
|
|
60
|
+
*/
|
|
61
|
+
maxGlobalFunctionCalls?: number;
|
|
62
|
+
/** Validated tool namespaces to bind in the inner VM */
|
|
63
|
+
toolNamespaces?: readonly NormalizedToolNamespace[];
|
|
56
64
|
}
|
|
57
65
|
/**
|
|
58
66
|
* Generate the parent VM bootstrap script
|
package/enclave.d.ts
CHANGED
|
@@ -49,6 +49,8 @@ export declare class Enclave {
|
|
|
49
49
|
private readonly scoringGate?;
|
|
50
50
|
private readonly doubleVmConfig;
|
|
51
51
|
private readonly customGlobalNames;
|
|
52
|
+
private readonly toolNamespaces;
|
|
53
|
+
private readonly sandboxAdapter?;
|
|
52
54
|
private adapter?;
|
|
53
55
|
constructor(options?: CreateEnclaveOptions);
|
|
54
56
|
/**
|
|
@@ -67,11 +69,23 @@ export declare class Enclave {
|
|
|
67
69
|
/**
|
|
68
70
|
* Execute AgentScript code
|
|
69
71
|
*
|
|
72
|
+
* Every error returned obeys `sanitizeStackTraces`, whichever stage raised it.
|
|
73
|
+
*
|
|
70
74
|
* @param code AgentScript code to execute
|
|
71
75
|
* @param toolHandler Optional tool handler (overrides constructor config)
|
|
72
76
|
* @returns Execution result
|
|
73
77
|
*/
|
|
74
78
|
run<T = unknown>(code: string, toolHandler?: ToolHandler): Promise<ExecutionResult<T>>;
|
|
79
|
+
/**
|
|
80
|
+
* Single exit for returned errors: with `sanitizeStackTraces` on, strip host paths, file
|
|
81
|
+
* locations and frames from the stack, whichever stage (validation, transform, compile,
|
|
82
|
+
* execution, tool call) and adapter produced the error.
|
|
83
|
+
*/
|
|
84
|
+
private applyStackTracePolicy;
|
|
85
|
+
/**
|
|
86
|
+
* Transform, validate and execute. `run` applies the stack-trace policy to what this returns.
|
|
87
|
+
*/
|
|
88
|
+
private execute;
|
|
75
89
|
/**
|
|
76
90
|
* Apply memory tracking transforms to code
|
|
77
91
|
*
|
|
@@ -96,7 +110,8 @@ export declare class Enclave {
|
|
|
96
110
|
/**
|
|
97
111
|
* Get or create the sandbox adapter
|
|
98
112
|
*
|
|
99
|
-
*
|
|
113
|
+
* A host-supplied `sandboxAdapter` is used as is. Otherwise, when double VM is enabled
|
|
114
|
+
* (default), the base adapter is wrapped
|
|
100
115
|
* with a double VM layer that provides:
|
|
101
116
|
* - Nested VM isolation (Parent VM + Inner VM)
|
|
102
117
|
* - Enhanced tool call validation
|