promocrypt_core/

lib.rs

//! # promocrypt-core
//!
//! Core library for cryptographically secure promotional code generation.
//!
//! ## Features
//!
//! - **HMAC-SHA256 code generation** - Cryptographically secure codes
//! - **Damm check digit** - 100% detection of single errors and transpositions
//! - **Two-key encryption** - MachineID for read, secret for write
//! - **Machine binding** - .bin files can be bound to specific machines
//! - **Multiple counter modes** - File, in-bin, manual, or external
//! - **FFI ready** - C-compatible interface for other languages
//!
//! ## Quick Start
//!
//! ```no_run
//! use promocrypt_core::{BinFile, BinConfig, CounterMode, create_config};
//!
//! // Create a new .bin file
//! let mut config = create_config("production");
//! config.counter_mode = CounterMode::InBin;
//!
//! let mut bin = BinFile::create("production.bin", "my-secret", config).unwrap();
//!
//! // Generate codes
//! let codes = bin.generate_batch(1000).unwrap();
//!
//! // Validate codes
//! for code in &codes {
//!     assert!(bin.is_valid(code));
//! }
//! ```
//!
//! ## Two-Key System
//!
//! Each .bin file uses a two-key encryption system:
//!
//! - **MachineID**: Derived from hardware identifiers, allows read-only access
//!   (validation, reading config)
//! - **Secret**: User-provided password, allows full access (generation,
//!   mastering, configuration changes)
//!
//! ```no_run
//! use promocrypt_core::BinFile;
//!
//! // Open read-only with machineID (automatic)
//! let bin = BinFile::open_readonly("production.bin").unwrap();
//! assert!(bin.validate("SOMECODE").is_valid() || !bin.validate("SOMECODE").is_valid());
//!
//! // Open with full access using secret
//! let mut bin = BinFile::open_with_secret("production.bin", "my-secret").unwrap();
//! let code = bin.generate().unwrap();
//! ```
//!
//! ## Counter Modes
//!
//! - `CounterMode::File { path }` - Counter in separate file with OS locking
//! - `CounterMode::InBin` - Counter in .bin mutable section
//! - `CounterMode::External` - Caller provides counter values
//! - `CounterMode::External` - Consumer manages counter (e.g., database)

#![warn(missing_docs)]
#![warn(clippy::all)]

pub mod alphabet;
pub mod audit;
pub mod binary_file;
pub mod counter;
pub mod damm;
pub mod encryption;
pub mod error;
pub mod generator;
pub mod machine_id;
pub mod validator;

#[cfg(feature = "ffi")]
pub mod ffi;

// Re-exports for convenience
pub use alphabet::{Alphabet, DEFAULT_ALPHABET, default_alphabet, validate_alphabet};
pub use audit::{
    AuditInfo, ConfigChange, GenerationLogEntry, History, MachineMastering, SecretRotation,
};
pub use binary_file::{AccessLevel, BinConfig, BinFile, BinStats, create_config};
pub use counter::CounterMode;
pub use damm::DammTable;
pub use error::{ErrorCode, PromocryptError, Result, ValidationResult};
pub use generator::{CheckPosition, CodeFormat, CodeGenerator, generate_batch, generate_code};
pub use machine_id::{get_machine_id, is_machine_id_available};
pub use validator::{is_valid, validate};

/// Library version.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// Validate a code without opening a .bin file.
///
/// This is useful for quick validation with known parameters.
///
/// # Arguments
/// * `code` - The code to validate
/// * `alphabet_str` - Alphabet string
/// * `code_length` - Expected code length (including check digit)
///
/// # Example
///
/// ```
/// use promocrypt_core::{validate_code, ValidationResult};
///
/// let result = validate_code("ABCDEFGHIJ", "0234679ABCDEFGHJKMNPQRTUXY", 10);
/// // result is ValidationResult::Valid or indicates the error
/// ```
pub fn validate_code(code: &str, alphabet_str: &str, code_length: usize) -> ValidationResult {
    let alphabet = match Alphabet::new(alphabet_str) {
        Ok(a) => a,
        Err(_) => return ValidationResult::InvalidCheckDigit, // Invalid alphabet
    };

    let damm = DammTable::new(alphabet.len());
    validate(code, &alphabet, code_length, &damm)
}

/// Generate a code with standalone parameters.
///
/// This is useful for testing or one-off generation without a .bin file.
///
/// # Arguments
/// * `secret_key` - 32-byte secret key
/// * `counter` - Counter value
/// * `alphabet_str` - Alphabet string (default if None)
/// * `code_length` - Number of random characters (9 default)
/// * `check_position` - Check digit position (End default)
///
/// # Example
///
/// ```
/// use promocrypt_core::{generate_code_standalone, CheckPosition};
///
/// let secret = [0u8; 32];
/// let code = generate_code_standalone(&secret, 0, None, None, None);
/// assert_eq!(code.len(), 10);
/// ```
pub fn generate_code_standalone(
    secret_key: &[u8; 32],
    counter: u64,
    alphabet_str: Option<&str>,
    code_length: Option<usize>,
    check_position: Option<CheckPosition>,
) -> String {
    let alphabet = alphabet_str
        .map(|s| Alphabet::new(s).unwrap_or_default())
        .unwrap_or_default();
    let damm = DammTable::new(alphabet.len());
    let length = code_length.unwrap_or(9);
    let position = check_position.unwrap_or(CheckPosition::End);

    generate_code(secret_key, counter, &alphabet, length, position, &damm)
}

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

    #[test]
    fn test_version() {
        assert!(!VERSION.is_empty());
    }

    #[test]
    fn test_validate_code_standalone() {
        let secret = [42u8; 32];
        let code = generate_code_standalone(&secret, 0, None, None, None);

        let result = validate_code(&code, DEFAULT_ALPHABET, 10);
        assert!(result.is_valid());
    }

    #[test]
    fn test_validate_code_invalid() {
        let result = validate_code("INVALID!", DEFAULT_ALPHABET, 10);
        assert!(!result.is_valid());
    }

    #[test]
    fn test_generate_standalone() {
        let secret = [0u8; 32];

        // Default parameters
        let code = generate_code_standalone(&secret, 0, None, None, None);
        assert_eq!(code.len(), 10);

        // Custom parameters
        let code = generate_code_standalone(
            &secret,
            0,
            Some("0123456789ABCDEF"),
            Some(8),
            Some(CheckPosition::Start),
        );
        assert_eq!(code.len(), 9);
    }

    #[test]
    fn test_reexports() {
        // Just verify these are accessible
        let _ = DEFAULT_ALPHABET;
        let _ = Alphabet::default_alphabet();
        let _ = DammTable::new(26);
        let _ = CheckPosition::End;
        let _ = CounterMode::External;
        let _ = AccessLevel::ReadOnly;
        let _ = ErrorCode::Success;
    }
}