didbot_serve/routes/

accounts.rs

use super::*;

/// `POST /xrpc/bot.did.deleteAccount`
///
/// `Credential::AccountSelf`: a harness client calls this directly to erase an
/// account at the end of a session, carrying that account's own write
/// credential — the self-service case [`auth::require_self`] exists for,
/// and the only case, since this server holds no credential that could
/// authenticate somebody acting on another account. The repository, its
/// blobs and its credentials go and the name is burned; the DID document,
/// its key and the account's row stay, `decommissioned`, so every signature
/// the agent made stays checkable. Refused with 403 `AccountLocked` while
/// any lock hangs and 403 `AccountHeld` under an operator's hold.
pub(crate) async fn delete_account(
    State(state): State<AppState>,
    headers: HeaderMap,
    XrpcBody(body): XrpcBody,
) -> Response {
    // `docs/write-pipeline.md`'s stage 1, ahead of everything else this
    // route does. The stop refuses outstanding work, and an agent acting on
    // its own account with a credential issued before the stop is
    // outstanding work: an operator who has pulled the brake has not
    // consented to a repository being emptied, a name being burned or a
    // freeze being lifted while it is pulled. `bot.did.freezeAccount` is
    // deliberately not gated this way; see its own doc comment.
    if let Err(halted) = state.estop.check_use(EstopRefusal::Operation) {
        return ApiError::from(halted).into_response();
    }

    let request: DidRequest = match parse_body(&body) {
        Ok(request) => request,
        Err(err) => return err.into_response(),
    };
    if let Err(err) = auth::require_self(state.registry.as_ref(), &headers, &request.did) {
        return err.into_response();
    }
    // Off the async worker for the same reason as `create_account`:
    // `delete` takes the write lock and tears the repository down under it.
    let registry = state.registry.clone();
    let did = request.did.clone();
    let outcome = tokio::task::spawn_blocking(move || registry.delete(&did)).await;
    match outcome {
        Ok(Ok(())) => Json(json!({})).into_response(),
        Ok(Err(err)) => ApiError::from(&err).into_response(),
        Err(join_err) => blocking_task_failed("bot.did.deleteAccount", join_err).into_response(),
    }
}

/// `POST /xrpc/bot.did.freezeAccount`
///
/// `Credential::AccountSelf`, the same posture as [`delete_account`]: an agent
/// hangs [`Lock::Frozen`] on itself as [`Actor::Account`], and nothing else
/// hangs a lock over HTTP. The repository stays readable; only writes are
/// refused, with 403 `AccountNotWritable`. Reversible with
/// [`unfreeze_account`], and only by the same party: an operator's own frozen
/// tag is not the account's to lift.
///
/// The one route in this group that the e-stop does **not** gate. Every
/// other one either destroys something or widens what the account may do,
/// and the stop refuses those; freezing can only ever narrow, so refusing
/// it under a stop would leave a caller less able to restrain itself than
/// before the operator pulled the brake. A gate that can only deny is safe
/// to skip for an operation that can only deny.
pub(crate) async fn freeze_account(
    State(state): State<AppState>,
    headers: HeaderMap,
    XrpcBody(body): XrpcBody,
) -> Response {
    let request: DidRequest = match parse_body(&body) {
        Ok(request) => request,
        Err(err) => return err.into_response(),
    };
    if let Err(err) = auth::require_self(state.registry.as_ref(), &headers, &request.did) {
        return err.into_response();
    }
    match state
        .registry
        .lock(&request.did, Lock::Frozen, Actor::Account)
    {
        Ok(()) => Json(json!({})).into_response(),
        Err(err) => ApiError::from(&err).into_response(),
    }
}

