beam-protocol-sdk 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beam-protocol-sdk",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "TypeScript SDK for the Beam Protocol \u2014 Agent-to-Agent communication",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,25 +29,5 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "license": "Apache-2.0",
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Beam-directory/beam-protocol.git",
-    "directory": "packages/sdk-typescript"
-  },
-  "homepage": "https://beam.directory",
-  "keywords": [
-    "beam",
-    "protocol",
-    "agent",
-    "a2a",
-    "ai",
-    "communication",
-    "ed25519"
-  ]
-}
+  "license": "Apache-2.0"
+}

package/src/client.ts

@@ -0,0 +1,383 @@
+import { BeamIdentity } from './identity.js'
+import { BeamDirectory } from './directory.js'
+import { createIntentFrame, createResultFrame, signFrame, validateIntentFrame } from './frames.js'
+import type {
+  AgentRecord,
+  BeamClientConfig,
+  BeamIdString,
+  IntentFrame,
+  ResultFrame,
+} from './types.js'
+
+interface WebSocketLike {
+  readyState: number
+  readonly OPEN: number
+  send(data: string): void
+  close(): void
+  onopen: ((event: unknown) => void) | null
+  onclose: ((event: unknown) => void) | null
+  onerror: ((event: unknown) => void) | null
+  onmessage: ((event: { data: string }) => void) | null
+}
+
+type IntentHandler = (
+  frame: IntentFrame,
+  respond: (options: {
+    success: boolean
+    payload?: Record<string, unknown>
+    error?: string
+    errorCode?: string
+    latency?: number
+  }) => ResultFrame
+) => void | Promise<void>
+
+interface PendingResult {
+  resolve: (frame: ResultFrame) => void
+  reject: (err: Error) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+const INITIAL_RECONNECT_DELAY_MS = 1_000
+const MAX_RECONNECT_DELAY_MS = 30_000
+const MAX_RECONNECT_ATTEMPTS = 10
+const RECONNECT_FACTOR = 2
+
+async function openWebSocket(url: string): Promise<WebSocketLike> {
+  if (typeof globalThis.WebSocket !== 'undefined') {
+    return new (globalThis.WebSocket as new (url: string) => WebSocketLike)(url)
+  }
+  const { default: WS } = await import('ws')
+  return new WS(url) as unknown as WebSocketLike
+}
+
+export class BeamClient {
+  private readonly _identity: BeamIdentity
+  private readonly _directory: BeamDirectory
+  private readonly _directoryUrl: string
+  private readonly _autoReconnect: boolean
+  private readonly _onDisconnect?: () => void
+  private readonly _onReconnect?: () => void
+  private _ws: WebSocketLike | null = null
+  private _wsConnected = false
+  private _isConnecting = false
+  private _manualDisconnect = false
+  private _reconnectAttempts = 0
+  private _reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  private readonly _pendingResults = new Map<string, PendingResult>()
+  private readonly _intentHandlers = new Map<string, IntentHandler>()
+
+  constructor(config: BeamClientConfig) {
+    this._identity = BeamIdentity.fromData(config.identity)
+    this._directoryUrl = config.directoryUrl
+    this._directory = new BeamDirectory({ baseUrl: config.directoryUrl })
+    this._autoReconnect = config.autoReconnect ?? true
+    this._onDisconnect = config.onDisconnect
+    this._onReconnect = config.onReconnect
+  }
+
+  get beamId(): BeamIdString {
+    return this._identity.beamId
+  }
+
+  get directory(): BeamDirectory {
+    return this._directory
+  }
+
+  async register(displayName: string, capabilities: string[]): Promise<AgentRecord> {
+    const parsed = BeamIdentity.parseBeamId(this._identity.beamId)
+    if (!parsed) throw new Error('Invalid beam ID on identity')
+
+    return this._directory.register({
+      beamId: this._identity.beamId,
+      displayName,
+      capabilities,
+      publicKey: this._identity.publicKeyBase64,
+      org: parsed.org,
+    })
+  }
+
+  async connect(): Promise<void> {
+    if (this._ws && this._wsConnected) return
+    if (this._isConnecting) {
+      return new Promise<void>((resolve, reject) => {
+        const startedAt = Date.now()
+        const poll = () => {
+          if (this._wsConnected) {
+            resolve()
+            return
+          }
+          if (!this._isConnecting) {
+            reject(new Error('WebSocket connection failed'))
+            return
+          }
+          if (Date.now() - startedAt > 30_000) {
+            reject(new Error('Timed out waiting for WebSocket connection'))
+            return
+          }
+          setTimeout(poll, 50)
+        }
+        poll()
+      })
+    }
+
+    this._manualDisconnect = false
+    this._clearReconnectTimer()
+    await this._openConnection(false)
+  }
+
+  private _getWebSocketUrl(): string {
+    return this._directoryUrl
+      .replace(/^http:\/\//, 'ws://')
+      .replace(/^https:\/\//, 'wss://')
+      .replace(/\/$/, '') + `/ws?beamId=${encodeURIComponent(this._identity.beamId)}`
+  }
+
+  private async _openConnection(isReconnect: boolean): Promise<void> {
+    this._isConnecting = true
+    const wsUrl = this._getWebSocketUrl()
+
+    try {
+      const ws = await openWebSocket(wsUrl)
+      await new Promise<void>((resolve, reject) => {
+        let settled = false
+        const previousHandleMessage = this._handleMessage.bind(this)
+
+        const finishResolve = () => {
+          if (settled) return
+          settled = true
+          this._handleMessage = previousHandleMessage
+          this._isConnecting = false
+          this._wsConnected = true
+          this._reconnectAttempts = 0
+          resolve()
+        }
+
+        const finishReject = (error: Error) => {
+          if (settled) return
+          settled = true
+          this._handleMessage = previousHandleMessage
+          this._isConnecting = false
+          this._wsConnected = false
+          this._ws = null
+          reject(error)
+        }
+
+        this._ws = ws
+
+        ws.onopen = () => {
+        }
+
+        ws.onmessage = (event) => {
+          this._handleMessage(event.data)
+        }
+
+        ws.onclose = () => {
+          const wasConnected = this._wsConnected || settled
+          this._handleSocketClose(wasConnected)
+          if (!settled) {
+            finishReject(new Error('WebSocket connection closed before handshake completed'))
+          }
+        }
+
+        ws.onerror = (event) => {
+          if (!settled) {
+            finishReject(new Error(`WebSocket connection error: ${String(event)}`))
+          }
+        }
+
+        this._handleMessage = (data: string) => {
+          try {
+            const msg = JSON.parse(data) as { type: string }
+            if (msg.type === 'connected') {
+              finishResolve()
+              return
+            }
+          } catch {
+          }
+          previousHandleMessage(data)
+        }
+      })
+
+      if (isReconnect) {
+        this._onReconnect?.()
+      }
+    } catch (error) {
+      this._isConnecting = false
+      this._wsConnected = false
+      this._ws = null
+      if (isReconnect) {
+        this._scheduleReconnect()
+      }
+      throw error
+    }
+  }
+
+  private _handleSocketClose(wasConnected: boolean): void {
+    this._wsConnected = false
+    this._isConnecting = false
+    this._ws = null
+
+    for (const [nonce, pending] of this._pendingResults) {
+      clearTimeout(pending.timer)
+      pending.reject(new Error('WebSocket connection closed'))
+      this._pendingResults.delete(nonce)
+    }
+
+    if (wasConnected) {
+      this._onDisconnect?.()
+    }
+
+    if (!this._manualDisconnect && this._autoReconnect) {
+      this._scheduleReconnect()
+    }
+  }
+
+  private _scheduleReconnect(): void {
+    if (this._reconnectTimer || this._isConnecting || this._manualDisconnect || !this._autoReconnect) {
+      return
+    }
+    if (this._reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+      return
+    }
+
+    const delay = Math.min(
+      INITIAL_RECONNECT_DELAY_MS * (RECONNECT_FACTOR ** this._reconnectAttempts),
+      MAX_RECONNECT_DELAY_MS
+    )
+    this._reconnectAttempts += 1
+
+    this._reconnectTimer = setTimeout(() => {
+      this._reconnectTimer = null
+      void this._openConnection(true).catch(() => {
+        this._scheduleReconnect()
+      })
+    }, delay)
+  }
+
+  private _clearReconnectTimer(): void {
+    if (this._reconnectTimer) {
+      clearTimeout(this._reconnectTimer)
+      this._reconnectTimer = null
+    }
+  }
+
+  private _handleMessage(data: string): void {
+    let msg: Record<string, unknown>
+    try {
+      msg = JSON.parse(data) as Record<string, unknown>
+    } catch {
+      return
+    }
+
+    if (msg['type'] === 'result') {
+      const frame = msg['frame'] as ResultFrame | undefined
+      if (!frame) return
+      const pending = this._pendingResults.get(frame.nonce)
+      if (pending) {
+        clearTimeout(pending.timer)
+        this._pendingResults.delete(frame.nonce)
+        pending.resolve(frame)
+      }
+    } else if (msg['type'] === 'intent') {
+      const frame = msg['frame'] as IntentFrame | undefined
+      const senderPublicKey = msg['senderPublicKey'] as string | undefined
+      if (!frame || !senderPublicKey) return
+
+      const validation = validateIntentFrame(frame, senderPublicKey)
+      if (!validation.valid) return
+
+      const handler = this._intentHandlers.get(frame.intent) ?? this._intentHandlers.get('*')
+      if (!handler) return
+
+      const startTime = Date.now()
+      const respond = (options: {
+        success: boolean
+        payload?: Record<string, unknown>
+        error?: string
+        errorCode?: string
+        latency?: number
+      }): ResultFrame => {
+        const latency = options.latency ?? (Date.now() - startTime)
+        const resultFrame = createResultFrame(
+          { ...options, nonce: frame.nonce, latency },
+          this._identity
+        )
+        if (this._ws && this._wsConnected) {
+          this._ws.send(JSON.stringify({ type: 'result', frame: resultFrame }))
+        }
+        return resultFrame
+      }
+
+      Promise.resolve(handler(frame, respond)).catch(() => {
+      })
+    }
+  }
+
+  async send(
+    to: BeamIdString,
+    intent: string,
+    payload?: Record<string, unknown>,
+    timeoutMs = 30_000
+  ): Promise<ResultFrame> {
+    const frame = createIntentFrame({ intent, from: this._identity.beamId, to, payload }, this._identity)
+    signFrame(frame, this._identity.export().privateKeyBase64)
+
+    if (this._ws && this._wsConnected) {
+      return this._sendViaWebSocket(frame, timeoutMs)
+    }
+    return this._sendViaHttp(frame)
+  }
+
+  private _sendViaWebSocket(frame: IntentFrame, timeoutMs: number): Promise<ResultFrame> {
+    return new Promise<ResultFrame>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pendingResults.delete(frame.nonce)
+        reject(new Error(`Intent "${frame.intent}" timed out after ${timeoutMs}ms`))
+      }, timeoutMs)
+
+      this._pendingResults.set(frame.nonce, { resolve, reject, timer })
+
+      try {
+        this._ws!.send(JSON.stringify({ type: 'intent', frame }))
+      } catch (err) {
+        clearTimeout(timer)
+        this._pendingResults.delete(frame.nonce)
+        reject(err instanceof Error ? err : new Error(String(err)))
+      }
+    })
+  }
+
+  private async _sendViaHttp(frame: IntentFrame): Promise<ResultFrame> {
+    const baseUrl = this._directoryUrl.replace(/\/$/, '')
+    const res = await fetch(`${baseUrl}/intents`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(frame),
+    })
+    if (!res.ok) {
+      throw new Error(`HTTP intent delivery failed: ${res.status} ${res.statusText}`)
+    }
+    return res.json() as Promise<ResultFrame>
+  }
+
+  on(intent: string, handler: IntentHandler): this {
+    this._intentHandlers.set(intent, handler)
+    return this
+  }
+
+  disconnect(): void {
+    this._manualDisconnect = true
+    this._clearReconnectTimer()
+
+    if (this._ws) {
+      this._wsConnected = false
+      for (const [nonce, pending] of this._pendingResults) {
+        clearTimeout(pending.timer)
+        pending.reject(new Error('Client disconnected'))
+        this._pendingResults.delete(nonce)
+      }
+      this._ws.close()
+      this._ws = null
+    }
+  }
+}

