jwt-lab 0.1.1

JWT crate for Rust: decode, verify, sign, mutate, JWK/JWKS, algorithm selection, time validation, and secure APIs.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

# jwt-lab

[![Crates.io](https://img.shields.io/crates/v/jwt-lab.svg)](https://crates.io/crates/jwt-lab)
[![Documentation](https://docs.rs/jwt-lab/badge.svg)](https://docs.rs/jwt-lab)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](https://github.com/yourname/jwt-lab#license)

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`:

```toml
[dependencies]
jwt-lab = "0.1"
```

### Basic Usage

```rust
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

```rust
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

```rust
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](LICENSE-MIT) or http://opensource.org/licenses/MIT).