@metamynd/agentsafe-mcp-guard 0.6.2 → 0.11.0

package/README.md

@@ -159,6 +159,107 @@ signing requests close together could race that replacement window and fail with
 `DAEMON_UNREACHABLE` even though the daemon was healthy. `key-providers.mjs` now retries a
 connection that fails with `ENOENT` for up to 3 seconds before giving up. No API change.
 
+**0.11.0 — payload binding: the claim states what this Service will actually execute (MAGP §8.3.9, §8.7.11).**
+`guardIncomingTool(action, handler, { bindPayload: true })` digests the tool's arguments (or `bindPayload: (signed, ...args) => value`
+to choose), refuses locally (`PAYLOAD_NOT_BOUND`) when they differ from the digest the agent signed, and sends the digest with the
+claim — in the `x-magp-payload-digest` header and as a signed field of the claim message — so the issuer compares it with the
+digest it stored at authorize time and refuses a mismatch, leaving the hold unclaimed. `requirePayloadBinding: true` also refuses
+an authorization the agent did not bind (`PAYLOAD_BINDING_REQUIRED`). A payload JSON cannot carry is refused
+(`PAYLOAD_NOT_CANONICALIZABLE`), not skipped, and a grant that does not echo the digest (an issuer that predates binding) is
+refused too. Both options are off by default; `verifyRequest(signed, { payloadDigest, requirePayloadBinding })` is the lower-level form.
+
+**0.10.0 — the agent can no longer skip a risk rule by hiding or understating its risk (D-03).** The rules
+now judge `riskLevel` with provenance (MAGP §6.3), identically to the issuer's gate:
+
+- A missing or unrecognised `riskLevel` **escalates** (`CONTEXT_UNVERIFIABLE`) for any rule that uses the
+  risk atom (it used to read as "not risky" and be allowed); `"HIGH"` is read as `high`. An agent that sends no
+  `riskLevel` will now be escalated.
+- **`trustedContext`** — what *this Service* derived from the real call, never from the agent. Pass it to
+  `verifyRequest(signed, { trustedContext: { riskLevel: 'high' } })`, or per tool:
+  `guardIncomingTool('wire-transfer', handler, { trustedContext: { riskLevel: 'high' } })` (an object, or
+  `(signed, ...rest) => object`). It is applied over the agent's claim and labelled `gateway_derived`; the agent
+  can raise its risk above it, never lower it below it. A deriver that throws, or that is configured but yields
+  nothing usable (returns `undefined`, a non-object, or a `riskLevel` that is not a level), fails the call closed —
+  it never falls back to the agent's word.
+- The mandate's owner-set **`riskTier`** (in the signed bundle) is a further floor, so the agent's "low" about an
+  action the owner classed `high` is judged `high`; and the SUPERVISED-mode high-risk escalation judges that
+  effective risk too.
+- A rule can demand a trusted source with `requireProvenance: { riskLevel: 'gateway_derived' }`.
+
+Without `trustedContext`, an owner tier or `requireProvenance`, the agent's claim is still all the rules see —
+this closes hiding and garbling; those three close understating.
+
+**0.9.0 — a lost claim response no longer strands the hold, and a refused claim can be looked up.**
+- Every claim now carries a fresh, unguessable `Idempotency-Key`, and a claim whose response never arrives
+  (dropped connection, a 5xx) is **retried once with the same key**. If the first attempt had actually landed,
+  the issuer recognises the retry as yours and returns your original grant (`claimAuthorization()` reports
+  `replayed: true`) instead of refusing, so you can go on to execute. Before this, a lost response left the
+  hold claimed with nobody executing it, committed to the cap until reconciled. The key is per call and never
+  persisted: a restarted process, or a second request for the same authorization, gets no replay — a claim is
+  still single-use. A definite answer is never retried; the issuer's `EFFECT_TRANSITION_CONTENDED` (an
+  overlapping attempt of yours is mid-claim) is retried, since it is not a refusal.
+- A second claim of the same authorization is now refused with the stable code
+  **`AUTHORIZATION_ALREADY_CLAIMED`** whatever became of the first (it used to be
+  `INVALID_EFFECT_TRANSITION` or `EFFECT_TRANSITION_CONTENDED` depending on timing).
+- New `lookupOutcome({ authorizationId })` — what became of it? Returns `outcome`
+  (`not_started | expired | in_flight | settled | not_executed | unknown | reversing | reversed |
+  reversal_failed`) and two safety bits: `nothingExecuted` (nothing has run *so far*) and **`retrySafe`**
+  (nothing can run *later* either — true only for `expired` and `not_executed`). Re-authorize and retry only on
+  `retrySafe`. A `not_started` hold is `nothingExecuted` but **not** `retrySafe`: it can still be claimed until
+  its window closes, so a request queued behind a slow gateway could run it while your retry runs too — void
+  it first, then read `not_executed`. Use it after an `AUTHORIZATION_ALREADY_CLAIMED`, and never retry an
+  `unknown` or `in_flight` outcome blindly.
+- The idempotency key must stay secret from the agent (128 bits of randomness; the issuer refuses one under 32
+  characters or containing the authorization id). Never use the authorization id as a *claim* key — it is the
+  one thing the agent knows; it is only the right key to give an *upstream* to de-duplicate on.
+- The authorization id is the effect's natural idempotency key: pass `decision.authorizationId` to an
+  upstream that de-duplicates, and the effect is exactly-once even if you ever run the same call twice.
+  (`@metamynd/agentsafe-http-gateway` 0.9.0 does this for you.) Needs an issuer that understands
+  `Idempotency-Key` (MAGP §8.7.7); an older issuer ignores it and behaves as before.
+
+**0.8.0 — a Service can prove who it is.** A claim token is a bearer secret: it proves "I made the claim",
+not who you are. Give the guard a signing identity and it signs the claim and every settlement call
+(capture / release / mark-unknown) instead:
+
+```js
+const guard = createMcpGuard({
+  serviceDid: 'did:hedera:testnet:…',   // did:key or did:hedera; the key must be the one the DID commits to
+  serviceKey: privateKeyHex,            // or keyProvider: a signing-capable provider
+  issuerApi, requireAuthorization: true,
+});
+```
+
+The issuer records `svc:<did>` as the claimer and only that identity can lower or void the hold; no
+claim token is issued, so nothing can leak. The signature covers the action, the authorization id and
+the amount/reason fields, plus a one-time nonce and timestamp, so a captured call can't be replayed or
+edited. A `serviceDid` with no key (or a non-DID label) keeps the 0.7.0 token behaviour. Limits, stated
+plainly: the issuer verifies the key controls the DID, not that the DID is one you trust — see spec
+§8.7.6. The `daemon` key provider does not sign service messages yet.
+
+**0.7.0 — the claim token is relayed, and a Service can close the hold it claimed.** The issuer now
+treats a *claimed* hold as a commitment: it stays against the mandate's cap until it is settled (it no
+longer lapses with the 15-minute hold TTL), and once claimed it can be settled *below* its amount, or
+voided, only with the **claim token** returned by that hold's successful claim. Without that, an agent
+could wait for a Service to execute and then capture `$0` (or void) its own hold to get the budget back
+— 26 × $250 executed against a $5,000 cap that way. This package used to discard the token, so a Service
+could neither settle below the hold nor release one after an upstream failure. Now:
+
+- `verifyRequest()` / `guardIncomingTool()` return the token as `decision.claimToken` (and
+  `decision.authorizationId`) on a claimed permit. They are **non-enumerable**, so an echoed,
+  logged, spread or `JSON.stringify`-ed verdict does not carry the token to the calling agent —
+  the one party that must not have it. Keep it server-side.
+- New guard methods, all best-effort and non-throwing (they return `{ ok, reasonCode }`):
+  `captureAuthorization({ authorizationId, claimToken, amountCharged, bookingRef?, settlementTxHash? })`,
+  `releaseAuthorization({ authorizationId, claimToken, reason? })`, and
+  `markAuthorizationUnknown({ authorizationId, reason? })`.
+- `guardIncomingTool(action, handler, { settle: true })` settles a handler that returns (at the
+  authorized amount) and parks one that throws as **UNKNOWN** — it never *releases* on a throw, because a
+  throw does not prove nothing was executed. Off by default: an existing embed is unchanged.
+- **Release only what provably did not happen.** `releaseAuthorization` returns the budget. Use it when
+  the upstream cleanly refused; use `markAuthorizationUnknown` for a timeout, a 5xx or a dropped
+  connection, which keeps the spend committed and hands it to reconciliation. Failing to settle can only
+  over-count spend, never under-count it.
+
 ### Replay, cumulative spend, rate limits, breakers, spend anomalies (`requireAuthorization`)
 
 Re-evaluating policy per request (above) proves the request is well-formed and in-policy — it

