@enclave-vm/broker 0.0.1 → 2.9.0
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 +202 -0
- package/esm/index.mjs +1569 -0
- package/esm/package.json +6 -0
- package/index.js +1611 -0
- package/package.json +12 -11
- package/src/broker-session.js +0 -312
- package/src/broker-session.js.map +0 -1
- package/src/broker.js +0 -290
- package/src/broker.js.map +0 -1
- package/src/event-filter.js +0 -305
- package/src/event-filter.js.map +0 -1
- package/src/http/express-adapter.js +0 -172
- package/src/http/express-adapter.js.map +0 -1
- package/src/http/index.js +0 -14
- package/src/http/index.js.map +0 -1
- package/src/http/session-handler.js +0 -351
- package/src/http/session-handler.js.map +0 -1
- package/src/http/types.js +0 -10
- package/src/http/types.js.map +0 -1
- package/src/index.js +0 -39
- package/src/index.js.map +0 -1
- package/src/session-manager.js +0 -203
- package/src/session-manager.js.map +0 -1
- package/src/tool-registry.js +0 -240
- package/src/tool-registry.js.map +0 -1
- /package/{src/broker-session.d.ts → broker-session.d.ts} +0 -0
- /package/{src/broker.d.ts → broker.d.ts} +0 -0
- /package/{src/event-filter.d.ts → event-filter.d.ts} +0 -0
- /package/{src/http → http}/express-adapter.d.ts +0 -0
- /package/{src/http → http}/index.d.ts +0 -0
- /package/{src/http → http}/session-handler.d.ts +0 -0
- /package/{src/http → http}/types.d.ts +0 -0
- /package/{src/index.d.ts → index.d.ts} +0 -0
- /package/{src/session-manager.d.ts → session-manager.d.ts} +0 -0
- /package/{src/tool-registry.d.ts → tool-registry.d.ts} +0 -0
package/README.md
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
# @enclave-vm/broker
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@enclave-vm/broker)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](https://www.typescriptlang.org/)
|
|
6
|
+
|
|
7
|
+
> Tool broker and session management for the EnclaveJS streaming runtime
|
|
8
|
+
|
|
9
|
+
The @enclave-vm/broker package provides server-side components for managing EnclaveJS sessions, routing tool calls, and handling the streaming protocol. It acts as the middleware between clients and the secure execution environment.
|
|
10
|
+
|
|
11
|
+
## Features
|
|
12
|
+
|
|
13
|
+
- **Session Management**: Create, manage, and clean up execution sessions
|
|
14
|
+
- **Tool Routing**: Route tool calls to appropriate handlers with pattern matching
|
|
15
|
+
- **Access Control**: Fine-grained tool permissions using glob patterns
|
|
16
|
+
- **Rate Limiting**: Configurable rate limits per session
|
|
17
|
+
- **State Management**: Track session state and tool call history
|
|
18
|
+
- **Middleware Support**: Extensible middleware pipeline for tool calls
|
|
19
|
+
|
|
20
|
+
## Installation
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm install @enclave-vm/broker
|
|
24
|
+
# or
|
|
25
|
+
yarn add @enclave-vm/broker
|
|
26
|
+
# or
|
|
27
|
+
pnpm add @enclave-vm/broker
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Quick Start
|
|
31
|
+
|
|
32
|
+
```typescript
|
|
33
|
+
import { Broker, createSession } from '@enclave-vm/broker';
|
|
34
|
+
|
|
35
|
+
// Create a broker with tool handlers
|
|
36
|
+
const broker = new Broker({
|
|
37
|
+
tools: {
|
|
38
|
+
'users:get': async (args) => {
|
|
39
|
+
return { id: args.id, name: 'Alice' };
|
|
40
|
+
},
|
|
41
|
+
'users:list': async () => {
|
|
42
|
+
return [
|
|
43
|
+
{ id: 1, name: 'Alice' },
|
|
44
|
+
{ id: 2, name: 'Bob' },
|
|
45
|
+
];
|
|
46
|
+
},
|
|
47
|
+
},
|
|
48
|
+
});
|
|
49
|
+
|
|
50
|
+
// Create a session
|
|
51
|
+
const session = await broker.createSession({
|
|
52
|
+
allowedTools: ['users:*'], // Glob pattern for allowed tools
|
|
53
|
+
timeout: 30000,
|
|
54
|
+
maxToolCalls: 100,
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
// Handle incoming messages
|
|
58
|
+
session.on('tool_call', async (call) => {
|
|
59
|
+
const result = await broker.executeToolCall(session.id, call);
|
|
60
|
+
session.send({ type: 'tool_result', id: call.id, data: result });
|
|
61
|
+
});
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Session Management
|
|
65
|
+
|
|
66
|
+
```typescript
|
|
67
|
+
import { SessionManager } from '@enclave-vm/broker';
|
|
68
|
+
|
|
69
|
+
const manager = new SessionManager({
|
|
70
|
+
maxConcurrentSessions: 100,
|
|
71
|
+
sessionTimeout: 60000, // 1 minute
|
|
72
|
+
cleanupInterval: 10000, // 10 seconds
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
// Create session
|
|
76
|
+
const session = await manager.create({
|
|
77
|
+
userId: 'user_123',
|
|
78
|
+
metadata: { source: 'api' },
|
|
79
|
+
});
|
|
80
|
+
|
|
81
|
+
// Get session
|
|
82
|
+
const retrieved = manager.get(session.id);
|
|
83
|
+
|
|
84
|
+
// List active sessions
|
|
85
|
+
const sessions = manager.list({ userId: 'user_123' });
|
|
86
|
+
|
|
87
|
+
// Destroy session
|
|
88
|
+
await manager.destroy(session.id);
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Tool Routing
|
|
92
|
+
|
|
93
|
+
Route tool calls with pattern matching:
|
|
94
|
+
|
|
95
|
+
```typescript
|
|
96
|
+
import { ToolRouter } from '@enclave-vm/broker';
|
|
97
|
+
|
|
98
|
+
const router = new ToolRouter();
|
|
99
|
+
|
|
100
|
+
// Register tools with glob patterns
|
|
101
|
+
router.register('db:*', {
|
|
102
|
+
handler: async (name, args) => {
|
|
103
|
+
const operation = name.split(':')[1];
|
|
104
|
+
return await database[operation](args);
|
|
105
|
+
},
|
|
106
|
+
rateLimit: { maxCalls: 100, windowMs: 60000 },
|
|
107
|
+
});
|
|
108
|
+
|
|
109
|
+
router.register('api:external:*', {
|
|
110
|
+
handler: async (name, args) => {
|
|
111
|
+
return await externalApi.call(name, args);
|
|
112
|
+
},
|
|
113
|
+
requiresAuth: true,
|
|
114
|
+
});
|
|
115
|
+
|
|
116
|
+
// Execute tool call
|
|
117
|
+
const result = await router.execute('db:query', { sql: 'SELECT * FROM users' });
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## Access Control
|
|
121
|
+
|
|
122
|
+
```typescript
|
|
123
|
+
import { AccessController } from '@enclave-vm/broker';
|
|
124
|
+
|
|
125
|
+
const access = new AccessController({
|
|
126
|
+
defaultPolicy: 'deny',
|
|
127
|
+
rules: [
|
|
128
|
+
{ pattern: 'public:*', allow: true },
|
|
129
|
+
{ pattern: 'admin:*', allow: false, unless: { role: 'admin' } },
|
|
130
|
+
{ pattern: 'user:*:read', allow: true },
|
|
131
|
+
{ pattern: 'user:*:write', allow: false, unless: { owner: true } },
|
|
132
|
+
],
|
|
133
|
+
});
|
|
134
|
+
|
|
135
|
+
// Check access
|
|
136
|
+
const canAccess = access.check('admin:delete', { role: 'user' }); // false
|
|
137
|
+
const canRead = access.check('user:profile:read', {}); // true
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## Middleware
|
|
141
|
+
|
|
142
|
+
Add middleware for cross-cutting concerns:
|
|
143
|
+
|
|
144
|
+
```typescript
|
|
145
|
+
import { Broker } from '@enclave-vm/broker';
|
|
146
|
+
|
|
147
|
+
const broker = new Broker({
|
|
148
|
+
middleware: [
|
|
149
|
+
// Logging middleware
|
|
150
|
+
async (call, next) => {
|
|
151
|
+
console.log(`Tool call: ${call.name}`);
|
|
152
|
+
const start = Date.now();
|
|
153
|
+
const result = await next(call);
|
|
154
|
+
console.log(`Completed in ${Date.now() - start}ms`);
|
|
155
|
+
return result;
|
|
156
|
+
},
|
|
157
|
+
// Validation middleware
|
|
158
|
+
async (call, next) => {
|
|
159
|
+
if (!isValidArgs(call.name, call.args)) {
|
|
160
|
+
throw new Error('Invalid arguments');
|
|
161
|
+
}
|
|
162
|
+
return next(call);
|
|
163
|
+
},
|
|
164
|
+
],
|
|
165
|
+
tools: {
|
|
166
|
+
// ... tool handlers
|
|
167
|
+
},
|
|
168
|
+
});
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## Rate Limiting
|
|
172
|
+
|
|
173
|
+
```typescript
|
|
174
|
+
import { RateLimiter } from '@enclave-vm/broker';
|
|
175
|
+
|
|
176
|
+
const limiter = new RateLimiter({
|
|
177
|
+
global: { maxCalls: 1000, windowMs: 60000 },
|
|
178
|
+
perSession: { maxCalls: 100, windowMs: 60000 },
|
|
179
|
+
perTool: {
|
|
180
|
+
'expensive:*': { maxCalls: 10, windowMs: 60000 },
|
|
181
|
+
},
|
|
182
|
+
});
|
|
183
|
+
|
|
184
|
+
// Check rate limit before execution
|
|
185
|
+
if (!limiter.allow(sessionId, toolName)) {
|
|
186
|
+
throw new Error('Rate limit exceeded');
|
|
187
|
+
}
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
## Related Packages
|
|
191
|
+
|
|
192
|
+
| Package | Description |
|
|
193
|
+
| ------------------------------------------- | --------------------------------- |
|
|
194
|
+
| [@enclave-vm/types](../enclavejs-types) | Type definitions and Zod schemas |
|
|
195
|
+
| [@enclave-vm/stream](../enclavejs-stream) | Streaming protocol implementation |
|
|
196
|
+
| [@enclave-vm/core](../enclave-vm) | Secure execution environment |
|
|
197
|
+
| [@enclave-vm/client](../enclavejs-client) | Browser/Node.js client SDK |
|
|
198
|
+
| [@enclave-vm/runtime](../enclavejs-runtime) | Standalone runtime worker |
|
|
199
|
+
|
|
200
|
+
## License
|
|
201
|
+
|
|
202
|
+
Apache-2.0
|