didbot_serve/routes/

oauth.rs

use super::*;
use crate::landing;
use didbot_brand::page::{escape, Landing, Tone};

use crate::oauth::error::OAuthError;
use crate::refusal::Severity;

/// An OAuth refusal on its way out: what the client is sent, and how the
/// journal says it. See `crate::refusal`.
pub(crate) struct Refused {
    error: OAuthError,
    severity: Severity,
    /// The reason, when it is more than the description the client is
    /// sent. A client metadata failure is one sentence on the wire and the
    /// whole cause here.
    reason: Option<String>,
}

impl Refused {
    pub(crate) fn info(error: OAuthError) -> Self {
        Self {
            error,
            severity: Severity::Info,
            reason: None,
        }
    }

    pub(crate) fn warn(error: OAuthError) -> Self {
        Self {
            error,
            severity: Severity::Warn,
            reason: None,
        }
    }

    fn because(mut self, reason: impl std::fmt::Display) -> Self {
        self.reason = Some(reason.to_string());
        self
    }

    /// Writes the refusal and answers with it.
    pub(crate) fn answer(
        self,
        endpoint: &'static str,
        client_id: Option<&str>,
        account: Option<&str>,
    ) -> Response {
        self.write(endpoint, client_id, account);
        self.error.into_response()
    }

    /// Writes the refusal, for an endpoint that answers a browser with a
    /// page instead.
    ///
    /// `use_dpop_nonce` is the first answer every DPoP client is given, and
    /// it retries at once, so it is not written.
    pub(crate) fn write(
        &self,
        endpoint: &'static str,
        client_id: Option<&str>,
        account: Option<&str>,
    ) {
        use crate::oauth::error::OAuthErrorCode;
        if self.error.error() != OAuthErrorCode::UseDpopNonce.as_str() {
            crate::refusal::refused(crate::refusal::Refusal {
                endpoint,
                client_id,
                account,
                error: self.error.error(),
                reason: self
                    .reason
                    .as_deref()
                    .unwrap_or_else(|| self.error.description()),
                severity: self.severity,
            });
        }
    }
}

/// `GET /.well-known/oauth-authorization-server`
///
/// See `crate::oauth::discovery` for why the issuer this reports is read out
/// of this deployment's own zone service document rather than computed here.
pub(crate) async fn oauth_server_metadata(State(state): State<AppState>) -> Response {
    use crate::oauth::error::{OAuthError, OAuthErrorCode};
    match crate::oauth::discovery::server_metadata(state.registry.as_ref()) {
        Ok(metadata) => Json(metadata).into_response(),
        Err(err) => OAuthError::new(OAuthErrorCode::ServerError, err.to_string()).into_response(),
    }
}

/// `GET /.well-known/oauth-protected-resource`
///
/// RFC 9728 plus the atproto profile; see `crate::oauth::discovery` for why
/// this reports the same origin `oauth_server_metadata`'s `issuer` does.
pub(crate) async fn oauth_protected_resource_metadata(State(state): State<AppState>) -> Response {
    use crate::oauth::error::{OAuthError, OAuthErrorCode};
    match crate::oauth::discovery::protected_resource_metadata(state.registry.as_ref()) {
        Ok(metadata) => Json(metadata).into_response(),
        Err(err) => OAuthError::new(OAuthErrorCode::ServerError, err.to_string()).into_response(),
    }
}

/// The wire fields `POST /oauth/par` accepts, form-encoded per RFC 9126.
#[derive(serde::Deserialize)]
pub(crate) struct OAuthParForm {
    client_id: String,
    response_type: Option<String>,
    response_mode: Option<String>,
    redirect_uri: Option<String>,
    scope: Option<String>,
    state: Option<String>,
    code_challenge: Option<String>,
    code_challenge_method: Option<String>,
    login_hint: Option<String>,
    client_assertion_type: Option<String>,
    client_assertion: Option<String>,
    dpop_jkt: Option<String>,
}

/// `POST /oauth/par`
///
/// The one place a sign-in is judged, and the earliest point a client is
/// known; see `crate::oauth::par`'s doc for the two inputs that reach the
/// verdict, and `crate::oauth::decision` for the record they are written
/// into. `login_hint` is resolved through this layer's own
/// [`Registry`] — the layer that holds one — and a hint naming no account on
/// this deployment gets the same `201` a real one does; see
/// `crate::oauth::par::push_for_unresolved_hint` for what it does not get.
///
/// Unauthenticated, and bounded per caller address by
/// [`crate::oauth::OAuthState::par_rate_limiter`] before any of that
/// happens. Its DPoP proof is checked next; see [`checked_proof`].
pub(crate) async fn oauth_par(
    State(state): State<AppState>,
    peer: Peer,
    headers: HeaderMap,
    axum::Form(form): axum::Form<OAuthParForm>,
) -> Response {
    use crate::oauth::par::{push_authorization_request, DecisionSeams, ParRequest};

    let client_id = form.client_id.clone();
    let refuse = |refused: Refused| refused.answer("par", Some(&client_id), None);

    // Before the client document is fetched: the fetch goes to a host this
    // caller chose, and nothing here has authenticated the caller.
    let key = caller_key(&headers, peer.0, state.trust_forwarded_headers);
    if !state.oauth.par_rate_limiter.check(&key) {
        return refuse(Refused::info(too_many_oauth_requests("par")));
    }

    // Checked and not accepted: a push may carry no credential at all, and
    // an entry in the replay window costs one. Its key is what the code this
    // push leads to is bound to.
    let proof = match checked_proof(&state, &headers, "/oauth/par") {
        Ok(proof) => proof,
        Err(refused) => return refuse(Refused::info(refused)),
    };

    let request = ParRequest {
        client_id: form.client_id,
        response_type: form.response_type,
        response_mode: form.response_mode,
        redirect_uri: form.redirect_uri,
        scope: form.scope,
        state: form.state,
        code_challenge: form.code_challenge,
        code_challenge_method: form.code_challenge_method,
        login_hint: form.login_hint,
        credentials: crate::oauth::client_auth::ClientCredentials {
            assertion_type: form.client_assertion_type,
            assertion: form.client_assertion,
        },
        dpop_jkt: form.dpop_jkt,
        proof_key: proof.thumbprint,
    };
    // Empty before the zone's document exists, as `deployment_did` is, and
    // then no client assertion names it.
    let issuer = crate::oauth::discovery::issuer_for(state.registry.as_ref()).unwrap_or_default();
    let pds_did = deployment_did(&state);
    let pds_hostname = state.registry.zone().to_owned();
    let seams = DecisionSeams {
        scope_policy: state.oauth.scope_policy.as_ref(),
        consent_store: state.oauth.consent_store.as_ref(),
        decisions: state.oauth.decision_store.as_ref(),
        gate: state.oauth.grant_gate.as_ref(),
        evaluation_log: state.oauth.evaluation_log.as_ref(),
        pds_did: &pds_did,
        pds_hostname: &pds_hostname,
        loopback_clients: crate::oauth::client_metadata::LoopbackClients::for_zone(&pds_hostname),
        client_assertions: state.oauth.client_assertions.as_ref(),
        issuer: &issuer,
        permission_sets: state.oauth.permission_sets.as_ref(),
    };
    match push_authorization_request(
        &state.oauth.http,
        state.oauth.client_cache.as_ref(),
        state.oauth.par_store.as_ref(),
        request,
        &|hint| resolve_identifier(&state, hint),
        &seams,
    )
    .await
    {
        Ok((request_uri, ttl)) => (
            StatusCode::CREATED,
            Json(json!({ "request_uri": request_uri, "expires_in": ttl.whole_seconds() })),
        )
            .into_response(),
        Err(err) => refuse(par_refusal(err)),
    }
}

