didbot_identity/

resolve.rs

//! Resolving a DID to its DID document, dispatched by method.
//!
//! Two methods are supported. `did:web` — see the next section for why this
//! crate ships its own implementation rather than a library's. `did:plc`
//! resolves by fetching `https://plc.directory/<did>` from the PLC
//! directory: no hostname to build, no percent-decoding, none of the
//! `did:web` hazards below apply. A DID of any other method is refused with
//! [`ResolveError::UnsupportedMethod`] naming the method, rather than
//! quietly answering "no document" for something this resolver simply does
//! not speak.
//!
//! # Why this crate ships its own `did:web` resolver
//!
//! jacquard-identity 0.12.1 builds the fetch URL by concatenating `https://`
//! with the method-specific identifier verbatim. Neither half of that works
//! for a development DID:
//!
//! * The identifier is never percent-decoded, so `did:web:localhost%3A3000`
//!   becomes a request for a host literally named `localhost%3A3000`, which
//!   no resolver, DNS or otherwise, will ever answer.
//! * The scheme is hardcoded to `https://`, and nothing is listening on TLS
//!   on a developer's loopback interface.
//!
//! Both are correct for the production case that library targets. Neither is
//! fixable from outside it, and atproto explicitly permits the shape they
//! break: "The special `localhost` hostname is allowed, but only in testing
//! and development environments. Port numbers (with separating colon
//! hex-encoded) are only allowed for `localhost`, and only in testing and
//! development." That `did:web` path is unchanged here.
//!
//! `did:plc` is a different code path: no hostname is built from the
//! identifier and there is nothing to percent-decode, so jacquard-identity's
//! objection above does not apply to it. This module still does not depend
//! on it. A `did:plc` resolves by a direct fetch to the directory over
//! [`DidDocumentSource`], this module's own transport trait, rather than
//! through jacquard-identity's `IdentityResolver`, which is a much larger
//! surface (handle resolution, DNS, Slingshot fallbacks) built around its
//! own client trait and several dependencies (`bon`, `http`, `n0_future`,
//! optionally `hickory_resolver`) this crate does not otherwise need.
//!
//! # Why the transport is a trait
//!
//! No HTTP client is a dependency here. The fetch is a trait so that the PDS
//! crate can supply the real transport with whatever client and runtime it
//! already has, and so that every test in this crate runs against
//! [`InMemoryDocuments`] with no network access at all. A real transport is
//! also what makes [`ResolveError::NotFound`] and [`ResolveError::Transport`]
//! meaningfully different: the directory answering "no such DID" and the
//! directory being unreachable are different facts, and only the transport
//! that made the request can tell them apart.

use std::collections::HashMap;

use crate::did::AccountDid;
use crate::document::DidDocument;

/// The PLC directory `did:plc` resolves against.
///
/// Not configurable here: a mirror would be selected by the caller supplying
/// a different [`DidDocumentSource`], which is where the transport already
/// lives.
pub const DEFAULT_PLC_DIRECTORY: &str = "https://plc.directory";

/// Length of the identifier in a `did:plc`.
const PLC_IDENTIFIER_LENGTH: usize = 24;

/// Why resolution failed.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum ResolveError {
    /// No document at the URL.
    #[error("no did document at {url}")]
    NotFound {
        /// The URL that was requested.
        url: String,
    },
    /// The transport could not complete the request.
    #[error("transport error fetching {url}: {message}")]
    Transport {
        /// The URL that was requested.
        url: String,
        /// What the transport reported.
        message: String,
    },
    /// The body was not a DID document.
    #[error("malformed did document at {url}: {message}")]
    Malformed {
        /// The URL that was requested.
        url: String,
        /// What the deserializer reported.
        message: String,
    },
    /// The document's `id` is not the DID that was asked for.
    ///
    /// The spec is blunt about this: "The DID declared in the document (in
    /// the `id` field) should always be verified against what was expected."
    /// Skipping it means accepting a document that claims to be a different
    /// account, which for `did:web` is whatever the host chose to serve.
    #[error("did document at {url} claims {found:?}, expected {expected:?}")]
    IdMismatch {
        /// The URL that was requested.
        url: String,
        /// The DID that was asked for.
        expected: String,
        /// The DID the document claimed.
        found: String,
    },
    /// The DID is not a legal one of its own method — a malformed `did:web`
    /// or a `did:plc` whose identifier is not base32-sortable. Caught before
    /// any fetch: an unvalidated identifier joined into a URL is how a
    /// resolver ends up requesting something other than a DID document.
    #[error("{did:?} is not a well-formed {method}: {message}")]
    InvalidDid {
        /// The DID that failed to parse.
        did: String,
        /// The method it claimed, e.g. `"did:web"`.
        method: String,
        /// What was wrong with it.
        message: String,
    },
    /// The DID's method is not one this resolver speaks.
    ///
    /// Named explicitly rather than folded into [`Self::NotFound`]: a method
    /// this resolver has no path for and a document that genuinely does not
    /// exist are different facts, and a caller deciding whether to keep
    /// polling needs to tell them apart.
    #[error("unsupported did method {method:?} in {did:?}")]
    UnsupportedMethod {
        /// The full DID that was requested.
        did: String,
        /// The method it named.
        method: String,
    },
}

