@7h3/protocol 0.5.0 → 0.5.2

package/docs/FUZZ_CAMPAIGN.md

@@ -1,121 +0,0 @@
-# Fuzz Campaign
-
-AIP employs two complementary fuzzing strategies: mutation-based harnesses for TypeScript and coverage-guided libFuzzer targets for Rust.
-
----
-
-## TypeScript — mutation-based harnesses
-
-**Location:** `fuzz/ts/`
-
-**Run:**
-```bash
-npm run fuzz:ts          # both harnesses, default rounds
-FUZZ_ROUNDS=200000 npm run fuzz:ts   # heavier run
-npm run fuzz:ts:decode   # decoder only
-npm run fuzz:ts:verify   # verifier only
-```
-
-### Harness: `harness-decode.ts`
-
-**Target:** `decodeEnvelope`  
-**Invariant:** Must never throw on any input — garbage returns `{ok: false}`, not a crash.
-
-**Strategy:**
-1. Seed corpus: conformance vectors (JSON full form + compact form) + known-bad inputs (`{}`, `[]`, `null`, `"string"`, `{`, etc.)
-2. Each round: pick a mutator, apply it to the current input
-3. Reset to a fresh corpus item every 500 rounds
-
-**Mutators:**
-- Bit flip at a random byte position
-- Random byte insertion
-- Random byte deletion
-- Truncation to a random prefix length
-- JSON field mutation (null, type change)
-- Token substitution (e.g. `"aip/0.1"` → `"aip/0.2"`)
-
-**Initial run result (2026-06-05):**
-```
-[harness-decode] rounds=50000 ok=98 ok:false=49902 crashes=0
-```
-No crashes. Decoder tolerates all 50,000 mutated inputs.
-
----
-
-### Harness: `harness-verify.ts`
-
-**Target:** `verifyEnvelopeHmac`  
-**Invariants:**
-1. Must never throw on a tampered envelope.
-2. Any tampered envelope must verify as `false` (no false positives).
-
-**Strategy:**
-1. Sign a fresh baseline envelope
-2. Each round: deep-clone and randomly mutate one field in `header` or `body`
-3. Guard: if mutation produced no net change, force `body.content` to a sentinel value
-4. Every 200 rounds: test with a fully broken envelope (`{}` headers/body)
-
-**Mutation operators:**
-- String fields: bit flip a random byte, UTF-8 round-tripped (invalid sequences → replacement char)
-- Numeric fields: add a non-zero delta (−500 to −1 or +1 to +500)
-- Optional fields: set to `null`
-
-**Initial run result (2026-06-05):**
-```
-[harness-verify] rounds=20000 tamper-false-positives=0 crashes=0
-```
-No crashes, no false positives. No tampered envelope verified as valid.
-
----
-
-## Rust — cargo-fuzz (libFuzzer)
-
-**Location:** `sdk/rust/fuzz/`
-
-**Prerequisites:**
-```bash
-rustup toolchain install nightly
-cargo install cargo-fuzz
-```
-
-**Run:**
-```bash
-npm run fuzz:rust:decode         # 60-second decode fuzzing session
-npm run fuzz:rust:canonicalize   # 60-second canonicalize fuzzing session
-
-# Or run directly:
-cargo +nightly fuzz run fuzz_decode --manifest-path sdk/rust/fuzz/Cargo.toml
-cargo +nightly fuzz run fuzz_canonicalize --manifest-path sdk/rust/fuzz/Cargo.toml
-```
-
-### Target: `fuzz_decode`
-
-**Target:** `aip7h3::decode_envelope`  
-**Invariant:** Must never panic on any UTF-8-valid input — errors are `Err(...)`, not panics.
-
-Input: arbitrary byte sequences converted to UTF-8 via `std::str::from_utf8`.
-
-### Target: `fuzz_canonicalize`
-
-**Target:** `aip7h3::canonicalize_envelope`  
-**Invariant:** Calling it twice on the same envelope returns the same string (idempotence / purity).
-
-Input: fuzz bytes carved into envelope fields (`messageId`, `content`) to exercise the canonicalization path under arbitrary field content.
-
----
-
-## Coverage gaps and known limitations
-
-| Gap | Notes |
-|---|---|
-| TypeScript fuzzing is mutation-based, not coverage-guided | Coverage-guided fuzzing (e.g. jazzer.js) requires Java; out of scope for CI. The mutation harnesses provide meaningful parser boundary coverage without the dependency. |
-| Binary decoder (`decodeEnvelope` with `Uint8Array`) | The existing property-based tests (fast-check) cover this path (`src/protocolFuzz.advanced.test.ts`). A dedicated fuzz harness is a future addition. |
-| Ed25519 verification paths | These depend on WebCrypto internals; crash surface is on the envelope parsing/canonicalization layer (covered). |
-| No crash corpus retained | Extend the harnesses with a `fuzz/corpus/` directory to persist and replay interesting inputs. |
-| Python | No standalone fuzz harness — Python correctness is covered by conformance vectors and the property-based TS tests. |
-
----
-
-## Pre-release fuzz policy
-
-Per `docs/RELEASE_GATE.md`, at minimum the TypeScript harnesses run at default round counts as part of every release gate check. Rust fuzzing is optional for patch releases and required for minor/major bumps.

