didbot_serve/

dashboard.rs

//! The per-server homepage and operations dashboard: this server, reporting
//! on itself. `docs/web-surfaces.md` calls this surface 3 of the project's
//! four websites, and draws the boundary this module keeps: it is served by
//! `didbot-serve`, about the deployment serving it, one per deployment
//! rather than one for the whole project, and it owns no policy — policy is
//! written from a separate, statically-hosted origin (surface 2) and only
//! ever read here, never edited.
//!
//! It answers before anyone signs in: [`about`] says what this deployment
//! is (its zone) and what it holds (`bot.did.stats`'s own numbers, reused rather than
//! reread). Everything past that is the authenticated operations view.
//!
//! `plan/ops-dashboard.md` sets one rule above everything else it asks for:
//! *never display invented data as if it were real*. Every panel this module
//! serves answers in exactly one of three states, carried in
//! [`crate::surface::PanelState`] rather than left for a client to infer
//! from shape:
//!
//! - **Live** — a real capability, read fresh from this process's own state.
//! - **Not implemented** — the epic it needs does not exist yet
//!   (`write-policy`, `scope-policy`, `app-allowlist`, `oauth`). Names what
//!   is missing and carries no numbers at all, because a plausible-looking
//!   zero is a lie this dashboard is built specifically not to tell.
//! - **Unreachable** — a real capability whose read failed, which is a
//!   different fact from a real capability that read as zero.
//!
//! `panel_state_never_carries_numbers_without_a_backing_capability` is the
//! mechanical guard on that rule: it asserts, at the JSON level, that
//! [`PanelState::NotImplemented`] and [`PanelState::Unreachable`] can never
//! serialize a `data` field, so a future panel cannot regress into showing a
//! number for a capability that is not there.
//!
//! # What is public here, and what is not
//!
//! Public: the static shell and its assets, [`about`] and [`capabilities`],
//! and the client metadata document — [`about`] is `bot.did.stats`'s own
//! public numbers, [`capabilities`] names which epics are unbuilt, which
//! `plan/` already says out loud, and the metadata document's own URL is
//! the `client_id`, so the operator's authorization server has to be able
//! to fetch it before it will show them a consent screen.
//!
//! Behind the operator sign-in: the e-stop's status and its two controls,
//! the `bot.did.operator` records the poll last read out of the operator's
//! own repository, and the relay announce. What authenticates them is
//! [`crate::operator`] — atproto OAuth against the operator's *own* server,
//! requesting `atproto` and nothing else, with the verified `sub` compared
//! against this deployment's `--operator`. No operator credential reaches this
//! server, which is what `plan/handshake.md` is protecting: the sign-in
//! proves control of a DID, and this server then issues a session of its
//! own.
//!
//! An anonymous, internet-reachable halt would be a denial of service
//! rather than an emergency stop, which is why throwing costs a sign-in
//! too and not only releasing.
//!
//! The session list still has no data behind it, and renders
//! [`PanelState::NotImplemented`] naming the epic it waits on. That is the
//! same honesty rule the rest of this module follows: a panel whose data
//! this server does not have is a panel that says so, not one showing a
//! plausible zero.
//!
//! The per-app panels — live logins, refusals and writes — are
//! [`crate::dashboard_apps`]'s, and the account list and detail are
//! [`crate::dashboard_accounts`]'s, both merged into this module's router.

use axum::extract::State;
use axum::http::StatusCode;
use axum::response::{IntoResponse, Response};
use axum::routing::{get, post};
use axum::{Json, Router};
use didbot_pds::{Actor, Lock};
use serde::Serialize;
use serde_json::json;

use crate::landing;
use crate::routes::AppState;
use crate::surface::{
    acting_operator, asset, html, operator, refusal, script, session_cookie, signed_in, stylesheet,
    PanelState, SESSION_COOKIE,
};
use crate::wire::{LifecycleLine, StatsResponse};

const INDEX_HTML: &str = include_str!("../assets/dashboard/index.html");
const DASHBOARD_CSS: &str = include_str!("../assets/dashboard/dashboard.css");
const DASHBOARD_JS: &str = include_str!("../assets/dashboard/dashboard.js");

// `DASHBOARD_WASM`: name, content type and bytes for each file of the wave
// field, copied into the build's own output by `build.rs` from whatever was
// on disk when this crate was compiled. See `wasm_asset`.
include!(concat!(env!("OUT_DIR"), "/dashboard_wasm.rs"));

/// Exposes the three asset constants to `crate::tests`'s accessibility
/// checks, which read the served markup, stylesheet and script as text
/// rather than duplicating them. Test-only: nothing outside a test binary
/// has a reason to read these three as strings instead of serving them.
#[cfg(test)]
pub(crate) fn dashboard_html_for_test() -> &'static str {
    INDEX_HTML
}

#[cfg(test)]
pub(crate) fn dashboard_css_for_test() -> &'static str {
    DASHBOARD_CSS
}

#[cfg(test)]
pub(crate) fn dashboard_js_for_test() -> &'static str {
    DASHBOARD_JS
}

