use core::fmt;
use core::str::FromStr;
use oxicode::de::{Decode, Decoder};
use oxicode::enc::{Encode, Encoder};
use oxicrypto::{Zeroize, ct_eq};
use serde::de::Error as _;
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use crate::error::{AuthTokenError, codec_invalid};
pub const AUTH_TOKEN_LEN: usize = 32;
pub const AUTH_TOKEN_HEX_LEN: usize = AUTH_TOKEN_LEN * 2;
pub const REDACTED: &str = "<redacted>";
const HEX_DIGITS: [u8; 16] = *b"0123456789abcdef";
#[derive(Clone)]
pub struct AuthToken {
bytes: [u8; AUTH_TOKEN_LEN],
}
impl AuthToken {
pub const ZERO: Self = Self {
bytes: [0u8; AUTH_TOKEN_LEN],
};
#[must_use]
pub const fn from_bytes(bytes: [u8; AUTH_TOKEN_LEN]) -> Self {
Self { bytes }
}
pub fn generate() -> Result<Self, AuthTokenError> {
let random = oxicrypto::random_bytes(AUTH_TOKEN_LEN).map_err(|err| {
AuthTokenError::RandomnessUnavailable {
reason: err.to_string(),
}
})?;
let bytes: [u8; AUTH_TOKEN_LEN] =
random
.as_slice()
.try_into()
.map_err(|_| AuthTokenError::RandomnessUnavailable {
reason: format!(
"csprng returned {} bytes, expected {AUTH_TOKEN_LEN}",
random.len()
),
})?;
Ok(Self { bytes })
}
pub fn parse_hex(text: &str) -> Result<Self, AuthTokenError> {
let count = text.chars().count();
if count != AUTH_TOKEN_HEX_LEN {
return Err(AuthTokenError::BadLength {
expected: AUTH_TOKEN_HEX_LEN,
found: count,
});
}
let mut bytes = [0u8; AUTH_TOKEN_LEN];
let mut nibbles = text.chars().enumerate();
for byte in &mut bytes {
let (high_index, high) = nibbles.next().ok_or(AuthTokenError::BadLength {
expected: AUTH_TOKEN_HEX_LEN,
found: count,
})?;
let (low_index, low) = nibbles.next().ok_or(AuthTokenError::BadLength {
expected: AUTH_TOKEN_HEX_LEN,
found: count,
})?;
*byte = (nibble(high, high_index)? << 4) | nibble(low, low_index)?;
}
Ok(Self { bytes })
}
#[must_use]
pub fn reveal_hex(&self) -> String {
let mut out = String::with_capacity(AUTH_TOKEN_HEX_LEN);
for byte in self.bytes {
out.push(char::from(HEX_DIGITS[usize::from(byte >> 4)]));
out.push(char::from(HEX_DIGITS[usize::from(byte & 0x0F)]));
}
out
}
#[must_use]
pub const fn reveal_bytes(&self) -> &[u8; AUTH_TOKEN_LEN] {
&self.bytes
}
#[must_use]
pub fn is_zero(&self) -> bool {
ct_eq(&self.bytes, &[0u8; AUTH_TOKEN_LEN])
}
#[must_use]
pub fn verify(&self, presented: &Self) -> bool {
ct_eq(&self.bytes, &presented.bytes)
}
}
fn nibble(ch: char, index: usize) -> Result<u8, AuthTokenError> {
match ch {
'0'..='9' => Ok(ch as u8 - b'0'),
'a'..='f' => Ok(ch as u8 - b'a' + 10),
_ => Err(AuthTokenError::NotLowercaseHex { ch, index }),
}
}
impl PartialEq for AuthToken {
fn eq(&self, other: &Self) -> bool {
ct_eq(&self.bytes, &other.bytes)
}
}
impl Eq for AuthToken {}
impl fmt::Debug for AuthToken {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "AuthToken({REDACTED})")
}
}
impl fmt::Display for AuthToken {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(REDACTED)
}
}
impl Default for AuthToken {
fn default() -> Self {
Self::ZERO
}
}
impl Drop for AuthToken {
fn drop(&mut self) {
self.bytes.zeroize();
}
}
impl FromStr for AuthToken {
type Err = AuthTokenError;
fn from_str(text: &str) -> Result<Self, Self::Err> {
Self::parse_hex(text)
}
}
impl Serialize for AuthToken {
fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
serializer.serialize_str(&self.reveal_hex())
}
}
impl<'de> Deserialize<'de> for AuthToken {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
let text = String::deserialize(deserializer)?;
Self::parse_hex(&text).map_err(D::Error::custom)
}
}
impl Encode for AuthToken {
fn encode<E: Encoder>(&self, encoder: &mut E) -> Result<(), oxicode::error::Error> {
self.bytes.encode(encoder)
}
}
impl<Context> Decode<Context> for AuthToken {
fn decode<D: Decoder<Context = Context>>(
decoder: &mut D,
) -> Result<Self, oxicode::error::Error> {
let bytes = <[u8; AUTH_TOKEN_LEN]>::decode(decoder)
.map_err(|_| codec_invalid("auth token must be exactly 32 bytes"))?;
Ok(Self { bytes })
}
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
use crate::codec::{WireDecode, WireEncode};
#[test]
fn hex_form_is_sixty_four_lowercase_characters() {
let token = AuthToken::from_bytes([0xDE; AUTH_TOKEN_LEN]);
let hex = token.reveal_hex();
assert_eq!(hex.len(), AUTH_TOKEN_HEX_LEN);
assert_eq!(hex, "de".repeat(32));
assert!(
hex.chars()
.all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase())
);
}
#[test]
fn hex_round_trips_for_every_byte_value() {
let mut bytes = [0u8; AUTH_TOKEN_LEN];
for (index, byte) in bytes.iter_mut().enumerate() {
*byte = (index as u8).wrapping_mul(8).wrapping_add(3);
}
let token = AuthToken::from_bytes(bytes);
let parsed = AuthToken::parse_hex(&token.reveal_hex()).unwrap();
assert_eq!(parsed, token);
assert_eq!(parsed.reveal_bytes(), &bytes);
}
#[test]
fn nibble_order_is_high_then_low() {
let mut bytes = [0u8; AUTH_TOKEN_LEN];
bytes[0] = 0x1F;
assert!(AuthToken::from_bytes(bytes).reveal_hex().starts_with("1f"));
}
#[test]
fn wrong_lengths_are_rejected() {
for len in [0usize, 1, 63, 65, 128] {
match AuthToken::parse_hex(&"a".repeat(len)) {
Err(AuthTokenError::BadLength { expected, found }) => {
assert_eq!(expected, AUTH_TOKEN_HEX_LEN);
assert_eq!(found, len);
}
other => panic!("length {len} should be rejected, got {other:?}"),
}
}
}
#[test]
fn uppercase_hex_is_rejected() {
let text = format!("A{}", "0".repeat(63));
match AuthToken::parse_hex(&text) {
Err(AuthTokenError::NotLowercaseHex { ch, index }) => {
assert_eq!(ch, 'A');
assert_eq!(index, 0);
}
other => panic!("unexpected {other:?}"),
}
}
#[test]
fn non_hex_characters_are_rejected_with_their_position() {
let mut text = "0".repeat(64);
text.replace_range(17..18, "z");
match AuthToken::parse_hex(&text) {
Err(AuthTokenError::NotLowercaseHex { ch, index }) => {
assert_eq!(ch, 'z');
assert_eq!(index, 17);
}
other => panic!("unexpected {other:?}"),
}
}
#[test]
fn multibyte_input_of_the_right_char_count_is_rejected_cleanly() {
let text = "é".repeat(64);
assert!(matches!(
AuthToken::parse_hex(&text),
Err(AuthTokenError::NotLowercaseHex { .. })
));
}
#[test]
fn equality_is_value_based() {
let a = AuthToken::from_bytes([9; AUTH_TOKEN_LEN]);
let b = AuthToken::from_bytes([9; AUTH_TOKEN_LEN]);
let mut differs_last = [9u8; AUTH_TOKEN_LEN];
differs_last[AUTH_TOKEN_LEN - 1] = 8;
let mut differs_first = [9u8; AUTH_TOKEN_LEN];
differs_first[0] = 8;
assert_eq!(a, b);
assert!(a.verify(&b));
assert_ne!(a, AuthToken::from_bytes(differs_last));
assert_ne!(a, AuthToken::from_bytes(differs_first));
assert!(!a.verify(&AuthToken::from_bytes(differs_first)));
}
#[test]
fn debug_and_display_never_leak_the_secret() {
let token = AuthToken::from_bytes([0xAB; AUTH_TOKEN_LEN]);
let hex = token.reveal_hex();
let rendered = format!("{token:?} {token}");
assert!(!rendered.contains(&hex));
assert!(!rendered.contains("abab"));
assert_eq!(format!("{token:?}"), "AuthToken(<redacted>)");
assert_eq!(token.to_string(), REDACTED);
}
#[test]
fn zero_token_is_recognised() {
assert!(AuthToken::ZERO.is_zero());
assert_eq!(AuthToken::default(), AuthToken::ZERO);
assert_eq!(AuthToken::ZERO.reveal_hex(), "0".repeat(64));
assert!(
!AuthToken::from_bytes([
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
0, 0, 0, 1
])
.is_zero()
);
}
#[test]
fn generate_produces_distinct_high_entropy_tokens() {
let a = AuthToken::generate().unwrap();
let b = AuthToken::generate().unwrap();
assert_ne!(a, b);
assert!(!a.is_zero());
let first = a.reveal_bytes()[0];
assert!(a.reveal_bytes().iter().any(|byte| *byte != first));
}
#[test]
fn codec_encodes_thirty_two_raw_bytes() {
let token = AuthToken::from_bytes([0x5A; AUTH_TOKEN_LEN]);
let bytes = token.encode_to_vec().unwrap();
assert_eq!(bytes.len(), AUTH_TOKEN_LEN);
assert_eq!(bytes, vec![0x5A; AUTH_TOKEN_LEN]);
assert_eq!(AuthToken::decode_exact(&bytes).unwrap(), token);
}
#[test]
fn a_short_encoded_token_is_rejected() {
let bytes = vec![0u8; AUTH_TOKEN_LEN - 1];
assert!(AuthToken::decode_exact(&bytes).is_err());
}
#[test]
fn serde_uses_the_hex_form() {
let token = AuthToken::from_bytes([0x0F; AUTH_TOKEN_LEN]);
let json = serde_json::to_string(&token).unwrap();
assert_eq!(json, format!("\"{}\"", "0f".repeat(32)));
assert_eq!(serde_json::from_str::<AuthToken>(&json).unwrap(), token);
assert!(serde_json::from_str::<AuthToken>("\"short\"").is_err());
}
#[test]
fn from_str_matches_parse_hex() {
let hex = "f".repeat(64);
assert_eq!(
hex.parse::<AuthToken>().unwrap(),
AuthToken::parse_hex(&hex).unwrap()
);
}
#[test]
fn cloning_preserves_the_value() {
let token = AuthToken::from_bytes([3; AUTH_TOKEN_LEN]);
let copy = token.clone();
assert_eq!(token, copy);
drop(copy);
assert_eq!(token.reveal_bytes(), &[3u8; AUTH_TOKEN_LEN]);
}
}