@astrasyncai/verification-gateway 2.5.1 → 3.1.0

package/dist/index.mjs

@@ -126,7 +126,7 @@ function getCapabilities(accessLevel) {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.4.13";
+var SDK_VERSION = "3.1.0";
 
 // src/well-known.ts
 var CACHE_TTL_MS = 60 * 60 * 1e3;
@@ -721,6 +721,9 @@ function setHttpHeaders(headers, credentials) {
   if (credentials.pdlss?.purpose) {
     const purposeValue = credentials.pdlss.purpose.action ? `${credentials.pdlss.purpose.category}:${credentials.pdlss.purpose.action}` : credentials.pdlss.purpose.category;
     result[`${HEADER_PREFIX}Purpose`] = purposeValue;
+    if (credentials.pdlss.purpose.action) {
+      result[`${HEADER_PREFIX}Action`] = credentials.pdlss.purpose.action;
+    }
   }
   if (credentials.pdlss?.duration?.maxSessionDuration) {
     result[`${HEADER_PREFIX}Duration`] = String(credentials.pdlss.duration.maxSessionDuration);
@@ -750,6 +753,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 = {
@@ -767,6 +777,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 = [];
@@ -825,33 +914,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, "\\/");
@@ -911,6 +992,7 @@ function createMiddleware(options) {
   const {
     extractCredentials: customExtractCredentials,
     extractPurpose: customExtractPurpose,
+    extractAction: customExtractAction,
     skipPaths = [],
     onDenied = defaultOnDenied,
     recordDecisions,
@@ -996,7 +1078,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);
@@ -1040,10 +1136,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,
@@ -1241,28 +1334,15 @@ function extractAstraSyncCredentialsFromNextRequest(request) {
   });
   return extractHttpCredentials(headers);
 }
-function extractPurpose(request) {
-  const astraPurpose = request.headers.get("x-astra-purpose");
-  if (astraPurpose) {
-    return astraPurpose.split(":")[0];
-  }
-  const purposeHeader = request.headers.get("x-purpose");
-  if (purposeHeader) {
-    return purposeHeader;
-  }
-  switch (request.method.toUpperCase()) {
-    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 resolveNextPdlss(request, routeConfig) {
+  return resolveHttpPdlss({
+    method: request.method,
+    astraPurpose: request.headers.get("x-astra-purpose") ?? void 0,
+    astraAction: request.headers.get("x-astra-action") ?? void 0,
+    legacyPurpose: request.headers.get("x-purpose") ?? void 0,
+    routePurpose: routeConfig?.purpose,
+    routeAction: routeConfig?.action
+  });
 }
 function generateCommerceShieldHtml(result, options) {
   const title = escapeHtml(options.commerceShield?.title || "AstraSync Agent Verification");
@@ -1475,7 +1555,16 @@ function createMiddleware2(options) {
     }
     const credentials = extractCredentialsFromNextRequest(request);
     const counterpartyUrl = config.counterpartyUrl || request.nextUrl.origin;
-    const purpose = extractPurpose(request);
+    const pdlssPair = resolveNextPdlss(request, routeConfig);
+    const purpose = pdlssPair.purpose;
+    if (config.debug) {
+      console.debug("[nextjs-middleware] pdlss resolved", {
+        purpose_source: pdlssPair.purposeSource,
+        resolved_purpose: pdlssPair.purpose,
+        action_source: pdlssPair.actionSource,
+        resolved_action: pdlssPair.action
+      });
+    }
     const astraCreds = extractAstraSyncCredentialsFromNextRequest(request);
     const preCheckFailures = performCounterpartyPreCheck(routeConfig, astraCreds, purpose);
     if (preCheckFailures.length > 0) {
@@ -1529,10 +1618,7 @@ function createMiddleware2(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: request.method.toUpperCase(),
+      action: pdlssPair.action,
       resource: pathname,
       counterpartyUrl,
       counterpartyType: config.counterpartyType || "website",
@@ -3287,9 +3373,9 @@ function toBuf(bytes) {
   new Uint8Array(out).set(bytes);
   return out;
 }
-function checkTimestamp(headerValue, toleranceSec, nowFn) {
-  if (!headerValue) return { ok: false, error: "missing Timestamp header" };
-  const ts = parseTimestamp(headerValue);
+function checkTimestamp(headerValue2, toleranceSec, nowFn) {
+  if (!headerValue2) return { ok: false, error: "missing Timestamp header" };
+  const ts = parseTimestamp(headerValue2);
   if (ts === null) return { ok: false, error: "unparseable Timestamp header" };
   const now = nowFn ? nowFn() : Math.floor(Date.now() / 1e3);
   if (Math.abs(now - ts) > toleranceSec) {
@@ -3524,14 +3610,14 @@ import {
 } from "@x402/core/schemas";
 import { safeBase64Decode } from "@x402/core/utils";
 function extractX402FromRequest(request) {
-  const headerValue = readHeader4(request.headers, "x-payment");
+  const headerValue2 = readHeader4(request.headers, "x-payment");
   if (request.body && typeof request.body === "object") {
     const parsed = tryParsePayload(request.body);
     if (parsed) return buildPayloadContext(parsed, "body");
   }
-  if (headerValue) {
+  if (headerValue2) {
     try {
-      const decoded = safeBase64Decode(headerValue);
+      const decoded = safeBase64Decode(headerValue2);
       if (decoded) {
         const json = JSON.parse(decoded);
         const parsed = tryParsePayload(json);
@@ -3554,10 +3640,10 @@ function extractX402FromResponse(response) {
     const parsed = tryParseRequired(response.body);
     if (parsed) return buildRequiredContext(parsed, "body");
   }
-  const headerValue = readHeader4(response.headers, "x-payment-required");
-  if (headerValue) {
+  const headerValue2 = readHeader4(response.headers, "x-payment-required");
+  if (headerValue2) {
     try {
-      const decoded = safeBase64Decode(headerValue);
+      const decoded = safeBase64Decode(headerValue2);
       if (decoded) {
         const json = JSON.parse(decoded);
         const parsed = tryParseRequired(json);
@@ -4393,7 +4479,10 @@ function mcpToPdlss(parsed, requestPath, headerPurpose, headerAction, toolGate)
   }
   let action;
   let actionSource;
-  if (headerAction) {
+  if (toolGate?.action !== void 0) {
+    action = toolGate.action;
+    actionSource = "tool_gate";
+  } else if (headerAction) {
     action = headerAction;
     actionSource = "header";
   } else if (parsed.actionFromBody && parsed.actionSourceFromBody) {
@@ -4567,7 +4656,7 @@ function createMcpMiddleware(options) {
         req.path,
         headerPurpose,
         headerAction,
-        gate ? { purpose: gate.purpose, resource: gate.resource } : void 0
+        gate ? { purpose: gate.purpose, action: gate.action, resource: gate.resource } : void 0
       );
       if (config.debug) {
         console.debug("[mcp-middleware] pdlss resolved", {
@@ -5068,7 +5157,10 @@ function buildGuidance(params) {
     message,
     guidance: {
       message: "Register either with an agent-scoped API key (the recommended credentialed path) OR, if you hold no credentials, via the owner's email using request_registration. Never send a password or private key over the wire.",
-      registrationUrl: `${origin}/agents/register`,
+      // 3.0.0: registrationUrl is the agent-actionable KEYLESS endpoint, not the
+      // human dashboard `/agents/register` (an auth-walled page an agent can't
+      // use). documentationUrl carries the machine-readable contract.
+      registrationUrl: `${origin}/api/agents/request-registration`,
       documentationUrl: `${origin}${docsPath.startsWith("/") ? docsPath : `/${docsPath}`}`,
       steps: [
         "Credentialed path (recommended): have your human mint an agent-scoped API key at Settings \u2192 API Keys, then re-call register_agent with apiKey set. An agent holding its own scoped kya_ key is fine and intended.",