import type { Jwk } from '../jwk.js';
import type { KeyIdentifier } from '../../types/identifier.js';
import type { JweHeaderParams } from './header.js';
/**
 * Key management input for encrypting with `"alg": "ECDH-ES"` (Direct Key Agreement).
 *
 * A fresh ephemeral X25519 key pair is generated for every encrypt operation and the public key
 * is placed in the JWE Protected Header as the "epk" parameter.
 */
export type JweEcdhEsEncryptKey = {
    /** Discriminates ECDH-ES key management input from JWK / Key Identifier / passphrase inputs. */
    mode: 'ecdh-es';
    /** The recipient's static X25519 public key in JWK format. */
    peerPublicKey: Jwk;
    /**
     * Optional PIN used to strengthen the derived Content Encryption Key. The PIN never transits:
     * when provided, the CEK is passed through HKDF-SHA256 with salt UTF8(pin) and
     * info UTF8('enbox/connect/v2/pin') after Concat KDF derivation. A recipient using the wrong
     * PIN derives a different CEK and fails closed with an AEAD authentication tag failure.
     */
    pin?: string;
};
/**
 * Key management input for decrypting with `"alg": "ECDH-ES"` (Direct Key Agreement).
 */
export type JweEcdhEsDecryptKey = {
    /** Discriminates ECDH-ES key management input from JWK / Key Identifier / passphrase inputs. */
    mode: 'ecdh-es';
    /** The recipient's static X25519 private key in JWK format. */
    privateKey: Jwk;
    /** {@inheritDoc JweEcdhEsEncryptKey.pin} */
    pin?: string;
};
/**
 * The key management key material accepted by {@link JweKeyManagement.decrypt}.
 */
export type JweKeyManagementDecryptKey = KeyIdentifier | Jwk | Uint8Array | JweEcdhEsDecryptKey;
/**
 * The key management key material accepted by {@link JweKeyManagement.encrypt}.
 */
export type JweKeyManagementEncryptKey = KeyIdentifier | Jwk | Uint8Array | JweEcdhEsEncryptKey;
/**
 * Represents the result of the JWE key management encryption process, encapsulating the Content
 * Encryption Key (CEK) and optionally the encrypted CEK.
 */
export interface JweKeyManagementEncryptResult {
    /**
     * The Content Encryption Key (CEK) used for encrypting the JWE payload. It can be a Key
     * Identifier such as a KMS URI or a JSON Web Key (JWK).
     */
    cek: KeyIdentifier | Jwk;
    /**
     * The encrypted version of the CEK, provided as a byte array. The encrypted version of the CEK
     * is returned for all key management modes other than "dir" (Direct Encryption Mode) and
     * "ECDH-ES" (Direct Key Agreement Mode).
     */
    encryptedKey?: Uint8Array;
    /**
     * Header parameters produced during key management (e.g. the ECDH-ES "epk" value) that MUST be
     * merged into the JWE Protected Header before it is encoded so that they are covered by the
     * Additional Authenticated Data.
     */
    headerParams?: Partial<JweHeaderParams>;
}
/**
 * Defines the parameters required to decrypt a JWE encrypted key, including the key management
 * details.
 */
export interface JweKeyManagementDecryptParams {
    /**
     * The decryption key which can be a Key Identifier such as a KMS key URI, a JSON Web Key (JWK),
     * raw key material represented as a byte array, or an ECDH-ES key agreement input.
     */
    key: JweKeyManagementDecryptKey;
    /**
     * The encrypted key extracted from the JWE, represented as a byte array. This parameter is
     * optional and is used when the key is wrapped.
     */
    encryptedKey?: Uint8Array;
    /**
     * The JWE header parameters that define the characteristics of the decryption process, specifying
     * the algorithm and encryption method among other settings.
     */
    joseHeader: JweHeaderParams;
}
/**
 * Defines the parameters required for encrypting a JWE CEK, including the key management details.
 */
export interface JweKeyManagementEncryptParams {
    /**
     * The encryption key which can be a Key Identifier such as a KMS key URI, a JSON Web Key (JWK),
     * raw key material represented as a byte array, or an ECDH-ES key agreement input.
     */
    key: JweKeyManagementEncryptKey;
    /**
     * The JWE header parameters that define the characteristics of the encryption process, specifying
     * the algorithm and encryption method among other settings.
     */
    joseHeader: JweHeaderParams;
}
/**
 * Generates a random Content Encryption Key (CEK) in JWK format for the given "enc" (Encryption
 * Algorithm) Header Parameter value.
 *
 * @param enc - The JWE "enc" value identifying the content encryption algorithm.
 * @returns A Promise that resolves to the generated CEK in JWK format.
 * @throws {@link CryptoError} with code `AlgorithmNotSupported` if the "enc" value is not
 *         supported.
 */
