@agentsbloom/sdk 0.2.0 → 0.5.0

package/index.js

@@ -2,6 +2,11 @@ import zlib from 'zlib';
 import crypto from 'crypto';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+// `setRequestHandler` takes a Zod request SCHEMA, not a method-name string.
+// Passing the strings 'tools/list' / 'tools/call' made the MCP SDK throw
+// `Error: Schema is missing a method literal` on EVERY `GET /mcp`, so the MCP
+// surface advertised in every discovery document was completely non-functional.
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { trace, metrics, ValueType, context, propagation } from '@opentelemetry/api';
 import { initExporter } from './telemetry.js';
 import {
@@ -11,7 +16,26 @@ import {
   ed25519PublicKeyFromDidKey,
   resetAp2ReplayCache,
   stopAp2ReplayCleanup,
+  canonicalCartHash,
+  stableStringify,
+  normalizeAudience,
+  SUPPORTED_MANDATE_ALGORITHMS,
 } from './lib/ap2.js';
+import { createReplayCache } from './lib/shared-store.js';
+import { createOutcomeReporter, stripeEventToOutcome } from './lib/outcomes.js';
+import {
+  verifyHttpMessageSignature,
+  createJwksCache,
+  isBlockedSsrfHostname,
+  SUPPORTED_SIGNATURE_ALGORITHMS,
+  STRICT_REQUIRED_COMPONENTS,
+} from './lib/http-signatures.js';
+import {
+  requestContextFromExpress,
+  normalizeAuthority as normalizeAuthorityForScheme,
+  PROFILE_STRICT,
+} from './lib/signature-base.js';
+import { compareAmounts, normalizeCurrencyCode, parseAmount } from './lib/money.js';
 
 const tracer = trace.getTracer('agentsbloom-sdk');
 const meter = metrics.getMeter('agentsbloom-sdk');
@@ -37,25 +61,97 @@ export async function setupTelemetry(options = {}) {
     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,
-  };
+  // Refuse to ship the collector credential over cleartext. The default
+  // endpoint is a local collector, which is fine; anything remote must be TLS.
+  let endpointIsLocal = false;
+  try {
+    const parsed = new URL(otlpEndpoint);
+    endpointIsLocal = parsed.hostname === 'localhost'
+      || parsed.hostname === '127.0.0.1'
+      || parsed.hostname === '::1'
+      || parsed.hostname === '[::1]';
+    if (apiKey && parsed.protocol !== 'https:' && !endpointIsLocal) {
+      throw new Error(
+        `refusing to send the telemetry API key to ${parsed.origin} over ${parsed.protocol.replace(':', '')}; use https`,
+      );
+    }
+  } catch (err) {
+    if (err instanceof TypeError) {
+      throw new Error(`AgentsBloom: otlpEndpoint is not a valid URL: ${otlpEndpoint}`);
+    }
+    throw err;
+  }
+
+  // Store NON-SECRET config for lazy initialization when the OTel SDK packages
+  // are available. The apiKey used to be parked on globalThis alongside it,
+  // where any code in the process (including a compromised transitive
+  // dependency) could read the merchant's collector credential.
+  globalThis.__agentsbloom_otel_config = { otlpEndpoint, serviceName, samplingRatio };
 
   const handle = await initExporter({ otlpEndpoint, serviceName, samplingRatio, apiKey });
   globalThis.__agentsbloom_otel_handle = handle;
 
-  console.log(`🌸 AgentsBloom: Telemetry configured (sampling: ${samplingRatio * 100}%)`);
-  return { otlpEndpoint, serviceName, samplingRatio };
+  const effectiveRatio = Number.isFinite(samplingRatio) ? Math.min(1, Math.max(0, samplingRatio)) : 1;
+  console.log(`🌸 AgentsBloom: Telemetry configured (sampling: ${(effectiveRatio * 100).toFixed(0)}%)`);
+  return { otlpEndpoint, serviceName, samplingRatio: effectiveRatio };
 }
