didbot_dns/

lib.rs

//! DNS providers for the records a deployment writes into its own zone.
//!
//! Every agent gets its own hostname, because atproto supports "only
//! hostname-level `did:web` DIDs". Those hostnames resolve through one
//! wildcard record the deployment's zone holds (`terraform-aws-didbot-pds/route53.tf`), so
//! minting an account writes nothing here — see `docs/names.md`. What a
//! deployment does write is the pair of records a wildcard cannot stand in
//! for: the `TXT` values an ACME DNS-01 challenge places at
//! `_acme-challenge.<zone>`, and the `CAA` record at the apex that says which
//! authority and which account may issue for the zone.
//!
//! The trait is deliberately small and synchronous. A write here is a rare,
//! coarse-grained operation on the certificate path, so nothing needs a
//! runtime; a provider that talks to a hosted DNS API blocks on its own
//! client without pushing an async runtime into every consumer.
//!
//! [`InMemoryDns`] is the test double and the model of what a real provider's
//! bookkeeping looks like. `route53::Route53Dns` drives a real hosted zone
//! and is the backend this server runs in production, behind the `route53`
//! feature so a build that does not need it does not pay for it. A provider
//! that drives some other authoritative zone — a different hosted DNS API, a
//! zone file, `nsupdate` — implements the same trait and slots in without a
//! caller change.
//!
//! [`DnsProvider::publish_txt`], [`DnsProvider::withdraw_txt`] and
//! [`DnsProvider::txt_values`] are an additive API over a set: the ACME
//! DNS-01 challenge for a certificate covering both a name and its wildcard
//! requires two values at one name simultaneously, and that is a set to add
//! to and remove from, not a single slot to overwrite.
//! [`DnsProvider::publish_caa`] is the opposite, a replacement: a zone's
//! issuance policy is one statement with one writer.

#![forbid(unsafe_code)]

use std::collections::BTreeMap;
use std::fmt;
use std::sync::Mutex;

#[cfg(feature = "aws-fake")]
pub mod aws_fake;
#[cfg(feature = "route53")]
pub mod route53;

/// One `CAA` property: RFC 8659's flags, tag and value.
///
/// A `CAA` record set is a statement about which certificate authority may
/// issue for a name and everything under it. It is not a defence against
/// whoever holds this zone's credential — that holder can rewrite this record
/// as easily as any other. What it does is narrow issuance to one authority
/// and one account at that authority, so a certificate for a name in this
/// zone cannot be obtained through any other path that does not first change
/// this record; and changing it is a second, separately visible act.
///
/// Only `issue` and `iodef` are constructed here. `issuewild` is deliberately
/// absent: RFC 8659 says a wildcard request falls back to `issue` when no
/// `issuewild` is present, and this deployment's certificate covers a zone
/// and its wildcard from one order through one account, so a second property
/// could only ever say the same thing or disagree with it.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub struct CaaValue {
    /// RFC 8659 flags octet. `0` for every property this crate writes: the
    /// critical bit tells a certificate authority to refuse issuance rather
    /// than ignore a property it does not understand, and `issue` and `iodef`
    /// are understood everywhere.
    pub flags: u8,
    /// The property tag: `issue` or `iodef`.
    pub tag: String,
    /// The property value, unquoted.
    pub value: String,
}

impl CaaValue {
    /// `issue`, authorising `issuer` — a domain name such as
    /// `letsencrypt.org` — and no one else.
    pub fn issue(issuer: impl Into<String>) -> Self {
        Self {
            flags: 0,
            tag: "issue".to_string(),
            value: issuer.into(),
        }
    }

    /// `issue` with RFC 8657's `accounturi` parameter, authorising `issuer`
    /// only when the request comes from the ACME account at `account_uri`.
    ///
    /// This is the half that matters. `issue "letsencrypt.org"` alone
    /// authorises anyone who can create an account at that authority, which
    /// is anyone; naming the account narrows it to the one this deployment
    /// holds the key for. An authority that does not implement RFC 8657
    /// ignores the parameter and enforces the issuer name only, which is
    /// what makes publishing it safe against an authority that has not
    /// caught up.
    pub fn issue_for_account(issuer: impl AsRef<str>, account_uri: impl AsRef<str>) -> Self {
        Self::issue(format!(
            "{}; accounturi={}",
            issuer.as_ref(),
            account_uri.as_ref()
        ))
    }

