didbot_serve/oauth/

client_metadata.rs

//! Fetching, validating, and caching OAuth client metadata documents.
//!
//! atproto's OAuth profile has no registered-client table: a `client_id` is
//! an HTTPS URL, and the document served there *is* the client's
//! registration, fetched fresh (or from a short-lived cache) on every use.
//! `plan/app-allowlist.md` needs more than the URL to enforce "an app that
//! changes its redirect URIs is a different app" — so [`ClientKey`] is
//! computed over the validated document's own content, not over the
//! `client_id` string, and it is what [`ClientMetadataCache`] keys on.
//!
//! This module does not decide whether a client is *admitted*; it decides
//! whether a document is *usable* at all. Admission is
//! `plan/app-allowlist.md`'s hook, called from `oauth::par` once a validated
//! document exists.
//!
//! One `client_id` form is the exception to "fetched fresh": the atproto
//! profile's "Localhost Client Development" `client_id`, exactly
//! `http://localhost` with no port and an empty or `/` path. There is
//! nothing to fetch — `parse_loopback_client_id` builds the document
//! straight from that URL's own `redirect_uri`/`scope` query parameters, and
//! [`resolve_client`] returns it before ever reaching the network.
//!
//! No other `client_id` may name a port: the profile says "there must not
//! be a port number included". A development deployment reaches a client
//! serving on another port through [`didbot_identity::did::RESOLVE_PORTS`],
//! as it reaches a `did:web`.

use std::collections::HashMap;
use std::sync::RwLock;

use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use time::{Duration, OffsetDateTime};

use crate::oauth::client_auth::{self, ClientAuthentication, Jwks};

/// How long a fetched document is trusted before it is fetched again.
///
/// Short on purpose: `plan/app-allowlist.md` treats a redirect-URI change as
/// a new app, and the whole point of keying on content is that this server
/// notices a change quickly rather than trusting a stale document for a
/// deployment's whole uptime.
pub const CACHE_TTL: Duration = Duration::minutes(15);

/// How many distinct `client_id`s [`MemoryClientMetadataCache`] holds at
/// once.
///
/// `POST /oauth/par` is unauthenticated and the `client_id` it names is the
/// caller's to choose, so every distinct string a caller invents is a
/// cacheable entry. Without a bound that map only ever grows, which is a way
/// to spend this server's memory while holding no credential. Past it the
/// cache drops what it has held longest, so a spree of invented ids costs a
/// re-fetch for the real clients rather than the process.
pub const CACHE_CAPACITY: usize = 512;

/// How long the whole client metadata fetch may take — connect, headers and
/// body together, not just the handshake.
///
/// `client_id` is chosen by an unauthenticated caller, so the host on the
/// other end of this GET is one an attacker picks. A `connect_timeout` alone
/// would not bound a server that completes its handshake and then trickles
/// the body forever; this is the total deadline, applied per request so it
/// holds whichever [`reqwest::Client`] a deployment wires in.
///
/// Ten seconds because that is what [`crate::relay::REQUEST_TIMEOUT`] — the
/// only other outbound HTTP deadline this crate sets — already uses, and it
/// sits comfortably inside `crate::routes::REQUEST_TIMEOUT`'s thirty seconds
/// for the inbound request this fetch happens underneath.
pub const FETCH_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);

/// The most of a client metadata document this server will read before
/// giving up on it.
///
/// The body is read against this bound rather than to completion, so a host
/// answering a `client_id` fetch with an endless stream costs this process a
/// bounded amount of memory rather than all of it. Sixty-four kibibytes is
/// this workspace's ceiling on a small JSON document read off input it does
/// not control, and is orders of magnitude more than the handful of fields
/// [`ClientMetadataDocument`] keeps.
pub const MAX_DOCUMENT_BYTES: usize = 64 * 1024;

/// A validated client metadata document.
///
/// Reduced to the fields this server's endpoints and `plan/app-allowlist.md`
/// need. `plan/app-allowlist.md` also asks that `client_name`, `client_uri`
/// and `logo_uri` be recorded and never displayed, since showing an
/// untrusted client's own self-description to anyone is how impersonation
/// works — this server has no human to show them to, so that requirement is
/// met by construction, and they are kept here only for the log line that
/// records them.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ClientMetadataDocument {
    /// Must equal the URL it was fetched from; checked in [`validate`].
    pub client_id: String,
    /// What kind of client this is, which decides the redirects it may
    /// register. Left out of the content key when it is the default, so a
    /// document that says `web` and one that says nothing hash alike.
    #[serde(default, skip_serializing_if = "ApplicationType::is_web")]
    pub application_type: ApplicationType,
    /// The applicant's own name for itself. Never displayed; see the module
    /// doc.
    pub client_name: Option<String>,
    /// The applicant's own homepage. Never displayed.
    pub client_uri: Option<String>,
    /// The applicant's own logo. Never displayed.
    pub logo_uri: Option<String>,
    /// Where an authorization code may be delivered. Never empty after
    /// validation.
    pub redirect_uris: Vec<String>,
    /// OAuth grant types this client uses. Defaults to
    /// `["authorization_code"]` when absent.
    pub grant_types: Vec<String>,
    /// OAuth response types this client uses. Defaults to `["code"]`.
    pub response_types: Vec<String>,
    /// How this client authenticates at `par` and `token`; see
    /// [`crate::oauth::client_auth`].
    #[serde(flatten)]
    pub authentication: ClientAuthentication,
    /// The scope this client declares it may ask for, if it published one.
    pub scope: Option<String>,
    /// Must be `true`: the atproto OAuth profile requires every access token
    /// to be DPoP-bound, and a client that has not opted into that is not
    /// one this server's tokens can be issued to.
    pub dpop_bound_access_tokens: bool,
}

/// A document's `application_type`, which the atproto profile borrows from
/// OpenID Connect. Absent, it is `web`; any other word refuses the document.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ApplicationType {
    /// A web service or a browser app. Its redirects are `https://`, or
    /// `http://` on a loopback host.
    #[default]
    Web,
    /// A mobile or desktop app. Its redirects follow the profile's rules for
    /// native clients; see `is_native_redirect_uri` (this module, private).
    Native,
}

impl ApplicationType {
    fn is_web(&self) -> bool {
        *self == Self::Web
    }
}

/// Why a client metadata document could not be used.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum ClientMetadataError {
    /// `client_id` is not an `https://` URL (loopback `http://` is the one
    /// exception, for development, mirroring `didbot_identity`'s own
    /// loopback carve-out for `did:web`).
    #[error("client_id `{0}` must be an https:// URL")]
    NotHttps(String),
    /// `client_id` has a fragment, which the spec forbids — a fragment is
    /// never sent to a server, so two client IDs differing only in one would
    /// be indistinguishable to anyone fetching them.
    #[error("client_id `{0}` may not contain a fragment")]
    HasFragment(String),
    /// `client_id` names a port, which the profile forbids outside its
    /// `http://localhost` form.
    #[error("client_id `{0}` may not name a port")]
    HasPort(String),
    /// The document could not be fetched at all.
    #[error("fetching client metadata for `{0}` failed: {1}")]
    Fetch(String, String),
    /// The document did not parse as the expected shape.
    #[error("client metadata document at `{0}` did not parse: {1}")]
    Malformed(String, String),
    /// The document's own `client_id` did not equal the URL it was served
    /// from — the binding the whole scheme depends on.
    #[error("document at `{fetched_from}` claims client_id `{claimed}`, which does not match")]
    ClientIdMismatch {
        /// The URL this server fetched.
        fetched_from: String,
        /// What the document claimed instead.
        claimed: String,
    },
    /// No `redirect_uris`, or every one of them is unusable.
    #[error("client metadata for `{0}` has no usable redirect_uris")]
    NoRedirectUris(String),
    /// A web client's `redirect_uris` entry is not `https://`, or carries a
    /// fragment.
    #[error("a web client's redirect_uri `{0}` must be https:// with no fragment")]
    BadRedirectUri(String),
    /// A native client's `redirect_uris` entry breaks the profile's rules for
    /// native clients; see `is_native_redirect_uri` (this module, private).
    #[error(
        "a native client's redirect_uri `{0}` must be its client_id's host in reverse-domain \
         order followed by `:/` and a path, https:// on its client_id's origin, or http:// on \
         127.0.0.1 or [::1], with no fragment"
    )]
    BadNativeRedirectUri(String),
    /// The fetch did not stay at `client_id`.
    ///
    /// A client metadata document *is* its `client_id`: the URL is the
    /// registration. A redirect means the document was served by something
    /// other than the identifier it claims, and nothing downstream re-checks
    /// where it actually landed — [`validate`] compares the document against
    /// the requested `client_id`, so an open redirect at an otherwise
    /// well-behaved `client_id` host would let a third party supply that
    /// host's registration. Refused rather than capped for that reason.
    #[error("client metadata fetch for `{client_id}` was redirected to `{to}`")]
    Redirected {
        /// The `client_id` that was requested.
        client_id: String,
        /// Where the response tried to send this server instead.
        to: String,
    },
    /// The fetch was answered with a status other than `200 OK`, which the
    /// profile requires ("not another 2xx or a redirect").
    #[error("client metadata fetch for `{client_id}` answered {status}, not 200 OK")]
    NotOk {
        /// The `client_id` whose document, or key set, was fetched.
        client_id: String,
        /// What the fetch was answered with.
        status: reqwest::StatusCode,
    },
    /// The document was not served as `application/json`, which the profile
    /// requires.
    #[error(
        "client metadata for `{client_id}` was served as `{content_type}`, not application/json"
    )]
    NotJson {
        /// The `client_id` whose document was fetched.
        client_id: String,
        /// The `Content-Type` it was served with, or nothing.
        content_type: String,
    },
    /// The document is larger than [`MAX_DOCUMENT_BYTES`].
    #[error("client metadata document at `{0}` is larger than {MAX_DOCUMENT_BYTES} bytes")]
    TooLarge(String),
    /// `dpop_bound_access_tokens` was absent or `false`.
    #[error("client metadata for `{0}` does not opt into DPoP-bound access tokens")]
    NotDpopBound(String),
    /// `token_endpoint_auth_method` is neither `none` nor `private_key_jwt`.
    #[error(
        "client metadata for `{0}` names a token_endpoint_auth_method this server does not accept"
    )]
    UnsupportedAuthMethod(String),
    /// `token_endpoint_auth_signing_alg` is `none`, or a confidential client
    /// names no algorithm this server verifies.
    #[error(
        "client metadata for `{0}` names no token_endpoint_auth_signing_alg this server verifies"
    )]
    UnsupportedSigningAlg(String),
    /// A confidential client publishes no key a client assertion can be
    /// checked against.
    #[error(
        "client metadata for `{0}` publishes no key a client assertion can be checked against"
    )]
    NoClientKeys(String),
    /// A confidential client names both `jwks` and `jwks_uri`, which the
    /// atproto profile forbids.
    #[error("client metadata for `{0}` names both jwks and jwks_uri")]
    TwoKeySets(String),
    /// `jwks_uri` is not `https://` (or loopback `http://` on a deployment
    /// that fetches from its own machine), or carries a fragment.
    #[error("jwks_uri `{0}` must be https://, or http:// on a loopback host, with no fragment")]
    BadJwksUri(String),
    /// A loopback `client_id`'s `redirect_uri` query parameter named a host
    /// other than `127.0.0.1` or `[::1]` — the atproto profile's "Localhost
    /// Client Development" form allows any port on either, and nothing
    /// else, including `localhost` itself.
    #[error("loopback redirect_uri `{0}` must be http://127.0.0.1 or http://[::1], any port")]
    LoopbackRedirectUri(String),
    /// `client_id`'s host is, or resolves to, an address outside
    /// [`didbot_http::REFUSED_BLOCKS`] — this deployment's own network
    /// rather than the public internet.
    #[error("client_id `{0}` resolves to an address this server will not fetch from")]
    RefusedAddress(String),
}

