didbot_serve/

dashboard_apps.rs

//! The operations dashboard's per-app view: what each OAuth application
//! holds on this server, and what it did.
//!
//! Part of [`crate::dashboard`] — surface 3 in `docs/web-surfaces.md`,
//! behind the same operator session as every other control there — kept in
//! its own file because it is its own panel group. Three reads, each
//! filterable by `client_id` and by account, and the two logs by how far
//! back:
//!
//! - **Live logins**, from the grant store. Beside each: what it may do
//!   now, and whether policy would issue it a token now. Neither is
//!   stored; both are asked of the ceiling and the gate at the moment the
//!   panel is drawn, so a ceiling narrowed or a policy loaded a second ago
//!   shows here.
//! - **Refusals**, from the evaluation log.
//! - **Writes**, from the write log.
//!
//! The two logs are read through their stores rather than out of the
//! write-ahead log, and a store that cannot list its rows answers
//! unreachable rather than empty: a deployment that keeps no log and one
//! that refused nothing are different facts.
//!
//! Beside the reads there is one control: ending every login an
//! application holds, here or on one account. It is the answer to an
//! application whose keys leaked, and it is not the answer to an
//! application that should not be here — that is a `denyClient` policy,
//! written from surface 2, which stops the same logins working while it
//! stands and lets them work again when it lifts. This ends them for good
//! and says nothing about whether the application may sign in again.

use axum::extract::{Query, State};
use axum::http::StatusCode;
use axum::response::{IntoResponse, Response};
use axum::routing::{get, post};
use axum::{Json, Router};
use didbot_pds::evaluation_log::DenialRow;
use didbot_pds::oauth::Grant;
use didbot_pds::write_log::WriteRow;
use serde::Serialize;
use time::format_description::well_known::Rfc3339;
use time::OffsetDateTime;

use crate::dashboard::{refused_partway, Acted};
use crate::oauth::token::{standing, GateAdmission};
use crate::routes::AppState;
use crate::surface::{acting_operator, refusal, signed_in, PanelState};

/// Builds the per-app routes, merged into the dashboard's own router.
pub fn routes() -> Router<AppState> {
    Router::new()
        .route("/dashboard/api/apps/logins", get(logins))
        .route("/dashboard/api/apps/refusals", get(refusals))
        .route("/dashboard/api/apps/writes", get(writes))
        .route("/dashboard/api/apps/end-logins", post(end_logins))
}

/// What every route here narrows on. Both empty lists everything.
#[derive(Debug, Clone, Default, serde::Deserialize)]
#[serde(default)]
pub struct AppFilter {
    /// One application, by the `client_id` the rows spell.
    client: Option<String>,
    /// One account, by its handle or its `did:`.
    account: Option<String>,
    /// Only log rows from this long ago or later, as a span such as `7d`. A
    /// live login carries no time to narrow on, so the logins read ignores
    /// it.
    since: Option<String>,
}

impl AppFilter {
    /// Whether a row naming `client` and `account` passes. A row with no
    /// client is the account writing with its own credential, which no
    /// client filter matches.
    fn admits(&self, client: Option<&str>, account: &str, resolved: Option<&str>) -> bool {
        if let Some(wanted) = &self.client {
            if client != Some(wanted.as_str()) {
                return false;
            }
        }
        match resolved {
            Some(wanted) => wanted == account,
            None => true,
        }
    }

    /// The moment `since` names, or the refusal to answer with.
    fn since(&self) -> Result<Option<OffsetDateTime>, Box<Response>> {
        self.since
            .as_deref()
            .map(|span| crate::dashboard_accounts::span_before_now("since", span))
            .transpose()
    }

    /// The account this filter names, as the rows spell it: its DID when
    /// this deployment holds it, and otherwise what the operator typed —
    /// so a row naming an account that has since gone is still findable.
    fn account(&self, state: &AppState) -> Option<String> {
        let named = self.account.as_deref()?;
        Some(crate::routes::resolve_repo(state, named).unwrap_or_else(|_| named.to_owned()))
    }
}

/// One live login, as the panel lists it.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct LoginView {
    /// The grant family: the chain of pairs one approval has rotated into.
    family: u64,
    /// The account the login authenticates as.
    account: String,
    /// The application it was issued to.
    client_id: String,
    /// The scope the account approved.
    approved_scope: String,
    /// What the login may do now, under the ceiling in force.
    scope_in_force: String,
    /// Whether policy would issue this client a token for this account now.
    admitted: bool,
    /// The RFC 7638 thumbprint both tokens are bound to.
    dpop_thumbprint: String,
    /// When the current access token stops working.
    access_expires_at: String,
    /// When the login itself stops working.
    refresh_expires_at: String,
}

