~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
1732 lines · 64.7 KB Raw History
//! Handles: `resolveHandle`, `updateHandle`, `getRecommendedDidCredentials`,
//! `GET /.well-known/atproto-did`, the DID document `describeRepo`
//! answers, and resolving a handle outside the server's domains
//! (`resolve`), as `spec/IDENTITY.md` says.
//!
//! A handle change is recorded in its account's log before its operation goes
//! to the PLC directory, and settled after: it landed, with its `#identity`
//! event, or it was dropped (`log::log_settled`). Until it is settled the
//! account keeps its handle and the new one stays taken. An account's changes
//! are made one at a time, each holding its account's `Slot` while it talks
//! to the directory; one left unsettled, by a restart or a directory that
//! could not be reached, waits in the slot, and is settled in the background
//! or by the account's next change. A `did:web` account's change posts
//! nothing: its document, read again, must name the handle already, and the
//! change lands at once (`spec/MIGRATION.md`, "A `did:web` account").

use crate::log;
use crate::ops::Level;
use crate::plc::{self, Upstream};
use crate::sessions;
use crate::{
    Account, Call, Handler, Resp, Service, Shared, Shown, XrpcError, durable, err, internal,
    invalid, read, required, write,
};
use axum::extract::State as AxState;
use axum::http::{HeaderMap, StatusCode, header};
use axum::response::{IntoResponse, Response};
use serde_json::{Map, Value as Json, json};
use std::collections::HashMap;
use std::sync::{Arc, PoisonError, Weak};
use std::time::Duration;

pub(crate) mod resolve;

/// Whether `handle` (already lowercased, outside `PDS_HANDLE_DOMAINS`)
/// resolves to `did`, as `spec/IDENTITY.md` "Resolving a handle" says: the
/// DID its one `did=` TXT record of `_atproto.<handle>` names, or else the
/// first line of its `/.well-known/atproto-did`, is `did` exactly.
pub(crate) async fn handle_resolves_to(s: &Service, handle: &str, did: &str) -> bool {
    resolve::resolve(s, handle).await.as_deref() == Some(did)
}

pub(crate) fn handler(nsid: &str) -> Option<Handler> {
    Some(match nsid {
        "com.atproto.identity.resolveHandle" => Handler::Query(resolve_handle),
        "com.atproto.identity.getRecommendedDidCredentials" => {
            Handler::Query(recommended_credentials)
        }
        "com.atproto.identity.updateHandle" => {
            Handler::Authed(sessions::access_token, |s, t, b| {
                Box::pin(update_handle(s, t.did, b))
            })
        }
        _ => return None,
    })
}

/// A handle in any case: an active account's, external or not, answers its
/// DID; one under the server's domains that no active account has is
/// `HandleNotFound`; any other is not the server's, and it looks it up not.
fn resolve_handle(
    s: &Service,
    _: &Call,
    _: &mut Shown,
    p: &Map<String, Json>,
) -> Result<Resp, XrpcError> {
    let handle = required(p, "handle")?.to_lowercase();
    if let Some(did) = active_did(s, &handle) {
        return Ok(Resp::Json(json!({ "did": did })));
    }
    if s.config
        .handle_domains
        .iter()
        .any(|d| handle.ends_with(d.as_str()))
    {
        return err(400, "HandleNotFound", "Unable to resolve handle");
    }
    invalid("Unable to resolve handle")
}

/// The DID of the active account whose handle this is: one not active is as none's.
fn active_did(s: &Service, handle: &str) -> Option<String> {
    let a = s.account(handle)?;
    crate::lifecycle::status(&a)
        .is_none()
        .then(|| a.did.clone())
}

/// What a DID document of the token's account on this server holds, as
/// `createAccount`'s genesis operation would hold it now: without its
/// handle while it is taken down.
fn recommended_credentials(
    s: &Service,
    call: &Call,
    _: &mut Shown,
    _: &Map<String, Json>,
) -> Result<Resp, XrpcError> {
    let did = s.auth(call.bearer).did()?;
    let Some(a) = s.account(&did) else {
        return internal();
    };
    let signing = plc::did_key(read(&a.store).repo.verifying_key());
    let mut methods = json!({ "atproto": signing });
    if let Some(kem) = &a.kem {
        methods["atproto_kem"] = json!(kem.public().did_key());
    }
    let mut out = json!({
        "verificationMethods": methods,
        "rotationKeys": plc::rotation_keys(&s.config),
        "services": { "atproto_pds": { "type": "AtprotoPersonalDataServer", "endpoint": s.config.public_url } },
    });
    if read(&a.state).takedown.is_none() {
        out["alsoKnownAs"] = json!([format!("at://{}", a.handle())]);
    }
    Ok(Resp::Json(out))
}

/// A DID document held as JSON text.
fn held_doc(text: &str) -> Json {
    serde_json::from_str(text).unwrap_or(Json::Null)
}

/// An account's DID document, as the directory or its host last served
/// it, if it was fetched within `PDS_DID_CACHE_SECS`.
fn kept_doc(s: &Service, a: &Account) -> Option<Json> {
    let (doc, at) = &*read(&a.did_doc);
    at.filter(|t| s.limits.clock.now() < t.saturating_add(s.config.did_cache))
        .map(|_| held_doc(doc))
}

/// The DID document of an account's DID: the one kept, if it was fetched
/// within `PDS_DID_CACHE_SECS`, or else the one the directory serves now,
/// fetched once at a time; the one it last served, should it not answer.
/// A `did:web`'s is its host's, and an error, as `proxy::read_did` gives
/// it, when it cannot be read (`spec/MIGRATION.md`, "A `did:web` account").
pub(crate) async fn did_doc(s: &Service, did: &str) -> Result<Json, XrpcError> {
    let Some(a) = s.account(did) else {
        return Ok(Json::Null);
    };
    if let Some(doc) = kept_doc(s, &a) {
        return Ok(doc);
    }
    let _fetching = a.fetching.lock().await;
    // Another call may have fetched it meanwhile.
    if let Some(doc) = kept_doc(s, &a) {
        return Ok(doc);
    }
    fetch_doc(s, &a).await
}

/// Whether a DID is a `did:web`, whose document its owner serves at its
/// host rather than the directory (`spec/MIGRATION.md`, "A `did:web` account").
pub(crate) fn is_web(did: &str) -> bool {
    did.starts_with("did:web:")
}

/// Fetch an account's DID document from the directory, or its host for a
/// `did:web`, and keep it; with the account's fetch held.
async fn fetch_doc(s: &Service, a: &Account) -> Result<Json, XrpcError> {
    if is_web(&a.did) {
        return fetch_web_doc(s, a).await;
    }
    let url = format!("{}/{}", s.config.plc_url.trim_end_matches('/'), a.did);
    Ok(match plc::document(&s.http, &url).await {
        Ok(Some(doc)) => {
            *write(&a.did_doc) = (doc.to_string().into(), Some(s.limits.clock.now()));
            doc
        }
        Ok(None) => {
            crate::ops::failed_for(
                Level::Warn,
                "DID document not served",
                &a.did,
                "none at the PLC directory",
            );
            held_doc(&read(&a.did_doc).0)
        }
        Err(why) => {
            crate::ops::failed_for(Level::Warn, "reading a DID document failed", &a.did, why);
            held_doc(&read(&a.did_doc).0)
        }
    })
}

/// A `did:web` account's document as its host serves it now, kept once
/// read; with the account's fetch held. `400 InvalidRequest` for a host
/// that answers anything but `2xx`, `500` for one that does not answer or
/// answers what is no document of the DID (`proxy::read_did`).
async fn fetch_web_doc(s: &Service, a: &Account) -> Result<Json, XrpcError> {
    let doc = crate::proxy::read_did(s, &a.did).await.inspect_err(|e| {
        crate::ops::failed_for(
            Level::Warn,
            "reading a did:web document failed",
            &a.did,
            e.name,
        );
    })?;
    *write(&a.did_doc) = (doc.to_string().into(), Some(s.limits.clock.now()));
    Ok(doc)
}