package/src/directory.ts

@@ -0,0 +1,91 @@
+import type {
+  AgentRecord,
+  AgentRegistration,
+  AgentSearchQuery,
+  BeamIdString,
+  DirectoryConfig
+} from './types.js'
+
+/** Normalize snake_case server response to camelCase AgentRecord */
+function normalizeAgent(raw: Record<string, unknown>): AgentRecord {
+  return {
+    beamId: (raw.beamId ?? raw.beam_id) as AgentRecord['beamId'],
+    displayName: (raw.displayName ?? raw.display_name ?? '') as string,
+    capabilities: (raw.capabilities ?? []) as string[],
+    publicKey: (raw.publicKey ?? raw.public_key ?? '') as string,
+    org: (raw.org ?? '') as string,
+    trustScore: (raw.trustScore ?? raw.trust_score ?? 0) as number,
+    verified: (raw.verified ?? false) as boolean,
+    createdAt: (raw.createdAt ?? raw.created_at ?? '') as string,
+    lastSeen: (raw.lastSeen ?? raw.last_seen ?? '') as string,
+  }
+}
+
+export class BeamDirectoryError extends Error {
+  constructor(
+    message: string,
+    public readonly statusCode: number
+  ) {
+    super(message)
+    this.name = 'BeamDirectoryError'
+  }
+}
+
+export class BeamDirectory {
+  private readonly baseUrl: string
+  private readonly headers: Record<string, string>
+
+  constructor(config: DirectoryConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, '')
+    this.headers = {
+      'Content-Type': 'application/json',
+      ...(config.apiKey && { Authorization: `Bearer ${config.apiKey}` })
+    }
+  }
+
+  async register(registration: AgentRegistration): Promise<AgentRecord> {
+    const res = await fetch(`${this.baseUrl}/agents/register`, {
+      method: 'POST',
+      headers: this.headers,
+      body: JSON.stringify(registration)
+    })
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({ error: res.statusText })) as { error: string }
+      throw new BeamDirectoryError(`Registration failed: ${body.error}`, res.status)
+    }
+    return res.json() as Promise<AgentRecord>
+  }
+
+  async lookup(beamId: BeamIdString): Promise<AgentRecord | null> {
+    const res = await fetch(`${this.baseUrl}/agents/${encodeURIComponent(beamId)}`, {
+      headers: this.headers
+    })
+    if (res.status === 404) return null
+    if (!res.ok) throw new BeamDirectoryError(`Lookup failed: ${res.statusText}`, res.status)
+    return res.json() as Promise<AgentRecord>
+  }
+
+  async search(query: AgentSearchQuery): Promise<AgentRecord[]> {
+    const params = new URLSearchParams()
+    if (query.org) params.set('org', query.org)
+    if (query.capabilities?.length) params.set('capabilities', query.capabilities.join(','))
+    if (query.minTrustScore !== undefined) params.set('minTrustScore', String(query.minTrustScore))
+    if (query.limit !== undefined) params.set('limit', String(query.limit))
+
+    const res = await fetch(`${this.baseUrl}/agents/search?${params}`, { headers: this.headers })
+    if (!res.ok) throw new BeamDirectoryError(`Search failed: ${res.statusText}`, res.status)
+    const body = await res.json() as { agents?: Record<string, unknown>[] } | Record<string, unknown>[]
+    const raw = Array.isArray(body) ? body : (body?.agents ?? [])
+    return raw.map(normalizeAgent)
+  }
+
+  async heartbeat(beamId: BeamIdString): Promise<void> {
+    const res = await fetch(`${this.baseUrl}/agents/${encodeURIComponent(beamId)}/heartbeat`, {
+      method: 'POST',
+      headers: this.headers
+    })
+    if (!res.ok && res.status !== 404) {
+      throw new BeamDirectoryError(`Heartbeat failed: ${res.statusText}`, res.status)
+    }
+  }
+}

