@astrasyncai/verification-gateway 4.0.0 → 4.1.0

package/dist/index.js

@@ -36,6 +36,7 @@ __export(src_exports, {
   AstraSync: () => AstraSync,
   AstraSyncError: () => AstraSyncError,
   AuthenticationError: () => AuthenticationError,
+  CAPTURE_SCHEMA_VERSION: () => CAPTURE_SCHEMA_VERSION,
   ChallengeHandler: () => ChallengeHandler,
   DEFAULT_EDGE_CONFIG: () => DEFAULT_EDGE_CONFIG,
   DEFAULT_TRUST_THRESHOLDS: () => DEFAULT_TRUST_THRESHOLDS,
@@ -54,9 +55,11 @@ __export(src_exports, {
   authorizeSettlement: () => authorizeSettlement,
   awaitStepUpApproval: () => awaitStepUpApproval,
   buildGuidance: () => buildGuidance,
+  buildSdkObservedMetadata: () => buildSdkObservedMetadata,
   clearCache: () => clearCache,
   createMcpMiddleware: () => createMcpMiddleware,
   degradeToObserve: () => degradeToObserve,
+  deriveConnectionFromHeaders: () => deriveConnectionFromHeaders,
   detectPlatformFingerprint: () => detectPlatformFingerprint,
   determineAccessLevel: () => determineAccessLevel,
   express: () => express_exports,
@@ -214,7 +217,7 @@ function getCapabilities(accessLevel) {
 }
 
 // src/version.ts
-var SDK_VERSION = "4.0.0";
+var SDK_VERSION = "4.1.0";
 
 // src/well-known.ts
 var CACHE_TTL_MS = 60 * 60 * 1e3;
@@ -1212,6 +1215,7 @@ function performCounterpartyPreCheck(routeConfig, astraCreds, purpose) {
 }
 
 // src/metadata-capture.ts
+var CAPTURE_SCHEMA_VERSION = 1;
 var SECRET_HEADER_NAMES = /* @__PURE__ */ new Set([
   "cookie",
   "set-cookie",
@@ -1356,6 +1360,373 @@ function extractPlatformHeaders(sanitized) {
   }
   return out;
 }
+var CONNECTION_HEADER_SOURCES = [
+  ["ip", ["cf-connecting-ip", "fastly-client-ip", "true-client-ip", "x-real-ip"]],
+  [
+    "country",
+    ["cf-ipcountry", "x-vercel-ip-country", "cloudfront-viewer-country", "fastly-geo-country"]
+  ],
+  ["region", ["x-vercel-ip-country-region", "cloudfront-viewer-country-region"]],
+  ["city", ["x-vercel-ip-city", "cloudfront-viewer-city"]],
+  ["asn", ["cloudfront-viewer-asn"]],
+  ["tlsVersion", ["cloudfront-viewer-tls"]],
+  ["httpVersion", ["cloudfront-viewer-http-version"]],
+  // TLS fingerprints can only be computed where TLS terminates. When a CDN
+  // terminates TLS in front of the merchant, its fingerprint headers ARE the
+  // connection-layer truth — normalising them here is the permanent design.
+  ["tlsFingerprint", ["cf-ja3-hash"]],
+  ["ja4", ["cf-ja4"]]
+];
+function deriveConnectionFromHeaders(headers) {
+  if (!headers) return void 0;
+  const lower = {};
+  for (const name of Object.keys(headers)) {
+    const value = headers[name];
+    if (typeof value === "string" && value.length > 0) lower[name.toLowerCase()] = value;
+  }
+  const connection = {};
+  for (const [key, sources] of CONNECTION_HEADER_SOURCES) {
+    for (const source of sources) {
+      const value = lower[source]?.trim();
+      if (value) {
+        connection[key] = value;
+        break;
+      }
+    }
+  }
+  if (!connection.ip) {
+    const xff = lower["x-forwarded-for"];
+    const client = xff?.split(",")[0]?.trim();
+    if (client) connection.ip = client;
+  }
+  return Object.keys(connection).length > 0 ? connection : void 0;
+}
+function buildSdkObservedMetadata(rawHeaders) {
+  const { headers, apiKeyFormat, platformHeaders } = sanitizeHeaders(rawHeaders);
+  const flat = {};
+  if (rawHeaders) {
+    for (const name of Object.keys(rawHeaders)) {
+      const value = rawHeaders[name];
+      if (value === void 0) continue;
+      flat[name.toLowerCase()] = Array.isArray(value) ? value.join(", ") : String(value);
+    }
+  }
+  const connection = deriveConnectionFromHeaders(flat);
+  return {
+    headers,
+    ...apiKeyFormat && { apiKeyFormat },
+    ...platformHeaders && { platformHeaders },
+    ...connection && { connection },
+    schemaVersion: CAPTURE_SCHEMA_VERSION
+  };
+}
+
+// src/edge-config.ts
+var DEFAULT_EDGE_CONFIG = Object.freeze({
+  version: 1,
+  mode: "observe",
+  depth: "classify",
+  pathRules: [],
+  sampling: Object.freeze({ anonymousBeaconRate: 0.1 }),
+  failurePosture: "open"
+});
+var EDGE_MODES = ["observe", "enforce"];
+var EDGE_DEPTHS = ["classify", "authenticate", "authorize"];
+function isEdgeConfig(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  if (v.version !== 1) return false;
+  if (!EDGE_MODES.includes(v.mode)) return false;
+  if (!EDGE_DEPTHS.includes(v.depth)) return false;
+  if (!Array.isArray(v.pathRules)) return false;
+  for (const rule of v.pathRules) {
+    if (typeof rule !== "object" || rule === null) return false;
+    const r = rule;
+    if (typeof r.pattern !== "string" || r.pattern.length === 0) return false;
+    if (r.mode !== void 0 && !EDGE_MODES.includes(r.mode)) return false;
+    if (r.depth !== void 0 && !EDGE_DEPTHS.includes(r.depth)) return false;
+  }
+  const sampling = v.sampling;
+  if (typeof sampling !== "object" || sampling === null || typeof sampling.anonymousBeaconRate !== "number" || sampling.anonymousBeaconRate < 0 || sampling.anonymousBeaconRate > 1) {
+    return false;
+  }
+  return v.failurePosture === "open";
+}
+async function fetchEdgeConfig(config, counterpartyId, opts) {
+  if (!counterpartyId) return null;
+  const headers = { Accept: "application/json" };
+  if (config.apiKey) {
+    headers["Authorization"] = `Bearer ${config.apiKey}`;
+    headers["X-API-Key"] = config.apiKey;
+  }
+  if (opts?.etag) headers["If-None-Match"] = opts.etag;
+  try {
+    const response = await fetch(
+      `${config.apiBaseUrl}/endpoints/${encodeURIComponent(counterpartyId)}/edge-config`,
+      { method: "GET", headers, signal: AbortSignal.timeout(opts?.timeoutMs ?? 5e3) }
+    );
+    if (response.status === 304) return { notModified: true };
+    if (!response.ok) return null;
+    const body = await response.json();
+    const edgeConfig = body.data?.edgeConfig;
+    if (!isEdgeConfig(edgeConfig)) return null;
+    return { edgeConfig, etag: response.headers.get("etag") ?? void 0 };
+  } catch {
+    return null;
+  }
+}
+var DEFAULT_TTL_MS = 60 * 1e3;
+var DEFAULT_MAX_STALE_MS = 24 * 60 * 60 * 1e3;
+var cache2 = /* @__PURE__ */ new Map();
+var inflight2 = /* @__PURE__ */ new Map();
+function cacheKey(apiBaseUrl, counterpartyId) {
+  return `${apiBaseUrl}|${counterpartyId}`;
+}
+function degradeToObserve(config) {
+  if (config.mode !== "enforce" && !config.pathRules.some((r) => r.mode === "enforce")) {
+    return config;
+  }
+  return {
+    ...config,
+    mode: "observe",
+    pathRules: config.pathRules.map((r) => r.mode === "enforce" ? { ...r, mode: "observe" } : r)
+  };
+}
+async function revalidate(config, counterpartyId) {
+  const key = cacheKey(config.apiBaseUrl, counterpartyId);
+  const existing = inflight2.get(key);
+  if (existing) return existing;
+  const promise = fetchEdgeConfig(config, counterpartyId, { etag: cache2.get(key)?.etag }).then((result) => {
+    if (result === null) return;
+    const now = Date.now();
+    if ("notModified" in result) {
+      const entry = cache2.get(key);
+      if (entry) entry.lastSuccessAt = now;
+      return;
+    }
+    cache2.set(key, { config: result.edgeConfig, etag: result.etag, lastSuccessAt: now });
+  }).finally(() => {
+    inflight2.delete(key);
+  });
+  inflight2.set(key, promise);
+  return promise;
+}
+async function getEdgeConfig(config, counterpartyId, opts) {
+  const ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
+  const maxStaleMs = opts?.maxStaleMs ?? DEFAULT_MAX_STALE_MS;
+  const key = cacheKey(config.apiBaseUrl, counterpartyId);
+  const entry = cache2.get(key);
+  if (entry) {
+    const age = Date.now() - entry.lastSuccessAt;
+    if (age > ttlMs) {
+      revalidate(config, counterpartyId).catch(() => {
+      });
+    }
+    return age > maxStaleMs ? degradeToObserve(entry.config) : entry.config;
+  }
+  await revalidate(config, counterpartyId).catch(() => {
+  });
+  return cache2.get(key)?.config ?? DEFAULT_EDGE_CONFIG;
+}
+function matchEdgePathRule(rules, path) {
+  for (const rule of rules) {
+    if (globToRegExp(rule.pattern).test(path)) return rule;
+  }
+  return void 0;
+}
+function globToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`, "i");
+}
+function _resetEdgeConfigCache() {
+  cache2.clear();
+  inflight2.clear();
+}
+
+// src/platform-signatures.ts
+var PLATFORM_AGENT_SIGNATURES = [
+  {
+    vendor: "claude",
+    displayName: "Anthropic Claude",
+    uaPatterns: [/claude/i, /anthropic/i],
+    agentCardPatterns: [/anthropic\.com/i, /claude\.ai/i],
+    apiKeyFormatPatterns: [/^sk-ant/i],
+    headerPatterns: [/^anthropic-version/i, /^anthropic-beta/i, /^x-anthropic-/i]
+  },
+  {
+    vendor: "chatgpt",
+    displayName: "OpenAI ChatGPT",
+    uaPatterns: [/chatgpt/i, /openai/i, /gpt-?\d/i],
+    agentCardPatterns: [/openai\.com/i, /chatgpt\.com/i],
+    apiKeyFormatPatterns: [/^sk-proj/i, /^sk-svcacct/i],
+    headerPatterns: [/^openai-organization/i, /^openai-project/i, /^openai-version/i]
+  },
+  {
+    vendor: "gemini",
+    displayName: "Google Gemini",
+    uaPatterns: [/gemini/i, /google-gemini/i, /bard/i],
+    agentCardPatterns: [/gemini\.google\.com/i, /ai\.google\.dev/i],
+    apiKeyFormatPatterns: [/^aiza/i],
+    headerPatterns: [/^x-goog-user-project/i, /^x-goog-api-client/i]
+  },
+  {
+    vendor: "cursor",
+    displayName: "Cursor",
+    uaPatterns: [/cursor/i],
+    agentCardPatterns: [/cursor\.sh/i, /cursor\.com/i]
+  },
+  {
+    vendor: "goose",
+    displayName: "Block Goose",
+    uaPatterns: [/goose/i, /block-goose/i],
+    agentCardPatterns: [/block\.xyz\/goose/i, /goose\.tools/i]
+  },
+  {
+    vendor: "perplexity",
+    displayName: "Perplexity",
+    uaPatterns: [/perplexity/i],
+    agentCardPatterns: [/perplexity\.ai/i],
+    apiKeyFormatPatterns: [/^pplx-/i]
+  }
+];
+function matchPlatformSignature(signatures, input) {
+  const ua = input.userAgent ?? "";
+  const cardUrl = input.agentCardUrl ?? "";
+  const apiKeyFormat = input.apiKeyFormat ?? "";
+  const headerLines = [];
+  if (input.platformHeaders) {
+    for (const [name, value] of Object.entries(input.platformHeaders)) {
+      headerLines.push(name, `${name}: ${value}`);
+    }
+  }
+  for (const sig of signatures) {
+    const uaMatch = sig.uaPatterns?.some((p) => p.test(ua));
+    const cardMatch = sig.agentCardPatterns?.some((p) => p.test(cardUrl));
+    const keyMatch = apiKeyFormat.length > 0 && sig.apiKeyFormatPatterns?.some((p) => p.test(apiKeyFormat));
+    const headerMatch = headerLines.length > 0 && sig.headerPatterns?.some((p) => headerLines.some((line) => p.test(line)));
+    if (uaMatch || cardMatch || keyMatch || headerMatch) {
+      const uaBase = ua.split(/[\s/]/)[0]?.toLowerCase() ?? "";
+      const cardHost = (() => {
+        try {
+          return cardUrl ? new URL(cardUrl).host : "";
+        } catch {
+          return "";
+        }
+      })();
+      const keyBasis = uaBase || cardHost || apiKeyFormat || "unknown";
+      return {
+        vendor: sig.vendor,
+        fingerprintKey: `${sig.vendor}:${keyBasis}`,
+        displayName: sig.displayName
+      };
+    }
+  }
+  return void 0;
+}
+function detectPlatformFingerprint(input) {
+  return matchPlatformSignature(PLATFORM_AGENT_SIGNATURES, input);
+}
+
+// src/edge-core/classify.ts
+var STATIC_EXTENSIONS = /\.(css|js|mjs|map|png|jpe?g|gif|webp|avif|svg|ico|woff2?|ttf|otf|eot|mp4|webm|pdf|txt|xml)$/i;
+var BOT_UA_PATTERN = /curl|wget|python-requests|python-urllib|node-fetch|axios|got|okhttp|go-http-client|libwww|httpie|java\/|ruby|php|scrapy|headless|phantomjs|selenium|playwright|puppeteer|bot|crawler|spider|slurp/i;
+var BROWSER_UA_PATTERN = /mozilla\/\d/i;
+var _patterns = { STATIC_EXTENSIONS, BOT_UA_PATTERN, BROWSER_UA_PATTERN };
+
+// src/edge-core/events.ts
+function sampled(rate, random = Math.random) {
+  if (rate <= 0) return false;
+  if (rate >= 1) return true;
+  return random() < rate;
+}
+
+// src/adapters/anonymous-beacon.ts
+function readHeader(raw, name) {
+  const value = raw[name];
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value[0];
+  return void 0;
+}
+function classifyPassThroughTraffic(path, rawHeaders) {
+  if (_patterns.STATIC_EXTENSIONS.test(path)) return { kind: "never" };
+  const credentials = extractCredentials(rawHeaders, {});
+  if (credentials.astraId || credentials.apiKey || credentials.jwt) {
+    return { kind: "never" };
+  }
+  const userAgent = readHeader(rawHeaders, "user-agent") ?? "";
+  const { apiKeyFormat, platformHeaders } = sanitizeHeaders(rawHeaders);
+  const fingerprint = detectPlatformFingerprint({ userAgent, apiKeyFormat, platformHeaders });
+  if (fingerprint) {
+    return {
+      kind: "platform",
+      protocol: "platform-ua",
+      evidence: { vendor: fingerprint.vendor, userAgent: userAgent || "(none)" }
+    };
+  }
+  if (!userAgent || _patterns.BOT_UA_PATTERN.test(userAgent) || !_patterns.BROWSER_UA_PATTERN.test(userAgent)) {
+    return {
+      kind: "anonymous-bot",
+      protocol: "ua-heuristic",
+      evidence: { userAgent: userAgent || "(none)" }
+    };
+  }
+  if (!readHeader(rawHeaders, "sec-fetch-mode") && !readHeader(rawHeaders, "accept-language")) {
+    return {
+      kind: "anonymous-bot",
+      protocol: "ua-heuristic",
+      evidence: { userAgent, spoofedBrowser: true }
+    };
+  }
+  return { kind: "never" };
+}
+function createAnonymousBeacon(config, options) {
+  const counterpartyId = config.counterpartyId;
+  if (!counterpartyId) return () => {
+  };
+  const random = options?.random ?? Math.random;
+  let edgeConfig;
+  let refreshing = false;
+  const refreshConfig = () => {
+    if (refreshing) return;
+    refreshing = true;
+    getEdgeConfig(config, counterpartyId).then((cfg) => {
+      edgeConfig = cfg;
+    }).catch(() => {
+    }).finally(() => {
+      refreshing = false;
+    });
+  };
+  refreshConfig();
+  return (input) => {
+    try {
+      refreshConfig();
+      const cfg = edgeConfig;
+      if (!cfg) return;
+      const traffic = classifyPassThroughTraffic(input.requestPath, input.rawHeaders);
+      if (traffic.kind === "never") return;
+      if (traffic.kind === "anonymous-bot" && !sampled(cfg.sampling.anonymousBeaconRate, random)) {
+        return;
+      }
+      const userAgent = readHeader(input.rawHeaders, "user-agent");
+      const xff = input.rawHeaders["x-forwarded-for"];
+      const xffStr = Array.isArray(xff) ? xff.join(", ") : xff;
+      const sourceIp = input.sourceIp ?? xffStr?.split(",")[0]?.trim();
+      reportUnregisteredAttempt(config, {
+        ...input.counterpartyUrl && { counterpartyUrl: input.counterpartyUrl },
+        counterpartyType: options?.counterpartyType ?? config.counterpartyType ?? "api",
+        ...sourceIp && { sourceIp },
+        ...userAgent && { userAgent },
+        requestPath: input.requestPath,
+        requestMethod: input.requestMethod,
+        ...traffic.protocol && { protocol: traffic.protocol },
+        ...traffic.evidence && { evidence: traffic.evidence },
+        observedMetadata: buildSdkObservedMetadata(input.rawHeaders)
+      }).catch(() => {
+      });
+    } catch {
+    }
+  };
+}
 
 // src/adapters/express.ts
 function defaultExtractCredentials(req) {
@@ -1367,7 +1738,7 @@ function defaultExtractCredentials(req) {
 function extractAstraSyncCredentials(req) {
   return extractHttpCredentials(req.headers);
 }
-function headerValue(value) {
+function headerValue2(value) {
   if (typeof value === "string") return value;
   if (Array.isArray(value)) return value[0];
   return void 0;
@@ -1375,9 +1746,9 @@ function headerValue(value) {
 function resolveRequestPdlss(req, routeConfig, customExtractPurpose, customExtractAction) {
   return resolveHttpPdlss({
     method: req.method,
-    astraPurpose: headerValue(req.headers["x-astra-purpose"]),
-    astraAction: headerValue(req.headers["x-astra-action"]),
-    legacyPurpose: headerValue(req.headers["x-purpose"] ?? req.headers["X-Purpose"]),
+    astraPurpose: headerValue2(req.headers["x-astra-purpose"]),
+    astraAction: headerValue2(req.headers["x-astra-action"]),
+    legacyPurpose: headerValue2(req.headers["x-purpose"] ?? req.headers["X-Purpose"]),
     queryPurpose: typeof req.query.purpose === "string" ? req.query.purpose : void 0,
     routePurpose: routeConfig?.purpose,
     routeAction: routeConfig?.action,
@@ -1460,6 +1831,11 @@ function defaultOnDenied(result, _req, res) {
 }
 var DEFAULT_ROUTES_REFRESH_MS = 5 * 60 * 1e3;
 function createMiddleware(options) {
+  if ("routes" in options) {
+    console.warn(
+      "[VerificationGateway] `routes` is dashboard-managed since v2.9.7; this option is ignored \u2014 configure route policy in your AstraSync dashboard."
+    );
+  }
   const {
     extractCredentials: customExtractCredentials,
     extractPurpose: customExtractPurpose,
@@ -1471,12 +1847,25 @@ function createMiddleware(options) {
     routesRefreshMs = DEFAULT_ROUTES_REFRESH_MS,
     failOnError = "open",
     caseInsensitiveRouteMatch = false,
+    anonymousBeacon = true,
     ...config
   } = options;
   if (config.apiBaseUrl) {
     prefetchWellKnown(config.apiBaseUrl).catch(() => {
     });
   }
+  const emitAnonymousBeacon = anonymousBeacon ? createAnonymousBeacon(config, { counterpartyType: config.counterpartyType ?? "api" }) : void 0;
+  const beaconPassThrough = emitAnonymousBeacon ? (req) => {
+    const xff = req.headers["x-forwarded-for"];
+    const xffStr = Array.isArray(xff) ? xff.join(", ") : xff;
+    emitAnonymousBeacon({
+      requestPath: req.path,
+      requestMethod: req.method,
+      counterpartyUrl: config.counterpartyUrl || `${req.protocol}://${req.get("host")}`,
+      sourceIp: req.ip ?? (xffStr ? xffStr.split(",")[0].trim() : void 0),
+      rawHeaders: req.headers
+    });
+  } : void 0;
   let cachedRoutes = [];
   let lastFetchAt = 0;
   let refreshing = null;
@@ -1537,6 +1926,7 @@ function createMiddleware(options) {
             cachedRoutes.length === 0 ? "no-policy" : "no-match"
           );
         }
+        beaconPassThrough?.(req);
         return next();
       }
       const wellKnownUrls = config.apiBaseUrl ? await getWellKnownUrls(config.apiBaseUrl).catch(() => void 0) : void 0;
