Skip to main content

hyprstream_rpc/transport/
carrier.rs

1//! Receive-side carrier classification (INV-2, #1042; ADR #1023).
2//!
3//! A [`CarrierContext`] states, for one accepted connection/request, which
4//! class of carrier the bytes arrived on. It is constructed **only at the
5//! server's real accept boundary** (the listener/session code in this crate)
6//! and threaded through [`super::rpc_session::serve_rpc_connection`] and
7//! [`crate::service::dispatch::process_request`] to the envelope-policy
8//! chokepoints. It is never derived from request bytes, headers, JWT claims,
9//! remote addresses, or caller assertions — whoever constructs a request must
10//! not be able to construct its trust class.
11//!
12//! The context answers exactly one policy question on the receive path: may a
13//! cleartext (`encrypted_envelope == None`) request envelope be processed?
14//! Untrusted carriers (iroh direct/relay, QUIC including loopback,
15//! WebTransport, unknown) must reject cleartext before claims evaluation or
16//! handler dispatch; only explicitly trusted same-host carriers (inproc, UDS,
17//! systemd-activated UDS) retain their documented cleartext behavior.
18//!
19//! This mirrors the send side's [`Transport::forbids_cleartext_envelope`]
20//! (#1036) so the two halves of INV-2 (#1028) classify identically. The
21//! carrier context is **not** an identity: remote NodeId, TLS identity,
22//! relay/direct state, and signer equality remain diagnostics — live identity
23//! admission is #1027's separate evidence.
24//!
25//! [`Transport::forbids_cleartext_envelope`]: crate::transport_traits::Transport::forbids_cleartext_envelope
26
27/// Carrier class of an accepted RPC connection, as attested by the accept
28/// boundary that constructed it.
29///
30/// Trusted-local constructors are `pub(crate)`: only this crate's transport
31/// accept boundaries (in-memory inproc, UDS/systemd listeners) can mint a
32/// trusted context. Untrusted constructors are freely public — classifying a
33/// carrier as untrusted is always safe.
34#[derive(Clone, Copy, Debug, PartialEq, Eq)]
35pub struct CarrierContext {
36    class: CarrierClass,
37}
38
39#[derive(Clone, Copy, Debug, PartialEq, Eq)]
40enum CarrierClass {
41    /// Same-process in-memory channel: bytes never leave the address space.
42    Inproc,
43    /// Same-host Unix domain socket accepted by this crate's UDS listener
44    /// (including systemd socket activation) — peer-credential authenticated.
45    TrustedUds,
46    /// iroh connection, direct or relay-carried.
47    Iroh,
48    /// QUIC session — cross-host or loopback. A loopback address is not
49    /// evidence the bytes stay inside the trust boundary (it can terminate at
50    /// a proxy/tunnel), so it earns no exemption.
51    Quic,
52    /// Native `web_transport_quinn` session. Network-untrusted, but it does not
53    /// claim browser provisioning provenance.
54    NativeWebTransport,
55    /// Browser-only WebTransport session selected by the dedicated CONNECT path.
56    BrowserWebTransport,
57    /// Unknown or ambiguous origin. Fail-closed: treated as untrusted.
58    Unknown,
59}
60
61impl CarrierContext {
62    /// Same-process in-memory carrier (trusted local). Accept-boundary only.
63    pub(crate) fn inproc() -> Self {
64        Self {
65            class: CarrierClass::Inproc,
66        }
67    }
68
69    /// Same-host UDS carrier accepted by this crate's listener, including
70    /// systemd socket activation (trusted local). Accept-boundary only.
71    pub(crate) fn trusted_uds() -> Self {
72        Self {
73            class: CarrierClass::TrustedUds,
74        }
75    }
76
77    /// An iroh carrier (direct or relay-carried). Untrusted.
78    pub fn iroh() -> Self {
79        Self {
80            class: CarrierClass::Iroh,
81        }
82    }
83
84    /// A QUIC carrier — cross-host **or loopback**. Untrusted.
85    pub fn quic() -> Self {
86        Self {
87            class: CarrierClass::Quic,
88        }
89    }
90
91    /// A native WebTransport carrier. Untrusted, without browser provenance.
92    pub fn web_transport() -> Self {
93        Self {
94            class: CarrierClass::NativeWebTransport,
95        }
96    }
97
98    /// Browser WebTransport selected by the dedicated accept-boundary path.
99    pub fn browser_web_transport() -> Self {
100        Self {
101            class: CarrierClass::BrowserWebTransport,
102        }
103    }
104
105    /// Unknown/ambiguous carrier. Untrusted (the fail-closed default any new
106    /// accept path should start from until it is deliberately classified).
107    pub fn untrusted_unknown() -> Self {
108        Self {
109            class: CarrierClass::Unknown,
110        }
111    }
112
113    /// Whether this carrier forbids cleartext request envelopes (INV-2).
114    ///
115    /// `true` for every network/unknown carrier; `false` only for the
116    /// explicitly trusted same-host classes.
117    pub fn forbids_cleartext_envelope(&self) -> bool {
118        match self.class {
119            CarrierClass::Inproc | CarrierClass::TrustedUds => false,
120            CarrierClass::Iroh
121            | CarrierClass::Quic
122            | CarrierClass::NativeWebTransport
123            | CarrierClass::BrowserWebTransport
124            | CarrierClass::Unknown => true,
125        }
126    }
127
128    /// Browser requests must carry accepted-current evidence and pass a live
129    /// checkpoint-backed check immediately before dispatch.
130    pub(crate) fn requires_browser_provisioning(self) -> bool {
131        self.class == CarrierClass::BrowserWebTransport
132    }
133
134    /// Short static label for logs/errors. Never used for policy.
135    pub fn label(&self) -> &'static str {
136        match self.class {
137            CarrierClass::Inproc => "inproc",
138            CarrierClass::TrustedUds => "uds",
139            CarrierClass::Iroh => "iroh",
140            CarrierClass::Quic => "quic",
141            CarrierClass::NativeWebTransport => "webtransport-native",
142            CarrierClass::BrowserWebTransport => "webtransport-browser",
143            CarrierClass::Unknown => "unknown",
144        }
145    }
146}
147
148impl std::fmt::Display for CarrierContext {
149    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
150        f.write_str(self.label())
151    }
152}
153
154#[cfg(test)]
155mod tests {
156    use super::*;
157
158    /// INV-2 receive-side classification matrix (#1042): every network or
159    /// unknown carrier forbids cleartext; only the explicit same-host classes
160    /// permit it.
161    #[test]
162    fn inv2_receive_carrier_matrix() {
163        assert!(CarrierContext::iroh().forbids_cleartext_envelope());
164        assert!(CarrierContext::quic().forbids_cleartext_envelope(),);
165        assert!(CarrierContext::web_transport().forbids_cleartext_envelope());
166        assert!(CarrierContext::browser_web_transport().forbids_cleartext_envelope());
167        assert!(!CarrierContext::web_transport().requires_browser_provisioning());
168        assert!(CarrierContext::browser_web_transport().requires_browser_provisioning());
169        assert!(
170            CarrierContext::untrusted_unknown().forbids_cleartext_envelope(),
171            "missing/ambiguous context must follow the untrusted branch"
172        );
173        assert!(!CarrierContext::inproc().forbids_cleartext_envelope());
174        assert!(!CarrierContext::trusted_uds().forbids_cleartext_envelope());
175    }
176}