oauth_as/

consent.rs

// SPDX-License-Identifier: MIT OR Apache-2.0
// Copyright (C) 2026 Matthew Jackson

//! Consent records, consent withdrawal, and RFC 9470 step-up authentication.
//!
//! Two things a real deployment needs that nothing else in this crate provided.
//!
//! # 1. A consent is a UNIT, and a unit can be withdrawn
//!
//! Before this module the only durable grouping this server had was the refresh chain's
//! `family_id` (see [`crate::token::RefreshTokenRecord::family_id`]), which exists so that RFC 9700
//! section 4.14.2 reuse detection can revoke "the tokens issued for that authorization grant".
//! That grouping is too NARROW to answer the question a user asks. A user does not ask "end the
//! chain that started on Tuesday"; they ask "this application should no longer act for me", and one
//! application acting for one user accumulates many families over time, because every fresh trip
//! through the authorization endpoint mints another one.
//!
//! So a [`ConsentRecord`] is the broader unit, keyed by (client, subject), and
//! [`crate::store::Storage::revoke_consent`] is [`crate::store::Storage::revoke_token_family`] at
//! that broader granularity: the same "remove every record reachable from this unit" primitive,
//! asked of a bigger unit, in ONE storage operation so a host's database can do the whole cascade
//! in one transaction. A withdrawal that left tokens alive would be the whole feature failing
//! silently, and silently is the worst way for it to fail, because the user has been told they
//! stopped something they did not. `tests/consent.rs` attacks exactly that case.
//!
//! # 2. This library cannot authenticate anybody, and says so
//!
//! RFC 9470 is about the AUTHENTICATION behind an authorization: a resource server decides the
//! request it just received needs a stronger or a fresher login than the token reflects, and says
//! so with an `insufficient_user_authentication` challenge (section 3). The client then repeats its
//! authorization request carrying `acr_values` and `max_age` (section 4, the parameters OpenID
//! Connect Core section 3.1.2.1 defines), and the authorization server is expected to act on them
//! (section 5) and to report what it did as `acr` and `auth_time` (section 6).
//!
//! SECTION 6 HAS TWO SUBSECTIONS AND THIS CRATE ANSWERS BOTH, because a token reaches a resource
//! server two ways: 6.1 is the RFC 9068 JWT access token, read offline by a server that never
//! introspects, and 6.2 is RFC 7662 introspection, which is all an OPAQUE token has. Through 0.9.1
//! only 6.2 was answered, which left the step-up invisible to exactly the deployment that verifies
//! signatures locally.
//!
//! This crate has no login page, no session store, no password, no second factor, and no way to
//! challenge a user, and it will not grow any of them: that is the same boundary the crate docs
//! draw around the HTTP listener and persistence. So the division of labour is blunt, and worth
//! stating in full rather than leaving to be discovered:
//!
//! - the HOST authenticates the user, by whatever means, and REPORTS the result as an
//!   [`Authentication`]: when it happened, and which authentication context class it satisfied. The
//!   library takes that report at face value, because it has nothing to check it against. A host
//!   that stamps `auth_time` with the current instant on every request has disabled `max_age` for
//!   itself and no code here can tell.
//! - the LIBRARY records that report on the consent, on the authorization code, and on the tokens
//!   the code mints, and it ENFORCES `max_age` and `acr_values` against it
//!   ([`AuthenticationRequirement::satisfied_by`]). Enforcement is the half that must not be left
//!   to the host: a `max_age` a host is trusted to check for itself is a `max_age` that gets
//!   checked in whichever code path somebody remembered.
//! - the library CANNOT re-authenticate anyone in response to a failure. It answers
//!   [`crate::error::ErrorCode::InsufficientUserAuthentication`] and the host decides whether that
//!   becomes a fresh login prompt or a refusal.
//!
//! # Allocation
//!
//! [`Authentication`] hangs off its three records as an `Option<Box<Authentication>>`: one null
//! pointer for the common case of a host that reports nothing, and one small allocation for a host
//! that does. Its `acr`, and the consent record's identifier and subject, are `Box<str>` rather
//! than `String` for the reason [`crate::token::IssuedToken::jkt`] gives: they are written once and
//! never appended to, so a `String`'s growable capacity would be 8 dead bytes on every record a
//! store holds. Everything here is feature gated, so a build without `consent` carries neither the
//! pointers nor the code that reads them.

use std::time::{Duration, SystemTime};

use serde::{Deserialize, Serialize};

use crate::client::ClientId;
use crate::error::{ErrorCode, ErrorResponse};
use crate::scope::ScopeSet;

