didbot_serve/oauth/

dpop.rs

//! DPoP proof verification (RFC 9449), the verifier side.
//!
//! jacquard's OAuth client (`jacquard-oauth`, pinned alongside
//! `jacquard-common`) builds DPoP proofs and never checks one; this module is
//! the other half. It exists so that an authorization server or resource
//! server built on top of `didbot-serve` -- sibling work under
//! `crates/didbot-serve/src/oauth/`, see `plan/oauth.md` -- can hold one
//! [`DpopVerifier`] and call [`DpopVerifier::verify`] once per protected
//! request, rather than re-deriving RFC 9449 §4.3's checklist at each call
//! site.
//!
//! # What a proof is
//!
//! A DPoP proof is a compact JWS: three base64url segments, `header.
//! payload.signature`, with no `.` inside a segment. This verifier accepts
//! exactly the shape jacquard's client mints (`jacquard-oauth-0.12.1`'s
//! `dpop::build_dpop_proof`), because that shape is this ecosystem's proof of
//! what a conformant client actually sends:
//!
//! * Header: `{"alg":"ES256","typ":"dpop+jwt","jwk":{"kty":"EC","crv":
//!   "P-256","x":..,"y":..}}` -- an EC P-256 public key embedded in the
//!   header, never a `kid` pointing elsewhere. Only ES256 is accepted;
//!   nothing else is a DPoP key jacquard's client can produce, and `none` is
//!   never entertained.
//! * Payload: `jti`, `iat`, `htm`, `htu`, and optionally `ath` (a hash of the
//!   access token this proof accompanies) and `nonce` (echoing a server-
//!   issued value). jacquard's proofs carry no `exp` -- RFC 9449 does not
//!   require one, freshness is `iat` plus the verifier's own window instead,
//!   which is [`DpopVerifier::verify`]'s clock-skew check below.
//! * Signature: a 64-byte compact `r || s` pair over `header.payload`, ES256.
//!
//! # What this module checks, and in what order
//!
//! [`presented_proof`] makes RFC 9449 §4.3's first check before any other:
//! a request carries one `DPoP` header. [`DpopVerifier::verify`] then checks
//! `typ`, `alg`, the embedded key and the signature, so nothing in the
//! payload is read before it is known to be signed. Then `htm`, `htu`, `iat`, the nonce and `jti` replay, and last
//! the two bindings: the proof's key against the thumbprint an access token
//! is bound to, and `ath` against the token itself. RFC 9449 §4.3 allows any
//! order; the nonce comes before replay and `ath`, as in the reference
//! provider. Structure or signature failures are reported before content is
//! trusted, and a content mismatch never reads as a signature failure -- see
//! [`DpopError`]'s variants, each of which names the one thing that did not
//! check out.
//!
//! # Replay is a two-step
//!
//! `verify` reads the replay window and [`DpopVerifier::accept`] writes it.
//! A caller verifies the proof, resolves the credential it arrived with, and
//! only then accepts: that is what keeps an entry from being something an
//! unauthenticated caller can spend, since every route that takes a proof
//! can be reached with a freshly generated key and no credential at all.
//!
//! The window is in memory, so a restart empties it. For the first
//! clock-skew window after one, a proof stamped before the process started
//! is refused with [`DpopError::PredatesStart`] — its own answer, so it
//! never reads as a clock disagreeing. Past that window the clock check
//! refuses every proof old enough to be worth replaying.
//!
//! # Nonces
//!
//! A verifier built with `require_nonce` refuses a proof that carries no
//! nonce it accepts, and names the one to retry with. It hands out one
//! nonce at a time, the same to every client, for `nonce_ttl`; the first
//! time one is asked for after that, a fresh one replaces it. The replaced
//! nonce is still accepted for one more `nonce_ttl`, so a request in flight
//! across a rotation is not refused for it. A refusal replaces nothing, so a
//! caller sending wrong nonces cannot move the one an honest client holds.

use std::sync::Mutex;

use axum::http::{HeaderMap, HeaderName, Method};
use base64::prelude::*;
use p256::ecdsa::signature::Verifier as _;
use p256::ecdsa::{Signature as P256Signature, VerifyingKey as P256VerifyingKey};
use rand_core::{OsRng, RngCore};
use serde::Deserialize;
use sha2::{Digest, Sha256};
use time::{Duration, OffsetDateTime};

use crate::auth::constant_time_eq;
use crate::replay::{Spent, SpentKeys, MAX_JTI_BYTES, REPLAY_CAPACITY};

/// The `typ` header RFC 9449 §4.2 requires on every DPoP proof JWT.
const JWT_TYP: &str = "dpop+jwt";

/// The one JWS algorithm this verifier accepts.
///
/// DPoP proofs in the wild are frequently ES256 -- P-256 is one of the two
/// curves atproto signing keys use, and it is the curve `jacquard-oauth`'s
/// client mints (`jacquard_oauth::dpop::build_dpop_proof` refuses to build
/// with anything else). `didbot-key`'s `secp256r1` module documents why this
/// workspace mints no P-256 *signing* key but does verify them: a key that
/// arrives from somewhere else is not ours to normalize, only to judge. The
/// same reasoning applies here.
pub(crate) const JWT_ALG: &str = "ES256";

const JWK_KTY: &str = "EC";
const JWK_CRV: &str = "P-256";

/// A raw, uninterpreted 32-byte EC coordinate, base64url-decoded from a JWK's
/// `x` or `y` member.
type Coordinate = [u8; 32];

/// The DPoP proof header this verifier is willing to read.
///
/// Only the members RFC 9449 requires. An unrecognised extra header member
/// (`kid`, `x5c`, and so on) is ignored rather than refused: nothing here
/// reads it, and a proof jacquard's client would never emit one, but refusing
/// on an unknown member the RFC does not forbid would be a stricter reading
/// than the spec supports.
#[derive(Debug, Deserialize)]
struct ProofHeader {
    alg: String,
    typ: Option<String>,
    jwk: Option<RawJwk>,
}

/// An embedded JWK, exactly as RFC 7517 §4 and RFC 7518 §6.2 name an EC
/// public key's members. Decoded lazily -- `x` and `y` stay base64url text
/// here, because [`Coordinate`] decoding has its own error to report and
/// [`RawJwk`] itself has none to give it.
#[derive(Debug, Clone, Deserialize)]
struct RawJwk {
    kty: String,
    crv: Option<String>,
    x: Option<String>,
    y: Option<String>,
}

/// The DPoP proof payload this verifier reads. RFC 9449 §4.2's required
/// claims, plus the two optional ones (`ath`, `nonce`) this module checks
/// when a caller asks it to.
#[derive(Debug, Deserialize)]
struct ProofClaims {
    jti: Option<String>,
    htm: Option<String>,
    htu: Option<String>,
    iat: Option<i64>,
    #[serde(default)]
    ath: Option<String>,
    #[serde(default)]
    nonce: Option<String>,
}

