didbot_tls/

dns.rs

//! The DNS-01 seam.
//!
//! A certificate that covers both `<zone>` and `*.<zone>` needs two ACME
//! authorizations — one per identifier — and RFC 8555 §8.4 puts both
//! challenges' answers at the *same* DNS name: `_acme-challenge.<zone>`. The
//! two values must be published together and both must be visible when the
//! CA checks, so this is not "publish, then overwrite" — it is "publish a
//! set of values at one name, then withdraw all of them together."
//!
//! `didbot_dns::DnsProvider`'s `publish_txt`/`withdraw_txt`/`txt_values`
//! are the multi-value API a challenge name needs: additive per value, and
//! idempotent for a value already there.
//!
//! This module does not fork a second DNS client to use them; instead
//! [`AcmeDnsChallenge`] states exactly what ACME's DNS-01 step
//! needs — nothing more — and [`DnsProviderAdapter`] is the thin join: it
//! diffs the value set a challenge asks for against what
//! `didbot_dns::DnsProvider::txt_values` already has published at that
//! name, and issues one `publish_txt`/`withdraw_txt` call per value that
//! needs to change, so a retried publish for values already there is a
//! no-op and a withdraw of a value someone else already cleared is not an
//! error. Any `DnsProvider` — `Route53Dns` in production, `InMemoryDns` in
//! a test — becomes an `AcmeDnsChallenge` this way with no new network
//! code. [`InMemoryAcmeDns`] remains this crate's own hand-rolled double,
//! kept because it models the set-per-name bookkeeping independently of
//! `didbot-dns`'s, which is what makes it useful as a check on
//! `DnsProviderAdapter` rather than a copy of what it wraps.

//! The same seam carries [`AcmeDnsChallenge::authorize_issuer`], which is
//! about the zone rather than about one order: the `CAA` record saying which
//! authority, and which account at that authority, may issue for any name in
//! it. It belongs here because both halves of that record — the authority
//! and the account URI — are read off the very objects an order is placed
//! through, and a `CAA` record that disagrees with them is an outage.

use std::collections::{BTreeMap, BTreeSet};
use std::sync::{Arc, Mutex};

use didbot_dns::{CaaValue, DnsError, DnsProvider};

/// Why a challenge value could not be published or withdrawn.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum AcmeDnsError {
    /// The backend refused the name, request, or credential.
    #[error("could not publish the challenge at {name:?}: {reason}")]
    Publish {
        /// The `_acme-challenge.<zone>` name that was refused.
        name: String,
        /// What the backend said.
        reason: String,
    },
    /// The backend could not withdraw a previously published set.
    #[error("could not withdraw the challenge at {name:?}: {reason}")]
    Withdraw {
        /// The `_acme-challenge.<zone>` name that could not be cleared.
        name: String,
        /// What the backend said.
        reason: String,
    },
}

/// Who may issue certificates for a zone: one authority, one account at it,
/// and where that authority should report a request it refused.
///
/// Every field is read off the live ACME objects an order is about to be
/// placed through, never from configuration. A `CAA` record naming an
/// authority or an account this deployment cannot actually use does not fail
/// safe — it stops the next renewal, and an expired certificate is a total
/// outage for every hostname in the zone, agents included. Deriving both
/// halves from the same objects is what makes that failure unreachable.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct IssuancePolicy {
    /// The authority's domain, for RFC 8659's `issue` property.
    pub issuer: String,
    /// The ACME account URL, for RFC 8657's `accounturi` parameter.
    pub account_uri: String,
    /// Where an authority should report an issuance this record refused, for
    /// RFC 8659's `iodef` property. Empty is legitimate: a deployment with no
    /// contact still gets the refusal, it just does not hear about it.
    pub report_to: Vec<String>,
}

impl IssuancePolicy {
    /// The `CAA` value set this policy publishes.
    ///
    /// No `issuewild`. RFC 8659 falls back to `issue` for a wildcard request
    /// when no `issuewild` is present, and this deployment covers a zone and
    /// its wildcard from one order through one account — so a second property
    /// could only restate this one or contradict it.
    pub fn caa_values(&self) -> Vec<CaaValue> {
        let mut values = vec![CaaValue::issue_for_account(&self.issuer, &self.account_uri)];
        values.extend(self.report_to.iter().map(CaaValue::iodef));
        values
    }
}

