@7h3/protocol 0.1.2 → 0.5.0

package/docs/TELEMETRY.md

@@ -0,0 +1,41 @@
+# Telemetry Events
+
+Transport-level telemetry can be attached to `receiveEnvelope` via `telemetry` callback.
+
+## Event phases
+
+- `decoded`
+- `rejected_clock_skew`
+- `rejected_validation`
+- `rejected_replay`
+- `rejected_missing_signature`
+- `rejected_missing_material`
+- `rejected_bad_signature`
+- `accepted`
+
+## Usage
+
+```ts
+import { receiveEnvelope } from './src/protocolTransport'
+
+await receiveEnvelope(rawEnvelope, {
+  nowMs: Date.now(),
+  replayCache,
+  secretResolver: async () => sharedSecret,
+  telemetry: async (event) => {
+    console.log(event.phase, event.sender, event.messageId, event.reason)
+  },
+})
+```
+
+## Gateway audit events
+
+`createAipMcpGatewayRuntime` supports `onAuditEvent` for request/policy traces.
+
+Phases:
+
+- `request_received`
+- `policy`
+- `verification_failed`
+- `request_success`
+- `request_error`

package/docs/THREAT_MODEL.md

@@ -0,0 +1,89 @@
+# 7h3 Protocol AIP Threat Model (v1.0 draft)
+
+## Scope
+
+This model covers `aip/0.1` envelope transport and verification paths in:
+
+- `src/protocol.ts`
+- `src/protocolTransport.ts`
+- `src/mcpGateway.ts`
+- `sdk/rust/src/lib.rs`
+
+## Assets
+
+- Message integrity and authenticity
+- Agent identity binding (`sender`, `keyId`, signature material)
+- Freshness (TTL + replay resistance)
+- Gateway policy decisions (allowlist/auth/rate-limit)
+
+## Assumptions
+
+- Clocks are roughly synchronized within deployment skew limits.
+- Secret/private-key material is provisioned securely outside protocol logic.
+- Transport channel can be observed/modified by adversaries; protocol must detect tamper.
+
+## Threats and controls
+
+## Tampering
+
+- Threat: attacker modifies envelope body/header in transit.
+- Controls:
+  - canonical payload signing (`HS256` / `ED25519`)
+  - signature verification before acceptance
+  - canonical key order fixed to prevent ambiguous signing forms
+
+## Replay
+
+- Threat: attacker replays previously valid signed envelopes.
+- Controls:
+  - TTL checks (`timestampMs + ttlMs`)
+  - replay cache consumption (`messageId` + `sender` + `nonce` semantics)
+
+## Sender impersonation
+
+- Threat: attacker signs as trusted sender with incorrect key material.
+- Controls:
+  - verifier resolves material by `(keyId, sender)` context
+  - `signatureResolver`/`secretResolver` mapping policy in transport layer
+
+## Algorithm confusion / downgrade
+
+- Threat: attacker swaps `alg` or relies on omitted compact alg fields.
+- Controls:
+  - explicit algorithm field in canonical signature object
+  - compact wire supports `sig.a`; default compatibility path only for legacy HS256
+  - verifier rejects material when resolved algorithm does not match envelope signature
+
+## Gateway abuse
+
+- Threat: unauthorized or abusive JSON-RPC method calls.
+- Controls:
+  - method allowlist
+  - authorization policy hook
+  - rate-limit policy hook with context-aware keys
+
+## Mitigated risks
+
+- **Distributed replay** — a Redis-backed `DistributedReplayStore` is shipped
+  (`createRedisReplayStore`, `src/replayStores.ts`). It uses atomic `SET NX PX`,
+  batches via pipeline (`reserveMany`), and degrades to a local store on a Redis
+  outage so a node never blindly accepts replays and never hard-stops. See
+  `DISTRIBUTED_REPLAY.md`.
+- **Fleet-wide key revocation** — a shared `RevocationStore`
+  (`createRedisRevocationStore`, `src/revocation.ts`) is consulted on the verify
+  path via `withRevocationCheck`. A key revoked on one node is rejected on all
+  nodes; reads are cached and fail **closed** by default. See `KEY_REVOCATION.md`.
+
+## Remaining risks (open)
+
+- No formal fuzz campaign yet for parser/canonicalization boundaries.
+- Revocation/replay stores rely on a correctly provisioned, available Redis (or
+  equivalent) control plane; operators own its HA and clock synchronization.
+- No third-party cryptographic audit yet.
+
+## Required production mitigations
+
+- Keep signature verification enabled by default in production paths.
+- Deploy a shared replay store (`createRedisReplayStore`) for horizontally scaled gateways.
+- Wire a shared revocation store (`createRedisRevocationStore` + `withRevocationCheck`)
+  and enforce key lifecycle policy (rotation, expiry, revocation) in the control plane.

