@agentsbloom/sdk 0.4.0 → 0.5.0

package/index.js

@@ -1,1995 +1,2352 @@
-import zlib from 'zlib';
-import crypto from 'crypto';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-import { trace, metrics, ValueType, context, propagation } from '@opentelemetry/api';
-import { initExporter } from './telemetry.js';
-import {
-  verifyAp2Mandate,
-  createAp2Mandate,
-  didKeyFromEd25519PublicKey,
-  ed25519PublicKeyFromDidKey,
-  resetAp2ReplayCache,
-  stopAp2ReplayCleanup,
-} from './lib/ap2.js';
+import zlib from 'zlib';
+import crypto from 'crypto';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+// `setRequestHandler` takes a Zod request SCHEMA, not a method-name string.
+// Passing the strings 'tools/list' / 'tools/call' made the MCP SDK throw
+// `Error: Schema is missing a method literal` on EVERY `GET /mcp`, so the MCP
+// surface advertised in every discovery document was completely non-functional.
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { trace, metrics, ValueType, context, propagation } from '@opentelemetry/api';
+import { initExporter } from './telemetry.js';
+import {
+  verifyAp2Mandate,
+  createAp2Mandate,
+  didKeyFromEd25519PublicKey,
+  ed25519PublicKeyFromDidKey,
+  resetAp2ReplayCache,
+  stopAp2ReplayCleanup,
+  canonicalCartHash,
+  stableStringify,
+  normalizeAudience,
+  SUPPORTED_MANDATE_ALGORITHMS,
+} from './lib/ap2.js';
 import { createReplayCache } from './lib/shared-store.js';