/// Where DID document bodies come from.
///
/// Implementors fetch `url` and return the response body. `url` is always
/// produced by this module's own method dispatch — [`AccountDid::did_json_url`]
/// for `did:web`, a join onto [`DEFAULT_PLC_DIRECTORY`] for `did:plc` — so it
/// has already been decoded, scheme-selected and checked for path injection;
/// an implementation should request it as given and must not append
/// anything to it.
pub trait DidDocumentSource {
    /// Fetches the body at `url`, or reports why it could not.
    fn fetch(&self, url: &str) -> Result<String, ResolveError>;
}

/// Resolves `did` through `source` and verifies the result belongs to it.
///
/// `did` is dispatched by method: `did:web` and `did:plc` each get the URL
/// their method defines, and any other method is refused with
/// [`ResolveError::UnsupportedMethod`] before `source` is ever asked to
/// fetch anything. The `id` check is here rather than in the source so that
/// no transport can be written that forgets it.
pub fn resolve<S>(source: &S, did: &str) -> Result<DidDocument, ResolveError>
where
    S: DidDocumentSource + ?Sized,
{
    let url = document_url(did)?;
    let body = source.fetch(&url)?;
    let document: DidDocument =
        serde_json::from_str(&body).map_err(|err| ResolveError::Malformed {
            url: url.clone(),
            message: err.to_string(),
        })?;
    if document.id != did {
        return Err(ResolveError::IdMismatch {
            url,
            expected: did.to_owned(),
            found: document.id,
        });
    }
    Ok(document)
}

/// The URL `did`'s document lives at, or why `did` cannot be resolved at
/// all.
///
/// Public because [`resolve`] is not the only shape a caller needs. A
/// caller holding an async HTTP client — `didbot-serve`'s operator poll —
/// cannot implement the synchronous [`DidDocumentSource`] over it, and
/// still needs the same method dispatch this module already performs: the
/// `did:web` rules in [`AccountDid`] for one method, the directory join for
/// the other, and [`ResolveError::UnsupportedMethod`] for anything else.
/// That caller fetches the body itself and makes [`resolve`]'s `id` check on
/// what comes back.
pub fn document_url(did: &str) -> Result<String, ResolveError> {
    if did.starts_with("did:web:") {
        let parsed = AccountDid::parse(did).map_err(|err| ResolveError::InvalidDid {
            did: did.to_owned(),
            method: "did:web".to_owned(),
            message: err.to_string(),
        })?;
        return Ok(parsed.did_json_url());
    }
    if let Some(identifier) = did.strip_prefix("did:plc:") {
        if !is_plc_identifier(identifier) {
            return Err(ResolveError::InvalidDid {
                did: did.to_owned(),
                method: "did:plc".to_owned(),
                message: format!(
                    "identifier must be {PLC_IDENTIFIER_LENGTH} lowercase base32 characters"
                ),
            });
        }
        return Ok(format!("{DEFAULT_PLC_DIRECTORY}/{did}"));
    }
    let method = did
        .strip_prefix("did:")
        .and_then(|rest| rest.split_once(':'))
        .map(|(method, _)| method)
        .unwrap_or(did);
    Err(ResolveError::UnsupportedMethod {
        did: did.to_owned(),
        method: method.to_owned(),
    })
}

/// Whether `identifier` is the base32-sortable body of a `did:plc`.
///
/// The specification fixes both the length and the alphabet, and this runs
/// before the identifier is joined into a directory URL: an unvalidated
/// identifier in a path join is how a resolver ends up requesting something
/// other than a DID document.
fn is_plc_identifier(identifier: &str) -> bool {
    identifier.len() == PLC_IDENTIFIER_LENGTH
        && identifier
            .bytes()
            .all(|b| b.is_ascii_lowercase() || (b'2'..=b'7').contains(&b))
}

