@memberjunction/encryption 0.0.1 → 2.130.0

package/dist/EncryptionEngine.d.ts

@@ -0,0 +1,351 @@
+/**
+ * @fileoverview Core encryption engine for MemberJunction field-level encryption.
+ *
+ * The EncryptionEngine is the central class for all encryption and decryption
+ * operations. It provides:
+ *
+ * - AES-256-GCM/CBC encryption with authenticated encryption support
+ * - Pluggable key sources via the ClassFactory pattern
+ * - Multi-level caching for performance (inherited from EncryptionEngineBase)
+ * - Self-describing encrypted value format
+ * - Key rotation support with explicit lookup overrides
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { EncryptionEngine } from '@memberjunction/encryption';
+ *
+ * // First, configure the engine to load metadata
+ * await EncryptionEngine.Instance.Config(false, contextUser);
+ *
+ * // Encrypt a value
+ * const encrypted = await EncryptionEngine.Instance.Encrypt(
+ *   'sensitive-data',
+ *   encryptionKeyId,
+ *   contextUser
+ * );
+ *
+ * // Decrypt a value
+ * const decrypted = await EncryptionEngine.Instance.Decrypt(encrypted, contextUser);
+ *
+ * // Check if a value is encrypted
+ * if (EncryptionEngine.Instance.IsEncrypted(someValue)) {
+ *   // Handle encrypted value
+ * }
+ * ```
+ *
+ * ## Security Design
+ *
+ * - Keys are never stored in memory longer than needed
+ * - Authenticated encryption (GCM) prevents tampering
+ * - Random IVs for each encryption operation
+ * - Self-describing format enables proper key lookup
+ * - Secure defaults (fail-safe on errors)
+ *
+ * @module @memberjunction/encryption
+ */
+/// <reference types="node" />
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { EncryptionEngineBase } from '@memberjunction/core-entities';
+import { EncryptedValueParts } from './interfaces';
+/**
+ * Core encryption engine for field-level encryption operations.
+ *
+ * This class extends EncryptionEngineBase to inherit metadata caching for
+ * encryption keys, algorithms, and key sources. It adds the actual
+ * encryption/decryption operations using Node.js crypto.
+ *
+ * Use `EncryptionEngine.Instance` to access the singleton.
+ *
+ * ## Thread Safety
+ *
+ * The engine is designed to be safe for concurrent use in async contexts.
+ * Cache operations are atomic Map operations and crypto operations
+ * use per-call state.
+ *
+ * ## Error Handling
+ *
+ * The engine throws descriptive errors for:
+ * - Missing keys or configurations
+ * - Invalid encrypted value format
+ * - Decryption failures (including auth tag mismatch)
+ * - Key length mismatches
+ *
+ * Callers should catch and handle errors appropriately.
+ */
+export declare class EncryptionEngine extends EncryptionEngineBase {
+    /**
+     * Cache for decrypted key material.
+     * Maps 'keyId:version' to Buffer.
+     * This is separate from the base class caches since key material
+     * is sensitive and needs different handling.
+     *
+     * @private
+     */
+    private _keyMaterialCache;
+    /**
+     * Cache for initialized key source instances.
+     * Maps driver class name to provider instance.
+     *
+     * @private
+     */
+    private _keySourceCache;
+    /**
+     * Cache TTL for key material in milliseconds.
+     * Can be configured for testing or specific deployment needs.
+     *
+     * @private
+     */
+    private readonly _keyMaterialCacheTtlMs;
+    /**
+     * Gets the singleton instance of the encryption engine.
+     *
+     * The instance is created on first access and reused thereafter.
+     *
+     * @example
+     * ```typescript
+     * const engine = EncryptionEngine.Instance;
+     * await engine.Config(false, contextUser);
+     * const encrypted = await engine.Encrypt(data, keyId, contextUser);
+     * ```
+     */
+    static get Instance(): EncryptionEngine;
+    /**
+     * Configures the engine by loading encryption metadata from the database.
+     *
+     * This overrides the base Config to ensure proper initialization.
+     * Must be called before performing encryption/decryption operations.
+     *
+     * @param forceRefresh - If true, reloads data even if already loaded
+     * @param contextUser - User context for database access (required server-side)
+     * @param provider - Optional metadata provider override
+     */
+    Config(forceRefresh?: boolean, contextUser?: UserInfo, provider?: IMetadataProvider): Promise<void>;
+    /**
+     * Encrypts a value using the specified encryption key.
+     *
+     * The method:
+     * 1. Gets the key configuration from cached metadata
+     * 2. Retrieves key material from the configured source (cached)
+     * 3. Generates a random IV
+     * 4. Encrypts the data using the configured algorithm
+     * 5. Returns a self-describing encrypted string
+     *
+     * ## Encrypted Format
+     *
+     * The result format is:
+     * `$ENC$<keyId>$<algorithm>$<iv>$<ciphertext>[$<authTag>]`
+     *
+     * This format contains all information needed for decryption.
+     *
+     * @param plaintext - The value to encrypt (string or Buffer)
+     * @param encryptionKeyId - UUID of the encryption key to use
+     * @param contextUser - User context for database access
+     * @returns The encrypted value as a string
+     *
+     * @throws Error if the key cannot be found or is invalid
+     * @throws Error if key material retrieval fails
+     *
+     * @example
+     * ```typescript
+     * const encrypted = await engine.Encrypt(
+     *   'secret-api-key',
+     *   '550e8400-e29b-41d4-a716-446655440000',
+     *   currentUser
+     * );
+     * // Returns: $ENC$550e8400-....$AES-256-GCM$<iv>$<ciphertext>$<authTag>
+     * ```
+     */
+    Encrypt(plaintext: string | Buffer, encryptionKeyId: string, contextUser?: UserInfo): Promise<string>;
+    /**
+     * Decrypts an encrypted value.
+     *
+     * If the value is not encrypted (doesn't start with marker), returns it unchanged.
+     *
+     * The method:
+     * 1. Parses the encrypted value to extract key ID and parameters
+     * 2. Gets the key configuration from cached metadata
+     * 3. Retrieves key material from the configured source (cached)
+     * 4. Decrypts using the algorithm and IV from the encrypted value
+     * 5. Verifies the auth tag for AEAD algorithms
+     *
+     * @param value - The value to decrypt (may or may not be encrypted)
+     * @param contextUser - User context for database access
+     * @returns The decrypted plaintext, or original value if not encrypted
+     *
+     * @throws Error if decryption fails (invalid key, corrupted data, auth tag mismatch)
+     *
+     * @example
+     * ```typescript
+     * // Decrypt an encrypted value
+     * const plaintext = await engine.Decrypt(encryptedValue, contextUser);
+     *
+     * // Non-encrypted values pass through unchanged
+     * const same = await engine.Decrypt('plain-text', contextUser);
+     * // Returns: 'plain-text'
+     * ```
+     */
+    Decrypt(value: string, contextUser?: UserInfo): Promise<string>;
+    /**
+     * Checks if a value is encrypted.
+     *
+     * Encrypted values start with the marker prefix (default: '$ENC$').
+     * This also checks for the encrypted sentinel value.
+     * This is a fast, synchronous check that doesn't require database access.
+     *
+     * @param value - The value to check
+     * @param encryptionMarker - Optional custom marker to check for (defaults to '$ENC$')
+     * @returns `true` if the value appears to be encrypted or is the sentinel value
+     *
+     * @example
+     * ```typescript
+     * if (engine.IsEncrypted(fieldValue)) {
+     *   const decrypted = await engine.Decrypt(fieldValue, user);
+     * }
+     *
+     * // With custom marker from key
+     * const key = engine.GetKeyByID(keyId);
+     * if (engine.IsEncrypted(fieldValue, key?.Marker)) {
+     *   const decrypted = await engine.Decrypt(fieldValue, user);
+     * }
+     * ```
+     */
+    IsEncrypted(value: unknown, encryptionMarker?: string): boolean;
+    /**
+     * Parses an encrypted value string into its component parts.
+     *
+     * Use this when you need to inspect the encrypted value without decrypting.
+     *
+     * @param value - The encrypted value string
+     * @returns Parsed components (marker, keyId, algorithm, iv, ciphertext, authTag)
+     *
+     * @throws Error if the format is invalid
+     *
+     * @example
+     * ```typescript
+     * const parts = engine.ParseEncryptedValue(encryptedValue);
+     * console.log(`Encrypted with key: ${parts.keyId}`);
+     * console.log(`Algorithm: ${parts.algorithm}`);
+     * ```
+     */
+    ParseEncryptedValue(value: string): EncryptedValueParts;
+    /**
+     * Validates that key material is accessible at a given lookup value.
+     *
+     * Used before key rotation to verify the new key exists and is valid.
+     * This prevents starting a rotation that would fail mid-way.
+     *
+     * @param lookupValue - The key source lookup value to validate
+     * @param encryptionKeyId - The key ID (to get source configuration)
+     * @param contextUser - User context for database access
+     *
+     * @throws Error if the key material cannot be accessed or is invalid
+     *
+     * @example
+     * ```typescript
+     * // Before rotation, validate the new key is ready
+     * await engine.ValidateKeyMaterial(
+     *   'MJ_ENCRYPTION_KEY_PII_NEW',
+     *   existingKeyId,
+     *   contextUser
+     * );
+     * // If no error, safe to proceed with rotation
+     * ```
+     */
+    ValidateKeyMaterial(lookupValue: string, encryptionKeyId: string, contextUser?: UserInfo): Promise<void>;
+    /**
+     * Encrypts a value using a specific key lookup (for key rotation).
+     *
+     * During key rotation, we need to encrypt with the new key material
+     * before updating the key metadata. This method allows specifying
+     * an alternate lookup value for the key material.
+     *
+     * @param plaintext - The value to encrypt
+     * @param encryptionKeyId - The key ID (for algorithm/marker config)
+     * @param keyLookupValue - Alternate lookup value for key material
+     * @param contextUser - User context for database access
+     * @returns The encrypted value string
+     *
+     * @example
+     * ```typescript
+     * // During rotation, encrypt with new key before metadata update
+     * const newEncrypted = await engine.EncryptWithLookup(
+     *   decryptedData,
+     *   keyId,
+     *   'MJ_ENCRYPTION_KEY_PII_NEW',
+     *   contextUser
+     * );
+     * ```
+     */
+    EncryptWithLookup(plaintext: string | Buffer, encryptionKeyId: string, keyLookupValue: string, contextUser?: UserInfo): Promise<string>;
+    /**
+     * Clears key material and source caches.
+     *
+     * Call after key rotation or configuration changes to ensure
+     * fresh data is loaded. The base class metadata caches are
+     * handled separately via RefreshAllItems().
+     */
+    ClearCaches(): void;
+    /**
+     * Clears all caches including base class metadata caches.
+     *
+     * This is more aggressive than ClearCaches() and should be used
+     * when you need to completely refresh all cached data.
+     */
+    ClearAllCaches(): Promise<void>;
+    /**
+     * Ensures the engine is configured before operations.
+     *
+     * @private
+     */
+    private ensureConfigured;
+    /**
+     * Builds a KeyConfiguration object from the cached metadata.
+     *
+     * @private
+     */
+    private buildKeyConfiguration;
+    /**
+     * Performs the actual encryption operation.
+     *
+     * @private
+     */
+    private performEncryption;
+    /**
+     * Performs the actual decryption operation.
+     *
+     * @private
+     */
+    private performDecryption;
+    /**
+     * Gets key material from cache or source.
+     *
+     * @private
+     */
+    private getKeyMaterial;
+    /**
+     * Gets key material using an overridden lookup value (for rotation).
+     *
+     * @private
+     */
+    private getKeyMaterialWithLookup;
+    /**
+     * Gets or creates a key source instance.
+     *
+     * @private
+     */
+    private getOrCreateKeySource;
+    /**
+     * Validates that key material has the correct length for the algorithm.
+     *
+     * @private
+     */
+    private validateKeyLength;
+    /**
+     * Validates that a string is a valid UUID.
+     *
+     * @private
+     */
+    private isValidUUID;
+}
+//# sourceMappingURL=EncryptionEngine.d.ts.map

