@7h3/protocol 0.1.2 → 0.5.0

package/sdk/threshold/src/index.ts

@@ -0,0 +1,355 @@
+import { bls12_381 } from '@noble/curves/bls12-381'
+
+// ─── Protocol Types (re-declared for standalone build; canonical source: @7h3/protocol) ──
+
+export interface ProtocolHeader {
+  version: string
+  messageId: string
+  timestampMs: number
+  ttlMs: number
+  sender: string
+  recipient?: string
+  nonce: string
+}
+
+export interface ProtocolBody {
+  intent: string
+  content: string
+  capability?: string
+  correlationId?: string
+}
+
+export interface ProtocolEnvelope {
+  header: ProtocolHeader
+  body: ProtocolBody
+}
+
+// ─── BLS Types ───────────────────────────────────────────────────────────────
+
+export interface BlsKeyPair {
+  publicKey: string  // G1 point, 48 bytes, base64url
+  privateKey: string // scalar, 32 bytes, base64url
+}
+
+export interface ThresholdConfig {
+  m: number  // minimum signers required
+  n: number  // total participants
+}
+
+export interface ThresholdSignature {
+  alg: 'BLS-G2-2'
+  keyId: string          // aggregated public key fingerprint (base64url of first 16 bytes)
+  value: string          // aggregated signature (base64url, G2 point 96 bytes)
+  signerIds: string[]    // which participants signed
+  threshold: ThresholdConfig
+}
+
+export interface ThresholdEnvelope extends ProtocolEnvelope {
+  thresholdSignature: ThresholdSignature
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function toBase64Url(bytes: Uint8Array): string {
+  const base64 = Buffer.from(bytes).toString('base64')
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '')
+}
+
+function fromBase64Url(value: string): Uint8Array {
+  const padded = value
+    .replace(/-/g, '+')
+    .replace(/_/g, '/')
+    .padEnd(Math.ceil(value.length / 4) * 4, '=')
+  return new Uint8Array(Buffer.from(padded, 'base64'))
+}
+
+async function sha256(data: string): Promise<Uint8Array> {
+  const encoder = new TextEncoder()
+  const buf = await crypto.subtle.digest('SHA-256', encoder.encode(data))
+  return new Uint8Array(buf)
+}
+
+/**
+ * Canonical serialization of a protocol envelope for signing.
+ * Must match the canonical format in @7h3/protocol.
+ */
+export function canonicalizeEnvelopeForBls(envelope: ProtocolEnvelope): string {
+  const h = envelope.header
+  const b = envelope.body
+
+  const headerParts: string[] = [
+    `"messageId":${JSON.stringify(h.messageId)}`,
+    `"nonce":${JSON.stringify(h.nonce)}`,
+  ]
+  if (h.recipient !== undefined) {
+    headerParts.push(`"recipient":${JSON.stringify(h.recipient)}`)
+  }
+  headerParts.push(`"sender":${JSON.stringify(h.sender)}`)
+  headerParts.push(`"timestampMs":${h.timestampMs}`)
+  headerParts.push(`"ttlMs":${h.ttlMs}`)
+  headerParts.push(`"version":${JSON.stringify(h.version)}`)
+  const headerStr = `{${headerParts.join(',')}}`
+
+  const bodyParts: string[] = []
+  if (b.capability !== undefined) bodyParts.push(`"capability":${JSON.stringify(b.capability)}`)
+  bodyParts.push(`"content":${JSON.stringify(b.content)}`)
+  if (b.correlationId !== undefined) bodyParts.push(`"correlationId":${JSON.stringify(b.correlationId)}`)
+  bodyParts.push(`"intent":${JSON.stringify(b.intent)}`)
+  const bodyStr = `{${bodyParts.join(',')}}`
+
+  return `{"body":${bodyStr},"header":${headerStr}}`
+}
+
+// ─── Key Generation ──────────────────────────────────────────────────────────
+
+export function generateBlsKeyPair(): BlsKeyPair {
+  const privateKeyBytes = bls12_381.utils.randomPrivateKey()
+  const publicKeyBytes = bls12_381.getPublicKey(privateKeyBytes)
+  return {
+    publicKey: toBase64Url(publicKeyBytes),
+    privateKey: toBase64Url(privateKeyBytes),
+  }
+}
+
+// ─── Partial Signing ─────────────────────────────────────────────────────────
+
+export async function signEnvelopeBls(
+  envelope: ProtocolEnvelope,
+  privateKeyBase64Url: string,
+  signerId: string,
+): Promise<{ signerId: string; partialSig: string; canonicalHash: string }> {
+  const canonical = canonicalizeEnvelopeForBls(envelope)
+  const msgHash = await sha256(canonical)
+  const privateKeyBytes = fromBase64Url(privateKeyBase64Url)
+  // BLS sign: signature is a G2 point (96 bytes)
+  const sigBytes = bls12_381.sign(msgHash, privateKeyBytes)
+  return {
+    signerId,
+    partialSig: toBase64Url(sigBytes),
+    canonicalHash: toBase64Url(msgHash),
+  }
+}
+
+// ─── Aggregation ─────────────────────────────────────────────────────────────
+
+export async function aggregateSignatures(
+  partialSigs: Array<{ signerId: string; partialSig: string }>,
+  publicKeys: Record<string, string>,  // signerId → BLS public key (base64url)
+  envelope: ProtocolEnvelope,
+  config: ThresholdConfig,
+): Promise<ThresholdEnvelope> {
+  if (partialSigs.length < config.m) {
+    throw new Error(
+      `Threshold not met: need ${config.m} signatures, got ${partialSigs.length}`,
+    )
+  }
+
+  // Use exactly m signatures (first m)
+  const selected = partialSigs.slice(0, config.m)
+
+  const signerIds = selected.map((s) => s.signerId)
+  const sigBytesArr = selected.map((s) => fromBase64Url(s.partialSig))
+  const pubKeyBytesArr = signerIds.map((id) => {
+    const pk = publicKeys[id]
+    if (!pk) throw new Error(`Missing public key for signer: ${id}`)
+    return fromBase64Url(pk)
+  })
+
+  const aggregatedSig = bls12_381.aggregateSignatures(sigBytesArr)
+  const aggregatedPubKey = bls12_381.aggregatePublicKeys(pubKeyBytesArr)
+
+  // Fingerprint: first 16 bytes of aggregated pubkey as base64url
+  const keyId = toBase64Url(aggregatedPubKey.slice(0, 16))
+
+  return {
+    ...envelope,
+    thresholdSignature: {
+      alg: 'BLS-G2-2',
+      keyId,
+      value: toBase64Url(aggregatedSig),
+      signerIds,
+      threshold: config,
+    },
+  }
+}
+
+// ─── Verification ────────────────────────────────────────────────────────────
+
+export async function verifyThresholdEnvelope(
+  envelope: ThresholdEnvelope,
+  participantPublicKeys: Record<string, string>,
+  config: ThresholdConfig,
+): Promise<boolean> {
+  try {
+    const { thresholdSignature } = envelope
+    if (!thresholdSignature) return false
+    if (thresholdSignature.alg !== 'BLS-G2-2') return false
+    if (thresholdSignature.signerIds.length < config.m) return false
+
+    const canonical = canonicalizeEnvelopeForBls({
+      header: envelope.header,
+      body: envelope.body,
+    })
+    const msgHash = await sha256(canonical)
+
+    const signerIds = thresholdSignature.signerIds
+    const pubKeyBytesArr = signerIds.map((id) => {
+      const pk = participantPublicKeys[id]
+      if (!pk) throw new Error(`Missing public key for signer: ${id}`)
+      return fromBase64Url(pk)
+    })
+
+    const aggregatedPubKey = bls12_381.aggregatePublicKeys(pubKeyBytesArr)
+    const sigBytes = fromBase64Url(thresholdSignature.value)
+
+    return bls12_381.verify(sigBytes, msgHash, aggregatedPubKey)
+  } catch {
+    return false
+  }
+}
+
+// ─── Shamir Secret Sharing ───────────────────────────────────────────────────
+// Operates over the BLS12-381 scalar field (Fr), prime order r.
+
+// BLS12-381 scalar field order r
+const FIELD_ORDER = BigInt(
+  '0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001',
+)
+
+function fieldMod(n: bigint): bigint {
+  return ((n % FIELD_ORDER) + FIELD_ORDER) % FIELD_ORDER
+}
+
+function fieldAdd(a: bigint, b: bigint): bigint {
+  return fieldMod(a + b)
+}
+
+function fieldMul(a: bigint, b: bigint): bigint {
+  return fieldMod(a * b)
+}
+
+// Modular inverse via Fermat's little theorem (field is prime order)
+function fieldInv(a: bigint): bigint {
+  if (a === 0n) throw new Error('Cannot invert zero')
+  return fieldPow(a, FIELD_ORDER - 2n)
+}
+
+function fieldPow(base: bigint, exp: bigint): bigint {
+  let result = 1n
+  base = fieldMod(base)
+  while (exp > 0n) {
+    if (exp & 1n) result = fieldMul(result, base)
+    base = fieldMul(base, base)
+    exp >>= 1n
+  }
+  return result
+}
+
+function bigintToBytes32(n: bigint): Uint8Array {
+  const hex = n.toString(16).padStart(64, '0')
+  const bytes = new Uint8Array(32)
+  for (let i = 0; i < 32; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)
+  }
+  return bytes
+}
+
+function bytes32ToBigint(bytes: Uint8Array): bigint {
+  let hex = ''
+  for (const b of bytes) {
+    hex += b.toString(16).padStart(2, '0')
+  }
+  return BigInt('0x' + hex)
+}
+
+// Generate a cryptographically random field element
+function randomFieldElement(): bigint {
+  const bytes = new Uint8Array(32)
+  crypto.getRandomValues(bytes)
+  return fieldMod(bytes32ToBigint(bytes))
+}
+
+/**
+ * Split a BLS private key into N shares using Shamir's Secret Sharing.
+ * Any M shares can reconstruct the original key.
+ * Returns N shares as base64url strings.
+ * Share format: 1 byte index (1-based) || 32 bytes value
+ */
+export function splitPrivateKey(
+  privateKeyBase64Url: string,
+  m: number,
+  n: number,
+): string[] {
+  if (m < 2 || m > n) throw new Error(`Invalid threshold: m=${m}, n=${n}`)
+
+  const secretBytes = fromBase64Url(privateKeyBase64Url)
+  const secret = fieldMod(bytes32ToBigint(secretBytes))
+
+  // Build polynomial: f(x) = secret + a1*x + a2*x^2 + ... + a_{m-1}*x^{m-1}
+  const coefficients: bigint[] = [secret]
+  for (let i = 1; i < m; i++) {
+    coefficients.push(randomFieldElement())
+  }
+
+  // Evaluate at x = 1..n
+  const shares: string[] = []
+  for (let x = 1; x <= n; x++) {
+    let y = 0n
+    let xPow = 1n
+    for (const coeff of coefficients) {
+      y = fieldAdd(y, fieldMul(coeff, xPow))
+      xPow = fieldMul(xPow, BigInt(x))
+    }
+    // Encode share: index byte + 32-byte value
+    const shareBytes = new Uint8Array(33)
+    shareBytes[0] = x
+    shareBytes.set(bigintToBytes32(y), 1)
+    shares.push(toBase64Url(shareBytes))
+  }
+
+  return shares
+}
+
+/**
+ * Reconstruct a BLS private key from M or more shares using Lagrange interpolation.
+ * @param shares - array of share strings (base64url, at least m of them)
+ * @param m - minimum number of shares required (used for validation only)
+ */
+export function reconstructPrivateKey(shares: string[], m: number): string {
+  if (shares.length < m) {
+    throw new Error(`Need at least ${m} shares, got ${shares.length}`)
+  }
+
+  // Decode shares — take exactly m
+  const decoded = shares.slice(0, m).map((s) => {
+    const bytes = fromBase64Url(s)
+    if (bytes.length !== 33) throw new Error('Invalid share format')
+    const x = BigInt(bytes[0])
+    const y = bytes32ToBigint(bytes.slice(1))
+    return { x, y }
+  })
+
+  // Lagrange interpolation at x=0 to recover secret
+  let secret = 0n
+  for (let i = 0; i < decoded.length; i++) {
+    const xi = decoded[i].x
+    const yi = decoded[i].y
+
+    // Compute Lagrange basis polynomial l_i(0)
+    let num = 1n
+    let den = 1n
+    for (let j = 0; j < decoded.length; j++) {
+      if (i === j) continue
+      const xj = decoded[j].x
+      // num *= (0 - xj) = -xj
+      num = fieldMul(num, fieldMod(-xj))
+      // den *= (xi - xj)
+      den = fieldMul(den, fieldMod(xi - xj))
+    }
+
+    const lagrangeBasis = fieldMul(num, fieldInv(den))
+    secret = fieldAdd(secret, fieldMul(yi, lagrangeBasis))
+  }
+
+  return toBase64Url(bigintToBytes32(secret))
+}

