didbot_serve/tree/

credentials.rs

//! `bot.did.updateCredentials`: what logs in as an account, changed after
//! it is created.
//!
//! Two callers. The account replaces the key that signed the request with
//! one new key, which signs `addProof`. The operator adds a credential,
//! removes one, or both, on any account but the server's own. Either way
//! the change is one commit, made by `Registry::update_credentials`.

use axum::extract::State;
use axum::http::{header, HeaderMap, StatusCode};
use axum::response::{IntoResponse, Response};
use axum::Json;
use didbot_pds::{ChangedBy, Credential, CredentialChange, EstopRefusal};
use serde::Deserialize;
use serde_json::{json, Value};
use time::OffsetDateTime;
use tracing::info;

use crate::error::ApiError;
use crate::rate_limit::{caller_key, Peer};
use crate::routes::{blocking_task_failed, AppState, XrpcBody};

use super::proof::{account_keys, decode_jwt, split_jwt, verify_key_jwt};

/// The method, as a key proof's `lxm` names it.
const METHOD: &str = "bot.did.updateCredentials";

/// Body of `bot.did.updateCredentials`.
#[derive(Debug, Deserialize)]
struct UpdateCredentialsRequest {
    did: String,
    #[serde(flatten)]
    change: ChangeRequest,
}

/// The change a body asks for. The dashboard's route names the account in
/// its path, so its body is this alone.
#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
struct ChangeRequest {
    #[serde(default)]
    add: Option<Value>,
    #[serde(default)]
    add_proof: Option<String>,
    #[serde(default)]
    parked_key: Option<String>,
    #[serde(default)]
    remove: Option<String>,
}

/// `POST /xrpc/bot.did.updateCredentials`
///
/// An operator session cookie makes the caller the operator. Otherwise the
/// bearer is the account's own JWT, and the account's change passes the
/// gates a new session passes: the e-stop's issuance gate, readiness, and
/// the per-address budget `createAccount` and `createSession` share. The
/// operator's change passes none of them, so a leaked key is replaced
/// while the server is stopped.
pub(crate) async fn update_credentials(
    State(state): State<AppState>,
    peer: Peer,
    headers: HeaderMap,
    XrpcBody(body): XrpcBody,
) -> Response {
    match update_credentials_inner(&state, peer, &headers, &body).await {
        Ok(response) => response,
        Err(error) => error.into_response(),
    }
}

async fn update_credentials_inner(
    state: &AppState,
    peer: Peer,
    headers: &HeaderMap,
    body: &axum::body::Bytes,
) -> Result<Response, ApiError> {
    let by_operator = crate::surface::session_cookie(headers).is_some();
    if !by_operator {
        state.estop.check_issue(EstopRefusal::Token)?;
        crate::routes::require_lifecycle(state, |p| p.provisions_accounts, METHOD)?;
        let key = caller_key(headers, peer.0, state.trust_forwarded_headers);
        if !state.provision_rate_limiter.check(&key) {
            info!(caller = %key, "credential change refused: too many attempts from this address");
            return Err(ApiError::rate_limited(
                "too many createAccount, createSession and updateCredentials calls; slow down",
            ));
        }
    }

    let request: UpdateCredentialsRequest = crate::routes::parse_body(body)?;
    change_credentials(state, headers, by_operator, &request.did, &request.change).await
}

/// `POST /dashboard/api/accounts/{did}/credentials`: the operator's change,
/// at a path the dashboard's session cookie reaches. That cookie is scoped
/// to `/dashboard`, so a browser never carries it to `/xrpc`.
pub(crate) async fn update_credentials_from_dashboard(
    state: &AppState,
    headers: &HeaderMap,
    did: &str,
    body: &axum::body::Bytes,
) -> Response {
    let changed = match crate::routes::parse_body::<ChangeRequest>(body) {
        Ok(request) => change_credentials(state, headers, true, did, &request).await,
        Err(error) => Err(error),
    };
    changed.unwrap_or_else(IntoResponse::into_response)
}

