didbot_serve/oauth/

authorize.rs

//! `GET /oauth/authorize`, the authorization response, and the ceiling.
//!
//! **Nothing is decided here.** This module reads a pushed authorization
//! request and the decision [`crate::oauth::par`] already minted for it. A
//! policy edited between the push and this call does not reach back into
//! that record — it applies to the next push, which is
//! `plan/app-allowlist.md`'s "de-admission is a rule change, not session
//! invalidation".
//!
//! # The page waits for the account
//!
//! A browser that loads the page before the account has answered gets a page
//! that reloads itself every [`RELOAD_INTERVAL`]. Once the account approves a
//! sign-in whose code a browser carries ([`browser_carries`]), the page
//! hands the code to a browser signed in as the account
//! (`crate::oauth::browser`), on a top-level navigation, once. Any other
//! browser keeps getting the page until the request expires. A decline, a
//! verdict that grants nothing, or an expiry sends the browser back to the
//! client with `access_denied`. See [`answer`] for what each load gets.
//!
//! A browser signed in as the account can also confirm a sign-in the
//! account's remembered approval covers, without asking the account
//! ([`confirms_unasked`]). The route approves it as
//! `bot.did.approveAuthorization` would before [`answer`] reads the record.
//!
//! # The ceiling is not policy
//!
//! [`ScopePolicy`] is the one narrowing mechanism left beside the tree, and
//! calling it a policy overstates it. It is the **deployment's** statement of
//! the most any agent here may ever hold, applied by intersection with what
//! the client asked for. It is applied at PAR alongside the tree's denials,
//! and again at every token issue and every write. It cannot grant: [`ConfiguredCeiling::new`] keeps only the atoms
//! [`GrantAnyScope`]'s compiled-in ceiling already admits, so the widest a
//! configured ceiling can be is the compiled-in one and every step from
//! there subtracts. It is also blunt — one statement for every agent and
//! every client, because it is keyed on neither.
//!
//! Retiring it in favour of a rule in the tree has a precondition:
//! `didbot_policy::Subject::Grant` carries a `client_id` and the requested
//! scopes, and no account. A per-account ceiling is not expressible as a
//! policy until it does. See `plan/scope-policy.md`.

use time::OffsetDateTime;

use crate::oauth::decision::{DecisionRecord, DecisionState, DecisionStore, Remembered, Verdict};
use crate::oauth::par::{ParStore, PushedRequest};
use crate::oauth::scope::ScopeSet;

/// The ceiling. PAR applies it to write the verdict an agent reads, and
/// `POST /oauth/token` and every write apply it again to the login's whole
/// request ([`crate::oauth::token::in_force`]). An approval covers that
/// request, so what a login may do moves with the ceiling.
pub trait ScopePolicy: Send + Sync {
    /// The most this `did` may ever hold from `client_id`. A ceiling only
    /// ever shrinks from [`GrantAnyScope`]'s; an empty [`ScopeSet`] refuses
    /// every non-empty request. Both arguments are ignored by every
    /// implementation here — see the module doc.
    fn ceiling(&self, did: &str, client_id: &str) -> ScopeSet;
}

/// The compiled-in ceiling, and the widest one this binary has: every
/// implementation of [`ScopePolicy`] is a subset of it.
///
/// It is written with wildcards rather than computed, so what it admits is
/// legible: every collection, every method, and the base scope.
/// `transition:*`, `account` and `identity` are outside it — the
/// compiled-in denial `plan/scope-policy.md`'s hard-blocked list asks for.
#[derive(Debug, Clone, Copy, Default)]
pub struct GrantAnyScope;

/// What [`GrantAnyScope`] admits.
const EVERY_SCOPE: &str = "atproto repo:* rpc:* blob:*/*";

impl ScopePolicy for GrantAnyScope {
    fn ceiling(&self, _did: &str, _client_id: &str) -> ScopeSet {
        ScopeSet::parse(EVERY_SCOPE).expect("a constant this crate's own parser accepts")
    }
}

/// The ceiling an operator wrote down, applied to every agent and every
/// client alike.
///
/// `plan/scope-policy.md`'s "from server configuration first": an
/// enumeration of scope atoms, not a pattern, read out of
/// `didbot_config::sections::OAuthSection::scope_ceiling`. Per-agent and
/// per-client profiles are the operator's repository's to hold, and this
/// ignores both arguments until that exists.
///
/// A seam, not a destination. `plan/policy-store.md`'s ceiling — read from
/// policy records in the operator's repository, per agent and per client —
/// implements this same [`ScopePolicy`] trait and replaces this
/// implementation whole when it lands; nothing that calls a ceiling has to
/// change for it. What it needs first is an account on
/// `didbot_policy::Subject::Grant`, which is what a per-account rule would
/// have to match on.
///
/// **It can only narrow.** [`ConfiguredCeiling::new`] intersects what it was
/// given with [`GrantAnyScope`]'s own ceiling and keeps the overlap, so a
/// configured atom outside the compiled-in ceiling — anything in
/// `plan/scope-policy.md`'s hard-blocked set, or a `kind:` a later grammar
/// adds — grants nothing however it is spelled in the file. That is what
/// lets a scope live in a configuration file at all; see
/// `didbot_config`'s own crate doc.
#[derive(Debug, Clone)]
pub struct ConfiguredCeiling(ScopeSet);