/// `POST /xrpc/bot.did.unfreezeAccount`
///
/// Reverses [`freeze_account`]. Refused with 409 `AccountNotLocked` for an
/// account the caller's party has not frozen.
pub(crate) async fn unfreeze_account(
    State(state): State<AppState>,
    headers: HeaderMap,
    XrpcBody(body): XrpcBody,
) -> Response {
    // `docs/write-pipeline.md`'s stage 1, ahead of everything else this
    // route does. The stop refuses outstanding work, and an agent acting on
    // its own account with a credential issued before the stop is
    // outstanding work: an operator who has pulled the brake has not
    // consented to a repository being emptied, a name being burned or a
    // freeze being lifted while it is pulled. `bot.did.freezeAccount` is
    // deliberately not gated this way; see its own doc comment.
    if let Err(halted) = state.estop.check_use(EstopRefusal::Operation) {
        return ApiError::from(halted).into_response();
    }

    let request: DidRequest = match parse_body(&body) {
        Ok(request) => request,
        Err(err) => return err.into_response(),
    };
    if let Err(err) = auth::require_self(state.registry.as_ref(), &headers, &request.did) {
        return err.into_response();
    }
    match state
        .registry
        .unlock(&request.did, Lock::Frozen, Actor::Account)
    {
        Ok(()) => Json(json!({})).into_response(),
        Err(err) => ApiError::from(&err).into_response(),
    }
}

/// `POST /xrpc/bot.did.deactivateAccount`
///
/// `Credential::AccountSelf`: an agent hangs [`Lock::Deactivated`] on itself.
/// Reads and writes are both refused while it hangs — a relay is told
/// `active: false, status: deactivated` — and the document, the key and the
/// repository all stay, so [`activate_account`] puts the account back exactly
/// as it was. Not gated by the e-stop, for the reason [`freeze_account`] is
/// not: it can only narrow.
pub(crate) async fn deactivate_account(
    State(state): State<AppState>,
    headers: HeaderMap,
    XrpcBody(body): XrpcBody,
) -> Response {
    let request: DidRequest = match parse_body(&body) {
        Ok(request) => request,
        Err(err) => return err.into_response(),
    };
    if let Err(err) = auth::require_self(state.registry.as_ref(), &headers, &request.did) {
        return err.into_response();
    }
    match state
        .registry
        .lock(&request.did, Lock::Deactivated, Actor::Account)
    {
        Ok(()) => Json(json!({})).into_response(),
        Err(err) => ApiError::from(&err).into_response(),
    }
}

/// `POST /xrpc/bot.did.activateAccount`
///
/// Reverses [`deactivate_account`]. Widens what the account may do, so the
/// e-stop gates it the way it gates [`unfreeze_account`].
pub(crate) async fn activate_account(
    State(state): State<AppState>,
    headers: HeaderMap,
    XrpcBody(body): XrpcBody,
) -> Response {
    if let Err(halted) = state.estop.check_use(EstopRefusal::Operation) {
        return ApiError::from(halted).into_response();
    }

    let request: DidRequest = match parse_body(&body) {
        Ok(request) => request,
        Err(err) => return err.into_response(),
    };
    if let Err(err) = auth::require_self(state.registry.as_ref(), &headers, &request.did) {
        return err.into_response();
    }
    match state
        .registry
        .unlock(&request.did, Lock::Deactivated, Actor::Account)
    {
        Ok(()) => Json(json!({})).into_response(),
        Err(err) => ApiError::from(&err).into_response(),
    }
}

/// `GET /xrpc/bot.did.listAccounts`
///
/// `Credential::Disclosure`: open by default, this deployment's own roster
/// of agents — see `auth::Disclosure` for why the default is public. Also
/// what vibescrobble.com's index surveys across *arbitrary* personal data
/// servers it does not administer, which is why closing it is this
/// deployment's own call rather than one this crate can make for every
/// deployment.
pub(crate) async fn list_accounts(State(state): State<AppState>) -> Response {
    if let Err(err) = require_lifecycle(&state, |p| p.serves_reads, "bot.did.listAccounts") {
        return err.into_response();
    }
    if let Err(err) =
        auth::require_disclosure(state.disclosure.list_accounts, "bot.did.listAccounts")
    {
        return err.into_response();
    }
    let operator = state.registry.operator_did();
    let accounts: Vec<AccountSummary> = state
        .registry
        .accounts()
        .iter()
        .map(|account| {
            let credentials = state.registry.credentials(account.did.as_str());
            AccountSummary::from_account(account, &operator, &credentials)
        })
        .collect();
    Json(json!({ "accounts": accounts })).into_response()
}

