@7h3/protocol 0.1.2 → 0.4.0

package/docs/RELEASE_BENCHMARK_REPORT_2026-05-15.md

@@ -0,0 +1,135 @@
+# Release Benchmark Report (2026-05-15)
+
+## 1) Metadata
+
+- Report ID: `gluv-release-bench-2026-05-15`
+- Date/Time (UTC): 2026-05-15 (updated 2026-05-18)
+- Branch/Commit: `bbcd960` (Fix inFlight counter leak in HTTP batch bench server handler)
+- Runtime: Node.js `v24.10.0`
+- Machine: local benchmark host (same environment used for prior release-gate runs)
+
+## 2) Scope
+
+- Profile: `full` (segmented mode-by-mode to avoid timeout)
+- Modes tested:
+  - `ws`, `ws-batch`, `ws-binary`, `ws-binary-batch`
+  - `http-binary`
+  - `http-batch` (concurrency 10 lanes complete; concurrency 100 unstable/timeout)
+  - `http-binary-batch` (concurrency 10 lanes complete; concurrency 100 incomplete)
+- Payload sizes: `256`, `1024`, `4096` bytes
+- Concurrency levels targeted: `10`, `100`
+
+## 3) Security Configuration Matrix
+
+| Check | Full Secure Protocol |
+|---|---:|
+| Signature verification | enabled |
+| Canonicalization | enabled |
+| Replay defense | enabled |
+| TTL/clock-skew enforcement | enabled |
+| Policy checks/guardrails | enabled |
+
+Notes:
+- Guardrail for unsafe plain `http` high-concurrency was enforced.
+- No benchmark run in this report used invariant-bypass settings.
+
+## 4) Commands Executed (Representative)
+
+```bash
+npx tsx scripts/bench-protocol-openloop.ts --profile full --ci --adaptive --p99-threshold 250 --drop-threshold-pct 2 --adaptive-max-doublings 6 --adaptive-binary-steps 8 --modes ws
+npx tsx scripts/bench-protocol-openloop.ts --profile full --ci --adaptive --p99-threshold 250 --drop-threshold-pct 2 --adaptive-max-doublings 6 --adaptive-binary-steps 8 --modes ws-batch
+npx tsx scripts/bench-protocol-openloop.ts --profile full --ci --adaptive --p99-threshold 250 --drop-threshold-pct 2 --adaptive-max-doublings 6 --adaptive-binary-steps 8 --modes ws-binary
+npx tsx scripts/bench-protocol-openloop.ts --profile full --ci --adaptive --p99-threshold 250 --drop-threshold-pct 2 --adaptive-max-doublings 6 --adaptive-binary-steps 8 --modes ws-binary-batch
+npx tsx scripts/bench-protocol-openloop.ts --profile full --ci --adaptive --p99-threshold 250 --drop-threshold-pct 2 --adaptive-max-doublings 6 --adaptive-binary-steps 8 --modes http-binary
+npx tsx scripts/bench-protocol-openloop.ts --profile full --adaptive --p99-threshold 250 --drop-threshold-pct 2 --adaptive-max-doublings 6 --adaptive-binary-steps 8 --modes http-batch --payloads 256,1024,4096 --concurrency 10
+npx tsx scripts/bench-protocol-openloop.ts --profile full --adaptive --p99-threshold 250 --drop-threshold-pct 2 --adaptive-max-doublings 6 --adaptive-binary-steps 8 --modes http-binary-batch --payloads 256,1024,4096 --concurrency 10
+```
+
+## 5) Results Summary (Best observed per lane)
+
+### Full Secure Protocol (authoritative)
+
+| Mode | Payload | Concurrency | Ops/s | Drop % | p99 ms | Sustainable |
+|---|---:|---:|---:|---:|---:|---|
+| ws | 256 | 100 | 6548.375 | 0.000 | 49.669 | yes |
+| ws | 1024 | 100 | 5887.500 | 0.000 | 53.772 | yes |
+| ws | 4096 | 100 | 3887.500 | 0.000 | 66.011 | yes |
+| ws-batch | 256 | 100 | 7649.000 | 0.000 | 30.971 | yes |
+| ws-batch | 1024 | 100 | 6749.500 | 0.000 | 37.306 | yes |
+| ws-batch | 4096 | 100 | 3850.000 | 0.000 | 49.455 | yes |
+| ws-binary | 256 | 100 | 7261.000 | 0.000 | 53.193 | yes |
+| ws-binary | 1024 | 100 | 5087.375 | 0.000 | 73.307 | yes |
+| ws-binary | 4096 | 100 | 3662.500 | 0.000 | 77.854 | yes |
+| ws-binary-batch | 256 | 100 | 5750.000 | 0.000 | 36.134 | yes |
+| ws-binary-batch | 1024 | 100 | 6499.000 | 0.000 | 35.508 | yes |
+| ws-binary-batch | 4096 | 100 | 4246.000 | 0.000 | 63.565 | yes |
+| http-binary | 256 | 100 | 2699.875 | 0.000 | 129.755 | yes |
+| http-binary | 1024 | 100 | 2385.000 | 0.000 | 119.438 | yes |
+| http-binary | 4096 | 100 | 11993.750 | 0.000 | 17.647 | yes |
+| http-batch | 256 | 10 | 399.125 | 1.359 | 0.867 | yes |
+| http-batch | 1024 | 10 | 291.625 | 1.686 | 0.939 | yes |
+| http-batch | 4096 | 10 | 320.500 | 1.536 | 1.259 | yes |
+| http-binary-batch | 256 | 10 | 276.000 | 1.779 | 0.979 | yes |
+| http-binary-batch | 1024 | 10 | 260.000 | 1.887 | 0.983 | yes |
+| http-binary-batch | 4096 | 10 | 447.500 | 1.214 | 1.260 | yes |
+
+### Updated results after bug fix (2026-05-18, commit `bbcd960`)
+
+Root cause identified and fixed: the `inFlight` counter in the HTTP batch bench server handler was never decremented for batch requests, causing it to accumulate until the server began 503-ing all traffic. Fix: added `finally { this.inFlight -= 1 }` to the batch path.
+
+| Mode | Payload | Concurrency | Ops/s | Drop % | p99 ms | Sustainable |
+|---|---:|---:|---:|---:|---:|---|
+| http-batch | 256 | 100 | 34940.000 | 0.000 | 7.877 | yes |
+| http-batch | 1024 | 100 | 21460.000 | 0.000 | 11.470 | yes |
+| http-batch | 4096 | 100 | 17886.667 | 0.000 | 13.683 | yes |
+| http-binary-batch | 256 | 100 | 28238.000 | 0.000 | 8.551 | yes |
+| http-binary-batch | 1024 | 100 | 19056.000 | 0.000 | 22.214 | yes |
+| http-binary-batch | 4096 | 100 | 11096.000 | 0.000 | 20.675 | yes |
+
+Evidence: `dist/bench/protocol-openloop.quick.2026-05-18T09-23-51-852Z.json`
+
+## 6) SLO Gate Status
+
+Defined gates used in this closure cycle:
+
+- Interactive lanes: `p99 <= 25ms`, `drop <= 2%`
+- High-throughput lanes: `p99 <= 250ms`, `drop <= 2%`
+
+Current status:
+
+- WS lanes (`ws*`): PASS on completed lanes.
+- `http-binary`: PASS on completed lanes.
+- `http-batch` and `http-binary-batch`: PASS at concurrency `100` after `bbcd960` bug fix (0% drop, all p99 within gate).
+
+Overall decision: `GO (all lanes pass SLO gates as of 2026-05-18)`
+
+## 7) Reliability Hardening Applied During Benchmarking
+
+- Added HTTP/2 server stream `error` handling in bench harness.
+- Added HTTP/2 client session `error` handling in bench harness.
+- These are benchmark resilience fixes and do not alter protocol invariants.
+
+## 8) Evidence Artifacts
+
+- `dist/bench/protocol-openloop.full.2026-05-15T08-33-35-118Z.json`
+- `dist/bench/protocol-openloop.full.2026-05-15T08-48-39-773Z.json`
+- `dist/bench/protocol-openloop.full.2026-05-15T09-03-28-317Z.json`
+- `dist/bench/protocol-openloop.full.2026-05-15T09-18-35-320Z.json`
+- `dist/bench/protocol-openloop.full.2026-05-15T09-33-32-306Z.json`
+- `dist/bench/protocol-openloop.full.2026-05-15T10-48-40-452Z.json`
+- `dist/bench/protocol-openloop.full.2026-05-15T11-18-47-746Z.json`
+
+## 9) Security Review Checklist
+
+- [x] Signature verification enabled
+- [x] Replay defense enabled
+- [x] TTL/clock-skew checks enabled
+- [x] Canonicalization enabled
+- [x] Policy validation run (`npm run policy:validate`)
+- [x] Release gate re-run after harness changes (`npm run release:gate`)
+
+## 10) Next Actions for Full Closure
+
+- ~~Rework HTTP batch transport path before re-qualification at concurrency `100`.~~ Resolved by `bbcd960`.
+- All transport modes qualified. No further bench gate blockers.
+- Proceed with `@7h3/protocol` publish from `dist/npm-aip/` via release automation.

