protect-mcp 0.3.1 → 0.3.2

package/dist/cli.js

@@ -2697,6 +2697,178 @@ var init_bundle = __esm({
   }
 });
 
+// src/report.ts
+var report_exports = {};
+__export(report_exports, {
+  formatReportMarkdown: () => formatReportMarkdown,
+  generateReport: () => generateReport
+});
+function generateReport(logPath, receiptPath, periodDays) {
+  const now = /* @__PURE__ */ new Date();
+  const from = new Date(now.getTime() - periodDays * 864e5);
+  const entries = [];
+  if ((0, import_node_fs7.existsSync)(logPath)) {
+    const raw = (0, import_node_fs7.readFileSync)(logPath, "utf-8");
+    for (const line of raw.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const jsonStr = trimmed.replace(/^\[PROTECT_MCP\]\s*/, "");
+      try {
+        const parsed = JSON.parse(jsonStr);
+        if (parsed.tool && parsed.decision && parsed.timestamp) {
+          const entryTime = typeof parsed.timestamp === "number" && parsed.timestamp > 1e12 ? parsed.timestamp : parsed.timestamp * 1e3;
+          if (entryTime >= from.getTime()) {
+            entries.push(parsed);
+          }
+        }
+      } catch {
+      }
+    }
+  }
+  let receiptsSigned = 0;
+  let signerKid = "";
+  let signerIssuer = "";
+  if ((0, import_node_fs7.existsSync)(receiptPath)) {
+    const raw = (0, import_node_fs7.readFileSync)(receiptPath, "utf-8");
+    for (const line of raw.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed.signature) {
+          receiptsSigned++;
+          if (parsed.kid && !signerKid) signerKid = parsed.kid;
+          if (parsed.issuer && !signerIssuer) signerIssuer = parsed.issuer;
+        }
+      } catch {
+      }
+    }
+  }
+  const toolMap = /* @__PURE__ */ new Map();
+  const tiers = /* @__PURE__ */ new Set();
+  const policyDigests = /* @__PURE__ */ new Map();
+  let allowed = 0;
+  let blocked = 0;
+  let rateLimited = 0;
+  let approvalRequired = 0;
+  for (const entry of entries) {
+    const tool = entry.tool;
+    if (!toolMap.has(tool)) {
+      toolMap.set(tool, { total: 0, allowed: 0, blocked: 0, rate_limited: 0, approval_required: 0 });
+    }
+    const tm = toolMap.get(tool);
+    tm.total++;
+    if (entry.decision === "allow") {
+      allowed++;
+      tm.allowed++;
+    } else if (entry.decision === "deny" && entry.reason_code === "rate_limit_exceeded") {
+      rateLimited++;
+      tm.rate_limited++;
+    } else if (entry.decision === "deny" && entry.reason_code === "require_approval") {
+      approvalRequired++;
+      tm.approval_required++;
+    } else {
+      blocked++;
+      tm.blocked++;
+    }
+    if (entry.tier) tiers.add(entry.tier);
+    if (entry.policy_digest && !policyDigests.has(entry.policy_digest)) {
+      policyDigests.set(entry.policy_digest, new Date(entry.timestamp).toISOString());
+    }
+  }
+  const policyChanges = Array.from(policyDigests.entries()).map(([digest, at]) => ({
+    at,
+    policy_digest: digest
+  })).sort((a, b) => a.at.localeCompare(b.at));
+  return {
+    generated_at: now.toISOString(),
+    period: { from: from.toISOString(), to: now.toISOString() },
+    signing_identity: signerKid ? { kid: signerKid, issuer: signerIssuer } : null,
+    summary: {
+      total_decisions: entries.length,
+      allowed,
+      blocked,
+      rate_limited: rateLimited,
+      approval_required: approvalRequired,
+      unique_tools: toolMap.size,
+      unique_tiers: tiers.size
+    },
+    tool_breakdown: Array.from(toolMap.entries()).map(([tool, stats]) => ({ tool, ...stats })).sort((a, b) => b.total - a.total),
+    policy_changes: policyChanges,
+    verification: {
+      receipts_signed: receiptsSigned,
+      receipts_unsigned: entries.length - receiptsSigned,
+      verify_command: "npx @veritasacta/verify audit-bundle.json --bundle"
+    }
+  };
+}
+function formatReportMarkdown(report) {
+  const lines = [];
+  lines.push("# ScopeBlind Compliance Report");
+  lines.push("");
+  lines.push(`**Generated:** ${report.generated_at}`);
+  lines.push(`**Period:** ${report.period.from.split("T")[0]} to ${report.period.to.split("T")[0]}`);
+  if (report.signing_identity) {
+    lines.push(`**Signing identity:** kid \`${report.signing_identity.kid}\`, issuer \`${report.signing_identity.issuer}\``);
+  }
+  lines.push("");
+  lines.push("## Summary");
+  lines.push("");
+  lines.push(`| Metric | Value |`);
+  lines.push(`|--------|-------|`);
+  lines.push(`| Total decisions | ${report.summary.total_decisions} |`);
+  lines.push(`| Allowed | ${report.summary.allowed} |`);
+  lines.push(`| Blocked | ${report.summary.blocked} |`);
+  lines.push(`| Rate-limited | ${report.summary.rate_limited} |`);
+  lines.push(`| Approval required | ${report.summary.approval_required} |`);
+  lines.push(`| Unique tools | ${report.summary.unique_tools} |`);
+  lines.push(`| Unique tiers | ${report.summary.unique_tiers} |`);
+  lines.push("");
+  if (report.tool_breakdown.length > 0) {
+    lines.push("## Tool Breakdown");
+    lines.push("");
+    lines.push("| Tool | Total | Allowed | Blocked | Rate-limited | Approval |");
+    lines.push("|------|-------|---------|---------|--------------|----------|");
+    for (const t of report.tool_breakdown) {
+      lines.push(`| \`${t.tool}\` | ${t.total} | ${t.allowed} | ${t.blocked} | ${t.rate_limited} | ${t.approval_required} |`);
+    }
+    lines.push("");
+  }
+  if (report.policy_changes.length > 0) {
+    lines.push("## Policy History");
+    lines.push("");
+    lines.push("| Timestamp | Policy Digest |");
+    lines.push("|-----------|--------------|");
+    for (const pc of report.policy_changes) {
+      lines.push(`| ${pc.at} | \`${pc.policy_digest}\` |`);
+    }
+    lines.push("");
+  }
+  lines.push("## Verification");
+  lines.push("");
+  lines.push(`- Receipts signed: **${report.verification.receipts_signed}**`);
+  lines.push(`- Receipts unsigned: **${report.verification.receipts_unsigned}**`);
+  lines.push("");
+  lines.push("Verify the audit bundle:");
+  lines.push("");
+  lines.push("```bash");
+  lines.push(report.verification.verify_command);
+  lines.push("```");
+  lines.push("");
+  lines.push("The verifier is MIT-licensed and works offline. No ScopeBlind account required.");
+  lines.push("");
+  lines.push("---");
+  lines.push("*Generated by protect-mcp \xB7 scopeblind.com*");
+  return lines.join("\n");
+}
+var import_node_fs7;
+var init_report = __esm({
+  "src/report.ts"() {
+    "use strict";
+    import_node_fs7 = require("fs");
+  }
+});
+
 // src/gateway.ts
 var import_node_child_process = require("child_process");
 var import_node_crypto2 = require("crypto");