impl LoginView {
    fn of(grant: Grant, standing: crate::oauth::token::Standing) -> Self {
        Self {
            family: grant.family,
            account: grant.did,
            client_id: grant.client_id,
            approved_scope: grant.scope,
            scope_in_force: standing.in_force.to_string(),
            admitted: standing.admitted,
            dpop_thumbprint: grant.dpop_thumbprint,
            access_expires_at: grant.access_expires_at.format(&Rfc3339).unwrap_or_default(),
            refresh_expires_at: grant
                .refresh_expires_at
                .format(&Rfc3339)
                .unwrap_or_default(),
        }
    }
}

/// `GET /dashboard/api/apps/logins`
///
/// Every live grant family, newest expiry last. What each may do now and
/// whether policy still admits it are computed here rather than read: see
/// [`crate::oauth::token::standing`].
async fn logins(
    State(state): State<AppState>,
    headers: axum::http::HeaderMap,
    Query(filter): Query<AppFilter>,
) -> Response {
    if let Err(refusal) = signed_in(&state, &headers, false) {
        return *refusal;
    }
    let account = filter.account(&state);
    let pds_did = crate::routes::deployment_did(&state);
    let pds_hostname = state.registry.zone().to_owned();
    let admission = GateAdmission {
        gate: state.oauth.grant_gate.as_ref(),
        registry: state.registry.as_ref(),
        pds_did: &pds_did,
        pds_hostname: &pds_hostname,
    };
    let ceiling = state.oauth.scope_policy.as_ref();
    let mut rows: Vec<LoginView> = state
        .oauth
        .tokens
        .live()
        .into_iter()
        .filter(|grant| filter.admits(Some(&grant.client_id), &grant.did, account.as_deref()))
        .map(|grant| {
            let standing = standing(&grant, ceiling, &admission);
            LoginView::of(grant, standing)
        })
        .collect();
    rows.sort_by(|left, right| {
        (&left.client_id, &left.account, left.family).cmp(&(
            &right.client_id,
            &right.account,
            right.family,
        ))
    });
    Json(PanelState::Live { data: rows }).into_response()
}

/// `GET /dashboard/api/apps/refusals`
///
/// The evaluation log's own rows: policy denials at sign-in, at token
/// issue and at the write, scope refusals of writes outside a token's
/// scope, and ceiling narrowings at the pushed request.
async fn refusals(
    State(state): State<AppState>,
    headers: axum::http::HeaderMap,
    Query(filter): Query<AppFilter>,
) -> Response {
    if let Err(refusal) = signed_in(&state, &headers, false) {
        return *refusal;
    }
    let Some(rows) = state.oauth.evaluation_log.rows() else {
        return Json(PanelState::<Vec<DenialRow>>::Unreachable {
            reason: "this deployment's evaluation log cannot be listed, so what it refused \
                     is not readable here"
                .to_owned(),
        })
        .into_response();
    };
    let since = match filter.since() {
        Ok(since) => since,
        Err(refused) => return *refused,
    };
    let account = filter.account(&state);
    let rows: Vec<DenialRow> = rows
        .into_iter()
        .filter(|row| filter.admits(row.client_id.as_deref(), &row.account, account.as_deref()))
        .filter(|row| since.is_none_or(|since| row.closed_at >= since))
        .collect();
    Json(PanelState::Live { data: rows }).into_response()
}

/// `GET /dashboard/api/apps/writes`
///
/// Every record a caller wrote or deleted, with the commit revision, the
/// key, what the write did, the record's CID and the operator policy
/// digest that admitted it.
async fn writes(
    State(state): State<AppState>,
    headers: axum::http::HeaderMap,
    Query(filter): Query<AppFilter>,
) -> Response {
    if let Err(refusal) = signed_in(&state, &headers, false) {
        return *refusal;
    }
    let Some(rows) = state.registry.write_rows() else {
        return Json(PanelState::<Vec<WriteRow>>::Unreachable {
            reason: "this deployment's write log cannot be listed, so what an app wrote is \
                     not readable here"
                .to_owned(),
        })
        .into_response();
    };
    let since = match filter.since() {
        Ok(since) => since,
        Err(refused) => return *refused,
    };
    let account = filter.account(&state);
    let rows: Vec<WriteRow> = rows
        .into_iter()
        .filter(|row| filter.admits(row.client_id.as_deref(), &row.account, account.as_deref()))
        .filter(|row| since.is_none_or(|since| row.at >= since))
        .collect();
    Json(PanelState::Live { data: rows }).into_response()
}