package/sdk/threshold/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2023", "DOM"],
+    "types": ["node"],
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": ".",
+    "rootDir": "./src",
+    "esModuleInterop": true,
+    "verbatimModuleSyntax": false
+  },
+  "include": ["src/index.ts"],
+  "exclude": ["src/**/*.test.ts", "node_modules"]
+}

package/sdk/threshold/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+  },
+  resolve: {
+    alias: {
+      '@7h3/protocol': '/tmp/aip-work/src/protocol.ts',
+    },
+  },
+})

package/src/agentAdapter.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest'
+import { createAipAgentAdapter } from './agentAdapter'
+import type { WireEnvelope } from './protocolTransport'
+
+describe('AIP agent adapter', () => {
+  it('supports raw task request/response flow', async () => {
+    const secret = 'adapter-shared-secret'
+
+    const coordinator = createAipAgentAdapter({
+      agentId: 'agent.coordinator',
+      outboundSecret: secret,
+      sharedSecrets: { 'agent.worker': secret },
+      wireFormat: 'compact',
+    })
+
+    const worker = createAipAgentAdapter({
+      agentId: 'agent.worker',
+      outboundSecret: secret,
+      sharedSecrets: { 'agent.coordinator': secret },
+      wireFormat: 'compact',
+      onTask: async (envelope) => ({
+        intent: 'RESULT',
+        content: `handled:${envelope.body.content}`,
+        capability: envelope.body.capability,
+      }),
+    })
+
+    const taskRaw = await coordinator.createRawIntent({
+      recipient: 'agent.worker',
+      intent: 'TASK',
+      content: 'optimize route',
+      capability: 'task.plan',
+    })
+
+    let responseRaw: WireEnvelope = ''
+    const handled = await worker.handleRaw(taskRaw, async (rawResponse) => {
+      responseRaw = rawResponse
+    })
+
+    expect(handled.ok).toBe(true)
+    expect(responseRaw.length).toBeGreaterThan(0)
+
+    const verification = await coordinator.receiveRaw(responseRaw)
+    expect(verification.ok).toBe(true)
+    expect(verification.received?.body.intent).toBe('RESULT')
+    expect(verification.received?.body.content).toContain('handled:optimize route')
+  })
+})

