blockintel-gate-sdk 0.3.6 → 0.3.7

package/README.md

@@ -13,6 +13,12 @@ npm install @blockintel/gate-sdk
 - Node.js >= 18.0.0 (uses global `fetch` API)
 - TypeScript >= 5.0.0 (optional, for type definitions)
 
+### 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.
+- **signingContext**: Hot Path requires `actorPrincipal` and `signerId`. The SDK defaults them when missing (`gate-sdk-client` or from `signingContext.signerId`).
+- **ESM**: HMAC and SHA-256 use `node:crypto` (no `require('crypto')`), so the SDK works in ESM (`"type": "module"`) and in bundled canary apps.
+
 ## Quick Start
 
 ### HMAC Authentication
@@ -203,6 +209,9 @@ When step-up is disabled, the SDK treats `REQUIRE_STEP_UP` as `BLOCK` by default
 GATE_BASE_URL=https://gate.blockintelai.com
 GATE_TENANT_ID=your-tenant-id
 
+# Heartbeat (required when not using local mode; parity with Python GATE_HEARTBEAT_KEY)
+GATE_HEARTBEAT_KEY=your-heartbeat-key
+
 # HMAC Authentication
 GATE_KEY_ID=your-key-id
 GATE_HMAC_SECRET=your-secret
@@ -376,6 +385,21 @@ The SDK automatically retries failed requests:
 - Same `requestId` is used across all retries
 - Ensures idempotency on Gate server
 
+## Degraded Mode / X-BlockIntel-Degraded
+
+When the SDK is in a degraded situation, it logs `X-BlockIntel-Degraded: true` with a `reason` for **logs and telemetry only**. This is **never sent as an HTTP request header** to the Gate server.
+
+**Reasons:** `retry`, `429`, `fail_open`, `fail_safe_allow`.
+
+**Example (one line):**  
+`[GATE SDK] X-BlockIntel-Degraded: true (reason=retry) attempt=1/3 status=503 err=RATE_LIMITED`
+
+**How to observe:**
+- **Logs:** `[GATE SDK] X-BlockIntel-Degraded: true (reason: <reason>)` via `console.warn`. Pipe stderr to your log aggregator.
+- **Metrics:** Use `onMetrics`; metrics include `timeouts`, `errors`, `failOpen`, etc. Correlate with log lines if you ship both.
+
+**Manual check (retry):** Point the SDK at an endpoint that returns 5xx; confirm one degraded log per retry attempt including `attempt`, `max`, and `status`/`err`.
+
 ## 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.

package/dist/index.cjs

@@ -2,18 +2,12 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+var crypto = require('crypto');
 var uuid = require('uuid');
 var clientKms = require('@aws-sdk/client-kms');
-var crypto$1 = require('crypto');
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
@@ -50,56 +44,24 @@ function canonicalizeJson(obj) {
   return JSON.stringify(sorted);
 }
 async function sha256Hex(input) {
-  if (typeof crypto !== "undefined" && crypto.subtle) {
-    const encoder = new TextEncoder();
-    const data = encoder.encode(input);
-    const hashBuffer = await crypto.subtle.digest("SHA-256", data);
-    const hashArray = Array.from(new Uint8Array(hashBuffer));
-    return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
-  }
-  if (typeof __require !== "undefined") {
-    const crypto2 = __require("crypto");
-    return crypto2.createHash("sha256").update(input, "utf8").digest("hex");
-  }
-  throw new Error("SHA-256 not available in this environment");
+  return crypto.createHash("sha256").update(input, "utf8").digest("hex");
 }
 var init_canonicalJson = __esm({
   "src/utils/canonicalJson.ts"() {
   }
 });
