didbot_serve/

auth.rs

//! The credential taxonomy: what this server accepts, and what each route
//! requires. See `plan/auth-types.md`.
//!
//! Nothing here is a policy engine — that is deliberately `plan/write-policy.md`
//! and `plan/policy-store.md`, not this. This is a small, explicit table:
//! each route names one [`Credential`] it accepts, and one function per kind
//! resolves a request's `Authorization` header against it. A route cannot be
//! missing from [`ROUTE_CREDENTIALS`], because the table and the router are
//! the same list — `routes.rs`'s `xrpc_methods!` macro builds both out of
//! entries that do not parse without a credential. This module's job is to
//! say what the kinds mean; `routes.rs` says which route takes which.
//!
//! [`Credential`]'s variants are the set. There is no list of them anywhere
//! else, and a second copy is a copy that will drift, so do not make one.
//!
//! # The kinds this server accepts
//!
//! - [`Credential::Public`] — no principal needed, and never toggleable: see
//!   "Why every public route is public" below for the three separate reasons
//!   a route ends up in this table with this credential, only one of which
//!   [`Credential::Disclosure`] now replaces.
//! - [`Credential::AccountToken`] — `com.atproto.repo.*`'s write routes,
//!   `uploadBlob`, `getServiceAuth` and `getSession`. Minted once, at
//!   provisioning, bound to one DID; see `didbot_pds::credential`. Not a legacy session and not
//!   OAuth: an agent has no person to paste an app password in and no
//!   authorization server to redirect through, so this is the smallest
//!   credential that lets a provisioning client write as the account it
//!   just provisioned. The authenticated DID must equal the repository a
//!   write names — see [`crate::error::ApiError::repo_mismatch`] — so a
//!   token from one account can never write another's repository.
//! - [`Credential::Creator`] — `createAccount` alone. The bearer credential
//!   names the account creating, in one of three shapes `crate::tree::prove`
//!   resolves: a session this server issued, a JWT signed by a key the
//!   creator's credential records name, or an OpenID Connect token the
//!   creator's `#oidc` entry describes. The deployment's operator, who holds
//!   no account here, presents the operator session instead; see below.
//!   The one deployment that creates with no credential is the `.localhost`
//!   development stack, by [`crate::AuthState::unauthenticated_creates`],
//!   and it creates beneath the deployment's own account.
//! - [`Credential::Proof`] — `createSession` alone: the two shapes above
//!   that are not a session, naming a hosted account.
//! - [`Credential::KeyProofOrOperator`] — `updateCredentials` alone: a JWT
//!   one of the account's keys signed, or the operator session. See
//!   `crate::tree::update_credentials`.
//! - [`Credential::Disclosure`] — `listAccounts`, `listAccountLedgers`,
//!   `getAccountLedger` and `stats`: disclosure, public by default and
//!   narrowable per route by this deployment's configuration, resolved by
//!   [`require_disclosure`]. See [`Disclosure`] for the reasoning this
//!   default rests on and the shape the toggle takes.
//!
//! # There is no operator credential
//!
//! No scheme here authenticates "the operator". A server learns which DID
//! operates it from the `bot.did.operator` record in the operator's *own*
//! repository, which this server only ever reads — see `plan/handshake.md`
//! and `crate::operator_poll`. That is the whole point of the handshake:
//! no operator credential is ever held by, presented to, or comparable by a
//! PDS, so there is nothing here for one to be stolen from.
//!
//! Two consequences this table makes concrete rather than leaving implied:
//!
//! - Every account-lifecycle mutation this server serves is *self-service*
//!   — [`require_self`], an agent token naming the account the request
//!   names. Acting on somebody else's account over HTTP has no credential
//!   here and therefore no route.
//! - A [`Credential::Disclosure`] route that this deployment has closed is
//!   closed to everyone. There is no credential that still reaches past the
//!   toggle, so `false` means refused, full stop.
//!
//! A human proves control of that DID to this server by signing in over
//! atproto OAuth — [`crate::operator`], which mints a dashboard session and
//! keeps no credential belonging to the operator. That session is not a
//! [`Credential`]: it reaches the dashboard, and `createAccount` for an
//! account the operator's record names.
//!
//! `DPoP` names the OAuth access tokens every [`Credential::AccountToken`]
//! route and every `atproto-proxy` call accept, through
//! [`require_agent_token_or_dpop`], which reads the scheme off the headers
//! itself. Every route resolved through [`present`] folds `DPoP` into
//! [`Presented::Disabled`], as it does `ServiceAuth`; see
//! [`DISABLED_SCHEMES`].
//!
//! # Why every public route is public
//!
//! `plan/auth-types.md` asks for this to be a decision this epic writes
//! down, not an accident, and it is one of four separate decisions rather
//! than one:
//!
//! - **Public because the protocol requires it.** Every `com.atproto.sync.*`
//!   route and the read half of `com.atproto.repo.*` — `getRecord`,
//!   `listRecords`, `describeRepo` — are what a relay crawls and an appview
//!   indexes. A credential here means no relay indexes these agents and
//!   nothing they write ever reaches Bluesky, which contradicts what this
//!   project says it does. This server exists to be read the way a public
//!   git remote or a public atproto PDS is, and nothing here narrows it:
//!   whether this deployment federates at all is the operator's decision, made
//!   and recorded as `Credential::Public` on purpose — `plan/spaces.md`
//!   names "private means federation off" as the alternative posture a
//!   future deployment may choose, which is exactly why this is written as a
//!   decision rather than left looking like nobody got to it.
//! - **Public because it must be, structurally.** `/.well-known/did.json`
//!   and `/.well-known/atproto-did` resolve a DID for anyone, which is what
//!   a DID is; a credential there and the identity premise this whole
//!   project rests on collapses. `com.atproto.identity.resolveHandle` is
//!   the same resolution, asked of this server by a client that cannot do
//!   DNS.
//! - **Public by default, on purpose, and narrowable.**
//!   [`Credential::Disclosure`] — see [`Disclosure`] — which is what
//!   `bot.did.listAccounts`, `listAccountLedgers`, `getAccountLedger` and `stats`
//!   now are. This is the tier finding 02 actually found: not "public
//!   because a relay needs it" and not "public because the alternative is
//!   incoherent", but public because nobody had written the reasoning down
//!   — and once it is written down, per-route configuration turns out to be
//!   the right shape, not a hole to close.
//! - **Public because it confers nothing, and the bound is elsewhere.**
//!   `bot.did.pollOperatorClaim` alone. It asks this server to read the
//!   operator's repository sooner than its timer would, and that is its
//!   whole effect — it cannot assert a claim, only ask the server to go and
//!   look for one. A credential would be protecting a capability that does
//!   not exist. What keeps an anonymous caller from turning it into a way to
//!   make this server work is the floor between two polls, which bounds the
//!   *outbound* rate rather than the inbound one; see
//!   `crate::operator_poll::MIN_POLL_INTERVAL`.

