@metamynd/agentsafe-guard 0.12.1 → 0.14.0

package/README.md

@@ -153,6 +153,45 @@ the guard — see "Passphrase-encrypted managed key" above. New export from `key
 backend's `encryptWithPassword`/`decryptWithPassword`, cross-verified against it). Fully
 additive: a config without `agentKeyEncrypted` is loaded exactly as before, no passphrase needed.
 
+**0.14.0 — sign the WHOLE payload, not just eight fields (MAGP §8.3.9).** The signed authorize message covers the
+agent, action, amount, currency, merchant and resource — not a payee, an account number or a passenger list. Pass
+`payload` to `authorize()` / `buildSignedRequest()` and the guard also signs a digest of it (RFC 8785 canonical JSON,
+`sha256:`), bound to that one authorization:
+
+```js
+await guard.authorize({ action: 'wire', amount: 250, currency: 'USD', merchant: 'skyward-air',
+  payload: { payee: { iban: 'NL91ABNA0417164300' }, reference: 'INV-1042' } });
+```
+
+The gate stores the digest with the hold, and the service that executes it (an `agentsafe-mcp-guard` with
+`bindPayload`, or an `agentsafe-http-gateway`, both 0.11.0) must present the digest of what it is about to run: a claim
+with a different payload is refused and the hold stays claimable. Pass the payload exactly as the service will receive
+it as JSON. A payload JSON cannot carry (`NaN`, a function, a lone surrogate) or a `keyProvider` that cannot sign a
+binding (the signer daemon, for now) **blocks** with `PAYLOAD_NOT_CANONICALIZABLE` / `PAYLOAD_BINDING_UNSUPPORTED` —
+it is never sent unbound. Off unless you pass `payload`; the wire body is otherwise unchanged. Also from `guardTool`: have `mapArgs`
+return `payload`. The gate echoes the digest it stored, and an agent that sent one **refuses a permit that does not echo
+it** (`PAYLOAD_BINDING_NOT_CONFIRMED`, releasing the hold) — so a proxy that strips the fields, or a backend that predates
+MAGP §8.3.9, is a loud failure, not a silently unbound request.
+
+**0.13.0 — a risk rule can no longer be skipped by staying silent about risk (D-03).** The rule layer
+now labels every context field with where it came from (`agent_asserted`, `agent_signed`,
+`gateway_derived`, `authoritative`, `attested`; MAGP §6.3) and judges `riskLevel` accordingly:
+
+- **A missing or unrecognised `riskLevel` escalates** (`CONTEXT_UNVERIFIABLE`) for any rule that uses the
+  risk atom, instead of reading as "not risky". `"HIGH"` and `" high "` are read as `high`. **If your requests
+  do not send a `riskLevel`, they will now escalate** — send one (`context: { riskLevel: 'low' }`), or have
+  your mandate's owner set a `riskTier` (below) so the risk does not depend on you.
+- **`riskTier` on a mandate permission** is the owner's classification of the action: a floor the agent's own
+  claim can never lower (the effective risk is the *maximum* of the tier and the claim — an agent may raise
+  its risk, never lower it). It travels in the signed mandate, so `evaluateLocally` and the issuer's gate agree.
+- **`requireProvenance`** on a rule (`{ riskLevel: 'authoritative' }`) makes it demand a trusted source: the
+  agent's own honest "low" is then not enough.
+- `evaluateLocally` builds its context the same way, and judges the SUPERVISED-mode high-risk escalation on
+  the effective risk.
+
+The claim itself is still the agent's word when no owner tier, gateway derivation or `requireProvenance`
+exists: this closes hiding and garbling risk, and gives owners the means to close understating it.
+
 ```yaml
 # .github/workflows/governance.yml
 name: Governance

package/agentsafe-guard.mjs

@@ -10,8 +10,10 @@
 // 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, operatingModeGate } from './policy-core.mjs';
+import { resolve as resolvePath } from 'node:path';
+import { evaluate, buildAuthMessage, applySignedLast, operatingModeGate, buildRuleContext, riskFloorFor, maxRisk, normalizeRiskLevel } from './policy-core.mjs';
 import { envelopeHashFor } from './governance-envelope.mjs';
+import { payloadDigestOf, toWireJson } from './payload-binding.mjs';
 import { verifyDidSignature } from './magp-did.mjs';
 import { checkSettlementBinding } from './x402.mjs';
 import { resolveKeyProvider, decryptAgentKeyWithPassword } from './key-providers.mjs';
