Skip to main content

hyprstream_rpc/transport/
quinn_transport.rs

1//! Quinn WebTransport RPC plane — moq M1 (#151).
2//!
3//! A second backend for the transport-generic RPC core (see
4//! [`super::rpc_session`]), proving the RPC plane is transport-pluggable: the
5//! exact same Cap'n Proto bidi wire protocol, DoS bounds, graceful-drain, and
6//! error-envelope semantics run over quinn's [`web_transport_quinn::Session`]
7//! instead of iroh's.
8//!
9//! - [`QuinnRpcServer`] — accepts WebTransport sessions on a quinn endpoint and
10//!   runs [`serve_rpc_connection`] per session.
11//! - [`QuinnTransport`] — client transport wrapping
12//!   [`SessionRpcTransport<web_transport_quinn::Session>`].
13//!
14//! Unlike the iroh substrate (which terminates raw QUIC bidi streams under a
15//! custom ALPN), web-transport-quinn speaks the full WebTransport handshake
16//! (HTTP/3 CONNECT, ALPN `h3`). The wire framing *inside* each bidi stream is
17//! identical, so the generic core is reused unchanged.
18
19use std::sync::Arc;
20use std::time::Duration;
21
22#[cfg(test)]
23use anyhow::Context;
24use anyhow::{anyhow, bail, Result};
25use async_trait::async_trait;
26use ed25519_dalek::SigningKey;
27use tokio::sync::Semaphore;
28use tokio_util::sync::CancellationToken;
29
30use crate::transport::rpc_session::{
31    serve_rpc_connection, IrohRequestProcessor, RpcPendingStream, RpcPublishStub,
32    SessionRpcTransport, DEFAULT_STREAM_LIMIT,
33};
34use crate::transport_traits::Transport;
35
36/// A WebTransport bidi stream carrying a 9P2000.L session, erased to a byte
37/// stream. The H1b `/9p` arm hands one of these to the injected
38/// [`NinePWtHandler`]; the handler runs the transport-agnostic
39/// `Translator::serve_connection` core over it (the same core H1a's WebSocket
40/// pump feeds). Blanket-implemented for any `AsyncRead + AsyncWrite` byte stream
41/// (a joined WT send/recv pair).
42pub trait NinePWtStream:
43    tokio::io::AsyncRead + tokio::io::AsyncWrite + Send + Unpin + 'static
44{
45}
46impl<T: tokio::io::AsyncRead + tokio::io::AsyncWrite + Send + Unpin + 'static> NinePWtStream for T {}
47
48/// Serves one 9P session over a WebTransport bidi stream (H1b / #765).
49///
50/// This is the injection seam that keeps the transport crate free of the 9P
51/// core: the concrete impl lives in the `hyprstream` crate (it owns the 9P
52/// `Translator`, the Subject-scoped export mount, and the mount-ticket
53/// validator), and is registered here via [`QuinnRpcServer::with_ninep_handler`]
54/// or the process-global [`set_global_ninep_handler`] — mirroring how the moq
55/// consumer is threaded onto the same endpoint. The mount ticket is validated
56/// at `Tattach.uname` inside the handler (the cert-pinned session carries no URL
57/// query), so this trait exposes only the raw byte stream.
58#[async_trait]
59pub trait NinePWtHandler: Send + Sync {
60    /// Drive the 9P session on `stream` to completion (returns on EOF, the peer
61    /// resetting the stream, or a fatal 9P framing error). The handler owns
62    /// session teardown.
63    async fn serve(&self, stream: Box<dyn NinePWtStream>);
64}
65
66/// Process-global 9P WebTransport handler, populated by the `hyprstream` crate
67/// at server startup (where `ServerState` — hence the export mount + ticket
68/// validator — is available). The per-service `QuinnRpcServer` build site lives
69/// in `hyprstream-service`, which cannot depend on `hyprstream`; a global here
70/// is the same seam the moq origin uses to cross that boundary. First write
71/// wins; later writes are ignored.
72static GLOBAL_NINEP_HANDLER: std::sync::OnceLock<Arc<dyn NinePWtHandler>> =
73    std::sync::OnceLock::new();
74
75/// Register the process-global 9P WebTransport handler (idempotent, first-wins).
76/// Returns `true` if this call installed it, `false` if one was already set.
77pub fn set_global_ninep_handler(handler: Arc<dyn NinePWtHandler>) -> bool {
78    GLOBAL_NINEP_HANDLER.set(handler).is_ok()
79}
80
81/// The process-global 9P WebTransport handler, if one has been registered.
82pub fn global_ninep_handler() -> Option<Arc<dyn NinePWtHandler>> {
83    GLOBAL_NINEP_HANDLER.get().cloned()
84}
85
86/// Process-global `/moq` CONNECT authenticator (#1153), populated by the
87/// `hyprstream` crate at server startup — where the authoritative
88/// subject→tenant provisioning map (PolicyManager) is available — so the
89/// `hyprstream-service` spawner (which cannot depend on `hyprstream`) can
90/// pick it up at construction via [`global_moq_connect_authz`]. Same seam
91/// pattern as [`set_global_ninep_handler`]. First write wins.
92static GLOBAL_MOQ_CONNECT_AUTHZ: std::sync::OnceLock<
93    crate::transport::moq_connect_auth::MoqConnectAuthz,
94> = std::sync::OnceLock::new();
95
96/// Register the process-global `/moq` CONNECT authenticator (idempotent,
97/// first-wins). The `hyprstream` crate calls this at startup with an
98/// [`MoqConnectAuthz`] built over its PolicyManager subject→tenant map.
99pub fn set_global_moq_connect_authz(
100    authz: crate::transport::moq_connect_auth::MoqConnectAuthz,
101) -> bool {
102    GLOBAL_MOQ_CONNECT_AUTHZ.set(authz).is_ok()
103}
104
105/// The process-global `/moq` CONNECT authenticator, if one has been
106/// registered.
107pub fn global_moq_connect_authz() -> Option<crate::transport::moq_connect_auth::MoqConnectAuthz> {
108    GLOBAL_MOQ_CONNECT_AUTHZ.get().cloned()
109}
110
111/// One-shot guard so the "no authenticator on a served `/moq` plane" warning
112/// (#1153/F1) fires once per process rather than per-CONNECT.
113static MOQ_NO_AUTHZ_WARNED: std::sync::Once = std::sync::Once::new();
114
115/// A quinn-backed WebTransport server for the RPC plane.
116///
117/// Accepts WebTransport sessions and spawns [`serve_rpc_connection`] for each.
118/// Caps concurrent streams *server-wide* via a single shared [`Semaphore`] (DoS
119/// bound) passed into every connection, matching the iroh handler's
120/// shared-semaphore drain. [`QuinnRpcServer::shutdown`] cancels the accept loop
121/// and then drains all in-flight streams before returning, so detached
122/// `handle_stream` tasks finish writing their responses rather than being
123/// abandoned mid-flight.
124pub struct QuinnRpcServer {
125    server: web_transport_quinn::Server,
126    processor: Arc<dyn IrohRequestProcessor>,
127    signing_key: SigningKey,
128    /// Server-wide concurrent-stream cap. Shared across all connections; one
129    /// permit is held per in-flight bidi stream. `shutdown` drains it via
130    /// `acquire_many` to wait for every in-flight stream to complete.
131    stream_limit: Arc<Semaphore>,
132    stream_limit_capacity: u32,
133    /// Cap on concurrent accepted connections (#162). One permit per live
134    /// connection; connections beyond the cap are rejected, not queued.
135    connection_limit: Arc<Semaphore>,
136    /// Per-stream request-read timeout (#159 slowloris bound).
137    read_timeout: Duration,
138    /// Accept-boundary carrier classification. Production is always
139    /// WebTransport; unit tests may use inproc for raw transport-only probes.
140    carrier: crate::transport::carrier::CarrierContext,
141    /// Optional moq streaming-plane consumer (#274). When set, sessions whose
142    /// WebTransport CONNECT URL path is [`crate::dial::MOQ_PATH`] are handed to
143    /// `moq_net::Server::accept` instead of the RPC core. `None` = RPC only.
144    moq_consumer: Option<moq_net::OriginConsumer>,
145    /// Optional moq RELAY origin (#358). When set, the `/moq` plane runs in
146    /// *relay* (bidirectional) mode: `moq_net::Server::with_origin` ingests a
147    /// connected producer's announced broadcasts into this origin AND re-serves
148    /// them to subscribers by track name — so a publisher and a subscriber
149    /// rendezvous through this node without either dialing the other. Takes
150    /// precedence over [`Self::moq_consumer`] (serve-only). The relay carries the
151    /// AEAD-sealed, chained-HMAC frames opaquely and holds no stream keys.
152    moq_relay_origin: Option<moq_net::OriginProducer>,
153    /// #276 subscribe-authz + per-tenant announce-scoping config for the `/moq`
154    /// plane. Defaults to "off" (open subscribe preserved).
155    moq_authz: crate::transport::iroh_moq::MoqAuthzConfig,
156    /// #1153 CONNECT-time authenticator for the `/moq` plane. When set, every
157    /// `/moq` CONNECT must present a verifiable bearer JWT and resolve to a
158    /// tenant from the *verified* subject, or the CONNECT is refused
159    /// (fail-closed) before any stream is established. `None` = the `/moq`
160    /// plane is single-tenant/open (the deployment has not opted into the
161    /// shared-endpoint boundary).
162    moq_connect_authz: Option<crate::transport::moq_connect_auth::MoqConnectAuthz>,
163    /// Optional 9P export handler (H1b / #765). When set, sessions whose
164    /// WebTransport CONNECT URL path is [`crate::dial::NINEP_PATH`] are handed to
165    /// it instead of the RPC core. Defaults to [`global_ninep_handler`] at
166    /// construction; `None` = 9P plane off (unknown-path sessions fall through to
167    /// the RPC core, matching pre-H1b behaviour).
168    ninep_handler: Option<Arc<dyn NinePWtHandler>>,
169    shutdown: CancellationToken,
170}
171
172impl QuinnRpcServer {
173    /// Build a server from a quinn endpoint configured for WebTransport (ALPN
174    /// `h3`). Use [`web_transport_quinn::ServerBuilder`] to construct one.
175    pub fn new<P: IrohRequestProcessor>(
176        server: web_transport_quinn::Server,
177        processor: P,
178        signing_key: SigningKey,
179    ) -> Self {
180        Self::with_capacity(
181            server,
182            Arc::new(processor),
183            signing_key,
184            DEFAULT_STREAM_LIMIT,
185        )
186    }
187
188    /// Build a server with an explicit server-wide concurrent-stream cap.
189    pub fn with_capacity(
190        server: web_transport_quinn::Server,
191        processor: Arc<dyn IrohRequestProcessor>,
192        signing_key: SigningKey,
193        stream_limit: usize,
194    ) -> Self {
195        Self {
196            server,
197            processor,
198            signing_key,
199            stream_limit: Arc::new(Semaphore::new(stream_limit)),
200            stream_limit_capacity: u32::try_from(stream_limit).unwrap_or(u32::MAX),
201            connection_limit: Arc::new(Semaphore::new(
202                super::rpc_session::DEFAULT_CONNECTION_LIMIT,
203            )),
204            read_timeout: super::rpc_session::REQUEST_READ_TIMEOUT,
205            carrier: crate::transport::carrier::CarrierContext::web_transport(),
206            moq_consumer: None,
207            moq_relay_origin: None,
208            moq_authz: crate::transport::iroh_moq::MoqAuthzConfig::default(),
209            // #1153/F3: do NOT snapshot `global_moq_connect_authz()` here.
210            // Reading the OnceLock once at construction makes startup ordering
211            // a silent security property: a server built before the `hyprstream`
212            // crate registers the authenticator runs open forever with no error.
213            // The accept loop resolves the effective authenticator per-CONNECT
214            // (`builder override OR global`), so registration order is no longer
215            // load-bearing.
216            moq_connect_authz: None,
217            // Pick up the process-global 9P handler if the `hyprstream` crate
218            // registered one; a builder call can still override it.
219            ninep_handler: global_ninep_handler(),
220            shutdown: CancellationToken::new(),
221        }
222    }
223
224    /// Serve the moq streaming plane on the same endpoint (#274).
225    ///
226    /// Sessions whose WebTransport CONNECT URL path is [`crate::dial::MOQ_PATH`]
227    /// are handed to `moq_net::Server::accept` against `consumer`; all other
228    /// paths route to the RPC core. Mirrors
229    /// [`crate::transport::iroh_moq::IrohMoqProtocolHandler`], which serves moq
230    /// over a per-connection iroh ALPN — here the multiplex is by URL path.
231    pub fn with_moq_consumer(mut self, consumer: moq_net::OriginConsumer) -> Self {
232        self.moq_consumer = Some(consumer);
233        self
234    }
235
236    #[cfg(test)]
237    pub(crate) fn with_test_trusted_carrier(mut self) -> Self {
238        self.carrier = crate::transport::carrier::CarrierContext::inproc();
239        self
240    }
241
242    /// Run the `/moq` plane as a RELAY (bidirectional) over `origin` (#358).
243    ///
244    /// In relay mode each `/moq` session is served via
245    /// `moq_net::Server::with_origin`, so a connected producer's announced
246    /// broadcasts are ingested into `origin` and re-served to every subscriber by
247    /// track name. This is the rendezvous endpoint a producer advertises as a
248    /// `Role::Relay` reach: a publisher links UP to it
249    /// ([`crate::moq_stream::serve_origin_to_relay_background`]) and a subscriber
250    /// dials it for the SAME `broadcastPath` — neither dials the other.
251    ///
252    /// The relay is **blind by construction**: frames are AEAD-sealed and
253    /// chained-HMAC'd at the source; this node holds no `enc_key` / `mac_key` and
254    /// forwards opaque `Bytes`. Takes precedence over [`Self::with_moq_consumer`].
255    pub fn with_moq_relay(mut self, origin: moq_net::OriginProducer) -> Self {
256        self.moq_relay_origin = Some(origin);
257        self
258    }
259
260    /// Install the #276 subscribe-authz + per-tenant announce-scoping config for
261    /// the `/moq` plane.
262    ///
263    /// **Identity caveat (documented seam):** the WebTransport `/moq` CONNECT is
264    /// *not* mutually authenticated at the TLS layer. Per-tenant announce
265    /// scoping via this config's `tenant_resolver` is only effective when a
266    /// resolver yields a tenant from non-identity context (e.g. a single-tenant
267    /// endpoint) — it receives [`crate::moq_authz::PeerIdentity::anonymous`] on
268    /// the open path. For a **shared multi-tenant** endpoint, install
269    /// [`Self::with_moq_connect_authz`] (#1153): that authenticates the CONNECT
270    /// (bearer JWT, verified before the handshake completes), resolves the
271    /// tenant from the *verified* subject, and — when set — takes precedence
272    /// over this config's anonymous resolver path, refusing unauthenticated /
273    /// tenant-less CONNECTs (fail-closed) and serving each authenticated peer
274    /// only its own tenant's broadcasts. Cross-tenant enumeration defense for
275    /// authenticated peers over the iroh `moql` ALPN lives in
276    /// [`crate::transport::iroh_moq`].
277    pub fn with_moq_authz(mut self, authz: crate::transport::iroh_moq::MoqAuthzConfig) -> Self {
278        self.moq_authz = authz;
279        self
280    }
281
282    /// Install the #1153 CONNECT-time authenticator for the `/moq` plane.
283    ///
284    /// When set, the accept loop verifies a bearer JWT from the CONNECT's
285    /// HTTP/3 `Authorization` header **before** completing the WebTransport
286    /// handshake, resolves the tenant from the *verified* subject via the
287    /// configured resolver, and refuses the CONNECT (fail-closed) on any
288    /// failure — missing header, bad signature, expired token, or a verified
289    /// subject with no tenant. A connected peer then sees only its own
290    /// tenant's broadcasts (structural scoping). With this unset, the `/moq`
291    /// plane stays single-tenant/open (no boundary), preserving the
292    /// pre-#1153 behaviour for deployments that have not opted in.
293    pub fn with_moq_connect_authz(
294        mut self,
295        authz: crate::transport::moq_connect_auth::MoqConnectAuthz,
296    ) -> Self {
297        self.moq_connect_authz = Some(authz);
298        self
299    }
300
301    /// Serve the 9P export plane on the same endpoint (H1b / #765).
302    ///
303    /// Sessions whose WebTransport CONNECT URL path is [`crate::dial::NINEP_PATH`]
304    /// are handed to `handler` (which runs the 9P `Translator::serve_connection`
305    /// core over the WT bidi stream); all other paths route to the RPC core (or
306    /// the moq plane for `/moq`). Overrides any process-global handler picked up
307    /// at construction.
308    pub fn with_ninep_handler(mut self, handler: Arc<dyn NinePWtHandler>) -> Self {
309        self.ninep_handler = Some(handler);
310        self
311    }
312
313    /// Override the concurrent-connection cap (#162, builder style).
314    pub fn with_connection_limit(mut self, limit: usize) -> Self {
315        self.connection_limit = Arc::new(Semaphore::new(limit));
316        self
317    }
318
319    /// Override the server-wide concurrent-stream cap (builder style).
320    pub fn with_stream_limit(mut self, limit: usize) -> Self {
321        self.stream_limit = Arc::new(Semaphore::new(limit));
322        self.stream_limit_capacity = u32::try_from(limit).unwrap_or(u32::MAX);
323        self
324    }
325
326    /// Override the per-stream request-read timeout (#159). Primarily for
327    /// tests; production uses [`super::rpc_session::REQUEST_READ_TIMEOUT`].
328    pub fn with_read_timeout(mut self, read_timeout: Duration) -> Self {
329        self.read_timeout = read_timeout;
330        self
331    }
332
333    /// Apply all tunables from an [`super::rpc_session::RpcConfig`] in one call (#197).
334    pub fn with_rpc_config(self, cfg: &super::rpc_session::RpcConfig) -> Self {
335        self.with_stream_limit(cfg.stream_limit)
336            .with_connection_limit(cfg.connection_limit)
337            .with_read_timeout(cfg.request_read_timeout)
338    }
339
340    /// A handle that, when cancelled, stops the accept loop and per-connection
341    /// serve loops.
342    ///
343    /// Note: cancelling this token alone does **not** drain in-flight streams.
344    /// To wait for in-flight responses to complete, hold a clone of the server
345    /// and call [`QuinnRpcServer::shutdown`] instead (or use it via a shared
346    /// handle). The token is exposed primarily for tests and for callers that
347    /// want to stop accepting without a graceful drain.
348    pub fn shutdown_token(&self) -> CancellationToken {
349        self.shutdown.clone()
350    }
351
352    /// Graceful shutdown mirroring [`super::iroh_rpc::IrohRpcProtocolHandler::shutdown`]:
353    /// cancel the accept loop, then wait for every in-flight stream to release
354    /// its permit (`acquire_many(capacity)`), then `forget()` + `close()` the
355    /// semaphore so any post-shutdown accept sees a closed semaphore and exits.
356    ///
357    /// Takes the shared `Semaphore` + token by reference, so it can be called
358    /// through a clone of the relevant handles while [`QuinnRpcServer::run`]
359    /// owns `self`. See the `quinn_shutdown_drains_in_flight` test.
360    pub async fn shutdown(stream_limit: &Arc<Semaphore>, capacity: u32, token: &CancellationToken) {
361        Self::shutdown_until(
362            stream_limit,
363            capacity,
364            token,
365            tokio::time::Instant::now() + super::rpc_session::DRAIN_TIMEOUT,
366        )
367        .await;
368    }
369
370    /// Drain against the owner's shared deadline, without starting a new grace.
371    pub async fn shutdown_until(
372        stream_limit: &Arc<Semaphore>,
373        capacity: u32,
374        token: &CancellationToken,
375        deadline: tokio::time::Instant,
376    ) {
377        // Stop accepting new streams (level-triggered).
378        token.cancel();
379        // Wait for all in-flight streams to release their permits, but bound
380        // the wait (#159): a wedged processor/transport must not hang shutdown
381        // forever. On timeout we close() and proceed — remaining tasks are torn
382        // down when the connection drops.
383        match tokio::time::timeout_at(deadline, stream_limit.acquire_many(capacity)).await {
384            Ok(Ok(permits)) => {
385                permits.forget();
386                stream_limit.close();
387            }
388            Ok(Err(_)) => {
389                // Already closed; nothing to drain.
390            }
391            Err(_) => {
392                tracing::warn!(
393                    timeout = ?super::rpc_session::DRAIN_TIMEOUT,
394                    "quinn-rpc: drain timed out, forcing teardown"
395                );
396                stream_limit.close();
397            }
398        }
399    }
400
401    /// The shared concurrent-stream semaphore. Pair with [`QuinnRpcServer::capacity`]
402    /// and [`QuinnRpcServer::shutdown_token`] to perform a graceful
403    /// [`QuinnRpcServer::shutdown`] while [`QuinnRpcServer::run`] owns `self`.
404    pub fn stream_limit(&self) -> Arc<Semaphore> {
405        Arc::clone(&self.stream_limit)
406    }
407
408    /// The configured server-wide concurrent-stream capacity.
409    pub fn capacity(&self) -> u32 {
410        self.stream_limit_capacity
411    }
412
413    /// Run the accept loop until `shutdown` is cancelled. Each accepted session
414    /// is served on its own task by the transport-generic core, sharing the
415    /// server-wide [`Semaphore`] so [`QuinnRpcServer::shutdown`] can drain every
416    /// in-flight stream regardless of which connection it belongs to.
417    pub async fn run(mut self) -> Result<()> {
418        loop {
419            tokio::select! {
420                biased;
421                _ = self.shutdown.cancelled() => {
422                    tracing::debug!("quinn-rpc: accept loop cancelled");
423                    return Ok(());
424                }
425                request = self.server.accept() => {
426                    let Some(request) = request else {
427                        tracing::debug!("quinn-rpc: server endpoint closed");
428                        return Ok(());
429                    };
430
431                    // Connection cap (#162): take a permit before doing any
432                    // per-connection work. try_acquire → reject (drop) when at
433                    // cap rather than queueing, so a flood can't build backlog.
434                    let conn_permit = match Arc::clone(&self.connection_limit).try_acquire_owned() {
435                        Ok(p) => p,
436                        Err(_) => {
437                            tracing::warn!("quinn-rpc: connection cap reached, rejecting connection");
438                            drop(request);
439                            continue;
440                        }
441                    };
442
443                    let processor = Arc::clone(&self.processor);
444                    let signing_key = self.signing_key.clone();
445                    let stream_limit = Arc::clone(&self.stream_limit);
446                    let read_timeout = self.read_timeout;
447                    let shutdown = self.shutdown.clone();
448                    let moq_consumer = self.moq_consumer.clone();
449                    let moq_relay_origin = self.moq_relay_origin.clone();
450                    let moq_authz = self.moq_authz.clone();
451                    let moq_connect_authz = self.moq_connect_authz.clone();
452                    let ninep_handler = self.ninep_handler.clone();
453                    let carrier = self.carrier;
454                    tokio::spawn(async move {
455                        let _conn_permit = conn_permit; // released when this connection ends
456                        // Multiplex by WebTransport CONNECT URL path (#274, H1b): read
457                        // it BEFORE `request.ok()` consumes the request. `/moq`
458                        // → moq streaming plane; `/9p` → 9P export plane (#765);
459                        // any other path → RPC core.
460                        // (`Request` Derefs to `ConnectRequest`, exposing `url`.)
461                        let is_moq = request.url.path() == crate::dial::MOQ_PATH;
462                        let is_ninep = request.url.path() == crate::dial::NINEP_PATH;
463                        let is_browser_rpc = request.url.path()
464                            == crate::browser_provisioning::BROWSER_RPC_PATH;
465                        // #1153/F3: resolve the effective authenticator
466                        // per-CONNECT (builder override OR process-global),
467                        // NOT once at construction. This removes the
468                        // ordering-dependent silent downgrade where a server
469                        // built before `set_global_moq_connect_authz` ran open
470                        // forever.
471                        let moq_connect_authz = moq_connect_authz
472                            .clone()
473                            .or_else(global_moq_connect_authz);
474                        // #1153/F1: if this endpoint serves `/moq` but no
475                        // authenticator is configured (override or global), warn
476                        // loudly ONCE per process — the unset state is exactly
477                        // the #1145 shape (an absent expected value silently
478                        // disabling the boundary) and must be detectable.
479                        if is_moq
480                            && (moq_consumer.is_some() || moq_relay_origin.is_some())
481                            && moq_connect_authz.is_none()
482                        {
483                            MOQ_NO_AUTHZ_WARNED.call_once(|| {
484                                tracing::warn!(
485                                    "quinn-moq: /moq plane is served with NO CONNECT authenticator (#1153) — \
486                                     anonymous/unscoped admission is LIVE. This is the #1145 fail-open shape; \
487                                     install MoqConnectAuthz via set_global_moq_connect_authz for a shared endpoint."
488                                );
489                            });
490                        }
491                        // #1153: authenticate the `/moq` CONNECT BEFORE the
492                        // WebTransport session is established. When a
493                        // `MoqConnectAuthz` is resolved, a `/moq` CONNECT must
494                        // present a verifiable bearer JWT (Authorization header)
495                        // whose subject the server resolves to a tenant; any
496                        // failure refuses the CONNECT — we `return` here,
497                        // dropping `request` so `request.ok()` never runs and the
498                        // client's CONNECT never completes. This is fail-closed:
499                        // there is no anonymous/wildcard admission on a
500                        // boundary-configured endpoint.
501                        let moq_connect_verified = if is_moq {
502                            match &moq_connect_authz {
503                                Some(authz) => match authz.verify(&request.headers) {
504                                    Some(verified) => Some(verified),
505                                    None => {
506                                        tracing::warn!(
507                                            "quinn-moq: refusing unauthenticated or tenant-less /moq CONNECT (#1153)"
508                                        );
509                                        return;
510                                    }
511                                },
512                                None => None,
513                            }
514                        } else {
515                            None
516                        };
517                        // Resolve the handshake INSIDE the task, bounded (#162),
518                        // so a slow/stalled CONNECT never blocks the accept loop.
519                        let session = match tokio::time::timeout(
520                            super::rpc_session::HANDSHAKE_TIMEOUT,
521                            request.ok(),
522                        )
523                        .await
524                        {
525                            Ok(Ok(s)) => s,
526                            Ok(Err(e)) => {
527                                tracing::warn!(error = ?e, "quinn-rpc: handshake failed");
528                                return;
529                            }
530                            Err(_) => {
531                                tracing::warn!(
532                                    timeout = ?super::rpc_session::HANDSHAKE_TIMEOUT,
533                                    "quinn-rpc: handshake timed out"
534                                );
535                                return;
536                            }
537                        };
538
539                        if is_moq {
540                            let moq_peer = moq_connect_verified.as_ref().map_or_else(
541                                crate::moq_authz::PeerIdentity::anonymous,
542                                |verified| verified.peer.clone(),
543                            );
544                            if !moq_authz
545                                .authorize_without_track_hook(&moq_peer)
546                                .await
547                                .is_allowed()
548                            {
549                                tracing::warn!(
550                                    subject = ?moq_peer.subject,
551                                    "quinn-moq: installed track authorizer denied session because #276 callback is unavailable"
552                                );
553                                return;
554                            }
555
556                            // Relay (bidirectional) mode takes precedence (#358):
557                            // ingest a producer's announced broadcasts into the
558                            // shared origin AND re-serve them to subscribers by
559                            // track name, so publisher and subscriber rendezvous
560                            // here without either dialing the other. The relay
561                            // holds no stream keys — frames pass through opaquely.
562                            //
563                            // #1153: when a `MoqConnectAuthz` is installed, an
564                            // anonymous CONNECT was already refused above (before
565                            // `request.ok()`), so reaching here on a
566                            // boundary-configured endpoint means the publisher is
567                            // an authenticated, tenant-resolved subject —
568                            // anonymous relay publish (the #1128 relay-mode gap)
569                            // is closed. The relay still routes by track name
570                            // (it must, to rendezvous publisher and subscriber),
571                            // so announce-name visibility through a relay is
572                            // inherent to relay mode; frame content is already
573                            // AEAD-sealed + chained-HMAC'd at the source.
574                            //
575                            // #1153 CRITICAL 3 (relay authorization): bind the
576                            // publisher's INGEST to its verified tenant prefix by
577                            // handing `Server::with_origin` a *scoped* producer.
578                            // Authentication alone let Alice publish into Bob's
579                            // namespace; `OriginProducer::scope` restricts this
580                            // session's publishes to `{tenant}/`, so a publish
581                            // of another tenant's prefix is rejected at ingest.
582                            if let Some(relay_origin) = moq_relay_origin {
583                                let scoped_origin = match &moq_connect_verified {
584                                    Some(verified) => {
585                                        if !crate::moq_authz::is_valid_tenant_segment(
586                                            &verified.tenant,
587                                        ) {
588                                            tracing::warn!(
589                                                tenant = %verified.tenant,
590                                                "quinn-moq-relay: invalid tenant segment; refusing publisher"
591                                            );
592                                            return;
593                                        }
594                                        let prefix =
595                                            crate::moq_authz::tenant_prefix(&verified.tenant);
596                                        let path = moq_net::Path::new(&prefix);
597                                        match relay_origin.scope(&[path]) {
598                                            Some(scoped) => {
599                                                tracing::debug!(
600                                                    subject = ?verified.peer.subject,
601                                                    tenant = %verified.tenant,
602                                                    "quinn-moq-relay: admitting authenticated publisher scoped to tenant prefix"
603                                                );
604                                                scoped
605                                            }
606                                            None => {
607                                                tracing::warn!(
608                                                    tenant = %verified.tenant,
609                                                    "quinn-moq-relay: tenant prefix out of relay scope; refusing publisher"
610                                                );
611                                                return;
612                                            }
613                                        }
614                                    }
615                                    None => relay_origin,
616                                };
617                                let server = moq_net::Server::new().with_origin(scoped_origin);
618                                match server.accept(session).await {
619                                    Ok(moq_session) => {
620                                        tokio::select! {
621                                            biased;
622                                            _ = shutdown.cancelled() => {}
623                                            res = moq_session.closed() => {
624                                                tracing::debug!(result = ?res, "quinn-moq-relay: session closed");
625                                            }
626                                        }
627                                    }
628                                    Err(e) => {
629                                        tracing::debug!(error = ?e, "quinn-moq-relay: accept failed");
630                                    }
631                                }
632                                return;
633                            }
634                            match moq_consumer {
635                                Some(consumer) => {
636                                    // #1153: resolve the publish consumer.
637                                    // - Authenticated path: a `MoqConnectAuthz`
638                                    //   is installed and the CONNECT was
639                                    //   verified; the tenant came from the
640                                    //   *verified* subject via the server-side
641                                    //   resolver. Serve ONLY that tenant's
642                                    //   broadcasts (structural scoping) — never
643                                    //   fall back to the unscoped consumer.
644                                    // - Open path: no authenticator installed.
645                                    //   Endpoint is single-tenant or explicitly
646                                    //   open; preserve the pre-#1153 resolver
647                                    //   behaviour.
648                                    let publish_consumer = match &moq_connect_verified {
649                                        Some(verified) => {
650                                            match crate::moq_authz::tenant_scoped_consumer(
651                                                &consumer,
652                                                &verified.tenant,
653                                            ) {
654                                                Some(scoped) => {
655                                                    tracing::debug!(
656                                                        subject = ?verified.peer.subject,
657                                                        tenant = %verified.tenant,
658                                                        "quinn-moq: CONNECT authenticated, serving tenant-scoped consumer"
659                                                    );
660                                                    scoped
661                                                }
662                                                None => {
663                                                    tracing::debug!(
664                                                        tenant = %verified.tenant,
665                                                        "quinn-moq: tenant has no visible broadcasts; dropping session"
666                                                    );
667                                                    return;
668                                                }
669                                            }
670                                        }
671                                        None => {
672                                            // Legacy/open path: no CONNECT
673                                            // authenticator installed. The peer is
674                                            // anonymous and per-tenant scoping is
675                                            // only effective if the resolver
676                                            // yields a tenant from non-identity
677                                            // context (e.g. a single-tenant
678                                            // endpoint).
679                                            let peer =
680                                                crate::moq_authz::PeerIdentity::anonymous();
681                                            match moq_authz.tenant_for(&peer) {
682                                                Some(tenant) => {
683                                                    match crate::moq_authz::tenant_scoped_consumer(&consumer, &tenant) {
684                                                        Some(scoped) => scoped,
685                                                        None => {
686                                                            tracing::debug!(%tenant, "quinn-moq: tenant has no visible broadcasts; dropping session");
687                                                            return;
688                                                        }
689                                                    }
690                                                }
691                                                None => consumer,
692                                            }
693                                        }
694                                    };
695                                    // Serve moq over this session, mirroring
696                                    // IrohMoqProtocolHandler: publish the shared
697                                    // origin consumer to remote subscribers.
698                                    let server = moq_net::Server::new().with_publish(publish_consumer);
699                                    match server.accept(session).await {
700                                        Ok(moq_session) => {
701                                            // Hold the session until it closes or
702                                            // shutdown is requested.
703                                            tokio::select! {
704                                                biased;
705                                                _ = shutdown.cancelled() => {}
706                                                res = moq_session.closed() => {
707                                                    tracing::debug!(result = ?res, "quinn-moq: session closed");
708                                                }
709                                            }
710                                        }
711                                        Err(e) => {
712                                            tracing::debug!(error = ?e, "quinn-moq: accept failed");
713                                        }
714                                    }
715                                }
716                                None => {
717                                    tracing::warn!(
718                                        "quinn-rpc: /moq requested but no moq consumer configured"
719                                    );
720                                }
721                            }
722                            return;
723                        }
724
725                        if is_ninep {
726                            // 9P export plane (H1b / #765): the QUIC path-mux
727                            // sibling of H1a's axum `/9p` WebSocket. Serve the
728                            // SAME `Translator::serve_connection` core (via the
729                            // injected handler) over a WT bidi stream.
730                            let Some(handler) = ninep_handler else {
731                                tracing::warn!(
732                                    "quinn-rpc: /9p requested but no 9P handler configured"
733                                );
734                                return;
735                            };
736                            // A stream permit bounds concurrency server-wide and
737                            // lets `shutdown` drain the in-flight session (same
738                            // DoS/drain contract as the RPC streams). If the
739                            // semaphore is closed (shutdown drained it), exit.
740                            let _permit = match Arc::clone(&stream_limit).acquire_owned().await {
741                                Ok(p) => p,
742                                Err(_) => return,
743                            };
744                            // Accept the single client-opened bidi stream (bounded
745                            // so a session that never opens one can't pin the
746                            // permit). `RecvStream`/`SendStream` impl tokio
747                            // `AsyncRead`/`AsyncWrite`, so joining them yields the
748                            // byte stream the 9P core serves directly — the WT
749                            // analogue of H1a's ws↔9p pump, tolerant of arbitrary
750                            // chunking.
751                            let accept = tokio::time::timeout(
752                                super::rpc_session::HANDSHAKE_TIMEOUT,
753                                session.accept_bi(),
754                            )
755                            .await;
756                            let (send, recv) = match accept {
757                                Ok(Ok(pair)) => pair,
758                                Ok(Err(e)) => {
759                                    tracing::debug!(error = ?e, "quinn-9p: accept_bi failed");
760                                    return;
761                                }
762                                Err(_) => {
763                                    tracing::warn!("quinn-9p: client opened no bidi stream in time");
764                                    return;
765                                }
766                            };
767                            let stream: Box<dyn NinePWtStream> =
768                                Box::new(tokio::io::join(recv, send));
769                            // Liveness (H1b, mirrors H1a's server-owned teardown):
770                            // the handler's serve loop returns on stream EOF / a
771                            // fatal 9P error; a dead peer is torn down by the
772                            // cert-pinned QUIC session's idle timeout (transport-
773                            // owned, the WT/reach layer) which resets the stream →
774                            // EOF. We also stop on server shutdown and on the WT
775                            // session closing, whichever comes first.
776                            tokio::select! {
777                                biased;
778                                _ = shutdown.cancelled() => {}
779                                _ = handler.serve(stream) => {}
780                                err = session.closed() => {
781                                    tracing::debug!(?err, "quinn-9p: WT session closed");
782                                }
783                            }
784                            return;
785                        }
786
787                        // INV-2 (#1042): this accept boundary terminates a
788                        // WebTransport-over-QUIC session — an untrusted
789                        // carrier even on a loopback address.
790                        // Browser provenance comes only from the CONNECT path
791                        // observed at this accept boundary, never request bytes.
792                        let rpc_carrier = if is_browser_rpc {
793                            crate::transport::carrier::CarrierContext::browser_web_transport()
794                        } else {
795                            carrier
796                        };
797                        if let Err(e) = serve_rpc_connection(
798                            session,
799                            processor,
800                            signing_key,
801                            stream_limit,
802                            read_timeout,
803                            shutdown,
804                            rpc_carrier,
805                        )
806                        .await
807                        {
808                            tracing::debug!(error = ?e, "quinn-rpc: connection serve ended");
809                        }
810                    });
811                }
812            }
813        }
814    }
815}
816
817/// Wraps a quinn [`web_transport_quinn::Session`] as a [`Transport`] for RPC
818/// plane traffic. Delegates to the transport-generic [`SessionRpcTransport`].
819#[derive(Clone)]
820pub struct QuinnTransport {
821    inner: SessionRpcTransport<web_transport_quinn::Session>,
822}
823
824impl QuinnTransport {
825    /// Build from an already-established WebTransport session.
826    pub fn new(session: web_transport_quinn::Session) -> Self {
827        Self {
828            inner: SessionRpcTransport::new(session),
829        }
830    }
831}
832
833/// Re-export the generic stubs under quinn-flavoured names.
834pub type QuinnPendingStream = RpcPendingStream;
835pub type QuinnPublishStub = RpcPublishStub;
836
837#[async_trait]
838impl Transport for QuinnTransport {
839    type Sub = QuinnPendingStream;
840    type Pub = QuinnPublishStub;
841
842    async fn send(&self, payload: Vec<u8>, timeout_ms: Option<i32>) -> Result<Vec<u8>> {
843        self.inner.send(payload, timeout_ms).await
844    }
845
846    fn forbids_cleartext_envelope(&self) -> bool {
847        true
848    }
849
850    async fn subscribe(&self, topic: &[u8]) -> Result<Self::Sub> {
851        self.inner.subscribe(topic).await
852    }
853
854    async fn publish(&self, topic: &[u8]) -> Result<Self::Pub> {
855        self.inner.publish(topic).await
856    }
857}
858
859/// Build a quinn WebTransport client session against a server with a CA-issued
860/// certificate, validated via the system root store and the DNS `server_name`
861/// (`QuicServerAuth::web_pki`). Dials `https://{server_name}:{port}/`.
862pub async fn connect_webpki(server_name: &str, port: u16) -> Result<web_transport_quinn::Session> {
863    let client = external_client_builder()?
864        .with_system_roots()
865        .map_err(|e| anyhow!("quinn client (system roots): {e}"))?;
866    let url = url::Url::parse(&format!("https://{server_name}:{port}/"))
867        .map_err(|e| anyhow!("quinn url: {e}"))?;
868    client
869        .connect(url)
870        .await
871        .map_err(|e| anyhow!("quinn connect (webpki): {e}"))
872}
873
874/// Build a quinn WebTransport client session against a self-signed server,
875/// accepting the leaf cert if its **SHA-256 fingerprint** is any of
876/// `cert_hashes` (`QuicServerAuth::accept_cert_hashes` — a set so rotation can
877/// overlap). Hermetic: dials an IP-literal URL so no DNS lookup or network
878/// egress occurs.
879pub async fn connect_pinned_hashes(
880    addr: std::net::SocketAddr,
881    cert_hashes: &[[u8; 32]],
882) -> Result<web_transport_quinn::Session> {
883    let hashes: Vec<Vec<u8>> = cert_hashes.iter().map(|h| h.to_vec()).collect();
884    let client = external_client_builder()?
885        .with_server_certificate_hashes(hashes)
886        .map_err(|e| anyhow!("quinn client build: {e}"))?;
887    let url =
888        url::Url::parse(&format!("https://{addr}/")).map_err(|e| anyhow!("quinn url: {e}"))?;
889    client
890        .connect(url)
891        .await
892        .map_err(|e| anyhow!("quinn connect: {e}"))
893}
894
895/// Verify the peer's leaf-cert SHA-256 is one of `accept` — the post-connect pin
896/// check for the WebPKI+pin mode (CA validation runs in the handshake; this adds
897/// the pin on top). Call immediately after connect, before any RPC. The cert
898/// fingerprint is public, so a plain comparison is fine (no secret to leak).
899pub fn verify_peer_cert_pinned(
900    session: &web_transport_quinn::Session,
901    accept: &[[u8; 32]],
902) -> Result<()> {
903    // `Session` derefs to `quinn::Connection`, exposing `peer_identity()`.
904    let identity = session
905        .peer_identity()
906        .ok_or_else(|| anyhow!("peer presented no certificate"))?;
907    let certs = identity
908        .downcast_ref::<Vec<rustls::pki_types::CertificateDer<'static>>>()
909        .ok_or_else(|| anyhow!("unexpected peer-identity type (not an X.509 chain)"))?;
910    let leaf = certs
911        .first()
912        .ok_or_else(|| anyhow!("peer cert chain is empty"))?;
913    let mut leaf_hash = [0u8; 32];
914    leaf_hash.copy_from_slice(&sha256(leaf.as_ref()));
915    if accept.contains(&leaf_hash) {
916        Ok(())
917    } else {
918        bail!("peer leaf-cert SHA-256 is not in the configured pin set")
919    }
920}
921
922/// Build a quinn WebTransport client session against a self-signed server at an
923/// explicit URL **path** (e.g. `/moq` for the moq plane vs `/` for RPC),
924/// accepting the leaf cert if its SHA-256 is any of `cert_hashes`. Hermetic:
925/// dials an IP-literal URL so no DNS lookup occurs. Mirrors
926/// [`connect_pinned_hashes`] but lets the caller select the path the server
927/// path-dispatches on (#274).
928pub async fn connect_pinned_hashes_path(
929    addr: std::net::SocketAddr,
930    cert_hashes: &[[u8; 32]],
931    path: &str,
932) -> Result<web_transport_quinn::Session> {
933    let hashes: Vec<Vec<u8>> = cert_hashes.iter().map(|h| h.to_vec()).collect();
934    let client = external_client_builder()?
935        .with_server_certificate_hashes(hashes)
936        .map_err(|e| anyhow!("quinn client build: {e}"))?;
937    let url =
938        url::Url::parse(&format!("https://{addr}{path}")).map_err(|e| anyhow!("quinn url: {e}"))?;
939    client
940        .connect(url)
941        .await
942        .map_err(|e| anyhow!("quinn connect: {e}"))
943}
944
945/// [`connect_pinned_hashes_path`] variant that attaches extra HTTP/3 CONNECT
946/// headers to the WebTransport request — used by #1153 to carry the
947/// `Authorization: Bearer <jwt>` credential the `/moq` endpoint verifies at
948/// CONNECT time. Hermetic: dials an IP-literal URL.
949pub async fn connect_pinned_hashes_path_with_headers(
950    addr: std::net::SocketAddr,
951    cert_hashes: &[[u8; 32]],
952    path: &str,
953    headers: http::HeaderMap,
954) -> Result<web_transport_quinn::Session> {
955    let hashes: Vec<Vec<u8>> = cert_hashes.iter().map(|h| h.to_vec()).collect();
956    let client = external_client_builder()?
957        .with_server_certificate_hashes(hashes)
958        .map_err(|e| anyhow!("quinn client build: {e}"))?;
959    let url =
960        url::Url::parse(&format!("https://{addr}{path}")).map_err(|e| anyhow!("quinn url: {e}"))?;
961    let request = web_transport_quinn::proto::ConnectRequest::from(url).with_headers(headers);
962    client
963        .connect(request)
964        .await
965        .map_err(|e| anyhow!("quinn connect: {e}"))
966}
967
968/// WebPKI variant of [`connect_pinned_hashes_path`]: validate via the system
969/// root store + DNS `server_name`, dialing the given URL `path` (#274).
970pub async fn connect_webpki_path(
971    server_name: &str,
972    port: u16,
973    path: &str,
974) -> Result<web_transport_quinn::Session> {
975    let client = external_client_builder()?
976        .with_system_roots()
977        .map_err(|e| anyhow!("quinn client (system roots): {e}"))?;
978    let url = url::Url::parse(&format!("https://{server_name}:{port}{path}"))
979        .map_err(|e| anyhow!("quinn url: {e}"))?;
980    client
981        .connect(url)
982        .await
983        .map_err(|e| anyhow!("quinn connect (webpki): {e}"))
984}
985
986/// Every native WebTransport client crosses the external-interoperability
987/// boundary. Install and validate the exact effective process policy before
988/// constructing the third-party builder, whose fallback otherwise depends on
989/// whichever rustls provider won process initialization.
990fn external_client_builder() -> Result<web_transport_quinn::ClientBuilder> {
991    crate::transport::pq_provider::install_pq_crypto_provider()
992        .map_err(|e| anyhow!("external WebTransport crypto policy: {e}"))?;
993    Ok(web_transport_quinn::ClientBuilder::new())
994}
995
996/// Convenience: pin by the full server cert DER (hashes it for you). Used by
997/// tests and callers that hold the cert rather than its fingerprint.
998pub async fn connect_pinned(
999    addr: std::net::SocketAddr,
1000    cert_der: &[u8],
1001) -> Result<web_transport_quinn::Session> {
1002    let mut hash = [0u8; 32];
1003    hash.copy_from_slice(&sha256(cert_der));
1004    connect_pinned_hashes(addr, &[hash]).await
1005}
1006
1007fn sha256(bytes: &[u8]) -> Vec<u8> {
1008    use sha2::{Digest, Sha256};
1009    Sha256::digest(bytes).to_vec()
1010}
1011
1012/// SHA-256 fingerprint of a DER-encoded certificate, as 32 raw bytes — the
1013/// cert-hash pin used in `QuicServerAuth`, the DID-doc `#quic` entry, and the
1014/// `StreamInfo.reach` Quic option (#274). The fingerprint is public material.
1015pub fn cert_sha256(cert_der: &[u8]) -> [u8; 32] {
1016    let mut out = [0u8; 32];
1017    out.copy_from_slice(&sha256(cert_der));
1018    out
1019}
1020
1021#[cfg(test)]
1022#[allow(clippy::expect_used)]
1023mod tests {
1024    use super::*;
1025    use bytes::Bytes;
1026    use rand::RngCore;
1027    use std::time::Duration;
1028
1029    fn fresh_signing_key() -> SigningKey {
1030        let mut k = [0u8; 32];
1031        rand::thread_rng().fill_bytes(&mut k);
1032        SigningKey::from_bytes(&k)
1033    }
1034
1035    /// Build a hermetic quinn WebTransport server bound to loopback with a
1036    /// self-signed cert. Returns (server, bound_addr, cert_der).
1037    fn build_server() -> Result<(web_transport_quinn::Server, std::net::SocketAddr, Vec<u8>)> {
1038        let cert_key = rcgen::generate_simple_self_signed(vec!["localhost".to_owned()])?;
1039        let cert_der = cert_key.cert.der().to_vec();
1040        let key_der = cert_key.key_pair.serialize_der();
1041
1042        let chain = vec![rustls::pki_types::CertificateDer::from(cert_der.clone())];
1043        let key = rustls::pki_types::PrivateKeyDer::Pkcs8(
1044            rustls::pki_types::PrivatePkcs8KeyDer::from(key_der),
1045        );
1046
1047        let addr: std::net::SocketAddr = "127.0.0.1:0".parse()?;
1048        let server = web_transport_quinn::ServerBuilder::new()
1049            .with_addr(addr)
1050            .with_certificate(chain, key)
1051            .map_err(|e| anyhow!("quinn server build: {e}"))?;
1052        let bound = server.local_addr()?;
1053        Ok((server, bound, cert_der))
1054    }
1055
1056    /// Round-trip: client sends a request, a closure-processor echoes it back
1057    /// with a 0xCD marker prefix, client asserts on the response.
1058    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
1059    async fn quinn_rpc_round_trip() -> Result<()> {
1060        crate::transport::pq_provider::install_pq_crypto_provider().expect("install PQ provider");
1061
1062        let processor = crate::transport::rpc_session::from_fn(|req: Bytes| async move {
1063            let mut out = Vec::with_capacity(1 + req.len());
1064            out.push(0xCD);
1065            out.extend_from_slice(&req);
1066            Ok(Bytes::from(out))
1067        });
1068
1069        let (server, addr, cert_der) = build_server()?;
1070        let rpc_server =
1071            QuinnRpcServer::new(server, processor, fresh_signing_key()).with_test_trusted_carrier();
1072        let shutdown = rpc_server.shutdown_token();
1073        let server_task = tokio::spawn(rpc_server.run());
1074
1075        let session = connect_pinned(addr, &cert_der).await?;
1076        let client = QuinnTransport::new(session);
1077
1078        let resp = client.send(b"ping".to_vec(), Some(5_000)).await?;
1079        assert_eq!(&resp[..], b"\xCDping");
1080
1081        shutdown.cancel();
1082        let _ = server_task.await;
1083        Ok(())
1084    }
1085
1086    /// Isolated test of the WebPKI+pin post-connect check: against the hermetic
1087    /// self-signed server, the leaf hash must match the pin set (right => Ok,
1088    /// wrong => Err, empty set => Err = fail-closed).
1089    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
1090    async fn verify_peer_cert_pinned_accepts_right_rejects_wrong() -> Result<()> {
1091        crate::transport::pq_provider::install_pq_crypto_provider().expect("install PQ provider");
1092        let processor = crate::transport::rpc_session::from_fn(|req: Bytes| async move { Ok(req) });
1093        let (server, addr, cert_der) = build_server()?;
1094        let rpc_server =
1095            QuinnRpcServer::new(server, processor, fresh_signing_key()).with_test_trusted_carrier();
1096        let shutdown = rpc_server.shutdown_token();
1097        let server_task = tokio::spawn(rpc_server.run());
1098
1099        let session = connect_pinned(addr, &cert_der).await?;
1100        let mut right = [0u8; 32];
1101        right.copy_from_slice(&sha256(&cert_der));
1102
1103        assert!(
1104            verify_peer_cert_pinned(&session, &[right]).is_ok(),
1105            "matching leaf hash must pass"
1106        );
1107        assert!(
1108            verify_peer_cert_pinned(&session, &[[0u8; 32]]).is_err(),
1109            "wrong hash must reject"
1110        );
1111        assert!(
1112            verify_peer_cert_pinned(&session, &[]).is_err(),
1113            "empty pin set must reject (fail-closed)"
1114        );
1115
1116        shutdown.cancel();
1117        let _ = server_task.await;
1118        Ok(())
1119    }
1120
1121    /// #162: with a connection cap of 1, a second concurrent connection is
1122    /// rejected while the first is still live. The first keeps working.
1123    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
1124    async fn quinn_connection_cap_rejects_excess() -> Result<()> {
1125        crate::transport::pq_provider::install_pq_crypto_provider().expect("install PQ provider");
1126
1127        let processor = crate::transport::rpc_session::from_fn(|req: Bytes| async move { Ok(req) });
1128
1129        let (server, addr, cert_der) = build_server()?;
1130        let rpc_server = QuinnRpcServer::new(server, processor, fresh_signing_key())
1131            .with_test_trusted_carrier()
1132            .with_connection_limit(1);
1133        let shutdown = rpc_server.shutdown_token();
1134        let server_task = tokio::spawn(rpc_server.run());
1135
1136        // First connection takes the only permit and works.
1137        let session1 = connect_pinned(addr, &cert_der).await?;
1138        let client1 = QuinnTransport::new(session1);
1139        let resp1 = client1.send(b"one".to_vec(), Some(5_000)).await?;
1140        assert_eq!(&resp1[..], b"one");
1141
1142        // Second connection: the server rejects it (drops the request before
1143        // accepting), so a request on it must fail rather than be served.
1144        // connect_pinned itself may or may not error depending on timing; the
1145        // load-bearing assertion is that no request succeeds on conn #2.
1146        let second = async {
1147            let session2 = connect_pinned(addr, &cert_der).await?;
1148            let client2 = QuinnTransport::new(session2);
1149            client2.send(b"two".to_vec(), Some(2_000)).await
1150        }
1151        .await;
1152        assert!(
1153            second.is_err(),
1154            "second connection over the cap must not be served, got {second:?}"
1155        );
1156
1157        // First connection still works after the rejection.
1158        let resp1b = client1.send(b"again".to_vec(), Some(5_000)).await?;
1159        assert_eq!(&resp1b[..], b"again");
1160
1161        shutdown.cancel();
1162        let _ = server_task.await;
1163        Ok(())
1164    }
1165
1166    /// Graceful shutdown drains in-flight requests: a request in-progress when
1167    /// `shutdown()` starts still completes with its real response rather than
1168    /// being abandoned mid-flight. Mirrors `iroh_rpc::rpc_shutdown_drains_in_flight`.
1169    ///
1170    /// Uses a `Notify` to synchronise "processor has entered the long sleep"
1171    /// with "now safe to shut down" — no wall-clock sleep races.
1172    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
1173    async fn quinn_shutdown_drains_in_flight() -> Result<()> {
1174        crate::transport::pq_provider::install_pq_crypto_provider().expect("install PQ provider");
1175
1176        let entered = Arc::new(tokio::sync::Notify::new());
1177        let entered_c = Arc::clone(&entered);
1178        let processor = crate::transport::rpc_session::from_fn(move |_req: Bytes| {
1179            let entered = Arc::clone(&entered_c);
1180            async move {
1181                entered.notify_one();
1182                tokio::time::sleep(Duration::from_millis(300)).await;
1183                Ok(Bytes::from_static(b"drained-ok"))
1184            }
1185        });
1186
1187        let (server, addr, cert_der) = build_server()?;
1188        let rpc_server =
1189            QuinnRpcServer::new(server, processor, fresh_signing_key()).with_test_trusted_carrier();
1190        // Grab the shared drain handles before `run()` consumes the server.
1191        let stream_limit = rpc_server.stream_limit();
1192        let capacity = rpc_server.capacity();
1193        let token = rpc_server.shutdown_token();
1194        let server_task = tokio::spawn(rpc_server.run());
1195
1196        let session = connect_pinned(addr, &cert_der).await?;
1197        let client = QuinnTransport::new(session);
1198
1199        // Fire the slow request on its own task.
1200        let req_task = {
1201            let client = client.clone();
1202            tokio::spawn(async move { client.send(b"slow".to_vec(), Some(10_000)).await })
1203        };
1204
1205        // Synchronise: wait until the processor has entered the sleep, then
1206        // drain-shutdown. No wall-clock guesses.
1207        tokio::time::timeout(Duration::from_secs(5), entered.notified())
1208            .await
1209            .context("processor was never entered before shutdown")?;
1210        QuinnRpcServer::shutdown(&stream_limit, capacity, &token).await;
1211
1212        // The in-flight request must still complete with its real response.
1213        let resp = req_task.await??;
1214        assert_eq!(&resp[..], b"drained-ok");
1215
1216        let _ = server_task.await;
1217        Ok(())
1218    }
1219
1220    async fn exercise_all_native_client_constructors() {
1221        // Malformed hostnames make the WebPKI variants stop after builder
1222        // construction. Pinned variants are polled briefly against a closed
1223        // loopback port; cancellation is enough because policy enforcement is
1224        // synchronous at the start of each constructor.
1225        let _ = connect_webpki("[", 443).await;
1226        let _ = connect_webpki_path("[", 443, "/moq").await;
1227        let closed: std::net::SocketAddr = "127.0.0.1:9".parse().expect("test address");
1228        let _ = tokio::time::timeout(
1229            Duration::from_millis(50),
1230            connect_pinned_hashes(closed, &[]),
1231        )
1232        .await;
1233        let _ = tokio::time::timeout(
1234            Duration::from_millis(50),
1235            connect_pinned_hashes_path(closed, &[], "/moq"),
1236        )
1237        .await;
1238    }
1239
1240    // These fixtures require fresh processes because rustls's default provider
1241    // is a OnceLock. Their parent tests invoke them by exact test name.
1242    #[tokio::test]
1243    #[ignore = "subprocess provider fixture"]
1244    async fn native_clients_install_external_policy_child() {
1245        assert!(
1246            rustls::crypto::CryptoProvider::get_default().is_none(),
1247            "fixture must begin without a process provider"
1248        );
1249        exercise_all_native_client_constructors().await;
1250        crate::transport::pq_provider::install_pq_crypto_provider()
1251            .expect("actual client constructors must install the exact external policy");
1252    }
1253
1254    #[tokio::test]
1255    #[ignore = "subprocess provider fixture"]
1256    async fn native_clients_reject_ring_first_child() {
1257        rustls::crypto::ring::default_provider()
1258            .install_default()
1259            .expect("fixture must install ring first");
1260
1261        let err = connect_webpki("127.0.0.1", 9)
1262            .await
1263            .expect_err("ring-first WebPKI constructor must fail before dialing");
1264        assert!(err.to_string().contains("crypto policy mismatch"));
1265
1266        let err = connect_webpki_path("127.0.0.1", 9, "/moq")
1267            .await
1268            .expect_err("ring-first WebPKI path constructor must fail before dialing");
1269        assert!(err.to_string().contains("crypto policy mismatch"));
1270
1271        let addr = "127.0.0.1:9".parse().expect("test address");
1272        let err = connect_pinned_hashes(addr, &[])
1273            .await
1274            .expect_err("ring-first pinned constructor must fail before dialing");
1275        assert!(err.to_string().contains("crypto policy mismatch"));
1276
1277        let err = connect_pinned_hashes_path(addr, &[], "/moq")
1278            .await
1279            .expect_err("ring-first pinned path constructor must fail before dialing");
1280        assert!(err.to_string().contains("crypto policy mismatch"));
1281    }
1282
1283    fn run_provider_fixture(name: &str) -> std::process::Output {
1284        let mut child =
1285            std::process::Command::new(std::env::current_exe().expect("test executable path"))
1286                .args(["--ignored", "--exact", name])
1287                .stdout(std::process::Stdio::piped())
1288                .stderr(std::process::Stdio::piped())
1289                .spawn()
1290                .expect("spawn native client provider fixture");
1291        let deadline = std::time::Instant::now() + Duration::from_secs(30);
1292        loop {
1293            if child
1294                .try_wait()
1295                .expect("poll native client fixture")
1296                .is_some()
1297            {
1298                return child
1299                    .wait_with_output()
1300                    .expect("collect native client fixture output");
1301            }
1302            if std::time::Instant::now() >= deadline {
1303                let _ = child.kill();
1304                let _ = child.wait();
1305                panic!("native client fixture {name} timed out after 30 seconds");
1306            }
1307            std::thread::sleep(Duration::from_millis(10));
1308        }
1309    }
1310
1311    #[test]
1312    fn native_clients_install_external_policy_in_fresh_process() {
1313        let output = run_provider_fixture(
1314            "transport::quinn_transport::tests::native_clients_install_external_policy_child",
1315        );
1316        assert!(
1317            output.status.success(),
1318            "fresh-process native clients failed: {}",
1319            String::from_utf8_lossy(&output.stderr)
1320        );
1321    }
1322
1323    #[test]
1324    fn native_clients_reject_ring_first_in_fresh_process() {
1325        let output = run_provider_fixture(
1326            "transport::quinn_transport::tests::native_clients_reject_ring_first_child",
1327        );
1328        assert!(
1329            output.status.success(),
1330            "ring-first native client policy fixture failed: {}",
1331            String::from_utf8_lossy(&output.stderr)
1332        );
1333    }
1334}