identity-kit 0.2.0

//! Validation of SD-JWT credentials: issuer signature and binding, time claims, key binding,
//! status.
//!
//! [`SdJwtCredentialValidator`] is the SD-JWT counterpart of
//! [`JwtCredentialValidator`](crate::vc::validation::JwtCredentialValidator), over the same
//! [`KeyResolver`] and [`JwsVerifier`]. It validates both SD-JWT credential types
//! ([two SD-JWT credential types](super#two-sd-jwt-credential-types)):
//! [`validate`](SdJwtCredentialValidator::validate) an SD-JWT VC,
//! [`validate_v2`](SdJwtCredentialValidator::validate_v2) a VCDM 2.0 credential secured with
//! SD-JWT. Each checks, in order:
//!
//! 1. The SD-JWT parses as an [`SdJwtVc`] (`typ`, disclosures, claims; RFC 9901 §7.1 steps 3
//!    to 5, SD-JWT VC §2.2) or as an [`SdJwtCredentialV2`] (`typ` `vc+sd-jwt` when present,
//!    or one of `options.additional_typ`; disclosures; the payload as a
//!    [`CredentialV2`](crate::vc::CredentialV2) with its registered claims agreeing with it).
//! 2. The header of the issuer-signed JWT names its key ([`KeyReference::from_jws`], with the
//!    issuer, `iss` or the credential's `issuer`, as `iss`): a `kid` that is a DID URL of the
//!    form `did:…#fragment` (a path or DID parameters such as `versionId` are refused, as in
//!    the JWT validators, ADR 0004), a `#fragment` relative to a DID issuer, a `kid` into the
//!    JWT VC issuer metadata of an HTTPS issuer (SD-JWT VC §3.5, resolved by `JwksResolver`
//!    with the `jwks` feature), or a `jwk`, `x5c` or `jku` header. The key is resolved for
//!    [`KeyRole::Issuer`], verifies the signature, and belongs to the issuer
//!    ([`KeyReference::binds_to`]).
//! 3. `nbf`, `exp` and `iat` hold at the validation time, and so do `validFrom` and
//!    `validUntil` of a VCDM 2.0 credential.
//! 4. When the options require key binding (RFC 9901 §7.3): the SD-JWT+KB carries a key
//!    binding JWT with `typ: kb+jwt`, signed by the holder's key, for the expected audience
//!    and nonce, issued within the window, with an `sd_hash` over the presented SD-JWT. The
//!    holder's key is `cnf.jwk`, used as it is since the issuer signed it, or else the key
//!    `cnf.kid` names, an absolute DID URL resolved for [`KeyRole::Subject`]
//!    (`authentication`); see [`KeyReference::from_confirmation`].
//! 5. `status` (as [`CredentialStatus::SdJwt`]) and the `credentialStatus` entries of a VCDM
//!    2.0 credential (as [`CredentialStatus::Vcdm`]) pass the [`StatusCheck`], per the
//!    [`StatusPolicy`].
//!
//! Type metadata is a separate step the application runs when its policy asks for it:
//! [`TypeMetadata::check_claims`](super::TypeMetadata::check_claims).

use core::time::Duration;
use std::collections::BTreeSet;

use chrono::{DateTime, Utc};

use super::{
    Confirmation, SdJwt, SdJwtCredentialV2, SdJwtCredentialV2Error, SdJwtVc, SdJwtVcError,
};
use crate::did::Uri;
use crate::jose::{DefaultVerifier, Jwk, JwsVerifier};
use crate::resolver::{KeyReference, KeyReferenceError, KeyResolver, KeyRole};
use crate::vc::validation::{
    CredentialStatus, StatusCheck, StatusPolicy, TimeOptions, ValidationError, check_statuses,
};
use crate::vc::{CredentialError, JwtClaims};

#[cfg(feature = "did-web")]
pub use status_list::StatusListCheck;

