@metamynd/agentsafe-mcp-guard 0.2.1 → 0.3.3

package/README.md

@@ -67,6 +67,19 @@ const bookFlight = guard.guardIncomingTool('flight-purchase', rawBookFlight);
 4. evaluates Standards → SOPs → mandate with `policy-core` — signed fields applied last, so a
    forged `itinerary` key can't shadow the signed amount/merchant (§6.4.2).
 
+`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. 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).
+
 ### Replay and cumulative spend (`requireAuthorization`)
 
 Re-evaluating policy per request (above) proves the request is well-formed and in-policy — it

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).

package/package.json

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

@@ -11,6 +11,24 @@ var ATOM_REGISTRY = {
     return have !== void 0 && need !== void 0 && have >= need;
   },
   "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`) 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),
@@ -72,6 +90,13 @@ var ATOM_SPECS = [
     config: [{ key: "limit", type: "number", required: true, description: "Maximum allowed amount for one transaction" }],
     requiredContext: ["amount"]
   },
+  {
+    predicate: "amount-unknown",
+    label: "Amount not determinable",
+    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"]
+  },
   {
     predicate: "cumulative-over",
     label: "Total budget over limit",
@@ -330,7 +355,9 @@ function constraintSatisfied(c, req) {
   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 (!op(left, c.rightOperand)) return false;
+  if (c.unit && req.values["mm:currency"] !== c.unit) return false;
+  return true;
 }
 function targetOf(rule, mandate) {
   return rule.target ?? mandate.target;
@@ -422,8 +449,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