/// A client for fetching `url`, pinned to the addresses its host resolves
/// to, and refused unless every one of them is one
/// [`didbot_http::is_public_address`] allows.
///
/// `POST /oauth/par` is unauthenticated and `client_id` is a URL the caller
/// chose, so without this the fetch is a request this server makes into
/// whatever network it is deployed in, aimed by a stranger. The pin is what
/// keeps the check true at connect time: a client that resolved the name
/// again could be answered with a private address the second time.
///
/// Every refusal is the same answer: a host that resolves to nothing at all
/// is refused here rather than left to fail in the fetch, so that both
/// outcomes cost the same and neither is distinguishable from the other --
/// see [`resolve_client`].
async fn pinned_public_client(
    client_id: &str,
    url: &reqwest::Url,
) -> Result<reqwest::Client, ClientMetadataError> {
    didbot_http::pinned_client(url, didbot_http::PrivateAddresses::Refused)
        .await
        .map_err(|error| match error {
            didbot_http::AddressError::NoClient { message, .. } => {
                ClientMetadataError::Fetch(client_id.to_owned(), message)
            }
            _ => ClientMetadataError::RefusedAddress(url.to_string()),
        })
}

/// Whether this deployment will fetch a client metadata document over
/// loopback `http://`.
///
/// A development client serves its document from its own machine, which
/// this server would then fetch. On a real deployment that is an outbound
/// GET to the machine running the PDS, with the outcome readable from the
/// error it answers: a probe of its own network reachable from an
/// unauthenticated endpoint. A deployment under `.localhost` is a
/// development one and needs the fetch; every other deployment refuses it.
///
/// The profile's `http://localhost` `client_id` form is built here from its
/// own query and fetches nothing, so every deployment accepts it; see
/// `parse_loopback_client_id`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LoopbackClients {
    /// Fetch them — a development deployment.
    Fetched,
    /// Refuse them.
    Refused,
}

impl LoopbackClients {
    /// What a deployment serving `zone` does. `.localhost` and `localhost`
    /// itself are development zones; nothing else is.
    pub fn for_zone(zone: &str) -> Self {
        let zone = zone.trim_end_matches('.').to_ascii_lowercase();
        if zone == "localhost" || zone.ends_with(".localhost") {
            Self::Fetched
        } else {
            Self::Refused
        }
    }
}

/// Checks a URL is `https://` (or loopback `http://`) with no fragment.
fn validate_url_scheme(raw: &str) -> Result<reqwest::Url, ()> {
    let url = reqwest::Url::parse(raw).map_err(|_| ())?;
    let ok_scheme =
        url.scheme() == "https" || (url.scheme() == "http" && didbot_http::is_loopback(&url));
    if !ok_scheme || url.fragment().is_some() {
        return Err(());
    }
    Ok(url)
}

/// Whether `raw` is a usable loopback redirect URI: `http://127.0.0.1` or
/// `http://[::1]`, any port, per the atproto profile's "Localhost Client
/// Development" form. Stricter than [`didbot_http::is_loopback`] on
/// purpose — that one also accepts the literal name `localhost`, which this
/// form forbids for a redirect.
fn is_loopback_redirect_uri(raw: &str) -> bool {
    let Ok(url) = reqwest::Url::parse(raw) else {
        return false;
    };
    // `Url::host_str` keeps an IPv6 literal's brackets (`"[::1]"`), unlike
    // `Url::host()`'s `HostAddr::Ipv6`.
    url.scheme() == "http" && matches!(url.host_str(), Some("127.0.0.1") | Some("[::1]"))
}

/// Whether a web client may register `raw` as a redirect: the profile says
/// a web client's redirect "is a HTTPS URL". A loopback `http://` redirect
/// belongs to a native client.
fn is_web_redirect_uri(raw: &str) -> bool {
    reqwest::Url::parse(raw).is_ok_and(|url| url.scheme() == "https" && url.fragment().is_none())
}

/// Whether a native client named `client_id` may register `raw` as a
/// redirect, by the atproto profile's rules for native clients.
///
/// A custom scheme must be the `client_id`'s host in reverse-domain order,
/// followed by a single `:/` and a path: `com.example.app:/callback` for
/// `https://app.example.com/...`. An `https://` redirect must be on the
/// `client_id`'s own origin. An `http://` one is the loopback form
/// [`is_loopback_redirect_uri`] accepts. None may carry a fragment.
fn is_native_redirect_uri(client_id: &str, raw: &str) -> bool {
    let (Ok(client), Ok(url)) = (reqwest::Url::parse(client_id), reqwest::Url::parse(raw)) else {
        return false;
    };
    if url.fragment().is_some() {
        return false;
    }
    match url.scheme() {
        "https" => url.origin() == client.origin(),
        "http" => is_loopback_redirect_uri(raw),
        scheme => {
            let Some(host) = client.host_str() else {
                return false;
            };
            let reversed = host.rsplit('.').collect::<Vec<_>>().join(".");
            // The serialization starts with the scheme and its colon.
            let rest = &url.as_str()[scheme.len() + 1..];
            scheme == reversed && rest.starts_with('/') && !rest.starts_with("//")
        }
    }
}

impl ClientMetadataDocument {
    /// Whether a push may name `requested` as its redirect.
    ///
    /// Exact, except for a loopback redirect (`http://127.0.0.1` or
    /// `http://[::1]`), which matches on everything but the port. A native
    /// client listens on whatever port it is handed when it starts: RFC 8252
    /// §7.3 says "the authorization server MUST allow any port to be
    /// specified at the time of the request for loopback IP redirect URIs",
    /// and the atproto profile says of its loopback clients "Path components
    /// must match, but port numbers are not matched."
    pub fn admits_redirect_uri(&self, requested: &str) -> bool {
        self.redirect_uris.iter().any(|registered| {
            registered == requested || same_loopback_redirect(registered, requested)
        })
    }
}

/// Whether `requested` is the loopback redirect `registered`, on any port.
///
/// Both are parsed, so `http://127.0.0.1` and `http://127.0.0.1/` are the
/// same redirect, as they are to the client that listens on it.
fn same_loopback_redirect(registered: &str, requested: &str) -> bool {
    if !is_loopback_redirect_uri(registered) {
        return false;
    }
    let (Ok(registered), Ok(mut requested)) = (
        reqwest::Url::parse(registered),
        reqwest::Url::parse(requested),
    ) else {
        return false;
    };
    requested.set_port(registered.port()).is_ok() && requested == registered
}