package/docs/GATEWAY.md

@@ -1,195 +0,0 @@
-# 7h3 Protocol — Gateway Quick-Start
-
-The 7h3 gateway is a verifying HTTP reverse proxy.  It sits in front of your
-service, intercepts every request, checks that the AIP envelope header carries
-a valid Ed25519 (or HMAC) signature from a known sender, enforces per-route
-policies and rate limits, optionally signs upstream responses, then forwards
-clean HTTP to your application.
-
----
-
-## 1. Install
-
-```bash
-npm install @7h3/protocol
-```
-
-`tsx` is required to run the CLI from source.  It is listed as a dev
-dependency and is also installed globally in the Docker image.
-
-```bash
-npm install -g tsx          # if running outside Docker
-```
-
----
-
-## 2. In-Process Middleware
-
-Drop the gateway into an existing Express (or any Node.js `http`) server in
-three lines:
-
-```ts
-import express from 'express'
-import { createGateway } from '@7h3/protocol/gateway'
-import { createStaticKeyRegistry } from '@7h3/protocol/key-registry'
-
-const app = express()
-
-const registry = createStaticKeyRegistry({
-  'agent@example.com': process.env.AGENT_PUBLIC_KEY!,
-})
-
-const gateway = createGateway({
-  upstream: 'http://internal-api:3000',
-  keyRegistry: registry,
-  defaultPolicy: 'deny',
-})
-
-// Verify every request before it reaches your routes
-app.use(async (req, res, next) => {
-  const headers: Record<string, string> = {}
-  for (const [k, v] of Object.entries(req.headers)) {
-    if (typeof v === 'string') headers[k] = v
-    else if (Array.isArray(v)) headers[k] = v[0]
-  }
-  const outcome = await gateway.verify({ method: req.method, path: req.path, headers })
-  if (!outcome.ok) return res.status(outcome.status).json({ error: outcome.reason })
-  res.locals.sender = outcome.sender
-  next()
-})
-```
-
----
-
-## 3. Gateway Mode (CLI / Standalone Proxy)
-
-### 3a. Generate a keypair
-
-```bash
-7h3 keygen --output keys.json
-```
-
-This writes a JSON file with `publicKey` and `privateKey` (both base64url-encoded
-Ed25519 SPKI/PKCS8).  Store `privateKey` in a secret; share `publicKey` with
-the agents that will call your service.
-
-### 3b. Start the gateway
-
-```bash
-7h3 gateway \
-  --upstream http://localhost:3000 \
-  --public-key <base64url-SPKI> \
-  --port 8080 \
-  --require ed25519
-```
-
-Full options:
-
-| Flag | Default | Description |
-|---|---|---|
-| `--upstream <url>` | _(required)_ | Upstream service URL |
-| `--port <n>` | `8080` | Port to listen on |
-| `--require ed25519\|none` | `ed25519` if `--public-key` is set, else `none` | Signature mode |
-| `--public-key <key>` | — | Ed25519 SPKI public key (base64url) |
-| `--sign-responses` | `false` | Sign every proxied response |
-| `--private-key <key>` | — | Private key for response signing |
-| `--sender <id>` | — | Sender ID attached to signed responses |
-
----
-
-## 4. Docker
-
-```bash
-# Bring up the gateway + example upstream
-docker compose up --build
-
-# Test with a health probe (no signature required)
-curl http://localhost:8080/health
-
-# Generate keys, then call a signed route
-7h3 keygen --output keys.json
-PRIV=$(jq -r .privateKey keys.json)
-PUB=$(jq -r .publicKey keys.json)
-
-ENVELOPE=$(7h3 sign --private-key "$PRIV" --sender agent@example.com --payload '{"q":"hello"}')
-curl -H "x-7h3-envelope: $ENVELOPE" http://localhost:8080/api/hello
-```
-
-To enable response signing, pass environment variables to the gateway service
-in `docker-compose.yaml`:
-
-```yaml
-environment:
-  GATEWAY_PRIVATE_KEY: <your-private-key>
-  GATEWAY_SENDER: gateway@my-service.example.com
-```
-
----
-
-## 5. Config Reference (YAML)
-
-See `7h3.example.yaml` for a fully-annotated configuration file.
-
-| Field | Type | Default | Description |
-|---|---|---|---|
-| `upstream` | string | _(required)_ | Upstream base URL |
-| `port` | number | `8080` | Listening port |
-| `sender` | string | — | Gateway sender identity for signed responses |
-| `sign_responses` | boolean | `false` | Sign every proxied response |
-| `default_policy` | `allow` \| `deny` | `allow` | Behaviour when no route policy matches |
-| `keys.private_key` | string | — | Gateway Ed25519 private key (base64url PKCS8) |
-| `keys.registry` | map | `{}` | `senderID → publicKey` (base64url SPKI) |
-| `policies[].path` | glob string | _(required)_ | Route glob (`**` crosses slashes) |
-| `policies[].require` | `ed25519` \| `hmac` \| `any` \| `none` | _(required)_ | Signature algorithm |
-| `policies[].allowed_senders` | string[] | _(all)_ | Allowlist of sender IDs |
-| `policies[].rate_limit.requests` | number | — | Max requests in window |
-| `policies[].rate_limit.window_ms` | number | — | Sliding window in ms |
-| `policies[].sign_response` | boolean | — | Per-route response signing override |
-
----
-
-## 6. Client-Side Signing
-
-Agents calling a 7h3-protected gateway must attach a signed AIP envelope to
-every request.  Use the TypeScript SDK:
-
-```ts
-import { createEnvelope, signEnvelopeEd25519 } from '@7h3/protocol'
-import { attachEnvelopeToHeaders } from '@7h3/protocol/http'
-
-async function signedFetch(url: string, body: string, privateKey: string) {
-  const envelope = createEnvelope({
-    sender: 'agent@example.com',
-    recipient: 'gateway@my-service.example.com',
-    intent: 'REQUEST',
-    content: body,
-    ttlMs: 60_000,
-  })
-
-  const signed = await signEnvelopeEd25519(envelope, privateKey)
-  const headers = attachEnvelopeToHeaders(signed, {})   // adds x-7h3-envelope
-
-  return fetch(url, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json', ...headers },
-    body,
-  })
-}
-```
-
-The gateway validates the envelope header, verifies the Ed25519 signature
-against the sender's registered public key, checks replay protection, and only
-then forwards the request to the upstream service.
-
----
-
-## 7. Policy Examples
-
-| Use Case | `path` | `require` | `allowed_senders` | `rate_limit` |
-|---|---|---|---|---|
-| Public health probe | `/health` | `none` | — | — |
-| Open public API | `/public/**` | `none` | — | — |
-| Any authenticated agent | `/api/**` | `ed25519` | — | 1 000 req / 60 s |
-| Named admin agents only | `/api/admin/**` | `ed25519` | `admin-agent@…`, `orchestrator@…` | — |
-| Partner integration | `/api/partner/**` | `ed25519` | `partner-bot@partner.example.com` | 200 req / 60 s |
-| Webhook receiver | `/webhooks/**` | `hmac` | — | 500 req / 60 s |

