jwt-lab

JWT crate for Rust. Decode, verify, sign, mutate, select keys from JWKS by kid, validate times with leeway, and choose algorithms with feature flags.

Features

• Multiple Algorithms: HS256/384/512, RS256/384/512, ES256/384/512, EdDSA
• JWK/JWKS Support: Verify tokens using JSON Web Key Sets
• Algorithm Validation: Prevent algorithm confusion attacks
• Time Validation: Configurable leeway for exp and nbf claims
• Claims Mutation: Modify JWT claims using JSON pointer paths
• Feature Flags: Fine-grained control over included algorithms
• Strong Error Types: Comprehensive error handling with clear messages

Usage

Add to your Cargo.toml:

[dependencies]
jwt-lab = "0.1"

Basic Usage

use jwt_lab::{Jwt, Key, VerifyOptions, Algorithm};

// Decode and verify a JWT
let token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
let jwt = Jwt::decode(token)?;

// Always validate the algorithm to prevent alg confusion attacks
jwt.verify(
    &Key::hs("secret"),
    VerifyOptions::default()
        .expect_alg(Algorithm::HS256)
        .leeway(30)
)?;

JWKS Verification

use jwt_lab::{Jwt, Jwks, VerifyOptions};

let jwks = Jwks::from_str(&std::fs::read_to_string("jwks.json")?)?;
let jwt = Jwt::decode(token)?;
jwt.verify_with_jwks(&jwks, VerifyOptions::default())?;

Signing Tokens

use jwt_lab::{Algorithm, Header, Claims, Key};
use jwt_lab::sign::sign;
use serde_json::json;

let header = Header {
    alg: Algorithm::HS256,
    typ: Some("JWT".into()),
    kid: None,
    extra: Default::default()
};
let claims = Claims(serde_json::from_value(json!({
    "sub": "user123",
    "iat": 1516239022,
    "exp": 1516242622
}))?);

let token = sign(&header, &claims, &Key::hs("secret"))?;

Security Considerations

⚠️ Important Security Notes:

• Always validate the algorithm to prevent algorithm confusion attacks
• Never accept tokens with alg: "none"
• Set appropriate expiration times and use minimal leeway
• Validate issuer and audience claims when possible
• Use strong, random secrets for HMAC algorithms
• Keep private keys secure and rotate them regularly

Feature Flags

• hs - Enable HMAC algorithms (HS256, HS384, HS512)
• rs - Enable RSA algorithms (RS256, RS384, RS512)
• es - Enable ECDSA algorithms (ES256, ES384, ES512)
• eddsa - Enable EdDSA algorithm
• jwk - Enable JWK/JWKS support
• explain - Enable detailed error explanations

License

Licensed under the MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT).