@astrasyncai/verification-gateway 3.0.0 → 3.2.0

package/dist/adapters/express.mjs

@@ -1,24 +1,13 @@
 // src/access-levels.ts
-var ACCESS_LEVEL_HIERARCHY = {
-  none: 0,
-  restricted: 1,
-  "read-only": 2,
-  standard: 3,
-  full: 4,
-  internal: 5
-};
 function getTrustLevel(score) {
   if (score >= 80) return "PLATINUM";
   if (score >= 60) return "GOLD";
   if (score >= 40) return "SILVER";
   return "BRONZE";
 }
-function hasMinimumAccess(actual, required) {
-  return ACCESS_LEVEL_HIERARCHY[actual] >= ACCESS_LEVEL_HIERARCHY[required];
-}
 
 // src/version.ts
-var SDK_VERSION = "3.0.0";
+var SDK_VERSION = "3.2.0";
 
 // src/well-known.ts
 var CACHE_TTL_MS = 60 * 60 * 1e3;
@@ -123,7 +112,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 || "",
@@ -136,6 +125,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",
@@ -159,8 +156,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;
@@ -172,9 +169,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
@@ -366,7 +363,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");
@@ -418,8 +415,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
@@ -493,17 +490,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}`;
@@ -512,16 +506,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
-      }
-    })
+    body: JSON.stringify({ decision, reason })
   }).catch(() => {
   });
 }
@@ -576,6 +561,13 @@ function extractHttpCredentials(headers) {
       purpose: { category, action }
     };
   }
+  const astraAction = getValue(`${HEADER_PREFIX}Action`) ?? getValue("x-astra-action");
+  if (astraAction) {
+    credentials.pdlss = {
+      ...credentials.pdlss,
+      purpose: { category: credentials.pdlss?.purpose?.category ?? "", action: astraAction }
+    };
+  }
   const duration = getValue(`${HEADER_PREFIX}Duration`) ?? getValue("x-astra-duration");
   if (duration) {
     credentials.pdlss = {
@@ -593,6 +585,85 @@ function extractHttpCredentials(headers) {
   return credentials;
 }
 
+// src/adapters/http-pdlss.ts
+var HTTP_METHOD_ACTION_TABLE = {
+  GET: "data.read",
+  HEAD: "data.read",
+  OPTIONS: "data.read",
+  POST: "data.write",
+  PUT: "data.write",
+  PATCH: "data.write",
+  DELETE: "data.delete"
+};
+var DEFAULT_HTTP_ACTION = "data.write";
+var DEFAULT_HTTP_PURPOSE = "data";
+function actionForHttpMethod(method) {
+  return HTTP_METHOD_ACTION_TABLE[method.toUpperCase()] ?? DEFAULT_HTTP_ACTION;
+}
+function normalizePurposeHeader(value) {
+  const colon = value.indexOf(":");
+  if (colon >= 0) {
+    return { purpose: value.slice(0, colon) };
+  }
+  const dot = value.indexOf(".");
+  if (dot > 0 && dot < value.length - 1) {
+    return { purpose: value.slice(0, dot), actionCandidate: value };
+  }
+  return { purpose: value };
+}
+function resolveHttpPdlss(input) {
+  const fromHeader = input.astraPurpose ? normalizePurposeHeader(input.astraPurpose) : void 0;
+  let action;
+  let actionSource;
+  if (input.routeAction) {
+    action = input.routeAction;
+    actionSource = "route_config";
+  } else if (input.hasCustomActionExtractor && input.customAction) {
+    action = input.customAction;
+    actionSource = "custom_extractor";
+  } else if (!input.hasCustomActionExtractor && input.astraAction) {
+    action = input.astraAction;
+    actionSource = "header";
+  } else if (!input.hasCustomActionExtractor && fromHeader?.actionCandidate) {
+    action = fromHeader.actionCandidate;
+    actionSource = "purpose_header_derived";
+  } else {
+    action = actionForHttpMethod(input.method);
+    actionSource = "method_table";
+  }
+  let purpose;
+  let purposeSource;
+  if (input.routePurpose) {
+    purpose = input.routePurpose;
+    purposeSource = "route_config";
+  } else if (input.hasCustomPurposeExtractor) {
+    if (input.customPurpose) {
+      purpose = input.customPurpose;
+      purposeSource = "custom_extractor";
+    }
+  } else if (fromHeader) {
+    purpose = fromHeader.purpose;
+    purposeSource = "header";
+  } else if (input.legacyPurpose) {
+    purpose = input.legacyPurpose;
+    purposeSource = "legacy_header";
+  } else if (input.queryPurpose) {
+    purpose = input.queryPurpose;
+    purposeSource = "query";
+  }
+  if (!purpose) {
+    const dot = action.indexOf(".");
+    if (dot > 0) {
+      purpose = action.slice(0, dot);
+      purposeSource = "action_derived";
+    } else {
+      purpose = DEFAULT_HTTP_PURPOSE;
+      purposeSource = "transport_default";
+    }
+  }
+  return { purpose, action, purposeSource, actionSource };
+}
+
 // src/pdlss-pre-check.ts
 function performCounterpartyPreCheck(routeConfig, astraCreds, purpose) {
   const failures = [];
@@ -651,33 +722,25 @@ function defaultExtractCredentials(req) {
 function extractAstraSyncCredentials(req) {
   return extractHttpCredentials(req.headers);
 }
-function defaultExtractPurpose(req) {
-  const astraPurpose = req.headers["x-astra-purpose"];
-  if (astraPurpose) {
-    const value = Array.isArray(astraPurpose) ? astraPurpose[0] : astraPurpose;
-    const category = value.split(":")[0];
-    return category;
-  }
-  const purposeHeader = req.headers["x-purpose"] || req.headers["X-Purpose"];
-  if (purposeHeader) {
-    return Array.isArray(purposeHeader) ? purposeHeader[0] : purposeHeader;
-  }
-  if (req.query.purpose && typeof req.query.purpose === "string") {
-    return req.query.purpose;
-  }
-  switch (req.method) {
-    case "GET":
-      return "read_data";
-    case "POST":
-      return "write_data";
-    case "PUT":
-    case "PATCH":
-      return "write_data";
-    case "DELETE":
-      return "delete_data";
-    default:
-      return "general";
-  }
+function headerValue(value) {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value[0];
+  return void 0;
+}
+function resolveRequestPdlss(req, routeConfig, customExtractPurpose, customExtractAction) {
+  return resolveHttpPdlss({
+    method: req.method,
+    astraPurpose: headerValue(req.headers["x-astra-purpose"]),
+    astraAction: headerValue(req.headers["x-astra-action"]),
+    legacyPurpose: headerValue(req.headers["x-purpose"] ?? req.headers["X-Purpose"]),
+    queryPurpose: typeof req.query.purpose === "string" ? req.query.purpose : void 0,
+    routePurpose: routeConfig?.purpose,
+    routeAction: routeConfig?.action,
+    hasCustomPurposeExtractor: !!customExtractPurpose,
+    customPurpose: customExtractPurpose?.(req),
+    hasCustomActionExtractor: !!customExtractAction,
+    customAction: customExtractAction?.(req)
+  });
 }
 function matchRoute(pattern, path, opts) {
   const regexPattern = pattern.replace(/\*/g, ".*").replace(/\//g, "\\/");
@@ -737,6 +800,7 @@ function createMiddleware(options) {
   const {
     extractCredentials: customExtractCredentials,
     extractPurpose: customExtractPurpose,
+    extractAction: customExtractAction,
     skipPaths = [],
     onDenied = defaultOnDenied,
     recordDecisions,
@@ -822,7 +886,21 @@ function createMiddleware(options) {
         }
         return next();
       }
-      const purpose = customExtractPurpose ? customExtractPurpose(req) : defaultExtractPurpose(req);
+      const pdlssPair = resolveRequestPdlss(
+        req,
+        routeConfig,
+        customExtractPurpose,
+        customExtractAction
+      );
+      const purpose = pdlssPair.purpose;
+      if (config.debug) {
+        console.debug("[express-middleware] pdlss resolved", {
+          purpose_source: pdlssPair.purposeSource,
+          resolved_purpose: pdlssPair.purpose,
+          action_source: pdlssPair.actionSource,
+          resolved_action: pdlssPair.action
+        });
+      }
       const astraCreds = extractAstraSyncCredentials(req);
       const counterpartyUrl = config.counterpartyUrl || `${req.protocol}://${req.get("host")}`;
       const preCheckFailures = performCounterpartyPreCheck(routeConfig, astraCreds, purpose);
@@ -866,10 +944,7 @@ function createMiddleware(options) {
       const result = await verify(config, {
         credentials,
         purpose,
-        // RFC 7230 § 3.1.1 — HTTP method tokens uppercase by IANA convention.
-        // Backend evaluator tolerates either case as defense-in-depth
-        // (round-18.6 batch 2); SDK emits canonical form.
-        action: req.method.toUpperCase(),
+        action: pdlssPair.action,
         resource: req.path,
         createSession: shouldRecordDecisions,
         counterpartyUrl,
@@ -907,35 +982,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];