jwt_compact_frame/

token.rs

//! `Token` and closely related types.

use base64ct::{Base64UrlUnpadded, Encoding};
use bounded_collections::{BoundedVec, ConstU32};
use parity_scale_codec::{Decode, Encode, MaxEncodedLen};
use scale_info::TypeInfo;
use serde::{
	de::{DeserializeOwned, Error as DeError, Visitor},
	Deserialize, Deserializer, Serialize, Serializer,
};

use core::{cmp, fmt};

#[cfg(feature = "ciborium")]
use crate::error::CborDeError;
use crate::{
	alloc::{format, Cow, String, Vec},
	Algorithm, Claims, Empty, ParseError, ValidationError,
};

/// Maximum "reasonable" signature size in bytes.
const SIGNATURE_SIZE: u32 = 256;

/// Representation of a X.509 certificate thumbprint (`x5t` and `x5t#S256` fields in
/// the JWT [`Header`]).
///
/// As per the JWS spec in [RFC 7515], a certificate thumbprint (i.e., the SHA-1 / SHA-256
/// digest of the certificate) must be base64url-encoded. Some JWS implementations however
/// encode not the thumbprint itself, but rather its hex encoding, sometimes even
/// with additional chars spliced within. To account for these implementations,
/// a thumbprint is represented as an enum – either a properly encoded hash digest,
/// or an opaque base64-encoded string.
///
/// [RFC 7515]: https://www.rfc-editor.org/rfc/rfc7515.html
///
/// # Examples
///
/// ```
/// # use assert_matches::assert_matches;
/// # use jwt_compact_frame::{
/// #     alg::{Hs256, Hs256Key}, AlgorithmExt, Claims, Header, Thumbprint, UntrustedToken,
/// # };
/// # fn main() -> anyhow::Result<()> {
/// let key = Hs256Key::new(b"super_secret_key_donut_steel");
///
/// // Creates a token with a custom-encoded SHA-1 thumbprint.
/// let thumbprint = "65:AF:69:09:B1:B0:75:8E:06:C6:E0:48:C4:60:02:B5:C6:95:E3:6B";
/// let header = Header::empty()
///     .with_key_id("my_key")
///     .with_certificate_sha1_thumbprint(thumbprint);
/// let token = Hs256.token(&header, &Claims::empty(), &key)?;
/// println!("{token}");
///
/// // Deserialize the token and check that its header fields are readable.
/// let token = UntrustedToken::new(&token)?;
/// let deserialized_thumbprint =
///     token.header().certificate_sha1_thumbprint.as_ref();
/// assert_matches!(
///     deserialized_thumbprint,
///     Some(Thumbprint::String(s)) if s == thumbprint
/// );
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash, Decode, Encode, TypeInfo)]
#[non_exhaustive]
pub enum Thumbprint<const N: usize> {
	/// Byte representation of a SHA-1 or SHA-256 digest.
	Bytes([u8; N]),
	/// Opaque string representation of the thumbprint. It is the responsibility
	/// of an application to verify that this value is valid.
	String(String),
}

impl<const N: usize> From<[u8; N]> for Thumbprint<N> {
	fn from(value: [u8; N]) -> Self {
		Self::Bytes(value)
	}
}

impl<const N: usize> From<String> for Thumbprint<N> {
	fn from(s: String) -> Self {
		Self::String(s)
	}
}

impl<const N: usize> From<&str> for Thumbprint<N> {
	fn from(s: &str) -> Self {
		Self::String(s.into())
	}
}

impl<const N: usize> Serialize for Thumbprint<N> {
	fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
		let input = match self {
			Self::Bytes(bytes) => bytes.as_slice(),
			Self::String(s) => s.as_bytes(),
		};
		serializer.serialize_str(&Base64UrlUnpadded::encode_string(input))
	}
}

impl<'de, const N: usize> Deserialize<'de> for Thumbprint<N> {
	fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
		struct Base64Visitor<const L: usize>;

		impl<const L: usize> Visitor<'_> for Base64Visitor<L> {
			type Value = Thumbprint<L>;

			fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
				write!(formatter, "base64url-encoded thumbprint")
			}

			fn visit_str<E: DeError>(self, mut value: &str) -> Result<Self::Value, E> {
				// Allow for padding. RFC 7515 defines base64url encoding as one without padding:
				//
				// > Base64url Encoding: Base64 encoding using the URL- and filename-safe
				// > character set defined in Section 5 of RFC 4648 [RFC4648], with all trailing '='
				// > characters omitted [...]
				//
				// ...but it's easy to trim the padding, so we support it anyway.
				//
				// See: https://www.rfc-editor.org/rfc/rfc7515.html#section-2
				for _ in 0..2 {
					if value.as_bytes().last() == Some(&b'=') {
						value = &value[..value.len() - 1];
					}
				}

				let decoded_len = value.len() * 3 / 4;
				match decoded_len.cmp(&L) {
					cmp::Ordering::Less => Err(E::custom(format!("thumbprint must contain at least {L} bytes"))),
					cmp::Ordering::Equal => {
						let mut bytes = [0_u8; L];
						let len = Base64UrlUnpadded::decode(value, &mut bytes).map_err(E::custom)?.len();
						debug_assert_eq!(len, L);
						Ok(bytes.into())
					},
					cmp::Ordering::Greater => {
						let decoded = Base64UrlUnpadded::decode_vec(value).map_err(E::custom)?;
						let decoded = String::from_utf8(decoded).map_err(|err| E::custom(err.utf8_error()))?;
						Ok(decoded.into())
					},
				}
			}
		}

		deserializer.deserialize_str(Base64Visitor)
	}
}

/// JWT header.
///
/// See [RFC 7515](https://tools.ietf.org/html/rfc7515#section-4.1) for the description
/// of the fields. The purpose of all fields except `token_type` is to determine
/// the verifying key. Since these values will be provided by the adversary in the case of
/// an attack, they require additional verification (e.g., a provided certificate might
/// be checked against the list of "acceptable" certificate authorities).
///
/// A `Header` can be created using `Default` implementation, which does not set any fields.
/// For added fluency, you may use `with_*` methods:
///
/// ```
/// # use jwt_compact_frame::Header;
/// use sha2::{digest::Digest, Sha256};
///
/// let my_key_cert = // DER-encoded key certificate
/// #   b"Hello, world!";
/// let thumbprint: [u8; 32] = Sha256::digest(my_key_cert).into();
/// let header = Header::empty()
///     .with_key_id("my-key-id")
///     .with_certificate_thumbprint(thumbprint);
/// ```
#[derive(Debug, Clone, Default, Serialize, Deserialize, Decode, Encode, TypeInfo, Eq, PartialEq)]
#[non_exhaustive]
pub struct Header<T = Empty> {
	/// URL of the JSON Web Key Set containing the key that has signed the token.
	/// This field is renamed to [`jku`] for serialization.
	///
	/// [`jku`]: https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.2
	#[serde(rename = "jku", default, skip_serializing_if = "Option::is_none")]
	pub key_set_url: Option<String>,

	/// Identifier of the key that has signed the token. This field is renamed to [`kid`]
	/// for serialization.
	///
	/// [`kid`]: https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.4
	#[serde(rename = "kid", default, skip_serializing_if = "Option::is_none")]
	pub key_id: Option<String>,

	/// URL of the X.509 certificate for the signing key. This field is renamed to [`x5u`]
	/// for serialization.
	///
	/// [`x5u`]: https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.5
	#[serde(rename = "x5u", default, skip_serializing_if = "Option::is_none")]
	pub certificate_url: Option<String>,

	/// SHA-1 thumbprint of the X.509 certificate for the signing key.
	/// This field is renamed to [`x5t`] for serialization.
	///
	/// [`x5t`]: https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.7
	#[serde(rename = "x5t", default, skip_serializing_if = "Option::is_none")]
	pub certificate_sha1_thumbprint: Option<Thumbprint<20>>,

	/// SHA-256 thumbprint of the X.509 certificate for the signing key.
	/// This field is renamed to [`x5t#S256`] for serialization.
	///
	/// [`x5t#S256`]: https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.8
	#[serde(rename = "x5t#S256", default, skip_serializing_if = "Option::is_none")]
	pub certificate_thumbprint: Option<Thumbprint<32>>,

	/// Application-specific [token type]. This field is renamed to `typ` for serialization.
	///
	/// [token type]: https://tools.ietf.org/html/rfc7519#section-5.1
	#[serde(rename = "typ", default, skip_serializing_if = "Option::is_none")]
	pub token_type: Option<String>,