package/src/frames.ts

@@ -0,0 +1,161 @@
+import { randomUUID, createPrivateKey, sign } from 'node:crypto'
+import type { IntentFrame, ResultFrame, BeamIdString } from './types.js'
+import { BeamIdentity } from './identity.js'
+
+export const MAX_FRAME_SIZE = 4 * 1024  // 4KB hard limit
+export const REPLAY_WINDOW_MS = 5 * 60 * 1000  // 5 minutes
+
+export function createIntentFrame(
+  options: {
+    intent: string
+    from: BeamIdString
+    to: BeamIdString
+    payload?: Record<string, unknown>
+  },
+  identity: BeamIdentity
+): IntentFrame {
+  const frame: IntentFrame = {
+    v: '1',
+    intent: options.intent,
+    from: options.from,
+    to: options.to,
+    payload: options.payload ?? {},
+    nonce: randomUUID(),
+    timestamp: new Date().toISOString()
+  }
+  return signFrame(frame, identity.export().privateKeyBase64)
+}
+
+export function signFrame(frame: IntentFrame, privateKeyBase64: string): IntentFrame {
+  const signedPayload = JSON.stringify({
+    type: 'intent',
+    from: frame.from,
+    to: frame.to,
+    intent: frame.intent,
+    payload: frame.payload,
+    timestamp: frame.timestamp,
+    nonce: frame.nonce,
+  })
+  const privateKey = createPrivateKey({
+    key: Buffer.from(privateKeyBase64, 'base64'),
+    format: 'der',
+    type: 'pkcs8',
+  })
+  frame.signature = sign(null, Buffer.from(signedPayload, 'utf8'), privateKey).toString('base64')
+  return frame
+}
+
+export function createResultFrame(
+  options: {
+    nonce: string
+    success: boolean
+    payload?: Record<string, unknown>
+    error?: string
+    errorCode?: string
+    latency?: number
+  },
+  identity: BeamIdentity
+): ResultFrame {
+  const frame: ResultFrame = {
+    v: '1',
+    success: options.success,
+    nonce: options.nonce,
+    timestamp: new Date().toISOString(),
+    ...(options.payload !== undefined && { payload: options.payload }),
+    ...(options.error !== undefined && { error: options.error }),
+    ...(options.errorCode !== undefined && { errorCode: options.errorCode }),
+    ...(options.latency !== undefined && { latency: options.latency })
+  }
+  frame.signature = identity.sign(canonicalizeFrame(frame as unknown as Record<string, unknown>))
+  return frame
+}
+
+export function validateIntentFrame(
+  frame: unknown,
+  senderPublicKey: string
+): { valid: boolean; error?: string } {
+  if (!frame || typeof frame !== 'object') {
+    return { valid: false, error: 'Frame must be an object' }
+  }
+  const f = frame as Record<string, unknown>
+
+  if (f['v'] !== '1') return { valid: false, error: 'Invalid protocol version' }
+  if (typeof f['intent'] !== 'string' || !f['intent']) return { valid: false, error: 'Missing or empty intent' }
+  if (typeof f['from'] !== 'string' || !BeamIdentity.parseBeamId(f['from'])) {
+    return { valid: false, error: 'Invalid from Beam ID' }
+  }
+  if (typeof f['to'] !== 'string' || !BeamIdentity.parseBeamId(f['to'])) {
+    return { valid: false, error: 'Invalid to Beam ID' }
+  }
+  if (typeof f['nonce'] !== 'string' || !f['nonce']) return { valid: false, error: 'Missing nonce' }
+  if (typeof f['timestamp'] !== 'string') return { valid: false, error: 'Missing timestamp' }
+  if (!f['payload'] || typeof f['payload'] !== 'object' || Array.isArray(f['payload'])) {
+    return { valid: false, error: 'Payload must be an object' }
+  }
+
+  const size = Buffer.byteLength(JSON.stringify(frame), 'utf8')
+  if (size > MAX_FRAME_SIZE) {
+    return { valid: false, error: `Frame size ${size} exceeds limit of ${MAX_FRAME_SIZE} bytes` }
+  }
+
+  const frameTime = new Date(f['timestamp'] as string).getTime()
+  if (isNaN(frameTime)) return { valid: false, error: 'Invalid timestamp format' }
+  if (Math.abs(Date.now() - frameTime) > REPLAY_WINDOW_MS) {
+    return { valid: false, error: 'Frame timestamp outside replay window (±5 minutes)' }
+  }
+
+  if (typeof f['signature'] !== 'string') return { valid: false, error: 'Missing signature' }
+  const signedPayload = JSON.stringify({
+    type: 'intent',
+    from: f['from'],
+    to: f['to'],
+    intent: f['intent'],
+    payload: f['payload'],
+    timestamp: f['timestamp'],
+    nonce: f['nonce'],
+  })
+  if (!BeamIdentity.verify(signedPayload, f['signature'] as string, senderPublicKey)) {
+    return { valid: false, error: 'Signature verification failed' }
+  }
+
+  return { valid: true }
+}
+
+export function validateResultFrame(
+  frame: unknown,
+  senderPublicKey: string
+): { valid: boolean; error?: string } {
+  if (!frame || typeof frame !== 'object') {
+    return { valid: false, error: 'Frame must be an object' }
+  }
+  const f = frame as Record<string, unknown>
+
+  if (f['v'] !== '1') return { valid: false, error: 'Invalid protocol version' }
+  if (typeof f['success'] !== 'boolean') return { valid: false, error: 'Missing success boolean' }
+  if (typeof f['nonce'] !== 'string' || !f['nonce']) return { valid: false, error: 'Missing nonce' }
+  if (typeof f['timestamp'] !== 'string') return { valid: false, error: 'Missing timestamp' }
+  if (typeof f['signature'] !== 'string') return { valid: false, error: 'Missing signature' }
+
+  const { signature, ...unsigned } = f
+  if (!BeamIdentity.verify(canonicalizeFrame(unsigned), signature as string, senderPublicKey)) {
+    return { valid: false, error: 'Signature verification failed' }
+  }
+
+  return { valid: true }
+}
+
+export function canonicalizeFrame(frame: Record<string, unknown>): string {
+  return JSON.stringify(deepSortKeys(frame))
+}
+
+function deepSortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(deepSortKeys)
+  if (value !== null && typeof value === 'object') {
+    const sorted: Record<string, unknown> = {}
+    for (const key of Object.keys(value as object).sort()) {
+      sorted[key] = deepSortKeys((value as Record<string, unknown>)[key])
+    }
+    return sorted
+  }
+  return value
+}