@memberjunction/encryption 0.0.1 → 2.130.0

package/dist/interfaces.d.ts

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview Type definitions and interfaces for the MemberJunction encryption system.
+ *
+ * This module defines the core types used throughout the encryption package:
+ * - Configuration interfaces for key sources
+ * - Parsed encrypted value structure
+ * - Key configuration for runtime operations
+ *
+ * @module @memberjunction/encryption
+ * @see {@link EncryptionEngine} for the main encryption/decryption API
+ * @see {@link EncryptionKeySourceBase} for implementing custom key sources
+ */
+/**
+ * Configuration passed to encryption key source providers during instantiation.
+ *
+ * Key sources use this configuration to understand how to retrieve key material.
+ * The specific properties used depend on the key source implementation.
+ *
+ * @example
+ * ```typescript
+ * // Environment variable source config
+ * const envConfig: EncryptionKeySourceConfig = {
+ *   lookupValue: 'MJ_ENCRYPTION_KEY_PII'
+ * };
+ *
+ * // Config file source config
+ * const fileConfig: EncryptionKeySourceConfig = {
+ *   lookupValue: 'pii_master_key'
+ * };
+ * ```
+ */
+export interface EncryptionKeySourceConfig {
+    /**
+     * The identifier used to look up the key from the source.
+     * - For env vars: the environment variable name
+     * - For config files: the key name in the encryptionKeys section
+     * - For vaults: the secret path
+     */
+    lookupValue?: string;
+    /**
+     * Optional additional configuration specific to the key source.
+     * Providers can cast this to their specific config type.
+     */
+    additionalConfig?: Record<string, unknown>;
+}
+/**
+ * Represents the parsed components of an encrypted value string.
+ *
+ * Encrypted values follow the format:
+ * `$ENC$<keyId>$<algorithm>$<iv>$<ciphertext>[$<authTag>]`
+ *
+ * This structure allows the encryption engine to:
+ * 1. Identify which key was used for encryption
+ * 2. Determine the algorithm for decryption
+ * 3. Extract the IV and ciphertext for the crypto operation
+ * 4. Verify authenticity with the auth tag (for AEAD algorithms)
+ *
+ * @example
+ * ```typescript
+ * const parts = engine.ParseEncryptedValue(encryptedValue);
+ * console.log(parts.keyId); // UUID of the encryption key
+ * console.log(parts.algorithm); // 'AES-256-GCM'
+ * ```
+ */
+export interface EncryptedValueParts {
+    /**
+     * The encryption marker prefix (always '$ENC$').
+     * Used for quick detection of encrypted values.
+     */
+    marker: string;
+    /**
+     * The UUID of the encryption key used.
+     * References the EncryptionKey entity in the database.
+     */
+    keyId: string;
+    /**
+     * The algorithm name used for encryption.
+     * Matches the Name field in the EncryptionAlgorithm entity.
+     * @example 'AES-256-GCM', 'AES-256-CBC'
+     */
+    algorithm: string;
+    /**
+     * Base64-encoded initialization vector.
+     * Randomly generated for each encryption operation.
+     */
+    iv: string;
+    /**
+     * Base64-encoded encrypted data.
+     */
+    ciphertext: string;
+    /**
+     * Base64-encoded authentication tag for AEAD algorithms.
+     * Only present for algorithms like AES-GCM that provide authentication.
+     * Undefined for non-AEAD algorithms like AES-CBC.
+     */
+    authTag?: string;
+}
+/**
+ * Complete key configuration loaded from the database.
+ *
+ * This structure contains everything needed to perform encryption
+ * or decryption operations, cached for performance.
+ *
+ * @internal Used by EncryptionEngine for key management
+ */
+export interface KeyConfiguration {
+    /** The encryption key's unique identifier (UUID) */
+    keyId: string;
+    /**
+     * Current version of the key for this configuration.
+     * Incremented during key rotation operations.
+     */
+    keyVersion: string;
+    /**
+     * Prefix marker for encrypted values.
+     * Defaults to '$ENC$' but can be customized per key.
+     */
+    marker: string;
+    /** Algorithm configuration */
+    algorithm: {
+        /** Display name of the algorithm (e.g., 'AES-256-GCM') */
+        name: string;
+        /** Node.js crypto module algorithm identifier (e.g., 'aes-256-gcm') */
+        nodeCryptoName: string;
+        /** Required key length in bits (e.g., 256 for AES-256) */
+        keyLengthBits: number;
+        /** Required IV length in bytes (e.g., 12 for GCM, 16 for CBC) */
+        ivLengthBytes: number;
+        /**
+         * Whether the algorithm provides Authenticated Encryption with Associated Data.
+         * AEAD algorithms (like AES-GCM) provide both confidentiality and integrity.
+         */
+        isAEAD: boolean;
+    };
+    /** Key source configuration for retrieving key material */
+    source: {
+        /**
+         * The registered class name of the key source provider.
+         * Used with ClassFactory to instantiate the provider.
+         */
+        driverClass: string;
+        /**
+         * The lookup value passed to the key source.
+         * Interpretation depends on the source type.
+         */
+        lookupValue: string;
+    };
+}
+/**
+ * Result structure returned by key rotation operations.
+ *
+ * @see {@link RotateEncryptionKeyAction} for the rotation action
+ */
+export interface RotateKeyResult {
+    /** Whether the rotation completed successfully */
+    success: boolean;
+    /** Total number of records that were re-encrypted */
+    recordsProcessed: number;
+    /**
+     * List of fields that were processed.
+     * Format: 'EntityName.FieldName'
+     */
+    fieldsProcessed: string[];
+    /** Error message if rotation failed */
+    error?: string;
+}
+/**
+ * Parameters for key rotation operations.
+ *
+ * @see {@link RotateEncryptionKeyAction} for the rotation action
+ */
+export interface RotateKeyParams {
+    /** UUID of the encryption key to rotate */
+    encryptionKeyId: string;
+    /**
+     * Lookup value for the new key material.
+     * The new key must be accessible via the key source before rotation.
+     */
+    newKeyLookupValue: string;
+    /**
+     * Number of records to process per batch.
+     * Larger batches are faster but use more memory.
+     * @default 100
+     */
+    batchSize?: number;
+}
+/**
+ * Result structure for field encryption operations.
+ *
+ * @see {@link EnableFieldEncryptionAction}
+ */
+export interface EnableFieldEncryptionResult {
+    /** Whether the operation completed successfully */
+    success: boolean;
+    /** Number of records that were encrypted */
+    recordsEncrypted: number;
+    /** Number of records that were already encrypted (skipped) */
+    recordsSkipped: number;
+    /** Error message if the operation failed */
+    error?: string;
+}
+/**
+ * Parameters for enabling encryption on existing data.
+ *
+ * @see {@link EnableFieldEncryptionAction}
+ */
+export interface EnableFieldEncryptionParams {
+    /** UUID of the EntityField to encrypt */
+    entityFieldId: string;
+    /**
+     * Number of records to process per batch.
+     * @default 100
+     */
+    batchSize?: number;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,yBAAyB;IACtC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,mBAAmB;IAChC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC7B,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf,8BAA8B;IAC9B,SAAS,EAAE;QACP,0DAA0D;QAC1D,IAAI,EAAE,MAAM,CAAC;QAEb,uEAAuE;QACvE,cAAc,EAAE,MAAM,CAAC;QAEvB,0DAA0D;QAC1D,aAAa,EAAE,MAAM,CAAC;QAEtB,iEAAiE;QACjE,aAAa,EAAE,MAAM,CAAC;QAEtB;;;WAGG;QACH,MAAM,EAAE,OAAO,CAAC;KACnB,CAAC;IAEF,2DAA2D;IAC3D,MAAM,EAAE;QACJ;;;WAGG;QACH,WAAW,EAAE,MAAM,CAAC;QAEpB;;;WAGG;QACH,WAAW,EAAE,MAAM,CAAC;KACvB,CAAC;CACL;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC5B,kDAAkD;IAClD,OAAO,EAAE,OAAO,CAAC;IAEjB,qDAAqD;IACrD,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;IAE1B,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC5B,2CAA2C;IAC3C,eAAe,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IACxC,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAC;IAEjB,4CAA4C;IAC5C,gBAAgB,EAAE,MAAM,CAAC;IAEzB,8DAA8D;IAC9D,cAAc,EAAE,MAAM,CAAC;IAEvB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IACxC,yCAAyC;IACzC,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/interfaces.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * @fileoverview Type definitions and interfaces for the MemberJunction encryption system.
+ *
+ * This module defines the core types used throughout the encryption package:
+ * - Configuration interfaces for key sources
+ * - Parsed encrypted value structure
+ * - Key configuration for runtime operations
+ *
+ * @module @memberjunction/encryption
+ * @see {@link EncryptionEngine} for the main encryption/decryption API
+ * @see {@link EncryptionKeySourceBase} for implementing custom key sources
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=interfaces.js.map

package/dist/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG"}

package/dist/providers/AWSKMSKeySource.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview AWS KMS encryption key source provider.
+ *
+ * This provider retrieves encryption keys from AWS Key Management Service (KMS).
+ * It supports both symmetric keys and data key encryption using envelope encryption.
+ *
+ * ## Configuration
+ *
+ * The provider uses the standard AWS credential chain:
+ * - Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+ * - Shared credentials file (~/.aws/credentials)
+ * - IAM role (when running on EC2, ECS, Lambda, etc.)
+ *
+ * ## Usage
+ *
+ * 1. Create a symmetric key in AWS KMS
+ * 2. Store the key ARN or alias as the KeyLookupValue in MemberJunction
+ * 3. Ensure the application has kms:Decrypt permission for the key
+ *
+ * ## Lookup Value Format
+ *
+ * The KeyLookupValue should be in one of these formats:
+ * - Full ARN: `arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012`
+ * - Alias ARN: `arn:aws:kms:us-east-1:123456789012:alias/my-key`
+ * - Alias name: `alias/my-key` (uses default region)
+ *
+ * ## Environment Variables
+ *
+ * - `AWS_REGION` or `AWS_DEFAULT_REGION`: AWS region (required if not in ARN)
+ * - `AWS_ACCESS_KEY_ID`: Access key (optional if using IAM role)
+ * - `AWS_SECRET_ACCESS_KEY`: Secret key (optional if using IAM role)
+ *
+ * @module @memberjunction/encryption
+ */
+/// <reference types="node" />
+import { EncryptionKeySourceBase } from '../EncryptionKeySourceBase';
+/**
+ * AWS KMS key source provider.
+ *
+ * Retrieves encryption keys from AWS Key Management Service.
+ * The key material is stored encrypted in KMS and decrypted on retrieval.
+ *
+ * ## Security Notes
+ *
+ * - Key material never leaves AWS in plaintext until decryption
+ * - All operations are logged in CloudTrail
+ * - IAM policies control access to keys
+ * - Supports key rotation managed by AWS
+ *
+ * @example
+ * ```typescript
+ * // In database: KeyLookupValue = 'alias/mj-encryption-key'
+ * // The provider will call KMS to decrypt the data key
+ * ```
+ */
+export declare class AWSKMSKeySource extends EncryptionKeySourceBase {
+    private _client;
+    private _initialized;
+    /**
+     * Human-readable name for this key source.
+     */
+    get SourceName(): string;
+    /**
+     * Initializes the AWS KMS client.
+     *
+     * Lazy-loads the AWS SDK to avoid requiring it when not used.
+     * Uses the default credential chain for authentication.
+     */
+    Initialize(): Promise<void>;
+    /**
+     * Validates that the AWS KMS client is properly configured.
+     *
+     * @returns true if the client is initialized and region is configured
+     */
+    ValidateConfiguration(): boolean;
+    /**
+     * Checks if a key exists in AWS KMS.
+     *
+     * Note: This only checks if the key ARN/alias format is valid.
+     * Actual key existence is verified on GetKey().
+     *
+     * @param lookupValue - The KMS key ARN or alias
+     * @returns true if the lookup value appears to be a valid KMS key reference
+     */
+    KeyExists(lookupValue: string): Promise<boolean>;
+    /**
+     * Retrieves encryption key material from AWS KMS.
+     *
+     * This method expects the lookupValue to contain a base64-encoded
+     * encrypted data key (ciphertext blob) that was encrypted using
+     * a KMS customer master key (CMK).
+     *
+     * For envelope encryption pattern:
+     * 1. Generate a data key using KMS GenerateDataKey
+     * 2. Store the encrypted data key (CiphertextBlob) as base64 in lookupValue
+     * 3. This method decrypts it to get the plaintext key
+     *
+     * @param lookupValue - Base64-encoded encrypted data key
+     * @param _keyVersion - Not used for KMS (versioning handled by KMS)
+     * @returns Buffer containing the decrypted key material
+     *
+     * @throws Error if the key cannot be decrypted
+     */
+    GetKey(lookupValue: string, _keyVersion?: string): Promise<Buffer>;
+    /**
+     * Cleans up the AWS KMS client.
+     */
+    Dispose(): Promise<void>;
+}
+//# sourceMappingURL=AWSKMSKeySource.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AWSKMSKeySource.d.ts","sourceRoot":"","sources":["../../src/providers/AWSKMSKeySource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;;AAIH,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAMrE;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBACa,eAAgB,SAAQ,uBAAuB;IACxD,OAAO,CAAC,OAAO,CAA6E;IAC5F,OAAO,CAAC,YAAY,CAAS;IAE7B;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BjC;;;;OAIG;IACH,qBAAqB,IAAI,OAAO;IAkBhC;;;;;;;;OAQG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAetD;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgExE;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAOjC"}

package/dist/providers/AWSKMSKeySource.js

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * @fileoverview AWS KMS encryption key source provider.
+ *
+ * This provider retrieves encryption keys from AWS Key Management Service (KMS).
+ * It supports both symmetric keys and data key encryption using envelope encryption.
+ *
+ * ## Configuration
+ *
+ * The provider uses the standard AWS credential chain:
+ * - Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+ * - Shared credentials file (~/.aws/credentials)
+ * - IAM role (when running on EC2, ECS, Lambda, etc.)
+ *
+ * ## Usage
+ *
+ * 1. Create a symmetric key in AWS KMS
+ * 2. Store the key ARN or alias as the KeyLookupValue in MemberJunction
+ * 3. Ensure the application has kms:Decrypt permission for the key
+ *
+ * ## Lookup Value Format
+ *
+ * The KeyLookupValue should be in one of these formats:
+ * - Full ARN: `arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012`
+ * - Alias ARN: `arn:aws:kms:us-east-1:123456789012:alias/my-key`
+ * - Alias name: `alias/my-key` (uses default region)
+ *
+ * ## Environment Variables
+ *
+ * - `AWS_REGION` or `AWS_DEFAULT_REGION`: AWS region (required if not in ARN)
+ * - `AWS_ACCESS_KEY_ID`: Access key (optional if using IAM role)
+ * - `AWS_SECRET_ACCESS_KEY`: Secret key (optional if using IAM role)
+ *
+ * @module @memberjunction/encryption
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+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;
+};
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AWSKMSKeySource = void 0;
+const global_1 = require("@memberjunction/global");
+const core_1 = require("@memberjunction/core");
+const EncryptionKeySourceBase_1 = require("../EncryptionKeySourceBase");
+// Lazy-load AWS SDK to avoid requiring it when not used
+let KMSClient = null;
+let DecryptCommand = null;
+/**
+ * AWS KMS key source provider.
+ *
+ * Retrieves encryption keys from AWS Key Management Service.
+ * The key material is stored encrypted in KMS and decrypted on retrieval.
+ *
+ * ## Security Notes
+ *
+ * - Key material never leaves AWS in plaintext until decryption
+ * - All operations are logged in CloudTrail
+ * - IAM policies control access to keys
+ * - Supports key rotation managed by AWS
+ *
+ * @example
+ * ```typescript
+ * // In database: KeyLookupValue = 'alias/mj-encryption-key'
+ * // The provider will call KMS to decrypt the data key
+ * ```
+ */
+let AWSKMSKeySource = class AWSKMSKeySource extends EncryptionKeySourceBase_1.EncryptionKeySourceBase {
+    _client = null;
+    _initialized = false;
+    /**
+     * Human-readable name for this key source.
+     */
+    get SourceName() {
+        return 'AWS KMS';
+    }
+    /**
+     * Initializes the AWS KMS client.
+     *
+     * Lazy-loads the AWS SDK to avoid requiring it when not used.
+     * Uses the default credential chain for authentication.
+     */
+    async Initialize() {
+        if (this._initialized) {
+            return;
+        }
+        try {
+            // Lazy-load AWS SDK
+            const kmsModule = await Promise.resolve().then(() => __importStar(require('@aws-sdk/client-kms')));
+            KMSClient = kmsModule.KMSClient;
+            DecryptCommand = kmsModule.DecryptCommand;
+            // Create client with default credential chain
+            const region = process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION;
+            this._client = new KMSClient({
+                region: region || undefined
+            });
+            this._initialized = true;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`Failed to initialize AWS KMS client: ${message}. ` +
+                'Ensure @aws-sdk/client-kms is installed: npm install @aws-sdk/client-kms');
+        }
+    }
+    /**
+     * Validates that the AWS KMS client is properly configured.
+     *
+     * @returns true if the client is initialized and region is configured
+     */
+    ValidateConfiguration() {
+        if (!this._initialized || !this._client) {
+            return false;
+        }
+        // Check that we have a region configured
+        const region = process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION;
+        if (!region) {
+            (0, core_1.LogError)('AWS KMS key source: No AWS region configured. ' +
+                'Set AWS_REGION or AWS_DEFAULT_REGION environment variable.');
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Checks if a key exists in AWS KMS.
+     *
+     * Note: This only checks if the key ARN/alias format is valid.
+     * Actual key existence is verified on GetKey().
+     *
+     * @param lookupValue - The KMS key ARN or alias
+     * @returns true if the lookup value appears to be a valid KMS key reference
+     */
+    async KeyExists(lookupValue) {
+        if (!lookupValue) {
+            return false;
+        }
+        // Check for valid KMS key reference formats
+        // ARN: arn:aws:kms:region:account:key/key-id
+        // Alias ARN: arn:aws:kms:region:account:alias/alias-name
+        // Alias: alias/alias-name
+        const arnPattern = /^arn:aws:kms:[a-z0-9-]+:[0-9]+:(key|alias)\/.+$/;
+        const aliasPattern = /^alias\/.+$/;
+        return arnPattern.test(lookupValue) || aliasPattern.test(lookupValue);
+    }
+    /**
+     * Retrieves encryption key material from AWS KMS.
+     *
+     * This method expects the lookupValue to contain a base64-encoded
+     * encrypted data key (ciphertext blob) that was encrypted using
+     * a KMS customer master key (CMK).
+     *
+     * For envelope encryption pattern:
+     * 1. Generate a data key using KMS GenerateDataKey
+     * 2. Store the encrypted data key (CiphertextBlob) as base64 in lookupValue
+     * 3. This method decrypts it to get the plaintext key
+     *
+     * @param lookupValue - Base64-encoded encrypted data key
+     * @param _keyVersion - Not used for KMS (versioning handled by KMS)
+     * @returns Buffer containing the decrypted key material
+     *
+     * @throws Error if the key cannot be decrypted
+     */
+    async GetKey(lookupValue, _keyVersion) {
+        if (!this._initialized || !this._client) {
+            await this.Initialize();
+        }
+        if (!this._client || !DecryptCommand) {
+            throw new Error('AWS KMS client not initialized');
+        }
+        if (!lookupValue) {
+            throw new Error('AWS KMS key source requires a lookup value. ' +
+                'Provide the base64-encoded encrypted data key (CiphertextBlob).');
+        }
+        try {
+            // The lookupValue should be a base64-encoded encrypted data key
+            // This is the CiphertextBlob from GenerateDataKey
+            const ciphertextBlob = Buffer.from(lookupValue, 'base64');
+            // Decrypt the data key using KMS
+            const command = new DecryptCommand({
+                CiphertextBlob: ciphertextBlob
+            });
+            const response = await this._client.send(command);
+            if (!response.Plaintext) {
+                throw new Error('KMS returned empty plaintext');
+            }
+            // Convert Uint8Array to Buffer
+            return Buffer.from(response.Plaintext);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // Provide helpful error messages for common issues
+            if (message.includes('InvalidCiphertextException')) {
+                throw new Error(`AWS KMS decryption failed: Invalid ciphertext. ` +
+                    `Ensure the lookup value contains a valid base64-encoded encrypted data key.`);
+            }
+            if (message.includes('AccessDeniedException')) {
+                throw new Error(`AWS KMS access denied. ` +
+                    `Ensure the application has kms:Decrypt permission for the key.`);
+            }
+            if (message.includes('NotFoundException')) {
+                throw new Error(`AWS KMS key not found. ` +
+                    `Verify the key ARN/alias exists and is in the correct region.`);
+            }
+            throw new Error(`AWS KMS key retrieval failed: ${message}`);
+        }
+    }
+    /**
+     * Cleans up the AWS KMS client.
+     */
+    async Dispose() {
+        if (this._client) {
+            this._client.destroy();
+            this._client = null;
+        }
+        this._initialized = false;
+    }
+};
+exports.AWSKMSKeySource = AWSKMSKeySource;
+exports.AWSKMSKeySource = AWSKMSKeySource = __decorate([
+    (0, global_1.RegisterClass)(EncryptionKeySourceBase_1.EncryptionKeySourceBase, 'AWSKMSKeySource')
+], AWSKMSKeySource);
+//# sourceMappingURL=AWSKMSKeySource.js.map

package/dist/providers/AWSKMSKeySource.js.map

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