/**
 * Key Provider for Field-Level Encryption
 *
 * Manages encryption keys for field-level encryption with support for:
 * - Key versioning for rotation
 * - HKDF key derivation for field-specific keys
 * - Environment-based key storage
 * - KMS integration (AWS KMS, HashiCorp Vault)
 * - Envelope encryption pattern
 * - Secure memory caching with TTL
 *
 * Security considerations:
 * - Master keys are never exposed outside this module
 * - Field-specific keys are derived using HKDF
 * - Key versions enable zero-downtime rotation
 * - All key material is wiped after use when possible
 * - KMS integration provides hardware-backed key protection
 *
 * @packageDocumentation
 * @module security/encryption/key-provider
 */
import type { KeyVersion, EncryptionConfig } from './types.js';
import type { KMSConfig } from '../kms/types.js';
/**
 * Interface for key providers
 *
 * Key providers are responsible for managing master encryption keys
 * and deriving field-specific keys using HKDF.
 */
export interface KeyProvider {
    /**
     * Get the current active key version number
     */
    getCurrentVersion(): Promise<number>;
    /**
     * Get a specific key version's metadata
     */
    getKeyVersion(version: number): Promise<KeyVersion | null>;
    /**
     * Get all available key versions
     */
    getAllVersions(): Promise<KeyVersion[]>;
    /**
     * Derive a field-specific encryption key
     *
     * @param version - Key version to use
     * @param fieldName - Name of the field (used in key derivation)
     * @param tenantId - Optional tenant ID for multi-tenant isolation
     * @returns Derived key buffer
     */
    deriveFieldKey(version: number, fieldName: string, tenantId?: string): Promise<Buffer>;
    /**
     * Derive a deterministic key for searchable encryption
     *
     * This uses a fixed "IV" derived from the plaintext to enable searching
     * while still providing encryption. Less secure than random IV encryption.
     *
     * @param version - Key version to use
     * @param fieldName - Name of the field
     * @param tenantId - Optional tenant ID
     * @returns Derived key buffer
     */
    deriveDeterministicKey(version: number, fieldName: string, tenantId?: string): Promise<Buffer>;
    /**
     * Rotate to a new key version
     *
     * @returns The new key version number
     */
    rotateKey(): Promise<number>;
    /**
     * Initialize the key provider
     */
    initialize(): Promise<void>;
    /**
     * Shutdown the key provider and clear sensitive data
     */
    shutdown(): Promise<void>;
}
/**
 * Key provider that reads master keys from environment variables
 *
 * Key format:
 * - VORION_ENCRYPTION_KEY: Current master key (base64 encoded, 32+ bytes)
 * - VORION_ENCRYPTION_KEY_V{N}: Version-specific keys for rotation
 *
 * @example
 * ```typescript
 * const provider = new EnvKeyProvider({
 *   keyDerivationInfo: 'my-app-encryption-v1',
 * });
 * await provider.initialize();
 *
 * // Derive a field-specific key
 * const key = await provider.deriveFieldKey(1, 'ssn');
 * ```
 */
export declare class EnvKeyProvider implements KeyProvider {
    private readonly config;
    private readonly masterKeys;
    private readonly keyVersions;
    private currentVersion;
    private initialized;
    constructor(config?: Partial<EncryptionConfig>);
    /**
     * Initialize the key provider by loading keys from environment
     */
    initialize(): Promise<void>;
    /**
     * Load versioned keys from environment (VORION_ENCRYPTION_KEY_V1, V2, etc.)
     */
    private loadVersionedKeys;
    /**
     * Load the current key from environment (VORION_ENCRYPTION_KEY)
     */
    private loadCurrentKey;
    /**
     * Decode a key from environment variable (supports base64 or raw)
     */
    private decodeKey;
    /**
     * Validate key length meets minimum requirements
     */
    private validateKeyLength;
    /**
     * Ensure the provider is initialized
     */
    private ensureInitialized;
    /**
     * Get the current active key version
     */
    getCurrentVersion(): Promise<number>;
    /**
     * Get metadata for a specific key version
     */
    getKeyVersion(version: number): Promise<KeyVersion | null>;
    /**
     * Get all available key versions
     */
    getAllVersions(): Promise<KeyVersion[]>;
    /**
     * Derive a field-specific encryption key using HKDF
     *
     * Key derivation:
     * - Input Key Material (IKM): Master key for the version
     * - Salt: SHA-256 hash of tenant ID (or empty for single-tenant)
     * - Info: Concatenation of config info prefix + field name
     */
    deriveFieldKey(version: number, fieldName: string, tenantId?: string): Promise<Buffer>;
    /**
     * Derive a deterministic key for searchable encryption
     *
     * Uses a different info string to ensure deterministic keys are
     * cryptographically separate from random IV keys.
     */
    deriveDeterministicKey(version: number, fieldName: string, tenantId?: string): Promise<Buffer>;
    /**
     * Rotate to a new key version
     *
     * Note: In a production environment, this would integrate with a secrets
     * management service. For the EnvKeyProvider, new keys must be added
     * to environment variables before rotation.
     */
    rotateKey(): Promise<number>;
    /**
     * Shutdown and clear sensitive key material
     */
    shutdown(): Promise<void>;
}
/**
 * Configuration for KMS-backed key provider
 */
