utilities

🛠️ UTILITY LIBRARIES BEST PRACTICES

TL;DR: Essential utility patterns for authentication, CLI tools, data structures, and common development tasks.

🔍 UTILITY LIBRARY SELECTION STRATEGY

graph TD
    Start["Utility Requirements"] --> UtilityType{"Utility<br>Category?"}

    UtilityType -->|Authentication| AuthUtils["Authentication Utilities"]
    UtilityType -->|CLI Tools| CLIUtils["CLI Utilities"]
    UtilityType -->|Data Structures| DataUtils["Data Structure Utilities"]
    UtilityType -->|Validation| ValidationUtils["Validation Utilities"]

    AuthUtils --> JWT["JWT Token Management"]
    AuthUtils --> PasswordHash["Password Hashing"]

    CLIUtils --> ClapCLI["Clap CLI Framework"]
    CLIUtils --> ProgressBars["Progress Indicators"]

    DataUtils --> TypedBuilder["TypedBuilder Pattern"]
    DataUtils --> EnumDispatch["enum_dispatch"]

    ValidationUtils --> SerdeValidation["Serde Validation"]
    ValidationUtils --> CustomValidation["Custom Validators"]

    JWT --> Security["Security Implementation"]
    PasswordHash --> Security
    ClapCLI --> UserInterface["User Interface"]
    ProgressBars --> UserInterface
    TypedBuilder --> CodeGeneration["Code Generation"]
    EnumDispatch --> CodeGeneration
    SerdeValidation --> DataIntegrity["Data Integrity"]
    CustomValidation --> DataIntegrity

    Security --> Production["Production Utilities"]
    UserInterface --> Production
    CodeGeneration --> Production
    DataIntegrity --> Production

    style Start fill:#4da6ff,stroke:#0066cc,color:white
    style AuthUtils fill:#4dbb5f,stroke:#36873f,color:white
    style CLIUtils fill:#ffa64d,stroke:#cc7a30,color:white
    style DataUtils fill:#d94dbb,stroke:#a3378a,color:white

🔐 AUTHENTICATION AND SECURITY

JWT with jsonwebtoken

# Cargo.toml - JWT configuration
[dependencies]
jsonwebtoken = "9.0"
serde = { version = "1.0", features = ["derive"] }
chrono = { version = "0.4", features = ["serde"] }

use jsonwebtoken::{decode, encode, Algorithm, DecodingKey, EncodingKey, Header, Validation};
use serde::{Deserialize, Serialize};
use chrono::{DateTime, Utc};

#[derive(Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Claims {
    pub sub: String,        // Subject (user ID)
    pub exp: i64,           // Expiration time
    pub iat: i64,           // Issued at
    pub user_role: String,  // Custom claim
    pub session_id: String, // Session identifier
}

#[derive(Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct TokenPair {
    pub access_token: String,
    pub refresh_token: String,
    pub expires_in: i64,
}

pub struct JwtService {
    encoding_key: EncodingKey,
    decoding_key: DecodingKey,
    access_token_expiry: i64,  // seconds
    refresh_token_expiry: i64, // seconds
}

impl JwtService {
    pub fn new(secret: &str) -> Self {
        Self {
            encoding_key: EncodingKey::from_secret(secret.as_bytes()),
            decoding_key: DecodingKey::from_secret(secret.as_bytes()),
            access_token_expiry: 3600,      // 1 hour
            refresh_token_expiry: 604800,   // 7 days
        }
    }

    pub fn generate_token_pair(&self, user_id: &str, role: &str) -> Result<TokenPair, JwtError> {
        let now = Utc::now().timestamp();
        let session_id = uuid::Uuid::new_v4().to_string();

        // Access token
        let access_claims = Claims {
            sub: user_id.to_string(),
            exp: now + self.access_token_expiry,
            iat: now,
            user_role: role.to_string(),
            session_id: session_id.clone(),
        };

        let access_token = encode(&Header::default(), &access_claims, &self.encoding_key)?;

        // Refresh token (longer expiry, minimal claims)
        let refresh_claims = Claims {
            sub: user_id.to_string(),
            exp: now + self.refresh_token_expiry,
            iat: now,
            user_role: "refresh".to_string(),
            session_id,
        };

        let refresh_token = encode(&Header::default(), &refresh_claims, &self.encoding_key)?;

        Ok(TokenPair {
            access_token,
            refresh_token,
            expires_in: self.access_token_expiry,
        })
    }

    pub fn validate_token(&self, token: &str) -> Result<Claims, JwtError> {
        let validation = Validation::new(Algorithm::HS256);
        let token_data = decode::<Claims>(token, &self.decoding_key, &validation)?;
        Ok(token_data.claims)
    }

    pub fn refresh_access_token(&self, refresh_token: &str) -> Result<TokenPair, JwtError> {
        let claims = self.validate_token(refresh_token)?;

        // Verify it's a refresh token
        if claims.user_role != "refresh" {
            return Err(JwtError::InvalidTokenType);
        }

        // Generate new token pair
        self.generate_token_pair(&claims.sub, "user") // Default role, should be fetched from DB
    }
}

#[derive(thiserror::Error, Debug)]
pub enum JwtError {
    #[error("JWT encoding/decoding error: {0}")]
    Token(#[from] jsonwebtoken::errors::Error),
    #[error("Invalid token type")]
    InvalidTokenType,
    #[error("Token expired")]
    Expired,
}