package/docs/VERSIONING_POLICY.md

@@ -0,0 +1,30 @@
+# AIP Versioning Policy
+
+## Protocol versions
+
+- Protocol version is declared in `header.version` (for example `aip/0.1`).
+- New major protocol versions must not silently alter canonicalization or signature semantics.
+- Backward-incompatible wire or verification changes require a new minor/major protocol tag.
+
+## Compatibility rules
+
+- Patch releases: bug fixes only, no wire-format or canonicalization changes.
+- Minor releases: additive changes only (new optional fields/capabilities, no required-field breakage).
+- Major releases: allowed to remove or alter semantics with explicit migration documentation.
+
+## Signature profile policy
+
+- Supported profiles are explicitly declared by `signature.alg`.
+- Adding a new signature profile is a minor release only if existing profiles continue to verify unchanged.
+- Removing a profile requires a major release.
+
+## SDK versioning
+
+- TypeScript, Python, and Rust SDKs follow semver independently.
+- Conformance fixture changes require SDK conformance updates in the same release train.
+
+## Release evidence requirements
+
+- Conformance suites (TS/Python/Rust) pass.
+- Bench regression checks attached for performance-sensitive changes.
+- Migration guide updated for any behavior change that impacts consumers.

package/docs/assets/banner.svg

@@ -0,0 +1,123 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="640" viewBox="0 0 1280 640">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#06060f"/>
+      <stop offset="100%" style="stop-color:#0c0c22"/>
+    </linearGradient>
+    <linearGradient id="accentGrad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#4f7cff"/>
+      <stop offset="100%" style="stop-color:#a855f7"/>
+    </linearGradient>
+    <pattern id="hex" x="0" y="0" width="70" height="60" patternUnits="userSpaceOnUse">
+      <polygon points="35,3 67,21 67,57 35,60 3,57 3,21" fill="none" stroke="#ffffff07" stroke-width="1"/>
+    </pattern>
+    <filter id="softglow" x="-10%" y="-10%" width="120%" height="120%">
+      <feGaussianBlur stdDeviation="2" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+
+  <!-- Background -->
+  <rect width="1280" height="640" fill="url(#bg)"/>
+  <rect width="1280" height="640" fill="url(#hex)"/>
+
+  <!-- Ambient glows -->
+  <ellipse cx="180" cy="220" rx="300" ry="240" fill="#4f7cff" opacity="0.05"/>
+  <ellipse cx="1100" cy="420" rx="260" ry="200" fill="#a855f7" opacity="0.06"/>
+
+  <!-- Top accent bar -->
+  <rect x="0" y="0" width="1280" height="3" fill="url(#accentGrad)"/>
+
+  <!-- LEFT COLUMN -->
+  <text x="64" y="70" font-family="SF Mono,Consolas,monospace" font-size="12" fill="#4f7cff" letter-spacing="5" opacity="0.85">CRYPTOGRAPHIC AGENT PROTOCOL  ·  v0.4.0</text>
+  <text x="58" y="162" font-family="Inter,Helvetica Neue,Arial,sans-serif" font-size="96" font-weight="800" fill="#ffffff" letter-spacing="-4">7h3 Protocol</text>
+  <text x="62" y="204" font-family="Inter,Helvetica Neue,Arial,sans-serif" font-size="22" font-weight="300" fill="#94a3b8" letter-spacing="0.3">Sign every message. Reject every replay.</text>
+  <rect x="62" y="220" width="320" height="2.5" rx="1.5" fill="url(#accentGrad)"/>
+
+  <!-- Transport pills -->
+  <text x="62" y="272" font-family="SF Mono,Consolas,monospace" font-size="10" fill="#475569" letter-spacing="4">SECURED TRANSPORTS</text>
+  <rect x="62"  y="284" width="128" height="36" rx="7" fill="#0f1f3d" stroke="#4f7cff" stroke-width="1.2"/>
+  <text x="126" y="307" font-family="Inter,sans-serif" font-size="13" font-weight="600" fill="#93c5fd" text-anchor="middle">HTTP / REST</text>
+  <rect x="200" y="284" width="122" height="36" rx="7" fill="#131040" stroke="#6366f1" stroke-width="1.2"/>
+  <text x="261" y="307" font-family="Inter,sans-serif" font-size="13" font-weight="600" fill="#a5b4fc" text-anchor="middle">WebSocket</text>
+  <rect x="332" y="284" width="90"  height="36" rx="7" fill="#160e3d" stroke="#8b5cf6" stroke-width="1.2"/>
+  <text x="377" y="307" font-family="Inter,sans-serif" font-size="13" font-weight="600" fill="#c4b5fd" text-anchor="middle">gRPC</text>
+  <rect x="432" y="284" width="120" height="36" rx="7" fill="#1a0f3d" stroke="#a855f7" stroke-width="1.2"/>
+  <text x="492" y="307" font-family="Inter,sans-serif" font-size="13" font-weight="600" fill="#d8b4fe" text-anchor="middle">Msg Queues</text>
+  <rect x="562" y="284" width="110" height="36" rx="7" fill="#2a0f2a" stroke="#ec4899" stroke-width="1.2"/>
+  <text x="617" y="307" font-family="Inter,sans-serif" font-size="13" font-weight="600" fill="#f9a8d4" text-anchor="middle">Webhooks</text>
+
+  <!-- SDK badges -->
+  <text x="62" y="356" font-family="SF Mono,Consolas,monospace" font-size="10" fill="#475569" letter-spacing="4">5 SDKs — ZERO RUNTIME DEPS</text>
+  <rect x="62"  y="368" width="98" height="32" rx="6" fill="#0f1d30"/>
+  <text x="111" y="389" font-family="Inter,sans-serif" font-size="13" font-weight="700" fill="#60a5fa" text-anchor="middle">TypeScript</text>
+  <rect x="170" y="368" width="84" height="32" rx="6" fill="#0a1f12"/>
+  <text x="212" y="389" font-family="Inter,sans-serif" font-size="13" font-weight="700" fill="#4ade80" text-anchor="middle">Python</text>
+  <rect x="264" y="368" width="72" height="32" rx="6" fill="#1f0f05"/>
+  <text x="300" y="389" font-family="Inter,sans-serif" font-size="13" font-weight="700" fill="#fb923c" text-anchor="middle">Rust</text>
+  <rect x="346" y="368" width="62" height="32" rx="6" fill="#051520"/>
+  <text x="377" y="389" font-family="Inter,sans-serif" font-size="13" font-weight="700" fill="#38bdf8" text-anchor="middle">Go</text>
+  <rect x="418" y="368" width="98" height="32" rx="6" fill="#180e28"/>
+  <text x="467" y="389" font-family="Inter,sans-serif" font-size="13" font-weight="700" fill="#c084fc" text-anchor="middle">Browser</text>
+
+  <!-- Install commands -->
+  <rect x="62" y="420" width="650" height="116" rx="10" fill="#080d18" stroke="#1e293b" stroke-width="1"/>
+  <rect x="62" y="420" width="3"   height="116" rx="1.5" fill="url(#accentGrad)"/>
+  <text x="82" y="450" font-family="SF Mono,Consolas,Courier New,monospace" font-size="12.5" fill="#4b5563">$</text>
+  <text x="98" y="450" font-family="SF Mono,Consolas,Courier New,monospace" font-size="12.5" fill="#cbd5e1">npm install <tspan fill="#60a5fa">@7h3/protocol</tspan></text>
+  <text x="82" y="476" font-family="SF Mono,Consolas,Courier New,monospace" font-size="12.5" fill="#4b5563">$</text>
+  <text x="98" y="476" font-family="SF Mono,Consolas,Courier New,monospace" font-size="12.5" fill="#cbd5e1">pip install <tspan fill="#4ade80">7h3-protocol</tspan></text>
+  <text x="82" y="502" font-family="SF Mono,Consolas,Courier New,monospace" font-size="12.5" fill="#4b5563">$</text>
+  <text x="98" y="502" font-family="SF Mono,Consolas,Courier New,monospace" font-size="12.5" fill="#cbd5e1">cargo add <tspan fill="#fb923c">protocol-7h3</tspan></text>
+  <text x="82" y="528" font-family="SF Mono,Consolas,Courier New,monospace" font-size="12.5" fill="#4b5563">$</text>
+  <text x="98" y="528" font-family="SF Mono,Consolas,Courier New,monospace" font-size="12.5" fill="#cbd5e1">go get <tspan fill="#38bdf8">github.com/IceMasterT/7h3-protocol/sdk/go</tspan></text>
+
+  <!-- RIGHT COLUMN — Stat cards -->
+  <rect x="776" y="52" width="210" height="112" rx="12" fill="#0a0f20" stroke="#4f7cff" stroke-width="1.2"/>
+  <text x="881" y="94"  font-family="Inter,sans-serif" font-size="30" font-weight="800" fill="#4f7cff"  text-anchor="middle" filter="url(#softglow)">Ed25519</text>
+  <text x="881" y="118" font-family="Inter,sans-serif" font-size="12" fill="#64748b" text-anchor="middle">Asymmetric signing</text>
+  <text x="881" y="138" font-family="Inter,sans-serif" font-size="11" fill="#334155" text-anchor="middle">PKCS8 · SPKI · base64url</text>
+
+  <rect x="1004" y="52" width="210" height="112" rx="12" fill="#0a1a12" stroke="#10b981" stroke-width="1.2"/>
+  <text x="1109" y="100" font-family="Inter,sans-serif" font-size="48" font-weight="800" fill="#10b981" text-anchor="middle" filter="url(#softglow)">278</text>
+  <text x="1109" y="124" font-family="Inter,sans-serif" font-size="12" fill="#64748b" text-anchor="middle">tests passing</text>
+  <text x="1109" y="142" font-family="Inter,sans-serif" font-size="11" fill="#334155" text-anchor="middle">TS · Python · Rust · Go</text>
+
+  <rect x="776" y="180" width="210" height="112" rx="12" fill="#130a20" stroke="#a855f7" stroke-width="1.2"/>
+  <text x="881" y="236" font-family="Inter,sans-serif" font-size="48" font-weight="800" fill="#a855f7" text-anchor="middle" filter="url(#softglow)">0</text>
+  <text x="881" y="260" font-family="Inter,sans-serif" font-size="12" fill="#64748b" text-anchor="middle">runtime deps</text>
+  <text x="881" y="278" font-family="Inter,sans-serif" font-size="11" fill="#334155" text-anchor="middle">Pure stdlib · all 5 SDKs</text>
+
+  <rect x="1004" y="180" width="210" height="112" rx="12" fill="#1a1400" stroke="#f59e0b" stroke-width="1.2"/>
+  <text x="1109" y="236" font-family="Inter,sans-serif" font-size="48" font-weight="800" fill="#f59e0b" text-anchor="middle" filter="url(#softglow)">5</text>
+  <text x="1109" y="260" font-family="Inter,sans-serif" font-size="12" fill="#64748b" text-anchor="middle">transports</text>
+  <text x="1109" y="278" font-family="Inter,sans-serif" font-size="11" fill="#334155" text-anchor="middle">One wire format: 7h3/0.1</text>
+
+  <!-- Security features panel -->
+  <rect x="776" y="308" width="438" height="242" rx="12" fill="#0a0d1a" stroke="#1e293b" stroke-width="1"/>
+  <rect x="776" y="308" width="438" height="3"   rx="1.5" fill="url(#accentGrad)"/>
+  <text x="796" y="338" font-family="SF Mono,Consolas,monospace" font-size="10" fill="#475569" letter-spacing="4">SECURITY GUARANTEES</text>
+
+  <rect x="796" y="350" width="3" height="38" rx="1.5" fill="#4f7cff"/>
+  <text x="810" y="368" font-family="Inter,sans-serif" font-size="14" font-weight="600" fill="#e2e8f0">Verified sender identity</text>
+  <text x="810" y="384" font-family="Inter,sans-serif" font-size="11.5" fill="#475569">Ed25519 — cryptographically impossible to forge</text>
+
+  <rect x="796" y="398" width="3" height="38" rx="1.5" fill="#10b981"/>
+  <text x="810" y="416" font-family="Inter,sans-serif" font-size="14" font-weight="600" fill="#e2e8f0">Replay attack prevention</text>
+  <text x="810" y="432" font-family="Inter,sans-serif" font-size="11.5" fill="#475569">TTL + nonce — captured messages expire, can't be reused</text>
+
+  <rect x="796" y="446" width="3" height="38" rx="1.5" fill="#a855f7"/>
+  <text x="810" y="464" font-family="Inter,sans-serif" font-size="14" font-weight="600" fill="#e2e8f0">Tamper-evident audit log</text>
+  <text x="810" y="480" font-family="Inter,sans-serif" font-size="11.5" fill="#475569">Ed25519-signed entries — alter one byte, break the chain</text>
+
+  <rect x="796" y="494" width="3" height="38" rx="1.5" fill="#f59e0b"/>
+  <text x="810" y="512" font-family="Inter,sans-serif" font-size="14" font-weight="600" fill="#e2e8f0">Bidirectional trust</text>
+  <text x="810" y="528" font-family="Inter,sans-serif" font-size="11.5" fill="#475569">Servers sign responses — clients verify replies too</text>
+
+  <!-- Footer -->
+  <rect x="0" y="608" width="1280" height="32" fill="#04040c"/>
+  <rect x="0" y="608" width="1280" height="1"  fill="#1e293b"/>
+  <text x="62"   y="630" font-family="SF Mono,Consolas,monospace" font-size="12" fill="#334155">github.com/IceMasterT/7h3-protocol</text>
+  <text x="640"  y="630" font-family="SF Mono,Consolas,monospace" font-size="12" fill="#334155" text-anchor="middle">MIT License  ·  wire: 7h3/0.1  ·  Zero runtime deps</text>
+  <text x="1218" y="630" font-family="SF Mono,Consolas,monospace" font-size="12" fill="#334155" text-anchor="end">v0.4.0</text>
+</svg>