/// What a refused push answers, and how loudly it is written.
///
/// `warn` is a client whose sign-ins will all fail until its own
/// deployment changes, and a server too full to take a push. The rest is a
/// caller's mistake or this server's policy, at `info`.
fn par_refusal(err: crate::oauth::par::ParError) -> Refused {
    use crate::oauth::error::OAuthErrorCode;
    use crate::oauth::par::ParError;
    let code = match err {
        ParError::MissingParameter(_)
        | ParError::BadScope(_)
        | ParError::UnsupportedCodeChallengeMethod(_)
        | ParError::MalformedCodeChallenge
        | ParError::TooLong { .. }
        | ParError::ClientRefused
        | ParError::UnsupportedResponseMode(_)
        | ParError::RedirectUriNotRegistered(_) => OAuthErrorCode::InvalidRequest,
        ParError::UnsupportedResponseType => OAuthErrorCode::UnsupportedResponseType,
        ParError::ClientId(_) | ParError::ClientMetadata(_) => OAuthErrorCode::InvalidClient,
        ParError::ClientAuthentication(ref refused) => refused.code(),
        ParError::DpopKeyMismatch => OAuthErrorCode::InvalidDpopProof,
        ParError::TooManyPending(_) => OAuthErrorCode::AccessDenied,
    };
    let error = OAuthError::new(code, err.to_string());
    match err {
        // The client is sent one sentence; the cause is the operator's.
        ParError::ClientMetadata(cause) => Refused::warn(error).because(cause),
        ParError::ClientAuthentication(_)
        | ParError::RedirectUriNotRegistered(_)
        | ParError::TooManyPending(_) => Refused::warn(error),
        _ => Refused::info(error),
    }
}

/// This deployment's own DID, as a policy subject names it: empty before
/// the zone's document exists.
pub(crate) fn deployment_did(state: &AppState) -> String {
    state
        .registry
        .did_document(state.registry.zone())
        .map(|document| document.id.clone())
        .unwrap_or_default()
}

/// `GET /oauth/authorize`'s query parameters.
#[derive(serde::Deserialize)]
pub(crate) struct OAuthAuthorizeQuery {
    client_id: String,
    request_uri: String,
}

/// The 429 the unauthenticated OAuth endpoints answer with; see
/// [`OAuthError::rate_limited`].
pub(crate) fn too_many_oauth_requests(endpoint: &str) -> OAuthError {
    OAuthError::rate_limited(endpoint)
}

pub(crate) fn authorize_error(err: crate::oauth::authorize::AuthorizeError) -> OAuthError {
    use crate::oauth::authorize::AuthorizeError;
    use crate::oauth::error::OAuthErrorCode;
    let code = match err {
        AuthorizeError::UnknownRequestUri | AuthorizeError::ClientMismatch => {
            OAuthErrorCode::InvalidGrant
        }
    };
    OAuthError::new(code, err.to_string())
}

/// The page [`oauth_authorize`] answers when `err` stops it before it
/// finds a sign-in to show.
pub(crate) fn authorize_error_page(err: crate::oauth::authorize::AuthorizeError) -> Response {
    use crate::oauth::authorize::AuthorizeError;
    let what = match err {
        AuthorizeError::UnknownRequestUri => "this sign-in request expired or is unknown",
        AuthorizeError::ClientMismatch => "this link does not match its sign-in request",
    };
    landing::refused(
        StatusCode::BAD_REQUEST,
        landing::AUTHORIZE,
        "invalid_grant",
        what,
        "",
        "Start the sign-in again from the app.",
    )
}

/// The page `GET /oauth/authorize` serves for one decision.
///
/// A person's view of exactly what `bot.did.getAuthorization` hands an
/// agent: the origin the client served its metadata from, its content key,
/// what it asked for, what this server would grant, and what it cut. The
/// client's own name, home page and logo are not here and must not be — see
/// `crate::oauth::decision`'s doc and `plan/app-allowlist.md`.
///
/// The heading is a placeholder, per this project's copywriting rule. The
/// rest is plain labels over the attributes, which are the load-bearing part.
///
/// The page names the decision's state and its own `authorize_url`. While
/// the account has not answered, or its approval's code waits for a browser
/// signed in as the account, it reloads itself every
/// [`crate::oauth::authorize::RELOAD_INTERVAL`], with no script, so the
/// load after the answer sees it. It carries no code; see
/// [`oauth_authorize`]. The URL is in the text because a harness finds a
/// sign-in by the `/oauth/authorize?` URLs in a tool's output: a browser tool
/// that reads this page reports the `request_uri`.
///
/// `data-browser` says whether this browser is signed in as the account.
/// While a code waits for one that is, a browser that is not is told where
/// to sign in, `sign_in_url`.
///
/// The page lists the scopes requested, then the scopes the scope ceiling
/// allows. Approving covers that second list, and the ceiling is asked again
/// at every use (`data-approves`, `data-ceiling-checked`).
///
/// There is no form. Approving is `bot.did.approveAuthorization`, which
/// takes the account's own agent token as `Credential::AccountSelf` — a
/// credential an HTML form cannot carry, so a form here could only post to
/// something that would refuse it. A browser-driven client approving on the
/// agent's behalf reads the one-time reference from
/// `bot.did.getAuthorization`, which takes the same credential the approval
/// itself takes: this route takes no credential at all, so anything that can
/// follow the `request_uri` can read what this page says, and the reference
/// is not on it.
///
/// Every element carries its value in an attribute for such a client and in
/// text for a person, which is why the account is rendered both ways rather
/// than sitting in markup a reader cannot see.
pub(crate) fn authorize_page(
    pending: &crate::oauth::authorize::AuthorizePending,
    authorize_url: &str,
    sign_in_url: &str,
) -> Response {
    let record = &pending.record;
    let items = |scopes: &crate::oauth::scope::ScopeSet| -> String {
        let items: String = scopes
            .0
            .iter()
            .map(|atom| {
                let atom = escape(&atom.to_string());
                format!("<li data-scope=\"{atom}\">{atom}</li>")
            })
            .collect();
        format!("<ul>{items}</ul>")
    };
    // Named for the check that produced it. The scope ceiling is the only
    // thing that decides this list; a token policy can still refuse the
    // exchange, and a write policy can still refuse a write a listed scope
    // covers, so a list labelled "policies" would promise their answers too.
    let only = if pending.cut.0.is_empty() {
        ""
    } else {
        "only "
    };
    let allowed = format!(
        "The scope ceiling allows {only}these scopes:{}",
        items(&pending.granted)
    );
    let account = escape(&record.account);
    let browser = match (pending.signed_in, pending.held) {
        (true, _) => {
            format!("<p data-browser=\"signed-in\">This browser is signed in as {account}.</p>")
        }
        (false, false) => format!(
            "<p data-browser=\"not-signed-in\">This browser is not signed in as {account}.</p>"
        ),
        (false, true) => format!(
            "<p class=\"next\" data-browser=\"not-signed-in\" data-sign-in=\"{url}\">This \
             browser is not signed in as {account}. Sign it in at <a href=\"{url}\">{url}</a>.</p>",
            url = escape(sign_in_url)
        ),
    };
    let (status, tone) = match (pending.waiting(), pending.held) {
        (true, _) => ("waiting for the account", Tone::Waiting),
        (false, true) => ("approved: waiting for its browser", Tone::Waiting),
        (false, false) => ("approved", Tone::Done),
    };
    let body = format!(
        "<p data-state=\"{state}\">State: {state}</p>\
         <p data-client-origin=\"{origin}\" data-client-key=\"{key}\" \
            data-client-first-time=\"{first}\">{origin}{unverified}</p>\
         <p data-account=\"{account}\">{account}</p>\
         {browser}\
         <div data-requested=\"{requested}\">This application has requested these scopes:\
            {requested_items}</div>\
         <div data-verdict=\"{verdict}\" data-granted=\"{granted}\" data-cut=\"{cut}\" \
            data-rule=\"{rule}\" data-approves=\"granted\" \
            data-ceiling-checked=\"each-use\">\
            {allowed}</div>\
         <p class=\"hint\" data-authorize-url=\"{url}\">Authorize URL: {url}</p>",
        state = record.state.as_str(),
        url = escape(authorize_url),
        origin = escape(&record.client_origin),
        key = escape(&record.client_key.0),
        first = record.first_time,
        unverified = if didbot_pds::policy::is_local_origin(&record.client_origin) {
            ": an unverified local app"
        } else {
            ""
        },
        requested = escape(&record.requested.to_string()),
        requested_items = items(&record.requested),
        verdict = record.verdict.kind(),
        granted = escape(&pending.granted.to_string()),
        cut = escape(&pending.cut.to_string()),
        rule = escape(&pending.rule),
    );
    landing::page(
        StatusCode::OK,
        &Landing {
            placeholder: landing::AUTHORIZE,
            tone,
            status,
            body: &body,
            reload: pending
                .reloads()
                .then_some(crate::oauth::authorize::RELOAD_INTERVAL.as_secs()),
        },
    )
}