	/// Other fields encoded in the header. These fields may be used by agreement between
	/// the producer and consumer of the token to pass additional information.
	/// See Sections 4.2 and 4.3 of [RFC 7515](https://www.rfc-editor.org/rfc/rfc7515#section-4.2)
	/// for details.
	///
	/// For the token creation and validation to work properly, the fields type must [`Serialize`]
	/// to a JSON object.
	///
	/// Note that these fields do not include the signing algorithm (`alg`) and the token
	/// content type (`cty`) since both these fields have predefined semantics and are used
	/// internally by the crate logic.
	#[serde(flatten)]
	pub other_fields: T,
}

impl Header {
	/// Creates an empty header.
	pub const fn empty() -> Self {
		Self {
			key_set_url: None,
			key_id: None,
			certificate_url: None,
			certificate_sha1_thumbprint: None,
			certificate_thumbprint: None,
			token_type: None,
			other_fields: Empty {},
		}
	}
}

impl<T> Header<T> {
	/// Creates a header with the specified custom fields.
	pub const fn new(fields: T) -> Self {
		Self {
			key_set_url: None,
			key_id: None,
			certificate_url: None,
			certificate_sha1_thumbprint: None,
			certificate_thumbprint: None,
			token_type: None,
			other_fields: fields,
		}
	}

	/// Sets the `key_set_url` field for this header.
	#[must_use]
	pub fn with_key_set_url(mut self, key_set_url: impl Into<String>) -> Self {
		self.key_set_url = Some(key_set_url.into());
		self
	}

	/// Sets the `key_id` field for this header.
	#[must_use]
	pub fn with_key_id(mut self, key_id: impl Into<String>) -> Self {
		self.key_id = Some(key_id.into());
		self
	}

	/// Sets the `certificate_url` field for this header.
	#[must_use]
	pub fn with_certificate_url(mut self, certificate_url: impl Into<String>) -> Self {
		self.certificate_url = Some(certificate_url.into());
		self
	}

	/// Sets the `certificate_sha1_thumbprint` field for this header.
	#[must_use]
	pub fn with_certificate_sha1_thumbprint(mut self, certificate_thumbprint: impl Into<Thumbprint<20>>) -> Self {
		self.certificate_sha1_thumbprint = Some(certificate_thumbprint.into());
		self
	}

	/// Sets the `certificate_thumbprint` field for this header.
	#[must_use]
	pub fn with_certificate_thumbprint(mut self, certificate_thumbprint: impl Into<Thumbprint<32>>) -> Self {
		self.certificate_thumbprint = Some(certificate_thumbprint.into());
		self
	}

	/// Sets the `token_type` field for this header.
	#[must_use]
	pub fn with_token_type(mut self, token_type: impl Into<String>) -> Self {
		self.token_type = Some(token_type.into());
		self
	}
}

#[derive(Debug, Clone, Serialize, Deserialize, Decode, Encode, TypeInfo, Eq, PartialEq)]
pub struct CompleteHeader<'a, T> {
	#[serde(rename = "alg")]
	pub algorithm: Cow<'a, str>,
	#[serde(rename = "cty", default, skip_serializing_if = "Option::is_none")]
	pub content_type: Option<String>,
	#[serde(flatten)]
	pub inner: T,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Decode, Encode, TypeInfo, MaxEncodedLen, Serialize, Deserialize)]
enum ContentType {
	Json,
	#[cfg(feature = "ciborium")]
	Cbor,
}