/// What a key binding JWT must prove (RFC 9901 §7.3, step 5).
///
/// The key binding JWT must be signed by the holder's key the credential's `cnf` names: by
/// value in `cnf.jwk`, or by reference in `cnf.kid`, an absolute DID URL the validator's
/// [`KeyResolver`] resolves for [`KeyRole::Subject`] (`authentication`).
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct KeyBindingOptions {
    /// The audience the key binding JWT must name: this verifier.
    pub audience: String,
    /// The nonce it must carry: the one of this transaction.
    pub nonce: String,
    /// The time its `iat` is checked against, with leeway.
    pub time: TimeOptions,
    /// How old it may be, if bounded.
    pub max_age: Option<Duration>,
}

impl KeyBindingOptions {
    /// Key binding for `audience` with `nonce`, checked at the current time with no age
    /// bound.
    pub fn new(audience: impl Into<String>, nonce: impl Into<String>) -> Self {
        Self {
            audience: audience.into(),
            nonce: nonce.into(),
            time: TimeOptions::default(),
            max_age: None,
        }
    }

    /// These options checking `iat` against `time`.
    #[must_use]
    pub fn with_time(mut self, time: TimeOptions) -> Self {
        self.time = time;
        self
    }

    /// These options rejecting a key binding JWT older than `max_age`.
    #[must_use]
    pub fn with_max_age(mut self, max_age: Duration) -> Self {
        self.max_age = Some(max_age);
        self
    }
}

/// Options of [`SdJwtCredentialValidator`].
#[derive(Debug, Clone, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct SdJwtValidationOptions {
    /// The validation time and leeway of the issuer-signed JWT.
    pub time: TimeOptions,
    /// The key binding required, if any; a key binding JWT is not verified otherwise.
    pub key_binding: Option<KeyBindingOptions>,
    /// What to do about `status` (and `credentialStatus`).
    pub status: StatusPolicy,
    /// Whether to reject the pre-standard `typ: vc+sd-jwt` on an SD-JWT VC.
    pub reject_legacy_typ: bool,
    /// Header `typ` values accepted for a VCDM 2.0 credential besides `vc+sd-jwt`; none by
    /// default. A token without `typ` is always accepted there. An SD-JWT VC's `typ` is fixed
    /// by its specification and not affected.
    pub additional_typ: BTreeSet<String>,
}

impl SdJwtValidationOptions {
    /// Default options: validate now without leeway, no key binding required,
    /// [`StatusPolicy::Strict`], `vc+sd-jwt` accepted.
    pub fn new() -> Self {
        Self::default()
    }

    /// These options with `time`.
    #[must_use]
    pub fn with_time(mut self, time: TimeOptions) -> Self {
        self.time = time;
        self
    }

    /// These options requiring `key_binding`.
    #[must_use]
    pub fn with_key_binding(mut self, key_binding: KeyBindingOptions) -> Self {
        self.key_binding = Some(key_binding);
        self
    }

    /// These options with `status`.
    #[must_use]
    pub fn with_status(mut self, status: StatusPolicy) -> Self {
        self.status = status;
        self
    }

    /// These options rejecting `typ: vc+sd-jwt` on an SD-JWT VC.
    #[must_use]
    pub fn rejecting_legacy_typ(mut self) -> Self {
        self.reject_legacy_typ = true;
        self
    }

    /// These options also accepting a VCDM 2.0 credential whose header `typ` is `typ`.
    #[must_use]
    pub fn with_additional_typ(mut self, typ: impl Into<String>) -> Self {
        self.additional_typ.insert(typ.into());
        self
    }
}

