common_access_token/

cat.rs

//! Core functionality for Common Access Token (CAT) generation and validation.
//!
//! This module provides the main entry point for working with CAT tokens. It implements:
//! - Token generation with HMAC signatures
//! - Token validation with comprehensive security checks
//! - Conversion between JSON and CAT claims
//!
//! The `Cat` struct is the primary interface for applications using this library.
//! It handles the cryptographic operations, token format, and claim validation.
//!
//! # Examples
//!
//! ```
//! use common_access_token::{Cat, CatGenerateOptions, CatOptions, CatValidationType, Claims};
//! use std::collections::HashMap;
//!
//! // Create a CAT instance with a cryptographic key
//! let key = hex::decode("403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388").unwrap();
//! let cat = Cat::new(CatOptions {
//!     keys: HashMap::from([("Symmetric256".to_string(), key)]),
//!     expect_cwt_tag: true,
//! });
//!
//! // Create claims for the token
//! let mut claims = Claims::new();
//! claims.set_issuer("example");
//! claims.set_subject("user123");
//! claims.set_audience("service");
//!
//! // Generate a token
//! let token = cat.generate(claims, &CatGenerateOptions {
//!     validation_type: CatValidationType::Mac,
//!     alg: "HS256".to_string(),
//!     kid: "Symmetric256".to_string(),
//!     generate_cwt_id: true,
//! }).unwrap();
//! ```

use crate::claims::{ClaimValue, Claims, LABEL_CTI};
use crate::cose::{CoseMac0, ALG_HS256, HEADER_ALG, HEADER_KID, TAG_COSE_MAC0, TAG_CWT};
use crate::error::Error;
use crate::util::{current_time_secs, from_base64_url, generate_random_hex, to_base64_no_padding};
use serde_json::json;
use std::collections::{BTreeMap, HashMap};

/// Type of CAT validation mechanism to use for token generation and validation.
///
/// This enum specifies the cryptographic mechanism used to secure the token.
#[derive(Debug, Clone, PartialEq)]
pub enum CatValidationType {
    /// HMAC-based authentication code (symmetric key)
    Mac,

    /// Digital signature (asymmetric key) - not currently implemented
    Sign,

    /// No cryptographic protection - not recommended for production use
    None,
}

/// Options for validating a CAT token.
///
/// This struct contains parameters that control how token validation is performed,
/// including which issuers and audiences are considered valid.
///
/// # Examples
///
/// ```
/// use common_access_token::CatValidationOptions;
///
/// // Basic validation requiring a specific issuer
/// let options = CatValidationOptions {
///     issuer: "trusted-issuer".to_string(),
///     audience: None, // Don't validate audience
/// };
///
/// // Validation with audience restriction
/// let options_with_audience = CatValidationOptions {
///     issuer: "trusted-issuer".to_string(),
///     audience: Some(vec!["app-1".to_string(), "app-2".to_string()]),
/// };
/// ```
#[derive(Debug, Clone)]
pub struct CatValidationOptions {
    /// Expected issuer of token. The token will be rejected if it doesn't match this value.
    pub issuer: String,

    /// Allowed audiences for token. If provided, the token must contain at least one
    /// of these audiences to be considered valid. If None, audience validation is skipped.
    pub audience: Option<Vec<String>>,
}

/// Options for generating a CAT token.
///
/// This struct contains parameters that control how a token is generated,
/// including which cryptographic algorithm and key to use.
///
/// # Examples
///
/// ```
/// use common_access_token::{CatGenerateOptions, CatValidationType};
///
/// // Basic token generation options
/// let options = CatGenerateOptions {
///     validation_type: CatValidationType::Mac,
///     alg: "HS256".to_string(),
///     kid: "key-1".to_string(),
///     generate_cwt_id: true,
/// };
///
/// // Using the default options
/// let default_options = CatGenerateOptions::default();
/// ```
#[derive(Debug, Clone)]
pub struct CatGenerateOptions {
    /// Type of validation mechanism to use for the token.
    /// Currently, only `CatValidationType::Mac` is fully implemented.
    pub validation_type: CatValidationType,

    /// Algorithm to use for token generation.
    /// For `CatValidationType::Mac`, this should be "HS256".
    pub alg: String,

    /// Key ID to use for token generation. This must match a key ID in the
    /// `keys` map provided to the `Cat` instance.
    pub kid: String,

    /// Whether to generate a CWT ID for the token.
    /// A CWT ID is a unique identifier for the token that can be used for tracking
    /// or revocation purposes.
    pub generate_cwt_id: bool,
}