/// The largest number of RFC 8707 resource indicators one [`ConsentRecord`] will accumulate.
///
/// # Why this one matters more than the per-request caps
///
/// [`crate::server::MAX_RESOURCE_INDICATORS`] bounds what a single request may ask for, and that
/// cost dies with the request. This bounds what a (client, subject) relationship accumulates over
/// its whole life. The list is only ever widened by [`ConsentRecord::extend`], it is never pruned,
/// and [`ConsentRecord::covers`] walks it linearly on every authorization request that consults the
/// record. Without a bound, a client naming one fresh indicator per request buys a record that
/// grows forever and a check that gets slower forever, and the deployment never gets that back.
///
/// # Why 32
///
/// It is twice the per-request cap, which is the smallest number that is not simply the per-request
/// cap in disguise: a relationship legitimately widens over time, so a user who approves one set of
/// resources today and a different set next month should not hit the ceiling on the second visit.
/// Beyond that, a single (client, subject) pair spanning more than thirty-two distinct resource
/// servers is a client acting for the user across an estate large enough that per-resource consent
/// has stopped meaning anything to the person granting it, which is a product problem this number
/// makes visible rather than a limit it creates.
pub const MAX_CONSENT_RESOURCES: usize = 32;

/// The largest number of authentication context classes one `acr_values` parameter may name
/// (RFC 9470 section 4, OpenID Connect Core section 3.1.2.1).
///
/// # Why a cap at all
///
/// `acr_values` is ONE parameter carrying a space-delimited list, and it arrives unauthenticated,
/// before any user interaction, at `GET /authorize` and at the RFC 9126 push. Parsing it stores one
/// `Box<str>` per non-empty segment, which is one heap allocation per segment, so without a bound
/// the segment count is whatever the request line or the body allowed. The cheapest input is
/// `"a a a ..."` at two bytes a token: 64 KiB of body, which is
/// `crate::http::MAX_BODY_BYTES`, is about 32,768 allocations from a single parameter, and the
/// GET form is worse because a URL is not bounded by that constant at all.
///
/// That is the exact shape `crate::http::MAX_FORM_PARAMETERS` exists to refuse, and it slipped
/// past because it is one parameter rather than many: that constant's own arithmetic puts 64 KiB of
/// `&a=b` pairs at about 2,300 parameters, so this one parameter bought an order of magnitude more
/// work than the case the parameter cap was introduced for.
///
/// # Why 16
///
/// `acr_values` is an ORDERED PREFERENCE list, not a set to enumerate: OpenID Connect Core section
/// 3.1.2.1 has the AS satisfy the first class it can, so the entries past the first few are already
/// alternatives nobody expects to be reached. No published profile lists more than a handful. It is
/// also the number [`crate::server::MAX_RESOURCE_INDICATORS`] and
/// `rar::MAX_AUTHORIZATION_DETAILS_ELEMENTS` use for the other repeatable things one request can
/// carry, so a reader does not have to hold a third number.
///
/// # It refuses, it does not truncate
///
/// Truncating would answer a resource server's step-up challenge with a class the user never
/// satisfied, or drop the one class the client could actually meet, and tell nobody. That is the
/// same failure [`crate::server::MAX_RESOURCE_INDICATORS`] refuses for RFC 8707 and
/// [`crate::rar`] refuses for unknown members. `invalid_request` is the honest answer.
pub const MAX_ACR_VALUES: usize = 16;

/// What the HOST says about how, and when, it authenticated the resource owner.
///
/// This is a REPORT, not a proof. See the module docs: this crate cannot authenticate anyone and
/// has no way to check this against anything, so it records it and holds requests to it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Authentication {
    /// When the user actually authenticated. OpenID Connect Core section 2 defines `auth_time` as
    /// the "time when the End-User authentication occurred", and RFC 9470 section 6 is what makes
    /// it worth carrying: `max_age` is meaningless without an instant to measure from. It is
    /// reported through both of that section's channels, the JWT claim of 6.1 and the introspection
    /// member of 6.2.
    ///
    /// NOT "when this request arrived". A host that conflates the two makes every request look
    /// freshly authenticated, which is the one mistake that turns this whole mechanism into
    /// decoration.
    pub auth_time: SystemTime,
    /// The authentication context class the host says was satisfied: OpenID Connect Core section 2
    /// `acr`. `None` means the host reported none, which can satisfy no `acr_values` request.
    ///
    /// The VALUES are the host's own vocabulary. This crate compares them as opaque strings and
    /// deliberately knows nothing about what any of them means: there is no registry it could check
    /// against, and a library that pretended to understand "phr" would be asserting something about
    /// a login flow it has never seen.
    ///
    /// `Box<str>`, not `String`: written once at the moment the host reports it and never appended
    /// to. Same reasoning as [`crate::token::IssuedToken::jkt`].
    pub acr: Option<Box<str>>,
}

impl Authentication {
    /// A report with no `acr`, for an authentication that happened at `auth_time`.
    ///
    /// `auth_time` is WHEN THE USER ACTUALLY LOGGED IN, not when this request arrived, and this
    /// constructor is the place that distinction is lost or kept. Passing `SystemTime::now()` here
    /// on every request makes every login look seconds old, which satisfies every `max_age` a
    /// client can ask for and turns RFC 9470 step-up into decoration for that deployment. Nothing
    /// downstream can detect it: see the module docs on which half of this boundary is the host's.
    pub fn at(auth_time: SystemTime) -> Self {
        Authentication {
            auth_time,
            acr: None,
        }
    }

