@metamynd/agentsafe-mcp-guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MetaMynd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# AgentSafe MCP Guard — the service side of MAGP governance
+
+The counterpart to [`agentsafe-guard`](../agentsafe-guard) (the agent side). A Service
+(an MCP, e.g. an Amadeus flight API) is an **identity-bearing peer** under MAGP (§4.6): it
+holds its own `did:hedera` + key, completes a **mutual handshake** with the agent, and
+**enforces governance trustlessly** — it independently re-verifies and re-evaluates the
+agent's request instead of trusting the agent's own guard.
+
+- **Zero external dependencies.** Node's built-in Ed25519 (`node:crypto`) + `fetch`, plus two
+  generated, dependency-free bundles: `policy-core.mjs` (the deterministic evaluator) and
+  `magp-did.mjs` (key-in-DID verification). Regenerate with `npm run build:mcp-guard-core`.
+- **No issuer round-trip to verify identity.** The verification key is embedded in the DID
+  (§4.1.2), so the guard verifies signatures and handshakes offline.
+- **Fail-closed.** A bad signature, a stale request, a failed bundle fetch, or any error
+  yields `block`.
+
+## 1. Mutual handshake (§8.2)
+
+Each side proves control of its DID; neither calls the issuer (keys are in the DIDs).
+
+```
+A → B  HELLO      { fromDid, nonceA }
+B → A  CHALLENGE  { toDid, nonceB, sigB(nonceA) }   ← B proves it controls toDid
+A → B  PROVE      { sigA(nonceB) }                    ← A proves it controls fromDid
+B → A  READY      { channelId }
+```
+
+```js
+import { createMcpGuard } from './agentsafe-mcp-guard.mjs';
+
+const guard = createMcpGuard({
+  serviceDid: process.env.SERVICE_DID,
+  serviceKey: process.env.SERVICE_KEY,      // the MCP's Ed25519 DER key (held only by the MCP)
+  issuerApi: 'https://metamynd.ai/api/v1',  // where policy bundles are fetched from
+});
+
+// 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)
+```
+
+The agent drives the initiator side with `createGuard(...).handshake()` from `agentsafe-guard`.
+
+## 2. Trustless enforcement (§9.3, §9.6)
+
+For a value-bearing tool call the Service re-checks the agent's **signed authorize request**
+and re-evaluates policy against the agent's **issuer-hosted bundle** — the same deterministic
+`policy-core` the gate runs. It never trusts the agent's guard.
+
+```js
+// The agent presents its signed authorize request alongside the tool call.
+const decision = await guard.verifyRequest({
+  agentDid, action: 'flight-purchase', amount: 150, currency: 'USD', merchant: 'amadeus',
+  itinerary: { riskLevel: 'low' }, nonce, issuedAt, signature,
+});
+// { decision: 'allow' | 'block' | 'escalate', reasonCode }
+
+// Or wrap a tool so it runs only after verification allows (throws GovernanceBlocked otherwise):
+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);
+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).
+
+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
+```
+
+## 3. Payment binding (x402, §7a)
+
+MAGP authorizes and reserves budget; it never custodies funds (§7a.5). Value moves over
+**x402**, and this guard **binds each settlement to exactly one authorization** so a payment
+can't be reused, can't exceed the authorized amount, and can't settle without a governance
+authorization behind it. The order is **authorize-before-pay** (§7a.1):
+
+```
+1. authorize   agent → gate: reserve amount → authorizationId (allow)
+2. request     agent → Service tool call
+3. 402         Service → agent: guard.requirePayment(...) — bound to authorizationId
+4. verify      guard.verifyRequest(...) re-checks the authorization trustlessly (§2)
+5. pay         agent → Service: X-PAYMENT; guard.settle(...) verifies + settles
+6. fulfil      Service performs the action → PNR + tx hash
+7. capture     agent → gate: capture(authorizationId, amountCharged, settlementTxHash)
+```
+
+```js
+// 3 — demand payment bound to the MAGP authorization (§7a.2):
+const requirements = guard.requirePayment({
+  authorizationId, agentDid, amount: 150, payTo: SERVICE_ADDR, asset: 'USDC', resource: '/book-flight',
+});
+
+// 5 — verify the binding, then settle via your x402 facilitator (injected):
+const { settled, txHash, reasonCode } = await guard.settle({
+  requirements, authorizationId, paidAmountMinor, xPayment,
+  settleFn: async ({ xPayment }) => facilitator.settle(xPayment),  // returns { settled, txHash }
+});
+```
+
+`settle` returns `AMOUNT_MISMATCH` for an overpayment (§7a.2.2), `SETTLEMENT_REUSED` if the
+authorization already settled (anti-reuse), and `SETTLEMENT_FAILED` if the facilitator can't
+settle — all fail-closed. `requirePayment` / `settle` don't move money; the injected facilitator
+does. On the agent side, `guard.preparePayment(requirements, authorizationId)` refuses an
+**unbound** 402 and one whose authorization doesn't match the agent's own hold.
+
+**Durable anti-reuse (SAFR §34).** By default `settle` tracks settled ids in-process (single
+instance). For HA, inject a `settlementStore` that persists the claim — e.g. one backed by
+`POST /magp/settlement/{reserve,finalize,release}` — so "one settlement per authorization" holds
+across instances + restarts. `settle` **reserves before settling** (atomic claim) and **releases**
+a claim whose settlement failed, so a legitimate retry can proceed:
+
+```js
+const guard = createMcpGuard({ serviceDid, settlementStore: {
+  reserve:  (id) => post('/magp/settlement/reserve',  { authorizationId: id }).then(r => ({ ok: r.reserved, reasonCode: r.reasonCode })),
+  release:  (id) => post('/magp/settlement/release',  { authorizationId: id }),
+  finalize: (id, { txHash, amountMinor }) => post('/magp/settlement/finalize', { authorizationId: id, txHash, amountMinor }),
+}});
+```
+
+**Commitment-bound capability (decision token, §7.7/§20).** Inject `verifyCapability(signed)` and,
+when a request carries a signed capability, `guardIncomingTool` requires it to authorize **this exact
+transaction** — the host reconstructs the tx and verifies MetaMynd's signature offline (via
+`checkCapabilityBinding` from `magp-bind`), so "authorize $150, execute $5,000" is rejected in the
+prod guard, not just the demo gateway. No verifier configured → opt-in (unchanged).
+
+Holds carry an expiry (§7a.4): if not captured, the reservation auto-voids and the budget returns
+to the cap; a party can also void explicitly via `POST /policy/mandate/authorize/:id/void`.
+
+Run the self-check:
+
+```powershell
+node pay.smoke.mjs   # bound / exact / single-use / fail-closed
+```
+
+## Where this fits
+
+MetaMynd is the **control plane** (issuer/anchor): it exposes the public DID resolver
+(`GET /did/:did`, §4.4) and the policy bundle (`GET /policy/bundle/:did`, §5.3.2). The agent
+guard and this MCP guard are the **data plane**: they discover each other via DID, verify
+mutually, and evaluate governance at the edge — no per-action call to the issuer for a routine
+decision. A value-bearing action is governed by BOTH sides (§9.6): the agent's guard, then this
+guard's trustless re-check.

package/agentsafe-mcp-guard.mjs