impl Default for CatGenerateOptions {
    /// Creates a default set of options for token generation.
    ///
    /// The default configuration:
    /// - Uses HMAC-based authentication (`CatValidationType::Mac`)
    /// - Uses the HS256 algorithm (HMAC with SHA-256)
    /// - Has an empty key ID (must be set before use)
    /// - Does not generate a CWT ID
    fn default() -> Self {
        CatGenerateOptions {
            validation_type: CatValidationType::Mac,
            alg: "HS256".to_string(),
            kid: "".to_string(),
            generate_cwt_id: false,
        }
    }
}

/// Configuration options for creating a CAT instance.
///
/// This struct contains the cryptographic keys and format options used
/// for token generation and validation.
///
/// # Examples
///
/// ```
/// use common_access_token::CatOptions;
/// use std::collections::HashMap;
///
/// // Create options with a single key
/// let key = hex::decode("403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388").unwrap();
/// let options = CatOptions {
///     keys: HashMap::from([("key-1".to_string(), key)]),
///     expect_cwt_tag: true,
/// };
///
/// // Create empty options (not useful until keys are added)
/// let empty_options = CatOptions::default();
/// ```
#[derive(Debug, Clone, Default)]
pub struct CatOptions {
    /// Map of key IDs to cryptographic keys.
    ///
    /// Each entry maps a key identifier (kid) to the actual key material (as bytes).
    /// When generating or validating tokens, the key ID is used to look up the
    /// appropriate key in this map.
    pub keys: HashMap<String, Vec<u8>>,

    /// Whether tokens should include the CWT tag.
    ///
    /// When true, tokens will be wrapped with the CWT tag (61) as defined in RFC 8392.
    /// This should be set to true for interoperability with other implementations.
    pub expect_cwt_tag: bool,
}

/// Common Access Token (CAT) validator and generator.
///
/// This is the main struct for working with CAT tokens. It provides methods for:
/// - Generating tokens from claims
/// - Validating tokens and extracting claims
/// - Converting between JSON and CAT claims
///
/// # Examples
///
/// ```
/// use common_access_token::{Cat, CatOptions, CatGenerateOptions, CatValidationOptions, CatValidationType, Claims};
/// use std::collections::HashMap;
///
/// // Create a CAT instance
/// let key = hex::decode("403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388").unwrap();
/// let cat = Cat::new(CatOptions {
///     keys: HashMap::from([("key-1".to_string(), key)]),
///     expect_cwt_tag: true,
/// });
///
/// // Create and generate a token
/// let mut claims = Claims::new();
/// claims.set_issuer("example");
/// let token = cat.generate(claims, &CatGenerateOptions {
///     validation_type: CatValidationType::Mac,
///     alg: "HS256".to_string(),
///     kid: "key-1".to_string(),
///     generate_cwt_id: true,
/// }).unwrap();
///
/// // Validate the token
/// let validation_options = CatValidationOptions {
///     issuer: "example".to_string(),
///     audience: None,
/// };
/// let validated_claims = cat.validate(&token, CatValidationType::Mac, &validation_options).unwrap();
/// ```
#[derive(Debug, Clone)]
pub struct Cat {
    /// Map of key IDs to cryptographic keys
    keys: HashMap<String, Vec<u8>>,
    /// Whether tokens should include the CWT tag
    expect_cwt_tag: bool,
}

impl Cat {
    /// Creates a new CAT instance with the specified options.
    ///
    /// # Arguments
    ///
    /// * `opts` - Configuration options including cryptographic keys and format settings
    ///
    /// # Examples
    ///
    /// ```
    /// use common_access_token::{Cat, CatOptions};
    /// use std::collections::HashMap;
    ///
    /// let key = hex::decode("403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388").unwrap();
    /// let cat = Cat::new(CatOptions {
    ///     keys: HashMap::from([("key-1".to_string(), key)]),
    ///     expect_cwt_tag: true,
    /// });
    /// ```
    pub fn new(opts: CatOptions) -> Self {
        Cat {
            keys: opts.keys,
            expect_cwt_tag: opts.expect_cwt_tag,
        }
    }

