Skip to main content

hyprstream_rpc/crypto/
key_exchange.rs

1//! Diffie-Hellman key exchange for stream MAC key derivation.
2//!
3//! Streaming responses use MAC authentication instead of per-token Ed25519
4//! signatures for performance. The MAC key is derived from a DH shared secret.
5//!
6//! # Ristretto255
7//!
8//! This module uses Ristretto255, a prime-order group built on Curve25519.
9//! Unlike X25519, Ristretto255 has no cofactor issues:
10//! - No small subgroups or low-order points
11//! - Invalid encodings are rejected at decode time
12//! - If a point decodes successfully, it's safe to use
13//!
14//! See: https://ristretto.group/why_ristretto.html
15//!
16//! # Flow
17//!
18//! 1. Client generates ephemeral Ristretto keypair
19//! 2. Client includes ephemeral public key in signed RequestEnvelope
20//! 3. Server computes shared secret: `DH(server_secret, client_ephemeral_pubkey)`
21//! 4. Both derive MAC key: `KDF(shared_secret || salt, context="mac")`
22//! 5. Server MACs each stream chunk, client verifies
23//!
24//! # Feature Flags
25//!
26//! - Default: Blake3 derive_key + Ristretto255 DH
27//! - `fips`: HKDF-SHA256 + ECDH P-256 (NIST approved)
28
29use subtle::ConstantTimeEq;
30use zeroize::{Zeroize, Zeroizing};
31
32use super::backend::derive_key;
33use crate::error::{EnvelopeError, EnvelopeResult};
34
35// ============================================================================
36// Stream Key Derivation (E2E Authenticated Streaming)
37// ============================================================================
38
39/// Derived keys for E2E authenticated streaming.
40///
41/// Contains:
42/// - `topic`: 64-char hex string derived from DH, used as ZMQ subscription prefix
43/// - `mac_key`: 32-byte HMAC key for MAC chain verification
44/// - `ctrl_topic`: 64-char hex string for control channel (consumer → producer)
45/// - `ctrl_mac_key`: 32-byte HMAC key for control channel authentication
46///
47/// Both client and server derive identical keys from their DH shared secret.
48#[derive(Clone)]
49pub struct StreamKeys {
50    /// Topic for ZMQ PUB/SUB routing (64 hex chars = 32 bytes encoded).
51    pub topic: String,
52    /// HMAC key for MAC chain (zeroized on drop).
53    pub mac_key: Zeroizing<[u8; 32]>,
54    /// AES-256-GCM key for transport-level AEAD of stream payloads (#321,
55    /// zeroized on drop). Distinct from `mac_key` via its own derivation context
56    /// (`"hyprstream stream-keys v1 enc"`). The mesh stream plane seals each
57    /// Data/Complete payload under this key; the chained HMAC still runs over the
58    /// (now-encrypted) block, so ordering / anti-replay are unchanged.
59    pub enc_key: Zeroizing<[u8; 32]>,
60    /// Control channel topic (64 hex chars, derived from same DH secret).
61    pub ctrl_topic: String,
62    /// Control channel HMAC key (zeroized on drop).
63    pub ctrl_mac_key: Zeroizing<[u8; 32]>,
64}
65
66impl StreamKeys {
67    /// Create from raw topic and mac_key bytes.
68    ///
69    /// The AEAD `enc_key` is deterministically derived from `mac_key` via a
70    /// dedicated context so this constructor stays source-compatible while still
71    /// producing a stable, non-zero, key-separated AEAD key.
72    pub fn new(topic: String, mac_key: [u8; 32]) -> Self {
73        let enc_key = derive_key("hyprstream stream-keys v1 enc", &mac_key);
74        Self {
75            topic,
76            mac_key: Zeroizing::new(mac_key),
77            enc_key: Zeroizing::new(enc_key),
78            ctrl_topic: String::new(),
79            ctrl_mac_key: Zeroizing::new([0u8; 32]),
80        }
81    }
82
83    /// Create with both data and control channel keys plus the AEAD enc_key.
84    pub fn with_ctrl(
85        topic: String,
86        mac_key: [u8; 32],
87        enc_key: [u8; 32],
88        ctrl_topic: String,
89        ctrl_mac_key: [u8; 32],
90    ) -> Self {
91        Self {
92            topic,
93            mac_key: Zeroizing::new(mac_key),
94            enc_key: Zeroizing::new(enc_key),
95            ctrl_topic,
96            ctrl_mac_key: Zeroizing::new(ctrl_mac_key),
97        }
98    }
99
100    /// Get the first 16 bytes of topic as bytes (for first block's prevMac).
101    ///
102    /// In the MAC chain, block 0 uses topic[..16] as prevMac.
103    ///
104    /// # Errors
105    /// Returns error if topic is not valid hex (should never happen with properly derived keys).
106    pub fn topic_prefix_bytes(&self) -> EnvelopeResult<[u8; 16]> {
107        // Decode first 32 hex chars (= 16 bytes)
108        let mut prefix = [0u8; 16];
109        hex::decode_to_slice(&self.topic[..32], &mut prefix)
110            .map_err(|_| EnvelopeError::InvalidTopicFormat)?;
111        Ok(prefix)
112    }
113}
114
115/// Check if two public keys are identical (self-connection attack).
116fn is_self_connection(client_pub: &[u8; 32], server_pub: &[u8; 32]) -> bool {
117    client_pub.ct_eq(server_pub).into()
118}
119
120/// Derive stream keys (topic and mac_key) from DH shared secret.
121///
122/// Uses the crypto backend (Blake3 or HKDF-SHA256) with:
123/// - IKM: shared_secret || salt (where salt = XOR of client_pub and server_pub)
124/// - Context: "hyprstream stream-keys v1 topic" or "hyprstream stream-keys v1 mac"
125///
126/// # Arguments
127///
128/// * `shared_secret` - 32-byte DH shared secret
129/// * `client_pub` - Client's ephemeral Ristretto public key (32 bytes)
130/// * `server_pub` - Server's ephemeral Ristretto public key (32 bytes)
131///
132/// # Returns
133///
134/// `StreamKeys` containing the derived topic (64 hex chars) and mac_key (32 bytes).
135///
136/// # Errors
137///
138/// Returns `EnvelopeError::KeyExchange` if client and server keys are identical.
139///
140/// # Security
141///
142/// - Ristretto255 eliminates low-order point attacks by construction
143/// - XOR salt ensures both parties' keys are bound to the derivation
144/// - Self-connection check prevents replay attacks
145///
146/// # Backend
147///
148/// - Default: Blake3 `derive_key()` (~10+ GB/s with SIMD)
149/// - FIPS mode: HKDF-SHA256 (NIST SP 800-56C)
150pub fn derive_stream_keys(
151    shared_secret: &[u8; 32],
152    client_pub: &[u8; 32],
153    server_pub: &[u8; 32],
154) -> EnvelopeResult<StreamKeys> {
155    // Ristretto255: No low-order point checks needed!
156    // Invalid encodings are rejected at decode time, and all valid
157    // Ristretto points are in the prime-order subgroup.
158
159    // Security check: reject self-connection
160    if is_self_connection(client_pub, server_pub) {
161        return Err(EnvelopeError::KeyExchange(
162            "client and server keys are identical".into(),
163        ));
164    }
165
166    // XOR public keys for salt (binds both parties' keys to the derivation)
167    let mut salt = [0u8; 32];
168    for i in 0..32 {
169        salt[i] = client_pub[i] ^ server_pub[i];
170    }
171
172    // Build IKM: shared_secret || salt
173    let mut ikm = [0u8; 64];
174    ikm[..32].copy_from_slice(shared_secret);
175    ikm[32..64].copy_from_slice(&salt);
176
177    // Derive topic (32 bytes -> 64 hex chars)
178    let topic_bytes = derive_key("hyprstream stream-keys v1 topic", &ikm);
179    let topic = hex::encode(topic_bytes);
180
181    // Derive mac_key (32 bytes)
182    let mac_key = derive_key("hyprstream stream-keys v1 mac", &ikm);
183
184    // Derive AEAD enc_key (32 bytes, #321) — a DISTINCT context from `mac`, so the
185    // transport-AEAD key is cryptographically separated from the HMAC-chain key
186    // (mirrors `derive_notification_keys`'s enc/mac split). The mesh stream plane
187    // seals each Data/Complete payload under this key.
188    let enc_key = derive_key("hyprstream stream-keys v1 enc", &ikm);
189
190    // Derive control channel topic (32 bytes -> 64 hex chars)
191    let ctrl_topic_bytes = derive_key("hyprstream stream-keys v1 ctrl-topic", &ikm);
192    let ctrl_topic = hex::encode(ctrl_topic_bytes);
193
194    // Derive control channel mac_key (32 bytes)
195    let ctrl_mac_key = derive_key("hyprstream stream-keys v1 ctrl-mac", &ikm);
196
197    // Zeroize IKM containing the shared secret (mirrors derive_notification_keys).
198    ikm.zeroize();
199
200    Ok(StreamKeys::with_ctrl(
201        topic,
202        mac_key,
203        enc_key,
204        ctrl_topic,
205        ctrl_mac_key,
206    ))
207}
208
209// ============================================================================
210// Hybrid post-quantum stream key agreement (S3 #554, epic #550)
211// ============================================================================
212//
213// Replaces the classical Ristretto255/X25519 stream DH with the S0 hybrid
214// multi-KEM (`crate::crypto::hybrid_kem`). The combiner secret is already
215// transcript-bound (it mixes every component ciphertext + recipient ek) and is
216// fed into `derive_stream_keys` as the IKM. The two 32-byte salt halves that
217// `derive_stream_keys` expects are domain-separated digests of the client public
218// material and the server ciphertexts — guaranteed distinct (different labels) so
219// the self-connection check never trips.
220//
221// Direction: stream data flows server -> client, so the CLIENT is the KEM
222// recipient (it decapsulates). The client sends a fresh ephemeral
223// `RecipientPublic` (forward secrecy via the ephemeral X25519 + ML-KEM legs); the
224// server encapsulates and returns the ciphertexts in `StreamInfo`.
225
226const HYBRID_CLIENT_SALT_CTX: &str = "hyprstream hybrid-stream client v1";
227const HYBRID_SERVER_SALT_CTX: &str = "hyprstream hybrid-stream server v1";
228
229/// Domain-separated 32-byte digest of handshake transcript bytes (a salt half
230/// for [`derive_stream_keys`]).
231fn hybrid_salt(label: &str, bytes: &[u8]) -> [u8; 32] {
232    derive_key(label, bytes)
233}
234
235/// Server side of the hybrid stream handshake (S3 #554).
236///
237/// `client_kem_public` is the client's encoded ephemeral
238/// [`RecipientPublic`](crate::crypto::hybrid_kem::RecipientPublic) from
239/// `RequestEnvelope.clientKemPublic`. Encapsulate to it, derive the stream keys
240/// from the hybrid combiner secret, and return the per-component ciphertexts to
241/// emit in `StreamInfo.kemCiphertexts`. Fail-closed on malformed/wrong-suite input.
242pub fn server_hybrid_stream_keys(
243    client_kem_public: &[u8],
244) -> EnvelopeResult<(crate::crypto::hybrid_kem::HybridKemMaterial, StreamKeys)> {
245    let client_pub = crate::crypto::hybrid_kem::RecipientPublic::decode(client_kem_public)
246        .map_err(|e| EnvelopeError::KeyExchange(format!("invalid client KEM public: {e}")))?;
247    let (material, secret) = crate::crypto::hybrid_kem::encapsulate_to(&client_pub)
248        .map_err(|e| EnvelopeError::KeyExchange(format!("hybrid encapsulate failed: {e}")))?;
249    let client_salt = hybrid_salt(HYBRID_CLIENT_SALT_CTX, client_kem_public);
250    let server_salt = hybrid_salt(HYBRID_SERVER_SALT_CTX, &material.encode());
251    let keys = derive_stream_keys(&secret, &client_salt, &server_salt)?;
252    Ok((material, keys))
253}
254
255/// Client side of the hybrid stream handshake (S3 #554).
256///
257/// Given the client's ephemeral
258/// [`RecipientKeypair`](crate::crypto::hybrid_kem::RecipientKeypair) and the
259/// server's encoded ciphertexts from `StreamInfo.kemCiphertexts`, decapsulate and
260/// derive the SAME [`StreamKeys`].
261pub fn client_hybrid_stream_keys(
262    keypair: &crate::crypto::hybrid_kem::RecipientKeypair,
263    kem_ciphertexts: &[u8],
264) -> EnvelopeResult<StreamKeys> {
265    let material = crate::crypto::hybrid_kem::HybridKemMaterial::decode(kem_ciphertexts)
266        .map_err(|e| EnvelopeError::KeyExchange(format!("invalid KEM ciphertexts: {e}")))?;
267    let secret = crate::crypto::hybrid_kem::decapsulate(keypair, &material)
268        .map_err(|e| EnvelopeError::KeyExchange(format!("hybrid decapsulate failed: {e}")))?;
269    let client_salt = hybrid_salt(HYBRID_CLIENT_SALT_CTX, &keypair.public().encode());
270    let server_salt = hybrid_salt(HYBRID_SERVER_SALT_CTX, kem_ciphertexts);
271    derive_stream_keys(&secret, &client_salt, &server_salt)
272}
273
274/// Server side of the transcript-bound identified stream epoch bootstrap.
275///
276/// This is the production successor to [`server_hybrid_stream_keys`].  The
277/// pinned HyKEM combiner secret is mixed with the complete accepted-current
278/// stream binding before any direction/track/epoch traffic key is derived.
279pub fn server_identified_stream_epoch(
280    client_kem_public: &[u8],
281    binding: crate::stream_epoch::IdentifiedStreamBinding,
282) -> EnvelopeResult<(
283    crate::crypto::hybrid_kem::HybridKemMaterial,
284    crate::stream_epoch::StreamEpochRatchet,
285)> {
286    let client_pub = crate::crypto::hybrid_kem::RecipientPublic::decode(client_kem_public)
287        .map_err(|e| EnvelopeError::KeyExchange(format!("invalid client KEM public: {e}")))?;
288    if client_pub.suite_id != crate::stream_epoch::IDENTIFIED_STREAM_SUITE {
289        return Err(EnvelopeError::KeyExchange(
290            "identified stream requires the pinned X25519+ML-KEM-768 suite".into(),
291        ));
292    }
293    let (material, secret) = crate::crypto::hybrid_kem::encapsulate_to(&client_pub)
294        .map_err(|e| EnvelopeError::KeyExchange(format!("hybrid encapsulate failed: {e}")))?;
295    let ratchet = crate::stream_epoch::StreamEpochRatchet::from_hybrid_secret(&secret, binding)
296        .map_err(|e| EnvelopeError::KeyExchange(format!("stream transcript rejected: {e}")))?;
297    Ok((material, ratchet))
298}
299
300/// Client side of the transcript-bound identified stream epoch bootstrap.
301pub fn client_identified_stream_epoch(
302    keypair: &crate::crypto::hybrid_kem::RecipientKeypair,
303    kem_ciphertexts: &[u8],
304    binding: crate::stream_epoch::IdentifiedStreamBinding,
305) -> EnvelopeResult<crate::stream_epoch::StreamEpochRatchet> {
306    if keypair.suite_id != crate::stream_epoch::IDENTIFIED_STREAM_SUITE {
307        return Err(EnvelopeError::KeyExchange(
308            "identified stream requires the pinned X25519+ML-KEM-768 suite".into(),
309        ));
310    }
311    let material = crate::crypto::hybrid_kem::HybridKemMaterial::decode(kem_ciphertexts)
312        .map_err(|e| EnvelopeError::KeyExchange(format!("invalid KEM ciphertexts: {e}")))?;
313    if material.suite_id != crate::stream_epoch::IDENTIFIED_STREAM_SUITE {
314        return Err(EnvelopeError::KeyExchange(
315            "identified stream ciphertexts use the wrong suite".into(),
316        ));
317    }
318    let secret = crate::crypto::hybrid_kem::decapsulate(keypair, &material)
319        .map_err(|e| EnvelopeError::KeyExchange(format!("hybrid decapsulate failed: {e}")))?;
320    crate::stream_epoch::StreamEpochRatchet::from_hybrid_secret(&secret, binding)
321        .map_err(|e| EnvelopeError::KeyExchange(format!("stream transcript rejected: {e}")))
322}
323
324/// One-way epoch ratchet for long-lived streams (S3 #554 / #223).
325///
326/// Derive the next epoch's key from the current one via a one-way KDF: a
327/// compromise of the current epoch key cannot recover any earlier epoch (forward
328/// secrecy across rekeys). Bump `epoch`, ratchet the key, reset `seq` — keeping
329/// the `(epoch, seq)` AEAD nonce (see `crypto::cose_encrypt`) unique-forever.
330pub fn ratchet_stream_key(current: &[u8; 32]) -> Zeroizing<[u8; 32]> {
331    Zeroizing::new(derive_key("hyprstream stream ratchet v1", current))
332}
333
334// ============================================================================
335// Notification Key Derivation (Broadcast Encryption)
336// ============================================================================
337
338/// Derived keys for notification broadcast encryption.
339///
340/// Contains:
341/// - `enc_key`: AES-256-GCM key for wrapping per-subscriber data keys
342/// - `mac_key`: One-shot MAC key for ciphertext authentication
343///
344/// Both publisher and subscriber derive identical keys from their DH shared secret.
345pub struct NotificationKeys {
346    /// AES-256-GCM key for data_key wrapping (zeroized on drop).
347    pub enc_key: Zeroizing<[u8; 32]>,
348    /// One-shot MAC key (zeroized on drop).
349    pub mac_key: Zeroizing<[u8; 32]>,
350}
351
352/// Derive notification keys (enc_key and mac_key) from DH shared secret.
353///
354/// Uses the crypto backend (Blake3 or HKDF-SHA256) with:
355/// - IKM: shared_secret || salt (where salt = XOR of publisher_pub and subscriber_pub)
356/// - Context: notification-specific domain separation strings
357///
358/// # Arguments
359///
360/// * `shared_secret` - 32-byte DH shared secret
361/// * `publisher_pub` - Publisher's ephemeral Ristretto public key (32 bytes)
362/// * `subscriber_pub` - Subscriber's (possibly blinded) Ristretto public key (32 bytes)
363///
364/// # Errors
365///
366/// Returns `EnvelopeError::KeyExchange` if publisher and subscriber keys are identical.
367pub fn derive_notification_keys(
368    shared_secret: &[u8; 32],
369    publisher_pub: &[u8; 32],
370    subscriber_pub: &[u8; 32],
371) -> EnvelopeResult<NotificationKeys> {
372    if is_self_connection(publisher_pub, subscriber_pub) {
373        return Err(EnvelopeError::KeyExchange(
374            "publisher and subscriber keys are identical".into(),
375        ));
376    }
377
378    // XOR public keys for salt
379    let mut salt = [0u8; 32];
380    for i in 0..32 {
381        salt[i] = publisher_pub[i] ^ subscriber_pub[i];
382    }
383
384    // Build IKM: shared_secret || salt
385    let mut ikm = [0u8; 64];
386    ikm[..32].copy_from_slice(shared_secret);
387    ikm[32..64].copy_from_slice(&salt);
388
389    let enc_key = derive_key("hyprstream notification-keys v1 enc", &ikm);
390    let mac_key = derive_key("hyprstream notification-keys v1 mac", &ikm);
391
392    // Zeroize IKM containing shared secret
393    ikm.zeroize();
394
395    Ok(NotificationKeys {
396        enc_key: Zeroizing::new(enc_key),
397        mac_key: Zeroizing::new(mac_key),
398    })
399}
400
401/// Shared secret from DH key exchange.
402///
403/// Wrapped in `Zeroizing` to ensure secure erasure when dropped.
404#[derive(Clone)]
405pub struct SharedSecret(Zeroizing<[u8; 32]>);
406
407impl SharedSecret {
408    /// Create from raw bytes.
409    pub fn new(bytes: [u8; 32]) -> Self {
410        Self(Zeroizing::new(bytes))
411    }
412
413    /// Get the raw bytes (for HKDF input).
414    pub fn as_bytes(&self) -> &[u8; 32] {
415        &self.0
416    }
417
418    /// Derive a MAC key from this shared secret using the crypto backend.
419    ///
420    /// # Arguments
421    ///
422    /// * `request_id` - Used in IKM for domain separation
423    /// * `info` - Context info (e.g., "stream-hmac")
424    ///
425    /// # Backend
426    ///
427    /// - Default: Blake3 `derive_key()` with fixed context
428    /// - FIPS mode: HKDF-SHA256
429    pub fn derive_hmac_key(&self, request_id: u64, info: &[u8]) -> [u8; 32] {
430        // Fixed context string (not dynamic for security)
431        const CONTEXT: &str = "hyprstream hmac v1";
432
433        // Build IKM: shared_secret || request_id || info
434        let mut ikm = Vec::with_capacity(40 + info.len());
435        ikm.extend_from_slice(self.as_bytes());
436        ikm.extend_from_slice(&request_id.to_le_bytes());
437        ikm.extend_from_slice(info);
438
439        derive_key(CONTEXT, &ikm)
440    }
441}
442
443impl Zeroize for SharedSecret {
444    fn zeroize(&mut self) {
445        self.0.zeroize();
446    }
447}
448
449/// Trait for Diffie-Hellman key exchange implementations.
450///
451/// This trait abstracts over Ristretto255 (default) and ECDH P-256 (FIPS mode).
452pub trait KeyExchange: Send + Sync {
453    /// Secret key type (zeroized on drop).
454    type SecretKey: Zeroize + Clone;
455
456    /// Public key type.
457    type PublicKey: AsRef<[u8]> + Clone;
458
459    /// Generate a new keypair.
460    fn generate_keypair() -> (Self::SecretKey, Self::PublicKey);
461
462    /// Derive shared secret from our secret key and their public key.
463    fn derive_shared(
464        secret: &Self::SecretKey,
465        their_pubkey: &Self::PublicKey,
466    ) -> EnvelopeResult<SharedSecret>;
467
468    /// Deserialize a public key from bytes.
469    fn pubkey_from_bytes(bytes: &[u8]) -> EnvelopeResult<Self::PublicKey>;
470
471    /// Serialize a public key to bytes.
472    fn pubkey_to_bytes(pubkey: &Self::PublicKey) -> Vec<u8>;
473}
474
475// ============================================================================
476// Ristretto255 Implementation (default)
477// ============================================================================
478
479#[cfg(not(feature = "fips"))]
480mod ristretto_impl {
481    use super::*;
482    use curve25519_dalek::{
483        constants::RISTRETTO_BASEPOINT_POINT,
484        ristretto::{CompressedRistretto, RistrettoPoint},
485        scalar::Scalar,
486    };
487
488    /// Ristretto255 secret key (scalar).
489    ///
490    /// Zeroized on drop to prevent key material from lingering in memory.
491    #[derive(Clone)]
492    pub struct RistrettoSecret(Scalar);
493
494    impl RistrettoSecret {
495        /// Reconstruct a secret key from a scalar.
496        ///
497        /// Returns `None` if the scalar is zero (identity element, unsafe for DH).
498        pub fn from_scalar(scalar: Scalar) -> Option<Self> {
499            if bool::from(scalar.ct_eq(&Scalar::ZERO)) {
500                return None;
501            }
502            Some(Self(scalar))
503        }
504
505        /// Get the underlying scalar for DH computation.
506        pub fn scalar(&self) -> &Scalar {
507            &self.0
508        }
509    }
510
511    impl Zeroize for RistrettoSecret {
512        fn zeroize(&mut self) {
513            // Overwrite scalar with zero
514            self.0 = Scalar::ZERO;
515        }
516    }
517
518    impl Drop for RistrettoSecret {
519        fn drop(&mut self) {
520            self.zeroize();
521        }
522    }
523
524    /// Ristretto255 public key (compressed point).
525    ///
526    /// Stores the compressed form for efficient serialization.
527    #[derive(Clone, Copy, PartialEq, Eq)]
528    pub struct RistrettoPublic {
529        point: RistrettoPoint,
530        compressed: [u8; 32],
531    }
532
533    impl RistrettoPublic {
534        /// Create from a RistrettoPoint.
535        pub fn from_point(point: RistrettoPoint) -> Self {
536            let compressed = point.compress().to_bytes();
537            Self { point, compressed }
538        }
539
540        /// Get the underlying point for DH computation.
541        pub fn point(&self) -> &RistrettoPoint {
542            &self.point
543        }
544
545        /// Serialize to 32 bytes.
546        pub fn to_bytes(&self) -> [u8; 32] {
547            self.compressed
548        }
549
550        /// Deserialize from 32 bytes.
551        ///
552        /// Returns `None` if the encoding is invalid.
553        /// This is the primary defense against invalid points -
554        /// Ristretto255 rejects all non-canonical encodings.
555        pub fn from_bytes(bytes: &[u8; 32]) -> Option<Self> {
556            let compressed = CompressedRistretto::from_slice(bytes).ok()?;
557            let point = compressed.decompress()?;
558            Some(Self {
559                point,
560                compressed: *bytes,
561            })
562        }
563    }
564
565    impl AsRef<[u8]> for RistrettoPublic {
566        fn as_ref(&self) -> &[u8] {
567            &self.compressed
568        }
569    }
570
571    impl RistrettoPublic {
572        /// Deserialize from a byte slice (must be exactly 32 bytes).
573        ///
574        /// This is a convenience wrapper for streaming that handles &[u8] input.
575        pub fn from_slice(bytes: &[u8]) -> Option<Self> {
576            if bytes.len() != 32 {
577                return None;
578            }
579            let mut arr = [0u8; 32];
580            arr.copy_from_slice(bytes);
581            Self::from_bytes(&arr)
582        }
583    }
584
585    /// Ristretto255 key exchange implementation.
586    pub struct RistrettoKeyExchange;
587
588    impl KeyExchange for RistrettoKeyExchange {
589        type SecretKey = RistrettoSecret;
590        type PublicKey = RistrettoPublic;
591
592        fn generate_keypair() -> (Self::SecretKey, Self::PublicKey) {
593            let secret = Scalar::random(&mut rand::thread_rng());
594            let public_point = RISTRETTO_BASEPOINT_POINT * secret;
595            (
596                RistrettoSecret(secret),
597                RistrettoPublic::from_point(public_point),
598            )
599        }
600
601        fn derive_shared(
602            secret: &Self::SecretKey,
603            their_pubkey: &Self::PublicKey,
604        ) -> EnvelopeResult<SharedSecret> {
605            let shared_point = their_pubkey.point() * secret.scalar();
606            let shared_bytes = shared_point.compress().to_bytes();
607            Ok(SharedSecret::new(shared_bytes))
608        }
609
610        fn pubkey_from_bytes(bytes: &[u8]) -> EnvelopeResult<Self::PublicKey> {
611            if bytes.len() != 32 {
612                return Err(EnvelopeError::InvalidPublicKey {
613                    expected: 32,
614                    actual: bytes.len(),
615                });
616            }
617            let mut arr = [0u8; 32];
618            arr.copy_from_slice(bytes);
619            RistrettoPublic::from_bytes(&arr).ok_or_else(|| {
620                EnvelopeError::KeyExchange("invalid ristretto255 point encoding".into())
621            })
622        }
623
624        fn pubkey_to_bytes(pubkey: &Self::PublicKey) -> Vec<u8> {
625            pubkey.to_bytes().to_vec()
626        }
627    }
628
629    /// Generate an ephemeral Ristretto255 keypair (for one-time use in requests).
630    pub fn generate_ephemeral_keypair() -> (RistrettoSecret, RistrettoPublic) {
631        RistrettoKeyExchange::generate_keypair()
632    }
633
634    /// Perform Ristretto255 Diffie-Hellman and return shared secret bytes.
635    pub fn ristretto_dh(secret: &RistrettoSecret, their_public: &RistrettoPublic) -> [u8; 32] {
636        let shared_point = their_public.point() * secret.scalar();
637        shared_point.compress().to_bytes()
638    }
639
640    /// Rerandomize a Ristretto255 public key: `blinded = pubkey + r * G`.
641    ///
642    /// Used by NotificationService to make subscriber pubkeys unlinkable across
643    /// different publish intents. Each intent uses a fresh random blinding scalar.
644    ///
645    /// Returns `(blinded_pubkey, blinding_scalar_bytes)`.
646    pub fn rerandomize_pubkey(pubkey: &RistrettoPublic) -> (RistrettoPublic, [u8; 32]) {
647        let r = Scalar::random(&mut rand::thread_rng());
648        let blinded_point = pubkey.point() + r * RISTRETTO_BASEPOINT_POINT;
649        let blinded = RistrettoPublic::from_point(blinded_point);
650        (blinded, r.to_bytes())
651    }
652
653    /// Perform blinding-aware DH: `shared = (secret + blinding_scalar) * their_pubkey`.
654    ///
655    /// Used by subscribers who received a blinding scalar `r_i` from the
656    /// NotificationService. The subscriber computes `(s_sub + r_i) * P_pub`,
657    /// which equals the publisher's `s_pub * (P_sub + r_i * G)` by DH commutativity.
658    ///
659    /// # Errors
660    ///
661    /// Returns error if:
662    /// - The blinding scalar bytes are not a valid Ristretto scalar
663    /// - The resulting combined scalar is zero
664    pub fn blinded_dh(
665        secret: &RistrettoSecret,
666        blinding_scalar_bytes: &[u8; 32],
667        their_pubkey: &RistrettoPublic,
668    ) -> EnvelopeResult<[u8; 32]> {
669        let r = Scalar::from_canonical_bytes(*blinding_scalar_bytes)
670            .into_option()
671            .ok_or_else(|| EnvelopeError::KeyExchange("invalid blinding scalar".into()))?;
672        let combined = secret.scalar() + r;
673        if bool::from(combined.ct_eq(&Scalar::ZERO)) {
674            return Err(EnvelopeError::KeyExchange("combined scalar is zero".into()));
675        }
676        let shared_point = their_pubkey.point() * combined;
677        Ok(shared_point.compress().to_bytes())
678    }
679
680    // =========================================================================
681    // Raw-bytes DH wrappers (for notification broadcast encryption)
682    // =========================================================================
683
684    /// Ristretto255 DH from raw scalar and pubkey bytes.
685    ///
686    /// Used by `BroadcastEncryptor` where typed key objects aren't available.
687    pub fn ristretto_dh_raw(
688        secret_bytes: &[u8; 32],
689        their_pub_bytes: &[u8; 32],
690    ) -> EnvelopeResult<[u8; 32]> {
691        let scalar = Scalar::from_canonical_bytes(*secret_bytes)
692            .into_option()
693            .ok_or_else(|| EnvelopeError::KeyExchange("invalid secret scalar".into()))?;
694        let compressed = CompressedRistretto::from_slice(their_pub_bytes)
695            .map_err(|_| EnvelopeError::KeyExchange("invalid public key length".into()))?;
696        let point = compressed
697            .decompress()
698            .ok_or_else(|| EnvelopeError::KeyExchange("invalid ristretto255 point".into()))?;
699        Ok((point * scalar).compress().to_bytes())
700    }
701
702    /// Blinding-aware DH from raw bytes: `(secret + blinding_scalar) * their_pubkey`.
703    ///
704    /// Used by `BroadcastDecryptor` where typed key objects aren't available.
705    pub fn blinded_dh_raw(
706        secret_bytes: &[u8; 32],
707        blinding_scalar_bytes: &[u8; 32],
708        their_pub_bytes: &[u8; 32],
709    ) -> EnvelopeResult<[u8; 32]> {
710        let s = Scalar::from_canonical_bytes(*secret_bytes)
711            .into_option()
712            .ok_or_else(|| EnvelopeError::KeyExchange("invalid subscriber secret".into()))?;
713        let r = Scalar::from_canonical_bytes(*blinding_scalar_bytes)
714            .into_option()
715            .ok_or_else(|| EnvelopeError::KeyExchange("invalid blinding scalar".into()))?;
716        let combined = s + r;
717        if bool::from(combined.ct_eq(&Scalar::ZERO)) {
718            return Err(EnvelopeError::KeyExchange("combined scalar is zero".into()));
719        }
720        let compressed = CompressedRistretto::from_slice(their_pub_bytes)
721            .map_err(|_| EnvelopeError::KeyExchange("invalid public key length".into()))?;
722        let point = compressed
723            .decompress()
724            .ok_or_else(|| EnvelopeError::KeyExchange("invalid ristretto255 point".into()))?;
725        Ok((point * combined).compress().to_bytes())
726    }
727
728    /// Reconstruct a blinded pubkey from raw bytes: `P_sub + r * G`.
729    pub fn reconstruct_blinded_pub_raw(
730        subscriber_pub_bytes: &[u8; 32],
731        blinding_scalar_bytes: &[u8; 32],
732    ) -> EnvelopeResult<[u8; 32]> {
733        let r = Scalar::from_canonical_bytes(*blinding_scalar_bytes)
734            .into_option()
735            .ok_or_else(|| EnvelopeError::KeyExchange("invalid blinding scalar".into()))?;
736        let compressed = CompressedRistretto::from_slice(subscriber_pub_bytes)
737            .map_err(|_| EnvelopeError::KeyExchange("invalid subscriber pubkey length".into()))?;
738        let sub_point = compressed.decompress().ok_or_else(|| {
739            EnvelopeError::KeyExchange("invalid subscriber ristretto point".into())
740        })?;
741        let blinded = sub_point + r * RISTRETTO_BASEPOINT_POINT;
742        Ok(blinded.compress().to_bytes())
743    }
744}
745
746#[cfg(not(feature = "fips"))]
747pub use ristretto_impl::{
748    blinded_dh, blinded_dh_raw, generate_ephemeral_keypair, reconstruct_blinded_pub_raw,
749    rerandomize_pubkey, ristretto_dh, ristretto_dh_raw, RistrettoKeyExchange, RistrettoPublic,
750    RistrettoSecret,
751};
752
753// ============================================================================
754// ECDH P-256 Implementation (FIPS mode)
755// ============================================================================
756
757#[cfg(feature = "fips")]
758mod p256_impl {
759    use super::*;
760    use p256::{
761        elliptic_curve::sec1::{FromEncodedPoint, ToEncodedPoint},
762        EncodedPoint, PublicKey, SecretKey,
763    };
764
765    /// P-256 secret key wrapper with Zeroize.
766    #[derive(Clone)]
767    pub struct P256SecretKey(SecretKey);
768
769    impl Zeroize for P256SecretKey {
770        fn zeroize(&mut self) {
771            // SecretKey uses NonZeroScalar which is zeroized on drop
772        }
773    }
774
775    /// P-256 public key wrapper.
776    #[derive(Clone)]
777    pub struct P256PublicKey(PublicKey);
778
779    impl P256PublicKey {
780        /// Deserialize from a byte slice (33-byte compressed or 65-byte uncompressed).
781        ///
782        /// Note: P-256 keys are NOT compatible with the 32-byte Ristretto format.
783        /// This method returns None for 32-byte inputs.
784        pub fn from_slice(bytes: &[u8]) -> Option<Self> {
785            // P-256 uses SEC1 encoding: 33 bytes compressed, 65 bytes uncompressed
786            // 32-byte inputs are invalid for P-256
787            let point = EncodedPoint::from_bytes(bytes).ok()?;
788            let pubkey: Option<PublicKey> = PublicKey::from_encoded_point(&point).into();
789            pubkey.map(P256PublicKey)
790        }
791
792        /// Serialize to compressed SEC1 format (33 bytes).
793        pub fn to_bytes(&self) -> Vec<u8> {
794            self.0.to_encoded_point(true).as_bytes().to_vec()
795        }
796    }
797
798    impl AsRef<[u8]> for P256PublicKey {
799        fn as_ref(&self) -> &[u8] {
800            // Note: This returns an empty slice because we can't return a reference
801            // to temporary data. Use to_bytes() for serialization instead.
802            &[]
803        }
804    }
805
806    /// ECDH P-256 key exchange implementation.
807    pub struct EcdhP256KeyExchange;
808
809    impl KeyExchange for EcdhP256KeyExchange {
810        type SecretKey = P256SecretKey;
811        type PublicKey = P256PublicKey;
812
813        fn generate_keypair() -> (Self::SecretKey, Self::PublicKey) {
814            let secret = SecretKey::random(&mut rand::thread_rng());
815            let public = secret.public_key();
816            (P256SecretKey(secret), P256PublicKey(public))
817        }
818
819        fn derive_shared(
820            secret: &Self::SecretKey,
821            their_pubkey: &Self::PublicKey,
822        ) -> EnvelopeResult<SharedSecret> {
823            use p256::ecdh::diffie_hellman;
824
825            let shared = diffie_hellman(secret.0.to_nonzero_scalar(), their_pubkey.0.as_affine());
826            let mut bytes = [0u8; 32];
827            bytes.copy_from_slice(shared.raw_secret_bytes());
828            Ok(SharedSecret::new(bytes))
829        }
830
831        fn pubkey_from_bytes(bytes: &[u8]) -> EnvelopeResult<Self::PublicKey> {
832            let point =
833                EncodedPoint::from_bytes(bytes).map_err(|_| EnvelopeError::InvalidPublicKey {
834                    expected: 33, // compressed
835                    actual: bytes.len(),
836                })?;
837            let pubkey: Option<PublicKey> = PublicKey::from_encoded_point(&point).into();
838            pubkey
839                .map(P256PublicKey)
840                .ok_or(EnvelopeError::InvalidPublicKey {
841                    expected: 33,
842                    actual: bytes.len(),
843                })
844        }
845
846        fn pubkey_to_bytes(pubkey: &Self::PublicKey) -> Vec<u8> {
847            pubkey.0.to_encoded_point(true).as_bytes().to_vec()
848        }
849    }
850
851    /// Generate an ephemeral P-256 keypair (FIPS mode).
852    pub fn generate_ephemeral_keypair() -> (P256SecretKey, P256PublicKey) {
853        EcdhP256KeyExchange::generate_keypair()
854    }
855
856    /// Perform P-256 ECDH and return shared secret bytes.
857    ///
858    /// FIPS-mode equivalent of `ristretto_dh()`.
859    pub fn p256_dh(secret: &P256SecretKey, their_public: &P256PublicKey) -> [u8; 32] {
860        use p256::ecdh::diffie_hellman;
861
862        let shared = diffie_hellman(secret.0.to_nonzero_scalar(), their_public.0.as_affine());
863        let mut bytes = [0u8; 32];
864        bytes.copy_from_slice(shared.raw_secret_bytes());
865        bytes
866    }
867}
868
869#[cfg(feature = "fips")]
870pub use p256_impl::{
871    generate_ephemeral_keypair, p256_dh, EcdhP256KeyExchange, P256PublicKey, P256SecretKey,
872};
873
874// ============================================================================
875// Default Key Exchange Type
876// ============================================================================
877
878/// Default key exchange algorithm based on feature flags.
879#[cfg(not(feature = "fips"))]
880pub type DefaultKeyExchange = RistrettoKeyExchange;
881
882#[cfg(feature = "fips")]
883pub type DefaultKeyExchange = EcdhP256KeyExchange;
884
885#[cfg(test)]
886mod tests {
887    use super::*;
888
889    #[test]
890    fn test_key_exchange_roundtrip() -> Result<(), Box<dyn std::error::Error>> {
891        // Generate two keypairs
892        let (secret_a, public_a) = DefaultKeyExchange::generate_keypair();
893        let (secret_b, public_b) = DefaultKeyExchange::generate_keypair();
894
895        // Both sides derive the same shared secret
896        let shared_a = DefaultKeyExchange::derive_shared(&secret_a, &public_b)?;
897        let shared_b = DefaultKeyExchange::derive_shared(&secret_b, &public_a)?;
898
899        assert_eq!(shared_a.as_bytes(), shared_b.as_bytes());
900        Ok(())
901    }
902
903    #[test]
904    fn test_hmac_key_derivation() -> Result<(), Box<dyn std::error::Error>> {
905        let (secret_a, public_a) = DefaultKeyExchange::generate_keypair();
906        let (secret_b, public_b) = DefaultKeyExchange::generate_keypair();
907
908        let shared_a = DefaultKeyExchange::derive_shared(&secret_a, &public_b)?;
909        let shared_b = DefaultKeyExchange::derive_shared(&secret_b, &public_a)?;
910
911        let request_id = 12345u64;
912        let hmac_key_a = shared_a.derive_hmac_key(request_id, b"stream-hmac");
913        let hmac_key_b = shared_b.derive_hmac_key(request_id, b"stream-hmac");
914
915        assert_eq!(hmac_key_a, hmac_key_b);
916        Ok(())
917    }
918
919    #[test]
920    fn test_different_request_ids_different_keys() -> Result<(), Box<dyn std::error::Error>> {
921        let (_secret_a, public_a) = DefaultKeyExchange::generate_keypair();
922        let (secret_b, _public_b) = DefaultKeyExchange::generate_keypair();
923
924        let shared = DefaultKeyExchange::derive_shared(&secret_b, &public_a)?;
925
926        let key1 = shared.derive_hmac_key(1, b"stream-hmac");
927        let key2 = shared.derive_hmac_key(2, b"stream-hmac");
928
929        assert_ne!(key1, key2);
930        Ok(())
931    }
932
933    #[test]
934    fn test_pubkey_serialization_roundtrip() -> Result<(), Box<dyn std::error::Error>> {
935        let (_secret, public) = DefaultKeyExchange::generate_keypair();
936
937        let bytes = DefaultKeyExchange::pubkey_to_bytes(&public);
938        let restored = DefaultKeyExchange::pubkey_from_bytes(&bytes)?;
939
940        assert_eq!(
941            DefaultKeyExchange::pubkey_to_bytes(&public),
942            DefaultKeyExchange::pubkey_to_bytes(&restored)
943        );
944        Ok(())
945    }
946
947    #[cfg(not(feature = "fips"))]
948    #[test]
949    fn test_invalid_ristretto_encoding_rejected() {
950        // Note: All-zeros is the identity point in Ristretto255 (valid encoding)
951        // We need to use truly invalid encodings
952
953        // All 0xFF is not a valid Ristretto encoding (with high probability)
954        let garbage = [0xffu8; 32];
955        let result = RistrettoPublic::from_bytes(&garbage);
956        assert!(result.is_none(), "0xFF bytes should be rejected");
957
958        // A point with the high bit set incorrectly (non-canonical)
959        let mut invalid = [0u8; 32];
960        invalid[31] = 0x80; // Set high bit - invalid for Ristretto
961        let result = RistrettoPublic::from_bytes(&invalid);
962        assert!(
963            result.is_none(),
964            "Non-canonical encoding should be rejected"
965        );
966    }
967
968    #[cfg(not(feature = "fips"))]
969    #[test]
970    fn test_ristretto_dh_function() {
971        let (client_secret, client_public) = generate_ephemeral_keypair();
972        let (server_secret, server_public) = generate_ephemeral_keypair();
973
974        // Both compute shared secret
975        let client_shared = ristretto_dh(&client_secret, &server_public);
976        let server_shared = ristretto_dh(&server_secret, &client_public);
977
978        assert_eq!(client_shared, server_shared);
979    }
980
981    // =========================================================================
982    // Stream key derivation tests
983    // =========================================================================
984
985    #[test]
986    fn test_derive_stream_keys_deterministic() -> Result<(), Box<dyn std::error::Error>> {
987        // Same inputs should produce same outputs
988        let shared_secret = [0x42u8; 32];
989        let client_pub = [0x01u8; 32];
990        let server_pub = [0x02u8; 32];
991
992        let keys1 = derive_stream_keys(&shared_secret, &client_pub, &server_pub)?;
993        let keys2 = derive_stream_keys(&shared_secret, &client_pub, &server_pub)?;
994
995        assert_eq!(keys1.topic, keys2.topic);
996        assert_eq!(*keys1.mac_key, *keys2.mac_key);
997        Ok(())
998    }
999
1000    #[test]
1001    fn test_derive_stream_keys_enc_key_distinct_and_deterministic(
1002    ) -> Result<(), Box<dyn std::error::Error>> {
1003        // #321: the AEAD enc_key must be deterministic, key-separated from mac_key,
1004        // and distinct from the control keys (own derivation context).
1005        let shared_secret = [0x42u8; 32];
1006        let client_pub = [0x01u8; 32];
1007        let server_pub = [0x02u8; 32];
1008
1009        let keys1 = derive_stream_keys(&shared_secret, &client_pub, &server_pub)?;
1010        let keys2 = derive_stream_keys(&shared_secret, &client_pub, &server_pub)?;
1011
1012        assert_eq!(
1013            *keys1.enc_key, *keys2.enc_key,
1014            "enc_key must be deterministic"
1015        );
1016        assert_ne!(
1017            *keys1.enc_key, *keys1.mac_key,
1018            "enc_key must differ from mac_key"
1019        );
1020        assert_ne!(
1021            *keys1.enc_key, *keys1.ctrl_mac_key,
1022            "enc_key must differ from ctrl_mac_key"
1023        );
1024        Ok(())
1025    }
1026
1027    #[test]
1028    fn test_derive_stream_keys_symmetric() -> Result<(), Box<dyn std::error::Error>> {
1029        // Order of pubkeys shouldn't matter (XOR is commutative)
1030        let shared_secret = [0x42u8; 32];
1031        let client_pub = [0x01u8; 32];
1032        let server_pub = [0x02u8; 32];
1033
1034        let keys1 = derive_stream_keys(&shared_secret, &client_pub, &server_pub)?;
1035        let keys2 = derive_stream_keys(&shared_secret, &server_pub, &client_pub)?;
1036
1037        // Both should produce identical keys (XOR is commutative)
1038        assert_eq!(keys1.topic, keys2.topic);
1039        assert_eq!(*keys1.mac_key, *keys2.mac_key);
1040        Ok(())
1041    }
1042
1043    #[test]
1044    fn test_derive_stream_keys_different_secrets() -> Result<(), Box<dyn std::error::Error>> {
1045        let client_pub = [0x01u8; 32];
1046        let server_pub = [0x02u8; 32];
1047
1048        let keys1 = derive_stream_keys(&[0x11u8; 32], &client_pub, &server_pub)?;
1049        let keys2 = derive_stream_keys(&[0x22u8; 32], &client_pub, &server_pub)?;
1050
1051        assert_ne!(keys1.topic, keys2.topic);
1052        assert_ne!(*keys1.mac_key, *keys2.mac_key);
1053        Ok(())
1054    }
1055
1056    #[test]
1057    fn test_derive_stream_keys_different_pubkeys() -> Result<(), Box<dyn std::error::Error>> {
1058        let shared_secret = [0x42u8; 32];
1059
1060        let keys1 = derive_stream_keys(&shared_secret, &[0x01u8; 32], &[0x02u8; 32])?;
1061        let keys2 = derive_stream_keys(&shared_secret, &[0x03u8; 32], &[0x04u8; 32])?;
1062
1063        assert_ne!(keys1.topic, keys2.topic);
1064        assert_ne!(*keys1.mac_key, *keys2.mac_key);
1065        Ok(())
1066    }
1067
1068    #[test]
1069    fn test_derive_stream_keys_topic_is_hex() -> Result<(), Box<dyn std::error::Error>> {
1070        let shared_secret = [0x42u8; 32];
1071        let client_pub = [0x01u8; 32];
1072        let server_pub = [0x02u8; 32];
1073
1074        let keys = derive_stream_keys(&shared_secret, &client_pub, &server_pub)?;
1075
1076        // Topic should be 64 hex chars
1077        assert_eq!(keys.topic.len(), 64);
1078        assert!(keys.topic.chars().all(|c| c.is_ascii_hexdigit()));
1079        Ok(())
1080    }
1081
1082    #[test]
1083    fn test_derive_stream_keys_topic_prefix() -> Result<(), Box<dyn std::error::Error>> {
1084        let shared_secret = [0x42u8; 32];
1085        let client_pub = [0x01u8; 32];
1086        let server_pub = [0x02u8; 32];
1087
1088        let keys = derive_stream_keys(&shared_secret, &client_pub, &server_pub)?;
1089        let prefix = keys.topic_prefix_bytes()?;
1090
1091        // Prefix should be first 16 bytes of topic
1092        assert_eq!(prefix.len(), 16);
1093
1094        // Verify it matches the topic
1095        let expected_prefix = hex::decode(&keys.topic[..32])?;
1096        assert_eq!(&prefix[..], &expected_prefix[..]);
1097        Ok(())
1098    }
1099
1100    #[test]
1101    fn test_derive_stream_keys_rejects_self_connection() {
1102        let shared_secret = [0x42u8; 32];
1103        let same_key = [0x01u8; 32];
1104
1105        let result = derive_stream_keys(&shared_secret, &same_key, &same_key);
1106        assert!(
1107            matches!(result, Err(EnvelopeError::KeyExchange(ref msg)) if msg.contains("identical")),
1108            "Should reject self-connection"
1109        );
1110    }
1111
1112    #[cfg(not(feature = "fips"))]
1113    #[test]
1114    fn test_derive_stream_keys_with_real_dh() -> Result<(), Box<dyn std::error::Error>> {
1115        // Full integration test with actual DH key exchange
1116        let (client_secret, client_pubkey) = generate_ephemeral_keypair();
1117        let (server_secret, server_pubkey) = generate_ephemeral_keypair();
1118
1119        // Both sides compute shared secret
1120        let client_shared = ristretto_dh(&client_secret, &server_pubkey);
1121        let server_shared = ristretto_dh(&server_secret, &client_pubkey);
1122
1123        // Both sides derive stream keys
1124        let client_keys = derive_stream_keys(
1125            &client_shared,
1126            &client_pubkey.to_bytes(),
1127            &server_pubkey.to_bytes(),
1128        )?;
1129
1130        let server_keys = derive_stream_keys(
1131            &server_shared,
1132            &client_pubkey.to_bytes(),
1133            &server_pubkey.to_bytes(),
1134        )?;
1135
1136        // Keys should be identical
1137        assert_eq!(client_keys.topic, server_keys.topic);
1138        assert_eq!(*client_keys.mac_key, *server_keys.mac_key);
1139        Ok(())
1140    }
1141
1142    #[cfg(not(feature = "fips"))]
1143    #[test]
1144    fn test_stream_keys_e2e_mac_verification() -> Result<(), Box<dyn std::error::Error>> {
1145        use crate::crypto::StreamHmacState;
1146
1147        // Full E2E test: DH → stream keys → MAC chain (matches wire format)
1148        let (client_secret, client_pubkey) = generate_ephemeral_keypair();
1149        let (server_secret, server_pubkey) = generate_ephemeral_keypair();
1150
1151        let client_shared = ristretto_dh(&client_secret, &server_pubkey);
1152        let server_shared = ristretto_dh(&server_secret, &client_pubkey);
1153
1154        let client_keys = derive_stream_keys(
1155            &client_shared,
1156            &client_pubkey.to_bytes(),
1157            &server_pubkey.to_bytes(),
1158        )?;
1159
1160        let server_keys = derive_stream_keys(
1161            &server_shared,
1162            &client_pubkey.to_bytes(),
1163            &server_pubkey.to_bytes(),
1164        )?;
1165
1166        // Both sides should derive identical topic + mac_key
1167        assert_eq!(client_keys.topic, server_keys.topic);
1168
1169        // Server produces 16-byte truncated MACs (wire format)
1170        let mut producer = StreamHmacState::new(*server_keys.mac_key, server_keys.topic.clone());
1171        let mac1 = producer.compute_next(b"token 1");
1172        let mac2 = producer.compute_next(b"token 2");
1173        let mac3 = producer.compute_next(b"[DONE]");
1174
1175        // Client verifies the same chain
1176        let mut verifier = StreamHmacState::new(*client_keys.mac_key, client_keys.topic);
1177        assert!(verifier.verify_next(b"token 1", &mac1));
1178        assert!(verifier.verify_next(b"token 2", &mac2));
1179        assert!(verifier.verify_next(b"[DONE]", &mac3));
1180        Ok(())
1181    }
1182
1183    // =========================================================================
1184    // Control channel key derivation tests (Part 7)
1185    // =========================================================================
1186
1187    #[test]
1188    fn test_ctrl_keys_differ_from_data_keys() -> Result<(), Box<dyn std::error::Error>> {
1189        let shared_secret = [0x42u8; 32];
1190        let client_pub = [0x01u8; 32];
1191        let server_pub = [0x02u8; 32];
1192
1193        let keys = derive_stream_keys(&shared_secret, &client_pub, &server_pub)?;
1194
1195        assert_ne!(
1196            keys.topic, keys.ctrl_topic,
1197            "ctrl_topic must differ from data topic"
1198        );
1199        assert_ne!(
1200            *keys.mac_key, *keys.ctrl_mac_key,
1201            "ctrl_mac_key must differ from data mac_key"
1202        );
1203        Ok(())
1204    }
1205
1206    #[test]
1207    fn test_ctrl_keys_deterministic() -> Result<(), Box<dyn std::error::Error>> {
1208        let shared_secret = [0x42u8; 32];
1209        let client_pub = [0x01u8; 32];
1210        let server_pub = [0x02u8; 32];
1211
1212        let keys1 = derive_stream_keys(&shared_secret, &client_pub, &server_pub)?;
1213        let keys2 = derive_stream_keys(&shared_secret, &client_pub, &server_pub)?;
1214
1215        assert_eq!(keys1.ctrl_topic, keys2.ctrl_topic);
1216        assert_eq!(*keys1.ctrl_mac_key, *keys2.ctrl_mac_key);
1217        Ok(())
1218    }
1219
1220    #[test]
1221    fn test_ctrl_keys_symmetric() -> Result<(), Box<dyn std::error::Error>> {
1222        let shared_secret = [0x42u8; 32];
1223        let client_pub = [0x01u8; 32];
1224        let server_pub = [0x02u8; 32];
1225
1226        let keys1 = derive_stream_keys(&shared_secret, &client_pub, &server_pub)?;
1227        let keys2 = derive_stream_keys(&shared_secret, &server_pub, &client_pub)?;
1228
1229        assert_eq!(keys1.ctrl_topic, keys2.ctrl_topic);
1230        assert_eq!(*keys1.ctrl_mac_key, *keys2.ctrl_mac_key);
1231        Ok(())
1232    }
1233
1234    #[test]
1235    fn test_ctrl_topic_is_hex() -> Result<(), Box<dyn std::error::Error>> {
1236        let shared_secret = [0x42u8; 32];
1237        let client_pub = [0x01u8; 32];
1238        let server_pub = [0x02u8; 32];
1239
1240        let keys = derive_stream_keys(&shared_secret, &client_pub, &server_pub)?;
1241
1242        assert_eq!(keys.ctrl_topic.len(), 64);
1243        assert!(keys.ctrl_topic.chars().all(|c| c.is_ascii_hexdigit()));
1244        Ok(())
1245    }
1246
1247    #[cfg(not(feature = "fips"))]
1248    #[test]
1249    fn test_ctrl_keys_with_real_dh() -> Result<(), Box<dyn std::error::Error>> {
1250        let (client_secret, client_pubkey) = generate_ephemeral_keypair();
1251        let (server_secret, server_pubkey) = generate_ephemeral_keypair();
1252
1253        let client_shared = ristretto_dh(&client_secret, &server_pubkey);
1254        let server_shared = ristretto_dh(&server_secret, &client_pubkey);
1255
1256        let client_keys = derive_stream_keys(
1257            &client_shared,
1258            &client_pubkey.to_bytes(),
1259            &server_pubkey.to_bytes(),
1260        )?;
1261        let server_keys = derive_stream_keys(
1262            &server_shared,
1263            &client_pubkey.to_bytes(),
1264            &server_pubkey.to_bytes(),
1265        )?;
1266
1267        // Both sides derive identical control keys
1268        assert_eq!(client_keys.ctrl_topic, server_keys.ctrl_topic);
1269        assert_eq!(*client_keys.ctrl_mac_key, *server_keys.ctrl_mac_key);
1270
1271        // Control keys differ from data keys
1272        assert_ne!(client_keys.topic, client_keys.ctrl_topic);
1273        assert_ne!(*client_keys.mac_key, *client_keys.ctrl_mac_key);
1274        Ok(())
1275    }
1276}
1277
1278#[cfg(test)]
1279#[allow(clippy::unwrap_used)]
1280mod hybrid_stream_tests {
1281    use super::*;
1282    use crate::crypto::hybrid_kem::{generate_recipient, SuiteId};
1283
1284    #[test]
1285    fn hybrid_stream_handshake_roundtrip() {
1286        // Client makes a fresh ephemeral hybrid keypair + sends its public; server
1287        // encapsulates + derives keys; client decapsulates + derives the SAME keys.
1288        let client_kp = generate_recipient(SuiteId::HyKemX25519MlKem768).unwrap();
1289        let client_pub_enc = client_kp.public().encode();
1290
1291        let (material, server_keys) = server_hybrid_stream_keys(&client_pub_enc).unwrap();
1292        let client_keys = client_hybrid_stream_keys(&client_kp, &material.encode()).unwrap();
1293
1294        assert_eq!(server_keys.topic, client_keys.topic);
1295        assert_eq!(*server_keys.mac_key, *client_keys.mac_key);
1296        assert_eq!(*server_keys.enc_key, *client_keys.enc_key);
1297        assert_eq!(server_keys.ctrl_topic, client_keys.ctrl_topic);
1298        assert_eq!(*server_keys.ctrl_mac_key, *client_keys.ctrl_mac_key);
1299    }
1300
1301    #[test]
1302    fn hybrid_stream_wrong_keypair_diverges() {
1303        let client_kp = generate_recipient(SuiteId::HyKemX25519MlKem768).unwrap();
1304        let (material, server_keys) =
1305            server_hybrid_stream_keys(&client_kp.public().encode()).unwrap();
1306        // A different keypair → different decapsulated secret (ML-KEM implicit
1307        // rejection + different X25519 DH) AND a different transcript salt → keys diverge.
1308        let other_kp = generate_recipient(SuiteId::HyKemX25519MlKem768).unwrap();
1309        let other_keys = client_hybrid_stream_keys(&other_kp, &material.encode()).unwrap();
1310        assert_ne!(server_keys.topic, other_keys.topic);
1311        assert_ne!(*server_keys.mac_key, *other_keys.mac_key);
1312    }
1313
1314    #[test]
1315    fn hybrid_stream_rejects_malformed_client_public() {
1316        // Fail-closed: a classical-only / missing / garbage clientKemPublic is rejected.
1317        assert!(server_hybrid_stream_keys(b"not a recipient public").is_err());
1318        assert!(server_hybrid_stream_keys(&[]).is_err());
1319    }
1320
1321    #[test]
1322    fn hybrid_stream_rejects_malformed_ciphertexts() {
1323        let client_kp = generate_recipient(SuiteId::HyKemX25519MlKem768).unwrap();
1324        assert!(client_hybrid_stream_keys(&client_kp, b"garbage").is_err());
1325        assert!(client_hybrid_stream_keys(&client_kp, &[]).is_err());
1326    }
1327
1328    #[test]
1329    fn epoch_ratchet_is_one_way_and_deterministic() {
1330        let k0 = [7u8; 32];
1331        let k1 = ratchet_stream_key(&k0);
1332        let k1b = ratchet_stream_key(&k0);
1333        assert_eq!(*k1, *k1b, "ratchet must be deterministic");
1334        assert_ne!(*k1, k0, "ratchet must advance the key");
1335        let k2 = ratchet_stream_key(&k1);
1336        assert_ne!(*k2, *k1, "each epoch key differs");
1337    }
1338}