@7h3/protocol 0.1.2 → 0.4.0

package/src/conformance.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest'
+import {
+  canonicalizeEnvelope,
+  signCanonicalPayloadEd25519,
+  signCanonicalPayloadHmac,
+  signEnvelopeEd25519,
+  signEnvelopeHmac,
+  verifyCanonicalPayloadEd25519,
+  verifyCanonicalPayloadHmac,
+  verifyEnvelopeEd25519,
+  verifyEnvelopeHmac,
+} from './protocol'
+import { InMemoryReplayCache } from './protocolReplay'
+import { decodeEnvelope, encodeEnvelope, receiveEnvelope } from './protocolTransport'
+import { decodeEnvelopeBinary, encodeEnvelopeBinary } from './protocolBinary'
+import { AIP_V01_CONFORMANCE_VECTORS, AIP_V01_ED25519_CONFORMANCE_VECTORS } from './conformanceVectors'
+
+describe('AIP v0.1 conformance vectors', () => {
+  for (const vector of AIP_V01_CONFORMANCE_VECTORS) {
+    it(`${vector.id}: canonicalization and signatures match fixture`, async () => {
+      const canonical = canonicalizeEnvelope(vector.envelope)
+      expect(canonical).toBe(vector.canonical)
+
+      const signature = await signCanonicalPayloadHmac(canonical, vector.secret)
+      expect(signature).toBe(vector.signature)
+
+      const signed = await signEnvelopeHmac(vector.envelope, vector.secret, vector.keyId)
+      expect(signed.signature).toEqual({
+        alg: 'HS256',
+        keyId: vector.keyId,
+        value: vector.signature,
+      })
+
+      expect(await verifyCanonicalPayloadHmac(canonical, vector.signature, vector.secret)).toBe(true)
+      expect(await verifyEnvelopeHmac(signed, vector.secret)).toBe(true)
+      expect(await verifyEnvelopeHmac(signed, `${vector.secret}-wrong`)).toBe(false)
+    })
+
+    it(`${vector.id}: transport roundtrip and replay/ttl checks`, async () => {
+      const signed = await signEnvelopeHmac(vector.envelope, vector.secret, vector.keyId)
+      const encodedCompact = encodeEnvelope(signed, 'compact')
+      const decoded = decodeEnvelope(encodedCompact)
+      expect(decoded.ok).toBe(true)
+      expect(decoded.envelope).toEqual(signed)
+
+      const binary = encodeEnvelopeBinary(signed)
+      const decodedBinary = decodeEnvelopeBinary(binary)
+      expect(decodedBinary.ok).toBe(true)
+      expect(decodedBinary.envelope).toEqual(signed)
+
+      const replayCache = new InMemoryReplayCache()
+      const first = await receiveEnvelope(encodedCompact, {
+        nowMs: vector.envelope.header.timestampMs + 1,
+        replayCache,
+        secretResolver: async () => vector.secret,
+      })
+      expect(first.ok).toBe(true)
+
+      const replay = await receiveEnvelope(encodedCompact, {
+        nowMs: vector.envelope.header.timestampMs + 2,
+        replayCache,
+        secretResolver: async () => vector.secret,
+      })
+      expect(replay.ok).toBe(false)
+      expect(replay.diagnostics.some((d) => d.message.includes('Replay detected'))).toBe(true)
+
+      const expired = await receiveEnvelope(encodedCompact, {
+        nowMs: vector.envelope.header.timestampMs + vector.envelope.header.ttlMs + 1,
+        replayCache: new InMemoryReplayCache(),
+        secretResolver: async () => vector.secret,
+      })
+      expect(expired.ok).toBe(false)
+      expect(expired.diagnostics.some((d) => d.message === 'Message TTL expired')).toBe(true)
+    })
+  }
+
+  for (const vector of AIP_V01_ED25519_CONFORMANCE_VECTORS) {
+    it(`${vector.id}: canonicalization and Ed25519 signatures match fixture`, async () => {
+      const canonical = canonicalizeEnvelope(vector.envelope)
+      expect(canonical).toBe(vector.canonical)
+
+      const signature = await signCanonicalPayloadEd25519(canonical, vector.privateKey)
+      expect(signature).toBe(vector.signature)
+
+      const signed = await signEnvelopeEd25519(vector.envelope, vector.privateKey, vector.keyId)
+      expect(signed.signature).toEqual({
+        alg: 'ED25519',
+        keyId: vector.keyId,
+        value: vector.signature,
+      })
+
+      expect(await verifyCanonicalPayloadEd25519(canonical, vector.signature, vector.publicKey)).toBe(true)
+      expect(await verifyEnvelopeEd25519(signed, vector.publicKey)).toBe(true)
+
+      const tampered = {
+        ...signed,
+        body: {
+          ...signed.body,
+          content: `${signed.body.content}:tampered`,
+        },
+      }
+      expect(await verifyEnvelopeEd25519(tampered, vector.publicKey)).toBe(false)
+    })
+
+    it(`${vector.id}: transport verify via signatureResolver`, async () => {
+      const signed = await signEnvelopeEd25519(vector.envelope, vector.privateKey, vector.keyId)
+      const encodedCompact = encodeEnvelope(signed, 'compact')
+      const decoded = decodeEnvelope(encodedCompact)
+      expect(decoded.ok).toBe(true)
+      expect(decoded.envelope).toEqual(signed)
+
+      const binary = encodeEnvelopeBinary(signed)
+      const decodedBinary = decodeEnvelopeBinary(binary)
+      expect(decodedBinary.ok).toBe(true)
+      expect(decodedBinary.envelope).toEqual(signed)
+
+      const first = await receiveEnvelope(encodedCompact, {
+        nowMs: vector.envelope.header.timestampMs + 1,
+        replayCache: new InMemoryReplayCache(),
+        signatureResolver: async (signature, sender) =>
+          signature.alg === 'ED25519' && signature.keyId === vector.keyId && sender === vector.envelope.header.sender
+            ? { alg: 'ED25519', publicKey: vector.publicKey }
+            : undefined,
+      })
+      expect(first.ok).toBe(true)
+
+      const expired = await receiveEnvelope(encodedCompact, {
+        nowMs: vector.envelope.header.timestampMs + vector.envelope.header.ttlMs + 1,
+        replayCache: new InMemoryReplayCache(),
+        signatureResolver: async () => ({ alg: 'ED25519', publicKey: vector.publicKey }),
+      })
+      expect(expired.ok).toBe(false)
+      expect(expired.diagnostics.some((d) => d.message === 'Message TTL expired')).toBe(true)
+    })
+  }
+})

