@astrasyncai/verification-gateway 5.11.0 → 5.12.0

package/dist/adapters/mcp.mjs

@@ -1,5 +1,5 @@
 // src/version.ts
-var SDK_VERSION = "5.11.0";
+var SDK_VERSION = "5.12.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",
@@ -331,11 +366,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 +460,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,6 +499,23 @@ 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) {
         return {
@@ -444,9 +530,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;
@@ -518,12 +606,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 +625,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 +728,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 +1202,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 +1251,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 +1261,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 +1393,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 +1415,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 +1432,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 +1458,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 +1492,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 +1532,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);
       }