-const DEFAULT_RFC_JWKS_URL = 'https://platform.openai.com/.well-known/jwks.json';
+// 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 jwksCache = new Map();
+const MAX_RATE_TRACKED_CLIENTS = 50_000;
+
+/**
+ * Bounded, swept, negatively-cached JWKS store shared by every middleware
+ * instance in the process. The cache and the SSRF guard now live in
+ * lib/http-signatures.js alongside the verification that uses them, so there
+ * is exactly one implementation of each rule instead of one per call site.
+ */
+const jwksCache = createJwksCache();
+
+/**
+ * Caps the cardinality of a value used as a telemetry label.
+ *
+ * Agent-supplied headers were passed straight through as OTel metric
+ * dimensions and span attributes, so a caller could mint unbounded
+ * time series inside the merchant's own monitoring pipeline.
+ */
+const MAX_LABEL_LENGTH = 64;
+function boundedLabel(value, fallback = 'unknown') {
+  if (typeof value !== 'string' || value.length === 0) return fallback;
+  const cleaned = value.replace(/[^\x20-\x7e]/g, '');
+  if (cleaned.length === 0) return fallback;
+  if (cleaned.length <= MAX_LABEL_LENGTH) return cleaned;
+  // Keep a stable, readable prefix plus a digest so distinct long values stay
+  // distinguishable without being unbounded.
+  const digest = crypto.createHash('sha256').update(cleaned).digest('base64url').slice(0, 8);
+  return `${cleaned.slice(0, MAX_LABEL_LENGTH - 9)}~${digest}`;
+}
+
+/** Escapes JSON for embedding inside an HTML <script> element. */
+function toSafeJson(value) {
+  return JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+/**
+ * Normalizes a client key for rate limiting: strips the IPv6-mapped IPv4
+ * prefix (::ffff:127.0.0.1 -> 127.0.0.1) so the same client cannot get a
+ * fresh bucket by alternating address representations.
+ */
+function normalizeRateLimitKey(ip) {
+  const raw = String(ip || '');
+  return raw.startsWith('::ffff:') ? raw.slice(7) : raw;
+}
 
 function verifySignature(signature, payload, secret) {
   try {
@@ -79,28 +175,87 @@ function buildLegacySignaturePayload(req, identifier, timestamp, nonce) {
   ]);
 }
 
-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');
+// Content-Digest computation and verification moved to lib/signature-base.js.
+//
+// The old helper here silently fell back to `Buffer.from(JSON.stringify(req.body))`
+// when `req.rawBody` was absent, which turned "this digest proves what the
+// client sent" into "this digest matches our re-serialization of what our
+// parser produced". An agent computing its digest the same way satisfied it
+// even when the bytes on the wire differed. `resolveBodyBytes` now requires
+// the real bytes and fails closed without them.
+
+/**
+ * v4: validates/coerces action parameters against the action's declared
+ * `params` type map. Shared by the REST action route AND the MCP tools/call
+ * handler - previously the MCP path passed arguments straight through with
+ * no validation at all, so the type guarantees advertised in discovery
+ * documents were not actually enforced there.
+ *
+ * @returns {{ ok: boolean, params?: object, message?: string }}
+ */
+function validateActionParams(rawParams, action) {
+  const params = { ...rawParams };
+  if (!action.params) return { ok: true, params };
+  for (const [key, type] of Object.entries(action.params)) {
+    const val = params[key];
+    if (val === undefined) continue;
+    if (type === 'any') continue;
+    if (type === 'number') {
+      if (typeof val === 'number' && !isNaN(val)) {
+        // valid
+      } else if (typeof val === 'string' && val.trim() !== '' && !isNaN(Number(val))) {
+        params[key] = Number(val);
+      } else {
+        return { ok: false, message: `Expected ${type} for parameter ${key}` };
+      }
+    } else if (type === 'boolean') {
+      if (typeof val === 'boolean') {
+        // valid
+      } else if (typeof val === 'string' && (val === 'true' || val === 'false' || val === '1' || val === '0')) {
+        params[key] = val === 'true' || val === '1';
+      } else {
+        return { ok: false, message: `Expected ${type} for parameter ${key}` };
+      }
+    } else if (type === 'string') {
+      if (typeof val !== 'string') {
+        return { ok: false, message: `Expected ${type} for parameter ${key}` };
+      }
+    } else if (typeof val !== type && !(typeof type === 'string' && type.includes(typeof val))) {
+      return { ok: false, message: `Expected ${type} for parameter ${key}` };
     }
-    bodyBytes = Buffer.alloc(0);
   }
-
-  const digest = crypto.createHash('sha256').update(bodyBytes).digest('base64');
-  return `sha-256=:${digest}:`;
+  return { ok: true, params };
 }
 
 // In-memory rate limiting map
 const rateLimitMap = new Map();
+// v4: bounded count of live MCP SSE sessions (see /mcp handler).
+let activeMcpSessions = 0;
+/**
+ * Live MCP SSE transports by session id, so `POST /mcp/messages` can be routed
+ * to the stream that opened it. Bounded implicitly by `mcp.maxSessions`;
+ * entries are deleted when the SSE response closes.
+ */
+const mcpTransports = new Map();
+
+// --- v4 medium pass (V15): the SaaS quota gate is now WIRED ---
+// Previously `quotaExceededUntil` was a per-instance variable initialized
+// to 0 that nothing ever set - dead code implying enforcement that did not
+// exist. The hosted gateway (or any operator tooling) can now trip every
+// middleware instance in the process via setQuotaExceededUntil(), or set
+// AGENTSBLOOM_QUOTA_EXCEEDED_UNTIL (epoch ms) in the environment.
+let quotaExceededUntilMs = Number(process.env.AGENTSBLOOM_QUOTA_EXCEEDED_UNTIL || 0) || 0;
+
+/** Marks quota exceeded process-wide until the given epoch-ms timestamp. */
+export function setQuotaExceededUntil(untilEpochMs) {
+  const value = Number(untilEpochMs);
+  quotaExceededUntilMs = Number.isFinite(value) ? value : 0;
+}
+
+/** Clears the process-wide quota-exceeded state immediately. */
+export function clearQuotaExceeded() {
+  quotaExceededUntilMs = 0;
+}
 const rateLimitInterval = setInterval(() => {
   const now = Date.now();
   for (const [key, val] of rateLimitMap.entries()) {
@@ -109,22 +264,337 @@ const rateLimitInterval = setInterval(() => {
 }, 60 * 1000);
 rateLimitInterval.unref();
 
-// In-memory Idempotency cache
+// 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 = 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);
   }
-  for (const [key, expiresAt] of signatureNonceMap.entries()) {
-    if (expiresAt < now) signatureNonceMap.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);
@@ -163,57 +633,281 @@ export function agentsbloom(config = {}) {
   } = 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");
+    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.");
+    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;
+  // v4 medium pass (V18): bound the per-process idempotency cache so
+  // unique-key spam cannot grow memory without limit between TTL sweeps.
+  const IDEMPOTENCY_MAX_ENTRIES = Number.isFinite(config.idempotency?.maxEntries) && config.idempotency.maxEntries > 0
+    ? config.idempotency.maxEntries
+    : 10_000;
   const signatureMaxAgeMs = Number.isFinite(config.signature?.maxAgeMs) && config.signature.maxAgeMs > 0
     ? config.signature.maxAgeMs
     : LEGACY_SIGNATURE_MAX_AGE_MS;
-  
+  // Host binding is now REQUIRED by default. Without `@authority` in the
+  // covered components, a signature captured at store A is structurally valid
+  // at store B for the same path — a real cross-merchant replay whenever two
+  // stores trust the same JWKS. Opting out re-opens that hole knowingly.
+  const signatureRequireAuthority = config.signature?.requireAuthority !== false;
+  // The pre-hardening (non-conformant) signature base is accepted only when a
+  // merchant explicitly opts in for a migration window. See
+  // lib/signature-base.js for exactly how the two profiles differ.
+  const acceptLegacySignatureProfile = config.signature?.acceptLegacyProfile === true;
+  // Escape hatch for applications that cannot capture `req.rawBody`. Hashing a
+  // re-serialized body does not prove what the client sent, so this is off by
+  // default and loud when enabled.
+  const allowReserializedBody = config.signature?.allowReserializedBody === true;
+  if (allowReserializedBody) {
+    console.warn(
+      "🌸 AgentsBloom Warning: signature.allowReserializedBody is enabled. Content-Digest will be computed from a RE-SERIALIZED body, "
+      + 'which does not prove what the client actually sent. Prefer express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }).',
+    );
+  }
+  if (acceptLegacySignatureProfile) {
+    console.warn(
+      "🌸 AgentsBloom Warning: signature.acceptLegacyProfile is enabled. The pre-0.6 signature base (lowercased @method, query folded into @path, "
+      + 'unbindable authority) is accepted as a fallback. Remove this once your agents sign the conformant RFC 9421 base.',
+    );
+  }
+  if (config.signature?.requireAuthority === false) {
+    console.warn(
+      '🌸 AgentsBloom Warning: signature.requireAuthority is disabled. Signatures will not bind the request host, so a signature captured '
+      + 'at another store that trusts the same keys can be replayed here.',
+    );
+  }
+
   const configuredAgentSecret = config.agentSecret ?? process.env.AGENTSBLOOM_SECRET;
   const agentSecret = typeof configuredAgentSecret === 'string' && configuredAgentSecret.length > 0
     ? configuredAgentSecret
     : null;
+  // Previous secret kept verify-live during rotation (see verifySignature
+  // call sites) so rolling AGENTSBLOOM_SECRET doesn't hard-drop every
+  // in-flight agent.
+  const configuredPreviousSecret = config.agentSecretPrevious ?? process.env.AGENTSBLOOM_SECRET_PREVIOUS;
+  const agentSecretPrevious = typeof configuredPreviousSecret === 'string' && configuredPreviousSecret.length > 0
+    ? configuredPreviousSecret
+    : null;
   const signatureAuthEnabled = config.disableSignatureAuth !== true && config.demoMode !== true;
-  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.");
+  // --- Replay-cache namespace (was: crypto.randomUUID()) ---
+  //
+  // This prefix is part of every nonce and idempotency cache key. Generating
+  // it randomly per `agentsbloom()` call silently DEFEATED cluster-wide replay
+  // protection: with Upstash configured, instance A stored
+  // `<uuid-A>:rfc:<keyid>:<nonce>` while instance B looked for
+  // `<uuid-B>:rfc:<keyid>:<nonce>`, so `SET NX` never collided and a captured
+  // signature replayed cleanly on any other pod — and on the same pod after a
+  // restart. (Mandate jtis were not namespaced at all, so the two paths
+  // disagreed about whether replay protection was cluster-wide.)
+  //
+  // The namespace is now DERIVED and stable across instances of the same
+  // store: explicit config first, then the merchant's `baseUrl`, then a fixed
+  // default. Distinct stores sharing one Redis still get distinct prefixes.
+  const cacheNamespace = (() => {
+    const explicit = config.cacheNamespace;
+    if (typeof explicit === 'string' && explicit.trim().length > 0) return explicit.trim();
+    if (baseUrl) {
+      return `ab:${crypto.createHash('sha256').update(normalizeAudience(baseUrl)).digest('base64url').slice(0, 16)}`;
+    }
+    console.warn(
+      '🌸 AgentsBloom Warning: neither `baseUrl` nor `cacheNamespace` is set, so replay-cache keys fall back to a shared default. '
+      + 'If several distinct stores share one replay store, set `cacheNamespace` per store.',
+    );
+    return 'ab:default';
+  })();
+
+  // --- v4 medium pass (V11): per-agent keys and revocation ---
+  // The single shared merchant secret meant one compromised agent
+  // compromised every agent: any holder could forge requests as ANY
+  // identifier, and there was no way to revoke one agent without rotating
+  // the global secret for all of them. `config.agentKeys` maps identifier
+  // -> per-agent secret (checked first); `config.revokedIdentifiers`
+  // rejects an identifier outright. The shared secret remains the
+  // fallback so existing deployments keep working.
+  const agentKeys = config.agentKeys && typeof config.agentKeys === 'object'
+    ? Object.fromEntries(
+        Object.entries(config.agentKeys).filter(([, v]) => typeof v === 'string' && v.length > 0)
+      )
+    : null;
+  const revokedIdentifiers = Array.isArray(config.revokedIdentifiers)
+    ? new Set(config.revokedIdentifiers)
+    : null;
+
+  // --- v4 medium pass (V12): per-action authorization ---
+  // Any verified identity could previously invoke ANY write action,
+  // checkout included - the permission matrix existed only in the hosted
+  // gateway. Merchants can now require a verified identity per action and
+  // restrict which identities may call it.
+  const actionAccess = config.actionAccess && typeof config.actionAccess === 'object' ? config.actionAccess : null;
+  const actionIdentities = config.actionIdentities && typeof config.actionIdentities === 'object' ? config.actionIdentities : null;
+
+  // --- v4 medium pass (V20): CORS origin policy ---
+  // Array = exact-match allow-list with per-request reflection; string =
+  // legacy single-value behavior ('*' by default). The wildcard default is
+  // loud about itself so merchants notice and restrict it.
+  const allowedOriginList = Array.isArray(config.corsOrigin)
+    ? config.corsOrigin.filter((o) => typeof o === 'string' && o.length > 0)
+    : null;
+  const allowedOriginString = allowedOriginList ? null : (config.corsOrigin || '*');
+  if (!config.corsOrigin) {
+    console.warn("🌸 AgentsBloom Warning: corsOrigin defaults to '*' - any web origin can call this store's API, including write endpoints reachable from a victim browser. Set corsOrigin to an explicit origin or array of origins for production.");
+  }
+
+  /**
+   * Returns a rejection descriptor when `identity` (verified cache identity
+   * string like `rfc:<keyid>` / `legacy:<identifier>`, or null) may not
+   * invoke `actionName`; null when allowed.
+   */
+  function authorizeAction(actionName, identity) {
+    if (actionAccess?.[actionName] === 'authenticated' && !identity) {
+      return {
+        status: 401,
+        body: {
+          error: "Authentication Required",
+          message: `Action ${actionName} requires a verified agent signature (RFC 9421 or X-Agent-Signature).`
+        },
+      };
+    }
+    const allowed = actionIdentities?.[actionName];
+    if (Array.isArray(allowed) && allowed.length > 0) {
+      const matched = Boolean(identity) && allowed.some((pattern) => (
+        pattern === identity || (typeof pattern === 'string' && pattern.endsWith(':') && identity.startsWith(pattern))
+      ));
+      if (!matched) {
+        return {
+          status: 403,
+          body: {
+            error: "Forbidden",
+            message: `Verified identity ${identity || '(anonymous)'} is not authorized to invoke ${actionName}.`
+          },
+        };
+      }
+    }
+    return null;
+  }
+
+  if (!agentSecret && !agentKeys && signatureAuthEnabled) {
+    console.warn("🌸 AgentsBloom Warning: Neither AGENTSBLOOM_SECRET nor config.agentKeys is set. Legacy signed write requests will be rejected until a secret is configured.");
+  }
+
+  // --- Host-header policy (resolved once, at construction) ---
+  //
+  // Used for two distinct purposes:
+  //   1. Discovery URLs: a request whose Host is not on the list gets its
+  //      URLs built from the merchant's trusted `baseUrl` instead of the
+  //      attacker-controlled Host.
+  //   2. Signature authority binding: `@authority` canonicalizes the request's
+  //      own Host header, so covering it only prevents cross-store replay if
+  //      the verifier ALSO knows which authorities are its own. Otherwise an
+  //      attacker replaying store A's signature here just sends
+  //      `Host: store-a.com` and the signature base reconstructs identically.
+  const allowedHosts = Array.isArray(config.allowedHosts)
+    ? config.allowedHosts.filter((h) => typeof h === 'string' && h.length > 0).map((h) => h.toLowerCase())
+    : null;
+
+  const expectedAuthorities = (() => {
+    const authorities = new Set();
+    for (const host of allowedHosts || []) {
+      authorities.add(normalizeAuthorityForScheme(host, 'https:'));
+      authorities.add(normalizeAuthorityForScheme(host, 'http:'));
+    }
+    if (baseUrl) {
+      try {
+        const parsed = new URL(baseUrl);
+        authorities.add(normalizeAuthorityForScheme(parsed.host, parsed.protocol));
+      } catch {
+        // A malformed baseUrl is already reported elsewhere; don't add it.
+      }
+    }
+    authorities.delete('');
+    if (authorities.size === 0 && signatureAuthEnabled && signatureRequireAuthority) {
+      console.warn(
+        '🌸 AgentsBloom Warning: neither `baseUrl` nor `allowedHosts` is set, so the Host header cannot be validated. '
+        + 'Signatures still have to COVER @authority, but a replayed signature from another store will match if the attacker '
+        + 'forwards that store\'s Host header. Set `baseUrl` (or `allowedHosts`) to make host binding effective.',
+      );
+      return null;
+    }
+    return authorities.size > 0 ? authorities : null;
+  })();
+
+  // v4 (Host-header poisoning defense): warn when the AP2 audience would be
+  // derived from the request's own Host header - that fallback is spoofable.
+  if (!config.ap2?.expectedAudience && !baseUrl) {
+    console.warn("🌸 AgentsBloom Warning: Neither `baseUrl` nor `ap2.expectedAudience` is configured. The AP2 mandate audience will fall back to each request's Host header, which an attacker can spoof. Set one of them for production.");
   }
 
   return async (req, res, next) => {
+    // v4 medium pass (V10): the 1MB gate used to check the Content-Length
+    // header only - a chunked transfer with no Content-Length sailed past
+    // it. The cap is now also enforced against the ACTUAL received bytes
+    // (req.rawBody) once the body parser has run, and is configurable.
+    const maxBodyBytes = Number.isFinite(config.maxBodyBytes) && config.maxBodyBytes > 0
+      ? config.maxBodyBytes
+      : 1024 * 1024;
     const contentLength = parseInt(req.headers['content-length'] || '0', 10);
-    if (contentLength > 1024 * 1024) {
-      return res.status(413).json({ error: "Payload Too Large", message: "Request body exceeds 1MB limit." });
+    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.2.0", uptime: process.uptime() });
+      return res.json({ status: "ok", version: "0.4.0", uptime: process.uptime() });
     }
 
-    const requestUrl = baseUrl || `${req.protocol}://${req.get('host')}`;
+    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 ---
-    const allowedOrigin = config.corsOrigin || baseUrl || '*';
-    res.setHeader('Access-Control-Allow-Origin', allowedOrigin);
+    // 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');
-    if (req.method === 'OPTIONS') {
-      return res.status(204).end();
-    }
 
     // --- SaaS QUOTA ENFORCEMENT (Zero Latency Cache) ---
-    if (now < quotaExceededUntil) {
+    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.",
@@ -222,10 +916,28 @@ export function agentsbloom(config = {}) {
     }
 
     // --- 1. DDoS PROTECTION (RATE LIMITING) ---
-    let limit = rateLimitMap.get(ip);
+    // 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(ip, limit);
+      rateLimitMap.set(rateKeyNormalized, limit);
     } else {
       limit.count++;
     }
@@ -245,6 +957,12 @@ export function agentsbloom(config = {}) {
       });
     }
 
+    // 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)
@@ -255,7 +973,7 @@ export function agentsbloom(config = {}) {
         name,
         description,
         version: "1.0.0",
-        agentsbloomVersion: "0.2.0",
+        agentsbloomVersion: "0.4.0",
         discoveryUrl: `${requestUrl}/v1/agent/spec`,
         catalogUrl: `${requestUrl}/v1/agent/catalog`,
         llmsUrl: `${requestUrl}/llms.txt`,
@@ -278,24 +996,20 @@ export function agentsbloom(config = {}) {
     }
 
     // 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') {
-      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"
-            }
-          ]
+      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)
@@ -313,9 +1027,20 @@ export function agentsbloom(config = {}) {
         ],
         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"]
         }
