@memberjunction/encryption 0.0.1 → 2.129.0

package/dist/providers/ConfigFileKeySource.js

@@ -0,0 +1,310 @@
+"use strict";
+/**
+ * @fileoverview Configuration file key source provider.
+ *
+ * This provider retrieves encryption keys from MemberJunction's
+ * configuration file (mj.config.cjs or other cosmiconfig-compatible formats).
+ *
+ * ## Usage
+ *
+ * 1. Add keys to your mj.config.cjs:
+ *    ```javascript
+ *    module.exports = {
+ *      encryptionKeys: {
+ *        pii_master: 'K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=',
+ *        api_secrets: 'aW5kZXhfbmV3X2tleV9mb3JfdjJfcm90YXRpb24='
+ *      }
+ *    };
+ *    ```
+ *
+ * 2. Configure in database with:
+ *    - EncryptionKeySourceID pointing to 'Configuration File' source
+ *    - KeyLookupValue = 'pii_master' (the key name in the config)
+ *
+ * ## Key Format
+ *
+ * Keys must be base64-encoded strings. Generate with:
+ * ```bash
+ * openssl rand -base64 32  # For AES-256
+ * openssl rand -base64 16  # For AES-128
+ * ```
+ *
+ * ## Security Considerations
+ *
+ * - Config files should have restricted file permissions (600 or 640)
+ * - Don't commit config files with keys to source control
+ * - Consider using .gitignore for mj.config.cjs
+ * - For production, prefer environment variables or secrets managers
+ *
+ * ## Key Rotation
+ *
+ * Add the new key with a versioned name:
+ * ```javascript
+ * encryptionKeys: {
+ *   pii_master: '<current-key>',
+ *   pii_master_v2: '<new-key>'
+ * }
+ * ```
+ *
+ * @module @memberjunction/encryption
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigFileKeySource = void 0;
+const global_1 = require("@memberjunction/global");
+const EncryptionKeySourceBase_1 = require("../EncryptionKeySourceBase");
+/**
+ * Encryption key source that retrieves keys from configuration files.
+ *
+ * Uses cosmiconfig to locate configuration in standard locations:
+ * - mj.config.cjs (recommended)
+ * - mj.config.js
+ * - .mjrc.json
+ * - .mjrc.yaml
+ *
+ * Keys are read from the `encryptionKeys` section of the configuration.
+ *
+ * @example
+ * ```typescript
+ * // Configuration file (mj.config.cjs):
+ * module.exports = {
+ *   encryptionKeys: {
+ *     pii_master: 'base64-encoded-key-here',
+ *     financial_data: 'another-base64-key'
+ *   }
+ * };
+ *
+ * // Usage (typically automatic via ClassFactory):
+ * const source = new ConfigFileKeySource();
+ * await source.Initialize(); // Load the config file
+ *
+ * const key = await source.GetKey('pii_master');
+ * ```
+ */
+let ConfigFileKeySource = class ConfigFileKeySource extends EncryptionKeySourceBase_1.EncryptionKeySourceBase {
+    /**
+     * Loaded configuration from the config file.
+     * Set during Initialize(), null if not yet loaded.
+     *
+     * @private
+     */
+    _loadedConfig = null;
+    /**
+     * Path to the loaded config file (for error messages).
+     *
+     * @private
+     */
+    _configFilePath = null;
+    /**
+     * Human-readable name for this source.
+     */
+    get SourceName() {
+        return 'Configuration File';
+    }
+    /**
+     * Initializes the key source by loading the configuration file.
+     *
+     * Uses cosmiconfig to search for configuration in standard locations.
+     * Must be called before any key operations.
+     *
+     * @throws Error if cosmiconfig module cannot be loaded
+     */
+    async Initialize() {
+        try {
+            // Dynamic import to avoid bundling cosmiconfig if not used
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { cosmiconfigSync } = require('cosmiconfig');
+            const explorer = cosmiconfigSync('mj', {
+                searchStrategy: 'global'
+            });
+            const result = explorer.search();
+            if (result?.config?.encryptionKeys) {
+                const keys = result.config.encryptionKeys;
+                // Validate that encryptionKeys is an object with string values
+                if (typeof keys !== 'object' || keys === null) {
+                    throw new Error('Invalid encryptionKeys configuration: expected an object with string values');
+                }
+                // Type check all values
+                for (const [keyName, keyValue] of Object.entries(keys)) {
+                    if (typeof keyValue !== 'string') {
+                        throw new Error(`Invalid key "${keyName}" in encryptionKeys: ` +
+                            `expected base64 string, got ${typeof keyValue}`);
+                    }
+                }
+                this._loadedConfig = keys;
+                this._configFilePath = result.filepath;
+            }
+        }
+        catch (err) {
+            // If cosmiconfig is not available or fails, log but don't crash
+            // The ValidateConfiguration check will fail appropriately
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`ConfigFileKeySource: Failed to load configuration: ${message}`);
+        }
+    }
+    /**
+     * Validates that the configuration file was loaded successfully.
+     *
+     * @returns `true` if the config file was loaded and contains encryptionKeys
+     */
+    ValidateConfiguration() {
+        return this._loadedConfig !== null;
+    }
+    /**
+     * Checks if a key exists in the configuration file.
+     *
+     * @param lookupValue - The key name to check
+     * @returns Promise resolving to `true` if the key exists
+     */
+    async KeyExists(lookupValue) {
+        if (!this._loadedConfig) {
+            return false;
+        }
+        if (!lookupValue || typeof lookupValue !== 'string') {
+            return false;
+        }
+        // Validate key name format
+        if (!this.isValidKeyName(lookupValue)) {
+            return false;
+        }
+        return this._loadedConfig[lookupValue] !== undefined;
+    }
+    /**
+     * Retrieves key material from the configuration file.
+     *
+     * Keys should be stored as base64-encoded strings in the encryptionKeys
+     * section of the configuration file.
+     *
+     * For versioned keys, the version is appended with an underscore:
+     * - `key_name` for version 1 (default)
+     * - `key_name_v2` for version 2
+     *
+     * @param lookupValue - The key name in the configuration
+     * @param keyVersion - Optional version number (defaults to '1')
+     * @returns Promise resolving to the decoded key bytes
+     *
+     * @throws Error if Initialize() was not called
+     * @throws Error if the key is not found
+     * @throws Error if the value is not valid base64
+     *
+     * @example
+     * ```typescript
+     * // Config file has: encryptionKeys: { pii_master: '...' }
+     * const key = await source.GetKey('pii_master');
+     *
+     * // For versioned keys during rotation:
+     * // Config has: pii_master, pii_master_v2
+     * const newKey = await source.GetKey('pii_master', '2');
+     * ```
+     */
+    async GetKey(lookupValue, keyVersion) {
+        // Check if initialized
+        if (!this._loadedConfig) {
+            const configPath = this._configFilePath || 'mj.config.cjs';
+            throw new Error(`Configuration file not loaded. Ensure Initialize() was called and ` +
+                `the configuration file (${configPath}) exists with an "encryptionKeys" section. ` +
+                `Example:\n` +
+                `module.exports = {\n` +
+                `  encryptionKeys: {\n` +
+                `    your_key_name: 'base64-encoded-key'\n` +
+                `  }\n` +
+                `};`);
+        }
+        // Validate lookup value
+        if (!lookupValue || typeof lookupValue !== 'string') {
+            throw new Error('Invalid lookup value: key name is required. ' +
+                'Provide the name of the key as defined in the encryptionKeys section.');
+        }
+        // Validate key name format
+        if (!this.isValidKeyName(lookupValue)) {
+            throw new Error(`Invalid key name: "${lookupValue}". ` +
+                'Key names must start with a letter or underscore and contain only ' +
+                'letters, numbers, and underscores.');
+        }
+        // Build the full key name with version
+        const keyName = this.buildKeyName(lookupValue, keyVersion);
+        // Retrieve the value
+        const keyValue = this._loadedConfig[keyName];
+        if (keyValue === undefined || keyValue === null) {
+            throw new Error(`Encryption key "${keyName}" not found in configuration file. ` +
+                `Add it to the "encryptionKeys" section of ${this._configFilePath || 'mj.config.cjs'}. ` +
+                `Example:\n` +
+                `encryptionKeys: {\n` +
+                `  "${keyName}": "base64-encoded-key"\n` +
+                `}\n\n` +
+                `Generate a key with: openssl rand -base64 32`);
+        }
+        if (keyValue.trim() === '') {
+            throw new Error(`Encryption key "${keyName}" in configuration file is empty. ` +
+                'The value must be a non-empty base64-encoded key.');
+        }
+        // Decode from base64
+        try {
+            const keyBytes = Buffer.from(keyValue, 'base64');
+            if (keyBytes.length === 0) {
+                throw new Error('Decoded key is empty');
+            }
+            return keyBytes;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`Invalid base64 encoding for key "${keyName}" in configuration file. ` +
+                `The value must be a valid base64-encoded string. Error: ${message}. ` +
+                'Generate a valid key with: openssl rand -base64 32');
+        }
+    }
+    /**
+     * Cleans up resources (no-op for config file source).
+     */
+    async Dispose() {
+        this._loadedConfig = null;
+        this._configFilePath = null;
+    }
+    /**
+     * Builds the full key name with optional version suffix.
+     *
+     * @param baseName - The base key name
+     * @param keyVersion - Optional version number
+     * @returns The full key name
+     *
+     * @private
+     */
+    buildKeyName(baseName, keyVersion) {
+        // No version or version '1' = use base name
+        if (!keyVersion || keyVersion === '1') {
+            return baseName;
+        }
+        // For other versions, append _v{version} (lowercase for config files)
+        return `${baseName}_v${keyVersion}`;
+    }
+    /**
+     * Validates that a string is a valid configuration key name.
+     *
+     * @param name - The name to validate
+     * @returns `true` if the name is valid
+     *
+     * @private
+     */
+    isValidKeyName(name) {
+        if (!name || name.length === 0) {
+            return false;
+        }
+        if (name.length > 256) {
+            return false;
+        }
+        // Allow alphanumeric, underscores, and hyphens
+        // Must start with letter or underscore
+        const keyNamePattern = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+        return keyNamePattern.test(name);
+    }
+};
+exports.ConfigFileKeySource = ConfigFileKeySource;
+exports.ConfigFileKeySource = ConfigFileKeySource = __decorate([
+    (0, global_1.RegisterClass)(EncryptionKeySourceBase_1.EncryptionKeySourceBase, 'ConfigFileKeySource')
+], ConfigFileKeySource);
+//# sourceMappingURL=ConfigFileKeySource.js.map