package/docs/KEY_MANAGEMENT_POLICY.md

@@ -1,53 +0,0 @@
-# 7h3 Protocol AIP Key Management Policy (v1.0 draft)
-
-## Supported signature profiles
-
-- `HS256` (shared secret)
-- `ED25519` (asymmetric keypair)
-
-## Key ID rules
-
-- Every signing key must have a unique `keyId`.
-- Verifiers must resolve verification material by both `keyId` and `sender`.
-- Reusing the same `keyId` for different senders is prohibited.
-
-## Rotation policy
-
-- Rotation interval target:
-  - `HS256`: every 30 days
-  - `ED25519`: every 90 days
-- Rotation process:
-  1. Provision new key as active for signing.
-  2. Keep previous key in verify-only mode during overlap window.
-  3. End overlap and revoke old key.
-
-## Revocation policy
-
-- Immediate revocation triggers:
-  - suspected credential leak
-  - host compromise
-  - failed integrity investigation
-- Revoked keys must fail verification in resolver control plane within SLA.
-- For multi-node deployments, back revocation with a shared `RevocationStore`
-  (`createRedisRevocationStore`) and wrap the verification resolver with
-  `withRevocationCheck` so a revoke on one node is enforced fleet-wide. The
-  store fails **closed** by default: if the revocation list is unreachable, the
-  key is treated as revoked. See `KEY_REVOCATION.md`.
-
-## Storage requirements
-
-- Do not commit secrets/private keys to source control.
-- Store key material in managed secrets/KMS.
-- Restrict read access to signing services and verification control plane.
-
-## Runtime policy
-
-- Production endpoints require signatures by default.
-- `HS256` is recommended for tightly controlled private clusters.
-- `ED25519` is recommended for cross-domain or multi-tenant federation.
-- Use `RollingKeyring` (`src/keyRotation.ts`) for overlap windows, verify-only periods, and revocation enforcement.
-
-## Audit requirements
-
-- Log key activation, rotation, revocation, and failed verification events.
-- Retain audit logs for incident response and compliance windows.

