@enclave-vm/broker

Tool broker and session management for the EnclaveJS streaming runtime

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.

Features

• Session Management: Create, manage, and clean up execution sessions
• Tool Routing: Route tool calls to appropriate handlers with pattern matching
• Access Control: Fine-grained tool permissions using glob patterns
• Rate Limiting: Configurable rate limits per session
• State Management: Track session state and tool call history
• Middleware Support: Extensible middleware pipeline for tool calls

Installation

npm install @enclave-vm/broker
# or
yarn add @enclave-vm/broker
# or
pnpm add @enclave-vm/broker

Quick Start

import { Broker, createSession } from '@enclave-vm/broker';

// Create a broker with tool handlers
const broker = new Broker({
  tools: {
    'users:get': async (args) => {
      return { id: args.id, name: 'Alice' };
    },
    'users:list': async () => {
      return [
        { id: 1, name: 'Alice' },
        { id: 2, name: 'Bob' },
      ];
    },
  },
});

// Create a session
const session = await broker.createSession({
  allowedTools: ['users:*'], // Glob pattern for allowed tools
  timeout: 30000,
  maxToolCalls: 100,
});

// Handle incoming messages
session.on('tool_call', async (call) => {
  const result = await broker.executeToolCall(session.id, call);
  session.send({ type: 'tool_result', id: call.id, data: result });
});

Session Management

import { SessionManager } from '@enclave-vm/broker';

const manager = new SessionManager({
  maxConcurrentSessions: 100,
  sessionTimeout: 60000, // 1 minute
  cleanupInterval: 10000, // 10 seconds
});

// Create session
const session = await manager.create({
  userId: 'user_123',
  metadata: { source: 'api' },
});

// Get session
const retrieved = manager.get(session.id);

// List active sessions
const sessions = manager.list({ userId: 'user_123' });

// Destroy session
await manager.destroy(session.id);

Tool Routing

Route tool calls with pattern matching:

import { ToolRouter } from '@enclave-vm/broker';

const router = new ToolRouter();

// Register tools with glob patterns
router.register('db:*', {
  handler: async (name, args) => {
    const operation = name.split(':')[1];
    return await database[operation](args);
  },
  rateLimit: { maxCalls: 100, windowMs: 60000 },
});

router.register('api:external:*', {
  handler: async (name, args) => {
    return await externalApi.call(name, args);
  },
  requiresAuth: true,
});

// Execute tool call
const result = await router.execute('db:query', { sql: 'SELECT * FROM users' });

Access Control

import { AccessController } from '@enclave-vm/broker';

const access = new AccessController({
  defaultPolicy: 'deny',
  rules: [
    { pattern: 'public:*', allow: true },
    { pattern: 'admin:*', allow: false, unless: { role: 'admin' } },
    { pattern: 'user:*:read', allow: true },
    { pattern: 'user:*:write', allow: false, unless: { owner: true } },
  ],
});

// Check access
const canAccess = access.check('admin:delete', { role: 'user' }); // false
const canRead = access.check('user:profile:read', {}); // true

Middleware

Add middleware for cross-cutting concerns:

import { Broker } from '@enclave-vm/broker';

const broker = new Broker({
  middleware: [
    // Logging middleware
    async (call, next) => {
      console.log(`Tool call: ${call.name}`);
      const start = Date.now();
      const result = await next(call);
      console.log(`Completed in ${Date.now() - start}ms`);
      return result;
    },
    // Validation middleware
    async (call, next) => {
      if (!isValidArgs(call.name, call.args)) {
        throw new Error('Invalid arguments');
      }
      return next(call);
    },
  ],
  tools: {
    // ... tool handlers
  },
});

Rate Limiting

import { RateLimiter } from '@enclave-vm/broker';

const limiter = new RateLimiter({
  global: { maxCalls: 1000, windowMs: 60000 },
  perSession: { maxCalls: 100, windowMs: 60000 },
  perTool: {
    'expensive:*': { maxCalls: 10, windowMs: 60000 },
  },
});

// Check rate limit before execution
if (!limiter.allow(sessionId, toolName)) {
  throw new Error('Rate limit exceeded');
}

Related Packages

| Package | Description | | ------------------------------------------- | --------------------------------- | | @enclave-vm/types | Type definitions and Zod schemas | | @enclave-vm/stream | Streaming protocol implementation | | @enclave-vm/core | Secure execution environment | | @enclave-vm/client | Browser/Node.js client SDK | | @enclave-vm/runtime | Standalone runtime worker |

License

Apache-2.0