didbot_serve/oauth/

mod.rs

//! OAuth 2.0 for atproto (`plan/oauth.md`).
//!
//! Built in slices; see each submodule's own doc for what it covers and what
//! it deliberately does not. [`dpop`] is the RFC 9449 verifier side, and
//! [`scope`] is `didbot-scope`, the granular atproto scope grammar as a typed
//! value with containment and intersection — the substrate a ceiling is
//! expressed over, shared with every other program that computes one.
//!
//! The authorization server itself — pushed authorization requests,
//! `authorize`, `token`, refresh rotation, client metadata — is sibling work
//! landing in sibling files under this module. Each of those endpoints holds a
//! [`dpop::DpopVerifier`] and calls [`dpop::DpopVerifier::verify`] once per
//! request.

pub mod authorize;
pub mod browser;
pub mod client_auth;
pub mod client_metadata;
pub mod consent;
pub mod decision;
pub mod discovery;
pub mod dpop;
pub mod dpop_seam;
pub mod error;
pub mod par;
pub mod permission_set;
pub mod token;

pub use didbot_scope as scope;

use std::sync::Arc;

use time::Duration;

/// Every collaborator the OAuth authorization server routes need, bundled so
/// [`crate::routes::AuthState`] carries one field instead of a dozen.
///
/// [`OAuthState::default`] is what every router this crate builds gets
/// unless a deployment wires its own: in-memory stores, plus the two things
/// that judge a sign-in — [`OAuthState::grant_gate`] and
/// [`OAuthState::scope_policy`] — with no denial loaded. A policy denies and
/// an empty policy set permits everything (`plan/policy.md`), so the default
/// grants every requested scope inside [`authorize::GrantAnyScope`]'s
/// ceiling; [`consent`]'s identity check is what stands between a client and
/// a token once the record says `allow`. Both are read at
/// `POST /oauth/par`, and the gate once more before `POST /oauth/token`
/// issues anything. DPoP verification is the one hook this crate
/// does own end to end (RFC 9449 is not a deployment policy choice the way
/// a scope ceiling is), so [`OAuthState::default`] wires the real
/// [`dpop::DpopVerifier`] rather than [`dpop_seam::RefusingDpopVerifier`] —
/// see `DPOP_SKEW` (this module, private) for the window it is built with.
#[derive(Clone)]
pub struct OAuthState {
    /// Fetches client metadata documents on a deployment that reaches its
    /// own machine (`client_metadata::LoopbackClients::Fetched`). Every other
    /// deployment fetches each one through a client pinned to the addresses
    /// it checked; see `oauth::client_metadata::resolve_client`. Nothing else
    /// in this crate shares it; `crate::relay` and `crate::operator_poll`
    /// each build their own. [`OAuthState::default`] builds it with
    /// [`client_metadata_http_client`]'s bounds, but a deployment may wire
    /// its own, so `resolve_client` applies the per-request bounds it needs
    /// regardless of what arrives here.
    pub http: reqwest::Client,
    /// Where fetched client metadata documents are cached; see
    /// `oauth::client_metadata`.
    pub client_cache: Arc<dyn client_metadata::ClientMetadataCache>,
    /// Where pushed authorization requests live between `par` and
    /// `authorize`; see `oauth::par`.
    pub par_store: Arc<dyn par::ParStore>,
    /// The deployment's scope ceiling, intersected with what a client asks
    /// for at PAR; see `oauth::authorize`.
    pub scope_policy: Arc<dyn authorize::ScopePolicy>,
    /// Where pending consent decisions live; see `oauth::consent`.
    pub consent_store: Arc<dyn consent::ConsentStore>,
    /// Where the decision records PAR mints live; see `oauth::decision`.
    pub decision_store: Arc<dyn decision::DecisionStore>,
    /// The browsers signed in as an account, and the tickets that sign one
    /// in; see `oauth::browser`.
    pub browser_sessions: Arc<browser::BrowserSessions>,
    /// The stop this process serves until, so
    /// `bot.did.listPendingAuthorizations`'s long poll comes back at once
    /// rather than holding a connection open for the rest of its window.
    /// A poll that begins after the stop does not wait at all.
    ///
    /// Only the long poll waits on anything here; every other route answers
    /// and returns. The default never stops; `didbot-pds` passes the stop
    /// its listener closes on.
    pub shutdown: crate::Stopping,
    /// `plan/policy.md`'s gate, asked about a `Subject::Grant` at PAR and a
    /// `Subject::Token` at `POST /oauth/token`. A deployment wires the same
    /// gate its writes are judged by. Denies only, and
    /// [`OAuthState::default`] wires the gate with nothing loaded. A client
    /// this deployment will not admit is denied here, by a `denyClient`
    /// policy, rather than by a check of its own.
    pub grant_gate: Arc<dyn didbot_pds::policy::PolicyGate>,
    /// Where a narrowed or denied grant is written down, payload-free; see
    /// `didbot_pds::evaluation_log`.
    pub evaluation_log: Arc<didbot_pds::evaluation_log::EvaluationLog>,
    /// Where issued authorization codes live between consent confirmation
    /// and exchange; see `oauth::token`.
    pub code_store: Arc<dyn token::AuthorizationCodeStore>,
    /// OAuth access/refresh token issuance and rotation; see
    /// `oauth::token`.
    pub tokens: Arc<token::OAuthTokenStore>,
    /// The DPoP verification seam; see `oauth::dpop_seam`.
    pub dpop: Arc<dyn dpop_seam::DpopVerifier>,
    /// Where a confidential client's assertion is checked at `par` and
    /// `token`, and its `jti` held; see `oauth::client_auth`.
    pub client_assertions: Arc<client_auth::ClientAssertionVerifier>,
    /// Where the permission set an `include:` scope names is resolved at
    /// `par`, and cached for every account; see `oauth::permission_set`.
    pub permission_sets: Arc<permission_set::PermissionSets>,
    /// Rate limits `GET /oauth/authorize`; see `crate::rate_limit`.
    pub authorize_rate_limiter: Arc<crate::rate_limit::RateLimiter>,
    /// Rate limits `POST /oauth/par` per caller address, the same way
    /// [`OAuthState::authorize_rate_limiter`] bounds the step after it.
    ///
    /// PAR is unauthenticated and does more work than `authorize` does: it
    /// fetches a document from a host the *caller* names (see
    /// [`client_metadata_http_client`]), then mints a decision record
    /// addressed to an account the caller names. Both are costs an anonymous
    /// client can spend without proving anything, which is the same argument
    /// `crate::routes::AuthState::provision_rate_limiter` makes for the other
    /// unauthenticated route that does real work.
    pub par_rate_limiter: Arc<crate::rate_limit::RateLimiter>,
    /// Rate limits `POST /oauth/token` per caller address.
    ///
    /// Also unauthenticated until the credential in the body checks out, and
    /// every call costs a DPoP proof verification, an ECDSA check made
    /// before that credential is read. Without this a caller with a fresh
    /// key can spend those checks with proofs naming no token at all.
    pub token_rate_limiter: Arc<crate::rate_limit::RateLimiter>,
}