use axum::http::{header, HeaderMap, HeaderName, StatusCode};
use didbot_pds::{Registry, TokenError};

use crate::error::ApiError;
use crate::oauth::scope::{Action, NsidPattern, Scope, ScopeSet};

/// Compares two secrets in time that does not depend on where they first
/// differ.
///
/// `subtle`, not a hand-rolled fold: a comparison the optimiser is free to
/// turn back into an early return is a comparison that leaks how much of a
/// secret a caller guessed right.
pub(crate) fn constant_time_eq(a: &[u8], b: &[u8]) -> bool {
    use subtle::ConstantTimeEq;
    a.len() == b.len() && bool::from(a.ct_eq(b))
}

/// A credential kind a route may declare it accepts.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Credential {
    /// No principal required. A deliberate decision, not an absence of one.
    Public,
    /// `didbot_pds::credential`'s bearer token, minted at provisioning, or a
    /// DPoP-bound OAuth access token; see `require_agent_token_or_dpop`.
    AccountToken,
    /// An agent's own [`Credential::AccountToken`], resolved to the account it
    /// authenticates as rather than to a repository path.
    ///
    /// Two postures, and which one a route takes depends on whether the
    /// request names an account at all.
    ///
    /// **Checked against the account the request names.** Every
    /// account-lifecycle mutation: `activateAccount`, `deactivateAccount`,
    /// `deleteAccount`, `freezeAccount` and `unfreezeAccount`.
    /// The request carries a DID and the token must authenticate as that
    /// same account — see `auth::require_self`. A client calls them carrying
    /// the credential `createAccount` handed back, and an agent tearing
    /// down or toggling *itself* is the only caller this server can
    /// authenticate for them.
    ///
    /// **Used as identity, with nothing to compare it against.** The four
    /// authorization-decision routes: `approveAuthorization`,
    /// `declineAuthorization`, `getAuthorization` and
    /// `listPendingAuthorizations`. These name no account, so there is no
    /// comparison to make and none is made: what they read and answer are
    /// the decisions addressed to the account the presented token
    /// authenticates as, and an agent cannot ask for anybody else's because
    /// there is nowhere in the request to ask. `createBrowserSignIn` is the
    /// same: its ticket signs a browser in as that account.
    ///
    /// Either way, there is no operator credential to carve an exception
    /// for; see the module doc.
    AccountSelf,
    /// `createAccount` alone: a credential naming the creator, in any of
    /// the shapes `crate::tree::prove` resolves. See the module doc.
    Creator,
    /// `createSession` alone: a key-signed JWT or an OpenID Connect token
    /// naming a hosted account; see `crate::tree::prove`.
    Proof,
    /// `updateCredentials` alone: a JWT one of the account's keys signed,
    /// or the operator session with its CSRF header.
    KeyProofOrOperator,
    /// Public by default, and narrowable by this deployment's own
    /// configuration to operator-only — never the reverse. `listAccounts`,
    /// `listAccountLedgers`, `getAccountLedger` and `stats`: disclosure rather
    /// than mutation, and this project's accountability story rather than an
    /// accident — see [`Disclosure`] and `require_disclosure` for the reasoning
    /// and the mechanism, and `plan/auth-types.md`'s "publish by default" for
    /// the write-up this epic owes an audience beyond this table.
    Disclosure,
}

/// Per-route configuration for every [`Credential::Disclosure`] route: open
/// (public) or closed (operator-only), one flag per route rather than one
/// flag for all of them.
///
/// # Why public is the default
///
/// `listAccounts`, `listAccountLedgers`, `getAccountLedger` and `stats` say which
/// agents this deployment runs and what happened to them. Publishing that is
/// this project's accountability story, not an afterthought: `plan/ownership.md`
/// exists so a stranger can ask whether an agent traces to a responsible
/// human, and that question has no answer if the deployment that could
/// answer it is also the one deciding whether to be asked. The same argument
/// this project makes elsewhere for publishing what it is doing — so
/// divergence from what was promised is a comparison somebody outside can
/// make — applies here without modification: an operator who wants a quiet
/// server may close a route, but the field a fresh deployment starts from is
/// `true`.
///
/// # Why it is still toggleable
///
/// This is a decision for now, not a permanent property.
/// `plan/spaces.md` names "private means federation off" as an alternative
/// posture a deployment may choose, and disclosure is the same kind of
/// choice at a smaller grain: a deployment running agents on behalf of
/// people who would rather not have every account enumerated by a stranger
/// needs a way to say so. Per-route rather than one switch, because closing
/// the ledger while leaving the roster open — or the reverse — is a
/// plausible posture a single flag cannot express.
///
/// # The toggle may only narrow
///
/// Every field defaults `true`. A deployment's configuration may flip a
/// field to `false`; nothing may flip one to something wider than `true`,
/// because there is nothing wider than public — narrowing is the only
/// direction this configuration tier is ever allowed to move in, the same
/// rule that governs every other tier below the operator's own repository.
///
/// # Closing a route is visible, not silent
///
/// The threat this default exists to resist is an operator who cannot be
/// audited, and the configuration tier that closes a route is a tier an
/// on-box attacker also reaches — so closing `listAccounts` is exactly what
/// that attacker would do to hide what a stranger needed to see. This
/// cannot be prevented from here, but it is made visible:
/// `auth::require_disclosure` answers a closed route with `DisclosureDisabled`,
/// never a 404 and never an empty list, so an outsider can tell "this
/// server runs no agents" from "this server is not telling you" — two very
/// different facts, and only one of them is suspicious.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Disclosure {
    /// Whether a stranger may read which accounts this deployment holds.
    ///
    /// Every route that names them alike, not `bot.did.listAccounts` on its
    /// own: `com.atproto.sync.listRepos` pages through the same accounts,
    /// and `com.atproto.sync.subscribeRepos` announces each one as it
    /// appears and as it writes. Closing one and leaving the others would
    /// answer `DisclosureDisabled` over a roster still readable two other
    /// ways, which is worse than not offering the toggle: it says the
    /// accounts are hidden when they are not.
    ///
    /// Closing it costs federation. A relay crawls `subscribeRepos`, and a
    /// deployment that refuses it is not indexed — the trade
    /// `plan/spaces.md` names as "private means federation off", taken at
    /// this grain.
    pub list_accounts: bool,
    /// `bot.did.listAccountLedgers`.
    pub list_account_ledgers: bool,
    /// `bot.did.getAccountLedger`.
    pub get_account_ledger: bool,
    /// `bot.did.stats`.
    pub stats: bool,
}

