@astrasyncai/verification-gateway 4.5.1 → 5.0.0

package/dist/index.js

@@ -30,8 +30,6 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
-  ACCESS_LEVEL_DESCRIPTIONS: () => ACCESS_LEVEL_DESCRIPTIONS,
-  ACCESS_LEVEL_HIERARCHY: () => ACCESS_LEVEL_HIERARCHY,
   AgentClient: () => AgentClient,
   AstraSync: () => AstraSync,
   AstraSyncError: () => AstraSyncError,
@@ -39,7 +37,6 @@ __export(src_exports, {
   CAPTURE_SCHEMA_VERSION: () => CAPTURE_SCHEMA_VERSION,
   ChallengeHandler: () => ChallengeHandler,
   DEFAULT_EDGE_CONFIG: () => DEFAULT_EDGE_CONFIG,
-  DEFAULT_TRUST_THRESHOLDS: () => DEFAULT_TRUST_THRESHOLDS,
   KYDRequiredError: () => KYDRequiredError,
   MAX_HEADERS: () => MAX_HEADERS,
   MAX_HEADER_VALUE_BYTES: () => MAX_HEADER_VALUE_BYTES,
@@ -66,7 +63,6 @@ __export(src_exports, {
   deriveConnectionFromHeaders: () => deriveConnectionFromHeaders,
   detectPlatformFingerprint: () => detectPlatformFingerprint,
   detectRuntime: () => detectRuntime,
-  determineAccessLevel: () => determineAccessLevel,
   express: () => express_exports,
   extractApiKeyFormat: () => extractApiKeyFormat,
   extractCredentials: () => extractCredentials,
@@ -74,14 +70,11 @@ __export(src_exports, {
   extractPlatformHeaders: () => extractPlatformHeaders,
   fetchEdgeConfig: () => fetchEdgeConfig,
   fetchRoutes: () => fetchRoutes,
-  getAccessLevelForScore: () => getAccessLevelForScore,
   getCachedWellKnownUrls: () => getCachedWellKnownUrls,
-  getCapabilities: () => getCapabilities,
   getEdgeConfig: () => getEdgeConfig,
   getTrustLevel: () => getTrustLevel,
   getWellKnownUrls: () => getWellKnownUrls,
   hasCredentials: () => hasCredentials,
-  hasMinimumAccess: () => hasMinimumAccess,
   isEdgeConfig: () => isEdgeConfig,
   isVerifiedHopValidFor: () => isVerifiedHopValidFor,
   matchEdgePathRule: () => matchEdgePathRule,
@@ -104,32 +97,7 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/access-levels.ts
-var ACCESS_LEVEL_HIERARCHY = {
-  none: 0,
-  restricted: 1,
-  "read-only": 2,
-  standard: 3,
-  full: 4,
-  internal: 5
-};
-var ACCESS_LEVEL_DESCRIPTIONS = {
-  none: "No access - credentials required",
-  restricted: "Restricted access - registration prompt only",
-  "read-only": "Read-only access - can browse but not modify",
-  standard: "Standard access - normal operations per PDLSS policy",
-  full: "Full access - all operations for high-trust agents",
-  internal: "Internal access - organization member privileges"
-};
-var DEFAULT_TRUST_THRESHOLDS = {
-  none: 0,
-  restricted: 0,
-  "read-only": 20,
-  standard: 40,
-  full: 70,
-  internal: 0
-  // Internal is based on org membership, not score
-};
+// src/trust-levels.ts
 var TRUST_LEVEL_RANGES = {
   BRONZE: { min: 0, max: 39 },
   SILVER: { min: 40, max: 59 },
@@ -142,91 +110,9 @@ function getTrustLevel(score) {
   if (score >= 40) return "SILVER";
   return "BRONZE";
 }
-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 "restricted";
-}
-function determineAccessLevel(verified, trustScore, isOrgMember, customThresholds) {
-  if (!verified) {
-    return "none";
-  }
-  if (isOrgMember) {
-    return "internal";
-  }
-  const thresholds = {
-    ...DEFAULT_TRUST_THRESHOLDS,
-    ...customThresholds
-  };
-  return getAccessLevelForScore(trustScore, thresholds);
-}
-function getCapabilities(accessLevel) {
-  switch (accessLevel) {
-    case "none":
-      return {
-        canRead: false,
-        canWrite: false,
-        canDelete: false,
-        canAdmin: false,
-        canAccessInternal: false
-      };
-    case "restricted":
-      return {
-        canRead: false,
-        canWrite: false,
-        canDelete: false,
-        canAdmin: false,
-        canAccessInternal: false
-      };
-    case "read-only":
-      return {
-        canRead: true,
-        canWrite: false,
-        canDelete: false,
-        canAdmin: false,
-        canAccessInternal: false
-      };
-    case "standard":
-      return {
-        canRead: true,
-        canWrite: true,
-        canDelete: false,
-        canAdmin: false,
-        canAccessInternal: false
-      };
-    case "full":
-      return {
-        canRead: true,
-        canWrite: true,
-        canDelete: true,
-        canAdmin: false,
-        canAccessInternal: false
-      };
-    case "internal":
-      return {
-        canRead: true,
-        canWrite: true,
-        canDelete: true,
-        canAdmin: true,
-        canAccessInternal: true
-      };
-    default:
-      return {
-        canRead: false,
-        canWrite: false,
-        canDelete: false,
-        canAdmin: false,
-        canAccessInternal: false
-      };
-  }
-}
 
 // src/version.ts
-var SDK_VERSION = "4.5.1";
+var SDK_VERSION = "5.0.0";
 
 // src/http.ts
 var SDK_USER_AGENT = `astrasync-sdk/${SDK_VERSION}`;
@@ -308,11 +194,6 @@ function getCachedWellKnownUrls(apiBaseUrl) {
 // src/verify.ts
 var DEFAULT_CONFIG = {
   apiBaseUrl: "https://astrasync.ai/api",
-  // 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 deliberately unset. When undefined, cacheResult applies the 60s
   // default; the caller's explicit value is honoured for cacheable results.
@@ -513,13 +394,6 @@ function createGuidanceResponse(_config, reason, options = {}) {
     // 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 `!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"],
     // Round-10 (#47, O5): on API-error fallback, surface a typed failure so
@@ -542,6 +416,11 @@ function createGuidanceResponse(_config, reason, options = {}) {
     // 4.0.0: typed marker so adapters render the misconfig envelope (503 +
     // MERCHANT_VERIFICATION_MISCONFIGURED) without string-matching.
     ...isMisconfig && { misconfigured: true },
+    // 4.6.0: a transient api_error is retryable — mark it so consumers surface
+    // "temporarily unavailable, retry" (recommendation 'error') instead of
+    // coercing the absent recommendation to a policy 'deny'. Misconfig is
+    // deterministic and intentionally NOT marked retryable.
+    ...isApiError && { retryable: true },
     correlationId: options.correlationId,
     attemptId: options.attemptId,
     verifiedAt: /* @__PURE__ */ new Date()
@@ -608,7 +487,6 @@ async function callVerifyAccessAPI(config, request) {
         attemptId: typeof data?.attemptId === "string" ? data.attemptId : void 0,
         access: {
           allowed: false,
-          accessLevel: "none",
           reason: "endpoint_deactivated",
           failures: [
             {
@@ -671,7 +549,7 @@ async function verify(config, request, options) {
   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."
+      "[VerificationGateway] minTrustScore / minTrustScoreForFull are deprecated in v2.3.0 and have no effect. Server is now the single source of truth for access decisions (verified ID + runtime challenge + PDLSS + trust score). To gate access to an endpoint, configure the endpoint's trust_score_requirement server-side."
     );
   }
   if (mergedConfig.cacheTtl !== 0 && !options?.bypassCache) {
@@ -717,14 +595,6 @@ async function verify(config, request, options) {
     const result2 = {
       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 `!identityVerified || !policyAllowed` before
-      // the gate check — belt-and-braces.
-      accessLevel: "none",
       // 3.6.0: the server now emits top-level denialReasons on every deny
       // path — prefer it verbatim; the failure-message reconstruction remains
       // as the fallback for older backends.
@@ -773,7 +643,6 @@ async function verify(config, request, options) {
     trustScore: apiResponse.organization.trustScore
   } : void 0;
   const verificationContext = apiResponse.verificationContext;
-  const accessLevel = apiResponse.access?.accessLevel ?? "standard";
   const result = {
     // 4.5.0 (probe F1): read idVerified from verificationContext with the
     // SAME absent⇒false default as the deny branch. The previous `!== false`
@@ -785,7 +654,6 @@ async function verify(config, request, options) {
     // this load-bearing must never be defaulted on.
     identityVerified: apiResponse.verificationContext?.idVerified === true,
     policyAllowed: true,
-    accessLevel,
     agent,
     developer,
     organization,
@@ -812,7 +680,6 @@ async function verify(config, request, options) {
   };
   if (result.recommendation === "deny") {
     result.policyAllowed = false;
-    result.accessLevel = "none";
     result.denialReasons = serverDenialReasons ?? result.recommendationReasons ?? ["Access denied by AstraSync recommendation"];
     result.guidance = result.runtimeChallenge ? {
       message: `Verification failed: ${result.runtimeChallenge.reason || "runtime challenge failed"}`,
@@ -915,7 +782,6 @@ async function quickVerify(config, credentials) {
   return {
     identityVerified: result.identityVerified,
     policyAllowed: result.policyAllowed,
-    accessLevel: result.accessLevel,
     reason: result.denialReasons?.[0]
   };
 }
@@ -1945,7 +1811,6 @@ function defaultOnDenied(result, _req, res) {
     error: {
       code: !result.identityVerified ? "UNAUTHORIZED" : "INSUFFICIENT_ACCESS",
       message: result.denialReasons?.[0] || "Access denied",
-      accessLevel: result.accessLevel,
       guidance: result.guidance,
       // Round-10: aggregated per-dimension detail + correlation handle.
       failures: result.failures,
@@ -2061,11 +1926,11 @@ function createMiddleware(options) {
       }
       const wellKnownUrls = config.apiBaseUrl ? await getWellKnownUrls(config.apiBaseUrl).catch(() => void 0) : void 0;
       const credentials = customExtractCredentials ? customExtractCredentials(req) : defaultExtractCredentials(req);
-      const shouldEnforce = routeConfig.minAccessLevel !== "none";
-      if (routeConfig.minAccessLevel === "none" && (!config.evaluateAlwaysIfCredentialed || !credentials.astraId)) {
+      const shouldEnforce = !routeConfig.observe;
+      if (routeConfig.observe && (!config.evaluateAlwaysIfCredentialed || !credentials.astraId)) {
         if (config.setPassThroughHeader) {
           res.setHeader("X-Astra-Gateway-Mode", "unenforced");
-          res.setHeader("X-Astra-Gateway-Reason", "route-none");
+          res.setHeader("X-Astra-Gateway-Reason", "route-observe");
         }
         beaconPassThrough?.(req);
         return next();
@@ -2102,7 +1967,6 @@ function createMiddleware(options) {
         const result2 = {
           identityVerified: false,
           policyAllowed: false,
-          accessLevel: "none",
           denialReasons: preCheckFailures.map((f) => f.message),
           guidance: {
             message: "Request exceeds counterparty-defined PDLSS limits.",
@@ -2265,7 +2129,6 @@ function createMiddleware(options) {
         const result = {
           identityVerified: false,
           policyAllowed: false,
-          accessLevel: "none",
           denialReasons: [`Verification middleware internal error: ${errorClass}`],
           failures: [
             {
@@ -2594,7 +2457,7 @@ function createMiddleware2(options) {
       beaconPassThrough?.(request, pathname);
       return NextResponse.next();
     }
-    if (routeConfig.minAccessLevel === "none") {
+    if (routeConfig.observe) {
       beaconPassThrough?.(request, pathname);
       return NextResponse.next();
     }
@@ -2624,7 +2487,6 @@ function createMiddleware2(options) {
       const preCheckResult = {
         identityVerified: false,
         policyAllowed: false,
-        accessLevel: "none",
         denialReasons: preCheckFailures.map((f) => f.message),
         guidance: {
           message: "Request exceeds counterparty-defined PDLSS limits.",
@@ -2762,7 +2624,6 @@ function createMiddleware2(options) {
     }
     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);
     }
@@ -2778,9 +2639,7 @@ var sdk_exports = {};
 __export(sdk_exports, {
   VerificationGatewayClient: () => VerificationGatewayClient,
   createClient: () => createClient,
-  getCapabilities: () => getCapabilities,
   getTrustLevel: () => getTrustLevel,
-  hasMinimumAccess: () => hasMinimumAccess,
   verifyOnce: () => verifyOnce
 });
 var VerificationGatewayClient = class {
@@ -2788,7 +2647,6 @@ var VerificationGatewayClient = class {
     this.config = {
       apiBaseUrl: options.apiBaseUrl,
       apiKey: options.apiKey,
-      defaultAccessLevel: options.defaultAccessLevel,
       minTrustScore: options.minTrustScore,
       minTrustScoreForFull: options.minTrustScoreForFull,
       cacheTtl: options.cacheTtl,
@@ -2837,26 +2695,6 @@ var VerificationGatewayClient = class {
   async quickVerify(credentials) {
     return this.executeWithRetry(() => quickVerify(this.config, credentials));
   }
-  /**
-   * Check if an agent has a specific access level.
-   *
-   * @deprecated 3.2.0 — the access-level band is informational only; it no
-   * longer gates in the middleware adapters (post-3.1.0 feedback #1). This
-   * explicit opt-in query still works, but prefer gating on the server-side
-   * policy decision (identity + policy + trust) or per-route `minTrustScore`.
-   * Explicit per-route condition→constraint rules are the Phase-2 successor.
-   */
-  async hasAccess(credentials, requiredLevel) {
-    const result = await this.quickVerify(credentials);
-    return hasMinimumAccess(result.accessLevel, requiredLevel);
-  }
-  /**
-   * Get capabilities for a verified agent
-   */
-  async getCapabilities(credentials) {
-    const result = await this.quickVerify(credentials);
-    return getCapabilities(result.accessLevel);
-  }
   /**
    * Verify a specific ASTRA-ID
    */
@@ -5584,18 +5422,13 @@ function mcpToPdlss(parsed, requestPath, headerPurpose, headerAction, toolGate)
   }
   return { purpose, action, resource, purposeSource, actionSource };
 }
-function mcpRiskTier(parsed) {
-  if (parsed.isInitialize || parsed.method === "notifications/initialized") return "none";
-  if (parsed.isIntrospection) return "none";
-  if (parsed.method === "resources/read") return "read-only";
-  if (parsed.isToolCall) return "standard";
-  return "standard";
+function mcpDefaultEnforced(parsed) {
+  if (parsed.isInitialize || parsed.method === "notifications/initialized") return false;
+  if (parsed.isIntrospection) return false;
+  return true;
 }
 
 // src/adapters/mcp.ts
-function normalizeToolGate(gate) {
-  return typeof gate === "string" ? { minAccessLevel: gate } : gate;
-}
 function readSingleHeader(value) {
   if (typeof value === "string") return value;
   if (Array.isArray(value)) return value[0];
@@ -5648,7 +5481,6 @@ function defaultMcpDenied(result, req, res) {
       code: !result.identityVerified ? -32e3 : -32001,
       message: result.denialReasons?.[0] ?? "Access denied",
       data: {
-        accessLevel: result.accessLevel,
         guidance: result.guidance,
         // Round-10: aggregated per-dimension detail + correlation handle.
         failures: result.failures,
@@ -5661,20 +5493,19 @@ function defaultMcpDenied(result, req, res) {
     }
   });
 }
-function resolveMinAccessLevel(parsed, opts) {
+function resolveGate(parsed, opts) {
   if (!parsed.toolName) {
-    if (opts.methodGates && opts.methodGates[parsed.method] !== void 0) {
-      return { level: opts.methodGates[parsed.method], source: "methodGate" };
+    const methodGate = opts.methodGates?.[parsed.method];
+    if (methodGate !== void 0) {
+      return methodGate === "observe" ? { enforce: false, source: "methodGate" } : { enforce: true, config: methodGate, source: "methodGate" };
     }
-    return { level: "none", source: "discovery_default" };
+    return { enforce: false, source: "discovery_default" };
   }
-  if (opts.toolGates && opts.toolGates[parsed.toolName] !== void 0) {
-    return {
-      level: normalizeToolGate(opts.toolGates[parsed.toolName]).minAccessLevel,
-      source: "toolGate"
-    };
+  const toolGate = opts.toolGates?.[parsed.toolName];
+  if (toolGate !== void 0) {
+    return toolGate === "observe" ? { enforce: false, source: "toolGate" } : { enforce: true, config: toolGate, source: "toolGate" };
   }
-  return { level: mcpRiskTier(parsed), source: "tier" };
+  return { enforce: mcpDefaultEnforced(parsed), source: "tier" };
 }
 function createMcpMiddleware(options) {
   const {
@@ -5694,15 +5525,6 @@ function createMcpMiddleware(options) {
     prefetchWellKnown(config.apiBaseUrl).catch(() => {
     });
   }
-  if (toolGates) {
-    for (const [toolName, gate] of Object.entries(toolGates)) {
-      if (typeof gate === "string") {
-        console.warn(
-          `[VerificationGateway/MCP] toolGates['${toolName}'] uses the bare-string shorthand ('${gate}'). Gated tools need a PDLSS purpose (else PDLSS_PURPOSE_REQUIRED 400) and evaluate purpose-only without a declared action. Use the object form instead: { minAccessLevel: '${gate}', purpose: '...', action: '...' }.`
-        );
-      }
-    }
-  }
   return async (req, res, next) => {
     try {
       if (skip) return next();
@@ -5751,7 +5573,7 @@ function createMcpMiddleware(options) {
           return next();
         }
       }
-      const { level: minAccessLevel } = resolveMinAccessLevel(parsed, {
+      const gateDecision = resolveGate(parsed, {
         toolGates,
         methodGates
       });
@@ -5760,16 +5582,15 @@ function createMcpMiddleware(options) {
         req.query
       );
       if (effectiveAstraId) credentials.astraId = effectiveAstraId;
-      const shouldEnforce = minAccessLevel !== "none";
-      if (minAccessLevel === "none" && (!config.evaluateAlwaysIfCredentialed || !credentials.astraId)) {
+      const shouldEnforce = gateDecision.enforce;
+      if (!shouldEnforce && (!config.evaluateAlwaysIfCredentialed || !credentials.astraId)) {
         if (config.setPassThroughHeader) {
           res.setHeader("X-Astra-Gateway-Mode", "unenforced");
-          res.setHeader("X-Astra-Gateway-Reason", "mcp-tier-none");
+          res.setHeader("X-Astra-Gateway-Reason", "mcp-observe");
         }
         return next();
       }
-      const rawGate = parsed.toolName && toolGates?.[parsed.toolName];
-      const gate = rawGate ? normalizeToolGate(rawGate) : void 0;
+      const gate = gateDecision.config;
       const headerPurpose = readSingleHeader(req.headers["x-astra-purpose"]);
       const headerAction = readSingleHeader(req.headers["x-astra-action"]);
       const pdlss = mcpToPdlss(
@@ -5905,7 +5726,6 @@ function createMcpMiddleware(options) {
         const result = {
           identityVerified: false,
           policyAllowed: false,
-          accessLevel: "none",
           denialReasons: [`MCP middleware internal error: ${errorClass}`],
           failures: [
             {
@@ -6661,8 +6481,6 @@ function detectRuntime(userAgent) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  ACCESS_LEVEL_DESCRIPTIONS,
-  ACCESS_LEVEL_HIERARCHY,
   AgentClient,
   AstraSync,
   AstraSyncError,
@@ -6670,7 +6488,6 @@ function detectRuntime(userAgent) {
   CAPTURE_SCHEMA_VERSION,
   ChallengeHandler,
   DEFAULT_EDGE_CONFIG,
-  DEFAULT_TRUST_THRESHOLDS,
   KYDRequiredError,
   MAX_HEADERS,
   MAX_HEADER_VALUE_BYTES,
@@ -6697,7 +6514,6 @@ function detectRuntime(userAgent) {
   deriveConnectionFromHeaders,
   detectPlatformFingerprint,
   detectRuntime,
-  determineAccessLevel,
   express,
   extractApiKeyFormat,
   extractCredentials,
@@ -6705,14 +6521,11 @@ function detectRuntime(userAgent) {
   extractPlatformHeaders,
   fetchEdgeConfig,
   fetchRoutes,
-  getAccessLevelForScore,
   getCachedWellKnownUrls,
-  getCapabilities,
   getEdgeConfig,
   getTrustLevel,
   getWellKnownUrls,
   hasCredentials,
-  hasMinimumAccess,
   isEdgeConfig,
   isVerifiedHopValidFor,
   matchEdgePathRule,