@memberjunction/encryption 0.0.1 → 2.129.0

package/dist/providers/AzureKeyVaultKeySource.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Azure Key Vault encryption key source provider.
+ *
+ * This provider retrieves encryption keys from Azure Key Vault secrets.
+ * Keys are stored as base64-encoded strings in Key Vault secrets.
+ *
+ * ## Configuration
+ *
+ * The provider uses DefaultAzureCredential which supports:
+ * - Environment variables (AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID)
+ * - Managed Identity (when running on Azure)
+ * - Azure CLI credentials
+ * - Visual Studio Code credentials
+ *
+ * ## Usage
+ *
+ * 1. Create a Key Vault in Azure
+ * 2. Store the encryption key as a base64-encoded secret
+ * 3. Set the KeyLookupValue to the vault URL and secret name
+ * 4. Ensure the application has Secret Get permission
+ *
+ * ## Lookup Value Format
+ *
+ * The KeyLookupValue should be in the format:
+ * `https://your-vault-name.vault.azure.net/secrets/secret-name`
+ *
+ * Or just the secret name if AZURE_KEYVAULT_URL is set:
+ * `my-encryption-key`
+ *
+ * ## Environment Variables
+ *
+ * - `AZURE_KEYVAULT_URL`: Default Key Vault URL (optional)
+ * - `AZURE_CLIENT_ID`: Service principal client ID (optional if using managed identity)
+ * - `AZURE_CLIENT_SECRET`: Service principal secret (optional if using managed identity)
+ * - `AZURE_TENANT_ID`: Azure AD tenant ID (optional if using managed identity)
+ *
+ * @module @memberjunction/encryption
+ */
+/// <reference types="node" />
+import { EncryptionKeySourceBase } from '../EncryptionKeySourceBase';
+/**
+ * Azure Key Vault key source provider.
+ *
+ * Retrieves encryption keys from Azure Key Vault secrets.
+ * Secrets should contain base64-encoded key material.
+ *
+ * ## Security Notes
+ *
+ * - Keys are stored encrypted at rest in Key Vault
+ * - Access is controlled by Azure RBAC or Key Vault access policies
+ * - All operations are logged in Azure Monitor
+ * - Supports secret versioning and soft-delete
+ *
+ * @example
+ * ```typescript
+ * // In database: KeyLookupValue = 'https://my-vault.vault.azure.net/secrets/mj-encryption-key'
+ * // Or if AZURE_KEYVAULT_URL is set: KeyLookupValue = 'mj-encryption-key'
+ * ```
+ */
+export declare class AzureKeyVaultKeySource extends EncryptionKeySourceBase {
+    private _clients;
+    private _initialized;
+    private _defaultVaultUrl;
+    /**
+     * Human-readable name for this key source.
+     */
+    get SourceName(): string;
+    /**
+     * Initializes the Azure Key Vault client.
+     *
+     * Lazy-loads the Azure SDK to avoid requiring it when not used.
+     * Uses DefaultAzureCredential for authentication.
+     */
+    Initialize(): Promise<void>;
+    /**
+     * Validates that the Azure Key Vault client is properly configured.
+     *
+     * @returns true if the client is initialized
+     */
+    ValidateConfiguration(): boolean;
+    /**
+     * Checks if a secret name/URL appears to be valid.
+     *
+     * @param lookupValue - The secret URL or name
+     * @returns true if the lookup value appears valid
+     */
+    KeyExists(lookupValue: string): Promise<boolean>;
+    /**
+     * Retrieves encryption key material from Azure Key Vault.
+     *
+     * @param lookupValue - Secret URL or name (if AZURE_KEYVAULT_URL is set)
+     * @param keyVersion - Optional secret version (uses latest if not specified)
+     * @returns Buffer containing the key material
+     *
+     * @throws Error if the secret cannot be retrieved
+     */
+    GetKey(lookupValue: string, keyVersion?: string): Promise<Buffer>;
+    /**
+     * Parses a lookup value into vault URL and secret name.
+     *
+     * @private
+     */
+    private parseLookupValue;
+    /**
+     * Cleans up Azure Key Vault clients.
+     */
+    Dispose(): Promise<void>;
+}
+//# sourceMappingURL=AzureKeyVaultKeySource.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AzureKeyVaultKeySource.d.ts","sourceRoot":"","sources":["../../src/providers/AzureKeyVaultKeySource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;;AAGH,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAMrE;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBACa,sBAAuB,SAAQ,uBAAuB;IAC/D,OAAO,CAAC,QAAQ,CAA+F;IAC/G,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,gBAAgB,CAAuB;IAE/C;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA2BjC;;;;OAIG;IACH,qBAAqB,IAAI,OAAO;IAShC;;;;;OAKG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAsBtD;;;;;;;;OAQG;IACG,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA6EvE;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IA4BxB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAIjC"}

