@7h3/protocol 0.1.2 → 0.4.0

package/src/protocolFuzz.advanced.test.ts

@@ -0,0 +1,235 @@
+/**
+ * Property-based fuzz tests using fast-check.
+ *
+ * Area 1: Wire decoder resilience — decodeEnvelope must never throw on arbitrary
+ *         string or Uint8Array input; it must always return {ok: false} on garbage.
+ *
+ * Area 2: Canonicalization determinism — canonicalizeEnvelope must be pure and
+ *         stable: calling it twice on the same envelope returns the same string,
+ *         and reordering the object's fields has no effect.
+ *
+ * Area 3: Replay cache idempotency — for any (sender, messageId, nonce) triple
+ *         the first consume() is ok:true and a second is ok:false, provided the
+ *         key is unique in the cache. Key collision via the "|" separator is
+ *         handled explicitly (see comment below).
+ */
+
+import * as fc from 'fast-check'
+import { describe, expect, it } from 'vitest'
+import { canonicalizeEnvelope } from './protocol'
+import type { ProtocolBody, ProtocolHeader } from './protocol'
+import { InMemoryReplayCache } from './protocolReplay'
+import { decodeEnvelope } from './protocolTransport'
+
+// ---------------------------------------------------------------------------
+// Area 1 — Wire decoder resilience
+// ---------------------------------------------------------------------------
+
+describe('decodeEnvelope resilience (property-based)', () => {
+  it('never throws on arbitrary string input — always returns {ok}', () => {
+    fc.assert(
+      fc.property(fc.string(), (raw) => {
+        let result: ReturnType<typeof decodeEnvelope>
+        expect(() => {
+          result = decodeEnvelope(raw)
+        }).not.toThrow()
+        // Must have an `ok` boolean — when the string is garbage it will be false.
+        expect(typeof result!.ok).toBe('boolean')
+      }),
+    )
+  })
+
+  it('never throws on arbitrary Uint8Array input — always returns {ok}', () => {
+    fc.assert(
+      fc.property(fc.uint8Array({ maxLength: 512 }), (bytes) => {
+        let result: ReturnType<typeof decodeEnvelope>
+        expect(() => {
+          result = decodeEnvelope(bytes)
+        }).not.toThrow()
+        expect(typeof result!.ok).toBe('boolean')
+      }),
+    )
+  })
+
+  it('returns ok:false (not throws) for partial JSON strings', () => {
+    // Strings that begin like JSON but are truncated or malformed.
+    fc.assert(
+      fc.property(
+        fc.oneof(
+          // Truncated JSON
+          fc.string({ maxLength: 20 }).map((s) => '{' + s),
+          // Random non-JSON
+          fc.string({ minLength: 1, maxLength: 64 }).filter((s) => {
+            try {
+              JSON.parse(s)
+              return false
+            } catch {
+              return true
+            }
+          }),
+        ),
+        (raw) => {
+          const result = decodeEnvelope(raw)
+          expect(result.ok).toBe(false)
+        },
+      ),
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Area 2 — Canonicalization determinism
+// ---------------------------------------------------------------------------
+
+/** Arbitraries for the valid types in headers and bodies. */
+const intentKindArb = fc.constantFrom(
+  'PING' as const,
+  'PONG' as const,
+  'CAPS' as const,
+  'TASK' as const,
+  'RESULT' as const,
+  'ERROR' as const,
+)
+
+const headerArb: fc.Arbitrary<ProtocolHeader> = fc.record({
+  version: fc.constant('7h3/0.1' as const),
+  messageId: fc.string({ minLength: 1, maxLength: 64 }),
+  timestampMs: fc.integer({ min: 0, max: Number.MAX_SAFE_INTEGER }),
+  ttlMs: fc.integer({ min: 1, max: 86_400_000 }),
+  sender: fc.string({ minLength: 1, maxLength: 64 }),
+  nonce: fc.string({ minLength: 1, maxLength: 32 }),
+  // recipient is optional — generate it or leave it undefined
+  recipient: fc.option(fc.string({ minLength: 1, maxLength: 64 }), { nil: undefined }),
+})
+
+const bodyArb: fc.Arbitrary<ProtocolBody> = fc.record({
+  intent: intentKindArb,
+  content: fc.string({ maxLength: 256 }),
+  capability: fc.option(fc.string({ minLength: 1, maxLength: 64 }), { nil: undefined }),
+  correlationId: fc.option(fc.string({ minLength: 1, maxLength: 64 }), { nil: undefined }),
+})
+
+describe('canonicalizeEnvelope determinism (property-based)', () => {
+  it('returns the same string when called twice on the same envelope', () => {
+    fc.assert(
+      fc.property(headerArb, bodyArb, (header, body) => {
+        const envelope = { header, body }
+        expect(canonicalizeEnvelope(envelope)).toBe(canonicalizeEnvelope(envelope))
+      }),
+    )
+  })
+
+  it('is not affected by key insertion order in the header object', () => {
+    fc.assert(
+      fc.property(headerArb, bodyArb, (header, body) => {
+        // Build a structurally identical header whose keys are inserted in reverse
+        // order to the one produced by headerArb.
+        const reversedHeader: ProtocolHeader = Object.fromEntries(
+          Object.entries(header).reverse(),
+        ) as unknown as ProtocolHeader
+
+        const canonical = canonicalizeEnvelope({ header, body })
+        const canonicalReversed = canonicalizeEnvelope({ header: reversedHeader, body })
+        expect(canonical).toBe(canonicalReversed)
+      }),
+    )
+  })
+
+  it('is not affected by key insertion order in the body object', () => {
+    fc.assert(
+      fc.property(headerArb, bodyArb, (header, body) => {
+        const reversedBody: ProtocolBody = Object.fromEntries(
+          Object.entries(body).reverse(),
+        ) as unknown as ProtocolBody
+
+        const canonical = canonicalizeEnvelope({ header, body })
+        const canonicalReversed = canonicalizeEnvelope({ header, body: reversedBody })
+        expect(canonical).toBe(canonicalReversed)
+      }),
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Area 3 — Replay cache properties
+// ---------------------------------------------------------------------------
+
+/**
+ * The InMemoryReplayCache key is built as `${sender}|${messageId}|${nonce}`.
+ * Because the separator is unescaped, two distinct (sender, messageId, nonce)
+ * triples can map to the same cache key — e.g. ("a|b", "c", "d") and
+ * ("a", "b|c", "d") both yield "a|b|c|d".  We track seen keys ourselves
+ * using the same join rule so our assertions match what the cache actually does.
+ */
+function replayCacheKey(sender: string, messageId: string, nonce: string): string {
+  return `${sender}|${messageId}|${nonce}`
+}
+
+const tripleArb = fc.record({
+  sender: fc.string({ maxLength: 32 }),
+  messageId: fc.string({ maxLength: 32 }),
+  nonce: fc.string({ maxLength: 32 }),
+})
+
+/** Build a minimal ProtocolEnvelope skeleton sufficient for InMemoryReplayCache.consume(). */
+function makeEnvelope(sender: string, messageId: string, nonce: string, nowMs: number) {
+  return {
+    header: {
+      version: '7h3/0.1' as const,
+      sender,
+      messageId,
+      nonce,
+      timestampMs: nowMs,
+      ttlMs: 600_000, // 10 min — ensures entry lives well past both consume() calls
+      recipient: undefined,
+    },
+    body: {
+      intent: 'PING' as const,
+      content: '',
+    },
+  }
+}
+
+describe('InMemoryReplayCache properties (property-based)', () => {
+  it('first consume() ok:true, second consume() ok:false for any unique triple', () => {
+    fc.assert(
+      fc.property(tripleArb, ({ sender, messageId, nonce }) => {
+        const cache = new InMemoryReplayCache()
+        const nowMs = 1_700_000_000_000
+        const envelope = makeEnvelope(sender, messageId, nonce, nowMs)
+
+        const first = cache.consume(envelope, nowMs)
+        expect(first.ok).toBe(true)
+
+        const second = cache.consume(envelope, nowMs)
+        expect(second.ok).toBe(false)
+      }),
+    )
+  })
+
+  it('for a sequence of triples: first reserve for a key is ok:true, repeat is ok:false', () => {
+    fc.assert(
+      fc.property(fc.array(tripleArb, { minLength: 1, maxLength: 20 }), (triples) => {
+        const cache = new InMemoryReplayCache()
+        const nowMs = 1_700_000_000_000
+        // Track which keys the cache has already seen (mirrors makeKey internals).
+        const seenKeys = new Set<string>()
+
+        for (const { sender, messageId, nonce } of triples) {
+          const key = replayCacheKey(sender, messageId, nonce)
+          const envelope = makeEnvelope(sender, messageId, nonce, nowMs)
+          const result = cache.consume(envelope, nowMs)
+
+          if (seenKeys.has(key)) {
+            // Cache already has this key — must be rejected as replay.
+            expect(result.ok).toBe(false)
+          } else {
+            // First time this key is presented — must be accepted.
+            expect(result.ok).toBe(true)
+            seenKeys.add(key)
+          }
+        }
+      }),
+    )
+  })
+})

package/src/protocolFuzz.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest'
+import { canonicalizeEnvelope, createEnvelope, signEnvelopeHmac, verifyEnvelopeHmac } from './protocol'
+import { InMemoryReplayCache } from './protocolReplay'
+import { decodeEnvelope, encodeEnvelope, receiveEnvelope } from './protocolTransport'
+
+function seededRandom(seed: number): () => number {
+  let state = seed >>> 0
+  return () => {
+    state = (1664525 * state + 1013904223) >>> 0
+    return state / 0xffffffff
+  }
+}
+
+function randomText(rand: () => number, length: number): string {
+  const alphabet = 'abcdefghijklmnopqrstuvwxyz0123456789:-_/'
+  let out = ''
+  for (let i = 0; i < length; i += 1) {
+    out += alphabet[Math.floor(rand() * alphabet.length)]
+  }
+  return out
+}
+
+describe('AIP property and fuzz checks', () => {
+  it('keeps canonicalization and signed roundtrip stable for random envelopes', async () => {
+    const rand = seededRandom(0xdecafbad)
+
+    for (let i = 0; i < 200; i += 1) {
+      const nowMs = 1_700_000_000_000 + i
+      const envelope = createEnvelope({
+        sender: `agent.${randomText(rand, 6)}`,
+        recipient: rand() > 0.5 ? `agent.${randomText(rand, 5)}` : undefined,
+        intent: rand() > 0.5 ? 'TASK' : 'RESULT',
+        content: randomText(rand, 64),
+        capability: rand() > 0.6 ? `task.${randomText(rand, 5)}` : undefined,
+        correlationId: rand() > 0.4 ? `corr-${randomText(rand, 8)}` : undefined,
+        messageId: `fuzz-${i}-${randomText(rand, 8)}`,
+        nonce: `n-${i}-${randomText(rand, 8)}`,
+        nowMs,
+        ttlMs: 10_000 + Math.floor(rand() * 20_000),
+      })
+
+      const canonicalA = canonicalizeEnvelope(envelope)
+      const canonicalB = canonicalizeEnvelope({ header: envelope.header, body: envelope.body })
+      expect(canonicalA).toBe(canonicalB)
+
+      const signed = await signEnvelopeHmac(envelope, 'fuzz-shared-secret', 'fuzz-k1')
+      expect(await verifyEnvelopeHmac(signed, 'fuzz-shared-secret')).toBe(true)
+
+      const encoded = encodeEnvelope(signed, rand() > 0.5 ? 'compact' : 'json')
+      const decoded = decodeEnvelope(encoded)
+      expect(decoded.ok).toBe(true)
+      expect(decoded.envelope).toEqual(signed)
+
+      const received = await receiveEnvelope(encoded, {
+        nowMs: nowMs + 1,
+        replayCache: new InMemoryReplayCache(),
+        secretResolver: async () => 'fuzz-shared-secret',
+      })
+      expect(received.ok).toBe(true)
+    }
+  })
+
+  it('rejects fuzzed malformed or tampered payloads', async () => {
+    const rand = seededRandom(0xabad1dea)
+    const base = await signEnvelopeHmac(
+      createEnvelope({
+        sender: 'agent.fuzz',
+        recipient: 'agent.verify',
+        intent: 'TASK',
+        content: 'fuzz-base',
+        messageId: 'fuzz-base-1',
+        nonce: 'fuzz-base-n1',
+        nowMs: 1_700_000_001_000,
+        ttlMs: 60_000,
+      }),
+      'fuzz-shared-secret',
+      'fuzz-k1',
+    )
+
+    const malformedPayloads = ['{', '[]', '{"v":"7h3/0.1"}', '{"header":{},"body":{}}', '{"hello":"world"}']
+    for (const raw of malformedPayloads) {
+      const result = await receiveEnvelope(raw, {
+        nowMs: 1_700_000_001_001,
+        replayCache: new InMemoryReplayCache(),
+        secretResolver: async () => 'fuzz-shared-secret',
+      })
+      expect(result.ok).toBe(false)
+    }
+
+    for (let i = 0; i < 120; i += 1) {
+      const compact = JSON.parse(encodeEnvelope(base, 'compact')) as {
+        sig?: { a?: string; k: string; v: string }
+      }
+      if (!compact.sig) throw new Error('expected signature in compact envelope')
+
+      const index = Math.floor(rand() * compact.sig.v.length)
+      const current = compact.sig.v[index] ?? 'A'
+      const replacement = current === 'A' ? 'B' : 'A'
+      compact.sig.v = `${compact.sig.v.slice(0, index)}${replacement}${compact.sig.v.slice(index + 1)}`
+      const tampered = JSON.stringify(compact)
+
+      const result = await receiveEnvelope(tampered, {
+        nowMs: 1_700_000_001_001,
+        replayCache: new InMemoryReplayCache(),
+        secretResolver: async () => 'fuzz-shared-secret',
+      })
+      expect(result.ok).toBe(false)
+      expect(result.diagnostics.some((d) => d.message === 'Signature verification failed')).toBe(true)
+    }
+  })
+})

package/src/protocolNegative.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest'
+import { createEnvelope, generateEd25519KeypairBase64Url, signEnvelopeEd25519, signEnvelopeHmac } from './protocol'
+import { InMemoryReplayCache } from './protocolReplay'
+import { decodeEnvelope, decodeEnvelopeBatch, encodeEnvelope, receiveEnvelope } from './protocolTransport'
+
+describe('AIP negative corpus', () => {
+  it('rejects invalid JSON envelopes', () => {
+    const decoded = decodeEnvelope('{invalid-json')
+    expect(decoded.ok).toBe(false)
+    expect(decoded.diagnostics.some((d) => d.message === 'Invalid JSON envelope')).toBe(true)
+  })
+
+  it('rejects unknown envelope shape', () => {
+    const decoded = decodeEnvelope(JSON.stringify({ hello: 'world' }))
+    expect(decoded.ok).toBe(false)
+    expect(decoded.diagnostics.some((d) => d.message.includes('shape is not recognized'))).toBe(true)
+  })
+
+  it('rejects batch payload that is not an array', () => {
+    const decoded = decodeEnvelopeBatch(JSON.stringify({ not: 'array' }))
+    expect(decoded).toHaveLength(1)
+    expect(decoded[0]?.ok).toBe(false)
+    expect(decoded[0]?.diagnostics.some((d) => d.message.includes('must be a JSON array'))).toBe(true)
+  })
+
+  it('rejects unsigned envelopes when signatures are required', async () => {
+    const unsigned = createEnvelope({
+      sender: 'agent.alpha',
+      intent: 'TASK',
+      content: 'unsigned',
+      messageId: 'neg-unsigned-1',
+      nonce: 'neg-unsigned-n1',
+      nowMs: 1000,
+      ttlMs: 60_000,
+    })
+
+    const result = await receiveEnvelope(encodeEnvelope(unsigned), {
+      nowMs: 1001,
+      replayCache: new InMemoryReplayCache(),
+      requireSignature: true,
+    })
+
+    expect(result.ok).toBe(false)
+    expect(result.diagnostics.some((d) => d.message === 'Missing signature')).toBe(true)
+  })
+
+  it('rejects signature when verification material algorithm mismatches', async () => {
+    const signed = await signEnvelopeHmac(
+      createEnvelope({
+        sender: 'agent.alpha',
+        intent: 'PING',
+        content: 'alg-mismatch',
+        messageId: 'neg-alg-1',
+        nonce: 'neg-alg-n1',
+        nowMs: 1000,
+        ttlMs: 60_000,
+      }),
+      'shared-secret',
+      'k1',
+    )
+
+    const result = await receiveEnvelope(encodeEnvelope(signed), {
+      nowMs: 1001,
+      replayCache: new InMemoryReplayCache(),
+      signatureResolver: async () => ({ alg: 'ED25519', publicKey: 'not-a-valid-ed25519-key' }),
+    })
+
+    expect(result.ok).toBe(false)
+    expect(result.diagnostics.some((d) => d.message === 'Signature verification failed')).toBe(true)
+  })
+
+  it('rejects ED25519 envelopes with missing verification material', async () => {
+    const keys = await generateEd25519KeypairBase64Url()
+    const signed = await signEnvelopeEd25519(
+      createEnvelope({
+        sender: 'agent.alpha',
+        intent: 'TASK',
+        content: 'needs-ed25519-material',
+        messageId: 'neg-ed-1',
+        nonce: 'neg-ed-n1',
+        nowMs: 1000,
+        ttlMs: 60_000,
+      }),
+      keys.privateKey,
+      'ed-k1',
+    )
+
+    const result = await receiveEnvelope(encodeEnvelope(signed, 'compact'), {
+      nowMs: 1001,
+      replayCache: new InMemoryReplayCache(),
+      secretResolver: async () => 'shared-secret',
+    })
+
+    expect(result.ok).toBe(false)
+    expect(result.diagnostics.some((d) => d.message.includes('No signature verification material'))).toBe(true)
+  })
+})

package/src/protocolReplay.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest'
+import { createEnvelope } from './protocol'
+import { InMemoryReplayCache } from './protocolReplay'
+
+describe('InMemoryReplayCache', () => {
+  it('rejects replays until ttl expires', () => {
+    const cache = new InMemoryReplayCache(100)
+    const envelope = createEnvelope({
+      sender: 'agent.alpha',
+      intent: 'PING',
+      content: 'hello',
+      messageId: 'r1',
+      nonce: 'n1',
+      nowMs: 1000,
+      ttlMs: 100,
+    })
+
+    expect(cache.consume(envelope, 1001).ok).toBe(true)
+    expect(cache.consume(envelope, 1002).ok).toBe(false)
+    expect(cache.consume(envelope, 1101).ok).toBe(true)
+  })
+
+  it('evicts by expiry order when capacity is reached', () => {
+    const cache = new InMemoryReplayCache(2)
+    const first = createEnvelope({
+      sender: 'agent.alpha',
+      intent: 'PING',
+      content: 'one',
+      messageId: 'r2-1',
+      nonce: 'n1',
+      nowMs: 1000,
+      ttlMs: 10,
+    })
+    const second = createEnvelope({
+      sender: 'agent.alpha',
+      intent: 'PING',
+      content: 'two',
+      messageId: 'r2-2',
+      nonce: 'n2',
+      nowMs: 1000,
+      ttlMs: 1000,
+    })
+    const third = createEnvelope({
+      sender: 'agent.alpha',
+      intent: 'PING',
+      content: 'three',
+      messageId: 'r2-3',
+      nonce: 'n3',
+      nowMs: 1000,
+      ttlMs: 1000,
+    })
+
+    expect(cache.consume(first, 1001).ok).toBe(true)
+    expect(cache.consume(second, 1001).ok).toBe(true)
+    expect(cache.consume(third, 1001).ok).toBe(true)
+
+    // first key should be evicted or expired first; re-consuming at same window should be accepted
+    expect(cache.consume(first, 1002).ok).toBe(true)
+  })
+
+  it('bulk consumes envelopes and rejects duplicates in order', () => {
+    const cache = new InMemoryReplayCache(100)
+    const first = createEnvelope({ sender: 'agent.alpha', intent: 'PING', content: 'one', messageId: 'bulk-1', nonce: 'n1', nowMs: 1000, ttlMs: 1000 })
+    const duplicate = createEnvelope({ sender: 'agent.alpha', intent: 'PING', content: 'one-again', messageId: 'bulk-1', nonce: 'n1', nowMs: 1000, ttlMs: 1000 })
+    const second = createEnvelope({ sender: 'agent.alpha', intent: 'PING', content: 'two', messageId: 'bulk-2', nonce: 'n2', nowMs: 1000, ttlMs: 1000 })
+
+    const results = cache.consumeMany([first, duplicate, second], 1001)
+
+    expect(results.map((result) => result.ok)).toEqual([true, false, true])
+  })
+})