@metamynd/agentsafe-mcp-guard 0.3.5 → 0.3.6

package/README.md

@@ -99,13 +99,36 @@ response that omits it — the one place a future backend change could quietly r
 confused-deputy gap this check exists to close, with nothing else here able to notice. The
 decision is unchanged (still tolerated, not blocked) — this is visibility, not a new refusal.
 
-### Replay and cumulative spend (`requireAuthorization`)
+**0.3.6 — two gaps a security review found in what this guard actually enforces, not just what
+its docs claimed.** First: `requireAuthorization`'s doc only ever named replay and cumulative
+spend as what it closes, but rate limits, circuit breakers, and spend-pattern anomaly detection
+are equally stateful and equally invisible to the stateless bundle re-check — the doc undersold
+its own scope. A value-bearing call permitted with `requireAuthorization` off now logs a warning
+naming all five. Second: `guardIncomingTool`'s capability check only ran when the CALLER chose to
+include `signed.capability` — an agent could simply omit it and the "authorize $150, execute
+$5,000" protection never engaged, verifier configured or not. New `requireCapability: true` makes
+an omitted capability a hard block (`CAPABILITY_REQUIRED`) instead of a silent pass-through. Both
+off by default — existing embeds are unchanged.
+
+### Replay, cumulative spend, rate limits, breakers, spend anomalies (`requireAuthorization`)
 
 Re-evaluating policy per request (above) proves the request is well-formed and in-policy — it
 does **not** stop a captured, still-fresh request from being replayed, and it can't enforce the
 mandate's TOTAL budget across many separately-legal calls (each is only checked against its own