/// A `did:web` account's document read again from its host, past anything
/// kept, as `fetch_web_doc` reads it.
pub(crate) async fn web_doc_now(s: &Service, a: &Account) -> Result<Json, XrpcError> {
    let _fetching = a.fetching.lock().await;
    fetch_web_doc(s, a).await
}

/// After an operation the server posted for the account: its document,
/// fetched now, is the one served from then on; out of date if it cannot be.
async fn refetch_doc(s: &Service, a: &Account) {
    let _fetching = a.fetching.lock().await;
    write(&a.did_doc).1 = None;
    let _ = fetch_doc(s, a).await;
}

/// Whether a DID document's first `at://` name is `at://<handle>`.
pub(crate) fn names_handle(doc: &Json, handle: &str) -> bool {
    let first = doc["alsoKnownAs"].as_array().and_then(|aka| {
        aka.iter()
            .filter_map(Json::as_str)
            .find(|u| u.starts_with("at://"))
    });
    first.and_then(|u| u.strip_prefix("at://")) == Some(handle)
}

/// The signing key a `did:web` document names, as `atproto/did.md` takes
/// it: of its first `verificationMethod` whose `id` ends `#atproto`.
pub(crate) fn web_signing_key(doc: &Json) -> Option<crate::space_credentials::jwt::Key> {
    let method = doc["verificationMethod"]
        .as_array()?
        .iter()
        .find(|m| m["id"].as_str().is_some_and(|id| id.ends_with("#atproto")))?;
    crate::space_credentials::jwt::Key::of_method(method)
}

/// The endpoint a `did:web` document names, as `atproto/did.md` takes it:
/// the `serviceEndpoint` of its first `service` whose `id` ends
/// `#atproto_pds` and whose `type` is `AtprotoPersonalDataServer`.
pub(crate) fn web_endpoint(doc: &Json) -> Option<&str> {
    doc["service"].as_array()?.iter().find(|s| {
        s["id"]
            .as_str()
            .is_some_and(|id| id.ends_with("#atproto_pds"))
            && s["type"] == "AtprotoPersonalDataServer"
    })?["serviceEndpoint"]
        .as_str()
}

/// Whether a `did:web` document names this server: its endpoint is
/// `PDS_PUBLIC_URL` and, if the account has one still, its signing key
/// the account's. No rotation key nor handle is asked of it.
pub(crate) fn web_names_server(
    s: &Service,
    doc: &Json,
    signing: Option<&k256::ecdsa::VerifyingKey>,
) -> bool {
    web_endpoint(doc) == Some(s.config.public_url.as_str())
        && signing.is_none_or(|k| {
            web_signing_key(doc) == Some(crate::space_credentials::jwt::Key::K256(*k))
        })
}

/// `GET /.well-known/atproto-did`: the DID of the account whose handle the
/// `Host` header names, less any `:port`, as given.
pub(crate) async fn well_known(AxState(s): AxState<Shared>, headers: HeaderMap) -> Response {
    let host = headers.get(header::HOST).and_then(|h| h.to_str().ok());
    match host.and_then(|h| host_did(&s, h)) {
        Some(did) => (
            StatusCode::OK,
            [(header::CONTENT_TYPE, "text/plain; charset=utf-8")],
            did,
        )
            .into_response(),
        None => (StatusCode::NOT_FOUND, "User not found").into_response(),
    }
}

fn host_did(s: &Service, host: &str) -> Option<String> {
    let name = match host.rsplit_once(':') {
        Some((name, port)) if !port.is_empty() && port.bytes().all(|c| c.is_ascii_digit()) => name,
        _ => host,
    };
    // A DID is no handle.
    if name.starts_with("did:") {
        return None;
    }
    active_did(s, name)
}

/// A handle change recorded and not yet settled: the handle, and its operation's CID.
#[derive(Clone)]
pub(crate) struct Pending {
    pub handle: String,
    pub cid: String,
}

/// An account's handle changes: held by the one being made, and holding one
/// left unsettled.
type Slot = Arc<tokio::sync::Mutex<Option<Pending>>>;

/// Each account's `Slot`, by DID.
#[derive(Default)]
pub(crate) struct Changes(std::sync::Mutex<HashMap<String, Slot>>);

impl Changes {
    fn slot(&self, did: &str) -> Slot {
        let mut slots = self.0.lock().unwrap_or_else(PoisonError::into_inner);
        slots.entry(did.to_string()).or_default().clone()
    }

    /// A change the server stopped during, as recovery found it.
    pub fn unsettled(&self, did: &str, p: Pending) {
        self.0
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .insert(did.to_string(), Arc::new(tokio::sync::Mutex::new(Some(p))));
    }

    fn unsettled_dids(&self) -> Vec<String> {
        let slots = self.0.lock().unwrap_or_else(PoisonError::into_inner);
        slots
            .iter()
            .filter(|(_, slot)| slot.try_lock().map_or(true, |p| p.is_some()))
            .map(|(did, _)| did.clone())
            .collect()
    }
}

/// Settle in the background every change the server stopped during.
pub(crate) fn settle_unfinished(s: &Shared) {
    for did in s.changes.unsettled_dids() {
        tokio::spawn(settle_later(Arc::downgrade(s), did));
    }
}

/// Ask the directory about an account's unsettled change until it answers,
/// waiting longer each time it does not; stop if the server goes.
async fn settle_later(s: Weak<Service>, did: String) {
    let mut pause = Duration::from_millis(100);
    loop {
        {
            let Some(s) = s.upgrade() else { return };
            let Some(a) = s.account(&did) else { return };
            let slot = s.changes.slot(&did);
            let mut change = slot.lock().await;
            match settle(&s, &a, &mut change).await {
                Ok(()) => return,
                Err(why) => crate::ops::failed_for(
                    Level::Warn,
                    "settling a handle change failed",
                    &did,
                    why,
                ),
            }
        }
        tokio::time::sleep(pause).await;
        pause = (pause * 2).min(Duration::from_secs(2));
    }
}

/// Settle an account's unsettled change, if it has one, by whether the
/// directory's log holds its operation; an error if the directory cannot say.
/// A `did:web`'s change posted nothing, and its document named the handle
/// when it was recorded: it landed.
async fn settle(s: &Service, a: &Account, change: &mut Option<Pending>) -> Result<(), String> {
    let Some(p) = change.as_ref() else {
        return Ok(());
    };
    let landed = is_web(&a.did) || plc::holds(&s.http, &s.config.plc_url, &a.did, &p.cid).await?;
    if !finish(s, a, change, landed).await {
        return Err("its settling could not be logged".into());
    }
    Ok(())
}

/// Settle the change in flight: in the log, on disk, then, if it landed, the
/// account's handle, freeing the old one, its `#identity` event, and its DID
/// document fetched again. Its handle is no longer held for it either way.
/// False, with the change still in flight, if it could not be logged.
async fn finish(s: &Service, a: &Account, change: &mut Option<Pending>, landed: bool) -> bool {
    let Some(p) = change.take() else { return true };
    let logged = {
        let mut st = write(&a.store);
        let landing = log::log_settled(
            &s.events,
            &a.did,
            &mut st,
            &p.cid,
            landed.then_some(p.handle.as_str()),
        );
        landing.map(|l| {
            let shown = Shown::after(l.as_ref(), vec![(st.wal.clone(), st.wal.written())]);
            (shown, l)
        })
    };
    let (shown, landing) = match logged {
        Ok(x) => x,
        Err(e) => {
            crate::ops::failed_for(Level::Error, "settling a handle change failed", &a.did, e);
            *change = Some(p);
            return false;
        }
    };
    // A sync that fails is said; the change is made in memory as it is in the log.
    let _ = shown.durable().await;
    {
        let mut d = write(&s.directory);
        d.claimed_handles.remove(&p.handle);
        if landed {
            let mut handle = write(&a.handle);
            if d.handles.get(&*handle) == Some(&a.did) {
                d.handles.remove(&*handle);
            }
            d.handles.insert(p.handle.clone(), a.did.clone());
            *handle = p.handle;
        }
    }
    // Settled: the service log has the handle, and a start need not look in the account's log for it.
    {
        let st = read(&a.store);
        let needs = st.needs_start();
        if landed || !needs {
            let handle = a.handle();
            if needs {
                s.ctx.eager.relax_handle(&a.did, &handle);
            } else {
                s.ctx.eager.relax(&a.did, Some(&handle));
            }
        }
    }
    if let Some(l) = landing {
        s.events.land(l);
    }
    if landed {
        refetch_doc(s, a).await;
    }
    true
}

