entropy-auth 2026.7.31

//! JWT claims (payload) parsing and validation per RFC 7519 §4.
//!
//! Parses the Base64url-encoded payload segment of a JWT into structured
//! claims with typed accessors for the registered claim names (`iss`,
//! `sub`, `aud`, `exp`, `nbf`, `iat`, `jti`). Custom claims are
//! accessible through the underlying [`JsonValue`].

use core::fmt;

use crate::json::JsonValue;

use super::decode::{SegmentDecodeError, decode_segment};

// ---------------------------------------------------------------------------
// Claims struct
// ---------------------------------------------------------------------------

/// Parsed JWT claims (payload).
///
/// Registered claims (RFC 7519 §4.1) are extracted into typed fields for
/// convenient access. The `aud` claim is always normalised to a `Vec<String>`
/// regardless of whether it appears as a single string or an array in the
/// token. The raw [`JsonValue`] is retained for accessing custom claims.
#[doc(alias = "payload")]
#[derive(Debug, Clone)]
pub struct JwtClaims {
    /// Issuer (`iss`).
    iss: Option<String>,
    /// Subject (`sub`).
    sub: Option<String>,
    /// Audience (`aud`), normalised to a list.
    aud: Vec<String>,
    /// Expiration time (`exp`) as seconds since the Unix epoch.
    exp: Option<u64>,
    /// Not-before time (`nbf`) as seconds since the Unix epoch.
    nbf: Option<u64>,
    /// Issued-at time (`iat`) as seconds since the Unix epoch.
    iat: Option<u64>,
    /// JWT ID (`jti`).
    jti: Option<String>,
    /// The raw parsed JSON for accessing custom claims.
    raw: JsonValue,
}

impl JwtClaims {
    /// Parses JWT claims from a Base64url-encoded payload segment.
    ///
    /// # Errors
    ///
    /// Returns [`JwtClaimsError`] if Base64url decoding fails, the
    /// decoded bytes are not valid UTF-8 or JSON, or the `aud` claim
    /// has an invalid type.
    #[must_use = "parsing may fail; handle the Result"]
    pub fn parse(payload_b64: &str) -> Result<Self, JwtClaimsError> {
        let value = decode_segment(payload_b64).map_err(|e| JwtClaimsError {
            kind: match e {
                SegmentDecodeError::InvalidBase64 => JwtClaimsErrorKind::InvalidBase64,
                SegmentDecodeError::InvalidUtf8 => JwtClaimsErrorKind::InvalidUtf8,
                SegmentDecodeError::InvalidJson => JwtClaimsErrorKind::InvalidJson,
            },
        })?;

        // RFC 7519 §7.2 step 10: the payload MUST be a JSON object. A bare
        // array/string/number decoded to an all-empty claim set whose
        // `validate_exp()` returns true — a structurally invalid token reading
        // as an unexpiring one.
        if !matches!(value, JsonValue::Object(_)) {
            return Err(JwtClaimsError {
                kind: JwtClaimsErrorKind::InvalidJson,
            });
        }

        let iss = value.get_str("iss").map(String::from);
        let sub = value.get_str("sub").map(String::from);
        let jti = value.get_str("jti").map(String::from);

        // `aud` may be a single string or an array of strings (RFC 7519 §4.1.3).
        let aud = match value.get("aud") {
            Some(JsonValue::String(s)) => vec![s.clone()],
            Some(JsonValue::Array(arr)) => {
                let mut audiences = Vec::with_capacity(arr.len());
                for item in arr {
                    match item.as_str() {
                        Some(s) => audiences.push(s.to_string()),
                        None => {
                            return Err(JwtClaimsError {
                                kind: JwtClaimsErrorKind::InvalidAudience,
                            });
                        }
                    }
                }
                audiences
            }
            Some(_) => {
                return Err(JwtClaimsError {
                    kind: JwtClaimsErrorKind::InvalidAudience,
                });
            }
            None => Vec::new(),
        };

        // Numeric claims — extract as u64 via i64 (timestamps are positive).
        let exp = Self::extract_timestamp(&value, "exp");
        let nbf = Self::extract_timestamp(&value, "nbf");
        let iat = Self::extract_timestamp(&value, "iat");

        Ok(Self {
            iss,
            sub,
            aud,
            exp,
            nbf,
            iat,
            jti,
            raw: value,
        })
    }

