@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.
- package/README.md +201 -85
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,29 +1,28 @@
|
|
|
1
1
|
# @enclave-vm/broker
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[](LICENSE)
|
|
5
|
-
[](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
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/@enclave-vm/broker)
|
|
6
|
+
[](https://github.com/agentfront/enclave/blob/main/LICENSE)
|
|
10
7
|
|
|
11
|
-
|
|
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
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
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); //
|
|
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
|
-
|
|
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
|
-
|
|
175
|
+
An error answer holds a `code` and a fixed `message`.
|
|
151
176
|
|
|
152
|
-
|
|
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
|
-
|
|
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
|
-
|
|
195
|
+
</details>
|
|
157
196
|
|
|
158
|
-
|
|
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
|
|
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
|
-
|
|
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))
|
|
237
|
+
if (filter.shouldSend(event)) console.log(event.type);
|
|
203
238
|
});
|
|
204
239
|
```
|
|
205
240
|
|
|
206
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
244
|
-
|
|
|
245
|
-
| [@enclave-vm/core](
|
|
246
|
-
| [@enclave-vm/
|
|
247
|
-
| [@enclave-vm/
|
|
248
|
-
| [@enclave-vm/
|
|
249
|
-
| [@enclave-vm/
|
|
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.
|
|
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.
|
|
38
|
-
"@enclave-vm/stream": "2.20.
|
|
39
|
-
"@enclave-vm/types": "2.20.
|
|
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
|
}
|