@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.
Files changed (48) hide show
  1. package/README.md +262 -105
  2. package/adapters/interpreter-adapter.d.ts +10 -1
  3. package/adapters/worker-pool/config.d.ts +15 -5
  4. package/adapters/worker-pool/protocol.d.ts +27 -1
  5. package/adapters/worker-pool/worker-pool-adapter.d.ts +24 -0
  6. package/adapters/worker-pool/worker-slot.d.ts +35 -6
  7. package/async-context.d.ts +34 -0
  8. package/babel/babel-wrapper.d.ts +21 -12
  9. package/babel/multi-file-transform.d.ts +3 -0
  10. package/babel/text-scan.d.ts +54 -0
  11. package/deadline-guard.d.ts +16 -0
  12. package/dynamic-import.d.ts +25 -0
  13. package/enclave-options.d.ts +62 -0
  14. package/enclave.d.ts +31 -7
  15. package/esm/index.mjs +4796 -852
  16. package/esm/worker.mjs +1236 -165
  17. package/execution-deadline.d.ts +6 -0
  18. package/global-function-gate.d.ts +34 -1
  19. package/index.d.ts +3 -3
  20. package/index.js +4836 -892
  21. package/interpreter/interpreter.d.ts +247 -8
  22. package/memory-tracker.d.ts +7 -0
  23. package/package.json +3 -3
  24. package/realm-airlock.d.ts +6 -1
  25. package/realm-memory.d.ts +89 -0
  26. package/realm-stack.d.ts +25 -0
  27. package/safe-runtime.d.ts +2 -0
  28. package/sandbox-rejections.d.ts +3 -1
  29. package/scoring/feature-extractor.d.ts +52 -1
  30. package/scoring/index.d.ts +2 -1
  31. package/scoring/scorers/index.d.ts +2 -1
  32. package/scoring/scorers/local-llm.scorer.d.ts +9 -3
  33. package/scoring/scorers/progressive.scorer.d.ts +28 -1
  34. package/scoring/scorers/rule-based.scorer.d.ts +11 -1
  35. package/scoring/types.d.ts +36 -8
  36. package/secure-proxy.d.ts +17 -3
  37. package/session/session.d.ts +8 -1
  38. package/session-types.d.ts +6 -4
  39. package/sidecar/index.d.ts +1 -1
  40. package/sidecar/reference-config.d.ts +18 -1
  41. package/sidecar/reference-resolver.d.ts +19 -1
  42. package/sidecar/reference-sidecar.d.ts +37 -0
  43. package/src/adapters/worker-pool/package.json +3 -3
  44. package/src/adapters/worker-pool/worker-script.js +2250 -428
  45. package/thrown-value.d.ts +59 -0
  46. package/types.d.ts +75 -19
  47. package/value-sanitizer.d.ts +6 -1
  48. 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[]): void;
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
- /** Max nested call depth (interpreter-defined functions). */
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
- private callDepth;
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
- /** The error that ended the run (step budget, abort, allocation budget); set once, never caught */
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 function a built-in
102
- * started and nobody awaited, a callback waiting for a tool call) stops at its next step. The
103
- * host calls this when the execution has returned, so that no script code runs after it.
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
- /** Apply a binary operator to two values. */
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
+ };
@@ -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.0",
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.0",
48
- "@enclave-vm/types": "2.19.0",
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",
@@ -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; this layer decides nothing except that host values are read-only.
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;
@@ -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,
@@ -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
  /**
@@ -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';