/// Parsed, but unvalidated token.
///
/// The type param ([`Empty`] by default) corresponds to the [additional information] enclosed
/// in the token [`Header`].
///
/// An `UntrustedToken` can be parsed from a string using the [`TryFrom`] implementation.
/// This checks that a token is well-formed (has a header, claims and a signature),
/// but does not validate the signature.
/// As a shortcut, a token without additional header info can be created using [`Self::new()`].
///
/// [additional information]: Header#other_fields
///
/// # Examples
///
/// ```
/// # use jwt_compact_frame::UntrustedToken;
/// let token_str = "eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJp\
///     c3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leG\
///     FtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJ\
///     U1p1r_wW1gFWFOEjXk";
/// let token: UntrustedToken = token_str.try_into()?;
/// // The same operation using a shortcut:
/// let same_token = UntrustedToken::new(token_str)?;
/// // Token header can be accessed to select the verifying key etc.
/// let key_id: Option<&str> = token.header().key_id.as_deref();
/// # Ok::<_, anyhow::Error>(())
/// ```
///
/// ## Handling tokens with custom header fields
///
/// ```
/// # use serde::Deserialize;
/// # use jwt_compact_frame::UntrustedToken;
/// #[derive(Debug, Clone, Deserialize)]
/// struct HeaderExtensions {
///     custom: String,
/// }
///
/// let token_str = "eyJhbGciOiJIUzI1NiIsImtpZCI6InRlc3Rfa2V5Iiwid\
///     HlwIjoiSldUIiwiY3VzdG9tIjoiY3VzdG9tIn0.eyJzdWIiOiIxMjM0NTY\
///     3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9._27Fb6nF\
///     Tg-HSt3vO4ylaLGcU_ZV2VhMJR4HL7KaQik";
/// let token: UntrustedToken<HeaderExtensions> = token_str.try_into()?;
/// let extensions = &token.header().other_fields;
/// println!("{}", extensions.custom);
/// # Ok::<_, anyhow::Error>(())
/// ```
#[derive(Debug, Clone, Decode, Encode, TypeInfo, Eq, PartialEq, MaxEncodedLen, Serialize, Deserialize)]
pub struct UntrustedToken<H = Empty> {
	// TODO: Find a reasonable upper bound for the signed data size.
	pub(crate) signed_data: BoundedVec<u8, ConstU32<2048>>,
	header: Header<H>,
	// The algorithm is a very short string.
	algorithm: BoundedVec<u8, ConstU32<8>>,
	content_type: ContentType,
	// TODO: Find a reasonable upper bound for the claims size.
	serialized_claims: BoundedVec<u8, ConstU32<2048>>,
	signature: BoundedVec<u8, ConstU32<SIGNATURE_SIZE>>,
}

/// Token with validated integrity.
///
/// Claims encoded in the token can be verified by invoking [`Claims`] methods
/// via [`Self::claims()`].
#[derive(Debug, Clone, Serialize, Deserialize, Decode, Encode, TypeInfo, Eq, PartialEq)]
pub struct Token<T, H = Empty> {
	header: Header<H>,
	claims: Claims<T>,
}

impl<T, H> Token<T, H> {
	pub(crate) const fn new(header: Header<H>, claims: Claims<T>) -> Self {
		Self { header, claims }
	}

	/// Gets token header.
	pub const fn header(&self) -> &Header<H> {
		&self.header
	}

	/// Gets token claims.
	pub const fn claims(&self) -> &Claims<T> {
		&self.claims
	}

	/// Splits the `Token` into the respective `Header` and `Claims` while consuming it.
	pub fn into_parts(self) -> (Header<H>, Claims<T>) {
		(self.header, self.claims)
	}
}

/// `Token` together with the validated token signature.
///
/// # Examples
///
/// ```
/// # use jwt_compact_frame::{alg::{Hs256, Hs256Key, Hs256Signature}, prelude::*};
/// # use chrono::Duration;
/// # use serde::{Deserialize, Serialize};
/// #
/// #[derive(Serialize, Deserialize)]
/// struct MyClaims {
///     // Custom claims in the token...
/// }
///
/// # fn main() -> anyhow::Result<()> {
/// # let key = Hs256Key::new(b"super_secret_key");
/// # let claims = Claims::new(MyClaims {})
/// #     .set_duration_and_issuance(&TimeOptions::default(), Duration::days(7));
/// let token_string: String = // token from an external source
/// #   Hs256.token(&Header::empty(), &claims, &key)?;
/// let token = UntrustedToken::new(&token_string)?;
/// let signed = Hs256.validator::<MyClaims>(&key)
///     .validate_for_signed_token(&token)?;
///
/// // `signature` is strongly typed.
/// let signature: Hs256Signature = signed.signature;
/// // Token itself is available via `token` field.
/// let claims = signed.token.claims();
/// claims.validate_expiration(&TimeOptions::default())?;
/// // Process the claims...
/// # Ok(())
/// # } // end main()
/// ```
#[non_exhaustive]
#[derive(Encode, Decode, MaxEncodedLen, Serialize, Deserialize)]
pub struct SignedToken<A: Algorithm + ?Sized, T, H = Empty> {
	/// Token signature.
	pub signature: A::Signature,
	/// Verified token.
	pub token: Token<T, H>,
}