impl Default for Disclosure {
    /// Every route open, which is this configuration's own resting state —
    /// see [`Disclosure`]'s own documentation for why the default is public
    /// rather than closed.
    fn default() -> Self {
        Self {
            list_accounts: true,
            list_account_ledgers: true,
            get_account_ledger: true,
            stats: true,
        }
    }
}

/// What a request's `Authorization` header actually named.
#[derive(Debug, Clone, PartialEq, Eq)]
enum Presented {
    /// No `Authorization` header, or one this server cannot parse at all.
    None,
    /// `Bearer <token>` — the scheme an agent token is presented under.
    Bearer(String),
    /// A scheme name this taxonomy knows and has decided not to serve here.
    Disabled(&'static str),
    /// A header with no space after its first word: a bare token, or a
    /// scheme and token split by something other than a space.
    NoScheme,
    /// A scheme word nobody defined. The word is not kept: a caller can put
    /// a token there, and [`authentication_required`] would echo it into the
    /// response and the journal.
    Unrecognized,
}

/// Schemes [`present`] names and refuses with 403 `SchemeDisabled`, so a
/// client presenting one is told "not enabled" rather than "not a scheme".
///
/// `DPoP` is the OAuth access token scheme atproto specifies. The routes
/// that take it read it off the headers through [`dpop_bearer`] instead of
/// through [`present`], so every route that resolves its credential here
/// refuses it.
///
/// `ServiceAuth` is refused on every route, and names no token this server
/// issues: the tokens `com.atproto.server.getServiceAuth` mints are
/// presented to other services as `Bearer`.
const DISABLED_SCHEMES: &[(&str, &str)] = &[("DPoP", "DPoP"), ("ServiceAuth", "ServiceAuth")];

fn present(headers: &HeaderMap) -> Presented {
    let Some(raw) = headers
        .get(header::AUTHORIZATION)
        .and_then(|value| value.to_str().ok())
    else {
        return Presented::None;
    };
    let Some((scheme, rest)) = raw.split_once(' ') else {
        return Presented::NoScheme;
    };
    let token = rest.trim().to_owned();
    if scheme.eq_ignore_ascii_case("Bearer") {
        return Presented::Bearer(token);
    }
    for (name, canonical) in DISABLED_SCHEMES {
        if scheme.eq_ignore_ascii_case(name) {
            return Presented::Disabled(canonical);
        }
    }
    Presented::Unrecognized
}

/// The header naming which scheme(s) a 401 wants.
const WWW_AUTHENTICATE: HeaderName = header::WWW_AUTHENTICATE;

/// `AuthenticationRequired`: no credential was presented at all, or the
/// scheme presented is not one this protocol defines.
fn authentication_required(hint: &str) -> ApiError {
    ApiError::new(
        StatusCode::UNAUTHORIZED,
        "AuthenticationRequired",
        format!("this route needs a credential, and none was presented ({hint})"),
    )
    .with_header(WWW_AUTHENTICATE, "Bearer")
}

/// `SchemeDisabled`: the scheme is one this server recognises, and this
/// route does not accept it. The message names the routes that do.
///
/// Its own name and its own status (403, not 401) so a client can tell this
/// apart from [`authentication_required`] by the name alone: retrying with a
/// *different* credential of the same kind will not help either, because the
/// kind itself is off here.
fn scheme_disabled(scheme: &'static str) -> ApiError {
    let message = if scheme == "DPoP" {
        let routes: Vec<&str> = ROUTE_CREDENTIALS
            .iter()
            .filter(|(_, credential)| *credential == Credential::AccountToken)
            .map(|(nsid, _)| *nsid)
            .collect();
        format!(
            "this route does not accept the `DPoP` scheme. These accept it: {}, and any call \
             carrying `atproto-proxy`",
            routes.join(", ")
        )
    } else {
        format!("no route accepts the `{scheme}` scheme")
    };
    ApiError::new(StatusCode::FORBIDDEN, "SchemeDisabled", message)
}

/// `DisclosureDisabled`: this deployment has closed a [`Credential::Disclosure`]
/// route by configuration, so it is closed to everyone.
///
/// Its own name, distinct from [`authentication_required`], on purpose: an
/// outsider reading `AuthenticationRequired` off a route that is public
/// everywhere else cannot tell "this deployment closed it" from "you forgot
/// a header", and both look identical to a route that does not exist. A
/// stranger auditing this deployment — `plan/ownership.md`'s whole premise —
/// needs to be able to tell "this server runs no agents" from "this server
/// is not telling you", and only a name of its own says which one happened.
/// 403, like [`scheme_disabled`]: retrying with a different credential will
/// not help either, because the deployment closed the route, not the
/// caller's credential.
fn disclosure_disabled(route: &str) -> ApiError {
    ApiError::new(
        StatusCode::FORBIDDEN,
        "DisclosureDisabled",
        format!(
            "this deployment has closed `{route}` by configuration; this is not evidence that \
             no agents exist here, only that this deployment chose not to publish it — and no \
             credential reaches past the toggle, which is closed for every caller alike"
        ),
    )
}

/// `InvalidToken`: the right scheme, a token this server does not recognise.
fn invalid_token(reason: &str) -> ApiError {
    ApiError::new(StatusCode::UNAUTHORIZED, "InvalidToken", reason.to_owned())
        .with_header(WWW_AUTHENTICATE, "Bearer")
}

/// What a refused `DPoP` credential was refused over, as RFC 9449 §7.1's
/// `error` names it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum DpopRefusal {
    /// The access token: unknown, expired, or bound to another key. A
    /// client refreshes on this one.
    Token,
    /// The proof beside it. A new token would not help.
    Proof,
}