@@ -1547,6 +1937,7 @@ function createMiddleware(options) {
           res.setHeader("X-Astra-Gateway-Mode", "unenforced");
           res.setHeader("X-Astra-Gateway-Reason", "route-none");
         }
+        beaconPassThrough?.(req);
         return next();
       }
       const pdlssPair = resolveRequestPdlss(
@@ -1639,16 +2030,10 @@ function createMiddleware(options) {
           forwardedFor: forwardedForStr,
           agentCardUrl,
           // Workstream D — capture EVERY inbound header (SDK-only merchants
-          // have no edge to do it upstream). Local string work, secrets
-          // stripped; out of the verify cache key so it doesn't defeat caching.
-          observedMetadata: (() => {
-            const { headers, apiKeyFormat, platformHeaders } = sanitizeHeaders(req.headers);
-            return {
-              headers,
-              ...apiKeyFormat && { apiKeyFormat },
-              ...platformHeaders && { platformHeaders }
-            };
-          })()
+          // have no edge to do it upstream) plus the CDN-derived connection
+          // block. Local string work, secrets stripped; out of the verify
+          // cache key so it doesn't defeat caching.
+          observedMetadata: buildSdkObservedMetadata(req.headers)
         }
       };
       let result = await verify(config, verificationRequest);
@@ -1842,7 +2227,7 @@ function resolveNextPdlss(request, routeConfig) {
     routeAction: routeConfig?.action
   });
 }
