protect-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,44 +1,147 @@
-# @scopeblind/protect-mcp
+# protect-mcp
 
-Security gateway for MCP servers. Tool-level policies, rate limiting, and structured decision logging.
+Security gateway for MCP servers. Tool-level policies, trust-tier gating, credential isolation, and signed decision receipts.
 
-**Observe by default.** Wraps any MCP server as a transparent proxy. Logs every tool call. Optionally enforces policies.
+**Shadow mode by default.** Wraps any MCP server as a transparent proxy. Logs every tool call. Signs every decision. Optionally enforces policies.
 
 ## Quick Start
 
 ```bash
-# Observe mode — log all tool calls, allow everything through
-npx @scopeblind/protect-mcp -- node my-server.js
+# Shadow mode — log and sign every tool call, enforce nothing
+npx protect-mcp -- node my-server.js
+
+# Initialize a new project with keys + config template
+npx protect-mcp init
 
 # Enforce mode with a policy file
-npx @scopeblind/protect-mcp --policy policy.json --enforce -- node my-server.js
+npx protect-mcp --policy policy.json --enforce -- node my-server.js
 ```
 
-## How It Works
+## What It Does
 
 protect-mcp sits between your MCP client and server as a stdio proxy:
 
 ```
-MCP Client <--stdin/stdout--> protect-mcp <--stdin/stdout--> your MCP server
+MCP Client ←stdin/stdout→ protect-mcp ←stdin/stdout→ your MCP server
 ```
 
 It intercepts `tools/call` JSON-RPC requests and:
-- **Observe mode** (default): logs every tool call to stderr, allows everything through
-- **Enforce mode**: applies policy rules, blocks denied tools, rate-limits others
+- **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
 
 All other MCP messages (`initialize`, `tools/list`, notifications) pass through transparently.
 
-## Policy File
+## 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"
+  }
+}
+```
+
+Supported formats: `opa`, `cerbos`, `generic`. ScopeBlind signs the receipt regardless of who made the decision.
+
+### Audit Bundle Export
 
-Create a `policy.json`:
+Export self-contained audit bundles for offline verification or compliance:
 
 ```json
 {
+  "format": "scopeblind:audit-bundle",
+  "version": 1,
+  "tenant": "my-service",
+  "receipts": [ ...signed artifacts... ],
+  "verification": {
+    "algorithm": "ed25519",
+    "signing_keys": [ ...JWK keys... ]
+  }
+}
+```
+
+## Policy File
+
+```json
+{
+  "default_tier": "unknown",
   "tools": {
-    "dangerous_tool": { "require": "gateway", "rate_limit": "5/hour" },
-    "read_only_tool": { "require": "any" },
-    "destructive_tool": { "block": true },
-    "*": { "require": "any", "rate_limit": "100/hour" }
+    "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" }
+  },
+  "credentials": {
+    "api_key": { "inject": "header", "name": "Authorization", "value_env": "MY_API_KEY" }
+  },
+  "signing": {
+    "key_file": ".protect-mcp-key.json"
   }
 }
 ```
@@ -47,11 +150,10 @@ Create a `policy.json`:
 
 | Field | Values | Description |
 |-------|--------|-------------|
-| `require` | `"gateway"`, `"any"`, `"none"` | Identity requirement (metadata only in v1 — not enforced until v2 SSE transport) |
-| `rate_limit` | `"N/unit"` | Rate limit (e.g. `"5/hour"`, `"100/day"`, `"10/minute"`) |
 | `block` | `true` | Explicitly block this tool |
-
-> **v1 enforcement:** `block` and `rate_limit` are enforced in `--enforce` mode. `require` is recorded in decision logs for policy documentation but not enforced — per-request identity verification requires the SSE gateway mode planned for v2.
+| `require` | `"any"`, `"none"` | Basic access requirement |
+| `min_tier` | `"unknown"`, `"signed-known"`, `"evidenced"`, `"privileged"` | Minimum trust tier required |
+| `rate_limit` | `"N/unit"` | Rate limit (e.g. `"5/hour"`, `"100/day"`) |
 
 Tool names match exactly, with `"*"` as a wildcard fallback.
 
@@ -67,7 +169,7 @@ Add to `claude_desktop_config.json`:
     "my-protected-server": {
       "command": "npx",
       "args": [
-        "-y", "@scopeblind/protect-mcp",
+        "-y", "protect-mcp",
         "--policy", "/path/to/policy.json",
         "--enforce",
         "--", "node", "my-server.js"
@@ -81,39 +183,19 @@ Add to `claude_desktop_config.json`:
 
 Same pattern — replace the server command with protect-mcp wrapping it.
 
-## Decision Logs
-
-Every tool call emits a structured JSON log to stderr:
-
-```
-[PROTECT_MCP] {"v":1,"tool":"dangerous_tool","decision":"deny","reason_code":"rate_limit_exceeded","policy_digest":"a1b2c3d4","request_id":"req_abc123","timestamp":1710000000,"mode":"enforce","rate_limit_remaining":0}
-```
-
-### Log Fields
-
-| Field | Description |
-|-------|-------------|
-| `v` | Schema version (always `1`) |
-| `tool` | Tool name that was called |
-| `decision` | `"allow"` or `"deny"` |
-| `reason_code` | `"policy_allow"`, `"policy_block"`, `"rate_limit_exceeded"`, `"observe_mode"`, `"default_allow"` |
-| `policy_digest` | SHA-256 prefix of the policy file |
-| `request_id` | Unique request identifier |
-| `timestamp` | Unix timestamp (ms) |
-| `mode` | `"observe"` or `"enforce"` |
-| `rate_limit_remaining` | Remaining rate limit budget (if applicable) |
-
-These are **decision logs**, not signed receipts. Cryptographically signed receipts require the ScopeBlind API (v2).
-
 ## CLI Options
 
 ```
 protect-mcp [options] -- <command> [args...]