    /// Validates a CAT token and returns the claims if valid.
    ///
    /// This method performs several validation steps:
    /// 1. Decodes the token from base64
    /// 2. Verifies the cryptographic signature/MAC
    /// 3. Validates the claims (issuer, expiration, audience)
    ///
    /// # Arguments
    ///
    /// * `token` - The CAT token as a base64url-encoded string
    /// * `validation_type` - The type of validation to perform (Mac, Sign, or None)
    /// * `opts` - Options controlling validation behavior
    ///
    /// # Returns
    ///
    /// * `Ok(Claims)` - The validated claims from the token
    /// * `Err(Error)` - An error indicating why validation failed
    ///
    /// # Examples
    ///
    /// ```
    /// # use common_access_token::{Cat, CatOptions, CatValidationOptions, CatValidationType};
    /// # use std::collections::HashMap;
    /// #
    /// # let key = hex::decode("403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388").unwrap();
    /// # let cat = Cat::new(CatOptions {
    /// #     keys: HashMap::from([("key-1".to_string(), key)]),
    /// #     expect_cwt_tag: true,
    /// # });
    /// #
    /// // Validate a token
    /// let token = "..."; // Base64url-encoded token
    /// let validation_options = CatValidationOptions {
    ///     issuer: "trusted-issuer".to_string(),
    ///     audience: Some(vec!["my-app".to_string()]),
    /// };
    ///
    /// match cat.validate(token, CatValidationType::Mac, &validation_options) {
    ///     Ok(claims) => {
    ///         println!("Token is valid!");
    ///         println!("Subject: {:?}", claims.get_subject());
    ///     },
    ///     Err(err) => {
    ///         println!("Token validation failed: {}", err);
    ///     }
    /// }
    /// ```
    pub fn validate(
        &self,
        token: &str,
        validation_type: CatValidationType,
        opts: &CatValidationOptions,
    ) -> Result<Claims, Error> {
        let token_without_padding = token;
        let token_bytes = from_base64_url(token_without_padding)?;

        match validation_type {
            CatValidationType::Mac => {
                if self.keys.is_empty() {
                    return Err(Error::MissingOptionsForMacValidation);
                }

                let mut last_error = Error::KeyNotFound("No keys available".to_string());

                // Try each key until one works
                for (kid, key) in &self.keys {
                    match self.validate_mac(&token_bytes, key, kid) {
                        Ok(claims) => {
                            // Validate the claims
                            self.validate_claims(&claims, opts)?;
                            return Ok(claims);
                        }
                        Err(err) => {
                            last_error = err;
                        }
                    }
                }

                Err(last_error)
            }
            _ => Err(Error::UnsupportedValidationType),
        }
    }

    /// Generates a CAT token from the provided claims.
    ///
    /// This method creates a token by:
    /// 1. Optionally generating a CWT ID if requested
    /// 2. Serializing the claims to CBOR
    /// 3. Creating a cryptographic signature/MAC
    /// 4. Encoding the result as a base64url string
    ///
    /// # Arguments
    ///
    /// * `claims` - The claims to include in the token
    /// * `opts` - Options controlling token generation
    ///
    /// # Returns
    ///
    /// * `Ok(String)` - The generated token as a base64url-encoded string
    /// * `Err(Error)` - An error indicating why token generation failed
    ///
    /// # Examples
    ///
    /// ```
    /// # use common_access_token::{Cat, CatOptions, CatGenerateOptions, CatValidationType, Claims};
    /// # use std::collections::HashMap;
    /// #
    /// # let key = hex::decode("403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388").unwrap();
    /// # let cat = Cat::new(CatOptions {
    /// #     keys: HashMap::from([("key-1".to_string(), key)]),
    /// #     expect_cwt_tag: true,
    /// # });
    /// #
    /// // Create claims
    /// let mut claims = Claims::new();
    /// claims.set_issuer("my-service");
    /// claims.set_subject("user-123");
    /// claims.set_audience("client-app");
    ///
    /// // Set expiration time
    /// let now = std::time::SystemTime::now()
    ///     .duration_since(std::time::UNIX_EPOCH)
    ///     .unwrap()
    ///     .as_secs() as i64;
    /// claims.set_expiration(now + 3600); // 1 hour from now
    ///
    /// // Generate the token
    /// let token = cat.generate(claims, &CatGenerateOptions {
    ///     validation_type: CatValidationType::Mac,
    ///     alg: "HS256".to_string(),
    ///     kid: "key-1".to_string(),
    ///     generate_cwt_id: true,
    /// }).unwrap();
    ///
    /// println!("Generated token: {}", token);
    /// ```
    pub fn generate(&self, claims: Claims, opts: &CatGenerateOptions) -> Result<String, Error> {
        let mut claims = claims;

        // Generate a CWT ID if requested
        if opts.generate_cwt_id && claims.get_claim(LABEL_CTI).is_none() {
            let cti = generate_random_hex(16);
            claims.set_cwt_id(cti.as_bytes());
        }

        match opts.validation_type {
            CatValidationType::Mac => {
                let key = self
                    .keys
                    .get(&opts.kid)
                    .ok_or_else(|| Error::KeyNotFound(opts.kid.clone()))?;

                let token_bytes = self.create_mac(&claims, key, &opts.kid)?;
                Ok(to_base64_no_padding(&token_bytes))
            }
            _ => Err(Error::UnsupportedValidationType),
        }
    }