/// What ACME's DNS-01 step needs from a DNS backend, and nothing more.
///
/// `name` is always a full `_acme-challenge.<host>` name; this trait does not
/// prepend the label, because the caller is the one that knows how many
/// identifiers share it. `values` is the complete set that must be visible at
/// once — a wildcard-plus-apex order asks for two — and a real
/// implementation must publish all of them as one operation's worth of
/// records, not a sequence of single-value writes that a resolver could catch
/// mid-update.
pub trait AcmeDnsChallenge: Send + Sync {
    /// Publishes exactly `values` as TXT records at `name`, replacing
    /// whatever this backend had published there before.
    ///
    /// Idempotent by design: a renewal that retries after a partial failure
    /// must be able to call this again with the same or a refreshed value
    /// set without first working out what is already there.
    fn publish_challenge(&self, name: &str, values: &[String]) -> Result<(), AcmeDnsError>;

    /// Removes every value published at `name`.
    ///
    /// Called once the order no longer needs the challenge, whether it
    /// succeeded or failed — a stale challenge TXT record is not harmful the
    /// way a stale `did:web` record is, but it is a leftover nobody should
    /// have to notice and clean up by hand.
    fn clear_challenge(&self, name: &str) -> Result<(), AcmeDnsError>;

    /// Publishes `policy` as the `CAA` record set at `zone`, replacing
    /// whatever was there.
    ///
    /// Called at every start, before the first order, so the record always
    /// names the account the process is about to use. There is no method to
    /// remove it: a zone with no `CAA` record authorises every authority,
    /// which is the state this exists to leave.
    ///
    /// This is not a defence against whoever holds the credential that writes
    /// it — that holder can rewrite this record along with everything else in
    /// the zone. It narrows issuance to one account, so obtaining a
    /// certificate for a name here by any other route requires changing this
    /// record first, and it points refusals at a contact the authority
    /// reaches directly rather than through this host.
    fn authorize_issuer(&self, zone: &str, policy: &IssuancePolicy) -> Result<(), AcmeDnsError>;
}

/// The in-memory double: what this crate's own tests use, and a model for a
/// production implementation's bookkeeping.
///
/// Deliberately not wired to `didbot-dns`'s `InMemoryDns`: this one holds a
/// whole set per name and replaces it, so it checks [`DnsProviderAdapter`]'s
/// diff-per-value join from outside rather than sharing its bookkeeping.
#[derive(Debug, Default)]
pub struct InMemoryAcmeDns {
    published: Mutex<BTreeMap<String, Vec<String>>>,
    caa: Mutex<BTreeMap<String, IssuancePolicy>>,
}

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

    /// The values currently published at `name`, if any.
    pub fn values(&self, name: &str) -> Option<Vec<String>> {
        self.published
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
            .get(name)
            .cloned()
    }
}

impl AcmeDnsChallenge for InMemoryAcmeDns {
    fn publish_challenge(&self, name: &str, values: &[String]) -> Result<(), AcmeDnsError> {
        let mut map = self
            .published
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        map.insert(name.to_owned(), values.to_vec());
        tracing::info!(
            name,
            count = values.len(),
            "published acme dns-01 challenge"
        );
        Ok(())
    }

    fn clear_challenge(&self, name: &str) -> Result<(), AcmeDnsError> {
        let mut map = self
            .published
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        map.remove(name);
        tracing::info!(name, "withdrew acme dns-01 challenge");
        Ok(())
    }

    fn authorize_issuer(&self, zone: &str, policy: &IssuancePolicy) -> Result<(), AcmeDnsError> {
        self.caa
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
            .insert(zone.to_owned(), policy.clone());
        tracing::info!(zone, issuer = %policy.issuer, "recorded zone issuance policy");
        Ok(())
    }
}

/// Adapts any [`didbot_dns::DnsProvider`] into an [`AcmeDnsChallenge`].
///
/// See the module docs for why this is safe to be this thin: the provider's
/// own [`DnsProvider::publish_txt`]/[`DnsProvider::withdraw_txt`] are
/// already additive and idempotent per value, so publishing a *set* is just
/// diffing that set against [`DnsProvider::txt_values`] and issuing one call
/// per value that needs to change. Both directions of that diff run to
/// completion (including waiting for propagation, on a backend that does
/// that — see `Route53Dns`) before [`Self::publish_challenge`] or
/// [`Self::clear_challenge`] return, so a caller sequencing several names —
/// as `crate::acme::issue` does — never proceeds to the next step with a
/// change still in flight underneath it.
pub struct DnsProviderAdapter<D> {
    dns: Arc<D>,
}

