protect-mcp 0.9.4 → 0.9.6

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 0.9.6: policy you can see and change
+
+The gate is default-deny and fail-closed, but a deny used to be a dead end: an
+empty reason and no pointer to the file that decides. This release makes the
+policy legible and editable from the terminal, and lets a running gate pick up
+a policy change without a restart.
+
+- **`policy` command.** `policy list` shows every tool named in the policy
+  (permit / forbid / default-deny) cross-referenced with how often the gate
+  actually allowed or denied it; `policy show` prints the active policy and its
+  digest; `policy allow <tool>` / `policy deny <tool>` append a Cedar rule and
+  print the digest change; `policy path` prints the file. Idempotent and
+  tool-name validated.
+- **Denies that teach.** A blocked call now says whether it was default-deny
+  (no permit matched) or an explicit forbid, names the policy directory, and
+  gives the exact fix: `npx protect-mcp policy allow <tool>`.
+- **Hot reload.** `protect-mcp serve` watches the .cedar files and reloads the
+  policy on an on-disk change, so `policy allow/deny` (or a hand edit) takes
+  effect without restarting the gate. Fail-closed: an unparseable edit keeps the
+  previous policy rather than opening the gate, and the reload is logged.
+
+## 0.9.5: replayable from scratch
+
+The public demo film (legate.scopeblind.com/record) is now reproducible by
+anyone in 60 seconds, and the CLI answers the first two commands every new
+user types.
+
+- **`sample`.** Seeds a clearly-labeled sample record (fresh Ed25519 keypair,
+  kid `sample-demo`): 8 decisions including one BLOCKED network call and two
+  payments ($0.02 x402-style per-call, $12.50 invoice), plus
+  `demo-tampered.jsonl` with one decision flipped after signing. The receipts
+  are real signed artifacts (same envelope and canonical-JSON preimage as the
+  gate's signer), so `record`, `claim --payment-under`, `verify-claim`, and
+  `anchor-record` work on the folder immediately. Refuses to touch an existing
+  record or signing key; `--force` overrides.
+- **`--version` / `version` / `-V`.** Prints the installed version. Previously
+  these fell through to wrap-mode parsing and errored demanding a `--`
+  separator, which was the first thing many new users saw.
+- **`help` word.** `npx protect-mcp help` prints usage (previously errored).
+  Help and version flags are now only recognized BEFORE the `--` separator, so
+  `protect-mcp -- node server.js --version` wraps that command as intended
+  instead of printing our help.
+
 ## 0.9.4: agent payments get receipts, records get heartbeats, anchors get names
 
 The provenance layer reaches the agentic economy's payment rails (x402), the

package/README.md

@@ -185,6 +185,26 @@ npx protect-mcp claim --no net.egress --anchor
 This is an accountable, position-blind attestation, not full zero-knowledge: it
 reveals the shape, not the content.
 
+## Try it in 60 seconds (no agent required)
+
+[![Watch the two-minute demo film](https://legate.scopeblind.com/media/scopeblind-demo-poster.jpg)](https://legate.scopeblind.com/record)
+
+Watch the two-minute film at [legate.scopeblind.com/record](https://legate.scopeblind.com/record), then replay it against your own copy:
+
+```bash
+npx protect-mcp sample     # seed a labeled sample record (8 decisions: 1 blocked, 2 payments)
+npx protect-mcp record     # open it: signatures verified in your browser
+
+npx protect-mcp claim --payment-under 100 --anchor --output payments-under-100.json
+npx protect-mcp verify-claim payments-under-100.json
+npx protect-mcp anchor-record
+```
+
+Drop the generated `demo-tampered.jsonl` into the record page to watch a
+post-signing edit get caught. `sample` refuses to touch an existing record, so
+run it in an empty folder. When you are ready for the real thing, wire the gate
+below and the same commands run against your agent's own record.
+
 ## Claude Code hook quickstart
 
 ```bash
@@ -368,6 +388,8 @@ To report a vulnerability, see [SECURITY.md](./SECURITY.md).
 |---------|-------------|
 | `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. |
+| `sample` | Seed a clearly-labeled sample record (8 decisions: one blocked call, two payments; kid `sample-demo`) plus a tampered copy, so `record`, `claim`, `verify-claim`, and `anchor-record` are replayable from scratch before wiring an agent. Refuses to touch an existing record; `--force` overrides. |
+| `policy` | See and change the Cedar policy from the terminal: `policy list` (permit / forbid / default-deny per tool, with how often the gate allowed or denied it), `policy show`, `policy allow <tool>`, `policy deny <tool>`, `policy path`. A running `serve` hot-reloads on the change. |
 | `wrap` | Print a protected MCP command or patch Claude Desktop MCP servers. Dry-run by default; use `--write` to update Claude Desktop config. |
 | `dashboard` | Start a local-only dashboard on `127.0.0.1` showing tool inventory, risk, policy coverage, exact-action approvals, receipt chains, and audit export. |
 | `recommend` | Draft a reviewable JSON policy from observed local calls. Dry-run by default; use `--write` to create `protect-mcp.recommended.json`. |

package/dist/{chunk-H332ZNJ6.mjs → chunk-WCZJGEBO.mjs}

@@ -20,7 +20,7 @@ import {
 // src/hook-server.ts
 import { createServer } from "http";
 import { createHash, randomUUID, randomBytes } from "crypto";
-import { appendFileSync, readFileSync, existsSync, readdirSync } from "fs";
+import { appendFileSync, readFileSync, existsSync, readdirSync, statSync } from "fs";
 import { join } from "path";
 
 // src/scopeblind-bridge.ts
@@ -256,6 +256,7 @@ async function handlePreToolUse(input, state) {
     ...input.teamName && { team_name: input.teamName },
     ...input.agentType && { agent_type: input.agentType }
   };
+  maybeReloadCedar(state);
   if (state.cedarPolicies) {
     try {
       const cedarDecision = await evaluateCedar(state.cedarPolicies, {
@@ -293,10 +294,13 @@ async function handlePreToolUse(input, state) {
           sandbox_state: detectSandboxState(),
           plan_receipt_id: state.activePlanReceiptId || void 0
         });
+        const isDefaultDeny = !reason || reason === "cedar_deny" || /reason":\[\]/.test(reason);
+        const policyRef = state.cedarDir ? ` Policy: ${state.cedarDir}.` : "";
+        const howTo = isDefaultDeny ? ` No permit matched (default-deny, fail-closed).${policyRef} Allow it: npx protect-mcp policy allow ${toolName}` : ` Blocked by an explicit forbid rule.${policyRef} Review: npx protect-mcp policy show`;
         if (denyCount === 1) {
           process.stderr.write(
-            `[PROTECT_MCP] No Cedar permit for "${toolName}" \u2014 suggest:
-  ${suggestion}
+            `[PROTECT_MCP] Denied "${toolName}" (${isDefaultDeny ? "default-deny" : "forbid"}).
+  Allow with: npx protect-mcp policy allow ${toolName}
 `
           );
         }
@@ -304,7 +308,7 @@ async function handlePreToolUse(input, state) {
           hookSpecificOutput: {
             hookEventName: "PreToolUse",
             permissionDecision: "deny",
-            permissionDecisionReason: `[ScopeBlind] Denied by Cedar policy. ${reason}. Forbidden: "${toolName}" is not permitted. Try a read-only alternative.` + (denyCount > 1 ? ` (attempt ${denyCount})` : "")
+            permissionDecisionReason: `[ScopeBlind] Denied "${toolName}".${howTo}` + (denyCount > 1 ? ` (attempt ${denyCount})` : "")
           }
         };
       }
@@ -803,6 +807,9 @@ async function startHookServer(options = {}) {
   }
   const state = {
     cedarPolicies,
+    cedarDir: cedarDir || null,
+    cedarMtimeMs: cedarDir ? newestCedarMtime(cedarDir) : 0,
+    cedarCheckedMs: 0,
     jsonPolicy,
     rateLimitStore: /* @__PURE__ */ new Map(),
     receiptBuffer: new ReceiptBuffer(),
@@ -993,6 +1000,40 @@ async function startHookServer(options = {}) {
   process.on("SIGTERM", shutdown);
   return server;
 }
+function newestCedarMtime(dir) {
+  try {
+    let newest = 0;
+    for (const f of readdirSync(dir)) {
+      if (!f.endsWith(".cedar")) continue;
+      const m = statSync(join(dir, f)).mtimeMs;
+      if (m > newest) newest = m;
+    }
+    return newest;
+  } catch {
+    return 0;
+  }
+}
+var CEDAR_CHECK_THROTTLE_MS = 2e3;
+function maybeReloadCedar(state) {
+  if (!state.cedarDir) return;
+  const nowMs = Date.now();
+  if (nowMs - state.cedarCheckedMs < CEDAR_CHECK_THROTTLE_MS) return;
+  state.cedarCheckedMs = nowMs;
+  const m = newestCedarMtime(state.cedarDir);
+  if (m <= state.cedarMtimeMs) return;
+  try {
+    const reloaded = loadCedarPolicies(state.cedarDir);
+    state.cedarPolicies = reloaded;
+    state.policyDigest = reloaded.digest;
+    state.cedarMtimeMs = m;
+    process.stderr.write(`[PROTECT_MCP] Cedar policy reloaded (digest: ${reloaded.digest}) after on-disk change.
+`);
+  } catch (err) {
+    process.stderr.write(`[PROTECT_MCP] Cedar reload failed, keeping the previous policy: ${err instanceof Error ? err.message : err}
+`);
+    state.cedarMtimeMs = m;
+  }
+}
 function findCedarDir() {
   for (const candidate of ["cedar", "policies", "."]) {
     try {