/// `InvalidToken` for a `DPoP` credential, challenged in the `DPoP` scheme,
/// as RFC 9449 §7.1 asks. atproto clients refresh only on a `DPoP`
/// challenge naming `invalid_token`; a `Bearer` one is read as final.
fn invalid_dpop(refused: DpopRefusal, reason: &str) -> ApiError {
    let error = match refused {
        DpopRefusal::Token => "invalid_token",
        DpopRefusal::Proof => "invalid_dpop_proof",
    };
    ApiError::new(StatusCode::UNAUTHORIZED, "InvalidToken", reason.to_owned()).with_header(
        WWW_AUTHENTICATE,
        format!(
            "DPoP error=\"{error}\", algs=\"{}\"",
            crate::oauth::dpop::JWT_ALG
        ),
    )
}

/// A refused `DPoP` proof: RFC 9449 §9's `use_dpop_nonce` challenge, with
/// the nonce to retry with in `DPoP-Nonce`, for a proof that carries no
/// nonce this server accepts, and [`invalid_dpop`] for any other.
fn refused_proof(err: crate::oauth::dpop_seam::DpopError) -> ApiError {
    match err {
        crate::oauth::dpop_seam::DpopError::UseNonce { nonce, message } => {
            ApiError::new(StatusCode::UNAUTHORIZED, "UseDpopNonce", message)
                .with_header(
                    WWW_AUTHENTICATE,
                    format!(
                        "DPoP error=\"use_dpop_nonce\", algs=\"{}\"",
                        crate::oauth::dpop::JWT_ALG
                    ),
                )
                .with_header(crate::oauth::dpop::DPOP_NONCE, nonce)
        }
        err => invalid_dpop(DpopRefusal::Proof, &err.to_string()),
    }
}

/// `ExpiredToken`: the right scheme, a token that was once good.
pub(crate) fn expired_token() -> ApiError {
    ApiError::new(
        StatusCode::UNAUTHORIZED,
        "ExpiredToken",
        "this token has expired",
    )
    .with_header(WWW_AUTHENTICATE, "Bearer")
}

/// The bearer token the `Authorization` header carries, whatever it turns
/// out to be: the shared first step of every bearer-taking route.
pub(crate) fn bearer(headers: &HeaderMap) -> Result<String, ApiError> {
    match present(headers) {
        Presented::None => Err(authentication_required("no Authorization header")),
        Presented::NoScheme => Err(authentication_required(
            "`<no scheme>`: expected a scheme, one space, then the credential",
        )),
        Presented::Unrecognized => Err(authentication_required(
            "the scheme is not one this server defines",
        )),
        Presented::Disabled(scheme) => Err(scheme_disabled(scheme)),
        Presented::Bearer(token) => Ok(token),
    }
}

/// Resolves an agent token from the `Authorization` header, for
/// `com.atproto.repo.*`'s write routes and `uploadBlob`.
///
/// `Bearer <token>`, because atproto has one bearer scheme and the *kind* of
/// bearer a route wants is which store the token is checked against, not a
/// separate word in the header. A token [`Registry::verify_agent_token`]
/// does not recognise is [`invalid_token`].
pub fn require_agent_token(
    registry: &dyn Registry,
    headers: &HeaderMap,
) -> Result<String, ApiError> {
    agent_token(registry, headers).inspect_err(|refused| refused_xrpc(refused, None, None))
}

/// [`require_agent_token`], without writing a refusal down.
fn agent_token(registry: &dyn Registry, headers: &HeaderMap) -> Result<String, ApiError> {
    match registry.verify_agent_token(&bearer(headers)?) {
        Ok(did) => Ok(did),
        Err(TokenError::Expired) => Err(expired_token()),
        Err(TokenError::Unknown) => Err(invalid_token(
            "this token is not an agent token this server issued",
        )),
    }
}

/// The `DPoP` credential scheme's raw pieces, straight off the
/// `Authorization` and `DPoP` headers — deliberately not routed through
/// [`present`]/[`Presented`], which still folds `DPoP` into
/// [`Presented::Disabled`] for every other route in this module that has
/// not opted into accepting it (see [`DISABLED_SCHEMES`]'s own doc). Kept to
/// exactly the two headers a caller presenting this scheme sends, mirroring
/// [`present`]'s own header-splitting rather than growing that function a
/// third scheme every existing call site would need a new match arm for.
///
/// `None` when the credential is not in the `DPoP` scheme. A `DPoP`
/// credential beside no proof, or more than one, is refused as a bad proof
/// (RFC 9449 §4.3, §7.1).
fn dpop_bearer(headers: &HeaderMap) -> Result<Option<(String, &str)>, ApiError> {
    let Some((scheme, rest)) = headers
        .get(header::AUTHORIZATION)
        .and_then(|value| value.to_str().ok())
        .and_then(|raw| raw.split_once(' '))
    else {
        return Ok(None);
    };
    if !scheme.eq_ignore_ascii_case("DPoP") {
        return Ok(None);
    }
    let proof = crate::oauth::dpop::presented_proof(headers)
        .map_err(|err| invalid_dpop(DpopRefusal::Proof, &err.to_string()))?
        .ok_or_else(|| {
            invalid_dpop(
                DpopRefusal::Proof,
                "a `DPoP` access token needs a `DPoP` proof header beside it",
            )
        })?;
    Ok(Some((rest.trim().to_owned(), proof)))
}

