huskarl-core 0.1.0

//! Validation infrastructure for JWT tokens.

use std::collections::HashSet;

use crate::{
    BoxedError,
    crypto::verifier::{JwsVerifier, KeyMatch, VerifyError},
    jwt::{ConfirmationClaim, JwsParseError, ParsedJws, parse_compact_jws},
    platform::{Duration, SystemTime},
};

use bon::Builder;
use serde::Deserialize;
use snafu::{ResultExt as _, Snafu, ensure};

use crate::crypto::verifier::BoxedJwsVerifier;

/// A check to perform on a JWT claim.
#[derive(Debug, Clone, Default)]
pub enum ClaimCheck {
    /// If claim is present, it must equal this value. Lack of value is acceptable.
    IfPresent(String),
    /// Claim must be present, value must match one of these.
    RequireAny(Vec<String>),
    /// Claim must be present and equal this value.
    RequiredValue(String),
    /// Claim must be present.
    Present,
    /// No check is performed.
    #[default]
    NoCheck,
}

impl ClaimCheck {
    /// If claim is present, it must equal this value. Lack of value is acceptable.
    pub fn if_present(value: impl Into<String>) -> Self {
        Self::IfPresent(value.into())
    }

    /// Claim must be present, and value must match one of these.
    pub fn require_any(values: impl IntoIterator<Item = impl Into<String>>) -> Self {
        Self::RequireAny(values.into_iter().map(Into::into).collect())
    }

    /// Claim must be present and equal this value.
    pub fn required_value(value: impl Into<String>) -> Self {
        Self::RequiredValue(value.into())
    }

    /// Claim must be present.
    #[must_use]
    pub fn present() -> Self {
        Self::Present
    }
}

/// JWT token validator.
#[allow(clippy::struct_excessive_bools)]
#[allow(clippy::should_implement_trait)] // `sub` is the JWT claim name, not arithmetic subtraction
#[derive(Debug, Builder)]
pub struct JwtValidator {
    /// JWS verifier to use for token validation.
    verifier: BoxedJwsVerifier,
    /// Check on the `iss` claim.
    #[builder(default)]
    iss: ClaimCheck,
    /// Check on the `sub` claim.
    #[builder(default)]
    sub: ClaimCheck,
    /// Check on the `aud` claim.
    #[builder(default)]
    aud: ClaimCheck,
    /// Type to validate against.
    #[builder(default)]
    typ: ClaimCheck,
    /// The `exp` claim is required.
    #[builder(default)]
    require_exp: bool,
    /// The `iat` claim is required.
    #[builder(default)]
    require_iat: bool,
    /// The `jti` claim is required.
    #[builder(default)]
    require_jti: bool,
    /// Maximum token age to validate against.
    max_token_age: Option<Duration>,
    #[builder(default)]
    clock_leeway: Duration,
    /// Specifies which `crit` values as allowed.
    ///
    /// By default, no values are understood, and a token
    /// containing any values will be rejected. Values may
    /// be added, where the user of the token is able to
    /// understand and handle the corresponding extension.
    #[builder(default, with = FromIterator::from_iter)]
    allowed_crit: HashSet<String>,
    /// If set, restricts accepted signature algorithms to this set.
    ///
    /// Per OIDC Core §3.1.3.7 step 7, the `alg` value SHOULD be `RS256` or the algorithm
    /// registered during client registration. Use this to enforce an allowlist.
    ///
    /// Regardless of this setting, the algorithm `"none"` is always rejected.
    #[builder(with = FromIterator::from_iter)]
    allowed_algorithms: Option<HashSet<String>>,
}

/// Per RFC 7515 §4.1.9 and RFC 2045, `typ` media type subtypes are case-insensitive,
/// and the `application/` prefix may be omitted when there is no other `/` in the value.
/// Normalize to the short form before comparison.
fn normalize_typ(typ: &str) -> &str {
    if typ.len() > 12 && typ[..12].eq_ignore_ascii_case("application/") {
        &typ[12..]
    } else {
        typ
    }
}

