@7h3/protocol 0.1.2 → 0.4.0

package/.dockerignore

@@ -0,0 +1,19 @@
+# Node modules — rebuilt inside the image by npm ci
+node_modules
+
+# Git history — not needed in image layers
+.git
+
+# Log files
+*.log
+
+# Compiled TypeScript output from local dev builds (the Dockerfile
+# builder stage produces its own clean dist/)
+dist
+
+# Rust build artefacts from the SDK sub-crate — large and irrelevant
+# to the Node.js runtime image
+sdk/rust/target
+
+# Benchmark result JSON snapshots — not needed at runtime
+bench-results

package/.github/dependabot.yml

@@ -0,0 +1,32 @@
+version: 2
+updates:
+  # Root package (npm)
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    target-branch: "main"
+    groups:
+      npm-non-security:
+        applies-to: version-updates
+        patterns:
+          - "*"
+
+  # mcp-server sub-package (npm)
+  - package-ecosystem: "npm"
+    directory: "/mcp-server"
+    schedule:
+      interval: "weekly"
+    target-branch: "main"
+    groups:
+      npm-mcp-non-security:
+        applies-to: version-updates
+        patterns:
+          - "*"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    target-branch: "main"

package/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+      - run: npm install
+      - run: npm run lint
+      - run: npm run test
+      - run: npm run build:aip
+  conformance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - run: pip install cryptography
+      - run: npm install
+      - run: npm run conformance:python
+      - run: npm run conformance:rust

package/.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish-aip:
+    name: publish @7h3/protocol
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build dist/npm-aip
+        run: npm run package:aip
+
+      - name: Publish @7h3/protocol
+        run: npm publish --provenance --access public
+        working-directory: dist/npm-aip
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  publish-mcp:
+    name: publish @7h3/protocol-mcp
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: mcp-server
+
+      - name: Build mcp-server
+        run: npm run build
+        working-directory: mcp-server
+
+      - name: Publish @7h3/protocol-mcp
+        run: npm publish --provenance --access public
+        working-directory: mcp-server
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/scorecard.yml

@@ -0,0 +1,37 @@
+name: scorecard
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: '30 1 * * 1'  # weekly, Monday 01:30 UTC
+  pull_request:
+    branches: [main]
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: scorecard-analysis
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Run OpenSSF Scorecard
+        uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a  # v2.4.3
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - name: Upload SARIF to GitHub Security tab
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: results.sarif

package/7h3.example.yaml

