@astrasyncai/verification-gateway 5.11.0 → 5.13.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,19 +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.
- */
-declare function reportAttempt(config: GatewayConfig, report: AttemptReport): Promise<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
- * accepts `routes` from merchant-side source code, it fetches them from
- * here on init (and refreshes periodically).
- *
- * Returns `null` when the request fails for any reason — the caller decides
- * how to fall back (the middleware allows-all when no policy is loaded so
- * a misconfigured init doesn't take down the merchant's API).
+ * 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, 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;
+}
 declare function fetchRoutes(config: GatewayConfig, counterpartyId: string): Promise<RouteAccessConfigShape[] | null>;
 /**
  * Minimal shape of an EndpointRoute as the SDK consumes it. Mirrors the
@@ -171,6 +185,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,19 +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.
- */
-declare function reportAttempt(config: GatewayConfig, report: AttemptReport): Promise<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
- * accepts `routes` from merchant-side source code, it fetches them from
- * here on init (and refreshes periodically).
- *
- * Returns `null` when the request fails for any reason — the caller decides
- * how to fall back (the middleware allows-all when no policy is loaded so
- * a misconfigured init doesn't take down the merchant's API).
+ * 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, 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;
+}
 declare function fetchRoutes(config: GatewayConfig, counterpartyId: string): Promise<RouteAccessConfigShape[] | null>;
 /**
  * Minimal shape of an EndpointRoute as the SDK consumes it. Mirrors the
@@ -171,6 +185,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.13.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",
@@ -86,7 +110,7 @@ function _resetInitCheck() {
   initCheckPerformed = false;
 }
 var deprecationWarningShown = false;
-async function performInitCheck(apiBaseUrl, debug, strictInit, apiKey) {
+async function performInitCheck(apiBaseUrl, debug, strictInit, apiKey, counterparty) {
   initCheckPerformed = true;
   try {
     const probeUrl = `${apiBaseUrl}/agents/verify-access`;
@@ -104,7 +128,8 @@ async function performInitCheck(apiBaseUrl, debug, strictInit, apiKey) {
       );
     }
     if (apiKey) {
-      const selfCheck = await sdkFetch(`${apiBaseUrl}/agents/verify-access/self-check`, {
+      const q = counterparty?.id ? `?counterpartyId=${encodeURIComponent(counterparty.id)}` : counterparty?.url ? `?counterpartyUrl=${encodeURIComponent(counterparty.url)}` : "";
+      const selfCheck = await sdkFetch(`${apiBaseUrl}/agents/verify-access/self-check${q}`, {
         headers: { Authorization: `Bearer ${apiKey}` }
       });
       if (selfCheck.status === 401) {
@@ -116,6 +141,13 @@ async function performInitCheck(apiBaseUrl, debug, strictInit, apiKey) {
         console.error(message);
       } else if (selfCheck.ok) {
         const body = await selfCheck.json().catch(() => ({}));
+        if (body.counterparty && body.counterparty.canVerify === false) {
+          const message = `[VerificationGateway] the configured AstraSync API key cannot verify for this endpoint (${body.counterparty.message ?? "endpoint not found or owned by another account"}). Every inbound agent will be turned away until the key or counterparty is corrected.`;
+          if (strictInit) {
+            throw new Error(`${message} (strictInit=true)`);
+          }
+          console.error(message);
+        }
         if (typeof body.daysToExpiry === "number" && body.daysToExpiry <= 7) {
           console.warn(
             `[VerificationGateway] the configured AstraSync API key expires in ${body.daysToExpiry} day(s) \u2014 rotate it at Settings \u2192 Developer Tools before integrations start failing.`
@@ -260,11 +292,11 @@ function createGuidanceResponse(_config, reason, options = {}) {
   const isMisconfig = source === "merchant_misconfig";
   const urls = options.urls;
   const guidance = isMisconfig ? {
-    message: "This site's AstraSync integration is misconfigured (its API key was revoked, expired, or rotated). Your identity and the AstraSync platform are fine \u2014 contact the site operator. Retrying will not help.",
+    message: "This site's AstraSync integration is misconfigured (its API key was revoked, expired, rotated, or belongs to another account). Your identity and the AstraSync platform are fine \u2014 contact the site operator. Retrying will not help.",
     registrationUrl: urls?.registrationUrl ?? "",
     documentationUrl: options.remediation?.docsUrl ?? urls?.documentationUrl ?? "",
     steps: [
-      "Report the failure to the site operator \u2014 their AstraSync API key needs rotating",
+      "Report the failure to the site operator \u2014 their AstraSync API key needs replacing",
       "Do not retry: the failure is deterministic until the operator updates their key"
     ]
   } : isApiError ? {
@@ -325,11 +357,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 +451,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,13 +490,31 @@ 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) {
+      const keyMismatch = response.status === 403 && data?.error === "COUNTERPARTY_KEY_MISMATCH";
+      if (response.status === 401 || keyMismatch) {
         return {
           success: false,
           error: data.message || data.error || "Integration API key rejected",
           misconfig: true,
-          misconfigCode: typeof data?.code === "string" ? data.code : void 0,
+          misconfigCode: keyMismatch ? "counterparty_key_mismatch" : typeof data?.code === "string" ? data.code : void 0,
           remediation: data?.remediation && typeof data.remediation === "object" ? data.remediation : void 0,
           correlationId: typeof data?.correlationId === "string" ? data.correlationId : void 0,
           attemptId: typeof data?.attemptId === "string" ? data.attemptId : void 0
@@ -438,9 +522,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;
@@ -461,14 +547,22 @@ async function verify(config, request, options) {
         mergedConfig.apiBaseUrl,
         mergedConfig.debug,
         true,
-        mergedConfig.apiKey
+        mergedConfig.apiKey,
+        {
+          id: mergedConfig.counterpartyId,
+          url: mergedConfig.counterpartyUrl ?? request.counterpartyUrl
+        }
       );
     } else {
       void performInitCheck(
         mergedConfig.apiBaseUrl,
         mergedConfig.debug,
         false,
-        mergedConfig.apiKey
+        mergedConfig.apiKey,
+        {
+          id: mergedConfig.counterpartyId,
+          url: mergedConfig.counterpartyUrl ?? request.counterpartyUrl
+        }
       );
     }
   }
@@ -512,12 +606,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 +625,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 +728,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 +751,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 +762,38 @@ 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;
+var refusedPolicyReads = /* @__PURE__ */ new Set();
 async function fetchRoutes(config, counterpartyId) {
   if (!counterpartyId) return null;
   const headers = { "Content-Type": "application/json" };
@@ -682,7 +806,15 @@ async function fetchRoutes(config, counterpartyId) {
       `${config.apiBaseUrl}/endpoints/${encodeURIComponent(counterpartyId)}/routes`,
       { method: "GET", headers }
     );
-    if (!response.ok) return null;
+    if (!response.ok) {
+      if ((response.status === 401 || response.status === 403 || response.status === 404) && !refusedPolicyReads.has(counterpartyId)) {
+        refusedPolicyReads.add(counterpartyId);
+        console.error(
+          `[VerificationGateway] the configured API key cannot read the route policy for ${counterpartyId} (HTTP ${response.status}). The key belongs to an account that does not own this endpoint, or the counterpartyId is wrong. The gateway is in PASS-THROUGH mode: no agent is being verified.`
+        );
+      }
+      return null;
+    }
     const body = await response.json();
     return body.data?.routes ?? [];
   } catch {
@@ -714,7 +846,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 +871,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 +885,7 @@ async function quickVerify(config, credentials) {
   extractCredentials,
   fetchRoutes,
   hasCredentials,
+  parseRetryAfterMs,
   quickVerify,
   recordDecision,
   reportAttempt,