/// What [`ConfiguredCeiling::new`] did not keep, and why — for the startup
/// line that reports it, since the two reasons ask different things of an
/// operator.
#[derive(Debug, Default, Clone, PartialEq, Eq)]
pub struct DroppedAtoms {
    /// Atoms the compiled-in ceiling does not admit whole, and atoms that
    /// did not parse. Rewriting them differently changes nothing: this build
    /// grants none of them however they are spelled.
    pub outside: Vec<String>,
    /// Atoms past [`crate::oauth::scope::MAX_SCOPE_ATOMS`]. The ceiling is
    /// the ones before them, so a shorter enumeration is a different
    /// ceiling.
    pub over_bound: Vec<String>,
}

impl DroppedAtoms {
    /// Whether every configured atom was kept.
    pub fn is_empty(&self) -> bool {
        self.outside.is_empty() && self.over_bound.is_empty()
    }
}

impl ConfiguredCeiling {
    /// Builds a ceiling from the atoms an operator enumerated, dropping
    /// every one the compiled-in ceiling does not already admit.
    ///
    /// An atom is kept only if the compiled-in ceiling admits it **whole**.
    /// A partial admission is dropped rather than kept at its projection:
    /// `transition:generic` overlaps `repo:* rpc:*`, and an operator who
    /// wrote a hard-blocked atom should get nothing for it rather than the
    /// slice of it that happens to fall inside. An atom that does not parse
    /// is dropped for the same reason — this runs at startup, and a ceiling
    /// that fails closed on the atoms it understood is the safe reading of a
    /// file it only half understands. The dropped atoms are returned so the
    /// caller can log them.
    ///
    /// **Bounded at [`crate::oauth::scope::MAX_SCOPE_ATOMS`].**
    /// [`ScopeSet::new`] compares every pair of atoms it is handed, and that
    /// constant is what bounds the comparison — which it does for
    /// [`ScopeSet::parse`], applied per string, but each configured atom is
    /// parsed on its own here and the results accumulate. Without this a
    /// configuration file naming a few thousand atoms is a few million
    /// comparisons at boot.
    pub fn new<'a>(atoms: impl IntoIterator<Item = &'a str>) -> (Self, DroppedAtoms) {
        let compiled = GrantAnyScope.ceiling("", "");
        let mut kept: Vec<crate::oauth::scope::Scope> = Vec::new();
        let mut dropped = DroppedAtoms::default();
        for atom in atoms {
            let Ok(parsed) = ScopeSet::parse(atom) else {
                dropped.outside.push(atom.to_owned());
                continue;
            };
            let (granted, cut) = parsed.narrow(&compiled);
            if !cut.0.is_empty() || granted.0.is_empty() {
                dropped.outside.push(atom.to_owned());
                continue;
            }
            if kept.len() + granted.0.len() > crate::oauth::scope::MAX_SCOPE_ATOMS {
                dropped.over_bound.push(atom.to_owned());
                continue;
            }
            kept.extend(granted.0);
        }
        (Self(ScopeSet::new(kept)), dropped)
    }

    /// What this ceiling admits, for a caller that wants to log or show it.
    pub fn scopes(&self) -> &ScopeSet {
        &self.0
    }
}

impl ScopePolicy for ConfiguredCeiling {
    fn ceiling(&self, _did: &str, _client_id: &str) -> ScopeSet {
        self.0.clone()
    }
}

/// How often the page reloads itself while the account has not answered.
///
/// Each address may load `GET /oauth/authorize`
/// [`crate::rate_limit::DEFAULT_LIMIT`] times a
/// [`crate::rate_limit::WINDOW`]. Every five seconds is twelve loads a
/// minute, so a second tab waiting on the same address still fits.
pub const RELOAD_INTERVAL: std::time::Duration = std::time::Duration::from_secs(5);

// A code is minted after its request was pushed, so while this holds the
// request always expires first, and a redirect the page hands over never
// carries a code that has expired.
const _: () = assert!(
    crate::oauth::par::REQUEST_URI_TTL.whole_seconds()
        <= crate::oauth::token::AUTHORIZATION_CODE_TTL.whole_seconds()
);

/// Where an authorization response carries its parameters.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum ResponseMode {
    /// In the redirect's query. A push that names no mode gets this.
    #[default]
    Query,
    /// In the redirect's fragment, which a browser keeps to itself.
    Fragment,
}

