@astrasyncai/verification-gateway 5.11.0 → 5.12.0

package/dist/{types-CTmUpNpS.d.mts → types-BCkwBA84.d.mts}

@@ -458,6 +458,18 @@ interface VerificationResult {
      * on misconfig (deterministic — retrying will not help) and on real denials.
      */
     retryable?: boolean;
+    /**
+     * 5.12.0: HTTP status the verify-access backend answered with on a
+     * non-2xx (e.g. 429, 503). Lets adapters and integrators tell a platform
+     * rate limit apart from an outage. Absent on network errors / timeouts.
+     */
+    httpStatus?: number;
+    /**
+     * 5.12.0: the backend's `Retry-After`, in milliseconds, when it sent one
+     * (429 / 503). Adapters relay it on their own 503 so callers back off for
+     * as long as the platform asked.
+     */
+    retryAfterMs?: number;
     /** Whether step-up authentication is required */
     requiresStepUp?: boolean;
     /** Whether approval is required */

package/dist/{types-CTmUpNpS.d.ts → types-BCkwBA84.d.ts}

@@ -458,6 +458,18 @@ interface VerificationResult {
      * on misconfig (deterministic — retrying will not help) and on real denials.
      */
     retryable?: boolean;
+    /**
+     * 5.12.0: HTTP status the verify-access backend answered with on a
+     * non-2xx (e.g. 429, 503). Lets adapters and integrators tell a platform
+     * rate limit apart from an outage. Absent on network errors / timeouts.
+     */
+    httpStatus?: number;
+    /**
+     * 5.12.0: the backend's `Retry-After`, in milliseconds, when it sent one
+     * (429 / 503). Adapters relay it on their own 503 so callers back off for
+     * as long as the platform asked.
+     */
+    retryAfterMs?: number;
     /** Whether step-up authentication is required */
     requiresStepUp?: boolean;
     /** Whether approval is required */

package/dist/{types-CtFXmDzm.d.ts → types-C_b4QTyO.d.ts}

@@ -400,6 +400,18 @@ interface VerificationResult {
      * on misconfig (deterministic — retrying will not help) and on real denials.
      */
     retryable?: boolean;
+    /**
+     * 5.12.0: HTTP status the verify-access backend answered with on a
+     * non-2xx (e.g. 429, 503). Lets adapters and integrators tell a platform
+     * rate limit apart from an outage. Absent on network errors / timeouts.
+     */
+    httpStatus?: number;
+    /**
+     * 5.12.0: the backend's `Retry-After`, in milliseconds, when it sent one
+     * (429 / 503). Adapters relay it on their own 503 so callers back off for
+     * as long as the platform asked.
+     */
+    retryAfterMs?: number;
     /** Whether step-up authentication is required */
     requiresStepUp?: boolean;
     /** Whether approval is required */
@@ -764,6 +776,12 @@ interface AttemptReport {
     agentId?: string;
     considerationSet?: ConsiderationSet;
     outcome?: AttemptOutcome;
+    /**
+     * Where a catalog view was answered from: `bridge_cache` (the AstraSync
+     * bridge's anonymous cache — no load on the merchant's site) or `merchant`
+     * (fetched fresh). Attribution only.
+     */
+    servedFrom?: 'bridge_cache' | 'merchant';
 }
 /**
  * Raw commerce-protocol artifacts as verify-access accepts them (backend

package/dist/{types-DQrn_kei.d.mts → types-DlshIIR-.d.mts}

@@ -400,6 +400,18 @@ interface VerificationResult {
      * on misconfig (deterministic — retrying will not help) and on real denials.
      */
     retryable?: boolean;
+    /**
+     * 5.12.0: HTTP status the verify-access backend answered with on a
+     * non-2xx (e.g. 429, 503). Lets adapters and integrators tell a platform
+     * rate limit apart from an outage. Absent on network errors / timeouts.
+     */
+    httpStatus?: number;
+    /**
+     * 5.12.0: the backend's `Retry-After`, in milliseconds, when it sent one
+     * (429 / 503). Adapters relay it on their own 503 so callers back off for
+     * as long as the platform asked.
+     */
+    retryAfterMs?: number;
     /** Whether step-up authentication is required */
     requiresStepUp?: boolean;
     /** Whether approval is required */
@@ -764,6 +776,12 @@ interface AttemptReport {
     agentId?: string;
     considerationSet?: ConsiderationSet;
     outcome?: AttemptOutcome;
+    /**
+     * Where a catalog view was answered from: `bridge_cache` (the AstraSync
+     * bridge's anonymous cache — no load on the merchant's site) or `merchant`
+     * (fetched fresh). Attribution only.
+     */
+    servedFrom?: 'bridge_cache' | 'merchant';
 }
 /**
  * Raw commerce-protocol artifacts as verify-access accepts them (backend

package/dist/ui/index.d.mts

@@ -1,4 +1,4 @@
-import { V as VerificationInterstitialProps, d as VerificationResult, A as AgentCredentials, b as GuidanceInfo, T as TrustLevel } from '../types-CTmUpNpS.mjs';
+import { V as VerificationInterstitialProps, d as VerificationResult, A as AgentCredentials, b as GuidanceInfo, T as TrustLevel } from '../types-BCkwBA84.mjs';
 
 /**
  * AstraSync Verification Interstitial Component

package/dist/ui/index.d.ts

@@ -1,4 +1,4 @@
-import { V as VerificationInterstitialProps, d as VerificationResult, A as AgentCredentials, b as GuidanceInfo, T as TrustLevel } from '../types-CTmUpNpS.js';
+import { V as VerificationInterstitialProps, d as VerificationResult, A as AgentCredentials, b as GuidanceInfo, T as TrustLevel } from '../types-BCkwBA84.js';
 
 /**
  * AstraSync Verification Interstitial Component

package/dist/verify.d.mts

@@ -1,4 +1,4 @@
-import { A as AgentCredentials, G as GatewayConfig, a as AttemptReport, V as VerificationRequest, c as VerificationResult } from './types-DQrn_kei.mjs';
+import { A as AgentCredentials, G as GatewayConfig, a as AttemptReport, V as VerificationRequest, c as VerificationResult } from './types-DlshIIR-.mjs';
 import { ObservedMetadata } from './metadata-capture.mjs';
 
 /**
@@ -22,6 +22,15 @@ declare function extractCredentials(headers: Record<string, string | string[] |
  * Check if credentials are present
  */
 declare function hasCredentials(credentials: AgentCredentials): boolean;
+/**
+ * 5.12.0: `Retry-After` (delta-seconds or HTTP-date) → milliseconds, or
+ * undefined when absent/unparseable. Clamped to [0, 15 min].
+ */
+declare function parseRetryAfterMs(response: {
+    headers?: {
+        get?(name: string): string | null;
+    };
+}): number | undefined;
 /**
  * Options for a single verify() call (as opposed to GatewayConfig, which is
  * per-gateway). Mirrors the Java SDK's `verify(request, bypassCache)`.
@@ -52,9 +61,24 @@ declare function recordDecision(config: GatewayConfig, sessionId: string, decisi
  * Authenticated with the same credentials as verify(); the backend responds
  * 202 and folds the data into the attempt chain keyed by `attemptId`.
  *
- * Fire-and-forget — errors are silently swallowed, never throws.
+ * Fire-and-forget — never throws. 5.12.0: a 429/5xx is retried once
+ * (Retry-After honoured, capped at 2s) off the caller's path; a lost report
+ * is surfaced via `options.onFailure`.
  */
-declare function reportAttempt(config: GatewayConfig, report: AttemptReport): Promise<void>;
+declare function reportAttempt(config: GatewayConfig, report: AttemptReport, options?: ReportAttemptOptions): Promise<void>;
+/** 5.12.0: options for {@link reportAttempt}. */
+interface ReportAttemptOptions {
+    /**
+     * Called once when the report is finally lost (non-retryable status,
+     * network error, or the single retry failed). For counters/telemetry;
+     * exceptions it throws are swallowed.
+     */
+    onFailure?: (failure: {
+        status?: number;
+        error?: string;
+        retried: boolean;
+    }) => void;
+}
 /**
  * Fetch the per-route policy for an endpoint from the AstraSync backend.
  * v2.9.7 moved policy authority into the dashboard — the SDK no longer
@@ -171,6 +195,13 @@ declare function quickVerify(config: GatewayConfig, credentials: AgentCredential
     identityVerified: boolean;
     policyAllowed: boolean;
     reason?: string;
+    /**
+     * 5.12.0: verification infrastructure was unavailable (timeout / 5xx /
+     * the platform's 429) — NOT a denial. Callers should fail open on reads
+     * or answer 503 + Retry-After (`retryAfterMs`, else 30s), never 401.
+     */
+    unavailable?: true;
+    retryAfterMs?: number;
 }>;
 
-export { type RouteAccessConfigShape, type VerifyOptions, _resetInitCheck, clearCache, extractCredentials, fetchRoutes, hasCredentials, quickVerify, recordDecision, reportAttempt, reportCounterpartyPreCheckFailure, reportUnregisteredAttempt, verify, verifyAndRecord };
+export { type ReportAttemptOptions, type RouteAccessConfigShape, type VerifyOptions, _resetInitCheck, clearCache, extractCredentials, fetchRoutes, hasCredentials, parseRetryAfterMs, quickVerify, recordDecision, reportAttempt, reportCounterpartyPreCheckFailure, reportUnregisteredAttempt, verify, verifyAndRecord };

package/dist/verify.d.ts

@@ -1,4 +1,4 @@
-import { A as AgentCredentials, G as GatewayConfig, a as AttemptReport, V as VerificationRequest, c as VerificationResult } from './types-CtFXmDzm.js';
+import { A as AgentCredentials, G as GatewayConfig, a as AttemptReport, V as VerificationRequest, c as VerificationResult } from './types-C_b4QTyO.js';
 import { ObservedMetadata } from './metadata-capture.js';
 
 /**
@@ -22,6 +22,15 @@ declare function extractCredentials(headers: Record<string, string | string[] |
  * Check if credentials are present
  */
 declare function hasCredentials(credentials: AgentCredentials): boolean;
+/**
+ * 5.12.0: `Retry-After` (delta-seconds or HTTP-date) → milliseconds, or
+ * undefined when absent/unparseable. Clamped to [0, 15 min].
+ */
+declare function parseRetryAfterMs(response: {
+    headers?: {
+        get?(name: string): string | null;
+    };
+}): number | undefined;
 /**
  * Options for a single verify() call (as opposed to GatewayConfig, which is
  * per-gateway). Mirrors the Java SDK's `verify(request, bypassCache)`.
@@ -52,9 +61,24 @@ declare function recordDecision(config: GatewayConfig, sessionId: string, decisi
  * Authenticated with the same credentials as verify(); the backend responds
  * 202 and folds the data into the attempt chain keyed by `attemptId`.
  *
- * Fire-and-forget — errors are silently swallowed, never throws.
+ * Fire-and-forget — never throws. 5.12.0: a 429/5xx is retried once
+ * (Retry-After honoured, capped at 2s) off the caller's path; a lost report
+ * is surfaced via `options.onFailure`.
  */
-declare function reportAttempt(config: GatewayConfig, report: AttemptReport): Promise<void>;
+declare function reportAttempt(config: GatewayConfig, report: AttemptReport, options?: ReportAttemptOptions): Promise<void>;
+/** 5.12.0: options for {@link reportAttempt}. */
+interface ReportAttemptOptions {
+    /**
+     * Called once when the report is finally lost (non-retryable status,
+     * network error, or the single retry failed). For counters/telemetry;
+     * exceptions it throws are swallowed.
+     */
+    onFailure?: (failure: {
+        status?: number;
+        error?: string;
+        retried: boolean;
+    }) => void;
+}
 /**
  * Fetch the per-route policy for an endpoint from the AstraSync backend.
  * v2.9.7 moved policy authority into the dashboard — the SDK no longer
@@ -171,6 +195,13 @@ declare function quickVerify(config: GatewayConfig, credentials: AgentCredential
     identityVerified: boolean;
     policyAllowed: boolean;
     reason?: string;
+    /**
+     * 5.12.0: verification infrastructure was unavailable (timeout / 5xx /
+     * the platform's 429) — NOT a denial. Callers should fail open on reads
+     * or answer 503 + Retry-After (`retryAfterMs`, else 30s), never 401.
+     */
+    unavailable?: true;
+    retryAfterMs?: number;
 }>;
 
-export { type RouteAccessConfigShape, type VerifyOptions, _resetInitCheck, clearCache, extractCredentials, fetchRoutes, hasCredentials, quickVerify, recordDecision, reportAttempt, reportCounterpartyPreCheckFailure, reportUnregisteredAttempt, verify, verifyAndRecord };
+export { type ReportAttemptOptions, type RouteAccessConfigShape, type VerifyOptions, _resetInitCheck, clearCache, extractCredentials, fetchRoutes, hasCredentials, parseRetryAfterMs, quickVerify, recordDecision, reportAttempt, reportCounterpartyPreCheckFailure, reportUnregisteredAttempt, verify, verifyAndRecord };

package/dist/verify.js

@@ -25,6 +25,7 @@ __export(verify_exports, {
   extractCredentials: () => extractCredentials,
   fetchRoutes: () => fetchRoutes,
   hasCredentials: () => hasCredentials,
+  parseRetryAfterMs: () => parseRetryAfterMs,
   quickVerify: () => quickVerify,
   recordDecision: () => recordDecision,
   reportAttempt: () => reportAttempt,
@@ -36,7 +37,7 @@ __export(verify_exports, {
 module.exports = __toCommonJS(verify_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}`;
@@ -71,6 +72,29 @@ function getCachedWellKnownUrls(apiBaseUrl) {
   return cache.get(apiBaseUrl)?.data;
 }
 
+// src/failure-posture.ts
+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;
+}
+
 // src/verify.ts
 var DEFAULT_CONFIG = {
   apiBaseUrl: "https://astrasync.ai/api",
@@ -325,11 +349,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 = {
@@ -386,7 +443,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,
@@ -424,6 +482,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 {
@@ -438,9 +513,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;
@@ -512,12 +589,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,
@@ -529,7 +608,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
@@ -629,7 +711,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"];
   }
@@ -652,7 +734,7 @@ async function recordDecision(config, sessionId, decision, reason) {
   }).catch(() => {
   });
 }
-async function reportAttempt(config, report) {
+async function reportAttempt(config, report, options = {}) {
   const apiBaseUrl = config.apiBaseUrl || DEFAULT_CONFIG.apiBaseUrl;
   const headers = { "Content-Type": "application/json" };
   if (config.apiKey) {
@@ -663,13 +745,37 @@ async function reportAttempt(config, report) {
     ...report,
     ...!report.counterpartyId && config.counterpartyId && { counterpartyId: config.counterpartyId }
   };
-  await sdkFetch(`${apiBaseUrl}/agents/verify-access/attempt-report`, {
-    method: "POST",
-    headers,
-    body: JSON.stringify(body)
-  }).catch(() => {
-  });
+  const url = `${apiBaseUrl}/agents/verify-access/attempt-report`;
+  const init = { method: "POST", headers, body: JSON.stringify(body) };
+  const fail = (failure) => {
+    try {
+      options.onFailure?.(failure);
+    } catch {
+    }
+  };
+  let response;
+  try {
+    response = await sdkFetch(url, init);
+  } catch (err) {
+    fail({ error: err instanceof Error ? err.message : String(err), retried: false });
+    return;
+  }
+  if (response.ok) return;
+  if (response.status !== 429 && response.status < 500) {
+    fail({ status: response.status, retried: false });
+    return;
+  }
+  const delayMs = Math.min(ATTEMPT_REPORT_MAX_RETRY_DELAY_MS, parseRetryAfterMs(response) ?? 500);
+  const timer = setTimeout(() => {
+    sdkFetch(url, init).then((retry) => {
+      if (!retry.ok) fail({ status: retry.status, retried: true });
+    }).catch((err) => {
+      fail({ error: err instanceof Error ? err.message : String(err), retried: true });
+    });
+  }, delayMs);
+  timer.unref?.();
 }
+var ATTEMPT_REPORT_MAX_RETRY_DELAY_MS = 2e3;
 async function fetchRoutes(config, counterpartyId) {
   if (!counterpartyId) return null;
   const headers = { "Content-Type": "application/json" };
@@ -714,7 +820,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(() => {
   });
@@ -736,7 +845,11 @@ async function quickVerify(config, credentials) {
   return {
     identityVerified: result.identityVerified,
     policyAllowed: result.policyAllowed,
-    reason: result.denialReasons?.[0]
+    reason: result.denialReasons?.[0],
+    ...isVerificationUnavailable(result) && {
+      unavailable: true,
+      retryAfterMs: unavailableRetryAfterSeconds(result) * 1e3
+    }
   };
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -746,6 +859,7 @@ async function quickVerify(config, credentials) {
   extractCredentials,
   fetchRoutes,
   hasCredentials,
+  parseRetryAfterMs,
   quickVerify,
   recordDecision,
   reportAttempt,