@enclave-vm/broker 2.20.0 → 2.20.1

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 (2) hide show
  1. package/README.md +201 -85
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,29 +1,28 @@
1
1
  # @enclave-vm/broker
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/@enclave-vm/broker.svg)](https://www.npmjs.com/package/@enclave-vm/broker)
4
- [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
5
- [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
6
-
7
- > Tool broker and session management for the EnclaveJS streaming runtime
3
+ The server side of EnclaveJS streaming: it runs scripts in an `@enclave-vm/core` sandbox, gives them the tools you register, and streams what happens as events, for Node.js services that execute scripts on behalf of clients.
8
4
 
9
- `@enclave-vm/broker` runs scripts in an [`@enclave-vm/core`](../core) sandbox on a server, gives them the tools you register, and streams what happens as events. It can serve sessions over HTTP for [`@enclave-vm/client`](../client).
5
+ [![npm version](https://img.shields.io/npm/v/@enclave-vm/broker.svg)](https://www.npmjs.com/package/@enclave-vm/broker)
6
+ [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/agentfront/enclave/blob/main/LICENSE)
10
7
 
11
- ## What it provides
8
+ The broker builds on [`@enclave-vm/core`](https://www.npmjs.com/package/@enclave-vm/core) (the sandbox) and [`@enclave-vm/types`](https://www.npmjs.com/package/@enclave-vm/types) (the protocol). It can be used in process, or serve sessions over HTTP for [`@enclave-vm/client`](https://www.npmjs.com/package/@enclave-vm/client) and [`@enclave-vm/react`](https://www.npmjs.com/package/@enclave-vm/react). It provides:
12
9
 
13
- - **A tool registry**: tools with a Zod schema for their arguments, and secrets that only tool handlers see.
14
- - **Sessions**: one sandbox per session, with limits (tool calls, lifetime, deadline, per-tool timeout) and a stream of events (`session_init`, `tool_call`, `tool_progress`, `tool_result_applied`, `partial_result`, `heartbeat`, `final`, ...).
15
- - **HTTP routes** for creating, reading, replaying and ending sessions, with an adapter for Express.
16
- - **Event filters** that decide which events a client is sent.
17
- - **Tools from an OpenAPI specification**, kept up to date by polling.
10
+ - a tool registry: tools with a Zod schema for their arguments, and secrets that only tool handlers see;
11
+ - sessions: one sandbox per session, with limits (tool calls, lifetime, deadline, per-tool timeout) and a stream of events;
12
+ - HTTP routes for creating, reading, replaying and ending sessions, with an adapter for Express;
13
+ - event filters that decide which events a client is sent;
14
+ - tools generated from an OpenAPI specification, kept up to date by polling.
18
15
 
19
16
  It does not provide authentication, rate limiting or transport encryption. Authentication is yours to put in front of the routes; the routes can then bind every session to its caller (see [Who may see a session](#who-may-see-a-session)).
20
17
 
21
- ## Installation
18
+ ## Install
22
19
 
23
20
  ```bash
24
- npm install @enclave-vm/broker
21
+ npm install @enclave-vm/broker zod
25
22
  ```
26
23
 
24
+ `zod` (version 4) is needed for the argument schemas of your tools.
25
+
27
26
  ## Quick start
28
27
 
29
28
  ```typescript
@@ -37,19 +36,10 @@ const broker = createBroker({
37
36
  limits: { maxToolCalls: 20, sessionTtlMs: 60_000 },
38
37
  });
39
38
 
40
- broker.secret('API_KEY', process.env.API_KEY!);
41
-
42
39
  broker.tool('getUser', {
43
40
  description: 'Look a user up by id',
44
41
  argsSchema: z.object({ id: z.string() }),
45
- secrets: ['API_KEY'],
46
- handler: async ({ id }, { secrets, signal }) => {
47
- const response = await fetch(`https://api.example.com/users/${encodeURIComponent(id)}`, {
48
- headers: { Authorization: `Bearer ${secrets.API_KEY}` },
49
- signal,
50
- });
51
- return response.json();
52
- },
42
+ handler: async ({ id }) => ({ id, name: 'Ada' }),
53
43
  });
54
44
 
55
45
  const result = await broker.execute(
@@ -60,18 +50,65 @@ const result = await broker.execute(
60
50
  { onEvent: (event) => console.log(event.type) },
61
51
  );
62
52
 
63
- if (result.success) console.log(result.value);
53
+ if (result.success) console.log(result.value); // 'Ada'
64
54
 
65
55
  await broker.dispose();
66
56
  ```
67
57
 
68
- `createBroker` reads `sessions`, `enclave`, `limits` and `history`. A key it does not know is ignored and reported with a warning: a sandbox option such as `securityLevel` has no effect at the top level.
58
+ ## Broker
59
+
60
+ `createBroker(config?)` (or `new Broker(config?)`) reads these options. A key it does not know is ignored and reported with a warning: a sandbox option such as `securityLevel` has no effect at the top level.
61
+
62
+ | Option | Type | Default | Meaning |
63
+ | ---------- | ------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------- |
64
+ | `enclave` | `CreateEnclaveOptions` | sandbox defaults | Options of the `@enclave-vm/core` sandbox of every session |
65
+ | `limits` | `Partial<SessionLimits>` | `DEFAULT_SESSION_LIMITS` | Limits of every session (see [Limits](#limits)) |
66
+ | `sessions` | `SessionManagerConfig` | `{ maxSessions: 100, cleanupIntervalMs: 60000 }` | Number of registered sessions, and how often finished and expired ones are removed |
67
+ | `history` | `SessionHistoryLimits` | `{ maxEvents: 10000, maxBytes: 4194304 }` | Events each session keeps for a replay |
68
+
69
+ Main methods:
70
+
71
+ | Method | Description |
72
+ | ---------------------------------------------------------- | --------------------------------------------------------------------- |
73
+ | `tool(name, definition)` / `tools(definitions)` | Register tools |
74
+ | `hasTool`, `listTools`, `removeTool` | Inspect and remove tools |
75
+ | `secret(key, value)` / `secrets(values)` | Store secrets for tool handlers |
76
+ | `hasSecret`, `removeSecret` | Inspect and remove secrets |
77
+ | `execute(code, { session?, onEvent? })` | Run a script in a new session and resolve with its result |
78
+ | `createSession(config?)` | Create a `BrokerSession` to drive yourself |
79
+ | `getSession(id)`, `listSessions()`, `listActiveSessions()` | Look sessions up |
80
+ | `terminateSession(id, reason?)` | End a session |
81
+ | `openapi(config)` | Add an OpenAPI source (see [Tools from OpenAPI](#tools-from-openapi)) |
82
+ | `stats()`, `cleanup()`, `dispose()` | Statistics, removal of finished sessions, shutdown |
83
+
84
+ ### Tools and secrets
85
+
86
+ ```typescript
87
+ broker.secret('API_KEY', process.env.API_KEY!);
88
+
89
+ broker.tool('getRemoteUser', {
90
+ description: 'Look a user up in the users API',
91
+ argsSchema: z.object({ id: z.string() }),
92
+ secrets: ['API_KEY'],
93
+ config: { timeout: 5_000 },
94
+ handler: async ({ id }, { secrets, signal }) => {
95
+ const response = await fetch(`https://api.example.com/users/${encodeURIComponent(id)}`, {
96
+ headers: { Authorization: `Bearer ${secrets.API_KEY}` },
97
+ signal,
98
+ });
99
+ return response.json();
100
+ },
101
+ });
102
+ ```
103
+
104
+ A tool definition has `handler` (required), `description`, `argsSchema`, `secrets` (names of the secrets the handler receives) and `config` (`ToolConfig`; only `timeout` has an effect). The handler receives the validated arguments and a context with `sessionId`, `callId`, `secrets` and `signal`. The signal is aborted when the call times out or the session is cancelled.
69
105
 
70
106
  ## Serving sessions over HTTP
71
107
 
72
108
  ```typescript
73
109
  import express from 'express';
74
110
  import { createBroker, createSessionHandler, registerExpressRoutes } from '@enclave-vm/broker';
111
+ import { authenticate } from './auth.js'; // your authentication middleware
75
112
 
76
113
  const broker = createBroker();
77
114
  const handler = createSessionHandler({
@@ -83,7 +120,7 @@ const handler = createSessionHandler({
83
120
 
84
121
  const app = express();
85
122
  app.use(express.json({ limit: '1mb' }));
86
- app.use(authenticate); // your authentication, before the routes
123
+ app.use(authenticate); // before the routes; let OPTIONS requests through (see "Cross-origin requests")
87
124
  registerExpressRoutes(app, handler);
88
125
  app.listen(3000);
89
126
  ```
@@ -99,6 +136,21 @@ app.listen(3000);
99
136
 
100
137
  For another framework, call `handler.getRoutes()` and adapt its request and response to `BrokerRequest` and `BrokerResponse`. `createExpressRouter` is deprecated: it registers no route.
101
138
 
139
+ ### Handler options
140
+
141
+ | Option | Type | Default | Meaning |
142
+ | ---------------------- | ------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
143
+ | `broker` | `Broker` | Required | The broker whose sessions the routes serve |
144
+ | `identify` | `CallerIdentifier` | none | Returns the caller of a request; binds every session to its creator (see below) |
145
+ | `cors` | `boolean` | `true` | Send CORS headers |
146
+ | `allowedOrigins` | `string[]` | `['*']` | Origins CORS headers are sent for |
147
+ | `allowedHeaders` | `string[]` | `[]` | Request headers a cross-origin page may send, besides the fixed ones |
148
+ | `sessionList` | `boolean` | `true` | Serve `GET /sessions` |
149
+ | `maxStreamsPerSession` | `number` | `8` | Streams one session may have open; a further one is answered with `429` |
150
+ | `maxBufferedBytes` | `number` | `8388608` (8 MB) | How far a reader may fall behind before its stream is dropped; dropping the creator's stream cancels the session. A custom adapter takes part by implementing `bufferedBytes()` and `destroy()` on its `BrokerResponse` |
151
+
152
+ An unknown option is ignored and reported with a warning.
153
+
102
154
  ### The request body of `POST /sessions`
103
155
 
104
156
  ```jsonc
@@ -112,50 +164,37 @@ For another framework, call `handler.getRoutes()` and adapt its request and resp
112
164
 
113
165
  The body is validated as a whole, and a request that does not pass is answered with `400` before a session exists:
114
166
 
115
- - `config` values are positive integers. A request can **lower** `maxToolCalls` and `maxExecutionMs` (the session's lifetime) and can never raise them above the broker's `limits` (or the package defaults when you set none). `heartbeatIntervalMs` is kept between 1 second and 5 minutes.
167
+ - `config` values are positive integers. A request can **lower** `maxToolCalls` and `maxExecutionMs` (the session's lifetime, `sessionTtlMs`) and can never raise them above the broker's `limits` (or the package defaults when you set none). `heartbeatIntervalMs` is kept between 1 second and 5 minutes.
116
168
  - `sessionId` is `s_` followed by 1 to 128 characters of `A-Z a-z 0-9 . _ : ~ -`. An id that is in use is answered with `409 SESSION_EXISTS`.
117
169
  - `filter` is checked against fixed bounds (16 rules, 32 patterns, 256 characters per pattern); see [Event filters](#event-filters).
118
170
  - A request with `encryption.mode: "required"` is refused: this broker does not encrypt sessions.
119
171
 
120
- Other answers: `401 UNAUTHORIZED` (no caller identity), `404 NOT_FOUND`, `410 EVENTS_GONE`, `429 TOO_MANY_STREAMS`, `503 MAX_SESSIONS_REACHED`, `500 SESSION_CREATE_ERROR`. An error answer holds a `code` and a fixed `message`.
121
-
122
- ## Security
123
-
124
- ### Who may see a session
125
-
126
- **Without an `identify` hook the routes do not tell callers apart.** Whoever can reach them can list every session, read its state, replay its events (tool arguments and the final result included) and end it. That is acceptable only where every caller is trusted alike, for example a broker that a single backend talks to. Authentication in front of the routes does not change it: an authenticated caller still reaches the sessions of every other caller.
127
-
128
- With `identify`, every session belongs to the caller that created it:
129
-
130
- ```typescript
131
- const handler = createSessionHandler({
132
- broker,
133
- identify: (request) => {
134
- // `request.raw` is the framework's request object, `request.headers` the headers.
135
- const user = (request.raw as { user?: { id: string } }).user;
136
- return user?.id; // a stable, non-empty string per caller; nothing when there is none
137
- },
138
- });
139
- ```
140
-
141
- - `GET /sessions` lists the caller's own sessions.
142
- - Reading, replaying and ending a session is answered only for its owner. Another caller gets `404`, the answer of an id that does not exist.
143
- - A request for which the hook returns nothing, or throws, is answered with `401`.
144
- - A session created in process (`broker.createSession()`) has no owner and is not reachable over the routes, unless you pass `owner`.
145
-
146
- The hook identifies; it does not authenticate. Verify the credential in your own middleware, or in the hook itself.
147
-
148
- It separates sessions, not data: a tool handler receives its arguments and a context with the id of its session, not the caller. A tool that reads data restricted per caller applies that restriction itself, with the owner of its session (`broker.getSession(context.sessionId as SessionId)?.owner`, the caller the hook returned), or leaves it to the data store.
172
+ <details>
173
+ <summary>Error answers</summary>
149
174
 
150
- ### Cross-origin requests
175
+ An error answer holds a `code` and a fixed `message`.
151
176
 
152
- CORS headers are on by default with `Access-Control-Allow-Origin: *`, so a page of any origin can call a broker its visitor's browser can reach, including one on `localhost` or an internal network. Set `allowedOrigins` to the origins of your application, or `cors: false`, for anything that is not a public demo.
177
+ | Status | Code | When |
178
+ | ------ | ------------------------------ | -------------------------------------------------------------------------- |
179
+ | 400 | `INVALID_REQUEST` | Invalid body, session id or `X-Session-Instance-ID` header |
180
+ | 400 | `INVALID_FILTER` | Invalid `filter`, in the body of `POST /sessions` or the query of a stream |
181
+ | 401 | `UNAUTHORIZED` | `identify` returned no caller, or threw |
182
+ | 404 | `NOT_FOUND` | Unknown session, a session of another caller, or the list is switched off |
183
+ | 409 | `SESSION_EXISTS` | The session id is in use |
184
+ | 409 | `SESSION_INSTANCE_UNAVAILABLE` | A conditional stop for a session that was created without an instance id |
185
+ | 410 | `EVENTS_GONE` | A replay that starts below the events the session still keeps |
186
+ | 412 | `SESSION_INSTANCE_MISMATCH` | A conditional stop for a session that was replaced |
187
+ | 429 | `TOO_MANY_STREAMS` | The session has `maxStreamsPerSession` streams open |
188
+ | 500 | `SESSION_CREATE_ERROR` | The session could not be created |
189
+ | 500 | `INTERNAL_ERROR` | The session list could not be produced |
190
+ | 503 | `MAX_SESSIONS_REACHED` | The broker holds `sessions.maxSessions` sessions |
191
+ | 503 | `SERVICE_UNAVAILABLE` | The broker is disposed |
153
192
 
154
- A cross-origin page may send `Content-Type`, `Accept`, `Last-Event-ID` and `Authorization`. If your clients send another header (an API-key header through the client's `headers` option, say), name it in `allowedHeaders`: a browser does not send a header the preflight answer does not list.
193
+ `X-Session-Instance-ID` is an optional header that `@enclave-vm/client` sends: a stop that carries it ends the session only if it is the creation that sent the same value.
155
194
 
156
- The routes answer the preflight (`OPTIONS`) themselves, and a browser sends it without the credential: authentication in front of the routes has to let `OPTIONS` requests through to them.
195
+ </details>
157
196
 
158
- ### Limits
197
+ ## Limits
159
198
 
160
199
  `limits` (see `SessionLimits` in `@enclave-vm/types`) bound every session of a broker. A session created in process may name its own value for a limit; a session created over HTTP may only lower `maxToolCalls` and the lifetime.
161
200
 
@@ -177,14 +216,9 @@ The routes answer the preflight (`OPTIONS`) themselves, and a browser sends it w
177
216
  What a session keeps and writes is bounded as well:
178
217
 
179
218
  - `history: { maxEvents, maxBytes }` (default 10,000 events and 4 MB) bounds the events a session keeps for a replay. When a bound is reached the oldest events are dropped, and a replay that would start below the kept events is answered with `410 EVENTS_GONE`.
180
- - `maxStreamsPerSession` (handler option, default 8) bounds the streams one session has open; a further one is answered with `429`.
181
- - `maxBufferedBytes` (handler option, default 8 MB): a reader that falls behind by more is disconnected, and when it is the creator of the session, the session is cancelled. A custom adapter takes part by implementing `bufferedBytes()` and `destroy()` on its `BrokerResponse`.
182
-
183
- ### What cancelling does, and what one script can hold
184
-
185
- A session runs in the broker's own process and thread. A script that computes without calling a tool holds the thread, and with it every other session, until it ends or reaches `toolTimeoutMs`. Cancelling a session (`DELETE`, a caller that disconnects, `deadlineMs`, `session.cancel()`) aborts the tool call in flight and refuses every later one; it does not interrupt a script that is computing. Keep `toolTimeoutMs` low, and run the broker in a process of its own (or give the sandbox the worker-pool adapter through `enclave`) when you serve callers you do not trust.
219
+ - `maxStreamsPerSession` and `maxBufferedBytes` (handler options above) bound the streams of a session and how far a reader may fall behind.
186
220
 
187
- ### Event filters
221
+ ## Event filters
188
222
 
189
223
  A filter decides which events a client is sent: by type, or by content with `exact`, `prefix`, `regex` and `glob` patterns.
190
224
 
@@ -198,19 +232,20 @@ const filter = createEventFilter({
198
232
  },
199
233
  });
200
234
 
235
+ const session = broker.createSession();
201
236
  session.onEvent((event) => {
202
- if (filter.shouldSend(event)) send(event);
237
+ if (filter.shouldSend(event)) console.log(event.type);
203
238
  });
204
239
  ```
205
240
 
206
- - Evaluating one event takes a bounded time: regular expressions and globs run under `regexTimeoutMs` (100 ms by default). `budgetMs` bounds all evaluations of one filter together.
241
+ `createEventFilter` takes `config` (`EventFilterConfig`), and optionally `onError`, `budgetMs` (total time for regular expressions and globs over the filter's life; no budget by default) and `expandGlobs` (default `true`). `createTypeFilter` and `createContentFilter` build a `config`.
242
+
243
+ - Evaluating one event takes a bounded time: regular expressions and globs run under `regexTimeoutMs` (100 ms by default).
207
244
  - An event a filter could not evaluate (a pattern that does not compile, an evaluation that ran out of time) is **not sent**, in either mode.
208
- - In exclude mode a glob is matched as text: `*` also matches `/` and a leading dot. In include mode a glob follows path rules, as before.
245
+ - In exclude mode a glob is matched as text: `*` also matches `/` and a leading dot. In include mode a glob follows path rules.
209
246
  - A filter that arrives in a request is validated, gets at most 100 ms per event and 500 ms per stream, and its globs are matched without brace and extglob expansion.
210
247
 
211
- A filter is a convenience for the client. **It is not a confidentiality control**: data a client must not see has to stay out of the events, that is, out of tool arguments and results.
212
-
213
- ### Tools from OpenAPI
248
+ ## Tools from OpenAPI
214
249
 
215
250
  ```typescript
216
251
  const source = broker.openapi({
@@ -219,18 +254,91 @@ const source = broker.openapi({
219
254
  baseUrl: 'https://api.example.com',
220
255
  auth: { type: 'bearer', token: process.env.API_TOKEN! },
221
256
  intervalMs: 60_000,
257
+ loaderOptions: { includeOperations: ['getUser', 'listUsers'] },
222
258
  });
223
259
 
224
260
  source.on('error', (error) => console.error('users API:', error.message));
225
261
  await source.start();
226
262
  ```
227
263
 
264
+ <details>
265
+ <summary>OpenAPI source options</summary>
266
+
267
+ | Option | Type | Default | Meaning |
268
+ | ------------------------------------------------------- | ------------------------------------------------------------- | -------------- | ---------------------------------------------------------- |
269
+ | `name` | `string` | Required | Name of the source |
270
+ | `url` | `string` | Required | URL of the specification |
271
+ | `baseUrl` | `string` | Required | Base URL of the upstream API that the generated tools call |
272
+ | `auth` | `{ type: 'bearer' \| 'api-key' \| 'basic', token?, header? }` | none | Credential for the upstream API |
273
+ | `intervalMs` | `number` | `60000` | Polling interval |
274
+ | `fetchTimeoutMs` | `number` | `10000` | Time limit for fetching the specification |
275
+ | `headers` | `Record<string, string>` | none | Headers for the specification request |
276
+ | `maxSpecBytes` | `number` | 32 MB | Largest specification read |
277
+ | `changeDetection`, `retry`, `unhealthyThreshold` | see `OpenApiPollerConfig` | | Polling behaviour |
278
+ | `loaderOptions.includeOperations` / `excludeOperations` | `string[]` | all operations | Operations that become tools |
279
+ | `loaderOptions.headers` | `Record<string, string>` | none | Headers sent to the upstream API |
280
+ | `loaderOptions.maxResponseBytes` | `number` | 10 MB | Largest upstream response read |
281
+ | `loaderOptions.perToolDeadlineMs`, `namingStrategy` | see `LoaderOptions` | | Per-tool timeout, tool naming |
282
+
283
+ </details>
284
+
228
285
  - A failure while polling is reported with the `error` event when it has a listener, and in `source.getStats()` (`pollHealth`, `lastError`) either way. The tools of the last specification that was applied stay registered. Tools are replaced in one step, and a source never replaces a tool it does not manage.
229
286
  - A path parameter fills its own segment of the path: a value that would leave the segment empty or turn it into `.` or `..` fails the call.
230
287
  - The credential (`auth`) and `loaderOptions.headers` go to the origin of `baseUrl` only. They are not sent with the request for the specification when it is on another origin (use `headers` of the source for what the specification host needs), and a redirect to another origin is followed without them. A header parameter of the specification cannot replace them.
231
- - Upstream responses are read up to `loaderOptions.maxResponseBytes` (10 MB), specifications up to `maxSpecBytes` (32 MB), and fetching a specification is bounded by `fetchTimeoutMs`.
232
288
 
233
- A script decides the arguments of a generated tool, so whatever an operation of the upstream does with its arguments is within reach of a script. Generate tools only for the operations a script may call (`loaderOptions.includeOperations`, `loaderOptions.excludeOperations`).
289
+ ## Security notes
290
+
291
+ ### What it does not do
292
+
293
+ - **No authentication and no rate limiting.** Put both in front of the routes.
294
+ - **No encryption.** Events are plain JSON; a request that requires encryption is refused. Serve the routes over HTTPS.
295
+ - **No separate process per session.** Sessions run in the broker's own process and thread, each in its own sandbox (see [What cancelling does](#what-cancelling-does-and-what-one-script-can-hold)).
296
+
297
+ ### Who may see a session
298
+
299
+ **Without an `identify` hook the routes do not tell callers apart.** Whoever can reach them can list every session, read its state, replay its events (tool arguments and the final result included) and end it. That is acceptable only where every caller is trusted alike, for example a broker that a single backend talks to. Authentication in front of the routes does not change it: an authenticated caller still reaches the sessions of every other caller.
300
+
301
+ With `identify`, every session belongs to the caller that created it:
302
+
303
+ ```typescript
304
+ const handler = createSessionHandler({
305
+ broker,
306
+ identify: (request) => {
307
+ // `request.raw` is the framework's request object, `request.headers` the headers.
308
+ const user = (request.raw as { user?: { id: string } }).user;
309
+ return user?.id; // a stable, non-empty string per caller; nothing when there is none
310
+ },
311
+ });
312
+ ```
313
+
314
+ - `GET /sessions` lists the caller's own sessions.
315
+ - Reading, replaying and ending a session is answered only for its owner. Another caller gets `404`, the answer of an id that does not exist.
316
+ - A request for which the hook returns nothing, or throws, is answered with `401`.
317
+ - A session created in process (`broker.createSession()`) has no owner and is not reachable over the routes, unless you pass `owner`.
318
+
319
+ The hook identifies; it does not authenticate. Verify the credential in your own middleware, or in the hook itself.
320
+
321
+ It separates sessions, not data: a tool handler receives its arguments and a context with the id of its session, not the caller. A tool that reads data restricted per caller applies that restriction itself, with the owner of its session (`broker.getSession(context.sessionId as SessionId)?.owner`, the caller the hook returned), or leaves it to the data store.
322
+
323
+ ### Cross-origin requests
324
+
325
+ CORS headers are on by default with `Access-Control-Allow-Origin: *`, so a page of any origin can call a broker its visitor's browser can reach, including one on `localhost` or an internal network. Set `allowedOrigins` to the origins of your application, or `cors: false`, for anything that is not a public demo.
326
+
327
+ A cross-origin page may send `Content-Type`, `Accept`, `Last-Event-ID`, `Authorization` and `X-Session-Instance-ID`. If your clients send another header (an API-key header through the client's `headers` option, say), name it in `allowedHeaders`: a browser does not send a header the preflight answer does not list.
328
+
329
+ The routes answer the preflight (`OPTIONS`) themselves, and a browser sends it without the credential: authentication in front of the routes has to let `OPTIONS` requests through to them.
330
+
331
+ ### What cancelling does, and what one script can hold
332
+
333
+ A session runs in the broker's own process and thread. A script that computes without calling a tool holds the thread, and with it every other session, until it ends or reaches `toolTimeoutMs`. Cancelling a session (`DELETE`, a caller that disconnects, `deadlineMs`, `session.cancel()`) aborts the tool call in flight and refuses every later one; it does not interrupt a script that is computing. Keep `toolTimeoutMs` low, and run the broker in a process of its own (or give the sandbox the worker-thread adapter with `enclave: { adapter: 'worker_threads' }`) when you serve callers you do not trust.
334
+
335
+ ### Event filters are not access control
336
+
337
+ A filter is a convenience for the client. **It is not a confidentiality control**: data a client must not see has to stay out of the events, that is, out of tool arguments and results.
338
+
339
+ ### Tools from OpenAPI
340
+
341
+ A script decides the arguments of a generated tool, so whatever an operation of the upstream does with its arguments is within reach of a script. Generate tools only for the operations a script may call (`loaderOptions.includeOperations`, `loaderOptions.excludeOperations`). Upstream responses are read up to `loaderOptions.maxResponseBytes`, specifications up to `maxSpecBytes`.
234
342
 
235
343
  ### Secrets and tool arguments
236
344
 
@@ -240,14 +348,22 @@ The message and code of an exception a handler throws are passed on to the scrip
240
348
 
241
349
  ## Related packages
242
350
 
243
- | Package | Description |
244
- | --------------------------------- | ------------------------------------------------------------- |
245
- | [@enclave-vm/core](../core) | The sandbox |
246
- | [@enclave-vm/types](../types) | Protocol types and Zod schemas |
247
- | [@enclave-vm/client](../client) | Browser and Node.js client |
248
- | [@enclave-vm/stream](../stream) | NDJSON and reconnection helpers |
249
- | [@enclave-vm/runtime](../runtime) | Runtime worker building blocks (does not execute scripts yet) |
351
+ | Package | Role |
352
+ | ------------------------------------------------------------------------ | ------------------------------------------------------ |
353
+ | [@enclave-vm/core](https://www.npmjs.com/package/@enclave-vm/core) | The sandbox |
354
+ | [@enclave-vm/client](https://www.npmjs.com/package/@enclave-vm/client) | Browser and Node.js client for these routes |
355
+ | [@enclave-vm/react](https://www.npmjs.com/package/@enclave-vm/react) | React provider and hooks on top of the client |
356
+ | [@enclave-vm/types](https://www.npmjs.com/package/@enclave-vm/types) | Protocol types and Zod schemas |
357
+ | [@enclave-vm/stream](https://www.npmjs.com/package/@enclave-vm/stream) | NDJSON and reconnection helpers |
358
+ | [@enclave-vm/runtime](https://www.npmjs.com/package/@enclave-vm/runtime) | Runtime worker building blocks (does not execute code) |
359
+
360
+ ## Documentation
361
+
362
+ - Documentation: https://agentfront.dev/docs/guides/enclave
363
+ - Repository: https://github.com/agentfront/enclave
364
+ - Architecture: https://github.com/agentfront/enclave/blob/main/README-ARCHITECTURE.md
365
+ - Security policy: https://github.com/agentfront/enclave/blob/main/SECURITY.md
250
366
 
251
367
  ## License
252
368
 
253
- Apache-2.0
369
+ Apache-2.0. See [LICENSE](https://github.com/agentfront/enclave/blob/main/LICENSE).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@enclave-vm/broker",
3
- "version": "2.20.0",
3
+ "version": "2.20.1",
4
4
  "description": "Tool broker and session management for the EnclaveJS streaming runtime",
5
5
  "author": "AgentFront <info@agentfront.dev>",
6
6
  "homepage": "https://github.com/agentfront/enclave",
@@ -34,9 +34,9 @@
34
34
  }
35
35
  },
36
36
  "dependencies": {
37
- "@enclave-vm/core": "2.20.0",
38
- "@enclave-vm/stream": "2.20.0",
39
- "@enclave-vm/types": "2.20.0",
37
+ "@enclave-vm/core": "2.20.1",
38
+ "@enclave-vm/stream": "2.20.1",
39
+ "@enclave-vm/types": "2.20.1",
40
40
  "minimatch": "^11.0.1",
41
41
  "zod": "^4.6.6"
42
42
  }