didbot_identity/

did.rs

//! Minting and validating the `did:web` identifiers that agents get.

use std::fmt;

/// Hard cap on DID length, from the atproto DID specification: "DID
/// identifiers do not generally have a maximum length restriction, but in the
/// context of atproto, there is a current hard limit of 2048 characters."
pub const MAX_DID_LENGTH: usize = 2048;

/// The prefix every DID this crate handles starts with.
const DID_WEB_PREFIX: &str = "did:web:";

/// Path the DID document is served at, per the `did:web` method.
const DID_JSON_PATH: &str = "/.well-known/did.json";

/// The only percent escape an atproto `did:web` may contain: the colon that
/// separates a bare loopback hostname from its port. Uppercase hex only,
/// because the spec says "DIDs are case-sensitive" and implementations
/// "should reject DIDs with invalid casing" — one spelling keeps comparison
/// a byte compare.
///
/// Nothing here mints a DID carrying one. A zone's accounts answer on 443,
/// so their DIDs name a hostname and nothing else; this is read, not
/// written, so a DID somebody else minted still parses.
const ENCODED_COLON: &str = "%3A";

/// Why a string is not a usable agent `did:web`.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum DidError {
    /// The string does not start with `did:web:`.
    #[error("not a did:web identifier: {0:?}")]
    NotDidWeb(String),
    /// Longer than the atproto cap of 2048 characters.
    #[error("did is {0} characters, over the atproto limit of {MAX_DID_LENGTH}")]
    TooLong(usize),
    /// The method-specific identifier is empty.
    #[error("did:web with an empty identifier")]
    EmptyIdentifier,
    /// A literal colon appeared in the identifier. In `did:web` that is the
    /// path separator, and atproto supports hostname-level DIDs only.
    #[error("path-based did:web is not supported in atproto: {0:?}")]
    PathBased(String),
    /// A percent escape that would decode to `/`, which would graft a path
    /// onto the fetch URL.
    #[error("did contains an encoded path separator: {0:?}")]
    EncodedPathSeparator(String),
    /// Some percent escape other than the port colon.
    #[error("unsupported percent escape in did: {0:?}")]
    BadPercentEscape(String),
    /// A character outside the allowed subset, or an uppercase letter in a
    /// hostname that must be lowercase to be comparable.
    #[error("invalid character {0:?} in did:web hostname")]
    InvalidCharacter(char),
    /// A `..`, a leading `.`, or a trailing `.` produced an empty DNS label.
    #[error("empty hostname label in {0:?}")]
    EmptyLabel(String),
    /// A label starting or ending with a hyphen.
    #[error("hostname label {0:?} starts or ends with a hyphen")]
    HyphenEdge(String),
    /// A port on something that is not localhost. Ports are development-only.
    #[error("port numbers are only allowed for localhost, not {0:?}")]
    PortOnNonLocalhost(String),
    /// The port is missing, empty, or not a number.
    #[error("invalid port {0:?}")]
    InvalidPort(String),
    /// A hostname under `.arpa`, which handles and `did:web` both exclude.
    #[error("the .arpa top-level domain is not allowed")]
    ArpaDomain,
    /// The agent id offered to [`AccountDid::mint`] is not a single DNS label.
    #[error("agent id {0:?} is not a usable hostname label")]
    InvalidAccountId(String),
    /// The zone host offered to [`Zone::new`] is not a usable hostname.
    #[error("zone host {0:?} is not a usable hostname")]
    InvalidZoneHost(String),
    /// The PDS hostname is not a usable hostname.
    #[error("pds host {0:?} is not a usable hostname")]
    InvalidPdsHost(String),
}

/// The DNS zone agents are minted under, plus the port their PDS listens on
/// during development.
///
/// A zone exists because atproto supports "only hostname-level `did:web`
/// DIDs: path-based DIDs are not supported". Every agent therefore needs its
/// own *hostname*, not its own path under a shared one, so the deployment has
/// to own a name it can put arbitrary subdomains under.
///
/// A zone is constructed against the hostname of the PDS that will serve the
/// accounts, but it does not have to sit at or below that hostname: a PDS at
/// `pds.example.com` may delegate `pds.example.com`, `agents.pds.example.com`,
/// or `agents.anotherexample.com`, provided it holds DNS credentials for
/// whichever zone it names. Which server serves a given agent is answered by
/// resolving the agent's DID document, which carries the PDS's
/// `serviceEndpoint` under `#atproto_pds` — not by inspecting the DID string.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Zone {
    pds_host: String,
    host: String,
}

