protect-mcp 0.2.0 → 0.2.2

package/README.md

@@ -1,20 +1,23 @@
 # protect-mcp
 
-Security gateway for MCP servers. Tool-level policies, trust-tier gating, credential isolation, and signed decision receipts.
+Security gateway for MCP servers. Shadow-mode logs by default, per-tool policies, optional local Ed25519 receipts, and verification-friendly audit output.
 
-**Shadow mode by default.** Wraps any MCP server as a transparent proxy. Logs every tool call. Signs every decision. Optionally enforces policies.
+**Current CLI path:** wrap any stdio MCP server as a transparent proxy. In shadow mode it logs every `tools/call` request and allows everything through. Add a policy file to enforce per-tool rules. Run `protect-mcp init` to generate local signing keys and config so the gateway can also emit signed receipts.
 
 ## Quick Start
 
 ```bash
-# Shadow mode — log and sign every tool call, enforce nothing
+# Shadow mode — log every tool call, enforce nothing
 npx protect-mcp -- node my-server.js
 
-# Initialize a new project with keys + config template
+# Generate keys + config template for local signing
 npx protect-mcp init
 
-# Enforce mode with a policy file
-npx protect-mcp --policy policy.json --enforce -- node my-server.js
+# Shadow mode with local signing enabled
+npx protect-mcp --policy protect-mcp.json -- node my-server.js
+
+# Enforce mode
+npx protect-mcp --policy protect-mcp.json --enforce -- node my-server.js
 ```
 
 ## What It Does
