@metamynd/agentsafe-mcp-guard 0.3.3 → 0.3.6

package/README.md

@@ -80,13 +80,55 @@ server time, a pre-signing window rather than ordinary clock skew. `issuedAt` ma
 to the freshness window (network/processing delay) but lead by no more than 30 seconds (clock
 skew only).
 
-### Replay and cumulative spend (`requireAuthorization`)
+**0.3.4 — a mandate's currency check no longer lets a PROHIBITION be dodged by relabeling
+the currency.** A payAmount/cumulativeSpend constraint issued with a `unit` (currency) is
+only satisfied in that currency — correct for a PERMISSION (fail closed to deny on a
+mismatch), but a prohibition only fires when every one of its own constraints is satisfied,
+so the identical "mismatch → not satisfied" rule let a prohibition like `payAmount gteq 1000
+unit USD` be silently skipped by declaring any other currency, including a mere case
+difference (`'usd'` vs `'USD'`). The currency comparison is also now case-insensitive.
+
+**0.3.5 — a degraded claim now warns instead of only being silently tolerated.**
+`claimAuthorization()`'s per-field cross-checks each skip when the issuer's claim response
+omits that field — a deliberate, documented rolling-upgrade tolerance for a Service pinned
+against an older backend whose response predates one of these fields existing at all. That
+tolerance was never meant to also mask a REGRESSION on an otherwise-current backend: this
+version logs (`console.warn`) whenever a value-bearing request's claim response omits
+`agentDid`/`amount`/`currency`, or a request that signed a real `merchant` gets a claim
+response that omits it — the one place a future backend change could quietly re-open the
+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.
+
+**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 });
@@ -180,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
@@ -229,7 +243,19 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
         if (!claim.claimed) return { decision: 'block', reasonCode: claim.reasonCode };
         // The claim alone only proves SOME real, unclaimed authorization exists — it must also
         // be FOR this agent and these exact values, or a cheap legitimate hold's id could be
-        // presented to unlock a completely different, more expensive execution.
+        // presented to unlock a completely different, more expensive execution. Each check is
+        // skipped when the claim response omits that field — tolerated for a Service pinned
+        // against an older, not-yet-migrated issuer whose response predates the field (see
+        // backend markEffect()'s own note) — but a value-bearing request with a real signed
+        // amount/merchant omitted from the claim is exactly the "field genuinely absent vs.
+        // issuer regressed" ambiguity that note warns about, so it's surfaced rather than
+        // silently trusted: this is the ONE place a future backend change could quietly
+        // re-open the confused-deputy gap this claim exists to close, and nothing else here
+        // would notice.
+        if (claim.agentDid === undefined) console.warn('[mcp-guard] claim response omitted agentDid — binding degraded to "some valid unclaimed authorization exists"');
+        if (Number(amount) > 0 && claim.amount === undefined) console.warn('[mcp-guard] claim response omitted amount for a value-bearing request — amount binding degraded');
+        if (Number(amount) > 0 && claim.currency === undefined) console.warn('[mcp-guard] claim response omitted currency for a value-bearing request — currency binding degraded');
+        if (merchant && claim.merchant === undefined) console.warn('[mcp-guard] claim response omitted merchant for a request that signed one — merchant binding degraded');
         if (claim.agentDid !== undefined && claim.agentDid !== agentDid) return { decision: 'block', reasonCode: 'AUTHORIZATION_AGENT_MISMATCH' };
         if (claim.amount !== undefined && Number(claim.amount) !== Number(amount)) return { decision: 'block', reasonCode: 'AUTHORIZATION_AMOUNT_MISMATCH' };
         if (claim.currency !== undefined && claim.currency !== currency) return { decision: 'block', reasonCode: 'AUTHORIZATION_CURRENCY_MISMATCH' };
@@ -261,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.3",
+  "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",

package/policy-core.mjs

@@ -351,13 +351,14 @@ function reasonFor(constraint) {
   if (!constraint) return "CONSTRAINT_FAILED";
   return REASON_BY_OPERAND[constraint.leftOperand] ?? `CONSTRAINT_FAILED:${constraint.leftOperand}`;
 }
-function constraintSatisfied(c, req) {
+function constraintSatisfied(c, req, strict) {
   const op = OPERATORS[c.operator];
   if (!op) return false;
   const left = Object.prototype.hasOwnProperty.call(req.values, c.leftOperand) ? req.values[c.leftOperand] : void 0;
-  if (!op(left, c.rightOperand)) return false;
-  if (c.unit && req.values["mm:currency"] !== c.unit) return false;
-  return true;
+  if (!c.unit) return op(left, c.rightOperand);
+  const currency = req.values["mm:currency"];
+  const unitMatches = typeof currency === "string" && currency.toUpperCase() === c.unit.toUpperCase();
+  return unitMatches ? op(left, c.rightOperand) : !strict;
 }
 function targetOf(rule, mandate) {
   return rule.target ?? mandate.target;
@@ -379,7 +380,7 @@ function evaluateMandate(mandate, req) {
   }
   for (const p of mandate.prohibition ?? []) {
     if (targetOf(p, mandate) !== req.target) continue;
-    const fires = (p.constraint ?? []).every((c) => constraintSatisfied(c, req));
+    const fires = (p.constraint ?? []).every((c) => constraintSatisfied(c, req, false));
     if (fires) {
       return {
         decision: p.enforcement ?? "block",
@@ -397,10 +398,10 @@ function evaluateMandate(mandate, req) {
     };
   }
   for (const p of perms) {
-    const failing = (p.constraint ?? []).find((c) => !constraintSatisfied(c, req));
+    const failing = (p.constraint ?? []).find((c) => !constraintSatisfied(c, req, true));
     if (!failing) return { decision: "allow", reasonCode: "AUTHORIZED" };
   }
-  const firstFail = (perms[0].constraint ?? []).find((c) => !constraintSatisfied(c, req));
+  const firstFail = (perms[0].constraint ?? []).find((c) => !constraintSatisfied(c, req, true));
   return {
     decision: firstFail?.onFail ?? "block",
     reasonCode: reasonFor(firstFail),