/// Why an SD-JWT credential did not validate.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum SdJwtValidationError {
    /// The SD-JWT is not a well-formed SD-JWT VC.
    #[error(transparent)]
    Credential(#[from] SdJwtVcError),
    /// The SD-JWT is not a well-formed VCDM 2.0 credential secured with SD-JWT.
    #[error(transparent)]
    CredentialV2(#[from] SdJwtCredentialV2Error),
    /// The issuer-signed JWT has the pre-standard `typ: vc+sd-jwt`, which the options reject.
    #[error("header `typ` is the pre-standard `vc+sd-jwt`")]
    LegacyTyp,
    /// A check shared with the JWT validators failed: `kid`, key resolution, signature,
    /// issuer binding, time, audience, nonce, status.
    #[error(transparent)]
    Validation(#[from] ValidationError),
    /// Key binding is required and the SD-JWT carries no key binding JWT.
    #[error("key binding is required, but the SD-JWT has no key binding JWT")]
    KeyBindingRequired,
    /// Key binding is required and `cnf` names no key this crate can look for: there is no
    /// `cnf`, or [`KeyReference::from_confirmation`] refuses it.
    #[error("key binding is required, but `cnf` carries no usable key reference: {0}")]
    NoHolderKey(KeyReferenceError),
    /// The key binding JWT is older than allowed.
    #[error("key binding JWT issued at {} is older than {max_age:?} (now is {})", issued_at.to_rfc3339(), now.to_rfc3339())]
    KeyBindingTooOld {
        /// Its `iat`.
        issued_at: DateTime<Utc>,
        /// The validation time.
        now: DateTime<Utc>,
        /// The bound.
        max_age: Duration,
    },
    /// The key binding JWT's `sd_hash` is not the digest of the presented SD-JWT.
    #[error("key binding `sd_hash` {found:?} is not the digest {expected:?} of the SD-JWT")]
    SdHashMismatch {
        /// The digest of the SD-JWT.
        expected: String,
        /// The `sd_hash` found.
        found: Option<String>,
    },
}

/// A validated SD-JWT VC.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct ValidatedSdJwtVc {
    /// The credential, with the presented disclosures applied.
    pub credential: SdJwtVc,
    /// Where the issuer-signed JWT says its key is.
    pub issuer_key: KeyReference,
    /// The claims of the key binding JWT, when key binding was required and verified.
    pub key_binding: Option<JwtClaims>,
    /// The holder's key that verified the key binding JWT, and where `cnf` said it is (a DID
    /// URL to compare with the presentation's holder or the credential subject, say), when key
    /// binding was required and verified.
    pub holder_key: Option<(KeyReference, Jwk)>,
}

/// A validated VCDM 2.0 credential secured with SD-JWT.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct ValidatedSdJwtCredentialV2 {
    /// The credential, with the presented disclosures applied.
    pub credential: SdJwtCredentialV2,
    /// Where the issuer-signed JWT says its key is.
    pub issuer_key: KeyReference,
    /// The claims of the key binding JWT, when key binding was required and verified.
    pub key_binding: Option<JwtClaims>,
    /// The holder's key that verified the key binding JWT, and where `cnf` said it is, when key
    /// binding was required and verified.
    pub holder_key: Option<(KeyReference, Jwk)>,
}

/// Validates SD-JWT credentials; see the [module documentation](self) for the checks.
pub struct SdJwtCredentialValidator<R, V = DefaultVerifier> {
    resolver: R,
    verifier: V,
    status: Option<Box<dyn StatusCheck>>,
}

impl<R: KeyResolver, V: JwsVerifier> SdJwtCredentialValidator<R, V> {
    /// A validator resolving keys with `resolver` and verifying signatures with `verifier`,
    /// without a status check.
    pub fn new(resolver: R, verifier: V) -> Self {
        Self {
            resolver,
            verifier,
            status: None,
        }
    }

    /// This validator checking the `status` claim and, for a VCDM 2.0 credential, the
    /// `credentialStatus` entries with `check`.
    #[must_use]
    pub fn with_status_check(mut self, check: impl StatusCheck + 'static) -> Self {
        self.status = Some(Box::new(check));
        self
    }

    /// The key resolver.
    pub fn resolver(&self) -> &R {
        &self.resolver
    }

    /// The signature verifier.
    pub fn verifier(&self) -> &V {
        &self.verifier
    }

    /// Whether a status check is configured.
    pub fn has_status_check(&self) -> bool {
        self.status.is_some()
    }

    /// Validates `sd_jwt` as an SD-JWT VC.
    ///
    /// # Errors
    ///
    /// The first [`SdJwtValidationError`] found, in the order the [module
    /// documentation](self) lists the checks.
    pub async fn validate(
        &self,
        sd_jwt: &SdJwt,
        options: &SdJwtValidationOptions,
    ) -> Result<ValidatedSdJwtVc, SdJwtValidationError> {
        let credential = SdJwtVc::from_sd_jwt(sd_jwt.clone())?;
        self.validate_credential(credential, options).await
    }

