@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
@@ -6,5 +6,6 @@
6
6
  export { DisabledScorer } from './disabled.scorer';
7
7
  export { RuleBasedScorer } from './rule-based.scorer';
8
8
  export { ExternalApiScorer, ExternalApiScorerError } from './external-api.scorer';
9
- export { ProgressiveScorer } from './progressive.scorer';
9
+ export { ProgressiveScorer, ProgressiveScorerError } from './progressive.scorer';
10
+ export type { ProgressiveScorerOptions } from './progressive.scorer';
10
11
  export { LocalLlmScorer, LocalLlmScorerError, DISABLE_MODEL_LOAD_ENV } from './local-llm.scorer';
@@ -1,11 +1,16 @@
1
1
  /**
2
2
  * Local LLM Scorer
3
3
  *
4
- * Provides ML-based security scoring with multiple options:
4
+ * Scores the extracted features with one of:
5
5
  * - Built-in heuristics: Keyword-based risk detection (default)
6
6
  * - Custom analyzer: Plug in external LLM or static code analyzer
7
7
  *
8
- * Optionally loads Hugging Face transformers.js for on-device ML support.
8
+ * At initialization the scorer loads a Hugging Face transformers.js pipeline when the optional
9
+ * dependency is installed (the model is downloaded on first use, into `cacheDir`). No score is
10
+ * computed from that model: the pipeline is not called. Whether it loaded decides which of two
11
+ * scorings applies when there is no custom analyzer: the keyword heuristics when it did, the
12
+ * rule-based fallback when it did not (and `fallbackToRules` is on). Set
13
+ * `ENCLAVE_DISABLE_LOCAL_LLM_MODEL=1` to skip the load.
9
14
  *
10
15
  * @packageDocumentation
11
16
  */
@@ -13,7 +18,8 @@ import { BaseScorer } from '../scorer.interface';
13
18
  import type { ExtractedFeatures, ScoringResult, LocalLlmConfig } from '../types';
14
19
  export declare const DISABLE_MODEL_LOAD_ENV = "ENCLAVE_DISABLE_LOCAL_LLM_MODEL";
15
20
  /**
16
- * Local LLM Scorer - ML-based security scoring
21
+ * Local LLM Scorer - keyword heuristics or a host-supplied analyzer (see the file header for
22
+ * what the loaded model is and is not used for)
17
23
  *
18
24
  * @example Basic usage with built-in heuristics
19
25
  * ```typescript
@@ -8,10 +8,36 @@
8
8
  * This provides optimal latency for benign code while still catching
9
9
  * sophisticated attacks through ML analysis.
10
10
  *
11
+ * When the detailed stage is called for and cannot answer (it throws, or it was not
12
+ * configured), the scorer either answers with the fast score alone or fails, depending on
13
+ * `requireDetailed` (see `ProgressiveScorerOptions`).
14
+ *
11
15
  * @packageDocumentation
12
16
  */
13
17
  import { BaseScorer } from '../scorer.interface';
14
18
  import type { ExtractedFeatures, ScoringResult, ProgressiveScoringConfig } from '../types';
19
+ /**
20
+ * Options of the progressive scorer
21
+ */
22
+ export interface ProgressiveScorerOptions {
23
+ /**
24
+ * What happens when the fast score reaches the escalation threshold and the detailed stage
25
+ * cannot answer (it throws, or none is configured):
26
+ *
27
+ * - false: the fast result is the answer
28
+ * - true: `score()` throws a `ProgressiveScorerError`, so that whoever asked decides. The
29
+ * scoring gate sets this when it is configured with `failOpen: false`.
30
+ *
31
+ * @default false
32
+ */
33
+ requireDetailed?: boolean;
34
+ }
35
+ /**
36
+ * Error thrown when the detailed stage is required and cannot answer
37
+ */
38
+ export declare class ProgressiveScorerError extends Error {
39
+ constructor(message: string);
40
+ }
15
41
  /**
16
42
  * Progressive Scorer - fast check first, escalate if suspicious
17
43
  *
@@ -37,7 +63,8 @@ export declare class ProgressiveScorer extends BaseScorer {
37
63
  private readonly escalationThreshold;
38
64
  private readonly combination;
39
65
  private readonly config;
40
- constructor(config: ProgressiveScoringConfig);
66
+ private readonly requireDetailed;
67
+ constructor(config: ProgressiveScoringConfig, options?: ProgressiveScorerOptions);
41
68
  /**
42
69
  * Initialize both scorers
43
70
  */