    /// Name the authentication context class this login satisfied.
    ///
    /// `&str` rather than `impl Into<String>`: a generic here monomorphizes once per argument type
    /// at every call site, and the value is going into a `Box<str>` either way.
    pub fn with_acr(mut self, acr: &str) -> Self {
        self.acr = Some(acr.into());
        self
    }

    /// How old this authentication is at `now`, or `None` if it is stamped in the future.
    ///
    /// A future `auth_time` is not an error here: clocks on separate machines disagree, and the one
    /// decision this feeds ([`AuthenticationRequirement::satisfied_by`]) reads `None` as "no
    /// elapsed time", which is the reading that cannot lock a user out over a clock skew.
    pub fn age(&self, now: SystemTime) -> Option<Duration> {
        now.duration_since(self.auth_time).ok()
    }
}

/// A persisted record that one resource owner granted one client a set of permissions.
///
/// Keyed by (`client_id`, `subject`): one live consent per pair, widened in place when the user
/// approves something further or re-authenticates. That key is what makes withdrawal answerable,
/// and it is deliberately COARSER than the refresh chain's `family_id`, because a user withdrawing
/// consent means "not this application, not for me, not any more" rather than "not this chain".
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ConsentRecord {
    /// The server-minted identifier for this consent.
    ///
    /// Opaque, and NOT a credential: it is accepted at no endpoint, it authenticates nobody, and
    /// its only power is to NAME this record in the host's own store, exactly as `family_id` names
    /// a chain (the [`crate::events`] module docs make that argument in full). It is still minted
    /// from OS randomness rather than derived from the client and the subject, because naming a
    /// record that can end a user's sessions should not be something a third party can do by
    /// guessing two strings it already knows.
    ///
    /// `Box<str>`: written once at creation and never appended to.
    pub consent_id: Box<str>,
    /// The client the user granted.
    pub client_id: ClientId,
    /// The resource owner who granted it, in the host's own vocabulary for users. `Box<str>` for
    /// the same reason as `consent_id`.
    pub subject: Box<str>,
    /// The scope the user approved, accumulated across grants: this is what "remembered consent"
    /// remembers.
    pub scope: ScopeSet,
    /// The RFC 8707 resource indicators the user approved this client to obtain tokens for. Empty
    /// means the user approved no audience restriction, which is NOT the same as approving every
    /// resource: see [`ConsentRecord::covers`].
    ///
    /// A `Vec` and not a `Box<[_]>`, unlike everything else here, because this is the one field
    /// that genuinely grows: [`ConsentRecord::extend`] widens it in place as a user approves more,
    /// and a boxed slice would mean reallocating the list on every widening to save 8 bytes on a
    /// record there is one of per (client, user) pair.
    pub resource: Vec<String>,
    /// When this consent was first recorded. Widening does not move it: a user asking "since when
    /// has this application been able to act for me" means the beginning, not the last change.
    pub granted_at: SystemTime,
    /// The authentication the host reported at the most recent approval, if any. See
    /// [`Authentication`], and the module docs on whose job this is.
    pub authentication: Option<Box<Authentication>>,
}

/// The RFC 9396 `authorization_details` an authorization request is ASKING FOR, in a shape that
/// exists in every feature configuration.
///
/// A WRAPPER rather than the details themselves, and the reason is structural, the same one
/// `crate::server`'s `GrantedDetails` records about `issue`: an argument can carry a `cfg`, but the
/// ARGUMENT AT A CALL SITE cannot, so a gated parameter on [`ConsentRecord::covers`] would make
/// every host's approval resolver — the one place this crate asks a host to write a comparison —
/// duplicate that call under a `cfg` of its own. A host that writes one call site cannot get it
/// wrong in the configuration it does not build.
///
/// Without `rar` this type has no fields, so it is zero sized, [`RequestedDetails::none`] compiles
/// to nothing, and a deployment that never enabled RFC 9396 pays for none of it.
///
/// `#[non_exhaustive]` because its field set varies with a feature, which is the rule
/// `tests/host_api_shape.rs` gates for every public type in this crate. Both fields are private
/// already, so the attribute costs a host nothing: the two constructors below are the only way to
/// make one in any build.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, Default)]
pub struct RequestedDetails<'a> {
    /// `None` for an empty request as well as an absent one: "asked for no detail" and "asked for
    /// an empty array" are the same request, and collapsing them here means
    /// [`ConsentRecord::covers`] has one case to reason about rather than two.
    #[cfg(feature = "rar")]
    details: Option<&'a crate::rar::AuthorizationDetails>,
    /// Without `rar` there is nothing to borrow, and the lifetime parameter still has to be used.
    #[cfg(not(feature = "rar"))]
    borrow: std::marker::PhantomData<&'a ()>,
}