    /// Generates a CAT token from a JSON object containing claims.
    ///
    /// This is a convenience method that converts JSON claims to a `Claims` object
    /// and then generates a token. It's useful when working with JSON data from
    /// external sources.
    ///
    /// # Arguments
    ///
    /// * `json_claims` - JSON object containing claims (e.g., `{"iss": "issuer", "sub": "subject"}`)
    /// * `opts` - Options controlling token generation
    ///
    /// # Returns
    ///
    /// * `Ok(String)` - The generated token as a base64url-encoded string
    /// * `Err(Error)` - An error indicating why token generation failed
    ///
    /// # Examples
    ///
    /// ```
    /// # use common_access_token::{Cat, CatOptions, CatGenerateOptions, CatValidationType};
    /// # use std::collections::HashMap;
    /// # use serde_json::json;
    /// #
    /// # let key = hex::decode("403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388").unwrap();
    /// # let cat = Cat::new(CatOptions {
    /// #     keys: HashMap::from([("key-1".to_string(), key)]),
    /// #     expect_cwt_tag: true,
    /// # });
    /// #
    /// // Create claims as JSON
    /// let now = std::time::SystemTime::now()
    ///     .duration_since(std::time::UNIX_EPOCH)
    ///     .unwrap()
    ///     .as_secs() as i64;
    ///
    /// let json_claims = json!({
    ///     "iss": "my-service",
    ///     "sub": "user-123",
    ///     "aud": "client-app",
    ///     "exp": now + 3600, // 1 hour from now
    ///     "iat": now
    /// });
    ///
    /// // Generate the token
    /// let token = cat.generate_from_json(json_claims, &CatGenerateOptions {
    ///     validation_type: CatValidationType::Mac,
    ///     alg: "HS256".to_string(),
    ///     kid: "key-1".to_string(),
    ///     generate_cwt_id: true,
    /// }).unwrap();
    /// ```
    pub fn generate_from_json(
        &self,
        json_claims: serde_json::Value,
        opts: &CatGenerateOptions,
    ) -> Result<String, Error> {
        let claims = self.json_to_claims(json_claims, opts)?;
        self.generate(claims, opts)
    }

    // Private methods

    /// Validates a token using HMAC-based authentication.
    ///
    /// This method handles the cryptographic verification of the token and
    /// extracts the claims if the verification succeeds.
    ///
    /// # Arguments
    ///
    /// * `token_bytes` - The raw binary token data
    /// * `key` - The cryptographic key to use for verification
    /// * `_kid` - The key ID (not used in the verification process)
    ///
    /// # Returns
    ///
    /// * `Ok(Claims)` - The claims from the token if verification succeeds
    /// * `Err(Error)` - An error if verification fails
    fn validate_mac(&self, token_bytes: &[u8], key: &[u8], _kid: &str) -> Result<Claims, Error> {
        // Note: _kid parameter is not used in the validation process, as we extract the kid from the token if needed
        // Check if the token has a CWT tag
        if self.expect_cwt_tag {
            // Try to parse the token as a tagged CWT
            match ciborium::de::from_reader::<(u64, Vec<u8>), _>(token_bytes) {
                Ok((tag, inner_data)) => {
                    if tag != TAG_CWT {
                        return Err(Error::ExpectedCwtTag);
                    }

                    // Try to parse the inner data as a tagged COSE_Mac0
                    match ciborium::de::from_reader::<(u64, Vec<u8>), _>(&inner_data[..]) {
                        Ok((inner_tag, cose_data)) => {
                            if inner_tag != TAG_COSE_MAC0 {
                                return Err(Error::TagMismatch);
                            }

                            // Parse the COSE_Mac0 structure
                            let cose_mac0 = CoseMac0::from_cbor(&cose_data)?;

                            // Verify the MAC
                            cose_mac0.verify(key)?;

                            // Parse the payload
                            let payload = cose_mac0.get_payload();
                            let claims_map: BTreeMap<u64, ClaimValue> =
                                ciborium::de::from_reader(payload)?;

                            Ok(Claims::from_map(claims_map))
                        }
                        Err(_) => {
                            // Try direct parsing as a fallback
                            let cose_mac0 = CoseMac0::from_cbor(&inner_data)?;
                            cose_mac0.verify(key)?;
                            let claims_map: BTreeMap<u64, ClaimValue> =
                                ciborium::de::from_reader(cose_mac0.get_payload())?;
                            Ok(Claims::from_map(claims_map))
                        }
                    }
                }
                Err(_) => {
                    // If we can't parse it as a tagged CWT, try parsing it directly as a COSE_Mac0
                    let cose_mac0 = CoseMac0::from_cbor(token_bytes)?;
                    cose_mac0.verify(key)?;
                    let claims_map: BTreeMap<u64, ClaimValue> =
                        ciborium::de::from_reader(cose_mac0.get_payload())?;
                    Ok(Claims::from_map(claims_map))
                }
            }
        } else {
            // Parse the token directly as a COSE_Mac0 structure
            let cose_mac0 = CoseMac0::from_cbor(token_bytes)?;

            // Verify the MAC
            cose_mac0.verify(key)?;

            // Parse the payload
            let payload = cose_mac0.get_payload();
            let claims_map: BTreeMap<u64, ClaimValue> = ciborium::de::from_reader(payload)?;

            Ok(Claims::from_map(claims_map))
        }
    }