package/dist/providers/ConfigFileKeySource.js.map

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

package/dist/providers/EnvVarKeySource.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Environment variable key source provider.
+ *
+ * This provider retrieves encryption keys from environment variables.
+ * It's the simplest and most commonly used key source for development
+ * and containerized deployments.
+ *
+ * ## Usage
+ *
+ * 1. Generate a key: `openssl rand -base64 32`
+ * 2. Set environment variable: `export MJ_ENCRYPTION_KEY_PII="<base64-key>"`
+ * 3. Configure in database with KeyLookupValue = 'MJ_ENCRYPTION_KEY_PII'
+ *
+ * ## Key Format
+ *
+ * Keys must be base64-encoded. For AES-256, generate with:
+ * ```bash
+ * openssl rand -base64 32
+ * ```
+ *
+ * For AES-128:
+ * ```bash
+ * openssl rand -base64 16
+ * ```
+ *
+ * ## Key Rotation
+ *
+ * During rotation, store the new key in a separate variable:
+ * ```bash
+ * export MJ_ENCRYPTION_KEY_PII="<current-key>"
+ * export MJ_ENCRYPTION_KEY_PII_NEW="<new-key>"
+ * ```
+ *
+ * After rotation completes, remove the old key and optionally
+ * rename the new key to the original variable name.
+ *
+ * ## Security Considerations
+ *
+ * - Environment variables may be logged or visible to child processes
+ * - Consider using secrets managers for production deployments
+ * - Ensure proper access controls on the runtime environment
+ * - Never commit keys to source control
+ *
+ * @module @memberjunction/encryption
+ */
+/// <reference types="node" />
+import { EncryptionKeySourceBase } from '../EncryptionKeySourceBase';
+/**
+ * Encryption key source that retrieves keys from environment variables.
+ *
+ * This is the default and recommended key source for:
+ * - Development environments
+ * - Docker/Kubernetes deployments with secret injection
+ * - Serverless functions with environment configuration
+ *
+ * Keys are expected to be base64-encoded strings in the environment.
+ * The provider decodes them to raw bytes for crypto operations.
+ *
+ * @example
+ * ```typescript
+ * // The provider is automatically instantiated by ClassFactory
+ * // based on database configuration. For manual usage:
+ *
+ * import { EnvVarKeySource } from '@memberjunction/encryption';
+ *
+ * const source = new EnvVarKeySource();
+ *
+ * // Check if key exists
+ * if (await source.KeyExists('MJ_ENCRYPTION_KEY_PII')) {
+ *   const keyBytes = await source.GetKey('MJ_ENCRYPTION_KEY_PII');
+ *   console.log(`Key length: ${keyBytes.length} bytes`);
+ * }
+ * ```
+ */
+export declare class EnvVarKeySource extends EncryptionKeySourceBase {
+    /**
+     * Human-readable name for this source.
+     */
+    get SourceName(): string;
+    /**
+     * Validates the source configuration.
+     *
+     * For environment variables, configuration is always valid as
+     * keys are validated at lookup time. This allows the source
+     * to be used dynamically for any environment variable.
+     *
+     * @returns Always returns `true`
+     */
+    ValidateConfiguration(): boolean;
+    /**
+     * Checks if an environment variable containing a key exists.
+     *
+     * @param lookupValue - The environment variable name to check
+     * @returns Promise resolving to `true` if the variable is defined
+     */
+    KeyExists(lookupValue: string): Promise<boolean>;
+    /**
+     * Retrieves key material from an environment variable.
+     *
+     * The environment variable should contain a base64-encoded key.
+     * For versioned keys, the version is appended with an underscore:
+     * - `KEY_NAME` for version 1 (default)
+     * - `KEY_NAME_V2` for version 2
+     * - etc.
+     *
+     * @param lookupValue - The environment variable name
+     * @param keyVersion - Optional version number (defaults to '1')
+     * @returns Promise resolving to the decoded key bytes
+     *
+     * @throws Error if the environment variable is not set
+     * @throws Error if the value is not valid base64
+     *
+     * @example
+     * ```typescript
+     * // Get current key
+     * const key = await source.GetKey('MJ_ENCRYPTION_KEY_PII');
+     *
+     * // Get specific version during rotation
+     * const oldKey = await source.GetKey('MJ_ENCRYPTION_KEY_PII', '1');
+     * const newKey = await source.GetKey('MJ_ENCRYPTION_KEY_PII', '2');
+     * // The above looks for MJ_ENCRYPTION_KEY_PII_V2
+     * ```
+     */
+    GetKey(lookupValue: string, keyVersion?: string): Promise<Buffer>;
+    /**
+     * Builds the full environment variable name with optional version suffix.
+     *
+     * @param baseName - The base environment variable name
+     * @param keyVersion - Optional version number
+     * @returns The full environment variable name
+     *
+     * @private
+     */
+    private buildEnvVarName;
+    /**
+     * Validates that a string is a valid environment variable name.
+     *
+     * Valid names:
+     * - Start with a letter (A-Z, a-z) or underscore (_)
+     * - Contain only letters, numbers, and underscores
+     *
+     * This prevents injection attacks where malicious lookupValues
+     * could be crafted to access unintended variables.
+     *
+     * @param name - The name to validate
+     * @returns `true` if the name is valid
+     *
+     * @private
+     */
+    private isValidEnvVarName;
+}
+//# sourceMappingURL=EnvVarKeySource.d.ts.map

package/dist/providers/EnvVarKeySource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnvVarKeySource.d.ts","sourceRoot":"","sources":["../../src/providers/EnvVarKeySource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;;AAGH,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBACa,eAAgB,SAAQ,uBAAuB;IACxD;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;;;;;OAQG;IACH,qBAAqB,IAAI,OAAO;IAMhC;;;;;OAKG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAatD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAsEvE;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAUvB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,iBAAiB;CAiB5B"}