@@ -344,13 +1069,68 @@ export function agentsbloom(config = {}) {
       });
     }
 
+    // Serve /openapi.json & /schema.json (OpenAPI 3.1 for custom GPT
+    // actions and any OpenAPI-consuming agent). The document is generated
+    // from the merchant's declared actions - previously it hardcoded five
+    // paths, so any custom action (removeFromCart, clearCart, or anything
+    // a merchant added) silently vanished from the OpenAPI surface, and
+    // AP2 endpoints were entirely undocumented.
+    if (req.path === '/openapi.json' || req.path === '/schema.json') {
+      res.setHeader('Content-Type', 'application/json');
+      res.setHeader('Cache-Control', 'public, max-age=86400');
+      return res.json(buildOpenApiDocument({ name, description, requestUrl, actions, signatureAuthEnabled }));
+    }
+
+    // --- Verified-identity bindings, declared BEFORE any closure reads them ---
+    //
+    // The MCP `tools/call` handler below closes over `authenticatedCacheIdentity`
+    // to enforce per-action authorization. That binding used to be declared
+    // ~40 lines LOWER with `let`, after this branch had already returned, so
+    // the closure ran while the binding was still in its temporal dead zone:
+    // every single MCP tool invocation threw
+    //   ReferenceError: Cannot access 'authenticatedCacheIdentity' before initialization
+    // regardless of configuration. Hoisting it here fixes the crash and keeps
+    // the authorization check meaningful.
+    let authenticatedCacheIdentity = null;
+    let signatureProfileUsed = null;
+
     // Serve MCP SSE Endpoint for Tool Calling
