relay.rs (15101B)
1 //! Nostr relay identifiers and network policy. 2 3 use crate::Error; 4 use core::fmt; 5 use nostr_sdk::error::Error as TransportError; 6 use radroots_transport::{Target, TargetNetworkPolicy, TransportId}; 7 use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; 8 use url::Url; 9 10 /// Validated canonical Nostr relay URL. 11 #[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] 12 pub struct RelayUrl(String); 13 14 impl RelayUrl { 15 /// Parses, canonicalizes, and applies an explicit destination policy. 16 pub fn parse(value: impl AsRef<str>, policy: RelayUrlPolicy) -> Result<Self, Error> { 17 let original = value.as_ref(); 18 let target = match policy { 19 RelayUrlPolicy::PrivateNetwork => { 20 Target::nostr_relay_with_policy(original, TargetNetworkPolicy::PrivateDevice) 21 } 22 RelayUrlPolicy::Public | RelayUrlPolicy::Local => Target::nostr_relay(original), 23 } 24 .map_err(|_| Error::InvalidRelayUrl)?; 25 let canonical = target.uri().as_str(); 26 let parsed = Url::parse(canonical).map_err(|_| Error::InvalidRelayUrl)?; 27 let host = parsed.host_str().ok_or(Error::InvalidRelayUrl)?; 28 validate_scheme(canonical, parsed.scheme(), policy)?; 29 validate_host(canonical, host, policy)?; 30 Ok(Self(canonical.to_owned())) 31 } 32 33 /// Converts a validated relay URL into the generic Nostr target model. 34 pub fn to_target(&self) -> Result<Target, Error> { 35 Target::nostr_relay(self.as_str()) 36 .or_else(|_| { 37 Target::nostr_relay_with_policy(self.as_str(), TargetNetworkPolicy::PrivateDevice) 38 }) 39 .map_err(|_| Error::Target) 40 } 41 42 /// Validates and converts a generic target under the selected policy. 43 pub fn from_target(target: &Target, policy: RelayUrlPolicy) -> Result<Self, Error> { 44 if *target.kind() != TransportId::NOSTR { 45 return Err(Error::UnexpectedTransport); 46 } 47 Self::parse(target.uri().as_str(), policy) 48 } 49 50 /// Revalidates every address returned by DNS before a connection is made. 51 pub fn validate_resolved_addresses( 52 &self, 53 policy: RelayUrlPolicy, 54 addresses: impl IntoIterator<Item = IpAddr>, 55 ) -> Result<(), Error> { 56 let mut resolved = false; 57 for address in addresses { 58 resolved = true; 59 if !policy.accepts_address(address) { 60 return Err(Error::ResolvedAddressDenied); 61 } 62 } 63 if !resolved { 64 return Err(Error::EmptyResolution); 65 } 66 Ok(()) 67 } 68 69 /// Returns the canonical relay URL. 70 pub fn as_str(&self) -> &str { 71 self.0.as_str() 72 } 73 } 74 75 impl fmt::Display for RelayUrl { 76 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { 77 formatter.write_str(self.as_str()) 78 } 79 } 80 81 #[derive(Debug)] 82 struct NetworkPolicyError(&'static str); 83 84 impl fmt::Display for NetworkPolicyError { 85 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { 86 formatter.write_str(self.0) 87 } 88 } 89 90 impl std::error::Error for NetworkPolicyError {} 91 92 pub(crate) fn policy_error(message: &'static str) -> TransportError { 93 TransportError::policy(NetworkPolicyError(message)) 94 } 95 96 /// Destination class authorized for relay connections. 97 #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] 98 #[non_exhaustive] 99 pub enum RelayUrlPolicy { 100 /// TLS-only public Internet endpoints; resolved addresses must be global. 101 Public, 102 /// Exact loopback endpoints; plaintext WebSocket is allowed. 103 Local, 104 /// Exact RFC1918 IPv4 or ULA IPv6 device endpoints. 105 PrivateNetwork, 106 } 107 108 impl RelayUrlPolicy { 109 pub(crate) fn accepts_address(self, address: IpAddr) -> bool { 110 match self { 111 Self::Public => public_address(address), 112 Self::Local => address.is_loopback(), 113 Self::PrivateNetwork => trusted_network_address(address), 114 } 115 } 116 } 117 118 fn validate_scheme(_url: &str, scheme: &str, policy: RelayUrlPolicy) -> Result<(), Error> { 119 if scheme == "wss" 120 || scheme == "ws" 121 && matches!( 122 policy, 123 RelayUrlPolicy::Local | RelayUrlPolicy::PrivateNetwork 124 ) 125 { 126 return Ok(()); 127 } 128 Err(Error::RelaySchemeDenied) 129 } 130 131 fn validate_host(_url: &str, host: &str, policy: RelayUrlPolicy) -> Result<(), Error> { 132 let address = host.trim_matches(['[', ']']).parse::<IpAddr>().ok(); 133 let accepted = match (policy, address) { 134 (RelayUrlPolicy::Public, Some(address)) => public_address(address), 135 (RelayUrlPolicy::Public, None) => public_hostname(host), 136 (RelayUrlPolicy::Local, Some(address)) => address.is_loopback(), 137 (RelayUrlPolicy::Local, None) => host.eq_ignore_ascii_case("localhost"), 138 (RelayUrlPolicy::PrivateNetwork, Some(address)) => trusted_network_address(address), 139 (RelayUrlPolicy::PrivateNetwork, None) => false, 140 }; 141 if accepted { 142 Ok(()) 143 } else { 144 Err(Error::RelayDestinationDenied) 145 } 146 } 147 148 fn public_hostname(host: &str) -> bool { 149 let host = host.trim_end_matches('.').to_ascii_lowercase(); 150 host.contains('.') 151 && host != "localhost" 152 && !host.ends_with(".localhost") 153 && !host.ends_with(".local") 154 && !host.ends_with(".home.arpa") 155 } 156 157 fn public_address(address: IpAddr) -> bool { 158 match address { 159 IpAddr::V4(address) => public_ipv4(address), 160 IpAddr::V6(address) => public_ipv6(address), 161 } 162 } 163 164 fn trusted_network_address(address: IpAddr) -> bool { 165 match address { 166 IpAddr::V4(address) => address.is_private(), 167 IpAddr::V6(address) => address.segments()[0] & 0xfe00 == 0xfc00, 168 } 169 } 170 171 fn public_ipv4(address: Ipv4Addr) -> bool { 172 let octets = address.octets(); 173 !(octets[0] == 0 174 || address.is_loopback() 175 || address.is_private() 176 || address.is_link_local() 177 || address.is_multicast() 178 || address.is_documentation() 179 || octets[0] == 100 && (64..=127).contains(&octets[1]) 180 || octets[0] == 192 && octets[1] == 0 && octets[2] == 0 181 || octets[0] == 192 && octets[1] == 88 && octets[2] == 99 182 || octets[0] == 198 && matches!(octets[1], 18 | 19) 183 || octets[0] >= 240) 184 } 185 186 fn public_ipv6(address: Ipv6Addr) -> bool { 187 if let Some(mapped) = address.to_ipv4_mapped() { 188 return public_ipv4(mapped); 189 } 190 let segments = address.segments(); 191 (segments[0] & 0xe000) == 0x2000 192 && !(segments[0] == 0x2001 && segments[1] <= 0x01ff) 193 && !(segments[0] == 0x2001 && segments[1] == 0x0db8) 194 && segments[0] != 0x2002 195 && !(segments[0] == 0x3fff && (segments[1] & 0xf000) == 0) 196 } 197 198 #[cfg(test)] 199 mod tests { 200 use super::*; 201 202 #[test] 203 fn policies_classify_literal_and_named_destinations() { 204 assert!(RelayUrl::parse("wss://relay.example.com", RelayUrlPolicy::Public).is_ok()); 205 assert!(RelayUrl::parse("wss://10.0.0.1", RelayUrlPolicy::Public).is_err()); 206 assert!(RelayUrl::parse("wss://10.0.0.1", RelayUrlPolicy::PrivateNetwork).is_ok()); 207 assert!(RelayUrl::parse("ws://127.0.0.1", RelayUrlPolicy::Local).is_ok()); 208 assert!(RelayUrl::parse("ws://relay.example.com", RelayUrlPolicy::Public).is_err()); 209 assert!(RelayUrl::parse("wss://localhost", RelayUrlPolicy::Local).is_ok()); 210 assert!(RelayUrl::parse("wss://localhost", RelayUrlPolicy::Public).is_err()); 211 assert!(!public_hostname("localhost.")); 212 assert!(!public_hostname("intranet")); 213 assert!(!public_hostname("host.localhost")); 214 assert!(RelayUrl::parse("wss://host.local", RelayUrlPolicy::Public).is_err()); 215 assert!(RelayUrl::parse("wss://host.home.arpa", RelayUrlPolicy::Public).is_err()); 216 assert!(RelayUrl::parse("wss://private.example", RelayUrlPolicy::PrivateNetwork).is_err()); 217 assert!(RelayUrl::parse("wss://localhost", RelayUrlPolicy::PrivateNetwork).is_err()); 218 assert!(RelayUrl::parse("ws://10.0.0.1", RelayUrlPolicy::PrivateNetwork).is_ok()); 219 assert!(RelayUrl::parse("ws://8.8.8.8", RelayUrlPolicy::PrivateNetwork).is_err()); 220 221 let relay = 222 RelayUrl::parse("wss://relay.example.com", RelayUrlPolicy::Public).expect("relay"); 223 assert_eq!(relay.to_string(), relay.as_str()); 224 assert_eq!( 225 RelayUrl::from_target(&relay.to_target().expect("target"), RelayUrlPolicy::Public), 226 Ok(relay) 227 ); 228 let local = Target::local("local:device").expect("local target"); 229 assert!(matches!( 230 RelayUrl::from_target(&local, RelayUrlPolicy::Public), 231 Err(Error::UnexpectedTransport) 232 )); 233 assert!(!policy_error("denied").to_string().is_empty()); 234 } 235 236 #[test] 237 fn device_network_policy_matches_the_shared_conformance_vectors() { 238 let document: serde_json::Value = serde_json::from_str(include_str!( 239 "../../../contracts/conformance/vectors/transport/device_network_policy.v1.json" 240 )) 241 .expect("device network policy vectors"); 242 for vector in document["vectors"].as_array().expect("vectors") { 243 let input = &vector["input"]; 244 if input["surface"] != "relay" { 245 continue; 246 } 247 let policy = match input["policy"].as_str().expect("policy") { 248 "public" => RelayUrlPolicy::Public, 249 "loopback" => RelayUrlPolicy::Local, 250 "private_device" => RelayUrlPolicy::PrivateNetwork, 251 other => panic!("unknown relay policy {other}"), 252 }; 253 let accepted = 254 RelayUrl::parse(input["endpoint"].as_str().expect("endpoint"), policy).is_ok(); 255 assert_eq!( 256 accepted, 257 vector["expected"]["accepted"].as_bool().expect("accepted"), 258 "{}", 259 vector["id"].as_str().expect("id") 260 ); 261 } 262 } 263 264 #[test] 265 fn patched_url_parser_rejects_ascii_masking_punycode() { 266 for denied in ["wss://xn--example-.org", "wss://example.org.xn--"] { 267 assert!(RelayUrl::parse(denied, RelayUrlPolicy::Public).is_err()); 268 } 269 } 270 271 #[test] 272 fn resolved_addresses_are_revalidated() { 273 let relay = RelayUrl::parse("wss://relay.example.com", RelayUrlPolicy::Public) 274 .expect("public relay"); 275 assert!( 276 relay 277 .validate_resolved_addresses( 278 RelayUrlPolicy::Public, 279 [IpAddr::V4(Ipv4Addr::new(93, 184, 216, 34))], 280 ) 281 .is_ok() 282 ); 283 assert!( 284 relay 285 .validate_resolved_addresses( 286 RelayUrlPolicy::Public, 287 [IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1))], 288 ) 289 .is_err() 290 ); 291 assert!( 292 relay 293 .validate_resolved_addresses( 294 RelayUrlPolicy::Public, 295 [ 296 IpAddr::V4(Ipv4Addr::new(93, 184, 216, 34)), 297 IpAddr::V4(Ipv4Addr::new(10, 0, 0, 1)), 298 ], 299 ) 300 .is_err() 301 ); 302 assert!( 303 relay 304 .validate_resolved_addresses(RelayUrlPolicy::Public, []) 305 .is_err() 306 ); 307 } 308 309 #[test] 310 fn address_policies_fail_closed_for_special_use_ranges() { 311 for denied in [ 312 Ipv4Addr::new(0, 0, 0, 0), 313 Ipv4Addr::new(0, 1, 1, 1), 314 Ipv4Addr::new(10, 0, 0, 1), 315 Ipv4Addr::new(100, 64, 0, 1), 316 Ipv4Addr::new(127, 0, 0, 1), 317 Ipv4Addr::new(169, 254, 1, 1), 318 Ipv4Addr::new(192, 0, 2, 1), 319 Ipv4Addr::new(198, 18, 0, 1), 320 Ipv4Addr::new(224, 0, 0, 1), 321 Ipv4Addr::new(240, 0, 0, 1), 322 ] { 323 assert!(!RelayUrlPolicy::Public.accepts_address(denied.into())); 324 } 325 for denied in [Ipv6Addr::UNSPECIFIED, Ipv6Addr::LOCALHOST] { 326 assert!(!RelayUrlPolicy::Public.accepts_address(denied.into())); 327 } 328 assert!(RelayUrlPolicy::Local.accepts_address(Ipv4Addr::LOCALHOST.into())); 329 assert!(!RelayUrlPolicy::Local.accepts_address(Ipv4Addr::new(10, 0, 0, 1).into())); 330 assert!(RelayUrlPolicy::PrivateNetwork.accepts_address(Ipv4Addr::new(10, 0, 0, 1).into())); 331 assert!(!RelayUrlPolicy::PrivateNetwork.accepts_address(Ipv4Addr::UNSPECIFIED.into())); 332 assert!(!RelayUrlPolicy::PrivateNetwork.accepts_address(Ipv4Addr::LOCALHOST.into())); 333 assert!(!RelayUrlPolicy::PrivateNetwork.accepts_address(Ipv4Addr::BROADCAST.into())); 334 assert!( 335 !RelayUrlPolicy::PrivateNetwork.accepts_address(Ipv4Addr::new(224, 0, 0, 1).into()) 336 ); 337 assert!( 338 RelayUrlPolicy::PrivateNetwork 339 .accepts_address("fd00::1".parse::<Ipv6Addr>().expect("private v6").into()) 340 ); 341 assert!(!RelayUrlPolicy::PrivateNetwork.accepts_address(Ipv6Addr::UNSPECIFIED.into())); 342 assert!(!RelayUrlPolicy::PrivateNetwork.accepts_address(Ipv6Addr::LOCALHOST.into())); 343 assert!( 344 !RelayUrlPolicy::PrivateNetwork 345 .accepts_address("ff02::1".parse::<Ipv6Addr>().expect("multicast").into()) 346 ); 347 348 for denied in [ 349 "192.0.0.1", 350 "192.88.99.1", 351 "198.19.0.1", 352 "255.0.0.1", 353 "::ffff:10.0.0.1", 354 "2001:db8::1", 355 "2002::1", 356 "3fff::1", 357 "fc00::1", 358 "fe80::1", 359 "ff02::1", 360 ] { 361 let address = denied.parse::<IpAddr>().expect("address"); 362 assert!( 363 !RelayUrlPolicy::Public.accepts_address(address), 364 "accepted {denied}" 365 ); 366 } 367 for allowed in ["8.8.8.8", "2606:4700:4700::1111"] { 368 assert!( 369 RelayUrlPolicy::Public.accepts_address(allowed.parse::<IpAddr>().expect("address")) 370 ); 371 } 372 } 373 374 #[test] 375 fn address_policy_keeps_special_use_range_edges_and_adjacent_global_addresses_distinct() { 376 for (address, accepted) in [ 377 ("100.63.255.255", true), 378 ("100.64.0.0", false), 379 ("100.127.255.255", false), 380 ("100.128.0.0", true), 381 ("192.0.0.0", false), 382 ("192.0.0.255", false), 383 ("192.0.1.0", true), 384 ("192.88.98.255", true), 385 ("192.88.99.0", false), 386 ("192.88.99.255", false), 387 ("192.88.100.0", true), 388 ("2001:1ff::1", false), 389 ("2001:200::1", true), 390 ("2001:db8::1", false), 391 ("2001:db9::1", true), 392 ] { 393 assert_eq!( 394 RelayUrlPolicy::Public.accepts_address(address.parse().unwrap()), 395 accepted, 396 "{address}" 397 ); 398 } 399 assert!(validate_scheme("ftp://relay.example", "ftp", RelayUrlPolicy::Public).is_err()); 400 } 401 }