@astrasyncai/verification-gateway 5.11.0 → 5.13.0

package/dist/adapters/mcp.mjs

@@ -1,5 +1,5 @@
 // src/version.ts
-var SDK_VERSION = "5.11.0";
+var SDK_VERSION = "5.13.0";
 
 // src/http.ts
 var SDK_USER_AGENT = `astrasync-sdk/${SDK_VERSION}`;
@@ -69,23 +69,58 @@ function prefetchWellKnown(apiBaseUrl) {
   inflight.set(apiBaseUrl, promise);
   return promise;
 }
-async function getWellKnownUrls(apiBaseUrl) {
-  const entry = cache.get(apiBaseUrl);
-  if (entry) {
-    if (Date.now() - entry.fetchedAt > CACHE_TTL_MS) {
-      prefetchWellKnown(apiBaseUrl).catch(() => {
-      });
-    }
-    return entry.data;
-  }
-  const pending = inflight.get(apiBaseUrl);
-  if (pending) return pending;
-  return prefetchWellKnown(apiBaseUrl);
-}
 function getCachedWellKnownUrls(apiBaseUrl) {
   return cache.get(apiBaseUrl)?.data;
 }
 
+// src/failure-posture.ts
+var VERIFICATION_STATUS_HEADER = "X-Astra-Verification";
+var DEFAULT_UNAVAILABLE_RETRY_AFTER_S = 30;
+var REJECTED_IDENTITY_DIMENSIONS = /* @__PURE__ */ new Set([
+  "identity.invalid_agent_id",
+  "identity.unknown_agent",
+  "agent.lookup"
+]);
+var UNKNOWN_AGENT_GUIDANCE = "Register your agent with AstraSync (or, inside an MCP host, add the AstraSync MCP connector for keyless, human-approved registration), then present the canonical ASTRA-* id issued after owner approval.";
+var UNAVAILABLE_DIMENSIONS = /* @__PURE__ */ new Set([
+  "verify_access.api_error",
+  "middleware.internal_error"
+]);
+function isVerificationUnavailable(result) {
+  if (result.misconfigured) return false;
+  return (result.failures ?? []).some((f) => UNAVAILABLE_DIMENSIONS.has(f.dimension));
+}
+function unavailableRetryAfterSeconds(result) {
+  if (typeof result.retryAfterMs === "number" && Number.isFinite(result.retryAfterMs)) {
+    return Math.max(1, Math.ceil(result.retryAfterMs / 1e3));
+  }
+  return DEFAULT_UNAVAILABLE_RETRY_AFTER_S;
+}
+function buildVerificationUnavailableBody(result) {
+  return {
+    success: false,
+    error: {
+      code: "VERIFICATION_UNAVAILABLE",
+      message: "Agent verification is temporarily unavailable and this path enforces verification. Your identity was not evaluated and no denial was recorded \u2014 retry after the Retry-After interval.",
+      retryable: true,
+      retryAfterSeconds: unavailableRetryAfterSeconds(result),
+      ...result.failures && { failures: result.failures },
+      ...result.correlationId && { correlationId: result.correlationId },
+      guidance: {
+        message: "Retry the request after the Retry-After interval, with exponential backoff; the condition is transient."
+      }
+    }
+  };
+}
+function isRejectedIdentityClaim(result) {
+  return (result.failures ?? []).some((f) => REJECTED_IDENTITY_DIMENSIONS.has(f.dimension));
+}
+function denyStatusFor(result, policyDeniedCode) {
+  if (isRejectedIdentityClaim(result)) return { status: 403, code: "AGENT_IDENTITY_REJECTED" };
+  if (result.identityVerified) return { status: 403, code: policyDeniedCode };
+  return { status: 401, code: "UNAUTHORIZED" };
+}
+
 // src/verify.ts
 var DEFAULT_CONFIG = {
   apiBaseUrl: "https://astrasync.ai/api",
@@ -98,7 +133,7 @@ var DEFAULT_CONFIG = {
 };
 var initCheckPerformed = false;
 var deprecationWarningShown = false;
-async function performInitCheck(apiBaseUrl, debug, strictInit, apiKey) {
+async function performInitCheck(apiBaseUrl, debug, strictInit, apiKey, counterparty) {
   initCheckPerformed = true;
   try {
     const probeUrl = `${apiBaseUrl}/agents/verify-access`;
@@ -116,7 +151,8 @@ async function performInitCheck(apiBaseUrl, debug, strictInit, apiKey) {
       );
     }
     if (apiKey) {
-      const selfCheck = await sdkFetch(`${apiBaseUrl}/agents/verify-access/self-check`, {
+      const q = counterparty?.id ? `?counterpartyId=${encodeURIComponent(counterparty.id)}` : counterparty?.url ? `?counterpartyUrl=${encodeURIComponent(counterparty.url)}` : "";
+      const selfCheck = await sdkFetch(`${apiBaseUrl}/agents/verify-access/self-check${q}`, {
         headers: { Authorization: `Bearer ${apiKey}` }
       });
       if (selfCheck.status === 401) {
@@ -128,6 +164,13 @@ async function performInitCheck(apiBaseUrl, debug, strictInit, apiKey) {
         console.error(message);
       } else if (selfCheck.ok) {
         const body = await selfCheck.json().catch(() => ({}));
+        if (body.counterparty && body.counterparty.canVerify === false) {
+          const message = `[VerificationGateway] the configured AstraSync API key cannot verify for this endpoint (${body.counterparty.message ?? "endpoint not found or owned by another account"}). Every inbound agent will be turned away until the key or counterparty is corrected.`;
+          if (strictInit) {
+            throw new Error(`${message} (strictInit=true)`);
+          }
+          console.error(message);
+        }
         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.`
@@ -266,11 +309,11 @@ function createGuidanceResponse(_config, reason, options = {}) {
   const isMisconfig = source === "merchant_misconfig";
   const urls = options.urls;
   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.",
+    message: "This site's AstraSync integration is misconfigured (its API key was revoked, expired, rotated, or belongs to another account). 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",
+      "Report the failure to the site operator \u2014 their AstraSync API key needs replacing",
       "Do not retry: the failure is deterministic until the operator updates their key"
     ]
   } : isApiError ? {
@@ -331,11 +374,44 @@ function createGuidanceResponse(_config, reason, options = {}) {
     // coercing the absent recommendation to a policy 'deny'. Misconfig is
     // deterministic and intentionally NOT marked retryable.
     ...isApiError && { retryable: true },
+    ...options.httpStatus !== void 0 && { httpStatus: options.httpStatus },
+    ...options.retryAfterMs !== void 0 && { retryAfterMs: options.retryAfterMs },
     correlationId: options.correlationId,
     attemptId: options.attemptId,
     verifiedAt: /* @__PURE__ */ new Date()
   };
 }
+async function readJsonSafe(response) {
+  try {
+    const parsed = await response.json();
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function rejectedIdentityGuidance(failures) {
+  const f = failures?.find((x) => REJECTED_IDENTITY_DIMENSIONS.has(x.dimension));
+  if (!f) return void 0;
+  if (f.dimension === "agent.lookup") {
+    return `The presented agent identifier is not registered with AstraSync. ${UNKNOWN_AGENT_GUIDANCE}`;
+  }
+  return f.guidance ? `${f.message} ${f.guidance}` : f.message;
+}
+var MAX_RETRY_AFTER_MS = 15 * 60 * 1e3;
+function parseRetryAfterMs(response) {
+  const raw = response.headers?.get?.("retry-after");
+  if (!raw) return void 0;
+  const trimmed = raw.trim();
+  let ms;
+  if (/^\d+(\.\d+)?$/.test(trimmed)) {
+    ms = Number(trimmed) * 1e3;
+  } else {
+    const at = Date.parse(trimmed);
+    if (Number.isNaN(at)) return void 0;
+    ms = at - Date.now();
+  }
+  return Math.min(MAX_RETRY_AFTER_MS, Math.max(0, Math.round(ms)));
+}
 async function callVerifyAccessAPI(config, request) {
   const { credentials, ...requestData } = request;
   const body = {
@@ -392,7 +468,8 @@ async function callVerifyAccessAPI(config, request) {
       body: JSON.stringify(body),
       signal: AbortSignal.timeout(config.verifyTimeoutMs ?? 1e4)
     });
-    const data = await response.json();
+    const data = await readJsonSafe(response);
+    const retryAfterMs = parseRetryAfterMs(response);
     if (response.status === 410) {
       return {
         success: true,
@@ -430,13 +507,31 @@ async function callVerifyAccessAPI(config, request) {
         }
       };
     }
+    if (response.status === 404 && credentials.astraId && (data?.error === "AGENT_NOT_FOUND" || typeof data?.message === "string" && /agent/i.test(data.message))) {
+      return {
+        success: true,
+        attemptId: typeof data?.attemptId === "string" ? data.attemptId : void 0,
+        access: {
+          allowed: false,
+          reason: "unknown_agent",
+          failures: [
+            {
+              dimension: "identity.unknown_agent",
+              message: "The presented agent identifier is not registered with AstraSync.",
+              guidance: UNKNOWN_AGENT_GUIDANCE
+            }
+          ]
+        }
+      };
+    }
     if (!response.ok) {
-      if (response.status === 401) {
+      const keyMismatch = response.status === 403 && data?.error === "COUNTERPARTY_KEY_MISMATCH";
+      if (response.status === 401 || keyMismatch) {
         return {
           success: false,
           error: data.message || data.error || "Integration API key rejected",
           misconfig: true,
-          misconfigCode: typeof data?.code === "string" ? data.code : void 0,
+          misconfigCode: keyMismatch ? "counterparty_key_mismatch" : 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
@@ -444,9 +539,11 @@ async function callVerifyAccessAPI(config, request) {
       }
       return {
         success: false,
-        error: data.message || data.error || `API returned ${response.status}`,
+        error: typeof data?.message === "string" && data.message || typeof data?.error === "string" && data.error || `API returned ${response.status}`,
         correlationId: typeof data?.correlationId === "string" ? data.correlationId : void 0,
-        attemptId: typeof data?.attemptId === "string" ? data.attemptId : void 0
+        attemptId: typeof data?.attemptId === "string" ? data.attemptId : void 0,
+        httpStatus: response.status,
+        ...retryAfterMs !== void 0 && { retryAfterMs }
       };
     }
     return data;
@@ -467,14 +564,22 @@ async function verify(config, request, options) {
         mergedConfig.apiBaseUrl,
         mergedConfig.debug,
         true,
-        mergedConfig.apiKey
+        mergedConfig.apiKey,
+        {
+          id: mergedConfig.counterpartyId,
+          url: mergedConfig.counterpartyUrl ?? request.counterpartyUrl
+        }
       );
     } else {
       void performInitCheck(
         mergedConfig.apiBaseUrl,
         mergedConfig.debug,
         false,
-        mergedConfig.apiKey
+        mergedConfig.apiKey,
+        {
+          id: mergedConfig.counterpartyId,
+          url: mergedConfig.counterpartyUrl ?? request.counterpartyUrl
+        }
       );
     }
   }
@@ -518,12 +623,14 @@ async function verify(config, request, options) {
       correlationId: apiResponse.correlationId,
       attemptId: apiResponse.attemptId,
       remediation: apiResponse.remediation,
+      httpStatus: apiResponse.httpStatus,
+      retryAfterMs: apiResponse.retryAfterMs,
       urls
     });
   }
   if (!apiResponse.access?.allowed) {
     const aggregatedFailures = apiResponse.access?.failures;
-    const idVerifiedFromBackend = apiResponse.verificationContext?.idVerified === true;
+    const idVerifiedFromBackend = apiResponse.verificationContext?.idVerified === true && !aggregatedFailures?.some((f) => REJECTED_IDENTITY_DIMENSIONS.has(f.dimension));
     const result2 = {
       identityVerified: idVerifiedFromBackend,
       policyAllowed: false,
@@ -535,7 +642,10 @@ async function verify(config, request, options) {
       requiresStepUp: apiResponse.access?.requiresStepUp,
       requiresApproval: apiResponse.access?.requiresApproval,
       guidance: {
-        message: apiResponse.access?.reason || "Access denied by PDLSS policy",
+        // 5.12.0: a presented-but-rejected id (malformed / unknown) carries
+        // actionable registration guidance on its failure — surface it
+        // instead of the bare machine reason ('unknown_agent').
+        message: rejectedIdentityGuidance(aggregatedFailures) ?? (apiResponse.access?.reason || "Access denied by PDLSS policy"),
         registrationUrl: urls?.registrationUrl ?? "",
         documentationUrl: urls?.documentationUrl ?? "",
         // 5.1.0: anonymous callers land on this branch — steer MCP-hosted
@@ -635,7 +745,7 @@ async function verify(config, request, options) {
       registrationUrl: urls?.registrationUrl ?? "",
       documentationUrl: urls?.documentationUrl ?? ""
     };
-  } else if (result.recommendation === "step_up_required") {
+  } else if (result.recommendation === "step_up_required" && result.identityVerified) {
     result.requiresStepUp = true;
     result.denialReasons = serverDenialReasons ?? result.recommendationReasons ?? ["Step-up verification required"];
   }
@@ -1109,8 +1219,37 @@ function dedupeFailures(result) {
     result.denialReasons = [...new Set(result.denialReasons)];
   }
 }
+function isReadOnlyMcpMethod(parsed) {
+  return parsed.method !== "tools/call";
+}
 function defaultMcpDenied(result, req, res) {
   const id = req.body?.id ?? null;
+  if (isVerificationUnavailable(result)) {
+    const retryAfterSeconds = unavailableRetryAfterSeconds(result);
+    const body = buildVerificationUnavailableBody(result).error;
+    res.setHeader("X-Astra-Gateway-Mode", "enforced");
+    res.setHeader(VERIFICATION_STATUS_HEADER, "unavailable");
+    res.setHeader("Retry-After", String(retryAfterSeconds));
+    res.status(503).json({
+      jsonrpc: "2.0",
+      id,
+      error: {
+        // -32003 → verification temporarily unavailable (retryable)
+        code: -32003,
+        message: body.message,
+        data: {
+          code: body.code,
+          recommendation: "error",
+          retryable: true,
+          retryAfterSeconds,
+          guidance: body.guidance,
+          failures: result.failures,
+          correlationId: result.correlationId
+        }
+      }
+    });
+    return;
+  }
   if (result.misconfigured) {
     res.setHeader("X-Astra-Gateway-Mode", "enforced");
     res.status(503).json({
@@ -1129,7 +1268,7 @@ function defaultMcpDenied(result, req, res) {
     });
     return;
   }
-  const status = !result.identityVerified ? 401 : 403;
+  const { status, code: denyCode } = denyStatusFor(result, "INSUFFICIENT_ACCESS");
   res.setHeader("X-Astra-Gateway-Mode", "enforced");
   res.status(status).json({
     jsonrpc: "2.0",
@@ -1139,9 +1278,11 @@ function defaultMcpDenied(result, req, res) {
       //   -32000 → unauthorized (no identity resolved)
       //   -32001 → insufficient access (identity OK, policy denied)
       //   -32002 → merchant verification misconfigured (handled above)
+      //   -32003 → verification temporarily unavailable (handled above)
       code: !result.identityVerified ? -32e3 : -32001,
       message: result.denialReasons?.[0] ?? "Access denied",
       data: {
+        code: denyCode,
         guidance: result.guidance,
         // Round-10: aggregated per-dimension detail + correlation handle.
         failures: result.failures,
@@ -1269,6 +1410,9 @@ function createMcpMiddleware(options) {
           resolved_action: pdlss.action
         });
       }
+      if (!pdlss.purpose && !shouldEnforce) {
+        return next();
+      }
       if (!pdlss.purpose) {
         const id = req.body?.id ?? null;
         res.status(400).json({
@@ -1288,6 +1432,9 @@ function createMcpMiddleware(options) {
       }
       const counterpartyUrl = config.counterpartyUrl || `${req.protocol}://${req.get("host")}${req.path}`;
       const shouldRecordDecisions = recordDecisions !== false;
+      const forwardedFor = req.headers["x-forwarded-for"];
+      const forwardedForStr = Array.isArray(forwardedFor) ? forwardedFor.join(", ") : forwardedFor;
+      const sourceIp = req.ip ?? (forwardedForStr ? forwardedForStr.split(",")[0].trim() : void 0);
       const verificationRequest = {
         credentials,
         purpose: pdlss.purpose,
@@ -1302,9 +1449,10 @@ function createMcpMiddleware(options) {
         counterpartyType: config.counterpartyType || "mcp_server",
         enableRuntimeChallenge,
         callerMetadata: {
-          sourceIp: req.ip,
+          sourceIp,
           userAgent: req.headers["user-agent"],
           host: req.headers.host,
+          ...forwardedForStr && { forwardedFor: forwardedForStr },
           // 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
@@ -1327,6 +1475,21 @@ function createMcpMiddleware(options) {
           result.stepUpOutcome = outcome;
         }
       }
+      if (!result.policyAllowed && isVerificationUnavailable(result) && (!shouldEnforce || isReadOnlyMcpMethod(parsed) && !credentials.astraId && !credentials.jwt)) {
+        res.setHeader(VERIFICATION_STATUS_HEADER, "unavailable");
+        return next();
+      }
+      if (!shouldEnforce) {
+        if (config.setPassThroughHeader) {
+          res.setHeader("X-Astra-Gateway-Mode", "enforced");
+          res.setHeader("X-Astra-Gateway-Reason", "evaluated-not-enforced");
+        }
+        if (shouldRecordDecisions && sessionId) {
+          recordDecision(config, sessionId, "granted").catch(() => {
+          });
+        }
+        return next();
+      }
       if (!result.policyAllowed) {
         if (shouldRecordDecisions && sessionId) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
@@ -1346,17 +1509,6 @@ function createMcpMiddleware(options) {
         onDenied(result, req, res);
         return;
       }
-      if (!shouldEnforce) {
-        if (config.setPassThroughHeader) {
-          res.setHeader("X-Astra-Gateway-Mode", "enforced");
-          res.setHeader("X-Astra-Gateway-Reason", "evaluated-not-enforced");
-        }
-        if (shouldRecordDecisions && sessionId) {
-          recordDecision(config, sessionId, "granted").catch(() => {
-          });
-        }
-        return next();
-      }
       if (effectiveAstraId) {
         res.setHeader(
           MCP_VERIFIED_HOP_HEADER,
@@ -1397,14 +1549,6 @@ function createMcpMiddleware(options) {
           verifiedAt: /* @__PURE__ */ new Date(),
           correlationId
         };
-        const catchUrls = config.apiBaseUrl ? await getWellKnownUrls(config.apiBaseUrl).catch(() => void 0) : void 0;
-        if (catchUrls) {
-          result.guidance = {
-            message: `Middleware threw ${errorClass} \u2014 failing closed`,
-            registrationUrl: catchUrls.registrationUrl,
-            documentationUrl: catchUrls.documentationUrl
-          };
-        }
         dedupeFailures(result);
         return onDenied(result, req, res);
       }