@enclave-vm/core 2.19.0 → 2.19.2
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 +262 -105
- package/adapters/interpreter-adapter.d.ts +10 -1
- 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/deadline-guard.d.ts +16 -0
- package/dynamic-import.d.ts +25 -0
- package/enclave-options.d.ts +62 -0
- package/enclave.d.ts +31 -7
- package/esm/index.mjs +4796 -852
- package/esm/worker.mjs +1236 -165
- package/execution-deadline.d.ts +6 -0
- package/global-function-gate.d.ts +34 -1
- package/index.d.ts +3 -3
- package/index.js +4836 -892
- package/interpreter/interpreter.d.ts +247 -8
- package/memory-tracker.d.ts +7 -0
- package/package.json +3 -3
- package/realm-airlock.d.ts +6 -1
- package/realm-memory.d.ts +89 -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/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 +19 -1
- 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 +2250 -428
- package/thrown-value.d.ts +59 -0
- package/types.d.ts +75 -19
- package/value-sanitizer.d.ts +6 -1
- package/worker.js +1236 -165
|
@@ -1,11 +1,36 @@
|
|
|
1
1
|
import type * as ESTree from 'estree';
|
|
2
2
|
/** Whether a property key is one a script may never use. */
|
|
3
3
|
export declare function isBlockedKey(key: string): boolean;
|
|
4
|
+
/** Whether the engine calls a function it finds under this name, without a call in the script. */
|
|
5
|
+
export declare function isEngineCalledKey(key: string): boolean;
|
|
6
|
+
/**
|
|
7
|
+
* Refuse to store a function where the engine would call it by itself. Such a call is not a
|
|
8
|
+
* call of the script: it gets none of the checks of a call, a function of the script that is
|
|
9
|
+
* called that way is not awaited, and a value with a `then` function is waited for wherever it
|
|
10
|
+
* is evaluated. Data of a script therefore never holds a function under one of those names (an
|
|
11
|
+
* array neither under `join`, which the engine calls for the text of an array). Any other
|
|
12
|
+
* value may be stored there, and the conversions every object inherits keep working.
|
|
13
|
+
*
|
|
14
|
+
* @throws InterpreterError when `value` is a function and `key` is such a name
|
|
15
|
+
*/
|
|
16
|
+
export declare function assertStorable(target: unknown, key: string, value: unknown): void;
|
|
17
|
+
/**
|
|
18
|
+
* Longest text one conversion may produce: `join`, `'' + array`, a template literal, an array
|
|
19
|
+
* given to a built-in function that expects text or a number, a text that is normalized or
|
|
20
|
+
* encoded (the budget still applies).
|
|
21
|
+
*/
|
|
22
|
+
export declare const MAX_JOIN_LENGTH = 16000000;
|
|
4
23
|
/**
|
|
5
24
|
* Longest array a script may make in one step: by assigning an index or `length`, or by
|
|
6
25
|
* spreading. An array of a billion holes costs nothing to make and a lot to `join`.
|
|
7
26
|
*/
|
|
8
27
|
export declare const MAX_ARRAY_LENGTH = 1000000;
|
|
28
|
+
/**
|
|
29
|
+
* The largest BigInt a script may hold, in bits (about 315,000 decimal digits). The engine
|
|
30
|
+
* allows a thousand times that for one value, and its arithmetic on such values runs for
|
|
31
|
+
* seconds in one step; at this size no single operation takes more than a few hundredths of one.
|
|
32
|
+
*/
|
|
33
|
+
export declare const MAX_BIGINT_BITS: number;
|
|
9
34
|
/**
|
|
10
35
|
* Declare that `fn` takes arrays as data and never converts one to text or to a number (the
|
|
11
36
|
* engine does that to an array wherever it expects a primitive). Arrays given to any other
|
|
@@ -19,6 +44,12 @@ export declare function takesArraysAsData<F extends object>(fn: F): F;
|
|
|
19
44
|
* hands such a function three arguments when it uses it as the callback of `map`.
|
|
20
45
|
*/
|
|
21
46
|
export declare function convertsArguments<F extends object>(fn: F, count: number): F;
|
|
47
|
+
/**
|
|
48
|
+
* Declare how `fn` converts its arguments before it looks at them. The conversion is made once,
|
|
49
|
+
* before the call is measured and charged, and `fn` is called with its result: what a bound was
|
|
50
|
+
* checked with is what the function gets.
|
|
51
|
+
*/
|
|
52
|
+
export declare function convertsBeforeCall<F extends object>(fn: F, convert: (args: unknown[]) => unknown[]): F;
|
|
22
53
|
/**
|
|
23
54
|
* Declare what a call of `fn` may allocate beyond the value it returns, in bytes, from its
|
|
24
55
|
* arguments. It is charged to the budget BEFORE the call: the engine builds the result in one
|
|
@@ -31,13 +62,18 @@ export declare function chargedBeforeCall<F extends object>(fn: F, cost: (args:
|
|
|
31
62
|
* joins an array's items, and the items of the arrays inside it: an array that holds another one
|
|
32
63
|
* many times is small in memory and huge as text.
|
|
33
64
|
*
|
|
65
|
+
* @returns The chars the arrays among `values` are as text (an upper bound; 0 without an array)
|
|
34
66
|
* @throws InterpreterError when the text of the arrays among `values` is longer than the limit
|
|
35
67
|
*/
|
|
36
|
-
export declare function assertArrayTextWithinLimit(...values: unknown[]):
|
|
68
|
+
export declare function assertArrayTextWithinLimit(...values: unknown[]): number;
|
|
37
69
|
/** Thrown when the instruction budget is exceeded (interrupts infinite loops). */
|
|
38
70
|
export declare class StepLimitError extends Error {
|
|
39
71
|
constructor(limit: number);
|
|
40
72
|
}
|
|
73
|
+
/** Thrown when the deadline of a run passes while its script is computing. */
|
|
74
|
+
export declare class DeadlineError extends Error {
|
|
75
|
+
constructor();
|
|
76
|
+
}
|
|
41
77
|
/** Thrown on any disallowed operation (blocked key, unknown identifier, bad call). */
|
|
42
78
|
export declare class InterpreterError extends Error {
|
|
43
79
|
constructor(message: string);
|
|
@@ -56,10 +92,28 @@ export interface InterpreterOptions {
|
|
|
56
92
|
globals: Record<string, unknown>;
|
|
57
93
|
/** Max evaluated nodes before aborting (interrupts infinite loops). */
|
|
58
94
|
maxSteps: number;
|
|
59
|
-
/**
|
|
95
|
+
/**
|
|
96
|
+
* How deep calls may nest: a call counts from where it is made to where it returns, along the
|
|
97
|
+
* chain of calls it belongs to. A callback counts as a call of the function that invokes it,
|
|
98
|
+
* so the tasks of one `parallel` batch each continue the chain that started the batch and do
|
|
99
|
+
* not add up.
|
|
100
|
+
*/
|
|
60
101
|
maxCallDepth: number;
|
|
102
|
+
/**
|
|
103
|
+
* How many calls of the whole execution may be unfinished at once, over all its chains: the
|
|
104
|
+
* ones that are running and the ones waiting for something they await. This bounds what the
|
|
105
|
+
* waiting calls hold. Default: {@link DEFAULT_MAX_PENDING_CALLS}.
|
|
106
|
+
*/
|
|
107
|
+
maxPendingCalls?: number;
|
|
61
108
|
/** Optional cancellation. */
|
|
62
109
|
signal?: AbortSignal;
|
|
110
|
+
/**
|
|
111
|
+
* The time, as `Date.now()` gives it, from which the run is over. The interpreter reads the
|
|
112
|
+
* clock every few hundred steps and before every built-in or host function it calls, and ends
|
|
113
|
+
* the run with a {@link DeadlineError} once the time has come. A signal alone cannot do that:
|
|
114
|
+
* the timer behind it does not fire while a script computes.
|
|
115
|
+
*/
|
|
116
|
+
deadline?: number;
|
|
63
117
|
/**
|
|
64
118
|
* What `new` may be applied to: for each such global, the function that builds the value from
|
|
65
119
|
* the arguments. `new` on anything else is refused.
|
|
@@ -74,6 +128,8 @@ export interface InterpreterOptions {
|
|
|
74
128
|
*/
|
|
75
129
|
charge?: (bytes: number) => void;
|
|
76
130
|
}
|
|
131
|
+
/** Unfinished calls an execution may have at once, when the host sets no `maxPendingCalls`. */
|
|
132
|
+
export declare const DEFAULT_MAX_PENDING_CALLS = 4096;
|
|
77
133
|
/**
|
|
78
134
|
* Evaluate a parsed AgentScript program. Returns the resolved value of the
|
|
79
135
|
* `__ag_main()` invocation (or the program's last value if no main wrapper).
|
|
@@ -81,13 +137,43 @@ export interface InterpreterOptions {
|
|
|
81
137
|
export declare class Interpreter {
|
|
82
138
|
private readonly options;
|
|
83
139
|
private steps;
|
|
84
|
-
|
|
140
|
+
/** Calls that have not returned: the running ones and the ones waiting on an `await` */
|
|
141
|
+
private pendingCalls;
|
|
142
|
+
/**
|
|
143
|
+
* The depth of whatever is making a call right now, for the function of the script that call
|
|
144
|
+
* starts. A function of the script is a host function too, and a built-in, `parallel` or a
|
|
145
|
+
* bound function invokes it without saying how deep it is: it reads this as it starts, in the
|
|
146
|
+
* same synchronous step as the call, and runs one deeper. Set by {@link withCallerDepth} for
|
|
147
|
+
* the synchronous part of a call only; a call that is waiting does not hold it, which is what
|
|
148
|
+
* keeps the depth of one chain apart from the depth of another. 0 when the host itself calls.
|
|
149
|
+
*/
|
|
150
|
+
private callerDepth;
|
|
151
|
+
private readonly maxPendingCalls;
|
|
85
152
|
private readonly globals;
|
|
86
|
-
/**
|
|
153
|
+
/**
|
|
154
|
+
* What is owed for the text `reduce` is handing to its callback, for that function to read as
|
|
155
|
+
* it starts (in the same synchronous step, like {@link callerDepth}); otherwise nothing.
|
|
156
|
+
*/
|
|
157
|
+
private accumulatorOwed;
|
|
158
|
+
/** The step count at which the clock is read next */
|
|
159
|
+
private nextClockCheck;
|
|
160
|
+
/** What built-ins worked through that has not made a full step yet (see {@link work}) */
|
|
161
|
+
private workDone;
|
|
162
|
+
/** The error that ended the run (step budget, deadline, abort, allocation budget); set once, never caught */
|
|
87
163
|
private fatal;
|
|
88
164
|
private readonly interpretedFunctions;
|
|
165
|
+
/** The functions the host provides: the globals, their members, and what `bind` made of them */
|
|
166
|
+
private readonly provided;
|
|
89
167
|
private readonly errorCopies;
|
|
168
|
+
/** BigInt literals of the program that were found to be within the size a BigInt may have */
|
|
169
|
+
private readonly checkedLiterals;
|
|
90
170
|
constructor(options: InterpreterOptions);
|
|
171
|
+
/**
|
|
172
|
+
* Remember the functions among the properties of `holder`, `depth` levels down: a global
|
|
173
|
+
* (`parseInt`) or a member of one (`Math.max`, a method of a tool namespace). Read from the
|
|
174
|
+
* property itself, so that nothing of the host runs for it. An array holds data.
|
|
175
|
+
*/
|
|
176
|
+
private provide;
|
|
91
177
|
/**
|
|
92
178
|
* Call a function for a script, with the checks that apply to a call the script writes itself.
|
|
93
179
|
* For a host helper that is handed a callback (`parallel(items, fn)`): `fn` may be a function
|
|
@@ -98,14 +184,48 @@ export declare class Interpreter {
|
|
|
98
184
|
get stepCount(): number;
|
|
99
185
|
run(program: ESTree.Program): Promise<unknown>;
|
|
100
186
|
/**
|
|
101
|
-
* End the run from outside: whatever of the script is still going (a
|
|
102
|
-
*
|
|
103
|
-
* host calls this when the execution has returned, so that no
|
|
187
|
+
* End the run from outside: whatever of the script is still going (a callback waiting for a
|
|
188
|
+
* tool call, a run that timed out while it waited) stops at its next step or its next call,
|
|
189
|
+
* whichever comes first. The host calls this when the execution has returned, so that no
|
|
190
|
+
* script code runs and no host function is called after it.
|
|
104
191
|
*/
|
|
105
192
|
stop(): void;
|
|
193
|
+
/**
|
|
194
|
+
* Charge an allocation that a runtime helper of the host made for the script (the helpers a
|
|
195
|
+
* transformed `+` or template literal calls). The budget is one budget wherever it is asked:
|
|
196
|
+
* a refusal ends the run here as it does for what the interpreter charges itself, and no
|
|
197
|
+
* `catch` or `finally` of the script runs after it.
|
|
198
|
+
*/
|
|
199
|
+
chargeAllocation(bytes: number): void;
|
|
106
200
|
/** End the run with an error no `catch` of the script can stop. */
|
|
107
201
|
private end;
|
|
108
202
|
private tick;
|
|
203
|
+
/** End the run when its deadline has passed. */
|
|
204
|
+
private checkClock;
|
|
205
|
+
/**
|
|
206
|
+
* Count what a built-in works through for the script, in chars or items: the engine does it
|
|
207
|
+
* in one step of its own, however large the operands are. {@link WORK_PER_STEP} units are a
|
|
208
|
+
* step of the budget, and the clock is read whenever that adds a step.
|
|
209
|
+
*/
|
|
210
|
+
private work;
|
|
211
|
+
/** {@link assertArrayTextWithinLimit}, and the text the arrays are written as counted as work. */
|
|
212
|
+
private arrayOperands;
|
|
213
|
+
/**
|
|
214
|
+
* Count a BigInt an operation made: it is held to the size a BigInt may have, and beyond the
|
|
215
|
+
* size of a number what it holds is charged to the budget and making it counts as work. Also
|
|
216
|
+
* for the runtime helper that adds for a transformed `+`.
|
|
217
|
+
*
|
|
218
|
+
* @throws InterpreterError when the value is larger than {@link MAX_BIGINT_BITS}
|
|
219
|
+
*/
|
|
220
|
+
countBigInt(value: bigint): void;
|
|
221
|
+
/** Count the work of writing a value as text, when it is a BigInt: the engine writes it in decimal. */
|
|
222
|
+
private bigIntAsText;
|
|
223
|
+
/**
|
|
224
|
+
* What is checked before an operator is applied to a BigInt: the operations whose result can
|
|
225
|
+
* be far larger than their operands are refused from the operands, and what the engine reads
|
|
226
|
+
* to compare a BigInt with a text is bounded and counted.
|
|
227
|
+
*/
|
|
228
|
+
private checkBigIntOperands;
|
|
109
229
|
/** Charge an allocation to the host's budget. */
|
|
110
230
|
private charge;
|
|
111
231
|
/** Charge what a host function returned, when that is a string or an array. */
|
|
@@ -130,11 +250,56 @@ export declare class Interpreter {
|
|
|
130
250
|
*/
|
|
131
251
|
private toScriptValue;
|
|
132
252
|
private evalExpr;
|
|
253
|
+
/**
|
|
254
|
+
* `s += x` or `s = s + x…` as a statement: append to a variable.
|
|
255
|
+
*
|
|
256
|
+
* The engine does not copy a text to append to it: the new text links to the old one, and is
|
|
257
|
+
* written out as a text of its own when something first looks into it. A loop that appends to
|
|
258
|
+
* one variable therefore allocates what it appends, and is charged that. What is not charged
|
|
259
|
+
* yet, the length of the text that was appended to, stays owed on the variable: it is paid by
|
|
260
|
+
* the first read that could look into the new text or keep it (`Scope.get`), because from then
|
|
261
|
+
* on it can exist as a full copy next to the texts it was built from. Nothing else can get
|
|
262
|
+
* hold of the new text: as a statement, the assignment has no value.
|
|
263
|
+
*/
|
|
264
|
+
private execAppend;
|
|
265
|
+
/**
|
|
266
|
+
* The value of the variable `name` with the operands appended, charged for what is appended.
|
|
267
|
+
*
|
|
268
|
+
* @returns The sum, and what is still owed for it when it is a text that was appended to a text
|
|
269
|
+
*/
|
|
270
|
+
private appendTo;
|
|
271
|
+
/**
|
|
272
|
+
* The value a function returns. In a callback that `reduce` called with a text, the
|
|
273
|
+
* accumulator itself and what is appended to it (`return text + item`) are returned as an
|
|
274
|
+
* {@link AccumulatedText}, without paying what is owed for them: `reduce` carries it on.
|
|
275
|
+
*/
|
|
276
|
+
private evalReturned;
|
|
277
|
+
/**
|
|
278
|
+
* The variable an identifier names when it holds an appended text that is still owed for.
|
|
279
|
+
* For the readers that learn nothing but its length or that it is a text.
|
|
280
|
+
*/
|
|
281
|
+
private appendedText;
|
|
282
|
+
/** Evaluate a condition. Whether a text is empty is known from its length. */
|
|
283
|
+
private evalTest;
|
|
133
284
|
private evalTemplate;
|
|
134
285
|
private evalUnary;
|
|
286
|
+
/** An operand the engine reads a number from: an array is joined first, a text is read through. */
|
|
287
|
+
private numericOperand;
|
|
135
288
|
private evalBinary;
|
|
136
|
-
/**
|
|
289
|
+
/**
|
|
290
|
+
* `a + b + c`: the operands from left to right, and one sum after the other. Only the last
|
|
291
|
+
* sum is a value the script gets hold of, and it is charged in full; the ones before it are
|
|
292
|
+
* part of it.
|
|
293
|
+
*/
|
|
294
|
+
private evalSum;
|
|
295
|
+
/**
|
|
296
|
+
* Apply a binary operator to two values.
|
|
297
|
+
*
|
|
298
|
+
* @param partOfSum - The result of `+` is an operand of the next `+` and nothing else: the
|
|
299
|
+
* caller charges for the text that comes of it
|
|
300
|
+
*/
|
|
137
301
|
private binary;
|
|
302
|
+
private operate;
|
|
138
303
|
/**
|
|
139
304
|
* Resolve a member expression to the object and the key it names, blocking escape keys.
|
|
140
305
|
* Inside an optional chain, a `?.` on `null` or `undefined` ends the chain.
|
|
@@ -158,8 +323,58 @@ export declare class Interpreter {
|
|
|
158
323
|
* Call a function with a receiver and arguments: an interpreted function, or a built-in or host
|
|
159
324
|
* function after the checks that apply to it. `call` and `apply` are resolved to the function
|
|
160
325
|
* they invoke first, so those checks cannot be passed by the way a call is written.
|
|
326
|
+
*
|
|
327
|
+
* @param depth - How many calls deep the code that makes this call runs
|
|
161
328
|
*/
|
|
162
329
|
private callFunction;
|
|
330
|
+
/**
|
|
331
|
+
* Count what a built-in or host function reads before it is called: its receiver, where the
|
|
332
|
+
* method goes through it (a search, a conversion, a copy; not a method that reads one char or
|
|
333
|
+
* works at the end of an array), and the texts among the arguments it converts or searches
|
|
334
|
+
* for. A value a function only keeps is not read: an item to push, the array a callback is
|
|
335
|
+
* handed with every item. An array that is read as text was counted where it was measured,
|
|
336
|
+
* and what the call makes is counted when it returns.
|
|
337
|
+
*/
|
|
338
|
+
private countRead;
|
|
339
|
+
/**
|
|
340
|
+
* Count a search for a place by how far the engine went: from where it started to where it
|
|
341
|
+
* found what it looked for, or to the end. A script that goes through a long text with
|
|
342
|
+
* `indexOf(text, position)` pays for the text once, not once per call.
|
|
343
|
+
*
|
|
344
|
+
* @param index - What the engine answered: the place, or -1
|
|
345
|
+
*/
|
|
346
|
+
private countSearched;
|
|
347
|
+
/**
|
|
348
|
+
* Make a search whose cost in the engine is the product of two lengths, piece by piece: a text
|
|
349
|
+
* in a text (the engine can need a comparison of the whole pattern at every position of a
|
|
350
|
+
* text that nearly matches everywhere), or a long text among the items of an array (every
|
|
351
|
+
* item of the same length can be compared to its end). Between the pieces a step is counted
|
|
352
|
+
* and the clock is read, so that one such call ends with the budget or the deadline like any
|
|
353
|
+
* other code. The answer is the engine's.
|
|
354
|
+
*
|
|
355
|
+
* @returns The result, or {@link NOT_SEARCHED} for a call that is not such a search or small
|
|
356
|
+
* enough to be one piece: the engine makes it
|
|
357
|
+
*/
|
|
358
|
+
private searchInPieces;
|
|
359
|
+
/** The first place at or after `from` where `pattern` starts in `text`, or -1. */
|
|
360
|
+
private findForward;
|
|
361
|
+
/** The last place at or before `from` where `pattern` starts in `text`, or -1. */
|
|
362
|
+
private findBackward;
|
|
363
|
+
/** `text.indexOf(pattern)` and the other searches for a text in a text, as the engine answers them. */
|
|
364
|
+
private searchText;
|
|
365
|
+
/** `array.indexOf(text)`, `lastIndexOf` and `includes` for a long text, as the engine answers them. */
|
|
366
|
+
private searchArray;
|
|
367
|
+
/**
|
|
368
|
+
* Count a call that starts `callerDepth` calls deep, until it returns.
|
|
369
|
+
*
|
|
370
|
+
* @returns The depth the call itself runs at
|
|
371
|
+
*/
|
|
372
|
+
private enterCall;
|
|
373
|
+
/**
|
|
374
|
+
* Make a call with `depth` as the depth a function of the script is called from, if one starts
|
|
375
|
+
* during it. It covers the synchronous part of the call, which is where a function starts.
|
|
376
|
+
*/
|
|
377
|
+
private withCallerDepth;
|
|
163
378
|
/** The argument list of `apply`: an array, or nothing. */
|
|
164
379
|
private argumentList;
|
|
165
380
|
/**
|
|
@@ -177,6 +392,14 @@ export declare class Interpreter {
|
|
|
177
392
|
private checkBuiltinCall;
|
|
178
393
|
private checkStringMethod;
|
|
179
394
|
private checkArrayMethod;
|
|
395
|
+
/**
|
|
396
|
+
* `array.toLocaleString(locales, options)`: the text of every item in the locale's format,
|
|
397
|
+
* joined by commas, as the engine writes it. The engine does it in one step and the length of
|
|
398
|
+
* what an item becomes is not known beforehand (a number can take hundreds of chars with the
|
|
399
|
+
* right options), so the items are converted here one at a time: each counts as a step, and
|
|
400
|
+
* the text is refused as soon as it is longer than a script's longest text.
|
|
401
|
+
*/
|
|
402
|
+
private arrayLocaleText;
|
|
180
403
|
/**
|
|
181
404
|
* Async implementations of the higher-order array methods, so interpreter
|
|
182
405
|
* callbacks (which are async — they may `await` tool calls) are awaited. Each
|
|
@@ -199,5 +422,21 @@ export declare class Interpreter {
|
|
|
199
422
|
/**
|
|
200
423
|
* Whether a value is data a script may change: an array, or an object whose prototype is
|
|
201
424
|
* `Object.prototype` or nothing. That is what literals, `JSON.parse` and tool results are made of.
|
|
425
|
+
*
|
|
426
|
+
* The two prototypes themselves fit that description (`Array.prototype` is an array, and the
|
|
427
|
+
* prototype of `Object.prototype` is nothing) and are nobody's data: every object and array of the
|
|
428
|
+
* process inherits from them.
|
|
202
429
|
*/
|
|
203
430
|
export declare function isScriptData(value: unknown): boolean;
|
|
431
|
+
/**
|
|
432
|
+
* Check `array[key] = value` against the longest array a script may make, wherever the write is
|
|
433
|
+
* made: an assignment, or a built-in that copies members onto an array.
|
|
434
|
+
*
|
|
435
|
+
* @returns What to write (a length is converted here, once: the number that is checked is the
|
|
436
|
+
* number that is set) and the length the array has afterwards
|
|
437
|
+
* @throws InterpreterError when the array would be longer than {@link MAX_ARRAY_LENGTH}
|
|
438
|
+
*/
|
|
439
|
+
export declare function checkArrayWrite(array: unknown[], key: string, value: unknown): {
|
|
440
|
+
value: unknown;
|
|
441
|
+
length: number;
|
|
442
|
+
};
|
package/memory-tracker.d.ts
CHANGED
|
@@ -101,12 +101,19 @@ export declare class MemoryTracker {
|
|
|
101
101
|
private trackedBytes;
|
|
102
102
|
private peakTrackedBytes;
|
|
103
103
|
private allocationCount;
|
|
104
|
+
/** Whether this tracker has refused an allocation since it was started */
|
|
105
|
+
private limitExceeded;
|
|
104
106
|
private readonly config;
|
|
105
107
|
constructor(config?: Partial<MemoryTrackerConfig>);
|
|
106
108
|
/**
|
|
107
109
|
* Start tracking (resets all counters)
|
|
108
110
|
*/
|
|
109
111
|
start(): void;
|
|
112
|
+
/**
|
|
113
|
+
* Whether the limit was exceeded since tracking started: the tracker itself refused an
|
|
114
|
+
* allocation. An error that only says so about itself is not evidence of that.
|
|
115
|
+
*/
|
|
116
|
+
hasExceededLimit(): boolean;
|
|
110
117
|
/**
|
|
111
118
|
* Track an allocation
|
|
112
119
|
*
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@enclave-vm/core",
|
|
3
|
-
"version": "2.19.
|
|
3
|
+
"version": "2.19.2",
|
|
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.19.
|
|
48
|
-
"@enclave-vm/types": "2.19.
|
|
47
|
+
"@enclave-vm/ast": "2.19.2",
|
|
48
|
+
"@enclave-vm/types": "2.19.2",
|
|
49
49
|
"@types/estree": "1.0.8",
|
|
50
50
|
"acorn": "8.15.0",
|
|
51
51
|
"acorn-walk": "8.3.4",
|
package/realm-airlock.d.ts
CHANGED
|
@@ -16,7 +16,10 @@
|
|
|
16
16
|
* INNER_REALM_GUARD_SOURCE in ./double-vm/parent-vm-bootstrap): its target is a fresh object of
|
|
17
17
|
* that realm, its traps are functions of that realm, and what those call is the handler built
|
|
18
18
|
* here, which forwards to the secure proxy. The secure proxy keeps deciding what may be read and
|
|
19
|
-
* called
|
|
19
|
+
* called. This layer decides two things only: host values are read-only, and what a script
|
|
20
|
+
* passes into a call goes on, and comes back, as the script holds it (an airlock proxy is never
|
|
21
|
+
* taken off a value on the way in; `call` and `apply` read off a host function are the sandbox
|
|
22
|
+
* realm's own).
|
|
20
23
|
*
|
|
21
24
|
* @packageDocumentation
|
|
22
25
|
*/
|
|
@@ -42,6 +45,8 @@ export interface RealmAirlock {
|
|
|
42
45
|
* `Object.prototype`. Says no to everything else, and to an object that cannot be asked.
|
|
43
46
|
*/
|
|
44
47
|
isRealmValue(value: object): boolean;
|
|
48
|
+
/** Whether a value is an airlock proxy: the form in which the script holds a value of the host */
|
|
49
|
+
isAirlockProxy(value: object): boolean;
|
|
45
50
|
}
|
|
46
51
|
/**
|
|
47
52
|
* Create the airlock of one execution.
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Accounting for arrays that grow, inside a sandbox realm
|
|
3
|
+
*
|
|
4
|
+
* `memoryLimit` is an estimate over the operations that make data grow. For strings those are
|
|
5
|
+
* concatenation and the amplifying methods (`repeat`, `padStart`, `padEnd`, `join`); `fill` was
|
|
6
|
+
* the one array operation. An array could otherwise grow without the limit seeing it, and a few
|
|
7
|
+
* dozen doublings are enough to exhaust the host's heap.
|
|
8
|
+
*
|
|
9
|
+
* The source below is evaluated in the script's realm, after the string patches, while the
|
|
10
|
+
* realm is still being set up. Three rules:
|
|
11
|
+
*
|
|
12
|
+
* 1. No single array is larger than the limit holds (8 bytes per element). Where the size of
|
|
13
|
+
* the result is known before the built-in runs, it is refused before; a built-in that turns
|
|
14
|
+
* a length into that many elements (`Array.from({ length })`, the copying methods on an array
|
|
15
|
+
* with holes, `fill`) is among those. Where it is not known (an iterable given to
|
|
16
|
+
* `Array.from`, a nesting given to `flat`), the built-in is stopped at the limit.
|
|
17
|
+
* 2. What an operation ADDS is charged to the execution's total: the elements pushed, spliced
|
|
18
|
+
* or unshifted in, the elements `concat`, `flat`, `flatMap` and a spread literal add to the
|
|
19
|
+
* largest array they started from, the elements `Array.from` makes out of something that is
|
|
20
|
+
* not an array, the elements `fill` writes. A plain copy adds nothing.
|
|
21
|
+
* 3. What is checked is what the built-in works on. A built-in converts the length of its
|
|
22
|
+
* receiver and its arguments by the language's rules, after anything in front of it has
|
|
23
|
+
* looked at them: a length that is a text, a position beyond 32 bits, an object that answers
|
|
24
|
+
* differently the second time it is asked. So every length and every argument a decision
|
|
25
|
+
* rests on is converted here, once, the way the built-in converts it, and the built-in is
|
|
26
|
+
* given the converted value. This holds for the text methods as well (`join`,
|
|
27
|
+
* `toLocaleString`, `repeat`, `padStart`, `padEnd`), which are wrapped here for that reason.
|
|
28
|
+
* It holds for what a receiver holds as well. An object that is not an array can answer
|
|
29
|
+
* for its length and for each slot through an accessor, differently every time: where a
|
|
30
|
+
* decision rests on it, it is read here, once (its length, then each slot, with the object
|
|
31
|
+
* itself as the receiver of the read), and the built-in works on the plain copy.
|
|
32
|
+
* (`Array.from` and `Array.fromAsync` hand a mapping function one slot before they read the
|
|
33
|
+
* next: of them the length is read here, once, and each slot when the built-in asks.) `flat`
|
|
34
|
+
* reads the elements of arrays too, and `concat` asks every value whether it is spread,
|
|
35
|
+
* which code of the script can answer, for an array as for anything else; so the result of
|
|
36
|
+
* these two is built in the pass that counts it, and the built-in does not run (for
|
|
37
|
+
* `concat`: ATK-MEMACC-31). Otherwise an array is handed on as it is: its length is its
|
|
38
|
+
* own, and nothing here reads its elements before the built-in does. An array behind a
|
|
39
|
+
* proxy is not its own answer. Where a realm leaves a script the Proxy constructor, the
|
|
40
|
+
* script gets a stand-in for it that remembers the proxies it makes, and such a proxy is
|
|
41
|
+
* read like any object that states a length (ATK-MEMACC-21).
|
|
42
|
+
* 4. No array has more slots than the limit holds, and no built-in works through more. The
|
|
43
|
+
* slots between the elements of an array hold nothing and cost nothing to make, but every
|
|
44
|
+
* built-in that goes by the length works through them, and one call into a built-in is
|
|
45
|
+
* finished by the engine: the deadline is not looked at inside it. So the length is what
|
|
46
|
+
* is bounded. A write that would give an array more slots than the limit holds is refused,
|
|
47
|
+
* and the slots a write adds are charged, the empty ones included: an element beyond the
|
|
48
|
+
* end and an assignment to `length` (the transform hands every such write to `__safe_set`
|
|
49
|
+
* and `__safe_slot`, see guardArrayWrites in @enclave-vm/ast), `Array(n)` under any name
|
|
50
|
+
* (the global is a guarded stand-in), `Object.assign`, the property definitions. And a
|
|
51
|
+
* built-in that works through its receiver is not given an object that states a longer
|
|
52
|
+
* length: of an object the length is read once, a built-in that reads works on a plain
|
|
53
|
+
* copy, and one that moves the slots of its receiver works on the object itself only when
|
|
54
|
+
* its length is a number it holds.
|
|
55
|
+
*
|
|
56
|
+
* What it does not cover: a copy is free, so a script can still hold many arrays that are each
|
|
57
|
+
* within the limit; object literals, Maps and Sets are not counted. With no limit (0) none of
|
|
58
|
+
* the rules applies, the fourth included. The limit is an estimate,
|
|
59
|
+
* not the engine's: where the host must survive whatever a script allocates, the script belongs
|
|
60
|
+
* in a worker or a process of its own.
|
|
61
|
+
*
|
|
62
|
+
* @packageDocumentation
|
|
63
|
+
*/
|
|
64
|
+
/** Bytes an array element is counted as. */
|
|
65
|
+
export declare const ARRAY_ELEMENT_BYTES = 8;
|
|
66
|
+
/** Name of the realm function that opens the accounting of an array literal with spreads. */
|
|
67
|
+
export declare const ARRAY_START_FN = "__safe_arrayStart";
|
|
68
|
+
/** Name of the realm function a spread source of an array literal passes through. */
|
|
69
|
+
export declare const ARRAY_SPREAD_FN = "__safe_spread";
|
|
70
|
+
/** Name of the realm function that closes the accounting of an array literal with spreads. */
|
|
71
|
+
export declare const ARRAY_FINISH_FN = "__safe_array";
|
|
72
|
+
/** Name of the realm function a write `X[K] = V` goes through (see ARRAY_WRITE_SET_FN in @enclave-vm/ast). */
|
|
73
|
+
export declare const ARRAY_SET_FN = "__safe_set";
|
|
74
|
+
/** Name of the realm function that stands in for the target of every other write through a member. */
|
|
75
|
+
export declare const ARRAY_SLOT_FN = "__safe_slot";
|
|
76
|
+
/**
|
|
77
|
+
* Source of a statement that patches the realm's array built-ins and defines the three helpers
|
|
78
|
+
* the transformed code calls around an array literal with spreads.
|
|
79
|
+
*
|
|
80
|
+
* Evaluate it in the sandbox realm before any script code and before the realm's prototypes are
|
|
81
|
+
* frozen, where `__host_memory_track__` is the realm-side function that charges the execution's
|
|
82
|
+
* memory tracker. With `memoryLimit` 0 the helpers are defined and count nothing. With a limit,
|
|
83
|
+
* the statement throws where a part of the accounting cannot be put in place (a global or a
|
|
84
|
+
* method of the realm that cannot be replaced any more): the realm is then not set up, and no
|
|
85
|
+
* script runs in it with a part of the checks off.
|
|
86
|
+
*
|
|
87
|
+
* @param memoryLimit The execution's memory limit in bytes, 0 for none
|
|
88
|
+
*/
|
|
89
|
+
export declare function realmArrayAccountingSource(memoryLimit: number): string;
|
package/realm-stack.d.ts
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* No stack traces for errors made in a sandbox realm
|
|
3
|
+
*
|
|
4
|
+
* The engine captures a stack trace when an error is made and formats it the first time `stack`
|
|
5
|
+
* is read. Node.js formats with a function of its own that is installed for the whole process,
|
|
6
|
+
* JavaScript of the host realm, and a sandbox realm has no way to put another one in its place.
|
|
7
|
+
* Whatever that function throws (it reads the error's `name` and `message`, and it needs stack to
|
|
8
|
+
* run at all) is an error of the host realm, raised in the middle of the script.
|
|
9
|
+
*
|
|
10
|
+
* So a sandbox realm does not capture stack traces. `Error.stackTraceLimit` of the realm is
|
|
11
|
+
* defined as a value that is not a number, read-only: the engine then captures nothing, an error
|
|
12
|
+
* has no `stack`, and the formatter is never called for an error of that realm. The property
|
|
13
|
+
* cannot be changed back by a script.
|
|
14
|
+
*
|
|
15
|
+
* What it costs: an error made inside the sandbox has no `stack`, for the script and in
|
|
16
|
+
* `result.error`. Errors the host makes (a tool handler's, a validation error) keep theirs and
|
|
17
|
+
* are subject to `sanitizeStackTraces` as before.
|
|
18
|
+
*
|
|
19
|
+
* @packageDocumentation
|
|
20
|
+
*/
|
|
21
|
+
/**
|
|
22
|
+
* Source to run in a sandbox realm, before anything else runs there and while `Error` is still
|
|
23
|
+
* the realm's own intrinsic. Idempotent.
|
|
24
|
+
*/
|
|
25
|
+
export declare const STACK_CAPTURE_OFF_SOURCE: string;
|
package/safe-runtime.d.ts
CHANGED
|
@@ -48,6 +48,8 @@ export interface SafeRuntimeOptions {
|
|
|
48
48
|
exposeToSandbox?: (value: unknown) => unknown;
|
|
49
49
|
/** Passed to the secure proxies this runtime creates (see `SecureProxyOptions.ownedBySandbox`). */
|
|
50
50
|
ownedBySandbox?: (value: object) => boolean;
|
|
51
|
+
/** Passed to the secure proxies this runtime creates (see `SecureProxyOptions.heldBySandbox`). */
|
|
52
|
+
heldBySandbox?: (value: object) => boolean;
|
|
51
53
|
/**
|
|
52
54
|
* Whether the result includes the host's standard library (`Math`, `JSON`, `Array`, `Object`,
|
|
53
55
|
* `String`, `Number`, `Date`) behind secure proxies, the custom globals and the loop,
|
package/sandbox-rejections.d.ts
CHANGED
|
@@ -18,7 +18,9 @@
|
|
|
18
18
|
* its reason; Node.js prints no warning when the script handles the rejection late;
|
|
19
19
|
* - everything else, the application's own rejections included, goes to the `emit` that was
|
|
20
20
|
* there before, untouched. What Node.js or the application does with those is what it did
|
|
21
|
-
* without this module, in every `--unhandled-rejections` mode.
|
|
21
|
+
* without this module, in every `--unhandled-rejections` mode. That includes an event whose
|
|
22
|
+
* promise is not a promise of the engine at all: a promise library reports the rejections of
|
|
23
|
+
* its own promise type by emitting the event itself, and Node.js never does that for a script.
|
|
22
24
|
*
|
|
23
25
|
* A reason is never read, formatted or passed on here. Formatting one with `util.inspect`, as a
|
|
24
26
|
* log line or Node's printer for an uncaught error would, calls a method the value can supply
|
|
@@ -6,26 +6,76 @@
|
|
|
6
6
|
*
|
|
7
7
|
* @packageDocumentation
|
|
8
8
|
*/
|
|
9
|
+
import type { NormalizedToolNamespace } from '@enclave-vm/ast';
|
|
9
10
|
import type { ExtractedFeatures } from './types';
|
|
11
|
+
/**
|
|
12
|
+
* Options of the feature extractor
|
|
13
|
+
*/
|
|
14
|
+
export interface FeatureExtractorOptions {
|
|
15
|
+
/**
|
|
16
|
+
* The tool namespaces of the sandbox the code is written for. A call of a namespace method
|
|
17
|
+
* (`mail.send(args)`) is the tool call it stands for (`callTool('mail.send', args)`) and is
|
|
18
|
+
* extracted as one.
|
|
19
|
+
*/
|
|
20
|
+
toolNamespaces?: ReadonlyArray<NormalizedToolNamespace>;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Error thrown when code cannot be analysed. The scoring gate treats it like any other scoring
|
|
24
|
+
* error: `failOpen` decides whether the script runs.
|
|
25
|
+
*/
|
|
26
|
+
export declare class FeatureExtractionError extends Error {
|
|
27
|
+
constructor(message: string);
|
|
28
|
+
}
|
|
10
29
|
/**
|
|
11
30
|
* Feature Extractor - extracts security-relevant features from code
|
|
12
31
|
*/
|
|
13
32
|
export declare class FeatureExtractor {
|
|
33
|
+
/** Namespace name -> method name -> tool name */
|
|
34
|
+
private readonly toolNamespaces;
|
|
35
|
+
constructor(options?: FeatureExtractorOptions);
|
|
14
36
|
/**
|
|
15
37
|
* Extract features from code
|
|
16
38
|
*
|
|
17
39
|
* @param code - Source code to analyze
|
|
18
40
|
* @returns Extracted features for scoring
|
|
41
|
+
* @throws FeatureExtractionError if the code cannot be parsed: text that cannot be read has
|
|
42
|
+
* no features, which is not the same as having none that count
|
|
19
43
|
*/
|
|
20
44
|
extract(code: string): ExtractedFeatures;
|
|
21
45
|
/**
|
|
22
46
|
* Parse code into AST
|
|
47
|
+
*
|
|
48
|
+
* The code is read as a module, in which a top-level `await` is allowed, and a top-level
|
|
49
|
+
* `return` is accepted as well: both forms of AgentScript can be analysed, the script as its
|
|
50
|
+
* author wrote it and the script wrapped in its main function.
|
|
51
|
+
*
|
|
52
|
+
* @throws FeatureExtractionError if the code does not parse
|
|
23
53
|
*/
|
|
24
54
|
private parseCode;
|
|
55
|
+
/**
|
|
56
|
+
* The string a node spells out in the source: a string literal, or a template literal without
|
|
57
|
+
* substitutions. `undefined` for anything else.
|
|
58
|
+
*/
|
|
59
|
+
private staticString;
|
|
60
|
+
/**
|
|
61
|
+
* The tool a member expression on a tool namespace refers to: `mail.send`, `mail['send']`
|
|
62
|
+
* (static), `mail[name]` (dynamic). `undefined` when the object is not a tool namespace, or
|
|
63
|
+
* the member is not one of its methods (nothing is called then).
|
|
64
|
+
*/
|
|
65
|
+
private toolReferenceOfMember;
|
|
66
|
+
/**
|
|
67
|
+
* The tool a call expression calls, by its callee: `callTool(name, args)`,
|
|
68
|
+
* `__safe_callTool(name, args)`, or a method of a tool namespace. `undefined` for any other call.
|
|
69
|
+
*/
|
|
70
|
+
private toolReferenceOfCallee;
|
|
25
71
|
/**
|
|
26
72
|
* Extract tool call information
|
|
27
73
|
*/
|
|
28
74
|
private extractToolCall;
|
|
75
|
+
/**
|
|
76
|
+
* Add one tool call to the features
|
|
77
|
+
*/
|
|
78
|
+
private recordToolCall;
|
|
29
79
|
/**
|
|
30
80
|
* Extract information from tool arguments
|
|
31
81
|
*/
|
|
@@ -43,7 +93,8 @@ export declare class FeatureExtractor {
|
|
|
43
93
|
*/
|
|
44
94
|
private findMaxLimitValue;
|
|
45
95
|
/**
|
|
46
|
-
* Hash code for caching
|
|
96
|
+
* Hash code for caching: the whole SHA-256 digest. The hash is the only key of a cached
|
|
97
|
+
* decision, so two texts may share a decision only if they are the same text.
|
|
47
98
|
*/
|
|
48
99
|
private hashCode;
|
|
49
100
|
/**
|
package/scoring/index.d.ts
CHANGED
|
@@ -24,7 +24,8 @@
|
|
|
24
24
|
* @packageDocumentation
|
|
25
25
|
*/
|
|
26
26
|
export { ScoringGate, ScoringGateError, createScoringGate } from './scoring-gate';
|
|
27
|
-
export { FeatureExtractor } from './feature-extractor';
|
|
27
|
+
export { FeatureExtractor, FeatureExtractionError } from './feature-extractor';
|
|
28
|
+
export type { FeatureExtractorOptions } from './feature-extractor';
|
|
28
29
|
export { ScoringCache } from './cache';
|
|
29
30
|
export { BaseScorer } from './scorer.interface';
|
|
30
31
|
export type { Scorer } from './scorer.interface';
|