@astrasyncai/verification-gateway 2.1.0 → 2.2.3

package/README.md

@@ -2,6 +2,18 @@
 
 Universal Verification Gateway for AstraSync KYA Platform - verify AI agents across any counterparty type.
 
+## Which package do I install?
+
+AstraSync ships two npm packages with deliberately distinct roles. Pick by who you are, not by what you're building:
+
+| You are…                                                                                      | Install                                                       | Use it for                                                                                                               |
+| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| **A merchant / counterparty** running an API, MCP server, or website that AI agents call into | `@astrasyncai/verification-gateway` (this package)            | Verifying inbound agents before they hit your endpoint. Express + Next.js middleware, Commerce Shield, webhook verifier. |
+| **An agent author** building an AI agent that calls out to other people's services            | `@astrasyncai/sdk` (the agent-side SDK on npm, separate repo) | Registering your agent with AstraSync, attaching credentials to outbound HTTP / MCP / A2A calls, KYD onboarding.         |
+| **A platform / orchestrator** doing both ends in one place                                    | Both                                                          | The two roles compose: each side's flow is independent.                                                                  |
+
+> Both packages talk to the same backend — `POST /agents/verify-access`. The contract is shared; the role is just which side you're sitting on.
+
 ## Overview
 
 The Verification Gateway provides a single, universal solution for verifying AI agents. One codebase, multiple deployment targets:
@@ -28,15 +40,17 @@ import { createMiddleware } from '@astrasyncai/verification-gateway/express';
 
 const app = express();
 
