Skip to main content

hyprstream_rpc/
moq_stream.rs

1//! moq-lite streaming plane (M2a of epic #134).
2//!
3//! Point-to-point / per-recipient streaming only (request/response, token
4//! streams, and per-recipient unique topics such as `NotificationService`'s
5//! blind broadcast — each recipient gets its own topic, not a shared fan-out
6//! track). Broadcast fan-out (N subscribers learning about one event from one
7//! source) is consolidated on the sibling `crate::moq_event` origin instead —
8//! see its module doc for the two-origins split.
9//!
10//! This is the moq-native replacement for the ZMQ PULL→XPUB queuing proxy in
11//! [`crate::service::streaming`]. Instead of a forwarding proxy with a custom
12//! per-topic queue + late-join rejoin buffer, in-process publishers append
13//! directly to a shared `moq_net::Origin`, and external subscribers consume the
14//! *same* origin over the `moql` ALPN via
15//! [`crate::transport::iroh_moq::IrohMoqProtocolHandler`].
16//!
17//! # Topic → Track mapping
18//!
19//! The existing call-site contract is a topic string (64-hex DH-derived, or a
20//! `notify-*` / control topic) plus opaque payload bytes. We map:
21//!
22//! ```text
23//!   topic-string  ->  moq Broadcast path  {tenant}/{service}/{topic}/{instance}
24//!   StreamBlock   ->  one moq Group (sequence = block index)
25//!                       containing one Frame = capnp_bytes || mac[16]
26//! ```
27//!
28//! For the in-process / direct path (M2a), the broadcast path is built from a
29//! caller-supplied `{tenant}/{service}/.../{instance}` prefix joined with the
30//! opaque topic. The topic itself stays opaque (and, for the relay'd path in
31//! M2b, DH-derived/unguessable). A single track name (`STREAM_TRACK`) carries
32//! the block sequence.
33//!
34//! # §7.5 chained-HMAC tokenstream
35//!
36//! The chained-HMAC envelope is preserved 1:1: each Group's Frame payload is
37//! the same `[capnp StreamBlock || 16-byte truncated MAC]` that the ZMQ wire
38//! format carried in frames 1+2 (frame 0, the topic, is now the Track/Broadcast
39//! path and is therefore dropped from the payload). [`StreamHmacState`] /
40//! [`StreamVerifier`] are reused unchanged, so the MAC chain — which binds each
41//! block to its predecessor — is byte-identical to the ZMQ path.
42//!
43//! Late-join is now moq's job: a subscriber that joins late is served the
44//! latest Group natively by the moq Track cache (respecting upstream Group
45//! cache consts), so the custom `StreamResume` / rejoin-buffer code is gone.
46
47use std::collections::HashMap;
48use std::path::{Path, PathBuf};
49use std::sync::{
50    atomic::{AtomicU64, Ordering},
51    Arc, OnceLock, Weak,
52};
53
54use anyhow::{anyhow, ensure, Context, Result};
55use bytes::Bytes;
56use moq_net::{
57    Broadcast, BroadcastConsumer, BroadcastProducer, Group, OriginConsumer, OriginProducer, Track,
58    TrackProducer,
59};
60use parking_lot::{Mutex, RwLock};
61use tokio_util::sync::CancellationToken;
62
63use crate::crypto::StreamHmacState;
64use crate::stream_epoch::StreamEpochRatchet;
65use crate::streaming::{StreamContext, StreamPayloadData, StreamVerifier};
66
67// ============================================================================
68// Process-global moq streaming origin — set once at startup, read everywhere.
69// Allows StreamChannel (publisher side) to use the same origin as StreamService
70// (server side) without threading it through every service factory.
71// ============================================================================
72
73static GLOBAL_MOQ_ORIGIN: OnceLock<MoqStreamOrigin> = OnceLock::new();
74/// The UDS socket path serving the moq plane (set by `serve_moq_uds_background`).
75static GLOBAL_MOQ_UDS_PATH: OnceLock<PathBuf> = OnceLock::new();
76/// Accepted-state-bound proof used for native Iroh `moql` client admission.
77/// Installed by the daemon's checkpointed service configuration; absent in
78/// browser, local, and test profiles.
79static GLOBAL_MOQ_ADMISSION_PROOF: OnceLock<crate::transport::moql_admission::MoqlAdmissionProof> =
80    OnceLock::new();
81
82/// Install this process's accepted-state-bound Iroh admission proof.
83pub fn init_global_moq_admission_proof(
84    proof: crate::transport::moql_admission::MoqlAdmissionProof,
85) -> bool {
86    GLOBAL_MOQ_ADMISSION_PROOF.set(proof).is_ok()
87}
88
89/// Borrow the process proof for other authenticated native MoQ planes.
90pub fn global_moq_admission_proof(
91) -> Option<&'static crate::transport::moql_admission::MoqlAdmissionProof> {
92    GLOBAL_MOQ_ADMISSION_PROOF.get()
93}
94
95/// Register the process-global moq streaming origin.
96///
97/// Must be called once at startup (from the streams service factory) before any
98/// `StreamChannel::publisher()` call. Returns `true` on first call, `false` if
99/// already set (idempotent — a second set is silently ignored).
100pub fn init_global_moq_origin(origin: MoqStreamOrigin) -> bool {
101    GLOBAL_MOQ_ORIGIN.set(origin).is_ok()
102}
103
104/// Borrow the process-global moq streaming origin, if initialized.
105///
106/// `None` when moq is not yet wired (unit tests, ZMQ-only deployments).
107pub fn global_moq_origin() -> Option<&'static MoqStreamOrigin> {
108    GLOBAL_MOQ_ORIGIN.get()
109}
110
111/// Path of the UDS socket that serves the moq streaming plane to local clients.
112///
113/// Set by [`serve_moq_uds_background`] once the listener is ready.
114/// `None` in ZMQ-only or unit-test deployments.
115pub fn global_moq_uds_path() -> Option<&'static Path> {
116    GLOBAL_MOQ_UDS_PATH.get().map(PathBuf::as_path)
117}
118
119/// Bound QUIC reach for one service's MoQ producer.
120#[derive(Clone, Debug)]
121pub struct NodeStreamReach {
122    /// Bound socket address external subscribers dial (`/moq` over WebTransport).
123    pub addr: std::net::SocketAddr,
124    /// TLS SNI / WebPKI validation name advertised for the endpoint.
125    pub server_name: String,
126    /// Acceptable leaf-cert SHA-256 pins (self-signed mesh; rotation = multiple).
127    pub cert_hashes: Vec<[u8; 32]>,
128}
129
130/// A node/server's moq reach inputs (#384) — the per-server context that builds
131/// a producer's `StreamInfo.reach`.
132///
133/// Plain config data (`Clone`, `Send + Sync`). The common-case relay is a
134/// server-global value (often an anycast PDS / federation-anchor address)
135/// carried in [`relay`]; a per-stream override is supplied at build time via
136/// [`ProducerReachConfig::reach_with_relay`].
137#[derive(Clone, Debug, Default)]
138pub struct ProducerReachConfig {
139    /// Resolver-verified accepted-state witness for this service's signed
140    /// StreamInfo. Native Iroh subscribers require it for mutual admission.
141    pub moql_server_identity: Option<crate::stream_info::MoqlServerIdentity>,
142    /// Resolver-verified accepted-state witness for the configured relay.
143    /// This is deliberately separate from the producing service's witness:
144    /// carrier EndpointId pinning is not application identity.
145    pub relay_moql_server_identity: Option<crate::stream_info::MoqlServerIdentity>,
146    /// The node's own iroh `EndpointId` (Ed25519 public key, 32 bytes) when the
147    /// iroh substrate is bound (#357). `None` → no iroh-direct reach advertised.
148    pub iroh_node_id: Option<[u8; 32]>,
149    /// The node's network-routable Quic / WebTransport reach (the bound QUIC
150    /// address + TLS name + leaf-cert pins). `None` → no Quic-direct reach
151    /// (UDS-only / unit-test deployments).
152    pub quic_reach: Option<NodeStreamReach>,
153    /// The server-global producer-chosen relay (#358), in wire-reach form.
154    /// `None` → direct-only advertisement (S1/S2 behaviour). A per-stream
155    /// override may supersede this for an individual stream.
156    pub relay: Option<crate::stream_info::TransportConfig>,
157}
158
159/// Mutable per-service reach source. The service spawner fills it with the
160/// actual QUIC and iroh bind results before the service accepts requests.
161pub type ProducerReachConfigHandle = Arc<RwLock<ProducerReachConfig>>;
162
163impl ProducerReachConfig {
164    /// Build this server's `StreamInfo.reach` using its server-global relay.
165    ///
166    /// Equivalent to `reach_with_relay(RelayChoice::ServerDefault)`. See
167    /// [`ProducerReachConfig::reach_with_relay`] for the per-stream override and
168    /// the reach-ordering contract.
169    pub fn reach(&self) -> Vec<crate::stream_info::Destination> {
170        self.reach_with_relay(RelayChoice::ServerDefault)
171    }
172
173    /// Build a stream's `StreamInfo.reach`, applying a per-stream relay choice (#384).
174    ///
175    /// Reach ORDERING contract (unchanged — `select_reach` does the QoS reorder
176    /// downstream): **iroh-direct first, then Quic, then relay** ("direct-first"
177    /// wire order). Server authority is preserved: the client may only route
178    /// among the reaches advertised here, so a relay-only stream
179    /// ([`RelayChoice::Only`]) omits the direct reaches and stays anonymized.
180    pub fn reach_with_relay(
181        &self,
182        relay_choice: RelayChoice,
183    ) -> Vec<crate::stream_info::Destination> {
184        use crate::stream_info::{Destination, IrohReach, QuicReach, Role, TransportConfig};
185        let mut reach = Vec::new();
186
187        // A per-stream `Only` (relay-only / anonymized) override omits ALL direct
188        // reaches so the client cannot route around the relay (server authority).
189        let relay_only = matches!(relay_choice, RelayChoice::Only(_));
190
191        if !relay_only {
192            // iroh-direct first (#357): native peers prefer the NAT-traversing,
193            // pkarr-discoverable direct path. Listed ahead of Quic so the shared
194            // resolver (`connect_moq_reach`) tries it before the Quic/UDS
195            // fallbacks. `None` when iroh is disabled/unbound (Quic-only).
196            if let Some(node_id) = self.iroh_node_id {
197                reach.push(Destination {
198                    role: Role::Direct,
199                    // moq streaming reach → moql ALPN; relayUrl empty = direct/pkarr (#282).
200                    transport: TransportConfig::Iroh(IrohReach {
201                        node_id,
202                        alpn: String::from_utf8_lossy(
203                            crate::transport::iroh_substrate::ALPN_MOQ_LITE,
204                        )
205                        .into_owned(),
206                        relay_url: String::new(),
207                    }),
208                    moql_server_identity: self.moql_server_identity.clone().unwrap_or_default(),
209                });
210            }
211
212            // Quic / WebTransport reach: directly-reachable peers + browsers.
213            // Kept as a fallback alongside iroh (S1's fallbacks preserved).
214            if let Some(r) = &self.quic_reach {
215                reach.push(Destination {
216                    role: Role::Direct,
217                    transport: TransportConfig::Quic(QuicReach {
218                        addr: r.addr.to_string(),
219                        server_name: r.server_name.clone(),
220                        cert_hashes: r.cert_hashes.iter().map(|h| h.to_vec()).collect(),
221                    }),
222                    moql_server_identity: self.moql_server_identity.clone().unwrap_or_default(),
223                });
224            }
225        }
226
227        // Relay reach (#358): the rendezvous endpoint. A subscriber that cannot
228        // (or, per QoS, prefers not to) reach the producer directly rendezvouses
229        // through it instead. Listed AFTER the direct reaches ("direct-first"
230        // wire order); the QoS-aware `select_reach` reorders relay-first for
231        // resumable/retained/fan-out streams (Job/Log).
232        //
233        // The per-stream choice picks WHICH relay (or none):
234        //   - `ServerDefault` → this server's `self.relay` (the common case),
235        //   - `Override(r)`   → a per-stream relay (per-tenant isolation),
236        //   - `Only(r)`       → a per-stream relay, direct reaches omitted,
237        //   - `NoRelay`        → no relay reach (direct-only for this stream).
238        let relay = match relay_choice {
239            RelayChoice::ServerDefault => self
240                .relay
241                .clone()
242                .map(|relay| (relay, self.relay_moql_server_identity.clone())),
243            // An override describes an independent remote endpoint. It must not
244            // inherit the server-default relay's accepted-state witness.
245            RelayChoice::Override(target) | RelayChoice::Only(target) => {
246                Some((target.transport, Some(target.server_identity)))
247            }
248            RelayChoice::NoRelay => None,
249        };
250        if let Some((relay, relay_identity)) = relay {
251            reach.push(Destination {
252                role: Role::Relay,
253                transport: relay,
254                moql_server_identity: relay_identity.unwrap_or_default(),
255            });
256        }
257
258        reach
259    }
260}
261
262/// Per-stream relay selection for [`ProducerReachConfig::reach_with_relay`] (#384).
263///
264/// Lets one stream pick a relay (or go relay-only / direct-only) independently
265/// of another in the SAME process — the heterogeneous-anonymization property.
266#[derive(Clone, Debug, Default)]
267pub enum RelayChoice {
268    /// Use the server-global relay ([`ProducerReachConfig::relay`]) — the common
269    /// case. Falls back to direct-only when the server has no relay configured.
270    #[default]
271    ServerDefault,
272    /// Override the server-global relay with a separately resolver-verified
273    /// per-stream target (e.g. per-tenant isolation). Direct reaches are still
274    /// advertised alongside it. A transport alone cannot authenticate an Iroh
275    /// relay and is deliberately not representable here.
276    Override(RelayTarget),
277    /// Relay-ONLY (anonymized): use this per-stream relay and OMIT all direct
278    /// reaches, so the client can only route through the relay (server authority).
279    Only(RelayTarget),
280    /// No relay reach for this stream — advertise the direct reaches only.
281    ///
282    /// Named `NoRelay` (not `None`) to avoid shadowing [`Option::None`] under a
283    /// glob import of this enum's variants.
284    NoRelay,
285}
286
287/// One independently resolver-verified relay selection for a stream.
288///
289/// The accepted-state server witness belongs to the relay, not the producer
290/// advertising the reach. Keeping them together prevents an Override/Only
291/// call site from emitting an Iroh relay that cannot confirm its remote peer.
292#[derive(Clone, Debug)]
293pub struct RelayTarget {
294    pub transport: crate::stream_info::TransportConfig,
295    pub server_identity: crate::stream_info::MoqlServerIdentity,
296}
297
298impl RelayTarget {
299    pub fn new(
300        transport: crate::stream_info::TransportConfig,
301        server_identity: crate::stream_info::MoqlServerIdentity,
302    ) -> Self {
303        Self {
304            transport,
305            server_identity,
306        }
307    }
308}
309
310/// Build the producer-chosen relay's wire-reach [`crate::stream_info::TransportConfig`]
311/// from a DID-document transport entry decoded by [`crate::service_entry`] (#358).
312///
313/// This is the bridge that keeps the stream relay address and the DID transport
314/// address from drifting: a node resolves its relay's DID service entry (default
315/// `#atproto_pds`), decodes it with the shared [`crate::service_entry::decode_service_entry`]
316/// codec, and passes the resulting [`crate::transport::TransportConfig`] here to
317/// obtain the wire-reach form to place in a [`ProducerReachConfig`].
318///
319/// Returns `None` for same-host transports (`ipc`/`inproc`/`systemd-fd`), which
320/// are never network-routable relay endpoints.
321pub fn relay_reach_from_decoded(
322    config: &crate::transport::TransportConfig,
323) -> Option<crate::stream_info::TransportConfig> {
324    use crate::stream_info::{IrohReach, QuicReach, TransportConfig as ReachTransport};
325    use crate::transport::EndpointType;
326    match &config.endpoint {
327        EndpointType::Quic {
328            addr,
329            server_name,
330            auth,
331        } => Some(ReachTransport::Quic(QuicReach {
332            addr: addr.to_string(),
333            server_name: server_name.clone(),
334            cert_hashes: auth
335                .accept_cert_hashes()
336                .iter()
337                .map(|h| h.to_vec())
338                .collect(),
339        })),
340        EndpointType::Iroh {
341            node_id, relay_url, ..
342        } => {
343            // A relay carries the moq stream → moql ALPN; relay_url passes through.
344            Some(ReachTransport::Iroh(IrohReach {
345                node_id: *node_id,
346                alpn: String::from_utf8_lossy(crate::transport::iroh_substrate::ALPN_MOQ_LITE)
347                    .into_owned(),
348                relay_url: relay_url.clone().unwrap_or_default(),
349            }))
350        }
351        EndpointType::Ipc { .. } | EndpointType::SystemdFd { .. } | EndpointType::Inproc { .. } => {
352            None
353        }
354    }
355}
356
357/// Start a UDS moq server in the background, serving the moq origin's consumer
358/// to local cross-process subscribers (e.g. `hyprstream tui attach`).
359///
360/// Each accepted connection that presents [`crate::transport::uds_session::PLANE_MOQ`]
361/// gets a dedicated moq server session via `moq_net::Server::with_publish`.
362/// The origin consumer is cloned per session so every subscriber sees the
363/// same live broadcast tree.
364///
365/// Idempotent: a second call is a no-op (the first path wins).
366pub fn serve_moq_uds_background(origin: MoqStreamOrigin, path: PathBuf) {
367    use crate::transport::uds_session::{accept_uds, PLANE_MOQ};
368    use moq_net::Server as MoqServer;
369
370    if native_iroh_required() {
371        tracing::error!("network-iroh-required refuses a local MoQ socket server");
372        return;
373    }
374    // Remove stale socket from a previous run (best-effort).
375    let _ = std::fs::remove_file(&path);
376
377    // Bind synchronously so the socket exists before we advertise the path.
378    // Any caller reading global_moq_uds_path() is guaranteed the socket is ready.
379    let listener = match std::os::unix::net::UnixListener::bind(&path) {
380        Ok(l) => l,
381        Err(e) => {
382            tracing::error!(path = %path.display(), "moq UDS bind failed: {e}");
383            return;
384        }
385    };
386
387    // 0o600: owner read/write only; SO_PEERCRED enforces uid match on Linux (see uds_server.rs).
388    #[cfg(unix)]
389    {
390        use std::os::unix::fs::PermissionsExt;
391        let _ = std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600));
392    }
393
394    // tokio requires the listener be non-blocking before adoption; otherwise
395    // `from_std` panics ("Registering a blocking socket with the tokio runtime
396    // is unsupported"). Mirrors the event-bus plane (moq_event.rs).
397    if let Err(e) = listener.set_nonblocking(true) {
398        tracing::error!("moq UDS set_nonblocking failed: {e}");
399        return;
400    }
401
402    // Convert to async and publish the path only after the socket is bound.
403    let listener = match tokio::net::UnixListener::from_std(listener) {
404        Ok(l) => l,
405        Err(e) => {
406            tracing::error!("moq UDS listener conversion failed: {e}");
407            return;
408        }
409    };
410
411    if GLOBAL_MOQ_UDS_PATH.set(path.clone()).is_err() {
412        return; // already started (concurrent call)
413    }
414
415    tracing::info!(path = %path.display(), "moq UDS listener ready");
416
417    tokio::spawn(async move {
418        loop {
419            let stream = match listener.accept().await {
420                Ok((s, _)) => s,
421                Err(e) => {
422                    tracing::warn!("moq UDS accept error: {e}");
423                    continue;
424                }
425            };
426            let consumer = origin.consumer().clone();
427            tokio::spawn(async move {
428                let (plane, session) = match accept_uds(stream).await {
429                    Ok(pair) => pair,
430                    Err(e) => {
431                        tracing::debug!("moq UDS handshake error: {e}");
432                        return;
433                    }
434                };
435                if plane != PLANE_MOQ {
436                    tracing::debug!("moq UDS: unexpected plane 0x{plane:02x} — dropping");
437                    return;
438                }
439                if let Err(e) = MoqServer::new()
440                    .with_publish(consumer)
441                    .accept(session)
442                    .await
443                {
444                    tracing::debug!("moq UDS session ended: {e}");
445                }
446            });
447        }
448    });
449}
450
451/// Timeout waiting for the moq origin to announce a broadcast at startup.
452pub const BROADCAST_ANNOUNCE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
453
454/// Timeout between consecutive moq Groups on a subscribed track.
455/// A timeout here signals the publisher is gone; the subscriber breaks out.
456pub const GROUP_IDLE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
457
458/// Timeout reading a single Frame from an already-opened Group.
459pub const FRAME_READ_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5);
460
461/// The single track name that carries StreamBlock groups for a broadcast.
462pub const STREAM_TRACK: &str = "stream";
463
464/// Default `{tenant}/{service}` broadcast-path prefix for the in-process plane.
465///
466/// The instance segment is appended per-publisher (the opaque topic). Callers
467/// that want tenant isolation pass their own prefix to
468/// [`MoqStreamOrigin::with_prefix`].
469pub const DEFAULT_PREFIX: &str = "local/streams";
470
471/// Shared moq origin for the streaming plane, plus the in-process publish gate.
472///
473/// Holds the `OriginProducer` (what in-process publishers append into) and the
474/// `OriginConsumer` (handed to `moq_net::Server` to serve external subscribers).
475/// This is the moq replacement for [`crate::service::StreamService`]'s ZMQ
476/// proxy: there is no forwarding loop — producers and consumers share one tree.
477#[derive(Clone)]
478pub struct MoqStreamOrigin {
479    inner: Arc<OriginInner>,
480}
481
482/// Mutable per-service MoQ origin source. `None` preserves the process-global
483/// origin for services that do not need relay isolation.
484pub type MoqStreamOriginHandle = Arc<RwLock<Option<MoqStreamOrigin>>>;
485
486/// Builder for [`MoqStreamOrigin`] — set the prefix and publish gate before the
487/// shared `Arc` is constructed (avoids clone-on-write of the origin tree).
488pub struct MoqStreamOriginBuilder {
489    producer: OriginProducer,
490    consumer: OriginConsumer,
491    prefix: String,
492    authorize_signer: Option<Arc<dyn Fn(&[u8; 32]) -> bool + Send + Sync>>,
493}
494
495impl MoqStreamOriginBuilder {
496    /// Set the `{tenant}/{service}` broadcast-path prefix.
497    pub fn with_prefix(mut self, prefix: impl Into<String>) -> Self {
498        self.prefix = prefix.into();
499        self
500    }
501
502    /// Install the in-process publish gate (mirrors
503    /// `StreamService::with_authorize_signer`).
504    pub fn with_authorize_signer(
505        mut self,
506        f: impl Fn(&[u8; 32]) -> bool + Send + Sync + 'static,
507    ) -> Self {
508        self.authorize_signer = Some(Arc::new(f));
509        self
510    }
511
512    /// Finish building.
513    pub fn build(self) -> MoqStreamOrigin {
514        MoqStreamOrigin {
515            inner: Arc::new(OriginInner {
516                producer: self.producer,
517                consumer: self.consumer,
518                prefix: self.prefix,
519                authorize_signer: self.authorize_signer,
520                broadcasts: Mutex::new(HashMap::new()),
521                next_broadcast_generation: AtomicU64::new(0),
522            }),
523        }
524    }
525}
526
527struct BroadcastEntry {
528    _producer: BroadcastProducer,
529    generation: u64,
530}
531
532struct OriginInner {
533    producer: OriginProducer,
534    consumer: OriginConsumer,
535    /// `{tenant}/{service}` prefix for broadcast paths.
536    prefix: String,
537    /// Optional in-process publish gate (mirrors `StreamService::authorize_signer`).
538    ///
539    /// When set, [`MoqStreamOrigin::authorize_signer`] must return `true` before
540    /// a publisher is created for a topic. `None` accepts any caller
541    /// (testing/bootstrap), matching the ZMQ default.
542    authorize_signer: Option<Arc<dyn Fn(&[u8; 32]) -> bool + Send + Sync>>,
543    /// Keep broadcast producers alive while their publishers are active.
544    ///
545    /// Keyed by broadcast path (replace semantics) so a re-announced topic
546    /// drops the old `BroadcastProducer` (unannouncing it) rather than
547    /// accumulating unboundedly (#164).
548    broadcasts: Mutex<HashMap<String, BroadcastEntry>>,
549    next_broadcast_generation: AtomicU64,
550}
551
552/// Removes the publisher's broadcast entry only while that exact publication
553/// is still current. A weak origin avoids making the publisher/cleanup guard
554/// retain the origin forever, and the generation prevents an old publisher
555/// from removing a newer same-path replacement.
556struct BroadcastCleanup {
557    origin: Weak<OriginInner>,
558    path: String,
559    generation: u64,
560}
561
562impl Drop for BroadcastCleanup {
563    fn drop(&mut self) {
564        let Some(origin) = self.origin.upgrade() else {
565            return;
566        };
567        let removed = {
568            let mut broadcasts = origin.broadcasts.lock();
569            let remove = broadcasts
570                .get(&self.path)
571                .is_some_and(|entry| entry.generation == self.generation);
572            if remove {
573                broadcasts.remove(&self.path)
574            } else {
575                None
576            }
577        };
578        // Drop the BroadcastProducer after releasing the origin mutex. Its
579        // close/unannounce path can notify consumers and must not re-enter the
580        // origin map while the lock is held.
581        drop(removed);
582    }
583}
584
585impl MoqStreamOrigin {
586    /// Begin building from an existing producer/consumer pair (e.g. the one
587    /// held by [`crate::transport::iroh_moq::IrohMoqProtocolHandler`]).
588    pub fn builder(producer: OriginProducer, consumer: OriginConsumer) -> MoqStreamOriginBuilder {
589        MoqStreamOriginBuilder {
590            producer,
591            consumer,
592            prefix: DEFAULT_PREFIX.to_owned(),
593            authorize_signer: None,
594        }
595    }
596
597    /// Build directly from a producer/consumer pair with defaults.
598    pub fn from_pair(producer: OriginProducer, consumer: OriginConsumer) -> Self {
599        Self::builder(producer, consumer).build()
600    }
601
602    /// Begin building a standalone origin with a fresh random id.
603    ///
604    /// Used when no shared substrate origin is available yet (M2a bootstrap).
605    /// Callers that have the substrate's `IrohMoqProtocolHandler` should use
606    /// [`Self::builder`] with its `origin_producer()` / `origin_consumer()`
607    /// instead, so external subscribers see the same tree.
608    pub fn standalone() -> MoqStreamOriginBuilder {
609        let producer = moq_net::Origin::random().produce();
610        let consumer = producer.consume();
611        Self::builder(producer, consumer)
612    }
613
614    /// Borrow the consumer (hand this to `moq_net::Server::with_publish`).
615    pub fn consumer(&self) -> &OriginConsumer {
616        &self.inner.consumer
617    }
618
619    /// Borrow the producer.
620    pub fn producer(&self) -> &OriginProducer {
621        &self.inner.producer
622    }
623
624    /// Check the in-process publish gate for a signer pubkey.
625    ///
626    /// Returns `true` when no gate is installed (bootstrap/testing).
627    pub fn authorize_signer(&self, signer: &[u8; 32]) -> bool {
628        match &self.inner.authorize_signer {
629            Some(f) => f(signer),
630            None => true,
631        }
632    }
633
634    /// Build the broadcast path for an opaque topic: `{prefix}/{topic}`.
635    pub fn broadcast_path(&self, topic: &str) -> String {
636        format!("{}/{}", self.inner.prefix, topic)
637    }
638
639    /// Create an in-process publisher for `ctx`'s topic.
640    ///
641    /// Creates (or replaces) the broadcast at `{prefix}/{topic}` with a single
642    /// [`STREAM_TRACK`] track, and returns a [`MoqStreamPublisher`] whose
643    /// chained-HMAC state is seeded from `ctx.mac_key()` / `ctx.topic()` — i.e.
644    /// byte-identical to the ZMQ `StreamBuilder`.
645    pub fn publisher(&self, ctx: &StreamContext) -> Result<MoqStreamPublisher> {
646        self.publisher_with_provenance(ctx, None)
647    }
648
649    /// Create an in-process publisher that additionally signs each StreamBlock
650    /// with the node's per-host hybrid COSE identity (#321 provenance / C-PROV).
651    ///
652    /// `provenance = Some(signer)` attaches a `StreamBlock.provenance` signature
653    /// so consumers can attribute each block to the producing host (threat T3);
654    /// `None` keeps the legacy chained-HMAC-only block.
655    pub fn publisher_with_provenance(
656        &self,
657        ctx: &StreamContext,
658        provenance: Option<crate::stream_provenance::ProvenanceSigner>,
659    ) -> Result<MoqStreamPublisher> {
660        ensure!(
661            !ctx.has_epoch_ratchet() || ctx.enc_key().is_some(),
662            "identified stream rejected a context with transport AEAD disabled"
663        );
664        // Hold the identified producer claim through all fallible MoQ setup.
665        // Every `StreamContext` clone shares this lock/slot. The ratchet is
666        // consumed only once setup succeeds, so a setup error remains retryable
667        // while successful construction cannot restart epoch/group/sequence
668        // zero or reuse the same AEAD key and nonce domain.
669        ctx.with_publisher_epoch_ratchet(|epoch_ratchet| {
670            let path = self.broadcast_path(ctx.topic());
671            let (broadcast, track) = publish_stream_broadcast(&path, |path, broadcast| {
672                self.inner.producer.publish_broadcast(path, broadcast)
673            })?;
674
675            let generation = self
676                .inner
677                .next_broadcast_generation
678                .fetch_add(1, Ordering::Relaxed);
679
680            // Retain the broadcast producer so it stays announced for the
681            // publisher's lifetime (dropping it would unannounce the broadcast).
682            // Replace-semantics: inserting the same path twice drops the old
683            // BroadcastProducer rather than accumulating indefinitely (#164).
684            let replaced = self.inner.broadcasts.lock().insert(
685                path.clone(),
686                BroadcastEntry {
687                    _producer: broadcast,
688                    generation,
689                },
690            );
691            // Replacement closes the old broadcast; keep that potentially
692            // notifying drop outside the origin mutex.
693            drop(replaced);
694
695            Ok(MoqStreamPublisher {
696                hmac_state: StreamHmacState::new(*ctx.mac_key(), ctx.topic().to_owned()),
697                // #321: AEAD enc_key — `Some` only on the DH (mesh) path. `None` on the
698                // keyless `StreamContext::new` path (NotificationService topics, whose
699                // payloads are already E2E-encrypted), where transport AEAD is skipped.
700                enc_key: ctx.enc_key().copied(),
701                provenance,
702                track,
703                next_group: 0,
704                next_sequence: 0,
705                epoch_ratchet: epoch_ratchet.take(),
706                cancel_token: ctx.cancel_token().clone(),
707                terminated: false,
708                topic: ctx.topic().to_owned(),
709                _broadcast_cleanup: BroadcastCleanup {
710                    origin: Arc::downgrade(&self.inner),
711                    path,
712                    generation,
713                },
714            })
715        })
716    }
717}
718
719/// Announce only after the required track is ready: another worker can subscribe
720/// as soon as publication becomes visible, before publisher construction returns.
721fn publish_stream_broadcast(
722    path: &str,
723    announce: impl FnOnce(&str, BroadcastConsumer) -> bool,
724) -> Result<(BroadcastProducer, TrackProducer)> {
725    let mut broadcast = Broadcast::new().produce();
726    let track = broadcast.create_track(Track::new(STREAM_TRACK))?;
727    ensure!(
728        announce(path, broadcast.consume()),
729        "create_broadcast denied for {path}"
730    );
731    Ok((broadcast, track))
732}
733
734/// In-process moq publisher with the §7.5 chained-HMAC tokenstream.
735///
736/// API mirrors [`crate::streaming::StreamPublisher`] (`publish_data`,
737/// `publish_error`, `complete`, ...) but appends to a moq Track instead of a
738/// ZMQ PUSH socket. Each call produces one StreamBlock = one moq Group whose
739/// single Frame payload is `capnp_bytes || mac[16]`.
740/// NOTE (M2a vs M2b): the StreamBlock *encoding* + HMAC chain are byte-identical
741/// to the ZMQ path (shared `encode_stream_block`), but the *batching policy*
742/// differs — this emits one payload per block/Group, whereas the ZMQ
743/// `StreamBuilder` adaptively batches multiple payloads per block. The MAC
744/// chain is valid either way (the verifier is batch-agnostic). Port
745/// `BatchingConfig` in M2b for granularity parity.
746pub struct MoqStreamPublisher {
747    hmac_state: StreamHmacState,
748    /// Transport-level AEAD key (#321). `Some` ⇒ each Data/Complete/Error payload is
749    /// sealed with AES-256-GCM into a `Tagged` payload before the HMAC chain runs;
750    /// `None` ⇒ cleartext (keyless notification path).
751    enc_key: Option<[u8; 32]>,
752    /// Per-host provenance signer (#321). `Some` ⇒ each StreamBlock carries a
753    /// hybrid COSE signature over its canonical signed region.
754    provenance: Option<crate::stream_provenance::ProvenanceSigner>,
755    track: TrackProducer,
756    /// Immutable MOQT Object identity: this counter never resets across rekeys.
757    next_group: u64,
758    /// Authenticated sequence number within the committed key epoch.
759    next_sequence: u64,
760    /// Identified transcript-bound epoch state; absent on legacy/keyless paths.
761    epoch_ratchet: Option<crate::stream_epoch::StreamEpochRatchet>,
762    cancel_token: CancellationToken,
763    terminated: bool,
764    topic: String,
765    _broadcast_cleanup: BroadcastCleanup,
766}
767
768impl MoqStreamPublisher {
769    /// Wait until a subscriber has attached before publishing a short lived
770    /// response. The demand is observable on the producer track, so callers
771    /// can avoid finishing before a late subscriber has a chance to join.
772    pub async fn wait_for_consumer(&self) -> Result<()> {
773        if self.cancel_token.is_cancelled() {
774            anyhow::bail!("stream cancelled before consumer demand");
775        }
776        tokio::select! {
777            _ = self.cancel_token.cancelled() => {
778                anyhow::bail!("stream cancelled before consumer demand");
779            }
780            result = self.track.used() => {
781                result.map_err(|error| anyhow!("stream consumer demand failed: {error}"))
782            }
783        }
784    }
785
786    /// Publish an opaque, authenticated control Object under the current epoch,
787    /// then atomically advance the producer to the next epoch. The consumer
788    /// performs the same verify-before-advance transition from the wire Object.
789    /// `next_group` deliberately never resets, preserving immutable MOQT IDs.
790    pub fn publish_next_epoch(&mut self) -> Result<u64> {
791        let ratchet = self
792            .epoch_ratchet
793            .as_ref()
794            .ok_or_else(|| anyhow!("stream is not using the identified epoch profile"))?;
795        let commit = ratchet.prepare_next()?;
796        let mut pending = ratchet.clone();
797        let keys = pending.commit_prepared(&commit)?;
798
799        // The current keys authenticate and encrypt this control Object. Do not
800        // expose or install the pending epoch until stock MoQ accepted the Object.
801        self.write_block(&[StreamPayloadData::EpochCommit(commit)])?;
802
803        self.hmac_state =
804            StreamHmacState::new(*keys.producer_to_consumer.mac_key, self.topic.clone());
805        self.enc_key = Some(*keys.producer_to_consumer.enc_key);
806        self.next_sequence = 0;
807        self.epoch_ratchet = Some(pending);
808        Ok(keys.epoch)
809    }
810
811    /// Publish one binary payload as a StreamBlock group.
812    pub async fn publish_data(&mut self, data: &[u8]) -> Result<()> {
813        if self.cancel_token.is_cancelled() {
814            anyhow::bail!("stream cancelled");
815        }
816        self.write_block(&[StreamPayloadData::Data(data.to_vec())])
817    }
818
819    /// Publish an error payload (terminal).
820    pub async fn publish_error(&mut self, message: &str) -> Result<()> {
821        self.write_block(&[StreamPayloadData::Error(message.to_owned())])?;
822        self.track.finish()?;
823        self.terminated = true;
824        Ok(())
825    }
826
827    /// Complete the stream with metadata (terminal).
828    pub async fn complete(mut self, metadata: &[u8]) -> Result<()> {
829        self.complete_ref(metadata).await
830    }
831
832    /// Complete the stream without consuming `self`.
833    pub async fn complete_ref(&mut self, metadata: &[u8]) -> Result<()> {
834        self.write_block(&[StreamPayloadData::Complete(metadata.to_vec())])?;
835        self.track.finish()?;
836        self.terminated = true;
837        Ok(())
838    }
839
840    /// The opaque topic this publisher serves.
841    pub fn topic(&self) -> &str {
842        &self.topic
843    }
844
845    /// Whether a terminal frame (Error/Complete) was sent.
846    pub fn is_terminated(&self) -> bool {
847        self.terminated
848    }
849
850    /// Whether the stream has been cancelled.
851    pub fn is_cancelled(&self) -> bool {
852        self.cancel_token.is_cancelled()
853    }
854
855    /// Serialize payloads into a StreamBlock, chain the MAC, and append as a
856    /// moq Group (one Frame = `capnp || mac`).
857    fn write_block(&mut self, payloads: &[StreamPayloadData]) -> Result<()> {
858        // `sequenceNumber` is per key epoch. `group_id` below is the immutable,
859        // lifetime-wide MOQT identity and deliberately never resets at rekey.
860        let sequence_number = self.next_sequence;
861        let epoch = self
862            .epoch_ratchet
863            .as_ref()
864            .map_or(0, StreamEpochRatchet::epoch);
865        let is_epoch_control = matches!(payloads, [StreamPayloadData::EpochCommit(_)]);
866        if is_epoch_control && self.enc_key.is_none() {
867            anyhow::bail!("identified stream epoch control cannot be serialized without AEAD");
868        }
869        if let Some(state) = &self.epoch_ratchet {
870            ensure!(
871                !payloads
872                    .iter()
873                    .any(|payload| matches!(payload, StreamPayloadData::Tagged { .. })),
874                "identified stream rejected pre-tagged payload bypass"
875            );
876            let limit = state.binding().max_blocks_per_epoch();
877            if sequence_number > limit || (sequence_number == limit && !is_epoch_control) {
878                anyhow::bail!(
879                    "identified stream epoch {epoch} exhausted after {} blocks; authenticated rekey required",
880                    state.binding().max_blocks_per_epoch()
881                );
882            }
883        }
884        let group_id = self.next_group;
885        let next_group = self
886            .next_group
887            .checked_add(1)
888            .ok_or_else(|| anyhow!("stream Group identity exhausted"))?;
889        let next_sequence = self
890            .next_sequence
891            .checked_add(1)
892            .ok_or_else(|| anyhow!("stream sequence exhausted"))?;
893
894        // #321: on the mesh/DH path (`enc_key = Some`), seal each application/control
895        // payload with AES-256-GCM into a `Tagged` payload BEFORE the HMAC chain
896        // runs (so the chain authenticates the ciphertext — no double-encryption,
897        // ordering/anti-replay unchanged). The AEAD AAD/key-commitment are bound to the block's
898        // `epoch` (and topic), so a rekey can't replay a block across epochs.
899        let sealed: Vec<StreamPayloadData>;
900        let payloads: &[StreamPayloadData] = match self.enc_key {
901            Some(ref enc_key) => {
902                let epoch_keys = self
903                    .epoch_ratchet
904                    .as_ref()
905                    .map(crate::stream_epoch::StreamEpochRatchet::current_keys);
906                sealed = payloads
907                    .iter()
908                    .enumerate()
909                    .map(|(index, p)| {
910                        let nonce = epoch_keys
911                            .as_ref()
912                            .map(|keys| {
913                                // One MoQ block currently carries one payload.  Keep
914                                // the index in the checked nonce position so future
915                                // batching cannot reuse a nonce silently.
916                                let counter = sequence_number
917                                    .checked_mul(1 << 16)
918                                    .and_then(|value| value.checked_add(index as u64))
919                                    .ok_or_else(|| {
920                                        anyhow!("stream payload nonce counter exhausted")
921                                    })?;
922                                Ok::<[u8; 12], anyhow::Error>(
923                                    keys.producer_to_consumer.nonce(counter),
924                                )
925                            })
926                            .transpose()?;
927                        seal_payload(
928                            enc_key,
929                            &self.topic,
930                            epoch,
931                            sequence_number,
932                            index,
933                            nonce,
934                            p,
935                        )
936                    })
937                    .collect::<Result<Vec<_>>>()?;
938                &sealed
939            }
940            None => payloads,
941        };
942
943        // Canonical signed region (#321): the StreamBlock with provenance EMPTY.
944        // This is what the provenance signature covers and what the consumer
945        // reconstructs; it also equals the legacy block when provenance is off.
946        let signed_region = crate::streaming::encode_stream_block(
947            self.hmac_state.prev_mac_bytes(),
948            sequence_number,
949            epoch,
950            payloads,
951        )?;
952
953        // #321 provenance: sign the signed region with the host's hybrid identity,
954        // then emit the block WITH the provenance field. The HMAC below covers the
955        // full wire bytes (incl. provenance); the sig covers the signed region, so
956        // verification is a layer on top of HMAC. No provenance ⇒ wire == signed_region.
957        let capnp_bytes = match self.provenance {
958            Some(ref signer) => {
959                let (signer_kid, sig) = signer.sign(&signed_region)?;
960                crate::streaming::encode_stream_block_with_provenance(
961                    self.hmac_state.prev_mac_bytes(),
962                    sequence_number,
963                    epoch,
964                    payloads,
965                    Some((&signer_kid, &sig)),
966                )?
967            }
968            None => signed_region,
969        };
970        let mut pending_hmac_state = self.hmac_state.clone();
971        let mac = pending_hmac_state.compute_next(&capnp_bytes);
972
973        let mut frame = Vec::with_capacity(capnp_bytes.len() + 16);
974        frame.extend_from_slice(&capnp_bytes);
975        frame.extend_from_slice(&mac);
976
977        let mut group = self.track.create_group(Group::from(group_id))?;
978        group.write_frame(Bytes::from(frame))?;
979        group.finish()?;
980
981        // Publication is the commit point: failures above leave all sequence,
982        // identity, and chained-MAC state unchanged, so a retry cannot create a
983        // gap or reuse an already-advanced cryptographic state.
984        self.hmac_state = pending_hmac_state;
985        self.next_group = next_group;
986        self.next_sequence = next_sequence;
987        Ok(())
988    }
989}
990
991// ============================================================================
992// AnyStreamPublisher — moq-lite publish API
993// ============================================================================
994
995/// Publisher for the moq-lite streaming plane.
996///
997/// Type alias for [`MoqStreamPublisher`]; the ZMQ variant was removed in the
998/// N4 hard cutover (#138/#213). Retained as an alias so existing call sites
999/// compile unchanged.
1000pub type AnyStreamPublisher = MoqStreamPublisher;
1001
1002impl MoqStreamPublisher {
1003    /// Publish binary data with a rate hint (ignored — each call maps 1:1 to one moq Group).
1004    pub async fn publish_data_with_rate(&mut self, data: &[u8], rate: f32) -> Result<()> {
1005        let _ = rate;
1006        self.publish_data(data).await
1007    }
1008
1009    /// Publish a progress update (`stage:current:total`).
1010    pub async fn publish_progress(
1011        &mut self,
1012        stage: &str,
1013        current: usize,
1014        total: usize,
1015    ) -> Result<()> {
1016        let data = format!("{}:{}:{}", stage, current, total);
1017        self.publish_data(data.as_bytes()).await
1018    }
1019
1020    /// Flush — no-op (each block is published immediately).
1021    pub async fn flush(&mut self) -> Result<()> {
1022        Ok(())
1023    }
1024
1025    /// Non-blocking publish — always succeeds immediately (no HWM concept).
1026    /// The `rate` hint is ignored.
1027    pub async fn try_publish_data(&mut self, data: &[u8], rate: f32) -> Result<bool> {
1028        let _ = rate;
1029        self.publish_data(data).await.map(|_| true)
1030    }
1031}
1032
1033/// moq stream consumer handle for MCP tool calls and other async consumers.
1034///
1035/// Connects to the moq UDS plane, subscribes to the broadcast, verifies the
1036/// chained-HMAC frames, and delivers [`crate::streaming::StreamPayload`]s via
1037/// an internal channel. Mirrors the `StreamHandle` interface (same `recv_next()`,
1038/// `stream_id()`, `cancel_token()`, and `futures::Stream` impl) so callers need
1039/// no code change beyond the constructor.
1040pub struct MoqStreamHandle {
1041    rx: tokio::sync::mpsc::Receiver<anyhow::Result<crate::streaming::StreamPayload>>,
1042    broadcast_path: String,
1043    cancel: tokio_util::sync::CancellationToken,
1044}
1045
1046impl MoqStreamHandle {
1047    /// Construct a handle and immediately spawn the background receive task.
1048    ///
1049    /// The task connects to the UDS moq server, subscribes to `broadcast_path`,
1050    /// verifies frames with the chained HMAC (derived from `mac_key` + `topic`),
1051    /// and forwards payloads to the channel. Errors and end-of-stream close the
1052    /// channel so `recv_next()` returns `Err` or `Ok(None)` respectively.
1053    pub fn new(
1054        uds_path: String,
1055        broadcast_path: String,
1056        mac_key: [u8; 32],
1057        enc_key: [u8; 32],
1058        topic: String,
1059    ) -> Self {
1060        let cancel = tokio_util::sync::CancellationToken::new();
1061        let (tx, rx) =
1062            tokio::sync::mpsc::channel::<anyhow::Result<crate::streaming::StreamPayload>>(64);
1063        tokio::spawn(moq_stream_handle_task(
1064            uds_path,
1065            broadcast_path.clone(),
1066            mac_key,
1067            enc_key,
1068            topic,
1069            None,
1070            tx,
1071            cancel.clone(),
1072        ));
1073        Self {
1074            rx,
1075            broadcast_path,
1076            cancel,
1077        }
1078    }
1079
1080    /// Construct an identified-profile UDS consumer whose receive loop accepts
1081    /// authenticated in-band epoch controls before delivering later Objects.
1082    pub fn identified(
1083        uds_path: String,
1084        broadcast_path: String,
1085        ratchet: crate::stream_epoch::StreamEpochRatchet,
1086    ) -> Self {
1087        let keys = ratchet.current_keys();
1088        let topic = ratchet.route_topic().to_owned();
1089        let cancel = tokio_util::sync::CancellationToken::new();
1090        let (tx, rx) =
1091            tokio::sync::mpsc::channel::<anyhow::Result<crate::streaming::StreamPayload>>(64);
1092        tokio::spawn(moq_stream_handle_task(
1093            uds_path,
1094            broadcast_path.clone(),
1095            *keys.producer_to_consumer.mac_key,
1096            *keys.producer_to_consumer.enc_key,
1097            topic,
1098            Some(ratchet),
1099            tx,
1100            cancel.clone(),
1101        ));
1102        Self {
1103            rx,
1104            broadcast_path,
1105            cancel,
1106        }
1107    }
1108
1109    /// Construct a handle that subscribes over the **network** (#274), retaining
1110    /// the resolver-authenticated remote server witness for every Iroh dial.
1111    ///
1112    /// Resolves the signed `StreamInfo`'s `reach` list and dials the first
1113    /// dialable network reach via [`crate::dial::dial_stream`] over
1114    /// `web_transport_quinn` — exactly as the working CLI `quick infer` consumer
1115    /// does. After connecting, it subscribes to `broadcast_path` and verifies the
1116    /// chained-HMAC frames exactly as [`Self::new`] does. Errors/end-of-stream
1117    /// close the channel.
1118    ///
1119    /// ## Transport selection (#275 TUI streaming fix)
1120    ///
1121    /// The producer's `reach` is the source of truth for where the stream lives.
1122    /// A stream is a networked address; the subscriber dials the **producer's**
1123    /// reach. Loopback works same-host (the bound QUIC `/moq` endpoint), proven by
1124    /// the CLI, so the networked reach is used uniformly whenever the StreamInfo
1125    /// carries one.
1126    ///
1127    /// The local moq UDS plane ([`global_moq_uds_path`]) is used **only as a
1128    /// fallback** when the StreamInfo carries no dialable reach (UDS-only /
1129    /// unit-test deployments). It must NOT be preferred when a reach is present:
1130    /// the local UDS is *this process's own* moq plane, which only carries the
1131    /// producer's broadcast if the producer is co-located in this very process.
1132    /// A consumer process that runs its own moq plane for unrelated streams (e.g.
1133    /// the TUI daemon serving its PTY/shell stdout stream) would otherwise connect
1134    /// to its own empty plane and time out waiting for the model service's
1135    /// broadcast that was published on a *different* process's plane (#275).
1136    ///
1137    /// ## QoS-driven direct-vs-relay routing (#358)
1138    ///
1139    /// `qos` is the service-signed [`crate::stream_info::StreamOpt`]; it selects the
1140    /// preferred *topology* (direct vs relay) via [`select_reach`] — relay-first for
1141    /// retained/resumable/fan-out streams (Job/Log), direct-first for live pipes
1142    /// (`Retention::Live`). This is a stable reorder of the SERVICE-advertised reach
1143    /// only: the client never invents a reach, so a relay-only (anonymized) stream
1144    /// stays relay-only. Topology is orthogonal to the delivery/integrity contract.
1145    pub fn networked(
1146        reach: Vec<crate::stream_info::Destination>,
1147        qos: &crate::stream_info::StreamOpt,
1148        broadcast_path: String,
1149        mac_key: [u8; 32],
1150        enc_key: [u8; 32],
1151        topic: String,
1152        server_identity: crate::stream_info::MoqlServerIdentity,
1153    ) -> Self {
1154        Self::networked_with_server_identity(
1155            reach,
1156            qos,
1157            broadcast_path,
1158            mac_key,
1159            enc_key,
1160            topic,
1161            server_identity,
1162        )
1163    }
1164
1165    /// Native constructor that retains the server witness authenticated by the
1166    /// streaming RPC response for the Iroh admission resolver.
1167    pub fn networked_with_server_identity(
1168        reach: Vec<crate::stream_info::Destination>,
1169        qos: &crate::stream_info::StreamOpt,
1170        broadcast_path: String,
1171        mac_key: [u8; 32],
1172        enc_key: [u8; 32],
1173        topic: String,
1174        server_identity: crate::stream_info::MoqlServerIdentity,
1175    ) -> Self {
1176        // QoS-aware topology selection over the SERVICE-advertised reach (server
1177        // authority preserved: stable reorder, never an invented/forced reach).
1178        let reach = select_reach(&reach, qos);
1179        let cancel = tokio_util::sync::CancellationToken::new();
1180        let (tx, rx) =
1181            tokio::sync::mpsc::channel::<anyhow::Result<crate::streaming::StreamPayload>>(64);
1182        // Prefer the producer's networked reach (the StreamInfo source of truth):
1183        // dial the producer directly, mirroring the CLI. Only fall back to the
1184        // local moq UDS plane when the StreamInfo carries no dialable reach —
1185        // never the other way around (see method docs; #275).
1186        let has_dialable_reach = reach.iter().any(|d| reach_to_transport_config(d).is_some());
1187        if has_dialable_reach || native_iroh_required() {
1188            tokio::spawn(moq_stream_handle_task_networked(
1189                reach,
1190                broadcast_path.clone(),
1191                mac_key,
1192                enc_key,
1193                topic,
1194                None,
1195                server_identity,
1196                tx,
1197                cancel.clone(),
1198            ));
1199        } else if let Some(uds) = global_moq_uds_path() {
1200            let uds_path = uds.to_string_lossy().into_owned();
1201            tokio::spawn(moq_stream_handle_task(
1202                uds_path,
1203                broadcast_path.clone(),
1204                mac_key,
1205                enc_key,
1206                topic,
1207                None,
1208                tx,
1209                cancel.clone(),
1210            ));
1211        } else {
1212            // No dialable reach and no local UDS plane: surface a clear error
1213            // rather than spawning a task that cannot connect.
1214            tokio::spawn(async move {
1215                let _ = tx
1216                    .send(Err(anyhow!(
1217                        "no dialable reach in StreamInfo and no local moq UDS plane — \
1218                         cannot subscribe to broadcast"
1219                    )))
1220                    .await;
1221            });
1222        }
1223        Self {
1224            rx,
1225            broadcast_path,
1226            cancel,
1227        }
1228    }
1229
1230    /// Construct an identified-profile network consumer with its authenticated
1231    /// remote server witness. A standard relay sees ordinary opaque Objects;
1232    /// this receive loop consumes authenticated epoch controls and delivers
1233    /// application payloads only.
1234    pub fn networked_identified(
1235        reach: Vec<crate::stream_info::Destination>,
1236        qos: &crate::stream_info::StreamOpt,
1237        broadcast_path: String,
1238        ratchet: crate::stream_epoch::StreamEpochRatchet,
1239        server_identity: crate::stream_info::MoqlServerIdentity,
1240    ) -> Self {
1241        let reach = select_reach(&reach, qos);
1242        let keys = ratchet.current_keys();
1243        let mac_key = *keys.producer_to_consumer.mac_key;
1244        let enc_key = *keys.producer_to_consumer.enc_key;
1245        let topic = ratchet.route_topic().to_owned();
1246        let cancel = tokio_util::sync::CancellationToken::new();
1247        let (tx, rx) =
1248            tokio::sync::mpsc::channel::<anyhow::Result<crate::streaming::StreamPayload>>(64);
1249        let has_dialable_reach = reach.iter().any(|d| reach_to_transport_config(d).is_some());
1250        if has_dialable_reach || native_iroh_required() {
1251            tokio::spawn(moq_stream_handle_task_networked(
1252                reach,
1253                broadcast_path.clone(),
1254                mac_key,
1255                enc_key,
1256                topic,
1257                Some(ratchet),
1258                server_identity,
1259                tx,
1260                cancel.clone(),
1261            ));
1262        } else if let Some(uds) = global_moq_uds_path() {
1263            tokio::spawn(moq_stream_handle_task(
1264                uds.to_string_lossy().into_owned(),
1265                broadcast_path.clone(),
1266                mac_key,
1267                enc_key,
1268                topic,
1269                Some(ratchet),
1270                tx,
1271                cancel.clone(),
1272            ));
1273        } else {
1274            tokio::spawn(async move {
1275                let _ = tx
1276                    .send(Err(anyhow!(
1277                        "no dialable reach in StreamInfo and no local moq UDS plane — \
1278                         cannot subscribe to identified broadcast"
1279                    )))
1280                    .await;
1281            });
1282        }
1283        Self {
1284            rx,
1285            broadcast_path,
1286            cancel,
1287        }
1288    }
1289
1290    /// Receive the next stream payload.
1291    ///
1292    /// Returns `Ok(None)` when the stream ends cleanly, `Err` on a stream error.
1293    pub async fn recv_next(&mut self) -> anyhow::Result<Option<crate::streaming::StreamPayload>> {
1294        match self.rx.recv().await {
1295            Some(Ok(p)) => Ok(Some(p)),
1296            Some(Err(e)) => Err(e),
1297            None => Ok(None),
1298        }
1299    }
1300
1301    /// Returns the moq broadcast path used as stream identifier.
1302    pub fn stream_id(&self) -> &str {
1303        &self.broadcast_path
1304    }
1305
1306    /// Returns a cancellation token that aborts the background receive task.
1307    pub fn cancel_token(&self) -> &tokio_util::sync::CancellationToken {
1308        &self.cancel
1309    }
1310
1311    /// Cancel the background receive task immediately.
1312    pub fn cancel(&self) {
1313        self.cancel.cancel();
1314    }
1315}
1316
1317impl futures::Stream for MoqStreamHandle {
1318    type Item = anyhow::Result<crate::streaming::StreamPayload>;
1319
1320    fn poll_next(
1321        mut self: std::pin::Pin<&mut Self>,
1322        cx: &mut std::task::Context<'_>,
1323    ) -> std::task::Poll<Option<Self::Item>> {
1324        self.rx.poll_recv(cx)
1325    }
1326}
1327
1328// TODO: add reconnect backoff on UDS disconnect (ZMQ auto-reconnect parity)
1329#[allow(clippy::too_many_arguments)]
1330async fn moq_stream_handle_task(
1331    uds_path: String,
1332    broadcast_path: String,
1333    mac_key: [u8; 32],
1334    enc_key: [u8; 32],
1335    topic: String,
1336    epoch_ratchet: Option<crate::stream_epoch::StreamEpochRatchet>,
1337    tx: tokio::sync::mpsc::Sender<anyhow::Result<crate::streaming::StreamPayload>>,
1338    cancel: tokio_util::sync::CancellationToken,
1339) {
1340    use crate::streaming::StreamVerifier;
1341    use crate::transport::uds_session::{connect_uds, PLANE_MOQ};
1342    use moq_net::{Client as MoqClient, Origin, Track};
1343
1344    if native_iroh_required() {
1345        let _ = tx
1346            .send(Err(anyhow!(
1347                "network-iroh-required refuses a local MoQ socket client"
1348            )))
1349            .await;
1350        return;
1351    }
1352    let session = match connect_uds(&uds_path, PLANE_MOQ).await {
1353        Ok(s) => s,
1354        Err(e) => {
1355            let _ = tx
1356                .send(Err(anyhow!("moq UDS connect {uds_path}: {e}")))
1357                .await;
1358            return;
1359        }
1360    };
1361    let client_origin = Origin::random().produce();
1362    let client_consumer = client_origin.consume();
1363    let moq_client = MoqClient::new().with_consume(client_origin);
1364    let _session = match moq_client.connect(session).await {
1365        Ok(s) => s,
1366        Err(e) => {
1367            let _ = tx.send(Err(anyhow!("moq handshake: {e}"))).await;
1368            return;
1369        }
1370    };
1371    let bc = match tokio::time::timeout(
1372        BROADCAST_ANNOUNCE_TIMEOUT,
1373        client_consumer.announced_broadcast(&broadcast_path),
1374    )
1375    .await
1376    {
1377        Ok(Some(bc)) => bc,
1378        Ok(None) => {
1379            let _ = tx
1380                .send(Err(anyhow!("broadcast {broadcast_path} not announced")))
1381                .await;
1382            return;
1383        }
1384        Err(_) => {
1385            let _ = tx
1386                .send(Err(anyhow!(
1387                    "timeout waiting for broadcast {broadcast_path}"
1388                )))
1389                .await;
1390            return;
1391        }
1392    };
1393    let track = match bc.subscribe_track(&Track::new(STREAM_TRACK)) {
1394        Ok(t) => t,
1395        Err(e) => {
1396            let _ = tx.send(Err(anyhow!("subscribe_track: {e}"))).await;
1397            return;
1398        }
1399    };
1400    // #321: AEAD ON for this DH-keyed mesh stream — open sealed Tagged blocks.
1401    let mut verifier = StreamVerifier::new(mac_key, topic.clone()).with_enc_key(enc_key);
1402    if let Some(ratchet) = epoch_ratchet {
1403        verifier = verifier.with_epoch_ratchet(ratchet);
1404    }
1405    // #145: read groups by EXACT sequence (get_group), not arrival-order next_group.
1406    // Each Group is served on its own QUIC uni-stream, so Groups can arrive out of
1407    // order; next_group's monotonic cursor returns the first Group with sequence >=
1408    // its cursor in *arrival* order, so a lower-seq Group that arrives after a higher
1409    // one (e.g. the small terminal / always-retained max_sequence Group) is skipped —
1410    // fatally breaking the ordered, gap-fatal chained HMAC. get_group(seq) waits for
1411    // each exact Group (even out-of-order), guaranteeing in-order, gap-free delivery.
1412    let mut expected_seq = 0u64;
1413    loop {
1414        if cancel.is_cancelled() {
1415            break;
1416        }
1417        let mut group =
1418            match tokio::time::timeout(GROUP_IDLE_TIMEOUT, track.get_group(expected_seq)).await {
1419                Ok(Ok(Some(g))) => g,
1420                Ok(Ok(None)) => break, // track ended cleanly
1421                Err(_elapsed) => {
1422                    let _ = tx
1423                        .send(Err(anyhow!(
1424                            "stream idle: no group for {}s",
1425                            GROUP_IDLE_TIMEOUT.as_secs()
1426                        )))
1427                        .await;
1428                    break;
1429                }
1430                Ok(Err(e)) => {
1431                    let _ = tx.send(Err(anyhow!("moq next_group: {e}"))).await;
1432                    break;
1433                }
1434            };
1435        expected_seq += 1;
1436        let frame: bytes::Bytes =
1437            match tokio::time::timeout(FRAME_READ_TIMEOUT, group.read_frame()).await {
1438                Ok(Ok(Some(f))) => f,
1439                Ok(Ok(None)) => break, // group ended without a frame
1440                Ok(Err(e)) => {
1441                    let _ = tx.send(Err(anyhow!("frame read error: {e}"))).await;
1442                    break;
1443                }
1444                Err(_elapsed) => {
1445                    let _ = tx
1446                        .send(Err(anyhow!(
1447                            "frame read timeout after {}s",
1448                            FRAME_READ_TIMEOUT.as_secs()
1449                        )))
1450                        .await;
1451                    break;
1452                }
1453            };
1454        match verify_moq_frame(&mut verifier, &topic, &frame) {
1455            Ok(payloads) => {
1456                for p in payloads {
1457                    let is_terminal = matches!(
1458                        p,
1459                        crate::streaming::StreamPayload::Complete(_)
1460                            | crate::streaming::StreamPayload::Error(_)
1461                    );
1462                    if tx.send(Ok(p)).await.is_err() {
1463                        return;
1464                    }
1465                    if is_terminal {
1466                        return;
1467                    }
1468                }
1469            }
1470            Err(e) => {
1471                let _ = tx.send(Err(e)).await;
1472                return;
1473            }
1474        }
1475    }
1476}
1477
1478/// Convert a wire-published [`crate::stream_info::Destination`] into the local
1479/// [`crate::transport::TransportConfig`] [`crate::dial::dial_stream`] dials (#274).
1480///
1481/// Only the network-routable transports map; same-host endpoints are never
1482/// carried in `reach` (co-located clients use the UDS fast path).
1483pub fn reach_to_transport_config(
1484    reach: &crate::stream_info::Destination,
1485) -> Option<crate::transport::TransportConfig> {
1486    wire_transport_to_dial(&reach.transport)
1487}
1488
1489/// The single wire→dial reach codec (#274/#320): map one wire
1490/// [`crate::stream_info::TransportConfig`] union arm to the local dialable
1491/// [`crate::transport::TransportConfig`]. Returns `None` for an un-routable arm
1492/// (e.g. an iroh reach with no relay). Shared by the streaming plane
1493/// ([`reach_to_transport_config`]) and the RPC inference router (#320), so there
1494/// is exactly ONE iroh/quic reach decoding.
1495pub fn wire_transport_to_dial(
1496    wire: &crate::stream_info::TransportConfig,
1497) -> Option<crate::transport::TransportConfig> {
1498    use crate::stream_info::TransportConfig as ReachTransport;
1499    use crate::transport::{QuicServerAuth, TransportConfig};
1500    match wire {
1501        ReachTransport::Quic(q) => {
1502            let addr: std::net::SocketAddr = q.addr.parse().ok()?;
1503            // Fixed-size cert pins (SHA-256 = 32 bytes); skip any malformed entry.
1504            let hashes: Vec<[u8; 32]> = q
1505                .cert_hashes
1506                .iter()
1507                .filter_map(|h| <[u8; 32]>::try_from(h.as_slice()).ok())
1508                .collect();
1509            let auth = if hashes.is_empty() {
1510                QuicServerAuth::web_pki()
1511            } else {
1512                // Pinned self-signed mesh (matches the DID-doc #quic entry).
1513                QuicServerAuth::pinned(hashes).ok()?
1514            };
1515            Some(TransportConfig::quic_with_auth(
1516                addr,
1517                q.server_name.clone(),
1518                auth,
1519            ))
1520        }
1521        // #320/#357: dial the wire-advertised iroh reach by node_id. iroh binds
1522        // the dialed `moql` connection to this `EndpointId` (its Ed25519 pubkey);
1523        // `dial_stream`'s iroh arm (#282/S2) consumes it and opens the `moql`
1524        // session. When `relayUrl` is empty the shared client endpoint's pkarr /
1525        // n0 DNS discovery (`presets::N0`) resolves the routable addresses, so a
1526        // native peer can dial by node_id alone (no direct addrs are carried on
1527        // the wire — see `IrohReach` in streaming.capnp).
1528        ReachTransport::Iroh(i) => {
1529            let relay_url = if i.relay_url.is_empty() {
1530                None
1531            } else {
1532                Some(i.relay_url.clone())
1533            };
1534            Some(TransportConfig::iroh(i.node_id, Vec::new(), relay_url))
1535        }
1536    }
1537}
1538
1539/// The single dial→wire reach codec (#320): map a local dialable
1540/// [`crate::transport::TransportConfig`] to a wire-publishable
1541/// [`crate::stream_info::TransportConfig`] union arm.
1542///
1543/// Returns `None` for same-host endpoints (`Inproc`/`Ipc`/`SystemdFd`) — these
1544/// are NEVER advertised on the wire (a remote caller could not dial them; a
1545/// co-located caller resolves them from local config). So a co-located-only
1546/// service yields an empty published reach list. The inverse of
1547/// [`wire_transport_to_dial`]; both live here as the one reach codec.
1548pub fn dial_transport_to_wire(
1549    dial: &crate::transport::TransportConfig,
1550) -> Option<crate::stream_info::TransportConfig> {
1551    use crate::stream_info::{IrohReach, QuicReach, TransportConfig as ReachTransport};
1552    use crate::transport::EndpointType;
1553    match &dial.endpoint {
1554        EndpointType::Quic {
1555            addr,
1556            server_name,
1557            auth,
1558        } => Some(ReachTransport::Quic(QuicReach {
1559            addr: addr.to_string(),
1560            server_name: server_name.clone(),
1561            cert_hashes: auth
1562                .accept_cert_hashes()
1563                .iter()
1564                .map(|h| h.to_vec())
1565                .collect(),
1566        })),
1567        // The wire iroh reach carries the carrier address (nodeId) + relay only; direct
1568        // addrs are not published (privacy + iroh discovery), matching the
1569        // DID-doc `IrohTransport` entry shape (#280/#282).
1570        EndpointType::Iroh {
1571            node_id, relay_url, ..
1572        } => Some(ReachTransport::Iroh(IrohReach {
1573            node_id: *node_id,
1574            alpn: String::from_utf8_lossy(crate::transport::iroh_substrate::ALPN_HYPRSTREAM_RPC)
1575                .into_owned(),
1576            relay_url: relay_url.clone().unwrap_or_default(),
1577        })),
1578        // Same-host endpoints are never wire-advertised (#320).
1579        EndpointType::Inproc { .. } | EndpointType::Ipc { .. } | EndpointType::SystemdFd { .. } => {
1580            None
1581        }
1582    }
1583}
1584
1585/// A live moq subscriber connection resolved from a producer's reach (#356).
1586///
1587/// Holds the `OriginConsumer` callers `announced_broadcast` + `subscribe_track`
1588/// against, plus the underlying `moq_net::Session` which MUST be kept alive for
1589/// the duration of the subscription (dropping it tears the transport down).
1590pub struct MoqReachConnection {
1591    /// The consumer side of the client origin the producer's broadcast is
1592    /// announced into. Subscribe to the producer's `broadcast_path` on this.
1593    pub consumer: OriginConsumer,
1594    /// The live moq session. Held only to keep the transport open; not used
1595    /// directly by callers, but must not be dropped before the consumer.
1596    _session: moq_net::Session,
1597}
1598
1599/// Monotonic process transport policy installed by native deployment bootstrap.
1600static NATIVE_IROH_REQUIRED: std::sync::atomic::AtomicBool =
1601    std::sync::atomic::AtomicBool::new(false);
1602
1603/// Require native Iroh; later compatibility callers cannot reopen fallbacks.
1604pub fn require_native_iroh() {
1605    NATIVE_IROH_REQUIRED.store(true, std::sync::atomic::Ordering::Release);
1606}
1607
1608pub fn native_iroh_required() -> bool {
1609    NATIVE_IROH_REQUIRED.load(std::sync::atomic::Ordering::Acquire)
1610}
1611
1612/// Resolve a producer's reach into a live moq subscriber connection (#356).
1613///
1614/// This is the **single** reach→connection resolver shared by every networked
1615/// subscriber (the inference [`MoqStreamHandle::networked`] task and the CLI
1616/// model-load / `notify subscribe` consumers). It enforces one transport policy
1617/// in one place. A required native process accepts only Iroh and never takes
1618/// the compatibility QUIC/UDS alternatives below:
1619///
1620///   1. **Networked first** — dial the first dialable `Destination` in `reach`
1621///      (the producer's wire-advertised QUIC/`/moq` endpoint) via
1622///      [`crate::dial::dial_stream`]. This is the source of truth: the stream
1623///      lives wherever the *producer* advertised, so cross-process / cross-
1624///      instance subscribers reach it (fixes #142 + the TUI cross-process bug).
1625///   2. **Local UDS fallback** — only when `reach` carries NO dialable network
1626///      reach (UDS-only / unit-test deployments) do we connect to *this
1627///      process's* local moq UDS plane ([`global_moq_uds_path`]). The UDS path is
1628///      resolved from LOCAL knowledge, never from the wire — a same-host fast
1629///      path, never advertised.
1630///   3. **Fail closed** — if neither is available, return an error rather than
1631///      connecting to an empty/wrong plane and timing out.
1632///
1633/// The UDS fast path is NEVER preferred over a present networked reach: the local
1634/// UDS plane only carries the producer's broadcast when the producer is co-located
1635/// in this very process, so preferring it silently breaks cross-process delivery.
1636pub async fn connect_moq_reach(
1637    reach: &[crate::stream_info::Destination],
1638) -> Result<MoqReachConnection> {
1639    connect_moq_reach_with_server_identity(
1640        reach,
1641        &crate::stream_info::MoqlServerIdentity::default(),
1642    )
1643    .await
1644}
1645
1646/// Resolve a stream reach with the server accepted-state witness authenticated
1647/// by the enclosing streaming RPC response. Iroh is fail-closed without it.
1648pub async fn connect_moq_reach_with_server_identity(
1649    reach: &[crate::stream_info::Destination],
1650    server_identity: &crate::stream_info::MoqlServerIdentity,
1651) -> Result<MoqReachConnection> {
1652    connect_moq_reach_for_profile(reach, server_identity, native_iroh_required()).await
1653}
1654
1655/// Explicit policy seam. Required mode admits only Iroh destinations.
1656pub async fn connect_moq_reach_for_profile(
1657    reach: &[crate::stream_info::Destination],
1658    server_identity: &crate::stream_info::MoqlServerIdentity,
1659    iroh_required: bool,
1660) -> Result<MoqReachConnection> {
1661    use crate::transport::uds_session::{connect_uds, PLANE_MOQ};
1662    use moq_net::{Client as MoqClient, Origin};
1663
1664    let iroh_required = iroh_required || native_iroh_required();
1665    let client_origin = Origin::random().produce();
1666    let consumer = client_origin.consume();
1667    let moq_client = MoqClient::new().with_consume(client_origin);
1668
1669    // 1. Networked reach (source of truth): dial the first reach we can resolve.
1670    let mut last_err: Option<String> = None;
1671    let mut had_dialable_network_reach = false;
1672    for dest in reach {
1673        let Some(cfg) = reach_to_transport_config(dest) else {
1674            continue;
1675        };
1676        if iroh_required && !matches!(cfg.endpoint, crate::transport::EndpointType::Iroh { .. }) {
1677            continue;
1678        }
1679        had_dialable_network_reach = true;
1680        let dial = match (&cfg.endpoint, global_moq_admission_proof()) {
1681            (crate::transport::EndpointType::Iroh { .. }, Some(proof)) => {
1682                // A relay is an independently operated Iroh server. It may
1683                // never borrow the producer witness attached to the enclosing
1684                // StreamInfo; only a direct destination retains that narrowly
1685                // scoped legacy fallback. QUIC authenticates its own pinned
1686                // transport path and does not require a MoQL witness.
1687                let expected_server = match destination_server_identity(dest, server_identity) {
1688                    Ok(identity) => identity,
1689                    Err(error) => {
1690                        last_err = Some(error.to_string());
1691                        continue;
1692                    }
1693                };
1694                match expected_server {
1695                    None => Err(anyhow!(
1696                        "iroh moql reach lacks a live resolver-verified server witness"
1697                    )),
1698                    Some(expected_server) => {
1699                        // The process-global proof is this client's local accepted
1700                        // identity. The signed StreamInfo supplies the *remote*
1701                        // server witness for this particular dial; never reuse the
1702                        // local announcement's witness as the expected server.
1703                        let mut proof = proof.clone();
1704                        proof.expected_server = expected_server.clone();
1705                        crate::dial::dial_stream_authenticated(&cfg, &proof).await
1706                    }
1707                }
1708            }
1709            (crate::transport::EndpointType::Iroh { .. }, None) => Err(anyhow::anyhow!(
1710                "iroh moql reach requires an accepted-state admission proof"
1711            )),
1712            _ => crate::dial::dial_stream(&cfg).await,
1713        };
1714        match dial {
1715            Ok(stream_session) => match stream_session.connect_moq(&moq_client).await {
1716                Ok(session) => {
1717                    return Ok(MoqReachConnection {
1718                        consumer,
1719                        _session: session,
1720                    });
1721                }
1722                Err(e) => last_err = Some(format!("moq handshake: {e}")),
1723            },
1724            Err(e) => last_err = Some(e.to_string()),
1725        }
1726    }
1727
1728    // A producer-advertised network endpoint is authoritative. In particular,
1729    // an authenticated Iroh rejection must not silently cross into this
1730    // process's local plane: that could subscribe to an unrelated producer.
1731    if iroh_required && !had_dialable_network_reach {
1732        return Err(anyhow!(
1733            "network-iroh-required: no dialable Iroh stream reach; refusing QUIC/local fallback"
1734        ));
1735    }
1736    if had_dialable_network_reach {
1737        return Err(anyhow!(
1738            "all dialable network reaches failed; refusing local moq UDS fallback{}",
1739            last_err
1740                .map(|e| format!(" (last dial error: {e})"))
1741                .unwrap_or_default()
1742        ));
1743    }
1744
1745    // 2. Local UDS fallback (same-host fast path, resolved from LOCAL config).
1746    if let Some(uds) = global_moq_uds_path() {
1747        let session = connect_uds(uds, PLANE_MOQ)
1748            .await
1749            .with_context(|| format!("moq UDS connect {}", uds.display()))?;
1750        let session = moq_client
1751            .connect(session)
1752            .await
1753            .map_err(|e| anyhow!("moq UDS handshake: {e}"))?;
1754        return Ok(MoqReachConnection {
1755            consumer,
1756            _session: session,
1757        });
1758    }
1759
1760    // 3. Fail closed.
1761    Err(anyhow!(
1762        "no dialable reach in StreamInfo and no local moq UDS plane — cannot subscribe to broadcast{}",
1763        last_err
1764            .map(|e| format!(" (last dial error: {e})"))
1765            .unwrap_or_default()
1766    ))
1767}
1768
1769/// Select the server accepted-state witness for exactly one destination.
1770/// Direct legacy entries may use the authenticated enclosing producer witness;
1771/// relays must carry their own current witness because their carrier endpoint
1772/// is not the producer's application identity.
1773fn destination_server_identity<'a>(
1774    destination: &'a crate::stream_info::Destination,
1775    enclosing: &'a crate::stream_info::MoqlServerIdentity,
1776) -> Result<Option<&'a crate::stream_info::MoqlServerIdentity>> {
1777    if destination_identity_is_live(&destination.moql_server_identity) {
1778        return Ok(Some(&destination.moql_server_identity));
1779    }
1780    if destination.role == crate::stream_info::Role::Relay {
1781        anyhow::bail!("relay moql reach lacks a live resolver-verified relay witness");
1782    }
1783    Ok(destination_identity_is_live(enclosing).then_some(enclosing))
1784}
1785
1786fn destination_identity_is_live(identity: &crate::stream_info::MoqlServerIdentity) -> bool {
1787    !identity.did.is_empty()
1788        && identity.epoch != 0
1789        && identity.head_digest.len() == 64
1790        && identity.ed25519.len() == 32
1791        && !identity.ml_dsa65.is_empty()
1792        && identity.expires_at_unix_ms > crate::envelope::current_timestamp()
1793}
1794
1795// ============================================================================
1796// QoS-driven reach selection (#358) — topology, orthogonal to delivery/integrity
1797//
1798// Topology (direct vs relay) is NOT a new QoS integrity axis: the delivery /
1799// ordering / completion / retention contract (`StreamOpt`) stays orthogonal to
1800// where the bytes flow. The selector only REORDERS the reaches the SERVICE
1801// advertised so the preferred topology is tried first; `connect_moq_reach`'s
1802// in-order try-then-fallback loop then provides automatic reachability fallback
1803// (direct → relay, or relay → direct) within the advertised set.
1804//
1805// **Server-authority invariant (enforced here):** selection is a stable reorder
1806// of `advertised` — it never invents a reach, never fabricates a `direct` reach
1807// the service didn't publish, and never drops a reach. So a service that
1808// published a stream relay-ONLY (omitting any direct reach to keep the producer
1809// anonymized) stays relay-only: there is no direct reach to promote, and the
1810// client cannot force one. The client READS qos/reach; it never writes them.
1811// ============================================================================
1812
1813/// Reorder the service-advertised `reach` list by the QoS-preferred topology
1814/// (#358), returning a new list the caller hands to [`connect_moq_reach`].
1815///
1816/// - `Retention::Live` (Pipe / live console, lowest-latency) → **direct-first**:
1817///   a live pipe wants the shortest path; the relay is the fallback only if the
1818///   producer is not directly reachable.
1819/// - retained / resumable / fan-out (Job / Log, `Retention::{Blocks,Seconds}`)
1820///   → **relay-first**: the relay is the natural late-join / retained / fan-out
1821///   surface, and lets a subscriber rendezvous without dialing the producer.
1822///
1823/// The reorder is **stable** (it preserves the service's relative ordering within
1824/// each role), so direct reaches keep their advertised priority (e.g. iroh before
1825/// Quic) and the only change is whether the relay group floats to the front.
1826pub fn select_reach(
1827    advertised: &[crate::stream_info::Destination],
1828    qos: &crate::stream_info::StreamOpt,
1829) -> Vec<crate::stream_info::Destination> {
1830    use crate::stream_info::{Retention, Role};
1831    let relay_first = !matches!(qos.retention, Retention::Live);
1832    let mut ordered: Vec<crate::stream_info::Destination> = Vec::with_capacity(advertised.len());
1833    // Stable partition: pull the preferred role to the front, keep within-role order.
1834    let prefer = if relay_first {
1835        Role::Relay
1836    } else {
1837        Role::Direct
1838    };
1839    ordered.extend(advertised.iter().filter(|d| d.role == prefer).cloned());
1840    ordered.extend(advertised.iter().filter(|d| d.role != prefer).cloned());
1841    ordered
1842}
1843
1844/// Resolve a service-advertised reach into a live moq connection, honouring the
1845/// QoS-preferred topology (#358).
1846///
1847/// Thin composition of [`select_reach`] (QoS reorder, server-authority-safe) and
1848/// [`connect_moq_reach`] (in-order dial with automatic direct↔relay fallback).
1849/// This is the single entry point networked subscribers should use when they
1850/// have the signed `StreamOpt` in hand, so direct-vs-relay routing lives in ONE
1851/// place and the reach the service published is the only thing ever dialed.
1852pub async fn connect_moq_reach_for_qos(
1853    reach: &[crate::stream_info::Destination],
1854    qos: &crate::stream_info::StreamOpt,
1855) -> Result<MoqReachConnection> {
1856    let ordered = select_reach(reach, qos);
1857    connect_moq_reach(&ordered).await
1858}
1859
1860// ============================================================================
1861// moq relay client (#358) — producer-side announce UP to the relay.
1862//
1863// Restores the rendezvous property the ZMQ→moq migration removed: a producing
1864// node that has a configured relay opens a moq link to it and announces its
1865// local origin's broadcasts UP to the relay (`with_origin`), so a subscriber
1866// that dials the relay sees the SAME broadcast by the SAME `broadcastPath`
1867// without ever dialing the producer. Mirrors the event-plane UDS link
1868// ([`connect_event_moq_uds_background`] / [`run_event_client_link`]) but points
1869// at a REMOTE relay via [`crate::dial::dial_stream`] instead of `connect_uds`.
1870//
1871// Relay-blind: the link carries the AEAD-sealed, chained-HMAC frames opaquely
1872// (`Bytes`); the relay holds no `enc_key` / `mac_key` and never decrypts.
1873// ============================================================================
1874
1875/// Base reconnect delay for the producer→relay link; the backoff grows
1876/// exponentially from this up to [`RELAY_RECONNECT_MAX`], with jitter.
1877const RELAY_RECONNECT_BASE: std::time::Duration = std::time::Duration::from_millis(500);
1878/// Cap on the exponential reconnect backoff.
1879const RELAY_RECONNECT_MAX: std::time::Duration = std::time::Duration::from_secs(30);
1880/// After this many consecutive failures, escalate the reconnect log from
1881/// `debug!` to `warn!` so a persistently-unreachable relay is observable.
1882const RELAY_RECONNECT_WARN_AFTER: u32 = 5;
1883
1884/// Fail-closed relay path-integrity gate (#504 item 3) — assert the dial is
1885/// pinned to the explicitly configured carrier endpoint before this node
1886/// announces its origin UP to it (`with_origin`).
1887///
1888/// ## The gap this closes
1889/// [`run_relay_announce_link`] dials the producer-chosen relay and announces this
1890/// node's broadcasts (track names / `broadcastPath`, traffic patterns) UP to it.
1891/// Frames are AEAD-sealed so **content** confidentiality holds regardless, but the
1892/// announce-handshake exposes broadcast **metadata** to whatever endpoint answers.
1893/// moq-net's session handshake exposes **no relay-role / announce-capability**
1894/// negotiation (the setup parameters are opaque `Bytes` and `Client` offers no
1895/// role hook). Relay-role authorization is an upstream configuration/policy
1896/// decision. This function only prevents path substitution by checking the
1897/// configured cert pin or iroh `EndpointId`; it grants no role or identity.
1898///
1899/// ## The check (fail-closed)
1900/// - **iroh**: the connection is bound to the configured carrier `EndpointId`,
1901///   so target/path substitution is rejected. No application identity follows.
1902/// - **QUIC, leaf-pinned** (`accept_cert_hashes` non-empty, with or without
1903///   WebPKI): the dialed peer must present a pinned leaf — accepted.
1904/// - **QUIC, WebPKI-only** (`require_web_pki` with an EMPTY pin set): **rejected.**
1905///   WebPKI proves only "some cert valid for this SNI", so any holder of a
1906///   CA-valid cert for that name could be substituted as the relay and silently
1907///   receive our broadcast announcements. We will not announce our origin UP to
1908///   an endpoint that is not pinned to the configured relay target.
1909/// - **same-host (`Ipc`/`Inproc`/`SystemdFd`)**: not reachable here
1910///   ([`reach_to_transport_config`] yields `None` for them), but rejected
1911///   defensively — they carry no network target pin at this seam.
1912///
1913/// Returns `Err` (and the caller skips `with_origin`) when target/path integrity
1914/// cannot be confirmed, rather than leaking announcements to a substituted
1915/// endpoint. Endpoint equality never authorizes application identity.
1916fn assert_relay_path_pinned(cfg: &crate::transport::TransportConfig) -> Result<()> {
1917    use crate::transport::EndpointType;
1918    match &cfg.endpoint {
1919        // Iroh pins the dial path to the configured EndpointId.
1920        EndpointType::Iroh { .. } => Ok(()),
1921        // QUIC target/path integrity requires a leaf-cert pin.
1922        EndpointType::Quic { auth, .. } => {
1923            if auth.accept_cert_hashes().is_empty() {
1924                Err(anyhow!(
1925                    "relay endpoint is WebPKI-only (no leaf-cert pin): cannot confirm it is the \
1926                     configured relay target — refusing to announce origin UP (fail-closed, #504)"
1927                ))
1928            } else {
1929                Ok(())
1930            }
1931        }
1932        other => Err(anyhow!(
1933            "relay endpoint {other:?} carries no network target pin — \
1934             refusing to announce origin UP (fail-closed, #504)"
1935        )),
1936    }
1937}
1938
1939/// Announce this node's streaming origin UP to the producer-chosen relay (#358).
1940///
1941/// Spawns a background task that dials the relay via [`crate::dial::dial_stream`],
1942/// runs the moq handshake with `with_origin(producer)` (so the producer's
1943/// broadcasts are announced UP to the relay and re-served to its subscribers),
1944/// holds the session open, and reconnects on failure. The task runs for the
1945/// process lifetime.
1946///
1947/// Called by the producing service after its relay reach is configured —
1948/// typically with `global_moq_origin().producer()`. No-op-safe to omit when the
1949/// node has no relay (direct-only deployments).
1950pub fn serve_origin_to_relay_background(
1951    producer: OriginProducer,
1952    relay: crate::stream_info::TransportConfig,
1953    admission_proof: Option<crate::transport::moql_admission::MoqlAdmissionProof>,
1954    relay_server_identity: Option<crate::stream_info::MoqlServerIdentity>,
1955) {
1956    tokio::spawn(async move {
1957        let mut failures: u32 = 0;
1958        loop {
1959            match run_relay_announce_link(
1960                &producer,
1961                &relay,
1962                admission_proof.as_ref(),
1963                relay_server_identity.as_ref(),
1964            )
1965            .await
1966            {
1967                // A link was established and the session closed; reset the backoff.
1968                Ok(()) => failures = 0,
1969                Err(e) => {
1970                    failures = failures.saturating_add(1);
1971                    if failures >= RELAY_RECONNECT_WARN_AFTER {
1972                        tracing::warn!(
1973                            failures,
1974                            "moq relay announce link failing repeatedly: {e}; relay may be unreachable"
1975                        );
1976                    } else {
1977                        tracing::debug!("moq relay announce link ended: {e}; reconnecting");
1978                    }
1979                }
1980            }
1981            // Exponential backoff with equal jitter, capped — de-correlates many
1982            // producers reconnecting to a shared relay (avoids a thundering-herd /
1983            // self-DoS against the federation anchor). `failures == 0` still waits
1984            // ~base, so an instantly-closing session can't spin a tight loop.
1985            let shift = failures.min(6); // 2^6 * 500ms = 32s, clamped by MAX below
1986            let backoff = RELAY_RECONNECT_BASE
1987                .checked_mul(1u32 << shift)
1988                .unwrap_or(RELAY_RECONNECT_MAX)
1989                .min(RELAY_RECONNECT_MAX);
1990            let half = backoff / 2;
1991            let jitter = if half.is_zero() {
1992                std::time::Duration::ZERO
1993            } else {
1994                std::time::Duration::from_nanos(rand::random::<u64>() % half.as_nanos() as u64)
1995            };
1996            tokio::time::sleep(half + jitter).await;
1997        }
1998    });
1999}
2000
2001/// One connect-and-hold cycle of the producer→relay announce link (#358).
2002///
2003/// Dials the relay, runs the moq handshake bidirectionally (`with_origin`), and
2004/// returns when the session closes so the caller can reconnect. The relay
2005/// ingests the announced broadcasts and re-serves them to its subscribers by
2006/// track name — the producer never learns who subscribes, the subscriber never
2007/// dials the producer.
2008///
2009/// Exposed (rather than only via [`serve_origin_to_relay_background`]) so a
2010/// caller that owns its own reconnect/lifecycle — and the rendezvous test — can
2011/// drive a single connect cycle directly.
2012pub async fn run_relay_announce_link(
2013    producer: &OriginProducer,
2014    relay: &crate::stream_info::TransportConfig,
2015    admission_proof: Option<&crate::transport::moql_admission::MoqlAdmissionProof>,
2016    relay_server_identity: Option<&crate::stream_info::MoqlServerIdentity>,
2017) -> Result<()> {
2018    use moq_net::Client as MoqClient;
2019
2020    // Reuse the ONE wire-reach → dial-config resolver so the relay is dialed by
2021    // the same code path (Quic / WebTransport / iroh) every direct reach uses.
2022    let dest = crate::stream_info::Destination {
2023        role: crate::stream_info::Role::Relay,
2024        transport: relay.clone(),
2025        moql_server_identity: relay_server_identity.cloned().unwrap_or_default(),
2026    };
2027    let cfg = reach_to_transport_config(&dest)
2028        .ok_or_else(|| anyhow!("relay reach is not a dialable network transport"))?;
2029
2030    if native_iroh_required()
2031        && !matches!(cfg.endpoint, crate::transport::EndpointType::Iroh { .. })
2032    {
2033        return Err(anyhow!(
2034            "network-iroh-required rejects non-Iroh stream relay"
2035        ));
2036    }
2037
2038    // #504 item 3 — relay-capability gate (fail-closed): do NOT announce this
2039    // node's origin (broadcast track names / `broadcastPath`, traffic patterns)
2040    // UP to an endpoint whose path does not match the configured relay target.
2041    // moq exposes no relay-role handshake; role authorization is upstream, while
2042    // this seam checks only the cert-hash pin / iroh EndpointId. A WebPKI-only
2043    // (unpinned) or identity-less endpoint is refused here — surfaced loudly and
2044    // the announce is skipped — rather than leaking announcements to a
2045    // misconfigured / substituted relay. See [`assert_relay_path_pinned`].
2046    if let Err(e) = assert_relay_path_pinned(&cfg) {
2047        tracing::warn!("moq relay announce gate: {e}");
2048        return Err(e);
2049    }
2050
2051    let stream_session = match (&cfg.endpoint, admission_proof, relay_server_identity) {
2052        (crate::transport::EndpointType::Iroh { .. }, Some(proof), Some(expected_server))
2053            if destination_identity_is_live(expected_server) =>
2054        {
2055            let mut proof = proof.clone();
2056            // A relay is a distinct remote server. Confirm it with its own
2057            // resolver-verified accepted state, never the producer witness.
2058            proof.expected_server = expected_server.clone();
2059            crate::dial::dial_stream_authenticated(&cfg, &proof).await?
2060        }
2061        (crate::transport::EndpointType::Iroh { .. }, Some(_), Some(_)) => {
2062            anyhow::bail!("iroh moql relay lacks a live resolver-verified relay witness")
2063        }
2064        (crate::transport::EndpointType::Iroh { .. }, Some(_), None) => {
2065            anyhow::bail!("iroh moql relay requires a resolver-verified relay witness")
2066        }
2067        (crate::transport::EndpointType::Iroh { .. }, None, _) => {
2068            anyhow::bail!("iroh moql relay requires an accepted-state admission proof")
2069        }
2070        _ => crate::dial::dial_stream(&cfg).await?,
2071    };
2072    // `with_origin` makes the link bidirectional: this node's broadcasts are
2073    // announced UP to the relay; the relay re-serves them to its subscribers.
2074    let moq_client = MoqClient::new().with_origin(producer.clone());
2075    let moq_session = stream_session
2076        .connect_moq(&moq_client)
2077        .await
2078        .map_err(|e| anyhow!("relay moq handshake: {e}"))?;
2079
2080    tracing::info!("moq relay announce link established");
2081    let reason = moq_session.closed().await;
2082    Err(anyhow!("moq relay session closed: {reason:?}"))
2083}
2084
2085/// Networked variant of [`moq_stream_handle_task`]: dial a `/moq`
2086/// `web_transport_quinn` session from the `reach` list instead of the UDS
2087/// plane, then run the identical subscribe + chained-HMAC verify loop (#274).
2088#[allow(clippy::too_many_arguments)]
2089async fn moq_stream_handle_task_networked(
2090    reach: Vec<crate::stream_info::Destination>,
2091    broadcast_path: String,
2092    mac_key: [u8; 32],
2093    enc_key: [u8; 32],
2094    topic: String,
2095    epoch_ratchet: Option<crate::stream_epoch::StreamEpochRatchet>,
2096    server_identity: crate::stream_info::MoqlServerIdentity,
2097    tx: tokio::sync::mpsc::Sender<anyhow::Result<crate::streaming::StreamPayload>>,
2098    cancel: tokio_util::sync::CancellationToken,
2099) {
2100    use crate::streaming::StreamVerifier;
2101    use moq_net::Track;
2102
2103    // Resolve the producer's reach into a live moq connection via the single
2104    // shared resolver (networked-first, local-UDS fallback, fail-closed; #356).
2105    let conn = match connect_moq_reach_with_server_identity(&reach, &server_identity).await {
2106        Ok(c) => c,
2107        Err(e) => {
2108            let _ = tx
2109                .send(Err(anyhow!("moq networked dial failed: {e}")))
2110                .await;
2111            return;
2112        }
2113    };
2114    // Borrow the consumer from `conn`; `conn` (and its session) stays alive for
2115    // the whole subscribe loop.
2116    let client_consumer = &conn.consumer;
2117    let bc = match tokio::time::timeout(
2118        BROADCAST_ANNOUNCE_TIMEOUT,
2119        client_consumer.announced_broadcast(&broadcast_path),
2120    )
2121    .await
2122    {
2123        Ok(Some(bc)) => bc,
2124        Ok(None) => {
2125            let _ = tx
2126                .send(Err(anyhow!("broadcast {broadcast_path} not announced")))
2127                .await;
2128            return;
2129        }
2130        Err(_) => {
2131            let _ = tx
2132                .send(Err(anyhow!(
2133                    "timeout waiting for broadcast {broadcast_path}"
2134                )))
2135                .await;
2136            return;
2137        }
2138    };
2139    let track = match bc.subscribe_track(&Track::new(STREAM_TRACK)) {
2140        Ok(t) => t,
2141        Err(e) => {
2142            let _ = tx.send(Err(anyhow!("subscribe_track: {e}"))).await;
2143            return;
2144        }
2145    };
2146    // #321: AEAD ON for this DH-keyed mesh stream — open sealed Tagged blocks.
2147    let mut verifier = StreamVerifier::new(mac_key, topic.clone()).with_enc_key(enc_key);
2148    if let Some(ratchet) = epoch_ratchet {
2149        verifier = verifier.with_epoch_ratchet(ratchet);
2150    }
2151    // #145: read groups by EXACT sequence (get_group), not arrival-order next_group.
2152    // Each Group is served on its own QUIC uni-stream, so Groups can arrive out of
2153    // order; next_group's monotonic cursor returns the first Group with sequence >=
2154    // its cursor in *arrival* order, so a lower-seq Group that arrives after a higher
2155    // one (e.g. the small terminal / always-retained max_sequence Group) is skipped —
2156    // fatally breaking the ordered, gap-fatal chained HMAC. get_group(seq) waits for
2157    // each exact Group (even out-of-order), guaranteeing in-order, gap-free delivery.
2158    let mut expected_seq = 0u64;
2159    loop {
2160        if cancel.is_cancelled() {
2161            break;
2162        }
2163        let mut group =
2164            match tokio::time::timeout(GROUP_IDLE_TIMEOUT, track.get_group(expected_seq)).await {
2165                Ok(Ok(Some(g))) => g,
2166                Ok(Ok(None)) => break,
2167                Err(_elapsed) => {
2168                    let _ = tx
2169                        .send(Err(anyhow!(
2170                            "stream idle: no group for {}s",
2171                            GROUP_IDLE_TIMEOUT.as_secs()
2172                        )))
2173                        .await;
2174                    break;
2175                }
2176                Ok(Err(e)) => {
2177                    let _ = tx.send(Err(anyhow!("moq next_group: {e}"))).await;
2178                    break;
2179                }
2180            };
2181        expected_seq += 1;
2182        let frame: bytes::Bytes =
2183            match tokio::time::timeout(FRAME_READ_TIMEOUT, group.read_frame()).await {
2184                Ok(Ok(Some(f))) => f,
2185                Ok(Ok(None)) => break,
2186                Ok(Err(e)) => {
2187                    let _ = tx.send(Err(anyhow!("frame read error: {e}"))).await;
2188                    break;
2189                }
2190                Err(_elapsed) => {
2191                    let _ = tx
2192                        .send(Err(anyhow!(
2193                            "frame read timeout after {}s",
2194                            FRAME_READ_TIMEOUT.as_secs()
2195                        )))
2196                        .await;
2197                    break;
2198                }
2199            };
2200        match verify_moq_frame(&mut verifier, &topic, &frame) {
2201            Ok(payloads) => {
2202                for p in payloads {
2203                    let is_terminal = matches!(
2204                        p,
2205                        crate::streaming::StreamPayload::Complete(_)
2206                            | crate::streaming::StreamPayload::Error(_)
2207                    );
2208                    if tx.send(Ok(p)).await.is_err() {
2209                        return;
2210                    }
2211                    if is_terminal {
2212                        return;
2213                    }
2214                }
2215            }
2216            Err(e) => {
2217                let _ = tx.send(Err(e)).await;
2218                return;
2219            }
2220        }
2221    }
2222}
2223
2224/// Consumer-side helper: split a moq Frame payload back into the ZMQ-style
2225/// `[topic, capnp, mac]` frames expected by [`StreamVerifier::verify`], then
2226/// verify and parse it.
2227///
2228/// `topic` is the opaque topic (not the broadcast path) and must match the
2229/// verifier's topic, exactly as the ZMQ frame-0 contract required.
2230pub fn verify_moq_frame(
2231    verifier: &mut StreamVerifier,
2232    topic: &str,
2233    frame: &[u8],
2234) -> Result<Vec<crate::streaming::StreamPayload>> {
2235    if frame.len() < 16 {
2236        anyhow::bail!("moq frame too short: {} bytes", frame.len());
2237    }
2238    let split = frame.len() - 16;
2239    // Zero-copy: pass slices into the received frame (`Bytes` from moq-net) straight
2240    // to the verifier — no per-frame `Vec` allocation of the (potentially large) payload.
2241    verifier.verify_parts(topic.as_bytes(), &frame[..split], &frame[split..])
2242}
2243
2244/// Mesh consumer entry point (#321): verify a moq frame's chained HMAC + AEAD
2245/// (via the `verifier`) AND its per-host provenance signature against a roster.
2246///
2247/// `roster` resolves a signer's anchored ML-DSA-65 key; `is_enrolled` confirms the
2248/// signer is a known mesh peer. Provenance is REQUIRED (fail-closed): a block with
2249/// no/invalid/unknown signer is rejected. Use [`verify_moq_frame`] for the
2250/// non-mesh client path that has no roster.
2251pub fn verify_moq_frame_with_provenance(
2252    verifier: &mut StreamVerifier,
2253    topic: &str,
2254    frame: &[u8],
2255    roster: &dyn crate::envelope::PqTrustStore,
2256    is_enrolled: &dyn Fn(&[u8; 32]) -> bool,
2257) -> Result<Vec<crate::streaming::StreamPayload>> {
2258    if frame.len() < 16 {
2259        anyhow::bail!("moq frame too short: {} bytes", frame.len());
2260    }
2261    let split = frame.len() - 16;
2262    let capnp_data = &frame[..split];
2263
2264    // 1) Chained HMAC + AEAD open (also rejects topic/order/MAC failures).
2265    let payloads = verifier.verify_parts(topic.as_bytes(), capnp_data, &frame[split..])?;
2266
2267    // 2) Per-host provenance, layered on top: parse the block, reconstruct the
2268    //    provenance-cleared signed region, and verify the signature + roster.
2269    let mut slice: &[u8] = capnp_data;
2270    let reader = capnp::serialize::read_message_from_flat_slice(
2271        &mut slice,
2272        capnp::message::ReaderOptions::default(),
2273    )?;
2274    let block = reader.get_root::<crate::streaming_capnp::stream_block::Reader>()?;
2275    let prov = block.get_provenance()?;
2276    let signer_kid = prov.get_signer_kid()?;
2277    let sig = prov.get_sig()?;
2278    let signed_region = crate::stream_provenance::signed_region_from_block(&block)?;
2279    crate::stream_provenance::verify_provenance(
2280        signer_kid,
2281        sig,
2282        &signed_region,
2283        roster,
2284        is_enrolled,
2285    )?;
2286
2287    Ok(payloads)
2288}
2289
2290/// Seal a single Data/Complete/Error/epoch-control payload into an AES-256-GCM `Tagged` payload
2291/// (#321). The 1-byte kind tag is prepended to the plaintext so the consumer can
2292/// restore the original variant. Already-Tagged/other variants pass through
2293/// unchanged (already-Tagged is the E2E notification path).
2294///
2295/// Shares its AAD + kind-tag framing with the cross-target open path
2296/// ([`crate::stream_consumer::open_sealed_payload`]).
2297fn seal_payload(
2298    enc_key: &[u8; 32],
2299    topic: &str,
2300    epoch: u64,
2301    sequence_number: u64,
2302    payload_index: usize,
2303    nonce: Option<[u8; 12]>,
2304    payload: &StreamPayloadData,
2305) -> Result<StreamPayloadData> {
2306    use crate::crypto::event_crypto::{encrypt_event, encrypt_event_with_nonce, EventPrivacy};
2307    use crate::stream_consumer::{
2308        stream_aead_aad, SEALED_KIND_COMPLETE, SEALED_KIND_DATA, SEALED_KIND_EPOCH_COMMIT,
2309        SEALED_KIND_ERROR,
2310    };
2311
2312    let control_bytes = match payload {
2313        StreamPayloadData::EpochCommit(commit) => Some(commit.encode_control_object()),
2314        _ => None,
2315    };
2316    let (kind, body): (u8, &[u8]) = match payload {
2317        StreamPayloadData::Data(d) => (SEALED_KIND_DATA, d),
2318        StreamPayloadData::Complete(d) => (SEALED_KIND_COMPLETE, d),
2319        StreamPayloadData::Error(message) => (SEALED_KIND_ERROR, message.as_bytes()),
2320        StreamPayloadData::EpochCommit(_) => (
2321            SEALED_KIND_EPOCH_COMMIT,
2322            control_bytes
2323                .as_deref()
2324                .ok_or_else(|| anyhow!("stream epoch control encoding missing"))?,
2325        ),
2326        // Leave non-sealed variants untouched.
2327        other => return Ok(other.clone()),
2328    };
2329
2330    let mut plaintext = Vec::with_capacity(1 + body.len());
2331    plaintext.push(kind);
2332    plaintext.extend_from_slice(body);
2333
2334    let aad = stream_aead_aad(topic, epoch, sequence_number, payload_index);
2335    let (tag, ciphertext, nonce, key_commitment) = match nonce {
2336        Some(nonce) => encrypt_event_with_nonce(enc_key, nonce, &aad, &plaintext),
2337        None => encrypt_event(enc_key, &aad, &plaintext, EventPrivacy::ZeroKnowledge),
2338    }
2339    .map_err(|e| anyhow!("stream AEAD seal failed: {e}"))?;
2340
2341    Ok(StreamPayloadData::Tagged {
2342        tag,
2343        payload: ciphertext,
2344        nonce: nonce.to_vec(),
2345        key_commitment: key_commitment.to_vec(),
2346    })
2347}
2348
2349#[cfg(test)]
2350#[allow(clippy::expect_used, clippy::unwrap_used)]
2351mod tests {
2352    use super::*;
2353    use crate::streaming::StreamPayload;
2354    use moq_net::Origin;
2355
2356    fn origin() -> MoqStreamOrigin {
2357        let producer = Origin::random().produce();
2358        let consumer = producer.consume();
2359        MoqStreamOrigin::from_pair(producer, consumer)
2360    }
2361
2362    /// Force a subscription inside the announcement call. This deterministically
2363    /// exercises the gap that another runtime worker can observe during setup.
2364    #[tokio::test]
2365    async fn moq_stream_announcement_has_subscribable_track() -> Result<()> {
2366        use futures::FutureExt;
2367
2368        let origin = origin();
2369        let path = origin.broadcast_path("immediate-subscriber");
2370        let mut subscriber = None;
2371        let (_broadcast, track) = publish_stream_broadcast(&path, |path, broadcast| {
2372            assert!(origin.inner.producer.publish_broadcast(path, broadcast));
2373            let announced = origin
2374                .consumer()
2375                .announced_broadcast(path)
2376                .now_or_never()
2377                .expect("publication must be immediately visible")
2378                .expect("published broadcast must exist");
2379            subscriber = Some(
2380                announced
2381                    .subscribe_track(&Track::new(STREAM_TRACK))
2382                    .expect("announced stream track must already be subscribable"),
2383            );
2384            true
2385        })?;
2386        assert!(subscriber.is_some());
2387        track
2388            .used()
2389            .now_or_never()
2390            .expect("subscriber demand must be visible")?;
2391        Ok(())
2392    }
2393
2394    #[tokio::test]
2395    async fn moq_stream_announcement_denial_is_an_error() {
2396        let error = publish_stream_broadcast("denied/stream", |_, _| false)
2397            .err()
2398            .expect("denied announcement must not return a publisher");
2399        assert_eq!(
2400            error.to_string(),
2401            "create_broadcast denied for denied/stream"
2402        );
2403    }
2404
2405    /// In-process publish → in-process consume over the *same* origin (the data
2406    /// an external moq subscriber sees on the wire), verifying the chained-HMAC.
2407    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
2408    async fn moq_stream_round_trip() -> Result<()> {
2409        let origin = origin();
2410        let (_client_secret, client_pub) = crate::crypto::generate_ephemeral_keypair();
2411        let ctx = StreamContext::from_third_party_interop_dh(&client_pub.to_bytes())?;
2412        let topic = ctx.topic().to_owned();
2413        let mac_key = *ctx.mac_key();
2414        // #321: DH path is AEAD-on; the verifier shares the same enc_key.
2415        let enc_key = *ctx.enc_key().expect("DH ctx has enc_key");
2416
2417        let mut pub_ = origin.publisher(&ctx)?;
2418        pub_.publish_data(b"hello").await?;
2419        pub_.publish_data(b"world").await?;
2420        pub_.complete_ref(b"{}").await?;
2421
2422        // Consume from the shared origin (same bytes a wire subscriber reads).
2423        let path = origin.broadcast_path(&topic);
2424        let bc = tokio::time::timeout(
2425            std::time::Duration::from_secs(5),
2426            origin.consumer().announced_broadcast(path.as_str()),
2427        )
2428        .await?
2429        .ok_or_else(|| anyhow!("broadcast not announced"))?;
2430        let mut track = bc.subscribe_track(&Track::new(STREAM_TRACK))?;
2431
2432        let mut verifier = StreamVerifier::new(mac_key, topic.clone()).with_enc_key(enc_key);
2433        let mut got: Vec<StreamPayload> = Vec::new();
2434        for _ in 0..3 {
2435            let mut group =
2436                tokio::time::timeout(std::time::Duration::from_secs(5), track.next_group())
2437                    .await??
2438                    .ok_or_else(|| anyhow!("next_group None"))?;
2439            let frame = tokio::time::timeout(std::time::Duration::from_secs(5), group.read_frame())
2440                .await??
2441                .ok_or_else(|| anyhow!("read_frame None"))?;
2442            got.extend(verify_moq_frame(&mut verifier, &topic, &frame)?);
2443        }
2444
2445        assert!(matches!(&got[0], StreamPayload::Data(d) if d == b"hello"));
2446        assert!(matches!(&got[1], StreamPayload::Data(d) if d == b"world"));
2447        assert!(matches!(&got[2], StreamPayload::Complete(_)));
2448        Ok(())
2449    }
2450
2451    /// A terminal Complete must preserve groups after the publisher is dropped
2452    /// while an attached consumer is still draining, then expose clean EOF.
2453    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
2454    async fn moq_stream_complete_finishes_track_for_attached_consumer() -> Result<()> {
2455        let origin = origin();
2456        let (_client_secret, client_pub) = crate::crypto::generate_ephemeral_keypair();
2457        let ctx = StreamContext::from_third_party_interop_dh(&client_pub.to_bytes())?;
2458        let topic = ctx.topic().to_owned();
2459        let mac_key = *ctx.mac_key();
2460        let enc_key = *ctx.enc_key().expect("DH ctx has enc_key");
2461
2462        let mut publisher = origin.publisher(&ctx)?;
2463        let broadcast = origin
2464            .consumer()
2465            .announced_broadcast(origin.broadcast_path(&topic).as_str())
2466            .await
2467            .ok_or_else(|| anyhow!("consumer did not see completed broadcast"))?;
2468        let mut track = broadcast.subscribe_track(&Track::new(STREAM_TRACK))?;
2469        publisher.publish_data(b"late-data").await?;
2470        publisher.complete_ref(b"{}").await?;
2471        drop(publisher);
2472
2473        let mut verifier = StreamVerifier::new(mac_key, topic.clone()).with_enc_key(enc_key);
2474        let mut got = Vec::new();
2475        for _ in 0..2 {
2476            let mut group = track
2477                .next_group()
2478                .await?
2479                .ok_or_else(|| anyhow!("completed stream omitted a group"))?;
2480            let frame = group
2481                .read_frame()
2482                .await?
2483                .ok_or_else(|| anyhow!("completed stream group omitted a frame"))?;
2484            got.extend(verify_moq_frame(&mut verifier, &topic, &frame)?);
2485        }
2486        assert!(matches!(&got[0], StreamPayload::Data(data) if data == b"late-data"));
2487        assert!(matches!(&got[1], StreamPayload::Complete(_)));
2488        assert!(
2489            track.next_group().await?.is_none(),
2490            "completed track must EOF cleanly"
2491        );
2492        Ok(())
2493    }
2494
2495    /// An application Error is also a clean terminal track event; dropping
2496    /// the publisher must not turn the authenticated error into transport Drop.
2497    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
2498    async fn moq_stream_error_finishes_track_for_attached_consumer() -> Result<()> {
2499        let origin = origin();
2500        let (_client_secret, client_pub) = crate::crypto::generate_ephemeral_keypair();
2501        let ctx = StreamContext::from_third_party_interop_dh(&client_pub.to_bytes())?;
2502        let topic = ctx.topic().to_owned();
2503        let mac_key = *ctx.mac_key();
2504        let enc_key = *ctx.enc_key().expect("DH ctx has enc_key");
2505
2506        let mut publisher = origin.publisher(&ctx)?;
2507        let broadcast = origin
2508            .consumer()
2509            .announced_broadcast(origin.broadcast_path(&topic).as_str())
2510            .await
2511            .ok_or_else(|| anyhow!("consumer did not see errored broadcast"))?;
2512        let mut track = broadcast.subscribe_track(&Track::new(STREAM_TRACK))?;
2513        publisher.publish_data(b"partial").await?;
2514        publisher.publish_error("expected failure").await?;
2515        drop(publisher);
2516
2517        let mut verifier = StreamVerifier::new(mac_key, topic.clone()).with_enc_key(enc_key);
2518        let mut got = Vec::new();
2519        for _ in 0..2 {
2520            let mut group = track
2521                .next_group()
2522                .await?
2523                .ok_or_else(|| anyhow!("errored stream omitted a group"))?;
2524            let frame = group
2525                .read_frame()
2526                .await?
2527                .ok_or_else(|| anyhow!("errored stream group omitted a frame"))?;
2528            got.extend(verify_moq_frame(&mut verifier, &topic, &frame)?);
2529        }
2530        assert!(matches!(&got[0], StreamPayload::Data(data) if data == b"partial"));
2531        assert!(matches!(&got[1], StreamPayload::Error(message) if message == "expected failure"));
2532        assert!(
2533            track.next_group().await?.is_none(),
2534            "errored track must EOF cleanly"
2535        );
2536        Ok(())
2537    }
2538
2539    /// A publisher owns the origin's retained broadcast entry. Removing only
2540    /// the matching generation bounds finished-stream retention while an
2541    /// already attached consumer keeps its track long enough to drain the
2542    /// authenticated terminal group.
2543    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
2544    async fn moq_stream_finished_broadcast_cleanup_is_exact_and_retains_attached_track(
2545    ) -> Result<()> {
2546        let origin = origin();
2547
2548        let (_complete_secret, complete_pub) = crate::crypto::generate_ephemeral_keypair();
2549        let complete_ctx = StreamContext::from_third_party_interop_dh(&complete_pub.to_bytes())?;
2550        let complete_topic = complete_ctx.topic().to_owned();
2551        let complete_mac_key = *complete_ctx.mac_key();
2552        let complete_enc_key = *complete_ctx.enc_key().expect("DH ctx has enc_key");
2553        let mut complete_publisher = origin.publisher(&complete_ctx)?;
2554        let complete_broadcast = origin
2555            .consumer()
2556            .announced_broadcast(origin.broadcast_path(&complete_topic).as_str())
2557            .await
2558            .ok_or_else(|| anyhow!("complete broadcast was not announced"))?;
2559        let mut complete_track = complete_broadcast.subscribe_track(&Track::new(STREAM_TRACK))?;
2560        complete_publisher
2561            .publish_data(b"retained-complete")
2562            .await?;
2563        complete_publisher.complete_ref(b"{}").await?;
2564        drop(complete_publisher);
2565        assert_eq!(origin.inner.broadcasts.lock().len(), 0);
2566
2567        let mut complete_verifier = StreamVerifier::new(complete_mac_key, complete_topic.clone())
2568            .with_enc_key(complete_enc_key);
2569        let mut complete_payloads = Vec::new();
2570        for _ in 0..2 {
2571            let mut group = complete_track
2572                .next_group()
2573                .await?
2574                .ok_or_else(|| anyhow!("complete group was not retained for attached consumer"))?;
2575            let frame = group
2576                .read_frame()
2577                .await?
2578                .ok_or_else(|| anyhow!("complete frame was not retained"))?;
2579            complete_payloads.extend(verify_moq_frame(
2580                &mut complete_verifier,
2581                &complete_topic,
2582                &frame,
2583            )?);
2584        }
2585        assert!(matches!(
2586            &complete_payloads[0],
2587            StreamPayload::Data(data) if data == b"retained-complete"
2588        ));
2589        assert!(matches!(&complete_payloads[1], StreamPayload::Complete(_)));
2590        assert!(complete_track.next_group().await?.is_none());
2591        drop(complete_track);
2592
2593        let (_error_secret, error_pub) = crate::crypto::generate_ephemeral_keypair();
2594        let error_ctx = StreamContext::from_third_party_interop_dh(&error_pub.to_bytes())?;
2595        let error_topic = error_ctx.topic().to_owned();
2596        let error_mac_key = *error_ctx.mac_key();
2597        let error_enc_key = *error_ctx.enc_key().expect("DH ctx has enc_key");
2598        let mut error_publisher = origin.publisher(&error_ctx)?;
2599        let error_broadcast = origin
2600            .consumer()
2601            .announced_broadcast(origin.broadcast_path(&error_topic).as_str())
2602            .await
2603            .ok_or_else(|| anyhow!("error broadcast was not announced"))?;
2604        let mut error_track = error_broadcast.subscribe_track(&Track::new(STREAM_TRACK))?;
2605        error_publisher.publish_data(b"retained-error").await?;
2606        error_publisher.publish_error("retained failure").await?;
2607        drop(error_publisher);
2608        assert_eq!(origin.inner.broadcasts.lock().len(), 0);
2609
2610        let mut error_verifier =
2611            StreamVerifier::new(error_mac_key, error_topic.clone()).with_enc_key(error_enc_key);
2612        let mut error_payloads = Vec::new();
2613        for _ in 0..2 {
2614            let mut group = error_track
2615                .next_group()
2616                .await?
2617                .ok_or_else(|| anyhow!("error group was not retained for attached consumer"))?;
2618            let frame = group
2619                .read_frame()
2620                .await?
2621                .ok_or_else(|| anyhow!("error frame was not retained"))?;
2622            error_payloads.extend(verify_moq_frame(&mut error_verifier, &error_topic, &frame)?);
2623        }
2624        assert!(matches!(
2625            &error_payloads[0],
2626            StreamPayload::Data(data) if data == b"retained-error"
2627        ));
2628        assert!(matches!(
2629            &error_payloads[1],
2630            StreamPayload::Error(message) if message == "retained failure"
2631        ));
2632        assert!(error_track.next_group().await?.is_none());
2633        drop(error_track);
2634
2635        // A completed stream without a consumer also releases its origin entry.
2636        let (_empty_secret, empty_pub) = crate::crypto::generate_ephemeral_keypair();
2637        let empty_ctx = StreamContext::from_third_party_interop_dh(&empty_pub.to_bytes())?;
2638        let mut empty_publisher = origin.publisher(&empty_ctx)?;
2639        empty_publisher.complete_ref(b"{}").await?;
2640        drop(empty_publisher);
2641        assert_eq!(origin.inner.broadcasts.lock().len(), 0);
2642
2643        // The old publisher's cleanup must not remove a newer same-path entry.
2644        let (_replacement_secret, replacement_pub) = crate::crypto::generate_ephemeral_keypair();
2645        let replacement_ctx =
2646            StreamContext::from_third_party_interop_dh(&replacement_pub.to_bytes())?;
2647        let old_publisher = origin.publisher(&replacement_ctx)?;
2648        let mut new_publisher = origin.publisher(&replacement_ctx)?;
2649        assert_eq!(origin.inner.broadcasts.lock().len(), 1);
2650        drop(old_publisher);
2651        assert_eq!(origin.inner.broadcasts.lock().len(), 1);
2652        new_publisher.complete_ref(b"{}").await?;
2653        drop(new_publisher);
2654        assert_eq!(origin.inner.broadcasts.lock().len(), 0);
2655        Ok(())
2656    }
2657
2658    /// Demand wait must release promptly when the stream is cancelled before
2659    /// any consumer attaches; this covers the no-subscriber continuation path.
2660    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
2661    async fn moq_stream_consumer_wait_observes_cancellation() -> Result<()> {
2662        let origin = origin();
2663        let (_client_secret, client_pub) = crate::crypto::generate_ephemeral_keypair();
2664        let ctx = StreamContext::from_third_party_interop_dh(&client_pub.to_bytes())?;
2665        let publisher = origin.publisher(&ctx)?;
2666        ctx.cancel_token().cancel();
2667        let error = publisher
2668            .wait_for_consumer()
2669            .await
2670            .expect_err("cancelled stream must not wait for a consumer");
2671        assert!(error.to_string().contains("cancelled"));
2672        Ok(())
2673    }
2674
2675    /// #324/N2 measurement contract for the keyed producer used by inter-host
2676    /// activation traffic.
2677    ///
2678    /// This is opt-in because finding the exact boundary cumulatively encrypts
2679    /// and serializes several hundred MiB. The binary search is bounded to 27
2680    /// iterations over [8 KiB, 64 MiB], but the 64 MiB upper bound is never
2681    /// materialized. Every real probe uses a fresh origin so a rejected oversized
2682    /// Group cannot affect the next result.
2683    #[tokio::test]
2684    #[ignore = "bounded 32 MiB MoQ application-frame ceiling measurement"]
2685    async fn measure_keyed_application_frame_ceiling() -> Result<()> {
2686        const DECODE_BF16_BYTES: usize = 8 * 1024;
2687        const PREFILL_BF16_BYTES: usize = 64 * 1024 * 1024;
2688        const RECOMMENDED_ACTIVATION_DATA_BUDGET: usize = 31 * 1024 * 1024;
2689        const MOQ_SERIALIZED_FRAME_CAP: usize = 32 * 1024 * 1024;
2690        const EXPECTED_DECODE_FRAME_BYTES: usize = 8_408;
2691        const EXPECTED_BUDGET_FRAME_BYTES: usize = 32_506_072;
2692        const EXPECTED_KEYED_PAYLOAD_CEILING_BYTES: usize = 33_554_223;
2693
2694        let decode_frame = keyed_application_frame_probe(DECODE_BF16_BYTES)
2695            .await?
2696            .map_err(|error| anyhow!("8 KiB decode probe rejected: {error}"))?;
2697        assert_eq!(decode_frame, EXPECTED_DECODE_FRAME_BYTES);
2698
2699        let budget_frame = keyed_application_frame_probe(RECOMMENDED_ACTIVATION_DATA_BUDGET)
2700            .await?
2701            .map_err(|error| anyhow!("31 MiB safety-budget probe rejected: {error}"))?;
2702        assert_eq!(budget_frame, EXPECTED_BUDGET_FRAME_BYTES);
2703        assert_eq!(MOQ_SERIALIZED_FRAME_CAP - budget_frame, 1_048_360);
2704
2705        // The keyed path is non-compressing: AES-GCM preserves plaintext length,
2706        // then Cap'n Proto and the chained MAC only add bytes. A payload already
2707        // larger than the serialized MoQ cap therefore cannot fit. Keep 64 MiB
2708        // as a numeric rejected upper bound; do not send it through production.
2709        const {
2710            assert!(PREFILL_BF16_BYTES > MOQ_SERIALIZED_FRAME_CAP);
2711        }
2712
2713        assert_negative_control_not_materialized(PREFILL_BF16_BYTES)?;
2714
2715        let mut accepted = DECODE_BF16_BYTES;
2716        let mut rejected = PREFILL_BF16_BYTES;
2717        while rejected - accepted > 1 {
2718            let candidate = accepted + (rejected - accepted) / 2;
2719            match keyed_application_frame_probe(candidate).await? {
2720                Ok(_) => accepted = candidate,
2721                Err(error) if error.contains("frame too large") => rejected = candidate,
2722                Err(error) => anyhow::bail!(
2723                    "payload probe at {candidate} bytes failed for a non-causal reason: {error}"
2724                ),
2725            }
2726        }
2727
2728        let ceiling_frame = keyed_application_frame_probe(accepted)
2729            .await?
2730            .map_err(|error| anyhow!("ceiling probe rejected: {error}"))?;
2731        let first_rejected_error = keyed_application_frame_probe(rejected)
2732            .await?
2733            .expect_err("first payload above the measured ceiling unexpectedly succeeded");
2734
2735        assert_eq!(rejected, accepted + 1);
2736        assert_eq!(accepted, EXPECTED_KEYED_PAYLOAD_CEILING_BYTES);
2737        assert_eq!(ceiling_frame, MOQ_SERIALIZED_FRAME_CAP);
2738        assert!(first_rejected_error.contains("frame too large"));
2739        assert!(PREFILL_BF16_BYTES >= rejected);
2740        Ok(())
2741    }
2742
2743    /// The representative prefill upper bound is a number used by the search,
2744    /// never a payload passed to the keyed production serializer.
2745    #[test]
2746    fn prefill_negative_control_does_not_invoke_allocator() -> Result<()> {
2747        assert_negative_control_not_materialized(64 * 1024 * 1024)
2748    }
2749
2750    fn assert_negative_control_not_materialized(payload_len: usize) -> Result<()> {
2751        // The injected allocator records an attempted materialization without
2752        // allocating. The size guard must return before invoking it.
2753        let mut allocation_attempted = false;
2754        let error = deterministic_bf16_probe_payload_with(payload_len, |_| {
2755            allocation_attempted = true;
2756            Vec::new()
2757        })
2758        .expect_err("negative-control payload unexpectedly reached the allocator");
2759        anyhow::ensure!(!allocation_attempted, "negative control invoked allocator");
2760        anyhow::ensure!(
2761            error.to_string().contains("refusing to materialize"),
2762            "negative-control guard failed for a non-causal reason: {error}"
2763        );
2764        Ok(())
2765    }
2766
2767    async fn keyed_application_frame_probe(
2768        payload_len: usize,
2769    ) -> Result<std::result::Result<usize, String>> {
2770        let payload = deterministic_bf16_probe_payload_with(payload_len, |len| vec![0_u8; len])?;
2771        let origin = origin();
2772        let (_client_secret, client_pub) = crate::crypto::generate_ephemeral_keypair();
2773        let ctx = StreamContext::from_third_party_interop_dh(&client_pub.to_bytes())?;
2774        let topic = ctx.topic().to_owned();
2775        let mut publisher = origin.publisher(&ctx)?;
2776
2777        if let Err(error) = publisher.publish_data(&payload).await {
2778            return Ok(Err(error.to_string()));
2779        }
2780
2781        let path = origin.broadcast_path(&topic);
2782        let broadcast = origin
2783            .consumer()
2784            .announced_broadcast(path.as_str())
2785            .await
2786            .ok_or_else(|| anyhow!("probe broadcast not announced"))?;
2787        let track = broadcast.subscribe_track(&Track::new(STREAM_TRACK))?;
2788        let mut group = track
2789            .get_group(0)
2790            .await?
2791            .ok_or_else(|| anyhow!("probe Group 0 missing"))?;
2792        let frame = group
2793            .read_frame()
2794            .await?
2795            .ok_or_else(|| anyhow!("probe frame missing"))?;
2796        Ok(Ok(frame.len()))
2797    }
2798
2799    fn deterministic_bf16_probe_payload_with(
2800        payload_len: usize,
2801        allocate: impl FnOnce(usize) -> Vec<u8>,
2802    ) -> Result<Vec<u8>> {
2803        // The first binary-search candidate is 32 MiB + 4 KiB. No subsequent
2804        // candidate is larger, so anything above this is a numeric bound only.
2805        const MAX_MATERIALIZED_PROBE_BYTES: usize = 32 * 1024 * 1024 + 4 * 1024;
2806        anyhow::ensure!(
2807            payload_len <= MAX_MATERIALIZED_PROBE_BYTES,
2808            "refusing to materialize {payload_len}-byte negative-control payload"
2809        );
2810
2811        // The producer treats activation bytes as opaque. Alternating bytes
2812        // encode BF16 1.0 on little-endian hosts while keeping the fixture
2813        // deterministic and representative of a BF16 tensor buffer.
2814        let mut payload = allocate(payload_len);
2815        anyhow::ensure!(
2816            payload.len() == payload_len,
2817            "probe allocator returned {} bytes for requested {payload_len}",
2818            payload.len()
2819        );
2820        for value in payload.chunks_exact_mut(2) {
2821            value.copy_from_slice(&[0x80, 0x3f]);
2822        }
2823        Ok(payload)
2824    }
2825
2826    /// #554 identified profile: a standards-compatible MoQT track carries only
2827    /// opaque Object bytes, an authenticated rekey resets the per-epoch sequence
2828    /// and traffic keys, and the relay-visible Group identity remains monotonic.
2829    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
2830    async fn identified_epoch_rekey_keeps_stock_moq_objects_opaque_and_immutable() -> Result<()> {
2831        use crate::crypto::hybrid_kem::{generate_recipient, SuiteId};
2832        use crate::crypto::key_exchange::client_identified_stream_epoch;
2833        use crate::stream_epoch::{
2834            IdentifiedStreamBinding, StreamAcceptedState, StreamCarrierProfile, StreamRouteRole,
2835        };
2836
2837        let binding = IdentifiedStreamBinding::new(
2838            StreamCarrierProfile::StandardPublicRelay,
2839            StreamRouteRole::Relay,
2840            "did:at9p:producer",
2841            "did:at9p:consumer",
2842            StreamAcceptedState {
2843                identity_did: "did:at9p:producer".into(),
2844                digest: [0x31; 64],
2845                epoch: 3,
2846            },
2847            StreamAcceptedState {
2848                identity_did: "did:at9p:consumer".into(),
2849                digest: [0x41; 64],
2850                epoch: 4,
2851            },
2852            "inference.generate",
2853            "infer:model:qwen",
2854            "local/streams/identified",
2855            "did:at9p:producer#mesh-kem",
2856            "urn:hyprstream:stream-client:one-shot",
2857            1,
2858        )?;
2859        let client_keypair = generate_recipient(SuiteId::HyKemX25519MlKem768)?;
2860        let ctx = StreamContext::from_hybrid_identified(
2861            &client_keypair.public().encode(),
2862            binding.clone(),
2863        )?;
2864        let client_ratchet = client_identified_stream_epoch(
2865            &client_keypair,
2866            ctx.kem_ciphertexts()
2867                .expect("hybrid context has ciphertexts"),
2868            binding.clone(),
2869        )?;
2870        let initial_ratchet = client_ratchet.clone();
2871        let topic = ctx.topic().to_owned();
2872        let origin = origin();
2873        let duplicate_ctx = ctx.clone();
2874        assert!(
2875            origin.publisher(&ctx.clone().without_aead()).is_err(),
2876            "identified context accepted an AEAD downgrade before publication"
2877        );
2878        let mut publisher = origin.publisher(&ctx)?;
2879        assert!(
2880            origin.publisher(&duplicate_ctx).is_err(),
2881            "identified context clone created a second epoch-zero publisher"
2882        );
2883        publisher.publish_data(b"epoch-zero-secret").await?;
2884        assert!(
2885            publisher.publish_data(b"must-rekey-first").await.is_err(),
2886            "epoch block bound must fail closed"
2887        );
2888
2889        assert_eq!(publisher.publish_next_epoch()?, 1);
2890        publisher.publish_data(b"epoch-one-secret").await?;
2891
2892        assert_eq!(publisher.publish_next_epoch()?, 2);
2893        let private_error = "private model failure: customer prompt rejected";
2894        publisher.publish_error(private_error).await?;
2895
2896        let path = origin.broadcast_path(&topic);
2897        let bc = tokio::time::timeout(
2898            std::time::Duration::from_secs(5),
2899            origin.consumer().announced_broadcast(path.as_str()),
2900        )
2901        .await?
2902        .ok_or_else(|| anyhow!("broadcast not announced"))?;
2903        let track = bc.subscribe_track(&Track::new(STREAM_TRACK))?;
2904        let mut verifier =
2905            StreamVerifier::new([0; 32], String::new()).with_epoch_ratchet(client_ratchet);
2906
2907        let mut frames = Vec::new();
2908        for group_id in 0..5 {
2909            let mut group =
2910                tokio::time::timeout(std::time::Duration::from_secs(5), track.get_group(group_id))
2911                    .await??
2912                    .ok_or_else(|| anyhow!("identified Group {group_id} missing"))?;
2913            frames.push(
2914                tokio::time::timeout(std::time::Duration::from_secs(5), group.read_frame())
2915                    .await??
2916                    .ok_or_else(|| anyhow!("identified Object {group_id} missing"))?,
2917            );
2918        }
2919        let frame0 = &frames[0];
2920        assert!(
2921            !frame0
2922                .windows(b"epoch-zero-secret".len())
2923                .any(|window| window == b"epoch-zero-secret"),
2924            "stock relay-visible Object leaked plaintext"
2925        );
2926        let first = verify_moq_frame(&mut verifier, &topic, frame0)?;
2927        assert!(matches!(&first[0], StreamPayload::Data(data) if data == b"epoch-zero-secret"));
2928
2929        let control0 = &frames[1];
2930        assert!(
2931            !control0
2932                .windows(b"HYSEPK01".len())
2933                .any(|window| window == b"HYSEPK01")
2934                && !control0
2935                    .windows(32)
2936                    .any(|window| window == binding.binding_hash()),
2937            "relay-visible control Object exposed the epoch-control plaintext"
2938        );
2939        assert!(verify_moq_frame(&mut verifier, &topic, control0)?.is_empty());
2940        let second = verify_moq_frame(&mut verifier, &topic, &frames[2])?;
2941        assert!(matches!(&second[0], StreamPayload::Data(data) if data == b"epoch-one-secret"));
2942
2943        assert!(verify_moq_frame(&mut verifier, &topic, &frames[3])?.is_empty());
2944        assert!(
2945            !frames[4]
2946                .windows(private_error.len())
2947                .any(|window| window == private_error.as_bytes()),
2948            "stock relay-visible Object leaked the private error string"
2949        );
2950        let error = verify_moq_frame(&mut verifier, &topic, &frames[4])?;
2951        assert!(matches!(&error[0], StreamPayload::Error(message) if message == private_error));
2952
2953        // Each negative control first consumes the real epoch-zero Object so
2954        // it has the exact authenticated old-epoch chain state. A subsequent
2955        // successful control+data delivery proves every rejection was causal
2956        // and left verifier state unchanged.
2957        let verifier_after_epoch_zero = || -> Result<StreamVerifier> {
2958            let mut verifier = StreamVerifier::new([0; 32], String::new())
2959                .with_epoch_ratchet(initial_ratchet.clone());
2960            let payloads = verify_moq_frame(&mut verifier, &topic, &frames[0])?;
2961            anyhow::ensure!(matches!(
2962                &payloads[0],
2963                StreamPayload::Data(data) if data == b"epoch-zero-secret"
2964            ));
2965            Ok(verifier)
2966        };
2967
2968        let mut tampered = frames[1].to_vec();
2969        let tampered_index = tampered.len() / 2;
2970        tampered[tampered_index] ^= 0x80;
2971        let mut tamper_verifier = verifier_after_epoch_zero()?;
2972        assert!(verify_moq_frame(&mut tamper_verifier, &topic, &tampered).is_err());
2973        assert!(verify_moq_frame(&mut tamper_verifier, &topic, &frames[1])?.is_empty());
2974        assert!(matches!(
2975            &verify_moq_frame(&mut tamper_verifier, &topic, &frames[2])?[0],
2976            StreamPayload::Data(data) if data == b"epoch-one-secret"
2977        ));
2978
2979        let mut replay_verifier = verifier_after_epoch_zero()?;
2980        assert!(verify_moq_frame(&mut replay_verifier, &topic, &frames[1])?.is_empty());
2981        assert!(verify_moq_frame(&mut replay_verifier, &topic, &frames[1]).is_err());
2982        assert!(matches!(
2983            &verify_moq_frame(&mut replay_verifier, &topic, &frames[2])?[0],
2984            StreamPayload::Data(data) if data == b"epoch-one-secret"
2985        ));
2986
2987        let previous_mac = &frames[0][frames[0].len() - 16..];
2988        let mut skipped = initial_ratchet.prepare_next()?;
2989        skipped.epoch += 1;
2990        let skipped_frame = identified_test_frame(
2991            &initial_ratchet,
2992            &topic,
2993            previous_mac,
2994            1,
2995            &StreamPayloadData::EpochCommit(skipped),
2996        )?;
2997        let mut skip_verifier = verifier_after_epoch_zero()?;
2998        assert!(verify_moq_frame(&mut skip_verifier, &topic, &skipped_frame).is_err());
2999        assert!(verify_moq_frame(&mut skip_verifier, &topic, &frames[1])?.is_empty());
3000
3001        let foreign_binding = IdentifiedStreamBinding::new(
3002            StreamCarrierProfile::StandardPublicRelay,
3003            StreamRouteRole::Relay,
3004            "did:at9p:producer",
3005            "did:at9p:consumer",
3006            StreamAcceptedState {
3007                identity_did: "did:at9p:producer".into(),
3008                digest: [0x31; 64],
3009                epoch: 3,
3010            },
3011            StreamAcceptedState {
3012                identity_did: "did:at9p:consumer".into(),
3013                digest: [0x41; 64],
3014                epoch: 4,
3015            },
3016            "inference.generate",
3017            "infer:model:qwen",
3018            "local/streams/foreign",
3019            "did:at9p:producer#mesh-kem",
3020            "urn:hyprstream:stream-client:one-shot",
3021            1,
3022        )?;
3023        let foreign = crate::stream_epoch::StreamEpochRatchet::from_hybrid_secret(
3024            &[0xA5; 32],
3025            foreign_binding,
3026        )?;
3027        let cross_stream_frame = identified_test_frame(
3028            &initial_ratchet,
3029            &topic,
3030            previous_mac,
3031            1,
3032            &StreamPayloadData::EpochCommit(foreign.prepare_next()?),
3033        )?;
3034        let mut cross_verifier = verifier_after_epoch_zero()?;
3035        assert!(verify_moq_frame(&mut cross_verifier, &topic, &cross_stream_frame).is_err());
3036        assert!(verify_moq_frame(&mut cross_verifier, &topic, &frames[1])?.is_empty());
3037
3038        let clear_payloads = [
3039            StreamPayloadData::Data(b"relay-visible forged data".to_vec()),
3040            StreamPayloadData::Error("relay-visible forged error".into()),
3041            StreamPayloadData::Complete(b"relay-visible forged completion".to_vec()),
3042            StreamPayloadData::Data(initial_ratchet.prepare_next()?.encode_control_object()),
3043        ];
3044        for clear_payload in &clear_payloads {
3045            let forged_clear =
3046                identified_test_frame(&initial_ratchet, &topic, previous_mac, 1, clear_payload)?;
3047            let mut clear_verifier = verifier_after_epoch_zero()?;
3048            assert!(verify_moq_frame(&mut clear_verifier, &topic, &forged_clear).is_err());
3049            assert!(verify_moq_frame(&mut clear_verifier, &topic, &frames[1])?.is_empty());
3050        }
3051
3052        let clear_heartbeat = identified_clear_heartbeat_frame(&initial_ratchet, previous_mac, 1)?;
3053        let mut heartbeat_verifier = verifier_after_epoch_zero()?;
3054        assert!(verify_moq_frame(&mut heartbeat_verifier, &topic, &clear_heartbeat).is_err());
3055        assert!(verify_moq_frame(&mut heartbeat_verifier, &topic, &frames[1])?.is_empty());
3056
3057        // Lost/reordered control and next-epoch data-before-control are the same
3058        // fail-closed condition. The valid control remains acceptable afterward.
3059        let mut reordered_verifier = verifier_after_epoch_zero()?;
3060        assert!(verify_moq_frame(&mut reordered_verifier, &topic, &frames[2]).is_err());
3061        assert!(verify_moq_frame(&mut reordered_verifier, &topic, &frames[1])?.is_empty());
3062        assert!(matches!(
3063            &verify_moq_frame(&mut reordered_verifier, &topic, &frames[2])?[0],
3064            StreamPayload::Data(data) if data == b"epoch-one-secret"
3065        ));
3066
3067        for pair in frames.windows(2) {
3068            assert_ne!(pair[0], pair[1]);
3069        }
3070        Ok(())
3071    }
3072
3073    fn identified_test_frame(
3074        ratchet: &crate::stream_epoch::StreamEpochRatchet,
3075        topic: &str,
3076        previous_mac: &[u8],
3077        sequence_number: u64,
3078        payload: &StreamPayloadData,
3079    ) -> Result<Vec<u8>> {
3080        let keys = ratchet.current_keys();
3081        let nonce = keys.producer_to_consumer.nonce(
3082            sequence_number
3083                .checked_mul(1 << 16)
3084                .ok_or_else(|| anyhow!("test stream payload nonce counter exhausted"))?,
3085        );
3086        let payload = if matches!(payload, StreamPayloadData::EpochCommit(_)) {
3087            seal_payload(
3088                &keys.producer_to_consumer.enc_key,
3089                topic,
3090                ratchet.epoch(),
3091                sequence_number,
3092                0,
3093                Some(nonce),
3094                payload,
3095            )?
3096        } else {
3097            payload.clone()
3098        };
3099        let capnp = crate::streaming::encode_stream_block(
3100            previous_mac,
3101            sequence_number,
3102            ratchet.epoch(),
3103            &[payload],
3104        )?;
3105        let mac = crate::crypto::keyed_mac_truncated_parts(
3106            &keys.producer_to_consumer.mac_key,
3107            &[previous_mac, &capnp],
3108        );
3109        let mut frame = capnp;
3110        frame.extend_from_slice(&mac);
3111        Ok(frame)
3112    }
3113
3114    fn identified_clear_heartbeat_frame(
3115        ratchet: &crate::stream_epoch::StreamEpochRatchet,
3116        previous_mac: &[u8],
3117        sequence_number: u64,
3118    ) -> Result<Vec<u8>> {
3119        let mut msg = capnp::message::Builder::new_default();
3120        {
3121            let mut block = msg.init_root::<crate::streaming_capnp::stream_block::Builder>();
3122            block.set_prev_mac(previous_mac);
3123            block.set_sequence_number(sequence_number);
3124            block.set_epoch(ratchet.epoch());
3125            block.init_payloads(1).get(0).set_heartbeat(());
3126        }
3127        let mut capnp = Vec::new();
3128        capnp::serialize::write_message(&mut capnp, &msg)?;
3129        let keys = ratchet.current_keys();
3130        let mac = crate::crypto::keyed_mac_truncated_parts(
3131            &keys.producer_to_consumer.mac_key,
3132            &[previous_mac, &capnp],
3133        );
3134        capnp.extend_from_slice(&mac);
3135        Ok(capnp)
3136    }
3137
3138    /// `AnyStreamPublisher` round-trip: publish via the type alias and verify
3139    /// the same bytes arrive on the moq consumer side.
3140    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
3141    async fn any_stream_publisher_moq_round_trip() -> Result<()> {
3142        let origin = origin();
3143        let (_client_secret, client_pub) = crate::crypto::generate_ephemeral_keypair();
3144        let ctx = StreamContext::from_third_party_interop_dh(&client_pub.to_bytes())?;
3145        let topic = ctx.topic().to_owned();
3146        let mac_key = *ctx.mac_key();
3147        // #321: DH path is AEAD-on; the verifier shares the same enc_key.
3148        let enc_key = *ctx.enc_key().expect("DH ctx has enc_key");
3149
3150        let mut any_pub: AnyStreamPublisher = origin.publisher(&ctx)?;
3151        any_pub.publish_data(b"ping").await?;
3152        any_pub.complete_ref(b"{}").await?;
3153
3154        // Consume and verify
3155        let path = origin.broadcast_path(&topic);
3156        let bc = tokio::time::timeout(
3157            std::time::Duration::from_secs(5),
3158            origin.consumer().announced_broadcast(path.as_str()),
3159        )
3160        .await?
3161        .ok_or_else(|| anyhow!("broadcast not announced"))?;
3162        let mut track = bc.subscribe_track(&Track::new(STREAM_TRACK))?;
3163        let mut verifier = StreamVerifier::new(mac_key, topic.clone()).with_enc_key(enc_key);
3164        let mut got: Vec<StreamPayload> = Vec::new();
3165        for _ in 0..2 {
3166            let mut group =
3167                tokio::time::timeout(std::time::Duration::from_secs(5), track.next_group())
3168                    .await??
3169                    .ok_or_else(|| anyhow!("next_group None"))?;
3170            let frame = tokio::time::timeout(std::time::Duration::from_secs(5), group.read_frame())
3171                .await??
3172                .ok_or_else(|| anyhow!("read_frame None"))?;
3173            got.extend(verify_moq_frame(&mut verifier, &topic, &frame)?);
3174        }
3175        assert!(matches!(&got[0], StreamPayload::Data(d) if d == b"ping"));
3176        assert!(matches!(&got[1], StreamPayload::Complete(_)));
3177        Ok(())
3178    }
3179
3180    /// #320: the iroh reach codec round-trips carrier address (nodeId) + relay.
3181    /// An empty-relay reach remains stream-dialable through iroh discovery;
3182    /// application RPC dialing separately requires explicit reach and proof.
3183    #[test]
3184    fn iroh_reach_dial_wire_roundtrip() {
3185        use crate::transport::{EndpointType, TransportConfig};
3186        let node_id = [0x42u8; 32];
3187        let dial = TransportConfig::iroh(
3188            node_id,
3189            Vec::new(),
3190            Some("https://relay.example".to_owned()),
3191        );
3192        let wire = dial_transport_to_wire(&dial).expect("iroh dial → wire");
3193        match &wire {
3194            crate::stream_info::TransportConfig::Iroh(i) => {
3195                assert_eq!(i.node_id, node_id);
3196                assert_eq!(i.relay_url, "https://relay.example");
3197                assert_eq!(i.alpn, "hyprstream-rpc/1");
3198            }
3199            other => panic!("expected wire Iroh, got {other:?}"),
3200        }
3201        let back = wire_transport_to_dial(&wire).expect("iroh wire → dial");
3202        match back.endpoint {
3203            EndpointType::Iroh {
3204                node_id: n,
3205                relay_url,
3206                direct_addrs,
3207            } => {
3208                assert_eq!(n, node_id);
3209                assert_eq!(relay_url.as_deref(), Some("https://relay.example"));
3210                assert!(
3211                    direct_addrs.is_empty(),
3212                    "wire iroh reach never carries direct addrs"
3213                );
3214            }
3215            other => panic!("expected dial Iroh, got {other:?}"),
3216        }
3217    }
3218
3219    /// #320: same-host endpoints (Inproc/Ipc) are NEVER advertised on the wire —
3220    /// `dial_transport_to_wire` returns None (a co-located-only service yields an
3221    /// empty published reach list).
3222    #[test]
3223    fn same_host_endpoints_never_wire_advertised() {
3224        use crate::transport::TransportConfig;
3225        assert!(
3226            dial_transport_to_wire(&TransportConfig::inproc("hyprstream/inference-x")).is_none()
3227        );
3228        assert!(dial_transport_to_wire(&TransportConfig::ipc("/tmp/x.sock")).is_none());
3229    }
3230
3231    /// #320: a wire iroh reach with an empty relayUrl preserves its carrier
3232    /// address. RPC `dial()` rejects it without explicit reachability and an
3233    /// independently resolved response key; `dial_stream()` may use discovery.
3234    #[test]
3235    fn iroh_reach_empty_relay_decodes_but_not_dialable() {
3236        use crate::stream_info::{IrohReach, TransportConfig as ReachTransport};
3237        let wire = ReachTransport::Iroh(IrohReach {
3238            node_id: [9u8; 32],
3239            alpn: "moql".to_owned(),
3240            relay_url: String::new(),
3241        });
3242        let dial = wire_transport_to_dial(&wire).expect("decodes");
3243        // No relay + no direct addrs ⇒ application RPC dial() fails fast.
3244        let signer = crate::signer::LocalSigner::new(crate::crypto::SigningKey::generate(
3245            &mut rand::rngs::OsRng,
3246        ));
3247        assert!(
3248            crate::dial::dial(&dial, signer, None, None).is_err(),
3249            "RPC dial must require explicit reachability and response proof"
3250        );
3251    }
3252
3253    /// #275: a StreamInfo carrying a dialable Quic reach must be classified as
3254    /// dialable, so `networked()` routes to the producer's networked reach
3255    /// (`dial_stream`) rather than this process's local moq UDS plane.
3256    #[test]
3257    fn quic_reach_is_dialable() {
3258        use crate::stream_info::{Destination, QuicReach, Role, TransportConfig as ReachTransport};
3259        let reach = Destination {
3260            role: Role::Direct,
3261            transport: ReachTransport::Quic(QuicReach {
3262                addr: "127.0.0.1:4433".to_owned(),
3263                server_name: "localhost".to_owned(),
3264                cert_hashes: vec![vec![0u8; 32]],
3265            }),
3266            moql_server_identity: Default::default(),
3267        };
3268        assert!(
3269            reach_to_transport_config(&reach).is_some(),
3270            "a Quic reach must resolve to a dialable TransportConfig (selects the \
3271             networked dial_stream path, not the local UDS)"
3272        );
3273    }
3274
3275    /// #357: an advertised iroh reach (carrying only the producer's node_id) must
3276    /// resolve to a dialable `EndpointType::Iroh { node_id, .. }` — the dial-by-
3277    /// node_id-alone path `dial_stream` opens over the `moql` ALPN (pkarr / n0 DNS
3278    /// discovery resolves the addresses on the shared client endpoint). This is
3279    /// the encode→resolve round-trip for the iroh-direct reach.
3280    #[test]
3281    fn iroh_reach_resolves_to_node_id() {
3282        use crate::stream_info::{Destination, IrohReach, Role, TransportConfig as ReachTransport};
3283        use crate::transport::EndpointType;
3284
3285        let node_id = [0x7u8; 32];
3286        // This is exactly the Destination `ProducerReachConfig::reach()` emits for iroh.
3287        let reach = Destination {
3288            role: Role::Direct,
3289            transport: ReachTransport::Iroh(IrohReach {
3290                node_id,
3291                alpn: "moql".to_owned(),
3292                relay_url: String::new(),
3293            }),
3294            moql_server_identity: Default::default(),
3295        };
3296        assert_eq!(
3297            reach.role,
3298            Role::Direct,
3299            "iroh reach is a direct producer reach"
3300        );
3301
3302        let cfg = reach_to_transport_config(&reach)
3303            .expect("an iroh reach with a node_id must resolve to a dialable TransportConfig");
3304        match cfg.endpoint {
3305            EndpointType::Iroh {
3306                node_id: got,
3307                direct_addrs,
3308                relay_url,
3309            } => {
3310                assert_eq!(
3311                    got, node_id,
3312                    "resolved node_id must round-trip the advertised one"
3313                );
3314                // S2 advertises node_id alone; discovery supplies reachability.
3315                assert!(
3316                    direct_addrs.is_empty(),
3317                    "S2 iroh reach carries no direct addrs (pkarr)"
3318                );
3319                assert!(
3320                    relay_url.is_none(),
3321                    "S2 iroh reach carries no relay URL (pkarr)"
3322                );
3323            }
3324            other => panic!("iroh reach must resolve to EndpointType::Iroh, got {other:?}"),
3325        }
3326    }
3327
3328    /// #357: an iroh-only reach list must be classified as dialable, so a
3329    /// native peer routes to the producer's iroh reach rather than falling
3330    /// through to the local UDS plane (the source-of-truth ordering S1 established).
3331    #[test]
3332    fn iroh_reach_is_dialable() {
3333        use crate::stream_info::{Destination, IrohReach, Role, TransportConfig as ReachTransport};
3334        let reach = [Destination {
3335            role: Role::Direct,
3336            transport: ReachTransport::Iroh(IrohReach {
3337                node_id: [0xABu8; 32],
3338                alpn: "moql".to_owned(),
3339                relay_url: String::new(),
3340            }),
3341            moql_server_identity: Default::default(),
3342        }];
3343        assert!(
3344            reach.iter().any(|d| reach_to_transport_config(d).is_some()),
3345            "an iroh reach must resolve to a dialable TransportConfig"
3346        );
3347    }
3348
3349    /// A dialable advertised Iroh destination remains authoritative even when
3350    /// its admission check rejects it. Falling through to this process's UDS
3351    /// plane would turn that rejection into an unauthenticated local fallback.
3352    #[tokio::test]
3353    async fn rejected_iroh_reach_never_falls_back_to_local_uds() -> Result<()> {
3354        use crate::stream_info::{Destination, IrohReach, Role, TransportConfig as ReachTransport};
3355
3356        let reach = [Destination {
3357            role: Role::Direct,
3358            transport: ReachTransport::Iroh(IrohReach {
3359                node_id: [0xCDu8; 32],
3360                alpn: "moql".to_owned(),
3361                relay_url: String::new(),
3362            }),
3363            moql_server_identity: Default::default(),
3364        }];
3365
3366        // No process-global admission proof means this fails before any network
3367        // I/O. The resolver must return that network-path rejection, even if a
3368        // test or daemon has installed a local UDS path in this process.
3369        let err = match connect_moq_reach(&reach).await {
3370            Ok(_) => panic!("Iroh reach without admission proof must be rejected"),
3371            Err(err) => err,
3372        };
3373        let message = err.to_string();
3374        assert!(
3375            message
3376                .contains("all dialable network reaches failed; refusing local moq UDS fallback"),
3377            "dialable Iroh rejection must not fall back to local UDS: {message}"
3378        );
3379        assert!(
3380            message.contains("iroh moql reach"),
3381            "network admission rejection must be retained: {message}"
3382        );
3383        Ok(())
3384    }
3385
3386    /// #275: the consumer dials the producer's networked reach even when this
3387    /// process also serves its own local moq UDS plane. Regression for the TUI
3388    /// timeout: the local UDS must NOT shadow a present reach (it is this
3389    /// process's plane, not the producer's).
3390    ///
3391    /// We assert the branch selection deterministically. With a dialable reach
3392    /// present we set the local UDS path to a socket that does NOT exist: the
3393    /// **UDS branch** would fail in milliseconds with a connect error naming that
3394    /// path, whereas the **networked branch** dials QUIC (which, to a closed
3395    /// loopback port, keeps retrying past a short deadline). So: a UDS-path error
3396    /// before the deadline ⇒ the pre-fix bug (UDS preferred — FAIL); reaching the
3397    /// deadline still trying ⇒ the networked dial was taken (PASS). A networked
3398    /// dial error is also an acceptable PASS (reach was dialed).
3399    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
3400    async fn networked_prefers_reach_over_local_uds() -> Result<()> {
3401        use crate::stream_info::{Destination, QuicReach, Role, TransportConfig as ReachTransport};
3402
3403        // Pretend this process has a local moq UDS plane (the TUI daemon does, to
3404        // serve its PTY stdout). The pre-fix code short-circuited onto this path
3405        // and ignored the reach; the fix must dial the reach instead. The path is
3406        // distinctive so a UDS connect error is unambiguously identifiable.
3407        let uds_marker = "/nonexistent/hyprstream-275-uds-marker.sock";
3408        let _ = GLOBAL_MOQ_UDS_PATH.set(PathBuf::from(uds_marker));
3409
3410        // A dialable Quic reach to a closed loopback port.
3411        let reach = vec![Destination {
3412            role: Role::Direct,
3413            transport: ReachTransport::Quic(QuicReach {
3414                addr: "127.0.0.1:1".to_owned(),
3415                server_name: "localhost".to_owned(),
3416                cert_hashes: vec![[0xABu8; 32].to_vec()],
3417            }),
3418            moql_server_identity: Default::default(),
3419        }];
3420
3421        let qos = crate::stream_info::StreamOpt::default();
3422        let mut handle = MoqStreamHandle::networked(
3423            reach,
3424            &qos,
3425            "local/streams/test/deadbeef".to_owned(),
3426            [0u8; 32],
3427            [0u8; 32],
3428            "deadbeef".repeat(8),
3429            Default::default(),
3430        );
3431
3432        match tokio::time::timeout(std::time::Duration::from_secs(3), handle.recv_next()).await {
3433            // Still dialing QUIC at the deadline — the networked branch was taken.
3434            Err(_elapsed) => Ok(()),
3435            // An early error: it must be a *networked* dial failure, NOT a UDS
3436            // connect to our marker path (which would prove the bug).
3437            Ok(res) => {
3438                let err = res.expect_err("dial to a closed port must not yield a payload");
3439                let msg = err.to_string();
3440                assert!(
3441                    !msg.contains(uds_marker),
3442                    "consumer connected to the local UDS plane instead of dialing the \
3443                     producer's reach (#275 regression): {msg}"
3444                );
3445                assert!(
3446                    msg.contains("networked dial"),
3447                    "expected a networked dial failure (reach was dialed), got: {msg}"
3448                );
3449                Ok(())
3450            }
3451        }
3452    }
3453
3454    #[test]
3455    fn authorize_signer_gate() {
3456        let producer = Origin::random().produce();
3457        let consumer = producer.consume();
3458        let gated = MoqStreamOrigin::builder(producer, consumer)
3459            .with_authorize_signer(|pk| pk[0] == 1)
3460            .build();
3461        assert!(gated.authorize_signer(&[1u8; 32]));
3462        assert!(!gated.authorize_signer(&[2u8; 32]));
3463        // No gate -> accept all.
3464        assert!(origin().authorize_signer(&[9u8; 32]));
3465    }
3466
3467    // ── #358 relay reach / selection unit tests ─────────────────────────────
3468
3469    use crate::stream_info::{
3470        Destination, IrohReach, Job, Log, Pipe, QuicReach, Role, StreamOpt, StreamOptPreset,
3471        TransportConfig as ReachTransport,
3472    };
3473
3474    fn direct_iroh(b: u8) -> Destination {
3475        Destination {
3476            role: Role::Direct,
3477            transport: ReachTransport::Iroh(IrohReach {
3478                node_id: [b; 32],
3479                alpn: String::new(),
3480                relay_url: String::new(),
3481            }),
3482            moql_server_identity: Default::default(),
3483        }
3484    }
3485    fn relay_quic(addr: &str) -> Destination {
3486        Destination {
3487            role: Role::Relay,
3488            transport: ReachTransport::Quic(QuicReach {
3489                addr: addr.to_owned(),
3490                server_name: "relay".to_owned(),
3491                cert_hashes: vec![vec![0u8; 32]],
3492            }),
3493            moql_server_identity: Default::default(),
3494        }
3495    }
3496
3497    #[tokio::test]
3498    async fn required_stream_reach_rejects_empty_and_browser_only_without_dial() {
3499        let identity = crate::stream_info::MoqlServerIdentity::default();
3500        for reach in [
3501            vec![],
3502            vec![crate::stream_info::Destination {
3503                role: crate::stream_info::Role::Direct,
3504                transport: crate::stream_info::TransportConfig::Quic(
3505                    crate::stream_info::QuicReach {
3506                        addr: "127.0.0.1:9".into(),
3507                        server_name: "localhost".into(),
3508                        cert_hashes: vec![],
3509                    },
3510                ),
3511                moql_server_identity: Default::default(),
3512            }],
3513        ] {
3514            let result = tokio::time::timeout(
3515                std::time::Duration::from_millis(200),
3516                connect_moq_reach_for_profile(&reach, &identity, true),
3517            )
3518            .await
3519            .unwrap();
3520            assert!(result
3521                .err()
3522                .unwrap()
3523                .to_string()
3524                .contains("no dialable Iroh stream reach"));
3525        }
3526    }
3527
3528    fn accepted_server_identity(did: &str, marker: u8) -> crate::stream_info::MoqlServerIdentity {
3529        crate::stream_info::MoqlServerIdentity {
3530            did: did.to_owned(),
3531            epoch: 1,
3532            head_digest: vec![marker; 64],
3533            expires_at_unix_ms: crate::envelope::current_timestamp() + 60_000,
3534            ed25519: [marker; 32],
3535            ml_dsa65: vec![marker; 1952],
3536        }
3537    }
3538
3539    /// A relay is a separate server, even when it is advertised beside a
3540    /// producer's direct reach. The wire destination must retain the relay's
3541    /// resolver witness; substituting the producer witness here would confirm
3542    /// the wrong remote peer during an authenticated Iroh dial.
3543    #[test]
3544    fn relay_destination_uses_its_own_accepted_state_witness() {
3545        let producer = accepted_server_identity("did:at9p:producer", 0x11);
3546        let relay = accepted_server_identity("did:at9p:relay", 0x22);
3547        let relay_transport = ReachTransport::Iroh(IrohReach {
3548            node_id: [0x33; 32],
3549            alpn: "moql".to_owned(),
3550            relay_url: String::new(),
3551        });
3552        let cfg = ProducerReachConfig {
3553            moql_server_identity: Some(producer.clone()),
3554            relay_moql_server_identity: Some(relay.clone()),
3555            iroh_node_id: Some([0x44; 32]),
3556            quic_reach: None,
3557            relay: Some(relay_transport.clone()),
3558        };
3559
3560        let reach = cfg.reach();
3561        let direct = reach
3562            .iter()
3563            .find(|destination| destination.role == Role::Direct)
3564            .expect("producer direct reach");
3565        let relay_destination = reach
3566            .iter()
3567            .find(|destination| destination.role == Role::Relay)
3568            .expect("relay reach");
3569        assert_eq!(direct.moql_server_identity, producer);
3570        assert_eq!(relay_destination.moql_server_identity, relay);
3571        assert_ne!(
3572            relay_destination.moql_server_identity, direct.moql_server_identity,
3573            "the relay must never inherit the producer accepted-state witness"
3574        );
3575
3576        let independent = cfg.reach_with_relay(RelayChoice::Override(RelayTarget::new(
3577            relay_transport,
3578            relay.clone(),
3579        )));
3580        let independent_relay = independent
3581            .iter()
3582            .find(|destination| destination.role == Role::Relay)
3583            .expect("independent relay reach");
3584        assert_eq!(independent_relay.moql_server_identity, relay);
3585    }
3586
3587    /// A live enclosing producer witness authenticates only a direct legacy
3588    /// Iroh destination. An independently operated Iroh relay with no own
3589    /// witness is rejected before its authenticated carrier dial.
3590    #[test]
3591    fn relay_without_witness_cannot_borrow_live_producer_authority() {
3592        let producer = accepted_server_identity("did:at9p:producer", 0x11);
3593        let relay = Destination {
3594            role: Role::Relay,
3595            transport: ReachTransport::Iroh(IrohReach {
3596                node_id: [0x22; 32],
3597                alpn: "moql".to_owned(),
3598                relay_url: String::new(),
3599            }),
3600            moql_server_identity: Default::default(),
3601        };
3602        let error = destination_server_identity(&relay, &producer)
3603            .expect_err("relay without its own resolver witness must reject");
3604        assert!(error.to_string().contains("relay witness"));
3605
3606        let direct = Destination {
3607            role: Role::Direct,
3608            transport: ReachTransport::Quic(QuicReach {
3609                addr: "127.0.0.1:4434".to_owned(),
3610                server_name: "producer".to_owned(),
3611                cert_hashes: vec![vec![0u8; 32]],
3612            }),
3613            moql_server_identity: Default::default(),
3614        };
3615        assert_eq!(
3616            destination_server_identity(&direct, &producer)
3617                .expect("direct legacy fallback remains valid")
3618                .expect("live producer witness"),
3619            &producer,
3620        );
3621    }
3622
3623    // ── #504 item 3: configured relay target/path pin gate ──────────────────
3624
3625    /// An iroh relay dial is pinned to the configured EndpointId, so path
3626    /// substitution is rejected without treating equality as identity authority.
3627    #[test]
3628    fn relay_gate_accepts_iroh_target_pinned_without_granting_identity() {
3629        // Equality or inequality with any application key cannot change this
3630        // path-only result: both values are opaque carrier targets here.
3631        for node_id in [[7u8; 32], [19u8; 32]] {
3632            let cfg = crate::transport::TransportConfig::iroh(node_id, Vec::new(), None);
3633            assert!(assert_relay_path_pinned(&cfg).is_ok());
3634        }
3635    }
3636
3637    /// A leaf-cert-pinned QUIC relay has a confirmed target path — accepted.
3638    #[test]
3639    fn relay_gate_accepts_quic_leaf_pinned() {
3640        let addr = "127.0.0.1:7777".parse().expect("addr");
3641        let cfg = crate::transport::TransportConfig::quic_pinned(addr, "relay", [3u8; 32]);
3642        assert!(assert_relay_path_pinned(&cfg).is_ok());
3643    }
3644
3645    /// A WebPKI-only QUIC relay (no leaf pin) proves only "some cert valid for
3646    /// this SNI" — any CA-valid cert holder could be substituted, so the gate
3647    /// REJECTS it fail-closed and the origin is never announced UP.
3648    #[test]
3649    fn relay_gate_rejects_quic_webpki_only() {
3650        let addr = "127.0.0.1:7777".parse().expect("addr");
3651        let cfg = crate::transport::TransportConfig::quic(addr, "relay");
3652        let err = assert_relay_path_pinned(&cfg).expect_err("WebPKI-only relay must be rejected");
3653        assert!(
3654            err.to_string().contains("WebPKI-only"),
3655            "expected a WebPKI-only rejection, got: {err}"
3656        );
3657    }
3658
3659    /// A WebPKI+leaf-pin QUIC relay (defence in depth) is still leaf-pinned —
3660    /// accepted.
3661    #[test]
3662    fn relay_gate_accepts_quic_webpki_plus_pin() {
3663        let addr = "127.0.0.1:7777".parse().expect("addr");
3664        let auth = crate::transport::QuicServerAuth::web_pki_pinned(vec![[5u8; 32]]).expect("auth");
3665        let cfg = crate::transport::TransportConfig::quic_with_auth(addr, "relay", auth);
3666        assert!(assert_relay_path_pinned(&cfg).is_ok());
3667    }
3668
3669    /// A same-host endpoint carries no network target pin — rejected (defensive;
3670    /// `reach_to_transport_config` already yields None for these).
3671    #[test]
3672    fn relay_gate_rejects_unpinned_same_host() {
3673        let cfg = crate::transport::TransportConfig::inproc("hyprstream/x");
3674        assert!(assert_relay_path_pinned(&cfg).is_err());
3675    }
3676
3677    /// A [`ProducerReachConfig`] with a server-global relay advertises a
3678    /// `Role::Relay` Destination — populating the existing schema, no new field.
3679    ///
3680    /// No `OnceLock` dance (#384): the config is per-instance, so this is
3681    /// deterministic regardless of process-global state or test ordering.
3682    #[test]
3683    fn producer_reach_advertises_relay_when_configured() {
3684        let relay = ReachTransport::Quic(QuicReach {
3685            addr: "10.0.0.9:4433".to_owned(),
3686            server_name: "pds".to_owned(),
3687            cert_hashes: vec![vec![1u8; 32]],
3688        });
3689        let cfg = ProducerReachConfig {
3690            relay: Some(relay.clone()),
3691            ..Default::default()
3692        };
3693        let reach = cfg.reach();
3694        assert!(
3695            reach
3696                .iter()
3697                .any(|d| d.role == Role::Relay && d.transport == relay),
3698            "ProducerReachConfig::reach must advertise the configured Role::Relay reach"
3699        );
3700    }
3701
3702    /// #384 regression: two DIFFERENT reach contexts in ONE process produce
3703    /// DIFFERENT reach — a relay-only-anonymized stream X coexists with a
3704    /// direct stream Y. This is the heterogeneous-anonymization property the
3705    /// `OnceLock` singletons structurally prevented (first-write-wins clobber).
3706    #[test]
3707    fn heterogeneous_reach_in_one_process() {
3708        let relay_x = ReachTransport::Quic(QuicReach {
3709            addr: "10.0.0.9:4433".to_owned(),
3710            server_name: "relay-x".to_owned(),
3711            cert_hashes: vec![vec![7u8; 32]],
3712        });
3713        // A server with BOTH a direct (iroh) reach and a server-global relay.
3714        let cfg = ProducerReachConfig {
3715            moql_server_identity: None,
3716            relay_moql_server_identity: None,
3717            iroh_node_id: Some([3u8; 32]),
3718            quic_reach: None,
3719            relay: Some(relay_x.clone()),
3720        };
3721
3722        // Stream Y: server default → direct (iroh) THEN relay, direct-first order.
3723        let reach_y = cfg.reach();
3724        assert_eq!(
3725            reach_y[0].role,
3726            Role::Direct,
3727            "Y must advertise its direct reach first"
3728        );
3729        assert!(
3730            reach_y.iter().any(|d| d.role == Role::Relay),
3731            "Y must also advertise the server-global relay"
3732        );
3733
3734        // Stream X: relay-ONLY (anonymized) override → NO direct reach, only the
3735        // per-stream relay — same process, same config instance, different result.
3736        let relay_only = ReachTransport::Quic(QuicReach {
3737            addr: "10.0.0.50:4433".to_owned(),
3738            server_name: "relay-anon".to_owned(),
3739            cert_hashes: vec![vec![9u8; 32]],
3740        });
3741        let reach_x = cfg.reach_with_relay(RelayChoice::Only(RelayTarget::new(
3742            relay_only.clone(),
3743            accepted_server_identity("did:at9p:relay-anon", 0x23),
3744        )));
3745        assert_eq!(
3746            reach_x.len(),
3747            1,
3748            "relay-only stream X must omit all direct reaches"
3749        );
3750        assert_eq!(reach_x[0].role, Role::Relay, "X is relay-only (anonymized)");
3751        assert_eq!(
3752            reach_x[0].transport, relay_only,
3753            "X uses its per-stream relay override"
3754        );
3755        assert!(
3756            !reach_x.iter().any(|d| d.role == Role::Direct),
3757            "X must NOT leak a direct reach (server authority / anonymization)"
3758        );
3759
3760        // The two streams genuinely differ in the same process — the property the
3761        // singletons precluded.
3762        assert_ne!(
3763            reach_x, reach_y,
3764            "X (relay-only) and Y (direct+relay) must differ"
3765        );
3766    }
3767
3768    /// Per-stream relay `Override` swaps the relay but KEEPS the direct reaches
3769    /// (per-tenant isolation without anonymization), preserving direct-first order.
3770    #[test]
3771    fn per_stream_relay_override_keeps_direct() {
3772        let server_relay = ReachTransport::Quic(QuicReach {
3773            addr: "10.0.0.1:4433".to_owned(),
3774            server_name: "server".to_owned(),
3775            cert_hashes: vec![vec![1u8; 32]],
3776        });
3777        let tenant_relay = ReachTransport::Quic(QuicReach {
3778            addr: "10.0.0.2:4433".to_owned(),
3779            server_name: "tenant".to_owned(),
3780            cert_hashes: vec![vec![2u8; 32]],
3781        });
3782        let cfg = ProducerReachConfig {
3783            moql_server_identity: None,
3784            relay_moql_server_identity: None,
3785            iroh_node_id: Some([4u8; 32]),
3786            quic_reach: None,
3787            relay: Some(server_relay.clone()),
3788        };
3789        let reach = cfg.reach_with_relay(RelayChoice::Override(RelayTarget::new(
3790            tenant_relay.clone(),
3791            accepted_server_identity("did:at9p:tenant-relay", 0x24),
3792        )));
3793        assert_eq!(
3794            reach[0].role,
3795            Role::Direct,
3796            "override keeps the direct reach, listed first"
3797        );
3798        let relay_d = reach
3799            .iter()
3800            .find(|d| d.role == Role::Relay)
3801            .expect("relay advertised");
3802        assert_eq!(
3803            relay_d.transport, tenant_relay,
3804            "per-stream override replaces the server relay"
3805        );
3806    }
3807
3808    /// QoS-driven selection: live pipes prefer DIRECT, retained/fan-out prefer RELAY.
3809    #[test]
3810    fn select_reach_orders_by_qos_topology() {
3811        let advertised = vec![direct_iroh(1), relay_quic("10.0.0.1:4433"), direct_iroh(2)];
3812
3813        // Pipe (Retention::Live) → direct-first; within-role order preserved.
3814        let pipe = Pipe::stream_opt();
3815        let ordered = select_reach(&advertised, &pipe);
3816        assert_eq!(
3817            ordered[0].role,
3818            Role::Direct,
3819            "live pipe must try direct first"
3820        );
3821        assert_eq!(
3822            ordered[2].role,
3823            Role::Relay,
3824            "relay falls to the back for a live pipe"
3825        );
3826        assert_eq!(
3827            ordered[0],
3828            direct_iroh(1),
3829            "within-role advertised order preserved"
3830        );
3831        assert_eq!(ordered[1], direct_iroh(2));
3832
3833        // Job (retained/resumable) → relay-first.
3834        let job = Job::stream_opt();
3835        let ordered = select_reach(&advertised, &job);
3836        assert_eq!(
3837            ordered[0].role,
3838            Role::Relay,
3839            "retained job must try relay first"
3840        );
3841
3842        // Log (retained) → relay-first.
3843        let log = Log::stream_opt();
3844        assert_eq!(select_reach(&advertised, &log)[0].role, Role::Relay);
3845    }
3846
3847    /// Server authority: selection NEVER invents, fabricates `direct`, or drops a
3848    /// reach. A relay-ONLY advertisement (anonymized stream) stays relay-only even
3849    /// for a live-pipe QoS that would *prefer* direct — there is nothing to promote.
3850    #[test]
3851    fn select_reach_preserves_server_authority() {
3852        let relay_only = vec![relay_quic("10.0.0.1:4433")];
3853
3854        // Even with default (Live → direct-preferred) qos, no direct reach appears.
3855        let ordered = select_reach(&relay_only, &StreamOpt::default());
3856        assert_eq!(ordered.len(), 1, "selection must not add or drop reaches");
3857        assert_eq!(
3858            ordered[0].role,
3859            Role::Relay,
3860            "a relay-only stream stays relay-only"
3861        );
3862        assert!(
3863            !ordered.iter().any(|d| d.role == Role::Direct),
3864            "the client must NOT fabricate a direct reach the service didn't advertise"
3865        );
3866
3867        // It is also a pure permutation: same multiset in, same multiset out.
3868        let advertised = vec![direct_iroh(1), relay_quic("a:1"), direct_iroh(2)];
3869        let mut a = advertised.clone();
3870        let mut b = select_reach(&advertised, &Job::stream_opt());
3871        a.sort_by_key(|d| (d.role == Role::Relay, format!("{d:?}")));
3872        b.sort_by_key(|d| (d.role == Role::Relay, format!("{d:?}")));
3873        assert_eq!(
3874            a, b,
3875            "selection must be a permutation of the advertised reach"
3876        );
3877    }
3878
3879    /// `relay_reach_from_decoded` round-trips a DID-decoded transport into the
3880    /// wire-reach form advertised as the relay — the shared codec, no drift.
3881    #[test]
3882    fn relay_reach_from_decoded_round_trips() {
3883        // iroh decoded config → iroh wire reach carrying the same node_id.
3884        let cfg = crate::transport::TransportConfig::iroh([0x5u8; 32], Vec::new(), None);
3885        match relay_reach_from_decoded(&cfg) {
3886            Some(ReachTransport::Iroh(i)) => assert_eq!(i.node_id, [0x5u8; 32]),
3887            other => panic!("expected iroh wire reach, got {other:?}"),
3888        }
3889        // Same-host transports are never relay endpoints.
3890        assert!(
3891            relay_reach_from_decoded(&crate::transport::TransportConfig::ipc("/tmp/x.sock"))
3892                .is_none(),
3893            "a same-host ipc transport is not a network-routable relay"
3894        );
3895    }
3896
3897    // ── #321 AEAD seal/open ────────────────────────────────────────────────
3898
3899    #[test]
3900    fn aead_seal_open_roundtrip() {
3901        let enc_key = [0x42u8; 32];
3902        let topic = "deadbeef";
3903        let epoch = 7u64;
3904        for payload in [
3905            StreamPayloadData::Data(b"hello tokens".to_vec()),
3906            StreamPayloadData::Complete(b"{\"done\":true}".to_vec()),
3907        ] {
3908            let sealed = seal_payload(&enc_key, topic, epoch, 0, 0, None, &payload).unwrap();
3909            let StreamPayloadData::Tagged {
3910                tag,
3911                payload: ct,
3912                nonce,
3913                key_commitment,
3914            } = &sealed
3915            else {
3916                panic!("seal must produce a Tagged payload");
3917            };
3918            let opened = crate::stream_consumer::open_sealed_payload(
3919                &enc_key,
3920                topic,
3921                epoch,
3922                0,
3923                0,
3924                tag,
3925                ct,
3926                nonce,
3927                key_commitment,
3928            )
3929            .unwrap();
3930            match (&payload, &opened) {
3931                (StreamPayloadData::Data(a), StreamPayload::Data(b))
3932                | (StreamPayloadData::Complete(a), StreamPayload::Complete(b)) => {
3933                    assert_eq!(a, b);
3934                }
3935                _ => panic!("opened variant must match sealed variant"),
3936            }
3937        }
3938    }
3939
3940    #[test]
3941    fn aead_open_rejects_wrong_key_and_tamper() {
3942        let enc_key = [0x42u8; 32];
3943        let topic = "t";
3944        let epoch = 1u64;
3945        let sealed = seal_payload(
3946            &enc_key,
3947            topic,
3948            epoch,
3949            0,
3950            0,
3951            None,
3952            &StreamPayloadData::Data(b"secret".to_vec()),
3953        )
3954        .unwrap();
3955        let StreamPayloadData::Tagged {
3956            tag,
3957            payload: ct,
3958            nonce,
3959            key_commitment,
3960        } = &sealed
3961        else {
3962            panic!("expected Tagged");
3963        };
3964
3965        // Wrong key.
3966        let wrong = [0x99u8; 32];
3967        assert!(crate::stream_consumer::open_sealed_payload(
3968            &wrong,
3969            topic,
3970            epoch,
3971            0,
3972            0,
3973            tag,
3974            ct,
3975            nonce,
3976            key_commitment
3977        )
3978        .is_err());
3979
3980        // Wrong epoch (AAD mismatch) — anti-replay across epochs.
3981        assert!(crate::stream_consumer::open_sealed_payload(
3982            &enc_key,
3983            topic,
3984            2,
3985            0,
3986            0,
3987            tag,
3988            ct,
3989            nonce,
3990            key_commitment
3991        )
3992        .is_err());
3993
3994        // Tampered ciphertext.
3995        let mut bad_ct = ct.clone();
3996        if let Some(b) = bad_ct.first_mut() {
3997            *b ^= 0xFF;
3998        }
3999        assert!(crate::stream_consumer::open_sealed_payload(
4000            &enc_key,
4001            topic,
4002            epoch,
4003            0,
4004            0,
4005            tag,
4006            &bad_ct,
4007            nonce,
4008            key_commitment
4009        )
4010        .is_err());
4011    }
4012
4013    // ── #321 provenance over a published block ─────────────────────────────
4014
4015    /// Publish a block with provenance ON, then verify HMAC + AEAD + provenance
4016    /// against a roster; assert wrong/unknown signers are rejected.
4017    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
4018    async fn provenance_publish_verify_and_reject() -> Result<()> {
4019        use crate::envelope::KeyedPqTrustStore;
4020        use crate::stream_provenance::ProvenanceSigner;
4021        use ed25519_dalek::SigningKey;
4022
4023        let origin = origin();
4024        let (_cs, client_pub) = crate::crypto::generate_ephemeral_keypair();
4025        let ctx = StreamContext::from_third_party_interop_dh(&client_pub.to_bytes())?;
4026        let topic = ctx.topic().to_owned();
4027        let mac_key = *ctx.mac_key();
4028        let enc_key = *ctx.enc_key().expect("DH ctx has enc_key");
4029
4030        let host_ed = SigningKey::from_bytes(&[5u8; 32]);
4031        let signer = ProvenanceSigner::from_ed25519(host_ed.clone());
4032        let kid = signer.signer_kid();
4033
4034        let mut pub_ = origin.publisher_with_provenance(&ctx, Some(signer))?;
4035        pub_.publish_data(b"hi").await?;
4036        pub_.complete_ref(b"{}").await?;
4037
4038        // Drain the two frames from the shared origin.
4039        let path = origin.broadcast_path(&topic);
4040        let bc = tokio::time::timeout(
4041            std::time::Duration::from_secs(5),
4042            origin.consumer().announced_broadcast(path.as_str()),
4043        )
4044        .await?
4045        .ok_or_else(|| anyhow!("broadcast not announced"))?;
4046        let mut track = bc.subscribe_track(&Track::new(STREAM_TRACK))?;
4047        let mut frames: Vec<bytes::Bytes> = Vec::new();
4048        for _ in 0..2 {
4049            let mut group =
4050                tokio::time::timeout(std::time::Duration::from_secs(5), track.next_group())
4051                    .await??
4052                    .ok_or_else(|| anyhow!("next_group None"))?;
4053            let frame = tokio::time::timeout(std::time::Duration::from_secs(5), group.read_frame())
4054                .await??
4055                .ok_or_else(|| anyhow!("read_frame None"))?;
4056            frames.push(frame);
4057        }
4058
4059        // Roster anchoring the host's mesh ML-DSA key + enrolled-set closure.
4060        use ml_dsa::Keypair;
4061        let mut roster = KeyedPqTrustStore::new();
4062        roster.bind(
4063            kid,
4064            &crate::node_identity::derive_mesh_mldsa_key(&host_ed).verifying_key(),
4065        );
4066        let enrolled = |k: &[u8; 32]| *k == kid;
4067
4068        // Valid: verify HMAC + AEAD + provenance.
4069        let mut v = StreamVerifier::new(mac_key, topic.clone()).with_enc_key(enc_key);
4070        let got = verify_moq_frame_with_provenance(&mut v, &topic, &frames[0], &roster, &enrolled)?;
4071        assert!(matches!(&got[0], StreamPayload::Data(d) if d == b"hi"));
4072
4073        // Unknown signer: empty roster / not enrolled → reject (re-verify frame 0
4074        // with a fresh verifier so the HMAC chain restarts at the same block).
4075        let empty = KeyedPqTrustStore::new();
4076        let none_enrolled = |_: &[u8; 32]| false;
4077        let mut v2 = StreamVerifier::new(mac_key, topic.clone()).with_enc_key(enc_key);
4078        assert!(verify_moq_frame_with_provenance(
4079            &mut v2,
4080            &topic,
4081            &frames[0],
4082            &empty,
4083            &none_enrolled
4084        )
4085        .is_err());
4086        Ok(())
4087    }
4088}