@iterable/mcp 1.0.3 → 1.1.0

package/dist/key-manager.d.ts

@@ -1,25 +1,20 @@
 /**
- * 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 and metadata 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)
  */
 export type SecurityExecutor = (args: string[]) => Promise<string>;
 export interface ApiKeyMetadata {
@@ -35,6 +30,8 @@ export interface ApiKeyMetadata {
     isActive: boolean;
     /** Optional per-key environment overrides (extensible for future vars) */
     env?: Record<string, string>;
+    /** API key value (only present when not using Keychain storage) */
+    apiKey?: string;
 }
 export declare class KeyManager {
     private readonly configDir;
@@ -43,16 +40,16 @@ export declare class KeyManager {
     private store;
     private saveLock;
     private readonly execSecurity;
+    private readonly useKeychain;
     /**
      * 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?: string, execSecurity?: SecurityExecutor);
     /**
-     * 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.
@@ -114,15 +111,13 @@ export declare class KeyManager {
     /**
      * 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
      */
     addKey(name: string, apiKey: string, baseUrl: string, envOverrides?: Record<string, string>): Promise<string>;
     /**
@@ -142,11 +137,11 @@ export declare 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
      */
     getKey(idOrName: string): Promise<string | null>;
     /**
@@ -156,14 +151,14 @@ export declare 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
      */
     getActiveKey(): Promise<string | null>;
     /**
      * 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
@@ -183,10 +178,9 @@ export declare 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.
      *
@@ -206,12 +200,12 @@ export declare 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
      */
     findKeyByValue(apiKeyValue: string): Promise<ApiKeyMetadata | null>;
     /**
@@ -219,13 +213,13 @@ export declare 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
      */
     migrateLegacyKey(apiKey: string, baseUrl: string, name?: string): Promise<string>;
 }

package/dist/key-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"key-manager.d.ts","sourceRoot":"","sources":["../src/key-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAwDH,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,4FAA4F;IAC5F,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,QAAQ,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AASD,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmB;IAEhD;;;;;;OAMG;gBACS,SAAS,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,gBAAgB;IAc/D;;;;;;;;OAQG;YACW,kBAAkB;IAmEhC;;;;;;;;;;;;OAYG;YACW,WAAW;IAsFzB;;;;;;;;;OASG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BjC;;OAEG;YACW,YAAY;IAU1B;;OAEG;YACW,cAAc;IAa5B;;OAEG;YACW,YAAY;IA6C1B;;;OAGG;IACH,OAAO,CAAC,UAAU;IAIlB;;OAEG;IACH,OAAO,CAAC,cAAc;IAWtB;;OAEG;IACH,OAAO,CAAC,eAAe;IAoCvB;;;;;;;;;;;;OAYG;IACG,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC,OAAO,CAAC,MAAM,CAAC;IAmElB;;OAEG;IACG,YAAY,CAChB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,OAAO,CAAC,IAAI,CAAC;IAiBhB;;;;;;;;OAQG;IACG,QAAQ,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAY3C;;;;;;;;OAQG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAgDtD;;;;;;;;OAQG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAiB5C;;;;;;;;OAQG;IACG,oBAAoB,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAY5D;;;;;;;;;OASG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BnD;;;;;;;;;;;;OAYG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkE1C;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAYjC;;;;;;;;;OASG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAiCzE;;;;;;;;;;;;OAYG;IACG,gBAAgB,CACpB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,SAAY,GACf,OAAO,CAAC,MAAM,CAAC;CAoBnB;AAKD;;GAEG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAK1C"}
+{"version":3,"file":"key-manager.d.ts","sourceRoot":"","sources":["../src/key-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAmCH,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,4FAA4F;IAC5F,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,QAAQ,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AASD,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmB;IAChD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IAEtC;;;;;OAKG;gBACS,SAAS,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,gBAAgB;IAY/D;;;;;;;;OAQG;YACW,kBAAkB;IAoEhC;;;;;;;;;;;;OAYG;YACW,WAAW;IAsFzB;;;;;;;;;OASG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BjC;;OAEG;YACW,YAAY;IAU1B;;OAEG;YACW,cAAc;IAa5B;;OAEG;YACW,YAAY;IA6C1B;;;OAGG;IACH,OAAO,CAAC,UAAU;IAIlB;;OAEG;IACH,OAAO,CAAC,cAAc;IAWtB;;OAEG;IACH,OAAO,CAAC,eAAe;IAoCvB;;;;;;;;;;OAUG;IACG,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC,OAAO,CAAC,MAAM,CAAC;IAwElB;;OAEG;IACG,YAAY,CAChB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,OAAO,CAAC,IAAI,CAAC;IAiBhB;;;;;;;;OAQG;IACG,QAAQ,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAY3C;;;;;;;;OAQG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA0DtD;;;;;;;;OAQG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAiB5C;;;;;;;;OAQG;IACG,oBAAoB,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAY5D;;;;;;;;;OASG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BnD;;;;;;;;;;;OAWG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2E1C;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAYjC;;;;;;;;;OASG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IA4CzE;;;;;;;;;;;;OAYG;IACG,gBAAgB,CACpB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,SAAY,GACf,OAAO,CAAC,MAAM,CAAC;CAoBnB;AAKD;;GAEG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAK1C"}

package/dist/key-manager.js

@@ -1,66 +1,46 @@
 /**
- * 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 and metadata 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}`);
+    }
 }
 export class KeyManager {
     configDir;
@@ -69,25 +49,26 @@ export class KeyManager {
     store = null;
     saveLock = null;
     execSecurity;
+    useKeychain;
     /**
      * 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;
+        // Use Keychain on macOS (or when mock execSecurity provided for tests)
+        // Can be overridden via ITERABLE_MCP_FORCE_FILE_STORAGE=true
+        this.useKeychain =
+            (!!execSecurity || process.platform === "darwin") &&
+                process.env.ITERABLE_MCP_FORCE_FILE_STORAGE !== "true";
     }
     /**
-     * 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 +77,8 @@ 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.useKeychain || !this.store || this.store.keys.length === 0) {
             return [];
         }
         const orphanedKeys = [];
@@ -396,15 +378,13 @@ export class KeyManager {
     /**
      * 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 +405,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 +418,30 @@ export class KeyManager {
                 ? { env: envOverrides }
                 : {}),
         };
+        // Store API key
+        if (this.useKeychain) {
+            // macOS: Store in 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)}`);
+            }
+        }
+        else {
+            // Windows/Linux: Store in JSON
+            metadata.apiKey = apiKey;
+        }
         // Store metadata
         this.store.keys.push(metadata);
         await this.saveMetadata();
@@ -499,11 +485,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 +503,40 @@ 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)}`);
+        // Get API key
+        if (this.useKeychain) {
+            // 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)}`);
+            }
         }
-        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}`);
+        else {
+            // Windows/Linux: 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 +545,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 +564,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 +611,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 +637,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.useKeychain) {
+            // 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 +700,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 +717,31 @@ 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;
+                if (this.useKeychain) {
+                    // macOS: Check Keychain
+                    storedKey = await this.execSecurity([
+                        "find-generic-password",
+                        "-a",
+                        keyMeta.id,
+                        "-s",
+                        SERVICE_NAME,
+                        "-w",
+                    ]);
+                }
+                else {
+                    // Windows/Linux: Check JSON
+                    if (!keyMeta.apiKey) {
+                        continue;
+                    }
+                    storedKey = keyMeta.apiKey;
+                }
                 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 +752,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