export declare function generateCek(enc: string): Promise<Jwk>;
/**
 * The `JweKeyManagement` class implements the key management aspects of JSON Web Encryption (JWE)
 * as specified in {@link https://datatracker.ietf.org/doc/html/rfc7516 | RFC 7516}.
 *
 * It supports algorithms for encrypting and decrypting keys, thereby enabling the secure
 * transmission of information where the payload is encrypted, and the encryption key is also
 * encrypted or agreed upon using key agreement techniques.
 *
 * The choice of algorithm is determined by the "alg" parameter in the JWE
 * header, and the class is designed to handle the intricacies associated with each algorithm,
 * ensuring the secure handling of the encryption keys.
 *
 * Supported algorithms include:
 * - `"dir"`: Direct Encryption Mode
 * - `"ECDH-ES"`: Direct Key Agreement Mode using Elliptic Curve Diffie-Hellman Ephemeral Static
 *   (X25519 only) with the Concat KDF, per RFC 7518, Section 4.6.
 * - `"PBES2-HS256+A128KW"`, `"PBES2-HS384+A192KW"`, `"PBES2-HS512+A256KW"`: Password-Based
 *   Encryption Mode with Key Wrapping (PBES2) using HMAC-SHA and AES Key Wrap algorithms for key
 *   wrapping and encryption.
 *
 * @example
 * ```ts
 * // To encrypt a key:
 * const keyEncryptionKey = Convert.string(passphrase).toUint8Array();
 * const { cek, encryptedKey: encryptedCek } = await JweKeyManagement.encrypt({
 *   key        : keyEncryptionKey,
 *   joseHeader : {
 *     alg : 'PBES2-HS512+A256KW',
 *     enc : 'A256GCM',
 *     p2c : 210_000,
 *     p2s : Convert.uint8Array(saltInput).toBase64Url()
 *   }
 * });
 *
 * // To decrypt a key:
 * const cek = await JweKeyManagement.decrypt({
 *   key          : keyEncryptionKey,
 *   encryptedKey : encryptedCek,
 *   joseHeader   : {
 *     alg : 'PBES2-HS512+A256KW',
 *     enc : 'A256GCM',
 *     p2c : 210_000,
 *     p2s : Convert.uint8Array(saltInput).toBase64Url()
 *   }
 * });
 * ```
 */