/// A handle held for a change before it is recorded, so that no other
/// account takes it meanwhile; let go when dropped, unless kept for the
/// change once it is recorded.
struct Held<'a> {
    s: &'a Service,
    handle: Option<String>,
}

impl Held<'_> {
    fn keep(mut self) {
        self.handle = None;
    }
}

impl Drop for Held<'_> {
    fn drop(&mut self) {
        if let Some(h) = &self.handle {
            write(&self.s.directory).claimed_handles.remove(h);
        }
    }
}

fn upstream<T>() -> Result<T, XrpcError> {
    err(
        502,
        "UpstreamFailure",
        "The PLC directory could not be reached",
    )
}

/// Give the token's account a handle, checked in the order `spec/IDENTITY.md`
/// gives, its token and input already checked.
async fn update_handle(s: Shared, did: String, b: Map<String, Json>) -> Result<Resp, XrpcError> {
    let handle = required(&b, "handle")?.to_lowercase();
    let external = crate::server::check_handle(&s, &handle, true)?;
    if external && !handle_resolves_to(&s, &handle, &did).await {
        return invalid("External handle did not resolve to DID");
    }
    let Some(a) = s.account(&did) else {
        return internal();
    };
    let slot = s.changes.slot(&did);
    let mut change = slot.lock().await;
    // A change left unsettled is settled first.
    if let Err(why) = settle(&s, &a, &mut change).await {
        crate::ops::failed_for(Level::Warn, "settling a handle change failed", &did, why);
        return upstream();
    }
    // An account not loaded that may have the handle is loaded first: then
    // those loaded say whether it is taken.
    s.load_hinted(crate::compact::HANDLE, &handle);
    let held = {
        let mut d = write(&s.directory);
        let taken = || {
            err(
                400,
                "HandleNotAvailable",
                format!("Handle already taken: {handle}"),
            )
        };
        match d.handles.get(&handle) {
            Some(owner) if *owner != did => return taken(),
            // Its own handle: a change like any other.
            Some(_) => Held {
                s: &s,
                handle: None,
            },
            None if d.claimed_handles.contains(&handle) => return taken(),
            None => {
                d.claimed_handles.insert(handle.clone());
                Held {
                    s: &s,
                    handle: Some(handle.clone()),
                }
            }
        }
    };
    // A `did:plc`'s handle goes to the directory in an operation; a
    // `did:web`'s document, read again now, must name it already.
    let (op, cid) = if is_web(&did) {
        let doc = match web_doc_now(&s, &a).await {
            Ok(doc) => doc,
            Err(_) => return internal(),
        };
        if !names_handle(&doc, &handle) {
            return invalid("DID document does not name the handle");
        }
        match plc::cid(&json!({ "did": did, "handle": handle })) {
            Ok(cid) => (None, cid),
            Err(why) => {
                crate::ops::failed_for(Level::Error, "updateHandle failed", &did, why);
                return internal();
            }
        }
    } else {
        let last = match plc::last_operation(&s.http, &s.config.plc_url, &did).await {
            Ok(op) => op,
            Err(Upstream::Refused(why)) => return invalid(why),
            Err(Upstream::Unreachable { why, .. }) => {
                crate::ops::failed_for(Level::Warn, "updateHandle failed", &did, why);
                return upstream();
            }
        };
        match plc::update(&s.config, &last, &handle).and_then(|op| Ok((plc::cid(&op)?, op))) {
            Ok((cid, op)) => (Some(op), cid),
            Err(why) => {
                crate::ops::failed_for(Level::Error, "updateHandle failed", &did, why);
                return internal();
            }
        }
    };
    // Recorded, and on disk, before the operation goes: from here the change
    // holds the handle until it is settled. A start looks for it in the
    // account's log, once marked (`cache`).
    let marking = (s.clone(), did.clone());
    match tokio::task::spawn_blocking(move || marking.0.ctx.eager.mark(&marking.1)).await {
        Ok(Ok(())) => {}
        Ok(Err(e)) => {
            crate::ops::failed_for(Level::Error, "updateHandle failed", &did, e);
            return internal();
        }
        Err(_) => return internal(),
    }
    let (wal, n) = {
        let mut st = write(&a.store);
        match st.wal.append(&[log::handle_entry(&handle, &cid)]) {
            Ok(n) => {
                st.pending = Some(Pending {
                    handle: handle.clone(),
                    cid: cid.clone(),
                });
                (st.wal.clone(), n)
            }
            Err(e) => {
                crate::ops::failed_for(Level::Error, "updateHandle failed", &did, e);
                return internal();
            }
        }
    };
    held.keep();
    *change = Some(Pending {
        handle: handle.clone(),
        cid: cid.clone(),
    });
    if durable(wal, n).await.is_err() {
        drop(change);
        tokio::spawn(settle_later(Arc::downgrade(&s), did));
        return internal();
    }
    let posted = match &op {
        // A `did:web`'s: nothing is posted, and it lands at once.
        None => Ok(()),
        Some(op) => plc::post(&s.http, &s.config.plc_url, &did, op).await,
    };
    let (landed, refused) = match posted {
        Ok(()) => (true, None),
        Err(Upstream::Refused(why)) => (false, Some(invalid(why))),
        Err(Upstream::Unreachable { why, sent }) => {
            crate::ops::failed_for(Level::Warn, "updateHandle failed", &did, &why);
            // A post that may have reached the directory: whether it took it is in its log.
            let found = if sent {
                plc::holds(&s.http, &s.config.plc_url, &did, &cid).await
            } else {
                Ok(false)
            };
            match found {
                Ok(true) => (true, None),
                Ok(false) => (false, Some(upstream())),
                Err(why) => {
                    crate::ops::failed_for(
                        Level::Warn,
                        "updateHandle failed, settling it later",
                        &did,
                        why,
                    );
                    drop(change);
                    tokio::spawn(settle_later(Arc::downgrade(&s), did));
                    return upstream();
                }
            }
        }
    };
    if !finish(&s, &a, &mut change, landed).await {
        // Settled in the background, once its settling can be logged.
        drop(change);
        tokio::spawn(settle_later(Arc::downgrade(&s), did));
        return internal();
    }
    refused.unwrap_or(Ok(Resp::Nothing))
}

/// A PLC directory for tests, keeping each DID's log of operations as
/// `atproto/did-plc.md` has the directory keep it: a genesis operation taken
/// only if it makes its DID, an update only if its `prev` is the CID of the
/// DID's last operation and one of that operation's rotation keys signed it.
/// Any operation naming a handle that starts `refused` is refused. It serves
/// each DID's document, `/log/last` and `/log/audit`, and goes down (no
/// connection is taken) and up again on the same port.
#[cfg(test)]
pub(crate) mod stub {
    use axum::body::Bytes;
    use axum::extract::{Path, State};
    use axum::http::{StatusCode, header};
    use axum::response::{IntoResponse, Response};
    use axum::{Router, routing::get};
    use serde_json::{Value as Json, json};
    use std::collections::HashMap;
    use std::sync::{Arc, Mutex};

    type Logs = Arc<Mutex<HashMap<String, Vec<Json>>>>;

    pub struct Plc {
        pub url: String,
        addr: std::net::SocketAddr,
        logs: Logs,
        serving: Mutex<Option<tokio::task::JoinHandle<()>>>,
    }