    /// Creates a MAC (Message Authentication Code) for the given claims.
    ///
    /// This method handles the cryptographic signing of the token:
    /// 1. Serializes the claims to CBOR
    /// 2. Creates the COSE_Mac0 structure
    /// 3. Computes the HMAC
    /// 4. Wraps the result with appropriate tags
    ///
    /// # Arguments
    ///
    /// * `claims` - The claims to include in the token
    /// * `key` - The cryptographic key to use for signing
    /// * `kid` - The key ID to include in the token header
    ///
    /// # Returns
    ///
    /// * `Ok(Vec<u8>)` - The raw binary token data
    /// * `Err(Error)` - An error if token creation fails
    fn create_mac(&self, claims: &Claims, key: &[u8], kid: &str) -> Result<Vec<u8>, Error> {
        // Serialize the claims to CBOR
        let mut claims_cbor = Vec::new();
        ciborium::ser::into_writer(claims.as_map(), &mut claims_cbor)?;

        // Create the protected header
        let mut protected_header = BTreeMap::new();
        protected_header.insert(HEADER_ALG, json!(ALG_HS256));

        // Create the unprotected header with the key ID as binary
        let mut unprotected_header = BTreeMap::new();
        // Store the kid as binary value (bytes) instead of a string
        unprotected_header.insert(
            HEADER_KID,
            serde_json::Value::Array(
                kid.as_bytes()
                    .iter()
                    .map(|&b| serde_json::Value::Number(serde_json::Number::from(b)))
                    .collect(),
            ),
        );

        // Create the COSE_Mac0 structure
        let mut cose_mac0 = CoseMac0::new(protected_header, unprotected_header, claims_cbor);

        // Create the MAC tag
        cose_mac0.create_tag(key)?;

        // Serialize the COSE_Mac0 structure to CBOR
        let cose_mac0_cbor = cose_mac0.to_cbor()?;

        if self.expect_cwt_tag {
            // Wrap the COSE_Mac0 in a CWT tag
            let mut result = Vec::new();

            // First tag with COSE_Mac0 tag
            let tagged_cose_mac0 = (TAG_COSE_MAC0, cose_mac0_cbor);
            let mut tagged_cose_mac0_cbor = Vec::new();
            ciborium::ser::into_writer(&tagged_cose_mac0, &mut tagged_cose_mac0_cbor)?;

            // Then tag with CWT tag
            let cwt = (TAG_CWT, tagged_cose_mac0_cbor);
            ciborium::ser::into_writer(&cwt, &mut result)?;

            Ok(result)
        } else {
            Ok(cose_mac0_cbor)
        }
    }

    /// Validates the claims in a token against the provided validation options.
    ///
    /// This method performs several validation checks:
    /// 1. Verifies the issuer matches the expected issuer
    /// 2. Checks if the token has expired
    /// 3. Checks if the token is not yet active (if not-before claim is present)
    /// 4. Verifies the audience is in the list of allowed audiences (if specified)
    ///
    /// # Arguments
    ///
    /// * `claims` - The claims to validate
    /// * `opts` - The validation options specifying expected values
    ///
    /// # Returns
    ///
    /// * `Ok(())` - If all validation checks pass
    /// * `Err(Error)` - An error indicating which validation check failed
    fn validate_claims(&self, claims: &Claims, opts: &CatValidationOptions) -> Result<(), Error> {
        // Check issuer
        if let Some(issuer) = claims.get_issuer() {
            if issuer != &opts.issuer {
                return Err(Error::InvalidIssuer {
                    expected: opts.issuer.clone(),
                    actual: issuer.clone(),
                });
            }
        }

        // Check expiration
        if let Some(exp) = claims.get_expiration() {
            let now = current_time_secs();
            if exp < now {
                return Err(Error::TokenExpired);
            }
        }

        // Check not before
        if let Some(nbf) = claims.get_not_before() {
            let now = current_time_secs();
            if nbf > now {
                return Err(Error::TokenNotActive);
            }
        }

        // Check audience
        if let Some(ref expected_audiences) = opts.audience {
            if let Some(token_audiences) = claims.get_audience() {
                if !expected_audiences
                    .iter()
                    .any(|expected| token_audiences.contains(expected))
                {
                    return Err(Error::InvalidAudience(token_audiences));
                }
            }
        }

        Ok(())
    }

