@7h3/protocol 0.1.2 → 0.4.0

package/sdk/rust/tests/keys.rs

@@ -0,0 +1,189 @@
+use protocol_7h3::keys::{
+    KeyEntry, KeyRotationManager, ManagedKeyPair, RevocationRegistry, WellKnownKeysDocument,
+};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+fn now_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis() as u64
+}
+
+fn make_key_entry(id: &str, revoked: Option<bool>, expires: Option<u64>) -> KeyEntry {
+    KeyEntry {
+        id: id.to_string(),
+        algorithm: "Ed25519".to_string(),
+        public_key: "dGVzdC1wdWJsaWMta2V5".to_string(),
+        created: now_ms() - 1000,
+        expires,
+        revoked,
+        revoked_at: None,
+    }
+}
+
+// 1. WellKnownKeysDocument round-trip JSON serialization
+#[test]
+fn test_well_known_document_json_round_trip() {
+    let entry = make_key_entry("key-1", None, None);
+    let doc = WellKnownKeysDocument::new(vec![entry]);
+
+    let json = doc.to_json().expect("serialization should succeed");
+    let restored = WellKnownKeysDocument::from_json(&json).expect("deserialization should succeed");
+
+    assert_eq!(restored.version, "7h3/0.1");
+    assert_eq!(restored.keys.len(), 1);
+    assert_eq!(restored.keys[0].id, "key-1");
+    assert_eq!(restored.keys[0].algorithm, "Ed25519");
+}
+
+// 2. get_active_key finds non-revoked keys
+#[test]
+fn test_get_active_key_finds_active() {
+    let entry = make_key_entry("key-active", None, None);
+    let doc = WellKnownKeysDocument::new(vec![entry]);
+
+    let found = doc.get_active_key("key-active");
+    assert!(found.is_some(), "should find an active key");
+    assert_eq!(found.unwrap().id, "key-active");
+}
+
+// 3. get_active_key ignores revoked keys
+#[test]
+fn test_get_active_key_ignores_revoked() {
+    let revoked = make_key_entry("key-revoked", Some(true), None);
+    let doc = WellKnownKeysDocument::new(vec![revoked]);
+
+    let found = doc.get_active_key("key-revoked");
+    assert!(found.is_none(), "should NOT find a revoked key");
+}
+
+// 3b. get_active_key ignores expired keys
+#[test]
+fn test_get_active_key_ignores_expired() {
+    // expires 10 seconds in the past
+    let expired = make_key_entry("key-expired", None, Some(now_ms() - 10_000));
+    let doc = WellKnownKeysDocument::new(vec![expired]);
+
+    let found = doc.get_active_key("key-expired");
+    assert!(found.is_none(), "should NOT find an expired key");
+}
+
+// 4. KeyRotationManager: add_key + get_current_key
+#[test]
+fn test_rotation_manager_add_and_get_current() {
+    let mgr = KeyRotationManager::new(86_400_000, 3_600_000);
+
+    let pair = ManagedKeyPair {
+        id: "rot-key-1".to_string(),
+        public_key: "pub1".to_string(),
+        private_key: "priv1".to_string(),
+        created: now_ms(),
+        expires_at: None,
+    };
+    mgr.add_key(pair);
+
+    let current = mgr.get_current_key();
+    assert!(current.is_some(), "should return current key");
+    assert_eq!(current.unwrap().id, "rot-key-1");
+}
+
+// 4b. get_current_key returns the most recent non-expired key
+#[test]
+fn test_rotation_manager_returns_most_recent() {
+    let mgr = KeyRotationManager::new(86_400_000, 3_600_000);
+    let base = now_ms();
+
+    mgr.add_key(ManagedKeyPair {
+        id: "older".to_string(),
+        public_key: "pub-older".to_string(),
+        private_key: "priv-older".to_string(),
+        created: base - 5000,
+        expires_at: None,
+    });
+    mgr.add_key(ManagedKeyPair {
+        id: "newer".to_string(),
+        public_key: "pub-newer".to_string(),
+        private_key: "priv-newer".to_string(),
+        created: base,
+        expires_at: None,
+    });
+
+    let current = mgr.get_current_key().expect("should have a current key");
+    assert_eq!(current.id, "newer");
+}
+
+// 4c. get_current_key excludes expired keys
+#[test]
+fn test_rotation_manager_excludes_expired() {
+    let mgr = KeyRotationManager::new(86_400_000, 3_600_000);
+
+    mgr.add_key(ManagedKeyPair {
+        id: "exp-key".to_string(),
+        public_key: "pub-exp".to_string(),
+        private_key: "priv-exp".to_string(),
+        created: now_ms() - 2000,
+        expires_at: Some(now_ms() - 1000), // already expired
+    });
+
+    let current = mgr.get_current_key();
+    assert!(current.is_none(), "expired key should not be returned as current");
+}
+
+// 5. KeyRotationManager: get_well_known_document structure
+#[test]
+fn test_rotation_manager_well_known_document() {
+    let mgr = KeyRotationManager::new(86_400_000, 3_600_000);
+
+    mgr.add_key(ManagedKeyPair {
+        id: "doc-key-1".to_string(),
+        public_key: "pub-doc".to_string(),
+        private_key: "priv-doc".to_string(),
+        created: now_ms(),
+        expires_at: None,
+    });
+
+    let doc = mgr.get_well_known_document();
+    assert_eq!(doc.version, "7h3/0.1");
+    assert_eq!(doc.keys.len(), 1);
+    assert_eq!(doc.keys[0].id, "doc-key-1");
+    assert_eq!(doc.keys[0].algorithm, "Ed25519");
+    assert_eq!(doc.keys[0].public_key, "pub-doc");
+    // non-expired key should not be marked revoked
+    assert!(doc.keys[0].revoked.is_none() || !doc.keys[0].revoked.unwrap());
+}
+
+// 6. RevocationRegistry: revoke + is_revoked
+#[test]
+fn test_revocation_registry_revoke_and_check() {
+    let registry = RevocationRegistry::new();
+
+    assert!(!registry.is_revoked("key-x"), "should not be revoked initially");
+    registry.revoke("key-x", Some("compromised"));
+    assert!(registry.is_revoked("key-x"), "should be revoked after revoke()");
+    assert!(!registry.is_revoked("key-y"), "unrelated key should not be revoked");
+}
+
+// 7. RevocationRegistry: get_list contains correct fields
+#[test]
+fn test_revocation_registry_get_list() {
+    let registry = RevocationRegistry::new();
+    registry.revoke("key-a", Some("expired"));
+    registry.revoke("key-b", None);
+
+    let list = registry.get_list();
+
+    assert_eq!(list["version"], "7h3/0.1");
+    let revoked_keys = list["revokedKeys"].as_array().expect("revokedKeys should be array");
+    assert_eq!(revoked_keys.len(), 2);
+
+    // Find key-a in the list
+    let key_a = revoked_keys.iter().find(|e| e["id"] == "key-a").expect("key-a should be in list");
+    assert!(key_a["revokedAt"].as_u64().unwrap() > 0, "revokedAt should be a positive timestamp");
+    assert_eq!(key_a["reason"], "expired");
+
+    // Find key-b in the list — no reason
+    let key_b = revoked_keys.iter().find(|e| e["id"] == "key-b").expect("key-b should be in list");
+    assert!(key_b["revokedAt"].as_u64().unwrap() > 0);
+    assert!(key_b.get("reason").is_none() || key_b["reason"].is_null());
+}

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)
+  })
+})