/// Recognises the atproto OAuth profile's "Localhost Client Development"
/// `client_id` form — exactly `http://localhost`, no port, path empty or
/// `/` — and builds its virtual client metadata document straight from the
/// `redirect_uri` (repeatable) and `scope` query parameters, fetching
/// nothing.
///
/// `None` means `client_id` is not this form, including a `localhost`
/// `client_id` that carries a port or a deeper path, which
/// [`resolve_client`] judges like any other. `Some` carries the
/// built-and-validated document, or the one way building it can fail.
fn parse_loopback_client_id(
    client_id: &str,
) -> Option<Result<ClientMetadataDocument, ClientMetadataError>> {
    let url = reqwest::Url::parse(client_id).ok()?;
    if url.scheme() != "http" {
        return None;
    }
    if !url
        .host_str()
        .is_some_and(|host| host.eq_ignore_ascii_case("localhost"))
    {
        return None;
    }
    if url.port().is_some() {
        return None;
    }
    if !matches!(url.path(), "" | "/") {
        return None;
    }

    let mut redirect_uris: Vec<String> = url
        .query_pairs()
        .filter(|(key, _)| key == "redirect_uri")
        .map(|(_, value)| value.into_owned())
        .collect();
    if redirect_uris.is_empty() {
        redirect_uris = vec!["http://127.0.0.1/".to_owned(), "http://[::1]/".to_owned()];
    }
    for redirect_uri in &redirect_uris {
        if !is_loopback_redirect_uri(redirect_uri) {
            return Some(Err(ClientMetadataError::LoopbackRedirectUri(
                redirect_uri.clone(),
            )));
        }
    }

    let scope = url
        .query_pairs()
        .find(|(key, _)| key == "scope")
        .map(|(_, value)| value.into_owned())
        .unwrap_or_else(|| "atproto".to_owned());

    Some(Ok(ClientMetadataDocument {
        client_id: client_id.to_owned(),
        // The profile's virtual document for this form says so.
        application_type: ApplicationType::Native,
        client_name: None,
        client_uri: None,
        logo_uri: None,
        redirect_uris,
        grant_types: vec!["authorization_code".to_owned(), "refresh_token".to_owned()],
        response_types: vec!["code".to_owned()],
        authentication: ClientAuthentication::public(),
        scope: Some(scope),
        dpop_bound_access_tokens: true,
    }))
}

/// Validates a raw fetched document against `client_id`, the URL it was
/// fetched from.
pub fn validate(
    client_id: &str,
    mut document: ClientMetadataDocument,
) -> Result<ClientMetadataDocument, ClientMetadataError> {
    if document.client_id != client_id {
        return Err(ClientMetadataError::ClientIdMismatch {
            fetched_from: client_id.to_owned(),
            claimed: document.client_id,
        });
    }
    if document.grant_types.is_empty() {
        document.grant_types = vec!["authorization_code".to_owned()];
    }
    if document.response_types.is_empty() {
        document.response_types = vec!["code".to_owned()];
    }
    if document.redirect_uris.is_empty() {
        return Err(ClientMetadataError::NoRedirectUris(client_id.to_owned()));
    }
    for redirect_uri in &document.redirect_uris {
        match document.application_type {
            ApplicationType::Web if !is_web_redirect_uri(redirect_uri) => {
                return Err(ClientMetadataError::BadRedirectUri(redirect_uri.clone()));
            }
            ApplicationType::Native if !is_native_redirect_uri(client_id, redirect_uri) => {
                return Err(ClientMetadataError::BadNativeRedirectUri(
                    redirect_uri.clone(),
                ));
            }
            _ => {}
        }
    }
    if !document.dpop_bound_access_tokens {
        return Err(ClientMetadataError::NotDpopBound(client_id.to_owned()));
    }
    check_authentication(client_id, &document.authentication)?;
    Ok(document)
}

/// Refuses what the atproto profile's "Confidential Client Authentication"
/// refuses of a document's client authentication fields.
///
/// A confidential client's `jwks_uri` is checked here as a URL and fetched by
/// [`resolve_client`].
fn check_authentication(
    client_id: &str,
    authentication: &ClientAuthentication,
) -> Result<(), ClientMetadataError> {
    let alg = authentication.token_endpoint_auth_signing_alg.as_deref();
    // "`none` is never allowed here", whichever method the client names.
    if alg == Some("none") {
        return Err(ClientMetadataError::UnsupportedSigningAlg(
            client_id.to_owned(),
        ));
    }
    match authentication.token_endpoint_auth_method.as_str() {
        client_auth::NONE => Ok(()),
        client_auth::PRIVATE_KEY_JWT => {
            if alg != Some(client_auth::SIGNING_ALG) {
                return Err(ClientMetadataError::UnsupportedSigningAlg(
                    client_id.to_owned(),
                ));
            }
            match (&authentication.jwks, &authentication.jwks_uri) {
                (Some(_), Some(_)) => Err(ClientMetadataError::TwoKeySets(client_id.to_owned())),
                (Some(jwks), None) if !jwks.is_empty() => Ok(()),
                (None, Some(jwks_uri)) => validate_url_scheme(jwks_uri)
                    .map(drop)
                    .map_err(|()| ClientMetadataError::BadJwksUri(jwks_uri.clone())),
                _ => Err(ClientMetadataError::NoClientKeys(client_id.to_owned())),
            }
        }
        _ => Err(ClientMetadataError::UnsupportedAuthMethod(
            client_id.to_owned(),
        )),
    }
}

/// A validated document's own identity, for [`ClientMetadataCache`] and for
/// `plan/app-allowlist.md`'s "an admitted app that changes its redirect URIs
/// is a different app" — computed over the document's content, so two
/// fetches of the same `client_id` that disagree produce two different keys.
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct ClientKey(pub String);

impl ClientKey {
    /// Hashes a validated document into its key.
    ///
    /// `serde_json::to_vec` over a `struct` (rather than a `Value` built from
    /// a `HashMap`) is deterministic — struct fields serialize in
    /// declaration order — so the same document always hashes the same way,
    /// which is the one property this has to have.
    pub fn compute(document: &ClientMetadataDocument) -> Self {
        let bytes = serde_json::to_vec(document)
            .expect("ClientMetadataDocument has no non-serializable field");
        let digest = Sha256::digest(bytes);
        Self(hex::encode(digest))
    }
}

/// A cached, validated document plus when it was fetched.
#[derive(Debug, Clone)]
pub struct CachedClientMetadata {
    /// The document as validated.
    pub document: ClientMetadataDocument,
    /// The document's content key; see [`ClientKey`].
    pub key: ClientKey,
    /// When this entry was fetched, for [`CACHE_TTL`] expiry.
    pub fetched_at: OffsetDateTime,
}

/// Where fetched client metadata is cached, keyed by `client_id`.
///
/// A cache hit still names the document by its [`ClientKey`], which is what
/// `plan/app-allowlist.md`'s admission check keys its list on — the cache is
/// keyed by URL because that is what a client presents, and it hands back
/// the content key alongside the document so a caller never has to choose
/// which one to trust.
pub trait ClientMetadataCache: Send + Sync {
    /// A fresh cached entry for `client_id`, if one exists and has not
    /// expired.
    fn get(&self, client_id: &str) -> Option<CachedClientMetadata>;
    /// Stores (or replaces) the entry for `client_id`.
    fn put(&self, client_id: &str, entry: CachedClientMetadata);
}

/// The in-process client metadata cache.
#[derive(Debug, Default)]
pub struct MemoryClientMetadataCache {
    entries: RwLock<HashMap<String, CachedClientMetadata>>,
}

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

impl ClientMetadataCache for MemoryClientMetadataCache {
    fn get(&self, client_id: &str) -> Option<CachedClientMetadata> {
        let entries = self
            .entries
            .read()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        let entry = entries.get(client_id)?;
        if OffsetDateTime::now_utc() - entry.fetched_at > CACHE_TTL {
            return None;
        }
        Some(entry.clone())
    }

    /// Stores the entry, dropping expired ones first and then the entry
    /// held longest if the cache is still at [`CACHE_CAPACITY`].
    ///
    /// Swept on write, the way `oauth::par`'s and `oauth::consent`'s own
    /// stores sweep theirs: no background task, and a caller's cost does not
    /// grow with how many other callers there are.
    fn put(&self, client_id: &str, entry: CachedClientMetadata) {
        let now = OffsetDateTime::now_utc();
        let mut entries = self
            .entries
            .write()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        entries.retain(|_, held| now - held.fetched_at <= CACHE_TTL);
        while entries.len() >= CACHE_CAPACITY && !entries.contains_key(client_id) {
            let Some(oldest) = entries
                .iter()
                .min_by_key(|(_, held)| held.fetched_at)
                .map(|(id, _)| id.clone())
            else {
                break;
            };
            entries.remove(&oldest);
        }
        entries.insert(client_id.to_owned(), entry);
    }
}

/// Where a response landed, if that is not `requested`.
///
/// Covers both halves of the redirect question at once, so the answer does
/// not depend on how the caller's [`reqwest::Client`] is configured: a client
/// that follows redirects arrives with a different [`reqwest::Response::url`],
/// and one that does not arrives with a 3xx status still sitting at the
/// requested URL. Either way the document did not come from `client_id`.
fn redirected_away_from(requested: &reqwest::Url, response: &reqwest::Response) -> Option<String> {
    if response.url() != requested {
        return Some(response.url().to_string());
    }
    if !response.status().is_redirection() {
        return None;
    }
    let location = response
        .headers()
        .get(reqwest::header::LOCATION)
        .and_then(|value| value.to_str().ok())
        .map(str::to_owned);
    Some(location.unwrap_or_else(|| response.status().to_string()))
}

