mindsim 0.1.5 → 0.1.7

package/src/cli.ts

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { Command } from "commander";
 import { login } from "./auth";
+import { loadServiceJsonFromFile, validateServiceJson } from "./config";
 import { MindSim } from "./index";
 import { checkForUpdates, getPackageVersion, updateSdk } from "./version";
 
@@ -88,6 +89,111 @@ const main = async () => {
       await updateSdk();
     });
 
+  // ==========================================
+  // SERVICE JSON VALIDATION
+  // ==========================================
+
+  program
+    .command("validate-service-json")
+    .description("Validate a service JSON credentials file")
+    .argument("<path>", "Path to the service JSON file")
+    .option("-v, --verbose", "Show detailed validation results", false)
+    .action(async (filePath: string, options: { verbose: boolean }) => {
+      try {
+        const resolvedPath = path.resolve(filePath);
+
+        // Check if file exists
+        if (!fs.existsSync(resolvedPath)) {
+          console.error(`❌ File not found: ${resolvedPath}`);
+          process.exit(1);
+        }
+
+        // Read and parse the file
+        let content: string;
+        try {
+          content = fs.readFileSync(resolvedPath, "utf-8");
+        } catch (readError) {
+          console.error(
+            `❌ Failed to read file: ${readError instanceof Error ? readError.message : readError}`,
+          );
+          process.exit(1);
+        }
+
+        // Parse JSON
+        let json: unknown;
+        try {
+          json = JSON.parse(content);
+        } catch (parseError) {
+          console.error("❌ Invalid JSON syntax");
+          if (options.verbose) {
+            console.error(`   ${parseError instanceof Error ? parseError.message : parseError}`);
+          }
+          process.exit(1);
+        }
+
+        // Validate service JSON structure
+        const validation = validateServiceJson(json);
+
+        if (validation.valid) {
+          console.log("✅ Service JSON is valid");
+
+          if (options.verbose && validation.serviceJson) {
+            console.log("\n📋 Credentials Summary:");
+            console.log(`   Project ID:    ${validation.serviceJson.project_id}`);
+            console.log(`   Project Name:  ${validation.serviceJson.project_name}`);
+            console.log(`   Environment:   ${validation.serviceJson.environment}`);
+            console.log(`   Client Email:  ${validation.serviceJson.client_email}`);
+            console.log(`   API Base URL:  ${validation.serviceJson.api_base_url}`);
+            console.log(`   Scopes:        ${validation.serviceJson.scopes.join(", ")}`);
+            console.log(`   Created At:    ${validation.serviceJson.created_at}`);
+            console.log("\n🔒 API key is present (not displayed for security)");
+          }
+
+          // Test that it can actually be loaded
+          const loaded = loadServiceJsonFromFile(resolvedPath);
+          if (loaded) {
+            console.log("✅ Service JSON can be loaded successfully");
+          }
+
+          process.exit(0);
+        } else {
+          console.error("❌ Service JSON validation failed");
+          console.error("\nErrors:");
+          for (const error of validation.errors) {
+            console.error(`   • ${error}`);
+          }
+
+          if (options.verbose) {
+            console.error("\n💡 Tip: Service JSON should have this structure:");
+            console.error(`   {
+     "type": "mindsim_service_account",
+     "version": "1",
+     "project_id": "your-app-slug",
+     "project_name": "Your App Name",
+     "environment": "production",
+     "client_email": "service@your-app.mindsim.io",
+     "client_id": "uuid",
+     "api_key": "dev_xxxxx",
+     "api_base_url": "https://api.reasoner.com/api/mindsim",
+     "scopes": ["minds:read", "simulate:run"],
+     "app_metadata": {
+       "app_id": "uuid",
+       "workspace_id": "uuid",
+       "mindsim_org_id": "uuid",
+       "use_case": "customer-facing"
+     },
+     "created_at": "2025-01-01T00:00:00Z"
+   }`);
+          }
+
+          process.exit(1);
+        }
+      } catch (error) {
+        console.error("❌ Unexpected error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+
   // ==========================================
   // MINDS RESOURCES
   // ==========================================

package/src/config.ts

@@ -1,7 +1,33 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import type { DeviceAuthConfig } from "./types";
+import { getLogger } from "./logger";
+import type { DeveloperUseCase, DeviceAuthConfig, MindsimScope, MindsimServiceJson } from "./types";
+
+// =============================================================================
+// Gap 7 Fix: Browser Environment Detection
+// =============================================================================
+
+/**
+ * Check if we're running in a Node.js environment.
+ * Returns false in browsers to prevent process.env access errors.
+ */
+function isNodeEnvironment(): boolean {
+  return (
+    typeof process !== "undefined" && process.versions != null && process.versions.node != null
+  );
+}
+
+/**
+ * Safely get an environment variable.
+ * Returns undefined in browser environments.
+ */
+function getEnvVar(name: string): string | undefined {
+  if (!isNodeEnvironment()) {
+    return undefined;
+  }
+  return process.env[name];
+}
 
 const API_BASE_URL = "https://api.reasoner.com/api/mindsim";
 const WORKOS_DEVICE_AUTH_URL = "https://auth.reasoner.com/user_management/authorize/device";
@@ -9,34 +35,390 @@ const WORKOS_TOKEN_URL = "https://auth.reasoner.com/user_management/authenticate
 const WORKOS_CLIENT_ID = "client_01GPECHM1J9DMY7WQNKTJ195P6";
 const SDK_KEYS_API_URL = "https://api.reasoner.com/api/sdk/keys";
 
-export function getConfigDir() {
+// Valid scopes for validation (must match rainmaker's ALL_SCOPES)
+const VALID_SCOPES: MindsimScope[] = [
+  "minds:read",
+  "minds:write",
+  "simulate:run",
+  "simulate:read",
+  "users:read",
+  "users:write",
+  "org:admin",
+];
+
+// Valid use cases for validation
+const VALID_USE_CASES: DeveloperUseCase[] = ["internal-workflow", "customer-facing", "agentic-ai"];
+
+// =============================================================================
+// Gap 12-14 Fix: Validation Helpers
+// =============================================================================
+
+/**
+ * UUID v4 validation regex
+ */
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Validate a UUID string
+ */
+function isValidUUID(value: unknown): boolean {
+  return typeof value === "string" && UUID_REGEX.test(value);
+}
+
+/**
+ * Validate a URL string (must be HTTPS for production)
+ */
+function isValidHttpsUrl(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate an ISO 8601 timestamp string
+ */
+function isValidISOTimestamp(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  const date = new Date(value);
+  return !Number.isNaN(date.getTime()) && value.includes("T");
+}
+
+/**
+ * Gap 8 Fix: Validate an email address format
+ */
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function isValidEmail(value: unknown): boolean {
+  return typeof value === "string" && EMAIL_REGEX.test(value);
+}
+
+/**
+ * Get the MindSim config directory path.
+ * @returns Path to ~/.mindsim directory
+ */
+export function getConfigDir(): string {
   return path.join(os.homedir(), ".mindsim");
 }
 
-export function getConfigFile() {
+/**
+ * Get the MindSim config file path.
+ * @returns Path to ~/.mindsim/config file
+ */
+export function getConfigFile(): string {
   return path.join(getConfigDir(), "config");
 }
 
+// =============================================================================
+// Service JSON Validation (Gap 6 Fix)
+// =============================================================================
+
+/**
+ * Validation result for service JSON.
+ */
+export interface ServiceJsonValidationResult {
+  valid: boolean;
+  errors: string[];
+  serviceJson?: MindsimServiceJson;
+}
+
+/**
+ * Validate a service JSON object has all required fields with correct types.
+ * This provides detailed error messages for debugging.
+ *
+ * @param json - The parsed JSON object to validate
+ * @returns Validation result with errors if invalid
+ */
+export function validateServiceJson(json: unknown): ServiceJsonValidationResult {
+  const errors: string[] = [];
+
+  if (!json || typeof json !== "object") {
+    return { valid: false, errors: ["Service JSON must be a valid object"] };
+  }
+
+  const obj = json as Record<string, unknown>;
+
+  // Required string fields
+  const requiredStrings: Array<{ key: string; name: string }> = [
+    { key: "type", name: "type" },
+    { key: "version", name: "version" },
+    { key: "project_id", name: "project_id" },
+    { key: "project_name", name: "project_name" },
+    { key: "environment", name: "environment" },
+    { key: "client_email", name: "client_email" },
+    { key: "client_id", name: "client_id" },
+    { key: "api_key", name: "api_key" },
+    { key: "api_base_url", name: "api_base_url" },
+    { key: "created_at", name: "created_at" },
+  ];
+
+  for (const { key, name } of requiredStrings) {
+    if (typeof obj[key] !== "string" || obj[key] === "") {
+      errors.push(`Missing or invalid required field: ${name}`);
+    }
+  }
+
+  // Validate type field value
+  if (obj.type !== "mindsim_service_account") {
+    errors.push('type field must be "mindsim_service_account"');
+  }
+
+  // Validate environment field value
+  if (obj.environment !== "production") {
+    errors.push('environment field must be "production"');
+  }
+
+  // Validate scopes array
+  if (!Array.isArray(obj.scopes)) {
+    errors.push("scopes must be an array");
+  } else if (obj.scopes.length === 0) {
+    errors.push("scopes array cannot be empty");
+  } else {
+    for (const scope of obj.scopes) {
+      if (!VALID_SCOPES.includes(scope as MindsimScope)) {
+        errors.push(`Invalid scope: ${scope}. Valid scopes: ${VALID_SCOPES.join(", ")}`);
+      }
+    }
+  }
+
+  // Validate app_metadata object
+  if (!obj.app_metadata || typeof obj.app_metadata !== "object") {
+    errors.push("app_metadata must be an object");
+  } else {
+    const metadata = obj.app_metadata as Record<string, unknown>;
+    const metadataFields = ["app_id", "workspace_id", "mindsim_org_id"];
+
+    for (const field of metadataFields) {
+      if (typeof metadata[field] !== "string" || metadata[field] === "") {
+        errors.push(`Missing or invalid app_metadata.${field}`);
+      }
+    }
+
+    // Validate use_case
+    if (!VALID_USE_CASES.includes(metadata.use_case as DeveloperUseCase)) {
+      errors.push(
+        `Invalid app_metadata.use_case: ${metadata.use_case}. Valid values: ${VALID_USE_CASES.join(", ")}`,
+      );
+    }
+
+    // Gap 12 Fix: Validate UUID format for ID fields
+    const uuidFields = ["app_id", "workspace_id", "mindsim_org_id"];
+    for (const field of uuidFields) {
+      if (metadata[field] && !isValidUUID(metadata[field])) {
+        errors.push(`Invalid UUID format for app_metadata.${field}`);
+      }
+    }
+  }
+
+  // Gap 12 Fix: Validate client_id as UUID
+  if (obj.client_id && !isValidUUID(obj.client_id)) {
+    errors.push("client_id must be a valid UUID");
+  }
+
+  // Gap 8 Fix: Validate client_email as valid email format
+  if (obj.client_email && !isValidEmail(obj.client_email)) {
+    errors.push("client_email must be a valid email address");
+  }
+
+  // Gap 13 Fix: Validate api_base_url as HTTPS URL
+  if (obj.api_base_url && !isValidHttpsUrl(obj.api_base_url)) {
+    errors.push("api_base_url must be a valid HTTPS URL");
+  }
+
+  // Gap 14 Fix: Validate timestamps as ISO 8601
+  if (obj.created_at && !isValidISOTimestamp(obj.created_at)) {
+    errors.push("created_at must be a valid ISO 8601 timestamp");
+  }
+  if (obj.expires_at && !isValidISOTimestamp(obj.expires_at)) {
+    errors.push("expires_at must be a valid ISO 8601 timestamp");
+  }
+  if (obj.issued_at && !isValidISOTimestamp(obj.issued_at)) {
+    errors.push("issued_at must be a valid ISO 8601 timestamp");
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+
+  return { valid: true, errors: [], serviceJson: obj as unknown as MindsimServiceJson };
+}
+
+// =============================================================================
+// Service JSON Loading Functions
+// =============================================================================
+
+/**
+ * Load service JSON from a file path.
+ *
+ * @param filePath - Path to the service JSON file
+ * @returns MindsimServiceJson object or null if invalid/not found
+ */
+export function loadServiceJsonFromFile(filePath: string): MindsimServiceJson | null {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    const content = fs.readFileSync(filePath, "utf-8");
+
+    let json: unknown;
+    try {
+      json = JSON.parse(content);
+    } catch (parseError) {
+      getLogger().error("Failed to parse service JSON file (invalid JSON syntax):", parseError);
+      return null;
+    }
+
+    // Validate all required fields
+    const validation = validateServiceJson(json);
+    if (!validation.valid) {
+      getLogger().error("Invalid service JSON:", validation.errors.join("; "));
+      return null;
+    }
+
+    return validation.serviceJson as MindsimServiceJson;
+  } catch (error) {
+    // Distinguish between different error types
+    if (error instanceof Error && "code" in error) {
+      const nodeError = error as NodeJS.ErrnoException;
+      if (nodeError.code === "EACCES") {
+        getLogger().error("Permission denied reading service JSON file:", filePath);
+      } else if (nodeError.code === "ENOENT") {
+        // File doesn't exist - this is handled above, but just in case
+        return null;
+      } else {
+        getLogger().error(`Failed to read service JSON file (${nodeError.code}):`, error);
+      }
+    } else {
+      getLogger().error("Failed to load service JSON:", error);
+    }
+    return null;
+  }
+}
+
+/**
+ * Load service JSON from a base64-encoded string.
+ * Useful for environment variables in containerized environments.
+ *
+ * @param base64 - Base64-encoded service JSON string
+ * @returns MindsimServiceJson object or null if invalid
+ */
+export function loadServiceJsonFromBase64(base64: string): MindsimServiceJson | null {
+  try {
+    if (!base64 || base64.trim() === "") {
+      getLogger().error("Empty base64 string provided");
+      return null;
+    }
+
+    const decoded = Buffer.from(base64, "base64").toString("utf-8");
+
+    if (!decoded || decoded.trim() === "") {
+      getLogger().error("Base64 decoded to empty string");
+      return null;
+    }
+
+    let json: unknown;
+    try {
+      json = JSON.parse(decoded);
+    } catch (parseError) {
+      getLogger().error("Failed to parse decoded service JSON (invalid JSON syntax):", parseError);
+      return null;
+    }
+
+    // Validate all required fields
+    const validation = validateServiceJson(json);
+    if (!validation.valid) {
+      getLogger().error("Invalid service JSON:", validation.errors.join("; "));
+      return null;
+    }
+
+    return validation.serviceJson as MindsimServiceJson;
+  } catch (error) {
+    getLogger().error("Failed to decode service JSON from base64:", error);
+    return null;
+  }
+}
+
+/**
+ * Load service JSON from environment variables.
+ * Priority: MINDSIM_SERVICE_JSON (file path) > MINDSIM_SERVICE_JSON_BASE64 (inline)
+ *
+ * @returns MindsimServiceJson object or null if not configured
+ */
+export function loadServiceJson(): MindsimServiceJson | null {
+  // Gap 7 Fix: Check Node environment before accessing env vars
+  if (!isNodeEnvironment()) {
+    return null;
+  }
+
+  // Try file path first
+  const filePath = getEnvVar("MINDSIM_SERVICE_JSON");
+  if (filePath) {
+    const serviceJson = loadServiceJsonFromFile(filePath);
+    if (serviceJson) {
+      return serviceJson;
+    }
+    getLogger().warn(`MINDSIM_SERVICE_JSON set but file not found or invalid: ${filePath}`);
+  }
+
+  // Try base64 encoded
+  const base64 = getEnvVar("MINDSIM_SERVICE_JSON_BASE64");
+  if (base64) {
+    const serviceJson = loadServiceJsonFromBase64(base64);
+    if (serviceJson) {
+      return serviceJson;
+    }
+    getLogger().warn("MINDSIM_SERVICE_JSON_BASE64 set but failed to decode");
+  }
+
+  return null;
+}
+
+// =============================================================================
+// API Key Loading
+// =============================================================================
+
+/**
+ * Load API key with priority:
+ * 1. Service JSON (env vars)
+ * 2. MINDSIM_API_KEY env var
+ * 3. Config file (~/.mindsim/config)
+ */
 export const loadApiKey = (): string | null => {
   try {
-    if (process.env.MINDSIM_API_KEY) {
-      return process.env.MINDSIM_API_KEY;
+    // Priority 1: Service JSON
+    const serviceJson = loadServiceJson();
+    if (serviceJson?.api_key) {
+      return serviceJson.api_key;
     }
 
-    const configFile = getConfigFile();
+    // Priority 2: Direct API key env var
+    const envApiKey = getEnvVar("MINDSIM_API_KEY");
+    if (envApiKey) {
+      return envApiKey;
+    }
 
-    if (fs.existsSync(configFile)) {
-      const config = JSON.parse(fs.readFileSync(configFile, "utf-8"));
-      return config.apiKey || null;
+    // Priority 3: Config file (only in Node environment)
+    if (isNodeEnvironment()) {
+      const configFile = getConfigFile();
+      if (fs.existsSync(configFile)) {
+        const config = JSON.parse(fs.readFileSync(configFile, "utf-8"));
+        return config.apiKey || null;
+      }
     }
   } catch (error) {
-    // TODO: define logging interface so users can control where they are written to
-    console.error(error);
+    getLogger().error("Failed to load API key:", error);
   }
   return null;
 };
 
 export const saveApiKey = (apiKey: string): void => {
+  // Gap 9 Fix: Check Node environment before accessing fs
+  if (!isNodeEnvironment()) {
+    throw new Error("saveApiKey is only available in Node.js environments");
+  }
+
   const configDir = getConfigDir();
   const configFile = getConfigFile();
 
@@ -48,13 +430,23 @@ export const saveApiKey = (apiKey: string): void => {
 
 export const getDeviceAuthConfig = (): DeviceAuthConfig => {
   return {
-    deviceAuthUrl: process.env.MINDSIM_WORKOS_DEVICE_AUTH_URL || WORKOS_DEVICE_AUTH_URL,
-    tokenUrl: process.env.MINDSIM_WORKOS_TOKEN_URL || WORKOS_TOKEN_URL,
-    clientId: process.env.MINDSIM_WORKOS_CLIENT_ID || WORKOS_CLIENT_ID,
-    sdkKeysApiUrl: process.env.MINDSIM_SDK_KEYS_API_URL || SDK_KEYS_API_URL,
+    deviceAuthUrl: getEnvVar("MINDSIM_WORKOS_DEVICE_AUTH_URL") || WORKOS_DEVICE_AUTH_URL,
+    tokenUrl: getEnvVar("MINDSIM_WORKOS_TOKEN_URL") || WORKOS_TOKEN_URL,
+    clientId: getEnvVar("MINDSIM_WORKOS_CLIENT_ID") || WORKOS_CLIENT_ID,
+    sdkKeysApiUrl: getEnvVar("MINDSIM_SDK_KEYS_API_URL") || SDK_KEYS_API_URL,
   };
 };
 
-export const getApiBaseUrl = () => {
-  return process.env.MIND_SIM_API_BASE_URL || API_BASE_URL;
+/**
+ * Get the API base URL.
+ * Priority: MINDSIM_API_BASE_URL > MIND_SIM_API_BASE_URL (deprecated) > default
+ * @returns API base URL
+ */
+export const getApiBaseUrl = (): string => {
+  // Gap 12 Fix: Use consistent naming (MINDSIM_*) with backwards compatibility
+  return (
+    getEnvVar("MINDSIM_API_BASE_URL") ||
+    getEnvVar("MIND_SIM_API_BASE_URL") || // Deprecated, for backwards compatibility
+    API_BASE_URL
+  );
 };