@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
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a thrown value says about itself, as text of the host
|
|
3
|
+
*
|
|
4
|
+
* A script can throw anything: an object whose `message` is another object, a function, a Proxy,
|
|
5
|
+
* `null`. Whatever it is, the caller of `run()` gets `result.error` with `name`, `message` and
|
|
6
|
+
* `stack` as the strings they are declared to be, of bounded length: an application logs them,
|
|
7
|
+
* concatenates them and serializes the result, and none of that may run code of the script or
|
|
8
|
+
* depend on the size of what was thrown.
|
|
9
|
+
*
|
|
10
|
+
* A member of the thrown value is read once and used only if it is a string. Nothing is called
|
|
11
|
+
* on the value and nothing is converted: an object in the place of a string is not asked for its
|
|
12
|
+
* text, it is left out.
|
|
13
|
+
*
|
|
14
|
+
* @packageDocumentation
|
|
15
|
+
*/
|
|
16
|
+
/** The longest `name` reported for a thrown value. */
|
|
17
|
+
export declare const MAX_THROWN_NAME_LENGTH = 256;
|
|
18
|
+
/** The longest `message` reported for a thrown value. */
|
|
19
|
+
export declare const MAX_THROWN_MESSAGE_LENGTH: number;
|
|
20
|
+
/** The longest `stack` taken from a thrown value (the stack-trace policy cuts further). */
|
|
21
|
+
export declare const MAX_THROWN_STACK_LENGTH: number;
|
|
22
|
+
/** What {@link describeThrown} could read. A member that was not a string is absent. */
|
|
23
|
+
export interface ThrownDescription {
|
|
24
|
+
name?: string;
|
|
25
|
+
message?: string;
|
|
26
|
+
stack?: string;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* The name, message and stack of a thrown value, each only if the value holds it as a string.
|
|
30
|
+
*
|
|
31
|
+
* - A thrown string is the message.
|
|
32
|
+
* - `null`, `undefined` and the other primitives are named in the message.
|
|
33
|
+
* - An object or function is asked for `name`, `message` and `stack`; what is not a string there
|
|
34
|
+
* is absent from the result, and the caller puts its own default in its place.
|
|
35
|
+
*/
|
|
36
|
+
export declare function describeThrown(thrown: unknown): ThrownDescription;
|
|
37
|
+
/**
|
|
38
|
+
* Whether a thrown value carries the code of the memory-limit error (read once, nothing called).
|
|
39
|
+
* That alone does not make it one: the caller also asks its memory tracker.
|
|
40
|
+
*/
|
|
41
|
+
export declare function isMemoryLimitPayload(thrown: unknown): boolean;
|
|
42
|
+
/** The message for a thrown object or function that has no message of its own. */
|
|
43
|
+
export declare const THROWN_WITHOUT_MESSAGE = "The script threw a value that is not an error";
|
|
44
|
+
/**
|
|
45
|
+
* `result.error` as plain text, whoever built it: `name` and `message` are strings of bounded
|
|
46
|
+
* length, `stack` and `code` are strings or absent. An adapter that is not one of the built-in
|
|
47
|
+
* ones (`sandboxAdapter`) hands back what it likes; this is applied to every result.
|
|
48
|
+
*/
|
|
49
|
+
export declare function normalizeErrorText<T extends {
|
|
50
|
+
name?: unknown;
|
|
51
|
+
message?: unknown;
|
|
52
|
+
stack?: unknown;
|
|
53
|
+
code?: unknown;
|
|
54
|
+
}>(error: T): T & {
|
|
55
|
+
name: string;
|
|
56
|
+
message: string;
|
|
57
|
+
stack?: string;
|
|
58
|
+
code?: string;
|
|
59
|
+
};
|
package/types.d.ts
CHANGED
|
@@ -125,17 +125,18 @@ export interface SecurityLevelConfig {
|
|
|
125
125
|
*/
|
|
126
126
|
sanitizeStackTraces: boolean;
|
|
127
127
|
/**
|
|
128
|
-
*
|
|
129
|
-
*
|
|
128
|
+
* Descriptive only: nothing in the runtime reads this value, and setting it changes nothing.
|
|
129
|
+
* What a script can reach of `Date` and timing APIs follows from the realm's globals.
|
|
130
130
|
*/
|
|
131
131
|
blockTimingAPIs: boolean;
|
|
132
132
|
/**
|
|
133
|
-
*
|
|
134
|
-
*
|
|
133
|
+
* Descriptive only: nothing in the runtime reads this value, and setting it changes nothing.
|
|
134
|
+
* Which loops a script may use is decided by the AST preset (`preset`).
|
|
135
135
|
*/
|
|
136
136
|
allowUnboundedLoops: boolean;
|
|
137
137
|
/**
|
|
138
|
-
*
|
|
138
|
+
* Descriptive only: nothing in the runtime reads this value, and setting it changes nothing.
|
|
139
|
+
* The Unicode checks are those of the pre-scanner preset the validation runs with.
|
|
139
140
|
*/
|
|
140
141
|
unicodeSecurityCheck: boolean;
|
|
141
142
|
/**
|
|
@@ -227,7 +228,9 @@ export interface ExecutionStats {
|
|
|
227
228
|
* tracked during execution. Tracking monitors String and Array allocations.
|
|
228
229
|
*
|
|
229
230
|
* Note: This is an estimate based on allocation tracking, not actual V8 heap usage.
|
|
230
|
-
*
|
|
231
|
+
* Where the engine's own bound is needed, use the `worker_threads` adapter: each worker has a
|
|
232
|
+
* heap limit of the engine (`workerPoolConfig.memoryLimitPerWorker`). Do not set the process
|
|
233
|
+
* flag `--max-old-space-size` for that: it replaces the limits of the workers.
|
|
231
234
|
*/
|
|
232
235
|
memoryUsage?: number;
|
|
233
236
|
/**
|
|
@@ -296,10 +299,11 @@ export interface EnclaveConfig {
|
|
|
296
299
|
* When set, the VM adapter tracks String and Array allocations and throws
|
|
297
300
|
* a MemoryLimitError if the limit is exceeded. Tracking adds ~5-10% overhead.
|
|
298
301
|
*
|
|
299
|
-
* Note: This is enforced via allocation tracking, not V8 heap limits.
|
|
300
|
-
*
|
|
302
|
+
* Note: This is enforced via allocation tracking, not V8 heap limits. It counts the
|
|
303
|
+
* operations that make text and arrays grow; a copy is not charged, and objects, Maps and
|
|
304
|
+
* Sets are not counted. For the engine's own limit, use the worker_threads adapter.
|
|
301
305
|
*
|
|
302
|
-
* Default:
|
|
306
|
+
* Default: 1 * 1024 * 1024 (1 MB); 0 switches the tracking off
|
|
303
307
|
*/
|
|
304
308
|
memoryLimit?: number;
|
|
305
309
|
/**
|
|
@@ -470,7 +474,7 @@ import type { ReferenceConfig } from './sidecar/reference-config';
|
|
|
470
474
|
import type { ScoringGateConfig, ScoringGateResult } from './scoring/types';
|
|
471
475
|
import type { WorkerPoolConfig } from './adapters/worker-pool/config';
|
|
472
476
|
import type { DoubleVmConfig, PartialDoubleVmConfig, ParentValidationConfig } from './double-vm/types';
|
|
473
|
-
import type { NormalizedToolNamespace, ToolNamespaces } from '@enclave-vm/ast';
|
|
477
|
+
import type { NormalizedToolNamespace, PartialPreScannerConfig, PreScannerPresetLevel, ToolNamespaces } from '@enclave-vm/ast';
|
|
474
478
|
import type { ConsoleHandler, ConsoleLevel } from './console-handler';
|
|
475
479
|
import type { HostActivity } from './execution-deadline';
|
|
476
480
|
/**
|
|
@@ -599,6 +603,12 @@ export interface ReferenceSidecarOptions {
|
|
|
599
603
|
* @default Determined by securityLevel
|
|
600
604
|
*/
|
|
601
605
|
maxResolvedSize?: number;
|
|
606
|
+
/**
|
|
607
|
+
* Maximum size, in bytes, of everything one execution resolves for its tool calls in total.
|
|
608
|
+
* A stored value counts once, a concatenation of references every time it is built.
|
|
609
|
+
* @default Twice `maxTotalSize`
|
|
610
|
+
*/
|
|
611
|
+
maxTotalResolvedSize?: number;
|
|
602
612
|
/**
|
|
603
613
|
* Whether to allow composite handles from string concatenation
|
|
604
614
|
* If false, concatenating references throws an error
|
|
@@ -667,6 +677,49 @@ export interface CreateEnclaveOptions extends EnclaveConfig {
|
|
|
667
677
|
* ```
|
|
668
678
|
*/
|
|
669
679
|
preset?: AstPreset;
|
|
680
|
+
/**
|
|
681
|
+
* The pre-scanner (layer 0): what is checked in the text of a script before anything parses
|
|
682
|
+
* it. Its size, the length and number of its lines, how deep it nests, its regular-expression
|
|
683
|
+
* and string literals, and Unicode that hides code.
|
|
684
|
+
*
|
|
685
|
+
* By default it runs with the pre-scanner preset named like the AST preset (`preset`):
|
|
686
|
+
* `agentscript`, `strict`, `secure`, `standard` or `permissive`. The `babel` preset runs with
|
|
687
|
+
* `standard`. The `agentscript` pre-scanner takes scripts of up to 100 KB in at most 1,000
|
|
688
|
+
* lines of at most 2,000 characters, string literals of up to 10 KB each, no
|
|
689
|
+
* regular-expression literal, and no bidirectional or invisible control character.
|
|
690
|
+
*
|
|
691
|
+
* - `preset` picks another pre-scanner preset.
|
|
692
|
+
* - `config` changes single limits of the preset in force (see `PreScannerConfig` of
|
|
693
|
+
* `@enclave-vm/ast`); the pre-scanner's own absolute maximums still hold.
|
|
694
|
+
*
|
|
695
|
+
* A host that stores large string literals in the reference sidecar, or that runs scripts
|
|
696
|
+
* above these sizes, sets the limits it needs here. With `validate: false` the pre-scanner
|
|
697
|
+
* does not run; the maximum size of a script (5,242,880 characters) holds in any case.
|
|
698
|
+
*
|
|
699
|
+
* @example
|
|
700
|
+
* ```typescript
|
|
701
|
+
* // The limits enclaves had before 2.19.2, whatever the AST preset
|
|
702
|
+
* const enclave = new Enclave({ preScan: { preset: 'standard' } });
|
|
703
|
+
*
|
|
704
|
+
* // The agentscript pre-scanner with room for larger string literals. The limit on one
|
|
705
|
+
* // literal and the limit on all literals together are separate: raise both. (A line is at
|
|
706
|
+
* // most 100,000 characters under any configuration.)
|
|
707
|
+
* const enclave = new Enclave({
|
|
708
|
+
* preScan: {
|
|
709
|
+
* config: {
|
|
710
|
+
* maxInputSize: 1024 * 1024,
|
|
711
|
+
* maxLineLength: 100000,
|
|
712
|
+
* maxStringLength: 512 * 1024,
|
|
713
|
+
* maxTotalStringContent: 1024 * 1024,
|
|
714
|
+
* },
|
|
715
|
+
* },
|
|
716
|
+
* });
|
|
717
|
+
* ```
|
|
718
|
+
*/
|
|
719
|
+
preScan?: {
|
|
720
|
+
preset?: PreScannerPresetLevel;
|
|
721
|
+
config?: PartialPreScannerConfig;
|
|
722
|
+
};
|
|
670
723
|
/**
|
|
671
724
|
* Whether to validate AgentScript code before execution
|
|
672
725
|
* Default: true
|
|
@@ -787,7 +840,7 @@ export interface CreateEnclaveOptions extends EnclaveConfig {
|
|
|
787
840
|
*
|
|
788
841
|
* Supported by the double VM (default), the `vm` adapter and the `worker_threads` adapter. A
|
|
789
842
|
* `sandboxAdapter` receives the handler as `ExecutionContext.consoleHandler`; the built-in
|
|
790
|
-
* `InterpreterAdapter`
|
|
843
|
+
* `InterpreterAdapter` gives the script a `console` when a handler is set, and none without one.
|
|
791
844
|
*
|
|
792
845
|
* @example
|
|
793
846
|
* ```typescript
|
|
@@ -825,10 +878,12 @@ export interface CreateEnclaveOptions extends EnclaveConfig {
|
|
|
825
878
|
* - Extracts large strings from code and stores them in a sidecar
|
|
826
879
|
* - Transforms concatenation to detect reference IDs
|
|
827
880
|
* - Resolves references at the callTool boundary
|
|
828
|
-
* -
|
|
881
|
+
* - Stores a tool result that is one large string in the sidecar and hands the script its
|
|
882
|
+
* reference (a string inside an object or an array is not stored)
|
|
829
883
|
*
|
|
830
|
-
*
|
|
831
|
-
* without
|
|
884
|
+
* A script can pass such data (videos, PDFs, images) from one tool to another, and concatenate
|
|
885
|
+
* references where the level allows it, without the data entering the JavaScript sandbox. It
|
|
886
|
+
* cannot read or change the data: nothing is resolved for the script itself.
|
|
832
887
|
*
|
|
833
888
|
* @example
|
|
834
889
|
* ```typescript
|
|
@@ -845,11 +900,11 @@ export interface CreateEnclaveOptions extends EnclaveConfig {
|
|
|
845
900
|
/**
|
|
846
901
|
* AI Scoring Gate configuration
|
|
847
902
|
*
|
|
848
|
-
*
|
|
849
|
-
*
|
|
903
|
+
* A heuristic that scores what a script's tool calls look like, as a signal on top of the
|
|
904
|
+
* AST validation, not a boundary:
|
|
850
905
|
* - Data exfiltration patterns (list→send)
|
|
851
906
|
* - Excessive access (high limits, wildcards)
|
|
852
|
-
* - Fan-out
|
|
907
|
+
* - Fan-out (tool calls in loops)
|
|
853
908
|
* - Sensitive data access (passwords, tokens)
|
|
854
909
|
*
|
|
855
910
|
* Runs AFTER AST validation but BEFORE code execution.
|
|
@@ -864,7 +919,7 @@ export interface CreateEnclaveOptions extends EnclaveConfig {
|
|
|
864
919
|
* },
|
|
865
920
|
* });
|
|
866
921
|
*
|
|
867
|
-
* // External API scorer (
|
|
922
|
+
* // External API scorer (the score is whatever the service returns)
|
|
868
923
|
* const enclave = new Enclave({
|
|
869
924
|
* scoringGate: {
|
|
870
925
|
* scorer: 'external-api',
|
|
@@ -881,7 +936,8 @@ export interface CreateEnclaveOptions extends EnclaveConfig {
|
|
|
881
936
|
* Worker Pool Adapter configuration
|
|
882
937
|
*
|
|
883
938
|
* Only used when adapter is set to 'worker_threads'.
|
|
884
|
-
*
|
|
939
|
+
* Runs each script in a worker thread: an isolate of the engine with its own heap limit, in
|
|
940
|
+
* the same process (not a boundary of the operating system), with:
|
|
885
941
|
* - Pool management (min/max workers, scaling)
|
|
886
942
|
* - Memory monitoring and enforcement
|
|
887
943
|
* - Hard halt capability via worker.terminate()
|
package/value-sanitizer.d.ts
CHANGED
|
@@ -48,7 +48,12 @@ interface PropertyCounter {
|
|
|
48
48
|
count: number;
|
|
49
49
|
}
|
|
50
50
|
/**
|
|
51
|
-
* Internal context
|
|
51
|
+
* Internal context of one sanitization: the property count, and the objects on the way from the
|
|
52
|
+
* root down to the value being copied (circular reference detection).
|
|
53
|
+
*
|
|
54
|
+
* Only an object that contains itself is a circle. An object that is referenced twice without
|
|
55
|
+
* containing itself is copied twice: each copy counts against the property limit, so a value
|
|
56
|
+
* that is small as a graph and large as a tree is bounded like any other large value.
|
|
52
57
|
*/
|
|
53
58
|
interface SanitizeContext {
|
|
54
59
|
propCount: PropertyCounter;
|