impl Zone {
    /// A zone that is the PDS's own hostname: agents become its immediate
    /// subdomains.
    pub fn new(pds_host: &str) -> Result<Self, DidError> {
        validate_hostname(pds_host).map_err(|_| DidError::InvalidPdsHost(pds_host.to_owned()))?;
        Ok(Self {
            pds_host: pds_host.to_owned(),
            host: pds_host.to_owned(),
        })
    }

    /// A zone the PDS delegates agent names from. It may be any hostname the
    /// PDS holds DNS credentials for, including one that does not sit under
    /// `pds_host` at all.
    pub fn delegated(pds_host: &str, zone_host: &str) -> Result<Self, DidError> {
        let zone = Self::new(pds_host)?;
        validate_hostname(zone_host)
            .map_err(|_| DidError::InvalidZoneHost(zone_host.to_owned()))?;
        Ok(Self {
            host: zone_host.to_owned(),
            ..zone
        })
    }

    /// The base hostname agents are minted under.
    pub fn host(&self) -> &str {
        &self.host
    }

    /// Whether this zone is `localhost` or under it, and so development-only.
    ///
    /// RFC 6761 reserves that subtree for loopback, so every agent hostname
    /// minted here resolves without a zone to write, has no operator's
    /// repository to read and is reachable by no relay. The server picks its
    /// listener, its certificate source and what it polls for by this.
    pub fn is_loopback(&self) -> bool {
        is_loopback_host(&self.host)
    }

    /// The hostname of the PDS this zone is delegated from.
    pub fn pds_host(&self) -> &str {
        &self.pds_host
    }

    /// The `did:web` naming the server itself, rather than any account on it.
    ///
    /// This is the DID a human's vouch record points at when it says "this is
    /// my personal data server and I take responsibility for the agents on
    /// it". It is the *zone* hostname and not the PDS hostname: a
    /// [`ZoneRegistry`] holds one `Zone` per zone a deployment mints under,
    /// and the vouch has to name the zone whose accounts it is vouching for
    /// — naming the PDS hostname instead would not say which of a
    /// deployment's several zones is covered.
    ///
    /// Returned as a string. It is a `did:web` for a service, not for an
    /// account, and handing back an [`AccountDid`] would say otherwise.
    pub fn service_did(&self) -> String {
        format!("{DID_WEB_PREFIX}{}", self.host)
    }
}

/// Why a set of zones could not be assembled.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum ZoneRegistryError {
    /// No zones were offered at all.
    #[error("a zone registry needs at least one zone")]
    Empty,
    /// The same hostname was offered twice.
    #[error("zone {0:?} is configured more than once")]
    Duplicate(String),
}

/// Several [`Zone`]s under one server. They may nest — a zone at
/// `dev.agents.bot` under a deployment that also mints from `agents.bot` is
/// fine — because nesting is not actually ambiguous: a wildcard certificate
/// matches exactly one label, so `*.agents.bot` covers `foo.agents.bot` and
/// does not cover `foo.dev.agents.bot`. The two namespaces do not intersect.
/// The single point of contact between them is `dev.agents.bot` itself,
/// which the outer zone could otherwise mint as an agent name, and that is
/// guarded separately — by reserving the inner zone's apex label in the
/// outer zone's own name registry, not by refusing the pair here. What this
/// type does check is what only a *set* of zones can violate: the same
/// hostname configured twice.
///
/// A deployment with one zone is the common case and stays exactly as simple
/// as it always was: [`ZoneRegistry::single`] wraps it.
///
/// # A zone here mints agents; the server's own hostname might not be one
///
/// `Zone::new(pds_host)` makes `pds_host` itself an agent-minting zone —
/// every label under it is a candidate agent name. A deployment delegating
/// subzones keeps its own identity — its service DID, its own pages — as a
/// [`Zone`] held separately, outside this registry.
///
/// # Nested zones each need their own certificate
///
/// One wildcard cannot span both depths: `agents.bot` plus `*.agents.bot` is
/// one certificate pair, and `dev.agents.bot` plus `*.dev.agents.bot` is
/// another. A deployment nesting zones needs a certificate pair per zone.
#[derive(Debug, Clone)]
pub struct ZoneRegistry {
    /// The zones offered to [`ZoneRegistry::new`], in order. None of them
    /// share a hostname; see [`ZoneRegistry::new`].
    zones: Vec<Zone>,
}

