librnxengine 1.1.0

/// # librnxengine - Comprehensive License Management System for Rust Applications
///
/// A robust, production-ready library for implementing license management,
/// activation, validation, and cryptographic signing in Rust applications.
/// Provides both client-side and server-side components for building
/// complete license management solutions.
///
/// ## Key Features
///
/// - **Cryptographic Security**: Ed25519 digital signatures for license integrity
/// - **Hardware Binding**: Unique device fingerprints to prevent license sharing
/// - **Offline/Online Validation**: Flexible validation modes for different deployment scenarios
/// - **Grace Periods**: Configurable grace periods for license renewals
/// - **Revocation Support**: Server-side license revocation capabilities
/// - **Multi-Platform**: Works on Windows, macOS, and Linux
/// - **Async Ready**: Built with async/await for modern Rust applications
///
/// ## Quick Start
///
/// ```rust
/// use librnxengine::*;
/// use uuid::Uuid;
/// use chrono::{Utc, Duration};
///
/// #[tokio::main]
/// async fn main() -> Result<(), LicenseError> {
///     // 1. Initialize the license engine
///     let engine = LicenseEngine::new(LicenseConfig::default());
///
///     // 2. Generate cryptographic keys
///     let keypair = engine.generate_keypair()?;
///
///     // 3. Create a license
///     let payload = LicensePayload {
///         license_id: Uuid::new_v4(),
///         customer_id: "customer-123".to_string(),
///         product_id: "myapp-pro".to_string(),
///         expires_at: Utc::now() + Duration::days(365),
///         issued_at: Utc::now(),
///         max_activations: 3,
///         features: vec!["premium".to_string(), "api-access".to_string()],
///         metadata: serde_json::json!({}),
///     };
///
///     let license = engine.create_license(&keypair, payload)?;
///
///     // 4. Verify the license
///     let result = engine.verify_license(&keypair.public, &license)?;
///
///     if result.is_valid() {
///         println!("License is valid!");
///         println!("Features: {:?}", result.features);
///         println!("Days remaining: {:?}", result.days_remaining);
///     }
///
///     Ok(())
/// }
/// ```
///
/// ## Module Structure
///
/// The library is organized into the following modules, each with a specific purpose:
///
/// - **`activation`**: Activation request/response structures for license-server communication
/// - **`client`**: HTTP client for remote license server operations (activation, validation, revocation)
/// - **`crypto`**: Cryptographic primitives (Ed25519 key generation, signing, verification)
/// - **`engine`**: Core license engine for creation, validation, and management
/// - **`error``: Comprehensive error types for all license operations
/// - **`hardware`**: Hardware fingerprint generation for device binding
/// - **`license`**: License data structures and serialization
/// - **`validation``: Validation logic and result reporting
///
/// ## Architecture Overview
///
/// ```text
/// ┌─────────────────────────────────────────────────────────────┐
/// │                    Application Layer                        │
/// │  Uses: LicenseEngine, LicenseClient, HardwareFingerprint    │
/// └─────────────────┬───────────────────────────────────────────┘
///                   │
/// ┌─────────────────▼───────────────────────────────────────────┐
/// │                  Core Service Layer                         │
/// │  Provides: License creation, validation, crypto operations  │
/// └─────────────────┬───────────────────────────────────────────┘
///                   │
/// ┌─────────────────▼───────────────────────────────────────────┐
/// │                Infrastructure Layer                         │
/// │  Handles: HTTP communication, hardware info, serialization  │
/// └─────────────────────────────────────────────────────────────┘
/// ```
///
/// ## Usage Patterns
///
/// ### 1. Software Vendor (License Issuance)
///
/// ```rust
/// // Generate keys once and store securely
/// let keypair = KeyPair::generate();
/// keypair.save_to_file("public_key.json")?;
///
/// // Create licenses for customers
/// let license = engine.create_license(&keypair, customer_payload)?;
/// let license_json = engine.license_to_json(&license)?;
///
/// // Distribute license.json to customer
/// ```
///
/// ### 2. End User Application (License Validation)
///
/// ```rust
/// // Load public key provided by vendor
/// let public_key = KeyPair::load_public_from_file("vendor_public_key.json")?;
///
/// // Load user's license
/// let license_json = std::fs::read_to_string("license.json")?;
/// let license = engine.license_from_json(&license_json)?;
///
/// // Validate license
/// let result = engine.verify_license(&public_key, &license)?;
///
/// // Check features
/// if license.has_feature("premium") {
///     enable_premium_features();
/// }
/// ```
///
/// ### 3. Online Activation Flow
///
/// ```rust
/// // Generate hardware fingerprint
/// let fingerprint = HardwareFingerprint::generate()?;
///
/// // Create activation request
/// let request = ActivationRequest {
///     license_id: license.license_id(),
///     hardware_fingerprint: fingerprint,
///     machine_name: get_hostname(),
///     timestamp: Utc::now(),
///     nonce: Uuid::new_v4().to_string(),
///     ..Default::default()
/// };
///
/// // Send to license server
/// let client = LicenseClient::new("https://license.example.com");
/// let response = client.activate_license(&request).await?;
///
/// // Store activation token securely
/// save_activation_token(response.activation_token);
/// ```
///
/// ## Security Considerations
///
/// ### Private Key Security
/// - **NEVER** embed private keys in client applications
/// - Use hardware security modules (HSMs) for production private key storage
/// - Implement key rotation policies
/// - Monitor for unauthorized key usage
///
/// ### License Validation
/// - Always verify cryptographic signatures before trusting license data
/// - Implement revocation checks for sensitive applications
/// - Use hardware binding to prevent license sharing
/// - Consider implementing tamper detection mechanisms
///
/// ### Network Security
/// - Use HTTPS for all license server communications
/// - Implement rate limiting to prevent brute force attacks
/// - Use secure token storage on client devices
/// - Implement proper session management
///
/// ## Performance Characteristics
///
/// - **License Verification**: ~0.1ms (Ed25519 verification is very fast)
/// - **Hardware Fingerprint Generation**: ~5-50ms (depends on system)
/// - **Network Operations**: Varies (typically 100-500ms for server calls)
/// - **Memory Usage**: Minimal (structures are small and efficient)
///
/// ## Error Handling
///
/// All operations return `Result<T, LicenseError>` with comprehensive error types:
///
/// ```rust
/// match engine.verify_license(&public_key, &license) {
///     Ok(result) => {
///         if !result.is_valid() {
///             // Handle validation warnings/violations
///             for violation in result.violations {
///                 eprintln!("Violation: {}", violation);
///             }
///         }
///     }
///     Err(LicenseError::SignatureValidationFailed) => {
///         // Handle tampered license
///         show_error("License has been tampered with!");
///     }
///     Err(LicenseError::LicenseExpired) => {
///         // Handle expired license
///         prompt_for_renewal();
///     }
///     Err(e) => {
///         // Handle other errors
///         eprintln!("License error: {}", e);
///     }
/// }
/// ```
///
/// ## Configuration Examples
///
/// ### Strict Validation (Security-Focused)
///
/// ```rust
/// let strict_config = LicenseConfig {
///     allow_offline: false,          // Require online validation
///     grace_period_days: 0,          // No grace period
///     max_clock_skew_seconds: 60,    // Strict time sync requirement
///     require_hardware_binding: true, // Enforce hardware binding
///     enable_revocation_check: true, // Check revocation status
/// };
/// ```
///
/// ### Flexible Validation (User-Friendly)
///
/// ```rust
/// let flexible_config = LicenseConfig {
///     allow_offline: true,           // Allow offline use
///     grace_period_days: 30,         // 30-day grace period
///     max_clock_skew_seconds: 3600,  // 1-hour clock skew tolerance
///     require_hardware_binding: false, // No hardware binding
///     enable_revocation_check: false, // No revocation checks
/// };
/// ```
///
/// ## Integration Examples
///
/// ### Desktop Application
///
/// ```rust
/// // Check license on application startup
/// fn check_license() -> Result<(), LicenseError> {
///     let engine = LicenseEngine::new(LicenseConfig::default());
///     let public_key = load_vendor_public_key();
///     let license = load_user_license();
///
///     let result = engine.verify_license(&public_key, &license)?;
///
///     if !result.is_valid() {
///         return Err(LicenseError::ValidationFailed(
///             result.violations.join(", ")
///         ));
///     }
///
///     Ok(())
/// }
/// ```
///
/// ### Web Service Backend
///
/// ```rust
/// // Validate license for API requests
/// async fn validate_api_license(
///     license_id: Uuid,
///     activation_token: &str,
/// ) -> Result<License, LicenseError> {
///     let client = LicenseClient::new(env::var("LICENSE_SERVER_URL")?);
///     let license = client.validate_license(&license_id, activation_token).await?;
///
///     if license.is_expired() {
///         return Err(LicenseError::LicenseExpired);
///     }
///
///     Ok(license)
/// }
/// ```
///
/// ### Command Line Tool
///
/// ```rust
/// // License activation command
/// #[derive(clap::Parser)]
/// struct ActivateCommand {
///     #[arg(short, long)]
///     license_key: String,
/// }
///
/// impl ActivateCommand {
///     async fn execute(&self) -> Result<(), LicenseError> {
///         let fingerprint = HardwareFingerprint::generate()?;
///         let request = create_activation_request(&self.license_key, fingerprint)?;
///
///         let client = LicenseClient::new("https://license.example.com");
///         let response = client.activate_license(&request).await?;
///
///         save_activation_response(response);
///         println!("License activated successfully!");
///
///         Ok(())
///     }
/// }
/// ```
///
/// ## Testing
///
/// The library includes comprehensive test utilities. Example test:
///
/// ```rust
/// #[cfg(test)]
/// mod tests {
///     use super::*;
///
///     #[test]
///     fn test_license_creation_and_verification() {
///         let engine = LicenseEngine::new(LicenseConfig::default());
///         let keypair = engine.generate_keypair().unwrap();
///
///         let payload = LicensePayload {
///             license_id: Uuid::new_v4(),
///             customer_id: "test".to_string(),
///             product_id: "test".to_string(),
///             expires_at: Utc::now() + Duration::days(1),
///             issued_at: Utc::now(),
///             max_activations: 1,
///             features: vec!["test-feature".to_string()],
///             metadata: serde_json::json!({}),
///         };
///
///         let license = engine.create_license(&keypair, payload).unwrap();
///         let result = engine.verify_license(&keypair.public, &license).unwrap();
///
///         assert!(result.is_valid());
///         assert!(license.has_feature("test-feature"));
///     }
/// }
/// ```
///
/// ## Dependencies
///
/// Key dependencies and their purposes:
///
/// - `chrono`: Date and time handling for license expiration
/// - `ed25519-dalek`: Ed25519 cryptographic signatures
/// - `reqwest`: HTTP client for license server communication
/// - `serde`: Serialization/deserialization for license data
/// - `thiserror`: Comprehensive error types
/// - `tracing`: Structured logging for debugging and monitoring
/// - `uuid`: Unique identifier generation
/// - `zeroize`: Secure memory zeroing for cryptographic keys
///
/// ## Platform Support
///
/// | Platform | Hardware Fingerprint | Notes |
/// |----------|---------------------|-------|
/// | Windows 10/11 | ✓ | Uses WMI for hardware information |
/// | macOS 10.15+ | ✓ | Uses system_profiler and ioreg |
/// | Linux (glibc) | ✓ | Uses /proc and /sys filesystems |
/// | Linux (musl) | ✓ | Alpine Linux supported |
/// | WebAssembly | ✗ | Hardware fingerprint not available |
/// | Android/iOS | ⚠️ | Limited hardware information |
///
/// ## Contributing
///
/// 1. Fork the repository
/// 2. Create a feature branch
/// 3. Add tests for new functionality
/// 4. Ensure all tests pass: `cargo test`
/// 5. Run clippy: `cargo clippy -- -D warnings`
/// 6. Format code: `cargo fmt`
/// 7. Submit a pull request
///
/// ## License
///
/// This library is dual-licensed under:
///
/// - Apache License, Version 2.0
/// - MIT License
///
/// See LICENSE-APACHE and LICENSE-MIT for details.
///
/// ## Support
///
/// - **Documentation**: [docs.rs/librnxengine](https://docs.rs/librnxengine)
/// - **Issues**: [GitHub Issues](https://github.com/neuxdotdev/librnxengine/issues)
/// - **Discussions**: [GitHub Discussions](https://github.com/neuxdotdev/librnxengine/discussions)
/// - **Security Issues**: security@neuxdotdev.my.id
///
/// ## Versioning
///
/// Follows [Semantic Versioning 2.0.0](https://semver.org/):
///
/// - **MAJOR**: Incompatible API changes
/// - **MINOR**: Backward-compatible new functionality
/// - **PATCH**: Backward-compatible bug fixes
///
/// ## Acknowledgments
///
/// - The Rust Crypto team for excellent cryptographic primitives
/// - The Tokio team for async runtime foundations
/// - All contributors and users of the library
///
/// ## See Also
///
/// - [crates.io/crates/librnxengine](https://crates.io/crates/librnxengine)
/// - [API Reference](https://docs.rs/librnxengine/latest/librnxengine/)
/// - [Examples](https://github.com/neuxdotdev/librnxengine/tree/main/examples)
/// - [Changelog](https://github.com/neuxdotdev/librnxengine/blob/main/CHANGELOG.md)
///