/// Builds the dashboard's routes, to be merged into the main router.
///
/// Not merged into `atproto_routes()` or listed in `ROUTE_CREDENTIALS`:
/// these are not `com.atproto.*`/`bot.did.*` NSIDs. Every one of them is
/// public — see the module doc for why the operations routes that were not
/// are gone rather than re-gated.
pub fn routes() -> Router<AppState> {
    // Once, where a deployment will see it: a missing background is
    // otherwise two 404s on a page nobody is watching the log for.
    if DASHBOARD_WASM.is_empty() {
        tracing::info!(
            "the dashboard's animated background was not built into this binary; the page \
             falls back to a still one. Run scripts/build-dashboard-wasm.sh and rebuild to \
             include it."
        );
    }
    Router::new()
        .route("/dashboard", get(index))
        .route("/dashboard/dashboard.css", get(css))
        .route("/dashboard/dashboard.js", get(js))
        .route("/dashboard/wasm/{file}", get(wasm_asset))
        .route("/dashboard/api/about", get(about))
        .route("/dashboard/api/capabilities", get(capabilities))
        .route(crate::operator::CLIENT_METADATA_PATH, get(client_metadata))
        .route("/dashboard/login", get(login))
        .route(crate::operator::CALLBACK_PATH, get(callback))
        .route("/dashboard/logout", post(logout))
        .route("/dashboard/api/estop", get(estop_status))
        .route("/dashboard/api/operator-records", get(operator_records))
        .route("/dashboard/api/estop/throw", post(estop_throw))
        .route("/dashboard/api/estop/release", post(estop_release))
        .route("/dashboard/api/relay/announce", post(relay_announce))
        .route("/dashboard/api/accounts/{did}/lock", post(account_lock))
        .route("/dashboard/api/accounts/{did}/unlock", post(account_unlock))
        .route(
            "/dashboard/api/accounts/{did}/lift-quarantine",
            post(account_lift_quarantine),
        )
        .route("/dashboard/api/accounts/{did}/erase", post(account_erase))
        .route("/dashboard/api/accounts/{did}/delete", post(account_delete))
        .route(
            "/dashboard/api/accounts/{did}/revoke-tokens",
            post(account_revoke_tokens),
        )
        .route(
            "/dashboard/api/accounts/{did}/credentials",
            post(account_credentials),
        )
        .merge(crate::dashboard_apps::routes())
        .merge(crate::dashboard_accounts::routes())
}

/// `GET /dashboard/oauth/client-metadata.json`
///
/// Public, and has to be: this document's own URL is the `client_id`, and
/// the operator's authorization server fetches it before it will show them
/// a consent screen.
async fn client_metadata(State(state): State<AppState>) -> Response {
    let operator = match operator(&state) {
        Ok(operator) => operator,
        Err(refusal) => return *refusal,
    };
    match operator.client_metadata_document() {
        Ok(document) => Json(document).into_response(),
        Err(error) => refusal(StatusCode::INTERNAL_SERVER_ERROR, "ClientMetadata", error),
    }
}

/// `GET /dashboard/login`
///
/// Redirects to the operator's own authorization server. The identity is
/// the one `--operator` names: a request naming another is refused here,
/// before anything is resolved or fetched. A browser follows this from a
/// link, so every refusal is a page.
async fn login(
    State(state): State<AppState>,
    peer: crate::rate_limit::Peer,
    headers: axum::http::HeaderMap,
    axum::extract::Query(query): axum::extract::Query<LoginQuery>,
) -> Response {
    let Some(operator) = state.operator.as_ref() else {
        return no_operator();
    };
    // Unauthenticated by necessity — signing in is how a caller gets a
    // credential — and each call makes this server resolve an identity and
    // push an authorization request to a host the caller named. Bounded the
    // same way `POST /oauth/par` already is.
    let key = crate::rate_limit::caller_key(&headers, peer.0, state.trust_forwarded_headers);
    if !state.operator_login_limiter.check(&key) {
        return landing::too_many(landing::OPERATOR);
    }
    // This deployment knows who it is waiting for, and resolving anyone
    // else would make it fetch from a host a stranger named. Refused before
    // the resolution rather than ignored, so a caller that meant something
    // by the parameter is told it means nothing.
    if query
        .handle
        .as_deref()
        .is_some_and(|handle| handle != operator.operator_did())
    {
        return landing::refused(
            StatusCode::BAD_REQUEST,
            landing::OPERATOR,
            "NotTheOperator",
            &format!("this server signs in as {} only", operator.operator_did()),
            "",
            "Sign in as its operator instead.",
        );
    }
    match operator.start(query.cli.as_deref()).await {
        Ok(url) => axum::response::Redirect::to(&url).into_response(),
        Err(error @ crate::operator::SignInError::NotLoopback { .. }) => {
            tracing::info!(%error, "refused an operator sign-in");
            landing::refused(
                StatusCode::BAD_REQUEST,
                landing::OPERATOR,
                "NotLoopback",
                "a command line's sign-in must come back to its own machine",
                "",
                "Run `didbot login` again.",
            )
        }
        Err(error) => {
            tracing::warn!(%error, "an operator sign-in could not start");
            landing::refused(
                StatusCode::BAD_GATEWAY,
                landing::OPERATOR,
                "SignIn",
                "could not reach the operator's own server",
                "",
                "Check that the operator's server is up, then sign in again.",
            )
        }
    }
}

/// The page [`login`] and [`callback`] answer on a deployment started
/// with no `--operator`.
fn no_operator() -> Response {
    landing::refused(
        StatusCode::SERVICE_UNAVAILABLE,
        landing::OPERATOR,
        "NoOperator",
        "this server has no operator to sign in as",
        "",
        "Start it with --operator to sign in here.",
    )
}

/// What `/dashboard/login` accepts.
#[derive(serde::Deserialize)]
pub struct LoginQuery {
    /// Accepted only when it names this deployment's operator, so a link
    /// carrying the parameter says what it does rather than being ignored.
    handle: Option<String>,
    /// Where to send the browser once signed in, for a command line waiting
    /// on a loopback address. Refused unless it is loopback — see
    /// [`crate::operator::OperatorAuth::start`].
    cli: Option<String>,
}