    /// Validates the parsed `credential`.
    ///
    /// # Errors
    ///
    /// As [`validate`](Self::validate).
    pub async fn validate_credential(
        &self,
        credential: SdJwtVc,
        options: &SdJwtValidationOptions,
    ) -> Result<ValidatedSdJwtVc, SdJwtValidationError> {
        if options.reject_legacy_typ && credential.has_legacy_typ() {
            return Err(SdJwtValidationError::LegacyTyp);
        }
        let claims = credential.claims();
        let issuer = claims
            .iss
            .as_deref()
            .ok_or(CredentialError::MissingClaim("iss"))
            .map_err(ValidationError::from)?;
        let (issuer_key, key) = self
            .verify_issuer_signature(credential.sd_jwt(), issuer)
            .await?;
        check_issuer(issuer, &issuer_key, &key)?;

        let mut time_claims = JwtClaims::new();
        time_claims.nbf = claims.nbf;
        time_claims.exp = claims.exp;
        time_claims.iat = claims.iat;
        options.time.check_claims(&time_claims)?;

        let (key_binding, holder_key) = match &options.key_binding {
            Some(required) => {
                let (claims, holder_key) = self
                    .check_key_binding(credential.sd_jwt(), credential.confirmation(), required)
                    .await?;
                (Some(claims), Some(holder_key))
            }
            None => (None, None),
        };

        self.check_status(claims.status.iter().map(CredentialStatus::SdJwt), options)
            .await?;

        Ok(ValidatedSdJwtVc {
            credential,
            issuer_key,
            key_binding,
            holder_key,
        })
    }

    /// Validates `sd_jwt` as a VCDM 2.0 credential secured with SD-JWT (VC-JOSE-COSE §3.2.1).
    ///
    /// # Errors
    ///
    /// The first [`SdJwtValidationError`] found, in the order the [module
    /// documentation](self) lists the checks.
    pub async fn validate_v2(
        &self,
        sd_jwt: &SdJwt,
        options: &SdJwtValidationOptions,
    ) -> Result<ValidatedSdJwtCredentialV2, SdJwtValidationError> {
        let credential =
            SdJwtCredentialV2::from_sd_jwt_with(sd_jwt.clone(), &options.additional_typ)?;
        self.validate_credential_v2(credential, options).await
    }

    /// Validates the parsed `credential`.
    ///
    /// # Errors
    ///
    /// As [`validate_v2`](Self::validate_v2).
    pub async fn validate_credential_v2(
        &self,
        credential: SdJwtCredentialV2,
        options: &SdJwtValidationOptions,
    ) -> Result<ValidatedSdJwtCredentialV2, SdJwtValidationError> {
        let validated = self
            .validate_credential_v2_unchecked_status(credential, options)
            .await?;
        let credential = &validated.credential;
        self.check_status(
            credential
                .credential()
                .statuses()
                .map(CredentialStatus::Vcdm)
                .chain(credential.status().map(CredentialStatus::SdJwt)),
            options,
        )
        .await?;
        Ok(validated)
    }

    /// Steps 2 to 4 of [`validate_credential_v2`](Self::validate_credential_v2): everything
    /// but the status checks, which the presentation validator runs with its own check.
    pub(crate) async fn validate_credential_v2_unchecked_status(
        &self,
        credential: SdJwtCredentialV2,
        options: &SdJwtValidationOptions,
    ) -> Result<ValidatedSdJwtCredentialV2, SdJwtValidationError> {
        let vc = credential.credential();
        let issuer = vc.issuer.id().as_str();
        let (issuer_key, key) = self
            .verify_issuer_signature(credential.sd_jwt(), issuer)
            .await?;
        check_issuer(issuer, &issuer_key, &key)?;
        options.time.check_claims(credential.claims())?;
        options.time.check(vc.valid_from, vc.valid_until, None)?;
        let (key_binding, holder_key) = match &options.key_binding {
            Some(required) => {
                let (claims, holder_key) = self
                    .check_key_binding(credential.sd_jwt(), credential.confirmation(), required)
                    .await?;
                (Some(claims), Some(holder_key))
            }
            None => (None, None),
        };
        Ok(ValidatedSdJwtCredentialV2 {
            credential,
            issuer_key,
            key_binding,
            holder_key,
        })
    }