/// `GET /oauth/authorize`
///
/// Answers every load of a pushed request this server holds, which RFC 9126
/// §4 allows, with what [`crate::oauth::authorize::answer`] decides: the
/// page while the account has not answered, and after it approved.
///
/// A code an approval held for a browser goes, as `303 See Other` to the
/// client's redirect, to a top-level navigation by a browser whose
/// [`crate::oauth::browser::COOKIE`] names a session signed in as the
/// account, once. `Sec-Fetch-Dest` tells a navigation apart where a browser
/// sends it. Any other browser gets the page, approved and reloading, until
/// the request expires, which is logged with the account. A decline, a
/// verdict that grants nothing, or an expiry answers `303 See Other` to the
/// client's redirect with `access_denied`.
///
/// A load that meets [`crate::oauth::authorize::confirms_unasked`] first
/// approves the sign-in on the account's remembered approval, so that
/// browser collects the code without the account being asked.
///
/// Nothing is decided here: see `crate::oauth::decision` for why the verdict
/// is reached at PAR. Every answer carries `Cache-Control: no-store`, since
/// the page changes when the account answers, and the landing page's
/// content security policy.
pub(crate) async fn oauth_authorize(
    State(state): State<AppState>,
    peer: Peer,
    query: Result<Query<OAuthAuthorizeQuery>, QueryRejection>,
    headers: HeaderMap,
) -> Response {
    landing_headers(authorize_answer(&state, peer, query, &headers))
}

/// `response`, uncached and under the landing page's content security
/// policy, as every answer from the two sign-in routes is, a redirect too.
fn landing_headers(mut response: Response) -> Response {
    let answered = response.headers_mut();
    answered.insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
    answered.insert(
        header::CONTENT_SECURITY_POLICY,
        HeaderValue::from_static(didbot_brand::page::content_security_policy()),
    );
    response
}

/// Everything [`oauth_authorize`] answers, before the header every answer
/// carries.
fn authorize_answer(
    state: &AppState,
    peer: Peer,
    query: Result<Query<OAuthAuthorizeQuery>, QueryRejection>,
    headers: &HeaderMap,
) -> Response {
    use crate::oauth::authorize::{answer, AuthorizeAnswer, Loader};
    use crate::oauth::error::OAuthErrorCode;

    let Query(query) = match query {
        Ok(query) => query,
        Err(rejection) => {
            let refused = ApiError::bad_request(rejection.body_text());
            crate::refusal::refused(crate::refusal::Refusal {
                endpoint: "authorize",
                client_id: None,
                account: None,
                error: refused.error(),
                reason: refused.message(),
                severity: Severity::Info,
            });
            return landing::refused(
                StatusCode::BAD_REQUEST,
                landing::AUTHORIZE,
                "invalid_request",
                "this sign-in link is incomplete",
                "",
                "Start the sign-in again from the app.",
            );
        }
    };
    // Every refusal is written to the journal and answered with a page.
    let refuse = |refused: Refused, page: Response| {
        refused.write("authorize", Some(&query.client_id), None);
        page
    };

    let key = caller_key(headers, peer.0, state.trust_forwarded_headers);
    if !state.oauth.authorize_rate_limiter.check(&key) {
        return refuse(
            Refused::info(too_many_oauth_requests("authorize")),
            landing::too_many(landing::AUTHORIZE),
        );
    }

    let browser = crate::oauth::browser::presented(headers)
        .and_then(|cookie| state.oauth.browser_sessions.browser(&cookie));
    let loader = Loader {
        accounts: browser
            .as_ref()
            .map(|browser| browser.accounts.clone())
            .unwrap_or_default(),
        navigation: headers
            .get("sec-fetch-dest")
            .is_none_or(|dest| dest == "document"),
    };
    confirm_remembered(state, &query.request_uri, &query.client_id, &loader);
    let answered = match answer(
        state.oauth.par_store.as_ref(),
        state.oauth.decision_store.as_ref(),
        &query.request_uri,
        &query.client_id,
        &loader,
        time::OffsetDateTime::now_utc(),
    ) {
        Ok(answered) => answered,
        Err(err) => {
            return refuse(
                Refused::info(authorize_error(err.clone())),
                authorize_error_page(err),
            )
        }
    };
    // Read out of this deployment's own zone service document, never a
    // header; see `oauth::discovery::issuer_for`.
    let issuer = crate::oauth::discovery::issuer_for(state.registry.as_ref());
    let response = match (answered, issuer) {
        (AuthorizeAnswer::Redirect { to, account }, _) => {
            info!(
                account,
                "a browser signed in as the account collected its code"
            );
            see_other(&to, landing::AUTHORIZE)
        }
        (AuthorizeAnswer::Denied(denial), Ok(issuer)) => match denial.redirect(&issuer) {
            Ok(to) => see_other(to.as_str(), landing::AUTHORIZE),
            Err(err) => {
                let why = format!("the client's redirect is unusable: {err}");
                refuse(
                    Refused::warn(OAuthError::new(OAuthErrorCode::ServerError, why.clone())),
                    landing::server_error(landing::AUTHORIZE, &why),
                )
            }
        },
        (AuthorizeAnswer::Page(pending), Ok(issuer)) => {
            if pending.held {
                info!(
                    account = pending.record.account,
                    signed_in = pending.signed_in,
                    "an approved sign-in's code waits for a browser signed in as the account"
                );
            }
            let query = url::form_urlencoded::Serializer::new(String::new())
                .append_pair("client_id", &query.client_id)
                .append_pair("request_uri", &query.request_uri)
                .finish();
            let authorize_url = format!("{issuer}/oauth/authorize?{query}");
            let sign_in_url = format!("{issuer}{}", crate::oauth::browser::PATH);
            authorize_page(&pending, &authorize_url, &sign_in_url)
        }
        (_, Err(err)) => landing::server_error(landing::AUTHORIZE, &err.to_string()),
    };
    // A browser that presented an id its session has since replaced is
    // given the current one, whatever the page answered.
    match browser.filter(|browser| browser.replaced) {
        Some(browser) => with_browser_cookie(response, &browser, landing::AUTHORIZE),
        None => response,
    }
}