/// `GET /dashboard/callback`
///
/// Where the operator's authorization server sends the browser back. A
/// sign-in the page started goes back to the page, with the session's CSRF
/// token in the address: `dashboard.js` reads it once and takes it out of
/// the address bar. A sign-in a command line started goes to the loopback
/// address it is waiting on. A sign-in that ended any other way is a page
/// saying so.
async fn callback(
    State(state): State<AppState>,
    axum::extract::Query(query): axum::extract::Query<CallbackQuery>,
) -> Response {
    /// What every way a sign-in can end here says to do next.
    const AGAIN: &str = "Sign in again. If a terminal started this sign-in, run its command again.";
    let Some(operator) = state.operator.as_ref() else {
        return no_operator();
    };
    let Some(code) = query.code else {
        return match query.error {
            Some(error) => {
                tracing::info!(
                    error,
                    description = query.error_description,
                    "the operator's server ended a sign-in without a code"
                );
                // Its description is the operator's own server's account of
                // why, set in text and cut short.
                let said = query
                    .error_description
                    .map(|said| {
                        let said: String = said.chars().take(300).collect();
                        format!(
                            "<p data-said>The operator's server said: {}</p>",
                            didbot_brand::page::escape(&said)
                        )
                    })
                    .unwrap_or_default();
                landing::refused(
                    StatusCode::FORBIDDEN,
                    landing::OPERATOR,
                    &error,
                    "sign-in denied",
                    &said,
                    AGAIN,
                )
            }
            None => landing::refused(
                StatusCode::BAD_REQUEST,
                landing::OPERATOR,
                "InvalidRequest",
                "this address is for the operator's own server to send a browser back to",
                "",
                AGAIN,
            ),
        };
    };
    let params = jacquard_oauth::types::CallbackParams {
        code: code.into(),
        state: query.state.map(Into::into),
        iss: query.iss.map(Into::into),
    };
    match operator.finish(params).await {
        Ok(signed_in) => {
            // `Secure` unconditionally: this deployment serves TLS, and a
            // session cookie that survives a downgrade is one an observer
            // can lift. `SameSite=Lax` so the redirect back from the
            // operator's server still carries it, with `CSRF_HEADER`
            // carrying the part `Lax` does not cover.
            let cookie = format!(
                "{SESSION_COOKIE}={}; HttpOnly; Secure; SameSite=Lax; Path=/dashboard; Max-Age={}",
                signed_in.token,
                operator.session_ttl().as_secs(),
            );
            // A command line holds no cookie jar, so it takes the session
            // itself at its loopback address. The page gets the cookie, and
            // its buttons echo the token its address carries.
            let to = match &signed_in.cli_redirect {
                Some(handoff) => format!(
                    "{handoff}?token={}&csrf={}",
                    signed_in.token, signed_in.csrf
                ),
                None => format!("/dashboard?csrf={}", signed_in.csrf),
            };
            (
                [(axum::http::header::SET_COOKIE, cookie)],
                axum::response::Redirect::to(&to),
            )
                .into_response()
        }
        Err(crate::operator::SignInError::NotTheOperator { got }) => landing::refused(
            StatusCode::FORBIDDEN,
            landing::OPERATOR,
            "NotTheOperator",
            &format!("signed in as {got}, which is not this server's operator"),
            "",
            &format!("Sign in as {} instead.", operator.operator_did()),
        ),
        Err(error) => {
            tracing::warn!(%error, "an operator sign-in did not finish");
            landing::refused(
                StatusCode::FORBIDDEN,
                landing::OPERATOR,
                "SignIn",
                "this sign-in could not be finished",
                "<p>It expired, was already used, or its server refused the exchange.</p>",
                AGAIN,
            )
        }
    }
}

/// What the authorization server sends back.
#[derive(serde::Deserialize)]
pub struct CallbackQuery {
    /// The authorization code, when the sign-in was approved.
    code: Option<String>,
    /// The `state` this server sent, echoed back.
    state: Option<String>,
    /// RFC 9207's issuer, against server mix-up.
    iss: Option<String>,
    /// RFC 6749 §4.1.2.1's error, when it was not.
    error: Option<String>,
    /// And the server's own words for it.
    error_description: Option<String>,
}

/// `POST /dashboard/logout`
async fn logout(State(state): State<AppState>, headers: axum::http::HeaderMap) -> Response {
    if let (Ok(operator), Some(token)) = (operator(&state), session_cookie(&headers)) {
        operator.sign_out(&token);
    }
    let cleared =
        format!("{SESSION_COOKIE}=; HttpOnly; Secure; SameSite=Lax; Path=/dashboard; Max-Age=0");
    (
        StatusCode::OK,
        [(axum::http::header::SET_COOKIE, cleared)],
        Json(json!({ "signedIn": false })),
    )
        .into_response()
}

/// `GET /dashboard/api/estop`
///
/// What the latch is doing and what it has refused since it engaged.
async fn estop_status(State(state): State<AppState>, headers: axum::http::HeaderMap) -> Response {
    if let Err(refusal) = signed_in(&state, &headers, false) {
        return *refusal;
    }
    Json(PanelState::Live {
        data: state.estop.status(),
    })
    .into_response()
}

/// `POST /dashboard/api/estop/throw`
async fn estop_throw(
    State(state): State<AppState>,
    headers: axum::http::HeaderMap,
    Json(body): Json<ThrowBody>,
) -> Response {
    if let Err(refusal) = signed_in(&state, &headers, true) {
        return *refusal;
    }
    // `plan/server-lifecycle.md`'s rule: an e-stop halts something that is
    // running, and a server that has not finished arriving is not.
    if !state.lifecycle.policy().may_halt {
        return refusal(
            StatusCode::CONFLICT,
            "NotRunning",
            format!(
                "this server is `{}`, a state in which the stop means nothing",
                state.lifecycle.state()
            ),
        );
    }
    if let Err(refusal) = as_the_operator(&state, |estop| estop.throw(body.mode)) {
        return *refusal;
    }
    Json(PanelState::Live {
        data: state.estop.status(),
    })
    .into_response()
}