@@ -0,0 +1,125 @@
+# 7h3 Protocol — Gateway Configuration Example
+# Wire version: 7h3/0.1
+# Reference: docs/GATEWAY.md
+#
+# All fields shown below are optional unless marked (required).
+
+# ---------------------------------------------------------------------------
+# Core proxy settings
+# ---------------------------------------------------------------------------
+
+# (required) URL of the upstream service to proxy requests to.
+# The gateway strips AIP envelopes, verifies signatures, and forwards clean
+# HTTP requests to this address. The request path is appended verbatim.
+upstream: http://api:3000
+
+# Port the gateway HTTP server binds to (default: 8080).
+port: 8080
+
+# ---------------------------------------------------------------------------
+# Gateway identity — needed only when sign_responses: true
+# ---------------------------------------------------------------------------
+
+# The sender identifier this gateway uses when signing response envelopes.
+# Must match the key-id advertised in your /.well-known/7h3-keys document
+# if you are using key-discovery.
+sender: gateway@my-service.example.com
+
+# Ed25519 private key (PKCS8, base64url-encoded) used to sign responses.
+# Generate one with:  7h3 keygen --output my-keys.json
+# Keep this value secret — store it in a mounted secret or environment
+# variable and reference it as $GATEWAY_PRIVATE_KEY instead.
+#
+# private_key: <base64url-encoded PKCS8 private key>   # or use $GATEWAY_PRIVATE_KEY
+
+# Whether the gateway should sign every upstream response it proxies.
+# Requires private_key and sender to be set. (default: false)
+sign_responses: false
+
+# ---------------------------------------------------------------------------
+# Default policy
+# ---------------------------------------------------------------------------
+
+# What to do when an incoming request does not match any entry in the
+# `policies` list below.
+#
+#   allow — pass the request through without signature verification
+#           (use for development or fully-open APIs)
+#   deny  — reject with HTTP 403
+#           (use for production; whitelist routes explicitly via policies)
+#
+# default: allow
+default_policy: deny
+
+# ---------------------------------------------------------------------------
+# Key registry — maps sender identities to their public keys
+# ---------------------------------------------------------------------------
+
+keys:
+  # The gateway's own public key (used to verify self-signed test requests
+  # or to advertise via the /.well-known/7h3-keys endpoint).
+  private_key: <base64url-encoded PKCS8 private key>
+
+  # Registry maps senderID (any opaque string) → Ed25519 SPKI public key
+  # (base64url-encoded). Add one entry per trusted agent or service.
+  registry:
+    # Internal orchestrator service
+    orchestrator@my-service.example.com: <base64url-encoded SPKI public key>
+
+    # Admin automation agent with elevated privileges
+    admin-agent@my-service.example.com: <base64url-encoded SPKI public key>
+
+    # Third-party partner integration
+    partner-bot@partner.example.com: <base64url-encoded SPKI public key>
+
+# ---------------------------------------------------------------------------
+# Route policies
+# ---------------------------------------------------------------------------
+# Evaluated in order — the first matching policy wins.
+# Glob syntax:
+#   /exact/path      — exact match
+#   /api/*           — single segment wildcard (no slashes)
+#   /api/**          — multi-segment wildcard (crosses slashes)
+#   /users/?d        — single character wildcard
+#
+# Policy fields:
+#   path             — glob pattern (required)
+#   require          — signature algorithm: ed25519 | hmac | any | none
+#   allowed_senders  — list of senderIDs permitted on this route
+#                      (omit to allow any verified sender)
+#   rate_limit       — sliding-window limit applied per sender
+#     requests       — max requests in the window
+#     window_ms      — window duration in milliseconds
+#   sign_response    — override sign_responses for this route only
+
+policies:
+  # -- Admin endpoints -------------------------------------------------
+  # Require Ed25519 signatures and restrict to explicitly named agents.
+  # No rate limit — admin tooling is expected to be low-volume.
+  - path: /api/admin/**
+    require: ed25519
+    allowed_senders:
+      - admin-agent@my-service.example.com
+      - orchestrator@my-service.example.com
+    sign_response: true     # always sign admin responses so callers can verify
+
+  # -- General API endpoints -------------------------------------------
+  # Require Ed25519; any verified sender may call; rate-limit per sender
+  # to 1 000 requests per 60-second sliding window.
+  - path: /api/**
+    require: ed25519
+    rate_limit:
+      requests: 1000
+      window_ms: 60000    # 60 seconds
+
+  # -- Health check ----------------------------------------------------
+  # Completely open — no signature needed. Suitable for load-balancer
+  # probes, uptime monitors, and Kubernetes liveness/readiness checks.
+  - path: /health
+    require: none
+
+  # -- Public read-only endpoints --------------------------------------
+  # No signature required; these routes serve unauthenticated traffic
+  # (documentation, status pages, marketing content, etc.).
+  - path: /public/**
+    require: none

package/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to `@7h3/protocol` are documented here.  
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).  
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.2] — 2026-06-05
+
+### Added
+- `SECURITY.md` — coordinated vulnerability disclosure process, 48h acknowledgement / 14-day critical patch SLA, Hall of Thanks
+- `CONTRIBUTING.md` — test commands, wire-freeze policy, conformance fixture update requirement, PR workflow
+- `GOVERNANCE.md` — LF Minimum Viable Governance style: single-maintainer stage, decision process, co-maintainership path
+- `.github/dependabot.yml` — weekly npm and GitHub Actions dependency updates; non-security updates grouped to reduce noise
+- `.github/workflows/scorecard.yml` — OpenSSF Scorecard workflow (activates when Actions billing is restored)
+- `.github/workflows/publish.yml` — provenance-enabled npm publish workflow for both `@7h3/protocol` and `@7h3/protocol-mcp` (activates when Actions billing is restored)
+- `src/protocolFuzz.advanced.test.ts` — 8 property-based fuzz tests via fast-check: wire decoder resilience (never throws on arbitrary input), canonicalization determinism (field-order invariant), replay cache uniqueness properties
+
+### Changed
+- README: added Ed25519 production recommendation with code snippet; added Security section linking to SECURITY.md
+- `docs/MCP_WRAPPER.md`: added HMAC vs Ed25519 comparison table and Ed25519 `wrapMcpServer` example
+- `mcp-server`: updated `aip_wrap_mcp_server` tool description to guide toward Ed25519 for production; HMAC boilerplate now includes a production upgrade comment
+
+### Fixed
+- README: corrected overstated fuzz status (now accurately notes property-based tests exist; formal fuzzing campaign still not done)
+
+---
+
+## [0.1.1] — 2026-06-05
+
+### Fixed
+- Published package was missing 21 individual `.d.ts` module files — only `index.d.ts` was included, causing TS2305 errors in any consumer using NodeNext or bundler moduleResolution. All 22 declaration files now ship with the package.
+- `scripts/prepare-aip-package.ts`: copy all `.d.ts` files from `dist/aip/` instead of only `index.d.ts`
+
+### Added
+- `@7h3/protocol-mcp@0.1.0` — MCP server installable into Claude Code (`claude mcp add aip -- npx @7h3/protocol-mcp`). Five tools: `aip_generate_secret`, `aip_generate_keypair`, `aip_wrap_mcp_server`, `aip_sign`, `aip_verify`
+
+---
+
+## [0.1.0] — 2026-06-01
+
+### Added
+
+**Core protocol (`aip/0.1`)**
+- `createEnvelope` / `signEnvelopeHmac` / `signEnvelopeEd25519` — envelope construction and signing over a deterministic canonical form (fixed key order).
+- `verifyEnvelopeHmac` / `verifyEnvelopeEd25519` — tamper-evident verification via real WebCrypto (no hand-rolled crypto).
+- `validateEnvelope` — structural + TTL + clock-skew validation with typed diagnostics.
+- `receiveEnvelope` — full receive pipeline: validate → verify → replay-check, composable via `ReceiveEnvelopeOptions`.
+- Wire formats: `json`, `compact` (minified), `binary` (MessagePack); encode/decode via `encodeEnvelope` / `decodeEnvelope`.
+- Polyglot parity: shared conformance fixture set (`conformance/aip_v0_1.json`) proves byte-identical signatures across TypeScript, Python (`aip7h3`), and Rust (`aip7h3`).
+
+**Replay protection**
+- `InMemoryReplayCache` — single-process `(sender, messageId, nonce)` uniqueness window with TTL.
+- `DistributedReplayCache` — wraps any `DistributedReplayStore`; routes batch ops through `reserveMany` when available.
+- `createRedisReplayStore` — atomic `SET NX PX` reserve over a client-agnostic `RedisLikeClient` interface; batch pipeline via `reserveMany`; `errorBehavior: 'fallback' | 'reject' | 'allow'` with graceful degradation to local store and `onDegraded` hook.
+- `InMemoryRedisLikeClient` — reference implementation for tests (no Redis dep required).
+
+**Fleet-wide key revocation**
+- `InMemoryRevocationStore` — single-process; supports time-bounded `untilMs`.
+- `createRedisRevocationStore` — cached reads (`cacheTtlMs` default 5 s), **fail-closed default** (`errorBehavior: 'reject'`), serves stale cache during Redis outage.
+- `withRevocationCheck` — wraps any `SignatureResolver`; revoked key returns `undefined` → verification fails.
+
+**MCP hardening wrapper**
+- `wrapMcpServer` — sign + replay-protect an existing MCP handler with zero handler changes; enforces recipient binding (cross-server relay defense).
+- `wrapMcpClient` / `createMcpClientCodec` — sign outbound requests; enforce sender binding (response-spoof defense) and correlation binding (response-substitution defense); replay protection on by default.
+- Demo: `npm run aip:mcp:wrap` — proves tampered and replayed requests rejected.
+
+**Transport adapters**
+- `serveMcpOverStdio` / `createStdioMcpClient` — newline-delimited; in-order sequential chain prevents response interleaving.
+- `createHttpMcpHandler` / `createHttpMcpClient` — `node:http` handler + `fetch` client; supports `binary` wire format.
+- No new runtime dependencies (uses `node:readline`, `node:http`, `node:stream`, global `fetch`).
+
+**Key management & policy**
+- Key rotation support (`keyRotation`), runtime policy (`runtimePolicy`, `policyEnforcer`), telemetry feedback hooks.
+- Framework adapters (`frameworkAdapters`), agent adapter (`agentAdapter`), MCP gateway (`mcpGateway`).
+
+### Documentation
+- `docs/THREAT_MODEL.md` — full threat coverage matrix.
+- `docs/DISTRIBUTED_REPLAY.md` — Redis store setup, `errorBehavior` table, operational guidance.
+- `docs/KEY_REVOCATION.md` — revocation store setup, cache TTL tuning.
+- `docs/MCP_WRAPPER.md` — threat coverage table, server + client usage, transport examples.
+
+### Test coverage
+- 123 tests / 22 test files — all green.
+- Live-Redis integration test (`redisIntegration.test.ts`) — auto-skips if no server present.
+- Python conformance: `conformance:python`.
+- Rust: `conformance:rust` (7 tests).
+
+---
+
+[0.1.0]: https://github.com/IceMasterT/7h3-protocol-aip/releases/tag/v0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to @7h3/protocol
+
+Thanks for your interest. This document covers how to run tests, submit changes,
+and understand what is and is not open for modification.
+
+## Prerequisites
+
+- Node.js 20+
+- Python 3.10+ (for Python conformance tests)
+- Rust stable toolchain (for Rust conformance tests)
+
+Install Node dependencies:
+
+```bash
+npm install
+```
+
+## Running Tests
+
+**TypeScript unit and integration tests:**
+
+```bash
+npm test
+```
+
+**Cross-runtime conformance tests:**
+
+```bash
+npm run conformance:python   # runs sdk/python/tests via unittest
+npm run conformance:rust     # runs cargo test in sdk/rust/
+```
+
+All three test suites must pass before a PR is mergeable.
+
+## The Wire Version is Frozen
+
+`aip/0.1` is the current wire version, and **it is frozen**. This means:
+
+- The envelope schema (field names, types, required fields) cannot change
+- The canonicalization algorithm cannot change
+- The intent vocabulary (`tool_call`, `tool_result`, `message`, `error`) cannot change
+
+Any change to these would silently break cross-runtime interoperability and
+require a new wire version designation. If you believe a wire-level change is
+necessary, open an issue first to discuss versioning strategy before writing code.
+
+The TypeScript API (types, builder functions, SDK surface) is pre-1.0 and may
+evolve on minor version bumps. Deprecation notices will be included in the
+changelog when possible.
+
+## Conformance Fixtures
+
+The canonical fixture set lives at `conformance/aip_v0_1.json`. If your PR adds
+or changes any signing behavior, canonicalization detail, or replay-safety logic,
+you must update this fixture file with vectors that cover the new behavior.
+
+Fixtures are the source of truth for cross-runtime verification. A PR that
+changes signing logic without updating fixtures will be rejected.
+
+## Submitting a Pull Request
+
+1. Fork the repo and create a branch with a descriptive name
+   (`fix/nonce-validation`, `feat/ed448-profile`, etc.)
+2. Make your changes and ensure all three test suites pass
+3. Update `conformance/aip_v0_1.json` if signing behavior changed
+4. Open a PR against `main` with a clear description of:
+   - What the change does
+   - Why it is needed
+   - Any trade-offs or alternatives you considered
+5. Reference any related issues in the PR description
+
+Keep PRs focused. A single PR that mixes unrelated changes is harder to review
+and slower to land.
+
+## Security Findings
+
+Do not open GitHub Issues for security vulnerabilities. Follow the process in
+[SECURITY.md](SECURITY.md) instead.
+
+---
+
+Maintainer: [@IceMasterT](https://github.com/IceMasterT)

package/Dockerfile

@@ -0,0 +1,73 @@
+# ---------------------------------------------------------------------------
+# Stage 1 — builder
+# Install all dependencies (including devDeps for the build step) and
+# compile TypeScript sources.  The compiled output ends up in /app/dist.
+# ---------------------------------------------------------------------------
+FROM node:22-alpine AS builder
+
+WORKDIR /app
+
+# Copy manifests first so Docker can cache the install layer separately
+# from source changes.
+COPY package.json package-lock.json ./
+
+# Install all deps (dev + prod) needed to build
+RUN npm ci --prefer-offline
+
+# Copy the full source tree
+COPY src/ src/
+COPY bin/ bin/
+COPY tsconfig.json tsconfig.lib.json ./
+COPY vite.lib.config.ts ./
+
+# Run the build script if it exists; swallow the error gracefully so that
+# repositories that haven't wired up the build step yet still produce a
+# working image.  The runtime stage uses tsx to execute TypeScript directly,
+# so a missing dist/ is not fatal.
+RUN npm run build:protocol 2>/dev/null || true
+
+# ---------------------------------------------------------------------------
+# Stage 2 — runtime
+# Lean image with only production dependencies.
+# tsx executes TypeScript directly, so we don't strictly need dist/; the
+# builder stage is kept separate to avoid polluting the final image with
+# devDependencies and intermediate build artefacts.
+# ---------------------------------------------------------------------------
+FROM node:22-alpine
+
+# Install tsx globally so the ENTRYPOINT can invoke TypeScript files.
+# Pinning via the package.json range is intentional — renovate will keep
+# this in sync with the devDependency version.
+RUN npm install -g tsx
+
+WORKDIR /app
+
+# Copy manifests for production install
+COPY package.json package-lock.json ./
+
+# Production-only install; omits devDependencies such as vitest and vite
+RUN npm ci --omit=dev --prefer-offline
+
+# Copy the source files required at runtime
+COPY src/ src/
+COPY bin/ bin/
+
+# Copy compiled output from the builder stage (used when tsx is not
+# available or when --no-tsx mode is added in future).
+COPY --from=builder /app/dist/ dist/
+
+# The gateway listens on this port by default.
+EXPOSE 8080
+
+# Lightweight health check: wget is present on node:alpine; curl is not.
+# This probe hits the /health route which, per the example config, is
+# policy-exempt (require: none) and will pass through to the upstream.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget -qO- http://localhost:8080/health || exit 1
+
+# Run the gateway sub-command of the 7h3 CLI.
+ENTRYPOINT ["tsx", "bin/7h3.ts", "gateway"]
+
+# Default arguments — overridden at runtime via docker-compose environment
+# variables or explicit docker run arguments.
+CMD ["--port", "8080", "--upstream", "http://upstream:3000", "--require", "ed25519"]

package/GOVERNANCE.md

@@ -0,0 +1,62 @@
+# Governance
+
+## Current Stage
+
+This project is in single-maintainer, pre-community stage. There is one
+maintainer ([@IceMasterT](https://github.com/IceMasterT)), no formal governance
+board, and no steering committee. That is appropriate for the project's current
+size and maturity, and it is stated clearly here so contributors know what to
+expect.
+
+## Decision Making
+
+The maintainer makes all final decisions about direction, API shape, release
+timing, and whether to accept a contribution.
+
+For significant changes -- anything that touches the wire format, the
+conformance fixture set, or the project's positioning relative to MCP/A2A --
+the maintainer will open a GitHub Issue before deciding, to give the community
+a window to raise concerns or provide context. That window will be at least
+seven days for non-urgent changes.
+
+Day-to-day decisions (bug fixes, documentation, minor SDK improvements) do not
+require community input first.
+
+## Versioning Policy
+
+The wire version `aip/0.1` is frozen. Interoperating implementations can rely
+on it not changing. A new wire version designation (e.g. `aip/0.2`) would be
+introduced in a new package major version and coexist with `aip/0.1` for a
+migration period.
+
+The TypeScript API is pre-1.0. Minor version bumps may include breaking API
+changes. Breaking changes will be documented in the changelog with migration
+notes. The `1.0.0` release will signal API stability.
+
+The Python and Rust SDKs track the TypeScript wire behavior. Their own version
+numbers are independent of the npm package version.
+
+## Path to Co-Maintainership
+
+There is no automatic path to co-maintainership based on contribution count.
+The relevant factors are:
+
+- Sustained engagement over multiple months
+- Demonstrated familiarity with the threat model (replay attacks, malleability,
+  cross-runtime canonicalization edge cases)
+- Good judgment in the review of other contributors' PRs
+- Willingness to own the security disclosure process
+
+If you are interested, open a conversation in Discussions rather than raising
+it in a PR.
+
+## Standards Body Adoption
+
+If this project is accepted into a standards body or foundation, this governance
+document will be replaced by whatever governance model that body requires.
+Community input will be sought before any such transition.
+
+---
+
+Last reviewed: 2026-06-05  
+Maintainer: [@IceMasterT](https://github.com/IceMasterT) / tech@mysms.promo