package/src/auditLog.ts

@@ -0,0 +1,147 @@
+import {
+  signCanonicalPayloadEd25519,
+  verifyCanonicalPayloadEd25519,
+} from './protocol'
+
+export type AuditEventType =
+  | 'verify-ok'
+  | 'verify-fail'
+  | 'rate-limited'
+  | 'sender-denied'
+  | 'response-signed'
+
+export interface AuditEntry {
+  id: string
+  timestampMs: number
+  type: AuditEventType
+  sender?: string
+  path?: string
+  method?: string
+  envelopeId?: string
+  failReason?: string
+  upstream?: string
+  responseStatus?: number
+  entrySignature: string // Ed25519 sig over the entry (minus entrySignature itself)
+}
+
+/**
+ * Produce a canonical payload string from an AuditEntry, excluding entrySignature.
+ * Uses explicit key order and omits undefined fields for determinism.
+ */
+function canonicalAuditPayload(entry: Omit<AuditEntry, 'entrySignature'> & { entrySignature?: string }): string {
+  const parts: string[] = [
+    `"id":${JSON.stringify(entry.id)}`,
+    `"timestampMs":${entry.timestampMs}`,
+    `"type":${JSON.stringify(entry.type)}`,
+  ]
+  if (entry.sender !== undefined) parts.push(`"sender":${JSON.stringify(entry.sender)}`)
+  if (entry.path !== undefined) parts.push(`"path":${JSON.stringify(entry.path)}`)
+  if (entry.method !== undefined) parts.push(`"method":${JSON.stringify(entry.method)}`)
+  if (entry.envelopeId !== undefined) parts.push(`"envelopeId":${JSON.stringify(entry.envelopeId)}`)
+  if (entry.failReason !== undefined) parts.push(`"failReason":${JSON.stringify(entry.failReason)}`)
+  if (entry.upstream !== undefined) parts.push(`"upstream":${JSON.stringify(entry.upstream)}`)
+  if (entry.responseStatus !== undefined) parts.push(`"responseStatus":${entry.responseStatus}`)
+  return `{${parts.join(',')}}`
+}
+
+export interface AuditLogger {
+  log(event: Omit<AuditEntry, 'id' | 'timestampMs' | 'entrySignature'>): Promise<void>
+  query(opts?: { type?: AuditEventType; sender?: string; since?: number; limit?: number }): Promise<AuditEntry[]>
+  verify(entry: AuditEntry, publicKey: string): Promise<boolean>
+}
+
+class InMemoryAuditLog implements AuditLogger {
+  private entries: AuditEntry[] = []
+  private privateKey: string
+  private maxEntries: number
+
+  constructor(privateKey: string, maxEntries = 10_000) {
+    this.privateKey = privateKey
+    this.maxEntries = maxEntries
+  }
+
+  async log(event: Omit<AuditEntry, 'id' | 'timestampMs' | 'entrySignature'>): Promise<void> {
+    const id = `audit-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
+    const timestampMs = Date.now()
+
+    const partial: Omit<AuditEntry, 'entrySignature'> = { id, timestampMs, ...event }
+    const payload = canonicalAuditPayload(partial)
+    const entrySignature = await signCanonicalPayloadEd25519(payload, this.privateKey)
+
+    const entry: AuditEntry = { ...partial, entrySignature }
+
+    if (this.entries.length >= this.maxEntries) {
+      this.entries.shift()
+    }
+    this.entries.push(entry)
+  }
+
+  async query(opts?: {
+    type?: AuditEventType
+    sender?: string
+    since?: number
+    limit?: number
+  }): Promise<AuditEntry[]> {
+    let results = [...this.entries]
+
+    if (opts?.type !== undefined) {
+      results = results.filter(e => e.type === opts.type)
+    }
+    if (opts?.sender !== undefined) {
+      results = results.filter(e => e.sender === opts.sender)
+    }
+    if (opts?.since !== undefined) {
+      results = results.filter(e => e.timestampMs >= opts.since!)
+    }
+    if (opts?.limit !== undefined) {
+      results = results.slice(-opts.limit)
+    }
+
+    return results
+  }
+
+  async verify(entry: AuditEntry, publicKey: string): Promise<boolean> {
+    const partial: Omit<AuditEntry, 'entrySignature'> = {
+      id: entry.id,
+      timestampMs: entry.timestampMs,
+      type: entry.type,
+      sender: entry.sender,
+      path: entry.path,
+      method: entry.method,
+      envelopeId: entry.envelopeId,
+      failReason: entry.failReason,
+      upstream: entry.upstream,
+      responseStatus: entry.responseStatus,
+    }
+    const payload = canonicalAuditPayload(partial)
+    return verifyCanonicalPayloadEd25519(payload, entry.entrySignature, publicKey)
+  }
+
+  size(): number {
+    return this.entries.length
+  }
+}
+
+class NoopAuditLog implements AuditLogger {
+  async log(_event: Omit<AuditEntry, 'id' | 'timestampMs' | 'entrySignature'>): Promise<void> {}
+  async query(_opts?: {
+    type?: AuditEventType
+    sender?: string
+    since?: number
+    limit?: number
+  }): Promise<AuditEntry[]> {
+    return []
+  }
+  async verify(_entry: AuditEntry, _publicKey: string): Promise<boolean> {
+    return false
+  }
+  size(): number {
+    return 0
+  }
+}
+
+export function createAuditLog(privateKey: string, opts?: { maxEntries?: number }): InMemoryAuditLog {
+  return new InMemoryAuditLog(privateKey, opts?.maxEntries)
+}
+
+export { InMemoryAuditLog, NoopAuditLog }