/// Moves the latch inside a span naming this deployment's operator, so the
/// line the latch logs for the throw or the release says who asked. The
/// span carries the DID and nothing from the session.
fn as_the_operator(
    state: &AppState,
    act: impl FnOnce(&didbot_pds::Estop),
) -> Result<(), Box<Response>> {
    let operator = acting_operator(state)?;
    tracing::info_span!("operator", operator = %operator).in_scope(|| act(&state.estop));
    Ok(())
}

/// What `/dashboard/api/estop/throw` accepts.
#[derive(serde::Deserialize)]
pub struct ThrowBody {
    /// Which setting to throw.
    mode: didbot_pds::EstopMode,
}

/// `POST /dashboard/api/estop/release`
///
/// Clears the operator's latch. Costs exactly what throwing costs — see
/// `didbot_pds::Estop::throw`.
async fn estop_release(State(state): State<AppState>, headers: axum::http::HeaderMap) -> Response {
    if let Err(refusal) = signed_in(&state, &headers, true) {
        return *refusal;
    }
    if let Err(refusal) = as_the_operator(&state, didbot_pds::Estop::release) {
        return *refusal;
    }
    Json(PanelState::Live {
        data: state.estop.status(),
    })
    .into_response()
}

/// One `bot.did.operator` record in the operator's own repository, as the
/// panel shows it.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct OperatorRecordView {
    /// The record's own address in the operator's repository.
    uri: String,
    /// The account the record names.
    subject: String,
    /// When its writer says they wrote it, by their own clock.
    created_at: Option<String>,
    /// Whether `subject` is an account this deployment holds. A record
    /// naming somewhere else is still the operator's to recognise.
    hosted_here: bool,
    /// What the account is, when this deployment holds it.
    #[serde(skip_serializing_if = "Option::is_none")]
    kind: Option<didbot_pds::AccountKind>,
    /// What logs in as the account, when this deployment holds it: the key
    /// fingerprints and OpenID Connect identities it was admitted with, and
    /// any changed since.
    #[serde(skip_serializing_if = "Option::is_none")]
    credentials: Option<Vec<crate::dashboard_accounts::CredentialView>>,
}

/// `GET /dashboard/api/operator-records`
///
/// Every `bot.did.operator` record the poll's last listing of the
/// operator's repository read, so the operator can find one they did not
/// write. An app holding their session writes as them, and their PDS cannot
/// tell the two apart, so seeing the records is the whole of the defence.
///
/// Read-only, and nothing here marks a record: what a record says is the
/// operator's repository's business, and this deployment reading it does
/// not make it this deployment's.
///
/// `Unreachable` rather than an empty list when no listing has landed yet —
/// a repository holding no records and a poll that has not read one are
/// different facts, and a zero standing in for the second is the lie this
/// module is built not to tell.
async fn operator_records(
    State(state): State<AppState>,
    headers: axum::http::HeaderMap,
) -> Response {
    if let Err(refusal) = signed_in(&state, &headers, false) {
        return *refusal;
    }
    let Some(lines) = state.operator_records.read() else {
        return Json(PanelState::<Vec<OperatorRecordView>>::Unreachable {
            reason: "the operator poll has not listed the operator's repository yet".to_owned(),
        })
        .into_response();
    };
    Json(PanelState::Live {
        data: lines
            .into_iter()
            .map(|line| {
                let kind = state.registry.account(&line.subject).map(|held| held.kind);
                OperatorRecordView {
                    hosted_here: kind.is_some(),
                    kind,
                    credentials: kind
                        .map(|_| crate::dashboard_accounts::credentials(&state, &line.subject)),
                    uri: line.uri,
                    subject: line.subject,
                    created_at: line.created_at,
                }
            })
            .collect::<Vec<_>>(),
    })
    .into_response()
}

/// `GET /dashboard`
///
/// The static shell only — no server-rendered numbers here at all. Every
/// panel's data comes from the `/dashboard/api/*` routes below, fetched by
/// `dashboard.js`, and both of them answer anyone: a homepage has to answer
/// before anyone signs in, and there is nobody to sign in as yet. The
/// operations panels are rendered client-side as not-implemented; see the
/// module doc.
async fn index() -> Response {
    html(INDEX_HTML)
}

/// `GET /dashboard/dashboard.css`
async fn css() -> Response {
    stylesheet(DASHBOARD_CSS)
}

/// `GET /dashboard/dashboard.js`
async fn js() -> Response {
    script(DASHBOARD_JS)
}

/// `GET /dashboard/wasm/{file}`
///
/// The travelling-wave field's compiled wasm, built by
/// `scripts/build-dashboard-wasm.sh` from `crates/didbot-site-anim` — an
/// opt-in build step, same as `scripts/build-wasm.sh` for the site, so
/// `cargo build`/`cargo test` never need a wasm32 toolchain. Run it, then
/// rebuild: `build.rs` bakes whatever it finds into the binary, and this
/// route serves that and never the filesystem. So a binary carries its own
/// background wherever it is copied, and a binary built without the step
/// answers 404 — which `dashboard.js` treats as "no field available",
/// falling back to a still background, the same fallback
/// `prefers-reduced-motion` gets.
///
/// `DASHBOARD_WASM` is also the allowlist: a name that is not in it is not
/// served, which is the whole of this endpoint's `../`-refusal.
async fn wasm_asset(axum::extract::Path(file): axum::extract::Path<String>) -> Response {
    match DASHBOARD_WASM
        .iter()
        .find(|(name, _, _)| *name == file.as_str())
    {
        Some((_, content_type, bytes)) => asset(content_type, *bytes),
        None => StatusCode::NOT_FOUND.into_response(),
    }
}