package/dist/providers/AzureKeyVaultKeySource.js

@@ -0,0 +1,268 @@
+"use strict";
+/**
+ * @fileoverview Azure Key Vault encryption key source provider.
+ *
+ * This provider retrieves encryption keys from Azure Key Vault secrets.
+ * Keys are stored as base64-encoded strings in Key Vault secrets.
+ *
+ * ## Configuration
+ *
+ * The provider uses DefaultAzureCredential which supports:
+ * - Environment variables (AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID)
+ * - Managed Identity (when running on Azure)
+ * - Azure CLI credentials
+ * - Visual Studio Code credentials
+ *
+ * ## Usage
+ *
+ * 1. Create a Key Vault in Azure
+ * 2. Store the encryption key as a base64-encoded secret
+ * 3. Set the KeyLookupValue to the vault URL and secret name
+ * 4. Ensure the application has Secret Get permission
+ *
+ * ## Lookup Value Format
+ *
+ * The KeyLookupValue should be in the format:
+ * `https://your-vault-name.vault.azure.net/secrets/secret-name`
+ *
+ * Or just the secret name if AZURE_KEYVAULT_URL is set:
+ * `my-encryption-key`
+ *
+ * ## Environment Variables
+ *
+ * - `AZURE_KEYVAULT_URL`: Default Key Vault URL (optional)
+ * - `AZURE_CLIENT_ID`: Service principal client ID (optional if using managed identity)
+ * - `AZURE_CLIENT_SECRET`: Service principal secret (optional if using managed identity)
+ * - `AZURE_TENANT_ID`: Azure AD tenant ID (optional if using managed identity)
+ *
+ * @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.AzureKeyVaultKeySource = void 0;
+const global_1 = require("@memberjunction/global");
+const EncryptionKeySourceBase_1 = require("../EncryptionKeySourceBase");
+// Lazy-load Azure SDK to avoid requiring it when not used
+let SecretClient = null;
+let DefaultAzureCredential = null;
+/**
+ * Azure Key Vault key source provider.
+ *
+ * Retrieves encryption keys from Azure Key Vault secrets.
+ * Secrets should contain base64-encoded key material.
+ *
+ * ## Security Notes
+ *
+ * - Keys are stored encrypted at rest in Key Vault
+ * - Access is controlled by Azure RBAC or Key Vault access policies
+ * - All operations are logged in Azure Monitor
+ * - Supports secret versioning and soft-delete
+ *
+ * @example
+ * ```typescript
+ * // In database: KeyLookupValue = 'https://my-vault.vault.azure.net/secrets/mj-encryption-key'
+ * // Or if AZURE_KEYVAULT_URL is set: KeyLookupValue = 'mj-encryption-key'
+ * ```
+ */
+let AzureKeyVaultKeySource = class AzureKeyVaultKeySource extends EncryptionKeySourceBase_1.EncryptionKeySourceBase {
+    _clients = new Map();
+    _initialized = false;
+    _defaultVaultUrl = null;
+    /**
+     * Human-readable name for this key source.
+     */
+    get SourceName() {
+        return 'Azure Key Vault';
+    }
+    /**
+     * Initializes the Azure Key Vault client.
+     *
+     * Lazy-loads the Azure SDK to avoid requiring it when not used.
+     * Uses DefaultAzureCredential for authentication.
+     */
+    async Initialize() {
+        if (this._initialized) {
+            return;
+        }
+        try {
+            // Lazy-load Azure SDKs
+            const secretsModule = await Promise.resolve().then(() => __importStar(require('@azure/keyvault-secrets')));
+            const identityModule = await Promise.resolve().then(() => __importStar(require('@azure/identity')));
+            SecretClient = secretsModule.SecretClient;
+            DefaultAzureCredential = identityModule.DefaultAzureCredential;
+            // Get default vault URL if configured
+            this._defaultVaultUrl = process.env.AZURE_KEYVAULT_URL || null;
+            this._initialized = true;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`Failed to initialize Azure Key Vault client: ${message}. ` +
+                'Ensure @azure/keyvault-secrets and @azure/identity are installed: ' +
+                'npm install @azure/keyvault-secrets @azure/identity');
+        }
+    }
+    /**
+     * Validates that the Azure Key Vault client is properly configured.
+     *
+     * @returns true if the client is initialized
+     */
+    ValidateConfiguration() {
+        if (!this._initialized) {
+            return false;
+        }
+        // Configuration is valid - credentials will be validated on first use
+        return true;
+    }
+    /**
+     * Checks if a secret name/URL appears to be valid.
+     *
+     * @param lookupValue - The secret URL or name
+     * @returns true if the lookup value appears valid
+     */
+    async KeyExists(lookupValue) {
+        if (!lookupValue) {
+            return false;
+        }
+        // Check for valid patterns
+        // Full URL: https://vault-name.vault.azure.net/secrets/secret-name
+        // Secret name only: my-secret-name (requires AZURE_KEYVAULT_URL)
+        const urlPattern = /^https:\/\/[a-zA-Z0-9-]+\.vault\.azure\.net\/secrets\/[a-zA-Z0-9-]+/;
+        const namePattern = /^[a-zA-Z0-9-]+$/;
+        if (urlPattern.test(lookupValue)) {
+            return true;
+        }
+        if (namePattern.test(lookupValue) && this._defaultVaultUrl) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Retrieves encryption key material from Azure Key Vault.
+     *
+     * @param lookupValue - Secret URL or name (if AZURE_KEYVAULT_URL is set)
+     * @param keyVersion - Optional secret version (uses latest if not specified)
+     * @returns Buffer containing the key material
+     *
+     * @throws Error if the secret cannot be retrieved
+     */
+    async GetKey(lookupValue, keyVersion) {
+        if (!this._initialized) {
+            await this.Initialize();
+        }
+        if (!SecretClient || !DefaultAzureCredential) {
+            throw new Error('Azure Key Vault client not initialized');
+        }
+        if (!lookupValue) {
+            throw new Error('Azure Key Vault key source requires a lookup value. ' +
+                'Provide the secret URL or name.');
+        }
+        try {
+            // Parse the lookup value to get vault URL and secret name
+            const { vaultUrl, secretName } = this.parseLookupValue(lookupValue);
+            // Get or create client for this vault
+            let client = this._clients.get(vaultUrl);
+            if (!client) {
+                const credential = new DefaultAzureCredential();
+                client = new SecretClient(vaultUrl, credential);
+                this._clients.set(vaultUrl, client);
+            }
+            // Build secret options
+            const options = keyVersion ? { version: keyVersion } : {};
+            // Get the secret
+            const secret = await client.getSecret(secretName, options);
+            if (!secret.value) {
+                throw new Error(`Secret "${secretName}" has no value`);
+            }
+            // Secret value should be base64-encoded key material
+            try {
+                return Buffer.from(secret.value, 'base64');
+            }
+            catch {
+                throw new Error(`Secret "${secretName}" is not valid base64. ` +
+                    'Encryption keys must be stored as base64-encoded strings in Key Vault.');
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // Provide helpful error messages for common issues
+            if (message.includes('SecretNotFound')) {
+                throw new Error(`Azure Key Vault secret not found: ${lookupValue}. ` +
+                    `Verify the secret exists in the vault.`);
+            }
+            if (message.includes('Forbidden') || message.includes('AccessDenied')) {
+                throw new Error(`Azure Key Vault access denied for: ${lookupValue}. ` +
+                    `Ensure the application has Secret Get permission.`);
+            }
+            if (message.includes('AuthenticationError')) {
+                throw new Error(`Azure authentication failed. ` +
+                    `Ensure credentials are configured (managed identity, service principal, or Azure CLI).`);
+            }
+            throw new Error(`Azure Key Vault key retrieval failed: ${message}`);
+        }
+    }
+    /**
+     * Parses a lookup value into vault URL and secret name.
+     *
+     * @private
+     */
+    parseLookupValue(lookupValue) {
+        // Full URL format: https://vault-name.vault.azure.net/secrets/secret-name[/version]
+        const urlMatch = lookupValue.match(/^(https:\/\/[a-zA-Z0-9-]+\.vault\.azure\.net)\/secrets\/([a-zA-Z0-9-]+)/);
+        if (urlMatch) {
+            return {
+                vaultUrl: urlMatch[1],
+                secretName: urlMatch[2]
+            };
+        }
+        // Simple name format (requires AZURE_KEYVAULT_URL)
+        if (this._defaultVaultUrl) {
+            return {
+                vaultUrl: this._defaultVaultUrl,
+                secretName: lookupValue
+            };
+        }
+        throw new Error(`Invalid Key Vault lookup value: "${lookupValue}". ` +
+            `Expected format: https://vault-name.vault.azure.net/secrets/secret-name ` +
+            `or set AZURE_KEYVAULT_URL and provide just the secret name.`);
+    }
+    /**
+     * Cleans up Azure Key Vault clients.
+     */
+    async Dispose() {
+        this._clients.clear();
+        this._initialized = false;
+    }
+};
+exports.AzureKeyVaultKeySource = AzureKeyVaultKeySource;
+exports.AzureKeyVaultKeySource = AzureKeyVaultKeySource = __decorate([
+    (0, global_1.RegisterClass)(EncryptionKeySourceBase_1.EncryptionKeySourceBase, 'AzureKeyVaultKeySource')
+], AzureKeyVaultKeySource);
+//# sourceMappingURL=AzureKeyVaultKeySource.js.map

package/dist/providers/AzureKeyVaultKeySource.js.map

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

package/dist/providers/ConfigFileKeySource.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @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
+ */
+/// <reference types="node" />
+import { EncryptionKeySourceBase } from '../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');
+ * ```
+ */
+export declare class ConfigFileKeySource extends EncryptionKeySourceBase {
+    /**
+     * Loaded configuration from the config file.
+     * Set during Initialize(), null if not yet loaded.
+     *
+     * @private
+     */
+    private _loadedConfig;
+    /**
+     * Path to the loaded config file (for error messages).
+     *
+     * @private
+     */
+    private _configFilePath;
+    /**
+     * Human-readable name for this source.
+     */
+    get SourceName(): string;
+    /**
+     * 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
+     */
+    Initialize(): Promise<void>;
+    /**
+     * Validates that the configuration file was loaded successfully.
+     *
+     * @returns `true` if the config file was loaded and contains encryptionKeys
+     */
+    ValidateConfiguration(): boolean;
+    /**
+     * 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
+     */
+    KeyExists(lookupValue: string): Promise<boolean>;
+    /**
+     * 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');
+     * ```
+     */
+    GetKey(lookupValue: string, keyVersion?: string): Promise<Buffer>;
+    /**
+     * Cleans up resources (no-op for config file source).
+     */
+    Dispose(): Promise<void>;
+    /**
+     * 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
+     */
+    private buildKeyName;
+    /**
+     * Validates that a string is a valid configuration key name.
+     *
+     * @param name - The name to validate
+     * @returns `true` if the name is valid
+     *
+     * @private
+     */
+    private isValidKeyName;
+}
+//# sourceMappingURL=ConfigFileKeySource.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigFileKeySource.d.ts","sourceRoot":"","sources":["../../src/providers/ConfigFileKeySource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;;AAGH,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAYrE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBACa,mBAAoB,SAAQ,uBAAuB;IAC5D;;;;;OAKG;IACH,OAAO,CAAC,aAAa,CAAuC;IAE5D;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAAuB;IAE9C;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;;;;OAOG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA6CjC;;;;OAIG;IACH,qBAAqB,IAAI,OAAO;IAIhC;;;;;OAKG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBtD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA6EvE;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IAUpB;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;CAczB"}