import type { Result } from '@private.me/shared';
/** X25519 ephemeral key pair for ECDH key agreement. */
export interface EphemeralKeyPair {
    /** Web Crypto private key handle (X25519). */
    readonly privateKey: CryptoKey;
    /** Web Crypto public key handle (X25519). */
    readonly publicKey: CryptoKey;
    /** Raw 32-byte X25519 public key for wire transport. */
    readonly rawPublicKey: Uint8Array;
}
/** Result of ECDH key agreement. */
export interface KeyAgreementResult {
    /** Derived AES-256-GCM shared key. */
    readonly sharedKey: CryptoKey;
    /** Ephemeral public key to include in envelope. */
    readonly ephemeralPublicKey: Uint8Array;
}
/** Result of hybrid (X25519 + ML-KEM-768) key agreement. */
export interface HybridKeyAgreementResult {
    /** Derived AES-256-GCM shared key (from HKDF over X25519 + ML-KEM shared secrets). */
    readonly sharedKey: CryptoKey;
    /** Ephemeral X25519 public key to include in envelope (32 bytes). */
    readonly ephemeralPublicKey: Uint8Array;
    /** ML-KEM-768 ciphertext to include in envelope (1088 bytes). */
    readonly kemCiphertext: Uint8Array;
}
/** Error codes for key agreement operations. Sub-codes give context. */
export type KeyAgreementError = 'KEYGEN_FAILED' | 'DERIVE_FAILED' | 'IMPORT_FAILED' | 'INVALID_KEY_LENGTH' | 'INVALID_KEY_LENGTH:EXPECTED_32' | 'KEM_ENCAPSULATE_FAILED' | 'KEM_DECAPSULATE_FAILED' | 'HKDF_FAILED' | 'EXPORT_KEY_FAILED';
/**
 * Generate an ephemeral X25519 key pair for ECDH key agreement.
 *
 * Uses Web Crypto API to generate a fresh X25519 key pair.
 * The key pair is ephemeral -- it should be used for a single
 * key agreement and then discarded.
 *
 * @returns Result containing the ephemeral key pair or error.
 *
 * @example
 * ```typescript
 * import { generateEphemeralKeyPair } from '@private.me/xbind';
 *
 * const ephemeral = await generateEphemeralKeyPair();
 * if (!ephemeral.ok) {
 *   throw new Error(`Key generation failed: ${ephemeral.error}`);
 * }
 *
 * console.log('Ephemeral public key (32 bytes):', ephemeral.value.rawPublicKey);
 * // Use ephemeral.value.privateKey for ECDH, then discard
 * ```
 */
export declare function generateEphemeralKeyPair(): Promise<Result<EphemeralKeyPair, KeyAgreementError>>;
/**
 * Import a raw 32-byte X25519 public key into a CryptoKey.
 *
 * Used by the receiver to import the sender's ephemeral public
 * key from the envelope for ECDH derivation.
 *
 * @param rawPublicKey - Raw 32-byte X25519 public key.
 * @returns Result containing the imported CryptoKey or error.
 */
export declare function importX25519PublicKey(rawPublicKey: Uint8Array): Promise<Result<CryptoKey, KeyAgreementError>>;
/**
 * Derive a shared AES-256-GCM key via X25519 ECDH.
 *
 * Performs ECDH key agreement between a local private key and a
 * remote public key, producing 256 bits of shared secret that
 * are imported as an AES-256-GCM key.
 *
 * @param localPrivateKey - Local X25519 private key.
 * @param remotePublicKey - Remote X25519 public key (CryptoKey).
 * @returns Result containing the derived AES-256-GCM key or error.
 */
export declare function deriveSharedKeyECDH(localPrivateKey: CryptoKey, remotePublicKey: CryptoKey): Promise<Result<CryptoKey, KeyAgreementError>>;
/**
 * Perform sender-side ECDH key agreement.
 *
 * Generates an ephemeral X25519 key pair, derives a shared key
 * with the recipient's static X25519 public key, and returns
 * both the shared key and the ephemeral public key to include
 * in the envelope.
 *
 * @param recipientX25519PubKey - Recipient's static X25519 public key.
 * @returns Result containing the key agreement result or error.
 *
 * @example
 * ```typescript
 * import { senderKeyAgreement, importX25519PublicKey } from '@private.me/xbind';
 *
 * // Import recipient's X25519 public key
 * const recipientPubKeyRaw = new Uint8Array(32); // From recipient's identity
 * const recipientPubKey = await importX25519PublicKey(recipientPubKeyRaw);
 * if (!recipientPubKey.ok) throw new Error(recipientPubKey.error);
 *
 * // Perform key agreement
 * const agreement = await senderKeyAgreement(recipientPubKey.value);
 * if (!agreement.ok) throw new Error(agreement.error);
 *
 * // Use shared key for encryption
 * const { sharedKey, ephemeralPublicKey } = agreement.value;
 * // Include ephemeralPublicKey in envelope header
 * ```
 */
