pata 0.0.1

A fast, lightweight, and evidence-driven email validation library for Rust
Documentation
//! Optional receiving-domain security posture.

use crate::{
    Certainty, Finding, FindingCode, Network, Outcome,
    dns::{ResolveError, TextRecords},
};

/// Publication state of one recognizable domain-security record.
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub enum RecordStatus {
    /// Exactly one recognizable record is present.
    Present,
    /// No recognizable record is present.
    Absent,
    /// Multiple recognizable records are present.
    Invalid,
    /// The DNS operation did not return a result.
    Unavailable,
}

/// Receiving-domain SPF, DMARC, MTA-STS, and TLS-RPT observations.
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct DomainPosture {
    spf: RecordStatus,
    dmarc: RecordStatus,
    mta_sts: RecordStatus,
    tls_rpt: RecordStatus,
}

impl DomainPosture {
    pub(crate) const fn unavailable() -> Self {
        Self {
            spf: RecordStatus::Unavailable,
            dmarc: RecordStatus::Unavailable,
            mta_sts: RecordStatus::Unavailable,
            tls_rpt: RecordStatus::Unavailable,
        }
    }

    /// Returns the SPF publication status.
    #[must_use]
    pub const fn spf(self) -> RecordStatus {
        self.spf
    }

    /// Returns the DMARC publication status.
    #[must_use]
    pub const fn dmarc(self) -> RecordStatus {
        self.dmarc
    }

    /// Returns the MTA-STS publication status.
    #[must_use]
    pub const fn mta_sts(self) -> RecordStatus {
        self.mta_sts
    }

    /// Returns the SMTP TLS reporting publication status.
    #[must_use]
    pub const fn tls_rpt(self) -> RecordStatus {
        self.tls_rpt
    }
}

pub(crate) async fn inspect(
    network: &Network,
    domain: &str,
    timeout: std::time::Duration,
) -> DomainPosture {
    let dmarc_name = format!("_dmarc.{domain}");
    let mta_sts_name = format!("_mta-sts.{domain}");
    let tls_rpt_name = format!("_smtp._tls.{domain}");
    let (spf, dmarc, mta_sts, tls_rpt) = futures_util::join!(
        resolve_text(network, domain, timeout),
        resolve_text(network, &dmarc_name, timeout),
        resolve_text(network, &mta_sts_name, timeout),
        resolve_text(network, &tls_rpt_name, timeout),
    );
    DomainPosture {
        spf: record(spf, "v=spf1"),
        dmarc: record(dmarc, "v=dmarc1"),
        mta_sts: record(mta_sts, "v=stsv1"),
        tls_rpt: record(tls_rpt, "v=tlsrptv1"),
    }
}

async fn resolve_text(
    network: &Network,
    domain: &str,
    duration: std::time::Duration,
) -> Result<TextRecords, ResolveError> {
    crate::runtime::timeout(
        network.timer(),
        duration,
        network.resolver().resolve_text(domain),
    )
    .await
    .unwrap_or_else(|_| {
        Err(ResolveError::new(
            crate::dns::ResolveErrorKind::Timeout,
            "TXT lookup exceeded its deadline",
        ))
    })
}

pub(crate) fn findings(posture: DomainPosture) -> impl Iterator<Item = Finding> {
    [
        posture_finding(FindingCode::PostureSpf, "SPF", posture.spf),
        posture_finding(FindingCode::PostureDmarc, "DMARC", posture.dmarc),
        posture_finding(FindingCode::PostureMtaSts, "MTA-STS", posture.mta_sts),
        posture_finding(FindingCode::PostureTlsRpt, "TLS-RPT", posture.tls_rpt),
    ]
    .into_iter()
    .flatten()
}

fn record(result: Result<TextRecords, ResolveError>, prefix: &str) -> RecordStatus {
    let Ok(records) = result else {
        return RecordStatus::Unavailable;
    };
    let matching = records
        .values()
        .iter()
        .filter(|value| has_version(value, prefix))
        .count();
    match matching {
        0 => RecordStatus::Absent,
        1 => RecordStatus::Present,
        _ => RecordStatus::Invalid,
    }
}

