@astrasyncai/verification-gateway 2.3.7 → 2.3.9

package/README.md

@@ -40,15 +40,16 @@ import { createMiddleware } from '@astrasyncai/verification-gateway/express';
 
 const app = express();
 
+// v2.3.7+ — per-route policy lives in the AstraSync dashboard.
+// The SDK fetches it on init via counterpartyId; do NOT pass routes here.
 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' },
-    ],
+    apiKey: process.env.ASTRASYNC_API_KEY,
+    counterpartyId: 'ASTRAE-...', // your endpoint id from the dashboard
+    setPassThroughHeader: true, // recommended for local-dev / staging
+    // — surfaces pass-through mode when
+    // no per-route policy is configured
   })
 );
 ```
@@ -59,13 +60,13 @@ app.use(
 // middleware.ts
 import { createMiddleware } from '@astrasyncai/verification-gateway/nextjs';
 
+// v2.3.7+ — per-route policy lives in the AstraSync dashboard.
+// The SDK fetches it on init via counterpartyId; do NOT pass routes here.
 export const middleware = createMiddleware({
   apiBaseUrl: 'https://api.astrasync.ai',
+  apiKey: process.env.ASTRASYNC_API_KEY,
+  counterpartyId: 'ASTRAE-...',
   showCommerceShield: true,
-  routes: [
-    { pattern: '/api/*', method: '*', minAccessLevel: 'standard' },
-    { pattern: '/dashboard/*', method: '*', minAccessLevel: 'read-only' },
-  ],
 });
 
 export const config = {
@@ -94,6 +95,88 @@ if (result.verified && result.accessLevel !== 'none') {
 }
 ```
 