/// `GET /oauth/browser`'s query parameters.
#[derive(serde::Deserialize)]
pub(crate) struct OAuthBrowserQuery {
    /// A ticket from `bot.did.createBrowserSignIn`.
    ticket: Option<String>,
}

/// `GET /oauth/browser`
///
/// With a `ticket`, spends it and signs this browser in as the account it
/// was minted for, then answers `303 See Other` to this page with
/// [`crate::oauth::browser::COOKIE`] set. Without one, lists the accounts
/// this browser is signed in as. See `crate::oauth::browser`.
///
/// Served on the issuer's host alone (`crate::oauth::discovery::issuer_for`),
/// so no cookie is set on an agent's own host. A ticket is refused, and left
/// as it was, when `Sec-Fetch-Site` says the link was followed from another
/// site, so a link planted on another page cannot sign a browser in, and
/// while the e-stop is engaged. The request span carries the path alone, so
/// a ticket is never logged.
///
/// Every answer carries `Cache-Control: no-store` and the landing page's
/// content security policy.
pub(crate) async fn oauth_browser(
    State(state): State<AppState>,
    uri: axum::http::Uri,
    query: Result<Query<OAuthBrowserQuery>, QueryRejection>,
    headers: HeaderMap,
) -> Response {
    landing_headers(browser_answer(&state, &uri, query, &headers))
}

/// Everything [`oauth_browser`] answers, before the headers every answer
/// carries.
fn browser_answer(
    state: &AppState,
    uri: &axum::http::Uri,
    query: Result<Query<OAuthBrowserQuery>, QueryRejection>,
    headers: &HeaderMap,
) -> Response {
    use crate::oauth::browser::PATH;

    const NEW_LINK: &str = "Ask the account for a new sign-in link.";
    let Query(query) = match query {
        Ok(query) => query,
        Err(_) => {
            return landing::refused(
                StatusCode::BAD_REQUEST,
                landing::BROWSER,
                "InvalidRequest",
                "this sign-in link is malformed",
                "",
                NEW_LINK,
            )
        }
    };
    let issuer = match crate::oauth::discovery::issuer_for(state.registry.as_ref()) {
        Ok(issuer) => issuer,
        Err(err) => return landing::server_error(landing::BROWSER, &err.to_string()),
    };
    if !on_issuer_host(&issuer, uri, headers) {
        let here = escape(&format!("{issuer}{PATH}"));
        return landing::refused(
            StatusCode::FORBIDDEN,
            landing::BROWSER,
            "WrongHost",
            "this is not this server's sign-in address",
            &format!(
                "<p data-refused=\"host\">This page is served only at \
                 <a href=\"{here}\">{here}</a>.</p>"
            ),
            "Open that address instead.",
        );
    }

    let sessions = &state.oauth.browser_sessions;
    let presented = crate::oauth::browser::presented(headers);
    let Some(ticket) = query.ticket else {
        return browser_list(presented.and_then(|cookie| sessions.browser(&cookie)));
    };
    if !followed_from_here(headers) {
        info!("refused a browser sign-in link followed from another site");
        return landing::refused(
            StatusCode::FORBIDDEN,
            landing::BROWSER,
            "CrossSite",
            "a sign-in link followed from another site is refused",
            "<p data-refused=\"cross-site\">The link still works, once.</p>",
            "Paste it into this browser's address bar.",
        );
    }
    if let Err(halted) = state.estop.check_issue(EstopRefusal::Token) {
        info!(%halted, "refused a browser sign-in while the e-stop is engaged");
        return landing::refused(
            StatusCode::SERVICE_UNAVAILABLE,
            landing::BROWSER,
            "Halted",
            "this server has stopped signing anything in",
            "",
            "Try again once this server's operator releases the stop.",
        );
    }
    let Some(signed_in) = sessions.redeem(&ticket, presented.as_deref()) else {
        return landing::refused(
            StatusCode::BAD_REQUEST,
            landing::BROWSER,
            "TicketNotLive",
            "this sign-in link is not live",
            "<p data-ticket=\"not-live\">It is unknown, used or expired.</p>",
            NEW_LINK,
        );
    };
    info!(account = signed_in.account, "a browser signed in");
    with_browser_cookie(
        see_other(PATH, landing::BROWSER),
        &signed_in.browser,
        landing::BROWSER,
    )
}

/// Whether a request was made to the issuer's own host, as its `Host` or its
/// HTTP/2 authority names it.
fn on_issuer_host(issuer: &str, uri: &axum::http::Uri, headers: &HeaderMap) -> bool {
    let Some(authority) = request_authority(uri, headers) else {
        return false;
    };
    let host = host_without_port(authority);
    url::Url::parse(issuer)
        .ok()
        .and_then(|issuer| issuer.host_str().map(str::to_owned))
        .is_some_and(|expected| expected.eq_ignore_ascii_case(host))
}

/// Whether `Sec-Fetch-Site` lets a sign-in link through: absent, `none` for
/// a link a person or a tool opened directly, or `same-origin`.
fn followed_from_here(headers: &HeaderMap) -> bool {
    headers
        .get("sec-fetch-site")
        .is_none_or(|site| matches!(site.to_str(), Ok("none" | "same-origin")))
}

/// The accounts a browser is signed in as, and the cookie again when it
/// presented an id its session has since replaced.
fn browser_list(browser: Option<crate::oauth::browser::Browser>) -> Response {
    let accounts = browser
        .as_ref()
        .map(|browser| browser.accounts.as_slice())
        .unwrap_or_default();
    let (status, tone, body) = if accounts.is_empty() {
        (
            "not signed in",
            Tone::Waiting,
            "<p data-accounts=\"0\">This browser is signed in as no account here.</p>\
             <p class=\"next\">Open a sign-in link from an account to sign it in.</p>"
                .to_owned(),
        )
    } else {
        let items: String = accounts
            .iter()
            .map(|account| {
                let account = escape(account);
                format!("<li data-account=\"{account}\">{account}</li>")
            })
            .collect();
        (
            "signed in",
            Tone::Done,
            format!(
                "<p data-accounts=\"{}\">This browser is signed in as:</p><ul>{items}</ul>\
                 <p class=\"next\">Go back to the sign-in that sent you here.</p>",
                accounts.len()
            ),
        )
    };
    let page = landing::page(
        StatusCode::OK,
        &Landing {
            placeholder: landing::BROWSER,
            tone,
            status,
            body: &body,
            reload: None,
        },
    );
    match browser.filter(|browser| browser.replaced) {
        Some(browser) => with_browser_cookie(page, &browser, landing::BROWSER),
        None => page,
    }
}

/// `response`, setting [`crate::oauth::browser::COOKIE`] to `browser`'s
/// current session id. `placeholder` heads the page if it cannot.
fn with_browser_cookie(
    mut response: Response,
    browser: &crate::oauth::browser::Browser,
    placeholder: &str,
) -> Response {
    match HeaderValue::try_from(crate::oauth::browser::cookie(browser)) {
        Ok(cookie) => {
            response.headers_mut().append(header::SET_COOKIE, cookie);
            response
        }
        Err(_) => landing::server_error(placeholder, "a browser session id is not a header value"),
    }
}