impl ZoneRegistry {
    /// Assembles a registry, refusing a set with the same hostname twice.
    ///
    /// `zones` is ordered; the first entry is the registry's
    /// [`ZoneRegistry::default_zone`]. Each zone must already be
    /// independently valid — that is [`Zone::new`] and [`Zone::delegated`]'s
    /// job, not this one's. Nesting is allowed; see the struct docs on why
    /// it is not the ambiguity a naive reading suggests, and on where the
    /// real protection against an outer zone minting an inner zone's apex
    /// actually lives.
    pub fn new(zones: Vec<Zone>) -> Result<Self, ZoneRegistryError> {
        if zones.is_empty() {
            return Err(ZoneRegistryError::Empty);
        }
        for i in 0..zones.len() {
            for j in (i + 1)..zones.len() {
                let a = &zones[i];
                let b = &zones[j];
                if a.host().eq_ignore_ascii_case(b.host()) {
                    return Err(ZoneRegistryError::Duplicate(a.host().to_owned()));
                }
            }
        }
        Ok(Self { zones })
    }

    /// A registry holding exactly one zone. Cannot fail: one zone can never
    /// duplicate itself.
    pub fn single(zone: Zone) -> Self {
        Self { zones: vec![zone] }
    }

    /// Every configured zone, in the order they were offered.
    pub fn zones(&self) -> &[Zone] {
        &self.zones
    }

    /// The registry's default zone: the first one offered to
    /// [`ZoneRegistry::new`], and where provisioning lands when nothing more
    /// specific routes it elsewhere.
    ///
    /// Not to be confused with the server's own identity, which is a
    /// separate [`Zone`] a deployment holds outside this registry — see the
    /// module docs on why a zone that mints agents and the PDS's own
    /// hostname are not required to be the same hostname once subzones
    /// exist.
    pub fn default_zone(&self) -> &Zone {
        &self.zones[0]
    }

    /// The configured zone named `host`, if any.
    pub fn find(&self, host: &str) -> Option<&Zone> {
        self.zones
            .iter()
            .find(|z| z.host().eq_ignore_ascii_case(host))
    }

    /// The most specific configured zone `host` sits at or below, if any.
    ///
    /// Zones may nest — see the struct docs — so a host can sit at or below
    /// more than one configured zone at once: everything under
    /// `dev.agents.bot` is, trivially, also under `agents.bot`. The deepest
    /// match, by label count, is the one that actually minted it, so that is
    /// what this returns. Two zones can never tie at the same depth without
    /// being the same zone, since a duplicate hostname is refused at
    /// construction.
    pub fn containing(&self, host: &str) -> Option<&Zone> {
        self.zones
            .iter()
            .filter(|z| hostname_is_at_or_below(host, z.host()))
            .max_by_key(|z| z.host().matches('.').count())
    }
}

/// Whether `host` is `ancestor` or a subdomain of it.
///
/// Compares DNS labels from the right, case-insensitively. Label boundaries
/// are the point: `evilfoo.bar` shares a suffix with `foo.bar` but no label
/// alignment, and `foo.bar.attacker.com` contains `foo.bar` but is below
/// `attacker.com`. Both are false here.
pub fn hostname_is_at_or_below(host: &str, ancestor: &str) -> bool {
    if host.is_empty() || ancestor.is_empty() {
        return false;
    }
    let host_labels: Vec<&str> = host.split('.').collect();
    let ancestor_labels: Vec<&str> = ancestor.split('.').collect();
    if host_labels.len() < ancestor_labels.len() {
        return false;
    }
    let tail = &host_labels[host_labels.len() - ancestor_labels.len()..];
    tail.iter()
        .zip(ancestor_labels.iter())
        .all(|(a, b)| a.eq_ignore_ascii_case(b))
}

/// A validated `did:web` belonging to one agent.
///
/// Held as the exact DID string plus its decoded authority, so that neither
/// the identifier nor the fetch URL has to be recomputed — and so that the
/// decoded form can never disagree with the encoded one.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct AccountDid {
    /// The DID exactly as it is written, port colon still encoded.
    did: String,
    /// Decoded hostname, without a port.
    host: String,
    /// Decoded port, if the DID carried one.
    port: Option<u16>,
}

