@enclave-vm/core 2.19.0 → 2.19.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/README.md +262 -105
  2. package/adapters/interpreter-adapter.d.ts +10 -1
  3. package/adapters/worker-pool/config.d.ts +15 -5
  4. package/adapters/worker-pool/protocol.d.ts +27 -1
  5. package/adapters/worker-pool/worker-pool-adapter.d.ts +24 -0
  6. package/adapters/worker-pool/worker-slot.d.ts +35 -6
  7. package/async-context.d.ts +34 -0
  8. package/babel/babel-wrapper.d.ts +21 -12
  9. package/babel/multi-file-transform.d.ts +3 -0
  10. package/babel/text-scan.d.ts +54 -0
  11. package/deadline-guard.d.ts +16 -0
  12. package/dynamic-import.d.ts +25 -0
  13. package/enclave-options.d.ts +62 -0
  14. package/enclave.d.ts +31 -7
  15. package/esm/index.mjs +4796 -852
  16. package/esm/worker.mjs +1236 -165
  17. package/execution-deadline.d.ts +6 -0
  18. package/global-function-gate.d.ts +34 -1
  19. package/index.d.ts +3 -3
  20. package/index.js +4836 -892
  21. package/interpreter/interpreter.d.ts +247 -8
  22. package/memory-tracker.d.ts +7 -0
  23. package/package.json +3 -3
  24. package/realm-airlock.d.ts +6 -1
  25. package/realm-memory.d.ts +89 -0
  26. package/realm-stack.d.ts +25 -0
  27. package/safe-runtime.d.ts +2 -0
  28. package/sandbox-rejections.d.ts +3 -1
  29. package/scoring/feature-extractor.d.ts +52 -1
  30. package/scoring/index.d.ts +2 -1
  31. package/scoring/scorers/index.d.ts +2 -1
  32. package/scoring/scorers/local-llm.scorer.d.ts +9 -3
  33. package/scoring/scorers/progressive.scorer.d.ts +28 -1
  34. package/scoring/scorers/rule-based.scorer.d.ts +11 -1
  35. package/scoring/types.d.ts +36 -8
  36. package/secure-proxy.d.ts +17 -3
  37. package/session/session.d.ts +8 -1
  38. package/session-types.d.ts +6 -4
  39. package/sidecar/index.d.ts +1 -1
  40. package/sidecar/reference-config.d.ts +18 -1
  41. package/sidecar/reference-resolver.d.ts +19 -1
  42. package/sidecar/reference-sidecar.d.ts +37 -0
  43. package/src/adapters/worker-pool/package.json +3 -3
  44. package/src/adapters/worker-pool/worker-script.js +2250 -428
  45. package/thrown-value.d.ts +59 -0
  46. package/types.d.ts +75 -19
  47. package/value-sanitizer.d.ts +6 -1
  48. package/worker.js +1236 -165
@@ -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
- * Whether to block Date.now() and performance timing APIs
129
- * (prevents timing attacks)
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
- * Whether to allow while/do-while loops
134
- * (false = only bounded for/for-of loops allowed)
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
- * Whether to check for Unicode security attacks in code
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
- * For precise memory isolation, use the worker_threads adapter with `--max-old-space-size`.
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
- * For precise memory isolation, use the worker_threads adapter.
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: 128 * 1024 * 1024 (128MB)
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` has no `console`, so a script that uses it fails there.
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
- * - Lifts large tool results back to the sidecar
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
- * This enables scripts to manipulate large data (videos, PDFs, images)
831
- * without loading them into the JavaScript sandbox.
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
- * Adds semantic security analysis that detects attack patterns
849
- * beyond what static AST validation can catch:
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 attacks (tool calls in loops)
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 (best detection)
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
- * Provides OS-level memory isolation via worker threads with:
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()
@@ -48,7 +48,12 @@ interface PropertyCounter {
48
48
  count: number;
49
49
  }
50
50
  /**
51
- * Internal context for tracking visited objects (circular reference detection)
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;