package/src/agentAdapter.ts

@@ -0,0 +1,56 @@
+import { type AgentReceiveResult, type AgentSessionConfig, AgentSession } from './protocolAgent'
+import { type IntentKind, type ProtocolEnvelope } from './protocol'
+import { encodeEnvelope, type WireEnvelope, type WireFormat } from './protocolTransport'
+
+export interface AipAdapterConfig extends AgentSessionConfig {
+  wireFormat?: WireFormat
+}
+
+export class AipAgentAdapter {
+  private readonly session: AgentSession
+  private readonly wireFormat: WireFormat
+
+  constructor(config: AipAdapterConfig) {
+    this.session = new AgentSession(config)
+    this.wireFormat = config.wireFormat ?? 'compact'
+  }
+
+  toRaw(envelope: ProtocolEnvelope): WireEnvelope {
+    return encodeEnvelope(envelope, this.wireFormat)
+  }
+
+  async createRawIntent(input: {
+    recipient?: string
+    intent: IntentKind
+    content: string
+    capability?: string
+    correlationId?: string
+    ttlMs?: number
+    messageId?: string
+    nonce?: string
+    nowMs?: number
+  }): Promise<WireEnvelope> {
+    const envelope = await this.session.createSignedIntent(input)
+    return this.toRaw(envelope)
+  }
+
+  async receiveRaw(raw: WireEnvelope, nowMs = Date.now()): Promise<AgentReceiveResult> {
+    return this.session.receiveAndRespond(raw, nowMs)
+  }
+
+  async handleRaw(
+    raw: WireEnvelope,
+    emitResponseRaw: (rawResponse: WireEnvelope, responseEnvelope: ProtocolEnvelope) => void | Promise<void>,
+    nowMs = Date.now(),
+  ): Promise<AgentReceiveResult> {
+    const result = await this.session.receiveAndRespond(raw, nowMs)
+    if (result.response) {
+      await emitResponseRaw(this.toRaw(result.response), result.response)
+    }
+    return result
+  }
+}
+
+export function createAipAgentAdapter(config: AipAdapterConfig): AipAgentAdapter {
+  return new AipAgentAdapter(config)
+}

