@astrasyncai/verification-gateway 5.21.1 → 5.22.0

package/dist/index.d.mts

@@ -155,9 +155,11 @@ declare function extractPlatformHeaders(sanitized: Record<string, string> | unde
  * `connection` keys the edge adapters populate natively, so SDK-only
  * deployments still get IP / geo / TLS attribution. Precedence per key:
  *
- * - `ip`: `cf-connecting-ip` > `fastly-client-ip` > `true-client-ip` >
- *   `x-real-ip` > `cloudfront-viewer-address` (port stripped) > leftmost
- *   `x-forwarded-for`
+ * - `ip`: `cf-connecting-ip` > `fastly-client-ip` > `incap-client-ip`
+ *   (Imperva) > `true-client-ip` (Akamai et al.) > `x-real-ip` >
+ *   `cloudfront-viewer-address` (port stripped) > leftmost `x-forwarded-for`
+ * - Akamai `x-akamai-edgescape` fills country / region / city / lat / long /
+ *   timeZone / asn / continent where no header above supplied them
  * - `country`: `cf-ipcountry` > `x-vercel-ip-country` >
  *   `cloudfront-viewer-country` > `fastly-geo-country`
  * - `region` / `city` / `timeZone`: Vercel then CloudFront viewer headers
@@ -5322,7 +5324,7 @@ declare function _resetEdgeConfigCache(): void;
  * Pure regex — no Node built-ins, edge-safe. Detection is regex-only for
  * v2.9 — TLS fingerprinting / behavioural signatures are deferred.
  */
-type PlatformAgentVendor = 'claude' | 'chatgpt' | 'gemini' | 'cursor' | 'goose' | 'perplexity' | 'chatgpt-atlas' | 'perplexity-comet' | 'astrasync-bridge' | 'astrasync-sdk' | 'unknown';
+type PlatformAgentVendor = 'claude' | 'chatgpt' | 'gemini' | 'cursor' | 'goose' | 'perplexity' | 'grok' | 'meta-ai' | 'chatgpt-atlas' | 'perplexity-comet' | 'astrasync-bridge' | 'astrasync-sdk' | 'unknown';
 interface PlatformFingerprint {
     vendor: PlatformAgentVendor;
     /** A stable identifier used as the orphan-agent dedup key. */
@@ -5358,6 +5360,13 @@ interface PlatformDetectionInput {
      * provider — registry validation rejects ASN-only signatures.
      */
     asn?: string;
+    /**
+     * Round 31 — bot labels a customer's WAF attached to the request (AWS Bot
+     * Control `…:bot:name:x`, Akamai Bot Manager bot name, Cloudflare
+     * verified-bot category, Imperva client classification). Present only on
+     * rows read from WAF security logs. Matched against `wafLabelPatterns`.
+     */
+    wafLabels?: string[];
 }
 /**
  * A signature definition, generic over the vendor key. The seed constant
@@ -5386,6 +5395,8 @@ interface PlatformSignatureDef<V extends string = string> {
     ja4Patterns?: RegExp[];
     /** Exact ASN strings this signature matches (never regex). */
     asnList?: string[];
+    /** Patterns tested against each WAF bot label (round 31; see PlatformDetectionInput.wafLabels). */
+    wafLabelPatterns?: RegExp[];
 }
 /**
  * A fingerprint whose vendor may be a dynamically-promoted (non-seed) key.
@@ -5402,6 +5413,16 @@ interface DynamicPlatformFingerprint {
  * Patterns are intentionally permissive (case-insensitive substring match) since
  * platform UA strings drift between versions. False positives are tolerable —
  * the orphan record is informational, not enforcement.
+ *
+ * Round 31: `wafLabelPatterns` attribute rows read from a customer's WAF
+ * security logs by the bot name THEIR WAF assigned; they never match inline
+ * traffic (no labels there).
+ *
+ * NOT detectable here, by design (Oct 2026): Meta's Muse and OpenAI's Dots
+ * publish no user agent and browse through real Chromium sessions that are
+ * indistinguishable from a person's. There is no signature to find — don't
+ * chase one. Verified identity (an ASTRA-id the agent presents) is the only
+ * durable way to know such an agent is there; that is the product's point.
  */
 declare const PLATFORM_AGENT_SIGNATURES: ReadonlyArray<PlatformSignatureDef<PlatformAgentVendor>>;
 /**
@@ -5466,7 +5487,7 @@ declare function detectRuntime(userAgent: string | undefined | null): string | u
  * silently (never throwing), so this is a no-op there — which is correct:
  * in a browser the page's real UA is the honest identity.
  */
-declare const SDK_USER_AGENT = "astrasync-sdk/5.21.1";
+declare const SDK_USER_AGENT = "astrasync-sdk/5.22.0";
 declare const sdkFetch: typeof fetch;
 
 interface LocalPolicy {
@@ -5584,7 +5605,7 @@ declare function parseYaml(yamlContent: string): ParseResult;
  * is fine — bumping both in the release-ceremony commit keeps them
  * lockstep.
  */
-declare const SDK_VERSION = "5.21.1";
+declare const SDK_VERSION = "5.22.0";
 
 /**
  * 5.15.0 — the `UCP-Agent` request header (UCP 2026-08-25): an RFC 8941

package/dist/index.d.ts

@@ -155,9 +155,11 @@ declare function extractPlatformHeaders(sanitized: Record<string, string> | unde
  * `connection` keys the edge adapters populate natively, so SDK-only
  * deployments still get IP / geo / TLS attribution. Precedence per key:
  *
- * - `ip`: `cf-connecting-ip` > `fastly-client-ip` > `true-client-ip` >
- *   `x-real-ip` > `cloudfront-viewer-address` (port stripped) > leftmost
- *   `x-forwarded-for`
+ * - `ip`: `cf-connecting-ip` > `fastly-client-ip` > `incap-client-ip`
+ *   (Imperva) > `true-client-ip` (Akamai et al.) > `x-real-ip` >
+ *   `cloudfront-viewer-address` (port stripped) > leftmost `x-forwarded-for`
+ * - Akamai `x-akamai-edgescape` fills country / region / city / lat / long /
+ *   timeZone / asn / continent where no header above supplied them
  * - `country`: `cf-ipcountry` > `x-vercel-ip-country` >
  *   `cloudfront-viewer-country` > `fastly-geo-country`
  * - `region` / `city` / `timeZone`: Vercel then CloudFront viewer headers
@@ -5322,7 +5324,7 @@ declare function _resetEdgeConfigCache(): void;
  * Pure regex — no Node built-ins, edge-safe. Detection is regex-only for
  * v2.9 — TLS fingerprinting / behavioural signatures are deferred.
  */
-type PlatformAgentVendor = 'claude' | 'chatgpt' | 'gemini' | 'cursor' | 'goose' | 'perplexity' | 'chatgpt-atlas' | 'perplexity-comet' | 'astrasync-bridge' | 'astrasync-sdk' | 'unknown';
+type PlatformAgentVendor = 'claude' | 'chatgpt' | 'gemini' | 'cursor' | 'goose' | 'perplexity' | 'grok' | 'meta-ai' | 'chatgpt-atlas' | 'perplexity-comet' | 'astrasync-bridge' | 'astrasync-sdk' | 'unknown';
 interface PlatformFingerprint {
     vendor: PlatformAgentVendor;
     /** A stable identifier used as the orphan-agent dedup key. */
@@ -5358,6 +5360,13 @@ interface PlatformDetectionInput {
      * provider — registry validation rejects ASN-only signatures.
      */
     asn?: string;
+    /**
+     * Round 31 — bot labels a customer's WAF attached to the request (AWS Bot
+     * Control `…:bot:name:x`, Akamai Bot Manager bot name, Cloudflare
+     * verified-bot category, Imperva client classification). Present only on
+     * rows read from WAF security logs. Matched against `wafLabelPatterns`.
+     */
+    wafLabels?: string[];
 }
 /**
  * A signature definition, generic over the vendor key. The seed constant
@@ -5386,6 +5395,8 @@ interface PlatformSignatureDef<V extends string = string> {
     ja4Patterns?: RegExp[];
     /** Exact ASN strings this signature matches (never regex). */
     asnList?: string[];
+    /** Patterns tested against each WAF bot label (round 31; see PlatformDetectionInput.wafLabels). */
+    wafLabelPatterns?: RegExp[];
 }
 /**
  * A fingerprint whose vendor may be a dynamically-promoted (non-seed) key.
@@ -5402,6 +5413,16 @@ interface DynamicPlatformFingerprint {
  * Patterns are intentionally permissive (case-insensitive substring match) since
  * platform UA strings drift between versions. False positives are tolerable —
  * the orphan record is informational, not enforcement.
+ *
+ * Round 31: `wafLabelPatterns` attribute rows read from a customer's WAF
+ * security logs by the bot name THEIR WAF assigned; they never match inline
+ * traffic (no labels there).
+ *
+ * NOT detectable here, by design (Oct 2026): Meta's Muse and OpenAI's Dots
+ * publish no user agent and browse through real Chromium sessions that are
+ * indistinguishable from a person's. There is no signature to find — don't
+ * chase one. Verified identity (an ASTRA-id the agent presents) is the only
+ * durable way to know such an agent is there; that is the product's point.
  */
 declare const PLATFORM_AGENT_SIGNATURES: ReadonlyArray<PlatformSignatureDef<PlatformAgentVendor>>;
 /**
@@ -5466,7 +5487,7 @@ declare function detectRuntime(userAgent: string | undefined | null): string | u
  * silently (never throwing), so this is a no-op there — which is correct:
  * in a browser the page's real UA is the honest identity.
  */
-declare const SDK_USER_AGENT = "astrasync-sdk/5.21.1";
+declare const SDK_USER_AGENT = "astrasync-sdk/5.22.0";
 declare const sdkFetch: typeof fetch;
 
 interface LocalPolicy {
@@ -5584,7 +5605,7 @@ declare function parseYaml(yamlContent: string): ParseResult;
  * is fine — bumping both in the release-ceremony commit keeps them
  * lockstep.
  */
-declare const SDK_VERSION = "5.21.1";
+declare const SDK_VERSION = "5.22.0";
 
 /**
  * 5.15.0 — the `UCP-Agent` request header (UCP 2026-08-25): an RFC 8941

package/dist/index.js

@@ -229,7 +229,7 @@ function getTrustLevel(score) {
 }
 
 // src/version.ts
-var SDK_VERSION = "5.21.1";
+var SDK_VERSION = "5.22.0";
 
 // src/http.ts
 var SDK_USER_AGENT = `astrasync-sdk/${SDK_VERSION}`;
@@ -1404,7 +1404,11 @@ var PLATFORM_HEADER_NAMES = /* @__PURE__ */ new Set([
   "x-goog-api-client",
   "user-agent",
   "x-agent-card-url",
-  "x-agent-provider"
+  "x-agent-provider",
+  // Round 31 — Web Bot Auth's Signature-Agent names the signing agent's
+  // directory host (a public URL, never a secret). It attributes a signed
+  // agent even when its UA is stock Chrome.
+  "signature-agent"
 ]);
 var PLATFORM_HEADER_PREFIXES = [
   "x-goog-",
@@ -1535,7 +1539,12 @@ function extractPlatformHeaders(sanitized) {
   return out;
 }
 var CONNECTION_HEADER_SOURCES = [
-  ["ip", ["cf-connecting-ip", "fastly-client-ip", "true-client-ip", "x-real-ip"]],
+  // Round 31: `incap-client-ip` = Imperva Cloud WAF; `true-client-ip` is
+  // also Akamai's client-IP header when the property enables it.
+  [
+    "ip",
+    ["cf-connecting-ip", "fastly-client-ip", "incap-client-ip", "true-client-ip", "x-real-ip"]
+  ],
   [
     "country",
     ["cf-ipcountry", "x-vercel-ip-country", "cloudfront-viewer-country", "fastly-geo-country"]
@@ -1586,6 +1595,28 @@ function deriveConnectionFromHeaders(headers) {
     if (portMatch) connection.sourcePort = portMatch[1];
     if (!connection.ip && addr) connection.ip = addr.replace(/:\d+$/, "");
   }
+  {
+    const edgescape = (lower["x-akamai-edgescape"] ?? lower["akamai-edgescape"])?.trim();
+    if (edgescape) {
+      const fields = /* @__PURE__ */ new Map();
+      for (const pair of edgescape.split(",")) {
+        const i = pair.indexOf("=");
+        if (i > 0) fields.set(pair.slice(0, i).trim().toLowerCase(), pair.slice(i + 1).trim());
+      }
+      const fill = (key, field) => {
+        const v = fields.get(field);
+        if (v && !connection[key]) connection[key] = v.slice(0, MAX_CONNECTION_VALUE_CHARS);
+      };
+      fill("country", "country_code");
+      fill("region", "region_code");
+      fill("city", "city");
+      fill("latitude", "lat");
+      fill("longitude", "long");
+      fill("timeZone", "timezone");
+      fill("asn", "asnum");
+      fill("continent", "continent");
+    }
+  }
   if (!connection.ip) {
     const xff = lower["x-forwarded-for"];
     const client = xff?.split(",")[0]?.trim();
@@ -2284,7 +2315,8 @@ var PLATFORM_AGENT_SIGNATURES = [
     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]
+    headerPatterns: [/^anthropic-version/i, /^anthropic-beta/i, /^x-anthropic-/i],
+    wafLabelPatterns: [/\bclaude/i, /\banthropic/i]
   },
   {
     vendor: "chatgpt",
@@ -2295,7 +2327,14 @@ var PLATFORM_AGENT_SIGNATURES = [
     uaPatterns: [/chatgpt/i, /openai/i, /gpt-?\d/i, /\bGPTBot\b/i, /\bOAI-SearchBot\b/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]
+    headerPatterns: [
+      /^openai-organization/i,
+      /^openai-project/i,
+      /^openai-version/i,
+      // ChatGPT agent signs with Web Bot Auth under this directory host.
+      /^signature-agent: "?https:\/\/chatgpt\.com/i
+    ],
+    wafLabelPatterns: [/\bgptbot\b/i, /\bchatgpt/i, /\boai-searchbot\b/i, /\bopenai/i]
   },
   {
     vendor: "gemini",
@@ -2316,7 +2355,8 @@ var PLATFORM_AGENT_SIGNATURES = [
     ],
     agentCardPatterns: [/gemini\.google\.com/i, /ai\.google\.dev/i],
     apiKeyFormatPatterns: [/^aiza/i],
-    headerPatterns: [/^x-goog-user-project/i, /^x-goog-api-client/i]
+    headerPatterns: [/^x-goog-user-project/i, /^x-goog-api-client/i],
+    wafLabelPatterns: [/\bgoogle-extended\b/i, /\bgoogleother\b/i, /\bgemini/i]
   },
   {
     vendor: "cursor",
@@ -2335,7 +2375,31 @@ var PLATFORM_AGENT_SIGNATURES = [
     displayName: "Perplexity",
     uaPatterns: [/perplexity/i],
     agentCardPatterns: [/perplexity\.ai/i],
-    apiKeyFormatPatterns: [/^pplx-/i]
+    apiKeyFormatPatterns: [/^pplx-/i],
+    wafLabelPatterns: [/\bperplexity/i]
+  },
+  // Round 30.1: xAI's documented crawlers (GrokBot/1.0, xAI-Grok/1.0,
+  // Grok-DeepSearch/1.0). Anchored, versioned tokens — never in a stock UA.
+  {
+    vendor: "grok",
+    displayName: "xAI Grok",
+    uaPatterns: [/\bGrokBot\//i, /\bxAI-Grok\//i, /\bGrok-DeepSearch\//i],
+    agentCardPatterns: [/\bx\.ai\b/i, /grok\.com/i],
+    apiKeyFormatPatterns: [/^xai-/i],
+    wafLabelPatterns: [/\bgrok/i, /\bxai\b/i]
+  },
+  // Round 30.1: Meta AI's index and fetch crawlers. facebookexternalhit
+  // (link previews) is deliberately NOT here — it stays a generic crawler.
+  {
+    vendor: "meta-ai",
+    displayName: "Meta AI",
+    uaPatterns: [/\bMeta-WebIndexer\b/i, /\bMeta-ExternalFetcher\b/i],
+    agentCardPatterns: [/meta\.ai/i],
+    wafLabelPatterns: [
+      /\bmeta-webindexer\b/i,
+      /\bmeta-externalfetcher\b/i,
+      /\bmeta-externalagent\b/i
+    ]
   },
   // Agentic browsers — versioned-token patterns ONLY (a stock Chrome UA must
   // never match). Distinct vendor keys (not 'chatgpt'/'perplexity'): the
@@ -2383,6 +2447,7 @@ function matchPlatformSignature(signatures, input) {
   const apiKeyFormat = input.apiKeyFormat ?? "";
   const ja4 = input.ja4 ?? "";
   const asn = input.asn ?? "";
+  const wafLabels = input.wafLabels ?? [];
   const headerLines = [];
   if (input.platformHeaders) {
     for (const [name, value] of Object.entries(input.platformHeaders)) {
@@ -2396,7 +2461,8 @@ function matchPlatformSignature(signatures, input) {
     const headerMatch = headerLines.length > 0 && sig.headerPatterns?.some((p) => headerLines.some((line) => p.test(line)));
     const ja4Match = ja4.length > 0 && sig.ja4Patterns?.some((p) => p.test(ja4));
     const asnMatch = asn.length > 0 && sig.asnList?.includes(asn);
-    if (uaMatch || cardMatch || keyMatch || headerMatch || ja4Match || asnMatch) {
+    const wafMatch = wafLabels.length > 0 && sig.wafLabelPatterns?.some((p) => wafLabels.some((label) => p.test(label)));
+    if (uaMatch || cardMatch || keyMatch || headerMatch || ja4Match || asnMatch || wafMatch) {
       const uaBase = ua.split(/[\s/]/)[0]?.toLowerCase() ?? "";
       const cardHost = (() => {
         try {
@@ -2405,7 +2471,7 @@ function matchPlatformSignature(signatures, input) {
           return "";
         }
       })();
-      const keyBasis = uaBase || cardHost || apiKeyFormat || ja4 || asn && `asn${asn}` || "unknown";
+      const keyBasis = uaBase || cardHost || apiKeyFormat || ja4 || asn && `asn${asn}` || wafMatch && `waf:${wafLabels[0]?.toLowerCase()}` || "unknown";
       return {
         vendor: sig.vendor,
         fingerprintKey: `${sig.vendor}:${keyBasis}`,