/// How far a DPoP proof's `iat` may sit from this server's own clock, either
/// direction — and, per [`dpop::DpopVerifier::new`]'s own doc, also how long
/// a `jti` is retained in the replay cache, since the two are the same
/// number for the reason named there. Matches [`token::ACCESS_TTL`]: a proof
/// need only stay fresh for about as long as the token it mints or presents
/// is good for.
const DPOP_SKEW: Duration = Duration::minutes(5);

/// How long a DPoP nonce is handed out before a fresh one replaces it.
///
/// The replaced nonce is accepted for as long again, so one nonce is good
/// for two minutes at most. The atproto profile gives a nonce five.
const DPOP_NONCE_TTL: Duration = Duration::minutes(1);

/// The client `OAuthState::default` fetches client metadata documents with.
///
/// `POST /oauth/par` is unauthenticated, so the host this client talks to is
/// chosen by whoever called it. Two bounds are set here, at the client, as
/// well as per-request in `client_metadata::resolve_client`: a total deadline
/// of [`client_metadata::FETCH_TIMEOUT`], and no redirect followed at all —
/// `reqwest`'s default is to follow up to ten, and a client metadata document
/// that arrives from anywhere but its own `client_id` is not that client's
/// registration (see `client_metadata::ClientMetadataError::Redirected`).
/// Refusing here means the second request is never issued; the check in
/// `resolve_client` is what still holds if a deployment supplies its own
/// client.
///
/// Falls back to a default-configured client if the builder fails — the same
/// fallback `crate::relay::RelayClient::new` makes, for the same reason: a
/// startup path that refuses to construct is worse than a degraded one, and
/// `resolve_client`'s own bounds survive the fallback.
pub fn client_metadata_http_client() -> reqwest::Client {
    didbot_http::builder()
        .timeout(client_metadata::FETCH_TIMEOUT)
        .redirect(reqwest::redirect::Policy::none())
        .build()
        .unwrap_or_else(|error| {
            tracing::warn!(
                %error,
                "building the client metadata HTTP client failed; falling back to                  reqwest's own defaults, which follow redirects and set no deadline —                  `client_metadata::resolve_client`'s own bounds still hold"
            );
            reqwest::Client::default()
        })
}

impl Default for OAuthState {
    fn default() -> Self {
        Self {
            http: client_metadata_http_client(),
            client_cache: Arc::new(client_metadata::MemoryClientMetadataCache::new()),
            par_store: Arc::new(par::MemoryParStore::new()),
            scope_policy: Arc::new(authorize::GrantAnyScope),
            consent_store: Arc::new(consent::MemoryConsentStore::new()),
            decision_store: Arc::new(decision::MemoryDecisionStore::new()),
            browser_sessions: Arc::new(browser::BrowserSessions::default()),
            shutdown: crate::Stopping::never(),
            grant_gate: Arc::new(didbot_pds::policy::NoPolicyGate),
            evaluation_log: Arc::new(didbot_pds::evaluation_log::EvaluationLog::disabled()),
            code_store: Arc::new(token::MemoryAuthorizationCodeStore::new()),
            tokens: Arc::new(token::OAuthTokenStore::new()),
            dpop: Arc::new(dpop::DpopVerifier::new(DPOP_SKEW, DPOP_NONCE_TTL, true)),
            client_assertions: Arc::new(client_auth::ClientAssertionVerifier::new()),
            permission_sets: Arc::new(permission_set::PermissionSets::default()),
            authorize_rate_limiter: Arc::new(crate::rate_limit::RateLimiter::default()),
            par_rate_limiter: Arc::new(crate::rate_limit::RateLimiter::default()),
            token_rate_limiter: Arc::new(crate::rate_limit::RateLimiter::default()),
        }
    }
}