@iterable/mcp 1.0.3 → 1.2.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 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)
  */
 export type SecurityExecutor = (args: string[]) => Promise<string>;
 export interface ApiKeyMetadata {
@@ -35,6 +30,10 @@ 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;
+    /** Encrypted API key (Windows DPAPI) */
+    encryptedApiKey?: string;
 }
 export declare class KeyManager {
     private readonly configDir;
@@ -43,16 +42,16 @@ export declare class KeyManager {
     private store;
     private saveLock;
     private readonly execSecurity;
+    private readonly 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?: 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.
@@ -111,18 +110,43 @@ export declare class KeyManager {
      * Validate and normalize base URL
      */
     private validateBaseUrl;
+    /**
+     * 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
+     */
+    private encryptWindows;
+    /**
+     * 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
+     */
+    private decryptWindows;
     /**
      * 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 +166,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 +180,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 +207,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 +229,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 +242,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":"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"}