postrust_auth/

jwt.rs

//! JWT token validation.
//!
//! The signature is checked by the library; the claims are checked here. That
//! split is deliberate: a claim can be wrong in two different ways -- absent,
//! or present and not the kind of thing that claim is -- and the client needs
//! to be told which. A library that folds both into "invalid token" answers a
//! question nobody asked.

use super::{AuthResult, ClaimFault, JwtConfig, JwtError, KeySet};
use jsonwebtoken::{decode, decode_header, Header, Validation};
use std::collections::HashMap;

/// How far ahead of the server a token's clock may be.
///
/// A token minted a moment ago on a machine whose clock runs a little fast is
/// not a forgery, and rejecting it would make a working deployment fail
/// intermittently and unreproducibly.
///
/// Only in that direction. `exp` is checked to the second, because leniency
/// there is leniency about a token that has been *withdrawn* -- it keeps a
/// revoked session alive past the moment its issuer said it ended, and it is a
/// window an attacker holding a stale token gets for free. `nbf` and `iat`
/// describe a token that is not valid *yet*, where the same slack costs
/// nothing and is the only remedy for a clock nobody controls.
const ALLOWED_SKEW: i64 = 30;

/// Validate a JWT token and extract claims.
pub fn validate_token(token: &str, config: &JwtConfig) -> Result<AuthResult, JwtError> {
    let keys = config.keys.as_ref().ok_or(JwtError::SecretMissing)?;

    // Read unverified, and used for one thing only: choosing which keys to try.
    // Nothing in it is believed -- its `alg` must be one the chosen key admits,
    // and the key, not the header, is what the signature is checked against.
    // A header that does not parse, `alg: none` among them, names no key.
    let header = decode_header(token).map_err(|e| match map_jwt_error(e) {
        JwtError::Claim(ClaimFault::Unparsable) => JwtError::NoSuitableKey,
        other => other,
    })?;

    let claims = verify(token, &header, &keys.current())?;

    check_claims(&claims, config, now())?;

    // The role decides what the request may do, so a token naming none, on a
    // server with no anonymous role, is a request with no identity at all.
    let role = role_of(&claims, config).ok_or(JwtError::NoIdentity)?;

    Ok(AuthResult { role, claims })
}

/// Check the signature against the keys the header selects.
///
/// No candidate at all -- an unknown `kid`, or an `alg` no key admits -- is a
/// token this server holds no key for, which PostgREST reports as "No
/// suitable key or wrong key type". Candidates that all refuse it is a
/// signature that does not verify. A token without a `kid` is tried against
/// every candidate in turn and passes on the first that verifies it, as in
/// PostgREST.
fn verify(
    token: &str,
    header: &Header,
    keys: &KeySet,
) -> Result<HashMap<String, serde_json::Value>, JwtError> {
    // Signature only, and only the header's algorithm, which every candidate
    // is already known to admit. Every claim the library could check here, it
    // checks differently from the way this API's contract says to -- a
    // missing `exp` is not an error, an `aud` that is not a string has a code
    // of its own -- so all of it is done in `check_claims`, where the answers
    // can be the right ones.
    let mut validation = Validation::new(header.alg);
    validation.validate_exp = false;
    validation.validate_nbf = false;
    validation.validate_aud = false;
    validation.required_spec_claims.clear();

    let mut failure = JwtError::NoSuitableKey;
    for key in keys.candidates(header.kid.as_deref(), header.alg) {
        match decode::<HashMap<String, serde_json::Value>>(token, key, &validation) {
            Ok(data) => return Ok(data.claims),
            // The signature verified and the payload is not claims. Another
            // key cannot change what the payload says.
            Err(e) if matches!(e.kind(), jsonwebtoken::errors::ErrorKind::Json(_)) => {
                return Err(JwtError::Claim(ClaimFault::Unparsable))
            }
            // A signature that failed under one candidate is the more useful
            // thing to report than a later candidate's key that could not be
            // used at all.
            Err(e) => {
                if !matches!(failure, JwtError::InvalidSignature) {
                    failure = map_jwt_error(e);
                }
            }
        }
    }
    Err(failure)
}

