blockintel-gate-sdk 0.3.2 → 0.3.3

package/dist/index.d.cts

@@ -264,6 +264,27 @@ interface GateClientConfig {
      * 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[];
 }
 
 /**
@@ -413,6 +434,13 @@ declare class GateClient {
     private readonly mode;
     private readonly onConnectionFailure;
     constructor(config: GateClientConfig);
+    /**
+     * Perform async IAM permission risk check (non-blocking)
+     *
+     * Performs async IAM simulation check in background.
+     * Logs warnings but doesn't block (initialization already completed).
+     */
+    private performIamRiskCheckAsync;
     /**
      * Evaluate a transaction defense request
      *

package/dist/index.d.ts

@@ -264,6 +264,27 @@ interface GateClientConfig {
      * 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[];
 }
 
 /**
@@ -413,6 +434,13 @@ declare class GateClient {
     private readonly mode;
     private readonly onConnectionFailure;
     constructor(config: GateClientConfig);
+    /**
+     * Perform async IAM permission risk check (non-blocking)
+     *
+     * Performs async IAM simulation check in background.
+     * Logs warnings but doesn't block (initialization already completed).
+     */
+    private performIamRiskCheckAsync;
     /**
      * Evaluate a transaction defense request
      *

package/dist/index.js

@@ -1246,6 +1246,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.blockintel.ai/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.blockintel.ai/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.blockintel.ai/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.blockintel.ai/gate/IAM_HARDENING"
+    };
+    console.warn("[GATE WARNING]", JSON.stringify(logData, null, 2));
+  }
+};
+
 // src/client/GateClient.ts
 var GateClient = class {
   config;
@@ -1324,6 +1568,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