    /// Returns the issuer (`iss`) claim, if present.
    #[must_use]
    #[inline]
    pub fn iss(&self) -> Option<&str> {
        self.iss.as_deref()
    }

    /// Returns the subject (`sub`) claim, if present.
    #[must_use]
    #[inline]
    pub fn sub(&self) -> Option<&str> {
        self.sub.as_deref()
    }

    /// Returns the audience (`aud`) claim as a slice.
    #[must_use]
    #[inline]
    pub fn aud(&self) -> &[String] {
        &self.aud
    }

    /// Returns the expiration time (`exp`) in seconds since the Unix epoch, if present.
    #[must_use]
    #[inline]
    pub fn exp(&self) -> Option<u64> {
        self.exp
    }

    /// Returns the not-before time (`nbf`) in seconds since the Unix epoch, if present.
    #[must_use]
    #[inline]
    pub fn nbf(&self) -> Option<u64> {
        self.nbf
    }

    /// Returns the issued-at time (`iat`) in seconds since the Unix epoch, if present.
    ///
    /// # Security
    ///
    /// Unlike `exp`/`nbf`, `iat` is *not* validated by [`validate_exp`] /
    /// [`validate_nbf`] — RFC 7519 §4.1.6 makes age checking optional and
    /// application-specific. If you need to reject implausibly old or
    /// future-dated tokens (e.g. to bound replay of a leaked token), compare
    /// this value against the current time yourself.
    ///
    /// [`validate_exp`]: Self::validate_exp
    /// [`validate_nbf`]: Self::validate_nbf
    #[must_use]
    #[inline]
    pub fn iat(&self) -> Option<u64> {
        self.iat
    }

    /// Returns the JWT ID (`jti`) claim, if present.
    #[must_use]
    #[inline]
    pub fn jti(&self) -> Option<&str> {
        self.jti.as_deref()
    }