package/agentsafe-mcp-guard.mjs

@@ -12,11 +12,28 @@
 // Dependencies are the two generated, zero-external-dependency bundles:
 //   policy-core.mjs (deterministic evaluator) and magp-did.mjs (key-in-DID verify).
 import crypto from 'node:crypto';
-import { evaluate, buildAuthMessage, applySignedLast, operatingModeGate } from './policy-core.mjs';
+import { evaluate, buildAuthMessage, applySignedLast, operatingModeGate, buildRuleContext, riskFloorFor, maxRisk, normalizeRiskLevel } from './policy-core.mjs';
 import { verifyDidSignature } from './magp-did.mjs';
 import { buildPaymentRequirements, checkSettlementBinding } from './x402.mjs';
 import { verifyBundle } from './magp-policy.mjs';
 import { resolveKeyProvider } from './key-providers.mjs';
+import { PAYLOAD_DIGEST_HEADER, buildPayloadBindingMessage, claimDigestField, isPayloadDigest, payloadDigestOf, toWireJson } from './payload-binding.mjs';
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * A `trustedContext` this Service configured must be a real object, and any `riskLevel` in it must be a real
+ * level. One that is not (a lookup that missed and returned undefined, a typo, a junk value) means the deriver is
+ * BROKEN — and the safe reading of a broken deriver is a refused call, never "carry on with the agent's word",
+ * which is exactly what the deriver was there to avoid. `undefined` itself means "not configured".
+ */
+function assertTrustedContext(tc, where) {
+  if (tc === undefined) return;
+  if (tc === null || typeof tc !== 'object' || Array.isArray(tc)) throw new Error(`trustedContext${where ? ` for ${where}` : ''} must be an object (got ${tc === null ? 'null' : Array.isArray(tc) ? 'an array' : typeof tc})`);
+  if (Object.prototype.hasOwnProperty.call(tc, 'riskLevel') && normalizeRiskLevel(tc.riskLevel) === null) {
+    throw new Error(`trustedContext${where ? ` for ${where}` : ''}.riskLevel is not one of low|medium|high|critical`);
+  }
+}
 
 /** Freshness window for signed requests and handshake nonces (spec §7.7). How far `issuedAt`
  *  may be BEHIND server time — network/processing delay. */