impl ResponseMode {
    /// Every mode a push may name.
    pub const ALL: [Self; 2] = [Self::Query, Self::Fragment];

    /// The wire word for this mode.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Query => "query",
            Self::Fragment => "fragment",
        }
    }

    /// The mode `raw` names, if it is one this server answers in.
    pub fn named(raw: &str) -> Option<Self> {
        Self::ALL.into_iter().find(|mode| mode.as_str() == raw)
    }
}

/// The client's redirect, carrying an authorization response: `result` (a
/// code, or an error), then `state` if the client sent one, then `iss`, in
/// the query or the fragment as `mode` says.
///
/// `iss` is RFC 9207's: this server's issuer, which a client compares with
/// the authorization server it pushed the request to. The metadata's
/// `authorization_response_iss_parameter_supported` promises it, and a
/// client that reads that refuses a response without it.
///
/// Parsed rather than concatenated: `state` is whatever the client sent.
pub fn authorization_response(
    redirect_uri: &str,
    mode: ResponseMode,
    result: &[(&str, &str)],
    state: Option<&str>,
    issuer: &str,
) -> Result<url::Url, url::ParseError> {
    let mut redirect = url::Url::parse(redirect_uri)?;
    let pairs = result
        .iter()
        .copied()
        .chain(state.map(|state| ("state", state)))
        .chain([("iss", issuer)]);
    match mode {
        ResponseMode::Query => {
            redirect.query_pairs_mut().extend_pairs(pairs);
        }
        ResponseMode::Fragment => {
            let fragment = url::form_urlencoded::Serializer::new(String::new())
                .extend_pairs(pairs)
                .finish();
            redirect.set_fragment(Some(&fragment));
        }
    }
    Ok(redirect)
}

/// Whether a browser carries a sign-in's code to its client: every redirect
/// but a loopback one taking its code in the query.
///
/// That one goes to a listener on the host that approved the sign-in, and
/// what approved it fetches it there, as `didbot_agentd::loopback::deliver`
/// does. An approval holds any other for the authorize page to hand to a
/// browser signed in as the account.
pub fn browser_carries(redirect_uri: &str, mode: ResponseMode) -> bool {
    mode == ResponseMode::Fragment
        || url::Url::parse(redirect_uri).map_or(true, |url| !didbot_http::is_loopback(&url))
}

/// Whether this load confirms the sign-in without asking the account, on
/// the approval it `remembered`. See `plan/remembered-consent.md`.
///
/// Every condition must hold. The client is confidential, so only the holder
/// of its key pushed this request, which is the spec's rule for silent
/// sign-in. A browser carries its code, and this load is a top-level
/// navigation by a browser signed in as the account, so the code can reach
/// no other browser. The record is live and grants something. And every atom
/// it grants is covered by the grant the account approved for this
/// [`crate::oauth::client_metadata::ClientKey`].
///
/// The e-stop is the caller's to check.
pub fn confirms_unasked(
    pushed: &PushedRequest,
    record: &DecisionRecord,
    remembered: Option<&Remembered>,
    loader: &Loader,
    now: OffsetDateTime,
) -> bool {
    pushed.client_metadata.authentication.is_confidential()
        && browser_carries(&pushed.redirect_uri, pushed.response_mode)
        && loader.navigation
        && loader.signed_in_as(&record.account)
        && record.is_live(now)
        && record.token.is_some()
        && remembered.is_some_and(|remembered| {
            now < remembered.expires_at
                && record
                    .granted()
                    .0
                    .iter()
                    .all(|atom| remembered.granted.covers(atom))
        })
}

/// The browser loading the page, as far as the page's answer turns on it.
#[derive(Debug, Clone, Default)]
pub struct Loader {
    /// The accounts it is signed in as; see `crate::oauth::browser`.
    pub accounts: Vec<String>,
    /// Whether the load is a top-level navigation: `Sec-Fetch-Dest` absent,
    /// where a browser does not send it, or `document`.
    pub navigation: bool,
}

impl Loader {
    /// Whether this browser is signed in as `account`.
    pub fn signed_in_as(&self, account: &str) -> bool {
        self.accounts.iter().any(|held| held == account)
    }
}

/// A decision, as the page shows it.
///
/// Only a decision that grants something reaches this type, so `granted`
/// and `cut` are read off the verdict once, where the refusal case is
/// already answered.
#[derive(Debug, Clone)]
pub struct AuthorizePending {
    /// The decision itself — client origin, requested scope, verdict, and
    /// what the verdict cut.
    pub record: DecisionRecord,
    /// What approving this covers.
    pub granted: ScopeSet,
    /// What the ceiling took out of the request. Empty when it took
    /// nothing.
    pub cut: ScopeSet,
    /// What did the narrowing, when `cut` is not empty.
    pub rule: String,
    /// Whether the browser loading the page is signed in as the account.
    pub signed_in: bool,
    /// Whether the approval's code waits here for a browser signed in as the
    /// account.
    pub held: bool,
}

