rs-jwt

JSON Web Token encoding, decoding, and validation with HMAC algorithms

Installation

[dependencies]
philiprehberger-jwt = "0.3.0"

Usage

use philiprehberger_jwt::{encode, decode, Algorithm, Claims, RegisteredClaims, Validation};
use std::time::{SystemTime, UNIX_EPOCH};

let now = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_secs();

let claims = Claims {
    registered: RegisteredClaims {
        sub: Some("user-123".into()),
        exp: Some(now + 3600),
        iat: Some(now),
        ..Default::default()
    },
    custom: serde_json::json!({}),
};

let secret = b"my-secret-key";
let token = encode(&claims, secret, Algorithm::HS256).unwrap();

let validation = Validation::default();
let decoded: Claims<serde_json::Value> = decode(&token, secret, &validation).unwrap();
assert_eq!(decoded.registered.sub, Some("user-123".into()));

Custom claims

use serde::{Serialize, Deserialize};
use philiprehberger_jwt::{encode, decode, Algorithm, Claims, RegisteredClaims, Validation};

#[derive(Debug, Serialize, Deserialize)]
struct MyClaims {
    role: String,
    permissions: Vec<String>,
}

let claims = Claims {
    registered: RegisteredClaims::default(),
    custom: MyClaims {
        role: "admin".into(),
        permissions: vec!["read".into(), "write".into()],
    },
};

let token = encode(&claims, b"secret", Algorithm::HS256).unwrap();
let decoded: Claims<MyClaims> = decode(&token, b"secret", &Validation::default()).unwrap();
assert_eq!(decoded.custom.role, "admin");

Quick encoding with encode_simple

use philiprehberger_jwt::encode_simple;
use serde::Serialize;

#[derive(Serialize)]
struct Payload {
    user_id: u64,
}

let token = encode_simple(&Payload { user_id: 42 }, b"secret").unwrap();

Validation options

use philiprehberger_jwt::Validation;

let validation = Validation::default()
    .leeway(30)
    .issuer("my-app")
    .audience("my-api")
    .required_claims(vec!["sub".into()]);

Inspect a token header

use philiprehberger_jwt::{inspect, Algorithm};

let header = inspect(&token).unwrap();
assert_eq!(header.alg, Algorithm::HS256);

Encode with a custom header (key rotation via kid)

use philiprehberger_jwt::{encode_with_header, Algorithm, Claims, Header, RegisteredClaims};

let mut header = Header::new(Algorithm::HS256);
header.kid = Some("key-2026".into());

let claims = Claims {
    registered: RegisteredClaims::default(),
    custom: serde_json::json!({}),
};
let token = encode_with_header(&header, &claims, b"secret").unwrap();

Multiple accepted audiences

use philiprehberger_jwt::Validation;

let validation = Validation::default()
    .audiences(vec!["gateway".to_string(), "downstream".to_string()]);
// Tokens whose `aud` is either "gateway" or "downstream" pass.

API

Function	Description
encode(claims, secret, algorithm)	Encode claims into a signed JWT string
encode_with_header(header, claims, secret)	Encode using a caller-provided header (e.g. with kid)
decode(token, secret, validation)	Decode and validate a JWT, returning typed claims
encode_simple(claims, secret)	Encode with HS256 and auto-set iat
inspect(token)	Decode the header without verifying the signature
decode_without_validation(token)	Decode claims without any verification (unsafe)
Algorithm::name()	Canonical algorithm string ("HS256", etc.)
Validation::audiences(list)	Accept tokens whose aud matches any value in the list

Type	Description
Algorithm	HMAC algorithm: HS256, HS384, HS512
Header	JWT header with algorithm and optional key ID
Claims<T>	Registered claims combined with custom typed claims
RegisteredClaims	Standard JWT claims (iss, sub, aud, exp, nbf, iat, jti)
Validation	Builder for configuring claim validation rules
JwtError	Error type for all JWT operations

Development

cargo test
cargo clippy -- -D warnings

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT