blockintel-gate-sdk 0.3.10 → 0.4.0

package/README.md

@@ -408,11 +408,27 @@ The SDK includes a **Heartbeat Manager** that automatically acquires and refresh
 
 ### How It Works
 
-1. **Automatic Token Acquisition**: The SDK automatically starts a background heartbeat refresher when the `GateClient` is initialized. This continuously sends heartbeats to the Control Plane, keeping the signer status active in the UI.
-2. **Token Refresh**: Heartbeat tokens are refreshed every 10 seconds (configurable via `heartbeatRefreshIntervalSeconds`) to maintain a valid token
-3. **Signing Enforcement**: Before any `evaluate()` call, the SDK checks for a valid heartbeat token. If missing or expired, it throws `HEARTBEAT_MISSING` error
-4. **Token Inclusion**: The heartbeat token is automatically included in the `signingContext` of every evaluation request
-5. **No Manual Scripts Needed**: The SDK handles all heartbeat management automatically - no need for separate heartbeat scripts
+1. **Per-Signer Token Cache**: The heartbeat manager maintains a `Map<signerId, SignerHeartbeatEntry>` so each signer gets its own cached token, refresh timer, and backoff state. Switching between signers never invalidates other signers' tokens.
+2. **Automatic Token Acquisition**: When `getTokenForSigner(signerId)` is called, the manager returns the cached token immediately if valid, or acquires a new one on demand. The initial default signer is pre-warmed on `start()`.
+3. **Per-Signer Refresh**: Each signer entry has its own background `setTimeout` timer that refreshes the token before expiry (default every 10 seconds + jitter + backoff on failure).
+4. **LRU Eviction**: When the number of concurrent signer entries exceeds `maxSigners` (default: 20), the least-recently-used entry is evicted.
+5. **Idle TTL Eviction**: A background timer (every 60s) evicts signer entries not used within `signerIdleTtlMs` (default: 5 minutes).
+6. **Local Rate Limiting**: Per-signer guard prevents re-requesting within `localRateLimitMs` (default: 2.1s) to avoid hammering the Control Plane.
+7. **Token Inclusion**: The heartbeat token is automatically included in the `signingContext` of every evaluation request.
+
+### Multi-Signer Support
+
+Trading desks running 3+ bot profiles no longer experience `HEARTBEAT_MISSING` errors when switching signers. Each signer's token is cached independently:
+
+```typescript
+// KMS wrapper automatically uses the correct signer from KeyId
+const protectedKms = gate.wrapKmsClient(kmsClient);
+
+// These calls use independent heartbeat tokens — no cross-invalidation
+await protectedKms.sign({ KeyId: 'alias/bot-1', Message: tx1, ... });
+await protectedKms.sign({ KeyId: 'alias/bot-2', Message: tx2, ... });
+await protectedKms.sign({ KeyId: 'alias/bot-1', Message: tx3, ... }); // cache hit
+```
 
 ### Configuration
 
@@ -426,8 +442,11 @@ const gate = new GateClient({
   // Heartbeat manager uses baseUrl to infer Control Plane URL
   // Or explicitly set controlPlaneUrl if different
   controlPlaneUrl: 'https://control-plane.blockintelai.com',  // Optional
-  signerId: 'my-signer-id',  // Optional: signerId for heartbeat (if known upfront)
+  signerId: 'my-signer-id',  // Optional: default signerId for heartbeat (if known upfront)
   heartbeatRefreshIntervalSeconds: 10,  // Optional: heartbeat refresh interval (default: 10s)
+  maxSigners: 20,             // Optional: max concurrent signer entries (default: 20)
+  signerIdleTtlMs: 300000,    // Optional: evict idle signers after this many ms (default: 5 min)
+  localRateLimitMs: 2100,     // Optional: min ms between acquire attempts per signer (default: 2.1s)
 });
 ```
 
@@ -458,23 +477,17 @@ try {
 
 ### Heartbeat Manager API
 
-The heartbeat manager is internal to the SDK, but you can access it if needed:
+The primary API is `getTokenForSigner()`, which handles cache lookup, on-demand acquisition, and waiting:
 
 ```typescript
-// Check if heartbeat is valid
-const isValid = gate.heartbeatManager.isValid();
-
-// Get current heartbeat token (if valid)
-const token = gate.heartbeatManager.getToken();
-
-// Update signer ID (called automatically when signer is known)
-gate.heartbeatManager.updateSignerId('new-signer-id');
+// Get token for a specific signer
+const token = await gate.heartbeatManager.getTokenForSigner('my-signer-id', 2000);
 
-// Stop heartbeat refresher (e.g., on shutdown)
+// Stop heartbeat manager and clean up all timers (e.g., on shutdown)
 gate.heartbeatManager.stop();
 ```
 
-**Note**: The heartbeat manager automatically updates the `signerId` when using the KMS wrapper, so manual updates are typically not needed.
+**Note**: The KMS wrapper automatically calls `getTokenForSigner()` with the correct signer ID extracted from `KeyId`, so manual token management is typically not needed.
 
 ## Secret Rotation
 

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)
      */