impl AuthorizePending {
    /// The page for `record`, or `None` for a verdict that grants nothing.
    fn of(record: DecisionRecord, signed_in: bool, held: bool) -> Option<Self> {
        let (granted, cut, rule) = match &record.verdict {
            Verdict::Allow => (record.requested.clone(), ScopeSet::default(), String::new()),
            Verdict::Narrow { granted, cut, rule } => (granted.clone(), cut.clone(), rule.clone()),
            Verdict::Deny { .. } => return None,
        };
        Some(Self {
            record,
            granted,
            cut,
            rule,
            signed_in,
            held,
        })
    }

    /// Whether the account has yet to answer.
    pub fn waiting(&self) -> bool {
        self.record.state == DecisionState::Pending
    }

    /// Whether the page reloads itself: the account has yet to answer, or a
    /// code waits for a browser signed in as the account.
    pub fn reloads(&self) -> bool {
        self.waiting() || self.held
    }
}

/// What one load of `GET /oauth/authorize` gets.
#[derive(Debug, Clone)]
pub enum AuthorizeAnswer {
    /// The page: the account has not answered, or it approved and the code
    /// went elsewhere or waits for another browser.
    Page(AuthorizePending),
    /// The client's redirect, carrying the code an approval held for a
    /// browser signed in as the account.
    Redirect {
        /// Where the browser goes.
        to: String,
        /// The account it is signed in as.
        account: String,
    },
    /// The sign-in ended without a code.
    Denied(Denial),
}

/// A sign-in that ended without a code, and the pushed request whose
/// redirect says so.
#[derive(Debug, Clone)]
pub struct Denial {
    pushed: PushedRequest,
    description: &'static str,
}

impl Denial {
    /// The client's redirect, carrying `access_denied` with a description,
    /// the client's `state`, and `issuer`.
    pub fn redirect(&self, issuer: &str) -> Result<url::Url, url::ParseError> {
        authorization_response(
            &self.pushed.redirect_uri,
            self.pushed.response_mode,
            &[
                ("error", "access_denied"),
                ("error_description", self.description),
            ],
            self.pushed.state.as_deref(),
            issuer,
        )
    }
}

/// Why `authorize` answered with an error rather than the page or a
/// redirect.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum AuthorizeError {
    /// `request_uri` names nothing this server holds: unknown, displaced,
    /// or expired and forgotten.
    #[error("request_uri is not live: unknown or expired")]
    UnknownRequestUri,
    /// The `client_id` on this request does not match the one the pushed
    /// request was made under.
    #[error("client_id does not match the pushed authorization request")]
    ClientMismatch,
}

/// The `error_description` for a request the account declined.
const DECLINED: &str = "the account declined this authorization request";
/// The `error_description` for a request that expired before its code
/// reached the client.
const EXPIRED: &str = "this authorization request expired";
/// The `error_description` for a request whose verdict grants nothing.
const REFUSED: &str = "this server refused this authorization request";