impl<'a> RequestedDetails<'a> {
    /// The request asks for no rich authorization detail. What a deployment without RFC 9396
    /// always passes, and what a request that sent no `authorization_details` means.
    pub fn none() -> Self {
        RequestedDetails::default()
    }

    /// What the request in hand is asking for: the `http` feature hands a host exactly this value
    /// as `ApprovalRequest::authorization_details`.
    #[cfg(feature = "rar")]
    pub fn of(details: &'a crate::rar::AuthorizationDetails) -> Self {
        RequestedDetails {
            details: (!details.is_empty()).then_some(details),
        }
    }

    /// Whether the request asked for any detail at all.
    fn is_empty(&self) -> bool {
        #[cfg(feature = "rar")]
        {
            self.details.is_none()
        }
        #[cfg(not(feature = "rar"))]
        {
            let _ = self.borrow;
            true
        }
    }
}

impl ConsentRecord {
    /// Whether this record already covers a request for `scope`, `resource` and `details`.
    ///
    /// This is the whole of what "remembered consent" means in this crate, and it ANSWERS a
    /// question rather than making a decision: the `http` feature's
    /// `ServiceBuilder::with_approval_resolver` is where the answer is turned into one. Nothing in
    /// this crate approves an authorization request on the strength of a `true` here.
    ///
    /// The first two halves are SUBSET tests against what was approved, never equality and never a
    /// widening: a request for less than was granted is covered, and a request for one token more
    /// is not. Requesting a resource that was never approved is not covered either, because RFC
    /// 8707 section 2 makes the resource the audience the token will be good at, so treating
    /// "approved for no particular resource" as "approved for that one" would let a remembered
    /// consent grow an audience the user never saw.
    ///
    /// # A request carrying `authorization_details` is NEVER covered
    ///
    /// Whatever this record holds. A [`ConsentRecord`] records a scope and a resource list and
    /// nothing else, so there is no approved element for a requested one to be compared against,
    /// and the only two answers available are "not covered" and "covered because the SCOPE
    /// matched". The second is the direction this method may not fail in: it would wave through an
    /// RFC 9396 element — an amount, a creditor account, an `identifier` — that the resource owner
    /// was never shown, on the strength of a scope string that RFC 9396 exists precisely because it
    /// cannot express such a thing. That is the same failure the resource half above refuses, one
    /// level more specific, and it is worse there because the element is the transaction.
    ///
    /// This is a REFUSAL and not a limitation to be worked around, and the reason is that the two
    /// answers are nearly the same answer. The widest comparison this crate could ever soundly make
    /// is [`crate::rar::AuthorizationDetail::is_narrowing_of`]: a requested element is covered only
    /// when an approved one is identical to it in every type-defined member, since section 6.1 says
    /// the AS cannot know what any of those members mean. For a payment that is the SAME payment
    /// again. So the coverage a details field would buy is "ask me once per distinct transaction,
    /// not once per request", and a remembered approval of one transaction is not an approval of
    /// the next one anyway.
    ///
    /// A host that wants a user asked about a detail exactly once therefore does it at the seam
    /// that can: the approval resolver is handed the parsed elements as
    /// `ApprovalRequest::authorization_details`, alongside this answer, and decides.
    pub fn covers(
        &self,
        scope: &ScopeSet,
        resource: &[String],
        details: RequestedDetails<'_>,
    ) -> bool {
        scope.is_subset(&self.scope)
            && resource.iter().all(|r| self.resource.contains(r))
            && details.is_empty()
    }

