blockintel-gate-sdk 0.3.7 → 0.3.9

package/README.md

@@ -13,6 +13,8 @@ npm install @blockintel/gate-sdk
 - Node.js >= 18.0.0 (uses global `fetch` API)
 - TypeScript >= 5.0.0 (optional, for type definitions)
 
+**Optional – On-prem HSM (PKCS#11):** For `GenericHsmSigner` with a real HSM (Thales nShield, Utimaco, AWS CloudHSM, SoftHSM2, etc.), install the optional dependency: `npm install pkcs11js`. Without it, `Pkcs11SessionImpl` throws at runtime when used; you can still pass a custom `pkcs11Session` to `GenericHsmSigner` for testing or a different PKCS#11 stack.
+
 ### Hot Path compatibility
 
 - **Mode**: Default is `SHADOW` (Hot Path returns ALLOW with reason codes for would-block decisions). Set `mode: 'ENFORCE'` or `GATE_MODE=ENFORCE` for real BLOCK responses.

package/dist/contracts-KKk945Ox.d.cts

@@ -0,0 +1,380 @@
+/**
+ * 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;
+    wouldBlockTotal: number;
+    failOpenTotal: 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 wouldBlockTotal;
+    private failOpenTotal;
+    private latencyMs;
+    private readonly maxSamples;
+    private readonly hooks;
+    /**
+     * Record a request
+     */
+    recordRequest(decision: 'ALLOW' | 'BLOCK' | 'REQUIRE_STEP_UP' | 'WOULD_BLOCK' | 'FAIL_OPEN', latencyMs: number): void;
+    /**
+     * Record a timeout
+     */
+    recordTimeout(): void;
+    /**
+     * Record an error
+     */
+    recordError(): void;
+    /**
+     * Record circuit breaker open
+     */
+    recordCircuitBreakerOpen(): void;
+    /**
+     * Record soft-enforce override (app chose to sign despite BLOCK decision)
+     */
+    recordSoftBlockOverride(decision: 'ALLOW' | 'BLOCK'): 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;
+    /**
+     * 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
+ */
+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;
+    decisionId?: string;
+    stepUp?: StepUpMetadata;
+    /**
+     * Decision token (JWS HS256) binding decision to txDigest. Required in ENFORCE/HARD when requireDecisionToken.
+     */
+    decisionToken?: string;
+    /**
+     * Unix seconds when decision token expires.
+     */
+    expiresAt?: number;
+    /**
+     * SHA256(canonicalJson(txBinding)). Must match when signing.
+     */
+    txDigest?: string;
+    /**
+     * 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;
+    /**
+     * Metadata (evaluation latency, simulation, policy hash for pinning)
+     */
+    metadata?: {
+        evaluationLatencyMs?: number;
+        policyHash?: string;
+        snapshotVersion?: number;
+        [key: string]: unknown;
+    };
+    /** True when evaluationMode was FIRE_AND_FORGET (optimistic ALLOW, attestation in background) */
+    fireAndForget?: boolean;
+    /** Warning message (e.g. SOFT_ENFORCE override) */
+    warning?: string;
+}
+/**
+ * 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 (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)
+ * SOFT_ENFORCE: Evaluate and return BLOCK decisions but let app override (no throw)
+ * ENFORCE: Evaluate and enforce decisions (block if policy violation)
+ */
+type GateMode = 'SHADOW' | 'SOFT_ENFORCE' | 'ENFORCE';
+/**
+ * Evaluation mode (attestation pitch: "Gate attests in parallel")
+ *
+ * BLOCKING: await gate.evaluate() blocks until response (default)
+ * FIRE_AND_FORGET: evaluate() returns immediately with optimistic ALLOW; attestation in background
+ * PARALLEL: same as BLOCKING; caller can await the returned promise later after doing other work
+ */
+type EvaluationMode = 'BLOCKING' | 'FIRE_AND_FORGET' | 'PARALLEL';
+/**
+ * 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
+ */
+interface CircuitBreakerConfig {
+    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;
+    /**
+     * Gate mode (default: SHADOW for safety)
+     *
+     * SHADOW: Monitor-only - evaluate and log, but always allow
+     * ENFORCE: Enforce decisions - block if policy violation
+     */
+    mode?: GateMode;
+    /** Evaluation mode: BLOCKING (default), FIRE_AND_FORGET (return immediately, attest in background), PARALLEL */
+    evaluationMode?: EvaluationMode;
+    /**
+     * 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;
+    enableStepUp?: boolean;
+    stepUp?: {
+        pollingIntervalMs?: number;
+        maxWaitMs?: number;
+        treatRequireStepUpAsBlockWhenDisabled?: boolean;
+    };
+    onMetrics?: (metrics: Metrics) => void | Promise<void>;
+    signerId?: string;
+    heartbeatRefreshIntervalSeconds?: number;
+    /** API key for Control Plane heartbeat endpoint (x-gate-heartbeat-key). Required when not local. Fallback: GATE_HEARTBEAT_KEY env. */
+    heartbeatApiKey?: string;
+    /** When true or GATE_SDK_DEBUG=1, log sanitized request/response (no secrets, no body values). */
+    debug?: boolean;
+    /**
+     * 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;
+    /**
+     * Enforcement mode (default: SOFT)
+     *
+     * SOFT: Warns if IAM permission risk detected, but allows initialization
+     * HARD: Blocks initialization if IAM permission risk detected (unless override set)
+     */
+    enforcementMode?: 'SOFT' | 'HARD';
+    /**
+     * Allow initialization even if IAM permission risk detected
+     *
+     * Default: false in HARD mode, true in SOFT mode
+     *
+     * WARNING: Setting to true in HARD mode defeats the purpose of hard enforcement.
+     * Only use during migration periods.
+     */
+    allowInsecureKmsSignPermission?: boolean;
+    /**
+     * Optional: Specific KMS key IDs to check for permission risk
+     * If not provided, checks for any kms:Sign permission
+     */
+    kmsKeyIds?: string[];
+    /**
+     * Require decision token before sign (default: true when mode=ENFORCE or enforcementMode=HARD).
+     * When true, evaluate() must return decisionToken/txDigest for ALLOW; sign path verifies digest match.
+     * Override with GATE_REQUIRE_DECISION_TOKEN env.
+     */
+    requireDecisionToken?: boolean;
+    /**
+     * Optional policy pinning: if set, evaluate response must have matching policyHash (from metadata).
+     * Mismatch → treat as BLOCK locally (do not call signer). Defense against Control Plane compromise.
+     */
+    expectedPolicyHash?: string;
+    /**
+     * Optional snapshot version pinning: if set, evaluate response must have matching snapshotVersion (from metadata).
+     * Mismatch → treat as BLOCK locally.
+     */
+    expectedSnapshotVersion?: number;
+    /**
+     * Optional: public key (PEM) to verify RS256 decision tokens. When set, ALLOW responses with decisionToken
+     * are signature-verified; invalid or wrong-key tokens are treated as BLOCK.
+     */
+    decisionTokenPublicKey?: string;
+}
+/**
+ * Post-sign attestation request (zero-latency audit: attest after signing)
+ */
+interface AttestCompletedRequest {
+    txIntent: TransactionIntentV2;
+    signature: {
+        signature: string;
+        signerId: string;
+        keyId: string;
+        algorithm: string;
+    };
+    signingContext?: SigningContext;
+}
+/**
+ * Post-sign attestation response
+ */
+interface AttestCompletedResponse {
+    decision: 'ALLOW' | 'POLICY_VIOLATION_DETECTED';
+    decisionId: string;
+    correlationId: string;
+    reasonCodes: string[];
+    attestation: {
+        signatureHash: string;
+        attestedAt: number;
+        attestationToken?: string;
+    };
+}
+
+export { type AttestCompletedRequest as A, type DefenseEvaluateRequestV2 as D, type EvaluationMode as E, type GateClientConfig as G, MetricsCollector as M, type StepUpStatusResponse as S, type TransactionIntentV2 as T, type DefenseEvaluateResponseV2 as a, type StepUpFinalResult as b, type SigningContext as c, type AttestCompletedResponse as d, type GateDecision as e, type GateMode as f, type StepUpMetadata as g, type GateStepUpStatus as h };