@@ -115,26 +132,193 @@ export function createMcpGuard({ serviceDid, serviceKey, keyProvider: keyProvide
    * entirely) could be presented to unlock a completely different one — the same confused-deputy
    * shape payload binding closes at the request layer, recurring one layer deeper.
    */
-  async function claimAuthorization({ authorizationId } = {}) {
+  /**
+   * Headers that sign one settlement-surface call as THIS Service (`x-magp-service-*`), or `{}` when it
+   * cannot: no `serviceKey`/`keyProvider` that can sign arbitrary messages, or a `serviceDid` that is not
+   * self-certifying (only did:key and did:hedera embed the verification key, so the issuer needs no
+   * registry to check them). The signed message is domain-separated from every other MAGP signature and
+   * binds the action, the authorization id and the call's own values:
+   *
+   *   MAGP-SERVICE-v1 | action | authorizationId | ...fields | nonce | issuedAt   (each field "\" and "|" escaped)
+   *
+   * An authenticated claim records this Service's DID on the effect chain; from then on only this identity
+   * may settle the hold below its amount, void it, or mark it unknown, and no bearer token is issued.
+   */
+  async function serviceAuthHeaders(action, authorizationId, fields = []) {
+    if (!serviceDid || !/^did:(key|hedera):/.test(serviceDid)) return {};
+    if (!keyProvider || typeof keyProvider.signServiceMessage !== 'function') return {};
+    const escape = (v) => String(v).replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+    const nonce = crypto.randomUUID();
+    const issuedAt = new Date().toISOString();
+    const message = ['MAGP-SERVICE-v1', action, authorizationId, ...fields, nonce, issuedAt].map(escape).join('|');
+    const signature = await keyProvider.signServiceMessage(message);
+    return { 'x-magp-service-did': serviceDid, 'x-magp-service-nonce': nonce, 'x-magp-service-issued-at': issuedAt, 'x-magp-service-signature': signature };
+  }
+
+  /**
+   * Claim the authorization, retrying ONCE when the answer is lost.
+   *
+   * A claim whose response never arrives (dropped connection, a 5xx from a proxy in front of the issuer) is
+   * ambiguous: it may have landed. Without more, this Service could not tell "my claim landed" from "someone
+   * else claimed", would refuse, and the hold would sit claimed — committed to the cap — with nobody executing
+   * it. So every claim CALL carries a fresh unguessable `Idempotency-Key`, reused only for the retry of that
+   * same call: the issuer recognises the retry as this claimant's own and returns the original grant
+   * (`replayed: true`) instead of refusing. The key is per call and never persisted, so a restarted process, or a
+   * later request for the same authorization, gets no replay — a claim is still single-use.
+   *
+   * Only an AMBIGUOUS failure is retried (no response, a 5xx, or the issuer's retryable
+   * EFFECT_TRANSITION_CONTENDED). A definite answer, including AUTHORIZATION_ALREADY_CLAIMED, is final and is
+   * returned as it is.
+   */
+  async function claimAuthorization({ authorizationId, payloadDigest } = {}) {
     if (!authorizationId) return { claimed: false, reasonCode: 'AUTHORIZATION_REQUIRED' };
     if (!base) throw new Error('issuerApi is required to claim an authorization');
+    if (payloadDigest !== undefined && !isPayloadDigest(payloadDigest)) return { claimed: false, reasonCode: 'PAYLOAD_DIGEST_INVALID' };
+    const idempotencyKey = crypto.randomUUID().replace(/-/g, '');
+    const attempts = 2;
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+      try {
+        // Re-signed per attempt (a fresh nonce; the signature also covers the key, so it cannot be swapped or stripped).
+        // `payloadDigest` — the digest of exactly what THIS Service is about to execute — is one more signed field and rides
+        // as a header: the issuer compares it with the digest the AGENT signed for this authorization and refuses the claim
+        // (leaving the hold unclaimed) on any difference. Payload binding, spec 8.3.9 / 8.7.11.
+        const auth = await serviceAuthHeaders('claim', authorizationId, [idempotencyKey, ...(payloadDigest ? [claimDigestField(payloadDigest)] : [])]);
+        const res = await fetch(`${base}/policy/mandate/authorize/${encodeURIComponent(authorizationId)}/effect/dispatching`, {
+          method: 'POST',
+          headers: { ...auth, 'idempotency-key': idempotencyKey, ...(payloadDigest ? { [PAYLOAD_DIGEST_HEADER]: payloadDigest } : {}) },
+        });
+        const body = await res.json().catch(() => null);
+        // Ambiguous, so worth one retry with the same key: a 5xx, or EFFECT_TRANSITION_CONTENDED — the issuer's
+        // "an overlapping attempt of yours is mid-claim, ask again", which is not a refusal.
+        const ambiguous = res.status >= 500 || (res.status === 409 && body?.message === 'EFFECT_TRANSITION_CONTENDED');
+        if (ambiguous && attempt < attempts) { lastError = `HTTP ${res.status}`; await sleep(150); continue; }
+        if (!res.ok) return { claimed: false, reasonCode: body?.message ?? body?.data?.reasonCode ?? `AUTHORIZATION_CLAIM_HTTP_${res.status}` };
+        return {
+          claimed: true,
+          agentDid: body?.data?.agentDid,
+          action: body?.data?.action,
+          amount: body?.data?.amount,
+          currency: body?.data?.currency,
+          merchant: body?.data?.merchant,
+          // The digest the agent signed for this authorization (null = unbound); absent from an issuer that predates it.
+          payloadDigest: body?.data?.payloadDigest,
+          // The settlement token the issuer hands ONLY the caller whose claim succeeded. Once a hold is
+          // claimed it can be settled below its amount, or voided, only with this token — so the Service
+          // that executes must keep it and present it (captureAuthorization / releaseAuthorization).
+          claimToken: body?.data?.claimToken,
+          // This claim was signed as this Service's own identity, so the issuer recorded it as the claimant.
+          counterpartyAuthenticated: 'x-magp-service-did' in auth,
+          // True when the issuer answered a RETRY with the grant of this call's own earlier attempt.
+          replayed: body?.data?.replayed === true,
+        };
+      } catch (err) {
+        lastError = String(err?.message ?? err);
+        if (attempt < attempts) { await sleep(150); continue; }
+      }
+    }
+    return { claimed: false, reasonCode: 'AUTHORIZATION_CLAIM_UNREACHABLE', error: lastError };
+  }
+
+  /**
+   * What became of an authorization? Public, keyed by the authorization id (no signature needed). Use it when a
+   * claim was refused with AUTHORIZATION_ALREADY_CLAIMED, or before deciding whether to retry anything:
+   *
+   *   `outcome`         not_started | expired | in_flight | settled | not_executed | unknown | reversing | reversed | reversal_failed
+   *   `nothingExecuted` nothing has executed SO FAR (not_started, expired, not_executed)
+   *   `retrySafe`       nothing can execute LATER either, so a fresh authorization cannot duplicate this one:
+   *                     true ONLY for expired and not_executed
+   *
+   * Retry only on `retrySafe`. `not_started` is nothingExecuted but NOT retrySafe: the hold can still be claimed
+   * until its window closes, so a request queued behind a slow gateway could run it too (void it first, then it
+   * reads not_executed). `unknown` and `in_flight` are neither — an ambiguous outcome must be reconciled, never
+   * retried blindly. Best-effort and non-throwing: `{ ok: false, reasonCode }` when the issuer cannot be asked.
+   */
+  async function lookupOutcome({ authorizationId } = {}) {
+    if (!authorizationId) return { ok: false, reasonCode: 'AUTHORIZATION_REQUIRED' };
+    if (!base) return { ok: false, reasonCode: 'ISSUER_API_REQUIRED' };
     try {
-      const res = await fetch(`${base}/policy/mandate/authorize/${encodeURIComponent(authorizationId)}/effect/dispatching`, { method: 'POST' });
+      const res = await fetch(`${base}/policy/mandate/authorize/${encodeURIComponent(authorizationId)}/effect`);
       const body = await res.json().catch(() => null);
-      if (!res.ok) return { claimed: false, reasonCode: body?.message ?? body?.data?.reasonCode ?? `AUTHORIZATION_CLAIM_HTTP_${res.status}` };
-      return {
-        claimed: true,
-        agentDid: body?.data?.agentDid,
-        action: body?.data?.action,
-        amount: body?.data?.amount,
-        currency: body?.data?.currency,
-        merchant: body?.data?.merchant,
-      };
+      if (!res.ok || !body?.data) return { ok: false, status: res.status, reasonCode: body?.message ?? `OUTCOME_HTTP_${res.status}` };
+      return { ok: true, ...body.data };
+    } catch (err) {
+      return { ok: false, reasonCode: 'ISSUER_UNREACHABLE', error: String(err?.message ?? err) };
+    }
+  }
+
+  /**
+   * Attach the claim to a PERMIT verdict as NON-ENUMERABLE properties. The verdict is routinely
+   * echoed onward (logged, put in a response, spread into another object), and the calling agent
+   * is exactly the party the claim token must be kept from: with it, the agent could void an
+   * executed hold or settle it for less. A non-enumerable property survives normal use
+   * (`decision.claimToken`) but not JSON.stringify or `{ ...decision }`.
+   */
+  function withClaim(verdict, authorizationId, claimToken, authenticated = false) {
+    if (!claimToken && !authenticated) return verdict;
+    const out = { ...verdict };
+    if (claimToken) Object.defineProperty(out, 'claimToken', { value: claimToken, enumerable: false });
+    // `true` when the claim was signed as this Service's own identity: there is then NO token, and the
+    // settlement helpers below authenticate each call by signing it instead.
+    if (authenticated) Object.defineProperty(out, 'counterpartyAuthenticated', { value: true, enumerable: false });
+    Object.defineProperty(out, 'authorizationId', { value: authorizationId, enumerable: false });
+    return out;
+  }
+
+  /** One best-effort call to the issuer's settlement surface. Never throws. */
+  async function issuerPost(path, body, extraHeaders = {}) {
+    if (!base) return { ok: false, reasonCode: 'ISSUER_API_REQUIRED' };
+    try {
+      const res = await fetch(`${base}${path}`, { method: 'POST', headers: { 'Content-Type': 'application/json', ...extraHeaders }, body: JSON.stringify(body ?? {}) });
+      const payload = await res.json().catch(() => null);
+      if (!res.ok) return { ok: false, status: res.status, reasonCode: payload?.message ?? payload?.data?.reasonCode ?? `ISSUER_HTTP_${res.status}` };
+      // void answers 200 with success:false when the hold was not voidable (e.g. already settled)
+      if (payload?.success === false) return { ok: false, status: res.status, reasonCode: payload?.data?.reasonCode ?? payload?.message ?? 'NOT_APPLIED', data: payload?.data ?? null };
+      return { ok: true, status: res.status, data: payload?.data ?? null };
     } catch (err) {
-      return { claimed: false, reasonCode: 'AUTHORIZATION_CLAIM_UNREACHABLE', error: String(err?.message ?? err) };
+      return { ok: false, reasonCode: 'ISSUER_UNREACHABLE', error: String(err?.message ?? err) };
     }
   }
 
+  /**
+   * Settle a claimed hold once the Service has actually executed. `claimToken` is the one the
+   * successful claim returned (`verdict.claimToken`); it is required to settle BELOW the authorized
+   * amount, and unnecessary at the full amount. Best-effort and non-throwing: a failure here never
+   * turns an executed call into an error, and a claimed hold stays committed to the mandate's cap
+   * either way, so failing to settle can only over-count spend, never under-count it.
+   */
+  async function captureAuthorization({ authorizationId, claimToken, amountCharged, bookingRef, settlementTxHash } = {}) {
+    if (!authorizationId) return { ok: false, reasonCode: 'AUTHORIZATION_REQUIRED' };
+    if (!Number.isFinite(Number(amountCharged))) return { ok: false, reasonCode: 'AMOUNT_CHARGED_REQUIRED' };
+    const amount = Number(amountCharged);
+    const auth = await serviceAuthHeaders('capture', authorizationId, [String(amount), bookingRef ?? '', settlementTxHash ?? '']);
+    return issuerPost(`/policy/mandate/authorize/${encodeURIComponent(authorizationId)}/capture`, { amountCharged: amount, bookingRef, settlementTxHash, claimToken }, auth);
+  }
+
+  /**
+   * Release a claimed hold whose effect provably did NOT happen (the upstream cleanly rejected it),
+   * returning its budget to the mandate. Requires the claim token: the issuer refuses to void a
+   * claimed hold for anyone else, because the agent could otherwise wait for this Service to
+   * execute and then void its own hold. Do NOT call this for an ambiguous outcome (a timeout, a 5xx,
+   * a dropped connection) — use markAuthorizationUnknown so the spend stays committed.
+   */
+  async function releaseAuthorization({ authorizationId, claimToken, reason } = {}) {
+    if (!authorizationId) return { ok: false, reasonCode: 'AUTHORIZATION_REQUIRED' };
+    const auth = await serviceAuthHeaders('void', authorizationId, [reason ?? '']);
+    return issuerPost(`/policy/mandate/authorize/${encodeURIComponent(authorizationId)}/void`, { reason, claimToken }, auth);
+  }
+
+  /**
+   * Report that the outcome of an executed-or-not call is unknown (response lost, 5xx, timeout).
+   * The effect moves to UNKNOWN, which keeps the spend committed and hands it to reconciliation
+   * instead of guessing in either direction.
+   */
+  async function markAuthorizationUnknown({ authorizationId, reason } = {}) {
+    if (!authorizationId) return { ok: false, reasonCode: 'AUTHORIZATION_REQUIRED' };
+    const auth = await serviceAuthHeaders('unknown', authorizationId, [reason ?? '']);
+    return issuerPost(`/policy/mandate/authorize/${encodeURIComponent(authorizationId)}/effect/unknown`, { reason }, auth);
+  }
+
   async function loadBundle(agentDid) {
     if (typeof fetchBundle === 'function') return fetchBundle(agentDid);
     if (!base) throw new Error('issuerApi (or fetchBundle) is required to load the policy bundle');
@@ -150,8 +334,15 @@ export function createMcpGuard({ serviceDid, serviceKey, keyProvider: keyProvide
     return body.data;
   }
 
-  /** Evaluate the agent's bundle against the request via policy-core (signed fields last). */
-  function verdictFromBundle(bundle, req) {
+  /**
+   * Evaluate the agent's bundle against the request via policy-core (signed fields last).
+   *
+   * `trustedContext` is context THIS SERVICE derived from the real request (never from the agent): it is applied
+   * over the agent's claim and labelled `gateway_derived`, so a rule can require it (`requireProvenance`) and a
+   * lie in the itinerary cannot outvote it. The mandate's own `riskTier` (in the signed bundle) is a risk floor
+   * under whatever the agent claims, exactly as at the issuer's gate (spec §6.4.3).
+   */
+  function verdictFromBundle(bundle, req, trustedContext) {
     const { agentDid, action, amount = 0, currency = 'USD', merchant = '', resource = null, itinerary = {}, cumulativeSpend = amount, now } = req;
     const mandates = bundle.mandates ?? [];
     const mandate = mandates.find((m) => m.action === action)?.document;
@@ -173,7 +364,12 @@ export function createMcpGuard({ serviceDid, serviceKey, keyProvider: keyProvide
       // cumulative-over Standards/SOP atom always sees currency as absent and fires closed
       // (SOP_SPEND_CAP on a genuinely in-cap request), and a resource-scope atom never runs
       // at all. Mirrors mandate.service.ts's ruleCtx (PR #588), the parity target for this.
-      context: applySignedLast(itinerary, { action, agentDid, amount, currency, merchant, resource }),
+      context: buildRuleContext({
+        unsigned: itinerary,
+        signed: { action, agentDid, amount, currency, merchant, resource },
+        gatewayDerived: trustedContext,
+        riskFloor: riskFloorFor(mandate, action),
+      }),
       mandateRequest: mandate
         ? {
             target: action,
@@ -201,10 +397,15 @@ export function createMcpGuard({ serviceDid, serviceKey, keyProvider: keyProvide
    * locally against the agent's issuer-hosted bundle. Fails CLOSED: any bad
    * signature, staleness, fetch error, or evaluation error returns a block.
    * @param {{agentDid,action,amount?,currency?,merchant?,resource?,itinerary?,nonce,issuedAt,signature}} signed
+   * @param {{ trustedContext?: Record<string, unknown> }} [options] `trustedContext`: context this Service derived
+   *   from the real request (e.g. `{ riskLevel: 'high' }` for a wire-transfer route) — NEVER anything the agent sent.
+   *   It outranks the agent's claim and is labelled `gateway_derived`; a risk it states can be raised by the agent
+   *   but not lowered. Without it the rules see the agent's own claim, as before.
    * @returns {Promise<{decision:'allow'|'observe'|'block'|'escalate'|'suspend'|'quarantine',reasonCode:string|null}>}
    */
-  async function verifyRequest(signed = {}) {
+  async function verifyRequest(signed = {}, { trustedContext, payloadDigest, requirePayloadBinding } = {}) {
     try {
+      assertTrustedContext(trustedContext); // a broken deriver is a refused request (GUARD_ERROR), never a quiet downgrade
       const { agentDid, action, amount = 0, currency = 'USD', merchant = '', resource = null, nonce, issuedAt, signature } = signed;
       if (!agentDid || !action || !nonce || !issuedAt || !signature) {
         return { decision: 'block', reasonCode: 'MALFORMED_REQUEST' };
@@ -216,6 +417,28 @@ export function createMcpGuard({ serviceDid, serviceKey, keyProvider: keyProvide
       if (!verifyDidSignature(agentDid, message, signature)) {
         return { decision: 'block', reasonCode: 'SIGNATURE_INVALID' };
       }
+      // 1b. Payload binding (spec 8.3.9). A digest with no valid signature over it binds nothing — refuse it. When THIS Service
+      // states the digest of what it is about to execute (`payloadDigest`), it must be the one the agent signed: a mismatch is
+      // refused here, before any claim, so it costs no round trip. (The ISSUER re-checks the same thing against the digest it
+      // stored at authorize time when the claim is made — this early check is only cheaper, never the authority.)
+      const signedDigest = signed.payloadDigest;
+      if (signedDigest !== undefined || signed.payloadSignature !== undefined) {
+        const bound = isPayloadDigest(signedDigest) && typeof signed.payloadSignature === 'string'
+          && verifyDidSignature(agentDid, buildPayloadBindingMessage({ agentDid, action, nonce, issuedAt, payloadDigest: signedDigest }), signed.payloadSignature);
+        if (!bound) return { decision: 'block', reasonCode: 'PAYLOAD_BINDING_INVALID' };
+      }
+      if (payloadDigest !== undefined) {
+        if (!isPayloadDigest(payloadDigest)) return { decision: 'block', reasonCode: 'PAYLOAD_DIGEST_INVALID' };
+        if (signedDigest === undefined) {
+          // The executor has a payload; the agent bound none. Refuse only when binding is REQUIRED — otherwise this is an
+          // unbound request, exactly as before payload binding existed (and it is not claimed with a digest: see below).
+          if (requirePayloadBinding) return { decision: 'block', reasonCode: 'PAYLOAD_BINDING_REQUIRED' };
+        } else if (signedDigest !== payloadDigest) {
+          return { decision: 'block', reasonCode: 'PAYLOAD_NOT_BOUND' };
+        }
+      } else if (requirePayloadBinding && signedDigest === undefined) {
+        return { decision: 'block', reasonCode: 'PAYLOAD_BINDING_REQUIRED' };
+      }
       // 2. Freshness. (Single-use nonce consumption stays the gate's job by default — a Service
       //    re-check is verification, not a second authorization. requireAuthorization below is
       //    the opt-in exception: it DOES give the Service its own single-use claim.)
@@ -243,7 +466,11 @@ export function createMcpGuard({ serviceDid, serviceKey, keyProvider: keyProvide
       // as a non-enumerable sibling. READ_ONLY refuses a value-bearing action up-front;
       // SUPERVISED/RESTRICTED only ESCALATE, applied to the verdict below so a rule block
       // still outranks the floor (most-restrictive-wins, mirroring the gate).
-      const modeGate = operatingModeGate(bundle?.__operatingMode?.mode, { amount, riskLevel: signed?.itinerary?.riskLevel });
+      // The risk it judges is the EFFECTIVE one — the owner's tier (in the signed bundle) and this Service's own
+      // derivation are floors under the agent's claim, so "low" cannot dodge the SUPERVISED high-risk escalation.
+      const mandateForRisk = (bundle?.mandates ?? []).find((m) => m.action === action)?.document;
+      const effectiveRisk = maxRisk(riskFloorFor(mandateForRisk, action), normalizeRiskLevel(trustedContext?.riskLevel), normalizeRiskLevel(signed?.itinerary?.riskLevel)) ?? undefined;
+      const modeGate = operatingModeGate(bundle?.__operatingMode?.mode, { amount, riskLevel: effectiveRisk });
       if (modeGate.decision === 'block') return { decision: 'block', reasonCode: modeGate.reasonCode };
       // 3b. Signed-bundle verification + risk-tiered fail-closed (Phase F, §5.3.2/§5.3.3). When a
       // policy key is configured, a value-bearing action (amount > 0) MUST fail closed on an
@@ -253,7 +480,7 @@ export function createMcpGuard({ serviceDid, serviceKey, keyProvider: keyProvide
         const v = verifyBundle(bundle, { publicKey: policyPublicKey, valueBearing: Number(amount) > 0 });
         if (!v.ok) return { decision: 'block', reasonCode: v.reasonCode };
       }
-      const verdict = verdictFromBundle(bundle, { ...signed, itinerary: signed.itinerary ?? {} });
+      const verdict = verdictFromBundle(bundle, { ...signed, itinerary: signed.itinerary ?? {} }, trustedContext);
       // Mode ESCALATE floor lifts an otherwise-PERMIT (allow or observe) to human review
       // (escalate outranks observe, so a flag never masks it) — mirrors the backend gate.
       const final = (verdict.decision === 'allow' || verdict.decision === 'observe') && modeGate.decision === 'escalate'
@@ -263,9 +490,19 @@ export function createMcpGuard({ serviceDid, serviceKey, keyProvider: keyProvide
       // stop REPLAY or CUMULATIVE SPEND past the mandate total — both are the stateful issuer
       // gate's job. Only claim on an actual PERMIT: escalate/block/suspend/quarantine execute
       // nothing, so there is nothing to protect and no reason to spend the hold's single use.
+      let claimToken; let claimAuthenticated = false;
       if (requireAuthorization && (final.decision === 'allow' || final.decision === 'observe')) {
-        const claim = await claimAuthorization({ authorizationId: signed.authorizationId });
+        // The claim states the digest of what THIS Service is about to execute — only when the agent bound one (a digest for
+        // an unbound authorization is refused by the issuer: this Service would be asserting a binding that does not exist).
+        const claimDigest = payloadDigest !== undefined && signedDigest !== undefined ? payloadDigest : undefined;
+        const claim = await claimAuthorization({ authorizationId: signed.authorizationId, payloadDigest: claimDigest });
+        claimToken = claim.claimToken; claimAuthenticated = claim.counterpartyAuthenticated === true;
         if (!claim.claimed) return { decision: 'block', reasonCode: claim.reasonCode };
+        // The grant states the digest the hold is bound to (null = unbound), so it must be the one this claim stated. The issuer
+        // already refused a claim whose digest differed; this catches an issuer that did NOT compare — one that predates payload
+        // binding ignores the header and its grant carries no digest at all, which is "not enforced", never "fine". Only
+        // reachable when the agent bound a payload, a flow an issuer that predates binding cannot honour anyway.
+        if ((claim.payloadDigest ?? null) !== (claimDigest ?? null)) return { decision: 'block', reasonCode: 'PAYLOAD_DIGEST_MISMATCH' };
         // The claim alone only proves SOME real, unclaimed authorization exists — it must also
         // be FOR this agent and these exact values, or a cheap legitimate hold's id could be
         // presented to unlock a completely different, more expensive execution. Each check is
@@ -288,7 +525,9 @@ export function createMcpGuard({ serviceDid, serviceKey, keyProvider: keyProvide
         if (claim.currency !== undefined && claim.currency !== currency) return { decision: 'block', reasonCode: 'AUTHORIZATION_CURRENCY_MISMATCH' };
         if (claim.merchant !== undefined && claim.merchant !== merchant) return { decision: 'block', reasonCode: 'AUTHORIZATION_MERCHANT_MISMATCH' };
       }
-      return final;
+      // On a claimed permit the Service that executes needs the claim token to settle or release the
+      // hold afterwards (non-enumerable — see withClaim).
+      return withClaim(final, signed.authorizationId, claimToken, claimAuthenticated);
     } catch (err) {
       return { decision: 'block', reasonCode: 'GUARD_ERROR', error: String(err?.message ?? err) };
     }
@@ -299,8 +538,38 @@ export function createMcpGuard({ serviceDid, serviceKey, keyProvider: keyProvide
    * agent's signed request must be passed as the first argument. Throws
    * GovernanceBlocked on any non-allow decision.
    */
-  function guardIncomingTool(action, handler) {
+  function guardIncomingTool(action, handler, { settle: settleClaim = false, trustedContext, bindPayload = false, requirePayloadBinding = false } = {}) {
+    // `requirePayloadBinding` only checks that the AGENT bound something; the comparison with what this tool executes needs a
+    // digest of it. Without `bindPayload` there is nothing to compare, so the option would give assurance it does not provide.
+    if (requirePayloadBinding && !bindPayload) {
+      throw new Error(`guardIncomingTool("${action}"): requirePayloadBinding needs bindPayload — without a digest of what the tool executes there is nothing to compare the binding with`);
+    }
     return async (signed, ...rest) => {
+      // Payload binding (spec 8.3.9): the digest of what THIS call is about to execute. `bindPayload: true` digests the tool's
+      // single argument after the signed request and hands the handler that same JSON snapshot, so what is digested is what
+      // runs (a `toJSON()` or a later mutation cannot make them differ); a tool with any other shape passes a function that
+      // returns what to digest, and then owns making the handler execute exactly that. Computed BEFORE the request is verified
+      // so a payload JSON cannot carry refuses the call rather than skipping the check.
+      let executorDigest;
+      if (bindPayload) {
+        try {
+          let payload;
+          if (typeof bindPayload === 'function') {
+            payload = await bindPayload(signed, ...rest);
+          } else {
+            if (rest.length !== 1) throw new Error(`bindPayload: true digests exactly one argument after the signed request, got ${rest.length}; pass a function to say what to digest`);
+            payload = rest[0];
+          }
+          const wire = toWireJson(payload);
+          executorDigest = payloadDigestOf(wire);
+          if (typeof bindPayload !== 'function') rest = [wire];
+        } catch (err) {
+          const e = new Error(`MCP guard BLOCK "${action}": PAYLOAD_NOT_CANONICALIZABLE`);
+          e.name = 'GovernanceBlocked';
+          e.governance = { decision: 'block', reasonCode: 'PAYLOAD_NOT_CANONICALIZABLE', error: String(err?.message ?? err) };
+          throw e;
+        }
+      }
       // The WRAPPED TOOL's own `action` is authoritative — never `signed?.action` (the caller's
       // own claim). A Service that wraps more than one tool with ONE guard instance (the normal
       // MCP-server shape: many tools, one guard) previously let a genuinely-valid signature for
@@ -311,7 +580,14 @@ export function createMcpGuard({ serviceDid, serviceKey, keyProvider: keyProvide
       // this guard (e.g. a wire transfer) and have it execute under that unrelated verification.
       // Mirrors gateway.mjs's `route.action ?? signed.action` — "the route pins the action ...
       // the client can't pick it" — for exactly the same reason, one layer down at the tool call.
-      const decision = await verifyRequest({ ...signed, action });
+      // `trustedContext` (an object, or `(signed, ...rest) => object`) is what THIS tool's author derived from
+      // the real call — the risk of wiring money vs reading a report — never the agent's claim. A throwing
+      // deriver fails the call closed (a governance error, not a silent downgrade to the agent's word).
+      const derived = typeof trustedContext === 'function' ? await trustedContext(signed, ...rest) : trustedContext;
+      // Configured but yielding nothing usable (a function that returned undefined) is a broken deriver, not "no
+      // trusted context": refuse rather than fall back to the agent's word. `undefined` option = not configured.
+      if (trustedContext !== undefined) assertTrustedContext(derived === undefined ? null : derived, `"${action}"`);
+      const decision = await verifyRequest({ ...signed, action }, { trustedContext: derived, payloadDigest: executorDigest, requirePayloadBinding });
       // allow/observe both PERMIT the tool call; observe is permit-but-flag (SAFR §11).
       if (decision.decision !== 'allow' && decision.decision !== 'observe') {
         const err = new Error(`MCP guard ${decision.decision.toUpperCase()} "${action}": ${decision.reasonCode}`);
@@ -358,6 +634,21 @@ export function createMcpGuard({ serviceDid, serviceKey, keyProvider: keyProvide
       if (!requireAuthorization && Number(signed?.amount) > 0) {
         console.warn(`[mcp-guard] "${action}" (amount=${signed.amount}) permitted in trustless mode — rate-limit, circuit-breaker, replay, cumulative-spend, and spend-anomaly floors are stateful and were NOT re-verified against live issuer state. Set requireAuthorization:true for custodial/value-bearing surfaces.`);
       }
+      // Opt-in settlement of a claimed hold (`requireAuthorization` + `{ settle: true }`): a handler
+      // that returns is settled at the authorized amount; one that throws is reported UNKNOWN, not
+      // released — a thrown error does not prove nothing was executed, and UNKNOWN keeps the spend
+      // committed until reconciliation decides. Off by default so existing embeds are unchanged.
+      if (settleClaim && (decision.claimToken || decision.counterpartyAuthenticated)) {
+        let result;
+        try {
+          result = await handler(signed, ...rest);
+        } catch (err) {
+          await markAuthorizationUnknown({ authorizationId: decision.authorizationId, reason: 'HANDLER_THREW' });
+          throw err;
+        }
+        await captureAuthorization({ authorizationId: decision.authorizationId, claimToken: decision.claimToken, amountCharged: Number(signed?.amount) });
+        return result;
+      }
       return handler(signed, ...rest);
     };
   }
@@ -418,7 +709,7 @@ export function createMcpGuard({ serviceDid, serviceKey, keyProvider: keyProvide
     return { settled: true, txHash: result.txHash, reasonCode: 'SETTLED' };
   }
 
-  return { handshakeChallenge, handshakeVerify, verifyRequest, guardIncomingTool, requirePayment, settle, claimAuthorization, serviceDid };
+  return { handshakeChallenge, handshakeVerify, verifyRequest, guardIncomingTool, requirePayment, settle, claimAuthorization, lookupOutcome, captureAuthorization, releaseAuthorization, markAuthorizationUnknown, serviceDid };
 }
 
 /**

package/key-providers.mjs

@@ -12,6 +12,14 @@ export function createStaticKeyProvider(serviceKeyHex) {
     async signHandshakeNonce(nonce) {
       return crypto.sign(null, Buffer.from(nonce, 'utf8'), privateKey).toString('hex');
     },
+    /**
+     * Sign one settlement-surface call (claim / capture / void / unknown) as this Service's own identity —
+     * the issuer verifies it against the key embedded in `serviceDid`. The daemon provider does not offer
+     * this yet, so a daemon-backed Service keeps making anonymous (token-bearing) calls.
+     */
+    async signServiceMessage(message) {
+      return crypto.sign(null, Buffer.from(message, 'utf8'), privateKey).toString('hex');
+    },
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-mcp-guard",
-  "version": "0.6.2",
+  "version": "0.11.0",
   "description": "Zero-dependency trustless governance for the SERVICE side. An MCP server or API re-verifies a calling agent's signed request against the agent's own published policy \u00e2\u20ac\u201d so an agent that ignores its own guard still cannot make your service act.",
   "type": "module",
   "main": "./agentsafe-mcp-guard.mjs",
@@ -18,13 +18,14 @@
     "key-providers.mjs",
     "magp-policy.mjs",
     "magp-did.mjs",
+    "payload-binding.mjs",
     "policy-core.mjs",
     "x402.mjs",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "test": "node mcp-guard.smoke.mjs && node pay.smoke.mjs && node decision-token.smoke.mjs && node claim-authorization.smoke.mjs && node guard-incoming-tool.smoke.mjs"
+    "test": "node mcp-guard.smoke.mjs && node pay.smoke.mjs && node decision-token.smoke.mjs && node claim-authorization.smoke.mjs && node claim-token.smoke.mjs && node payload-binding.smoke.mjs && node guard-incoming-tool.smoke.mjs"
   },
   "engines": {
     "node": ">=18"

package/payload-binding.mjs

@@ -0,0 +1,110 @@
+// GENERATED from backend/src/features/magp/payload-binding.ts - do not edit. Regenerate: npm run build:mcp-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:mcp-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
 };