+protect-mcp init
+
+Commands:
+  init              Generate Ed25519 keypair + config template
 
 Options:
-  --policy <path>   Policy JSON file (default: allow-all)
-  --slug <slug>     ScopeBlind tenant slug (optional)
-  --enforce         Enable enforcement mode (default: observe-only)
+  --policy <path>   Policy JSON file (default: shadow mode, allow-all)
+  --slug <slug>     Service identifier for receipts
+  --enforce         Enable enforcement mode (default: shadow)
   --verbose         Enable debug logging
   --help            Show help
 ```
@@ -121,21 +203,41 @@ Options:
 ## Programmatic API
 
 ```typescript
-import { ProtectGateway, loadPolicy } from '@scopeblind/protect-mcp';
+import {
+  ProtectGateway,
+  loadPolicy,
+  evaluateTier,
+  meetsMinTier,
+  resolveCredential,
+  initSigning,
+  signDecision,
+  createAuditBundle,
+} from 'protect-mcp';
+```
 
-const { policy, digest } = loadPolicy('./policy.json');
+## Decision Logs
 
-const gateway = new ProtectGateway({
-  command: 'node',
-  args: ['my-server.js'],
-  policy,
-  policyDigest: digest,
-  enforce: true,
-});
+Every tool call emits structured JSON to stderr:
 
-await gateway.start();
 ```
