blockintel-gate-sdk 0.3.1 → 0.3.3

package/dist/index.cjs

@@ -6,64 +6,48 @@ var uuid = require('uuid');
 var clientKms = require('@aws-sdk/client-kms');
 var crypto$1 = require('crypto');
 
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
   get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
 }) : x)(function(x) {
   if (typeof require !== "undefined") return require.apply(this, arguments);
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
-
-// src/utils/crypto.ts
-async function hmacSha256(secret, message) {
-  if (typeof crypto !== "undefined" && crypto.subtle) {
-    const encoder = new TextEncoder();
-    const keyData = encoder.encode(secret);
-    const messageData = encoder.encode(message);
-    const key = await crypto.subtle.importKey(
-      "raw",
-      keyData,
-      { name: "HMAC", hash: "SHA-256" },
-      false,
-      ["sign"]
-    );
-    const signature = await crypto.subtle.sign("HMAC", key, messageData);
-    const hashArray = Array.from(new Uint8Array(signature));
-    return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
-  }
-  if (typeof __require !== "undefined") {
-    const crypto2 = __require("crypto");
-    const hmac = crypto2.createHmac("sha256", secret);
-    hmac.update(message, "utf8");
-    return hmac.digest("hex");
-  }
-  throw new Error("HMAC-SHA256 not available in this environment");
-}
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 
 // src/utils/canonicalJson.ts
+var canonicalJson_exports = {};
+__export(canonicalJson_exports, {
+  canonicalizeJson: () => canonicalizeJson,
+  sha256Hex: () => sha256Hex
+});
 function canonicalizeJson(obj) {
   if (obj === null || obj === void 0) {
     return "null";
   }
-  if (typeof obj === "string") {
-    return JSON.stringify(obj);
-  }
-  if (typeof obj === "number" || typeof obj === "boolean") {
-    return String(obj);
-  }
-  if (Array.isArray(obj)) {
-    const items = obj.map((item) => canonicalizeJson(item));
-    return `[${items.join(",")}]`;
-  }
-  if (typeof obj === "object") {
-    const keys = Object.keys(obj).sort();
-    const pairs = keys.map((key) => {
-      const value = obj[key];
-      const canonicalValue = canonicalizeJson(value);
-      return `${JSON.stringify(key)}:${canonicalValue}`;
-    });
-    return `{${pairs.join(",")}}`;
+  const cloned = JSON.parse(JSON.stringify(obj));
+  function sortKeys(item) {
+    if (Array.isArray(item)) {
+      return item.map(sortKeys);
+    }
+    if (item !== null && typeof item === "object") {
+      const sorted2 = {};
+      Object.keys(item).sort().forEach((key) => {
+        sorted2[key] = sortKeys(item[key]);
+      });
+      return sorted2;
+    }
+    return item;
   }
-  return JSON.stringify(obj);
+  const sorted = sortKeys(cloned);
+  return JSON.stringify(sorted);
 }
 async function sha256Hex(input) {
   if (typeof crypto !== "undefined" && crypto.subtle) {
@@ -79,14 +63,53 @@ async function sha256Hex(input) {
   }
   throw new Error("SHA-256 not available in this environment");
 }
+var init_canonicalJson = __esm({
+  "src/utils/canonicalJson.ts"() {
+  }
+});
+
+// src/utils/crypto.ts
+async function hmacSha256(secret, message) {
+  if (typeof __require !== "undefined") {
+    const crypto2 = __require("crypto");
+    const hmac = crypto2.createHmac("sha256", secret);
+    hmac.update(message, "utf8");
+    const signatureHex = hmac.digest("hex");
+    console.error("[HMAC CRYPTO DEBUG] Signature computation:", JSON.stringify({
+      secretLength: secret.length,
+      messageLength: message.length,
+      messagePreview: message.substring(0, 200) + "...",
+      signatureLength: signatureHex.length,
+      signaturePreview: signatureHex.substring(0, 16) + "..."
+    }, null, 2));
+    return signatureHex;
+  }
+  if (typeof crypto !== "undefined" && crypto.subtle) {
+    const encoder = new TextEncoder();
+    const keyData = encoder.encode(secret);
+    const messageData = encoder.encode(message);
+    const key = await crypto.subtle.importKey(
+      "raw",
+      keyData,
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"]
+    );
+    const signature = await crypto.subtle.sign("HMAC", key, messageData);
+    const hashArray = Array.from(new Uint8Array(signature));
+    return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  throw new Error("HMAC-SHA256 not available in this environment");
+}
 
 // src/auth/HmacSigner.ts
+init_canonicalJson();
 var HmacSigner = class {
   keyId;
   secret;
   constructor(config) {
     this.keyId = config.keyId;
-    this.secret = config.secret;
+    this.secret = config.secret.trim();
     if (!this.secret || this.secret.length === 0) {
       throw new Error("HMAC secret cannot be empty");
     }
@@ -109,7 +132,26 @@ var HmacSigner = class {
       // Used as nonce in canonical string
       bodyHash
     ].join("\n");
+    console.error("[HMAC SIGNER DEBUG] Canonical request string:", JSON.stringify({
+      method: method.toUpperCase(),
+      path,
+      tenantId,
+      keyId: this.keyId,
+      timestampMs: String(timestampMs),
+      requestId,
+      bodyHash,
+      signingStringLength: signingString.length,
+      signingStringPreview: signingString.substring(0, 200) + "...",
+      bodyJsonLength: bodyJson.length,
+      bodyJsonPreview: bodyJson.substring(0, 200) + "..."
+    }, null, 2));
     const signature = await hmacSha256(this.secret, signingString);
+    console.error("[HMAC SIGNER DEBUG] Signature computed:", JSON.stringify({
+      signatureLength: signature.length,
+      signaturePreview: signature.substring(0, 16) + "...",
+      secretLength: this.secret.length,
+      secretPreview: this.secret.substring(0, 4) + "..." + this.secret.substring(this.secret.length - 4)
+    }, null, 2));
     return {
       "X-GATE-TENANT-ID": tenantId,
       "X-GATE-KEY-ID": this.keyId,
@@ -158,6 +200,10 @@ var GateErrorCode = /* @__PURE__ */ ((GateErrorCode2) => {
   GateErrorCode2["BLOCKED"] = "BLOCKED";
   GateErrorCode2["SERVICE_UNAVAILABLE"] = "SERVICE_UNAVAILABLE";
   GateErrorCode2["AUTH_ERROR"] = "AUTH_ERROR";
+  GateErrorCode2["HEARTBEAT_MISSING"] = "HEARTBEAT_MISSING";
+  GateErrorCode2["HEARTBEAT_EXPIRED"] = "HEARTBEAT_EXPIRED";
+  GateErrorCode2["HEARTBEAT_INVALID"] = "HEARTBEAT_INVALID";
+  GateErrorCode2["HEARTBEAT_MISMATCH"] = "HEARTBEAT_MISMATCH";
   return GateErrorCode2;
 })(GateErrorCode || {});
 var GateError = class extends Error {
@@ -339,21 +385,55 @@ var HttpClient = class {
     const url = `${this.baseUrl}${path}`;
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+    let requestDetailsForLogging = null;
+    let requestDetailsSet = false;
     try {
       const response = await retryWithBackoff(
         async () => {
+          const requestHeaders = {};
+          for (const [key, value] of Object.entries(headers)) {
+            requestHeaders[key] = String(value);
+          }
+          requestHeaders["User-Agent"] = this.userAgent;
+          requestHeaders["Content-Type"] = "application/json";
           const fetchOptions = {
             method,
-            headers: {
-              ...headers,
-              "User-Agent": this.userAgent,
-              "Content-Type": "application/json"
-            },
+            headers: requestHeaders,
             signal: controller.signal
           };
           if (body) {
-            fetchOptions.body = JSON.stringify(body);
+            if (body.__canonicalJson) {
+              fetchOptions.body = body.__canonicalJson;
+              delete body.__canonicalJson;
+            } else {
+              fetchOptions.body = JSON.stringify(body);
+            }
+          }
+          const logHeaders = {};
+          if (fetchOptions.headers) {
+            Object.entries(fetchOptions.headers).forEach(([key, value]) => {
+              if (key.toLowerCase().includes("signature") || key.toLowerCase().includes("secret")) {
+                logHeaders[key] = String(value).substring(0, 8) + "...";
+              } else {
+                logHeaders[key] = String(value);
+              }
+            });
           }
+          const bodyStr = typeof fetchOptions.body === "string" ? fetchOptions.body : null;
+          const details = {
+            headers: logHeaders,
+            bodyLength: bodyStr ? bodyStr.length : 0,
+            bodyPreview: bodyStr ? bodyStr.substring(0, 300) : null
+          };
+          requestDetailsForLogging = details;
+          requestDetailsSet = true;
+          console.error("[HTTP CLIENT DEBUG] Sending request:", JSON.stringify({
+            url,
+            method,
+            headers: logHeaders,
+            bodyLength: requestDetailsForLogging.bodyLength,
+            bodyPreview: requestDetailsForLogging.bodyPreview
+          }, null, 2));
           const res = await fetch(url, fetchOptions);
           if (!res.ok && isRetryableStatus(res.status)) {
             throw res;
@@ -371,10 +451,26 @@ var HttpClient = class {
       clearTimeout(timeoutId);
       let data;
       const contentType = response.headers.get("content-type");
+      console.error("[HTTP CLIENT DEBUG] Response received:", JSON.stringify({
+        status: response.status,
+        ok: response.ok,
+        statusText: response.statusText,
+        contentType,
+        url: response.url
+      }, null, 2));
       if (contentType && contentType.includes("application/json")) {
         try {
-          data = await response.json();
+          const jsonText = await response.text();
+          console.error("[HTTP CLIENT DEBUG] Response body (first 500 chars):", jsonText.substring(0, 500));
+          data = JSON.parse(jsonText);
+          console.error("[HTTP CLIENT DEBUG] Parsed JSON:", JSON.stringify({
+            hasSuccess: typeof data?.success !== "undefined",
+            success: data?.success,
+            hasData: typeof data?.data !== "undefined",
+            hasError: typeof data?.error !== "undefined"
+          }, null, 2));
         } catch (parseError) {
+          console.error("[HTTP CLIENT DEBUG] JSON parse error:", parseError);
           throw new GateError(
             "INVALID_RESPONSE" /* INVALID_RESPONSE */,
             "Failed to parse JSON response",
@@ -398,6 +494,32 @@ var HttpClient = class {
         );
       }
       if (!response.ok) {
+        const responseHeaders = {};
+        response.headers.forEach((value, key) => {
+          responseHeaders[key] = value;
+        });
+        if (response.status === 401) {
+          console.error("[HTTP CLIENT DEBUG] 401 UNAUTHORIZED - Full request details:", JSON.stringify({
+            status: response.status,
+            statusText: response.statusText,
+            url: response.url,
+            requestMethod: method,
+            requestPath: path,
+            requestHeaders: requestDetailsForLogging ? requestDetailsForLogging.headers : {},
+            responseHeaders,
+            responseData: data,
+            bodyLength: requestDetailsForLogging ? requestDetailsForLogging.bodyLength : 0,
+            bodyPreview: requestDetailsForLogging ? requestDetailsForLogging.bodyPreview : null
+          }, null, 2));
+        } else {
+          console.error("[HTTP CLIENT DEBUG] Response not OK:", JSON.stringify({
+            status: response.status,
+            statusText: response.statusText,
+            url: response.url,
+            headers: responseHeaders,
+            data
+          }, null, 2));
+        }
         const errorCode = this.statusToErrorCode(response.status);
         const correlationId = response.headers.get("X-Correlation-ID") ?? void 0;
         throw new GateError(errorCode, `HTTP ${response.status}: ${response.statusText}`, {
@@ -407,6 +529,7 @@ var HttpClient = class {
           details: data
         });
       }
+      console.error("[HTTP CLIENT DEBUG] Response OK, returning data");
       return data;
     } catch (error) {
       clearTimeout(timeoutId);
@@ -716,6 +839,10 @@ var MetricsCollector = class {
   timeoutsTotal = 0;
   errorsTotal = 0;
   circuitBreakerOpenTotal = 0;
+  wouldBlockTotal = 0;
+  // Shadow mode would-block count
+  failOpenTotal = 0;
+  // Fail-open count
   latencyMs = [];
   maxSamples = 1e3;
   // Keep last 1000 samples
@@ -731,6 +858,12 @@ var MetricsCollector = class {
       this.blockedTotal++;
     } else if (decision === "REQUIRE_STEP_UP") {
       this.stepupTotal++;
+    } else if (decision === "WOULD_BLOCK") {
+      this.wouldBlockTotal++;
+      this.allowedTotal++;
+    } else if (decision === "FAIL_OPEN") {
+      this.failOpenTotal++;
+      this.allowedTotal++;
     }
     this.latencyMs.push(latencyMs);
     if (this.latencyMs.length > this.maxSamples) {
@@ -772,6 +905,8 @@ var MetricsCollector = class {
       timeoutsTotal: this.timeoutsTotal,
       errorsTotal: this.errorsTotal,
       circuitBreakerOpenTotal: this.circuitBreakerOpenTotal,
+      wouldBlockTotal: this.wouldBlockTotal,
+      failOpenTotal: this.failOpenTotal,
       latencyMs: [...this.latencyMs]
       // Copy array
     };
@@ -806,6 +941,8 @@ var MetricsCollector = class {
     this.timeoutsTotal = 0;
     this.errorsTotal = 0;
     this.circuitBreakerOpenTotal = 0;
+    this.wouldBlockTotal = 0;
+    this.failOpenTotal = 0;
     this.latencyMs = [];
   }
 };
@@ -858,10 +995,25 @@ function defaultExtractTxIntent(command) {
 async function handleSignCommand(command, originalClient, gateClient, options) {
   const txIntent = options.extractTxIntent(command);
   const signerId = command.input?.KeyId ?? command.KeyId ?? "unknown";
+  gateClient.heartbeatManager.updateSignerId(signerId);
+  const heartbeatToken = gateClient.heartbeatManager.getToken();
+  if (!heartbeatToken) {
+    throw new BlockIntelBlockedError(
+      "HEARTBEAT_MISSING",
+      void 0,
+      // receiptId
+      void 0,
+      // correlationId
+      void 0
+      // requestId
+    );
+  }
   const signingContext = {
     signerId,
-    actorPrincipal: "kms-signer"
+    actorPrincipal: "kms-signer",
     // Default - can be customized via extractTxIntent
+    heartbeatToken
+    // Attach heartbeat token
   };
   try {
     const decision = await gateClient.evaluate({
@@ -926,6 +1078,421 @@ var ProvenanceProvider = class {
     return !!(process.env.GATE_CALLER_REPO || process.env.GATE_CALLER_WORKFLOW || process.env.GATE_ATTESTATION_VALID);
   }
 };
+var HeartbeatManager = class {
+  httpClient;
+  tenantId;
+  signerId;
+  environment;
+  baseRefreshIntervalSeconds;
+  clientInstanceId;
+  // Unique per process
+  sdkVersion;
+  // SDK version for tracking
+  currentToken = null;
+  refreshTimer = null;
+  started = false;
+  consecutiveFailures = 0;
+  maxBackoffSeconds = 30;
+  // Maximum backoff interval
+  constructor(options) {
+    this.httpClient = options.httpClient;
+    this.tenantId = options.tenantId;
+    this.signerId = options.signerId;
+    this.environment = options.environment ?? "prod";
+    this.baseRefreshIntervalSeconds = options.refreshIntervalSeconds ?? 10;
+    this.clientInstanceId = options.clientInstanceId || uuid.v4();
+    this.sdkVersion = options.sdkVersion || "1.0.0";
+  }
+  /**
+   * Start background heartbeat refresher
+   */
+  start() {
+    if (this.started) {
+      return;
+    }
+    this.started = true;
+    this.acquireHeartbeat().catch((error) => {
+      console.error("[HEARTBEAT] Failed to acquire initial heartbeat:", error);
+    });
+    this.scheduleNextRefresh();
+  }
+  /**
+   * Schedule next refresh with jitter and backoff
+   */
+  scheduleNextRefresh() {
+    if (!this.started) {
+      return;
+    }
+    const baseInterval = this.baseRefreshIntervalSeconds * 1e3;
+    const jitter = Math.random() * 2e3;
+    const backoff = this.calculateBackoff();
+    const interval = baseInterval + jitter + backoff;
+    this.refreshTimer = setTimeout(() => {
+      this.acquireHeartbeat().then(() => {
+        this.consecutiveFailures = 0;
+        this.scheduleNextRefresh();
+      }).catch((error) => {
+        this.consecutiveFailures++;
+        console.error("[HEARTBEAT] Refresh failed (will retry):", error);
+        this.scheduleNextRefresh();
+      });
+    }, interval);
+  }
+  /**
+   * Calculate exponential backoff (capped at maxBackoffSeconds)
+   */
+  calculateBackoff() {
+    if (this.consecutiveFailures === 0) {
+      return 0;
+    }
+    const backoffSeconds = Math.min(
+      Math.pow(2, this.consecutiveFailures) * 1e3,
+      this.maxBackoffSeconds * 1e3
+    );
+    return backoffSeconds;
+  }
+  /**
+   * Stop background heartbeat refresher
+   */
+  stop() {
+    if (!this.started) {
+      return;
+    }
+    this.started = false;
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  }
+  /**
+   * Get current heartbeat token if valid
+   */
+  getToken() {
+    if (!this.currentToken) {
+      return null;
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    if (this.currentToken.expiresAt <= now + 2) {
+      return null;
+    }
+    return this.currentToken.token;
+  }
+  /**
+   * Check if current heartbeat token is valid
+   */
+  isValid() {
+    return this.getToken() !== null;
+  }
+  /**
+   * Update signer ID (called when signer is known)
+   */
+  updateSignerId(signerId) {
+    if (this.signerId !== signerId) {
+      this.signerId = signerId;
+      this.currentToken = null;
+    }
+  }
+  /**
+   * Acquire a new heartbeat token from Control Plane
+   * NEVER logs token value (security)
+   */
+  async acquireHeartbeat() {
+    try {
+      const response = await this.httpClient.request({
+        method: "POST",
+        path: "/api/v1/gate/heartbeat",
+        body: {
+          tenantId: this.tenantId,
+          signerId: this.signerId,
+          environment: this.environment,
+          clientInstanceId: this.clientInstanceId,
+          sdkVersion: this.sdkVersion
+        }
+      });
+      if (response.success && response.data) {
+        const token = response.data.heartbeatToken;
+        const expiresAt = response.data.expiresAt;
+        if (!token || !expiresAt) {
+          throw new GateError(
+            "INVALID_RESPONSE" /* INVALID_RESPONSE */,
+            "Invalid heartbeat response: missing token or expiresAt"
+          );
+        }
+        this.currentToken = {
+          token,
+          expiresAt,
+          jti: response.data.jti,
+          policyHash: response.data.policyHash
+        };
+        console.log("[HEARTBEAT] Acquired heartbeat token", {
+          expiresAt,
+          jti: response.data.jti,
+          policyHash: response.data.policyHash?.substring(0, 8) + "..."
+          // DO NOT log token value
+        });
+      } else {
+        const error = response.error || {};
+        throw new GateError(
+          "SERVER_ERROR" /* SERVER_ERROR */,
+          `Heartbeat acquisition failed: ${error.message || "Unknown error"}`
+        );
+      }
+    } catch (error) {
+      console.error("[HEARTBEAT] Failed to acquire heartbeat:", error.message || error);
+      throw error;
+    }
+  }
+  /**
+   * Get client instance ID (for tracking)
+   */
+  getClientInstanceId() {
+    return this.clientInstanceId;
+  }
+};
+
+// src/security/IamPermissionRiskChecker.ts
+var IamPermissionRiskChecker = class {
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Perform synchronous IAM permission risk check
+   * 
+   * Performs quick checks (credentials, environment markers) synchronously.
+   * In HARD mode, throws error if risk detected and override not set.
+   * 
+   * Use this for blocking initialization checks.
+   */
+  checkSync() {
+    const checks = [];
+    const credentialsCheck = this.checkAwsCredentials();
+    if (credentialsCheck.hasRisk) {
+      checks.push(credentialsCheck);
+    }
+    const envCheck = this.checkEnvironmentMarkers();
+    if (envCheck.hasRisk) {
+      checks.push(envCheck);
+    }
+    const highestConfidence = this.getHighestConfidence(checks);
+    const highestRisk = checks.find((c) => c.confidence === highestConfidence);
+    if (!highestRisk || !highestRisk.hasRisk) {
+      return {
+        hasRisk: false,
+        confidence: "LOW",
+        details: "No IAM permission risk detected (synchronous check)"
+      };
+    }
+    if (this.options.enforcementMode === "HARD" && !this.options.allowInsecureKmsSignPermission) {
+      const errorMessage = this.buildErrorMessage(highestRisk);
+      throw new Error(errorMessage);
+    }
+    this.logWarning(highestRisk);
+    return highestRisk;
+  }
+  /**
+   * Perform full IAM permission risk check (including async IAM simulation)
+   * 
+   * Returns risk assessment with confidence level.
+   * In HARD mode, throws error if risk detected and override not set.
+   */
+  async check() {
+    const syncResult = this.checkSync();
+    const simulationCheck = await this.checkIamSimulation();
+    if (simulationCheck.hasRisk) {
+      if (this.options.enforcementMode === "HARD" && !this.options.allowInsecureKmsSignPermission) {
+        const errorMessage = this.buildErrorMessage(simulationCheck);
+        throw new Error(errorMessage);
+      }
+      this.logWarning(simulationCheck);
+      return simulationCheck;
+    }
+    return syncResult;
+  }
+  /**
+   * Check if AWS credentials are present
+   */
+  checkAwsCredentials() {
+    const hasEnvVars = !!(process.env.AWS_ACCESS_KEY_ID || process.env.AWS_SECRET_ACCESS_KEY || process.env.AWS_SESSION_TOKEN);
+    const hasRoleCredentials = !!(process.env.AWS_ROLE_ARN || process.env.AWS_WEB_IDENTITY_TOKEN_FILE || process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI);
+    if (hasEnvVars || hasRoleCredentials) {
+      return {
+        hasRisk: true,
+        riskType: "AWS_CREDENTIALS_DETECTED",
+        confidence: "MEDIUM",
+        details: "AWS credentials detected in environment. Application may have direct KMS signing permissions.",
+        remediation: "Remove kms:Sign permission from application role. See https://docs.blockintel.ai/gate/IAM_HARDENING"
+      };
+    }
+    return {
+      hasRisk: false,
+      confidence: "LOW",
+      details: "No AWS credentials detected in environment variables"
+    };
+  }
+  /**
+   * Check IAM permissions using simulation API (if available)
+   */
+  async checkIamSimulation() {
+    try {
+      const iamModule = await import('@aws-sdk/client-iam').catch(() => null);
+      if (!iamModule || !iamModule.IAMClient || !iamModule.SimulatePrincipalPolicyCommand) {
+        return {
+          hasRisk: false,
+          confidence: "LOW",
+          details: "AWS SDK not available for IAM simulation"
+        };
+      }
+      const { IAMClient, SimulatePrincipalPolicyCommand } = iamModule;
+      const principalArn = await this.getCurrentPrincipalArn();
+      if (!principalArn) {
+        return {
+          hasRisk: false,
+          confidence: "LOW",
+          details: "Could not determine current principal ARN for simulation"
+        };
+      }
+      const client = new IAMClient({});
+      const command = new SimulatePrincipalPolicyCommand({
+        PolicySourceArn: principalArn,
+        ActionNames: ["kms:Sign"],
+        ResourceArns: this.options.kmsKeyIds?.map((id) => `arn:aws:kms:*:*:key/${id}`) || ["arn:aws:kms:*:*:key/*"]
+      });
+      const response = await client.send(command).catch(() => null);
+      if (!response) {
+        return {
+          hasRisk: false,
+          confidence: "LOW",
+          details: "IAM simulation not available (may require additional permissions)"
+        };
+      }
+      const allowsSign = response.EvaluationResults?.some(
+        (result) => result.EvalDecision === "allowed" || result.EvalDecision === "explicitAllow"
+      );
+      if (allowsSign) {
+        return {
+          hasRisk: true,
+          riskType: "DIRECT_KMS_SIGN_PERMISSION",
+          confidence: "HIGH",
+          details: `IAM simulation confirms principal ${principalArn} has kms:Sign permission. Direct KMS signing can bypass Gate.`,
+          remediation: "Remove kms:Sign permission from application role. See https://docs.blockintel.ai/gate/IAM_HARDENING"
+        };
+      }
+      return {
+        hasRisk: false,
+        confidence: "HIGH",
+        details: "IAM simulation confirms no kms:Sign permission"
+      };
+    } catch (error) {
+      return {
+        hasRisk: false,
+        confidence: "LOW",
+        details: `IAM simulation failed: ${error instanceof Error ? error.message : "Unknown error"}`
+      };
+    }
+  }
+  /**
+   * Check environment markers that suggest direct KMS usage
+   */
+  checkEnvironmentMarkers() {
+    const markers = [
+      "KMS_KEY_ID",
+      "AWS_KMS_KEY_ID",
+      "KMS_KEY_ARN",
+      "AWS_KMS_KEY_ARN"
+    ];
+    const foundMarkers = markers.filter((marker) => process.env[marker]);
+    if (foundMarkers.length > 0) {
+      return {
+        hasRisk: true,
+        riskType: "ENVIRONMENT_MARKERS",
+        confidence: "LOW",
+        details: `Environment markers suggest direct KMS usage: ${foundMarkers.join(", ")}`,
+        remediation: "Review environment variables and ensure KMS access is gated through Gate SDK"
+      };
+    }
+    return {
+      hasRisk: false,
+      confidence: "LOW",
+      details: "No environment markers suggesting direct KMS usage"
+    };
+  }
+  /**
+   * Get current principal ARN (best-effort)
+   */
+  async getCurrentPrincipalArn() {
+    try {
+      const stsModule = await import('@aws-sdk/client-sts').catch(() => null);
+      if (!stsModule || !stsModule.STSClient || !stsModule.GetCallerIdentityCommand) {
+        return null;
+      }
+      const { STSClient, GetCallerIdentityCommand } = stsModule;
+      const client = new STSClient({});
+      const command = new GetCallerIdentityCommand({});
+      const response = await client.send(command).catch(() => null);
+      if (response?.Arn) {
+        return response.Arn;
+      }
+    } catch (error) {
+    }
+    return null;
+  }
+  /**
+   * Get highest confidence level from checks
+   */
+  getHighestConfidence(checks) {
+    if (checks.some((c) => c.confidence === "HIGH")) {
+      return "HIGH";
+    }
+    if (checks.some((c) => c.confidence === "MEDIUM")) {
+      return "MEDIUM";
+    }
+    return "LOW";
+  }
+  /**
+   * Build error message for HARD mode
+   */
+  buildErrorMessage(result) {
+    const parts = [
+      "[GATE ERROR] Hard enforcement mode blocked initialization:",
+      `  - IAM permission risk: ${result.details}`,
+      `  - Risk type: ${result.riskType}`,
+      `  - Confidence: ${result.confidence}`,
+      `  - Tenant ID: ${this.options.tenantId}`
+    ];
+    if (this.options.signerId) {
+      parts.push(`  - Signer ID: ${this.options.signerId}`);
+    }
+    if (this.options.environment) {
+      parts.push(`  - Environment: ${this.options.environment}`);
+    }
+    if (result.remediation) {
+      parts.push(`  - Remediation: ${result.remediation}`);
+    }
+    parts.push("  - See: https://docs.blockintel.ai/gate/IAM_HARDENING");
+    parts.push(`  - Override: Set allowInsecureKmsSignPermission=true (not recommended for production)`);
+    return parts.join("\n");
+  }
+  /**
+   * Log warning (SOFT mode or override set)
+   */
+  logWarning(result) {
+    const logData = {
+      level: "WARN",
+      message: "IAM permission risk detected",
+      tenantId: this.options.tenantId,
+      signerId: this.options.signerId,
+      environment: this.options.environment,
+      enforcementMode: this.options.enforcementMode,
+      riskType: result.riskType,
+      confidence: result.confidence,
+      details: result.details,
+      remediation: result.remediation,
+      documentation: "https://docs.blockintel.ai/gate/IAM_HARDENING"
+    };
+    console.warn("[GATE WARNING]", JSON.stringify(logData, null, 2));
+  }
+};
 
 // src/client/GateClient.ts
 var GateClient = class {
@@ -936,8 +1503,18 @@ var GateClient = class {
   stepUpPoller;
   circuitBreaker;
   metrics;
+  heartbeatManager;
+  mode;
+  onConnectionFailure;
   constructor(config) {
     this.config = config;
+    const envMode = process.env.GATE_MODE;
+    this.mode = envMode || config.mode || "SHADOW";
+    if (config.onConnectionFailure) {
+      this.onConnectionFailure = config.onConnectionFailure;
+    } else {
+      this.onConnectionFailure = this.mode === "SHADOW" ? "FAIL_OPEN" : "FAIL_CLOSED";
+    }
     if (config.auth.mode === "hmac") {
       this.hmacSigner = new HmacSigner({
         keyId: config.auth.keyId,
@@ -968,11 +1545,73 @@ var GateClient = class {
     if (config.onMetrics) {
       this.metrics.registerHook(config.onMetrics);
     }
+    if (config.local) {
+      console.warn("[GATE CLIENT] LOCAL MODE ENABLED - Auth, heartbeat, and break-glass are disabled");
+      this.heartbeatManager = null;
+    } else {
+      let controlPlaneUrl = config.baseUrl;
+      if (controlPlaneUrl.includes("/defense")) {
+        controlPlaneUrl = controlPlaneUrl.split("/defense")[0];
+      }
+      if (config.controlPlaneUrl) {
+        controlPlaneUrl = config.controlPlaneUrl;
+      }
+      const heartbeatHttpClient = new HttpClient({
+        baseUrl: controlPlaneUrl,
+        timeoutMs: 5e3,
+        // 5s timeout for heartbeat
+        userAgent: config.userAgent
+      });
+      const initialSignerId = config.signerId ?? "trading-bot-signer";
+      this.heartbeatManager = new HeartbeatManager({
+        httpClient: heartbeatHttpClient,
+        tenantId: config.tenantId,
+        signerId: initialSignerId,
+        environment: config.environment ?? "prod",
+        refreshIntervalSeconds: config.heartbeatRefreshIntervalSeconds ?? 10
+      });
+      this.heartbeatManager.start();
+    }
+    if (!config.local) {
+      const enforcementMode = config.enforcementMode || "SOFT";
+      const allowInsecureKmsSignPermission = config.allowInsecureKmsSignPermission ?? enforcementMode === "SOFT";
+      const riskChecker = new IamPermissionRiskChecker({
+        tenantId: config.tenantId,
+        signerId: config.signerId,
+        environment: config.environment,
+        enforcementMode,
+        allowInsecureKmsSignPermission,
+        kmsKeyIds: config.kmsKeyIds
+      });
+      riskChecker.checkSync();
+      this.performIamRiskCheckAsync(riskChecker, enforcementMode).catch((error) => {
+        if (enforcementMode === "SOFT" || allowInsecureKmsSignPermission) {
+          console.warn("[GATE CLIENT] Async IAM risk check warning:", error instanceof Error ? error.message : String(error));
+        } else {
+          console.error("[GATE CLIENT] Async IAM risk check found risk after initialization:", error);
+        }
+      });
+    }
+  }
+  /**
+   * Perform async IAM permission risk check (non-blocking)
+   * 
+   * Performs async IAM simulation check in background.
+   * Logs warnings but doesn't block (initialization already completed).
+   */
+  async performIamRiskCheckAsync(riskChecker, enforcementMode) {
+    try {
+      await riskChecker.check();
+    } catch (error) {
+      console.warn("[GATE CLIENT] Async IAM risk check warning:", error instanceof Error ? error.message : String(error));
+    }
   }
   /**
    * Evaluate a transaction defense request
    * 
    * Implements:
+   * - Shadow Mode (SHADOW: monitor-only, ENFORCE: enforce decisions)
+   * - Connection failure strategy (FAIL_OPEN vs FAIL_CLOSED)
    * - Circuit breaker protection
    * - Fail-safe modes (ALLOW_ON_TIMEOUT, BLOCK_ON_TIMEOUT, BLOCK_ON_ANOMALY)
    * - Metrics collection
@@ -983,7 +1622,29 @@ var GateClient = class {
     const timestampMs = req.timestampMs ?? nowMs();
     const startTime = Date.now();
     const failSafeMode = this.config.failSafeMode ?? "ALLOW_ON_TIMEOUT";
+    const requestMode = req.mode || this.mode;
     const executeRequest = async () => {
+      if (!this.config.local && this.heartbeatManager && req.signingContext?.signerId) {
+        this.heartbeatManager.updateSignerId(req.signingContext.signerId);
+      }
+      let heartbeatToken = null;
+      if (!this.config.local && this.heartbeatManager) {
+        heartbeatToken = this.heartbeatManager.getToken();
+        if (!heartbeatToken) {
+          const maxWaitMs = 2e3;
+          const startTime2 = Date.now();
+          while (!heartbeatToken && Date.now() - startTime2 < maxWaitMs) {
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            heartbeatToken = this.heartbeatManager.getToken();
+          }
+        }
+        if (!heartbeatToken) {
+          throw new GateError(
+            "HEARTBEAT_MISSING" /* HEARTBEAT_MISSING */,
+            "Signing blocked: Heartbeat token is missing or expired. Gate must be alive and enforcing policy."
+          );
+        }
+      }
       const txIntent = { ...req.txIntent };
       if (txIntent.to && !txIntent.toAddress) {
         txIntent.toAddress = txIntent.to;
@@ -996,9 +1657,11 @@ var GateClient = class {
         delete txIntent.from;
       }
       const signingContext = {
-        ...req.signingContext,
-        actorPrincipal: req.signingContext?.actorPrincipal || req.signingContext?.signerId || "unknown"
+        ...req.signingContext
       };
+      if (heartbeatToken) {
+        signingContext.heartbeatToken = heartbeatToken;
+      }
       const provenance = ProvenanceProvider.getProvenance();
       if (provenance) {
         signingContext.caller = {
@@ -1009,20 +1672,36 @@ var GateClient = class {
           attestation: provenance.attestation
         };
       }
-      const body = {
+      let body = {
         requestId,
-        tenantId: this.config.tenantId,
         timestampMs,
         txIntent,
         signingContext,
         // Add SDK info (required by Hot Path validation)
+        // Note: Must match Python SDK name for consistent canonical JSON
         sdk: {
-          name: "blockintel-gate-sdk",
+          name: "gate-sdk",
           version: "0.1.0"
-        }
+        },
+        // Add mode and connection failure strategy
+        mode: requestMode,
+        onConnectionFailure: this.onConnectionFailure
       };
-      let headers;
-      if (this.hmacSigner) {
+      if (req.simulate === true) {
+        body.simulate = true;
+      }
+      if (!this.config.local && this.config.breakglassToken) {
+        signingContext.breakglassToken = this.config.breakglassToken;
+      }
+      let headers = {};
+      if (this.config.local) {
+        headers = {
+          "Content-Type": "application/json"
+        };
+        console.log("[GATE CLIENT] LOCAL MODE - Skipping authentication");
+      } else if (this.hmacSigner) {
+        const { canonicalizeJson: canonicalizeJson2 } = await Promise.resolve().then(() => (init_canonicalJson(), canonicalJson_exports));
+        const canonicalBodyJson = canonicalizeJson2(body);
         const hmacHeaders = await this.hmacSigner.signRequest({
           method: "POST",
           path: "/defense/evaluate",
@@ -1030,8 +1709,19 @@ var GateClient = class {
           timestampMs,
           requestId,
           body
+          // Pass original body - HmacSigner will canonicalize it internally
         });
         headers = { ...hmacHeaders };
+        body.__canonicalJson = canonicalBodyJson;
+        const debugHeaders = {};
+        Object.entries(headers).forEach(([key, value]) => {
+          if (key.toLowerCase().includes("signature")) {
+            debugHeaders[key] = value.substring(0, 8) + "...";
+          } else {
+            debugHeaders[key] = value;
+          }
+        });
+        console.error("[GATE CLIENT DEBUG] HMAC headers prepared:", JSON.stringify(debugHeaders, null, 2));
       } else if (this.apiKeyAuth) {
         const apiKeyHeaders = this.apiKeyAuth.createHeaders({
           tenantId: this.config.tenantId,
@@ -1039,6 +1729,7 @@ var GateClient = class {
           requestId
         });
         headers = { ...apiKeyHeaders };
+        console.error("[GATE CLIENT DEBUG] API key headers prepared:", JSON.stringify(headers, null, 2));
       } else {
         throw new Error("No authentication configured");
       }
@@ -1049,17 +1740,35 @@ var GateClient = class {
         body,
         requestId
       });
-      if (!apiResponse.success || !apiResponse.data) {
+      let responseData;
+      if (apiResponse.success === true && apiResponse.data) {
+        responseData = apiResponse.data;
+      } else if (apiResponse.success === false && apiResponse.error) {
+        const error = apiResponse.error;
+        throw new GateError(
+          error.code || "SERVER_ERROR" /* SERVER_ERROR */,
+          error.message || "Request failed",
+          {
+            status: error.status,
+            correlationId: error.correlationId,
+            requestId,
+            details: error
+          }
+        );
+      } else if (apiResponse.decision) {
+        responseData = apiResponse;
+      } else {
         throw new GateError(
           "INVALID_RESPONSE" /* INVALID_RESPONSE */,
-          "Invalid response format: expected { success: true, data: { ... } }",
+          "Invalid response format: expected { success: true, data: { ... } } or unwrapped response",
           {
             requestId,
             details: apiResponse
           }
         );
       }
-      const responseData = apiResponse.data;
+      const metadata = responseData.metadata || {};
+      const simulationData = metadata.simulation;
       const result = {
         decision: responseData.decision,
         reasonCodes: responseData.reason_codes ?? responseData.reasonCodes ?? [],
@@ -1068,10 +1777,38 @@ var GateClient = class {
         stepUp: responseData.step_up ? {
           requestId: responseData.step_up.request_id ?? (responseData.stepUp?.requestId ?? ""),
           ttlSeconds: responseData.step_up.ttl_seconds ?? responseData.stepUp?.ttlSeconds
-        } : responseData.stepUp
+        } : responseData.stepUp,
+        enforced: responseData.enforced ?? requestMode === "ENFORCE",
+        shadowWouldBlock: responseData.shadow_would_block ?? responseData.shadowWouldBlock ?? false,
+        mode: responseData.mode ?? requestMode,
+        ...simulationData ? {
+          simulation: {
+            willRevert: simulationData.willRevert ?? simulationData.will_revert ?? false,
+            gasUsed: simulationData.gasUsed ?? simulationData.gas_used,
+            balanceChanges: simulationData.balanceChanges ?? simulationData.balance_changes,
+            errorReason: simulationData.errorReason ?? simulationData.error_reason
+          },
+          simulationLatencyMs: metadata.simulationLatencyMs ?? metadata.simulation_latency_ms
+        } : {}
       };
       const latencyMs = Date.now() - startTime;
       if (result.decision === "BLOCK") {
+        if (requestMode === "SHADOW") {
+          console.warn("[GATE SHADOW MODE] Would have blocked transaction", {
+            requestId,
+            reasonCodes: result.reasonCodes,
+            correlationId: result.correlationId,
+            tenantId: this.config.tenantId,
+            signerId: req.signingContext?.signerId
+          });
+          this.metrics.recordRequest("WOULD_BLOCK", latencyMs);
+          return {
+            ...result,
+            decision: "ALLOW",
+            enforced: false,
+            shadowWouldBlock: true
+          };
+        }
         const receiptId = responseData.decision_id || requestId;
         const reasonCode = result.reasonCodes[0] || "POLICY_VIOLATION";
         this.metrics.recordRequest("BLOCK", latencyMs);
@@ -1116,6 +1853,31 @@ var GateClient = class {
           requestId
         );
       }
+      const isConnectionFailure = error instanceof GateError && (error.code === "TIMEOUT" /* TIMEOUT */ || error.code === "SERVER_ERROR" /* SERVER_ERROR */) || error instanceof BlockIntelUnavailableError || error?.code === "ECONNREFUSED" || error?.code === "ENOTFOUND" || error?.code === "ETIMEDOUT";
+      if (isConnectionFailure) {
+        this.metrics.recordTimeout();
+        if (this.onConnectionFailure === "FAIL_OPEN") {
+          console.error("[GATE CONNECTION FAILURE] FAIL_OPEN mode - allowing transaction", {
+            requestId,
+            error: error.message,
+            tenantId: this.config.tenantId,
+            mode: requestMode
+          });
+          this.metrics.recordRequest("FAIL_OPEN", Date.now() - startTime);
+          return {
+            decision: "ALLOW",
+            reasonCodes: ["GATE_HOTPATH_UNAVAILABLE"],
+            correlationId: requestId,
+            enforced: false,
+            mode: requestMode
+          };
+        } else {
+          throw new BlockIntelUnavailableError(
+            `Signing blocked: Gate hot path unreachable (fail-closed). ${error.message}`,
+            requestId
+          );
+        }
+      }
       if (error instanceof GateError && error.code === "TIMEOUT" /* TIMEOUT */) {
         this.metrics.recordTimeout();
         const failSafeResult = this.handleFailSafe(failSafeMode, error, requestId);
@@ -1235,6 +1997,7 @@ exports.BlockIntelUnavailableError = BlockIntelUnavailableError;
 exports.GateClient = GateClient;
 exports.GateError = GateError;
 exports.GateErrorCode = GateErrorCode;
+exports.HeartbeatManager = HeartbeatManager;
 exports.ProvenanceProvider = ProvenanceProvider;
 exports.StepUpNotConfiguredError = StepUpNotConfiguredError;
 exports.createGateClient = createGateClient;