impl AccountDid {
    /// Mints the DID for `account_id` within `zone`.
    ///
    /// Produces `did:web:<account_id>.<zone host>`, which resolves at
    /// `https://<account_id>.<zone host>/.well-known/did.json` — no port,
    /// because the spec allows one only for a bare loopback hostname and an
    /// account is a subdomain of its zone.
    pub fn mint(zone: &Zone, account_id: &str) -> Result<Self, DidError> {
        validate_label(account_id)
            .map_err(|_| DidError::InvalidAccountId(account_id.to_owned()))?;
        let mut did =
            String::with_capacity(DID_WEB_PREFIX.len() + account_id.len() + zone.host.len() + 8);
        did.push_str(DID_WEB_PREFIX);
        did.push_str(account_id);
        did.push('.');
        did.push_str(&zone.host);
        // Parsing what we just built is not redundant: it is the only thing
        // that guarantees mint can never emit a DID that parse would refuse.
        Self::parse(&did)
    }

    /// Parses and validates an agent `did:web`.
    pub fn parse(did: &str) -> Result<Self, DidError> {
        if did.len() > MAX_DID_LENGTH {
            return Err(DidError::TooLong(did.len()));
        }
        let identifier = did
            .strip_prefix(DID_WEB_PREFIX)
            .ok_or_else(|| DidError::NotDidWeb(did.to_owned()))?;
        if identifier.is_empty() {
            return Err(DidError::EmptyIdentifier);
        }
        // A literal colon here is the `did:web` path separator. atproto:
        // "only hostname-level did:web DIDs are supported: path-based DIDs
        // are not supported."
        if identifier.contains(':') {
            return Err(DidError::PathBased(did.to_owned()));
        }
        // The generic atproto DID regex ends `[a-zA-Z0-9._-]$`: an identifier
        // may not end mid-escape.
        if identifier.ends_with('%') {
            return Err(DidError::BadPercentEscape(identifier.to_owned()));
        }

        let authority = decode_authority(identifier)?;
        let (host, port) = match authority.split_once(':') {
            Some((host, port)) => (host.to_owned(), Some(parse_port(port)?)),
            None => (authority, None),
        };

        validate_hostname(&host)?;
        // The spec allows a port "only ... for `localhost`, and only in
        // testing and development". A bare loopback hostname, not anything
        // merely under `.localhost`: an atproto client refuses the rest, so
        // accepting them here would produce DIDs only this codebase can
        // resolve.
        if port.is_some() && !is_loopback_literal(&host) {
            return Err(DidError::PortOnNonLocalhost(host));
        }

        Ok(Self {
            did: did.to_owned(),
            host,
            port,
        })
    }

    /// The agent's own label: the leftmost component of the hostname.
    pub fn account_id(&self) -> &str {
        self.host.split('.').next().unwrap_or(&self.host)
    }

    /// The decoded hostname, without any port.
    pub fn host(&self) -> &str {
        &self.host
    }

    /// The decoded port, if this is a development DID that carries one.
    pub fn port(&self) -> Option<u16> {
        self.port
    }

    /// The decoded authority: `host`, or `host:port` for a development DID.
    ///
    /// This is the `did:web` identifier with its port colon *decoded*, which
    /// is what an atproto record key may contain — `:` is in the record-key
    /// character set and `%` is not. Anything keying a record by the server
    /// a DID names has to use this rather than the encoded form
    /// [`Self::as_str`] carries, and both sides of `bot.did.operator` do:
    /// `didbot operate` writes at this key and the server's own poll reads at
    /// it. Deriving it here rather than at each end is what stops the two
    /// from disagreeing.
    pub fn authority(&self) -> String {
        match self.port {
            Some(port) => format!("{}:{port}", self.host),
            None => self.host.clone(),
        }
    }

    /// Whether this DID names a loopback host, and so is development-only.
    pub fn is_loopback(&self) -> bool {
        is_loopback_host(&self.host)
    }

    /// The URL the DID document is served at. Always `https://`: every
    /// server this project runs terminates TLS, on a developer's machine as
    /// much as anywhere else.
    ///
    /// A DID carries no port, so this is port 443 — except for a loopback
    /// host [`RESOLVE_PORTS`] names, which is how a harness reaches several
    /// servers at once on one machine.
    pub fn did_json_url(&self) -> String {
        match self.port.or_else(|| resolve_port(&self.host)) {
            Some(port) => format!("https://{}:{port}{DID_JSON_PATH}", self.host),
            None => format!("https://{}{DID_JSON_PATH}", self.host),
        }
    }

