@metamynd/agentsafe-mcp-guard 0.3.6 → 0.6.1

package/README.md

@@ -35,8 +35,8 @@ const guard = createMcpGuard({
 });
 
 // Responder side, over your HTTP transport:
-const challenge = guard.handshakeChallenge(hello);   // POST /magp/handshake  (HELLO → CHALLENGE)
-const ready     = guard.handshakeVerify(prove);      // POST /magp/handshake  (PROVE → READY, or throws)
+const challenge = await guard.handshakeChallenge(hello);  // POST /magp/handshake  (HELLO → CHALLENGE)
+const ready     = guard.handshakeVerify(prove);           // POST /magp/handshake  (PROVE → READY, or throws)
 ```
 
 The agent drives the initiator side with `createGuard(...).handshake()` from `agentsafe-guard`.
@@ -110,6 +110,55 @@ $5,000" protection never engaged, verifier configured or not. New `requireCapabi
 an omitted capability a hard block (`CAPABILITY_REQUIRED`) instead of a silent pass-through. Both
 off by default — existing embeds are unchanged.
 
+**0.5.0 — the `keyProvider` seam
+([docs/design/agent-key-custody-local-signer-daemon-plan.md](../../docs/design/agent-key-custody-local-signer-daemon-plan.md)).**
+`serviceKey` no longer has to be a raw hex key living in this process. Pass
+`keyProvider: 'daemon'` + `daemonSocketPath` instead, and `handshakeChallenge` gets its signature
+from a separate `@metamynd/agentsafe-signer` daemon (`role: 'service'`) over a local socket — the
+key never enters this process at all. `serviceKey` (unchanged) still works exactly as before and
+remains the default. **Breaking, disclosed plainly**: `handshakeChallenge` and
+`createHandshakeInitiator(...).prove()` are now `async` (a daemon-backed provider needs a socket
+round trip); every caller needs an `await` added. New internal module `key-providers.mjs` — still
+zero external dependencies.
+
+**0.5.3 — `requireAuthorization`'s claim now actually enforces revoked authority and mandate
+expiry, and the claim-binding check closes the action axis too.** A four-client readiness review's
+P0 finding required a tested counterparty-verification pattern covering, by name, replay, wrong
+identity, wrong action, expired mandate, and revoked authority. Building the end-to-end trial
+against a real backend (not the mocked cases below) surfaced that two of those five were silently
+unenforced at the claim step itself, not just untested:
+
+- **Revoked authority.** Revoking a mandate (`POST /mandate/:ref/revoke`) only ever flipped the
+  hold's `mandate_event.status` to `voided` — it never touched the `effect_transition` chain, and
+  `markEffect`'s transition check only validated the state-machine shape (`authorized →
+  dispatching` is always syntactically legal), never the hold's own status. A resource relying on
+  `requireAuthorization` could successfully claim and execute a hold whose mandate had already been
+  revoked. Now refused with `AUTHORIZATION_VOIDED`.
+- **Expired mandate.** A hold's expiry (`isWithinHoldWindow`/the TTL) is a *derived* property —
+  nothing writes it back to the row when time passes, so the same claim step had no way to see a
+  hold was stale. Now refused with `AUTHORIZATION_EXPIRED`.
+- **Wrong action.** `claimAuthorization()`'s mismatch checks compared the claimed hold's
+  `agentDid`/`amount`/`currency`/`merchant` against the request being executed, but never `action`
+  — because the backend's claim response never carried it. A real, unclaimed authorization minted
+  for one action (e.g. `office-supplies-purchase`) could be claimed while executing a *different*
+  action at the identical agent/amount/currency/merchant — the same confused-deputy shape the 0.3.6
+  merchant check closed, one axis short. The backend now resolves and returns the hold's authorized
+  `action` on claim (backward-compatible — an older backend simply omits it, same
+  skip-when-absent tolerance as every other field here). Now refused with
+  `AUTHORIZATION_ACTION_MISMATCH`.
+
+All three are backend-side (`MandateService.markEffect`) except the action check, which also
+needed this guard to compare the new field. See
+[`docs/design/mcp-reverification-quickstart.md`](../../docs/design/mcp-reverification-quickstart.md) (§7)
+for the end-to-end trial these gaps were found and closed against.
+
+**0.5.1 — `keyProvider: 'daemon'` retries a transient connect failure.** Same fix as
+`@metamynd/agentsafe-guard` 0.9.1: on Windows the signer daemon's socket is a pool of independent
+named-pipe instances, each consumed by one connection and replaced asynchronously, so two
+signing requests close together could race that replacement window and fail with
+`DAEMON_UNREACHABLE` even though the daemon was healthy. `key-providers.mjs` now retries a
+connection that fails with `ENOENT` for up to 3 seconds before giving up. No API change.
+
 ### 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

package/agentsafe-mcp-guard.mjs

@@ -16,6 +16,7 @@ import { evaluate, buildAuthMessage, applySignedLast, operatingModeGate } from '
 import { verifyDidSignature } from './magp-did.mjs';
 import { buildPaymentRequirements, checkSettlementBinding } from './x402.mjs';
 import { verifyBundle } from './magp-policy.mjs';
+import { resolveKeyProvider } from './key-providers.mjs';
 
 /** Freshness window for signed requests and handshake nonces (spec §7.7). How far `issuedAt`
  *  may be BEHIND server time — network/processing delay. */
@@ -57,19 +58,15 @@ const CLOCK_SKEW_TOLERANCE_MS = 30 * 1000;
  *   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, requireCapability = false } = {}) {
+export function createMcpGuard({ serviceDid, serviceKey, keyProvider: keyProviderOpt, daemonSocketPath, 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
-    ? crypto.createPrivateKey({ key: Buffer.from(serviceKey, 'hex'), format: 'der', type: 'pkcs8' })
-    : null;
+  // keyProvider seam (docs/design/agent-key-custody-local-signer-daemon-plan.md): null when
+  // neither `serviceKey` nor `keyProvider` is configured — handshakeChallenge throws its own
+  // clear error only if actually called, matching the original lazy-throw behavior exactly.
+  const keyProvider = resolveKeyProvider({ keyProvider: keyProviderOpt, serviceKey, daemonSocketPath });
   const pending = new Map(); // handshakeId -> { fromDid, nonceB, expiresAt }
 
-  function sign(message) {
-    if (!privateKey) throw new Error('serviceKey is required to sign handshake messages');
-    return crypto.sign(null, Buffer.from(message, 'utf8'), privateKey).toString('hex');
-  }
-
   // --- Mutual handshake, RESPONDER side (spec §8.2) ---
   //   A → B  HELLO      { fromDid, nonceA }
   //   B → A  CHALLENGE  { toDid, nonceB, sigB(nonceA) }   ← proves B controls toDid
@@ -77,12 +74,13 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
   //   B → A  READY      { channelId }
 
   /** Step 1 (B): on HELLO, sign nonceA to prove control of serviceDid, issue nonceB. */
-  function handshakeChallenge({ fromDid, nonceA, protoVersion } = {}) {
+  async function handshakeChallenge({ fromDid, nonceA, protoVersion } = {}) {
     if (!fromDid || !nonceA) throw new Error('HELLO requires { fromDid, nonceA }');
+    if (!keyProvider) throw new Error('serviceKey (or keyProvider) is required to sign handshake messages');
     const handshakeId = crypto.randomUUID();
     const nonceB = crypto.randomUUID();
     pending.set(handshakeId, { fromDid, nonceB, expiresAt: Date.now() + FRESHNESS_MS });
-    return { handshakeId, toDid: serviceDid, nonceB, sigB: sign(nonceA), protoVersion: protoVersion ?? '1.0' };
+    return { handshakeId, toDid: serviceDid, nonceB, sigB: await keyProvider.signHandshakeNonce(nonceA), protoVersion: protoVersion ?? '1.0' };
   }
 
   /** Step 2 (B): on PROVE, verify sigA over nonceB against fromDid's key-in-DID. */
@@ -110,12 +108,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`/`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.
+   * On success, also returns the hold's OWN bound `agentDid`/`action`/`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 (or a DIFFERENT action
+   * entirely) 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' };
@@ -124,7 +122,14 @@ 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, merchant: body?.data?.merchant };
+      return {
+        claimed: true,
+        agentDid: body?.data?.agentDid,
+        action: body?.data?.action,
+        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) };
     }