/// Resolves the `repo` parameter, which is an at-identifier.
///
/// A DID or a handle, because that is what every `com.atproto.repo.*` lexicon
/// says the field is. Resolving it here rather than inside the registry means
/// the handle-to-DID step happens once, in the layer that already owns
/// `/.well-known/atproto-did`, and every route below works in DIDs.
///
/// The returned DID is the *stored* one, never the string the caller sent, so
/// an `at://` URI built from it names the repository the same way twice
/// however the caller spelled it.
///
/// A DID goes through [`canonical_did`] first, for the local-only trap
/// leaves behind: a development DID carries a percent-encoded port, a query
/// value is percent-decoded once before a handler sees it, and a person who
/// copied `did:web:kestrel.agents.localhost%3A4211` out of a log and pasted
/// it into a URL would otherwise get a 404 for a repository that is plainly
/// there. The query service performs the same repair, from the same function.
pub(crate) fn resolve_repo(state: &AppState, repo: &str) -> Result<String, ApiError> {
    let did = if repo.starts_with("did:") {
        let canonical = canonical_did(repo);
        state
            .registry
            .account(&canonical)
            .map(|a| a.did.as_str().to_owned())
    } else {
        state
            .registry
            .handle_did(repo)
            .filter(|did| state.registry.account(did).is_some())
    };
    did.ok_or_else(|| ApiError::repo_not_found(repo))
}

/// `GET /xrpc/bot.did.getAccountLedger`
///
/// The bookkeeping for one agent, which is the one read here that deliberately
/// answers about accounts that no longer exist. A 404 means this deployment
/// never minted that DID at all — not that the agent has been deprovisioned,
/// which is an answer with a body.
///
/// `Credential::Disclosure`: open by default, this deployment's own audit
/// trail for one account — see `auth::Disclosure`.
pub(crate) async fn get_account_ledger(
    State(state): State<AppState>,
    query: Result<Query<LedgerQuery>, QueryRejection>,
) -> Response {
    if let Err(err) = require_lifecycle(&state, |p| p.serves_reads, "bot.did.getAccountLedger") {
        return err.into_response();
    }
    if let Err(err) = auth::require_disclosure(
        state.disclosure.get_account_ledger,
        "bot.did.getAccountLedger",
    ) {
        return err.into_response();
    }
    let Query(query) = match query {
        Ok(query) => query,
        Err(rejection) => return ApiError::bad_request(rejection.body_text()).into_response(),
    };
    match state.registry.ledger(&query.did) {
        Some(ledger) => Json(ledger).into_response(),
        None => ApiError::new(
            StatusCode::NOT_FOUND,
            "UnknownAccount",
            format!("this deployment has no bookkeeping for {}", query.did),
        )
        .into_response(),
    }
}

/// `GET /xrpc/bot.did.listAccountLedgers`
///
/// Every agent this deployment has ever provisioned, which is longer than
/// `listAccounts` by exactly the ones it has taken away again.
///
/// `Credential::Disclosure`, the same as [`get_account_ledger`]: open by
/// default, the audit trail for every account this deployment has ever
/// held.
pub(crate) async fn list_ledgers(State(state): State<AppState>) -> Response {
    if let Err(err) = require_lifecycle(&state, |p| p.serves_reads, "bot.did.listAccountLedgers") {
        return err.into_response();
    }
    if let Err(err) = auth::require_disclosure(
        state.disclosure.list_account_ledgers,
        "bot.did.listAccountLedgers",
    ) {
        return err.into_response();
    }
    Json(json!({ "ledgers": state.registry.ledgers() })).into_response()
}