package/docs/RELEASE_GATE.md

@@ -0,0 +1,25 @@
+# GLUV Release Gate
+
+Run this gate before publishing protocol performance claims or changing transport defaults.
+
+```bash
+npm run release:gate
+```
+
+The gate runs tests, AIP build, lint, wire benchmarks, and adaptive open-loop CI checks. For release candidates, also run:
+
+```bash
+npm run bench:wire:full
+npm run bench:replay:full
+npm run bench:openloop:full
+npm run conformance:binary
+npm run conformance:python
+npm run conformance:rust
+```
+
+## Rollout Rules
+
+- Compact JSON remains the default wire format for `aip/0.1` compatibility.
+- Binary wire and binary WebSocket modes are opt-in until negotiated through `CAPS`.
+- Signature verification, replay defense, TTL validation, and canonicalization must stay enabled in all benchmark claims.
+- README performance numbers must come from fresh benchmark artifacts committed or attached to the release.

package/docs/RELEASE_NOTES_v0.1.0.md

@@ -0,0 +1,54 @@
+# v0.1.0 — First public release
+
+> **The signing-and-replay layer your agent protocol forgot.**
+
+MCP sends JSON-RPC unsigned. A2A signs the identity card, not the traffic.  
+`@7h3/protocol` puts a signed, TTL-bounded, replay-checked AIP envelope around every message — without touching your handler.
+
+## What's included
+
+**Core AIP (`aip/0.1`)**  
+Real WebCrypto HMAC-SHA256 + Ed25519 over a deterministic canonical form. Byte-identical signatures in TypeScript, Python, and Rust via a shared conformance fixture.
+
+**Distributed replay protection**  
+Redis-backed `SET NX PX` atomic reserve. Client-agnostic (`RedisLikeClient`) — works with ioredis, node-redis, or any adapter. Graceful degradation to local store on Redis outage; `onDegraded` hook for observability.
+
+**Fleet-wide key revocation**  
+Cached reads, fail-closed default. Wraps any `SignatureResolver` — one line to add revocation to an existing verify path.
+
+**MCP hardening wrapper**  
+Drop `wrapMcpServer` around your handler. Add `wrapMcpClient` on the caller. Four threat bindings enforced out of the box:
+
+| Binding | Defends against |
+|---|---|
+| Recipient | Cross-server replay |
+| Sender | Response spoofing |
+| Correlation | Response substitution |
+| Replay (default on) | Duplicate execution |
+
+**Transport adapters**  
+`serveMcpOverStdio` + `createHttpMcpHandler` — real transports, no new npm deps.
+
+## Install
+
+```bash
+npm install @7h3/protocol
+```
+
+## Quick demo
+
+```bash
+git clone https://github.com/IceMasterT/7h3-protocol-aip
+cd 7h3-protocol-aip && npm install
+npm run aip:mcp:wrap   # proves tamper + replay rejection
+```
+
+## Honest caveats
+
+- No independent security audit yet — reproductions and findings welcome.
+- Distributed stores require a Redis (or equivalent) control plane; operators own HA and clock sync.
+- Wire version `aip/0.1` is stable; the TypeScript API is pre-1.0 (minor version may bring breaking changes).
+
+## License
+
+MIT.