/// A [`DidDocumentSource`] backed by a map from URL to response body.
///
/// The test double, and also a usable cache or fixture loader. Keys are the
/// full URLs [`AccountDid::did_json_url`] produces, so a test that gets the
/// scheme or the port wrong sees a [`ResolveError::NotFound`] rather than
/// silently passing.
#[derive(Debug, Clone, Default)]
pub struct InMemoryDocuments {
    bodies: HashMap<String, String>,
}

impl InMemoryDocuments {
    /// An empty source.
    pub fn new() -> Self {
        Self::default()
    }

    /// Stores a raw body at `url`. Use this to test malformed responses.
    pub fn insert_body(&mut self, url: &str, body: &str) -> &mut Self {
        self.bodies.insert(url.to_owned(), body.to_owned());
        self
    }

    /// Serializes `document` and serves it at `did`'s document URL.
    ///
    /// Returns the serialization error rather than panicking, so callers keep
    /// their no-`unwrap` discipline.
    pub fn insert(
        &mut self,
        did: &AccountDid,
        document: &DidDocument,
    ) -> Result<&mut Self, serde_json::Error> {
        let body = serde_json::to_string(document)?;
        self.bodies.insert(did.did_json_url(), body);
        Ok(self)
    }
}

impl DidDocumentSource for InMemoryDocuments {
    fn fetch(&self, url: &str) -> Result<String, ResolveError> {
        self.bodies
            .get(url)
            .cloned()
            .ok_or_else(|| ResolveError::NotFound {
                url: url.to_owned(),
            })
    }
}

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

    const PLC_DID: &str = "did:plc:nlzmjyfv6loqtxyzvdcznwgf";

    /// A transport that always fails as if the network itself were down,
    /// never as "no document here" — the distinction a caller polling for
    /// a claim needs to make.
    struct AlwaysDown;

    impl DidDocumentSource for AlwaysDown {
        fn fetch(&self, url: &str) -> Result<String, ResolveError> {
            Err(ResolveError::Transport {
                url: url.to_owned(),
                message: "connection refused".to_owned(),
            })
        }
    }

    #[test]
    fn a_plc_identifier_is_fixed_length_base32() {
        assert!(is_plc_identifier("nlzmjyfv6loqtxyzvdcznwgf"));
        // Too short, uppercase, a digit outside the alphabet, and the one
        // that matters: anything that would climb out of the directory path.
        assert!(!is_plc_identifier("nlzmjyfv6loqtxyzvdcznwg"));
        assert!(!is_plc_identifier("NLZMJYFV6LOQTXYZVDCZNWGF"));
        assert!(!is_plc_identifier("nlzmjyfv8loqtxyzvdcznwgf"));
        assert!(!is_plc_identifier("../../../etc/passwd0000000"));
    }

    #[test]
    fn a_did_plc_resolves_through_the_directory_url() {
        let document = DidDocument::for_service(PLC_DID, "https://pds.example.com");
        let mut source = InMemoryDocuments::new();
        source.insert_body(
            &format!("{DEFAULT_PLC_DIRECTORY}/{PLC_DID}"),
            &serde_json::to_string(&document).expect("serializes"),
        );

        let resolved = resolve(&source, PLC_DID).expect("resolution succeeds");
        assert_eq!(resolved, document);
    }

    #[test]
    fn a_malformed_plc_identifier_is_rejected_before_any_fetch() {
        // `AlwaysDown` never answers a fetch: if this got past validation and
        // tried to fetch anyway, the test would see a `Transport` error, not
        // `InvalidDid`.
        match resolve(&AlwaysDown, "did:plc:not-base32") {
            Err(ResolveError::InvalidDid { method, .. }) => assert_eq!(method, "did:plc"),
            other => panic!("expected InvalidDid, got {other:?}"),
        }
    }

    #[test]
    fn an_unsupported_method_names_itself_rather_than_answering_not_found() {
        let source = InMemoryDocuments::new();
        match resolve(
            &source,
            "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
        ) {
            Err(ResolveError::UnsupportedMethod { method, .. }) => assert_eq!(method, "key"),
            other => panic!("expected UnsupportedMethod, got {other:?}"),
        }
    }

    #[test]
    fn a_directory_outage_is_distinguishable_from_a_missing_did() {
        // Down: the transport itself failed.
        assert!(matches!(
            resolve(&AlwaysDown, PLC_DID),
            Err(ResolveError::Transport { .. })
        ));
        // Reachable, but nothing there: a different fact.
        let source = InMemoryDocuments::new();
        assert!(matches!(
            resolve(&source, PLC_DID),
            Err(ResolveError::NotFound { .. })
        ));
    }
}