@astrasyncai/verification-gateway 3.11.1 → 4.0.0

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

@@ -3701,7 +3701,7 @@ function getTrustLevel(score) {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.11.1";
+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,14 +3891,24 @@ 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()
   };
 }
@@ -3897,6 +3938,8 @@ async function callVerifyAccessAPI(config, request) {
     body.runtimeChallengeOptions = requestData.runtimeChallengeOptions;
   if (requestData.invocationProtocol) body.invocationProtocol = requestData.invocationProtocol;
   if (requestData.commerceArtifacts) body.commerceArtifacts = requestData.commerceArtifacts;
+  if (requestData.attemptId) body.attemptId = requestData.attemptId;
+  if (requestData.considerationSet) body.considerationSet = requestData.considerationSet;
   body.sdkVersion = SDK_VERSION;
   if (requestData.callerMetadata || requestData.clientIp || requestData.userAgent) {
     const meta = {
@@ -3918,12 +3961,16 @@ 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) {
       return {
         success: true,
+        // 3.12.0 (Trust Record): keep the server-echoed attempt handle even on
+        // the synthesised 410 deny shape (echoed on every branch).
+        attemptId: typeof data?.attemptId === "string" ? data.attemptId : void 0,
         access: {
           allowed: false,
           accessLevel: "none",
@@ -3939,10 +3986,22 @@ 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}`,
-        correlationId: typeof data?.correlationId === "string" ? data.correlationId : void 0
+        correlationId: typeof data?.correlationId === "string" ? data.correlationId : void 0,
+        attemptId: typeof data?.attemptId === "string" ? data.attemptId : void 0
       };
     }
     return data;
@@ -3959,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)) {
@@ -3976,7 +4045,13 @@ async function verify(config, request, options) {
       if (mergedConfig.debug) {
         console.log("[VerificationGateway] Returning cached result");
       }
-      return cached;
+      const hit = { ...cached };
+      if (request.attemptId) {
+        hit.attemptId = request.attemptId;
+      } else {
+        delete hit.attemptId;
+      }
+      return hit;
     }
   }
   const enrichedRequest = { ...request };
@@ -3994,8 +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
     });
   }
@@ -4031,6 +4108,9 @@ async function verify(config, request, options) {
       // Anonymous traffic has no session → correlationId is the per-attempt
       // linking key (the sessionId-equivalent for anonymous callers).
       correlationId: apiResponse.correlationId,
+      // 3.12.0 (Trust Record): server echoes the attempt-chain handle on
+      // every branch — denials included (the funnel outlives one deny).
+      attemptId: apiResponse.attemptId,
       recommendation: apiResponse.recommendation,
       recommendationReasons: apiResponse.recommendationReasons,
       stepUpApproval: apiResponse.stepUpApproval,
@@ -4082,6 +4162,8 @@ async function verify(config, request, options) {
     // v2.3.10 (defect #34, round-4): anonymous responses surface correlationId
     // (no session row exists for unverified callers).
     correlationId: apiResponse.correlationId,
+    // 3.12.0 (Trust Record): server-echoed attempt-chain handle.
+    attemptId: apiResponse.attemptId,
     runtimeChallenge: apiResponse.runtimeChallenge,
     tokenGuidance: apiResponse.tokenGuidance,
     recommendation: apiResponse.recommendation,

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

@@ -3700,7 +3700,7 @@ function getTrustLevel(score) {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.11.1";
+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,14 +3890,24 @@ 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()
   };
 }
@@ -3896,6 +3937,8 @@ async function callVerifyAccessAPI(config, request) {
     body.runtimeChallengeOptions = requestData.runtimeChallengeOptions;
   if (requestData.invocationProtocol) body.invocationProtocol = requestData.invocationProtocol;
   if (requestData.commerceArtifacts) body.commerceArtifacts = requestData.commerceArtifacts;
+  if (requestData.attemptId) body.attemptId = requestData.attemptId;
+  if (requestData.considerationSet) body.considerationSet = requestData.considerationSet;
   body.sdkVersion = SDK_VERSION;
   if (requestData.callerMetadata || requestData.clientIp || requestData.userAgent) {
     const meta = {
@@ -3917,12 +3960,16 @@ 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) {
       return {
         success: true,
+        // 3.12.0 (Trust Record): keep the server-echoed attempt handle even on
+        // the synthesised 410 deny shape (echoed on every branch).
+        attemptId: typeof data?.attemptId === "string" ? data.attemptId : void 0,
         access: {
           allowed: false,
           accessLevel: "none",
@@ -3938,10 +3985,22 @@ 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}`,
-        correlationId: typeof data?.correlationId === "string" ? data.correlationId : void 0
+        correlationId: typeof data?.correlationId === "string" ? data.correlationId : void 0,
+        attemptId: typeof data?.attemptId === "string" ? data.attemptId : void 0
       };
     }
     return data;
@@ -3958,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)) {
@@ -3975,7 +4044,13 @@ async function verify(config, request, options) {
       if (mergedConfig.debug) {
         console.log("[VerificationGateway] Returning cached result");
       }
-      return cached;
+      const hit = { ...cached };
+      if (request.attemptId) {
+        hit.attemptId = request.attemptId;
+      } else {
+        delete hit.attemptId;
+      }
+      return hit;
     }
   }
   const enrichedRequest = { ...request };