/// Why a presented DPoP proof, or the binding it claims, was refused.
///
/// Each variant names the one check that failed rather than folding every
/// failure into a single "invalid proof" -- in particular
/// [`DpopError::ClockSkew`] carries both timestamps and the window, so a
/// refusal caused by clock drift between two honest clocks reads as exactly
/// that rather than as a forged signature.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum DpopError {
    /// The request carried more than one `DPoP` header.
    MoreThanOneProof,
    /// Not three `.`-separated segments.
    Malformed,
    /// A segment was not valid, unpadded base64url, or the JSON it decoded
    /// to did not have the shape this module reads. The `&'static str` names
    /// which segment.
    InvalidEncoding(&'static str),
    /// A required claim (`jti`, `htm`, `htu`, or `iat`) was absent.
    MissingClaim(&'static str),
    /// The `jti` is longer than [`MAX_JTI_BYTES`], so the replay window
    /// will not keep it.
    JtiTooLong {
        /// How long it was, in bytes.
        length: usize,
    },
    /// `typ` was missing, or present and not `"dpop+jwt"`.
    WrongTyp(Option<String>),
    /// `alg` was not `"ES256"`.
    UnsupportedAlgorithm(String),
    /// The embedded `jwk` did not name an EC P-256 key with well-formed `x`
    /// and `y` members, or did not decode to a point on the curve.
    UnsupportedKey,
    /// The signature did not verify over `header.payload`.
    BadSignature,
    /// `htm` did not match the request's method.
    MethodMismatch {
        /// What the proof claimed.
        proof: String,
        /// What the request actually was.
        expected: String,
    },
    /// `htu` did not match the request's target, once both are normalized
    /// (query and fragment dropped, scheme and host lowercased).
    UriMismatch {
        /// What the proof claimed.
        proof: String,
        /// What the caller told this verifier to expect.
        expected: String,
    },
    /// `iat` fell outside the accepted clock-skew window.
    ClockSkew {
        /// The proof's own `iat`, as an absolute time.
        iat: OffsetDateTime,
        /// This verifier's own clock at the moment it checked.
        now: OffsetDateTime,
        /// The window on either side of `now` that would have been accepted.
        window: Duration,
    },
    /// The proof was stamped before this verifier began accepting proofs,
    /// and it is still inside the first clock-skew window since. Its own
    /// refusal rather than [`DpopError::ClockSkew`], because the clocks
    /// agree: the proof is simply older than the replay window can speak
    /// for.
    PredatesStart {
        /// The proof's own `iat`, as an absolute time.
        iat: OffsetDateTime,
        /// When this verifier began accepting proofs.
        started: OffsetDateTime,
    },
    /// This `jti` was already accepted once, inside the window during which
    /// it is still considered fresh.
    Replayed {
        /// The repeated `jti`.
        jti: String,
    },
    /// The replay window is holding as many `jti`s as it will, so this
    /// verifier cannot promise this one has not been seen. Refused rather
    /// than admitted: a replay cache that forgets to make room is a replay
    /// cache that lets one through. See [`REPLAY_CAPACITY`].
    ReplayWindowFull,
    /// A binding was requested (`expected_thumbprint` in
    /// [`DpopVerifier::verify`]) and the proof's key does not have it.
    ThumbprintMismatch,
    /// An access token was supplied to check against and the proof's `ath`
    /// does not hash to it -- either absent or wrong.
    AccessTokenHashMismatch,
    /// This verifier requires a nonce and the proof carried none. The client
    /// resolves this by retrying with the carried nonce, which is now the
    /// only nonce this verifier accepts.
    NonceRequired {
        /// The nonce to retry with.
        fresh: String,
    },
    /// A nonce was presented and it is not one this verifier currently
    /// accepts. Same resolution as [`DpopError::NonceRequired`].
    NonceMismatch {
        /// The nonce to retry with.
        fresh: String,
    },
}

impl std::fmt::Display for DpopError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            DpopError::MoreThanOneProof => write!(
                f,
                "a request carries one DPoP proof, and this one carries more than one"
            ),
            DpopError::Malformed => {
                write!(
                    f,
                    "a DPoP proof is three '.'-separated segments; this was not"
                )
            }
            DpopError::InvalidEncoding(part) => {
                write!(
                    f,
                    "the proof's {part} did not decode as unpadded base64url JSON"
                )
            }
            DpopError::MissingClaim(claim) => {
                write!(f, "the proof's payload has no `{claim}` claim")
            }
            DpopError::JtiTooLong { length } => write!(
                f,
                "the proof's `jti` is {length} bytes, longer than the {MAX_JTI_BYTES} this \
                 verifier keeps"
            ),
            DpopError::WrongTyp(got) => write!(
                f,
                "the proof's `typ` header must be {JWT_TYP:?}, got {got:?}"
            ),
            DpopError::UnsupportedAlgorithm(got) => write!(
                f,
                "the proof's `alg` header must be {JWT_ALG:?}, got {got:?}"
            ),
            DpopError::UnsupportedKey => write!(
                f,
                "the proof's embedded `jwk` is not a well-formed EC P-256 public key"
            ),
            DpopError::BadSignature => {
                write!(
                    f,
                    "the proof's signature does not verify against its own embedded key"
                )
            }
            DpopError::MethodMismatch { proof, expected } => write!(
                f,
                "the proof's `htm` claim is {proof:?}, this request is {expected:?}"
            ),
            DpopError::UriMismatch { proof, expected } => write!(
                f,
                "the proof's `htu` claim is {proof:?}, this request targets {expected:?}"
            ),
            DpopError::ClockSkew { iat, now, window } => write!(
                f,
                "the proof was issued at {iat} and checked at {now}, outside the \
                 {window}-second clock-skew window either side of it",
                window = window.whole_seconds(),
            ),
            DpopError::PredatesStart { iat, started } => write!(
                f,
                "the proof was issued at {iat}, before this server began accepting proofs \
                 at {started}; mint a fresh proof"
            ),
            DpopError::Replayed { jti } => {
                write!(f, "the proof's `jti` {jti:?} has already been used")
            }
            DpopError::ReplayWindowFull => write!(
                f,
                "this verifier's replay window is full and cannot accept another proof right now"
            ),
            DpopError::ThumbprintMismatch => write!(
                f,
                "the proof's key does not have the thumbprint this credential is bound to"
            ),
            DpopError::AccessTokenHashMismatch => write!(
                f,
                "the proof's `ath` claim does not hash the access token it accompanies"
            ),
            DpopError::NonceRequired { .. } => {
                write!(
                    f,
                    "this verifier requires a DPoP nonce and the proof carried none"
                )
            }
            DpopError::NonceMismatch { .. } => write!(
                f,
                "the proof's `nonce` claim is not one this verifier currently accepts"
            ),
        }
    }
}

impl std::error::Error for DpopError {}

impl DpopError {
    /// The nonce a client should retry with, for the two refusals that
    /// carry one.
    pub fn fresh_nonce(&self) -> Option<&str> {
        match self {
            DpopError::NonceRequired { fresh } | DpopError::NonceMismatch { fresh } => {
                Some(fresh.as_str())
            }
            _ => None,
        }
    }
}

/// `DPoP-Nonce`, the response header a server hands a client a nonce in --
/// RFC 9449 §8.
pub const DPOP_NONCE: HeaderName = HeaderName::from_static("dpop-nonce");

/// `DPoP`, the request header a proof travels in -- RFC 9449 §4.1.
pub const DPOP: HeaderName = HeaderName::from_static("dpop");