-app.use(createMiddleware({
-  apiBaseUrl: 'https://api.astrasync.ai',
-  routes: [
-    { pattern: '/api/public/*', method: '*', minAccessLevel: 'none' },
-    { pattern: '/api/data/*', method: 'GET', minAccessLevel: 'read-only' },
-    { pattern: '/api/data/*', method: '*', minAccessLevel: 'standard' },
-    { pattern: '/api/admin/*', method: '*', minAccessLevel: 'internal' },
-  ],
-}));
+app.use(
+  createMiddleware({
+    apiBaseUrl: 'https://astrasync.ai/api',
+    routes: [
+      { pattern: '/api/public/*', method: '*', minAccessLevel: 'none' },
+      { pattern: '/api/data/*', method: 'GET', minAccessLevel: 'read-only' },
+      { pattern: '/api/data/*', method: '*', minAccessLevel: 'standard' },
+      { pattern: '/api/admin/*', method: '*', minAccessLevel: 'internal' },
+    ],
+  })
+);
 ```
 
 ### Next.js Middleware
@@ -82,23 +96,23 @@ if (result.verified && result.accessLevel !== 'none') {
 
 ## Access Levels
 
-| Level | Description |
-|-------|-------------|
-| `none` | No credentials provided |
-| `guidance` | Commerce Shield overlay shown |
-| `read-only` | Can browse, no mutations |
-| `standard` | Normal access per PDLSS |
-| `full` | Full access for high-trust agents |
-| `internal` | Organization member access |
+| Level       | Description                       |
+| ----------- | --------------------------------- |
+| `none`      | No credentials provided           |
+| `guidance`  | Commerce Shield overlay shown     |
+| `read-only` | Can browse, no mutations          |
+| `standard`  | Normal access per PDLSS           |
+| `full`      | Full access for high-trust agents |
+| `internal`  | Organization member access        |
 
 ## Trust Levels
 
-| Level | Score Range |
-|-------|-------------|
-| BRONZE | 0-39 |
-| SILVER | 40-59 |
-| GOLD | 60-79 |
-| PLATINUM | 80-100 |
+| Level    | Score Range |
+| -------- | ----------- |
+| BRONZE   | 0-39        |
+| SILVER   | 40-59       |
+| GOLD     | 60-79       |
+| PLATINUM | 80-100      |
 
 ## UI Components
 
@@ -184,16 +198,36 @@ interface VerificationResult {
 
 ```typescript
 interface GatewayConfig {
-  // Required
+  // Required. Always include the /api path prefix — for prod use
+  // 'https://astrasync.ai/api', for staging 'https://staging.astrasync.ai/api'.
   apiBaseUrl: string;
 
   // Optional
-  apiKey?: string;              // For authenticated requests
-  defaultAccessLevel?: string;  // Default: 'guidance'
-  minTrustScore?: number;       // For 'standard' access (default: 40)
-  minTrustScoreForFull?: number; // For 'full' access (default: 70)
-  cacheTtl?: number;            // Cache duration in seconds (default: 300)
-  debug?: boolean;              // Enable debug logging
+  apiKey?: string; // For authenticated requests
+  defaultAccessLevel?: string; // Default: 'guidance'
+  cacheTtl?: number; // Cache duration in seconds (default: 300)
+  debug?: boolean; // Enable debug logging
+
+  // Counterparty attribution (v2.2.3+)
+  counterpartyUrl?: string; // Sent with verify-access for analytics
+  counterpartyType?: 'agent' | 'api' | 'mcp_server' | 'website' | 'other' | 'unknown';
+  counterpartyId?: string; // Your ASTRAE-id (issued at endpoint registration);
+  // forwarded on every verify-access call so the server attributes traffic
+  // directly to this endpoint rather than resolving by URL.
+
+  // Init self-test (v2.2.3+) — fires a HEAD probe to verify-access on first
+  // call and warns if apiBaseUrl is pointing at HTML (catches the marketing-
+  // 404 case). Set true for tests where the extra request is undesirable.
+  disableInitChecks?: boolean;
+
+  // @deprecated — removed as functional config in v2.3.0. Server is the
+  // single source of truth for access-level decisions; the SDK reads
+  // access.accessLevel from the response verbatim. Setting these has no
+  // effect (a one-shot console.warn fires). To gate access to your
+  // endpoint, configure trust_score_requirement server-side via the
+  // /api/endpoints registration.
+  minTrustScore?: number;
+  minTrustScoreForFull?: number;
 }
 ```
 

package/dist/adapter-interface/interface.d.mts

@@ -1,6 +1,6 @@
 import { AstraSyncGateway } from '../gateway/gateway.mjs';
-import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-jJnPXStc.mjs';
-import '../types-CxQwJKbd.mjs';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-CgXPKUwi.mjs';
+import '../types-DOrqNMgy.mjs';
 
 /**
  * PlatformAdapter Interface

package/dist/adapter-interface/interface.d.ts

@@ -1,6 +1,6 @@
 import { AstraSyncGateway } from '../gateway/gateway.js';
-import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-79qS7aON.js';
-import '../types-CxQwJKbd.js';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-BYKAY6Cc.js';
+import '../types-DOrqNMgy.js';
 
 /**
  * PlatformAdapter Interface

package/dist/adapters/express.d.mts

@@ -1,3 +1,3 @@
 import 'express';
-import '../types-CxQwJKbd.mjs';
-export { c as createMiddleware, a as extractAstraSyncCredentials, r as requireAccess, v as verifyOnly } from '../express-CtwDIZyF.mjs';
+import '../types-DOrqNMgy.mjs';
+export { c as createMiddleware, a as extractAstraSyncCredentials, r as requireAccess, v as verifyOnly } from '../express-DgwpS8Ha.mjs';

package/dist/adapters/express.d.ts

@@ -1,3 +1,3 @@
 import 'express';
-import '../types-CxQwJKbd.js';
-export { c as createMiddleware, a as extractAstraSyncCredentials, r as requireAccess, v as verifyOnly } from '../express-Bcl-uBUE.js';
+import '../types-DOrqNMgy.js';
+export { c as createMiddleware, a as extractAstraSyncCredentials, r as requireAccess, v as verifyOnly } from '../express-BtKlLI8U.js';

package/dist/adapters/express.js

@@ -36,15 +36,6 @@ var ACCESS_LEVEL_HIERARCHY = {
   full: 4,
   internal: 5
 };
-var DEFAULT_TRUST_THRESHOLDS = {
-  none: 0,
-  guidance: 0,
-  "read-only": 20,
-  standard: 40,
-  full: 70,
-  internal: 0
-  // Internal is based on org membership, not score
-};
 function getTrustLevel(score) {
   if (score >= 80) return "PLATINUM";
   if (score >= 60) return "GOLD";
@@ -54,36 +45,39 @@ function getTrustLevel(score) {
 function hasMinimumAccess(actual, required) {
   return ACCESS_LEVEL_HIERARCHY[actual] >= ACCESS_LEVEL_HIERARCHY[required];
 }
-function getAccessLevelForScore(trustScore, thresholds = DEFAULT_TRUST_THRESHOLDS) {
-  if (trustScore >= thresholds.full) return "full";
-  if (trustScore >= thresholds.standard) return "standard";
-  if (trustScore >= thresholds["read-only"]) return "read-only";
-  return "guidance";
-}
-function determineAccessLevel(verified, trustScore, isOrgMember, customThresholds) {
-  if (!verified) {
-    return "guidance";
-  }
-  if (isOrgMember) {
-    return "internal";
-  }
-  const thresholds = {
-    ...DEFAULT_TRUST_THRESHOLDS,
-    ...customThresholds
-  };
-  return getAccessLevelForScore(trustScore, thresholds);
-}
 
 // src/verify.ts
 var DEFAULT_CONFIG = {
-  apiBaseUrl: "https://api.astrasync.ai",
+  apiBaseUrl: "https://astrasync.ai/api",
   defaultAccessLevel: "guidance",
-  minTrustScore: 40,
-  minTrustScoreForFull: 70,
+  // minTrustScore + minTrustScoreForFull deprecated in v2.3.0 — server decides.
   cacheTtl: 300,
   // 5 minutes
   debug: false
 };
+var initCheckPerformed = false;
+var deprecationWarningShown = false;
+async function performInitCheck(apiBaseUrl, debug) {
+  initCheckPerformed = true;
+  try {
+    const probeUrl = `${apiBaseUrl}/agents/verify-access`;
+    const response = await fetch(probeUrl, { method: "HEAD" });
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.startsWith("text/html")) {
+      console.warn(
+        `[VerificationGateway] apiBaseUrl '${apiBaseUrl}' returned HTML (content-type: ${contentType}). This usually means apiBaseUrl is pointing at a marketing site instead of the API. Expected: 'https://astrasync.ai/api' (prod) or 'https://staging.astrasync.ai/api' (staging). Set disableInitChecks: true on GatewayConfig to silence this warning.`
+      );
+    } else if (debug) {
+      console.log(
+        `[VerificationGateway] init check passed for ${apiBaseUrl} (content-type: ${contentType})`
+      );
+    }
+  } catch (err) {
+    if (debug) {
+      console.log(`[VerificationGateway] init check failed (non-blocking): ${String(err)}`);
+    }
+  }
+}
 var verificationCache = /* @__PURE__ */ new Map();
 function getCacheKey(credentials) {
   return `${credentials.astraId || ""}-${credentials.apiKey || ""}-${credentials.jwt || ""}`;
@@ -108,7 +102,7 @@ function cacheResult(credentials, result, ttlSeconds) {
 }
 function extractCredentials(headers, query) {
   const credentials = {};
-  const astraIdHeader = headers["x-astra-id"] || headers["X-Astra-Id"] || headers["X-ASTRA-ID"];
+  const astraIdHeader = headers["x-astra-id"] || headers["X-Astra-Id"] || headers["X-ASTRA-ID"] || headers["x-astra-agentid"] || headers["X-Astra-AgentId"] || headers["x-astra-agent-id"] || headers["X-Astra-Agent-Id"] || headers["X-ASTRA-AGENT-ID"];
   if (astraIdHeader) {
     credentials.astraId = Array.isArray(astraIdHeader) ? astraIdHeader[0] : astraIdHeader;
   }
@@ -134,9 +128,6 @@ function extractCredentials(headers, query) {
   }
   return credentials;
 }
-function hasCredentials(credentials) {
-  return !!(credentials.astraId || credentials.apiKey || credentials.jwt);
-}
 function createGuidanceResponse(config, reason) {
   const guidance = {
     message: "This service verifies AI agents before granting access. Please register your agent with AstraSync.",
@@ -160,7 +151,7 @@ function createGuidanceResponse(config, reason) {
 async function callVerifyAccessAPI(config, request) {
   const { credentials, ...requestData } = request;
   const body = {
-    agentId: credentials.astraId,
+    ...credentials.astraId && { agentId: credentials.astraId },
     purpose: requestData.purpose || "general"
   };
   if (requestData.action) body.action = requestData.action;
@@ -172,21 +163,34 @@ async function callVerifyAccessAPI(config, request) {
   if (requestData.isSubAgentRequest) body.isSubAgentRequest = requestData.isSubAgentRequest;
   if (requestData.parentAgentId) body.parentAgentId = requestData.parentAgentId;
   if (requestData.subAgentDepth !== void 0) body.subAgentDepth = requestData.subAgentDepth;
-  if (requestData.enableRuntimeChallenge) body.enableRuntimeChallenge = requestData.enableRuntimeChallenge;
+  if (requestData.enableRuntimeChallenge)
+    body.enableRuntimeChallenge = requestData.enableRuntimeChallenge;
   if (requestData.createSession) body.createSession = requestData.createSession;
   if (requestData.durationRequired) body.durationRequired = requestData.durationRequired;
   if (requestData.counterpartyType) body.counterpartyType = requestData.counterpartyType;
   if (requestData.counterpartyUrl) body.counterpartyUrl = requestData.counterpartyUrl;
-  if (requestData.runtimeChallengeOptions) body.runtimeChallengeOptions = requestData.runtimeChallengeOptions;
+  if (config.counterpartyId) body.counterpartyId = config.counterpartyId;
+  if (requestData.runtimeChallengeOptions)
+    body.runtimeChallengeOptions = requestData.runtimeChallengeOptions;
+  if (requestData.callerMetadata || requestData.clientIp || requestData.userAgent) {
+    const meta = {
+      ...requestData.clientIp && { sourceIp: requestData.clientIp },
+      ...requestData.userAgent && { userAgent: requestData.userAgent },
+      ...requestData.callerMetadata
+    };
+    if (Object.keys(meta).length > 0) body.callerMetadata = meta;
+  }
   const headers = {
     "Content-Type": "application/json",
     ...config.customHeaders
   };
-  if (config.apiKey) {
-    headers["X-API-Key"] = config.apiKey;
-  }
   if (credentials.authorizationHeader) {
     headers["Authorization"] = credentials.authorizationHeader;
+  } else if (config.apiKey) {
+    headers["Authorization"] = `Bearer ${config.apiKey}`;
+  }
+  if (config.apiKey) {
+    headers["X-API-Key"] = config.apiKey;
   }
   try {
     const response = await fetch(`${config.apiBaseUrl}/agents/verify-access`, {
@@ -212,8 +216,14 @@ async function callVerifyAccessAPI(config, request) {
 }
 async function verify(config, request) {
   const mergedConfig = { ...DEFAULT_CONFIG, ...config };
-  if (!hasCredentials(request.credentials)) {
-    return createGuidanceResponse(mergedConfig, "No agent credentials provided");
+  if (!initCheckPerformed && !mergedConfig.disableInitChecks && mergedConfig.apiBaseUrl) {
+    void performInitCheck(mergedConfig.apiBaseUrl, mergedConfig.debug);
+  }
+  if (!deprecationWarningShown && (config.minTrustScore !== void 0 || config.minTrustScoreForFull !== void 0)) {
+    deprecationWarningShown = true;
+    console.warn(
+      "[VerificationGateway] minTrustScore / minTrustScoreForFull are deprecated in v2.3.0 and have no effect. Server is now the single source of truth for access-level decisions (the SDK reads access.accessLevel from the verify-access response). To gate access to an endpoint, configure the endpoint's trust_score_requirement server-side."
+    );
   }
   if (mergedConfig.cacheTtl && mergedConfig.cacheTtl > 0) {
     const cached = getCachedResult(request.credentials);
@@ -285,18 +295,7 @@ async function verify(config, request) {
     selfInstantiationAllowed: apiResponse.access.pdlss.selfInstantiationAllowed,
     appliedPolicy: apiResponse.access.appliedPolicy
   } : void 0;
-  const trustScore = agent?.trustScore || 0;
-  const isOrgMember = false;
-  const accessLevel = determineAccessLevel(
-    true,
-    trustScore,
-    isOrgMember,
-    {
-      "read-only": 20,
-      standard: mergedConfig.minTrustScore || 40,
-      full: mergedConfig.minTrustScoreForFull || 70
-    }
-  );
+  const accessLevel = apiResponse.access?.accessLevel ?? "standard";
   const result = {
     verified: true,
     accessLevel,
@@ -318,7 +317,9 @@ async function verify(config, request) {
   if (result.recommendation === "deny") {
     result.verified = false;
     result.accessLevel = "none";
-    result.denialReasons = result.recommendationReasons || ["Access denied by AstraSync recommendation"];
+    result.denialReasons = result.recommendationReasons || [
+      "Access denied by AstraSync recommendation"
+    ];
     if (result.runtimeChallenge) {
       result.guidance = {
         message: `Verification failed: ${result.runtimeChallenge.reason || "runtime challenge failed"}`,
@@ -340,7 +341,10 @@ async function verify(config, request) {
 }
 async function recordDecision(config, sessionId, decision, reason) {
   const headers = { "Content-Type": "application/json" };
-  if (config.apiKey) headers["X-API-Key"] = config.apiKey;
+  if (config.apiKey) {
+    headers["Authorization"] = `Bearer ${config.apiKey}`;
+    headers["X-API-Key"] = config.apiKey;
+  }
   await fetch(`${config.apiBaseUrl}/agents/verify-access/${sessionId}/decision`, {
     method: "POST",
     headers,
@@ -348,15 +352,6 @@ async function recordDecision(config, sessionId, decision, reason) {
   }).catch(() => {
   });
 }
-async function reportUnregisteredAttempt(config, data) {
-  const apiBaseUrl = config.apiBaseUrl || DEFAULT_CONFIG.apiBaseUrl;
-  await fetch(`${apiBaseUrl}/verification-activity/unregistered-attempt`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(data)
-  }).catch(() => {
-  });
-}
 async function reportCounterpartyPreCheckFailure(config, data) {
   const apiBaseUrl = config.apiBaseUrl || DEFAULT_CONFIG.apiBaseUrl;
   await fetch(`${apiBaseUrl}/verification-activity/counterparty-pre-check-failure`, {
@@ -541,32 +536,6 @@ function createMiddleware(options) {
         return next();
       }
       const credentials = customExtractCredentials ? customExtractCredentials(req) : defaultExtractCredentials(req);
-      if (!hasCredentials(credentials) && routeConfig.minAccessLevel !== "guidance") {
-        const counterpartyUrl2 = config.counterpartyUrl || `${req.protocol}://${req.get("host")}`;
-        reportUnregisteredAttempt(config, {
-          counterpartyUrl: counterpartyUrl2,
-          counterpartyType: config.counterpartyType || "api",
-          sourceIp: req.ip,
-          userAgent: req.headers["user-agent"],
-          requestPath: req.path,
-          requestMethod: req.method
-        }).catch(() => {
-        });
-        const result2 = {
-          verified: false,
-          accessLevel: "none",
-          denialReasons: ["No agent credentials provided"],
-          guidance: {
-            message: "This endpoint requires agent verification. Please provide your ASTRA-ID.",
-            registrationUrl: `${config.apiBaseUrl?.replace("/api", "")}/register`,
-            documentationUrl: `${config.apiBaseUrl?.replace("/api", "")}/docs/agent-access`
-          },
-          verifiedAt: /* @__PURE__ */ new Date()
-        };
-        req.agentVerification = result2;
-        onDenied(result2, req, res);
-        return;
-      }
       const purpose = customExtractPurpose ? customExtractPurpose(req) : defaultExtractPurpose(req);
       const astraCreds = extractAstraSyncCredentials(req);
       const counterpartyUrl = config.counterpartyUrl || `${req.protocol}://${req.get("host")}`;