    fn refuse(why: impl Into<String>) -> Response {
        (
            StatusCode::BAD_REQUEST,
            [(header::CONTENT_TYPE, "application/json")],
            json!({ "message": why.into() }).to_string(),
        )
            .into_response()
    }

    fn found(j: Json) -> Response {
        ([(header::CONTENT_TYPE, "application/json")], j.to_string()).into_response()
    }

    async fn post(State(logs): State<Logs>, Path(did): Path<String>, body: Bytes) -> Response {
        let Ok(op) = serde_json::from_slice::<Json>(&body) else {
            return refuse("not JSON");
        };
        let names = |u: &Json| u.as_str().is_some_and(|u| u.starts_with("at://refused"));
        if op["alsoKnownAs"]
            .as_array()
            .is_some_and(|aka| aka.iter().any(names))
        {
            return refuse("this handle is refused");
        }
        let mut logs = logs.lock().unwrap();
        let log = logs.entry(did.clone()).or_default();
        let checked = match log.last() {
            None => crate::plc::verify(&did, &op),
            Some(last) => crate::plc::verify_update(last, &op).map(|_| ()),
        };
        if let Err(why) = checked {
            return refuse(why);
        }
        log.push(op);
        StatusCode::OK.into_response()
    }

    fn last(logs: &Logs, did: &str) -> Option<Json> {
        logs.lock().unwrap().get(did)?.last().cloned()
    }

    async fn doc(State(logs): State<Logs>, Path(did): Path<String>) -> Response {
        let Some(op) = last(&logs, &did) else {
            return StatusCode::NOT_FOUND.into_response();
        };
        found(crate::testing::did_document(&did, &op))
    }

    async fn log_last(State(logs): State<Logs>, Path(did): Path<String>) -> Response {
        last(&logs, &did).map_or_else(|| StatusCode::NOT_FOUND.into_response(), found)
    }

    /// The DID's current data, as `GET <PLC>/<did>/data` answers it.
    async fn data(State(logs): State<Logs>, Path(did): Path<String>) -> Response {
        let Some(op) = last(&logs, &did) else {
            return StatusCode::NOT_FOUND.into_response();
        };
        found(json!({
            "did": did, "verificationMethods": op["verificationMethods"], "rotationKeys": op["rotationKeys"],
            "alsoKnownAs": op["alsoKnownAs"], "services": op["services"],
        }))
    }

    async fn log_audit(State(logs): State<Logs>, Path(did): Path<String>) -> Response {
        let Some(log) = logs.lock().unwrap().get(&did).cloned() else {
            return StatusCode::NOT_FOUND.into_response();
        };
        let entries: Vec<Json> = log
            .iter()
            .map(|op| json!({ "did": did, "operation": op, "cid": crate::plc::cid(op).unwrap(), "nullified": false, "createdAt": "2026-01-01T00:00:00.000Z" }))
            .collect();
        found(json!(entries))
    }

    impl Plc {
        pub async fn start() -> Arc<Plc> {
            let listener = tokio::net::TcpListener::bind(("127.0.0.1", 0))
                .await
                .unwrap();
            let addr = listener.local_addr().unwrap();
            let plc = Plc {
                url: format!("http://{addr}"),
                addr,
                logs: Logs::default(),
                serving: Mutex::new(None),
            };
            plc.serve(listener);
            Arc::new(plc)
        }

        fn serve(&self, listener: tokio::net::TcpListener) {
            let app = Router::new()
                .route("/{did}", get(doc).post(post))
                .route("/{did}/log/last", get(log_last))
                .route("/{did}/data", get(data))
                .route("/{did}/log/audit", get(log_audit))
                .with_state(self.logs.clone());
            *self.serving.lock().unwrap() = Some(tokio::spawn(async move {
                axum::serve(listener, app).await.unwrap()
            }));
        }

        /// Stop listening: a connection is refused until it comes up.
        pub async fn down(&self) {
            let serving = self.serving.lock().unwrap().take();
            if let Some(h) = serving {
                h.abort();
                let _ = h.await;
            }
        }

        pub async fn up(&self) {
            self.serve(tokio::net::TcpListener::bind(self.addr).await.unwrap());
        }

        /// The DID's operations, first to last.
        pub fn log(&self, did: &str) -> Vec<Json> {
            self.logs
                .lock()
                .unwrap()
                .get(did)
                .cloned()
                .unwrap_or_default()
        }

        /// Post an operation as a client other than the server would.
        pub async fn post(&self, did: &str, op: &Json) -> u16 {
            let res = crate::plc::client()
                .unwrap()
                .post(format!("{}/{did}", self.url))
                .body(op.to_string())
                .send()
                .await
                .unwrap();
            res.status().as_u16()
        }
    }
}

#[cfg(test)]
pub(crate) mod tests {
    use super::stub::Plc;
    use super::*;
    use crate::testing::*;

    const UPDATE: &str = "com.atproto.identity.updateHandle";
    const RESOLVE: &str = "com.atproto.identity.resolveHandle";
    const CREDENTIALS: &str = "com.atproto.identity.getRecommendedDidCredentials";
    const DESCRIBE: &str = "com.atproto.repo.describeRepo";
    const SESSION: &str = "com.atproto.server.getSession";
    const CREATE: &str = "com.atproto.server.createAccount";

    async fn update(s: &Shared, token: &str, handle: &str) -> Result<Json, String> {
        call(s, UPDATE, Some(token), json!({ "handle": handle })).await
    }

    async fn resolve(s: &Shared, handle: &str) -> Result<Json, String> {
        call_with(
            s,
            RESOLVE,
            None,
            &[("handle".into(), handle.into())],
            json!({}),
        )
        .await
    }

    async fn describe(s: &Shared, repo: &str) -> Result<Json, String> {
        call_with(
            s,
            DESCRIBE,
            None,
            &[("repo".into(), repo.into())],
            json!({}),
        )
        .await
    }

    fn handle_of(s: &Service, did: &str) -> String {
        s.account(did).unwrap().handle()
    }

    fn claimed(s: &Service) -> Vec<String> {
        let mut c: Vec<String> = read(&s.directory).claimed_handles.iter().cloned().collect();
        c.sort();
        c
    }

    /// Every event, its header's `t` beside its body's fields.
    fn events(s: &Service) -> Vec<Json> {
        s.events
            .get(s, 0, u64::MAX - 1, 0)
            .iter()
            .map(|f| {
                let (head, at) = pds_repo::data::decode_prefix(f).unwrap();
                let mut body = pds_repo::data::to_json(&pds_repo::data::decode(&f[at..]).unwrap());
                body["t"] = pds_repo::data::to_json(&head)["t"].clone();
                body
            })
            .collect()
    }

    /// The handle the directory's document of `did` names.
    fn directory_handle(plc: &Plc, did: &str) -> String {
        let last = plc.log(did).pop().unwrap();
        let aka = last["alsoKnownAs"].as_array().unwrap().clone();
        aka.iter()
            .filter_map(Json::as_str)
            .find_map(|u| u.strip_prefix("at://"))
            .unwrap()
            .to_string()
    }

    /// Wait, up to `secs` seconds, for the account `did` to have `handle` and
    /// no change in flight, and then for its events to be sent: a change
    /// settled in the background gives the account its handle a moment
    /// before its `#identity` event reaches the firehose.
    async fn settled(s: &Service, did: &str, handle: &str, secs: u64) {
        for _ in 0..secs * 20 {
            if handle_of(s, did) == handle && claimed(s).is_empty() {
                // Numbered, and on disk, before the handle shows.
                let last = read(&s.account(did).unwrap().store).last_seq;
                let mut published = s.events.subscribe();
                let sent = tokio::time::timeout(
                    Duration::from_secs(secs),
                    published.wait_for(|p| *p >= last),
                )
                .await;
                assert!(
                    sent.is_ok_and(|r| r.is_ok()),
                    "{did}'s event {last} not sent"
                );
                return;
            }
            tokio::time::sleep(Duration::from_millis(50)).await;
        }
        panic!(
            "{did} has {} and holds {:?}, not {handle}",
            handle_of(s, did),
            claimed(s)
        );
    }