/// Reads at most [`MAX_DOCUMENT_BYTES`] of a response body.
///
/// A declared `Content-Length` over the bound is refused without reading
/// anything; a body that lies about its length, or declines to declare one,
/// is refused the moment it crosses the bound. Neither path ever holds more
/// than one chunk past [`MAX_DOCUMENT_BYTES`] in memory.
async fn read_bounded(
    client_id: &str,
    mut response: reqwest::Response,
) -> Result<Vec<u8>, ClientMetadataError> {
    if response
        .content_length()
        .is_some_and(|len| len > MAX_DOCUMENT_BYTES as u64)
    {
        return Err(ClientMetadataError::TooLarge(client_id.to_owned()));
    }
    let mut body = Vec::new();
    while let Some(chunk) = response
        .chunk()
        .await
        .map_err(|err| ClientMetadataError::Fetch(client_id.to_owned(), err.to_string()))?
    {
        if body.len() + chunk.len() > MAX_DOCUMENT_BYTES {
            tracing::debug!(
                client_id,
                max_bytes = MAX_DOCUMENT_BYTES,
                "abandoning an oversized client metadata document mid-body"
            );
            return Err(ClientMetadataError::TooLarge(client_id.to_owned()));
        }
        body.extend_from_slice(&chunk);
    }
    Ok(body)
}

/// Fetches, validates, and caches the client metadata document for
/// `client_id`.
///
/// A cache hit skips the network entirely. A miss fetches over `http`,
/// validates the result, and stores it — keyed by the URL, carrying the
/// content key — before returning it. A confidential client's `jwks_uri` is
/// fetched on the same miss, under the same bounds, and cached with the
/// document, so its keys are read again whenever the document is.
///
/// `client_id` is attacker-chosen on the one endpoint that reaches this
/// ([`crate::oauth::par`], which is unauthenticated), so the fetch is bounded
/// here rather than left to whichever client is passed: the host must
/// resolve to a public address ([`didbot_http::REFUSED_BLOCKS`]) and the
/// fetch connects to the addresses that check approved,
/// [`FETCH_TIMEOUT`] is a
/// per-request total deadline, [`MAX_DOCUMENT_BYTES`] bounds the body, no
/// redirect is followed at all — see [`ClientMetadataError::Redirected`] —
/// and only a `200 OK` served as `application/json` is read.
/// `http` makes the fetch only on a deployment that reaches its own machine
/// ([`LoopbackClients::Fetched`]); every other one fetches through
/// `pinned_public_client`.
///
/// Every variant this returns reaches `POST /oauth/par`'s caller as one
/// sentence that names none of them — see
/// [`crate::oauth::par::ParError::ClientMetadata`] — so the distinctions
/// here are for this deployment's own log.
pub async fn resolve_client(
    http: &reqwest::Client,
    cache: &dyn ClientMetadataCache,
    client_id: &str,
    loopback: LoopbackClients,
) -> Result<(ClientMetadataDocument, ClientKey), ClientMetadataError> {
    if let Some(built) = parse_loopback_client_id(client_id) {
        let document = validate(client_id, built?)?;
        let key = ClientKey::compute(&document);
        return Ok((document, key));
    }
    if let Some(cached) = cache.get(client_id) {
        return Ok((cached.document, cached.key));
    }
    let url = validate_url_scheme(client_id)
        .map_err(|()| ClientMetadataError::NotHttps(client_id.to_owned()))?;
    // Before the fetch, and answering exactly what a non-HTTPS `client_id`
    // answers: this deployment does not reach loopback on a caller's say-so.
    if url.scheme() == "http" && loopback == LoopbackClients::Refused {
        return Err(ClientMetadataError::NotHttps(client_id.to_owned()));
    }
    if url.port().is_some() {
        return Err(ClientMetadataError::HasPort(client_id.to_owned()));
    }
    if url.fragment().is_some() {
        return Err(ClientMetadataError::HasFragment(client_id.to_owned()));
    }
    let body = fetch_bounded(http, client_id, &url, loopback, true).await?;
    let raw: ClientMetadataDocument = serde_json::from_slice(&body)
        .map_err(|err| ClientMetadataError::Malformed(client_id.to_owned(), err.to_string()))?;
    let mut document = validate(client_id, raw)?;
    if document.authentication.is_confidential() {
        if let Some(jwks_uri) = document.authentication.jwks_uri.clone() {
            document.authentication.jwks_uri_keys =
                Some(fetch_jwks(http, client_id, &jwks_uri, loopback).await?);
        }
    }
    let key = ClientKey::compute(&document);
    cache.put(
        client_id,
        CachedClientMetadata {
            document: document.clone(),
            key: key.clone(),
            fetched_at: OffsetDateTime::now_utc(),
        },
    );
    Ok((document, key))
}

/// GETs `url` on `client_id`'s behalf, under every bound [`resolve_client`]
/// names: [`FETCH_TIMEOUT`] for the whole fetch, [`MAX_DOCUMENT_BYTES`] for
/// the body, and no redirect. Only a `200 OK` is read, and when `json_only`,
/// only one served as `application/json`.
///
/// On a deployment that reaches its own machine the fetch goes through
/// `http`, to the port [`didbot_identity::did::RESOLVE_PORTS`] names for a
/// loopback host when `url` names none. Every other deployment fetches
/// through a client pinned to the addresses `url`'s host resolves to,
/// refused unless every one of them is public. That is the same gate the
/// loopback carve-out is on, and deliberately so:
/// `LoopbackClients::for_zone` is the one place that decides which
/// deployments may reach their own machine.
async fn fetch_bounded(
    http: &reqwest::Client,
    client_id: &str,
    url: &reqwest::Url,
    loopback: LoopbackClients,
    json_only: bool,
) -> Result<Vec<u8>, ClientMetadataError> {
    let pinned;
    let mut url = url.clone();
    let http = match loopback {
        LoopbackClients::Fetched => {
            let named = url.host_str().and_then(didbot_identity::did::resolve_port);
            if let (None, Some(port)) = (url.port(), named) {
                tracing::debug!(client_id, %url, port, "fetching on the port RESOLVE_PORTS names");
                // Fails only for a URL with no host, and this one has one.
                let _ = url.set_port(Some(port));
            }
            http
        }
        LoopbackClients::Refused => {
            pinned = pinned_public_client(client_id, &url).await?;
            &pinned
        }
    };
    let response = http
        .get(url.clone())
        .timeout(FETCH_TIMEOUT)
        .send()
        .await
        .map_err(|err| ClientMetadataError::Fetch(client_id.to_owned(), err.to_string()))?;
    if let Some(to) = redirected_away_from(&url, &response) {
        tracing::debug!(
            client_id,
            %url,
            %to,
            "refusing client metadata served from somewhere other than the URL fetched"
        );
        return Err(ClientMetadataError::Redirected {
            client_id: client_id.to_owned(),
            to,
        });
    }
    if response.status() != reqwest::StatusCode::OK {
        return Err(ClientMetadataError::NotOk {
            client_id: client_id.to_owned(),
            status: response.status(),
        });
    }
    if json_only {
        let served = response
            .headers()
            .get(reqwest::header::CONTENT_TYPE)
            .and_then(|value| value.to_str().ok())
            .unwrap_or_default();
        let matches = served
            .parse::<mime::Mime>()
            .is_ok_and(|served| served.essence_str() == mime::APPLICATION_JSON.essence_str());
        if !matches {
            return Err(ClientMetadataError::NotJson {
                client_id: client_id.to_owned(),
                content_type: served.to_owned(),
            });
        }
    }
    read_bounded(client_id, response).await
}

/// The key set a confidential client publishes at `jwks_uri`, fetched the way
/// its document is ([`fetch_bounded`]).
async fn fetch_jwks(
    http: &reqwest::Client,
    client_id: &str,
    jwks_uri: &str,
    loopback: LoopbackClients,
) -> Result<Jwks, ClientMetadataError> {
    let url = validate_url_scheme(jwks_uri)
        .map_err(|()| ClientMetadataError::BadJwksUri(jwks_uri.to_owned()))?;
    // Before the fetch, as for a `client_id`: this deployment does not reach
    // loopback on a caller's say-so.
    if url.scheme() == "http" && loopback == LoopbackClients::Refused {
        return Err(ClientMetadataError::BadJwksUri(jwks_uri.to_owned()));
    }
    let body = fetch_bounded(http, client_id, &url, loopback, false).await?;
    let keys: Jwks = serde_json::from_slice(&body)
        .map_err(|err| ClientMetadataError::Malformed(jwks_uri.to_owned(), err.to_string()))?;
    if keys.is_empty() {
        return Err(ClientMetadataError::NoClientKeys(client_id.to_owned()));
    }
    Ok(keys)
}

/// `crate::oauth::par`'s own tests need a stand-in `client_id` host too, and
/// this module already has one.
#[cfg(test)]
pub(crate) use tests::{
    client_host as tests_client_host, reaching as tests_reaching, HOST as TESTS_HOST,
};

#[cfg(test)]
mod tests {
    use axum::response::{IntoResponse, Redirect};
    use axum::routing::get;
    use axum::Router;
    use tokio::io::AsyncWriteExt;
    use tokio::net::TcpListener;

    use super::*;

    fn doc(client_id: &str, redirect_uris: Vec<&str>) -> ClientMetadataDocument {
        ClientMetadataDocument {
            client_id: client_id.to_owned(),
            application_type: ApplicationType::Web,
            client_name: Some("Placeholder Zydeco".to_owned()),
            client_uri: None,
            logo_uri: None,
            redirect_uris: redirect_uris.into_iter().map(str::to_owned).collect(),
            grant_types: vec![],
            response_types: vec![],
            authentication: ClientAuthentication::public(),
            scope: None,
            dpop_bound_access_tokens: true,
        }
    }

    #[test]
    fn validate_defaults_grant_and_response_types() {
        let d = validate(
            "https://client.example/id.json",
            doc(
                "https://client.example/id.json",
                vec!["https://client.example/cb"],
            ),
        )
        .unwrap();
        assert_eq!(d.grant_types, vec!["authorization_code"]);
        assert_eq!(d.response_types, vec!["code"]);
    }

