@7h3/protocol 0.1.2 → 0.5.0

package/src/telemetry.test.ts

@@ -0,0 +1,251 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import {
+  SimpleCounter,
+  SimpleHistogram,
+  Protocol7h3Metrics,
+  renderPrometheusText,
+  createMetricsMiddleware,
+} from './telemetry'
+
+// ─── 1. Counter increments correctly with labels ──────────────────────────────
+
+describe('SimpleCounter with labels', () => {
+  it('increments independently per label set', () => {
+    const counter = new SimpleCounter()
+    counter.increment({ result: 'ok', alg: 'ED25519' })
+    counter.increment({ result: 'ok', alg: 'ED25519' })
+    counter.increment({ result: 'fail', alg: 'HS256' })
+
+    expect(counter.value({ result: 'ok', alg: 'ED25519' })).toBe(2)
+    expect(counter.value({ result: 'fail', alg: 'HS256' })).toBe(1)
+    expect(counter.value({ result: 'ok', alg: 'HS256' })).toBe(0)
+  })
+
+  it('label order does not affect key identity', () => {
+    const counter = new SimpleCounter()
+    counter.increment({ a: '1', b: '2' })
+    counter.increment({ b: '2', a: '1' })
+    expect(counter.value({ a: '1', b: '2' })).toBe(2)
+    expect(counter.value({ b: '2', a: '1' })).toBe(2)
+  })
+})
+
+// ─── 2. Counter with no labels increments the default bucket ─────────────────
+
+describe('SimpleCounter with no labels', () => {
+  it('starts at 0', () => {
+    const counter = new SimpleCounter()
+    expect(counter.value()).toBe(0)
+  })
+
+  it('increments the default bucket', () => {
+    const counter = new SimpleCounter()
+    counter.increment()
+    counter.increment()
+    counter.increment()
+    expect(counter.value()).toBe(3)
+    // labeled lookup returns 0 — separate bucket
+    expect(counter.value({ x: '1' })).toBe(0)
+  })
+})
+
+// ─── 3. Histogram records observations and buckets correctly ─────────────────
+
+describe('SimpleHistogram', () => {
+  it('counts observations into correct buckets', () => {
+    const h = new SimpleHistogram([1, 5, 10, 50, 100])
+    h.observe(0.5)
+    h.observe(3)
+    h.observe(7)
+    h.observe(75)
+    h.observe(200)
+
+    const snap = h.snapshot()
+    // ≤1: 0.5 → 1
+    expect(snap.buckets['1']).toBe(1)
+    // ≤5: 0.5, 3 → 2
+    expect(snap.buckets['5']).toBe(2)
+    // ≤10: 0.5, 3, 7 → 3
+    expect(snap.buckets['10']).toBe(3)
+    // ≤50: 0.5, 3, 7 → 3
+    expect(snap.buckets['50']).toBe(3)
+    // ≤100: 0.5, 3, 7, 75 → 4
+    expect(snap.buckets['100']).toBe(4)
+    // +Inf: all 5
+    expect(snap.buckets['+Inf']).toBe(5)
+    expect(snap.count).toBe(5)
+    expect(snap.sum).toBeCloseTo(0.5 + 3 + 7 + 75 + 200)
+  })
+
+  it('tracks per-label state independently', () => {
+    const h = new SimpleHistogram([10])
+    h.observe(5, { transport: 'http' })
+    h.observe(15, { transport: 'ws' })
+
+    const snapHttp = h.snapshot({ transport: 'http' })
+    expect(snapHttp.count).toBe(1)
+    expect(snapHttp.buckets['10']).toBe(1)
+
+    const snapWs = h.snapshot({ transport: 'ws' })
+    expect(snapWs.count).toBe(1)
+    expect(snapWs.buckets['10']).toBe(0)
+  })
+
+  it('returns zero snapshot for unseen labels', () => {
+    const h = new SimpleHistogram([1, 5])
+    const snap = h.snapshot({ transport: 'grpc' })
+    expect(snap.count).toBe(0)
+    expect(snap.sum).toBe(0)
+    expect(snap.buckets['+Inf']).toBe(0)
+  })
+})
+
+// ─── 4. renderPrometheusText produces valid Prometheus format ─────────────────
+
+describe('renderPrometheusText', () => {
+  it('contains # HELP, # TYPE, and metric lines', () => {
+    const m = new Protocol7h3Metrics()
+    m.verifications_total.increment({ result: 'ok', alg: 'ED25519', transport: 'http' })
+    m.verifications_total.increment({ result: 'ok', alg: 'ED25519', transport: 'http' })
+    m.verifications_total.increment({ result: 'fail', alg: 'none', transport: 'http' })
+    m.verification_duration_ms.observe(2.5)
+
+    const text = renderPrometheusText(m)
+
+    expect(text).toMatch(/# HELP 7h3_verifications_total /)
+    expect(text).toMatch(/# TYPE 7h3_verifications_total counter/)
+    expect(text).toMatch(/7h3_verifications_total\{.*result="ok".*\} 2/)
+    expect(text).toMatch(/7h3_verifications_total\{.*result="fail".*\} 1/)
+    expect(text).toMatch(/# HELP 7h3_verification_duration_ms /)
+    expect(text).toMatch(/# TYPE 7h3_verification_duration_ms histogram/)
+    expect(text).toMatch(/7h3_verification_duration_ms_bucket\{.*le="\+Inf".*\} 1/)
+    expect(text).toMatch(/7h3_verification_duration_ms_count 1/)
+  })
+
+  it('respects a custom prefix', () => {
+    const m = new Protocol7h3Metrics()
+    m.rate_limit_hits_total.increment({ sender: 'agent-a', path: '/api' })
+    const text = renderPrometheusText(m, 'myapp')
+    expect(text).toMatch(/# HELP myapp_verifications_total/)
+    expect(text).toMatch(/myapp_rate_limit_hits_total/)
+  })
+
+  it('all expected metric names appear', () => {
+    const m = new Protocol7h3Metrics()
+    const text = renderPrometheusText(m)
+    const expectedNames = [
+      '7h3_verifications_total',
+      '7h3_verification_duration_ms',
+      '7h3_rate_limit_hits_total',
+      '7h3_sender_denials_total',
+      '7h3_replay_detections_total',
+      '7h3_audit_entries_total',
+      '7h3_active_connections',
+    ]
+    for (const name of expectedNames) {
+      expect(text).toContain(`# HELP ${name}`)
+    }
+  })
+
+  it('ends with a newline', () => {
+    const m = new Protocol7h3Metrics()
+    const text = renderPrometheusText(m)
+    expect(text.endsWith('\n')).toBe(true)
+  })
+})
+
+// ─── 5. metrics.verifications_total increments on gateway verify calls ────────
+
+describe('Protocol7h3Metrics integration via gateway verify', () => {
+  it('increments verifications_total on skip-verify path (allow policy)', async () => {
+    // Import gateway dynamically to get a fresh reference to globalMetrics
+    // We directly test Protocol7h3Metrics counting logic by simulating the verify flow
+    const m = new Protocol7h3Metrics()
+
+    // Simulate a successful skip-verify (allow-all gateway)
+    m.verifications_total.increment({ result: 'ok', alg: 'none', transport: 'http' })
+
+    expect(m.verifications_total.value({ result: 'ok', alg: 'none', transport: 'http' })).toBe(1)
+    expect(m.verifications_total.value({ result: 'fail', alg: 'none', transport: 'http' })).toBe(0)
+  })
+
+  it('increments verifications_total fail on rate-limit', async () => {
+    const m = new Protocol7h3Metrics()
+
+    // Simulate a rate-limit hit
+    m.verifications_total.increment({ result: 'fail', alg: 'ED25519', transport: 'http' })
+    m.rate_limit_hits_total.increment({ sender: 'agent-x', path: '/api/data' })
+
+    expect(m.verifications_total.value({ result: 'fail', alg: 'ED25519', transport: 'http' })).toBe(1)
+    expect(m.rate_limit_hits_total.value({ sender: 'agent-x', path: '/api/data' })).toBe(1)
+  })
+
+  it('increments sender_denials_total on 403', async () => {
+    const m = new Protocol7h3Metrics()
+
+    m.verifications_total.increment({ result: 'fail', alg: 'ED25519', transport: 'http' })
+    m.sender_denials_total.increment({ sender: 'rogue-agent', path: '/admin' })
+
+    expect(m.sender_denials_total.value({ sender: 'rogue-agent', path: '/admin' })).toBe(1)
+    expect(m.verifications_total.value({ result: 'fail', alg: 'ED25519', transport: 'http' })).toBe(1)
+  })
+
+  it('records duration in verification_duration_ms', () => {
+    const m = new Protocol7h3Metrics()
+
+    m.verification_duration_ms.observe(0.3)
+    m.verification_duration_ms.observe(2.0)
+    m.verification_duration_ms.observe(120)
+
+    const snap = m.verification_duration_ms.snapshot()
+    expect(snap.count).toBe(3)
+    expect(snap.sum).toBeCloseTo(0.3 + 2.0 + 120)
+    // 0.3 ≤ 0.5 → should appear in bucket 0.5
+    expect(snap.buckets['0.5']).toBe(1)
+    // +Inf must be count
+    expect(snap.buckets['+Inf']).toBe(3)
+  })
+})
+
+// ─── 6. createMetricsMiddleware serves metrics ────────────────────────────────
+
+describe('createMetricsMiddleware', () => {
+  it('serves Prometheus text at /metrics', () => {
+    const m = new Protocol7h3Metrics()
+    m.verifications_total.increment({ result: 'ok', alg: 'ED25519', transport: 'http' })
+    const middleware = createMetricsMiddleware('/metrics', m)
+
+    let status = 0
+    let body = ''
+    let headers: Record<string, string> = {}
+    const req = { url: '/metrics', method: 'GET' }
+    const res = {
+      writeHead(s: number, h: Record<string, string>) { status = s; headers = h },
+      end(b: string) { body = b },
+    }
+    let nextCalled = false
+    const next = () => { nextCalled = true }
+
+    middleware(req, res, next)
+
+    expect(status).toBe(200)
+    expect(headers['content-type']).toMatch(/text\/plain/)
+    expect(body).toContain('# HELP 7h3_verifications_total')
+    expect(nextCalled).toBe(false)
+  })
+
+  it('calls next() for non-metrics paths', () => {
+    const m = new Protocol7h3Metrics()
+    const middleware = createMetricsMiddleware('/metrics', m)
+
+    let nextCalled = false
+    const req = { url: '/api/data', method: 'GET' }
+    const res = {
+      writeHead() {},
+      end() {},
+    }
+    middleware(req, res, () => { nextCalled = true })
+
+    expect(nextCalled).toBe(true)
+  })
+})

package/src/telemetry.ts

@@ -0,0 +1,299 @@
+/**
+ * telemetry.ts — Prometheus metrics for 7h3 Protocol
+ *
+ * Zero runtime dependencies. Plain in-memory counters and histograms rendered
+ * to standard Prometheus text exposition format.
+ */
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface TelemetryConfig {
+  enabled?: boolean
+  prefix?: string // default '7h3'
+}
+
+export interface Counter {
+  increment(labels?: Record<string, string>): void
+  value(labels?: Record<string, string>): number
+}
+
+export interface HistogramSnapshot {
+  count: number
+  sum: number
+  buckets: Record<string, number> // upper bound (as string) → cumulative count
+}
+
+export interface Histogram {
+  observe(value: number, labels?: Record<string, string>): void
+  snapshot(labels?: Record<string, string>): HistogramSnapshot
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function labelKey(labels?: Record<string, string>): string {
+  if (!labels || Object.keys(labels).length === 0) return '__default__'
+  return Object.entries(labels)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([k, v]) => `${k}=${v}`)
+    .join(',')
+}
+
+function renderLabels(labels?: Record<string, string>): string {
+  if (!labels || Object.keys(labels).length === 0) return ''
+  const parts = Object.entries(labels)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([k, v]) => `${k}="${v}"`)
+  return `{${parts.join(',')}}`
+}
+
+// ─── SimpleCounter ────────────────────────────────────────────────────────────
+
+export class SimpleCounter implements Counter {
+  private counts = new Map<string, number>()
+  private labelSets = new Map<string, Record<string, string> | undefined>()
+
+  increment(labels?: Record<string, string>): void {
+    const key = labelKey(labels)
+    this.counts.set(key, (this.counts.get(key) ?? 0) + 1)
+    if (!this.labelSets.has(key)) {
+      this.labelSets.set(key, labels)
+    }
+  }
+
+  value(labels?: Record<string, string>): number {
+    return this.counts.get(labelKey(labels)) ?? 0
+  }
+
+  entries(): Array<{ labels?: Record<string, string>; value: number }> {
+    const result: Array<{ labels?: Record<string, string>; value: number }> = []
+    for (const [key, value] of this.counts) {
+      result.push({ labels: this.labelSets.get(key), value })
+    }
+    return result
+  }
+}
+
+// ─── SimpleHistogram ──────────────────────────────────────────────────────────
+
+interface BucketState {
+  count: number
+  sum: number
+  // bucket upper bounds → cumulative count (populated on snapshot)
+  observations: number[]
+}
+
+export class SimpleHistogram implements Histogram {
+  private bucketBounds: number[]
+  private states = new Map<string, BucketState>()
+  private labelSets = new Map<string, Record<string, string> | undefined>()
+
+  constructor(buckets: number[] = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]) {
+    this.bucketBounds = [...buckets].sort((a, b) => a - b)
+  }
+
+  observe(value: number, labels?: Record<string, string>): void {
+    const key = labelKey(labels)
+    if (!this.states.has(key)) {
+      this.states.set(key, { count: 0, sum: 0, observations: [] })
+      this.labelSets.set(key, labels)
+    }
+    const state = this.states.get(key)!
+    state.count++
+    state.sum += value
+    state.observations.push(value)
+  }
+
+  snapshot(labels?: Record<string, string>): HistogramSnapshot {
+    const key = labelKey(labels)
+    const state = this.states.get(key) ?? { count: 0, sum: 0, observations: [] }
+
+    const buckets: Record<string, number> = {}
+    for (const bound of this.bucketBounds) {
+      buckets[String(bound)] = state.observations.filter(v => v <= bound).length
+    }
+    // +Inf bucket
+    buckets['+Inf'] = state.count
+
+    return { count: state.count, sum: state.sum, buckets }
+  }
+
+  entries(): Array<{ labels?: Record<string, string>; snapshot: HistogramSnapshot }> {
+    const result: Array<{ labels?: Record<string, string>; snapshot: HistogramSnapshot }> = []
+    for (const [key] of this.states) {
+      const labels = this.labelSets.get(key)
+      result.push({ labels, snapshot: this.snapshot(labels) })
+    }
+    return result
+  }
+
+  getBounds(): number[] {
+    return [...this.bucketBounds]
+  }
+}
+
+// ─── Protocol7h3Metrics ───────────────────────────────────────────────────────
+
+export class Protocol7h3Metrics {
+  /** labels: result (ok|fail), alg (ED25519|HS256|none), transport (http|ws|grpc|queue|webhook) */
+  verifications_total = new SimpleCounter()
+
+  /** buckets in ms */
+  verification_duration_ms = new SimpleHistogram([0.1, 0.5, 1, 5, 10, 50, 100])
+
+  /** labels: sender, path */
+  rate_limit_hits_total = new SimpleCounter()
+
+  /** labels: sender, path */
+  sender_denials_total = new SimpleCounter()
+
+  /** labels: transport */
+  replay_detections_total = new SimpleCounter()
+
+  /** labels: type */
+  audit_entries_total = new SimpleCounter()
+
+  /** labels: transport — use for WS/gRPC connection tracking */
+  active_connections = new SimpleCounter()
+}
+
+// ─── Global instance ──────────────────────────────────────────────────────────
+
+export const metrics = new Protocol7h3Metrics()
+
+// ─── Prometheus text format renderer ─────────────────────────────────────────
+
+export function renderPrometheusText(m: Protocol7h3Metrics, prefix = '7h3'): string {
+  const lines: string[] = []
+
+  // Helper: emit a counter
+  function emitCounter(name: string, help: string, counter: SimpleCounter): void {
+    const fullName = `${prefix}_${name}`
+    lines.push(`# HELP ${fullName} ${help}`)
+    lines.push(`# TYPE ${fullName} counter`)
+    const entries = counter.entries()
+    if (entries.length === 0) {
+      lines.push(`${fullName} 0`)
+    } else {
+      for (const { labels, value } of entries) {
+        if (labels && Object.keys(labels).length > 0) {
+          lines.push(`${fullName}${renderLabels(labels)} ${value}`)
+        } else {
+          lines.push(`${fullName} ${value}`)
+        }
+      }
+    }
+  }
+
+  // Helper: emit a histogram
+  function emitHistogram(name: string, help: string, histogram: SimpleHistogram): void {
+    const fullName = `${prefix}_${name}`
+    lines.push(`# HELP ${fullName} ${help}`)
+    lines.push(`# TYPE ${fullName} histogram`)
+    const entries = histogram.entries()
+    if (entries.length === 0) {
+      // Emit empty histogram with zero counts
+      for (const bound of histogram.getBounds()) {
+        lines.push(`${fullName}_bucket{le="${bound}"} 0`)
+      }
+      lines.push(`${fullName}_bucket{le="+Inf"} 0`)
+      lines.push(`${fullName}_sum 0`)
+      lines.push(`${fullName}_count 0`)
+    } else {
+      for (const { labels, snapshot } of entries) {
+        const labelStr = labels && Object.keys(labels).length > 0
+          ? renderLabels(labels)
+          : ''
+
+        for (const [bound, count] of Object.entries(snapshot.buckets)) {
+          if (bound === '+Inf') continue
+          const bucketLabels = labelStr
+            ? labelStr.slice(0, -1) + `,le="${bound}"}`
+            : `{le="${bound}"}`
+          lines.push(`${fullName}_bucket${bucketLabels} ${count}`)
+        }
+        // +Inf bucket
+        const infLabels = labelStr
+          ? labelStr.slice(0, -1) + `,le="+Inf"}`
+          : `{le="+Inf"}`
+        lines.push(`${fullName}_bucket${infLabels} ${snapshot.count}`)
+        lines.push(`${fullName}_sum${labelStr} ${snapshot.sum}`)
+        lines.push(`${fullName}_count${labelStr} ${snapshot.count}`)
+      }
+    }
+  }
+
+  emitCounter(
+    'verifications_total',
+    'Total number of AIP envelope verifications, by result, algorithm, and transport',
+    m.verifications_total,
+  )
+
+  emitHistogram(
+    'verification_duration_ms',
+    'Verification latency in milliseconds',
+    m.verification_duration_ms,
+  )
+
+  emitCounter(
+    'rate_limit_hits_total',
+    'Total number of rate-limit rejections, by sender and path',
+    m.rate_limit_hits_total,
+  )
+
+  emitCounter(
+    'sender_denials_total',
+    'Total number of sender-denied (403) rejections, by sender and path',
+    m.sender_denials_total,
+  )
+
+  emitCounter(
+    'replay_detections_total',
+    'Total number of replay-detected events, by transport',
+    m.replay_detections_total,
+  )
+
+  emitCounter(
+    'audit_entries_total',
+    'Total number of audit log entries written, by type',
+    m.audit_entries_total,
+  )
+
+  emitCounter(
+    'active_connections',
+    'Current active connections, by transport (WS/gRPC)',
+    m.active_connections,
+  )
+
+  return lines.join('\n') + '\n'
+}
+
+// ─── Node.js http-compatible metrics middleware ───────────────────────────────
+
+type NodeReq = { url?: string; method?: string }
+type NodeRes = {
+  writeHead(status: number, headers: Record<string, string>): void
+  end(body: string): void
+}
+type NextFn = () => void
+
+/**
+ * Returns a Node.js http-compatible middleware that serves Prometheus metrics
+ * at the given path (default: /metrics).
+ */
+export function createMetricsMiddleware(
+  path = '/metrics',
+  m: Protocol7h3Metrics = metrics,
+  prefix = '7h3',
+): (req: NodeReq, res: NodeRes, next: NextFn) => void {
+  return (req, res, next) => {
+    if (req.url === path && (req.method === 'GET' || req.method === undefined)) {
+      const body = renderPrometheusText(m, prefix)
+      res.writeHead(200, {
+        'content-type': 'text/plain; version=0.0.4; charset=utf-8',
+      })
+      res.end(body)
+    } else {
+      next()
+    }
+  }
+}

package/src/webhookBinding.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect } from 'vitest'
+import {
+  signWebhook,
+  verifyWebhook,
+  signWebhookHmac,
+  verifyWebhookHmac,
+  consumeWebhook,
+  generateEd25519KeypairBase64Url,
+  WEBHOOK_SIG_HEADER,
+  WEBHOOK_TS_HEADER,
+} from './webhookBinding'
+
+describe('webhookBinding', () => {
+  // 1. Ed25519 sign + verify round trip
+  it('signWebhook + verifyWebhook round trip (Ed25519)', async () => {
+    const { privateKey, publicKey } = await generateEd25519KeypairBase64Url()
+    const payload = JSON.stringify({ event: 'user.created', userId: '123' })
+    const headers = await signWebhook(payload, { privateKey })
+    const valid = await verifyWebhook(payload, headers, { publicKey })
+    expect(valid).toBe(true)
+  })
+
+  // 2. HMAC sign + verify round trip
+  it('signWebhookHmac + verifyWebhookHmac round trip', async () => {
+    const secret = 'super-secret-webhook-key'
+    const payload = JSON.stringify({ event: 'order.paid', orderId: 'abc' })
+    const headers = await signWebhookHmac(payload, { secret })
+    const valid = await verifyWebhookHmac(payload, headers, { secret })
+    expect(valid).toBe(true)
+  })
+
+  // 3. Tampered payload returns false (Ed25519)
+  it('tampered payload returns false (Ed25519)', async () => {
+    const { privateKey, publicKey } = await generateEd25519KeypairBase64Url()
+    const payload = JSON.stringify({ event: 'user.created', userId: '123' })
+    const headers = await signWebhook(payload, { privateKey })
+    const tamperedPayload = JSON.stringify({ event: 'user.created', userId: '999' })
+    const valid = await verifyWebhook(tamperedPayload, headers, { publicKey })
+    expect(valid).toBe(false)
+  })
+
+  // 3b. Tampered payload returns false (HMAC)
+  it('tampered payload returns false (HMAC)', async () => {
+    const secret = 'super-secret-webhook-key'
+    const payload = JSON.stringify({ event: 'order.paid', orderId: 'abc' })
+    const headers = await signWebhookHmac(payload, { secret })
+    const tamperedPayload = JSON.stringify({ event: 'order.paid', orderId: 'TAMPERED' })
+    const valid = await verifyWebhookHmac(tamperedPayload, headers, { secret })
+    expect(valid).toBe(false)
+  })
+
+  // 4. Expired timestamp returns false
+  it('expired timestamp returns false', async () => {
+    const { privateKey, publicKey } = await generateEd25519KeypairBase64Url()
+    const payload = JSON.stringify({ event: 'ping' })
+    const headers = await signWebhook(payload, { privateKey })
+    // Backdate the timestamp to be 10 minutes ago
+    const expiredHeaders = {
+      ...headers,
+      [WEBHOOK_TS_HEADER]: String(Date.now() - 10 * 60 * 1000),
+    }
+    const valid = await verifyWebhook(payload, expiredHeaders, { publicKey, maxAgeMs: 300_000 })
+    expect(valid).toBe(false)
+  })
+
+  // 5. Wrong key returns false
+  it('wrong public key returns false', async () => {
+    const { privateKey } = await generateEd25519KeypairBase64Url()
+    const { publicKey: wrongPublicKey } = await generateEd25519KeypairBase64Url()
+    const payload = JSON.stringify({ event: 'test' })
+    const headers = await signWebhook(payload, { privateKey })
+    const valid = await verifyWebhook(payload, headers, { publicKey: wrongPublicKey })
+    expect(valid).toBe(false)
+  })
+
+  // 5b. Wrong HMAC secret returns false
+  it('wrong HMAC secret returns false', async () => {
+    const secret = 'correct-secret'
+    const payload = JSON.stringify({ event: 'test' })
+    const headers = await signWebhookHmac(payload, { secret })
+    const valid = await verifyWebhookHmac(payload, headers, { secret: 'wrong-secret' })
+    expect(valid).toBe(false)
+  })
+
+  // 6. consumeWebhook parses valid payload
+  it('consumeWebhook parses valid payload and returns parsed object', async () => {
+    const { privateKey, publicKey } = await generateEd25519KeypairBase64Url()
+    const data = { event: 'invoice.paid', amount: 9900, currency: 'usd' }
+    const payload = JSON.stringify(data)
+    const headers = await signWebhook(payload, { privateKey })
+    const result = await consumeWebhook<typeof data>(payload, headers as Record<string, string>, { publicKey })
+    expect(result).toEqual(data)
+  })
+
+  // 7. consumeWebhook throws on invalid signature
+  it('consumeWebhook throws on invalid signature', async () => {
+    const { privateKey } = await generateEd25519KeypairBase64Url()
+    const { publicKey: wrongPublicKey } = await generateEd25519KeypairBase64Url()
+    const payload = JSON.stringify({ event: 'invoice.paid' })
+    const headers = await signWebhook(payload, { privateKey })
+    await expect(
+      consumeWebhook(payload, headers as Record<string, string>, { publicKey: wrongPublicKey })
+    ).rejects.toThrow('7h3: webhook signature verification failed')
+  })
+
+  // 7b. consumeWebhook throws on expired timestamp
+  it('consumeWebhook throws on expired timestamp', async () => {
+    const { privateKey, publicKey } = await generateEd25519KeypairBase64Url()
+    const payload = JSON.stringify({ event: 'test' })
+    const headers = await signWebhook(payload, { privateKey })
+    const expiredHeaders = {
+      ...headers,
+      [WEBHOOK_TS_HEADER]: String(Date.now() - 10 * 60 * 1000),
+    }
+    await expect(
+      consumeWebhook(payload, expiredHeaders as Record<string, string>, { publicKey, maxAgeMs: 300_000 })
+    ).rejects.toThrow('7h3: webhook signature verification failed')
+  })
+
+  // Edge: missing headers return false
+  it('missing sig header returns false', async () => {
+    const { publicKey } = await generateEd25519KeypairBase64Url()
+    const payload = 'hello'
+    const valid = await verifyWebhook(payload, { [WEBHOOK_TS_HEADER]: String(Date.now()) } as Record<string, string>, { publicKey })
+    expect(valid).toBe(false)
+  })
+
+  it('missing ts header returns false', async () => {
+    const { publicKey } = await generateEd25519KeypairBase64Url()
+    const payload = 'hello'
+    const valid = await verifyWebhook(payload, { [WEBHOOK_SIG_HEADER]: 'fakesig' } as Record<string, string>, { publicKey })
+    expect(valid).toBe(false)
+  })
+
+  // Uint8Array payload works (Ed25519)
+  it('Uint8Array payload signs and verifies (Ed25519)', async () => {
+    const { privateKey, publicKey } = await generateEd25519KeypairBase64Url()
+    const payloadStr = JSON.stringify({ binary: true })
+    const payloadBytes = new TextEncoder().encode(payloadStr)
+    const headers = await signWebhook(payloadBytes, { privateKey })
+    const valid = await verifyWebhook(payloadBytes, headers, { publicKey })
+    expect(valid).toBe(true)
+  })
+})