/// The DPoP proof a request carries, if it carries one.
///
/// RFC 9449 §4.3's first check: a request with more than one `DPoP` header
/// is refused, so which proof the server checked is never a guess.
pub fn presented_proof(headers: &HeaderMap) -> Result<Option<&str>, DpopError> {
    let mut proofs = headers.get_all(DPOP).iter();
    let Some(proof) = proofs.next() else {
        return Ok(None);
    };
    if proofs.next().is_some() {
        return Err(DpopError::MoreThanOneProof);
    }
    proof.to_str().map(Some).map_err(|_| DpopError::Malformed)
}

/// What a successfully verified proof establishes.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VerifiedProof {
    /// The proof's `jti`, now recorded in the replay cache.
    pub jti: String,
    /// The proof's `iat`, as an absolute time.
    pub iat: OffsetDateTime,
    /// The RFC 7638 thumbprint of the key the proof was signed with. An
    /// authorization server mints an access token's `cnf.jkt` from this; a
    /// resource server compares it against one.
    pub thumbprint: String,
}

/// Proof checking, nonce issuance, and the replay cache, held together
/// because the replay window and the clock-skew window are the same number
/// -- see [`DpopVerifier::new`].
///
/// One instance covers one nonce space. This deployment's authorization
/// server and resource server are one origin and hold one verifier between
/// them, which the atproto profile allows: "The Resource Server and
/// Authorization Server may share nonces (especially if they are the same
/// server)".
pub struct DpopVerifier {
    /// How far from this verifier's own clock a proof's `iat` may sit,
    /// either direction, and also how long a `jti` is retained in the replay
    /// cache: past that point the proof itself would fail the clock check on
    /// a second presentation, so retaining it longer catches nothing a resend
    /// would not already be refused for.
    skew: Duration,
    /// How long a nonce is handed out before a fresh one replaces it. The
    /// replaced nonce is accepted for as long again.
    nonce_ttl: Duration,
    /// Whether [`DpopVerifier::verify`] requires a nonce, and so whether
    /// this verifier hands any out.
    require_nonce: bool,
    /// When this verifier began accepting proofs, to the whole second.
    ///
    /// The replay window is in memory, so a restart empties it and a proof
    /// captured just before the restart would verify a second time. For
    /// the first `skew` after this instant a proof stamped earlier than it
    /// is refused, which is exactly the window the emptied cache could
    /// have covered. Past that, no proof old enough to matter still
    /// passes the clock check.
    ///
    /// Whole seconds because `iat` is whole seconds: a proof minted inside
    /// the second this verifier started reads as minted at the start, and
    /// is accepted.
    started: OffsetDateTime,
    /// `jti` values already accepted, and when each one falls out of the
    /// window in which it could still be replayed usefully.
    ///
    /// An entry is spent by [`DpopVerifier::accept`], which a caller reaches
    /// only once the credential the proof arrived with has checked out, so
    /// filling [`REPLAY_CAPACITY`] takes that many authenticated requests
    /// inside one clock-skew window.
    replay: Mutex<SpentKeys>,
    nonces: Mutex<NonceState>,
}

/// The nonce this verifier hands out, and the one it handed out before it,
/// each with the instant it stops or stopped being handed out. Both are
/// accepted until one `nonce_ttl` past that instant.
#[derive(Default)]
struct NonceState {
    current: Option<(String, OffsetDateTime)>,
    previous: Option<(String, OffsetDateTime)>,
}

impl NonceState {
    /// Whether `presented` is a nonce held here that is still accepted at
    /// `now`, `ttl` past the instant it stopped being handed out.
    fn honours(&self, presented: &str, now: OffsetDateTime, ttl: Duration) -> bool {
        [&self.current, &self.previous]
            .into_iter()
            .flatten()
            .any(|(nonce, until)| nonce == presented && now < *until + ttl)
    }
}

impl DpopVerifier {
    /// Builds a verifier with the given clock-skew/replay window, nonce
    /// lifetime, and whether a nonce is required at all.
    /// `OAuthState::default` supplies this deployment's numbers.
    pub fn new(skew: Duration, nonce_ttl: Duration, require_nonce: bool) -> Self {
        Self::started_at(skew, nonce_ttl, require_nonce, OffsetDateTime::now_utc())
    }

    /// [`DpopVerifier::new`] with the instant it began accepting proofs
    /// given rather than read off the clock, so a test can put a proof on
    /// either side of it.
    fn started_at(
        skew: Duration,
        nonce_ttl: Duration,
        require_nonce: bool,
        started: OffsetDateTime,
    ) -> Self {
        let started = OffsetDateTime::from_unix_timestamp(started.unix_timestamp())
            .unwrap_or(OffsetDateTime::UNIX_EPOCH);
        Self {
            skew,
            nonce_ttl,
            require_nonce,
            started,
            replay: Mutex::new(SpentKeys::new(REPLAY_CAPACITY, started)),
            nonces: Mutex::new(NonceState::default()),
        }
    }

    /// The nonce to hand a client in `DPoP-Nonce`: the one this verifier
    /// hands out now, replaced with a fresh one once it has been handed out
    /// for `nonce_ttl`.
    pub fn current_nonce(&self) -> String {
        self.current_nonce_at(OffsetDateTime::now_utc())
    }

    fn current_nonce_at(&self, now: OffsetDateTime) -> String {
        let mut state = self.nonces.lock().unwrap_or_else(|p| p.into_inner());
        if let Some((nonce, until)) = &state.current {
            if now < *until {
                return nonce.clone();
            }
        }
        let fresh = random_nonce();
        state.previous = state.current.replace((fresh.clone(), now + self.nonce_ttl));
        fresh
    }

    /// Verifies a DPoP proof JWT against a request.
    ///
    /// `method` and `htu` describe the request this proof must be bound to;
    /// `htu` is a caller-built canonical absolute URL (scheme, host, and
    /// path -- no query, no fragment) because assembling one correctly behind
    /// a reverse proxy is a deployment concern this module has no way to get
    /// right on its own; see `axum::extract::OriginalUri` and the `Host`
    /// header for how a caller typically builds it.
    ///
    /// `access_token`, if given, is checked against the proof's `ath` claim
    /// (RFC 9449 §4.3's binding of a proof to a specific bearer of a
    /// specific access token). `expected_thumbprint`, if given, is checked
    /// against the RFC 7638 thumbprint of the proof's own key -- the check
    /// that makes a copied access token useless to whoever copied it,
    /// because their proof is signed by a different key with a different
    /// thumbprint.
    pub fn verify(
        &self,
        proof_jwt: &str,
        method: &Method,
        htu: &str,
        access_token: Option<&str>,
        expected_thumbprint: Option<&str>,
    ) -> Result<VerifiedProof, DpopError> {
        self.verify_at(
            proof_jwt,
            method,
            htu,
            access_token,
            expected_thumbprint,
            OffsetDateTime::now_utc(),
        )
    }

