blockintel-gate-sdk 0.3.0 → 0.3.2

package/dist/index.d.cts

@@ -14,6 +14,8 @@ interface Metrics {
     timeoutsTotal: number;
     errorsTotal: number;
     circuitBreakerOpenTotal: number;
+    wouldBlockTotal: number;
+    failOpenTotal: number;
     latencyMs: number[];
 }
 type MetricsHook = (metrics: Metrics) => void | Promise<void>;
@@ -28,13 +30,15 @@ declare class MetricsCollector {
     private timeoutsTotal;
     private errorsTotal;
     private circuitBreakerOpenTotal;
+    private wouldBlockTotal;
+    private failOpenTotal;
     private latencyMs;
     private readonly maxSamples;
     private readonly hooks;
     /**
      * Record a request
      */
-    recordRequest(decision: 'ALLOW' | 'BLOCK' | 'REQUIRE_STEP_UP', latencyMs: number): void;
+    recordRequest(decision: 'ALLOW' | 'BLOCK' | 'REQUIRE_STEP_UP' | 'WOULD_BLOCK' | 'FAIL_OPEN', latencyMs: number): void;
     /**
      * Record a timeout
      */
@@ -111,6 +115,13 @@ interface DefenseEvaluateRequestV2 {
     signingContext?: SigningContext;
     requestId?: string;
     timestampMs?: number;
+    /**
+     * Enable transaction simulation (optional, defaults to false)
+     *
+     * When true, Hot Path will simulate the transaction after static policy evaluation.
+     * Adds 300-800ms latency but provides additional security checks.
+     */
+    simulate?: boolean;
 }
 /**
  * Gate decision types
@@ -132,6 +143,18 @@ interface DefenseEvaluateResponseV2 {
     policyVersion?: string;
     correlationId?: string;
     stepUp?: StepUpMetadata;
+    /**
+     * Whether the decision was enforced (false in SHADOW mode)
+     */
+    enforced?: boolean;
+    /**
+     * Whether shadow mode would have blocked (true if mode=SHADOW and decision=BLOCK)
+     */
+    shadowWouldBlock?: boolean;
+    /**
+     * Gate mode used for this evaluation
+     */
+    mode?: GateMode;
 }
 /**
  * Step-up status types
@@ -162,9 +185,23 @@ interface StepUpFinalResult {
     correlationId?: string;
 }
 /**
- * Fail-safe mode for SDK
+ * Fail-safe mode for SDK (deprecated - use onConnectionFailure instead)
  */
 type FailSafeMode = 'ALLOW_ON_TIMEOUT' | 'BLOCK_ON_TIMEOUT' | 'BLOCK_ON_ANOMALY';
+/**
+ * Gate Mode
+ *
+ * SHADOW: Evaluate and log, but always allow (monitor-only)
+ * ENFORCE: Evaluate and enforce decisions (block if policy violation)
+ */
+type GateMode = 'SHADOW' | 'ENFORCE';
+/**
+ * Connection Failure Strategy
+ *
+ * FAIL_OPEN: Allow transaction if hotpath is unreachable
+ * FAIL_CLOSED: Block transaction if hotpath is unreachable (security-first)
+ */
+type ConnectionFailureStrategy = 'FAIL_OPEN' | 'FAIL_CLOSED';
 /**
  * Circuit breaker configuration
  */
