protect-mcp 0.6.3 → 0.7.1

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+## 0.7.1: documentation and security policy
+
+No code change from 0.7.0. Rewrote the README to lead with the fail-closed and
+self-test guarantees, and added a `SECURITY.md` disclosure policy (supported
+versions, the affected 0.5.x/0.6.x range, the published advisory, and the
+coordinated-disclosure process). The package now ships `SECURITY.md`.
+
+## 0.7.0 (security release): the gate now fails closed and actually evaluates
+
+This release fixes the way the Cedar policy gate behaves when anything goes
+wrong, and a separate defect that meant Cedar policies were not being evaluated
+at all against the pinned engine. If you rely on protect-mcp to enforce a Cedar
+policy, upgrade.
+
+### Security
+
+- **Fail closed, not open.** Before 0.7.0, if the Cedar engine was unavailable,
+  the result was malformed, evaluation threw, or a policy errored, the evaluator
+  returned ALLOW. A security gate must do the opposite. Every error and
+  uncertainty path now DENIES. The allow-on-error behavior is reachable only by
+  explicitly passing `{ failClosed: false }` (observe mode), and even then the
+  decision is flagged `would_deny: true` so a failure is never silent.
+- **An errored policy can no longer permit-all.** Cedar silently discards a
+  policy that errors at evaluation (for example the `context.<string> in [list]`
+  type error in the 0.5.x and 0.6.x advisory), which could leave a residual
+  permit standing. The evaluator now treats any per-policy error as an
+  evaluation error and denies under enforcement.
+- **Cedar policies are actually evaluated now.** The `isAuthorized` call passed
+  the policy text as a bare string, but `@cedar-policy/cedar-wasm@4.x` requires a
+  structured `PolicySet`. As a result every Cedar evaluation errored against the
+  pinned engine and (with the old fail-open default) allowed everything. The call
+  shape and the response parser are corrected, so a `forbid` rule actually denies
+  and a `permit` actually allows.
+
+### Added
+
+- **`protect-mcp evaluate`** and **`protect-mcp sign`**: one-shot per-call verbs
+  for PreToolUse and PostToolUse hooks. `evaluate` loads a Cedar policy, evaluates
+  one tool call fail-closed, and exits 2 on deny (so the tool is blocked) and 0 on
+  allow; a missing or unloadable policy denies unless `--fail-on-missing-policy
+  false` is set. This makes hook configs that invoke these verbs work as written.
+- **`runEvaluatorSelfTest()`** plus a startup gate: `serve --enforce` runs the
+  self-test before arming and refuses to start if the engine cannot prove it
+  denies a known-forbidden vector. `protect-mcp doctor` reports the same, so the
+  gate verifies its own restraint before it is trusted.
+- A CI tripwire test that fails the build if the discarded `in`-on-String pattern
+  is ever reintroduced into a shipped policy.
+
+### Affected versions
+
+The fail-open behavior and the unevaluated-Cedar defect are present in the
+0.5.x and 0.6.x lines. Upgrade to 0.7.0.

package/README.md

@@ -1,240 +1,122 @@
 # protect-mcp
 