    /// `iodef`, naming where a certificate authority should report a request
    /// this record made it refuse.
    ///
    /// A refused issuance is the signal that someone tried to obtain a
    /// certificate for this zone through an account that is not ours, and it
    /// arrives from the authority rather than from this host — which is the
    /// point, since a host holding the zone credential cannot be trusted to
    /// report on its own misuse.
    pub fn iodef(target: impl Into<String>) -> Self {
        Self {
            flags: 0,
            tag: "iodef".to_string(),
            value: target.into(),
        }
    }

    /// The record's wire form: `<flags> <tag> "<value>"`, with `"` and `\`
    /// escaped inside the quoted value.
    pub fn to_wire(&self) -> String {
        let escaped = self.value.replace('\\', "\\\\").replace('"', "\\\"");
        format!("{} {} \"{}\"", self.flags, self.tag, escaped)
    }
}

impl fmt::Display for CaaValue {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.to_wire())
    }
}

/// Why a record could not be published or withdrawn.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum DnsError {
    /// The host is not one this provider is allowed to write.
    ///
    /// A provider is scoped to a zone, and a request outside it is a
    /// configuration error, not a routing decision. Refusing loudly is the
    /// point: the alternative is a provider that quietly does nothing while
    /// the caller believes a challenge value is in place.
    #[error("host {host:?} is not under this provider's zone")]
    NotUnderZone {
        /// The host that was refused.
        host: String,
    },
    /// Nothing was published for this host, so there is nothing to withdraw.
    #[error("no record is published for {host:?}")]
    NotPublished {
        /// The host that was absent.
        host: String,
    },
    /// The provider's own request failed for a reason that is not zone
    /// containment — a network error, a malformed response, or exhausting a
    /// retry budget against a rate limit.
    #[error("dns provider error for {host:?}: {message}")]
    Backend {
        /// The host the failing request was for.
        host: String,
        /// What the provider said went wrong.
        message: String,
    },
}

/// A zone the records a certificate depends on can be written into.
///
/// Implementations must be safe to share: the certificate manager holds one
/// behind a shared reference for the life of the process and calls it from
/// whatever task a renewal runs on.
pub trait DnsProvider: Send + Sync {
    /// Short stable identifier for this provider, used in log fields.
    fn name(&self) -> &str;

    /// Adds `value` to the set of `TXT` values published at `host`, leaving
    /// any other values at that name untouched.
    ///
    /// A `TXT` name used for the ACME DNS-01 challenge holds a set: issuing
    /// one certificate that covers both `pds.example` and `*.pds.example`
    /// requires two simultaneous values at `_acme-challenge.pds.example`,
    /// one per name being validated, and a provider that cannot hold both
    /// cannot issue that certificate. Calling this twice with the same
    /// `value` is a no-op, not a collision: a retried challenge publish must
    /// not fail.
    ///
    /// Returns once the value is visible to a resolver, on a backend that can
    /// tell: the caller's next step is to ask the authority to look.
    fn publish_txt(&self, host: &str, value: &str) -> Result<(), DnsError>;

    /// Removes one `TXT` value at `host`, leaving any other values at that
    /// name untouched.
    ///
    /// Removing the last value at a name removes the name; removing a value
    /// that was never published, or a value that has already been withdrawn,
    /// fails with [`DnsError::NotPublished`].
    fn withdraw_txt(&self, host: &str, value: &str) -> Result<(), DnsError>;

    /// Every `TXT` value currently published at `host`, sorted.
    ///
    /// Empty, not an error, when nothing is published there — checking is a
    /// read, and an empty set is a legitimate answer to it. Sorted so that a
    /// test or an operator comparing two listings sees a difference only
    /// when the set actually differs.
    fn txt_values(&self, host: &str) -> Vec<String>;

    /// Replaces the `CAA` record set at `host` with exactly `values`,
    /// removing the record entirely when `values` is empty.
    ///
    /// An upsert, deliberately not [`DnsProvider::publish_txt`]'s additive
    /// rule. Adding to a `CAA` set widens who may issue; the operation this
    /// needs is "authorise these and nobody else", which only a replacement
    /// gives. A zone's issuance policy is one statement with one writer,
    /// restated on every start from the account and authority the process is
    /// actually about to order through; a provider that refused to restate
    /// it could never correct a stale one, and a stale `CAA` naming an
    /// account this deployment no longer holds is an outage on the next
    /// renewal rather than a safe default.
    ///
    /// `CAA` lives at the zone apex, beside the address record for the server
    /// itself. The two do not collide: they are different record types at one
    /// name rather than two answers to one question.
    fn publish_caa(&self, host: &str, values: &[CaaValue]) -> Result<(), DnsError>;