+    // v4: concurrent SSE sessions are bounded (config.mcp.maxSessions,
+    // default 100). Previously every GET /mcp created an unbounded new
+    // transport with no accounting - a trivial socket/memory exhaustion
+    // vector.
     if (req.path === '/mcp') {
+      const maxMcpSessions = Number.isFinite(config.mcp?.maxSessions) && config.mcp.maxSessions > 0
+        ? config.mcp.maxSessions
+        : 100;
+      if (activeMcpSessions >= maxMcpSessions) {
+        return res.status(503).json({
+          error: "Too Many MCP Sessions",
+          message: `Concurrent MCP session limit (${maxMcpSessions}) reached. Retry later.`
+        });
+      }
       const transport = new SSEServerTransport('/mcp/messages', res);
+      activeMcpSessions += 1;
+      // The slot must be released exactly once. `res.on('close')` and the
+      // connect() catch below could both fire for one session, drifting the
+      // counter negative and loosening the concurrency cap over time.
+      let sessionSlotReleased = false;
+      const releaseMcpSession = () => {
+        if (sessionSlotReleased) return;
+        sessionSlotReleased = true;
+        activeMcpSessions = Math.max(0, activeMcpSessions - 1);
+        if (transport.sessionId) mcpTransports.delete(transport.sessionId);
+      };
+      res.on('close', releaseMcpSession);
+      // Register the transport so POST /mcp/messages can reach it. Without
+      // this the MCP surface was advertised in every discovery document but
+      // unusable: `/mcp/messages` fell through to next() and no tool call
+      // could ever be delivered. The registry is bounded by the same
+      // maxMcpSessions cap and entries are removed when the stream closes.
+      if (transport.sessionId) mcpTransports.set(transport.sessionId, transport);
       const mcpServer = new Server({ name: name, version: "1.0.0" }, { capabilities: { tools: {} } });
-      
       // Auto-generate MCP tool declarations from actions
-      mcpServer.setRequestHandler("tools/list", async () => ({
+      mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: Object.entries(actions).map(([key, val]) => ({
           name: key,
           description: val.description,
@@ -364,22 +1144,51 @@ export function agentsbloom(config = {}) {
         }))
       }));
 
-      mcpServer.setRequestHandler("tools/call", async (request) => {
+      mcpServer.setRequestHandler(CallToolRequestSchema, 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);
+        // v4 medium pass (V12): the same per-action authorization model
+        // applies to MCP tool invocations.
+        //
+        // The identity is read from the TRANSPORT, not from this closure's
+        // captured `authenticatedCacheIdentity`. That variable belongs to the
+        // GET /mcp request that opened the SSE stream — which is not a
+        // protected action path, so it is always null. Authorizing against it
+        // meant `actionAccess: 'authenticated'` could never be satisfied and
+        // `actionIdentities` could never match. The verified identity of the
+        // POST /mcp/messages request that actually carries the tool call is
+        // stashed on the transport by that handler.
+        const mcpIdentity = transport.__agentsbloomIdentity ?? null;
+        req.agentIdentity = mcpIdentity;
+        const accessRejection = authorizeAction(request.params.name, mcpIdentity);
+        if (accessRejection) throw new Error(accessRejection.body.message);
+        // v4: enforce the declared parameter contract. The REST route has
+        // always validated/coerced params; the MCP path now does too, so
+        // merchants get identical type guarantees on both surfaces.
+        const validation = validateActionParams(request.params.arguments || {}, action);
+        if (!validation.ok) throw new Error(validation.message);
+        const result = await action.handler(validation.params, req, res);
         return { content: [{ type: "text", text: JSON.stringify(result) }] };
       });
 
-      return mcpServer.connect(transport);
+      // Second-pass review (N4): if connect() rejects, release the session
+      // slot immediately instead of waiting for a close event that may not
+      // fire for a transport that never started.
+      try {
+        return await mcpServer.connect(transport);
+      } catch (err) {
+        releaseMcpSession();
+        throw err;
+      }
     }
 
     // Serve /llms.txt
     if (req.path === '/llms.txt') {
       res.setHeader('Content-Type', 'text/plain; charset=utf-8');
       res.setHeader('Cache-Control', 'public, max-age=86400, stale-while-revalidate=3600');
-      const defaultLlmDoc = `# ${name}\n\n${description}\n\n## Developer API Reference\n\n- GET /.well-known/agent-spec : Spec sheets\n- GET /ai-catalog.json : Catalog schemas\n`;
-      return res.send(llmsDoc || defaultLlmDoc);
+      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) ---
@@ -388,14 +1197,39 @@ export function agentsbloom(config = {}) {
     const rawIdempotencyKey = req.headers['idempotency-key'];
     const idempotencyHeader = typeof rawIdempotencyKey === 'string' ? rawIdempotencyKey : null;
     let idempotencyKey = null;
-    let authenticatedCacheIdentity = null;
+    // `authenticatedCacheIdentity` / `signatureProfileUsed` are declared above
+    // the /mcp branch so its tool-call closure can read them.
 
     // --- 4. CRYPTOGRAPHIC CAPTCHA BYPASSING (Web Bot Auth + Legacy HMAC) ---
     const isMcpMessage = req.path === '/mcp/messages' && method === 'POST';
+    // Second-pass review (N3): AP2 intent/checkout POSTs are now part of the
+    // signature gate. The agent-side SDK has always signed these posts, but
+    // the merchant gate ignored them - so a mandate alone could check out
+    // anonymously, and per-action authorization policies could never see a
+    // verified identity on the most valuable endpoint. A verified mandate
+    // proves budget INTENT; a signature proves who is spending it.
+    const isAp2WritePath = method === 'POST' && (
+      req.path === '/ap2/intent'
+      || req.path === '/ap2/checkout'
+      || req.path === '/v1/ap2/intent'
+      || req.path === '/v1/ap2/checkout'
+    );
     const isAgentAction = req.path.startsWith('/api/agentsbloom/')
       || req.path.startsWith('/v1/agent/actions/')
-      || isMcpMessage;
-    if (isAgentAction && isWrite && signatureAuthEnabled) {
+      || 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'];
@@ -421,134 +1255,60 @@ export function agentsbloom(config = {}) {
       }
       
       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 });
-          }
+        // RFC 9421 verification now lives in lib/http-signatures.js: real
+        // structured-field parsing, canonical signature base, curve/modulus
+        // pinning, ECDSA P1363, authority validation, digest over the received
+        // bytes, and a replay record that outlives the acceptance window.
+        const verification = await verifyHttpMessageSignature({
+          req,
+          requestContext: requestContextFromExpress(req, { forwardedProto }),
+          signatureHeader: rfcSignature,
+          signatureInputHeader: rfcSignatureInput,
+          jwks: config.agentJwks || null,
+          jwksUrl: typeof config.agentJwksUrl === 'string' ? config.agentJwksUrl : null,
+          jwksCache,
+          nonceCache: signatureNonceMap,
+          nonceNamespace: cacheNamespace,
+          maxAgeMs: signatureMaxAgeMs,
+          clockSkewMs: RFC_SIGNATURE_CLOCK_SKEW_MS,
+          requireAuthority: signatureRequireAuthority,
+          expectedAuthorities,
+          acceptLegacyProfile: acceptLegacySignatureProfile,
+          allowReserializedBody,
+        });
 
-          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 });
+        if (!verification.ok) {
+          // Verifier internals (expected values, raw crypto error text, which
+          // JWKS key was missing) stay server-side. The caller gets a stable
+          // machine-readable code and a generic message.
+          console.error(
+            `🌸 AgentsBloom: RFC 9421 signature verification failed [${verification.code}]: ${verification.detail}`,
+          );
+          return res.status(verification.status).json({
+            error: verification.status === 503 ? 'Service Unavailable' : 'Forbidden',
+            code: verification.code,
+            message: verification.publicMessage,
+          });
         }
+        authenticatedCacheIdentity = verification.identity;
+        signatureProfileUsed = verification.profile;
       } else {
+        // v4 medium pass (V11): resolve a PER-AGENT secret when one is
+        // configured, and reject revoked identifiers outright.
+        if (revokedIdentifiers && typeof identifier === 'string' && revokedIdentifiers.has(identifier)) {
+          return res.status(403).json({
+            error: "Verification Failed",
+            message: "X-Agent-Identifier has been revoked."
+          });
+        }
+        const perAgentSecret = agentKeys && typeof identifier === 'string' ? agentKeys[identifier] : undefined;
+        const effectiveSecret = (typeof perAgentSecret === 'string' && perAgentSecret.length > 0)
+          ? perAgentSecret
+          : agentSecret;
+
         const headerValuePattern = /^[\x21-\x7e]+$/;
         if (
-          !agentSecret ||
+          !effectiveSecret ||
           typeof signature !== 'string' ||
           typeof identifier !== 'string' ||
           typeof timestamp !== 'string' ||
@@ -566,7 +1326,9 @@ export function agentsbloom(config = {}) {
           });
         }
 
-        const timestampSeconds = Number(timestamp);
+        // Bound the timestamp string before Number() so a 10,000-digit value
+        // never reaches the parser.
+        const timestampSeconds = timestamp.length <= 20 ? Number(timestamp) : NaN;
         const timestampMs = timestampSeconds * 1000;
         const nowMs = Date.now();
         if (!Number.isSafeInteger(timestampSeconds) || Math.abs(nowMs - timestampMs) > signatureMaxAgeMs) {
@@ -577,12 +1339,6 @@ export function agentsbloom(config = {}) {
         }
 
         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 {
@@ -593,27 +1349,80 @@ export function agentsbloom(config = {}) {
             message: "Request body cannot be serialized for signature verification."
           });
         }
-        if (!verifySignature(signature, signaturePayload, agentSecret)) {
+        // 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."
           });
         }
 
-        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."
+        // v4: atomic claim AFTER successful verification - failed attempts
+        // never burn the nonce, and concurrent replays cannot slip through
+        // the old has()/set() race window.
+        //
+        // The record must outlive the window in which this signature could
+        // still be accepted. `timestampMs + signatureMaxAgeMs` alone was too
+        // short for a timestamp already near the edge of the window: the
+        // nonce expired while the signature was still considered fresh,
+        // re-opening replay. Floor it at now + the full window.
+        const legacyRetainUntilMs = Math.max(
+          timestampMs + signatureMaxAgeMs,
+          nowMs + signatureMaxAgeMs,
+        );
+        const claimed = await signatureNonceMap.claim(replayKey, legacyRetainUntilMs);
+        if (!claimed) {
+          return res.status(403).json({
+            error: "Verification Failed",
+            message: "X-Agent-Signature nonce has already been used."
           });
         }
-        signatureNonceMap.set(replayKey, timestampMs + signatureMaxAgeMs);
         authenticatedCacheIdentity = `legacy:${identifier}`;
       }
     }
 