    /// Resolves the key the issuer-signed JWT names, `issuer` being its issuer, for
    /// [`KeyRole::Issuer`] and verifies the signature; the reference and the key.
    async fn verify_issuer_signature(
        &self,
        sd_jwt: &SdJwt,
        issuer: &str,
    ) -> Result<(KeyReference, Jwk), ValidationError> {
        let jws = sd_jwt.jwt().decode()?;
        let reference = KeyReference::from_jws(&jws, Some(issuer))?;
        let key = self
            .resolver
            .resolve_key(&reference, KeyRole::Issuer)
            .await
            .map_err(|source| ValidationError::KeyResolution {
                key: Box::new(reference.clone()),
                source,
            })?;
        jws.verify(&self.verifier, &key)?;
        Ok((reference, key))
    }

    /// The holder's key `cnf` names: `cnf.jwk` as it is, since the issuer signed it, or the
    /// key a `cnf.kid` resolves to for [`KeyRole::Subject`].
    async fn holder_key(
        &self,
        cnf: Option<&Confirmation>,
    ) -> Result<(KeyReference, Jwk), SdJwtValidationError> {
        let cnf = cnf.ok_or(SdJwtValidationError::NoHolderKey(
            KeyReferenceError::Missing,
        ))?;
        let reference =
            KeyReference::from_confirmation(cnf).map_err(SdJwtValidationError::NoHolderKey)?;
        let key = match &reference {
            KeyReference::Jwk(jwk) => jwk.public(),
            reference => self
                .resolver
                .resolve_key(reference, KeyRole::Subject)
                .await
                .map_err(|source| ValidationError::KeyResolution {
                    key: Box::new(reference.clone()),
                    source,
                })?,
        };
        Ok((reference, key))
    }

    /// RFC 9901 §7.3, step 5: the key binding JWT of `sd_jwt`, signed by the key `cnf` names;
    /// its claims and that key.
    async fn check_key_binding(
        &self,
        sd_jwt: &SdJwt,
        cnf: Option<&Confirmation>,
        required: &KeyBindingOptions,
    ) -> Result<(JwtClaims, (KeyReference, Jwk)), SdJwtValidationError> {
        let kb_jwt = sd_jwt
            .key_binding_jwt()
            .ok_or(SdJwtValidationError::KeyBindingRequired)?;
        let holder_key = self.holder_key(cnf).await?;
        let jws = kb_jwt.decode().map_err(ValidationError::from)?;
        match jws.header().typ.as_deref() {
            Some(super::KB_JWT_TYP) => {}
            found => {
                return Err(ValidationError::UnexpectedTyp {
                    expected: super::KB_JWT_TYP,
                    found: found.unwrap_or("").to_owned(),
                }
                .into());
            }
        }
        jws.verify(&self.verifier, &holder_key.1)
            .map_err(ValidationError::from)?;
        let claims: JwtClaims = serde_json::from_slice(jws.payload())
            .map_err(|e| ValidationError::Payload(e.to_string()))?;

        if !claims.audiences().any(|aud| aud == required.audience) {
            return Err(ValidationError::AudienceMismatch {
                expected: required.audience.clone(),
                found: claims.aud.clone(),
            }
            .into());
        }
        let nonce = claims.additional.get("nonce").and_then(|v| v.as_str());
        if nonce != Some(required.nonce.as_str()) {
            return Err(ValidationError::NonceMismatch {
                expected: required.nonce.clone(),
                found: nonce.map(str::to_owned),
            }
            .into());
        }
        let iat = claims
            .iat
            .ok_or(CredentialError::MissingClaim("iat"))
            .map_err(ValidationError::from)?;
        let issued_at = JwtClaims::timestamp(iat).ok_or_else(|| {
            ValidationError::from(CredentialError::InvalidClaim {
                claim: "iat",
                reason: format!("{iat} is out of range"),
            })
        })?;
        required.time.check(None, None, Some(issued_at))?;
        if let Some(max_age) = required.max_age {
            let now = required.time.now();
            // A `max_age` beyond what `chrono` represents bounds nothing.
            let oldest = chrono::TimeDelta::from_std(max_age)
                .ok()
                .and_then(|delta| now.checked_sub_signed(delta))
                .unwrap_or(DateTime::<Utc>::MIN_UTC);
            if issued_at < oldest {
                return Err(SdJwtValidationError::KeyBindingTooOld {
                    issued_at,
                    now,
                    max_age,
                });
            }
        }
        let alg = sd_jwt.hash_algorithm().map_err(SdJwtVcError::from)?;
        let expected = sd_jwt.sd_hash(alg);
        let found = claims.additional.get("sd_hash").and_then(|v| v.as_str());
        if found != Some(expected.as_str()) {
            return Err(SdJwtValidationError::SdHashMismatch {
                expected,
                found: found.map(str::to_owned),
            });
        }
        Ok((claims, holder_key))
    }