@@ -191,6 +228,20 @@ interface GateClientConfig {
     clockSkewMs?: number;
     retries?: number;
     failSafeMode?: FailSafeMode;
+    /**
+     * Gate mode (default: SHADOW for safety)
+     *
+     * SHADOW: Monitor-only - evaluate and log, but always allow
+     * ENFORCE: Enforce decisions - block if policy violation
+     */
+    mode?: GateMode;
+    /**
+     * Connection failure strategy (default: based on mode)
+     *
+     * FAIL_OPEN: Allow on connection failure (default in SHADOW mode)
+     * FAIL_CLOSED: Block on connection failure (default in ENFORCE mode)
+     */
+    onConnectionFailure?: ConnectionFailureStrategy;
     circuitBreaker?: CircuitBreakerConfig$1;
     enableStepUp?: boolean;
     stepUp?: {
@@ -199,6 +250,20 @@ interface GateClientConfig {
         treatRequireStepUpAsBlockWhenDisabled?: boolean;
     };
     onMetrics?: (metrics: Metrics) => void | Promise<void>;
+    signerId?: string;
+    heartbeatRefreshIntervalSeconds?: number;
+    /**
+     * Break-glass token (optional, for emergency override)
+     *
+     * JWT token issued by Control Plane for time-bound policy bypass.
+     * Only valid if explicitly activated via break-glass endpoint.
+     */
+    breakglassToken?: string;
+    /**
+     * Local development mode - disables auth, heartbeat, and break-glass
+     * Set to true when using gate-local emulator
+     */
+    local?: boolean;
 }
 
 /**
@@ -344,11 +409,16 @@ declare class GateClient {
     private readonly stepUpPoller?;
     private readonly circuitBreaker?;
     private readonly metrics;
+    private readonly heartbeatManager;
+    private readonly mode;
+    private readonly onConnectionFailure;
     constructor(config: GateClientConfig);
     /**
      * 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
@@ -428,7 +498,11 @@ declare enum GateErrorCode {
     STEP_UP_TIMEOUT = "STEP_UP_TIMEOUT",
     BLOCKED = "BLOCKED",
     SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
-    AUTH_ERROR = "AUTH_ERROR"
+    AUTH_ERROR = "AUTH_ERROR",
+    HEARTBEAT_MISSING = "HEARTBEAT_MISSING",
+    HEARTBEAT_EXPIRED = "HEARTBEAT_EXPIRED",
+    HEARTBEAT_INVALID = "HEARTBEAT_INVALID",
+    HEARTBEAT_MISMATCH = "HEARTBEAT_MISMATCH"
 }
 /**
  * Base Gate error class
@@ -534,4 +608,126 @@ declare class ProvenanceProvider {
     static isEnabled(): boolean;
 }
 
-export { BlockIntelAuthError, BlockIntelBlockedError, BlockIntelStepUpRequiredError, BlockIntelUnavailableError, type DefenseEvaluateRequestV2, type DefenseEvaluateResponseV2, GateClient, type GateClientConfig, type GateDecision, GateError, GateErrorCode, type GateStepUpStatus, type Provenance, ProvenanceProvider, type SigningContext, type StepUpFinalResult, type StepUpMetadata, StepUpNotConfiguredError, type StepUpStatusResponse, type TransactionIntentV2, type WrapKmsClientOptions, type WrappedKmsClient, createGateClient, GateClient as default, wrapKmsClient };
+/**
+ * BlockIntel Gate SDK - HTTP Client
+ *
+ * Fetch wrapper with timeout, retry, and error handling.
+ */
+interface HttpClientConfig {
+    baseUrl: string;
+    timeoutMs?: number;
+    userAgent?: string;
+    retryOptions?: {
+        maxAttempts?: number;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        factor?: number;
+    };
+}
+interface RequestOptions {
+    method: string;
+    path: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    requestId?: string;
+}
+/**
+ * HTTP client with retry and timeout support
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly userAgent;
+    private readonly retryOptions;
+    constructor(config: HttpClientConfig);
+    /**
+     * Make an HTTP request with retry and timeout
+     */
+    request<T>(options: RequestOptions): Promise<T>;
+    /**
+     * Map HTTP status code to GateErrorCode
+     */
+    private statusToErrorCode;
+}
+
+/**
+ * Gate SDK - Heartbeat Manager
+ *
+ * Manages heartbeat token acquisition and validation.
+ * Heartbeat tokens prove Gate is alive and enforcing policy.
+ * Required for all signing operations.
+ *
+ * Features:
+ * - Automatic refresh with jitter
+ * - Exponential backoff on failures
+ * - Client instance metadata tracking
+ */
+
+interface HeartbeatToken {
+    token: string;
+    expiresAt: number;
+    jti?: string;
+    policyHash?: string;
+}
+declare class HeartbeatManager {
+    private readonly httpClient;
+    private readonly tenantId;
+    private signerId;
+    private readonly environment;
+    private readonly baseRefreshIntervalSeconds;
+    private readonly clientInstanceId;
+    private readonly sdkVersion;
+    private currentToken;
+    private refreshTimer;
+    private started;
+    private consecutiveFailures;
+    private maxBackoffSeconds;
+    constructor(options: {
+        httpClient: HttpClient;
+        tenantId: string;
+        signerId: string;
+        environment?: string;
+        refreshIntervalSeconds?: number;
+        clientInstanceId?: string;
+        sdkVersion?: string;
+    });
+    /**
+     * Start background heartbeat refresher
+     */
+    start(): void;
+    /**
+     * Schedule next refresh with jitter and backoff
+     */
+    private scheduleNextRefresh;
+    /**
+     * Calculate exponential backoff (capped at maxBackoffSeconds)
+     */
+    private calculateBackoff;
+    /**
+     * Stop background heartbeat refresher
+     */
+    stop(): void;
+    /**
+     * Get current heartbeat token if valid
+     */
+    getToken(): string | null;
+    /**
+     * Check if current heartbeat token is valid
+     */
+    isValid(): boolean;
+    /**
+     * Update signer ID (called when signer is known)
+     */
+    updateSignerId(signerId: string): void;
+    /**
+     * Acquire a new heartbeat token from Control Plane
+     * NEVER logs token value (security)
+     */
+    private acquireHeartbeat;
+    /**
+     * Get client instance ID (for tracking)
+     */
+    getClientInstanceId(): string;
+}
+
+export { BlockIntelAuthError, BlockIntelBlockedError, BlockIntelStepUpRequiredError, BlockIntelUnavailableError, type DefenseEvaluateRequestV2, type DefenseEvaluateResponseV2, GateClient, type GateClientConfig, type GateDecision, GateError, GateErrorCode, type GateStepUpStatus, HeartbeatManager, type HeartbeatToken, type Provenance, ProvenanceProvider, type SigningContext, type StepUpFinalResult, type StepUpMetadata, StepUpNotConfiguredError, type StepUpStatusResponse, type TransactionIntentV2, type WrapKmsClientOptions, type WrappedKmsClient, createGateClient, GateClient as default, wrapKmsClient };

