@astrasyncai/verification-gateway 5.11.0 → 5.12.0

package/dist/bin/astrasync.js

@@ -36,7 +36,7 @@ var SDK_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    SDK_VERSION = "5.11.0";
+    SDK_VERSION = "5.12.0";
   }
 });
 
@@ -5057,6 +5057,20 @@ var init_well_known = __esm({
   }
 });
 
+// src/failure-posture.ts
+var REJECTED_IDENTITY_DIMENSIONS, UNKNOWN_AGENT_GUIDANCE;
+var init_failure_posture = __esm({
+  "src/failure-posture.ts"() {
+    "use strict";
+    REJECTED_IDENTITY_DIMENSIONS = /* @__PURE__ */ new Set([
+      "identity.invalid_agent_id",
+      "identity.unknown_agent",
+      "agent.lookup"
+    ]);
+    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.";
+  }
+});
+
 // src/verify.ts
 async function performInitCheck(apiBaseUrl, debug, strictInit, apiKey) {
   initCheckPerformed = true;
@@ -5255,11 +5269,43 @@ 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;
+}
+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, request2) {
   const { credentials, ...requestData } = request2;
   const body = {
@@ -5316,7 +5362,8 @@ async function callVerifyAccessAPI(config, request2) {
       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,
@@ -5354,6 +5401,23 @@ async function callVerifyAccessAPI(config, request2) {
         }
       };
     }
+    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 {
@@ -5368,9 +5432,11 @@ async function callVerifyAccessAPI(config, request2) {
       }
       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;
@@ -5442,12 +5508,14 @@ async function verify(config, request2, 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,
@@ -5459,7 +5527,10 @@ async function verify(config, request2, 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
@@ -5559,7 +5630,7 @@ async function verify(config, request2, 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"];
   }
@@ -5569,7 +5640,7 @@ async function verify(config, request2, options) {
   }
   return result;
 }
-var DEFAULT_CONFIG, initCheckPerformed, deprecationWarningShown, verificationCache, DEFAULT_CACHE_TTL_SECONDS;
+var DEFAULT_CONFIG, initCheckPerformed, deprecationWarningShown, verificationCache, DEFAULT_CACHE_TTL_SECONDS, MAX_RETRY_AFTER_MS;
 var init_verify = __esm({
   "src/verify.ts"() {
     "use strict";
@@ -5577,6 +5648,7 @@ var init_verify = __esm({
     init_trust_levels();
     init_version();
     init_well_known();
+    init_failure_posture();
     DEFAULT_CONFIG = {
       apiBaseUrl: "https://astrasync.ai/api",
       // minTrustScore + minTrustScoreForFull deprecated in v2.3.0 — server decides.
@@ -5590,6 +5662,7 @@ var init_verify = __esm({
     deprecationWarningShown = false;
     verificationCache = /* @__PURE__ */ new Map();
     DEFAULT_CACHE_TTL_SECONDS = 60;
+    MAX_RETRY_AFTER_MS = 15 * 60 * 1e3;
   }
 });
 
@@ -5712,12 +5785,223 @@ var init_classify = __esm({
 });
 
 // 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, BeaconBuffer, beaconBuffer;
 var init_events = __esm({
   "src/edge-core/events.ts"() {
     "use strict";
+    init_http();
     init_metadata_capture();
-    init_verify();
+    init_version();
     init_request();
+    destKeyOf = (d) => `${d.apiBaseUrl}\0${d.apiKey ?? ""}\0${d.counterparty}\0${d.adapter ?? ""}`;
+    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();
+      }
+    };
+    beaconBuffer = new BeaconBuffer();
   }
 });
 
@@ -5749,6 +6033,7 @@ var init_express = __esm({
     init_well_known();
     init_metadata_capture();
     init_anonymous_beacon();
+    init_failure_posture();
     DEFAULT_ROUTES_REFRESH_MS = 5 * 60 * 1e3;
   }
 });
@@ -5764,6 +6049,7 @@ var init_nextjs = __esm({
     init_pdlss_pre_check();
     init_metadata_capture();
     init_anonymous_beacon();
+    init_failure_posture();
     init_http_pdlss();
     init_approval_gate();
     init_verified_hop();
@@ -6085,6 +6371,7 @@ var init_mcp2 = __esm({
     init_approval_gate();
     init_stepup_poll();
     init_well_known();
+    init_failure_posture();
     init_mcp_server();
   }
 });
@@ -6173,6 +6460,7 @@ var init_src = __esm({
     "use strict";
     init_trust_levels();
     init_verify();
+    init_failure_posture();
     init_stepup_poll();
     init_settlement();
     init_express();