@memberjunction/encryption 0.0.1 → 2.129.0

package/dist/providers/EnvVarKeySource.js

@@ -0,0 +1,251 @@
+"use strict";
+/**
+ * @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
+ */
+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.EnvVarKeySource = void 0;
+const global_1 = require("@memberjunction/global");
+const EncryptionKeySourceBase_1 = require("../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`);
+ * }
+ * ```
+ */
+let EnvVarKeySource = class EnvVarKeySource extends EncryptionKeySourceBase_1.EncryptionKeySourceBase {
+    /**
+     * Human-readable name for this source.
+     */
+    get SourceName() {
+        return 'Environment Variable';
+    }
+    /**
+     * 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() {
+        // Environment variable source is always valid
+        // Keys are validated at lookup time, not configuration time
+        return true;
+    }
+    /**
+     * 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
+     */
+    async KeyExists(lookupValue) {
+        if (!lookupValue || typeof lookupValue !== 'string') {
+            return false;
+        }
+        // Validate the lookup value format (env var name)
+        if (!this.isValidEnvVarName(lookupValue)) {
+            return false;
+        }
+        return process.env[lookupValue] !== undefined;
+    }
+    /**
+     * 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
+     * ```
+     */
+    async GetKey(lookupValue, keyVersion) {
+        // Validate lookup value
+        if (!lookupValue || typeof lookupValue !== 'string') {
+            throw new Error('Invalid lookup value: environment variable name is required. ' +
+                'Provide the name of the environment variable containing the base64-encoded key.');
+        }
+        // Validate env var name format to prevent injection
+        if (!this.isValidEnvVarName(lookupValue)) {
+            throw new Error(`Invalid environment variable name: "${lookupValue}". ` +
+                'Names must start with a letter or underscore and contain only ' +
+                'letters, numbers, and underscores.');
+        }
+        // Build the full environment variable name
+        // For versions other than '1', append _V{version}
+        const envVarName = this.buildEnvVarName(lookupValue, keyVersion);
+        // Retrieve the value
+        const keyValue = process.env[envVarName];
+        if (keyValue === undefined || keyValue === null) {
+            throw new Error(`Encryption key not found in environment variable: "${envVarName}". ` +
+                'Ensure the environment variable is set with a base64-encoded key value. ' +
+                'Generate a key with: openssl rand -base64 32');
+        }
+        if (keyValue.trim() === '') {
+            throw new Error(`Encryption key in environment variable "${envVarName}" is empty. ` +
+                'The variable must contain a non-empty base64-encoded key value.');
+        }
+        // Decode from base64
+        try {
+            const keyBytes = Buffer.from(keyValue, 'base64');
+            // Verify we got actual bytes (empty buffer check)
+            if (keyBytes.length === 0) {
+                throw new Error('Decoded key is empty');
+            }
+            // Validate it was actually valid base64
+            // by checking the round-trip
+            const roundTrip = keyBytes.toString('base64');
+            const normalized = keyValue.replace(/\s+/g, '');
+            if (roundTrip !== normalized && roundTrip + '=' !== normalized && roundTrip + '==' !== normalized) {
+                // If they don't match, the input wasn't valid base64
+                // (We allow for padding differences)
+                throw new Error('Input does not appear to be valid base64 encoding');
+            }
+            return keyBytes;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`Invalid base64 encoding for encryption key in "${envVarName}". ` +
+                `The value must be a valid base64-encoded string. Error: ${message}. ` +
+                'Generate a valid key with: openssl rand -base64 32');
+        }
+    }
+    /**
+     * 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
+     */
+    buildEnvVarName(baseName, keyVersion) {
+        // No version or version '1' = use base name
+        if (!keyVersion || keyVersion === '1') {
+            return baseName;
+        }
+        // For other versions, append _V{version}
+        return `${baseName}_V${keyVersion}`;
+    }
+    /**
+     * 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
+     */
+    isValidEnvVarName(name) {
+        // Must be non-empty
+        if (!name || name.length === 0) {
+            return false;
+        }
+        // Maximum reasonable length to prevent DoS
+        if (name.length > 256) {
+            return false;
+        }
+        // Standard environment variable naming rules
+        // Must start with letter or underscore
+        // Can contain letters, numbers, underscores
+        const envVarPattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+        return envVarPattern.test(name);
+    }
+};
+exports.EnvVarKeySource = EnvVarKeySource;
+exports.EnvVarKeySource = EnvVarKeySource = __decorate([
+    (0, global_1.RegisterClass)(EncryptionKeySourceBase_1.EncryptionKeySourceBase, 'EnvVarKeySource')
+], EnvVarKeySource);
+//# sourceMappingURL=EnvVarKeySource.js.map

package/dist/providers/EnvVarKeySource.js.map

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

package/package.json

@@ -1,10 +1,69 @@
 {
   "name": "@memberjunction/encryption",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @memberjunction/encryption",
+  "version": "2.129.0",
+  "description": "MemberJunction: Field-level encryption engine with pluggable key sources. Server-side only - provides AES-256-GCM/CBC encryption with environment variable, config file, AWS KMS, and Azure Key Vault key sources.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
+  "author": "MemberJunction.com",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.4.5"
+  },
+  "dependencies": {
+    "@memberjunction/global": "2.129.0",
+    "@memberjunction/core": "2.129.0",
+    "@memberjunction/core-entities": "2.129.0",
+    "@memberjunction/actions-base": "2.129.0",
+    "cosmiconfig": "^9.0.0"
+  },
+  "optionalDependencies": {
+    "@aws-sdk/client-kms": "^3.700.0",
+    "@azure/keyvault-secrets": "^4.9.0",
+    "@azure/identity": "^4.5.0"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-kms": "^3.0.0",
+    "@azure/keyvault-secrets": "^4.0.0",
+    "@azure/identity": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-kms": {
+      "optional": true
+    },
+    "@azure/keyvault-secrets": {
+      "optional": true
+    },
+    "@azure/identity": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/MJ"
+  },
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+    "memberjunction",
+    "encryption",
+    "field-level-encryption",
+    "aes-256-gcm",
+    "security",
+    "aws-kms",
+    "azure-keyvault"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
 }