package/dist/index.d.ts

@@ -14,6 +14,8 @@ interface Metrics {
     timeoutsTotal: number;
     errorsTotal: number;
     circuitBreakerOpenTotal: number;
+    wouldBlockTotal: number;
+    failOpenTotal: number;
     latencyMs: number[];
 }
 type MetricsHook = (metrics: Metrics) => void | Promise<void>;
@@ -28,13 +30,15 @@ declare class MetricsCollector {
     private timeoutsTotal;
     private errorsTotal;
     private circuitBreakerOpenTotal;
+    private wouldBlockTotal;
+    private failOpenTotal;
     private latencyMs;
     private readonly maxSamples;
     private readonly hooks;
     /**
      * Record a request
      */
-    recordRequest(decision: 'ALLOW' | 'BLOCK' | 'REQUIRE_STEP_UP', latencyMs: number): void;
+    recordRequest(decision: 'ALLOW' | 'BLOCK' | 'REQUIRE_STEP_UP' | 'WOULD_BLOCK' | 'FAIL_OPEN', latencyMs: number): void;
     /**
      * Record a timeout
      */
@@ -111,6 +115,13 @@ interface DefenseEvaluateRequestV2 {
     signingContext?: SigningContext;
     requestId?: string;
     timestampMs?: number;
+    /**
+     * Enable transaction simulation (optional, defaults to false)
+     *
+     * When true, Hot Path will simulate the transaction after static policy evaluation.
+     * Adds 300-800ms latency but provides additional security checks.
+     */
+    simulate?: boolean;
 }
 /**
  * Gate decision types
@@ -132,6 +143,18 @@ interface DefenseEvaluateResponseV2 {
     policyVersion?: string;
     correlationId?: string;
     stepUp?: StepUpMetadata;
+    /**
+     * Whether the decision was enforced (false in SHADOW mode)
+     */
+    enforced?: boolean;
+    /**
+     * Whether shadow mode would have blocked (true if mode=SHADOW and decision=BLOCK)
+     */
+    shadowWouldBlock?: boolean;
+    /**
+     * Gate mode used for this evaluation
+     */
+    mode?: GateMode;
 }
 /**
  * Step-up status types
@@ -162,9 +185,23 @@ interface StepUpFinalResult {
     correlationId?: string;
 }
 /**
- * Fail-safe mode for SDK
+ * Fail-safe mode for SDK (deprecated - use onConnectionFailure instead)
  */
 type FailSafeMode = 'ALLOW_ON_TIMEOUT' | 'BLOCK_ON_TIMEOUT' | 'BLOCK_ON_ANOMALY';