    /// Widen this record to also cover `scope` and `resource`.
    ///
    /// Accumulating rather than replacing, because a user who approves `write` today has not
    /// withdrawn the `read` they approved last month, and a record that replaced would re-prompt
    /// for something they can see in their own consent list. Narrowing is not done here at all: the
    /// way to take something back is [`crate::server::AuthorizationServer::withdraw_consent`],
    /// which also revokes what the grant issued, and a silent narrowing that left live tokens
    /// holding the removed scope would be the same lie this module exists to avoid.
    ///
    /// RFC 9396 `authorization_details` are NOT accumulated here, because they are not recorded at
    /// all: see [`ConsentRecord::covers`] for why a remembered consent never covers a request that
    /// carries any, and why the coverage a details field would buy is one repeat of an identical
    /// transaction rather than a class of them.
    pub fn extend(&mut self, scope: &ScopeSet, resource: &[String]) {
        if !scope.is_subset(&self.scope) {
            let merged = self
                .scope
                .iter()
                .chain(scope.iter())
                .map(|s| s.as_str())
                .collect::<Vec<&str>>();
            // Both sets were parsed by `ScopeSet` already, so the union of their tokens cannot fail
            // to parse. On the impossible error the OLD set stands: failing to widen re-prompts a
            // user, and that is the harmless direction to fail in.
            if let Ok(widened) = ScopeSet::from_tokens(merged) {
                self.scope = widened;
            }
        }
        // CAPPED at [`MAX_CONSENT_RESOURCES`], and this is the one bound in the crate whose cost is
        // DURABLE rather than per request. `self.resource` is the union of every resource ever
        // approved for one (client, subject) pair; it is only ever widened here and pruned nowhere,
        // and `covers` scans it linearly on every authorization request that consults the record.
        // A client that names one fresh resource indicator per authorization request therefore
        // bought a permanently larger record and a permanently slower check, and nothing anywhere
        // said no.
        //
        // The cap refuses to GROW; it never removes. Dropping something already approved would
        // narrow a consent silently while tokens carrying it are still live, which is the same lie
        // this method's docs refuse to tell about narrowing generally.
        //
        // Failing here is the HARMLESS direction, and it is the same direction the scope union
        // above already fails in: a resource that did not fit is not covered, `covers` answers
        // false, and the host re-prompts the user. The dangerous direction would be reporting
        // coverage that was never recorded.
        let room = MAX_CONSENT_RESOURCES.saturating_sub(self.resource.len());
        self.resource.reserve(resource.len().min(room));
        for r in resource {
            if self.resource.len() >= MAX_CONSENT_RESOURCES {
                break;
            }
            if !self.resource.contains(r) {
                self.resource.push(r.clone());
            }
        }
    }
}

/// What the client asked for about the USER's authentication, from an authorization request.
///
/// RFC 9470 section 4 carries exactly two parameters, both defined by OpenID Connect Core section
/// 3.1.2.1, and this crate implements only those two. Reading two of OpenID Connect's parameters
/// does not make this OpenID Connect: there is no `id_token`, no UserInfo endpoint and no claims
/// model here, and all three are off this crate's list on purpose.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct AuthenticationRequirement {
    /// Requested authentication context classes, in order of preference, from the space-delimited
    /// `acr_values` parameter. Empty means the client asked for none.
    ///
    /// Satisfied when the host's reported `acr` is ANY of these. OpenID Connect Core section 3.1.2.1
    /// makes `acr_values` a voluntary, ordered preference rather than a demand, so honouring a later
    /// entry is legal; RFC 9470 section 4 is what turns it into a requirement here, because the
    /// whole point of the exchange is that a resource server has already refused the token the
    /// previous `acr` produced.
    ///
    /// Bounded by [`MAX_ACR_VALUES`] when it comes off the wire: a parameter naming more classes
    /// than that is REFUSED rather than truncated. A requirement a host builds itself is its own
    /// data and is not bounded here, for the reason `rar::AuthorizationDetails::from_elements`
    /// gives: these bounds defend against an unauthenticated stranger, not against the deployment.
    pub acr_values: Vec<Box<str>>,
    /// The RFC 9470 section 4 / OpenID Connect Core section 3.1.2.1 `max_age`: how old the user's
    /// authentication may be. `None` means the client did not constrain it.
    ///
    /// `max_age=0` is a real and meaningful value, not an absent one: it means re-authenticate now.
    /// It is kept as `Some(Duration::ZERO)` for that reason, and any elapsed time at all fails it.
    pub max_age: Option<Duration>,
}

impl AuthenticationRequirement {
    /// No requirement at all: what an ordinary authorization request carries.
    pub fn none() -> Self {
        AuthenticationRequirement::default()
    }

    /// Collect the two RFC 9470 section 4 parameters from already-decoded `(name, value)` query
    /// pairs, the same shape [`crate::authorization::AuthorizationRequest::from_pairs`] takes.
    ///
    /// This is a CONVENIENCE over [`AuthenticationRequirement::from_request`], for a host that
    /// holds query pairs and nothing else. It is not what this crate's own endpoints use: they
    /// build the requirement from the RESOLVED request, because for an RFC 9126 pushed request or
    /// an RFC 9101 signed one the query is not where these parameters live, and reading it anyway
    /// both drops the ones that were sent and honours ones that were not.
    ///
    /// A repeated parameter keeps the FIRST occurrence, matching `from_pairs` and for the same
    /// reason: RFC 6749 section 3.1 says a parameter MUST NOT appear more than once, and last-wins
    /// is the smuggling-friendly choice when two intermediaries disagree about which copy counts.
    pub fn from_pairs<I, K, V>(pairs: I) -> Result<Self, ErrorResponse>
    where
        I: IntoIterator<Item = (K, V)>,
        K: AsRef<str>,
        V: AsRef<str>,
    {
        let mut acr_values = None;
        let mut max_age = None;
        for (k, v) in pairs {
            match k.as_ref() {
                "acr_values" if acr_values.is_none() => acr_values = Some(v),
                "max_age" if max_age.is_none() => max_age = Some(v),
                _ => {}
            }
        }
        AuthenticationRequirement::from_raw(
            acr_values.as_ref().map(AsRef::as_ref),
            max_age.as_ref().map(AsRef::as_ref),
        )
    }

