protect-mcp 0.6.0 → 0.6.3

package/README.md

@@ -8,6 +8,11 @@
 > A policy check that sits between your AI agent and the tools it calls.
 > Every tool call is evaluated against a rule you wrote. Every decision is signed.
 
+> **Receipt format:** `protect-mcp` emits Veritas Acta receipts. Legacy
+> ScopeBlind receipts remain verifiable, but Acta v0.1 is the canonical
+> format going forward. Spec: [`@veritasacta/protocol`](https://www.npmjs.com/package/@veritasacta/protocol)
+> · IETF: [draft-farley-acta-signed-receipts](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/).
+
 ## What it does, in plain English
 
 When an AI agent (Claude Code, Cursor, a custom LangChain app, anything that
@@ -335,6 +340,42 @@ Free tier: 20,000 receipts/month. No credit card required.
 
 [scopeblind.com/pricing](https://scopeblind.com/pricing)
 
+### ScopeBlind tenant integration (Founding Plan)
+
+If you have a ScopeBlind Founding Plan tenant, set your `SCOPEBLIND_TOKEN`
+(from the welcome email) in the environment and protect-mcp forwards every
+signed receipt to your dashboard at `https://scopeblind.com/console/<your-slug>`.
+
+```bash
+# Your protect-mcp install with cloud-synced receipts
+SCOPEBLIND_TOKEN=scp_... \
+  npx protect-mcp init-hooks
+```
+
+How it works:
+
+1. On first receipt, the bridge exchanges your token for a short-lived BRASS-v2
+   auth proof at `/fn/brass/issue` (ECDSA P-256 signed, hourly expiry).
+2. Receipts are batched and POSTed to `/fn/console/<slug>/receipts` every 5
+   seconds (up to 128 per batch).
+3. The local `.receipts/` chain remains authoritative regardless of forward
+   status. Network failures are retried; quota exhaustion is reported. No
+   crash, no blocking.
+
+Quota: founding tier 10,000 receipts/day, enterprise 100,000/day. Anything
+above quota is rejected with a structured response; receipts stay safe in
+`.receipts/` until you upgrade or until tomorrow.
+
+Receipt verification by third parties:
+
+```bash
+# Anyone can verify your receipts offline using the public JWKS
+curl https://scopeblind.com/.well-known/jwks.json
+npx @veritasacta/verify .receipts/0001.json
+```
+
+Verification is independent of ScopeBlind — the math doesn't care who runs it.
+
 ## Interoperability
 
 The receipt format is independently implemented and verified across multiple systems:
@@ -344,7 +385,7 @@ The receipt format is independently implemented and verified across multiple sys
 | **4 independent implementations** | TypeScript (protect-mcp), Python (protect-mcp-adk), Rust (Cedar WASM), APS ProxyGateway |
 | **2 IETF Internet-Drafts** | [draft-farley-acta-signed-receipts-01](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/), [draft-pidlisnyi-aps-00](https://datatracker.ietf.org/doc/draft-pidlisnyi-aps/) |
 | **8 cross-engine receipts** | [Composition test](https://github.com/ScopeBlind/examples/tree/main/interop/composition-test): 2 engines, 1 verifier, all VALID |
-| **3 enterprise integrations** | Microsoft AGT [#667](https://github.com/microsoft/agent-governance-toolkit/pull/667), [#1159](https://github.com/microsoft/agent-governance-toolkit/pull/1159), [#1168](https://github.com/microsoft/agent-governance-toolkit/pull/1168) |
+| **PRs merged into microsoft/agent-governance-toolkit** | [#667](https://github.com/microsoft/agent-governance-toolkit/pull/667), [#1159](https://github.com/microsoft/agent-governance-toolkit/pull/1159), [#1168](https://github.com/microsoft/agent-governance-toolkit/pull/1168), [#1186](https://github.com/microsoft/agent-governance-toolkit/pull/1186), [#1197](https://github.com/microsoft/agent-governance-toolkit/pull/1197), [#1202](https://github.com/microsoft/agent-governance-toolkit/pull/1202), [#1203](https://github.com/microsoft/agent-governance-toolkit/pull/1203), [#1205](https://github.com/microsoft/agent-governance-toolkit/pull/1205) |
 | **1 verifier, zero dependencies** | `npx @veritasacta/verify receipt.json --key <hex>` (Apache-2.0, offline) |
 
 Verify any receipt from any implementation:

package/dist/{chunk-SPHLVRJ2.mjs → chunk-3YCKR72H.mjs}

@@ -11,13 +11,166 @@ import {
   loadPolicy,
   parseRateLimit,
   signDecision
-} from "./chunk-YTBC72JJ.mjs";
+} from "./chunk-UV53U6D4.mjs";
 
 // src/hook-server.ts
 import { createServer } from "http";
 import { createHash, randomUUID, randomBytes } from "crypto";
 import { appendFileSync, readFileSync, existsSync, readdirSync } from "fs";
 import { join } from "path";
+
+// src/scopeblind-bridge.ts
+var DEFAULT_BASE = "https://scopeblind.com";
+var FLUSH_INTERVAL_MS = 5e3;
+var BATCH_MAX = 128;
+var BRASS_REFRESH_MARGIN_MS = 5 * 60 * 1e3;
+var ScopeBlindBridge = class {
+  token;
+  base;
+  tenantOverride;
+  cachedProof = null;
+  queue = [];
+  flushTimer = null;
+  stats;
+  shuttingDown = false;
+  constructor(env = process.env) {
+    this.token = env.SCOPEBLIND_TOKEN || null;
+    this.base = (env.SCOPEBLIND_BASE || DEFAULT_BASE).replace(/\/$/, "");
+    this.tenantOverride = env.SCOPEBLIND_TENANT || null;
+    this.stats = {
+      enabled: Boolean(this.token),
+      tenant_slug: this.tenantOverride,
+      forwarded_total: 0,
+      rejected_total: 0,
+      last_flush_at: null,
+      last_error: null
+    };
+    if (this.enabled()) {
+      this.flushTimer = setInterval(() => {
+        void this.flush();
+      }, FLUSH_INTERVAL_MS);
+      if (typeof this.flushTimer === "object" && this.flushTimer && "unref" in this.flushTimer) {
+        this.flushTimer.unref?.();
+      }
+      process.on("beforeExit", () => {
+        void this.shutdown();
+      });
+    }
+  }
+  enabled() {
+    return Boolean(this.token);
+  }
+  /** Push a signed receipt into the queue. Non-blocking. */
+  forward(signedReceipt) {
+    if (!this.enabled() || this.shuttingDown) return;
+    this.queue.push(signedReceipt);
+    if (this.queue.length >= BATCH_MAX) void this.flush();
+  }
+  /** Flush the queue. Safe to call concurrently. */
+  async flush() {
+    if (!this.enabled() || this.queue.length === 0) return;
+    const batch = this.queue.splice(0, BATCH_MAX);
+    try {
+      const proof = await this.ensureBrassProof();
+      const slug = this.tenantOverride || proof?.tenant_id;
+      if (!slug) {
+        this.queue.unshift(...batch);
+        return;
+      }
+      this.stats.tenant_slug = slug;
+      const res = await fetch(`${this.base}/fn/console/${slug}/receipts`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.token}`,
+          "user-agent": "protect-mcp/scopeblind-bridge"
+        },
+        body: JSON.stringify({ receipts: batch })
+      });
+      if (!res.ok) {
+        const errBody = await res.text().catch(() => "");
+        this.stats.last_error = `HTTP ${res.status} ${errBody.slice(0, 160)}`;
+        this.stats.rejected_total += batch.length;
+        if (res.status >= 500 && res.status !== 503) {
+          this.queue.unshift(...batch);
+        }
+        return;
+      }
+      const body = await res.json().catch(() => ({}));
+      this.stats.forwarded_total += body?.accepted ?? batch.length;
+      this.stats.rejected_total += body?.rejected ?? 0;
+      this.stats.last_flush_at = (/* @__PURE__ */ new Date()).toISOString();
+      this.stats.last_error = null;
+    } catch (err) {
+      this.stats.last_error = String(err?.message || err);
+      this.queue.unshift(...batch);
+    }
+  }
+  /** Exchange SCOPEBLIND_TOKEN for a BRASS-v2 proof; refresh near expiry. */
+  async ensureBrassProof() {
+    if (!this.token) return null;
+    const now = Date.now();
+    if (this.cachedProof && Date.parse(this.cachedProof.expires_at) - now > BRASS_REFRESH_MARGIN_MS) {
+      return this.cachedProof;
+    }
+    try {
+      const res = await fetch(`${this.base}/fn/brass/issue`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "user-agent": "protect-mcp/scopeblind-bridge"
+        },
+        body: JSON.stringify({
+          token: this.token,
+          scope: "protect-mcp-receipt-emit",
+          ttl_seconds: 3600
+        })
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        this.stats.last_error = `brass-issue: HTTP ${res.status} ${text.slice(0, 160)}`;
+        return null;
+      }
+      const body = await res.json();
+      if (!body?.auth_proof) {
+        this.stats.last_error = "brass-issue: missing auth_proof in response";
+        return null;
+      }
+      this.cachedProof = body.auth_proof;
+      return this.cachedProof;
+    } catch (err) {
+      this.stats.last_error = `brass-issue: ${err?.message || err}`;
+      return null;
+    }
+  }
+  /**
+   * Return a snapshot of bridge stats. Useful for `protect-mcp scopeblind status`.
+   */
+  getStats() {
+    return {
+      ...this.stats,
+      queued: this.queue.length,
+      brass_proof_expires_at: this.cachedProof?.expires_at || null
+    };
+  }
+  /** Flush remaining receipts and stop the interval. Called on process exit. */
+  async shutdown() {
+    if (this.shuttingDown) return;
+    this.shuttingDown = true;
+    if (this.flushTimer) clearInterval(this.flushTimer);
+    if (this.queue.length > 0) await this.flush();
+  }
+};
+var singleton = null;
+function getScopeBlindBridge() {
+  if (!singleton) singleton = new ScopeBlindBridge();
+  return singleton;
+}
+function forwardReceipt(signedReceipt) {
+  getScopeBlindBridge().forward(signedReceipt);
+}
+
+// src/hook-server.ts
 var DEFAULT_PORT = 9377;
 var LOG_FILE = ".protect-mcp-log.jsonl";
 var RECEIPTS_FILE = ".protect-mcp-receipts.jsonl";
@@ -225,7 +378,7 @@ async function handlePreToolUse(input, state) {
   const hookLatency = Date.now() - hookStart;
   const denyKey = `${toolName}:${input.sessionId || "default"}`;
   state.denyCounter.delete(denyKey);
-  emitDecisionLog(state, {
+  const emit = emitDecisionLog(state, {
     tool: toolName,
     decision: "allow",
     reason_code: state.cedarPolicies ? "cedar_allow" : state.jsonPolicy ? "policy_allow" : "observe_mode",
@@ -237,6 +390,15 @@ async function handlePreToolUse(input, state) {
     sandbox_state: detectSandboxState(),
     plan_receipt_id: state.activePlanReceiptId || void 0
   });
+  if (state.enforce && emit.signingFailed) {
+    return {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: `[ScopeBlind] "${toolName}" was blocked because its receipt could not be signed. Failing closed: a governed action that cannot be proven is not allowed.`
+      }
+    };
+  }
   return {};
 }
 async function handlePostToolUse(input, state) {
@@ -484,11 +646,35 @@ function emitDecisionLog(state, entry) {
       } catch {
       }
       state.receiptBuffer.add(log.request_id, signed.signed);
-    } else if (signed.warning) {
-      process.stderr.write(`[PROTECT_MCP] Warning: ${signed.warning}
+      try {
+        const bridge = getScopeBlindBridge();
+        if (bridge.enabled()) {
+          const parsed = typeof signed.signed === "string" ? JSON.parse(signed.signed) : signed.signed;
+          bridge.forward(parsed);
+        }
+      } catch (err) {
+        process.stderr.write(`[PROTECT_MCP] ScopeBlind forward error: ${err instanceof Error ? err.message : err}
+`);
+      }
+    } else if (signed.error) {
+      const tombstone = JSON.stringify({
+        type: "scopeblind.signing_failure.v1",
+        request_id: log.request_id,
+        tool: log.tool,
+        decision: log.decision,
+        error: signed.error,
+        at: new Date(log.timestamp).toISOString()
+      });
+      try {
+        appendFileSync(state.receiptFilePath, tombstone + "\n");
+      } catch {
+      }
+      process.stderr.write(`[PROTECT_MCP_SIGNING_FAILURE] ${tombstone}
 `);
+      return { signingFailed: true };
     }
   }
+  return { signingFailed: false };
 }
 async function routeHookEvent(input, state) {
   switch (input.hookEventName) {
@@ -828,5 +1014,38 @@ function normalizeHookInput(raw) {
 }
 
 export {
+  ScopeBlindBridge,
+  getScopeBlindBridge,
+  forwardReceipt,
   startHookServer
 };
+/**
+ * scopeblind-bridge.ts
+ *
+ * Optional bridge between protect-mcp (local, MIT) and a paid ScopeBlind
+ * tenant. When SCOPEBLIND_TOKEN is set in the environment, every signed
+ * receipt that protect-mcp emits also gets forwarded to the tenant's
+ * dashboard at https://scopeblind.com/console/<slug>.
+ *
+ * Lifecycle:
+ *   1. On first use, exchange SCOPEBLIND_TOKEN for a short-lived BRASS-v2
+ *      auth proof from /fn/brass/issue. Cache the proof in memory until
+ *      ~5 minutes before expiry, then refresh.
+ *   2. As receipts are emitted by hook-server.ts, push them into an
+ *      in-memory batch queue.
+ *   3. Flush the queue every 5s (or when it reaches 128 receipts) by POSTing
+ *      to /fn/console/<slug>/receipts with Bearer SCOPEBLIND_TOKEN.
+ *
+ * Failure mode: forward errors NEVER throw upstream. protect-mcp continues
+ * to mint and persist receipts locally regardless of dashboard availability.
+ * The bridge logs failures to stderr (best-effort) and retries on the next
+ * flush.
+ *
+ * Configuration:
+ *   SCOPEBLIND_TOKEN        Tenant bearer token (from welcome email).
+ *   SCOPEBLIND_TENANT       Optional slug override. By default we discover
+ *                           the slug from the BRASS proof's tenant_id.
+ *   SCOPEBLIND_BASE         Defaults to https://scopeblind.com.
+ *
+ * @license MIT
+ */

package/dist/{chunk-BYYWYSHM.mjs → chunk-PLKRTBDR.mjs}

@@ -7,7 +7,7 @@ import {
   parseRateLimit,
   signDecision,
   startStatusServer
-} from "./chunk-YTBC72JJ.mjs";
+} from "./chunk-UV53U6D4.mjs";
 
 // src/evidence-store.ts
 import { readFileSync, writeFileSync, existsSync } from "fs";
@@ -974,8 +974,20 @@ var ProtectGateway = class {
             this.evidenceStore.save();
           }
         }
-      } else if (signed.warning) {
-        process.stderr.write(`[PROTECT_MCP] Warning: ${signed.warning}
+      } else if (signed.error) {
+        const tombstone = JSON.stringify({
+          type: "scopeblind.signing_failure.v1",
+          request_id: log.request_id,
+          tool: log.tool,
+          decision: log.decision,
+          error: signed.error,
+          at: new Date(log.timestamp).toISOString()
+        });
+        try {
+          appendFileSync(this.receiptFilePath, tombstone + "\n");
+        } catch {
+        }
+        process.stderr.write(`[PROTECT_MCP_SIGNING_FAILURE] ${tombstone}
 `);
       }
     }

package/dist/{chunk-GQWJCHQV.mjs → chunk-S4ICHNSP.mjs}

@@ -1,11 +1,11 @@
 import {
   meetsMinTier
-} from "./chunk-BYYWYSHM.mjs";
+} from "./chunk-PLKRTBDR.mjs";
 import {
   checkRateLimit,
   getToolPolicy,
   parseRateLimit
-} from "./chunk-YTBC72JJ.mjs";
+} from "./chunk-UV53U6D4.mjs";
 
 // src/simulate.ts
 import { readFileSync } from "fs";

package/dist/{chunk-YTBC72JJ.mjs → chunk-UV53U6D4.mjs}

@@ -78,11 +78,40 @@ function checkRateLimit(key, limit, store) {
 import { readFileSync as readFileSync2, existsSync } from "fs";
 var signerState = null;
 var artifactsModule = null;
+var signingConfigured = false;
+var signingInitError = null;
 async function initSigning(config) {
   const warnings = [];
+  signerState = null;
+  artifactsModule = null;
+  signingConfigured = Boolean(config && config.enabled !== false);
+  signingInitError = null;
   if (!config || config.enabled === false) {
     return warnings;
   }
+  if (!config.key_path) {
+    signingInitError = "signing enabled but key_path is not configured";
+    warnings.push(`signing: ${signingInitError}`);
+    return warnings;
+  }
+  if (!existsSync(config.key_path)) {
+    signingInitError = `key file not found at ${config.key_path}`;
+    warnings.push(`signing: ${signingInitError} \u2014 run "protect-mcp init" to generate`);
+    return warnings;
+  }
+  let keyData;
+  try {
+    keyData = JSON.parse(readFileSync2(config.key_path, "utf-8"));
+    if (!keyData.privateKey || !keyData.publicKey) {
+      signingInitError = "key file missing privateKey or publicKey fields";
+      warnings.push(`signing: ${signingInitError}`);
+      return warnings;
+    }
+  } catch (err) {
+    signingInitError = `failed to load key file: ${err instanceof Error ? err.message : err}`;
+    warnings.push(`signing: ${signingInitError}`);
+    return warnings;
+  }
   try {
     const moduleName = "@veritasacta/artifacts";
     artifactsModule = await import(
@@ -90,37 +119,48 @@ async function initSigning(config) {
       moduleName
     );
   } catch {
-    warnings.push("signing: @veritasacta/artifacts not available \u2014 receipts will be unsigned");
+    signingInitError = "@veritasacta/artifacts not available";
+    warnings.push(`signing: ${signingInitError} \u2014 enforce mode will fail closed`);
     return warnings;
   }
-  if (config.key_path) {
-    if (!existsSync(config.key_path)) {
-      warnings.push(`signing: key file not found at ${config.key_path} \u2014 run "protect-mcp init" to generate`);
-      return warnings;
-    }
-    try {
-      const keyData = JSON.parse(readFileSync2(config.key_path, "utf-8"));
-      if (!keyData.privateKey || !keyData.publicKey) {
-        warnings.push("signing: key file missing privateKey or publicKey fields");
-        return warnings;
-      }
-      signerState = {
-        privateKey: keyData.privateKey,
-        publicKey: keyData.publicKey,
-        kid: keyData.kid || artifactsModule.computeKid(keyData.publicKey),
-        issuer: config.issuer || keyData.issuer || "protect-mcp"
-      };
-    } catch (err) {
-      warnings.push(`signing: failed to load key file: ${err instanceof Error ? err.message : err}`);
-    }
+  try {
+    signerState = {
+      privateKey: keyData.privateKey,
+      publicKey: keyData.publicKey,
+      kid: keyData.kid || artifactsModule.computeKid(keyData.publicKey),
+      issuer: config.issuer || keyData.issuer || "protect-mcp"
+    };
+  } catch (err) {
+    signingInitError = `failed to initialize signer: ${err instanceof Error ? err.message : err}`;
+    artifactsModule = null;
+    warnings.push(`signing: ${signingInitError} \u2014 enforce mode will fail closed`);
   }
   return warnings;
 }
 function signDecision(entry) {
+  const artifactType = entry.decision === "deny" ? "gateway_restraint" : "decision_receipt";
+  if (signingConfigured && signingInitError) {
+    return {
+      ok: false,
+      signed: null,
+      artifact_type: artifactType,
+      warning: `signing initialization failed: ${signingInitError}`,
+      error: signingInitError
+    };
+  }
+  if (signingConfigured && (!signerState || !artifactsModule)) {
+    const error = "signing was configured but no signer is ready";
+    return {
+      ok: false,
+      signed: null,
+      artifact_type: artifactType,
+      warning: error,
+      error
+    };
+  }
   if (!signerState || !artifactsModule) {
-    return { signed: null, artifact_type: "none" };
+    return { ok: false, signed: null, artifact_type: "none" };
   }
-  const artifactType = entry.decision === "deny" ? "gateway_restraint" : "decision_receipt";
   try {
     const payload = {
       tool: entry.tool,
@@ -161,14 +201,18 @@ function signDecision(entry) {
       }
     );
     return {
+      ok: true,
       signed: JSON.stringify(result.artifact),
       artifact_type: artifactType
     };
   } catch (err) {
+    const message = err instanceof Error ? err.message : "unknown error";
     return {
+      ok: false,
       signed: null,
       artifact_type: artifactType,
-      warning: `signing failed: ${err instanceof Error ? err.message : "unknown error"}`
+      warning: `signing failed: ${message}`,
+      error: message
     };
   }
 }
@@ -181,7 +225,7 @@ function getSignerInfo() {
   };
 }
 function isSigningEnabled() {
-  return signerState !== null && artifactsModule !== null;
+  return signingConfigured && signingInitError === null && signerState !== null && artifactsModule !== null;
 }
 
 // src/cedar-evaluator.ts