ironshield_types/

token.rs

use chrono::Utc;
use serde::{
    Deserialize, 
    Serialize
};

use crate::serde_utils::{
    serialize_signature, 
    deserialize_signature
};

/// IronShield Token structure
///
/// * `challenge_signature`:      The Ed25519 signature of the challenge.
/// * `valid_for`:                The Unix timestamp in unix millis.
/// * `public_key`:               The Ed25519 public key corresponding
///                               to the central private key (32 bytes).
/// * `authentication_signature`: The signature over (challenge_signature
///                               || valid_for).
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct IronShieldToken {
    #[serde(
        serialize_with = "serialize_signature",
        deserialize_with = "deserialize_signature"
    )]
    pub challenge_signature: [u8; 64],
    pub valid_for:           i64,
    pub public_key:          [u8; 32],
    #[serde(
        serialize_with = "serialize_signature",
        deserialize_with = "deserialize_signature"
    )]
    pub auth_signature:      [u8; 64],
}

impl IronShieldToken {
    pub fn new(
        challenge_signature: [u8; 64],
        valid_for:           i64,
        public_key:          [u8; 32],
        auth_signature:      [u8; 64],
    ) -> Self {
        Self {
            challenge_signature,
            valid_for,
            public_key,
            auth_signature,
        }
    }

    /// # Returns
    /// * `bool`: 
    pub fn is_expired(&self) -> bool {
        Utc::now().timestamp_millis() > self.valid_for
    }

    /// Concatenates the token data into a string.
    ///
    /// Concatenates:
    /// - `challenge_signature`       as a lowercase hex string.
    /// - `valid_for`:                as a string.
    /// - `public_key`:               as a lowercase hex string.
    /// - `authentication_signature`: as a lowercase hex string.
    pub fn concat_struct(&self) -> String {
        format!(
            "{}|{}|{}|{}",
            // Use of hex::encode to convert the arrays to hex strings
            // "Encodes data as hex string using lowercase characters."
            // Requirement of `format!`.
            hex::encode(self.challenge_signature),
            self.valid_for,
            hex::encode(self.public_key),
            hex::encode(self.auth_signature)
        )
    }

    /// Creates an `IronShieldToken` from a concatenated string.
    ///
    /// This function reverses the operation of `IronShieldToken::concat_struct`.
    /// Expects a string in the format:
    /// "challenge_signature|valid_for|public_key|authentication_signature"
    ///
    /// # Arguments
    ///
    /// * `concat_str`: The concatenated string to parse, typically
    ///                 generated by `concat_struct()`.
    ///
    /// # Returns
    ///
    /// * `Result<Self, String>`: A result containing the parsed
    ///                           `IronShieldToken` or an error message
    ///                           if parsing fails.
    pub fn from_concat_struct(concat_str: &str) -> Result<Self, String> {
        let parts: Vec<&str> = concat_str.split('|').collect();

        if parts.len() != 4 {
            return Err(format!("Expected 4 parts, got {}", parts.len()));
        }

        let challenge_signature_bytes = hex::decode(parts[0])
            .map_err(|_| "Failed to decode challenge_signature hex string")?;
        let challenge_signature: [u8; 64] = challenge_signature_bytes.try_into()
            .map_err(|_| "Challenge signature must be exactly 64 bytes")?;

        let valid_for = parts[1].parse::<i64>()
            .map_err(|_| "Failed to parse valid_for as i64")?;

        let public_key_bytes = hex::decode(parts[2])
            .map_err(|_| "Failed to decode public_key hex string")?;
        let public_key: [u8; 32] = public_key_bytes.try_into()
            .map_err(|_| "Public key must be exactly 32 bytes")?;

        let auth_signature_bytes = hex::decode(parts[3])
            .map_err(|_| "Failed to decode authentication_signature hex string")?;
        let authentication_signature: [u8; 64] = auth_signature_bytes.try_into()
            .map_err(|_| "Authentication signature must be exactly 64 bytes")?;

        Ok(Self {
            challenge_signature,
            valid_for,
            public_key,
            auth_signature: authentication_signature,
        })
    }

    /// Encodes the response as a base64url string for HTTP header transport.
    ///
    /// This method concatenates all response fields using the established `|` delimiter
    /// format, and then base64url-encodes the result for safe transport in HTTP headers.
    ///
    /// # Returns
    /// * `String` - Base64url-encoded string ready for HTTP header use
    ///
    /// # Example
    /// ```
    /// use ironshield_types::IronShieldToken;
    /// let response = IronShieldToken::new([0xAB; 64], 12345, [0x12; 32], [0x34; 64]);
    /// let header_value = response.to_base64url_header();
    /// // Use header_value in HTTP header: "X-IronShield-Challenge-Response: {header_value}"
    /// ```
    pub fn to_base64url_header(&self) -> String {
        crate::serde_utils::concat_struct_base64url_encode(&self.concat_struct())
    }