/// What the unauthenticated homepage panel reports.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct AboutView {
    /// This deployment's own zone — what it is, not the project's name.
    /// `docs/web-surfaces.md`: there is one of these pages per deployment,
    /// not one for the project, and nothing here should assume there is
    /// only one server in the world.
    zone: String,
    stats: StatsResponse,
    /// What the deployment is doing right now. A halted or unclaimed server
    /// still answers this route, and this is the field that says so — the
    /// envelope's `live` is about the panel, not about the server.
    lifecycle: LifecycleLine,
}

/// `GET /dashboard/api/about`
///
/// What this server is and what it holds, for anyone. Reuses exactly
/// what `bot.did.stats` (`Credential::Public`) already serves, over the same
/// `Registry` — this is that route's data, not a second read of it.
async fn about(State(state): State<AppState>) -> Response {
    Json(PanelState::Live {
        data: AboutView {
            zone: state.registry.zone().to_owned(),
            stats: StatsResponse::from_stats(&state.registry.stats()),
            lifecycle: LifecycleLine::from_snapshot(&state.lifecycle.snapshot()),
        },
    })
    .into_response()
}

/// `GET /dashboard/api/capabilities`
///
/// The dashboard's own honesty ledger: what it can and cannot show, and
/// why, so an operator does not have to infer completeness from an absent
/// panel. `plan/ops-dashboard.md`'s "say what it cannot be trusted about"
/// is not only this endpoint — the trust note on the page itself says the
/// same thing in prose — but this is the machine-readable form of it.
/// Public, like everything else this module serves: it names which epics are
/// unbuilt and nothing else, which is a fact `plan/` publishes anyway. Gating
/// the honesty ledger behind the credential whose absence it is reporting was
/// circular even before that credential turned out not to exist.
///
/// A live entry here carries `data: null`: this is the ledger, not the
/// panel, and the number a panel has belongs on the panel. What the ledger
/// says is which of the three states each panel is in and, for the ones
/// that are not there, which epic each waits on.
async fn capabilities() -> Response {
    Json(json!({
        "operatorSignIn": PanelState::Live { data: () },
        "estop": PanelState::Live { data: () },
        "operatorRecords": PanelState::Live { data: () },
        "sessions": PanelState::<()>::NotImplemented { missing: vec!["oauth"] },
        "accounts": PanelState::Live { data: () },
        "refusalLog": PanelState::Live { data: () },
        "grants": PanelState::Live { data: () },
        "writes": PanelState::Live { data: () },
    }))
    .into_response()
}

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

    /// The mechanical guard on the epic's honesty rule: a panel reporting
    /// that its capability is absent, or that it could not be reached, can
    /// never carry a `data` field — the field [`PanelState::Live`] is the
    /// only variant that has. This is checked at the JSON level rather than
    /// by inspecting the enum, because JSON is what an operator's browser
    /// actually receives and a future refactor of the Rust shape should not
    /// be able to pass this test while a client-visible number leaks back
    /// in some other field name.
    #[test]
    fn panel_state_never_carries_numbers_without_a_backing_capability() {
        let live = serde_json::to_value(PanelState::Live { data: 42 }).unwrap();
        assert_eq!(live["status"], "live");
        assert_eq!(live["data"], 42);

        let not_implemented = serde_json::to_value(PanelState::NotImplemented::<i32> {
            missing: vec!["write-policy"],
        })
        .unwrap();
        assert_eq!(not_implemented["status"], "not_implemented");
        assert!(
            not_implemented.get("data").is_none(),
            "a not-implemented panel must carry no data field at all: {not_implemented}"
        );
        assert_eq!(not_implemented["missing"][0], "write-policy");

        let unreachable = serde_json::to_value(PanelState::Unreachable::<i32> {
            reason: "timed out".to_owned(),
        })
        .unwrap();
        assert_eq!(unreachable["status"], "unreachable");
        assert!(
            unreachable.get("data").is_none(),
            "an unreachable panel must carry no data field at all: {unreachable}"
        );
        // And it must not be confusable with a live zero: no numeric field
        // anywhere in its JSON.
        assert!(
            unreachable
                .as_object()
                .unwrap()
                .values()
                .all(|v| !v.is_number()),
            "an unreachable panel must not carry any number: {unreachable}"
        );
    }

    #[test]
    fn the_three_states_serialize_to_distinct_tags() {
        let values = [
            serde_json::to_value(PanelState::Live { data: 1 }).unwrap(),
            serde_json::to_value(PanelState::NotImplemented::<i32> { missing: vec![] }).unwrap(),
            serde_json::to_value(PanelState::Unreachable::<i32> {
                reason: String::new(),
            })
            .unwrap(),
        ];
        let tags: Vec<&str> = values
            .iter()
            .map(|v| v["status"].as_str().unwrap())
            .collect();
        let unique: std::collections::HashSet<&str> = tags.iter().copied().collect();
        assert_eq!(
            unique.len(),
            3,
            "the three panel states must render distinguishably: {tags:?}"
        );
    }

    /// The route used to read the build machine's source path at request
    /// time, so a binary moved anywhere else served two 404s. What it
    /// serves is settled when the binary is compiled.
    #[tokio::test]
    async fn the_field_comes_from_the_binary_and_not_from_the_source_tree() {
        let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("assets/dashboard/wasm");
        let name = "site-anim.js";
        let path = dir.join(name);

        if let Some((_, _, baked)) = DASHBOARD_WASM.iter().find(|(n, _, _)| *n == name) {
            let served = body_of(wasm_asset(axum::extract::Path(name.to_owned())).await).await;
            assert_eq!(
                served.as_slice(),
                *baked,
                "the route served something other than what was compiled in"
            );
            return;
        }

        // Nothing was compiled in. A file appearing on disk afterwards is
        // the build machine's source tree, and this binary must not read
        // it. Planted only when the opt-in build has not left a real one.
        let planted = !path.exists();
        if planted {
            std::fs::create_dir_all(&dir).expect("make the asset directory");
            std::fs::write(&path, b"// not compiled into this binary")
                .expect("plant a file the binary never saw");
        }
        let response = wasm_asset(axum::extract::Path(name.to_owned())).await;
        let status = response.status();
        if planted {
            let _ = std::fs::remove_file(&path);
        }
        assert_eq!(
            status,
            StatusCode::NOT_FOUND,
            "the route read {} at request time",
            path.display()
        );
    }

    /// A path from the machine that compiled this crate has no business in
    /// the binary it produced: `include_bytes!` records the file it read in
    /// the source map, so an absolute source path reaches every build made
    /// from it. `build.rs` copies each asset into the build's own output and
    /// includes it from there, by bare name.
    #[test]
    fn the_asset_table_names_no_build_machine_path() {
        const TABLE: &str = include_str!(concat!(env!("OUT_DIR"), "/dashboard_wasm.rs"));
        assert!(
            !TABLE.contains(env!("CARGO_MANIFEST_DIR")),
            "the asset table names the tree it was built from:\n{TABLE}"
        );
        for (name, _, _) in DASHBOARD_WASM {
            assert!(
                TABLE.contains(&format!("include_bytes!({name:?})")),
                "{name} is included by something other than its bare name:\n{TABLE}"
            );
        }
    }

    async fn body_of(response: Response) -> Vec<u8> {
        axum::body::to_bytes(response.into_body(), usize::MAX)
            .await
            .expect("read the response body")
            .to_vec()
    }
}