+### Inner-hop verification (MCP → REST dedupe with X-Astra-Verified-Hop)
+
+When an MCP tool calls an inner REST endpoint that ALSO runs the
+verification gateway, two verify-access calls fire for the same agent in
+the same logical request — audit gets noisy and you pay a doubled
+round-trip. The `X-Astra-Verified-Hop` header marks the inner hop as
+already-verified by the upstream so the inner middleware skips a
+redundant verify-access call.
+
+The MCP middleware emits the marker automatically on its outbound
+response. Tool handlers calling inner REST hops need to forward it on
+outgoing fetches; the inner middleware reads it via `parseVerifiedHop` +
+`isVerifiedHopValidFor` and skips a duplicate verify-access if the
+marker is fresh AND matches the agent claimed on the inner hop.
+
+**Worked example — upstream MCP → inner REST hop:**
+
+```typescript
+// === outer MCP server ===
+import express from 'express';
+import { createMcpMiddleware } from '@astrasyncai/verification-gateway/mcp';
+
+const mcp = express();
+mcp.use(express.json());
+mcp.use(
+  createMcpMiddleware({
+    apiBaseUrl: 'https://astrasync.ai/api',
+    apiKey: process.env.ASTRASYNC_API_KEY,
+    counterpartyId: 'ASTRAE-mcp...',
+    toolGates: { start_checkout: 'standard' },
+  })
+);
+
+// MCP middleware sets X-Astra-Verified-Hop on the response automatically
+// AND populates req.agentVerification. Tool handlers can read both.
+mcp.post('/mcp', async (req, res) => {
+  const v = req.agentVerification!;
+  // Forward the verified-hop marker on outgoing inner-hop calls.
+  // Build it from the same fields the middleware uses on the response.
+  const { serializeVerifiedHop, MCP_VERIFIED_HOP_HEADER } =
+    await import('@astrasyncai/verification-gateway/mcp');
+  const hop = serializeVerifiedHop({
+    astraId: v.agent!.astraId,
+    sessionId: v.sessionId,
+    checkedAt: Date.now(),
+  });
+
+  const inner = await fetch('http://internal/api/checkout/items', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Astra-Id': v.agent!.astraId, // identity marker
+      [MCP_VERIFIED_HOP_HEADER]: hop, // verified-hop dedupe marker
+    },
+    body: JSON.stringify({ sku: 'sku_42' }),
+  });
+  res.status(inner.status).json(await inner.json());
+});
+
+// === inner REST hop (same fleet) ===
+import { createMiddleware } from '@astrasyncai/verification-gateway/express';
+
+const rest = express();
+rest.use(
+  createMiddleware({
+    apiBaseUrl: 'https://astrasync.ai/api',
+    apiKey: process.env.ASTRASYNC_API_KEY,
+    counterpartyId: 'ASTRAE-rest...',
+    trustVerifiedHop: true, // accept the dedupe marker
+    verifiedHopMaxAgeMs: 60_000, // 60s default; tighten for high-stakes
+  })
+);
+// Inner middleware reads X-Astra-Verified-Hop, validates via
+// parseVerifiedHop + isVerifiedHopValidFor, and skips verify-access
+// when the marker is fresh AND its astraId matches the X-Astra-Id on
+// this request.
+```
+
+**Important:** the marker is NOT proof of identity by itself — pair it
+with `X-Astra-Id` so the inner middleware can verify the marker matches
+the claimed agent. The marker only gates the dedupe-skip decision.
+
 ## Access Levels
 
 | Level       | Description                       |

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-DxY5zt4z.mjs';
-import '../types-Bxqj1sKY.mjs';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-CKafuHDn.mjs';
+import '../types-UYT4GdPW.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-BecRpozv.js';
-import '../types-Bxqj1sKY.js';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-ppkhdldJ.js';
+import '../types-UYT4GdPW.js';
 
 /**
  * PlatformAdapter Interface

package/dist/adapters/express.d.mts

@@ -1,3 +1,3 @@
 import 'express';
-import '../types-Bxqj1sKY.mjs';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-D9oRsseg.mjs';
+import '../types-UYT4GdPW.mjs';
+export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-BiB51d5t.mjs';

package/dist/adapters/express.d.ts

@@ -1,3 +1,3 @@
 import 'express';
-import '../types-Bxqj1sKY.js';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-DMSIl20m.js';
+import '../types-UYT4GdPW.js';
+export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-D6tEDU08.js';

package/dist/adapters/express.js

@@ -28,7 +28,7 @@ module.exports = __toCommonJS(express_exports);
 // src/access-levels.ts
 var ACCESS_LEVEL_HIERARCHY = {
   none: 0,
-  guidance: 1,
+  restricted: 1,
   "read-only": 2,
   standard: 3,
   full: 4,
@@ -47,7 +47,11 @@ function hasMinimumAccess(actual, required) {
 // src/verify.ts
 var DEFAULT_CONFIG = {
   apiBaseUrl: "https://astrasync.ai/api",
-  defaultAccessLevel: "guidance",
+  // v2.3.9 (defect #30): default for unconfigured callers is `'none'` (no
+  // access). Pre-rename this defaulted to `'guidance'`, which combined with
+  // a route gated at `'guidance'` to silently let unverified traffic
+  // through (`hasMinimumAccess('guidance', 'guidance') === true`).
+  defaultAccessLevel: "none",
   // minTrustScore + minTrustScoreForFull deprecated in v2.3.0 — server decides.
   cacheTtl: 300,
   // 5 minutes
@@ -140,7 +144,12 @@ function createGuidanceResponse(config, reason) {
   };
   return {
     verified: false,
-    accessLevel: "guidance",
+    // v2.3.9 (defect #30): denials grant `'none'`, NEVER a positive band.
+    // Adapters additionally short-circuit on `verified === false` before
+    // the gate check, but the access level still has to be honest at the
+    // data layer so downstream consumers (SDK adapters in other languages,
+    // custom integrations) inherit the correct semantics.
+    accessLevel: "none",
     guidance,
     denialReasons: reason ? [reason] : ["No valid agent credentials provided"],
     verifiedAt: /* @__PURE__ */ new Date()
@@ -197,6 +206,23 @@ async function callVerifyAccessAPI(config, request) {
       body: JSON.stringify(body)
     });
     const data = await response.json();
