@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
@@ -2,8 +2,17 @@ import type { ExecutionContext, ExecutionResult, SandboxAdapter } from '../types
2
2
  export interface InterpreterAdapterOptions {
3
3
  /** Override the instruction budget (default 5,000,000). */
4
4
  maxSteps?: number;
5
- /** Override the max interpreter call depth (default 256). */
5
+ /**
6
+ * How deep the calls of a script may nest (default 256). Counted along each chain of calls: a
7
+ * callback is a call of the function that invokes it, and the tasks of a `parallel` batch each
8
+ * continue the chain that started the batch, so a batch does not add up.
9
+ */
6
10
  maxCallDepth?: number;
11
+ /**
12
+ * How many calls of an execution may be unfinished at once, running or waiting, over all its
13
+ * chains (default 4096). It bounds what the waiting calls of nested `parallel` batches hold.
14
+ */
15
+ maxPendingCalls?: number;
7
16
  /**
8
17
  * The most a script may allocate, in bytes, as the interpreter estimates it (default 64 MB).
9
18
  * An execution's own `memoryLimit` applies when it is lower.
@@ -55,23 +55,33 @@ export interface WorkerPoolConfig {
55
55
  */
56
56
  maxQueueSize: number;
57
57
  /**
58
- * Time to wait for graceful shutdown before force terminating workers
58
+ * Time an idle worker that was asked to exit gets before it is terminated. Only a worker with
59
+ * nothing to run is asked: one that may still be running a script is terminated at once.
59
60
  * @default 5000
60
61
  */
61
62
  gracefulShutdownTimeoutMs: number;
62
63
  /**
63
- * Maximum messages per second allowed from a single worker
64
- * Prevents message flooding attacks
64
+ * Maximum messages per second a worker may send while it runs one execution: what a script
65
+ * makes it send (tool calls, console output). The count starts with each execution; the
66
+ * result and the worker's confirmation that it is idle are not counted. An execution that
67
+ * sends more fails with `MessageFloodError`, and its worker is terminated.
65
68
  * @default 1000
66
69
  */
67
70
  maxMessagesPerSecond: number;
68
71
  /**
69
- * Maximum concurrent pending tool calls per execution
72
+ * Maximum concurrent pending tool calls per execution. An execution with more in flight fails
73
+ * with `TooManyPendingCallsError`, and its worker is terminated.
70
74
  * @default 100
71
75
  */
72
76
  maxPendingToolCalls: number;
73
77
  /**
74
- * Maximum size of a single message in bytes
78
+ * Maximum size of a single message from a worker, in bytes. A larger message is refused before
79
+ * it is parsed: the execution fails with `MessageSizeError` and the worker is replaced.
80
+ *
81
+ * The limit applied to an execution is never below what the enclave's own limits let one
82
+ * message carry: a tool request (`toolBridge.maxPayloadBytes`) or a result (`memoryLimit`).
83
+ * So it decides where those are larger than it or off: with `memoryLimit: 0` it is the only
84
+ * bound on the size of a result.
75
85
  * @default 16 * 1024 * 1024 (16MB)
76
86
  */
77
87
  maxMessageSizeBytes: number;
@@ -237,10 +237,22 @@ export interface ConsoleMessage {
237
237
  /** Console arguments */
238
238
  args: unknown[];
239
239
  }
240
+ /**
241
+ * The worker has nothing left to run for an execution.
242
+ *
243
+ * Sent after the result, from a new turn of the worker's event loop: a turn the worker only
244
+ * reaches when the script, and everything the script scheduled, has stopped running. The pool
245
+ * waits for it before the worker is given to another execution.
246
+ */
247
+ export interface WorkerIdleMessage {
248
+ type: 'idle';
249
+ /** The execution that has ended */
250
+ requestId: string;
251
+ }
240
252
  /**
241
253
  * Union of all messages from worker to main thread
242
254
  */
243
- export type WorkerToMainMessage = WorkerReadyMessage | ToolCallMessage | ExecutionResultMessage | MemoryReportResultMessage | ConsoleMessage;
255
+ export type WorkerToMainMessage = WorkerReadyMessage | ToolCallMessage | ExecutionResultMessage | MemoryReportResultMessage | ConsoleMessage | WorkerIdleMessage;
244
256
  /**
245
257
  * Zod schema for tool call messages
246
258
  */
@@ -319,6 +331,13 @@ export declare const consoleMessageSchema: z.ZodObject<{
319
331
  export declare const workerReadyMessageSchema: z.ZodObject<{
320
332
  type: z.ZodLiteral<"ready">;
321
333
  }, z.core.$strict>;
334
+ /**
335
+ * Zod schema for worker idle messages
336
+ */
337
+ export declare const workerIdleMessageSchema: z.ZodObject<{
338
+ type: z.ZodLiteral<"idle">;
339
+ requestId: z.ZodString;
340
+ }, z.core.$strict>;
322
341
  /**
323
342
  * Union schema for all worker-to-main messages
324
343
  */
@@ -380,6 +399,9 @@ export declare const workerToMainMessageSchema: z.ZodDiscriminatedUnion<[z.ZodOb
380
399
  debug: "debug";
381
400
  }>;
382
401
  args: z.ZodArray<z.ZodUnknown>;
402
+ }, z.core.$strict>, z.ZodObject<{
403
+ type: z.ZodLiteral<"idle">;
404
+ requestId: z.ZodString;
383
405
  }, z.core.$strict>], "type">;