+    // Expose the verified signature identity (rfc:<keyid> or legacy:<id>)
+    // to merchant handlers: stores persist it on orders to correlate
+    // purchases with the agent-reputation system. Null for unsigned
+    // traffic - never trust the raw self-asserted header alone.
+    req.agentIdentity = authenticatedCacheIdentity;
+    req.agentSignatureProfile = signatureProfileUsed;
+
+    // --- MCP message delivery ---
+    //
+    // Routed here, AFTER the signature gate, so a tool call carries a verified
+    // identity. Previously this path was never wired at all: `/mcp` handed the
+    // client a `/mcp/messages` endpoint, but a POST to it fell straight through
+    // to next(), so the MCP surface advertised in every discovery document
+    // could not actually execute a tool.
+    if (isMcpMessage) {
+      const sessionId = typeof req.query?.sessionId === 'string' ? req.query.sessionId : null;
+      const transport = sessionId ? mcpTransports.get(sessionId) : null;
+      if (!transport) {
+        return res.status(404).json({
+          error: 'Unknown MCP Session',
+          message: 'No open MCP SSE session matches this sessionId. Open GET /mcp first and reuse the endpoint it returns.',
+        });
+      }
+      // Hand the verified identity to the tool-call handler, which runs in the
+      // SSE request's closure and therefore cannot see this request directly.
+      transport.__agentsbloomIdentity = authenticatedCacheIdentity;
+      try {
+        return await transport.handlePostMessage(req, res, req.body);
+      } catch (err) {
+        console.error('🌸 AgentsBloom: MCP message delivery failed:', err?.message);
+        if (!res.headersSent) {
+          return res.status(400).json({ error: 'Invalid MCP Message' });
+        }
+        return undefined;
+      }
+    }
+
     // --- 3b. IDEMPOTENCY CHECKS FOR WRITES (POST/PUT/PATCH/DELETE) ---
     // Perform this lookup only after the protected-route authentication gate.
     // Cache keys are scoped to this middleware instance and the verified agent
@@ -650,43 +1459,143 @@ export function agentsbloom(config = {}) {
 
       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);
       }
     }
 
+    /**
+     * Installs store-and-replay capture for the current Idempotency-Key.
+     *
+     * Previously this patch was installed ONLY inside the REST action-routing
+     * branch, so `/ap2/checkout` and `/api/agentsbloom/checkout/acp` — the two
+     * endpoints that mint payment links — accepted an Idempotency-Key, served
+     * no replay for it, and re-ran the checkout handler on every retry.
+     *
+     * Safe to call more than once; the patch installs at most once per
+     * response.
+     */
+    function captureIdempotentResponse(response) {
+      if (!isWrite || !idempotencyKey || response.__agentsbloomIdempotencyPatched) return;
+      response.__agentsbloomIdempotencyPatched = true;
+      const originalSend = response.send;
+      response.send = function patchedSend(body) {
+        if (response.statusCode >= 200 && response.statusCode < 300) {
+          // v4 (V18): evict the oldest entry at capacity instead of growing
+          // without bound between TTL sweeps.
+          if (!idempotencyMap.has(idempotencyKey) && idempotencyMap.size >= IDEMPOTENCY_MAX_ENTRIES) {
+            const oldestKey = idempotencyMap.keys().next().value;
+            if (oldestKey !== undefined) idempotencyMap.delete(oldestKey);
+          }
+          idempotencyMap.set(idempotencyKey, {
+            responseBody: body,
+            status: response.statusCode,
+            headers: { 'content-type': response.getHeader('content-type') },
+            timestamp: Date.now(),
+            expiry: Date.now() + IDEMPOTENCY_TTL,
+          });
+        }
+        return originalSend.apply(this, arguments);
+      };
+    }
+
     // --- 4b. AP2 MANDATE VERIFICATION (Wired into middleware) ---
-    const ap2MandateHeader = req.headers['x-ap2-mandate'] || req.headers['authorization'];
+    // v4: the legacy `authorization` header fallback is now only honored on
+    // requests that are ALREADY AP2-shaped (an /ap2 path or x-protocol AP2).
+    // Previously ANY request carrying a dotted Authorization value - which
+    // includes every ordinary OAuth/JWT bearer token - was parsed as an AP2
+    // SD-JWT, failed verification, and had the whole request rejected 403,
+    // breaking unrelated authenticated routes. The explicit
+    // `x-ap2-mandate` header works everywhere as before.
     const detectedProtocol = resolveProtocol(req);
+    const rawAuthorizationHeader = req.headers['authorization'];
+    const ap2MandateHeader = req.headers['x-ap2-mandate']
+      || (detectedProtocol === 'AP2' && typeof rawAuthorizationHeader === 'string'
+        ? rawAuthorizationHeader
+        : null);
     let ap2MandateResult = null;
 
     if (detectedProtocol === 'AP2' || (ap2MandateHeader && ap2MandateHeader.includes('.'))) {
+      // Second-pass review (N2): the mandate's single-use jti must only be
+      // consumed where the mandate is actually USED. Verification still
+      // runs wherever a mandate is presented (so merchant handlers keep
+      // receiving req.ap2Mandate), but a mandate riding along on an
+      // unrelated cart-add no longer burns itself.
+      const isAp2Endpoint = req.path.startsWith('/ap2/') || req.path.startsWith('/v1/ap2/');
+      // Cart Mandate binding: only the checkout consumer recomputes the
+      // merchant's canonical cart hash. A merchant that configures
+      // ap2.computeCartHash(req) gets a hard reject when a cart-bound
+      // mandate is presented against different cart contents; without the
+      // callback, binding stays 'unverified' (surfaced, never silent).
+      const isAp2CheckoutPath = req.path === '/ap2/checkout' || req.path === '/v1/ap2/checkout';
+      let expectedCartHash = null;
+      let cartHashComputationFailed = false;
+      if (isAp2CheckoutPath && typeof config.ap2?.computeCartHash === 'function') {
+        try {
+          expectedCartHash = config.ap2.computeCartHash(req) || null;
+        } catch (err) {
+          // A throwing hook used to be swallowed into `null`, which silently
+          // downgraded a cart-bound mandate to 'unverified' — exactly the
+          // state the checkout gate is supposed to refuse. Record the failure
+          // so the gate can reject instead of guessing.
+          cartHashComputationFailed = true;
+          expectedCartHash = null;
+          console.error('🌸 AgentsBloom: ap2.computeCartHash threw; treating the session cart as unverifiable:', err?.message);
+        }
+      }
       // Verify the SD-JWT mandate before allowing any write action. Uses
       // either a merchant-configured trusted public key (config.ap2PublicKey)
       // or, when absent, derives a key from the mandate's own did:key issuer
       // (self-certifying - see lib/ap2.js for why an unverifiable mandate is
       // now rejected outright rather than passed through as "valid").
-      ap2MandateResult = verifyAP2Mandates(req.headers, req.body || {}, {
+      ap2MandateResult = await verifyAP2Mandates(req.headers, req.body || {}, {
         trustedPublicKey: config.ap2PublicKey || null,
-        expectedAudience: config.ap2?.expectedAudience || requestUrl,
+        // v4: production-grade trust policy. When ap2.trustedIssuersOnly is
+        // set, self-certifying did:key mandates (which anyone can mint for
+        // any budget) are rejected in favor of the merchant-trusted key.
+        allowSelfCertifying: config.ap2?.trustedIssuersOnly !== true,
+        // Audience binding prefers explicit configuration, then the
+        // merchant-configured baseUrl (a trusted deployment constant), and
+        // only falls back to the Host-derived requestUrl when neither is
+        // set - deriving the expected audience purely from the request's
+        // own Host header would let an attacker align a stolen mandate's
+        // audience with a spoofed Host.
+        expectedAudience: config.ap2?.expectedAudience || (baseUrl ? baseUrl : requestUrl),
         maxMandateLifetimeSec: config.ap2?.maxMandateLifetimeSec,
         requireJti: config.ap2?.requireJti,
         requestedCategories: req.body?.requestedCategories || config.ap2?.requestedCategories,
+        expectedCurrency: config.ap2?.expectedCurrency,
+        requireCurrency: config.ap2?.requireCurrency !== false,
+        clockSkewSec: config.ap2?.clockSkewSec,
+        consumeJti: isAp2Endpoint,
+        ...(isAp2CheckoutPath ? { expectedCartHash } : {}),
       });
 
       if (!ap2MandateResult.valid) {
+        // Disclosure policy: an agent must be able to learn that its budget is
+        // too low or its cart does not match, so it can self-correct. It must
+        // NOT learn this store's expected audience or currency, which JWKS key
+        // was missing, or raw crypto error text. lib/ap2.js classifies each
+        // rejection; the HTTP layer honors that classification.
+        const discloseReason = config.ap2?.exposeReasons === true || ap2MandateResult.disclose === true;
+        if (!discloseReason) {
+          console.error(
+            `🌸 AgentsBloom: AP2 mandate rejected [${ap2MandateResult.code}]: ${ap2MandateResult.reason}`,
+          );
+        }
         return res.status(403).json({
           error: "AP2 Mandate Rejected",
           protocol: "AP2",
-          reason: ap2MandateResult.reason,
+          code: ap2MandateResult.code,
+          reason: discloseReason ? ap2MandateResult.reason : ap2MandateResult.publicReason,
           message: "The Verifiable Intent mandate failed validation. The agent's payment authorization is invalid."
         });
       }
 
       // Attach mandate info to request for downstream handlers
       req.ap2Mandate = ap2MandateResult;
+      ap2MandateResult.cartHashComputationFailed = cartHashComputationFailed;
     }
 
     // --- AP2 Discovery Endpoint ---
@@ -697,6 +1606,12 @@ export function agentsbloom(config = {}) {
         store: { name, description, baseUrl: requestUrl },
         mandateTypes: ["intentMandate", "cartMandate", "paymentMandate"],
         verificationMethods: ["sd-jwt", "jwt"],
+        features: {
+          budgetEnforcement: true,
+          cartBinding: true,
+          currencyBinding: true,
+          replayProtection: true
+        },
         endpoints: {
           capabilities: `${requestUrl}/ap2/capabilities`,
           intent: `${requestUrl}/ap2/intent`,
@@ -704,7 +1619,11 @@ export function agentsbloom(config = {}) {
           actions: Object.keys(actions).map(k => `${requestUrl}/v1/agent/actions/${k}`)
         },
         budgetEnforcement: true,
-        signatureAlgorithms: ["ES256", "ES384", "ES512", "RS256", "RS384", "RS512", "EdDSA"]
+        // Advertise what the verifier actually accepts. The old hardcoded list
+        // claimed ES256/384/512 support while ECDSA verification was broken
+        // outright (DER vs raw r||s), so an agent that followed the discovery
+        // document could never authenticate.
+        signatureAlgorithms: [...SUPPORTED_MANDATE_ALGORITHMS]
       });
     }
 
@@ -752,44 +1671,226 @@ export function agentsbloom(config = {}) {
         });
       }
 
