@astrasyncai/verification-gateway 5.11.0 → 5.12.0

package/README.md

@@ -272,6 +272,10 @@ import express from 'express';
 import { createMcpMiddleware } from '@astrasyncai/verification-gateway/mcp';
 
 const mcp = express();
+// Behind a load balancer / CDN, set trust proxy to your real hop count so
+// req.ip (the client IP recorded on verify-access) is the caller, not the
+// proxy. The middleware never trusts a raw leftmost X-Forwarded-For over it.
+mcp.set('trust proxy', 1);
 mcp.use(express.json());
 mcp.use(
   createMcpMiddleware({

package/dist/adapters/express.d.mts

@@ -1,5 +1,5 @@
 import { RequestHandler, Request } from 'express';
-import { d as VerificationResult, E as ExpressMiddlewareOptions, a as AstraSyncCredentials } from '../types-CTmUpNpS.mjs';
+import { d as VerificationResult, E as ExpressMiddlewareOptions, a as AstraSyncCredentials } from '../types-BCkwBA84.mjs';
 
 /**
  * AstraSync Universal Verification Gateway - Express Middleware

package/dist/adapters/express.d.ts

@@ -1,5 +1,5 @@
 import { RequestHandler, Request } from 'express';
-import { d as VerificationResult, E as ExpressMiddlewareOptions, a as AstraSyncCredentials } from '../types-CTmUpNpS.js';
+import { d as VerificationResult, E as ExpressMiddlewareOptions, a as AstraSyncCredentials } from '../types-BCkwBA84.js';
 
 /**
  * AstraSync Universal Verification Gateway - Express Middleware

package/dist/adapters/express.js

@@ -26,7 +26,7 @@ __export(express_exports, {
 module.exports = __toCommonJS(express_exports);
 
 // src/version.ts
-var SDK_VERSION = "5.11.0";
+var SDK_VERSION = "5.12.0";
 
 // src/http.ts
 var SDK_USER_AGENT = `astrasync-sdk/${SDK_VERSION}`;
@@ -171,6 +171,59 @@ function getCachedWellKnownUrls(apiBaseUrl) {
   return cache.get(apiBaseUrl)?.data;
 }
 
+// src/failure-posture.ts
+var VERIFICATION_STATUS_HEADER = "X-Astra-Verification";
+var DEFAULT_UNAVAILABLE_RETRY_AFTER_S = 30;
+var REJECTED_IDENTITY_DIMENSIONS = /* @__PURE__ */ new Set([
+  "identity.invalid_agent_id",
+  "identity.unknown_agent",
+  "agent.lookup"
+]);
+var UNKNOWN_AGENT_GUIDANCE = "Register your agent with AstraSync (or, inside an MCP host, add the AstraSync MCP connector for keyless, human-approved registration), then present the canonical ASTRA-* id issued after owner approval.";
+var UNAVAILABLE_DIMENSIONS = /* @__PURE__ */ new Set([
+  "verify_access.api_error",
+  "middleware.internal_error"
+]);
+function isVerificationUnavailable(result) {
+  if (result.misconfigured) return false;
+  return (result.failures ?? []).some((f) => UNAVAILABLE_DIMENSIONS.has(f.dimension));
+}
+function unavailableRetryAfterSeconds(result) {
+  if (typeof result.retryAfterMs === "number" && Number.isFinite(result.retryAfterMs)) {
+    return Math.max(1, Math.ceil(result.retryAfterMs / 1e3));
+  }
+  return DEFAULT_UNAVAILABLE_RETRY_AFTER_S;
+}
+function isAnonymousRead(method, credentials) {
+  const m = (method ?? "").toUpperCase();
+  if (m !== "GET" && m !== "HEAD") return false;
+  return !credentials.astraId && !credentials.jwt;
+}
+function buildVerificationUnavailableBody(result) {
+  return {
+    success: false,
+    error: {
+      code: "VERIFICATION_UNAVAILABLE",
+      message: "Agent verification is temporarily unavailable and this path enforces verification. Your identity was not evaluated and no denial was recorded \u2014 retry after the Retry-After interval.",
+      retryable: true,
+      retryAfterSeconds: unavailableRetryAfterSeconds(result),
+      ...result.failures && { failures: result.failures },
+      ...result.correlationId && { correlationId: result.correlationId },
+      guidance: {
+        message: "Retry the request after the Retry-After interval, with exponential backoff; the condition is transient."
+      }
+    }
+  };
+}
+function isRejectedIdentityClaim(result) {
+  return (result.failures ?? []).some((f) => REJECTED_IDENTITY_DIMENSIONS.has(f.dimension));
+}
+function denyStatusFor(result, policyDeniedCode) {
+  if (isRejectedIdentityClaim(result)) return { status: 403, code: "AGENT_IDENTITY_REJECTED" };
+  if (result.identityVerified) return { status: 403, code: policyDeniedCode };
+  return { status: 401, code: "UNAUTHORIZED" };
+}
+
 // src/verify.ts
 var DEFAULT_CONFIG = {
   apiBaseUrl: "https://astrasync.ai/api",
@@ -416,11 +469,44 @@ function createGuidanceResponse(_config, reason, options = {}) {
     // coercing the absent recommendation to a policy 'deny'. Misconfig is
     // deterministic and intentionally NOT marked retryable.
     ...isApiError && { retryable: true },
+    ...options.httpStatus !== void 0 && { httpStatus: options.httpStatus },
+    ...options.retryAfterMs !== void 0 && { retryAfterMs: options.retryAfterMs },
     correlationId: options.correlationId,
     attemptId: options.attemptId,
     verifiedAt: /* @__PURE__ */ new Date()
   };
 }
+async function readJsonSafe(response) {
+  try {
+    const parsed = await response.json();
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function rejectedIdentityGuidance(failures) {
+  const f = failures?.find((x) => REJECTED_IDENTITY_DIMENSIONS.has(x.dimension));
+  if (!f) return void 0;
+  if (f.dimension === "agent.lookup") {
+    return `The presented agent identifier is not registered with AstraSync. ${UNKNOWN_AGENT_GUIDANCE}`;
+  }
+  return f.guidance ? `${f.message} ${f.guidance}` : f.message;
+}
+var MAX_RETRY_AFTER_MS = 15 * 60 * 1e3;
+function parseRetryAfterMs(response) {
+  const raw = response.headers?.get?.("retry-after");
+  if (!raw) return void 0;
+  const trimmed = raw.trim();
+  let ms;
+  if (/^\d+(\.\d+)?$/.test(trimmed)) {
+    ms = Number(trimmed) * 1e3;
+  } else {
+    const at = Date.parse(trimmed);
+    if (Number.isNaN(at)) return void 0;
+    ms = at - Date.now();
+  }
+  return Math.min(MAX_RETRY_AFTER_MS, Math.max(0, Math.round(ms)));
+}
 async function callVerifyAccessAPI(config, request) {
   const { credentials, ...requestData } = request;
   const body = {
@@ -477,7 +563,8 @@ async function callVerifyAccessAPI(config, request) {
       body: JSON.stringify(body),
       signal: AbortSignal.timeout(config.verifyTimeoutMs ?? 1e4)
     });
-    const data = await response.json();
+    const data = await readJsonSafe(response);
+    const retryAfterMs = parseRetryAfterMs(response);
     if (response.status === 410) {
       return {
         success: true,
@@ -515,6 +602,23 @@ async function callVerifyAccessAPI(config, request) {
         }
       };
     }
+    if (response.status === 404 && credentials.astraId && (data?.error === "AGENT_NOT_FOUND" || typeof data?.message === "string" && /agent/i.test(data.message))) {
+      return {
+        success: true,
+        attemptId: typeof data?.attemptId === "string" ? data.attemptId : void 0,
+        access: {
+          allowed: false,
+          reason: "unknown_agent",
+          failures: [
+            {
+              dimension: "identity.unknown_agent",
+              message: "The presented agent identifier is not registered with AstraSync.",
+              guidance: UNKNOWN_AGENT_GUIDANCE
+            }
+          ]
+        }
+      };
+    }
     if (!response.ok) {
       if (response.status === 401) {
         return {
@@ -529,9 +633,11 @@ async function callVerifyAccessAPI(config, request) {
       }
       return {
         success: false,
-        error: data.message || data.error || `API returned ${response.status}`,
+        error: typeof data?.message === "string" && data.message || typeof data?.error === "string" && data.error || `API returned ${response.status}`,
         correlationId: typeof data?.correlationId === "string" ? data.correlationId : void 0,
-        attemptId: typeof data?.attemptId === "string" ? data.attemptId : void 0
+        attemptId: typeof data?.attemptId === "string" ? data.attemptId : void 0,
+        httpStatus: response.status,
+        ...retryAfterMs !== void 0 && { retryAfterMs }
       };
     }
     return data;
@@ -603,12 +709,14 @@ async function verify(config, request, options) {
       correlationId: apiResponse.correlationId,
       attemptId: apiResponse.attemptId,
       remediation: apiResponse.remediation,
+      httpStatus: apiResponse.httpStatus,
+      retryAfterMs: apiResponse.retryAfterMs,
       urls
     });
   }
   if (!apiResponse.access?.allowed) {
     const aggregatedFailures = apiResponse.access?.failures;
-    const idVerifiedFromBackend = apiResponse.verificationContext?.idVerified === true;
+    const idVerifiedFromBackend = apiResponse.verificationContext?.idVerified === true && !aggregatedFailures?.some((f) => REJECTED_IDENTITY_DIMENSIONS.has(f.dimension));
     const result2 = {
       identityVerified: idVerifiedFromBackend,
       policyAllowed: false,
@@ -620,7 +728,10 @@ async function verify(config, request, options) {
       requiresStepUp: apiResponse.access?.requiresStepUp,
       requiresApproval: apiResponse.access?.requiresApproval,
       guidance: {
-        message: apiResponse.access?.reason || "Access denied by PDLSS policy",
+        // 5.12.0: a presented-but-rejected id (malformed / unknown) carries
+        // actionable registration guidance on its failure — surface it
+        // instead of the bare machine reason ('unknown_agent').
+        message: rejectedIdentityGuidance(aggregatedFailures) ?? (apiResponse.access?.reason || "Access denied by PDLSS policy"),
         registrationUrl: urls?.registrationUrl ?? "",
         documentationUrl: urls?.documentationUrl ?? "",
         // 5.1.0: anonymous callers land on this branch — steer MCP-hosted
@@ -720,7 +831,7 @@ async function verify(config, request, options) {
       registrationUrl: urls?.registrationUrl ?? "",
       documentationUrl: urls?.documentationUrl ?? ""
     };
-  } else if (result.recommendation === "step_up_required") {
+  } else if (result.recommendation === "step_up_required" && result.identityVerified) {
     result.requiresStepUp = true;
     result.denialReasons = serverDenialReasons ?? result.recommendationReasons ?? ["Step-up verification required"];
   }
@@ -772,7 +883,10 @@ async function reportUnregisteredAttempt(config, data) {
   };
   await sdkFetch(`${apiBaseUrl}/verification-activity/unregistered-attempt`, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers: {
+      "Content-Type": "application/json",
+      ...config.apiKey && { Authorization: `Bearer ${config.apiKey}` }
+    },
     body: JSON.stringify(body)
   }).catch(() => {
   });
@@ -1362,7 +1476,10 @@ var PLATFORM_AGENT_SIGNATURES = [
   {
     vendor: "chatgpt",
     displayName: "OpenAI ChatGPT",
-    uaPatterns: [/chatgpt/i, /openai/i, /gpt-?\d/i],
+    // GPTBot (training crawler) and OAI-SearchBot (ChatGPT search) are
+    // OpenAI's declared crawler UAs — `gpt-?\d` never matched them, so they
+    // classified as unattributed crawlers (round-27.4 W5).
+    uaPatterns: [/chatgpt/i, /openai/i, /gpt-?\d/i, /\bGPTBot\b/i, /\bOAI-SearchBot\b/i],
     agentCardPatterns: [/openai\.com/i, /chatgpt\.com/i],
     apiKeyFormatPatterns: [/^sk-proj/i, /^sk-svcacct/i],
     headerPatterns: [/^openai-organization/i, /^openai-project/i, /^openai-version/i]
@@ -1497,6 +1614,215 @@ var BROWSER_UA_PATTERN = /mozilla\/\d/i;
 var _patterns = { STATIC_EXTENSIONS, BOT_UA_PATTERN, BROWSER_UA_PATTERN, SELF_UA_PATTERN };
 
 // src/edge-core/events.ts
+async function withBudget(promise, ms) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(void 0), ms);
+      })
+    ]);
+  } catch {
+    return void 0;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+var destKeyOf = (d) => `${d.apiBaseUrl}\0${d.apiKey ?? ""}\0${d.counterparty}\0${d.adapter ?? ""}`;
+var BeaconBuffer = class {
+  constructor(options = {}) {
+    this.queue = [];
+    this.droppedSinceLast = 0;
+    this.droppedTotal = 0;
+    this.deliveredTotal = 0;
+    this.backoffUntil = 0;
+    this.collapse = /* @__PURE__ */ new Map();
+    /** Keys the backend answered 401 for — later batches go unauthenticated. */
+    this.rejectedKeys = /* @__PURE__ */ new Set();
+    this.opts = {
+      maxItems: options.maxItems ?? 1e3,
+      maxBatch: options.maxBatch ?? 100,
+      maxAttempts: options.maxAttempts ?? 3,
+      collapseWindowMs: options.collapseWindowMs ?? 6e4,
+      collapseMaxKeys: options.collapseMaxKeys ?? 1e3,
+      requestTimeoutMs: options.requestTimeoutMs ?? 1e4,
+      retryBackoffMs: options.retryBackoffMs ?? 1e3,
+      now: options.now ?? Date.now
+    };
+  }
+  /**
+   * Queue one beacon. With a `collapseKey`, a repeat inside the window is
+   * merged into a held aggregate (sent when the window closes) instead of
+   * becoming its own item.
+   */
+  enqueue(dest, item, collapseKey) {
+    const now = this.opts.now();
+    if (collapseKey) {
+      const entry = this.collapse.get(collapseKey);
+      if (entry && now - entry.firstSeenAt < this.opts.collapseWindowMs) {
+        for (const target of [entry.first, entry.held]) {
+          if (target && !target.inFlight && this.queue.includes(target)) {
+            target.item.repeatCount = (target.item.repeatCount ?? 1) + 1;
+            return;
+          }
+        }
+        const held = this.push(
+          dest,
+          { ...item, repeatCount: 1 },
+          entry.firstSeenAt + this.opts.collapseWindowMs
+        );
+        entry.held = held;
+        return;
+      }
+      this.collapse.delete(collapseKey);
+      if (this.collapse.size >= this.opts.collapseMaxKeys) {
+        const oldest = this.collapse.keys().next().value;
+        if (oldest !== void 0) this.collapse.delete(oldest);
+      }
+      const fresh = { firstSeenAt: now };
+      this.collapse.set(collapseKey, fresh);
+      fresh.first = this.push(dest, item, now);
+      return;
+    }
+    this.push(dest, item, now);
+  }
+  /**
+   * Deliver every eligible queued item. Concurrent callers share ONE
+   * in-flight drain (it survives the caller's budget and a Lambda freeze),
+   * so nothing in flight is ever sent twice; items queued while it runs are
+   * picked up by the same drain.
+   */
+  flush() {
+    if (!this.inFlight) {
+      this.inFlight = this.drain().finally(() => {
+        this.inFlight = void 0;
+      });
+    }
+    return this.inFlight;
+  }
+  /** Counters for tests and diagnostics. */
+  stats() {
+    return {
+      queueDepth: this.queue.length,
+      droppedSinceLast: this.droppedSinceLast,
+      droppedTotal: this.droppedTotal,
+      deliveredTotal: this.deliveredTotal,
+      flushing: this.inFlight !== void 0
+    };
+  }
+  push(dest, item, eligibleAt) {
+    while (this.queue.length >= this.opts.maxItems) this.dropOldest();
+    const entry = {
+      dest,
+      destKey: destKeyOf(dest),
+      item,
+      attempts: 0,
+      eligibleAt,
+      inFlight: false
+    };
+    this.queue.push(entry);
+    return entry;
+  }
+  dropOldest() {
+    if (this.queue.shift()) this.countDropped(1);
+  }
+  countDropped(n) {
+    this.droppedSinceLast += n;
+    this.droppedTotal += n;
+  }
+  async drain() {
+    for (; ; ) {
+      const now = this.opts.now();
+      if (now < this.backoffUntil) return;
+      const batch = this.takeBatch(now);
+      if (batch.length === 0) return;
+      const ok = await this.send(batch);
+      if (!ok) return;
+    }
+  }
+  /** Oldest eligible item + up to maxBatch-1 more for the same destination. */
+  takeBatch(now) {
+    const first = this.queue.find((q) => q.eligibleAt <= now);
+    if (!first) return [];
+    const batch = [];
+    const rest = [];
+    for (const q of this.queue) {
+      if (batch.length < this.opts.maxBatch && q.destKey === first.destKey && q.eligibleAt <= now) {
+        q.inFlight = true;
+        batch.push(q);
+      } else {
+        rest.push(q);
+      }
+    }
+    this.queue = rest;
+    return batch;
+  }
+  /** POST one batch. Returns false when the drain should pause (backoff). */
+  async send(batch) {
+    const dest = batch[0].dest;
+    const useKey = dest.apiKey && !this.rejectedKeys.has(dest.apiKey) ? dest.apiKey : void 0;
+    const reportedDropped = this.droppedSinceLast;
+    const meta = {
+      droppedSinceLast: reportedDropped,
+      queueDepth: this.queue.length,
+      adapter: dest.adapter ?? "edge-core",
+      version: SDK_VERSION
+    };
+    const controller = typeof AbortController !== "undefined" ? new AbortController() : void 0;
+    const response = await withBudget(
+      sdkFetch(`${dest.apiBaseUrl}/verification-activity/edge-events`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...useKey && { Authorization: `Bearer ${useKey}` }
+        },
+        body: JSON.stringify({ events: batch.map((q) => q.item), meta }),
+        ...controller && { signal: controller.signal }
+      }),
+      this.opts.requestTimeoutMs
+    );
+    if (!response) controller?.abort();
+    const status = response?.status;
+    for (const q of batch) q.inFlight = false;
+    if (status !== void 0 && status >= 200 && status < 300) {
+      this.droppedSinceLast = Math.max(0, this.droppedSinceLast - reportedDropped);
+      this.deliveredTotal += batch.length;
+      return true;
+    }
+    if (status === 401 && useKey) {
+      this.rejectedKeys.add(useKey);
+      this.requeue(batch, false);
+      return true;
+    }
+    if (status === 429) {
+      const retryAfter = Number(response?.headers.get("retry-after"));
+      const waitMs = Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter, 120) * 1e3 : 3e4;
+      this.backoffUntil = this.opts.now() + waitMs;
+      this.requeue(batch, false);
+      return false;
+    }
+    if (status !== void 0 && status >= 400 && status < 500) {
+      this.countDropped(batch.length);
+      return true;
+    }
+    this.backoffUntil = this.opts.now() + this.opts.retryBackoffMs;
+    this.requeue(batch, true);
+    return false;
+  }
+  /** Put a failed batch back at the head of the queue (order preserved). */
+  requeue(batch, countAttempt) {
+    const keep = [];
+    for (const q of batch) {
+      if (countAttempt) q.attempts += 1;
+      if (q.attempts >= this.opts.maxAttempts) this.countDropped(1);
+      else keep.push(q);
+    }
+    this.queue = [...keep, ...this.queue];
+    while (this.queue.length > this.opts.maxItems) this.dropOldest();
+  }
+};
+var beaconBuffer = new BeaconBuffer();
 function sampled(rate, random = Math.random) {
   if (rate <= 0) return false;
   if (rate >= 1) return true;
@@ -1673,12 +1999,19 @@ function defaultOnDenied(result, _req, res) {
     });
     return;
   }
-  const statusCode = !result.identityVerified ? 401 : 403;
+  if (isVerificationUnavailable(result)) {
+    res.setHeader("X-Astra-Gateway-Mode", "enforced");
+    res.setHeader(VERIFICATION_STATUS_HEADER, "unavailable");
+    res.setHeader("Retry-After", String(unavailableRetryAfterSeconds(result)));
+    res.status(503).json(buildVerificationUnavailableBody(result));
+    return;
+  }
+  const { status: statusCode, code } = denyStatusFor(result, "INSUFFICIENT_ACCESS");
   res.setHeader("X-Astra-Gateway-Mode", "enforced");
   res.status(statusCode).json({
     success: false,
     error: {
-      code: !result.identityVerified ? "UNAUTHORIZED" : "INSUFFICIENT_ACCESS",
+      code,
       message: result.denialReasons?.[0] || "Access denied",
       guidance: result.guidance,
       // Round-10: aggregated per-dimension detail + correlation handle.
@@ -1926,6 +2259,21 @@ function createMiddleware(options) {
           result.stepUpOutcome = outcome;
         }
       }
+      if (!result.policyAllowed && isVerificationUnavailable(result) && (!shouldEnforce || isAnonymousRead(req.method, credentials))) {
+        res.setHeader(VERIFICATION_STATUS_HEADER, "unavailable");
+        return next();
+      }
+      if (!shouldEnforce) {
+        if (config.setPassThroughHeader) {
+          res.setHeader("X-Astra-Gateway-Mode", "enforced");
+          res.setHeader("X-Astra-Gateway-Reason", "evaluated-not-enforced");
+        }
+        if (shouldRecordDecisions && sessionId) {
+          recordDecision(config, sessionId, "granted").catch(() => {
+          });
+        }
+        return next();
+      }
       if (!result.policyAllowed) {
         if (shouldRecordDecisions && sessionId) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
@@ -1945,17 +2293,6 @@ function createMiddleware(options) {
         onDenied(result, req, res);
         return;
       }
-      if (!shouldEnforce) {
-        if (config.setPassThroughHeader) {
-          res.setHeader("X-Astra-Gateway-Mode", "enforced");
-          res.setHeader("X-Astra-Gateway-Reason", "evaluated-not-enforced");
-        }
-        if (shouldRecordDecisions && sessionId) {
-          recordDecision(config, sessionId, "granted").catch(() => {
-          });
-        }
-        return next();
-      }
       if (routeConfig.minTrustScore && result.agent) {
         if (result.agent.trustScore < routeConfig.minTrustScore) {
           const trustFailure = {
@@ -2011,14 +2348,6 @@ function createMiddleware(options) {
           verifiedAt: /* @__PURE__ */ new Date(),
           correlationId
         };
-        const catchUrls = config.apiBaseUrl ? await getWellKnownUrls(config.apiBaseUrl).catch(() => void 0) : void 0;
-        if (catchUrls) {
-          result.guidance = {
-            message: `Middleware threw ${errorClass} \u2014 failing closed`,
-            registrationUrl: catchUrls.registrationUrl,
-            documentationUrl: catchUrls.documentationUrl
-          };
-        }
         dedupeFailures(result);
         return onDenied(result, req, res);
       }