/// `303 See Other` to `location`, which a browser follows with a `GET`
/// whatever method brought it here. `placeholder` heads the page if it
/// cannot.
fn see_other(location: &str, placeholder: &str) -> Response {
    match HeaderValue::from_str(location) {
        Ok(location) => (StatusCode::SEE_OTHER, [(header::LOCATION, location)]).into_response(),
        Err(_) => landing::server_error(placeholder, "the client's redirect is not a header value"),
    }
}

/// The wire fields `POST /oauth/token` accepts, form-encoded per RFC 6749
/// §4.
#[derive(serde::Deserialize)]
pub(crate) struct OAuthTokenForm {
    grant_type: String,
    code: Option<String>,
    redirect_uri: Option<String>,
    code_verifier: Option<String>,
    client_id: Option<String>,
    refresh_token: Option<String>,
    client_assertion_type: Option<String>,
    client_assertion: Option<String>,
}

/// Marks every answer from `POST /oauth/par` and `POST /oauth/token`
/// uncacheable, success and refusal alike.
///
/// RFC 6749 §5.1 has an authorization server send `Cache-Control: no-store`
/// and `Pragma: no-cache` on any response containing tokens, credentials or
/// other sensitive information. The reference provider sends both on every
/// answer from these endpoints, as this does.
pub(crate) async fn never_cached(
    request: axum::extract::Request,
    next: axum::middleware::Next,
) -> Response {
    let mut response = next.run(request).await;
    let headers = response.headers_mut();
    headers.insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
    headers.insert(header::PRAGMA, HeaderValue::from_static("no-cache"));
    response
}

/// The DPoP proof a request to this authorization server carries, checked
/// against the absolute URL of `path` on this deployment.
///
/// A client answers a nonce challenge by sending the same body again with a
/// new proof, so this runs before anything the body names is fetched or
/// spent: the client's document, its assertion, a code, a refresh token. The
/// reference provider checks in the same order. The proof's `jti` is read
/// here and not spent; see `crate::oauth::dpop`.
fn checked_proof(
    state: &AppState,
    headers: &HeaderMap,
    path: &str,
) -> Result<crate::oauth::dpop_seam::VerifiedProof, crate::oauth::error::OAuthError> {
    use crate::oauth::dpop_seam::DpopError;
    use crate::oauth::error::{OAuthError, OAuthErrorCode};

    let proof = match crate::oauth::dpop::presented_proof(headers) {
        Ok(Some(proof)) => proof,
        Ok(None) => {
            return Err(OAuthError::new(
                OAuthErrorCode::InvalidDpopProof,
                "this request carries no DPoP proof",
            ))
        }
        Err(err) => {
            return Err(OAuthError::new(
                OAuthErrorCode::InvalidDpopProof,
                err.to_string(),
            ))
        }
    };
    // The absolute URL a conformant client's proof signs, read out of this
    // deployment's own zone service document and never out of `Host` or an
    // `X-Forwarded-*` header; see `oauth::discovery::request_htu`.
    let htu = crate::oauth::discovery::request_htu(state.registry.as_ref(), path)
        .map_err(|err| OAuthError::new(OAuthErrorCode::ServerError, err.to_string()))?;
    // RFC 9449 §8's `use_dpop_nonce` for a proof that carries no nonce this
    // server accepts, and §5's `invalid_dpop_proof` for any other refusal.
    state
        .oauth
        .dpop
        .verify(proof, "POST", &htu, None)
        .map_err(|err| match err {
            DpopError::UseNonce { nonce, message } => {
                OAuthError::new(OAuthErrorCode::UseDpopNonce, message).with_dpop_nonce(nonce)
            }
            err => OAuthError::new(OAuthErrorCode::InvalidDpopProof, err.to_string()),
        })
}

pub(crate) fn oauth_token_response(tokens: crate::oauth::token::OAuthTokens) -> Response {
    let expires_in = (tokens.access_expires_at - time::OffsetDateTime::now_utc())
        .whole_seconds()
        .max(0);
    Json(json!({
        // `DPoP`, not `Bearer`: this deployment's tokens slot into
        // `crate::auth`'s existing credential taxonomy rather than a scheme
        // of this module's own invention; see `crate::oauth::token`'s doc.
        "token_type": "DPoP",
        "access_token": tokens.access_token,
        "expires_in": expires_in,
        "refresh_token": tokens.refresh_token,
        "scope": tokens.scope.to_string(),
        "sub": tokens.did,
    }))
    .into_response()
}

/// What a refused exchange or refresh answers, and how loudly it is
/// written.
///
/// `warn` is a presentation that looks like a stolen credential (a refresh
/// token used twice, a proof under another key), a client whose
/// authentication no longer matches its metadata, and a grant this server
/// could not keep. The rest is ordinary expiry, a caller's mistake, or this
/// server's policy, at `info`.
pub(crate) fn token_refusal(err: crate::oauth::token::TokenError) -> Refused {
    use crate::oauth::error::OAuthErrorCode;
    use crate::oauth::token::TokenError;
    let code = match err {
        TokenError::UnsupportedGrantType(_) => OAuthErrorCode::UnsupportedGrantType,
        TokenError::MissingParameter(_) => OAuthErrorCode::InvalidRequest,
        TokenError::InvalidCode
        | TokenError::InvalidRefreshToken
        | TokenError::RefreshReused
        | TokenError::DpopKeyMismatch
        | TokenError::RedirectUriMismatch
        | TokenError::PkceFailed
        | TokenError::ClientMismatch
        | TokenError::ClientAuthenticationChanged
        | TokenError::ClientRefused => OAuthErrorCode::InvalidGrant,
        TokenError::ClientAssertionRequired => OAuthErrorCode::InvalidClient,
        TokenError::Dpop(_) | TokenError::CodeKeyMismatch => OAuthErrorCode::InvalidDpopProof,
        TokenError::NotKept => OAuthErrorCode::ServerError,
    };
    let error = OAuthError::new(code, err.to_string());
    match err {
        TokenError::RefreshReused
        | TokenError::DpopKeyMismatch
        | TokenError::CodeKeyMismatch
        | TokenError::ClientAuthenticationChanged
        | TokenError::ClientAssertionRequired
        | TokenError::NotKept => Refused::warn(error),
        _ => Refused::info(error),
    }
}

/// How long `bot.did.listPendingAuthorizations` will hold a request open.
///
/// The daemon polls with `wait=25`, one poll per account it holds a token
/// for, and this is the ceiling it is clamped to. Long enough that a poll
/// loop is cheap and short enough to stay well inside any intermediary's own
/// idle timeout.
pub const MAX_AUTHORIZATION_WAIT: u64 = 30;

/// `GET /xrpc/bot.did.listPendingAuthorizations`'s query parameters.
#[derive(serde::Deserialize)]
pub(crate) struct ListPendingAuthorizationsQuery {
    /// Where the caller got to last time. Opaque on the wire, and safe to
    /// keep across a restart: a cursor this server did not mint is read as
    /// the beginning rather than as a place it has not reached. See
    /// `crate::oauth::decision::Cursor`.
    cursor: Option<String>,
    /// How many seconds to hold the request open for if there is nothing
    /// newer, clamped to [`MAX_AUTHORIZATION_WAIT`].
    wait: Option<u64>,
}

/// `GET /xrpc/bot.did.getAuthorization`'s query parameters.
#[derive(serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub(crate) struct GetAuthorizationQuery {
    /// The pushed request whose decision to read.
    request_uri: String,
}

