@7h3/protocol 0.1.2 → 0.5.0

package/src/protocolBinary.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it } from 'vitest'
+import { createEnvelope, signEnvelopeEd25519, signEnvelopeHmac } from './protocol'
+import { DEFAULT_MAX_BINARY_ENVELOPE_BYTES, decodeEnvelopeBinary, encodeEnvelopeBinary } from './protocolBinary'
+
+function stringFieldOffset(raw: Uint8Array, fieldIndex: number): { lengthOffset: number; valueOffset: number; length: number } {
+  let offset = 4 + 1 + 1 + 8 + 4
+  const view = new DataView(raw.buffer, raw.byteOffset, raw.byteLength)
+  for (let index = 0; index <= fieldIndex; index += 1) {
+    const lengthOffset = offset
+    const length = view.getUint32(lengthOffset, false)
+    const valueOffset = lengthOffset + 4
+    if (index === fieldIndex) return { lengthOffset, valueOffset, length }
+    offset = valueOffset + length
+  }
+  throw new Error(`missing string field ${fieldIndex}`)
+}
+
+function replaceAscii(raw: Uint8Array, fieldIndex: number, value: string): Uint8Array {
+  const copy = raw.slice()
+  const field = stringFieldOffset(copy, fieldIndex)
+  if (value.length !== field.length) throw new Error('replacement must preserve encoded length')
+  for (let index = 0; index < value.length; index += 1) {
+    copy[field.valueOffset + index] = value.charCodeAt(index)
+  }
+  return copy
+}
+
+describe('AIP binary wire codec', () => {
+  it('roundtrips HS256 signed envelope', async () => {
+    const signed = await signEnvelopeHmac(
+      createEnvelope({
+        sender: 'agent.alpha',
+        recipient: 'agent.beta',
+        intent: 'TASK',
+        content: 'route:binary',
+        capability: 'task.plan',
+        correlationId: 'corr-b1',
+        messageId: 'bin-1',
+        nonce: 'nb1',
+        nowMs: 1000,
+        ttlMs: 60_000,
+      }),
+      'shared-secret',
+      'k1',
+    )
+
+    const raw = encodeEnvelopeBinary(signed)
+    const decoded = decodeEnvelopeBinary(raw)
+    expect(decoded.ok).toBe(true)
+    expect(decoded.envelope).toEqual(signed)
+  })
+
+  it('roundtrips ED25519 signed envelope', async () => {
+    const privateKey = 'MC4CAQAwBQYDK2VwBCIEICheZbQGuDVb6hezIlcs0QnCHGxz6IhiLkC9M0qr8OOZ'
+    const signed = await signEnvelopeEd25519(
+      createEnvelope({
+        sender: 'agent.ed',
+        recipient: 'agent.verify',
+        intent: 'TASK',
+        content: 'route:ed25519-binary',
+        capability: 'task.sign',
+        correlationId: 'corr-ed-b1',
+        messageId: 'bin-ed-1',
+        nonce: 'n-ed-b1',
+        nowMs: 1000,
+        ttlMs: 45_000,
+      }),
+      privateKey,
+      'ed-k1',
+    )
+
+    const raw = encodeEnvelopeBinary(signed)
+    const decoded = decodeEnvelopeBinary(raw)
+    expect(decoded.ok).toBe(true)
+    expect(decoded.envelope).toEqual(signed)
+  })
+
+  it('rejects bad magic and trailing bytes', async () => {
+    const signed = await signEnvelopeHmac(
+      createEnvelope({
+        sender: 'agent.alpha',
+        intent: 'PING',
+        content: 'x',
+        messageId: 'bin-2',
+        nonce: 'nb2',
+        nowMs: 1000,
+        ttlMs: 60_000,
+      }),
+      'shared-secret',
+      'k1',
+    )
+
+    const raw = encodeEnvelopeBinary(signed)
+    const badMagic = raw.slice()
+    badMagic[0] = 0
+    const decodedMagic = decodeEnvelopeBinary(badMagic)
+    expect(decodedMagic.ok).toBe(false)
+    expect(decodedMagic.diagnostics.some((d) => d.message.includes('magic'))).toBe(true)
+
+    const trailing = new Uint8Array(raw.byteLength + 1)
+    trailing.set(raw)
+    trailing[raw.byteLength] = 1
+    const decodedTrailing = decodeEnvelopeBinary(trailing)
+    expect(decodedTrailing.ok).toBe(false)
+    expect(decodedTrailing.diagnostics.some((d) => d.message.includes('Trailing bytes'))).toBe(true)
+  })
+
+  it('rejects oversized binary frames before parsing', () => {
+    const oversized = new Uint8Array(DEFAULT_MAX_BINARY_ENVELOPE_BYTES + 1)
+    const decoded = decodeEnvelopeBinary(oversized)
+
+    expect(decoded.ok).toBe(false)
+    expect(decoded.diagnostics.some((d) => d.message.includes('maximum frame size'))).toBe(true)
+  })
+
+  it('rejects malformed string lengths', async () => {
+    const signed = await signEnvelopeHmac(
+      createEnvelope({
+        sender: 'agent.alpha',
+        intent: 'PING',
+        content: 'x',
+        messageId: 'bin-malformed-length',
+        nonce: 'nb-malformed-length',
+        nowMs: 1000,
+        ttlMs: 60_000,
+      }),
+      'shared-secret',
+      'k1',
+    )
+
+    const raw = encodeEnvelopeBinary(signed)
+    const malformed = raw.slice()
+    const version = stringFieldOffset(malformed, 0)
+    new DataView(malformed.buffer, malformed.byteOffset, malformed.byteLength).setUint32(version.lengthOffset, raw.byteLength, false)
+
+    const decoded = decodeEnvelopeBinary(malformed)
+    expect(decoded.ok).toBe(false)
+    expect(decoded.diagnostics.some((d) => d.message.includes('Unexpected end'))).toBe(true)
+  })
+
+  it('rejects unsupported decoded protocol fields', async () => {
+    const signed = await signEnvelopeHmac(
+      createEnvelope({
+        sender: 'agent.alpha',
+        intent: 'TASK',
+        content: 'x',
+        messageId: 'bin-invalid-fields',
+        nonce: 'nb-invalid-fields',
+        nowMs: 1000,
+        ttlMs: 60_000,
+      }),
+      'shared-secret',
+      'k1',
+    )
+
+    const raw = encodeEnvelopeBinary(signed)
+    const badVersion = decodeEnvelopeBinary(replaceAscii(raw, 0, 'aip/0.2'))
+    const badIntent = decodeEnvelopeBinary(replaceAscii(raw, 4, 'NOPE'))
+
+    expect(badVersion.ok).toBe(false)
+    expect(badVersion.diagnostics.some((d) => d.message.includes('Unsupported protocol version'))).toBe(true)
+    expect(badIntent.ok).toBe(false)
+    expect(badIntent.diagnostics.some((d) => d.message.includes('Unsupported intent'))).toBe(true)
+  })
+})