    #[test]
    fn client_id_must_match_the_document() {
        let err = validate(
            "https://client.example/id.json",
            doc(
                "https://someone-else.example/id.json",
                vec!["https://client.example/cb"],
            ),
        )
        .unwrap_err();
        assert!(matches!(err, ClientMetadataError::ClientIdMismatch { .. }));
    }

    #[test]
    fn empty_redirect_uris_is_refused() {
        let err = validate(
            "https://client.example/id.json",
            doc("https://client.example/id.json", vec![]),
        )
        .unwrap_err();
        assert!(matches!(err, ClientMetadataError::NoRedirectUris(_)));
    }

    /// A web client's redirect is `https://`, on any origin and any port.
    /// A loopback `http://` redirect is a native client's, so a web client
    /// may not register one either.
    #[test]
    fn a_web_client_registers_only_https_redirects() {
        let client_id = "https://client.example/id.json";
        let web = |redirect_uri: &str| validate(client_id, doc(client_id, vec![redirect_uri]));
        for admitted in [
            "https://client.example/cb",
            "https://elsewhere.example:8443/cb",
        ] {
            assert!(web(admitted).is_ok(), "{admitted}");
        }
        for refused in [
            "http://evil.example/cb",
            "http://127.0.0.1/cb",
            "http://[::1]:4000/cb",
            "http://localhost:4000/cb",
            "https://client.example/cb#done",
        ] {
            assert_eq!(
                web(refused).unwrap_err(),
                ClientMetadataError::BadRedirectUri(refused.to_owned()),
                "{refused}"
            );
        }
    }

    #[test]
    fn loopback_client_id_with_redirect_uri_and_scope_builds_its_own_document() {
        let client_id =
            "http://localhost/?redirect_uri=http%3A%2F%2F127.0.0.1%3A5555%2Fcb&scope=atproto+transition%3Ageneric";
        let document = parse_loopback_client_id(client_id)
            .expect("recognised as the loopback form")
            .expect("builds");
        assert_eq!(document.client_id, client_id);
        assert_eq!(document.redirect_uris, vec!["http://127.0.0.1:5555/cb"]);
        assert_eq!(
            document.scope.as_deref(),
            Some("atproto transition:generic")
        );
        assert_eq!(
            document.grant_types,
            vec!["authorization_code", "refresh_token"]
        );
        assert_eq!(document.response_types, vec!["code"]);
        assert_eq!(document.authentication.token_endpoint_auth_method, "none");
        assert!(document.dpop_bound_access_tokens);
        assert_eq!(document.application_type, ApplicationType::Native);
    }

    /// The atproto profile's rules for a native client's redirects, each
    /// refused on its own.
    #[test]
    fn a_native_client_registers_only_the_redirects_the_profile_allows() {
        let client_id = "https://app.example.com/oauth-client-metadata.json";
        let native = |redirect: &str| {
            validate(
                client_id,
                ClientMetadataDocument {
                    application_type: ApplicationType::Native,
                    ..doc(client_id, vec![redirect])
                },
            )
        };
        for admitted in [
            "com.example.app:/callback",
            "com.example.app:/",
            "https://app.example.com/callback",
            "http://127.0.0.1:4000/callback",
            "http://[::1]/callback",
        ] {
            assert!(native(admitted).is_ok(), "{admitted}");
        }
        for refused in [
            // Not the client_id's host in reverse-domain order.
            "com.example.other:/callback",
            "app.example.com:/callback",
            // Not a single slash after the scheme.
            "com.example.app://callback",
            "com.example.app:///callback",
            "com.example.app:callback",
            "com.example.app:/callback#done",
            // Not the client_id's origin.
            "https://other.example.com/callback",
            "https://app.example.com:8443/callback",
            // Not a loopback address.
            "http://localhost:4000/callback",
            "http://app.example.com/callback",
        ] {
            assert_eq!(
                native(refused).unwrap_err(),
                ClientMetadataError::BadNativeRedirectUri(refused.to_owned()),
                "{refused}"
            );
        }
    }

    /// A custom scheme is a native client's, so a web client may not
    /// register one.
    #[test]
    fn a_web_client_may_not_register_a_custom_scheme() {
        let client_id = "https://app.example.com/oauth-client-metadata.json";
        let err =
            validate(client_id, doc(client_id, vec!["com.example.app:/callback"])).unwrap_err();
        assert_eq!(
            err,
            ClientMetadataError::BadRedirectUri("com.example.app:/callback".to_owned())
        );
    }

    /// `application_type` is `web` or `native`, and `web` when absent. A
    /// document saying `web` is the same document as one saying nothing.
    #[test]
    fn application_type_is_web_native_or_absent() {
        let read = |application_type: Option<&str>| {
            let mut document = serde_json::json!({
                "client_id": "https://app.example.com/oauth-client-metadata.json",
                "redirect_uris": ["https://app.example.com/callback"],
                "grant_types": ["authorization_code"],
                "response_types": ["code"],
                "token_endpoint_auth_method": "none",
                "dpop_bound_access_tokens": true,
            });
            if let Some(application_type) = application_type {
                document["application_type"] = application_type.into();
            }
            serde_json::from_value::<ClientMetadataDocument>(document)
        };
        let absent = read(None).expect("absent reads");
        let web = read(Some("web")).expect("web reads");
        let native = read(Some("native")).expect("native reads");
        assert_eq!(absent.application_type, ApplicationType::Web);
        assert_eq!(ClientKey::compute(&absent), ClientKey::compute(&web));
        assert_eq!(native.application_type, ApplicationType::Native);
        assert_ne!(ClientKey::compute(&absent), ClientKey::compute(&native));
        assert!(read(Some("desktop")).is_err());
    }

    #[test]
    fn loopback_client_id_with_neither_param_gets_the_spec_defaults() {
        let document = parse_loopback_client_id("http://localhost")
            .expect("recognised as the loopback form")
            .expect("builds");
        assert_eq!(
            document.redirect_uris,
            vec!["http://127.0.0.1/", "http://[::1]/"]
        );
        assert_eq!(document.scope.as_deref(), Some("atproto"));
    }

    /// A loopback redirect matches on every part but the port, which a
    /// native client learns only when it starts listening. Everything else
    /// matches exactly.
    #[test]
    fn a_loopback_redirect_matches_on_every_part_but_the_port() {
        let defaults = parse_loopback_client_id("http://localhost")
            .expect("recognised as the loopback form")
            .expect("builds");
        for admitted in [
            "http://127.0.0.1:61023/",
            "http://[::1]:61023/",
            // jacquard-oauth's spelling of the first default.
            "http://127.0.0.1",
        ] {
            assert!(defaults.admits_redirect_uri(admitted), "{admitted}");
        }
        for refused in [
            "http://127.0.0.1:61023/elsewhere",
            "http://127.0.0.1:61023/?next=elsewhere",
            "https://127.0.0.1:61023/",
            "http://localhost:61023/",
            "http://127.0.0.2:61023/",
            "http://user@127.0.0.1:61023/",
        ] {
            assert!(!defaults.admits_redirect_uri(refused), "{refused}");
        }

        // A registered port is no more binding than a missing one.
        let named = parse_loopback_client_id(
            "http://localhost/?redirect_uri=http%3A%2F%2F127.0.0.1%3A4000%2Fcallback",
        )
        .expect("recognised as the loopback form")
        .expect("builds");
        assert!(named.admits_redirect_uri("http://127.0.0.1:5000/callback"));

        // A web client's redirect is matched exactly, port and all.
        let web = doc(
            "https://client.example/id.json",
            vec!["https://client.example/cb"],
        );
        assert!(web.admits_redirect_uri("https://client.example/cb"));
        assert!(!web.admits_redirect_uri("https://client.example:8443/cb"));
        assert!(!web.admits_redirect_uri("https://client.example/cb/"));
    }

    #[test]
    fn loopback_client_id_with_a_trailing_slash_is_still_recognised() {
        let document = parse_loopback_client_id("http://localhost/")
            .expect("recognised as the loopback form")
            .expect("builds");
        assert_eq!(
            document.redirect_uris,
            vec!["http://127.0.0.1/", "http://[::1]/"]
        );
    }

    #[test]
    fn loopback_client_ids_redirect_uri_on_localhost_is_refused() {
        let err = parse_loopback_client_id(
            "http://localhost/?redirect_uri=http%3A%2F%2Flocalhost%3A5555%2Fcb",
        )
        .expect("recognised as the loopback form")
        .expect_err("localhost is not a usable loopback redirect_uri");
        assert!(matches!(err, ClientMetadataError::LoopbackRedirectUri(_)));
    }

    #[test]
    fn a_port_on_the_client_id_is_not_the_loopback_form() {
        // `http://localhost:4000/...` is the other, fetchable development
        // carve-out (see `loopback_redirect_uri_is_allowed_for_development`
        // above) — the port alone must be enough to keep this branch from
        // claiming it.
        assert!(parse_loopback_client_id(
            "http://localhost:4000/?redirect_uri=http%3A%2F%2F127.0.0.1%2Fcb"
        )
        .is_none());
    }

    #[test]
    fn a_deeper_path_on_localhost_is_not_the_loopback_form() {
        assert!(parse_loopback_client_id("http://localhost/id.json").is_none());
    }

    #[test]
    fn loopback_clients_with_different_scopes_get_different_keys() {
        let a = parse_loopback_client_id("http://localhost/?scope=atproto")
            .expect("recognised")
            .expect("builds");
        let b = parse_loopback_client_id("http://localhost/?scope=atproto+transition%3Ageneric")
            .expect("recognised")
            .expect("builds");
        assert_ne!(ClientKey::compute(&a), ClientKey::compute(&b));
    }

