@astrasyncai/verification-gateway 3.12.0 → 4.0.0

package/dist/bin/astrasync-claude-hook.js

@@ -3701,7 +3701,7 @@ function getTrustLevel(score) {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.12.0";
+var SDK_VERSION = "4.0.0";
 
 // src/well-known.ts
 var CACHE_TTL_MS = 60 * 60 * 1e3;
@@ -3727,7 +3727,7 @@ var DEFAULT_CONFIG = {
 };
 var initCheckPerformed = false;
 var deprecationWarningShown = false;
-async function performInitCheck(apiBaseUrl, debug, strictInit) {
+async function performInitCheck(apiBaseUrl, debug, strictInit, apiKey) {
   initCheckPerformed = true;
   try {
     const probeUrl = `${apiBaseUrl}/agents/verify-access`;
@@ -3744,6 +3744,28 @@ async function performInitCheck(apiBaseUrl, debug, strictInit) {
         `[VerificationGateway] init check passed for ${apiBaseUrl} (content-type: ${contentType})`
       );
     }
+    if (apiKey) {
+      const selfCheck = await fetch(`${apiBaseUrl}/agents/verify-access/self-check`, {
+        headers: { Authorization: `Bearer ${apiKey}` }
+      });
+      if (selfCheck.status === 401) {
+        const body = await selfCheck.json().catch(() => ({}));
+        const message = `[VerificationGateway] the configured AstraSync API key was REJECTED at startup (${body.code ?? "api_key_invalid"}: ${body.message ?? "invalid key"}). Every inbound agent will be turned away until the key is rotated` + (body.remediation?.manageUrl ? ` at ${body.remediation.manageUrl}` : "") + `.`;
+        if (strictInit) {
+          throw new Error(`${message} (strictInit=true)`);
+        }
+        console.error(message);
+      } else if (selfCheck.ok) {
+        const body = await selfCheck.json().catch(() => ({}));
+        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.`
+          );
+        } else if (debug) {
+          console.log("[VerificationGateway] API key self-check passed");
+        }
+      }
+    }
   } catch (err) {
     if (strictInit) {
       throw err;
@@ -3821,8 +3843,17 @@ function cacheResult(request, result, configuredTtl, counterpartyId) {
 function createGuidanceResponse(_config, reason, options = {}) {
   const source = options.source ?? "no_credentials";
   const isApiError = source === "api_error";
+  const isMisconfig = source === "merchant_misconfig";
   const urls = options.urls;
-  const guidance = isApiError ? {
+  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.",
+    registrationUrl: urls?.registrationUrl ?? "",
+    documentationUrl: options.remediation?.docsUrl ?? urls?.documentationUrl ?? "",
+    steps: [
+      "Report the failure to the site operator \u2014 their AstraSync API key needs rotating",
+      "Do not retry: the failure is deterministic until the operator updates their key"
+    ]
+  } : isApiError ? {
     message: "Verification is temporarily unavailable. Retry with exponential backoff; if the issue persists, contact support with the correlationId.",
     registrationUrl: urls?.registrationUrl ?? "",
     documentationUrl: urls?.documentationUrl ?? "",
@@ -3860,13 +3891,22 @@ function createGuidanceResponse(_config, reason, options = {}) {
     // partners (and their custom onDenied handlers) can branch on
     // dimension. Without this, the synthesised stub was indistinguishable
     // from a real policy deny.
-    failures: isApiError ? [
+    failures: isMisconfig ? [
+      {
+        dimension: "verify_access.merchant_misconfigured",
+        message: reason ?? "The integration API key was rejected by AstraSync",
+        guidance: guidance.message
+      }
+    ] : isApiError ? [
       {
         dimension: "verify_access.api_error",
         message: reason ?? "Verification temporarily unavailable",
         guidance: guidance.message
       }
     ] : void 0,
+    // 4.0.0: typed marker so adapters render the misconfig envelope (503 +
+    // MERCHANT_VERIFICATION_MISCONFIGURED) without string-matching.
+    ...isMisconfig && { misconfigured: true },
     correlationId: options.correlationId,
     attemptId: options.attemptId,
     verifiedAt: /* @__PURE__ */ new Date()
@@ -3921,7 +3961,8 @@ async function callVerifyAccessAPI(config, request) {
     const response = await fetch(`${config.apiBaseUrl}/agents/verify-access`, {
       method: "POST",
       headers,
-      body: JSON.stringify(body)
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(config.verifyTimeoutMs ?? 1e4)
     });
     const data = await response.json();
     if (response.status === 410) {
@@ -3945,6 +3986,17 @@ async function callVerifyAccessAPI(config, request) {
       };
     }
     if (!response.ok) {
+      if (response.status === 401) {
+        return {
+          success: false,
+          error: data.message || data.error || "Integration API key rejected",
+          misconfig: true,
+          misconfigCode: 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
+        };
+      }
       return {
         success: false,
         error: data.message || data.error || `API returned ${response.status}`,
@@ -3966,9 +4018,19 @@ async function verify(config, request, options) {
   const urls = mergedConfig.apiBaseUrl ? getCachedWellKnownUrls(mergedConfig.apiBaseUrl) : void 0;
   if (!initCheckPerformed && !mergedConfig.disableInitChecks && mergedConfig.apiBaseUrl) {
     if (mergedConfig.strictInit) {
-      await performInitCheck(mergedConfig.apiBaseUrl, mergedConfig.debug, true);
+      await performInitCheck(
+        mergedConfig.apiBaseUrl,
+        mergedConfig.debug,
+        true,
+        mergedConfig.apiKey
+      );
     } else {
-      void performInitCheck(mergedConfig.apiBaseUrl, mergedConfig.debug, false);
+      void performInitCheck(
+        mergedConfig.apiBaseUrl,
+        mergedConfig.debug,
+        false,
+        mergedConfig.apiKey
+      );
     }
   }
   if (!deprecationWarningShown && (config.minTrustScore !== void 0 || config.minTrustScoreForFull !== void 0)) {
@@ -4007,9 +4069,10 @@ async function verify(config, request, options) {
   const serverDenialReasons = Array.isArray(rawServerDenialReasons) && rawServerDenialReasons.length > 0 ? rawServerDenialReasons : void 0;
   if (!apiResponse.success) {
     return createGuidanceResponse(mergedConfig, apiResponse.error, {
-      source: "api_error",
+      source: apiResponse.misconfig ? "merchant_misconfig" : "api_error",
       correlationId: apiResponse.correlationId,
       attemptId: apiResponse.attemptId,
+      remediation: apiResponse.remediation,
       urls
     });
   }

package/dist/bin/astrasync-codex-hook.js

@@ -3700,7 +3700,7 @@ function getTrustLevel(score) {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.12.0";
+var SDK_VERSION = "4.0.0";
 
 // src/well-known.ts
 var CACHE_TTL_MS = 60 * 60 * 1e3;
@@ -3726,7 +3726,7 @@ var DEFAULT_CONFIG = {
 };
 var initCheckPerformed = false;
 var deprecationWarningShown = false;
-async function performInitCheck(apiBaseUrl, debug, strictInit) {
+async function performInitCheck(apiBaseUrl, debug, strictInit, apiKey) {
   initCheckPerformed = true;
   try {
     const probeUrl = `${apiBaseUrl}/agents/verify-access`;
@@ -3743,6 +3743,28 @@ async function performInitCheck(apiBaseUrl, debug, strictInit) {
         `[VerificationGateway] init check passed for ${apiBaseUrl} (content-type: ${contentType})`
       );
     }
+    if (apiKey) {
+      const selfCheck = await fetch(`${apiBaseUrl}/agents/verify-access/self-check`, {
+        headers: { Authorization: `Bearer ${apiKey}` }
+      });
+      if (selfCheck.status === 401) {
+        const body = await selfCheck.json().catch(() => ({}));
+        const message = `[VerificationGateway] the configured AstraSync API key was REJECTED at startup (${body.code ?? "api_key_invalid"}: ${body.message ?? "invalid key"}). Every inbound agent will be turned away until the key is rotated` + (body.remediation?.manageUrl ? ` at ${body.remediation.manageUrl}` : "") + `.`;
+        if (strictInit) {
+          throw new Error(`${message} (strictInit=true)`);
+        }
+        console.error(message);
+      } else if (selfCheck.ok) {
+        const body = await selfCheck.json().catch(() => ({}));
+        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.`
+          );
+        } else if (debug) {
+          console.log("[VerificationGateway] API key self-check passed");
+        }
+      }
+    }
   } catch (err) {
     if (strictInit) {
       throw err;
@@ -3820,8 +3842,17 @@ function cacheResult(request, result, configuredTtl, counterpartyId) {
 function createGuidanceResponse(_config, reason, options = {}) {
   const source = options.source ?? "no_credentials";
   const isApiError = source === "api_error";
+  const isMisconfig = source === "merchant_misconfig";
   const urls = options.urls;
-  const guidance = isApiError ? {
+  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.",
+    registrationUrl: urls?.registrationUrl ?? "",
+    documentationUrl: options.remediation?.docsUrl ?? urls?.documentationUrl ?? "",
+    steps: [
+      "Report the failure to the site operator \u2014 their AstraSync API key needs rotating",
+      "Do not retry: the failure is deterministic until the operator updates their key"
+    ]
+  } : isApiError ? {
     message: "Verification is temporarily unavailable. Retry with exponential backoff; if the issue persists, contact support with the correlationId.",
     registrationUrl: urls?.registrationUrl ?? "",
     documentationUrl: urls?.documentationUrl ?? "",
@@ -3859,13 +3890,22 @@ function createGuidanceResponse(_config, reason, options = {}) {
     // partners (and their custom onDenied handlers) can branch on
     // dimension. Without this, the synthesised stub was indistinguishable
     // from a real policy deny.
-    failures: isApiError ? [
+    failures: isMisconfig ? [
+      {
+        dimension: "verify_access.merchant_misconfigured",
+        message: reason ?? "The integration API key was rejected by AstraSync",
+        guidance: guidance.message
+      }
+    ] : isApiError ? [
       {
         dimension: "verify_access.api_error",
         message: reason ?? "Verification temporarily unavailable",
         guidance: guidance.message
       }
     ] : void 0,
+    // 4.0.0: typed marker so adapters render the misconfig envelope (503 +
+    // MERCHANT_VERIFICATION_MISCONFIGURED) without string-matching.
+    ...isMisconfig && { misconfigured: true },
     correlationId: options.correlationId,
     attemptId: options.attemptId,
     verifiedAt: /* @__PURE__ */ new Date()
@@ -3920,7 +3960,8 @@ async function callVerifyAccessAPI(config, request) {
     const response = await fetch(`${config.apiBaseUrl}/agents/verify-access`, {
       method: "POST",
       headers,
-      body: JSON.stringify(body)
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(config.verifyTimeoutMs ?? 1e4)
     });
     const data = await response.json();
     if (response.status === 410) {
@@ -3944,6 +3985,17 @@ async function callVerifyAccessAPI(config, request) {
       };
     }
     if (!response.ok) {
+      if (response.status === 401) {
+        return {
+          success: false,
+          error: data.message || data.error || "Integration API key rejected",
+          misconfig: true,
+          misconfigCode: 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
+        };
+      }
       return {
         success: false,
         error: data.message || data.error || `API returned ${response.status}`,
@@ -3965,9 +4017,19 @@ async function verify(config, request, options) {
   const urls = mergedConfig.apiBaseUrl ? getCachedWellKnownUrls(mergedConfig.apiBaseUrl) : void 0;
   if (!initCheckPerformed && !mergedConfig.disableInitChecks && mergedConfig.apiBaseUrl) {
     if (mergedConfig.strictInit) {
-      await performInitCheck(mergedConfig.apiBaseUrl, mergedConfig.debug, true);
+      await performInitCheck(
+        mergedConfig.apiBaseUrl,
+        mergedConfig.debug,
+        true,
+        mergedConfig.apiKey
+      );
     } else {
-      void performInitCheck(mergedConfig.apiBaseUrl, mergedConfig.debug, false);
+      void performInitCheck(
+        mergedConfig.apiBaseUrl,
+        mergedConfig.debug,
+        false,
+        mergedConfig.apiKey
+      );
     }
   }
   if (!deprecationWarningShown && (config.minTrustScore !== void 0 || config.minTrustScoreForFull !== void 0)) {
@@ -4006,9 +4068,10 @@ async function verify(config, request, options) {
   const serverDenialReasons = Array.isArray(rawServerDenialReasons) && rawServerDenialReasons.length > 0 ? rawServerDenialReasons : void 0;
   if (!apiResponse.success) {
     return createGuidanceResponse(mergedConfig, apiResponse.error, {
-      source: "api_error",
+      source: apiResponse.misconfig ? "merchant_misconfig" : "api_error",
       correlationId: apiResponse.correlationId,
       attemptId: apiResponse.attemptId,
+      remediation: apiResponse.remediation,
       urls
     });
   }

package/dist/bin/astrasync-guard.js

@@ -4609,7 +4609,7 @@ function getTrustLevel(score) {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.12.0";
+var SDK_VERSION = "4.0.0";
 
 // src/well-known.ts
 var CACHE_TTL_MS = 60 * 60 * 1e3;
@@ -4635,7 +4635,7 @@ var DEFAULT_CONFIG = {
 };
 var initCheckPerformed = false;
 var deprecationWarningShown = false;
-async function performInitCheck(apiBaseUrl, debug, strictInit) {
+async function performInitCheck(apiBaseUrl, debug, strictInit, apiKey) {
   initCheckPerformed = true;
   try {
     const probeUrl = `${apiBaseUrl}/agents/verify-access`;
@@ -4652,6 +4652,28 @@ async function performInitCheck(apiBaseUrl, debug, strictInit) {
         `[VerificationGateway] init check passed for ${apiBaseUrl} (content-type: ${contentType})`
       );
     }
+    if (apiKey) {
+      const selfCheck = await fetch(`${apiBaseUrl}/agents/verify-access/self-check`, {
+        headers: { Authorization: `Bearer ${apiKey}` }
+      });
+      if (selfCheck.status === 401) {
+        const body = await selfCheck.json().catch(() => ({}));
+        const message = `[VerificationGateway] the configured AstraSync API key was REJECTED at startup (${body.code ?? "api_key_invalid"}: ${body.message ?? "invalid key"}). Every inbound agent will be turned away until the key is rotated` + (body.remediation?.manageUrl ? ` at ${body.remediation.manageUrl}` : "") + `.`;
+        if (strictInit) {
+          throw new Error(`${message} (strictInit=true)`);
+        }
+        console.error(message);
+      } else if (selfCheck.ok) {
+        const body = await selfCheck.json().catch(() => ({}));
+        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.`
+          );
+        } else if (debug) {
+          console.log("[VerificationGateway] API key self-check passed");
+        }
+      }
+    }
   } catch (err) {
     if (strictInit) {
       throw err;
@@ -4729,8 +4751,17 @@ function cacheResult(request2, result, configuredTtl, counterpartyId) {
 function createGuidanceResponse(_config, reason, options = {}) {
   const source = options.source ?? "no_credentials";
   const isApiError = source === "api_error";
+  const isMisconfig = source === "merchant_misconfig";
   const urls = options.urls;
-  const guidance = isApiError ? {
+  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.",
+    registrationUrl: urls?.registrationUrl ?? "",
+    documentationUrl: options.remediation?.docsUrl ?? urls?.documentationUrl ?? "",
+    steps: [
+      "Report the failure to the site operator \u2014 their AstraSync API key needs rotating",
+      "Do not retry: the failure is deterministic until the operator updates their key"
+    ]
+  } : isApiError ? {
     message: "Verification is temporarily unavailable. Retry with exponential backoff; if the issue persists, contact support with the correlationId.",
     registrationUrl: urls?.registrationUrl ?? "",
     documentationUrl: urls?.documentationUrl ?? "",
@@ -4768,13 +4799,22 @@ function createGuidanceResponse(_config, reason, options = {}) {
     // partners (and their custom onDenied handlers) can branch on
     // dimension. Without this, the synthesised stub was indistinguishable
     // from a real policy deny.
-    failures: isApiError ? [
+    failures: isMisconfig ? [
+      {
+        dimension: "verify_access.merchant_misconfigured",
+        message: reason ?? "The integration API key was rejected by AstraSync",
+        guidance: guidance.message
+      }
+    ] : isApiError ? [
       {
         dimension: "verify_access.api_error",
         message: reason ?? "Verification temporarily unavailable",
         guidance: guidance.message
       }
     ] : void 0,
+    // 4.0.0: typed marker so adapters render the misconfig envelope (503 +
+    // MERCHANT_VERIFICATION_MISCONFIGURED) without string-matching.
+    ...isMisconfig && { misconfigured: true },
     correlationId: options.correlationId,
     attemptId: options.attemptId,
     verifiedAt: /* @__PURE__ */ new Date()
@@ -4829,7 +4869,8 @@ async function callVerifyAccessAPI(config, request2) {
     const response = await fetch(`${config.apiBaseUrl}/agents/verify-access`, {
       method: "POST",
       headers,
-      body: JSON.stringify(body)
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(config.verifyTimeoutMs ?? 1e4)
     });
     const data = await response.json();
     if (response.status === 410) {
@@ -4853,6 +4894,17 @@ async function callVerifyAccessAPI(config, request2) {
       };
     }
     if (!response.ok) {
+      if (response.status === 401) {
+        return {
+          success: false,
+          error: data.message || data.error || "Integration API key rejected",
+          misconfig: true,
+          misconfigCode: 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
+        };
+      }
       return {
         success: false,
         error: data.message || data.error || `API returned ${response.status}`,
@@ -4874,9 +4926,19 @@ async function verify(config, request2, options) {
   const urls = mergedConfig.apiBaseUrl ? getCachedWellKnownUrls(mergedConfig.apiBaseUrl) : void 0;
   if (!initCheckPerformed && !mergedConfig.disableInitChecks && mergedConfig.apiBaseUrl) {
     if (mergedConfig.strictInit) {
-      await performInitCheck(mergedConfig.apiBaseUrl, mergedConfig.debug, true);
+      await performInitCheck(
+        mergedConfig.apiBaseUrl,
+        mergedConfig.debug,
+        true,
+        mergedConfig.apiKey
+      );
     } else {
-      void performInitCheck(mergedConfig.apiBaseUrl, mergedConfig.debug, false);
+      void performInitCheck(
+        mergedConfig.apiBaseUrl,
+        mergedConfig.debug,
+        false,
+        mergedConfig.apiKey
+      );
     }
   }
   if (!deprecationWarningShown && (config.minTrustScore !== void 0 || config.minTrustScoreForFull !== void 0)) {
@@ -4915,9 +4977,10 @@ async function verify(config, request2, options) {
   const serverDenialReasons = Array.isArray(rawServerDenialReasons) && rawServerDenialReasons.length > 0 ? rawServerDenialReasons : void 0;
   if (!apiResponse.success) {
     return createGuidanceResponse(mergedConfig, apiResponse.error, {
-      source: "api_error",
+      source: apiResponse.misconfig ? "merchant_misconfig" : "api_error",
       correlationId: apiResponse.correlationId,
       attemptId: apiResponse.attemptId,
+      remediation: apiResponse.remediation,
       urls
     });
   }

package/dist/bin/astrasync.js

@@ -5000,7 +5000,7 @@ var SDK_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    SDK_VERSION = "3.12.0";
+    SDK_VERSION = "4.0.0";
   }
 });
 
@@ -5018,7 +5018,7 @@ var init_well_known = __esm({
 });
 
 // src/verify.ts
-async function performInitCheck(apiBaseUrl, debug, strictInit) {
+async function performInitCheck(apiBaseUrl, debug, strictInit, apiKey) {
   initCheckPerformed = true;
   try {
     const probeUrl = `${apiBaseUrl}/agents/verify-access`;
@@ -5035,6 +5035,28 @@ async function performInitCheck(apiBaseUrl, debug, strictInit) {
         `[VerificationGateway] init check passed for ${apiBaseUrl} (content-type: ${contentType})`
       );
     }
+    if (apiKey) {
+      const selfCheck = await fetch(`${apiBaseUrl}/agents/verify-access/self-check`, {
+        headers: { Authorization: `Bearer ${apiKey}` }
+      });
+      if (selfCheck.status === 401) {
+        const body = await selfCheck.json().catch(() => ({}));
+        const message = `[VerificationGateway] the configured AstraSync API key was REJECTED at startup (${body.code ?? "api_key_invalid"}: ${body.message ?? "invalid key"}). Every inbound agent will be turned away until the key is rotated` + (body.remediation?.manageUrl ? ` at ${body.remediation.manageUrl}` : "") + `.`;
+        if (strictInit) {
+          throw new Error(`${message} (strictInit=true)`);
+        }
+        console.error(message);
+      } else if (selfCheck.ok) {
+        const body = await selfCheck.json().catch(() => ({}));
+        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.`
+          );
+        } else if (debug) {
+          console.log("[VerificationGateway] API key self-check passed");
+        }
+      }
+    }
   } catch (err) {
     if (strictInit) {
       throw err;
@@ -5110,8 +5132,17 @@ function cacheResult(request2, result, configuredTtl, counterpartyId) {
 function createGuidanceResponse(_config, reason, options = {}) {
   const source = options.source ?? "no_credentials";
   const isApiError = source === "api_error";
+  const isMisconfig = source === "merchant_misconfig";
   const urls = options.urls;
-  const guidance = isApiError ? {
+  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.",
+    registrationUrl: urls?.registrationUrl ?? "",
+    documentationUrl: options.remediation?.docsUrl ?? urls?.documentationUrl ?? "",
+    steps: [
+      "Report the failure to the site operator \u2014 their AstraSync API key needs rotating",
+      "Do not retry: the failure is deterministic until the operator updates their key"
+    ]
+  } : isApiError ? {
     message: "Verification is temporarily unavailable. Retry with exponential backoff; if the issue persists, contact support with the correlationId.",
     registrationUrl: urls?.registrationUrl ?? "",
     documentationUrl: urls?.documentationUrl ?? "",
@@ -5149,13 +5180,22 @@ function createGuidanceResponse(_config, reason, options = {}) {
     // partners (and their custom onDenied handlers) can branch on
     // dimension. Without this, the synthesised stub was indistinguishable
     // from a real policy deny.
-    failures: isApiError ? [
+    failures: isMisconfig ? [
+      {
+        dimension: "verify_access.merchant_misconfigured",
+        message: reason ?? "The integration API key was rejected by AstraSync",
+        guidance: guidance.message
+      }
+    ] : isApiError ? [
       {
         dimension: "verify_access.api_error",
         message: reason ?? "Verification temporarily unavailable",
         guidance: guidance.message
       }
     ] : void 0,
+    // 4.0.0: typed marker so adapters render the misconfig envelope (503 +
+    // MERCHANT_VERIFICATION_MISCONFIGURED) without string-matching.
+    ...isMisconfig && { misconfigured: true },
     correlationId: options.correlationId,
     attemptId: options.attemptId,
     verifiedAt: /* @__PURE__ */ new Date()
@@ -5210,7 +5250,8 @@ async function callVerifyAccessAPI(config, request2) {
     const response = await fetch(`${config.apiBaseUrl}/agents/verify-access`, {
       method: "POST",
       headers,
-      body: JSON.stringify(body)
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(config.verifyTimeoutMs ?? 1e4)
     });
     const data = await response.json();
     if (response.status === 410) {
@@ -5234,6 +5275,17 @@ async function callVerifyAccessAPI(config, request2) {
       };
     }
     if (!response.ok) {
+      if (response.status === 401) {
+        return {
+          success: false,
+          error: data.message || data.error || "Integration API key rejected",
+          misconfig: true,
+          misconfigCode: 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
+        };
+      }
       return {
         success: false,
         error: data.message || data.error || `API returned ${response.status}`,
@@ -5255,9 +5307,19 @@ async function verify(config, request2, options) {
   const urls = mergedConfig.apiBaseUrl ? getCachedWellKnownUrls(mergedConfig.apiBaseUrl) : void 0;
   if (!initCheckPerformed && !mergedConfig.disableInitChecks && mergedConfig.apiBaseUrl) {
     if (mergedConfig.strictInit) {
-      await performInitCheck(mergedConfig.apiBaseUrl, mergedConfig.debug, true);
+      await performInitCheck(
+        mergedConfig.apiBaseUrl,
+        mergedConfig.debug,
+        true,
+        mergedConfig.apiKey
+      );
     } else {
-      void performInitCheck(mergedConfig.apiBaseUrl, mergedConfig.debug, false);
+      void performInitCheck(
+        mergedConfig.apiBaseUrl,
+        mergedConfig.debug,
+        false,
+        mergedConfig.apiKey
+      );
     }
   }
   if (!deprecationWarningShown && (config.minTrustScore !== void 0 || config.minTrustScoreForFull !== void 0)) {
@@ -5296,9 +5358,10 @@ async function verify(config, request2, options) {
   const serverDenialReasons = Array.isArray(rawServerDenialReasons) && rawServerDenialReasons.length > 0 ? rawServerDenialReasons : void 0;
   if (!apiResponse.success) {
     return createGuidanceResponse(mergedConfig, apiResponse.error, {
-      source: "api_error",
+      source: apiResponse.misconfig ? "merchant_misconfig" : "api_error",
       correlationId: apiResponse.correlationId,
       attemptId: apiResponse.attemptId,
+      remediation: apiResponse.remediation,
       urls
     });
   }