    /// Checks every status entry with this validator's check, per the policy, at the
    /// validation time.
    async fn check_status<'a>(
        &self,
        statuses: impl IntoIterator<Item = CredentialStatus<'a>>,
        options: &SdJwtValidationOptions,
    ) -> Result<(), SdJwtValidationError> {
        Ok(check_statuses(
            self.status.as_deref(),
            statuses,
            options.status,
            options.time.now(),
        )
        .await?)
    }
}

/// Checks that `key`, which `reference` resolved to, belongs to `issuer`
/// ([`KeyReference::binds_to`]).
fn check_issuer(issuer: &str, reference: &KeyReference, key: &Jwk) -> Result<(), ValidationError> {
    if !reference.binds_to(Some(issuer), key) {
        return Err(ValidationError::IssuerMismatch {
            issuer: Uri::parse(issuer).map_err(|e| CredentialError::InvalidClaim {
                claim: "iss",
                reason: e.to_string(),
            })?,
            key: Box::new(reference.clone()),
        });
    }
    Ok(())
}

impl<R: core::fmt::Debug, V: core::fmt::Debug> core::fmt::Debug for SdJwtCredentialValidator<R, V> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("SdJwtCredentialValidator")
            .field("resolver", &self.resolver)
            .field("verifier", &self.verifier)
            .field("status", &self.status.as_ref().map(|_| "StatusCheck"))
            .finish()
    }
}

#[cfg(feature = "did-web")]
mod status_list {
    use chrono::{DateTime, Utc};
    use url::Url;

    use crate::jose::{DefaultVerifier, JwsVerifier};
    use crate::methods::web::HttpClient;
    use crate::resolver::{KeyReference, KeyResolver, KeyRole};
    use crate::sd_jwt_vc::{StatusListToken, StatusMechanism};
    use crate::vc::Jwt;
    use crate::vc::validation::{CredentialStatus, StatusCheck, StatusError};

    /// A [`StatusCheck`] for the Token Status List: for the `status` claim of an SD-JWT
    /// credential ([`CredentialStatus::SdJwt`]), fetches the status list token from the
    /// referenced URI with an [`HttpClient`], verifies it was signed by the key its header
    /// names ([`KeyReference::from_jws`] with the token's `iss`), resolved for
    /// [`KeyRole::Issuer`], and reads the status at the referenced index (Token Status List
    /// §8).
    ///
    /// When the token has an `iss`, the key must belong to it ([`KeyReference::binds_to`]);
    /// without one, only a key named by a DID URL is accepted, since a key by value or a key
    /// set could be anybody's. Beyond that the check trusts the key the reference resolves
    /// to; whether that key may speak for the list is the application's policy to enforce
    /// around it, by restricting the resolver, say.
    ///
    /// The status list URI comes from the credential, so the client fetches whatever an issuer
    /// names: `client` must enforce the protections `ReqwestClient` (feature `reqwest`) does
    /// (HTTPS only, no redirects, no non-public addresses after name resolution, a body limit
    /// and a timeout), or the status check becomes a request forgery primitive.
    pub struct StatusListCheck<C, R, V = DefaultVerifier> {
        client: C,
        resolver: R,
        verifier: V,
    }