package/docs/KEY_REVOCATION.md

@@ -1,69 +0,0 @@
-# Fleet-Wide Key Revocation
-
-`RollingKeyring` (`src/keyRotation.ts`) enforces revocation and `notBefore`/
-`notAfter` expiry **in-process**. For horizontally scaled deployments, a shared
-`RevocationStore` makes a revocation effective across every node: revoke a
-`(sender, keyId)` on one gateway and all gateways that consult the same store
-reject it.
-
-Source: `src/revocation.ts`.
-
-## Interfaces
-
-- `RevocationStore` — `isRevoked(sender, keyId, nowMs?)` and `revoke(sender, keyId, { untilMs? })`.
-- `InMemoryRevocationStore` — single-process implementation (tests, local dev, single node).
-- `createRedisRevocationStore` — Redis-backed shared store with cached reads.
-- `withRevocationCheck(resolver, store)` — wraps a signature resolver so a revoked key resolves to **no material**, which makes verification fail and the envelope is rejected.
-
-## Usage
-
-```ts
-import {
-  RollingKeyring,
-  createKeyringSignatureResolver,
-  createRedisRevocationStore,
-  withRevocationCheck,
-  receiveEnvelope,
-} from '@7h3/protocol'
-
-const keyring = new RollingKeyring(records)
-const revocations = createRedisRevocationStore(redisLikeClient, {
-  keyPrefix: 'aip:revoked:',
-  errorBehavior: 'reject', // fail closed (default)
-  cacheTtlMs: 5000,
-  onDegraded: (err, ctx) => metrics.increment('aip.revocation.degraded'),
-})
-
-const signatureResolver = withRevocationCheck(
-  createKeyringSignatureResolver(keyring),
-  revocations,
-)
-
-await receiveEnvelope(rawEnvelope, { signatureResolver })
-
-// Operationally, on a suspected compromise:
-await revocations.revoke('agent.worker', 'agent.worker-k1')           // permanent
-await revocations.revoke('agent.worker', 'agent.worker-k2', { untilMs: Date.now() + 86_400_000 }) // 24h
-```
-
-## Behavior on Redis outage (`errorBehavior`)
-
-| Value | On client error | Rationale |
-|---|---|---|
-| `reject` (default) | Treat the key as **revoked** (fail closed) | A revoked key is a compromised key — never accept on uncertainty |
-| `allow` | Treat the key as **not revoked** | Favor availability where the risk is acceptable |
-
-Reads are served from a short-lived local cache (`cacheTtlMs`), so:
-
-- the verify hot path does not hit Redis on every message (scalability), and
-- known revocations keep enforcing through a brief Redis outage (a stale cached
-  `revoked: true` is still honored).
-
-Every degraded decision fires `onDegraded` — degradation is never silent.
-
-## Operational guidance
-
-- Wire `withRevocationCheck` into every verifying node's `signatureResolver`.
-- Treat the `onDegraded` rate as a security signal; sustained degradation means
-  revocations may not be propagating.
-- Keep `cacheTtlMs` short enough that a revocation propagates within your SLA.