+/**
+ * Gate Mode
+ *
+ * SHADOW: Evaluate and log, but always allow (monitor-only)
+ * ENFORCE: Evaluate and enforce decisions (block if policy violation)
+ */
+type GateMode = 'SHADOW' | 'ENFORCE';
+/**
+ * Connection Failure Strategy
+ *
+ * FAIL_OPEN: Allow transaction if hotpath is unreachable
+ * FAIL_CLOSED: Block transaction if hotpath is unreachable (security-first)
+ */
+type ConnectionFailureStrategy = 'FAIL_OPEN' | 'FAIL_CLOSED';
 /**
  * Circuit breaker configuration
  */
@@ -191,6 +228,20 @@ interface GateClientConfig {
     clockSkewMs?: number;
     retries?: number;
     failSafeMode?: FailSafeMode;
+    /**
+     * Gate mode (default: SHADOW for safety)
+     *
+     * SHADOW: Monitor-only - evaluate and log, but always allow
+     * ENFORCE: Enforce decisions - block if policy violation
+     */
+    mode?: GateMode;
+    /**
+     * Connection failure strategy (default: based on mode)
+     *
+     * FAIL_OPEN: Allow on connection failure (default in SHADOW mode)
+     * FAIL_CLOSED: Block on connection failure (default in ENFORCE mode)
+     */
+    onConnectionFailure?: ConnectionFailureStrategy;
     circuitBreaker?: CircuitBreakerConfig$1;
     enableStepUp?: boolean;
     stepUp?: {
@@ -199,6 +250,20 @@ interface GateClientConfig {
         treatRequireStepUpAsBlockWhenDisabled?: boolean;
     };
     onMetrics?: (metrics: Metrics) => void | Promise<void>;
+    signerId?: string;
+    heartbeatRefreshIntervalSeconds?: number;
+    /**
+     * Break-glass token (optional, for emergency override)
+     *
+     * JWT token issued by Control Plane for time-bound policy bypass.
+     * Only valid if explicitly activated via break-glass endpoint.
+     */
+    breakglassToken?: string;
+    /**
+     * Local development mode - disables auth, heartbeat, and break-glass
+     * Set to true when using gate-local emulator
+     */
+    local?: boolean;
 }
 
 /**
@@ -344,11 +409,16 @@ declare class GateClient {
     private readonly stepUpPoller?;
     private readonly circuitBreaker?;
     private readonly metrics;
+    private readonly heartbeatManager;
+    private readonly mode;
+    private readonly onConnectionFailure;
     constructor(config: GateClientConfig);
     /**
      * 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
@@ -428,7 +498,11 @@ declare enum GateErrorCode {
     STEP_UP_TIMEOUT = "STEP_UP_TIMEOUT",
     BLOCKED = "BLOCKED",
     SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
-    AUTH_ERROR = "AUTH_ERROR"
+    AUTH_ERROR = "AUTH_ERROR",
+    HEARTBEAT_MISSING = "HEARTBEAT_MISSING",
+    HEARTBEAT_EXPIRED = "HEARTBEAT_EXPIRED",
+    HEARTBEAT_INVALID = "HEARTBEAT_INVALID",
+    HEARTBEAT_MISMATCH = "HEARTBEAT_MISMATCH"
 }
 /**
  * Base Gate error class
@@ -534,4 +608,126 @@ declare class ProvenanceProvider {
     static isEnabled(): boolean;
 }
 
-export { BlockIntelAuthError, BlockIntelBlockedError, BlockIntelStepUpRequiredError, BlockIntelUnavailableError, type DefenseEvaluateRequestV2, type DefenseEvaluateResponseV2, GateClient, type GateClientConfig, type GateDecision, GateError, GateErrorCode, type GateStepUpStatus, type Provenance, ProvenanceProvider, type SigningContext, type StepUpFinalResult, type StepUpMetadata, StepUpNotConfiguredError, type StepUpStatusResponse, type TransactionIntentV2, type WrapKmsClientOptions, type WrappedKmsClient, createGateClient, GateClient as default, wrapKmsClient };
+/**
+ * BlockIntel Gate SDK - HTTP Client
+ *
+ * Fetch wrapper with timeout, retry, and error handling.
+ */
+interface HttpClientConfig {
+    baseUrl: string;
+    timeoutMs?: number;
+    userAgent?: string;
+    retryOptions?: {
+        maxAttempts?: number;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        factor?: number;
+    };
+}
+interface RequestOptions {
+    method: string;
+    path: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    requestId?: string;
+}
+/**
+ * HTTP client with retry and timeout support
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly userAgent;
+    private readonly retryOptions;
+    constructor(config: HttpClientConfig);
+    /**
+     * Make an HTTP request with retry and timeout
+     */
+    request<T>(options: RequestOptions): Promise<T>;
+    /**
+     * Map HTTP status code to GateErrorCode
+     */
+    private statusToErrorCode;
+}
+
+/**
+ * Gate SDK - Heartbeat Manager
+ *
+ * Manages heartbeat token acquisition and validation.
+ * Heartbeat tokens prove Gate is alive and enforcing policy.
+ * Required for all signing operations.
+ *
+ * Features:
+ * - Automatic refresh with jitter
+ * - Exponential backoff on failures
+ * - Client instance metadata tracking
+ */
+
+interface HeartbeatToken {
+    token: string;
+    expiresAt: number;
+    jti?: string;
+    policyHash?: string;
+}
+declare class HeartbeatManager {
+    private readonly httpClient;
+    private readonly tenantId;
+    private signerId;
+    private readonly environment;
+    private readonly baseRefreshIntervalSeconds;
+    private readonly clientInstanceId;
+    private readonly sdkVersion;
+    private currentToken;
+    private refreshTimer;
+    private started;
+    private consecutiveFailures;
+    private maxBackoffSeconds;
+    constructor(options: {
+        httpClient: HttpClient;
+        tenantId: string;
+        signerId: string;
+        environment?: string;
+        refreshIntervalSeconds?: number;
+        clientInstanceId?: string;
+        sdkVersion?: string;
+    });
+    /**
+     * Start background heartbeat refresher
+     */
+    start(): void;
+    /**
+     * Schedule next refresh with jitter and backoff
+     */
+    private scheduleNextRefresh;
+    /**
+     * Calculate exponential backoff (capped at maxBackoffSeconds)
+     */
+    private calculateBackoff;
+    /**
+     * Stop background heartbeat refresher
+     */
+    stop(): void;
+    /**
+     * Get current heartbeat token if valid
+     */
+    getToken(): string | null;
+    /**
+     * Check if current heartbeat token is valid
+     */
+    isValid(): boolean;
+    /**
+     * Update signer ID (called when signer is known)
+     */
+    updateSignerId(signerId: string): void;
+    /**
+     * Acquire a new heartbeat token from Control Plane
+     * NEVER logs token value (security)
+     */
+    private acquireHeartbeat;
+    /**
+     * Get client instance ID (for tracking)
+     */
+    getClientInstanceId(): string;
+}
+
+export { BlockIntelAuthError, BlockIntelBlockedError, BlockIntelStepUpRequiredError, BlockIntelUnavailableError, type DefenseEvaluateRequestV2, type DefenseEvaluateResponseV2, GateClient, type GateClientConfig, type GateDecision, GateError, GateErrorCode, type GateStepUpStatus, HeartbeatManager, type HeartbeatToken, type Provenance, ProvenanceProvider, type SigningContext, type StepUpFinalResult, type StepUpMetadata, StepUpNotConfiguredError, type StepUpStatusResponse, type TransactionIntentV2, type WrapKmsClientOptions, type WrappedKmsClient, createGateClient, GateClient as default, wrapKmsClient };