blockintel-gate-sdk 0.3.9 → 0.3.11

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as _aws_sdk_client_kms from '@aws-sdk/client-kms';
 import { SignCommandInput, KMSClient, SigningAlgorithmSpec } from '@aws-sdk/client-kms';
-import { G as GateClientConfig, D as DefenseEvaluateRequestV2, a as DefenseEvaluateResponseV2, M as MetricsCollector, S as StepUpStatusResponse, b as StepUpFinalResult, c as SigningContext, A as AttestCompletedRequest, d as AttestCompletedResponse } from './contracts-KKk945Ox.cjs';
-export { E as EvaluationMode, e as GateDecision, f as GateMode, h as GateStepUpStatus, g as StepUpMetadata, T as TransactionIntentV2 } from './contracts-KKk945Ox.cjs';
+import { G as GateClientConfig, D as DefenseEvaluateRequestV2, a as DefenseEvaluateResponseV2, M as MetricsCollector, S as StepUpStatusResponse, b as StepUpFinalResult, c as SigningContext, A as AttestCompletedRequest, d as AttestCompletedResponse } from './contracts-Dxb9vt_M.cjs';
+export { E as EvaluationMode, e as GateDecision, f as GateMode, h as GateStepUpStatus, g as StepUpMetadata, T as TransactionIntentV2 } from './contracts-Dxb9vt_M.cjs';
 
 /**
  * Circuit Breaker for SDK
@@ -50,6 +50,36 @@ declare class CircuitBreaker {
     reset(): void;
 }
 
+/**
+ * Pluggable metrics sink for Gate SDK sign attempts.
+ * Used to compute receipt coverage % (signed_with_receipt / sign_attempts) for underwriting.
+ * Default: no-op. Wire to POST /api/v1/gate/metrics/sign for backend aggregation.
+ */
+type GateSignMetricName = 'sign_attempt_total' | 'sign_blocked_missing_receipt_total' | 'sign_blocked_invalid_receipt_total' | 'sign_success_with_receipt_total' | 'sign_success_total';
+interface GateMetricEventLabels {
+    tenantId?: string;
+    signerId?: string;
+    adoptionStage?: string;
+    env?: string;
+    chain?: string;
+    kmsKeyId?: string;
+    region?: string;
+}
+interface GateMetricEvent {
+    name: GateSignMetricName;
+    labels: GateMetricEventLabels;
+    timestampMs?: number;
+}
+/**
+ * Sink for sign metrics. Implement to forward events to your backend (e.g. POST /api/v1/gate/metrics/sign).
+ * Default when not provided: no-op.
+ */
+interface GateMetricsSink {
+    emit(event: GateMetricEvent): void | Promise<void>;
+}
+/** No-op sink (default). */
+declare const noOpMetricsSink: GateMetricsSink;
+
 /**
  * BlockIntel Gate SDK - AWS SDK v3 KMS Wrapper
  *
@@ -66,6 +96,11 @@ interface WrapKmsClientOptions {
      * - "dry-run": Evaluate but always allow KMS call (for testing)
      */
     mode?: 'enforce' | 'dry-run';
+    /**
+     * When true (e.g. HARD_KMS_ATTESTED mode), KMS Sign is only allowed if the evaluate response
+     * includes a receipt (or decisionHash). Rejects with RECEIPT_REQUIRED if missing.
+     */
+    requireReceiptForSign?: boolean;
     /**
      * Callback invoked when a decision is made
      */
@@ -80,6 +115,11 @@ interface WrapKmsClientOptions {
         chainId?: number;
         [key: string]: any;
     };
+    /**
+     * Optional metrics sink for observability.
+     * If not provided, uses no-op sink (metrics are discarded).
+     */
+    metricsSink?: GateMetricsSink;
 }
 /**
  * Wrapped KMS client type (proxy that intercepts send calls)
@@ -547,17 +587,19 @@ interface HeartbeatToken {
 declare class HeartbeatManager {
     private readonly httpClient;
     private readonly tenantId;
-    private signerId;
+    private defaultSignerId;
     private readonly environment;
     private readonly baseRefreshIntervalSeconds;
     private readonly clientInstanceId;
     private readonly sdkVersion;
     private readonly apiKey;
-    private currentToken;
-    private refreshTimer;
+    private readonly signerEntries;
+    private evictionTimer;
     private started;
-    private consecutiveFailures;
     private maxBackoffSeconds;
+    private readonly maxSigners;
+    private readonly signerIdleTtlMs;
+    private readonly localRateLimitMs;
     constructor(options: {
         httpClient: HttpClient;
         tenantId: string;
@@ -568,6 +610,9 @@ declare class HeartbeatManager {
         sdkVersion?: string;
         /** API key for heartbeat endpoint auth (x-gate-heartbeat-key). Required unless local mode. */
         apiKey?: string;
