@metamynd/agentsafe-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,223 @@
+# AgentSafe Guard — runtime governance for OpenClaw (and any Node agent)
+
+Drop-in middleware that gates an agent's actions through the AgentSafe **authorize** endpoint
+before they run. The gate deterministically returns `allow` / `block` / `escalate` after checking
+the agent's **mandate**, its enforced **Standards**, and its assigned **SOPs** — the same rules a
+compliance team edits in the dashboard, changeable live with no redeploy.
+
+- **Zero dependencies.** Uses Node's built-in Ed25519 (`node:crypto`) + `fetch` (Node 18+), plus
+  `policy-core.mjs` — the deterministic evaluator, itself dependency-free, generated from
+  `backend/src/policy-core` (regenerate with `npm run build:guard-core`).
+- **Deterministic + tamper-resistant.** Every call is Ed25519-signed over a canonical message with a
+  single-use nonce; the gate is server-authoritative and cannot be bypassed. No LLM at the gate.
+- **Fail-closed.** A network/gate failure returns `block`, so the agent never proceeds blind.
+- **Local evaluation.** The guard can also evaluate a signed policy bundle **locally** with the same
+  `policy-core` the gate runs (MAGP §9.2 cooperative mode) — identical inputs give the identical
+  verdict, with no network round-trip. See §4.
+
+## Install
+
+```bash
+npm i @metamynd/agentsafe-guard
+```
+
+Requires Node ≥ 18 (built-in `fetch` + Ed25519). The package has **no dependencies**.
+
+### Fastest start — scaffold a governed agent in one command
+
+If you don't have an agent config yet, let the scaffolder log you in, provision the agent
+(identity + mandate + starter SOP + Standards in one call), write `agent.metamynd.json`, and drop a
+runnable example:
+
+```bash
+npm create metamynd-agent@latest      # or: npx create-metamynd-agent
+```
+
+Then:
+
+```js
+import { createGuardFromConfig } from '@metamynd/agentsafe-guard';
+const guard = await createGuardFromConfig('./agent.metamynd.json');   // no env vars
+```
+
+The rest of this guide shows the manual path (seed → wire) and the advanced features
+(local eval, handshake, escalation, payments).
+
+### Bring your own key (BYOK)
+
+Provision the agent with your **own** public key so MetaMynd never sees the private key. The identity
+is issued unverified with a one-time `challenge`; the gate blocks it (`AGENT_KEY_UNVERIFIED`) until you
+prove control. The guard signs the challenge with your key and submits it:
+
+```js
+const guard = await createGuardFromConfig('./agent.metamynd.json', { agentKey: myPrivateKey });
+await guard.verifyKey({ ref: config.identityId, challenge: config.challenge, token: ownerToken }); // one-time
+```
+
+`guard.signChallenge(challenge)` returns just the hex signature if you'd rather submit verify-key
+yourself. (Fastest path: `npm create metamynd-agent@latest -- --byok` does all of this for you.)
+
+## 1. Seed a bound agent (once)
+
+Run the seed against a running stack — it prints the agent's `DID` and `KEY`:
+
+```powershell
+cd backend
+$env:API_BASE="http://localhost:9926/api/v1"   # or https://metamynd.ai/api/v1
+node_modules\.bin\tsx scripts\demo-seed-governance.ts
+# → AGENT_DID = did:hedera:testnet:...
+# → AGENT_KEY = 302e0201...
+```
+
+The agent is now bound to a mandate (`flight-purchase`), an **enforced Standard** (EU AI Act) and an
+**active SOP** (spend cap + approved tools). Manage/toggle these from the dashboard:
+Super Admin → Standards, Legal Entity → SOPs.
+
+## 2. Try the example
+
+```powershell
+cd integrations\agentsafe-guard
+$env:AGENTSAFE_API="http://localhost:9926/api/v1"
+$env:AGENT_DID="did:hedera:testnet:..."
+$env:AGENT_KEY="302e0201..."
+node example-openclaw-agent.mjs
+```
+
+```
+✅ ALLOW    $150 book-flight, low risk     → booked PNR-DEMO (remaining $200)
+⛔ BLOCK    $600 book-flight               → SOP_SPEND_CAP
+⛔ BLOCK    $100 wire-transfer tool        → SOP_TOOL_BLOCKED
+⚠ ESCALATE $100 high-risk decision        → RISK_REVIEW
+```
+
+Now flip the SOP's **active → inactive** toggle in the UI (or edit a rule) and re-run — the decision
+changes in real time.
+
+## 3. Wire it into your OpenClaw agent
+
+Wrap each governed tool's handler with `guardTool(...)`. The wrapped handler only runs when the gate
+allows; otherwise it throws a `GovernanceBlocked` error your agent surfaces to the user.
+
+```js
+import { createGuard, createGuardFromConfig } from '@metamynd/agentsafe-guard';
+
+// Preferred: load the portable config the one-call onboarding endpoint returns (no env vars).
+const guard = await createGuardFromConfig('./agent.metamynd.json');
+
+// Or configure explicitly:
+const guardExplicit = createGuard({
+  api: process.env.AGENTSAFE_API,
+  agentDid: process.env.AGENT_DID,
+  agentKey: process.env.AGENT_KEY,   // held only by the agent
+});
+
+// Your existing OpenClaw tool handler:
+async function bookFlight(args) { /* …call the airline… */ return { pnr: 'ABC123' }; }
+
+// Register the GATED version with OpenClaw instead of the raw handler:
+const gatedBookFlight = guard.guardTool(
+  'flight-purchase',                 // the governed action (matches the mandate scope)
+  bookFlight,
+  (a) => ({                          // map tool args → gate inputs
+    amount: a.amount,
+    currency: 'USD',
+    merchant: a.merchant,
+    context: { tool: 'book-flight', jurisdiction: a.jurisdiction, riskLevel: a.riskLevel },
+  }),
+);
+```
+
+- If your OpenClaw build has a **pre-tool hook / middleware** instead of raw handlers, call
+  `await guard.authorize({ action, amount, merchant, context })` there and refuse on any non-`allow`.
+- **`context`** is what the Standard/SOP atoms read (jurisdiction, model, tool, PII, risk, …). Each
+  atom declares what it needs — fetch the catalog at `GET /api/v1/standards/atoms` to see the exact
+  fields (`requiredContext`) for the rules your agent is bound to.
+- For **payment** tools (x402, §7a): after `authorize` allows, the Service returns a 402 bound to
+  your `authorizationId`. Call `guard.preparePayment(requirements, authorizationId)` — it refuses an
+  unbound or mismatched 402 — pay via x402, then reconcile the hold with
+  `await guard.capture(authorizationId, amountCharged, bookingRef, settlementTxHash)`. An
+  uncaptured hold auto-voids at its expiry (`POST /policy/mandate/authorize/:id/void` to release early).
+
+## 4. Evaluate locally (no network)
+
+For low-latency, cooperative-mode governance the guard can evaluate a **policy bundle** locally with
+the same deterministic `policy-core` the gate runs — no round-trip. Given the same rule packs,
+mandate, and request, it returns the **identical** `allow` / `block` / `escalate` verdict.
+
+```js
+const verdict = guard.evaluateLocally({
+  standards: [{ standardKey: 'eu-ai-act', document: { molecules: [/* … */] } }],
+  sops:      [{ standardKey: 'sop:travel', document: { molecules: [/* … */] } }],
+  mandate:   { permission: [/* ODRL constraints … */] },
+  request:   { action: 'flight-purchase', amount: 600, merchant: 'amadeus',
+               context: { riskLevel: 'low' } },
+});
+// → { decision: 'block', reasonCode: 'SOP_SPEND_CAP', authorizationId: null, remaining: null, proofRef: null }
+```
+
+Or wrap a tool to gate it against a local bundle (fails closed like `guardTool`):
+
+```js
+const gated = guard.guardToolLocal('flight-purchase', bookFlight, mapArgs, { standards, sops, mandate });
+```
+
+Signed request fields (`amount`, `merchant`) are always applied over the unsigned `context`, so a
+forged context key can never shadow them (MAGP §6.4.2). Run the self-check:
+
+```powershell
+cd integrations\agentsafe-guard
+node local-eval.smoke.mjs   # PASS when every local verdict matches the gate
+```
+
+Local evaluation is the cooperative-mode pre-check; the gate still owns the stateful parts
+(single-use nonce, atomic spend-cap reservation, evidence anchoring), so value-bearing actions should
+still settle through the gate / `capture` flow.
+
+## 5. Mutual handshake with a Service (§8.2)
+
+Before transacting with a Service (an MCP), the agent and Service prove control of their DIDs
+to each other — no issuer calls, because the keys are embedded in the DIDs (§4.1.2). The agent
+drives the initiator side:
+
+```js
+const hs = guard.handshake();
+const { nonceA, message } = hs.hello();              // → send HELLO to the Service
+// Service replies with CHALLENGE { toDid, nonceB, sigB(nonceA) }
+const { sigA, handshakeId } = hs.prove({ nonceA, challenge });  // verifies the Service, → send PROVE
+// Service replies READY { channelId }
+```
+
+`prove()` throws `HandshakeFailed` if the Service's CHALLENGE does not verify against the key in
+its DID. The Service side uses [`agentsafe-mcp-guard`](../agentsafe-mcp-guard), which also
+re-evaluates the agent's signed request trustlessly (§9.6). Discover a Service's endpoint and
+confirm its key via the public resolver `GET /did/:did` (§4.4).
+
+## 6. Escalation — human-in-the-loop (§9a)
+
+An `escalate` verdict is **not a denial** — the action is *held* pending the Owner's approval. The
+verdict carries an `escalationId`; no budget is reserved and (for payments) nothing settles until it
+is approved. The Owner resolves it in the dashboard / via `POST /policy/escalations/:id/resolve`;
+the agent polls the outcome:
+
+```js
+const d = await guard.authorize({ action: 'flight-purchase', amount: 5000, context: { riskLevel: 'high' } });
+if (d.decision === 'escalate') {
+  // parked for review — d.escalationId, d.expiresAt
+  const outcome = await guard.escalationStatus(d.escalationId);
+  // → { status: 'approved' | 'denied' | 'expired' | 'pending', authorizationId, reasonCode }
+  // on 'approved', outcome.authorizationId carries into the §7a capture/pay flow.
+}
+```
+
+On approval the budget/cap gate re-runs (§9a.3), so an approval still can't overspend; an
+unresolved escalation lapses to denied after its TTL (§9a.4).
+
+## Trust model
+
+The gate is a **checkpoint** — enforcement is real when it's actually called.
+- **Trustless:** the counterparty the agent transacts with calls the *public* authorize endpoint and
+  only proceeds on `allow`. A rogue agent that skips the call can't get the counterparty to act.
+- **Cooperative:** the agent's own tool layer (this guard) calls the gate and refuses on block/escalate.
+
+Either way, every decision is Ed25519-authenticated, deterministic, and anchored as evidence
+(visible in the dashboard's Regulator log and on HashScan).

package/agentsafe-guard.mjs

@@ -0,0 +1,316 @@
+// agentsafe-guard.mjs — drop-in runtime governance for any Node agent (OpenClaw, LangChain, custom).
+//
+// ZERO external dependencies: uses Node's built-in Ed25519 (node:crypto) + fetch (Node 18+),
+// plus policy-core.mjs (the deterministic evaluator, itself dependency-free, generated from
+// backend/src/policy-core). Before an agent performs a governed action the guard can either
+// call the AgentSafe authorize gate (trustless fallback) OR evaluate a signed policy bundle
+// LOCALLY (spec §9.2 cooperative mode) — both compute the identical allow/block/escalate
+// verdict from the identical inputs, because they run the same policy-core.
+//
+// The agent's private key is a Hedera Ed25519 DER key (the AGENT_KEY the seed prints).
+import crypto from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { evaluate, buildAuthMessage, applySignedLast } from './policy-core.mjs';
+import { verifyDidSignature } from './magp-did.mjs';
+import { checkSettlementBinding } from './x402.mjs';
+
+/**
+ * @param {{ api: string, agentDid: string, agentKey: string }} cfg
+ *   api      e.g. "http://localhost:9926/api/v1" or "https://metamynd.ai/api/v1"
+ *   agentDid the agent's did:hedera
+ *   agentKey the agent's Ed25519 private key (Hedera DER hex, held only by the agent)
+ */
+/**
+ * Async loader — build a guard from the portable config the one-call `POST /onboarding/agent`
+ * endpoint returns: a URL, a file path, or the config object itself. Overrides win over the config.
+ *   const guard = await createGuardFromConfig('./agent.metamynd.json');
+ */
+export async function createGuardFromConfig(source, overrides = {}) {
+  let cfg = source;
+  if (typeof source === 'string') {
+    cfg = /^https?:\/\//.test(source) ? await (await fetch(source)).json() : JSON.parse(readFileSync(source, 'utf8'));
+  }
+  if (cfg && cfg.data && !cfg.agentDid) cfg = cfg.data; // unwrap a { success, data } API response
+  return createGuard({ config: cfg, ...overrides });
+}
+
+export function createGuard(opts = {}) {
+  // Accept a portable agent config (from /onboarding/agent) via `config` or `configPath`, in
+  // addition to explicit { api, agentDid, agentKey }. Explicit fields win over the config.
+  let cfg = opts.config ?? null;
+  if (!cfg && opts.configPath) {
+    try { cfg = JSON.parse(readFileSync(opts.configPath, 'utf8')); }
+    catch (e) { throw new Error(`createGuard: cannot read configPath "${opts.configPath}": ${e.message}`); }
+  }
+  if (cfg && cfg.data && !cfg.agentDid) cfg = cfg.data; // unwrap a { success, data } API response
+  const api = opts.api ?? cfg?.apiBase ?? cfg?.api;
+  const agentDid = opts.agentDid ?? cfg?.agentDid;
+  const agentKey = opts.agentKey ?? cfg?.agentKey;
+  if (!api || !agentDid || !agentKey) throw new Error('createGuard requires { api, agentDid, agentKey } — directly, or via { config } / { configPath } / createGuardFromConfig()');
+  const base = api.replace(/\/$/, '');
+  const privateKey = crypto.createPrivateKey({ key: Buffer.from(agentKey, 'hex'), format: 'der', type: 'pkcs8' });
+
+  // Ed25519 over the exact canonical message the backend verifies.
+  function sign(message) {
+    return crypto.sign(null, Buffer.from(message, 'utf8'), privateKey).toString('hex');
+  }
+
+  /**
+   * Build a signed authorize request (spec §7.2/§7.3) WITHOUT sending it — the object an
+   * agent presents to a counterparty (e.g. an MCP) so the counterparty can re-verify the
+   * agent's authorization trustlessly against the agent's policy bundle (§9.3). Same shape
+   * `authorize()` posts to the gate; a fresh nonce each call.
+   */
+  function buildSignedRequest({ action, amount = 0, currency = 'USD', merchant = '', context = {} }) {
+    const nonce = crypto.randomUUID();
+    const issuedAt = new Date().toISOString();
+    const message = buildAuthMessage({ agentDid, action, amount, currency, merchant, nonce, issuedAt });
+    return { agentDid, action, amount, currency, merchant, itinerary: context, nonce, issuedAt, signature: sign(message) };
+  }
+
+  /**
+   * Ask the gate whether an action is authorized. Never throws on a policy decision —
+   * returns { decision:'allow'|'block'|'escalate', reasonCode, authorizationId, remaining }.
+   * A network/gate failure returns a fail-CLOSED block so the agent can't proceed blind.
+   */
+  async function authorize({ action, amount = 0, currency = 'USD', merchant = '', context = {} }) {
+    const nonce = crypto.randomUUID();
+    const issuedAt = new Date().toISOString();
+    // Build the canonical signed message with policy-core so the guard and the
+    // backend gate produce byte-identical input to Ed25519 (spec §7.3).
+    const message = buildAuthMessage({ agentDid, action, amount, currency, merchant, nonce, issuedAt });
+    try {
+      const res = await fetch(`${base}/policy/mandate/authorize`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ agentDid, action, amount, currency, merchant, itinerary: context, nonce, issuedAt, signature: sign(message) }),
+      });
+      const body = await res.json().catch(() => null);
+      return body?.data ?? { decision: 'block', reasonCode: `GATE_HTTP_${res.status}` };
+    } catch (err) {
+      return { decision: 'block', reasonCode: 'GATE_UNREACHABLE', error: String(err?.message ?? err) };
+    }
+  }
+
+  /**
+   * Settle an approved hold (two-phase). Call after the real action succeeds with the
+   * amount actually charged (≤ the authorized amount). Pass the x402 `settlementTxHash`
+   * to record the on-chain payment proof against the capture (§7a.3.2). Optional —
+   * skip for non-payment tools.
+   */
+  async function capture(authorizationId, amountCharged, bookingRef, settlementTxHash) {
+    const res = await fetch(`${base}/policy/mandate/authorize/${authorizationId}/capture`, {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ amountCharged, bookingRef, settlementTxHash }),
+    });
+    return res.json().catch(() => ({}));
+  }
+
+  /**
+   * Evaluate a signed policy bundle LOCALLY — no network — using the same
+   * deterministic policy-core the gate runs (spec §9.2 cooperative mode). Given the
+   * same (rule packs, mandate, request), this returns the identical verdict the
+   * gate would. The stateful parts the gate owns (nonce/replay, atomic spend-cap
+   * reservation, evidence anchoring) are NOT done here — this is the local
+   * allow/block/escalate pre-check, so `authorizationId`/`remaining` are null.
+   *
+   * @param {object} p
+   * @param {Array<{standardKey:string,document:object}>} [p.standards] enforced Standards bound to the agent
+   * @param {Array<{standardKey:string,document:object}>} [p.sops]      active SOPs assigned to the agent
+   * @param {object} [p.mandate]  the ODRL mandate document (omit to skip the mandate layer)
+   * @param {{action:string,amount?:number,merchant?:string,context?:object,cumulativeSpend?:number,now?:string}} p.request
+   * @returns {{decision:'allow'|'block'|'escalate',reasonCode:string|null,authorizationId:null,remaining:null,proofRef:null}}
+   */
+  function evaluateLocally({ standards = [], sops = [], mandate, request }) {
+    const { action, amount = 0, merchant = '', context = {}, cumulativeSpend = amount, now } = request;
+    // Signed fields (action/agentDid/amount, mm:* operands) are applied LAST so an
+    // unsigned context key can never shadow them (spec §6.4.2) — the same invariant
+    // the gate enforces, via the same policy-core helper.
+    return evaluate({
+      standards,
+      sops,
+      mandate,
+      context: applySignedLast(context, { action, agentDid, amount }),
+      mandateRequest: mandate
+        ? {
+            target: action,
+            now: now ?? new Date().toISOString(),
+            values: applySignedLast(context, {
+              'mm:payAmount': amount,
+              'mm:cumulativeSpend': cumulativeSpend,
+              'mm:merchant': merchant,
+            }),
+          }
+        : undefined,
+    });
+  }
+
+  /**
+   * Like guardTool, but evaluates LOCALLY against a policy bundle instead of calling
+   * the gate — cooperative-mode, low-latency governance (spec §9.2). Fails CLOSED:
+   * any error during local evaluation throws GovernanceBlocked, never allows.
+   *
+   * @param {string} action
+   * @param {(args:any, decision:any)=>any} handler
+   * @param {(args:any)=>{amount?:number,merchant?:string,context?:object}} mapArgs
+   * @param {object|((args:any)=>object|Promise<object>)} getBundle  { standards, sops, mandate } (or a resolver)
+   */
+  function guardToolLocal(action, handler, mapArgs = (a) => a, getBundle = {}) {
+    return async (args) => {
+      let decision;
+      try {
+        const { amount, merchant, context } = mapArgs(args);
+        const bundle = typeof getBundle === 'function' ? await getBundle(args) : getBundle;
+        decision = evaluateLocally({ ...bundle, request: { action, amount, merchant, context } });
+      } catch (err) {
+        decision = { decision: 'block', reasonCode: 'LOCAL_EVAL_ERROR', error: String(err?.message ?? err) };
+      }
+      if (decision.decision !== 'allow') {
+        const err = new Error(`AgentSafe ${decision.decision.toUpperCase()} "${action}": ${decision.reasonCode}`);
+        err.name = 'GovernanceBlocked';
+        err.governance = decision;
+        throw err;
+      }
+      return handler(args, decision);
+    };
+  }
+
+  /**
+   * Wrap a tool handler so it is gated. Returns a function you register with your agent
+   * framework in place of the raw handler. On a non-allow decision it THROWS a
+   * GovernanceBlocked error (with `.governance`) so the agent surfaces the reason and
+   * does NOT perform the action.
+   *
+   * @param {string} action  the governed action (must match a mandate scope, e.g. 'flight-purchase')
+   * @param {(args:any, decision:any)=>any} handler  the real tool implementation
+   * @param {(args:any)=>{amount?:number,currency?:string,merchant?:string,context?:object}} mapArgs
+   *   maps the tool's call args to the gate inputs (amount/merchant + the context the rules need)
+   */
+  function guardTool(action, handler, mapArgs = (a) => a) {
+    return async (args) => {
+      const decision = await authorize({ action, ...mapArgs(args) });
+      if (decision.decision !== 'allow') {
+        const err = new Error(`AgentSafe ${decision.decision.toUpperCase()} "${action}": ${decision.reasonCode}`);
+        err.name = 'GovernanceBlocked';
+        err.governance = decision;
+        throw err;
+      }
+      return handler(args, decision);
+    };
+  }
+
+  /**
+   * Mutual-handshake INITIATOR (spec §8.2). Prove control of this agent's DID to a
+   * Service and verify the Service controls its DID — no issuer calls (keys are in
+   * the DIDs, §4.1.2). Returns { hello, prove } to drive the exchange:
+   *   const hs = guard.handshake();
+   *   const { nonceA, message } = hs.hello();           // → send HELLO to the Service
+   *   const { sigA, handshakeId } = hs.prove({ nonceA, challenge });  // verifies the Service, → send PROVE
+   * `prove` throws HandshakeFailed if the Service's CHALLENGE does not verify.
+   */
+  function handshake() {
+    return {
+      hello() {
+        const nonceA = crypto.randomUUID();
+        return { nonceA, message: { fromDid: agentDid, nonceA, protoVersion: '0.4' } };
+      },
+      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('Service failed to prove control of its DID');
+          e.name = 'HandshakeFailed';
+          throw e;
+        }
+        return { handshakeId, sigA: sign(nonceB), remoteDid: toDid };
+      },
+    };
+  }
+
+  /**
+   * Read a Service's 402 PaymentRequirements and prepare to pay (spec §7a.1 step 5).
+   * Refuses a 402 that is NOT bound to a MAGP authorization (§7a.2.1) — the agent
+   * must never pay for an ungoverned request — and refuses one whose authorization
+   * does not match the `authorizationId` the agent holds from its own authorize
+   * (allow) step, so a swapped 402 can't redirect the payment.
+   *
+   * @param {object} requirements  the x402 PaymentRequirements from the 402 response
+   * @param {string} [expectedAuthorizationId]  the authorizationId from guard.authorize()
+   * @returns {{authorizationId:string, amountMinor:string, payTo:string, asset:string, network:string, resource:string}}
+   */
+  function preparePayment(requirements, expectedAuthorizationId) {
+    const a = requirements?.accepts?.[0];
+    if (!a?.extra?.magpAuthorizationId) {
+      const e = new Error('402 is not bound to a MAGP authorization — refusing to pay');
+      e.name = 'UnboundPayment';
+      throw e;
+    }
+    if (expectedAuthorizationId && a.extra.magpAuthorizationId !== expectedAuthorizationId) {
+      const e = new Error('402 authorization does not match the agent authorization');
+      e.name = 'AuthorizationMismatch';
+      throw e;
+    }
+    // Pay exactly the authorized amount; the binding check guards against overpay.
+    checkSettlementBinding(requirements, { authorizationId: a.extra.magpAuthorizationId, paidAmountMinor: a.maxAmountRequired });
+    return {
+      authorizationId: a.extra.magpAuthorizationId,
+      amountMinor: a.maxAmountRequired,
+      payTo: a.payTo,
+      asset: a.asset,
+      network: a.network,
+      resource: a.resource,
+    };
+  }
+
+  /**
+   * Poll the outcome of an escalated action (spec §9a). When authorize() returns
+   * `escalate`, its `escalationId` parks the action for the Owner to approve/deny.
+   * The agent polls this until the status is terminal; on `approved` the returned
+   * `authorizationId` carries into the §7a capture/pay flow. Fails soft (never throws).
+   * @returns {Promise<{status:string,reasonCode:string,authorizationId:string|null,expiresAt:string|null}>}
+   */
+  async function escalationStatus(escalationId) {
+    try {
+      const res = await fetch(`${base}/policy/escalations/${encodeURIComponent(escalationId)}/status`);
+      const body = await res.json().catch(() => null);
+      return body?.data ?? { status: 'unknown', reasonCode: `GATE_HTTP_${res.status}`, authorizationId: null, expiresAt: null };
+    } catch (err) {
+      return { status: 'unreachable', reasonCode: 'GATE_UNREACHABLE', authorizationId: null, expiresAt: null, error: String(err?.message ?? err) };
+    }
+  }
+
+  /**
+   * BYOK proof-of-possession (onboarding proposal #4). For an agent that brought its OWN key,
+   * MetaMynd issued the identity with a one-time `challenge` and left the key UNVERIFIED — the gate
+   * blocks it with AGENT_KEY_UNVERIFIED until control is proven. This signs the challenge with the
+   * agent's private key (the same Ed25519 the gate checks) and submits it to verify-key, flipping
+   * the key to verified. A one-time SETUP step: verify-key is owner-authenticated, so pass the owner
+   * `token` you onboarded with. `ref` defaults to the identityId; `challenge` comes from the config.
+   *
+   * @param {{ ref: string, challenge: string, token?: string }} p
+   * @returns {Promise<{ verified: boolean, did?: string }>}
+   */
+  async function verifyKey({ ref, challenge, token } = {}) {
+    if (!ref || !challenge) throw new Error('verifyKey requires { ref, challenge } (from the BYOK onboarding config)');
+    const res = await fetch(`${base}/agent-identity/${encodeURIComponent(ref)}/verify-key`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+      body: JSON.stringify({ signature: sign(challenge) }),
+    });
+    const body = await res.json().catch(() => null);
+    if (!res.ok) {
+      const e = new Error(body?.message || `verify-key HTTP ${res.status}`);
+      e.name = 'KeyVerificationFailed';
+      throw e;
+    }
+    return body?.data ?? { verified: true };
+  }
+
+  /** Sign a BYOK challenge with the agent's key (hex) — for integrators who submit verify-key themselves. */
+  function signChallenge(challenge) {
+    if (!challenge) throw new Error('signChallenge requires the challenge nonce');
+    return sign(challenge);
+  }
+
+  return { authorize, buildSignedRequest, capture, guardTool, evaluateLocally, guardToolLocal, handshake, preparePayment, escalationStatus, verifyKey, signChallenge, agentDid };
+}