fn check_str_claim(
    check: &ClaimCheck,
    value: Option<&str>,
    missing: impl FnOnce() -> JwtValidationError,
    mismatch: impl FnOnce(String, &str) -> JwtValidationError,
) -> Result<(), JwtValidationError> {
    match check {
        ClaimCheck::Present => {
            if value.is_none() {
                return Err(missing());
            }
        }
        ClaimCheck::RequiredValue(v) => match value {
            Some(val) if val == v.as_str() => {}
            Some(val) => return Err(mismatch(v.clone(), val)),
            None => return Err(missing()),
        },
        ClaimCheck::RequireAny(vs) => match value {
            Some(val) if vs.iter().any(|x| val == x.as_str()) => {}
            Some(val) => return Err(mismatch(vs.join(", "), val)),
            None => return Err(missing()),
        },
        ClaimCheck::IfPresent(v) => {
            if let Some(val) = value
                && val != v.as_str()
            {
                return Err(mismatch(v.clone(), val));
            }
        }
        ClaimCheck::NoCheck => {}
    }
    Ok(())
}

impl JwtValidator {
    /// Validate a pre-parsed JWS, returning a [`ValidatedJwt`] on success.
    ///
    /// # Errors
    ///
    /// Returns a [`JwtValidationError`] if the token is invalid.
    #[allow(clippy::too_many_lines)]
    pub async fn validate_parsed_jws<C: for<'de> Deserialize<'de> + Clone + 'static>(
        &self,
        parsed_jwt: ParsedJws<(), C>,
    ) -> Result<ValidatedJwt<C>, JwtValidationError> {
        let now = SystemTime::now();

        ensure!(parsed_jwt.header.alg != "none", UnsignedTokenSnafu);

        if let Some(allowed) = &self.allowed_algorithms {
            ensure!(
                allowed.contains(&*parsed_jwt.header.alg),
                DisallowedAlgorithmSnafu {
                    alg: parsed_jwt.header.alg.to_string()
                }
            );
        }

        ensure!(
            parsed_jwt
                .header
                .crit
                .iter()
                .all(|v| self.allowed_crit.contains(v)),
            UnrecognizedCriticalHeaderSnafu {
                params: parsed_jwt.header.crit
            }
        );

        let key_match = KeyMatch {
            alg: &parsed_jwt.header.alg,
            kid: parsed_jwt.header.kid.as_deref(),
        };
        self.verifier
            .verify(&parsed_jwt.signing_input, &parsed_jwt.signature, &key_match)
            .await
            .context(SignatureSnafu)?;

        match &self.aud {
            ClaimCheck::Present => ensure!(
                !parsed_jwt.claims.aud.is_empty(),
                RequiredClaimMissingSnafu { claim: "aud" }
            ),
            ClaimCheck::RequiredValue(v) => ensure!(
                parsed_jwt.claims.aud.contains(v),
                AudienceMismatchSnafu { expected: v }
            ),
            ClaimCheck::RequireAny(vs) => ensure!(
                vs.iter().any(|v| parsed_jwt.claims.aud.contains(v)),
                AudienceMismatchSnafu {
                    expected: vs.join(", ")
                }
            ),
            ClaimCheck::IfPresent(v) => {
                if !parsed_jwt.claims.aud.is_empty() {
                    ensure!(
                        parsed_jwt.claims.aud.contains(v),
                        AudienceMismatchSnafu { expected: v }
                    );
                }
            }
            ClaimCheck::NoCheck => {}
        }

        if self.require_exp {
            ensure!(
                parsed_jwt.claims.exp.is_some(),
                RequiredClaimMissingSnafu { claim: "exp" }
            );
        }

        if self.require_iat {
            ensure!(
                parsed_jwt.claims.iat.is_some(),
                RequiredClaimMissingSnafu { claim: "iat" }
            );
        }

        if self.require_jti {
            ensure!(
                parsed_jwt.claims.jti.is_some(),
                RequiredClaimMissingSnafu { claim: "jti" }
            );
        }

        if let Some(max_token_age) = self.max_token_age {
            let iat = parsed_jwt
                .claims
                .iat
                .ok_or_else(|| RequiredClaimMissingSnafu { claim: "iat" }.build())?;

            let issued_at = SystemTime::UNIX_EPOCH + Duration::from_secs(iat);

            ensure!(
                now.duration_since(issued_at)
                    .is_ok_and(|d| d <= max_token_age + self.clock_leeway),
                TokenTooOldSnafu {
                    issued_at,
                    max_token_age
                }
            );
        }

        match &self.typ {
            ClaimCheck::IfPresent(t) => ensure!(
                parsed_jwt.header.typ.as_ref().is_none_or(|typ| {
                    normalize_typ(typ).eq_ignore_ascii_case(normalize_typ(t))
                }),
                InvalidTokenTypeSnafu {
                    typ: parsed_jwt.header.typ.map(Into::into)
                }
            ),
            ClaimCheck::RequireAny(allowed) => match parsed_jwt.header.typ.as_deref() {
                None => return RequiredClaimMissingSnafu { claim: "typ" }.fail(),
                Some(typ)
                    if allowed
                        .iter()
                        .any(|t| normalize_typ(typ).eq_ignore_ascii_case(normalize_typ(t))) => {}
                Some(typ) => {
                    return InvalidTokenTypeSnafu {
                        typ: Some(typ.into()),
                    }
                    .fail();
                }
            },
            ClaimCheck::RequiredValue(t) => match parsed_jwt.header.typ.as_deref() {
                None => return RequiredClaimMissingSnafu { claim: "typ" }.fail(),
                Some(typ) if normalize_typ(typ).eq_ignore_ascii_case(normalize_typ(t)) => {}
                Some(typ) => {
                    return InvalidTokenTypeSnafu {
                        typ: Some(typ.into()),
                    }
                    .fail();
                }
            },
            ClaimCheck::Present => {
                ensure!(
                    parsed_jwt.header.typ.is_some(),
                    RequiredClaimMissingSnafu { claim: "typ" }
                );
            }
            ClaimCheck::NoCheck => {}
        }

        check_str_claim(
            &self.iss,
            parsed_jwt.claims.iss.as_deref(),
            || RequiredClaimMissingSnafu { claim: "iss" }.build(),
            |expected, actual| IssuerMismatchSnafu { expected, actual }.build(),
        )?;

        check_str_claim(
            &self.sub,
            parsed_jwt.claims.sub.as_deref(),
            || RequiredClaimMissingSnafu { claim: "sub" }.build(),
            |expected, actual| SubjectMismatchSnafu { expected, actual }.build(),
        )?;

        if let Some(exp) = parsed_jwt.claims.exp {
            let expiration = SystemTime::UNIX_EPOCH + Duration::from_secs(exp);
            ensure!(
                expiration + self.clock_leeway >= now,
                ExpiredSnafu { expiration, now }
            );
        }

        if let Some(nbf) = parsed_jwt.claims.nbf {
            let not_before = SystemTime::UNIX_EPOCH + Duration::from_secs(nbf);
            ensure!(
                not_before <= now + self.clock_leeway,
                NotYetValidSnafu { not_before, now }
            );
        }

        if let Some(iat) = parsed_jwt.claims.iat {
            let issued_at = SystemTime::UNIX_EPOCH + Duration::from_secs(iat);
            ensure!(
                issued_at <= now + self.clock_leeway,
                IssuedInFutureSnafu { issued_at, now }
            );
        }

        Ok(ValidatedJwt {
            issuer: parsed_jwt.claims.iss.map(Into::into),
            subject: parsed_jwt.claims.sub.map(Into::into),
            audience: parsed_jwt.claims.aud.iter().map(Into::into).collect(),
            issued_at: parsed_jwt
                .claims
                .iat
                .map(|iat| SystemTime::UNIX_EPOCH + Duration::from_secs(iat)),
            expiration: parsed_jwt
                .claims
                .exp
                .map(|exp| SystemTime::UNIX_EPOCH + Duration::from_secs(exp)),
            jti: parsed_jwt.claims.jti.map(Into::into),
            cnf: parsed_jwt.claims.cnf,
            claims: parsed_jwt.claims.extra_claims.map(|c| match c {
                std::borrow::Cow::Borrowed(c) => c.clone(),
                std::borrow::Cow::Owned(c) => c,
            }),
        })
    }

    /// Validate a JWT token, returning a [`ValidatedJwt`] on success.
    ///
    /// # Errors
    ///
    /// Returns a [`JwtValidationError`] if the token is invalid.
    pub async fn validate<C: Clone + for<'de> Deserialize<'de> + 'static>(
        &self,
        token: &str,
    ) -> Result<ValidatedJwt<C>, JwtValidationError> {
        let parsed_jwt = parse_compact_jws::<(), _>(token).context(ParseSnafu)?;
        self.validate_parsed_jws(parsed_jwt).await
    }
}