package/src/conformanceVectors.ts

@@ -0,0 +1,99 @@
+import type { ProtocolEnvelope } from './protocol'
+
+export interface ConformanceVector {
+  id: string
+  secret: string
+  keyId: string
+  envelope: Omit<ProtocolEnvelope, 'signature'>
+  canonical: string
+  signature: string
+}
+
+export interface Ed25519ConformanceVector {
+  id: string
+  keyId: string
+  publicKey: string
+  privateKey: string
+  envelope: Omit<ProtocolEnvelope, 'signature'>
+  canonical: string
+  signature: string
+}
+
+export const AIP_V01_CONFORMANCE_VECTORS: ConformanceVector[] = [
+  {
+    id: 'task-with-capability-and-recipient',
+    secret: 'vector-secret-1',
+    keyId: 'vector-key-1',
+    envelope: {
+      header: {
+        version: '7h3/0.1',
+        messageId: 'vec-1',
+        timestampMs: 1712500000000,
+        ttlMs: 60000,
+        sender: 'agent.alpha',
+        recipient: 'agent.beta',
+        nonce: 'nonce-vec-1',
+      },
+      body: {
+        intent: 'TASK',
+        content: 'route:alpha->beta',
+        capability: 'task.plan',
+        correlationId: 'corr-1',
+      },
+    },
+    canonical:
+      '{"body":{"capability":"task.plan","content":"route:alpha->beta","correlationId":"corr-1","intent":"TASK"},"header":{"messageId":"vec-1","nonce":"nonce-vec-1","recipient":"agent.beta","sender":"agent.alpha","timestampMs":1712500000000,"ttlMs":60000,"version":"7h3/0.1"}}',
+    signature: 'bZP1N1f4w4RGSKw6pfdcA6dQjvpv9nIHAQCttjNCZyI',
+  },
+  {
+    id: 'result-with-minimal-fields',
+    secret: 'vector-secret-2',
+    keyId: 'vector-key-2',
+    envelope: {
+      header: {
+        version: '7h3/0.1',
+        messageId: 'vec-2',
+        timestampMs: 1712500005000,
+        ttlMs: 30000,
+        sender: 'memory.agent',
+        nonce: 'nonce-vec-2',
+      },
+      body: {
+        intent: 'RESULT',
+        content: 'memory:ok',
+      },
+    },
+    canonical:
+      '{"body":{"content":"memory:ok","intent":"RESULT"},"header":{"messageId":"vec-2","nonce":"nonce-vec-2","sender":"memory.agent","timestampMs":1712500005000,"ttlMs":30000,"version":"7h3/0.1"}}',
+    signature: '_soWM4GZS8qWZDWyXEeXPaQp7Diyp2SQua9mKy2q0BQ',
+  },
+]
+
+export const AIP_V01_ED25519_CONFORMANCE_VECTORS: Ed25519ConformanceVector[] = [
+  {
+    id: 'task-ed25519-with-recipient',
+    keyId: 'ed-vector-key-1',
+    publicKey: 'MCowBQYDK2VwAyEA-mUFiTQtcKN4nnD19V_-Wyy4q19OivnAutRUPhOcC78',
+    privateKey: 'MC4CAQAwBQYDK2VwBCIEICheZbQGuDVb6hezIlcs0QnCHGxz6IhiLkC9M0qr8OOZ',
+    envelope: {
+      header: {
+        version: '7h3/0.1',
+        messageId: 'vec-ed-1',
+        timestampMs: 1712500010000,
+        ttlMs: 45000,
+        sender: 'agent.ed',
+        recipient: 'agent.verify',
+        nonce: 'nonce-ed-1',
+      },
+      body: {
+        intent: 'TASK',
+        content: 'route:ed25519',
+        capability: 'task.sign',
+        correlationId: 'corr-ed-1',
+      },
+    },
+    canonical:
+      '{"body":{"capability":"task.sign","content":"route:ed25519","correlationId":"corr-ed-1","intent":"TASK"},"header":{"messageId":"vec-ed-1","nonce":"nonce-ed-1","recipient":"agent.verify","sender":"agent.ed","timestampMs":1712500010000,"ttlMs":45000,"version":"7h3/0.1"}}',
+    signature: 'AAWu-6pp7NQZ-NtWKrgREWlMBx-kMZZzZ5dIiBqOdT-zdr-u4HtS6upE79yX7UUNPYUfyKs7lfssi0EeOvIxAA',
+  },
+]