@@ -597,18 +566,28 @@ function createMiddleware(options) {
         return;
       }
       const shouldRecordDecisions = recordDecisions !== false;
+      const forwardedFor = req.headers["x-forwarded-for"];
+      const forwardedForStr = Array.isArray(forwardedFor) ? forwardedFor.join(", ") : forwardedFor;
+      const originalClientIp = forwardedForStr ? forwardedForStr.split(",")[0].trim() : req.ip;
+      const agentCardUrl = typeof req.headers["x-astrasync-agent-card"] === "string" ? req.headers["x-astrasync-agent-card"] : void 0;
       const result = await verify(config, {
         credentials,
         purpose,
         action: req.method.toLowerCase(),
         resource: req.path,
-        clientIp: req.ip,
-        userAgent: req.headers["user-agent"],
         createSession: shouldRecordDecisions,
         counterpartyUrl,
         counterpartyType: config.counterpartyType || "api",
         enableRuntimeChallenge,
-        durationRequired: astraCreds?.pdlss?.duration?.maxSessionDuration
+        durationRequired: astraCreds?.pdlss?.duration?.maxSessionDuration,
+        callerMetadata: {
+          sourceIp: originalClientIp,
+          userAgent: req.headers["user-agent"],
+          referer: req.headers.referer,
+          host: req.headers.host,
+          forwardedFor: forwardedForStr,
+          agentCardUrl
+        }
       });
       req.agentVerification = result;
       const sessionId = result.sessionId;