@metamynd/agentsafe-mcp-guard 0.2.0 → 0.3.1

package/README.md

@@ -67,6 +67,11 @@ 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.
+
 ### Replay and cumulative spend (`requireAuthorization`)
 
 Re-evaluating policy per request (above) proves the request is well-formed and in-policy — it
@@ -83,11 +88,14 @@ When set, a PERMIT verdict (allow/observe) additionally requires `signed.authori
 **atomically claim single-use execution** against the issuer (`AUTHORIZED → DISPATCHING`, the
 effect-safety state machine) — a second claim of the same id, whether a genuine replay or a race,
 fails, because that transition is legal exactly once. The claimed hold's own bound
-`agentDid`/`amount`/`currency` are checked against what's actually being executed, too — a claim
-alone only proves *some* real, unclaimed authorization exists; without this check, a cheap
-legitimate hold's id could be presented to unlock a completely different, more expensive
+`agentDid`/`amount`/`currency`/`merchant` are checked against what's actually being executed, too
+— a claim alone only proves *some* real, unclaimed authorization exists; without this check, a
+cheap legitimate hold's id could be presented to unlock a completely different, more expensive
 execution (`AUTHORIZATION_AGENT_MISMATCH` / `AUTHORIZATION_AMOUNT_MISMATCH` /
-`AUTHORIZATION_CURRENCY_MISMATCH`).
+`AUTHORIZATION_CURRENCY_MISMATCH` / `AUTHORIZATION_MERCHANT_MISMATCH`). A field the backend
+response omits (e.g. an older, not-yet-migrated deployment with no `merchant` column) is skipped,
+not treated as a mismatch — this degrades gracefully, it doesn't silently under-check going
+forward once the backend does report it.
 
 The `authorizationId` has to come from a **real** `guard.authorize()` call on the agent side —
 not `buildSignedRequest()`, which never talks to the network. In practice this usually needs no

package/agentsafe-mcp-guard.mjs

@@ -90,11 +90,12 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
    * against the stateful issuer gate already checked both (agentsafe-guard.mjs's authorizeLocal()
    * seals any value-bearing action through the real remote authorize() by default).
    *
-   * On success, also returns the hold's OWN bound `agentDid`/`amount`/`currency` — the caller MUST
-   * compare these to the request actually being executed. A claim alone only proves "some real,
-   * unclaimed authorization exists"; without this check, a legitimately-obtained authorization for
-   * a small, honest transaction could be presented to unlock a completely different one — the same
-   * confused-deputy shape payload binding closes at the request layer, recurring one layer deeper.
+   * On success, also returns the hold's OWN bound `agentDid`/`amount`/`currency`/`merchant` — the
+   * caller MUST compare these to the request actually being executed. A claim alone only proves
+   * "some real, unclaimed authorization exists"; without this check, a legitimately-obtained
+   * authorization for a small, honest transaction could be presented to unlock a completely
+   * different one — the same confused-deputy shape payload binding closes at the request layer,
+   * recurring one layer deeper.
    */
   async function claimAuthorization({ authorizationId } = {}) {
     if (!authorizationId) return { claimed: false, reasonCode: 'AUTHORIZATION_REQUIRED' };
@@ -103,7 +104,7 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
       const res = await fetch(`${base}/policy/mandate/authorize/${encodeURIComponent(authorizationId)}/effect/dispatching`, { method: 'POST' });
       const body = await res.json().catch(() => null);
       if (!res.ok) return { claimed: false, reasonCode: body?.message ?? body?.data?.reasonCode ?? `AUTHORIZATION_CLAIM_HTTP_${res.status}` };
-      return { claimed: true, agentDid: body?.data?.agentDid, amount: body?.data?.amount, currency: body?.data?.currency };
+      return { claimed: true, agentDid: body?.data?.agentDid, amount: body?.data?.amount, currency: body?.data?.currency, merchant: body?.data?.merchant };
     } catch (err) {
       return { claimed: false, reasonCode: 'AUTHORIZATION_CLAIM_UNREACHABLE', error: String(err?.message ?? err) };
     }
@@ -218,6 +219,7 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
         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' };
+        if (claim.merchant !== undefined && claim.merchant !== merchant) return { decision: 'block', reasonCode: 'AUTHORIZATION_MERCHANT_MISMATCH' };
       }
       return final;
     } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-mcp-guard",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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,14 @@ 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`): 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)),
   // 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 +80,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 \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.",
+    config: [],
+    requiredContext: ["amount"]
+  },
   {
     predicate: "cumulative-over",
     label: "Total budget over limit",