package/docs/MCP_WRAPPER.md

@@ -1,159 +0,0 @@
-# MCP Hardening Wrapper
-
-MCP messages are plain JSON-RPC 2.0 with no signature and no replay protection.
-This wrapper puts a signed AIP envelope around every MCP message on the wire —
-authenticating it, TTL-bounding it, and replay-checking it — **without changing
-your MCP handler**. Your handler still receives plain JSON-RPC `{ method, params }`
-and returns plain results; AIP lives entirely on the wire.
-
-Source: `src/mcpWrapper.ts`. Runnable demo: `npm run aip:mcp:wrap`.
-
-## Threat coverage
-
-| Threat | Covered by |
-|---|---|
-| Message tampering (params/method altered in flight) | Canonical signature over the envelope (HS256 / Ed25519) |
-| Replay / duplicate execution | `(sender, messageId, nonce)` replay cache + TTL; **on by default** (`InMemoryReplayCache` if none supplied) |
-| Cross-server relay (valid envelope for server A replayed to server B) | **Recipient binding** — the server runs the handler only when `recipient === selfAgentId` |
-| Response spoofing (another valid signer answers) | **Sender binding** — the client accepts a response only when `sender === peerAgentId` (peerAgentId is required) |
-| Response substitution (a valid response to request A returned for request B) | **Correlation binding** — the client requires `correlationId === the request's messageId` |
-| Compromised key still in use | Compose `withRevocationCheck` into `receive.signatureResolver` |
-
-`encodeRequest` returns `{ raw, messageId }`; pass `messageId` to `decodeResponse(raw, { expectCorrelationId })` to enforce the correlation binding (`wrapMcpClient` does this for you).
-
-## Server side — wrap an existing handler
-
-```ts
-import { wrapMcpServer, signEnvelopeHmac } from '@7h3/protocol'
-import { DistributedReplayCache, createRedisReplayStore } from '@7h3/protocol'
-
-// Your existing MCP handler — unchanged, AIP-unaware.
-async function myMcpServer(request) {
-  if (request.method === 'tools/call') return { jsonrpc: '2.0', id: request.id, result: runTool(request.params) }
-  return { jsonrpc: '2.0', id: request.id, error: { code: -32601, message: 'Method not found' } }
-}
-
-const secured = wrapMcpServer(myMcpServer, {
-  selfAgentId: 'agent.mcp-server',
-  sign: (e) => signEnvelopeHmac(e, process.env.AIP_SECRET!, 'server-k1'),
-  receive: {
-    secretResolver: async () => process.env.AIP_SECRET!,
-    replayCache: new DistributedReplayCache(createRedisReplayStore(redisLikeClient)), // fleet-wide replay
-  },
-})
-
-// `secured(rawWireEnvelope) => Promise<rawWireEnvelope>` — drop it into your stdio/HTTP transport read loop.
-```
-
-## HMAC vs Ed25519
-
-| | HMAC (HS256) | Ed25519 |
-|---|---|---|
-| Secret model | Shared secret — both sides can sign and verify | Keypair — only you can sign; peers verify with your public key |
-| Peer compromise | A compromised peer can forge messages | A compromised peer cannot forge your messages |
-| Key distribution | One secret distributed to all trusted peers | Public key is safe to publish; private key never leaves the signer |
-| When to use | Dev, testing, fully trusted internal infra | Production, multi-tenant, or any boundary where you do not control both sides |
-
-**Use HMAC when** you own both sides of the wire (same team, same trusted cluster) and want the simplest possible setup.
-
-**Use Ed25519 in production.** If a worker/peer node is compromised, the attacker gains verify capability only — they cannot impersonate the signer.
-
-Ed25519 server example (replace the HMAC `sign`/`receive` block above):
-
-```ts
-import { wrapMcpServer, signEnvelopeEd25519 } from '@7h3/protocol'
-
-// Generate keys once: npx @7h3/protocol-mcp → aip_generate_keypair
-// Set AIP_PRIVATE_KEY (server) and distribute AIP_CLIENT_PUBLIC_KEY (client's pubkey)
-
-const secured = wrapMcpServer(myMcpServer, {
-  selfAgentId: 'agent.mcp-server',
-  sign: (e) => signEnvelopeEd25519(e, process.env.AIP_PRIVATE_KEY!, 'k1'),
-  receive: {
-    signatureResolver: async (sig) =>
-      sig.alg === 'ED25519'
-        ? { alg: 'ED25519' as const, publicKey: process.env.AIP_CLIENT_PUBLIC_KEY! }
-        : undefined,
-  },
-})
-```
-
-## Client side — sign requests, verify responses
-
-```ts
-import { wrapMcpClient, signEnvelopeHmac } from '@7h3/protocol'
-
-const call = wrapMcpClient(transport.send /* (raw) => Promise<raw> */, {
-  selfAgentId: 'agent.mcp-client',
-  peerAgentId: 'agent.mcp-server',
-  sign: (e) => signEnvelopeHmac(e, process.env.AIP_SECRET!, 'client-k1'),
-  receive: { secretResolver: async () => process.env.AIP_SECRET! },
-})
-
-const result = await call({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'planner' } })
-// throws if the server response signature does not verify
-```
-
-`createMcpClientCodec(options)` exposes `encodeRequest` / `decodeResponse` directly
-when you manage the transport send yourself. `encodeRequest` returns
-`{ raw, messageId }`; pass that `messageId` as `decodeResponse(raw, { expectCorrelationId })`
-to bind each response to its request. `peerAgentId` is required so responses can be
-bound to the expected sender.
-
-## Composes with the rest of the stack
-
-The `receive` field is a full `ReceiveEnvelopeOptions`, so the wrapper inherits
-everything the transport pipeline offers:
-
-- **Fleet-wide replay** — pass a `DistributedReplayCache(createRedisReplayStore(...))`.
-- **Key revocation** — set `receive.signatureResolver = withRevocationCheck(resolver, revocationStore)`.
-- **Ed25519** — sign with `signEnvelopeEd25519` and resolve material via `signatureResolver`.
-- **Clock skew / TTL / telemetry** — `maxClockSkewMs`, `telemetry`, etc.
-
-## Transports
-
-The wrapper is transport-agnostic (it operates on wire envelopes). Two adapters
-connect it to real transports; both keep the handler on plain JSON-RPC.
-
-### stdio (newline-delimited)
-
-```ts
-import { wrapMcpServer, serveMcpOverStdio, createStdioMcpClient, wrapMcpClient } from '@7h3/protocol'
-
-// server process: read envelopes from stdin, write replies to stdout
-serveMcpOverStdio(wrapMcpServer(myMcpServer, serverOpts)) // defaults to process.stdin/stdout
-
-// client process: spawn the server and talk to it
-const stdio = createStdioMcpClient({ input: child.stdout, output: child.stdin })
-const call = wrapMcpClient(stdio.send, clientOpts)
-const result = await call({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'planner' } })
-```
-
-Stdio frames one envelope per line, so it supports the `json` and `compact` wire
-formats. For `binary`, use HTTP.
-
-### HTTP
-
-```ts
-import http from 'node:http'
-import { wrapMcpServer, createHttpMcpHandler, createHttpMcpClient, wrapMcpClient } from '@7h3/protocol'
-
-// server: any node:http-compatible host
-http.createServer(createHttpMcpHandler(wrapMcpServer(myMcpServer, serverOpts))).listen(8787)
-
-// client: POSTs each request envelope, returns the reply envelope (global fetch)
-const httpClient = createHttpMcpClient({ url: 'http://localhost:8787' })
-const call = wrapMcpClient(httpClient.send, clientOpts)
-const result = await call({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'planner' } })
-```
-
-Pass `{ binary: true }` to both `createHttpMcpHandler` and `createHttpMcpClient`
-to use the `binary` wire format over HTTP.
-
-## Notes
-
-- Both peers must be wrapped: the on-wire message is an AIP envelope, not plain
-  JSON-RPC. For interop with un-wrapped MCP peers, terminate AIP at a gateway.
-- `wireFormat` defaults to `compact`; use `binary` for the highest-throughput lanes.
-- Verification failures and replays come back as signed JSON-RPC errors
-  (`-32600`), so the client still gets an authenticated, well-formed response.