// ============================================================================
// Module Declarations
// ============================================================================

/// License activation structures and server communication protocols.
///
/// Contains request/response types for license activation flows including
/// hardware binding, token management, and activation records.
pub mod activation;

/// HTTP client for remote license server operations.
///
/// Provides async methods for license activation, validation, and revocation
/// checking against a remote license management server.
pub mod client;

/// Cryptographic primitives for license signing and verification.
///
/// Implements Ed25519 key generation, signing, verification, and secure
/// key management with automatic memory zeroization.
pub mod crypto;

/// Core license engine for creation, validation, and management.
///
/// Main entry point for license operations. Handles cryptographic signing,
/// content validation, serialization, and configuration-based validation rules.
pub mod engine;

/// Comprehensive error types for all license operations.
///
/// Defines detailed error variants for cryptographic failures, validation
/// errors, network issues, and license-specific error conditions.
pub mod error;

/// Hardware fingerprint generation for device identification.
///
/// Platform-specific hardware information collection and unique fingerprint
/// generation for license binding and anti-piracy measures.
pub mod hardware;

/// License data structures and serialization formats.
///
/// Core license data types including payloads, complete licenses, and
/// structured feature definitions with serialization support.
pub mod license;

/// Validation logic and result reporting.
///
/// Lightweight validation components for runtime license checking with
/// configurable validation rules and detailed result reporting.
pub mod validation;

