@astrasyncai/verification-gateway 3.1.0 → 3.2.1

package/dist/index.mjs

@@ -126,7 +126,7 @@ function getCapabilities(accessLevel) {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.1.0";
+var SDK_VERSION = "3.2.1";
 
 // src/well-known.ts
 var CACHE_TTL_MS = 60 * 60 * 1e3;
@@ -231,7 +231,7 @@ async function performInitCheck(apiBaseUrl, debug, strictInit) {
   }
 }
 var verificationCache = /* @__PURE__ */ new Map();
-function getCacheKey(request) {
+function getCacheKey(request, counterpartyId) {
   const c = request.credentials;
   return [
     c.astraId || "",
@@ -244,6 +244,14 @@ function getCacheKey(request) {
     request.jurisdiction || "",
     request.transactionValue ?? "",
     request.currency || "",
+    // SECURITY (cross-merchant cache leak): the merchant identity is sent via
+    // `config.counterpartyId`, NOT on the request, so it was previously absent
+    // from the key — two verifies for the SAME agent/purpose/action/value but
+    // DIFFERENT merchants collided, and a grant at a permissive merchant (low
+    // trust floor) was served for a stricter one. Same bug class as the
+    // duration omission (F-A1-07). counterpartyId affects the backend verdict
+    // (trust floor / per-route policy), so it MUST key the cache.
+    counterpartyId || "",
     request.counterpartyUrl || "",
     request.counterpartyType || "",
     request.isSubAgentRequest ? "1" : "0",
@@ -267,8 +275,8 @@ function getCacheKey(request) {
     request.callerMetadata?.agentCardUrl || ""
   ].join("|");
 }
-function getCachedResult(request) {
-  const key = getCacheKey(request);
+function getCachedResult(request, counterpartyId) {
+  const key = getCacheKey(request, counterpartyId);
   const cached = verificationCache.get(key);
   if (cached && cached.expiresAt > Date.now()) {
     return cached.result;
@@ -280,9 +288,9 @@ function getCachedResult(request) {
 }
 var DEFAULT_AUTONOMOUS_TTL_SECONDS = 60;
 var DEFAULT_STEP_UP_TTL_SECONDS = 300;
-function cacheResult(request, result, configuredTtl) {
+function cacheResult(request, result, configuredTtl, counterpartyId) {
   const ttlSeconds = configuredTtl && configuredTtl > 0 ? configuredTtl : result.requiresStepUp ? DEFAULT_STEP_UP_TTL_SECONDS : DEFAULT_AUTONOMOUS_TTL_SECONDS;
-  const key = getCacheKey(request);
+  const key = getCacheKey(request, counterpartyId);
   verificationCache.set(key, {
     result,
     expiresAt: Date.now() + ttlSeconds * 1e3
@@ -480,7 +488,7 @@ async function verify(config, request) {
     );
   }
   if (mergedConfig.cacheTtl !== 0) {
-    const cached = getCachedResult(request);
+    const cached = getCachedResult(request, mergedConfig.counterpartyId);
     if (cached) {
       if (mergedConfig.debug) {
         console.log("[VerificationGateway] Returning cached result");
@@ -532,8 +540,8 @@ async function verify(config, request) {
       verifiedAt: /* @__PURE__ */ new Date(),
       // Extract sessionId so decisions can be recorded for denials too
       sessionId: apiResponse.sessionId,
-      // v2.3.10 (defect #34, round-4): anonymous traffic has no session →
-      // correlationId is the linking key for paired local_override events.
+      // Anonymous traffic has no session → correlationId is the per-attempt
+      // linking key (the sessionId-equivalent for anonymous callers).
       correlationId: apiResponse.correlationId,
       recommendation: apiResponse.recommendation,
       recommendationReasons: apiResponse.recommendationReasons
@@ -607,17 +615,14 @@ async function verify(config, request) {
     };
   } else if (result.recommendation === "step_up_required") {
     result.requiresStepUp = true;
-    if (ACCESS_LEVEL_HIERARCHY[result.accessLevel] > ACCESS_LEVEL_HIERARCHY["read-only"]) {
-      result.accessLevel = "read-only";
-    }
     result.denialReasons = result.recommendationReasons || ["Step-up verification required"];
   }
   if (mergedConfig.cacheTtl !== 0 && result.recommendation !== "deny") {
-    cacheResult(request, result, mergedConfig.cacheTtl);
+    cacheResult(request, result, mergedConfig.cacheTtl, mergedConfig.counterpartyId);
   }
   return result;
 }
-async function recordDecision(config, sessionId, decision, reason, override) {
+async function recordDecision(config, sessionId, decision, reason) {
   const headers = { "Content-Type": "application/json" };
   if (config.apiKey) {
     headers["Authorization"] = `Bearer ${config.apiKey}`;
@@ -626,36 +631,7 @@ async function recordDecision(config, sessionId, decision, reason, override) {
   await fetch(`${config.apiBaseUrl}/agents/verify-access/${sessionId}/decision`, {
     method: "POST",
     headers,
-    body: JSON.stringify({
-      decision,
-      reason,
-      ...override && {
-        overriddenBy: override.overriddenBy,
-        toolName: override.toolName,
-        requestedLevel: override.requestedLevel,
-        grantedLevel: override.grantedLevel
-      }
-    })
-  }).catch(() => {
-  });
-}
-async function recordAnonymousLocalOverride(config, correlationId, override, reason) {
-  const headers = { "Content-Type": "application/json" };
-  if (config.apiKey) {
-    headers["Authorization"] = `Bearer ${config.apiKey}`;
-    headers["X-API-Key"] = config.apiKey;
-  }
-  await fetch(`${config.apiBaseUrl}/agents/verify-access/local-override`, {
-    method: "POST",
-    headers,
-    body: JSON.stringify({
-      correlationId,
-      reason,
-      overriddenBy: override.overriddenBy,
-      toolName: override.toolName,
-      requestedLevel: override.requestedLevel,
-      grantedLevel: override.grantedLevel
-    })
+    body: JSON.stringify({ decision, reason })
   }).catch(() => {
   });
 }
@@ -856,6 +832,19 @@ function resolveHttpPdlss(input) {
   return { purpose, action, purposeSource, actionSource };
 }
 
+// src/adapters/approval-gate.ts
+var APPROVAL_REASON = "Transaction is above the autonomous limit and requires human approval, which is not yet available \u2014 it cannot be completed automatically.";
+function requiresHumanApproval(result) {
+  return result.requiresStepUp === true || result.requiresApproval === true;
+}
+function annotateApprovalRequired(result) {
+  result.failures = [
+    ...result.failures ?? [],
+    { dimension: "commerce.intent.approval_required", message: APPROVAL_REASON }
+  ];
+  result.denialReasons = [APPROVAL_REASON, ...result.denialReasons ?? []];
+}
+
 // src/pdlss-pre-check.ts
 function performCounterpartyPreCheck(routeConfig, astraCreds, purpose) {
   const failures = [];
@@ -1163,6 +1152,16 @@ function createMiddleware(options) {
         onDenied(result, req, res);
         return;
       }
+      if (requiresHumanApproval(result)) {
+        annotateApprovalRequired(result);
+        if (shouldRecordDecisions && sessionId) {
+          recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
+          });
+        }
+        dedupeFailures(result);
+        onDenied(result, req, res);
+        return;
+      }
       if (!shouldEnforce) {
         if (config.setPassThroughHeader) {
           res.setHeader("X-Astra-Gateway-Mode", "enforced");
@@ -1174,35 +1173,12 @@ function createMiddleware(options) {
         }
         return next();
       }
-      if (!hasMinimumAccess(result.accessLevel, routeConfig.minAccessLevel)) {
-        const insufficientFailure = {
-          dimension: "access_level.insufficient",
-          message: `Endpoint requires accessLevel '${routeConfig.minAccessLevel}'; agent has '${result.accessLevel}'.`,
-          guidance: "Request elevated access via step-up verification (coming soon \u2014 ships this month). Step-up lets the agent owner approve a one-time elevation for this specific counterparty + purpose without changing the agent's baseline trust score."
-        };
-        result.failures = [...result.failures ?? [], insufficientFailure];
-        result.denialReasons = [...result.denialReasons ?? [], insufficientFailure.message];
-        if (!result.guidance && wellKnownUrls) {
-          result.guidance = {
-            message: insufficientFailure.message,
-            registrationUrl: wellKnownUrls.registrationUrl,
-            documentationUrl: wellKnownUrls.documentationUrl
-          };
-        }
-        if (shouldRecordDecisions && sessionId) {
-          recordDecision(config, sessionId, "denied", insufficientFailure.message).catch(() => {
-          });
-        }
-        dedupeFailures(result);
-        onDenied(result, req, res);
-        return;
-      }
       if (routeConfig.minTrustScore && result.agent) {
         if (result.agent.trustScore < routeConfig.minTrustScore) {
           const trustFailure = {
-            dimension: "access_level.insufficient",
-            message: `Trust score ${result.agent.trustScore} is below required ${routeConfig.minTrustScore} for this route.`,
-            guidance: "Request elevated access via step-up verification (coming soon \u2014 ships this month). Step-up lets the agent owner approve a one-time elevation for this specific counterparty + purpose without changing the agent's baseline trust score."
+            dimension: "endpoint.trust",
+            message: "Trust below the route requirement for this endpoint.",
+            guidance: "Trust is below this route's floor. Trust is not overridable \u2014 the agent either meets the endpoint's trust policy or it doesn't. Raise the agent's trust via real signals (KYD, blockchain registration, agent-card), or have the operator lower the route's minTrustScore."
           };
           result.failures = [...result.failures ?? [], trustFailure];
           result.denialReasons = [trustFailure.message];
@@ -1633,7 +1609,9 @@ function createMiddleware2(options) {
         agentCardUrl: request.headers.get("x-astrasync-agent-card") || void 0
       }
     });
-    if (!result.identityVerified || !result.policyAllowed || !hasMinimumAccess(result.accessLevel, routeConfig.minAccessLevel)) {
+    const approvalRequired = result.identityVerified && result.policyAllowed && requiresHumanApproval(result);
+    if (approvalRequired) annotateApprovalRequired(result);
+    if (!result.identityVerified || !result.policyAllowed || approvalRequired) {
       if (pathname.startsWith("/api/")) {
         return NextResponse.json(
           {
@@ -1641,11 +1619,10 @@ function createMiddleware2(options) {
             error: {
               // Round-18 G4: 401 → identity missing (re-auth); 403 → identity
               // OK, policy denied (update PDLSS / step up).
-              code: !result.identityVerified ? "UNAUTHORIZED" : "INSUFFICIENT_ACCESS",
+              code: !result.identityVerified ? "UNAUTHORIZED" : "POLICY_DENIED",
               message: result.denialReasons?.[0] || "Access denied",
-              accessLevel: result.accessLevel,
-              required: routeConfig.minAccessLevel,
-              guidance: result.guidance
+              guidance: result.guidance,
+              failures: result.failures
             }
           },
           { status: !result.identityVerified ? 401 : 403 }
@@ -1672,7 +1649,6 @@ function createMiddleware2(options) {
     response.headers.set("X-AstraSync-Access-Level", result.accessLevel);
     if (result.agent) {
       response.headers.set("X-AstraSync-Agent-Id", result.agent.astraId);
-      response.headers.set("X-AstraSync-Trust-Score", result.agent.trustScore.toString());
     }
     return response;
   };
@@ -1746,7 +1722,13 @@ var VerificationGatewayClient = class {
     return this.executeWithRetry(() => quickVerify(this.config, credentials));
   }
   /**
-   * Check if an agent has a specific access level
+   * Check if an agent has a specific access level.
+   *
+   * @deprecated 3.2.0 — the access-level band is informational only; it no
+   * longer gates in the middleware adapters (post-3.1.0 feedback #1). This
+   * explicit opt-in query still works, but prefer gating on the server-side
+   * policy decision (identity + policy + trust) or per-route `minTrustScore`.
+   * Explicit per-route condition→constraint rules are the Phase-2 successor.
    */
   async hasAccess(credentials, requiredLevel) {
     const result = await this.quickVerify(credentials);
@@ -4593,7 +4575,6 @@ function createMcpMiddleware(options) {
         return next();
       }
       req.mcpRequest = parsed;
-      const wellKnownUrls = config.apiBaseUrl ? await getWellKnownUrls(config.apiBaseUrl).catch(() => void 0) : void 0;
       const headerRaw = req.headers["x-astra-id"] ?? req.headers["x-astra-agentid"];
       const headerAstraId = typeof headerRaw === "string" ? headerRaw : Array.isArray(headerRaw) ? headerRaw[0] : void 0;
       const bodyAstraId = parsed.agentIdFromBody;
@@ -4630,7 +4611,7 @@ function createMcpMiddleware(options) {
           return next();
         }
       }
-      const { level: minAccessLevel, source: gateSource } = resolveMinAccessLevel(parsed, {
+      const { level: minAccessLevel } = resolveMinAccessLevel(parsed, {
         toolGates,
         methodGates
       });
@@ -4666,6 +4647,23 @@ function createMcpMiddleware(options) {
           resolved_action: pdlss.action
         });
       }
+      if (!pdlss.purpose) {
+        const id = req.body?.id ?? null;
+        res.status(400).json({
+          jsonrpc: "2.0",
+          id,
+          error: {
+            code: -32602,
+            message: "PDLSS_PURPOSE_REQUIRED",
+            data: {
+              dimension: "pdlss.purpose",
+              detail: "This tool is access-gated but the call declared no PDLSS purpose. Supply a bare-category purpose via the X-Astra-Purpose header or params._meta.astrasync.purpose, or have the merchant set the tool\u2019s purpose in its toolGate config.",
+              resolvedAction: pdlss.action
+            }
+          }
+        });
+        return;
+      }
       const counterpartyUrl = config.counterpartyUrl || `${req.protocol}://${req.get("host")}${req.path}`;
       const shouldRecordDecisions = recordDecisions !== false;
       const result = await verify(config, {
@@ -4689,7 +4687,6 @@ function createMcpMiddleware(options) {
       });
       req.agentVerification = result;
       const sessionId = result.sessionId;
-      const correlationId = result.correlationId;
       if (!result.identityVerified || !result.policyAllowed) {
         if (shouldRecordDecisions && sessionId) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
@@ -4699,6 +4696,16 @@ function createMcpMiddleware(options) {
         onDenied(result, req, res);
         return;
       }
+      if (requiresHumanApproval(result)) {
+        annotateApprovalRequired(result);
+        if (shouldRecordDecisions && sessionId) {
+          recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
+          });
+        }
+        dedupeFailures2(result);
+        onDenied(result, req, res);
+        return;
+      }
       if (!shouldEnforce) {
         if (config.setPassThroughHeader) {
           res.setHeader("X-Astra-Gateway-Mode", "enforced");
@@ -4710,48 +4717,6 @@ function createMcpMiddleware(options) {
         }
         return next();
       }
-      if (!hasMinimumAccess(result.accessLevel, minAccessLevel)) {
-        const insufficientFailure = {
-          dimension: "access_level.insufficient",
-          message: `Tool requires accessLevel '${minAccessLevel}'; agent has '${result.accessLevel}'.`,
-          guidance: "Request elevated access via step-up verification (coming soon \u2014 ships this month). Step-up lets the agent owner approve a one-time elevation for this specific counterparty + purpose without changing the agent's baseline trust score."
-        };
-        result.failures = [...result.failures ?? [], insufficientFailure];
-        result.denialReasons = [...result.denialReasons ?? [], insufficientFailure.message];
-        if (!result.guidance && wellKnownUrls) {
-          result.guidance = {
-            message: insufficientFailure.message,
-            registrationUrl: wellKnownUrls.registrationUrl,
-            documentationUrl: wellKnownUrls.documentationUrl
-          };
-        }
-        if (shouldRecordDecisions) {
-          const overrideKind = gateSource === "toolGate" ? "toolGate" : gateSource === "methodGate" ? "methodGate" : "other";
-          const override = {
-            overriddenBy: overrideKind,
-            ...parsed.toolName && { toolName: parsed.toolName },
-            requestedLevel: minAccessLevel,
-            grantedLevel: result.accessLevel
-          };
-          if (sessionId) {
-            recordDecision(config, sessionId, "denied", result.denialReasons?.[0], override).catch(
-              () => {
-              }
-            );
-          } else if (correlationId) {
-            recordAnonymousLocalOverride(
-              config,
-              correlationId,
-              override,
-              result.denialReasons?.[0]
-            ).catch(() => {
-            });
-          }
-        }
-        dedupeFailures2(result);
-        onDenied(result, req, res);
-        return;
-      }
       if (effectiveAstraId) {
         res.setHeader(
           MCP_VERIFIED_HOP_HEADER,