/// The change `request` asks of `did`, by the operator when `by_operator`.
async fn change_credentials(
    state: &AppState,
    headers: &HeaderMap,
    by_operator: bool,
    did: &str,
    request: &ChangeRequest,
) -> Result<Response, ApiError> {
    let add = parse_add(request)?;
    if let Some(Credential::PublicKey {
        public_key_multibase,
    }) = &add
    {
        didbot_pds::account_key_curve(public_key_multibase).map_err(|error| {
            ApiError::new(
                StatusCode::BAD_REQUEST,
                "InvalidKey",
                format!("add: {error}"),
            )
        })?;
    }
    if did == state.registry.service_did() {
        return Err(ApiError::new(
            StatusCode::FORBIDDEN,
            "ServerAccount",
            format!("{did} is this server's own account, and its credentials do not change"),
        ));
    }
    let Some(account) = state.registry.account(did) else {
        return Err(ApiError::repo_not_found(did));
    };
    let now = OffsetDateTime::now_utc();

    let operator = if by_operator {
        if let Err(refusal) = crate::surface::signed_in(state, headers, true) {
            info!("credential change refused: no live operator session");
            return Ok(*refusal);
        }
        Some(state.registry.operator_did())
    } else {
        let signed_by = prove_account(state, headers, did, now)?;
        require_replace(state, did, request, add.as_ref(), &signed_by)?;
        None
    };

    // The new key signed for this account, this server and this method:
    // required of the account, checked for the operator when given.
    if let (
        Some(Credential::PublicKey {
            public_key_multibase,
        }),
        Some(proof),
    ) = (&add, request.add_proof.as_deref())
    {
        check_add_proof(state, did, public_key_multibase, proof, now)?;
    } else if operator.is_none() {
        return Err(add_proof_invalid("`addProof` is missing"));
    }

    let add = match (&operator, request.parked_key.as_deref()) {
        (Some(_), Some(fingerprint)) => Some(take_parked(state, &account, fingerprint, now)?),
        _ => add,
    };

    let change = CredentialChange {
        add,
        remove: request.remove.clone(),
        by: match &operator {
            Some(operator) => ChangedBy::Operator(operator),
            None => ChangedBy::Account,
        },
    };
    let registry = state.registry.clone();
    let owned_did = did.to_owned();
    let owned_change = OwnedChange::from(&change);
    let outcome = tokio::task::spawn_blocking(move || {
        registry.update_credentials(&owned_did, owned_change.borrow())
    })
    .await;
    let changed = match outcome {
        Ok(Ok(changed)) => changed,
        Ok(Err(error)) => {
            info!(did, %error, "credential change refused");
            return Err(ApiError::from(&error));
        }
        Err(join) => return Ok(blocking_task_failed(METHOD, join).into_response()),
    };
    let collection = didbot_lexicon::nsid::CREDENTIAL;
    let mut answer = json!({
        "did": did,
        "commit": { "cid": changed.commit, "rev": changed.rev },
    });
    if let Some(added) = &changed.added {
        answer["added"] = json!({
            "uri": format!("at://{did}/{collection}/{}", added.rkey),
            "cid": added.cid.to_string(),
        });
    }
    if let Some(removed) = &changed.removed {
        answer["removed"] = json!(format!("at://{did}/{collection}/{removed}"));
    }
    Ok(Json(answer).into_response())
}

/// The request's `add`, `parkedKey` and `remove`, checked for shape.
fn parse_add(request: &ChangeRequest) -> Result<Option<Credential>, ApiError> {
    if request.add.is_none() && request.parked_key.is_none() && request.remove.is_none() {
        return Err(ApiError::bad_request(
            "name a credential to add, a parked key, a record to remove, or two of those",
        ));
    }
    if request.add.is_some() && request.parked_key.is_some() {
        return Err(ApiError::bad_request(
            "name one of `add` and `parkedKey`, not both",
        ));
    }
    if let Some(remove) = request.remove.as_deref() {
        didbot_schema::tid::validate(remove)
            .map_err(|error| ApiError::bad_request(format!("remove: {error}")))?;
    }
    let Some(add) = &request.add else {
        return Ok(None);
    };
    let credential = Credential::from_json(add)
        .ok_or_else(|| ApiError::bad_request("add: not a credential kind this server knows"))?;
    if let Credential::OidcIdentity(identity) = &credential {
        if let Some(claim) = identity.repeated_claim() {
            return Err(ApiError::bad_request(format!(
                "add: the identity names the claim {} more than once; name each claim once",
                claim.name
            )));
        }
    }
    Ok(Some(credential))
}

