@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.
@@ -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 { MainToWorkerMessage, WorkerToMainMessage } from './protocol';
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
- /** Memory limit in MB for --max-old-space-size */
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
  */
@@ -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
- constructor(config: DoubleVmConfig, securityLevel: SecurityLevel);
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
  *