package/example-openclaw-agent.mjs

@@ -0,0 +1,47 @@
+// example-openclaw-agent.mjs — a runnable demo of the guard against a seeded bound agent.
+//
+// Simulates how an OpenClaw agent's TOOL is wrapped: the raw tool only runs if the
+// AgentSafe gate returns `allow`. Run it after seeding an agent with
+// backend/scripts/demo-seed-governance.ts:
+//
+//   $env:AGENTSAFE_API="http://localhost:9926/api/v1"
+//   $env:AGENT_DID="did:hedera:testnet:..."
+//   $env:AGENT_KEY="302e0201..."
+//   node example-openclaw-agent.mjs
+import { createGuard } from './agentsafe-guard.mjs';
+
+const guard = createGuard({
+  api: process.env.AGENTSAFE_API ?? 'http://localhost:9926/api/v1',
+  agentDid: process.env.AGENT_DID,
+  agentKey: process.env.AGENT_KEY,
+});
+
+// --- The agent's tool. In OpenClaw you register this handler for the tool; here we
+//     wrap it with guard.guardTool so every call is gated first. ---
+const bookFlight = guard.guardTool(
+  'flight-purchase', // the governed action (matches the mandate scope)
+  async (args, decision) => {
+    // Only reached when the gate ALLOWED. Real booking would go here.
+    return { booked: true, pnr: 'PNR-DEMO', remaining: decision.remaining, ...args };
+  },
+  // Map the tool args → gate inputs. `context` carries what the Standard/SOP rules need.
+  (a) => ({ amount: a.amount, currency: 'USD', merchant: a.merchant, context: { tool: a.tool ?? 'book-flight', riskLevel: a.riskLevel ?? 'low' } }),
+);
+
+async function ask(label, args) {
+  try {
+    const r = await bookFlight(args);
+    console.log(`  \x1b[32m✅ ALLOW\x1b[0m   ${label.padEnd(30)} → booked ${r.pnr} (remaining $${r.remaining})`);
+  } catch (e) {
+    const g = e.governance ?? {};
+    const tag = g.decision === 'escalate' ? '\x1b[33m⚠ ESCALATE\x1b[0m' : '\x1b[31m⛔ BLOCK\x1b[0m';
+    console.log(`  ${tag} ${label.padEnd(30)} → ${g.reasonCode ?? e.message}`);
+  }
+}
+
+console.log(`\n  OpenClaw agent — every booking passes through the AgentSafe gate\n  ${'─'.repeat(60)}`);
+await ask('$150 book-flight, low risk', { amount: 150, merchant: 'skyward-air', tool: 'book-flight', riskLevel: 'low' });
+await ask('$600 book-flight', { amount: 600, merchant: 'skyward-air', tool: 'book-flight', riskLevel: 'low' });
+await ask('$100 wire-transfer tool', { amount: 100, merchant: 'skyward-air', tool: 'wire-transfer', riskLevel: 'low' });
+await ask('$100 high-risk decision', { amount: 100, merchant: 'skyward-air', tool: 'book-flight', riskLevel: 'high' });
+console.log(`\n  The agent refuses blocked/escalated actions itself — governance decided, not the LLM.\n`);