/// The account's own JWT: a key proof whose `iss` is `did`, for this
/// server and this method, spent here. Answers the key that signed it.
///
/// A session and an ID token are refused before anything is fetched: a
/// new key is a way to take sessions, and only a key the account holds
/// may ask for one.
fn prove_account(
    state: &AppState,
    headers: &HeaderMap,
    did: &str,
    now: OffsetDateTime,
) -> Result<String, ApiError> {
    let token = crate::auth::bearer(headers)?;
    let key_proof_required = || {
        ApiError::new(
            StatusCode::UNAUTHORIZED,
            "KeyProofRequired",
            "an account changes its credentials with a JWT one of its keys signed, not a \
             session or an OpenID Connect token",
        )
        .with_header(header::WWW_AUTHENTICATE, "Bearer")
    };
    if !matches!(
        state.registry.verify_agent_token(&token),
        Err(didbot_pds::TokenError::Unknown)
    ) || split_jwt(&token).is_none()
    {
        return Err(key_proof_required());
    }
    let (_, claims) = decode_jwt(&token)?;
    let iss = claims
        .get("iss")
        .and_then(Value::as_str)
        .filter(|iss| iss.starts_with("did:"))
        .ok_or_else(key_proof_required)?;
    if iss != did {
        return Err(ApiError::repo_mismatch(iss, did));
    }
    let keys = account_keys(state, did);
    let proof = verify_key_jwt(state, &token, did, METHOD, &keys, now)?;
    let signed_by = proof.key.to_owned();
    proof.spend(state, now)?;
    Ok(signed_by)
}

/// Refuses an account's change that is not one key replacing the key that
/// signed the request.
fn require_replace(
    state: &AppState,
    did: &str,
    request: &ChangeRequest,
    add: Option<&Credential>,
    signed_by: &str,
) -> Result<(), ApiError> {
    let signing_record = state
        .registry
        .credential_records(did)
        .into_iter()
        .find(|(_, credential)| credential.public_key_multibase() == Some(signed_by))
        .map(|(rkey, _)| rkey);
    let replaces = request.parked_key.is_none()
        && matches!(add, Some(Credential::PublicKey { .. }))
        && request.remove.is_some()
        && request.remove == signing_record;
    if replaces {
        return Ok(());
    }
    Err(ApiError::new(
        StatusCode::FORBIDDEN,
        "ReplaceOnly",
        "an account replaces the key that signed the request with one new key: `add` a key, \
         and `remove` the record of the key that signed",
    ))
}

fn add_proof_invalid(why: impl std::fmt::Display) -> ApiError {
    ApiError::new(
        StatusCode::BAD_REQUEST,
        "AddProofInvalid",
        format!("addProof: {why}"),
    )
}

/// `addProof`: a JWT the added key signed as the account, for this server
/// and this method, spent here.
fn check_add_proof(
    state: &AppState,
    did: &str,
    key: &str,
    proof: &str,
    now: OffsetDateTime,
) -> Result<(), ApiError> {
    let keys = [key.to_owned()];
    let checked = verify_key_jwt(state, proof, did, METHOD, &keys, now)
        .map_err(|error| add_proof_invalid(error.message()))?;
    checked.spend(state, now).map_err(|error| {
        if error.error() == "InvalidToken" {
            add_proof_invalid(error.message())
        } else {
            error
        }
    })
}

/// The key parked under the account's hostname with `fingerprint`, taken,
/// for the account's kind.
fn take_parked(
    state: &AppState,
    account: &didbot_pds::HostedAccount,
    fingerprint: &str,
    now: OffsetDateTime,
) -> Result<Credential, ApiError> {
    let name = account.did.did().authority();
    let parked = state
        .tree
        .parked
        .take(&name, fingerprint, now)
        .ok_or_else(|| {
            ApiError::new(
                StatusCode::NOT_FOUND,
                "ParkedKeyNotFound",
                format!("no key with fingerprint {fingerprint} is parked for {name:?}"),
            )
        })?;
    if parked.kind != account.kind {
        return Err(ApiError::new(
            StatusCode::BAD_REQUEST,
            "ParkedKeyKindMismatch",
            format!(
                "the key was parked for {}, and {} is {}",
                parked.kind.with_article(),
                account.did.as_str(),
                account.kind.with_article()
            ),
        ));
    }
    Ok(Credential::key(&parked.key))
}

/// A [`CredentialChange`] that can cross into a blocking task.
struct OwnedChange {
    add: Option<Credential>,
    remove: Option<String>,
    operator: Option<String>,
}

impl From<&CredentialChange<'_>> for OwnedChange {
    fn from(change: &CredentialChange<'_>) -> Self {
        Self {
            add: change.add.clone(),
            remove: change.remove.clone(),
            operator: match change.by {
                ChangedBy::Operator(operator) => Some(operator.to_owned()),
                ChangedBy::Account => None,
            },
        }
    }
}

impl OwnedChange {
    fn borrow(&self) -> CredentialChange<'_> {
        CredentialChange {
            add: self.add.clone(),
            remove: self.remove.clone(),
            by: match &self.operator {
                Some(operator) => ChangedBy::Operator(operator),
                None => ChangedBy::Account,
            },
        }
    }
}