+        maxSigners?: number;
+        signerIdleTtlMs?: number;
+        localRateLimitMs?: number;
     });
     /**
      * Start background heartbeat refresher.
@@ -576,36 +621,43 @@ declare class HeartbeatManager {
     start(options?: {
         waitForInitial?: boolean;
     }): void;
+    private startEvictionTimer;
     /**
-     * Schedule next refresh with jitter and backoff
+     * Schedule next refresh with jitter and backoff for a specific signer
      */
-    private scheduleNextRefresh;
-    /**
-     * Calculate exponential backoff (capped at maxBackoffSeconds)
-     */
-    private calculateBackoff;
+    private scheduleRefreshForSigner;
     /**
      * Stop background heartbeat refresher
      */
     stop(): void;
     /**
-     * Get current heartbeat token if valid
+     * Get current heartbeat token if valid for the default signer
+     * @deprecated Use getTokenForSigner() instead.
      */
     getToken(): string | null;
     /**
-     * Check if current heartbeat token is valid
+     * Check if current heartbeat token is valid for the default signer
+     * @deprecated Use getTokenForSigner() instead.
      */
     isValid(): boolean;
     /**
-     * Update signer ID (called when signer is known)
+     * Update signer ID (called when signer is known).
+     * @deprecated Use getTokenForSigner() — signerId changes are handled automatically by the per-signer cache.
      */
     updateSignerId(signerId: string): void;
     /**
-     * Acquire a new heartbeat token from Control Plane
+     * 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).
+     */
+    getTokenForSigner(signerId: string, maxWaitMs?: number): Promise<string>;
+    /**
+     * 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.
      */
-    private acquireHeartbeat;
+    private acquireHeartbeatForSigner;
     /**
      * Get client instance ID (for tracking)
      */
@@ -892,4 +944,4 @@ declare class GenericHsmSigner implements SignerBackend {
     close(): Promise<void>;
 }
 
-export { AttestCompletedRequest, AttestCompletedResponse, AwsKmsSigner, BlockIntelAuthError, BlockIntelBlockedError, BlockIntelStepUpRequiredError, BlockIntelUnavailableError, DefenseEvaluateRequestV2, DefenseEvaluateResponseV2, FireblocksSigner, type FireblocksSignerConfig, Gate, GateClient, GateClientConfig, GateError, GateErrorCode, GcpKmsSigner, GenericHsmSigner, type GenericHsmSignerConfig, HeartbeatManager, type HeartbeatToken, type Pkcs11Session, type Provenance, ProvenanceProvider, type SignRequest, type SignResponse, type SignerBackend, SigningContext, StepUpFinalResult, StepUpNotConfiguredError, StepUpStatusResponse, type TxBindingObject, VaultSigner, type WrapKmsClientOptions, type WrappedKmsClient, buildTxBindingObject, computeTxDigest, createGateClient, GateClient as default, wrapKmsClient };
+export { AttestCompletedRequest, AttestCompletedResponse, AwsKmsSigner, BlockIntelAuthError, BlockIntelBlockedError, BlockIntelStepUpRequiredError, BlockIntelUnavailableError, DefenseEvaluateRequestV2, DefenseEvaluateResponseV2, FireblocksSigner, type FireblocksSignerConfig, Gate, GateClient, GateClientConfig, GateError, GateErrorCode, type GateMetricEvent, type GateMetricEventLabels, type GateMetricsSink, type GateSignMetricName, GcpKmsSigner, GenericHsmSigner, type GenericHsmSignerConfig, HeartbeatManager, type HeartbeatToken, type Pkcs11Session, type Provenance, ProvenanceProvider, type SignRequest, type SignResponse, type SignerBackend, SigningContext, StepUpFinalResult, StepUpNotConfiguredError, StepUpStatusResponse, type TxBindingObject, VaultSigner, type WrapKmsClientOptions, type WrappedKmsClient, buildTxBindingObject, computeTxDigest, createGateClient, GateClient as default, noOpMetricsSink, wrapKmsClient };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as _aws_sdk_client_kms from '@aws-sdk/client-kms';
 import { SignCommandInput, KMSClient, SigningAlgorithmSpec } from '@aws-sdk/client-kms';