@@ -3019,7 +3191,11 @@ async function initSigning(config) {
     return warnings;
   }
   try {
-    artifactsModule = await import("@veritasacta/artifacts");
+    const moduleName = "@veritasacta/artifacts";
+    artifactsModule = await import(
+      /* @vite-ignore */
+      moduleName
+    );
   } catch {
     warnings.push("signing: @veritasacta/artifacts not available \u2014 receipts will be unsigned");
     return warnings;
@@ -3596,8 +3772,31 @@ var ProtectGateway = class {
   async interceptToolCall(request) {
     const toolName = request.params?.name || "unknown";
     const requestId = (0, import_node_crypto2.randomUUID)().slice(0, 12);
-    const toolPolicy = getToolPolicy(toolName, this.config.policy);
     const mode = this.config.enforce ? "enforce" : "shadow";
+    let resolvedAgentKid = this.admissionResult?.agent_id;
+    let effectiveToolPolicy;
+    if (this.config.multiAgent?.enabled) {
+      const paramKid = request.params?._passport_kid;
+      if (paramKid) resolvedAgentKid = paramKid;
+      const agentOverrides = resolvedAgentKid ? this.config.multiAgent.agentPolicies?.[resolvedAgentKid] : void 0;
+      if (agentOverrides && agentOverrides[toolName]) {
+        effectiveToolPolicy = { ...getToolPolicy(toolName, this.config.policy), ...agentOverrides[toolName] };
+      } else if (!resolvedAgentKid && this.config.multiAgent.unknownAgentPolicy === "deny") {
+        this.emitDecisionLog({ tool: toolName, decision: "deny", reason_code: "unknown_agent_denied", request_id: requestId, tier: this.currentTier });
+        if (this.config.enforce) {
+          return this.makeErrorResponse(request.id, -32600, `Tool "${toolName}" denied: unidentified agent`);
+        }
+        return null;
+      } else {
+        effectiveToolPolicy = getToolPolicy(toolName, this.config.policy);
+      }
+      if (this.config.verbose && resolvedAgentKid) {
+        this.log(`Multi-agent: resolved kid=${resolvedAgentKid} for tool=${toolName}`);
+      }
+    } else {
+      effectiveToolPolicy = getToolPolicy(toolName, this.config.policy);
+    }
+    const toolPolicy = effectiveToolPolicy;
     let credentialRef;
     if (this.config.credentials) {
       const cred = resolveCredential(toolName, this.config.credentials);
@@ -3772,6 +3971,137 @@ var ProtectGateway = class {
   }
 };
 
+// src/simulate.ts
+var import_node_fs6 = require("fs");
+function parseLogFile(path) {
+  const raw = (0, import_node_fs6.readFileSync)(path, "utf-8");
+  const entries = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const jsonStr = trimmed.replace(/^\[PROTECT_MCP\]\s*/, "");
+    try {
+      const parsed = JSON.parse(jsonStr);
+      if (parsed.tool && parsed.decision) {
+        entries.push(parsed);
+      }
+    } catch {
+    }
+  }
+  return entries;
+}
+function simulate(entries, policy, tier = "unknown") {
+  const rateLimitStore = /* @__PURE__ */ new Map();
+  const toolResults = /* @__PURE__ */ new Map();
+  const totals = {
+    allow: 0,
+    block: 0,
+    rate_limited: 0,
+    require_approval: 0,
+    tier_insufficient: 0
+  };
+  const originalTotals = { allow: 0, deny: 0 };
+  const changes = [];
+  for (const entry of entries) {
+    const toolName = entry.tool;
+    const toolPolicy = getToolPolicy(toolName, policy);
+    if (entry.decision === "allow") {
+      originalTotals.allow++;
+    } else {
+      originalTotals.deny++;
+    }
+    let newDecision;
+    if (toolPolicy.block) {
+      newDecision = "block";
+    } else if (toolPolicy.min_tier && !meetsMinTier(tier, toolPolicy.min_tier)) {
+      newDecision = "tier_insufficient";
+    } else if (toolPolicy.require_approval) {
+      newDecision = "require_approval";
+    } else if (toolPolicy.rate_limit) {
+      const limit = parseRateLimit(toolPolicy.rate_limit);
+      const result = checkRateLimit(toolName, limit, rateLimitStore);
+      newDecision = result.allowed ? "allow" : "rate_limited";
+    } else {
+      newDecision = "allow";
+    }
+    totals[newDecision]++;
+    if (!toolResults.has(toolName)) {
+      toolResults.set(toolName, {
+        tool: toolName,
+        calls: 0,
+        results: { allow: 0, block: 0, rate_limited: 0, require_approval: 0, tier_insufficient: 0 },
+        original: { allow: 0, deny: 0 }
+      });
+    }
+    const tr = toolResults.get(toolName);
+    tr.calls++;
+    tr.results[newDecision]++;
+    if (entry.decision === "allow") {
+      tr.original.allow++;
+    } else {
+      tr.original.deny++;
+    }
+  }
+  for (const [tool, result] of toolResults) {
+    const wasAllBlocked = result.original.allow === 0;
+    const nowAllBlocked = result.results.allow === 0;
+    const wasAllAllowed = result.original.deny === 0;
+    if (wasAllAllowed && result.results.block > 0) {
+      changes.push(`${tool}: ${result.results.block} calls would be blocked (was: all allowed)`);
+    }
+    if (wasAllAllowed && result.results.rate_limited > 0) {
+      changes.push(`${tool}: ${result.results.rate_limited} calls would be rate-limited (was: all allowed)`);
+    }
+    if (wasAllAllowed && result.results.require_approval > 0) {
+      changes.push(`${tool}: ${result.results.require_approval} calls would require approval (was: all allowed)`);
+    }
+    if (wasAllAllowed && result.results.tier_insufficient > 0) {
+      changes.push(`${tool}: ${result.results.tier_insufficient} calls would fail tier check (was: all allowed)`);
+    }
+    if (wasAllBlocked && result.results.allow > 0 && !nowAllBlocked) {
+      changes.push(`${tool}: ${result.results.allow} calls would now be allowed (was: all blocked)`);
+    }
+  }
+  return {
+    policy_file: "",
+    log_file: "",
+    total_calls: entries.length,
+    results: totals,
+    original: originalTotals,
+    tool_breakdown: Array.from(toolResults.values()).sort((a, b) => b.calls - a.calls),
+    changes
+  };
+}
+function formatSimulation(summary) {
+  const lines = [];
+  lines.push(`Simulating ${summary.policy_file} against ${summary.total_calls} recorded tool calls:
+`);
+  const maxToolLen = Math.max(...summary.tool_breakdown.map((t) => t.tool.length), 4);
+  for (const tr of summary.tool_breakdown) {
+    const parts = [];
+    if (tr.results.allow > 0) parts.push(`${tr.results.allow} allow`);
+    if (tr.results.block > 0) parts.push(`\x1B[31m${tr.results.block} blocked\x1B[0m`);
+    if (tr.results.rate_limited > 0) parts.push(`\x1B[33m${tr.results.rate_limited} rate_limited\x1B[0m`);
+    if (tr.results.require_approval > 0) parts.push(`\x1B[36m${tr.results.require_approval} require_approval\x1B[0m`);
+    if (tr.results.tier_insufficient > 0) parts.push(`\x1B[35m${tr.results.tier_insufficient} tier_insufficient\x1B[0m`);
+    const originalParts = [];
+    if (tr.original.allow > 0) originalParts.push(`${tr.original.allow} allow`);
+    if (tr.original.deny > 0) originalParts.push(`${tr.original.deny} deny`);
+    lines.push(`  ${tr.tool.padEnd(maxToolLen)}  \xD7 ${String(tr.calls).padStart(3)} \u2192 ${parts.join(", ")}  (was: ${originalParts.join(", ")})`);
+  }
+  lines.push("");
+  lines.push(`Summary: ${summary.results.allow} allow, ${summary.results.block} blocked, ${summary.results.rate_limited} rate_limited, ${summary.results.require_approval} require_approval, ${summary.results.tier_insufficient} tier_insufficient`);
+  lines.push(`  vs original: ${summary.original.allow} allow, ${summary.original.deny} deny`);
+  if (summary.changes.length > 0) {
+    lines.push("");
+    lines.push("Changes:");
+    for (const change of summary.changes) {
+      lines.push(`  \u2022 ${change}`);
+    }
+  }
+  return lines.join("\n");
+}
+
 // src/cli.ts
 function printHelp() {
   process.stderr.write(`
@@ -3779,12 +4109,16 @@ protect-mcp \u2014 Shadow-mode security gateway for MCP servers
 
 Usage:
   protect-mcp [options] -- <command> [args...]
+  protect-mcp quickstart
   protect-mcp init [--dir <path>]
   protect-mcp demo
+  protect-mcp trace <receipt_id> [--endpoint <url>] [--depth <n>]
   protect-mcp status [--dir <path>]
   protect-mcp digest [--today] [--dir <path>]
   protect-mcp receipts [--last <n>] [--dir <path>]
   protect-mcp bundle [--output <path>] [--dir <path>]
+  protect-mcp simulate --policy <path> [--log <path>] [--tier <tier>] [--json]
+  protect-mcp report [--period <days>d] [--format md|json] [--output <path>] [--dir <path>]
 
 Options:
   --policy <path>   Policy/config JSON file (default: allow-all)
@@ -3794,19 +4128,22 @@ Options:
   --help            Show this help
 
 Commands:
+  quickstart        Zero-config onboarding: init + demo + show receipts in one command
   init              Generate config template, Ed25519 keypair, and sample policy
   demo              Start a demo server wrapped with protect-mcp (see receipts instantly)
+  trace <id>        Visualize the receipt DAG from a given receipt_id (ASCII tree)
   status            Show tool call statistics from the local decision log
   digest            Generate a human-readable summary of agent activity
   receipts          Show recent persisted signed receipts
   bundle            Export an offline-verifiable audit bundle
 
 Examples:
+  protect-mcp quickstart
   protect-mcp -- node my-server.js
   protect-mcp --policy protect-mcp.json -- node my-server.js
-  protect-mcp --policy protect-mcp.json --enforce -- node my-server.js
   protect-mcp init
   protect-mcp demo
+  protect-mcp trace sha256:abc123 --depth 5
   protect-mcp status
   protect-mcp digest --today
   protect-mcp receipts --last 10
@@ -3854,7 +4191,7 @@ function parseArgs(argv) {
   return { policyPath, slug, enforce, verbose, childCommand };
 }
 async function handleInit(argv) {
-  const { writeFileSync: writeFileSync2, existsSync: existsSync4, mkdirSync } = await import("fs");
+  const { writeFileSync: writeFileSync2, existsSync: existsSync5, mkdirSync } = await import("fs");
   const { join: join4 } = await import("path");
   let dir = process.cwd();
   const dirIdx = argv.indexOf("--dir");
@@ -3864,17 +4201,14 @@ async function handleInit(argv) {
   const configPath = join4(dir, "protect-mcp.json");
   const keysDir = join4(dir, "keys");
   const keyPath = join4(keysDir, "gateway.json");
-  if (existsSync4(configPath)) {
+  if (existsSync5(configPath)) {
     process.stderr.write(`[PROTECT_MCP] Config already exists at ${configPath}
 `);
     process.stderr.write("[PROTECT_MCP] Delete it first if you want to regenerate.\n");
     process.exit(1);
   }
   let keypair;
-  try {
-    const artifacts = await import("@veritasacta/artifacts");
-    keypair = artifacts.generateKeypair();
-  } catch {
+  {
     const { randomBytes: randomBytes3 } = await import("crypto");
     const { ed25519: ed255192 } = await Promise.resolve().then(() => (init_ed25519(), ed25519_exports));
     const { bytesToHex: bytesToHex2 } = await Promise.resolve().then(() => (init_utils(), utils_exports));
@@ -3886,7 +4220,7 @@ async function handleInit(argv) {
       kid: "generated"
     };
   }
-  if (!existsSync4(keysDir)) {
+  if (!existsSync5(keysDir)) {
     mkdirSync(keysDir, { recursive: true });
   }
   writeFileSync2(keyPath, JSON.stringify({
@@ -3897,7 +4231,7 @@ async function handleInit(argv) {
     warning: "KEEP THIS FILE SECRET. Never commit to version control."
   }, null, 2) + "\n");
   const gitignorePath = join4(keysDir, ".gitignore");
-  if (!existsSync4(gitignorePath)) {
+  if (!existsSync5(gitignorePath)) {
     writeFileSync2(gitignorePath, "# Never commit signing keys\n*.json\n");
   }
   const config = {
@@ -3970,13 +4304,13 @@ Add --enforce when ready to block policy violations.
 `);
 }
 async function handleDemo() {
-  const { existsSync: existsSync4 } = await import("fs");
+  const { existsSync: existsSync5 } = await import("fs");
   const { join: join4, dirname, resolve } = await import("path");
   const cliPath = resolve(process.argv[1] || "dist/cli.js");
   const cliDir = dirname(cliPath);
   const demoServerPath = join4(cliDir, "demo-server.js");
   const configPath = join4(process.cwd(), "protect-mcp.json");
-  const hasConfig = existsSync4(configPath);
+  const hasConfig = existsSync5(configPath);
   if (!hasConfig) {
     process.stderr.write(`
 ${bold("protect-mcp demo")}
@@ -4050,7 +4384,7 @@ Starting demo server with 5 tools...
   await gateway.start();
 }
 async function handleStatus2(argv) {
-  const { readFileSync: readFileSync5, existsSync: existsSync4 } = await import("fs");
+  const { readFileSync: readFileSync7, existsSync: existsSync5 } = await import("fs");
   const { join: join4 } = await import("path");
   let dir = process.cwd();
   const dirIdx = argv.indexOf("--dir");
@@ -4058,7 +4392,7 @@ async function handleStatus2(argv) {
     dir = argv[dirIdx + 1];
   }
   const logPath = join4(dir, ".protect-mcp-log.jsonl");
-  if (!existsSync4(logPath)) {
+  if (!existsSync5(logPath)) {
     process.stderr.write(`${bold("protect-mcp status")}
 
 `);
@@ -4068,7 +4402,7 @@ async function handleStatus2(argv) {
 `);
     process.exit(0);
   }
-  const raw = readFileSync5(logPath, "utf-8");
+  const raw = readFileSync7(logPath, "utf-8");
   const lines = raw.trim().split("\n").filter(Boolean);
   if (lines.length === 0) {
     process.stderr.write(`${bold("protect-mcp status")}
@@ -4148,9 +4482,9 @@ ${bold("protect-mcp status")}
 `);
   }
   const evidencePath = join4(dir, ".protect-mcp-evidence.json");
-  if (existsSync4(evidencePath)) {
+  if (existsSync5(evidencePath)) {
     try {
-      const evidenceRaw = readFileSync5(evidencePath, "utf-8");
+      const evidenceRaw = readFileSync7(evidencePath, "utf-8");
       const evidence = JSON.parse(evidenceRaw);
       const agentCount = Object.keys(evidence.agents || {}).length;
       process.stdout.write(`
@@ -4160,9 +4494,9 @@ ${bold("protect-mcp status")}
     }
   }
   const keyPath = join4(dir, "keys", "gateway.json");
-  if (existsSync4(keyPath)) {
+  if (existsSync5(keyPath)) {
     try {
-      const keyData = JSON.parse(readFileSync5(keyPath, "utf-8"));
+      const keyData = JSON.parse(readFileSync7(keyPath, "utf-8"));
       if (keyData.publicKey) {
         const fingerprint = keyData.publicKey.slice(0, 16) + "...";
         process.stdout.write(`
@@ -4201,21 +4535,21 @@ function yellow(s) {
   return process.env.NO_COLOR ? s : `\x1B[33m${s}\x1B[0m`;
 }
 async function handleDigest(argv) {
-  const { readFileSync: readFileSync5, existsSync: existsSync4 } = await import("fs");
+  const { readFileSync: readFileSync7, existsSync: existsSync5 } = await import("fs");
   const { join: join4 } = await import("path");
   let dir = process.cwd();
   const dirIdx = argv.indexOf("--dir");
   if (dirIdx !== -1 && argv[dirIdx + 1]) dir = argv[dirIdx + 1];
   const today = argv.includes("--today");
   const logPath = join4(dir, ".protect-mcp-log.jsonl");
-  if (!existsSync4(logPath)) {
+  if (!existsSync5(logPath)) {
     process.stderr.write(`${bold("protect-mcp digest")}
 
 No log file found. Run protect-mcp first.
 `);
     process.exit(0);
   }
-  const raw = readFileSync5(logPath, "utf-8");
+  const raw = readFileSync7(logPath, "utf-8");
   const lines = raw.trim().split("\n").filter(Boolean);
   let entries = [];
   for (const line of lines) {
@@ -4292,7 +4626,7 @@ ${bold("\u{1F6E1}\uFE0F Agent Daily Digest")}
 `);
 }
 async function handleReceipts2(argv) {
-  const { readFileSync: readFileSync5, existsSync: existsSync4 } = await import("fs");
+  const { readFileSync: readFileSync7, existsSync: existsSync5 } = await import("fs");
   const { join: join4 } = await import("path");
   let dir = process.cwd();
   const dirIdx = argv.indexOf("--dir");
@@ -4300,14 +4634,14 @@ async function handleReceipts2(argv) {
   const lastIdx = argv.indexOf("--last");
   const count = lastIdx !== -1 && argv[lastIdx + 1] ? parseInt(argv[lastIdx + 1], 10) : 20;
   const receiptsPath = join4(dir, ".protect-mcp-receipts.jsonl");
-  if (!existsSync4(receiptsPath)) {
+  if (!existsSync5(receiptsPath)) {
     process.stderr.write(`${bold("protect-mcp receipts")}
 
 No signed receipt file found. Run protect-mcp with signing enabled first.
 `);
     process.exit(0);
   }
-  const raw = readFileSync5(receiptsPath, "utf-8");
+  const raw = readFileSync7(receiptsPath, "utf-8");
   const lines = raw.trim().split("\n").filter(Boolean);
   const recent = lines.slice(-count);
   process.stdout.write(`
@@ -4330,7 +4664,7 @@ ${bold("\u{1F6E1}\uFE0F Recent Receipts")} (last ${recent.length})
 `);
 }
 async function handleBundle(argv) {
-  const { readFileSync: readFileSync5, writeFileSync: writeFileSync2, existsSync: existsSync4 } = await import("fs");
+  const { readFileSync: readFileSync7, writeFileSync: writeFileSync2, existsSync: existsSync5 } = await import("fs");
   const { join: join4 } = await import("path");
   const { createAuditBundle: createAuditBundle2 } = await Promise.resolve().then(() => (init_bundle(), bundle_exports));
   let dir = process.cwd();
@@ -4340,22 +4674,22 @@ async function handleBundle(argv) {
   const outputPath = outputIdx !== -1 && argv[outputIdx + 1] ? argv[outputIdx + 1] : join4(dir, "audit-bundle.json");
   const receiptsPath = join4(dir, ".protect-mcp-receipts.jsonl");
   const keyPath = join4(dir, "keys", "gateway.json");
-  if (!existsSync4(receiptsPath)) {
+  if (!existsSync5(receiptsPath)) {
     process.stderr.write(`${bold("protect-mcp bundle")}
 
 No signed receipt file found. Run protect-mcp with signing enabled first.
 `);
     process.exit(0);
   }
-  if (!existsSync4(keyPath)) {
+  if (!existsSync5(keyPath)) {
     process.stderr.write(`${bold("protect-mcp bundle")}
 
 No key file found at ${keyPath}
 `);
     process.exit(1);
   }
-  const receipts = readFileSync5(receiptsPath, "utf-8").trim().split("\n").filter(Boolean).map((line) => JSON.parse(line));
-  const keyData = JSON.parse(readFileSync5(keyPath, "utf-8"));
+  const receipts = readFileSync7(receiptsPath, "utf-8").trim().split("\n").filter(Boolean).map((line) => JSON.parse(line));
+  const keyData = JSON.parse(readFileSync7(keyPath, "utf-8"));
   const bundle = createAuditBundle2({
     tenant: keyData.issuer || "protect-mcp",
     receipts,
@@ -4380,12 +4714,322 @@ ${bold("protect-mcp bundle")}
 
 `);
 }
+async function handleQuickstart() {
+  const { mkdtempSync, writeFileSync: writeFileSync2, existsSync: existsSync5, mkdirSync, readFileSync: readFileSync7 } = await import("fs");
+  const { join: join4 } = await import("path");
+  const { tmpdir } = await import("os");
+  const dir = mkdtempSync(join4(tmpdir(), "protect-mcp-quickstart-"));
+  process.stdout.write(`
+${bold("protect-mcp quickstart")}
+`);
+  process.stdout.write(`${"\u2500".repeat(50)}
+
+`);
+  process.stdout.write(`  This will:
+`);
+  process.stdout.write(`  1. Generate an Ed25519 signing keypair
+`);
+  process.stdout.write(`  2. Create a shadow-mode policy
+`);
+  process.stdout.write(`  3. Start a demo MCP server with protect-mcp wrapping it
+`);
+  process.stdout.write(`  4. Log signed receipts for every tool call
+
+`);
+  process.stdout.write(`  Working dir: ${dir}
+
+`);
+  const keysDir = join4(dir, "keys");
+  mkdirSync(keysDir, { recursive: true });
+  const { randomBytes: randomBytes3 } = await import("crypto");
+  let keypair;
+  try {
+    const { ed25519: ed255192 } = await Promise.resolve().then(() => (init_ed25519(), ed25519_exports));
+    const { bytesToHex: bytesToHex2 } = await Promise.resolve().then(() => (init_utils(), utils_exports));
+    const privateKey = randomBytes3(32);
+    const publicKey = ed255192.getPublicKey(privateKey);
+    keypair = {
+      privateKey: bytesToHex2(privateKey),
+      publicKey: bytesToHex2(publicKey),
+      kid: `quickstart-${Date.now()}`
+    };
+  } catch {
+    keypair = {
+      privateKey: randomBytes3(32).toString("hex"),
+      publicKey: randomBytes3(32).toString("hex"),
+      kid: `quickstart-${Date.now()}`
+    };
+  }
+  writeFileSync2(join4(keysDir, "gateway.json"), JSON.stringify({
+    privateKey: keypair.privateKey,
+    publicKey: keypair.publicKey,
+    kid: keypair.kid,
+    generated_at: (/* @__PURE__ */ new Date()).toISOString()
+  }, null, 2) + "\n");
+  const configPath = join4(dir, "protect-mcp.json");
+  const config = {
+    tools: {
+      "*": { rate_limit: "100/hour" },
+      "delete_file": { block: true }
+    },
+    default_tier: "unknown",
+    signing: {
+      key_path: join4(keysDir, "gateway.json"),
+      issuer: "protect-mcp-quickstart",
+      enabled: true
+    }
+  };
+  writeFileSync2(configPath, JSON.stringify(config, null, 2) + "\n");
+  process.stdout.write(`  \u2713 Keypair generated (kid: ${keypair.kid})
+`);
+  process.stdout.write(`  \u2713 Policy created (shadow mode, all tools logged)
+`);
+  process.stdout.write(`  \u2713 Signing enabled (Ed25519)
+
+`);
+  process.stdout.write(`${bold("Starting demo server...")}
+
+`);
+  process.stdout.write(`  Every tool call will produce a signed receipt.
+`);
+  process.stdout.write(`  Try it with Claude Desktop or any MCP client.
+
+`);
+  process.stdout.write(`  ${bold("To use in production:")}
+`);
+  process.stdout.write(`    1. Copy ${configPath} to your project
+`);
+  process.stdout.write(`    2. Edit tool policies to match your server
+`);
+  process.stdout.write(`    3. Run: protect-mcp --policy protect-mcp.json -- node your-server.js
+
+`);
+  process.stdout.write(`${"\u2500".repeat(50)}
+
+`);
+  process.env.PROTECT_MCP_CONFIG = configPath;
+  await handleDemo();
+}
+async function handleTrace(argv) {
+  const receiptId = argv[0];
+  if (!receiptId) {
+    process.stderr.write("[PROTECT_MCP] Usage: protect-mcp trace <receipt_id> [--endpoint <url>] [--depth <n>]\n");
+    process.exit(1);
+  }
+  let endpoint = "https://evidence-indexer.tomjwxf.workers.dev";
+  let depth = 3;
+  for (let i = 1; i < argv.length; i++) {
+    if (argv[i] === "--endpoint" && argv[i + 1]) {
+      endpoint = argv[++i];
+    } else if (argv[i] === "--depth" && argv[i + 1]) {
+      depth = Math.min(10, Math.max(1, parseInt(argv[++i], 10) || 3));
+    }
+  }
+  process.stdout.write(`
+${bold("protect-mcp trace")}
+`);
+  process.stdout.write(`${"\u2500".repeat(60)}
+
+`);
+  process.stdout.write(`  Root:     ${receiptId}
+`);
+  process.stdout.write(`  Endpoint: ${endpoint}
+`);
+  process.stdout.write(`  Depth:    ${depth}
+
+`);
+  const url = `${endpoint}/evidence/graph/${encodeURIComponent(receiptId)}?depth=${depth}&direction=both&max=50`;
+  let graphData;
+  try {
+    const resp = await fetch(url);
+    if (!resp.ok) {
+      const body = await resp.text();
+      process.stderr.write(`[PROTECT_MCP] Error fetching graph: ${resp.status} ${body}
+`);
+      process.exit(1);
+    }
+    graphData = await resp.json();
+  } catch (err) {
+    process.stderr.write(`[PROTECT_MCP] Could not reach evidence indexer at ${endpoint}
+`);
+    process.stderr.write(`[PROTECT_MCP] Trying local receipts...
+
+`);
+    await traceLocal(receiptId);
+    return;
+  }
+  if (!graphData.nodes || graphData.nodes.length === 0) {
+    process.stdout.write(`  No receipts found for ${receiptId}
+
+`);
+    return;
+  }
+  process.stdout.write(`  ${bold("Evidence DAG")} (${graphData.node_count} nodes, ${graphData.edge_count} edges)
+
+`);
+  const nodeMap = /* @__PURE__ */ new Map();
+  for (const node of graphData.nodes) {
+    nodeMap.set(node.receipt_id, node);
+  }
+  const childMap = /* @__PURE__ */ new Map();
+  for (const edge of graphData.edges) {
+    if (!childMap.has(edge.from)) childMap.set(edge.from, []);
+    childMap.get(edge.from).push({ to: edge.to, relation: edge.relation });
+  }
+  const rendered = /* @__PURE__ */ new Set();
+  function renderNode(id, prefix, isLast) {
+    const node = nodeMap.get(id);
+    const connector = isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+    const childPrefix = isLast ? "    " : "\u2502   ";
+    const typeEmoji = getTypeEmoji(node?.receipt_type || "unknown");
+    const shortId = id.length > 16 ? id.slice(0, 12) + "\u2026" : id;
+    const time = node?.event_time ? new Date(node.event_time).toLocaleTimeString() : "?";
+    const type = node?.receipt_type?.replace("acta:", "") || "unknown";
+    process.stdout.write(`${prefix}${connector}${typeEmoji} ${bold(type)} ${dim(shortId)} ${dim(time)}
+`);
+    if (rendered.has(id)) {
+      process.stdout.write(`${prefix}${childPrefix}${dim("(cycle \u2014 already rendered)")}
+`);
+      return;
+    }
+    rendered.add(id);
+    const children = childMap.get(id) || [];
+    for (let i = 0; i < children.length; i++) {
+      const child = children[i];
+      const edgeLabel = dim(`\u2500\u2500[${child.relation}]\u2500\u2500\u25B6`);
+      process.stdout.write(`${prefix}${childPrefix}${edgeLabel}
+`);
+      renderNode(child.to, prefix + childPrefix, i === children.length - 1);
+    }
+  }
+  const rootNode = nodeMap.get(receiptId);
+  if (rootNode) {
+    const typeEmoji = getTypeEmoji(rootNode.receipt_type);
+    const type = rootNode.receipt_type?.replace("acta:", "") || "unknown";
+    const time = rootNode.event_time ? new Date(rootNode.event_time).toLocaleTimeString() : "?";
+    process.stdout.write(`  ${typeEmoji} ${bold(type)} ${dim(receiptId.slice(0, 16) + "\u2026")} ${dim(time)} ${bold("(root)")}
+`);
+    rendered.add(receiptId);
+    const children = childMap.get(receiptId) || [];
+    for (let i = 0; i < children.length; i++) {
+      const child = children[i];
+      const edgeLabel = dim(`\u2500\u2500[${child.relation}]\u2500\u2500\u25B6`);
+      process.stdout.write(`  ${edgeLabel}
+`);
+      renderNode(child.to, "  ", i === children.length - 1);
+    }
+    const incomingEdges = (graphData.edges || []).filter((e) => e.to === receiptId);
+    if (incomingEdges.length > 0) {
+      process.stdout.write(`
+  ${bold("Incoming edges:")}
+`);
+      for (const edge of incomingEdges) {
+        const fromNode = nodeMap.get(edge.from);
+        const fromType = fromNode?.receipt_type?.replace("acta:", "") || "unknown";
+        process.stdout.write(`  \u25C0\u2500\u2500[${edge.relation}]\u2500\u2500 ${getTypeEmoji(fromNode?.receipt_type)} ${fromType} ${dim(edge.from.slice(0, 16) + "\u2026")}
+`);
+      }
+    }
+  } else {
+    for (const node of graphData.nodes) {
+      const typeEmoji = getTypeEmoji(node.receipt_type);
+      const type = node.receipt_type?.replace("acta:", "") || "unknown";
+      process.stdout.write(`  ${typeEmoji} ${bold(type)} ${dim(node.receipt_id.slice(0, 16) + "\u2026")}
+`);
+    }
+  }
+  process.stdout.write(`
+${"\u2500".repeat(60)}
+`);
+  process.stdout.write(`  ${dim(`Fetched from ${endpoint}`)}
+
+`);
+}
+async function traceLocal(receiptId) {
+  const { readFileSync: readFileSync7, existsSync: existsSync5 } = await import("fs");
+  const { join: join4 } = await import("path");
+  const dir = process.cwd();
+  const receiptsDir = join4(dir, ".protect-mcp", "receipts");
+  if (!existsSync5(receiptsDir)) {
+    process.stdout.write(`  No local receipts found in ${receiptsDir}
+
+`);
+    return;
+  }
+  const { readdirSync } = await import("fs");
+  const files = readdirSync(receiptsDir).filter((f) => f.endsWith(".json"));
+  process.stdout.write(`  Scanning ${files.length} local receipts...
+
+`);
+  const receipts = [];
+  for (const file of files) {
+    try {
+      const content = readFileSync7(join4(receiptsDir, file), "utf-8");
+      const receipt = JSON.parse(content);
+      receipts.push(receipt);
+    } catch {
+    }
+  }
+  const match = receipts.find(
+    (r) => r.signed_claims?.claims?.receipt_id === receiptId || r.receipt_id === receiptId
+  );
+  if (match) {
+    const claims = match.signed_claims?.claims || match;
+    process.stdout.write(`  Found: ${getTypeEmoji(claims.receipt_type)} ${bold(claims.receipt_type?.replace("acta:", "") || "unknown")}
+`);
+    process.stdout.write(`  Event:  ${claims.event_id || "?"}
+`);
+    process.stdout.write(`  Issuer: ${claims.issuer_id || "?"}
+`);
+    process.stdout.write(`  Time:   ${claims.event_time || "?"}
+`);
+    if (claims.edges && claims.edges.length > 0) {
+      process.stdout.write(`
+  ${bold("Edges:")}
+`);
+      for (const edge of claims.edges) {
+        process.stdout.write(`    \u2500\u2500[${edge.relation}]\u2500\u2500\u25B6 ${dim(edge.receipt_id?.slice(0, 16) + "\u2026")}
+`);
+      }
+    }
+  } else {
+    process.stdout.write(`  Receipt ${receiptId} not found locally.
+`);
+  }
+  process.stdout.write("\n");
+}
+function getTypeEmoji(type) {
+  switch (type) {
+    case "acta:observation":
+      return "\u{1F441} ";
+    case "acta:policy-load":
+      return "\u{1F4CB}";
+    case "acta:approval":
+      return "\u2705";
+    case "acta:decision":
+      return "\u2696\uFE0F ";
+    case "acta:execution":
+      return "\u26A1";
+    case "acta:outcome":
+      return "\u{1F4E6}";
+    case "acta:delegation":
+      return "\u{1F91D}";
+    case "acta:capability-attestation":
+      return "\u{1F3C5}";
+    default:
+      return "\u{1F4C4}";
+  }
+}
 async function main() {
   const args = process.argv.slice(2);
   if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
     printHelp();
     process.exit(0);
   }
+  if (args[0] === "quickstart") {
+    await handleQuickstart();
+    return;
+  }
   if (args[0] === "init") {
     await handleInit(args.slice(1));
     process.exit(0);
@@ -4410,6 +5054,18 @@ async function main() {
     await handleBundle(args.slice(1));
     process.exit(0);
   }
+  if (args[0] === "trace") {
+    await handleTrace(args.slice(1));
+    process.exit(0);
+  }
+  if (args[0] === "simulate") {
+    await handleSimulate(args.slice(1));
+    process.exit(0);
+  }
+  if (args[0] === "report") {
+    await handleReport(args.slice(1));
+    process.exit(0);
+  }
   const { policyPath, slug, enforce, verbose, childCommand } = parseArgs(args);
   let policy = null;
   let policyDigest = "none";
@@ -4460,6 +5116,85 @@ async function main() {
   const gateway = new ProtectGateway(config);
   await gateway.start();
 }
+async function handleSimulate(args) {
+  let policyPath = "";
+  let logPath = ".protect-mcp-log.jsonl";
+  let tier = "unknown";
+  let jsonOutput = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--policy" && args[i + 1]) {
+      policyPath = args[++i];
+    } else if (args[i] === "--log" && args[i + 1]) {
+      logPath = args[++i];
+    } else if (args[i] === "--tier" && args[i + 1]) {
+      tier = args[++i];
+    } else if (args[i] === "--json") {
+      jsonOutput = true;
+    }
+  }
+  if (!policyPath) {
+    process.stderr.write("Usage: protect-mcp simulate --policy <path> [--log <path>] [--tier <tier>] [--json]\n");
+    process.exit(1);
+  }
+  const { existsSync: existsSync5 } = await import("fs");
+  if (!existsSync5(logPath)) {
+    process.stderr.write(`Log file not found: ${logPath}
+`);
+    process.stderr.write("Run protect-mcp in shadow mode first to generate a log file.\n");
+    process.exit(1);
+  }
+  const { policy } = loadPolicy(policyPath);
+  const entries = parseLogFile(logPath);
+  if (entries.length === 0) {
+    process.stderr.write("No tool call entries found in log file.\n");
+    process.exit(1);
+  }
+  const summary = simulate(entries, policy, tier);
+  summary.policy_file = policyPath;
+  summary.log_file = logPath;
+  if (jsonOutput) {
+    process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
+  } else {
+    process.stdout.write(formatSimulation(summary) + "\n");
+  }
+}
+async function handleReport(args) {
+  let period = 30;
+  let format = "json";
+  let outputPath = "";
+  let dir = process.cwd();
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--period" && args[i + 1]) {
+      const match = args[++i].match(/^(\d+)d$/);
+      if (match) period = parseInt(match[1], 10);
+    } else if (args[i] === "--format" && args[i + 1]) {
+      format = args[++i];
+    } else if (args[i] === "--output" && args[i + 1]) {
+      outputPath = args[++i];
+    } else if (args[i] === "--dir" && args[i + 1]) {
+      dir = args[++i];
+    }
+  }
+  const { generateReport: generateReport2, formatReportMarkdown: formatReportMarkdown2 } = await Promise.resolve().then(() => (init_report(), report_exports));
+  const { join: join4 } = await import("path");
+  const logPath = join4(dir, ".protect-mcp-log.jsonl");
+  const receiptPath = join4(dir, ".protect-mcp-receipts.jsonl");
+  const report = generateReport2(logPath, receiptPath, period);
+  let output;
+  if (format === "md") {
+    output = formatReportMarkdown2(report);
+  } else {
+    output = JSON.stringify(report, null, 2);
+  }
+  if (outputPath) {
+    const { writeFileSync: writeFileSync2 } = await import("fs");
+    writeFileSync2(outputPath, output, "utf-8");
+    process.stderr.write(`Report written to ${outputPath}
+`);
+  } else {
+    process.stdout.write(output + "\n");
+  }
+}
 main().catch((err) => {
   process.stderr.write(`[PROTECT_MCP] Fatal error: ${err instanceof Error ? err.message : err}
 `);