-[![npm version](https://img.shields.io/npm/v/protect-mcp)](https://www.npmjs.com/package/protect-mcp)
-[![Downloads](https://img.shields.io/npm/dm/protect-mcp)](https://www.npmjs.com/package/protect-mcp)
-[![Claude Code Marketplace](https://img.shields.io/badge/Claude%20Code-marketplace-d97757?logo=anthropic&logoColor=white)](https://github.com/wshobson/agents/tree/main/plugins/protect-mcp)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
-
-> A policy check that sits between your AI agent and the tools it calls.
-> Every tool call is evaluated against a rule you wrote. Every decision is signed.
-
-> **Receipt format:** `protect-mcp` emits Veritas Acta receipts. Legacy
-> ScopeBlind receipts remain verifiable, but Acta v0.1 is the canonical
-> format going forward. Spec: [`@veritasacta/protocol`](https://www.npmjs.com/package/@veritasacta/protocol)
-> · IETF: [draft-farley-acta-signed-receipts](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/).
-
-## What it does, in plain English
-
-When an AI agent (Claude Code, Cursor, a custom LangChain app, anything that
-uses the Model Context Protocol) wants to run a command, edit a file, or call
-an API, `protect-mcp` intercepts that request before it executes:
-
-1. **Checks a policy.** You write rules in [Cedar](https://www.cedarpolicy.com/)
-   — the same policy language AWS uses for IAM. Rules like *"never allow
-   `rm -rf /`"*, *"only allow `Bash` during working hours"*, or *"require
-   human approval for anything touching production."*
-2. **Returns a decision.** `allow`, `deny`, or `request_approval`. The agent
-   framework respects the decision — if it's `deny`, the tool call doesn't run.
-3. **Signs a receipt.** An Ed25519-signed, hash-chained record of the decision,
-   written to `.receipts/`. Verifiable offline by anyone with the public key.
-   When your auditor asks *"what did that agent do on 2026-03-14?"* you have
-   cryptographic proof — not a log file you might have tampered with.
-
-You install it once. Your agent keeps working the same way. The difference:
-every action it takes is now policy-checked and audit-evidenced.
-
-## Who this is for
-
-- **Developers using Claude Code / Cursor / Cline** who want *"don't let the
-  agent delete my repo"* enforced rather than hoped for.
-- **Security teams** shipping agents to engineering who need a portable
-  policy layer that travels across frameworks.
-- **Compliance teams** who need tamper-evident evidence of what agents did,
-  verifiable without trusting the vendor.
-
-## How it relates to `sb-runtime`
-
-`protect-mcp` is a **library** — it sits inside your agent framework and
-gates tool calls cooperatively. Right tool when you own the agent's code and
-trust its framework to honour decisions.
-
-[`sb-runtime`](https://github.com/ScopeBlind/sb-runtime) is the companion
-**binary** that wraps the whole agent *process* in an OS-level sandbox
-(Landlock + seccomp on Linux). It enforces decisions at the kernel layer —
-the agent can't ignore them even if it tried. Use `sb-runtime` when you're
-running an agent you didn't write, or when you want belt-and-braces defence
-in depth:
-
-```
-┌─────────────────────────────────────────────────┐
-│  sb-runtime   ← OS refuses forbidden syscalls   │
-│  ┌───────────────────────────────────────────┐  │
-│  │  agent process (Claude Code, Python, …)   │  │
-│  │  ┌─────────────────────────────────────┐  │  │
-│  │  │  protect-mcp                        │  │  │
-│  │  │    ← Cedar decides per tool call,   │  │  │
-│  │  │      receipts every decision        │  │  │
-│  │  └─────────────────────────────────────┘  │  │
-│  └───────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────┘
-```
-
-**One-liner:** `protect-mcp` is the policy hook inside your agent.
-`sb-runtime` is the OS sandbox around it. You want both.
-
----
-
-## Quick Start — Claude Code
-
-Two commands. Every tool call is receipted.
+Fail-closed Cedar policy gate plus signed receipts for AI agent tool calls.
 
-```bash
-# 1. Generate hooks, keys, Cedar policy, and /verify-receipt skill
-npx protect-mcp init-hooks
-
-# 2. Start the hook server
-npx protect-mcp serve
-```
-
-Open Claude Code in the same project. Every tool call is now intercepted, evaluated, and signed.
-
-To also connect to the ScopeBlind dashboard in one step:
-
-```bash
-npx protect-mcp quickstart --connect
-```
-
-Creates a free ScopeBlind dashboard and configures receipt upload automatically. No signup required. Free up to 20,000 receipts/month.
-
-### What `init-hooks` creates
-
-| File | Purpose |
-|------|---------|
-| `.claude/settings.json` | Hook config (PreToolUse, PostToolUse, + 9 lifecycle events) |
-| `keys/gateway.json` | Ed25519 signing keypair (auto-gitignored) |
-| `policies/agent.cedar` | Starter Cedar policy — customize to your needs |
-| `protect-mcp.json` | JSON policy with signing + rate limits |
-| `.claude/skills/verify-receipt/SKILL.md` | `/verify-receipt` skill for Claude Code |
-
-### Architecture
-
-```
-Claude Code  →  POST /hook  →  protect-mcp (Cedar + sign)  →  response
-                                    ↓
-                            .protect-mcp-log.jsonl
-                            .protect-mcp-receipts.jsonl
-```
-
-- **PreToolUse**: synchronous Cedar policy check → deny blocks the tool
-- **PostToolUse**: async receipt signing → zero latency impact
-- **deny is architecturally final** — it cannot be overridden by the model or other hooks
-
-### Endpoints
-
-| Method | Path | Description |
-|--------|------|-------------|
-| POST   | `/hook` | Claude Code hook endpoint |
-| GET    | `/health` | Server status, policy info, signer info |
-| GET    | `/receipts` | Recent signed receipts |
-| GET    | `/receipts/latest` | Most recent receipt |
-| GET    | `/suggestions` | Auto-generated Cedar policy fix suggestions |
-| GET    | `/alerts` | Config tamper detection alerts |
-
-### Verify receipts
+[![npm version](https://img.shields.io/npm/v/protect-mcp)](https://www.npmjs.com/package/protect-mcp)
+[![downloads](https://img.shields.io/npm/dm/protect-mcp)](https://www.npmjs.com/package/protect-mcp)
+[![license](https://img.shields.io/npm/l/protect-mcp)](https://www.npmjs.com/package/protect-mcp)
+[![node](https://img.shields.io/node/v/protect-mcp)](https://www.npmjs.com/package/protect-mcp)
+
+`protect-mcp` is a gate that sits in front of an AI agent's tool calls. It evaluates
+each call against a [Cedar](https://www.cedarpolicy.com/) policy (the same language
+AWS uses for IAM), blocks what breaks the rules before it runs, and signs an
+offline-verifiable Ed25519 receipt of every decision. It runs locally, sends no
+telemetry of your decisions anywhere, and is MIT licensed.
+
+## Why it is different
+
+- **Fail-closed by default.** On any policy error, a missing engine, or an
+  evaluation failure, the decision is DENY. The gate never silently allows. An
+  observe mode exists for shadow rollout, but even there a call that would be
+  blocked is flagged `would_deny: true`, so a failure is never silent.
+- **It proves its own restraint.** `serve --enforce` and `doctor` run a startup
+  self-test and refuse to arm the gate unless they can show that a known-forbidden
+  action is actually denied. A gate that cannot prove it denies does not start.
+- **Every decision is a receipt anyone can verify.** Decisions are Ed25519-signed
+  and verifiable offline with [`@veritasacta/verify`](https://www.npmjs.com/package/@veritasacta/verify).
+  No vendor trust required: the math does not care who runs it.
+
+## Quickstart (30 seconds)
 
 ```bash
-# Inside Claude Code:
-/verify-receipt
-
-# From terminal:
-curl http://127.0.0.1:9377/receipts/latest | jq .
-npx protect-mcp receipts
+# 1. Generate an Ed25519 keypair, a config template, and a sample policy.
+npx protect-mcp init
 
-# Check policy suggestions:
-curl http://127.0.0.1:9377/suggestions | jq .
+# 2. Put a Cedar policy in ./cedar (see "Write a policy" below), then serve
+#    the Claude Code hook gate in enforce mode. It runs a restraint self-test
+#    first and refuses to start if it cannot prove it denies a forbidden vector.
+npx protect-mcp serve --enforce --cedar ./cedar
 ```
 
-## Quick Start — MCP Server Wrapper
-
-Wrap any stdio MCP server as a transparent proxy:
+One-shot evaluation, the way a PreToolUse hook calls it. Exit code 2 means deny
+(the tool is blocked); exit 0 means allow:
 
 ```bash
-# Shadow mode — log every tool call, enforce nothing
-npx protect-mcp -- node my-server.js
+npx protect-mcp evaluate --cedar ./cedar --tool Bash --input '{"command":"rm"}'
+echo $?   # 2  -> denied, fail-closed
 
-# Enforce mode with policy
-npx protect-mcp --policy protect-mcp.json --enforce -- node my-server.js
-
-# Generate keys + config template
-npx protect-mcp init
+npx protect-mcp evaluate --cedar ./cedar --tool Read --input '{"path":"README.md"}'
+echo $?   # 0  -> allowed
 ```
 
-## How It Works
-
-protect-mcp evaluates every tool call against a policy (JSON, Cedar, or external PDP), signs the decision as an Ed25519 receipt, and logs the result.
-
-**Two integration modes:**
-
-| Mode | Transport | Use Case |
-|------|-----------|----------|
-| Hook Server | HTTP (`npx protect-mcp serve`) | Claude Code, agent swarms |
-| Stdio Proxy | stdin/stdout (`npx protect-mcp -- ...`) | Claude Desktop, Cursor, any MCP client |
+A missing or unloadable policy denies (exit 2) unless you explicitly pass
+`--fail-on-missing-policy false`.
 
-**Three policy engines:**
+## Claude Code hooks
 
-| Engine | Config | Notes |
-|--------|--------|-------|
-| JSON | `--policy policy.json` | Simple per-tool rules |
-| Cedar | `--cedar ./policies/` | Local WASM evaluation via `@cedar-policy/cedar-wasm` |
-| External PDP | `policy_engine: "external"` | OPA, Cerbos, or any HTTP PDP |
-
-## Swarm Tracking
-
-In multi-agent sessions, protect-mcp automatically tracks the swarm topology.
-
-**11 hook events handled:**
-
-| Event | Type | Description |
-|-------|------|-------------|
-| `PreToolUse` | Sync | Cedar/policy evaluation before tool execution |
-| `PostToolUse` | Async | Receipt signing after tool execution |
-| `SubagentStart` / `SubagentStop` | Lifecycle | Worker agent spawn/completion |
-| `TaskCreated` / `TaskCompleted` | Lifecycle | Coordinator task assignment |
-| `SessionStart` / `SessionEnd` | Lifecycle | Session lifecycle with sandbox detection |
-| `TeammateIdle` | Lifecycle | Agent utilization monitoring |
-| `ConfigChange` | Security | Tamper detection for `.claude/settings.json` |
-| `Stop` | Lifecycle | Finalization + policy suggestion summary |
-
-Each receipt includes:
-- `swarm.agent_id`, `swarm.agent_type`, `swarm.team_name`
-- `timing.tool_duration_ms`, `timing.hook_latency_ms`
-- `payload_digest` (SHA-256 hash for payloads >1KB)
-- `deny_iteration` (retry count after denial)
-- `sandbox_state` (enabled/disabled/unavailable)
-- OpenTelemetry `otel_trace_id` and `otel_span_id`
-
-## Policy File
+`protect-mcp init-hooks` writes a `.claude/settings.json` for you. To wire the
+gate by hand, the two verbs you need are `evaluate` (PreToolUse, blocks on exit 2)
+and `sign` (PostToolUse, records a receipt). Pin the version so a Claude Code
+session always runs the gate you tested:
 
 ```json
 {
-  "default_tier": "unknown",
-  "tools": {
-    "dangerous_tool": { "block": true },
-    "admin_tool": { "min_tier": "signed-known", "rate_limit": "5/hour" },
-    "read_tool": { "require": "any", "rate_limit": "100/hour" },
-    "*": { "rate_limit": "500/hour" }
-  },
-  "signing": {
-    "key_path": "./keys/gateway.json",
-    "issuer": "protect-mcp",
-    "enabled": true
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx protect-mcp@0.7.0 evaluate --cedar ./cedar --tool \"$TOOL_NAME\" --input \"$TOOL_INPUT\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx protect-mcp@0.7.0 sign --tool \"$TOOL_NAME\" --receipts ./receipts --key ./keys/gateway.json"
+          }
+        ]
+      }
+    ]
   }
 }
 ```
 
-### Cedar Policies
+`evaluate` exits 2 on deny so Claude Code blocks the tool call, and 0 on allow.
+`sign` is best-effort: it appends an Ed25519-signed receipt when a key is
+configured, and if no signer is available it records an honest unsigned line
+(`"signed": false`) rather than failing the tool.
+
+## Write a policy
 
-Cedar deny decisions are **authoritative** — they cannot be overridden.
+Cedar policies live in a directory you point at with `--cedar`. A `forbid` rule
+denies, a `permit` rule allows. To match against a value in the tool input, use
+the `.contains()` idiom:
 
 ```cedar
-// Allow read-only tools
+// Allow read-only tools.
 permit(
   principal,
   action == Action::"MCP::Tool::call",
   resource == Tool::"Read"
 );
 
-// Block destructive tools
+// Deny dangerous shell commands by matching the command against a list.
+forbid(
+  principal,
+  action == Action::"MCP::Tool::call",
+  resource == Tool::"Bash"
+) when {
+  ["rm", "dd", "mkfs"].contains(context.command)
+};
+
+// Block destructive tools outright.
 forbid(
   principal,
   action == Action::"MCP::Tool::call",
@@ -242,228 +124,67 @@ forbid(
 );
 ```
 
-When a tool is denied, protect-mcp auto-suggests the minimal Cedar `permit()` rule via `GET /suggestions`.
-
-## CVE-Anchored Policy Packs
-
-Each prevents a real attack:
-
-| Policy | Incident | OWASP |
-|--------|----------|-------|
-| `clinejection.json` | CVE-2025-6514: MCP OAuth proxy hijack (437K environments) | A01, A03 |
-| `terraform-destroy.json` | Autonomous Terraform agent destroys production | A05, A06 |
-| `github-mcp-hijack.json` | Prompt injection via crafted GitHub issue | A01, A02, A03 |
-| `data-exfiltration.json` | Agent data theft via outbound tool abuse | A02, A04 |
-| `financial-safe.json` | Unauthorized financial transaction | A05, A06 |
-
-Cedar equivalents available in `policies/cedar/`.
-
-## MCP Client Configuration
-
-### Claude Desktop
-
-```json
-{
-  "mcpServers": {
-    "my-protected-server": {
-      "command": "npx",
-      "args": [
-        "-y", "protect-mcp",
-        "--policy", "/path/to/protect-mcp.json",
-        "--enforce",
-        "--", "node", "my-server.js"
-      ]
-    }
-  }
-}
-```
-
-### Cursor / VS Code
-
-Same pattern — replace the server command with `protect-mcp` wrapping it.
+> **Hazard:** do NOT write `context.command in ["rm", "dd"]` to match a string
+> against a list. `in` is for entity hierarchies, not string membership. Cedar
+> treats the expression as a type error and silently discards the whole `forbid`
+> rule, which (under a fail-open gate) leaves a residual `permit` standing. This
+> is the exact defect behind the advisory below. Use `[...].contains(context.command)`
+> instead. From 0.7.0 the gate denies on that error rather than permitting, and a
+> CI tripwire test fails the build if the pattern is reintroduced into a shipped
+> policy. See [GHSA-hm46-7j72-rpv9](https://github.com/ScopeBlind/scopeblind-gateway/security/advisories/GHSA-hm46-7j72-rpv9).
 
-## CLI Commands
+Ready-to-use Cedar packs ship in `policies/cedar/` (Clinejection / CVE-2025-6514,
+Terraform destroy, secret-file exfiltration, spending authority).
 
-```
-Commands:
-  serve             Start HTTP hook server for Claude Code (port 9377)
-  init-hooks        Generate Claude Code hook config + skill + sample Cedar policy
-  quickstart        Zero-config onboarding: init + demo + show receipts
-  connect           Link to ScopeBlind dashboard (creates sandbox if needed)
-  init              Generate Ed25519 keypair + config template
-  demo              Start a demo server wrapped with protect-mcp
-  doctor            Check your setup: keys, policies, verifier, connectivity
-  trace <id>        Visualize the receipt DAG from a given receipt_id
-  status            Show tool call statistics from the decision log
-  digest            Generate a human-readable summary of agent activity
-  receipts          Show recent persisted signed receipts
-  bundle            Export an offline-verifiable audit bundle
-  simulate          Dry-run a policy against recorded tool calls
-  report            Generate a compliance report from an audit bundle
-
-Options:
-  --policy <path>   Policy/config JSON file
-  --cedar <dir>     Cedar policy directory
-  --enforce         Enable enforcement mode (default: shadow)
-  --port <port>     HTTP server port (default: 9377 for serve)
-  --verbose         Enable debug logging
-```
+## Verify a receipt
 
-## Decision Logs
-
-Every tool call emits structured JSON to `stderr`:
-
-```json
-[PROTECT_MCP] {"v":2,"tool":"read_file","decision":"allow","reason_code":"cedar_allow","policy_digest":"a1b2c3...","mode":"enforce","hook_event":"PreToolUse","timing":{"hook_latency_ms":1},"otel_trace_id":"..."}
-```
-
-When signing is configured, a signed receipt is persisted to `.protect-mcp-receipts.jsonl`.
-
-## Audit Bundles
+Receipts are signed and verifiable offline by anyone with the public key. No
+network, no vendor, no trust in ScopeBlind:
 
 ```bash
-npx protect-mcp bundle --output audit.json
+npx @veritasacta/verify ./receipts/receipts.jsonl --format jsonl
+# Exit 0 = valid, non-zero = tampered or malformed
 ```
 
-Self-contained offline-verifiable bundle with receipts + signing keys. Verify with `npx @veritasacta/verify`.
+`npx protect-mcp bundle --output audit.json` exports a self-contained,
+offline-verifiable audit bundle of your receipts plus the public signing key.
 
-## Dashboard
+## Security
 
-protect-mcp works fully offline. Optionally connect to the ScopeBlind dashboard for:
+`protect-mcp` 0.7.0 fails closed by design. On any policy-evaluation error, a
+missing engine, or a policy that errored at evaluation, the decision is DENY,
+not allow. `serve --enforce` and `doctor` run a boot self-test that proves the
+gate denies a known-forbidden vector before it is trusted, and refuse to arm if
+it cannot.
 
-- Real-time receipt visualization
-- Abuse alerts and anomaly detection
-- Compliance export and audit bundles
-- Usage analytics
+**Affected versions: 0.5.x and 0.6.x.** Those lines fail open (they return ALLOW
+on evaluation error) and do not evaluate Cedar correctly against the pinned
+engine, so a `forbid` rule could fail to block. **Upgrade to >= 0.7.0.**
 
-Free tier: 20,000 receipts/month. No credit card required.
+Details and remediation: [GHSA-hm46-7j72-rpv9](https://github.com/ScopeBlind/scopeblind-gateway/security/advisories/GHSA-hm46-7j72-rpv9).
+To report a vulnerability, see [SECURITY.md](./SECURITY.md).
 
-[scopeblind.com/pricing](https://scopeblind.com/pricing)
+## Commands
 
-### ScopeBlind tenant integration (Founding Plan)
+| Command | Description |
+|---------|-------------|
+| `serve` | Start the HTTP hook server for Claude Code (port 9377). `--enforce` runs the restraint self-test first; `--cedar <dir>` and `--policy <path>` select the policy. |
+| `init` | Generate an Ed25519 keypair (`keys/gateway.json`), a config template, and a sample policy. |
+| `evaluate` | Evaluate one tool call against a Cedar policy (PreToolUse gate). Exit 2 = deny (fail-closed), exit 0 = allow. |
+| `sign` | Sign one tool call into a receipt (PostToolUse). Best-effort: records an honest unsigned line if no key. |
+| `simulate` | Dry-run a policy against a recorded decision log to see what it would have blocked. |
+| `demo` | Start a built-in demo server wrapped with the gate, to see receipts instantly. |
+| `doctor` | Check your setup (keys, policies, Cedar engine, verifier) and run the restraint self-test. |
+| `bundle` | Export an offline-verifiable audit bundle of receipts plus the public key. |
+| `report` | Generate a compliance report (Markdown or JSON) from the decision log and receipts. |
 
-If you have a ScopeBlind Founding Plan tenant, set your `SCOPEBLIND_TOKEN`
-(from the welcome email) in the environment and protect-mcp forwards every
-signed receipt to your dashboard at `https://scopeblind.com/console/<your-slug>`.
-
-```bash
-# Your protect-mcp install with cloud-synced receipts
-SCOPEBLIND_TOKEN=scp_... \
-  npx protect-mcp init-hooks
-```
-
-How it works:
-
-1. On first receipt, the bridge exchanges your token for a short-lived BRASS-v2
-   auth proof at `/fn/brass/issue` (ECDSA P-256 signed, hourly expiry).
-2. Receipts are batched and POSTed to `/fn/console/<slug>/receipts` every 5
-   seconds (up to 128 per batch).
-3. The local `.receipts/` chain remains authoritative regardless of forward
-   status. Network failures are retried; quota exhaustion is reported. No
-   crash, no blocking.
-
-Quota: founding tier 10,000 receipts/day, enterprise 100,000/day. Anything
-above quota is rejected with a structured response; receipts stay safe in
-`.receipts/` until you upgrade or until tomorrow.
-
-Receipt verification by third parties:
-
-```bash
-# Anyone can verify your receipts offline using the public JWKS
-curl https://scopeblind.com/.well-known/jwks.json
-npx @veritasacta/verify .receipts/0001.json
-```
-
-Verification is independent of ScopeBlind — the math doesn't care who runs it.
-
-## Interoperability
-
-The receipt format is independently implemented and verified across multiple systems:
-
-| Evidence | Detail |
-|----------|--------|
-| **4 independent implementations** | TypeScript (protect-mcp), Python (protect-mcp-adk), Rust (Cedar WASM), APS ProxyGateway |
-| **2 IETF Internet-Drafts** | [draft-farley-acta-signed-receipts-01](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/), [draft-pidlisnyi-aps-00](https://datatracker.ietf.org/doc/draft-pidlisnyi-aps/) |
-| **8 cross-engine receipts** | [Composition test](https://github.com/ScopeBlind/examples/tree/main/interop/composition-test): 2 engines, 1 verifier, all VALID |
-| **PRs merged into microsoft/agent-governance-toolkit** | [#667](https://github.com/microsoft/agent-governance-toolkit/pull/667), [#1159](https://github.com/microsoft/agent-governance-toolkit/pull/1159), [#1168](https://github.com/microsoft/agent-governance-toolkit/pull/1168), [#1186](https://github.com/microsoft/agent-governance-toolkit/pull/1186), [#1197](https://github.com/microsoft/agent-governance-toolkit/pull/1197), [#1202](https://github.com/microsoft/agent-governance-toolkit/pull/1202), [#1203](https://github.com/microsoft/agent-governance-toolkit/pull/1203), [#1205](https://github.com/microsoft/agent-governance-toolkit/pull/1205) |
-| **1 verifier, zero dependencies** | `npx @veritasacta/verify receipt.json --key <hex>` (Apache-2.0, offline) |
-
-Verify any receipt from any implementation:
-
-```bash
-npx @veritasacta/verify receipt.json --key <public-key-hex>
-# Exit 0 = valid, 1 = tampered, 2 = malformed
-```
-
-## Standards & IP
-
-- **IETF Internet-Draft**: [draft-farley-acta-signed-receipts-01](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/)
-- **Patent Status**: 4 Australian provisional patents pending (2025-2026)
-- **Cedar WASM**: [PR #64](https://github.com/cedar-policy/cedar-for-agents/pull/64) merged + [PR #73](https://github.com/cedar-policy/cedar-for-agents/pull/73) (RequestGenerator, pending review)
-
-## What's New in v0.5.3
-
-- `quickstart --connect`: Auto-create dashboard sandbox and configure receipt upload
-- `connect` subcommand: Link an existing setup to the ScopeBlind dashboard
-- Anonymous install telemetry (opt-out: `PROTECT_MCP_TELEMETRY=off`)
-- Improved Cedar WASM detection
-
-## Cybersecurity: Vulnerability Disclosure Receipts
-
-protect-mcp provides the infrastructure for receipt-signed vulnerability disclosure workflows. When AI security agents (Claude Code Security, Mythos, or similar) discover vulnerabilities, every step of the disclosure lifecycle can produce a signed, chain-linked receipt:
-
-```
-DISCOVER → DISCLOSE → PATCH → DEPLOY
-(Each step: Ed25519-signed, chain-linked, Cedar policy-bound)
-```
-
-Cedar policies govern what the scanning agent is allowed to do:
-- **CAN**: scan code, report findings internally
-- **CANNOT**: disclose externally or deploy patches without human approval
-- **MUST**: escalate critical findings to humans
-
-See the [security vulnerability disclosure example](https://github.com/ScopeBlind/examples/tree/main/security-vulnerability-disclosure) for a complete working implementation with Cedar policies and example receipt chains.
-
-Related: [Vulnerability Disclosure Receipt Design](https://github.com/scopeblind/scopeblind-gateway/issues/2)
-
-## Examples
-
-See complete working examples at [github.com/ScopeBlind/examples](https://github.com/ScopeBlind/examples):
-- [Claude Code hooks](https://github.com/ScopeBlind/examples/tree/main/claude-code-hooks) — receipt signing for every tool call
-- [Security vulnerability disclosure](https://github.com/ScopeBlind/examples/tree/main/security-vulnerability-disclosure) — receipt-signed disclosure lifecycle with Cedar governance
-- [MCP server signing](https://github.com/ScopeBlind/examples/tree/main/mcp-server-signing) — Cedar WASM policy engine with audit bundles
-
-## ScopeBlind Dashboard
-
-protect-mcp works fully offline, forever, for free. For teams that want visibility across agents, ScopeBlind offers a hosted dashboard:
-
-```bash
-npx protect-mcp connect
-```
-
-| | Free | Pro | Enterprise |
-|---|---|---|---|
-| Receipts/month | 20,000 | Pay-as-you-go | Annual commit |
-| Price | $0 | $0.50 / 1K | $0.40 / 1K |
-| Receipt explorer | Yes | Yes | Yes |
-| Compliance reports | Yes | Yes | Yes |
-| SSO / SAML | - | - | Yes |
-| SLA | - | - | 99.9% |
-
-No signup required for free tier. No card upfront.
-
-[Dashboard](https://scopeblind.com) | [Docs](https://scopeblind.com/docs/protect-mcp) | [Pricing](https://scopeblind.com/pricing)
-
-## Telemetry
-
-protect-mcp sends a single anonymous install beacon on first run (package name, version, OS, Node version). No PII. Disable with:
-
-```bash
-PROTECT_MCP_TELEMETRY=off
-```
+Run `npx protect-mcp --help` for the full flag reference.
 
-## License
+## Links
 
-MIT — free to use, modify, distribute, and build upon without restriction.
+- Protocol (IETF): [draft-farley-acta-signed-receipts](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/)
+- [CHANGELOG](./CHANGELOG.md)
+- [npm](https://www.npmjs.com/package/protect-mcp)
+- [scopeblind.com](https://scopeblind.com)
 
-Built by [ScopeBlind](https://scopeblind.com) | [npm](https://www.npmjs.com/package/protect-mcp) | [GitHub](https://github.com/scopeblind/scopeblind-gateway) | [IETF Draft](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/)
+MIT licensed. Built by [ScopeBlind](https://scopeblind.com).