package/dist/EncryptionEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EncryptionEngine.d.ts","sourceRoot":"","sources":["../src/EncryptionEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;;AAIH,OAAO,EAAE,iBAAiB,EAAY,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAErE,OAAO,EACH,mBAAmB,EAEtB,MAAM,cAAc,CAAC;AAkBtB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,gBAAiB,SAAQ,oBAAoB;IACtD;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB,CAA8C;IAEvE;;;;;OAKG;IACH,OAAO,CAAC,eAAe,CAAmD;IAE1E;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAA6C;IAEpF;;;;;;;;;;;OAWG;IACH,WAA2B,QAAQ,IAAI,gBAAgB,CAEtD;IAED;;;;;;;;;OASG;IACmB,MAAM,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,OAAO,CACT,SAAS,EAAE,MAAM,GAAG,MAAM,EAC1B,eAAe,EAAE,MAAM,EACvB,WAAW,CAAC,EAAE,QAAQ,GACvB,OAAO,CAAC,MAAM,CAAC;IA2BlB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,OAAO,CACT,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,QAAQ,GACvB,OAAO,CAAC,MAAM,CAAC;IAsBlB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO;IAI/D;;;;;;;;;;;;;;;;OAgBG;IACH,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB;IA2CvD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,mBAAmB,CACrB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,WAAW,CAAC,EAAE,QAAQ,GACvB,OAAO,CAAC,IAAI,CAAC;IA+BhB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,iBAAiB,CACnB,SAAS,EAAE,MAAM,GAAG,MAAM,EAC1B,eAAe,EAAE,MAAM,EACvB,cAAc,EAAE,MAAM,EACtB,WAAW,CAAC,EAAE,QAAQ,GACvB,OAAO,CAAC,MAAM,CAAC;IAsBlB;;;;;;OAMG;IACH,WAAW,IAAI,IAAI;IAKnB;;;;;OAKG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IASrC;;;;OAIG;YACW,gBAAgB;IAM9B;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IA0D7B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAiDzB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAuEzB;;;;OAIG;YACW,cAAc;IA8B5B;;;;OAIG;YACW,wBAAwB;IActC;;;;OAIG;YACW,oBAAoB;IAmDlC;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAazB;;;;OAIG;IACH,OAAO,CAAC,WAAW;CAStB"}