@iterable/mcp 1.0.3 → 1.2.0

package/dist/key-manager.js

@@ -1,67 +1,59 @@
 /**
- * Secure API Key Management using macOS Keychain
+ * Secure API Key Management with cross-platform support
  *
- * This module provides secure storage and management of multiple Iterable API keys
- * using macOS Keychain via the native `security` command-line tool.
+ * This module provides secure storage and management of multiple Iterable API keys.
  *
- * Platform Support:
- * - macOS: Full support with Keychain integration
- * - Windows/Linux: Not supported - use ITERABLE_API_KEY environment variable
- *
- * Storage:
- * - API keys: Stored securely in macOS Keychain (never on disk)
- * - Metadata: Stored in ~/.iterable-mcp/keys.json (names, IDs, endpoints, timestamps)
- * - Lock file: ~/.iterable-mcp/keys.lock (prevents concurrent modifications)
+ * Storage Strategy:
+ * - macOS: API keys in Keychain, metadata in ~/.iterable-mcp/keys.json
+ * - Windows: API keys encrypted with DPAPI in ~/.iterable-mcp/keys.json
+ * - Linux: API keys and metadata in ~/.iterable-mcp/keys.json (mode 0o600)
+ * - Lock file: ~/.iterable-mcp/keys.lock prevents concurrent modifications
  *
  * Security Features:
- * - Uses spawn() with argument arrays to prevent shell injection
- * - File-based locking for concurrent access protection
- * - Test-specific service name to isolate test keychain entries
  * - API key format validation (32-char lowercase hex)
- * - HTTPS-only URL validation
+ * - HTTPS-only URL validation (except localhost)
  * - Duplicate key detection (both names and values)
+ * - File-based locking for concurrent access protection
+ * - Restrictive file permissions where supported (Linux/macOS)
  */
 import { logger } from "@iterable/api";
-import { spawn } from "child_process";
+import { execFile } from "child_process";
 import { randomUUID } from "crypto";
 import { promises as fs } from "fs";
 import os from "os";
 import path from "path";
+import { promisify } from "util";
 import { isHttpsOrLocalhost, isLocalhostHost } from "./utils/url.js";
 // Service name for keychain entries
 // IMPORTANT: This must be constant to avoid data loss. Never use NODE_ENV here!
 // Tests should use dependency injection with mock execSecurity instead.
 const SERVICE_NAME = "iterable-mcp";
+const execFileAsync = promisify(execFile);
 /**
  * Safely execute macOS security command with proper argument escaping
- * Uses spawn to prevent shell injection vulnerabilities
+ * Uses execFile to prevent shell injection vulnerabilities
  */
 async function execSecurityDefault(args) {
-    return new Promise((resolve, reject) => {
-        const child = spawn("security", args, {
-            stdio: ["ignore", "pipe", "pipe"],
-        });
-        let stdout = "";
-        let stderr = "";
-        child.stdout.on("data", (data) => {
-            stdout += data.toString();
-        });
-        child.stderr.on("data", (data) => {
-            stderr += data.toString();
-        });
-        child.on("error", (error) => {
-            reject(new Error(`Failed to execute security command: ${error.message}`));
-        });
-        child.on("close", (code) => {
-            if (code === 0) {
-                resolve(stdout.trim());
-            }
-            else {
-                reject(new Error(`Security command failed with code ${code}: ${stderr.trim() || stdout.trim()}`));
-            }
-        });
-    });
+    try {
+        const { stdout } = await execFileAsync("security", args);
+        return stdout.trim();
+    }
+    catch (error) {
+        throw new Error(`Security command failed: ${error.stderr?.toString().trim() || error.message}`);
+    }
 }
