@enclave-vm/core 2.18.0 → 2.19.0
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 +239 -39
- package/SECURITY-AUDIT.md +85 -77
- package/adapters/interpreter-adapter.d.ts +27 -0
- package/adapters/worker-pool/config.d.ts +4 -2
- package/adapters/worker-pool/memory-monitor.d.ts +16 -2
- package/adapters/worker-pool/protocol.d.ts +52 -8
- package/adapters/worker-pool/worker-pool-adapter.d.ts +45 -2
- package/adapters/worker-pool/worker-script.d.ts +14 -4
- package/adapters/worker-pool/worker-slot.d.ts +99 -2
- package/console-handler.d.ts +5 -0
- package/deadline-guard.d.ts +65 -0
- package/double-vm/double-vm-wrapper.d.ts +11 -2
- package/double-vm/parent-vm-bootstrap.d.ts +118 -0
- package/enclave.d.ts +30 -0
- package/esm/index.mjs +12431 -8274
- package/esm/worker.mjs +2935 -212
- package/execution-deadline.d.ts +69 -0
- package/global-function-gate.d.ts +22 -1
- package/globals-validator.d.ts +12 -0
- package/index.d.ts +1 -0
- package/index.js +12503 -8347
- package/interpreter/interpreter.d.ts +149 -5
- package/interpreter/safe-globals.d.ts +14 -0
- package/package.json +4 -4
- package/realm-airlock.d.ts +51 -0
- package/safe-error.d.ts +6 -0
- package/safe-runtime.d.ts +16 -0
- package/sandbox-rejections.d.ts +67 -0
- package/sandbox-script.d.ts +156 -0
- package/secure-proxy.d.ts +21 -0
- package/src/adapters/worker-pool/package.json +4 -4
- package/src/adapters/worker-pool/worker-script.js +8604 -640
- package/stack-reserve.d.ts +46 -0
- package/tool-bridge.d.ts +34 -2
- package/types.d.ts +68 -5
- package/worker.js +2935 -212
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
import { Worker } from 'worker_threads';
|
|
10
10
|
import { EventEmitter } from 'events';
|
|
11
11
|
import type { WorkerSlotStatus, ResourceUsage } from './config';
|
|
12
|
-
import type
|
|
12
|
+
import { type MainToWorkerMessage, type WorkerToMainMessage } from './protocol';
|
|
13
13
|
/**
|
|
14
14
|
* Events emitted by WorkerSlot
|
|
15
15
|
*/
|
|
@@ -24,16 +24,85 @@ export interface WorkerSlotEvents {
|
|
|
24
24
|
ready: [];
|
|
25
25
|
/** State changed */
|
|
26
26
|
stateChange: [WorkerSlotStatus, WorkerSlotStatus];
|
|
27
|
+
/** The host-side heap check ended the running execution (bytes the worker held) */
|
|
28
|
+
heapLimitExceeded: [number];
|
|
27
29
|
}
|
|
28
30
|
/**
|
|
29
31
|
* Worker slot options
|
|
30
32
|
*/
|
|
31
33
|
export interface WorkerSlotOptions {
|
|
32
|
-
/**
|
|
34
|
+
/** Heap limit of the worker in MB (its old generation); 0 for no limit */
|
|
33
35
|
memoryLimitMB: number;
|
|
34
36
|
/** Startup timeout in milliseconds */
|
|
35
37
|
startupTimeoutMs?: number;
|
|
36
38
|
}
|
|
39
|
+
/**
|
|
40
|
+
* The young generation of a worker that has a memory limit, in MB.
|
|
41
|
+
*
|
|
42
|
+
* A worker thread shares the process. When a worker reaches the limit of its old generation,
|
|
43
|
+
* Node.js ends the worker and raises the limit by 16 MB so that the engine can finish what it is
|
|
44
|
+
* doing. One scavenge can move a whole semi-space, a third of the young generation, into the old
|
|
45
|
+
* generation at once. Left to the engine, the young generation of a limited worker is 192 MB on
|
|
46
|
+
* Node.js 24 (48 MB on Node.js 22): a burst of up to 64 MB against an allowance of 16, and when
|
|
47
|
+
* the burst is larger than the allowance the engine ends the PROCESS with a fatal out-of-memory
|
|
48
|
+
* error instead of the worker.
|
|
49
|
+
*
|
|
50
|
+
* Measured on Node.js 24.18 with a script that fills a 64 MB worker, each run a process of its
|
|
51
|
+
* own: with the engine's default, 13 of 480 processes aborted at 12 in parallel, 3 of 380 at 6 to
|
|
52
|
+
* 8 in parallel and 0 of 40 one at a time. With 24 MB (semi-spaces of 8 MB, half the allowance):
|
|
53
|
+
* 0 of 480 at 12 in parallel. 24 is also a value the engine keeps as it is: it rounds a
|
|
54
|
+
* semi-space up to a power of two, so asking for 16 gives 24 and asking for 32 gives 48.
|
|
55
|
+
*
|
|
56
|
+
* This bounds the burst of a scavenge. It does not make the limit a guarantee: one allocation
|
|
57
|
+
* larger than the allowance still ends the process (see "The Worker Heap Limit" in the README).
|
|
58
|
+
*/
|
|
59
|
+
export declare const WORKER_YOUNG_GENERATION_MB = 24;
|
|
60
|
+
/**
|
|
61
|
+
* Who stops a worker that outgrows its memory limit:
|
|
62
|
+
*
|
|
63
|
+
* - `engine`: V8, through the worker's `resourceLimits`. The normal case.
|
|
64
|
+
* - `host`: this thread, by reading the worker's heap while it executes, because the engine does
|
|
65
|
+
* not apply the limit (see {@link isHeapLimitApplied}).
|
|
66
|
+
* - `none`: nobody. No limit is configured, or the engine does not apply it and this Node.js
|
|
67
|
+
* version cannot read a worker's heap from outside.
|
|
68
|
+
*/
|
|
69
|
+
export type HeapLimitEnforcement = 'engine' | 'host' | 'none';
|
|
70
|
+
/**
|
|
71
|
+
* Whether the engine applies the heap limit a worker was created with.
|
|
72
|
+
*
|
|
73
|
+
* `resourceLimits.maxOldGenerationSizeMb` does nothing when the process itself runs with
|
|
74
|
+
* `--max-old-space-size` (on the command line or in `NODE_OPTIONS`): the flag is process-wide,
|
|
75
|
+
* every worker gets its value, and `worker.resourceLimits` goes on reporting what was asked for.
|
|
76
|
+
* What tells the two cases apart is the worker's actual heap size limit: with the limit applied
|
|
77
|
+
* it is the old generation that was asked for plus the young generation.
|
|
78
|
+
*
|
|
79
|
+
* @param heapSizeLimitBytes `heap_size_limit` from the worker's heap statistics
|
|
80
|
+
* @param budgetBytes The limit the worker was created with plus its young generation
|
|
81
|
+
*/
|
|
82
|
+
export declare function isHeapLimitApplied(heapSizeLimitBytes: number, budgetBytes: number): boolean;
|
|
83
|
+
/**
|
|
84
|
+
* Whether the process was started with a V8 old-space flag, as far as its arguments tell. Only
|
|
85
|
+
* consulted where a worker's heap cannot be read (Node.js before 22.16), to say that the limit
|
|
86
|
+
* is not enforced.
|
|
87
|
+
*/
|
|
88
|
+
export declare function hasProcessHeapFlag(execArgv: readonly string[], nodeOptions: string | undefined): boolean;
|
|
89
|
+
/**
|
|
90
|
+
* Find the compiled worker script (worker threads need JavaScript, built by the
|
|
91
|
+
* `build-worker-script` target) from the directory of the module that spawns the worker.
|
|
92
|
+
*
|
|
93
|
+
* That module is in a different place in each form the package runs in:
|
|
94
|
+
*
|
|
95
|
+
* - the CommonJS bundle `dist/index.js`: the script is at `dist/src/adapters/worker-pool/`;
|
|
96
|
+
* - the ES module bundle `dist/esm/index.mjs`: one level up from there;
|
|
97
|
+
* - the TypeScript sources under ts-jest (`src/adapters/worker-pool/`): in the `dist` folder
|
|
98
|
+
* next to `src`;
|
|
99
|
+
* - an unbundled build: next to this module.
|
|
100
|
+
*
|
|
101
|
+
* @param moduleDir Directory of the calling module
|
|
102
|
+
* @param exists File existence check (a test passes its own)
|
|
103
|
+
* @throws Error naming every location tried when the script is in none of them
|
|
104
|
+
*/
|
|
105
|
+
export declare function resolveWorkerScriptPath(moduleDir: string, exists?: (file: string) => boolean): string;
|
|
37
106
|
/**
|
|
38
107
|
* Manages a single worker thread
|
|
39
108
|
*/
|
|
@@ -54,6 +123,12 @@ export declare class WorkerSlot extends EventEmitter {
|
|
|
54
123
|
private _currentExecutionId;
|
|
55
124
|
/** Last memory report */
|
|
56
125
|
private _memoryUsage;
|
|
126
|
+
/** Who enforces this worker's memory limit; decided when the worker has started */
|
|
127
|
+
private _heapLimitEnforcement;
|
|
128
|
+
/** What this worker may hold: its limit plus the young generation, in bytes. 0 without a limit. */
|
|
129
|
+
private _memoryBudgetBytes;
|
|
130
|
+
/** The host-side heap check of the running execution (only with `host` enforcement) */
|
|
131
|
+
private heapWatchdog;
|
|
57
132
|
/** Configuration */
|
|
58
133
|
private readonly options;
|
|
59
134
|
/** Message handler bound to this instance */
|
|
@@ -69,6 +144,8 @@ export declare class WorkerSlot extends EventEmitter {
|
|
|
69
144
|
get lastActiveAt(): number;
|
|
70
145
|
get currentExecutionId(): string | null;
|
|
71
146
|
get memoryUsage(): ResourceUsage | null;
|
|
147
|
+
get heapLimitEnforcement(): HeapLimitEnforcement;
|
|
148
|
+
get memoryBudgetBytes(): number;
|
|
72
149
|
get isIdle(): boolean;
|
|
73
150
|
get isExecuting(): boolean;
|
|
74
151
|
get isTerminated(): boolean;
|
|
@@ -76,6 +153,26 @@ export declare class WorkerSlot extends EventEmitter {
|
|
|
76
153
|
* Spawn the worker thread
|
|
77
154
|
*/
|
|
78
155
|
spawn(): Promise<void>;
|
|
156
|
+
/**
|
|
157
|
+
* Work out what this worker may hold and who stops it when it holds more (see
|
|
158
|
+
* {@link HeapLimitEnforcement}). Asking for a limit is not enough to have one: a process-wide
|
|
159
|
+
* heap flag silently replaces it, so the worker's actual limit is read back.
|
|
160
|
+
*/
|
|
161
|
+
private resolveHeapLimitEnforcement;
|
|
162
|
+
/**
|
|
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).
|
|
167
|
+
*/
|
|
168
|
+
private startHeapWatchdog;
|
|
169
|
+
private stopHeapWatchdog;
|
|
170
|
+
/**
|
|
171
|
+
* End the execution that is running in this worker with `error`, and the worker with it. The
|
|
172
|
+
* waiting execution is told first: a worker that is being terminated reports nothing itself,
|
|
173
|
+
* and the execution would wait for its timeout.
|
|
174
|
+
*/
|
|
175
|
+
failExecution(error: Error): void;
|
|
79
176
|
/**
|
|
80
177
|
* Get the path to the worker script
|
|
81
178
|
*/
|
package/console-handler.d.ts
CHANGED
|
@@ -8,6 +8,11 @@ export type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
|
|
|
8
8
|
/**
|
|
9
9
|
* Receives each console call of a script as its level and formatted line. Its return value is
|
|
10
10
|
* ignored and anything it throws or rejects with is swallowed.
|
|
11
|
+
*
|
|
12
|
+
* It is not called for a console call a script makes with the stack nearly full (less than
|
|
13
|
+
* HOST_STACK_RESERVE_BYTES left, see ./stack-reserve): that line is dropped. A handler that
|
|
14
|
+
* started there would be cut off wherever the stack ends, which for one that writes to
|
|
15
|
+
* `process.stdout` leaves the stream unusable for the rest of the process.
|
|
11
16
|
*/
|
|
12
17
|
export type ConsoleHandler = (level: ConsoleLevel, message: string) => void;
|
|
13
18
|
export interface ConsoleLimits {
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Deadline Guard Transform (cooperative timeout)
|
|
3
|
+
*
|
|
4
|
+
* `vm`'s `timeout` only bounds the synchronous run of the script evaluation that it was passed to.
|
|
5
|
+
* A script is an async function: everything after its first `await` runs as a promise job on the
|
|
6
|
+
* host's event loop, outside that watchdog. The enclave's own timer cannot stop it either, because a
|
|
7
|
+
* timer only fires between jobs, and a script that never yields never lets one fire. So
|
|
8
|
+
* `await 0; <busy work>` used to run for as long as it liked, on the host's only thread.
|
|
9
|
+
*
|
|
10
|
+
* This transform makes the script check the clock itself. It inserts a call to `__ag_tick()`:
|
|
11
|
+
* - at the start of every function body (arrow functions with an expression body get a block body),
|
|
12
|
+
* which bounds recursion and every callback a built-in drives (`map`, `sort`, a Proxy trap, a
|
|
13
|
+
* `toString` called by a coercion, ...);
|
|
14
|
+
* - at the start of every loop body.
|
|
15
|
+
*
|
|
16
|
+
* `__ag_tick` is the sandbox realm's `__safe_tick`, captured once at program scope. The adapter
|
|
17
|
+
* defines it; it samples the realm's clock and throws once the execution's deadline has passed, and
|
|
18
|
+
* from then on throws on every call, so a script that catches the error still cannot run another
|
|
19
|
+
* loop iteration or enter another function. An adapter that does not define `__safe_tick` gets a
|
|
20
|
+
* no-op, so the transformed code runs unchanged there.
|
|
21
|
+
*
|
|
22
|
+
* Applied AFTER validation, like the computed-key guard, so the static rules see the script as
|
|
23
|
+
* written and never the injected helper. The `__ag_` prefix is reserved: a script cannot declare,
|
|
24
|
+
* shadow or assign `__ag_tick`.
|
|
25
|
+
*
|
|
26
|
+
* What this does not bound: a single built-in call that does all its work natively (the memory
|
|
27
|
+
* limits bound those), and a script run with `transform: false`.
|
|
28
|
+
*
|
|
29
|
+
* @packageDocumentation
|
|
30
|
+
*/
|
|
31
|
+
import type * as acorn from 'acorn';
|
|
32
|
+
/** Name of the injected local that holds the realm's tick function. */
|
|
33
|
+
export declare const TICK_FN = "__ag_tick";
|
|
34
|
+
/** Name of the tick function an adapter defines in the sandbox realm. */
|
|
35
|
+
export declare const REALM_TICK_FN = "__safe_tick";
|
|
36
|
+
/**
|
|
37
|
+
* How many ticks pass between two readings of the clock. A reading costs far more than the counter
|
|
38
|
+
* increment, and a tick is at most one loop iteration or function entry apart from the next.
|
|
39
|
+
*/
|
|
40
|
+
export declare const TICKS_PER_CLOCK_CHECK = 256;
|
|
41
|
+
/** Result of the deadline-guard transform. */
|
|
42
|
+
export interface DeadlineGuardResult {
|
|
43
|
+
/** Number of function and loop bodies that received a deadline check. */
|
|
44
|
+
guardedCount: number;
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Insert a deadline check at the start of every function and loop body, and the helper it calls at
|
|
48
|
+
* the top of the program.
|
|
49
|
+
*
|
|
50
|
+
* Mutates the AST in place. Must be given a Program node.
|
|
51
|
+
*
|
|
52
|
+
* @param ast Program AST to transform
|
|
53
|
+
* @param parse Acorn parse function, used to build the injected helper statement
|
|
54
|
+
* @returns Number of bodies guarded
|
|
55
|
+
*/
|
|
56
|
+
export declare function injectDeadlineChecks(ast: acorn.Node, parse: (source: string) => acorn.Node): DeadlineGuardResult;
|
|
57
|
+
/**
|
|
58
|
+
* Source of an expression that, evaluated in a sandbox realm BEFORE any script code, defines the
|
|
59
|
+
* realm's `__safe_tick` for an execution that may run for `timeoutMs`.
|
|
60
|
+
*
|
|
61
|
+
* It captures the realm's own `Date.now` (so nothing the script does to `Date` afterwards matters)
|
|
62
|
+
* and installs `__safe_tick` as a read-only global. What it throws is a string: an inert value in a
|
|
63
|
+
* script's `catch`, and the adapters already report a thrown string as the error message.
|
|
64
|
+
*/
|
|
65
|
+
export declare function realmTickSource(timeoutMs: number): string;
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
* @packageDocumentation
|
|
9
9
|
*/
|
|
10
10
|
import type { SandboxAdapter, ExecutionContext, ExecutionResult, SecurityLevel } from '../types';
|
|
11
|
-
import type { DoubleVmConfig } from './types';
|
|
11
|
+
import type { DoubleVmConfig, SerializableSuspiciousPattern } from './types';
|
|
12
12
|
/**
|
|
13
13
|
* Double VM Wrapper
|
|
14
14
|
*
|
|
@@ -19,8 +19,17 @@ import type { DoubleVmConfig } from './types';
|
|
|
19
19
|
export declare class DoubleVmWrapper implements SandboxAdapter {
|
|
20
20
|
private readonly config;
|
|
21
21
|
private readonly securityLevel;
|
|
22
|
+
private readonly serializedCustomPatterns?;
|
|
22
23
|
private parentContext?;
|
|
23
|
-
|
|
24
|
+
/**
|
|
25
|
+
* @param config Double VM configuration
|
|
26
|
+
* @param securityLevel Security level of the enclave
|
|
27
|
+
* @param serializedCustomPatterns The custom suspicious patterns of `config`, already
|
|
28
|
+
* serialized. A worker receives them in this form (a detector is a function, and functions
|
|
29
|
+
* do not cross a thread boundary); when given, `config.parentValidation.suspiciousPatterns`
|
|
30
|
+
* is not read.
|
|
31
|
+
*/
|
|
32
|
+
constructor(config: DoubleVmConfig, securityLevel: SecurityLevel, serializedCustomPatterns?: readonly SerializableSuspiciousPattern[] | undefined);
|
|
24
33
|
/**
|
|
25
34
|
* Execute code in the double VM structure
|
|
26
35
|
*/
|
|
@@ -61,11 +61,129 @@ export interface ParentVmBootstrapOptions {
|
|
|
61
61
|
maxGlobalFunctionCalls?: number;
|
|
62
62
|
/** Validated tool namespaces to bind in the inner VM */
|
|
63
63
|
toolNamespaces?: readonly NormalizedToolNamespace[];
|
|
64
|
+
/**
|
|
65
|
+
* The global names the inner realm may hold (`realmGlobals: 'allowlist'`). When set, every
|
|
66
|
+
* other global is removed from the inner realm before the script runs, the safe standard
|
|
67
|
+
* globals that are not on the list are not defined, and regular expressions cannot be executed
|
|
68
|
+
* there. Absent: only the security level's dangerous globals are removed.
|
|
69
|
+
*/
|
|
70
|
+
realmGlobalAllowlist?: readonly string[];
|
|
64
71
|
}
|
|
72
|
+
/**
|
|
73
|
+
* How many arguments the stack reserve pushes (see INNER_REALM_GUARD_SOURCE): 8 bytes each, so
|
|
74
|
+
* 64 KB.
|
|
75
|
+
*
|
|
76
|
+
* The size follows from one measured fact: V8 refuses to compile a function for its first call
|
|
77
|
+
* when less than about 40 KB of stack is left (39.9 KB with Node.js 24, 46.4 KB with Node.js 22).
|
|
78
|
+
* Below that, any function of the runtime that has not run yet in this process throws a
|
|
79
|
+
* RangeError at its call site, in the middle of whatever was calling it. With half this reserve
|
|
80
|
+
* (the first version) a host function passed in globals could run and then fail to hand its
|
|
81
|
+
* result back. 64 KB is that zone plus room for the frames between the script and the deepest
|
|
82
|
+
* call of the runtime's own code (measured: under 10 KB). Code the application supplied gets a
|
|
83
|
+
* larger reserve of its own, where it starts: see ../stack-reserve.
|
|
84
|
+
*
|
|
85
|
+
* The check costs about 2.7 microseconds (the engine pushes every argument).
|
|
86
|
+
*/
|
|
87
|
+
export declare const STACK_RESERVE_ARGUMENTS = 8192;
|
|
88
|
+
/**
|
|
89
|
+
* Source of an expression evaluated in a pristine sandbox realm (the inner realm of the double
|
|
90
|
+
* VM, the one realm of the single VM). Its value is that realm's half of the membrane:
|
|
91
|
+
* `makeProxy(target, parentHandler)`, `wrap(fn, needsReserve)`, `own(value)` (what a script may
|
|
92
|
+
* be handed in place of a thrown value or a rejection reason) and `shell(kind)`.
|
|
93
|
+
*
|
|
94
|
+
* Why the membrane needs a half in the script's realm: an error is created in the realm of the
|
|
95
|
+
* function that is running when it is raised, and a stack overflow is raised at the ENTRY of the
|
|
96
|
+
* function that no longer fits. A script that recurses until the stack is full and then touches a
|
|
97
|
+
* membrane proxy overflows at the entry of the trap, before any catch of the trap exists: the
|
|
98
|
+
* RangeError it catches is a raw object of the trap's realm, never laundered. With a host function
|
|
99
|
+
* called directly from inner-realm code (the memory accounting hook was one) it is a HOST error,
|
|
100
|
+
* and its constructor chain reaches the one Function constructor that can generate code.
|
|
101
|
+
*
|
|
102
|
+
* So the first frame a script enters is always a function of its own realm:
|
|
103
|
+
*
|
|
104
|
+
* - a Proxy handler is an inner-realm object whose traps call the parent realm's traps inside a
|
|
105
|
+
* try block;
|
|
106
|
+
* - every parent or host function that inner-realm code holds directly is wrapped the same way.
|
|
107
|
+
*
|
|
108
|
+
* Whatever comes out of that try block is passed on only if a script may have it: a primitive,
|
|
109
|
+
* an object without a prototype (the runtime's inert errors), or an object of this realm.
|
|
110
|
+
* Anything else is replaced by an error of this realm with the same name and message. The catch
|
|
111
|
+
* runs in this realm as well, so if IT overflows, that error is this realm's too.
|
|
112
|
+
*
|
|
113
|
+
* The stack reserve: a call (and a construct) first checks that some stack is left, by calling a
|
|
114
|
+
* function with STACK_RESERVE_ARGUMENTS arguments, which the engine has to push. With less room
|
|
115
|
+
* than that the script gets a RangeError of its own realm before anything of the runtime has
|
|
116
|
+
* started. The runtime's code therefore never begins at a nearly full stack, where a failure
|
|
117
|
+
* halfway through is not something it is written for. Reading a property (the get trap and the
|
|
118
|
+
* other traps) is not checked: it happens far too often for a check of this price.
|
|
119
|
+
*/
|
|
120
|
+
export declare const INNER_REALM_GUARD_SOURCE: string;
|
|
121
|
+
/**
|
|
122
|
+
* Source of a statement evaluated in the inner realm: `Symbol.for` refuses keys in the
|
|
123
|
+
* `nodejs.` namespace.
|
|
124
|
+
*
|
|
125
|
+
* The symbol registry is the isolate's, shared with the host, and Node.js looks up some of its
|
|
126
|
+
* own protocols there. `util.inspect` calls the method an object has under
|
|
127
|
+
* `Symbol.for('nodejs.util.inspect.custom')` and passes it the host's own `inspect` function;
|
|
128
|
+
* anything of the host that formats a value of a script (a log line, the printer for an uncaught
|
|
129
|
+
* error) would hand that function to the script. No intrinsic of a fresh realm carries such a
|
|
130
|
+
* key, so a script that cannot ask the registry for one cannot define the method.
|
|
131
|
+
*/
|
|
132
|
+
export declare const INNER_REALM_SYMBOL_REGISTRY_SOURCE: string;
|
|
133
|
+
/**
|
|
134
|
+
* Source of an expression that, evaluated in a pristine realm, yields a function freezing that
|
|
135
|
+
* realm's intrinsics: every constructor, prototype and namespace object the global object names
|
|
136
|
+
* (including the constructors inside namespaces such as `Intl` and `WebAssembly`), and the ones
|
|
137
|
+
* only syntax reaches (generator, async and iterator prototypes, the typed array base). Used for
|
|
138
|
+
* the PARENT realm, right before the script runs.
|
|
139
|
+
*
|
|
140
|
+
* Why: the parent realm's trusted code (the membrane, the tool gate) calls `Object.keys`,
|
|
141
|
+
* `JSON.stringify`, `Array.isArray`, `Reflect.apply`, ... on every operation. A value of the parent
|
|
142
|
+
* realm that reached the script unwrapped used to be enough to replace one of those with a function
|
|
143
|
+
* of the script's, which the trusted code then called with raw objects. A handful of them were
|
|
144
|
+
* pinned after such a report; freezing the objects that hold them covers the ones nobody listed.
|
|
145
|
+
* A method is replaced by writing to the object that holds it, so the method functions themselves
|
|
146
|
+
* are left alone: that keeps this to about two hundred objects per execution.
|
|
147
|
+
*
|
|
148
|
+
* The objects are collected when the expression is evaluated. Only objects of the realm itself
|
|
149
|
+
* are taken from the global object: a value another realm put there (a host bridge) has a
|
|
150
|
+
* prototype chain that never reaches this realm's `Object.prototype`. The global object itself is
|
|
151
|
+
* not frozen. Accessors are never invoked: properties are read as descriptors.
|
|
152
|
+
*
|
|
153
|
+
* It is NOT used for the inner realm: the membrane hands out the methods of the inner realm's safe
|
|
154
|
+
* globals (`Math.max`, `JSON.parse`, ...) as wrapped forwarders, and a Proxy must report the exact
|
|
155
|
+
* value of a frozen target's property, so freezing those objects would unwrap them.
|
|
156
|
+
*/
|
|
157
|
+
export declare const REALM_LOCKDOWN_SOURCE: string;
|
|
65
158
|
/**
|
|
66
159
|
* Generate the parent VM bootstrap script
|
|
67
160
|
*
|
|
68
161
|
* This returns JavaScript code as a string that will be executed
|
|
69
162
|
* inside the parent VM context.
|
|
70
163
|
*/
|
|
164
|
+
/**
|
|
165
|
+
* `value` as a JavaScript string literal made of ASCII characters only.
|
|
166
|
+
*
|
|
167
|
+
* The bootstrap is ASCII, so the engine stores its source with one byte per character. A single
|
|
168
|
+
* character outside Latin-1 anywhere in the text doubles that, and the engine keeps the source of
|
|
169
|
+
* every script it compiled until several major garbage collections have passed. The script to run
|
|
170
|
+
* is the one part of the bootstrap that can contain any character.
|
|
171
|
+
*/
|
|
172
|
+
export declare function asciiStringLiteral(value: string): string;
|
|
173
|
+
/**
|
|
174
|
+
* Source of the statements that define `__safe_concat` and `__safe_template` inside a sandbox
|
|
175
|
+
* realm (the inner realm of the double VM, the one realm of the single VM): the `+` operator
|
|
176
|
+
* and template literals of a transformed script, with memory accounting and reference handling.
|
|
177
|
+
*
|
|
178
|
+
* They are functions OF the realm on purpose. As host or parent-realm functions they would be
|
|
179
|
+
* raw objects of another realm in the script's hands, and a stack overflow inside one would
|
|
180
|
+
* span realms (see INNER_REALM_GUARD_SOURCE). The realm must still have its `Proxy`, `Reflect`
|
|
181
|
+
* and `globalThis` when this runs, and `__host_memory_track__` if memory is accounted for.
|
|
182
|
+
*/
|
|
183
|
+
export declare function innerRealmRuntimeSource(params: {
|
|
184
|
+
stackTraceHardeningCode: string;
|
|
185
|
+
allowComposites: boolean;
|
|
186
|
+
memoryLimit: number;
|
|
187
|
+
blockedProperties: readonly string[];
|
|
188
|
+
}): string;
|
|
71
189
|
export declare function generateParentVmBootstrap(options: ParentVmBootstrapOptions): string;
|
package/enclave.d.ts
CHANGED
|
@@ -52,7 +52,13 @@ export declare class Enclave {
|
|
|
52
52
|
private readonly toolNamespaces;
|
|
53
53
|
private readonly sandboxAdapter?;
|
|
54
54
|
private readonly consoleHandler?;
|
|
55
|
+
/** How long after the deadline a host call still in flight may take to deliver (see ./execution-deadline) */
|
|
56
|
+
private readonly toolCallGraceMs;
|
|
57
|
+
/** Global names the script's realm may hold (`realmGlobals: 'allowlist'`); absent otherwise. */
|
|
58
|
+
private readonly realmGlobalAllowlist?;
|
|
55
59
|
private adapter?;
|
|
60
|
+
/** The adapter while it is being created: executions that start at once share it */
|
|
61
|
+
private adapterCreation?;
|
|
56
62
|
constructor(options?: CreateEnclaveOptions);
|
|
57
63
|
/**
|
|
58
64
|
* Build double VM configuration from user options
|
|
@@ -97,6 +103,13 @@ export declare class Enclave {
|
|
|
97
103
|
* @returns The transformed code
|
|
98
104
|
*/
|
|
99
105
|
private applyComputedKeyGuard;
|
|
106
|
+
/**
|
|
107
|
+
* Insert cooperative deadline checks (see ./deadline-guard).
|
|
108
|
+
*
|
|
109
|
+
* @param code The validated, transformed code
|
|
110
|
+
* @returns The code with a deadline check at the start of every function and loop body
|
|
111
|
+
*/
|
|
112
|
+
private applyDeadlineGuard;
|
|
100
113
|
private applyMemoryTrackingTransforms;
|
|
101
114
|
/**
|
|
102
115
|
* Apply sidecar transforms to code
|
|
@@ -120,6 +133,11 @@ export declare class Enclave {
|
|
|
120
133
|
* - Defense-in-depth against VM escape attacks
|
|
121
134
|
*/
|
|
122
135
|
private getAdapter;
|
|
136
|
+
/**
|
|
137
|
+
* Create the sandbox adapter this enclave is configured for (see {@link getAdapter}, which
|
|
138
|
+
* keeps it)
|
|
139
|
+
*/
|
|
140
|
+
private createAdapter;
|
|
123
141
|
/**
|
|
124
142
|
* Get the current security level
|
|
125
143
|
*
|
|
@@ -142,7 +160,19 @@ export declare class Enclave {
|
|
|
142
160
|
maxSanitizeDepth: number;
|
|
143
161
|
maxSanitizeProperties: number;
|
|
144
162
|
memoryLimit: number;
|
|
163
|
+
realmGlobals: 'allowlist' | 'security-level';
|
|
145
164
|
};
|
|
165
|
+
/**
|
|
166
|
+
* The global names a script of this enclave may use: the AgentScript globals of the security
|
|
167
|
+
* level, the enclave's runtime helpers, `console` when it is available, and the custom globals
|
|
168
|
+
* and tool namespaces (each under its own name and its `__safe_` name).
|
|
169
|
+
*
|
|
170
|
+
* One list serves two purposes: the validator refuses every other free identifier, and with
|
|
171
|
+
* `realmGlobals: 'allowlist'` the sandbox removes every other global from the script's realm.
|
|
172
|
+
*
|
|
173
|
+
* @param customAllowedGlobals Names of custom globals and tool namespaces, with their `__safe_` forms
|
|
174
|
+
*/
|
|
175
|
+
private buildAllowedGlobals;
|
|
146
176
|
/**
|
|
147
177
|
* Create a validator based on the selected preset
|
|
148
178
|
*
|