// ============================================================================
// Re-exports for Convenient Library Usage
// ============================================================================

/// Re-exports activation request and response types.
///
/// Use these types to communicate with license servers for activation flows.
pub use crate::activation::{ActivationRequest, ActivationResponse};

/// Re-exports the HTTP client for remote license operations.
///
/// Use `LicenseClient` to interact with license management servers over HTTP.
pub use crate::client::LicenseClient;

/// Re-exports cryptographic key pair structure.
///
/// Use `KeyPair` for generating and managing cryptographic keys for
/// license signing and verification.
pub use crate::crypto::KeyPair;

/// Re-exports the core license engine.
///
/// Use `LicenseEngine` as the primary interface for license creation,
/// validation, and management operations.
pub use crate::engine::LicenseEngine;

/// Re-exports comprehensive error enumeration.
///
/// Use `LicenseError` for error handling across all license operations.
pub use crate::error::LicenseError;

/// Re-exports hardware fingerprint generator.
///
/// Use `HardwareFingerprint` to generate unique device identifiers for
/// license binding and activation.
pub use crate::hardware::HardwareFingerprint;

/// Re-exports license data structures.
///
/// Use `License`, `LicenseFeatures`, and `LicensePayload` to work with
/// license data at different levels of abstraction.
pub use crate::license::{License, LicenseFeatures, LicensePayload};