/// The role a token names, or the anonymous one where it names none.
///
/// A role is a name, and only a string is one. Rendering anything else --
/// `"role": 42`, `"role": {"a": 1}` -- would make a database role nobody
/// created out of a claim that does not name one, so a claim of the wrong
/// shape is read as a token that named no role at all and falls back the same
/// way an absent claim does.
///
/// So are two strings that are not names either. The role is switched to with
/// `set_config('role', ..)`, and PostgreSQL reads `none` there as "no role":
/// the request would run as the connection's own role, the authenticator,
/// rather than as one the token names. An empty string names no role at all,
/// and was refused by the database with a 500.
fn role_of(claims: &HashMap<String, serde_json::Value>, config: &JwtConfig) -> Option<String> {
    lookup_claim(claims, &config.role_claim_key)
        .and_then(serde_json::Value::as_str)
        .filter(|role| !matches!(*role, "" | "none"))
        .map(str::to_string)
        .or_else(|| config.anon_role.clone())
}

/// Resolve a claim key, which may name a nested claim.
///
/// The literal key is tried first, and a dotted path only if that misses. The
/// order matters: a top-level claim name is allowed to contain dots, and the
/// ones that do are exactly the ones that must not be re-read as a path --
/// Hasura mints `https://hasura.io/jwt/claims`, and splitting that would look
/// for a claim named `https://hasura` instead.
///
/// Only objects are walked. A path that runs into a string or a number stops
/// there and finds nothing, rather than pretending the rest of the path was
/// satisfied.
fn lookup_claim<'a>(
    claims: &'a HashMap<String, serde_json::Value>,
    key: &str,
) -> Option<&'a serde_json::Value> {
    if let Some(value) = claims.get(key) {
        return Some(value);
    }

    let (first, rest) = key.split_once('.')?;
    let mut current = claims.get(first)?;
    for segment in rest.split('.') {
        current = current.as_object()?.get(segment)?;
    }
    Some(current)
}

/// The registered claims, checked in the order the contract checks them.
///
/// Order is part of the answer: a token that is both expired and out of
/// audience is reported as expired, because that is the first thing wrong with
/// it and the one the client can act on.
fn check_claims(
    claims: &HashMap<String, serde_json::Value>,
    config: &JwtConfig,
    now: i64,
) -> Result<(), JwtError> {
    // A claim that is absent is not a claim that is wrong. Only one that is
    // present in the wrong shape is.
    let number = |name: &'static str| -> Result<Option<i64>, JwtError> {
        match claims.get(name) {
            None | Some(serde_json::Value::Null) => Ok(None),
            Some(value) => value
                .as_f64()
                .map(|seconds| seconds as i64)
                .map(Some)
                .ok_or(JwtError::Claim(ClaimFault::NotANumber(name))),
        }
    };

    if let Some(exp) = number("exp")? {
        if now > exp {
            return Err(JwtError::Claim(ClaimFault::Expired));
        }
    }
    if let Some(nbf) = number("nbf")? {
        if now + ALLOWED_SKEW < nbf {
            return Err(JwtError::Claim(ClaimFault::NotYetValid));
        }
    }
    if let Some(iat) = number("iat")? {
        if now + ALLOWED_SKEW < iat {
            return Err(JwtError::Claim(ClaimFault::IssuedInFuture));
        }
    }

    // With no audience configured the server accepts any, but the claim still
    // has to *be* an audience: a list with an object in it is a malformed
    // token, not a token meant for somebody else. That is the difference
    // between a client fixing how it mints tokens and hunting for a setting
    // this server does not have.
    let matches = |aud: &str| match &config.audience {
        Some(wanted) => aud == wanted,
        None => true,
    };
    match claims.get("aud") {
        None | Some(serde_json::Value::Null) => {}
        Some(serde_json::Value::String(aud)) => {
            if !matches(aud) {
                return Err(JwtError::Claim(ClaimFault::NotInAudience));
            }
        }
        Some(serde_json::Value::Array(auds)) => {
            if !auds.iter().all(serde_json::Value::is_string) {
                return Err(JwtError::Claim(ClaimFault::AudienceNotStrings));
            }
            // A list naming no audience excludes nobody.
            let admitted = auds
                .iter()
                .filter_map(serde_json::Value::as_str)
                .any(matches);
            if !auds.is_empty() && !admitted {
                return Err(JwtError::Claim(ClaimFault::NotInAudience));
            }
        }
        Some(_) => return Err(JwtError::Claim(ClaimFault::AudienceNotStrings)),
    }

    // Unlike `aud`, an absent `iss` is not admitted. A token without an `aud`
    // says it is meant for everyone, which is how PostgREST reads it; a token
    // without an `iss` says nothing about who minted it, and naming the one
    // issuer to accept is the whole of what this setting is for. It matters
    // most where it is most likely to be set: an identity provider whose
    // signing keys are shared across tenants, where the `iss` is the only
    // thing that tells one tenant's tokens from another's. And unlike `aud`,
    // nothing is checked when no issuer is configured -- PostgREST does not
    // look at `iss` at all, so a token it accepts must not be refused here
    // over the shape of a claim nobody asked about.
    if let Some(wanted) = &config.issuer {
        if claims.get("iss").and_then(serde_json::Value::as_str) != Some(wanted.as_str()) {
            return Err(JwtError::Claim(ClaimFault::UnexpectedIssuer));
        }
    }

    Ok(())
}