    fn verify_at(
        &self,
        proof_jwt: &str,
        method: &Method,
        htu: &str,
        access_token: Option<&str>,
        expected_thumbprint: Option<&str>,
        now: OffsetDateTime,
    ) -> Result<VerifiedProof, DpopError> {
        let mut segments = proof_jwt.split('.');
        let (Some(header_b64), Some(payload_b64), Some(sig_b64), None) = (
            segments.next(),
            segments.next(),
            segments.next(),
            segments.next(),
        ) else {
            return Err(DpopError::Malformed);
        };

        // -- header: typ, alg, jwk -------------------------------------
        // `URL_SAFE_NO_PAD` refuses padding and a final character with
        // unused bits set, so each segment has one spelling.
        let header_json = BASE64_URL_SAFE_NO_PAD
            .decode(header_b64)
            .map_err(|_| DpopError::InvalidEncoding("header"))?;
        let header: ProofHeader = serde_json::from_slice(&header_json)
            .map_err(|_| DpopError::InvalidEncoding("header"))?;
        if header.typ.as_deref() != Some(JWT_TYP) {
            return Err(DpopError::WrongTyp(header.typ));
        }
        if header.alg != JWT_ALG {
            return Err(DpopError::UnsupportedAlgorithm(header.alg));
        }
        let jwk = header.jwk.ok_or(DpopError::UnsupportedKey)?;
        let (x, y) = decode_ec_point(&jwk)?;

        // -- signature ----------------------------------------------------
        let verifying_key = p256_verifying_key(&x, &y)?;
        let sig_bytes = BASE64_URL_SAFE_NO_PAD
            .decode(sig_b64)
            .map_err(|_| DpopError::InvalidEncoding("signature"))?;
        let sig_bytes: [u8; 64] = sig_bytes.try_into().map_err(|_| DpopError::BadSignature)?;
        let signature =
            P256Signature::from_slice(&sig_bytes).map_err(|_| DpopError::BadSignature)?;
        let signing_input = format!("{header_b64}.{payload_b64}");
        verifying_key
            .verify(signing_input.as_bytes(), &signature)
            .map_err(|_| DpopError::BadSignature)?;

        // -- payload: only trusted once the signature above verified -----
        let payload_json = BASE64_URL_SAFE_NO_PAD
            .decode(payload_b64)
            .map_err(|_| DpopError::InvalidEncoding("payload"))?;
        let claims: ProofClaims = serde_json::from_slice(&payload_json)
            .map_err(|_| DpopError::InvalidEncoding("payload"))?;
        let jti = claims.jti.ok_or(DpopError::MissingClaim("jti"))?;
        if jti.len() > MAX_JTI_BYTES {
            return Err(DpopError::JtiTooLong { length: jti.len() });
        }
        let htm = claims.htm.ok_or(DpopError::MissingClaim("htm"))?;
        let claimed_htu = claims.htu.ok_or(DpopError::MissingClaim("htu"))?;
        let iat_ts = claims.iat.ok_or(DpopError::MissingClaim("iat"))?;

        if !htm.eq_ignore_ascii_case(method.as_str()) {
            return Err(DpopError::MethodMismatch {
                proof: htm,
                expected: method.as_str().to_owned(),
            });
        }
        match (normalize_htu(&claimed_htu), normalize_htu(htu)) {
            (Some(a), Some(b)) if a == b => {}
            _ => {
                return Err(DpopError::UriMismatch {
                    proof: claimed_htu,
                    expected: htu.to_owned(),
                })
            }
        }

        let iat = OffsetDateTime::from_unix_timestamp(iat_ts)
            .map_err(|_| DpopError::InvalidEncoding("payload"))?;
        if iat < now - self.skew || iat > now + self.skew {
            return Err(DpopError::ClockSkew {
                iat,
                now,
                window: self.skew,
            });
        }
        // The replay window below is in memory. For the first `skew` after
        // this verifier started, it cannot speak for a proof minted before
        // it existed, so such a proof is refused rather than admitted on an
        // empty cache's say-so. After that window every such proof already
        // fails the check above.
        if now < self.started + self.skew && iat < self.started {
            return Err(DpopError::PredatesStart {
                iat,
                started: self.started,
            });
        }

        // -- nonce, before replay and `ath`, as the reference provider --
        if self.require_nonce {
            self.check_nonce_at(claims.nonce.as_deref(), now)?;
        }

        // -- replay, over jti, read but not written ------------------------
        //
        // An already-recorded `jti` is refused here, before anything else is
        // spent on this proof. Recording one is [`DpopVerifier::accept`]'s,
        // called once the credential the proof arrived with has checked out
        // — see that method for why an entry is not the verifier's to spend
        // on an unauthenticated caller's say-so.
        //
        // Swept once per window rather than on every proof: a full scan per
        // call makes one caller's cost grow with how many other callers
        // there are. Amortized this way an entry outlives its window by at
        // most one more.
        {
            let mut replay = self.replay.lock().unwrap_or_else(|p| p.into_inner());
            replay.sweep_if_due(now, self.skew);
            if replay.holds(&jti) {
                return Err(DpopError::Replayed { jti });
            }
        }

        // -- the bindings: the key an access token is bound to, and ath ----
        let thumbprint = jwk_thumbprint(&x, &y);
        if let Some(expected) = expected_thumbprint {
            if !constant_time_eq(thumbprint.as_bytes(), expected.as_bytes()) {
                return Err(DpopError::ThumbprintMismatch);
            }
        }
        if let Some(token) = access_token {
            let expected_ath = BASE64_URL_SAFE_NO_PAD.encode(Sha256::digest(token.as_bytes()));
            match &claims.ath {
                Some(ath) if constant_time_eq(ath.as_bytes(), expected_ath.as_bytes()) => {}
                _ => return Err(DpopError::AccessTokenHashMismatch),
            }
        }

        Ok(VerifiedProof {
            jti,
            iat,
            thumbprint,
        })
    }

    /// Records a verified proof's `jti`, so that presenting the same proof
    /// again is [`DpopError::Replayed`].
    ///
    /// Called once the credential the proof arrived with has checked out —
    /// the access token at a repo write, the authorization code or the
    /// refresh token at `POST /oauth/token`. Before that, nothing about the
    /// caller is known: `POST /oauth/token`'s refresh grant is reachable
    /// with any freshly generated key, so an entry spent at
    /// [`DpopVerifier::verify`] is an entry an unauthenticated caller spends,
    /// and the window would fill with proofs naming no credential at all.
    ///
    /// [`DpopError::ReplayWindowFull`] rather than an eviction, for
    /// [`REPLAY_CAPACITY`]'s own reason: dropping an entry that still names
    /// a live proof is how a full cache becomes a way to get a replay
    /// accepted.
    pub fn accept(&self, proof: &VerifiedProof) -> Result<(), DpopError> {
        self.accept_at(proof, OffsetDateTime::now_utc())
    }

    fn accept_at(&self, proof: &VerifiedProof, now: OffsetDateTime) -> Result<(), DpopError> {
        let mut replay = self.replay.lock().unwrap_or_else(|p| p.into_inner());
        replay
            .spend(proof.jti.clone(), proof.iat + self.skew, now)
            .map_err(|refusal| match refusal {
                Spent::Replayed => DpopError::Replayed {
                    jti: proof.jti.clone(),
                },
                Spent::WindowFull => DpopError::ReplayWindowFull,
            })
    }

    /// Accepts a nonce this verifier handed out and still honours. A
    /// refusal names the nonce every client is being handed, and replaces
    /// nothing.
    fn check_nonce_at(
        &self,
        presented: Option<&str>,
        now: OffsetDateTime,
    ) -> Result<(), DpopError> {
        let accepted = presented.is_some_and(|presented| {
            self.nonces
                .lock()
                .unwrap_or_else(|p| p.into_inner())
                .honours(presented, now, self.nonce_ttl)
        });
        if accepted {
            return Ok(());
        }
        let fresh = self.current_nonce_at(now);
        match presented {
            None => Err(DpopError::NonceRequired { fresh }),
            Some(_) => Err(DpopError::NonceMismatch { fresh }),
        }
    }
}