/// `GET /xrpc/bot.did.listPendingAuthorizations`
///
/// `Credential::AccountSelf`, used as identity rather than as a comparison:
/// this route names no account, and the decisions it lists are the ones
/// addressed to the account the presented agent token authenticates as. An
/// agent cannot ask for anybody else's, because there is nowhere in the
/// request to ask.
///
/// Long-polls. It answers at once when this account has a live decision
/// newer than `cursor`, and otherwise holds the request open for up to
/// `wait` seconds waiting for one — which is what lets the daemon learn of a
/// decision without polling in a tight loop. Records that were approved,
/// declined, or whose pushed request expired are not returned; the cursor
/// still advances past them, so a caller that keeps sending back what it was
/// given never re-reads a decision it has already seen.
pub(crate) async fn list_pending_authorizations(
    State(state): State<AppState>,
    headers: HeaderMap,
    query: Result<Query<ListPendingAuthorizationsQuery>, QueryRejection>,
) -> Response {
    let Query(query) = match query {
        Ok(query) => query,
        Err(rejection) => return ApiError::bad_request(rejection.body_text()).into_response(),
    };
    let did = match auth::require_agent_token(state.registry.as_ref(), &headers) {
        Ok(did) => did,
        Err(err) => return err.into_response(),
    };
    let cursor = query.cursor.as_deref();
    let wait = std::time::Duration::from_secs(query.wait.unwrap_or(0).min(MAX_AUTHORIZATION_WAIT));

    let deadline = tokio::time::Instant::now() + wait;
    let arrivals = state.oauth.decision_store.arrivals();
    let shutdown = state.oauth.shutdown.clone();
    loop {
        // Subscribe before reading, so a record that arrives between the
        // read and the wait wakes this rather than being missed until the
        // deadline. A stop that came first resolves `stopping` at once: an
        // HTTP/2 client can still send a poll after the stop began, and one
        // parked then holds the listener closed for all of `drain_secs`.
        let notified = arrivals.notified();
        let stopping = shutdown.clone().wait();
        let (pending, next) = state.oauth.decision_store.pending_for(&did, cursor);
        if !pending.is_empty() || tokio::time::Instant::now() >= deadline {
            return pending_authorizations(&pending, &next);
        }
        let waited = tokio::select! {
            () = notified => true,
            () = stopping => false,
            () = tokio::time::sleep_until(deadline) => false,
        };
        if !waited {
            let (pending, next) = state.oauth.decision_store.pending_for(&did, cursor);
            return pending_authorizations(&pending, &next);
        }
    }
}

/// The one answer shape `bot.did.listPendingAuthorizations` has, built in
/// one place so the wait's three exits cannot drift apart.
pub(crate) fn pending_authorizations(
    pending: &[crate::oauth::decision::DecisionRecord],
    next: &str,
) -> Response {
    let pending: Vec<serde_json::Value> = pending
        .iter()
        .map(crate::oauth::decision::DecisionRecord::to_json)
        .collect();
    Json(json!({ "cursor": next, "pending": pending })).into_response()
}

/// `GET /xrpc/bot.did.getAuthorization`
///
/// One decision by the pushed request it decides. `Credential::AccountSelf`:
/// answered only when the decision is addressed to the account the presented
/// token authenticates as, and answered as "not found" otherwise, so this is
/// not a way to learn that somebody else has a sign-in in flight.
pub(crate) async fn get_authorization(
    State(state): State<AppState>,
    headers: HeaderMap,
    query: Result<Query<GetAuthorizationQuery>, QueryRejection>,
) -> Response {
    let Query(query) = match query {
        Ok(query) => query,
        Err(rejection) => return ApiError::bad_request(rejection.body_text()).into_response(),
    };
    let did = match auth::require_agent_token(state.registry.as_ref(), &headers) {
        Ok(did) => did,
        Err(err) => return err.into_response(),
    };
    match state.oauth.decision_store.get(&query.request_uri) {
        Some(record) if record.account == did => Json(record.to_json()).into_response(),
        _ => ApiError::new(
            StatusCode::NOT_FOUND,
            "AuthorizationNotFound",
            "no authorization request of yours answers to that request_uri",
        )
        .into_response(),
    }
}

/// Reads one decision by its approval token, for the account the presented
/// credential authenticates as.
///
/// The account check is here rather than in a request field: an agent
/// approving cannot name the account it is approving for, so naming somebody
/// else's is not a thing the wire allows. A token that names a decision
/// addressed to another account is answered exactly as an unknown token is,
/// so a caller holding a stolen token learns nothing from the refusal.
pub(crate) fn decision_by_token(
    state: &AppState,
    did: &str,
    token: &str,
) -> Result<crate::oauth::decision::DecisionRecord, ApiError> {
    let unknown =
        || ApiError::bad_request("this approval token is unknown, already used, or expired");
    let record = state
        .oauth
        .decision_store
        .by_token(token)
        .ok_or_else(unknown)?;
    if record.account != did {
        return Err(unknown());
    }
    if !record.is_live(time::OffsetDateTime::now_utc()) {
        return Err(unknown());
    }
    Ok(record)
}

/// `POST /xrpc/bot.did.approveAuthorization`
///
/// The one way an authorization is approved. `Credential::AccountSelf`: the
/// agent presents its own token, and the decision it approves must be the
/// one addressed to that account — `plan/oauth.md`'s "the account is
/// checked server-side, not by the daemon", enforced by the credential
/// rather than by a DID in the body a caller could write anything into.
///
/// Answers with the client's redirect, built here from the pending
/// consent's own `redirect_uri` and `state` and the pushed request's
/// `response_mode` — which is the whole of what an approving caller is not
/// allowed to see — and this server's issuer. A loopback redirect carrying
/// its code in the query is the caller's to deliver, because this server
/// cannot reach the host the client listens on. A browser carries any other
/// ([`crate::oauth::authorize::browser_carries`]): the approval holds it for
/// `GET /oauth/authorize` to hand to a browser signed in as the account.
///
/// Answers with the scope the decision record granted, which is what the
/// code carries: a token is issued at that set as the ceiling grants it at
/// exchange, and judged the same way at every use after.
///
/// The approval is remembered for the account and the client's
/// [`crate::oauth::client_metadata::ClientKey`], at this grant; see
/// [`crate::oauth::decision::DecisionStore::remember`].
///
/// Nothing is evaluated here. The record PAR wrote is read, and a policy
/// loaded since that push does not reach back into it — see
/// `crate::oauth::par`.
pub(crate) async fn approve_authorization(
    State(state): State<AppState>,
    headers: HeaderMap,
    XrpcBody(body): XrpcBody,
) -> Response {
    if let Err(halted) = state.estop.check_issue(EstopRefusal::Token) {
        return ApiError::from(halted).into_response();
    }
    let request: crate::wire::ApproveAuthorizationRequest = match parse_body(&body) {
        Ok(request) => request,
        Err(err) => return err.into_response(),
    };
    let did = match auth::require_agent_token(state.registry.as_ref(), &headers) {
        Ok(did) => did,
        Err(err) => return err.into_response(),
    };
    let record = match decision_by_token(&state, &did, &request.token) {
        Ok(record) => record,
        Err(err) => return err.into_response(),
    };
    if let crate::oauth::decision::Verdict::Deny { reason, rule } = &record.verdict {
        info!(account = did, rule, "approval refused: the decision denies");
        return ApiError::bad_request(format!(
            "this authorization request was refused by `{rule}`: {reason}"
        ))
        .into_response();
    }
    let issued = match issue_approval(&state, &did, &record, request.token) {
        Ok(issued) => issued,
        Err(err) => return err.into_response(),
    };
    state.oauth.decision_store.remember(
        &did,
        &record.client_key,
        &issued.client_id,
        issued.granted.clone(),
        time::OffsetDateTime::now_utc(),
    );
    if issued.browser {
        info!(
            account = did,
            "approved; a browser signed in as the account collects the code"
        );
    } else {
        info!(account = did, "approved; the caller delivers the code");
    }

    Json(json!({
        "requestUri": record.request_uri,
        "granted": issued.granted.0.iter().map(ToString::to_string).collect::<Vec<_>>(),
        "redirect": issued.redirect.as_str(),
    }))
    .into_response()
}

