@metamynd/agentsafe-mcp-guard 0.3.5 → 0.4.0

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.4.0",
   "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

@@ -2,6 +2,14 @@
 
 // src/policy-core/atom-registry.ts
 var RISK_RANK = { low: 0, medium: 1, high: 2, critical: 3 };
+function currencyOutOfScope(ctx, cfgCurrency) {
+  if (cfgCurrency === void 0 || cfgCurrency === null) return false;
+  const allowed = Array.isArray(cfgCurrency) ? cfgCurrency : [cfgCurrency];
+  if (allowed.length === 0) return false;
+  const currency = ctx.currency;
+  const matches = typeof currency === "string" && allowed.some((u) => typeof u === "string" && u.toUpperCase() === currency.toUpperCase());
+  return !matches;
+}
 var ATOM_REGISTRY = {
   "data-source-not-approved": (c, cfg) => !!c.dataSourceId && !(cfg?.approved ?? []).includes(String(c.dataSourceId)),
   "consent-missing": (c) => c.consent === false,
@@ -10,7 +18,11 @@ var ATOM_REGISTRY = {
     const need = RISK_RANK[String(cfg?.level ?? "high")];
     return have !== void 0 && need !== void 0 && have >= need;
   },
-  "amount-over": (c, cfg) => typeof c.amount === "number" && c.amount > Number(cfg?.limit ?? 0),
+  "amount-over": (c, cfg) => {
+    if (typeof c.amount !== "number") return false;
+    if (currencyOutOfScope(c, cfg?.currency)) return true;
+    return c.amount > Number(cfg?.limit ?? 0);
+  },
   // Deny-by-default primitive for value-moving actions. Fires on ABSENCE (like the
   // evidence atoms below, and unlike `amount-over`) OR on a NEGATIVE amount: true when
   // the context carries no usable amount, or one that cannot be trusted for capping —
@@ -31,7 +43,12 @@ var ATOM_REGISTRY = {
   "amount-unknown": (c) => !(typeof c.amount === "number" && Number.isFinite(c.amount) && c.amount >= 0),
   // Total budget: cumulativeSpend is a SERVER-derived, signed-last context field (never
   // shadowable by the agent's itinerary), so this compares already-spent + this amount.
-  "cumulative-over": (c, cfg) => Number(c.cumulativeSpend ?? 0) + Number(c.amount ?? 0) > Number(cfg?.limit ?? 0),
+  // See `currencyOutOfScope` above: a configured currency scope that this request's
+  // currency doesn't match fires the cap outright, same fail-closed reasoning as `amount-over`.
+  "cumulative-over": (c, cfg) => {
+    if (currencyOutOfScope(c, cfg?.currency)) return true;
+    return Number(c.cumulativeSpend ?? 0) + Number(c.amount ?? 0) > Number(cfg?.limit ?? 0);
+  },
   // Fires if any configured term appears in the prompt and/or output text.
   // Used to govern agent responses on content (prohibited claims, sensitive advice).
   "text-matches": (c, cfg) => {
@@ -87,7 +104,25 @@ var ATOM_SPECS = [
     predicate: "amount-over",
     label: "Per-transaction amount over limit",
     description: "Fires when a single action amount exceeds a configured limit (per-transaction cap).",
-    config: [{ key: "limit", type: "number", required: true, description: "Maximum allowed amount for one transaction" }],
+    config: [
+      { key: "limit", type: "number", required: true, description: "Maximum allowed amount for one transaction" },
+      {
+        key: "currency",
+        type: "string[]",
+        required: false,
+        description: `Optional currency scope for the limit (e.g. ['USD'], or ['USD','GBP'] for several). Leave empty to keep the limit currency-blind \u2014 the historical default: the raw number is compared regardless of currency. Once set, a request in a currency outside this list \u2014 or with none supplied at all \u2014 fires this atom regardless of amount (unverifiable is treated as unsafe, not as "smaller"), so the cap can't be cleared by naming a cheaper-looking currency (e.g. 200 JPY vs 200 USD).`
+      }
+    ],
+    // `currency` is NOT listed here even though the executable atom conditionally reads it:
+    // unlike `limit`, the `currency` config is OPTIONAL per atom instance, so whether an agent
+    // needs to supply it depends on how a given molecule configures this atom — something
+    // `requiredContextFor`'s per-predicate (not per-instance) model can't express. Every
+    // authorize request already carries `currency` unconditionally regardless (see
+    // AuthorizeInput), so nothing is actually left unfed by omitting it here — this only
+    // controls the Scenario Bank simulate form / docs "context contract" surfacing, and
+    // forcing it onto every amount-over molecule would spuriously mark scenarios that never
+    // configure a currency scope as unexercised (see cumulative-over-atom.test.ts's sibling
+    // comment below for the same reasoning applied there).
     requiredContext: ["amount"]
   },
   {
@@ -101,8 +136,32 @@ var ATOM_SPECS = [
     predicate: "cumulative-over",
     label: "Total budget over limit",
     description: "Fires when cumulative spend (already-spent + this transaction) exceeds a configured total budget.",
-    config: [{ key: "limit", type: "number", required: true, description: "Maximum total budget across all transactions" }],
-    requiredContext: ["amount"]
+    config: [
+      { key: "limit", type: "number", required: true, description: "Maximum total budget across all transactions" },
+      {
+        key: "currency",
+        type: "string[]",
+        required: false,
+        description: "Optional currency scope for the budget (e.g. ['USD'], or ['USD','GBP'] for several). Leave empty to keep it currency-blind \u2014 the historical default. Once set, a request in a currency outside this list \u2014 or with none supplied at all \u2014 fires this atom regardless of amount, same fail-closed design as amount-over's currency scope."
+      }
+    ],
+    // The executable atom (atom-registry.ts) reads BOTH fields: `cumulativeSpend + amount >
+    // limit`. Omitting `cumulativeSpend` here silently broke two downstream consumers this
+    // catalog is the single source of truth for (see file header): the Scenario Bank's
+    // simulate form never rendered an "already spent" field for any set using this atom —
+    // including its own seeded preset, which supplied `cumulativeSpend` for a form field
+    // that didn't exist — so the control could never actually be exercised from the UI; and
+    // the integration docs' generated "context contract" told real SDK integrators this
+    // atom only needs `amount`, so an agent that never sends `cumulativeSpend` gets it
+    // silently treated as 0 and the total-budget cap never fires in production either.
+    //
+    // `currency`, by contrast, is deliberately NOT added here even though the executable atom
+    // conditionally reads it — see the sibling comment on `amount-over`'s currency config
+    // above: it is optional PER ATOM INSTANCE (only read when a molecule configures a
+    // currency scope), so unlike `cumulativeSpend` (always read), a static per-predicate
+    // requiredContext can't represent it without forcing every set using this atom to demand
+    // a currency it may never need.
+    requiredContext: ["amount", "cumulativeSpend"]
   },
   {
     predicate: "risk-at-or-above",
@@ -357,7 +416,8 @@ function constraintSatisfied(c, req, strict) {
   const left = Object.prototype.hasOwnProperty.call(req.values, c.leftOperand) ? req.values[c.leftOperand] : void 0;
   if (!c.unit) return op(left, c.rightOperand);
   const currency = req.values["mm:currency"];
-  const unitMatches = typeof currency === "string" && currency.toUpperCase() === c.unit.toUpperCase();
+  const allowedUnits = Array.isArray(c.unit) ? c.unit : [c.unit];
+  const unitMatches = typeof currency === "string" && allowedUnits.some((u) => u.toUpperCase() === currency.toUpperCase());
   return unitMatches ? op(left, c.rightOperand) : !strict;
 }
 function targetOf(rule, mandate) {