blockintel-gate-sdk 0.4.4 → 0.4.5

package/dist/index.d.cts

@@ -273,6 +273,11 @@ declare class GateClient {
      * Logs warnings but doesn't block (initialization already completed).
      */
     private performIamRiskCheckAsync;
+    /**
+     * Warn if the local SDK mode is SHADOW but the server's adoption stage is enforcing.
+     * Runs non-blocking after heartbeat startup; never throws.
+     */
+    private checkAdoptionStageMismatch;
     /**
      * Evaluate a transaction defense request
      *
@@ -597,6 +602,8 @@ declare class HeartbeatManager {
     private evictionTimer;
     private started;
     private maxBackoffSeconds;
+    /** Server's current adoption stage for this tenant (cached from heartbeat response) */
+    private adoptionStage;
     private readonly maxSigners;
     private readonly signerIdleTtlMs;
     private readonly localRateLimitMs;
@@ -662,6 +669,12 @@ declare class HeartbeatManager {
      * Get client instance ID (for tracking)
      */
     getClientInstanceId(): string;
+    /**
+     * Get the server's current adoption stage for this tenant.
+     * Populated after the first successful heartbeat response.
+     * Returns null if not yet received.
+     */
+    getAdoptionStage(): string | null;
 }
 
 /**

package/dist/index.d.ts

@@ -273,6 +273,11 @@ declare class GateClient {
      * Logs warnings but doesn't block (initialization already completed).
      */
     private performIamRiskCheckAsync;
+    /**
+     * Warn if the local SDK mode is SHADOW but the server's adoption stage is enforcing.
+     * Runs non-blocking after heartbeat startup; never throws.
+     */
+    private checkAdoptionStageMismatch;
     /**
      * Evaluate a transaction defense request
      *
@@ -597,6 +602,8 @@ declare class HeartbeatManager {
     private evictionTimer;
     private started;
     private maxBackoffSeconds;
+    /** Server's current adoption stage for this tenant (cached from heartbeat response) */
+    private adoptionStage;
     private readonly maxSigners;
     private readonly signerIdleTtlMs;
     private readonly localRateLimitMs;
@@ -662,6 +669,12 @@ declare class HeartbeatManager {
      * Get client instance ID (for tracking)
      */
     getClientInstanceId(): string;
+    /**
+     * Get the server's current adoption stage for this tenant.
+     * Populated after the first successful heartbeat response.
+     * Returns null if not yet received.
+     */
+    getAdoptionStage(): string | null;
 }
 
 /**

package/dist/index.js

@@ -1282,6 +1282,8 @@ var HeartbeatManager = class {
   started = false;
   maxBackoffSeconds = 30;
   // Maximum backoff interval
+  /** Server's current adoption stage for this tenant (cached from heartbeat response) */
+  adoptionStage = null;
   maxSigners;
   signerIdleTtlMs;
   localRateLimitMs;
@@ -1555,6 +1557,9 @@ var HeartbeatManager = class {
           policyHash: response.data.policyHash
         };
         entry.consecutiveFailures = 0;
+        if (response.data.adoptionStage != null) {
+          this.adoptionStage = response.data.adoptionStage;
+        }
         console.log("[HEARTBEAT] Acquired heartbeat token", {
           expiresAt,
           signerId,
@@ -1583,6 +1588,14 @@ var HeartbeatManager = class {
   getClientInstanceId() {
     return this.clientInstanceId;
   }
+  /**
+   * Get the server's current adoption stage for this tenant.
+   * Populated after the first successful heartbeat response.
+   * Returns null if not yet received.
+   */
+  getAdoptionStage() {
+    return this.adoptionStage;
+  }
 };
 
 // src/security/IamPermissionRiskChecker.ts
@@ -1915,6 +1928,8 @@ var GateClient = class {
         apiKey: heartbeatApiKey
       });
       this.heartbeatManager.start();
+      this.checkAdoptionStageMismatch().catch(() => {
+      });
     }
     if (!config.local) {
       const enforcementMode = config.enforcementMode || "SOFT";
@@ -1960,9 +1975,38 @@ var GateClient = class {
       console.warn("[GATE CLIENT] Async IAM risk check warning:", error instanceof Error ? error.message : String(error));
     }
   }
+  /**
+   * Warn if the local SDK mode is SHADOW but the server's adoption stage is enforcing.
+   * Runs non-blocking after heartbeat startup; never throws.
+   */
+  async checkAdoptionStageMismatch() {
+    if (!this.heartbeatManager) return;
+    const signerId = this.config.signerId ?? DEFAULT_SIGNER_ID;
+    try {
+      await this.heartbeatManager.getTokenForSigner(signerId, 5e3);
+    } catch {
+      return;
+    }
+    const adoptionStage = this.heartbeatManager.getAdoptionStage();
+    if (!adoptionStage) return;
+    const ENFORCING_STAGES = [
+      "SOFT_ENFORCE",
+      "HARD_ENFORCE",
+      "PROVENANCE",
+      "HARD_KMS_GATEWAY",
+      "HARD_KMS_ATTESTED",
+      "HARD_KMS_ATTESTED_ENCLAVE",
+      "HARD_GCP_CONFIDENTIAL_VM"
+    ];
+    if (this.mode === "SHADOW" && ENFORCING_STAGES.includes(adoptionStage)) {
+      console.warn(
+        `[GATE SDK] Server adoption stage is ${adoptionStage} but SDK mode is SHADOW. Consider updating mode to 'ENFORCE' so your application handles blocks correctly. Until updated, the SDK will allow transactions the server would block.`
+      );
+    }
+  }
   /**
    * Evaluate a transaction defense request
-   * 
+   *
    * Implements:
    * - Shadow Mode (SHADOW: monitor-only, ENFORCE: enforce decisions)
    * - Connection failure strategy (FAIL_OPEN vs FAIL_CLOSED)
@@ -2223,7 +2267,8 @@ var GateClient = class {
         }
       }
       if (result.decision === "BLOCK") {
-        if (requestMode === "SOFT_ENFORCE") {
+        const effectiveMode = result.mode ?? requestMode;
+        if (effectiveMode === "SOFT_ENFORCE") {
           console.warn("[SOFT ENFORCE] Policy violation detected - app can override", {
             requestId,
             reasonCodes: result.reasonCodes
@@ -2237,7 +2282,7 @@ var GateClient = class {
             warning: "Policy violation detected. Override at your own risk."
           };
         }
-        if (requestMode === "SHADOW") {
+        if (effectiveMode === "SHADOW") {
           console.warn("[GATE SHADOW MODE] Would have blocked transaction", {
             requestId,
             reasonCodes: result.reasonCodes,