export declare class JweKeyManagement {
    /**
     * Decrypts the encrypted key (JWE Encrypted Key) using the specified key encryption algorithm
     * defined in the JWE Header's "alg" parameter.
     *
     * This method supports multiple key management algorithms, including Direct Encryption (dir),
     * Direct Key Agreement (ECDH-ES), and PBES2 schemes with key wrapping.
     *
     * The method takes a key, which can be a Key Identifier, JWK, raw byte array, or ECDH-ES key
     * agreement input, and the encrypted key along with the JWE header. It returns the decrypted
     * Content Encryption Key (CEK) which can then be used to decrypt the JWE ciphertext.
     *
     * @example
     * ```ts
     * // Decrypting the CEK with the PBES2-HS512+A256KW algorithm
     * const cek = await JweKeyManagement.decrypt({
     *   key          : Convert.string(passphrase).toUint8Array(),
     *   encryptedKey : encryptedCek,
     *   joseHeader   : {
     *     alg : 'PBES2-HS512+A256KW',
     *     enc : 'A256GCM',
     *     p2c : 210_000,
     *     p2s : Convert.uint8Array(saltInput).toBase64Url(),
     *   }
     * });
     * ```
     *
     * @param params - The decryption parameters.
     * @param options - Options controlling decryption constraints (e.g. the minimum acceptable
     *                  PBES2 iteration count).
     * @throws Throws an error if the key management algorithm is not supported or if required
     *         parameters are missing or invalid.
     */
    static decrypt({ key, encryptedKey, joseHeader }: JweKeyManagementDecryptParams, options?: {
        minP2cCount?: number;
    }): Promise<KeyIdentifier | Jwk>;
    /**
     * Encrypts a Content Encryption Key (CEK) using the key management algorithm specified in the
     * JWE Header's "alg" parameter.
     *
     * This method supports various key management algorithms, including Direct Encryption (dir),
     * Direct Key Agreement (ECDH-ES), and PBES2 with key wrapping.
     *
     * For PBES2, it generates a random CEK for the specified encryption algorithm in the JWE header,
     * which can then be used to encrypt the actual payload, and returns the CEK along with the
     * encrypted key. For ECDH-ES, it generates a fresh ephemeral X25519 key pair, derives the CEK
     * from the shared secret, and returns the ephemeral public key as a header parameter that MUST
     * be merged into the JWE Protected Header.
     *
     * @example
     * ```ts
     * // Encrypting the CEK with the PBES2-HS512+A256KW algorithm
     * const { cek, encryptedKey } = await JweKeyManagement.encrypt({
     *   key        : Convert.string(passphrase).toUint8Array(),
     *   joseHeader : {
     *     alg : 'PBES2-HS512+A256KW',
     *     enc : 'A256GCM',
     *     p2c : 210_000,
     *     p2s : Convert.uint8Array(saltInput).toBase64Url(),
     *   }
     * });
     * ```
     *
     * @param params - The encryption parameters.
     * @returns The encrypted key result containing the CEK, optionally the encrypted CEK
     *          (JWE Encrypted Key), and optionally header parameters that must be added to the JWE
     *          Protected Header.
     * @throws Throws an error if the key management algorithm is not supported or if required
     *         parameters are missing or invalid.
     */
    static encrypt({ key, joseHeader }: JweKeyManagementEncryptParams): Promise<JweKeyManagementEncryptResult>;
    /**
     * Derives the Content Encryption Key (CEK) for "ECDH-ES" (Direct Key Agreement Mode) from an
     * ECDH shared secret using the Concat KDF, per
     * {@link https://datatracker.ietf.org/doc/html/rfc7518#section-4.6.2 | RFC 7518, Section 4.6.2}:
     * - AlgorithmID is the value of the "enc" Header Parameter.
     * - PartyUInfo / PartyVInfo are the decoded values of the "apu" / "apv" Header Parameters, or
     *   the empty octet sequence when absent.
     * - SuppPubInfo is keydatalen, the bit length of the key used by the "enc" algorithm.
     *
     * When a `pin` is provided, the derived CEK is additionally passed through HKDF-SHA256 with
     * salt UTF8(pin) and info UTF8('enbox/connect/v2/pin'). The PIN never transits; a recipient
     * using the wrong PIN derives a different CEK and fails closed with an AEAD authentication tag
     * failure.
     *
     * @param params - The CEK derivation parameters.
     * @returns A Promise that resolves to the derived CEK in JWK format.
     * @throws {@link CryptoError} if the shared secret is all zeros (low-order point rejection), the
     *         "enc" value is unsupported, or the "apu" / "apv" values cannot be decoded.
     */
    private static deriveEcdhEsCek;
    /**
     * Decodes an agreement party ("apu" / "apv") Header Parameter from Base64 URL format to a byte
     * array, returning the empty octet sequence when the parameter is absent.
     *
     * @param param - The name of the Header Parameter being decoded; used for error messaging.
     * @param value - The Base64 URL encoded value of the Header Parameter, if present.
     * @returns The decoded value as a byte array.
     * @throws {@link CryptoError} if the value is present but not a properly encoded Base64 URL
     *         string.
     */
    private static decodeAgreementParty;
    /**
     * Derives the PBES2 Key Encryption Key (KEK) from a passphrase using PBKDF2, per
     * {@link https://www.rfc-editor.org/rfc/rfc7518.html#section-4.8 | RFC 7518, Section 4.8}.
     *
     * The salt value used is (UTF8(Alg) || 0x00 || Salt Input), where Alg is the "alg" (algorithm)
     * Header Parameter value. This reduces the potential for a precomputed dictionary attack (also
     * known as a rainbow table attack).
     *
     * @param params - The KEK derivation parameters.
     * @returns A Promise that resolves to the derived AES Key Wrap KEK in JWK format.
     * @throws {@link CryptoError} if the "p2s" value cannot be decoded.
     */
    private static derivePbes2Kek;
    /**
     * Validates the "epk" (Ephemeral Public Key) Header Parameter for ECDH-ES key agreement.
     *
     * @param epk - The "epk" value from the JOSE Header.
     * @returns The validated ephemeral public key in JWK format.
     * @throws {@link CryptoError} if the "epk" value is missing, malformed, or uses an unsupported
     *         curve.
     */
    private static validateEpk;
}
//# sourceMappingURL=key-management.d.ts.map