@7h3/protocol 0.5.0 → 0.5.2

package/src/protocolFuzz.advanced.test.ts

@@ -1,235 +0,0 @@
-/**
- * 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

@@ -1,111 +0,0 @@
-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

@@ -1,97 +0,0 @@
-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

@@ -1,71 +0,0 @@
-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])
-  })
-})