package/src/frameworkAdapters.test.ts

@@ -0,0 +1,290 @@
+import { describe, expect, it } from 'vitest'
+import { createAipAgentAdapter } from './agentAdapter'
+import type { WireEnvelope } from './protocolTransport'
+import {
+  createRawTaskFromJsonRpc,
+  createRawTaskFromLangChain,
+  createRawTaskFromLlamaIndex,
+  toJsonRpcResponse,
+  toLangChainMessage,
+  toLlamaIndexMessage,
+  type JsonRpcRequestLike,
+} from './frameworkAdapters'
+
+describe('framework adapters', () => {
+  const secret = 'framework-adapter-secret'
+
+  it('maps LangChain-style message into signed TASK flow', async () => {
+    const orchestrator = createAipAgentAdapter({
+      agentId: 'agent.orchestrator',
+      outboundSecret: secret,
+      sharedSecrets: { 'agent.worker': secret },
+      wireFormat: 'compact',
+    })
+
+    const worker = createAipAgentAdapter({
+      agentId: 'agent.worker',
+      outboundSecret: secret,
+      sharedSecrets: { 'agent.orchestrator': secret },
+      wireFormat: 'compact',
+      onTask: async (envelope) => ({
+        intent: 'RESULT',
+        content: `done:${envelope.body.content}`,
+        capability: envelope.body.capability,
+      }),
+    })
+
+    const raw = await createRawTaskFromLangChain(
+      orchestrator,
+      { content: 'plan travel graph', name: 'human' },
+      { recipient: 'agent.worker', capability: 'task.plan' },
+    )
+
+    let rawResponse: WireEnvelope = ''
+    await worker.handleRaw(raw, async (responseRaw) => {
+      rawResponse = responseRaw
+    })
+
+    const verified = await orchestrator.receiveRaw(rawResponse)
+    expect(verified.ok).toBe(true)
+    expect(verified.received).not.toBeNull()
+    const langchainMsg = toLangChainMessage(verified.received!)
+    expect(langchainMsg.content).toContain('done:plan travel graph')
+    expect(langchainMsg.additionalKwargs?.capability).toBe('task.plan')
+  })
+
+  it('maps LlamaIndex-style message into signed TASK flow', async () => {
+    const orchestrator = createAipAgentAdapter({
+      agentId: 'agent.orchestrator',
+      outboundSecret: secret,
+      sharedSecrets: { 'agent.worker': secret },
+      wireFormat: 'compact',
+    })
+
+    const worker = createAipAgentAdapter({
+      agentId: 'agent.worker',
+      outboundSecret: secret,
+      sharedSecrets: { 'agent.orchestrator': secret },
+      wireFormat: 'compact',
+      onTask: async (envelope) => ({
+        intent: 'RESULT',
+        content: envelope.body.content.toUpperCase(),
+        capability: envelope.body.capability,
+      }),
+    })
+
+    const raw = await createRawTaskFromLlamaIndex(
+      orchestrator,
+      { role: 'user', content: 'summarize logs' },
+      { recipient: 'agent.worker', capability: 'task.summarize' },
+    )
+
+    let rawResponse: WireEnvelope = ''
+    await worker.handleRaw(raw, async (responseRaw) => {
+      rawResponse = responseRaw
+    })
+
+    const verified = await orchestrator.receiveRaw(rawResponse)
+    expect(verified.ok).toBe(true)
+    expect(verified.received).not.toBeNull()
+    const llamaMsg = toLlamaIndexMessage(verified.received!)
+    expect(llamaMsg.role).toBe('assistant')
+    expect(llamaMsg.content).toBe('SUMMARIZE LOGS')
+    expect(llamaMsg.additionalKwargs?.capability).toBe('task.summarize')
+  })
+
+  it('maps JSON-RPC request/response through TASK and RESULT envelopes', async () => {
+    const orchestrator = createAipAgentAdapter({
+      agentId: 'agent.gateway',
+      outboundSecret: secret,
+      sharedSecrets: { 'agent.mcp-worker': secret },
+      wireFormat: 'compact',
+    })
+
+    const worker = createAipAgentAdapter({
+      agentId: 'agent.mcp-worker',
+      outboundSecret: secret,
+      sharedSecrets: { 'agent.gateway': secret },
+      wireFormat: 'compact',
+      onTask: async (envelope) => ({
+        intent: 'RESULT',
+        content: JSON.stringify({ ok: true, receivedCapability: envelope.body.capability }),
+        capability: envelope.body.capability,
+      }),
+    })
+
+    const req: JsonRpcRequestLike = {
+      jsonrpc: '2.0',
+      id: 7,
+      method: 'tools/call',
+      params: { name: 'planner', input: 'optimize route' },
+    }
+
+    const raw = await createRawTaskFromJsonRpc(orchestrator, req, { recipient: 'agent.mcp-worker' })
+
+    let rawResponse: WireEnvelope = ''
+    await worker.handleRaw(raw, async (responseRaw) => {
+      rawResponse = responseRaw
+    })
+
+    const verified = await orchestrator.receiveRaw(rawResponse)
+    expect(verified.ok).toBe(true)
+    expect(verified.received).not.toBeNull()
+
+    const mcpResponse = toJsonRpcResponse(verified.received!, req.id)
+    expect(mcpResponse.jsonrpc).toBe('2.0')
+    expect(mcpResponse.id).toBe(7)
+    expect(mcpResponse.error).toBeUndefined()
+    expect(mcpResponse.result).toEqual({ ok: true, receivedCapability: 'mcp.tools/call' })
+  })
+
+  it('rejects disallowed JSON-RPC methods before sending', async () => {
+    const orchestrator = createAipAgentAdapter({
+      agentId: 'agent.gateway',
+      outboundSecret: secret,
+      sharedSecrets: { 'agent.mcp-worker': secret },
+      wireFormat: 'compact',
+    })
+
+    const req: JsonRpcRequestLike = {
+      jsonrpc: '2.0',
+      id: 'abc',
+      method: 'tools/secret-call',
+      params: {},
+    }
+
+    await expect(
+      createRawTaskFromJsonRpc(orchestrator, req, {
+        recipient: 'agent.mcp-worker',
+        allowedMethods: ['tools/call', 'resources/read'],
+      }),
+    ).rejects.toThrow("JSON-RPC method 'tools/secret-call' is not allowed")
+  })
+
+  it('rejects unauthorized JSON-RPC methods before sending', async () => {
+    const orchestrator = createAipAgentAdapter({
+      agentId: 'agent.gateway',
+      outboundSecret: secret,
+      sharedSecrets: { 'agent.mcp-worker': secret },
+      wireFormat: 'compact',
+    })
+
+    const req: JsonRpcRequestLike = {
+      jsonrpc: '2.0',
+      id: 'auth-1',
+      method: 'tools/call',
+      params: { name: 'planner' },
+    }
+
+    await expect(
+      createRawTaskFromJsonRpc(orchestrator, req, {
+        recipient: 'agent.mcp-worker',
+        authorizeMethod: async () => false,
+      }),
+    ).rejects.toThrow("JSON-RPC method 'tools/call' is not authorized")
+  })
+
+  it('rejects rate-limited JSON-RPC methods before sending', async () => {
+    const orchestrator = createAipAgentAdapter({
+      agentId: 'agent.gateway',
+      outboundSecret: secret,
+      sharedSecrets: { 'agent.mcp-worker': secret },
+      wireFormat: 'compact',
+    })
+
+    const req: JsonRpcRequestLike = {
+      jsonrpc: '2.0',
+      id: 'rate-1',
+      method: 'tools/call',
+      params: { name: 'planner' },
+    }
+
+    await expect(
+      createRawTaskFromJsonRpc(orchestrator, req, {
+        recipient: 'agent.mcp-worker',
+        rateLimiter: {
+          consume: async () => false,
+        },
+      }),
+    ).rejects.toThrow("JSON-RPC method 'tools/call' is rate-limited")
+  })
+
+  it('passes capability context into policy hooks', async () => {
+    const orchestrator = createAipAgentAdapter({
+      agentId: 'agent.gateway',
+      outboundSecret: secret,
+      sharedSecrets: { 'agent.mcp-worker': secret },
+      wireFormat: 'compact',
+    })
+
+    const req: JsonRpcRequestLike = {
+      jsonrpc: '2.0',
+      id: 'ctx-1',
+      method: 'tools/call',
+      params: { name: 'planner' },
+    }
+
+    let authCapability = ''
+    let rateKey = ''
+    const raw = await createRawTaskFromJsonRpc(orchestrator, req, {
+      recipient: 'agent.mcp-worker',
+      methodToCapability: (method) => `custom.${method}`,
+      authorizeMethod: async (_request, context) => {
+        authCapability = context.capability
+        return true
+      },
+      rateLimitKey: (_request, context) => `${context.capability}:${context.correlationId}`,
+      rateLimiter: {
+        consume: async (key) => {
+          rateKey = key
+          return true
+        },
+      },
+    })
+
+    expect(raw.length).toBeGreaterThan(0)
+    expect(authCapability).toBe('custom.tools/call')
+    expect(rateKey).toBe('custom.tools/call:ctx-1')
+  })
+
+  it('emits policy events for allow and deny decisions', async () => {
+    const orchestrator = createAipAgentAdapter({
+      agentId: 'agent.gateway',
+      outboundSecret: secret,
+      sharedSecrets: { 'agent.mcp-worker': secret },
+      wireFormat: 'compact',
+    })
+
+    const req: JsonRpcRequestLike = {
+      jsonrpc: '2.0',
+      id: 'evt-1',
+      method: 'tools/call',
+      params: {},
+    }
+
+    const events: string[] = []
+    await createRawTaskFromJsonRpc(orchestrator, req, {
+      recipient: 'agent.mcp-worker',
+      allowedMethods: ['tools/call'],
+      authorizeMethod: async () => true,
+      onPolicyEvent: async (event) => {
+        events.push(`${event.stage}:${event.decision}`)
+      },
+    })
+
+    expect(events).toContain('allowlist:allow')
+    expect(events).toContain('authorize:allow')
+
+    await expect(
+      createRawTaskFromJsonRpc(orchestrator, { ...req, id: 'evt-2', method: 'resources/read' }, {
+        recipient: 'agent.mcp-worker',
+        allowedMethods: ['tools/call'],
+        onPolicyEvent: async (event) => {
+          events.push(`${event.stage}:${event.decision}`)
+        },
+      }),
+    ).rejects.toThrow("JSON-RPC method 'resources/read' is not allowed")
+
+    expect(events).toContain('allowlist:deny')
+  })
+})