-per-transaction cap). Both are the stateful issuer gate's job, not something a stateless re-check
-can do on its own.
+per-transaction cap). Neither is something a stateless re-check can do on its own: both, like
+rate limits, circuit breakers, and spend-pattern anomaly detection, key off the agent's history
+on the issuer's side, which never travels to this guard's stateless bundle re-check. **All of
+these are the stateful issuer gate's job.** `requireAuthorization` is the one setting that closes
+all of them at once, because it forces the exact request back through that gate before this
+Service executes anything. Left off, a value-bearing call permitted here logs a warning saying
+exactly that, so the gap is visible in your own logs rather than silent:
+
+```
+[mcp-guard] "flight-purchase" (amount=100) permitted in trustless mode — rate-limit,
+circuit-breaker, replay, cumulative-spend, and spend-anomaly floors are stateful and were NOT
+re-verified against live issuer state. Set requireAuthorization:true for custodial/value-bearing
+surfaces.
+```
 
 ```js
 const guard = createMcpGuard({ serviceDid, issuerApi, requireAuthorization: true });
@@ -199,6 +222,19 @@ transaction** — the host reconstructs the tx and verifies MetaMynd's signature
 `checkCapabilityBinding` from `magp-bind`), so "authorize $150, execute $5,000" is rejected in the
 prod guard, not just the demo gateway. No verifier configured → opt-in (unchanged).
 
+Presenting a capability is otherwise the **caller's** choice: an agent can simply omit
+`signed.capability` and the check above never runs, verifier configured or not. Set
+`requireCapability: true` to close that omission — a PERMIT with no capability is then blocked
+(`CAPABILITY_REQUIRED`) instead of silently passing through unbound:
+
+```js
+const guard = createMcpGuard({ serviceDid, verifyCapability, requireCapability: true });
+```
+
+Off by default, so an existing integration whose callers don't yet present a capability keeps
+working unchanged. Turn it on for any Service where the decision-token binding is meant to be
+mandatory, not opt-in.
+
 Holds carry an expiry (§7a.4): if not captured, the reservation auto-voids and the budget returns
 to the cap; a party can also void explicitly via `POST /policy/mandate/authorize/:id/void`.
 

package/agentsafe-mcp-guard.mjs

@@ -42,8 +42,22 @@ const CLOCK_SKEW_TOLERANCE_MS = 30 * 1000;
  *   SPEND, neither of which the stateless re-check above can enforce on its own. Off by default:
  *   it costs a network round trip per value-bearing call, so it's a deliberate choice, not a
  *   strictly-dominant one — a Service happy with per-request policy re-evaluation alone can skip it.
+ *
+ *   The stateless re-check ALSO cannot see the issuer's other STATEFUL floors — rate limits,
+ *   circuit breakers, and spend-pattern anomaly detection all key off the agent's server-side
+ *   history, which never travels to the edge. `requireAuthorization` is the one mechanism that
+ *   closes all of these at once, because it forces the exact request through the stateful gate
+ *   before this Service will execute it. A value-bearing call permitted here with
+ *   `requireAuthorization` OFF logs a warning for exactly this reason — see guardIncomingTool.
+ * @param {boolean} [cfg.requireCapability] when true AND `verifyCapability` is configured, a PERMIT
+ *   verdict for a call with NO `signed.capability` is now BLOCKED (`CAPABILITY_REQUIRED`) rather than
+ *   silently passing through unbound. Without this, capability binding is opt-in from the CALLER's
+ *   side — an agent can simply omit `capability` and the "authorize $150, execute $5,000" check below
+ *   never runs at all, since it only fires when the field is present. Off by default (an existing
+ *   integrator's un-capability-aware callers must keep working); set true on any Service where
+ *   capability binding is meant to be mandatory, not opt-in.
  */
-export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle, policyPublicKey, settlementStore, verifyCapability, requireAuthorization = false } = {}) {
+export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle, policyPublicKey, settlementStore, verifyCapability, requireAuthorization = false, requireCapability = false } = {}) {
   if (!serviceDid) throw new Error('createMcpGuard requires { serviceDid }');
   const base = issuerApi ? issuerApi.replace(/\/$/, '') : null;
   const privateKey = serviceKey
@@ -273,20 +287,40 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
       // exact transaction — the host reconstructs the tx + verifies MetaMynd's signature OFFLINE,
       // so "authorize $150, execute $5,000" (authorize-A / execute-B) is rejected HERE, in the
       // prod guard, not just the demo gateway. No verifier configured → unchanged (opt-in).
-      if (signed?.capability && typeof verifyCapability === 'function') {
-        let bind;
-        try { bind = await verifyCapability(signed); }
-        catch (err) { bind = { ok: false, reasonCode: 'CAPABILITY_CHECK_ERROR', error: String(err?.message ?? err) }; }
-        if (!bind?.ok) {
-          const err = new Error(`MCP guard CAPABILITY "${action}": ${bind?.reasonCode ?? 'CAPABILITY_INVALID'}`);
+      //
+      // Presenting a capability is the CALLER's choice, not this guard's: an agent can simply
+      // omit `signed.capability` and this whole check is skipped, verifier or not — that is
+      // exactly the omission `requireCapability` closes. Without it, capability binding is
+      // opt-in from the wrong side of the trust boundary.
+      if (typeof verifyCapability === 'function') {
+        if (signed?.capability) {
+          let bind;
+          try { bind = await verifyCapability(signed); }
+          catch (err) { bind = { ok: false, reasonCode: 'CAPABILITY_CHECK_ERROR', error: String(err?.message ?? err) }; }
+          if (!bind?.ok) {
+            const err = new Error(`MCP guard CAPABILITY "${action}": ${bind?.reasonCode ?? 'CAPABILITY_INVALID'}`);
+            err.name = 'GovernanceBlocked';
+            err.governance = { decision: 'block', reasonCode: bind?.reasonCode ?? 'CAPABILITY_INVALID' };
+            throw err;
+          }
+        } else if (requireCapability) {
+          const err = new Error(`MCP guard CAPABILITY "${action}": CAPABILITY_REQUIRED`);
           err.name = 'GovernanceBlocked';
-          err.governance = { decision: 'block', reasonCode: bind?.reasonCode ?? 'CAPABILITY_INVALID' };
+          err.governance = { decision: 'block', reasonCode: 'CAPABILITY_REQUIRED' };
           throw err;
         }
       }
       if (decision.decision === 'observe') {
         console.warn(`[mcp-guard] OBSERVE "${action}": ${decision.reasonCode} — served under monitoring`);
       }
+      // Trustless mode cannot see the issuer's stateful floors (see requireAuthorization's own
+      // doc above) — surface that as a loud, per-call signal rather than a silent gap, so an
+      // operator serving real value through this path finds out from their own logs rather
+      // than from an incident. Gated on value-bearing (amount > 0): a free/read action has
+      // nothing for those floors to protect, so warning on it would just be noise.
+      if (!requireAuthorization && Number(signed?.amount) > 0) {
+        console.warn(`[mcp-guard] "${action}" (amount=${signed.amount}) permitted in trustless mode — rate-limit, circuit-breaker, replay, cumulative-spend, and spend-anomaly floors are stateful and were NOT re-verified against live issuer state. Set requireAuthorization:true for custodial/value-bearing surfaces.`);
+      }
       return handler(signed, ...rest);
     };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-mcp-guard",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Zero-dependency trustless governance for the SERVICE side. An MCP server or API re-verifies a calling agent's signed request against the agent's own published policy \u00e2\u20ac\u201d so an agent that ignores its own guard still cannot make your service act.",
   "type": "module",
   "main": "./agentsafe-mcp-guard.mjs",