@@ -0,0 +1,303 @@
+// agentsafe-mcp-guard.mjs — the SERVICE (MCP) side of MAGP governance.
+//
+// A Service is an identity-bearing peer (MAGP §4.6). This guard lets an MCP:
+//   1. complete the mutual handshake (§8.2) — prove it controls its DID and verify
+//      the counterparty controls theirs, with NO calls to the issuer (keys are in
+//      the DIDs, §4.1.2); and
+//   2. enforce TRUSTLESSLY (§9.3, §9.6) — independently re-evaluate the agent's
+//      signed authorize request against the agent's issuer-hosted policy bundle
+//      using the same deterministic policy-core the gate runs. The Service never
+//      has to trust the agent's own guard.
+//
+// Dependencies are the two generated, zero-external-dependency bundles:
+//   policy-core.mjs (deterministic evaluator) and magp-did.mjs (key-in-DID verify).
+import crypto from 'node:crypto';
+import { evaluate, buildAuthMessage, applySignedLast, operatingModeGate } from './policy-core.mjs';
+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). */
+const FRESHNESS_MS = 5 * 60 * 1000;
+
+/**
+ * @param {object} cfg
+ * @param {string}  cfg.serviceDid  the MCP's own did:hedera
+ * @param {string} [cfg.serviceKey] the MCP's Ed25519 private key (Hedera DER hex) — needed to sign handshakes
+ * @param {string} [cfg.issuerApi]  the issuer API base (e.g. https://metamynd.ai/api/v1) to fetch policy bundles
+ * @param {(agentDid:string)=>Promise<object>} [cfg.fetchBundle] override bundle loading (tests / caching)
+ * @param {string} [cfg.policyPublicKey] MetaMynd's Ed25519 policy-signing key (hex, from
+ *   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.
+ */
+export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle, policyPublicKey, settlementStore, verifyCapability } = {}) {
+  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;
+  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
+  //   A → B  PROVE      { sigA(nonceB) }                   ← proves A controls fromDid
+  //   B → A  READY      { channelId }
+
+  /** Step 1 (B): on HELLO, sign nonceA to prove control of serviceDid, issue nonceB. */
+  function handshakeChallenge({ fromDid, nonceA, protoVersion } = {}) {
+    if (!fromDid || !nonceA) throw new Error('HELLO requires { fromDid, nonceA }');
+    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' };
+  }
+
+  /** Step 2 (B): on PROVE, verify sigA over nonceB against fromDid's key-in-DID. */
+  function handshakeVerify({ handshakeId, sigA } = {}) {
+    const st = pending.get(handshakeId);
+    pending.delete(handshakeId); // single-use, whatever the outcome
+    if (!st) throw new Error('unknown or already-used handshake');
+    if (Date.now() > st.expiresAt) throw new Error('handshake expired');
+    if (!verifyDidSignature(st.fromDid, st.nonceB, sigA)) {
+      const e = new Error('handshake PROVE signature invalid');
+      e.name = 'HandshakeFailed';
+      throw e;
+    }
+    return { channelId: crypto.randomUUID(), remoteDid: st.fromDid };
+  }
+
+  // --- Trustless re-evaluation (spec §9.3, §9.6) ---
+
+  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');
+    const res = await fetch(`${base}/policy/bundle/${encodeURIComponent(agentDid)}`);
+    const body = await res.json().catch(() => null);
+    if (!res.ok || !body?.data) throw new Error(`policy bundle fetch failed (HTTP ${res.status})`);
+    // Live containment (Phase 2.4) + operating mode (Phase 2.5b) ride as SIBLINGS of the
+    // signed bundle. Expose them as NON-ENUMERABLE props so they never enter the
+    // canonicalization verifyBundle signs over (Object.keys skips them) — the signature
+    // stays valid, the flags are readable.
+    Object.defineProperty(body.data, '__contained', { value: body?.contained ?? null, enumerable: false, configurable: true });
+    Object.defineProperty(body.data, '__operatingMode', { value: body?.operatingMode ?? null, enumerable: false, configurable: true });
+    return body.data;
+  }
+
+  /** 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 mandate = (bundle.mandates ?? []).find((m) => m.action === action)?.document;
+    return evaluate({
+      standards: (bundle.standards ?? []).map((s) => ({ standardKey: s.key, document: s.document })),
+      sops: (bundle.sops ?? []).map((s) => ({ standardKey: `sop:${s.id}`, document: s.document })),
+      mandate,
+      context: applySignedLast(itinerary, { action, agentDid, amount }),
+      mandateRequest: mandate
+        ? {
+            target: action,
+            now: now ?? new Date().toISOString(),
+            values: applySignedLast(itinerary, {
+              'mm:payAmount': amount,
+              'mm:cumulativeSpend': cumulativeSpend,
+              'mm:merchant': merchant,
+            }),
+          }
+        : undefined,
+    });
+  }
+
+  /**
+   * Verify an agent's presented signed authorize request, then re-evaluate policy
+   * locally against the agent's issuer-hosted bundle. Fails CLOSED: any bad
+   * signature, staleness, fetch error, or evaluation error returns a block.
+   * @param {{agentDid,action,amount?,currency?,merchant?,itinerary?,nonce,issuedAt,signature}} signed
+   * @returns {Promise<{decision:'allow'|'observe'|'block'|'escalate'|'suspend'|'quarantine',reasonCode:string|null}>}
+   */
+  async function verifyRequest(signed = {}) {
+    try {
+      const { agentDid, action, amount = 0, currency = 'USD', merchant = '', nonce, issuedAt, signature } = signed;
+      if (!agentDid || !action || !nonce || !issuedAt || !signature) {
+        return { decision: 'block', reasonCode: 'MALFORMED_REQUEST' };
+      }
+      // 1. Signature over the canonical message (§7.3), verified via key-in-DID (§4.1.2).
+      const message = buildAuthMessage({ agentDid, action, amount, currency, merchant, nonce, issuedAt });
+      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.)
+      const ts = Date.parse(issuedAt);
+      if (Number.isNaN(ts) || Math.abs(Date.now() - ts) > FRESHNESS_MS) {
+        return { decision: 'block', reasonCode: 'REQUEST_EXPIRED' };
+      }
+      // 3. Re-evaluate against the issuer-hosted bundle (fetched over TLS from the issuer).
+      const bundle = await loadBundle(agentDid);
+      if (bundle?.subject && bundle.subject !== agentDid) {
+        return { decision: 'block', reasonCode: 'BUNDLE_SUBJECT_MISMATCH' };
+      }
+      // 3a. Containment (Phase 2.4): a server-contained agent is refused regardless of
+      // the action — the tool provider will not serve a suspended/quarantined agent.
+      const contained = bundle?.__contained;
+      if (contained && contained.status) {
+        const decision = contained.status === 'quarantined' ? 'quarantine' : 'suspend';
+        const reasonCode = contained.status === 'quarantined' ? 'AGENT_QUARANTINED' : 'AGENT_SUSPENDED';
+        return { decision, reasonCode };
+      }
+      // 3a.5. Operating-mode autonomy ladder (Phase 2.5b): the trust-driven posture rides
+      // as a non-enumerable sibling. READ_ONLY refuses a value-bearing action up-front;
+      // SUPERVISED/RESTRICTED only ESCALATE, applied to the verdict below so a rule block
+      // still outranks the floor (most-restrictive-wins, mirroring the gate).
+      const modeGate = operatingModeGate(bundle?.__operatingMode?.mode, { amount, riskLevel: signed?.itinerary?.riskLevel });
+      if (modeGate.decision === 'block') return { decision: 'block', reasonCode: modeGate.reasonCode };
+      // 3b. Signed-bundle verification + risk-tiered fail-closed (Phase F, §5.3.2/§5.3.3). When a
+      // policy key is configured, a value-bearing action (amount > 0) MUST fail closed on an
+      // unsigned / tampered / stale bundle — so enforcement needs no live MetaMynd. A bad SIGNATURE
+      // is a hard fail even for non-value reads.
+      if (policyPublicKey) {
+        const v = verifyBundle(bundle, { publicKey: policyPublicKey, valueBearing: Number(amount) > 0 });
+        if (!v.ok) return { decision: 'block', reasonCode: v.reasonCode };
+      }
+      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 };
+      }
+      return verdict;
+    } catch (err) {
+      return { decision: 'block', reasonCode: 'GUARD_ERROR', error: String(err?.message ?? err) };
+    }
+  }
+
+  /**
+   * Wrap a Service tool so it runs only after trustless verification allows. The
+   * agent's signed request must be passed as the first argument. Throws
+   * GovernanceBlocked on any non-allow decision.
+   */
+  function guardIncomingTool(action, handler) {
+    return async (signed, ...rest) => {
+      const decision = await verifyRequest({ ...signed, action: signed?.action ?? 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}`);
+        err.name = 'GovernanceBlocked';
+        err.governance = decision;
+        throw err;
+      }
+      // Commitment-bound capability (decision token, §7.7/§20, Phase-4 PR-5). When the request
+      // carries a signed capability AND a verifier is configured, the token must authorize THIS
+      // exact transaction — the host reconstructs the tx + verifies MetaMynd's signature OFFLINE,
+      // so "authorize $150, execute $5,000" (authorize-A / execute-B) is rejected HERE, in the
+      // prod guard, not just the demo gateway. No verifier configured → unchanged (opt-in).
+      if (signed?.capability && typeof verifyCapability === 'function') {
+        let bind;
+        try { bind = await verifyCapability(signed); }
+        catch (err) { bind = { ok: false, reasonCode: 'CAPABILITY_CHECK_ERROR', error: String(err?.message ?? err) }; }
+        if (!bind?.ok) {
+          const err = new Error(`MCP guard CAPABILITY "${action}": ${bind?.reasonCode ?? 'CAPABILITY_INVALID'}`);
+          err.name = 'GovernanceBlocked';
+          err.governance = { decision: 'block', reasonCode: bind?.reasonCode ?? 'CAPABILITY_INVALID' };
+          throw err;
+        }
+      }
+      if (decision.decision === 'observe') {
+        console.warn(`[mcp-guard] OBSERVE "${action}": ${decision.reasonCode} — served under monitoring`);
+      }
+      return handler(signed, ...rest);
+    };
+  }
+
+  // --- x402 payment binding (spec §7a). MAGP authorizes; x402 moves the money;
+  //     this binds a settlement to exactly one authorization. No custody (§7a.5). ---
+  // Durable anti-reuse (Phase-4 PR-5): a `settlementStore` may be injected to persist the
+  // "one settlement per authorization" invariant across instances + restarts (SAFR §34) —
+  // e.g. one backed by POST /magp/settlement/{reserve,finalize,release}. The DEFAULT keeps the
+  // original in-process behaviour so existing embeds are unchanged; it is single-instance only.
+  const store = settlementStore ?? (() => {
+    const claimed = new Set();
+    return {
+      async reserve(id) { if (claimed.has(id)) return { ok: false, reasonCode: 'SETTLEMENT_REUSED' }; claimed.add(id); return { ok: true }; },
+      async release(id) { claimed.delete(id); },
+      async finalize() { /* the id stays claimed */ },
+    };
+  })();
+
+  /**
+   * Build the 402 PaymentRequirements bound to a MAGP authorization (§7a.2). The
+   * Service returns this after a value-bearing tool call whose authorization it has
+   * verified (step 4 of §7a.1), before it will settle.
+   * @param {{authorizationId,agentDid,amount,payTo,asset,resource,network?,decimals?}} p
+   */
+  function requirePayment(p) {
+    return buildPaymentRequirements(p);
+  }
+
+  /**
+   * Verify a presented settlement is bound to the authorization, then settle via the
+   * injected facilitator (§7a.3). Enforces the amount binding (§7a.2.2) and anti-reuse
+   * (one settlement per authorizationId). `settleFn` performs the actual x402
+   * verify+settle and MUST return { settled:true, txHash } on success.
+   * @returns {Promise<{settled:boolean, txHash?:string, reasonCode:string}>}
+   */
+  async function settle({ requirements, authorizationId, paidAmountMinor, xPayment, settleFn } = {}) {
+    const binding = checkSettlementBinding(requirements, { authorizationId, paidAmountMinor });
+    if (!binding.ok) return { settled: false, reasonCode: binding.reasonCode };
+    if (typeof settleFn !== 'function') return { settled: false, reasonCode: 'NO_FACILITATOR' };
+    // ATOMICALLY claim the authorization BEFORE settling (closes the check-then-settle race that
+    // the old in-memory Set had: two concurrent settles could both pass a read-only check). A
+    // durable store makes this correct across instances/restarts.
+    const reserved = await store.reserve(authorizationId);
+    if (!reserved?.ok) return { settled: false, reasonCode: reserved?.reasonCode ?? 'SETTLEMENT_REUSED' };
+    let result;
+    try {
+      result = await settleFn({ requirements, authorizationId, paidAmountMinor, xPayment });
+    } catch (err) {
+      await store.release(authorizationId); // settle threw → free the claim so a legit retry works
+      return { settled: false, reasonCode: 'SETTLEMENT_FAILED', error: String(err?.message ?? err) };
+    }
+    if (!result?.settled || !result?.txHash) {
+      await store.release(authorizationId); // facilitator declined → free the claim
+      return { settled: false, reasonCode: 'SETTLEMENT_FAILED' };
+    }
+    await store.finalize?.(authorizationId, { txHash: result.txHash, amountMinor: paidAmountMinor });
+    return { settled: true, txHash: result.txHash, reasonCode: 'SETTLED' };
+  }
+
+  return { handshakeChallenge, handshakeVerify, verifyRequest, guardIncomingTool, requirePayment, settle, serviceDid };
+}
+
+/**
+ * Mutual-handshake INITIATOR helper (the agent/peer side of §8.2). Drives HELLO
+ * 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
+ */
+export function createHandshakeInitiator({ fromDid, sign } = {}) {
+  if (!fromDid || typeof sign !== 'function') throw new Error('createHandshakeInitiator requires { fromDid, sign }');
+  return {
+    /** Step 0 (A): build HELLO; keep nonceA to bind the responder's CHALLENGE. */
+    hello() {
+      const nonceA = crypto.randomUUID();
+      return { nonceA, message: { fromDid, nonceA, protoVersion: '1.0' } };
+    },
+    /** Step 3 (A): verify CHALLENGE proves the responder controls toDid, then PROVE. */
+    prove({ nonceA, challenge } = {}) {
+      const { toDid, nonceB, sigB, handshakeId } = challenge ?? {};
+      if (!toDid || !nonceB || !sigB) throw new Error('malformed CHALLENGE');
+      if (!verifyDidSignature(toDid, nonceA, sigB)) {
+        const e = new Error('responder failed to prove control of its DID');
+        e.name = 'HandshakeFailed';
+        throw e;
+      }
+      return { handshakeId, sigA: sign(nonceB), remoteDid: toDid };
+    },
+  };
+}

package/magp-did.mjs

@@ -0,0 +1,157 @@
+// GENERATED from backend/src/features/magp/did.ts — do not edit. Regenerate: npm run build:mcp-guard-core
+
+// src/features/magp/did.ts
+import crypto from "node:crypto";
+
+// src/features/agent-identity/did.util.ts
+var BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+function base58(bytes) {
+  let zeros = 0;
+  while (zeros < bytes.length && bytes[zeros] === 0) zeros++;
+  const digits = [];
+  for (let i = zeros; i < bytes.length; i++) {
+    let carry = bytes[i];
+    for (let j = 0; j < digits.length; j++) {
+      carry += digits[j] << 8;
+      digits[j] = carry % 58;
+      carry = carry / 58 | 0;
+    }
+    while (carry > 0) {
+      digits.push(carry % 58);
+      carry = carry / 58 | 0;
+    }
+  }
+  let out = "";
+  for (let k = 0; k < zeros; k++) out += BASE58_ALPHABET[0];
+  for (let q = digits.length - 1; q >= 0; q--) out += BASE58_ALPHABET[digits[q]];
+  return out;
+}
+function multibaseBase58btc(bytes) {
+  return "z" + base58(bytes);
+}
+function buildHederaDid(network, publicKeyBytes, topicId) {
+  return `did:hedera:${network}:${multibaseBase58btc(publicKeyBytes)}_${topicId}`;
+}
+function base58Decode(str) {
+  const bytes = [0];
+  for (const ch of str) {
+    const value = BASE58_ALPHABET.indexOf(ch);
+    if (value === -1) throw new Error(`invalid base58 character '${ch}'`);
+    let carry = value;
+    for (let j = 0; j < bytes.length; j++) {
+      carry += bytes[j] * 58;
+      bytes[j] = carry & 255;
+      carry >>= 8;
+    }
+    while (carry > 0) {
+      bytes.push(carry & 255);
+      carry >>= 8;
+    }
+  }
+  let zeros = 0;
+  for (let k = 0; k < str.length && str[k] === BASE58_ALPHABET[0]; k++) zeros++;
+  const out = new Uint8Array(zeros + bytes.length);
+  for (let i = 0; i < bytes.length; i++) out[zeros + i] = bytes[bytes.length - 1 - i];
+  return out;
+}
+function parseHederaDid(did) {
+  const m = /^did:hedera:(mainnet|testnet|previewnet|devnet):(z[1-9A-HJ-NP-Za-km-z]+)_(\d+\.\d+\.\d+)$/.exec(did ?? "");
+  if (!m) return null;
+  const [, network, publicKeyMultibase, topicId] = m;
+  let publicKeyBytes;
+  try {
+    publicKeyBytes = base58Decode(publicKeyMultibase.slice(1));
+  } catch {
+    return null;
+  }
+  if (publicKeyBytes.length !== 32) return null;
+  return { network, publicKeyMultibase, publicKeyBytes, topicId };
+}
+var ED25519_MULTICODEC = Uint8Array.of(237, 1);
+function buildDidKey(publicKeyBytes) {
+  const prefixed = new Uint8Array(ED25519_MULTICODEC.length + publicKeyBytes.length);
+  prefixed.set(ED25519_MULTICODEC, 0);
+  prefixed.set(publicKeyBytes, ED25519_MULTICODEC.length);
+  return `did:key:${multibaseBase58btc(prefixed)}`;
+}
+function parseDidKey(did) {
+  const m = /^did:key:(z[1-9A-HJ-NP-Za-km-z]+)$/.exec(did ?? "");
+  if (!m) return null;
+  const multibase = m[1];
+  let decoded;
+  try {
+    decoded = base58Decode(multibase.slice(1));
+  } catch {
+    return null;
+  }
+  if (decoded.length !== ED25519_MULTICODEC.length + 32) return null;
+  if (decoded[0] !== ED25519_MULTICODEC[0] || decoded[1] !== ED25519_MULTICODEC[1]) return null;
+  return { method: "key", publicKeyMultibase: multibase, publicKeyBytes: decoded.slice(ED25519_MULTICODEC.length) };
+}
+function didPublicKeyBytes(did) {
+  return parseHederaDid(did)?.publicKeyBytes ?? parseDidKey(did)?.publicKeyBytes ?? null;
+}
+
+// src/features/magp/did.ts
+var ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+function ed25519KeyFromRaw(raw) {
+  const der = Buffer.concat([ED25519_SPKI_PREFIX, Buffer.from(raw)]);
+  return crypto.createPublicKey({ key: der, format: "der", type: "spki" });
+}
+function verifyDidSignature(did, message, signatureHex) {
+  const publicKeyBytes = didPublicKeyBytes(did);
+  if (!publicKeyBytes) return false;
+  try {
+    const key = ed25519KeyFromRaw(publicKeyBytes);
+    return crypto.verify(null, Buffer.from(message, "utf8"), key, Buffer.from(signatureHex, "hex"));
+  } catch {
+    return false;
+  }
+}
+function buildDidDocument(did, service) {
+  const hedera = parseHederaDid(did);
+  const key = hedera ? null : parseDidKey(did);
+  if (!hedera && !key) return null;
+  const publicKeyMultibase = hedera ? hedera.publicKeyMultibase : key.publicKeyMultibase;
+  const fragment = hedera ? "#did-root-key" : `#${key.publicKeyMultibase}`;
+  const vmId = `${did}${fragment}`;
+  const doc = {
+    "@context": ["https://www.w3.org/ns/did/v1"],
+    id: did,
+    controller: did,
+    verificationMethod: [
+      {
+        id: vmId,
+        type: "Ed25519VerificationKey2020",
+        controller: did,
+        publicKeyMultibase
+      }
+    ],
+    authentication: [vmId]
+  };
+  if (service) {
+    doc.service = [
+      {
+        id: `${did}#magp`,
+        type: "MAGPEndpoint",
+        serviceEndpoint: service.serviceEndpoint,
+        channels: service.channels,
+        protoVersions: service.protoVersions
+      }
+    ];
+  }
+  return doc;
+}
+export {
+  base58,
+  base58Decode,
+  buildDidDocument,
+  buildDidKey,
+  buildHederaDid,
+  didPublicKeyBytes,
+  ed25519KeyFromRaw,
+  multibaseBase58btc,
+  parseDidKey,
+  parseHederaDid,
+  verifyDidSignature
+};

package/magp-policy.mjs

@@ -0,0 +1,104 @@
+// magp-policy.mjs — MAGP Phase F: signed policy bundles + staleness + risk-tiered fail-closed.
+//
+// The policy bundle (§5.3.2) binds an agent's DID to the exact Standards/SOPs/mandate governing it,
+// so a guard fetches ONE document and evaluates locally (trustless re-eval, §9.6). Until now the
+// bundle was only hash-addressed + TLS-trusted; this adds a real **Ed25519 signature** over the
+// bundle, so a guard can verify authenticity + integrity + freshness from ANY source — a cache, a
+// CDN, or a Hedera mirror — with **no live MetaMynd call** (the Phase F exit: no MetaMynd dependence
+// for per-request enforcement).
+//
+// Risk-tiered fail-closed (§5.3.3): a value-bearing action MUST fail closed on an unsigned,
+// tampered, or stale (past `maxStaleness`) bundle; a non-value read may proceed (a bad *signature*
+// is always a hard fail). Zero dependencies — node:crypto Ed25519 only.
+import crypto from 'node:crypto';
+
+// ── canonicalization (deterministic bytes for signing) ────────────────────────────────────────
+function canonicalJson(v) {
+  if (v === null || typeof v !== 'object') return JSON.stringify(v ?? null);
+  if (Array.isArray(v)) return '[' + v.map(canonicalJson).join(',') + ']';
+  const keys = Object.keys(v).filter((k) => v[k] !== undefined).sort();
+  return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(v[k])).join(',') + '}';
+}
+/** The exact bytes signed/verified: the bundle WITHOUT its `proof` field, canonicalized. */
+function signingBytes(bundle) {
+  const { proof, ...rest } = bundle;
+  return Buffer.from('MAGP-POLICY-BUNDLE-v1\x00' + canonicalJson(rest), 'utf8');
+}
+
+// ── keys (node:crypto Ed25519; accept KeyObject or raw hex) ───────────────────────────────────
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+/** Build an Ed25519 public KeyObject from a raw 32-byte hex key (as published by the pubkey endpoint). */
+export function publicKeyFromRawHex(hex) {
+  const raw = Buffer.from(String(hex).replace(/^0x/, ''), 'hex');
+  return crypto.createPublicKey({ key: Buffer.concat([ED25519_SPKI_PREFIX, raw]), format: 'der', type: 'spki' });
+}
+const toPublicKey = (k) => (typeof k === 'string' ? publicKeyFromRawHex(k) : k);
+/** The raw 32-byte public key (hex) for an Ed25519 KeyObject — what a service publishes. */
+export function rawPublicKeyHex(keyObject) {
+  const der = keyObject.export({ format: 'der', type: 'spki' });
+  return Buffer.from(der.subarray(der.length - 32)).toString('hex');
+}
+
+// ── sign / verify ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Sign a policy bundle (issuer side). `privateKey` is an Ed25519 KeyObject. Returns the bundle with
+ * a real `proof`: an Ed25519 signature over the bundle, plus the verification key + timestamps.
+ */
+export function signBundle(bundle, privateKey, { verificationMethod = null } = {}) {
+  const base = { ...bundle };
+  delete base.proof;
+  const signature = crypto.sign(null, signingBytes(base), privateKey).toString('hex');
+  return {
+    ...base,
+    proof: {
+      type: 'Ed25519Signature2020',
+      created: bundle.issuedAt ?? null,
+      verificationMethod,
+      publicKeyHex: rawPublicKeyHex(crypto.createPublicKey(privateKey)),
+      signature,
+    },
+  };
+}
+
+/** Parse an ISO-8601 duration like `PT10M` / `PT1H30M` / `PT45S` to milliseconds. */
+export function parseDurationMs(iso) {
+  const m = /^PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?$/.exec(String(iso ?? ''));
+  if (!m) return null;
+  return ((Number(m[1] || 0) * 3600) + (Number(m[2] || 0) * 60) + Number(m[3] || 0)) * 1000;
+}
+
+/**
+ * Verify a signed bundle and apply the risk tier. Returns
+ * `{ ok, reasonCode, ageMs, maxStalenessMs, signed }`.
+ *   • a present-but-invalid signature → POLICY_BUNDLE_SIGNATURE_INVALID (hard fail, any tier)
+ *   • unsigned → POLICY_BUNDLE_UNSIGNED (fail closed only for value-bearing)
+ *   • stale past maxStaleness → POLICY_BUNDLE_STALE (fail closed only for value-bearing)
+ *   • otherwise → POLICY_BUNDLE_OK
+ *
+ * @param {object} opts { publicKey?, nowMs?, valueBearing?, maxStalenessMs? }
+ */
+export function verifyBundle(bundle, opts = {}) {
+  const nowMs = opts.nowMs ?? Date.now();
+  const valueBearing = !!opts.valueBearing;
+  const sig = bundle?.proof?.signature;
+  // The verifier's trusted key wins; else fall back to the key the bundle advertises (still checked
+  // for freshness, but a caller SHOULD pin publicKey to a MetaMynd key it trusts).
+  const keyMaterial = opts.publicKey ?? bundle?.proof?.publicKeyHex ?? null;
+
+  if (!sig || !keyMaterial) {
+    return { ok: !valueBearing, reasonCode: 'POLICY_BUNDLE_UNSIGNED', ageMs: null, maxStalenessMs: null, signed: false };
+  }
+  let sigOk = false;
+  try { sigOk = crypto.verify(null, signingBytes(bundle), toPublicKey(keyMaterial), Buffer.from(sig, 'hex')); } catch { sigOk = false; }
+  if (!sigOk) return { ok: false, reasonCode: 'POLICY_BUNDLE_SIGNATURE_INVALID', ageMs: null, maxStalenessMs: null, signed: true };
+
+  const maxStalenessMs = opts.maxStalenessMs ?? parseDurationMs(bundle.maxStaleness) ?? null;
+  const issuedMs = Date.parse(bundle.issuedAt);
+  const ageMs = Number.isFinite(issuedMs) ? nowMs - issuedMs : null;
+  const stale = maxStalenessMs != null && ageMs != null && ageMs > maxStalenessMs;
+  if (stale) return { ok: !valueBearing, reasonCode: 'POLICY_BUNDLE_STALE', ageMs, maxStalenessMs, signed: true };
+
+  return { ok: true, reasonCode: 'POLICY_BUNDLE_OK', ageMs, maxStalenessMs, signed: true };
+}
+
+export const _policy = { canonicalJson, signingBytes };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@metamynd/agentsafe-mcp-guard",
+  "version": "0.1.0",
+  "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 — so an agent that ignores its own guard still cannot make your service act.",
+  "type": "module",
+  "main": "./agentsafe-mcp-guard.mjs",
+  "module": "./agentsafe-mcp-guard.mjs",
+  "exports": {
+    ".": "./agentsafe-mcp-guard.mjs",
+    "./policy": "./magp-policy.mjs",
+    "./policy-core": "./policy-core.mjs",
+    "./did": "./magp-did.mjs",
+    "./x402": "./x402.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "agentsafe-mcp-guard.mjs",
+    "magp-policy.mjs",
+    "magp-did.mjs",
+    "policy-core.mjs",
+    "x402.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node mcp-guard.smoke.mjs && node pay.smoke.mjs && node decision-token.smoke.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "agent",
+    "agents",
+    "governance",
+    "authorization",
+    "trustless",
+    "zero-trust",
+    "ed25519",
+    "did",
+    "x402",
+    "magp",
+    "metamynd",
+    "agentsafe"
+  ],
+  "author": "MetaMynd",
+  "license": "MIT",
+  "homepage": "https://metamynd.ai/en/developers/spec",
+  "bugs": {
+    "url": "https://metamynd.ai/en/support/contact"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/policy-core.mjs

@@ -0,0 +1,490 @@
+// GENERATED from backend/src/policy-core — do not edit. Regenerate: npm run build:mcp-guard-core
+
+// src/policy-core/atom-registry.ts
+var RISK_RANK = { low: 0, medium: 1, high: 2, critical: 3 };
+var ATOM_REGISTRY = {
+  "data-source-not-approved": (c, cfg) => !!c.dataSourceId && !(cfg?.approved ?? []).includes(String(c.dataSourceId)),
+  "consent-missing": (c) => c.consent === false,
+  "risk-at-or-above": (c, cfg) => {
+    const have = RISK_RANK[String(c.riskLevel)];
+    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),
+  // 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),
+  // 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) => {
+    const hay = `${c.prompt ?? ""}
+${c.output ?? ""}`.toLowerCase();
+    const terms = (cfg?.terms ?? []).map((t) => String(t).toLowerCase());
+    return terms.some((t) => t.length > 0 && hay.includes(t));
+  },
+  // --- Compliance atoms. Allow-list atoms fire when the context field is PRESENT
+  //     and NOT allowed (consistent with data-source-not-approved: a missing field
+  //     does not fire — the atom's requiredContext documents what to supply). ---
+  "jurisdiction-not-allowed": (c, cfg) => notInAllowList(c.jurisdiction, cfg?.allowed),
+  "data-residency-violation": (c, cfg) => notInAllowList(c.dataResidency, cfg?.allowedRegions),
+  "model-not-allowed": (c, cfg) => notInAllowList(c.model, cfg?.allowed),
+  "tool-not-allowed": (c, cfg) => notInAllowList(c.tool, cfg?.allowed),
+  "pii-present": (c) => c.piiPresent === true,
+  "rate-limit-exceeded": (c, cfg) => typeof c.callCount === "number" && c.callCount > Number(cfg?.max ?? 0),
+  // --- Evidence-quality atoms (SAFR §24). Unlike the allow-list atoms, these fire on ABSENCE:
+  //     a REQUIRE semantic — "the action must be backed by this evidence; if it isn't, fire"
+  //     (author with escalate/block). Opt-in: they only run when a rule keys them. ---
+  // Fires when any REQUIRED evidence type is not among the attested `evidenceTypes` (missing
+  // evidence — including none supplied at all → all required missing → fires).
+  "evidence-requirement": (c, cfg) => {
+    const required = (cfg?.required ?? []).map((t) => String(t).toLowerCase().trim()).filter(Boolean);
+    if (required.length === 0) return false;
+    const have = new Set((Array.isArray(c.evidenceTypes) ? c.evidenceTypes : []).map((t) => String(t).toLowerCase().trim()));
+    return required.some((r) => !have.has(r));
+  },
+  // Fires when a required minimum confidence (min > 0) is not met — the attested confidence is
+  // below it, or absent (a required confidence that was never supplied fails the bar). A min of
+  // 0 / unset is no requirement and never fires.
+  "evidence-confidence-below": (c, cfg) => {
+    const min = Number(cfg?.min ?? 0);
+    if (!(min > 0)) return false;
+    return typeof c.evidenceConfidence !== "number" || c.evidenceConfidence < min;
+  },
+  // Trust guidance (MetaMynd Trust Index / HCS-28). Fires when the counterparty's trust score is
+  // below a soft REVIEW line — intended to author an ESCALATE (route to a human), NOT a hard block.
+  // The score is server-derived (signed-last) so the agent's itinerary can't fake it; when no score
+  // is present (e.g. no counterparty resolved) the atom simply does not fire — no guidance.
+  "hol-trust-below-review": (c, cfg) => typeof c.holTrustScore === "number" && c.holTrustScore < Number(cfg?.reviewBelow ?? 60)
+};
+function notInAllowList(value, allowList) {
+  const v = value != null ? String(value).toLowerCase().trim() : "";
+  const allowed = (Array.isArray(allowList) ? allowList : []).map((x) => String(x).toLowerCase().trim());
+  return v !== "" && allowed.length > 0 && !allowed.includes(v);
+}
+
+// src/policy-core/atom-catalog.ts
+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" }],
+    requiredContext: ["amount"]
+  },
+  {
+    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"]
+  },
+  {
+    predicate: "risk-at-or-above",
+    label: "Risk at or above level",
+    description: "Fires when the assessed risk level is at or above the configured threshold.",
+    config: [
+      {
+        key: "level",
+        type: "enum",
+        required: true,
+        description: "Threshold risk level",
+        options: ["low", "medium", "high", "critical"]
+      }
+    ],
+    requiredContext: ["riskLevel"]
+  },
+  {
+    predicate: "data-source-not-approved",
+    label: "Data source not approved",
+    description: "Fires when the action uses a data source not on the approved list.",
+    config: [
+      { key: "approved", type: "string[]", required: true, description: "Allow-list of approved data source ids" }
+    ],
+    requiredContext: ["dataSourceId"]
+  },
+  {
+    predicate: "consent-missing",
+    label: "Consent missing",
+    description: "Fires when explicit consent is absent for the action.",
+    config: [],
+    requiredContext: ["consent"]
+  },
+  {
+    predicate: "text-matches",
+    label: "Text contains prohibited terms",
+    description: "Fires when the prompt or output contains any of the configured terms.",
+    config: [{ key: "terms", type: "string[]", required: true, description: "Terms that must not appear" }],
+    requiredContext: ["prompt", "output"]
+  },
+  {
+    predicate: "jurisdiction-not-allowed",
+    label: "Jurisdiction not allowed",
+    description: "Fires when the action's jurisdiction is not on the allow-list.",
+    config: [{ key: "allowed", type: "string[]", required: true, description: "Allowed jurisdictions (e.g. US, MY, EU)" }],
+    requiredContext: ["jurisdiction"]
+  },
+  {
+    predicate: "data-residency-violation",
+    label: "Data residency violation",
+    description: "Fires when data would be processed in a region not on the allow-list.",
+    config: [{ key: "allowedRegions", type: "string[]", required: true, description: "Allowed processing regions" }],
+    requiredContext: ["dataResidency"]
+  },
+  {
+    predicate: "model-not-allowed",
+    label: "LLM model not allowed",
+    description: "Fires when the agent uses an LLM model not on the approved list.",
+    config: [{ key: "allowed", type: "string[]", required: true, description: "Approved model ids" }],
+    requiredContext: ["model"]
+  },
+  {
+    predicate: "tool-not-allowed",
+    label: "Tool not allowed",
+    description: "Fires when the agent invokes a tool/function not on the approved list.",
+    config: [{ key: "allowed", type: "string[]", required: true, description: "Approved tool names" }],
+    requiredContext: ["tool"]
+  },
+  {
+    predicate: "pii-present",
+    label: "PII present",
+    description: "Fires when the action is flagged as involving personal data (PII).",
+    config: [],
+    requiredContext: ["piiPresent"]
+  },
+  {
+    predicate: "rate-limit-exceeded",
+    label: "Rate limit exceeded",
+    description: "Fires when the rolling call count exceeds a configured maximum.",
+    config: [{ key: "max", type: "number", required: true, description: "Maximum allowed calls" }],
+    requiredContext: ["callCount"]
+  },
+  {
+    predicate: "hol-trust-below-review",
+    label: "Counterparty trust below review line",
+    description: "Routes to human review when the counterparty's MetaMynd Trust Index (HCS-28) score is below a soft review line. Guidance, not a hard block \u2014 author it with an ESCALATE decision. The score is resolved server-side; no counterparty score \u2192 the atom does not fire.",
+    config: [{ key: "reviewBelow", type: "number", required: true, description: "Trust score (0\u2013100) below which a human is asked to decide" }],
+    requiredContext: ["holTrustScore"]
+  },
+  {
+    predicate: "evidence-requirement",
+    label: "Required evidence missing",
+    description: "Fires when the action is not backed by every REQUIRED evidence type the agent attests to in `evidenceTypes` (missing evidence \u2014 including none supplied). A REQUIRE control (SAFR \xA724): author it with ESCALATE or BLOCK so an under-evidenced action is stopped or reviewed.",
+    config: [{ key: "required", type: "string[]", required: true, description: "Evidence types that must all be present (e.g. kyc, source-doc, signature)" }],
+    requiredContext: ["evidenceTypes"]
+  },
+  {
+    predicate: "evidence-confidence-below",
+    label: "Evidence confidence below minimum",
+    description: "Fires when the attested evidence confidence is below a required minimum \u2014 or absent (SAFR \xA724). A min of 0 / unset is no requirement. Author with ESCALATE to route low-confidence actions to review.",
+    config: [{ key: "min", type: "number", required: true, description: "Minimum evidence confidence (0\u20131) required" }],
+    requiredContext: ["evidenceConfidence"]
+  }
+];
+var CATALOGUED_ATOMS = ATOM_SPECS.filter((s) => !!ATOM_REGISTRY[s.predicate]);
+function requiredContextFor(predicates) {
+  const fields = /* @__PURE__ */ new Set();
+  for (const p of predicates) {
+    const spec = ATOM_SPECS.find((s) => s.predicate === p);
+    for (const f of spec?.requiredContext ?? []) fields.add(f);
+  }
+  return [...fields].sort();
+}
+
+// src/policy-core/standards-rules.ts
+var PRECEDENCE = { allow: 0, observe: 1, escalate: 2, block: 3, suspend: 4, quarantine: 5 };
+function atomFires(atom, ctx) {
+  const pred = ATOM_REGISTRY[atom.predicate];
+  if (!pred) return false;
+  try {
+    return !!pred(ctx, atom.config);
+  } catch (err) {
+    console.warn(
+      `[standards] atom '${atom.predicate}' threw during evaluation (treated as not-firing):`,
+      err instanceof Error ? err.message : err
+    );
+    return false;
+  }
+}
+function moleculeFires(m, ctx) {
+  if (!m.atoms || m.atoms.length === 0) return false;
+  const results = m.atoms.map((a) => atomFires(a, ctx));
+  switch (m.combinator) {
+    case "all":
+      return results.every(Boolean);
+    case "any":
+      return results.some(Boolean);
+    case "none":
+      return !results.some(Boolean);
+    default:
+      return false;
+  }
+}
+function evaluateStandardRules(molecules, ctx, standardKey = null) {
+  let best = null;
+  for (const m of molecules ?? []) {
+    if (moleculeFires(m, ctx)) {
+      if (!best || PRECEDENCE[m.decision] > PRECEDENCE[best.decision]) {
+        best = { decision: m.decision, reasonCode: m.reasonCode, id: m.id };
+      }
+    }
+  }
+  if (!best) return { decision: "allow", reasonCode: null, firedMoleculeId: null, standardKey };
+  return { decision: best.decision, reasonCode: best.reasonCode, firedMoleculeId: best.id, standardKey };
+}
+function evaluateBoundStandards(standards, ctx) {
+  let best = { decision: "allow", reasonCode: null, firedMoleculeId: null, standardKey: null };
+  for (const s of standards) {
+    const r = evaluateStandardRules(s.document?.molecules, ctx, s.standardKey);
+    if (PRECEDENCE[r.decision] > PRECEDENCE[best.decision]) best = r;
+  }
+  return best;
+}
+function configValueValid(field, value) {
+  switch (field.type) {
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "string":
+      return typeof value === "string";
+    case "string[]":
+      return Array.isArray(value) && value.every((v) => typeof v === "string");
+    case "enum":
+      return typeof value === "string" && (field.options ?? []).includes(value);
+    default:
+      return true;
+  }
+}
+function validateAtomConfig(predicate, config) {
+  const spec = ATOM_SPECS.find((s) => s.predicate === predicate);
+  if (!spec) return [];
+  const errors = [];
+  const cfg = config ?? {};
+  for (const field of spec.config) {
+    const present = cfg[field.key] !== void 0 && cfg[field.key] !== null;
+    if (!present) {
+      if (field.required) errors.push(`atom '${predicate}' missing required config '${field.key}'`);
+      continue;
+    }
+    if (!configValueValid(field, cfg[field.key])) {
+      errors.push(`atom '${predicate}' config '${field.key}' must be a ${field.type}`);
+    }
+  }
+  return errors;
+}
+function validateMolecules(molecules) {
+  const issues = [];
+  for (const m of molecules ?? []) {
+    if (!m.id) issues.push({ moleculeId: "(missing id)", message: "molecule is missing an id" });
+    if (!["all", "any", "none"].includes(m.combinator)) {
+      issues.push({ moleculeId: m.id, message: `invalid combinator '${m.combinator}' (all|any|none)` });
+    }
+    if (!["observe", "block", "escalate", "suspend", "quarantine"].includes(m.decision)) {
+      issues.push({ moleculeId: m.id, message: `invalid decision '${m.decision}' (observe|block|escalate|suspend|quarantine)` });
+    }
+    if (!m.reasonCode) issues.push({ moleculeId: m.id, message: "molecule is missing a reasonCode" });
+    if (!m.atoms || m.atoms.length === 0) {
+      issues.push({ moleculeId: m.id, message: "molecule has no atoms" });
+    }
+    for (const a of m.atoms ?? []) {
+      if (!ATOM_REGISTRY[a.predicate]) {
+        issues.push({ moleculeId: m.id, message: `unknown atom predicate '${a.predicate}'` });
+        continue;
+      }
+      for (const err of validateAtomConfig(a.predicate, a.config)) {
+        issues.push({ moleculeId: m.id, message: err });
+      }
+    }
+  }
+  return { ok: issues.length === 0, issues };
+}
+
+// src/policy-core/mandate-eval.ts
+var toNum = (v) => typeof v === "number" ? v : Number(v);
+var toArray = (v) => Array.isArray(v) ? v : v === void 0 || v === null ? [] : [v];
+var toTime = (v) => Date.parse(String(v));
+var OPERATORS = {
+  eq: (l, r) => l === r,
+  neq: (l, r) => l !== r,
+  lt: (l, r) => toNum(l) < toNum(r),
+  lteq: (l, r) => toNum(l) <= toNum(r),
+  gt: (l, r) => toNum(l) > toNum(r),
+  gteq: (l, r) => toNum(l) >= toNum(r),
+  isAnyOf: (l, r) => toArray(r).includes(l),
+  isNoneOf: (l, r) => !toArray(r).includes(l),
+  isPartOf: (l, r) => toArray(r).includes(l),
+  before: (l, r) => toTime(l) < toTime(r),
+  after: (l, r) => toTime(l) > toTime(r)
+};
+var REASON_BY_OPERAND = {
+  "mm:payAmount": "SPEND_LIMIT_EXCEEDED",
+  "mm:cumulativeSpend": "SPEND_LIMIT_EXCEEDED",
+  "mm:merchant": "MERCHANT_NOT_ALLOWED",
+  "mm:route": "ROUTE_NOT_ALLOWED",
+  "mm:counterparty": "COUNTERPARTY_NOT_ALLOWED"
+};
+function reasonFor(constraint) {
+  if (!constraint) return "CONSTRAINT_FAILED";
+  return REASON_BY_OPERAND[constraint.leftOperand] ?? `CONSTRAINT_FAILED:${constraint.leftOperand}`;
+}
+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);
+}
+function targetOf(rule, mandate) {
+  return rule.target ?? mandate.target;
+}
+function evaluateMandate(mandate, req) {
+  const now = toTime(req.now);
+  if (mandate.validFrom && now < toTime(mandate.validFrom)) {
+    return { decision: "block", reasonCode: "MANDATE_NOT_YET_VALID", matched: { kind: "expiry" } };
+  }
+  if (mandate.validUntil && now > toTime(mandate.validUntil)) {
+    return { decision: "block", reasonCode: "MANDATE_EXPIRED", matched: { kind: "expiry" } };
+  }
+  for (const p of mandate.prohibition ?? []) {
+    if (targetOf(p, mandate) !== req.target) continue;
+    const fires = (p.constraint ?? []).every((c) => constraintSatisfied(c, req));
+    if (fires) {
+      return {
+        decision: p.enforcement ?? "block",
+        reasonCode: p.reasonCode ?? "PROHIBITED",
+        matched: { kind: "prohibition", target: p.target }
+      };
+    }
+  }
+  const perms = (mandate.permission ?? []).filter((p) => targetOf(p, mandate) === req.target);
+  if (perms.length === 0) {
+    return {
+      decision: "block",
+      reasonCode: "NO_PERMISSION_FOR_ACTION",
+      matched: { kind: "no-permission", target: req.target }
+    };
+  }
+  for (const p of perms) {
+    const failing = (p.constraint ?? []).find((c) => !constraintSatisfied(c, req));
+    if (!failing) return { decision: "allow", reasonCode: "AUTHORIZED" };
+  }
+  const firstFail = (perms[0].constraint ?? []).find((c) => !constraintSatisfied(c, req));
+  return {
+    decision: firstFail?.onFail ?? "block",
+    reasonCode: reasonFor(firstFail),
+    matched: { kind: "permission", target: perms[0].target, constraint: firstFail }
+  };
+}
+function remainingBudget(b) {
+  return Math.max(0, b.cap - b.spent - b.held);
+}
+function canAuthorize(b, amount) {
+  return amount >= 0 && amount <= remainingBudget(b);
+}
+function applyHold(b, amount) {
+  return { ...b, held: b.held + amount };
+}
+function applyCapture(b, amount) {
+  return { cap: b.cap, spent: b.spent + amount, held: Math.max(0, b.held - amount) };
+}
+function releaseHold(b, amount) {
+  return { ...b, held: Math.max(0, b.held - amount) };
+}
+function sumEventField(events, type, field) {
+  return events.filter((e) => e.type === type).reduce((acc, e) => acc + (typeof e.payload[field] === "number" ? e.payload[field] : 0), 0);
+}
+
+// src/policy-core/evaluate.ts
+var PRECEDENCE2 = { allow: 0, observe: 1, escalate: 2, block: 3, suspend: 4, quarantine: 5 };
+function evaluate(input) {
+  let decision = "allow";
+  let reasonCode = "AUTHORIZED";
+  const consider = (d, code) => {
+    if (PRECEDENCE2[d] > PRECEDENCE2[decision]) {
+      decision = d;
+      reasonCode = code;
+    }
+  };
+  const std = evaluateBoundStandards(input.standards ?? [], input.context);
+  if (std.decision !== "allow") consider(std.decision, std.reasonCode ?? "STANDARD_RULE");
+  const sop = evaluateBoundStandards(input.sops ?? [], input.context);
+  if (sop.decision !== "allow") consider(sop.decision, sop.reasonCode ?? "SOP_RULE");
+  if (input.mandate && input.mandateRequest) {
+    const m = evaluateMandate(input.mandate, input.mandateRequest);
+    if (m.decision !== "allow") consider(m.decision, m.reasonCode);
+  }
+  return { decision, reasonCode, authorizationId: null, remaining: null, proofRef: null };
+}
+
+// src/policy-core/canonical.ts
+function buildAuthMessage(f) {
+  return `${f.agentDid}|${f.action}|${f.amount}|${f.currency}|${f.merchant ?? ""}|${f.nonce}|${f.issuedAt}`;
+}
+
+// src/policy-core/context.ts
+function applySignedLast(unsigned, signed) {
+  return { ...unsigned ?? {}, ...signed };
+}
+
+// src/policy-core/operating-mode.ts
+var MODE_RANK = {
+  read_only: 0,
+  restricted: 1,
+  supervised: 2,
+  autonomous: 3
+};
+var MODES_BY_RANK = ["read_only", "restricted", "supervised", "autonomous"];
+function isOperatingMode(v) {
+  return typeof v === "string" && Object.prototype.hasOwnProperty.call(MODE_RANK, v);
+}
+function asOperatingMode(v) {
+  return isOperatingMode(v) ? v : "autonomous";
+}
+function moreRestrictive(a, b) {
+  return MODE_RANK[a] <= MODE_RANK[b] ? a : b;
+}
+var SUPERVISED_AMOUNT_CAP = 100;
+var RISK_RANK2 = { low: 0, medium: 1, high: 2, critical: 3 };
+function riskAtOrAboveHigh(riskLevel) {
+  const r = typeof riskLevel === "string" ? RISK_RANK2[riskLevel.toLowerCase()] : void 0;
+  return r !== void 0 && r >= RISK_RANK2.high;
+}
+function operatingModeGate(mode, ctx) {
+  const m = asOperatingMode(mode);
+  const valueBearing = (ctx.amount ?? 0) > 0;
+  if (!valueBearing || m === "autonomous") return { decision: "allow", reasonCode: null };
+  switch (m) {
+    case "read_only":
+      return { decision: "block", reasonCode: "MODE_READ_ONLY" };
+    case "restricted":
+      return { decision: "escalate", reasonCode: "MODE_RESTRICTED_REVIEW" };
+    case "supervised":
+      return riskAtOrAboveHigh(ctx.riskLevel) || (ctx.amount ?? 0) >= SUPERVISED_AMOUNT_CAP ? { decision: "escalate", reasonCode: "MODE_SUPERVISED_REVIEW" } : { decision: "allow", reasonCode: null };
+    default:
+      return { decision: "allow", reasonCode: null };
+  }
+}
+export {
+  ATOM_REGISTRY,
+  ATOM_SPECS,
+  CATALOGUED_ATOMS,
+  MODES_BY_RANK,
+  MODE_RANK,
+  SUPERVISED_AMOUNT_CAP,
+  applyCapture,
+  applyHold,
+  applySignedLast,
+  asOperatingMode,
+  buildAuthMessage,
+  canAuthorize,
+  evaluate,
+  evaluateBoundStandards,
+  evaluateMandate,
+  evaluateStandardRules,
+  isOperatingMode,
+  moleculeFires,
+  moreRestrictive,
+  operatingModeGate,
+  releaseHold,
+  remainingBudget,
+  requiredContextFor,
+  sumEventField,
+  validateMolecules
+};

