lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

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 }