mindsim 0.1.6 → 0.1.7

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
+  );
 };

package/src/index.ts

@@ -1,5 +1,5 @@
 import axios, { type AxiosInstance } from "axios";
-import { getApiBaseUrl, loadApiKey } from "./config";
+import { getApiBaseUrl, loadApiKey, loadServiceJson, validateServiceJson } from "./config";
 import { ArtifactsResource } from "./resources/artifacts";
 import { MindTopicsResource } from "./resources/mind-topics";
 import { MindsResource } from "./resources/minds";
@@ -7,10 +7,60 @@ import { PsychometricsResource } from "./resources/psychometrics";
 import { SimulationsResource } from "./resources/simulations";
 import { SnapshotsResource } from "./resources/snapshots";
 import { TagsResource } from "./resources/tags";
+import type { MindsimServiceJson } from "./types";
 import { checkForUpdates, getPackageVersion } from "./version";
 
+// =============================================================================
+// Gap 15 Fix: Browser Compatibility Check
+// =============================================================================
+
+/**
+ * Check if the SDK is running in a Node.js environment.
+ * Some features (like file-based service JSON loading) only work in Node.js.
+ */
+export function isNodeEnvironment(): boolean {
+  return (
+    typeof process !== "undefined" && process.versions != null && process.versions.node != null
+  );
+}
+
+/**
+ * Check if the SDK is running in a browser environment.
+ */
+export function isBrowserEnvironment(): boolean {
+  // Use typeof checks to avoid ReferenceError in Node.js
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  return typeof globalThis !== "undefined" && "window" in globalThis && "document" in globalThis;
+}
+
+// =============================================================================
+// Gap 14 Fix: Auth Method Detection
+// =============================================================================
+
+/**
+ * Authentication method used by the MindSim client.
+ */
+export type AuthMethod =
+  | "service_json" // Service JSON credentials (file or base64)
+  | "api_key_env" // MINDSIM_API_KEY environment variable
+  | "api_key_constructor" // API key passed to constructor
+  | "config_file"; // ~/.mindsim/config file
+
+/**
+ * Options for initializing the MindSim client.
+ */
+export interface MindSimOptions {
+  /** Custom API base URL (overrides default and service JSON) */
+  apiBaseUrl?: string;
+  /** Service JSON credentials (alternative to API key) */
+  serviceJson?: MindsimServiceJson;
+}
+
 export class MindSim {
   private client: AxiosInstance;
+  private serviceJson: MindsimServiceJson | null = null;
+  // Gap 14 Fix: Track which auth method was used
+  private authMethod: AuthMethod = "config_file";
 
   public artifacts: ArtifactsResource;
   public minds: MindsResource;
@@ -20,20 +70,72 @@ export class MindSim {
   public simulations: SimulationsResource;
   public tags: TagsResource;
 
-  constructor(apiKey?: string, options?: { apiBaseUrl?: string }) {
+  constructor(apiKey?: string, options?: MindSimOptions) {
     // 1. Trigger the auto-update check (Fire and forget, do not await)
     checkForUpdates().catch(() => {
       // Catching here ensures no unhandled promise rejections in the user's console
       // if the check fails completely.
     });
 
-    const token = apiKey || loadApiKey();
     const sdkVersion = getPackageVersion();
-    const apiBaseUrl = options?.apiBaseUrl || getApiBaseUrl();
+
+    // Priority for credentials:
+    // 1. Constructor apiKey parameter
+    // 2. Constructor serviceJson option
+    // 3. Environment service JSON (MINDSIM_SERVICE_JSON or MINDSIM_SERVICE_JSON_BASE64)
+    // 4. Environment API key (MINDSIM_API_KEY)
+    // 5. Config file (~/.mindsim/config)
+
+    let token: string | null = apiKey || null;
+    let apiBaseUrl = options?.apiBaseUrl || getApiBaseUrl();
+
+    // Track auth method for Gap 14 fix
+    if (apiKey) {
+      this.authMethod = "api_key_constructor";
+    }
+
+    // Check for service JSON if no direct API key provided
+    if (!token) {
+      let serviceJson: MindsimServiceJson | null = null;
+
+      // Gap 3 Fix: Validate serviceJson when passed via constructor options
+      if (options?.serviceJson) {
+        const validation = validateServiceJson(options.serviceJson);
+        if (!validation.valid) {
+          throw new Error(`Invalid serviceJson: ${validation.errors.join(", ")}`);
+        }
+        serviceJson = validation.serviceJson as MindsimServiceJson;
+      } else {
+        // loadServiceJson() already validates internally
+        serviceJson = loadServiceJson();
+      }
+
+      if (serviceJson) {
+        this.serviceJson = serviceJson;
+        this.authMethod = "service_json";
+        token = serviceJson.api_key;
+        // Use API base URL from service JSON if not explicitly overridden
+        if (!options?.apiBaseUrl && serviceJson.api_base_url) {
+          apiBaseUrl = serviceJson.api_base_url;
+        }
+      }
+    }
+
+    // Fallback to traditional loading
+    if (!token) {
+      // Gap 7 Fix: Check if MINDSIM_API_KEY is set (only in Node environment)
+      const hasEnvApiKey = isNodeEnvironment() && process.env.MINDSIM_API_KEY;
+      if (hasEnvApiKey) {
+        this.authMethod = "api_key_env";
+      } else {
+        this.authMethod = "config_file";
+      }
+      token = loadApiKey();
+    }
 
     if (!token) {
       throw new Error(
-        "API Key not found. Please run `mindsim auth` or pass the key to the constructor.",
+        "API Key not found. Please run `mindsim auth`, set MINDSIM_SERVICE_JSON/MINDSIM_SERVICE_JSON_BASE64, or pass credentials to the constructor.",
       );
     }
 
@@ -45,6 +147,10 @@ export class MindSim {
         "x-reasoner-source": "sdk",
         "x-reasoner-sdk": "mindsim/mindsim-sdk-typescript",
         "x-reasoner-sdk-version": sdkVersion,
+        // Include project ID from service JSON for better request tracing
+        ...(this.serviceJson && {
+          "x-mindsim-project-id": this.serviceJson.project_id,
+        }),
       },
     });
 
@@ -56,7 +162,73 @@ export class MindSim {
     this.simulations = new SimulationsResource(this.client);
     this.tags = new TagsResource(this.client);
   }
+
+  /**
+   * Get the loaded service JSON (if any).
+   * Useful for debugging or accessing project metadata.
+   *
+   * @returns The service JSON object or null if not using service JSON auth
+   */
+  public getServiceJson(): MindsimServiceJson | null {
+    return this.serviceJson;
+  }
+
+  // ==========================================================================
+  // Gap 14 Fix: Auth Method Detection Helpers
+  // ==========================================================================
+
+  /**
+   * Check if the client is using service JSON authentication.
+   *
+   * @returns true if using service JSON, false otherwise
+   */
+  public isUsingServiceJsonAuth(): boolean {
+    return this.serviceJson !== null;
+  }
+
+  /**
+   * Get the authentication method used by this client.
+   *
+   * @returns The auth method: 'service_json', 'api_key_env', 'api_key_constructor', or 'config_file'
+   */
+  public getAuthMethod(): AuthMethod {
+    return this.authMethod;
+  }
+
+  /**
+   * Get authentication info for debugging.
+   * Does NOT expose the actual API key.
+   *
+   * @returns Object with auth details (method, project info if service JSON)
+   */
+  public getAuthInfo(): {
+    method: AuthMethod;
+    isServiceJson: boolean;
+    projectId: string | null;
+    projectName: string | null;
+    environment: string | null;
+  } {
+    return {
+      method: this.authMethod,
+      isServiceJson: this.serviceJson !== null,
+      projectId: this.serviceJson?.project_id ?? null,
+      projectName: this.serviceJson?.project_name ?? null,
+      environment: this.serviceJson?.environment ?? null,
+    };
+  }
 }
 
+// Export validation utilities from config
+export { type ServiceJsonValidationResult, validateServiceJson } from "./config";
+
+// Export logger interface (Gap 8 Fix)
+export {
+  createSilentLogger,
+  createVerboseLogger,
+  defaultLogger,
+  getLogger,
+  type MindSimLogger,
+  setLogger,
+} from "./logger";
 // Export types for consumer use
 export * from "./types";