/// Re-exports validation components.
///
/// Use `LicenseValidator` and `ValidationResult` for runtime license
/// validation with configurable rules and detailed reporting.
pub use crate::validation::{LicenseValidator, ValidationResult};

/// Re-exports chrono types for convenient date/time handling.
///
/// Provides `DateTime<Utc>` for working with timestamps in license operations.
pub use chrono::{DateTime, Utc};

/// Re-exports UUID type for identifier generation.
///
/// Provides `Uuid` for generating and working with unique identifiers
/// in license systems.
pub use uuid::Uuid;

// ============================================================================
// Library-Level Configuration and Constants
// ============================================================================

/// Current version of the librnxengine library.
///
/// Follows semantic versioning (MAJOR.MINOR.PATCH). This constant is used
/// internally and can be used by dependents to check library version.
pub const LIBRARY_VERSION: &str = env!("CARGO_PKG_VERSION");

/// Minimum supported Rust version (MSRV).
///
/// The library guarantees compatibility with this Rust version and newer.
/// Breaking changes to MSRV will result in a MAJOR version bump.
pub const MSRV: &str = "1.70.0";

/// Default license file extension.
///
/// The recommended file extension for license files saved to disk.
pub const DEFAULT_LICENSE_EXTENSION: &str = ".license.json";