+      // Hardened Cart Mandate verification: If the mandate declares an exact
+      // Cart Mandate (signed cartHash), the store MUST verify that cartHash
+      // against the actual session cart. Unverified cart mandates are rejected
+      // unless explicitly allowed by config (allowUnverifiedCartMandates: true).
+      const hasDeclaredCartMandate = Boolean(ap2MandateResult.mandates?.cartMandate?.cartHash);
+      if (
+        hasDeclaredCartMandate &&
+        ap2MandateResult.cartBinding === 'unverified' &&
+        config.ap2?.allowUnverifiedCartMandates !== true
+      ) {
+        return res.status(403).json({
+          error: "AP2 Cart Mandate Verification Required",
+          protocol: "AP2",
+          code: 'cart_binding_unverified',
+          reason: ap2MandateResult.cartHashComputationFailed
+            ? "This mandate is cryptographically bound to an exact cart hash, but this store's computeCartHash hook failed, so the session cart could not be verified."
+            : "This mandate is cryptographically bound to an exact cart hash, but this store has not verified the session cart (configure config.ap2.computeCartHash).",
+          message: "Cart Mandate verification failed: the store cannot confirm the session cart matches the signed mandate."
+        });
+      }
+
       const checkoutAction = actions['checkout'];
       if (!checkoutAction || typeof checkoutAction.handler !== 'function') {
         return res.status(404).json({ error: 'Checkout action not configured for this store.' });
       }
 
-      // Validate budget before executing checkout
-      const orderTotal = req.body?.orderTotal || req.body?.total || 0;
-      const maxBudget = ap2MandateResult.mandates?.intentMandate?.maxBudget
-                     || ap2MandateResult.mandates?.paymentMandate?.maxBudget;
+      // v4 medium pass (V12): mandate verification proves budget intent,
+      // not identity authorization - the checkout action still respects
+      // the merchant's per-action policy.
+      const checkoutAccessRejection = authorizeAction('checkout', authenticatedCacheIdentity);
+      if (checkoutAccessRejection) {
+        return res.status(checkoutAccessRejection.status).json(checkoutAccessRejection.body);
+      }
+
+      // The declared parameter contract was enforced on every REST action and
+      // on MCP tool calls, but NOT here — the highest-value endpoint in the
+      // SDK passed `req.body` to the handler unvalidated.
+      const checkoutValidation = validateActionParams({ ...(req.body || {}) }, checkoutAction);
+      if (!checkoutValidation.ok) {
+        return res.status(400).json({
+          error: "Invalid Parameter",
+          protocol: "AP2",
+          message: checkoutValidation.message,
+        });
+      }
+
+      // --- Budget enforcement ---
+      //
+      // A checkout mandate MUST declare a positive maxBudget: a capless
+      // mandate authorizes unlimited spend.
+      //
+      // Note `??` rather than `||`. With `||`, an `orderTotal` of 0 fell
+      // through to `total`, and a `maxBudget` of 0 fell through to the payment
+      // mandate's — both silent value substitutions on a money field.
+      const rawOrderTotal = req.body?.orderTotal ?? req.body?.total ?? 0;
+      const rawMaxBudget = ap2MandateResult.mandates?.intentMandate?.maxBudget
+                        ?? ap2MandateResult.mandates?.paymentMandate?.maxBudget;
+
+      const maxBudgetAmount = parseAmount(rawMaxBudget, { allowZero: false });
+      if (maxBudgetAmount === null) {
+        return res.status(403).json({
+          error: "AP2 Mandate Rejected",
+          protocol: "AP2",
+          code: 'budget_missing',
+          reason: "Mandate must declare a positive intentMandate.maxBudget for checkout",
+          message: "A checkout mandate without a spending cap authorizes unlimited spend and is rejected. Reissue the mandate with maxBudget."
+        });
+      }
 
-      if (maxBudget && Number(orderTotal) > Number(maxBudget)) {
+      // The client-declared total is a fast-fail convenience only. It is
+      // attacker-controlled and never the basis of authorization — but it must
+      // still be well-formed, because `Number('abc')` is NaN and every
+      // comparison against NaN is false, so a malformed total used to PASS
+      // this check instead of failing it.
+      const clientTotalAmount = parseAmount(rawOrderTotal, { allowZero: true });
+      if (clientTotalAmount === null) {
+        return res.status(400).json({
+          error: "Invalid Request",
+          protocol: "AP2",
+          code: 'order_total_invalid',
+          message: "orderTotal must be a non-negative number.",
+        });
+      }
+
+      // v4 medium pass (V17): a budget number without a matching currency is
+      // unitless. lib/ap2.js already rejects a mandate that declares a budget
+      // with no currency (`requireCurrency`); these checks pin it to the
+      // store's and the order's currency.
+      const mandateCurrency = normalizeCurrencyCode(
+        ap2MandateResult.mandates?.intentMandate?.currency
+        ?? ap2MandateResult.mandates?.paymentMandate?.currency,
+      );
+      const expectedCheckoutCurrency = normalizeCurrencyCode(config.ap2?.expectedCurrency);
+      if (mandateCurrency && expectedCheckoutCurrency && mandateCurrency !== expectedCheckoutCurrency) {
+        // Echoing the store's configured currency back is a config disclosure;
+        // log it, tell the caller only that there is a mismatch.
+        console.error(
+          `🌸 AgentsBloom: AP2 checkout currency mismatch: mandate "${mandateCurrency}" vs store "${expectedCheckoutCurrency}"`,
+        );
+        return res.status(403).json({
+          error: "AP2 Mandate Rejected",
+          protocol: "AP2",
+          code: 'currency_mismatch_store',
+          reason: config.ap2?.exposeReasons === true
+            ? `Mandate currency "${mandateCurrency}" does not match this store's expected currency "${expectedCheckoutCurrency}"`
+            : 'The mandate was issued for a different currency than this store accepts.',
+          message: "The mandate was issued for a different currency than this store accepts."
+        });
+      }
+      const orderCurrency = req.body?.currency === undefined || req.body?.currency === null
+        ? null
+        : normalizeCurrencyCode(req.body.currency);
+      if (req.body?.currency !== undefined && req.body?.currency !== null && !orderCurrency) {
+        return res.status(400).json({
+          error: "Invalid Request",
+          protocol: "AP2",
+          code: 'order_currency_invalid',
+          message: "currency must be a valid ISO 4217 alphabetic code.",
+        });
+      }
+      if (mandateCurrency && orderCurrency && mandateCurrency !== orderCurrency) {
+        return res.status(403).json({
+          error: "AP2 Budget Exceeded",
+          protocol: "AP2",
+          code: 'currency_mismatch_order',
+          reason: `Order currency "${orderCurrency}" does not match the mandate's currency "${mandateCurrency}"`,
+          message: "Order currency does not match the mandate's declared currency."
+        });
+      }
+
+      // Exact comparison. `Number(a) > Number(b)` on doubles could accept a
+      // total a fraction of a cent over the authorized cap.
+      if (compareAmounts(clientTotalAmount.decimal, maxBudgetAmount.decimal) === 1) {
         return res.status(403).json({
           error: "AP2 Budget Exceeded",
           protocol: "AP2",
-          orderTotal: Number(orderTotal),
-          maxBudget: Number(maxBudget),
-          message: `Order total $${orderTotal} exceeds mandate budget limit of $${maxBudget}.`
+          code: 'budget_exceeded',
+          orderTotal: Number(clientTotalAmount.decimal),
+          maxBudget: Number(maxBudgetAmount.decimal),
+          message: `Order total ${clientTotalAmount.decimal} exceeds mandate budget limit of ${maxBudgetAmount.decimal}.`
         });
       }
 
-      return Promise.resolve(checkoutAction.handler(req.body, req, res))
+      const issuerTrust = ap2MandateResult.selfCertifying ? 'self-certifying' : 'merchant-trusted';
+      // Store-and-replay for the Idempotency-Key. Every REST action installed
+      // this; /ap2/checkout did not, so a retried checkout re-ran the handler.
+      captureIdempotentResponse(res);
+
+      return Promise.resolve(checkoutAction.handler(checkoutValidation.params, req, res))
         .then(result => {
+          const rawServerTotal = result && (result.total ?? result.totalPrice);
+          const serverTotalAmount = rawServerTotal === undefined || rawServerTotal === null
+            ? null
+            : parseAmount(rawServerTotal, { allowZero: true });
+
+          // --- The authoritative check ---
+          //
+          // This is the bypass that mattered most. The old code computed
+          //   effectiveTotal = serverTotal !== undefined ? Number(serverTotal) : Number(orderTotal)
+          // and then only enforced the cap `if (Number.isFinite(effectiveTotal))`.
+          // So a handler that returned no total at all, or a non-numeric one,
+          // produced NaN, `Number.isFinite(NaN)` was false, and the budget
+          // check was SKIPPED ENTIRELY — a payment URL was issued with zero
+          // enforcement while the response still reported budgetEnforced:true.
+          //
+          // A total we cannot parse is now a hard failure, never a pass.
+          if (serverTotalAmount === null) {
+            if (config.ap2?.requireHandlerTotal === false) {
+              // Explicit opt-out: fall back to the client-declared total,
+              // which was already validated and compared above. Reported
+              // honestly as such so nobody mistakes it for enforcement.
+              if (!res.headersSent) {
+                res.json(buildAp2CheckoutResponse({
+                  result,
+                  totalSource: 'client-declared',
+                  orderTotalDecimal: clientTotalAmount.decimal,
+                }));
+              }
+              return undefined;
+            }
+            console.error(
+              '🌸 AgentsBloom: the checkout handler returned no usable `total`/`totalPrice`, so the AP2 mandate budget '
+              + `cannot be enforced (received: ${JSON.stringify(rawServerTotal)}). Return a numeric total, or set `
+              + 'ap2.requireHandlerTotal:false to authorize against the client-declared total instead.',
+            );
+            if (!res.headersSent) {
+              res.status(500).json({
+                error: 'AP2 Checkout Misconfigured',
+                protocol: 'AP2',
+                code: 'handler_total_missing',
+                message: 'This store could not compute an authoritative order total, so the mandate budget could not be enforced. No checkout link was issued.',
+              });
+            }
+            return undefined;
+          }
+
+          if (compareAmounts(serverTotalAmount.decimal, maxBudgetAmount.decimal) === 1) {
+            if (!res.headersSent) {
+              res.status(403).json({
+                error: "AP2 Budget Exceeded",
+                protocol: "AP2",
+                code: 'budget_exceeded_server',
+                reason: "Server-computed order total exceeds the mandate's maxBudget; the client-declared orderTotal is never authoritative.",
+                orderTotal: Number(serverTotalAmount.decimal),
+                totalSource: 'handler',
+                maxBudget: Number(maxBudgetAmount.decimal),
+                message: `Order total ${serverTotalAmount.decimal} computed by the store exceeds mandate budget limit of ${maxBudgetAmount.decimal}. No checkout link was issued.`
+              });
+            }
+            return undefined;
+          }
+
           if (!res.headersSent) {
-            res.json({
-              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
-            });
+            res.json(buildAp2CheckoutResponse({
+              result,
+              totalSource: 'handler',
+              orderTotalDecimal: serverTotalAmount.decimal,
+            }));
           }
+          return undefined;
         })
         .catch(err => {
           console.error("AP2 Checkout error:", err);
@@ -797,19 +1898,63 @@ export function agentsbloom(config = {}) {
             res.status(500).json({ error: 'Internal AP2 checkout error', protocol: 'AP2' });
           }
         });
+
+      /** Shapes the authorized-checkout response with honest evidence. */
+      function buildAp2CheckoutResponse({ result, totalSource, orderTotalDecimal }) {
+        return {
+          protocol: "AP2",
+          verifiableIntent: {
+            mandateVerified: ap2MandateResult.verified,
+            // Reports what actually happened rather than `!!maxBudget`: the
+            // cap was compared against a store-computed total only when the
+            // handler supplied one.
+            budgetEnforced: totalSource === 'handler',
+            issuerTrust,
+            cartBinding: ap2MandateResult.cartBinding || 'absent',
+            maxBudget: Number(maxBudgetAmount.decimal),
+            currency: mandateCurrency || null,
+            orderTotal: Number(orderTotalDecimal),
+            totalSource,
+            signatureIdentity: authenticatedCacheIdentity,
+            ...(signatureProfileUsed ? { signatureProfile: signatureProfileUsed } : {}),
+          },
+          session_id: result?.sessionId || `ap2_sess_${crypto.randomUUID()}`,
+          payment_url: result?.paymentUrl,
+          status: "authorized",
+          expires_at: Math.floor(Date.now() / 1000) + 3600,
+          checkout: result
+        };
+      }
     }
 
     // --- 5. HANDLE ACTION ROUTING ---
     // Agentic Commerce Protocol (ACP) Checkout Wrapper
