blockintel-gate-sdk 0.2.0 → 0.3.1

package/README.md

@@ -254,6 +254,10 @@ try {
 - `INVALID_RESPONSE` - Invalid response format
 - `STEP_UP_NOT_CONFIGURED` - Step-up required but not enabled
 - `STEP_UP_TIMEOUT` - Step-up polling timeout
+- `HEARTBEAT_MISSING` - Heartbeat token is missing or expired
+- `HEARTBEAT_EXPIRED` - Heartbeat token has expired
+- `HEARTBEAT_INVALID` - Heartbeat token is invalid
+- `HEARTBEAT_MISMATCH` - Heartbeat token does not match expected parameters
 
 ## Authentication
 
@@ -263,9 +267,11 @@ The SDK implements HMAC v1 signing for secure authentication:
 
 **Signing String:**
 ```
+v1\n
 <HTTP_METHOD>\n
 <PATH>\n
 <TENANT_ID>\n
+<KEY_ID>\n
 <TIMESTAMP_MS>\n
 <REQUEST_ID>\n
 <SHA256_HEX_OF_BODY>\n
@@ -329,6 +335,78 @@ The SDK automatically retries failed requests:
 - Same `requestId` is used across all retries
 - Ensures idempotency on Gate server
 
+## Heartbeat System
+
+The SDK includes a **Heartbeat Manager** that automatically acquires and refreshes heartbeat tokens from the Gate Control Plane. Heartbeat tokens are required for all signing operations and ensure that Gate is alive and enforcing policy.
+
+### How It Works
+
+1. **Automatic Token Acquisition**: The SDK automatically starts a background heartbeat refresher when the `GateClient` is initialized
+2. **Token Refresh**: Heartbeat tokens are refreshed every 10 seconds (configurable) 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
+
+### Configuration
+
+The heartbeat manager is automatically configured based on your `GateClientConfig`:
+
+```typescript
+const gate = new GateClient({
+  baseUrl: 'https://gate.blockintelai.net',  // Hot Path URL
+  tenantId: 'your-tenant-id',
+  auth: { mode: 'hmac', ... },
+  // Heartbeat manager uses baseUrl to infer Control Plane URL
+  // Or explicitly set controlPlaneUrl if different
+  controlPlaneUrl: 'https://control-plane.blockintelai.net',  // Optional
+  defaultSignerId: 'my-signer-id',  // Optional: default signerId for heartbeat
+});
+```
+
+### Heartbeat Token Properties
+
+- **TTL**: 15-30 seconds (short-lived for security)
+- **Scope**: Scoped to `tenantId`, `signerId`, `environment`, and `policyVersion`
+- **Validation**: Hot Path validates heartbeat tokens before processing any transaction
+- **Enforcement**: "No valid heartbeat → NO SIGNATURE" - transactions are blocked if heartbeat is missing or expired
+
+### Error Handling
+
+```typescript
+import { GateError, GateErrorCode } from '@blockintel/gate-sdk';
+
+try {
+  const response = await gate.evaluate({ ... });
+} catch (error) {
+  if (error instanceof GateError) {
+    if (error.code === GateErrorCode.HEARTBEAT_MISSING) {
+      console.error('Heartbeat token missing - Gate may be down or unreachable');
+    } else if (error.code === GateErrorCode.HEARTBEAT_EXPIRED) {
+      console.error('Heartbeat token expired - will retry automatically');
+    }
+  }
+}
+```
+
+### Heartbeat Manager API
+
+The heartbeat manager is internal to the SDK, but you can access it if needed:
+
+```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');
+
+// Stop heartbeat refresher (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.
+
 ## Secret Rotation
 
 For HMAC authentication, secret rotation is the customer's responsibility:
@@ -345,6 +423,7 @@ The SDK does not cache secrets across process restarts unless the user explicitl
 - **Secret Protection:** Never logs secrets or API keys
 - **Clock Skew:** Configurable tolerance for timestamp validation
 - **Replay Protection:** Request ID + timestamp prevent replay attacks
+- **Heartbeat Enforcement:** All signing operations require valid heartbeat tokens
 
 ## TypeScript Support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blockintel-gate-sdk",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Production-grade TypeScript/Node.js SDK for BlockIntel Gate Hot Path",
   "type": "module",
   "main": "./dist/index.cjs",