impl<A, T, H> fmt::Debug for SignedToken<A, T, H>
where
	A: Algorithm,
	A::Signature: fmt::Debug,
	T: fmt::Debug,
	H: fmt::Debug,
{
	fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
		formatter.debug_struct("SignedToken").field("token", &self.token).field("signature", &self.signature).finish()
	}
}

impl<A, T, H> Clone for SignedToken<A, T, H>
where
	A: Algorithm,
	A::Signature: Clone,
	T: Clone,
	H: Clone,
{
	fn clone(&self) -> Self {
		Self { signature: self.signature.clone(), token: self.token.clone() }
	}
}

impl<'a, H: DeserializeOwned> TryFrom<&'a str> for UntrustedToken<H> {
	type Error = ParseError;

	fn try_from(s: &'a str) -> Result<Self, Self::Error> {
		let token_parts: Vec<_> = s.splitn(4, '.').collect();
		match &token_parts[..] {
			[header, claims, signature] => {
				let header = Base64UrlUnpadded::decode_vec(header).map_err(|_| ParseError::InvalidBase64Encoding)?;
				let serialized_claims = Base64UrlUnpadded::decode_vec(claims)
					.map_err(|_| ParseError::InvalidBase64Encoding)
					.and_then(|claims| BoundedVec::try_from(claims).map_err(|_| ParseError::ClaimsTooLarge))?;

				// Decode into a temporary Vec<u8>
				let signature_len =
					Base64UrlUnpadded::decode_vec(signature).map_err(|_| ParseError::InvalidBase64Encoding)?;

				// Convert the Vec<u8> into a BoundedVec<u8>
				let bounded_decoded_signature =
					BoundedVec::try_from(signature_len).map_err(|_| ParseError::SignatureTooLarge)?;

				let header: CompleteHeader<_> = serde_json::from_slice(&header).map_err(ParseError::MalformedHeader)?;
				let content_type = match header.content_type {
					None => ContentType::Json,
					Some(s) if s.eq_ignore_ascii_case("json") => ContentType::Json,
					#[cfg(feature = "ciborium")]
					Some(s) if s.eq_ignore_ascii_case("cbor") => ContentType::Cbor,
					Some(s) => return Err(ParseError::UnsupportedContentType(s)),
				};
				let signed_data = s.rsplit_once('.').unwrap().0.as_bytes();
				let bounded_signed_data =
					BoundedVec::try_from(signed_data.to_vec()).map_err(|_| ParseError::SignedDataTooLarge)?;
				let bounded_header_algorithm = BoundedVec::try_from(header.algorithm.as_bytes().to_vec())
					.map_err(|_| ParseError::SignedDataTooLarge)?;
				Ok(Self {
					signed_data: bounded_signed_data,
					header: header.inner,
					algorithm: bounded_header_algorithm,
					content_type,
					serialized_claims,
					signature: bounded_decoded_signature,
				})
			},
			_ => Err(ParseError::InvalidTokenStructure),
		}
	}
}

impl<'a> UntrustedToken {
	/// Creates an untrusted token from a string. This is a shortcut for calling the [`TryFrom`]
	/// conversion.
	pub fn new<S: AsRef<str> + ?Sized>(s: &'a S) -> Result<Self, ParseError> {
		Self::try_from(s.as_ref())
	}
}

impl<H> UntrustedToken<H> {
	/// Converts this token to an owned form.
	pub fn into_owned(self) -> Self {
		Self {
			signed_data: self.signed_data,
			header: self.header,
			algorithm: self.algorithm,
			content_type: self.content_type,
			serialized_claims: self.serialized_claims,
			signature: self.signature,
		}
	}

	/// Gets the token header.
	pub const fn header(&self) -> &Header<H> {
		&self.header
	}

	/// Gets the integrity algorithm used to secure the token.
	pub fn algorithm(&self) -> &str {
		core::str::from_utf8(&self.algorithm).expect("algorithm is always valid UTF-8")
	}

	/// Returns signature bytes from the token. These bytes are **not** guaranteed to form a valid
	/// signature.
	pub fn signature_bytes(&self) -> &[u8] {
		&self.signature
	}

