pata 0.0.1

A fast, lightweight, and evidence-driven email validation library for Rust
Documentation
use std::{net::IpAddr, time::Duration};

use hickory_resolver::{
    Resolver as HickoryResolver,
    proto::rr::{RData, rdata::MX},
};

use super::runtime::PortableProvider;
use crate::{
    Error, Result,
    dns::{
        MAX_EXCHANGES, MailExchange, Resolution, ResolutionKind, Resolve, ResolveError,
        ResolveErrorKind, Resolver,
    },
};

#[derive(Clone)]
pub(super) struct SystemResolver {
    inner: HickoryResolver<PortableProvider>,
}

impl SystemResolver {
    pub(super) fn new() -> Result<Self> {
        super::runtime::initialize()?;
        let builder = HickoryResolver::builder(PortableProvider).map_err(|error| {
            Error::NetworkInitialization(format!("cannot read system DNS configuration: {error}"))
        })?;
        let inner = builder.build().map_err(|error| {
            Error::NetworkInitialization(format!("cannot initialize system DNS: {error}"))
        })?;
        Ok(Self { inner })
    }
}

impl Resolver for SystemResolver {
    fn resolve(&self, domain: &str) -> Resolve<'_> {
        let domain = domain.to_owned();
        Box::pin(async move { resolve(&self.inner, domain).await })
    }

    #[cfg(feature = "posture")]
    fn resolve_text(&self, domain: &str) -> crate::dns::ResolveText<'_> {
        let domain = absolute_name(domain);
        Box::pin(async move {
            match self.inner.txt_lookup(domain).await {
                Ok(lookup) => {
                    let values = lookup
                        .answers()
                        .iter()
                        .filter_map(|record| match &record.data {
                            RData::TXT(text) => Some(
                                text.txt_data
                                    .iter()
                                    .flat_map(|part| part.iter().copied())
                                    .collect::<Vec<_>>(),
                            ),
                            _ => None,
                        })
                        .map(|value| String::from_utf8_lossy(&value).into_owned())
                        .collect();
                    let valid_for = Some(
                        lookup
                            .valid_until()
                            .saturating_duration_since(std::time::Instant::now()),
                    );
                    crate::dns::TextRecords::new(values, valid_for)
                }
                Err(error) if error.is_no_records_found() || error.is_nx_domain() => {
                    crate::dns::TextRecords::new(Vec::new(), negative_lifetime(&error))
                }
                Err(error) => Err(map_error(&error)),
            }
        })
    }
}

async fn resolve(
    resolver: &HickoryResolver<PortableProvider>,
    domain: String,
) -> std::result::Result<Resolution, ResolveError> {
    let query = absolute_name(&domain);
    match resolver.mx_lookup(query.as_str()).await {
        Ok(mx) => {
            let mut valid_for = lookup_lifetime(mx.valid_until());
            let mut records = mx
                .answers()
                .iter()
                .filter_map(|record| match &record.data {
                    RData::MX(mx) => Some(mx),
                    _ => None,
                })
                .collect::<Vec<_>>();
            if normalize_mail_exchangers(&mut records)? {
                return Ok(Resolution::new(
                    ResolutionKind::NullMx,
                    Vec::new(),
                    valid_for,
                ));
            }

            let mut exchanges = Vec::with_capacity(records.len());
            let mut address_lookup_failed = false;
            for record in records {
                let host = record.exchange.to_ascii();
                let addresses = match resolver.lookup_ip(host.as_str()).await {
                    Ok(lookup) => {
                        valid_for =
                            minimum_lifetime(valid_for, lookup_lifetime(lookup.valid_until()));
                        lookup.iter().collect()
                    }
                    Err(error) if error.is_no_records_found() || error.is_nx_domain() => {
                        valid_for = minimum_lifetime(valid_for, negative_lifetime(&error));
                        Vec::new()
                    }
                    Err(_) => {
                        address_lookup_failed = true;
                        Vec::new()
                    }
                };
                exchanges.push(MailExchange::new(record.preference, host, addresses)?);
            }
            if exchanges.is_empty() {
                return Ok(Resolution::new(
                    ResolutionKind::NoMailRoute,
                    Vec::new(),
                    valid_for,
                ));
            }
            if address_lookup_failed
                && exchanges
                    .iter()
                    .all(|exchange| exchange.addresses().is_empty())
            {
                return Err(ResolveError::new(
                    ResolveErrorKind::Unavailable,
                    "mail exchanger addresses could not be resolved",
                ));
            }
            if address_lookup_failed {
                valid_for = minimum_lifetime(valid_for, Some(Duration::from_secs(60)));
            }
            Ok(Resolution::new(ResolutionKind::Mx, exchanges, valid_for))
        }
        Err(error) if error.is_nx_domain() => Ok(Resolution::new(
            ResolutionKind::NxDomain,
            Vec::new(),
            negative_lifetime(&error),
        )),
        Err(error) if error.is_no_records_found() => {
            match resolver.lookup_ip(query.as_str()).await {
                Ok(addresses) => {
                    let valid_for = lookup_lifetime(addresses.valid_until());
                    let addresses = addresses.iter().collect::<Vec<IpAddr>>();
                    if addresses.is_empty() {
                        Ok(Resolution::new(
                            ResolutionKind::NoMailRoute,
                            Vec::new(),
                            valid_for,
                        ))
                    } else {
                        Ok(Resolution::new(
                            ResolutionKind::ImplicitMx,
                            vec![MailExchange::new(0, domain, addresses)?],
                            valid_for,
                        ))
                    }
                }
                Err(fallback) if fallback.is_nx_domain() => Ok(Resolution::new(
                    ResolutionKind::NxDomain,
                    Vec::new(),
                    negative_lifetime(&fallback),
                )),
                Err(fallback) if fallback.is_no_records_found() => Ok(Resolution::new(
                    ResolutionKind::NoMailRoute,
                    Vec::new(),
                    negative_lifetime(&fallback),
                )),
                Err(fallback) => Err(map_error(&fallback)),
            }
        }
        Err(error) => Err(map_error(&error)),
    }
}

