@astrasyncai/verification-gateway 4.2.0 → 4.3.0

package/README.md

@@ -229,20 +229,39 @@ The CLI uses the same response logic — it will print a "Sign in to approve" me
 
 > A `PDLSSConfig` type exists in both `/registration` and `/agent`, with **different shapes**. `/registration`'s `PDLSSConfig` is the boundary declaration submitted at register time; `/agent`'s `PDLSSConfig` is the per-request runtime request shape. Disambiguate via the import path — the root export deliberately does not re-export either.
 
-### Inner-hop verification (MCP → REST dedupe with X-Astra-Verified-Hop)
-
-When an MCP tool calls an inner REST endpoint that ALSO runs the
-verification gateway, two verify-access calls fire for the same agent in
-the same logical request — audit gets noisy and you pay a doubled
-round-trip. The `X-Astra-Verified-Hop` header marks the inner hop as
-already-verified by the upstream so the inner middleware skips a
-redundant verify-access call.
-
-The MCP middleware emits the marker automatically on its outbound
-response. Tool handlers calling inner REST hops need to forward it on
-outgoing fetches; the inner middleware reads it via `parseVerifiedHop` +
-`isVerifiedHopValidFor` and skips a duplicate verify-access if the
-marker is fresh AND matches the agent claimed on the inner hop.
+### Inner-hop verification (cross-hop dedupe with X-Astra-Verified-Hop)
+
+When an upstream AstraSync hop and an inner gateway-protected endpoint
+both verify the same agent in the same logical request, two verify-access
+calls fire — audit gets noisy and you pay a doubled round-trip. The
+`X-Astra-Verified-Hop` header marks the inner hop as already-verified by
+the upstream so the inner middleware skips the redundant call.
+
+Two upstreams emit the marker automatically (SDK 4.3.0+):
+
+- the **MCP middleware**, on its outbound response (tool handlers calling
+  inner REST hops forward it on outgoing fetches — worked example below);
+- the **edge gateway** (`adapter-lambda` / `adapter-edge`), toward the
+  origin whenever its verify-access call produced identity (authenticate /
+  authorize depth). An SDK-middleware origin behind the TAG then skips the
+  double verify by setting `trustVerifiedHop: true` — at the default
+  classify depth no marker is emitted and the origin verifies as usual.
+
+`trustVerifiedHop` + `verifiedHopMaxAgeMs` are supported on the `express`,
+`nextjs`, and `mcp` middleware options (all default off). The inner
+middleware validates the marker via `parseVerifiedHop` +
+`isVerifiedHopValidFor` and skips a duplicate verify-access only if the
+marker is fresh AND matches the agent claimed on the inner hop. The edge
+gateway strips any inbound `X-Astra-Verified-Hop` on evaluated passes, so
+a viewer can never smuggle one through the TAG.
+
+**Trust model (read before enabling):** the marker is UNSIGNED — a dedupe
+advisory, not proof. Enable `trustVerifiedHop` only when every network
+path to the inner hop crosses a stripping gateway (the TAG) or an
+equivalent trusted boundary; inside that boundary a forger could reduce
+verify-access from "every request" to "once per freshness window" for an
+agent id it already presents. This is the same trust model as the
+unsigned `X-AstraSync-*` attestation headers.
 
 **Worked example — upstream MCP → inner REST hop:**
 
@@ -589,13 +608,18 @@ The **Trusted Agent Gateway (TAG)** is AstraSync's verification gateway at the C
 
 Both consume the same dashboard-managed policy (`./edge-config`), the same platform fingerprint registry (`./platform-signatures`), and the same header sanitiser (`./metadata-capture`) as this SDK — one classification everywhere.
 