    /// Converts a JSON object to a Claims object.
    ///
    /// This method maps standard JWT claim names to their CWT equivalents:
    /// - "iss" -> issuer
    /// - "sub" -> subject
    /// - "aud" -> audience
    /// - "exp" -> expiration
    /// - "nbf" -> not before
    /// - "iat" -> issued at
    /// - "cti" -> CWT ID
    ///
    /// # Arguments
    ///
    /// * `json_claims` - JSON object containing claims
    /// * `opts` - Generation options (used for CWT ID generation)
    ///
    /// # Returns
    ///
    /// * `Ok(Claims)` - The converted claims
    /// * `Err(Error)` - An error if conversion fails
    ///   Re-signs an existing token with a new expiration time.
    ///
    /// This method extends the lifetime of an existing token by:
    ///
    /// 1. Validating the existing token
    /// 2. Extracting the claims
    /// 3. Updating the expiration time
    /// 4. Generating a new token with the updated claims
    ///
    /// # Arguments
    ///
    /// * `token` - The existing token to re-sign
    /// * `validation_opts` - Options for validating the existing token
    /// * `new_expiration` - The new expiration time (in seconds since UNIX epoch)
    /// * `generate_opts` - Options for generating the new token
    ///
    /// # Returns
    ///
    /// * `Ok(String)` - The newly generated token with extended lifetime
    /// * `Err(Error)` - An error if token validation or generation fails
    ///
    /// # Examples
    ///
    /// ```
    /// # use common_access_token::{Cat, CatOptions, CatGenerateOptions, CatValidationOptions, CatValidationType, Claims};
    /// # use std::collections::HashMap;
    /// # use std::time::SystemTime;
    /// #
    /// # // Create a CAT instance for testing
    /// # let key = hex::decode("403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388").unwrap();
    /// # let cat = Cat::new(CatOptions {
    /// #     keys: HashMap::from([("key-1".to_string(), key)]),
    /// #     expect_cwt_tag: true,
    /// # });
    /// #
    /// # // First, create a valid token to work with
    /// # let mut claims = Claims::new();
    /// # claims.set_issuer("trusted-issuer");
    /// # claims.set_subject("user123");
    /// # let now = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap().as_secs() as i64;
    /// # claims.set_expiration(now + 60); // 1 minute expiration
    /// # claims.set_issued_at(now);
    /// #
    /// # let generate_options = CatGenerateOptions {
    /// #     validation_type: CatValidationType::Mac,
    /// #     alg: "HS256".to_string(),
    /// #     kid: "key-1".to_string(),
    /// #     generate_cwt_id: true,
    /// # };
    /// #
    /// # // Generate a token that we'll use as our "existing token"
    /// # let existing_token = cat.generate(claims, &generate_options).unwrap();
    /// #
    /// // Validation options for the existing token
    /// let validation_options = CatValidationOptions {
    ///     issuer: "trusted-issuer".to_string(),
    ///     audience: None,
    /// };
    ///
    /// // Calculate new expiration time (e.g., 1 hour from now)
    /// let now = std::time::SystemTime::now()
    ///     .duration_since(std::time::UNIX_EPOCH)
    ///     .unwrap()
    ///     .as_secs() as i64;
    /// let new_expiration = now + 3600;
    ///
    /// // Generation options for the new token
    /// let generate_options = CatGenerateOptions {
    ///     validation_type: CatValidationType::Mac,
    ///     alg: "HS256".to_string(),
    ///     kid: "key-1".to_string(),
    ///     generate_cwt_id: true, // Generate a new CWT ID
    /// };
    ///
    /// // Re-sign the token with the new expiration
    /// let new_token = cat.resign_token(
    ///     &existing_token,
    ///     &validation_options,
    ///     new_expiration,
    ///     &generate_options
    /// ).unwrap();
    /// ```
    pub fn resign_token(
        &self,
        token: &str,
        validation_opts: &CatValidationOptions,
        new_expiration: i64,
        generate_opts: &CatGenerateOptions,
    ) -> Result<String, Error> {
        // Validate the existing token
        let mut claims = self.validate(token, CatValidationType::Mac, validation_opts)?;

        // Update the expiration time
        claims.set_expiration(new_expiration);

        // Update the issued_at time to current time
        claims.set_issued_at(current_time_secs());

        // Generate a new token with the updated claims
        self.generate(claims, generate_opts)
    }

