@agentsbloom/sdk 0.2.0 → 0.4.0

package/index.js

@@ -1,1112 +1,1995 @@
-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';
-
-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 };
-}
-const DEFAULT_RFC_JWKS_URL = 'https://platform.openai.com/.well-known/jwks.json';
-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 jwksCache = new Map();
-
-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}:`;
-}
-
-// In-memory rate limiting map
-const rateLimitMap = new Map();
-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
-const idempotencyMap = new Map();
-const signatureNonceMap = new Map();
-const idempotencyInterval = setInterval(() => {
-  const now = Date.now();
-  for (const [key, val] of idempotencyMap.entries()) {
-    if (val.expiry < now) idempotencyMap.delete(key);
-  }
-  for (const [key, expiresAt] of signatureNonceMap.entries()) {
-    if (expiresAt < now) signatureNonceMap.delete(key);
-  }
-}, 60 * 1000);
-idempotencyInterval.unref();
-
-let otelShutdownPromise = null;
-
-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.");
-  }
-
-  let quotaExceededUntil = 0;
-
-  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;
-  const signatureMaxAgeMs = Number.isFinite(config.signature?.maxAgeMs) && config.signature.maxAgeMs > 0
-    ? config.signature.maxAgeMs
-    : LEGACY_SIGNATURE_MAX_AGE_MS;
-  
-  const configuredAgentSecret = config.agentSecret ?? process.env.AGENTSBLOOM_SECRET;
-  const agentSecret = typeof configuredAgentSecret === 'string' && configuredAgentSecret.length > 0
-    ? configuredAgentSecret
-    : null;
-  const signatureAuthEnabled = config.disableSignatureAuth !== true && config.demoMode !== true;
-  const cacheNamespace = crypto.randomUUID();
-
-  if (!agentSecret && signatureAuthEnabled) {
-    console.warn("🌸 AgentsBloom Warning: AGENTSBLOOM_SECRET is not set. Legacy signed write requests will be rejected until a secret is configured.");
-  }
-
-  return async (req, res, next) => {
-    const contentLength = parseInt(req.headers['content-length'] || '0', 10);
-    if (contentLength > 1024 * 1024) {
-      return res.status(413).json({ error: "Payload Too Large", message: "Request body exceeds 1MB limit." });
-    }
-
-    if (req.path === '/health' && req.method === 'GET') {
-      return res.json({ status: "ok", version: "0.2.0", uptime: process.uptime() });
-    }
-
-    const requestUrl = baseUrl || `${req.protocol}://${req.get('host')}`;
-    const ip = req.ip || req.socket.remoteAddress || '127.0.0.1';
-    const now = Date.now();
-
-    // --- CORS HEADERS ---
-    const allowedOrigin = config.corsOrigin || baseUrl || '*';
-    res.setHeader('Access-Control-Allow-Origin', allowedOrigin);
-    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');
-    if (req.method === 'OPTIONS') {
-      return res.status(204).end();
-    }
-
-    // --- SaaS QUOTA ENFORCEMENT (Zero Latency Cache) ---
-    if (now < quotaExceededUntil) {
-      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) ---
-    let limit = rateLimitMap.get(ip);
-    if (!limit || now > limit.resetTime) {
-      limit = { count: 1, resetTime: now + RATE_LIMIT_WINDOW };
-      rateLimitMap.set(ip, 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)
-      });
-    }
-
-    // --- 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.2.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
-    if (req.path === '/.well-known/http-message-signatures-directory') {
-      res.setHeader('Content-Type', 'application/json');
-      res.setHeader('Cache-Control', 'public, max-age=86400');
-      if (config.merchantJwks) {
-        return res.json(config.merchantJwks);
-      } else {
-        console.warn("🌸 AgentsBloom Warning: Serving placeholder JWKS. Provide `merchantJwks` in config for real keys.");
-        return res.json({
-          keys: [
-            {
-              kty: "OKP",
-              crv: "Ed25519",
-              kid: "placeholder-merchant-key",
-              x: "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPPRwX0"
-            }
-          ]
-        });
-      }
-    }
-
-    // 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`,
-          cart: `${requestUrl}/api/agentsbloom/cart`,
-          checkout: `${requestUrl}/api/agentsbloom/checkout/acp`
-        },
-        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 MCP SSE Endpoint for Tool Calling
-    if (req.path === '/mcp') {
-      const transport = new SSEServerTransport('/mcp/messages', res);
-      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}`);
-        const result = await action.handler(request.params.arguments, req, res);
-        return { content: [{ type: "text", text: JSON.stringify(result) }] };
-      });
-
-      return mcpServer.connect(transport);
-    }
-
-    // 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`;
-      return res.send(llmsDoc || defaultLlmDoc);
-    }
-
-    // --- 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';
-    const isAgentAction = req.path.startsWith('/api/agentsbloom/')
-      || req.path.startsWith('/v1/agent/actions/')
-      || isMcpMessage;
-    if (isAgentAction && isWrite && 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];
-          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');
-          }
-
-          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");
-          }
-
-          const trustedJwks = config.agentJwks;
-          const trustedJwksUrl = config.agentJwksUrl || DEFAULT_RFC_JWKS_URL;
-          const cacheKey = `${cacheNamespace}:${trustedJwks ? 'inline' : trustedJwksUrl}:${keyid}`;
-          let publicKey = null;
-          const cached = jwksCache.get(cacheKey);
-          if (cached && cached.expires > Date.now()) {
-            publicKey = cached.key;
-          } 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) throw new Error("Configured JWKS does not contain the requested key id");
-            publicKey = crypto.createPublicKey({ key: jwk, format: 'jwk' });
-            jwksCache.set(cacheKey, { key: publicKey, expires: Date.now() + 3600 * 1000 });
-          }
-
-          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 = alg.includes('sha512') ? 'SHA512' : '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." });
-          for (const [replayKey, expiresAt] of signatureNonceMap.entries()) {
-            if (expiresAt < nowMs) signatureNonceMap.delete(replayKey);
-          }
-          if (signatureNonceMap.has(rfcReplayKey)) {
-            return res.status(403).json({
-              error: "Forbidden",
-              message: "HTTP Message Signature nonce has already been used."
-            });
-          }
-          if (signatureNonceMap.size >= SIGNATURE_REPLAY_CACHE_MAX_SIZE) {
-            return res.status(503).json({
-              error: "Verification Unavailable",
-              message: "Signature replay protection is temporarily at capacity."
-            });
-          }
-          signatureNonceMap.set(rfcReplayKey, expiresMs);
-          authenticatedCacheIdentity = `rfc:${keyid}`;
-        } catch (err) {
-          return res.status(403).json({ error: "Forbidden", message: "Signature verification failed: " + err.message });
-        }
-      } else {
-        const headerValuePattern = /^[\x21-\x7e]+$/;
-        if (
-          !agentSecret ||
-          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}`;
-        if (signatureNonceMap.has(replayKey)) {
-          return res.status(403).json({
-            error: "Verification Failed",
-            message: "X-Agent-Signature nonce has already been used."
-          });
-        }
-
-        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."
-          });
-        }
-        if (!verifySignature(signature, signaturePayload, agentSecret)) {
-          return res.status(403).json({
-            error: "Verification Failed",
-            message: "X-Agent-Signature is invalid. Access denied."
-          });
-        }
-
-        for (const [key, expiresAt] of signatureNonceMap.entries()) {
-          if (expiresAt < nowMs) signatureNonceMap.delete(key);
-        }
-        if (signatureNonceMap.size >= SIGNATURE_REPLAY_CACHE_MAX_SIZE) {
-          return res.status(503).json({
-            error: "Verification Unavailable",
-            message: "Signature replay protection is temporarily at capacity."
-          });
-        }
-        signatureNonceMap.set(replayKey, timestampMs + signatureMaxAgeMs);
-        authenticatedCacheIdentity = `legacy:${identifier}`;
-      }
-    }
-
-    // --- 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) ---
-    const ap2MandateHeader = req.headers['x-ap2-mandate'] || req.headers['authorization'];
-    const detectedProtocol = resolveProtocol(req);
-    let ap2MandateResult = null;
-
-    if (detectedProtocol === 'AP2' || (ap2MandateHeader && ap2MandateHeader.includes('.'))) {
-      // 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 = verifyAP2Mandates(req.headers, req.body || {}, {
-        trustedPublicKey: config.ap2PublicKey || null,
-        expectedAudience: config.ap2?.expectedAudience || requestUrl,
-        maxMandateLifetimeSec: config.ap2?.maxMandateLifetimeSec,
-        requireJti: config.ap2?.requireJti,
-        requestedCategories: req.body?.requestedCategories || config.ap2?.requestedCategories,
-      });
-
-      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.' });
-      }
-
-      // Validate budget before executing checkout
-      const orderTotal = req.body?.orderTotal || req.body?.total || 0;
-      const maxBudget = ap2MandateResult.mandates?.intentMandate?.maxBudget
-                     || ap2MandateResult.mandates?.paymentMandate?.maxBudget;
-
-      if (maxBudget && 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}.`
-        });
-      }
-
-      return Promise.resolve(checkoutAction.handler(req.body, req, res))
-        .then(result => {
-          if (!res.headersSent) {
-            res.json({
-              protocol: "AP2",
-              verifiableIntent: {
-                mandateVerified: ap2MandateResult.verified,
-                budgetEnforced: !!maxBudget,
-                maxBudget: maxBudget || null,
-                orderTotal: result.total || orderTotal
-              },
-              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 = req.path.replace('/api/agentsbloom/', '').replace('/v1/agent/actions/', '');
-      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,
-          });
-        }
-
-        const params = method === 'GET' ? req.query : req.body;
-        
-        if (action.params) {
-          for (const [key, type] of Object.entries(action.params)) {
-            if (params[key] !== undefined && typeof params[key] !== type && type !== 'any') {
-              return res.status(400).json({ error: "Invalid Parameter", message: `Expected ${type} for parameter ${key}` });
-            }
-          }
-        }
-        
-        // 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) {
-            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(params, 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>')) {
-          const jsonLdData = {
-            "@context": "https://schema.org",
-            "@type": "WebPage",
-            "name": name,
-            "description": description,
-            "potentialAction": Object.entries(actions).map(([key, val]) => ({
-              "@type": "SearchAction",
-              "name": key,
-              "target": `${requestUrl}/api/agentsbloom/${key}`
-            }))
-          };
-
-          const jsonLdScript = `\n<script type="application/ld+json">\n${JSON.stringify(jsonLdData, null, 2)}\n</script>`;
-
-          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') {
-    console.log("🌸 AgentsBloom: Registering WebMCP tools natively in browser.");
-    
-    ${Object.entries(actions).map(([key, val]) => `
-    navigator.ai.registerTool({
-      name: "${key}",
-      description: "${val.description.replace(/"/g, '\\"')}",
-      inputSchema: {
-        type: "object",
-        properties: {
-          ${Object.entries(val.params || {}).map(([pkey, pval]) => `
-          "${pkey}": { type: "${pval}" }
-          `).join(',')}
-        }
-      },
-      handler: async (args) => {
-        try {
-          const method = "${val.method || 'POST'}";
-          const headers = { 'Content-Type': 'application/json', 'Accept': 'application/json' };
-          let fetchOptions = { method, headers };
-          
-          let url = '/api/agentsbloom/${key}';
-          if (method === 'GET') {
-            const queryParams = new URLSearchParams(args).toString();
-            if (queryParams) url += '?' + queryParams;
-          } else {
-            fetchOptions.body = JSON.stringify(args);
-          }
-          
-          const response = await fetch(url, fetchOptions);
-          return await response.json();
-        } catch (e) {
-          return { error: e.message };
-        }
-      }
-    });
-    `).join('\n')}
-  }
-})();
-</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 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 { 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);
+}
+
 export { createAp2Mandate, didKeyFromEd25519PublicKey, ed25519PublicKeyFromDidKey, resetAp2ReplayCache };
-
+export { createOutcomeReporter, stripeEventToOutcome };
+