+    if (response.status === 410) {
+      return {
+        success: true,
+        access: {
+          allowed: false,
+          accessLevel: "none",
+          reason: "endpoint_deactivated",
+          failures: [
+            {
+              dimension: "endpoint.deactivated",
+              message: typeof data?.message === "string" ? data.message : "Endpoint has been deactivated",
+              guidance: typeof data?.guidance === "string" ? data.guidance : "Reactivate via POST /api/endpoints/{id}/reactivate, or update the URL on the calling agent."
+            }
+          ]
+        }
+      };
+    }
     if (!response.ok) {
       return {
         success: false,
@@ -250,7 +276,14 @@ async function verify(config, request) {
     const aggregatedFailures = apiResponse.access?.failures;
     const result2 = {
       verified: false,
-      accessLevel: "guidance",
+      // v2.3.9 (defect #30): denials grant `'none'`, NEVER a positive band.
+      // Pre-rename this hardcoded `'guidance'`, which conflated with the
+      // colocated `guidance: {...}` help-payload object below and let
+      // denied requests pass any route gated at `'guidance'` because
+      // `hasMinimumAccess('guidance', 'guidance') === true`. Adapters now
+      // ALSO short-circuit on `verified === false` before the gate check —
+      // belt-and-braces.
+      accessLevel: "none",
       denialReasons: aggregatedFailures && aggregatedFailures.length > 0 ? aggregatedFailures.map((f) => f.message) : apiResponse.access?.reason ? [apiResponse.access.reason] : ["Access denied"],
       failures: aggregatedFailures,
       requiresStepUp: apiResponse.access?.requiresStepUp,
@@ -306,7 +339,8 @@ async function verify(config, request) {
     runtimeChallenge: apiResponse.runtimeChallenge,
     tokenGuidance: apiResponse.tokenGuidance,
     recommendation: apiResponse.recommendation,
-    recommendationReasons: apiResponse.recommendationReasons
+    recommendationReasons: apiResponse.recommendationReasons,
+    warningHeader: apiResponse.warningHeader
   };
   if (result.recommendation === "deny") {
     result.verified = false;
@@ -333,7 +367,7 @@ async function verify(config, request) {
   }
   return result;
 }
-async function recordDecision(config, sessionId, decision, reason) {
+async function recordDecision(config, sessionId, decision, reason, override) {
   const headers = { "Content-Type": "application/json" };
   if (config.apiKey) {
     headers["Authorization"] = `Bearer ${config.apiKey}`;
@@ -342,7 +376,16 @@ async function recordDecision(config, sessionId, decision, reason) {
   await fetch(`${config.apiBaseUrl}/agents/verify-access/${sessionId}/decision`, {
     method: "POST",
     headers,
-    body: JSON.stringify({ decision, reason })
+    body: JSON.stringify({
+      decision,
+      reason,
+      ...override && {
+        overriddenBy: override.overriddenBy,
+        toolName: override.toolName,
+        requestedLevel: override.requestedLevel,
+        grantedLevel: override.grantedLevel
+      }
+    })
   }).catch(() => {
   });
 }
@@ -540,6 +583,7 @@ function createMiddleware(options) {
   let lastFetchAt = 0;
   let refreshing = null;
   let warnedNoCounterparty = false;
+  let warnedEmptyRoutes = false;
   async function refreshRoutes() {
     if (!config.counterpartyId) {
       if (!warnedNoCounterparty) {
@@ -554,6 +598,13 @@ function createMiddleware(options) {
     if (fetched) {
       cachedRoutes = fetched;
       lastFetchAt = Date.now();
+      if (cachedRoutes.length === 0 && !warnedEmptyRoutes) {
+        const dashboard = config.dashboardUrl ?? "https://app.astrasync.ai";
+        console.warn(
+          `[VerificationGateway] No route policy configured for ${config.counterpartyId}. Gateway is in pass-through mode for ALL traffic until you add at least one route. Configure at ${dashboard}/dashboard/endpoints/${config.counterpartyId}/routes`
+        );
+        warnedEmptyRoutes = true;
+      }
     }
   }
   refreshing = refreshRoutes().finally(() => {
@@ -576,9 +627,20 @@ 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-Reason",
+            cachedRoutes.length === 0 ? "no-policy" : "no-match"
+          );
+        }
         return next();
       }
       if (routeConfig.minAccessLevel === "none") {
+        if (config.setPassThroughHeader) {
+          res.setHeader("X-Astra-Gateway-Mode", "pass-through");
+          res.setHeader("X-Astra-Gateway-Reason", "route-none");
+        }
         return next();
       }
       const credentials = customExtractCredentials ? customExtractCredentials(req) : defaultExtractCredentials(req);
@@ -637,6 +699,14 @@ function createMiddleware(options) {
       });
       req.agentVerification = result;
       const sessionId = result.sessionId;
+      if (!result.verified) {
+        if (shouldRecordDecisions && sessionId) {
+          recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
+          });
+        }
+        onDenied(result, req, res);
+        return;
+      }
       if (!hasMinimumAccess(result.accessLevel, routeConfig.minAccessLevel)) {
         if (shouldRecordDecisions && sessionId) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
@@ -662,6 +732,10 @@ function createMiddleware(options) {
         recordDecision(config, sessionId, "granted").catch(() => {
         });
       }
+      const enhancedResult = result;
+      if (enhancedResult.warningHeader) {
+        res.setHeader(enhancedResult.warningHeader.name, enhancedResult.warningHeader.value);
+      }
       next();
     } catch (error) {
       console.error("[VerificationGateway] Middleware error:", error);