/// `POST /dashboard/api/relay/announce`
///
/// Asks every configured relay to crawl this server. An operator command like
/// the stop, reached the same way, because it is the same question: who may
/// tell this server to do something. `plan/federation.md` keeps it
/// deliberate rather than automatic — naming a relay does not announce
/// anything by itself.
///
/// The answer lists each relay with one of the three outcomes
/// `docs/conformance.md` names, because an operator who asked needs to know
/// which happened at each relay and not just that the call returned.
async fn relay_announce(
    State(state): State<AppState>,
    headers: axum::http::HeaderMap,
    Json(body): Json<AnnounceBody>,
) -> Response {
    if let Err(refusal) = signed_in(&state, &headers, true) {
        return *refusal;
    }
    let Some(relay) = state.relay.clone() else {
        return refusal(
            StatusCode::SERVICE_UNAVAILABLE,
            "NoRelay",
            "this deployment names no relay; see --relay-hostname",
        );
    };
    if !state.lifecycle.policy().announces_outward {
        return refusal(
            StatusCode::CONFLICT,
            "NotAnnouncing",
            format!(
                "this server is `{}`, a state in which it asks nobody to come look",
                state.lifecycle.state()
            ),
        );
    }
    // `notifyOfUpdate` is deprecated in `requestCrawl`'s favour, and kept
    // because upstream still names it for resuming a relay's subscription
    // after a stream gap.
    let relays: Vec<serde_json::Value> = relay
        .announce(body.resume)
        .await
        .into_iter()
        .map(|(relay, outcome)| match outcome {
            Ok(()) => json!({ "relay": relay, "result": "accepted" }),
            Err(crate::relay::RelayCrawlError::Refused { status, body, .. }) => json!({
                "relay": relay,
                "result": "refused",
                "status": status,
                "body": body,
            }),
            Err(error) => json!({
                "relay": relay,
                "result": "unreachable",
                "error": error.to_string(),
            }),
        })
        .collect();
    Json(json!({ "relays": relays })).into_response()
}

/// What `/dashboard/api/relay/announce` accepts.
#[derive(serde::Deserialize, Default)]
#[serde(default)]
pub struct AnnounceBody {
    /// Call the deprecated `notifyOfUpdate` instead of `requestCrawl`, which
    /// upstream still names for resuming a subscription after a gap.
    resume: bool,
}

// ---------------------------------------------------------------------------
// One account, acted on by the operator
// ---------------------------------------------------------------------------
//
// `didbot_pds::Actor::Operator`, or the operator's DID, is what these hand
// the registry, so what each of them does lands in that account's ledger
// naming the DID this deployment was started with. They are reached the way the stop is reached — the
// dashboard's session, echoed CSRF token — because it is the same question
// of who may tell this server to do something, and `didbot account <verb>`
// carries the same session to the same routes.
//
// The path segment is a DID or a handle, resolved through the same
// `resolve_repo` the `com.atproto.repo.*` routes use, so an operator may
// type the name they already know the account by.

/// What one account route did, as it answers.
///
/// `ledger` is the entry the action wrote in that account's ledger, absent
/// when it wrote none. A recursive delete answers with one of these per
/// account it took, deepest first, and ending an app's logins with one per
/// account a login ended on.
#[derive(Serialize)]
pub(crate) struct Acted {
    /// The account acted on.
    pub(crate) did: String,
    /// The ledger entry the action made.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub(crate) ledger: Option<didbot_pds::LedgerEntry>,
}

/// The account the path segment names, or the refusal to answer with.
fn account_at(state: &AppState, named: &str) -> Result<String, Box<Response>> {
    crate::routes::resolve_repo(state, named).map_err(|error| Box::new(error.into_response()))
}

/// [`Acted`] for `did`, reading the entry the action just wrote.
fn acted(state: &AppState, did: &str) -> Acted {
    Acted {
        did: did.to_owned(),
        ledger: state
            .registry
            .ledger(did)
            .and_then(|ledger| ledger.entries.last().cloned()),
    }
}