package/docs/SECURITY_REVIEW_2026-06-05.md

@@ -0,0 +1,165 @@
+# Internal Security Review — AIP v0.1.2
+
+**Date:** 2026-06-05  
+**Reviewer:** Claude Code (AI-assisted internal review)  
+**Scope:** `@7h3/protocol` v0.1.2 — TypeScript sources, Python SDK, Rust SDK  
+**Status:** ⚠️ NOT an independent third-party audit. This review was performed by the same AI assistant that co-developed parts of the codebase. It is published for transparency; it does not substitute for an independent cryptographic audit.
+
+---
+
+## Summary
+
+The core cryptographic choices are sound: WebCrypto primitives for both HMAC-SHA256 and Ed25519, constant-time verification, algorithm-confusion guards, and fail-closed revocation. Two real bugs were found and fixed in this review pass. No signature-forgery or authentication-bypass paths were identified.
+
+| Finding | Severity | Status |
+|---|---|---|
+| Replay key collision via unescaped `\|` separator | Medium | **Fixed** — `encodeURIComponent` applied |
+| Empty nonce not rejected by `validateEnvelope` | Low | **Fixed** — error diagnostic added |
+| Rust cargo-fuzz targets uncompiled (README overclaim) | Low | **Corrected in README** |
+| `recipient: null` vs `undefined` — cross-language parity gap | Low | Documented accepted risk |
+| Revocation key space-separator (minor variant of #1) | Low | Documented accepted risk |
+
+---
+
+## Finding 1 — Replay Key Collision (Medium, Fixed)
+
+**File:** `src/protocolReplay.ts` — `InMemoryReplayCache.makeKey` and `DistributedReplayCache.makeKey`
+
+**Before:**
+```ts
+return `${envelope.header.sender}|${envelope.header.messageId}|${envelope.header.nonce}`
+```
+
+**Problem:** The `|` separator is unescaped. A sender named `"a|b"` with messageId `"c"` produces the same composite key as sender `"a"` with messageId `"b|c"`. If an attacker controls their own agent ID and can observe or predict a target agent's messageId, they can send a message first that "claims" the target's replay key, causing the legitimate message to be rejected as a replay.
+
+**Security impact:** This is a **false-rejection DoS**, not a forgery or auth bypass. Signatures still cover the full, unencoded field values — an attacker cannot craft a message that validates under a victim's key. The worst they can achieve is having a legitimate message silently dropped.
+
+**Fix applied:**
+```ts
+return `${encodeURIComponent(envelope.header.sender)}|${encodeURIComponent(envelope.header.messageId)}|${encodeURIComponent(envelope.header.nonce)}`
+```
+
+`encodeURIComponent` maps `|` → `%7C`, making cross-boundary collisions impossible. For typical agent IDs containing only word characters and hyphens, the output is byte-identical to the old format — no Redis key migration required for standard deployments.
+
+**Note on deployed keys:** If your Redis instance already contains replay keys with agent IDs containing `|`, `%`, or other URI-reserved characters, those keys will have a different format after this fix. Existing entries will expire naturally via their TTL; no manual migration is needed.
+
+---
+
+## Finding 2 — Empty Nonce Not Validated (Low, Fixed)
+
+**File:** `src/protocol.ts` — `validateEnvelope`
+
+**Problem:** `validateEnvelope` checked `messageId`, `sender`, `ttlMs`, `timestampMs`, and `content` but did not validate `nonce`. A missing or empty nonce produces a replay key of the form `sender||messageId`. While this doesn't defeat replay protection outright (the composite key still covers sender + messageId), it eliminates the entropy contribution of the nonce and allows any two messages with identical sender + messageId to collide in the replay cache, regardless of time.
+
+**Fix applied:** Added `if (!nonce.trim()) diagnostics.push({ level: 'error', message: 'Missing nonce — replay protection requires a unique nonce per message' })`.
+
+---
+
+## Finding 3 — Rust cargo-fuzz Targets Uncompiled (Low, Corrected)
+
+**File:** `sdk/rust/fuzz/`, `README.md` status table
+
+**Problem:** `cargo-fuzz` is not installed in the development environment. The Rust fuzz targets (`fuzz_decode.rs`, `fuzz_canonicalize.rs`) were authored and reviewed but have never been compiled or run. The prior README entry claimed "✅ cargo-fuzz targets" without this qualification.
+
+**Correction:** The README status now reads: "TypeScript harnesses run clean (50k/20k rounds); Rust targets authored, not yet executed (`cargo-fuzz` not installed)."
+
+The targets themselves look structurally correct:
+- `fuzz_decode`: feeds arbitrary bytes through `decode_envelope` under a no-panic invariant — correct
+- `fuzz_canonicalize`: constructs `ProtocolEnvelope` from fuzz bytes, asserts `canonicalize_envelope` is idempotent — correct
+
+To run:
+```bash
+rustup toolchain install nightly
+cargo install cargo-fuzz
+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
+```
+
+---
+
+## Finding 4 — `recipient: null` vs Absent (Low, Accepted Risk)
+
+**File:** `src/protocol.ts` — `serializeHeaderCanonical`
+
+```ts
+if (header.recipient !== undefined) {
+  parts.push(`"recipient":${JSON.stringify(header.recipient)}`)
+}
+```
+
+If a JSON message arrives with `"recipient": null`, JavaScript parses this as `null`, which passes the `!== undefined` check. `JSON.stringify(null)` produces `"null"`, so the canonical form includes `"recipient":null` — different from a message where `recipient` is absent entirely.
+
+In the TypeScript type system, `ProtocolHeader.recipient` is typed as `string | undefined`. A `null` value is a type violation but not rejected at runtime.
+
+**Cross-language risk:** The Rust SDK uses `Option<String>` for `recipient`, which serializes `None` as absent (the field is skipped). If a TS caller writes `recipient: null` and the Rust verifier receives it, the canonical forms diverge → signature mismatch.
+
+**Status:** Accepted risk. The correct mitigation is to normalise `null` → `undefined` in the wire decoder. This is tracked as a future improvement. In practice, `null` recipients do not appear in protocol-generated envelopes (`createEnvelope` leaves `recipient` undefined when not supplied).
+
+---
+
+## Finding 5 — Revocation Key Space Separator (Low, Accepted Risk)
+
+**File:** `src/revocation.ts` — `InMemoryRevocationStore.makeKey` and `createRedisRevocationStore`
+
+The revocation key format `"${sender} ${keyId}"` uses a space as separator. If a sender ID contains a space (e.g., `"agent one"`) and a keyId starts with something that continues the pattern, a collision is theoretically possible. However:
+
+1. Key IDs in practice are short tokens like `"k1"`, `"prod-key-2026"` — not containing spaces
+2. Agent IDs with spaces are unusual enough to warrant operator documentation
+3. The collision would cause a revocation miss (treating a non-revoked key as revoked, or vice versa) — not an auth bypass
+
+**Status:** Accepted risk. Documented in this review. Consider changing to `${encodeURIComponent(sender)}:${encodeURIComponent(keyId)}` in a future patch.
+
+---
+
+## Positive Findings
+
+### Constant-time HMAC verification
+
+`hmacVerify` delegates to `crypto.subtle.verify` (WebCrypto), which is specified to run in constant time. There is no string `===` comparison of signature bytes anywhere on the verify hot path.
+
+### Algorithm confusion rejected
+
+`verifyEnvelopeSignature` checks `signature.alg !== material.alg` before dispatching. An envelope signed with Ed25519 cannot be verified with HMAC material and vice versa — the check is at the dispatch level, before any cryptographic operation.
+
+`verifyEnvelopeHmac` checks `envelope.signature.alg !== 'HS256'` explicitly before calling `hmacVerify`. Same for `verifyEnvelopeEd25519` / `'ED25519'`. Downgrade attacks via algorithm confusion are blocked at two independent points.
+
+### Revocation fail-closed
+
+`createRedisRevocationStore` defaults to `errorBehavior: 'reject'`. A Redis outage causes the store to treat the key as revoked. Cached stale-revoked entries serve during brief outages without allowing a previously-revoked key through.
+
+### MCP wrapper — all four bindings present
+
+Code review confirms all four claimed bindings in `src/mcpWrapper.ts`:
+
+| Binding | Code location | Enforcement |
+|---|---|---|
+| Recipient | line 120: `envelope.header.recipient !== options.selfAgentId` | Returns 32600 error; handler does not run |
+| Sender | line 176: `received.envelope.header.sender !== options.peerAgentId` | Throws; response discarded |
+| Correlation | line 181: `body.correlationId !== decodeOptions.expectCorrelationId` | Throws; response discarded |
+| Replay | `InMemoryReplayCache` injected by default in `wrapMcpServer` | Replay → `consume()` returns `{ok: false}` |
+
+### Cross-language parity (within tested scope)
+
+The three conformance vectors in `conformance/aip_v0_1.json` produce byte-identical signatures in TypeScript, Python, and Rust. The canonicalization format is simple string concatenation with fixed key order; there is no runtime type ambiguity within the tested input set.
+
+**Caveat:** Three vectors are a narrow coverage set. Cross-language divergence on edge cases (very large integers, Unicode normalization, `NaN`/`Infinity` in numeric fields) is not covered by the current conformance suite.
+
+---
+
+## Scope Not Covered
+
+| Area | Reason not covered |
+|---|---|
+| WebCrypto Ed25519 implementation | Browser/Node built-in; outside reviewable scope |
+| Binary wire format (protocolBinary.ts) | Not reviewed in this pass — fuzz coverage via `protocolFuzz.advanced.test.ts` exists |
+| Framework adapters (LangChain, LlamaIndex) | Translation adapters; lower security surface |
+| Policy enforcer | Logic review only; not cryptographic |
+| Python pure-Ed25519 implementation | Correctness verified against conformance vector; not audited for side channels |
+
+---
+
+## Conclusion
+
+The cryptographic architecture is well-chosen: standard primitives, no custom crypto, constant-time comparison, fail-closed defaults. The two bugs fixed in this review (replay key collision, empty nonce) were low-to-medium severity and have been patched. No authentication bypass, signature forgery, or replay-protection bypass paths were found.
+
+**This review does not substitute for an independent third-party audit by a qualified cryptographer.** The parsing, canonicalization, and replay-cache logic remain unaudited by an external reviewer. Treat accordingly for high-stakes deployments.

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/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 },
+    },
+  },
+)