    #[test]
    fn not_dpop_bound_is_refused() {
        let mut document = doc(
            "https://client.example/id.json",
            vec!["https://client.example/cb"],
        );
        document.dpop_bound_access_tokens = false;
        let err = validate("https://client.example/id.json", document).unwrap_err();
        assert!(matches!(err, ClientMetadataError::NotDpopBound(_)));
    }

    #[test]
    fn changing_redirect_uris_changes_the_client_key() {
        let a = validate(
            "https://client.example/id.json",
            doc(
                "https://client.example/id.json",
                vec!["https://client.example/cb"],
            ),
        )
        .unwrap();
        let b = validate(
            "https://client.example/id.json",
            doc(
                "https://client.example/id.json",
                vec!["https://client.example/new-cb"],
            ),
        )
        .unwrap();
        assert_ne!(ClientKey::compute(&a), ClientKey::compute(&b));
    }

    #[test]
    fn the_same_document_content_is_the_same_key_every_time() {
        let a = doc(
            "https://client.example/id.json",
            vec!["https://client.example/cb"],
        );
        let b = a.clone();
        assert_eq!(ClientKey::compute(&a), ClientKey::compute(&b));
    }

    #[test]
    fn memory_cache_expires_after_ttl() {
        let cache = MemoryClientMetadataCache::new();
        let document = validate(
            "https://client.example/id.json",
            doc(
                "https://client.example/id.json",
                vec!["https://client.example/cb"],
            ),
        )
        .unwrap();
        let key = ClientKey::compute(&document);
        cache.put(
            "https://client.example/id.json",
            CachedClientMetadata {
                document,
                key,
                fetched_at: OffsetDateTime::now_utc() - CACHE_TTL - Duration::seconds(1),
            },
        );
        assert!(cache.get("https://client.example/id.json").is_none());
    }

    /// A metadata document, as JSON, claiming `client_id`.
    fn document_json(client_id: &str) -> String {
        serde_json::json!({
            "client_id": client_id,
            "redirect_uris": ["https://app.example/cb"],
            "grant_types": ["authorization_code"],
            "response_types": ["code"],
            "token_endpoint_auth_method": "none",
            "dpop_bound_access_tokens": true,
        })
        .to_string()
    }

    /// Where every stand-in `client_id` host in these tests is named. A
    /// `client_id` may not carry a port, so each test reaches its host
    /// through [`reaching`].
    pub(crate) const HOST: &str = "http://localhost";

    /// [`crate::oauth::client_metadata_http_client`], but reaching `addr` for
    /// [`HOST`], and following redirects only if `redirects` says so. This
    /// is how a `.localhost` deployment reaches a client that
    /// [`didbot_identity::did::RESOLVE_PORTS`] names, without setting this
    /// process's environment.
    pub(crate) fn reaching(
        addr: std::net::SocketAddr,
        redirects: reqwest::redirect::Policy,
    ) -> reqwest::Client {
        didbot_http::builder()
            .timeout(FETCH_TIMEOUT)
            .redirect(redirects)
            .resolve("localhost", addr)
            .build()
            .expect("a client")
    }

    /// [`reaching`] `addr`, following no redirect, as a deployment's own
    /// client does not.
    fn reaching_only(addr: std::net::SocketAddr) -> reqwest::Client {
        reaching(addr, reqwest::redirect::Policy::none())
    }

    /// A loopback server standing in for [`HOST`], serving four documents:
    /// one well-behaved, one that redirects, one the redirect lands on that
    /// *claims the redirecting URL's own `client_id`* (so a server that
    /// followed the redirect would accept it), and one that is far too large
    /// with an honest `Content-Length`.
    ///
    /// Returns the address it listens on. Every body it serves is bounded —
    /// proving a cap is applied does not require serving anything near a
    /// real flood.
    pub(crate) async fn client_host() -> std::net::SocketAddr {
        let listener = TcpListener::bind("127.0.0.1:0")
            .await
            .expect("loopback binds");
        let addr = listener.local_addr().expect("bound listener has an addr");
        let good = document_json(&format!("{HOST}/id.json"));
        // The document the redirect lands on impersonates the URL that
        // redirected: `validate` compares against the *requested*
        // `client_id`, so nothing downstream would catch this.
        let impersonating = document_json(&format!("{HOST}/moved.json"));
        let oversized = "x".repeat(MAX_DOCUMENT_BYTES + 1);
        let app = Router::new()
            .route("/id.json", get(move || async move { json(good) }))
            .route(
                "/moved.json",
                get(|| async { Redirect::temporary("/elsewhere.json") }),
            )
            .route(
                "/elsewhere.json",
                get(move || async move { json(impersonating) }),
            )
            .route("/huge.json", get(move || async move { json(oversized) }));
        tokio::spawn(async move {
            axum::serve(listener, app)
                .await
                .expect("client host serves");
        });
        addr
    }

    /// One `application/json` response body.
    fn json(body: String) -> axum::response::Response {
        (
            [(axum::http::header::CONTENT_TYPE, "application/json")],
            body,
        )
            .into_response()
    }

    /// A loopback server that answers any request with a chunked body and no
    /// `Content-Length`, so the only thing that can stop it is the streaming
    /// half of [`read_bounded`]. Written by hand rather than through `axum`
    /// so the response genuinely declares no length.
    ///
    /// It writes five sixteen-kibibyte chunks and stops — enough to cross
    /// [`MAX_DOCUMENT_BYTES`], and nothing like a real endless stream.
    async fn chunked_client_host() -> std::net::SocketAddr {
        let listener = TcpListener::bind("127.0.0.1:0")
            .await
            .expect("loopback binds");
        let addr = listener.local_addr().expect("bound listener has an addr");
        tokio::spawn(async move {
            while let Ok((mut socket, _)) = listener.accept().await {
                tokio::spawn(async move {
                    // The request is irrelevant; answer without reading it.
                    let head = "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\n\
                                Transfer-Encoding: chunked\r\n\r\n";
                    if socket.write_all(head.as_bytes()).await.is_err() {
                        return;
                    }
                    let payload = "x".repeat(16 * 1024);
                    for _ in 0..5 {
                        let chunk = format!("{:x}\r\n{payload}\r\n", payload.len());
                        // A broken pipe here is the success case: the reader
                        // gave up partway, which is the point of the test.
                        if socket.write_all(chunk.as_bytes()).await.is_err() {
                            return;
                        }
                    }
                    let _ = socket.write_all(b"0\r\n\r\n").await;
                });
            }
        });
        addr
    }

    /// A `client_id` host that accepts the connection and never answers
    /// costs `/oauth/par` exactly [`FETCH_TIMEOUT`], then a fetch error.
    #[tokio::test(start_paused = true)]
    async fn a_client_id_host_that_never_answers_is_a_fetch_error_after_the_fetch_timeout() {
        let addr = didbot_http::test_support::hung_server();
        let cache = MemoryClientMetadataCache::new();
        let client = reaching_only(addr);
        let client_id = format!("{HOST}/client-metadata.json");
        let started = tokio::time::Instant::now();
        let resolving = resolve_client(&client, &cache, &client_id, LoopbackClients::Fetched);
        let err = tokio::time::timeout(FETCH_TIMEOUT * 2, resolving)
            .await
            .expect("the fetch's own timeout fires first")
            .expect_err("nothing ever answers");
        assert!(matches!(err, ClientMetadataError::Fetch(..)), "{err:?}");
        assert_eq!(started.elapsed(), FETCH_TIMEOUT);
    }

    #[tokio::test]
    async fn resolve_client_recognises_the_loopback_form_without_any_network() {
        let cache = MemoryClientMetadataCache::new();
        // No listener bound anywhere; a network call here would time out and
        // fail the test. The loopback form is resolved from the query
        // alone.
        let (document, key) = resolve_client(
            &crate::oauth::client_metadata_http_client(),
            &cache,
            "http://localhost/?redirect_uri=http%3A%2F%2F127.0.0.1%3A9%2Fcb&scope=atproto",
            LoopbackClients::Fetched,
        )
        .await
        .expect("the loopback form resolves without a fetch");
        assert_eq!(document.redirect_uris, vec!["http://127.0.0.1:9/cb"]);
        assert_eq!(key, ClientKey::compute(&document));
    }

    #[tokio::test]
    async fn a_bare_loopback_client_id_resolves_with_both_default_redirect_uris() {
        let cache = MemoryClientMetadataCache::new();
        let (document, _key) = resolve_client(
            &crate::oauth::client_metadata_http_client(),
            &cache,
            "http://localhost",
            LoopbackClients::Fetched,
        )
        .await
        .expect("a client_id that spells no redirect_uri resolves on the spec defaults");
        assert_eq!(
            document.redirect_uris,
            vec!["http://127.0.0.1/", "http://[::1]/"]
        );
    }