fn normalize_mail_exchangers(records: &mut Vec<&MX>) -> std::result::Result<bool, ResolveError> {
    if records.len() > MAX_EXCHANGES {
        return Err(ResolveError::new(
            ResolveErrorKind::Protocol,
            "MX response exceeded its resource limit",
        ));
    }
    records.sort_by_key(|record| (record.preference, record.exchange.to_ascii()));
    records.dedup_by(|left, right| {
        left.preference == right.preference && left.exchange == right.exchange
    });
    if records.iter().any(|record| record.exchange.is_root()) {
        if records.len() == 1 && records[0].preference == 0 {
            return Ok(true);
        }
        return Err(ResolveError::new(
            ResolveErrorKind::Protocol,
            "invalid Null MX response",
        ));
    }
    Ok(false)
}

// A mailbox domain is an absolute DNS name. A trailing root label prevents
// operating-system search suffixes from changing a negative public lookup.
fn absolute_name(domain: &str) -> String {
    let mut absolute = String::with_capacity(domain.len() + 1);
    absolute.push_str(domain);
    absolute.push('.');
    absolute
}

fn negative_lifetime(error: &hickory_resolver::net::NetError) -> Option<Duration> {
    match error {
        hickory_resolver::net::NetError::Dns(hickory_resolver::net::DnsError::NoRecordsFound(
            no_records,
        )) => no_records
            .negative_ttl
            .map(|seconds| Duration::from_secs(u64::from(seconds))),
        _ => None,
    }
}

fn lookup_lifetime(valid_until: std::time::Instant) -> Option<Duration> {
    Some(valid_until.saturating_duration_since(std::time::Instant::now()))
}

fn minimum_lifetime(left: Option<Duration>, right: Option<Duration>) -> Option<Duration> {
    match (left, right) {
        (Some(left), Some(right)) => Some(left.min(right)),
        (left, right) => left.or(right),
    }
}

fn map_error(error: &hickory_resolver::net::NetError) -> ResolveError {
    let kind = if matches!(error, hickory_resolver::net::NetError::Timeout) {
        ResolveErrorKind::Timeout
    } else {
        ResolveErrorKind::Unavailable
    };
    ResolveError::new(kind, "DNS lookup did not complete")
}

#[cfg(test)]
mod tests {
    use hickory_resolver::proto::rr::{Name, rdata::MX};

    use super::{MAX_EXCHANGES, ResolveErrorKind, absolute_name, normalize_mail_exchangers};

    #[test]
    fn mailbox_domains_are_queried_from_the_dns_root() {
        assert_eq!(absolute_name("mail.example"), "mail.example.");
    }

    #[test]
    fn duplicate_exchangers_produce_one_route() {
        let exchange = MX::new(10, Name::from_ascii("mx.example.").unwrap());
        let records = vec![exchange; MAX_EXCHANGES];
        let mut records = records.iter().collect();

        assert!(!normalize_mail_exchangers(&mut records).unwrap());
        assert_eq!(records.len(), 1);
    }

    #[test]
    fn excess_unique_exchangers_are_rejected_before_address_lookups() {
        let records = (0..=MAX_EXCHANGES)
            .map(|index| {
                MX::new(
                    index as u16,
                    Name::from_ascii(format!("mx-{index}.example.")).unwrap(),
                )
            })
            .collect::<Vec<_>>();
        let mut records = records.iter().collect();

        let error = normalize_mail_exchangers(&mut records).unwrap_err();

        assert_eq!(error.kind(), ResolveErrorKind::Protocol);
    }

    #[test]
    fn null_mx_cannot_be_mixed_with_mail_routes() {
        let records = [
            MX::new(0, Name::root()),
            MX::new(10, Name::from_ascii("mx.example.").unwrap()),
        ];
        let mut records = records.iter().collect();

        let error = normalize_mail_exchangers(&mut records).unwrap_err();

        assert_eq!(error.kind(), ResolveErrorKind::Protocol);
    }
}