package/eslint.config.js

@@ -0,0 +1,15 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config(
+  { ignores: ['dist', 'node_modules', 'sdk/rust/target'] },
+  {
+    extends: [js.configs.recommended, ...tseslint.configs.recommended],
+    files: ['**/*.ts'],
+    languageOptions: {
+      ecmaVersion: 2022,
+      globals: { ...globals.node, ...globals.browser },
+    },
+  },
+)

package/fuzz/ts/harness-decode.ts

@@ -0,0 +1,136 @@
+/**
+ * Fuzz harness: wire decoder resilience.
+ *
+ * Invariant: decodeEnvelope must NEVER throw on any input — arbitrary strings
+ * and arbitrary bytes both. On garbage it must return {ok: false}.
+ *
+ * Strategy: start from the conformance corpus, apply mutations, run N rounds.
+ */
+
+import { readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { decodeEnvelope } from '../../src/index.js'
+
+const __dir = dirname(fileURLToPath(import.meta.url))
+const VECTORS_PATH = join(__dir, '../../conformance/7h3_v0_1.json')
+const ROUNDS = parseInt(process.env.FUZZ_ROUNDS ?? '50000', 10)
+
+const { vectors, ed25519Vectors = [] } = JSON.parse(readFileSync(VECTORS_PATH, 'utf-8'))
+
+// --- corpus: valid JSON and compact encodings from conformance vectors ---
+const corpus: (string | Uint8Array)[] = []
+for (const v of [...vectors, ...ed25519Vectors]) {
+  const env = v.envelope
+  corpus.push(JSON.stringify(env))
+  // compact encoding
+  corpus.push(
+    JSON.stringify({
+      v: env.header?.version,
+      mid: env.header?.messageId,
+      ts: env.header?.timestampMs,
+      ttl: env.header?.ttlMs,
+      s: env.header?.sender,
+      n: env.header?.nonce,
+      i: env.body?.intent,
+      c: env.body?.content,
+    }),
+  )
+}
+// seed with known-bad corpus
+corpus.push('', '{}', '[]', 'null', '"string"', '{', '{"header":{}}', '{"header":{},"body":{}}')
+
+// --- mutators ---
+type Mutator = (input: string, rand: () => number) => string
+
+const mutators: Mutator[] = [
+  // bit flip a byte
+  (s, r) => {
+    const buf = Buffer.from(s, 'utf-8')
+    if (!buf.length) return s
+    buf[Math.floor(r() * buf.length)] ^= 1 << Math.floor(r() * 8)
+    return buf.toString('utf-8')
+  },
+  // insert random byte
+  (s, r) => {
+    const buf = Buffer.from(s, 'utf-8')
+    const idx = Math.floor(r() * (buf.length + 1))
+    const b = Math.floor(r() * 256)
+    return Buffer.concat([buf.subarray(0, idx), Buffer.from([b]), buf.subarray(idx)]).toString('utf-8')
+  },
+  // delete a byte
+  (s, r) => {
+    const buf = Buffer.from(s, 'utf-8')
+    if (!buf.length) return s
+    const idx = Math.floor(r() * buf.length)
+    return Buffer.concat([buf.subarray(0, idx), buf.subarray(idx + 1)]).toString('utf-8')
+  },
+  // truncate
+  (s, r) => {
+    const buf = Buffer.from(s, 'utf-8')
+    return buf.subarray(0, Math.floor(r() * buf.length)).toString('utf-8')
+  },
+  // mutate a JSON field
+  (s, r) => {
+    try {
+      const obj = JSON.parse(s) as Record<string, unknown>
+      const keys = Object.keys(obj)
+      if (!keys.length) return s
+      const key = keys[Math.floor(r() * keys.length)]
+      const replacement = [null, 0, 1, -1, '', [], {}, true, false][Math.floor(r() * 9)]
+      obj[key] = replacement
+      return JSON.stringify(obj)
+    } catch {
+      return s
+    }
+  },
+  // replace a known token with another
+  (s, r) => {
+    const tokens = ['7h3/0.1', 'TASK', 'PING', 'RESULT', 'HS256', 'ED25519', '"sender"', '"body"']
+    const replacements = ['aip/0.2', 'INVALID', '', '0', 'NONE', 'RSA', '"SENDER"', '"Body"']
+    const i = Math.floor(r() * tokens.length)
+    return s.split(tokens[i]).join(replacements[i])
+  },
+]
+
+// --- runner ---
+let crashes = 0
+let okFalse = 0
+let okTrue = 0
+
+function rand(): number {
+  return Math.random()
+}
+
+let current = corpus[0] as string
+
+for (let i = 0; i < ROUNDS; i++) {
+  // pick a mutator and apply it
+  const mutator = mutators[Math.floor(rand() * mutators.length)]
+  current = mutator(current, rand)
+
+  // occasionally reset to a fresh corpus item
+  if (i % 500 === 0) {
+    current = corpus[Math.floor(rand() * corpus.length)] as string
+  }
+
+  try {
+    const result = decodeEnvelope(current)
+    if (result.ok) {
+      okTrue++
+    } else {
+      okFalse++
+    }
+  } catch (err) {
+    crashes++
+    console.error(`\nCRASH at round ${i}:`)
+    console.error('  Input (first 200 chars):', JSON.stringify(current.slice(0, 200)))
+    console.error('  Error:', err)
+  }
+}
+
+console.log(`[harness-decode] rounds=${ROUNDS} ok=${okTrue} ok:false=${okFalse} crashes=${crashes}`)
+if (crashes > 0) {
+  console.error(`FAIL: ${crashes} crash(es) detected`)
+  process.exit(1)
+}

package/fuzz/ts/harness-verify.ts

@@ -0,0 +1,121 @@
+/**
+ * Fuzz harness: signature verification with tampered envelopes.
+ *
+ * Invariants:
+ *   1. verifyEnvelopeHmac must NEVER throw — tampered or malformed envelopes
+ *      must return false, not crash.
+ *   2. A valid envelope always verifies as true (regression check).
+ *   3. Single-byte tampering of any signed field must make verification fail.
+ *
+ * Strategy: start from valid signed envelopes, apply structural and byte mutations.
+ */
+
+import { readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createEnvelope, signEnvelopeHmac, verifyEnvelopeHmac } from '../../src/index.js'
+
+const __dir = dirname(fileURLToPath(import.meta.url))
+const VECTORS_PATH = join(__dir, '../../conformance/7h3_v0_1.json')
+const ROUNDS = parseInt(process.env.FUZZ_ROUNDS ?? '20000', 10)
+
+const { vectors } = JSON.parse(readFileSync(VECTORS_PATH, 'utf-8'))
+
+const SECRET = vectors[0].secret as string
+
+// Build and sign a fresh envelope so we have a known-valid baseline
+const BASE_ENVELOPE = await signEnvelopeHmac(
+  createEnvelope({ sender: 'fuzzer', recipient: 'target', intent: 'TASK', content: 'baseline' }),
+  SECRET,
+)
+
+// Regression: valid envelope must verify
+const baseOk = await verifyEnvelopeHmac(BASE_ENVELOPE, SECRET)
+if (!baseOk) {
+  console.error('FAIL: baseline verification returned false — test setup error')
+  process.exit(1)
+}
+
+// --- corpus of tampered envelopes ---
+function deepClone<T>(x: T): T {
+  return JSON.parse(JSON.stringify(x)) as T
+}
+
+type Env = typeof BASE_ENVELOPE
+
+async function tamper(env: Env, rand: () => number): Promise<Env> {
+  const e = deepClone(env)
+  const target = rand() < 0.5 ? 'header' : 'body'
+  const obj = e[target] as unknown as Record<string, unknown>
+  const keys = Object.keys(obj)
+  const key = keys[Math.floor(rand() * keys.length)]
+  const v = obj[key]
+  // Mutate the value
+  if (typeof v === 'string') {
+    if (v.length === 0) {
+      obj[key] = 'mutated'
+    } else {
+      const buf = Buffer.from(v, 'utf-8')
+      const idx = Math.floor(rand() * buf.length)
+      buf[idx] ^= 1 << Math.floor(rand() * 8)
+      obj[key] = buf.toString('utf-8')
+    }
+  } else if (typeof v === 'number') {
+    // Ensure delta is non-zero: map [0, 999] → [-500, -1] ∪ [1, 500]
+    const raw = Math.floor(rand() * 1000)
+    const delta = raw < 500 ? raw - 500 : raw - 499 // skips 0
+    obj[key] = v + delta
+  } else {
+    obj[key] = null
+  }
+
+  // Guard: if the mutation produced no net change (e.g. bit flip round-tripped
+  // through invalid UTF-8 to the same replacement character), force a known change.
+  if (JSON.stringify(e) === JSON.stringify(env)) {
+    const guard = e.body as unknown as Record<string, unknown>
+    guard['content'] = '__forced_tamper__'
+  }
+
+  return e
+}
+
+// --- runner ---
+let crashes = 0
+let tamperFalsePositive = 0
+
+for (let i = 0; i < ROUNDS; i++) {
+  const rand = () => Math.random()
+  const tampered = await tamper(BASE_ENVELOPE, rand)
+
+  try {
+    const result = await verifyEnvelopeHmac(tampered, SECRET)
+    if (result === true) {
+      tamperFalsePositive++
+      console.error(`\nFAIL false positive at round ${i} — tampered envelope verified as ok`)
+      console.error('  Tampered:', JSON.stringify(tampered).slice(0, 300))
+    }
+  } catch (err) {
+    crashes++
+    console.error(`\nCRASH at round ${i}:`)
+    console.error('  Input:', JSON.stringify(tampered).slice(0, 300))
+    console.error('  Error:', err)
+  }
+
+  // Occasionally test with a structurally broken envelope (missing fields)
+  if (i % 200 === 0) {
+    const broken = { header: {}, body: {}, signature: BASE_ENVELOPE.signature } as unknown as Env
+    try {
+      await verifyEnvelopeHmac(broken, SECRET)
+    } catch (err) {
+      crashes++
+      console.error(`\nCRASH (broken envelope) at round ${i}:`, err)
+    }
+  }
+}
+
+console.log(
+  `[harness-verify] rounds=${ROUNDS} tamper-false-positives=${tamperFalsePositive} crashes=${crashes}`,
+)
+if (crashes > 0 || tamperFalsePositive > 0) {
+  process.exit(1)
+}

package/fuzz/ts/run.ts

@@ -0,0 +1,35 @@
+/**
+ * Fuzz campaign runner — executes all TypeScript harnesses in sequence.
+ *
+ * Usage:
+ *   npm run fuzz:ts              # default 50k/20k rounds
+ *   FUZZ_ROUNDS=200000 npm run fuzz:ts
+ */
+
+import { spawnSync } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dir = dirname(fileURLToPath(import.meta.url))
+
+const HARNESSES = ['harness-decode.ts', 'harness-verify.ts']
+
+let failed = false
+for (const harness of HARNESSES) {
+  process.stdout.write(`Running ${harness} ... `)
+  const result = spawnSync('npx', ['tsx', join(__dir, harness)], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env },
+  })
+  const out = result.stdout.toString().trim()
+  const err = result.stderr.toString().trim()
+  if (result.status !== 0) {
+    console.error(`FAIL\n${out}\n${err}`)
+    failed = true
+  } else {
+    console.log(`PASS  ${out}`)
+    if (err) console.error(err)
+  }
+}
+
+process.exit(failed ? 1 : 0)

package/mcp-server/README.md

@@ -0,0 +1,38 @@
+# @7h3/protocol-mcp
+
+MCP server for [@7h3/protocol](https://github.com/IceMasterT/7h3-protocol-aip) — install into Claude to generate AIP secrets, keypairs, and server boilerplate.
+
+## Install into Claude Code
+
+```bash
+claude mcp add aip -- npx @7h3/protocol-mcp
+```
+
+## Install into Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "aip": {
+      "command": "npx",
+      "args": ["@7h3/protocol-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `aip_generate_secret` | Generates a 32-byte HMAC secret — store as `AIP_SECRET` |
+| `aip_generate_keypair` | Generates an Ed25519 keypair — store keys as env vars |
+| `aip_wrap_mcp_server` | Outputs ready-to-paste boilerplate for your MCP server |
+| `aip_sign` | Signs a test envelope (debugging / fixture generation) |
+| `aip_verify` | Verifies an envelope signature and shape |
+
+## License
+
+MIT