use std::fmt;
use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
use serde::{Serialize, de::DeserializeOwned};
use sha2::{Digest as _, Sha256};
use thiserror::Error;
use crate::result::{ClassifyError, ErrorKind};
use crate::secret::{ExposeSecret, SecretString};
use crate::signing::SigningKeys;
pub const MIN_SIGNING_KEY_BYTES: usize = crate::signing::MIN_SIGNING_KEY_BYTES;
pub const DEFAULT_TOKEN_BYTES: usize = 32;
pub const DEFAULT_MAX_SIGNED_TOKEN_BYTES: usize = 8 * 1024;
pub const MAX_NUMERIC_CODE_DIGITS: u32 = 18;
#[must_use]
pub fn constant_time_eq(left: &[u8], right: &[u8]) -> bool {
let mut diff = left.len() ^ right.len();
let max_len = left.len().max(right.len());
for index in 0..max_len {
let left = left.get(index).copied().unwrap_or_default();
let right = right.get(index).copied().unwrap_or_default();
diff |= usize::from(left ^ right);
}
diff == 0
}
pub fn random_bytes(length: usize) -> Result<Vec<u8>, CryptoError> {
if length == 0 {
return Err(CryptoError::InvalidTokenSize);
}
let mut bytes = vec![0_u8; length];
getrandom::fill(&mut bytes).map_err(|_| CryptoError::Random)?;
Ok(bytes)
}
pub fn random_array<const N: usize>() -> Result<[u8; N], CryptoError> {
if N == 0 {
return Err(CryptoError::InvalidTokenSize);
}
let mut bytes = [0_u8; N];
getrandom::fill(&mut bytes).map_err(|_| CryptoError::Random)?;
Ok(bytes)
}
#[must_use]
pub fn sha256_urlsafe(value: impl AsRef<[u8]>) -> String {
URL_SAFE_NO_PAD.encode(Sha256::digest(value.as_ref()))
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct StableKeyHasher;
impl StableKeyHasher {
#[must_use]
pub const fn new() -> Self {
Self
}
#[must_use]
pub fn hash(self, value: impl AsRef<[u8]>) -> String {
sha256_urlsafe(value)
}
#[must_use]
pub fn hash_parts<I, P>(self, parts: I) -> String
where
I: IntoIterator<Item = P>,
P: AsRef<[u8]>,
{
let mut hasher = Sha256::new();
for part in parts {
let part = part.as_ref();
let len = part.len() as u64;
hasher.update(len.to_be_bytes());
hasher.update(part);
}
URL_SAFE_NO_PAD.encode(hasher.finalize())
}
}
pub type TokenHasher = StableKeyHasher;
#[must_use]
pub fn pkce_s256_challenge(verifier: &str) -> String {
sha256_urlsafe(verifier.as_bytes())
}
#[must_use]
pub fn verify_pkce_s256(verifier: &str, expected_challenge: &str) -> bool {
let actual = pkce_s256_challenge(verifier);
constant_time_eq(actual.as_bytes(), expected_challenge.as_bytes())
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub struct TokenGenerator {
token_bytes: usize,
}
impl Default for TokenGenerator {
fn default() -> Self {
Self {
token_bytes: DEFAULT_TOKEN_BYTES,
}
}
}
impl TokenGenerator {
pub const fn new(token_bytes: usize) -> Result<Self, CryptoError> {
if token_bytes == 0 {
return Err(CryptoError::InvalidTokenSize);
}
Ok(Self { token_bytes })
}
#[must_use]
pub const fn token_bytes(&self) -> usize {
self.token_bytes
}
pub fn generate(&self) -> Result<OpaqueToken, CryptoError> {
let bytes = random_bytes(self.token_bytes)?;
Ok(OpaqueToken::new(URL_SAFE_NO_PAD.encode(bytes)))
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub struct NumericCodeGenerator {
digits: u32,
}
impl NumericCodeGenerator {
pub const fn new(digits: u32) -> Result<Self, CryptoError> {
if digits == 0 || digits > MAX_NUMERIC_CODE_DIGITS {
return Err(CryptoError::InvalidNumericCodeDigits {
min_digits: 1,
max_digits: MAX_NUMERIC_CODE_DIGITS,
});
}
Ok(Self { digits })
}
#[must_use]
pub const fn digits(&self) -> u32 {
self.digits
}
pub fn generate(&self) -> Result<String, CryptoError> {
let modulo = 10_u64.pow(self.digits);
let value = random_u64_below(modulo)?;
Ok(format!("{value:0width$}", width = self.digits as usize))
}
}
#[derive(Clone, Eq, PartialEq, Hash)]
#[non_exhaustive]
pub struct OpaqueToken {
value: SecretString,
}
impl OpaqueToken {
#[must_use]
pub fn new(value: impl Into<String>) -> Self {
Self {
value: SecretString::new(value),
}
}
#[must_use]
pub fn expose(&self) -> &str {
self.value.expose_secret()
}
#[must_use]
pub fn into_secret(self) -> String {
self.value.into_secret()
}
}
impl fmt::Debug for OpaqueToken {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
self.value.fmt(formatter)
}
}
impl fmt::Display for OpaqueToken {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
self.value.fmt(formatter)
}
}
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct SignedTokenCodec {
keys: SigningKeys,
max_token_bytes: usize,
}
impl SignedTokenCodec {
pub fn new(active_key: impl AsRef<[u8]>) -> Result<Self, CryptoError> {
Ok(Self {
keys: SigningKeys::new(active_key).map_err(|_| CryptoError::InvalidSigningKey {
min_bytes: MIN_SIGNING_KEY_BYTES,
})?,
max_token_bytes: DEFAULT_MAX_SIGNED_TOKEN_BYTES,
})
}
pub fn with_previous_key(mut self, key: impl AsRef<[u8]>) -> Result<Self, CryptoError> {
self.keys
.add_previous(key)
.map_err(|_| CryptoError::InvalidSigningKey {
min_bytes: MIN_SIGNING_KEY_BYTES,
})?;
Ok(self)
}
pub fn with_previous_keys<I, K>(mut self, keys: I) -> Result<Self, CryptoError>
where
I: IntoIterator<Item = K>,
K: AsRef<[u8]>,
{
for key in keys {
self = self.with_previous_key(key)?;
}
Ok(self)
}
pub fn with_max_token_bytes(mut self, max_token_bytes: usize) -> Result<Self, CryptoError> {
if max_token_bytes == 0 {
return Err(CryptoError::InvalidSignedTokenMaxBytes);
}
self.max_token_bytes = max_token_bytes;
Ok(self)
}
pub fn encode<T>(&self, value: &T) -> Result<String, CryptoError>
where
T: Serialize,
{
let bytes = serde_json::to_vec(value).map_err(|_| CryptoError::Serialization)?;
let payload = URL_SAFE_NO_PAD.encode(bytes);
let signature =
self.keys
.sign(payload.as_bytes())
.map_err(|_| CryptoError::InvalidSigningKey {
min_bytes: MIN_SIGNING_KEY_BYTES,
})?;
let token = format!("v1.{payload}.{signature}");
validate_signed_token_length(&token, self.max_token_bytes)?;
Ok(token)
}
pub fn decode<T>(&self, token: &str) -> Result<T, CryptoError>
where
T: DeserializeOwned,
{
validate_signed_token_length(token, self.max_token_bytes)?;
let (version, rest) = token.split_once('.').ok_or(CryptoError::InvalidToken)?;
if version != "v1" {
return Err(CryptoError::UnsupportedTokenVersion);
}
let (payload, signature) = rest.split_once('.').ok_or(CryptoError::InvalidToken)?;
self.keys
.verify(payload.as_bytes(), signature)
.map_err(|_| CryptoError::InvalidSignature)?;
let bytes = URL_SAFE_NO_PAD
.decode(payload)
.map_err(|_| CryptoError::InvalidToken)?;
serde_json::from_slice(&bytes).map_err(|_| CryptoError::Serialization)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
#[non_exhaustive]
pub enum CryptoError {
#[error("token size must be greater than zero")]
InvalidTokenSize,
#[error("numeric code digits must be between {min_digits} and {max_digits}")]
InvalidNumericCodeDigits {
#[doc = "The minimum number of digits."]
min_digits: u32,
#[doc = "The maximum number of digits."]
max_digits: u32,
},
#[error("random integer upper bound must be greater than zero")]
InvalidRandomBound,
#[error("secure random source failed")]
Random,
#[error("signing key must be at least {min_bytes} bytes")]
InvalidSigningKey {
#[doc = "The minimum number of bytes."]
min_bytes: usize,
},
#[error("signed token is too large")]
TokenTooLarge,
#[error("signed token max bytes must be greater than zero")]
InvalidSignedTokenMaxBytes,
#[error("signed token is invalid")]
InvalidToken,
#[error("signed token version is unsupported")]
UnsupportedTokenVersion,
#[error("signed token signature is invalid")]
InvalidSignature,
#[error("signed token payload serialization failed")]
Serialization,
}
impl ClassifyError for CryptoError {
fn error_kind(&self) -> ErrorKind {
match self {
Self::InvalidTokenSize
| Self::InvalidNumericCodeDigits { .. }
| Self::InvalidRandomBound
| Self::InvalidSigningKey { .. }
| Self::TokenTooLarge
| Self::InvalidSignedTokenMaxBytes
| Self::InvalidToken
| Self::UnsupportedTokenVersion
| Self::InvalidSignature
| Self::Serialization => ErrorKind::Validation,
Self::Random => ErrorKind::Unavailable,
}
}
fn error_code(&self) -> crate::result::ErrorCode {
crate::result::ErrorCode::internal(match self {
Self::InvalidTokenSize => "invalid_token_size",
Self::InvalidNumericCodeDigits { .. } => "invalid_numeric_code_digits",
Self::InvalidRandomBound => "invalid_random_bound",
Self::Random => "secure_random_unavailable",
Self::InvalidSigningKey { .. } => "invalid_signing_key",
Self::TokenTooLarge => "token_too_large",
Self::InvalidSignedTokenMaxBytes => "invalid_signed_token_max_bytes",
Self::InvalidToken => "invalid_token",
Self::UnsupportedTokenVersion => "unsupported_token_version",
Self::InvalidSignature => "invalid_signature",
Self::Serialization => "token_serialization_failed",
})
}
}
fn validate_signed_token_length(token: &str, max_token_bytes: usize) -> Result<(), CryptoError> {
if max_token_bytes == 0 {
return Err(CryptoError::InvalidSignedTokenMaxBytes);
}
if token.len() > max_token_bytes {
return Err(CryptoError::TokenTooLarge);
}
Ok(())
}
fn random_u64_below(upper_bound: u64) -> Result<u64, CryptoError> {
if upper_bound == 0 {
return Err(CryptoError::InvalidRandomBound);
}
let acceptance_zone = u64::MAX - (u64::MAX % upper_bound);
loop {
let candidate = u64::from_be_bytes(random_array::<8>()?);
if candidate < acceptance_zone {
return Ok(candidate % upper_bound);
}
}
}
#[cfg(test)]
mod tests {
use serde_json::json;
use super::*;
const KEY: &[u8] = b"01234567890123456789012345678901";
const OLD_KEY: &[u8] = b"abcdefghijklmnopqrstuvwxyz123456";
#[test]
fn constant_time_compare_requires_same_bytes() {
assert!(constant_time_eq(b"same", b"same"));
assert!(!constant_time_eq(b"same", b"diff"));
assert!(!constant_time_eq(b"same", b"same-but-longer"));
}
#[test]
fn token_generator_returns_redacted_url_safe_token() {
let token = TokenGenerator::new(16)
.expect("valid token size")
.generate()
.expect("token should generate");
assert!(!token.expose().is_empty());
assert_eq!(format!("{token:?}"), "[REDACTED]");
assert_eq!(format!("{token}"), "[REDACTED]");
}
#[test]
fn random_numeric_code_is_zero_padded() {
let code = NumericCodeGenerator::new(8)
.expect("valid digits")
.generate()
.expect("code should generate");
assert_eq!(code.len(), 8);
assert!(code.chars().all(|ch| ch.is_ascii_digit()));
}
#[test]
fn stable_key_hasher_hashes_parts_without_delimiter_ambiguity() {
let hasher = StableKeyHasher::new();
assert_ne!(
hasher.hash_parts([b"ab".as_slice(), b"c".as_slice()]),
hasher.hash_parts([b"a".as_slice(), b"bc".as_slice()])
);
assert!(!hasher.hash(b"token").is_empty());
assert!(!hasher.hash_parts([b"token".as_slice()]).is_empty());
}
#[test]
fn pkce_s256_matches_rfc_vector() {
let verifier = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk";
assert_eq!(
pkce_s256_challenge(verifier),
"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
);
assert!(verify_pkce_s256(
verifier,
"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
));
assert!(!verify_pkce_s256(verifier, "invalid"));
}
#[test]
fn signed_token_preserves_wire_format_and_key_validation() {
let codec = SignedTokenCodec::new(KEY)
.unwrap()
.with_previous_keys([OLD_KEY])
.unwrap();
let expected = "v1.eyJzdWIiOiJ1c3JfMDEifQ.nf4CI4DU1v4TPMbeCCYao9DpuCKrgyEVBH8q8ZUYSy0";
assert_eq!(codec.encode(&json!({"sub": "usr_01"})).unwrap(), expected);
assert_eq!(
codec.decode::<serde_json::Value>(expected).unwrap(),
json!({"sub": "usr_01"})
);
for signature in ["", "!", "AA", "A".repeat(43).as_str()] {
assert_eq!(
codec
.decode::<serde_json::Value>(&format!("v1.eyJzdWIiOiJ1c3JfMDEifQ.{signature}")),
Err(CryptoError::InvalidSignature)
);
}
assert!(SignedTokenCodec::new(b"short").is_err());
assert!(codec.clone().with_previous_key(b"short").is_err());
let debug = format!("{codec:?}");
for key in [KEY, OLD_KEY] {
assert!(!debug.contains(std::str::from_utf8(key).unwrap()));
}
assert!(debug.contains("redacted"));
}
#[test]
fn signed_token_round_trips_json_payload() {
let codec = SignedTokenCodec::new(KEY).expect("valid key");
let token = codec
.encode(&json!({ "sub": "usr_01" }))
.expect("token should encode");
let decoded: serde_json::Value = codec.decode(&token).expect("token should decode");
assert_eq!(decoded["sub"], "usr_01");
}
#[test]
fn signed_token_accepts_previous_key_for_rotation() {
let old_codec = SignedTokenCodec::new(OLD_KEY).expect("valid key");
let token = old_codec
.encode(&json!({ "sub": "usr_01" }))
.expect("token should encode");
let rotated = SignedTokenCodec::new(KEY)
.expect("valid key")
.with_previous_key(OLD_KEY)
.expect("valid previous key");
let decoded: serde_json::Value = rotated.decode(&token).expect("token should decode");
assert_eq!(decoded["sub"], "usr_01");
}
#[test]
fn signed_token_rejects_tampering() {
let codec = SignedTokenCodec::new(KEY).expect("valid key");
let token = codec
.encode(&json!({ "sub": "usr_01" }))
.expect("token should encode");
let mut tampered = token.clone();
let last = tampered.pop().expect("token should not be empty");
tampered.push(if last == 'A' { 'B' } else { 'A' });
assert_eq!(
codec.decode::<serde_json::Value>(&tampered).unwrap_err(),
CryptoError::InvalidSignature
);
}
#[test]
fn signed_token_rejects_invalid_size_limits() {
assert_eq!(
SignedTokenCodec::new(KEY)
.expect("valid key")
.with_max_token_bytes(0)
.expect_err("zero max token bytes should fail"),
CryptoError::InvalidSignedTokenMaxBytes
);
let codec = SignedTokenCodec::new(KEY)
.expect("valid key")
.with_max_token_bytes(8)
.expect("limit should be valid");
assert_eq!(
codec.encode(&json!({ "sub": "usr_01" })).unwrap_err(),
CryptoError::TokenTooLarge
);
}
}