+[PROTECT_MCP] {"v":2,"tool":"read_file","decision":"allow","tier":"signed-known","reason_code":"policy_allow","policy_digest":"a1b2c3d4","mode":"shadow","timestamp":1710000000}
+```
+
+When signing is configured, a signed receipt follows:
+
+```
+[PROTECT_MCP_RECEIPT] {"v":2,"type":"decision_receipt","algorithm":"ed25519",...,"signature":"..."}
+```
+
+## 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.
 
 ## License
 
-FSL-1.1-MIT
+FSL-1.1-MIT — free to use, converts to full MIT after 2 years.
+
+[scopeblind.com](https://scopeblind.com) · [npm](https://www.npmjs.com/package/protect-mcp) · [GitHub](https://github.com/tomjwxf/scopeblind-gateway)

package/dist/chunk-D733KAPG.mjs

@@ -0,0 +1,252 @@
+// node_modules/@noble/hashes/esm/cryptoNode.js
+import * as nc from "crypto";
+var crypto = nc && typeof nc === "object" && "webcrypto" in nc ? nc.webcrypto : nc && typeof nc === "object" && "randomBytes" in nc ? nc : void 0;
+
+// node_modules/@noble/hashes/esm/utils.js
+function isBytes(a) {
+  return a instanceof Uint8Array || ArrayBuffer.isView(a) && a.constructor.name === "Uint8Array";
+}
+function anumber(n) {
+  if (!Number.isSafeInteger(n) || n < 0)
+    throw new Error("positive integer expected, got " + n);
+}
+function abytes(b, ...lengths) {
+  if (!isBytes(b))
+    throw new Error("Uint8Array expected");
+  if (lengths.length > 0 && !lengths.includes(b.length))
+    throw new Error("Uint8Array expected of length " + lengths + ", got length=" + b.length);
+}
+function ahash(h) {
+  if (typeof h !== "function" || typeof h.create !== "function")
+    throw new Error("Hash should be wrapped by utils.createHasher");
+  anumber(h.outputLen);
+  anumber(h.blockLen);
+}
+function aexists(instance, checkFinished = true) {
+  if (instance.destroyed)
+    throw new Error("Hash instance has been destroyed");
+  if (checkFinished && instance.finished)
+    throw new Error("Hash#digest() has already been called");
+}
+function aoutput(out, instance) {
+  abytes(out);
+  const min = instance.outputLen;
+  if (out.length < min) {
+    throw new Error("digestInto() expects output buffer of length at least " + min);
+  }
+}
+function u8(arr) {
+  return new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength);
+}
+function u32(arr) {
+  return new Uint32Array(arr.buffer, arr.byteOffset, Math.floor(arr.byteLength / 4));
+}
+function clean(...arrays) {
+  for (let i = 0; i < arrays.length; i++) {
+    arrays[i].fill(0);
+  }
+}
+function createView(arr) {
+  return new DataView(arr.buffer, arr.byteOffset, arr.byteLength);
+}
+function rotr(word, shift) {
+  return word << 32 - shift | word >>> shift;
+}
+function rotl(word, shift) {
+  return word << shift | word >>> 32 - shift >>> 0;
+}
+var isLE = /* @__PURE__ */ (() => new Uint8Array(new Uint32Array([287454020]).buffer)[0] === 68)();
+function byteSwap(word) {
+  return word << 24 & 4278190080 | word << 8 & 16711680 | word >>> 8 & 65280 | word >>> 24 & 255;
+}
+var swap8IfBE = isLE ? (n) => n : (n) => byteSwap(n);
+var byteSwapIfBE = swap8IfBE;
+function byteSwap32(arr) {
+  for (let i = 0; i < arr.length; i++) {
+    arr[i] = byteSwap(arr[i]);
+  }
+  return arr;
+}
+var swap32IfBE = isLE ? (u) => u : byteSwap32;
+var hasHexBuiltin = /* @__PURE__ */ (() => (
+  // @ts-ignore
+  typeof Uint8Array.from([]).toHex === "function" && typeof Uint8Array.fromHex === "function"
+))();
+var hexes = /* @__PURE__ */ Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, "0"));
+function bytesToHex(bytes) {
+  abytes(bytes);
+  if (hasHexBuiltin)
+    return bytes.toHex();
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) {
+    hex += hexes[bytes[i]];
+  }
+  return hex;
+}
+var asciis = { _0: 48, _9: 57, A: 65, F: 70, a: 97, f: 102 };
+function asciiToBase16(ch) {
+  if (ch >= asciis._0 && ch <= asciis._9)
+    return ch - asciis._0;
+  if (ch >= asciis.A && ch <= asciis.F)
+    return ch - (asciis.A - 10);
+  if (ch >= asciis.a && ch <= asciis.f)
+    return ch - (asciis.a - 10);
+  return;
+}
+function hexToBytes(hex) {
+  if (typeof hex !== "string")
+    throw new Error("hex string expected, got " + typeof hex);
+  if (hasHexBuiltin)
+    return Uint8Array.fromHex(hex);
+  const hl = hex.length;
+  const al = hl / 2;
+  if (hl % 2)
+    throw new Error("hex string expected, got unpadded hex of length " + hl);
+  const array = new Uint8Array(al);
+  for (let ai = 0, hi = 0; ai < al; ai++, hi += 2) {
+    const n1 = asciiToBase16(hex.charCodeAt(hi));
+    const n2 = asciiToBase16(hex.charCodeAt(hi + 1));
+    if (n1 === void 0 || n2 === void 0) {
+      const char = hex[hi] + hex[hi + 1];
+      throw new Error('hex string expected, got non-hex character "' + char + '" at index ' + hi);
+    }
+    array[ai] = n1 * 16 + n2;
+  }
+  return array;
+}
+var nextTick = async () => {
+};
+async function asyncLoop(iters, tick, cb) {
+  let ts = Date.now();
+  for (let i = 0; i < iters; i++) {
+    cb(i);
+    const diff = Date.now() - ts;
+    if (diff >= 0 && diff < tick)
+      continue;
+    await nextTick();
+    ts += diff;
+  }
+}
+function utf8ToBytes(str) {
+  if (typeof str !== "string")
+    throw new Error("string expected");
+  return new Uint8Array(new TextEncoder().encode(str));
+}
+function bytesToUtf8(bytes) {
+  return new TextDecoder().decode(bytes);
+}
+function toBytes(data) {
+  if (typeof data === "string")
+    data = utf8ToBytes(data);
+  abytes(data);
+  return data;
+}
+function kdfInputToBytes(data) {
+  if (typeof data === "string")
+    data = utf8ToBytes(data);
+  abytes(data);
+  return data;
+}
+function concatBytes(...arrays) {
+  let sum = 0;
+  for (let i = 0; i < arrays.length; i++) {
+    const a = arrays[i];
+    abytes(a);
+    sum += a.length;
+  }
+  const res = new Uint8Array(sum);
+  for (let i = 0, pad = 0; i < arrays.length; i++) {
+    const a = arrays[i];
+    res.set(a, pad);
+    pad += a.length;
+  }
+  return res;
+}
+function checkOpts(defaults, opts) {
+  if (opts !== void 0 && {}.toString.call(opts) !== "[object Object]")
+    throw new Error("options should be object or undefined");
+  const merged = Object.assign(defaults, opts);
+  return merged;
+}
+var Hash = class {
+};
+function createHasher(hashCons) {
+  const hashC = (msg) => hashCons().update(toBytes(msg)).digest();
+  const tmp = hashCons();
+  hashC.outputLen = tmp.outputLen;
+  hashC.blockLen = tmp.blockLen;
+  hashC.create = () => hashCons();
+  return hashC;
+}
+function createOptHasher(hashCons) {
+  const hashC = (msg, opts) => hashCons(opts).update(toBytes(msg)).digest();
+  const tmp = hashCons({});
+  hashC.outputLen = tmp.outputLen;
+  hashC.blockLen = tmp.blockLen;
+  hashC.create = (opts) => hashCons(opts);
+  return hashC;
+}
+function createXOFer(hashCons) {
+  const hashC = (msg, opts) => hashCons(opts).update(toBytes(msg)).digest();
+  const tmp = hashCons({});
+  hashC.outputLen = tmp.outputLen;
+  hashC.blockLen = tmp.blockLen;
+  hashC.create = (opts) => hashCons(opts);
+  return hashC;
+}
+var wrapConstructor = createHasher;
+var wrapConstructorWithOpts = createOptHasher;
+var wrapXOFConstructorWithOpts = createXOFer;
+function randomBytes(bytesLength = 32) {
+  if (crypto && typeof crypto.getRandomValues === "function") {
+    return crypto.getRandomValues(new Uint8Array(bytesLength));
+  }
+  if (crypto && typeof crypto.randomBytes === "function") {
+    return Uint8Array.from(crypto.randomBytes(bytesLength));
+  }
+  throw new Error("crypto.getRandomValues must be defined");
+}
+
+export {
+  isBytes,
+  anumber,
+  abytes,
+  ahash,
+  aexists,
+  aoutput,
+  u8,
+  u32,
+  clean,
+  createView,
+  rotr,
+  rotl,
+  isLE,
+  byteSwap,
+  swap8IfBE,
+  byteSwapIfBE,
+  byteSwap32,
+  swap32IfBE,
+  bytesToHex,
+  hexToBytes,
+  nextTick,
+  asyncLoop,
+  utf8ToBytes,
+  bytesToUtf8,
+  toBytes,
+  kdfInputToBytes,
+  concatBytes,
+  checkOpts,
+  Hash,
+  createHasher,
+  createOptHasher,
+  createXOFer,
+  wrapConstructor,
+  wrapConstructorWithOpts,
+  wrapXOFConstructorWithOpts,
+  randomBytes
+};
+/*! Bundled license information:
+
+@noble/hashes/esm/utils.js:
+  (*! noble-hashes - MIT License (c) 2022 Paul Miller (paulmillr.com) *)
+*/