+/**
+ * Storage method for API keys
+ */
+var StorageMethod;
+(function (StorageMethod) {
+    /** macOS Keychain - keys stored and encrypted by OS keychain service */
+    StorageMethod["KEYCHAIN"] = "keychain";
+    /** Windows DPAPI - keys encrypted by OS (user-scoped keys), stored in JSON file */
+    StorageMethod["DPAPI"] = "dpapi";
+    /** File storage - plaintext keys in JSON file with restrictive permissions (Linux/other) */
+    StorageMethod["FILE"] = "file";
+})(StorageMethod || (StorageMethod = {}));
 export class KeyManager {
     configDir;
     metadataFile;
@@ -69,25 +61,39 @@ export class KeyManager {
     store = null;
     saveLock = null;
     execSecurity;
+    storageMethod;
     /**
      * Create a new KeyManager instance
      *
      * @param configDir - Optional custom config directory (defaults to ~/.iterable-mcp)
      * @param execSecurity - Optional security command executor (for dependency injection in tests)
-     * @throws {Error} If not running on macOS and no mock executor is provided
      */
     constructor(configDir, execSecurity) {
-        // Check if running on macOS (skip check in tests when mock is provided)
-        if (!execSecurity && process.platform !== "darwin") {
-            throw new Error("Key Manager only supports macOS. Windows and Linux users should use the ITERABLE_API_KEY environment variable.");
-        }
         this.configDir = configDir || path.join(os.homedir(), ".iterable-mcp");
         this.metadataFile = path.join(this.configDir, "keys.json");
         this.lockFile = path.join(this.configDir, "keys.lock");
         this.execSecurity = execSecurity || execSecurityDefault;
+        // Determine storage method based on platform
+        // Can be overridden via ITERABLE_MCP_FORCE_FILE_STORAGE=true
+        if (process.env.ITERABLE_MCP_FORCE_FILE_STORAGE === "true") {
+            // Force file storage mode (for testing or debugging)
+            this.storageMethod = StorageMethod.FILE;
+        }
+        else if (execSecurity || process.platform === "darwin") {
+            // Use Keychain on macOS or when execSecurity is provided (for tests)
+            this.storageMethod = StorageMethod.KEYCHAIN;
+        }
+        else if (process.platform === "win32") {
+            // Use DPAPI on Windows
+            this.storageMethod = StorageMethod.DPAPI;
+        }
+        else {
+            // Use file storage on other platforms
+            this.storageMethod = StorageMethod.FILE;
+        }
     }
     /**
-     * Validate metadata against keychain and clean up orphaned entries
+     * Validate metadata against keychain and clean up orphaned entries (macOS only)
      *
      * Checks if each key in metadata still exists in the keychain.
      * Removes any metadata entries that no longer have corresponding keychain entries.
@@ -96,7 +102,10 @@ export class KeyManager {
      * @returns Array of cleaned up key names (if any)
      */
     async validateAndCleanup() {
-        if (!this.store || this.store.keys.length === 0) {
+        // Only validate Keychain on macOS
+        if (this.storageMethod !== StorageMethod.KEYCHAIN ||
+            !this.store ||
+            this.store.keys.length === 0) {
             return [];
         }
         const orphanedKeys = [];
@@ -393,18 +402,85 @@ export class KeyManager {
             console.warn(`⚠️  Warning: Using non-standard Iterable domain: ${url.hostname}`);
         }
     }
+    /**
+     * Encrypt data using Windows DPAPI
+     *
+     * Security: Uses native C++ bindings to Windows DPAPI (Data Protection API).
+     * - No shell execution or code evaluation
+     * - Encrypted data can only be decrypted by the same user on the same machine
+     * - Uses CurrentUser scope for user-level protection
+     * - No optional entropy parameter (null) for simplicity
+     *
+     * @param text - Plain text to encrypt (validated as 32-char hex by caller)
+     * @returns Base64-encoded encrypted blob
+     * @throws {Error} If DPAPI encryption fails or platform is not Windows
+     */
+    async encryptWindows(text) {
+        if (process.platform !== "win32") {
+            throw new Error("DPAPI encryption is only supported on Windows");
+        }
+        try {
+            // Dynamic import to avoid loading native module on non-Windows platforms
+            const { Dpapi } = await import("@primno/dpapi");
+            // Convert string to buffer (UTF-8 encoding)
+            const plainBuffer = Buffer.from(text, "utf-8");
+            // Encrypt using DPAPI (returns Uint8Array)
+            // Parameters: data, optionalEntropy (null), scope ("CurrentUser")
+            const encryptedBytes = Dpapi.protectData(plainBuffer, null, "CurrentUser");
+            // Convert to Buffer and encode as base64 for JSON storage
+            return Buffer.from(encryptedBytes).toString("base64");
+        }
+        catch (error) {
+            logger.error("DPAPI encryption failed", { error });
+            throw new Error(`Failed to encrypt data with Windows DPAPI: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Decrypt data using Windows DPAPI
+     *
+     * Security: Uses native C++ bindings to Windows DPAPI.
+     * - No shell execution or code evaluation
+     * - Only the user who encrypted the data can decrypt it
+     * - Validates base64 input before decryption
+     *
+     * @param encryptedBase64 - Base64-encoded encrypted blob
+     * @returns Decrypted plain text
+     * @throws {Error} If DPAPI decryption fails, data is corrupt, or platform is not Windows
+     */
+    async decryptWindows(encryptedBase64) {
+        if (process.platform !== "win32") {
+            throw new Error("DPAPI decryption is only supported on Windows");
+        }
+        // Validate base64 format to prevent invalid data from reaching DPAPI
+        if (!/^[A-Za-z0-9+/]+=*$/.test(encryptedBase64)) {
+            throw new Error("Invalid encrypted data format (not valid base64)");
+        }
+        try {
+            // Dynamic import to avoid loading native module on non-Windows platforms
+            const { Dpapi } = await import("@primno/dpapi");
+            // Decode base64 to buffer
+            const encryptedBuffer = Buffer.from(encryptedBase64, "base64");
+            // Decrypt using DPAPI (returns Uint8Array)
+            // Parameters: encryptedData, optionalEntropy (null), scope ("CurrentUser")
+            const decryptedBytes = Dpapi.unprotectData(encryptedBuffer, null, "CurrentUser");
+            // Convert to Buffer and decode as UTF-8
+            return Buffer.from(decryptedBytes).toString("utf-8");
+        }
+        catch (error) {
+            logger.error("DPAPI decryption failed", { error });
+            throw new Error(`Failed to decrypt data with Windows DPAPI: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     /**
      * Add a new API key
      *
-     * Securely stores an API key in macOS Keychain and saves its metadata
-     * (name, base URL, timestamps) to disk. Each key is tightly coupled to
-     * its API endpoint.
+     * Stores an API key securely (Keychain on macOS, file on other platforms).
      *
      * @param name - User-friendly name for the key (must be unique)
      * @param apiKey - 32-character lowercase hexadecimal Iterable API key
      * @param baseUrl - Iterable API base URL (must be HTTPS)
      * @returns The unique ID generated for this key
-     * @throws {Error} If the key name already exists, validation fails, or keychain storage fails
+     * @throws {Error} If the key name already exists, validation fails, or storage fails
      */
     async addKey(name, apiKey, baseUrl, envOverrides) {
         if (!this.store) {
@@ -425,24 +501,6 @@ export class KeyManager {
         }
         // Generate unique ID
         const id = this.generateId();
-        // Store in macOS Keychain using security command
-        // Using spawn with argument array to prevent shell injection
-        try {
-            await this.execSecurity([
-                "add-generic-password",
-                "-a",
-                id,
-                "-s",
-                SERVICE_NAME,
-                "-w",
-                apiKey,
-                "-U",
-            ]);
-        }
-        catch (error) {
-            logger.error("Failed to store key in keychain", { error, id });
-            throw new Error(`Failed to store key in macOS Keychain: ${error instanceof Error ? error.message : String(error)}`);
-        }
         // If this is the first key, make it active
         const isActive = this.store.keys.length === 0;
         // Create metadata
@@ -456,6 +514,40 @@ export class KeyManager {
                 ? { env: envOverrides }
                 : {}),
         };
+        // Store API key
+        switch (this.storageMethod) {
+            case StorageMethod.KEYCHAIN:
+                try {
+                    await this.execSecurity([
+                        "add-generic-password",
+                        "-a",
+                        id,
+                        "-s",
+                        SERVICE_NAME,
+                        "-w",
+                        apiKey,
+                        "-U",
+                    ]);
+                }
+                catch (error) {
+                    logger.error("Failed to store key in keychain", { error, id });
+                    throw new Error(`Failed to store key in macOS Keychain: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                break;
+            case StorageMethod.DPAPI:
+                try {
+                    metadata.encryptedApiKey = await this.encryptWindows(apiKey);
+                }
+                catch (error) {
+                    logger.error("Failed to encrypt key with DPAPI", { error, id });
+                    throw new Error(`Failed to encrypt key with Windows DPAPI: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                break;
+            default:
+                // Linux/Other: Store in JSON
+                metadata.apiKey = apiKey;
+                break;
+        }
         // Store metadata
         this.store.keys.push(metadata);
         await this.saveMetadata();
@@ -499,11 +591,11 @@ export class KeyManager {
     /**
      * Get a key by ID or name
      *
-     * Retrieves the actual API key value from macOS Keychain.
+     * Retrieves the actual API key value from storage.
      *
      * @param idOrName - The unique ID or user-friendly name of the key
      * @returns The API key value, or null if not found
-     * @throws {Error} If keychain access fails
+     * @throws {Error} If storage access fails
      */
     async getKey(idOrName) {
         if (!this.store) {
@@ -517,31 +609,62 @@ export class KeyManager {
         if (!keyMeta) {
             return null;
         }
-        // Get from macOS Keychain using security command
-        // Using spawn with argument array to prevent shell injection
-        let apiKey;
-        try {
-            apiKey = await this.execSecurity([
-                "find-generic-password",
-                "-a",
-                keyMeta.id,
-                "-s",
-                SERVICE_NAME,
-                "-w",
-            ]);
-        }
-        catch (error) {
-            logger.error("Failed to retrieve key from keychain", {
-                error,
-                id: keyMeta.id,
-            });
-            throw new Error(`Failed to retrieve key from macOS Keychain: ${error instanceof Error ? error.message : String(error)}`);
-        }
-        if (!apiKey) {
-            logger.error("Key not found in keychain", { id: keyMeta.id });
-            throw new Error(`Key not found in macOS Keychain for ID ${keyMeta.id}`);
+        // Get API key
+        switch (this.storageMethod) {
+            case StorageMethod.KEYCHAIN:
+                // macOS: Get from Keychain
+                try {
+                    const apiKey = await this.execSecurity([
+                        "find-generic-password",
+                        "-a",
+                        keyMeta.id,
+                        "-s",
+                        SERVICE_NAME,
+                        "-w",
+                    ]);
+                    if (!apiKey) {
+                        logger.error("Key not found in keychain", { id: keyMeta.id });
+                        throw new Error(`Key not found in macOS Keychain for ID ${keyMeta.id}`);
+                    }
+                    return apiKey;
+                }
+                catch (error) {
+                    logger.error("Failed to retrieve key from keychain", {
+                        error,
+                        id: keyMeta.id,
+                    });
+                    throw new Error(`Failed to retrieve key from macOS Keychain: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            case StorageMethod.DPAPI:
+                // Windows: Decrypt from JSON
+                if (keyMeta.encryptedApiKey) {
+                    try {
+                        return await this.decryptWindows(keyMeta.encryptedApiKey);
+                    }
+                    catch (error) {
+                        logger.error("Failed to decrypt key with DPAPI", {
+                            error,
+                            id: keyMeta.id,
+                        });
+                        throw new Error(`Failed to decrypt key with Windows DPAPI: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+                else if (keyMeta.apiKey) {
+                    // Fallback for legacy keys stored in plaintext on Windows
+                    return keyMeta.apiKey;
+                }
+                else {
+                    logger.error("Key not found in metadata", { id: keyMeta.id });
+                    throw new Error(`Key not found in storage for ID ${keyMeta.id}`);
+                }
+            default:
+                // Linux/Other: Get from JSON
+                if (!keyMeta.apiKey) {
+                    logger.error("Key not found in metadata", { id: keyMeta.id });
+                    throw new Error(`Key not found in storage for ID ${keyMeta.id}`);
+                }
+                return keyMeta.apiKey;
         }
-        return apiKey;
     }
     /**
      * Get the currently active key
@@ -550,7 +673,7 @@ export class KeyManager {
      * Only one key can be active at a time.
      *
      * @returns The active API key value, or null if no key is active
-     * @throws {Error} If keychain access fails
+     * @throws {Error} If storage access fails
      */
     async getActiveKey() {
         if (!this.store) {
@@ -569,7 +692,7 @@ export class KeyManager {
      * Get the active key metadata
      *
      * Returns metadata for the currently active key without retrieving the
-     * actual API key value from Keychain.
+     * actual API key value.
      *
      * @returns The active key metadata, or null if no key is active
      * @throws {Error} If the key store is not initialized
@@ -616,10 +739,9 @@ export class KeyManager {
     /**
      * Delete a key by ID
      *
-     * Removes a key from both the macOS Keychain and the metadata store.
+     * Removes a key from storage and the metadata store.
      * The currently active key cannot be deleted - you must activate a different
-     * key first. If keychain deletion fails, the metadata will still be removed
-     * and a warning will be displayed.
+     * key first.
      *
      * Note: Only accepts key ID (not name) since IDs are guaranteed unique.
      *
@@ -643,38 +765,46 @@ export class KeyManager {
         if (keyMeta.isActive) {
             throw new Error(`Cannot delete the currently active key "${keyMeta.name}". Please activate a different key first.`);
         }
-        // Delete from macOS Keychain using security command
-        // Using spawn with argument array to prevent shell injection
-        let keychainDeleted = false;
-        try {
-            await this.execSecurity([
-                "delete-generic-password",
-                "-a",
-                keyMeta.id,
-                "-s",
-                SERVICE_NAME,
-            ]);
-            keychainDeleted = true;
-        }
-        catch (error) {
-            logger.error("Failed to delete key from keychain", {
-                error,
-                id: keyMeta.id,
-            });
-            // Continue anyway to clean up metadata, but warn the user
-        }
-        // Remove from metadata
-        this.store.keys.splice(index, 1);
-        await this.saveMetadata();
-        if (!keychainDeleted) {
-            logger.warn("Key removed from metadata but may still exist in Keychain", {
-                id: keyMeta.id,
-                name: keyMeta.name,
-            });
-            console.warn(`⚠️  Warning: Key "${keyMeta.name}" removed from metadata but may still exist in Keychain.`);
-            console.warn(`    To manually remove: security delete-generic-password -a "${keyMeta.id}" -s "${SERVICE_NAME}"`);
+        // Delete from storage
+        if (this.storageMethod === StorageMethod.KEYCHAIN) {
+            // macOS: Delete from Keychain
+            let keychainDeleted = false;
+            try {
+                await this.execSecurity([
+                    "delete-generic-password",
+                    "-a",
+                    keyMeta.id,
+                    "-s",
+                    SERVICE_NAME,
+                ]);
+                keychainDeleted = true;
+            }
+            catch (error) {
+                logger.error("Failed to delete key from keychain", {
+                    error,
+                    id: keyMeta.id,
+                });
+                // Continue anyway to clean up metadata, but warn the user
+            }
+            // Remove from metadata
+            this.store.keys.splice(index, 1);
+            await this.saveMetadata();
+            if (!keychainDeleted) {
+                logger.warn("Key removed from metadata but may still exist in Keychain", {
+                    id: keyMeta.id,
+                    name: keyMeta.name,
+                });
+                console.warn(`⚠️  Warning: Key "${keyMeta.name}" removed from metadata but may still exist in Keychain.`);
+                console.warn(`    To manually remove: security delete-generic-password -a "${keyMeta.id}" -s "${SERVICE_NAME}"`);
+            }
+            else {
+                logger.info("API key deleted", { id: keyMeta.id, name: keyMeta.name });
+            }
         }
         else {
+            // Windows/Linux: Just remove from JSON
+            this.store.keys.splice(index, 1);
+            await this.saveMetadata();
             logger.info("API key deleted", { id: keyMeta.id, name: keyMeta.name });
         }
     }
@@ -698,12 +828,12 @@ export class KeyManager {
     /**
      * Find a key by its actual API key value
      *
-     * Checks all stored keys in the keychain to see if the given API key value
-     * already exists. Useful for preventing duplicate key values.
+     * Checks all stored keys to see if the given API key value already exists.
+     * Useful for preventing duplicate key values.
      *
      * @param apiKeyValue - The API key value to search for
      * @returns The metadata of the matching key, or null if not found
-     * @throws {Error} If keychain access fails
+     * @throws {Error} If storage access fails
      */
     async findKeyByValue(apiKeyValue) {
         if (!this.store) {
@@ -715,20 +845,42 @@ export class KeyManager {
         // Check each key to see if the value matches
         for (const keyMeta of this.store.keys) {
             try {
-                const storedKey = await this.execSecurity([
-                    "find-generic-password",
-                    "-a",
-                    keyMeta.id,
-                    "-s",
-                    SERVICE_NAME,
-                    "-w",
-                ]);
+                let storedKey;
+                switch (this.storageMethod) {
+                    case StorageMethod.KEYCHAIN:
+                        storedKey = await this.execSecurity([
+                            "find-generic-password",
+                            "-a",
+                            keyMeta.id,
+                            "-s",
+                            SERVICE_NAME,
+                            "-w",
+                        ]);
+                        break;
+                    case StorageMethod.DPAPI:
+                        if (keyMeta.encryptedApiKey) {
+                            storedKey = await this.decryptWindows(keyMeta.encryptedApiKey);
+                        }
+                        else if (keyMeta.apiKey) {
+                            storedKey = keyMeta.apiKey;
+                        }
+                        else {
+                            continue;
+                        }
+                        break;
+                    default:
+                        if (!keyMeta.apiKey) {
+                            continue;
+                        }
+                        storedKey = keyMeta.apiKey;
+                        break;
+                }
                 if (storedKey.trim() === apiKeyValue) {
                     return keyMeta;
                 }
             }
             catch {
-                // Skip keys that can't be retrieved (may have been manually deleted from keychain)
+                // Skip keys that can't be retrieved (may have been manually deleted)
                 continue;
             }
         }
@@ -739,13 +891,13 @@ export class KeyManager {
      *
      * Adds an API key to the key manager with a default name if it doesn't
      * already exist. This is used during the migration path from environment
-     * variable-based configuration to secure keychain storage.
+     * variable-based configuration to key manager storage.
      *
      * @param apiKey - The 32-character lowercase hexadecimal API key to migrate
      * @param baseUrl - The Iterable API base URL for this key
      * @param name - The name to assign (defaults to "default")
      * @returns The unique ID of the migrated key (existing or newly created)
-     * @throws {Error} If validation fails or keychain storage fails
+     * @throws {Error} If validation fails or storage fails
      */
     async migrateLegacyKey(apiKey, baseUrl, name = "default") {
         // Check if a key with this name already exists