    /// Every `CAA` value currently published at `host`, sorted.
    ///
    /// Empty, not an error, when nothing is published there — the same
    /// reasoning [`DnsProvider::txt_values`] documents.
    fn caa_values(&self, host: &str) -> Vec<CaaValue>;
}

/// A boxed provider is a provider.
///
/// A caller that picks its backend at runtime needs one concrete type every
/// arm produces. `Box<dyn DnsProvider>` is that type, and this impl is what
/// lets it stand in for a generic parameter instead of the caller writing an
/// enum with one variant per backend.
impl DnsProvider for Box<dyn DnsProvider> {
    fn name(&self) -> &str {
        (**self).name()
    }

    fn publish_txt(&self, host: &str, value: &str) -> Result<(), DnsError> {
        (**self).publish_txt(host, value)
    }

    fn withdraw_txt(&self, host: &str, value: &str) -> Result<(), DnsError> {
        (**self).withdraw_txt(host, value)
    }

    fn txt_values(&self, host: &str) -> Vec<String> {
        (**self).txt_values(host)
    }

    fn publish_caa(&self, host: &str, values: &[CaaValue]) -> Result<(), DnsError> {
        (**self).publish_caa(host, values)
    }

    fn caa_values(&self, host: &str) -> Vec<CaaValue> {
        (**self).caa_values(host)
    }
}

/// A shared provider is a provider.
///
/// One provider instance, held in more than one place at once: the
/// certificate manager for a zone and a test that inspects what it wrote
/// look at the same maps. `Box<dyn DnsProvider>` cannot be shared, so this
/// is the form that case takes. Generic over `T` rather than written for
/// `Arc<dyn DnsProvider>` alone, so that a caller keeping a concrete
/// provider can hand the same `Arc` to something that wants only the trait.
impl<T: DnsProvider + ?Sized> DnsProvider for std::sync::Arc<T> {
    fn name(&self) -> &str {
        (**self).name()
    }

    fn publish_txt(&self, host: &str, value: &str) -> Result<(), DnsError> {
        (**self).publish_txt(host, value)
    }

    fn withdraw_txt(&self, host: &str, value: &str) -> Result<(), DnsError> {
        (**self).withdraw_txt(host, value)
    }

    fn txt_values(&self, host: &str) -> Vec<String> {
        (**self).txt_values(host)
    }

    fn publish_caa(&self, host: &str, values: &[CaaValue]) -> Result<(), DnsError> {
        (**self).publish_caa(host, values)
    }

    fn caa_values(&self, host: &str) -> Vec<CaaValue> {
        (**self).caa_values(host)
    }
}

/// Folds `host` to the form every bookkeeping map keys on.
///
/// RFC 1035 3.1 makes DNS name comparison case-insensitive: `A.example` and
/// `a.example` are one name. Every map in this module is keyed on the
/// lowercased spelling so that two spellings of one host read and write one
/// entry, instead of each believing the other's values are not there.
fn normalize_host(host: &str) -> String {
    host.to_ascii_lowercase()
}

/// Shared multi-value `TXT` bookkeeping.
///
/// A second, third or fourth value at one name is the entire point (see
/// [`DnsProvider::publish_txt`]), so nothing here refuses a write. A
/// `BTreeSet` inside a `BTreeMap` because [`DnsProvider::txt_values`]
/// promises sorted output and a sorted container gives it for free.
#[derive(Debug, Default)]
struct TxtRecords(Mutex<BTreeMap<String, std::collections::BTreeSet<String>>>);