    /// Decodes a base64url-encoded response from an HTTP header.
    ///
    /// This method reverses the `to_base64url_header()` operation by first base64url-decoding
    /// the input string and then parsing it using the established `|` delimiter format.
    ///
    /// # Arguments
    /// * `encoded_header` - The base64url-encoded string from the HTTP header
    ///
    /// # Returns
    /// * `Result<Self, String>` - Decoded response or detailed error message
    ///
    /// # Example
    /// ```
    /// use ironshield_types::IronShieldToken;
    /// // Create a response and encode it
    /// let original = IronShieldToken::new([0xAB; 64], 12345, [0x12; 32], [0x34; 64]);
    /// let header_value = original.to_base64url_header();
    /// // Decode it back
    /// let decoded = IronShieldToken::from_base64url_header(&header_value).unwrap();
    /// assert_eq!(original.challenge_signature, decoded.challenge_signature);
    /// ```
    pub fn from_base64url_header(encoded_header: &str) -> Result<Self, String> {
        // Decode using the existing serde_utils function.
        let concat_str: String = crate::serde_utils::concat_struct_base64url_decode(encoded_header.to_string())?;

        // Parse using the existing concat_struct format.
        Self::from_concat_struct(&concat_str)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_from_concat_struct_edge_cases() {
        // Test with a valid minimum length hex (32 bytes = 64 hex chars for public_key, 64 bytes = 128 hex chars for signatures).
        // Building strings programmatically.
        let valid_32_byte_hex = "0".repeat(64);  // 32 bytes = 64 hex chars
        let valid_64_byte_hex = "0".repeat(128); // 64 bytes = 128 hex chars
        assert_eq!(valid_32_byte_hex.len(), 64, "32-byte hex string should be exactly 64 characters");
        assert_eq!(valid_64_byte_hex.len(), 128, "64-byte hex string should be exactly 128 characters");

        let input = format!("{}|1000000|{}|{}",
                            valid_64_byte_hex, valid_32_byte_hex, valid_64_byte_hex);
        let result = IronShieldToken::from_concat_struct(&input);

        if result.is_err() {
            panic!("Expected success but got error: {}", result.unwrap_err());
        }

        let parsed = result.unwrap();
        assert_eq!(parsed.challenge_signature, [0u8; 64]);
        assert_eq!(parsed.valid_for, 1000000);
        assert_eq!(parsed.public_key, [0u8; 32]);
        assert_eq!(parsed.auth_signature, [0u8; 64]);

        // Test with all F's hex.
        let all_f_32_hex = "f".repeat(64);   // 32 bytes of 0xFF
        let all_f_64_hex = "f".repeat(128);  // 64 bytes of 0xFF
        assert_eq!(all_f_32_hex.len(), 64, "All F's 32-byte hex string should be exactly 64 characters");
        assert_eq!(all_f_64_hex.len(), 128, "All F's 64-byte hex string should be exactly 128 characters");

        let input = format!("{}|9999999|{}|{}",
                            all_f_64_hex, all_f_32_hex, all_f_64_hex);
        let result = IronShieldToken::from_concat_struct(&input);

        if result.is_err() {
            panic!("Expected success but got error: {}", result.unwrap_err());
        }

        let parsed = result.unwrap();
        assert_eq!(parsed.challenge_signature, [0xffu8; 64]);
        assert_eq!(parsed.valid_for, 9999999);
        assert_eq!(parsed.public_key, [0xffu8; 32]);
        assert_eq!(parsed.auth_signature, [0xffu8; 64]);
    }

    #[test]
    fn test_concat_struct_roundtrip() {
        // Create a token with known values.
        let original_token = IronShieldToken::new(
            [0xAB; 64],
            1700000000000,
            [0xCD; 32],
            [0xEF; 64],
        );

        // Convert to concat string and back.
        let concat_str = original_token.concat_struct();
        let parsed_token = IronShieldToken::from_concat_struct(&concat_str).unwrap();

        // Verify all fields are preserved.
        assert_eq!(original_token.challenge_signature, parsed_token.challenge_signature);
        assert_eq!(original_token.valid_for, parsed_token.valid_for);
        assert_eq!(original_token.public_key, parsed_token.public_key);
        assert_eq!(original_token.auth_signature, parsed_token.auth_signature);
    }

    #[test]
    fn test_empty_string_parsing() {
        let result = IronShieldToken::from_concat_struct("");
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("Expected 4 parts, got 1"));
    }


    #[test]
    fn test_from_concat_struct_error_cases() {
        // Test with the wrong number of parts.
        let result = IronShieldToken::from_concat_struct("only|two|parts");
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("Expected 4 parts, got 3"));

        let result = IronShieldToken::from_concat_struct("too|many|parts|here|extra");
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("Expected 4 parts, got 5"));

        // Test with invalid hex for challenge_signature.
        let valid_32_hex = "0".repeat(64);
        let valid_64_hex = "0".repeat(128);
        let invalid_hex = "invalid_hex_string";

        let input = format!("{}|1000000|{}|{}", invalid_hex, valid_32_hex, valid_64_hex);
        let result = IronShieldToken::from_concat_struct(&input);
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("Failed to decode challenge_signature hex string"));

        // Test with invalid hex for public_key.
        let input = format!("{}|1000000|{}|{}", valid_64_hex, invalid_hex, valid_64_hex);
        let result = IronShieldToken::from_concat_struct(&input);
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("Failed to decode public_key hex string"));

        // Test with invalid hex for authentication_signature.
        let input = format!("{}|1000000|{}|{}", valid_64_hex, valid_32_hex, invalid_hex);
        let result = IronShieldToken::from_concat_struct(&input);
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("Failed to decode authentication_signature hex string"));

        // Test with an invalid timestamp.
        let input = format!("{}|not_a_number|{}|{}", valid_64_hex, valid_32_hex, valid_64_hex);
        let result = IronShieldToken::from_concat_struct(&input);
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("Failed to parse valid_for as i64"));

        // Test with wrong length hex strings.
        let short_hex = "0".repeat(32); // Too short for a 64-byte signature.
        let input = format!("{}|1000000|{}|{}", short_hex, valid_32_hex, valid_64_hex);
        let result = IronShieldToken::from_concat_struct(&input);
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("Challenge signature must be exactly 64 bytes"));

        let short_32_hex = "0".repeat(32); // Too short for a 32-byte public key.
        let input = format!("{}|1000000|{}|{}", valid_64_hex, short_32_hex, valid_64_hex);
        let result = IronShieldToken::from_concat_struct(&input);
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("Public key must be exactly 32 bytes"));
    }
}