/// Answers one load of the page for `request_uri`, by `loader`, at `now`.
///
/// The page, while the account has not answered. Once it approves, the
/// redirect the approval held for a browser goes to a top-level navigation
/// by a browser signed in as the record's account, once
/// ([`DecisionStore::collect`]). Any other load gets the page, approved and
/// reloading, until the request expires, and then `access_denied`. An
/// approval that held nothing gets the page, with no code on it: its code
/// went to what approved it. A decline, a verdict that grants nothing, or a
/// request that expired first is a [`Denial`]: the browser goes to the
/// client with `access_denied` (RFC 6749 §4.1.2.1).
///
/// RFC 9126 §4 allows a reload of the same `request_uri`, so nothing here
/// spends it. PKCE leaves a code useless to anything but the client that
/// pushed the request.
pub fn answer(
    par_store: &dyn ParStore,
    decisions: &dyn DecisionStore,
    request_uri: &str,
    client_id: &str,
    loader: &Loader,
    now: OffsetDateTime,
) -> Result<AuthorizeAnswer, AuthorizeError> {
    let pushed = par_store
        .get(request_uri)
        .ok_or(AuthorizeError::UnknownRequestUri)?;
    if pushed.client_id != client_id {
        return Err(AuthorizeError::ClientMismatch);
    }
    let record = decisions
        .get(request_uri)
        .ok_or(AuthorizeError::UnknownRequestUri)?;
    let signed_in = loader.signed_in_as(&record.account);
    let expired = now >= record.expires_at;
    let held = decisions.holds(request_uri);
    let page = |record, held| match AuthorizePending::of(record, signed_in, held) {
        Some(page) => AuthorizeAnswer::Page(page),
        None => AuthorizeAnswer::Denied(Denial {
            pushed: pushed.clone(),
            description: REFUSED,
        }),
    };
    let description = match record.state {
        DecisionState::Approved if held && expired => {
            decisions.collect(request_uri);
            EXPIRED
        }
        DecisionState::Approved if held && signed_in && loader.navigation => {
            return Ok(match decisions.collect(request_uri) {
                Some(to) => AuthorizeAnswer::Redirect {
                    to,
                    account: record.account,
                },
                // A load a moment ago took it.
                None => page(record, false),
            });
        }
        DecisionState::Approved => return Ok(page(record, held)),
        DecisionState::Pending if !expired => return Ok(page(record, false)),
        DecisionState::Declined => DECLINED,
        DecisionState::Pending | DecisionState::Expired => EXPIRED,
    };
    Ok(AuthorizeAnswer::Denied(Denial {
        pushed,
        description,
    }))
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::oauth::client_metadata::{ApplicationType, ClientKey, ClientMetadataDocument};
    use crate::oauth::consent::ConsentReference;
    use crate::oauth::decision::{ClientSelf, MemoryDecisionStore};
    use crate::oauth::par::MemoryParStore;

    const CLIENT_ID: &str = "https://client.example/id.json";
    const ISSUER: &str = "https://pds.example";

    fn document(client_id: &str) -> ClientMetadataDocument {
        ClientMetadataDocument {
            client_id: client_id.to_owned(),
            application_type: ApplicationType::Web,
            client_name: None,
            client_uri: None,
            logo_uri: None,
            redirect_uris: vec!["https://client.example/cb".to_owned()],
            grant_types: vec!["authorization_code".to_owned()],
            response_types: vec!["code".to_owned()],
            authentication: crate::oauth::client_auth::ClientAuthentication::public(),
            scope: None,
            dpop_bound_access_tokens: true,
        }
    }

    fn pushed(client_id: &str, scope: &str) -> PushedRequest {
        let document = document(client_id);
        PushedRequest {
            client_id: client_id.to_owned(),
            client_key: ClientKey::compute(&document),
            client_metadata: document,
            redirect_uri: "https://client.example/cb".to_owned(),
            scope: ScopeSet::parse(scope).unwrap(),
            state: Some("xyz".to_owned()),
            response_mode: ResponseMode::Query,
            code_challenge: "abc".to_owned(),
            code_challenge_method: "S256".to_owned(),
            login_hint: Some("did:web:agent.example".to_owned()),
            did: "did:web:agent.example".to_owned(),
            dpop_jkt: crate::oauth::dpop_seam::DpopThumbprint("a-key".to_owned()),
            expires_at: OffsetDateTime::now_utc() + time::Duration::minutes(2),
        }
    }

    /// The record PAR would have minted for `pushed`, with `verdict` as the
    /// answer it reached.
    fn record(request_uri: &str, verdict: Verdict, token: Option<&str>) -> DecisionRecord {
        let now = OffsetDateTime::now_utc();
        DecisionRecord {
            request_uri: request_uri.to_owned(),
            account: "did:web:agent.example".to_owned(),
            client_origin: "https://client.example".to_owned(),
            client_key: ClientKey("k".to_owned()),
            first_time: true,
            client_self: ClientSelf::default(),
            requested: ScopeSet::parse("atproto").unwrap(),
            verdict,
            token: token.map(|t| ConsentReference(t.to_owned())),
            created_at: now,
            expires_at: now + time::Duration::minutes(2),
            state: DecisionState::Pending,
            sequence: 0,
        }
    }

    /// A push and its decision, stored the way PAR stores them.
    fn stored(verdict: Verdict) -> (MemoryParStore, MemoryDecisionStore, String) {
        let par = MemoryParStore::new();
        let uri = par.push(pushed(CLIENT_ID, "atproto"));
        let decisions = MemoryDecisionStore::new();
        let token = (!verdict.is_deny()).then_some("reference");
        decisions.put(record(&uri, verdict, token)).unwrap();
        (par, decisions, uri)
    }

    fn load(par: &MemoryParStore, decisions: &MemoryDecisionStore, uri: &str) -> AuthorizeAnswer {
        load_by(par, decisions, uri, &Loader::default())
    }

    /// One load by `loader`, now.
    fn load_by(
        par: &MemoryParStore,
        decisions: &MemoryDecisionStore,
        uri: &str,
        loader: &Loader,
    ) -> AuthorizeAnswer {
        answer(
            par,
            decisions,
            uri,
            CLIENT_ID,
            loader,
            OffsetDateTime::now_utc(),
        )
        .expect("the page answers")
    }

    /// A browser signed in as `accounts`, loading the page as `navigation`
    /// says.
    fn browser(accounts: &[&str], navigation: bool) -> Loader {
        Loader {
            accounts: accounts
                .iter()
                .map(|account| (*account).to_owned())
                .collect(),
            navigation,
        }
    }

    /// Where the account's approval of a web sign-in sends a browser.
    const HELD: &str =
        "https://client.example/cb?code=c0de&state=xyz&iss=https%3A%2F%2Fpds.example";

    /// The query of the redirect a denial sends the browser to.
    fn sent_to(answer: AuthorizeAnswer) -> Vec<(String, String)> {
        let AuthorizeAnswer::Denied(denial) = answer else {
            panic!("expected a denial, got {answer:?}");
        };
        denial
            .redirect(ISSUER)
            .unwrap()
            .query_pairs()
            .map(|(key, value)| (key.into_owned(), value.into_owned()))
            .collect()
    }

    /// A remembered approval confirms a sign-in only when every rule holds,
    /// and each rule refuses on its own.
    #[test]
    fn a_remembered_approval_confirms_only_when_every_rule_holds() {
        let now = OffsetDateTime::now_utc();
        let account = "did:web:agent.example";
        let mut confidential = pushed(CLIENT_ID, "atproto");
        confidential
            .client_metadata
            .authentication
            .token_endpoint_auth_method = crate::oauth::client_auth::PRIVATE_KEY_JWT.to_owned();
        let pending = record("urn:r", Verdict::Allow, Some("reference"));
        let remembered = Remembered {
            client_id: CLIENT_ID.to_owned(),
            granted: ScopeSet::parse("atproto repo:*").unwrap(),
            expires_at: now + time::Duration::minutes(1),
        };
        let signed_in = browser(&[account], true);
        let confirms = |pushed: &PushedRequest,
                        record: &DecisionRecord,
                        remembered: Option<&Remembered>,
                        loader: &Loader| {
            confirms_unasked(pushed, record, remembered, loader, now)
        };
        assert!(confirms(
            &confidential,
            &pending,
            Some(&remembered),
            &signed_in
        ));

        let public = pushed(CLIENT_ID, "atproto");
        let mut loopback = confidential.clone();
        loopback.redirect_uri = "http://127.0.0.1/cb".to_owned();
        let mut answered = pending.clone();
        answered.state = DecisionState::Approved;
        let denied = record(
            "urn:r",
            Verdict::Deny {
                reason: "no".to_owned(),
                rule: "a-policy".to_owned(),
            },
            None,
        );
        let mut wider = pending.clone();
        wider.requested = ScopeSet::parse("atproto blob:*/*").unwrap();
        let lapsed = Remembered {
            expires_at: now,
            ..remembered.clone()
        };
        let refusals = [
            (
                "a public client",
                confirms(&public, &pending, Some(&remembered), &signed_in),
            ),
            (
                "a loopback sign-in",
                confirms(&loopback, &pending, Some(&remembered), &signed_in),
            ),
            (
                "a browser signed in as another account",
                confirms(
                    &confidential,
                    &pending,
                    Some(&remembered),
                    &browser(&["did:web:other.example"], true),
                ),
            ),
            (
                "a load that is not a navigation",
                confirms(
                    &confidential,
                    &pending,
                    Some(&remembered),
                    &browser(&[account], false),
                ),
            ),
            (
                "an answered record",
                confirms(&confidential, &answered, Some(&remembered), &signed_in),
            ),
            (
                "a verdict that grants nothing",
                confirms(&confidential, &denied, Some(&remembered), &signed_in),
            ),
            (
                "a wider grant",
                confirms(&confidential, &wider, Some(&remembered), &signed_in),
            ),
            (
                "no remembered approval",
                confirms(&confidential, &pending, None, &signed_in),
            ),
            (
                "a lapsed one",
                confirms(&confidential, &pending, Some(&lapsed), &signed_in),
            ),
        ];
        for (why, confirmed) in refusals {
            assert!(!confirmed, "{why} confirmed");
        }
    }

    /// RFC 9126 §4 allows a reload of the same `request_uri`, so the page
    /// answers every load until the account does, and spends nothing.
    #[test]
    fn the_page_answers_every_reload_until_the_account_answers() {
        let (par, decisions, uri) = stored(Verdict::Allow);
        for _ in 0..3 {
            let AuthorizeAnswer::Page(page) = load(&par, &decisions, &uri) else {
                panic!("the account has not answered");
            };
            assert!(page.waiting());
            assert_eq!(page.granted.to_string(), "atproto");
        }
    }

    /// An approval that held nothing sent its code to what approved it, so
    /// every load after it gets the page, which carries no code and no
    /// longer reloads, whoever loads it.
    #[test]
    fn an_approval_that_held_nothing_gets_the_page_and_no_code() {
        let (par, decisions, uri) = stored(Verdict::Allow);
        decisions
            .approve(&uri, None)
            .expect("a live record approves");
        for loader in [Loader::default(), browser(&["did:web:agent.example"], true)] {
            let AuthorizeAnswer::Page(page) = load_by(&par, &decisions, &uri, &loader) else {
                panic!("an approval that held nothing sends the browser nowhere");
            };
            assert!(!page.waiting() && !page.reloads());
        }
    }

    /// A held code goes to a top-level navigation by a browser signed in as
    /// the record's account, once. Another account's browser, a browser
    /// signed in as nobody, and a load that is not a navigation each get the
    /// page, approved and reloading.
    #[test]
    fn a_held_code_goes_once_to_a_navigation_signed_in_as_the_account() {
        let (par, decisions, uri) = stored(Verdict::Allow);
        decisions
            .approve(&uri, Some(HELD.to_owned()))
            .expect("a live record approves");
        for (loader, signed_in) in [
            (Loader::default(), false),
            (browser(&["did:web:someone-else.example"], true), false),
            (browser(&["did:web:agent.example"], false), true),
        ] {
            let AuthorizeAnswer::Page(page) = load_by(&par, &decisions, &uri, &loader) else {
                panic!("{loader:?} is not the account's browser navigating");
            };
            assert!(!page.waiting() && page.held && page.reloads(), "{loader:?}");
            assert_eq!(page.signed_in, signed_in, "{loader:?}");
        }

        let account = browser(
            &["did:web:someone-else.example", "did:web:agent.example"],
            true,
        );
        let AuthorizeAnswer::Redirect { to, account: named } =
            load_by(&par, &decisions, &uri, &account)
        else {
            panic!("the account's browser collects the code");
        };
        assert_eq!(to, HELD);
        assert_eq!(named, "did:web:agent.example");
        let AuthorizeAnswer::Page(page) = load_by(&par, &decisions, &uri, &account) else {
            panic!("the code went out once");
        };
        assert!(!page.held && !page.reloads());
    }

    /// A held code nobody collected is dropped when its request expires, and
    /// the browser still waiting is sent back with `access_denied`.
    #[test]
    fn a_held_code_nobody_collected_ends_in_access_denied() {
        let (par, decisions, uri) = stored(Verdict::Allow);
        decisions
            .approve(&uri, Some(HELD.to_owned()))
            .expect("a live record approves");
        let expiry = decisions.get(&uri).unwrap().expires_at;
        let answered = answer(
            &par,
            &decisions,
            &uri,
            CLIENT_ID,
            &Loader::default(),
            expiry,
        )
        .expect("the page answers");
        let pairs = sent_to(answered);
        assert_eq!(pairs[0], ("error".to_owned(), "access_denied".to_owned()));
        assert_eq!(pairs[1].1, EXPIRED);
        assert!(
            !decisions.holds(&uri),
            "the code was dropped with the request"
        );
    }

    /// A sign-in that ends without a code sends the browser to the client
    /// with `access_denied`, its `state` and this server's `iss`.
    #[test]
    fn a_decline_an_expiry_and_a_denial_send_access_denied() {
        let (par, decisions, declined) = stored(Verdict::Allow);
        decisions.settle(&declined, DecisionState::Declined);

        let expired = par.push(pushed(CLIENT_ID, "atproto"));
        decisions
            .put(record(&expired, Verdict::Allow, Some("expired")))
            .unwrap();

        let denied = par.push(pushed(CLIENT_ID, "atproto"));
        let deny = Verdict::Deny {
            reason: "nope".to_owned(),
            rule: "a-rule".to_owned(),
        };
        decisions.put(record(&denied, deny, None)).unwrap();

        let later = OffsetDateTime::now_utc() + time::Duration::minutes(3);
        for (uri, now, description) in [
            (&declined, OffsetDateTime::now_utc(), DECLINED),
            (&expired, later, EXPIRED),
            (&denied, OffsetDateTime::now_utc(), REFUSED),
        ] {
            let answered =
                answer(&par, &decisions, uri, CLIENT_ID, &Loader::default(), now).unwrap();
            let pairs = sent_to(answered);
            let names: Vec<&str> = pairs.iter().map(|(name, _)| name.as_str()).collect();
            assert_eq!(names, ["error", "error_description", "state", "iss"]);
            assert_eq!(pairs[0].1, "access_denied");
            assert_eq!(pairs[1].1, description);
            assert_eq!(pairs[2].1, "xyz");
            assert_eq!(pairs[3].1, ISSUER);
        }
    }

    /// A request nothing was ever stored under is unknown, and nothing is
    /// sent anywhere for it.
    #[test]
    fn a_request_nothing_was_stored_under_is_unknown() {
        let (par, decisions, _) = stored(Verdict::Allow);
        let never_existed = "urn:ietf:params:oauth:request_uri:0000000000000000";
        assert_eq!(
            answer(
                &par,
                &decisions,
                never_existed,
                CLIENT_ID,
                &Loader::default(),
                OffsetDateTime::now_utc()
            )
            .unwrap_err(),
            AuthorizeError::UnknownRequestUri
        );
    }

    #[test]
    fn a_mismatched_client_id_is_refused() {
        let (par, decisions, uri) = stored(Verdict::Allow);
        assert_eq!(
            answer(
                &par,
                &decisions,
                &uri,
                "https://someone-else.example/id.json",
                &Loader::default(),
                OffsetDateTime::now_utc()
            )
            .unwrap_err(),
            AuthorizeError::ClientMismatch
        );
    }

    /// `fragment` puts the whole response after `#` and leaves the
    /// redirect's own query alone; `query` adds to that query.
    #[test]
    fn a_response_goes_in_the_query_or_the_fragment_the_client_named() {
        let result = [("code", "c0de")];
        let query = authorization_response(
            "https://client.example/cb?from=app",
            ResponseMode::Query,
            &result,
            Some("a b&c"),
            ISSUER,
        )
        .unwrap();
        assert_eq!(
            query.as_str(),
            "https://client.example/cb?from=app&code=c0de&state=a+b%26c&iss=https%3A%2F%2Fpds.example"
        );

        let fragment = authorization_response(
            "https://client.example/cb?from=app",
            ResponseMode::Fragment,
            &result,
            Some("a b&c"),
            ISSUER,
        )
        .unwrap();
        assert_eq!(
            fragment.as_str(),
            "https://client.example/cb?from=app#code=c0de&state=a+b%26c&iss=https%3A%2F%2Fpds.example"
        );
    }

    /// A browser carries every sign-in's code but a loopback redirect's in
    /// the query, which is fetched on the host that approved it.
    #[test]
    fn a_browser_carries_every_code_but_a_loopback_query() {
        for (redirect_uri, mode, browser) in [
            ("http://127.0.0.1:4000/cb", ResponseMode::Query, false),
            ("http://[::1]:4000/cb", ResponseMode::Query, false),
            ("http://127.0.0.1:4000/cb", ResponseMode::Fragment, true),
            ("https://client.example/cb", ResponseMode::Query, true),
            ("com.example.app:/cb", ResponseMode::Query, true),
        ] {
            assert_eq!(
                browser_carries(redirect_uri, mode),
                browser,
                "{redirect_uri} {mode:?}"
            );
        }
    }

    /// A configured ceiling may only shrink from the compiled-in one. An
    /// operator naming a hard-blocked capability gets nothing for it, which
    /// is what lets a scope live in a configuration file at all.
    #[test]
    fn a_configured_ceiling_cannot_reach_past_the_compiled_in_one() {
        let (ceiling, dropped) = ConfiguredCeiling::new([
            "atproto",
            "repo:app.bsky.feed.post",
            "transition:generic",
            "account:email",
            "notascope:whatever",
        ]);
        let admitted = ceiling.ceiling("did:web:a", "https://c");
        assert_eq!(admitted.to_string(), "atproto repo:app.bsky.feed.post");
        assert_eq!(
            dropped.outside,
            vec!["transition:generic", "account:email", "notascope:whatever"]
        );
        assert!(dropped.over_bound.is_empty());
    }

    /// **The bound that did not hold.** `MAX_SCOPE_ATOMS` bounds
    /// `ScopeSet::new`'s pairwise comparison, and `ScopeSet::parse` applies
    /// it per string — but each configured atom is its own string, so what
    /// accumulated here was unbounded. A ceiling naming more atoms than that
    /// is the atoms up to the bound, and the rest are reported.
    #[test]
    fn a_configured_ceiling_is_bounded_and_says_what_the_bound_dropped() {
        let atoms: Vec<String> = (0..crate::oauth::scope::MAX_SCOPE_ATOMS + 10)
            .map(|n| format!("repo:com.example.c{n}"))
            .collect();
        let (ceiling, dropped) = ConfiguredCeiling::new(atoms.iter().map(String::as_str));
        assert_eq!(
            ceiling.scopes().0.len(),
            crate::oauth::scope::MAX_SCOPE_ATOMS
        );
        assert_eq!(dropped.over_bound.len(), 10);
        assert!(dropped.outside.is_empty());
        assert_eq!(
            dropped.over_bound[0],
            format!("repo:com.example.c{}", crate::oauth::scope::MAX_SCOPE_ATOMS)
        );
    }

    #[test]
    fn a_configured_ceiling_with_nothing_in_it_grants_nothing() {
        let (ceiling, _) = ConfiguredCeiling::new(std::iter::empty());
        assert!(ceiling.scopes().0.is_empty());
        let request = ScopeSet::parse("atproto").unwrap();
        let (granted, cut) = request.narrow(&ceiling.ceiling("did:web:a", "https://c"));
        assert!(granted.0.is_empty());
        assert_eq!(cut, request);
    }
}