Skip to main content

hyprstream_rpc/
stream_consumer.rs

1//! Cross-target streaming consumer types.
2//!
3//! Extracted from `streaming.rs` (native-only) so that `StreamHandleImpl<T>`
4//! can compile on both native and wasm32. All types here are pure logic —
5//! no ZMQ, no Tokio, no platform-specific deps.
6//!
7//! - `StreamPayload` — parsed output from verified stream blocks
8//! - `StreamVerifier` — HMAC chain verifier (pure crypto)
9//! - `StreamHandleImpl<T>` — unified stream consumer over any `Transport`
10
11use std::collections::VecDeque;
12use std::sync::atomic::{AtomicBool, Ordering};
13use std::sync::Arc;
14
15use anyhow::{ensure, Result};
16use futures::StreamExt;
17
18use crate::crypto::{derive_stream_keys, keyed_mac_truncated, keyed_mac_truncated_parts};
19use crate::stream_info::StreamInfo;
20use crate::streaming_capnp;
21use crate::transport_traits::{PublishSink, Transport};
22
23#[cfg(not(feature = "fips"))]
24use crate::crypto::ristretto_dh_raw as dh_compute_raw;
25
26// TODO: Add FIPS p256_dh_raw equivalent when needed
27// #[cfg(feature = "fips")]
28// use crate::crypto::p256_dh_raw as dh_compute_raw;
29
30// ============================================================================
31// StreamPayload — parsed output from verified stream blocks
32// ============================================================================
33
34/// Output payload from StreamVerifier.
35#[derive(Clone, Debug)]
36pub enum StreamPayload {
37    /// Generic binary data (tokens, I/O, etc.)
38    Data(Vec<u8>),
39    /// Error during streaming
40    Error(String),
41    /// Completion with app-specific metadata
42    Complete(Vec<u8>),
43    /// Encrypted tagged payload with key commitment
44    Tagged {
45        tag: Vec<u8>,
46        payload: Vec<u8>,
47        nonce: Vec<u8>,
48        key_commitment: Vec<u8>,
49    },
50}
51
52// ============================================================================
53// StreamVerifier — HMAC chain verifier (pure crypto)
54// ============================================================================
55
56/// Consumer-side ordering contract (#163/#213). The full `StreamOpt` (schema) carries
57/// producer-side QoS too (delivery/retention/overflow); the consumer only needs ordering
58/// + completion to *verify*. Cross-target so native and the wasm/browser consumer share it.
59#[derive(Debug, Clone, Copy, PartialEq, Eq)]
60pub enum StreamOrdering {
61    /// In-order, gap-fatal: each block's `sequenceNumber` must equal the previous + 1.
62    Ordered,
63    /// Out-of-order media: gaps tolerated (skip-to-live); a block whose `sequenceNumber` is
64    /// at/under `last_seen - anti_replay_window` is rejected as a replay.
65    Unordered { anti_replay_window: u32 },
66}
67
68/// Consumer-side truncation contract (#163/#213). Maps to the schema `Completion` axis
69/// (schema `none` → `Open`).
70#[derive(Debug, Clone, Copy, PartialEq, Eq)]
71pub enum Completion {
72    /// A `Complete`/`Error` payload must be observed before EOF; EOF-without-terminal is a
73    /// truncation and must be rejected by the consumer (see [`StreamVerifier::requires_terminal`]).
74    /// Matches schema `endOfStream` (gRPC END_STREAM / HTTP/2 DATA+END_STREAM).
75    EndOfStream,
76    /// EOF is accepted; truncation is not detectable (the explicit choice for inference/live).
77    Open,
78}
79
80/// The consumer's slice of the stream's API contract (#213), set from the service's
81/// `$streamQos` via codegen (#217) — NOT from the wire, so it can't be downgraded.
82#[derive(Debug, Clone, Copy, PartialEq, Eq)]
83pub struct VerifierContract {
84    pub ordering: StreamOrdering,
85    pub completion: Completion,
86}
87
88/// HMAC chain verifier for StreamBlock.
89pub struct StreamVerifier {
90    key: [u8; 32],
91    /// Transport-level AEAD key (#321). `Some` ⇒ a `Tagged` payload is opened
92    /// (AES-256-GCM, AAD bound to topic+epoch) back into Data/Complete/Error; `None` ⇒
93    /// `Tagged` payloads pass through unchanged (the E2E notification path, which
94    /// the app layer decrypts itself).
95    enc_key: Option<[u8; 32]>,
96    prev_mac: Option<[u8; 16]>,
97    topic: String,
98    /// Verifier contract enforcement (#163). `None` ⇒ legacy behaviour (MAC chain only, no
99    /// `seq`/completion checks). Set via [`StreamVerifier::with_policy`] by codegen-generated
100    /// consumers; default `new()` keeps `None` so existing call sites are unchanged.
101    policy: Option<VerifierContract>,
102    /// Next expected `seq` (ordered) / highest `seq` seen (media). `None` until the first
103    /// block, so a late-join starting at an arbitrary offset is accepted, then enforced.
104    seq_cursor: Option<u64>,
105    /// Whether a terminal (`Complete`/`Error`) payload has been observed (for `completion`).
106    terminal_seen: bool,
107    /// Explicit identified epoch state.  Epoch commits are accepted separately
108    /// and reset the chain atomically before any next-epoch Object is processed.
109    epoch_ratchet: Option<crate::stream_epoch::StreamEpochRatchet>,
110}
111
112impl StreamVerifier {
113    /// Create a new verifier with **no** policy enforcement (MAC chain only) — legacy behaviour.
114    ///
115    /// AEAD opening is OFF (`enc_key = None`); use [`StreamVerifier::with_enc_key`] to
116    /// open transport-sealed `Tagged` payloads (#321).
117    pub fn new(key: [u8; 32], topic: String) -> Self {
118        Self {
119            key,
120            enc_key: None,
121            prev_mac: None,
122            topic,
123            policy: None,
124            seq_cursor: None,
125            terminal_seen: false,
126            epoch_ratchet: None,
127        }
128    }
129
130    /// Set the transport AEAD key so sealed `Tagged` payloads are opened (#321).
131    ///
132    /// Builder-style; pass the `enc_key` from `derive_client_stream_keys`. With it
133    /// set, the verifier decrypts each `Tagged` block back into Data/Complete/Error and
134    /// fails closed on tamper / wrong key.
135    pub fn with_enc_key(mut self, enc_key: [u8; 32]) -> Self {
136        self.enc_key = Some(enc_key);
137        self
138    }
139
140    /// Install the identified epoch profile at its current committed epoch.
141    pub fn with_epoch_ratchet(mut self, ratchet: crate::stream_epoch::StreamEpochRatchet) -> Self {
142        let keys = ratchet.current_keys();
143        self.key = *keys.producer_to_consumer.mac_key;
144        self.enc_key = Some(*keys.producer_to_consumer.enc_key);
145        self.topic = ratchet.route_topic().to_owned();
146        self.prev_mac = None;
147        self.seq_cursor = None;
148        self.epoch_ratchet = Some(ratchet);
149        self
150    }
151
152    /// Authenticate and atomically install the next epoch.  Failed, replayed,
153    /// skipped, or cross-stream commits leave the current verifier state intact.
154    pub fn accept_epoch_commit(
155        &mut self,
156        commit: &crate::stream_epoch::StreamEpochCommit,
157    ) -> Result<()> {
158        let ratchet = self
159            .epoch_ratchet
160            .as_ref()
161            .ok_or_else(|| anyhow::anyhow!("stream is not using the identified epoch profile"))?;
162        let mut pending = ratchet.clone();
163        let keys = pending.accept_commit(commit)?;
164        self.key = *keys.producer_to_consumer.mac_key;
165        self.enc_key = Some(*keys.producer_to_consumer.enc_key);
166        self.prev_mac = None;
167        self.seq_cursor = None;
168        self.epoch_ratchet = Some(pending);
169        Ok(())
170    }
171
172    /// Create a verifier that enforces `policy` (#163) — used by codegen-generated consumers,
173    /// where the contract is a compile-time constant from the service's API contract.
174    pub fn with_policy(key: [u8; 32], topic: String, policy: VerifierContract) -> Self {
175        let mut v = Self::new(key, topic);
176        v.policy = Some(policy);
177        v
178    }
179
180    /// True if this stream's policy requires a terminal payload before EOF; the consumer must
181    /// reject an EOF when this is true and [`StreamVerifier::terminal_seen`] is false.
182    pub fn requires_terminal(&self) -> bool {
183        matches!(
184            self.policy.map(|p| p.completion),
185            Some(Completion::EndOfStream)
186        )
187    }
188
189    /// True once a terminal (`Complete`/`Error`) payload has been observed.
190    pub fn terminal_seen(&self) -> bool {
191        self.terminal_seen
192    }
193
194    /// Verify frames and return parsed payloads.
195    ///
196    /// Expected frames: [topic, capnp StreamBlock, 16-byte MAC]
197    pub fn verify(&mut self, frames: &[Vec<u8>]) -> Result<Vec<StreamPayload>> {
198        if frames.len() != 3 {
199            anyhow::bail!("Expected 3 frames, got {}", frames.len());
200        }
201        self.verify_parts(&frames[0], &frames[1], &frames[2])
202    }
203
204    /// Zero-copy variant of [`verify`](Self::verify) over borrowed slices.
205    ///
206    /// `verify` is a thin wrapper over this. The moq path calls it directly with
207    /// slices into the received `Bytes` frame (`verify_moq_frame`), so a large
208    /// payload (e.g. a pipeline activation tensor) is never copied into owned
209    /// per-frame `Vec`s — combined with the multi-part MAC and
210    /// `read_message_from_flat_slice` below, the block stays a view into the
211    /// receive buffer end-to-end.
212    pub fn verify_parts(
213        &mut self,
214        received_topic: &[u8],
215        capnp_data: &[u8],
216        received_mac: &[u8],
217    ) -> Result<Vec<StreamPayload>> {
218        if received_mac.len() != 16 {
219            anyhow::bail!("Expected 16-byte MAC, got {}", received_mac.len());
220        }
221
222        if received_topic != self.topic.as_bytes() {
223            anyhow::bail!("Topic mismatch");
224        }
225
226        // Compute the expected MAC over `prev_mac ‖ capnp_data` (or `topic ‖ capnp_data`
227        // for the first block) WITHOUT allocating a joined buffer. The multi-part MAC is
228        // byte-identical to MAC-of-concatenation, so the payload is never copied into a
229        // scratch `Vec` — this matters for large frames (e.g. pipeline activation tensors).
230        let prefix: &[u8] = match &self.prev_mac {
231            None => self.topic.as_bytes(),
232            Some(prev) => &prev[..],
233        };
234        let expected_mac = keyed_mac_truncated_parts(&self.key, &[prefix, capnp_data]);
235
236        if !constant_time_eq(received_mac, &expected_mac) {
237            anyhow::bail!("MAC verification failed");
238        }
239
240        // Prepare the chain update, but do not mutate verifier state until the
241        // complete authenticated block (including AEAD payloads) is accepted.
242        let mut new_prev = [0u8; 16];
243        new_prev.copy_from_slice(received_mac);
244
245        // Parse StreamBlock with a borrowing (zero-copy) reader: the capnp `Reader`
246        // references `capnp_data` directly instead of copying the whole block into an
247        // owned message, so a large payload stays a view into the receive buffer.
248        let mut slice: &[u8] = capnp_data;
249        let reader = capnp::serialize::read_message_from_flat_slice(
250            &mut slice,
251            capnp::message::ReaderOptions::default(),
252        )?;
253        let block = reader.get_root::<streaming_capnp::stream_block::Reader>()?;
254        let block_epoch = block.get_epoch();
255        if let Some(ratchet) = &self.epoch_ratchet {
256            ensure!(
257                block_epoch == ratchet.epoch(),
258                "stream block epoch {} is not committed epoch {}",
259                block_epoch,
260                ratchet.epoch()
261            );
262        }
263
264        // Policy-selected ordering/replay enforcement (#163). The MAC already authenticates
265        // `sequenceNumber` (it's inside the block, #219), so a tampered sequenceNumber fails
266        // MAC above; here we enforce *position*. `None` policy ⇒ legacy behaviour (MAC chain
267        // only, no sequenceNumber/completion checks).
268        let mut next_seq_cursor = self.seq_cursor;
269        if let Some(policy) = self.policy {
270            let sequence_number = block.get_sequence_number();
271            match policy.ordering {
272                StreamOrdering::Ordered => {
273                    if let Some(expected) = self.seq_cursor {
274                        if sequence_number != expected {
275                            anyhow::bail!(
276                                "stream ordering violation: expected sequenceNumber {expected}, \
277                                 got {sequence_number} (gap/reorder on an ordered stream)"
278                            );
279                        }
280                    }
281                    // First block (late-join): accept its sequenceNumber, then enforce contiguity.
282                    next_seq_cursor = Some(
283                        sequence_number
284                            .checked_add(1)
285                            .ok_or_else(|| anyhow::anyhow!("stream sequenceNumber exhausted"))?,
286                    );
287                }
288                StreamOrdering::Unordered { .. } => {
289                    // Media (out-of-order) needs a per-Group *self-authenticating* MAC, not the
290                    // chained prev_mac this verifier uses — the chain assumes contiguous
291                    // delivery, which moq's out-of-order/eviction model breaks. Fail closed
292                    // until the per-Group MAC scheme lands (producer + consumer); see #163.
293                    anyhow::bail!(
294                        "unordered/media stream policy not yet supported: needs the per-Group \
295                         self-authenticating MAC (the chained MAC assumes in-order delivery) — #163 follow-on"
296                    );
297                }
298            }
299        }
300
301        // #321: the AEAD AAD binds each sealed payload to (topic, epoch); read the
302        // block epoch so a sealed Tagged payload can only open under its own epoch.
303        let block_sequence = block.get_sequence_number();
304
305        let payloads_reader = block.get_payloads()?;
306        let mut payloads = Vec::with_capacity(payloads_reader.len() as usize);
307        let mut pending_epoch_commit = None;
308
309        let mut terminal_seen = self.terminal_seen;
310        for i in 0..payloads_reader.len() {
311            let p = payloads_reader.get(i);
312
313            use streaming_capnp::stream_payload::Which;
314            let payload = match p.which()? {
315                Which::Data(data_result) => {
316                    ensure!(
317                        self.epoch_ratchet.is_none(),
318                        "identified stream rejected cleartext Data payload"
319                    );
320                    StreamPayload::Data(data_result?.to_vec())
321                }
322                Which::Error(err_result) => {
323                    ensure!(
324                        self.epoch_ratchet.is_none(),
325                        "identified stream rejected cleartext Error payload"
326                    );
327                    let err = err_result?;
328                    StreamPayload::Error(err.get_message()?.to_string()?)
329                }
330                Which::Complete(complete_result) => {
331                    ensure!(
332                        self.epoch_ratchet.is_none(),
333                        "identified stream rejected cleartext Complete payload"
334                    );
335                    StreamPayload::Complete(complete_result?.to_vec())
336                }
337                Which::Heartbeat(()) => {
338                    ensure!(
339                        self.epoch_ratchet.is_none(),
340                        "identified stream rejected cleartext Heartbeat payload"
341                    );
342                    continue;
343                }
344                Which::Tagged(tagged_result) => {
345                    let tagged = tagged_result?;
346                    match self.enc_key {
347                        // #321: transport AEAD ON — open the sealed payload back into
348                        // Data/Complete/Error (fails closed on tamper / wrong key).
349                        Some(ref enc_key) => match open_sealed_payload_inner(
350                            enc_key,
351                            &self.topic,
352                            block_epoch,
353                            block_sequence,
354                            i as usize,
355                            tagged.get_tag()?,
356                            tagged.get_payload()?,
357                            tagged.get_nonce()?,
358                            tagged.get_key_commitment()?,
359                        )? {
360                            OpenedStreamPayload::Application(payload) => payload,
361                            OpenedStreamPayload::EpochCommit(commit) => {
362                                ensure!(
363                                    self.epoch_ratchet.is_some(),
364                                    "stream epoch control on a non-identified stream"
365                                );
366                                ensure!(
367                                    payloads_reader.len() == 1 && i == 0,
368                                    "stream epoch control must be the sole Object payload"
369                                );
370                                pending_epoch_commit = Some(commit);
371                                continue;
372                            }
373                        },
374                        // No transport key (E2E notification path): pass Tagged through.
375                        None => StreamPayload::Tagged {
376                            tag: tagged.get_tag()?.to_vec(),
377                            payload: tagged.get_payload()?.to_vec(),
378                            nonce: tagged.get_nonce()?.to_vec(),
379                            key_commitment: tagged.get_key_commitment()?.to_vec(),
380                        },
381                    }
382                }
383            };
384
385            // Track terminal observation for the `completion` axis (#163).
386            if matches!(
387                payload,
388                StreamPayload::Complete(_) | StreamPayload::Error(_)
389            ) {
390                terminal_seen = true;
391            }
392            payloads.push(payload);
393        }
394
395        if let Some(commit) = pending_epoch_commit {
396            // The control Object was authenticated and opened entirely under
397            // the current epoch. Only now atomically install the next epoch;
398            // failed validation leaves every verifier field unchanged.
399            self.accept_epoch_commit(&commit)?;
400            return Ok(Vec::new());
401        }
402
403        self.prev_mac = Some(new_prev);
404        self.seq_cursor = next_seq_cursor;
405        self.terminal_seen = terminal_seen;
406
407        Ok(payloads)
408    }
409
410    /// Get the topic.
411    pub fn topic(&self) -> &str {
412        &self.topic
413    }
414}
415
416fn constant_time_eq(a: &[u8], b: &[u8]) -> bool {
417    use subtle::ConstantTimeEq;
418    a.ct_eq(b).into()
419}
420
421// ============================================================================
422// #321 — transport-level AEAD framing (cross-target seal/open glue).
423//
424// The seal side lives in `moq_stream` (native publisher); the open side here is
425// cross-target so the wasm/browser consumer opens sealed blocks too. Both sides
426// share this AAD + kind-tag framing.
427// ============================================================================
428
429/// Plaintext kind tag prepended inside the AEAD-sealed bytes so the open path can
430/// restore the original payload variant without a schema change. Authenticated
431/// as part of the AEAD plaintext.
432pub(crate) const SEALED_KIND_DATA: u8 = 0x00;
433pub(crate) const SEALED_KIND_COMPLETE: u8 = 0x01;
434pub(crate) const SEALED_KIND_ERROR: u8 = 0x02;
435pub(crate) const SEALED_KIND_EPOCH_COMMIT: u8 = 0x03;
436
437enum OpenedStreamPayload {
438    Application(StreamPayload),
439    EpochCommit(crate::stream_epoch::StreamEpochCommit),
440}
441
442/// Build the AEAD AAD (also the `encrypt_event` "prefix") binding each sealed
443/// payload to its `topic` and key-`epoch` (#321/#223). Reused verbatim by the
444/// publisher seal path; a block replayed under a different epoch fails AEAD open.
445pub(crate) fn stream_aead_aad(
446    topic: &str,
447    epoch: u64,
448    sequence_number: u64,
449    payload_index: usize,
450) -> String {
451    format!(
452        "{topic}|identified-stream-object-v1|epoch={epoch}|sequence={sequence_number}|payload={payload_index}"
453    )
454}
455
456/// Open an AEAD-sealed `Tagged` payload (#321), restoring the original
457/// Data/Complete/Error variant. Returns `Err` on tamper / wrong key (fail-closed).
458///
459/// `epoch` is the StreamBlock's epoch and MUST match the seal-side AAD.
460#[cfg(test)]
461pub(crate) fn open_sealed_payload(
462    enc_key: &[u8; 32],
463    topic: &str,
464    epoch: u64,
465    sequence_number: u64,
466    payload_index: usize,
467    tag: &[u8],
468    ciphertext: &[u8],
469    nonce: &[u8],
470    key_commitment: &[u8],
471) -> Result<StreamPayload> {
472    match open_sealed_payload_inner(
473        enc_key,
474        topic,
475        epoch,
476        sequence_number,
477        payload_index,
478        tag,
479        ciphertext,
480        nonce,
481        key_commitment,
482    )? {
483        OpenedStreamPayload::Application(payload) => Ok(payload),
484        OpenedStreamPayload::EpochCommit(_) => {
485            anyhow::bail!("stream epoch control is not an application payload")
486        }
487    }
488}
489
490#[allow(clippy::too_many_arguments)]
491fn open_sealed_payload_inner(
492    enc_key: &[u8; 32],
493    topic: &str,
494    epoch: u64,
495    sequence_number: u64,
496    payload_index: usize,
497    tag: &[u8],
498    ciphertext: &[u8],
499    nonce: &[u8],
500    key_commitment: &[u8],
501) -> Result<OpenedStreamPayload> {
502    use crate::crypto::event_crypto::{check_key_commitment, decrypt_event_full};
503
504    let nonce12: [u8; 12] = nonce
505        .try_into()
506        .map_err(|_| anyhow::anyhow!("stream AEAD: bad nonce length {}", nonce.len()))?;
507    let commitment16: [u8; 16] = key_commitment.try_into().map_err(|_| {
508        anyhow::anyhow!(
509            "stream AEAD: bad key_commitment length {}",
510            key_commitment.len()
511        )
512    })?;
513
514    // Fast committing-AEAD rejection of a wrong-key block before the GCM open.
515    if !check_key_commitment(enc_key, &nonce12, &commitment16) {
516        anyhow::bail!("stream AEAD: key commitment mismatch (wrong key or tampered block)");
517    }
518
519    let aad = stream_aead_aad(topic, epoch, sequence_number, payload_index);
520    let plaintext = decrypt_event_full(enc_key, &nonce12, tag, ciphertext, &aad)
521        .map_err(|e| anyhow::anyhow!("stream AEAD open failed: {e}"))?;
522
523    let (&kind, body) = plaintext
524        .split_first()
525        .ok_or_else(|| anyhow::anyhow!("stream AEAD: empty sealed plaintext (missing kind tag)"))?;
526    match kind {
527        SEALED_KIND_DATA => Ok(OpenedStreamPayload::Application(StreamPayload::Data(
528            body.to_vec(),
529        ))),
530        SEALED_KIND_COMPLETE => Ok(OpenedStreamPayload::Application(StreamPayload::Complete(
531            body.to_vec(),
532        ))),
533        SEALED_KIND_ERROR => Ok(OpenedStreamPayload::Application(StreamPayload::Error(
534            std::str::from_utf8(body)
535                .map_err(|error| {
536                    anyhow::anyhow!("stream AEAD: sealed error is not UTF-8: {error}")
537                })?
538                .to_owned(),
539        ))),
540        SEALED_KIND_EPOCH_COMMIT => Ok(OpenedStreamPayload::EpochCommit(
541            crate::stream_epoch::StreamEpochCommit::decode_control_object(body)?,
542        )),
543        other => anyhow::bail!("stream AEAD: unknown sealed kind tag {other:#x}"),
544    }
545}
546
547// ============================================================================
548// StreamHandleImpl<T> — unified stream consumer over any Transport
549// ============================================================================
550
551/// E2E authenticated stream consumer, generic over transport.
552///
553/// Same struct on native (`StreamHandle<ZmqConnection>`) and WASM
554/// (`StreamHandle<WtConnection>`). ECDH, key derivation, MAC verification,
555/// and Cap'n Proto parsing are identical — only the wire transport differs.
556pub struct StreamHandleImpl<T: Transport> {
557    subscriber: T::Sub,
558    publisher: Option<T::Pub>,
559    stream_id: String,
560    topic: String,
561    verifier: StreamVerifier,
562    pending: VecDeque<StreamPayload>,
563    completed: bool,
564    cancelled: Arc<AtomicBool>,
565    ctrl_topic: String,
566    ctrl_mac_key: [u8; 32],
567}
568
569impl<T: Transport> StreamHandleImpl<T> {
570    /// Full streaming setup: ECDH → derive keys → subscribe → open ctrl → create verifier.
571    ///
572    /// Called by `RpcClient::open_stream()` after the streaming RPC returns `StreamInfo`.
573    ///
574    /// #385 INVARIANT (S8 close-out — `dhPublic` authenticity):
575    /// The entire AEAD + chained-HMAC integrity envelope bootstraps from
576    /// `stream_info.dh_public` — the server's ephemeral Ristretto255 DH public
577    /// key. It is trustworthy ONLY because `StreamInfo` arrives over the
578    /// authenticated RPC response: carrier target/path checks are insufficient;
579    /// the reply is independently wrapped in a `ResponseEnvelope` carrying a
580    /// COSE composite signature (EdDSA +
581    /// ML-DSA-65 under Hybrid), so `dhPublic` authentication reaches PQ
582    /// strength. A `dh_public` sourced from an *unauthenticated* path would let
583    /// any MITM substitute its own key, derive the stream keys itself, and forge
584    /// frames — defeating the whole envelope. This entry point is the single
585    /// library/codegen boundary that turns a `StreamInfo` into a live stream;
586    /// `dh_public` MUST therefore arrive here already authenticated. Callers
587    /// MUST NOT construct `StreamInfo` from untrusted input (e.g. a forwarded
588    /// relay advertisement or an unsigned lookup result). See
589    /// [`crate::rpc_client::parse_stream_info`] — the only producer of a
590    /// `StreamInfo` from wire bytes, reached solely via the authenticated
591    /// `call_streaming` RPC reply path.
592    pub async fn open(
593        transport: &T,
594        stream_info: StreamInfo,
595        client_secret: &[u8; 32],
596        client_pubkey: &[u8; 32],
597    ) -> Result<Self> {
598        // Pure crypto — same code, both targets.
599        // #385: assert the INVARIANT above at the entry point — the envelope's
600        // integrity is a consequence of `dh_public`'s authenticity, so a
601        // zero/empty `dh_public` (an obvious "StreamInfo-from-untrusted-input"
602        // signature) fails fast here rather than producing a silently-weak
603        // handshake. (A *substituted* valid key is not detectable at this layer;
604        // it is detected by the consumer's AEAD/MAC verification failing — see
605        // the `relay_dhpublic_substitution_is_rejected` test.)
606        assert!(
607            stream_info.dh_public.iter().any(|&b| b != 0),
608            "#385 INVARIANT: StreamInfo.dh_public must be a real (non-zero) DH key — \
609             never construct StreamInfo from untrusted input"
610        );
611        let shared_secret = dh_compute_raw(client_secret, &stream_info.dh_public)?;
612        let keys = derive_stream_keys(&shared_secret, client_pubkey, &stream_info.dh_public)?;
613
614        // Transport-abstracted — ZMQ or WebTransport
615        let subscriber = transport.subscribe(keys.topic.as_bytes()).await?;
616        let publisher = transport.publish(keys.ctrl_topic.as_bytes()).await.ok();
617
618        // QoS contract from the signed StreamInfo handshake — enforced for both native and WASM paths.
619        // #321: AEAD ON for this DH-keyed (mesh/networked) stream — open sealed Tagged blocks.
620        let verifier =
621            StreamVerifier::with_policy(*keys.mac_key, keys.topic.clone(), stream_info.qos.into())
622                .with_enc_key(*keys.enc_key);
623
624        Ok(Self {
625            subscriber,
626            publisher,
627            stream_id: stream_info.stream_id,
628            topic: keys.topic,
629            verifier,
630            pending: VecDeque::new(),
631            completed: false,
632            cancelled: Arc::new(AtomicBool::new(false)),
633            ctrl_topic: keys.ctrl_topic,
634            ctrl_mac_key: *keys.ctrl_mac_key,
635        })
636    }
637
638    /// Get next verified payload. Returns None on stream end.
639    pub async fn next_payload(&mut self) -> Result<Option<StreamPayload>> {
640        // Drain buffered payloads first
641        if let Some(p) = self.pending.pop_front() {
642            return Ok(Some(p));
643        }
644        if self.completed || self.cancelled.load(Ordering::Acquire) {
645            return Ok(None);
646        }
647
648        // Poll subscriber (T::Sub implements futures::Stream)
649        let frames = match self.subscriber.next().await {
650            Some(Ok(frames)) => frames,
651            Some(Err(e)) => return Err(e),
652            None => {
653                self.completed = true;
654                return Ok(None);
655            }
656        };
657
658        // Verify MAC + parse Cap'n Proto (pure crypto, cross-target)
659        let payloads = self.verifier.verify(&frames)?;
660        for p in payloads {
661            if matches!(p, StreamPayload::Complete(..) | StreamPayload::Error(..)) {
662                self.completed = true;
663            }
664            self.pending.push_back(p);
665        }
666
667        Ok(self.pending.pop_front())
668    }
669
670    /// Cancel the stream via ctrl channel.
671    /// Sets local cancelled flag AND sends cancel message to producer.
672    ///
673    /// Takes `&mut self` so the future is `Send` (holds `&mut Self`, which is
674    /// `Send` because `Self: Send`) rather than requiring `Self: Sync`. See
675    /// #670 / the `StreamHandle::cancel` trait method.
676    pub async fn cancel(&mut self) -> Result<()> {
677        self.cancelled.store(true, Ordering::Release);
678        if let Some(ref pub_handle) = self.publisher {
679            let msg = build_stream_control_cancel();
680            let mac = keyed_mac_truncated(&self.ctrl_mac_key, &msg);
681            pub_handle
682                .send_frames(&[self.ctrl_topic.as_bytes(), &msg, &mac])
683                .await?;
684        }
685        Ok(())
686    }
687
688    pub fn stream_id(&self) -> &str {
689        &self.stream_id
690    }
691
692    pub fn topic(&self) -> &str {
693        &self.topic
694    }
695
696    pub fn is_completed(&self) -> bool {
697        self.completed
698    }
699}
700
701/// Build a StreamControl::Cancel capnp message.
702#[allow(clippy::expect_used)]
703fn build_stream_control_cancel() -> Vec<u8> {
704    let mut builder = capnp::message::Builder::new_default();
705    {
706        let mut ctrl = builder.init_root::<streaming_capnp::stream_control::Builder>();
707        ctrl.set_cancel(());
708    }
709    let mut buf = Vec::new();
710    capnp::serialize::write_message(&mut buf, &builder)
711        .expect("StreamControl serialization cannot fail");
712    buf
713}
714
715// ============================================================================
716// StreamHandle — object-safe trait for generated portable clients
717// ============================================================================
718
719/// Object-safe stream handle for dynamic dispatch.
720///
721/// Generated portable clients use `Box<dyn StreamHandle>` so they work
722/// with any `StreamHandleImpl<T>` regardless of concrete transport.
723///
724/// # `Send` futures on native (#670)
725///
726/// On native the trait methods return `Send` futures (plain `#[async_trait]`),
727/// so a native `Send + Sync` `Mount` (e.g. the `/stream` pipe reader in
728/// `hyprstream-rpc-std`) can hold a `StreamHandle` future across `.await`. This
729/// is sound because the only implementors are `StreamHandleImpl<T>` and
730/// `Box<dyn StreamHandle>`, and `StreamHandleImpl<T>` is built entirely from the
731/// `Transport` associated types — which are already `Send`
732/// (`Transport::Sub: Send`, `Transport::Pub: Send`), and whose native
733/// `PublishSink` impls return `Send` futures.
734///
735/// On wasm the trait stays `#[async_trait(?Send)]`: the WebTransport
736/// `WtPublisher::send_frames` future holds JS values and is genuinely `!Send`,
737/// and the browser namespace never needs `Send` (wasm32 is single-threaded).
738/// The dual `cfg_attr` mirrors the `hyprstream_vfs::Mount` trait itself.
739#[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)]
740#[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))]
741pub trait StreamHandle: Send {
742    /// Get next verified payload. Returns None on stream end.
743    async fn next_payload(&mut self) -> Result<Option<StreamPayload>>;
744
745    /// Cancel the stream via ctrl channel.
746    ///
747    /// Takes `&mut self` (not `&self`) so the returned future is `Send` without
748    /// requiring `Self: Sync` — a `dyn StreamHandle` is `Send` but not `Sync`
749    /// (its transport `Sub`/`Pub` are only `Send`-bound), so a `&self` future
750    /// could not be sent across threads. `&mut self` also matches the state it
751    /// mutates (the cancelled flag). See #670.
752    async fn cancel(&mut self) -> Result<()>;
753
754    /// Get the stream ID.
755    fn stream_id(&self) -> &str;
756
757    /// Check if stream is completed.
758    fn is_completed(&self) -> bool;
759}
760
761/// Blanket impl: any `StreamHandleImpl<T>` satisfies `StreamHandle`.
762#[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)]
763#[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))]
764impl<T: Transport> StreamHandle for StreamHandleImpl<T> {
765    async fn next_payload(&mut self) -> Result<Option<StreamPayload>> {
766        StreamHandleImpl::next_payload(self).await
767    }
768
769    async fn cancel(&mut self) -> Result<()> {
770        StreamHandleImpl::cancel(self).await
771    }
772
773    fn stream_id(&self) -> &str {
774        StreamHandleImpl::stream_id(self)
775    }
776
777    fn is_completed(&self) -> bool {
778        StreamHandleImpl::is_completed(self)
779    }
780}
781
782/// Blanket impl for Box<dyn StreamHandle> so callers can use it directly.
783#[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)]
784#[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))]
785impl StreamHandle for Box<dyn StreamHandle> {
786    async fn next_payload(&mut self) -> Result<Option<StreamPayload>> {
787        (**self).next_payload().await
788    }
789
790    async fn cancel(&mut self) -> Result<()> {
791        (**self).cancel().await
792    }
793
794    fn stream_id(&self) -> &str {
795        (**self).stream_id()
796    }
797
798    fn is_completed(&self) -> bool {
799        (**self).is_completed()
800    }
801}
802
803// ─── Conversion from wire StreamOpt ───────────────────────────────────────────
804
805/// Convert the full wire `StreamOpt` (5 axes) to the consumer's 2-axis slice.
806///
807/// The delivery, retention, and overflow_policy axes are producer-side concerns;
808/// the consumer only enforces ordering + completion.
809impl From<crate::stream_info::StreamOpt> for VerifierContract {
810    fn from(q: crate::stream_info::StreamOpt) -> Self {
811        let ordering = match q.ordering {
812            crate::stream_info::Ordering::Ordered => StreamOrdering::Ordered,
813            crate::stream_info::Ordering::Unordered { anti_replay_window } => {
814                StreamOrdering::Unordered { anti_replay_window }
815            }
816        };
817        let completion = match q.completion {
818            crate::stream_info::Completion::EndOfStream => Completion::EndOfStream,
819            crate::stream_info::Completion::None => Completion::Open,
820        };
821        VerifierContract {
822            ordering,
823            completion,
824        }
825    }
826}
827
828#[cfg(test)]
829#[allow(clippy::unwrap_used, clippy::expect_used)]
830mod policy_tests {
831    use super::*;
832
833    /// Build one `[topic, capnp StreamBlock, mac]` frame, chaining the MAC exactly as the
834    /// producer does (`prev` ‖ capnp, or topic for the first block).
835    fn frame(
836        key: &[u8; 32],
837        topic: &str,
838        prev: Option<[u8; 16]>,
839        sequence_number: u64,
840        terminal: bool,
841    ) -> (Vec<Vec<u8>>, [u8; 16]) {
842        let mut msg = capnp::message::Builder::new_default();
843        {
844            let mut b = msg.init_root::<streaming_capnp::stream_block::Builder>();
845            let pm: Vec<u8> = match prev {
846                Some(p) => p.to_vec(),
847                None => topic.as_bytes().iter().take(16).copied().collect(),
848            };
849            b.set_prev_mac(&pm);
850            b.set_sequence_number(sequence_number);
851            b.set_epoch(0);
852            let mut list = b.init_payloads(1);
853            let mut p = list.reborrow().get(0);
854            if terminal {
855                p.set_complete(b"done");
856            } else {
857                p.set_data(b"x");
858            }
859        }
860        let mut capnp_bytes = Vec::new();
861        capnp::serialize::write_message(&mut capnp_bytes, &msg).unwrap();
862        let mut input = Vec::new();
863        match prev {
864            None => input.extend_from_slice(topic.as_bytes()),
865            Some(p) => input.extend_from_slice(&p),
866        }
867        input.extend_from_slice(&capnp_bytes);
868        let mac = keyed_mac_truncated(key, &input);
869        (
870            vec![topic.as_bytes().to_vec(), capnp_bytes, mac.to_vec()],
871            mac,
872        )
873    }
874
875    #[test]
876    fn tampered_mac_is_rejected() {
877        // Exercises the subtle::ConstantTimeEq path in StreamVerifier::verify.
878        let key = [0xAAu8; 32];
879        let topic = "tamper";
880        let mut v = StreamVerifier::with_policy(
881            key,
882            topic.to_owned(),
883            VerifierContract {
884                ordering: StreamOrdering::Ordered,
885                completion: Completion::Open,
886            },
887        );
888        let (mut frame, _) = frame(&key, topic, None, 0, false);
889        // Corrupt the MAC part (last element of the frame).
890        let mac = frame.last_mut().unwrap();
891        mac[0] ^= 0xFF; // flip a bit — constant_time_eq must reject this
892        let err = v.verify(&frame).unwrap_err().to_string();
893        assert!(
894            err.contains("MAC")
895                || err.contains("mac")
896                || err.contains("HMAC")
897                || err.contains("invalid"),
898            "tampered MAC should be rejected, got: {err}"
899        );
900    }
901
902    #[test]
903    fn ordered_accepts_contiguous_and_rejects_gap() {
904        let key = [7u8; 32];
905        let topic = "tok";
906        let mut v = StreamVerifier::with_policy(
907            key,
908            topic.to_owned(),
909            VerifierContract {
910                ordering: StreamOrdering::Ordered,
911                completion: Completion::Open,
912            },
913        );
914        let (f5, m5) = frame(&key, topic, None, 5, false); // late-join at seq 5
915        v.verify(&f5).unwrap();
916        let (f6, m6) = frame(&key, topic, Some(m5), 6, false);
917        v.verify(&f6).unwrap();
918        let (f9, _) = frame(&key, topic, Some(m6), 9, false); // gap: expected 7
919        let err = v.verify(&f9).unwrap_err().to_string();
920        assert!(err.contains("ordering violation"), "got: {err}");
921    }
922
923    #[test]
924    fn no_policy_keeps_legacy_behaviour() {
925        let key = [3u8; 32];
926        let topic = "leg";
927        let mut v = StreamVerifier::new(key, topic.to_owned()); // no policy
928        let (f5, m5) = frame(&key, topic, None, 5, false);
929        v.verify(&f5).unwrap();
930        // Big seq jump is accepted — no enforcement without a policy (unchanged behaviour).
931        let (f9, _) = frame(&key, topic, Some(m5), 9, false);
932        v.verify(&f9).unwrap();
933    }
934
935    #[test]
936    fn unordered_rejected_until_per_group_mac() {
937        let key = [1u8; 32];
938        let topic = "med";
939        let mut v = StreamVerifier::with_policy(
940            key,
941            topic.to_owned(),
942            VerifierContract {
943                ordering: StreamOrdering::Unordered {
944                    anti_replay_window: 4,
945                },
946                completion: Completion::Open,
947            },
948        );
949        let (f0, _) = frame(&key, topic, None, 0, false);
950        assert!(v.verify(&f0).is_err());
951    }
952
953    #[test]
954    fn completion_tracks_terminal() {
955        let key = [5u8; 32];
956        let topic = "fin";
957        let mut v = StreamVerifier::with_policy(
958            key,
959            topic.to_owned(),
960            VerifierContract {
961                ordering: StreamOrdering::Ordered,
962                completion: Completion::EndOfStream,
963            },
964        );
965        assert!(v.requires_terminal());
966        assert!(!v.terminal_seen());
967        let (f0, m0) = frame(&key, topic, None, 0, false);
968        v.verify(&f0).unwrap();
969        assert!(!v.terminal_seen());
970        let (f1, _) = frame(&key, topic, Some(m0), 1, true); // terminal payload
971        v.verify(&f1).unwrap();
972        assert!(v.terminal_seen());
973    }
974
975    // ── #385 S8 — relay dhPublic-substitution rejection ──────────────────────
976    //
977    // Threat (S3 relay + S5 provenance gap): once a relay is interposed, a MITM
978    // relay could try to substitute its OWN `dhPublic` in the handshake so the
979    // consumer derives keys the relay controls. S5 COSE provenance authenticates
980    // each *frame* to the producing host, but the handshake `dhPublic`→producer
981    // binding is not separately tested. This test closes that gap: it shows the
982    // consumer's AEAD verification FAILS when the keys are derived from a
983    // `dhPublic` the relay substituted, because they do not match the keys the
984    // producer sealed the frame under. The consumer, holding the *authenticated*
985    // `dhPublic` (delivered over the RPC channel — see `StreamHandleImpl::open`
986    // INVARIANT), is never fooled: it never re-derives from a relay-supplied
987    // `dhPublic`. The test asserts the negative — *if* the relay's substituted
988    // key reached the key-derivation, AEAD open would fail — which is exactly
989    // the rejection property.
990    #[test]
991    fn relay_dhpublic_substitution_is_rejected() {
992        use crate::crypto::{derive_stream_keys, generate_ephemeral_keypair, ristretto_dh_raw};
993
994        // Consumer generates an ephemeral keypair (the `client_pubkey` it sends
995        // in the streaming RPC request).
996        let (client_secret, client_pub) = generate_ephemeral_keypair();
997        let client_pub_bytes = client_pub.to_bytes();
998        let client_secret_bytes = client_secret.scalar().to_bytes();
999
1000        // Producer's REAL ephemeral keypair — its public half is the `dhPublic`
1001        // the authenticated RPC reply carries (the value the consumer trusts).
1002        let (producer_secret, producer_pub) = generate_ephemeral_keypair();
1003        let real_dh_public = producer_pub.to_bytes();
1004
1005        // The relay's substituted keypair — the MITM key the relay would inject
1006        // in place of `dhPublic` to try to own the derived keys.
1007        let (_relay_secret, relay_pub) = generate_ephemeral_keypair();
1008        let relay_dh_public = relay_pub.to_bytes();
1009        assert_ne!(
1010            real_dh_public, relay_dh_public,
1011            "test setup: keys must differ"
1012        );
1013
1014        // Producer derives the REAL stream keys from the real DH (ECDH with the
1015        // client's public) — these are the keys it seals every frame under.
1016        let producer_shared =
1017            ristretto_dh_raw(&producer_secret.scalar().to_bytes(), &client_pub_bytes).unwrap();
1018        let real_keys =
1019            derive_stream_keys(&producer_shared, &client_pub_bytes, &real_dh_public).unwrap();
1020
1021        // Build one AEAD-sealed Tagged payload exactly as the producer does
1022        // (`moq_stream::seal_payload`), using the REAL enc_key. This is the
1023        // ciphertext the relay forwards verbatim (it is blind to the keys).
1024        let epoch = 0u64;
1025        let topic = real_keys.topic.clone();
1026        let real_enc = *real_keys.enc_key;
1027        let plaintext = {
1028            let mut p = Vec::with_capacity(1 + b"secret-token".len());
1029            p.push(SEALED_KIND_DATA);
1030            p.extend_from_slice(b"secret-token");
1031            p
1032        };
1033        use crate::crypto::event_crypto::{encrypt_event, EventPrivacy};
1034        let aad = stream_aead_aad(&topic, epoch, 0, 0);
1035        let (tag, ciphertext, nonce, key_commitment) =
1036            encrypt_event(&real_enc, &aad, &plaintext, EventPrivacy::ZeroKnowledge).unwrap();
1037
1038        // 1) Consumer holding the AUTHENTICATED keys (the real `dhPublic` arrived
1039        //    over the RPC channel) opens the relay-forwarded frame: SUCCESS.
1040        let consumer_shared = ristretto_dh_raw(&client_secret_bytes, &real_dh_public).unwrap();
1041        let consumer_keys =
1042            derive_stream_keys(&consumer_shared, &client_pub_bytes, &real_dh_public).unwrap();
1043        assert_eq!(
1044            *consumer_keys.enc_key, real_enc,
1045            "consumer (real dhPublic) and producer derive the same enc_key"
1046        );
1047        let opened = open_sealed_payload(
1048            &consumer_keys.enc_key,
1049            &topic,
1050            epoch,
1051            0,
1052            0,
1053            &tag,
1054            &ciphertext,
1055            &nonce,
1056            &key_commitment,
1057        )
1058        .expect("consumer with the authenticated dhPublic opens the frame");
1059        assert!(matches!(opened, StreamPayload::Data(d) if d == b"secret-token"));
1060
1061        // 2) Relay-substitution attack: a consumer that (wrongly) re-derived its
1062        //    keys from the RELAY's substituted `dhPublic` cannot open the frame —
1063        //    AEAD fails (wrong key). This is the rejection: the relay cannot make
1064        //    a substituted `dhPublic` stick, because the keys won't line up with
1065        //    the producer's sealed ciphertext. (The honest consumer never enters
1066        //    this branch — it keeps the authenticated `dhPublic`; this case shows
1067        //    what would happen if the substituted key were used.)
1068        let sub_shared = ristretto_dh_raw(&client_secret_bytes, &relay_dh_public).unwrap();
1069        let sub_keys =
1070            derive_stream_keys(&sub_shared, &client_pub_bytes, &relay_dh_public).unwrap();
1071        assert_ne!(
1072            *sub_keys.enc_key, real_enc,
1073            "substituted dhPublic MUST derive a different enc_key"
1074        );
1075        let subst_err = open_sealed_payload(
1076            &sub_keys.enc_key,
1077            &topic,
1078            epoch,
1079            0,
1080            0,
1081            &tag,
1082            &ciphertext,
1083            &nonce,
1084            &key_commitment,
1085        )
1086        .unwrap_err();
1087        let msg = subst_err.to_string();
1088        assert!(
1089            msg.contains("AEAD") || msg.contains("commitment") || msg.contains("key"),
1090            "substituted-dhPublic AEAD open should fail closed, got: {msg}"
1091        );
1092
1093        // 3) The MAC chain has the same property: a frame chained under the real
1094        //    mac_key fails verification under the relay's mac_key. This is the
1095        //    belt-and-braces check on the chained-HMAC envelope.
1096        let real_mac = *real_keys.mac_key;
1097        let sub_mac = *sub_keys.mac_key;
1098        assert_ne!(
1099            real_mac, sub_mac,
1100            "substituted dhPublic MUST derive a different mac_key"
1101        );
1102        let (real_frame, _) = frame(&real_mac, &topic, None, 0, false);
1103        // Real consumer (real mac_key) verifies the producer's frame.
1104        let mut v_real = StreamVerifier::with_policy(
1105            real_mac,
1106            topic.clone(),
1107            VerifierContract {
1108                ordering: StreamOrdering::Ordered,
1109                completion: Completion::Open,
1110            },
1111        );
1112        assert!(
1113            v_real.verify(&real_frame).is_ok(),
1114            "real mac_key verifies the frame"
1115        );
1116        // Substituted consumer (relay mac_key) CANNOT verify the producer's frame.
1117        let mut v_sub = StreamVerifier::with_policy(
1118            sub_mac,
1119            topic,
1120            VerifierContract {
1121                ordering: StreamOrdering::Ordered,
1122                completion: Completion::Open,
1123            },
1124        );
1125        assert!(
1126            v_sub.verify(&real_frame).is_err(),
1127            "a frame chained under the producer's mac_key MUST NOT verify under the \
1128             relay's substituted-dhPublic mac_key (the consumer rejects the substitution)"
1129        );
1130    }
1131}