didbot_serve/oauth/

error.rs

//! The error shape OAuth's own endpoints use.
//!
//! `crate::error::ApiError` is atproto XRPC's `{"error","message"}` body.
//! PAR, `authorize` and `token` are not XRPC procedures — they are OAuth 2.1
//! endpoints, and RFC 6749 §5.2 defines their own wire shape:
//! `{"error","error_description"}`, drawn from a fixed vocabulary
//! (`invalid_request`, `invalid_client`, `invalid_grant`, ...). A client
//! library written against the OAuth spec switches on that vocabulary, not on
//! this project's own error names, so reusing [`crate::error::ApiError`] here
//! would answer a spec-defined request with a shape no OAuth client expects.

use axum::http::{HeaderValue, StatusCode};
use axum::response::{IntoResponse, Response};
use axum::Json;
use serde::Serialize;

/// One of the `error` values RFC 6749 and its extensions define, restricted
/// to the ones this server's endpoints actually raise.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OAuthErrorCode {
    /// A required parameter is missing, malformed, or repeated.
    InvalidRequest,
    /// The client is not recognised, or its metadata does not check out.
    InvalidClient,
    /// The authorization code, refresh token, or PAR `request_uri` presented
    /// is unknown, expired, already used, or was issued to a different
    /// client.
    InvalidGrant,
    /// This client is not permitted to use the grant type it asked for.
    UnauthorizedClient,
    /// `grant_type` named something this server does not implement.
    UnsupportedGrantType,
    /// `response_type` named something other than `code`.
    UnsupportedResponseType,
    /// The requested scope is outside what this token may be issued —
    /// including every refusal `plan/scope-policy.md`'s ceiling will
    /// eventually make, and every one it makes today by not existing yet.
    InvalidScope,
    /// The resource owner (or, here, the policy standing in for one) refused
    /// the request. This is the consent seam's own refusal.
    AccessDenied,
    /// Something on this server's side, not the caller's request.
    ServerError,
    /// The DPoP proof is missing or does not check out (RFC 9449 §5).
    InvalidDpopProof,
    /// The DPoP proof carries no nonce this server accepts (RFC 9449 §8).
    /// The answer names the nonce to retry with in `DPoP-Nonce`.
    UseDpopNonce,
}

impl OAuthErrorCode {
    pub(crate) fn as_str(self) -> &'static str {
        match self {
            OAuthErrorCode::InvalidRequest => "invalid_request",
            OAuthErrorCode::InvalidClient => "invalid_client",
            OAuthErrorCode::InvalidGrant => "invalid_grant",
            OAuthErrorCode::UnauthorizedClient => "unauthorized_client",
            OAuthErrorCode::UnsupportedGrantType => "unsupported_grant_type",
            OAuthErrorCode::UnsupportedResponseType => "unsupported_response_type",
            OAuthErrorCode::InvalidScope => "invalid_scope",
            OAuthErrorCode::AccessDenied => "access_denied",
            OAuthErrorCode::ServerError => "server_error",
            OAuthErrorCode::InvalidDpopProof => "invalid_dpop_proof",
            OAuthErrorCode::UseDpopNonce => "use_dpop_nonce",
        }
    }

    /// The HTTP status RFC 6749 pairs with this error, at the token endpoint.
    /// `authorize` and PAR redirect or refuse a subset of these; see each
    /// module's own mapping.
    fn status(self) -> StatusCode {
        match self {
            OAuthErrorCode::InvalidClient => StatusCode::UNAUTHORIZED,
            OAuthErrorCode::AccessDenied => StatusCode::FORBIDDEN,
            OAuthErrorCode::ServerError => StatusCode::INTERNAL_SERVER_ERROR,
            _ => StatusCode::BAD_REQUEST,
        }
    }
}

#[derive(Debug, Clone, Serialize)]
struct OAuthErrorBody {
    error: &'static str,
    #[serde(skip_serializing_if = "Option::is_none")]
    error_description: Option<String>,
}

/// An OAuth-shaped failure: `{"error", "error_description"}`, per RFC 6749.
#[derive(Debug, Clone)]
pub struct OAuthError {
    status: StatusCode,
    body: OAuthErrorBody,
    /// The nonce a `use_dpop_nonce` refusal hands the client in
    /// `DPoP-Nonce`.
    dpop_nonce: Option<String>,
}

impl OAuthError {
    /// Builds a failure from its RFC 6749 error code and a human sentence.
    ///
    /// `description` is never a secret and never the caller's own submitted
    /// content verbatim, for the same reason `ApiError`'s messages are safe to
    /// return: this project puts no credential or key material into a
    /// `Display` impl that a wire error could quote.
    pub fn new(code: OAuthErrorCode, description: impl Into<String>) -> Self {
        Self {
            status: code.status(),
            body: OAuthErrorBody {
                error: code.as_str(),
                error_description: Some(description.into()),
            },
            dpop_nonce: None,
        }
    }

    /// The `429` the unauthenticated OAuth endpoints answer a caller over
    /// its rate with. RFC 6749 has no code for it, so this is
    /// `invalid_request` with a description naming the endpoint.
    pub fn rate_limited(endpoint: &str) -> Self {
        let mut refused = Self::new(
            OAuthErrorCode::InvalidRequest,
            format!("too many {endpoint} requests from this caller; slow down"),
        );
        refused.status = StatusCode::TOO_MANY_REQUESTS;
        refused
    }

    /// The `error` value the client is sent.
    pub(crate) fn error(&self) -> &'static str {
        self.body.error
    }

    /// The `error_description` the client is sent.
    pub(crate) fn description(&self) -> &str {
        self.body.error_description.as_deref().unwrap_or_default()
    }

    /// This refusal, handing the client `nonce` in `DPoP-Nonce` to sign its
    /// retry with (RFC 9449 §8).
    pub fn with_dpop_nonce(mut self, nonce: impl Into<String>) -> Self {
        self.dpop_nonce = Some(nonce.into());
        self
    }
}

impl IntoResponse for OAuthError {
    fn into_response(self) -> Response {
        let mut response = (self.status, Json(self.body)).into_response();
        if let Some(value) = self
            .dpop_nonce
            .and_then(|nonce| HeaderValue::from_str(&nonce).ok())
        {
            response
                .headers_mut()
                .insert(crate::oauth::dpop::DPOP_NONCE, value);
        }
        response
    }
}