@agentsbloom/sdk 0.4.0 → 0.5.0

package/lib/ap2.js

@@ -1,537 +1,1017 @@
-import crypto from 'crypto';
-import { createReplayCache } from './shared-store.js';
-
-/**
- * Hardened AP2 (Agent Payments Protocol) mandate verification.
- *
- * This module replaces the previous "valid but unverified" bypass in
- * packages/sdk/index.js's verifyAP2Mandates: a mandate that could not be
- * cryptographically verified was still returned as `{ valid: true,
- * verified: false }` and the checkout gate only checked `!ap2MandateResult`
- * / budget, never `.verified`. That meant any attacker could hand-craft an
- * unsigned (or badly-signed) mandate claiming an arbitrary maxBudget and
- * have it treated as authorization to check out.
- *
- * The rules enforced here:
- *   1. If no mandate header is present at all, AP2 simply isn't in use for
- *      this request - that's still `{ valid: true, verified: false }` so
- *      non-AP2 traffic (REST/ACP) is never blocked by AP2 logic.
- *   2. If a mandate header IS present, it MUST verify successfully or the
- *      request is rejected outright (`valid: false`). There is no
- *      "valid but unverified" middle ground once a mandate is presented.
- *   3. Signature verification uses either (a) a merchant-configured
- *      trusted public key (out-of-band trust, any of ES256/384/512,
- *      RS256/384/512, EdDSA), or (b) self-certifying did:key issuers
- *      (Ed25519/EdDSA only - the public key IS the issuer identifier, so
- *      no pre-registration is needed for arbitrary agents/wallets).
- *   4. Mandates must carry a unique `jti` and are checked against a
- *      bounded in-memory replay cache - a captured valid mandate cannot be
- *      replayed to trigger a second charge.
- *   5. `aud` is checked against the caller-supplied expected audience
- *      (the merchant's own base URL) when one is provided, so a mandate
- *      signed for store A cannot be replayed against store B.
- *   6. Mandate lifetime (`exp - iat`) is bounded, so a "valid forever"
- *      mandate cannot be crafted even with a real signature.
- */
-
-// --- base58btc (Bitcoin alphabet) - no external dependency ---
-const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
-const BASE58_MAP = new Map(BASE58_ALPHABET.split('').map((c, i) => [c, i]));
-
-/** @param {Buffer} buffer @returns {string} */
-function base58Encode(buffer) {
-  if (buffer.length === 0) return '';
-  let value = 0n;
-  for (const byte of buffer) value = value * 256n + BigInt(byte);
-
-  let encoded = '';
-  while (value > 0n) {
-    const remainder = value % 58n;
-    value = value / 58n;
-    encoded = BASE58_ALPHABET[Number(remainder)] + encoded;
-  }
-
-  let leadingZeros = 0;
-  for (const byte of buffer) {
-    if (byte === 0) leadingZeros++;
-    else break;
-  }
-  return BASE58_ALPHABET[0].repeat(leadingZeros) + encoded;
-}
-
-/** @param {string} str @returns {Buffer} */
-function base58Decode(str) {
-  if (str.length === 0) return Buffer.alloc(0);
-  let value = 0n;
-  for (const char of str) {
-    const digit = BASE58_MAP.get(char);
-    if (digit === undefined) throw new Error(`Invalid base58 character: ${char}`);
-    value = value * 58n + BigInt(digit);
-  }
-
-  const bytes = [];
-  while (value > 0n) {
-    bytes.unshift(Number(value % 256n));
-    value = value / 256n;
-  }
-
-  let leadingZeros = 0;
-  for (const char of str) {
-    if (char === BASE58_ALPHABET[0]) leadingZeros++;
-    else break;
-  }
-  return Buffer.concat([Buffer.alloc(leadingZeros, 0), Buffer.from(bytes)]);
-}
-
-// Ed25519 multicodec (0xed) varint-encoded as [0xed, 0x01], per the did:key
-// Ed25519 method spec (multicodec ed25519-pub prefix).
-const ED25519_MULTICODEC_PREFIX = Buffer.from([0xed, 0x01]);
-
-// Fixed 12-byte SPKI DER prefix for Ed25519 public keys (RFC 8410) - Ed25519
-// has no algorithm parameters, so the DER encoding of any Ed25519 SPKI key
-// is always this fixed prefix followed by the raw 32-byte public key.
-const ED25519_SPKI_DER_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
-
-/**
- * Derives a did:key identifier from an Ed25519 public key.
- * @param {crypto.KeyObject|Buffer} publicKey - a Node KeyObject or raw 32-byte public key
- * @returns {string} e.g. "did:key:z6Mk..."
- */
-export function didKeyFromEd25519PublicKey(publicKey) {
-  const rawKey = Buffer.isBuffer(publicKey)
-    ? publicKey
-    : publicKey.export({ type: 'spki', format: 'der' }).subarray(-32);
-  const prefixed = Buffer.concat([ED25519_MULTICODEC_PREFIX, rawKey]);
-  return `did:key:z${base58Encode(prefixed)}`;
-}
-
-/**
- * Derives an Ed25519 public KeyObject from a did:key identifier.
- * @param {string} didKey - e.g. "did:key:z6Mk..."
- * @returns {crypto.KeyObject|null} null if the identifier is not a
- *   well-formed Ed25519 did:key (caller treats this as "cannot verify")
- */
-export function ed25519PublicKeyFromDidKey(didKey) {
-  if (typeof didKey !== 'string' || !didKey.startsWith('did:key:z')) return null;
-  try {
-    const multibase = didKey.slice('did:key:'.length);
-    const decoded = base58Decode(multibase.slice(1)); // drop leading 'z' multibase prefix
-    if (
-      decoded.length !== ED25519_MULTICODEC_PREFIX.length + 32 ||
-      !decoded.subarray(0, 2).equals(ED25519_MULTICODEC_PREFIX)
-    ) {
-      return null;
-    }
-    const rawKey = decoded.subarray(2);
-    const der = Buffer.concat([ED25519_SPKI_DER_PREFIX, rawKey]);
-    return crypto.createPublicKey({ key: der, format: 'der', type: 'spki' });
-  } catch {
-    return null;
-  }
-}
-
-// --- Replay protection ---
-// Consumed mandate jtis. Local Map by default; when an Upstash Redis REST
-// endpoint is configured (see lib/shared-store.js) the cache becomes
-// cluster-wide so a mandate consumed on one instance cannot replay against
-// another. `has()` is maybe-async (boolean locally, Promise when shared) -
-// callers await it.
-const seenMandateJtis = createReplayCache('agentsbloom:ap2:jti', 50_000);
-
-/** Clears all replay-tracking state. Exposed for tests and shutdown(). */
-export function resetAp2ReplayCache() {
-  seenMandateJtis.clear();
-}
-
-/** No-op retained for shutdown() compatibility; eviction is amortized. */
-export function stopAp2ReplayCleanup() {}
-
-/**
- * Normalizes an audience/merchantScope value for comparison. Clients that
- * build URLs with `new URL(...).href` (the standard practice - the
- * Test Console's dynamic target validation does exactly this) produce a
- * trailing slash ("https://store.example.com/") while merchants configure
- * the same audience without one. Comparing raw strings rejected those
- * perfectly valid mandates, so both sides are normalized: URL-parsed when
- * possible (lowercased host, trailing slashes stripped), plain
- * slash-stripped otherwise (non-URL audience strings keep old behavior).
- *
- * @param {string} value
- * @returns {string}
- */
-export function normalizeAudience(value) {
-  if (typeof value !== 'string') return String(value ?? '');
-  const trimmed = value.trim();
-  if (trimmed === '') return trimmed;
-  try {
-    const url = new URL(trimmed);
-    const path = url.pathname.replace(/\/+$/, '');
-    return `${url.protocol}//${url.host}${path}`;
-  } catch {
-    return trimmed.replace(/\/+$/, '');
-  }
-}
-
-/** Audience comparison that tolerates URL-normalization differences. */
-function audienceMatches(claimed, expected) {
-  return normalizeAudience(claimed) === normalizeAudience(expected);
-}
-
-// --- Signature verification helpers ---
-
-/**
- * Algorithms accepted when the merchant has configured an explicit,
- * out-of-band-trusted public key. The merchant already trusts this key by
- * configuring it, so we support the same breadth of algorithms the
- * original implementation advertised.
- */
-const EXPLICIT_KEY_ALLOWED_ALGS = new Set(['EdDSA', 'ES256', 'ES384', 'ES512', 'RS256', 'RS384', 'RS512']);
-
-function hashAlgForJwtAlg(alg) {
-  if (alg === 'EdDSA') return null; // Ed25519/Ed448 signature algorithm is built into the key
-  if (alg.includes('384')) return 'SHA384';
-  if (alg.includes('512')) return 'SHA512';
-  return 'SHA256';
-}
-
-/**
- * Verifies an AP2 mandate SD-JWT presented in an incoming request.
- *
- * @param {Record<string, string>} [headers]
- * @param {Record<string, unknown>} [body]
- * @param {object} [options]
- * @param {crypto.KeyObject|Buffer|string|null} [options.trustedPublicKey] - merchant-configured
- *   out-of-band-trusted key (any format accepted by crypto.createPublicKey, or an
- *   already-constructed KeyObject). When set, this key is used instead of deriving
- *   one from a did:key issuer, and the broader algorithm set is permitted.
- * @param {string} [options.expectedAudience] - if set, `aud` must equal this value
- * @param {number} [options.maxMandateLifetimeSec=3600] - maximum allowed `exp - iat`
- * @param {boolean} [options.requireJti=true] - reject mandates without a `jti` claim
- * @param {string[]} [options.requestedCategories] - if set and the mandate's
- *   `intentMandate.allowedCategories` is present, the two must overlap
- * @param {boolean} [options.allowSelfCertifying=true] - v4: when false,
- *   self-certifying did:key mandates are rejected and only the
- *   merchant-configured trusted key is accepted (production-grade posture:
- *   a self-certifying mandate proves only that the MINTER holds the key,
- *   not that any real wallet/payer authorized the spend)
- * @param {string} [options.expectedCurrency] - v4: when set, the mandate's
- *   declared currency (intentMandate.currency or paymentMandate.currency)
- *   must match it, closing unit-mismatch budget attacks (a "100" cap in a
- *   low-value currency authorizing 100 in the merchant's currency)
- * @param {boolean} [options.consumeJti=true] - second-pass review: when
- *   false, a valid mandate is verified and returned WITHOUT consuming its
- *   single-use jti. The middleware passes false for mandates presented on
- *   non-AP2 routes so a mandate riding along on an unrelated action does
- *   not burn itself; AP2 endpoints consume as before.
- * @returns {{ valid: boolean, verified: boolean, protocol: 'AP2', reason?: string, mandates?: object }}
- */
-export function verifyAp2Mandate(headers = {}, body = {}, options = {}) {
-  const {
-    trustedPublicKey = null,
-    expectedAudience = null,
-    maxMandateLifetimeSec = 3600,
-    requireJti = true,
-    requestedCategories = null,
-    allowSelfCertifying = true,
-    expectedCurrency = null,
-    consumeJti = true,
-  } = options;
-
-  const mandateHeader = headers['x-ap2-mandate'] || headers['authorization'];
-  if (!mandateHeader) {
-    // AP2 simply isn't in use for this request - not a security decision.
-    return { valid: true, protocol: 'AP2', verified: false, note: 'No AP2 Mandates attached' };
-  }
-
-  let header, payload, signatureB64;
-  try {
-    const token = String(mandateHeader).replace(/^Bearer\s+/i, '');
-    const parts = token.split('.');
-    if (parts.length < 3) return { valid: false, reason: 'Invalid AP2 Mandate SD-JWT format', protocol: 'AP2' };
-    header = JSON.parse(Buffer.from(parts[0], 'base64url').toString('utf8'));
-    payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
-    signatureB64 = parts[2];
-  } catch {
-    return { valid: false, reason: 'Invalid AP2 Mandate SD-JWT format', protocol: 'AP2' };
-  }
-
-  // --- JOSE header sanity (v4 medium pass) ---
-  // The typ claim, when present, must be a JWT/SD-JWT type. Anything else
-  // (e.g. a nested JWT or an attacker-chosen custom typ) is rejected rather
-  // than silently processed. Selective-disclosure processing remains a
-  // documented gap - this verifier handles the signed envelope only.
-  if (
-    header.typ !== undefined &&
-    !['jwt', 'sd-jwt'].includes(String(header.typ).toLowerCase())
-  ) {
-    return { valid: false, reason: `Unsupported mandate typ: ${header.typ}`, protocol: 'AP2' };
-  }
-  if (!header.alg) {
-    return { valid: false, reason: 'Missing alg in mandate header', protocol: 'AP2' };
-  }
-
-  // --- Required claims present ---
-  if (!payload.iss) return { valid: false, reason: 'Missing issuer', protocol: 'AP2' };
-  if (!payload.aud) return { valid: false, reason: 'Missing audience', protocol: 'AP2' };
-  if (typeof payload.iat !== 'number') return { valid: false, reason: 'Missing iat', protocol: 'AP2' };
-  if (typeof payload.exp !== 'number') return { valid: false, reason: 'Missing exp', protocol: 'AP2' };
-  if (requireJti && !payload.jti) {
-    return { valid: false, reason: 'Missing jti (required for replay protection)', protocol: 'AP2' };
-  }
-
-  // --- Temporal validity ---
-  const now = Math.floor(Date.now() / 1000);
-  if (payload.exp < now) return { valid: false, reason: 'Token expired', protocol: 'AP2' };
-  if (payload.iat > now) return { valid: false, reason: 'Token issued in the future', protocol: 'AP2' };
-
-  // --- Bounded mandate lifetime ---
-  if (payload.exp - payload.iat > maxMandateLifetimeSec) {
-    return { valid: false, reason: `Mandate lifetime exceeds maximum allowed (${maxMandateLifetimeSec}s)`, protocol: 'AP2' };
-  }
-
-  // --- Resolve verification key + algorithm policy ---
-  let publicKey = null;
-  let usingSelfCertifyingKey = false;
-
-  // v4: merchants can require an out-of-band-trusted issuer. A
-  // self-certifying did:key mandate is cryptographically sound but
-  // semantically self-vouched - anyone can mint one declaring any
-  // maxBudget - so production deployments that bind mandates to real
-  // wallets should set allowSelfCertifying: false.
-  const isDidKeyIssuer = String(payload.iss || '').startsWith('did:key:');
-  if (!allowSelfCertifying && isDidKeyIssuer) {
-    return {
-      valid: false,
-      reason: 'Self-certifying did:key mandates are disabled for this store; a merchant-trusted public key is required',
-      protocol: 'AP2',
-    };
-  }
-
-  if (trustedPublicKey) {
-    try {
-      publicKey = trustedPublicKey instanceof crypto.KeyObject
-        ? trustedPublicKey
-        : crypto.createPublicKey(trustedPublicKey);
-    } catch {
-      return { valid: false, reason: 'Configured trusted public key is invalid', protocol: 'AP2' };
-    }
-    if (!EXPLICIT_KEY_ALLOWED_ALGS.has(header.alg)) {
-      return { valid: false, reason: `Unsupported signature algorithm: ${header.alg}`, protocol: 'AP2' };
-    }
-  } else if (isDidKeyIssuer) {
-    usingSelfCertifyingKey = true;
-    if (header.alg !== 'EdDSA') {
-      return { valid: false, reason: 'did:key issuers require the EdDSA algorithm', protocol: 'AP2' };
-    }
-    publicKey = ed25519PublicKeyFromDidKey(payload.iss);
-    if (!publicKey) {
-      return { valid: false, reason: 'Issuer is not a valid Ed25519 did:key identifier', protocol: 'AP2' };
-    }
-  } else {
-    // No merchant-trusted key configured, and the issuer isn't a
-    // self-certifying did:key we can derive a key from - there is no way
-    // to verify this mandate, so it must be rejected rather than passed
-    // through as "valid but unverified".
-    return {
-      valid: false,
-      reason: 'Cannot verify mandate: issuer is not a did:key and no trusted public key is configured',
-      protocol: 'AP2',
-    };
-  }
-
-  // --- Signature verification (mandatory) ---
-  try {
-    const [encodedHeader, encodedPayload] = String(mandateHeader).replace(/^Bearer\s+/i, '').split('.');
-    const signingInput = Buffer.from(`${encodedHeader}.${encodedPayload}`);
-    const signature = Buffer.from(signatureB64, 'base64url');
-    const hashAlg = hashAlgForJwtAlg(header.alg);
-    const isValid = crypto.verify(hashAlg, signingInput, publicKey, signature);
-    if (!isValid) return { valid: false, reason: 'Invalid signature', protocol: 'AP2' };
-  } catch (err) {
-    return { valid: false, reason: `Signature verification failed: ${err.message}`, protocol: 'AP2' };
-  }
-
-  // --- Audience binding ---
-  if (expectedAudience && !audienceMatches(payload.aud, expectedAudience)) {
-    return {
-      valid: false,
-      reason: `Mandate audience "${payload.aud}" does not match this store ("${expectedAudience}")`,
-      protocol: 'AP2',
-    };
-  }
-
-  // --- merchantScope binding (if the mandate declares one, it must match too) ---
-  const merchantScope = payload.intentMandate?.merchantScope;
-  if (expectedAudience && merchantScope && !audienceMatches(merchantScope, expectedAudience)) {
-    return {
-      valid: false,
-      reason: `Mandate merchantScope "${merchantScope}" does not match this store ("${expectedAudience}")`,
-      protocol: 'AP2',
-    };
-  }
-
-  // --- Replay protection + final validations ---
-  // v4: the jti is now consumed with an ATOMIC claim() as the FINAL step,
-  // after every other validation passes. This preserves the 2026-08 audit
-  // semantics (an over-budget/category/audience attempt never burns the
-  // mandate - the corrected retry works) while closing the check-then-act
-  // race where two concurrent requests could both observe "not seen"
-  // before either recorded the jti. With claim(), exactly one concurrent
-  // request wins the mandate; the loser is rejected as a replay.
-  return finishVerification();
-
-  /** Everything after signature/audience verification. Maybe-async. */
-  function finishVerification() {
-
-  // --- Category enforcement (only if both the mandate and caller supply it) ---
-  const allowedCategories = payload.intentMandate?.allowedCategories;
-  if (Array.isArray(allowedCategories) && Array.isArray(requestedCategories) && requestedCategories.length > 0) {
-    const overlaps = requestedCategories.some((c) => allowedCategories.includes(c));
-    if (!overlaps) {
-      return {
-        valid: false,
-        reason: `Requested categories [${requestedCategories.join(', ')}] are not within the mandate's allowedCategories [${allowedCategories.join(', ')}]`,
-        protocol: 'AP2',
-      };
-    }
-  }
-
-  // --- Budget enforcement (checked here for the common case where the
-  // caller already knows the order total; the SDK middleware also
-  // re-checks this at the /ap2/checkout call site once the cart total is known) ---
-  const maxBudget = payload.intentMandate?.maxBudget ?? payload.paymentMandate?.maxBudget;
-  if (maxBudget !== undefined && body?.orderTotal !== undefined) {
-    if (Number(body.orderTotal) > Number(maxBudget)) {
-      return { valid: false, reason: 'Order total exceeds Intent Mandate maxBudget limit', protocol: 'AP2' };
-    }
-  }
-
-  // --- Currency binding (v4 medium pass) ---
-  // A budget number without a currency is unitless and forgeable by
-  // relabeling: a "100" cap minted in a low-value currency must not
-  // authorize "100" in the merchant's currency. When both sides declare a
-  // currency they must agree; merchants can also pin one via expectedCurrency.
-  const mandateCurrency = payload.intentMandate?.currency ?? payload.paymentMandate?.currency;
-  const normalizeCurrency = (value) => String(value || '').trim().toUpperCase();
-  if (mandateCurrency && expectedCurrency && normalizeCurrency(mandateCurrency) !== normalizeCurrency(expectedCurrency)) {
-    return {
-      valid: false,
-      reason: `Mandate currency "${mandateCurrency}" does not match this store's expected currency "${expectedCurrency}"`,
-      protocol: 'AP2',
-    };
-  }
-  if (
-    mandateCurrency &&
-    body?.currency &&
-    normalizeCurrency(mandateCurrency) !== normalizeCurrency(body.currency)
-  ) {
-    return {
-      valid: false,
-      reason: `Order currency "${body.currency}" does not match the mandate's currency "${mandateCurrency}"`,
-      protocol: 'AP2',
-    };
-  }
-
-  const replayRejection = () => ({
-    valid: false,
-    reason: 'Mandate has already been used (replay detected)',
-    protocol: 'AP2',
-  });
-
-  // --- Consume the jti: every validation above passed, so winning the
-  // atomic claim is the single successful use of this mandate. When
-  // consumeJti is false (non-AP2 routes), skip consumption entirely. ---
-  if (payload.jti && consumeJti) {
-    const claimed = seenMandateJtis.claim(payload.jti, payload.exp * 1000);
-    if (typeof claimed === 'boolean') {
-      if (!claimed) return replayRejection();
-    } else {
-      return claimed.then((won) => (won ? buildSuccess() : replayRejection()));
-    }
-  }
-
-  return buildSuccess();
-
-  function buildSuccess() {
-    return {
-      valid: true,
-      protocol: 'AP2',
-      verified: true,
-      selfCertifying: usingSelfCertifyingKey,
-      mandates: payload,
-    };
-  }
-  }
-}
-
-/**
- * Builds and signs a complete AP2 Intent+Payment Mandate SD-JWT for
- * agent-side tooling (test harnesses, demos, or a real agent's own wallet
- * integration). The issuer is a did:key derived from the signing keypair,
- * so the resulting mandate self-certifies without any prior key
- * registration with the merchant.
- *
- * @param {object} options
- * @param {string} options.audience - the merchant/store base URL this mandate authorizes (required)
- * @param {number} options.maxBudget - spending cap enforced by the merchant on checkout
- * @param {string} [options.currency='USD']
- * @param {string[]} [options.allowedCategories] - optional category allowlist
- * @param {string} [options.merchantScope] - defaults to `audience`
- * @param {number} [options.lifetimeSec=3600] - mandate validity window
- * @param {string} [options.paymentMethod='tokenized_card']
- * @param {string} [options.subject='user_wallet_delegation']
- * @param {crypto.KeyObject} [options.privateKey] - reuse an existing Ed25519 private key;
- *   a fresh ephemeral keypair is generated if omitted
- * @returns {{ token: string, did: string, publicKey: crypto.KeyObject, privateKey: crypto.KeyObject }}
- */
-export function createAp2Mandate(options = {}) {
-  const {
-    audience,
-    maxBudget,
-    currency = 'USD',
-    allowedCategories,
-    merchantScope,
-    lifetimeSec = 3600,
-    paymentMethod = 'tokenized_card',
-    subject = 'user_wallet_delegation',
-    privateKey: providedPrivateKey,
-  } = options;
-
-  if (!audience) throw new Error('createAp2Mandate requires an `audience` (the target store base URL)');
-  if (maxBudget === undefined) throw new Error('createAp2Mandate requires a `maxBudget`');
-
-  const { privateKey, publicKey } = providedPrivateKey
-    ? { privateKey: providedPrivateKey, publicKey: crypto.createPublicKey(providedPrivateKey) }
-    : crypto.generateKeyPairSync('ed25519');
-
-  const did = didKeyFromEd25519PublicKey(publicKey);
-  const iat = Math.floor(Date.now() / 1000);
-  const exp = iat + lifetimeSec;
-
-  const header = { alg: 'EdDSA', typ: 'JWT' };
-  const payload = {
-    iss: did,
-    aud: audience,
-    sub: subject,
-    iat,
-    exp,
-    jti: crypto.randomUUID(),
-    intentMandate: {
-      maxBudget,
-      currency,
-      merchantScope: merchantScope || audience,
-      ...(allowedCategories ? { allowedCategories } : {}),
-    },
-    paymentMandate: {
-      paymentMethod,
-      currency,
-    },
-  };
-
-  const encodedHeader = Buffer.from(JSON.stringify(header)).toString('base64url');
-  const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
-  const signingInput = `${encodedHeader}.${encodedPayload}`;
-  const signature = crypto.sign(null, Buffer.from(signingInput), privateKey).toString('base64url');
-
-  return { token: `${signingInput}.${signature}`, did, publicKey, privateKey };
-}
+import crypto from 'crypto';
+import { createReplayCache } from './shared-store.js';
+import {
+  compareAmounts,
+  normalizeCurrencyCode,
+  parseAmount,
+  sumLineItems,
+  toHundredths,
+} from './money.js';
+
+/**
+ * Hardened AP2 (Agent Payments Protocol) mandate verification.
+ *
+ * A mandate is a cryptographic spending authorization. If this file is wrong,
+ * money moves that should not have. The rules enforced here:
+ *
+ *   1. No mandate header at all => AP2 simply isn't in use for this request:
+ *      `{ valid: true, verified: false }`, so plain REST/ACP traffic is never
+ *      blocked by AP2 logic. Callers that GATE on a mandate must therefore
+ *      check `.verified`, never mere truthiness.
+ *   2. A mandate that IS presented MUST verify cryptographically or the
+ *      request is rejected. There is no "valid but unverified" middle ground.
+ *   3. Verification uses either a merchant-configured trusted public key
+ *      (out-of-band trust) or a self-certifying `did:key` issuer, where the
+ *      public key IS the issuer identifier.
+ *   4. Mandates carry a unique `jti` and are single-use against an atomic
+ *      replay claim, consumed only after every other check passes so a
+ *      rejected attempt does not brick the corrected retry.
+ *   5. `aud` (and `intentMandate.merchantScope`) bind the mandate to one
+ *      store, so a mandate signed for store A cannot be replayed at store B.
+ *   6. `exp - iat` is bounded, so a "valid forever" mandate cannot be minted.
+ *
+ * ---------------------------------------------------------------------------
+ * What this hardening pass changed
+ * ---------------------------------------------------------------------------
+ *
+ * - **ECDSA now verifies.** `crypto.verify(hash, data, key, sig)` expects DER;
+ *   JOSE `ES256`/`ES384`/`ES512` signatures are raw `r||s`. Every genuine
+ *   ECDSA-signed mandate previously failed, while the algorithm allow-list and
+ *   `/ap2/capabilities` both advertised support. Fixed with
+ *   `dsaEncoding: 'ieee-p1363'` plus explicit curve pinning.
+ * - **`alg` is pinned to the trusted key.** Membership in an allow-list is not
+ *   a binding: an `ES256` header against an RSA trusted key used to reach the
+ *   crypto call and merely fail, rather than being refused as a policy error.
+ *   RSA keys below 2048 bits are refused.
+ * - **Money is exact.** `Number(orderTotal) > Number(maxBudget)` compared
+ *   IEEE-754 doubles, and `Number('abc')` is `NaN`, for which every comparison
+ *   is false — a malformed total PASSED the budget check. Amounts now parse
+ *   strictly and compare as exact integers (see ./money.js).
+ * - **Unitless budgets are rejected.** Every currency check used to be
+ *   conditional on the mandate declaring a currency, so a mandate with
+ *   `maxBudget` and no `currency` bypassed all of them.
+ * - **Clock skew is tolerated.** `iat`/`exp` were compared with zero
+ *   tolerance, rejecting legitimate mandates from any client a second fast.
+ * - **The envelope is strict.** `parts.length >= 3` accepted a 5-segment
+ *   JWE-shaped token and treated part 3 as the signature; `crit` was ignored;
+ *   SD-JWT `~` disclosures were silently truncated. All now refused.
+ * - **Rejections carry a `code` and a `disclose` flag** so the HTTP layer can
+ *   tell an agent "your budget is too low" (actionable) without telling it
+ *   "this store expects audience X" or echoing raw crypto error text.
+ * - **`jti` is validated** before it becomes a cache key, and the cart hash
+ *   totals are overflow-checked.
+ */
+
+// --- base58btc (Bitcoin alphabet) - no external dependency ---
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const BASE58_MAP = new Map(BASE58_ALPHABET.split('').map((c, i) => [c, i]));
+/**
+ * base58 decoding is O(n^2) in BigInt divisions. A did:key for Ed25519 is
+ * always 48 characters, so anything materially longer is either a mistake or
+ * an attempt to burn CPU.
+ */
+const MAX_BASE58_LENGTH = 128;
+
+/** @param {Buffer} buffer @returns {string} */
+function base58Encode(buffer) {
+  if (buffer.length === 0) return '';
+  let value = 0n;
+  for (const byte of buffer) value = value * 256n + BigInt(byte);
+
+  let encoded = '';
+  while (value > 0n) {
+    const remainder = value % 58n;
+    value /= 58n;
+    encoded = BASE58_ALPHABET[Number(remainder)] + encoded;
+  }
+
+  let leadingZeros = 0;
+  for (const byte of buffer) {
+    if (byte === 0) leadingZeros++;
+    else break;
+  }
+  return BASE58_ALPHABET[0].repeat(leadingZeros) + encoded;
+}
+
+/** @param {string} str @returns {Buffer} */
+function base58Decode(str) {
+  if (str.length === 0) return Buffer.alloc(0);
+  if (str.length > MAX_BASE58_LENGTH) throw new Error('base58 input is too long');
+  let value = 0n;
+  for (const char of str) {
+    const digit = BASE58_MAP.get(char);
+    if (digit === undefined) throw new Error(`Invalid base58 character: ${char}`);
+    value = value * 58n + BigInt(digit);
+  }
+
+  const bytes = [];
+  while (value > 0n) {
+    bytes.unshift(Number(value % 256n));
+    value /= 256n;
+  }
+
+  let leadingZeros = 0;
+  for (const char of str) {
+    if (char === BASE58_ALPHABET[0]) leadingZeros++;
+    else break;
+  }
+  return Buffer.concat([Buffer.alloc(leadingZeros, 0), Buffer.from(bytes)]);
+}
+
+// Ed25519 multicodec (0xed) varint-encoded as [0xed, 0x01], per the did:key
+// Ed25519 method spec (multicodec ed25519-pub prefix).
+const ED25519_MULTICODEC_PREFIX = Buffer.from([0xed, 0x01]);
+
+// Fixed 12-byte SPKI DER prefix for Ed25519 public keys (RFC 8410) - Ed25519
+// has no algorithm parameters, so the DER encoding of any Ed25519 SPKI key is
+// always this fixed prefix followed by the raw 32-byte public key.
+const ED25519_SPKI_DER_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
+/**
+ * Derives a did:key identifier from an Ed25519 public key.
+ * @param {crypto.KeyObject|Buffer} publicKey
+ * @returns {string} e.g. "did:key:z6Mk..."
+ */
+export function didKeyFromEd25519PublicKey(publicKey) {
+  const rawKey = Buffer.isBuffer(publicKey)
+    ? publicKey
+    : publicKey.export({ type: 'spki', format: 'der' }).subarray(-32);
+  const prefixed = Buffer.concat([ED25519_MULTICODEC_PREFIX, rawKey]);
+  return `did:key:z${base58Encode(prefixed)}`;
+}
+
+/**
+ * Derives an Ed25519 public KeyObject from a did:key identifier.
+ * @param {string} didKey
+ * @returns {crypto.KeyObject|null} null when the identifier is not a
+ *   well-formed Ed25519 did:key (callers treat this as "cannot verify")
+ */
+export function ed25519PublicKeyFromDidKey(didKey) {
+  if (typeof didKey !== 'string' || !didKey.startsWith('did:key:z')) return null;
+  try {
+    const multibase = didKey.slice('did:key:'.length);
+    const decoded = base58Decode(multibase.slice(1)); // drop leading 'z' multibase prefix
+    if (
+      decoded.length !== ED25519_MULTICODEC_PREFIX.length + 32
+      || !decoded.subarray(0, 2).equals(ED25519_MULTICODEC_PREFIX)
+    ) {
+      return null;
+    }
+    const rawKey = decoded.subarray(2);
+    const der = Buffer.concat([ED25519_SPKI_DER_PREFIX, rawKey]);
+    return crypto.createPublicKey({ key: der, format: 'der', type: 'spki' });
+  } catch {
+    return null;
+  }
+}
+
+// --- Replay protection ---
+// Consumed mandate jtis. Local Map by default; when an Upstash Redis REST
+// endpoint is configured (see lib/shared-store.js) the cache becomes
+// cluster-wide so a mandate consumed on one instance cannot replay against
+// another. `claim()` is maybe-async (boolean locally, Promise when shared).
+const seenMandateJtis = createReplayCache('agentsbloom:ap2:jti', 50_000);
+
+/** Clears all replay-tracking state. Exposed for tests and shutdown(). */
+export function resetAp2ReplayCache() {
+  seenMandateJtis.clear();
+}
+
+/** Replay-cache diagnostics (local size, evictions, shared-store posture). */
+export function ap2ReplayCacheStats() {
+  return seenMandateJtis.stats();
+}
+
+/** No-op retained for shutdown() compatibility; eviction is amortized. */
+export function stopAp2ReplayCleanup() {}
+
+/**
+ * Normalizes an audience/merchantScope value for comparison.
+ *
+ * Clients that build URLs with `new URL(...).href` produce a trailing slash
+ * while merchants configure the same audience without one, and a default port
+ * may or may not be present (`https://x` vs `https://x:443`). Comparing raw
+ * strings rejected perfectly valid mandates, so both sides are normalized:
+ * lowercased host, default port for the scheme removed, trailing slashes
+ * stripped. Non-URL audience strings keep the plain slash-stripped behavior.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+export function normalizeAudience(value) {
+  if (typeof value !== 'string') return String(value ?? '');
+  const trimmed = value.trim();
+  if (trimmed === '') return trimmed;
+  try {
+    const url = new URL(trimmed);
+    const defaultPort = url.protocol === 'https:' ? '443' : url.protocol === 'http:' ? '80' : null;
+    // `url.host` keeps a non-default port; drop the scheme's default so
+    // https://store.example.com and https://store.example.com:443 match.
+    const host = defaultPort && url.port === defaultPort ? url.hostname : url.host;
+    const path = url.pathname.replace(/\/+$/, '');
+    return `${url.protocol}//${host}${path}`;
+  } catch {
+    return trimmed.replace(/\/+$/, '');
+  }
+}
+
+/** Audience comparison that tolerates URL-normalization differences. */
+function audienceMatches(claimed, expected) {
+  return normalizeAudience(claimed) === normalizeAudience(expected);
+}
+
+// --- Canonical cart binding (Cart Mandate support) ---
+//
+// AP2's Cart Mandate proves the human approved an EXACT cart, not just a
+// budget. The proof only means something if the merchant can recompute the
+// same fingerprint from its own session cart and compare it against the
+// signed claim - so both sides need one deterministic serialization.
+//
+// Rules (must stay byte-identical to the agent-sdk WebCrypto port):
+//   * payload  = { v: 1, currency, items: [{ id, s, q, u }] }
+//     - id: product identifier string; s: size/variant string ('' when none)
+//     - q: positive integer quantity; u: unit price in HUNDREDTHS of the
+//          major unit. Hundredths is fixed by the wire format, deliberately
+//          independent of the currency's real ISO 4217 minor unit, so every
+//          port computes the same bytes without a currency table.
+//     - items sorted by (id, s); totalCents derived as sum(q*u)
+//   * stableStringify: object keys sorted recursively, arrays keep order
+//   * cartHash = 'ac1_' + base64url(sha256(stableStringify(payload)))
+// Only strings and integers appear in the payload, so JSON.stringify output is
+// identical across Node/V8 and browser engines (no float formatting).
+
+/** Bounds per-item quantity so a cart cannot be used to force an overflow. */
+const MAX_ITEM_QUANTITY = 1_000_000;
+/** Bounds cart size; a cart hash over 10k lines is not a real basket. */
+const MAX_CART_ITEMS = 1000;
+
+/**
+ * Deterministic JSON serialization: object keys sorted lexicographically at
+ * every depth, arrays kept in order. Throws on non-finite numbers and on
+ * structures nested deeply enough to risk a stack overflow.
+ *
+ * @param {unknown} value
+ * @param {number} [depth]
+ * @returns {string}
+ */
+export function stableStringify(value, depth = 0) {
+  if (depth > 64) throw new Error('stableStringify: input is nested too deeply');
+  if (value === null || typeof value !== 'object') {
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+      throw new Error('stableStringify cannot serialize non-finite numbers');
+    }
+    if (typeof value === 'bigint') throw new Error('stableStringify cannot serialize BigInt');
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => (entry === undefined ? 'null' : stableStringify(entry, depth + 1))).join(',')}]`;
+  }
+  const keys = Object.keys(value).filter((key) => value[key] !== undefined).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key], depth + 1)}`).join(',')}}`;
+}
+
+/**
+ * Normalizes a cart into the canonical integer-only payload and returns it
+ * together with the derived cartHash. Both the agent side (agent-sdk port)
+ * and merchants (via this function) must produce identical hashes for the
+ * same logical cart or the Cart Mandate binding rejects checkout.
+ *
+ * @param {object} input
+ * @param {string} [input.currency='USD']
+ * @param {Array<{id: unknown, size?: unknown, quantity?: unknown, unitPrice?: unknown, price?: unknown}>} input.items
+ * @returns {{ payload: object, itemCount: number, totalCents: number, cartHash: string }}
+ */
+export function canonicalCartHash(input = {}) {
+  const currency = normalizeCurrencyCode(input.currency) || 'USD';
+  const rawItems = Array.isArray(input.items) ? input.items : [];
+  if (rawItems.length > MAX_CART_ITEMS) {
+    throw new Error(`canonicalCartHash: a cart may contain at most ${MAX_CART_ITEMS} items`);
+  }
+
+  const items = rawItems.map((item) => {
+    const id = String(item?.id ?? '').trim();
+    const size = String(item?.size ?? '').trim();
+    if (!id) throw new Error('canonicalCartHash: every cart item requires an `id`');
+
+    // Quantities are counts, not money: an integer parse is correct here.
+    const quantityAmount = parseAmount(item?.quantity, { allowZero: false });
+    const quantity = quantityAmount === null ? NaN : Math.round(Number(quantityAmount.decimal));
+    if (!Number.isInteger(quantity) || quantity <= 0 || quantity > MAX_ITEM_QUANTITY) {
+      throw new Error(`canonicalCartHash: item "${id}" has an invalid quantity`);
+    }
+
+    // Exact decimal -> hundredths. `Math.round(price * 100)` silently lost a
+    // cent for any price whose double sits just below a half-cent boundary.
+    const unitSource = item?.unitPrice ?? item?.price ?? 0;
+    const unitCents = toHundredths(unitSource);
+    if (unitCents === null || unitCents < 0) {
+      throw new Error(`canonicalCartHash: item "${id}" has an invalid unit price`);
+    }
+    return { id, s: size, q: quantity, u: unitCents };
+  }).sort((a, b) => (a.id === b.id ? (a.s < b.s ? -1 : a.s > b.s ? 1 : 0) : a.id < b.id ? -1 : 1));
+
+  if (!items.length) throw new Error('canonicalCartHash: the cart has no items');
+
+  const payload = { v: 1, currency, items };
+  // Exact summation: the old `reduce` over doubles silently lost precision
+  // past 2^53, which would let a crafted cart produce a total the merchant
+  // could not reproduce.
+  const totalCents = sumLineItems(items.map((item) => ({ quantity: item.q, unitHundredths: item.u })));
+  if (totalCents === null) throw new Error('canonicalCartHash: the cart total is not exactly representable');
+  const itemCount = sumLineItems(items.map((item) => ({ quantity: item.q, unitHundredths: 1 })));
+
+  const digest = crypto.createHash('sha256').update(stableStringify(payload)).digest('base64url');
+  return { payload, itemCount, totalCents, cartHash: `ac1_${digest}` };
+}
+
+// --- Signature verification helpers ---
+
+/**
+ * JWS algorithms, each pinned to the exact key material it may be used with.
+ *
+ * The previous implementation kept a flat allow-list (`EXPLICIT_KEY_ALLOWED_ALGS`)
+ * and let a mismatch fall through to the crypto call. Membership in a set is
+ * not a binding; this table is.
+ */
+const JWS_ALGORITHMS = Object.freeze({
+  EdDSA: { keyType: 'ed25519', hash: null },
+  ES256: { keyType: 'ec', curve: 'prime256v1', hash: 'sha256', dsaEncoding: 'ieee-p1363', sigLength: 64 },
+  ES384: { keyType: 'ec', curve: 'secp384r1', hash: 'sha384', dsaEncoding: 'ieee-p1363', sigLength: 96 },
+  ES512: { keyType: 'ec', curve: 'secp521r1', hash: 'sha512', dsaEncoding: 'ieee-p1363', sigLength: 132 },
+  RS256: { keyType: 'rsa', hash: 'sha256', rsaPadding: 'pkcs1' },
+  RS384: { keyType: 'rsa', hash: 'sha384', rsaPadding: 'pkcs1' },
+  RS512: { keyType: 'rsa', hash: 'sha512', rsaPadding: 'pkcs1' },
+  PS256: { keyType: 'rsa', hash: 'sha256', rsaPadding: 'pss' },
+  PS384: { keyType: 'rsa', hash: 'sha384', rsaPadding: 'pss' },
+  PS512: { keyType: 'rsa', hash: 'sha512', rsaPadding: 'pss' },
+});
+
+/** Algorithms accepted when the merchant configured an explicit trusted key. */
+export const SUPPORTED_MANDATE_ALGORITHMS = Object.freeze(Object.keys(JWS_ALGORITHMS));
+
+const MIN_RSA_MODULUS_BITS = 2048;
+/** `jti` becomes a replay-cache key; bound its shape before it is used. */
+const JTI_PATTERN = /^[\x21-\x7e]{8,256}$/;
+/** A compact JWS is three base64url segments and nothing else. */
+const COMPACT_JWS_SEGMENT = /^[A-Za-z0-9_-]+$/;
+/** Bounds the whole token so a giant header cannot cost real work. */
+const MAX_MANDATE_TOKEN_LENGTH = 16 * 1024;
+/** Default tolerance for client/server clock drift, in seconds. */
+const DEFAULT_CLOCK_SKEW_SEC = 60;
+
+/**
+ * Confirms a key is usable with a declared algorithm.
+ *
+ * @param {crypto.KeyObject} key
+ * @param {string} alg
+ * @returns {string|null} an error description, or null when compatible
+ */
+function keyIncompatibility(key, alg) {
+  const spec = JWS_ALGORITHMS[alg];
+  if (!spec) return `Unsupported signature algorithm: ${alg}`;
+  const keyType = String(key.asymmetricKeyType || '').toLowerCase();
+  const details = key.asymmetricKeyDetails || {};
+
+  if (spec.keyType === 'ed25519') {
+    if (keyType !== 'ed25519') return `Algorithm ${alg} requires an Ed25519 key, got ${keyType || 'unknown'}`;
+    return null;
+  }
+  if (spec.keyType === 'ec') {
+    if (keyType !== 'ec') return `Algorithm ${alg} requires an EC key, got ${keyType || 'unknown'}`;
+    if (details.namedCurve !== spec.curve) {
+      return `Algorithm ${alg} requires curve ${spec.curve}, got ${details.namedCurve || 'unknown'}`;
+    }
+    return null;
+  }
+  if (spec.keyType === 'rsa') {
+    if (keyType !== 'rsa' && keyType !== 'rsa-pss') {
+      return `Algorithm ${alg} requires an RSA key, got ${keyType || 'unknown'}`;
+    }
+    const bits = Number(details.modulusLength || 0);
+    if (!(bits >= MIN_RSA_MODULUS_BITS)) {
+      return `RSA key is ${bits || 'an unknown number of'} bits; the minimum is ${MIN_RSA_MODULUS_BITS}`;
+    }
+    return null;
+  }
+  return `Unsupported signature algorithm: ${alg}`;
+}
+
+/**
+ * Verifies a compact JWS signature with the algorithm's exact parameters.
+ *
+ * @param {string} alg
+ * @param {crypto.KeyObject} key
+ * @param {Buffer} signingInput
+ * @param {Buffer} signature
+ * @returns {boolean}
+ */
+function verifyJwsSignature(alg, key, signingInput, signature) {
+  const spec = JWS_ALGORITHMS[alg];
+  if (!spec) return false;
+
+  if (spec.keyType === 'ed25519') {
+    if (signature.length !== 64) return false;
+    return crypto.verify(null, signingInput, key, signature);
+  }
+  if (spec.keyType === 'ec') {
+    // JOSE ECDSA signatures are raw r||s. Node defaults to DER, which is why
+    // every genuine ES* mandate failed before this line existed.
+    if (signature.length !== spec.sigLength) return false;
+    return crypto.verify(spec.hash, signingInput, { key, dsaEncoding: spec.dsaEncoding }, signature);
+  }
+  const keyInput = spec.rsaPadding === 'pss'
+    ? { key, padding: crypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: crypto.constants.RSA_PSS_SALTLEN_DIGEST }
+    : { key, padding: crypto.constants.RSA_PKCS1_PADDING };
+  return crypto.verify(spec.hash, signingInput, keyInput, signature);
+}
+
+/**
+ * Builds a rejection result.
+ *
+ * `disclose` tells the HTTP layer whether `reason` is safe to return to the
+ * caller. Actionable policy failures (budget too low, wrong category, replay)
+ * are disclosed so a legitimate agent can self-correct; anything that would
+ * reveal store configuration or verifier internals is not.
+ */
+function rejectMandate(code, reason, { disclose = true, publicReason } = {}) {
+  return {
+    valid: false,
+    protocol: 'AP2',
+    verified: false,
+    code,
+    reason,
+    disclose,
+    publicReason: publicReason || (disclose ? reason : 'The mandate failed validation.'),
+  };
+}
+
+/**
+ * Projects the decoded mandate payload down to the claims the SDK and
+ * merchant handlers actually consume.
+ *
+ * The verifier used to return `mandates: payload` — the entire
+ * attacker-supplied JWT body — which `/ap2/intent` then echoed back in its
+ * response. That is an unbounded reflection surface and an easy way to smuggle
+ * content through a store's own API.
+ *
+ * @param {Record<string, unknown>} payload
+ * @returns {Record<string, unknown>}
+ */
+function projectMandate(payload) {
+  const pick = (source, keys) => {
+    if (!source || typeof source !== 'object') return undefined;
+    const out = {};
+    for (const key of keys) {
+      if (source[key] !== undefined) out[key] = source[key];
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+  };
+
+  const intent = pick(payload.intentMandate, [
+    'maxBudget', 'currency', 'merchantScope', 'allowedCategories', 'expiresAt',
+  ]);
+  if (intent && Array.isArray(intent.allowedCategories)) {
+    intent.allowedCategories = intent.allowedCategories
+      .filter((entry) => typeof entry === 'string')
+      .slice(0, 64)
+      .map((entry) => entry.slice(0, 128));
+  }
+
+  const projected = {
+    iss: payload.iss,
+    aud: payload.aud,
+    sub: typeof payload.sub === 'string' ? payload.sub.slice(0, 256) : payload.sub,
+    iat: payload.iat,
+    exp: payload.exp,
+    jti: payload.jti,
+  };
+  if (intent) projected.intentMandate = intent;
+  const cart = pick(payload.cartMandate, ['cartHash', 'itemCount', 'totalCents', 'currency']);
+  if (cart) projected.cartMandate = cart;
+  const payment = pick(payload.paymentMandate, ['paymentMethod', 'currency', 'agentInitiated', 'maxBudget']);
+  if (payment) projected.paymentMandate = payment;
+  return projected;
+}
+
+/**
+ * Verifies an AP2 mandate SD-JWT presented in an incoming request.
+ *
+ * Returns synchronously when no shared replay store is configured, and a
+ * Promise when one is — callers must treat the result as maybe-async
+ * (`await` works for both).
+ *
+ * @param {Record<string, string>} [headers]
+ * @param {Record<string, unknown>} [body]
+ * @param {object} [options]
+ * @param {crypto.KeyObject|Buffer|string|null} [options.trustedPublicKey] - merchant-configured
+ *   out-of-band-trusted key. When set it is used instead of deriving one from
+ *   a did:key issuer, and the broader algorithm set is permitted.
+ * @param {string} [options.expectedAudience] - when set, `aud` must match
+ * @param {number} [options.maxMandateLifetimeSec=3600] - maximum allowed `exp - iat`
+ * @param {boolean} [options.requireJti=true]
+ * @param {string[]} [options.requestedCategories] - when set and the mandate
+ *   declares `intentMandate.allowedCategories`, the two must overlap
+ * @param {boolean} [options.allowSelfCertifying=true] - when false, did:key
+ *   mandates (which anyone can mint for any budget) are rejected in favor of
+ *   the merchant-trusted key
+ * @param {string} [options.expectedCurrency] - pins the currency budgets are
+ *   denominated in
+ * @param {boolean} [options.requireCurrency=true] - reject a mandate that
+ *   declares a `maxBudget` with no `currency`. A budget without a unit is
+ *   forgeable by relabeling, and EVERY currency check was previously
+ *   conditional on the mandate declaring one.
+ * @param {number} [options.clockSkewSec=60] - tolerance for `iat`/`exp`
+ * @param {boolean} [options.consumeJti=true] - when false the mandate is
+ *   verified WITHOUT consuming its single-use jti (used for mandates riding
+ *   along on non-AP2 routes so they do not burn themselves)
+ * @param {string|null} [options.expectedCartHash=null] - the merchant-computed
+ *   canonical cart hash. When the mandate carries a `cartMandate.cartHash` the
+ *   two must match: the human signed THAT exact cart, not this one.
+ * @param {number} [options.nowMs] - injectable clock for tests
+ * @returns {object|Promise<object>}
+ */
+export function verifyAp2Mandate(headers = {}, body = {}, options = {}) {
+  const {
+    trustedPublicKey = null,
+    expectedAudience = null,
+    maxMandateLifetimeSec = 3600,
+    requireJti = true,
+    requestedCategories = null,
+    allowSelfCertifying = true,
+    expectedCurrency = null,
+    requireCurrency = true,
+    clockSkewSec = DEFAULT_CLOCK_SKEW_SEC,
+    consumeJti = true,
+    expectedCartHash = null,
+    nowMs = Date.now(),
+  } = options;
+
+  const mandateHeader = headers['x-ap2-mandate'] || headers['authorization'];
+  if (!mandateHeader) {
+    // AP2 simply isn't in use for this request - not a security decision.
+    return { valid: true, protocol: 'AP2', verified: false, note: 'No AP2 Mandates attached' };
+  }
+
+  // --- Envelope parsing (strict) ---
+  const token = String(mandateHeader).replace(/^Bearer\s+/i, '').trim();
+  if (token.length === 0 || token.length > MAX_MANDATE_TOKEN_LENGTH) {
+    return rejectMandate('mandate_malformed', 'Invalid AP2 Mandate SD-JWT format');
+  }
+  if (token.includes('~')) {
+    // SD-JWT selective disclosure is not implemented. Silently ignoring the
+    // disclosure segments (as `split('.')` did) means verifying a subset of
+    // what the holder presented.
+    return rejectMandate(
+      'sd_jwt_disclosures_unsupported',
+      'AP2 mandates with SD-JWT selective-disclosure segments are not supported by this verifier',
+    );
+  }
+
+  const parts = token.split('.');
+  // Exactly three segments. `>= 3` accepted a 5-segment JWE shape and treated
+  // its third segment as the signature over the first two.
+  if (parts.length !== 3 || !parts.every((part) => COMPACT_JWS_SEGMENT.test(part))) {
+    return rejectMandate('mandate_malformed', 'Invalid AP2 Mandate SD-JWT format');
+  }
+
+  let header;
+  let payload;
+  try {
+    header = JSON.parse(Buffer.from(parts[0], 'base64url').toString('utf8'));
+    payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+  } catch {
+    return rejectMandate('mandate_malformed', 'Invalid AP2 Mandate SD-JWT format');
+  }
+  if (!header || typeof header !== 'object' || Array.isArray(header)) {
+    return rejectMandate('mandate_malformed', 'Invalid AP2 Mandate SD-JWT format');
+  }
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return rejectMandate('mandate_malformed', 'Invalid AP2 Mandate SD-JWT format');
+  }
+  const signatureB64 = parts[2];
+
+  // --- JOSE header sanity ---
+  if (header.typ !== undefined && !['jwt', 'sd-jwt'].includes(String(header.typ).toLowerCase())) {
+    return rejectMandate('typ_unsupported', `Unsupported mandate typ: ${String(header.typ).slice(0, 64)}`);
+  }
+  if (header.crit !== undefined) {
+    // `crit` means "you MUST understand these extensions". We understand none.
+    return rejectMandate(
+      'crit_unsupported',
+      'AP2 mandate declares critical header extensions that this verifier does not implement',
+    );
+  }
+  if (typeof header.alg !== 'string' || header.alg.length === 0) {
+    return rejectMandate('alg_missing', 'Missing alg in mandate header');
+  }
+  // `alg: none` and friends: only registered asymmetric algorithms exist here,
+  // so an unknown value can never reach the crypto call.
+  if (!JWS_ALGORITHMS[header.alg]) {
+    return rejectMandate('alg_unsupported', `Unsupported signature algorithm: ${String(header.alg).slice(0, 32)}`);
+  }
+
+  // --- Required claims present ---
+  if (!payload.iss || typeof payload.iss !== 'string') return rejectMandate('claim_missing', 'Missing issuer');
+  if (!payload.aud || typeof payload.aud !== 'string') return rejectMandate('claim_missing', 'Missing audience');
+  if (typeof payload.iat !== 'number' || !Number.isFinite(payload.iat)) {
+    return rejectMandate('claim_missing', 'Missing iat');
+  }
+  if (typeof payload.exp !== 'number' || !Number.isFinite(payload.exp)) {
+    return rejectMandate('claim_missing', 'Missing exp');
+  }
+  if (requireJti && !payload.jti) {
+    return rejectMandate('claim_missing', 'Missing jti (required for replay protection)');
+  }
+  if (payload.jti !== undefined && (typeof payload.jti !== 'string' || !JTI_PATTERN.test(payload.jti))) {
+    // The jti becomes a replay-cache key; an unbounded value became an
+    // unbounded Redis key.
+    return rejectMandate('jti_invalid', 'Mandate jti must be 8-256 printable ASCII characters');
+  }
+  if (payload.nbf !== undefined) {
+    if (typeof payload.nbf !== 'number' || !Number.isFinite(payload.nbf)) {
+      return rejectMandate('claim_missing', 'Invalid nbf');
+    }
+  }
+
+  // --- Temporal validity (with clock-skew tolerance) ---
+  const now = Math.floor(nowMs / 1000);
+  const skew = Number.isFinite(clockSkewSec) && clockSkewSec >= 0 ? Math.floor(clockSkewSec) : 0;
+  if (payload.exp < now - skew) return rejectMandate('expired', 'Token expired');
+  if (payload.iat > now + skew) return rejectMandate('future', 'Token issued in the future');
+  if (payload.nbf !== undefined && payload.nbf > now + skew) {
+    return rejectMandate('not_yet_valid', 'Token is not yet valid');
+  }
+  if (payload.exp - payload.iat > maxMandateLifetimeSec) {
+    return rejectMandate(
+      'lifetime_exceeded',
+      `Mandate lifetime exceeds maximum allowed (${maxMandateLifetimeSec}s)`,
+    );
+  }
+
+  // --- Resolve verification key + algorithm policy ---
+  let publicKey = null;
+  let usingSelfCertifyingKey = false;
+
+  const isDidKeyIssuer = payload.iss.startsWith('did:key:');
+  if (!allowSelfCertifying && isDidKeyIssuer) {
+    return rejectMandate(
+      'self_certifying_disabled',
+      'Self-certifying did:key mandates are disabled for this store; a merchant-trusted public key is required',
+    );
+  }
+
+  if (trustedPublicKey) {
+    try {
+      publicKey = trustedPublicKey instanceof crypto.KeyObject
+        ? trustedPublicKey
+        : crypto.createPublicKey(trustedPublicKey);
+    } catch {
+      return rejectMandate('trusted_key_invalid', 'Configured trusted public key is invalid', { disclose: false });
+    }
+    // Pin the declared algorithm to the actual key. An allow-list check alone
+    // let an attacker shop algorithms against an unrelated key.
+    const incompatibility = keyIncompatibility(publicKey, header.alg);
+    if (incompatibility) {
+      return rejectMandate('alg_key_mismatch', incompatibility, {
+        disclose: false,
+        publicReason: 'The mandate signature algorithm is not accepted by this store.',
+      });
+    }
+  } else if (isDidKeyIssuer) {
+    usingSelfCertifyingKey = true;
+    if (header.alg !== 'EdDSA') {
+      return rejectMandate('didkey_alg', 'did:key issuers require the EdDSA algorithm');
+    }
+    publicKey = ed25519PublicKeyFromDidKey(payload.iss);
+    if (!publicKey) {
+      return rejectMandate('didkey_invalid', 'Issuer is not a valid Ed25519 did:key identifier');
+    }
+  } else {
+    // No merchant-trusted key configured, and the issuer isn't a
+    // self-certifying did:key we can derive a key from - there is no way to
+    // verify this mandate, so it must be rejected rather than passed through
+    // as "valid but unverified".
+    return rejectMandate(
+      'unverifiable',
+      'Cannot verify mandate: issuer is not a did:key and no trusted public key is configured',
+    );
+  }
+
+  // --- Signature verification (mandatory) ---
+  try {
+    const signingInput = Buffer.from(`${parts[0]}.${parts[1]}`, 'utf8');
+    const signature = Buffer.from(signatureB64, 'base64url');
+    if (!verifyJwsSignature(header.alg, publicKey, signingInput, signature)) {
+      return rejectMandate('signature_invalid', 'Invalid signature');
+    }
+  } catch (err) {
+    // Raw crypto error text used to be echoed to the caller verbatim.
+    return rejectMandate('signature_error', `Signature verification failed: ${err.message}`, {
+      disclose: false,
+      publicReason: 'Invalid signature',
+    });
+  }
+
+  // --- Audience binding ---
+  if (expectedAudience && !audienceMatches(payload.aud, expectedAudience)) {
+    return rejectMandate(
+      'audience_mismatch',
+      `Mandate audience "${payload.aud}" does not match this store ("${expectedAudience}")`,
+      { disclose: false, publicReason: 'This mandate was issued for a different store.' },
+    );
+  }
+
+  // --- merchantScope binding (if the mandate declares one, it must match) ---
+  const merchantScope = payload.intentMandate?.merchantScope;
+  if (expectedAudience && merchantScope && !audienceMatches(merchantScope, expectedAudience)) {
+    return rejectMandate(
+      'merchant_scope_mismatch',
+      `Mandate merchantScope "${merchantScope}" does not match this store ("${expectedAudience}")`,
+      { disclose: false, publicReason: 'This mandate is scoped to a different merchant.' },
+    );
+  }
+
+  return finishVerification();
+
+  /**
+   * Everything after signature/audience verification. The jti claim is the
+   * LAST step so a rejected attempt (over budget, wrong category, wrong cart)
+   * never burns the mandate and the corrected retry still works.
+   *
+   * Maybe-async: returns a Promise only when a shared replay store makes the
+   * claim asynchronous.
+   */
+  function finishVerification() {
+    // --- Cart Mandate binding ---
+    // A signed cartMandate.cartHash means the human approved one exact cart.
+    // When the merchant can recompute its own canonical hash, a mismatch is a
+    // hard reject: swapping cart contents under a signed approval must fail.
+    const rawClaimedCartHash = payload.cartMandate?.cartHash;
+    const claimedCartHash = typeof rawClaimedCartHash === 'string' ? rawClaimedCartHash.trim() : null;
+    let cartBinding = claimedCartHash ? 'unverified' : 'unbound';
+    if (claimedCartHash && expectedCartHash) {
+      const a = Buffer.from(claimedCartHash, 'utf8');
+      const b = Buffer.from(String(expectedCartHash), 'utf8');
+      if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
+        return rejectMandate(
+          'cart_binding_mismatch',
+          'Cart binding mismatch: the mandate signs a different cart than the one in this session (Cart Mandate verification failed)',
+        );
+      }
+      cartBinding = 'verified';
+    }
+
+    // --- Category enforcement (only when both sides supply one) ---
+    const allowedCategories = payload.intentMandate?.allowedCategories;
+    if (Array.isArray(allowedCategories) && Array.isArray(requestedCategories) && requestedCategories.length > 0) {
+      const allowed = new Set(allowedCategories.filter((entry) => typeof entry === 'string'));
+      const overlaps = requestedCategories.some((category) => allowed.has(category));
+      if (!overlaps) {
+        return rejectMandate(
+          'category_denied',
+          `Requested categories [${requestedCategories.join(', ')}] are not within the mandate's allowedCategories [${allowedCategories.join(', ')}]`,
+        );
+      }
+    }
+
+    // --- Currency binding ---
+    // A budget number without a currency is unitless and forgeable by
+    // relabeling: a "100" cap minted in a low-value currency must not
+    // authorize "100" in the merchant's currency. Every currency check used to
+    // be conditional on the mandate declaring one, so omitting `currency`
+    // bypassed all of them.
+    const rawMandateCurrency = payload.intentMandate?.currency ?? payload.paymentMandate?.currency;
+    const mandateCurrency = normalizeCurrencyCode(rawMandateCurrency);
+    const rawMaxBudget = payload.intentMandate?.maxBudget ?? payload.paymentMandate?.maxBudget;
+    const declaresBudget = rawMaxBudget !== undefined && rawMaxBudget !== null;
+
+    if (rawMandateCurrency !== undefined && rawMandateCurrency !== null && !mandateCurrency) {
+      return rejectMandate(
+        'currency_invalid',
+        `Mandate currency "${String(rawMandateCurrency).slice(0, 16)}" is not a valid ISO 4217 code`,
+      );
+    }
+    if (requireCurrency && declaresBudget && !mandateCurrency) {
+      return rejectMandate(
+        'currency_missing',
+        'Mandate declares a maxBudget with no currency; an amount without a unit cannot be enforced',
+      );
+    }
+    const expected = normalizeCurrencyCode(expectedCurrency);
+    if (expectedCurrency && !expected) {
+      return rejectMandate('store_currency_invalid', 'Configured expectedCurrency is not a valid ISO 4217 code', {
+        disclose: false,
+      });
+    }
+    if (mandateCurrency && expected && mandateCurrency !== expected) {
+      return rejectMandate(
+        'currency_mismatch_store',
+        `Mandate currency "${mandateCurrency}" does not match this store's expected currency "${expected}"`,
+        { disclose: false, publicReason: 'The mandate was issued for a different currency than this store accepts.' },
+      );
+    }
+    const bodyCurrency = body?.currency === undefined || body?.currency === null
+      ? null
+      : normalizeCurrencyCode(body.currency);
+    if (body?.currency !== undefined && body?.currency !== null && !bodyCurrency) {
+      return rejectMandate('order_currency_invalid', 'Order currency is not a valid ISO 4217 code');
+    }
+    if (mandateCurrency && bodyCurrency && mandateCurrency !== bodyCurrency) {
+      return rejectMandate(
+        'currency_mismatch_order',
+        `Order currency "${bodyCurrency}" does not match the mandate's currency "${mandateCurrency}"`,
+      );
+    }
+
+    // --- Budget enforcement (convenience pre-check) ---
+    // The authoritative check runs at the /ap2/checkout call site against the
+    // merchant-computed total; this one only lets an obviously-over-budget
+    // request fail before any handler runs.
+    if (declaresBudget) {
+      const budget = parseAmount(rawMaxBudget, { allowZero: true });
+      if (budget === null) {
+        return rejectMandate(
+          'budget_invalid',
+          'Mandate maxBudget is not a valid non-negative amount',
+        );
+      }
+      if (body?.orderTotal !== undefined && body?.orderTotal !== null) {
+        const orderTotal = parseAmount(body.orderTotal, { allowZero: true });
+        // `Number('abc')` is NaN and `NaN > budget` is false, so a malformed
+        // total used to PASS this check. It now fails.
+        if (orderTotal === null) {
+          return rejectMandate('order_total_invalid', 'Order total is not a valid non-negative amount');
+        }
+        if (compareAmounts(orderTotal.decimal, budget.decimal) === 1) {
+          return rejectMandate('budget_exceeded', 'Order total exceeds Intent Mandate maxBudget limit');
+        }
+      }
+    }
+
+    const replayRejection = () => rejectMandate(
+      'replay',
+      'Mandate has already been used (replay detected)',
+    );
+
+    // --- Consume the jti: every validation above passed, so winning the
+    // atomic claim is the single successful use of this mandate. ---
+    if (payload.jti && consumeJti) {
+      const claimed = seenMandateJtis.claim(payload.jti, payload.exp * 1000);
+      if (typeof claimed === 'boolean') {
+        if (!claimed) return replayRejection();
+      } else {
+        return claimed.then((won) => (won ? buildSuccess() : replayRejection()));
+      }
+    }
+
+    return buildSuccess();
+
+    function buildSuccess() {
+      return {
+        valid: true,
+        protocol: 'AP2',
+        verified: true,
+        selfCertifying: usingSelfCertifyingKey,
+        cartBinding,
+        currency: mandateCurrency,
+        maxBudget: declaresBudget ? rawMaxBudget : undefined,
+        algorithm: header.alg,
+        // A curated projection, not the raw attacker-supplied payload.
+        mandates: projectMandate(payload),
+      };
+    }
+  }
+}
+
+/**
+ * Builds and signs a complete AP2 Intent+Payment Mandate SD-JWT for
+ * agent-side tooling (test harnesses, demos, or a real agent's own wallet
+ * integration). The issuer is a did:key derived from the signing keypair, so
+ * the resulting mandate self-certifies without any prior key registration.
+ *
+ * @param {object} options
+ * @param {string} options.audience - the store base URL this mandate authorizes (required)
+ * @param {number|string} options.maxBudget - spending cap enforced on checkout (required, > 0)
+ * @param {string} [options.currency='USD']
+ * @param {string[]} [options.allowedCategories]
+ * @param {string} [options.merchantScope] - defaults to `audience`
+ * @param {number} [options.lifetimeSec=3600] - capped at 24 hours
+ * @param {string} [options.paymentMethod='tokenized_card']
+ * @param {string} [options.subject='user_wallet_delegation']
+ * @param {boolean} [options.agentInitiated]
+ * @param {{ items: Array<object>, currency?: string }} [options.cart] - embeds a
+ *   Cart Mandate binding this mandate to one exact cart
+ * @param {string} [options.cartHash] - precomputed hash, used when `cart` is absent
+ * @param {crypto.KeyObject} [options.privateKey] - reuse an Ed25519 private key
+ * @returns {{ token: string, did: string, publicKey: crypto.KeyObject, privateKey: crypto.KeyObject, cartHash: string|null, maxBudget: string, audience: string, expiresAt: number }}
+ */
+export function createAp2Mandate(options = {}) {
+  const {
+    audience,
+    maxBudget,
+    currency = 'USD',
+    allowedCategories,
+    merchantScope,
+    lifetimeSec = 3600,
+    paymentMethod = 'tokenized_card',
+    subject = 'user_wallet_delegation',
+    agentInitiated,
+    cart,
+    cartHash: providedCartHash,
+    privateKey: providedPrivateKey,
+  } = options;
+
+  if (typeof audience !== 'string' || audience.trim() === '') {
+    throw new Error('createAp2Mandate requires an `audience` (the target store base URL)');
+  }
+  if (maxBudget === undefined) throw new Error('createAp2Mandate requires a `maxBudget`');
+
+  // A capless or malformed budget is rejected at mint time rather than at
+  // checkout, so a broken mandate never reaches a payment gate.
+  const budget = parseAmount(maxBudget, { allowZero: false });
+  if (budget === null) {
+    throw new Error('createAp2Mandate requires a positive numeric `maxBudget`');
+  }
+  const normalizedCurrency = normalizeCurrencyCode(currency);
+  if (!normalizedCurrency) {
+    throw new Error(`createAp2Mandate requires a valid ISO 4217 \`currency\`, got "${currency}"`);
+  }
+  if (!Number.isFinite(lifetimeSec) || lifetimeSec <= 0 || lifetimeSec > 24 * 60 * 60) {
+    throw new Error('createAp2Mandate `lifetimeSec` must be between 1 second and 24 hours');
+  }
+
+  // Cart Mandate binding: embed the exact-cart fingerprint when a cart (or a
+  // precomputed hash) is supplied.
+  let cartHash = typeof providedCartHash === 'string' && providedCartHash.trim() ? providedCartHash.trim() : null;
+  let cartBindingMeta = null;
+  if (cart) {
+    const canonical = canonicalCartHash({ currency: normalizedCurrency, items: cart.items });
+    cartHash = canonical.cartHash;
+    cartBindingMeta = canonical;
+    // A cart whose own total exceeds the cap it is minted with is
+    // self-contradictory; catching it here saves a doomed checkout.
+    const cartTotalMajor = (canonical.totalCents / 100).toFixed(2);
+    if (compareAmounts(cartTotalMajor, budget.decimal) === 1) {
+      throw new Error(
+        `createAp2Mandate: the cart total ${cartTotalMajor} exceeds the requested maxBudget ${budget.decimal}`,
+      );
+    }
+  }
+
+  const { privateKey, publicKey } = providedPrivateKey
+    ? { privateKey: providedPrivateKey, publicKey: crypto.createPublicKey(providedPrivateKey) }
+    : crypto.generateKeyPairSync('ed25519');
+
+  const did = didKeyFromEd25519PublicKey(publicKey);
+  const iat = Math.floor(Date.now() / 1000);
+  const exp = iat + Math.floor(lifetimeSec);
+
+  const header = { alg: 'EdDSA', typ: 'JWT' };
+  const payload = {
+    iss: did,
+    aud: audience,
+    sub: subject,
+    iat,
+    exp,
+    jti: crypto.randomUUID(),
+    intentMandate: {
+      maxBudget,
+      currency: normalizedCurrency,
+      merchantScope: merchantScope || audience,
+      ...(allowedCategories ? { allowedCategories } : {}),
+    },
+    ...(cartBindingMeta
+      ? {
+        cartMandate: {
+          cartHash,
+          itemCount: cartBindingMeta.itemCount,
+          totalCents: cartBindingMeta.totalCents,
+          currency: normalizedCurrency,
+        },
+      }
+      : cartHash
+        ? { cartMandate: { cartHash } }
+        : {}),
+    paymentMandate: {
+      paymentMethod,
+      currency: normalizedCurrency,
+      ...(agentInitiated !== undefined ? { agentInitiated: Boolean(agentInitiated) } : {}),
+    },
+  };
+
+  const encodedHeader = Buffer.from(JSON.stringify(header)).toString('base64url');
+  const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const signingInput = `${encodedHeader}.${encodedPayload}`;
+  const signature = crypto.sign(null, Buffer.from(signingInput), privateKey).toString('base64url');
+
+  return {
+    token: `${signingInput}.${signature}`,
+    did,
+    publicKey,
+    privateKey,
+    cartHash,
+    maxBudget: budget.decimal,
+    audience,
+    expiresAt: exp,
+  };
+}