export interface KMSKeyProviderConfig {
    /** Encryption configuration */
    encryptionConfig?: Partial<EncryptionConfig>;
    /** KMS configuration (if not using default provider) */
    kmsConfig?: KMSConfig;
    /** Cache TTL for derived keys in milliseconds */
    cacheTtlMs?: number;
    /** Maximum cache size */
    maxCacheSize?: number;
    /** Enable key caching */
    enableCaching?: boolean;
    /** Encryption context to include with data keys */
    encryptionContext?: Record<string, string>;
}
/**
 * Key provider that uses KMS for envelope encryption
 *
 * This provider uses a KMS (AWS KMS, HashiCorp Vault, or local) to
 * generate and protect data encryption keys. The pattern used is
 * envelope encryption:
 *
 * 1. KMS generates a data key (plaintext + encrypted)
 * 2. The plaintext data key is used to derive field-specific keys via HKDF
 * 3. The encrypted data key is stored for later decryption
 * 4. Plaintext keys are cached securely in memory with TTL
 *
 * Security benefits:
 * - Master key never leaves KMS
 * - Data keys are protected by KMS encryption
 * - Key rotation is handled by KMS
 * - Audit logging of all key operations
 *
 * @example
 * ```typescript
 * const provider = new KMSKeyProvider({
 *   kmsConfig: {
 *     provider: 'aws',
 *     keyArn: 'arn:aws:kms:us-west-2:123456789:key/abc-123',
 *   },
 * });
 * await provider.initialize();
 *
 * // Derive a field-specific key
 * const key = await provider.deriveFieldKey(1, 'ssn');
 * ```
 */
export declare class KMSKeyProvider implements KeyProvider {
    private readonly encryptionConfig;
    private readonly kmsConfig?;
    private readonly cacheTtlMs;
    private readonly maxCacheSize;
    private readonly enableCaching;
    private readonly encryptionContext?;
    private kmsProvider;
    private derivedKeyCache;
    private dataKeyVersions;
    private keyVersionMetadata;
    private currentVersion;
    private initialized;
    constructor(config?: KMSKeyProviderConfig);
    /**
     * Initialize the KMS key provider
     */
    initialize(): Promise<void>;
    /**
     * Generate a new data key version from KMS
     */
    private generateDataKeyVersion;
    /**
     * Get the data key for a specific version
     */
    private getDataKey;
    /**
     * Ensure the provider is initialized
     */
    private ensureInitialized;
    /**
     * Get the current active key version
     */
    getCurrentVersion(): Promise<number>;
    /**
     * Get metadata for a specific key version
     */
    getKeyVersion(version: number): Promise<KeyVersion | null>;
    /**
     * Get all available key versions
     */
    getAllVersions(): Promise<KeyVersion[]>;
    /**
     * Derive a field-specific encryption key using HKDF
     */
    deriveFieldKey(version: number, fieldName: string, tenantId?: string): Promise<Buffer>;
    /**
     * Derive a deterministic key for searchable encryption
     */
    deriveDeterministicKey(version: number, fieldName: string, tenantId?: string): Promise<Buffer>;
    /**
     * Rotate to a new key version
     */
    rotateKey(): Promise<number>;
    /**
     * Shutdown and clear sensitive key material
     */
    shutdown(): Promise<void>;
    /**
     * Get the encrypted data keys for persistence
     *
     * This method returns the encrypted data keys that should be stored
     * securely (e.g., in a database) to allow key recovery after restart.
     */
    getEncryptedDataKeys(): Map<number, Buffer>;
    /**
     * Load encrypted data keys from storage
     *
     * This method loads previously stored encrypted data keys and decrypts
     * them using KMS.
     */
    loadEncryptedDataKeys(encryptedKeys: Map<number, Buffer>, metadata: Map<number, KeyVersion>): Promise<void>;
    /**
     * Get cache statistics
     */
    getCacheStats(): {
        size: number;
        ttlMs: number;
        maxSize: number;
    } | null;
}
/**
 * Create an EnvKeyProvider instance
 */
export declare function createEnvKeyProvider(config?: Partial<EncryptionConfig>): EnvKeyProvider;
/**
 * Create a KMSKeyProvider instance
 */
export declare function createKMSKeyProvider(config?: KMSKeyProviderConfig): KMSKeyProvider;
/**
 * Get the default key provider instance
 *
 * Returns a KMSKeyProvider if KMS is configured, otherwise falls back to EnvKeyProvider.
 * The provider is NOT initialized - call initialize() before use.
 */
export declare function getKeyProvider(): KeyProvider;
/**
 * Get an initialized key provider
 *
 * Creates and initializes the appropriate key provider based on configuration.
 */
export declare function getInitializedKeyProvider(): Promise<KeyProvider>;
/**
 * Set a custom key provider as the default
 */
export declare function setKeyProvider(provider: KeyProvider): void;
/**
 * Reset the default key provider (for testing)
 */
export declare function resetKeyProvider(): Promise<void>;
/**
 * Create the appropriate key provider based on environment
 *
 * @param useKMS - Force KMS usage even if not detected in environment
 * @returns A key provider (not initialized)
 */
export declare function createKeyProvider(useKMS?: boolean): KeyProvider;
//# sourceMappingURL=key-provider.d.ts.map