/// What [`issue_approval`] issued.
struct Issued {
    /// The client the approval is for.
    client_id: String,
    /// What the code carries.
    granted: crate::oauth::scope::ScopeSet,
    /// The client's redirect, carrying the code.
    redirect: url::Url,
    /// Whether a browser carries the code, so the record holds `redirect`
    /// for a browser signed in as the account.
    browser: bool,
}

/// Approves `record` for `did` by spending `token`: issues the code, builds
/// the client's redirect, and settles the record, holding the redirect when
/// a browser carries it.
///
/// What `bot.did.approveAuthorization` does once it knows the caller, and
/// what `GET /oauth/authorize` does for a sign-in the account's remembered
/// approval confirms. The e-stop is the caller's to check.
fn issue_approval(
    state: &AppState,
    did: &str,
    record: &crate::oauth::decision::DecisionRecord,
    token: String,
) -> Result<Issued, ApiError> {
    // Read before anything is spent, so a server that cannot name itself
    // refuses the approval rather than using the decision up.
    let issuer = crate::oauth::discovery::issuer_for(state.registry.as_ref()).map_err(|err| {
        ApiError::new(
            StatusCode::INTERNAL_SERVER_ERROR,
            "ServerError",
            err.to_string(),
        )
    })?;

    let Some(pushed) = state.oauth.par_store.get(&record.request_uri) else {
        return Err(ApiError::bad_request(
            "this authorization request is not live",
        ));
    };

    // Spending the reference is what makes an approval single-use: a second
    // call finds nothing to confirm.
    let reference = crate::oauth::consent::ConsentReference(token);
    let pending =
        crate::oauth::consent::confirm(state.oauth.consent_store.as_ref(), &reference, did)
            .map_err(|err| {
                info!(account = did, error = %err, "consent refused");
                ApiError::bad_request(err.to_string())
            })?;

    let granted = record.granted();
    let redirect_uri = pending.redirect_uri.clone();
    let state_param = pending.state.clone();
    let code = state.oauth.code_store.issue(pending.into());
    // `redeem` takes a code out of the store, so a code that cannot reach
    // its client is never exchanged.
    let redirect = match crate::oauth::authorize::authorization_response(
        &redirect_uri,
        pushed.response_mode,
        &[("code", &code)],
        state_param.as_deref(),
        &issuer,
    ) {
        Ok(redirect) => redirect,
        Err(err) => {
            state.oauth.code_store.redeem(&code);
            return Err(ApiError::bad_request(format!(
                "the client's redirect is unusable: {err}"
            )));
        }
    };
    let browser =
        crate::oauth::authorize::browser_carries(&pushed.redirect_uri, pushed.response_mode);
    // Settled together with the redirect it holds for a browser, so no load
    // of the page finds this approval without it. A decline or an expiry
    // that reached the record first leaves nothing to settle.
    if state
        .oauth
        .decision_store
        .approve(&record.request_uri, browser.then(|| redirect.to_string()))
        .is_none()
    {
        state.oauth.code_store.redeem(&code);
        return Err(ApiError::bad_request(
            "this authorization request has already been answered",
        ));
    }
    Ok(Issued {
        client_id: pushed.client_id,
        granted,
        redirect,
        browser,
    })
}

/// Approves the sign-in `request_uri` names without asking the account, when
/// this load meets every rule of
/// [`crate::oauth::authorize::confirms_unasked`] and the e-stop is clear.
/// [`crate::oauth::authorize::answer`] then hands this browser the code.
///
/// The remembered approval is left as it was, so a confirmation never
/// renews it.
fn confirm_remembered(
    state: &AppState,
    request_uri: &str,
    client_id: &str,
    loader: &crate::oauth::authorize::Loader,
) {
    let now = time::OffsetDateTime::now_utc();
    let (Some(pushed), Some(record)) = (
        state.oauth.par_store.get(request_uri),
        state.oauth.decision_store.get(request_uri),
    ) else {
        return;
    };
    if pushed.client_id != client_id {
        return;
    }
    let remembered =
        state
            .oauth
            .decision_store
            .remembered(&record.account, &record.client_key, now);
    if !crate::oauth::authorize::confirms_unasked(
        &pushed,
        &record,
        remembered.as_ref(),
        loader,
        now,
    ) {
        return;
    }
    // Logged and counted by the e-stop itself. The page waits, as it does
    // for any sign-in the account has not answered.
    if state.estop.check_issue(EstopRefusal::Token).is_err() {
        return;
    }
    let Some(token) = record.token.clone() else {
        return;
    };
    match issue_approval(state, &record.account, &record, token.0) {
        Ok(_) => info!(
            account = record.account,
            client = pushed.client_id,
            "confirmed a sign-in on the account's remembered approval"
        ),
        Err(err) => info!(
            account = record.account,
            client = pushed.client_id,
            error = err.message(),
            "a remembered approval did not confirm a sign-in"
        ),
    }
}

/// `POST /xrpc/bot.did.createBrowserSignIn`
///
/// Mints a ticket that signs a browser in as the account, and answers with
/// the link that spends it, on the issuer's host, and when it stops being
/// live. See `crate::oauth::browser`.
///
/// `Credential::AccountSelf`, used as identity: the ticket is the account's
/// the presented agent token authenticates as, and it replaces any ticket
/// that account already had. Refused while the e-stop is engaged, with
/// nothing stored. The ticket is never logged.
pub(crate) async fn create_browser_sign_in(
    State(state): State<AppState>,
    headers: HeaderMap,
) -> Response {
    if let Err(halted) = state.estop.check_issue(EstopRefusal::Token) {
        return ApiError::from(halted).into_response();
    }
    let did = match auth::require_agent_token(state.registry.as_ref(), &headers) {
        Ok(did) => did,
        Err(err) => return err.into_response(),
    };
    let issuer = match crate::oauth::discovery::issuer_for(state.registry.as_ref()) {
        Ok(issuer) => issuer,
        Err(err) => {
            return ApiError::new(
                StatusCode::INTERNAL_SERVER_ERROR,
                "ServerError",
                err.to_string(),
            )
            .into_response()
        }
    };
    let minted = state.oauth.browser_sessions.mint(&did);
    info!(account = did, "minted a browser sign-in link");
    Json(json!({
        "url": format!("{issuer}{}?ticket={}", crate::oauth::browser::PATH, minted.ticket),
        "expiresAt": didbot_schema::format::datetime::render(minted.expires_at),
    }))
    .into_response()
}