    /// The DID as written, with the port colon still encoded.
    pub fn as_str(&self) -> &str {
        &self.did
    }
}

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

impl std::str::FromStr for AccountDid {
    type Err = DidError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Self::parse(s)
    }
}

/// Reads the port half of a decoded authority, in one spelling only.
///
/// `u16::from_str` is not that: it accepts a leading `+` and any number of
/// leading zeros, so `%3A3000`, `%3A03000` and `%3A+3000` would all decode to
/// port 3000. That is the two-spellings-one-identity problem, and it is not
/// hypothetical here — [`AccountDid`] compares and hashes on the DID string it
/// was given, while [`AccountDid::did_json_url`] and [`AccountDid::authority`]
/// derive from the decoded port, so the spellings are distinct identifiers
/// naming one account. The `+` form is
/// worse still: [`validate_did`] refuses `+` outright, so accepting it here
/// made this supposedly stricter parser admit a string that is not a
/// syntactically valid DID of any method at all.
///
/// Digits only, and no leading zero unless the port is exactly `0` — which
/// is then refused as a port anyway, since nothing listens on it.
fn parse_port(port: &str) -> Result<u16, DidError> {
    let bad = || DidError::InvalidPort(port.to_owned());
    if port.is_empty() || !port.bytes().all(|byte| byte.is_ascii_digit()) {
        return Err(bad());
    }
    if port.len() > 1 && port.starts_with('0') {
        return Err(bad());
    }
    let port: u16 = port.parse().map_err(|_| bad())?;
    if port == 0 {
        return Err(DidError::InvalidPort("0".to_owned()));
    }
    Ok(port)
}

/// Turns the method-specific identifier into a decoded `host` or `host:port`.
///
/// Deliberately not a general percent decoder. `%3A` is the only escape an
/// atproto `did:web` has any reason to contain, and a general decoder is
/// exactly how a crafted DID smuggles a path separator into a fetch URL.
fn decode_authority(identifier: &str) -> Result<String, DidError> {
    let mut out = String::with_capacity(identifier.len());
    let bytes = identifier.as_bytes();
    let mut i = 0;
    while i < bytes.len() {
        if bytes[i] == b'%' {
            let escape = identifier
                .get(i..i + 3)
                .ok_or_else(|| DidError::BadPercentEscape(identifier.to_owned()))?;
            if escape.eq_ignore_ascii_case("%2F") {
                return Err(DidError::EncodedPathSeparator(identifier.to_owned()));
            }
            if escape != ENCODED_COLON {
                return Err(DidError::BadPercentEscape(escape.to_owned()));
            }
            out.push(':');
            i += 3;
        } else {
            out.push(bytes[i] as char);
            i += 1;
        }
    }
    Ok(out)
}

/// Checks a decoded hostname: lowercase DNS labels, no empties, no `.arpa`.
fn validate_hostname(host: &str) -> Result<(), DidError> {
    if host.is_empty() {
        return Err(DidError::EmptyIdentifier);
    }
    for label in host.split('.') {
        if label.is_empty() {
            return Err(DidError::EmptyLabel(host.to_owned()));
        }
        validate_label(label)?;
    }
    // The spec: "The same restrictions on top-level domains that apply to
    // handles (eg, no .arpa) also apply to did:web domains."
    if let Some(tld) = host.rsplit('.').next() {
        if tld == "arpa" {
            return Err(DidError::ArpaDomain);
        }
    }
    Ok(())
}

/// Checks one DNS label. Uppercase is rejected rather than normalized: a DID
/// is compared byte for byte across the network, so two spellings of one
/// identity would be two identities.
///
/// This is the authority on what an agent id may be: [`AccountDid::mint`] and
/// `validate_hostname` (this crate's `did:web` host check) both call it
/// rather than a copy, and anything upstream that generates a label — a
/// namer, or any derivation — should too. Two validators that disagree about which
/// labels are legal is how an illegal one reaches DNS: one accepts what the
/// other would have refused. This function has no notion of a maximum label
/// length; that is a DNS-label rule with no `did:web`-specific meaning, and a
/// caller that cares (`didbot-name`, publishing under a zone) enforces its own
/// bound on top of this.
pub fn validate_label(label: &str) -> Result<(), DidError> {
    if label.is_empty() {
        return Err(DidError::EmptyLabel(label.to_owned()));
    }
    for ch in label.chars() {
        if !(ch.is_ascii_lowercase() || ch.is_ascii_digit() || ch == '-') {
            return Err(DidError::InvalidCharacter(ch));
        }
    }
    if label.starts_with('-') || label.ends_with('-') {
        return Err(DidError::HyphenEdge(label.to_owned()));
    }
    Ok(())
}