export declare function senderKeyAgreement(recipientX25519PubKey: CryptoKey): Promise<Result<KeyAgreementResult, KeyAgreementError>>;
/**
 * Perform receiver-side ECDH key agreement.
 *
 * Imports the sender's ephemeral public key from the envelope
 * and derives the shared key using the receiver's static X25519
 * private key.
 *
 * @param receiverPrivateKey - Receiver's static X25519 private key.
 * @param senderEphemeralPubRaw - Sender's ephemeral public key (raw bytes).
 * @returns Result containing the derived AES-256-GCM key or error.
 */
export declare function receiverKeyAgreement(receiverPrivateKey: CryptoKey, senderEphemeralPubRaw: Uint8Array): Promise<Result<CryptoKey, KeyAgreementError>>;
/**
 * Combine X25519 + ML-KEM shared secrets using IETF X-Wing combiner.
 *
 * IETF draft-connolly-cfrg-xwing-kem-10 compliant combiner that includes:
 * - ML-KEM shared secret (32B)
 * - ML-KEM ciphertext (1088B for ML-KEM-768)
 * - X25519 shared secret (32B)
 * - X25519 ephemeral public key (32B)
 * - X25519 recipient public key (32B)
 * - ML-KEM recipient public key (1184B for ML-KEM-768)
 *
 * This prevents Unknown Key Share (UKS) attacks, transcript manipulation,
 * and session confusion by binding the key material to the full protocol transcript.
 *
 * Session 159 - CRYPTO-1: Upgraded from naive concatenation to IETF standard.
 *
 * @param mlKemShared - 32-byte ML-KEM-768 shared secret
 * @param mlKemCiphertext - 1088-byte ML-KEM-768 ciphertext
 * @param x25519Shared - 32-byte raw X25519 ECDH shared secret
 * @param x25519EphemeralPub - 32-byte sender's ephemeral X25519 public key
 * @param x25519RecipientPub - 32-byte recipient's static X25519 public key
 * @param mlKemRecipientPub - 1184-byte recipient's ML-KEM-768 public key
 * @returns AES-256-GCM CryptoKey derived using IETF X-Wing combiner
 */
export declare function combineSharedSecrets(mlKemShared: Uint8Array, mlKemCiphertext: Uint8Array, x25519Shared: Uint8Array, x25519EphemeralPub: Uint8Array, x25519RecipientPub: Uint8Array, mlKemRecipientPub: Uint8Array): Promise<Result<CryptoKey, KeyAgreementError>>;
/**
 * Perform sender-side hybrid key agreement (X25519 + ML-KEM-768).
 *
 * 1. Generate ephemeral X25519, ECDH → x25519SharedBits
 * 2. ML-KEM-768 encapsulate → kemCiphertext + mlKemShared
 * 3. HKDF(x25519Shared || mlKemShared) → AES-256-GCM key
 *
 * @param recipientX25519Pub - Recipient's static X25519 public key.
 * @param recipientMlKemPub - Recipient's ML-KEM-768 public key (1184B).
 * @returns Hybrid key agreement result with shared key, ephemeral pub, and KEM ciphertext.
 */
export declare function senderHybridKeyAgreement(recipientX25519Pub: CryptoKey, recipientMlKemPub: Uint8Array): Promise<Result<HybridKeyAgreementResult, KeyAgreementError>>;
/**
 * Perform receiver-side hybrid key agreement (X25519 + ML-KEM-768).
 *
 * 1. Import ephemeral X25519, ECDH → x25519SharedBits
 * 2. ML-KEM-768 decapsulate → mlKemShared
 * 3. IETF X-Wing combiner → same AES-256-GCM key
 *
 * Session 159 - CRYPTO-1: Updated to use IETF X-Wing combiner with public keys.
 *
 * @param x25519PrivateKey - Receiver's static X25519 private key.
 * @param x25519PublicKeyRaw - Receiver's static X25519 public key (32B raw bytes).
 * @param ephPubRaw - Sender's ephemeral X25519 public key (32B).
 * @param kemCiphertext - ML-KEM-768 ciphertext from sender (1088B).
 * @param mlKemSecretKey - Receiver's ML-KEM-768 secret key (2400B).
 * @param mlKemPublicKey - Receiver's ML-KEM-768 public key (1184B).
 * @returns AES-256-GCM shared key or error.
 */
export declare function receiverHybridKeyAgreement(x25519PrivateKey: CryptoKey, x25519PublicKeyRaw: Uint8Array, ephPubRaw: Uint8Array, kemCiphertext: Uint8Array, mlKemSecretKey: Uint8Array, mlKemPublicKey: Uint8Array): Promise<Result<CryptoKey, KeyAgreementError>>;