/// Default public key file extension.
///
/// The recommended file extension for public key files saved to disk.
pub const DEFAULT_PUBKEY_EXTENSION: &str = ".pubkey.json";

/// Maximum license size in bytes.
///
/// Licenses larger than this will be rejected to prevent denial of service
/// attacks via extremely large license files.
pub const MAX_LICENSE_SIZE: usize = 1024 * 1024; // 1 MB

/// Supported signature algorithms.
///
/// List of cryptographic algorithms supported for license signing.
/// Currently only Ed25519 is supported, but this may expand in future versions.
pub const SUPPORTED_ALGORITHMS: &[&str] = &["ed25519"];

/// Default license server API path prefix.
///
/// The standard API path prefix used by license servers. Used internally
/// by `LicenseClient` when constructing URLs.
pub const DEFAULT_API_PATH_PREFIX: &str = "/api/v1/licenses";

// ============================================================================
// Pre-defined License Configurations
// ============================================================================

/// Returns a strict license configuration for high-security applications.
///
/// This configuration enforces:
/// - Online validation only (no offline mode)
/// - No grace period (immediate expiration enforcement)
/// - Strict clock synchronization requirements
/// - Hardware binding enforcement
/// - Revocation checking enabled
///
/// # Example
/// ```rust
/// use librnxengine::engine::LicenseConfig;
///
/// let config = strict_license_config();
/// let engine = LicenseEngine::new(config);
/// ```
pub fn strict_license_config() -> crate::engine::LicenseConfig {
    crate::engine::LicenseConfig {
        allow_offline: false,
        grace_period_days: 0,
        max_clock_skew_seconds: 60,
        require_hardware_binding: true,
        enable_revocation_check: true,
    }
}

/// Returns a flexible license configuration for user-friendly applications.
///
/// This configuration provides:
/// - Offline validation allowed
/// - Generous grace period for renewals
/// - Lenient clock synchronization
/// - Optional hardware binding
/// - Basic revocation checking
///
/// # Example
/// ```rust
/// use librnxengine::engine::LicenseConfig;
///
/// let config = flexible_license_config();
/// let engine = LicenseEngine::new(config);
/// ```
pub fn flexible_license_config() -> crate::engine::LicenseConfig {
    crate::engine::LicenseConfig {
        allow_offline: true,
        grace_period_days: 30,
        max_clock_skew_seconds: 3600,
        require_hardware_binding: false,
        enable_revocation_check: true,
    }
}