impl<D: DnsProvider> DnsProviderAdapter<D> {
    /// Wraps `dns` so it can answer ACME's DNS-01 step.
    pub fn new(dns: Arc<D>) -> Self {
        Self { dns }
    }
}

impl<D: DnsProvider> AcmeDnsChallenge for DnsProviderAdapter<D> {
    fn publish_challenge(&self, name: &str, values: &[String]) -> Result<(), AcmeDnsError> {
        let existing: BTreeSet<String> = self.dns.txt_values(name).into_iter().collect();
        let wanted: BTreeSet<String> = values.iter().cloned().collect();

        // Add first, then remove: a caller reading mid-way through this call
        // sees a superset of `wanted`, never a subset of it — the direction
        // that matters, since a missing value is a failed challenge and an
        // extra one briefly still there is not.
        for value in wanted.difference(&existing) {
            self.dns
                .publish_txt(name, value)
                .map_err(|err| publish_error(name, &err))?;
        }
        for value in existing.difference(&wanted) {
            // Already gone by the time we get here — a concurrent caller, or
            // a retried publish that already cleaned it up — is the goal
            // state reached by a different path, not a failure.
            match self.dns.withdraw_txt(name, value) {
                Ok(()) | Err(DnsError::NotPublished { .. }) => {}
                Err(err) => return Err(publish_error(name, &err)),
            }
        }
        Ok(())
    }

    fn authorize_issuer(&self, zone: &str, policy: &IssuancePolicy) -> Result<(), AcmeDnsError> {
        self.dns
            .publish_caa(zone, &policy.caa_values())
            .map_err(|err| publish_error(zone, &err))
    }

    fn clear_challenge(&self, name: &str) -> Result<(), AcmeDnsError> {
        for value in self.dns.txt_values(name) {
            match self.dns.withdraw_txt(name, &value) {
                Ok(()) | Err(DnsError::NotPublished { .. }) => {}
                Err(err) => return Err(withdraw_error(name, &err)),
            }
        }
        Ok(())
    }
}

fn publish_error(name: &str, err: &DnsError) -> AcmeDnsError {
    AcmeDnsError::Publish {
        name: name.to_owned(),
        reason: err.to_string(),
    }
}

