@astrasyncai/verification-gateway 2.3.8 → 2.3.10

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-z-QVnG4b.mjs';
-import '../types-D_tmbDA_.mjs';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-pU2O0BFq.mjs';
+import '../types-BVp22KkN.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-Bzp1SMaD.js';
-import '../types-D_tmbDA_.js';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-DVCWReEN.js';
+import '../types-BVp22KkN.js';
 
 /**
  * PlatformAdapter Interface

package/dist/adapters/express.d.mts

@@ -1,3 +1,3 @@
 import 'express';
-import '../types-D_tmbDA_.mjs';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-BNWqDVIz.mjs';
+import '../types-BVp22KkN.mjs';
+export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-4Vau6x6X.mjs';

package/dist/adapters/express.d.ts

@@ -1,3 +1,3 @@
 import 'express';
-import '../types-D_tmbDA_.js';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-BYup_4Jg.js';
+import '../types-BVp22KkN.js';
+export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-Nq-wWICa.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()
@@ -267,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,
@@ -280,6 +296,9 @@ 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.
+      correlationId: apiResponse.correlationId,
       recommendation: apiResponse.recommendation,
       recommendationReasons: apiResponse.recommendationReasons
     };
@@ -320,6 +339,9 @@ async function verify(config, request) {
     cacheTtl: mergedConfig.cacheTtl,
     // Handshake Protocol v10 enhanced fields (present when backend returns them)
     sessionId: apiResponse.sessionId,
+    // v2.3.10 (defect #34, round-4): anonymous responses surface correlationId
+    // (no session row exists for unverified callers).
+    correlationId: apiResponse.correlationId,
     runtimeChallenge: apiResponse.runtimeChallenge,
     tokenGuidance: apiResponse.tokenGuidance,
     recommendation: apiResponse.recommendation,
@@ -351,7 +373,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}`;
@@ -360,7 +382,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(() => {
   });
 }
@@ -674,6 +705,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(() => {