/// Returns a development/testing license configuration.
///
/// This configuration is suitable for development and testing:
/// - Allows all validation modes
/// - Extended grace periods
/// - Very lenient clock requirements
/// - No hardware binding
/// - No revocation checks
///
/// # Warning
/// Do not use this configuration in production!
///
/// # Example
/// ```rust
/// use librnxengine::engine::LicenseConfig;
///
/// let config = development_license_config();
/// let engine = LicenseEngine::new(config);
/// ```
pub fn development_license_config() -> crate::engine::LicenseConfig {
    crate::engine::LicenseConfig {
        allow_offline: true,
        grace_period_days: 365,
        max_clock_skew_seconds: 86400,
        require_hardware_binding: false,
        enable_revocation_check: false,
    }
}

// ============================================================================
// Convenience Functions
// ============================================================================

/// Creates a new license engine with default configuration.
///
/// Shortcut for `LicenseEngine::new(LicenseConfig::default())`.
///
/// # Returns
/// A new `LicenseEngine` instance with sensible default settings.
///
/// # Example
/// ```rust
/// use librnxengine::new_license_engine;
///
/// let engine = new_license_engine();
/// ```
pub fn new_license_engine() -> LicenseEngine {
    LicenseEngine::new(crate::engine::LicenseConfig::default())
}

/// Creates a new license client with the specified base URL.
///
/// Shortcut for `LicenseClient::new(base_url)`.
///
/// # Parameters
/// - `base_url`: Base URL of the license management server
///
/// # Returns
/// A new `LicenseClient` instance configured for the specified server.
///
/// # Example
/// ```rust
/// use librnxengine::new_license_client;
///
/// let client = new_license_client("https://license.example.com");
/// ```
pub fn new_license_client(base_url: &str) -> LicenseClient {
    LicenseClient::new(base_url)
}

/// Generates a new cryptographic key pair.
///
/// Shortcut for creating a key pair with secure random generation.
/// Uses the operating system's cryptographically secure random number generator.
///
/// # Returns
/// A new `KeyPair` suitable for license signing and verification.
///
/// # Example
/// ```rust
/// use librnxengine::generate_keypair;
///
/// let keypair = generate_keypair()?;
/// ```
pub fn generate_keypair() -> Result<KeyPair, LicenseError> {
    let engine = new_license_engine();
    engine.generate_keypair()
}

/// Validates that a license string is properly formatted.
///
/// Performs basic validation on a license JSON string without full
/// cryptographic verification. Useful for quick sanity checks.
///
/// # Parameters
/// - `license_json`: JSON string containing license data
///
/// # Returns
/// - `Ok(())`: License is properly formatted
/// - `Err(LicenseError)`: License has formatting issues
///
/// # Example
/// ```rust
/// use librnxengine::validate_license_format;
///
/// let license_json = std::fs::read_to_string("license.json")?;
/// validate_license_format(&license_json)?;
/// ```
pub fn validate_license_format(license_json: &str) -> Result<(), LicenseError> {
    let engine = new_license_engine();
    // Try to parse the license
    let _ = engine.license_from_json(license_json)?;
    Ok(())
}

/// Checks if the current system supports hardware fingerprint generation.
///
/// Tests whether the hardware fingerprint generation will work on the
/// current platform and configuration. Useful for feature detection.
///
/// # Returns
/// - `true`: Hardware fingerprint generation is supported
/// - `false`: Hardware fingerprint generation is not available
///
/// # Example
/// ```rust
/// use librnxengine::is_hardware_fingerprint_supported;
///
/// if is_hardware_fingerprint_supported() {
///     println!("Hardware binding is available");
/// } else {
///     println!("Hardware binding is not supported on this system");
/// }
/// ```
pub fn is_hardware_fingerprint_supported() -> bool {
    // Quick platform detection
    cfg!(any(
        target_os = "windows",
        target_os = "linux",
        target_os = "macos"
    ))
}

// ============================================================================
// Integration Helpers
// ============================================================================

/// Trait for applications to implement custom license storage.
///
/// Implement this trait to provide custom license storage mechanisms
/// (e.g., encrypted files, secure enclaves, cloud storage).
///
/// # Example
/// ```rust
/// use librnxengine::{LicenseStorage, License, LicenseError};
///
/// struct EncryptedFileStorage {
///     path: std::path::PathBuf,
///     encryption_key: [u8; 32],
/// }
///
/// impl LicenseStorage for EncryptedFileStorage {
///     fn save_license(&self, license: &License) -> Result<(), LicenseError> {
///         // Custom encryption logic here
///         Ok(())
///     }
///
///     fn load_license(&self) -> Result<License, LicenseError> {
///         // Custom decryption logic here
///         todo!()
///     }
/// }
/// ```
pub trait LicenseStorage {
    /// Saves a license to the custom storage backend.
    fn save_license(&self, license: &License) -> Result<(), LicenseError>;