/// Seconds since the epoch. `web_time` is `std::time` natively; on wasm32,
/// where `SystemTime::now()` panics, it asks the JavaScript host.
fn now() -> i64 {
    web_time::SystemTime::now()
        .duration_since(web_time::UNIX_EPOCH)
        .map(|elapsed| elapsed.as_secs() as i64)
        .unwrap_or_default()
}

/// Map jsonwebtoken error to JwtError.
fn map_jwt_error(e: jsonwebtoken::errors::Error) -> JwtError {
    use jsonwebtoken::errors::ErrorKind;

    match e.kind() {
        ErrorKind::InvalidSignature => JwtError::InvalidSignature,
        // The token was read and its claims were not a JSON object, which is a
        // different failure from a key that could not decode it at all.
        ErrorKind::Json(_) => JwtError::Claim(ClaimFault::Unparsable),
        _ => JwtError::NoSuitableKey,
    }
}

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

    fn config() -> JwtConfig {
        JwtConfig {
            keys: crate::JwtKeys::from_config(Some("reallyreallyreallyreallyverysafe"), false)
                .unwrap(),
            ..JwtConfig::default()
        }
    }

    fn claims(json: serde_json::Value) -> HashMap<String, serde_json::Value> {
        match json {
            serde_json::Value::Object(map) => map.into_iter().collect(),
            _ => panic!("claims must be an object"),
        }
    }

    fn role_with(key: &str, json: serde_json::Value) -> Option<String> {
        let config = JwtConfig {
            role_claim_key: key.to_string(),
            ..config()
        };
        role_of(&claims(json), &config)
    }

    #[test]
    fn a_flat_role_claim_is_found() {
        assert_eq!(
            role_with("role", serde_json::json!({"role": "web_user"})),
            Some("web_user".to_string())
        );
        assert_eq!(
            role_with("my_role", serde_json::json!({"my_role": "web_user"})),
            Some("web_user".to_string())
        );
    }

    /// `none` would run the request as the authenticator, and `""` names
    /// nothing: both are read as no role, as a role that is not a string is.
    #[test]
    fn a_role_of_none_or_nothing_is_no_role() {
        for role in ["none", ""] {
            assert_eq!(role_with("role", serde_json::json!({ "role": role })), None);
            let anon = JwtConfig {
                anon_role: Some("web_anon".into()),
                ..config()
            };
            assert_eq!(
                role_of(&claims(serde_json::json!({ "role": role })), &anon),
                Some("web_anon".to_string())
            );
        }
        // A role that only looks like it is still a role.
        assert_eq!(
            role_with("role", serde_json::json!({"role": "None"})),
            Some("None".to_string())
        );
    }

    #[test]
    fn a_dotted_key_reaches_a_nested_claim() {
        // `PGRST_JWT_ROLE_CLAIM_KEY="user.role"` over
        // `{"user": {"role": "..."}}` is the example the documentation gives.
        // A flat `get` looks for a claim literally named `user.role`, finds
        // nothing, and every such request silently became anonymous.
        assert_eq!(
            role_with(
                "user.role",
                serde_json::json!({"user": {"role": "web_user"}})
            ),
            Some("web_user".to_string())
        );
        assert_eq!(
            role_with("a.b.c", serde_json::json!({"a": {"b": {"c": "web_user"}}})),
            Some("web_user".to_string())
        );
    }

    #[test]
    fn a_literal_dotted_claim_wins_over_the_path_reading() {
        // Hasura mints `https://hasura.io/jwt/claims`, and a namespaced claim
        // name full of dots must not be split into a path.
        assert_eq!(
            role_with(
                "https://hasura.io/jwt/claims",
                serde_json::json!({"https://hasura.io/jwt/claims": "web_user"})
            ),
            Some("web_user".to_string())
        );
        // Both present: the literal key is the one that was asked for.
        assert_eq!(
            role_with(
                "user.role",
                serde_json::json!({"user.role": "literal", "user": {"role": "nested"}})
            ),
            Some("literal".to_string())
        );
    }

    #[test]
    fn a_path_that_runs_into_a_non_object_finds_nothing() {
        // Falls back to the anonymous role rather than inventing one.
        let anon = JwtConfig {
            role_claim_key: "user.role".to_string(),
            anon_role: Some("web_anon".to_string()),
            ..config()
        };
        assert_eq!(
            role_of(&claims(serde_json::json!({"user": "not-an-object"})), &anon),
            Some("web_anon".to_string())
        );
        assert_eq!(
            role_of(&claims(serde_json::json!({"user": {"other": 1}})), &anon),
            Some("web_anon".to_string())
        );
    }

    /// The token in PostgREST's own suite carries `"aud": [{...}, "test"]`,
    /// which is neither an audience nor a list of them.
    #[test]
    fn an_audience_that_is_not_a_string_is_a_malformed_token() {
        assert!(matches!(
            check_claims(
                &claims(serde_json::json!({"aud": [{"invalid": "value"}, "test"]})),
                &config(),
                0
            ),
            Err(JwtError::Claim(ClaimFault::AudienceNotStrings))
        ));
    }

    /// With no audience configured, any audience is this server's.
    #[test]
    fn any_audience_is_accepted_when_none_is_configured() {
        assert!(check_claims(
            &claims(serde_json::json!({"aud": ["someone", "else"]})),
            &config(),
            0
        )
        .is_ok());
    }

    /// A list naming no audience excludes nobody.
    #[test]
    fn an_empty_audience_list_excludes_no_one() {
        let configured = JwtConfig {
            audience: Some("us".into()),
            ..config()
        };
        assert!(check_claims(&claims(serde_json::json!({"aud": []})), &configured, 0).is_ok());
        assert!(matches!(
            check_claims(
                &claims(serde_json::json!({"aud": ["them"]})),
                &configured,
                0
            ),
            Err(JwtError::Claim(ClaimFault::NotInAudience))
        ));
    }

    /// A token that does not say when it expires does not expire.
    #[test]
    fn a_token_without_exp_is_not_rejected_for_having_none() {
        assert!(check_claims(&claims(serde_json::json!({"role": "x"})), &config(), 0).is_ok());
    }

    /// Present, but not the kind of thing that claim is.
    #[test]
    fn a_timestamp_claim_that_is_not_a_number_is_reported_as_such() {
        assert!(matches!(
            check_claims(&claims(serde_json::json!({"exp": "soon"})), &config(), 0),
            Err(JwtError::Claim(ClaimFault::NotANumber("exp")))
        ));
    }

    /// A clock a few seconds ahead is not a forgery.
    #[test]
    fn a_token_that_is_not_valid_yet_is_given_the_benefit_of_the_clock() {
        let issued_moments_hence = claims(serde_json::json!({"iat": 1_000}));
        assert!(check_claims(&issued_moments_hence, &config(), 990).is_ok());
        assert!(matches!(
            check_claims(&issued_moments_hence, &config(), 900),
            Err(JwtError::Claim(ClaimFault::IssuedInFuture))
        ));

        let valid_moments_hence = claims(serde_json::json!({"nbf": 1_000}));
        assert!(check_claims(&valid_moments_hence, &config(), 990).is_ok());
        assert!(matches!(
            check_claims(&valid_moments_hence, &config(), 900),
            Err(JwtError::Claim(ClaimFault::NotYetValid))
        ));
    }

    /// The same slack the other way would keep a withdrawn token alive past
    /// the second its issuer said it ended.
    #[test]
    fn an_expiry_is_honoured_to_the_second() {
        let expires_at = claims(serde_json::json!({"exp": 1_000}));
        assert!(check_claims(&expires_at, &config(), 1_000).is_ok());
        assert!(matches!(
            check_claims(&expires_at, &config(), 1_001),
            Err(JwtError::Claim(ClaimFault::Expired))
        ));
    }

    /// A role is a name, and a claim that is not a string does not carry one.
    #[test]
    fn a_role_claim_that_is_not_a_string_names_no_role() {
        let configured = JwtConfig {
            anon_role: Some("anon".into()),
            ..config()
        };
        for value in [
            serde_json::json!(42),
            serde_json::json!({"a": 1}),
            serde_json::json!(["admin"]),
        ] {
            let mut claims = HashMap::new();
            claims.insert("role".to_string(), value.clone());
            assert_eq!(
                role_of(&claims, &configured),
                Some("anon".to_string()),
                "{value}"
            );
        }

        let mut named = HashMap::new();
        named.insert("role".to_string(), serde_json::json!("web_user"));
        assert_eq!(role_of(&named, &configured), Some("web_user".to_string()));
    }

    /// Configured, the issuer must be named, and named exactly.
    #[test]
    fn a_configured_issuer_must_be_the_tokens() {
        let configured = JwtConfig {
            issuer: Some("https://issuer.example".into()),
            ..config()
        };
        assert!(check_claims(
            &claims(serde_json::json!({"iss": "https://issuer.example"})),
            &configured,
            0
        )
        .is_ok());
        for token in [
            serde_json::json!({"iss": "https://issuer.example/"}),
            serde_json::json!({"iss": null}),
            serde_json::json!({}),
        ] {
            assert!(
                matches!(
                    check_claims(&claims(token.clone()), &configured, 0),
                    Err(JwtError::Claim(ClaimFault::UnexpectedIssuer))
                ),
                "{token}"
            );
        }
    }

    /// Unconfigured, `iss` is not looked at, whatever shape it has.
    #[test]
    fn no_issuer_configured_means_iss_is_not_checked() {
        for iss in [serde_json::json!("anyone"), serde_json::json!(42)] {
            assert!(check_claims(&claims(serde_json::json!({"iss": iss})), &config(), 0).is_ok());
        }
    }

    /// An expired token is reported as expired before its issuer is.
    #[test]
    fn expiry_is_reported_before_the_issuer() {
        let configured = JwtConfig {
            issuer: Some("https://issuer.example".into()),
            ..config()
        };
        assert!(matches!(
            check_claims(&claims(serde_json::json!({"exp": 1})), &configured, 9_000),
            Err(JwtError::Claim(ClaimFault::Expired))
        ));
    }

    /// The first thing wrong with the token is what the client is told.
    #[test]
    fn an_expired_token_is_reported_as_expired_whatever_else_is_wrong() {
        assert!(matches!(
            check_claims(
                &claims(serde_json::json!({"exp": 1_000, "aud": [{"bad": 1}]})),
                &config(),
                9_000
            ),
            Err(JwtError::Claim(ClaimFault::Expired))
        ));
    }
}