-import { createOutcomeReporter, stripeEventToOutcome } from './lib/outcomes.js';
-
-const tracer = trace.getTracer('agentsbloom-sdk');
-const meter = metrics.getMeter('agentsbloom-sdk');
-
-const agentRequestsCounter = meter.createCounter('agent_visits_total', { description: 'Total AI Visits' });
-const agentRevenueCounter = meter.createCounter('agent_revenue_usd', { description: 'Total AI Revenue', valueType: ValueType.DOUBLE });
-
-/**
- * Initialize OpenTelemetry with OTLP exporters.
- * Call this BEFORE using the agentsbloom() middleware.
- * 
- * @param {Object} options
- * @param {string} options.otlpEndpoint - OTLP collector URL (default: http://localhost:4318)
- * @param {string} options.serviceName - Service name for traces (default: agentsbloom-merchant)
- * @param {number} options.samplingRatio - Trace sampling ratio 0.0-1.0 (default: 1.0)
- * @param {string} options.apiKey - API key for authenticating with the collector
- */
-export async function setupTelemetry(options = {}) {
-  const {
-    otlpEndpoint = process.env.AGENTSBLOOM_OTEL_ENDPOINT || 'http://localhost:4318',
-    serviceName = 'agentsbloom-merchant',
-    samplingRatio = parseFloat(process.env.AGENTSBLOOM_SAMPLING_RATIO || '1.0'),
-    apiKey = process.env.AGENTSBLOOM_API_KEY || '',
-  } = options;
-
-  // Store config for lazy initialization when OTel SDK packages are available
-  globalThis.__agentsbloom_otel_config = {
-    otlpEndpoint,
-    serviceName,
-    samplingRatio,
-    apiKey,
-  };
-
-  const handle = await initExporter({ otlpEndpoint, serviceName, samplingRatio, apiKey });
-  globalThis.__agentsbloom_otel_handle = handle;
-
-  console.log(`🌸 AgentsBloom: Telemetry configured (sampling: ${samplingRatio * 100}%)`);
-  return { otlpEndpoint, serviceName, samplingRatio };
-}
-// v4 security hardening: there is deliberately NO default RFC 9421 JWKS
-// source anymore. The previous default pointed at a third-party provider's
-// live key set, which silently accepted that provider's signing keys for
-// MERCHANT write actions whenever a merchant forgot to configure their own
-// trust root. Verification now fails closed until the merchant configures
-// `agentJwks` (inline JWKS object) or `agentJwksUrl` (HTTPS JWKS endpoint).
-const LEGACY_SIGNATURE_MAX_AGE_MS = 5 * 60 * 1000;
-const RFC_SIGNATURE_CLOCK_SKEW_MS = 30 * 1000;
-const SIGNATURE_REPLAY_CACHE_MAX_SIZE = 50_000;
-const MAX_RATE_TRACKED_CLIENTS = 50_000;
-// Second-pass review: the JWKS cache was an unswept Map keyed by
-// (config, keyid) - attacker-controlled keyids grew it without bound, and
-// every UNKNOWN keyid triggered a live JWKS fetch (5s timeout), turning
-// cheap requests into outbound-request amplification. The cache is now
-// bounded, swept, and unknown keyids are negatively cached briefly so
-// repeated junk kids cost one lookup instead of one network fetch each.
-const JWKS_CACHE_MAX_ENTRIES = 500;
-const JWKS_NEGATIVE_TTL_MS = 60 * 1000;
-const jwksCache = new Map();
-
-/** Returns the cached JWKS entry (positive or negative) or null. Sweeps lazily. */
-function jwksCacheGet(cacheKey) {
-  const entry = jwksCache.get(cacheKey);
-  if (!entry) return null;
-  if (entry.expires <= Date.now()) {
-    jwksCache.delete(cacheKey);
-    return null;
-  }
-  return entry;
-}
-
-/** Bounded insert: sweep expired first, then evict the oldest-tracked entry. */
-function jwksCachePut(cacheKey, entry) {
-  if (jwksCache.size >= JWKS_CACHE_MAX_ENTRIES) {
-    const now = Date.now();
-    for (const [key, value] of jwksCache.entries()) {
-      if (value.expires <= now) jwksCache.delete(key);
-    }
-    if (jwksCache.size >= JWKS_CACHE_MAX_ENTRIES) {
-      const oldestKey = jwksCache.keys().next().value;
-      if (oldestKey !== undefined) jwksCache.delete(oldestKey);
-    }
-  }
-  jwksCache.set(cacheKey, entry);
-}
-
-/** Escapes JSON for embedding inside an HTML <script> element. */
-function toSafeJson(value) {
-  return JSON.stringify(value)
-    .replace(/</g, '\\u003c')
-    .replace(/>/g, '\\u003e')
-    .replace(/&/g, '\\u0026')
-    .replace(/\u2028/g, '\\u2028')
-    .replace(/\u2029/g, '\\u2029');
-}
-
-/**
- * Normalizes a client key for rate limiting: strips the IPv6-mapped IPv4
- * prefix (::ffff:127.0.0.1 -> 127.0.0.1) so the same client cannot get a
- * fresh bucket by alternating address representations.
- */
-function normalizeRateLimitKey(ip) {
-  const raw = String(ip || '');
-  return raw.startsWith('::ffff:') ? raw.slice(7) : raw;
-}
-
-function verifySignature(signature, payload, secret) {
-  try {
-    if (typeof signature !== 'string' || !/^[a-f0-9]{64}$/i.test(signature)) return false;
-    const computed = crypto.createHmac('sha256', secret).update(payload).digest();
-    const provided = Buffer.from(signature, 'hex');
-    return crypto.timingSafeEqual(computed, provided);
-  } catch {
-    return false;
-  }
-}
-
-function buildLegacySignaturePayload(req, identifier, timestamp, nonce) {
-  return JSON.stringify([
-    identifier,
-    String(req.method || '').toUpperCase(),
-    req.originalUrl || req.path,
-    timestamp,
-    nonce,
-    req.body ?? null,
-  ]);
-}
-
-function buildRequestContentDigest(req) {
-  let bodyBytes;
-  if (req.rawBody !== undefined) {
-    bodyBytes = Buffer.isBuffer(req.rawBody) ? req.rawBody : Buffer.from(String(req.rawBody));
-  } else if (Buffer.isBuffer(req.body)) {
-    bodyBytes = req.body;
-  } else if (req.body !== undefined) {
-    bodyBytes = Buffer.from(JSON.stringify(req.body ?? null));
-  } else {
-    const contentLength = Number(req.headers['content-length'] || 0);
-    if (contentLength > 0) {
-      throw new Error('Protected HTTP signatures require parsed request bodies or req.rawBody');
-    }
-    bodyBytes = Buffer.alloc(0);
-  }
-
-  const digest = crypto.createHash('sha256').update(bodyBytes).digest('base64');
-  return `sha-256=:${digest}:`;
-}
-
-/**
- * v4: validates/coerces action parameters against the action's declared
- * `params` type map. Shared by the REST action route AND the MCP tools/call
- * handler - previously the MCP path passed arguments straight through with
- * no validation at all, so the type guarantees advertised in discovery
- * documents were not actually enforced there.
- *
- * @returns {{ ok: boolean, params?: object, message?: string }}
- */
-function validateActionParams(rawParams, action) {
-  const params = { ...rawParams };
-  if (!action.params) return { ok: true, params };
-  for (const [key, type] of Object.entries(action.params)) {
-    const val = params[key];
-    if (val === undefined) continue;
-    if (type === 'any') continue;
-    if (type === 'number') {
-      if (typeof val === 'number' && !isNaN(val)) {
-        // valid
-      } else if (typeof val === 'string' && val.trim() !== '' && !isNaN(Number(val))) {
-        params[key] = Number(val);
-      } else {
-        return { ok: false, message: `Expected ${type} for parameter ${key}` };
-      }
-    } else if (type === 'boolean') {
-      if (typeof val === 'boolean') {
-        // valid
-      } else if (typeof val === 'string' && (val === 'true' || val === 'false' || val === '1' || val === '0')) {
-        params[key] = val === 'true' || val === '1';
-      } else {
-        return { ok: false, message: `Expected ${type} for parameter ${key}` };
-      }
-    } else if (type === 'string') {
-      if (typeof val !== 'string') {
-        return { ok: false, message: `Expected ${type} for parameter ${key}` };
-      }
-    } else if (typeof val !== type && !(typeof type === 'string' && type.includes(typeof val))) {
-      return { ok: false, message: `Expected ${type} for parameter ${key}` };
-    }
-  }
-  return { ok: true, params };
-}
-
-// In-memory rate limiting map
-const rateLimitMap = new Map();
-// v4: bounded count of live MCP SSE sessions (see /mcp handler).
-let activeMcpSessions = 0;
-
-// --- v4 medium pass (V15): the SaaS quota gate is now WIRED ---
-// Previously `quotaExceededUntil` was a per-instance variable initialized
-// to 0 that nothing ever set - dead code implying enforcement that did not
-// exist. The hosted gateway (or any operator tooling) can now trip every
-// middleware instance in the process via setQuotaExceededUntil(), or set
-// AGENTSBLOOM_QUOTA_EXCEEDED_UNTIL (epoch ms) in the environment.
-let quotaExceededUntilMs = Number(process.env.AGENTSBLOOM_QUOTA_EXCEEDED_UNTIL || 0) || 0;
-
-/** Marks quota exceeded process-wide until the given epoch-ms timestamp. */
-export function setQuotaExceededUntil(untilEpochMs) {
-  const value = Number(untilEpochMs);
-  quotaExceededUntilMs = Number.isFinite(value) ? value : 0;
-}
-
-/** Clears the process-wide quota-exceeded state immediately. */
-export function clearQuotaExceeded() {
-  quotaExceededUntilMs = 0;
-}
-const rateLimitInterval = setInterval(() => {
-  const now = Date.now();
-  for (const [key, val] of rateLimitMap.entries()) {
-    if (val.resetTime < now) rateLimitMap.delete(key);
-  }
-}, 60 * 1000);
-rateLimitInterval.unref();
-
-// In-memory Idempotency cache (per-instance optimization; order-level
-// idempotency is enforced downstream by deterministic order refs).
-// Signature nonces live in a replay cache that becomes cluster-wide when
-// an Upstash REST endpoint is configured (lib/shared-store.js).
-const idempotencyMap = new Map();
-const signatureNonceMap = createReplayCache('agentsbloom:sig:nonce', SIGNATURE_REPLAY_CACHE_MAX_SIZE);
-const idempotencyInterval = setInterval(() => {
-  const now = Date.now();
-  for (const [key, val] of idempotencyMap.entries()) {
-    if (val.expiry < now) idempotencyMap.delete(key);
-  }
-}, 60 * 1000);
-idempotencyInterval.unref();
-
-let otelShutdownPromise = null;
-
-// --- OpenAPI 3.1 document generation ---
-//
-// Generated from the merchant's declared actions so every action the store
-// actually mounts appears in /openapi.json. Well-known commerce actions
-// keep their curated, example-rich schemas; anything else a merchant
-// declares is derived from its `params` type map. AP2 and protocol
-// discovery endpoints are documented alongside the REST surface, and the
-// security schemes describe the exact headers RFC 9421 / legacy /
-// AP2 callers must send.
-
-const OPENAPI_PARAM_TYPE_MAP = {
-  string: 'string',
-  number: 'number',
-  integer: 'integer',
-  boolean: 'boolean',
-  any: null, // schema-less when the action accepts anything
-};
-
-function openApiSchemaForParamType(type) {
-  const mapped = OPENAPI_PARAM_TYPE_MAP[type];
-  return mapped ? { type: mapped } : {};
-}
-
-/** Common error responses referenced via $ref from every generated operation. */
-function openApiErrorRefs() {
-  return {
-    "401": { $ref: '#/components/responses/VerificationRequired' },
-    "403": { $ref: '#/components/responses/Forbidden' },
-    "429": { $ref: '#/components/responses/RateLimited' },
-  };
-}
-
-/** Curated, example-rich entries for the canonical commerce actions. */
-function curatedOpenApiPaths() {
-  return {
-    "/api/agentsbloom/products": {
-      get: {
-        operationId: "listProducts",
-        summary: "Retrieve product catalog or filter by category/query",
-        parameters: [
-          { name: "category", in: "query", schema: { type: "string" }, description: "Category filter (e.g. shoes, apparel, accessories, electronics, home, books)" },
-          { name: "query", in: "query", schema: { type: "string" }, description: "Search term" },
-          { name: "limit", in: "query", schema: { type: "integer" }, description: "Maximum products to return" }
-        ],
-        responses: { "200": { description: "List of matching products with price, sizes, stock, rating" }, ...openApiErrorRefs() }
-      }
-    },
-    "/api/agentsbloom/search": {
-      get: {
-        operationId: "searchProducts",
-        summary: "Search products by natural language query",
-        parameters: [
-          { name: "query", in: "query", schema: { type: "string" }, description: "Product name or search keywords" },
-          { name: "category", in: "query", schema: { type: "string" }, description: "Category filter" }
-        ],
-        responses: { "200": { description: "Search results with count and product details" }, ...openApiErrorRefs() }
-      }
-    },
-    "/api/agentsbloom/cart": {
-      get: {
-        operationId: "getCart",
-        summary: "Retrieve current cart contents and total price",
-        responses: { "200": { description: "Cart items, item count, and price breakdown" }, ...openApiErrorRefs() }
-      }
-    },
-    "/api/agentsbloom/addToCart": {
-      post: {
-        operationId: "addToCart",
-        summary: "Add a product variant to cart",
-        security: [{ HttpSignatureAuth: [] }, { LegacyAgentSignature: [] }],
-        requestBody: {
-          required: true,
-          content: {
-            "application/json": {
-              schema: {
-                type: "object",
-                required: ["productId"],
-                properties: {
-                  productId: { type: "string", description: "Product ID (e.g. puma-velocity-3, trail-master-x2, agent-pro-backpack)" },
-                  size: { type: "string", description: "Product size or variant (e.g. 10, M, One Size)" },
-                  quantity: { type: "integer", default: 1, description: "Quantity to add" }
-                }
-              }
-            }
-          }
-        },
-        responses: { "200": { description: "Success confirmation and updated cart size" }, ...openApiErrorRefs() }
-      }
-    },
-    "/api/agentsbloom/checkout": {
-      post: {
-        operationId: "checkout",
-        summary: "Create a secure checkout link for payment",
-        security: [{ HttpSignatureAuth: [] }, { LegacyAgentSignature: [] }],
-        requestBody: {
-          required: false,
-          content: {
-            "application/json": {
-              schema: {
-                type: "object",
-                properties: {
-                  address: { type: "string", description: "Customer shipping destination address" },
-                  gateway: { type: "string", default: "stripe", description: "Payment gateway: stripe, razorpay, or paddle" }
-                }
-              }
-            }
-          }
-        },
-        responses: { "200": { description: "Secure payment URL and session ID" }, ...openApiErrorRefs() }
-      }
-    }
-  };
-}
-
-/** Derives an operation entry for any declared action from its params map. */
-function openApiOperationForAction(key, action, signatureAuthEnabled) {
-  const httpMethod = String(action.method || 'POST').toLowerCase();
-  const isWrite = ['post', 'put', 'patch', 'delete'].includes(httpMethod);
-  const paramSchema = {
-    type: "object",
-    properties: Object.fromEntries(
-      Object.entries(action.params || {}).map(([pkey, pval]) => [pkey, openApiSchemaForParamType(pval)])
-    ),
-  };
-
-  const operation = {
-    operationId: key,
-    summary: action.description || key,
-    ...(isWrite && signatureAuthEnabled
-      ? { security: [{ HttpSignatureAuth: [] }, { LegacyAgentSignature: [] }] }
-      : {}),
-    ...(httpMethod === 'get'
-      ? {
-          parameters: Object.entries(action.params || {}).map(([pkey, pval]) => ({
-            name: pkey,
-            in: "query",
-            schema: openApiSchemaForParamType(pval),
-          })),
-        }
-      : {
-          requestBody: {
-            required: true,
-            content: { "application/json": { schema: paramSchema } },
-          },
-        }),
-    responses: {
-      "200": { description: action.description ? `${action.description} result` : `${key} result` },
-      ...openApiErrorRefs(),
-    },
-  };
-
-  return { [httpMethod]: operation };
-}
-
-/**
- * Builds the full OpenAPI 3.1 document: generated action paths, curated
- * canonical entries, AP2 endpoints, discovery endpoints, reusable security
- * schemes, and error responses.
- */
-function buildOpenApiDocument({ name, description, requestUrl, actions = {}, signatureAuthEnabled = true }) {
-  const paths = {};
-
-  // Every declared action gets a path (curated entries override generated
-  // ones for the canonical five).
-  for (const [key, action] of Object.entries(actions)) {
-    paths[`/api/agentsbloom/${key}`] = openApiOperationForAction(key, action, signatureAuthEnabled);
-  }
-  Object.assign(paths, curatedOpenApiPaths());
-
-  // AP2 protocol surface.
-  paths["/ap2/capabilities"] = {
-    get: {
-      operationId: "ap2Capabilities",
-      summary: "AP2 capabilities, mandate types, and verification methods",
-      responses: { "200": { description: "AP2 capability document" }, ...openApiErrorRefs() },
-    },
-  };
-  paths["/ap2/intent"] = {
-    post: {
-      operationId: "ap2Intent",
-      summary: "Announce purchase intent with a verified AP2 Intent Mandate",
-      security: [{ Ap2MandateAuth: [] }],
-      requestBody: {
-        required: false,
-        content: {
-          "application/json": {
-            schema: {
-              type: "object",
-              properties: {
-                requestedCategories: { type: "array", items: { type: "string" }, description: "Cart categories the intent covers" },
-              },
-            },
-          },
-        },
-      },
-      responses: {
-        "200": { description: "Intent accepted with mandate verification evidence" },
-        "401": { $ref: '#/components/responses/VerificationRequired' },
-        "403": { $ref: '#/components/responses/Forbidden' },
-      },
-    },
-  };
-  paths["/ap2/checkout"] = {
-    post: {
-      operationId: "ap2Checkout",
-      summary: "Mandate-gated checkout: creates a payment URL only when a verified AP2 mandate with a positive maxBudget covers the order total",
-      security: [{ Ap2MandateAuth: [] }],
-      requestBody: {
-        required: true,
-        content: {
-          "application/json": {
-            schema: {
-              type: "object",
-              required: ["orderTotal"],
-              properties: {
-                orderTotal: { type: "number", description: "Order total that must be covered by the mandate's maxBudget" },
-                address: { type: "string", description: "Customer shipping destination address" },
-                gateway: { type: "string", default: "stripe", description: "Payment gateway: stripe, razorpay, or paddle" },
-              },
-            },
-          },
-        },
-      },
-      responses: {
-        "200": { description: "Authorized checkout with payment URL, session id, and budget-enforcement evidence" },
-        "401": { $ref: '#/components/responses/VerificationRequired' },
-        "403": { $ref: '#/components/responses/Forbidden' },
-      },
-    },
-  };
-
-  // Protocol discovery surface.
-  paths["/.well-known/agent-spec"] = {
-    get: {
-      operationId: "agentSpec",
-      summary: "Legacy/compatibility discovery document",
-      responses: { "200": { description: "Agent spec manifest" } },
-    },
-  };
-  paths["/.well-known/ucp"] = {
-    get: {
-      operationId: "ucpProfile",
-      summary: "UCP (Universal Commerce Protocol) profile",
-      responses: { "200": { description: "UCP profile with capabilities and endpoint declarations" } },
-    },
-  };
-  paths["/ai-catalog.json"] = {
-    get: {
-      operationId: "aiCatalog",
-      summary: "WebMCP/ARD-style action catalog",
-      responses: { "200": { description: "Action catalog document" } },
-    },
-  };
-  paths["/llms.txt"] = {
-    get: {
-      operationId: "llmsDoc",
-      summary: "LLM-oriented developer guide",
-      responses: { "200": { description: "Plain-text guide for LLM agents" } },
-    },
-  };
-
-  return {
-    openapi: "3.1.0",
-    info: { title: name, description, version: "1.0.0" },
-    servers: [{ url: requestUrl }],
-    // Reads are open; writes carry their own operation-level security.
-    security: [],
-    tags: [
-      { name: "catalog", description: "Product browsing and search" },
-      { name: "cart", description: "Cart operations (write actions require agent signatures)" },
-      { name: "checkout", description: "Checkout link creation" },
-      { name: "ap2", description: "AP2 mandate-gated payment authorization" },
-      { name: "discovery", description: "Protocol discovery documents" },
-    ],
-    paths,
-    components: {
-      securitySchemes: {
-        HttpSignatureAuth: {
-          type: "apiKey",
-          description: "RFC 9421 HTTP Message Signatures: send `Signature` and `Signature-Input` headers; the signature must cover @method, @path, and content-digest for bodied requests, with created/expires/nonce parameters and a keyid resolvable through the configured JWKS.",
-          in: "header",
-          name: "Signature",
-        },
-        LegacyAgentSignature: {
-          type: "apiKey",
-          description: "Legacy HMAC scheme: X-Agent-Signature plus X-Agent-Identifier, X-Agent-Timestamp, X-Agent-Nonce headers, signed with the shared agent secret.",
-          in: "header",
-          name: "X-Agent-Signature",
-        },
-        Ap2MandateAuth: {
-          type: "apiKey",
-          description: "AP2 budget mandate: an SD-JWT with intentMandate.maxBudget, audience-bound to this store, sent as `X-AP2-Mandate: Bearer <sd-jwt>`.",
-          in: "header",
-          name: "X-AP2-Mandate",
-        },
-      },
-      responses: {
-        VerificationRequired: {
-          description: "Credential missing - write actions need an agent signature; AP2 endpoints need a mandate.",
-          content: { "application/json": { schema: { type: "object", properties: { error: { type: "string" }, message: { type: "string" } } } } },
-        },
-        Forbidden: {
-          description: "Credential presented but invalid (bad signature, expired mandate, budget exceeded, wrong audience, replay detected).",
-          content: { "application/json": { schema: { type: "object", properties: { error: { type: "string" }, reason: { type: "string" }, protocol: { type: "string" } } } } },
-        },
-        RateLimited: {
-          description: "Too many requests - respect X-RateLimit-Reset and Retry-After.",
-          content: { "application/json": { schema: { type: "object", properties: { error: { type: "string" }, retryAfter: { type: "number" } } } } },
-        },
-      },
-    },
-  };
-}
-
-
-export async function shutdown() {
-  clearInterval(rateLimitInterval);
-  clearInterval(idempotencyInterval);
-  rateLimitMap.clear();
-  idempotencyMap.clear();
-  signatureNonceMap.clear();
-  jwksCache.clear();
-  stopAp2ReplayCleanup();
-
-  if (otelShutdownPromise) {
-    return otelShutdownPromise;
-  }
-
-  const otelHandle = globalThis.__agentsbloom_otel_handle;
-  if (!otelHandle) return;
-
-  // Clear the handle before awaiting so a repeated/concurrent shutdown cannot
-  // start a second provider shutdown, even if the first one rejects.
-  globalThis.__agentsbloom_otel_handle = null;
-  otelShutdownPromise = Promise.resolve().then(() => otelHandle.provider.shutdown());
-  try {
-    await otelShutdownPromise;
-  } finally {
-    otelShutdownPromise = null;
-  }
-}
-
-export function agentsbloom(config = {}) {
-  const {
-    apiKey = null,
-    name = "My Agent-Ready Store",
-    description = "An e-commerce store optimized for human and machine AI agents.",
-    actions = {},
-    llmsDoc = "",
-    baseUrl = ""
-  } = config;
-
-  if (!apiKey) {
-    console.error("🌸 AgentsBloom SDK Error: Missing `apiKey`. You must provide an API Key to use the SDK. Get one at dashboard.agentsbloom.com");
-  }
-  if (!baseUrl) {
-    console.error("🌸 AgentsBloom SDK Error: Missing `baseUrl` in config. This is required for secure telemetry.");
-  }
-
-  const MAX_REQUESTS = config.rateLimit?.max || 30;
-  const RATE_LIMIT_WINDOW = config.rateLimit?.windowMs || 60 * 1000;
-  const IDEMPOTENCY_TTL = config.idempotency?.ttlMs || 5 * 60 * 1000;
-  // v4 medium pass (V18): bound the per-process idempotency cache so
-  // unique-key spam cannot grow memory without limit between TTL sweeps.
-  const IDEMPOTENCY_MAX_ENTRIES = Number.isFinite(config.idempotency?.maxEntries) && config.idempotency.maxEntries > 0
-    ? config.idempotency.maxEntries
-    : 10_000;
-  const signatureMaxAgeMs = Number.isFinite(config.signature?.maxAgeMs) && config.signature.maxAgeMs > 0
-    ? config.signature.maxAgeMs
-    : LEGACY_SIGNATURE_MAX_AGE_MS;
-  // v4 medium pass (V14): require the @authority covered component so the
-  // host is bound into every RFC 9421 signature (off by default for
-  // backward compatibility with agents that don't sign it yet).
-  const signatureRequireAuthority = config.signature?.requireAuthority === true;
-  
-  const configuredAgentSecret = config.agentSecret ?? process.env.AGENTSBLOOM_SECRET;
-  const agentSecret = typeof configuredAgentSecret === 'string' && configuredAgentSecret.length > 0
-    ? configuredAgentSecret
-    : null;
-  // Previous secret kept verify-live during rotation (see verifySignature
-  // call sites) so rolling AGENTSBLOOM_SECRET doesn't hard-drop every
-  // in-flight agent.
-  const configuredPreviousSecret = config.agentSecretPrevious ?? process.env.AGENTSBLOOM_SECRET_PREVIOUS;
-  const agentSecretPrevious = typeof configuredPreviousSecret === 'string' && configuredPreviousSecret.length > 0
-    ? configuredPreviousSecret
-    : null;
-  const signatureAuthEnabled = config.disableSignatureAuth !== true && config.demoMode !== true;
-  const cacheNamespace = crypto.randomUUID();
-
-  // --- v4 medium pass (V11): per-agent keys and revocation ---
-  // The single shared merchant secret meant one compromised agent
-  // compromised every agent: any holder could forge requests as ANY
-  // identifier, and there was no way to revoke one agent without rotating
-  // the global secret for all of them. `config.agentKeys` maps identifier
-  // -> per-agent secret (checked first); `config.revokedIdentifiers`
-  // rejects an identifier outright. The shared secret remains the
-  // fallback so existing deployments keep working.
-  const agentKeys = config.agentKeys && typeof config.agentKeys === 'object'
-    ? Object.fromEntries(
-        Object.entries(config.agentKeys).filter(([, v]) => typeof v === 'string' && v.length > 0)
-      )
-    : null;
-  const revokedIdentifiers = Array.isArray(config.revokedIdentifiers)
-    ? new Set(config.revokedIdentifiers)
-    : null;
-
-  // --- v4 medium pass (V12): per-action authorization ---
-  // Any verified identity could previously invoke ANY write action,
-  // checkout included - the permission matrix existed only in the hosted
-  // gateway. Merchants can now require a verified identity per action and
-  // restrict which identities may call it.
-  const actionAccess = config.actionAccess && typeof config.actionAccess === 'object' ? config.actionAccess : null;
-  const actionIdentities = config.actionIdentities && typeof config.actionIdentities === 'object' ? config.actionIdentities : null;
-
-  // --- v4 medium pass (V20): CORS origin policy ---
-  // Array = exact-match allow-list with per-request reflection; string =
-  // legacy single-value behavior ('*' by default). The wildcard default is
-  // loud about itself so merchants notice and restrict it.
-  const allowedOriginList = Array.isArray(config.corsOrigin)
-    ? config.corsOrigin.filter((o) => typeof o === 'string' && o.length > 0)
-    : null;
-  const allowedOriginString = allowedOriginList ? null : (config.corsOrigin || '*');
-  if (!config.corsOrigin) {
-    console.warn("🌸 AgentsBloom Warning: corsOrigin defaults to '*' - any web origin can call this store's API, including write endpoints reachable from a victim browser. Set corsOrigin to an explicit origin or array of origins for production.");
-  }
-
-  /**
-   * Returns a rejection descriptor when `identity` (verified cache identity
-   * string like `rfc:<keyid>` / `legacy:<identifier>`, or null) may not
-   * invoke `actionName`; null when allowed.
-   */
-  function authorizeAction(actionName, identity) {
-    if (actionAccess?.[actionName] === 'authenticated' && !identity) {
-      return {
-        status: 401,
-        body: {
-          error: "Authentication Required",
-          message: `Action ${actionName} requires a verified agent signature (RFC 9421 or X-Agent-Signature).`
-        },
-      };
-    }
-    const allowed = actionIdentities?.[actionName];
-    if (Array.isArray(allowed) && allowed.length > 0) {
-      const matched = Boolean(identity) && allowed.some((pattern) => (
-        pattern === identity || (typeof pattern === 'string' && pattern.endsWith(':') && identity.startsWith(pattern))
-      ));
-      if (!matched) {
-        return {
-          status: 403,
-          body: {
-            error: "Forbidden",
-            message: `Verified identity ${identity || '(anonymous)'} is not authorized to invoke ${actionName}.`
-          },
-        };
-      }
-    }
-    return null;
-  }
-
-  if (!agentSecret && !agentKeys && signatureAuthEnabled) {
-    console.warn("🌸 AgentsBloom Warning: Neither AGENTSBLOOM_SECRET nor config.agentKeys is set. Legacy signed write requests will be rejected until a secret is configured.");
-  }
-
-  // v4 (Host-header poisoning defense): warn when the AP2 audience would be
-  // derived from the request's own Host header - that fallback is spoofable.
-  if (!config.ap2?.expectedAudience && !baseUrl) {
-    console.warn("🌸 AgentsBloom Warning: Neither `baseUrl` nor `ap2.expectedAudience` is configured. The AP2 mandate audience will fall back to each request's Host header, which an attacker can spoof. Set one of them for production.");
-  }
-
-  return async (req, res, next) => {
-    // v4 medium pass (V10): the 1MB gate used to check the Content-Length
-    // header only - a chunked transfer with no Content-Length sailed past
-    // it. The cap is now also enforced against the ACTUAL received bytes
-    // (req.rawBody) once the body parser has run, and is configurable.
-    const maxBodyBytes = Number.isFinite(config.maxBodyBytes) && config.maxBodyBytes > 0
-      ? config.maxBodyBytes
-      : 1024 * 1024;
-    const contentLength = parseInt(req.headers['content-length'] || '0', 10);
-    if (contentLength > maxBodyBytes) {
-      return res.status(413).json({ error: "Payload Too Large", message: `Request body exceeds ${maxBodyBytes} byte limit.` });
-    }
-    let receivedBodyBytes;
-    if (Buffer.isBuffer(req.rawBody)) {
-      receivedBodyBytes = req.rawBody.length;
-    } else if (typeof req.rawBody === 'string') {
-      receivedBodyBytes = Buffer.byteLength(req.rawBody);
-    }
-    if (receivedBodyBytes !== undefined && receivedBodyBytes > maxBodyBytes) {
-      return res.status(413).json({
-        error: "Payload Too Large",
-        message: `Request body exceeds ${maxBodyBytes} byte limit.`,
-        code: "body_size_exceeded"
-      });
-    }
-
-    if (req.path === '/health' && req.method === 'GET') {
-      return res.json({ status: "ok", version: "0.4.0", uptime: process.uptime() });
-    }
-
-    // v4 (Host-header poisoning defense): when `config.allowedHosts` is
-    // configured, a request whose Host header is not on the list gets its
-    // discovery URLs built from the merchant's trusted `baseUrl` instead of
-    // the attacker-controlled Host. Without an allow-list the previous
-    // behavior is preserved (tunnel hosts etc. keep working), so this is
-    // opt-in hardening for production deployments behind a fixed domain.
-    const allowedHosts = Array.isArray(config.allowedHosts)
-      ? config.allowedHosts.filter((h) => typeof h === 'string' && h.length > 0).map((h) => h.toLowerCase())
-      : null;
-    const rawHost = req.get('host') || '';
-    const hostIsAllowed = !allowedHosts || !rawHost || allowedHosts.includes(rawHost.toLowerCase());
-    const host = hostIsAllowed ? rawHost : '';
-    // v4: only well-known protocol values are honored from x-forwarded-proto.
-    const forwardedProtoCandidate = String(req.get('x-forwarded-proto') || '').split(',')[0].trim().toLowerCase();
-    const forwardedProto = forwardedProtoCandidate === 'http' || forwardedProtoCandidate === 'https'
-      ? forwardedProtoCandidate
-      : '';
-    const isTlsTunnel = host.includes('.life') || host.includes('.loca.lt') || host.includes('.trycloudflare.com') || host.includes('.ngrok');
-    const protocol = forwardedProto || (isTlsTunnel ? 'https' : (req.protocol || 'http'));
-    const requestUrl = host ? `${protocol}://${host}` : (baseUrl || `${protocol}://localhost:3000`);
-    const ip = req.ip || req.socket.remoteAddress || '127.0.0.1';
-    const now = Date.now();
-
-    // --- CORS HEADERS ---
-    // v4 medium pass (V20): `corsOrigin` now accepts an array of exact
-    // origins; requests whose Origin matches get it reflected (with
-    // Vary: Origin), everyone else gets NO Access-Control-Allow-Origin at
-    // all - a real allow-list instead of `*` for everything including
-    // writes. The string form behaves exactly as before. The wildcard
-    // default is retained for backward compatibility but warns once.
-    if (Array.isArray(allowedOriginList)) {
-      const requestOrigin = req.headers.origin;
-      if (typeof requestOrigin === 'string' && allowedOriginList.includes(requestOrigin)) {
-        res.setHeader('Access-Control-Allow-Origin', requestOrigin);
-        res.setHeader('Vary', 'Origin');
-      }
-    } else {
-      res.setHeader('Access-Control-Allow-Origin', allowedOriginString);
-    }
-    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
-    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Content-Digest, X-Agent-Signature, X-Agent-Identifier, X-Agent-Timestamp, X-Agent-Nonce, Idempotency-Key, Signature, Signature-Input, Signature-Agent');
-
-    // --- SaaS QUOTA ENFORCEMENT (Zero Latency Cache) ---
-    if (now < quotaExceededUntilMs) {
-      res.setHeader('Content-Type', 'application/json');
-      return res.status(402).json({
-        error: "AgentsBloom Quota Exceeded. Please upgrade your API plan to continue serving AI Agents.",
-        code: "api_quota_exceeded"
-      });
-    }
-
-    // --- 1. DDoS PROTECTION (RATE LIMITING) ---
-    // v4: OPTIONS preflights are now counted toward the same bucket (they
-    // used to bypass the limiter entirely, making free preflight floods
-    // possible), and the client key is normalized so IPv6-mapped IPv4
-    // representations cannot mint fresh buckets.
-    const rateKey = normalizeRateLimitKey(ip);
-    let limit = rateLimitMap.get(rateKey);
-    const rateKeyNormalized = rateKey;
-    if (!limit || now > limit.resetTime) {
-      // v4: bound the tracking map. When at capacity, sweep expired
-      // entries first; if still full, drop the oldest-tracked client so
-      // attacker-controlled IP rotation cannot grow memory unboundedly.
-      if (!rateLimitMap.has(rateKeyNormalized) && rateLimitMap.size >= MAX_RATE_TRACKED_CLIENTS) {
-        for (const [key, val] of rateLimitMap.entries()) {
-          if (val.resetTime < now) rateLimitMap.delete(key);
-        }
-        if (rateLimitMap.size >= MAX_RATE_TRACKED_CLIENTS) {
-          const oldestKey = rateLimitMap.keys().next().value;
-          if (oldestKey !== undefined) rateLimitMap.delete(oldestKey);
-        }
-      }
-      limit = { count: 1, resetTime: now + RATE_LIMIT_WINDOW };
-      rateLimitMap.set(rateKeyNormalized, limit);
-    } else {
-      limit.count++;
-    }
-
-    const remaining = Math.max(0, MAX_REQUESTS - limit.count);
-    res.setHeader('X-RateLimit-Limit', String(MAX_REQUESTS));
-    res.setHeader('X-RateLimit-Remaining', String(remaining));
-    res.setHeader('X-RateLimit-Reset', String(Math.ceil((limit.resetTime - now) / 1000)));
-
-    if (limit.count > MAX_REQUESTS) {
-      res.setHeader('Content-Type', 'application/json');
-      res.setHeader('Retry-After', String(Math.ceil((limit.resetTime - now) / 1000)));
-      return res.status(429).json({
-        error: "Too Many Requests",
-        message: "Rate limit exceeded. Please slow down.",
-        retryAfter: Math.ceil((limit.resetTime - now) / 1000)
-      });
-    }
-
-    // OPTIONS preflights are answered AFTER being counted against the
-    // caller's rate bucket (v4 fix for unthrottled preflight floods).
-    if (req.method === 'OPTIONS') {
-      return res.status(204).end();
-    }
-
-    // --- 2. SERVE SPEC ENDPOINTS ---
-    
-    // Serve /.well-known/agent-spec & /v1/agent/spec (API Versioning)
-    if (req.path === '/.well-known/agent-spec' || req.path === '/v1/agent/spec') {
-      res.setHeader('Content-Type', 'application/json');
-      res.setHeader('Cache-Control', 'public, max-age=86400, stale-while-revalidate=3600');
-      return res.json({
-        name,
-        description,
-        version: "1.0.0",
-        agentsbloomVersion: "0.4.0",
-        discoveryUrl: `${requestUrl}/v1/agent/spec`,
-        catalogUrl: `${requestUrl}/v1/agent/catalog`,
-        llmsUrl: `${requestUrl}/llms.txt`,
-        security: {
-          rateLimiting: { maxRequestsPerMin: MAX_REQUESTS },
-          captchaBypassing: { supported: true, authHeader: "X-Agent-Signature", webBotAuth: true },
-          idempotency: { supported: true, header: "Idempotency-Key", ttlSeconds: 300 }
-        },
-        actions: Object.entries(actions).reduce((acc, [key, val]) => {
-          acc[key] = {
-            endpoint: `/api/agentsbloom/${key}`,
-            method: val.method || 'POST',
-            description: val.description,
-            params: val.params || {}
-          };
-          return acc;
-        }, {}),
-        authentication: { type: "http-message-signatures-or-x-agent-signature", requiredForWrites: true }
-      });
-    }
-
-    // Serve /.well-known/http-message-signatures-directory
-    // v4 medium pass (V16): the old placeholder key ("placeholder-merchant-key")
-    // was a fake trust anchor - agents could "verify" nothing real against
-    // it while believing they had a genuine merchant key set. Fail closed
-    // instead until the merchant configures their JWKS.
-    if (req.path === '/.well-known/http-message-signatures-directory') {
-      if (!config.merchantJwks) {
-        return res.status(503).json({
-          error: 'JWKS Not Configured',
-          message: 'This store has not published a merchant JWKS. Provide `merchantJwks` in the AgentsBloom SDK config to serve /.well-known/http-message-signatures-directory.'
-        });
-      }
-      res.setHeader('Content-Type', 'application/json');
-      res.setHeader('Cache-Control', 'public, max-age=86400');
-      return res.json(config.merchantJwks);
-    }
-
-    // Serve /.well-known/ucp (Universal Commerce Protocol Profile)
-    if (req.path === '/.well-known/ucp') {
-      res.setHeader('Content-Type', 'application/json');
-      res.setHeader('Cache-Control', 'public, max-age=86400');
-      return res.json({
-        protocol: "ucp",
-        version: "1.0.0",
-        store: { name, description, baseUrl: requestUrl },
-        capabilities: [
-          "dev.ucp.shopping",
-          "dev.ucp.shopping.checkout",
-          "dev.ucp.common.identity_linking"
-        ],
-        endpoints: {
-          catalog: `${requestUrl}/ai-catalog.json`,
-          search: `${requestUrl}/api/agentsbloom/search`,
-          products: `${requestUrl}/api/agentsbloom/products`,
-          cart: `${requestUrl}/api/agentsbloom/cart`,
-          checkout: `${requestUrl}/api/agentsbloom/checkout/acp`
-        },
-        actions: Object.entries(actions).reduce((acc, [key, val]) => {
-          acc[key] = {
-            endpoint: `/api/agentsbloom/${key}`,
-            method: val.method || 'POST',
-            description: val.description,
-            params: val.params || {}
-          };
-          return acc;
-        }, {}),
-        auth: {
-          methods: ["http-message-signatures", "x-agent-signature"]
-        }
-      });
-    }
-
-    // Serve /ai-catalog.json & /v1/agent/catalog (ARD / UCP Compliant)
-    if (req.path === '/ai-catalog.json' || req.path === '/.well-known/ai-catalog.json' || req.path === '/v1/agent/catalog') {
-      res.setHeader('Content-Type', 'application/json');
-      res.setHeader('Cache-Control', 'public, max-age=86400, stale-while-revalidate=3600');
-      return res.json({
-        $schema: "https://universalcommerce.org/schemas/catalog.json",
-        name,
-        description,
-        version: "1.0.0",
-        auth: {
-          supported: ["http-message-signatures", "x-agent-signature"]
-        },
-        items: Object.entries(actions).map(([key, val]) => ({
-          id: key,
-          type: "action",
-          title: key,
-          description: val.description,
-          actionUrl: `${requestUrl}/api/agentsbloom/${key}`
-        }))
-      });
-    }
-
-    // Serve /openapi.json & /schema.json (OpenAPI 3.1 for custom GPT
-    // actions and any OpenAPI-consuming agent). The document is generated
-    // from the merchant's declared actions - previously it hardcoded five
-    // paths, so any custom action (removeFromCart, clearCart, or anything
-    // a merchant added) silently vanished from the OpenAPI surface, and
-    // AP2 endpoints were entirely undocumented.
-    if (req.path === '/openapi.json' || req.path === '/schema.json') {
-      res.setHeader('Content-Type', 'application/json');
-      res.setHeader('Cache-Control', 'public, max-age=86400');
-      return res.json(buildOpenApiDocument({ name, description, requestUrl, actions, signatureAuthEnabled }));
-    }
-
-    // Serve MCP SSE Endpoint for Tool Calling
-    // v4: concurrent SSE sessions are bounded (config.mcp.maxSessions,
-    // default 100). Previously every GET /mcp created an unbounded new
-    // transport with no accounting - a trivial socket/memory exhaustion
-    // vector.
-    if (req.path === '/mcp') {
-      const maxMcpSessions = Number.isFinite(config.mcp?.maxSessions) && config.mcp.maxSessions > 0
-        ? config.mcp.maxSessions
-        : 100;
-      if (activeMcpSessions >= maxMcpSessions) {
-        return res.status(503).json({
-          error: "Too Many MCP Sessions",
-          message: `Concurrent MCP session limit (${maxMcpSessions}) reached. Retry later.`
-        });
-      }
-      const transport = new SSEServerTransport('/mcp/messages', res);
-      activeMcpSessions += 1;
-      res.on('close', () => { activeMcpSessions -= 1; });
-      const mcpServer = new Server({ name: name, version: "1.0.0" }, { capabilities: { tools: {} } });
-      // Auto-generate MCP tool declarations from actions
-      mcpServer.setRequestHandler("tools/list", async () => ({
-        tools: Object.entries(actions).map(([key, val]) => ({
-          name: key,
-          description: val.description,
-          inputSchema: {
-            type: "object",
-            properties: Object.entries(val.params || {}).reduce((acc, [pkey, pval]) => {
-              acc[pkey] = { type: pval };
-              return acc;
-            }, {})
-          }
-        }))
-      }));
-
-      mcpServer.setRequestHandler("tools/call", async (request) => {
-        const action = actions[request.params.name];
-        if (!action) throw new Error(`Tool not found: ${request.params.name}`);
-        // v4 medium pass (V12): the same per-action authorization model
-        // applies to MCP tool invocations.
-        const accessRejection = authorizeAction(request.params.name, authenticatedCacheIdentity);
-        if (accessRejection) throw new Error(accessRejection.body.message);
-        // v4: enforce the declared parameter contract. The REST route has
-        // always validated/coerced params; the MCP path now does too, so
-        // merchants get identical type guarantees on both surfaces.
-        const validation = validateActionParams(request.params.arguments || {}, action);
-        if (!validation.ok) throw new Error(validation.message);
-        const result = await action.handler(validation.params, req, res);
-        return { content: [{ type: "text", text: JSON.stringify(result) }] };
-      });
-
-      // Second-pass review (N4): if connect() rejects, release the session
-      // slot immediately instead of waiting for a close event that may not
-      // fire for a transport that never started.
-      try {
-        return await mcpServer.connect(transport);
-      } catch (err) {
-        activeMcpSessions -= 1;
-        throw err;
-      }
-    }
-
-    // Serve /llms.txt
-    if (req.path === '/llms.txt') {
-      res.setHeader('Content-Type', 'text/plain; charset=utf-8');
-      res.setHeader('Cache-Control', 'public, max-age=86400, stale-while-revalidate=3600');
-      const defaultLlmDoc = `# ${name}\n\n${description}\n\n## Developer API Reference\n\n- GET /.well-known/agent-spec : Spec sheets\n- GET /ai-catalog.json : Catalog schemas\n- GET /openapi.json : OpenAPI 3.1 schema\n`;
-      const docContent = typeof llmsDoc === 'function' ? llmsDoc() : (llmsDoc || defaultLlmDoc);
-      return res.send(docContent);
-    }
-
-    // --- 3. IDEMPOTENCY METADATA FOR WRITES (POST/PUT/PATCH/DELETE) ---
-    const method = String(req.method || '').toUpperCase();
-    const isWrite = ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method);
-    const rawIdempotencyKey = req.headers['idempotency-key'];
-    const idempotencyHeader = typeof rawIdempotencyKey === 'string' ? rawIdempotencyKey : null;
-    let idempotencyKey = null;
-    let authenticatedCacheIdentity = null;
-
-    // --- 4. CRYPTOGRAPHIC CAPTCHA BYPASSING (Web Bot Auth + Legacy HMAC) ---
-    const isMcpMessage = req.path === '/mcp/messages' && method === 'POST';
-    // Second-pass review (N3): AP2 intent/checkout POSTs are now part of the
-    // signature gate. The agent-side SDK has always signed these posts, but
-    // the merchant gate ignored them - so a mandate alone could check out
-    // anonymously, and per-action authorization policies could never see a
-    // verified identity on the most valuable endpoint. A verified mandate
-    // proves budget INTENT; a signature proves who is spending it.
-    const isAp2WritePath = method === 'POST' && (
-      req.path === '/ap2/intent'
-      || req.path === '/ap2/checkout'
-      || req.path === '/v1/ap2/intent'
-      || req.path === '/v1/ap2/checkout'
-    );
-    const isAgentAction = req.path.startsWith('/api/agentsbloom/')
-      || req.path.startsWith('/v1/agent/actions/')
-      || isMcpMessage
-      || isAp2WritePath;
-    // v4 medium pass (V12): resolve which action (if any) this path targets
-    // so per-action authorization can require verification even on reads.
-    let requestedActionName = null;
-    if (req.path.startsWith('/api/agentsbloom/')) {
-      requestedActionName = req.path.slice('/api/agentsbloom/'.length);
-    } else if (req.path.startsWith('/v1/agent/actions/')) {
-      requestedActionName = req.path.slice('/v1/agent/actions/'.length);
-    }
-    const needsAuthenticatedRead = Boolean(
-      requestedActionName && actionAccess?.[requestedActionName] === 'authenticated'
-    );
-    if (isAgentAction && (isWrite || needsAuthenticatedRead) && signatureAuthEnabled) {
-      const signature = req.headers['x-agent-signature'];
-      const identifier = req.headers['x-agent-identifier'];
-      const timestamp = req.headers['x-agent-timestamp'];
-      const nonce = req.headers['x-agent-nonce'];
-      
-      const rfcSignature = req.headers['signature'];
-      const rfcSignatureInput = req.headers['signature-input'];
-      const hasRfcSignature = typeof rfcSignature === 'string' && rfcSignature.length > 0;
-      const hasRfcSignatureInput = typeof rfcSignatureInput === 'string' && rfcSignatureInput.length > 0;
-
-      if (!signature && !hasRfcSignature && !hasRfcSignatureInput) {
-        return res.status(401).json({
-          error: "Verification Required",
-          message: "CAPTCHA check required. Please provide standard RFC 9421 HTTP Message Signatures or the legacy X-Agent-Signature."
-        });
-      }
-
-      if (hasRfcSignature !== hasRfcSignatureInput) {
-        return res.status(403).json({
-          error: "Verification Failed",
-          message: "Signature and Signature-Input headers must be provided together."
-        });
-      }
-      
-      if (hasRfcSignature) {
-        try {
-          const keyidMatch = rfcSignatureInput.match(/keyid="([^"]+)"/);
-          if (!keyidMatch) throw new Error("Missing keyid");
-          const keyid = keyidMatch[1];
-
-          // v4 medium pass (V19/V14): only single-label signatures are
-          // supported - the regex-based parameter extraction below would
-          // silently mis-parse a multi-label input, so reject it explicitly
-          // instead of verifying something other than what was sent.
-          if (/,\s*[a-zA-Z0-9_]+\s*=\s*\(/.test(rfcSignatureInput)) {
-            return res.status(403).json({
-              error: "Verification Failed",
-              message: "Multi-label HTTP Message Signatures are not supported; send exactly one signature label."
-            });
-          }
-          const inputLabelMatch = rfcSignatureInput.match(/^([a-zA-Z0-9_]+)\s*=/);
-          const sigLabelMatch = rfcSignature.match(/^([a-zA-Z0-9_]+)\s*=/);
-          if (!inputLabelMatch || !sigLabelMatch || inputLabelMatch[1] !== sigLabelMatch[1]) {
-            return res.status(403).json({
-              error: "Verification Failed",
-              message: "Signature and Signature-Input labels do not match."
-            });
-          }
-
-          const componentsMatch = rfcSignatureInput.match(/\(([^)]+)\)/);
-          const components = componentsMatch
-            ? componentsMatch[1].split(' ').map(s => s.replace(/"/g, ''))
-            : [];
-          if (!components.includes('@method') || !components.includes('@path') || !components.includes('content-digest')) {
-            throw new Error('HTTP Message Signatures must cover @method, @path, and content-digest');
-          }
-
-          // v4 medium pass (V14): deployments that need the host bound into
-          // every signature can require the @authority component.
-          if (signatureRequireAuthority && !components.includes('@authority')) {
-            throw new Error('HTTP Message Signatures must cover @authority for this deployment');
-          }
-
-          const createdMatch = rfcSignatureInput.match(/(?:^|;)created=(\d+)(?:;|$)/);
-          const expiresMatch = rfcSignatureInput.match(/(?:^|;)expires=(\d+)(?:;|$)/);
-          const nonceMatch = rfcSignatureInput.match(/(?:^|;)nonce="([^"]+)"(?:;|$)/);
-          const algMatch = rfcSignatureInput.match(/(?:^|;)alg="([^"]+)"(?:;|$)/);
-          if (!createdMatch || !expiresMatch || !nonceMatch || !algMatch) {
-            throw new Error('HTTP Message Signatures require created, expires, nonce, and alg parameters');
-          }
-
-          const createdSeconds = Number(createdMatch[1]);
-          const expiresSeconds = Number(expiresMatch[1]);
-          const createdMs = createdSeconds * 1000;
-          const expiresMs = expiresSeconds * 1000;
-          const nowMs = Date.now();
-          if (
-            !Number.isSafeInteger(createdSeconds) ||
-            !Number.isSafeInteger(expiresSeconds) ||
-            expiresSeconds <= createdSeconds ||
-            createdMs > nowMs + RFC_SIGNATURE_CLOCK_SKEW_MS ||
-            createdMs < nowMs - signatureMaxAgeMs ||
-            expiresMs < nowMs - RFC_SIGNATURE_CLOCK_SKEW_MS ||
-            expiresMs - createdMs > signatureMaxAgeMs
-          ) {
-            throw new Error('HTTP Message Signature is expired or outside the allowed lifetime');
-          }
-
-          const rfcNonce = nonceMatch[1];
-          if (!/^[\x21-\x7e]{16,256}$/.test(rfcNonce)) {
-            throw new Error('HTTP Message Signature nonce must be a printable value of 16 to 256 characters');
-          }
-
-          const contentDigest = req.headers['content-digest'];
-          if (typeof contentDigest !== 'string' || contentDigest !== buildRequestContentDigest(req)) {
-            throw new Error('HTTP Message Signature content-digest does not match the request body');
-          }
-
-          const alg = algMatch[1];
-          const rfcReplayKey = `${cacheNamespace}:rfc:${keyid}:${rfcNonce}`;
-          
-          if (/^https?:\/\//i.test(keyid)) {
-            throw new Error("Remote keyid URLs are not accepted; configure a trusted JWKS and use its exact key id");
-          }
-
-          // v4 (fail closed): RFC 9421 verification requires a merchant-
-          // configured trust root. The old third-party default JWKS meant
-          // unconfigured merchants accepted an external provider's signing
-          // keys for their own write actions.
-          const trustedJwks = config.agentJwks;
-          const trustedJwksUrl = config.agentJwksUrl;
-          if (!trustedJwks && !trustedJwksUrl) {
-            return res.status(503).json({
-              error: "Forbidden",
-              message: "RFC 9421 verification is not configured: set config.agentJwks or config.agentJwksUrl to your agent population's JWKS."
-            });
-          }
-          const cacheKey = `${cacheNamespace}:${trustedJwks ? 'inline' : trustedJwksUrl}:${keyid}`;
-          let publicKey = null;
-          const cachedEntry = jwksCacheGet(cacheKey);
-          if (cachedEntry && cachedEntry.key) {
-            publicKey = cachedEntry.key;
-          } else if (cachedEntry && cachedEntry.negative) {
-            // Second-pass review: negative caching - an unknown keyid must
-            // not re-trigger a JWKS fetch on every request.
-            throw new Error("Configured JWKS does not contain the requested key id");
-          } else {
-            let jwks;
-            if (trustedJwks) {
-              jwks = trustedJwks;
-            } else {
-              const parsedJwksUrl = new URL(trustedJwksUrl);
-              if (parsedJwksUrl.protocol !== 'https:') {
-                throw new Error("Configured agentJwksUrl must use HTTPS");
-              }
-              const jwksRes = await fetch(parsedJwksUrl.href, {
-                redirect: 'error',
-                signal: AbortSignal.timeout(5000),
-              });
-              if (!jwksRes.ok) throw new Error(`JWKS request failed with HTTP ${jwksRes.status}`);
-              jwks = await jwksRes.json();
-            }
-
-            if (!Array.isArray(jwks?.keys)) throw new Error("Configured JWKS is invalid");
-            const jwk = jwks.keys.find((candidate) => candidate && candidate.kid === keyid);
-            if (!jwk) {
-              jwksCachePut(cacheKey, { negative: true, expires: Date.now() + JWKS_NEGATIVE_TTL_MS });
-              throw new Error("Configured JWKS does not contain the requested key id");
-            }
-            publicKey = crypto.createPublicKey({ key: jwk, format: 'jwk' });
-            jwksCachePut(cacheKey, { key: publicKey, expires: Date.now() + 3600 * 1000 });
-          }
-
-          // v4 medium pass (V14): pin the declared algorithm family to the
-          // resolved key type so an attacker cannot shop algorithms against
-          // an unrelated key, and derive the digest correctly - the old code
-          // mapped EVERY non-512 alg to SHA-256, silently breaking 384 and
-          // rejecting Ed25519 keys outright.
-          const keyTypeName = String(publicKey.asymmetricKeyType || '').toLowerCase();
-          const algLower = alg.toLowerCase();
-          const isEdKey = keyTypeName === 'ed25519' || keyTypeName === 'ed448';
-          const algFamilyCompatible =
-            (keyTypeName === 'rsa' && algLower.startsWith('rs')) ||
-            (keyTypeName === 'ec' && algLower.startsWith('es')) ||
-            (isEdKey && algLower.startsWith('ed'));
-          if (!algFamilyCompatible) {
-            throw new Error(`Signature algorithm ${alg} is not compatible with the configured key type`);
-          }
-
-          let signatureBase = '';
-          for (const comp of components) {
-            if (comp === '@method') signatureBase += `"@method": ${req.method.toLowerCase()}\n`;
-            else if (comp === '@path') signatureBase += `"@path": ${req.originalUrl || req.path}\n`;
-            else if (comp === '@authority') signatureBase += `"@authority": ${req.headers.host}\n`;
-            else signatureBase += `"${comp}": ${req.headers[comp] || ''}\n`;
-          }
-          const sigParams = rfcSignatureInput.replace(/^[a-zA-Z0-9_]+=\s*/, '');
-          signatureBase += `"@signature-params": ${sigParams}`;
-
-          const sigMatch = rfcSignature.match(/=:([a-zA-Z0-9+/=]+):/);
-          const rawSig = sigMatch ? sigMatch[1] : rfcSignature.replace(/^[a-zA-Z0-9_]+=\s*/, '');
-          const signatureBuffer = Buffer.from(rawSig, 'base64');
-          
-          const hashAlg = isEdKey
-            ? null // Ed25519/Ed448 sign the message itself, no digest
-            : algLower.includes('512') ? 'SHA512' : algLower.includes('384') ? 'SHA384' : 'SHA256';
-
-          const isValid = crypto.verify(hashAlg, Buffer.from(signatureBase), publicKey, signatureBuffer);
-
-          if (!isValid) return res.status(403).json({ error: "Forbidden", message: "Invalid HTTP Message Signature." });
-          // v4: atomic claim - the previous has()-then-set() pair had a
-          // race window where two concurrent identical requests could both
-          // pass before either recorded the nonce. Exactly one of N
-          // concurrent claims now wins.
-          const claimed = await signatureNonceMap.claim(rfcReplayKey, expiresMs);
-          if (!claimed) {
-            return res.status(403).json({
-              error: "Forbidden",
-              message: "HTTP Message Signature nonce has already been used."
-            });
-          }
-          authenticatedCacheIdentity = `rfc:${keyid}`;
-        } catch (err) {
-          // v4 medium pass (V13): verification internals (err.message) were
-          // previously reflected to the caller. Log server-side, respond
-          // with a generic message.
-          console.error("🌸 AgentsBloom: RFC 9421 signature verification failed:", err.message);
-          return res.status(403).json({ error: "Forbidden", message: "Invalid HTTP Message Signature." });
-        }
-      } else {
-        // v4 medium pass (V11): resolve a PER-AGENT secret when one is
-        // configured, and reject revoked identifiers outright.
-        if (revokedIdentifiers && typeof identifier === 'string' && revokedIdentifiers.has(identifier)) {
-          return res.status(403).json({
-            error: "Verification Failed",
-            message: "X-Agent-Identifier has been revoked."
-          });
-        }
-        const perAgentSecret = agentKeys && typeof identifier === 'string' ? agentKeys[identifier] : undefined;
-        const effectiveSecret = (typeof perAgentSecret === 'string' && perAgentSecret.length > 0)
-          ? perAgentSecret
-          : agentSecret;
-
-        const headerValuePattern = /^[\x21-\x7e]+$/;
-        if (
-          !effectiveSecret ||
-          typeof signature !== 'string' ||
-          typeof identifier !== 'string' ||
-          typeof timestamp !== 'string' ||
-          typeof nonce !== 'string' ||
-          identifier.length > 256 ||
-          nonce.length < 16 ||
-          nonce.length > 256 ||
-          !headerValuePattern.test(identifier) ||
-          !headerValuePattern.test(timestamp) ||
-          !headerValuePattern.test(nonce)
-        ) {
-          return res.status(403).json({
-            error: "Verification Failed",
-            message: "X-Agent-Signature requires a configured secret, identifier, timestamp, and nonce."
-          });
-        }
-
-        const timestampSeconds = Number(timestamp);
-        const timestampMs = timestampSeconds * 1000;
-        const nowMs = Date.now();
-        if (!Number.isSafeInteger(timestampSeconds) || Math.abs(nowMs - timestampMs) > signatureMaxAgeMs) {
-          return res.status(403).json({
-            error: "Verification Failed",
-            message: "X-Agent-Signature is expired or has an invalid timestamp."
-          });
-        }
-
-        const replayKey = `${cacheNamespace}:legacy:${identifier}:${nonce}`;
-
-        let signaturePayload;
-        try {
-          signaturePayload = buildLegacySignaturePayload(req, identifier, timestamp, nonce);
-        } catch {
-          return res.status(400).json({
-            error: "Invalid Request",
-            message: "Request body cannot be serialized for signature verification."
-          });
-        }
-        // Rotation window: a signature minted under the PREVIOUS secret
-        // still verifies while merchants roll AGENTSBLOOM_SECRET. Per-agent
-        // keys (V11) are checked first; the shared secret(s) remain the
-        // fallback so existing agents keep working during migration.
-        if (!verifySignature(signature, signaturePayload, effectiveSecret)
-          && !(agentSecret && agentSecret !== effectiveSecret && verifySignature(signature, signaturePayload, agentSecret))
-          && !(agentSecretPrevious && verifySignature(signature, signaturePayload, agentSecretPrevious))) {
-          return res.status(403).json({
-            error: "Verification Failed",
-            message: "X-Agent-Signature is invalid. Access denied."
-          });
-        }
-
-        // v4: atomic claim AFTER successful verification - failed attempts
-        // never burn the nonce, and concurrent replays cannot slip through
-        // the old has()/set() race window.
-        const claimed = await signatureNonceMap.claim(replayKey, timestampMs + signatureMaxAgeMs);
-        if (!claimed) {
-          return res.status(403).json({
-            error: "Verification Failed",
-            message: "X-Agent-Signature nonce has already been used."
-          });
-        }
-        authenticatedCacheIdentity = `legacy:${identifier}`;
-      }
-    }
-
-    // Expose the verified signature identity (rfc:<keyid> or legacy:<id>)
-    // to merchant handlers: stores persist it on orders to correlate
-    // purchases with the agent-reputation system. Null for unsigned
-    // traffic - never trust the raw self-asserted header alone.
-    req.agentIdentity = authenticatedCacheIdentity;
-
-    // --- 3b. IDEMPOTENCY CHECKS FOR WRITES (POST/PUT/PATCH/DELETE) ---
-    // Perform this lookup only after the protected-route authentication gate.
-    // Cache keys are scoped to this middleware instance and the verified agent
-    // identity so one caller cannot replay another caller's cached response.
-    if (isWrite && idempotencyHeader) {
-      const requestedIdentity = typeof req.headers['x-agent-identifier'] === 'string'
-        ? req.headers['x-agent-identifier']
-        : 'anonymous';
-      const cacheIdentity = authenticatedCacheIdentity || `anonymous:${requestedIdentity}`;
-      let serializedRequestBody;
-      try {
-        serializedRequestBody = JSON.stringify(req.body ?? null);
-      } catch {
-        return res.status(400).json({
-          error: "Invalid Request",
-          message: "Request body cannot be serialized for idempotency verification."
-        });
-      }
-      const cacheKeyMaterial = [
-        cacheNamespace,
-        cacheIdentity,
-        method,
-        req.originalUrl || req.path,
-        serializedRequestBody,
-        idempotencyHeader,
-      ].join('\u0000');
-      idempotencyKey = `${cacheNamespace}:${crypto.createHash('sha256').update(cacheKeyMaterial).digest('hex')}`;
-
-      for (const [key, val] of idempotencyMap.entries()) {
-        if (val.expiry < now) {
-          idempotencyMap.delete(key);
-        }
-      }
-
-      const cachedResponse = idempotencyMap.get(idempotencyKey);
-      if (cachedResponse) {
-        console.log('🌸 AgentsBloom: Found cached response for an Idempotency Key');
-        res.setHeader('X-Cache', 'Idempotent-Hit');
-        res.setHeader('Content-Type', cachedResponse.headers['content-type'] || 'application/json');
-        return res.status(cachedResponse.status).send(cachedResponse.responseBody);
-      }
-    }
-
-    // --- 4b. AP2 MANDATE VERIFICATION (Wired into middleware) ---
-    // v4: the legacy `authorization` header fallback is now only honored on
-    // requests that are ALREADY AP2-shaped (an /ap2 path or x-protocol AP2).
-    // Previously ANY request carrying a dotted Authorization value - which
-    // includes every ordinary OAuth/JWT bearer token - was parsed as an AP2
-    // SD-JWT, failed verification, and had the whole request rejected 403,
-    // breaking unrelated authenticated routes. The explicit
-    // `x-ap2-mandate` header works everywhere as before.
-    const detectedProtocol = resolveProtocol(req);
-    const rawAuthorizationHeader = req.headers['authorization'];
-    const ap2MandateHeader = req.headers['x-ap2-mandate']
-      || (detectedProtocol === 'AP2' && typeof rawAuthorizationHeader === 'string'
-        ? rawAuthorizationHeader
-        : null);
-    let ap2MandateResult = null;
-
-    if (detectedProtocol === 'AP2' || (ap2MandateHeader && ap2MandateHeader.includes('.'))) {
-      // Second-pass review (N2): the mandate's single-use jti must only be
-      // consumed where the mandate is actually USED. Verification still
-      // runs wherever a mandate is presented (so merchant handlers keep
-      // receiving req.ap2Mandate), but a mandate riding along on an
-      // unrelated cart-add no longer burns itself.
-      const isAp2Endpoint = req.path.startsWith('/ap2/') || req.path.startsWith('/v1/ap2/');
-      // Verify the SD-JWT mandate before allowing any write action. Uses
-      // either a merchant-configured trusted public key (config.ap2PublicKey)
-      // or, when absent, derives a key from the mandate's own did:key issuer
-      // (self-certifying - see lib/ap2.js for why an unverifiable mandate is
-      // now rejected outright rather than passed through as "valid").
-      ap2MandateResult = await verifyAP2Mandates(req.headers, req.body || {}, {
-        trustedPublicKey: config.ap2PublicKey || null,
-        // v4: production-grade trust policy. When ap2.trustedIssuersOnly is
-        // set, self-certifying did:key mandates (which anyone can mint for
-        // any budget) are rejected in favor of the merchant-trusted key.
-        allowSelfCertifying: config.ap2?.trustedIssuersOnly !== true,
-        // Audience binding prefers explicit configuration, then the
-        // merchant-configured baseUrl (a trusted deployment constant), and
-        // only falls back to the Host-derived requestUrl when neither is
-        // set - deriving the expected audience purely from the request's
-        // own Host header would let an attacker align a stolen mandate's
-        // audience with a spoofed Host.
-        expectedAudience: config.ap2?.expectedAudience || (baseUrl ? baseUrl : requestUrl),
-        maxMandateLifetimeSec: config.ap2?.maxMandateLifetimeSec,
-        requireJti: config.ap2?.requireJti,
-        requestedCategories: req.body?.requestedCategories || config.ap2?.requestedCategories,
-        expectedCurrency: config.ap2?.expectedCurrency,
-        consumeJti: isAp2Endpoint,
-      });
-
-      if (!ap2MandateResult.valid) {
-        return res.status(403).json({
-          error: "AP2 Mandate Rejected",
-          protocol: "AP2",
-          reason: ap2MandateResult.reason,
-          message: "The Verifiable Intent mandate failed validation. The agent's payment authorization is invalid."
-        });
-      }
-
-      // Attach mandate info to request for downstream handlers
-      req.ap2Mandate = ap2MandateResult;
-    }
-
-    // --- AP2 Discovery Endpoint ---
-    if (req.path === '/ap2/capabilities' || req.path === '/v1/ap2/capabilities') {
-      return res.json({
-        protocol: "AP2",
-        version: "1.0.0",
-        store: { name, description, baseUrl: requestUrl },
-        mandateTypes: ["intentMandate", "cartMandate", "paymentMandate"],
-        verificationMethods: ["sd-jwt", "jwt"],
-        endpoints: {
-          capabilities: `${requestUrl}/ap2/capabilities`,
-          intent: `${requestUrl}/ap2/intent`,
-          checkout: `${requestUrl}/ap2/checkout`,
-          actions: Object.keys(actions).map(k => `${requestUrl}/v1/agent/actions/${k}`)
-        },
-        budgetEnforcement: true,
-        signatureAlgorithms: ["ES256", "ES384", "ES512", "RS256", "RS384", "RS512", "EdDSA"]
-      });
-    }
-
-    // --- AP2 Intent Endpoint (agent announces what it wants to do) ---
-    if ((req.path === '/ap2/intent' || req.path === '/v1/ap2/intent') && req.method === 'POST') {
-      // Must check `.verified`, not mere truthiness: ap2MandateResult is a
-      // truthy object even when no mandate header was ever presented
-      // (`{ valid: true, verified: false, note: '...' }`), so a bare
-      // `if (!ap2MandateResult)` check would let unauthenticated requests
-      // reach this mandate-gated endpoint.
-      if (!ap2MandateResult?.verified) {
-        return res.status(401).json({
-          error: "AP2 Mandate Required",
-          message: "Send x-ap2-mandate: Bearer <sd-jwt> header with a valid Intent Mandate."
-        });
-      }
-      return res.json({
-        protocol: "AP2",
-        intentAccepted: true,
-        mandateVerified: ap2MandateResult.verified,
-        mandates: ap2MandateResult.mandates || {},
-        availableActions: Object.entries(actions).map(([key, val]) => ({
-          action: key,
-          endpoint: `/v1/agent/actions/${key}`,
-          method: val.method || 'POST',
-          description: val.description
-        })),
-        budgetRemaining: ap2MandateResult.mandates?.intentMandate?.maxBudget || "unlimited"
-      });
-    }
-
-    // --- AP2 Checkout Endpoint (mandate-gated checkout) ---
-    if ((req.path === '/ap2/checkout' || req.path === '/v1/ap2/checkout') && req.method === 'POST') {
-      // Same fix as /ap2/intent above: this MUST require a genuinely
-      // verified mandate, not just a truthy result object. Previously,
-      // hitting /ap2/checkout with no x-ap2-mandate header at all still
-      // produced a truthy `ap2MandateResult` (valid:true, verified:false),
-      // which passed this check, then found no `.mandates.intentMandate`
-      // to read a maxBudget from - so checkout proceeded with ZERO budget
-      // enforcement. Requiring `.verified` closes that bypass.
-      if (!ap2MandateResult?.verified) {
-        return res.status(401).json({
-          error: "AP2 Payment Mandate Required",
-          message: "AP2 checkout requires x-ap2-mandate header with a valid Payment Mandate."
-        });
-      }
-
-      const checkoutAction = actions['checkout'];
-      if (!checkoutAction || typeof checkoutAction.handler !== 'function') {
-        return res.status(404).json({ error: 'Checkout action not configured for this store.' });
-      }
-
-      // v4 medium pass (V12): mandate verification proves budget intent,
-      // not identity authorization - the checkout action still respects
-      // the merchant's per-action policy.
-      const checkoutAccessRejection = authorizeAction('checkout', authenticatedCacheIdentity);
-      if (checkoutAccessRejection) {
-        return res.status(checkoutAccessRejection.status).json(checkoutAccessRejection.body);
-      }
-
-      // Validate budget before executing checkout. A checkout-time mandate
-      // MUST declare a positive maxBudget: a capless mandate would
-      // authorize unlimited spend (previously it produced
-      // budgetEnforced:false and the checkout proceeded at any total).
-      const orderTotal = req.body?.orderTotal || req.body?.total || 0;
-      const maxBudget = ap2MandateResult.mandates?.intentMandate?.maxBudget
-                     || ap2MandateResult.mandates?.paymentMandate?.maxBudget;
-
-      if (!Number.isFinite(Number(maxBudget)) || Number(maxBudget) <= 0) {
-        return res.status(403).json({
-          error: "AP2 Mandate Rejected",
-          protocol: "AP2",
-          reason: "Mandate must declare a positive intentMandate.maxBudget for checkout",
-          message: "A checkout mandate without a spending cap authorizes unlimited spend and is rejected. Reissue the mandate with maxBudget."
-        });
-      }
-
-      // v4 medium pass (V17): a budget number without a matching currency
-      // is unitless - reject unit-mismatch attempts before any handler run.
-      const mandateCurrency = ap2MandateResult.mandates?.intentMandate?.currency
-        || ap2MandateResult.mandates?.paymentMandate?.currency;
-      const normalizeCurrency = (value) => String(value || '').trim().toUpperCase();
-      const expectedCheckoutCurrency = config.ap2?.expectedCurrency;
-      if (
-        mandateCurrency && expectedCheckoutCurrency &&
-        normalizeCurrency(mandateCurrency) !== normalizeCurrency(expectedCheckoutCurrency)
-      ) {
-        return res.status(403).json({
-          error: "AP2 Mandate Rejected",
-          protocol: "AP2",
-          reason: `Mandate currency "${mandateCurrency}" does not match this store's expected currency "${expectedCheckoutCurrency}"`,
-          message: "The mandate was issued for a different currency than this store accepts."
-        });
-      }
-      if (
-        mandateCurrency && req.body?.currency &&
-        normalizeCurrency(mandateCurrency) !== normalizeCurrency(req.body.currency)
-      ) {
-        return res.status(403).json({
-          error: "AP2 Budget Exceeded",
-          protocol: "AP2",
-          reason: `Order currency "${req.body.currency}" does not match the mandate's currency "${mandateCurrency}"`,
-          message: "Order currency does not match the mandate's declared currency."
-        });
-      }
-
-      if (Number(orderTotal) > Number(maxBudget)) {
-        return res.status(403).json({
-          error: "AP2 Budget Exceeded",
-          protocol: "AP2",
-          orderTotal: Number(orderTotal),
-          maxBudget: Number(maxBudget),
-          message: `Order total $${orderTotal} exceeds mandate budget limit of $${maxBudget}.`
-        });
-      }
-
-      // v4 (budget bypass fix): the client-declared orderTotal above is a
-      // fast-fail convenience only - it is attacker-controlled and can
-      // never be the basis of authorization. The AUTHORITATIVE check runs
-      // after the merchant handler returns, against the handler-computed
-      // total (result.total / result.totalPrice). If the real cart total
-      // exceeds the mandate budget, no payment URL is returned.
-      const issuerTrust = ap2MandateResult.selfCertifying ? 'self-certifying' : 'merchant-trusted';
-
-      return Promise.resolve(checkoutAction.handler(req.body, req, res))
-        .then(result => {
-          const serverTotal = result && (result.total ?? result.totalPrice);
-          const effectiveTotal = serverTotal !== undefined ? Number(serverTotal) : Number(orderTotal);
-          if (Number.isFinite(effectiveTotal) && effectiveTotal > Number(maxBudget)) {
-            return res.status(403).json({
-              error: "AP2 Budget Exceeded",
-              protocol: "AP2",
-              reason: "Server-computed order total exceeds the mandate's maxBudget; the client-declared orderTotal is never authoritative.",
-              orderTotal: effectiveTotal,
-              totalSource: serverTotal !== undefined ? 'handler' : 'client-declared',
-              maxBudget: Number(maxBudget),
-              message: `Order total $${effectiveTotal} computed by the store exceeds mandate budget limit of $${maxBudget}. No checkout link was issued.`
-            });
-          }
-          if (!res.headersSent) {
-            res.json({
-              protocol: "AP2",
-              verifiableIntent: {
-                mandateVerified: ap2MandateResult.verified,
-                budgetEnforced: !!maxBudget,
-                issuerTrust,
-                maxBudget: maxBudget || null,
-                orderTotal: result.total || orderTotal,
-                ...(serverTotal !== undefined ? { totalSource: 'handler' } : {})
-              },
-              session_id: result.sessionId || `ap2_sess_${Date.now()}`,
-              payment_url: result.paymentUrl,
-              status: "authorized",
-              expires_at: Math.floor(Date.now() / 1000) + 3600,
-              checkout: result
-            });
-          }
-        })
-        .catch(err => {
-          console.error("AP2 Checkout error:", err);
-          if (!res.headersSent) {
-            res.status(500).json({ error: 'Internal AP2 checkout error', protocol: 'AP2' });
-          }
-        });
-    }
-
-    // --- 5. HANDLE ACTION ROUTING ---
-    // Agentic Commerce Protocol (ACP) Checkout Wrapper
-    if (req.path === '/api/agentsbloom/checkout/acp' && req.method === 'POST') {
-      const checkoutAction = actions['checkout'];
-      if (checkoutAction && typeof checkoutAction.handler === 'function') {
-        return Promise.resolve(checkoutAction.handler(req.body, req, res))
-          .then(result => {
-            if (!res.headersSent) {
-              res.json({
-                session_id: result.sessionId || `acp_sess_${Date.now()}`,
-                payment_url: result.paymentUrl,
-                status: "open",
-                expires_at: Math.floor(Date.now() / 1000) + 3600
-              });
-            }
-          })
-          .catch(err => {
-            console.error(`ACP Checkout execution error:`, err);
-            if (!res.headersSent) {
-              res.status(500).json({ error: 'Internal ACP checkout error' });
-            }
-          });
-      } else {
-        return res.status(404).json({ error: 'ACP Checkout not configured for this store.' });
-      }
-    }
-
-    if (req.path.startsWith('/api/agentsbloom/') || req.path.startsWith('/v1/agent/actions/')) {
-      const actionName = requestedActionName;
-      const action = actions[actionName];
-
-      if (action && typeof action.handler === 'function') {
-        const configuredMethod = String(action.method || 'POST').toUpperCase();
-        if (method !== configuredMethod) {
-          res.setHeader('Allow', configuredMethod);
-          return res.status(405).json({
-            error: "Method Not Allowed",
-            message: `Action ${actionName} only accepts ${configuredMethod} requests.`,
-            allowedMethod: configuredMethod,
-          });
-        }
-
-        // v4 medium pass (V12): per-action authorization - the SDK had no
-        // authorization model at all; any verified identity could invoke
-        // any write action including checkout.
-        const accessRejection = authorizeAction(actionName, authenticatedCacheIdentity);
-        if (accessRejection) {
-          return res.status(accessRejection.status).json(accessRejection.body);
-        }
-
-        const params = method === 'GET' ? { ...req.query } : { ...req.body };
-
-        // v4: shared with the MCP tools/call path so both surfaces enforce
-        // the same declared parameter contract.
-        const validation = validateActionParams(params, action);
-        if (!validation.ok) {
-          return res.status(400).json({ error: "Invalid Parameter", message: validation.message });
-        }
-        const validatedParams = validation.params;
-        
-        // Cache original res.send to support idempotency key caching
-        const originalSend = res.send;
-        res.send = function (body) {
-          if (isWrite && idempotencyKey && res.statusCode >= 200 && res.statusCode < 300) {
-            // v4 (V18): evict the oldest entry at capacity instead of
-            // growing without bound between TTL sweeps.
-            if (!idempotencyMap.has(idempotencyKey) && idempotencyMap.size >= IDEMPOTENCY_MAX_ENTRIES) {
-              const oldestKey = idempotencyMap.keys().next().value;
-              if (oldestKey !== undefined) idempotencyMap.delete(oldestKey);
-            }
-                  idempotencyMap.set(idempotencyKey, {
-              responseBody: body,
-              status: res.statusCode,
-              headers: { 'content-type': res.getHeader('content-type') },
-              timestamp: Date.now(),
-              expiry: Date.now() + IDEMPOTENCY_TTL
-            });
-          }
-          return originalSend.apply(this, arguments);
-        };
-
-        const startTime = Date.now();
-        const agentName = req.headers['x-agent-identifier'] || req.headers['signature-agent'] || 'Unknown Agent';
-
-        // Extract W3C Trace Context from incoming request (HIGH-16)
-        const parentContext = propagation.extract(context.active(), req.headers);
-        const span = tracer.startSpan(`agent_request:${actionName}`, {}, parentContext);
-
-        return Promise.resolve(action.handler(validatedParams, req, res))
-          .then(result => {
-            if (!res.headersSent) {
-              res.json(result);
-            }
-            
-            const latencyMs = Date.now() - startTime;
-            const revenue = result && result.totalPrice ? result.totalPrice : 0;
-
-            // OpenTelemetry Native Instrumentation
-            span.setAttribute('agent.name', agentName);
-            span.setAttribute('agent.route', `/api/agentsbloom/${actionName}`);
-            span.setAttribute('http.status_code', res.statusCode);
-            span.setAttribute('http.latency_ms', latencyMs);
-            
-            agentRequestsCounter.add(1, { agent: agentName });
-            if (revenue) agentRevenueCounter.add(revenue, { agent: agentName });
-            span.end();
-
-            // Telemetry is handled by OTLP exporters configured via setupTelemetry().
-            // The span.end() call above will auto-export to the OTLP collector.
-          })
-          .catch(err => {
-            span.setAttribute('error', true);
-            span.end();
-            console.error(`AgentsBloom action execution error (${actionName}):`, err);
-            if (!res.headersSent) {
-              res.status(500).json({ error: 'Internal agent endpoint error' });
-            }
-          });
-      } else {
-        return res.status(404).json({ error: `Unknown AgentsBloom action.` });
-      }
-    }
-
-    // --- 6. HTML INJECTION WITH COMPRESSION SUPPORT ---
-    // Opt-out via config.disableHtmlInjection (MED-12)
-    if (config.disableHtmlInjection) {
-      return next();
-    }
-
-    const originalWrite = res.write;
-    const originalEnd = res.end;
-    let chunks = [];
-    let isHtml = false;
-
-    const originalWriteHead = res.writeHead;
-    res.writeHead = function (statusCode, headers) {
-      const contentType = res.getHeader('Content-Type') || (headers && headers['content-type']) || '';
-      if (typeof contentType === 'string' && contentType.includes('text/html')) {
-        isHtml = true;
-        res.removeHeader('Content-Length');
-        if (headers) delete headers['content-length'];
-      }
-      return originalWriteHead.apply(this, arguments);
-    };
-
-    res.write = function (chunk) {
-      const contentType = res.getHeader('Content-Type') || '';
-      if (isHtml || (typeof contentType === 'string' && contentType.includes('text/html'))) {
-        isHtml = true;
-        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
-        return true;
-      }
-      return originalWrite.apply(res, arguments);
-    };
-
-    res.end = function (chunk) {
-      const contentType = res.getHeader('Content-Type') || '';
-      if (isHtml || (typeof contentType === 'string' && contentType.includes('text/html'))) {
-        isHtml = true;
-        if (chunk) {
-          chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
-        }
-        
-        let bodyBuffer = Buffer.concat(chunks);
-        const encoding = res.getHeader('Content-Encoding');
-        const isGzipped = typeof encoding === 'string' && encoding.includes('gzip');
-
-        // Decompress if gzipped
-        if (isGzipped) {
-          try {
-            bodyBuffer = zlib.gunzipSync(bodyBuffer);
-          } catch (err) {
-            console.error("AgentsBloom decompression error:", err);
-          }
-        }
-
-        let body = bodyBuffer.toString('utf8');
-
-        if (body.toLowerCase().includes('</body>')) {
-          // v4 (stored-XSS fix): merchant-controlled strings (store name,
-          // description, action names/descriptions) are no longer spliced
-          // into inline JavaScript or raw JSON.stringify output. JSON.stringify
-          // does NOT escape `</script>`, so a crafted description used to be
-          // able to break out of the script tag and execute on every page.
-          // All dynamic data is now serialized through toSafeJson() (hex-
-          // escaped `<`, `>`, `&`, U+2028/2029) and consumed as DATA by a
-          // static loader - the same approach as the hardened next-sdk.
-          const jsonLdData = {
-            "@context": "https://schema.org",
-            "@type": "WebPage",
-            "name": name,
-            "description": description,
-            "potentialAction": Object.entries(actions).map(([key]) => ({
-              "@type": "SearchAction",
-              "name": key,
-              "target": `${requestUrl}/api/agentsbloom/${key}`
-            }))
-          };
-
-          const jsonLdScript = `\n<script type="application/ld+json">\n${toSafeJson(jsonLdData)}\n</script>`;
-
-          const webMcpTools = Object.entries(actions).map(([key, val]) => ({
-            name: key,
-            description: val.description || '',
-            method: String(val.method || 'POST').toUpperCase(),
-            inputSchema: {
-              type: 'object',
-              properties: Object.fromEntries(
-                Object.entries(val.params || {}).map(([pkey, pval]) => [pkey, { type: pval }])
-              ),
-            },
-          }));
-          const webMcpScript = `
-<meta name="webmcp" content="active">
-<script>
-// Auto-generated WebMCP Declarative Actions by AgentsBloom
-(function() {
-  if (typeof navigator === 'undefined' || !navigator.ai || typeof navigator.ai.registerTool !== 'function') return;
-  var tools = ${toSafeJson(webMcpTools)};
-  for (var i = 0; i < tools.length; i++) {
-    (function(tool) {
-      navigator.ai.registerTool({
-        name: tool.name,
-        description: tool.description,
-        inputSchema: tool.inputSchema,
-        handler: async function(args) {
-          try {
-            var headers = { 'Content-Type': 'application/json', 'Accept': 'application/json' };
-            var options = { method: tool.method, headers: headers };
-            var url = '/api/agentsbloom/' + encodeURIComponent(tool.name);
-            if (tool.method === 'GET') {
-              var queryParams = new URLSearchParams(args).toString();
-              if (queryParams) url += '?' + queryParams;
-            } else {
-              options.body = JSON.stringify(args);
-            }
-            var response = await fetch(url, options);
-            return await response.json();
-          } catch (e) {
-            return { error: e.message };
-          }
-        }
-      });
-    })(tools[i]);
-  }
-})();
-</script>
-`;
-
-          if (body.toLowerCase().includes('</head>')) {
-            body = body.replace(/<\/head>/i, `${jsonLdScript}\n</head>`);
-          } else {
-            body = body + jsonLdScript;
-          }
-
-          body = body.replace(/<\/body>/i, `${webMcpScript}\n</body>`);
-        }
-
-        let outputBuffer = Buffer.from(body);
-
-        // Re-compress if gzipped
-        if (isGzipped) {
-          try {
-            outputBuffer = zlib.gzipSync(outputBuffer);
-          } catch (err) {
-            console.error("AgentsBloom compression error:", err);
-          }
-        }
-
-        res.setHeader('Content-Length', outputBuffer.length);
-        originalWrite.call(res, outputBuffer);
-        return originalEnd.call(res);
-      }
-      return originalEnd.apply(res, arguments);
-    };
-
-    next();
-  };
-}
-
-// --- UNIFIED PROTOCOL ROUTER ---
-export function resolveProtocol(req) {
-  const accept = (req.headers && req.headers['accept']) || '';
-  const xProtocol = (req.headers && req.headers['x-protocol']) || '';
-  const path = req.path || req.url || '';
-
-  if (accept.includes('application/mcp+json') || path.startsWith('/mcp')) {
-    return 'WEBMCP';
-  }
-  if (xProtocol.toLowerCase() === 'ucp' || path.startsWith('/.well-known/ucp') || path.startsWith('/ucp')) {
-    return 'UCP';
-  }
-  if (xProtocol.toLowerCase() === 'acp' || path.startsWith('/acp')) {
-    return 'ACP';
-  }
-  if (req.headers && (req.headers['x-ap2-mandate'] || path.startsWith('/ap2'))) {
-    return 'AP2';
-  }
-  return 'AGENTSBLOOM_REST';
-}
-
-// --- AP2 (AGENT PAYMENTS PROTOCOL) SD-JWT MANDATE VERIFIER ---
-//
-// Thin, backward-compatible wrapper over the hardened implementation in
-// lib/ap2.js. The original signature `verifyAP2Mandates(headers, body,
-// publicKey)` treated an unsigned/unverifiable mandate as "valid but
-// unverified" and let downstream code (and, worse, the /ap2/checkout gate
-// itself - see the truthiness-check fix above) treat that as authorization
-// to check out. lib/ap2.js's verifyAp2Mandate instead REJECTS any mandate
-// it cannot cryptographically verify.
-//
-// Both call shapes are supported for backward compatibility:
-//   verifyAP2Mandates(headers, body, publicKey)              // legacy
-//   verifyAP2Mandates(headers, body, { trustedPublicKey, expectedAudience, ... })  // current
-export function verifyAP2Mandates(headers = {}, body = {}, publicKeyOrOptions = null) {
-  let options;
-  if (publicKeyOrOptions === null || publicKeyOrOptions === undefined) {
-    options = {};
-  } else if (
-    publicKeyOrOptions instanceof crypto.KeyObject ||
-    Buffer.isBuffer(publicKeyOrOptions) ||
-    typeof publicKeyOrOptions === 'string'
-  ) {
-    // Legacy call shape: third argument is a raw public key.
-    options = { trustedPublicKey: publicKeyOrOptions };
-  } else {
-    // Current call shape: third argument is an options object.
-    options = publicKeyOrOptions;
-  }
-  return verifyAp2Mandate(headers, body, options);
-}
-
+import { createOutcomeReporter, stripeEventToOutcome } from './lib/outcomes.js';
+import {
+  verifyHttpMessageSignature,
+  createJwksCache,
+  isBlockedSsrfHostname,
+  SUPPORTED_SIGNATURE_ALGORITHMS,
+  STRICT_REQUIRED_COMPONENTS,
+} from './lib/http-signatures.js';
+import {
+  requestContextFromExpress,
+  normalizeAuthority as normalizeAuthorityForScheme,
+  PROFILE_STRICT,
+} from './lib/signature-base.js';
+import { compareAmounts, normalizeCurrencyCode, parseAmount } from './lib/money.js';
+
+const tracer = trace.getTracer('agentsbloom-sdk');
+const meter = metrics.getMeter('agentsbloom-sdk');
+
+const agentRequestsCounter = meter.createCounter('agent_visits_total', { description: 'Total AI Visits' });
+const agentRevenueCounter = meter.createCounter('agent_revenue_usd', { description: 'Total AI Revenue', valueType: ValueType.DOUBLE });
+
+/**
+ * Initialize OpenTelemetry with OTLP exporters.
+ * Call this BEFORE using the agentsbloom() middleware.
+ * 
+ * @param {Object} options
+ * @param {string} options.otlpEndpoint - OTLP collector URL (default: http://localhost:4318)
+ * @param {string} options.serviceName - Service name for traces (default: agentsbloom-merchant)
+ * @param {number} options.samplingRatio - Trace sampling ratio 0.0-1.0 (default: 1.0)
+ * @param {string} options.apiKey - API key for authenticating with the collector
+ */
+export async function setupTelemetry(options = {}) {
+  const {
+    otlpEndpoint = process.env.AGENTSBLOOM_OTEL_ENDPOINT || 'http://localhost:4318',
+    serviceName = 'agentsbloom-merchant',
+    samplingRatio = parseFloat(process.env.AGENTSBLOOM_SAMPLING_RATIO || '1.0'),
+    apiKey = process.env.AGENTSBLOOM_API_KEY || '',
+  } = options;
+
+  // Refuse to ship the collector credential over cleartext. The default
+  // endpoint is a local collector, which is fine; anything remote must be TLS.
+  let endpointIsLocal = false;
+  try {
+    const parsed = new URL(otlpEndpoint);
+    endpointIsLocal = parsed.hostname === 'localhost'
+      || parsed.hostname === '127.0.0.1'
+      || parsed.hostname === '::1'
+      || parsed.hostname === '[::1]';
+    if (apiKey && parsed.protocol !== 'https:' && !endpointIsLocal) {
+      throw new Error(
+        `refusing to send the telemetry API key to ${parsed.origin} over ${parsed.protocol.replace(':', '')}; use https`,
+      );
+    }
+  } catch (err) {
+    if (err instanceof TypeError) {
+      throw new Error(`AgentsBloom: otlpEndpoint is not a valid URL: ${otlpEndpoint}`);
+    }
+    throw err;
+  }
+
+  // Store NON-SECRET config for lazy initialization when the OTel SDK packages
+  // are available. The apiKey used to be parked on globalThis alongside it,
+  // where any code in the process (including a compromised transitive
+  // dependency) could read the merchant's collector credential.
+  globalThis.__agentsbloom_otel_config = { otlpEndpoint, serviceName, samplingRatio };
+
+  const handle = await initExporter({ otlpEndpoint, serviceName, samplingRatio, apiKey });
+  globalThis.__agentsbloom_otel_handle = handle;
+
+  const effectiveRatio = Number.isFinite(samplingRatio) ? Math.min(1, Math.max(0, samplingRatio)) : 1;
+  console.log(`🌸 AgentsBloom: Telemetry configured (sampling: ${(effectiveRatio * 100).toFixed(0)}%)`);
+  return { otlpEndpoint, serviceName, samplingRatio: effectiveRatio };
+}
+// v4 security hardening: there is deliberately NO default RFC 9421 JWKS
+// source anymore. The previous default pointed at a third-party provider's
+// live key set, which silently accepted that provider's signing keys for
+// MERCHANT write actions whenever a merchant forgot to configure their own
+// trust root. Verification now fails closed until the merchant configures
+// `agentJwks` (inline JWKS object) or `agentJwksUrl` (HTTPS JWKS endpoint).
+const LEGACY_SIGNATURE_MAX_AGE_MS = 5 * 60 * 1000;
+const RFC_SIGNATURE_CLOCK_SKEW_MS = 30 * 1000;
+const SIGNATURE_REPLAY_CACHE_MAX_SIZE = 50_000;
+const MAX_RATE_TRACKED_CLIENTS = 50_000;
+
+/**
+ * Bounded, swept, negatively-cached JWKS store shared by every middleware
+ * instance in the process. The cache and the SSRF guard now live in
+ * lib/http-signatures.js alongside the verification that uses them, so there
+ * is exactly one implementation of each rule instead of one per call site.
+ */
+const jwksCache = createJwksCache();
+
+/**
+ * Caps the cardinality of a value used as a telemetry label.
+ *
+ * Agent-supplied headers were passed straight through as OTel metric
+ * dimensions and span attributes, so a caller could mint unbounded
+ * time series inside the merchant's own monitoring pipeline.
+ */
+const MAX_LABEL_LENGTH = 64;
+function boundedLabel(value, fallback = 'unknown') {
+  if (typeof value !== 'string' || value.length === 0) return fallback;
+  const cleaned = value.replace(/[^\x20-\x7e]/g, '');
+  if (cleaned.length === 0) return fallback;
+  if (cleaned.length <= MAX_LABEL_LENGTH) return cleaned;
+  // Keep a stable, readable prefix plus a digest so distinct long values stay
+  // distinguishable without being unbounded.
+  const digest = crypto.createHash('sha256').update(cleaned).digest('base64url').slice(0, 8);
+  return `${cleaned.slice(0, MAX_LABEL_LENGTH - 9)}~${digest}`;
+}
+
+/** Escapes JSON for embedding inside an HTML <script> element. */
+function toSafeJson(value) {
+  return JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+/**
+ * Normalizes a client key for rate limiting: strips the IPv6-mapped IPv4
+ * prefix (::ffff:127.0.0.1 -> 127.0.0.1) so the same client cannot get a
+ * fresh bucket by alternating address representations.
+ */
+function normalizeRateLimitKey(ip) {
+  const raw = String(ip || '');
+  return raw.startsWith('::ffff:') ? raw.slice(7) : raw;
+}
+
+function verifySignature(signature, payload, secret) {
+  try {
+    if (typeof signature !== 'string' || !/^[a-f0-9]{64}$/i.test(signature)) return false;
+    const computed = crypto.createHmac('sha256', secret).update(payload).digest();
+    const provided = Buffer.from(signature, 'hex');
+    return crypto.timingSafeEqual(computed, provided);
+  } catch {
+    return false;
+  }
+}
+
+function buildLegacySignaturePayload(req, identifier, timestamp, nonce) {
+  return JSON.stringify([
+    identifier,
+    String(req.method || '').toUpperCase(),
+    req.originalUrl || req.path,
+    timestamp,
+    nonce,
+    req.body ?? null,
+  ]);
+}
+
+// Content-Digest computation and verification moved to lib/signature-base.js.
+//
+// The old helper here silently fell back to `Buffer.from(JSON.stringify(req.body))`
+// when `req.rawBody` was absent, which turned "this digest proves what the
+// client sent" into "this digest matches our re-serialization of what our
+// parser produced". An agent computing its digest the same way satisfied it
+// even when the bytes on the wire differed. `resolveBodyBytes` now requires
+// the real bytes and fails closed without them.
+
+/**
+ * v4: validates/coerces action parameters against the action's declared
+ * `params` type map. Shared by the REST action route AND the MCP tools/call
+ * handler - previously the MCP path passed arguments straight through with
+ * no validation at all, so the type guarantees advertised in discovery
+ * documents were not actually enforced there.
+ *
+ * @returns {{ ok: boolean, params?: object, message?: string }}
+ */
+function validateActionParams(rawParams, action) {
+  const params = { ...rawParams };
+  if (!action.params) return { ok: true, params };
+  for (const [key, type] of Object.entries(action.params)) {
+    const val = params[key];
+    if (val === undefined) continue;
+    if (type === 'any') continue;
+    if (type === 'number') {
+      if (typeof val === 'number' && !isNaN(val)) {
+        // valid
+      } else if (typeof val === 'string' && val.trim() !== '' && !isNaN(Number(val))) {
+        params[key] = Number(val);
+      } else {
+        return { ok: false, message: `Expected ${type} for parameter ${key}` };
+      }
+    } else if (type === 'boolean') {
+      if (typeof val === 'boolean') {
+        // valid
+      } else if (typeof val === 'string' && (val === 'true' || val === 'false' || val === '1' || val === '0')) {
+        params[key] = val === 'true' || val === '1';
+      } else {
+        return { ok: false, message: `Expected ${type} for parameter ${key}` };
+      }
+    } else if (type === 'string') {
+      if (typeof val !== 'string') {
+        return { ok: false, message: `Expected ${type} for parameter ${key}` };
+      }
+    } else if (typeof val !== type && !(typeof type === 'string' && type.includes(typeof val))) {
+      return { ok: false, message: `Expected ${type} for parameter ${key}` };
+    }
+  }
+  return { ok: true, params };
+}
+
+// In-memory rate limiting map
+const rateLimitMap = new Map();
+// v4: bounded count of live MCP SSE sessions (see /mcp handler).
+let activeMcpSessions = 0;
+/**
+ * Live MCP SSE transports by session id, so `POST /mcp/messages` can be routed
+ * to the stream that opened it. Bounded implicitly by `mcp.maxSessions`;
+ * entries are deleted when the SSE response closes.
+ */
+const mcpTransports = new Map();
+
+// --- v4 medium pass (V15): the SaaS quota gate is now WIRED ---
+// Previously `quotaExceededUntil` was a per-instance variable initialized
+// to 0 that nothing ever set - dead code implying enforcement that did not
+// exist. The hosted gateway (or any operator tooling) can now trip every
+// middleware instance in the process via setQuotaExceededUntil(), or set
+// AGENTSBLOOM_QUOTA_EXCEEDED_UNTIL (epoch ms) in the environment.
+let quotaExceededUntilMs = Number(process.env.AGENTSBLOOM_QUOTA_EXCEEDED_UNTIL || 0) || 0;
+
+/** Marks quota exceeded process-wide until the given epoch-ms timestamp. */
+export function setQuotaExceededUntil(untilEpochMs) {
+  const value = Number(untilEpochMs);
+  quotaExceededUntilMs = Number.isFinite(value) ? value : 0;
+}
+
+/** Clears the process-wide quota-exceeded state immediately. */
+export function clearQuotaExceeded() {
+  quotaExceededUntilMs = 0;
+}
+const rateLimitInterval = setInterval(() => {
+  const now = Date.now();
+  for (const [key, val] of rateLimitMap.entries()) {
+    if (val.resetTime < now) rateLimitMap.delete(key);
+  }
+}, 60 * 1000);
+rateLimitInterval.unref();
+
+// In-memory Idempotency cache (per-instance optimization; order-level
+// idempotency is enforced downstream by deterministic order refs).
+// Signature nonces live in a replay cache that becomes cluster-wide when
+// an Upstash REST endpoint is configured (lib/shared-store.js).
+const idempotencyMap = new Map();
+const signatureNonceMap = createReplayCache('agentsbloom:sig:nonce', SIGNATURE_REPLAY_CACHE_MAX_SIZE);
+const idempotencyInterval = setInterval(() => {
+  const now = Date.now();
+  for (const [key, val] of idempotencyMap.entries()) {
+    if (val.expiry < now) idempotencyMap.delete(key);
+  }
+}, 60 * 1000);
+idempotencyInterval.unref();
+
+let otelShutdownPromise = null;
+
+// --- OpenAPI 3.1 document generation ---
+//
+// Generated from the merchant's declared actions so every action the store
+// actually mounts appears in /openapi.json. Well-known commerce actions
+// keep their curated, example-rich schemas; anything else a merchant
+// declares is derived from its `params` type map. AP2 and protocol
+// discovery endpoints are documented alongside the REST surface, and the
+// security schemes describe the exact headers RFC 9421 / legacy /
+// AP2 callers must send.
+
+const OPENAPI_PARAM_TYPE_MAP = {
+  string: 'string',
+  number: 'number',
+  integer: 'integer',
+  boolean: 'boolean',
+  any: null, // schema-less when the action accepts anything
+};
+
+function openApiSchemaForParamType(type) {
+  const mapped = OPENAPI_PARAM_TYPE_MAP[type];
+  return mapped ? { type: mapped } : {};
+}
+
+/** Common error responses referenced via $ref from every generated operation. */
+function openApiErrorRefs() {
+  return {
+    "401": { $ref: '#/components/responses/VerificationRequired' },
+    "403": { $ref: '#/components/responses/Forbidden' },
+    "429": { $ref: '#/components/responses/RateLimited' },
+  };
+}
+
+/** Curated, example-rich entries for the canonical commerce actions. */
+function curatedOpenApiPaths() {
+  return {
+    "/api/agentsbloom/products": {
+      get: {
+        operationId: "listProducts",
+        summary: "Retrieve product catalog or filter by category/query",
+        parameters: [
+          { name: "category", in: "query", schema: { type: "string" }, description: "Category filter (e.g. shoes, apparel, accessories, electronics, home, books)" },
+          { name: "query", in: "query", schema: { type: "string" }, description: "Search term" },
+          { name: "limit", in: "query", schema: { type: "integer" }, description: "Maximum products to return" }
+        ],
+        responses: { "200": { description: "List of matching products with price, sizes, stock, rating" }, ...openApiErrorRefs() }
+      }
+    },
+    "/api/agentsbloom/search": {
+      get: {
+        operationId: "searchProducts",
+        summary: "Search products by natural language query",
+        parameters: [
+          { name: "query", in: "query", schema: { type: "string" }, description: "Product name or search keywords" },
+          { name: "category", in: "query", schema: { type: "string" }, description: "Category filter" }
+        ],
+        responses: { "200": { description: "Search results with count and product details" }, ...openApiErrorRefs() }
+      }
+    },
+    "/api/agentsbloom/cart": {
+      get: {
+        operationId: "getCart",
+        summary: "Retrieve current cart contents and total price",
+        responses: { "200": { description: "Cart items, item count, and price breakdown" }, ...openApiErrorRefs() }
+      }
+    },
+    "/api/agentsbloom/addToCart": {
+      post: {
+        operationId: "addToCart",
+        summary: "Add a product variant to cart",
+        security: [{ HttpSignatureAuth: [] }, { LegacyAgentSignature: [] }],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                required: ["productId"],
+                properties: {
+                  productId: { type: "string", description: "Product ID (e.g. puma-velocity-3, trail-master-x2, agent-pro-backpack)" },
+                  size: { type: "string", description: "Product size or variant (e.g. 10, M, One Size)" },
+                  quantity: { type: "integer", default: 1, description: "Quantity to add" }
+                }
+              }
+            }
+          }
+        },
+        responses: { "200": { description: "Success confirmation and updated cart size" }, ...openApiErrorRefs() }
+      }
+    },
+    "/api/agentsbloom/checkout": {
+      post: {
+        operationId: "checkout",
+        summary: "Create a secure checkout link for payment",
+        security: [{ HttpSignatureAuth: [] }, { LegacyAgentSignature: [] }],
+        requestBody: {
+          required: false,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  address: { type: "string", description: "Customer shipping destination address" },
+                  gateway: { type: "string", default: "stripe", description: "Payment gateway: stripe, razorpay, or paddle" }
+                }
+              }
+            }
+          }
+        },
+        responses: { "200": { description: "Secure payment URL and session ID" }, ...openApiErrorRefs() }
+      }
+    }
+  };
+}
+
+/** Derives an operation entry for any declared action from its params map. */
+function openApiOperationForAction(key, action, signatureAuthEnabled) {
+  const httpMethod = String(action.method || 'POST').toLowerCase();
+  const isWrite = ['post', 'put', 'patch', 'delete'].includes(httpMethod);
+  const paramSchema = {
+    type: "object",
+    properties: Object.fromEntries(
+      Object.entries(action.params || {}).map(([pkey, pval]) => [pkey, openApiSchemaForParamType(pval)])
+    ),
+  };
+
+  const operation = {
+    operationId: key,
+    summary: action.description || key,
+    ...(isWrite && signatureAuthEnabled
+      ? { security: [{ HttpSignatureAuth: [] }, { LegacyAgentSignature: [] }] }
+      : {}),
+    ...(httpMethod === 'get'
+      ? {
+          parameters: Object.entries(action.params || {}).map(([pkey, pval]) => ({
+            name: pkey,
+            in: "query",
+            schema: openApiSchemaForParamType(pval),
+          })),
+        }
+      : {
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: paramSchema } },
+          },
+        }),
+    responses: {
+      "200": { description: action.description ? `${action.description} result` : `${key} result` },
+      ...openApiErrorRefs(),
+    },
+  };
+
+  return { [httpMethod]: operation };
+}
+
+/**
+ * Builds the full OpenAPI 3.1 document: generated action paths, curated
+ * canonical entries, AP2 endpoints, discovery endpoints, reusable security
+ * schemes, and error responses.
+ */
+function buildOpenApiDocument({ name, description, requestUrl, actions = {}, signatureAuthEnabled = true }) {
+  const paths = {};
+
+  // Every declared action gets a path (curated entries override generated
+  // ones for the canonical five).
+  for (const [key, action] of Object.entries(actions)) {
+    paths[`/api/agentsbloom/${key}`] = openApiOperationForAction(key, action, signatureAuthEnabled);
+  }
+  Object.assign(paths, curatedOpenApiPaths());
+
+  // AP2 protocol surface.
+  paths["/ap2/capabilities"] = {
+    get: {
+      operationId: "ap2Capabilities",
+      summary: "AP2 capabilities, mandate types, and verification methods",
+      responses: { "200": { description: "AP2 capability document" }, ...openApiErrorRefs() },
+    },
+  };
+  paths["/ap2/intent"] = {
+    post: {
+      operationId: "ap2Intent",
+      summary: "Announce purchase intent with a verified AP2 Intent Mandate",
+      security: [{ Ap2MandateAuth: [] }],
+      requestBody: {
+        required: false,
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                requestedCategories: { type: "array", items: { type: "string" }, description: "Cart categories the intent covers" },
+              },
+            },
+          },
+        },
+      },
+      responses: {
+        "200": { description: "Intent accepted with mandate verification evidence" },
+        "401": { $ref: '#/components/responses/VerificationRequired' },
+        "403": { $ref: '#/components/responses/Forbidden' },
+      },
+    },
+  };
+  paths["/ap2/checkout"] = {
+    post: {
+      operationId: "ap2Checkout",
+      summary: "Mandate-gated checkout: creates a payment URL only when a verified AP2 mandate with a positive maxBudget covers the order total",
+      security: [{ Ap2MandateAuth: [] }],
+      requestBody: {
+        required: true,
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              required: ["orderTotal"],
+              properties: {
+                orderTotal: { type: "number", description: "Order total that must be covered by the mandate's maxBudget" },
+                address: { type: "string", description: "Customer shipping destination address" },
+                gateway: { type: "string", default: "stripe", description: "Payment gateway: stripe, razorpay, or paddle" },
+              },
+            },
+          },
+        },
+      },
+      responses: {
+        "200": { description: "Authorized checkout with payment URL, session id, and budget-enforcement evidence" },
+        "401": { $ref: '#/components/responses/VerificationRequired' },
+        "403": { $ref: '#/components/responses/Forbidden' },
+      },
+    },
+  };
+
+  // Protocol discovery surface.
+  paths["/.well-known/agent-spec"] = {
+    get: {
+      operationId: "agentSpec",
+      summary: "Legacy/compatibility discovery document",
+      responses: { "200": { description: "Agent spec manifest" } },
+    },
+  };
+  paths["/.well-known/ucp"] = {
+    get: {
+      operationId: "ucpProfile",
+      summary: "UCP (Universal Commerce Protocol) profile",
+      responses: { "200": { description: "UCP profile with capabilities and endpoint declarations" } },
+    },
+  };
+  paths["/ai-catalog.json"] = {
+    get: {
+      operationId: "aiCatalog",
+      summary: "WebMCP/ARD-style action catalog",
+      responses: { "200": { description: "Action catalog document" } },
+    },
+  };
+  paths["/llms.txt"] = {
+    get: {
+      operationId: "llmsDoc",
+      summary: "LLM-oriented developer guide",
+      responses: { "200": { description: "Plain-text guide for LLM agents" } },
+    },
+  };
+
+  return {
+    openapi: "3.1.0",
+    info: { title: name, description, version: "1.0.0" },
+    servers: [{ url: requestUrl }],
+    // Reads are open; writes carry their own operation-level security.
+    security: [],
+    tags: [
+      { name: "catalog", description: "Product browsing and search" },
+      { name: "cart", description: "Cart operations (write actions require agent signatures)" },
+      { name: "checkout", description: "Checkout link creation" },
+      { name: "ap2", description: "AP2 mandate-gated payment authorization" },
+      { name: "discovery", description: "Protocol discovery documents" },
+    ],
+    paths,
+    components: {
+      securitySchemes: {
+        HttpSignatureAuth: {
+          type: "apiKey",
+          description: "RFC 9421 HTTP Message Signatures: send `Signature` and `Signature-Input` headers; the signature must cover @method, @path, and content-digest for bodied requests, with created/expires/nonce parameters and a keyid resolvable through the configured JWKS.",
+          in: "header",
+          name: "Signature",
+        },
+        LegacyAgentSignature: {
+          type: "apiKey",
+          description: "Legacy HMAC scheme: X-Agent-Signature plus X-Agent-Identifier, X-Agent-Timestamp, X-Agent-Nonce headers, signed with the shared agent secret.",
+          in: "header",
+          name: "X-Agent-Signature",
+        },
+        Ap2MandateAuth: {
+          type: "apiKey",
+          description: "AP2 budget mandate: an SD-JWT with intentMandate.maxBudget, audience-bound to this store, sent as `X-AP2-Mandate: Bearer <sd-jwt>`.",
+          in: "header",
+          name: "X-AP2-Mandate",
+        },
+      },
+      responses: {
+        VerificationRequired: {
+          description: "Credential missing - write actions need an agent signature; AP2 endpoints need a mandate.",
+          content: { "application/json": { schema: { type: "object", properties: { error: { type: "string" }, message: { type: "string" } } } } },
+        },
+        Forbidden: {
+          description: "Credential presented but invalid (bad signature, expired mandate, budget exceeded, wrong audience, replay detected).",
+          content: { "application/json": { schema: { type: "object", properties: { error: { type: "string" }, reason: { type: "string" }, protocol: { type: "string" } } } } },
+        },
+        RateLimited: {
+          description: "Too many requests - respect X-RateLimit-Reset and Retry-After.",
+          content: { "application/json": { schema: { type: "object", properties: { error: { type: "string" }, retryAfter: { type: "number" } } } } },
+        },
+      },
+    },
+  };
+}
+
+
+export async function shutdown() {
+  clearInterval(rateLimitInterval);
+  clearInterval(idempotencyInterval);
+  rateLimitMap.clear();
+  idempotencyMap.clear();
+  signatureNonceMap.clear();
+  jwksCache.clear();
+  stopAp2ReplayCleanup();
+
+  if (otelShutdownPromise) {
+    return otelShutdownPromise;
+  }
+
+  const otelHandle = globalThis.__agentsbloom_otel_handle;
+  if (!otelHandle) return;
+
+  // Clear the handle before awaiting so a repeated/concurrent shutdown cannot
+  // start a second provider shutdown, even if the first one rejects.
+  globalThis.__agentsbloom_otel_handle = null;
+  otelShutdownPromise = Promise.resolve().then(() => otelHandle.provider.shutdown());
+  try {
+    await otelShutdownPromise;
+  } finally {
+    otelShutdownPromise = null;
+  }
+}
+
+export function agentsbloom(config = {}) {
+  const {
+    apiKey = null,
+    name = "My Agent-Ready Store",
+    description = "An e-commerce store optimized for human and machine AI agents.",
+    actions = {},
+    llmsDoc = "",
+    baseUrl = ""
+  } = config;
+
+  if (!apiKey) {
+    console.error("🌸 AgentsBloom SDK Error: Missing `apiKey`. You must provide an API Key to use the SDK. Get one at dashboard.agentsbloom.com");
+  }
+  if (!baseUrl) {
+    console.error("🌸 AgentsBloom SDK Error: Missing `baseUrl` in config. This is required for secure telemetry.");
+  }
+
+  const MAX_REQUESTS = config.rateLimit?.max || 30;
+  const RATE_LIMIT_WINDOW = config.rateLimit?.windowMs || 60 * 1000;
+  const IDEMPOTENCY_TTL = config.idempotency?.ttlMs || 5 * 60 * 1000;
+  // v4 medium pass (V18): bound the per-process idempotency cache so
+  // unique-key spam cannot grow memory without limit between TTL sweeps.
+  const IDEMPOTENCY_MAX_ENTRIES = Number.isFinite(config.idempotency?.maxEntries) && config.idempotency.maxEntries > 0
+    ? config.idempotency.maxEntries
+    : 10_000;
+  const signatureMaxAgeMs = Number.isFinite(config.signature?.maxAgeMs) && config.signature.maxAgeMs > 0
+    ? config.signature.maxAgeMs
+    : LEGACY_SIGNATURE_MAX_AGE_MS;
+  // Host binding is now REQUIRED by default. Without `@authority` in the
+  // covered components, a signature captured at store A is structurally valid
+  // at store B for the same path — a real cross-merchant replay whenever two
+  // stores trust the same JWKS. Opting out re-opens that hole knowingly.
+  const signatureRequireAuthority = config.signature?.requireAuthority !== false;
+  // The pre-hardening (non-conformant) signature base is accepted only when a
+  // merchant explicitly opts in for a migration window. See
+  // lib/signature-base.js for exactly how the two profiles differ.
+  const acceptLegacySignatureProfile = config.signature?.acceptLegacyProfile === true;
+  // Escape hatch for applications that cannot capture `req.rawBody`. Hashing a
+  // re-serialized body does not prove what the client sent, so this is off by
+  // default and loud when enabled.
+  const allowReserializedBody = config.signature?.allowReserializedBody === true;
+  if (allowReserializedBody) {
+    console.warn(
+      "🌸 AgentsBloom Warning: signature.allowReserializedBody is enabled. Content-Digest will be computed from a RE-SERIALIZED body, "
+      + 'which does not prove what the client actually sent. Prefer express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }).',
+    );
+  }
+  if (acceptLegacySignatureProfile) {
+    console.warn(
+      "🌸 AgentsBloom Warning: signature.acceptLegacyProfile is enabled. The pre-0.6 signature base (lowercased @method, query folded into @path, "
+      + 'unbindable authority) is accepted as a fallback. Remove this once your agents sign the conformant RFC 9421 base.',
+    );
+  }
+  if (config.signature?.requireAuthority === false) {
+    console.warn(
+      '🌸 AgentsBloom Warning: signature.requireAuthority is disabled. Signatures will not bind the request host, so a signature captured '
+      + 'at another store that trusts the same keys can be replayed here.',
+    );
+  }
+
+  const configuredAgentSecret = config.agentSecret ?? process.env.AGENTSBLOOM_SECRET;
+  const agentSecret = typeof configuredAgentSecret === 'string' && configuredAgentSecret.length > 0
+    ? configuredAgentSecret
+    : null;
+  // Previous secret kept verify-live during rotation (see verifySignature
+  // call sites) so rolling AGENTSBLOOM_SECRET doesn't hard-drop every
+  // in-flight agent.
+  const configuredPreviousSecret = config.agentSecretPrevious ?? process.env.AGENTSBLOOM_SECRET_PREVIOUS;
+  const agentSecretPrevious = typeof configuredPreviousSecret === 'string' && configuredPreviousSecret.length > 0
+    ? configuredPreviousSecret
+    : null;
+  const signatureAuthEnabled = config.disableSignatureAuth !== true && config.demoMode !== true;
+
+  // --- Replay-cache namespace (was: crypto.randomUUID()) ---
+  //
+  // This prefix is part of every nonce and idempotency cache key. Generating
+  // it randomly per `agentsbloom()` call silently DEFEATED cluster-wide replay
+  // protection: with Upstash configured, instance A stored
+  // `<uuid-A>:rfc:<keyid>:<nonce>` while instance B looked for
+  // `<uuid-B>:rfc:<keyid>:<nonce>`, so `SET NX` never collided and a captured
+  // signature replayed cleanly on any other pod — and on the same pod after a
+  // restart. (Mandate jtis were not namespaced at all, so the two paths
+  // disagreed about whether replay protection was cluster-wide.)
+  //
+  // The namespace is now DERIVED and stable across instances of the same
+  // store: explicit config first, then the merchant's `baseUrl`, then a fixed
+  // default. Distinct stores sharing one Redis still get distinct prefixes.
+  const cacheNamespace = (() => {
+    const explicit = config.cacheNamespace;
+    if (typeof explicit === 'string' && explicit.trim().length > 0) return explicit.trim();
+    if (baseUrl) {
+      return `ab:${crypto.createHash('sha256').update(normalizeAudience(baseUrl)).digest('base64url').slice(0, 16)}`;
+    }
+    console.warn(
+      '🌸 AgentsBloom Warning: neither `baseUrl` nor `cacheNamespace` is set, so replay-cache keys fall back to a shared default. '
+      + 'If several distinct stores share one replay store, set `cacheNamespace` per store.',
+    );
+    return 'ab:default';
+  })();
+
+  // --- v4 medium pass (V11): per-agent keys and revocation ---
+  // The single shared merchant secret meant one compromised agent
+  // compromised every agent: any holder could forge requests as ANY
+  // identifier, and there was no way to revoke one agent without rotating
+  // the global secret for all of them. `config.agentKeys` maps identifier
+  // -> per-agent secret (checked first); `config.revokedIdentifiers`
+  // rejects an identifier outright. The shared secret remains the
+  // fallback so existing deployments keep working.
+  const agentKeys = config.agentKeys && typeof config.agentKeys === 'object'
+    ? Object.fromEntries(
+        Object.entries(config.agentKeys).filter(([, v]) => typeof v === 'string' && v.length > 0)
+      )
+    : null;
+  const revokedIdentifiers = Array.isArray(config.revokedIdentifiers)
+    ? new Set(config.revokedIdentifiers)
+    : null;
+
+  // --- v4 medium pass (V12): per-action authorization ---
+  // Any verified identity could previously invoke ANY write action,
+  // checkout included - the permission matrix existed only in the hosted
+  // gateway. Merchants can now require a verified identity per action and
+  // restrict which identities may call it.
+  const actionAccess = config.actionAccess && typeof config.actionAccess === 'object' ? config.actionAccess : null;
+  const actionIdentities = config.actionIdentities && typeof config.actionIdentities === 'object' ? config.actionIdentities : null;
+
+  // --- v4 medium pass (V20): CORS origin policy ---
+  // Array = exact-match allow-list with per-request reflection; string =
+  // legacy single-value behavior ('*' by default). The wildcard default is
+  // loud about itself so merchants notice and restrict it.
+  const allowedOriginList = Array.isArray(config.corsOrigin)
+    ? config.corsOrigin.filter((o) => typeof o === 'string' && o.length > 0)
+    : null;
+  const allowedOriginString = allowedOriginList ? null : (config.corsOrigin || '*');
+  if (!config.corsOrigin) {
+    console.warn("🌸 AgentsBloom Warning: corsOrigin defaults to '*' - any web origin can call this store's API, including write endpoints reachable from a victim browser. Set corsOrigin to an explicit origin or array of origins for production.");
+  }
+
+  /**
+   * Returns a rejection descriptor when `identity` (verified cache identity
+   * string like `rfc:<keyid>` / `legacy:<identifier>`, or null) may not
+   * invoke `actionName`; null when allowed.
+   */
+  function authorizeAction(actionName, identity) {
+    if (actionAccess?.[actionName] === 'authenticated' && !identity) {
+      return {
+        status: 401,
+        body: {
+          error: "Authentication Required",
+          message: `Action ${actionName} requires a verified agent signature (RFC 9421 or X-Agent-Signature).`
+        },
+      };
+    }
+    const allowed = actionIdentities?.[actionName];
+    if (Array.isArray(allowed) && allowed.length > 0) {
+      const matched = Boolean(identity) && allowed.some((pattern) => (
+        pattern === identity || (typeof pattern === 'string' && pattern.endsWith(':') && identity.startsWith(pattern))
+      ));
+      if (!matched) {
+        return {
+          status: 403,
+          body: {
+            error: "Forbidden",
+            message: `Verified identity ${identity || '(anonymous)'} is not authorized to invoke ${actionName}.`
+          },
+        };
+      }
+    }
+    return null;
+  }
+
+  if (!agentSecret && !agentKeys && signatureAuthEnabled) {
+    console.warn("🌸 AgentsBloom Warning: Neither AGENTSBLOOM_SECRET nor config.agentKeys is set. Legacy signed write requests will be rejected until a secret is configured.");
+  }
+
+  // --- Host-header policy (resolved once, at construction) ---
+  //
+  // Used for two distinct purposes:
+  //   1. Discovery URLs: a request whose Host is not on the list gets its
+  //      URLs built from the merchant's trusted `baseUrl` instead of the
+  //      attacker-controlled Host.
+  //   2. Signature authority binding: `@authority` canonicalizes the request's
+  //      own Host header, so covering it only prevents cross-store replay if
+  //      the verifier ALSO knows which authorities are its own. Otherwise an
+  //      attacker replaying store A's signature here just sends
+  //      `Host: store-a.com` and the signature base reconstructs identically.
+  const allowedHosts = Array.isArray(config.allowedHosts)
+    ? config.allowedHosts.filter((h) => typeof h === 'string' && h.length > 0).map((h) => h.toLowerCase())
+    : null;
+
+  const expectedAuthorities = (() => {
+    const authorities = new Set();
+    for (const host of allowedHosts || []) {
+      authorities.add(normalizeAuthorityForScheme(host, 'https:'));
+      authorities.add(normalizeAuthorityForScheme(host, 'http:'));
+    }
+    if (baseUrl) {
+      try {
+        const parsed = new URL(baseUrl);
+        authorities.add(normalizeAuthorityForScheme(parsed.host, parsed.protocol));
+      } catch {
+        // A malformed baseUrl is already reported elsewhere; don't add it.
+      }
+    }
+    authorities.delete('');
+    if (authorities.size === 0 && signatureAuthEnabled && signatureRequireAuthority) {
+      console.warn(
+        '🌸 AgentsBloom Warning: neither `baseUrl` nor `allowedHosts` is set, so the Host header cannot be validated. '
+        + 'Signatures still have to COVER @authority, but a replayed signature from another store will match if the attacker '
+        + 'forwards that store\'s Host header. Set `baseUrl` (or `allowedHosts`) to make host binding effective.',
+      );
+      return null;
+    }
+    return authorities.size > 0 ? authorities : null;
+  })();
+
+  // v4 (Host-header poisoning defense): warn when the AP2 audience would be
+  // derived from the request's own Host header - that fallback is spoofable.
+  if (!config.ap2?.expectedAudience && !baseUrl) {
+    console.warn("🌸 AgentsBloom Warning: Neither `baseUrl` nor `ap2.expectedAudience` is configured. The AP2 mandate audience will fall back to each request's Host header, which an attacker can spoof. Set one of them for production.");
+  }
+
+  return async (req, res, next) => {
+    // v4 medium pass (V10): the 1MB gate used to check the Content-Length
+    // header only - a chunked transfer with no Content-Length sailed past
+    // it. The cap is now also enforced against the ACTUAL received bytes
+    // (req.rawBody) once the body parser has run, and is configurable.
+    const maxBodyBytes = Number.isFinite(config.maxBodyBytes) && config.maxBodyBytes > 0
+      ? config.maxBodyBytes
+      : 1024 * 1024;
+    const contentLength = parseInt(req.headers['content-length'] || '0', 10);
+    if (contentLength > maxBodyBytes) {
+      return res.status(413).json({ error: "Payload Too Large", message: `Request body exceeds ${maxBodyBytes} byte limit.` });
+    }
+    let receivedBodyBytes;
+    if (Buffer.isBuffer(req.rawBody)) {
+      receivedBodyBytes = req.rawBody.length;
+    } else if (typeof req.rawBody === 'string') {
+      receivedBodyBytes = Buffer.byteLength(req.rawBody);
+    }
+    if (receivedBodyBytes !== undefined && receivedBodyBytes > maxBodyBytes) {
+      return res.status(413).json({
+        error: "Payload Too Large",
+        message: `Request body exceeds ${maxBodyBytes} byte limit.`,
+        code: "body_size_exceeded"
+      });
+    }
+
+    if (req.path === '/health' && req.method === 'GET') {
+      return res.json({ status: "ok", version: "0.4.0", uptime: process.uptime() });
+    }
+
+    const rawHost = req.get('host') || '';
+    const hostIsAllowed = !allowedHosts || !rawHost || allowedHosts.includes(rawHost.toLowerCase());
+    const host = hostIsAllowed ? rawHost : '';
+    // v4: only well-known protocol values are honored from x-forwarded-proto.
+    const forwardedProtoCandidate = String(req.get('x-forwarded-proto') || '').split(',')[0].trim().toLowerCase();
+    const forwardedProto = forwardedProtoCandidate === 'http' || forwardedProtoCandidate === 'https'
+      ? forwardedProtoCandidate
+      : '';
+    const isTlsTunnel = host.includes('.life') || host.includes('.loca.lt') || host.includes('.trycloudflare.com') || host.includes('.ngrok');
+    const protocol = forwardedProto || (isTlsTunnel ? 'https' : (req.protocol || 'http'));
+    const requestUrl = host ? `${protocol}://${host}` : (baseUrl || `${protocol}://localhost:3000`);
+    const ip = req.ip || req.socket.remoteAddress || '127.0.0.1';
+    const now = Date.now();
+
+    // --- CORS HEADERS ---
+    // v4 medium pass (V20): `corsOrigin` now accepts an array of exact
+    // origins; requests whose Origin matches get it reflected (with
+    // Vary: Origin), everyone else gets NO Access-Control-Allow-Origin at
+    // all - a real allow-list instead of `*` for everything including
+    // writes. The string form behaves exactly as before. The wildcard
+    // default is retained for backward compatibility but warns once.
+    if (Array.isArray(allowedOriginList)) {
+      const requestOrigin = req.headers.origin;
+      if (typeof requestOrigin === 'string' && allowedOriginList.includes(requestOrigin)) {
+        res.setHeader('Access-Control-Allow-Origin', requestOrigin);
+        res.setHeader('Vary', 'Origin');
+      }
+    } else {
+      res.setHeader('Access-Control-Allow-Origin', allowedOriginString);
+    }
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Content-Digest, X-Agent-Signature, X-Agent-Identifier, X-Agent-Timestamp, X-Agent-Nonce, Idempotency-Key, Signature, Signature-Input, Signature-Agent');
+
+    // --- SaaS QUOTA ENFORCEMENT (Zero Latency Cache) ---
+    if (now < quotaExceededUntilMs) {
+      res.setHeader('Content-Type', 'application/json');
+      return res.status(402).json({
+        error: "AgentsBloom Quota Exceeded. Please upgrade your API plan to continue serving AI Agents.",
+        code: "api_quota_exceeded"
+      });
+    }
+
+    // --- 1. DDoS PROTECTION (RATE LIMITING) ---
+    // v4: OPTIONS preflights are now counted toward the same bucket (they
+    // used to bypass the limiter entirely, making free preflight floods
+    // possible), and the client key is normalized so IPv6-mapped IPv4
+    // representations cannot mint fresh buckets.
+    const rateKey = normalizeRateLimitKey(ip);
+    let limit = rateLimitMap.get(rateKey);
+    const rateKeyNormalized = rateKey;
+    if (!limit || now > limit.resetTime) {
+      // v4: bound the tracking map. When at capacity, sweep expired
+      // entries first; if still full, drop the oldest-tracked client so
+      // attacker-controlled IP rotation cannot grow memory unboundedly.
+      if (!rateLimitMap.has(rateKeyNormalized) && rateLimitMap.size >= MAX_RATE_TRACKED_CLIENTS) {
+        for (const [key, val] of rateLimitMap.entries()) {
+          if (val.resetTime < now) rateLimitMap.delete(key);
+        }
+        if (rateLimitMap.size >= MAX_RATE_TRACKED_CLIENTS) {
+          const oldestKey = rateLimitMap.keys().next().value;
+          if (oldestKey !== undefined) rateLimitMap.delete(oldestKey);
+        }
+      }
+      limit = { count: 1, resetTime: now + RATE_LIMIT_WINDOW };
+      rateLimitMap.set(rateKeyNormalized, limit);
+    } else {
+      limit.count++;
+    }
+
+    const remaining = Math.max(0, MAX_REQUESTS - limit.count);
+    res.setHeader('X-RateLimit-Limit', String(MAX_REQUESTS));
+    res.setHeader('X-RateLimit-Remaining', String(remaining));
+    res.setHeader('X-RateLimit-Reset', String(Math.ceil((limit.resetTime - now) / 1000)));
+
+    if (limit.count > MAX_REQUESTS) {
+      res.setHeader('Content-Type', 'application/json');
+      res.setHeader('Retry-After', String(Math.ceil((limit.resetTime - now) / 1000)));
+      return res.status(429).json({
+        error: "Too Many Requests",
+        message: "Rate limit exceeded. Please slow down.",
+        retryAfter: Math.ceil((limit.resetTime - now) / 1000)
+      });
+    }
+
+    // OPTIONS preflights are answered AFTER being counted against the
+    // caller's rate bucket (v4 fix for unthrottled preflight floods).
+    if (req.method === 'OPTIONS') {
+      return res.status(204).end();
+    }
+
+    // --- 2. SERVE SPEC ENDPOINTS ---
+    
+    // Serve /.well-known/agent-spec & /v1/agent/spec (API Versioning)
+    if (req.path === '/.well-known/agent-spec' || req.path === '/v1/agent/spec') {
+      res.setHeader('Content-Type', 'application/json');
+      res.setHeader('Cache-Control', 'public, max-age=86400, stale-while-revalidate=3600');
+      return res.json({
+        name,
+        description,
+        version: "1.0.0",
+        agentsbloomVersion: "0.4.0",
+        discoveryUrl: `${requestUrl}/v1/agent/spec`,
+        catalogUrl: `${requestUrl}/v1/agent/catalog`,
+        llmsUrl: `${requestUrl}/llms.txt`,
+        security: {
+          rateLimiting: { maxRequestsPerMin: MAX_REQUESTS },
+          captchaBypassing: { supported: true, authHeader: "X-Agent-Signature", webBotAuth: true },
+          idempotency: { supported: true, header: "Idempotency-Key", ttlSeconds: 300 }
+        },
+        actions: Object.entries(actions).reduce((acc, [key, val]) => {
+          acc[key] = {
+            endpoint: `/api/agentsbloom/${key}`,
+            method: val.method || 'POST',
+            description: val.description,
+            params: val.params || {}
+          };
+          return acc;
+        }, {}),
+        authentication: { type: "http-message-signatures-or-x-agent-signature", requiredForWrites: true }
+      });
+    }
+
+    // Serve /.well-known/http-message-signatures-directory
+    // v4 medium pass (V16): the old placeholder key ("placeholder-merchant-key")
+    // was a fake trust anchor - agents could "verify" nothing real against
+    // it while believing they had a genuine merchant key set. Fail closed
+    // instead until the merchant configures their JWKS.
+    if (req.path === '/.well-known/http-message-signatures-directory') {
+      if (!config.merchantJwks) {
+        return res.status(503).json({
+          error: 'JWKS Not Configured',
+          message: 'This store has not published a merchant JWKS. Provide `merchantJwks` in the AgentsBloom SDK config to serve /.well-known/http-message-signatures-directory.'
+        });
+      }
+      res.setHeader('Content-Type', 'application/json');
+      res.setHeader('Cache-Control', 'public, max-age=86400');
+      return res.json(config.merchantJwks);
+    }
+
+    // Serve /.well-known/ucp (Universal Commerce Protocol Profile)
+    if (req.path === '/.well-known/ucp') {
+      res.setHeader('Content-Type', 'application/json');
+      res.setHeader('Cache-Control', 'public, max-age=86400');
+      return res.json({
+        protocol: "ucp",
+        version: "1.0.0",
+        store: { name, description, baseUrl: requestUrl },
+        capabilities: [
+          "dev.ucp.shopping",
+          "dev.ucp.shopping.checkout",
+          "dev.ucp.common.identity_linking"
+        ],
+        endpoints: {
+          catalog: `${requestUrl}/ai-catalog.json`,
+          search: `${requestUrl}/api/agentsbloom/search`,
+          products: `${requestUrl}/api/agentsbloom/products`,
+          cart: `${requestUrl}/api/agentsbloom/cart`,
+          checkout: `${requestUrl}/api/agentsbloom/checkout/acp`
+        },
+        actions: Object.entries(actions).reduce((acc, [key, val]) => {
+          acc[key] = {
+            endpoint: `/api/agentsbloom/${key}`,
+            method: val.method || 'POST',
+            description: val.description,
+            params: val.params || {}
+          };
+          return acc;
+        }, {}),
+        auth: {
+          methods: ["http-message-signatures", "x-agent-signature"]
+        }
+      });
+    }
+
+    // Serve /ai-catalog.json & /v1/agent/catalog (ARD / UCP Compliant)
+    if (req.path === '/ai-catalog.json' || req.path === '/.well-known/ai-catalog.json' || req.path === '/v1/agent/catalog') {
+      res.setHeader('Content-Type', 'application/json');
+      res.setHeader('Cache-Control', 'public, max-age=86400, stale-while-revalidate=3600');
+      return res.json({
+        $schema: "https://universalcommerce.org/schemas/catalog.json",
+        name,
+        description,
+        version: "1.0.0",
+        auth: {
+          supported: ["http-message-signatures", "x-agent-signature"]
+        },
+        items: Object.entries(actions).map(([key, val]) => ({
+          id: key,
+          type: "action",
+          title: key,
+          description: val.description,
+          actionUrl: `${requestUrl}/api/agentsbloom/${key}`
+        }))
+      });
+    }
+
+    // Serve /openapi.json & /schema.json (OpenAPI 3.1 for custom GPT
+    // actions and any OpenAPI-consuming agent). The document is generated
+    // from the merchant's declared actions - previously it hardcoded five
+    // paths, so any custom action (removeFromCart, clearCart, or anything
+    // a merchant added) silently vanished from the OpenAPI surface, and
+    // AP2 endpoints were entirely undocumented.
+    if (req.path === '/openapi.json' || req.path === '/schema.json') {
+      res.setHeader('Content-Type', 'application/json');
+      res.setHeader('Cache-Control', 'public, max-age=86400');
+      return res.json(buildOpenApiDocument({ name, description, requestUrl, actions, signatureAuthEnabled }));
+    }
+
+    // --- Verified-identity bindings, declared BEFORE any closure reads them ---
+    //
+    // The MCP `tools/call` handler below closes over `authenticatedCacheIdentity`
+    // to enforce per-action authorization. That binding used to be declared
+    // ~40 lines LOWER with `let`, after this branch had already returned, so
+    // the closure ran while the binding was still in its temporal dead zone:
+    // every single MCP tool invocation threw
+    //   ReferenceError: Cannot access 'authenticatedCacheIdentity' before initialization
+    // regardless of configuration. Hoisting it here fixes the crash and keeps
+    // the authorization check meaningful.
+    let authenticatedCacheIdentity = null;
+    let signatureProfileUsed = null;
+
+    // Serve MCP SSE Endpoint for Tool Calling
+    // v4: concurrent SSE sessions are bounded (config.mcp.maxSessions,
+    // default 100). Previously every GET /mcp created an unbounded new
+    // transport with no accounting - a trivial socket/memory exhaustion
+    // vector.
+    if (req.path === '/mcp') {
+      const maxMcpSessions = Number.isFinite(config.mcp?.maxSessions) && config.mcp.maxSessions > 0
+        ? config.mcp.maxSessions
+        : 100;
+      if (activeMcpSessions >= maxMcpSessions) {
+        return res.status(503).json({
+          error: "Too Many MCP Sessions",
+          message: `Concurrent MCP session limit (${maxMcpSessions}) reached. Retry later.`
+        });
+      }
+      const transport = new SSEServerTransport('/mcp/messages', res);
+      activeMcpSessions += 1;
+      // The slot must be released exactly once. `res.on('close')` and the
+      // connect() catch below could both fire for one session, drifting the
+      // counter negative and loosening the concurrency cap over time.
+      let sessionSlotReleased = false;
+      const releaseMcpSession = () => {
+        if (sessionSlotReleased) return;
+        sessionSlotReleased = true;
+        activeMcpSessions = Math.max(0, activeMcpSessions - 1);
+        if (transport.sessionId) mcpTransports.delete(transport.sessionId);
+      };
+      res.on('close', releaseMcpSession);
+      // Register the transport so POST /mcp/messages can reach it. Without
+      // this the MCP surface was advertised in every discovery document but
+      // unusable: `/mcp/messages` fell through to next() and no tool call
+      // could ever be delivered. The registry is bounded by the same
+      // maxMcpSessions cap and entries are removed when the stream closes.
+      if (transport.sessionId) mcpTransports.set(transport.sessionId, transport);
+      const mcpServer = new Server({ name: name, version: "1.0.0" }, { capabilities: { tools: {} } });
+      // Auto-generate MCP tool declarations from actions
+      mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: Object.entries(actions).map(([key, val]) => ({
+          name: key,
+          description: val.description,
+          inputSchema: {
+            type: "object",
+            properties: Object.entries(val.params || {}).reduce((acc, [pkey, pval]) => {
+              acc[pkey] = { type: pval };
+              return acc;
+            }, {})
+          }
+        }))
+      }));
+
+      mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const action = actions[request.params.name];
+        if (!action) throw new Error(`Tool not found: ${request.params.name}`);
+        // v4 medium pass (V12): the same per-action authorization model
+        // applies to MCP tool invocations.
+        //
+        // The identity is read from the TRANSPORT, not from this closure's
+        // captured `authenticatedCacheIdentity`. That variable belongs to the
+        // GET /mcp request that opened the SSE stream — which is not a
+        // protected action path, so it is always null. Authorizing against it
+        // meant `actionAccess: 'authenticated'` could never be satisfied and
+        // `actionIdentities` could never match. The verified identity of the
+        // POST /mcp/messages request that actually carries the tool call is
+        // stashed on the transport by that handler.
+        const mcpIdentity = transport.__agentsbloomIdentity ?? null;
+        req.agentIdentity = mcpIdentity;
+        const accessRejection = authorizeAction(request.params.name, mcpIdentity);
+        if (accessRejection) throw new Error(accessRejection.body.message);
+        // v4: enforce the declared parameter contract. The REST route has
+        // always validated/coerced params; the MCP path now does too, so
+        // merchants get identical type guarantees on both surfaces.
+        const validation = validateActionParams(request.params.arguments || {}, action);
+        if (!validation.ok) throw new Error(validation.message);
+        const result = await action.handler(validation.params, req, res);
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      });
+
+      // Second-pass review (N4): if connect() rejects, release the session
+      // slot immediately instead of waiting for a close event that may not
+      // fire for a transport that never started.
+      try {
+        return await mcpServer.connect(transport);
+      } catch (err) {
+        releaseMcpSession();
+        throw err;
+      }
+    }
+
+    // Serve /llms.txt
+    if (req.path === '/llms.txt') {
+      res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+      res.setHeader('Cache-Control', 'public, max-age=86400, stale-while-revalidate=3600');
+      const defaultLlmDoc = `# ${name}\n\n${description}\n\n## Developer API Reference\n\n- GET /.well-known/agent-spec : Spec sheets\n- GET /ai-catalog.json : Catalog schemas\n- GET /openapi.json : OpenAPI 3.1 schema\n`;
+      const docContent = typeof llmsDoc === 'function' ? llmsDoc() : (llmsDoc || defaultLlmDoc);
+      return res.send(docContent);
+    }
+
+    // --- 3. IDEMPOTENCY METADATA FOR WRITES (POST/PUT/PATCH/DELETE) ---
+    const method = String(req.method || '').toUpperCase();
+    const isWrite = ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method);
+    const rawIdempotencyKey = req.headers['idempotency-key'];
+    const idempotencyHeader = typeof rawIdempotencyKey === 'string' ? rawIdempotencyKey : null;
+    let idempotencyKey = null;
+    // `authenticatedCacheIdentity` / `signatureProfileUsed` are declared above
+    // the /mcp branch so its tool-call closure can read them.
+
+    // --- 4. CRYPTOGRAPHIC CAPTCHA BYPASSING (Web Bot Auth + Legacy HMAC) ---
+    const isMcpMessage = req.path === '/mcp/messages' && method === 'POST';
+    // Second-pass review (N3): AP2 intent/checkout POSTs are now part of the
+    // signature gate. The agent-side SDK has always signed these posts, but
+    // the merchant gate ignored them - so a mandate alone could check out
+    // anonymously, and per-action authorization policies could never see a
+    // verified identity on the most valuable endpoint. A verified mandate
+    // proves budget INTENT; a signature proves who is spending it.
+    const isAp2WritePath = method === 'POST' && (
+      req.path === '/ap2/intent'
+      || req.path === '/ap2/checkout'
+      || req.path === '/v1/ap2/intent'
+      || req.path === '/v1/ap2/checkout'
+    );
+    const isAgentAction = req.path.startsWith('/api/agentsbloom/')
+      || req.path.startsWith('/v1/agent/actions/')
+      || isMcpMessage
+      || isAp2WritePath;
+    // v4 medium pass (V12): resolve which action (if any) this path targets
+    // so per-action authorization can require verification even on reads.
+    let requestedActionName = null;
+    if (req.path.startsWith('/api/agentsbloom/')) {
+      requestedActionName = req.path.slice('/api/agentsbloom/'.length);
+    } else if (req.path.startsWith('/v1/agent/actions/')) {
+      requestedActionName = req.path.slice('/v1/agent/actions/'.length);
+    }
+    const needsAuthenticatedRead = Boolean(
+      requestedActionName && actionAccess?.[requestedActionName] === 'authenticated'
+    );
+    if (isAgentAction && (isWrite || needsAuthenticatedRead) && signatureAuthEnabled) {
+      const signature = req.headers['x-agent-signature'];
+      const identifier = req.headers['x-agent-identifier'];
+      const timestamp = req.headers['x-agent-timestamp'];
+      const nonce = req.headers['x-agent-nonce'];
+      
+      const rfcSignature = req.headers['signature'];
+      const rfcSignatureInput = req.headers['signature-input'];
+      const hasRfcSignature = typeof rfcSignature === 'string' && rfcSignature.length > 0;
+      const hasRfcSignatureInput = typeof rfcSignatureInput === 'string' && rfcSignatureInput.length > 0;
+
+      if (!signature && !hasRfcSignature && !hasRfcSignatureInput) {
+        return res.status(401).json({
+          error: "Verification Required",
+          message: "CAPTCHA check required. Please provide standard RFC 9421 HTTP Message Signatures or the legacy X-Agent-Signature."
+        });
+      }
+
+      if (hasRfcSignature !== hasRfcSignatureInput) {
+        return res.status(403).json({
+          error: "Verification Failed",
+          message: "Signature and Signature-Input headers must be provided together."
+        });
+      }
+      
+      if (hasRfcSignature) {
+        // RFC 9421 verification now lives in lib/http-signatures.js: real
+        // structured-field parsing, canonical signature base, curve/modulus
+        // pinning, ECDSA P1363, authority validation, digest over the received
+        // bytes, and a replay record that outlives the acceptance window.
+        const verification = await verifyHttpMessageSignature({
+          req,
+          requestContext: requestContextFromExpress(req, { forwardedProto }),
+          signatureHeader: rfcSignature,
+          signatureInputHeader: rfcSignatureInput,
+          jwks: config.agentJwks || null,
+          jwksUrl: typeof config.agentJwksUrl === 'string' ? config.agentJwksUrl : null,
+          jwksCache,
+          nonceCache: signatureNonceMap,
+          nonceNamespace: cacheNamespace,
+          maxAgeMs: signatureMaxAgeMs,
+          clockSkewMs: RFC_SIGNATURE_CLOCK_SKEW_MS,
+          requireAuthority: signatureRequireAuthority,
+          expectedAuthorities,
+          acceptLegacyProfile: acceptLegacySignatureProfile,
+          allowReserializedBody,
+        });
+
+        if (!verification.ok) {
+          // Verifier internals (expected values, raw crypto error text, which
+          // JWKS key was missing) stay server-side. The caller gets a stable
+          // machine-readable code and a generic message.
+          console.error(
+            `🌸 AgentsBloom: RFC 9421 signature verification failed [${verification.code}]: ${verification.detail}`,
+          );
+          return res.status(verification.status).json({
+            error: verification.status === 503 ? 'Service Unavailable' : 'Forbidden',
+            code: verification.code,
+            message: verification.publicMessage,
+          });
+        }
+        authenticatedCacheIdentity = verification.identity;
+        signatureProfileUsed = verification.profile;
+      } else {
+        // v4 medium pass (V11): resolve a PER-AGENT secret when one is
+        // configured, and reject revoked identifiers outright.
+        if (revokedIdentifiers && typeof identifier === 'string' && revokedIdentifiers.has(identifier)) {
+          return res.status(403).json({
+            error: "Verification Failed",
+            message: "X-Agent-Identifier has been revoked."
+          });
+        }
+        const perAgentSecret = agentKeys && typeof identifier === 'string' ? agentKeys[identifier] : undefined;
+        const effectiveSecret = (typeof perAgentSecret === 'string' && perAgentSecret.length > 0)
+          ? perAgentSecret
+          : agentSecret;
+
+        const headerValuePattern = /^[\x21-\x7e]+$/;
+        if (
+          !effectiveSecret ||
+          typeof signature !== 'string' ||
+          typeof identifier !== 'string' ||
+          typeof timestamp !== 'string' ||
+          typeof nonce !== 'string' ||
+          identifier.length > 256 ||
+          nonce.length < 16 ||
+          nonce.length > 256 ||
+          !headerValuePattern.test(identifier) ||
+          !headerValuePattern.test(timestamp) ||
+          !headerValuePattern.test(nonce)
+        ) {
+          return res.status(403).json({
+            error: "Verification Failed",
+            message: "X-Agent-Signature requires a configured secret, identifier, timestamp, and nonce."
+          });
+        }
+
+        // Bound the timestamp string before Number() so a 10,000-digit value
+        // never reaches the parser.
+        const timestampSeconds = timestamp.length <= 20 ? Number(timestamp) : NaN;
+        const timestampMs = timestampSeconds * 1000;
+        const nowMs = Date.now();
+        if (!Number.isSafeInteger(timestampSeconds) || Math.abs(nowMs - timestampMs) > signatureMaxAgeMs) {
+          return res.status(403).json({
+            error: "Verification Failed",
+            message: "X-Agent-Signature is expired or has an invalid timestamp."
+          });
+        }
+
+        const replayKey = `${cacheNamespace}:legacy:${identifier}:${nonce}`;
+
+        let signaturePayload;
+        try {
+          signaturePayload = buildLegacySignaturePayload(req, identifier, timestamp, nonce);
+        } catch {
+          return res.status(400).json({
+            error: "Invalid Request",
+            message: "Request body cannot be serialized for signature verification."
+          });
+        }
+        // Rotation window: a signature minted under the PREVIOUS secret
+        // still verifies while merchants roll AGENTSBLOOM_SECRET. Per-agent
+        // keys (V11) are checked first; the shared secret(s) remain the
+        // fallback so existing agents keep working during migration.
+        if (!verifySignature(signature, signaturePayload, effectiveSecret)
+          && !(agentSecret && agentSecret !== effectiveSecret && verifySignature(signature, signaturePayload, agentSecret))
+          && !(agentSecretPrevious && verifySignature(signature, signaturePayload, agentSecretPrevious))) {
+          return res.status(403).json({
+            error: "Verification Failed",
+            message: "X-Agent-Signature is invalid. Access denied."
+          });
+        }
+
+        // v4: atomic claim AFTER successful verification - failed attempts
+        // never burn the nonce, and concurrent replays cannot slip through
+        // the old has()/set() race window.
+        //
+        // The record must outlive the window in which this signature could
+        // still be accepted. `timestampMs + signatureMaxAgeMs` alone was too
+        // short for a timestamp already near the edge of the window: the
+        // nonce expired while the signature was still considered fresh,
+        // re-opening replay. Floor it at now + the full window.
+        const legacyRetainUntilMs = Math.max(
+          timestampMs + signatureMaxAgeMs,
+          nowMs + signatureMaxAgeMs,
+        );
+        const claimed = await signatureNonceMap.claim(replayKey, legacyRetainUntilMs);
+        if (!claimed) {
+          return res.status(403).json({
+            error: "Verification Failed",
+            message: "X-Agent-Signature nonce has already been used."
+          });
+        }
+        authenticatedCacheIdentity = `legacy:${identifier}`;
+      }
+    }
+
+    // Expose the verified signature identity (rfc:<keyid> or legacy:<id>)
+    // to merchant handlers: stores persist it on orders to correlate
+    // purchases with the agent-reputation system. Null for unsigned
+    // traffic - never trust the raw self-asserted header alone.
+    req.agentIdentity = authenticatedCacheIdentity;
+    req.agentSignatureProfile = signatureProfileUsed;
+
+    // --- MCP message delivery ---
+    //
+    // Routed here, AFTER the signature gate, so a tool call carries a verified
+    // identity. Previously this path was never wired at all: `/mcp` handed the
+    // client a `/mcp/messages` endpoint, but a POST to it fell straight through
+    // to next(), so the MCP surface advertised in every discovery document
+    // could not actually execute a tool.
+    if (isMcpMessage) {
+      const sessionId = typeof req.query?.sessionId === 'string' ? req.query.sessionId : null;
+      const transport = sessionId ? mcpTransports.get(sessionId) : null;
+      if (!transport) {
+        return res.status(404).json({
+          error: 'Unknown MCP Session',
+          message: 'No open MCP SSE session matches this sessionId. Open GET /mcp first and reuse the endpoint it returns.',
+        });
+      }
+      // Hand the verified identity to the tool-call handler, which runs in the
+      // SSE request's closure and therefore cannot see this request directly.
+      transport.__agentsbloomIdentity = authenticatedCacheIdentity;
+      try {
+        return await transport.handlePostMessage(req, res, req.body);
+      } catch (err) {
+        console.error('🌸 AgentsBloom: MCP message delivery failed:', err?.message);
+        if (!res.headersSent) {
+          return res.status(400).json({ error: 'Invalid MCP Message' });
+        }
+        return undefined;
+      }
+    }
+
+    // --- 3b. IDEMPOTENCY CHECKS FOR WRITES (POST/PUT/PATCH/DELETE) ---
+    // Perform this lookup only after the protected-route authentication gate.
+    // Cache keys are scoped to this middleware instance and the verified agent
+    // identity so one caller cannot replay another caller's cached response.
+    if (isWrite && idempotencyHeader) {
+      const requestedIdentity = typeof req.headers['x-agent-identifier'] === 'string'
+        ? req.headers['x-agent-identifier']
+        : 'anonymous';
+      const cacheIdentity = authenticatedCacheIdentity || `anonymous:${requestedIdentity}`;
+      let serializedRequestBody;
+      try {
+        serializedRequestBody = JSON.stringify(req.body ?? null);
+      } catch {
+        return res.status(400).json({
+          error: "Invalid Request",
+          message: "Request body cannot be serialized for idempotency verification."
+        });
+      }
+      const cacheKeyMaterial = [
+        cacheNamespace,
+        cacheIdentity,
+        method,
+        req.originalUrl || req.path,
+        serializedRequestBody,
+        idempotencyHeader,
+      ].join('\u0000');
+      idempotencyKey = `${cacheNamespace}:${crypto.createHash('sha256').update(cacheKeyMaterial).digest('hex')}`;
+
+      for (const [key, val] of idempotencyMap.entries()) {
+        if (val.expiry < now) {
+          idempotencyMap.delete(key);
+        }
+      }
+
+      const cachedResponse = idempotencyMap.get(idempotencyKey);
+      if (cachedResponse) {
+        res.setHeader('X-Cache', 'Idempotent-Hit');
+        res.setHeader('Content-Type', cachedResponse.headers['content-type'] || 'application/json');
+        return res.status(cachedResponse.status).send(cachedResponse.responseBody);
+      }
+    }
+
+    /**
+     * Installs store-and-replay capture for the current Idempotency-Key.
+     *
+     * Previously this patch was installed ONLY inside the REST action-routing
+     * branch, so `/ap2/checkout` and `/api/agentsbloom/checkout/acp` — the two
+     * endpoints that mint payment links — accepted an Idempotency-Key, served
+     * no replay for it, and re-ran the checkout handler on every retry.
+     *
+     * Safe to call more than once; the patch installs at most once per
+     * response.
+     */
+    function captureIdempotentResponse(response) {
+      if (!isWrite || !idempotencyKey || response.__agentsbloomIdempotencyPatched) return;
+      response.__agentsbloomIdempotencyPatched = true;
+      const originalSend = response.send;
+      response.send = function patchedSend(body) {
+        if (response.statusCode >= 200 && response.statusCode < 300) {
+          // v4 (V18): evict the oldest entry at capacity instead of growing
+          // without bound between TTL sweeps.
+          if (!idempotencyMap.has(idempotencyKey) && idempotencyMap.size >= IDEMPOTENCY_MAX_ENTRIES) {
+            const oldestKey = idempotencyMap.keys().next().value;
+            if (oldestKey !== undefined) idempotencyMap.delete(oldestKey);
+          }
+          idempotencyMap.set(idempotencyKey, {
+            responseBody: body,
+            status: response.statusCode,
+            headers: { 'content-type': response.getHeader('content-type') },
+            timestamp: Date.now(),
+            expiry: Date.now() + IDEMPOTENCY_TTL,
+          });
+        }
+        return originalSend.apply(this, arguments);
+      };
+    }
+
+    // --- 4b. AP2 MANDATE VERIFICATION (Wired into middleware) ---
+    // v4: the legacy `authorization` header fallback is now only honored on
+    // requests that are ALREADY AP2-shaped (an /ap2 path or x-protocol AP2).
+    // Previously ANY request carrying a dotted Authorization value - which
+    // includes every ordinary OAuth/JWT bearer token - was parsed as an AP2
+    // SD-JWT, failed verification, and had the whole request rejected 403,
+    // breaking unrelated authenticated routes. The explicit
+    // `x-ap2-mandate` header works everywhere as before.
+    const detectedProtocol = resolveProtocol(req);
+    const rawAuthorizationHeader = req.headers['authorization'];
+    const ap2MandateHeader = req.headers['x-ap2-mandate']
+      || (detectedProtocol === 'AP2' && typeof rawAuthorizationHeader === 'string'
+        ? rawAuthorizationHeader
+        : null);
+    let ap2MandateResult = null;
+
+    if (detectedProtocol === 'AP2' || (ap2MandateHeader && ap2MandateHeader.includes('.'))) {
+      // Second-pass review (N2): the mandate's single-use jti must only be
+      // consumed where the mandate is actually USED. Verification still
+      // runs wherever a mandate is presented (so merchant handlers keep
+      // receiving req.ap2Mandate), but a mandate riding along on an
+      // unrelated cart-add no longer burns itself.
+      const isAp2Endpoint = req.path.startsWith('/ap2/') || req.path.startsWith('/v1/ap2/');
+      // Cart Mandate binding: only the checkout consumer recomputes the
+      // merchant's canonical cart hash. A merchant that configures
+      // ap2.computeCartHash(req) gets a hard reject when a cart-bound
+      // mandate is presented against different cart contents; without the
+      // callback, binding stays 'unverified' (surfaced, never silent).
+      const isAp2CheckoutPath = req.path === '/ap2/checkout' || req.path === '/v1/ap2/checkout';
+      let expectedCartHash = null;
+      let cartHashComputationFailed = false;
+      if (isAp2CheckoutPath && typeof config.ap2?.computeCartHash === 'function') {
+        try {
+          expectedCartHash = config.ap2.computeCartHash(req) || null;
+        } catch (err) {
+          // A throwing hook used to be swallowed into `null`, which silently
+          // downgraded a cart-bound mandate to 'unverified' — exactly the
+          // state the checkout gate is supposed to refuse. Record the failure
+          // so the gate can reject instead of guessing.
+          cartHashComputationFailed = true;
+          expectedCartHash = null;
+          console.error('🌸 AgentsBloom: ap2.computeCartHash threw; treating the session cart as unverifiable:', err?.message);
+        }
+      }
+      // Verify the SD-JWT mandate before allowing any write action. Uses
+      // either a merchant-configured trusted public key (config.ap2PublicKey)
+      // or, when absent, derives a key from the mandate's own did:key issuer
+      // (self-certifying - see lib/ap2.js for why an unverifiable mandate is
+      // now rejected outright rather than passed through as "valid").
+      ap2MandateResult = await verifyAP2Mandates(req.headers, req.body || {}, {
+        trustedPublicKey: config.ap2PublicKey || null,
+        // v4: production-grade trust policy. When ap2.trustedIssuersOnly is
+        // set, self-certifying did:key mandates (which anyone can mint for
+        // any budget) are rejected in favor of the merchant-trusted key.
+        allowSelfCertifying: config.ap2?.trustedIssuersOnly !== true,
+        // Audience binding prefers explicit configuration, then the
+        // merchant-configured baseUrl (a trusted deployment constant), and
+        // only falls back to the Host-derived requestUrl when neither is
+        // set - deriving the expected audience purely from the request's
+        // own Host header would let an attacker align a stolen mandate's
+        // audience with a spoofed Host.
+        expectedAudience: config.ap2?.expectedAudience || (baseUrl ? baseUrl : requestUrl),
+        maxMandateLifetimeSec: config.ap2?.maxMandateLifetimeSec,
+        requireJti: config.ap2?.requireJti,
+        requestedCategories: req.body?.requestedCategories || config.ap2?.requestedCategories,
+        expectedCurrency: config.ap2?.expectedCurrency,
+        requireCurrency: config.ap2?.requireCurrency !== false,
+        clockSkewSec: config.ap2?.clockSkewSec,
+        consumeJti: isAp2Endpoint,
+        ...(isAp2CheckoutPath ? { expectedCartHash } : {}),
+      });
+
+      if (!ap2MandateResult.valid) {
+        // Disclosure policy: an agent must be able to learn that its budget is
+        // too low or its cart does not match, so it can self-correct. It must
+        // NOT learn this store's expected audience or currency, which JWKS key
+        // was missing, or raw crypto error text. lib/ap2.js classifies each
+        // rejection; the HTTP layer honors that classification.
+        const discloseReason = config.ap2?.exposeReasons === true || ap2MandateResult.disclose === true;
+        if (!discloseReason) {
+          console.error(
+            `🌸 AgentsBloom: AP2 mandate rejected [${ap2MandateResult.code}]: ${ap2MandateResult.reason}`,
+          );
+        }
+        return res.status(403).json({
+          error: "AP2 Mandate Rejected",
+          protocol: "AP2",
+          code: ap2MandateResult.code,
+          reason: discloseReason ? ap2MandateResult.reason : ap2MandateResult.publicReason,
+          message: "The Verifiable Intent mandate failed validation. The agent's payment authorization is invalid."
+        });
+      }
+
+      // Attach mandate info to request for downstream handlers
+      req.ap2Mandate = ap2MandateResult;
+      ap2MandateResult.cartHashComputationFailed = cartHashComputationFailed;
+    }
+
+    // --- AP2 Discovery Endpoint ---
+    if (req.path === '/ap2/capabilities' || req.path === '/v1/ap2/capabilities') {
+      return res.json({
+        protocol: "AP2",
+        version: "1.0.0",
+        store: { name, description, baseUrl: requestUrl },
+        mandateTypes: ["intentMandate", "cartMandate", "paymentMandate"],
+        verificationMethods: ["sd-jwt", "jwt"],
+        features: {
+          budgetEnforcement: true,
+          cartBinding: true,
+          currencyBinding: true,
+          replayProtection: true
+        },
+        endpoints: {
+          capabilities: `${requestUrl}/ap2/capabilities`,
+          intent: `${requestUrl}/ap2/intent`,
+          checkout: `${requestUrl}/ap2/checkout`,
+          actions: Object.keys(actions).map(k => `${requestUrl}/v1/agent/actions/${k}`)
+        },
+        budgetEnforcement: true,
+        // Advertise what the verifier actually accepts. The old hardcoded list
+        // claimed ES256/384/512 support while ECDSA verification was broken
+        // outright (DER vs raw r||s), so an agent that followed the discovery
+        // document could never authenticate.
+        signatureAlgorithms: [...SUPPORTED_MANDATE_ALGORITHMS]
+      });
+    }
+
+    // --- AP2 Intent Endpoint (agent announces what it wants to do) ---
+    if ((req.path === '/ap2/intent' || req.path === '/v1/ap2/intent') && req.method === 'POST') {
+      // Must check `.verified`, not mere truthiness: ap2MandateResult is a
+      // truthy object even when no mandate header was ever presented
+      // (`{ valid: true, verified: false, note: '...' }`), so a bare
+      // `if (!ap2MandateResult)` check would let unauthenticated requests
+      // reach this mandate-gated endpoint.
+      if (!ap2MandateResult?.verified) {
+        return res.status(401).json({
+          error: "AP2 Mandate Required",
+          message: "Send x-ap2-mandate: Bearer <sd-jwt> header with a valid Intent Mandate."
+        });
+      }
+      return res.json({
+        protocol: "AP2",
+        intentAccepted: true,
+        mandateVerified: ap2MandateResult.verified,
+        mandates: ap2MandateResult.mandates || {},
+        availableActions: Object.entries(actions).map(([key, val]) => ({
+          action: key,
+          endpoint: `/v1/agent/actions/${key}`,
+          method: val.method || 'POST',
+          description: val.description
+        })),
+        budgetRemaining: ap2MandateResult.mandates?.intentMandate?.maxBudget || "unlimited"
+      });
+    }
+
+    // --- AP2 Checkout Endpoint (mandate-gated checkout) ---
+    if ((req.path === '/ap2/checkout' || req.path === '/v1/ap2/checkout') && req.method === 'POST') {
+      // Same fix as /ap2/intent above: this MUST require a genuinely
+      // verified mandate, not just a truthy result object. Previously,
+      // hitting /ap2/checkout with no x-ap2-mandate header at all still
+      // produced a truthy `ap2MandateResult` (valid:true, verified:false),
+      // which passed this check, then found no `.mandates.intentMandate`
+      // to read a maxBudget from - so checkout proceeded with ZERO budget
+      // enforcement. Requiring `.verified` closes that bypass.
+      if (!ap2MandateResult?.verified) {
+        return res.status(401).json({
+          error: "AP2 Payment Mandate Required",
+          message: "AP2 checkout requires x-ap2-mandate header with a valid Payment Mandate."
+        });
+      }
+
+      // Hardened Cart Mandate verification: If the mandate declares an exact
+      // Cart Mandate (signed cartHash), the store MUST verify that cartHash
+      // against the actual session cart. Unverified cart mandates are rejected
+      // unless explicitly allowed by config (allowUnverifiedCartMandates: true).
+      const hasDeclaredCartMandate = Boolean(ap2MandateResult.mandates?.cartMandate?.cartHash);
+      if (
+        hasDeclaredCartMandate &&
+        ap2MandateResult.cartBinding === 'unverified' &&
+        config.ap2?.allowUnverifiedCartMandates !== true
+      ) {
+        return res.status(403).json({
+          error: "AP2 Cart Mandate Verification Required",
+          protocol: "AP2",
+          code: 'cart_binding_unverified',
+          reason: ap2MandateResult.cartHashComputationFailed
+            ? "This mandate is cryptographically bound to an exact cart hash, but this store's computeCartHash hook failed, so the session cart could not be verified."
+            : "This mandate is cryptographically bound to an exact cart hash, but this store has not verified the session cart (configure config.ap2.computeCartHash).",
+          message: "Cart Mandate verification failed: the store cannot confirm the session cart matches the signed mandate."
+        });
+      }
+
+      const checkoutAction = actions['checkout'];
+      if (!checkoutAction || typeof checkoutAction.handler !== 'function') {
+        return res.status(404).json({ error: 'Checkout action not configured for this store.' });
+      }
+
+      // v4 medium pass (V12): mandate verification proves budget intent,
+      // not identity authorization - the checkout action still respects
+      // the merchant's per-action policy.
+      const checkoutAccessRejection = authorizeAction('checkout', authenticatedCacheIdentity);
+      if (checkoutAccessRejection) {
+        return res.status(checkoutAccessRejection.status).json(checkoutAccessRejection.body);
+      }
+
+      // The declared parameter contract was enforced on every REST action and
+      // on MCP tool calls, but NOT here — the highest-value endpoint in the
+      // SDK passed `req.body` to the handler unvalidated.
+      const checkoutValidation = validateActionParams({ ...(req.body || {}) }, checkoutAction);
+      if (!checkoutValidation.ok) {
+        return res.status(400).json({
+          error: "Invalid Parameter",
+          protocol: "AP2",
+          message: checkoutValidation.message,
+        });
+      }
+
+      // --- Budget enforcement ---
+      //
+      // A checkout mandate MUST declare a positive maxBudget: a capless
+      // mandate authorizes unlimited spend.
+      //
+      // Note `??` rather than `||`. With `||`, an `orderTotal` of 0 fell
+      // through to `total`, and a `maxBudget` of 0 fell through to the payment
+      // mandate's — both silent value substitutions on a money field.
+      const rawOrderTotal = req.body?.orderTotal ?? req.body?.total ?? 0;
+      const rawMaxBudget = ap2MandateResult.mandates?.intentMandate?.maxBudget
+                        ?? ap2MandateResult.mandates?.paymentMandate?.maxBudget;
+
+      const maxBudgetAmount = parseAmount(rawMaxBudget, { allowZero: false });
+      if (maxBudgetAmount === null) {
+        return res.status(403).json({
+          error: "AP2 Mandate Rejected",
+          protocol: "AP2",
+          code: 'budget_missing',
+          reason: "Mandate must declare a positive intentMandate.maxBudget for checkout",
+          message: "A checkout mandate without a spending cap authorizes unlimited spend and is rejected. Reissue the mandate with maxBudget."
+        });
+      }
+
+      // The client-declared total is a fast-fail convenience only. It is
+      // attacker-controlled and never the basis of authorization — but it must
+      // still be well-formed, because `Number('abc')` is NaN and every
+      // comparison against NaN is false, so a malformed total used to PASS
+      // this check instead of failing it.
+      const clientTotalAmount = parseAmount(rawOrderTotal, { allowZero: true });
+      if (clientTotalAmount === null) {
+        return res.status(400).json({
+          error: "Invalid Request",
+          protocol: "AP2",
+          code: 'order_total_invalid',
+          message: "orderTotal must be a non-negative number.",
+        });
+      }
+
+      // v4 medium pass (V17): a budget number without a matching currency is
+      // unitless. lib/ap2.js already rejects a mandate that declares a budget
+      // with no currency (`requireCurrency`); these checks pin it to the
+      // store's and the order's currency.
+      const mandateCurrency = normalizeCurrencyCode(
+        ap2MandateResult.mandates?.intentMandate?.currency
+        ?? ap2MandateResult.mandates?.paymentMandate?.currency,
+      );
+      const expectedCheckoutCurrency = normalizeCurrencyCode(config.ap2?.expectedCurrency);
+      if (mandateCurrency && expectedCheckoutCurrency && mandateCurrency !== expectedCheckoutCurrency) {
+        // Echoing the store's configured currency back is a config disclosure;
+        // log it, tell the caller only that there is a mismatch.
+        console.error(
+          `🌸 AgentsBloom: AP2 checkout currency mismatch: mandate "${mandateCurrency}" vs store "${expectedCheckoutCurrency}"`,
+        );
+        return res.status(403).json({
+          error: "AP2 Mandate Rejected",
+          protocol: "AP2",
+          code: 'currency_mismatch_store',
+          reason: config.ap2?.exposeReasons === true
+            ? `Mandate currency "${mandateCurrency}" does not match this store's expected currency "${expectedCheckoutCurrency}"`
+            : 'The mandate was issued for a different currency than this store accepts.',
+          message: "The mandate was issued for a different currency than this store accepts."
+        });
+      }
+      const orderCurrency = req.body?.currency === undefined || req.body?.currency === null
+        ? null
+        : normalizeCurrencyCode(req.body.currency);
+      if (req.body?.currency !== undefined && req.body?.currency !== null && !orderCurrency) {
+        return res.status(400).json({
+          error: "Invalid Request",
+          protocol: "AP2",
+          code: 'order_currency_invalid',
+          message: "currency must be a valid ISO 4217 alphabetic code.",
+        });
+      }
+      if (mandateCurrency && orderCurrency && mandateCurrency !== orderCurrency) {
+        return res.status(403).json({
+          error: "AP2 Budget Exceeded",
+          protocol: "AP2",
+          code: 'currency_mismatch_order',
+          reason: `Order currency "${orderCurrency}" does not match the mandate's currency "${mandateCurrency}"`,
+          message: "Order currency does not match the mandate's declared currency."
+        });
+      }
+
+      // Exact comparison. `Number(a) > Number(b)` on doubles could accept a
+      // total a fraction of a cent over the authorized cap.
+      if (compareAmounts(clientTotalAmount.decimal, maxBudgetAmount.decimal) === 1) {
+        return res.status(403).json({
+          error: "AP2 Budget Exceeded",
+          protocol: "AP2",
+          code: 'budget_exceeded',
+          orderTotal: Number(clientTotalAmount.decimal),
+          maxBudget: Number(maxBudgetAmount.decimal),
+          message: `Order total ${clientTotalAmount.decimal} exceeds mandate budget limit of ${maxBudgetAmount.decimal}.`
+        });
+      }
+
+      const issuerTrust = ap2MandateResult.selfCertifying ? 'self-certifying' : 'merchant-trusted';
+      // Store-and-replay for the Idempotency-Key. Every REST action installed
+      // this; /ap2/checkout did not, so a retried checkout re-ran the handler.
+      captureIdempotentResponse(res);
+
+      return Promise.resolve(checkoutAction.handler(checkoutValidation.params, req, res))
+        .then(result => {
+          const rawServerTotal = result && (result.total ?? result.totalPrice);
+          const serverTotalAmount = rawServerTotal === undefined || rawServerTotal === null
+            ? null
+            : parseAmount(rawServerTotal, { allowZero: true });
+
+          // --- The authoritative check ---
+          //
+          // This is the bypass that mattered most. The old code computed
+          //   effectiveTotal = serverTotal !== undefined ? Number(serverTotal) : Number(orderTotal)
+          // and then only enforced the cap `if (Number.isFinite(effectiveTotal))`.
+          // So a handler that returned no total at all, or a non-numeric one,
+          // produced NaN, `Number.isFinite(NaN)` was false, and the budget
+          // check was SKIPPED ENTIRELY — a payment URL was issued with zero
+          // enforcement while the response still reported budgetEnforced:true.
+          //
+          // A total we cannot parse is now a hard failure, never a pass.
+          if (serverTotalAmount === null) {
+            if (config.ap2?.requireHandlerTotal === false) {
+              // Explicit opt-out: fall back to the client-declared total,
+              // which was already validated and compared above. Reported
+              // honestly as such so nobody mistakes it for enforcement.
+              if (!res.headersSent) {
+                res.json(buildAp2CheckoutResponse({
+                  result,
+                  totalSource: 'client-declared',
+                  orderTotalDecimal: clientTotalAmount.decimal,
+                }));
+              }
+              return undefined;
+            }
+            console.error(
+              '🌸 AgentsBloom: the checkout handler returned no usable `total`/`totalPrice`, so the AP2 mandate budget '
+              + `cannot be enforced (received: ${JSON.stringify(rawServerTotal)}). Return a numeric total, or set `
+              + 'ap2.requireHandlerTotal:false to authorize against the client-declared total instead.',
+            );
+            if (!res.headersSent) {
+              res.status(500).json({
+                error: 'AP2 Checkout Misconfigured',
+                protocol: 'AP2',
+                code: 'handler_total_missing',
+                message: 'This store could not compute an authoritative order total, so the mandate budget could not be enforced. No checkout link was issued.',
+              });
+            }
+            return undefined;
+          }
+
+          if (compareAmounts(serverTotalAmount.decimal, maxBudgetAmount.decimal) === 1) {
+            if (!res.headersSent) {
+              res.status(403).json({
+                error: "AP2 Budget Exceeded",
+                protocol: "AP2",
+                code: 'budget_exceeded_server',
+                reason: "Server-computed order total exceeds the mandate's maxBudget; the client-declared orderTotal is never authoritative.",
+                orderTotal: Number(serverTotalAmount.decimal),
+                totalSource: 'handler',
+                maxBudget: Number(maxBudgetAmount.decimal),
+                message: `Order total ${serverTotalAmount.decimal} computed by the store exceeds mandate budget limit of ${maxBudgetAmount.decimal}. No checkout link was issued.`
+              });
+            }
+            return undefined;
+          }
+
+          if (!res.headersSent) {
+            res.json(buildAp2CheckoutResponse({
+              result,
+              totalSource: 'handler',
+              orderTotalDecimal: serverTotalAmount.decimal,
+            }));
+          }
+          return undefined;
+        })
+        .catch(err => {
+          console.error("AP2 Checkout error:", err);
+          if (!res.headersSent) {
+            res.status(500).json({ error: 'Internal AP2 checkout error', protocol: 'AP2' });
+          }
+        });
+
+      /** Shapes the authorized-checkout response with honest evidence. */
+      function buildAp2CheckoutResponse({ result, totalSource, orderTotalDecimal }) {
+        return {
+          protocol: "AP2",
+          verifiableIntent: {
+            mandateVerified: ap2MandateResult.verified,
+            // Reports what actually happened rather than `!!maxBudget`: the
+            // cap was compared against a store-computed total only when the
+            // handler supplied one.
+            budgetEnforced: totalSource === 'handler',
+            issuerTrust,
+            cartBinding: ap2MandateResult.cartBinding || 'absent',
+            maxBudget: Number(maxBudgetAmount.decimal),
+            currency: mandateCurrency || null,
+            orderTotal: Number(orderTotalDecimal),
+            totalSource,
+            signatureIdentity: authenticatedCacheIdentity,
+            ...(signatureProfileUsed ? { signatureProfile: signatureProfileUsed } : {}),
+          },
+          session_id: result?.sessionId || `ap2_sess_${crypto.randomUUID()}`,
+          payment_url: result?.paymentUrl,
+          status: "authorized",
+          expires_at: Math.floor(Date.now() / 1000) + 3600,
+          checkout: result
+        };
+      }
+    }
+
+    // --- 5. HANDLE ACTION ROUTING ---
+    // Agentic Commerce Protocol (ACP) Checkout Wrapper
+    //
+    // This branch returns before the action-routing branch below, so it used
+    // to skip BOTH `authorizeAction` and `validateActionParams`: a store that
+    // configured `actionAccess.checkout = 'authenticated'` or restricted
+    // `actionIdentities.checkout` had those policies silently ignored on this
+    // path, and the handler received an unvalidated body. The RFC/legacy
+    // signature gate did apply (the path is under /api/agentsbloom/), but
+    // per-action authorization did not.
+    if (req.path === '/api/agentsbloom/checkout/acp' && req.method === 'POST') {
+      const checkoutAction = actions['checkout'];
+      if (checkoutAction && typeof checkoutAction.handler === 'function') {
+        const acpAccessRejection = authorizeAction('checkout', authenticatedCacheIdentity);
+        if (acpAccessRejection) {
+          return res.status(acpAccessRejection.status).json(acpAccessRejection.body);
+        }
+        const acpValidation = validateActionParams({ ...(req.body || {}) }, checkoutAction);
+        if (!acpValidation.ok) {
+          return res.status(400).json({ error: "Invalid Parameter", message: acpValidation.message });
+        }
+        captureIdempotentResponse(res);
+        return Promise.resolve(checkoutAction.handler(acpValidation.params, req, res))
+          .then(result => {
+            if (!res.headersSent) {
+              res.json({
+                session_id: result?.sessionId || `acp_sess_${crypto.randomUUID()}`,
+                payment_url: result?.paymentUrl,
+                status: "open",
+                expires_at: Math.floor(Date.now() / 1000) + 3600
+              });
+            }
+          })
+          .catch(err => {
+            console.error(`ACP Checkout execution error:`, err);
+            if (!res.headersSent) {
+              res.status(500).json({ error: 'Internal ACP checkout error' });
+            }
+          });
+      } else {
+        return res.status(404).json({ error: 'ACP Checkout not configured for this store.' });
+      }
+    }
+
+    if (req.path.startsWith('/api/agentsbloom/') || req.path.startsWith('/v1/agent/actions/')) {
+      const actionName = requestedActionName;
+      const action = actions[actionName];
+
+      if (action && typeof action.handler === 'function') {
+        const configuredMethod = String(action.method || 'POST').toUpperCase();
+        if (method !== configuredMethod) {
+          res.setHeader('Allow', configuredMethod);
+          return res.status(405).json({
+            error: "Method Not Allowed",
+            message: `Action ${actionName} only accepts ${configuredMethod} requests.`,
+            allowedMethod: configuredMethod,
+          });
+        }
+
+        // v4 medium pass (V12): per-action authorization - the SDK had no
+        // authorization model at all; any verified identity could invoke
+        // any write action including checkout.
+        const accessRejection = authorizeAction(actionName, authenticatedCacheIdentity);
+        if (accessRejection) {
+          return res.status(accessRejection.status).json(accessRejection.body);
+        }
+
+        const params = method === 'GET' ? { ...req.query } : { ...req.body };
+
+        // v4: shared with the MCP tools/call path so both surfaces enforce
+        // the same declared parameter contract.
+        const validation = validateActionParams(params, action);
+        if (!validation.ok) {
+          return res.status(400).json({ error: "Invalid Parameter", message: validation.message });
+        }
+        const validatedParams = validation.params;
+        
+        captureIdempotentResponse(res);
+
+        const startTime = Date.now();
+        // Telemetry labels must be bounded. Passing a raw agent-supplied header
+        // through as an OTel metric dimension let a caller mint unbounded time
+        // series inside the merchant's own monitoring pipeline. Prefer the
+        // VERIFIED identity when we have one; fall back to a bounded rendering
+        // of the self-asserted header.
+        const agentName = boundedLabel(
+          authenticatedCacheIdentity
+            || req.headers['x-agent-identifier']
+            || req.headers['signature-agent'],
+          'Unknown Agent',
+        );
+
+        // Extract W3C Trace Context from incoming request (HIGH-16).
+        // The span name is a metric dimension too: `actionName` comes from the
+        // URL path, so bound it even though it matched a declared action.
+        const parentContext = propagation.extract(context.active(), req.headers);
+        const span = tracer.startSpan(`agent_request:${boundedLabel(actionName, 'unknown')}`, {}, parentContext);
+
+        return Promise.resolve(action.handler(validatedParams, req, res))
+          .then(result => {
+            if (!res.headersSent) {
+              res.json(result);
+            }
+            
+            const latencyMs = Date.now() - startTime;
+            // Revenue is a merchant-supplied number; a non-finite value would
+            // poison the counter permanently.
+            const revenueAmount = parseAmount(result?.totalPrice, { allowZero: false });
+
+            // OpenTelemetry Native Instrumentation
+            span.setAttribute('agent.name', agentName);
+            span.setAttribute('agent.route', `/api/agentsbloom/${boundedLabel(actionName, 'unknown')}`);
+            span.setAttribute('http.status_code', res.statusCode);
+            span.setAttribute('http.latency_ms', latencyMs);
+
+            agentRequestsCounter.add(1, { agent: agentName });
+            if (revenueAmount) agentRevenueCounter.add(Number(revenueAmount.decimal), { agent: agentName });
+            span.end();
+
+            // Telemetry is handled by OTLP exporters configured via setupTelemetry().
+            // The span.end() call above will auto-export to the OTLP collector.
+          })
+          .catch(err => {
+            span.setAttribute('error', true);
+            span.end();
+            console.error(`AgentsBloom action execution error (${actionName}):`, err);
+            if (!res.headersSent) {
+              res.status(500).json({ error: 'Internal agent endpoint error' });
+            }
+          });
+      } else {
+        return res.status(404).json({ error: `Unknown AgentsBloom action.` });
+      }
+    }
+
+    // --- 6. HTML INJECTION WITH COMPRESSION SUPPORT ---
+    // Opt-out via config.disableHtmlInjection (MED-12)
+    if (config.disableHtmlInjection) {
+      return next();
+    }
+
+    // --- HTML injection buffering limits ---
+    //
+    // This path buffers the ENTIRE HTML response in memory so it can splice in
+    // JSON-LD and the WebMCP loader. Previously it did so with no size cap and
+    // then called `zlib.gunzipSync` / `zlib.gzipSync`, which means:
+    //   * any large or streamed page was fully materialized in memory,
+    //   * a compressed upstream response was a decompression-amplification
+    //     vector (a few MB of gzip expands to gigabytes),
+    //   * the synchronous zlib calls blocked the event loop for every request,
+    //   * `res.write` always returned `true`, discarding backpressure.
+    //
+    // Now: buffering stops at a cap and the response passes through unmodified
+    // beyond it, decompression is bounded by `maxOutputLength`, and the
+    // recompression happens off the main path.
+    const htmlInjectionMaxBytes = Number.isFinite(config.htmlInjection?.maxBytes) && config.htmlInjection.maxBytes > 0
+      ? config.htmlInjection.maxBytes
+      : 2 * 1024 * 1024;
+
+    const originalWrite = res.write;
+    const originalEnd = res.end;
+    let chunks = [];
+    let bufferedBytes = 0;
+    let isHtml = false;
+    // Once the cap is exceeded we stop rewriting and flush what we hold,
+    // becoming a transparent pass-through for the rest of the response.
+    let passThrough = false;
+
+    const originalWriteHead = res.writeHead;
+    res.writeHead = function (statusCode, headers) {
+      const contentType = res.getHeader('Content-Type') || (headers && headers['content-type']) || '';
+      if (typeof contentType === 'string' && contentType.includes('text/html')) {
+        isHtml = true;
+        res.removeHeader('Content-Length');
+        if (headers) delete headers['content-length'];
+      }
+      return originalWriteHead.apply(this, arguments);
+    };
+
+    /** Flushes buffered chunks and stops intercepting. */
+    function abandonInjection() {
+      passThrough = true;
+      const pending = chunks;
+      chunks = [];
+      bufferedBytes = 0;
+      for (const chunk of pending) originalWrite.call(res, chunk);
+    }
+
+    res.write = function (chunk, ...rest) {
+      const contentType = res.getHeader('Content-Type') || '';
+      if (!passThrough && (isHtml || (typeof contentType === 'string' && contentType.includes('text/html')))) {
+        isHtml = true;
+        const buffered = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk ?? '');
+        if (bufferedBytes + buffered.length > htmlInjectionMaxBytes) {
+          // Too large to rewrite safely: flush and hand back control, so
+          // backpressure and streaming behave normally from here on.
+          abandonInjection();
+          return originalWrite.call(res, buffered, ...rest);
+        }
+        chunks.push(buffered);
+        bufferedBytes += buffered.length;
+        return true;
+      }
+      return originalWrite.apply(res, arguments);
+    };
+
+    res.end = function (chunk, ...rest) {
+      const contentType = res.getHeader('Content-Type') || '';
+      if (!passThrough && (isHtml || (typeof contentType === 'string' && contentType.includes('text/html')))) {
+        isHtml = true;
+        if (chunk) {
+          const buffered = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+          if (bufferedBytes + buffered.length > htmlInjectionMaxBytes) {
+            abandonInjection();
+            return originalEnd.call(res, buffered, ...rest);
+          }
+          chunks.push(buffered);
+          bufferedBytes += buffered.length;
+        }
+
+        let bodyBuffer = Buffer.concat(chunks);
+        const encoding = res.getHeader('Content-Encoding');
+        const isGzipped = typeof encoding === 'string' && encoding.includes('gzip');
+
+        // Decompress if gzipped, with a hard output bound so a compression
+        // bomb cannot allocate unbounded memory.
+        if (isGzipped) {
+          try {
+            bodyBuffer = zlib.gunzipSync(bodyBuffer, { maxOutputLength: htmlInjectionMaxBytes });
+          } catch (err) {
+            // Includes ERR_BUFFER_TOO_LARGE when the bound is hit: leave the
+            // response exactly as the application produced it.
+            console.error('AgentsBloom: skipping HTML injection (decompression failed or exceeded the size cap):', err?.message);
+            return originalEnd.call(res, Buffer.concat(chunks), ...rest);
+          }
+        }
+
+        let body = bodyBuffer.toString('utf8');
+
+        if (body.toLowerCase().includes('</body>')) {
+          // v4 (stored-XSS fix): merchant-controlled strings (store name,
+          // description, action names/descriptions) are no longer spliced
+          // into inline JavaScript or raw JSON.stringify output. JSON.stringify
+          // does NOT escape `</script>`, so a crafted description used to be
+          // able to break out of the script tag and execute on every page.
+          // All dynamic data is now serialized through toSafeJson() (hex-
+          // escaped `<`, `>`, `&`, U+2028/2029) and consumed as DATA by a
+          // static loader - the same approach as the hardened next-sdk.
+          const jsonLdData = {
+            "@context": "https://schema.org",
+            "@type": "WebPage",
+            "name": name,
+            "description": description,
+            "potentialAction": Object.entries(actions).map(([key]) => ({
+              "@type": "SearchAction",
+              "name": key,
+              "target": `${requestUrl}/api/agentsbloom/${key}`
+            }))
+          };
+
+          const jsonLdScript = `\n<script type="application/ld+json">\n${toSafeJson(jsonLdData)}\n</script>`;
+
+          const webMcpTools = Object.entries(actions).map(([key, val]) => ({
+            name: key,
+            description: val.description || '',
+            method: String(val.method || 'POST').toUpperCase(),
+            inputSchema: {
+              type: 'object',
+              properties: Object.fromEntries(
+                Object.entries(val.params || {}).map(([pkey, pval]) => [pkey, { type: pval }])
+              ),
+            },
+          }));
+          const webMcpScript = `
+<meta name="webmcp" content="active">
+<script>
+// Auto-generated WebMCP Declarative Actions by AgentsBloom
+(function() {
+  if (typeof navigator === 'undefined' || !navigator.ai || typeof navigator.ai.registerTool !== 'function') return;
+  var tools = ${toSafeJson(webMcpTools)};
+  for (var i = 0; i < tools.length; i++) {
+    (function(tool) {
+      navigator.ai.registerTool({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        handler: async function(args) {
+          try {
+            var headers = { 'Content-Type': 'application/json', 'Accept': 'application/json' };
+            var options = { method: tool.method, headers: headers };
+            var url = '/api/agentsbloom/' + encodeURIComponent(tool.name);
+            if (tool.method === 'GET') {
+              var queryParams = new URLSearchParams(args).toString();
+              if (queryParams) url += '?' + queryParams;
+            } else {
+              options.body = JSON.stringify(args);
+            }
+            var response = await fetch(url, options);
+            return await response.json();
+          } catch (e) {
+            return { error: e.message };
+          }
+        }
+      });
+    })(tools[i]);
+  }
+})();
+</script>
+`;
+
+          if (body.toLowerCase().includes('</head>')) {
+            body = body.replace(/<\/head>/i, `${jsonLdScript}\n</head>`);
+          } else {
+            body = body + jsonLdScript;
+          }
+
+          body = body.replace(/<\/body>/i, `${webMcpScript}\n</body>`);
+        }
+
+        let outputBuffer = Buffer.from(body, 'utf8');
+
+        // Re-compress if gzipped. On failure, fall back to sending the
+        // uncompressed body and drop the now-inaccurate Content-Encoding
+        // rather than shipping a body the client cannot decode.
+        if (isGzipped) {
+          try {
+            outputBuffer = zlib.gzipSync(outputBuffer);
+          } catch (err) {
+            console.error('AgentsBloom compression error:', err?.message);
+            res.removeHeader('Content-Encoding');
+          }
+        }
+
+        res.setHeader('Content-Length', outputBuffer.length);
+        originalWrite.call(res, outputBuffer);
+        // Forward res.end's own arguments (encoding, completion callback).
+        // Calling `originalEnd.call(res)` bare dropped the callback, so
+        // frameworks awaiting response completion never resolved.
+        return originalEnd.call(res, ...(chunk !== undefined ? rest : []));
+      }
+      return originalEnd.apply(res, arguments);
+    };
+
+    next();
+  };
+}
+
+// --- UNIFIED PROTOCOL ROUTER ---
+export function resolveProtocol(req) {
+  const accept = String((req.headers && req.headers['accept']) || '');
+  const xProtocol = String((req.headers && req.headers['x-protocol']) || '').toLowerCase();
+  const rawPath = String(req.path || req.url || '');
+  // Strip any query string so `/ap2?x=1` classifies like `/ap2`.
+  const path = rawPath.split('?')[0];
+
+  /**
+   * Matches a path PREFIX on a segment boundary.
+   *
+   * `path.startsWith('/ap2')` also matched `/ap2foo` and `/ap2-internal`, so
+   * unrelated merchant routes were classified as AP2 and inherited the
+   * `Authorization`-header-as-mandate fallback — turning an ordinary bearer
+   * token on such a route into a failed mandate and a 403.
+   */
+  const underSegment = (prefix) => path === prefix || path.startsWith(`${prefix}/`);
+
+  if (accept.includes('application/mcp+json') || underSegment('/mcp')) {
+    return 'WEBMCP';
+  }
+  if (xProtocol === 'ucp' || underSegment('/.well-known/ucp') || underSegment('/ucp')) {
+    return 'UCP';
+  }
+  if (xProtocol === 'acp' || underSegment('/acp')) {
+    return 'ACP';
+  }
+  if ((req.headers && req.headers['x-ap2-mandate']) || underSegment('/ap2') || underSegment('/v1/ap2')) {
+    return 'AP2';
+  }
+  return 'AGENTSBLOOM_REST';
+}
+
+// --- AP2 (AGENT PAYMENTS PROTOCOL) SD-JWT MANDATE VERIFIER ---
+//
+// Thin, backward-compatible wrapper over the hardened implementation in
+// lib/ap2.js. The original signature `verifyAP2Mandates(headers, body,
+// publicKey)` treated an unsigned/unverifiable mandate as "valid but
+// unverified" and let downstream code (and, worse, the /ap2/checkout gate
+// itself - see the truthiness-check fix above) treat that as authorization
+// to check out. lib/ap2.js's verifyAp2Mandate instead REJECTS any mandate
+// it cannot cryptographically verify.
+//
+// Both call shapes are supported for backward compatibility:
+//   verifyAP2Mandates(headers, body, publicKey)              // legacy
+//   verifyAP2Mandates(headers, body, { trustedPublicKey, expectedAudience, ... })  // current
+export function verifyAP2Mandates(headers = {}, body = {}, publicKeyOrOptions = null) {
+  let options;
+  if (publicKeyOrOptions === null || publicKeyOrOptions === undefined) {
+    options = {};
+  } else if (
+    publicKeyOrOptions instanceof crypto.KeyObject ||
+    Buffer.isBuffer(publicKeyOrOptions) ||
+    typeof publicKeyOrOptions === 'string'
+  ) {
+    // Legacy call shape: third argument is a raw public key.
+    options = { trustedPublicKey: publicKeyOrOptions };
+  } else {
+    // Current call shape: third argument is an options object.
+    options = publicKeyOrOptions;
+  }
+  return verifyAp2Mandate(headers, body, options);
+}
+
 export { createAp2Mandate, didKeyFromEd25519PublicKey, ed25519PublicKeyFromDidKey, resetAp2ReplayCache };
-export { createOutcomeReporter, stripeEventToOutcome };
-
+export { canonicalCartHash, stableStringify };
+export { createOutcomeReporter, stripeEventToOutcome };
+// `normalizeAudience` has been declared in index.d.ts all along but was never
+// re-exported here, so a TypeScript consumer that imported it got `undefined`
+// at runtime. Merchants need it to compute the audience string their configured
+// `baseUrl` will be compared against.
+export { normalizeAudience };
+// The accepted algorithm sets, so a merchant (or a port of this SDK) can assert
+// against the same lists the verifier enforces instead of hardcoding them.
+export { SUPPORTED_SIGNATURE_ALGORITHMS, SUPPORTED_MANDATE_ALGORITHMS };
+