    /// Extracts a numeric timestamp (`NumericDate`) claim as `u64`.
    ///
    /// - Absent → `None` (no constraint; the caller decides whether the claim
    ///   is required).
    /// - Present but not a number at all (a string, bool, array, object — e.g.
    ///   `"exp": "1735689600"`) → the claim's own fail-closed sentinel, NOT
    ///   `None`. Dropping it to `None` made a string-typed `exp` read as
    ///   "never expires", defeating the fail-closed policy the numeric-garbage
    ///   path already implements.
    /// - Integral and in range → the exact value via the round-trip-checked
    ///   [`JsonValue::as_i64`] path, so an integer `NumericDate` never loses
    ///   precision to an intermediate `f64` cast.
    /// - Present but garbage (NaN/Inf/negative) → `Some(0)` so it fails
    ///   *closed*: an `exp` reads as already-expired rather than silently
    ///   disabling the expiry check (the previous code dropped such values to
    ///   `None`, which `validate_exp` treats as "never expires").
    ///   The sentinel is direction-aware: `0` (already expired) for `exp`, and
    ///   `u64::MAX` (not yet valid) for `nbf`/`iat`, since `0` would be the
    ///   *fail-open* direction there. See [`validate_nbf`](Self::validate_nbf).
    /// - Present but at or beyond the `u64` range — `n >= 2^64` (the f64
    ///   comparison rounds the boundary up to `2^64`, so values within
    ///   rounding distance of `u64::MAX` are included) — → `u64::MAX` (a
    ///   genuine far-future timestamp), so an `nbf` still reads as
    ///   not-yet-valid instead of being dropped.
    /// - Otherwise (a fractional value) → floored to whole seconds.
    #[allow(
        clippy::cast_sign_loss,
        clippy::cast_possible_truncation,
        clippy::cast_precision_loss
    )]
    fn extract_timestamp(value: &JsonValue, key: &str) -> Option<u64> {
        let v = value.get(key)?;
        // The value that makes THIS claim reject the token when it is present
        // but unusable. `exp` rejects at 0 (already expired); `nbf`/`iat`
        // reject at u64::MAX (not yet valid) — 0 would mean "valid since the
        // epoch", i.e. no constraint at all.
        let fail_closed = if key == "exp" { 0 } else { u64::MAX };
        // Exact integer path first: a round-trip-checked i64 preserves every
        // representable integral second. A negative instant fails *closed*.
        if let Some(i) = v.as_i64() {
            return Some(u64::try_from(i).unwrap_or(fail_closed));
        }
        // Fractional, or integral-but-out-of-i64-range: fall back to the float
        // reading, keeping the fail-closed garbage/overflow policy.
        match v.as_f64() {
            // Present but not numeric at all (string/bool/array/object).
            None => Some(fail_closed),
            Some(n) if !n.is_finite() || n < 0.0 => Some(fail_closed),
            Some(n) if n >= u64::MAX as f64 => Some(u64::MAX),
            Some(n) => Some(n as u64),
        }
    }

    /// Validates the `exp` (expiration) claim against the current time.
    ///
    /// Returns `true` if the token has not expired, accounting for the
    /// specified clock skew tolerance in seconds. Returns `true` if no
    /// `exp` claim is present (the caller decides whether `exp` is required).
    ///
    /// # Security
    ///
    /// A token with **no** `exp` claim is treated as never-expiring (this
    /// returns `true`). Callers that require expiry must separately assert
    /// [`exp()`](Self::exp)`.is_some()` — this method alone will not reject a
    /// token that simply omits `exp`.
    #[must_use]
    #[inline]
    pub fn validate_exp(&self, now_secs: u64, clock_skew_secs: u64) -> bool {
        match self.exp {
            Some(exp) => now_secs < exp.saturating_add(clock_skew_secs),
            None => true,
        }
    }

    /// Validates the `nbf` (not-before) claim against the current time.
    ///
    /// Returns `true` if the token is already valid, accounting for the
    /// specified clock skew tolerance in seconds. Returns `true` if no
    /// `nbf` claim is present (the caller decides whether `nbf` is required).
    ///
    /// # Security
    ///
    /// A malformed `nbf` — negative, NaN, non-numeric (a JSON string/bool), or
    /// otherwise un-representable — parses to `u64::MAX`, so it reads as
    /// "not yet valid" and this check **fails closed**. An absent `nbf` is
    /// still no constraint (it is optional per RFC 7519 §4.1.5); only a
    /// present-but-unusable one rejects.
    #[must_use]
    #[inline]
    pub fn validate_nbf(&self, now_secs: u64, clock_skew_secs: u64) -> bool {
        match self.nbf {
            Some(nbf) => now_secs.saturating_add(clock_skew_secs) >= nbf,
            None => true,
        }
    }

    /// Validates the `iss` (issuer) claim against an expected value.
    ///
    /// Returns `true` if the `iss` claim is present and matches the
    /// expected issuer exactly.
    #[must_use]
    #[inline]
    pub fn validate_iss(&self, expected: &str) -> bool {
        self.iss.as_deref() == Some(expected)
    }

    /// Validates the `aud` (audience) claim against an expected audience.
    ///
    /// Returns `true` if the expected audience appears in the `aud` list.
    #[must_use]
    #[inline]
    pub fn validate_aud(&self, expected: &str) -> bool {
        self.aud.iter().any(|a| a == expected)
    }

    /// Accesses a custom claim by key from the raw JSON payload.
    #[must_use]
    #[inline]
    pub fn get_claim(&self, key: &str) -> Option<&JsonValue> {
        self.raw.get(key)
    }
}

// ---------------------------------------------------------------------------
// Error type
// ---------------------------------------------------------------------------

