@metamynd/agentsafe-mcp-guard 0.3.1 → 0.3.5

package/README.md

@@ -70,7 +70,34 @@ const bookFlight = guard.guardIncomingTool('flight-purchase', rawBookFlight);
 `policy-core`'s `amount-unknown` atom (0.3.0) is a deny-by-default check for any value-moving
 tool call whose amount the guard can't determine — a signed-transaction or nested x402 payload
 can carry its value somewhere a naive spend cap never looks, and this blocks that case instead
-of letting it slip past the cap untested.
+of letting it slip past the cap untested. As of 0.3.2 it also fires on a **negative** amount,
+which previously read as "a real, known number" and could clear a spend cap for free.
+
+**0.3.2 — freshness is no longer symmetric.** The staleness check used to compare
+`|now - issuedAt|` against the freshness window, which treated a request timestamped in the
+*future* the same as one from the past — accepting anything signed up to 5 minutes ahead of
+server time, a pre-signing window rather than ordinary clock skew. `issuedAt` may now lag by up
+to the freshness window (network/processing delay) but lead by no more than 30 seconds (clock
+skew only).
+
+**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.
 
 ### Replay and cumulative spend (`requireAuthorization`)
 

package/agentsafe-mcp-guard.mjs

@@ -17,8 +17,14 @@ import { verifyDidSignature } from './magp-did.mjs';
 import { buildPaymentRequirements, checkSettlementBinding } from './x402.mjs';
 import { verifyBundle } from './magp-policy.mjs';
 
-/** Freshness window for signed requests and handshake nonces (spec §7.7). */
+/** Freshness window for signed requests and handshake nonces (spec §7.7). How far `issuedAt`
+ *  may be BEHIND server time — network/processing delay. */
 const FRESHNESS_MS = 5 * 60 * 1000;
+/** How far a signed request's `issuedAt` may be AHEAD of server time — clock skew, not a window
+ *  to pre-sign a request for later use. Checked separately from FRESHNESS_MS so `Math.abs()`
+ *  can't fold both directions into one 10-minute window (found live: a request signed up to 5
+ *  minutes in the future was accepted). Mirrors mandate.service.ts's CLOCK_SKEW_TOLERANCE_MS. */
+const CLOCK_SKEW_TOLERANCE_MS = 30 * 1000;
 
 /**
  * @param {object} cfg
@@ -127,7 +133,7 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
 
   /** Evaluate the agent's bundle against the request via policy-core (signed fields last). */
   function verdictFromBundle(bundle, req) {
-    const { agentDid, action, amount = 0, merchant = '', itinerary = {}, cumulativeSpend = amount, now } = req;
+    const { agentDid, action, amount = 0, currency = 'USD', merchant = '', itinerary = {}, cumulativeSpend = amount, now } = req;
     const mandate = (bundle.mandates ?? []).find((m) => m.action === action)?.document;
     return evaluate({
       standards: (bundle.standards ?? []).map((s) => ({ standardKey: s.key, document: s.document })),
@@ -142,6 +148,11 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
               'mm:payAmount': amount,
               'mm:cumulativeSpend': cumulativeSpend,
               'mm:merchant': merchant,
+              // A payAmount/cumulativeSpend constraint issued with a `unit` (currency) is
+              // only satisfied in that currency (see mandate-eval.ts's constraintSatisfied)
+              // — omitting this would make EVERY unit-bearing cap fail regardless of amount.
+              // Defaults to 'USD', matching verifyRequest()'s own default for this field.
+              'mm:currency': currency,
             }),
           }
         : undefined,
@@ -169,8 +180,11 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
       // 2. Freshness. (Single-use nonce consumption stays the gate's job by default — a Service
       //    re-check is verification, not a second authorization. requireAuthorization below is
       //    the opt-in exception: it DOES give the Service its own single-use claim.)
+      // Asymmetric: `age` positive = issuedAt in the past (tolerate FRESHNESS_MS); negative =
+      // issuedAt in the future (tolerate only CLOCK_SKEW_TOLERANCE_MS) — see its own comment.
       const ts = Date.parse(issuedAt);
