@astrasyncai/verification-gateway 2.4.8 → 2.4.10

package/dist/git-trigger/git-hooks.d.mts

@@ -1,6 +1,6 @@
 import { AstraSyncGateway } from '../gateway/gateway.mjs';
-import { V as VerificationDecision, P as PDLSSContext } from '../types-DOAb89cm.mjs';
-import '../types-BwDmjIdr.mjs';
+import { V as VerificationDecision, P as PDLSSContext } from '../types-DNK2BgIf.mjs';
+import '../types-L15pYd2c.mjs';
 
 /**
  * Git Trigger — Enterprise git push / PR verification

package/dist/git-trigger/git-hooks.d.ts

@@ -1,6 +1,6 @@
 import { AstraSyncGateway } from '../gateway/gateway.js';
-import { V as VerificationDecision, P as PDLSSContext } from '../types-aucqzfUa.js';
-import '../types-BwDmjIdr.js';
+import { V as VerificationDecision, P as PDLSSContext } from '../types-DoWIuzfj.js';
+import '../types-L15pYd2c.js';
 
 /**
  * Git Trigger — Enterprise git push / PR verification

package/dist/{index-DYFS9QVb.d.mts → index-ChPX4WHl.d.mts}

@@ -1,4 +1,4 @@
-import { b as AstraSyncCredentials, f as ProtocolTransport, G as GatewayConfig } from './types-BwDmjIdr.mjs';
+import { b as AstraSyncCredentials, f as ProtocolTransport, G as GatewayConfig } from './types-L15pYd2c.mjs';
 
 /**
  * AgentClient — Credential Presentation

package/dist/{index-DO0oG8ED.d.ts → index-Cjm-zBeZ.d.ts}

@@ -1,4 +1,4 @@
-import { b as AstraSyncCredentials, f as ProtocolTransport, G as GatewayConfig } from './types-BwDmjIdr.js';
+import { b as AstraSyncCredentials, f as ProtocolTransport, G as GatewayConfig } from './types-L15pYd2c.js';
 
 /**
  * AgentClient — Credential Presentation

package/dist/{index-2WAlxs2G.d.ts → index-CzJMCgEy.d.ts}

@@ -1,4 +1,4 @@
-import { b as AstraSyncCredentials, f as ProtocolTransport } from './types-BwDmjIdr.js';
+import { b as AstraSyncCredentials, f as ProtocolTransport } from './types-L15pYd2c.js';
 import { JWK } from 'jose';
 
 /**

package/dist/{index-P9t7M_dJ.d.mts → index-D8IEntil.d.mts}

@@ -1,4 +1,4 @@
-import { b as AstraSyncCredentials, f as ProtocolTransport } from './types-BwDmjIdr.mjs';
+import { b as AstraSyncCredentials, f as ProtocolTransport } from './types-L15pYd2c.mjs';
 import { JWK } from 'jose';
 
 /**

package/dist/index.d.mts

@@ -1,12 +1,12 @@
-import { a as AgentCredentials, G as GatewayConfig, A as AccessLevel, V as VerificationRequest, i as VerificationResult } from './types-BwDmjIdr.mjs';
-export { b as AstraSyncCredentials, C as CommerceShieldProps, c as CounterpartyType, E as EnhancedVerificationResult, d as ExpressMiddlewareOptions, e as GuidanceInfo, N as NextJsMiddlewareOptions, P as PDLSSInfo, f as ProtocolTransport, R as RouteAccessConfig, g as RuntimeChallengeResult, S as SDKOptions, T as TokenGuidance, h as TrustLevel, j as VerifiedAgent, k as VerifiedDeveloper, l as VerifiedOrganization } from './types-BwDmjIdr.mjs';
-export { A as ACCESS_LEVEL_DESCRIPTIONS, a as ACCESS_LEVEL_HIERARCHY, b as AccessCapabilities, D as DEFAULT_TRUST_THRESHOLDS, T as TRUST_LEVEL_RANGES, d as determineAccessLevel, g as getAccessLevelForScore, e as getCapabilities, f as getTrustLevel, h as hasMinimumAccess, s as sdk } from './sdk-wwhFDXWX.mjs';
-export { e as express } from './express-DvVjR2H4.mjs';
-export { n as nextjs } from './nextjs-BCoH7EqF.mjs';
-export { aR as extractMcpCredentials, bg as setMcpMeta, b1 as transport } from './index-P9t7M_dJ.mjs';
+import { a as AgentCredentials, G as GatewayConfig, A as AccessLevel, V as VerificationRequest, i as VerificationResult } from './types-L15pYd2c.mjs';
+export { b as AstraSyncCredentials, C as CommerceShieldProps, c as CounterpartyType, E as EnhancedVerificationResult, d as ExpressMiddlewareOptions, e as GuidanceInfo, N as NextJsMiddlewareOptions, P as PDLSSInfo, f as ProtocolTransport, R as RouteAccessConfig, g as RuntimeChallengeResult, S as SDKOptions, T as TokenGuidance, h as TrustLevel, j as VerifiedAgent, k as VerifiedDeveloper, l as VerifiedOrganization } from './types-L15pYd2c.mjs';
+export { A as ACCESS_LEVEL_DESCRIPTIONS, a as ACCESS_LEVEL_HIERARCHY, b as AccessCapabilities, D as DEFAULT_TRUST_THRESHOLDS, T as TRUST_LEVEL_RANGES, d as determineAccessLevel, g as getAccessLevelForScore, e as getCapabilities, f as getTrustLevel, h as hasMinimumAccess, s as sdk } from './sdk-Chhz-FcT.mjs';
+export { e as express } from './express-4WStX3PV.mjs';
+export { n as nextjs } from './nextjs-CjzHdaXA.mjs';
+export { aR as extractMcpCredentials, bg as setMcpMeta, b1 as transport } from './index-D8IEntil.mjs';
 export { McpMiddlewareOptions, createMcpMiddleware } from './adapters/mcp.mjs';
-export { AgentProtocol, AgentRecord, AstraSync, AstraSyncConfig, AstraSyncError, AuthenticationError, FrameworkConfig, HealthResponse, KYDRequiredError, ModelConfig, PDLSSConfig, PDLSSDuration, PDLSSLimits, PDLSSPurpose, PDLSSScope, PDLSSSelfInstantiation, PendingRegistrationResponse, PollRegistrationResult, RegisterOptions, RegisterResult, RegistrationDeniedError, RegistrationExpiredError, RegistrationResponse, RegistrationTimeoutError, VerifyResponse, WaitForApprovalOptions } from './registration/index.mjs';
-export { A as AgentClient, C as ChallengeHandler, i as agent, r as recordDecision } from './index-DYFS9QVb.mjs';
+export { AgentProtocol, AgentRecord, AstraSync, AstraSyncConfig, AstraSyncError, AuthenticationError, BuildGuidanceParams, FrameworkConfig, GuidanceEnvelope, HealthResponse, KYDRequiredError, ModelConfig, PDLSSConfig, PDLSSDuration, PDLSSLimits, PDLSSPurpose, PDLSSScope, PDLSSSelfInstantiation, PendingRegistrationResponse, PollRegistrationResult, RegisterOptions, RegisterResult, RegistrationDeniedError, RegistrationExpiredError, RegistrationResponse, RegistrationTimeoutError, VerifyResponse, WaitForApprovalOptions, buildGuidance } from './registration/index.mjs';
+export { A as AgentClient, C as ChallengeHandler, i as agent, r as recordDecision } from './index-ChPX4WHl.mjs';
 import 'express';
 import 'next/server';
 import 'jose';
@@ -35,10 +35,17 @@ declare function hasCredentials(credentials: AgentCredentials): boolean;
  */
 declare function verify(config: GatewayConfig, request: VerificationRequest): Promise<VerificationResult>;
 /**
- * Quick verification - just check if credentials are valid
+ * Quick verification — checks credentials and policy in one call.
+ *
+ * Round-18 G4: return shape mirrors `VerificationResult`'s split — partners
+ * writing custom handlers around `quickVerify` get the same identity/policy
+ * distinction as those calling `verify()` directly. Map to HTTP status the
+ * same way: `!identityVerified` → 401; `identityVerified && !policyAllowed`
+ * → 403.
  */
 declare function quickVerify(config: GatewayConfig, credentials: AgentCredentials): Promise<{
-    verified: boolean;
+    identityVerified: boolean;
+    policyAllowed: boolean;
     accessLevel: AccessLevel;
     reason?: string;
 }>;