/// The category of JWT claims parse failure.
#[derive(Debug, Clone, PartialEq, Eq)]
enum JwtClaimsErrorKind {
    /// The payload segment is not valid Base64url.
    InvalidBase64,
    /// The decoded payload is not valid UTF-8.
    InvalidUtf8,
    /// The decoded payload is not valid JSON.
    InvalidJson,
    /// The `aud` claim has an invalid type (not a string or array of strings).
    InvalidAudience,
}

/// Error returned when JWT claims parsing fails.
///
/// Error messages never include the raw payload content to avoid leaking
/// potentially sensitive data (tokens, user identifiers).
#[doc(alias = "claims_error")]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct JwtClaimsError {
    kind: JwtClaimsErrorKind,
}

impl fmt::Display for JwtClaimsError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self.kind {
            JwtClaimsErrorKind::InvalidBase64 => {
                write!(f, "jwt claims: invalid base64url encoding")
            }
            JwtClaimsErrorKind::InvalidUtf8 => {
                write!(f, "jwt claims: decoded bytes are not valid UTF-8")
            }
            JwtClaimsErrorKind::InvalidJson => {
                write!(f, "jwt claims: decoded content is not valid JSON")
            }
            JwtClaimsErrorKind::InvalidAudience => {
                write!(f, "jwt claims: 'aud' claim has invalid type")
            }
        }
    }
}

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

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;
    use crate::encoding::base64url_encode;

    /// Helper: encode a JSON string as base64url for claim parsing.
    fn encode_claims(json: &str) -> String {
        base64url_encode(json.as_bytes())
    }

    // --- Parsing ---

    #[test]
    fn parse_minimal_claims() {
        let b64 = encode_claims("{}");
        let claims = JwtClaims::parse(&b64).unwrap();
        assert_eq!(claims.iss(), None);
        assert_eq!(claims.sub(), None);
        assert!(claims.aud().is_empty());
        assert_eq!(claims.exp(), None);
        assert_eq!(claims.nbf(), None);
        assert_eq!(claims.iat(), None);
        assert_eq!(claims.jti(), None);
    }

    #[test]
    fn parse_full_claims() {
        let json = r#"{
            "iss": "https://auth.example.com",
            "sub": "user-123",
            "aud": "my-client",
            "exp": 1700000000,
            "nbf": 1699999000,
            "iat": 1699999000,
            "jti": "unique-id-abc"
        }"#;
        let b64 = encode_claims(json);
        let claims = JwtClaims::parse(&b64).unwrap();

        assert_eq!(claims.iss(), Some("https://auth.example.com"));
        assert_eq!(claims.sub(), Some("user-123"));
        assert_eq!(claims.aud(), &["my-client"]);
        assert_eq!(claims.exp(), Some(1_700_000_000));
        assert_eq!(claims.nbf(), Some(1_699_999_000));
        assert_eq!(claims.iat(), Some(1_699_999_000));
        assert_eq!(claims.jti(), Some("unique-id-abc"));
    }

    #[test]
    fn parse_aud_as_array() {
        let json = r#"{"aud": ["client-a", "client-b"]}"#;
        let b64 = encode_claims(json);
        let claims = JwtClaims::parse(&b64).unwrap();
        assert_eq!(claims.aud(), &["client-a", "client-b"]);
    }

    #[test]
    fn parse_aud_as_single_string() {
        let json = r#"{"aud": "single-client"}"#;
        let b64 = encode_claims(json);
        let claims = JwtClaims::parse(&b64).unwrap();
        assert_eq!(claims.aud(), &["single-client"]);
    }

    #[test]
    fn reject_invalid_aud_type() {
        let json = r#"{"aud": 42}"#;
        let b64 = encode_claims(json);
        let err = JwtClaims::parse(&b64).unwrap_err();
        assert!(err.to_string().contains("aud"));
    }

    #[test]
    fn reject_aud_array_with_non_string() {
        let json = r#"{"aud": ["ok", 42]}"#;
        let b64 = encode_claims(json);
        assert!(JwtClaims::parse(&b64).is_err());
    }

    // --- Custom claims ---

    #[test]
    fn get_custom_claim() {
        let json = r#"{"iss": "test", "custom_field": "custom_value"}"#;
        let b64 = encode_claims(json);
        let claims = JwtClaims::parse(&b64).unwrap();

        let custom = claims.get_claim("custom_field").unwrap();
        assert_eq!(custom.as_str(), Some("custom_value"));
    }

    #[test]
    fn get_missing_custom_claim() {
        let b64 = encode_claims("{}");
        let claims = JwtClaims::parse(&b64).unwrap();
        assert_eq!(claims.get_claim("nonexistent"), None);
    }

    // --- Validation ---

    #[test]
    fn validate_exp_not_expired() {
        let json = r#"{"exp": 1000}"#;
        let b64 = encode_claims(json);
        let claims = JwtClaims::parse(&b64).unwrap();
        assert!(claims.validate_exp(999, 0));
    }

    #[test]
    fn extract_timestamp_fails_closed_on_garbage() {
        // Overflowing exp → far-future → still treated as not-expired.
        let claims = JwtClaims::parse(&encode_claims(r#"{"exp": 99999999999999999999}"#)).unwrap();
        assert!(claims.validate_exp(2_000_000_000, 0));
        // Negative exp must FAIL CLOSED (expired), not silently drop to "no
        // exp" (which `validate_exp` would treat as never-expiring).
        let claims = JwtClaims::parse(&encode_claims(r#"{"exp": -5}"#)).unwrap();
        assert!(!claims.validate_exp(0, 0));
        // Overflowing nbf → far-future → not yet valid (fails closed).
        let claims = JwtClaims::parse(&encode_claims(r#"{"nbf": 99999999999999999999}"#)).unwrap();
        assert!(!claims.validate_nbf(2_000_000_000, 0));
    }

    #[test]
    fn garbage_nbf_fails_closed() {
        // A garbage `nbf` reads as u64::MAX ("not yet valid"), the fail-CLOSED
        // direction for a not-before claim. Reading it as 0 would mean "valid
        // since the epoch" — i.e. no constraint at all.
        let claims = JwtClaims::parse(&encode_claims(r#"{"nbf": -5}"#)).unwrap();
        assert_eq!(claims.nbf(), Some(u64::MAX));
        assert!(!claims.validate_nbf(0, 0));
    }

    #[test]
    fn string_typed_timestamps_fail_closed() {
        // A string-typed `exp` used to parse to None, which `validate_exp`
        // treats as "never expires" — a fail-OPEN read of a malformed token.
        let claims = JwtClaims::parse(&encode_claims(r#"{"exp": "1735689600"}"#)).unwrap();
        assert_eq!(claims.exp(), Some(0));
        assert!(!claims.validate_exp(0, 0));
        // Same for a non-numeric `nbf`, in its own fail-closed direction.
        let claims = JwtClaims::parse(&encode_claims(r#"{"nbf": true}"#)).unwrap();
        assert_eq!(claims.nbf(), Some(u64::MAX));
        assert!(!claims.validate_nbf(2_000_000_000, 0));
    }

    #[test]
    fn validate_exp_exactly_expired() {
        let json = r#"{"exp": 1000}"#;
        let b64 = encode_claims(json);
        let claims = JwtClaims::parse(&b64).unwrap();
        // now == exp means expired (exp is exclusive upper bound).
        assert!(!claims.validate_exp(1000, 0));
    }

    #[test]
    fn validate_exp_expired() {
        let json = r#"{"exp": 1000}"#;
        let b64 = encode_claims(json);
        let claims = JwtClaims::parse(&b64).unwrap();
        assert!(!claims.validate_exp(1001, 0));
    }

    #[test]
    fn validate_exp_with_clock_skew() {
        let json = r#"{"exp": 1000}"#;
        let b64 = encode_claims(json);
        let claims = JwtClaims::parse(&b64).unwrap();
        // now=1005, exp=1000, skew=10 → exp+skew=1010 > 1005 → valid.
        assert!(claims.validate_exp(1005, 10));
    }

    #[test]
    fn validate_exp_absent_returns_true() {
        let b64 = encode_claims("{}");
        let claims = JwtClaims::parse(&b64).unwrap();
        assert!(claims.validate_exp(9999, 0));
    }

    // --- validate_nbf ---

    #[test]
    fn validate_nbf_already_valid() {
        let json = r#"{"nbf": 1000}"#;
        let b64 = encode_claims(json);
        let claims = JwtClaims::parse(&b64).unwrap();
        // now=1000, nbf=1000 → now >= nbf → valid.
        assert!(claims.validate_nbf(1000, 0));
    }

    #[test]
    fn validate_nbf_not_yet_valid() {
        let json = r#"{"nbf": 1000}"#;
        let b64 = encode_claims(json);
        let claims = JwtClaims::parse(&b64).unwrap();
        // now=999, nbf=1000 → now < nbf → not valid.
        assert!(!claims.validate_nbf(999, 0));
    }

    #[test]
    fn validate_nbf_with_clock_skew() {
        let json = r#"{"nbf": 1000}"#;
        let b64 = encode_claims(json);
        let claims = JwtClaims::parse(&b64).unwrap();
        // now=995, nbf=1000, skew=10 → now+skew=1005 >= 1000 → valid.
        assert!(claims.validate_nbf(995, 10));
    }

    #[test]
    fn validate_nbf_with_clock_skew_still_invalid() {
        let json = r#"{"nbf": 1000}"#;
        let b64 = encode_claims(json);
        let claims = JwtClaims::parse(&b64).unwrap();
        // now=985, nbf=1000, skew=10 → now+skew=995 < 1000 → not valid.
        assert!(!claims.validate_nbf(985, 10));
    }

    #[test]
    fn validate_nbf_absent_returns_true() {
        let b64 = encode_claims("{}");
        let claims = JwtClaims::parse(&b64).unwrap();
        assert!(claims.validate_nbf(0, 0));
    }

    #[test]
    fn validate_iss_match() {
        let json = r#"{"iss": "https://auth.example.com"}"#;
        let b64 = encode_claims(json);
        let claims = JwtClaims::parse(&b64).unwrap();
        assert!(claims.validate_iss("https://auth.example.com"));
    }

    #[test]
    fn validate_iss_mismatch() {
        let json = r#"{"iss": "https://auth.example.com"}"#;
        let b64 = encode_claims(json);
        let claims = JwtClaims::parse(&b64).unwrap();
        assert!(!claims.validate_iss("https://other.example.com"));
    }

    #[test]
    fn validate_iss_absent() {
        let b64 = encode_claims("{}");
        let claims = JwtClaims::parse(&b64).unwrap();
        assert!(!claims.validate_iss("any"));
    }

    #[test]
    fn validate_aud_match() {
        let json = r#"{"aud": ["client-a", "client-b"]}"#;
        let b64 = encode_claims(json);
        let claims = JwtClaims::parse(&b64).unwrap();
        assert!(claims.validate_aud("client-b"));
    }

    #[test]
    fn validate_aud_mismatch() {
        let json = r#"{"aud": "client-a"}"#;
        let b64 = encode_claims(json);
        let claims = JwtClaims::parse(&b64).unwrap();
        assert!(!claims.validate_aud("client-x"));
    }

    #[test]
    fn validate_aud_empty() {
        let b64 = encode_claims("{}");
        let claims = JwtClaims::parse(&b64).unwrap();
        assert!(!claims.validate_aud("any"));
    }

    // --- Error cases ---

    #[test]
    fn reject_invalid_base64() {
        let err = JwtClaims::parse("!!!invalid!!!").unwrap_err();
        assert!(err.to_string().contains("base64url"));
    }

    #[test]
    fn reject_invalid_json() {
        let b64 = base64url_encode(b"not json");
        let err = JwtClaims::parse(&b64).unwrap_err();
        assert!(err.to_string().contains("JSON"));
    }

    #[test]
    fn error_implements_std_error() {
        let err: Box<dyn std::error::Error> = Box::new(JwtClaimsError {
            kind: JwtClaimsErrorKind::InvalidJson,
        });
        let _ = err.to_string();
    }
}