-      if (Number.isNaN(ts) || Math.abs(Date.now() - ts) > FRESHNESS_MS) {
+      const age = Date.now() - ts;
+      if (Number.isNaN(ts) || age > FRESHNESS_MS || age < -CLOCK_SKEW_TOLERANCE_MS) {
         return { decision: 'block', reasonCode: 'REQUEST_EXPIRED' };
       }
       // 3. Re-evaluate against the issuer-hosted bundle (fetched over TLS from the issuer).
@@ -215,7 +229,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' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-mcp-guard",
-  "version": "0.3.1",
+  "version": "0.3.5",
   "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

@@ -12,13 +12,23 @@ var ATOM_REGISTRY = {
   },
   "amount-over": (c, cfg) => typeof c.amount === "number" && 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`): true when the context carries no
-  // usable amount — the gate cannot tell how much value the call would move, so a
-  // spend cap authored next to it would silently never fire. Author it with BLOCK as
-  // the FIRST rule of a spend policy; the cap that follows then only ever judges a
-  // known number. Opt-in: only a rule that keys it runs it, so actions that carry no
-  // amount by nature are unaffected.
-  "amount-unknown": (c) => !(typeof c.amount === "number" && Number.isFinite(c.amount)),
+  // 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 —
+  // the gate cannot tell how much value the call would move, so a spend cap authored
+  // next to it would silently never fire. `amount-over` only ever fires on `> limit`,
+  // so a negative amount clears every positive cap by construction, and on a system
+  // that tracks committed spend ADDITIVELY (reserved += amount), a negative claim can
+  // net-reduce what's already committed rather than add to it — the same "cap never
+  // fires" failure as a missing amount, reached from the other side of zero. Zero
+  // itself is NOT covered here: a genuine $0 action (a read, a no-op) is a valid,
+  // known amount, not an unknown one. Author this with BLOCK as the FIRST rule of a
+  // spend policy; the cap that follows then only ever judges a known, non-negative
+  // number. Opt-in: only a rule that keys it runs it, so actions that carry no amount
+  // by nature are unaffected. The public authorize endpoint's own schema already
+  // rejects a negative amount before it reaches this atom (defense in depth, not the
+  // only layer) — this is what closes the same gap for paths that schema doesn't
+  // cover: the local/harness evaluator and the platform's own MCP tool policies.
+  "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),
@@ -83,7 +93,7 @@ var ATOM_SPECS = [
   {
     predicate: "amount-unknown",
     label: "Amount not determinable",
-    description: "Fires when the action carries no usable amount \u2014 the gate cannot tell how much value it would move. A deny-by-default control for value-moving actions: author it with BLOCK ahead of a spend cap, otherwise an action whose amount is missing or unparseable passes the cap untested. Fires on ABSENCE, so only attach it to actions that must always carry an amount.",
+    description: "Fires when the action carries no usable amount, or a NEGATIVE one \u2014 the gate cannot trust either for capping. A deny-by-default control for value-moving actions: author it with BLOCK ahead of a spend cap, otherwise an amount that is missing, unparseable, or negative passes the cap untested (amount-over only ever fires above the limit, so a negative amount clears every positive cap). A genuine $0 amount does NOT fire this \u2014 only attach it to actions that must always carry a real, non-negative amount.",
     config: [],
     requiredContext: ["amount"]
   },
@@ -341,11 +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;
-  return op(left, c.rightOperand);
+  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;
@@ -367,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",
@@ -385,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),
@@ -437,8 +450,11 @@ function evaluate(input) {
 }
 
 // src/policy-core/canonical.ts
+function escapeField(v) {
+  return v.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+}
 function buildAuthMessage(f) {
-  return `${f.agentDid}|${f.action}|${f.amount}|${f.currency}|${f.merchant ?? ""}|${f.nonce}|${f.issuedAt}`;
+  return [f.agentDid, f.action, f.amount, f.currency, f.merchant ?? "", f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
 }
 
 // src/policy-core/context.ts