    /// A `client_id` may not name a port, whichever deployment is asked,
    /// and it is refused before anything is fetched: the host accepts and
    /// never answers, so a fetch would cost [`FETCH_TIMEOUT`]. The loopback
    /// form is `http://localhost` with no port, so `localhost` with one is
    /// judged like any other `client_id`.
    #[tokio::test(start_paused = true)]
    async fn a_client_id_that_names_a_port_is_refused_before_the_fetch() {
        let addr = didbot_http::test_support::hung_server();
        let cache = MemoryClientMetadataCache::new();
        let started = tokio::time::Instant::now();
        for client_id in [
            format!("http://localhost:{}/id.json", addr.port()),
            format!("http://localhost:{}", addr.port()),
            format!("https://localhost:{}/id.json", addr.port()),
            "https://app.example:8443/id.json".to_owned(),
        ] {
            for loopback in [LoopbackClients::Fetched, LoopbackClients::Refused] {
                let err = resolve_client(&reaching_only(addr), &cache, &client_id, loopback)
                    .await
                    .expect_err("a client_id with a port is refused");
                let refused = match loopback {
                    // Off a `.localhost` zone, loopback `http://` is refused
                    // first, as it is with no port.
                    LoopbackClients::Refused if client_id.starts_with("http:") => {
                        ClientMetadataError::NotHttps(client_id.clone())
                    }
                    _ => ClientMetadataError::HasPort(client_id.clone()),
                };
                assert_eq!(err, refused, "{client_id} {loopback:?}");
            }
        }
        assert_eq!(started.elapsed(), std::time::Duration::ZERO);
    }

    #[tokio::test]
    async fn a_well_formed_document_still_resolves_through_the_bounded_read() {
        let addr = client_host().await;
        let cache = MemoryClientMetadataCache::new();
        let client_id = format!("{HOST}/id.json");
        let (document, _key) = resolve_client(
            &reaching_only(addr),
            &cache,
            &client_id,
            LoopbackClients::Fetched,
        )
        .await
        .expect("an ordinary document resolves");
        assert_eq!(document.client_id, client_id);
    }

    /// The client [`crate::oauth::client_metadata_http_client`] builds does
    /// not follow redirects, so the 3xx itself arrives — and is refused.
    #[tokio::test]
    async fn a_redirecting_client_id_is_refused_when_the_client_does_not_follow() {
        let addr = client_host().await;
        let cache = MemoryClientMetadataCache::new();
        let err = resolve_client(
            &reaching_only(addr),
            &cache,
            &format!("{HOST}/moved.json"),
            LoopbackClients::Fetched,
        )
        .await
        .expect_err("a redirect is not a client metadata document");
        assert!(
            matches!(err, ClientMetadataError::Redirected { .. }),
            "expected Redirected, got {err:?}"
        );
    }

    /// And a client that *does* follow — the `reqwest` default a deployment
    /// might wire in — lands somewhere else and is refused there. Without
    /// this check the impersonating document `/elsewhere.json` serves would
    /// be accepted: it claims exactly the `client_id` that was requested.
    #[tokio::test]
    async fn a_followed_redirect_is_refused_at_the_url_it_landed_on() {
        let addr = client_host().await;
        let cache = MemoryClientMetadataCache::new();
        let err = resolve_client(
            &reaching(addr, reqwest::redirect::Policy::default()),
            &cache,
            &format!("{HOST}/moved.json"),
            LoopbackClients::Fetched,
        )
        .await
        .expect_err("the document did not come from the client_id");
        match err {
            ClientMetadataError::Redirected { to, .. } => {
                assert!(to.ends_with("/elsewhere.json"), "landed on {to}");
            }
            other => panic!("expected Redirected, got {other:?}"),
        }
    }

    /// The profile has a document answered with "HTTP status must be 200
    /// (not another 2xx or a redirect)" and "the correct Content-Type
    /// (application/json)". A document that is otherwise well formed is
    /// refused on either.
    #[tokio::test]
    async fn only_a_200_served_as_json_is_read() {
        let listener = TcpListener::bind("127.0.0.1:0")
            .await
            .expect("loopback binds");
        let addr = listener.local_addr().expect("bound listener has an addr");
        // Every path serves a document claiming its own URL, answered as the
        // path's name says.
        let app = Router::new().fallback(|uri: axum::http::Uri| async move {
            let (status, content_type) = match uri.path() {
                "/created.json" => (201, Some("application/json")),
                "/missing.json" => (404, Some("application/json")),
                "/text.json" => (200, Some("text/plain")),
                "/ld.json" => (200, Some("application/ld+json")),
                "/untyped.json" => (200, None),
                "/charset.json" => (200, Some("application/json; charset=utf-8")),
                _ => (200, Some("application/json")),
            };
            let mut response = axum::response::Response::builder().status(status);
            if let Some(content_type) = content_type {
                response = response.header(axum::http::header::CONTENT_TYPE, content_type);
            }
            response
                .body(axum::body::Body::from(document_json(&format!(
                    "{HOST}{}",
                    uri.path()
                ))))
                .expect("a response")
        });
        tokio::spawn(async move {
            axum::serve(listener, app)
                .await
                .expect("client host serves");
        });

        let cache = MemoryClientMetadataCache::new();
        let resolve = |path: &str| {
            let client_id = format!("{HOST}{path}");
            let http = reaching_only(addr);
            let cache = &cache;
            async move {
                resolve_client(&http, cache, &client_id, LoopbackClients::Fetched)
                    .await
                    .map(|_| ())
            }
        };
        for read in ["/id.json", "/charset.json"] {
            assert_eq!(resolve(read).await, Ok(()), "{read}");
        }
        for (path, status) in [("/created.json", 201), ("/missing.json", 404)] {
            assert_eq!(
                resolve(path).await,
                Err(ClientMetadataError::NotOk {
                    client_id: format!("{HOST}{path}"),
                    status: reqwest::StatusCode::from_u16(status).expect("a status"),
                }),
                "{path}"
            );
        }
        for (path, content_type) in [
            ("/text.json", "text/plain"),
            ("/ld.json", "application/ld+json"),
            ("/untyped.json", ""),
        ] {
            assert_eq!(
                resolve(path).await,
                Err(ClientMetadataError::NotJson {
                    client_id: format!("{HOST}{path}"),
                    content_type: content_type.to_owned(),
                }),
                "{path}"
            );
        }
    }

    #[tokio::test]
    async fn an_oversized_document_is_refused_on_its_declared_length() {
        let addr = client_host().await;
        let cache = MemoryClientMetadataCache::new();
        let err = resolve_client(
            &reaching_only(addr),
            &cache,
            &format!("{HOST}/huge.json"),
            LoopbackClients::Fetched,
        )
        .await
        .expect_err("a document over the cap is not read");
        assert!(
            matches!(err, ClientMetadataError::TooLarge(_)),
            "expected TooLarge, got {err:?}"
        );
    }

    #[tokio::test]
    async fn an_oversized_document_that_declares_no_length_is_refused_mid_body() {
        let addr = chunked_client_host().await;
        let cache = MemoryClientMetadataCache::new();
        let err = resolve_client(
            &reaching_only(addr),
            &cache,
            &format!("{HOST}/id.json"),
            LoopbackClients::Fetched,
        )
        .await
        .expect_err("a body that outgrows the cap is abandoned");
        assert!(
            matches!(err, ClientMetadataError::TooLarge(_)),
            "expected TooLarge, got {err:?}"
        );
    }

    /// **The port oracle this closes.** A `client_id` naming a loopback
    /// host makes this server fetch a port of the caller's choosing on the
    /// machine running it, and answer differently depending on what it
    /// found. `POST /oauth/par` is unauthenticated, so on a deployment that
    /// is not itself a development one that is a port scanner anyone can
    /// drive. Refused before the fetch, with the same answer a plain
    /// `http://` `client_id` gets, so nothing is learned from the wording
    /// either.
    #[tokio::test]
    async fn a_loopback_client_id_is_refused_before_the_fetch_off_a_localhost_zone() {
        let addr = client_host().await;
        let cache = MemoryClientMetadataCache::new();
        let client_id = format!("{HOST}/id.json");
        let err = resolve_client(
            &reaching_only(addr),
            &cache,
            &client_id,
            LoopbackClients::Refused,
        )
        .await
        .expect_err("a real deployment does not fetch loopback on a caller's say-so");
        assert!(matches!(err, ClientMetadataError::NotHttps(_)), "{err:?}");
        assert!(cache.get(&client_id).is_none());

        // The `http://localhost` form fetches nothing, so it reaches no
        // port and every deployment builds it.
        let virtual_id =
            "http://localhost/?redirect_uri=http%3A%2F%2F127.0.0.1%3A9%2Fcb&scope=atproto";
        let (built, _key) = resolve_client(
            &reaching_only(addr),
            &cache,
            virtual_id,
            LoopbackClients::Refused,
        )
        .await
        .expect("a native client's virtual document needs no fetch");
        assert_eq!(built.redirect_uris, ["http://127.0.0.1:9/cb"]);
    }

    /// And the check runs before the fetch, not after it: the `client_id` is
    /// `https://`, so the loopback carve-out never sees it, and nothing is
    /// sent to the address it names.
    #[tokio::test(start_paused = true)]
    async fn a_client_id_on_this_network_is_refused_before_the_fetch() {
        let cache = MemoryClientMetadataCache::new();
        let client_id = "https://127.0.0.1/client-metadata.json".to_owned();
        let started = tokio::time::Instant::now();
        let err = resolve_client(
            &crate::oauth::client_metadata_http_client(),
            &cache,
            &client_id,
            LoopbackClients::Refused,
        )
        .await
        .expect_err("a real deployment does not fetch from its own network");
        assert!(
            matches!(err, ClientMetadataError::RefusedAddress(_)),
            "{err:?}"
        );
        assert_eq!(started.elapsed(), std::time::Duration::ZERO);
        assert!(cache.get(&client_id).is_none());
    }

    /// The `.localhost` development exception is the one thing that gets
    /// past it, and it is gated exactly where it already was: on the
    /// deployment's own zone, through [`LoopbackClients`].
    #[tokio::test]
    async fn a_localhost_zone_still_fetches_from_its_own_machine() {
        let addr = client_host().await;
        let cache = MemoryClientMetadataCache::new();
        let client_id = format!("{HOST}/id.json");
        let (document, _key) = resolve_client(
            &reaching_only(addr),
            &cache,
            &client_id,
            LoopbackClients::Fetched,
        )
        .await
        .expect("a development deployment reaches its own machine");
        assert_eq!(document.client_id, client_id);
    }