@@ -26,105 +29,28 @@ MCP Client ←stdin/stdout→ protect-mcp ←stdin/stdout→ your MCP server
 ```
 
 It intercepts `tools/call` JSON-RPC requests and:
-- **Shadow mode** (default): logs every tool call, signs a decision receipt, allows everything through
-- **Enforce mode**: applies policy rules — block, rate-limit, or gate by trust tier
+- **Shadow mode** (default): logs every tool call and allows everything through
+- **Enforce mode**: applies per-tool policy rules such as `block`, `rate_limit`, and `min_tier`
+- **Optional local signing**: when signing is configured, emits an Ed25519-signed receipt alongside the structured log
 
 All other MCP messages (`initialize`, `tools/list`, notifications) pass through transparently.
 
-## Key Features
-
-### Trust-Tier Gating
-
-Agents present signed manifests. protect-mcp evaluates them into trust tiers and gates tool access accordingly:
-
-| Tier | Meaning | How Assigned |
-|------|---------|--------------|
-| `unknown` | No manifest, or invalid signature | Default |
-| `signed-known` | Valid signed manifest | Automatic |
-| `evidenced` | Manifest + sufficient evidence history | Automatic |
-| `privileged` | Operator-granted elevated trust | Manual override |
-
-Policy example — require `signed-known` for destructive tools:
-
-```json
-{
-  "default_tier": "unknown",
-  "tools": {
-    "delete_user": { "min_tier": "signed-known", "rate_limit": "5/hour" },
-    "read_file": { "require": "any" },
-    "*": { "rate_limit": "100/hour" }
-  }
-}
-```
-
-### Credential Vault
-
-Agents never see raw API keys. Credentials are resolved from environment variables at call time and injected transparently:
-
-```json
-{
-  "credentials": {
-    "stripe_api": {
-      "inject": "header",
-      "name": "Authorization",
-      "value_env": "STRIPE_SECRET_KEY"
-    },
-    "github_token": {
-      "inject": "header",
-      "name": "Authorization",
-      "value_env": "GITHUB_TOKEN"
-    }
-  }
-}
-```
-
-Decision logs reference credential labels (`stripe_api`), never values.
-
-### Signed Decision Receipts
-
-Every tool call produces an Ed25519-signed v2 artifact — independently verifiable, no trust required:
-
-```
-[PROTECT_MCP_RECEIPT] {"v":2,"type":"decision_receipt","algorithm":"ed25519","kid":"kPrK...","issuer":"sb:protect","issued_at":"2026-03-21T10:00:00Z","payload":{"decision":"allow","tool":"read_file","tier":"signed-known","policy_digest":"a1b2c3d4","scope":"default","mode":"shadow"},"signature":"a1b2c3..."}
-```
-
-Verify with the CLI: `npx @veritasacta/verify receipt.json`
-Verify in browser: [scopeblind.com/verify](https://scopeblind.com/verify)
-
-### Bring Your Own Policy Engine (BYOPE)
-
-Plug in OPA, Cerbos, or any HTTP policy endpoint:
-
-```json
-{
-  "policy_engine": "external",
-  "external": {
-    "endpoint": "http://localhost:8181/v1/data/mcp/allow",
-    "format": "opa",
-    "timeout_ms": 500,
-    "fallback": "deny"
-  }
-}
-```
+## What Ships Today
 
-Supported formats: `opa`, `cerbos`, `generic`. ScopeBlind signs the receipt regardless of who made the decision.
+- **Per-tool policies** — block destructive tools, rate-limit expensive ones, and attach minimum-tier requirements
+- **Structured decision logs** — every decision is emitted to `stderr` with `[PROTECT_MCP]`
+- **Optional local signed receipts** — generated when you run with a policy containing `signing.key_path`
+- **Offline verification** — verify receipts or bundles with `npx @veritasacta/verify`
+- **No account required** — local keys, local policy, local process
 
-### Audit Bundle Export
+## Current Capability Boundaries
 
-Export self-contained audit bundles for offline verification or compliance:
+These are important before you roll this out or talk to users:
 
-```json
-{
-  "format": "scopeblind:audit-bundle",
-  "version": 1,
-  "tenant": "my-service",
-  "receipts": [ ...signed artifacts... ],
-  "verification": {
-    "algorithm": "ed25519",
-    "signing_keys": [ ...JWK keys... ]
-  }
-}
-```
+- **Signing is not automatic on the bare `npx protect-mcp -- ...` path.** That path logs decisions in shadow mode. For local signing, run `npx protect-mcp init` and then start the gateway with the generated policy file.
+- **Tier-aware policy checks are live, but manifest admission is not wired into the default CLI/stdio path.** The CLI defaults sessions to `unknown` unless a host integration calls the admission API programmatically.
+- **Credential config currently validates env-backed credential references and records credential labels in logs/receipts.** Generic per-call injection into arbitrary stdio tools is adapter-specific and is not performed by the default proxy path.
+- **External PDP adapters and audit bundle helpers exist as exported utilities.** They are not yet fully wired into the default CLI path.
 
 ## Policy File
 
@@ -137,11 +63,17 @@ Export self-contained audit bundles for offline verification or compliance:
     "read_tool": { "require": "any", "rate_limit": "100/hour" },
     "*": { "rate_limit": "500/hour" }
   },
-  "credentials": {
-    "api_key": { "inject": "header", "name": "Authorization", "value_env": "MY_API_KEY" }
-  },
   "signing": {
-    "key_file": ".protect-mcp-key.json"
+    "key_path": "./keys/gateway.json",
+    "issuer": "protect-mcp",
+    "enabled": true
+  },
+  "credentials": {
+    "internal_api": {
+      "inject": "env",
+      "name": "INTERNAL_API_KEY",
+      "value_env": "INTERNAL_API_KEY"
+    }
   }
 }
 ```
@@ -152,7 +84,7 @@ Export self-contained audit bundles for offline verification or compliance:
 |-------|--------|-------------|
 | `block` | `true` | Explicitly block this tool |
 | `require` | `"any"`, `"none"` | Basic access requirement |