-
-// src/utils/crypto.ts
 async function hmacSha256(secret, message) {
-  if (typeof __require !== "undefined") {
-    const crypto2 = __require("crypto");
-    const hmac = crypto2.createHmac("sha256", secret);
-    hmac.update(message, "utf8");
-    const signatureHex = hmac.digest("hex");
-    console.error("[HMAC CRYPTO DEBUG] Signature computation:", JSON.stringify({
-      secretLength: secret.length,
-      messageLength: message.length,
-      messagePreview: message.substring(0, 200) + "...",
-      signatureLength: signatureHex.length,
-      signaturePreview: signatureHex.substring(0, 16) + "..."
-    }, null, 2));
-    return signatureHex;
-  }
-  if (typeof crypto !== "undefined" && crypto.subtle) {
-    const encoder = new TextEncoder();
-    const keyData = encoder.encode(secret);
-    const messageData = encoder.encode(message);
-    const key = await crypto.subtle.importKey(
-      "raw",
-      keyData,
-      { name: "HMAC", hash: "SHA-256" },
-      false,
-      ["sign"]
-    );
-    const signature = await crypto.subtle.sign("HMAC", key, messageData);
-    const hashArray = Array.from(new Uint8Array(signature));
-    return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
-  }
-  throw new Error("HMAC-SHA256 not available in this environment");
+  const hmac = crypto.createHmac("sha256", secret);
+  hmac.update(message, "utf8");
+  const signatureHex = hmac.digest("hex");
+  console.error("[HMAC CRYPTO DEBUG] Signature computation:", JSON.stringify({
+    secretLength: secret.length,
+    messageLength: message.length,
+    messagePreview: message.substring(0, 200) + "...",
+    signatureLength: signatureHex.length,
+    signaturePreview: signatureHex.substring(0, 16) + "..."
+  }, null, 2));
+  return signatureHex;
 }
 
 // src/auth/HmacSigner.ts
@@ -132,26 +94,7 @@ var HmacSigner = class {
       // Used as nonce in canonical string
       bodyHash
     ].join("\n");
-    console.error("[HMAC SIGNER DEBUG] Canonical request string:", JSON.stringify({
-      method: method.toUpperCase(),
-      path,
-      tenantId,
-      keyId: this.keyId,
-      timestampMs: String(timestampMs),
-      requestId,
-      bodyHash,
-      signingStringLength: signingString.length,
-      signingStringPreview: signingString.substring(0, 200) + "...",
-      bodyJsonLength: bodyJson.length,
-      bodyJsonPreview: bodyJson.substring(0, 200) + "..."
-    }, null, 2));
     const signature = await hmacSha256(this.secret, signingString);