fn has_version(value: &str, version: &str) -> bool {
    let Some((candidate, suffix)) = value.split_at_checked(version.len()) else {
        return false;
    };
    candidate.eq_ignore_ascii_case(version)
        && (suffix.is_empty()
            || suffix
                .as_bytes()
                .first()
                .is_some_and(|byte| matches!(byte, b' ' | b'\t' | b';')))
}

fn posture_finding(code: FindingCode, name: &'static str, status: RecordStatus) -> Option<Finding> {
    match (name, status) {
        (_, RecordStatus::Absent | RecordStatus::Unavailable) => None,
        ("SPF", RecordStatus::Present) => Some(Finding::new(
            code,
            Outcome::Pass,
            Certainty::Conclusive,
            "the domain publishes an SPF record",
        )),
        ("DMARC", RecordStatus::Present) => Some(Finding::new(
            code,
            Outcome::Pass,
            Certainty::Conclusive,
            "the domain publishes a DMARC record",
        )),
        ("MTA-STS", RecordStatus::Present) => Some(Finding::new(
            code,
            Outcome::Pass,
            Certainty::Conclusive,
            "the domain publishes an MTA-STS record",
        )),
        ("TLS-RPT", RecordStatus::Present) => Some(Finding::new(
            code,
            Outcome::Pass,
            Certainty::Conclusive,
            "the domain publishes an SMTP TLS reporting record",
        )),
        (_, RecordStatus::Invalid) => Some(Finding::new(
            code,
            Outcome::Warning,
            Certainty::Conclusive,
            "the domain publishes multiple recognizable security records",
        )),
        _ => None,
    }
}

#[cfg(test)]
mod tests {
    use futures_executor::block_on;

    use super::*;

    #[test]
    fn duplicate_policy_records_are_invalid() {
        let status = record(
            TextRecords::new(
                vec!["v=DMARC1; p=none".into(), "v=DMARC1; p=reject".into()],
                None,
            ),
            "v=dmarc1",
        );

        assert_eq!(status, RecordStatus::Invalid);
    }

    #[test]
    fn identical_policy_records_remain_invalid() {
        let status = record(
            TextRecords::new(
                vec!["v=DMARC1; p=reject".into(), "v=DMARC1; p=reject".into()],
                None,
            ),
            "v=dmarc1",
        );

        assert_eq!(status, RecordStatus::Invalid);
    }

    #[test]
    fn near_match_is_not_a_security_record() {
        let status = record(
            TextRecords::new(vec!["v=spf10 include:example.com".into()], None),
            "v=spf1",
        );

        assert_eq!(status, RecordStatus::Absent);
    }

    #[test]
    fn version_tag_must_start_the_record() {
        let status = record(
            TextRecords::new(vec![" v=DMARC1; p=reject".into()], None),
            "v=dmarc1",
        );

        assert_eq!(status, RecordStatus::Absent);
    }

    #[test]
    fn text_lookups_obey_the_dns_deadline() {
        struct StalledResolver;
        impl crate::dns::Resolver for StalledResolver {
            fn resolve(&self, _domain: &str) -> crate::dns::Resolve<'_> {
                Box::pin(std::future::pending())
            }

            fn resolve_text(&self, _domain: &str) -> crate::dns::ResolveText<'_> {
                Box::pin(std::future::pending())
            }
        }
        struct ImmediateTimer;
        impl crate::runtime::Timer for ImmediateTimer {
            fn sleep(&self, _duration: std::time::Duration) -> crate::runtime::Sleep {
                Box::pin(std::future::ready(()))
            }
        }
        let network = Network::new(StalledResolver, ImmediateTimer);

        let posture = block_on(inspect(
            &network,
            "example.com",
            std::time::Duration::from_secs(1),
        ));

        assert_eq!(posture.spf(), RecordStatus::Unavailable);
        assert_eq!(posture.dmarc(), RecordStatus::Unavailable);
        assert_eq!(posture.mta_sts(), RecordStatus::Unavailable);
        assert_eq!(posture.tls_rpt(), RecordStatus::Unavailable);
    }
}