/// A validated JWT, containing the parsed claims and other metadata.
#[derive(Debug)]
pub struct ValidatedJwt<C> {
    /// The issuer of the JWT, if present.
    pub issuer: Option<String>,
    /// The subject of the JWT, if present.
    pub subject: Option<String>,
    /// The audience of the JWT, if present.
    pub audience: Vec<String>,
    /// The JWT ID, if present.
    pub jti: Option<String>,
    /// The issued-at timestamp of the JWT, if present.
    pub issued_at: Option<SystemTime>,
    /// The expiration timestamp of the JWT, if present.
    pub expiration: Option<SystemTime>,
    /// The key confirmation claim (`cnf`, RFC 7800), if present.
    ///
    /// Binds the token to a `DPoP` key (`jkt`, RFC 9449) or mTLS certificate
    /// (`x5t#S256`, RFC 8705). Independent of the token profile and claims type.
    pub cnf: Option<ConfirmationClaim>,
    /// The claims of the JWT, if present.
    pub claims: Option<C>,
}

impl<C> ValidatedJwt<C> {
    /// Maps the claims of the JWT using the provided function.
    pub fn map_claims<C1, F>(self, f: F) -> ValidatedJwt<C1>
    where
        F: FnOnce(C) -> C1,
    {
        ValidatedJwt {
            issuer: self.issuer,
            subject: self.subject,
            audience: self.audience,
            jti: self.jti,
            issued_at: self.issued_at,
            expiration: self.expiration,
            cnf: self.cnf,
            claims: self.claims.map(f),
        }
    }
}

