protect-mcp 0.1.1 → 0.2.1

package/README.md

@@ -1,44 +1,79 @@
 # protect-mcp
 
-Security gateway for MCP servers. Tool-level policies, rate limiting, and structured decision logging.
+Security gateway for MCP servers. Shadow-mode logs by default, per-tool policies, optional local Ed25519 receipts, and verification-friendly audit output.
 
-**Observe by default.** Wraps any MCP server as a transparent proxy. Logs every tool call. 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
-# Observe mode — log all tool calls, allow everything through
+# Shadow mode — log every tool call, enforce nothing
 npx protect-mcp -- node my-server.js
 
-# Enforce mode with a policy file
-npx protect-mcp --policy policy.json --enforce -- node my-server.js
+# Generate keys + config template for local signing
+npx protect-mcp init
+
+# 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
 ```
 
-## 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 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.
 
-## Policy File
+## What Ships Today
+
+- **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
+
+## Current Capability Boundaries
 
-Create a `policy.json`:
+These are important before you roll this out or talk to users:
+
+- **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
 
 ```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" }
+  },
+  "signing": {
+    "key_path": "./keys/gateway.json",
+    "issuer": "protect-mcp",
+    "enabled": true
+  },
+  "credentials": {
+    "internal_api": {
+      "inject": "env",
+      "name": "INTERNAL_API_KEY",
+      "value_env": "INTERNAL_API_KEY"
+    }
   }
 }
 ```
@@ -47,11 +82,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 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.
 
@@ -68,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"
       ]
@@ -79,63 +113,95 @@ Add to `claude_desktop_config.json`:
 
 ### Cursor / VS Code
 
-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).
+Same pattern — replace the server command with `protect-mcp` wrapping it.
 
 ## 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/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 { ProtectGateway, loadPolicy } from 'protect-mcp'; // npm: protect-mcp
+import {
+  ProtectGateway,
+  loadPolicy,
+  evaluateTier,
+  meetsMinTier,
+  resolveCredential,
+  initSigning,
+  signDecision,
+  queryExternalPDP,
+  buildDecisionContext,
+  createAuditBundle,
+} from 'protect-mcp';
+```
+
+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
+
+## Decision Logs and Receipts
+
+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":"..."}
+```
+
+Verify with the CLI: `npx @veritasacta/verify receipt.json`
+Verify in browser: [scopeblind.com/verify](https://scopeblind.com/verify)
 
-const { policy, digest } = loadPolicy('./policy.json');
+## Audit Bundles
 
-const gateway = new ProtectGateway({
-  command: 'node',
-  args: ['my-server.js'],
-  policy,
-  policyDigest: digest,
-  enforce: true,
-});
+The package exports a helper for self-contained audit bundles:
 
-await gateway.start();
+```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 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
 
-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) *)
+*/