package/magp-did.mjs

@@ -0,0 +1,126 @@
+// GENERATED from backend/src/features/magp/did.ts — do not edit. Regenerate: npm run build: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 };
+}
+
+// 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 parsed = parseHederaDid(did);
+  if (!parsed) return false;
+  try {
+    const key = ed25519KeyFromRaw(parsed.publicKeyBytes);
+    return crypto.verify(null, Buffer.from(message, "utf8"), key, Buffer.from(signatureHex, "hex"));
+  } catch {
+    return false;
+  }
+}
+function buildDidDocument(did, service) {
+  const parsed = parseHederaDid(did);
+  if (!parsed) return null;
+  const doc = {
+    "@context": ["https://www.w3.org/ns/did/v1"],
+    id: did,
+    controller: did,
+    verificationMethod: [
+      {
+        id: `${did}#did-root-key`,
+        type: "Ed25519VerificationKey2020",
+        controller: did,
+        publicKeyMultibase: parsed.publicKeyMultibase
+      }
+    ],
+    authentication: [`${did}#did-root-key`]
+  };
+  if (service) {
+    doc.service = [
+      {
+        id: `${did}#magp`,
+        type: "MAGPEndpoint",
+        serviceEndpoint: service.serviceEndpoint,
+        channels: service.channels,
+        protoVersions: service.protoVersions
+      }
+    ];
+  }
+  return doc;
+}
+export {
+  base58,
+  base58Decode,
+  buildDidDocument,
+  buildHederaDid,
+  ed25519KeyFromRaw,
+  multibaseBase58btc,
+  parseHederaDid,
+  verifyDidSignature
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@metamynd/agentsafe-guard",
+  "version": "0.1.0",
+  "description": "Zero-dependency runtime governance for any Node AI agent — gate tool calls through MetaMynd/AgentSafe (allow / block / escalate) against the agent's mandate, enforced Standards, and SOPs. Ed25519-signed, deterministic, fail-closed.",
+  "type": "module",
+  "main": "./agentsafe-guard.mjs",
+  "module": "./agentsafe-guard.mjs",
+  "exports": {
+    ".": "./agentsafe-guard.mjs",
+    "./policy-core": "./policy-core.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "agentsafe-guard.mjs",
+    "policy-core.mjs",
+    "magp-did.mjs",
+    "x402.mjs",
+    "example-openclaw-agent.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node local-eval.smoke.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "ai",
+    "agent",
+    "agents",
+    "governance",
+    "ai-safety",
+    "guardrails",
+    "policy",
+    "mandate",
+    "authorization",
+    "ed25519",
+    "magp",
+    "metamynd",
+    "agentsafe",
+    "compliance"
+  ],
+  "author": "MetaMynd",
+  "license": "MIT",
+  "homepage": "https://github.com/jasimp18/AgentSafe/tree/main/integrations/agentsafe-guard#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jasimp18/AgentSafe.git",
+    "directory": "integrations/agentsafe-guard"
+  },
+  "bugs": {
+    "url": "https://github.com/jasimp18/AgentSafe/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/policy-core.mjs

@@ -0,0 +1,389 @@
+// GENERATED from backend/src/policy-core — do not edit. Regenerate: npm run build: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),
+  // 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)
+};
+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: "Amount over limit",
+    description: "Fires when the action amount exceeds a configured limit.",
+    config: [{ key: "limit", type: "number", required: true, description: "Maximum allowed amount" }],
+    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"]
+  }
+];
+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, escalate: 1, block: 2 };
+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 (!["block", "escalate"].includes(m.decision)) {
+      issues.push({ moleculeId: m.id, message: `invalid decision '${m.decision}' (block|escalate)` });
+    }
+    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, escalate: 1, block: 2 };
+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 };
+}
+export {
+  ATOM_REGISTRY,
+  ATOM_SPECS,
+  CATALOGUED_ATOMS,
+  applyCapture,
+  applyHold,
+  applySignedLast,
+  buildAuthMessage,
+  canAuthorize,
+  evaluate,
+  evaluateBoundStandards,
+  evaluateMandate,
+  evaluateStandardRules,
+  moleculeFires,
+  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: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
+};