blockintel-gate-sdk 0.4.6 → 0.4.8

package/README.md

@@ -2,6 +2,10 @@
 
 Production-grade TypeScript/Node.js SDK for [BlockIntel Gate](https://blockintelai.com) Hot Path API.
 
+Gate intercepts AWS KMS signing operations before cryptographic signatures are produced. Every transaction is evaluated against policy (denylist, velocity caps, value thresholds, signer allowlist) in <50ms. If policy says no, the key never signs.
+
+**SHADOW mode** — zero production risk. Gate evaluates every transaction and logs WOULD_BLOCK decisions, but never blocks. Drop it into your existing signing flow in minutes and collect 14 days of data before enforcing anything.
+
 ## Installation
 
 ```bash
@@ -21,9 +25,51 @@ npm install @blockintel/gate-sdk
 - **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
+## Quick Start — 3 Steps
 
-### HMAC Authentication
+```typescript
+// 1. Install
+// npm install @blockintel/gate-sdk
+
+// 2. Initialize (API key — simplest auth for getting started)
+import { GateClient } from '@blockintel/gate-sdk';
+
+const gate = new GateClient({
+  baseUrl: process.env.GATE_BASE_URL!,
+  tenantId: process.env.GATE_TENANT_ID!,
+  auth: { mode: 'apiKey', apiKey: process.env.GATE_API_KEY! },
+});
+
+// 3. Wrap your signing call
+const decision = await gate.evaluate({
+  txIntent: {
+    from: '0xYourAddress',
+    to: '0xDestination',
+    value: '1000000000000000000', // 1 ETH in wei
+    chainId: 1,
+  },
+});
+
+// In SHADOW mode: always ALLOW, but reasonCodes shows what WOULD_BLOCK
+console.log(decision.decision);    // "ALLOW"
+console.log(decision.reasonCodes); // ["DENYLIST"] if policy would have blocked
+```
+
+Get a free tenant at [blockintelai.com](https://blockintelai.com). For production use, switch to HMAC authentication — see the [Production Setup — HMAC Authentication](#production-setup--hmac-authentication) section below.
+
+## Why Gate
+
+**The problem:** Every `kms:Sign` call is unrestricted by default. Any process with valid IAM permissions can sign any transaction to any address for any amount. A compromised credential is a blank check.
+
+**What Gate adds:**
+- **Pre-signature policy evaluation** — denylist, value thresholds, velocity caps, signer allowlist
+- **Cryptographic receipts** — every decision signed with HMAC + RSA, verifiable by third parties
+- **SHADOW mode** — collect 14 days of data with zero production risk before enforcing
+- **Enforcement ladder** — SHADOW → SOFT_ENFORCE → HARD_KMS_GATEWAY (IAM-level, app loses kms:Sign)
+
+**Who uses it:** Crypto exchanges and custodians who need independently verifiable evidence of signing controls — for insurance carriers, compliance auditors (VARA, NYDFS), and internal governance.
+
+## Production Setup — HMAC Authentication
 
 ```typescript
 import { GateClient } from '@blockintel/gate-sdk';
@@ -180,6 +226,8 @@ console.log('Elapsed time:', result.elapsedMs, 'ms');
 
 ## Configuration
 
+> **SHADOW mode is the default.** `onConnectionFailure: 'FAIL_OPEN'` means Gate never blocks your signing operations — even if Gate itself is unreachable. You get full visibility into what would have been blocked without any production risk. Switch to `FAIL_CLOSED` only when you're ready to enforce.
+
 ### `GateClientConfig`
 
 ```typescript

package/dist/index.cjs

@@ -1217,7 +1217,7 @@ async function handleSignCommand(command, originalClient, gateClient, options) {
     if (options.mode === "dry-run") {
       return await originalClient.send(new clientKms.SignCommand(command));
     }
-    const GATEWAY_STAGES = ["HARD_KMS_GATEWAY", "HARD_GCP_GATEWAY", "HARD_HSM_GATEWAY"];
+    const GATEWAY_STAGES = ["HARD_KMS_GATEWAY", "HARD_GCP_GATEWAY"];
     const currentStage = gateClient.heartbeatManager?.getAdoptionStage?.();
     if (currentStage && GATEWAY_STAGES.includes(currentStage)) {
       emitMetric(options.metricsSink, "sign_success_total", labels);
@@ -3010,7 +3010,38 @@ var GcpKmsSigner = class {
       if (!this.config.credentials) {
         throw new Error("GCP credentials not configured");
       }
-      throw new Error("Service account authentication requires @google-cloud/kms SDK. Install it with: npm install @google-cloud/kms. Alternatively, use workload identity (recommended for GCP environments).");
+      const creds = typeof this.config.credentials === "string" ? JSON.parse(this.config.credentials) : this.config.credentials;
+      if (!creds.client_email || !creds.private_key) {
+        throw new Error("GCP credentials must contain client_email and private_key");
+      }
+      const crypto = await import('crypto');
+      const now = Math.floor(Date.now() / 1e3);
+      const header = Buffer.from(JSON.stringify({ alg: "RS256", typ: "JWT" })).toString("base64url");
+      const payload = Buffer.from(JSON.stringify({
+        iss: creds.client_email,
+        scope: "https://www.googleapis.com/auth/cloudkms",
+        aud: "https://oauth2.googleapis.com/token",
+        iat: now,
+        exp: now + 3600
+      })).toString("base64url");
+      const sigInput = `${header}.${payload}`;
+      const sign = crypto.createSign("RSA-SHA256");
+      sign.update(sigInput);
+      const sig = sign.sign(creds.private_key, "base64url");
+      const jwt = `${sigInput}.${sig}`;
+      const tokenResponse = await fetch("https://oauth2.googleapis.com/token", {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: `grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=${jwt}`
+      });
+      if (!tokenResponse.ok) {
+        const errText = await tokenResponse.text();
+        throw new Error(`GCP SA token exchange failed: ${tokenResponse.status} ${errText}`);
+      }
+      const data = await tokenResponse.json();
+      this.accessToken = data.access_token;
+      this.tokenExpiry = Date.now() + data.expires_in * 1e3;
+      return data.access_token;
     }
   }
   /**