	/// Deserializes claims from this token without checking token integrity. The resulting
	/// claims are thus **not** guaranteed to be valid.
	pub fn deserialize_claims_unchecked<T>(&self) -> Result<Claims<T>, ValidationError>
	where
		T: DeserializeOwned,
	{
		match self.content_type {
			ContentType::Json => {
				serde_json::from_slice(&self.serialized_claims).map_err(ValidationError::MalformedClaims)
			},

			#[cfg(feature = "ciborium")]
			ContentType::Cbor => {
				ciborium::from_reader(&self.serialized_claims[..]).map_err(|err| {
					ValidationError::MalformedCborClaims(match err {
						CborDeError::Io(err) => CborDeError::Io(anyhow::anyhow!(err)),
						// ^ In order to be able to use `anyhow!` in both std and no-std envs,
						// we inline the error transform directly here.
						CborDeError::Syntax(offset) => CborDeError::Syntax(offset),
						CborDeError::Semantic(offset, description) => CborDeError::Semantic(offset, description),
						CborDeError::RecursionLimitExceeded => CborDeError::RecursionLimitExceeded,
					})
				})
			},
		}
	}
}

#[cfg(test)]
mod tests {
	use assert_matches::assert_matches;
	use base64ct::{Base64UrlUnpadded, Encoding};

	use super::*;
	use crate::{
		alg::{Hs256, Hs256Key},
		alloc::{ToOwned, ToString},
		AlgorithmExt, Empty,
	};

	type Obj = serde_json::Map<String, serde_json::Value>;

	const HS256_TOKEN: &str = "eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.\
                               eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt\
                               cGxlLmNvbS9pc19yb290Ijp0cnVlfQ.\
                               dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk";
	const HS256_KEY: &str = "AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75\
                             aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow";

	#[test]
	fn invalid_token_structure() {
		let mangled_str = HS256_TOKEN.replace('.', "");
		assert_matches!(UntrustedToken::new(&mangled_str).unwrap_err(), ParseError::InvalidTokenStructure);

		let mut mangled_str = HS256_TOKEN.to_owned();
		let signature_start = mangled_str.rfind('.').unwrap();
		mangled_str.truncate(signature_start);
		assert_matches!(UntrustedToken::new(&mangled_str).unwrap_err(), ParseError::InvalidTokenStructure);

		let mut mangled_str = HS256_TOKEN.to_owned();
		mangled_str.push('.');
		assert_matches!(UntrustedToken::new(&mangled_str).unwrap_err(), ParseError::InvalidTokenStructure);
	}

	#[test]
	fn base64_error_during_parsing() {
		let mangled_str = HS256_TOKEN.replace('0', "+");
		assert_matches!(UntrustedToken::new(&mangled_str).unwrap_err(), ParseError::InvalidBase64Encoding);
	}

	#[test]
	fn base64_padding_error_during_parsing() {
		let mut mangled_str = HS256_TOKEN.to_owned();
		mangled_str.pop();
		mangled_str.push('_'); // leads to non-zero padding for the last encoded byte
		assert_matches!(UntrustedToken::new(&mangled_str).unwrap_err(), ParseError::InvalidBase64Encoding);
	}

	#[test]
	fn header_fields_are_not_serialized_if_not_present() {
		let header = Header::empty();
		let json = serde_json::to_string(&header).unwrap();
		assert_eq!(json, "{}");
	}

	#[test]
	fn header_with_x5t_field() {
		let header = r#"{"alg":"HS256","x5t":"lDpwLQbzRZmu4fjajvn3KWAx1pk"}"#;
		let header: CompleteHeader<Header<Empty>> = serde_json::from_str(header).unwrap();
		let thumbprint = header.inner.certificate_sha1_thumbprint.as_ref().unwrap();
		let Thumbprint::Bytes(thumbprint) = thumbprint else {
			unreachable!();
		};

		assert_eq!(thumbprint[0], 0x94);
		assert_eq!(thumbprint[19], 0x99);

		let json = serde_json::to_value(header).unwrap();
		assert_eq!(
			json,
			serde_json::json!({
				"alg": "HS256",
				"x5t": "lDpwLQbzRZmu4fjajvn3KWAx1pk",
			})
		);
	}

	#[test]
	fn header_with_padded_x5t_field() {
		let header = r#"{"alg":"HS256","x5t":"lDpwLQbzRZmu4fjajvn3KWAx1pk=="}"#;
		let header: CompleteHeader<Header<Empty>> = serde_json::from_str(header).unwrap();
		let thumbprint = header.inner.certificate_sha1_thumbprint.as_ref().unwrap();
		let Thumbprint::Bytes(thumbprint) = thumbprint else { unreachable!() };

		assert_eq!(thumbprint[0], 0x94);
		assert_eq!(thumbprint[19], 0x99);
	}

