@7h3/protocol 0.1.2 → 0.4.0

package/docs/DISTRIBUTED_REPLAY.md

@@ -0,0 +1,142 @@
+# Distributed Replay Defense
+
+7h3 Protocol AIP protects against replay through pluggable cache interfaces.
+
+## Interfaces
+
+- `InMemoryReplayCache`: single-process replay protection.
+- `DistributedReplayCache`: wraps a shared `DistributedReplayStore` for multi-node deployments.
+- `createRedisReplayStore`: a production `DistributedReplayStore` backed by Redis-style `SET NX PX`.
+
+Source: `src/protocolReplay.ts`, `src/replayStores.ts`.
+
+## Client-agnostic by design
+
+The library ships **no Redis dependency**. You inject any client matching the
+small `RedisLikeClient` surface (`set` with `nx`/`pxMs`, optional `get`/`del`,
+optional `pipeline`). `ioredis`, `node-redis`, Upstash, or a cluster proxy all
+adapt in a few lines. An `InMemoryRedisLikeClient` reference implementation is
+provided for tests and local development.
+
+## Usage
+
+```ts
+import { DistributedReplayCache, createRedisReplayStore, receiveEnvelope } from '@7h3/protocol'
+import Redis from 'ioredis'
+
+const redis = new Redis(process.env.REDIS_URL)
+
+const replayCache = new DistributedReplayCache(
+  createRedisReplayStore(
+    // adapt ioredis' set(key, val, 'PX', ms, 'NX') to the RedisLikeClient shape:
+    {
+      set: async (key, value, opts = {}) => {
+        const args = []
+        if (opts.pxMs !== undefined) args.push('PX', opts.pxMs)
+        if (opts.nx) args.push('NX')
+        return (await redis.set(key, value, ...args)) === 'OK' ? 'OK' : null
+      },
+    },
+    {
+      keyPrefix: 'aip:replay:',
+      errorBehavior: 'fallback', // degrade to local store on a Redis outage
+      onDegraded: (err) => metrics.increment('aip.replay.degraded'),
+    },
+  ),
+)
+
+await receiveEnvelope(rawEnvelope, { replayCache, secretResolver: async () => sharedSecret })
+```
+
+## Shared store contract
+
+`DistributedReplayStore.reserve(key, expiresAtMs, nowMs)` must be atomic:
+
+- Return `true` when the key is newly reserved.
+- Return `false` when the key is already reserved and still valid.
+
+`key` format is `sender|messageId|nonce`. The optional `reserveMany(entries, nowMs)`
+performs a batched reserve (one round-trip via a client pipeline) and is used
+automatically by `DistributedReplayCache.consumeMany` when present.
+
+## Behavior on Redis outage (`errorBehavior`)
+
+| Value | On client error | Use when |
+|---|---|---|
+| `fallback` (default) | Degrade to a local in-memory store — traffic flows, single-node replay protection stays in force, and TTL still bounds replays | Default; balances safety and uptime |
+| `reject` | Fail closed — deny the message | Strictest security posture |
+| `allow` | Fail open — accept the message | Uptime outweighs the narrow replay risk |
+
+Every degraded decision fires `onDegraded` so the condition is observable — degradation is never silent.
+
+## High-availability topologies
+
+### Redis Sentinel
+
+ioredis connects to Sentinel transparently. The adapter wrapper is identical to standalone Redis:
+
+```ts
+import Redis from 'ioredis'
+
+const redis = new Redis({
+  sentinels: [
+    { host: 'sentinel-1', port: 26379 },
+    { host: 'sentinel-2', port: 26379 },
+    { host: 'sentinel-3', port: 26379 },
+  ],
+  name: 'mymaster',
+})
+
+const aipRedis = {
+  set: async (key: string, value: string, opts: { nx?: boolean; pxMs?: number } = {}) => {
+    const args: (string | number)[] = []
+    if (opts.pxMs !== undefined) args.push('PX', opts.pxMs)
+    if (opts.nx) args.push('NX')
+    return (await redis.set(key, value, ...(args as [string, number, string]))) === 'OK'
+      ? ('OK' as const)
+      : null
+  },
+}
+
+const replayCache = new DistributedReplayCache(
+  createRedisReplayStore(aipRedis, { errorBehavior: 'fallback' }),
+)
+```
+
+Sentinel handles leader election automatically. During failover (typically < 30 s), `errorBehavior` controls whether requests are rejected or degrade to local replay protection.
+
+### Redis Cluster
+
+AIP replay keys (`aip:replay:{sender}:{messageId}:{nonce}`) and revocation keys (`aip:revoked:{keyId}`) are independent — no cross-slot transactions required. Cluster mode works without modification. Adapt a Cluster client the same way as standalone.
+
+```ts
+const cluster = new Redis.Cluster([
+  { host: 'node-1', port: 7000 },
+  { host: 'node-2', port: 7001 },
+  { host: 'node-3', port: 7002 },
+])
+// adapter wrapper identical to standalone
+```
+
+### Upstash (serverless / edge)
+
+Upstash's `@upstash/redis` client's `set` method matches `RedisLikeClient` directly:
+
+```ts
+import { Redis } from '@upstash/redis'
+
+const redis = new Redis({ url: process.env.UPSTASH_URL!, token: process.env.UPSTASH_TOKEN! })
+
+const aipRedis = {
+  set: async (key: string, value: string, opts: { nx?: boolean; pxMs?: number } = {}) =>
+    redis.set(key, value, { nx: opts.nx, px: opts.pxMs }),
+}
+```
+
+## Operational guidance
+
+- Use a distributed replay cache for any horizontally scaled gateway.
+- Keep clocks synchronized (NTP / PTP) — AIP TTL checks require clocks within the configured skew window (default ±30 s) across all nodes and Sentinel/Cluster members.
+- Monitor replay reject rate and `onDegraded` rate as security / health signals.
+- During Redis failover, `errorBehavior: 'fallback'` keeps traffic flowing under single-node replay protection. `errorBehavior: 'reject'` is safer but means failover = downtime for inbound envelopes. Choose the posture that matches your threat model.
+- The replay store is the only component AIP requires Redis for. The revocation store (`createRedisRevocationStore`) uses the same `RedisLikeClient` interface and the same HA patterns apply.

package/docs/FUZZ_CAMPAIGN.md

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

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

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

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