fn withdraw_error(name: &str, err: &DnsError) -> AcmeDnsError {
    AcmeDnsError::Withdraw {
        name: name.to_owned(),
        reason: err.to_string(),
    }
}

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

    #[test]
    fn publishes_two_values_at_one_name() {
        let dns = InMemoryAcmeDns::new();
        let name = "_acme-challenge.pds.did.bot";
        dns.publish_challenge(name, &["one".into(), "two".into()])
            .unwrap();
        let values = dns.values(name).unwrap();
        assert_eq!(values, vec!["one".to_string(), "two".to_string()]);
    }

    #[test]
    fn the_caa_set_names_the_account_and_every_contact() {
        let policy = IssuancePolicy {
            issuer: "letsencrypt.org".into(),
            account_uri: "https://acme-v02.api.letsencrypt.org/acme/acct/7".into(),
            report_to: vec!["mailto:ops@example.com".into()],
        };
        let values = policy.caa_values();
        assert_eq!(values.len(), 2);
        assert_eq!(
            values[0].to_wire(),
            "0 issue \"letsencrypt.org; accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/7\""
        );
        assert_eq!(values[1].to_wire(), "0 iodef \"mailto:ops@example.com\"");
        // No issuewild: RFC 8659 falls back to `issue` for a wildcard when
        // none is present, and the wildcard is in the same order.
        assert!(values.iter().all(|v| v.tag != "issuewild"));
    }

    #[test]
    fn authorizing_an_issuer_reaches_the_underlying_zone() {
        let dns = Arc::new(InMemoryDns::new());
        let adapter = DnsProviderAdapter::new(dns.clone());
        let policy = IssuancePolicy {
            issuer: "letsencrypt.org".into(),
            account_uri: "https://acme.example/acct/7".into(),
            report_to: Vec::new(),
        };
        adapter.authorize_issuer("pds.did.bot", &policy).unwrap();
        assert_eq!(dns.caa_values("pds.did.bot"), policy.caa_values());

        // A restart with a new account replaces the record; it must not end
        // up authorising both.
        let rotated = IssuancePolicy {
            account_uri: "https://acme.example/acct/8".into(),
            ..policy
        };
        adapter.authorize_issuer("pds.did.bot", &rotated).unwrap();
        assert_eq!(dns.caa_values("pds.did.bot"), rotated.caa_values());
        assert_eq!(dns.caa_values("pds.did.bot").len(), 1);
    }

    #[test]
    fn republishing_replaces_rather_than_accumulates() {
        let dns = InMemoryAcmeDns::new();
        let name = "_acme-challenge.pds.did.bot";
        dns.publish_challenge(name, &["stale".into()]).unwrap();
        dns.publish_challenge(name, &["fresh".into()]).unwrap();
        assert_eq!(dns.values(name).unwrap(), vec!["fresh".to_string()]);
    }

    #[test]
    fn clearing_removes_the_whole_set() {
        let dns = InMemoryAcmeDns::new();
        let name = "_acme-challenge.pds.did.bot";
        dns.publish_challenge(name, &["one".into(), "two".into()])
            .unwrap();
        dns.clear_challenge(name).unwrap();
        assert_eq!(dns.values(name), None);
    }

    #[test]
    fn adapter_publishes_both_values_at_the_shared_name() {
        let backend = Arc::new(InMemoryDns::new());
        let adapter = DnsProviderAdapter::new(backend.clone());
        let name = "_acme-challenge.pds.did.bot";
        adapter
            .publish_challenge(
                name,
                &["apex-token".to_string(), "wildcard-token".to_string()],
            )
            .unwrap();
        assert_eq!(
            backend.txt_values(name),
            vec!["apex-token".to_string(), "wildcard-token".to_string()]
        );
    }

    #[test]
    fn adapter_a_second_publish_adds_rather_than_drops_the_first_value() {
        // The regression this exists to catch: an adapter that withdrew and
        // republished the whole set non-additively would leave a window with
        // only one value visible. Publishing the apex's value, then the
        // wildcard's, as two separate `publish_challenge` calls -- which is
        // exactly what a renewal replaying a partially-completed attempt
        // looks like -- must end with both still present.
        let backend = Arc::new(InMemoryDns::new());
        let adapter = DnsProviderAdapter::new(backend.clone());
        let name = "_acme-challenge.pds.did.bot";
        adapter
            .publish_challenge(name, &["apex-token".to_string()])
            .unwrap();
        adapter
            .publish_challenge(
                name,
                &["apex-token".to_string(), "wildcard-token".to_string()],
            )
            .unwrap();
        assert_eq!(
            backend.txt_values(name),
            vec!["apex-token".to_string(), "wildcard-token".to_string()]
        );
    }

    #[test]
    fn adapter_publish_withdraws_values_no_longer_wanted() {
        let backend = Arc::new(InMemoryDns::new());
        let adapter = DnsProviderAdapter::new(backend.clone());
        let name = "_acme-challenge.pds.did.bot";
        adapter
            .publish_challenge(name, &["stale".to_string()])
            .unwrap();
        adapter
            .publish_challenge(name, &["fresh".to_string()])
            .unwrap();
        assert_eq!(backend.txt_values(name), vec!["fresh".to_string()]);
    }

    #[test]
    fn adapter_republishing_the_same_set_is_a_no_op() {
        let backend = Arc::new(InMemoryDns::new());
        let adapter = DnsProviderAdapter::new(backend.clone());
        let name = "_acme-challenge.pds.did.bot";
        let values = vec!["one".to_string(), "two".to_string()];
        adapter.publish_challenge(name, &values).unwrap();
        adapter.publish_challenge(name, &values).unwrap();
        assert_eq!(backend.txt_values(name), values);
    }

    #[test]
    fn adapter_clear_removes_every_value() {
        let backend = Arc::new(InMemoryDns::new());
        let adapter = DnsProviderAdapter::new(backend.clone());
        let name = "_acme-challenge.pds.did.bot";
        adapter
            .publish_challenge(name, &["one".to_string(), "two".to_string()])
            .unwrap();
        adapter.clear_challenge(name).unwrap();
        assert!(backend.txt_values(name).is_empty());
    }

    #[test]
    fn adapter_clear_of_nothing_published_is_not_an_error() {
        let backend = Arc::new(InMemoryDns::new());
        let adapter = DnsProviderAdapter::new(backend);
        assert!(adapter
            .clear_challenge("_acme-challenge.never.example")
            .is_ok());
    }
}