package/x402.mjs

@@ -0,0 +1,43 @@
+// GENERATED from backend/src/features/magp/x402-binding.ts — do not edit. Regenerate: npm run build:mcp-guard-core
+
+// src/features/magp/x402-binding.ts
+function toMinorUnits(amount, decimals) {
+  if (!Number.isFinite(amount) || amount < 0) throw new Error("amount must be a non-negative number");
+  const factor = 10 ** decimals;
+  return String(Math.round(amount * factor));
+}
+function buildPaymentRequirements(input) {
+  if (!input.authorizationId) throw new Error("buildPaymentRequirements requires an authorizationId");
+  const decimals = input.decimals ?? 6;
+  return {
+    x402Version: 1,
+    accepts: [
+      {
+        scheme: "exact",
+        network: input.network ?? "hedera-testnet",
+        maxAmountRequired: toMinorUnits(input.amount, decimals),
+        payTo: input.payTo,
+        asset: input.asset,
+        resource: input.resource,
+        extra: { magpAuthorizationId: input.authorizationId, magpAgentDid: input.agentDid }
+      }
+    ]
+  };
+}
+function checkSettlementBinding(requirements, claim) {
+  const accept = requirements?.accepts?.[0];
+  if (!accept?.extra?.magpAuthorizationId) return { ok: false, reasonCode: "MISSING_BINDING" };
+  if (accept.extra.magpAuthorizationId !== claim.authorizationId) {
+    return { ok: false, reasonCode: "AUTHORIZATION_MISMATCH" };
+  }
+  const authorizedMinor = Number(accept.maxAmountRequired);
+  const paidMinor = Number(claim.paidAmountMinor);
+  if (!Number.isFinite(paidMinor) || paidMinor < 0) return { ok: false, reasonCode: "AMOUNT_INVALID" };
+  if (paidMinor > authorizedMinor) return { ok: false, reasonCode: "AMOUNT_MISMATCH" };
+  return { ok: true, reasonCode: "BINDING_OK" };
+}
+export {
+  buildPaymentRequirements,
+  checkSettlementBinding,
+  toMinorUnits
+};