/// Resolves either an agent's own [`Credential::AccountToken`] or a DPoP-bound
/// OAuth access token minted by `crate::oauth::token`, for
/// `com.atproto.repo.*`'s write routes and `uploadBlob` — the resource path
/// an app authorized over OAuth actually writes through.
///
/// `http_method` and `path` are this request's own method and route path
/// (e.g. `"/xrpc/com.atproto.repo.createRecord"`); a DPoP proof presented
/// here must bind to *this* request, not merely to some request the caller
/// once made. The absolute `htu` a proof is checked against is derived from
/// `path` the same way [`crate::oauth::discovery::request_htu`] builds it
/// for `/oauth/token` — out of this deployment's own zone service document,
/// never a header — and, deliberately, only when a `DPoP`-scheme credential
/// is actually presented: an agent-token route with no zone document seeded
/// yet (a bare `FakeRegistry`, or a deployment mid-bootstrap) must still be
/// reachable with a plain agent token, which needs no `htu` at all.
///
/// A `DPoP <token>` credential is checked in two steps, both required: the
/// `DPoP` header's proof must verify against this request
/// ([`crate::oauth::dpop_seam::DpopVerifier::verify`]), and the resulting
/// thumbprint must match the one `access_token` was minted bound to
/// ([`crate::oauth::token::OAuthTokenStore::validate_access`]). A bare
/// stolen token with no proof, or a well-formed proof signed by the wrong
/// key, fails at one of those two steps — see `plan/adversarial.md`'s
/// DPoP-binding findings, which this function exists to close.
pub fn require_agent_token_or_dpop(
    registry: &dyn Registry,
    oauth: &crate::oauth::OAuthState,
    headers: &HeaderMap,
    http_method: &str,
    path: &str,
) -> Result<Writer, ApiError> {
    agent_token_or_dpop(registry, oauth, headers, http_method, path)
        .inspect_err(|refused| refused_xrpc(refused, None, None))
}

/// [`require_agent_token_or_dpop`], without writing a refusal down.
fn agent_token_or_dpop(
    registry: &dyn Registry,
    oauth: &crate::oauth::OAuthState,
    headers: &HeaderMap,
    http_method: &str,
    path: &str,
) -> Result<Writer, ApiError> {
    if let Some((token, proof)) = dpop_bearer(headers)? {
        let htu = crate::oauth::discovery::request_htu(registry, path).map_err(|err| {
            ApiError::new(
                StatusCode::INTERNAL_SERVER_ERROR,
                "ServerError",
                err.to_string(),
            )
        })?;
        // The token goes in: RFC 9449 §7.1's `ath` check, which is what
        // binds this proof to *this* access token rather than to any request
        // the caller's key once signed.
        let verified = oauth
            .dpop
            .verify(proof, http_method, &htu, Some(&token))
            .map_err(refused_proof)?;
        let grant = oauth
            .tokens
            .validate_access(&token, &verified.thumbprint, oauth.scope_policy.as_ref())
            .ok_or_else(|| {
                invalid_dpop(
                    DpopRefusal::Token,
                    "this access token is not one this server issued, has expired, or does not \
                 match the key the presented DPoP proof proves possession of",
                )
            })?;
        // The token checked out, so this proof is one an authenticated
        // caller presented: now it costs a replay-window entry, and
        // presenting it a second time is refused.
        oauth
            .dpop
            .accept(&verified)
            .map_err(|err| invalid_dpop(DpopRefusal::Proof, &err.to_string()))?;
        return Ok(Writer {
            did: grant.did,
            token: Some((grant.client_id, grant.scope)),
        });
    }
    agent_token(registry, headers).map(|did| Writer { did, token: None })
}

/// Who a repo write speaks for, as [`require_agent_token_or_dpop`] resolved
/// it.
///
/// What a write needs past the account is reached through
/// [`Writer::authorize`] alone, so a route cannot name the client to the
/// write path without first checking the token's scope.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Writer {
    did: String,
    /// The application whose OAuth token was presented, and the scope that
    /// token was granted. `None` for the account's own agent token.
    token: Option<(didbot_pds::policy::ClientId, ScopeSet)>,
}

/// A write [`Writer::authorize`] found inside the credential's scope.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Authorized<'a> {
    /// The account writing.
    pub did: &'a str,
    /// The application whose token presented the write, for the policy
    /// that judges it. `None` for the account's own agent token.
    pub client_id: Option<&'a didbot_pds::policy::ClientId>,
}

/// What a request would have done, for the one it was refused over.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Wanted {
    /// A record write.
    Record {
        /// The collection written.
        collection: String,
        /// What the write would have done there.
        action: Action,
    },
    /// A blob upload.
    Upload {
        /// The type the uploader declared.
        mime_type: String,
    },
    /// A call at another service, or a service-auth token for one.
    Rpc {
        /// The method, or `None` for a token bound to no method.
        lxm: Option<String>,
        /// The service, as a DID or a DID and a service fragment.
        aud: String,
    },
}

/// The one thing a token's scope did not cover, which
/// [`insufficient_scope`] names.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ScopeMissing {
    /// The application whose token lacked it.
    pub client_id: didbot_pds::policy::ClientId,
    /// What it was trying to do.
    pub wanted: Wanted,
}

impl ScopeMissing {
    /// The scope it needed.
    #[must_use]
    pub fn needed(&self) -> Scope {
        match &self.wanted {
            Wanted::Record { collection, action } => Scope::repo_write(collection, *action),
            Wanted::Upload { mime_type } => Scope::blob_upload(mime_type),
            Wanted::Rpc { lxm, aud } => Scope::Rpc {
                method: lxm.clone().map_or(NsidPattern::Any, NsidPattern::Exact),
                aud: Some(aud.clone()),
            },
        }
    }
}

