blockintel-gate-sdk 0.3.10 → 0.3.11

package/dist/{contracts-KKk945Ox.d.cts → contracts-Dxb9vt_M.d.cts}

@@ -169,6 +169,18 @@ interface DefenseEvaluateResponseV2 {
      * Gate mode used for this evaluation
      */
     mode?: GateMode;
+    /**
+     * Gate receipt (when HARD_KMS_GATEWAY (or HARD_KMS_ATTESTED, deprecated) or receipt requested). Required for KMS signing in receipt-required mode.
+     */
+    receipt?: Record<string, unknown>;
+    /**
+     * Decision hash from receipt (SHA256 of canonical receipt payload). Used for receipt-required KMS flow.
+     */
+    decisionHash?: string;
+    /**
+     * Receipt signature (HS256:base64). Used for receipt-required KMS flow.
+     */
+    receiptSignature?: string;
     /**
      * Metadata (evaluation latency, simulation, policy hash for pinning)
      */

package/dist/{contracts-KKk945Ox.d.ts → contracts-Dxb9vt_M.d.ts}

@@ -169,6 +169,18 @@ interface DefenseEvaluateResponseV2 {
      * Gate mode used for this evaluation
      */
     mode?: GateMode;
+    /**
+     * Gate receipt (when HARD_KMS_GATEWAY (or HARD_KMS_ATTESTED, deprecated) or receipt requested). Required for KMS signing in receipt-required mode.
+     */
+    receipt?: Record<string, unknown>;
+    /**
+     * Decision hash from receipt (SHA256 of canonical receipt payload). Used for receipt-required KMS flow.
+     */
+    decisionHash?: string;
+    /**
+     * Receipt signature (HS256:base64). Used for receipt-required KMS flow.
+     */
+    receiptSignature?: string;
     /**
      * Metadata (evaluation latency, simulation, policy hash for pinning)
      */

package/dist/index.cjs

@@ -1047,13 +1047,21 @@ function computeTxDigest(binding) {
   return crypto.createHash("sha256").update(canonical, "utf8").digest("hex");
 }
 
+// src/metrics/GateMetricsSink.ts
+var noOpMetricsSink = {
+  emit() {
+  }
+};
+
 // src/kms/wrapAwsSdkV3KmsClient.ts
 function wrapKmsClient(kmsClient, gateClient, options = {}) {
   const defaultOptions = {
     mode: options.mode || "enforce",
+    requireReceiptForSign: options.requireReceiptForSign ?? false,
     onDecision: options.onDecision || (() => {
     }),
-    extractTxIntent: options.extractTxIntent || defaultExtractTxIntent
+    extractTxIntent: options.extractTxIntent || defaultExtractTxIntent,
+    metricsSink: options.metricsSink ?? noOpMetricsSink
   };
   const wrapped = new Proxy(kmsClient, {
     get(target, prop, receiver) {
@@ -1094,12 +1102,39 @@ function defaultExtractTxIntent(command) {
     // Backward compatibility
   };
 }
+function buildMetricLabels(gateClient, command, signerId, txIntent) {
+  const config = gateClient.config;
+  const keyId = command.input?.KeyId ?? command.KeyId;
+  return {
+    tenantId: config?.tenantId,
+    signerId: signerId || void 0,
+    adoptionStage: config?.adoptionStage ?? process.env.GATE_ADOPTION_STAGE,
+    env: config?.env ?? process.env.GATE_ENV ?? process.env.NODE_ENV,
+    chain: txIntent.chainId != null ? String(txIntent.chainId) : txIntent.networkFamily,
+    kmsKeyId: keyId,
+    region: process.env.AWS_REGION
+  };
+}
+function emitMetric(sink, name, labels) {
+  const event = { name, labels, timestampMs: Date.now() };
+  try {
+    const result = sink.emit(event);
+    if (result && typeof result.catch === "function") {
+      result.catch(() => {
+      });
+    }
+  } catch {
+  }
+}
 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) {
+  const labels = buildMetricLabels(gateClient, command, signerId, txIntent);
+  emitMetric(options.metricsSink, "sign_attempt_total", labels);
+  let heartbeatToken;
+  try {
+    heartbeatToken = await gateClient.heartbeatManager.getTokenForSigner(signerId, 2e3);
+  } catch {
     throw new BlockIntelBlockedError(
       "HEARTBEAT_MISSING",
       void 0,
@@ -1123,6 +1158,28 @@ async function handleSignCommand(command, originalClient, gateClient, options) {
       // Type assertion - txIntent may have extra fields
       signingContext
     });
+    if (decision.decision === "ALLOW" && options.requireReceiptForSign) {
+      const hasReceipt2 = decision.receipt != null || decision.decisionHash != null && decision.receiptSignature != null;
+      if (!hasReceipt2) {
+        emitMetric(options.metricsSink, "sign_blocked_missing_receipt_total", labels);
+        options.onDecision("BLOCK", {
+          error: new BlockIntelBlockedError(
+            "RECEIPT_REQUIRED",
+            decision.decisionId,
+            decision.correlationId,
+            void 0
+          ),
+          signerId,
+          command
+        });
+        throw new BlockIntelBlockedError(
+          "RECEIPT_REQUIRED",
+          decision.decisionId,
+          decision.correlationId,
+          void 0
+        );
+      }
+    }
     if (decision.decision === "ALLOW" && gateClient.getRequireDecisionToken() && decision.txDigest != null) {
       const binding = buildTxBindingObject(
         txIntent,
@@ -1151,6 +1208,11 @@ async function handleSignCommand(command, originalClient, gateClient, options) {
         );
       }
     }
+    const hasReceipt = decision.receipt != null || decision.decisionHash != null && decision.receiptSignature != null;
+    if (hasReceipt) {
+      emitMetric(options.metricsSink, "sign_success_with_receipt_total", labels);
+    }
+    emitMetric(options.metricsSink, "sign_success_total", labels);
     options.onDecision("ALLOW", { decision, signerId, command });
     if (options.mode === "dry-run") {
       return await originalClient.send(new clientKms.SignCommand(command));
@@ -1211,7 +1273,7 @@ var ProvenanceProvider = class {
 var HeartbeatManager = class {
   httpClient;
   tenantId;
-  signerId;
+  defaultSignerId;
   environment;
   baseRefreshIntervalSeconds;
   clientInstanceId;
@@ -1220,24 +1282,27 @@ var HeartbeatManager = class {
   // SDK version for tracking
   apiKey;
   // x-gate-heartbeat-key for Control Plane auth
-  currentToken = null;
-  refreshTimer = null;
+  signerEntries = /* @__PURE__ */ new Map();
+  evictionTimer = null;
   started = false;
-  consecutiveFailures = 0;
   maxBackoffSeconds = 30;
   // Maximum backoff interval
-  /** SignerId used for the in-flight request; used to ignore stale responses after updateSignerId(). */
-  acquiringForSignerId = null;
+  maxSigners;
+  signerIdleTtlMs;
+  localRateLimitMs;
   constructor(options) {
     this.httpClient = options.httpClient;
     this.tenantId = options.tenantId;
-    this.signerId = options.signerId;
+    this.defaultSignerId = options.signerId;
     this.environment = options.environment ?? "prod";
     this.baseRefreshIntervalSeconds = options.refreshIntervalSeconds ?? 10;
     this.apiKey = options.apiKey;
     this.clientInstanceId = options.clientInstanceId || uuid.v4();
     this.sdkVersion = options.sdkVersion || "1.0.0";
     this.apiKey = options.apiKey;
+    this.maxSigners = options.maxSigners ?? 20;
+    this.signerIdleTtlMs = options.signerIdleTtlMs ?? 3e5;
+    this.localRateLimitMs = options.localRateLimitMs ?? 2100;
   }
   /**
    * Start background heartbeat refresher.
@@ -1248,46 +1313,56 @@ var HeartbeatManager = class {
       return;
     }
     this.started = true;
-    this.acquireHeartbeat().catch((error) => {
-      console.error("[HEARTBEAT] Failed to acquire initial heartbeat:", error instanceof Error ? error.message : error);
+    this.startEvictionTimer();
+    this.getTokenForSigner(this.defaultSignerId, 0).catch((error) => {
+      console.warn("[HEARTBEAT] Failed to acquire initial heartbeat:", error instanceof Error ? error.message : error);
     });
-    this.scheduleNextRefresh();
+  }
+  startEvictionTimer() {
+    if (this.evictionTimer) clearInterval(this.evictionTimer);
+    this.evictionTimer = setInterval(() => {
+      const now = Date.now();
+      for (const [signerId, entry] of this.signerEntries) {
+        if (now - entry.lastUsedMs > this.signerIdleTtlMs) {
+          if (entry.refreshTimer) clearTimeout(entry.refreshTimer);
+          this.signerEntries.delete(signerId);
+        }
+      }
+    }, 6e4);
   }
   /**
-   * Schedule next refresh with jitter and backoff
+   * Schedule next refresh with jitter and backoff for a specific signer
    */
-  scheduleNextRefresh() {
-    if (!this.started) {
+  scheduleRefreshForSigner(signerId, entry) {
+    if (!this.started || !this.signerEntries.has(signerId)) {
       return;
     }
+    if (entry.refreshTimer) {
+      clearTimeout(entry.refreshTimer);
+      entry.refreshTimer = null;
+    }
     const baseInterval = this.baseRefreshIntervalSeconds * 1e3;
     const jitter = Math.random() * 2e3;
-    const backoff = this.calculateBackoff();
+    const backoff = Math.min(
+      Math.pow(2, entry.consecutiveFailures) * 1e3,
+      this.maxBackoffSeconds * 1e3
+    );
     const interval = baseInterval + jitter + backoff;
-    this.refreshTimer = setTimeout(() => {
-      this.acquireHeartbeat().then(() => {
-        this.consecutiveFailures = 0;
-        this.scheduleNextRefresh();
+    entry.refreshTimer = setTimeout(() => {
+      if (!this.signerEntries.has(signerId)) return;
+      entry.acquiring = true;
+      entry.acquirePromise = this.acquireHeartbeatForSigner(signerId, entry).then(() => {
+        this.scheduleRefreshForSigner(signerId, entry);
       }).catch((error) => {
-        this.consecutiveFailures++;
-        console.error("[HEARTBEAT] Refresh failed (will retry):", error);
-        this.scheduleNextRefresh();
+        entry.consecutiveFailures++;
+        console.error(`[HEARTBEAT] Refresh failed for signer ${signerId} (will retry):`, error.message || error);
+        this.scheduleRefreshForSigner(signerId, entry);
+      }).finally(() => {
+        entry.acquiring = false;
+        entry.acquirePromise = null;
       });
     }, 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
    */
@@ -1296,53 +1371,153 @@ var HeartbeatManager = class {
       return;
     }
     this.started = false;
-    if (this.refreshTimer) {
-      clearTimeout(this.refreshTimer);
-      this.refreshTimer = null;
+    if (this.evictionTimer) {
+      clearInterval(this.evictionTimer);
+      this.evictionTimer = null;
+    }
+    for (const [signerId, entry] of this.signerEntries) {
+      if (entry.refreshTimer) {
+        clearTimeout(entry.refreshTimer);
+        entry.refreshTimer = null;
+      }
     }
+    this.signerEntries.clear();
   }
   /**
-   * Get current heartbeat token if valid
+   * Get current heartbeat token if valid for the default signer
+   * @deprecated Use getTokenForSigner() instead.
    */
   getToken() {
-    if (!this.currentToken) {
-      return null;
-    }
-    const now = Math.floor(Date.now() / 1e3);
-    if (this.currentToken.expiresAt <= now + 2) {
-      return null;
+    const entry = this.signerEntries.get(this.defaultSignerId);
+    if (entry && entry.token && entry.token.expiresAt > Math.floor(Date.now() / 1e3) + 2) {
+      entry.lastUsedMs = Date.now();
+      return entry.token.token;
     }
-    return this.currentToken.token;
+    return null;
   }
   /**
-   * Check if current heartbeat token is valid
+   * Check if current heartbeat token is valid for the default signer
+   * @deprecated Use getTokenForSigner() instead.
    */
   isValid() {
     return this.getToken() !== null;
   }
   /**
    * Update signer ID (called when signer is known).
-   * Invalidates current token and triggers an immediate heartbeat acquisition so evaluate() can get a matching token.
+   * @deprecated Use getTokenForSigner() — signerId changes are handled automatically by the per-signer cache.
    */
   updateSignerId(signerId) {
-    if (this.signerId !== signerId) {
-      this.signerId = signerId;
-      this.currentToken = null;
-      if (this.started && this.apiKey) {
-        setImmediate(() => {
-          this.acquireHeartbeat().catch((err) => {
-            console.warn("[HEARTBEAT] Immediate acquire after signerId change failed:", err instanceof Error ? err.message : err);
-          });
-        });
+    this.defaultSignerId = signerId;
+  }
+  /**
+   * Get a valid heartbeat token for a specific signer.
+   * Returns immediately if a cached valid token exists.
+   * If no token, triggers acquisition and returns a Promise that resolves
+   * when the token is available (or rejects after maxWaitMs).
+   */
+  async getTokenForSigner(signerId, maxWaitMs = 2e3) {
+    if (!this.started) {
+      throw new GateError("HEARTBEAT_MISSING" /* HEARTBEAT_MISSING */, "HeartbeatManager not started");
+    }
+    const startTime = Date.now();
+    let entry = this.signerEntries.get(signerId);
+    const now = Date.now();
+    const getValidToken = (e) => {
+      if (e.token && e.token.expiresAt > Math.floor(Date.now() / 1e3) + 2) {
+        return e.token.token;
       }
+      return null;
+    };
+    if (entry) {
+      entry.lastUsedMs = now;
+      const t2 = getValidToken(entry);
+      if (t2) return t2;
+    } else {
+      if (this.signerEntries.size >= this.maxSigners) {
+        let oldestSignerId = null;
+        let oldestUsedMs = Infinity;
+        for (const [sId, e] of this.signerEntries) {
+          if (e.lastUsedMs < oldestUsedMs) {
+            oldestUsedMs = e.lastUsedMs;
+            oldestSignerId = sId;
+          }
+        }
+        if (oldestSignerId) {
+          const oldestEntry = this.signerEntries.get(oldestSignerId);
+          if (oldestEntry?.refreshTimer) clearTimeout(oldestEntry.refreshTimer);
+          this.signerEntries.delete(oldestSignerId);
+        }
+      }
+      entry = {
+        token: null,
+        refreshTimer: null,
+        consecutiveFailures: 0,
+        lastAcquireAttemptMs: 0,
+        lastUsedMs: now,
+        acquiring: false,
+        acquirePromise: null
+      };
+      this.signerEntries.set(signerId, entry);
+    }
+    if (entry.acquiring && entry.acquirePromise) {
+      const remainingWait = Math.max(0, maxWaitMs - (Date.now() - startTime));
+      try {
+        await Promise.race([
+          entry.acquirePromise,
+          new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), remainingWait))
+        ]);
+      } catch (e) {
+      }
+      const t2 = getValidToken(entry);
+      if (t2) return t2;
+    }
+    const timeSinceLastAttempt = Date.now() - entry.lastAcquireAttemptMs;
+    let timeToWaitBeforeFetch = 0;
+    if (timeSinceLastAttempt < this.localRateLimitMs) {
+      timeToWaitBeforeFetch = this.localRateLimitMs - timeSinceLastAttempt;
+    }
+    const remainingWait2 = Math.max(0, maxWaitMs - (Date.now() - startTime));
+    if (timeToWaitBeforeFetch >= remainingWait2) {
+      throw new GateError(
+        "HEARTBEAT_MISSING" /* HEARTBEAT_MISSING */,
+        "Signing blocked: Heartbeat token is missing or expired. Gate must be alive and enforcing policy."
+      );
+    }
+    if (timeToWaitBeforeFetch > 0) {
+      await new Promise((resolve) => setTimeout(resolve, timeToWaitBeforeFetch));
+    }
+    if (!entry.acquiring) {
+      entry.acquiring = true;
+      entry.acquirePromise = this.acquireHeartbeatForSigner(signerId, entry).finally(() => {
+        if (entry) {
+          entry.acquiring = false;
+          entry.acquirePromise = null;
+        }
+      });
     }
+    const remainingWait3 = Math.max(0, maxWaitMs - (Date.now() - startTime));
+    try {
+      if (entry.acquirePromise) {
+        await Promise.race([
+          entry.acquirePromise,
+          new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), remainingWait3))
+        ]);
+      }
+    } catch (e) {
+    }
+    const t = getValidToken(entry);
+    if (t) return t;
+    throw new GateError(
+      "HEARTBEAT_MISSING" /* HEARTBEAT_MISSING */,
+      "Signing blocked: Heartbeat token is missing or expired. Gate must be alive and enforcing policy."
+    );
   }
   /**
-   * Acquire a new heartbeat token from Control Plane
+   * Acquire a new heartbeat token from Control Plane for a specific signer
    * NEVER logs token value (security)
    * Requires x-gate-heartbeat-key header (apiKey) for authentication.
    */
-  async acquireHeartbeat() {
+  async acquireHeartbeatForSigner(signerId, entry) {
     if (!this.apiKey || this.apiKey.length === 0) {
       throw new GateError(
         "UNAUTHORIZED" /* UNAUTHORIZED */,
@@ -1350,8 +1525,7 @@ var HeartbeatManager = class {
         {}
       );
     }
-    const signerIdAtRequest = this.signerId;
-    this.acquiringForSignerId = signerIdAtRequest;
+    entry.lastAcquireAttemptMs = Date.now();
     try {
       const response = await this.httpClient.request({
         method: "POST",
@@ -1361,12 +1535,15 @@ var HeartbeatManager = class {
         },
         body: {
           tenantId: this.tenantId,
-          signerId: this.signerId,
+          signerId,
           environment: this.environment,
           clientInstanceId: this.clientInstanceId,
           sdkVersion: this.sdkVersion
         }
       });
+      if (!this.signerEntries.has(signerId)) {
+        return;
+      }
       if (response.success && response.data) {
         const token = response.data.heartbeatToken;
         const expiresAt = response.data.expiresAt;
@@ -1376,19 +1553,22 @@ var HeartbeatManager = class {
             "Invalid heartbeat response: missing token or expiresAt"
           );
         }
-        if (this.signerId === signerIdAtRequest) {
-          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
-          });
+        entry.token = {
+          token,
+          expiresAt,
+          jti: response.data.jti,
+          policyHash: response.data.policyHash
+        };
+        entry.consecutiveFailures = 0;
+        console.log("[HEARTBEAT] Acquired heartbeat token", {
+          expiresAt,
+          signerId,
+          jti: response.data.jti,
+          policyHash: response.data.policyHash?.substring(0, 8) + "..."
+          // DO NOT log token value
+        });
+        if (!entry.refreshTimer) {
+          this.scheduleRefreshForSigner(signerId, entry);
         }
       } else {
         const error = response.error || {};
@@ -1398,12 +1578,8 @@ var HeartbeatManager = class {
         );
       }
     } catch (error) {
-      console.error("[HEARTBEAT] Failed to acquire heartbeat:", error.message || error);
+      console.error(`[HEARTBEAT] Failed to acquire heartbeat for signer ${signerId}:`, error.message || error);
       throw error;
-    } finally {
-      if (this.acquiringForSignerId === signerIdAtRequest) {
-        this.acquiringForSignerId = null;
-      }
     }
   }
   /**
@@ -1659,6 +1835,7 @@ var IamPermissionRiskChecker = class {
 };
 
 // src/client/GateClient.ts
+var DEFAULT_SIGNER_ID = "gate-sdk-client";
 var GateClient = class {
   config;
   httpClient;
@@ -1733,7 +1910,7 @@ var GateClient = class {
         // 5s timeout for heartbeat
         userAgent: config.userAgent
       });
-      const initialSignerId = config.signerId ?? "trading-bot-signer";
+      const initialSignerId = config.signerId ?? DEFAULT_SIGNER_ID;
       this.heartbeatManager = new HeartbeatManager({
         httpClient: heartbeatHttpClient,
         tenantId: config.tenantId,
@@ -1808,26 +1985,10 @@ var GateClient = class {
     const requestMode = req.mode || this.mode;
     const requireToken = this.getRequireDecisionToken();
     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 effectiveSignerId2 = req.signingContext?.signerId ?? req.signingContext?.actorPrincipal ?? DEFAULT_SIGNER_ID;
+        heartbeatToken = await this.heartbeatManager.getTokenForSigner(effectiveSignerId2, 2e3);
       }
       const txIntent = { ...req.txIntent };
       if (txIntent.to && !txIntent.toAddress) {
@@ -1840,10 +2001,11 @@ var GateClient = class {
       if (txIntent.from && !txIntent.fromAddress) {
         delete txIntent.from;
       }
+      const effectiveSignerId = req.signingContext?.signerId ?? req.signingContext?.actorPrincipal ?? DEFAULT_SIGNER_ID;
       const signingContext = {
         ...req.signingContext,
-        actorPrincipal: req.signingContext?.actorPrincipal ?? req.signingContext?.signerId ?? "gate-sdk-client",
-        signerId: req.signingContext?.signerId ?? req.signingContext?.actorPrincipal ?? "gate-sdk-client"
+        actorPrincipal: req.signingContext?.actorPrincipal ?? req.signingContext?.signerId ?? DEFAULT_SIGNER_ID,
+        signerId: effectiveSignerId
       };
       if (heartbeatToken) {
         signingContext.heartbeatToken = heartbeatToken;
@@ -1960,6 +2122,9 @@ var GateClient = class {
         enforced: responseData.enforced ?? requestMode === "ENFORCE",
         shadowWouldBlock: responseData.shadow_would_block ?? responseData.shadowWouldBlock ?? false,
         mode: responseData.mode ?? requestMode,
+        receipt: responseData.receipt,
+        decisionHash: responseData.decision_hash ?? responseData.decisionHash,
+        receiptSignature: responseData.receipt_signature ?? responseData.receiptSignature,
         ...simulationData ? {
           simulation: {
             willRevert: simulationData.willRevert ?? simulationData.will_revert ?? false,
@@ -3053,6 +3218,7 @@ exports.buildTxBindingObject = buildTxBindingObject;
 exports.computeTxDigest = computeTxDigest;
 exports.createGateClient = createGateClient;
 exports.default = GateClient;
+exports.noOpMetricsSink = noOpMetricsSink;
 exports.wrapKmsClient = wrapKmsClient;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map