beam-protocol-sdk 0.2.2 → 0.3.0

package/src/identity.ts

@@ -0,0 +1,85 @@
+import {
+  generateKeyPairSync,
+  sign,
+  verify,
+  createPrivateKey,
+  createPublicKey,
+  randomUUID,
+  type KeyObject
+} from 'node:crypto'
+import type { BeamIdString, BeamIdentityConfig, BeamIdentityData } from './types.js'
+
+export class BeamIdentity {
+  readonly beamId: BeamIdString
+  readonly publicKeyBase64: string
+  private readonly _privateKey: KeyObject
+  private readonly _publicKey: KeyObject
+
+  private constructor(beamId: BeamIdString, privateKey: KeyObject, publicKey: KeyObject) {
+    this.beamId = beamId
+    this._privateKey = privateKey
+    this._publicKey = publicKey
+    this.publicKeyBase64 = (publicKey.export({ type: 'spki', format: 'der' }) as Buffer).toString('base64')
+  }
+
+  static generate(config: BeamIdentityConfig): BeamIdentity {
+    const { privateKey, publicKey } = generateKeyPairSync('ed25519')
+    const beamId = `${config.agentName}@${config.orgName}.beam.directory` as BeamIdString
+    return new BeamIdentity(beamId, privateKey, publicKey)
+  }
+
+  static fromData(data: BeamIdentityData): BeamIdentity {
+    const privateKey = createPrivateKey({
+      key: Buffer.from(data.privateKeyBase64, 'base64'),
+      format: 'der',
+      type: 'pkcs8'
+    })
+    const publicKey = createPublicKey({
+      key: Buffer.from(data.publicKeyBase64, 'base64'),
+      format: 'der',
+      type: 'spki'
+    })
+    return new BeamIdentity(data.beamId, privateKey, publicKey)
+  }
+
+  export(): BeamIdentityData {
+    return {
+      beamId: this.beamId,
+      publicKeyBase64: this.publicKeyBase64,
+      privateKeyBase64: (this._privateKey.export({ type: 'pkcs8', format: 'der' }) as Buffer).toString('base64')
+    }
+  }
+
+  sign(data: string): string {
+    const signature = sign(null, Buffer.from(data, 'utf8'), this._privateKey)
+    return (signature as Buffer).toString('base64')
+  }
+
+  static verify(data: string, signatureBase64: string, publicKeyBase64: string): boolean {
+    try {
+      const publicKey = createPublicKey({
+        key: Buffer.from(publicKeyBase64, 'base64'),
+        format: 'der',
+        type: 'spki'
+      })
+      return verify(
+        null,
+        Buffer.from(data, 'utf8'),
+        publicKey,
+        Buffer.from(signatureBase64, 'base64')
+      )
+    } catch {
+      return false
+    }
+  }
+
+  static parseBeamId(beamId: string): { agent: string; org: string } | null {
+    const match = beamId.match(/^([a-z0-9_-]+)@([a-z0-9_-]+)\.beam\.directory$/)
+    if (!match) return null
+    return { agent: match[1], org: match[2] }
+  }
+
+  static generateNonce(): string {
+    return randomUUID()
+  }
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export { BeamIdentity } from './identity.js'
+export { BeamDirectory, BeamDirectoryError } from './directory.js'
+export { BeamClient } from './client.js'
+export {
+  createIntentFrame,
+  createResultFrame,
+  signFrame,
+  validateIntentFrame,
+  validateResultFrame,
+  canonicalizeFrame,
+  MAX_FRAME_SIZE,
+  REPLAY_WINDOW_MS
+} from './frames.js'
+export type {
+  BeamIdString,
+  BeamIdentityConfig,
+  BeamIdentityData,
+  IntentFrame,
+  ResultFrame,
+  AgentRegistration,
+  AgentRecord,
+  DirectoryConfig,
+  BeamClientConfig,
+  AgentSearchQuery
+} from './types.js'

package/src/types.ts

@@ -0,0 +1,71 @@
+/** Beam ID format: agent@org.beam.directory */
+export type BeamIdString = `${string}@${string}.beam.directory`
+
+export interface BeamIdentityConfig {
+  agentName: string
+  orgName: string
+}
+
+export interface BeamIdentityData {
+  beamId: BeamIdString
+  publicKeyBase64: string
+  privateKeyBase64: string
+}
+
+export interface IntentFrame {
+  v: '1'
+  intent: string
+  from: BeamIdString
+  to: BeamIdString
+  payload: Record<string, unknown>
+  nonce: string
+  timestamp: string
+  signature?: string
+}
+
+export interface ResultFrame {
+  v: '1'
+  success: boolean
+  payload?: Record<string, unknown>
+  error?: string
+  errorCode?: string
+  nonce: string
+  timestamp: string
+  latency?: number
+  signature?: string
+}
+
+export interface AgentRegistration {
+  beamId: BeamIdString
+  displayName: string
+  capabilities: string[]
+  publicKey: string
+  org: string
+}
+
+export interface AgentRecord extends AgentRegistration {
+  trustScore: number
+  verified: boolean
+  createdAt: string
+  lastSeen: string
+}
+
+export interface DirectoryConfig {
+  baseUrl: string
+  apiKey?: string
+}
+
+export interface BeamClientConfig {
+  identity: BeamIdentityData
+  directoryUrl: string
+  autoReconnect?: boolean
+  onDisconnect?: () => void
+  onReconnect?: () => void
+}
+
+export interface AgentSearchQuery {
+  org?: string
+  capabilities?: string[]
+  minTrustScore?: number
+  limit?: number
+}

package/tests/client.test.ts

@@ -0,0 +1,217 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { BeamClient } from '../src/client.js'
+import { createIntentFrame, validateResultFrame } from '../src/frames.js'
+import { BeamIdentity } from '../src/identity.js'
+
+class MockWebSocket {
+  static instances: MockWebSocket[] = []
+
+  readonly OPEN = 1
+  readonly url: string
+  readyState = 0
+  sent: string[] = []
+  onopen: ((event: unknown) => void) | null = null
+  onclose: ((event: unknown) => void) | null = null
+  onerror: ((event: unknown) => void) | null = null
+  onmessage: ((event: { data: string }) => void) | null = null
+
+  constructor(url: string) {
+    this.url = url
+    MockWebSocket.instances.push(this)
+  }
+
+  send(data: string): void {
+    if (this.readyState !== this.OPEN) {
+      throw new Error('Socket not open')
+    }
+    this.sent.push(data)
+  }
+
+  close(): void {
+    this.readyState = 3
+    this.onclose?.({ type: 'close' })
+  }
+
+  emitOpen(): void {
+    this.readyState = this.OPEN
+    this.onopen?.({ type: 'open' })
+  }
+
+  emitMessage(message: unknown): void {
+    const data = typeof message === 'string' ? message : JSON.stringify(message)
+    this.onmessage?.({ data })
+  }
+}
+
+function getLastSocket(): MockWebSocket {
+  const socket = MockWebSocket.instances.at(-1)
+  if (!socket) {
+    throw new Error('Expected a mock WebSocket instance')
+  }
+  return socket
+}
+
+async function createConnectedClient() {
+  const identity = BeamIdentity.generate({ agentName: 'receiver', orgName: 'acme' })
+  const client = new BeamClient({ identity: identity.export(), directoryUrl: 'http://directory.test/' })
+  const connectPromise = client.connect()
+  const socket = getLastSocket()
+
+  await Promise.resolve()
+  socket.emitOpen()
+  socket.emitMessage({ type: 'connected', beamId: identity.beamId })
+  await connectPromise
+
+  return { client, socket, identity }
+}
+
+describe('BeamClient', () => {
+  const fetchMock = vi.fn()
+
+  beforeEach(() => {
+    MockWebSocket.instances = []
+    fetchMock.mockReset()
+    vi.stubGlobal('WebSocket', MockWebSocket as unknown as typeof WebSocket)
+    vi.stubGlobal('fetch', fetchMock)
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.unstubAllGlobals()
+  })
+
+  it('connect() opens the WebSocket and waits for the connected message', async () => {
+    const identity = BeamIdentity.generate({ agentName: 'alice', orgName: 'acme' })
+    const client = new BeamClient({ identity: identity.export(), directoryUrl: 'https://directory.test/' })
+
+    const connectPromise = client.connect()
+    const socket = getLastSocket()
+    expect(socket.url).toBe('wss://directory.test/ws?beamId=alice%40acme.beam.directory')
+
+    let resolved = false
+    void connectPromise.then(() => {
+      resolved = true
+    })
+
+    await Promise.resolve()
+    expect(resolved).toBe(false)
+
+    socket.emitOpen()
+    socket.emitMessage({ type: 'connected', beamId: identity.beamId })
+    await expect(connectPromise).resolves.toBeUndefined()
+    expect(resolved).toBe(true)
+  })
+
+  it('send() delivers intents over WebSocket and resolves matching results', async () => {
+    const { client, socket } = await createConnectedClient()
+
+    const sendPromise = client.send('target@acme.beam.directory', 'agent.ping', { message: 'hello' }, 5_000)
+
+    const outbound = JSON.parse(socket.sent[0]) as { type: string; frame: { nonce: string; intent: string } }
+    expect(outbound.type).toBe('intent')
+    expect(outbound.frame.intent).toBe('agent.ping')
+
+    socket.emitMessage({
+      type: 'result',
+      frame: {
+        v: '1',
+        success: true,
+        nonce: outbound.frame.nonce,
+        timestamp: new Date().toISOString(),
+        signature: 'not-validated-on-receive',
+        payload: { status: 'ok' },
+      },
+    })
+
+    await expect(sendPromise).resolves.toEqual(
+      expect.objectContaining({ success: true, nonce: outbound.frame.nonce, payload: { status: 'ok' } }),
+    )
+  })
+
+  it('on() invokes intent handlers and sends signed result frames', async () => {
+    const { client, socket, identity } = await createConnectedClient()
+    const sender = BeamIdentity.generate({ agentName: 'sender', orgName: 'acme' })
+    const handled = vi.fn()
+
+    client.on('task.delegate', async (frame, respond) => {
+      handled(frame)
+      respond({ success: true, payload: { accepted: true } })
+    })
+
+    const incomingFrame = createIntentFrame(
+      {
+        intent: 'task.delegate',
+        from: sender.beamId,
+        to: identity.beamId,
+        payload: { task: 'Prepare brief', priority: 'medium' },
+      },
+      sender,
+    )
+
+    socket.emitMessage({
+      type: 'intent',
+      frame: incomingFrame,
+      senderPublicKey: sender.publicKeyBase64,
+    })
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(handled).toHaveBeenCalledWith(expect.objectContaining({ intent: 'task.delegate' }))
+    const outbound = JSON.parse(socket.sent[0]) as { type: string; frame: Record<string, unknown> }
+    expect(outbound.type).toBe('result')
+    expect(outbound.frame.nonce).toBe(incomingFrame.nonce)
+    expect(validateResultFrame(outbound.frame, identity.publicKeyBase64)).toEqual({ valid: true })
+  })
+
+  it('send() falls back to HTTP when WebSocket is not connected', async () => {
+    const identity = BeamIdentity.generate({ agentName: 'alice', orgName: 'acme' })
+    const client = new BeamClient({ identity: identity.export(), directoryUrl: 'http://directory.test/' })
+
+    fetchMock.mockResolvedValue({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      json: vi.fn().mockResolvedValue({
+        v: '1',
+        success: true,
+        nonce: 'http-nonce',
+        timestamp: new Date().toISOString(),
+        signature: 'server-signature',
+      }),
+    })
+
+    const result = await client.send('target@acme.beam.directory', 'agent.ping', { message: 'fallback' })
+    expect(result).toEqual(expect.objectContaining({ success: true, nonce: 'http-nonce' }))
+    expect(fetchMock).toHaveBeenCalledWith(
+      'http://directory.test/intents',
+      expect.objectContaining({ method: 'POST', headers: { 'Content-Type': 'application/json' } }),
+    )
+    const requestBody = JSON.parse(fetchMock.mock.calls[0][1].body as string) as { intent: string; from: string; to: string }
+    expect(requestBody.intent).toBe('agent.ping')
+    expect(requestBody.from).toBe(identity.beamId)
+    expect(requestBody.to).toBe('target@acme.beam.directory')
+  })
+
+  it('send() rejects when a WebSocket intent times out', async () => {
+    vi.useFakeTimers()
+    const { client } = await createConnectedClient()
+
+    const pending = client.send('target@acme.beam.directory', 'agent.ping', { message: 'timeout' }, 250)
+    const assertion = expect(pending).rejects.toThrow('Intent "agent.ping" timed out after 250ms')
+
+    await vi.advanceTimersByTimeAsync(251)
+    await assertion
+  })
+
+  it('disconnect() closes the socket and rejects pending requests', async () => {
+    const { client, socket } = await createConnectedClient()
+
+    const pending = client.send('target@acme.beam.directory', 'agent.ping', { message: 'bye' }, 5_000)
+    expect(socket.sent).toHaveLength(1)
+
+    client.disconnect()
+
+    await expect(pending).rejects.toThrow('Client disconnected')
+    expect(socket.readyState).toBe(3)
+  })
+})

package/tests/directory.test.ts

@@ -0,0 +1,202 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { BeamDirectory, BeamDirectoryError } from '../src/directory.js'
+import type { AgentRecord } from '../src/types.js'
+
+interface MockResponseInit {
+  body?: unknown
+  ok?: boolean
+  status?: number
+  statusText?: string
+}
+
+function createResponse(init: MockResponseInit) {
+  return {
+    ok: init.ok ?? true,
+    status: init.status ?? 200,
+    statusText: init.statusText ?? 'OK',
+    json: vi.fn().mockResolvedValue(init.body),
+  }
+}
+
+describe('BeamDirectory', () => {
+  const fetchMock = vi.fn()
+  const directory = new BeamDirectory({ baseUrl: 'https://directory.example/', apiKey: 'secret-key' })
+
+  beforeEach(() => {
+    fetchMock.mockReset()
+    vi.stubGlobal('fetch', fetchMock)
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('register() posts agent registration and returns the created agent', async () => {
+    const agent: AgentRecord = {
+      beamId: 'alice@acme.beam.directory',
+      displayName: 'Alice',
+      capabilities: ['agent.ping'],
+      publicKey: 'pub-key',
+      org: 'acme',
+      trustScore: 0.7,
+      verified: true,
+      createdAt: '2026-03-08T10:00:00.000Z',
+      lastSeen: '2026-03-08T10:00:00.000Z',
+    }
+    fetchMock.mockResolvedValue(createResponse({ body: agent, status: 201 }))
+
+    const result = await directory.register({
+      beamId: agent.beamId,
+      displayName: agent.displayName,
+      capabilities: agent.capabilities,
+      publicKey: agent.publicKey,
+      org: agent.org,
+    })
+
+    expect(result).toEqual(agent)
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://directory.example/agents/register',
+      expect.objectContaining({
+        method: 'POST',
+        headers: expect.objectContaining({
+          'Content-Type': 'application/json',
+          Authorization: 'Bearer secret-key',
+        }),
+      }),
+    )
+    expect(JSON.parse(fetchMock.mock.calls[0][1].body as string)).toEqual({
+      beamId: agent.beamId,
+      displayName: agent.displayName,
+      capabilities: agent.capabilities,
+      publicKey: agent.publicKey,
+      org: agent.org,
+    })
+  })
+
+  it('register() wraps API failures in BeamDirectoryError', async () => {
+    fetchMock.mockResolvedValue(
+      createResponse({
+        ok: false,
+        status: 400,
+        statusText: 'Bad Request',
+        body: { error: 'Invalid registration' },
+      }),
+    )
+
+    await expect(
+      directory.register({
+        beamId: 'alice@acme.beam.directory',
+        displayName: 'Alice',
+        capabilities: [],
+        publicKey: 'pub-key',
+        org: 'acme',
+      }),
+    ).rejects.toEqual(expect.objectContaining<Partial<BeamDirectoryError>>({
+      name: 'BeamDirectoryError',
+      message: 'Registration failed: Invalid registration',
+      statusCode: 400,
+    }))
+  })
+
+  it('lookup() returns an agent when found', async () => {
+    const agent = {
+      beamId: 'bob@acme.beam.directory',
+      displayName: 'Bob',
+      capabilities: ['task.delegate'],
+      publicKey: 'pub-key',
+      org: 'acme',
+      trustScore: 0.6,
+      verified: false,
+      createdAt: '2026-03-08T10:00:00.000Z',
+      lastSeen: '2026-03-08T10:10:00.000Z',
+    }
+    fetchMock.mockResolvedValue(createResponse({ body: agent }))
+
+    await expect(directory.lookup(agent.beamId)).resolves.toEqual(agent)
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://directory.example/agents/bob%40acme.beam.directory',
+      expect.objectContaining({ headers: expect.any(Object) }),
+    )
+  })
+
+  it('lookup() returns null for 404 responses', async () => {
+    fetchMock.mockResolvedValue(createResponse({ ok: false, status: 404, statusText: 'Not Found' }))
+
+    await expect(directory.lookup('missing@acme.beam.directory')).resolves.toBeNull()
+  })
+
+  it('search() sends filters and normalizes snake_case records', async () => {
+    fetchMock.mockResolvedValue(
+      createResponse({
+        body: {
+          agents: [
+            {
+              beam_id: 'clara@acme.beam.directory',
+              display_name: 'Clara',
+              capabilities: ['sales.pipeline_summary', 'agent.ping'],
+              public_key: 'pub-key',
+              org: 'acme',
+              trust_score: 0.9,
+              verified: true,
+              created_at: '2026-03-01T10:00:00.000Z',
+              last_seen: '2026-03-08T09:00:00.000Z',
+            },
+          ],
+          total: 1,
+        },
+      }),
+    )
+
+    const result = await directory.search({
+      org: 'acme',
+      capabilities: ['sales.pipeline_summary', 'agent.ping'],
+      minTrustScore: 0.8,
+      limit: 5,
+    })
+
+    expect(result).toEqual([
+      {
+        beamId: 'clara@acme.beam.directory',
+        displayName: 'Clara',
+        capabilities: ['sales.pipeline_summary', 'agent.ping'],
+        publicKey: 'pub-key',
+        org: 'acme',
+        trustScore: 0.9,
+        verified: true,
+        createdAt: '2026-03-01T10:00:00.000Z',
+        lastSeen: '2026-03-08T09:00:00.000Z',
+      },
+    ])
+
+    const [url] = fetchMock.mock.calls[0] as [string]
+    const parsedUrl = new URL(url)
+    expect(parsedUrl.searchParams.get('org')).toBe('acme')
+    expect(parsedUrl.searchParams.get('capabilities')).toBe('sales.pipeline_summary,agent.ping')
+    expect(parsedUrl.searchParams.get('minTrustScore')).toBe('0.8')
+    expect(parsedUrl.searchParams.get('limit')).toBe('5')
+  })
+
+  it('heartbeat() posts to the heartbeat endpoint', async () => {
+    fetchMock.mockResolvedValue(createResponse({ body: { ok: true } }))
+
+    await expect(directory.heartbeat('alice@acme.beam.directory')).resolves.toBeUndefined()
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://directory.example/agents/alice%40acme.beam.directory/heartbeat',
+      expect.objectContaining({ method: 'POST' }),
+    )
+  })
+
+  it('heartbeat() ignores 404 responses but rejects other failures', async () => {
+    fetchMock.mockResolvedValueOnce(createResponse({ ok: false, status: 404, statusText: 'Not Found' }))
+    fetchMock.mockResolvedValueOnce(createResponse({ ok: false, status: 500, statusText: 'Server Error' }))
+
+    await expect(directory.heartbeat('missing@acme.beam.directory')).resolves.toBeUndefined()
+    await expect(directory.heartbeat('broken@acme.beam.directory')).rejects.toEqual(
+      expect.objectContaining<Partial<BeamDirectoryError>>({
+        name: 'BeamDirectoryError',
+        message: 'Heartbeat failed: Server Error',
+        statusCode: 500,
+      }),
+    )
+  })
+})