impl TxtRecords {
    /// Takes the lock, recovering from a poisoned mutex.
    ///
    /// A panic while holding this lock cannot leave the map inconsistent —
    /// every write under it is a single map operation — so the data is still
    /// good and refusing to serve it would turn one unrelated panic into a
    /// permanently broken provider.
    fn map(
        &self,
    ) -> std::sync::MutexGuard<'_, BTreeMap<String, std::collections::BTreeSet<String>>> {
        self.0
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
    }

    /// Adds `value` at `host`. Returns whether it was newly added, so a
    /// caller can skip a redundant network write on a retried publish.
    fn insert(&self, host: &str, value: &str) -> bool {
        self.map()
            .entry(normalize_host(host))
            .or_default()
            .insert(value.to_owned())
    }

    /// Removes `value` at `host`. Cleans up the name entirely once its last
    /// value is gone, so an empty set never lingers as a false positive in
    /// [`Self::values`].
    fn remove(&self, host: &str, value: &str) -> Result<(), DnsError> {
        let mut map = self.map();
        let key = normalize_host(host);
        let Some(values) = map.get_mut(&key) else {
            return Err(DnsError::NotPublished {
                host: host.to_owned(),
            });
        };
        if !values.remove(value) {
            return Err(DnsError::NotPublished {
                host: host.to_owned(),
            });
        }
        if values.is_empty() {
            map.remove(&key);
        }
        Ok(())
    }

    fn values(&self, host: &str) -> Vec<String> {
        self.map()
            .get(&normalize_host(host))
            .map(|values| values.iter().cloned().collect())
            .unwrap_or_default()
    }
}

/// Shared `CAA` bookkeeping.
///
/// Not [`TxtRecords`], whose insert is additive; this one replaces, for the
/// reason [`DnsProvider::publish_caa`] gives.
#[derive(Debug, Default)]
struct CaaRecords(Mutex<BTreeMap<String, Vec<CaaValue>>>);

impl CaaRecords {
    /// Takes the lock, recovering from a poisoned mutex; see
    /// [`TxtRecords::map`] for why that is safe here too.
    fn map(&self) -> std::sync::MutexGuard<'_, BTreeMap<String, Vec<CaaValue>>> {
        self.0
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
    }

    /// Sets the set at `host` to `values`, or removes the name when `values`
    /// is empty. Returns whether anything changed, so a caller can skip a
    /// redundant network write when a restart restates what is already there.
    fn replace(&self, host: &str, values: &[CaaValue]) -> bool {
        let mut sorted = values.to_vec();
        sorted.sort();
        sorted.dedup();
        let key = normalize_host(host);
        let mut map = self.map();
        if sorted.is_empty() {
            return map.remove(&key).is_some();
        }
        match map.get(&key) {
            Some(existing) if *existing == sorted => false,
            _ => {
                map.insert(key, sorted);
                true
            }
        }
    }

    fn values(&self, host: &str) -> Vec<CaaValue> {
        self.map()
            .get(&normalize_host(host))
            .cloned()
            .unwrap_or_default()
    }
}

/// A provider that records everything and admits any hostname.
///
/// The test double for callers that want to assert on what a certificate
/// order asked for without also asserting on zone rules. It has no zone, so
/// it never returns [`DnsError::NotUnderZone`].
#[derive(Debug, Default)]
pub struct InMemoryDns {
    txt: TxtRecords,
    caa: CaaRecords,
}

impl InMemoryDns {
    /// A provider with nothing published.
    pub fn new() -> Self {
        Self::default()
    }
}

impl DnsProvider for InMemoryDns {
    fn name(&self) -> &str {
        "in-memory"
    }

    fn publish_txt(&self, host: &str, value: &str) -> Result<(), DnsError> {
        if self.txt.insert(host, value) {
            tracing::info!(
                provider = self.name(),
                host = host,
                value = value,
                "published txt value"
            );
        }
        Ok(())
    }

    fn withdraw_txt(&self, host: &str, value: &str) -> Result<(), DnsError> {
        self.txt.remove(host, value)?;
        tracing::info!(
            provider = self.name(),
            host = host,
            value = value,
            "withdrew txt value"
        );
        Ok(())
    }

    fn txt_values(&self, host: &str) -> Vec<String> {
        self.txt.values(host)
    }

    fn publish_caa(&self, host: &str, values: &[CaaValue]) -> Result<(), DnsError> {
        if self.caa.replace(host, values) {
            log_caa(self.name(), host, values, "published caa record set");
        }
        Ok(())
    }

    fn caa_values(&self, host: &str) -> Vec<CaaValue> {
        self.caa.values(host)
    }
}

