@astrasyncai/verification-gateway 3.12.0 → 4.1.0

package/dist/adapters/mcp.js

@@ -40,7 +40,7 @@ function getTrustLevel(score) {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.12.0";
+var SDK_VERSION = "4.1.0";
 
 // src/well-known.ts
 var CACHE_TTL_MS = 60 * 60 * 1e3;
@@ -118,7 +118,7 @@ var DEFAULT_CONFIG = {
 };
 var initCheckPerformed = false;
 var deprecationWarningShown = false;
-async function performInitCheck(apiBaseUrl, debug, strictInit) {
+async function performInitCheck(apiBaseUrl, debug, strictInit, apiKey) {
   initCheckPerformed = true;
   try {
     const probeUrl = `${apiBaseUrl}/agents/verify-access`;
@@ -135,6 +135,28 @@ async function performInitCheck(apiBaseUrl, debug, strictInit) {
         `[VerificationGateway] init check passed for ${apiBaseUrl} (content-type: ${contentType})`
       );
     }
+    if (apiKey) {
+      const selfCheck = await fetch(`${apiBaseUrl}/agents/verify-access/self-check`, {
+        headers: { Authorization: `Bearer ${apiKey}` }
+      });
+      if (selfCheck.status === 401) {
+        const body = await selfCheck.json().catch(() => ({}));
+        const message = `[VerificationGateway] the configured AstraSync API key was REJECTED at startup (${body.code ?? "api_key_invalid"}: ${body.message ?? "invalid key"}). Every inbound agent will be turned away until the key is rotated` + (body.remediation?.manageUrl ? ` at ${body.remediation.manageUrl}` : "") + `.`;
+        if (strictInit) {
+          throw new Error(`${message} (strictInit=true)`);
+        }
+        console.error(message);
+      } else if (selfCheck.ok) {
+        const body = await selfCheck.json().catch(() => ({}));
+        if (typeof body.daysToExpiry === "number" && body.daysToExpiry <= 7) {
+          console.warn(
+            `[VerificationGateway] the configured AstraSync API key expires in ${body.daysToExpiry} day(s) \u2014 rotate it at Settings \u2192 Developer Tools before integrations start failing.`
+          );
+        } else if (debug) {
+          console.log("[VerificationGateway] API key self-check passed");
+        }
+      }
+    }
   } catch (err) {
     if (strictInit) {
       throw err;
@@ -246,8 +268,17 @@ function extractCredentials(headers, query) {
 function createGuidanceResponse(_config, reason, options = {}) {
   const source = options.source ?? "no_credentials";
   const isApiError = source === "api_error";
+  const isMisconfig = source === "merchant_misconfig";
   const urls = options.urls;
-  const guidance = isApiError ? {
+  const guidance = isMisconfig ? {
+    message: "This site's AstraSync integration is misconfigured (its API key was revoked, expired, or rotated). Your identity and the AstraSync platform are fine \u2014 contact the site operator. Retrying will not help.",
+    registrationUrl: urls?.registrationUrl ?? "",
+    documentationUrl: options.remediation?.docsUrl ?? urls?.documentationUrl ?? "",
+    steps: [
+      "Report the failure to the site operator \u2014 their AstraSync API key needs rotating",
+      "Do not retry: the failure is deterministic until the operator updates their key"
+    ]
+  } : isApiError ? {
     message: "Verification is temporarily unavailable. Retry with exponential backoff; if the issue persists, contact support with the correlationId.",
     registrationUrl: urls?.registrationUrl ?? "",
     documentationUrl: urls?.documentationUrl ?? "",
@@ -285,13 +316,22 @@ function createGuidanceResponse(_config, reason, options = {}) {
     // partners (and their custom onDenied handlers) can branch on
     // dimension. Without this, the synthesised stub was indistinguishable
     // from a real policy deny.
-    failures: isApiError ? [
+    failures: isMisconfig ? [
+      {
+        dimension: "verify_access.merchant_misconfigured",
+        message: reason ?? "The integration API key was rejected by AstraSync",
+        guidance: guidance.message
+      }
+    ] : isApiError ? [
       {
         dimension: "verify_access.api_error",
         message: reason ?? "Verification temporarily unavailable",
         guidance: guidance.message
       }
     ] : void 0,
+    // 4.0.0: typed marker so adapters render the misconfig envelope (503 +
+    // MERCHANT_VERIFICATION_MISCONFIGURED) without string-matching.
+    ...isMisconfig && { misconfigured: true },
     correlationId: options.correlationId,
     attemptId: options.attemptId,
     verifiedAt: /* @__PURE__ */ new Date()
@@ -346,7 +386,8 @@ async function callVerifyAccessAPI(config, request) {
     const response = await fetch(`${config.apiBaseUrl}/agents/verify-access`, {
       method: "POST",
       headers,
-      body: JSON.stringify(body)
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(config.verifyTimeoutMs ?? 1e4)
     });
     const data = await response.json();
     if (response.status === 410) {
@@ -370,6 +411,17 @@ async function callVerifyAccessAPI(config, request) {
       };
     }
     if (!response.ok) {
+      if (response.status === 401) {
+        return {
+          success: false,
+          error: data.message || data.error || "Integration API key rejected",
+          misconfig: true,
+          misconfigCode: typeof data?.code === "string" ? data.code : void 0,
+          remediation: data?.remediation && typeof data.remediation === "object" ? data.remediation : void 0,
+          correlationId: typeof data?.correlationId === "string" ? data.correlationId : void 0,
+          attemptId: typeof data?.attemptId === "string" ? data.attemptId : void 0
+        };
+      }
       return {
         success: false,
         error: data.message || data.error || `API returned ${response.status}`,
@@ -391,9 +443,19 @@ async function verify(config, request, options) {
   const urls = mergedConfig.apiBaseUrl ? getCachedWellKnownUrls(mergedConfig.apiBaseUrl) : void 0;
   if (!initCheckPerformed && !mergedConfig.disableInitChecks && mergedConfig.apiBaseUrl) {
     if (mergedConfig.strictInit) {
-      await performInitCheck(mergedConfig.apiBaseUrl, mergedConfig.debug, true);
+      await performInitCheck(
+        mergedConfig.apiBaseUrl,
+        mergedConfig.debug,
+        true,
+        mergedConfig.apiKey
+      );
     } else {
-      void performInitCheck(mergedConfig.apiBaseUrl, mergedConfig.debug, false);
+      void performInitCheck(
+        mergedConfig.apiBaseUrl,
+        mergedConfig.debug,
+        false,
+        mergedConfig.apiKey
+      );
     }
   }
   if (!deprecationWarningShown && (config.minTrustScore !== void 0 || config.minTrustScoreForFull !== void 0)) {
@@ -432,9 +494,10 @@ async function verify(config, request, options) {
   const serverDenialReasons = Array.isArray(rawServerDenialReasons) && rawServerDenialReasons.length > 0 ? rawServerDenialReasons : void 0;
   if (!apiResponse.success) {
     return createGuidanceResponse(mergedConfig, apiResponse.error, {
-      source: "api_error",
+      source: apiResponse.misconfig ? "merchant_misconfig" : "api_error",
       correlationId: apiResponse.correlationId,
       attemptId: apiResponse.attemptId,
+      remediation: apiResponse.remediation,
       urls
     });
   }
@@ -571,6 +634,205 @@ async function recordDecision(config, sessionId, decision, reason) {
   });
 }
 
+// src/metadata-capture.ts
+var CAPTURE_SCHEMA_VERSION = 1;
+var SECRET_HEADER_NAMES = /* @__PURE__ */ new Set([
+  "cookie",
+  "set-cookie",
+  "x-csrf-token",
+  "proxy-authorization",
+  "x-astrasync-signature",
+  "x-astrasync-secret",
+  "x-hub-signature",
+  "x-hub-signature-256"
+]);
+var SECRET_HEADER_PREFIXES = ["x-astrasync-", "kya-", "kya_"];
+var CREDENTIAL_HEADER_NAMES = /* @__PURE__ */ new Set([
+  "authorization",
+  "x-api-key",
+  "x-goog-api-key",
+  "api-key"
+]);
+function isSignatureHeader(name) {
+  return name === "signature" || name.endsWith("-signature") || name.endsWith("-signature-256");
+}
+var PLATFORM_HEADER_NAMES = /* @__PURE__ */ new Set([
+  "openai-organization",
+  "openai-project",
+  "openai-version",
+  "openai-processing-ms",
+  "anthropic-version",
+  "anthropic-beta",
+  "x-goog-user-project",
+  "x-goog-api-client",
+  "user-agent",
+  "x-agent-card-url",
+  "x-agent-provider"
+]);
+var PLATFORM_HEADER_PREFIXES = ["x-goog-", "x-stainless-", "x-anthropic-", "x-openai-"];
+var KEY_FORMAT_PREFIXES = [
+  "sk-ant-api03",
+  "sk-ant-api",
+  "sk-ant",
+  "sk-proj",
+  "sk-svcacct",
+  "sk-or-v1",
+  "sk-or",
+  "sk-lf",
+  "sk-",
+  "gsk_",
+  "aiza",
+  "ya29",
+  "ghp_",
+  "gho_",
+  "github_pat_",
+  "xai-",
+  "pplx-",
+  "r8_",
+  "hf_",
+  "astra-",
+  "astrae-"
+];
+var MAX_HEADERS = 64;
+var MAX_HEADER_VALUE_BYTES = 1024;
+var MAX_TOTAL_BYTES = 16 * 1024;
+function byteLength(s) {
+  let bytes = 0;
+  for (let i = 0; i < s.length; i++) {
+    const code = s.charCodeAt(i);
+    if (code < 128) bytes += 1;
+    else if (code < 2048) bytes += 2;
+    else if (code >= 55296 && code <= 56319) {
+      bytes += 4;
+      i++;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+function extractApiKeyFormat(rawValue) {
+  if (!rawValue) return void 0;
+  let value = rawValue.trim();
+  const spaceIdx = value.indexOf(" ");
+  if (spaceIdx > 0) {
+    const scheme = value.slice(0, spaceIdx).toLowerCase();
+    if (scheme === "bearer" || scheme === "basic" || scheme === "token") {
+      value = value.slice(spaceIdx + 1).trim();
+    }
+  }
+  const lower = value.toLowerCase();
+  for (const prefix of KEY_FORMAT_PREFIXES) {
+    if (lower.startsWith(prefix)) {
+      return prefix;
+    }
+  }
+  return void 0;
+}
+function isSecretHeader(name) {
+  if (SECRET_HEADER_NAMES.has(name)) return true;
+  if (SECRET_HEADER_PREFIXES.some((p) => name.startsWith(p))) return true;
+  if (isSignatureHeader(name)) return true;
+  return false;
+}
+function isPlatformHeader(name) {
+  if (PLATFORM_HEADER_NAMES.has(name)) return true;
+  return PLATFORM_HEADER_PREFIXES.some((p) => name.startsWith(p));
+}
+function sanitizeHeaders(raw) {
+  const headers = {};
+  const platformHeaders = {};
+  let apiKeyFormat;
+  let totalBytes = 0;
+  let count = 0;
+  if (!raw) return { headers };
+  for (const rawName of Object.keys(raw)) {
+    if (count >= MAX_HEADERS) break;
+    const name = rawName.toLowerCase();
+    const rawValue = raw[rawName];
+    if (rawValue === void 0) continue;
+    const joined = Array.isArray(rawValue) ? rawValue.join(", ") : String(rawValue);
+    if (CREDENTIAL_HEADER_NAMES.has(name)) {
+      const fmt = extractApiKeyFormat(joined);
+      if (fmt && !apiKeyFormat) apiKeyFormat = fmt;
+      continue;
+    }
+    if (isSecretHeader(name)) continue;
+    let value = joined;
+    if (byteLength(value) > MAX_HEADER_VALUE_BYTES) {
+      value = value.slice(0, MAX_HEADER_VALUE_BYTES);
+    }
+    const entryBytes = byteLength(name) + byteLength(value);
+    if (totalBytes + entryBytes > MAX_TOTAL_BYTES) continue;
+    totalBytes += entryBytes;
+    count++;
+    headers[name] = value;
+    if (isPlatformHeader(name)) platformHeaders[name] = value;
+  }
+  const result = { headers };
+  if (apiKeyFormat) result.apiKeyFormat = apiKeyFormat;
+  if (Object.keys(platformHeaders).length > 0) result.platformHeaders = platformHeaders;
+  return result;
+}
+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/adapters/approval-gate.ts
 var APPROVAL_REASON = "Transaction is above the autonomous limit and requires human approval. The agent owner can approve or deny this transaction in the AstraSync dashboard.";
 function requiresHumanApproval(result) {
@@ -749,8 +1011,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 };
@@ -788,6 +1053,24 @@ function dedupeFailures(result) {
 }
 function defaultMcpDenied(result, req, res) {
   const id = req.body?.id ?? null;
+  if (result.misconfigured) {
+    res.setHeader("X-Astra-Gateway-Mode", "enforced");
+    res.status(503).json({
+      jsonrpc: "2.0",
+      id,
+      error: {
+        // -32002 → merchant verification misconfigured (see -32000/-32001 below)
+        code: -32002,
+        message: result.denialReasons?.[0] ?? "This server's AstraSync integration is misconfigured",
+        data: {
+          guidance: result.guidance,
+          failures: result.failures,
+          correlationId: result.correlationId
+        }
+      }
+    });
+    return;
+  }
   const status = !result.identityVerified ? 401 : 403;
   res.setHeader("X-Astra-Gateway-Mode", "enforced");
   res.status(status).json({
@@ -797,6 +1080,7 @@ function defaultMcpDenied(result, req, res) {
       // JSON-RPC error codes:
       //   -32000 → unauthorized (no identity resolved)
       //   -32001 → insufficient access (identity OK, policy denied)
+      //   -32002 → merchant verification misconfigured (handled above)
       code: !result.identityVerified ? -32e3 : -32001,
       message: result.denialReasons?.[0] ?? "Access denied",
       data: {
@@ -846,6 +1130,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();
@@ -965,7 +1258,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);