/// The environment variable naming which port a loopback hostname's
/// documents answer on, as `host=port` pairs separated by commas.
///
/// A `did:web` carries no port, so resolving one means port 443 — and one
/// machine has one port 443. A developer's own stack takes it (see
/// `docs/running-locally.md`); a harness starting several servers at once
/// cannot, so it says here where each one is and every tool in this
/// workspace resolves accordingly. A browser is told the same thing through
/// its own resolver rules.
///
/// Only a loopback hostname may be named. An entry for anything else is
/// ignored, so this can never move where a real name resolves.
pub const RESOLVE_PORTS: &str = "DIDBOT_RESOLVE_PORTS";

/// The port [`RESOLVE_PORTS`] gives `host`, if it gives one.
///
/// A zone's entry covers everything under it, because a zone's accounts are
/// one listener; the most specific entry wins, matching
/// [`ZoneRegistry`]'s own rule. Read once per process: this is a harness's
/// own wiring, fixed before anything it starts runs.
pub fn resolve_port(host: &str) -> Option<u16> {
    static PORTS: std::sync::OnceLock<Vec<(String, u16)>> = std::sync::OnceLock::new();
    let ports = PORTS.get_or_init(|| {
        let Ok(raw) = std::env::var(RESOLVE_PORTS) else {
            return Vec::new();
        };
        raw.split(',')
            .filter_map(|entry| entry.trim().split_once('='))
            .filter(|(host, _)| is_loopback_host(host))
            .filter_map(|(host, port)| Some((host.to_ascii_lowercase(), port.parse().ok()?)))
            .collect()
    });
    let host = host.to_ascii_lowercase();
    ports
        .iter()
        .filter(|(named, _)| host == *named || host.ends_with(&format!(".{named}")))
        .max_by_key(|(named, _)| named.len())
        .map(|(_, port)| *port)
}

/// A hostname without the port it is reached on.
///
/// A person types the port their server answers on; a `did:web`, a record
/// key and a zone all carry none. This is the half of a typed name that can
/// be compared against any of them.
///
/// ```
/// use didbot_identity::did::host_without_port;
/// assert_eq!(host_without_port("agents.localhost:3000"), "agents.localhost");
/// assert_eq!(host_without_port("agents.example.com"), "agents.example.com");
/// ```
pub fn host_without_port(name: &str) -> &str {
    match name.rsplit_once(':') {
        Some((host, port))
            if !port.is_empty() && port.bytes().all(|byte| byte.is_ascii_digit()) =>
        {
            host
        }
        _ => name,
    }
}

/// The `did:web` a hostname spells.
///
/// A hostname a person types carries the port they reach the server on. A
/// `did:web` carries one only for a bare loopback hostname — an atproto
/// client reads a port on anything else as a handle — so anywhere else the
/// port is dropped, which is also what the server's own
/// [`Zone::service_did`] does. The colon that stays is percent-encoded,
/// the spelling [`AccountDid::parse`] reads back.
///
/// One function because seven callers had a copy of it, and a DID that
/// disagrees with the one the server minted is a record written where
/// nothing reads it.
///
/// ```
/// use didbot_identity::did::did_web_for_host;
/// assert_eq!(did_web_for_host("kestrel.agents.localhost:3000"), "did:web:kestrel.agents.localhost");
/// assert_eq!(did_web_for_host("localhost:3000"), "did:web:localhost%3A3000");
/// assert_eq!(did_web_for_host("agents.example.com"), "did:web:agents.example.com");
/// ```
pub fn did_web_for_host(host: &str) -> String {
    let name = host_without_port(host);
    match host.strip_prefix(name) {
        Some(port) if !port.is_empty() && is_loopback_literal(name) => {
            format!("{DID_WEB_PREFIX}{name}{ENCODED_COLON}{}", &port[1..])
        }
        _ => format!("{DID_WEB_PREFIX}{name}"),
    }
}