@@ -84,6 +86,38 @@ export function executionAdapterFromEnv(env = (typeof process !== 'undefined' ?
  *   agentDid the agent's did:hedera
  *   agentKey the agent's Ed25519 private key (Hedera DER hex, held only by the agent)
  */
+/**
+ * Read + parse an agent config file, failing with the NEXT STEP rather than a bare `ENOENT`.
+ * `agent.metamynd.json` holds the agent's identity (and, for a managed key, its secret), so it is
+ * deliberately gitignored — which means a fresh clone of any agent project can never contain it.
+ * A raw "no such file or directory" left a first-time user with no way forward (beta regression
+ * 2026-09-20, BR-004); the message below names the three ways to get the file.
+ */
+function readConfigFile(path, who) {
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (e) {
+    if (e && e.code === 'ENOENT') {
+      throw new Error([
+        `${who}: no agent config at "${resolvePath(path)}".`,
+        `  agent.metamynd.json holds the agent's identity and key, so it is gitignored - a fresh clone never has it.`,
+        `  To get one:`,
+        `    1. New agent:      npx create-metamynd-agent      (creates the agent and writes this file)`,
+        `    2. Existing agent: dashboard -> Agents -> your agent -> download its configuration, save it as ${path}`,
+        `    3. Kept elsewhere: pass its real path, e.g. createGuardFromConfig('/path/to/agent.metamynd.json')`,
+        `  Then re-run. Step-by-step: https://metamynd.ai/developers/quickstart`,
+      ].join('\n'));
+    }
+    throw new Error(`${who}: cannot read agent config "${path}": ${e && e.message}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new Error(`${who}: "${path}" is not valid JSON (${e.message}). Re-download the configuration rather than editing it by hand.`);
+  }
+}
+
 /**
  * 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.
@@ -100,7 +134,7 @@ export function executionAdapterFromEnv(env = (typeof process !== 'undefined' ?
 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'));
+    cfg = /^https?:\/\//.test(source) ? await (await fetch(source)).json() : readConfigFile(source, 'createGuardFromConfig');
   }
   if (cfg && cfg.data && !cfg.agentDid) cfg = cfg.data; // unwrap a { success, data } API response
   const { passphrase, ...rest } = overrides;
@@ -119,8 +153,7 @@ export function createGuard(opts = {}) {
   // 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}`); }
+    cfg = readConfigFile(opts.configPath, 'createGuard');
   }
   if (cfg && cfg.data && !cfg.agentDid) cfg = cfg.data; // unwrap a { success, data } API response
   const api = opts.api ?? cfg?.apiBase ?? cfg?.api;
@@ -150,6 +183,27 @@ export function createGuard(opts = {}) {
     return keyProvider.signEnvelope({ agentDid, action, amount, currency, merchant, itinerary: context, trace, materiality, nonce, issuedAt });
   }
 
+  // Payload binding (spec §8.3.9): sign a digest of the COMPLETE payload the caller will execute, bound to THIS authorization
+  // (agent, action, nonce, issuedAt). The eight signed fields cover amount/merchant/resource only; everything else a tool takes
+  // (a payee, an account number) is otherwise unbound, and this is what binds it. `payload` is whatever the executing
+  // counterparty will receive — the JSON body a gateway forwards, or the arguments an MCP tool is called with — normalised to
+  // the JSON it would be on the wire. Fails CLOSED: if a binding was asked for and cannot be produced (a payload JSON cannot
+  // carry, or a key provider that cannot sign one), this throws — it never quietly sends the request unbound.
+  async function payloadBindingFor({ action, nonce, issuedAt, payload }) {
+    if (payload === undefined) return {};
+    let payloadDigest;
+    try {
+      payloadDigest = payloadDigestOf(toWireJson(payload));
+    } catch (err) {
+      throw Object.assign(new Error(`payload cannot be bound: ${err?.message ?? err}`), { code: 'PAYLOAD_NOT_CANONICALIZABLE' });
+    }
+    if (typeof keyProvider.signPayloadBinding !== 'function') {
+      throw Object.assign(new Error('this keyProvider cannot sign a payload binding (signPayloadBinding)'), { code: 'PAYLOAD_BINDING_UNSUPPORTED' });
+    }
+    const payloadSignature = await keyProvider.signPayloadBinding({ agentDid, action, nonce, issuedAt, payloadDigest });
+    return { payloadDigest, payloadSignature };
+  }
+
   // --- Enforcement mode (spec §9.2 + local-first plan) --------------------------------------
   // 'local' (DEFAULT): decide the rule layer LOCALLY against a cached signed bundle — a
   //   block/escalate needs no network; an allowed VALUE action is still sealed by the remote
@@ -182,7 +236,7 @@ export function createGuard(opts = {}) {
    * agent's authorization trustlessly against the agent's policy bundle (§9.3). Same shape
    * `authorize()` posts to the gate; a fresh nonce each call.
    */
-  async function buildSignedRequest({ action, amount, currency, merchant, resource, context = {}, trace, materiality }) {
+  async function buildSignedRequest({ action, amount, currency, merchant, resource, context = {}, trace, materiality, payload }) {
     const nonce = crypto.randomUUID();
     const issuedAt = new Date().toISOString();
     // This object is presented to a COUNTERPARTY (spec §9.3) — but its own docstring also
@@ -211,11 +265,12 @@ export function createGuard(opts = {}) {
     // action fields don't include it yet either (only amount/currency/merchant) — adding it
     // to just one side would break Tier-1 envelope-hash verification for any resource-
     // declaring request. A coordinated backend+guard follow-up, not something to do half here.
-    const [signature, envelopeSignature] = await Promise.all([
+    const [signature, envelopeSignature, binding] = await Promise.all([
       keyProvider.signAuthorize({ agentDid, action, amount: signedAmount, currency: signedCurrency, merchant, resource, nonce, issuedAt }),
       envelopeSignatureFor({ action, amount: wireAmount, currency: wireCurrency, merchant, context, trace, materiality, nonce, issuedAt }),
+      payloadBindingFor({ action, nonce, issuedAt, payload }),
     ]);
-    return { agentDid, action, amount: wireAmount, currency: wireCurrency, merchant, resource, itinerary: context, trace, materiality, nonce, issuedAt, signature, envelopeSignature };
+    return { agentDid, action, amount: wireAmount, currency: wireCurrency, merchant, resource, itinerary: context, trace, materiality, nonce, issuedAt, signature, envelopeSignature, ...binding };
   }
 
   /**
@@ -223,7 +278,7 @@ export function createGuard(opts = {}) {
    * 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, currency, merchant, resource, context = {}, trace, materiality }) {
+  async function authorize({ action, amount, currency, merchant, resource, context = {}, trace, materiality, payload }) {
     const nonce = crypto.randomUUID();
     const issuedAt = new Date().toISOString();
     try {
@@ -244,9 +299,10 @@ export function createGuard(opts = {}) {
       // see key-providers.mjs for why callers pass structured fields, not a pre-built string.
       // `resource` deliberately NOT passed to envelopeSignatureFor — see buildSignedRequest's
       // own comment on why (backend governance-envelope.ts doesn't include it yet either).
-      const [signature, envelopeSignature] = await Promise.all([
+      const [signature, envelopeSignature, binding] = await Promise.all([
         keyProvider.signAuthorize({ agentDid, action, amount: signedAmount, currency: signedCurrency, merchant, resource, nonce, issuedAt }),
         envelopeSignatureFor({ action, amount, currency, merchant, context, trace, materiality, nonce, issuedAt }),
+        payloadBindingFor({ action, nonce, issuedAt, payload }),
       ]);
       const res = await fetch(`${base}/policy/mandate/authorize`, {
         method: 'POST',
@@ -258,11 +314,27 @@ export function createGuard(opts = {}) {
           agentDid, action, amount, currency, merchant, resource, itinerary: context, trace, materiality, nonce, issuedAt,
           signature,
           envelopeSignature,
+          ...binding, // payloadDigest + payloadSignature, or nothing for an unbound request
         }),
       });
       const body = await res.json().catch(() => null);
-      return body?.data ?? { decision: 'block', reasonCode: `GATE_HTTP_${res.status}` };
+      const data = body?.data ?? { decision: 'block', reasonCode: `GATE_HTTP_${res.status}` };
+      // The gate ACKNOWLEDGES a binding by echoing the digest it stored. A permit or escalation that does not — a hop stripped
+      // the fields, or the backend predates payload binding and ignored them — was never bound, and this agent must not act as
+      // if it were: refuse, and release the hold it just got (best effort; an unclaimed hold also lapses on its own).
+      if (binding.payloadDigest && (data.decision === 'allow' || data.decision === 'observe' || data.decision === 'escalate') && data.payloadDigest !== binding.payloadDigest) {
+        if (data.authorizationId) {
+          fetch(`${base}/policy/mandate/authorize/${encodeURIComponent(data.authorizationId)}/void`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' }).catch(() => {});
+        }
+        return { decision: 'block', reasonCode: 'PAYLOAD_BINDING_NOT_CONFIRMED', authorizationId: null, error: 'the gate did not confirm the payload binding (an older backend, or the digest was stripped in transit)' };
+      }
+      return data;
     } catch (err) {
+      // A payload binding that was asked for and cannot be produced is its own answer — NOT a gate outage, and never a
+      // reason to send the request unbound. Fail closed with the real cause.
+      if (err?.code === 'PAYLOAD_NOT_CANONICALIZABLE' || err?.code === 'PAYLOAD_BINDING_UNSUPPORTED') {
+        return { decision: 'block', reasonCode: err.code, error: String(err.message) };
+      }
       // A daemon-backed keyProvider can fail before the gate is ever reached (the signer, not
       // the gate, was unreachable) — a distinct reasonCode so this doesn't read as a gate outage
       // it wasn't. Still fail-CLOSED either way, which is the property that actually matters.
@@ -315,7 +387,9 @@ export function createGuard(opts = {}) {
     // SIBLING (like `contained`) and biases the edge verdict identically to the gate.
     // READ_ONLY denies a value-bearing action up-front; SUPERVISED/RESTRICTED only
     // ESCALATE, applied to the verdict below so a rule block/escalate still outranks it.
-    const modeGate = operatingModeGate(operatingMode?.mode, { amount, riskLevel: context?.riskLevel });
+    // The EFFECTIVE risk (spec §6.4.3): the owner's tier in the mandate is a floor under the agent's own claim, so
+    // this local pre-check agrees with the gate instead of telling the agent "low" is enough.
+    const modeGate = operatingModeGate(operatingMode?.mode, { amount, riskLevel: maxRisk(riskFloorFor(mandate, action), normalizeRiskLevel(context?.riskLevel)) ?? undefined });
     if (modeGate.decision === 'block') {
       return { decision: 'block', reasonCode: modeGate.reasonCode, authorizationId: null, remaining: null, proofRef: null };
     }
@@ -330,7 +404,7 @@ export function createGuard(opts = {}) {
       // omitting them here means a currency-scoped amount-over/cumulative-over Standards/SOP
       // atom always sees currency as absent and fires closed. Mirrors mandate.service.ts's
       // ruleCtx (PR #588) and the same fix in agentsafe-mcp-guard.mjs's verdictFromBundle.
-      context: applySignedLast(context, { action, agentDid, amount, currency, merchant, resource }),
+      context: buildRuleContext({ unsigned: context, signed: { action, agentDid, amount, currency, merchant, resource }, riskFloor: riskFloorFor(mandate, action) }),
       mandateRequest: mandate
         ? {
             target: action,

package/cli.mjs

@@ -19,7 +19,19 @@ if (cmd === 'demo') {
   // or when a control named by --require is not configured at all.
   const { verify } = await import('./verify.mjs');
   try {
+    // --context <file>: the request context of a request that satisfies every rule (see verify.mjs).
+    let context;
+    // flag() is null when absent and '' when given with no value (`--context` last, or an unset shell
+    // variable) — the latter must be an error, not a silent bare run.
+    if (flag('context') !== null) {
+      const path = flag('context');
+      if (!path) throw new Error('--context needs a file path');
+      try { context = JSON.parse((await import('node:fs')).readFileSync(path, 'utf8')); }
+      catch (e) { throw new Error(`cannot read --context ${path}: ${e.message}`); }
+      if (context === null || typeof context !== 'object' || Array.isArray(context)) throw new Error(`--context ${path} must contain a JSON object`);
+    }
     const result = await verify({
+      context,
       configPath: flag('config') ?? './agent.metamynd.json',
       require: (flag('require') ?? '').split(',').map((s) => s.trim()).filter(Boolean),
       json: process.argv.includes('--json'),
@@ -50,6 +62,9 @@ if (cmd === 'demo') {
       --config <path>     agent config (default ./agent.metamynd.json)
       --require <a,b>     fail when a control is NOT configured, e.g.
                           --require merchants,perTxn
+      --context <path>    JSON file: the request context of a request that
+                          satisfies every rule (rule inputs like consent or
+                          evidenceTypes), for policies that require inputs
       --json              machine-readable output
 
     A control the mandate does not set is reported, never passed: an empty

package/key-providers.mjs

@@ -12,6 +12,7 @@ import net from 'node:net';
 import path from 'node:path';
 import { buildAuthMessage, buildLocalDecisionMessage } from './policy-core.mjs';
 import { envelopeHashFor } from './governance-envelope.mjs';
+import { buildPayloadBindingMessage } from './payload-binding.mjs';
 
 /**
  * Today's default: the raw key lives in THIS process (see the design doc's "What this does not
@@ -37,6 +38,12 @@ export function createStaticKeyProvider(agentKeyHex) {
     async signLocalDecision(fields) {
       return rawSign(buildLocalDecisionMessage(fields));
     },
+    // Payload binding (spec 8.3.9): sign the digest of the COMPLETE payload, bound to this authorization. OPTIONAL like
+    // signLocalDecision; the guard refuses (fail closed) to send an unbound request when a binding was asked for and the
+    // provider cannot produce one.
+    async signPayloadBinding(fields) {
+      return rawSign(buildPayloadBindingMessage(fields));
+    },
   };
 }
 
@@ -129,6 +136,12 @@ export function createDaemonKeyProvider({ socketPath }) {
       const { signature } = await daemonRequest(socketPath, 'sign-local-decision', fields);
       return signature;
     },
+    // The daemon builds every message it signs from structured fields and will not sign arbitrary bytes, so payload binding
+    // needs its own `sign-payload` operation there. Until that exists this refuses, LOUDLY and closed: a guard asked to bind
+    // a payload must never fall back to sending the request unbound.
+    async signPayloadBinding() {
+      throw Object.assign(new Error('the agentsafe-signer daemon does not support payload binding yet (sign-payload); use a static key provider, or omit `payload`'), { code: 'PAYLOAD_BINDING_UNSUPPORTED' });
+    },
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-guard",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "Zero-dependency runtime governance for any Node AI agent \u2014 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",
@@ -20,13 +20,14 @@
     "policy-core.mjs",
     "governance-envelope.mjs",
     "magp-did.mjs",
+    "payload-binding.mjs",
     "x402.mjs",
     "example-openclaw-agent.mjs",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "test": "node demo.mjs && node local-eval.smoke.mjs && node execution-adapter.smoke.mjs && node verify.smoke.mjs && node context-signature.smoke.mjs && node local-decision-report.smoke.mjs && node resource-constraint.smoke.mjs && node passphrase-key.smoke.mjs",
+    "test": "node demo.mjs && node local-eval.smoke.mjs && node execution-adapter.smoke.mjs && node verify.smoke.mjs && node context-signature.smoke.mjs && node payload-binding.smoke.mjs && node local-decision-report.smoke.mjs && node resource-constraint.smoke.mjs && node passphrase-key.smoke.mjs && node missing-config.smoke.mjs",
     "demo": "node demo.mjs"
   },
   "engines": {

package/payload-binding.mjs

@@ -0,0 +1,110 @@
+// GENERATED from backend/src/features/magp/payload-binding.ts - do not edit. Regenerate: npm run build:guard-core
+
+// src/features/magp/payload-binding.ts
+import { createHash } from "node:crypto";
+
+// src/policy-core/canonical.ts
+function escapeField(v) {
+  return v.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+}
+
+// src/features/magp/payload-binding.ts
+var PAYLOAD_BINDING_PREFIX = "MAGP-PAYLOAD-v1";
+var PAYLOAD_DIGEST_PREFIX = "sha256:";
+var PAYLOAD_DIGEST_HEADER = "x-magp-payload-digest";
+var MAX_CANONICAL_PAYLOAD_BYTES = 256 * 1024;
+var MAX_DEPTH = 32;
+var PayloadNotCanonicalizable = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PayloadNotCanonicalizable";
+  }
+};
+function hasLoneSurrogate(s) {
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c >= 55296 && c <= 56319) {
+      const next = s.charCodeAt(i + 1);
+      if (!(next >= 56320 && next <= 57343)) return true;
+      i++;
+    } else if (c >= 56320 && c <= 57343) {
+      return true;
+    }
+  }
+  return false;
+}
+function serialize(value, depth, path) {
+  if (depth > MAX_DEPTH) throw new PayloadNotCanonicalizable(`payload is nested deeper than ${MAX_DEPTH} levels at ${path}`);
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "boolean":
+      return value ? "true" : "false";
+    case "number":
+      if (!Number.isFinite(value)) throw new PayloadNotCanonicalizable(`${path} is not a finite number`);
+      return JSON.stringify(value);
+    // ECMAScript Number::toString — what RFC 8785 specifies; -0 serialises as "0"
+    case "string":
+      if (hasLoneSurrogate(value)) throw new PayloadNotCanonicalizable(`${path} contains an unpaired surrogate`);
+      return JSON.stringify(value);
+    case "object": {
+      if (Array.isArray(value)) return `[${value.map((v, i) => serialize(v, depth + 1, `${path}[${i}]`)).join(",")}]`;
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) throw new PayloadNotCanonicalizable(`${path} is not a plain JSON object`);
+      const obj = value;
+      const keys = Object.keys(obj).sort();
+      const parts = keys.map((k) => {
+        if (hasLoneSurrogate(k)) throw new PayloadNotCanonicalizable(`${path} has a key with an unpaired surrogate`);
+        return `${JSON.stringify(k)}:${serialize(obj[k], depth + 1, `${path}.${k}`)}`;
+      });
+      return `{${parts.join(",")}}`;
+    }
+    default:
+      throw new PayloadNotCanonicalizable(`${path} is a ${typeof value}, which JSON cannot represent`);
+  }
+}
+function canonicalPayload(value) {
+  const text = serialize(value, 0, "$");
+  if (Buffer.byteLength(text, "utf8") > MAX_CANONICAL_PAYLOAD_BYTES) {
+    throw new PayloadNotCanonicalizable(`canonical payload exceeds ${MAX_CANONICAL_PAYLOAD_BYTES} bytes`);
+  }
+  return text;
+}
+function payloadDigestOf(value) {
+  return PAYLOAD_DIGEST_PREFIX + createHash("sha256").update(canonicalPayload(value), "utf8").digest("hex");
+}
+var DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+function isPayloadDigest(value) {
+  return typeof value === "string" && DIGEST_RE.test(value);
+}
+function toWireJson(value) {
+  const text = JSON.stringify(value);
+  if (text === void 0) throw new PayloadNotCanonicalizable("payload is not JSON-serialisable");
+  return JSON.parse(text);
+}
+function buildPayloadBindingMessage(input) {
+  return [PAYLOAD_BINDING_PREFIX, input.agentDid, input.action, input.nonce, input.issuedAt, input.payloadDigest].map((f) => escapeField(String(f))).join("|");
+}
+function decideClaimPayload(stored, presented) {
+  if (stored) {
+    if (!presented) return { ok: false, reasonCode: "PAYLOAD_DIGEST_REQUIRED" };
+    return presented === stored ? { ok: true } : { ok: false, reasonCode: "PAYLOAD_DIGEST_MISMATCH" };
+  }
+  return presented ? { ok: false, reasonCode: "PAYLOAD_NOT_BOUND_AT_AUTHORIZE" } : { ok: true };
+}
+function claimDigestField(payloadDigest) {
+  return `payload=${payloadDigest}`;
+}
+export {
+  MAX_CANONICAL_PAYLOAD_BYTES,
+  PAYLOAD_BINDING_PREFIX,
+  PAYLOAD_DIGEST_HEADER,
+  PAYLOAD_DIGEST_PREFIX,
+  PayloadNotCanonicalizable,
+  buildPayloadBindingMessage,
+  canonicalPayload,
+  claimDigestField,
+  decideClaimPayload,
+  isPayloadDigest,
+  payloadDigestOf,
+  toWireJson
+};

package/policy-core.mjs

@@ -1,5 +1,129 @@
 // GENERATED from backend/src/policy-core — do not edit. Regenerate: npm run build:guard-core
 
+// src/policy-core/provenance.ts
+var PROVENANCE_LEVELS = ["agent_asserted", "agent_signed", "gateway_derived", "authoritative", "attested"];
+var PROVENANCE_RANK = {
+  agent_asserted: 0,
+  agent_signed: 1,
+  gateway_derived: 2,
+  authoritative: 3,
+  attested: 4
+};
+function isProvenance(v) {
+  return typeof v === "string" && Object.prototype.hasOwnProperty.call(PROVENANCE_RANK, v);
+}
+var PROVENANCE_KEY = Symbol.for("magp.context.provenance");
+function provenanceOf(ctx, field) {
+  const map = ctx?.[PROVENANCE_KEY];
+  const p = map && typeof map === "object" ? map[field] : void 0;
+  return isProvenance(p) ? p : "agent_asserted";
+}
+function meetsProvenance(actual, minimum) {
+  return PROVENANCE_RANK[actual] >= PROVENANCE_RANK[minimum];
+}
+var RISK_LEVELS = ["low", "medium", "high", "critical"];
+var RISK_ORDER = { low: 0, medium: 1, high: 2, critical: 3 };
+function normalizeRiskLevel(v) {
+  if (typeof v !== "string") return null;
+  const s = v.trim().toLowerCase();
+  return Object.prototype.hasOwnProperty.call(RISK_ORDER, s) ? s : null;
+}
+function maxRisk(...levels) {
+  let best = null;
+  for (const l of levels) if (l && (best === null || RISK_ORDER[l] > RISK_ORDER[best])) best = l;
+  return best;
+}
+function riskFloorFor(mandate, target) {
+  if (!mandate) return null;
+  let floor = null;
+  for (const p of mandate.permission ?? []) {
+    if (!p || typeof p !== "object") continue;
+    if ((p.target ?? mandate.target) !== target) continue;
+    floor = maxRisk(floor, normalizeRiskLevel(p.riskTier));
+  }
+  return floor;
+}
+var FIELD_KINDS = {
+  riskLevel: "risk",
+  consent: "boolean",
+  piiPresent: "boolean",
+  amount: "number",
+  cumulativeSpend: "number",
+  callCount: "number",
+  evidenceConfidence: "number",
+  holTrustScore: "number",
+  dataSourceId: "string",
+  jurisdiction: "string",
+  dataResidency: "string",
+  model: "string",
+  tool: "string",
+  currency: "string",
+  action: "string",
+  prompt: "string",
+  output: "string",
+  evidenceTypes: "string[]"
+};
+function contextFieldProblem(ctx, field) {
+  const v = ctx?.[field];
+  if (v === void 0 || v === null) return "missing";
+  if (typeof v === "string" && v.trim() === "") return "missing";
+  switch (FIELD_KINDS[field]) {
+    case "risk":
+      return normalizeRiskLevel(v) === null ? "malformed" : null;
+    case "boolean":
+      return typeof v === "boolean" ? null : "malformed";
+    case "number":
+      return typeof v === "number" && Number.isFinite(v) ? null : "malformed";
+    case "string":
+      return typeof v === "string" ? null : "malformed";
+    case "string[]":
+      return Array.isArray(v) && v.every((x) => typeof x === "string") ? null : "malformed";
+    default:
+      return null;
+  }
+}
+var ATOM_DEFAULT_REQUIRED_CONTEXT = {
+  "risk-at-or-above": ["riskLevel"]
+};
+function buildRuleContext(src) {
+  const ctx = {};
+  const prov = /* @__PURE__ */ Object.create(null);
+  const put = (k, v, level) => {
+    Object.defineProperty(ctx, k, { value: v, enumerable: true, writable: true, configurable: true });
+    prov[k] = level;
+  };
+  const layers = [
+    [src.unsigned, "agent_asserted"],
+    [src.signed, "agent_signed"],
+    [src.gatewayDerived, "gateway_derived"],
+    [src.serverDerived, "authoritative"]
+  ];
+  for (const [layer, level] of layers) {
+    for (const [k, v] of Object.entries(layer ?? {})) {
+      if (k === "riskLevel" && (level === "gateway_derived" || level === "authoritative") && normalizeRiskLevel(v) === null) continue;
+      put(k, v, level);
+    }
+  }
+  const floors = [];
+  const addFloor = (v, source) => {
+    const n = normalizeRiskLevel(v);
+    if (n) floors.push({ level: n, source });
+  };
+  addFloor(src.riskFloor, "authoritative");
+  addFloor(src.gatewayDerived?.riskLevel, "gateway_derived");
+  addFloor(src.serverDerived?.riskLevel, "authoritative");
+  const assertedUnsigned = normalizeRiskLevel(src.unsigned?.riskLevel);
+  const assertedSigned = normalizeRiskLevel(src.signed?.riskLevel);
+  const asserted = maxRisk(assertedUnsigned, assertedSigned);
+  if (floors.length > 0) {
+    put("riskLevel", maxRisk(asserted, ...floors.map((f) => f.level)), floors.reduce((best, f) => PROVENANCE_RANK[f.source] > PROVENANCE_RANK[best] ? f.source : best, "agent_asserted"));
+  } else if (asserted) {
+    put("riskLevel", asserted, assertedSigned ? "agent_signed" : "agent_asserted");
+  }
+  Object.defineProperty(ctx, PROVENANCE_KEY, { value: prov, enumerable: true, writable: false });
+  return ctx;
+}
+
 // src/policy-core/atom-registry.ts
 var RISK_RANK = { low: 0, medium: 1, high: 2, critical: 3 };
 function currencyOutOfScope(ctx, cfgCurrency) {
@@ -14,7 +138,8 @@ 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 haveLevel = normalizeRiskLevel(c.riskLevel);
+    const have = haveLevel === null ? void 0 : RISK_RANK[haveLevel];
     const need = RISK_RANK[String(cfg?.level ?? "high")];
     return have !== void 0 && need !== void 0 && have >= need;
   },
@@ -276,6 +401,7 @@ function requiredContextFor(predicates) {
 }
 
 // src/policy-core/standards-rules.ts
+var CONTEXT_UNVERIFIABLE = "CONTEXT_UNVERIFIABLE";
 var PRECEDENCE = { allow: 0, observe: 1, escalate: 2, block: 3, suspend: 4, quarantine: 5, decommission: 6 };
 function atomFires(atom, ctx) {
   const pred = ATOM_REGISTRY[atom.predicate];
@@ -304,17 +430,49 @@ function moleculeFires(m, ctx) {
       return false;
   }
 }
+function requiredContextOf(m) {
+  const required = /* @__PURE__ */ new Map();
+  const need = (field, level) => {
+    const have = required.get(field);
+    if (!have || PROVENANCE_RANK[level] > PROVENANCE_RANK[have]) required.set(field, level);
+  };
+  for (const a of m.atoms ?? []) {
+    if (!Object.prototype.hasOwnProperty.call(ATOM_DEFAULT_REQUIRED_CONTEXT, a.predicate)) continue;
+    for (const f of ATOM_DEFAULT_REQUIRED_CONTEXT[a.predicate]) need(f, "agent_asserted");
+  }
+  for (const [f, level] of Object.entries(m.requireProvenance ?? {})) {
+    need(f, isProvenance(level) ? level : "attested");
+  }
+  return required;
+}
+function moleculeUnverifiable(m, ctx) {
+  const bad = [];
+  for (const [field, minimum] of requiredContextOf(m)) {
+    if (contextFieldProblem(ctx, field) !== null || !meetsProvenance(provenanceOf(ctx, field), minimum)) bad.push(field);
+  }
+  return bad.sort();
+}
 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 };
-      }
+    const fired = moleculeFires(m, ctx);
+    const unverifiable = moleculeUnverifiable(m, ctx);
+    if (!fired && unverifiable.length === 0) continue;
+    let decision = fired ? m.decision : "escalate";
+    if (unverifiable.length > 0 && PRECEDENCE[decision] < PRECEDENCE.escalate) decision = "escalate";
+    const reasonCode = fired ? m.reasonCode : CONTEXT_UNVERIFIABLE;
+    if (!best || PRECEDENCE[decision] > PRECEDENCE[best.decision]) {
+      best = { decision, reasonCode, id: m.id, unverifiable: unverifiable.length > 0 ? unverifiable : void 0 };
     }
   }
   if (!best) return { decision: "allow", reasonCode: null, firedMoleculeId: null, standardKey };
-  return { decision: best.decision, reasonCode: best.reasonCode, firedMoleculeId: best.id, standardKey };
+  return {
+    decision: best.decision,
+    reasonCode: best.reasonCode,
+    firedMoleculeId: best.id,
+    standardKey,
+    ...best.unverifiable ? { unverifiableContext: best.unverifiable } : {}
+  };
 }
 function evaluateBoundStandards(standards, ctx) {
   let best = { decision: "allow", reasonCode: null, firedMoleculeId: null, standardKey: null };
@@ -369,6 +527,19 @@ function validateMolecules(molecules) {
     if (!m.atoms || m.atoms.length === 0) {
       issues.push({ moleculeId: m.id, message: "molecule has no atoms" });
     }
+    if (m.requireProvenance !== void 0) {
+      const rp = m.requireProvenance;
+      if (rp === null || typeof rp !== "object" || Array.isArray(rp)) {
+        issues.push({ moleculeId: m.id, message: "requireProvenance must be an object of { field: level }" });
+      } else {
+        for (const [field, level] of Object.entries(rp)) {
+          if (field.trim() === "") issues.push({ moleculeId: m.id, message: "requireProvenance has an empty field name" });
+          if (!isProvenance(level)) {
+            issues.push({ moleculeId: m.id, message: `requireProvenance '${field}' must be one of agent_asserted|agent_signed|gateway_derived|authoritative|attested` });
+          }
+        }
+      }
+    }
     for (const a of m.atoms ?? []) {
       if (!ATOM_REGISTRY[a.predicate]) {
         issues.push({ moleculeId: m.id, message: `unknown atom predicate '${a.predicate}'` });
@@ -406,9 +577,14 @@ var REASON_BY_OPERAND = {
   "mm:route": "ROUTE_NOT_ALLOWED",
   "mm:counterparty": "COUNTERPARTY_NOT_ALLOWED"
 };
-function reasonFor(constraint) {
+var AMOUNT_OPERANDS = /* @__PURE__ */ new Set(["mm:payAmount", "mm:cumulativeSpend"]);
+function reasonFor(constraint, req) {
   if (!constraint) return "CONSTRAINT_FAILED";
-  return REASON_BY_OPERAND[constraint.leftOperand] ?? `CONSTRAINT_FAILED:${constraint.leftOperand}`;
+  const { leftOperand } = constraint;
+  if (AMOUNT_OPERANDS.has(leftOperand) && !Object.prototype.hasOwnProperty.call(req.values, leftOperand)) {
+    return "AMOUNT_NOT_DETERMINABLE";
+  }
+  return REASON_BY_OPERAND[leftOperand] ?? `CONSTRAINT_FAILED:${leftOperand}`;
 }
 function constraintSatisfied(c, req, strict) {
   const op = OPERATORS[c.operator];
@@ -464,7 +640,7 @@ function evaluateMandate(mandate, req) {
   const firstFail = (perms[0].constraint ?? []).find((c) => !constraintSatisfied(c, req, true));
   return {
     decision: firstFail?.onFail ?? "block",
-    reasonCode: reasonFor(firstFail),
+    reasonCode: reasonFor(firstFail, req),
     matched: { kind: "permission", target: perms[0].target, constraint: firstFail }
   };
 }
@@ -516,6 +692,9 @@ function escapeField(v) {
 function buildAuthMessage(f) {
   return [f.agentDid, f.action, f.amount, f.currency, f.merchant ?? "", f.resource ?? "", f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
 }
+function buildLegacyAuthMessageV1(f) {
+  return [f.agentDid, f.action, f.amount, f.currency, f.merchant ?? "", f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
+}
 function buildLocalDecisionMessage(f) {
   return [f.agentDid, f.action, f.decision, f.reasonCode, f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
 }
@@ -569,11 +748,17 @@ function operatingModeGate(mode, ctx) {
   }
 }
 export {
+  ATOM_DEFAULT_REQUIRED_CONTEXT,
   ATOM_REGISTRY,
   ATOM_SPECS,
   CATALOGUED_ATOMS,
+  CONTEXT_UNVERIFIABLE,
   MODES_BY_RANK,
   MODE_RANK,
+  PROVENANCE_KEY,
+  PROVENANCE_LEVELS,
+  PROVENANCE_RANK,
+  RISK_LEVELS,
   SUPERVISED_AMOUNT_CAP,
   applyCapture,
   applyHold,
@@ -582,20 +767,31 @@ export {
   authorityFailure,
   buildAuthMessage,
   buildCheckpointAnchorMessage,
+  buildLegacyAuthMessageV1,
   buildLocalDecisionMessage,
+  buildRuleContext,
   canAuthorize,
+  contextFieldProblem,
   evaluate,
   evaluateBoundStandards,
   evaluateMandate,
   evaluateStandardRules,
   isAuthorityFailure,
   isOperatingMode,
+  isProvenance,
+  maxRisk,
+  meetsProvenance,
   moleculeFires,
+  moleculeUnverifiable,
   moreRestrictive,
+  normalizeRiskLevel,
   operatingModeGate,
+  provenanceOf,
   releaseHold,
   remainingBudget,
   requiredContextFor,
+  requiredContextOf,
+  riskFloorFor,
   sumEventField,
   validateMolecules
 };

package/verify.mjs

@@ -41,7 +41,7 @@ const CONTROLS = {
     detail: 'the ceiling on any single action',
     configured: (c) => {
       const k = c.find((x) => x.leftOperand === 'mm:payAmount' && x.operator === 'lteq');
-      return k ? { configured: true, summary: `${k.rightOperand}${k.unit ? ' ' + k.unit : ''}`, limit: Number(k.rightOperand) } : { configured: false };
+      return k ? { configured: true, summary: `${k.rightOperand}${k.unit ? ' ' + k.unit : ''}`, limit: Number(k.rightOperand), unit: k.unit } : { configured: false };
     },
   },
   cumulative: {
@@ -49,7 +49,7 @@ const CONTROLS = {
     detail: 'the ceiling on total spend across actions',
     configured: (c) => {
       const k = c.find((x) => x.leftOperand === 'mm:cumulativeSpend' && x.operator === 'lteq');
-      return k ? { configured: true, summary: `${k.rightOperand}${k.unit ? ' ' + k.unit : ''}`, limit: Number(k.rightOperand) } : { configured: false };
+      return k ? { configured: true, summary: `${k.rightOperand}${k.unit ? ' ' + k.unit : ''}`, limit: Number(k.rightOperand), unit: k.unit } : { configured: false };
     },
   },
   merchants: {
@@ -92,7 +92,15 @@ function packsFor(bundle, action) {
 
 const permits = (v) => v.decision === 'allow' || v.decision === 'observe';
 
-export async function verify({ configPath = './agent.metamynd.json', require: required = [], json = false, log = console.log, env = process.env } = {}) {
+/**
+ * `context` is the request context of a request that satisfies every rule in the agent's policy
+ * (rule inputs such as `consent`, `evidenceTypes`, `jurisdiction`). The baseline and cap checks send
+ * it, because a policy that REQUIRES an input blocks a request without it — which would make the
+ * baseline report a healthy agent as broken, and let a cap "hold" for the wrong reason. Omit it for
+ * a policy with no input-dependent rules (the old behaviour, unchanged). The scope check never
+ * uses it: an ungranted action must be refused whatever the context says.
+ */
+export async function verify({ configPath = './agent.metamynd.json', require: required = [], json = false, log = console.log, env = process.env, context: baseContext = {} } = {}) {
   // AGENT_KEY / AGENT_DID / METAMYND_API from the environment win over the config file.
   // CI is the whole point of this command, and a CI story that requires committing the
   // agent's signing key to the repository is not one — so a key-less config plus a secret
@@ -116,6 +124,12 @@ export async function verify({ configPath = './agent.metamynd.json', require: re
   const found = {};
   for (const [key, spec] of Object.entries(CONTROLS)) found[key] = spec.configured(constraints);
 
+  // The probes must be denominated in the currency the mandate's caps are. `evaluateLocally` assumes USD when a
+  // request names none, and a cap in any other currency refuses a currency-less or mismatched request (fail-closed),
+  // so a GBP agent would fail its own baseline check and read as broken. Only a cap that names a unit sets one.
+  const unitOf = (control) => (control.unit ? { currency: control.unit } : {});
+  const baselineCurrency = unitOf(found.perTxn.configured ? found.perTxn : found.cumulative);
+
   const checks = [];
   const add = (control, status, assertion, verdict, note) =>
     checks.push({ control, status, assertion, decision: verdict?.decision ?? null, reasonCode: verdict?.reasonCode ?? null, note });
@@ -125,7 +139,7 @@ export async function verify({ configPath = './agent.metamynd.json', require: re
   {
     const amount = found.perTxn.configured ? Math.max(1, Math.floor(found.perTxn.limit / 2)) : 1;
     const merchant = found.merchants.list?.length ? found.merchants.list[0] : 'any-merchant';
-    const v = evaluate({ action, amount, merchant, context: { riskLevel: 'low' } });
+    const v = evaluate({ action, amount, ...baselineCurrency, merchant, context: { riskLevel: 'low', ...baseContext } });
     add('baseline', permits(v) ? PASS : FAIL, 'permits ordinary in-scope work', v,
       permits(v) ? null : 'the agent cannot perform the action it was issued for');
   }
@@ -141,7 +155,7 @@ export async function verify({ configPath = './agent.metamynd.json', require: re
   // 3–5. Only assert a limit the mandate actually sets. Asserting an absent control is how
   //      you end up believing in one.
   if (found.perTxn.configured) {
-    const v = evaluate({ action, amount: found.perTxn.limit + 1, merchant: found.merchants.list?.length ? found.merchants.list[0] : 'any-merchant', context: {} });
+    const v = evaluate({ action, amount: found.perTxn.limit + 1, ...unitOf(found.perTxn), merchant: found.merchants.list?.length ? found.merchants.list[0] : 'any-merchant', context: { ...baseContext } });
     add('perTxn', permits(v) ? FAIL : PASS, `refuses ${found.perTxn.limit + 1} against a cap of ${found.perTxn.limit}`, v,
       permits(v) ? 'the per-transaction cap did not hold' : null);
   } else {
@@ -150,8 +164,8 @@ export async function verify({ configPath = './agent.metamynd.json', require: re
 
   if (found.cumulative.configured) {
     const v = evaluate({
-      action, amount: 1, merchant: found.merchants.list?.length ? found.merchants.list[0] : 'any-merchant',
-      cumulativeSpend: found.cumulative.limit + 1, context: {},
+      action, amount: 1, ...unitOf(found.cumulative), merchant: found.merchants.list?.length ? found.merchants.list[0] : 'any-merchant',
+      cumulativeSpend: found.cumulative.limit + 1, context: { ...baseContext },
     });
     add('cumulative', permits(v) ? FAIL : PASS, `refuses spending past a total of ${found.cumulative.limit}`, v,
       permits(v) ? 'the cumulative cap did not hold' : null);
@@ -166,7 +180,7 @@ export async function verify({ configPath = './agent.metamynd.json', require: re
     // Deliberately UNDER any cap: a refusal at an amount that also trips a spend limit
     // proves nothing about merchants, which is exactly how this went unnoticed before.
     const amt = found.perTxn.configured ? Math.max(1, Math.floor(found.perTxn.limit / 2)) : 1;
-    const v = evaluate({ action, amount: amt, merchant: '__unapproved_supplier__', context: {} });
+    const v = evaluate({ action, amount: amt, ...baselineCurrency, merchant: '__unapproved_supplier__', context: { ...baseContext } });
     add('merchants', permits(v) ? FAIL : PASS, 'refuses an unlisted merchant, under the cap', v,
       permits(v) ? 'the merchant allow-list did not hold' : null);
   } else {