    /// The requirement an already-resolved authorization request carries.
    ///
    /// THE one source of these two parameters for every path into the authorization endpoint. A
    /// plain RFC 6749 request populated the fields from its query, an RFC 9126 pushed request from
    /// the record it stored at push time, and an RFC 9101 signed request from the claims inside
    /// the signature; each of the three is the only text that path is allowed to trust, and this
    /// reads whichever one it was handed.
    pub fn from_request(
        request: &crate::authorization::AuthorizationRequest<'_>,
    ) -> Result<Self, ErrorResponse> {
        AuthenticationRequirement::from_raw(
            request.acr_values.as_deref(),
            request.max_age.as_deref(),
        )
    }

    /// The parse itself, over the two raw parameter values.
    fn from_raw(acr_values: Option<&str>, max_age: Option<&str>) -> Result<Self, ErrorResponse> {
        let mut out = AuthenticationRequirement::none();
        if let Some(raw) = acr_values {
            // One pass to COUNT and one to fill: `acr_values` is a short space-delimited list, and
            // a counting pass allocates nothing, so the second pass can reserve exactly what it
            // stores instead of reallocating its way there.
            //
            // The count is over NON-EMPTY segments, which is what the fill stores, so a parameter
            // of nothing but spaces counts zero rather than one per space.
            //
            // `take(MAX_ACR_VALUES + 1)` is what makes the refusal cheap: it stops reading at the
            // seventeenth class, so an oversized parameter is neither counted in full nor stored at
            // all. This bounds the STORED count and not merely a reservation. A cap on the
            // reservation alone bounds nothing: the `extend` below stores one `Box<str>`, which is
            // one heap allocation, per segment, so it is the segment count that a request gets to
            // choose and therefore the segment count that has to be refused. See [`MAX_ACR_VALUES`].
            let count = raw
                .split(' ')
                .filter(|s| !s.is_empty())
                .take(MAX_ACR_VALUES + 1)
                .count();
            if count > MAX_ACR_VALUES {
                return Err(ErrorResponse::new(ErrorCode::InvalidRequest).with_description(
                    "acr_values names more authentication context classes than this server accepts",
                ));
            }
            out.acr_values = Vec::with_capacity(count);
            out.acr_values.extend(
                raw.split(' ')
                    .filter(|s| !s.is_empty())
                    .map(Box::<str>::from),
            );
        }
        if let Some(raw) = max_age {
            // Refused rather than ignored. OpenID Connect Core section 3.1.2.1 makes this
            // the "Maximum Authentication Age... Specified as the number of seconds", so a
            // value that is not that is not a weaker request, it is an unintelligible one,
            // and treating it as absent would answer a step-up challenge with a token that
            // never had the freshness the resource server asked for.
            let secs: u64 = raw.parse().map_err(|_| {
                ErrorResponse::new(ErrorCode::InvalidRequest)
                    .with_description("max_age must be a non-negative number of seconds")
            })?;
            out.max_age = Some(Duration::from_secs(secs));
        }
        Ok(out)
    }

    /// Whether this asks for nothing, in which case no check has to run at all.
    pub fn is_empty(&self) -> bool {
        self.acr_values.is_empty() && self.max_age.is_none()
    }

    /// Hold a host's reported authentication to this requirement.
    ///
    /// The ORDER of the two checks is deliberate: freshness first, then class. A user whose login is
    /// both too old and of the wrong class is told to log in again, which is the action that fixes
    /// either problem, and it avoids telling a client which `acr` a stale session had.
    ///
    /// An absent report fails any non-empty requirement. "The host told us nothing" must never read
    /// as "there is nothing to check": that reading is what makes an unwired host silently satisfy
    /// every step-up challenge it is ever sent.
    pub fn satisfied_by(
        &self,
        authentication: Option<&Authentication>,
        now: SystemTime,
    ) -> Result<(), StepUpFailure> {
        if self.is_empty() {
            return Ok(());
        }
        let authentication = match authentication {
            Some(a) => a,
            None => return Err(StepUpFailure::NotReported),
        };
        if let Some(max_age) = self.max_age {
            // `age` is `None` only for an `auth_time` in the future, which reads as zero elapsed
            // time (see `Authentication::age`) and therefore passes.
            if authentication.age(now).unwrap_or_default() > max_age {
                return Err(StepUpFailure::Stale);
            }
        }
        if !self.acr_values.is_empty() {
            match &authentication.acr {
                Some(acr) => {
                    if !self
                        .acr_values
                        .iter()
                        .any(|want| want.as_ref() == acr.as_ref())
                    {
                        return Err(StepUpFailure::AcrNotMet);
                    }
                }
                // A host that reported no `acr` has not satisfied a request for a specific one.
                // Same rule as the absent report above, one level down.
                None => return Err(StepUpFailure::AcrNotMet),
            }
        }
        Ok(())
    }
}