/// Validation errors that can occur while processing a JWT.
#[derive(Debug, Snafu)]
pub enum JwtValidationError {
    /// The token is invalid.
    Parse {
        /// The underlying error.
        source: JwsParseError,
    },
    /// The token signature is invalid.
    Signature {
        /// The underlying error.
        source: VerifyError<BoxedError>,
    },
    /// The token is unsigned.
    UnsignedToken,
    /// The token uses a disallowed signature algorithm.
    DisallowedAlgorithm {
        /// The algorithm used by the token.
        alg: String,
    },
    /// The token contains unrecognized critical header parameters.
    UnrecognizedCriticalHeader {
        /// The unrecognized critical header parameters.
        params: Vec<String>,
    },
    /// The token is expired.
    Expired {
        /// The expiration timestamp of the JWT.
        expiration: SystemTime,
        /// The current time.
        now: SystemTime,
    },
    /// The token is not yet valid.
    NotYetValid {
        /// The not-before timestamp of the JWT.
        not_before: SystemTime,
        /// The current time.
        now: SystemTime,
    },
    /// The token is issued in the future.
    IssuedInFuture {
        /// The issued-at timestamp of the JWT.
        issued_at: SystemTime,
        /// The current time.
        now: SystemTime,
    },
    /// The token is too old.
    TokenTooOld {
        /// The issued-at timestamp of the JWT.
        issued_at: SystemTime,
        /// The maximum age of the token.
        max_token_age: Duration,
    },
    /// The token type claim is invalid.
    InvalidTokenType {
        /// The type of the JWT.
        typ: Option<String>,
    },
    /// The issuer claim did not match the expected issuer.
    IssuerMismatch {
        /// The expected issuer.
        expected: String,
        /// The actual issuer.
        actual: String,
    },
    /// The subject claim did not match the expected subject.
    SubjectMismatch {
        /// The expected subject.
        expected: String,
        /// The actual subject.
        actual: String,
    },
    /// The audience claim does not contain the expected value.
    AudienceMismatch {
        /// The expected audience value.
        expected: String,
    },
    /// A required claim is missing from the JWT.
    RequiredClaimMissing {
        /// The missing claim.
        claim: &'static str,
    },
}