package/src/auditLog.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect, beforeAll } from 'vitest'
+import { createAuditLog, NoopAuditLog, type AuditEntry } from './auditLog'
+import { generateEd25519KeypairBase64Url } from './protocol'
+
+let keys: { publicKey: string; privateKey: string }
+
+beforeAll(async () => {
+  keys = await generateEd25519KeypairBase64Url()
+})
+
+describe('InMemoryAuditLog', () => {
+  it('logs and queries entries', async () => {
+    const log = createAuditLog(keys.privateKey)
+    await log.log({ type: 'verify-ok', sender: 'agent-a', path: '/api/test', method: 'GET' })
+    await log.log({ type: 'verify-fail', sender: 'agent-b', path: '/api/test', method: 'POST', failReason: 'invalid-signature' })
+
+    const all = await log.query()
+    expect(all).toHaveLength(2)
+    expect(log.size()).toBe(2)
+  })
+
+  it('query filters by type', async () => {
+    const log = createAuditLog(keys.privateKey)
+    await log.log({ type: 'verify-ok', sender: 'alice' })
+    await log.log({ type: 'verify-fail', sender: 'bob', failReason: 'expired' })
+    await log.log({ type: 'rate-limited', sender: 'alice' })
+
+    const oks = await log.query({ type: 'verify-ok' })
+    expect(oks).toHaveLength(1)
+    expect(oks[0].type).toBe('verify-ok')
+  })
+
+  it('query filters by sender', async () => {
+    const log = createAuditLog(keys.privateKey)
+    await log.log({ type: 'verify-ok', sender: 'alice' })
+    await log.log({ type: 'verify-ok', sender: 'bob' })
+    await log.log({ type: 'verify-fail', sender: 'alice', failReason: 'expired' })
+
+    const aliceEntries = await log.query({ sender: 'alice' })
+    expect(aliceEntries).toHaveLength(2)
+    expect(aliceEntries.every(e => e.sender === 'alice')).toBe(true)
+  })
+
+  it('query filters by since', async () => {
+    const log = createAuditLog(keys.privateKey)
+    const before = Date.now()
+    await log.log({ type: 'verify-ok', sender: 'alice' })
+    await new Promise(r => setTimeout(r, 5))
+    const mid = Date.now()
+    await log.log({ type: 'verify-ok', sender: 'bob' })
+
+    const recent = await log.query({ since: mid })
+    expect(recent).toHaveLength(1)
+    expect(recent[0].sender).toBe('bob')
+
+    const all = await log.query({ since: before - 1 })
+    expect(all).toHaveLength(2)
+  })
+
+  it('query respects limit', async () => {
+    const log = createAuditLog(keys.privateKey)
+    for (let i = 0; i < 5; i++) {
+      await log.log({ type: 'verify-ok', sender: `agent-${i}` })
+    }
+    const limited = await log.query({ limit: 2 })
+    expect(limited).toHaveLength(2)
+  })
+
+  it('verify() returns true for valid entry', async () => {
+    const log = createAuditLog(keys.privateKey)
+    await log.log({ type: 'verify-ok', sender: 'alice', path: '/api/test' })
+
+    const entries = await log.query()
+    expect(entries).toHaveLength(1)
+    const valid = await log.verify(entries[0], keys.publicKey)
+    expect(valid).toBe(true)
+  })
+
+  it('verify() returns false for tampered entry', async () => {
+    const log = createAuditLog(keys.privateKey)
+    await log.log({ type: 'verify-ok', sender: 'alice', path: '/api/test' })
+
+    const entries = await log.query()
+    const tampered: AuditEntry = { ...entries[0], sender: 'eve' }
+    const valid = await log.verify(tampered, keys.publicKey)
+    expect(valid).toBe(false)
+  })
+
+  it('verify() returns false with wrong public key', async () => {
+    const log = createAuditLog(keys.privateKey)
+    await log.log({ type: 'verify-ok', sender: 'alice' })
+
+    const wrongKeys = await generateEd25519KeypairBase64Url()
+    const entries = await log.query()
+    const valid = await log.verify(entries[0], wrongKeys.publicKey)
+    expect(valid).toBe(false)
+  })
+
+  it('respects maxEntries by evicting oldest', async () => {
+    const log = createAuditLog(keys.privateKey, { maxEntries: 3 })
+    for (let i = 0; i < 5; i++) {
+      await log.log({ type: 'verify-ok', sender: `agent-${i}` })
+    }
+    expect(log.size()).toBe(3)
+    const entries = await log.query()
+    // Should have the last 3 (agents 2, 3, 4)
+    expect(entries[0].sender).toBe('agent-2')
+  })
+
+  it('entries have id, timestampMs, and entrySignature', async () => {
+    const log = createAuditLog(keys.privateKey)
+    await log.log({ type: 'response-signed', upstream: 'http://upstream' })
+
+    const entries = await log.query()
+    expect(typeof entries[0].id).toBe('string')
+    expect(typeof entries[0].timestampMs).toBe('number')
+    expect(typeof entries[0].entrySignature).toBe('string')
+    expect(entries[0].entrySignature.length).toBeGreaterThan(0)
+  })
+})
+
+describe('NoopAuditLog', () => {
+  it('log does nothing', async () => {
+    const log = new NoopAuditLog()
+    await log.log({ type: 'verify-ok', sender: 'alice' })
+    expect(log.size()).toBe(0)
+  })
+
+  it('query returns empty array', async () => {
+    const log = new NoopAuditLog()
+    const result = await log.query()
+    expect(result).toEqual([])
+  })
+
+  it('verify always returns false', async () => {
+    const log = new NoopAuditLog()
+    const fakeEntry = {
+      id: 'x',
+      timestampMs: Date.now(),
+      type: 'verify-ok' as const,
+      entrySignature: 'fake',
+    }
+    expect(await log.verify(fakeEntry, 'key')).toBe(false)
+  })
+})