/// What the evaluation log names, where a policy's row names the policy,
/// for a write refused because its token's scope does not cover it.
pub const TOKEN_SCOPE_RULE: &str = "token-scope";

impl Writer {
    /// The account the credential authenticates as.
    #[must_use]
    pub fn did(&self) -> &str {
        &self.did
    }

    /// Checks every `(collection, action)` a request would write against
    /// the token's scope. The account's own agent token is not scoped: what
    /// it may write is policy's question alone.
    ///
    /// # Errors
    ///
    /// The first write the token's scope does not cover.
    pub fn authorize<'a>(
        &'a self,
        writes: &[(&str, Action)],
    ) -> Result<Authorized<'a>, ScopeMissing> {
        let Some((client_id, scope)) = &self.token else {
            return Ok(Authorized {
                did: &self.did,
                client_id: None,
            });
        };
        if let Some((collection, action)) = writes
            .iter()
            .find(|(collection, action)| !scope.covers(&Scope::repo_write(collection, *action)))
        {
            return Err(ScopeMissing {
                client_id: client_id.clone(),
                wanted: Wanted::Record {
                    collection: (*collection).to_owned(),
                    action: *action,
                },
            });
        }
        Ok(Authorized {
            did: &self.did,
            client_id: Some(client_id),
        })
    }

    /// Checks one upload's declared type against the token's scope. How
    /// large a blob may be is policy's and the server's, not the grant's.
    ///
    /// # Errors
    ///
    /// The upload, when the token's scope does not cover it.
    pub fn authorize_blob(&self, mime_type: &str) -> Result<Authorized<'_>, ScopeMissing> {
        let Some((client_id, scope)) = &self.token else {
            return Ok(Authorized {
                did: &self.did,
                client_id: None,
            });
        };
        if !scope.covers(&Scope::blob_upload(mime_type)) {
            return Err(ScopeMissing {
                client_id: client_id.clone(),
                wanted: Wanted::Upload {
                    mime_type: mime_type.to_owned(),
                },
            });
        }
        Ok(Authorized {
            did: &self.did,
            client_id: Some(client_id),
        })
    }

    /// Checks acting at another service against the token's scope: calling
    /// `lxm` at `aud`, or taking a service-auth token for it. The account's
    /// own agent token acts anywhere.
    ///
    /// # Errors
    ///
    /// The call, when the token's scope does not permit it; see
    /// [`ScopeSet::permits_rpc`].
    pub fn authorize_rpc(
        &self,
        lxm: Option<&str>,
        aud: &str,
    ) -> Result<Authorized<'_>, ScopeMissing> {
        let Some((client_id, scope)) = &self.token else {
            return Ok(Authorized {
                did: &self.did,
                client_id: None,
            });
        };
        if !scope.permits_rpc(lxm, aud) {
            return Err(ScopeMissing {
                client_id: client_id.clone(),
                wanted: Wanted::Rpc {
                    lxm: lxm.map(str::to_owned),
                    aud: aud.to_owned(),
                },
            });
        }
        Ok(Authorized {
            did: &self.did,
            client_id: Some(client_id),
        })
    }
}

/// `InsufficientScope`: a real token, asked to do what it was not granted.
/// RFC 6750's `insufficient_scope`, in the DPoP scheme the token was
/// presented under, naming the scope the write needed. Written to the
/// journal with the client and `did`, the account the token speaks for.
pub fn insufficient_scope(did: &str, missing: &ScopeMissing) -> ApiError {
    let refused = ApiError::new(
        StatusCode::FORBIDDEN,
        "InsufficientScope",
        format!("this token's scope does not cover `{}`", missing.needed()),
    )
    .with_header(
        WWW_AUTHENTICATE,
        format!(
            "DPoP error=\"insufficient_scope\", scope=\"{}\"",
            missing.needed()
        ),
    );
    refused_xrpc(&refused, Some(missing.client_id.as_str()), Some(did));
    refused
}

/// Writes an XRPC credential refusal to the journal; see `crate::refusal`.
///
/// `UseDpopNonce` is the first answer every DPoP client is given, and it
/// retries at once, so it is not written.
fn refused_xrpc(refused: &ApiError, client_id: Option<&str>, account: Option<&str>) {
    if refused.error() == "UseDpopNonce" {
        return;
    }
    crate::refusal::refused(crate::refusal::Refusal {
        endpoint: "xrpc",
        client_id,
        account,
        error: refused.error(),
        reason: refused.message(),
        severity: crate::refusal::Severity::Info,
    });
}

/// Resolves an agent's own credential against the account a request names,
/// for every account-lifecycle mutation this server serves.
///
/// `target` is the account the request names — the `did` field of the body.
/// An agent token authenticates only when it names that same account, which
/// is [`ApiError::account_mismatch`] otherwise: these routes are
/// self-service and nothing else. Acting on *another* account over HTTP
/// would need a credential proving this deployment's operator, and there is
/// no such credential — a server reads who operates it out of the
/// operator's own repository and never holds anything presentable back to
/// it. See the module doc's "There is no operator credential", and
/// `Registry::hard_delete` for the one lifecycle operation that
/// consequently has no route at all.
///
/// Same failure shapes as [`require_agent_token`] for everything short of the
/// account check: no header or an unrecognised scheme is
/// [`authentication_required`], a defined-but-disabled scheme is
/// [`scheme_disabled`], and a well-formed credential of the wrong kind or
/// value is [`invalid_token`].
pub fn require_self(
    registry: &dyn Registry,
    headers: &HeaderMap,
    target: &str,
) -> Result<(), ApiError> {
    own_account(registry, headers, target)
        .inspect_err(|refused| refused_xrpc(refused, None, Some(target)))
}

/// [`require_self`], without writing a refusal down.
fn own_account(registry: &dyn Registry, headers: &HeaderMap, target: &str) -> Result<(), ApiError> {
    match registry.verify_agent_token(&bearer(headers)?) {
        Ok(did) if did == target => Ok(()),
        Ok(did) => Err(ApiError::account_mismatch(&did, target)),
        Err(TokenError::Expired) => Err(expired_token()),
        Err(TokenError::Unknown) => Err(invalid_token(
            "this token is not an agent token this server issued",
        )),
    }
}

