@metamynd/agentsafe-mcp-guard 0.1.2 → 0.2.1

package/README.md

@@ -61,16 +61,54 @@ const bookFlight = guard.guardIncomingTool('flight-purchase', rawBookFlight);
 
 `verifyRequest`:
 1. rebuilds the canonical message (§7.3) and verifies the Ed25519 signature via **key-in-DID**;
-2. checks freshness (single-use nonce stays the gate's job);
+2. checks freshness (single-use nonce stays the gate's job **unless `requireAuthorization` is
+   set** — see below, that's the exception);
 3. fetches the agent's policy bundle from the issuer (`GET /policy/bundle/:did`, over TLS);
 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).
 
+### Replay and cumulative spend (`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.
+
+```js
+const guard = createMcpGuard({ serviceDid, issuerApi, requireAuthorization: true });
+```
+
+When set, a PERMIT verdict (allow/observe) additionally requires `signed.authorizationId` to
+**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`/`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_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
+extra agent-side plumbing: `agentsafe-guard`'s default `guardTool()` path already calls the real
+remote `authorize()` for any value-bearing action (`sealValueActions`, on by default), so its
+`authorizationId` is already sitting in the `decision` object `guardTool()` hands your handler —
+thread it through to the signed request you present to this guard.
+
+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
+(no replay/cumulative-spend guarantee) can skip it.
+
 Run the self-check (handshake + trustless eval, no network):
 
 ```powershell
 cd integrations\agentsafe-mcp-guard
-node mcp-guard.smoke.mjs   # PASS when every case matches
+node mcp-guard.smoke.mjs             # PASS when every case matches
+node claim-authorization.smoke.mjs   # requireAuthorization: replay, mismatch, fail-closed
 ```
 
 ## 3. Payment binding (x402, §7a)

package/agentsafe-mcp-guard.mjs

@@ -30,8 +30,14 @@ const FRESHNESS_MS = 5 * 60 * 1000;
  *   GET /magp/policy/pubkey). When set, the guard VERIFIES the bundle signature + freshness (Phase F,
  *   §5.3.2/§5.3.3) and fails closed for value-bearing actions on an unsigned/tampered/stale bundle —
  *   so per-request enforcement needs no live MetaMynd. Omit for the legacy hash-addressed + TLS mode.
+ * @param {boolean} [cfg.requireAuthorization] when true, a PERMIT verdict (allow/observe) is only
+ *   actually granted if `signed.authorizationId` atomically claims single-use execution against the
+ *   stateful issuer gate (see claimAuthorization below) — this is what closes REPLAY and CUMULATIVE
+ *   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.
  */