/// A registry refusal, as the operator reads it.
fn refused(error: &didbot_pds::ProvisionError) -> Response {
    crate::error::ApiError::from(error).into_response()
}

/// A registry refusal that came after the action had already reached some
/// accounts, with those accounts beside it: a caller that saw only the
/// refusal would not know what had already happened.
pub(crate) fn refused_partway(error: &didbot_pds::ProvisionError, reached: &[Acted]) -> Response {
    let refusal = crate::error::ApiError::from(error);
    (
        refusal.status(),
        Json(json!({
            "error": refusal.error(),
            "message": refusal.message(),
            "accounts": reached,
        })),
    )
        .into_response()
}

/// The envelope every account route answers with: what was asked for, and
/// each account it reached.
fn did_it(action: &str, accounts: Vec<Acted>) -> Response {
    Json(json!({ "action": action, "accounts": accounts })).into_response()
}

/// `POST /dashboard/api/accounts/{did}/lock`
///
/// [`didbot_pds::Lock::Frozen`]: writes refused, the repository still
/// readable. The lock an operator hangs on one account to stop the bleeding.
async fn account_lock(
    State(state): State<AppState>,
    axum::extract::Path(named): axum::extract::Path<String>,
    headers: axum::http::HeaderMap,
) -> Response {
    if let Err(refusal) = signed_in(&state, &headers, true) {
        return *refusal;
    }
    let (did, operator) = match (account_at(&state, &named), acting_operator(&state)) {
        (Ok(did), Ok(operator)) => (did, operator),
        (Err(refusal), _) | (_, Err(refusal)) => return *refusal,
    };
    match state
        .registry
        .lock(&did, Lock::Frozen, Actor::Operator(&operator))
    {
        Ok(()) => did_it("lock", vec![acted(&state, &did)]),
        Err(error) => refused(&error),
    }
}

/// `POST /dashboard/api/accounts/{did}/unlock`
///
/// Lifts this operator's own [`didbot_pds::Lock::Frozen`]. A tag another
/// party hung stays where it is, and the refusal names it.
async fn account_unlock(
    State(state): State<AppState>,
    axum::extract::Path(named): axum::extract::Path<String>,
    headers: axum::http::HeaderMap,
) -> Response {
    if let Err(refusal) = signed_in(&state, &headers, true) {
        return *refusal;
    }
    let (did, operator) = match (account_at(&state, &named), acting_operator(&state)) {
        (Ok(did), Ok(operator)) => (did, operator),
        (Err(refusal), _) | (_, Err(refusal)) => return *refusal,
    };
    match state
        .registry
        .unlock(&did, Lock::Frozen, Actor::Operator(&operator))
    {
        Ok(()) => did_it("unlock", vec![acted(&state, &did)]),
        Err(error) => refused(&error),
    }
}

/// `POST /dashboard/api/accounts/{did}/lift-quarantine`
///
/// The recorded exception `plan/account-lifecycle.md` names: a policy hung
/// the tag and the operator takes it off, with the ledger saying which
/// operator overrode it.
async fn account_lift_quarantine(
    State(state): State<AppState>,
    axum::extract::Path(named): axum::extract::Path<String>,
    headers: axum::http::HeaderMap,
) -> Response {
    if let Err(refusal) = signed_in(&state, &headers, true) {
        return *refusal;
    }
    let (did, operator) = match (account_at(&state, &named), acting_operator(&state)) {
        (Ok(did), Ok(operator)) => (did, operator),
        (Err(refusal), _) | (_, Err(refusal)) => return *refusal,
    };
    match state
        .registry
        .unlock(&did, Lock::Quarantined, Actor::Operator(&operator))
    {
        Ok(()) => did_it("lift-quarantine", vec![acted(&state, &did)]),
        Err(error) => refused(&error),
    }
}

/// `POST /dashboard/api/accounts/{did}/erase`
///
/// The operator's erasure: the repository, its history, its blobs and its
/// credentials go, the name is burned, and the row and the DID document stay
/// so past signatures keep checking. It ignores the locks, so a locked or
/// quarantined account is erased too, and the ledger names the operator.
async fn account_erase(
    State(state): State<AppState>,
    axum::extract::Path(named): axum::extract::Path<String>,
    headers: axum::http::HeaderMap,
) -> Response {
    if let Err(refusal) = signed_in(&state, &headers, true) {
        return *refusal;
    }
    let (did, operator) = match (account_at(&state, &named), acting_operator(&state)) {
        (Ok(did), Ok(operator)) => (did, operator),
        (Err(refusal), _) | (_, Err(refusal)) => return *refusal,
    };
    match state.registry.operator_erase(&did, &operator) {
        Ok(()) => did_it("erase", vec![acted(&state, &did)]),
        Err(error) => refused(&error),
    }
}

