@iterable/cli 0.1.0

package/dist/key-manager.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Secure API Key Management with cross-platform support
+ *
+ * This module provides secure storage and management of multiple Iterable API keys.
+ *
+ * Storage Strategy:
+ * - macOS: API keys in Keychain, metadata in ~/.iterable/keys.json
+ * - Windows: API keys encrypted with DPAPI in ~/.iterable/keys.json
+ * - Linux: API keys and metadata in ~/.iterable/keys.json (mode 0o600)
+ * - Lock file: ~/.iterable/keys.lock prevents concurrent modifications
+ *
+ * Security Features:
+ * - API key format validation (32-char lowercase hex)
+ * - 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 {
+    /** Unique identifier for this key */
+    id: string;
+    /** User-friendly name for this key */
+    name: string;
+    /** Iterable API base URL (e.g., https://api.iterable.com or https://api.eu.iterable.com) */
+    baseUrl: string;
+    /** ISO timestamp when key was created */
+    created: string;
+    /** ISO timestamp when key was last updated */
+    updated?: string;
+    /** Whether this is the currently active key */
+    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;
+    private readonly metadataFile;
+    private readonly lockFile;
+    private store;
+    private saveLock;
+    private readonly execSecurity;
+    private readonly storageMethod;
+    /**
+     * Create a new KeyManager instance
+     *
+     * @param configDir - Optional custom config directory (defaults to ~/.iterable)
+     * @param execSecurity - Optional security command executor (for dependency injection in tests)
+     */
+    constructor(configDir?: string, execSecurity?: SecurityExecutor);
+    /**
+     * 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.
+     * This prevents sync issues when keychain entries are manually deleted.
+     *
+     * @returns Array of cleaned up key names (if any)
+     */
+    private validateAndCleanup;
+    /**
+     * Acquire an exclusive lock for metadata operations
+     *
+     * Uses atomic file creation (wx flag = O_CREAT | O_EXCL) to prevent concurrent
+     * modifications. Retries up to 20 times with 50ms delays (1 second total).
+     * Fails safely if lock cannot be acquired rather than forcefully stealing it.
+     *
+     * Lock contention is rare since writes only happen during explicit user operations
+     * (add, delete, activate keys) - no automatic updates.
+     *
+     * @returns An async unlock function that should be called in a finally block
+     * @throws {Error} If lock cannot be acquired after 1 second timeout
+     */
+    private acquireLock;
+    /**
+     * Initialize the key manager
+     *
+     * Creates the configuration directory (mode 0o700) and loads existing metadata.
+     * If the metadata file doesn't exist, creates a new empty store.
+     * Uses idiomatic Node.js approach: try to read, handle ENOENT if file missing.
+     * This method must be called before any other key management operations.
+     *
+     * @throws {Error} If the configuration directory cannot be created or metadata is corrupt
+     */
+    initialize(): Promise<void>;
+    /**
+     * Load metadata from disk (with locking)
+     */
+    private loadMetadata;
+    /**
+     * Create a backup of the metadata file before destructive operations
+     */
+    private backupMetadata;
+    /**
+     * Save metadata to disk (with locking to prevent concurrent modifications)
+     */
+    private saveMetadata;
+    /**
+     * Generate a unique ID for a key
+     * Uses UUID v4 for guaranteed uniqueness and no collision risk
+     */
+    private generateId;
+    /**
+     * Validate API key format
+     */
+    private validateApiKey;
+    /**
+     * 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;
+    /**
+     * Save (add or update) an API key
+     *
+     * Private implementation that handles both add and update operations.
+     * If idOrName is provided, updates an existing key. Otherwise, adds a new key.
+     *
+     * @param name - User-friendly name for the key
+     * @param apiKey - The Iterable API key value
+     * @param baseUrl - Iterable API base URL
+     * @param envOverrides - Environment variable overrides. If undefined, keeps existing env (update) or no env (add). If provided (even empty {}), replaces/clears env.
+     * @param idOrName - If provided, updates the existing key with this ID or name
+     * @returns The ID of the saved key
+     */
+    private saveKey;
+    /**
+     * Add a new API key
+     *
+     * Stores an API key securely (Keychain on macOS, encrypted on Windows, file on Linux).
+     *
+     * @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)
+     * @param envOverrides - Optional environment variable overrides for this key
+     * @returns The unique ID generated for this key
+     * @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>;
+    /**
+     * Update an existing API key
+     *
+     * Updates all properties of an existing key including name, API key value, base URL, and environment overrides.
+     *
+     * @param idOrName - The unique ID or name of the key to update
+     * @param name - New name for the key (must be unique unless unchanged)
+     * @param apiKey - New API key value (can be the same as existing)
+     * @param baseUrl - New Iterable API base URL
+     * @param envOverrides - New environment variable overrides (undefined = keep existing, {} = clear)
+     * @returns The ID of the updated key
+     * @throws {Error} If the key is not found, name conflict, validation fails, or storage fails
+     */
+    updateKey(idOrName: string, name: string, apiKey: string, baseUrl: string, envOverrides?: Record<string, string>): Promise<string>;
+    /**
+     * List all keys (metadata only, not the actual keys)
+     *
+     * Returns metadata for all stored API keys including names, IDs, base URLs,
+     * timestamps, and active status. Does NOT return the actual API key values.
+     *
+     * @returns Array of API key metadata
+     * @throws {Error} If the key store is not initialized
+     */
+    listKeys(): Promise<ApiKeyMetadata[]>;
+    /**
+     * Get key metadata by ID
+     *
+     * @param idOrName - The unique ID or user-friendly name of the key
+     * @returns The key metadata, or null if not found
+     */
+    getKeyMetadata(idOrName: string): Promise<ApiKeyMetadata | null>;
+    /**
+     * Get a key by ID or name
+     *
+     * 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 storage access fails
+     */
+    getKey(idOrName: string): Promise<string | null>;
+    /**
+     * Get the currently active key
+     *
+     * Retrieves the API key value for whichever key is currently marked as active.
+     * 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 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.
+     *
+     * @returns The active key metadata, or null if no key is active
+     * @throws {Error} If the key store is not initialized
+     */
+    getActiveKeyMetadata(): Promise<ApiKeyMetadata | null>;
+    /**
+     * Set a key as active by ID or name
+     *
+     * Marks the specified key as active and deactivates all other keys.
+     * The active key's base URL and API key will be used by the CLI.
+     * Only one key can be active at a time.
+     *
+     * @param idOrName - The unique ID or user-friendly name of the key to activate
+     * @throws {Error} If the key is not found or the store is not initialized
+     */
+    setActiveKey(idOrName: string): Promise<void>;
+    /**
+     * Delete a key by ID
+     *
+     * Removes a key from storage and the metadata store.
+     * Note: Only accepts key ID (not name) since IDs are guaranteed unique.
+     *
+     * @param id - The unique ID of the key to delete
+     * @throws {Error} If the key is not found or the store is not initialized
+     */
+    deleteKey(id: string): Promise<void>;
+    /**
+     * Check if any keys exist
+     *
+     * Returns true if at least one API key has been stored in the key manager.
+     *
+     * @returns True if keys exist, false otherwise
+     * @throws {Error} If the key store is not initialized
+     */
+    hasKeys(): Promise<boolean>;
+    /** Check if any key is currently marked as active (metadata only, no keychain call). */
+    hasActiveKey(): Promise<boolean>;
+    /** Deactivate all keys (no key will be active). */
+    deactivateAllKeys(): Promise<void>;
+    /**
+     * Find a key by its actual API key value
+     *
+     * 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 storage access fails
+     */
+    findKeyByValue(apiKeyValue: string): Promise<ApiKeyMetadata | null>;
+}
+/**
+ * Get the singleton KeyManager instance
+ */
+export declare function getKeyManager(): KeyManager;
+//# sourceMappingURL=key-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"key-manager.d.ts","sourceRoot":"","sources":["../src/key-manager.ts"],"names":[],"mappings":"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"}