package/src/protocolBinary.ts

@@ -0,0 +1,312 @@
+import type { ProtocolEnvelope, ProtocolSignature } from './protocol'
+import type { ReceiveEnvelopeResult } from './protocolTransport'
+
+const MAGIC = [0x41, 0x49, 0x50, 0x42] as const // AIPB
+const MAGIC_BYTES = Uint8Array.from(MAGIC)
+const FORMAT_VERSION = 1
+export const DEFAULT_MAX_BINARY_ENVELOPE_BYTES = 1024 * 1024
+
+const FLAG_RECIPIENT = 1 << 0
+const FLAG_CAPABILITY = 1 << 1
+const FLAG_CORRELATION = 1 << 2
+const FLAG_SIGNATURE = 1 << 3
+const textEncoder = new TextEncoder()
+const textDecoder = new TextDecoder()
+const INTENT_KINDS = new Set(['PING', 'PONG', 'CAPS', 'TASK', 'RESULT', 'ERROR'])
+
+export interface BinaryDecodeOptions {
+  maxFrameBytes?: number
+}
+
+function utf8Encode(value: string): Uint8Array {
+  return textEncoder.encode(value)
+}
+
+function utf8Decode(value: Uint8Array): string {
+  return textDecoder.decode(value)
+}
+
+function signatureAlgCode(alg: ProtocolSignature['alg']): number {
+  return alg === 'ED25519' ? 2 : 1
+}
+
+function signatureAlgFromCode(code: number): ProtocolSignature['alg'] | null {
+  if (code === 1) return 'HS256'
+  if (code === 2) return 'ED25519'
+  return null
+}
+
+interface EncodedString {
+  bytes: Uint8Array
+}
+
+function encodeString(value: string): EncodedString {
+  return { bytes: utf8Encode(value) }
+}
+
+function encodedStringSize(encoded: EncodedString | null): number {
+  return encoded ? 4 + encoded.bytes.byteLength : 0
+}
+
+class BinaryWriter {
+  private readonly bytes: Uint8Array
+
+  private readonly view: DataView
+
+  private offset = 0
+
+  constructor(size: number) {
+    this.bytes = new Uint8Array(size)
+    this.view = new DataView(this.bytes.buffer, this.bytes.byteOffset, this.bytes.byteLength)
+  }
+
+  writeU8(value: number): void {
+    this.bytes[this.offset] = value & 0xff
+    this.offset += 1
+  }
+
+  writeU32(value: number): void {
+    this.view.setUint32(this.offset, value, false)
+    this.offset += 4
+  }
+
+  writeU64(value: number): void {
+    this.view.setBigUint64(this.offset, BigInt(value), false)
+    this.offset += 8
+  }
+
+  writeBytes(value: Uint8Array): void {
+    this.bytes.set(value, this.offset)
+    this.offset += value.byteLength
+  }
+
+  writeString(encoded: EncodedString): void {
+    this.writeU32(encoded.bytes.byteLength)
+    this.writeBytes(encoded.bytes)
+  }
+
+  finish(): Uint8Array {
+    return this.bytes
+  }
+}
+
+class BinaryReader {
+  private readonly bytes: Uint8Array
+
+  private offset = 0
+
+  constructor(bytes: Uint8Array) {
+    this.bytes = bytes
+  }
+
+  remaining(): number {
+    return this.bytes.byteLength - this.offset
+  }
+
+  readU8(): number {
+    if (this.remaining() < 1) throw new Error('Unexpected end of binary envelope')
+    const value = this.bytes[this.offset]
+    this.offset += 1
+    return value ?? 0
+  }
+
+  readU32(): number {
+    if (this.remaining() < 4) throw new Error('Unexpected end of binary envelope')
+    const value = new DataView(this.bytes.buffer, this.bytes.byteOffset + this.offset, 4).getUint32(0, false)
+    this.offset += 4
+    return value
+  }
+
+  readU64(): number {
+    if (this.remaining() < 8) throw new Error('Unexpected end of binary envelope')
+    const value = new DataView(this.bytes.buffer, this.bytes.byteOffset + this.offset, 8).getBigUint64(0, false)
+    this.offset += 8
+    return Number(value)
+  }
+
+  readBytes(length: number): Uint8Array {
+    if (length < 0 || this.remaining() < length) throw new Error('Unexpected end of binary envelope')
+    const value = this.bytes.slice(this.offset, this.offset + length)
+    this.offset += length
+    return value
+  }
+
+  readString(): string {
+    const length = this.readU32()
+    const value = this.readBytes(length)
+    return utf8Decode(value)
+  }
+}
+
+export function encodeEnvelopeBinary(envelope: ProtocolEnvelope): Uint8Array {
+  const flags =
+    (envelope.header.recipient ? FLAG_RECIPIENT : 0) |
+    (envelope.body.capability ? FLAG_CAPABILITY : 0) |
+    (envelope.body.correlationId ? FLAG_CORRELATION : 0) |
+    (envelope.signature ? FLAG_SIGNATURE : 0)
+
+  const version = encodeString(envelope.header.version)
+  const messageId = encodeString(envelope.header.messageId)
+  const sender = encodeString(envelope.header.sender)
+  const nonce = encodeString(envelope.header.nonce)
+  const intent = encodeString(envelope.body.intent)
+  const content = encodeString(envelope.body.content)
+  const recipient = envelope.header.recipient ? encodeString(envelope.header.recipient) : null
+  const capability = envelope.body.capability ? encodeString(envelope.body.capability) : null
+  const correlationId = envelope.body.correlationId ? encodeString(envelope.body.correlationId) : null
+  const signatureKeyId = envelope.signature ? encodeString(envelope.signature.keyId) : null
+  const signatureValue = envelope.signature ? encodeString(envelope.signature.value) : null
+
+  const size =
+    MAGIC_BYTES.byteLength +
+    1 +
+    1 +
+    8 +
+    4 +
+    encodedStringSize(version) +
+    encodedStringSize(messageId) +
+    encodedStringSize(sender) +
+    encodedStringSize(nonce) +
+    encodedStringSize(intent) +
+    encodedStringSize(content) +
+    encodedStringSize(recipient) +
+    encodedStringSize(capability) +
+    encodedStringSize(correlationId) +
+    (envelope.signature ? 1 : 0) +
+    encodedStringSize(signatureKeyId) +
+    encodedStringSize(signatureValue)
+
+  const writer = new BinaryWriter(size)
+  writer.writeBytes(MAGIC_BYTES)
+  writer.writeU8(FORMAT_VERSION)
+  writer.writeU8(flags)
+  writer.writeU64(envelope.header.timestampMs)
+  writer.writeU32(envelope.header.ttlMs)
+
+  writer.writeString(version)
+  writer.writeString(messageId)
+  writer.writeString(sender)
+  writer.writeString(nonce)
+  writer.writeString(intent)
+  writer.writeString(content)
+
+  if (recipient) writer.writeString(recipient)
+  if (capability) writer.writeString(capability)
+  if (correlationId) writer.writeString(correlationId)
+
+  if (envelope.signature && signatureKeyId && signatureValue) {
+    writer.writeU8(signatureAlgCode(envelope.signature.alg))
+    writer.writeString(signatureKeyId)
+    writer.writeString(signatureValue)
+  }
+
+  return writer.finish()
+}
+
+export function decodeEnvelopeBinary(payload: Uint8Array, options: BinaryDecodeOptions = {}): ReceiveEnvelopeResult {
+  try {
+    const maxFrameBytes = options.maxFrameBytes ?? DEFAULT_MAX_BINARY_ENVELOPE_BYTES
+    if (payload.byteLength > maxFrameBytes) {
+      return {
+        ok: false,
+        diagnostics: [{ level: 'error', message: `Binary envelope exceeds maximum frame size '${maxFrameBytes}'` }],
+        envelope: null,
+      }
+    }
+
+    const reader = new BinaryReader(payload)
+    const magic = [reader.readU8(), reader.readU8(), reader.readU8(), reader.readU8()]
+    if (magic.some((value, idx) => value !== MAGIC[idx])) {
+      return {
+        ok: false,
+        diagnostics: [{ level: 'error', message: 'Invalid binary envelope magic' }],
+        envelope: null,
+      }
+    }
+
+    const version = reader.readU8()
+    if (version !== FORMAT_VERSION) {
+      return {
+        ok: false,
+        diagnostics: [{ level: 'error', message: `Unsupported binary envelope version '${version}'` }],
+        envelope: null,
+      }
+    }
+
+    const flags = reader.readU8()
+    const timestampMs = reader.readU64()
+    const ttlMs = reader.readU32()
+
+    const envelope: ProtocolEnvelope = {
+      header: {
+        version: reader.readString() as '7h3/0.1',
+        messageId: reader.readString(),
+        timestampMs,
+        ttlMs,
+        sender: reader.readString(),
+        nonce: reader.readString(),
+      },
+      body: {
+        intent: reader.readString() as ProtocolEnvelope['body']['intent'],
+        content: reader.readString(),
+      },
+    }
+
+    if (envelope.header.version !== '7h3/0.1') {
+      return {
+        ok: false,
+        diagnostics: [{ level: 'error', message: `Unsupported protocol version '${envelope.header.version}'` }],
+        envelope: null,
+      }
+    }
+
+    if (!INTENT_KINDS.has(envelope.body.intent)) {
+      return {
+        ok: false,
+        diagnostics: [{ level: 'error', message: `Unsupported intent '${envelope.body.intent}'` }],
+        envelope: null,
+      }
+    }
+
+    if (flags & FLAG_RECIPIENT) envelope.header.recipient = reader.readString()
+    if (flags & FLAG_CAPABILITY) envelope.body.capability = reader.readString()
+    if (flags & FLAG_CORRELATION) envelope.body.correlationId = reader.readString()
+
+    if (flags & FLAG_SIGNATURE) {
+      const algCode = reader.readU8()
+      const alg = signatureAlgFromCode(algCode)
+      if (!alg) {
+        return {
+          ok: false,
+          diagnostics: [{ level: 'error', message: `Unsupported binary signature algorithm '${algCode}'` }],
+          envelope: null,
+        }
+      }
+      envelope.signature = {
+        alg,
+        keyId: reader.readString(),
+        value: reader.readString(),
+      }
+    }
+
+    if (reader.remaining() !== 0) {
+      return {
+        ok: false,
+        diagnostics: [{ level: 'error', message: 'Trailing bytes found in binary envelope' }],
+        envelope: null,
+      }
+    }
+
+    return {
+      ok: true,
+      diagnostics: [],
+      envelope,
+    }
+  } catch (error: unknown) {
+    return {
+      ok: false,
+      diagnostics: [{ level: 'error', message: error instanceof Error ? error.message : 'Invalid binary envelope' }],
+      envelope: null,
+    }
+  }
+}

