@7h3/protocol 0.1.2 → 0.4.0

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