/// Renders a `CAA` set for one log line, so an operator reading the log sees
/// the policy that was written rather than a count of properties.
fn log_caa(provider: &str, host: &str, values: &[CaaValue], message: &'static str) {
    let rendered = values
        .iter()
        .map(CaaValue::to_wire)
        .collect::<Vec<_>>()
        .join(" | ");
    tracing::info!(
        provider = provider,
        host = host,
        caa = rendered.as_str(),
        "{message}"
    );
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_caa_set_names_the_issuer_and_the_account() {
        let value = CaaValue::issue_for_account(
            "letsencrypt.org",
            "https://acme-v02.api.letsencrypt.org/acme/acct/1",
        );
        assert_eq!(
            value.to_wire(),
            "0 issue \"letsencrypt.org; accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/1\""
        );
        assert_eq!(
            CaaValue::iodef("mailto:ops@example.com").to_wire(),
            "0 iodef \"mailto:ops@example.com\""
        );
    }

    #[test]
    fn caa_replaces_the_whole_set_rather_than_adding_to_it() {
        let dns = InMemoryDns::new();
        assert!(dns
            .publish_caa("example", &[CaaValue::issue("one.example")])
            .is_ok());
        assert!(dns
            .publish_caa("example", &[CaaValue::issue("two.example")])
            .is_ok());
        // Not both: a set that only ever grows widens who may issue, which
        // is the opposite of what publishing this record is for.
        assert_eq!(
            dns.caa_values("example"),
            vec![CaaValue::issue("two.example")]
        );

        assert!(dns.publish_caa("example", &[]).is_ok());
        assert!(dns.caa_values("example").is_empty());
    }

    #[test]
    fn txt_values_are_additive_not_exclusive() {
        // The case this API exists for: a certificate over both `pds.example`
        // and `*.pds.example` needs two simultaneous values at
        // `_acme-challenge.pds.example`, and a second publish must not
        // clobber the first.
        let dns = InMemoryDns::new();
        let name = "_acme-challenge.pds.example";
        assert!(dns.publish_txt(name, "token-for-apex").is_ok());
        assert!(dns.publish_txt(name, "token-for-wildcard").is_ok());
        assert_eq!(
            dns.txt_values(name),
            vec!["token-for-apex", "token-for-wildcard"]
        );
    }

    #[test]
    fn publishing_the_same_txt_value_twice_is_a_no_op() {
        let dns = InMemoryDns::new();
        assert!(dns.publish_txt("a.example", "tok").is_ok());
        assert!(dns.publish_txt("a.example", "tok").is_ok());
        assert_eq!(dns.txt_values("a.example"), vec!["tok"]);
    }

    #[test]
    fn withdrawing_one_txt_value_leaves_the_others() {
        let dns = InMemoryDns::new();
        assert!(dns.publish_txt("a.example", "one").is_ok());
        assert!(dns.publish_txt("a.example", "two").is_ok());
        assert!(dns.withdraw_txt("a.example", "one").is_ok());
        assert_eq!(dns.txt_values("a.example"), vec!["two"]);
    }

    #[test]
    fn withdrawing_the_last_txt_value_clears_the_name() {
        let dns = InMemoryDns::new();
        assert!(dns.publish_txt("a.example", "only").is_ok());
        assert!(dns.withdraw_txt("a.example", "only").is_ok());
        assert!(dns.txt_values("a.example").is_empty());
    }

    #[test]
    fn withdrawing_an_absent_txt_value_is_not_published() {
        let dns = InMemoryDns::new();
        assert_eq!(
            dns.withdraw_txt("a.example", "never-published"),
            Err(DnsError::NotPublished {
                host: "a.example".to_string()
            })
        );
        assert!(dns.publish_txt("a.example", "one").is_ok());
        assert_eq!(
            dns.withdraw_txt("a.example", "not-this-one"),
            Err(DnsError::NotPublished {
                host: "a.example".to_string()
            })
        );
    }

    #[test]
    fn missing_txt_values_are_an_empty_read_not_an_error() {
        let dns = InMemoryDns::new();
        assert!(dns.txt_values("never.example").is_empty());
    }

    #[test]
    fn providers_are_usable_behind_a_trait_object() {
        let dns: Box<dyn DnsProvider> = Box::new(InMemoryDns::new());
        assert!(dns
            .publish_txt("_acme-challenge.a.localhost", "tok")
            .is_ok());
        assert_eq!(dns.txt_values("_acme-challenge.a.localhost"), vec!["tok"]);
        assert_eq!(dns.name(), "in-memory");
    }
}