-### What each integration captures
+### What each integration captures (canonical capture matrix)
+
+Header-level capture (`ObservedMetadata.headers` etc.) is identical everywhere: **automatic on every verify** for the edge adapters and the `express` / `nextjs` / `mcp` SDK adapters (no config, no opt-out). What differs is the **connection layer** — and the deciding variable is _who operates the CDN in front of your origin_:
+
+| Integration                                                                                        | Connection layer                                                                                                          | TLS fingerprint (JA3/JA4)                                                                                                                                                       |
+| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Edge adapter** (`adapter-lambda`, `adapter-edge`)                                                | **Full** — native platform signals (IP, ASN, geo, TLS, HTTP version, device class, header structure)                      | CloudFront: **JA3 + JA4** (2.2.0+, via the template's origin request policy). Cloudflare Workers: Bot Management zones only. Vercel: JA4 with BotID. Fastly: none               |
+| **SDK behind a CDN you control** (your own Cloudflare / Fastly / Vercel / CloudFront distribution) | **Derived** — geo/ASN/TLS promoted from the CDN's injected headers (`deriveConnectionFromHeaders`)                        | Cloudflare: JA3 + JA4 (`cf-ja3-hash` / `cf-ja4`, plan-dependent). CloudFront: JA3 + JA4 — add the `CloudFront-Viewer-JA3/JA4-Fingerprint` headers to your origin request policy |
+| **SDK behind a platform-managed CDN** (Railway, Render, Fly, Heroku, …)                            | **IP only** — platform CDNs forward `x-forwarded-for` but NOT their provider-specific geo/TLS headers to customer origins | None — no fingerprint header reaches your origin                                                                                                                                |
+| **SDK, no CDN**                                                                                    | Absent (IP from `x-forwarded-for` when a proxy sets it)                                                                   | None                                                                                                                                                                            |
 
-| Integration                                      | Header-level capture (`ObservedMetadata`)                   | Connection layer (IP / ASN / country / TLS / HTTP version / device class)                                                                                              |
-| ------------------------------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Edge adapters (`adapter-lambda`, `adapter-edge`) | Yes                                                         | **Yes** — native platform signals (the authoritative source)                                                                                                           |
-| `express` + `nextjs` SDK adapters                | Yes — **automatic on every verify** (no config, no opt-out) | Derived from CDN-injected headers when your origin sits behind Cloudflare / Fastly / Vercel / CloudFront (`deriveConnectionFromHeaders`, from 4.1.0); absent otherwise |
-| `mcp` SDK adapter                                | Yes — from 4.1.0                                            | Same CDN-header derivation as express/nextjs                                                                                                                           |
+> "Behind Fastly" ≠ "receives Fastly's headers": platform-managed CDNs are operated by the platform, and they do not forward `Fastly-Client-IP`-style headers to your origin. If connection-layer signals or fingerprints matter to you on a managed platform, deploy the edge adapter in front (bucket 1) — that is the whole point of the TAG.
 
 > **Note:** `runCommercePipeline` (on the `./transport` subpath) is the **server-side** orchestrator of commerce-protocol verification — it runs inside the AstraSync verify-access service. The edge adapters forward raw commerce artifacts to verify-access and never bundle or call the pipeline themselves.
 
@@ -622,7 +646,7 @@ The ONE sanitiser deciding what is safe to store from an inbound agent's request
 - `sanitizeHeaders(raw)` → `{ headers, apiKeyFormat?, platformHeaders? }` — drops genuine secrets (cookies, signatures, AstraSync credential headers), reduces credential headers to a safe **format prefix** (e.g. `sk-ant-api03` — a platform signal, never the key), keeps everything else verbatim, and enforces size caps (`MAX_HEADERS`, `MAX_HEADER_VALUE_BYTES`, `MAX_TOTAL_BYTES`).
 - `extractApiKeyFormat(value)` — the safe key-format prefix of a credential header value, or `undefined` for unrecognised/opaque tokens.
 - `extractPlatformHeaders(sanitized)` — the platform-signal subset (`openai-organization`, `anthropic-version`, `x-goog-user-project`, …) of an already-sanitised map.
-- `deriveConnectionFromHeaders(headers)` — promotes CDN-injected headers (Cloudflare / Fastly / Vercel / CloudFront geo, client-IP, and TLS-fingerprint headers, incl. `cf-ja3-hash` / `cf-ja4`) into the `connection` block, so SDK-only deployments behind a CDN still get connection-layer attribution. Native edge signals remain authoritative; this is the SDK-level fallback.
+- `deriveConnectionFromHeaders(headers)` — promotes CDN-injected headers (Cloudflare / Fastly / Vercel / CloudFront geo, client-IP, TLS-fingerprint, and header-structure headers — incl. `cf-ja3-hash` / `cf-ja4` and `cloudfront-viewer-ja3-fingerprint` / `-ja4-fingerprint` from 4.3.0) into the `connection` block, so SDK-only deployments behind a CDN **you control** still get connection-layer attribution (see the capture matrix for the platform-managed-CDN caveat). Values are truncated to `MAX_CONNECTION_VALUE_CHARS` (256 — the platform bound). Native edge signals remain authoritative; this is the SDK-level fallback.
 - `buildSdkObservedMetadata(rawHeaders)` — the one builder the express / nextjs / mcp adapters share: sanitised headers + `apiKeyFormat` + `platformHeaders` + derived `connection` + `schemaVersion`.
 - `CAPTURE_SCHEMA_VERSION` — the capture-semantics version stamped on every `ObservedMetadata` (currently `1`). Capture semantics are **frozen within a major version**: `schemaVersion` bumps only on a semantic change to what is kept/dropped/derived, never for additive signals. The verify body's `sdkVersion` disambiguates builds.
 - Types: `ObservedMetadata` (`{ headers, apiKeyFormat?, platformHeaders?, connection?, schemaVersion? }` — `connection` is populated natively by edge adapters and via CDN-header derivation by SDK adapters), `SanitizeHeadersResult`.

package/dist/adapter-interface/interface.d.mts

@@ -1,6 +1,6 @@
 import { AstraSyncGateway } from '../gateway/gateway.mjs';
-import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-DqfPU5Bl.mjs';
-import '../types-r850cOt0.mjs';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-C7Rb-w0d.mjs';
+import '../types-C0zfSXMB.mjs';
 import '../metadata-capture.mjs';
 
 /**

package/dist/adapter-interface/interface.d.ts

@@ -1,6 +1,6 @@
 import { AstraSyncGateway } from '../gateway/gateway.js';
-import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-BLUx92FJ.js';
-import '../types-sMxBT-nM.js';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-nIh3HtuA.js';
+import '../types-DwSfO7Sb.js';
 import '../metadata-capture.js';
 
 /**

package/dist/adapters/express.d.mts

@@ -1,4 +1,4 @@
 import 'express';
-import '../types-r850cOt0.mjs';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-D_4hTn5Z.mjs';
+import '../types-C0zfSXMB.mjs';
+export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-CR6F3njD.mjs';
 import '../metadata-capture.mjs';

package/dist/adapters/express.d.ts

@@ -1,4 +1,4 @@
 import 'express';
-import '../types-sMxBT-nM.js';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-BVd1_3FE.js';
+import '../types-DwSfO7Sb.js';
+export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-DaqL11tx.js';
 import '../metadata-capture.js';

package/dist/adapters/express.js

@@ -775,6 +775,31 @@ function extractHttpCredentials(headers) {
   return credentials;
 }
 
+// src/verified-hop.ts
+var MCP_VERIFIED_HOP_HEADER = "X-Astra-Verified-Hop";
+var MCP_VERIFIED_HOP_MAX_AGE_MS = 6e4;
+function parseVerifiedHop(value) {
+  if (!value) return null;
+  const parts = value.split(";");
+  if (parts.length !== 3) return null;
+  const [astraId, sessionId, checkedAtRaw] = parts;
+  if (!astraId) return null;
+  const checkedAt = Number(checkedAtRaw);
+  if (!Number.isFinite(checkedAt) || checkedAt <= 0) return null;
+  return {
+    astraId,
+    ...sessionId ? { sessionId } : {},
+    checkedAt
+  };
+}
+function isVerifiedHopValidFor(marker, expectedAstraId, opts = {}) {
+  if (!marker) return false;
+  if (marker.astraId !== expectedAstraId) return false;
+  const maxAge = opts.maxAgeMs ?? MCP_VERIFIED_HOP_MAX_AGE_MS;
+  const now = opts.now ?? Date.now();
+  return now - marker.checkedAt <= maxAge && now >= marker.checkedAt;
+}
+
 // src/adapters/http-pdlss.ts
 var HTTP_METHOD_ACTION_TABLE = {
   GET: "data.read",
@@ -925,7 +950,9 @@ var SECRET_HEADER_NAMES = /* @__PURE__ */ new Set([
   "x-astrasync-signature",
   "x-astrasync-secret",
   "x-hub-signature",
-  "x-hub-signature-256"
+  "x-hub-signature-256",
+  // Short-lived verify dedupe token — must never persist in stored metadata.
+  "x-astra-verified-hop"
 ]);
 var SECRET_HEADER_PREFIXES = ["x-astrasync-", "kya-", "kya_"];
 var CREDENTIAL_HEADER_NAMES = /* @__PURE__ */ new Set([
@@ -1060,16 +1087,25 @@ var CONNECTION_HEADER_SOURCES = [
     ["cf-ipcountry", "x-vercel-ip-country", "cloudfront-viewer-country", "fastly-geo-country"]
   ],
   ["region", ["x-vercel-ip-country-region", "cloudfront-viewer-country-region"]],
+  ["countryRegionName", ["cloudfront-viewer-country-region-name"]],
   ["city", ["x-vercel-ip-city", "cloudfront-viewer-city"]],
   ["asn", ["cloudfront-viewer-asn"]],
   ["tlsVersion", ["cloudfront-viewer-tls"]],
   ["httpVersion", ["cloudfront-viewer-http-version"]],
+  ["timeZone", ["x-vercel-ip-timezone", "cloudfront-viewer-time-zone"]],
+  ["metroCode", ["cloudfront-viewer-metro-code"]],
   // 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"]]
+  // CloudFront delivers JA3/JA4 only via an origin request policy and only
+  // for HTTPS viewer connections.
+  ["tlsFingerprint", ["cf-ja3-hash", "cloudfront-viewer-ja3-fingerprint"]],
+  ["ja4", ["cf-ja4", "cloudfront-viewer-ja4-fingerprint"]],
+  // Header-structure fingerprint: browser/SDK-distinctive header ordering.
+  ["headerOrder", ["cloudfront-viewer-header-order"]],
+  ["headerCount", ["cloudfront-viewer-header-count"]]
 ];
+var MAX_CONNECTION_VALUE_CHARS = 256;
 function deriveConnectionFromHeaders(headers) {
   if (!headers) return void 0;
   const lower = {};
@@ -1082,11 +1118,15 @@ function deriveConnectionFromHeaders(headers) {
     for (const source of sources) {
       const value = lower[source]?.trim();
       if (value) {
-        connection[key] = value;
+        connection[key] = value.slice(0, MAX_CONNECTION_VALUE_CHARS);
         break;
       }
     }
   }
+  if (!connection.ip) {
+    const addr = lower["cloudfront-viewer-address"]?.trim();
+    if (addr) connection.ip = addr.replace(/:\d+$/, "");
+  }
   if (!connection.ip) {
     const xff = lower["x-forwarded-for"];
     const client = xff?.split(",")[0]?.trim();
@@ -1527,6 +1567,8 @@ function createMiddleware(options) {
     failOnError = "open",
     caseInsensitiveRouteMatch = false,
     anonymousBeacon = true,
+    trustVerifiedHop = false,
+    verifiedHopMaxAgeMs,
     ...config
   } = options;
   if (config.apiBaseUrl) {
@@ -1619,6 +1661,16 @@ function createMiddleware(options) {
         beaconPassThrough?.(req);
         return next();
       }
+      if (trustVerifiedHop && credentials.astraId) {
+        const hopRaw = req.headers[MCP_VERIFIED_HOP_HEADER.toLowerCase()];
+        const hopValue = typeof hopRaw === "string" ? hopRaw : Array.isArray(hopRaw) ? hopRaw[0] : void 0;
+        const marker = parseVerifiedHop(hopValue);
+        if (isVerifiedHopValidFor(marker, credentials.astraId, {
+          ...verifiedHopMaxAgeMs !== void 0 ? { maxAgeMs: verifiedHopMaxAgeMs } : {}
+        })) {
+          return next();
+        }
+      }
       const pdlssPair = resolveRequestPdlss(
         req,
         routeConfig,