package/docs/MIGRATION_GUIDE.md

@@ -1,40 +0,0 @@
-# AIP Migration Guide
-
-## Import path migration (JS/TS)
-
-Use the stable package subpath export:
-
-```ts
-import { createAipAgentAdapter, receiveEnvelope } from '@7h3/protocol'
-```
-
-Avoid repo-relative imports in consumer apps.
-
-## Signature profile migration
-
-### HS256 to ED25519
-
-1. Generate/provision ED25519 key pairs.
-2. Keep HS256 verification active during overlap window.
-3. Start signing outbound envelopes with ED25519.
-4. Monitor verify failures by algorithm.
-5. Revoke/decommission HS256 keys after migration window.
-
-## Replay cache migration
-
-### Single-node to distributed
-
-1. Replace `InMemoryReplayCache` with `DistributedReplayCache`.
-2. Implement atomic reserve in shared store (for example Redis `SET NX PX`).
-3. Roll out gradually and monitor replay reject metrics.
-
-## Clock skew migration
-
-1. Start with default `maxClockSkewMs` (30s).
-2. Tighten to lower values in synchronized environments.
-3. Monitor `rejected_clock_skew` telemetry for false-positive tuning.
-
-## Rollback guidance
-
-- Keep prior verification profiles and key material during rollout.
-- Do not remove old verifiers until telemetry confirms stable traffic.