/// The RFC 7638 JWK thumbprint of an EC P-256 public key, from its raw
/// coordinates.
///
/// A standalone entry point as well as [`DpopVerifier::verify`]'s internal
/// step: an authorization server mints a token's `cnf.jkt` from the DPoP
/// proof presented at the token endpoint, before any resource-server
/// verifier is in the picture, and needs this without a whole [`DpopVerifier`]
/// to get it.
pub fn jwk_thumbprint(x: &Coordinate, y: &Coordinate) -> String {
    // RFC 7638 §3.2: the JSON object over exactly the required members for
    // the key type, ordered lexicographically by member name, no
    // insignificant whitespace. For an EC key that is `crv`, `kty`, `x`,
    // `y` -- already alphabetical, so no separate sort is needed here.
    let x = BASE64_URL_SAFE_NO_PAD.encode(x);
    let y = BASE64_URL_SAFE_NO_PAD.encode(y);
    let canonical = format!(r#"{{"crv":"{JWK_CRV}","kty":"{JWK_KTY}","x":"{x}","y":"{y}"}}"#);
    BASE64_URL_SAFE_NO_PAD.encode(Sha256::digest(canonical.as_bytes()))
}

/// Decodes a JWK's `x`/`y` members into raw coordinates, refusing anything
/// that is not an EC P-256 key with both present and exactly 32 bytes long.
fn decode_ec_point(jwk: &RawJwk) -> Result<(Coordinate, Coordinate), DpopError> {
    if jwk.kty != JWK_KTY || jwk.crv.as_deref() != Some(JWK_CRV) {
        return Err(DpopError::UnsupportedKey);
    }
    let x = jwk.x.as_deref().ok_or(DpopError::UnsupportedKey)?;
    let y = jwk.y.as_deref().ok_or(DpopError::UnsupportedKey)?;
    let x = BASE64_URL_SAFE_NO_PAD
        .decode(x)
        .map_err(|_| DpopError::UnsupportedKey)?;
    let y = BASE64_URL_SAFE_NO_PAD
        .decode(y)
        .map_err(|_| DpopError::UnsupportedKey)?;
    let x: Coordinate = x.try_into().map_err(|_| DpopError::UnsupportedKey)?;
    let y: Coordinate = y.try_into().map_err(|_| DpopError::UnsupportedKey)?;
    Ok((x, y))
}

/// Builds a verifying key from raw coordinates, the same SEC1-uncompressed
/// route `didbot_key::secp256r1::VerifyingKey::from_multibase` takes -- see
/// that module's doc for why a key that arrives from elsewhere is judged
/// rather than normalized.
fn p256_verifying_key(x: &Coordinate, y: &Coordinate) -> Result<P256VerifyingKey, DpopError> {
    let mut sec1 = [0u8; 65];
    sec1[0] = 0x04;
    sec1[1..33].copy_from_slice(x);
    sec1[33..65].copy_from_slice(y);
    let public = p256::PublicKey::from_sec1_bytes(&sec1).map_err(|_| DpopError::UnsupportedKey)?;
    Ok(public.into())
}

/// Strips query and fragment and lowercases scheme and host, so that `htu`
/// comparison follows RFC 9449 §4.3's "the same server can use different
/// forms" allowance without demanding byte-identical strings for two URLs
/// that name the same resource.
fn normalize_htu(raw: &str) -> Option<String> {
    let raw = raw.split(['?', '#']).next().unwrap_or(raw);
    let (scheme, rest) = raw.split_once("://")?;
    let (authority, path) = match rest.find('/') {
        Some(idx) => (&rest[..idx], &rest[idx..]),
        None => (rest, ""),
    };
    Some(format!(
        "{}://{}{}",
        scheme.to_ascii_lowercase(),
        authority.to_ascii_lowercase(),
        path
    ))
}

/// A fresh nonce: 18 CSPRNG-drawn bytes, base64url. The same entropy source
/// `didbot_pds::credential`'s bearer tokens draw from.
fn random_nonce() -> String {
    let mut bytes = [0u8; 18];
    OsRng.fill_bytes(&mut bytes);
    BASE64_URL_SAFE_NO_PAD.encode(bytes)
}

// -- the seam every route holds ---------------------------------------------
//
// `oauth::token`, `crate::auth` and the OAuth routes hold a `dyn
// dpop_seam::DpopVerifier`. The adapter verifies a proof against the request
// and the access token alone, with no thumbprint binding of its own: that
// binding happens one layer up, once a token's `cnf.jkt` is on hand to check
// it against (`oauth::token::OAuthTokenStore::validate_access`). A nonce
// refusal crosses the seam with the nonce to retry with, so each caller can
// answer it the way RFC 9449 asks of it.
impl crate::oauth::dpop_seam::DpopVerifier for DpopVerifier {
    fn verify(
        &self,
        proof: &str,
        http_method: &str,
        http_uri: &str,
        access_token: Option<&str>,
    ) -> Result<crate::oauth::dpop_seam::VerifiedProof, crate::oauth::dpop_seam::DpopError> {
        let method: Method = http_method.parse().map_err(|_| {
            crate::oauth::dpop_seam::DpopError::Refused(format!(
                "`{http_method}` is not a valid HTTP method"
            ))
        })?;
        self.verify(proof, &method, http_uri, access_token, None)
            .map(|verified| crate::oauth::dpop_seam::VerifiedProof {
                thumbprint: crate::oauth::dpop_seam::DpopThumbprint(verified.thumbprint),
                jti: verified.jti,
                iat: verified.iat,
            })
            .map_err(|err| match err.fresh_nonce() {
                Some(nonce) => crate::oauth::dpop_seam::DpopError::UseNonce {
                    nonce: nonce.to_owned(),
                    message: err.to_string(),
                },
                None => crate::oauth::dpop_seam::DpopError::Refused(err.to_string()),
            })
    }

    fn accept(
        &self,
        proof: &crate::oauth::dpop_seam::VerifiedProof,
    ) -> Result<(), crate::oauth::dpop_seam::DpopError> {
        self.accept(&VerifiedProof {
            jti: proof.jti.clone(),
            iat: proof.iat,
            thumbprint: proof.thumbprint.0.clone(),
        })
        .map_err(|err| crate::oauth::dpop_seam::DpopError::Refused(err.to_string()))
    }

    fn nonce(&self) -> Option<String> {
        self.require_nonce.then(|| self.current_nonce())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use p256::ecdsa::signature::Signer as _;
    use p256::ecdsa::SigningKey;
    use serde_json::json;

    /// A proof builder that mirrors `jacquard-oauth-0.12.1`'s
    /// `dpop::build_dpop_proof` byte-for-byte in its default shape, but takes
    /// every field explicitly so a test can bend exactly one of them.
    struct ProofBuilder {
        key: SigningKey,
        typ: &'static str,
        alg: &'static str,
        htm: String,
        htu: String,
        jti: String,
        iat: i64,
        nonce: Option<String>,
        ath: Option<String>,
    }

    impl ProofBuilder {
        fn new(key: &SigningKey, htm: &str, htu: &str) -> Self {
            Self {
                key: key.clone(),
                typ: JWT_TYP,
                alg: JWT_ALG,
                htm: htm.to_owned(),
                htu: htu.to_owned(),
                jti: "test-jti-0".to_owned(),
                iat: OffsetDateTime::now_utc().unix_timestamp(),
                nonce: None,
                ath: None,
            }
        }

        fn jti(mut self, jti: &str) -> Self {
            self.jti = jti.to_owned();
            self
        }

        fn iat(mut self, iat: OffsetDateTime) -> Self {
            self.iat = iat.unix_timestamp();
            self
        }

        fn nonce(mut self, nonce: &str) -> Self {
            self.nonce = Some(nonce.to_owned());
            self
        }

        fn ath(mut self, access_token: &str) -> Self {
            self.ath = Some(BASE64_URL_SAFE_NO_PAD.encode(Sha256::digest(access_token.as_bytes())));
            self
        }

        fn build(&self) -> String {
            let verifying_key = P256VerifyingKey::from(&self.key);
            let point = verifying_key.to_encoded_point(false);
            let x = BASE64_URL_SAFE_NO_PAD.encode(point.x().expect("uncompressed point has x"));
            let y = BASE64_URL_SAFE_NO_PAD.encode(point.y().expect("uncompressed point has y"));
            let header = json!({
                "alg": self.alg,
                "typ": self.typ,
                "jwk": {"kty": "EC", "crv": "P-256", "x": x, "y": y},
            });
            let mut payload = json!({
                "jti": self.jti,
                "iat": self.iat,
                "htm": self.htm,
                "htu": self.htu,
            });
            if let Some(nonce) = &self.nonce {
                payload["nonce"] = json!(nonce);
            }
            if let Some(ath) = &self.ath {
                payload["ath"] = json!(ath);
            }
            let header_b64 = BASE64_URL_SAFE_NO_PAD.encode(serde_json::to_vec(&header).unwrap());
            let payload_b64 = BASE64_URL_SAFE_NO_PAD.encode(serde_json::to_vec(&payload).unwrap());
            let signing_input = format!("{header_b64}.{payload_b64}");
            let signature: P256Signature = self.key.sign(signing_input.as_bytes());
            let sig_b64 = BASE64_URL_SAFE_NO_PAD.encode(signature.to_bytes());
            format!("{signing_input}.{sig_b64}")
        }
    }

    fn method() -> Method {
        Method::POST
    }

    const HTU: &str = "https://pds.example/xrpc/com.atproto.repo.createRecord";

    /// A verifier with the server's windows and no nonce, for the tests
    /// about every other check. Each test builds it before it stamps a
    /// proof: a proof stamped in a second before the verifier started is
    /// refused as [`DpopError::PredatesStart`].
    fn verifier() -> DpopVerifier {
        DpopVerifier::new(Duration::minutes(5), Duration::minutes(1), false)
    }

    #[test]
    fn a_well_formed_proof_verifies_and_reports_its_thumbprint() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = verifier();
        let proof = ProofBuilder::new(&key, "POST", HTU).build();
        let verified = v
            .verify(&proof, &method(), HTU, None, None)
            .expect("a proof matching the request verifies");
        assert_eq!(verified.jti, "test-jti-0");
        assert!(!verified.thumbprint.is_empty());
    }

    /// The replay window does not survive a restart, so for the first
    /// skew window after one a proof minted before the restart is refused
    /// with its own answer. The same proof shape minted afterwards
    /// verifies.
    #[test]
    fn a_proof_minted_before_this_process_started_is_refused_after_a_restart() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let started = OffsetDateTime::from_unix_timestamp(1_800_000_000).expect("a clock");
        let verifier =
            DpopVerifier::started_at(Duration::minutes(5), Duration::minutes(1), false, started);

        let captured = ProofBuilder::new(&key, "POST", HTU)
            .iat(started - Duration::minutes(1))
            .build();
        let err = verifier
            .verify_at(
                &captured,
                &method(),
                HTU,
                None,
                None,
                started + Duration::minutes(1),
            )
            .expect_err("a proof older than this process is refused");
        assert!(
            matches!(err, DpopError::PredatesStart { .. }),
            "a restart's own refusal, not clock skew: {err:?}"
        );

        // Minted after the start, inside the same window: accepted.
        let fresh = ProofBuilder::new(&key, "POST", HTU)
            .iat(started + Duration::seconds(30))
            .build();
        verifier
            .verify_at(
                &fresh,
                &method(),
                HTU,
                None,
                None,
                started + Duration::minutes(1),
            )
            .expect("a proof minted after the start verifies");

        // Past the window, the clock check alone decides.
        let later = ProofBuilder::new(&key, "POST", HTU)
            .iat(started + Duration::minutes(10))
            .build();
        verifier
            .verify_at(
                &later,
                &method(),
                HTU,
                None,
                None,
                started + Duration::minutes(10),
            )
            .expect("past the first window nothing is refused for predating the start");
    }

    #[test]
    fn a_tampered_payload_is_refused() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = verifier();
        let proof = ProofBuilder::new(&key, "POST", HTU).build();
        let (header, rest) = proof.split_once('.').unwrap();
        let (payload, sig) = rest.split_once('.').unwrap();
        let mut claims: serde_json::Value =
            serde_json::from_slice(&BASE64_URL_SAFE_NO_PAD.decode(payload).unwrap()).unwrap();
        claims["htm"] = json!("GET");
        let tampered_payload = BASE64_URL_SAFE_NO_PAD.encode(serde_json::to_vec(&claims).unwrap());
        let tampered = format!("{header}.{tampered_payload}.{sig}");
        let err = v.verify(&tampered, &method(), HTU, None, None).unwrap_err();
        assert_eq!(err, DpopError::BadSignature);
    }

    #[test]
    fn a_replayed_jti_is_refused_the_second_time() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = verifier();
        let proof = ProofBuilder::new(&key, "POST", HTU)
            .jti("replay-me")
            .build();
        let accepted = v
            .verify(&proof, &method(), HTU, None, None)
            .expect("first presentation verifies");
        v.accept(&accepted).expect("and is recorded");
        let err = v.verify(&proof, &method(), HTU, None, None).unwrap_err();
        assert_eq!(
            err,
            DpopError::Replayed {
                jti: "replay-me".to_owned()
            }
        );
    }

    /// A `jti` is the caller's string, and the window keeps it. One past
    /// [`MAX_JTI_BYTES`] is refused before it could be kept; one at the
    /// bound verifies.
    #[test]
    fn a_jti_past_the_bound_is_refused() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = verifier();
        let past = ProofBuilder::new(&key, "POST", HTU)
            .jti(&"j".repeat(MAX_JTI_BYTES + 1))
            .build();
        assert_eq!(
            v.verify(&past, &method(), HTU, None, None).unwrap_err(),
            DpopError::JtiTooLong {
                length: MAX_JTI_BYTES + 1
            }
        );
        let at = ProofBuilder::new(&key, "POST", HTU)
            .jti(&"j".repeat(MAX_JTI_BYTES))
            .build();
        v.verify(&at, &method(), HTU, None, None)
            .expect("a jti at the bound verifies");
    }

    /// **The entry an unauthenticated caller used to spend.** A proof's
    /// `jti` was recorded the moment the proof verified, and every route
    /// that takes one can be reached with a freshly generated key and no
    /// credential. Verification alone now records nothing: the caller
    /// resolves the credential the proof arrived with and calls
    /// [`DpopVerifier::accept`], which is the only thing that spends an
    /// entry.
    #[test]
    fn verifying_a_proof_records_nothing_until_it_is_accepted() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = verifier();
        for n in 0..8 {
            let proof = ProofBuilder::new(&key, "POST", HTU)
                .jti(&format!("unauthenticated-{n}"))
                .build();
            v.verify(&proof, &method(), HTU, None, None)
                .expect("the proof itself is well formed");
        }
        assert_eq!(
            v.replay.lock().unwrap().len(),
            0,
            "a proof that authenticated nothing cost a replay-window entry"
        );
    }

    /// **The binding this closes.** The seam `auth.rs` and `token.rs` hold
    /// used to verify a proof against the request alone, with no access
    /// token to check `ath` against — so a proof minted for one token
    /// authenticated a request carrying another. RFC 9449 §7.1 requires the
    /// check, and the seam now passes the token the request presented.
    #[test]
    fn the_seam_checks_ath_against_the_token_the_request_presented() {
        // Named explicitly: this type has an inherent `verify` too, and the
        // seam's is the one every route reaches it through.
        use crate::oauth::dpop_seam::DpopVerifier as Seam;
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = verifier();

        let for_another_token = ProofBuilder::new(&key, "POST", HTU)
            .jti("ath-wrong")
            .ath("some-other-token")
            .build();
        let err =
            Seam::verify(&v, &for_another_token, "POST", HTU, Some("the-real-token")).unwrap_err();
        assert!(
            format!("{err}").contains("ath"),
            "a proof bound to another token was accepted: {err}"
        );

        let none_at_all = ProofBuilder::new(&key, "POST", HTU)
            .jti("ath-absent")
            .build();
        assert!(
            Seam::verify(&v, &none_at_all, "POST", HTU, Some("the-real-token")).is_err(),
            "a proof carrying no `ath` was accepted alongside an access token"
        );

        let bound = ProofBuilder::new(&key, "POST", HTU)
            .jti("ath-right")
            .ath("the-real-token")
            .build();
        assert!(Seam::verify(&v, &bound, "POST", HTU, Some("the-real-token")).is_ok());

        // `/oauth/token` has no access token yet, and passes `None`.
        let unbound = ProofBuilder::new(&key, "POST", HTU).jti("no-token").build();
        assert!(Seam::verify(&v, &unbound, "POST", HTU, None).is_ok());
    }

    /// **The unbounded window this closes.** Past [`REPLAY_CAPACITY`] a
    /// proof is refused rather than admitted unchecked or allowed to evict a
    /// live entry — either of which would be a way to get a replay
    /// accepted.
    #[test]
    fn a_full_replay_window_refuses_rather_than_forgetting() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = verifier();
        {
            let mut replay = v.replay.lock().unwrap();
            let now = OffsetDateTime::now_utc();
            let expiry = now + Duration::minutes(5);
            for n in 0..REPLAY_CAPACITY {
                replay
                    .spend(format!("held-{n}"), expiry, now)
                    .expect("the window fills one key at a time");
            }
        }
        let proof = ProofBuilder::new(&key, "POST", HTU)
            .jti("one-too-many")
            .build();
        let accepted = v
            .verify(&proof, &method(), HTU, None, None)
            .expect("the proof itself checks out");
        assert_eq!(
            v.accept(&accepted).unwrap_err(),
            DpopError::ReplayWindowFull
        );
        // A `jti` already in the window still reads as the replay it is,
        // rather than as the window being full.
        let held = ProofBuilder::new(&key, "POST", HTU).jti("held-0").build();
        assert_eq!(
            v.verify(&held, &method(), HTU, None, None).unwrap_err(),
            DpopError::Replayed {
                jti: "held-0".to_owned()
            }
        );
    }

    #[test]
    fn a_stale_nonce_is_refused_and_names_a_fresh_one() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = DpopVerifier::new(Duration::minutes(5), Duration::minutes(1), true);
        let proof = ProofBuilder::new(&key, "POST", HTU).build();
        let err = v.verify(&proof, &method(), HTU, None, None).unwrap_err();
        let DpopError::NonceRequired { fresh } = err else {
            panic!("expected NonceRequired, got {err:?}");
        };
        assert!(!fresh.is_empty());

        // Retrying with a nonce this verifier never issued is a mismatch,
        // not a second "required" -- and it too names a fresh nonce to
        // retry with.
        let wrong = ProofBuilder::new(&key, "POST", HTU)
            .jti("second-attempt")
            .nonce("not-a-real-nonce")
            .build();
        let err = v.verify(&wrong, &method(), HTU, None, None).unwrap_err();
        assert!(matches!(err, DpopError::NonceMismatch { .. }));

        // The nonce actually issued is accepted.
        let good = ProofBuilder::new(&key, "POST", HTU)
            .jti("third-attempt")
            .nonce(&fresh)
            .build();
        v.verify(&good, &method(), HTU, None, None)
            .expect("the freshly issued nonce is accepted");
    }

    #[test]
    fn a_wrong_htm_is_refused() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = verifier();
        let proof = ProofBuilder::new(&key, "GET", HTU).build();
        let err = v.verify(&proof, &method(), HTU, None, None).unwrap_err();
        assert_eq!(
            err,
            DpopError::MethodMismatch {
                proof: "GET".to_owned(),
                expected: "POST".to_owned(),
            }
        );
    }

    #[test]
    fn a_wrong_htu_is_refused() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = verifier();
        let proof =
            ProofBuilder::new(&key, "POST", "https://pds.example/xrpc/other.method").build();
        let err = v.verify(&proof, &method(), HTU, None, None).unwrap_err();
        assert!(matches!(err, DpopError::UriMismatch { .. }));
    }

    #[test]
    fn a_proof_outside_the_clock_window_is_refused_by_name() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = verifier();
        let stale_iat = OffsetDateTime::now_utc() - Duration::minutes(10);
        let proof = ProofBuilder::new(&key, "POST", HTU).iat(stale_iat).build();
        let err = v.verify(&proof, &method(), HTU, None, None).unwrap_err();
        let DpopError::ClockSkew { iat, now, window } = err else {
            panic!("expected ClockSkew, got {err:?}");
        };
        // Both timestamps are on the error, not folded into a generic
        // signature failure.
        assert_eq!(iat.unix_timestamp(), stale_iat.unix_timestamp());
        assert!(now > iat);
        assert_eq!(window, Duration::minutes(5));
    }

    #[test]
    fn a_wrong_typ_is_refused() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = verifier();
        let mut builder = ProofBuilder::new(&key, "POST", HTU);
        builder.typ = "JWT";
        let proof = builder.build();
        let err = v.verify(&proof, &method(), HTU, None, None).unwrap_err();
        assert_eq!(err, DpopError::WrongTyp(Some("JWT".to_owned())));
    }

    #[test]
    fn an_unsupported_algorithm_is_refused() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = verifier();
        let mut builder = ProofBuilder::new(&key, "POST", HTU);
        builder.alg = "none";
        let proof = builder.build();
        let err = v.verify(&proof, &method(), HTU, None, None).unwrap_err();
        assert_eq!(err, DpopError::UnsupportedAlgorithm("none".to_owned()));
    }

    #[test]
    fn thumbprint_binding_refuses_a_different_key() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let other_key = SigningKey::random(&mut rand_core::OsRng);
        let bound_thumbprint = {
            let vk = P256VerifyingKey::from(&other_key);
            let point = vk.to_encoded_point(false);
            let x: Coordinate = (*point.x().unwrap()).into();
            let y: Coordinate = (*point.y().unwrap()).into();
            jwk_thumbprint(&x, &y)
        };
        let v = verifier();
        let proof = ProofBuilder::new(&key, "POST", HTU).build();
        let err = v
            .verify(&proof, &method(), HTU, None, Some(&bound_thumbprint))
            .unwrap_err();
        assert_eq!(err, DpopError::ThumbprintMismatch);
    }

    #[test]
    fn an_access_token_hash_mismatch_is_refused() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = verifier();
        let proof = ProofBuilder::new(&key, "POST", HTU)
            .ath("the-real-token")
            .build();
        let err = v
            .verify(&proof, &method(), HTU, Some("a-different-token"), None)
            .unwrap_err();
        assert_eq!(err, DpopError::AccessTokenHashMismatch);
    }

    #[test]
    fn a_missing_access_token_hash_is_refused_when_one_is_expected() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = verifier();
        let proof = ProofBuilder::new(&key, "POST", HTU).build();
        let err = v
            .verify(&proof, &method(), HTU, Some("the-real-token"), None)
            .unwrap_err();
        assert_eq!(err, DpopError::AccessTokenHashMismatch);
    }

    #[test]
    fn a_malformed_proof_is_refused_before_any_decoding() {
        let err = verifier()
            .verify("not-a-jwt", &method(), HTU, None, None)
            .unwrap_err();
        assert_eq!(err, DpopError::Malformed);
    }

    /// A signature has one spelling. Padded, with an unused bit set in its
    /// final character, or in the standard alphabet, it is the same 64 bytes
    /// to a lenient decoder and would verify. Each is refused.
    #[test]
    fn a_signature_spelled_another_way_is_refused() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = verifier();
        // One whose signature holds `-` or `_`, the two characters the
        // standard alphabet spells differently.
        let proof = (0..32)
            .map(|n| {
                ProofBuilder::new(&key, "POST", HTU)
                    .jti(&format!("spelling-{n}"))
                    .build()
            })
            .find(|proof| {
                proof
                    .rsplit('.')
                    .next()
                    .is_some_and(|sig| sig.contains(['-', '_']))
            })
            .expect("a signature holds `-` or `_` within a few tries");
        assert!(v.verify(&proof, &method(), HTU, None, None).is_ok());
        let (signed, sig) = proof.rsplit_once('.').expect("three segments");

        // 86 characters carry 516 bits for 512, so the final character is
        // `A`, `Q`, `g` or `w`, and the letter after it sets an unused bit.
        let (head, last) = sig.split_at(sig.len() - 1);
        let unused_bit = char::from(last.as_bytes()[0] + 1);
        for respelled in [
            format!("{sig}=="),
            format!("{head}{unused_bit}"),
            sig.replace('-', "+").replace('_', "/"),
        ] {
            assert_eq!(
                v.verify(&format!("{signed}.{respelled}"), &method(), HTU, None, None),
                Err(DpopError::InvalidEncoding("signature")),
                "{respelled}"
            );
        }
    }

    /// A nonce is handed out for `nonce_ttl` and replaced the first time one
    /// is asked for after that. The replaced nonce still verifies for one
    /// more `nonce_ttl`, so a request in flight across the rotation lands,
    /// and not after.
    #[test]
    fn a_replaced_nonce_is_accepted_for_one_more_lifetime() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let started = OffsetDateTime::from_unix_timestamp(1_800_000_000).expect("a clock");
        let ttl = Duration::minutes(1);
        let v = DpopVerifier::started_at(Duration::minutes(5), ttl, true, started);
        let presented = |nonce: &str, jti: &str, now: OffsetDateTime| {
            let proof = ProofBuilder::new(&key, "POST", HTU)
                .jti(jti)
                .iat(now)
                .nonce(nonce)
                .build();
            v.verify_at(&proof, &method(), HTU, None, None, now)
        };

        let first = v.current_nonce_at(started);
        assert_eq!(v.current_nonce_at(started + Duration::seconds(59)), first);
        let second = v.current_nonce_at(started + ttl);
        assert_ne!(
            second, first,
            "a nonce is replaced once its lifetime is over"
        );

        presented(&first, "in-flight", started + ttl + Duration::seconds(59))
            .expect("the replaced nonce still verifies");
        assert!(matches!(
            presented(&first, "too-late", started + ttl * 2),
            Err(DpopError::NonceMismatch { .. })
        ));
        presented(&second, "its-successor", started + ttl * 2)
            .expect("the nonce that replaced it still verifies");
    }

    /// **The rotation a stranger could force.** A refusal used to mint a
    /// fresh nonce, and only two are held, so two wrong nonces from anyone
    /// displaced the one every honest client held. A refusal now names the
    /// nonce being handed out and replaces nothing.
    #[test]
    fn a_refused_nonce_moves_nothing() {
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = DpopVerifier::new(Duration::minutes(5), Duration::minutes(1), true);
        let held = v.current_nonce();
        for n in 0..8 {
            let wrong = ProofBuilder::new(&key, "POST", HTU)
                .jti(&format!("wrong-{n}"))
                .nonce("not-a-nonce-this-server-issued")
                .build();
            assert_eq!(
                v.verify(&wrong, &method(), HTU, None, None),
                Err(DpopError::NonceMismatch {
                    fresh: held.clone()
                })
            );
        }
        let honest = ProofBuilder::new(&key, "POST", HTU)
            .jti("honest")
            .nonce(&held)
            .build();
        v.verify(&honest, &method(), HTU, None, None)
            .expect("the nonce an honest client holds still verifies");
    }

    /// The seam every route holds carries a nonce refusal with the nonce to
    /// retry with, and hands out that same nonce for a response header. A
    /// verifier that requires no nonce hands none out.
    #[test]
    fn the_seam_carries_the_nonce_to_retry_with() {
        use crate::oauth::dpop_seam::{DpopError as SeamError, DpopVerifier as Seam};
        let key = SigningKey::random(&mut rand_core::OsRng);
        let v = DpopVerifier::new(Duration::minutes(5), Duration::minutes(1), true);

        let bare = ProofBuilder::new(&key, "POST", HTU).jti("no-nonce").build();
        let Err(SeamError::UseNonce { nonce, .. }) = Seam::verify(&v, &bare, "POST", HTU, None)
        else {
            panic!("a proof with no nonce is a nonce challenge");
        };
        assert_eq!(Seam::nonce(&v), Some(nonce.clone()));

        let retried = ProofBuilder::new(&key, "POST", HTU)
            .jti("retried")
            .nonce(&nonce)
            .build();
        assert!(Seam::verify(&v, &retried, "POST", HTU, None).is_ok());

        assert_eq!(Seam::nonce(&verifier()), None);
    }
}