384
406
  /**
385
407
  * Type guard for tool call messages
@@ -401,3 +423,7 @@ export declare function isConsoleMessage(msg: WorkerToMainMessage): msg is Conso
401
423
  * Type guard for worker ready messages
402
424
  */
403
425
  export declare function isWorkerReadyMessage(msg: WorkerToMainMessage): msg is WorkerReadyMessage;
426
+ /**
427
+ * Type guard for worker idle messages
428
+ */
429
+ export declare function isWorkerIdleMessage(msg: WorkerToMainMessage): msg is WorkerIdleMessage;
@@ -24,6 +24,11 @@ import type { DoubleVmConfig } from '../../double-vm/types';
24
24
  * by default (or a single VM when the double VM is disabled). The worker thread is an additional
25
25
  * layer around that sandbox, not a replacement for it. Tool calls come back to this thread and
26
26
  * go through the same tool bridge as in-process tool calls.
27
+ *
28
+ * A worker runs one execution at a time. It goes back into the pool only when it has confirmed,
29
+ * after its result, that nothing of the script is left in it; in every other case (no
30
+ * confirmation in time, an execution this side ended, a message the protocol does not allow)
31
+ * the worker is terminated and the pool goes on with a new one.
27
32
  */
28
33
  export declare class WorkerPoolAdapter implements SandboxAdapter {
29
34
  private readonly config;
@@ -53,6 +58,11 @@ export declare class WorkerPoolAdapter implements SandboxAdapter {
53
58
  private _heapLimitKills;
54
59
  /** Workers already counted as a memory kill (by the memory monitor or as a heap-limit kill) */
55
60
  private readonly memoryKilledSlots;
61
+ /**
62
+ * Workers that sent a message for an execution other than the one they are running. Such a
63
+ * worker is not in the state the pool believes: it is not given another execution.
64
+ */
65
+ private readonly distrustedSlots;
56
66
  /**
57
67
  * @param config Worker pool configuration
58
68
  * @param securityLevel Security level of the enclave
@@ -93,11 +103,25 @@ export declare class WorkerPoolAdapter implements SandboxAdapter {
93
103
  * forever, and with one worker every later execution would wait in the queue until it timed out.
94
104
  */
95
105
  private removeDeadSlot;
106
+ /**
107
+ * End a worker that is alive but cannot be trusted to be free, and take it out of the pool.
108
+ * The next execution finds the pool below its size and gets a new worker.
109
+ */
110
+ private retireSlot;
96
111
  private releaseSlot;
97
112
  private handleSlotRecycling;
98
113
  private handleMemoryExceeded;
99
114
  private checkIdleSlots;
100
115
  private executeInSlot;
116
+ /**
117
+ * The largest message a worker may send while it runs a script of this execution.
118
+ *
119
+ * `maxMessageSizeBytes`, but never less than what the enclave's own limits allow one message
120
+ * to carry: a tool request (the tool bridge's `maxPayloadBytes`) or a result (the serialized
121
+ * size the sandbox accepts under `memoryLimit`). Where the sandbox bounds nothing itself
122
+ * (`memoryLimit: 0`), this is the bound on what the host thread parses.
123
+ */
124
+ private messageSizeLimit;
101
125
  private handleToolCall;
102
126
  private handleConsoleMessage;
103
127
  /**
@@ -8,7 +8,7 @@
8
8
  */
9
9
  import { Worker } from 'worker_threads';
10
10
  import { EventEmitter } from 'events';
11
- import type { WorkerSlotStatus, ResourceUsage } from './config';
11
+ import { type WorkerSlotStatus, type ResourceUsage } from './config';
12
12
  import { type MainToWorkerMessage, type WorkerToMainMessage } from './protocol';
13
13
  /**
14
14
  * Events emitted by WorkerSlot
@@ -35,6 +35,13 @@ export interface WorkerSlotOptions {
35
35
  memoryLimitMB: number;
36
36
  /** Startup timeout in milliseconds */
37
37
  startupTimeoutMs?: number;
38
+ /**
39
+ * Largest message the worker may send, in bytes of UTF-8. A larger one is refused before it is
40
+ * parsed. Default: the pool's default `maxMessageSizeBytes`.
41
+ */
42
+ maxMessageSizeBytes?: number;
43
+ /** How long an idle worker that was asked to leave gets before it is terminated. Default: 5000 */
44
+ gracefulShutdownTimeoutMs?: number;
38
45
  }
39
46
  /**
40
47
  * The young generation of a worker that has a memory limit, in MB.
@@ -127,8 +134,14 @@ export declare class WorkerSlot extends EventEmitter {
127
134
  private _heapLimitEnforcement;
128
135
  /** What this worker may hold: its limit plus the young generation, in bytes. 0 without a limit. */
129
136
  private _memoryBudgetBytes;
130
- /** The host-side heap check of the running execution (only with `host` enforcement) */
137
+ /** The host-side memory check of the running execution */
131
138
  private heapWatchdog;
139
+ /** Largest message the worker may send right now, in bytes (see limitMessageSize) */
140
+ private messageSizeLimitBytes;
141
+ /** The worker sent something the protocol does not allow: it is ended, not asked to leave */
142
+ private protocolViolated;
143
+ /** Memory reports asked for and not answered yet: each entry ends its request */
144
+ private readonly pendingMemoryReports;
132
145
  /** Configuration */
133
146
  private readonly options;
134
147
  /** Message handler bound to this instance */
@@ -160,10 +173,20 @@ export declare class WorkerSlot extends EventEmitter {
160
173
  */
161
174
  private resolveHeapLimitEnforcement;
162
175
  /**
163
- * With `host` enforcement: read the worker's heap while it executes, and end the execution
164
- * when the worker holds more than its budget. The engine would have done the same at the old
165
- * generation limit; from outside only the total is visible, so the young generation is part
166
- * of the budget and the limit is approximate (a script can also allocate between two reads).
176
+ * Read what the worker holds while it executes (its heap plus its external memory), and end
177
+ * the execution when that is more than the worker's budget.
178
+ *
179
+ * With `host` enforcement this is the heap limit itself: the engine would have ended the worker
180
+ * at the old generation limit; from outside only the total is visible, so the young generation
181
+ * is part of the budget and the limit is approximate (a script can also allocate between two
182
+ * reads).
183
+ *
184
+ * With `engine` enforcement the engine bounds the heap, and this bounds what the engine does
185
+ * not count: memory outside the heap. The memory monitor counts it too, but it asks the worker
186
+ * by message, and a worker answers messages only when its script lets it. This read needs no
187
+ * answer from the script.
188
+ *
189
+ * Not on a Node.js that cannot read a worker's heap from outside (before 22.16).
167
190
  */
168
191
  private startHeapWatchdog;
169
192
  private stopHeapWatchdog;
@@ -185,6 +208,12 @@ export declare class WorkerSlot extends EventEmitter {
185
208
  * Acquire this slot for execution
186
209
  */
187
210
  acquire(executionId: string): void;
211
+ /**
212
+ * The largest message the worker may send while it runs the next execution, in bytes. The pool
213
+ * sets it per execution, because what one message may legitimately carry depends on the
214
+ * limits of the enclave the script belongs to. release() puts the slot's own limit back.
215
+ */
216
+ limitMessageSize(maxBytes: number): void;
188
217
  /**
189
218
  * Release this slot after execution
190
219
  */
@@ -0,0 +1,34 @@
1
+ /**
2
+ * The async context a script runs in
3
+ *
4
+ * A host commonly calls `run()` inside `AsyncLocalStorage.run(store, ...)`: a request context, a
5
+ * tracing span. Where the engine propagates such a store by copying it onto every async resource
6
+ * (Node.js 22, and later versions started without async context frames), a promise that a script
7
+ * creates in a `vm` context is such a resource: the store, an object of the host, hangs on it as
8
+ * an own symbol-keyed property, with no membrane in between.
9
+ *
10
+ * So the script does not run in the caller's async context. Two async resources are made for an
11
+ * execution:
12
+ *
13
+ * - one in which no store is current, for the script: what the engine copies onto the script's
14
+ * promises there is `undefined`;
15
+ * - one that is the caller's context, for everything of the host that the script causes to run
16
+ * (the tool handler, the console handler, a function from `globals`): those still read the
17
+ * store of the `run()` that called them.
18
+ *
19
+ * Where the runtime has no `async_hooks` (a bundle for another runtime), both are plain calls.
20
+ *
21
+ * @packageDocumentation
22
+ */
23
+ /** The two contexts of one execution (see the module documentation). */
24
+ export interface AsyncContexts {
25
+ /** Run `fn` in the async context of the caller of `run()`. */
26
+ inHostContext<R>(fn: () => R): R;
27
+ /** Run `fn` in an async context that carries no store of the host. */
28
+ inScriptContext<R>(fn: () => R): R;
29
+ }
30
+ /**
31
+ * Make the two async contexts of an execution. Call it where `run()` was called: the host
32
+ * context is the one that is current here.
33
+ */
34
+ export declare function separateAsyncContexts(): AsyncContexts;
@@ -4,14 +4,23 @@
4
4
  * Provides a restricted Babel.transform() API for use inside the enclave sandbox.
5
5
  * Uses @babel/standalone for browser-compatible transformation.
6
6
  *
7
- * SECURITY: Babel transforms run in an isolated VM context with NO access to:
8
- * - File system (fs, path)
9
- * - Process/environment (process, env)
10
- * - Network (http, https, net)
11
- * - Child processes (child_process)
12
- * - Module loading (require, import)
7
+ * SECURITY: where Babel runs, and what restricts it.
13
8
  *
14
- * Only pure JavaScript transformation is allowed.
9
+ * `@babel/standalone` is loaded into the host realm and runs there, with the host's intrinsics
10
+ * and the host's authority, like any other function a host puts in `globals`. It is called from
11
+ * a separate VM context, and what that context provides is a timeout for the call: a function
12
+ * runs in the realm it was created in, whichever context calls it, so the context is not an
13
+ * isolation boundary and takes nothing away from Babel.
14
+ *
15
+ * What a script can make Babel do is restricted by what this wrapper passes on:
16
+ * - the source text is data: Babel parses and prints it and never executes it
17
+ * - presets are names from the security level's allowlist; plugins are always none
18
+ * - no configuration files, no source maps, no AST in the result
19
+ * - a sanitized file name, a size limit on the input and on the output, and the timeout
20
+ * - the work the wrapper itself does on a script's text is linear in its size
21
+ *
22
+ * A defect in Babel's parser or in a preset would therefore be a defect in host code. A host
23
+ * that needs Babel isolated from its process runs the enclave in a process of its own.
15
24
  *
16
25
  * @packageDocumentation
17
26
  */
@@ -71,10 +80,10 @@ export interface BabelWrapperConfig {
71
80
  /**
72
81
  * Create a restricted Babel object for sandbox use
73
82
  *
74
- * SECURITY: All transforms run in an isolated VM context with:
75
- * - NO access to fs, process, require, or any Node.js APIs
76
- * - NO access to network APIs
77
- * - NO ability to load external code
83
+ * SECURITY: Babel runs in the host realm (see the header of this file). A transform is
84
+ * restricted by what this function passes to it and checks around it:
85
+ * - the source is parsed and printed, never executed
86
+ * - no plugins, no configuration files, no source maps, no AST output
78
87
  * - Timeout enforcement
79
88
  * - Input/output size limits
80
89
  * - Preset whitelist
@@ -110,7 +119,7 @@ export declare function createRestrictedBabel(config: BabelWrapperConfig): {
110
119
  */
111
120
  export declare function getAvailableBabelPresets(): string[];
112
121
  /**
113
- * Reset the isolated Babel context
122
+ * Reset the context Babel is called from
114
123
  *
115
124
  * Useful for testing or if you want to ensure a fresh context.
116
125
  * Note: This is generally not needed as the context is reused for performance.
@@ -12,6 +12,9 @@
12
12
  * - Total input/output size limits
13
13
  * - Filename sanitization
14
14
  * - No path traversal in filenames
15
+ * - The file set is a script's: besides Babel itself (which has its own timeout), everything
16
+ * done here with a file's text or name takes time linear in the size of the input, and the
17
+ * text is measured against the limits before it is worked on (see ./text-scan)
15
18
  *
16
19
  * @packageDocumentation
17
20
  */
@@ -0,0 +1,54 @@
1
+ /**
2
+ * Scans of text a script controls
3
+ *
4
+ * The Babel path reads three things out of text it did not write: which modules a source file
5
+ * names in its imports (to order the files and report their dependencies), where the import
6
+ * paths are in the code Babel produced (to give a local import the extension of the file it will
7
+ * find), and where the stack locations are in the message of a failed transform (Babel quotes
8
+ * the source in it). That text is a script's, and this work runs in the host outside every
9
+ * timeout, so each scan here takes time linear in the length of the text, whatever the text is:
10
+ *
11
+ * - the text is read from left to right, one occurrence of a keyword after the other;
12
+ * - every search for "the next character of some kind" remembers its answer (`forwardSearch`)
13
+ * and is asked with starts that never decrease, and every check of the text around such an
14
+ * answer remembers its result, so no stretch of text is examined again for a later occurrence
15
+ * of the keyword.
16
+ *
17
+ * No regular expression is applied to the text. What is recognised is what the expressions
18
+ * these scans replace recognised, character for character; the comment of each scan states it.
19
+ *
20
+ * @packageDocumentation
21
+ */
22
+ /**
23
+ * The module specifiers a source file names: first what follows each `import` keyword, then the
24
+ * dynamic imports written with a string (which the first pass has seen as well).
25
+ *
26
+ * This reads TypeScript and JSX as text, before Babel has parsed them, so it is an
27
+ * approximation: a keyword inside a comment or a string counts. It decides the order in which
28
+ * files are transformed and what the dependency report says, nothing else.
29
+ */
30
+ export declare function findImportSources(text: string): string[];
31
+ /**
32
+ * Apply `map` to the specifier of every static import statement of `text` and return the text
33
+ * with the specifiers `map` changed.
34
+ *
35
+ * An import statement is the keyword followed by one of
36
+ *
37
+ * - white space and a quoted string: `import './a'`
38
+ * - white space, a clause in braces, `from` and a quoted string: `import { a, b } from './a'`
39
+ * - a clause of names, `*` and commas, `from` and a quoted string: `import a from './a'`,
40
+ * `import * as a from './a'`
41
+ *
42
+ * where the quoted string is not empty. Re-exports and dynamic imports are not import
43
+ * statements in this sense and are left as they are.
44
+ */
45
+ export declare function mapStaticImportSources(text: string, map: (source: string) => string): string;
46
+ /**
47
+ * Whether a specifier ends in a file extension: a dot followed by ASCII letters, at the end.
48
+ */
49
+ export declare function hasFileExtension(source: string): boolean;
50
+ /**
51
+ * Remove what looks like a stack location from a message: `at`, white space, a name without
52
+ * white space, white space, and a parenthesis that is not empty, as in `at parse (file:1:2)`.
53
+ */
54
+ export declare function removeStackLocations(text: string): string;
@@ -11,6 +11,8 @@
11
11
  * - at the start of every function body (arrow functions with an expression body get a block body),
12
12
  * which bounds recursion and every callback a built-in drives (`map`, `sort`, a Proxy trap, a
13
13
  * `toString` called by a coercion, ...);
14
+ * - in front of what a parameter evaluates before the body starts (a default value, a computed
15
+ * key of a destructuring pattern);
14
16
  * - at the start of every loop body.
15
17
  *
16
18
  * `__ag_tick` is the sandbox realm's `__safe_tick`, captured once at program scope. The adapter
@@ -38,6 +40,14 @@ export declare const REALM_TICK_FN = "__safe_tick";
38
40
  * increment, and a tick is at most one loop iteration or function entry apart from the next.
39
41
  */
40
42
  export declare const TICKS_PER_CLOCK_CHECK = 256;
43
+ /**
44
+ * How many more checks pass once an execution has ended, before every further check throws.
45
+ * Enough for what a script left behind to settle; a chain that re-arms itself is over within
46
+ * microseconds.
47
+ */
48
+ export declare const TICKS_AFTER_END = 1024;
49
+ /** What a deadline check throws once the execution it belongs to has ended. */
50
+ export declare const EXECUTION_ENDED_MESSAGE = "Script execution has ended";
41
51
  /** Result of the deadline-guard transform. */
42
52
  export interface DeadlineGuardResult {
43
53
  /** Number of function and loop bodies that received a deadline check. */
@@ -61,5 +71,11 @@ export declare function injectDeadlineChecks(ast: acorn.Node, parse: (source: st
61
71
  * It captures the realm's own `Date.now` (so nothing the script does to `Date` afterwards matters)
62
72
  * and installs `__safe_tick` as a read-only global. What it throws is a string: an inert value in a
63
73
  * script's `catch`, and the adapters already report a thrown string as the error message.
74
+ *
75
+ * The expression's value is a function of that realm, for the adapter alone: called when the
76
+ * execution has ended (its script has settled, either way), it lets `TICKS_AFTER_END` more
77
+ * checks pass and makes every check after those throw, so that what the script left behind
78
+ * settles if it is about to and is stopped if it keeps going, instead of running until the
79
+ * deadline.
64
80
  */
65
81
  export declare function realmTickSource(timeoutMs: number): string;
@@ -0,0 +1,25 @@
1
+ /**
2
+ * No dynamic import in a script, whatever checked it before
3
+ *
4
+ * Every validator preset refuses `import()`. A host can switch validation off, and then the
5
+ * runtime is alone with it: a `vm` script that reaches a dynamic import is answered by Node.js
6
+ * itself, with a promise and an error of the host realm, outside everything the sandbox wraps.
7
+ * A `vm.Script` option does not change that. So the text that is about to be handed to an
8
+ * adapter is looked at once more, by structure, and refused if it holds the construct.
9
+ *
10
+ * The text is only parsed when it contains the word at all, which a script almost never does.
11
+ *
12
+ * @packageDocumentation
13
+ */
14
+ /** The message of the refusal. */
15
+ export declare const DYNAMIC_IMPORT_MESSAGE = "Dynamic import() is not available in the sandbox";
16
+ /**
17
+ * Why `code` may not run, or `undefined` if it holds no dynamic import.
18
+ *
19
+ * - `import(...)` anywhere, called or not, is refused, and so is `import.meta`.
20
+ * - The word as a property name, in a string, in a comment or as part of a longer name is not
21
+ * the construct.
22
+ * - Text that contains the word and cannot be parsed is refused as well: what cannot be read
23
+ * cannot be cleared.
24
+ */
25
+ export declare function refuseDynamicImport(code: string): string | undefined;
@@ -0,0 +1,62 @@
1
+ /**
2
+ * Checks of the options an `Enclave` is created with
3
+ *
4
+ * The options are the host's own, but a host passes on what it was given: a wrapper forwards
5
+ * `{ maxIterations: opts.maxIterations }` whether or not its caller set it, and a server copies a
6
+ * number out of a request. So the constructor holds two things:
7
+ *
8
+ * 1. An option has the documented type and range, or the constructor refuses it with a
9
+ * `TypeError`. The limits end up as numbers in the runtime the sandbox generates for itself;
10
+ * a value that is not a number has no business there, and `count > NaN` is never true.
11
+ * 2. An option whose value is `undefined` is an option that was not set: it has the value of the
12
+ * security level, exactly as if the key were absent.
13
+ *
14
+ * @packageDocumentation
15
+ */
16
+ import type { CreateEnclaveOptions, SecurityLevel } from './types';
17
+ /**
18
+ * The largest timeout: the longest delay a timer holds. `setTimeout` fires after 1 ms for a
19
+ * longer one, which would end a script at once. (`vm` itself would take up to 2^32 - 1, and the
20
+ * sum of a timeout and `doubleVm.parentTimeoutBuffer` stays below that.)
21
+ */
22
+ export declare const MAX_TIMEOUT_MS = 2147483647;
23
+ /** A copy of `value` with the own properties whose value is not `undefined`. */
24
+ export declare function withoutUndefined<T extends object>(value: T): T;
25
+ /**
26
+ * A count or a size: an integer between `min` and `max`.
27
+ *
28
+ * @throws TypeError for anything else, a number that is not finite included
29
+ */
30
+ export declare function assertIntegerOption(name: string, value: unknown, min: number, max?: number): asserts value is number;
31
+ /** @throws TypeError unless `value` is a finite number of at least `min` */
32
+ export declare function assertFiniteNumberOption(name: string, value: unknown, min: number): asserts value is number;
33
+ /** @throws TypeError unless `value` is `true` or `false` */
34
+ export declare function assertBooleanOption(name: string, value: unknown): asserts value is boolean;
35
+ /** @throws TypeError unless `value` is one of the four security levels */
36
+ export declare function assertSecurityLevel(value: unknown): asserts value is SecurityLevel;
37
+ /**
38
+ * Check the options of an `Enclave` and return them without the keys that are `undefined`
39
+ * (nested: `secureProxyConfig`, `toolBridge`, `doubleVm` and its `parentValidation`).
40
+ *
41
+ * Only the scalar options are checked here: the ones that select or bound a control. Handlers,
42
+ * globals, tool namespaces, adapters, `maxGlobalFunctionCalls`, `toolCallGraceMs` and the tool
43
+ * bridge's mode and payload size have their own checks in the constructor.
44
+ *
45
+ * @throws TypeError when an option has a value outside its documented type or range
46
+ */
47
+ export declare function normalizeEnclaveOptions(options: CreateEnclaveOptions): CreateEnclaveOptions;
48
+ /**
49
+ * A number as the text of a numeric literal, for code the runtime generates for itself.
50
+ *
51
+ * The generators call this for every limit they write into a script, whatever checked the value
52
+ * before: a parameter that is not a finite number never becomes program text.
53
+ *
54
+ * @throws TypeError unless `value` is a finite number
55
+ */
56
+ export declare function numericLiteral(name: string, value: unknown): string;
57
+ /**
58
+ * A boolean as the text `true` or `false`, for code the runtime generates for itself.
59
+ *
60
+ * @throws TypeError unless `value` is a boolean
61
+ */
62
+ export declare function booleanLiteral(name: string, value: unknown): string;
package/enclave.d.ts CHANGED
@@ -43,8 +43,12 @@ export declare class Enclave {
43
43
  private readonly config;
44
44
  private readonly securityLevel;
45
45
  private readonly validator;
46
+ /** Layer 0: looks at the text of a script before anything parses it (see `preScan`) */
47
+ private readonly preScanner;
46
48
  private readonly validateCode;
47
49
  private readonly transformCode;
50
+ /** Whether the run-time key guard also refuses the property names the AgentScript validator refuses */
51
+ private readonly guardsReflectionKeys;
48
52
  private readonly referenceConfig?;
49
53
  private readonly scoringGate?;
50
54
  private readonly doubleVmConfig;
@@ -59,7 +63,7 @@ export declare class Enclave {
59
63
  private adapter?;
60
64
  /** The adapter while it is being created: executions that start at once share it */
61
65
  private adapterCreation?;
62
- constructor(options?: CreateEnclaveOptions);
66
+ constructor(rawOptions?: CreateEnclaveOptions);
63
67
  /**
64
68
  * Build double VM configuration from user options
65
69
  *
@@ -94,15 +98,20 @@ export declare class Enclave {
94
98
  */
95
99
  private execute;
96
100
  /**
97
- * Apply memory tracking transforms to code
98
- *
99
- * Transforms concatenation operations to use __safe_concat for memory tracking.
100
- * This is used when memoryLimit is set but no sidecar is configured.
101
+ * Guard the member accesses whose key is only known at run time (see guardComputedMemberKeys):
102
+ * the key is checked against the names this security level refuses before the access happens.
101
103
  *
102
- * @param code The code to transform
103
- * @returns The transformed code
104
+ * @param code The validated, transformed code
105
+ * @returns The code with every computed member key guarded
104
106
  */
105
107
  private applyComputedKeyGuard;
108
+ /**
109
+ * Hand the writes that can change the size of an array to the runtime (see guardArrayWrites).
110
+ *
111
+ * @param code The validated, transformed code
112
+ * @returns The code with those writes rewritten
113
+ */
114
+ private applyArrayWriteGuard;
106
115
  /**
107
116
  * Insert cooperative deadline checks (see ./deadline-guard).
108
117
  *
@@ -110,6 +119,21 @@ export declare class Enclave {
110
119
  * @returns The code with a deadline check at the start of every function and loop body
111
120
  */
112
121
  private applyDeadlineGuard;
122
+ /**
123
+ * Whether the runtime the script will run in defines the array accounting helpers (see
124
+ * ./realm-memory): the built-in VM adapters do, in process and in a worker. A host-supplied
125
+ * adapter gets the code without the calls to them.
126
+ */
127
+ private accountsForArrays;
128
+ /**
129
+ * Apply memory tracking transforms to code
130
+ *
131
+ * Transforms concatenation operations to use __safe_concat for memory tracking.
132
+ * This is used when memoryLimit is set but no sidecar is configured.
133
+ *
134
+ * @param code The code to transform
135
+ * @returns The transformed code
136
+ */
113
137
  private applyMemoryTrackingTransforms;
114
138
  /**
115
139
  * Apply sidecar transforms to code