/// Why a host's reported authentication did not satisfy an [`AuthenticationRequirement`].
///
/// Fieldless on purpose, and not only for the size of it. The `error_description` these produce goes
/// back to the CLIENT through the authorization response redirect (RFC 6749 section 4.1.2.1), and
/// the client is not entitled to learn when the user last logged in or which `acr` they hold; "not
/// fresh enough" is the whole of what it needs in order to decide to ask again.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum StepUpFailure {
    /// The host reported no authentication at all, and the request asked about one.
    NotReported,
    /// The authentication is older than the request's `max_age`.
    Stale,
    /// The reported `acr` is not one of the requested `acr_values` (or none was reported).
    AcrNotMet,
}

impl StepUpFailure {
    /// The developer-facing description this failure carries onto the wire.
    ///
    /// `&'static str`, so a refusal allocates nothing for it. The authorization endpoint is a path
    /// whose rate an unauthenticated caller sets, and an allocation per refusal there is a cost an
    /// attacker chooses.
    pub fn description(self) -> &'static str {
        match self {
            StepUpFailure::NotReported => "no user authentication was reported for this request",
            StepUpFailure::Stale => "the user authentication is older than the requested max_age",
            StepUpFailure::AcrNotMet => {
                "the user authentication does not satisfy the requested acr_values"
            }
        }
    }

    /// The RFC 9470 section 3 error this failure is reported as.
    ///
    /// `insufficient_user_authentication` is registered by RFC 9470 for the RESOURCE server's
    /// challenge, and section 4 names no code for the authorization server's own refusal. This crate
    /// uses the same one, deliberately, because it is the code the client has just been handed by
    /// the resource server and re-sending it says exactly the true thing: the authentication is
    /// still not sufficient. The alternative, a bare `invalid_request`, tells a client its
    /// parameters were malformed and invites it to retry the identical request.
    pub fn error_response(self) -> ErrorResponse {
        ErrorResponse::new(ErrorCode::InsufficientUserAuthentication)
            .with_description(self.description())
    }
}

impl std::fmt::Display for StepUpFailure {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(match self {
            StepUpFailure::NotReported => "no authentication reported",
            StepUpFailure::Stale => "authentication older than max_age",
            StepUpFailure::AcrNotMet => "acr_values not satisfied",
        })
    }
}

/// The other error-shaped types in this crate ([`crate::dpop::DpopFailure`],
/// [`crate::client_assertion::AssertionFailure`], [`crate::mtls::MtlsRegistrationError`]) are all
/// `std::error::Error`, and a host that puts one of them behind `?` or in a `Box<dyn Error>` has to
/// be able to do the same with this one. `Display` above is the whole implementation.
impl std::error::Error for StepUpFailure {}

impl From<StepUpFailure> for ErrorResponse {
    fn from(failure: StepUpFailure) -> ErrorResponse {
        failure.error_response()
    }
}