/// How a person reads an account's name in a command's output.
///
/// A `did:web` is its hostname. Any other DID is `@handle` when `handle` is
/// one the caller verified both ways, and the DID itself when it is not.
///
/// ```
/// use didbot_identity::did::account_name;
/// assert_eq!(account_name("did:web:kestrel.pds.example", None), "kestrel.pds.example");
/// assert_eq!(account_name("did:web:localhost%3A3000", None), "localhost:3000");
/// assert_eq!(account_name("did:plc:abc", Some("operator.example")), "@operator.example");
/// assert_eq!(account_name("did:plc:abc", None), "did:plc:abc");
/// ```
pub fn account_name(did: &str, handle: Option<&str>) -> String {
    if let Ok(web) = AccountDid::parse(did) {
        return web.authority();
    }
    match handle {
        Some(handle) => format!("@{handle}"),
        None => did.to_owned(),
    }
}

/// Whether a hostname is one of the bare loopback names the atproto profile
/// permits a port on.
///
/// Narrower than [`is_loopback_host`], and deliberately: `agents.localhost`
/// resolves to this machine, but an atproto client reads
/// `did:web:agents.localhost%3A3000` as a handle rather than a DID, so a DID
/// in that shape is one nothing else can resolve.
pub fn is_loopback_literal(host: &str) -> bool {
    host == "localhost" || host == "127.0.0.1" || host == "::1" || host == "[::1]"
}

/// Whether a hostname resolves to this machine.
///
/// `*.localhost` counts. RFC 6761 reserves the whole subtree for loopback,
/// and minting gives every agent a subdomain, so a development zone is
/// `agents.localhost` and every agent under it lands here. This answers what
/// a deployment has around it — no public DNS, no operator's repository, no
/// relay that can reach it — not what scheme it speaks.
pub fn is_loopback_host(host: &str) -> bool {
    host == "localhost"
        || host.ends_with(".localhost")
        || host == "127.0.0.1"
        || host == "::1"
        || host == "[::1]"
}

/// Why a string is not a syntactically valid DID of any method.
///
/// Separate from [`DidError`] because the two validators answer separate
/// questions; see [`validate_did`].
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum SyntaxError {
    /// Longer than the atproto cap of 2048 characters.
    #[error("did is {0} characters, over the atproto limit of {MAX_DID_LENGTH}")]
    TooLong(usize),
    /// Does not begin with the lowercase literal `did:`.
    #[error("did does not start with `did:`")]
    NoDidPrefix,
    /// No colon after the method name, so there is no method-specific
    /// identifier at all.
    #[error("did has no method-specific identifier")]
    NoIdentifier,
    /// The method name was empty or held something other than `a-z`.
    #[error("did method {0:?} must be one or more lowercase letters")]
    BadMethod(String),
    /// The method-specific identifier was empty.
    #[error("did:{0} with an empty identifier")]
    EmptyIdentifier(String),
    /// A character outside `A-Za-z0-9._:%-` appeared in the identifier.
    #[error("invalid character {0:?} in did identifier")]
    InvalidCharacter(char),
    /// A `%` not followed by two hexadecimal digits.
    #[error("malformed percent escape in did identifier")]
    BadPercentEscape,
    /// The identifier ended on the `:` that separates its own parts, which
    /// would make the last part empty.
    #[error("did identifier ends with a colon")]
    TrailingColon,
}