	#[test]
	fn header_with_hex_x5t_field() {
		let header = r#"{"alg":"HS256","x5t":"NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDAyQjVDNjk1RTM2Qg"}"#;
		let header: CompleteHeader<Header<Empty>> = serde_json::from_str(header).unwrap();
		let thumbprint = header.inner.certificate_sha1_thumbprint.as_ref().unwrap();
		let Thumbprint::String(thumbprint) = thumbprint else { unreachable!() };

		assert_eq!(thumbprint, "65AF6909B1B0758E06C6E048C46002B5C695E36B");

		let json = serde_json::to_value(header).unwrap();
		assert_eq!(
			json,
			serde_json::json!({
				"alg": "HS256",
				"x5t": "NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDAyQjVDNjk1RTM2Qg",
			})
		);
	}

	#[test]
	fn header_with_padded_hex_x5t_field() {
		let header = r#"{"alg":"HS256","x5t":"NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDAyQjVDNjk1RTM2Qg=="}"#;
		let header: CompleteHeader<Header<Empty>> = serde_json::from_str(header).unwrap();
		let thumbprint = header.inner.certificate_sha1_thumbprint.as_ref().unwrap();
		let Thumbprint::String(thumbprint) = thumbprint else { unreachable!() };

		assert_eq!(thumbprint, "65AF6909B1B0758E06C6E048C46002B5C695E36B");
	}

	#[test]
	fn header_with_overly_short_x5t_field() {
		let header = r#"{"alg":"HS256","x5t":"aGk="}"#;
		let err = serde_json::from_str::<CompleteHeader<Header<Empty>>>(header).unwrap_err();
		let err = err.to_string();
		assert!(err.contains("thumbprint must contain at least 20 bytes"), "{err}");
	}

	#[test]
	fn header_with_non_base64_x5t_field() {
		let headers = [
			r#"{"alg":"HS256","x5t":"lDpwLQbzRZmu4fjajvn3KWAx1p?"}"#,
			r#"{"alg":"HS256","x5t":"NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDAyQjVDNjk!RTM2Qg"}"#,
		];
		for header in headers {
			let err = serde_json::from_str::<CompleteHeader<Header<Empty>>>(header).unwrap_err();
			let err = err.to_string();
			assert!(err.contains("Base64"), "{err}");
		}
	}

	#[test]
	fn header_with_x5t_sha256_field() {
		let header = r#"{"alg":"HS256","x5t#S256":"MV9b23bQeMQ7isAGTkoBZGErH853yGk0W_yUx1iU7dM"}"#;
		let header: CompleteHeader<Header<Empty>> = serde_json::from_str(header).unwrap();
		let thumbprint = header.inner.certificate_thumbprint.as_ref().unwrap();
		let Thumbprint::Bytes(thumbprint) = thumbprint else { unreachable!() };

		assert_eq!(thumbprint[0], 0x31);
		assert_eq!(thumbprint[31], 0xd3);

		let json = serde_json::to_value(header).unwrap();
		assert_eq!(
			json,
			serde_json::json!({
				"alg": "HS256",
				"x5t#S256": "MV9b23bQeMQ7isAGTkoBZGErH853yGk0W_yUx1iU7dM",
			})
		);
	}

