feat: add macros for custom headers and claims

Add `Header` derive macro, `header` attribute macro, and `claims`
attribute macro.

`Header` derive macro implements required traits for custom headers
`header` and `claims` are convenience attribute macros that add
the required derive macros.

Author: dsykes16

Cargo.toml

@@ -44,6 +44,9 @@ rand = { version = "0.8.5", optional = true, features = ["std"], default-feature
 rsa = { version = "0.9.6", optional = true }
 sha2 = { version = "0.10.7", optional = true, features = ["oid"] }
 
+# proc-macros (e.g. Header, claims)
+jsonwebtoken-proc-macros = { path = "jsonwebtoken-proc-macros" }
+
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 js-sys = "0.3"
 getrandom = "0.2"

examples/custom_header.rs

@@ -1,30 +1,25 @@
-use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 
 use jsonwebtoken::errors::ErrorKind;
+use jsonwebtoken::macros::{claims, header};
 use jsonwebtoken::{
-    Algorithm, DecodingKey, EncodingKey, Validation, decode_with_custom_header, encode, header,
+    Algorithm, DecodingKey, EncodingKey, Validation, decode_with_custom_header, encode,
 };
 
-#[derive(Debug, Serialize, Deserialize, Clone)]
+#[claims]
 struct Claims {
     sub: String,
     company: String,
     exp: u64,
 }
 
-#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq, Hash)]
+#[header]
+#[derive(PartialEq, Eq)] // only required for assertions in tests, not required by jsonwebtoken
 struct CustomHeader {
     alg: Algorithm,
     custom: String,
     another_custom_field: Option<usize>,
 }
-impl header::FromEncoded for CustomHeader {}
-impl header::Alg for CustomHeader {
-    fn alg(&self) -> &Algorithm {
-        &self.alg
-    }
-}
 
 fn main() {
     let my_claims =

examples/extras_header.rs

@@ -0,0 +1,44 @@
+use std::collections::HashMap;
+
+use jsonwebtoken::errors::ErrorKind;
+use jsonwebtoken::{
+    Algorithm, DecodingKey, EncodingKey, Header, Validation, decode, encode, macros::claims,
+};
+
+#[claims]
+struct Claims {
+    sub: String,
+    company: String,
+    exp: u64,
+}
+
+fn main() {
+    let my_claims =
+        Claims { sub: "[email protected]".to_owned(), company: "ACME".to_owned(), exp: 10000000000 };
+    let key = b"secret";
+
+    let mut extras = HashMap::with_capacity(1);
+    extras.insert("custom".to_string(), "header".to_string());
+
+    let header = Header { alg: Algorithm::HS512, extras, ..Default::default() };
+
+    let token = match encode(&header, &my_claims, &EncodingKey::from_secret(key)) {
+        Ok(t) => t,
+        Err(_) => panic!(), // in practice you would return the error
+    };
+    println!("{:?}", token);
+
+    let token_data = match decode::<Claims>(
+        &token,
+        &DecodingKey::from_secret(key),
+        &Validation::new(Algorithm::HS512),
+    ) {
+        Ok(c) => c,
+        Err(err) => match *err.kind() {
+            ErrorKind::InvalidToken => panic!(), // Example on how to handle a specific error
+            _ => panic!(),
+        },
+    };
+    println!("{:?}", token_data.claims);
+    println!("{:?}", token_data.header);
+}

jsonwebtoken-proc-macros/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "jsonwebtoken-proc-macros"
+version = "0.1.0"
+edition = "2024"
+
+[lib]
+proc-macro = true
+
+[dependencies]
+quote = "1.0.41"
+syn = { version = "2.0.106", features = ["full"] }

jsonwebtoken-proc-macros/src/lib.rs

@@ -0,0 +1,100 @@
+//! This library provides convenient derive and attribute macros for custom Header and Claim
+//! structs for `jsonwebtoken`.
+//!
+//! Example
+//! ```rust
+//! use jsonwebtoken::Algorithm;
+//! use jsonwebtoken::macros::header;
+//! #[header]
+//! struct CustomJwtHeader {
+//!     // `alg` is the only required struct field
+//!     alg: Algorithm,
+//!     custom_header: Option<String>,
+//!     another_custom_header: String,
+//! }
+//! ````
+extern crate proc_macro;
+
+use proc_macro::TokenStream;
+use quote::quote;
+use syn::{DeriveInput, Item, ItemStruct, parse_macro_input};
+
+/// Convenience macro for JWT header structs
+///
+/// Adds the following derive macros:
+/// ```rust
+/// #[derive(
+///     Debug,
+///     Clone,
+///     Default,
+///     serde::Serialize,
+///     serde::Deserialize
+/// )]
+/// ```
+#[proc_macro_attribute]
+pub fn claims(_attr: TokenStream, input: TokenStream) -> TokenStream {
+    let mut item = parse_macro_input!(input as Item);
+
+    match &mut item {
+        Item::Struct(ItemStruct { attrs, .. }) => {
+            attrs.push(
+                syn::parse_quote!(#[derive(Debug, Clone, Default, jsonwebtoken::serde::Serialize, jsonwebtoken::serde::Deserialize)]),
+            );
+            quote!(#item).into()
+        }
+        _ => syn::Error::new_spanned(&item, "#[header] can only be used on structs")
+            .to_compile_error()
+            .into(),
+    }
+}
+
+/// Convenience macro for JWT header structs
+///
+/// Adds the following derive macros:
+/// ```rust
+/// #[derive(
+///     Debug,
+///     Clone,
+///     Default,
+///     jsonwebtoken::macros::Header,
+///     serde::Serialize,
+///     serde::Deserialize
+/// )]
+/// ```
+#[proc_macro_attribute]
+pub fn header(_attr: TokenStream, input: TokenStream) -> TokenStream {
+    let mut item = parse_macro_input!(input as Item);
+
+    match &mut item {
+        Item::Struct(ItemStruct { attrs, .. }) => {
+            attrs.push(syn::parse_quote!(#[derive(Debug, Clone, Default, jsonwebtoken::serde::Serialize, jsonwebtoken::serde::Deserialize, jsonwebtoken::macros::Header)]));
+            quote!(#item).into()
+        }
+        _ => syn::Error::new_spanned(&item, "#[header] can only be used on structs")
+            .to_compile_error()
+            .into(),
+    }
+}
+
+/// Derive macro required for custom JWT headers used with `jsonwebtoken`
+///
+/// Requires an `alg: jsonwebtoken::Algorithm` field exists in the struct
+#[proc_macro_derive(Header)]
+pub fn derive_header(input: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(input as DeriveInput);
+
+    let name = &input.ident;
+    let generics = &input.generics;
+    let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();
+
+    let expanded = quote! {
+        impl #impl_generics ::jsonwebtoken::header::FromEncoded for #name #ty_generics #where_clause {}
+        impl #impl_generics ::jsonwebtoken::header::Alg for #name #ty_generics #where_clause {
+            fn alg(&self) -> &::jsonwebtoken::Algorithm {
+                &self.alg
+            }
+        }
+    };
+
+    TokenStream::from(expanded)
+}

src/decoding.rs

@@ -325,7 +325,7 @@ where
 /// DANGER: This performs zero validation on the JWT
 pub fn insecure_decode<T: DeserializeOwned + Clone>(
     token: impl AsRef<[u8]>,
-) -> Result<TokenData<T>> {
+) -> Result<TokenData<Header, T>> {
     let token = token.as_ref();
 
     let (_, message) = expect_two!(token.rsplitn(2, |b| *b == b'.'));

src/encoding.rs

@@ -153,10 +153,9 @@ impl Debug for EncodingKey {
 /// If the algorithm given is RSA or EC, the key needs to be in the PEM format.
 ///
 /// ```rust
-/// use serde::{Deserialize, Serialize};
-/// use jsonwebtoken::{encode, Algorithm, Header, EncodingKey};
+/// use jsonwebtoken::{encode, macros::claims, Algorithm, Header, EncodingKey};
 ///
-/// #[derive(Debug, Serialize, Deserialize)]
+/// #[claims]
 /// struct Claims {
 ///    sub: String,
 ///    company: String

src/header.rs

@@ -3,11 +3,13 @@ use std::collections::HashMap;
 use std::result;
 
 use base64::{Engine, engine::general_purpose::STANDARD};
+use jsonwebtoken_proc_macros::header;
 use serde::{Deserialize, Deserializer, Serialize, Serializer};
 
 use crate::algorithms::Algorithm;
 use crate::errors::Result;
 use crate::jwk::Jwk;
+use crate::macros::Header;
 use crate::serialization::b64_decode;
 
 const ZIP_SERIAL_DEFLATE: &str = "DEF";
@@ -137,7 +139,7 @@ pub trait FromEncoded {
 
 /// A basic JWT header, the alg defaults to HS256 and typ is automatically
 /// set to `JWT`. All the other fields are optional.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Header, Default, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct Header {
     /// The type of JWS: it can only be "JWT" here
     ///
@@ -254,24 +256,10 @@ impl Header {
     }
 }
 
-impl Default for Header {
-    /// Returns a JWT header using the default Algorithm, HS256
-    fn default() -> Self {
-        Header::new(Algorithm::default())
-    }
-}
-
-impl Alg for Header {
-    fn alg(&self) -> &Algorithm {
-        &self.alg
-    }
-}
-
-impl FromEncoded for Header {}
-
 /// A truly basic JWT header, the alg defaults to HS256 and typ is automatically
 /// set to `JWT`. All the other fields are optional.
-#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)]
+#[header]
+#[derive(Hash, PartialEq, Eq)]
 pub struct BasicHeader {
     /// The type of JWS: it can only be "JWT" here
     ///
@@ -370,18 +358,3 @@ impl BasicHeader {
         }
     }
 }
-
-impl Default for BasicHeader {
-    /// Returns a JWT header using the default Algorithm, HS256
-    fn default() -> Self {
-        Self::new(Algorithm::default())
-    }
-}
-
-impl Alg for BasicHeader {
-    fn alg(&self) -> &Algorithm {
-        &self.alg
-    }
-}
-
-impl FromEncoded for BasicHeader {}

src/jwk.rs

@@ -596,7 +596,7 @@ impl Jwk {
 
     /// Compute the thumbprint of the JWK.
     ///
-    /// Per [RFC-7638](https://datatracker.ietf.org/doc/html/rfc7638)
+    /// Per (RFC-7638)[<https://datatracker.ietf.org/doc/html/rfc7638>]
     pub fn thumbprint(&self, hash_function: ThumbprintHash) -> String {
         let pre = match &self.algorithm {
             AlgorithmParameters::EllipticCurve(a) => match a.curve {

src/lib.rs

@@ -13,6 +13,14 @@ compile_error!(
 #[cfg(not(any(feature = "rust_crypto", feature = "aws_lc_rs")))]
 compile_error!("at least one of the features \"rust_crypto\" or \"aws_lc_rs\" must be enabled");
 
+// hidden export of `self` as `jsonwebtoken` required by proc macros
+#[doc(hidden)]
+extern crate self as jsonwebtoken;
+
+// hidden re-export of serde for proc macros
+#[doc(hidden)]
+pub use serde;
+
 pub use algorithms::Algorithm;
 pub use decoding::{
     DecodingKey, TokenData, decode, decode_custom_header, decode_header, decode_with_custom_header,
@@ -33,10 +41,17 @@ mod decoding;
 mod encoding;
 /// All the errors that can be encountered while encoding/decoding JWTs
 pub mod errors;
-pub mod header;
 pub mod jwk;
 pub mod jws;
 #[cfg(feature = "use_pem")]
 mod pem;
 mod serialization;
 mod validation;
+
+#[doc(hidden)]
+pub mod header;
+
+/// Derive macros for custom JWT Header and Claims
+pub mod macros {
+    pub use jsonwebtoken_proc_macros::{Header, claims, header};
+}