-function generateCommerceShieldHtml(result, options) {
+function generateInterstitialHtml(result, options) {
   const title = escapeHtml(options.commerceShield?.title || "AstraSync Agent Verification");
   const message = escapeHtml(
     options.commerceShield?.message || result.guidance?.message || "This site verifies AI agents before granting access. We noticed you're visiting without AstraSync credentials."
@@ -1998,13 +2383,31 @@ function generateCommerceShieldHtml(result, options) {
 }
 var DEFAULT_ROUTES_REFRESH_MS2 = 5 * 60 * 1e3;
 function createMiddleware2(options) {
+  if ("routes" in options) {
+    console.warn(
+      "[VerificationGateway/Next.js] `routes` is dashboard-managed since v2.9.7; this option is ignored \u2014 configure route policy in your AstraSync dashboard."
+    );
+  }
   const {
     skipPaths = [],
-    showCommerceShield = true,
+    showInterstitial,
+    showCommerceShield,
     enableRuntimeChallenge = true,
     routesRefreshMs = DEFAULT_ROUTES_REFRESH_MS2,
+    anonymousBeacon = true,
     ...config
   } = options;
+  const interstitialEnabled = showInterstitial ?? showCommerceShield ?? true;
+  const emitAnonymousBeacon = anonymousBeacon ? createAnonymousBeacon(config, { counterpartyType: config.counterpartyType ?? "website" }) : void 0;
+  const beaconPassThrough = emitAnonymousBeacon ? (request, pathname) => {
+    emitAnonymousBeacon({
+      requestPath: pathname,
+      requestMethod: request.method,
+      counterpartyUrl: config.counterpartyUrl || request.nextUrl.origin,
+      sourceIp: request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() || void 0,
+      rawHeaders: Object.fromEntries(request.headers.entries())
+    });
+  } : void 0;
   let cachedRoutes = [];
   let lastFetchAt = 0;
   let refreshing = null;
@@ -2046,9 +2449,11 @@ function createMiddleware2(options) {
     }
     const routeConfig = findRouteConfig2(cachedRoutes, pathname, request.method);
     if (!routeConfig) {
+      beaconPassThrough?.(request, pathname);
       return NextResponse.next();
     }
     if (routeConfig.minAccessLevel === "none") {
+      beaconPassThrough?.(request, pathname);
       return NextResponse.next();
     }
     const credentials = extractCredentialsFromNextRequest(request);
@@ -2100,8 +2505,8 @@ function createMiddleware2(options) {
           { status: 403 }
         );
       }
-      if (showCommerceShield) {
-        return new NextResponse(generateCommerceShieldHtml(preCheckResult, options), {
+      if (interstitialEnabled) {
+        return new NextResponse(generateInterstitialHtml(preCheckResult, options), {
           status: 200,
           headers: {
             "Content-Type": "text/html",
@@ -2129,17 +2534,9 @@ function createMiddleware2(options) {
         host: request.headers.get("host") || void 0,
         forwardedFor,
         agentCardUrl: request.headers.get("x-astrasync-agent-card") || void 0,
-        // Workstream D — full sanitised header capture (Web Headers → plain map).
-        observedMetadata: (() => {
-          const { headers, apiKeyFormat, platformHeaders } = sanitizeHeaders(
-            Object.fromEntries(request.headers.entries())
-          );
-          return {
-            headers,
-            ...apiKeyFormat && { apiKeyFormat },
-            ...platformHeaders && { platformHeaders }
-          };
-        })()
+        // Workstream D — full sanitised header capture + CDN-derived
+        // connection block (Web Headers → plain map).
+        observedMetadata: buildSdkObservedMetadata(Object.fromEntries(request.headers.entries()))
       }
     };
     let result = await verify(config, verificationRequest);
@@ -2194,8 +2591,8 @@ function createMiddleware2(options) {
           }
         );
       }
-      if (showCommerceShield) {
-        return new NextResponse(generateCommerceShieldHtml(result, options), {
+      if (interstitialEnabled) {
+        return new NextResponse(generateInterstitialHtml(result, options), {
           status: 200,
           headers: {
             "Content-Type": "text/html",
@@ -2283,7 +2680,7 @@ var VerificationGatewayClient = class {
   /**
    * Quick verification — checks credentials and policy in one call.
    *
-   * Round-18 G4: return shape mirrors `VerificationResult`'s identity/policy
+   * The return shape mirrors `VerificationResult`'s identity/policy
    * split. Map to HTTP status the same way: `!identityVerified` → 401,
    * `identityVerified && !policyAllowed` → 403.
    */
@@ -2713,8 +3110,8 @@ function extractX402TransactionValue(req) {
 // src/transport/rfc9421.ts
 var import_structured_headers = require("structured-headers");
 function parseRFC9421(headers) {
-  const sigInput = readHeader(headers, "signature-input");
-  const sig = readHeader(headers, "signature");
+  const sigInput = readHeader2(headers, "signature-input");
+  const sig = readHeader2(headers, "signature");
   if (!sigInput || !sig) return null;
   let inputDict;
   let sigDict;
@@ -2758,7 +3155,7 @@ function parseRFC9421(headers) {
   if (signatures.length === 0) return null;
   return { signatures };
 }
-function readHeader(headers, name) {
+function readHeader2(headers, name) {
   for (const key of Object.keys(headers)) {
     if (key.toLowerCase() === name) {
       const raw = headers[key];
@@ -3076,11 +3473,11 @@ function extractACPContext(request) {
   const purpose = mapACPRequestToPurpose(method, path);
   const sessionId = extractSessionId2(path);
   const headers = request.headers ?? {};
-  const signatureHeader = readHeader2(headers, "signature");
-  const timestampHeader = readHeader2(headers, "timestamp");
-  const idempotencyKey = readHeader2(headers, "idempotency-key");
-  const apiVersion = readHeader2(headers, "api-version");
-  const bearer = extractBearer(readHeader2(headers, "authorization"));
+  const signatureHeader = readHeader3(headers, "signature");
+  const timestampHeader = readHeader3(headers, "timestamp");
+  const idempotencyKey = readHeader3(headers, "idempotency-key");
+  const apiVersion = readHeader3(headers, "api-version");
+  const bearer = extractBearer(readHeader3(headers, "authorization"));
   const body = request.body ?? {};
   const merchantId = coerceString3(body.merchant_id ?? body.merchantId);
   const totals = Array.isArray(body.totals) ? body.totals : void 0;
@@ -3148,7 +3545,7 @@ function extractFulfillmentOption(body) {
   }
   return void 0;
 }
-function readHeader2(headers, name) {
+function readHeader3(headers, name) {
   for (const key of Object.keys(headers)) {
     if (key.toLowerCase() === name) {
       const raw = headers[key];
@@ -3942,9 +4339,9 @@ function toBuf(bytes) {
   new Uint8Array(out).set(bytes);
   return out;
 }
-function checkTimestamp(headerValue2, toleranceSec, nowFn) {
-  if (!headerValue2) return { ok: false, error: "missing Timestamp header" };
-  const ts = parseTimestamp(headerValue2);
+function checkTimestamp(headerValue3, toleranceSec, nowFn) {
+  if (!headerValue3) return { ok: false, error: "missing Timestamp header" };
+  const ts = parseTimestamp(headerValue3);
   if (ts === null) return { ok: false, error: "unparseable Timestamp header" };
   const now = nowFn ? nowFn() : Math.floor(Date.now() / 1e3);
   if (Math.abs(now - ts) > toleranceSec) {
@@ -3988,7 +4385,7 @@ async function getSubtle() {
 // src/transport/mpp.ts
 var import_mppx = require("mppx");
 function extractMPPFromRequest(request) {
-  const auth = readHeader3(request.headers, "authorization");
+  const auth = readHeader4(request.headers, "authorization");
   if (!auth || !/^\s*Payment\s+/i.test(auth)) return null;
   try {
     const credential = import_mppx.Credential.deserialize(auth);
@@ -4016,7 +4413,7 @@ function extractMPPFromResponse(response) {
       offeredMethods: methods
     };
   }
-  const receiptHeader = readHeader3(response.headers, "payment-receipt");
+  const receiptHeader = readHeader4(response.headers, "payment-receipt");
   if (receiptHeader) {
     try {
       const parsed = import_mppx.Receipt.deserialize(receiptHeader);
@@ -4036,7 +4433,7 @@ function extractMPPFromResponse(response) {
       return { kind: "error", error: { type: "invalid-receipt-encoding" } };
     }
   }
-  const contentType = readHeader3(response.headers, "content-type");
+  const contentType = readHeader4(response.headers, "content-type");
   if (contentType && /application\/problem\+json/i.test(contentType)) {
     const body = typeof response.body === "object" && response.body !== null ? response.body : {};
     return {
@@ -4059,7 +4456,7 @@ function extractMPPContext(message) {
   return extractMPPFromRequest(message);
 }
 function collectChallenges(response) {
-  const wwwAuth = readHeader3(response.headers, "www-authenticate");
+  const wwwAuth = readHeader4(response.headers, "www-authenticate");
   if (!wwwAuth) return [];
   const headers = new Headers();
   headers.set("www-authenticate", wwwAuth);
@@ -4087,7 +4484,7 @@ function summarizeChallenge(ch) {
     opaque: raw.opaque
   };
 }
-function readHeader3(headers, name) {
+function readHeader4(headers, name) {
   for (const key of Object.keys(headers)) {
     if (key.toLowerCase() === name) {
       const raw = headers[key];
@@ -4176,14 +4573,14 @@ function verifyMPP(input) {
 var import_schemas = require("@x402/core/schemas");
 var import_utils = require("@x402/core/utils");
 function extractX402FromRequest(request) {
-  const headerValue2 = readHeader4(request.headers, "x-payment");
+  const headerValue3 = readHeader5(request.headers, "x-payment");
   if (request.body && typeof request.body === "object") {
     const parsed = tryParsePayload(request.body);
     if (parsed) return buildPayloadContext(parsed, "body");
   }
-  if (headerValue2) {
+  if (headerValue3) {
     try {
-      const decoded = (0, import_utils.safeBase64Decode)(headerValue2);
+      const decoded = (0, import_utils.safeBase64Decode)(headerValue3);
       if (decoded) {
         const json = JSON.parse(decoded);
         const parsed = tryParsePayload(json);
@@ -4206,10 +4603,10 @@ function extractX402FromResponse(response) {
     const parsed = tryParseRequired(response.body);
     if (parsed) return buildRequiredContext(parsed, "body");
   }
-  const headerValue2 = readHeader4(response.headers, "x-payment-required");
-  if (headerValue2) {
+  const headerValue3 = readHeader5(response.headers, "x-payment-required");
+  if (headerValue3) {
     try {
-      const decoded = (0, import_utils.safeBase64Decode)(headerValue2);
+      const decoded = (0, import_utils.safeBase64Decode)(headerValue3);
       if (decoded) {
         const json = JSON.parse(decoded);
         const parsed = tryParseRequired(json);
@@ -4306,7 +4703,7 @@ function coerceVersion(v) {
   if (v === 1 || v === 2) return v;
   return null;
 }
-function readHeader4(headers, name) {
+function readHeader5(headers, name) {
   if (!headers) return void 0;
   for (const key of Object.keys(headers)) {
     if (key.toLowerCase() === name) {
@@ -5054,8 +5451,11 @@ function mcpToPdlss(parsed, requestPath, headerPurpose, headerAction, toolGate)
   } else if (parsed.actionFromBody && parsed.actionSourceFromBody) {
     action = parsed.actionFromBody;
     actionSource = parsed.actionSourceFromBody;
+  } else if (parsed.method === "tools/call") {
+    action = void 0;
+    actionSource = void 0;
   } else {
-    action = parsed.toolName ? parsed.method === "tools/call" ? parsed.toolName : `${parsed.method}:${parsed.toolName}` : parsed.method;
+    action = parsed.toolName ? `${parsed.method}:${parsed.toolName}` : parsed.method;
     actionSource = "transport_layer";
   }
   return { purpose, action, resource, purposeSource, actionSource };
@@ -5170,6 +5570,15 @@ function createMcpMiddleware(options) {
     prefetchWellKnown(config.apiBaseUrl).catch(() => {
     });
   }
+  if (toolGates) {
+    for (const [toolName, gate] of Object.entries(toolGates)) {
+      if (typeof gate === "string") {
+        console.warn(
+          `[VerificationGateway/MCP] toolGates['${toolName}'] uses the bare-string shorthand ('${gate}'). Gated tools need a PDLSS purpose (else PDLSS_PURPOSE_REQUIRED 400) and evaluate purpose-only without a declared action. Use the object form instead: { minAccessLevel: '${gate}', purpose: '...', action: '...' }.`
+        );
+      }
+    }
+  }
   return async (req, res, next) => {
     try {
       if (skip) return next();
@@ -5289,7 +5698,13 @@ function createMcpMiddleware(options) {
         callerMetadata: {
           sourceIp: req.ip,
           userAgent: req.headers["user-agent"],
-          host: req.headers.host
+          host: req.headers.host,
+          // Capture EVERY inbound header (parity with the express adapter —
+          // MCP-only merchants have no edge to do it upstream) plus the
+          // CDN-derived connection block. Local string work, secrets
+          // stripped; out of the verify cache key so it doesn't defeat
+          // caching.
+          observedMetadata: buildSdkObservedMetadata(req.headers)
         }
       };
       let result = await verify(config, verificationRequest);
@@ -6074,212 +6489,6 @@ async function recordDecision2(config, params) {
     blockchainTxHash: result.blockchainTxHash
   };
 }
-
-// src/edge-config.ts
-var DEFAULT_EDGE_CONFIG = Object.freeze({
-  version: 1,
-  mode: "observe",
-  depth: "classify",
-  pathRules: [],
-  sampling: Object.freeze({ anonymousBeaconRate: 0.1 }),
-  failurePosture: "open"
-});
-var EDGE_MODES = ["observe", "enforce"];
-var EDGE_DEPTHS = ["classify", "authenticate", "authorize"];
-function isEdgeConfig(value) {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value;
-  if (v.version !== 1) return false;
-  if (!EDGE_MODES.includes(v.mode)) return false;
-  if (!EDGE_DEPTHS.includes(v.depth)) return false;
-  if (!Array.isArray(v.pathRules)) return false;
-  for (const rule of v.pathRules) {
-    if (typeof rule !== "object" || rule === null) return false;
-    const r = rule;
-    if (typeof r.pattern !== "string" || r.pattern.length === 0) return false;
-    if (r.mode !== void 0 && !EDGE_MODES.includes(r.mode)) return false;
-    if (r.depth !== void 0 && !EDGE_DEPTHS.includes(r.depth)) return false;
-  }
-  const sampling = v.sampling;
-  if (typeof sampling !== "object" || sampling === null || typeof sampling.anonymousBeaconRate !== "number" || sampling.anonymousBeaconRate < 0 || sampling.anonymousBeaconRate > 1) {
-    return false;
-  }
-  return v.failurePosture === "open";
-}
-async function fetchEdgeConfig(config, counterpartyId, opts) {
-  if (!counterpartyId) return null;
-  const headers = { Accept: "application/json" };
-  if (config.apiKey) {
-    headers["Authorization"] = `Bearer ${config.apiKey}`;
-    headers["X-API-Key"] = config.apiKey;
-  }
-  if (opts?.etag) headers["If-None-Match"] = opts.etag;
-  try {
-    const response = await fetch(
-      `${config.apiBaseUrl}/endpoints/${encodeURIComponent(counterpartyId)}/edge-config`,
-      { method: "GET", headers, signal: AbortSignal.timeout(opts?.timeoutMs ?? 5e3) }
-    );
-    if (response.status === 304) return { notModified: true };
-    if (!response.ok) return null;
-    const body = await response.json();
-    const edgeConfig = body.data?.edgeConfig;
-    if (!isEdgeConfig(edgeConfig)) return null;
-    return { edgeConfig, etag: response.headers.get("etag") ?? void 0 };
-  } catch {
-    return null;
-  }
-}
-var DEFAULT_TTL_MS = 60 * 1e3;
-var DEFAULT_MAX_STALE_MS = 24 * 60 * 60 * 1e3;
-var cache2 = /* @__PURE__ */ new Map();
-var inflight2 = /* @__PURE__ */ new Map();
-function cacheKey(apiBaseUrl, counterpartyId) {
-  return `${apiBaseUrl}|${counterpartyId}`;
-}
-function degradeToObserve(config) {
-  if (config.mode !== "enforce" && !config.pathRules.some((r) => r.mode === "enforce")) {
-    return config;
-  }
-  return {
-    ...config,
-    mode: "observe",
-    pathRules: config.pathRules.map((r) => r.mode === "enforce" ? { ...r, mode: "observe" } : r)
-  };
-}
-async function revalidate(config, counterpartyId) {
-  const key = cacheKey(config.apiBaseUrl, counterpartyId);
-  const existing = inflight2.get(key);
-  if (existing) return existing;
-  const promise = fetchEdgeConfig(config, counterpartyId, { etag: cache2.get(key)?.etag }).then((result) => {
-    if (result === null) return;
-    const now = Date.now();
-    if ("notModified" in result) {
-      const entry = cache2.get(key);
-      if (entry) entry.lastSuccessAt = now;
-      return;
-    }
-    cache2.set(key, { config: result.edgeConfig, etag: result.etag, lastSuccessAt: now });
-  }).finally(() => {
-    inflight2.delete(key);
-  });
-  inflight2.set(key, promise);
-  return promise;
-}
-async function getEdgeConfig(config, counterpartyId, opts) {
-  const ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
-  const maxStaleMs = opts?.maxStaleMs ?? DEFAULT_MAX_STALE_MS;
-  const key = cacheKey(config.apiBaseUrl, counterpartyId);
-  const entry = cache2.get(key);
-  if (entry) {
-    const age = Date.now() - entry.lastSuccessAt;
-    if (age > ttlMs) {
-      revalidate(config, counterpartyId).catch(() => {
-      });
-    }
-    return age > maxStaleMs ? degradeToObserve(entry.config) : entry.config;
-  }
-  await revalidate(config, counterpartyId).catch(() => {
-  });
-  return cache2.get(key)?.config ?? DEFAULT_EDGE_CONFIG;
-}
-function matchEdgePathRule(rules, path) {
-  for (const rule of rules) {
-    if (globToRegExp(rule.pattern).test(path)) return rule;
-  }
-  return void 0;
-}
-function globToRegExp(pattern) {
-  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
-  return new RegExp(`^${escaped}$`, "i");
-}
-function _resetEdgeConfigCache() {
-  cache2.clear();
-  inflight2.clear();
-}
-
-// src/platform-signatures.ts
-var PLATFORM_AGENT_SIGNATURES = [
-  {
-    vendor: "claude",
-    displayName: "Anthropic Claude",
-    uaPatterns: [/claude/i, /anthropic/i],
-    agentCardPatterns: [/anthropic\.com/i, /claude\.ai/i],
-    apiKeyFormatPatterns: [/^sk-ant/i],
-    headerPatterns: [/^anthropic-version/i, /^anthropic-beta/i, /^x-anthropic-/i]
-  },
-  {
-    vendor: "chatgpt",
-    displayName: "OpenAI ChatGPT",
-    uaPatterns: [/chatgpt/i, /openai/i, /gpt-?\d/i],
-    agentCardPatterns: [/openai\.com/i, /chatgpt\.com/i],
-    apiKeyFormatPatterns: [/^sk-proj/i, /^sk-svcacct/i],
-    headerPatterns: [/^openai-organization/i, /^openai-project/i, /^openai-version/i]
-  },
-  {
-    vendor: "gemini",
-    displayName: "Google Gemini",
-    uaPatterns: [/gemini/i, /google-gemini/i, /bard/i],
-    agentCardPatterns: [/gemini\.google\.com/i, /ai\.google\.dev/i],
-    apiKeyFormatPatterns: [/^aiza/i],
-    headerPatterns: [/^x-goog-user-project/i, /^x-goog-api-client/i]
-  },
-  {
-    vendor: "cursor",
-    displayName: "Cursor",
-    uaPatterns: [/cursor/i],
-    agentCardPatterns: [/cursor\.sh/i, /cursor\.com/i]
-  },
-  {
-    vendor: "goose",
-    displayName: "Block Goose",
-    uaPatterns: [/goose/i, /block-goose/i],
-    agentCardPatterns: [/block\.xyz\/goose/i, /goose\.tools/i]
-  },
-  {
-    vendor: "perplexity",
-    displayName: "Perplexity",
-    uaPatterns: [/perplexity/i],
-    agentCardPatterns: [/perplexity\.ai/i],
-    apiKeyFormatPatterns: [/^pplx-/i]
-  }
-];
-function matchPlatformSignature(signatures, input) {
-  const ua = input.userAgent ?? "";
-  const cardUrl = input.agentCardUrl ?? "";
-  const apiKeyFormat = input.apiKeyFormat ?? "";
-  const headerLines = [];
-  if (input.platformHeaders) {
-    for (const [name, value] of Object.entries(input.platformHeaders)) {
-      headerLines.push(name, `${name}: ${value}`);
-    }
-  }
-  for (const sig of signatures) {
-    const uaMatch = sig.uaPatterns?.some((p) => p.test(ua));
-    const cardMatch = sig.agentCardPatterns?.some((p) => p.test(cardUrl));
-    const keyMatch = apiKeyFormat.length > 0 && sig.apiKeyFormatPatterns?.some((p) => p.test(apiKeyFormat));
-    const headerMatch = headerLines.length > 0 && sig.headerPatterns?.some((p) => headerLines.some((line) => p.test(line)));
-    if (uaMatch || cardMatch || keyMatch || headerMatch) {
-      const uaBase = ua.split(/[\s/]/)[0]?.toLowerCase() ?? "";
-      const cardHost = (() => {
-        try {
-          return cardUrl ? new URL(cardUrl).host : "";
-        } catch {
-          return "";
-        }
-      })();
-      const keyBasis = uaBase || cardHost || apiKeyFormat || "unknown";
-      return {
-        vendor: sig.vendor,
-        fingerprintKey: `${sig.vendor}:${keyBasis}`,
-        displayName: sig.displayName
-      };
-    }
-  }
-  return void 0;
-}
-function detectPlatformFingerprint(input) {
-  return matchPlatformSignature(PLATFORM_AGENT_SIGNATURES, input);
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ACCESS_LEVEL_DESCRIPTIONS,
@@ -6288,6 +6497,7 @@ function detectPlatformFingerprint(input) {
   AstraSync,
   AstraSyncError,
   AuthenticationError,
+  CAPTURE_SCHEMA_VERSION,
   ChallengeHandler,
   DEFAULT_EDGE_CONFIG,
   DEFAULT_TRUST_THRESHOLDS,
@@ -6306,9 +6516,11 @@ function detectPlatformFingerprint(input) {
   authorizeSettlement,
   awaitStepUpApproval,
   buildGuidance,
+  buildSdkObservedMetadata,
   clearCache,
   createMcpMiddleware,
   degradeToObserve,
+  deriveConnectionFromHeaders,
   detectPlatformFingerprint,
   determineAccessLevel,
   express,