+    //
+    // This branch returns before the action-routing branch below, so it used
+    // to skip BOTH `authorizeAction` and `validateActionParams`: a store that
+    // configured `actionAccess.checkout = 'authenticated'` or restricted
+    // `actionIdentities.checkout` had those policies silently ignored on this
+    // path, and the handler received an unvalidated body. The RFC/legacy
+    // signature gate did apply (the path is under /api/agentsbloom/), but
+    // per-action authorization did not.
     if (req.path === '/api/agentsbloom/checkout/acp' && req.method === 'POST') {
       const checkoutAction = actions['checkout'];
       if (checkoutAction && typeof checkoutAction.handler === 'function') {
-        return Promise.resolve(checkoutAction.handler(req.body, req, res))
+        const acpAccessRejection = authorizeAction('checkout', authenticatedCacheIdentity);
+        if (acpAccessRejection) {
+          return res.status(acpAccessRejection.status).json(acpAccessRejection.body);
+        }
+        const acpValidation = validateActionParams({ ...(req.body || {}) }, checkoutAction);
+        if (!acpValidation.ok) {
+          return res.status(400).json({ error: "Invalid Parameter", message: acpValidation.message });
+        }
+        captureIdempotentResponse(res);
+        return Promise.resolve(checkoutAction.handler(acpValidation.params, req, res))
           .then(result => {
             if (!res.headersSent) {
               res.json({
-                session_id: result.sessionId || `acp_sess_${Date.now()}`,
-                payment_url: result.paymentUrl,
+                session_id: result?.sessionId || `acp_sess_${crypto.randomUUID()}`,
+                payment_url: result?.paymentUrl,
                 status: "open",
                 expires_at: Math.floor(Date.now() / 1000) + 3600
               });
@@ -827,7 +1972,7 @@ export function agentsbloom(config = {}) {
     }
 
     if (req.path.startsWith('/api/agentsbloom/') || req.path.startsWith('/v1/agent/actions/')) {
-      const actionName = req.path.replace('/api/agentsbloom/', '').replace('/v1/agent/actions/', '');
+      const actionName = requestedActionName;
       const action = actions[actionName];
 
       if (action && typeof action.handler === 'function') {
@@ -841,55 +1986,64 @@ export function agentsbloom(config = {}) {
           });
         }
 
-        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}` });
-            }
-          }
+        // 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) {
-            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);
-        };
+        captureIdempotentResponse(res);
 
         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)
+        // Telemetry labels must be bounded. Passing a raw agent-supplied header
+        // through as an OTel metric dimension let a caller mint unbounded time
+        // series inside the merchant's own monitoring pipeline. Prefer the
+        // VERIFIED identity when we have one; fall back to a bounded rendering
+        // of the self-asserted header.
+        const agentName = boundedLabel(
+          authenticatedCacheIdentity
+            || req.headers['x-agent-identifier']
+            || req.headers['signature-agent'],
+          'Unknown Agent',
+        );
+
+        // Extract W3C Trace Context from incoming request (HIGH-16).
+        // The span name is a metric dimension too: `actionName` comes from the
+        // URL path, so bound it even though it matched a declared action.
         const parentContext = propagation.extract(context.active(), req.headers);
-        const span = tracer.startSpan(`agent_request:${actionName}`, {}, parentContext);
-        
-        return Promise.resolve(action.handler(params, req, res))
+        const span = tracer.startSpan(`agent_request:${boundedLabel(actionName, 'unknown')}`, {}, parentContext);
+
+        return Promise.resolve(action.handler(validatedParams, req, res))
           .then(result => {
             if (!res.headersSent) {
               res.json(result);
             }
             
             const latencyMs = Date.now() - startTime;
-            const revenue = result && result.totalPrice ? result.totalPrice : 0;
+            // Revenue is a merchant-supplied number; a non-finite value would
+            // poison the counter permanently.
+            const revenueAmount = parseAmount(result?.totalPrice, { allowZero: false });
 
             // OpenTelemetry Native Instrumentation
             span.setAttribute('agent.name', agentName);
-            span.setAttribute('agent.route', `/api/agentsbloom/${actionName}`);
+            span.setAttribute('agent.route', `/api/agentsbloom/${boundedLabel(actionName, 'unknown')}`);
             span.setAttribute('http.status_code', res.statusCode);
             span.setAttribute('http.latency_ms', latencyMs);
-            
+
             agentRequestsCounter.add(1, { agent: agentName });
-            if (revenue) agentRevenueCounter.add(revenue, { agent: agentName });
+            if (revenueAmount) agentRevenueCounter.add(Number(revenueAmount.decimal), { agent: agentName });
             span.end();
 
             // Telemetry is handled by OTLP exporters configured via setupTelemetry().
@@ -914,10 +2068,32 @@ export function agentsbloom(config = {}) {
       return next();
     }
 
+    // --- HTML injection buffering limits ---
+    //
+    // This path buffers the ENTIRE HTML response in memory so it can splice in
+    // JSON-LD and the WebMCP loader. Previously it did so with no size cap and
+    // then called `zlib.gunzipSync` / `zlib.gzipSync`, which means:
+    //   * any large or streamed page was fully materialized in memory,
+    //   * a compressed upstream response was a decompression-amplification
+    //     vector (a few MB of gzip expands to gigabytes),
+    //   * the synchronous zlib calls blocked the event loop for every request,
+    //   * `res.write` always returned `true`, discarding backpressure.
+    //
+    // Now: buffering stops at a cap and the response passes through unmodified
+    // beyond it, decompression is bounded by `maxOutputLength`, and the
+    // recompression happens off the main path.
+    const htmlInjectionMaxBytes = Number.isFinite(config.htmlInjection?.maxBytes) && config.htmlInjection.maxBytes > 0
+      ? config.htmlInjection.maxBytes
+      : 2 * 1024 * 1024;
+
     const originalWrite = res.write;
     const originalEnd = res.end;
     let chunks = [];
+    let bufferedBytes = 0;
     let isHtml = false;
+    // Once the cap is exceeded we stop rewriting and flush what we hold,
+    // becoming a transparent pass-through for the rest of the response.
+    let passThrough = false;
 
     const originalWriteHead = res.writeHead;
     res.writeHead = function (statusCode, headers) {
@@ -930,96 +2106,132 @@ export function agentsbloom(config = {}) {
       return originalWriteHead.apply(this, arguments);
     };
 
-    res.write = function (chunk) {
+    /** Flushes buffered chunks and stops intercepting. */
+    function abandonInjection() {
+      passThrough = true;
+      const pending = chunks;
+      chunks = [];
+      bufferedBytes = 0;
+      for (const chunk of pending) originalWrite.call(res, chunk);
+    }
+
+    res.write = function (chunk, ...rest) {
       const contentType = res.getHeader('Content-Type') || '';
-      if (isHtml || (typeof contentType === 'string' && contentType.includes('text/html'))) {
+      if (!passThrough && (isHtml || (typeof contentType === 'string' && contentType.includes('text/html')))) {
         isHtml = true;
-        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+        const buffered = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk ?? '');
+        if (bufferedBytes + buffered.length > htmlInjectionMaxBytes) {
+          // Too large to rewrite safely: flush and hand back control, so
+          // backpressure and streaming behave normally from here on.
+          abandonInjection();
+          return originalWrite.call(res, buffered, ...rest);
+        }
+        chunks.push(buffered);
+        bufferedBytes += buffered.length;
         return true;
       }
       return originalWrite.apply(res, arguments);
     };
 
-    res.end = function (chunk) {
+    res.end = function (chunk, ...rest) {
       const contentType = res.getHeader('Content-Type') || '';
-      if (isHtml || (typeof contentType === 'string' && contentType.includes('text/html'))) {
+      if (!passThrough && (isHtml || (typeof contentType === 'string' && contentType.includes('text/html')))) {
         isHtml = true;
         if (chunk) {
-          chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+          const buffered = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+          if (bufferedBytes + buffered.length > htmlInjectionMaxBytes) {
+            abandonInjection();
+            return originalEnd.call(res, buffered, ...rest);
+          }
+          chunks.push(buffered);
+          bufferedBytes += buffered.length;
         }
-        
+
         let bodyBuffer = Buffer.concat(chunks);
         const encoding = res.getHeader('Content-Encoding');
         const isGzipped = typeof encoding === 'string' && encoding.includes('gzip');
 
-        // Decompress if gzipped
+        // Decompress if gzipped, with a hard output bound so a compression
+        // bomb cannot allocate unbounded memory.
         if (isGzipped) {
           try {
-            bodyBuffer = zlib.gunzipSync(bodyBuffer);
+            bodyBuffer = zlib.gunzipSync(bodyBuffer, { maxOutputLength: htmlInjectionMaxBytes });
           } catch (err) {
-            console.error("AgentsBloom decompression error:", err);
+            // Includes ERR_BUFFER_TOO_LARGE when the bound is hit: leave the
+            // response exactly as the application produced it.
+            console.error('AgentsBloom: skipping HTML injection (decompression failed or exceeded the size cap):', err?.message);
+            return originalEnd.call(res, Buffer.concat(chunks), ...rest);
           }
         }
 
         let body = bodyBuffer.toString('utf8');
 
         if (body.toLowerCase().includes('</body>')) {
+          // v4 (stored-XSS fix): merchant-controlled strings (store name,
+          // description, action names/descriptions) are no longer spliced
+          // into inline JavaScript or raw JSON.stringify output. JSON.stringify
+          // does NOT escape `</script>`, so a crafted description used to be
+          // able to break out of the script tag and execute on every page.
+          // All dynamic data is now serialized through toSafeJson() (hex-
+          // escaped `<`, `>`, `&`, U+2028/2029) and consumed as DATA by a
+          // static loader - the same approach as the hardened next-sdk.
           const jsonLdData = {
             "@context": "https://schema.org",
             "@type": "WebPage",
             "name": name,
             "description": description,
-            "potentialAction": Object.entries(actions).map(([key, val]) => ({
+            "potentialAction": Object.entries(actions).map(([key]) => ({
               "@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 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') {
-    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);
+  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 };
           }
-          
-          const response = await fetch(url, fetchOptions);
-          return await response.json();
-        } catch (e) {
-          return { error: e.message };
         }
-      }
-    });
-    `).join('\n')}
+      });
+    })(tools[i]);
   }
 })();
 </script>