@@ -24,8 +24,18 @@ import type { ExtractedFeatures, ScoringResult } from '../types';
24
24
  export declare class RuleBasedScorer extends BaseScorer {
25
25
  readonly type: "rule-based";
26
26
  readonly name = "RuleBasedScorer";
27
- private customRules;
27
+ /** The base score of each rule: the built-in one, or the host's from `customRules` */
28
+ private readonly ruleScores;
29
+ /**
30
+ * @param customRules Scores by rule id that replace the built-in ones (clamped to 0-100).
31
+ * Ids that are not rule ids and values that are not numbers are ignored.
32
+ */
28
33
  constructor(customRules?: Record<string, number>);
34
+ /**
35
+ * The most a rule contributes: its built-in cap, or its base score where a host set one
36
+ * above the cap
37
+ */
38
+ private capFor;
29
39
  score(features: ExtractedFeatures): Promise<ScoringResult>;
30
40
  /**
31
41
  * Rule 1: Check for sensitive field access
@@ -6,14 +6,17 @@
6
6
  *
7
7
  * @packageDocumentation
8
8
  */
9
+ import { type NormalizedToolNamespace, type ToolNamespaces } from '@enclave-vm/ast';
9
10
  /**
10
11
  * Scorer implementation types
11
12
  *
12
13
  * - `disabled`: No scoring, pass-through mode (0ms latency)
13
14
  * - `rule-based`: Pure TypeScript rules, zero dependencies (~1ms latency)
14
- * - `local-llm`: On-device LLM scoring (~5-10ms latency, model download required)
15
+ * - `local-llm`: The host's `customAnalyzer`, or a built-in keyword heuristic over the extracted
16
+ * features. A Hugging Face model is loaded at initialization when the optional dependency is
17
+ * installed (downloaded on first use), but no score is computed from it.
15
18
  * - `external-api`: External API-based scoring (~100ms latency, best detection)
16
- * - `progressive`: Fast rule-based check, escalate to ML if suspicious
19
+ * - `progressive`: Fast rule-based check, escalate to a detailed scorer if suspicious
17
20
  */
18
21
  export type ScorerType = 'disabled' | 'rule-based' | 'local-llm' | 'external-api' | 'progressive';
19
22
  /**
@@ -369,8 +372,11 @@ export interface LocalLlmConfig {
369
372
  modelId: 'Xenova/codebert-base' | 'Xenova/all-MiniLM-L6-v2' | string;
370
373
  /**
371
374
  * Scoring mode
372
- * - classification: Use text classification model for direct scoring
373
- * - similarity: Use embeddings + VectoriaDB for similarity-based scoring
375
+ * - classification: the score is the `customAnalyzer`'s, or the built-in keyword heuristic
376
+ * over the extracted features. No classification model is run.
377
+ * - similarity: additionally searches a VectoriaDB index for similar patterns. The index is
378
+ * created empty and this configuration has no way to add patterns to it, so the search
379
+ * finds nothing and the score is the same as in classification mode.
374
380
  * @default 'classification'
375
381
  */
376
382
  mode?: 'classification' | 'similarity';
@@ -410,8 +416,8 @@ export interface LocalLlmConfig {
410
416
  * Custom analyzer for external LLM or static code analysis
411
417
  *
412
418
  * If provided, this analyzer will be used instead of the built-in
413
- * heuristic-based analysis. The HuggingFace pipeline will still be
414
- * loaded for potential embedding support.
419
+ * heuristic-based analysis. The HuggingFace pipeline is still loaded
420
+ * when the optional dependency is installed; its output is not used.
415
421
  *
416
422
  * @example
417
423
  * ```typescript
@@ -568,7 +574,8 @@ export interface ScoringGateConfig {
568
574
  blockThreshold?: number;
569
575
  /**
570
576
  * Score threshold for warning (0-100)
571
- * Scripts with scores >= this value will log a warning
577
+ * Scripts with scores >= this value (and below `blockThreshold`) run, with `warned` set in the
578
+ * result. The gate writes to the console only with `verbose`.
572
579
  * @default 40
573
580
  */
574
581
  warnThreshold?: number;
@@ -592,13 +599,30 @@ export interface ScoringGateConfig {
592
599
  * - true (fail-open): Allow execution if scoring fails
593
600
  * - false (fail-closed): Block execution if scoring fails
594
601
  *
602
+ * A scoring error is anything that keeps the configured scorer from giving its answer: code
603
+ * the feature extractor cannot parse, a scorer that throws, and in progressive mode a detailed
604
+ * stage that fails or is missing once the fast score called for it. With `failOpen: false`
605
+ * each of these blocks the script; with `failOpen: true` the script runs, and `reason` of the
606
+ * result says why. In progressive mode a detailed stage that fails leaves the fast score to
607
+ * decide, and the result has no reason for it.
608
+ *
595
609
  * @default true
596
610
  */
597
611
  failOpen?: boolean;
598
612
  /**
599
- * Custom rules to add or override for rule-based scorer
613
+ * Scores for the rules of the rule-based scorer, by rule id (see `RuleId`): the base score a
614
+ * rule contributes when it fires, instead of the built-in one. Values are clamped to 0-100;
615
+ * 0 turns a rule off. Ids that are not rule ids, and values that are not numbers, are ignored.
616
+ *
617
+ * @example { EXFIL_PATTERN: 100, BULK_OPERATION: 0 }
600
618
  */
601
619
  customRules?: Record<string, number>;
620
+ /**
621
+ * The tool namespaces of the sandbox whose scripts are scored (the `toolNamespaces` of the
622
+ * enclave). A call of a namespace method, `mail.send(args)`, is scored as the tool call it
623
+ * stands for, `callTool('mail.send', args)`. Without this the gate only sees `callTool`.
624
+ */
625
+ toolNamespaces?: ToolNamespaces | ReadonlyArray<NormalizedToolNamespace>;
602
626
  /**
603
627
  * Log detailed scoring information
604
628
  * @default false
@@ -620,6 +644,10 @@ export interface NormalizedScoringConfig {
620
644
  * The effective scorer type
621
645
  */
622
646
  scorerType: ScorerType;
647
+ /**
648
+ * Validated tool namespaces whose method calls are scored as tool calls (empty when none)
649
+ */
650
+ toolNamespaces: ReadonlyArray<NormalizedToolNamespace>;
623
651
  /**
624
652
  * Progressive config if using progressive strategy
625
653
  */
package/secure-proxy.d.ts CHANGED
@@ -163,11 +163,25 @@ export interface SecureProxyOptions {
163
163
  exposeToSandbox?: (value: unknown) => unknown;
164
164
  /**
165
165
  * Whether an object was made in the sandbox realm (by the script, or for it). Such a value is
166
- * the script's own: when a host built-in passes it to a callback (the object a script gave
167
- * `reduce` to collect into) it goes back as it is instead of behind the membrane, where it
168
- * would be read-only. The test must only say yes to what certainly is of that realm.
166
+ * the script's own, wherever it comes back from: passed to a callback by a host built-in (the
167
+ * object a script gave `reduce` to collect into), read out of what a built-in returned (a
168
+ * function a `map` callback returned), or returned by a call. It leaves the membrane as it is,
169
+ * never behind a proxy: a proxy would make the script's object read-only and would send a call
170
+ * to the script's function through the gate for host functions. The test must only say yes to
171
+ * what certainly is of that realm.
169
172
  */
170
173
  ownedBySandbox?: (value: object) => boolean;
174
+ /**
175
+ * Whether a value is the form in which the sandbox holds a value of the host: what
176
+ * `exposeToSandbox` returned for it earlier (the single VM's airlock proxy). A script passes
177
+ * such a value into a call as it is. Whatever the callee does with it (hands it on to a
178
+ * function of the script, keeps it in what it returns), it leaves the membrane as it went in,
179
+ * and it is not wrapped a second time.
180
+ *
181
+ * With this hook set, a built-in method of host data runs on host data only: on an object
182
+ * that is not a value of the host the call is refused (see the apply trap).
183
+ */
184
+ heldBySandbox?: (value: object) => boolean;
171
185
  }
172
186
  /**
173
187
  * Create a secure proxy that blocks dangerous property access
@@ -44,10 +44,17 @@ export declare class Session implements ISession {
44
44
  private readonly config;
45
45
  private readonly toolHandler?;
46
46
  private _pendingToolCall;
47
+ /**
48
+ * How the promise of the pending tool call is settled. Kept beside the pending call and tied
49
+ * to its call id from the moment the call exists, so a result always reaches the call it was
50
+ * submitted for, whenever the tool handler of that call settles.
51
+ */
52
+ private pendingSettlement;
47
53
  private readonly stats;
48
54
  private stdoutBytes;
55
+ /** The promise every caller of wait() gets while the session is running, and how it is resolved */
56
+ private waitPromise;
49
57
  private resolveWait;
50
- private rejectWait;
51
58
  private heartbeatInterval;
52
59
  constructor(options?: SessionOptions);
53
60
  /**
@@ -40,7 +40,8 @@ export interface SessionConfig extends CreateEnclaveOptions {
40
40
  */
41
41
  heartbeatIntervalMs?: number;
42
42
  /**
43
- * Enable encryption for streaming events
43
+ * Not implemented: nothing in the session reads this value, and its events are not encrypted
44
+ * whatever it is set to.
44
45
  * @default false
45
46
  */
46
47
  encryption?: boolean;
@@ -214,8 +215,8 @@ export interface SessionFinalResult {
214
215
  * Runtime channel abstraction
215
216
  *
216
217
  * Provides bidirectional communication between the broker and runtime.
217
- * Different implementations support embedded (in-process) and remote
218
- * (WebSocket) runtime execution.
218
+ * This package implements the embedded (in-process) channel only; the remote (WebSocket)
219
+ * channel is a type of the design, with no implementation here.
219
220
  */
220
221
  export interface RuntimeChannel {
221
222
  /**
@@ -246,7 +247,8 @@ export interface EmbeddedChannelConfig {
246
247
  /**
247
248
  * WebSocket runtime channel configuration
248
249
  *
249
- * For remote execution where the runtime is in a separate process/worker.
250
+ * For remote execution where the runtime is in a separate process/worker. A type of the
251
+ * design: this package has no channel that takes it.
250
252
  */
251
253
  export interface WebSocketChannelConfig {
252
254
  type: 'websocket';
@@ -7,6 +7,6 @@
7
7
  *
8
8
  * @packageDocumentation
9
9
  */
10
- export { ReferenceConfig, REFERENCE_CONFIGS, REF_ID_PREFIX, REF_ID_SUFFIX, REF_ID_PATTERN, isReferenceId, getReferenceConfig, } from './reference-config';
10
+ export { ReferenceConfig, REFERENCE_CONFIGS, REF_ID_PREFIX, REF_ID_SUFFIX, REF_ID_PATTERN, isReferenceId, getReferenceConfig, getMaxTotalResolvedSize, } from './reference-config';
11
11
  export { ReferenceSidecar, ReferenceSource, ReferenceMetadata, SidecarLimitError, ReferenceNotFoundError, } from './reference-sidecar';
12
12
  export { ReferenceResolver, ResolutionLimitError, CompositeHandle, isCompositeHandle } from './reference-resolver';
@@ -27,10 +27,22 @@ export interface ReferenceConfig {
27
27
  */
28
28
  extractionThreshold: number;
29
29
  /**
30
- * Maximum expanded size when resolving references for tool calls
30
+ * Maximum expanded size when resolving references for one tool call
31
31
  * Prevents predictive expansion attacks
32
32
  */
33
33
  maxResolvedSize: number;
34
+ /**
35
+ * Maximum number of bytes the references of one execution may be expanded to, summed over
36
+ * all its tool calls. `maxResolvedSize` limits one call; a script can make many calls, and
37
+ * what was resolved for a call is held until its handler settles.
38
+ *
39
+ * A stored value counts once, the first time it is resolved: every later resolution hands
40
+ * out the same string. A concatenation of references counts every time it is built.
41
+ *
42
+ * @default twice `maxTotalSize`: every stored value can be passed as it is and once more
43
+ * inside a concatenation
44
+ */
45
+ maxTotalResolvedSize?: number;
34
46
  /**
35
47
  * Whether to allow composite handles from concatenation
36
48
  * If false, __safe_concat__ throws when references are detected
@@ -75,6 +87,11 @@ export declare const REF_ID_PATTERN: RegExp;
75
87
  * Check if a string is a reference ID
76
88
  */
77
89
  export declare function isReferenceId(value: unknown): value is string;
90
+ /**
91
+ * The limit on what one execution resolves in total: `maxTotalResolvedSize` when the
92
+ * configuration sets it to a number that is not negative, otherwise twice `maxTotalSize`.
93
+ */
94
+ export declare function getMaxTotalResolvedSize(config: ReferenceConfig): number;
78
95
  /**
79
96
  * Get reference config for a security level, with optional overrides
80
97
  */
@@ -73,10 +73,28 @@ export declare class ReferenceResolver {
73
73
  /**
74
74
  * Check if resolution would exceed size limits
75
75
  *
76
+ * Two limits apply: `maxResolvedSize` to what this value expands to, and
77
+ * `maxTotalResolvedSize` to what the execution has had resolved so far plus what resolving
78
+ * this value would add (see `predictAddedSize`).
79
+ *
76
80
  * @param value - The value to check
77
- * @returns true if resolution would exceed maxResolvedSize
81
+ * @returns true if resolution would exceed maxResolvedSize or the execution's total
78
82
  */
79
83
  wouldExceedLimit(value: unknown): boolean;
84
+ /**
85
+ * Predict what resolving a value would add to the execution's total of resolved data,
86
+ * WITHOUT allocating memory
87
+ *
88
+ * A stored value adds its size the first time it is resolved in the execution and nothing
89
+ * afterwards (`counted` holds the ones this walk has seen). A composite adds the size of the
90
+ * string it is joined into, every time, besides what its parts add.
91
+ */
92
+ private predictAddedSize;
93
+ /**
94
+ * Run a step that counts resolved data against the execution's total; when the sidecar
95
+ * refuses it, the refusal is thrown as the resolution error callers of `resolve` handle
96
+ */
97
+ private withinTotal;
80
98
  /**
81
99
  * Resolve all reference IDs in a value tree
82
100
  *
@@ -77,7 +77,12 @@ export declare class ReferenceSidecar {
77
77
  private readonly config;
78
78
  private readonly storage;
79
79
  private readonly metadata;
80
+ /** The stored values that were resolved for a tool call, as the string they were resolved to */
81
+ private readonly resolved;
80
82
  private totalSize;
83
+ /** Bytes of resolved data built for the tool calls of this execution so far */
84
+ private resolvedSize;
85
+ private readonly maxTotalResolvedSize;
81
86
  private disposed;
82
87
  constructor(config: ReferenceConfig);
83
88
  /**
@@ -108,6 +113,38 @@ export declare class ReferenceSidecar {
108
113
  * @returns The stored data as a string or undefined
109
114
  */
110
115
  retrieveString(refId: string, encoding?: BufferEncoding): string | undefined;
116
+ /**
117
+ * Resolve a reference for a tool call: the stored data as a string
118
+ *
119
+ * A stored value is decoded once in the life of the sidecar (one execution) and counted
120
+ * against `maxTotalResolvedSize` then. Every later resolution, in the same call or in another,
121
+ * returns the same string and counts nothing: a string cannot be changed, so handing it out
122
+ * again takes no memory.
123
+ *
124
+ * @param refId - The reference ID to resolve
125
+ * @returns The stored data as a string, or undefined if the reference is not known
126
+ * @throws SidecarLimitError if the execution's total of resolved data would be exceeded
127
+ */
128
+ resolveString(refId: string): string | undefined;
129
+ /**
130
+ * Whether a reference was resolved before, so that resolving it again counts nothing
131
+ */
132
+ isResolved(refId: string): boolean;
133
+ /**
134
+ * Count resolved data that is about to be built for a tool call of this execution
135
+ *
136
+ * @param bytes - Size of the data in bytes
137
+ * @throws SidecarLimitError if the total would exceed `maxTotalResolvedSize`; nothing is counted then
138
+ */
139
+ countResolved(bytes: number): void;
140
+ /**
141
+ * Whether `bytes` more of resolved data fit in what this execution may resolve in total
142
+ */
143
+ canResolve(bytes: number): boolean;
144
+ /**
145
+ * Bytes of resolved data built for the tool calls of this execution so far
146
+ */
147
+ getResolvedSize(): number;
111
148
  /**
112
149
  * Check if a reference ID exists
113
150
  */
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@enclave-vm/core",
3
- "version": "2.19.0",
3
+ "version": "2.19.2",
4
4
  "description": "Sandbox runtime for secure JavaScript code execution",
5
5
  "author": "AgentFront <info@agentfront.dev>",
6
6
  "homepage": "https://github.com/agentfront/enclave",
@@ -46,8 +46,8 @@
46
46
  },
47
47
  "dependencies": {
48
48
  "@babel/standalone": "^7.29.0",
49
- "@enclave-vm/ast": "2.19.0",
50
- "@enclave-vm/types": "2.19.0",
49
+ "@enclave-vm/ast": "2.19.2",
50
+ "@enclave-vm/types": "2.19.2",
51
51
  "@types/estree": "1.0.8",
52
52
  "acorn": "8.15.0",
53
53
  "acorn-walk": "8.3.4",