-import { G as GateClientConfig, D as DefenseEvaluateRequestV2, a as DefenseEvaluateResponseV2, M as MetricsCollector, S as StepUpStatusResponse, b as StepUpFinalResult, c as SigningContext, A as AttestCompletedRequest, d as AttestCompletedResponse } from './contracts-KKk945Ox.js';
-export { E as EvaluationMode, e as GateDecision, f as GateMode, h as GateStepUpStatus, g as StepUpMetadata, T as TransactionIntentV2 } from './contracts-KKk945Ox.js';
+import { G as GateClientConfig, D as DefenseEvaluateRequestV2, a as DefenseEvaluateResponseV2, M as MetricsCollector, S as StepUpStatusResponse, b as StepUpFinalResult, c as SigningContext, A as AttestCompletedRequest, d as AttestCompletedResponse } from './contracts-Dxb9vt_M.js';
+export { E as EvaluationMode, e as GateDecision, f as GateMode, h as GateStepUpStatus, g as StepUpMetadata, T as TransactionIntentV2 } from './contracts-Dxb9vt_M.js';
 
 /**
  * Circuit Breaker for SDK
@@ -50,6 +50,36 @@ declare class CircuitBreaker {
     reset(): void;
 }
 
+/**
+ * Pluggable metrics sink for Gate SDK sign attempts.
+ * Used to compute receipt coverage % (signed_with_receipt / sign_attempts) for underwriting.
+ * Default: no-op. Wire to POST /api/v1/gate/metrics/sign for backend aggregation.
+ */
+type GateSignMetricName = 'sign_attempt_total' | 'sign_blocked_missing_receipt_total' | 'sign_blocked_invalid_receipt_total' | 'sign_success_with_receipt_total' | 'sign_success_total';
+interface GateMetricEventLabels {
+    tenantId?: string;
+    signerId?: string;
+    adoptionStage?: string;
+    env?: string;
+    chain?: string;
+    kmsKeyId?: string;
+    region?: string;
+}
+interface GateMetricEvent {
+    name: GateSignMetricName;
+    labels: GateMetricEventLabels;
+    timestampMs?: number;
+}
+/**
+ * Sink for sign metrics. Implement to forward events to your backend (e.g. POST /api/v1/gate/metrics/sign).
+ * Default when not provided: no-op.
+ */
+interface GateMetricsSink {
+    emit(event: GateMetricEvent): void | Promise<void>;
+}
+/** No-op sink (default). */
+declare const noOpMetricsSink: GateMetricsSink;
+
 /**
  * BlockIntel Gate SDK - AWS SDK v3 KMS Wrapper
  *
@@ -66,6 +96,11 @@ interface WrapKmsClientOptions {
      * - "dry-run": Evaluate but always allow KMS call (for testing)
      */
     mode?: 'enforce' | 'dry-run';
+    /**
+     * When true (e.g. HARD_KMS_ATTESTED mode), KMS Sign is only allowed if the evaluate response
+     * includes a receipt (or decisionHash). Rejects with RECEIPT_REQUIRED if missing.
+     */
+    requireReceiptForSign?: boolean;
     /**
      * Callback invoked when a decision is made
      */
@@ -80,6 +115,11 @@ interface WrapKmsClientOptions {
         chainId?: number;
         [key: string]: any;
     };
+    /**
+     * Optional metrics sink for observability.
+     * If not provided, uses no-op sink (metrics are discarded).
+     */
+    metricsSink?: GateMetricsSink;
 }
 /**
  * Wrapped KMS client type (proxy that intercepts send calls)
@@ -547,17 +587,19 @@ interface HeartbeatToken {
 declare class HeartbeatManager {
     private readonly httpClient;
     private readonly tenantId;
-    private signerId;
+    private defaultSignerId;
     private readonly environment;
     private readonly baseRefreshIntervalSeconds;
     private readonly clientInstanceId;
     private readonly sdkVersion;
     private readonly apiKey;
-    private currentToken;
-    private refreshTimer;
+    private readonly signerEntries;
+    private evictionTimer;
     private started;
-    private consecutiveFailures;
     private maxBackoffSeconds;
+    private readonly maxSigners;
+    private readonly signerIdleTtlMs;
+    private readonly localRateLimitMs;
     constructor(options: {
         httpClient: HttpClient;
         tenantId: string;
@@ -568,6 +610,9 @@ declare class HeartbeatManager {
         sdkVersion?: string;
         /** API key for heartbeat endpoint auth (x-gate-heartbeat-key). Required unless local mode. */
         apiKey?: string;