-| `min_tier` | `"unknown"`, `"signed-known"`, `"evidenced"`, `"privileged"` | Minimum trust tier required |
+| `min_tier` | `"unknown"`, `"signed-known"`, `"evidenced"`, `"privileged"` | Minimum tier required if your host sets admission state |
 | `rate_limit` | `"N/unit"` | Rate limit (e.g. `"5/hour"`, `"100/day"`) |
 
 Tool names match exactly, with `"*"` as a wildcard fallback.
@@ -170,7 +102,7 @@ Add to `claude_desktop_config.json`:
       "command": "npx",
       "args": [
         "-y", "protect-mcp",
-        "--policy", "/path/to/policy.json",
+        "--policy", "/path/to/protect-mcp.json",
         "--enforce",
         "--", "node", "my-server.js"
       ]
@@ -181,7 +113,7 @@ Add to `claude_desktop_config.json`:
 
 ### Cursor / VS Code
 
-Same pattern — replace the server command with protect-mcp wrapping it.
+Same pattern — replace the server command with `protect-mcp` wrapping it.
 
 ## CLI Options
 
@@ -193,14 +125,16 @@ Commands:
   init              Generate Ed25519 keypair + config template
 
 Options:
-  --policy <path>   Policy JSON file (default: shadow mode, allow-all)
-  --slug <slug>     Service identifier for receipts
+  --policy <path>   Policy/config JSON file
+  --slug <slug>     Service identifier for logs/receipts
   --enforce         Enable enforcement mode (default: shadow)
   --verbose         Enable debug logging
   --help            Show help
 ```
 
-## Programmatic API
+## Programmatic Hooks
+
+The library also exposes the primitives that are not yet wired into the default CLI path:
 
 ```typescript
 import {
@@ -211,30 +145,60 @@ import {
   resolveCredential,
   initSigning,
   signDecision,
+  queryExternalPDP,
+  buildDecisionContext,
   createAuditBundle,
 } from 'protect-mcp';
 ```
 
-## Decision Logs
+Use these if you want to add:
+- manifest admission before a session starts
+- an external PDP (OPA, Cerbos, or a generic HTTP webhook)
+- custom credential-brokered integrations
+- audit bundle export around your own receipt store
 
-Every tool call emits structured JSON to stderr:
+## Decision Logs and Receipts
 
-```
-[PROTECT_MCP] {"v":2,"tool":"read_file","decision":"allow","tier":"signed-known","reason_code":"policy_allow","policy_digest":"a1b2c3d4","mode":"shadow","timestamp":1710000000}
+Every tool call emits structured JSON to `stderr`:
+
+```json
+[PROTECT_MCP] {"v":2,"tool":"read_file","decision":"allow","reason_code":"observe_mode","policy_digest":"none","mode":"shadow","timestamp":1710000000}
 ```
 
 When signing is configured, a signed receipt follows:
 
+```json
+[PROTECT_MCP_RECEIPT] {"v":2,"type":"decision_receipt","algorithm":"ed25519","kid":"...","issuer":"protect-mcp","issued_at":"2026-03-22T00:00:00Z","payload":{"tool":"read_file","decision":"allow","policy_digest":"...","mode":"shadow","request_id":"..."},"signature":"..."}
 ```
-[PROTECT_MCP_RECEIPT] {"v":2,"type":"decision_receipt","algorithm":"ed25519",...,"signature":"..."}
+
+Verify with the CLI: `npx @veritasacta/verify receipt.json`
+Verify in browser: [scopeblind.com/verify](https://scopeblind.com/verify)
+
+## Audit Bundles
+
+The package exports a helper for self-contained audit bundles:
+
+```json
+{
+  "format": "scopeblind:audit-bundle",
+  "version": 1,
+  "tenant": "my-service",
+  "receipts": ["..."],
+  "verification": {
+    "algorithm": "ed25519",
+    "signing_keys": ["..."]
+  }
+}
 ```
 
+Use `createAuditBundle()` around your own collected signed receipts.
+
 ## Philosophy
 
-- **Shadow first.** See what's happening before you control anything.
-- **Receipts, not logs.** Signed, independently verifiable. Not "trust us."
-- **Credential isolation.** Agents call tools. They never see API keys.
-- **Observe → Enforce → Audit.** Progressive adoption, not all-or-nothing.
+- **Shadow first.** See what agents are doing before you enforce anything.
+- **Receipts beat dashboard-only logs.** Signed artifacts should be independently verifiable.
+- **Keep the claims tight.** The default CLI path does not yet do everything the long-term architecture will support.
+- **Layer on top of existing auth.** Don't rip out your stack just to add control and evidence.
 
 ## License
 

package/dist/cli.js

@@ -3228,7 +3228,7 @@ var ProtectGateway = class {
 // src/cli.ts
 function printHelp() {
   process.stderr.write(`
-protect-mcp \u2014 Signed shadow-mode security gateway for MCP servers
+protect-mcp \u2014 Shadow-mode security gateway for MCP servers
 
 Usage:
   protect-mcp [options] -- <command> [args...]
@@ -3375,7 +3375,7 @@ async function handleInit(argv) {
 ${bold("protect-mcp initialized!")}
 
 Created:
-  ${configPath}     Config with shadow mode + tier gating
+  ${configPath}     Config with shadow mode + optional local signing
   ${keyPath}       Ed25519 signing keypair
 
 ${bold("Next steps:")}
@@ -3389,8 +3389,8 @@ ${bold("Your gateway public key:")}
 ${bold("Key ID (kid):")}
   ${keypair.kid}
 
-Shadow mode is the default \u2014 all tool calls are logged with signed
-receipts, but nothing is blocked. Add --enforce when ready.
+Shadow mode is the default \u2014 all tool calls are logged and nothing is blocked.
+Run with the generated policy file if you also want local signed receipts. Add --enforce when ready.
 `);
 }
 function bold(s) {

package/dist/cli.mjs

@@ -9,7 +9,7 @@ import {
 // src/cli.ts
 function printHelp() {
   process.stderr.write(`
-protect-mcp \u2014 Signed shadow-mode security gateway for MCP servers
+protect-mcp \u2014 Shadow-mode security gateway for MCP servers
 
 Usage:
   protect-mcp [options] -- <command> [args...]
@@ -156,7 +156,7 @@ async function handleInit(argv) {
 ${bold("protect-mcp initialized!")}
 
 Created:
-  ${configPath}     Config with shadow mode + tier gating
+  ${configPath}     Config with shadow mode + optional local signing
   ${keyPath}       Ed25519 signing keypair
 
 ${bold("Next steps:")}
@@ -170,8 +170,8 @@ ${bold("Your gateway public key:")}
 ${bold("Key ID (kid):")}
   ${keypair.kid}
 
-Shadow mode is the default \u2014 all tool calls are logged with signed
-receipts, but nothing is blocked. Add --enforce when ready.
+Shadow mode is the default \u2014 all tool calls are logged and nothing is blocked.
+Run with the generated policy file if you also want local signed receipts. Add --enforce when ready.
 `);
 }
 function bold(s) {

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "protect-mcp",
-  "version": "0.2.0",
-  "description": "Security gateway for MCP servers. Tool-level policies, rate limiting, and structured decision logging. Observe-by-default.",
+  "version": "0.2.2",
+  "description": "Security gateway for MCP servers. Shadow-mode logs by default, per-tool policies, optional local signing, and offline-verifiable receipts.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "module": "dist/index.mjs",
   "bin": {
-    "protect-mcp": "./dist/cli.js"
+    "protect-mcp": "dist/cli.js"
   },
   "exports": {
     ".": {
@@ -49,7 +49,7 @@
     "url": "https://github.com/tomjwxf/scopeblind-gateway/issues"
   },
   "dependencies": {
-    "@veritasacta/artifacts": "file:../../artifacts"
+    "@veritasacta/artifacts": "^0.2.0"
   },
   "optionalDependencies": {
     "@noble/curves": "^1.8.0",