/// Resolves a [`Credential::Disclosure`] route: open unless this
/// deployment's configuration has closed it, in which case it is closed to
/// everyone.
///
/// `open` is the one field of [`Disclosure`] this route's toggle lives at,
/// and it is the whole of the decision — this function reads no header at
/// all. `true` — the default — is public, full stop, the same as
/// [`Credential::Public`]. `false` is [`disclosure_disabled`] for every
/// caller alike: there is no operator credential that could reach past the
/// toggle (see the module doc), so a deployment that closes a disclosure
/// route closes it to itself over HTTP too, and an operator who wants the
/// data back turns the toggle back on rather than presenting something.
///
/// One refusal rather than the usual [`authentication_required`] versus
/// [`invalid_token`] split, which was already true when a credential could
/// reach past this and is more plainly true now: the caller only needs to
/// learn one thing here, that this route is closed by configuration and not
/// merely guarded by a login it forgot.
pub fn require_disclosure(open: bool, route: &str) -> Result<(), ApiError> {
    if open {
        return Ok(());
    }
    Err(disclosure_disabled(route))
}

/// Every `com.atproto.*`, `app.bsky.*` and `bot.did.*` method this router
/// serves, and the credential it declares. See the module doc for what each kind means.
///
/// This is `plan/auth-types.md`'s "one extractor, and a per-route
/// declaration of what it accepts", and it is **not written here**: it is
/// assembled from `routes::ATPROTO_CREDENTIALS`,
/// `routes::APP_BSKY_CREDENTIALS` and `routes::BOT_DID_CREDENTIALS`, which
/// the `xrpc_methods!` macro emits from
/// the same entries it builds the router out of. A route therefore cannot
/// exist without a declaration — the macro arm does not accept an entry that
/// omits one — and a declaration cannot outlive the route it names, because
/// deleting the entry deletes both. Neither direction of drift is
/// representable, which is why nothing below is a runtime check.
///
/// Where each kind's reasoning lives: [`Credential`]'s variants for what a
/// kind is, this module's "Why every public route is public" for the three
/// separate reasons a route is `Public`, and the three macro invocations in
/// `routes.rs` for which routes take what.
pub const ROUTE_CREDENTIALS: &[(&str, Credential)] = &ROUTE_CREDENTIAL_TABLE;

/// The backing array [`ROUTE_CREDENTIALS`] borrows.
///
/// A `const fn` rather than a literal because the parts come from three
/// macro invocations and `const` slice concatenation is not otherwise
/// available.
const ROUTE_CREDENTIAL_TABLE: [(&str, Credential); ROUTE_CREDENTIAL_COUNT] = route_credentials();

const ROUTE_CREDENTIAL_COUNT: usize = crate::routes::ATPROTO_CREDENTIALS.len()
    + crate::routes::APP_BSKY_CREDENTIALS.len()
    + crate::routes::BOT_DID_CREDENTIALS.len();