    #[test]
    fn only_a_localhost_zone_fetches_loopback_clients() {
        for zone in [
            "localhost",
            "agents.localhost",
            "AGENTS.LOCALHOST",
            "a.b.localhost.",
        ] {
            assert_eq!(
                LoopbackClients::for_zone(zone),
                LoopbackClients::Fetched,
                "{zone}"
            );
        }
        for zone in ["pds.did.bot", "localhost.example", "example.com", ""] {
            assert_eq!(
                LoopbackClients::for_zone(zone),
                LoopbackClients::Refused,
                "{zone}"
            );
        }
    }

    /// **The unbounded map this closes.** Every distinct `client_id` an
    /// unauthenticated caller invents was its own entry, in a map nothing
    /// ever removed from. Past [`CACHE_CAPACITY`] the entry held longest
    /// goes, so the footprint is the bound rather than the caller's
    /// imagination.
    #[test]
    fn the_cache_never_holds_more_than_its_capacity() {
        let cache = MemoryClientMetadataCache::new();
        let document = ClientMetadataDocument {
            client_id: "https://client.example/id.json".to_owned(),
            application_type: ApplicationType::Web,
            client_name: None,
            client_uri: None,
            logo_uri: None,
            redirect_uris: vec!["https://client.example/cb".to_owned()],
            grant_types: vec!["authorization_code".to_owned()],
            response_types: vec!["code".to_owned()],
            authentication: ClientAuthentication::public(),
            scope: Some("atproto".to_owned()),
            dpop_bound_access_tokens: true,
        };
        let key = ClientKey::compute(&document);
        let start = OffsetDateTime::now_utc();
        for n in 0..(CACHE_CAPACITY * 2) {
            cache.put(
                &format!("https://invented-{n}.example/id.json"),
                CachedClientMetadata {
                    document: document.clone(),
                    key: key.clone(),
                    // Distinct, increasing, so "held longest" is well defined.
                    fetched_at: start + Duration::seconds(n as i64),
                },
            );
        }
        assert_eq!(
            cache.entries.read().unwrap().len(),
            CACHE_CAPACITY,
            "the cache grew past its bound"
        );
        assert!(cache.get("https://invented-0.example/id.json").is_none());
        assert!(cache
            .get(&format!(
                "https://invented-{}.example/id.json",
                CACHE_CAPACITY * 2 - 1
            ))
            .is_some());
    }

    /// Nothing is cached from a fetch that was refused — a refusal must not
    /// become a poisoned entry a later, legitimate fetch reads back.
    #[tokio::test]
    async fn a_refused_fetch_caches_nothing() {
        let addr = client_host().await;
        let cache = MemoryClientMetadataCache::new();
        let client_id = format!("{HOST}/moved.json");
        let _ = resolve_client(
            &reaching_only(addr),
            &cache,
            &client_id,
            LoopbackClients::Fetched,
        )
        .await;
        assert!(cache.get(&client_id).is_none());
    }

    /// The public half of a fresh ES256 key named `kid`, as a client
    /// publishes it.
    fn published_keys(kid: &str) -> serde_json::Value {
        let keyset = jacquard_oauth::keyset::Keyset::generate_es256(kid).expect("a key");
        serde_json::to_value(keyset.public_jwks()).expect("a key set serializes")
    }

    /// What the atproto profile refuses of a confidential client's
    /// document, each refused on its own. A public client may name none of
    /// it, but `none` as an algorithm is refused whoever names it.
    #[test]
    fn what_the_profile_refuses_of_client_authentication_is_refused() {
        let client_id = "https://client.example/id.json";
        let keys: Jwks =
            serde_json::from_value(published_keys("client-key-1")).expect("the key set reads");
        let confidential = ClientAuthentication {
            token_endpoint_auth_method: client_auth::PRIVATE_KEY_JWT.to_owned(),
            token_endpoint_auth_signing_alg: Some(client_auth::SIGNING_ALG.to_owned()),
            jwks: Some(keys),
            ..ClientAuthentication::public()
        };
        let with = |authentication: ClientAuthentication| ClientMetadataDocument {
            authentication,
            ..doc(client_id, vec!["https://client.example/cb"])
        };
        let jwks_uri = Some("https://client.example/jwks.json".to_owned());
        assert!(validate(client_id, with(confidential.clone())).is_ok());
        assert!(validate(
            client_id,
            with(ClientAuthentication {
                jwks: None,
                jwks_uri: jwks_uri.clone(),
                ..confidential.clone()
            })
        )
        .is_ok());

        let id = client_id.to_owned();
        for (authentication, refused) in [
            (
                ClientAuthentication {
                    token_endpoint_auth_method: "client_secret_basic".to_owned(),
                    ..confidential.clone()
                },
                ClientMetadataError::UnsupportedAuthMethod(id.clone()),
            ),
            (
                ClientAuthentication {
                    token_endpoint_auth_signing_alg: None,
                    ..confidential.clone()
                },
                ClientMetadataError::UnsupportedSigningAlg(id.clone()),
            ),
            (
                ClientAuthentication {
                    token_endpoint_auth_signing_alg: Some("RS256".to_owned()),
                    ..confidential.clone()
                },
                ClientMetadataError::UnsupportedSigningAlg(id.clone()),
            ),
            (
                ClientAuthentication {
                    token_endpoint_auth_signing_alg: Some("none".to_owned()),
                    ..ClientAuthentication::public()
                },
                ClientMetadataError::UnsupportedSigningAlg(id.clone()),
            ),
            (
                ClientAuthentication {
                    jwks: None,
                    ..confidential.clone()
                },
                ClientMetadataError::NoClientKeys(id.clone()),
            ),
            (
                ClientAuthentication {
                    jwks: Some(Jwks::default()),
                    ..confidential.clone()
                },
                ClientMetadataError::NoClientKeys(id.clone()),
            ),
            (
                ClientAuthentication {
                    jwks_uri: jwks_uri.clone(),
                    ..confidential.clone()
                },
                ClientMetadataError::TwoKeySets(id.clone()),
            ),
            (
                ClientAuthentication {
                    jwks: None,
                    jwks_uri: Some("http://client.example/jwks.json".to_owned()),
                    ..confidential.clone()
                },
                ClientMetadataError::BadJwksUri("http://client.example/jwks.json".to_owned()),
            ),
        ] {
            assert_eq!(validate(client_id, with(authentication)), Err(refused));
        }
    }

    /// A confidential client's `jwks_uri` is fetched when its document is,
    /// and cached with it, so the keys are read again whenever the document
    /// is. What `jwks_uri` served is not part of the document's content key.
    #[tokio::test]
    async fn a_jwks_uri_is_fetched_with_the_document_and_cached_with_it() {
        let listener = TcpListener::bind("127.0.0.1:0")
            .await
            .expect("loopback binds");
        let addr = listener.local_addr().expect("bound listener has an addr");
        let client_id = format!("{HOST}/id.json");
        let served = serde_json::json!({
            "client_id": client_id,
            "redirect_uris": ["https://app.example/cb"],
            "grant_types": ["authorization_code"],
            "response_types": ["code"],
            "token_endpoint_auth_method": client_auth::PRIVATE_KEY_JWT,
            "token_endpoint_auth_signing_alg": client_auth::SIGNING_ALG,
            "jwks_uri": format!("{HOST}/jwks.json"),
            "dpop_bound_access_tokens": true,
        })
        .to_string();
        let keys = published_keys("client-key-1").to_string();
        let app = Router::new()
            .route("/id.json", get(move || async move { json(served) }))
            .route("/jwks.json", get(move || async move { json(keys) }));
        tokio::spawn(async move {
            axum::serve(listener, app)
                .await
                .expect("client host serves");
        });

        let cache = MemoryClientMetadataCache::new();
        let (document, key) = resolve_client(
            &reaching_only(addr),
            &cache,
            &client_id,
            LoopbackClients::Fetched,
        )
        .await
        .expect("a confidential client's document and keys resolve");
        assert!(document
            .authentication
            .keys()
            .is_some_and(|keys| !keys.is_empty()));
        let cached = cache.get(&client_id).expect("the document is cached");
        assert_eq!(
            cached.document.authentication.keys(),
            document.authentication.keys()
        );

        let mut as_served = document.clone();
        as_served.authentication.jwks_uri_keys = None;
        assert_eq!(key, ClientKey::compute(&as_served));
    }

    /// A `jwks_uri` is a URL the client chose, fetched on an unauthenticated
    /// request's behalf, so it is refused on this deployment's own network
    /// before anything is sent, as a `client_id` is. The host accepts and
    /// never answers, so a fetch would cost [`FETCH_TIMEOUT`].
    #[tokio::test(start_paused = true)]
    async fn a_jwks_uri_on_this_network_is_refused_before_the_fetch() {
        let addr = didbot_http::test_support::hung_server();
        let started = tokio::time::Instant::now();
        let err = fetch_jwks(
            &crate::oauth::client_metadata_http_client(),
            "https://client.example/id.json",
            &format!("https://{addr}/jwks.json"),
            LoopbackClients::Refused,
        )
        .await
        .expect_err("a real deployment does not fetch keys from its own network");
        assert!(
            matches!(err, ClientMetadataError::RefusedAddress(_)),
            "{err:?}"
        );
        assert_eq!(started.elapsed(), std::time::Duration::ZERO);
    }
}