-export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle, policyPublicKey, settlementStore, verifyCapability } = {}) {
+export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle, policyPublicKey, settlementStore, verifyCapability, requireAuthorization = false } = {}) {
   if (!serviceDid) throw new Error('createMcpGuard requires { serviceDid }');
   const base = issuerApi ? issuerApi.replace(/\/$/, '') : null;
   const privateKey = serviceKey
@@ -75,6 +81,35 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
 
   // --- Trustless re-evaluation (spec §9.3, §9.6) ---
 
+  /**
+   * Atomically claim a stateful authorization for single execution (AUTHORIZED -> DISPATCHING,
+   * the effect-safety state machine in backend/src/features/policy/mandate/effect-machine.ts). A
+   * SECOND claim of the SAME authorizationId — a replay, or a race — fails: that transition is only
+   * legal once. This is what actually stops replay and enforces the mandate's cumulative budget at
+   * a Service, because the authorizationId only exists because the agent's own authorize() call
+   * 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`/`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' };
+    if (!base) throw new Error('issuerApi is required to claim an authorization');
+    try {
+      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, merchant: body?.data?.merchant };
+    } catch (err) {
+      return { claimed: false, reasonCode: 'AUTHORIZATION_CLAIM_UNREACHABLE', error: String(err?.message ?? err) };
+    }
+  }
+
   async function loadBundle(agentDid) {
     if (typeof fetchBundle === 'function') return fetchBundle(agentDid);
     if (!base) throw new Error('issuerApi (or fetchBundle) is required to load the policy bundle');
@@ -131,8 +166,9 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
       if (!verifyDidSignature(agentDid, message, signature)) {
         return { decision: 'block', reasonCode: 'SIGNATURE_INVALID' };
       }
-      // 2. Freshness. (Single-use nonce consumption stays the gate's job — a Service
-      //    re-check is verification, not a second authorization.)
+      // 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.)
       const ts = Date.parse(issuedAt);
       if (Number.isNaN(ts) || Math.abs(Date.now() - ts) > FRESHNESS_MS) {
         return { decision: 'block', reasonCode: 'REQUEST_EXPIRED' };
@@ -167,10 +203,25 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
       const verdict = verdictFromBundle(bundle, { ...signed, itinerary: signed.itinerary ?? {} });
       // Mode ESCALATE floor lifts an otherwise-PERMIT (allow or observe) to human review
       // (escalate outranks observe, so a flag never masks it) — mirrors the backend gate.
-      if ((verdict.decision === 'allow' || verdict.decision === 'observe') && modeGate.decision === 'escalate') {
-        return { ...verdict, decision: 'escalate', reasonCode: modeGate.reasonCode };
+      const final = (verdict.decision === 'allow' || verdict.decision === 'observe') && modeGate.decision === 'escalate'
+        ? { ...verdict, decision: 'escalate', reasonCode: modeGate.reasonCode }
+        : verdict;
+      // 4. Stateful claim (opt-in). Re-evaluating policy per request (above) does not by itself
+      // stop REPLAY or CUMULATIVE SPEND past the mandate total — both are the stateful issuer
+      // gate's job. Only claim on an actual PERMIT: escalate/block/suspend/quarantine execute
+      // nothing, so there is nothing to protect and no reason to spend the hold's single use.
+      if (requireAuthorization && (final.decision === 'allow' || final.decision === 'observe')) {
+        const claim = await claimAuthorization({ authorizationId: signed.authorizationId });
+        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.
+        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 verdict;
+      return final;
     } catch (err) {
       return { decision: 'block', reasonCode: 'GUARD_ERROR', error: String(err?.message ?? err) };
     }
@@ -270,7 +321,7 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
     return { settled: true, txHash: result.txHash, reasonCode: 'SETTLED' };
   }
 
-  return { handshakeChallenge, handshakeVerify, verifyRequest, guardIncomingTool, requirePayment, settle, serviceDid };
+  return { handshakeChallenge, handshakeVerify, verifyRequest, guardIncomingTool, requirePayment, settle, claimAuthorization, serviceDid };
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-mcp-guard",
-  "version": "0.1.2",
+  "version": "0.2.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",
@@ -23,7 +23,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node mcp-guard.smoke.mjs && node pay.smoke.mjs && node decision-token.smoke.mjs"
+    "test": "node mcp-guard.smoke.mjs && node pay.smoke.mjs && node decision-token.smoke.mjs && node claim-authorization.smoke.mjs"
   },
   "engines": {
     "node": ">=18"

package/policy-core.mjs

@@ -58,8 +58,9 @@ ${c.output ?? ""}`.toLowerCase();
 };
 function notInAllowList(value, allowList) {
   const v = value != null ? String(value).toLowerCase().trim() : "";
+  if (v === "") return false;
   const allowed = (Array.isArray(allowList) ? allowList : []).map((x) => String(x).toLowerCase().trim());
-  return v !== "" && allowed.length > 0 && !allowed.includes(v);
+  return !allowed.includes(v);
 }
 
 // src/policy-core/atom-catalog.ts
@@ -191,7 +192,7 @@ function requiredContextFor(predicates) {
 }
 
 // src/policy-core/standards-rules.ts
-var PRECEDENCE = { allow: 0, observe: 1, escalate: 2, block: 3, suspend: 4, quarantine: 5 };
+var PRECEDENCE = { allow: 0, observe: 1, escalate: 2, block: 3, suspend: 4, quarantine: 5, decommission: 6 };
 function atomFires(atom, ctx) {
   const pred = ATOM_REGISTRY[atom.predicate];
   if (!pred) return false;
@@ -399,7 +400,7 @@ function sumEventField(events, type, field) {
 }
 
 // src/policy-core/evaluate.ts
-var PRECEDENCE2 = { allow: 0, observe: 1, escalate: 2, block: 3, suspend: 4, quarantine: 5 };
+var PRECEDENCE2 = { allow: 0, observe: 1, escalate: 2, block: 3, suspend: 4, quarantine: 5, decommission: 6 };
 function evaluate(input) {
   let decision = "allow";
   let reasonCode = "AUTHORIZED";