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}