@@ -3993,8 +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
     });
   }
@@ -4030,6 +4107,9 @@ async function verify(config, request, options) {
       // Anonymous traffic has no session → correlationId is the per-attempt
       // linking key (the sessionId-equivalent for anonymous callers).
       correlationId: apiResponse.correlationId,
+      // 3.12.0 (Trust Record): server echoes the attempt-chain handle on
+      // every branch — denials included (the funnel outlives one deny).
+      attemptId: apiResponse.attemptId,
       recommendation: apiResponse.recommendation,
       recommendationReasons: apiResponse.recommendationReasons,
       stepUpApproval: apiResponse.stepUpApproval,
@@ -4081,6 +4161,8 @@ async function verify(config, request, options) {
     // v2.3.10 (defect #34, round-4): anonymous responses surface correlationId
     // (no session row exists for unverified callers).
     correlationId: apiResponse.correlationId,
+    // 3.12.0 (Trust Record): server-echoed attempt-chain handle.
+    attemptId: apiResponse.attemptId,
     runtimeChallenge: apiResponse.runtimeChallenge,
     tokenGuidance: apiResponse.tokenGuidance,
     recommendation: apiResponse.recommendation,

package/dist/bin/astrasync-guard.js

@@ -4609,7 +4609,7 @@ function getTrustLevel(score) {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.11.1";
+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,14 +4799,24 @@ 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()
   };
 }
@@ -4805,6 +4846,8 @@ async function callVerifyAccessAPI(config, request2) {
     body.runtimeChallengeOptions = requestData.runtimeChallengeOptions;
   if (requestData.invocationProtocol) body.invocationProtocol = requestData.invocationProtocol;
   if (requestData.commerceArtifacts) body.commerceArtifacts = requestData.commerceArtifacts;
+  if (requestData.attemptId) body.attemptId = requestData.attemptId;
+  if (requestData.considerationSet) body.considerationSet = requestData.considerationSet;
   body.sdkVersion = SDK_VERSION;
   if (requestData.callerMetadata || requestData.clientIp || requestData.userAgent) {
     const meta = {
@@ -4826,12 +4869,16 @@ 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) {
       return {
         success: true,
+        // 3.12.0 (Trust Record): keep the server-echoed attempt handle even on
+        // the synthesised 410 deny shape (echoed on every branch).
+        attemptId: typeof data?.attemptId === "string" ? data.attemptId : void 0,
         access: {
           allowed: false,
           accessLevel: "none",
@@ -4847,10 +4894,22 @@ 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}`,
-        correlationId: typeof data?.correlationId === "string" ? data.correlationId : void 0
+        correlationId: typeof data?.correlationId === "string" ? data.correlationId : void 0,
+        attemptId: typeof data?.attemptId === "string" ? data.attemptId : void 0
       };
     }
     return data;
@@ -4867,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)) {
@@ -4884,7 +4953,13 @@ async function verify(config, request2, options) {
       if (mergedConfig.debug) {
         console.log("[VerificationGateway] Returning cached result");
       }
-      return cached;
+      const hit = { ...cached };
+      if (request2.attemptId) {
+        hit.attemptId = request2.attemptId;
+      } else {
+        delete hit.attemptId;
+      }
+      return hit;
     }
   }
   const enrichedRequest = { ...request2 };
@@ -4902,8 +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
     });
   }
@@ -4939,6 +5016,9 @@ async function verify(config, request2, options) {
       // Anonymous traffic has no session → correlationId is the per-attempt
       // linking key (the sessionId-equivalent for anonymous callers).
       correlationId: apiResponse.correlationId,
+      // 3.12.0 (Trust Record): server echoes the attempt-chain handle on
+      // every branch — denials included (the funnel outlives one deny).
+      attemptId: apiResponse.attemptId,
       recommendation: apiResponse.recommendation,
       recommendationReasons: apiResponse.recommendationReasons,
       stepUpApproval: apiResponse.stepUpApproval,
@@ -4990,6 +5070,8 @@ async function verify(config, request2, options) {
     // v2.3.10 (defect #34, round-4): anonymous responses surface correlationId
     // (no session row exists for unverified callers).
     correlationId: apiResponse.correlationId,
+    // 3.12.0 (Trust Record): server-echoed attempt-chain handle.
+    attemptId: apiResponse.attemptId,
     runtimeChallenge: apiResponse.runtimeChallenge,
     tokenGuidance: apiResponse.tokenGuidance,
     recommendation: apiResponse.recommendation,