    fn json_to_claims(
        &self,
        json_claims: serde_json::Value,
        opts: &CatGenerateOptions,
    ) -> Result<Claims, Error> {
        let mut claims = Claims::new();

        if let serde_json::Value::Object(map) = json_claims {
            for (key, value) in map {
                match key.as_str() {
                    "iss" => {
                        if let serde_json::Value::String(s) = value {
                            claims.set_issuer(&s);
                        }
                    }
                    "sub" => {
                        if let serde_json::Value::String(s) = value {
                            claims.set_subject(&s);
                        }
                    }
                    "aud" => match value {
                        serde_json::Value::String(s) => {
                            claims.set_audience(&s);
                        }
                        serde_json::Value::Array(arr) => {
                            let audience: Vec<String> = arr
                                .iter()
                                .filter_map(|v| {
                                    if let serde_json::Value::String(s) = v {
                                        Some(s.clone())
                                    } else {
                                        None
                                    }
                                })
                                .collect();
                            claims.set_audience_list(audience);
                        }
                        _ => {}
                    },
                    "exp" => {
                        if let serde_json::Value::Number(n) = value {
                            if let Some(i) = n.as_i64() {
                                claims.set_expiration(i);
                            }
                        }
                    }
                    "nbf" => {
                        if let serde_json::Value::Number(n) = value {
                            if let Some(i) = n.as_i64() {
                                claims.set_not_before(i);
                            }
                        }
                    }
                    "iat" => {
                        if let serde_json::Value::Number(n) = value {
                            if let Some(i) = n.as_i64() {
                                claims.set_issued_at(i);
                            }
                        }
                    }
                    "cti" => {
                        if let serde_json::Value::String(s) = value {
                            claims.set_cwt_id(s.as_bytes());
                        }
                    }
                    // Add more claim types as needed
                    _ => {
                        // For now, we'll ignore other claims
                    }
                }
            }
        }

        // Generate a CWT ID if requested and not already set
        if opts.generate_cwt_id && claims.get_claim(LABEL_CTI).is_none() {
            let cti = generate_random_hex(16);
            claims.set_cwt_id(cti.as_bytes());
        }

        Ok(claims)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::util::current_time_secs;
    use std::collections::HashMap;

    fn create_test_cat() -> Cat {
        let key = hex::decode("403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388")
            .unwrap();
        let mut keys = HashMap::new();
        keys.insert("Symmetric256".to_string(), key);

        let cat_options = CatOptions {
            keys,
            expect_cwt_tag: true,
        };

        Cat::new(cat_options)
    }

    #[test]
    fn test_generate_and_validate() {
        let cat = create_test_cat();

        // Create claims
        let mut claims = Claims::new();
        claims.set_issuer("eyevinn");
        claims.set_subject("jonas");
        claims.set_audience("one");

        let now = current_time_secs();
        claims.set_expiration(now + 120);
        claims.set_issued_at(now);

        // Generate token
        let generate_options = CatGenerateOptions {
            validation_type: CatValidationType::Mac,
            alg: "HS256".to_string(),
            kid: "Symmetric256".to_string(),
            generate_cwt_id: true,
        };

        let token = cat.generate(claims, &generate_options).unwrap();

        // Validate token
        let validation_options = CatValidationOptions {
            issuer: "eyevinn".to_string(),
            audience: None,
        };

        let validated_claims = cat
            .validate(&token, CatValidationType::Mac, &validation_options)
            .unwrap();

        assert_eq!(validated_claims.get_issuer().unwrap(), "eyevinn");
        assert_eq!(validated_claims.get_subject().unwrap(), "jonas");
        assert_eq!(validated_claims.get_audience().unwrap(), vec!["one"]);
        assert!(validated_claims.get_cwt_id().is_some());
    }

    #[test]
    fn test_generate_from_json() {
        let cat = create_test_cat();

        let now = current_time_secs();
        let json_claims = json!({
            "iss": "eyevinn",
            "sub": "jonas",
            "aud": "one",
            "exp": now + 120,
            "iat": now
        });

        // Generate token
        let generate_options = CatGenerateOptions {
            validation_type: CatValidationType::Mac,
            alg: "HS256".to_string(),
            kid: "Symmetric256".to_string(),
            generate_cwt_id: true,
        };

        let token = cat
            .generate_from_json(json_claims, &generate_options)
            .unwrap();

        // Validate token
        let validation_options = CatValidationOptions {
            issuer: "eyevinn".to_string(),
            audience: None,
        };

        let validated_claims = cat
            .validate(&token, CatValidationType::Mac, &validation_options)
            .unwrap();

        assert_eq!(validated_claims.get_issuer().unwrap(), "eyevinn");
        assert_eq!(validated_claims.get_subject().unwrap(), "jonas");
        assert_eq!(validated_claims.get_audience().unwrap(), vec!["one"]);
    }

    #[test]
    fn test_token_expiration() {
        let cat = create_test_cat();

        // Create claims with expired token
        let mut claims = Claims::new();
        claims.set_issuer("eyevinn");
        claims.set_expiration(current_time_secs() - 60); // 1 minute in the past

        // Generate token
        let generate_options = CatGenerateOptions {
            validation_type: CatValidationType::Mac,
            alg: "HS256".to_string(),
            kid: "Symmetric256".to_string(),
            generate_cwt_id: false,
        };

        let token = cat.generate(claims, &generate_options).unwrap();

        // Validate token
        let validation_options = CatValidationOptions {
            issuer: "eyevinn".to_string(),
            audience: None,
        };

        let result = cat.validate(&token, CatValidationType::Mac, &validation_options);
        assert!(result.is_err());

        match result {
            Err(Error::TokenExpired) => {} // Expected error
            _ => panic!("Expected TokenExpired error"),
        }
    }

    #[test]
    fn test_invalid_issuer() {
        let cat = create_test_cat();

        // Create claims
        let mut claims = Claims::new();
        claims.set_issuer("eyevinn");
        claims.set_expiration(current_time_secs() + 120);

        // Generate token
        let generate_options = CatGenerateOptions {
            validation_type: CatValidationType::Mac,
            alg: "HS256".to_string(),
            kid: "Symmetric256".to_string(),
            generate_cwt_id: false,
        };

        let token = cat.generate(claims, &generate_options).unwrap();

        // Validate token with wrong issuer
        let validation_options = CatValidationOptions {
            issuer: "wrong-issuer".to_string(),
            audience: None,
        };

        let result = cat.validate(&token, CatValidationType::Mac, &validation_options);
        assert!(result.is_err());

        match result {
            Err(Error::InvalidIssuer { .. }) => {} // Expected error
            _ => panic!("Expected InvalidIssuer error"),
        }
    }

    #[test]
    fn test_resign_token() {
        let cat = create_test_cat();

        // Create claims with a short expiration time
        let mut claims = Claims::new();
        claims.set_issuer("eyevinn");
        claims.set_subject("user123");

        let now = current_time_secs();
        let initial_exp = now + 60; // 1 minute from now
        claims.set_expiration(initial_exp);
        claims.set_issued_at(now);

        // Generate the initial token
        let generate_options = CatGenerateOptions {
            validation_type: CatValidationType::Mac,
            alg: "HS256".to_string(),
            kid: "Symmetric256".to_string(),
            generate_cwt_id: true,
        };

        let token = cat.generate(claims, &generate_options).unwrap();

        // Validation options for the token
        let validation_options = CatValidationOptions {
            issuer: "eyevinn".to_string(),
            audience: None,
        };

        // Verify the initial token
        let validated_claims = cat
            .validate(&token, CatValidationType::Mac, &validation_options)
            .unwrap();
        assert_eq!(validated_claims.get_expiration().unwrap(), initial_exp);

        // Re-sign the token with a longer expiration
        let new_exp = now + 3600; // 1 hour from now
        let new_token = cat
            .resign_token(&token, &validation_options, new_exp, &generate_options)
            .unwrap();

        // Verify the new token
        let new_validated_claims = cat
            .validate(&new_token, CatValidationType::Mac, &validation_options)
            .unwrap();

        // Check that the expiration time was updated
        assert_eq!(new_validated_claims.get_expiration().unwrap(), new_exp);

        // Check that other claims were preserved
        assert_eq!(new_validated_claims.get_issuer().unwrap(), "eyevinn");
        assert_eq!(new_validated_claims.get_subject().unwrap(), "user123");

        // Check that issued_at was updated
        assert!(new_validated_claims.get_issued_at().unwrap() >= now);

        // Verify that the tokens are different
        assert_ne!(token, new_token);
    }
}