/// What `POST /dashboard/api/apps/end-logins` takes.
#[derive(Debug, serde::Deserialize)]
pub struct EndLoginsBody {
    /// The application, by `client_id`.
    client: String,
    /// One account, by handle or `did:`. Absent ends the application's
    /// logins on every account this deployment holds.
    #[serde(default)]
    account: Option<String>,
}

/// `POST /dashboard/api/apps/end-logins`
///
/// Ends every grant family the client holds, and drops its unredeemed
/// authorization codes and pending consents so nothing in flight becomes a
/// token afterwards. The accounts' remembered approvals of the client are
/// forgotten too, so its next sign-in is asked. A durable grant store writes the ending down before
/// this answers. When it cannot, the logins still end in this process, and
/// the answer is an error saying a restart may bring them back.
///
/// Each account a login ended on gains one `loginsEnded` entry naming the
/// operator and the application, in DID order, and the answer lists them.
/// An ending that reached no account writes no entry.
///
/// The account is the one the path's `account` names, resolved the way the
/// `com.atproto.repo.*` routes resolve a repository, so an operator may
/// type the handle they already know it by. An account this deployment
/// does not hold is refused rather than quietly matching nothing.
async fn end_logins(
    State(state): State<AppState>,
    headers: axum::http::HeaderMap,
    Json(body): Json<EndLoginsBody>,
) -> Response {
    if let Err(refused) = signed_in(&state, &headers, true) {
        return *refused;
    }
    let operator = match acting_operator(&state) {
        Ok(operator) => operator,
        Err(refused) => return *refused,
    };
    if body.client.trim().is_empty() {
        return refusal(
            StatusCode::BAD_REQUEST,
            "NoClient",
            "name the application whose logins to end, by its client_id",
        );
    }
    let account = match body.account.as_deref() {
        None => None,
        Some(named) => match crate::routes::resolve_repo(&state, named) {
            Ok(did) => Some(did),
            Err(error) => return error.into_response(),
        },
    };
    let ended = state
        .oauth
        .tokens
        .revoke_client(&body.client, account.as_deref());
    let codes = state
        .oauth
        .code_store
        .revoke_client(&body.client, account.as_deref());
    let consents = state
        .oauth
        .consent_store
        .revoke_client(&body.client, account.as_deref());
    let remembered = state
        .oauth
        .decision_store
        .forget_client(&body.client, account.as_deref());
    let ended = match ended {
        Ok(ended) => ended,
        Err(unkept) => {
            tracing::error!(
                operator,
                client = body.client,
                account = account.as_deref().unwrap_or("every account"),
                codes,
                consents,
                remembered,
                error = %unkept.reason,
                "an operator ended an application's logins, and pds.grants could not be written"
            );
            return refusal(
                StatusCode::INTERNAL_SERVER_ERROR,
                "GrantStoreFailed",
                format!(
                    "the logins ended, and pds.grants could not be written: {}. They may \
                     return after a restart.",
                    unkept.reason
                ),
            );
        }
    };
    let reached: std::collections::BTreeSet<&str> =
        ended.iter().map(|login| login.did.as_str()).collect();
    let mut accounts = Vec::with_capacity(reached.len());
    for did in reached {
        match state
            .registry
            .record_logins_ended(did, &body.client, &operator)
        {
            Ok(entry) => accounts.push(Acted {
                did: did.to_owned(),
                ledger: Some(entry),
            }),
            Err(error) => {
                tracing::error!(
                    operator,
                    client = body.client,
                    did,
                    %error,
                    "an operator ended an application's logins, and the account's ledger could \
                     not record it"
                );
                return refused_partway(&error, &accounts);
            }
        }
    }
    tracing::info!(
        operator,
        client = body.client,
        account = account.as_deref().unwrap_or("every account"),
        families = ended.len(),
        accounts = accounts.len(),
        codes,
        consents,
        remembered,
        "an operator ended an application's logins"
    );
    Json(serde_json::json!({
        "action": "end-logins",
        "client": body.client,
        "account": account,
        "operator": operator,
        "families": ended.len(),
        "codes": codes,
        "consents": consents,
        "accounts": accounts,
    }))
    .into_response()
}