package/src/protocolCapabilities.ts

@@ -0,0 +1,70 @@
+import type { WireFormat } from './protocolTransport'
+
+export type AckMode = 'fast' | 'receipt'
+
+export interface AipCapabilities {
+  agent: string
+  capabilities: string[]
+  wireFormats: WireFormat[]
+  batchMax: number
+  ackModes: AckMode[]
+}
+
+export interface NegotiatedAipCapabilities {
+  wireFormat: WireFormat
+  batchMax: number
+  ackMode: AckMode
+}
+
+const WIRE_FORMAT_ORDER: WireFormat[] = ['binary', 'compact', 'json']
+const ACK_MODE_ORDER: AckMode[] = ['fast', 'receipt']
+
+export function createAipCapabilities(input: {
+  agent: string
+  capabilities?: string[]
+  wireFormats?: WireFormat[]
+  batchMax?: number
+  ackModes?: AckMode[]
+}): AipCapabilities {
+  return {
+    agent: input.agent,
+    capabilities: input.capabilities ?? [],
+    wireFormats: input.wireFormats ?? ['compact', 'json'],
+    batchMax: input.batchMax ?? 1,
+    ackModes: input.ackModes ?? ['receipt'],
+  }
+}
+
+export function encodeAipCapabilities(capabilities: AipCapabilities): string {
+  return JSON.stringify(capabilities)
+}
+
+export function parseAipCapabilities(raw: string): AipCapabilities | null {
+  try {
+    const parsed = JSON.parse(raw) as Partial<AipCapabilities>
+    if (typeof parsed.agent !== 'string') return null
+    if (!Array.isArray(parsed.capabilities)) return null
+    if (!Array.isArray(parsed.wireFormats)) return null
+    if (!Array.isArray(parsed.ackModes)) return null
+    if (typeof parsed.batchMax !== 'number' || parsed.batchMax < 1) return null
+    return {
+      agent: parsed.agent,
+      capabilities: parsed.capabilities.filter((item): item is string => typeof item === 'string'),
+      wireFormats: parsed.wireFormats.filter((item): item is WireFormat => item === 'json' || item === 'compact' || item === 'binary'),
+      batchMax: Math.floor(parsed.batchMax),
+      ackModes: parsed.ackModes.filter((item): item is AckMode => item === 'fast' || item === 'receipt'),
+    }
+  } catch {
+    return null
+  }
+}
+
+export function negotiateAipCapabilities(local: AipCapabilities, remote: AipCapabilities): NegotiatedAipCapabilities {
+  const wireFormat = WIRE_FORMAT_ORDER.find((format) => local.wireFormats.includes(format) && remote.wireFormats.includes(format)) ?? 'compact'
+  const ackMode = ACK_MODE_ORDER.find((mode) => local.ackModes.includes(mode) && remote.ackModes.includes(mode)) ?? 'receipt'
+  return {
+    wireFormat,
+    batchMax: Math.max(1, Math.min(local.batchMax, remote.batchMax)),
+    ackMode,
+  }
+}