@enclave-vm/core 2.15.2 → 2.15.3
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 +12 -0
- package/double-vm/parent-vm-bootstrap.d.ts +8 -0
- package/enclave.d.ts +13 -0
- package/esm/index.mjs +1129 -327
- 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 +1148 -347
- package/package.json +3 -3
- package/safe-error.d.ts +5 -1
- package/safe-runtime.d.ts +13 -2
- package/secure-proxy.d.ts +12 -0
- package/src/adapters/worker-pool/package.json +3 -3
- package/src/adapters/worker-pool/worker-script.js +96 -3
- package/stack-trace.d.ts +38 -0
- package/tool-namespaces.d.ts +38 -0
- package/types.d.ts +117 -2
- package/worker.js +158 -4
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@enclave-vm/core",
|
|
3
|
-
"version": "2.15.
|
|
3
|
+
"version": "2.15.3",
|
|
4
4
|
"description": "Sandbox runtime for secure JavaScript code execution",
|
|
5
5
|
"author": "AgentFront <info@agentfront.dev>",
|
|
6
6
|
"homepage": "https://github.com/agentfront/enclave",
|
|
@@ -44,8 +44,8 @@
|
|
|
44
44
|
},
|
|
45
45
|
"dependencies": {
|
|
46
46
|
"@babel/standalone": "^7.29.0",
|
|
47
|
-
"@enclave-vm/ast": "2.15.
|
|
48
|
-
"@enclave-vm/types": "2.15.
|
|
47
|
+
"@enclave-vm/ast": "2.15.3",
|
|
48
|
+
"@enclave-vm/types": "2.15.3",
|
|
49
49
|
"@types/estree": "1.0.8",
|
|
50
50
|
"acorn": "8.15.0",
|
|
51
51
|
"acorn-walk": "8.3.4",
|
package/safe-error.d.ts
CHANGED
|
@@ -13,6 +13,10 @@
|
|
|
13
13
|
/**
|
|
14
14
|
* Create an Error instance whose prototype chain is severed (actual [[Prototype]]),
|
|
15
15
|
* preventing prototype-chain escape to host constructors.
|
|
16
|
+
*
|
|
17
|
+
* @param message Error message
|
|
18
|
+
* @param name Error name
|
|
19
|
+
* @param code Optional error code (a read-only own property)
|
|
16
20
|
*/
|
|
17
|
-
export declare function createSafeError(message: string, name?: string): Error;
|
|
21
|
+
export declare function createSafeError(message: string, name?: string, code?: string): Error;
|
|
18
22
|
export declare function createSafeTypeError(message: string): Error;
|
package/safe-runtime.d.ts
CHANGED
|
@@ -6,7 +6,8 @@
|
|
|
6
6
|
*
|
|
7
7
|
* @packageDocumentation
|
|
8
8
|
*/
|
|
9
|
-
import type { ExecutionContext, SecureProxyLevelConfig } from './types';
|
|
9
|
+
import type { CallToolOptions, ExecutionContext, SecureProxyLevelConfig } from './types';
|
|
10
|
+
import type { GlobalFunctionCallGate } from './global-function-gate';
|
|
10
11
|
import { ReferenceSidecar } from './sidecar/reference-sidecar';
|
|
11
12
|
import { ReferenceConfig } from './sidecar/reference-config';
|
|
12
13
|
import { MemoryTracker } from './memory-tracker';
|
|
@@ -35,6 +36,12 @@ export interface SafeRuntimeOptions {
|
|
|
35
36
|
* and enforce memory limits
|
|
36
37
|
*/
|
|
37
38
|
memoryTracker?: MemoryTracker;
|
|
39
|
+
/**
|
|
40
|
+
* Gate for calls into host functions passed in `globals` (see `createGlobalFunctionGate`).
|
|
41
|
+
* When provided, the custom globals are wrapped so every call into one of their functions goes
|
|
42
|
+
* through it.
|
|
43
|
+
*/
|
|
44
|
+
globalFunctionGate?: GlobalFunctionCallGate;
|
|
38
45
|
}
|
|
39
46
|
/**
|
|
40
47
|
* Create safe runtime context with all __safe_* functions
|
|
@@ -51,7 +58,7 @@ export declare function createSafeRuntime(context: ExecutionContext, options?: S
|
|
|
51
58
|
isFinite: typeof isFinite;
|
|
52
59
|
parseInt: typeof parseInt;
|
|
53
60
|
parseFloat: typeof parseFloat;
|
|
54
|
-
__safe_callTool: (toolName: string, args: Record<string, unknown
|
|
61
|
+
__safe_callTool: (toolName: string, args: Record<string, unknown>, options?: CallToolOptions) => Promise<unknown>;
|
|
55
62
|
__safe_forOf: <T>(iterable: Iterable<T>) => Iterable<T>;
|
|
56
63
|
__safe_for: (init: () => void, test: () => boolean, update: () => void, body: () => void) => void;
|
|
57
64
|
__safe_while: (test: () => boolean, body: () => void) => void;
|
|
@@ -67,6 +74,10 @@ export declare function createSafeRuntime(context: ExecutionContext, options?: S
|
|
|
67
74
|
* Serialize safe runtime code as a string for injection
|
|
68
75
|
* This is used by sandbox adapters that need to inject the runtime as code
|
|
69
76
|
*
|
|
77
|
+
* The adapter provides `__internal_callTool(toolName, args, options)`; `options` is the script's
|
|
78
|
+
* third `callTool` argument, so the adapter implements `{ throwOnError: false }` (a failure of the
|
|
79
|
+
* tool resolves to `{ success: false, error }`, a success to `{ success: true, data }`).
|
|
80
|
+
*
|
|
70
81
|
* @returns JavaScript code string containing the safe runtime
|
|
71
82
|
*/
|
|
72
83
|
export declare function serializeSafeRuntime(): string;
|
package/secure-proxy.d.ts
CHANGED
|
@@ -142,6 +142,18 @@ export interface SecureProxyOptions {
|
|
|
142
142
|
* - Explicitly set `throwOnBlocked: false` in options
|
|
143
143
|
*/
|
|
144
144
|
throwOnBlocked?: boolean;
|
|
145
|
+
/**
|
|
146
|
+
* Gate for calls into wrapped functions (used for host functions passed in `globals`).
|
|
147
|
+
*
|
|
148
|
+
* When set, a call through this proxy, or through any proxy derived from it (a method read off
|
|
149
|
+
* a wrapped object), whose target `gates()` accepts is handed to `call(target, thisArg, args)`
|
|
150
|
+
* instead of being invoked directly, and its return value is returned unwrapped: the gate is
|
|
151
|
+
* responsible for producing a sandbox-safe value. Calling such a function with `new` is refused.
|
|
152
|
+
*/
|
|
153
|
+
callGate?: {
|
|
154
|
+
gates(target: unknown): boolean;
|
|
155
|
+
call(target: unknown, thisArg: unknown, args: unknown[]): unknown;
|
|
156
|
+
};
|
|
145
157
|
}
|
|
146
158
|
/**
|
|
147
159
|
* Create a secure proxy that blocks dangerous property access
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@enclave-vm/core",
|
|
3
|
-
"version": "2.15.
|
|
3
|
+
"version": "2.15.3",
|
|
4
4
|
"description": "Sandbox runtime for secure JavaScript code execution",
|
|
5
5
|
"author": "AgentFront <info@agentfront.dev>",
|
|
6
6
|
"homepage": "https://github.com/agentfront/enclave",
|
|
@@ -46,8 +46,8 @@
|
|
|
46
46
|
},
|
|
47
47
|
"dependencies": {
|
|
48
48
|
"@babel/standalone": "^7.29.0",
|
|
49
|
-
"@enclave-vm/ast": "2.15.
|
|
50
|
-
"@enclave-vm/types": "2.15.
|
|
49
|
+
"@enclave-vm/ast": "2.15.3",
|
|
50
|
+
"@enclave-vm/types": "2.15.3",
|
|
51
51
|
"@types/estree": "1.0.8",
|
|
52
52
|
"acorn": "8.15.0",
|
|
53
53
|
"acorn-walk": "8.3.4",
|
|
@@ -150,6 +150,58 @@ function sanitizeObject(value, depth = 0) {
|
|
|
150
150
|
return result;
|
|
151
151
|
}
|
|
152
152
|
|
|
153
|
+
// libs/core/src/tool-namespaces.ts
|
|
154
|
+
var TOOL_NAMESPACE_FACTORY_SOURCE = `
|
|
155
|
+
(function () {
|
|
156
|
+
'use strict';
|
|
157
|
+
var parse = JSON.parse;
|
|
158
|
+
var freeze = Object.freeze;
|
|
159
|
+
var isArray = Array.isArray;
|
|
160
|
+
|
|
161
|
+
function isSafeKey(key) {
|
|
162
|
+
return typeof key === 'string' && key.length > 0 &&
|
|
163
|
+
!(key.charAt(0) === '_' && key.charAt(1) === '_') &&
|
|
164
|
+
key !== 'constructor' && key !== 'prototype';
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
function bind(callTool, toolName) {
|
|
168
|
+
return (args, options) => callTool(toolName, args === undefined ? {} : args, options);
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
return function install(callTool, namespacesJson) {
|
|
172
|
+
var spec = parse(namespacesJson);
|
|
173
|
+
var namespaces = { __proto__: null };
|
|
174
|
+
if (isArray(spec)) {
|
|
175
|
+
for (var i = 0; i < spec.length; i++) {
|
|
176
|
+
var ns = spec[i];
|
|
177
|
+
if (!ns || !isSafeKey(ns.name) || !isArray(ns.methods)) continue;
|
|
178
|
+
var target = { __proto__: null };
|
|
179
|
+
for (var j = 0; j < ns.methods.length; j++) {
|
|
180
|
+
var method = ns.methods[j];
|
|
181
|
+
if (!method || !isSafeKey(method.name) || typeof method.toolName !== 'string') continue;
|
|
182
|
+
target[method.name] = bind(callTool, method.toolName);
|
|
183
|
+
}
|
|
184
|
+
freeze(target);
|
|
185
|
+
namespaces[ns.name] = target;
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
freeze(namespaces);
|
|
189
|
+
return namespaces;
|
|
190
|
+
};
|
|
191
|
+
})()
|
|
192
|
+
`.trim();
|
|
193
|
+
function buildToolNamespaceBindings(install, callTool, namespaces) {
|
|
194
|
+
if (namespaces.length === 0) return [];
|
|
195
|
+
if (typeof install !== "function") {
|
|
196
|
+
throw new Error("Tool namespace factory is not available in the sandbox");
|
|
197
|
+
}
|
|
198
|
+
const built = install(
|
|
199
|
+
callTool,
|
|
200
|
+
JSON.stringify(namespaces)
|
|
201
|
+
);
|
|
202
|
+
return namespaces.map((ns) => ({ name: ns.name, value: built[ns.name] }));
|
|
203
|
+
}
|
|
204
|
+
|
|
153
205
|
// libs/core/src/adapters/worker-pool/worker-script.ts
|
|
154
206
|
var STACK_TRACE_HARDENING_CODE = `
|
|
155
207
|
(function() {
|
|
@@ -299,6 +351,7 @@ var CODE_GENERATION_VIOLATION_DETECTOR_CODE = `
|
|
|
299
351
|
})();
|
|
300
352
|
`.trim();
|
|
301
353
|
var CODE_GENERATION_VIOLATION_DETECTOR_SCRIPT = new import_vm.default.Script(CODE_GENERATION_VIOLATION_DETECTOR_CODE);
|
|
354
|
+
var TOOL_NAMESPACE_FACTORY_SCRIPT = new import_vm.default.Script(TOOL_NAMESPACE_FACTORY_SOURCE, { filename: "tool-namespaces.js" });
|
|
302
355
|
var port = import_worker_threads.parentPort;
|
|
303
356
|
if (!port) {
|
|
304
357
|
throw new Error("worker-script.ts must run inside a worker thread");
|
|
@@ -327,6 +380,9 @@ for (const name of DANGEROUS_GLOBALS) {
|
|
|
327
380
|
}
|
|
328
381
|
var currentExecution = null;
|
|
329
382
|
var pendingToolCalls = /* @__PURE__ */ new Map();
|
|
383
|
+
function plainResult(fields) {
|
|
384
|
+
return Object.assign(/* @__PURE__ */ Object.create(null), fields);
|
|
385
|
+
}
|
|
330
386
|
port.on("message", async (raw) => {
|
|
331
387
|
try {
|
|
332
388
|
const msg = safeDeserialize(raw);
|
|
@@ -374,6 +430,21 @@ async function handleExecute(msg) {
|
|
|
374
430
|
});
|
|
375
431
|
const isStrictOrSecure = msg.config.securityLevel === "STRICT" || msg.config.securityLevel === "SECURE";
|
|
376
432
|
const policyViolation = {};
|
|
433
|
+
const toolNamespaces = msg.config.toolNamespaces ?? [];
|
|
434
|
+
if (toolNamespaces.length > 0) {
|
|
435
|
+
const install = TOOL_NAMESPACE_FACTORY_SCRIPT.runInContext(context);
|
|
436
|
+
const callTool = context["__safe_callTool"];
|
|
437
|
+
for (const binding of buildToolNamespaceBindings(install, callTool, toolNamespaces)) {
|
|
438
|
+
for (const name of [binding.name, `__safe_${binding.name}`]) {
|
|
439
|
+
Object.defineProperty(context, name, {
|
|
440
|
+
value: binding.value,
|
|
441
|
+
writable: false,
|
|
442
|
+
configurable: false,
|
|
443
|
+
enumerable: false
|
|
444
|
+
});
|
|
445
|
+
}
|
|
446
|
+
}
|
|
447
|
+
}
|
|
377
448
|
const shouldHardenStacks = msg.config.sanitizeStackTraces ?? true;
|
|
378
449
|
if (shouldHardenStacks) {
|
|
379
450
|
try {
|
|
@@ -462,11 +533,26 @@ function handleToolResponse(msg) {
|
|
|
462
533
|
}
|
|
463
534
|
pendingToolCalls.delete(msg.callId);
|
|
464
535
|
if (msg.error) {
|
|
536
|
+
if (!pending.throwOnError && msg.toolError === true) {
|
|
537
|
+
pending.resolve(
|
|
538
|
+
plainResult({
|
|
539
|
+
success: false,
|
|
540
|
+
error: plainResult({
|
|
541
|
+
name: msg.error.name,
|
|
542
|
+
message: msg.error.message,
|
|
543
|
+
...typeof msg.error.code === "string" ? { code: msg.error.code } : {},
|
|
544
|
+
toolName: pending.toolName
|
|
545
|
+
})
|
|
546
|
+
})
|
|
547
|
+
);
|
|
548
|
+
return;
|
|
549
|
+
}
|
|
465
550
|
const error = new Error(msg.error.message);
|
|
466
551
|
error.name = msg.error.name;
|
|
467
552
|
pending.reject(error);
|
|
468
553
|
} else {
|
|
469
|
-
|
|
554
|
+
const result = sanitizeObject(msg.result);
|
|
555
|
+
pending.resolve(pending.throwOnError ? result : plainResult({ success: true, data: result }));
|
|
470
556
|
}
|
|
471
557
|
}
|
|
472
558
|
function handleMemoryReport() {
|
|
@@ -624,7 +710,14 @@ function createSandbox(requestId, config) {
|
|
|
624
710
|
return sandbox;
|
|
625
711
|
}
|
|
626
712
|
function createProxiedCallTool(requestId, config) {
|
|
627
|
-
return async function __safe_callTool(toolName, args) {
|
|
713
|
+
return async function __safe_callTool(toolName, args, options) {
|
|
714
|
+
let throwOnError = true;
|
|
715
|
+
if (options !== void 0 && options !== null) {
|
|
716
|
+
if (typeof options !== "object") {
|
|
717
|
+
throw new TypeError("callTool options must be an object");
|
|
718
|
+
}
|
|
719
|
+
throwOnError = options.throwOnError !== false;
|
|
720
|
+
}
|
|
628
721
|
if (currentExecution?.aborted) {
|
|
629
722
|
throw new Error("Execution aborted");
|
|
630
723
|
}
|
|
@@ -644,7 +737,7 @@ function createProxiedCallTool(requestId, config) {
|
|
|
644
737
|
}
|
|
645
738
|
const callId = `${requestId}-${Date.now()}-${import_crypto.default.randomUUID()}`;
|
|
646
739
|
return new Promise((resolve, reject) => {
|
|
647
|
-
pendingToolCalls.set(callId, { resolve, reject });
|
|
740
|
+
pendingToolCalls.set(callId, { resolve, reject, throwOnError, toolName });
|
|
648
741
|
sendMessage({
|
|
649
742
|
type: "tool-call",
|
|
650
743
|
requestId,
|
package/stack-trace.d.ts
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Stack Trace Sanitization
|
|
3
|
+
*
|
|
4
|
+
* One sanitizer for every error the enclave hands back to its caller, whichever stage raised it
|
|
5
|
+
* (validation, transformation, compilation, execution, tool calls) and whichever adapter ran the
|
|
6
|
+
* script. With `sanitizeStackTraces` on, a returned stack keeps its message lines (with paths,
|
|
7
|
+
* locations and credential-like strings redacted) and every stack frame becomes `at [REDACTED]`,
|
|
8
|
+
* so no host path, file name, line or column number, or host function name survives.
|
|
9
|
+
*
|
|
10
|
+
* @packageDocumentation
|
|
11
|
+
*/
|
|
12
|
+
/**
|
|
13
|
+
* Sensitive patterns redacted from the non-frame lines of a stack (the error header, and the
|
|
14
|
+
* source excerpt V8 prints for syntax errors).
|
|
15
|
+
*
|
|
16
|
+
* Categories covered:
|
|
17
|
+
* - File system paths (Unix, Windows, UNC), file URLs and file locations (`name.js:10:5`)
|
|
18
|
+
* - Cloud, container and CI paths
|
|
19
|
+
* - Secret/credential patterns
|
|
20
|
+
* - Internal hostnames and IPs
|
|
21
|
+
* - Package manager cache paths
|
|
22
|
+
*/
|
|
23
|
+
export declare const SENSITIVE_STACK_PATTERNS: readonly RegExp[];
|
|
24
|
+
/**
|
|
25
|
+
* Sanitize a stack trace for the enclave's caller.
|
|
26
|
+
*
|
|
27
|
+
* With `sanitize` on, every frame line becomes `at [REDACTED]` and sensitive data in the other
|
|
28
|
+
* lines is redacted (see {@link SENSITIVE_STACK_PATTERNS}); the number of frames is preserved so
|
|
29
|
+
* the shape of the error stays recognizable. With `sanitize` off, the stack is returned unchanged.
|
|
30
|
+
*
|
|
31
|
+
* Only simple, non-nested patterns are applied, one bounded line at a time (the stack is cut at
|
|
32
|
+
* 16 KiB and each line at 1000 characters), so hostile input cannot make sanitization expensive.
|
|
33
|
+
*
|
|
34
|
+
* @param stack Original stack trace
|
|
35
|
+
* @param sanitize Whether to sanitize (defaults to true)
|
|
36
|
+
* @returns The sanitized stack trace (or the original if `sanitize` is false)
|
|
37
|
+
*/
|
|
38
|
+
export declare function sanitizeStackTrace(stack: string | undefined, sanitize?: boolean): string | undefined;
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tool Namespace Bindings
|
|
3
|
+
*
|
|
4
|
+
* Builds the `toolNamespaces` objects (`mail.list(args)`) INSIDE a sandbox realm. The objects and
|
|
5
|
+
* their methods are created by code evaluated in that realm, so the script never receives a host
|
|
6
|
+
* object: each namespace is a frozen, null-prototype object whose methods are realm-local arrow
|
|
7
|
+
* functions that call the realm's own `callTool` (and therefore the enclave's tool-call gate).
|
|
8
|
+
*
|
|
9
|
+
* The configuration crosses into the realm as a JSON string and is parsed there. No source code is
|
|
10
|
+
* generated from it; names were validated by `normalizeToolNamespaces` on the host, and the
|
|
11
|
+
* factory skips prototype keys again as defense in depth.
|
|
12
|
+
*
|
|
13
|
+
* @packageDocumentation
|
|
14
|
+
*/
|
|
15
|
+
import type { NormalizedToolNamespace } from '@enclave-vm/ast';
|
|
16
|
+
/**
|
|
17
|
+
* Source of an expression that, evaluated in a sandbox realm, captures that realm's `JSON.parse`
|
|
18
|
+
* and `Object.freeze` and returns `install(callTool, namespacesJson)`.
|
|
19
|
+
*
|
|
20
|
+
* `install` returns a frozen, null-prototype map from namespace name to namespace object. Each
|
|
21
|
+
* method is `(args, options) => callTool(toolName, args === undefined ? {} : args, options)`.
|
|
22
|
+
*/
|
|
23
|
+
export declare const TOOL_NAMESPACE_FACTORY_SOURCE: string;
|
|
24
|
+
/** A namespace name paired with the realm-local object that implements it. */
|
|
25
|
+
export interface ToolNamespaceBinding {
|
|
26
|
+
readonly name: string;
|
|
27
|
+
readonly value: unknown;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Build the namespace objects with an `install` function obtained by evaluating
|
|
31
|
+
* {@link TOOL_NAMESPACE_FACTORY_SOURCE} in the sandbox realm.
|
|
32
|
+
*
|
|
33
|
+
* @param install The realm-local `install` function
|
|
34
|
+
* @param callTool The realm's gated `callTool`
|
|
35
|
+
* @param namespaces Validated namespaces
|
|
36
|
+
* @returns One binding per namespace, in configuration order
|
|
37
|
+
*/
|
|
38
|
+
export declare function buildToolNamespaceBindings(install: unknown, callTool: unknown, namespaces: readonly NormalizedToolNamespace[]): ToolNamespaceBinding[];
|
package/types.d.ts
CHANGED
|
@@ -348,8 +348,51 @@ export interface EnclaveConfig {
|
|
|
348
348
|
}
|
|
349
349
|
/**
|
|
350
350
|
* Tool call handler function
|
|
351
|
+
*
|
|
352
|
+
* Called for every `callTool(name, args)` and every `toolNamespaces` method call that passes the
|
|
353
|
+
* enclave's checks. The script's `callTool` options (see {@link CallToolOptions}) are applied
|
|
354
|
+
* inside the enclave and are not passed to the handler.
|
|
351
355
|
*/
|
|
352
356
|
export type ToolHandler = (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
|
|
357
|
+
/**
|
|
358
|
+
* Options a script may pass as the third argument of `callTool(name, args, options)`, or as the
|
|
359
|
+
* second argument of a `toolNamespaces` method (`mail.send(args, options)`).
|
|
360
|
+
*/
|
|
361
|
+
export interface CallToolOptions {
|
|
362
|
+
/**
|
|
363
|
+
* When `false`, a failing tool does not throw into the script: the call resolves to
|
|
364
|
+
* `{ success: false, error }` instead, and a successful call resolves to `{ success: true, data }`
|
|
365
|
+
* (see {@link ToolCallResult}). A failing tool is one whose handler threw or rejected, or whose
|
|
366
|
+
* result could not be delivered (unsafe or oversized). Refusals by the enclave itself (abort,
|
|
367
|
+
* `maxToolCalls`, rate limit, operation-name and suspicious-sequence checks, invalid or oversized
|
|
368
|
+
* arguments) always throw.
|
|
369
|
+
*
|
|
370
|
+
* @default true
|
|
371
|
+
*/
|
|
372
|
+
throwOnError?: boolean;
|
|
373
|
+
}
|
|
374
|
+
/**
|
|
375
|
+
* Error details a script receives for a failing tool when `throwOnError` is `false`.
|
|
376
|
+
* Plain data created inside the sandbox: no stack, no host object.
|
|
377
|
+
*/
|
|
378
|
+
export interface ToolCallErrorInfo {
|
|
379
|
+
name: string;
|
|
380
|
+
message: string;
|
|
381
|
+
/** Error code reported by the tool, when it is a string */
|
|
382
|
+
code?: string;
|
|
383
|
+
/** Name of the tool that failed */
|
|
384
|
+
toolName: string;
|
|
385
|
+
}
|
|
386
|
+
/**
|
|
387
|
+
* What `callTool(name, args, { throwOnError: false })` resolves to inside the sandbox.
|
|
388
|
+
*/
|
|
389
|
+
export type ToolCallResult<T = unknown> = {
|
|
390
|
+
success: true;
|
|
391
|
+
data: T;
|
|
392
|
+
} | {
|
|
393
|
+
success: false;
|
|
394
|
+
error: ToolCallErrorInfo;
|
|
395
|
+
};
|
|
353
396
|
/**
|
|
354
397
|
* Safe runtime context provided to AgentScript code
|
|
355
398
|
*/
|
|
@@ -358,7 +401,7 @@ export interface SafeRuntimeContext {
|
|
|
358
401
|
* Safe tool call function
|
|
359
402
|
* Tracks calls, enforces limits, and delegates to the tool handler
|
|
360
403
|
*/
|
|
361
|
-
__safe_callTool: (toolName: string, args: Record<string, unknown
|
|
404
|
+
__safe_callTool: (toolName: string, args: Record<string, unknown>, options?: CallToolOptions) => Promise<unknown>;
|
|
362
405
|
/**
|
|
363
406
|
* Safe for-of loop iterator
|
|
364
407
|
* Enforces iteration limits
|
|
@@ -412,6 +455,7 @@ import type { ReferenceConfig } from './sidecar/reference-config';
|
|
|
412
455
|
import type { ScoringGateConfig, ScoringGateResult } from './scoring/types';
|
|
413
456
|
import type { WorkerPoolConfig } from './adapters/worker-pool/config';
|
|
414
457
|
import type { DoubleVmConfig, PartialDoubleVmConfig, ParentValidationConfig } from './double-vm/types';
|
|
458
|
+
import type { NormalizedToolNamespace, ToolNamespaces } from '@enclave-vm/ast';
|
|
415
459
|
/**
|
|
416
460
|
* Internal execution context (tracks state during execution)
|
|
417
461
|
*/
|
|
@@ -424,7 +468,16 @@ export interface ExecutionContext {
|
|
|
424
468
|
sanitizeStackTraces: boolean;
|
|
425
469
|
maxSanitizeDepth: number;
|
|
426
470
|
maxSanitizeProperties: number;
|
|
471
|
+
/**
|
|
472
|
+
* Cap on calls into host functions passed in `globals`
|
|
473
|
+
* (defaults to 10 × `maxToolCalls` when absent)
|
|
474
|
+
*/
|
|
475
|
+
maxGlobalFunctionCalls?: number;
|
|
427
476
|
};
|
|
477
|
+
/**
|
|
478
|
+
* Validated tool namespaces to bind in the sandbox (see `CreateEnclaveOptions.toolNamespaces`)
|
|
479
|
+
*/
|
|
480
|
+
toolNamespaces?: readonly NormalizedToolNamespace[];
|
|
428
481
|
/**
|
|
429
482
|
* Statistics tracker
|
|
430
483
|
*/
|
|
@@ -588,16 +641,72 @@ export interface CreateEnclaveOptions extends EnclaveConfig {
|
|
|
588
641
|
* Whether to allow functions in custom globals
|
|
589
642
|
* Default: Determined by securityLevel (false for STRICT/SECURE/STANDARD)
|
|
590
643
|
*
|
|
644
|
+
* Every call the script makes into such a function goes through the enclave's gate: it is
|
|
645
|
+
* refused once the execution is aborted, counts toward {@link maxGlobalFunctionCalls} (not
|
|
646
|
+
* `maxToolCalls`), shares the double VM's operation rate limit
|
|
647
|
+
* (`doubleVm.parentValidation.maxOperationsPerSecond`) with tool calls, and its return value is
|
|
648
|
+
* sanitized like a tool result (functions, symbols and values beyond the sanitize limits are
|
|
649
|
+
* refused; the script receives a plain-data copy). Errors it throws reach the script as plain
|
|
650
|
+
* errors without the host stack, and calling it with `new` is refused.
|
|
651
|
+
* The suspicious-sequence detectors only look at tool calls: expose tools with
|
|
652
|
+
* {@link toolNamespaces} or `callTool()`, not as functions.
|
|
653
|
+
* The `worker_threads` adapter never passes functions into the sandbox.
|
|
654
|
+
*
|
|
655
|
+
* Functions (and objects with methods, such as class instances) are refused inside arrays,
|
|
656
|
+
* Maps and Sets in `globals`, whatever this option says: the built-in methods of those
|
|
657
|
+
* collections (forEach, iteration, get) hand elements to the script directly, which would skip
|
|
658
|
+
* the gate. Promises, WeakMaps, iterators and generators are refused anywhere in `globals`.
|
|
659
|
+
*
|
|
591
660
|
* Security Warning: Functions can leak host scope via closures.
|
|
592
661
|
* Only enable if you understand the security implications.
|
|
593
662
|
*/
|
|
594
663
|
allowFunctionsInGlobals?: boolean;
|
|
664
|
+
/**
|
|
665
|
+
* Maximum number of calls the script may make into functions passed in `globals`
|
|
666
|
+
* (including functions nested in objects), per execution.
|
|
667
|
+
*
|
|
668
|
+
* Default: 10 × `maxToolCalls`
|
|
669
|
+
*/
|
|
670
|
+
maxGlobalFunctionCalls?: number;
|
|
671
|
+
/**
|
|
672
|
+
* Tool namespaces: expose tools to the script as namespaced functions.
|
|
673
|
+
*
|
|
674
|
+
* With `{ mail: ['list', 'send'] }`, `await mail.list(args, options)` inside the sandbox is exactly
|
|
675
|
+
* `await callTool('mail.list', args, options)`: it counts toward `maxToolCalls`, is rate-limited
|
|
676
|
+
* and pattern-checked, its result is sanitized, and it reaches the `toolHandler`. A method can
|
|
677
|
+
* name its tool explicitly: `{ users: { list: 'users:list' } }`. `args` defaults to `{}`.
|
|
678
|
+
*
|
|
679
|
+
* Each namespace is a frozen, null-prototype object created inside the sandbox, so aliasing
|
|
680
|
+
* (`const m = mail; m.list()`) and destructuring work and no host object is exposed.
|
|
681
|
+
*
|
|
682
|
+
* The constructor throws a `TypeError` for names that are not identifiers, prototype keys,
|
|
683
|
+
* names starting with `__`, reserved words and sandbox globals used as namespaces, identifiers
|
|
684
|
+
* the AgentScript validator refuses, namespaces that collide with a custom global, duplicated
|
|
685
|
+
* methods, and empty tool names.
|
|
686
|
+
*
|
|
687
|
+
* @example
|
|
688
|
+
* ```typescript
|
|
689
|
+
* const enclave = new Enclave({
|
|
690
|
+
* toolHandler,
|
|
691
|
+
* toolNamespaces: { mail: ['list', 'send'], users: { get: 'users:get' } },
|
|
692
|
+
* });
|
|
693
|
+
* await enclave.run(`
|
|
694
|
+
* const inbox = await mail.list({ unread: true });
|
|
695
|
+
* const r = await users.get({ id: inbox[0].from }, { throwOnError: false });
|
|
696
|
+
* return r.success ? r.data.name : r.error.message;
|
|
697
|
+
* `);
|
|
698
|
+
* ```
|
|
699
|
+
*/
|
|
700
|
+
toolNamespaces?: ToolNamespaces;
|
|
595
701
|
/**
|
|
596
702
|
* Whether to sanitize stack traces in error messages
|
|
597
703
|
* Default: Determined by securityLevel (true for STRICT/SECURE)
|
|
598
704
|
*
|
|
599
705
|
* When enabled, file paths and line numbers are removed from stack traces
|
|
600
|
-
* to prevent information leakage about the host system.
|
|
706
|
+
* to prevent information leakage about the host system. This applies to every
|
|
707
|
+
* error `run()` returns, whichever stage raised it (validation, transformation,
|
|
708
|
+
* compilation, execution, tool calls) and on every adapter: stack frames become
|
|
709
|
+
* `at [REDACTED]` and paths in the remaining lines are redacted.
|
|
601
710
|
*/
|
|
602
711
|
sanitizeStackTraces?: boolean;
|
|
603
712
|
/**
|
|
@@ -766,6 +875,12 @@ export type { WorkerPoolConfig };
|
|
|
766
875
|
* @see {@link ParentValidationConfig} Parent VM validation settings
|
|
767
876
|
*/
|
|
768
877
|
export type { DoubleVmConfig, PartialDoubleVmConfig, ParentValidationConfig };
|
|
878
|
+
/**
|
|
879
|
+
* Re-exported tool namespace types
|
|
880
|
+
* @see {@link ToolNamespaces} The `toolNamespaces` configuration
|
|
881
|
+
* @see {@link NormalizedToolNamespace} A validated namespace
|
|
882
|
+
*/
|
|
883
|
+
export type { ToolNamespaces, NormalizedToolNamespace };
|
|
769
884
|
/**
|
|
770
885
|
* Default double VM configuration
|
|
771
886
|
*
|