    async fn well_known_of(s: &Shared, host: Option<&str>) -> (u16, Option<String>, String) {
        let mut headers = HeaderMap::new();
        if let Some(h) = host {
            headers.insert(header::HOST, h.parse().unwrap());
        }
        let res = well_known(AxState(s.clone()), headers).await;
        let status = res.status().as_u16();
        let ct = res
            .headers()
            .get(header::CONTENT_TYPE)
            .map(|v| v.to_str().unwrap().to_string());
        let body = axum::body::to_bytes(res.into_body(), usize::MAX)
            .await
            .unwrap();
        (status, ct, String::from_utf8(body.to_vec()).unwrap())
    }

    /// `updateHandle` answers the first fault in the spec's order: token,
    /// input, the handle as `createAccount` checks it, then a handle taken.
    /// A refused change posts nothing, changes nothing and sends no event.
    #[tokio::test]
    async fn checks_in_order() {
        let plc = Plc::start().await;
        let dir = scratch("identity-order");
        let s = open(&dir, &plc.url);
        let (alice, ta) = create(&s, "alice").await;
        create(&s, "bob").await;
        let events_before = s.events.len();
        let long = format!("{}.test", "a".repeat(19));
        let cases: Vec<(Option<&str>, Json, &str)> = vec![
            (None, json!({ "handle": 5 }), "AuthMissing"),
            (None, json!({ "handle": "bob.test" }), "AuthMissing"),
            (Some("nope"), json!({ "handle": 5 }), "InvalidToken"),
            (Some("nope"), json!({}), "InvalidToken"),
            (Some(&ta), json!({}), "InvalidRequest"),
            (Some(&ta), json!({ "handle": 5 }), "InvalidRequest"),
            (
                Some(&ta),
                json!({ "handle": "not a handle" }),
                "InvalidRequest",
            ),
            (
                Some(&ta),
                json!({ "handle": "admin..test" }),
                "InvalidRequest",
            ),
            // A disallowed top-level domain, before anything else of the handle.
            (
                Some(&ta),
                json!({ "handle": "abc.invalid" }),
                "InvalidHandle",
            ),
            (
                Some(&ta),
                json!({ "handle": "admin.example" }),
                "InvalidHandle",
            ),
            (
                Some(&ta),
                json!({ "handle": "bob.EXAMPLE" }),
                "InvalidHandle",
            ),
            // Under the server's domains: a dot, then the length, then reserved.
            (
                Some(&ta),
                json!({ "handle": "a.admin.test" }),
                "InvalidHandle",
            ),
            (Some(&ta), json!({ "handle": "ab.test" }), "InvalidHandle"),
            (Some(&ta), json!({ "handle": long }), "InvalidHandle"),
            (
                Some(&ta),
                json!({ "handle": "admin.test" }),
                "HandleNotAvailable",
            ),
            (
                Some(&ta),
                json!({ "handle": "Admin.TEST" }),
                "HandleNotAvailable",
            ),
            // Elsewhere: an external handle, which resolves to nothing.
            (Some(&ta), json!({ "handle": "bob.com" }), "InvalidRequest"),
            (
                Some(&ta),
                json!({ "handle": "alice.test.com" }),
                "InvalidRequest",
            ),
            // Another account's, in any case.
            (
                Some(&ta),
                json!({ "handle": "bob.test" }),
                "HandleNotAvailable",
            ),
            (
                Some(&ta),
                json!({ "handle": "BOB.test", "unknown": 1 }),
                "HandleNotAvailable",
            ),
        ];
        for (token, body, want) in cases {
            assert_eq!(
                call(&s, UPDATE, token, body.clone()).await,
                Err(want.to_string()),
                "{token:?} {body}"
            );
        }
        assert_eq!(plc.log(&alice).len(), 1);
        assert_eq!(s.events.len(), events_before);
        assert_eq!(handle_of(&s, &alice), "alice.test");
        assert!(claimed(&s).is_empty());
        // Fields the lexicon does not name are ignored; the handle is lowercased.
        assert_eq!(
            call(
                &s,
                UPDATE,
                Some(&ta),
                json!({ "handle": "Carol.TEST", "unknown": 1 })
            )
            .await,
            Ok(Json::Null)
        );
        assert_eq!(handle_of(&s, &alice), "carol.test");
        // Its own handle again is a change like any other, with its operation and event.
        assert_eq!(update(&s, &ta, "CAROL.test").await, Ok(Json::Null));
        assert_eq!(plc.log(&alice).len(), 3);
        assert_eq!(s.events.len(), events_before + 2);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// The update operation, built on the directory's last operation for the
    /// DID, even one the server did not post; and all that changes with it.
    #[tokio::test]
    async fn update_operation_and_what_it_changes() {
        let plc = Plc::start().await;
        let dir = scratch("identity-update");
        let s = open(&dir, &plc.url);
        let (alice, ta) = create(&s, "alice").await;
        create(&s, "bob").await;
        let genesis = plc.log(&alice)[0].clone();
        // An operation of another's, adding an `https://` name.
        let mut theirs = genesis.clone();
        theirs["alsoKnownAs"] = json!(["at://alice.test", "https://alice.example.com"]);
        theirs["prev"] = json!(plc::cid(&genesis).unwrap());
        let theirs = plc::signed(&s.config, &theirs);
        assert_eq!(plc.post(&alice, &theirs).await, 200);
        let seq = s.events.len();

        assert_eq!(update(&s, &ta, "carol.test").await, Ok(Json::Null));
        let log = plc.log(&alice);
        assert_eq!(log.len(), 3);
        let (last, op) = (&log[1], &log[2]);
        // Signed by the server's rotation key, `prev` the CID of the last operation.
        assert_eq!(
            plc::verify_update(last, op).unwrap(),
            plc::did_key(s.config.rotation_key.verifying_key())
        );
        assert_eq!(op["prev"], json!(plc::cid(last).unwrap()));
        // Every field but `alsoKnownAs` as it was; the `https://` name kept.
        let mut fields: Vec<&String> = op.as_object().unwrap().keys().collect();
        fields.sort();
        assert_eq!(
            fields,
            [
                "alsoKnownAs",
                "prev",
                "rotationKeys",
                "services",
                "sig",
                "type",
                "verificationMethods"
            ]
        );
        for k in ["type", "rotationKeys", "verificationMethods", "services"] {
            assert_eq!(op[k], last[k], "{k}");
        }
        // The KEM key with the signing key, unchanged (`spec/SPACES.md`).
        assert_eq!(op["verificationMethods"], genesis["verificationMethods"]);
        assert!(
            op["verificationMethods"]["atproto_kem"]
                .as_str()
                .is_some_and(|k| k.starts_with("did:key:zDn"))
        );
        assert_eq!(
            op["alsoKnownAs"],
            json!(["at://carol.test", "https://alice.example.com"])
        );

        // `#identity`, numbered after every event before it.
        let evs = events(&s);
        assert_eq!(evs.len(), seq + 1);
        let ev = evs.last().unwrap();
        assert_eq!(
            (
                ev["t"].clone(),
                ev["seq"].clone(),
                ev["did"].clone(),
                ev["handle"].clone()
            ),
            (
                json!("#identity"),
                json!(seq + 1),
                json!(alice),
                json!("carol.test")
            )
        );
        assert!(ev["time"].is_string());

        // Everything knows it by the new handle, and by the old one nothing.
        let session = call(&s, SESSION, Some(&ta), json!({})).await.unwrap();
        assert_eq!(session["handle"], json!("carol.test"));
        let login = json!({ "identifier": "Carol.Test", "password": "alice-pw" });
        assert_eq!(
            call(&s, "com.atproto.server.createSession", None, login)
                .await
                .unwrap()["handle"],
            json!("carol.test")
        );
        let got = describe(&s, "carol.test").await.unwrap();
        assert_eq!(
            (
                got["did"].clone(),
                got["handle"].clone(),
                got["handleIsCorrect"].clone()
            ),
            (json!(alice), json!("carol.test"), json!(true))
        );
        assert_eq!(
            got["didDoc"]["alsoKnownAs"],
            json!(["at://carol.test", "https://alice.example.com"])
        );
        assert_eq!(describe(&s, "alice.test").await, Err("RepoNotFound".into()));
        let put = |repo: &str| json!({ "repo": repo, "collection": "a.b.c", "rkey": "k", "record": record(1) });
        assert_eq!(
            call(
                &s,
                "com.atproto.repo.putRecord",
                Some(&ta),
                put("alice.test")
            )
            .await,
            Err("AccountNotFound".into())
        );
        call(
            &s,
            "com.atproto.repo.putRecord",
            Some(&ta),
            put("carol.test"),
        )
        .await
        .unwrap();
        assert_eq!(
            resolve(&s, "carol.test").await.unwrap(),
            json!({ "did": alice })
        );
        assert_eq!(
            resolve(&s, "alice.test").await,
            Err("HandleNotFound".into())
        );
        // The old handle is free at once.
        let other = json!({ "handle": "alice.test", "email": "other@mail.com", "password": "pw" });
        assert_eq!(
            call(&s, CREATE, None, other).await.unwrap()["handle"],
            json!("alice.test")
        );

        // describeRepo answers the document as the directory serves it now.
        let mut more = op.clone();
        more["alsoKnownAs"] = json!(["at://carol.test"]);
        more["prev"] = json!(plc::cid(op).unwrap());
        assert_eq!(plc.post(&alice, &plc::signed(&s.config, &more)).await, 200);
        assert_eq!(
            describe(&s, &alice).await.unwrap()["didDoc"]["alsoKnownAs"],
            json!(["at://carol.test"])
        );

        // A directory that refuses: no change, no event, the handle free.
        let n = s.events.len();
        assert_eq!(
            update(&s, &ta, "refused1.test").await,
            Err("InvalidRequest".into())
        );
        assert_eq!(
            (
                handle_of(&s, &alice),
                plc.log(&alice).len(),
                s.events.len(),
                claimed(&s)
            ),
            ("carol.test".into(), 4, n, vec![])
        );
        // One that cannot be reached: the same, and 502.
        plc.down().await;
        assert_eq!(
            update(&s, &ta, "dave.test").await,
            Err("UpstreamFailure".into())
        );
        assert_eq!(
            (handle_of(&s, &alice), s.events.len(), claimed(&s)),
            ("carol.test".into(), n, vec![])
        );
        // describeRepo answers the document it last had.
        let got = describe(&s, "carol.test").await.unwrap();
        assert_eq!(
            (
                got["didDoc"]["alsoKnownAs"].clone(),
                got["handleIsCorrect"].clone()
            ),
            (json!(["at://carol.test"]), json!(true))
        );
        plc.up().await;
        assert_eq!(update(&s, &ta, "dave.test").await, Ok(Json::Null));
        assert_eq!(
            (handle_of(&s, &alice), directory_handle(&plc, &alice)),
            ("dave.test".into(), "dave.test".into())
        );

        // The handle survives a restart, with every event.
        let evs = events(&s);
        drop(s);
        let s = open(&dir, &plc.url);
        assert_eq!(handle_of(&s, &alice), "dave.test");
        assert_eq!(
            resolve(&s, "dave.test").await.unwrap(),
            json!({ "did": alice })
        );
        assert_eq!(events(&s), evs);
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[tokio::test]
    async fn resolve_handle() {
        let plc = Plc::start().await;
        let dir = scratch("identity-resolve");
        let s = open(&dir, &plc.url);
        let (alice, ta) = create(&s, "alice").await;
        assert_eq!(
            resolve(&s, "ALICE.Test").await.unwrap(),
            json!({ "did": alice })
        );
        // A token is ignored, even one the server never gave out.
        let params = [("handle".to_string(), "alice.test".to_string())];
        assert_eq!(
            call_with(&s, RESOLVE, Some("nope"), &params, json!({}))
                .await
                .unwrap(),
            json!({ "did": alice })
        );
        for (handle, want) in [
            ("nobody.test", "HandleNotFound"),
            ("a.b.test", "HandleNotFound"),
            ("admin.test", "HandleNotFound"),
            ("abc.example", "HandleNotFound"),
            ("alice.example.com", "InvalidRequest"),
            ("alice.invalid", "InvalidRequest"),
            ("alice.test.org", "InvalidRequest"),
            ("not a handle", "InvalidRequest"),
            ("alice..test", "InvalidRequest"),
        ] {
            assert_eq!(resolve(&s, handle).await, Err(want.to_string()), "{handle}");
        }
        assert_eq!(
            call(&s, RESOLVE, None, json!({})).await,
            Err("InvalidRequest".into())
        );
        update(&s, &ta, "carol.test").await.unwrap();
        assert_eq!(
            resolve(&s, "alice.test").await,
            Err("HandleNotFound".into())
        );
        assert_eq!(
            resolve(&s, "Carol.test").await.unwrap(),
            json!({ "did": alice })
        );
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// An external handle is the account's only if it resolves to its DID:
    /// by DNS or HTTPS, DNS's DID winning; and then it answers that DID.
    #[tokio::test]
    async fn external_handles() {
        use super::resolve::stub::serve;
        let plc = Plc::start().await;
        let dir = scratch("identity-external");
        let s = open(&dir, &plc.url);
        let (alice, ta) = create(&s, "alice").await;
        let (bob, _) = create(&s, "bob").await;
        let txt = format!("did={alice}");
        let other = format!("did={bob}");
        let body = format!("  {alice} \nmore");
        // Unserved, then another account's DID by either way.
        assert_eq!(
            update(&s, &ta, "alice-ext.com").await,
            Err("InvalidRequest".into())
        );
        serve("alice-ext.com", &[&[&other]], None);
        assert_eq!(
            update(&s, &ta, "alice-ext.com").await,
            Err("InvalidRequest".into())
        );
        serve("alice-ext.com", &[], Some(&bob));
        assert_eq!(
            update(&s, &ta, "alice-ext.com").await,
            Err("InvalidRequest".into())
        );
        // Two `did=` records find none by DNS: the HTTPS answer stands.
        serve("alice-ext.com", &[&[&txt], &[&other]], Some(&alice));
        assert_eq!(update(&s, &ta, "alice-ext.com").await, Ok(Json::Null));
        assert_eq!(handle_of(&s, &alice), "alice-ext.com");
        assert_eq!(
            resolve(&s, "Alice-Ext.com").await.unwrap(),
            json!({ "did": alice })
        );
        // DNS's DID wins over the HTTPS one; a record's strings are joined.
        let (head, tail) = txt.split_at(10);
        serve("alice-dns.net", &[&["v=x"], &[head, tail]], Some(&bob));
        assert_eq!(update(&s, &ta, "Alice-DNS.net").await, Ok(Json::Null));
        serve("alice-dns.net", &[&[&other]], Some(&alice));
        assert_eq!(
            update(&s, &ta, "alice-dns.net").await,
            Err("InvalidRequest".into())
        );
        // By HTTPS alone, its first line trimmed.
        serve("alice.example.org", &[], Some(&body));
        assert_eq!(update(&s, &ta, "alice.example.org").await, Ok(Json::Null));
        assert_eq!(handle_of(&s, &alice), "alice.example.org");
        assert_eq!(directory_handle(&plc, &alice), "alice.example.org");
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// `/.well-known/atproto-did` by `Host`, its port taken off, as given.
    #[tokio::test]
    async fn well_known_by_host() {
        let plc = Plc::start().await;
        let dir = scratch("identity-well-known");
        let s = open(&dir, &plc.url);
        let (alice, ta) = create(&s, "alice").await;
        let text = Some("text/plain; charset=utf-8".to_string());
        assert_eq!(
            well_known_of(&s, Some("alice.test")).await,
            (200, text.clone(), alice.clone())
        );
        assert_eq!(
            well_known_of(&s, Some("alice.test:2583")).await,
            (200, text.clone(), alice.clone())
        );
        for host in [
            Some("Alice.test"),
            Some("ALICE.TEST:80"),
            Some("nobody.test"),
            Some("localhost"),
            Some("127.0.0.1:2583"),
            Some("[::1]:2583"),
            Some("alice.test:"),
            None,
        ] {
            assert_eq!(well_known_of(&s, host).await.0, 404, "{host:?}");
        }
        update(&s, &ta, "carol.test").await.unwrap();
        assert_eq!(well_known_of(&s, Some("alice.test")).await.0, 404);
        assert_eq!(
            well_known_of(&s, Some("carol.test")).await,
            (200, text, alice)
        );
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[tokio::test]
    async fn recommended_credentials() {
        let plc = Plc::start().await;
        let dir = scratch("identity-credentials");
        let s = open(&dir, &plc.url);
        let (alice, ta) = create(&s, "alice").await;
        let genesis = plc.log(&alice)[0].clone();
        let got = call(&s, CREDENTIALS, Some(&ta), json!({})).await.unwrap();
        let rotation = plc::did_key(s.config.rotation_key.verifying_key());
        assert_eq!(
            got,
            json!({
                "alsoKnownAs": ["at://alice.test"],
                "verificationMethods": { "atproto": genesis["verificationMethods"]["atproto"], "atproto_kem": genesis["verificationMethods"]["atproto_kem"] },
                "rotationKeys": [s.config.recovery_did_key.clone().unwrap(), rotation],
                "services": { "atproto_pds": { "type": "AtprotoPersonalDataServer", "endpoint": "http://127.0.0.1:2583" } },
            })
        );
        assert_eq!(
            call(&s, CREDENTIALS, None, json!({})).await,
            Err("AuthMissing".into())
        );
        assert_eq!(
            call(&s, CREDENTIALS, Some("nope"), json!({})).await,
            Err("InvalidToken".into())
        );
        // The handle now, whatever the directory's document says; the same keys.
        update(&s, &ta, "carol.test").await.unwrap();
        let after = call(&s, CREDENTIALS, Some(&ta), json!({})).await.unwrap();
        assert_eq!(after["alsoKnownAs"], json!(["at://carol.test"]));
        assert_eq!(after["verificationMethods"], got["verificationMethods"]);
        assert_eq!(
            plc.log(&alice)[1]["verificationMethods"],
            genesis["verificationMethods"]
        );
        // Each account its own KEM key, which a restart keeps, posting nothing.
        let (bob, tb) = create(&s, "bob").await;
        let bobs = call(&s, CREDENTIALS, Some(&tb), json!({})).await.unwrap();
        assert_eq!(
            bobs["verificationMethods"]["atproto_kem"],
            plc.log(&bob)[0]["verificationMethods"]["atproto_kem"]
        );
        assert_ne!(
            bobs["verificationMethods"]["atproto_kem"],
            got["verificationMethods"]["atproto_kem"]
        );
        drop(s);
        let s = open(&dir, &plc.url);
        assert_eq!(
            call(&s, CREDENTIALS, Some(&ta), json!({})).await.unwrap()["verificationMethods"],
            got["verificationMethods"]
        );
        assert_eq!(
            call(&s, CREDENTIALS, Some(&tb), json!({})).await.unwrap()["verificationMethods"],
            bobs["verificationMethods"]
        );
        assert_eq!((plc.log(&alice).len(), plc.log(&bob).len()), (2, 1));
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// Changes at once to one handle give it to one account at most, and
    /// the loser posts nothing; one account's changes at once land one
    /// after the other. Every account's handle is the one its document names.
    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
    async fn one_handle_one_account() {
        let plc = Plc::start().await;
        let dir = scratch("identity-race");
        let s = open(&dir, &plc.url);
        let (alice, ta) = create(&s, "alice").await;
        let (bob, tb) = create(&s, "bob").await;
        for round in 0..12 {
            let handle = format!("race{round}.test");
            let (na, nb) = (plc.log(&alice).len(), plc.log(&bob).len());
            let (s1, s2) = (s.clone(), s.clone());
            let (h1, h2, t1, t2) = (handle.clone(), handle.clone(), ta.clone(), tb.clone());
            let (a, b) = tokio::join!(
                tokio::spawn(async move { update(&s1, &t1, &h1).await }),
                tokio::spawn(async move { update(&s2, &t2, &h2).await })
            );
            let (a, b) = (a.unwrap(), b.unwrap());
            let (winner, loser, lost) = match (&a, &b) {
                (Ok(_), Err(e)) => (&alice, &bob, e),
                (Err(e), Ok(_)) => (&bob, &alice, e),
                _ => panic!("{a:?} {b:?}"),
            };
            assert_eq!(lost, "HandleNotAvailable");
            assert_eq!(handle_of(&s, winner), handle);
            assert_eq!(plc.log(&alice).len() + plc.log(&bob).len(), na + nb + 1);
            assert_eq!(directory_handle(&plc, winner), handle);
            assert_eq!(directory_handle(&plc, loser), handle_of(&s, loser));
        }
        // An updateHandle and a createAccount of one handle at once.
        for round in 0..12 {
            let handle = format!("both{round}.test");
            let (s1, s2, h1, t1) = (s.clone(), s.clone(), handle.clone(), ta.clone());
            let body = json!({ "handle": handle, "email": format!("both{round}@mail.com"), "password": "pw" });
            let (u, c) = tokio::join!(
                tokio::spawn(async move { update(&s1, &t1, &h1).await }),
                tokio::spawn(async move { call(&s2, CREATE, None, body).await })
            );
            match (u.unwrap(), c.unwrap()) {
                (Ok(_), Err(e)) => {
                    assert_eq!(e, "InvalidRequest");
                    assert_eq!(handle_of(&s, &alice), handle);
                }
                (Err(e), Ok(made)) => {
                    assert_eq!(e, "HandleNotAvailable");
                    assert_eq!(made["handle"], json!(handle));
                    assert_ne!(handle_of(&s, &alice), handle);
                }
                (u, c) => panic!("{u:?} {c:?}"),
            }
            assert_eq!(directory_handle(&plc, &alice), handle_of(&s, &alice));
        }
        // One account's two changes at once: both land, one after the other.
        for round in 0..6 {
            let n = plc.log(&alice).len();
            let (s1, s2, t1, t2) = (s.clone(), s.clone(), ta.clone(), ta.clone());
            let (a, b) = tokio::join!(
                tokio::spawn(async move { update(&s1, &t1, &format!("one{round}.test")).await }),
                tokio::spawn(async move { update(&s2, &t2, &format!("two{round}.test")).await })
            );
            assert_eq!((a.unwrap(), b.unwrap()), (Ok(Json::Null), Ok(Json::Null)));
            assert_eq!(plc.log(&alice).len(), n + 2);
            assert_eq!(directory_handle(&plc, &alice), handle_of(&s, &alice));
        }
        assert!(claimed(&s).is_empty());
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// The account's log, rewritten to end with the frame that records its
    /// last handle change: as if the server stopped after posting it.
    pub(crate) fn stop_before_settling(dir: &std::path::Path, did: &str) {
        redone(dir);
        let path = crate::log::repo_log(dir, did);
        let (frames, _) = pds_store::scan(&std::fs::read(&path).unwrap()).unwrap();
        let n = frames.len();
        assert_eq!(frames[n - 2][0]["t"], json!("handle"));
        assert_eq!(frames[n - 1][0]["t"], json!("handled"));
        let bytes: Vec<u8> = frames[..n - 1]
            .iter()
            .flat_map(|f| pds_store::frame(f))
            .collect();
        std::fs::write(&path, bytes).unwrap();
        // Nor did the service log take the handle settled: its note follows.
        let service = crate::log::accounts_log(dir);
        let (frames, _) = pds_store::scan(&std::fs::read(&service).unwrap()).unwrap();
        let note = |e: &Json| {
            e["t"] == crate::cache::DIR && (e.get("handle").is_some() || e["eager"] == json!(false))
        };
        let bytes: Vec<u8> = frames
            .iter()
            .filter(|f| !f.iter().all(note))
            .flat_map(|f| pds_store::frame(f))
            .collect();
        std::fs::write(&service, bytes).unwrap();
    }

    /// A change the directory took, the server stopped before settling it,
    /// and the directory up as it starts: settled at once, landing whole.
    #[tokio::test]
    async fn unsettled_change_lands_at_start() {
        let plc = Plc::start().await;
        let dir = scratch("identity-crash-up");
        let s = open(&dir, &plc.url);
        let (alice, ta) = create(&s, "alice").await;
        let (_, tb) = create(&s, "bob").await;
        update(&s, &ta, "carol.test").await.unwrap();
        let landed = events(&s);
        drop(s);
        stop_before_settling(&dir, &alice);
        let s = open(&dir, &plc.url);
        // Until it is settled: the old handle, the new one taken, no event.
        assert_eq!(
            (handle_of(&s, &alice), claimed(&s)),
            ("alice.test".to_string(), vec!["carol.test".to_string()])
        );
        assert_eq!(events(&s)[..], landed[..landed.len() - 1]);
        assert_eq!(
            update(&s, &tb, "carol.test").await,
            Err("HandleNotAvailable".into())
        );
        let body = json!({ "handle": "carol.test", "email": "c@mail.com", "password": "pw" });
        assert_eq!(
            call(&s, CREATE, None, body).await,
            Err("InvalidRequest".into())
        );
        settle_unfinished(&s);
        settled(&s, &alice, "carol.test", 3).await;
        let evs = events(&s);
        assert_eq!(evs.len(), landed.len());
        assert_eq!(evs[..evs.len() - 1], landed[..landed.len() - 1]);
        // Its event is numbered after every seq given out: the index keeps
        // the entry of the one the stop cut, never sent, and its seq is not
        // given again.
        let ev = evs.last().unwrap();
        assert_eq!(
            (ev["t"].clone(), ev["seq"].clone(), ev["handle"].clone()),
            (
                json!("#identity"),
                json!(landed.last().unwrap()["seq"].as_u64().unwrap() + 1),
                json!("carol.test")
            )
        );
        assert_eq!(plc.log(&alice).len(), 2);
        assert_eq!(
            resolve(&s, "alice.test").await,
            Err("HandleNotFound".into())
        );
        // Settled for good.
        drop(s);
        let s = open(&dir, &plc.url);
        assert_eq!(
            (handle_of(&s, &alice), claimed(&s), events(&s)),
            ("carol.test".to_string(), vec![], evs)
        );
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// The same with the directory down as the server starts: it serves at
    /// once, with the old handle, and settles the change once it can.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn unsettled_change_waits_for_the_directory() {
        let plc = Plc::start().await;
        let dir = scratch("identity-crash-down");
        let s = open(&dir, &plc.url);
        let (alice, ta) = create(&s, "alice").await;
        let (_, tb) = create(&s, "bob").await;
        update(&s, &ta, "carol.test").await.unwrap();
        let landed = events(&s);
        let n = landed.len();
        drop(s);
        stop_before_settling(&dir, &alice);
        plc.down().await;
        let s = open(&dir, &plc.url);
        settle_unfinished(&s);
        assert_eq!(
            call(&s, SESSION, Some(&ta), json!({})).await.unwrap()["handle"],
            json!("alice.test")
        );
        assert_eq!(
            describe(&s, "alice.test").await.unwrap()["handle"],
            json!("alice.test")
        );
        assert_eq!(
            resolve(&s, "alice.test").await.unwrap(),
            json!({ "did": alice })
        );
        assert_eq!(
            resolve(&s, "carol.test").await,
            Err("HandleNotFound".into())
        );
        assert_eq!(well_known_of(&s, Some("alice.test")).await.0, 200);
        assert_eq!(well_known_of(&s, Some("carol.test")).await.0, 404);
        assert_eq!(
            update(&s, &tb, "carol.test").await,
            Err("HandleNotAvailable".into())
        );
        // Another change of the account waits for it to settle, which cannot be done.
        assert_eq!(
            update(&s, &ta, "dave.test").await,
            Err("UpstreamFailure".into())
        );
        assert_eq!(
            (handle_of(&s, &alice), claimed(&s), events(&s)),
            (
                "alice.test".to_string(),
                vec!["carol.test".to_string()],
                landed[..n - 1].to_vec()
            )
        );
        plc.up().await;
        settled(&s, &alice, "carol.test", 5).await;
        let evs = events(&s);
        assert_eq!(
            (
                evs.len(),
                evs[n - 1]["t"].clone(),
                evs[n - 1]["handle"].clone()
            ),
            (n, json!("#identity"), json!("carol.test"))
        );
        assert_eq!(update(&s, &ta, "dave.test").await, Ok(Json::Null));
        assert_eq!(directory_handle(&plc, &alice), "dave.test");
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// A change whose operation the directory never took is dropped as the
    /// server starts: the handle free again, and nothing else changed.
    #[tokio::test]
    async fn untaken_change_is_dropped() {
        let plc = Plc::start().await;
        let dir = scratch("identity-crash-dropped");
        let s = open(&dir, &plc.url);
        let (alice, ta) = create(&s, "alice").await;
        assert_eq!(
            update(&s, &ta, "refused1.test").await,
            Err("InvalidRequest".into())
        );
        let evs = events(&s);
        drop(s);
        stop_before_settling(&dir, &alice);
        let s = open(&dir, &plc.url);
        assert_eq!(claimed(&s), ["refused1.test"]);
        settle_unfinished(&s);
        settled(&s, &alice, "alice.test", 3).await;
        assert_eq!((events(&s), plc.log(&alice).len()), (evs.clone(), 1));
        drop(s);
        let s = open(&dir, &plc.url);
        assert_eq!(
            (handle_of(&s, &alice), claimed(&s), events(&s)),
            ("alice.test".to_string(), vec![], evs)
        );
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// With `PDS_DID_CACHE_SECS`, `describeRepo` serves the document kept, not
    /// one changed behind the server's back, until it is that old; after the
    /// server's own handle change, the new document at once.
    #[tokio::test]
    async fn documents_are_kept() {
        let plc = Plc::start().await;
        let dir = scratch("did-cache");
        let s = open_with(&dir, &plc.url, |c| c.did_cache = 60);
        s.limits.clock.freeze();
        let (alice, ta) = create(&s, "alice").await;
        let genesis = plc.log(&alice).pop().unwrap();
        let mut theirs = genesis.clone();
        theirs["alsoKnownAs"] = json!(["at://elsewhere.test"]);
        theirs["prev"] = json!(plc::cid(&genesis).unwrap());
        assert_eq!(
            plc.post(&alice, &plc::signed(&s.config, &theirs)).await,
            200
        );
        let aka = |d: Json| d["didDoc"]["alsoKnownAs"].clone();
        assert_eq!(
            aka(describe(&s, &alice).await.unwrap()),
            json!(["at://alice.test"])
        );
        // Older than the cache's time: fetched again.
        s.limits
            .clock
            .skew
            .store(61, std::sync::atomic::Ordering::SeqCst);
        assert_eq!(
            aka(describe(&s, &alice).await.unwrap()),
            json!(["at://elsewhere.test"])
        );
        // The server's own change: at once.
        update(&s, &ta, "carol.test").await.unwrap();
        let got = describe(&s, "carol.test").await.unwrap();
        assert_eq!(
            (aka(got.clone()), &got["handleIsCorrect"]),
            (json!(["at://carol.test"]), &json!(true))
        );
        // Down, the directory is not asked while the document is young.
        plc.down().await;
        assert_eq!(
            aka(describe(&s, &alice).await.unwrap()),
            json!(["at://carol.test"])
        );
        plc.up().await;
        let _ = std::fs::remove_dir_all(&dir);
    }
}