@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
|
@@ -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
|
-
/**
|
|
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
|
|
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
|
|
64
|
-
*
|
|
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
|
|
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
|
|
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
|
-
*
|
|
164
|
-
* when
|
|
165
|
-
*
|
|
166
|
-
*
|
|
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;
|
package/babel/babel-wrapper.d.ts
CHANGED
|
@@ -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
|
|
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
|
-
*
|
|
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:
|
|
75
|
-
*
|
|
76
|
-
* -
|
|
77
|
-
* -
|
|
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
|
|
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;
|
package/deadline-guard.d.ts
CHANGED
|
@@ -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(
|
|
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
|
-
*
|
|
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
|
|
103
|
-
* @returns The
|
|
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
|