/// Checks a string against the generic atproto DID syntax rules.
///
/// # This is not [`AccountDid::parse`], and the difference is deliberate
///
/// [`AccountDid`] is much stricter: `did:web` only, hostname-level only, ports
/// only on loopback, lowercase only. That strictness is this project's
/// security posture rather than atproto's grammar — see [`Zone`]. Running the
/// protocol's generic DID vectors against `AccountDid` would report failures
/// that are the entire point of the type, so they are run against this
/// function instead.
///
/// The two are still connected: every DID [`AccountDid::mint`] produces is also
/// valid here, and the conformance suite asserts it.
///
/// ```
/// use didbot_identity::did::validate_did;
/// assert!(validate_did("did:plc:7iza6de2dwap2sbkpav7c6c6").is_ok());
/// assert!(validate_did("did:web:localhost%3A1234").is_ok());
/// assert!(validate_did("did:m123:val").is_err()); // method is letters only
/// assert!(validate_did("did:method:val:").is_err());
/// ```
pub fn validate_did(did: &str) -> Result<(), SyntaxError> {
    if did.len() > MAX_DID_LENGTH {
        return Err(SyntaxError::TooLong(did.len()));
    }
    let rest = did.strip_prefix("did:").ok_or(SyntaxError::NoDidPrefix)?;
    let (method, identifier) = rest.split_once(':').ok_or(SyntaxError::NoIdentifier)?;

    if method.is_empty() || !method.bytes().all(|b| b.is_ascii_lowercase()) {
        return Err(SyntaxError::BadMethod(method.to_owned()));
    }
    if identifier.is_empty() {
        return Err(SyntaxError::EmptyIdentifier(method.to_owned()));
    }
    // A trailing colon would leave an empty final part. Colons *inside* the
    // identifier are ordinary: `did:method::::val` is valid, and `did:web`
    // uses them for the paths this crate refuses at a higher level.
    if identifier.ends_with(':') {
        return Err(SyntaxError::TrailingColon);
    }

    let bytes = identifier.as_bytes();
    let mut i = 0;
    while i < bytes.len() {
        let byte = bytes[i];
        if byte == b'%' {
            // Percent escapes are checked, never decoded. Decoding is a
            // method's business, and a general decoder in a syntax check is
            // how a crafted identifier smuggles a separator past it.
            let hex = identifier
                .get(i + 1..i + 3)
                .ok_or(SyntaxError::BadPercentEscape)?;
            if !hex.bytes().all(|b| b.is_ascii_hexdigit()) {
                return Err(SyntaxError::BadPercentEscape);
            }
            i += 3;
            continue;
        }
        if !(byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'-' | b'_' | b':')) {
            // The identifier is not necessarily ASCII, so the offending
            // character comes from the char iterator rather than the byte.
            let ch = identifier[i..]
                .chars()
                .next()
                .unwrap_or(char::REPLACEMENT_CHARACTER);
            return Err(SyntaxError::InvalidCharacter(ch));
        }
        i += 1;
    }
    Ok(())
}

/// A DID from a URL, spelled the way this project stores it.
///
/// Both a path segment and a query value are percent-decoded once before a
/// handler sees them, and a local agent's DID already contains a
/// percent-encoding of its own: a DID on a bare loopback host is written
/// `did:web:localhost%3A3400`, so naming one in a URL means encoding the
/// `%` as well. A client that builds URLs properly does that and
/// this changes nothing; a person with `curl` and a DID copied out of a log
/// writes the bare colon, and without this gets an empty answer for an agent
/// that is plainly there.
///
/// The repair is unambiguous rather than a guess: in `did:web` a colon
/// separates path segments, a port must be written `%3A`, and a bare
/// `host:3400` in the identifier position is not a DID this server could have
/// minted. Anything that is not a `did:web` with a numeric last segment comes
/// back untouched, so a `did:plc`, a handle and a properly encoded DID all
/// pass straight through.
///
/// Applied to every DID-valued input rather than only where a bug was noticed:
/// a filter that silently matched nothing is worse than a 404, because a
/// caller reads it as "no such children" rather than as "ask differently".
///
/// It lives here rather than beside either caller because both the query
/// service and the personal data server's `com.atproto.repo.*` routes need
/// exactly this repair, and two copies of it would agree until one was
/// edited.
///
/// ```
/// use didbot_identity::canonical_did;
/// assert_eq!(
///     canonical_did("did:web:localhost:3400"),
///     "did:web:localhost%3A3400"
/// );
/// // Already encoded, a plain hostname, and a `did:plc` all pass through.
/// assert_eq!(
///     canonical_did("did:web:localhost%3A3400"),
///     "did:web:localhost%3A3400"
/// );
/// assert_eq!(canonical_did("did:web:agents.example"), "did:web:agents.example");
/// assert_eq!(canonical_did("did:plc:abc123"), "did:plc:abc123");
/// ```
pub fn canonical_did(value: &str) -> String {
    let Some(rest) = value.strip_prefix("did:web:") else {
        return value.to_owned();
    };
    let Some((host, port)) = rest.rsplit_once(':') else {
        return value.to_owned();
    };
    if port.is_empty() || !port.bytes().all(|byte| byte.is_ascii_digit()) {
        return value.to_owned();
    }
    format!("did:web:{host}%3A{port}")
}