-    console.error("[HMAC SIGNER DEBUG] Signature computed:", JSON.stringify({
-      signatureLength: signature.length,
-      signaturePreview: signature.substring(0, 16) + "...",
-      secretLength: this.secret.length,
-      secretPreview: this.secret.substring(0, 4) + "..." + this.secret.substring(this.secret.length - 4)
-    }, null, 2));
     return {
       "X-GATE-TENANT-ID": tenantId,
       "X-GATE-KEY-ID": this.keyId,
@@ -350,6 +293,10 @@ async function retryWithBackoff(fn, options = {}) {
       if (!isRetryable) {
         throw error;
       }
+      const status = error instanceof Response && error.status || error && typeof error === "object" && "status" in error && error.status || error && typeof error === "object" && "statusCode" in error && error.statusCode;
+      const errName = error instanceof Error ? error.name : error && typeof error === "object" && "code" in error ? error.code : "Unknown";
+      const extra = ` attempt=${attempt}/${opts.maxAttempts} status=${status ?? "n/a"} err=${errName}`;
+      console.warn("[GATE SDK] X-BlockIntel-Degraded: true (reason=retry)" + extra);
       const delay = calculateBackoffDelay(attempt, opts);
       await new Promise((resolve) => setTimeout(resolve, delay));
     }
@@ -357,17 +304,73 @@ async function retryWithBackoff(fn, options = {}) {
   throw lastError;
 }
 
+// src/utils/sanitize.ts
+var SENSITIVE_HEADER_NAMES = /* @__PURE__ */ new Set([
+  "authorization",
+  "x-api-key",
+  "x-gate-heartbeat-key",
+  "x-gate-signature",
+  "cookie"
+]);
+var MAX_STRING_LENGTH = 80;
+function sanitizeHeaders(headers) {
+  const out = {};
+  for (const [key, value] of Object.entries(headers)) {
+    const lower = key.toLowerCase();
+    if (SENSITIVE_HEADER_NAMES.has(lower) || lower.includes("signature") || lower.includes("secret") || lower.includes("token")) {
+      out[key] = value ? "[REDACTED]" : "[empty]";
+    } else {
+      out[key] = truncate(String(value), MAX_STRING_LENGTH);
+    }
+  }
+  return out;
+}
+function sanitizeBodyShape(body) {
+  if (body === null || body === void 0) {
+    return {};
+  }
+  if (typeof body !== "object") {
+    return { _: typeof body };
+  }
+  if (Array.isArray(body)) {
+    return { _: "array", length: String(body.length) };
+  }
+  const out = {};
+  for (const key of Object.keys(body).sort()) {
+    const val = body[key];
+    if (val !== null && typeof val === "object" && !Array.isArray(val)) {
+      out[key] = "object";
+    } else if (Array.isArray(val)) {
+      out[key] = "array";
+    } else {
+      out[key] = typeof val;
+    }
+  }
+  return out;
+}
+function truncate(s, max) {
+  if (s.length <= max) return s;
+  return s.slice(0, max) + "...";
+}
+function isDebugEnabled(debugOption) {
+  if (debugOption === true) return true;
+  if (typeof process !== "undefined" && process.env.GATE_SDK_DEBUG === "1") return true;
+  return false;
+}
+
 // src/http/HttpClient.ts
 var HttpClient = class {
   baseUrl;
   timeoutMs;
   userAgent;
   retryOptions;
+  debug;
   constructor(config) {
     this.baseUrl = config.baseUrl.replace(/\/$/, "");
     this.timeoutMs = config.timeoutMs ?? 15e3;
     this.userAgent = config.userAgent ?? "blockintel-gate-sdk/0.1.0";
     this.retryOptions = config.retryOptions;
+    this.debug = isDebugEnabled(config.debug);
     if (!this.baseUrl) {
       throw new Error("baseUrl is required");
     }
@@ -386,7 +389,6 @@ var HttpClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
     let requestDetailsForLogging = null;
-    let requestDetailsSet = false;
     try {
       const response = await retryWithBackoff(
         async () => {
@@ -409,31 +411,22 @@ var HttpClient = class {
               fetchOptions.body = JSON.stringify(body);
             }
           }
-          const logHeaders = {};
-          if (fetchOptions.headers) {
-            Object.entries(fetchOptions.headers).forEach(([key, value]) => {
-              if (key.toLowerCase().includes("signature") || key.toLowerCase().includes("secret")) {
-                logHeaders[key] = String(value).substring(0, 8) + "...";
-              } else {
-                logHeaders[key] = String(value);
-              }
-            });
-          }
           const bodyStr = typeof fetchOptions.body === "string" ? fetchOptions.body : null;
-          const details = {
-            headers: logHeaders,
-            bodyLength: bodyStr ? bodyStr.length : 0,
-            bodyPreview: bodyStr ? bodyStr.substring(0, 300) : null
+          requestDetailsForLogging = {
+            headers: this.debug ? sanitizeHeaders(requestHeaders) : {},
+            bodyLength: bodyStr ? bodyStr.length : 0
           };
-          requestDetailsForLogging = details;
-          requestDetailsSet = true;
-          console.error("[HTTP CLIENT DEBUG] Sending request:", JSON.stringify({
-            url,
-            method,
-            headers: logHeaders,
-            bodyLength: requestDetailsForLogging.bodyLength,
-            bodyPreview: requestDetailsForLogging.bodyPreview
-          }, null, 2));
+          if (this.debug) {
+            const bodyShape = body && typeof body === "object" ? sanitizeBodyShape(body) : {};
+            console.error("[GATE SDK] Request:", JSON.stringify({
+              url,
+              method,
+              headerNames: Object.keys(requestHeaders),
+              headersRedacted: requestDetailsForLogging.headers,
+              bodyLength: requestDetailsForLogging.bodyLength,
+              bodyKeysAndTypes: bodyShape
+            }, null, 2));
+          }
           const res = await fetch(url, fetchOptions);
           if (!res.ok && isRetryableStatus(res.status)) {
             throw res;
@@ -451,26 +444,24 @@ var HttpClient = class {
       clearTimeout(timeoutId);
       let data;
       const contentType = response.headers.get("content-type");
-      console.error("[HTTP CLIENT DEBUG] Response received:", JSON.stringify({
-        status: response.status,
-        ok: response.ok,
-        statusText: response.statusText,
-        contentType,
-        url: response.url
-      }, null, 2));
+      if (this.debug) {
+        console.error("[GATE SDK] Response:", JSON.stringify({
+          status: response.status,
+          ok: response.ok,
+          url: response.url
+        }, null, 2));
+      }
       if (contentType && contentType.includes("application/json")) {
         try {
           const jsonText = await response.text();
-          console.error("[HTTP CLIENT DEBUG] Response body (first 500 chars):", jsonText.substring(0, 500));
           data = JSON.parse(jsonText);
-          console.error("[HTTP CLIENT DEBUG] Parsed JSON:", JSON.stringify({
-            hasSuccess: typeof data?.success !== "undefined",
-            success: data?.success,
-            hasData: typeof data?.data !== "undefined",
-            hasError: typeof data?.error !== "undefined"
-          }, null, 2));
+          if (this.debug && data && typeof data === "object") {
+            console.error("[GATE SDK] Response keys:", Object.keys(data));
+          }
         } catch (parseError) {
-          console.error("[HTTP CLIENT DEBUG] JSON parse error:", parseError);
+          if (this.debug) {
+            console.error("[GATE SDK] JSON parse error:", parseError instanceof Error ? parseError.message : String(parseError));
+          }
           throw new GateError(
             "INVALID_RESPONSE" /* INVALID_RESPONSE */,
             "Failed to parse JSON response",
@@ -498,26 +489,12 @@ var HttpClient = class {
         response.headers.forEach((value, key) => {
           responseHeaders[key] = value;
         });
-        if (response.status === 401) {
-          console.error("[HTTP CLIENT DEBUG] 401 UNAUTHORIZED - Full request details:", JSON.stringify({
+        if (this.debug) {
+          console.error("[GATE SDK] Error response:", JSON.stringify({
             status: response.status,
-            statusText: response.statusText,
             url: response.url,
-            requestMethod: method,
             requestPath: path,
-            requestHeaders: requestDetailsForLogging ? requestDetailsForLogging.headers : {},
-            responseHeaders,
-            responseData: data,
-            bodyLength: requestDetailsForLogging ? requestDetailsForLogging.bodyLength : 0,
-            bodyPreview: requestDetailsForLogging ? requestDetailsForLogging.bodyPreview : null
-          }, null, 2));
-        } else {
-          console.error("[HTTP CLIENT DEBUG] Response not OK:", JSON.stringify({
-            status: response.status,
-            statusText: response.statusText,
-            url: response.url,
-            headers: responseHeaders,
-            data
+            responseKeys: data && typeof data === "object" ? Object.keys(data) : []
           }, null, 2));
         }
         const errorCode = this.statusToErrorCode(response.status);
@@ -529,7 +506,6 @@ var HttpClient = class {
           details: data
         });
       }
-      console.error("[HTTP CLIENT DEBUG] Response OK, returning data");
       return data;
     } catch (error) {
       clearTimeout(timeoutId);
@@ -982,7 +958,7 @@ function defaultExtractTxIntent(command) {
     throw new Error("SignCommand missing required Message property");
   }
   const messageBuffer = message instanceof Buffer ? message : Buffer.from(message);
-  const messageHash = crypto$1.createHash("sha256").update(messageBuffer).digest("hex");
+  const messageHash = crypto.createHash("sha256").update(messageBuffer).digest("hex");
   return {
     networkFamily: "OTHER",
     toAddress: void 0,
@@ -1088,6 +1064,8 @@ var HeartbeatManager = class {
   // Unique per process
   sdkVersion;
   // SDK version for tracking
+  apiKey;
+  // x-gate-heartbeat-key for Control Plane auth
   currentToken = null;
   refreshTimer = null;
   started = false;
@@ -1100,19 +1078,22 @@ var HeartbeatManager = class {
     this.signerId = options.signerId;
     this.environment = options.environment ?? "prod";
     this.baseRefreshIntervalSeconds = options.refreshIntervalSeconds ?? 10;
+    this.apiKey = options.apiKey;
     this.clientInstanceId = options.clientInstanceId || uuid.v4();
     this.sdkVersion = options.sdkVersion || "1.0.0";
+    this.apiKey = options.apiKey;
   }
   /**
-   * Start background heartbeat refresher
+   * Start background heartbeat refresher.
+   * Optionally wait for initial token (first evaluate() will otherwise wait up to 2s for token).
    */
-  start() {
+  start(options) {
     if (this.started) {
       return;
     }
     this.started = true;
     this.acquireHeartbeat().catch((error) => {
-      console.error("[HEARTBEAT] Failed to acquire initial heartbeat:", error);
+      console.error("[HEARTBEAT] Failed to acquire initial heartbeat:", error instanceof Error ? error.message : error);
     });
     this.scheduleNextRefresh();
   }
@@ -1195,12 +1176,23 @@ var HeartbeatManager = class {
   /**
    * Acquire a new heartbeat token from Control Plane
    * NEVER logs token value (security)
+   * Requires x-gate-heartbeat-key header (apiKey) for authentication.
    */
   async acquireHeartbeat() {
+    if (!this.apiKey || this.apiKey.length === 0) {
+      throw new GateError(
+        "UNAUTHORIZED" /* UNAUTHORIZED */,
+        "Heartbeat API key is required. Set GATE_HEARTBEAT_KEY in environment or pass heartbeatApiKey in GateClientConfig.",
+        {}
+      );
+    }
     try {
       const response = await this.httpClient.request({
         method: "POST",
         path: "/api/v1/gate/heartbeat",
+        headers: {
+          "x-gate-heartbeat-key": this.apiKey
+        },
         body: {
           tenantId: this.tenantId,
           signerId: this.signerId,
@@ -1528,7 +1520,8 @@ var GateClient = class {
     this.httpClient = new HttpClient({
       baseUrl: config.baseUrl,
       timeoutMs: config.timeoutMs,
-      userAgent: config.userAgent
+      userAgent: config.userAgent,
+      debug: config.debug
     });
     if (config.enableStepUp) {
       this.stepUpPoller = new StepUpPoller({
@@ -1549,6 +1542,12 @@ var GateClient = class {
       console.warn("[GATE CLIENT] LOCAL MODE ENABLED - Auth, heartbeat, and break-glass are disabled");
       this.heartbeatManager = null;
     } else {
+      const heartbeatApiKey = config.heartbeatApiKey ?? (typeof process !== "undefined" ? process.env.GATE_HEARTBEAT_KEY : void 0);
+      if (!heartbeatApiKey || heartbeatApiKey.length === 0) {
+        throw new Error(
+          "GATE_HEARTBEAT_KEY environment variable or heartbeatApiKey in config is required for heartbeat authentication. Set GATE_HEARTBEAT_KEY in your environment or pass heartbeatApiKey in GateClientConfig."
+        );
+      }
       let controlPlaneUrl = config.baseUrl;
       if (controlPlaneUrl.includes("/defense")) {
         controlPlaneUrl = controlPlaneUrl.split("/defense")[0];
@@ -1568,7 +1567,8 @@ var GateClient = class {
         tenantId: config.tenantId,
         signerId: initialSignerId,
         environment: config.environment ?? "prod",
-        refreshIntervalSeconds: config.heartbeatRefreshIntervalSeconds ?? 10
+        refreshIntervalSeconds: config.heartbeatRefreshIntervalSeconds ?? 10,
+        apiKey: heartbeatApiKey
       });
       this.heartbeatManager.start();
     }
@@ -1657,7 +1657,9 @@ var GateClient = class {
         delete txIntent.from;
       }
       const signingContext = {
-        ...req.signingContext
+        ...req.signingContext,
+        actorPrincipal: req.signingContext?.actorPrincipal ?? req.signingContext?.signerId ?? "gate-sdk-client",
+        signerId: req.signingContext?.signerId ?? req.signingContext?.actorPrincipal ?? "gate-sdk-client"
       };
       if (heartbeatToken) {
         signingContext.heartbeatToken = heartbeatToken;
@@ -1673,17 +1675,16 @@ var GateClient = class {
         };
       }
       let body = {
+        tenantId: this.config.tenantId,
         requestId,
         timestampMs,
         txIntent,
         signingContext,
         // Add SDK info (required by Hot Path validation)
-        // Note: Must match Python SDK name for consistent canonical JSON
         sdk: {
           name: "gate-sdk",
           version: "0.1.0"
         },
-        // Add mode and connection failure strategy
         mode: requestMode,
         onConnectionFailure: this.onConnectionFailure
       };
@@ -1713,15 +1714,6 @@ var GateClient = class {
         });
         headers = { ...hmacHeaders };
         body.__canonicalJson = canonicalBodyJson;
-        const debugHeaders = {};
-        Object.entries(headers).forEach(([key, value]) => {
-          if (key.toLowerCase().includes("signature")) {
-            debugHeaders[key] = value.substring(0, 8) + "...";
-          } else {
-            debugHeaders[key] = value;
-          }
-        });
-        console.error("[GATE CLIENT DEBUG] HMAC headers prepared:", JSON.stringify(debugHeaders, null, 2));
       } else if (this.apiKeyAuth) {
         const apiKeyHeaders = this.apiKeyAuth.createHeaders({
           tenantId: this.config.tenantId,
@@ -1729,7 +1721,6 @@ var GateClient = class {
           requestId
         });
         headers = { ...apiKeyHeaders };
-        console.error("[GATE CLIENT DEBUG] API key headers prepared:", JSON.stringify(headers, null, 2));
       } else {
         throw new Error("No authentication configured");
       }
@@ -1863,6 +1854,7 @@ var GateClient = class {
             tenantId: this.config.tenantId,
             mode: requestMode
           });
+          console.warn("[GATE SDK] X-BlockIntel-Degraded: true (reason: fail_open)");
           this.metrics.recordRequest("FAIL_OPEN", Date.now() - startTime);
           return {
             decision: "ALLOW",
@@ -1894,6 +1886,10 @@ var GateClient = class {
         }
         throw error;
       }
+      if (error instanceof GateError && error.code === "RATE_LIMITED" /* RATE_LIMITED */) {
+        console.warn("[GATE SDK] X-BlockIntel-Degraded: true (reason: 429)");
+        throw error;
+      }
       if (error instanceof BlockIntelBlockedError || error instanceof BlockIntelStepUpRequiredError) {
         throw error;
       }
@@ -1906,6 +1902,7 @@ var GateClient = class {
    */
   handleFailSafe(mode, error, requestId) {
     if (mode === "ALLOW_ON_TIMEOUT") {
+      console.warn("[GATE SDK] X-BlockIntel-Degraded: true (reason: fail_safe_allow)");
       return {
         decision: "ALLOW",
         reasonCodes: ["FAIL_SAFE_ALLOW"],
@@ -1916,6 +1913,7 @@ var GateClient = class {
       return null;
     }
     if (mode === "BLOCK_ON_ANOMALY") {
+      console.warn("[GATE SDK] X-BlockIntel-Degraded: true (reason: fail_safe_allow)");
       return {
         decision: "ALLOW",
         reasonCodes: ["FAIL_SAFE_ALLOW"],