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}