/**
 * TypeScript interfaces for Django-CFG encryption.
 *
 * These types match the encrypted response format from Django-CFG backend.
 */
/**
 * Encrypted field envelope returned by Django-CFG API.
 *
 * When a serializer field is encrypted, it returns this structure
 * instead of the plain value.
 *
 * @example
 * ```json
 * {
 *   "encrypted": true,
 *   "field": "price",
 *   "algorithm": "AES-256-GCM",
 *   "iv": "base64...",
 *   "data": "base64...",
 *   "auth_tag": "base64..."
 * }
 * ```
 */
interface EncryptedField {
    /** Always true for encrypted fields */
    encrypted: true;
    /** Field name that was encrypted */
    field?: string;
    /** Encryption algorithm used */
    algorithm: 'AES-256-GCM' | 'AES-256-CBC';
    /** Base64-encoded initialization vector */
    iv: string;
    /** Base64-encoded ciphertext */
    data: string;
    /** Base64-encoded authentication tag (GCM only) */
    auth_tag: string;
}
/**
 * Full encrypted response envelope.
 *
 * When response-level encryption is enabled, the entire response
 * body is wrapped in this structure.
 *
 * @example
 * ```json
 * {
 *   "encrypted": true,
 *   "algorithm": "AES-256-GCM",
 *   "salt": "base64...",
 *   "iv": "base64...",
 *   "data": "base64...",
 *   "auth_tag": "base64..."
 * }
 * ```
 */
interface EncryptedResponse {
    /** Always true for encrypted responses */
    encrypted: true;
    /** Encryption algorithm used */
    algorithm: 'AES-256-GCM' | 'AES-256-CBC';
    /** Base64-encoded salt for key derivation */
    salt: string;
    /** Base64-encoded initialization vector */
    iv: string;
    /** Base64-encoded ciphertext */
    data: string;
    /** Base64-encoded authentication tag (GCM only) */
    auth_tag: string;
}
/**
 * Configuration for the decryption client.
 */
interface DecryptionConfig {
    /**
     * Secret key for key derivation.
     * Should match the Django SECRET_KEY or a derived key.
     */
    secretKey: string;
    /**
     * User ID for per-user key derivation (optional).
     * When provided, keys are derived per-user for isolation.
     */
    userId?: string | number;
    /**
     * Session ID for per-session key derivation (optional).
     * Takes precedence over userId if both provided.
     */
    sessionId?: string;
    /**
     * Number of PBKDF2 iterations (default: 100000).
     * Must match backend configuration.
     */
    iterations?: number;
    /**
     * Key prefix for derivation (default: "djangocfg_encryption").
     * Must match backend configuration.
     */
    keyPrefix?: string;
}
/**
 * Result of a decryption operation.
 */
interface DecryptionResult<T = unknown> {
    /** Decrypted data */
    data: T;
    /** Whether decryption was successful */
    success: true;
}
/**
 * Error from a decryption operation.
 */
interface DecryptionError {
    /** Error message */
    message: string;
    /** Error code */
    code: 'INVALID_FORMAT' | 'DECRYPTION_FAILED' | 'AUTH_FAILED' | 'KEY_ERROR';
    /** Whether decryption was successful */
    success: false;
}
/**
 * Type guard to check if a value is an encrypted field.
 */
declare function isEncryptedField(value: unknown): value is EncryptedField;
/**
 * Type guard to check if a value is an encrypted response.
 */
declare function isEncryptedResponse(value: unknown): value is EncryptedResponse;

/**
 * PBKDF2 key derivation using Web Crypto API.
 *
 * Matches Django-CFG backend key derivation for decryption compatibility.
 */
/**
 * Derive an encryption key using PBKDF2.
 *
 * Uses Web Crypto API for secure key derivation that matches
 * the Django-CFG backend implementation.
 *
 * @param password - The password/secret key to derive from
 * @param salt - Salt bytes for key derivation
 * @param iterations - Number of PBKDF2 iterations (default: 100000)
 * @param keyLength - Desired key length in bytes (default: 32 for AES-256)
 * @returns Promise resolving to derived key as CryptoKey
 *
 * @example
 * ```typescript
 * const salt = new TextEncoder().encode('my-salt');
 * const key = await deriveKey('secret', salt, 100000);
 * ```
 */
declare function deriveKey(password: string, salt: Uint8Array, iterations?: number, keyLength?: number): Promise<CryptoKey>;
/**
 * Derive raw key bytes using PBKDF2.
 *
 * @param password - The password/secret key to derive from
 * @param salt - Salt bytes for key derivation
 * @param iterations - Number of PBKDF2 iterations (default: 100000)
 * @param keyLength - Desired key length in bytes (default: 32 for AES-256)
 * @returns Promise resolving to derived key as Uint8Array
 */
