@astrasyncai/verification-gateway 2.4.0 → 2.4.2

package/dist/index.mjs

@@ -217,8 +217,18 @@ function extractCredentials(headers, query) {
 function hasCredentials(credentials) {
   return !!(credentials.astraId || credentials.apiKey || credentials.jwt);
 }
-function createGuidanceResponse(config, reason) {
-  const guidance = {
+function createGuidanceResponse(config, reason, options = {}) {
+  const source = options.source ?? "no_credentials";
+  const isApiError = source === "api_error";
+  const guidance = isApiError ? {
+    message: "Verification is temporarily unavailable. Retry with exponential backoff; if the issue persists, contact support with the correlationId.",
+    registrationUrl: `${config.apiBaseUrl.replace("/api", "")}/register`,
+    documentationUrl: `${config.apiBaseUrl.replace("/api", "")}/docs/agent-access`,
+    steps: [
+      "Retry the request with exponential backoff",
+      "If failures persist, share the correlationId with support"
+    ]
+  } : {
     message: "This service verifies AI agents before granting access. Please register your agent with AstraSync.",
     registrationUrl: `${config.apiBaseUrl.replace("/api", "")}/register`,
     documentationUrl: `${config.apiBaseUrl.replace("/api", "")}/docs/agent-access`,
@@ -239,6 +249,18 @@ function createGuidanceResponse(config, reason) {
     accessLevel: "none",
     guidance,
     denialReasons: reason ? [reason] : ["No valid agent credentials provided"],
+    // Round-10 (#47, O5): on API-error fallback, surface a typed failure so
+    // partners (and their custom onDenied handlers) can branch on
+    // dimension. Without this, the synthesised stub was indistinguishable
+    // from a real policy deny.
+    failures: isApiError ? [
+      {
+        dimension: "verify_access.api_error",
+        message: reason ?? "Verification temporarily unavailable",
+        guidance: guidance.message
+      }
+    ] : void 0,
+    correlationId: options.correlationId,
     verifiedAt: /* @__PURE__ */ new Date()
   };
 }
@@ -313,7 +335,8 @@ async function callVerifyAccessAPI(config, request) {
     if (!response.ok) {
       return {
         success: false,
-        error: data.message || data.error || `API returned ${response.status}`
+        error: data.message || data.error || `API returned ${response.status}`,
+        correlationId: typeof data?.correlationId === "string" ? data.correlationId : void 0
       };
     }
     return data;
@@ -357,7 +380,10 @@ async function verify(config, request) {
   }
   const apiResponse = await callVerifyAccessAPI(mergedConfig, enrichedRequest);
   if (!apiResponse.success) {
-    return createGuidanceResponse(mergedConfig, apiResponse.error);
+    return createGuidanceResponse(mergedConfig, apiResponse.error, {
+      source: "api_error",
+      correlationId: apiResponse.correlationId
+    });
   }
   if (!apiResponse.access?.allowed) {
     const aggregatedFailures = apiResponse.access?.failures;
@@ -689,13 +715,17 @@ function findRouteConfig(routes, path, method) {
 }
 function defaultOnDenied(result, _req, res) {
   const statusCode = result.verified ? 403 : 401;
+  res.setHeader("X-Astra-Gateway-Mode", "enforced");
   res.status(statusCode).json({
     success: false,
     error: {
       code: result.verified ? "INSUFFICIENT_ACCESS" : "UNAUTHORIZED",
       message: result.denialReasons?.[0] || "Access denied",
       accessLevel: result.accessLevel,
-      guidance: result.guidance
+      guidance: result.guidance,
+      // Round-10: aggregated per-dimension detail + correlation handle.
+      failures: result.failures,
+      correlationId: result.correlationId
     }
   });
 }
@@ -760,7 +790,7 @@ function createMiddleware(options) {
       const routeConfig = findRouteConfig(cachedRoutes, req.path, req.method);
       if (!routeConfig) {
         if (config.setPassThroughHeader) {
-          res.setHeader("X-Astra-Gateway-Mode", "pass-through");
+          res.setHeader("X-Astra-Gateway-Mode", "unenforced");
           res.setHeader(
             "X-Astra-Gateway-Reason",
             cachedRoutes.length === 0 ? "no-policy" : "no-match"
@@ -770,7 +800,7 @@ function createMiddleware(options) {
       }
       if (routeConfig.minAccessLevel === "none") {
         if (config.setPassThroughHeader) {
-          res.setHeader("X-Astra-Gateway-Mode", "pass-through");
+          res.setHeader("X-Astra-Gateway-Mode", "unenforced");
           res.setHeader("X-Astra-Gateway-Reason", "route-none");
         }
         return next();