@@ -1034,20 +2246,26 @@ export function agentsbloom(config = {}) {
           body = body.replace(/<\/body>/i, `${webMcpScript}\n</body>`);
         }
 
-        let outputBuffer = Buffer.from(body);
+        let outputBuffer = Buffer.from(body, 'utf8');
 
-        // Re-compress if gzipped
+        // Re-compress if gzipped. On failure, fall back to sending the
+        // uncompressed body and drop the now-inaccurate Content-Encoding
+        // rather than shipping a body the client cannot decode.
         if (isGzipped) {
           try {
             outputBuffer = zlib.gzipSync(outputBuffer);
           } catch (err) {
-            console.error("AgentsBloom compression error:", err);
+            console.error('AgentsBloom compression error:', err?.message);
+            res.removeHeader('Content-Encoding');
           }
         }
 
         res.setHeader('Content-Length', outputBuffer.length);
         originalWrite.call(res, outputBuffer);
-        return originalEnd.call(res);
+        // Forward res.end's own arguments (encoding, completion callback).
+        // Calling `originalEnd.call(res)` bare dropped the callback, so
+        // frameworks awaiting response completion never resolved.
+        return originalEnd.call(res, ...(chunk !== undefined ? rest : []));
       }
       return originalEnd.apply(res, arguments);
     };
@@ -1058,20 +2276,32 @@ export function agentsbloom(config = {}) {
 
 // --- 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')) {
+  const accept = String((req.headers && req.headers['accept']) || '');
+  const xProtocol = String((req.headers && req.headers['x-protocol']) || '').toLowerCase();
+  const rawPath = String(req.path || req.url || '');
+  // Strip any query string so `/ap2?x=1` classifies like `/ap2`.
+  const path = rawPath.split('?')[0];
+
+  /**
+   * Matches a path PREFIX on a segment boundary.
+   *
+   * `path.startsWith('/ap2')` also matched `/ap2foo` and `/ap2-internal`, so
+   * unrelated merchant routes were classified as AP2 and inherited the
+   * `Authorization`-header-as-mandate fallback — turning an ordinary bearer
+   * token on such a route into a failed mandate and a 403.
+   */
+  const underSegment = (prefix) => path === prefix || path.startsWith(`${prefix}/`);
+
+  if (accept.includes('application/mcp+json') || underSegment('/mcp')) {
     return 'WEBMCP';
   }
-  if (xProtocol.toLowerCase() === 'ucp' || path.startsWith('/.well-known/ucp') || path.startsWith('/ucp')) {
+  if (xProtocol === 'ucp' || underSegment('/.well-known/ucp') || underSegment('/ucp')) {
     return 'UCP';
   }
-  if (xProtocol.toLowerCase() === 'acp' || path.startsWith('/acp')) {
+  if (xProtocol === 'acp' || underSegment('/acp')) {
     return 'ACP';
   }
-  if (req.headers && (req.headers['x-ap2-mandate'] || path.startsWith('/ap2'))) {
+  if ((req.headers && req.headers['x-ap2-mandate']) || underSegment('/ap2') || underSegment('/v1/ap2')) {
     return 'AP2';
   }
   return 'AGENTSBLOOM_REST';
@@ -1109,4 +2339,14 @@ export function verifyAP2Mandates(headers = {}, body = {}, publicKeyOrOptions =
 }
 
 export { createAp2Mandate, didKeyFromEd25519PublicKey, ed25519PublicKeyFromDidKey, resetAp2ReplayCache };
+export { canonicalCartHash, stableStringify };
+export { createOutcomeReporter, stripeEventToOutcome };
+// `normalizeAudience` has been declared in index.d.ts all along but was never
+// re-exported here, so a TypeScript consumer that imported it got `undefined`
+// at runtime. Merchants need it to compute the audience string their configured
+// `baseUrl` will be compared against.
+export { normalizeAudience };
+// The accepted algorithm sets, so a merchant (or a port of this SDK) can assert
+// against the same lists the verifier enforces instead of hardcoding them.
+export { SUPPORTED_SIGNATURE_ALGORITHMS, SUPPORTED_MANDATE_ALGORITHMS };