@7h3/protocol 0.4.0 → 0.5.1

package/docs/TELEMETRY.md

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

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

@@ -1,30 +0,0 @@
-# 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/eslint.config.js

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

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

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

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

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