    impl<C: HttpClient, R: KeyResolver, V: JwsVerifier> StatusListCheck<C, R, V> {
        /// A check fetching with `client`, resolving the status issuer's key with `resolver`
        /// and verifying with `verifier`.
        pub fn new(client: C, resolver: R, verifier: V) -> Self {
            Self {
                client,
                resolver,
                verifier,
            }
        }

        /// The status list token at `uri`, fetched and verified.
        async fn fetch(&self, uri: &str) -> Result<StatusListToken, StatusError> {
            let url = Url::parse(uri)
                .map_err(|e| StatusError::Unavailable(format!("`uri` {uri:?}: {e}")))?;
            let response = self
                .client
                .get(&url)
                .await
                .map_err(|e| StatusError::Unavailable(format!("fetching {uri}: {e}")))?;
            if !(200..300).contains(&response.status) {
                return Err(StatusError::Unavailable(format!(
                    "fetching {uri}: HTTP {}",
                    response.status
                )));
            }
            let body = String::from_utf8(response.body)
                .map_err(|_| StatusError::Unavailable(format!("{uri}: body is not UTF-8")))?;
            let jwt = Jwt::new(body.trim())
                .map_err(|e| StatusError::Unavailable(format!("{uri}: {e}")))?;
            let (_, token) = StatusListToken::decode(&jwt)
                .map_err(|e| StatusError::Unavailable(format!("{uri}: {e}")))?;
            let jws = jwt
                .decode()
                .map_err(|e| StatusError::Unavailable(format!("{uri}: {e}")))?;
            let iss = token.additional.get("iss").and_then(|iss| iss.as_str());
            let reference = KeyReference::from_jws(&jws, iss)
                .map_err(|e| StatusError::Unavailable(format!("{uri}: {e}")))?;
            let key = self
                .resolver
                .resolve_key(&reference, KeyRole::Issuer)
                .await
                .map_err(|e| {
                    StatusError::Unavailable(format!("{uri}: resolving key {reference}: {e}"))
                })?;
            jws.verify(&self.verifier, &key)
                .map_err(|e| StatusError::Unavailable(format!("{uri}: signature: {e}")))?;
            let bound = match iss {
                Some(iss) => reference.binds_to(Some(iss), &key),
                None => matches!(reference, KeyReference::DidUrl(_)),
            };
            if !bound {
                return Err(StatusError::Unavailable(format!(
                    "{uri}: key {reference} does not belong to the issuer {iss:?}"
                )));
            }
            Ok(token)
        }
    }

    #[async_trait::async_trait]
    impl<C: HttpClient, R: KeyResolver, V: JwsVerifier> StatusCheck for StatusListCheck<C, R, V> {
        /// Checks the Token Status List reference of a `status` claim; a `credentialStatus`
        /// entry, or a `status` claim without one, is [`StatusError::Unsupported`].
        async fn check(
            &self,
            status: CredentialStatus<'_>,
            now: DateTime<Utc>,
        ) -> Result<(), StatusError> {
            let CredentialStatus::SdJwt(status) = status else {
                return Err(StatusError::Unsupported(status.mechanism()));
            };
            let Some(reference) = &status.status_list else {
                let names: Vec<&str> = status
                    .mechanisms()
                    .filter_map(|m| match m {
                        StatusMechanism::Other { name, .. } => Some(name),
                        _ => None,
                    })
                    .collect();
                return Err(StatusError::Unsupported(names.join(", ")));
            };
            let token = self.fetch(&reference.uri).await?;
            let status_type = token
                .status_of(reference, now)
                .map_err(|e| StatusError::Unavailable(e.to_string()))?;
            if status_type.is_valid() {
                Ok(())
            } else {
                Err(StatusError::Invalid(status_type.to_string()))
            }
        }
    }

    impl<C: core::fmt::Debug, R: core::fmt::Debug, V: core::fmt::Debug> core::fmt::Debug
        for StatusListCheck<C, R, V>
    {
        fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
            f.debug_struct("StatusListCheck")
                .field("client", &self.client)
                .field("resolver", &self.resolver)
                .field("verifier", &self.verifier)
                .finish()
        }
    }
}