Skip to main content

hyprstream_rpc/
stream_epoch.rs

1//! Identified point-to-point stream epoch cryptography (#554).
2//!
3//! This module is deliberately carrier-neutral.  A stock MOQT relay forwards the
4//! resulting encrypted Object bytes without learning this transcript or any key.
5//! Network key release remains gated by #726; the types here make the authority
6//! input explicit without implementing the restricted-anonymous work in
7//! #1060-#1062.
8
9use anyhow::{ensure, Result};
10use subtle::ConstantTimeEq;
11use zeroize::Zeroizing;
12
13use crate::crypto::backend::{derive_key, keyed_mac};
14use crate::crypto::hybrid_kem::SuiteId;
15
16/// The only stream KEM suite accepted by this profile.
17pub const IDENTIFIED_STREAM_SUITE: SuiteId = SuiteId::HyKemX25519MlKem768;
18/// Protocol/domain version included in every canonical transcript.
19pub const IDENTIFIED_STREAM_VERSION: u16 = 1;
20
21const SESSION_ROOT_DOMAIN: &str = "hyprstream identified-stream session-root v1";
22const BINDING_HASH_DOMAIN: &str = "hyprstream identified-stream binding-hash v1";
23const ROUTE_TOPIC_DOMAIN: &str = "hyprstream identified-stream route-topic v1";
24const CONTROL_TOPIC_DOMAIN: &str = "hyprstream identified-stream control-topic v1";
25const EPOCH_SECRET_DOMAIN: &str = "hyprstream identified-stream epoch-ratchet v1";
26const DATA_MAC_DOMAIN: &str = "hyprstream identified-stream data-mac v1";
27const DATA_AEAD_DOMAIN: &str = "hyprstream identified-stream data-aead v1";
28const CONTROL_MAC_DOMAIN: &str = "hyprstream identified-stream control-mac v1";
29const REKEY_AUTH_DOMAIN: &str = "hyprstream identified-stream rekey-auth v1";
30const NONCE_DOMAIN: &str = "hyprstream identified-stream nonce-domain v1";
31const EPOCH_NAMESPACE_DOMAIN: &str = "hyprstream identified-stream epoch-namespace v1";
32const CONTROL_OBJECT_MAGIC: &[u8; 8] = b"HYSEPK01";
33const CONTROL_OBJECT_LEN: usize = 154;
34
35const MAX_TEXT: usize = 1024;
36const MAX_CAPABILITY: usize = 4096;
37
38/// Carrier profile selected by signed resolution/admission policy.
39#[derive(Clone, Copy, Debug, PartialEq, Eq)]
40#[repr(u8)]
41pub enum StreamCarrierProfile {
42    /// Hyprstream owns the endpoint and requires its hybrid transport policy.
43    OwnedHybridTransport = 1,
44    /// A standards-compatible relay is an explicitly untrusted classical carrier.
45    StandardPublicRelay = 2,
46}
47
48/// The selected route's role in the stream transcript.
49#[derive(Clone, Copy, Debug, PartialEq, Eq)]
50#[repr(u8)]
51pub enum StreamRouteRole {
52    Direct = 1,
53    Relay = 2,
54}
55
56/// Direction is a key and nonce domain, never merely descriptive metadata.
57#[derive(Clone, Copy, Debug, PartialEq, Eq)]
58#[repr(u8)]
59pub enum StreamDirection {
60    ProducerToConsumer = 1,
61    ConsumerToProducer = 2,
62}
63
64/// Accepted-current identity state frozen into the stream authorization.
65#[derive(Clone, Debug, PartialEq, Eq)]
66pub struct StreamAcceptedState {
67    pub identity_did: String,
68    pub digest: [u8; 64],
69    pub epoch: u64,
70}
71
72impl StreamAcceptedState {
73    fn validate(&self, label: &str) -> Result<()> {
74        validate_did(&self.identity_did, label)?;
75        ensure!(
76            self.digest.iter().any(|byte| *byte != 0),
77            "{label} accepted-state digest is all zero"
78        );
79        Ok(())
80    }
81}
82
83/// Complete identified-session binding consumed by HyKEM and every epoch KDF.
84///
85/// `consumer_state.identity_did` is the identified principal.  Anonymous key
86/// release intentionally has no constructor in this slice.
87#[derive(Clone, Debug, PartialEq, Eq)]
88pub struct IdentifiedStreamBinding {
89    carrier_profile: StreamCarrierProfile,
90    route_role: StreamRouteRole,
91    producer_endpoint_did: String,
92    consumer_endpoint_did: String,
93    producer_state: StreamAcceptedState,
94    consumer_state: StreamAcceptedState,
95    service: String,
96    capability: String,
97    track: String,
98    producer_kem_key_id: String,
99    consumer_kem_key_id: String,
100    max_blocks_per_epoch: u64,
101    suite: SuiteId,
102}
103
104impl IdentifiedStreamBinding {
105    /// Build the pinned identified profile.  Suite negotiation is intentionally
106    /// absent: callers cannot request a classical-only or unknown suite.
107    #[allow(clippy::too_many_arguments)]
108    pub fn new(
109        carrier_profile: StreamCarrierProfile,
110        route_role: StreamRouteRole,
111        producer_endpoint_did: impl Into<String>,
112        consumer_endpoint_did: impl Into<String>,
113        producer_state: StreamAcceptedState,
114        consumer_state: StreamAcceptedState,
115        service: impl Into<String>,
116        capability: impl Into<String>,
117        track: impl Into<String>,
118        producer_kem_key_id: impl Into<String>,
119        consumer_kem_key_id: impl Into<String>,
120        max_blocks_per_epoch: u64,
121    ) -> Result<Self> {
122        let binding = Self {
123            carrier_profile,
124            route_role,
125            producer_endpoint_did: producer_endpoint_did.into(),
126            consumer_endpoint_did: consumer_endpoint_did.into(),
127            producer_state,
128            consumer_state,
129            service: service.into(),
130            capability: capability.into(),
131            track: track.into(),
132            producer_kem_key_id: producer_kem_key_id.into(),
133            consumer_kem_key_id: consumer_kem_key_id.into(),
134            max_blocks_per_epoch,
135            suite: IDENTIFIED_STREAM_SUITE,
136        };
137        binding.validate()?;
138        Ok(binding)
139    }
140
141    fn validate(&self) -> Result<()> {
142        ensure!(
143            self.suite == IDENTIFIED_STREAM_SUITE,
144            "identified stream requires the pinned X25519+ML-KEM-768 suite"
145        );
146        validate_did(&self.producer_endpoint_did, "producer endpoint")?;
147        validate_did(&self.consumer_endpoint_did, "consumer endpoint")?;
148        self.producer_state.validate("producer")?;
149        self.consumer_state.validate("consumer")?;
150        validate_text(&self.service, "service", MAX_TEXT)?;
151        validate_text(&self.capability, "capability", MAX_CAPABILITY)?;
152        validate_text(&self.track, "track", MAX_TEXT)?;
153        validate_text(&self.producer_kem_key_id, "producer KEM key id", MAX_TEXT)?;
154        validate_text(&self.consumer_kem_key_id, "consumer KEM key id", MAX_TEXT)?;
155        ensure!(
156            self.producer_state.identity_did == self.producer_endpoint_did,
157            "producer endpoint DID does not match accepted state"
158        );
159        ensure!(
160            self.consumer_state.identity_did == self.consumer_endpoint_did,
161            "consumer endpoint DID does not match accepted state"
162        );
163        ensure!(
164            self.max_blocks_per_epoch > 0,
165            "max_blocks_per_epoch must be non-zero"
166        );
167        ensure!(
168            self.max_blocks_per_epoch <= (u64::MAX >> 16),
169            "max_blocks_per_epoch exceeds the deterministic nonce counter domain"
170        );
171        Ok(())
172    }
173
174    /// The policy-pinned suite; this is descriptive, not negotiated.
175    pub fn suite(&self) -> SuiteId {
176        self.suite
177    }
178
179    /// Admission-pinned upper bound before an authenticated epoch transition is required.
180    pub fn max_blocks_per_epoch(&self) -> u64 {
181        self.max_blocks_per_epoch
182    }
183
184    /// Canonical length-framed session transcript.
185    pub fn canonical_bytes(&self) -> Vec<u8> {
186        let mut out = Vec::with_capacity(512);
187        out.extend_from_slice(&IDENTIFIED_STREAM_VERSION.to_be_bytes());
188        out.extend_from_slice(&self.suite.as_u16().to_be_bytes());
189        out.push(self.carrier_profile as u8);
190        out.push(self.route_role as u8);
191        put_text(&mut out, &self.producer_endpoint_did);
192        put_text(&mut out, &self.consumer_endpoint_did);
193        put_state(&mut out, &self.producer_state);
194        put_state(&mut out, &self.consumer_state);
195        put_text(&mut out, &self.service);
196        put_text(&mut out, &self.capability);
197        put_text(&mut out, &self.track);
198        put_text(&mut out, &self.producer_kem_key_id);
199        put_text(&mut out, &self.consumer_kem_key_id);
200        out.extend_from_slice(&self.max_blocks_per_epoch.to_be_bytes());
201        out
202    }
203
204    pub fn binding_hash(&self) -> [u8; 32] {
205        derive_key(BINDING_HASH_DOMAIN, &self.canonical_bytes())
206    }
207}
208
209/// Generic authority seam shared by identified and future anonymous releases.
210///
211/// This module provides no anonymous-capability implementation and derives no
212/// assurance from this enum.  #1060-#1062 must supply a reviewed concrete type
213/// and gate before `AnonymousCapability` can authorize production key release.
214#[derive(Clone, Debug, PartialEq, Eq)]
215pub enum StreamKeyReleasePrincipal<I, A> {
216    Identified(I),
217    AnonymousCapability(A),
218}
219
220/// Authorization/key-release policy seam.  Crypto code consumes an authorized
221/// binding; network implementations must call a gate at the #726 release PEP.
222pub trait StreamKeyReleaseGate<P> {
223    type Grant;
224    fn authorize_release(
225        &self,
226        principal: &P,
227        binding: &IdentifiedStreamBinding,
228    ) -> Result<Self::Grant>;
229}
230
231/// Directional keys for one track epoch.
232#[derive(Clone)]
233pub struct StreamEpochKeys {
234    pub epoch: u64,
235    pub direction: StreamDirection,
236    pub mac_key: Zeroizing<[u8; 32]>,
237    pub enc_key: Zeroizing<[u8; 32]>,
238    pub control_mac_key: Zeroizing<[u8; 32]>,
239    rekey_auth_key: Zeroizing<[u8; 32]>,
240    nonce_domain: [u8; 4],
241    epoch_namespace: [u8; 32],
242}
243
244impl StreamEpochKeys {
245    /// Deterministic AES-GCM nonce: a transcript-derived 32-bit domain followed
246    /// by the authenticated per-epoch sequence number.  The key and prefix both
247    /// differ across direction/track/epoch.
248    pub fn nonce(&self, sequence_number: u64) -> [u8; 12] {
249        let sequence = sequence_number.to_be_bytes();
250        std::array::from_fn(|index| {
251            if index < self.nonce_domain.len() {
252                self.nonce_domain[index]
253            } else {
254                sequence[index - self.nonce_domain.len()]
255            }
256        })
257    }
258
259    pub fn epoch_namespace(&self) -> &[u8; 32] {
260        &self.epoch_namespace
261    }
262}
263
264/// Both direction domains for one committed epoch.
265#[derive(Clone)]
266pub struct StreamEpochKeySet {
267    pub epoch: u64,
268    pub producer_to_consumer: StreamEpochKeys,
269    pub consumer_to_producer: StreamEpochKeys,
270}
271
272impl StreamEpochKeySet {
273    pub fn for_direction(&self, direction: StreamDirection) -> &StreamEpochKeys {
274        match direction {
275            StreamDirection::ProducerToConsumer => &self.producer_to_consumer,
276            StreamDirection::ConsumerToProducer => &self.consumer_to_producer,
277        }
278    }
279}
280
281/// Authenticated epoch transition.  It contains no traffic key.
282#[derive(Clone, Debug, PartialEq, Eq)]
283pub struct StreamEpochCommit {
284    pub binding_hash: [u8; 32],
285    pub previous_epoch: u64,
286    pub epoch: u64,
287    pub producer_namespace: [u8; 32],
288    pub consumer_namespace: [u8; 32],
289    pub auth_tag: [u8; 32],
290}
291
292impl StreamEpochCommit {
293    fn authenticated_bytes(&self) -> Vec<u8> {
294        let mut out = Vec::with_capacity(112);
295        out.extend_from_slice(&self.binding_hash);
296        out.extend_from_slice(&self.previous_epoch.to_be_bytes());
297        out.extend_from_slice(&self.epoch.to_be_bytes());
298        out.extend_from_slice(&self.producer_namespace);
299        out.extend_from_slice(&self.consumer_namespace);
300        out
301    }
302
303    /// Fixed, versioned control plaintext sealed inside an ordinary opaque
304    /// stream Object. Authentication is still provided by `auth_tag`, the
305    /// current-epoch AEAD, and the chained Object MAC.
306    pub fn encode_control_object(&self) -> Vec<u8> {
307        let mut out = Vec::with_capacity(CONTROL_OBJECT_LEN);
308        out.extend_from_slice(CONTROL_OBJECT_MAGIC);
309        out.extend_from_slice(&IDENTIFIED_STREAM_VERSION.to_be_bytes());
310        out.extend_from_slice(&self.binding_hash);
311        out.extend_from_slice(&self.previous_epoch.to_be_bytes());
312        out.extend_from_slice(&self.epoch.to_be_bytes());
313        out.extend_from_slice(&self.producer_namespace);
314        out.extend_from_slice(&self.consumer_namespace);
315        out.extend_from_slice(&self.auth_tag);
316        out
317    }
318
319    /// Decode the control plaintext after current-epoch AEAD verification.
320    pub fn decode_control_object(bytes: &[u8]) -> Result<Self> {
321        ensure!(
322            bytes.len() == CONTROL_OBJECT_LEN,
323            "stream epoch control has invalid length {}",
324            bytes.len()
325        );
326        ensure!(
327            &bytes[..8] == CONTROL_OBJECT_MAGIC,
328            "stream epoch control magic mismatch"
329        );
330        ensure!(
331            u16::from_be_bytes(bytes[8..10].try_into()?) == IDENTIFIED_STREAM_VERSION,
332            "stream epoch control version mismatch"
333        );
334        Ok(Self {
335            binding_hash: bytes[10..42].try_into()?,
336            previous_epoch: u64::from_be_bytes(bytes[42..50].try_into()?),
337            epoch: u64::from_be_bytes(bytes[50..58].try_into()?),
338            producer_namespace: bytes[58..90].try_into()?,
339            consumer_namespace: bytes[90..122].try_into()?,
340            auth_tag: bytes[122..154].try_into()?,
341        })
342    }
343}
344
345/// Stateful, one-way, explicit stream epoch ratchet.
346///
347/// `prepare_next` is non-mutating.  `commit_prepared`/`accept_commit` make the
348/// transition atomic: an invalid or interrupted pending update leaves the prior
349/// committed epoch live and exposes no pending traffic keys.
350#[derive(Clone)]
351pub struct StreamEpochRatchet {
352    binding: IdentifiedStreamBinding,
353    binding_hash: [u8; 32],
354    route_topic: String,
355    control_topic: String,
356    epoch: u64,
357    secret: Zeroizing<[u8; 32]>,
358}
359
360impl StreamEpochRatchet {
361    pub(crate) fn from_hybrid_secret(
362        hybrid_secret: &[u8; 32],
363        binding: IdentifiedStreamBinding,
364    ) -> Result<Self> {
365        binding.validate()?;
366        let binding_bytes = binding.canonical_bytes();
367        let mut root_input = Zeroizing::new(Vec::with_capacity(32 + binding_bytes.len()));
368        root_input.extend_from_slice(hybrid_secret);
369        root_input.extend_from_slice(&binding_bytes);
370        let secret = Zeroizing::new(derive_key(SESSION_ROOT_DOMAIN, &root_input));
371        let binding_hash = binding.binding_hash();
372        let route_topic = hex::encode(derive_label(ROUTE_TOPIC_DOMAIN, &secret, &binding_hash));
373        let control_topic = hex::encode(derive_label(CONTROL_TOPIC_DOMAIN, &secret, &binding_hash));
374        Ok(Self {
375            binding,
376            binding_hash,
377            route_topic,
378            control_topic,
379            epoch: 0,
380            secret,
381        })
382    }
383
384    pub fn binding(&self) -> &IdentifiedStreamBinding {
385        &self.binding
386    }
387
388    pub fn epoch(&self) -> u64 {
389        self.epoch
390    }
391
392    pub fn route_topic(&self) -> &str {
393        &self.route_topic
394    }
395
396    pub fn control_topic(&self) -> &str {
397        &self.control_topic
398    }
399
400    pub fn current_keys(&self) -> StreamEpochKeySet {
401        derive_epoch_key_set(&self.secret, &self.binding, self.epoch)
402    }
403
404    pub fn prepare_next(&self) -> Result<StreamEpochCommit> {
405        let next_epoch = self
406            .epoch
407            .checked_add(1)
408            .ok_or_else(|| anyhow::anyhow!("stream epoch exhausted"))?;
409        let next_secret = next_epoch_secret(&self.secret, &self.binding_hash, next_epoch);
410        let next_keys = derive_epoch_key_set(&next_secret, &self.binding, next_epoch);
411        let mut commit = StreamEpochCommit {
412            binding_hash: self.binding_hash,
413            previous_epoch: self.epoch,
414            epoch: next_epoch,
415            producer_namespace: *next_keys.producer_to_consumer.epoch_namespace(),
416            consumer_namespace: *next_keys.consumer_to_producer.epoch_namespace(),
417            auth_tag: [0u8; 32],
418        };
419        let current = self.current_keys();
420        commit.auth_tag = keyed_mac(
421            &current.producer_to_consumer.rekey_auth_key,
422            &commit.authenticated_bytes(),
423        );
424        Ok(commit)
425    }
426
427    pub fn commit_prepared(&mut self, commit: &StreamEpochCommit) -> Result<StreamEpochKeySet> {
428        self.accept_commit(commit)
429    }
430
431    pub fn accept_commit(&mut self, commit: &StreamEpochCommit) -> Result<StreamEpochKeySet> {
432        ensure!(
433            commit.binding_hash == self.binding_hash,
434            "stream rekey binding mismatch"
435        );
436        ensure!(
437            commit.previous_epoch == self.epoch,
438            "stream rekey is stale, replayed, or skips the committed epoch"
439        );
440        ensure!(
441            commit.epoch
442                == self
443                    .epoch
444                    .checked_add(1)
445                    .ok_or_else(|| anyhow::anyhow!("stream epoch exhausted"))?,
446            "stream rekey target is not the next epoch"
447        );
448        let current = self.current_keys();
449        let expected = keyed_mac(
450            &current.producer_to_consumer.rekey_auth_key,
451            &commit.authenticated_bytes(),
452        );
453        ensure!(
454            bool::from(expected.ct_eq(&commit.auth_tag)),
455            "stream rekey authentication failed"
456        );
457        let next_secret = next_epoch_secret(&self.secret, &self.binding_hash, commit.epoch);
458        let next_keys = derive_epoch_key_set(&next_secret, &self.binding, commit.epoch);
459        ensure!(
460            commit.producer_namespace == *next_keys.producer_to_consumer.epoch_namespace()
461                && commit.consumer_namespace == *next_keys.consumer_to_producer.epoch_namespace(),
462            "stream rekey namespace commitment mismatch"
463        );
464
465        // Atomic commit: all validation above is non-mutating.
466        self.secret = next_secret;
467        self.epoch = commit.epoch;
468        Ok(next_keys)
469    }
470}
471
472fn derive_epoch_key_set(
473    epoch_secret: &[u8; 32],
474    binding: &IdentifiedStreamBinding,
475    epoch: u64,
476) -> StreamEpochKeySet {
477    StreamEpochKeySet {
478        epoch,
479        producer_to_consumer: derive_direction_keys(
480            epoch_secret,
481            binding,
482            epoch,
483            StreamDirection::ProducerToConsumer,
484        ),
485        consumer_to_producer: derive_direction_keys(
486            epoch_secret,
487            binding,
488            epoch,
489            StreamDirection::ConsumerToProducer,
490        ),
491    }
492}
493
494fn derive_direction_keys(
495    epoch_secret: &[u8; 32],
496    binding: &IdentifiedStreamBinding,
497    epoch: u64,
498    direction: StreamDirection,
499) -> StreamEpochKeys {
500    let mut transcript = binding.canonical_bytes();
501    transcript.push(direction as u8);
502    transcript.extend_from_slice(&epoch.to_be_bytes());
503    let derive = |domain: &'static str| {
504        let mut input = Zeroizing::new(Vec::with_capacity(32 + transcript.len()));
505        input.extend_from_slice(epoch_secret);
506        input.extend_from_slice(&transcript);
507        derive_key(domain, &input)
508    };
509    let nonce = derive(NONCE_DOMAIN);
510    let mut nonce_domain = [0u8; 4];
511    nonce_domain.copy_from_slice(&nonce[..4]);
512    StreamEpochKeys {
513        epoch,
514        direction,
515        mac_key: Zeroizing::new(derive(DATA_MAC_DOMAIN)),
516        enc_key: Zeroizing::new(derive(DATA_AEAD_DOMAIN)),
517        control_mac_key: Zeroizing::new(derive(CONTROL_MAC_DOMAIN)),
518        rekey_auth_key: Zeroizing::new(derive(REKEY_AUTH_DOMAIN)),
519        nonce_domain,
520        epoch_namespace: derive(EPOCH_NAMESPACE_DOMAIN),
521    }
522}
523
524fn next_epoch_secret(
525    current: &[u8; 32],
526    binding_hash: &[u8; 32],
527    epoch: u64,
528) -> Zeroizing<[u8; 32]> {
529    let mut input = Zeroizing::new([0u8; 72]);
530    input[..32].copy_from_slice(current);
531    input[32..64].copy_from_slice(binding_hash);
532    input[64..].copy_from_slice(&epoch.to_be_bytes());
533    Zeroizing::new(derive_key(EPOCH_SECRET_DOMAIN, &*input))
534}
535
536fn derive_label(domain: &'static str, secret: &[u8; 32], binding_hash: &[u8; 32]) -> [u8; 32] {
537    let mut input = Zeroizing::new([0u8; 64]);
538    input[..32].copy_from_slice(secret);
539    input[32..].copy_from_slice(binding_hash);
540    derive_key(domain, &*input)
541}
542
543fn validate_did(value: &str, label: &str) -> Result<()> {
544    validate_text(value, label, MAX_TEXT)?;
545    ensure!(value.starts_with("did:"), "{label} is not a DID");
546    Ok(())
547}
548
549fn validate_text(value: &str, label: &str, limit: usize) -> Result<()> {
550    ensure!(!value.is_empty(), "{label} is empty");
551    ensure!(value.len() <= limit, "{label} exceeds {limit} bytes");
552    ensure!(!value.bytes().any(|byte| byte == 0), "{label} contains NUL");
553    Ok(())
554}
555
556fn put_text(out: &mut Vec<u8>, value: &str) {
557    // Bindings are validated and frozen at construction, so this conversion is
558    // infallible in practice. Encoding u64 avoids a panic path in the canonicalizer.
559    let len = u64::try_from(value.len()).unwrap_or(u64::MAX);
560    out.extend_from_slice(&len.to_be_bytes());
561    out.extend_from_slice(value.as_bytes());
562}
563
564fn put_state(out: &mut Vec<u8>, state: &StreamAcceptedState) {
565    put_text(out, &state.identity_did);
566    out.extend_from_slice(&state.digest);
567    out.extend_from_slice(&state.epoch.to_be_bytes());
568}
569
570#[cfg(test)]
571#[allow(clippy::unwrap_used)]
572mod tests {
573    use super::*;
574
575    fn binding(profile: StreamCarrierProfile) -> IdentifiedStreamBinding {
576        IdentifiedStreamBinding::new(
577            profile,
578            StreamRouteRole::Relay,
579            "did:at9p:producer",
580            "did:at9p:consumer",
581            StreamAcceptedState {
582                identity_did: "did:at9p:producer".into(),
583                digest: [0x11; 64],
584                epoch: 7,
585            },
586            StreamAcceptedState {
587                identity_did: "did:at9p:consumer".into(),
588                digest: [0x22; 64],
589                epoch: 9,
590            },
591            "inference.generate",
592            "infer:model:qwen",
593            "local/streams/tokens",
594            "did:at9p:producer#mesh-kem",
595            "urn:hyprstream:ephemeral-kem:123",
596            1024,
597        )
598        .unwrap()
599    }
600
601    fn ratchet(profile: StreamCarrierProfile) -> StreamEpochRatchet {
602        StreamEpochRatchet::from_hybrid_secret(&[0x44; 32], binding(profile)).unwrap()
603    }
604
605    #[test]
606    fn transcript_mutations_separate_every_security_axis() {
607        let base = binding(StreamCarrierProfile::StandardPublicRelay);
608        let base_hash = base.binding_hash();
609        let mut mutations = Vec::new();
610        let mut v = base.clone();
611        v.carrier_profile = StreamCarrierProfile::OwnedHybridTransport;
612        mutations.push(v);
613        let mut v = base.clone();
614        v.route_role = StreamRouteRole::Direct;
615        mutations.push(v);
616        let mut v = base.clone();
617        v.producer_endpoint_did.push_str(":other");
618        v.producer_state.identity_did = v.producer_endpoint_did.clone();
619        mutations.push(v);
620        let mut v = base.clone();
621        v.consumer_endpoint_did.push_str(":other");
622        v.consumer_state.identity_did = v.consumer_endpoint_did.clone();
623        mutations.push(v);
624        let mut v = base.clone();
625        v.producer_state.digest[0] ^= 1;
626        mutations.push(v);
627        let mut v = base.clone();
628        v.consumer_state.epoch += 1;
629        mutations.push(v);
630        let mut v = base.clone();
631        v.capability.push_str(":other");
632        mutations.push(v);
633        let mut v = base.clone();
634        v.service.push_str(":other");
635        mutations.push(v);
636        let mut v = base.clone();
637        v.track.push_str("-other");
638        mutations.push(v);
639        let mut v = base.clone();
640        v.producer_kem_key_id.push_str("-other");
641        mutations.push(v);
642        let mut v = base.clone();
643        v.consumer_kem_key_id.push_str("-other");
644        mutations.push(v);
645        let mut v = base.clone();
646        v.max_blocks_per_epoch += 1;
647        mutations.push(v);
648        for mutation in mutations {
649            assert_ne!(mutation.binding_hash(), base_hash);
650        }
651    }
652
653    #[test]
654    fn direction_track_epoch_keys_and_nonces_are_disjoint() {
655        let r = ratchet(StreamCarrierProfile::StandardPublicRelay);
656        let k0 = r.current_keys();
657        assert_ne!(
658            *k0.producer_to_consumer.enc_key,
659            *k0.consumer_to_producer.enc_key
660        );
661        assert_ne!(
662            k0.producer_to_consumer.nonce(4),
663            k0.consumer_to_producer.nonce(4)
664        );
665        assert_ne!(
666            k0.producer_to_consumer.nonce(4),
667            k0.producer_to_consumer.nonce(5)
668        );
669
670        let mut other_track = binding(StreamCarrierProfile::StandardPublicRelay);
671        other_track.track.push_str("-other");
672        let other = StreamEpochRatchet::from_hybrid_secret(&[0x44; 32], other_track).unwrap();
673        assert_ne!(
674            *k0.producer_to_consumer.enc_key,
675            *other.current_keys().producer_to_consumer.enc_key
676        );
677    }
678
679    #[test]
680    fn authenticated_rekey_is_atomic_replay_safe_and_one_way() {
681        let mut sender = ratchet(StreamCarrierProfile::StandardPublicRelay);
682        let mut receiver = sender.clone();
683        let old = sender.current_keys();
684        let commit = sender.prepare_next().unwrap();
685
686        let mut tampered = commit.clone();
687        tampered.producer_namespace[0] ^= 1;
688        assert!(receiver.accept_commit(&tampered).is_err());
689        assert_eq!(
690            receiver.epoch(),
691            0,
692            "invalid pending update mutated committed state"
693        );
694
695        let sender_next = sender.commit_prepared(&commit).unwrap();
696        let receiver_next = receiver.accept_commit(&commit).unwrap();
697        assert_eq!(sender_next.epoch, 1);
698        assert_eq!(
699            *sender_next.producer_to_consumer.enc_key,
700            *receiver_next.producer_to_consumer.enc_key
701        );
702        assert_ne!(
703            *old.producer_to_consumer.enc_key,
704            *sender_next.producer_to_consumer.enc_key
705        );
706        assert!(
707            receiver.accept_commit(&commit).is_err(),
708            "replayed commit accepted"
709        );
710    }
711
712    #[test]
713    fn profile_substitution_breaks_key_agreement() {
714        let owned = ratchet(StreamCarrierProfile::OwnedHybridTransport);
715        let relay = ratchet(StreamCarrierProfile::StandardPublicRelay);
716        assert_ne!(owned.binding_hash, relay.binding_hash);
717        assert_ne!(
718            *owned.current_keys().producer_to_consumer.enc_key,
719            *relay.current_keys().producer_to_consumer.enc_key
720        );
721    }
722
723    #[test]
724    fn identified_binding_rejects_anonymous_or_stale_shape() {
725        let mut b = binding(StreamCarrierProfile::StandardPublicRelay);
726        b.consumer_endpoint_did = "anonymous".into();
727        assert!(b.validate().is_err());
728        b.consumer_endpoint_did = b.consumer_state.identity_did.clone();
729        b.consumer_state.digest = [0; 64];
730        assert!(b.validate().is_err());
731    }
732
733    #[test]
734    fn pinned_hykem_handshake_requires_both_components_and_binds_context() {
735        use crate::crypto::hybrid_kem::{generate_recipient, HybridKemMaterial};
736        use crate::crypto::key_exchange::{
737            client_identified_stream_epoch, server_identified_stream_epoch,
738        };
739
740        let keypair = generate_recipient(IDENTIFIED_STREAM_SUITE).unwrap();
741        let binding = binding(StreamCarrierProfile::StandardPublicRelay);
742        let (material, server) =
743            server_identified_stream_epoch(&keypair.public().encode(), binding.clone()).unwrap();
744        let client =
745            client_identified_stream_epoch(&keypair, &material.encode(), binding.clone()).unwrap();
746        assert_eq!(
747            *server.current_keys().producer_to_consumer.enc_key,
748            *client.current_keys().producer_to_consumer.enc_key
749        );
750
751        // A classical-only material list is structurally rejected before key use.
752        let mut classical_only = material.clone();
753        classical_only.shares.truncate(1);
754        assert!(client_identified_stream_epoch(
755            &keypair,
756            &classical_only.encode(),
757            binding.clone()
758        )
759        .is_err());
760
761        // Mutating either component changes or invalidates the agreed key.  ML-KEM
762        // uses implicit rejection, so key mismatch is the expected failure signal.
763        for index in 0..material.shares.len() {
764            let mut crossed: HybridKemMaterial = material.clone();
765            crossed.shares[index].bytes[0] ^= 1;
766            if let Ok(crossed_client) =
767                client_identified_stream_epoch(&keypair, &crossed.encode(), binding.clone())
768            {
769                assert_ne!(
770                    *server.current_keys().producer_to_consumer.enc_key,
771                    *crossed_client.current_keys().producer_to_consumer.enc_key
772                );
773            }
774        }
775
776        let mut substituted = binding;
777        substituted.track.push_str("-substituted");
778        let wrong_context =
779            client_identified_stream_epoch(&keypair, &material.encode(), substituted).unwrap();
780        assert_ne!(
781            *server.current_keys().producer_to_consumer.enc_key,
782            *wrong_context.current_keys().producer_to_consumer.enc_key
783        );
784    }
785
786    #[test]
787    fn client_kem_public_survives_authenticated_envelope_codec() {
788        use crate::crypto::hybrid_kem::generate_recipient;
789        use crate::envelope::RequestEnvelope;
790        use crate::{FromCapnp, ToCapnp};
791
792        let recipient = generate_recipient(IDENTIFIED_STREAM_SUITE)
793            .unwrap()
794            .public();
795        let envelope = RequestEnvelope::new(b"start identified stream".to_vec())
796            .with_client_kem_public(recipient.clone())
797            .unwrap();
798        let mut message = capnp::message::Builder::new_default();
799        envelope
800            .write_to(&mut message.init_root::<crate::common_capnp::request_envelope::Builder>());
801        let decoded = RequestEnvelope::read_from(
802            message
803                .into_reader()
804                .get_root::<crate::common_capnp::request_envelope::Reader>()
805                .unwrap(),
806        )
807        .unwrap();
808        assert_eq!(decoded.client_kem_public, Some(recipient));
809    }
810
811    #[test]
812    fn stock_relay_payload_is_opaque_and_forwarded_byte_identically() {
813        use crate::crypto::event_crypto::{decrypt_event_full, encrypt_event_with_nonce};
814        use crate::stream_consumer::stream_aead_aad;
815
816        let ratchet = ratchet(StreamCarrierProfile::StandardPublicRelay);
817        let keys = ratchet.current_keys();
818        let traffic = &keys.producer_to_consumer;
819        let plaintext = b"private inference token";
820        let nonce = traffic.nonce(0);
821        let aad = stream_aead_aad(ratchet.route_topic(), 0, 0, 0);
822        let (tag, ciphertext, sent_nonce, commitment) =
823            encrypt_event_with_nonce(&traffic.enc_key, nonce, &aad, plaintext).unwrap();
824
825        // These are ordinary opaque Object payload bytes.  A stock relay copies
826        // them without a HyKEM/epoch parser or any traffic key.
827        let mut object = Vec::new();
828        object.extend_from_slice(&sent_nonce);
829        object.extend_from_slice(&commitment);
830        object.extend_from_slice(&tag);
831        object.extend_from_slice(&ciphertext);
832        assert!(!object
833            .windows(plaintext.len())
834            .any(|window| window == plaintext));
835        let relayed = object.clone();
836        assert_eq!(relayed, object);
837
838        let opened =
839            decrypt_event_full(&traffic.enc_key, &sent_nonce, &tag, &ciphertext, &aad).unwrap();
840        assert_eq!(opened, plaintext);
841    }
842}