/// Build the RFC 9470 section 3 `WWW-Authenticate` challenge a RESOURCE SERVER sends when the token
/// it received is valid but the authentication behind it is not enough.
///
/// This crate is an authorization server, not a resource server, so this is a HELPER for the host's
/// own resource servers rather than something this server ever sends: the same posture as
/// [`crate::resource_metadata`], where the type is defined here and publishing it is the resource's
/// job. It is here because the challenge and the authorization request that answers it have to agree
/// on the spelling of two parameters, and one module owning both is how they stay in agreement.
///
/// `scheme` is the RFC 6750 section 3 (or RFC 9449 section 7.1) authentication scheme the resource
/// server challenges with, normally `Bearer` or `DPoP`. Section 3 puts `error`, `error_description`,
/// `acr_values` and `max_age` in the challenge; `acr_values` is omitted when empty rather than sent
/// blank, because an empty list reads as "no class is acceptable".
///
/// # What this does to the values, and why it is not only escaping
///
/// The values are emitted inside quoted strings, so a `"` or a `\` in an `acr` value would forge the
/// parameter that follows it. Both are ESCAPED, per the `quoted-string` rule of RFC 9110 section
/// 5.6.4, rather than the value being rejected: this crate does not own the host's `acr` vocabulary
/// and has no business refusing a value it merely has to transmit.
///
/// Escaping is not enough on its own, and reading section 5.6.4 as though it were is the defect the
/// 0.9.1 audit found here. `qdtext` is `HTAB / SP / %x21 / %x23-5B / %x5D-7E / obs-text`, and
/// `quoted-pair` is `"\" ( HTAB / SP / VCHAR / obs-text )`: NEITHER production admits a control
/// character, so a CR, an LF or a DEL cannot be escaped into a legal `quoted-string` at all. It can
/// only be removed, and until this was fixed it was passed through verbatim, which is a header
/// break emitted out of a value this doc called escaped. Reachability is not theoretical: the
/// parameter type is exactly [`AuthenticationRequirement::acr_values`], which
/// [`AuthenticationRequirement::from_pairs`] fills from the client's own query parameter, and the
/// whole point of this helper is that those classes come back out in a header.
///
/// So anything outside `HTAB`, `SP`, `%x21..=%x7E` and `%x80..=%xFF` is DROPPED. Dropping rather
/// than refusing keeps the signature total, and the two are the same answer in practice: a value
/// with a control character in it is not a class name any host defined, so there is nothing to
/// preserve. Every byte a `quoted-string` does admit survives, non-ASCII included.
///
/// `scheme` is written outside any quoted string, where no escaping exists at all, so it is filtered
/// to the RFC 9110 section 5.6.2 `tchar` set for the same reason. `Bearer` and `DPoP` pass through
/// untouched; anything that would forge the rest of the header does not survive to do it.
///
/// One allocation for every value this crate can produce: the buffer is sized up front from the
/// parts that go into it, and filtering only ever shortens what goes in. A value that is nothing but
/// quotes and backslashes escapes to twice its length and would grow the buffer once; that is a
/// `String`'s ordinary behaviour and not a bound anyone relies on.
pub fn step_up_challenge(
    scheme: &str,
    acr_values: &[Box<str>],
    max_age: Option<Duration>,
) -> String {
    use std::fmt::Write as _;

    const ERROR: &str = " error=\"insufficient_user_authentication\"";
    const DESCRIPTION: &str =
        ", error_description=\"the user authentication does not meet the requirements of this \
         resource\"";
    let acr_len: usize = acr_values.iter().map(|a| a.len() + 3).sum();
    let mut out = String::with_capacity(
        scheme.len() + ERROR.len() + DESCRIPTION.len() + acr_len + max_age.map_or(0, |_| 32),
    );
    out.extend(scheme.chars().filter(|c| is_tchar(*c)));
    out.push_str(ERROR);
    out.push_str(DESCRIPTION);
    if !acr_values.is_empty() {
        out.push_str(", acr_values=\"");
        for (i, acr) in acr_values.iter().enumerate() {
            if i > 0 {
                out.push(' ');
            }
            push_quoted(&mut out, acr);
        }
        out.push('"');
    }
    if let Some(max_age) = max_age {
        // Written through the same buffer rather than through an intermediate `to_string`, so the
        // whole challenge is still the one allocation the capacity above sized.
        let _ = write!(out, ", max_age=\"{}\"", max_age.as_secs());
    }
    out
}

/// Append `value` as the inside of an RFC 9110 section 5.6.4 `quoted-string`: `"` and `\` escaped,
/// and everything the grammar cannot carry dropped.
///
/// The two rules are not alternatives, and treating them as one was the bug. `quoted-string` is
/// `DQUOTE *( qdtext / quoted-pair ) DQUOTE` with
///
/// ```text
/// qdtext      = HTAB / SP / %x21 / %x23-5B / %x5D-7E / obs-text
/// quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text )
/// obs-text    = %x80-FF
/// ```
///
/// so `"` (%x22) and `\` (%x5C) are the two characters that are legal only as the second half of a
/// `quoted-pair`, which is what the escape below produces. A control character is in NEITHER
/// production: it is not `qdtext`, and it is not `VCHAR`, so a backslash in front of it produces an
/// illegal `quoted-pair` rather than a legal escape. There is no spelling of CR, LF or DEL inside a
/// `quoted-string`, so the only conformant thing to do with one is to not emit it. See
/// [`step_up_challenge`] for why the value can contain one in the first place.
///
/// [`char::is_control`] is not the test used here: it is true for the Unicode `Cc` category, which
/// includes `%x80..=%x9F`, and those are `obs-text` and therefore legal. The ranges are written out
/// instead, and every scalar value above `%x7F` is kept.
fn push_quoted(out: &mut String, value: &str) {
    for c in value.chars() {
        match c {
            '"' | '\\' => {
                out.push('\\');
                out.push(c);
            }
            '\t' | ' ' | '\u{21}'..='\u{7e}' | '\u{80}'.. => out.push(c),
            // Everything else is %x00-%x08, %x0A-%x1F or %x7F, none of which a `quoted-string` can
            // carry escaped or otherwise.
            _ => {}
        }
    }
}

/// RFC 9110 section 5.6.2 `tchar`, the character set an auth scheme (section 11.1 `auth-scheme`,
/// which is a `token`) is made of.
///
/// Used to filter [`step_up_challenge`]'s `scheme`, which is written outside every quoted string in
/// the challenge and so has no escape available to it at all: one space in it and everything after
/// it reads as the auth parameters of a different scheme, one `"` and the quoting is off by one for
/// the rest of the header.
fn is_tchar(c: char) -> bool {
    c.is_ascii_alphanumeric() || "!#$%&'*+-.^_`|~".contains(c)
}

#[cfg(test)]
#[path = "tests/consent.rs"]
mod tests;