	#[test]
	fn malformed_header() {
		let mangled_headers = [
			// Missing closing brace
			r#"{"alg":"HS256""#,
			// Missing necessary `alg` field
			"{}",
			// `alg` field is not a string
			r#"{"alg":5}"#,
			r#"{"alg":[1,"foo"]}"#,
			r#"{"alg":false}"#,
			// Duplicate `alg` field
			r#"{"alg":"HS256","alg":"none"}"#,
			// Invalid thumbprint fields
			r#"{"alg":"HS256","x5t":"lDpwLQbzRZmu4fjajvn3KWAx1p"}"#,
			r#"{"alg":"HS256","x5t":["lDpwLQbzRZmu4fjajvn3KWAx1pk"]}"#,
			r#"{"alg":"HS256","x5t":"lDpwLQbzRZmu4fjajvn3KWAx1 k"}"#,
			r#"{"alg":"HS256","x5t":"lDpwLQbzRZmu4fjajvn3KWAx1pk==="}"#,
			r#"{"alg":"HS256","x5t":"lDpwLQbzRZmu4fjajvn3KWAx1pkk"}"#,
			r#"{"alg":"HS256","x5t":"MV9b23bQeMQ7isAGTkoBZGErH853yGk0W_yUx1iU7dM"}"#,
			r#"{"alg":"HS256","x5t#S256":"lDpwLQbzRZmu4fjajvn3KWAx1pk"}"#,
		];

		for mangled_header in &mangled_headers {
			let mangled_header = Base64UrlUnpadded::encode_string(mangled_header.as_bytes());
			let mut mangled_str = HS256_TOKEN.to_owned();
			mangled_str.replace_range(..mangled_str.find('.').unwrap(), &mangled_header);
			assert_matches!(UntrustedToken::new(&mangled_str).unwrap_err(), ParseError::MalformedHeader(_));
		}
	}

	#[test]
	fn unsupported_content_type() {
		let mangled_header = br#"{"alg":"HS256","cty":"txt"}"#;
		let mangled_header = Base64UrlUnpadded::encode_string(mangled_header);
		let mut mangled_str = HS256_TOKEN.to_owned();
		mangled_str.replace_range(..mangled_str.find('.').unwrap(), &mangled_header);
		assert_matches!(
			UntrustedToken::new(&mangled_str).unwrap_err(),
			ParseError::UnsupportedContentType(s) if s == "txt"
		);
	}

	#[test]
	fn extracting_custom_header_fields() {
		let header = r#"{"alg":"HS256","custom":[1,"field"],"x5t":"lDpwLQbzRZmu4fjajvn3KWAx1pk"}"#;
		let header: CompleteHeader<Header<Obj>> = serde_json::from_str(header).unwrap();
		assert_eq!(header.algorithm, "HS256");
		assert!(header.inner.certificate_sha1_thumbprint.is_some());
		assert_eq!(header.inner.other_fields.len(), 1);
		assert!(header.inner.other_fields["custom"].is_array());
	}

	#[test]
	fn malformed_json_claims() {
		let malformed_claims = [
			// Missing closing brace
			r#"{"exp":1500000000"#,
			// `exp` claim is not a number
			r#"{"exp":"1500000000"}"#,
			r#"{"exp":false}"#,
			// Duplicate `exp` claim
			r#"{"exp":1500000000,"nbf":1400000000,"exp":1510000000}"#,
			// Too large `exp` value
			r#"{"exp":1500000000000000000000000000000000}"#,
		];

		let claims_start = HS256_TOKEN.find('.').unwrap() + 1;
		let claims_end = HS256_TOKEN.rfind('.').unwrap();
		let key = Base64UrlUnpadded::decode_vec(HS256_KEY).unwrap();
		let key = Hs256Key::new(key);

		for claims in &malformed_claims {
			let encoded_claims = Base64UrlUnpadded::encode_string(claims.as_bytes());
			let mut mangled_str = HS256_TOKEN.to_owned();
			mangled_str.replace_range(claims_start..claims_end, &encoded_claims);
			let token = UntrustedToken::new(&mangled_str).unwrap();
			assert_matches!(
				Hs256.validator::<Obj>(&key).validate(&token).unwrap_err(),
				ValidationError::MalformedClaims(_),
				"Failing claims: {claims}"
			);
		}
	}

	fn test_invalid_signature_len(mangled_str: &str, actual_len: usize) {
		let token = UntrustedToken::new(&mangled_str).unwrap();
		let key = Base64UrlUnpadded::decode_vec(HS256_KEY).unwrap();
		let key = Hs256Key::new(key);

		let err = Hs256.validator::<Empty>(&key).validate(&token).unwrap_err();
		assert_matches!(
			err,
			ValidationError::InvalidSignatureLen { actual, expected: 32 }
				if actual == actual_len
		);
	}

	#[test]
	fn short_signature_error() {
		test_invalid_signature_len(&HS256_TOKEN[..HS256_TOKEN.len() - 3], 30);
	}

	#[test]
	fn long_signature_error() {
		let mut mangled_string = HS256_TOKEN.to_owned();
		mangled_string.push('a');
		test_invalid_signature_len(&mangled_string, 33);
	}
}