@@ -253,10 +258,12 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
         // 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 (claim.action === undefined) console.warn('[mcp-guard] claim response omitted action — action binding degraded');
         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.action !== undefined && claim.action !== action) return { decision: 'block', reasonCode: 'AUTHORIZATION_ACTION_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' };
@@ -274,7 +281,17 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
    */
   function guardIncomingTool(action, handler) {
     return async (signed, ...rest) => {
-      const decision = await verifyRequest({ ...signed, action: signed?.action ?? action });
+      // The WRAPPED TOOL's own `action` is authoritative — never `signed?.action` (the caller's
+      // own claim). A Service that wraps more than one tool with ONE guard instance (the normal
+      // MCP-server shape: many tools, one guard) previously let a genuinely-valid signature for
+      // action A verify successfully — correctly, it really was valid for A — and then run
+      // action B's handler, because verifyRequest was asked to check whatever the SIGNED payload
+      // claimed instead of which wrapped function was actually being invoked. A caller with a
+      // real, cheap, in-policy authorization (e.g. a $0 read) could invoke ANY other tool sharing
+      // this guard (e.g. a wire transfer) and have it execute under that unrelated verification.
+      // Mirrors gateway.mjs's `route.action ?? signed.action` — "the route pins the action ...
+      // the client can't pick it" — for exactly the same reason, one layer down at the tool call.
+      const decision = await verifyRequest({ ...signed, action });
       // allow/observe both PERMIT the tool call; observe is permit-but-flag (SAFR §11).
       if (decision.decision !== 'allow' && decision.decision !== 'observe') {
         const err = new Error(`MCP guard ${decision.decision.toUpperCase()} "${action}": ${decision.reasonCode}`);
@@ -389,7 +406,9 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
  * then, given the responder's CHALLENGE, verifies the responder proved control of
  * its DID before producing PROVE.
  *
- * @param {{fromDid:string, sign:(msg:string)=>string}} p  sign() uses the initiator's own key
+ * @param {{fromDid:string, sign:(msg:string)=>(string|Promise<string>)}} p  sign() uses the
+ *   initiator's own key — may be sync (a raw local key) or async (e.g. a keyProvider backed by
+ *   agentsafe-signer); `prove()` awaits it either way, see key-providers.mjs.
  */
 export function createHandshakeInitiator({ fromDid, sign } = {}) {
   if (!fromDid || typeof sign !== 'function') throw new Error('createHandshakeInitiator requires { fromDid, sign }');
@@ -400,7 +419,7 @@ export function createHandshakeInitiator({ fromDid, sign } = {}) {
       return { nonceA, message: { fromDid, nonceA, protoVersion: '1.0' } };
     },
     /** Step 3 (A): verify CHALLENGE proves the responder controls toDid, then PROVE. */
-    prove({ nonceA, challenge } = {}) {
+    async prove({ nonceA, challenge } = {}) {
       const { toDid, nonceB, sigB, handshakeId } = challenge ?? {};
       if (!toDid || !nonceB || !sigB) throw new Error('malformed CHALLENGE');
       if (!verifyDidSignature(toDid, nonceA, sigB)) {
@@ -408,7 +427,7 @@ export function createHandshakeInitiator({ fromDid, sign } = {}) {
         e.name = 'HandshakeFailed';
         throw e;
       }
-      return { handshakeId, sigA: sign(nonceB), remoteDid: toDid };
+      return { handshakeId, sigA: await sign(nonceB), remoteDid: toDid };
     },
   };
 }

package/key-providers.mjs

@@ -0,0 +1,91 @@
+// key-providers.mjs — the keyProvider seam for the SERVICE side (docs/design/
+// agent-key-custody-local-signer-daemon-plan.md). Much smaller than agentsafe-guard's own copy:
+// serviceKey is only ever used for one thing (signing a handshake nonce, MAGP §8.2), so there is
+// only one provider method here, not four.
+import crypto from 'node:crypto';
+import net from 'node:net';
+import path from 'node:path';
+
+export function createStaticKeyProvider(serviceKeyHex) {
+  const privateKey = crypto.createPrivateKey({ key: Buffer.from(serviceKeyHex, 'hex'), format: 'der', type: 'pkcs8' });
+  return {
+    async signHandshakeNonce(nonce) {
+      return crypto.sign(null, Buffer.from(nonce, 'utf8'), privateKey).toString('hex');
+    },
+  };
+}
+
+/** Must match agentsafe-guard/key-providers.mjs's and agentsafe-signer/daemon.mjs's own copy — see either's own comment for why this isn't a shared import. */
+function toPlatformSocketPath(logicalPath) {
+  if (process.platform !== 'win32') return logicalPath;
+  const name = crypto.createHash('sha256').update(path.resolve(logicalPath)).digest('hex').slice(0, 32);
+  return `\\\\.\\pipe\\agentsafe-signer-${name}`;
+}
+
+const PROTOCOL_VERSION = 1;
+
+function daemonRequest(socketPath, op, params, { connectTimeoutMs = 3000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + connectTimeoutMs;
+    function attempt() {
+      const sock = net.connect(toPlatformSocketPath(socketPath));
+      const requestId = crypto.randomUUID();
+      let buf = '';
+      const cleanup = () => sock.destroy();
+      sock.once('error', (err) => {
+        cleanup();
+        // See agentsafe-guard/key-providers.mjs's own copy of this function for why: on Windows
+        // the signing socket is a pool of independent named-pipe instances, each consumed by one
+        // connection and replaced asynchronously, so a request can transiently race that
+        // replacement window (ENOENT) even though the daemon is healthy. Only ENOENT retries — a
+        // genuinely down daemon still fails fast.
+        if (err.code === 'ENOENT' && Date.now() < deadline) {
+          setTimeout(attempt, 20);
+          return;
+        }
+        reject(Object.assign(new Error(`agentsafe-signer daemon unreachable at ${socketPath}: ${err.message}`), { code: 'DAEMON_UNREACHABLE' }));
+      });
+      sock.once('connect', () => {
+        sock.write(JSON.stringify({ protocolVersion: PROTOCOL_VERSION, requestId, op, params }) + '\n');
+      });
+      sock.on('data', (chunk) => {
+        buf += chunk.toString('utf8');
+        const idx = buf.indexOf('\n');
+        if (idx === -1) return;
+        let res;
+        try {
+          res = JSON.parse(buf.slice(0, idx));
+        } catch (err) {
+          cleanup();
+          reject(err);
+          return;
+        }
+        cleanup();
+        if (res.ok) resolve(res.result);
+        else reject(Object.assign(new Error(res.error?.message || res.error?.code || 'daemon rejected request'), { code: res.error?.code }));
+      });
+    }
+    attempt();
+  });
+}
+
+/** The key never enters this process — a service-role agentsafe-signer daemon signs instead. */
+export function createDaemonKeyProvider({ socketPath }) {
+  if (!socketPath) throw new Error('createDaemonKeyProvider requires { socketPath }');
+  return {
+    async signHandshakeNonce(nonce) {
+      const { signature } = await daemonRequest(socketPath, 'sign-handshake-nonce', { nonce });
+      return signature;
+    },
+  };
+}
+
+/** Resolves a keyProvider from createMcpGuard's opts — null (not thrown) when neither
+ *  keyProvider nor serviceKey is configured, matching today's "handshakeChallenge throws only if
+ *  actually called without one" behavior rather than failing construction eagerly. */
+export function resolveKeyProvider({ keyProvider, serviceKey, daemonSocketPath } = {}) {
+  if (keyProvider && typeof keyProvider === 'object' && typeof keyProvider.signHandshakeNonce === 'function') return keyProvider;
+  if (keyProvider === 'daemon') return createDaemonKeyProvider({ socketPath: daemonSocketPath });
+  if (!serviceKey) return null;
+  return createStaticKeyProvider(serviceKey);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-mcp-guard",
-  "version": "0.3.6",
+  "version": "0.6.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",
@@ -15,6 +15,7 @@
   },
   "files": [
     "agentsafe-mcp-guard.mjs",
+    "key-providers.mjs",
     "magp-policy.mjs",
     "magp-did.mjs",
     "policy-core.mjs",
@@ -23,7 +24,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node mcp-guard.smoke.mjs && node pay.smoke.mjs && node decision-token.smoke.mjs && node claim-authorization.smoke.mjs"
+    "test": "node mcp-guard.smoke.mjs && node pay.smoke.mjs && node decision-token.smoke.mjs && node claim-authorization.smoke.mjs && node guard-incoming-tool.smoke.mjs"
   },
   "engines": {
     "node": ">=18"

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) {
@@ -454,7 +514,15 @@ 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].map((v) => escapeField(String(v))).join("|");
+  return [f.agentDid, f.action, f.amount, f.currency, f.merchant ?? "", f.resource ?? "", f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
+}
+function buildLocalDecisionMessage(f) {
+  return [f.agentDid, f.action, f.decision, f.reasonCode, f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
+}
+
+// src/policy-core/checkpoint-anchor.ts
+function buildCheckpointAnchorMessage(f) {
+  return [f.agentDid, f.checkpointHash, f.previousCheckpointHash, f.entryCount, f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
 }
 
 // src/policy-core/context.ts
@@ -513,6 +581,8 @@ export {
   asOperatingMode,
   authorityFailure,
   buildAuthMessage,
+  buildCheckpointAnchorMessage,
+  buildLocalDecisionMessage,
   canAuthorize,
   evaluate,
   evaluateBoundStandards,