@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 ADDED
@@ -0,0 +1,202 @@
1
+ # @enclave-vm/broker
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
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