blockintel-gate-sdk 0.3.2 → 0.3.4

package/README.md

@@ -1,6 +1,6 @@
 # BlockIntel Gate SDK
 
-Production-grade TypeScript/Node.js SDK for [BlockIntel Gate](https://blockintel.ai) Hot Path API.
+Production-grade TypeScript/Node.js SDK for [BlockIntel Gate](https://blockintelai.com) Hot Path API.
 
 ## Installation
 
@@ -102,6 +102,47 @@ const response = await gate.evaluate({
 });
 ```
 
+### Local Development with Gate Local
+
+For local development and testing, use **Gate Local** - a Docker container that emulates the Gate Hot Path:
+
+```bash
+# Start Gate Local
+docker pull blockintelai/gate-local:latest
+docker run -d --name gate-local -p 3000:3000 blockintelai/gate-local:latest
+```
+
+Then configure your client for local mode:
+
+```typescript
+import { GateClient } from '@blockintel/gate-sdk';
+
+// Local development configuration
+const gate = new GateClient({
+  baseUrl: 'http://localhost:3000',  // Gate Local endpoint
+  tenantId: 'local-dev',              // Any tenant ID (ignored in local mode)
+  local: true,                        // Enable local mode (disables auth/heartbeat)
+  auth: {
+    mode: 'apiKey',
+    apiKey: 'local-dev-key'           // Any API key (ignored in local mode)
+  },
+});
+
+// Evaluate transactions locally
+const response = await gate.evaluate({
+  txIntent: {
+    toAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+    value: '1000000000000000000',  // 1 ETH in wei
+    valueUsd: 2500.0,
+    chainId: 1,
+  },
+});
+
+console.log(`Decision: ${response.decision}`);
+```
+
+**📚 Full Local Development Guide**: See [Gate Local Quick Start Guide](https://docs.blockintelai.com/gate/local-development) for complete setup instructions, trading bot integration examples, and troubleshooting.
+
 ### Step-Up Polling
 
 ```typescript
@@ -159,7 +200,7 @@ When step-up is disabled, the SDK treats `REQUIRE_STEP_UP` as `BLOCK` by default
 
 ```bash
 # Required
-GATE_BASE_URL=https://gate.blockintelai.net
+GATE_BASE_URL=https://gate.blockintelai.com
 GATE_TENANT_ID=your-tenant-id
 
 # HMAC Authentication
@@ -353,12 +394,12 @@ The heartbeat manager is automatically configured based on your `GateClientConfi
 
 ```typescript
 const gate = new GateClient({
-  baseUrl: 'https://gate.blockintelai.net',  // Hot Path URL
+  baseUrl: 'https://gate.blockintelai.com',  // Hot Path URL
   tenantId: 'your-tenant-id',
   auth: { mode: 'hmac', ... },
   // Heartbeat manager uses baseUrl to infer Control Plane URL
   // Or explicitly set controlPlaneUrl if different
-  controlPlaneUrl: 'https://control-plane.blockintelai.net',  // Optional
+  controlPlaneUrl: 'https://control-plane.blockintelai.com',  // Optional
   signerId: 'my-signer-id',  // Optional: signerId for heartbeat (if known upfront)
   heartbeatRefreshIntervalSeconds: 10,  // Optional: heartbeat refresh interval (default: 10s)
 });
@@ -455,13 +496,22 @@ See [examples](./examples) directory for complete examples:
 
 See [PUBLISHING.md](./PUBLISHING.md) for detailed publishing instructions.
 
+**Quick steps:**
+1. Update version in `package.json`
+2. Create GitHub release tag
+3. GitHub Actions publishes to NPM automatically
+
 ## License
 
 MIT License - see [LICENSE](./LICENSE) file.
 
 ## Support
 
-- **Documentation:** https://docs.blockintel.ai
+- **Documentation:** https://docs.blockintelai.com
 - **Issues:** https://github.com/4KInc/blockintel-ai/issues
-- **Email:** support@blockintel.ai
+- **Email:** support@blockintelai.com
+
+## Keywords
+
+blockintel, gate, sdk, defense, crypto, security, transaction, evaluation
 

package/dist/index.cjs

@@ -1250,6 +1250,250 @@ var HeartbeatManager = class {
   }
 };
 
+// src/security/IamPermissionRiskChecker.ts
+var IamPermissionRiskChecker = class {
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Perform synchronous IAM permission risk check
+   * 
+   * Performs quick checks (credentials, environment markers) synchronously.
+   * In HARD mode, throws error if risk detected and override not set.
+   * 
+   * Use this for blocking initialization checks.
+   */
+  checkSync() {
+    const checks = [];
+    const credentialsCheck = this.checkAwsCredentials();
+    if (credentialsCheck.hasRisk) {
+      checks.push(credentialsCheck);
+    }
+    const envCheck = this.checkEnvironmentMarkers();
+    if (envCheck.hasRisk) {
+      checks.push(envCheck);
+    }
+    const highestConfidence = this.getHighestConfidence(checks);
+    const highestRisk = checks.find((c) => c.confidence === highestConfidence);
+    if (!highestRisk || !highestRisk.hasRisk) {
+      return {
+        hasRisk: false,
+        confidence: "LOW",
+        details: "No IAM permission risk detected (synchronous check)"
+      };
+    }
+    if (this.options.enforcementMode === "HARD" && !this.options.allowInsecureKmsSignPermission) {
+      const errorMessage = this.buildErrorMessage(highestRisk);
+      throw new Error(errorMessage);
+    }
+    this.logWarning(highestRisk);
+    return highestRisk;
+  }
+  /**
+   * Perform full IAM permission risk check (including async IAM simulation)
+   * 
+   * Returns risk assessment with confidence level.
+   * In HARD mode, throws error if risk detected and override not set.
+   */
+  async check() {
+    const syncResult = this.checkSync();
+    const simulationCheck = await this.checkIamSimulation();
+    if (simulationCheck.hasRisk) {
+      if (this.options.enforcementMode === "HARD" && !this.options.allowInsecureKmsSignPermission) {
+        const errorMessage = this.buildErrorMessage(simulationCheck);
+        throw new Error(errorMessage);
+      }
+      this.logWarning(simulationCheck);
+      return simulationCheck;
+    }
+    return syncResult;
+  }
+  /**
+   * Check if AWS credentials are present
+   */
+  checkAwsCredentials() {
+    const hasEnvVars = !!(process.env.AWS_ACCESS_KEY_ID || process.env.AWS_SECRET_ACCESS_KEY || process.env.AWS_SESSION_TOKEN);
+    const hasRoleCredentials = !!(process.env.AWS_ROLE_ARN || process.env.AWS_WEB_IDENTITY_TOKEN_FILE || process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI);
+    if (hasEnvVars || hasRoleCredentials) {
+      return {
+        hasRisk: true,
+        riskType: "AWS_CREDENTIALS_DETECTED",
+        confidence: "MEDIUM",
+        details: "AWS credentials detected in environment. Application may have direct KMS signing permissions.",
+        remediation: "Remove kms:Sign permission from application role. See https://docs.blockintelai.com/gate/IAM_HARDENING"
+      };
+    }
+    return {
+      hasRisk: false,
+      confidence: "LOW",
+      details: "No AWS credentials detected in environment variables"
+    };
+  }
+  /**
+   * Check IAM permissions using simulation API (if available)
+   */
+  async checkIamSimulation() {
+    try {
+      const iamModule = await import('@aws-sdk/client-iam').catch(() => null);
+      if (!iamModule || !iamModule.IAMClient || !iamModule.SimulatePrincipalPolicyCommand) {
+        return {
+          hasRisk: false,
+          confidence: "LOW",
+          details: "AWS SDK not available for IAM simulation"
+        };
+      }
+      const { IAMClient, SimulatePrincipalPolicyCommand } = iamModule;
+      const principalArn = await this.getCurrentPrincipalArn();
+      if (!principalArn) {
+        return {
+          hasRisk: false,
+          confidence: "LOW",
+          details: "Could not determine current principal ARN for simulation"
+        };
+      }
+      const client = new IAMClient({});
+      const command = new SimulatePrincipalPolicyCommand({
+        PolicySourceArn: principalArn,
+        ActionNames: ["kms:Sign"],
+        ResourceArns: this.options.kmsKeyIds?.map((id) => `arn:aws:kms:*:*:key/${id}`) || ["arn:aws:kms:*:*:key/*"]
+      });
+      const response = await client.send(command).catch(() => null);
+      if (!response) {
+        return {
+          hasRisk: false,
+          confidence: "LOW",
+          details: "IAM simulation not available (may require additional permissions)"
+        };
+      }
+      const allowsSign = response.EvaluationResults?.some(
+        (result) => result.EvalDecision === "allowed" || result.EvalDecision === "explicitAllow"
+      );
+      if (allowsSign) {
+        return {
+          hasRisk: true,
+          riskType: "DIRECT_KMS_SIGN_PERMISSION",
+          confidence: "HIGH",
+          details: `IAM simulation confirms principal ${principalArn} has kms:Sign permission. Direct KMS signing can bypass Gate.`,
+          remediation: "Remove kms:Sign permission from application role. See https://docs.blockintelai.com/gate/IAM_HARDENING"
+        };
+      }
+      return {
+        hasRisk: false,
+        confidence: "HIGH",
+        details: "IAM simulation confirms no kms:Sign permission"
+      };
+    } catch (error) {
+      return {
+        hasRisk: false,
+        confidence: "LOW",
+        details: `IAM simulation failed: ${error instanceof Error ? error.message : "Unknown error"}`
+      };
+    }
+  }
+  /**
+   * Check environment markers that suggest direct KMS usage
+   */
+  checkEnvironmentMarkers() {
+    const markers = [
+      "KMS_KEY_ID",
+      "AWS_KMS_KEY_ID",
+      "KMS_KEY_ARN",
+      "AWS_KMS_KEY_ARN"
+    ];
+    const foundMarkers = markers.filter((marker) => process.env[marker]);
+    if (foundMarkers.length > 0) {
+      return {
+        hasRisk: true,
+        riskType: "ENVIRONMENT_MARKERS",
+        confidence: "LOW",
+        details: `Environment markers suggest direct KMS usage: ${foundMarkers.join(", ")}`,
+        remediation: "Review environment variables and ensure KMS access is gated through Gate SDK"
+      };
+    }
+    return {
+      hasRisk: false,
+      confidence: "LOW",
+      details: "No environment markers suggesting direct KMS usage"
+    };
+  }
+  /**
+   * Get current principal ARN (best-effort)
+   */
+  async getCurrentPrincipalArn() {
+    try {
+      const stsModule = await import('@aws-sdk/client-sts').catch(() => null);
+      if (!stsModule || !stsModule.STSClient || !stsModule.GetCallerIdentityCommand) {
+        return null;
+      }
+      const { STSClient, GetCallerIdentityCommand } = stsModule;
+      const client = new STSClient({});
+      const command = new GetCallerIdentityCommand({});
+      const response = await client.send(command).catch(() => null);
+      if (response?.Arn) {
+        return response.Arn;
+      }
+    } catch (error) {
+    }
+    return null;
+  }
+  /**
+   * Get highest confidence level from checks
+   */
+  getHighestConfidence(checks) {
+    if (checks.some((c) => c.confidence === "HIGH")) {
+      return "HIGH";
+    }
+    if (checks.some((c) => c.confidence === "MEDIUM")) {
+      return "MEDIUM";
+    }
+    return "LOW";
+  }
+  /**
+   * Build error message for HARD mode
+   */
+  buildErrorMessage(result) {
+    const parts = [
+      "[GATE ERROR] Hard enforcement mode blocked initialization:",
+      `  - IAM permission risk: ${result.details}`,
+      `  - Risk type: ${result.riskType}`,
+      `  - Confidence: ${result.confidence}`,
+      `  - Tenant ID: ${this.options.tenantId}`
+    ];
+    if (this.options.signerId) {
+      parts.push(`  - Signer ID: ${this.options.signerId}`);
+    }
+    if (this.options.environment) {
+      parts.push(`  - Environment: ${this.options.environment}`);
+    }
+    if (result.remediation) {
+      parts.push(`  - Remediation: ${result.remediation}`);
+    }
+    parts.push("  - See: https://docs.blockintelai.com/gate/IAM_HARDENING");
+    parts.push(`  - Override: Set allowInsecureKmsSignPermission=true (not recommended for production)`);
+    return parts.join("\n");
+  }
+  /**
+   * Log warning (SOFT mode or override set)
+   */
+  logWarning(result) {
+    const logData = {
+      level: "WARN",
+      message: "IAM permission risk detected",
+      tenantId: this.options.tenantId,
+      signerId: this.options.signerId,
+      environment: this.options.environment,
+      enforcementMode: this.options.enforcementMode,
+      riskType: result.riskType,
+      confidence: result.confidence,
+      details: result.details,
+      remediation: result.remediation,
+      documentation: "https://docs.blockintelai.com/gate/IAM_HARDENING"
+    };
+    console.warn("[GATE WARNING]", JSON.stringify(logData, null, 2));
+  }
+};
+
 // src/client/GateClient.ts
 var GateClient = class {
   config;
@@ -1328,6 +1572,39 @@ var GateClient = class {
       });
       this.heartbeatManager.start();
     }
+    if (!config.local) {
+      const enforcementMode = config.enforcementMode || "SOFT";
+      const allowInsecureKmsSignPermission = config.allowInsecureKmsSignPermission ?? enforcementMode === "SOFT";
+      const riskChecker = new IamPermissionRiskChecker({
+        tenantId: config.tenantId,
+        signerId: config.signerId,
+        environment: config.environment,
+        enforcementMode,
+        allowInsecureKmsSignPermission,
+        kmsKeyIds: config.kmsKeyIds
+      });
+      riskChecker.checkSync();
+      this.performIamRiskCheckAsync(riskChecker, enforcementMode).catch((error) => {
+        if (enforcementMode === "SOFT" || allowInsecureKmsSignPermission) {
+          console.warn("[GATE CLIENT] Async IAM risk check warning:", error instanceof Error ? error.message : String(error));
+        } else {
+          console.error("[GATE CLIENT] Async IAM risk check found risk after initialization:", error);
+        }
+      });
+    }
+  }
+  /**
+   * Perform async IAM permission risk check (non-blocking)
+   * 
+   * Performs async IAM simulation check in background.
+   * Logs warnings but doesn't block (initialization already completed).
+   */
+  async performIamRiskCheckAsync(riskChecker, enforcementMode) {
+    try {
+      await riskChecker.check();
+    } catch (error) {
+      console.warn("[GATE CLIENT] Async IAM risk check warning:", error instanceof Error ? error.message : String(error));
+    }
   }
   /**
    * Evaluate a transaction defense request