+        maxSigners?: number;
+        signerIdleTtlMs?: number;
+        localRateLimitMs?: number;
     });
     /**
      * Start background heartbeat refresher.
@@ -576,36 +621,43 @@ declare class HeartbeatManager {
     start(options?: {
         waitForInitial?: boolean;
     }): void;
+    private startEvictionTimer;
     /**
-     * Schedule next refresh with jitter and backoff
+     * Schedule next refresh with jitter and backoff for a specific signer
      */
-    private scheduleNextRefresh;
-    /**
-     * Calculate exponential backoff (capped at maxBackoffSeconds)
-     */
-    private calculateBackoff;
+    private scheduleRefreshForSigner;
     /**
      * Stop background heartbeat refresher
      */
     stop(): void;
     /**
-     * Get current heartbeat token if valid
+     * Get current heartbeat token if valid for the default signer
+     * @deprecated Use getTokenForSigner() instead.
      */
     getToken(): string | null;
     /**
-     * Check if current heartbeat token is valid
+     * Check if current heartbeat token is valid for the default signer
+     * @deprecated Use getTokenForSigner() instead.
      */
     isValid(): boolean;
     /**
-     * Update signer ID (called when signer is known)
+     * Update signer ID (called when signer is known).
+     * @deprecated Use getTokenForSigner() — signerId changes are handled automatically by the per-signer cache.
      */
     updateSignerId(signerId: string): void;
     /**
-     * Acquire a new heartbeat token from Control Plane
+     * 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).
+     */
+    getTokenForSigner(signerId: string, maxWaitMs?: number): Promise<string>;
+    /**
+     * 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.
      */
-    private acquireHeartbeat;
+    private acquireHeartbeatForSigner;
     /**
      * Get client instance ID (for tracking)
      */
@@ -892,4 +944,4 @@ declare class GenericHsmSigner implements SignerBackend {
     close(): Promise<void>;
 }
 
-export { AttestCompletedRequest, AttestCompletedResponse, AwsKmsSigner, BlockIntelAuthError, BlockIntelBlockedError, BlockIntelStepUpRequiredError, BlockIntelUnavailableError, DefenseEvaluateRequestV2, DefenseEvaluateResponseV2, FireblocksSigner, type FireblocksSignerConfig, Gate, GateClient, GateClientConfig, GateError, GateErrorCode, GcpKmsSigner, GenericHsmSigner, type GenericHsmSignerConfig, HeartbeatManager, type HeartbeatToken, type Pkcs11Session, type Provenance, ProvenanceProvider, type SignRequest, type SignResponse, type SignerBackend, SigningContext, StepUpFinalResult, StepUpNotConfiguredError, StepUpStatusResponse, type TxBindingObject, VaultSigner, type WrapKmsClientOptions, type WrappedKmsClient, buildTxBindingObject, computeTxDigest, createGateClient, GateClient as default, wrapKmsClient };
+export { AttestCompletedRequest, AttestCompletedResponse, AwsKmsSigner, BlockIntelAuthError, BlockIntelBlockedError, BlockIntelStepUpRequiredError, BlockIntelUnavailableError, DefenseEvaluateRequestV2, DefenseEvaluateResponseV2, FireblocksSigner, type FireblocksSignerConfig, Gate, GateClient, GateClientConfig, GateError, GateErrorCode, type GateMetricEvent, type GateMetricEventLabels, type GateMetricsSink, type GateSignMetricName, GcpKmsSigner, GenericHsmSigner, type GenericHsmSignerConfig, HeartbeatManager, type HeartbeatToken, type Pkcs11Session, type Provenance, ProvenanceProvider, type SignRequest, type SignResponse, type SignerBackend, SigningContext, StepUpFinalResult, StepUpNotConfiguredError, StepUpStatusResponse, type TxBindingObject, VaultSigner, type WrapKmsClientOptions, type WrappedKmsClient, buildTxBindingObject, computeTxDigest, createGateClient, GateClient as default, noOpMetricsSink, wrapKmsClient };