/// `POST /xrpc/bot.did.declineAuthorization`
///
/// An agent's "no", recorded rather than left to look like an expiry.
/// `Credential::AccountSelf`, the same posture as [`approve_authorization`].
/// The approval token is spent either way, so a declined request cannot be
/// approved afterwards.
pub(crate) async fn decline_authorization(
    State(state): State<AppState>,
    headers: HeaderMap,
    XrpcBody(body): XrpcBody,
) -> Response {
    let request: crate::wire::DeclineAuthorizationRequest = match parse_body(&body) {
        Ok(request) => request,
        Err(err) => return err.into_response(),
    };
    let did = match auth::require_agent_token(state.registry.as_ref(), &headers) {
        Ok(did) => did,
        Err(err) => return err.into_response(),
    };
    let record = match decision_by_token(&state, &did, &request.token) {
        Ok(record) => record,
        Err(err) => return err.into_response(),
    };
    if state
        .oauth
        .decision_store
        .settle(
            &record.request_uri,
            crate::oauth::decision::DecisionState::Declined,
        )
        .is_none()
    {
        return ApiError::bad_request("this authorization request has already been answered")
            .into_response();
    }
    // Spend the reference too, so nothing can approve what was declined.
    state
        .oauth
        .consent_store
        .consume(&crate::oauth::consent::ConsentReference(request.token));
    info!(
        account = did,
        reason = request.reason.as_deref().unwrap_or(""),
        "authorization declined"
    );
    Json(json!({ "requestUri": record.request_uri })).into_response()
}

/// The confidential client a `POST /oauth/token` request authenticated as,
/// or `None` when it carries no client assertion.
///
/// A request with no assertion fetches nothing. Whether its code or refresh
/// token needed one is the grant's to say; see `crate::oauth::token`. One
/// with an assertion is checked against the key set its client publishes
/// now, read with its metadata document.
async fn authenticated_client(
    state: &AppState,
    client_id: Option<&str>,
    credentials: &crate::oauth::client_auth::ClientCredentials,
) -> Result<Option<crate::oauth::client_auth::AuthenticatedClient>, Refused> {
    use crate::oauth::error::OAuthErrorCode;

    if credentials.is_empty() {
        return Ok(None);
    }
    let Some(client_id) = client_id else {
        return Err(Refused::info(OAuthError::new(
            OAuthErrorCode::InvalidRequest,
            "a client_assertion needs the client_id it authenticates",
        )));
    };
    // The one spelling PAR takes, checked before anything is fetched, as PAR
    // checks it.
    if let Err(error) = didbot_pds::policy::ClientId::parse(client_id) {
        return Err(Refused::info(OAuthError::new(
            OAuthErrorCode::InvalidClient,
            error.to_string(),
        )));
    }
    let issuer = crate::oauth::discovery::issuer_for(state.registry.as_ref()).map_err(|err| {
        Refused::warn(OAuthError::new(
            OAuthErrorCode::ServerError,
            err.to_string(),
        ))
    })?;
    let (document, _) = crate::oauth::client_metadata::resolve_client(
        &state.oauth.http,
        state.oauth.client_cache.as_ref(),
        client_id,
        crate::oauth::client_metadata::LoopbackClients::for_zone(state.registry.zone()),
    )
    .await
    .map_err(|error| {
        // The caller gets the one sentence PAR answers with, which names
        // nothing the fetch found (see `ParError::ClientMetadata`). The
        // journal gets the cause.
        Refused::warn(OAuthError::new(
            OAuthErrorCode::InvalidClient,
            crate::oauth::par::ParError::ClientMetadata(error.clone()).to_string(),
        ))
        .because(error)
    })?;
    let key = state
        .oauth
        .client_assertions
        .authenticate(&document, credentials, &issuer)
        .map_err(|error| Refused::warn(OAuthError::new(error.code(), error.to_string())))?;
    Ok(
        key.map(|key| crate::oauth::client_auth::AuthenticatedClient {
            client_id: client_id.to_owned(),
            key,
        }),
    )
}

/// `POST /oauth/token`
///
/// `authorization_code` exchange and `refresh_token` rotation, both DPoP
/// bound. Every exchange and every refresh runs through
/// `crate::oauth::dpop_seam::DpopVerifier`, which [`crate::oauth::OAuthState::default`]
/// wires to the real RFC 9449 verifier — see `crate::oauth::dpop`. The proof
/// is checked before the client or the grant; see [`checked_proof`].
///
/// A confidential client authenticates each one with a client assertion,
/// checked by [`authenticated_client`] before either grant runs.
///
/// Both are judged by policy before a token is issued; see
/// `crate::oauth::token::GateAdmission`.
pub(crate) async fn oauth_token(
    State(state): State<AppState>,
    peer: Peer,
    headers: HeaderMap,
    axum::Form(form): axum::Form<OAuthTokenForm>,
) -> Response {
    use crate::oauth::error::OAuthErrorCode;

    let client_id = form.client_id.clone();
    let refuse = |refused: Refused| refused.answer("token", client_id.as_deref(), None);

    if let Err(halted) = state.estop.check_issue(EstopRefusal::Token) {
        let refused = ApiError::from(halted);
        crate::refusal::refused(crate::refusal::Refusal {
            endpoint: "token",
            client_id: client_id.as_deref(),
            account: None,
            error: refused.error(),
            reason: refused.message(),
            severity: Severity::Info,
        });
        return refused.into_response();
    }

    // Before the DPoP proof is verified: the proof is checked before the
    // credential in the body, so a caller with a fresh key spends an ECDSA
    // check per call while holding no credential at all.
    let key = caller_key(&headers, peer.0, state.trust_forwarded_headers);
    if !state.oauth.token_rate_limiter.check(&key) {
        return refuse(Refused::info(too_many_oauth_requests("token")));
    }

    let proof = match checked_proof(&state, &headers, "/oauth/token") {
        Ok(proof) => proof,
        Err(refused) => return refuse(Refused::info(refused)),
    };

    let pds_did = deployment_did(&state);
    let pds_hostname = state.registry.zone().to_owned();
    let admission = crate::oauth::token::GateAdmission {
        gate: state.oauth.grant_gate.as_ref(),
        registry: state.registry.as_ref(),
        pds_did: &pds_did,
        pds_hostname: &pds_hostname,
    };

    let credentials = crate::oauth::client_auth::ClientCredentials {
        assertion_type: form.client_assertion_type,
        assertion: form.client_assertion,
    };
    let client = match authenticated_client(&state, form.client_id.as_deref(), &credentials).await {
        Ok(client) => client,
        Err(refused) => return refuse(refused),
    };

    match form.grant_type.as_str() {
        "authorization_code" => {
            let (Some(code), Some(redirect_uri), Some(code_verifier), Some(client_id)) = (
                form.code,
                form.redirect_uri,
                form.code_verifier,
                form.client_id,
            ) else {
                return refuse(Refused::info(OAuthError::new(
                    OAuthErrorCode::InvalidRequest,
                    "authorization_code grant needs code, redirect_uri, code_verifier, and client_id",
                )));
            };
            match state.oauth.tokens.exchange_code(
                state.oauth.code_store.as_ref(),
                state.oauth.dpop.as_ref(),
                &admission,
                state.oauth.scope_policy.as_ref(),
                &code,
                &redirect_uri,
                &code_verifier,
                &client_id,
                client.as_ref(),
                &proof,
            ) {
                Ok(tokens) => oauth_token_response(tokens),
                Err(err) => refuse(token_refusal(err)),
            }
        }
        "refresh_token" => {
            let Some(refresh_token) = form.refresh_token else {
                return refuse(Refused::info(OAuthError::new(
                    OAuthErrorCode::InvalidRequest,
                    "refresh_token grant needs refresh_token",
                )));
            };
            match state.oauth.tokens.refresh(
                state.oauth.dpop.as_ref(),
                &admission,
                state.oauth.scope_policy.as_ref(),
                &refresh_token,
                client.as_ref(),
                &proof,
            ) {
                Ok(tokens) => oauth_token_response(tokens),
                Err(err) => refuse(token_refusal(err)),
            }
        }
        other => refuse(Refused::info(OAuthError::new(
            OAuthErrorCode::UnsupportedGrantType,
            format!("grant_type `{other}` is not supported"),
        ))),
    }
}