declare function deriveKeyBytes(password: string, salt: Uint8Array, iterations?: number, keyLength?: number): Promise<Uint8Array>;
/**
 * Build a deterministic salt from context components.
 *
 * Matches Django-CFG backend salt generation for key derivation.
 *
 * @param keyPrefix - Key prefix (default: "djangocfg_encryption")
 * @param userId - Optional user ID for per-user keys
 * @param sessionId - Optional session ID for per-session keys
 * @returns Salt as Uint8Array (first 16 bytes of SHA-256 hash)
 */
declare function buildSalt(keyPrefix?: string, userId?: string | number, sessionId?: string): Promise<Uint8Array>;
/**
 * Derive encryption key from Django-CFG config.
 *
 * Convenience function that matches backend key derivation.
 *
 * @param config - Configuration object with secretKey and optional context
 * @returns Promise resolving to CryptoKey for decryption
 *
 * @example
 * ```typescript
 * const key = await deriveKeyFromConfig({
 *   secretKey: 'django-secret-key',
 *   userId: 123,
 *   iterations: 100000
 * });
 * ```
 */
declare function deriveKeyFromConfig(config: {
    secretKey: string;
    userId?: string | number;
    sessionId?: string;
    iterations?: number;
    keyPrefix?: string;
}): Promise<CryptoKey>;

/**
 * AES-256-GCM decryption using Web Crypto API.
 *
 * Decrypts data encrypted by Django-CFG backend.
 */

/**
 * Decrypt AES-256-GCM ciphertext.
 *
 * @param ciphertext - Encrypted data bytes
 * @param key - CryptoKey for decryption
 * @param iv - Initialization vector
 * @param authTag - Authentication tag
 * @returns Promise resolving to decrypted bytes
 */
declare function decryptAES256GCM(ciphertext: Uint8Array, key: CryptoKey, iv: Uint8Array, authTag: Uint8Array): Promise<Uint8Array>;
/**
 * Decrypt a single encrypted field value.
 *
 * @param field - Encrypted field envelope
 * @param key - CryptoKey for decryption
 * @returns Promise resolving to decrypted value
 *
 * @example
 * ```typescript
 * const key = await deriveKeyFromConfig({ secretKey: '...' });
 * const price = await decryptField(response.price, key);
 * console.log(price); // 99.99
 * ```
 */
declare function decryptField<T = unknown>(field: EncryptedField, key: CryptoKey): Promise<T>;
/**
 * Decrypt an entire encrypted response.
 *
 * @param response - Encrypted response envelope
 * @param secretKey - Secret key for key derivation
 * @param config - Additional config (userId, sessionId, etc.)
 * @returns Promise resolving to decrypted response data
 */
declare function decryptResponse<T = unknown>(response: EncryptedResponse, secretKey: string, config?: Partial<Omit<DecryptionConfig, 'secretKey'>>): Promise<T>;
/**
 * Recursively decrypt all encrypted fields in an object.
 *
 * @param data - Object potentially containing encrypted fields
 * @param key - CryptoKey for decryption
 * @returns Promise resolving to object with all fields decrypted
 *
 * @example
 * ```typescript
 * const key = await deriveKeyFromConfig({ secretKey: '...' });
 * const product = await decryptObject(response, key);
 * // product.price is now decrypted
 * ```
 */
declare function decryptObject<T>(data: unknown, key: CryptoKey): Promise<T>;
/**
 * Create a decryption client with pre-configured key.
 *
 * @param config - Decryption configuration
 * @returns Object with decryption methods
 *
 * @example
 * ```typescript
 * const crypto = await createDecryptionClient({
 *   secretKey: 'django-secret-key',
 *   userId: currentUser.id
 * });
 *
 * const response = await fetch('/api/products/?encrypt=true');
 * const data = await crypto.decryptObject(await response.json());
 * ```
 */
declare function createDecryptionClient(config: DecryptionConfig): Promise<{
    /**
     * Decrypt a single encrypted field.
     */
    decryptField: <T = unknown>(field: EncryptedField) => Promise<T>;
    /**
     * Recursively decrypt all encrypted fields in an object.
     */
    decryptObject: <T>(data: unknown) => Promise<T>;
    /**
     * Check if a value is an encrypted field.
     */
    isEncryptedField: typeof isEncryptedField;
    /**
     * Check if a value is an encrypted response.
     */
    isEncryptedResponse: typeof isEncryptedResponse;
}>;
/**
 * Safe decryption wrapper that returns result or error.
 *
 * @param fn - Async function to execute
 * @returns Promise resolving to DecryptionResult or DecryptionError
 */
declare function safeDecrypt<T>(fn: () => Promise<T>): Promise<DecryptionResult<T> | DecryptionError>;

export { type DecryptionConfig, type DecryptionError, type DecryptionResult, type EncryptedField, type EncryptedResponse, buildSalt, createDecryptionClient, decryptAES256GCM, decryptField, decryptObject, decryptResponse, deriveKey, deriveKeyBytes, deriveKeyFromConfig, isEncryptedField, isEncryptedResponse, safeDecrypt };