const fn route_credentials() -> [(&'static str, Credential); ROUTE_CREDENTIAL_COUNT] {
    let halves = [
        crate::routes::ATPROTO_CREDENTIALS,
        crate::routes::APP_BSKY_CREDENTIALS,
        crate::routes::BOT_DID_CREDENTIALS,
    ];
    let mut table = [("", Credential::Public); ROUTE_CREDENTIAL_COUNT];
    let mut at = 0;
    let mut half = 0;
    while half < halves.len() {
        let mut i = 0;
        while i < halves[half].len() {
            table[at] = halves[half][i];
            at += 1;
            i += 1;
        }
        half += 1;
    }
    table
}

/// The credential a route declares.
///
/// `None` only for an NSID this server does not serve: every route it does
/// serve is in the table by construction — see [`ROUTE_CREDENTIALS`].
#[cfg(test)]
pub fn declared(nsid: &str) -> Option<Credential> {
    ROUTE_CREDENTIALS
        .iter()
        .find(|(name, _)| *name == nsid)
        .map(|(_, credential)| *credential)
}

#[cfg(test)]
mod tests {
    use super::*;
    use axum::http::HeaderValue;

    fn headers_with_auth(value: &str) -> HeaderMap {
        let mut headers = HeaderMap::new();
        headers.insert(header::AUTHORIZATION, HeaderValue::from_str(value).unwrap());
        headers
    }

    /// The credential table and the served NSIDs agree in both directions.
    ///
    /// Both come from the same macro entries, so this cannot fail while the
    /// macro is the only way routes are declared. It is here to fail if
    /// somebody stops using it — a hand-written `.route()` call added
    /// alongside the macro, or an entry hand-added to one list and not the
    /// other. `crate::tests::every_served_route_has_a_credential` is the
    /// half this cannot do: it reads the router itself rather than either
    /// list.
    #[test]
    fn the_credential_table_is_exactly_the_served_routes() {
        let served: Vec<&str> = crate::routes::ATPROTO_METHODS
            .iter()
            .chain(crate::routes::APP_BSKY_METHODS)
            .chain(crate::routes::BOT_DID_METHODS)
            .copied()
            .collect();
        for nsid in &served {
            assert!(
                declared(nsid).is_some(),
                "{nsid} is served and has no entry in ROUTE_CREDENTIALS"
            );
        }
        for (nsid, _) in ROUTE_CREDENTIALS {
            assert!(
                served.contains(nsid),
                "{nsid} has a declared credential and is not served"
            );
        }
    }

    #[test]
    fn no_credential_is_authentication_required() {
        let registry = crate::tests::FakeRegistry::new();
        let err = require_agent_token(&registry, &HeaderMap::new()).unwrap_err();
        assert_eq!(err.error(), "AuthenticationRequired");
        assert_eq!(err.status(), StatusCode::UNAUTHORIZED);
    }

    #[test]
    fn an_unrecognised_scheme_is_authentication_required() {
        let registry = crate::tests::FakeRegistry::new();
        let headers = headers_with_auth("Digest abc123");
        let err = require_agent_token(&registry, &headers).unwrap_err();
        assert_eq!(err.error(), "AuthenticationRequired");
    }

    /// The distinguishability test `plan/auth-types.md` calls for by name:
    /// an unrecognised scheme and a recognised-but-disabled one must not
    /// read the same way.
    #[test]
    fn a_disabled_scheme_reads_differently_from_an_unrecognised_one() {
        let registry = crate::tests::FakeRegistry::new();
        let unrecognised =
            require_agent_token(&registry, &headers_with_auth("Digest abc")).unwrap_err();
        let disabled = require_agent_token(&registry, &headers_with_auth("DPoP abc")).unwrap_err();
        assert_ne!(unrecognised.error(), disabled.error());
        assert_ne!(unrecognised.status(), disabled.status());
        assert_eq!(disabled.error(), "SchemeDisabled");
        assert_eq!(disabled.status(), StatusCode::FORBIDDEN);

        let service_auth =
            require_agent_token(&registry, &headers_with_auth("ServiceAuth abc")).unwrap_err();
        assert_eq!(service_auth.error(), "SchemeDisabled");
    }

    #[test]
    fn an_unknown_bearer_token_is_invalid_not_authentication_required() {
        let registry = crate::tests::FakeRegistry::new();
        let headers = headers_with_auth("Bearer not-a-real-token");
        let err = require_agent_token(&registry, &headers).unwrap_err();
        assert_eq!(err.error(), "InvalidToken");
    }

    /// The removal this module's "There is no operator credential" section
    /// describes, asserted rather than only written down: `Operator` is not
    /// a scheme this server defines, so presenting one reads exactly like
    /// presenting `Digest` or any other word nobody defined — and, in
    /// particular, never like a credential that merely failed to match.
    #[test]
    fn the_operator_scheme_is_not_a_scheme_this_server_defines() {
        let registry = crate::tests::FakeRegistry::new();
        let operator =
            require_agent_token(&registry, &headers_with_auth("Operator swordfish")).unwrap_err();
        let unknown =
            require_agent_token(&registry, &headers_with_auth("Digest swordfish")).unwrap_err();
        assert_eq!(operator.error(), "AuthenticationRequired");
        assert_eq!(operator.error(), unknown.error());
        assert_eq!(operator.status(), unknown.status());
    }

    /// A closed disclosure route is closed to everyone: no credential, and
    /// specifically no `Operator` one, reaches past the toggle.
    #[test]
    fn a_closed_disclosure_route_refuses_every_caller() {
        assert!(require_disclosure(true, "bot.did.listAccounts").is_ok());
        let err = require_disclosure(false, "bot.did.listAccounts").unwrap_err();
        assert_eq!(err.error(), "DisclosureDisabled");
        assert_eq!(err.status(), StatusCode::FORBIDDEN);
    }

    /// Hard delete is the one account-lifecycle operation with no route,
    /// because it is the one that must not be self-service and this server
    /// has no administrator credential. A future branch that adds the route
    /// back has to change this test to do it.
    #[test]
    fn hard_delete_has_no_route_and_no_declared_credential() {
        assert!(declared("bot.did.hardDeleteAccount").is_none());
        assert!(!crate::routes::BOT_DID_METHODS.contains(&"bot.did.hardDeleteAccount"));
    }

    #[test]
    fn disclosure_defaults_to_every_route_open() {
        assert_eq!(
            Disclosure::default(),
            Disclosure {
                list_accounts: true,
                list_account_ledgers: true,
                get_account_ledger: true,
                stats: true,
            }
        );
    }

    #[test]
    fn an_open_disclosure_route_needs_no_credential_at_all() {
        // An open route is public, full stop. `require_disclosure` reads no
        // header at all now, so there is nothing a caller could present
        // that would change this either way.
        assert!(require_disclosure(true, "bot.did.stats").is_ok());
    }

    #[test]
    fn a_closed_disclosure_route_is_disclosure_disabled_not_authentication_required() {
        let err = require_disclosure(false, "bot.did.stats").unwrap_err();
        assert_eq!(err.error(), "DisclosureDisabled");
        assert_eq!(err.status(), StatusCode::FORBIDDEN);
    }

    /// A closed route used to answer a valid `Operator` credential. It
    /// answers nobody now — including a caller presenting the scheme that
    /// used to work, which must read as closed rather than as a login it
    /// got wrong.
    #[test]
    fn a_closed_disclosure_route_answers_nobody() {
        for header in [
            "Operator swordfish",
            "Bearer swordfish",
            "Nonsense whatever",
        ] {
            let _ = headers_with_auth(header);
            let err = require_disclosure(false, "bot.did.stats").unwrap_err();
            assert_eq!(err.error(), "DisclosureDisabled");
        }
    }

    /// The three tree routes declare the credentials they read, and nothing
    /// else declares them.
    #[test]
    fn the_tree_routes_declare_their_own_credentials() {
        assert_eq!(declared("bot.did.createAccount"), Some(Credential::Creator));
        assert_eq!(declared("bot.did.createSession"), Some(Credential::Proof));
        assert_eq!(declared("bot.did.parkKey"), Some(Credential::Public));
        assert_eq!(
            declared("bot.did.updateCredentials"),
            Some(Credential::KeyProofOrOperator)
        );
        assert_eq!(
            ROUTE_CREDENTIALS
                .iter()
                .filter(|(_, credential)| matches!(
                    credential,
                    Credential::Creator | Credential::Proof | Credential::KeyProofOrOperator
                ))
                .count(),
            3
        );
    }

    #[test]
    fn disclosure_disabled_reads_differently_from_authentication_required() {
        let closed = require_disclosure(false, "bot.did.stats").unwrap_err();
        let unauthenticated =
            require_agent_token(&crate::tests::FakeRegistry::new(), &HeaderMap::new()).unwrap_err();
        assert_ne!(closed.error(), unauthenticated.error());
    }
}