blockintel-gate-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,492 @@
+import * as _aws_sdk_client_kms from '@aws-sdk/client-kms';
+import { SignCommandInput, KMSClient } from '@aws-sdk/client-kms';
+
+/**
+ * Metrics Collector for SDK
+ *
+ * Collects counters and latency metrics for observability.
+ */
+interface Metrics {
+    requestsTotal: number;
+    allowedTotal: number;
+    blockedTotal: number;
+    stepupTotal: number;
+    timeoutsTotal: number;
+    errorsTotal: number;
+    circuitBreakerOpenTotal: number;
+    latencyMs: number[];
+}
+type MetricsHook = (metrics: Metrics) => void | Promise<void>;
+/**
+ * Metrics Collector
+ */
+declare class MetricsCollector {
+    private requestsTotal;
+    private allowedTotal;
+    private blockedTotal;
+    private stepupTotal;
+    private timeoutsTotal;
+    private errorsTotal;
+    private circuitBreakerOpenTotal;
+    private latencyMs;
+    private readonly maxSamples;
+    private readonly hooks;
+    /**
+     * Record a request
+     */
+    recordRequest(decision: 'ALLOW' | 'BLOCK' | 'REQUIRE_STEP_UP', latencyMs: number): void;
+    /**
+     * Record a timeout
+     */
+    recordTimeout(): void;
+    /**
+     * Record an error
+     */
+    recordError(): void;
+    /**
+     * Record circuit breaker open
+     */
+    recordCircuitBreakerOpen(): void;
+    /**
+     * Get current metrics snapshot
+     */
+    getMetrics(): Metrics;
+    /**
+     * Register a metrics hook (e.g., for Prometheus/OpenTelemetry export)
+     */
+    registerHook(hook: MetricsHook): void;
+    /**
+     * Emit metrics to all registered hooks
+     */
+    private emitMetrics;
+    /**
+     * Reset all metrics
+     */
+    reset(): void;
+}
+
+/**
+ * BlockIntel Gate SDK - Type Contracts
+ *
+ * Type definitions for Gate Hot Path API v2 contracts.
+ * Internal SDK uses camelCase; mapping to/from API snake_case is handled internally.
+ */
+/**
+ * Transaction intent structure for evaluate request
+ */
+interface TransactionIntentV2 {
+    from: string;
+    to: string;
+    value?: string;
+    data?: string;
+    nonce?: number | string;
+    gasPrice?: string;
+    gasLimit?: string;
+    chainId?: number | string;
+    [key: string]: unknown;
+}
+/**
+ * Signing context metadata
+ */
+interface SigningContext {
+    signerId?: string;
+    source?: {
+        repo?: string;
+        workflow?: string;
+        environment?: string;
+        [key: string]: unknown;
+    };
+    wallet?: {
+        address: string;
+        type?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Defense evaluate request (v2)
+ */
+interface DefenseEvaluateRequestV2 {
+    txIntent: TransactionIntentV2;
+    signingContext?: SigningContext;
+    requestId?: string;
+    timestampMs?: number;
+}
+/**
+ * Gate decision types
+ */
+type GateDecision = 'ALLOW' | 'BLOCK' | 'REQUIRE_STEP_UP';
+/**
+ * Step-up metadata in evaluate response
+ */
+interface StepUpMetadata {
+    requestId: string;
+    ttlSeconds?: number;
+}
+/**
+ * Defense evaluate response (v2)
+ */
+interface DefenseEvaluateResponseV2 {
+    decision: GateDecision;
+    reasonCodes: string[];
+    policyVersion?: string;
+    correlationId?: string;
+    stepUp?: StepUpMetadata;
+}
+/**
+ * Step-up status types
+ */
+type GateStepUpStatus = 'PENDING' | 'APPROVED' | 'DENIED' | 'EXPIRED';
+/**
+ * Step-up status response
+ */
+interface StepUpStatusResponse {
+    status: GateStepUpStatus;
+    tenantId: string;
+    requestId: string;
+    decision?: string;
+    reasonCodes?: string[];
+    correlationId?: string;
+    expiresAtMs?: number;
+    ttl?: number;
+}
+/**
+ * Final result from awaitStepUpDecision
+ */
+interface StepUpFinalResult {
+    status: GateStepUpStatus;
+    requestId: string;
+    elapsedMs: number;
+    decision?: string;
+    reasonCodes?: string[];
+    correlationId?: string;
+}
+/**
+ * Fail-safe mode for SDK
+ */
+type FailSafeMode = 'ALLOW_ON_TIMEOUT' | 'BLOCK_ON_TIMEOUT' | 'BLOCK_ON_ANOMALY';
+/**
+ * Circuit breaker configuration
+ */
+interface CircuitBreakerConfig$1 {
+    tripAfterConsecutiveFailures?: number;
+    coolDownMs?: number;
+}
+/**
+ * SDK client configuration
+ */
+interface GateClientConfig {
+    baseUrl: string;
+    tenantId: string;
+    auth: {
+        mode: 'hmac';
+        keyId: string;
+        secret: string;
+    } | {
+        mode: 'apiKey';
+        apiKey: string;
+    };
+    timeoutMs?: number;
+    userAgent?: string;
+    clockSkewMs?: number;
+    retries?: number;
+    failSafeMode?: FailSafeMode;
+    circuitBreaker?: CircuitBreakerConfig$1;
+    enableStepUp?: boolean;
+    stepUp?: {
+        pollingIntervalMs?: number;
+        maxWaitMs?: number;
+        treatRequireStepUpAsBlockWhenDisabled?: boolean;
+    };
+    onMetrics?: (metrics: Metrics) => void | Promise<void>;
+}
+
+/**
+ * Circuit Breaker for SDK
+ *
+ * Prevents cascading failures by opening the circuit after consecutive failures.
+ */
+type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+interface CircuitBreakerConfig {
+    tripAfterConsecutiveFailures?: number;
+    coolDownMs?: number;
+}
+interface CircuitBreakerMetrics {
+    failures: number;
+    successes: number;
+    state: CircuitState;
+    lastFailureTime?: number;
+    lastSuccessTime?: number;
+    tripsToOpen: number;
+}
+/**
+ * Circuit Breaker implementation
+ */
+declare class CircuitBreaker {
+    private state;
+    private failures;
+    private successes;
+    private lastFailureTime?;
+    private lastSuccessTime?;
+    private tripsToOpen;
+    private readonly tripThreshold;
+    private readonly coolDownMs;
+    constructor(config?: CircuitBreakerConfig);
+    /**
+     * Execute function with circuit breaker protection
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    private onSuccess;
+    private onFailure;
+    /**
+     * Get current metrics
+     */
+    getMetrics(): CircuitBreakerMetrics;
+    /**
+     * Reset circuit breaker to CLOSED state
+     */
+    reset(): void;
+}
+
+/**
+ * BlockIntel Gate SDK - AWS SDK v3 KMS Wrapper
+ *
+ * Wraps AWS SDK v3 KMSClient to intercept SignCommand calls and enforce Gate policies.
+ */
+
+/**
+ * KMS wrapper options
+ */
+interface WrapKmsClientOptions {
+    /**
+     * Wrapper mode
+     * - "enforce": Block if Gate denies, require step-up approval
+     * - "dry-run": Evaluate but always allow KMS call (for testing)
+     */
+    mode?: 'enforce' | 'dry-run';
+    /**
+     * Callback invoked when a decision is made
+     */
+    onDecision?: (decision: 'ALLOW' | 'BLOCK' | 'REQUIRE_STEP_UP', details: any) => void;
+    /**
+     * Custom hook to extract transaction intent from SignCommand
+     * If not provided, uses default extraction (minimal txIntent from message hash)
+     */
+    extractTxIntent?: (command: SignCommandInput) => {
+        toAddress?: string;
+        networkFamily?: 'EVM' | 'BTC' | 'SOL' | 'OTHER';
+        chainId?: number;
+        [key: string]: any;
+    };
+}
+/**
+ * Wrapped KMS client type (proxy that intercepts send calls)
+ */
+interface WrappedKmsClient extends KMSClient {
+    /**
+     * Intercepted send method (overrides KMSClient.send)
+     */
+    send<T>(command: T): Promise<any>;
+    /**
+     * Original KMS client (for fallback or direct access)
+     */
+    _originalClient: KMSClient;
+    /**
+     * Gate client used for evaluation
+     */
+    _gateClient: GateClient;
+    /**
+     * Wrapper options
+     */
+    _wrapperOptions: Required<WrapKmsClientOptions>;
+}
+/**
+ * Wrap AWS SDK v3 KMS client to intercept SignCommand calls
+ *
+ * @param kmsClient - AWS SDK v3 KMSClient instance
+ * @param gateClient - Gate client for evaluation
+ * @param options - Wrapper options
+ * @returns Proxy object that intercepts send() calls
+ *
+ * @example
+ * ```typescript
+ * import { KMSClient } from '@aws-sdk/client-kms';
+ * import { GateClient, wrapKmsClient } from 'blockintel-gate-sdk';
+ *
+ * const kms = new KMSClient({});
+ * const gate = new GateClient({
+ *   baseUrl: process.env.GATE_BASE_URL!,
+ *   tenantId: process.env.GATE_TENANT_ID!,
+ *   auth: { mode: 'hmac', keyId: process.env.GATE_KEY_ID!, secret: process.env.GATE_HMAC_SECRET! },
+ * });
+ *
+ * const protectedKms = wrapKmsClient(kms, gate);
+ *
+ * // Now calls to protectedKms.send(new SignCommand(...)) will be intercepted
+ * const result = await protectedKms.send(new SignCommand({
+ *   KeyId: 'alias/my-key',
+ *   Message: Buffer.from('...'),
+ *   MessageType: 'RAW',
+ *   SigningAlgorithm: 'ECDSA_SHA_256',
+ * }));
+ * ```
+ */
+declare function wrapKmsClient(kmsClient: KMSClient, gateClient: GateClient, options?: WrapKmsClientOptions): WrappedKmsClient;
+
+/**
+ * Gate Client for Hot Path API
+ */
+declare class GateClient {
+    private readonly config;
+    private readonly httpClient;
+    private readonly hmacSigner?;
+    private readonly apiKeyAuth?;
+    private readonly stepUpPoller?;
+    private readonly circuitBreaker?;
+    private readonly metrics;
+    constructor(config: GateClientConfig);
+    /**
+     * Evaluate a transaction defense request
+     *
+     * Implements:
+     * - Circuit breaker protection
+     * - Fail-safe modes (ALLOW_ON_TIMEOUT, BLOCK_ON_TIMEOUT, BLOCK_ON_ANOMALY)
+     * - Metrics collection
+     * - Error handling (BLOCK → BlockIntelBlockedError, REQUIRE_STEP_UP → BlockIntelStepUpRequiredError)
+     */
+    evaluate(req: DefenseEvaluateRequestV2, opts?: {
+        requestId?: string;
+    }): Promise<DefenseEvaluateResponseV2>;
+    /**
+     * Handle fail-safe modes for timeouts/errors
+     */
+    private handleFailSafe;
+    /**
+     * Get current metrics
+     */
+    getMetrics(): ReturnType<MetricsCollector['getMetrics']>;
+    /**
+     * Get circuit breaker metrics (if enabled)
+     */
+    getCircuitBreakerMetrics(): ReturnType<CircuitBreaker['getMetrics']> | null;
+    /**
+     * Get step-up status
+     */
+    getStepUpStatus(args: {
+        requestId: string;
+        tenantId?: string;
+    }): Promise<StepUpStatusResponse>;
+    /**
+     * Wait for step-up decision with polling
+     */
+    awaitStepUpDecision(args: {
+        requestId: string;
+        maxWaitMs?: number;
+        intervalMs?: number;
+    }): Promise<StepUpFinalResult>;
+    /**
+     * Wrap AWS SDK v3 KMS client to intercept SignCommand calls
+     *
+     * @param kmsClient - AWS SDK v3 KMSClient instance
+     * @param options - Wrapper options
+     * @returns Wrapped KMS client that enforces Gate policies
+     *
+     * @example
+     * ```typescript
+     * import { KMSClient } from '@aws-sdk/client-kms';
+     *
+     * const kms = new KMSClient({});
+     * const protectedKms = gateClient.wrapKmsClient(kms);
+     *
+     * // Now SignCommand calls will be intercepted and evaluated by Gate
+     * const result = await protectedKms.send(new SignCommand({ ... }));
+     * ```
+     */
+    wrapKmsClient<T extends typeof _aws_sdk_client_kms.KMSClient>(kmsClient: InstanceType<T>, options?: WrapKmsClientOptions): WrappedKmsClient;
+}
+/**
+ * Create a Gate client instance
+ */
+declare function createGateClient(config: GateClientConfig): GateClient;
+
+/**
+ * BlockIntel Gate SDK - Error Types
+ */
+/**
+ * Gate error codes
+ */
+declare enum GateErrorCode {
+    NETWORK_ERROR = "NETWORK_ERROR",
+    TIMEOUT = "TIMEOUT",
+    NOT_FOUND = "NOT_FOUND",
+    UNAUTHORIZED = "UNAUTHORIZED",
+    FORBIDDEN = "FORBIDDEN",
+    RATE_LIMITED = "RATE_LIMITED",
+    SERVER_ERROR = "SERVER_ERROR",
+    INVALID_RESPONSE = "INVALID_RESPONSE",
+    STEP_UP_NOT_CONFIGURED = "STEP_UP_NOT_CONFIGURED",
+    STEP_UP_TIMEOUT = "STEP_UP_TIMEOUT",
+    BLOCKED = "BLOCKED",
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
+    AUTH_ERROR = "AUTH_ERROR"
+}
+/**
+ * Base Gate error class
+ */
+declare class GateError extends Error {
+    readonly code: GateErrorCode;
+    readonly status?: number;
+    readonly details?: Record<string, unknown>;
+    readonly requestId?: string;
+    readonly correlationId?: string;
+    constructor(code: GateErrorCode, message: string, options?: {
+        status?: number;
+        details?: Record<string, unknown>;
+        requestId?: string;
+        correlationId?: string;
+        cause?: Error;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Step-up not configured error
+ * Thrown when REQUIRE_STEP_UP is returned but SDK is not configured for step-up
+ */
+declare class StepUpNotConfiguredError extends GateError {
+    constructor(requestId?: string);
+}
+/**
+ * Blocked error
+ * Thrown when transaction is BLOCKED by Gate
+ */
+declare class BlockIntelBlockedError extends GateError {
+    readonly receiptId?: string;
+    readonly reasonCode: string;
+    constructor(reasonCode: string, receiptId?: string, correlationId?: string, requestId?: string);
+}
+/**
+ * Service unavailable error
+ * Thrown when fail-safe mode is BLOCK_ON_TIMEOUT and service is unavailable
+ */
+declare class BlockIntelUnavailableError extends GateError {
+    constructor(message: string, requestId?: string);
+}
+/**
+ * Auth error
+ * Thrown on 401/403 - always fails CLOSED (never silently allows)
+ */
+declare class BlockIntelAuthError extends GateError {
+    constructor(message: string, status: number, requestId?: string);
+}
+/**
+ * Step-up required error
+ * Thrown when REQUIRE_STEP_UP is returned and step-up is enabled
+ */
+declare class BlockIntelStepUpRequiredError extends GateError {
+    readonly stepUpRequestId: string;
+    readonly statusUrl?: string;
+    readonly expiresAtMs?: number;
+    constructor(stepUpRequestId: string, statusUrl?: string, expiresAtMs?: number, requestId?: string);
+}
+
+export { BlockIntelAuthError, BlockIntelBlockedError, BlockIntelStepUpRequiredError, BlockIntelUnavailableError, type DefenseEvaluateRequestV2, type DefenseEvaluateResponseV2, GateClient, type GateClientConfig, type GateDecision, GateError, GateErrorCode, type GateStepUpStatus, type SigningContext, type StepUpFinalResult, type StepUpMetadata, StepUpNotConfiguredError, type StepUpStatusResponse, type TransactionIntentV2, type WrapKmsClientOptions, type WrappedKmsClient, createGateClient, GateClient as default, wrapKmsClient };