@@ -56,9 +63,13 @@ declare function quickVerify(config: GatewayConfig, credentials: AgentCredential
  * const credentials = extractCredentials(request.headers);
  * const result = await verify(config, { credentials, purpose: 'data-access' });
  *
- * if (result.verified && result.accessLevel !== 'none') {
+ * if (result.identityVerified && result.policyAllowed && result.accessLevel !== 'none') {
  *   // Grant access based on result.accessLevel
  * }
+ *
+ * // Or map to HTTP status codes directly:
+ * if (!result.identityVerified) return res.status(401).json({ ... });   // re-auth
+ * if (!result.policyAllowed)    return res.status(403).json({ ... });   // step up / update PDLSS
  * ```
  *
  * @packageDocumentation

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import { a as AgentCredentials, G as GatewayConfig, A as AccessLevel, V as VerificationRequest, i as VerificationResult } from './types-BwDmjIdr.js';
-export { b as AstraSyncCredentials, C as CommerceShieldProps, c as CounterpartyType, E as EnhancedVerificationResult, d as ExpressMiddlewareOptions, e as GuidanceInfo, N as NextJsMiddlewareOptions, P as PDLSSInfo, f as ProtocolTransport, R as RouteAccessConfig, g as RuntimeChallengeResult, S as SDKOptions, T as TokenGuidance, h as TrustLevel, j as VerifiedAgent, k as VerifiedDeveloper, l as VerifiedOrganization } from './types-BwDmjIdr.js';
-export { A as ACCESS_LEVEL_DESCRIPTIONS, a as ACCESS_LEVEL_HIERARCHY, b as AccessCapabilities, D as DEFAULT_TRUST_THRESHOLDS, T as TRUST_LEVEL_RANGES, d as determineAccessLevel, g as getAccessLevelForScore, e as getCapabilities, f as getTrustLevel, h as hasMinimumAccess, s as sdk } from './sdk-kiA49vqJ.js';
-export { e as express } from './express-714gJbaW.js';
-export { n as nextjs } from './nextjs-CZ-MwSOT.js';
-export { aR as extractMcpCredentials, bg as setMcpMeta, b1 as transport } from './index-2WAlxs2G.js';
+import { a as AgentCredentials, G as GatewayConfig, A as AccessLevel, V as VerificationRequest, i as VerificationResult } from './types-L15pYd2c.js';
+export { b as AstraSyncCredentials, C as CommerceShieldProps, c as CounterpartyType, E as EnhancedVerificationResult, d as ExpressMiddlewareOptions, e as GuidanceInfo, N as NextJsMiddlewareOptions, P as PDLSSInfo, f as ProtocolTransport, R as RouteAccessConfig, g as RuntimeChallengeResult, S as SDKOptions, T as TokenGuidance, h as TrustLevel, j as VerifiedAgent, k as VerifiedDeveloper, l as VerifiedOrganization } from './types-L15pYd2c.js';
+export { A as ACCESS_LEVEL_DESCRIPTIONS, a as ACCESS_LEVEL_HIERARCHY, b as AccessCapabilities, D as DEFAULT_TRUST_THRESHOLDS, T as TRUST_LEVEL_RANGES, d as determineAccessLevel, g as getAccessLevelForScore, e as getCapabilities, f as getTrustLevel, h as hasMinimumAccess, s as sdk } from './sdk-CqTEQAc6.js';
+export { e as express } from './express-C1ePFB7n.js';
+export { n as nextjs } from './nextjs-BIORS__0.js';
+export { aR as extractMcpCredentials, bg as setMcpMeta, b1 as transport } from './index-CzJMCgEy.js';
 export { McpMiddlewareOptions, createMcpMiddleware } from './adapters/mcp.js';
-export { AgentProtocol, AgentRecord, AstraSync, AstraSyncConfig, AstraSyncError, AuthenticationError, FrameworkConfig, HealthResponse, KYDRequiredError, ModelConfig, PDLSSConfig, PDLSSDuration, PDLSSLimits, PDLSSPurpose, PDLSSScope, PDLSSSelfInstantiation, PendingRegistrationResponse, PollRegistrationResult, RegisterOptions, RegisterResult, RegistrationDeniedError, RegistrationExpiredError, RegistrationResponse, RegistrationTimeoutError, VerifyResponse, WaitForApprovalOptions } from './registration/index.js';
-export { A as AgentClient, C as ChallengeHandler, i as agent, r as recordDecision } from './index-DO0oG8ED.js';
+export { AgentProtocol, AgentRecord, AstraSync, AstraSyncConfig, AstraSyncError, AuthenticationError, BuildGuidanceParams, FrameworkConfig, GuidanceEnvelope, HealthResponse, KYDRequiredError, ModelConfig, PDLSSConfig, PDLSSDuration, PDLSSLimits, PDLSSPurpose, PDLSSScope, PDLSSSelfInstantiation, PendingRegistrationResponse, PollRegistrationResult, RegisterOptions, RegisterResult, RegistrationDeniedError, RegistrationExpiredError, RegistrationResponse, RegistrationTimeoutError, VerifyResponse, WaitForApprovalOptions, buildGuidance } from './registration/index.js';
+export { A as AgentClient, C as ChallengeHandler, i as agent, r as recordDecision } from './index-Cjm-zBeZ.js';
 import 'express';
 import 'next/server';
 import 'jose';
@@ -35,10 +35,17 @@ declare function hasCredentials(credentials: AgentCredentials): boolean;
  */
 declare function verify(config: GatewayConfig, request: VerificationRequest): Promise<VerificationResult>;
 /**
- * Quick verification - just check if credentials are valid
+ * Quick verification — checks credentials and policy in one call.
+ *
+ * Round-18 G4: return shape mirrors `VerificationResult`'s split — partners
+ * writing custom handlers around `quickVerify` get the same identity/policy
+ * distinction as those calling `verify()` directly. Map to HTTP status the
+ * same way: `!identityVerified` → 401; `identityVerified && !policyAllowed`
+ * → 403.
  */
 declare function quickVerify(config: GatewayConfig, credentials: AgentCredentials): Promise<{
-    verified: boolean;
+    identityVerified: boolean;
+    policyAllowed: boolean;
     accessLevel: AccessLevel;
     reason?: string;
 }>;
@@ -56,9 +63,13 @@ declare function quickVerify(config: GatewayConfig, credentials: AgentCredential
  * const credentials = extractCredentials(request.headers);
  * const result = await verify(config, { credentials, purpose: 'data-access' });
  *
- * if (result.verified && result.accessLevel !== 'none') {
+ * if (result.identityVerified && result.policyAllowed && result.accessLevel !== 'none') {
  *   // Grant access based on result.accessLevel
  * }
+ *
+ * // Or map to HTTP status codes directly:
+ * if (!result.identityVerified) return res.status(401).json({ ... });   // re-auth
+ * if (!result.policyAllowed)    return res.status(403).json({ ... });   // step up / update PDLSS
  * ```
  *
  * @packageDocumentation

package/dist/index.js

@@ -45,6 +45,7 @@ __export(src_exports, {
   TRUST_LEVEL_RANGES: () => TRUST_LEVEL_RANGES,
   VERSION: () => VERSION,
   agent: () => agent_exports,
+  buildGuidance: () => buildGuidance,
   clearCache: () => clearCache,
   createMcpMiddleware: () => createMcpMiddleware,
   determineAccessLevel: () => determineAccessLevel,
@@ -188,7 +189,7 @@ function getCapabilities(accessLevel) {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.4.7";
+var SDK_VERSION = "2.4.10";
 
 // src/verify.ts
 var DEFAULT_CONFIG = {
@@ -199,8 +200,10 @@ var DEFAULT_CONFIG = {
   // through (`hasMinimumAccess('guidance', 'guidance') === true`).
   defaultAccessLevel: "none",
   // minTrustScore + minTrustScoreForFull deprecated in v2.3.0 — server decides.
-  cacheTtl: 300,
-  // 5 minutes
+  // Round-18.5 F4: cacheTtl deliberately unset. When undefined, cacheResult
+  // applies the split default (60s autonomous / 300s step-up). When the
+  // caller sets cacheTtl explicitly, that value is honoured uniformly.
+  // Set cacheTtl: 0 to disable caching entirely.
   debug: false
 };
 var initCheckPerformed = false;
@@ -227,11 +230,28 @@ async function performInitCheck(apiBaseUrl, debug) {
   }
 }
 var verificationCache = /* @__PURE__ */ new Map();
-function getCacheKey(credentials) {
-  return `${credentials.astraId || ""}-${credentials.apiKey || ""}-${credentials.jwt || ""}`;
-}
-function getCachedResult(credentials) {
-  const key = getCacheKey(credentials);
+function getCacheKey(request) {
+  const c = request.credentials;
+  return [
+    c.astraId || "",
+    c.apiKey || "",
+    c.jwt || "",
+    request.purpose || "",
+    request.action || "",
+    request.resourceType || "",
+    request.resource || "",
+    request.jurisdiction || "",
+    request.transactionValue ?? "",
+    request.currency || "",
+    request.counterpartyUrl || "",
+    request.counterpartyType || "",
+    request.isSubAgentRequest ? "1" : "0",
+    request.parentAgentId || "",
+    request.subAgentDepth ?? ""
+  ].join("|");
+}
+function getCachedResult(request) {
+  const key = getCacheKey(request);
   const cached = verificationCache.get(key);
   if (cached && cached.expiresAt > Date.now()) {
     return cached.result;
@@ -241,8 +261,11 @@ function getCachedResult(credentials) {
   }
   return null;
 }
-function cacheResult(credentials, result, ttlSeconds) {
-  const key = getCacheKey(credentials);
+var DEFAULT_AUTONOMOUS_TTL_SECONDS = 60;
+var DEFAULT_STEP_UP_TTL_SECONDS = 300;
+function cacheResult(request, result, configuredTtl) {
+  const ttlSeconds = configuredTtl && configuredTtl > 0 ? configuredTtl : result.requiresStepUp ? DEFAULT_STEP_UP_TTL_SECONDS : DEFAULT_AUTONOMOUS_TTL_SECONDS;
+  const key = getCacheKey(request);
   verificationCache.set(key, {
     result,
     expiresAt: Date.now() + ttlSeconds * 1e3
@@ -305,12 +328,17 @@ function createGuidanceResponse(config, reason, options = {}) {
     ]
   };
   return {
-    verified: false,
+    // Round-18 G4: createGuidanceResponse fires for unverified-agent path or
+    // API-error fallback. Identity is not verified (no agent resolved);
+    // policy is not evaluated (we never reached the gate).
+    identityVerified: false,
+    policyAllowed: false,
     // 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.
+    // Adapters additionally short-circuit on `!identityVerified ||
+    // !policyAllowed` 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"],
@@ -426,8 +454,8 @@ async function verify(config, request) {
       "[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);
+  if (mergedConfig.cacheTtl !== 0) {
+    const cached = getCachedResult(request);
     if (cached) {
       if (mergedConfig.debug) {
         console.log("[VerificationGateway] Returning cached result");
@@ -454,15 +482,17 @@ async function verify(config, request) {
   }
   if (!apiResponse.access?.allowed) {
     const aggregatedFailures = apiResponse.access?.failures;
+    const idVerifiedFromBackend = apiResponse.verificationContext?.idVerified === true;
     const result2 = {
-      verified: false,
+      identityVerified: idVerifiedFromBackend,
+      policyAllowed: false,
       // 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.
+      // ALSO short-circuit on `!identityVerified || !policyAllowed` 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,
@@ -506,7 +536,13 @@ async function verify(config, request) {
   const verificationContext = apiResponse.verificationContext;
   const accessLevel = apiResponse.access?.accessLevel ?? "standard";
   const result = {
-    verified: true,
+    // Round-18 G4: backend allowed access. Identity is verified (we resolved
+    // the caller to an agent) and policy passed all gates. Read idVerified
+    // from verificationContext for symmetry with the deny branch; default true
+    // on success path since `access.allowed === true` implies identity was
+    // resolvable (anonymous-allow paths flow through createGuidanceResponse).
+    identityVerified: apiResponse.verificationContext?.idVerified !== false,
+    policyAllowed: true,
     accessLevel,
     agent,
     developer,
@@ -529,7 +565,7 @@ async function verify(config, request) {
     warningHeader: apiResponse.warningHeader
   };
   if (result.recommendation === "deny") {
-    result.verified = false;
+    result.policyAllowed = false;
     result.accessLevel = "none";
     result.denialReasons = result.recommendationReasons || [
       "Access denied by AstraSync recommendation"
@@ -548,8 +584,8 @@ async function verify(config, request) {
     }
     result.denialReasons = result.recommendationReasons || ["Step-up verification required"];
   }
-  if (mergedConfig.cacheTtl && mergedConfig.cacheTtl > 0 && result.recommendation !== "deny") {
-    cacheResult(request.credentials, result, mergedConfig.cacheTtl);
+  if (mergedConfig.cacheTtl !== 0 && result.recommendation !== "deny") {
+    cacheResult(request, result, mergedConfig.cacheTtl);
   }
   return result;
 }
@@ -629,7 +665,8 @@ async function quickVerify(config, credentials) {
     purpose: "verification"
   });
   return {
-    verified: result.verified,
+    identityVerified: result.identityVerified,
+    policyAllowed: result.policyAllowed,
     accessLevel: result.accessLevel,
     reason: result.denialReasons?.[0]
   };
@@ -705,8 +742,15 @@ function extractHttpCredentials(headers) {
 // src/pdlss-pre-check.ts
 function performCounterpartyPreCheck(routeConfig, astraCreds, purpose) {
   const failures = [];
-  if (routeConfig.allowedPurposes && routeConfig.allowedPurposes.length > 0 && purpose) {
-    if (!routeConfig.allowedPurposes.includes(purpose)) {
+  if (purpose) {
+    if (!routeConfig.allowedPurposes || routeConfig.allowedPurposes.length === 0) {
+      failures.push({
+        field: "purpose",
+        requested: purpose,
+        limit: [],
+        message: `Purpose "${purpose}" not allowed: route declares no allowedPurposes. The endpoint owner must enumerate allowedPurposes on the route config to authorise specific purposes.`
+      });
+    } else if (!routeConfig.allowedPurposes.includes(purpose)) {
       failures.push({
         field: "purpose",
         requested: purpose,
@@ -736,9 +780,16 @@ function performCounterpartyPreCheck(routeConfig, astraCreds, purpose) {
       });
     }
   }
-  if (routeConfig.allowedJurisdictions && routeConfig.allowedJurisdictions.length > 0 && astraCreds?.pdlss?.scope?.jurisdiction) {
+  if (astraCreds?.pdlss?.scope?.jurisdiction) {
     const requested = astraCreds.pdlss.scope.jurisdiction;
-    if (!routeConfig.allowedJurisdictions.includes(requested)) {
+    if (!routeConfig.allowedJurisdictions || routeConfig.allowedJurisdictions.length === 0) {
+      failures.push({
+        field: "jurisdiction",
+        requested,
+        limit: [],
+        message: `Jurisdiction "${requested}" not allowed: route declares no allowedJurisdictions. The endpoint owner must enumerate allowedJurisdictions on the route config to authorise specific jurisdictions.`
+      });
+    } else if (!routeConfig.allowedJurisdictions.includes(requested)) {
       failures.push({
         field: "jurisdiction",
         requested,
@@ -801,12 +852,12 @@ function findRouteConfig(routes, path, method) {
   });
 }
 function defaultOnDenied(result, _req, res) {
-  const statusCode = result.verified ? 403 : 401;
+  const statusCode = !result.identityVerified ? 401 : 403;
   res.setHeader("X-Astra-Gateway-Mode", "enforced");
   res.status(statusCode).json({
     success: false,
     error: {
-      code: result.verified ? "INSUFFICIENT_ACCESS" : "UNAUTHORIZED",
+      code: !result.identityVerified ? "UNAUTHORIZED" : "INSUFFICIENT_ACCESS",
       message: result.denialReasons?.[0] || "Access denied",
       accessLevel: result.accessLevel,
       guidance: result.guidance,
@@ -900,7 +951,8 @@ function createMiddleware(options) {
       const preCheckFailures = performCounterpartyPreCheck(routeConfig, astraCreds, purpose);
       if (preCheckFailures.length > 0) {
         const result2 = {
-          verified: false,
+          identityVerified: false,
+          policyAllowed: false,
           accessLevel: "none",
           denialReasons: preCheckFailures.map((f) => f.message),
           guidance: {
@@ -949,7 +1001,7 @@ function createMiddleware(options) {
       });
       req.agentVerification = result;
       const sessionId = result.sessionId;
-      if (!result.verified) {
+      if (!result.identityVerified || !result.policyAllowed) {
         if (shouldRecordDecisions && sessionId) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
           });
@@ -1300,7 +1352,8 @@ function createMiddleware2(options) {
     const preCheckFailures = performCounterpartyPreCheck(routeConfig, astraCreds, purpose);
     if (preCheckFailures.length > 0) {
       const preCheckResult = {
-        verified: false,
+        identityVerified: false,
+        policyAllowed: false,
         accessLevel: "none",
         denialReasons: preCheckFailures.map((f) => f.message),
         guidance: {
@@ -1363,20 +1416,22 @@ function createMiddleware2(options) {
         agentCardUrl: request.headers.get("x-astrasync-agent-card") || void 0
       }
     });
-    if (!result.verified || !hasMinimumAccess(result.accessLevel, routeConfig.minAccessLevel)) {
+    if (!result.identityVerified || !result.policyAllowed || !hasMinimumAccess(result.accessLevel, routeConfig.minAccessLevel)) {
       if (pathname.startsWith("/api/")) {
         return NextResponse.json(
           {
             success: false,
             error: {
-              code: result.verified ? "INSUFFICIENT_ACCESS" : "UNAUTHORIZED",
+              // Round-18 G4: 401 → identity missing (re-auth); 403 → identity
+              // OK, policy denied (update PDLSS / step up).
+              code: !result.identityVerified ? "UNAUTHORIZED" : "INSUFFICIENT_ACCESS",
               message: result.denialReasons?.[0] || "Access denied",
               accessLevel: result.accessLevel,
               required: routeConfig.minAccessLevel,
               guidance: result.guidance
             }
           },
-          { status: result.verified ? 403 : 401 }
+          { status: !result.identityVerified ? 401 : 403 }
         );
       }
       if (showCommerceShield) {
@@ -1391,7 +1446,12 @@ function createMiddleware2(options) {
       return NextResponse.redirect(new URL("/unauthorized", request.url));
     }
     const response = NextResponse.next();
-    response.headers.set("X-AstraSync-Verified", result.verified.toString());
+    response.headers.set(
+      "X-AstraSync-Verified",
+      (result.identityVerified && result.policyAllowed).toString()
+    );
+    response.headers.set("X-AstraSync-Identity-Verified", result.identityVerified.toString());
+    response.headers.set("X-AstraSync-Policy-Allowed", result.policyAllowed.toString());
     response.headers.set("X-AstraSync-Access-Level", result.accessLevel);
     if (result.agent) {
       response.headers.set("X-AstraSync-Agent-Id", result.agent.astraId);
@@ -1459,7 +1519,11 @@ var VerificationGatewayClient = class {
     );
   }
   /**
-   * Quick verification - just check if credentials are valid
+   * Quick verification — checks credentials and policy in one call.
+   *
+   * Round-18 G4: return shape mirrors `VerificationResult`'s identity/policy
+   * split. Map to HTTP status the same way: `!identityVerified` → 401,
+   * `identityVerified && !policyAllowed` → 403.
    */
   async quickVerify(credentials) {
     return this.executeWithRetry(() => quickVerify(this.config, credentials));
@@ -4102,13 +4166,16 @@ function readSingleHeader(value) {
 }
 function defaultMcpDenied(result, req, res) {
   const id = req.body?.id ?? null;
-  const status = result.verified ? 403 : 401;
+  const status = !result.identityVerified ? 401 : 403;
   res.setHeader("X-Astra-Gateway-Mode", "enforced");
   res.status(status).json({
     jsonrpc: "2.0",
     id,
     error: {
-      code: result.verified ? -32001 : -32e3,
+      // JSON-RPC error codes:
+      //   -32000 → unauthorized (no identity resolved)
+      //   -32001 → insufficient access (identity OK, policy denied)
+      code: !result.identityVerified ? -32e3 : -32001,
       message: result.denialReasons?.[0] ?? "Access denied",
       data: {
         accessLevel: result.accessLevel,
@@ -4242,7 +4309,7 @@ function createMcpMiddleware(options) {
       req.agentVerification = result;
       const sessionId = result.sessionId;
       const correlationId = result.correlationId;
-      if (!result.verified) {
+      if (!result.identityVerified || !result.policyAllowed) {
         if (shouldRecordDecisions && sessionId) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
           });
@@ -4659,6 +4726,29 @@ var AstraSync = class {
   }
 };
 
+// src/registration/guidance.ts
+function buildGuidance(params) {
+  const origin = params.origin.replace(/\/+$/, "");
+  const docsPath = params.documentationPath ?? "/docs/agent-access";
+  const message = params.message ?? "AstraSync registration requires credentials.";
+  return {
+    status: "credentials_required",
+    message,
+    guidance: {
+      message: "AstraSync registration requires credentials. Get an account + API key, then call register_agent again.",
+      registrationUrl: `${origin}/register`,
+      documentationUrl: `${origin}${docsPath.startsWith("/") ? docsPath : `/${docsPath}`}`,
+      steps: [
+        "Visit registrationUrl and create an AstraSync account (or log in if you have one).",
+        "Generate an API key from Settings \u2192 API Keys.",
+        "Re-call register_agent with the apiKey populated.",
+        "After registration returns status: pending_approval, the owner approves via email.",
+        "Use poll_registration({ requestId }) to retrieve the astraId once approved."
+      ]
+    }
+  };
+}
+
 // src/agent/index.ts
 var agent_exports = {};
 __export(agent_exports, {
@@ -4992,6 +5082,7 @@ var VERSION = "2.0.0";
   TRUST_LEVEL_RANGES,
   VERSION,
   agent,
+  buildGuidance,
   clearCache,
   createMcpMiddleware,
   determineAccessLevel,