    /// Loads a license from the custom storage backend.
    fn load_license(&self) -> Result<License, LicenseError>;

    /// Checks if a license exists in the storage backend.
    fn license_exists(&self) -> bool;

    /// Removes a license from the storage backend.
    fn delete_license(&self) -> Result<(), LicenseError>;
}

/// Trait for applications to implement custom license validation hooks.
///
/// Implement this trait to add custom validation logic beyond the
/// standard license validation (e.g., business rules, external checks).
///
/// # Example
/// ```rust
/// use librnxengine::{LicenseValidationHook, License, ValidationResult};
///
/// struct UsageLimitHook {
///     max_usage_hours: u32,
///     usage_tracker: UsageTracker,
/// }
///
/// impl LicenseValidationHook for UsageLimitHook {
///     fn validate(&self, license: &License, base_result: &mut ValidationResult) {
///         let usage_hours = self.usage_tracker.get_usage_hours();
///         if usage_hours > self.max_usage_hours {
///             base_result.add_violation(
///                 format!("Usage limit exceeded: {}/{} hours",
///                         usage_hours, self.max_usage_hours)
///             );
///         }
///     }
/// }
/// ```
pub trait LicenseValidationHook {
    /// Performs custom validation logic.
    ///
    /// # Parameters
    /// - `license`: The license being validated
    /// - `base_result`: The validation result to modify with custom violations/warnings
    fn validate(&self, license: &License, base_result: &mut ValidationResult);
}

// ============================================================================
// Type Aliases for Common Use Cases
// ============================================================================

/// Alias for license ID type for cleaner code.
///
/// Use `LicenseId` instead of `Uuid` when referring to license identifiers
/// for better code clarity and future-proofing.
pub type LicenseId = Uuid;

/// Alias for activation token type.
///
/// Use `ActivationToken` for strings that contain JWT or similar activation tokens.
pub type ActivationToken = String;

/// Alias for hardware fingerprint type.
///
/// Use `HardwareFingerprintString` for strings that contain hardware fingerprints.
pub type HardwareFingerprintString = String;

/// Alias for feature list type.
///
/// Use `FeatureList` for vectors containing license feature names.
pub type FeatureList = Vec<String>;

/// Alias for license metadata type.
///
/// Use `LicenseMetadata` for JSON values containing license metadata.
pub type LicenseMetadata = serde_json::Value;

// ============================================================================
// Deprecation Notices and Compatibility
// ============================================================================

// Note: The following items are kept for backward compatibility.
// They will be removed in a future major version.

#[doc(hidden)]
#[deprecated(since = "0.3.0", note = "Use `LicenseEngine` instead")]
pub type LicenseManager = LicenseEngine;

#[doc(hidden)]
#[deprecated(since = "0.3.0", note = "Use `validate_license_format` instead")]
pub fn check_license_syntax(license_json: &str) -> Result<(), LicenseError> {
    validate_license_format(license_json)
}

// ============================================================================
// Unit Tests (Example)
// ============================================================================

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

    /// Tests that the library version constant is properly set.
    #[test]
    fn test_library_version() {
        assert!(!LIBRARY_VERSION.is_empty());
        // Version should be in semver format
        let parts: Vec<&str> = LIBRARY_VERSION.split('.').collect();
        assert_eq!(parts.len(), 3);
    }

    /// Tests that hardware fingerprint support detection works.
    #[test]
    fn test_hardware_support_detection() {
        let supported = is_hardware_fingerprint_supported();
        // This should be true on supported platforms
        // The test doesn't assert a specific value since it varies by platform
        println!("Hardware fingerprint supported: {}", supported);
    }
}

// ============================================================================
// End of Library Definition
// ============================================================================