/// `POST /dashboard/api/accounts/{did}/delete`
///
/// The hard delete: the row goes too, and the ledger is what is left. An
/// account with children is refused unless the body asks for the subtree,
/// which is taken deepest first — a parent is erased only once nothing
/// beneath it is live, which is the rule
/// `Provisioner::require_no_live_children` enforces underneath.
///
/// The server's own account is refused before anything is taken. Every
/// account the server created hangs beneath it, so walking its subtree
/// would delete them all before the refusal reached the server itself.
///
/// `kind`, `neverWrote` and `idleFor` are conditions on every account it
/// would take; see [`crate::dashboard_accounts::Keeping`]. They are checked
/// for the whole subtree first, where one that fails refuses the delete.
/// They are checked again for each account with its writes held off, so an
/// account that wrote after it was listed stays. `didbot account delete
/// --never-wrote` and the accounts panel's bulk delete send all three.
async fn account_delete(
    State(state): State<AppState>,
    axum::extract::Path(named): axum::extract::Path<String>,
    headers: axum::http::HeaderMap,
    body: Option<Json<DeleteBody>>,
) -> Response {
    if let Err(refusal) = signed_in(&state, &headers, true) {
        return *refusal;
    }
    let (did, operator) = match (account_at(&state, &named), acting_operator(&state)) {
        (Ok(did), Ok(operator)) => (did, operator),
        (Err(refusal), _) | (_, Err(refusal)) => return *refusal,
    };
    if did == state.registry.service_did() {
        tracing::warn!(%did, "hard delete refused: that is the server's own account");
        return refused(&didbot_pds::ProvisionError::ServerAccount {
            did,
            operation: "deletion",
        });
    }
    let body = body.map(|Json(body)| body).unwrap_or_default();
    let keeping = match crate::dashboard_accounts::Keeping::of(
        &state,
        body.kind,
        body.never_wrote,
        body.idle_for.as_deref(),
    ) {
        Ok(keeping) => keeping,
        Err(refusal) => return *refusal,
    };
    let recursive = body.recursive;
    let subtree = match subtree_of(&state, &did) {
        Ok(subtree) => subtree,
        Err(error) => return refused(&error),
    };
    if !recursive && subtree.len() > 1 {
        return refusal(
            StatusCode::CONFLICT,
            "LiveChildren",
            format!(
                "{did} has {} accounts beneath it; pass recursive to take them too",
                subtree.len() - 1
            ),
        );
    }
    for target in &subtree {
        let Some(account) = state.registry.account(target) else {
            continue;
        };
        if let Err(why) = keeping.check(&state, &account) {
            tracing::info!(%did, %target, %why, "hard delete refused: an account is kept");
            return refused(&didbot_pds::ProvisionError::Kept {
                did: target.clone(),
                why,
            });
        }
    }
    let may_go = |account: &didbot_pds::HostedAccount| keeping.check(&state, account);
    let mut taken = Vec::new();
    for target in subtree {
        if let Err(error) = state
            .registry
            .hard_delete_if(&target, &target, &operator, &may_go)
        {
            // Whatever was already taken is gone.
            return refused_partway(&error, &taken);
        }
        taken.push(acted(&state, &target));
    }
    did_it("delete", taken)
}

/// `POST /dashboard/api/accounts/{did}/revoke-tokens`
///
/// Ends every token that authenticates as the account: its account tokens,
/// its app logins and its unredeemed codes. The account keeps its state and
/// its locks, whatever they are. The ledger gains a `tokensRevoked` entry
/// naming the operator, unless nothing was live to end. The answer counts
/// what ended.
async fn account_revoke_tokens(
    State(state): State<AppState>,
    axum::extract::Path(named): axum::extract::Path<String>,
    headers: axum::http::HeaderMap,
) -> Response {
    if let Err(refusal) = signed_in(&state, &headers, true) {
        return *refusal;
    }
    let (did, operator) = match (account_at(&state, &named), acting_operator(&state)) {
        (Ok(did), Ok(operator)) => (did, operator),
        (Err(refusal), _) | (_, Err(refusal)) => return *refusal,
    };
    match state.registry.revoke_tokens(&did, &operator) {
        Ok(revoked) => Json(json!({
            "action": "revoke-tokens",
            "accounts": [Acted {
                did,
                ledger: revoked.entry,
            }],
            "tokens": revoked.tokens,
            "logins": revoked.logins,
        }))
        .into_response(),
        Err(error) => refused(&error),
    }
}

/// `POST /dashboard/api/accounts/{did}/credentials`
///
/// `bot.did.updateCredentials` as the operator, the change `didbot account
/// credentials` makes: the body is that method's, with the account named
/// in the path instead of `did`.
async fn account_credentials(
    State(state): State<AppState>,
    axum::extract::Path(named): axum::extract::Path<String>,
    headers: axum::http::HeaderMap,
    crate::routes::XrpcBody(body): crate::routes::XrpcBody,
) -> Response {
    if let Err(refusal) = signed_in(&state, &headers, true) {
        return *refusal;
    }
    let did = match account_at(&state, &named) {
        Ok(did) => did,
        Err(refusal) => return *refusal,
    };
    crate::tree::update_credentials_from_dashboard(&state, &headers, &did, &body).await
}

/// What `/dashboard/api/accounts/{did}/delete` accepts.
#[derive(serde::Deserialize, Default)]
#[serde(default)]
pub struct DeleteBody {
    /// Take everything beneath the account too.
    recursive: bool,
    /// Refuse unless every account taken is known never to have written,
    /// and is no host or service account unless `kind` names it.
    #[serde(rename = "neverWrote")]
    never_wrote: bool,
    /// Refuse unless every account taken is idle this long, a span such as
    /// `24h`. A `neverWrote` delete has to name it.
    #[serde(rename = "idleFor")]
    idle_for: Option<String>,
    /// Refuse unless every account taken is of this kind.
    kind: Option<didbot_pds::AccountKind>,
}

/// `did` and everything beneath it, deepest first — the order a hard delete
/// has to take them in.
fn subtree_of(state: &AppState, did: &str) -> Result<Vec<String>, didbot_pds::ProvisionError> {
    // Breadth-first down, then reversed: a level is only ever listed after
    // its parent, so reversing puts every child ahead of the account it
    // hangs from.
    let mut order = vec![state.registry.children(did).map(|_| did.to_owned())?];
    let mut next = 0;
    while next < order.len() {
        let children = state.registry.children(&order[next])?;
        order.extend(
            children
                .into_iter()
                .map(|child| child.did.as_str().to_owned()),
        );
        next += 1;
    }
    order.reverse();
    Ok(order)
}