promocrypt_core/

binary_file.rs

//! Binary file format handling for .bin files.
//!
//! Implements the promocrypt binary file format including:
//! - Two-key encryption (machineID + secret)
//! - Machine binding
//! - Counter management
//! - Code generation and validation
//! - Storage encryption for database codes
//! - History tracking and generation logs

use std::fs::{File, OpenOptions};
use std::io::{Read, Seek, SeekFrom, Write};
use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use crate::alphabet::Alphabet;
use crate::audit::{AuditInfo, GenerationLogEntry, History};
use crate::counter::{CounterManager, CounterMode, counter_from_bytes, counter_to_bytes};
use crate::damm::DammTable;
use crate::encryption::{
    ENCRYPTED_KEY_SIZE, NONCE_SIZE, SALT_SIZE, decrypt_code_from_storage, decrypt_data,
    decrypt_data_key, encrypt_code_for_storage, encrypt_data, encrypt_data_key, generate_nonce,
    generate_random_key, generate_salt, hash_secret,
};
use crate::error::{PromocryptError, Result, ValidationResult};
use crate::generator::{CheckPosition, CodeFormat, generate_batch, generate_code};
use crate::machine_id::get_machine_id;

// File format constants
const MAGIC: &[u8; 8] = b"PROMOCRY";
const VERSION: u8 = 0x02;

// Header offsets
const OFFSET_MAGIC: usize = 0;
const OFFSET_VERSION: usize = 8;
const OFFSET_FLAGS: usize = 9;
const OFFSET_HEADER_CRC: usize = 10;
const OFFSET_SALT: usize = 14;
const OFFSET_MACHINE_NONCE: usize = 30;
const OFFSET_MACHINE_KEY: usize = 42;
const OFFSET_SECRET_NONCE: usize = 90;
const OFFSET_SECRET_KEY: usize = 102;
const OFFSET_DATA_NONCE: usize = 150;
const OFFSET_DATA_LENGTH: usize = 162;
const OFFSET_DATA: usize = 166;

// Header size (before encrypted data)
const HEADER_SIZE: usize = OFFSET_DATA;

// Flags
const FLAG_IS_BOUND: u8 = 0x01;
const FLAG_HAS_MUTABLE: u8 = 0x02;

/// Access level when opening a .bin file.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum AccessLevel {
    /// Opened with machineID - can only read and validate.
    ReadOnly,
    /// Opened with secret - full access including generation.
    FullAccess,
}

/// Configuration stored in a .bin file.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct BinConfig {
    /// Name/identifier for this configuration
    pub name: String,
    /// Alphabet for code generation
    pub alphabet: Alphabet,
    /// Number of random characters (not including check digit)
    pub code_length: usize,
    /// Position of check digit (index-based)
    pub check_position: CheckPosition,
    /// 256-bit secret key for HMAC (hex encoded)
    pub secret_key: String,
    /// 256-bit storage key for database encryption (hex encoded)
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub storage_key: String,
    /// Whether storage encryption is enabled
    #[serde(default)]
    pub storage_encryption_enabled: bool,
    /// Damm table for check digit calculation
    pub damm_table: DammTable,
    /// Counter storage mode
    pub counter_mode: CounterMode,
    /// Code formatting (prefix, suffix, separators)
    #[serde(default, skip_serializing_if = "CodeFormat::is_default")]
    pub format: CodeFormat,
    /// Audit trail
    pub audit: AuditInfo,
}

impl CodeFormat {
    /// Check if this is the default (empty) format.
    pub fn is_default(&self) -> bool {
        self.prefix.is_none()
            && self.suffix.is_none()
            && self.separator.is_none()
            && self.separator_positions.is_empty()
    }
}

impl BinConfig {
    /// Get the base code length (code_length + 1 for check digit).
    pub fn base_code_length(&self) -> usize {
        self.code_length + 1
    }

    /// Get the total formatted code length.
    pub fn total_code_length(&self) -> usize {
        self.format.total_length(self.base_code_length())
    }
}

/// Handle to an opened .bin file.
pub struct BinFile {
    /// File path (None if in-memory)
    path: Option<PathBuf>,
    /// Raw file data (for in-memory operations)
    raw_data: Option<Vec<u8>>,
    /// Configuration
    config: BinConfig,
    /// 32-byte data key (decrypted)
    data_key: [u8; 32],
    /// 32-byte secret key for HMAC
    secret_key: [u8; 32],
    /// 32-byte storage key for database encryption
    storage_key: [u8; 32],
    /// Counter manager
    counter: CounterManager,
    /// Access level
    access_level: AccessLevel,
    /// Salt from file
    salt: [u8; SALT_SIZE],
    /// Is the file bound to a machine?
    is_bound: bool,
    /// Has mutable section?
    has_mutable: bool,
    /// Current machine ID (cached)
    current_machine_id: Option<[u8; 32]>,
}

impl BinFile {
    // ==================== Creation ====================

    /// Create a new .bin file.
    ///
    /// # Arguments
    /// * `path` - File path for the new .bin file
    /// * `secret` - Secret password for accessing the file
    /// * `config` - Configuration for the .bin file
    ///
    /// # Example
    ///
    /// ```no_run
    /// use promocrypt_core::{BinFile, BinConfig, Alphabet, CheckPosition, CounterMode, AuditInfo, CodeFormat};
    ///
    /// let config = BinConfig {
    ///     name: "production".to_string(),
    ///     alphabet: Alphabet::default_alphabet(),
    ///     code_length: 9,
    ///     check_position: CheckPosition::End,
    ///     secret_key: String::new(), // Will be generated
    ///     storage_key: String::new(), // Will be generated
    ///     storage_encryption_enabled: false,
    ///     damm_table: promocrypt_core::DammTable::new(26),
    ///     counter_mode: CounterMode::External,
    ///     format: CodeFormat::default(),
    ///     audit: AuditInfo::default(),
    /// };
    ///
    /// let bin = BinFile::create("production.bin", "my-secret", config).unwrap();
    /// ```
    pub fn create(path: impl AsRef<Path>, secret: &str, mut config: BinConfig) -> Result<Self> {
        let path = path.as_ref();

        // Get machine ID
        let machine_id = get_machine_id()?;

        // Generate random keys
        let data_key = generate_random_key()?;
        let secret_key = generate_random_key()?;
        let storage_key = generate_random_key()?;
        let salt = generate_salt()?;

        // Set keys in config
        config.secret_key = hex::encode(secret_key);
        config.storage_key = hex::encode(storage_key);

        // Update audit
        config.audit = AuditInfo::new(&machine_id);

        // Serialize config to JSON
        let config_json = serde_json::to_vec(&config)?;

        // Generate nonces
        let machine_nonce = generate_nonce()?;
        let secret_nonce = generate_nonce()?;
        let data_nonce = generate_nonce()?;

        // Encrypt data_key for machine and secret
        let machine_encrypted_key =
            encrypt_data_key(&data_key, &machine_id, &salt, &machine_nonce)?;
        let secret_encrypted_key =
            encrypt_data_key(&data_key, secret.as_bytes(), &salt, &secret_nonce)?;

        // Encrypt config
        let encrypted_data = encrypt_data(&data_key, &config_json, &data_nonce)?;

        // Build file
        let flags = FLAG_IS_BOUND; // Bound to creation machine
        let has_mutable = config.counter_mode.is_in_bin();

        let mut file_data = Vec::new();

        // Header
        file_data.extend_from_slice(MAGIC);
        file_data.push(VERSION);
        file_data.push(flags | if has_mutable { FLAG_HAS_MUTABLE } else { 0 });

        // CRC placeholder (4 bytes)
        let crc_offset = file_data.len();
        file_data.extend_from_slice(&[0u8; 4]);

        // Salt and encrypted keys
        file_data.extend_from_slice(&salt);
        file_data.extend_from_slice(&machine_nonce);
        file_data.extend_from_slice(&machine_encrypted_key);
        file_data.extend_from_slice(&secret_nonce);
        file_data.extend_from_slice(&secret_encrypted_key);

        // Encrypted data
        file_data.extend_from_slice(&data_nonce);
        file_data.extend_from_slice(&(encrypted_data.len() as u32).to_le_bytes());
        file_data.extend_from_slice(&encrypted_data);

        // Mutable section (if needed)
        if has_mutable {
            let mutable_nonce = generate_nonce()?;
            let counter_bytes = counter_to_bytes(0);
            let encrypted_counter = encrypt_data(&data_key, &counter_bytes, &mutable_nonce)?;

            file_data.extend_from_slice(&mutable_nonce);
            file_data.extend_from_slice(&(encrypted_counter.len() as u32).to_le_bytes());
            file_data.extend_from_slice(&encrypted_counter);
        }

        // Calculate and write CRC
        let crc = crc32fast::hash(&file_data[0..10]);
        file_data[crc_offset..crc_offset + 4].copy_from_slice(&crc.to_le_bytes());

        // Write file
        let mut file = File::create(path)?;
        file.write_all(&file_data)?;
        file.sync_all()?;

        // Create counter manager
        let counter = CounterManager::new(config.counter_mode.clone());

        Ok(Self {
            path: Some(path.to_path_buf()),
            raw_data: Some(file_data), // Cache the raw data for save() method
            config,
            data_key,
            secret_key,
            storage_key,
            counter,
            access_level: AccessLevel::FullAccess,
            salt,
            is_bound: true,
            has_mutable,
            current_machine_id: Some(machine_id),
        })
    }

    /// Create .bin in memory (for database storage).
    pub fn create_in_memory(secret: &str, config: BinConfig) -> Result<Vec<u8>> {
        // Create a temporary file path-like name
        let temp_path =
            std::env::temp_dir().join(format!("promocrypt_{}.bin", rand::random::<u64>()));
        let bin = Self::create(&temp_path, secret, config)?;

        // Read back the file content
        let data = std::fs::read(&temp_path)?;

        // Clean up temp file
        std::fs::remove_file(&temp_path).ok();

        drop(bin);
        Ok(data)
    }

    // ==================== Opening ====================

    /// Open with machineID (read-only access).
    pub fn open_readonly(path: impl AsRef<Path>) -> Result<Self> {
        let path = path.as_ref();
        let data = std::fs::read(path)
            .map_err(|_| PromocryptError::FileNotFound(path.display().to_string()))?;

        let machine_id = get_machine_id()?;
        Self::open_from_bytes_internal(&data, Some(&machine_id), None, Some(path.to_path_buf()))
    }

    /// Open with secret (full access).
    pub fn open_with_secret(path: impl AsRef<Path>, secret: &str) -> Result<Self> {
        let path = path.as_ref();
        let data = std::fs::read(path)
            .map_err(|_| PromocryptError::FileNotFound(path.display().to_string()))?;

        // Get machine ID for history tracking (optional - don't fail if unavailable)
        let machine_id = get_machine_id().ok();
        Self::open_from_bytes_internal(
            &data,
            machine_id.as_ref(),
            Some(secret),
            Some(path.to_path_buf()),
        )
    }

    /// Open from bytes with machineID (read-only access).
    pub fn from_bytes_readonly(data: &[u8]) -> Result<Self> {
        let machine_id = get_machine_id()?;
        Self::open_from_bytes_internal(data, Some(&machine_id), None, None)
    }

    /// Open from bytes with secret (full access).
    pub fn from_bytes_with_secret(data: &[u8], secret: &str) -> Result<Self> {
        // Get machine ID for history tracking (optional - don't fail if unavailable)
        let machine_id = get_machine_id().ok();
        Self::open_from_bytes_internal(data, machine_id.as_ref(), Some(secret), None)
    }

    /// Internal method to open from bytes.
    fn open_from_bytes_internal(
        data: &[u8],
        machine_id: Option<&[u8; 32]>,
        secret: Option<&str>,
        path: Option<PathBuf>,
    ) -> Result<Self> {
        // Validate minimum size
        if data.len() < HEADER_SIZE {
            return Err(PromocryptError::InvalidFileFormat);
        }

        // Check magic
        if &data[OFFSET_MAGIC..OFFSET_MAGIC + 8] != MAGIC {
            return Err(PromocryptError::InvalidFileFormat);
        }

        // Check version
        let version = data[OFFSET_VERSION];
        if version != VERSION {
            return Err(PromocryptError::UnsupportedVersion(version));
        }

        // Get flags
        let flags = data[OFFSET_FLAGS];
        let is_bound = (flags & FLAG_IS_BOUND) != 0;
        let has_mutable = (flags & FLAG_HAS_MUTABLE) != 0;

        // Verify CRC
        let stored_crc = u32::from_le_bytes([
            data[OFFSET_HEADER_CRC],
            data[OFFSET_HEADER_CRC + 1],
            data[OFFSET_HEADER_CRC + 2],
            data[OFFSET_HEADER_CRC + 3],
        ]);
        let computed_crc = crc32fast::hash(&data[0..10]);
        if stored_crc != computed_crc {
            return Err(PromocryptError::HeaderChecksumMismatch);
        }

        // Extract salt
        let mut salt = [0u8; SALT_SIZE];
        salt.copy_from_slice(&data[OFFSET_SALT..OFFSET_SALT + SALT_SIZE]);

        // Determine access level and decrypt data_key
        let (data_key, access_level) = if let Some(secret) = secret {
            // Try secret key
            let mut secret_nonce = [0u8; NONCE_SIZE];
            secret_nonce
                .copy_from_slice(&data[OFFSET_SECRET_NONCE..OFFSET_SECRET_NONCE + NONCE_SIZE]);

            let mut secret_encrypted = [0u8; ENCRYPTED_KEY_SIZE];
            secret_encrypted
                .copy_from_slice(&data[OFFSET_SECRET_KEY..OFFSET_SECRET_KEY + ENCRYPTED_KEY_SIZE]);

            let data_key =
                decrypt_data_key(&secret_encrypted, secret.as_bytes(), &salt, &secret_nonce)?;
            (data_key, AccessLevel::FullAccess)
        } else if let Some(machine_id) = machine_id {
            // Try machine key
            if !is_bound {
                return Err(PromocryptError::MachineMismatch);
            }

            let mut machine_nonce = [0u8; NONCE_SIZE];
            machine_nonce
                .copy_from_slice(&data[OFFSET_MACHINE_NONCE..OFFSET_MACHINE_NONCE + NONCE_SIZE]);

            let mut machine_encrypted = [0u8; ENCRYPTED_KEY_SIZE];
            machine_encrypted.copy_from_slice(
                &data[OFFSET_MACHINE_KEY..OFFSET_MACHINE_KEY + ENCRYPTED_KEY_SIZE],
            );

            let data_key = decrypt_data_key(&machine_encrypted, machine_id, &salt, &machine_nonce)
                .map_err(|_| PromocryptError::MachineMismatch)?;
            (data_key, AccessLevel::ReadOnly)
        } else {
            return Err(PromocryptError::InvalidArgument(
                "Either machine_id or secret must be provided".to_string(),
            ));
        };

        // Decrypt config
        let mut data_nonce = [0u8; NONCE_SIZE];
        data_nonce.copy_from_slice(&data[OFFSET_DATA_NONCE..OFFSET_DATA_NONCE + NONCE_SIZE]);

        let data_length = u32::from_le_bytes([
            data[OFFSET_DATA_LENGTH],
            data[OFFSET_DATA_LENGTH + 1],
            data[OFFSET_DATA_LENGTH + 2],
            data[OFFSET_DATA_LENGTH + 3],
        ]) as usize;

        let data_end = OFFSET_DATA + data_length;
        if data.len() < data_end {
            return Err(PromocryptError::InvalidFileFormat);
        }

        let encrypted_config = &data[OFFSET_DATA..data_end];
        let config_json = decrypt_data(&data_key, encrypted_config, &data_nonce)?;
        let config: BinConfig = serde_json::from_slice(&config_json)?;

        // Parse secret key
        let secret_key_bytes = hex::decode(&config.secret_key).map_err(|_| {
            PromocryptError::InvalidFileFormatDetails("Invalid secret key hex".to_string())
        })?;
        if secret_key_bytes.len() != 32 {
            return Err(PromocryptError::InvalidFileFormatDetails(
                "Secret key must be 32 bytes".to_string(),
            ));
        }
        let mut secret_key = [0u8; 32];
        secret_key.copy_from_slice(&secret_key_bytes);

        // Parse storage key (may be empty for older files)
        let mut storage_key = [0u8; 32];
        if !config.storage_key.is_empty() {
            let storage_key_bytes = hex::decode(&config.storage_key).map_err(|_| {
                PromocryptError::InvalidFileFormatDetails("Invalid storage key hex".to_string())
            })?;
            if storage_key_bytes.len() == 32 {
                storage_key.copy_from_slice(&storage_key_bytes);
            }
        }

        // Read counter from mutable section if present
        let mut counter_value = 0u64;
        if has_mutable && data.len() > data_end {
            let mutable_offset = data_end;
            if data.len() >= mutable_offset + NONCE_SIZE + 4 {
                let mut mutable_nonce = [0u8; NONCE_SIZE];
                mutable_nonce.copy_from_slice(&data[mutable_offset..mutable_offset + NONCE_SIZE]);

                let mutable_length = u32::from_le_bytes([
                    data[mutable_offset + NONCE_SIZE],
                    data[mutable_offset + NONCE_SIZE + 1],
                    data[mutable_offset + NONCE_SIZE + 2],
                    data[mutable_offset + NONCE_SIZE + 3],
                ]) as usize;

                let mutable_start = mutable_offset + NONCE_SIZE + 4;
                let mutable_end = mutable_start + mutable_length;

                if data.len() >= mutable_end {
                    let encrypted_counter = &data[mutable_start..mutable_end];
                    if let Ok(counter_bytes) =
                        decrypt_data(&data_key, encrypted_counter, &mutable_nonce)
                        && let Ok(val) = counter_from_bytes(&counter_bytes)
                    {
                        counter_value = val;
                    }
                }
            }
        }

        let counter = CounterManager::with_in_bin_value(config.counter_mode.clone(), counter_value);

        Ok(Self {
            path,
            raw_data: Some(data.to_vec()),
            config,
            data_key,
            secret_key,
            storage_key,
            counter,
            access_level,
            salt,
            is_bound,
            has_mutable,
            current_machine_id: machine_id.copied(),
        })
    }

    /// Try to open with machineID, returns None on any error.
    pub fn try_open_readonly(path: impl AsRef<Path>) -> Option<Self> {
        Self::open_readonly(path).ok()
    }

    /// Try to open with secret, returns None on any error.
    pub fn try_open_with_secret(path: impl AsRef<Path>, secret: &str) -> Option<Self> {
        Self::open_with_secret(path, secret).ok()
    }

    // ==================== Getters ====================

    /// Get configuration (both access levels).
    pub fn config(&self) -> &BinConfig {
        &self.config
    }

    /// Get name.
    pub fn name(&self) -> &str {
        &self.config.name
    }

    /// Get alphabet.
    pub fn alphabet(&self) -> &Alphabet {
        &self.config.alphabet
    }

    /// Get code length (without check digit).
    pub fn code_length(&self) -> usize {
        self.config.code_length
    }

    /// Get total code length (with check digit).
    pub fn total_length(&self) -> usize {
        self.config.code_length + 1
    }

    /// Get check position.
    pub fn check_position(&self) -> CheckPosition {
        self.config.check_position
    }

    /// Get counter mode.
    pub fn counter_mode(&self) -> &CounterMode {
        &self.config.counter_mode
    }

    /// Get audit info (both access levels).
    pub fn audit(&self) -> &AuditInfo {
        &self.config.audit
    }

    /// Get access level.
    pub fn access_level(&self) -> AccessLevel {
        self.access_level
    }

    /// Check if file is bound to a machine.
    pub fn is_bound(&self) -> bool {
        self.is_bound
    }

    /// Get code format.
    pub fn format(&self) -> &CodeFormat {
        &self.config.format
    }

    /// Check if storage encryption is enabled.
    pub fn is_storage_encryption_enabled(&self) -> bool {
        self.config.storage_encryption_enabled
    }

    /// Get history.
    pub fn get_history(&self) -> &History {
        &self.config.audit.history
    }

    /// Get generation log.
    pub fn get_generation_log(&self) -> &[GenerationLogEntry] {
        self.config.audit.get_generation_log()
    }

    /// Get total codes generated.
    pub fn total_codes_generated(&self) -> u64 {
        self.config.audit.generation_count
    }

    // ==================== Validation ====================

    /// Validate a code (both access levels).
    /// Handles formatted codes by stripping prefix/suffix/separators.
    pub fn validate(&self, code: &str) -> ValidationResult {
        // Strip formatting if present
        let base_code = if self.config.format.has_formatting() {
            match self.config.format.strip(code) {
                Some(c) => c,
                None => {
                    return ValidationResult::InvalidFormat {
                        reason: "prefix or suffix mismatch".to_string(),
                    };
                }
            }
        } else {
            code.to_string()
        };

        crate::validator::validate(
            &base_code,
            &self.config.alphabet,
            self.total_length(),
            &self.config.damm_table,
        )
    }

    /// Quick validation check.
    pub fn is_valid(&self, code: &str) -> bool {
        self.validate(code).is_valid()
    }

    /// Validate multiple codes at once.
    pub fn validate_batch(&self, codes: &[&str]) -> Vec<ValidationResult> {
        codes.iter().map(|c| self.validate(c)).collect()
    }

    // ==================== Generation ====================

    /// Generate a single code (requires FullAccess).
    /// Returns formatted code with prefix/suffix/separators if configured.
    /// If storage_encryption_enabled, returns encrypted code.
    pub fn generate(&mut self) -> Result<String> {
        self.require_full_access()?;

        let counter = self.counter.reserve(1)?;
        let base_code = generate_code(
            &self.secret_key,
            counter,
            &self.config.alphabet,
            self.config.code_length,
            self.config.check_position,
            &self.config.damm_table,
        );

        // Apply formatting
        let formatted = self.config.format.format(&base_code);

        // Record generation with log
        if let Some(machine_id) = &self.current_machine_id {
            self.config
                .audit
                .record_generation_with_log(machine_id, 1, counter);
        } else {
            self.config.audit.record_generation(1);
        }
        // Save the full config to persist generation log (not just mutable section)
        self.save()?;

        // Apply storage encryption if enabled
        if self.config.storage_encryption_enabled {
            encrypt_code_for_storage(&self.storage_key, &formatted)
        } else {
            Ok(formatted)
        }
    }

    /// Generate batch of codes (requires FullAccess).
    pub fn generate_batch(&mut self, count: usize) -> Result<Vec<String>> {
        self.require_full_access()?;

        let start_counter = self.counter.reserve(count as u64)?;
        let base_codes = generate_batch(
            &self.secret_key,
            start_counter,
            count,
            &self.config.alphabet,
            self.config.code_length,
            self.config.check_position,
            &self.config.damm_table,
        );

        // Apply formatting
        let formatted: Vec<String> = base_codes
            .iter()
            .map(|c| self.config.format.format(c))
            .collect();

        // Record generation with log
        if let Some(machine_id) = &self.current_machine_id {
            self.config
                .audit
                .record_generation_with_log(machine_id, count as u64, start_counter);
        } else {
            self.config.audit.record_generation(count as u64);
        }
        // Save the full config to persist generation log (not just mutable section)
        self.save()?;

        // Apply storage encryption if enabled
        if self.config.storage_encryption_enabled {
            let code_refs: Vec<&str> = formatted.iter().map(|s| s.as_str()).collect();
            crate::encryption::encrypt_codes_for_storage(&self.storage_key, &code_refs)
        } else {
            Ok(formatted)
        }
    }

    /// Generate code at specific counter (doesn't update counter).
    pub fn generate_at(&self, counter: u64) -> Result<String> {
        self.require_full_access()?;

        let base_code = generate_code(
            &self.secret_key,
            counter,
            &self.config.alphabet,
            self.config.code_length,
            self.config.check_position,
            &self.config.damm_table,
        );

        Ok(self.config.format.format(&base_code))
    }

    /// Generate batch at specific counter (doesn't update counter).
    pub fn generate_batch_at(&self, start_counter: u64, count: usize) -> Result<Vec<String>> {
        self.require_full_access()?;

        let base_codes = generate_batch(
            &self.secret_key,
            start_counter,
            count,
            &self.config.alphabet,
            self.config.code_length,
            self.config.check_position,
            &self.config.damm_table,
        );

        Ok(base_codes
            .iter()
            .map(|c| self.config.format.format(c))
            .collect())
    }

    // ==================== Counter ====================

    /// Get current counter value.
    pub fn get_counter(&self) -> Result<u64> {
        self.counter.get()
    }

    /// Set counter value (requires FullAccess).
    ///
    /// This sets the counter to a specific value. Use with caution as it can
    /// cause duplicate codes if set to a previously used value.
    ///
    /// # Arguments
    /// * `value` - The new counter value
    ///
    /// # Errors
    /// Returns an error if:
    /// - Access level is not FullAccess
    /// - Counter mode is Manual or External (counter not stored)
    /// - IO error during save
    ///
    /// # Example
    /// ```no_run
    /// use promocrypt_core::BinFile;
    ///
    /// let mut bin = BinFile::open_with_secret("campaign.bin", "secret")?;
    /// bin.set_counter(1000)?;
    /// # Ok::<(), promocrypt_core::PromocryptError>(())
    /// ```
    pub fn set_counter(&mut self, value: u64) -> Result<()> {
        self.require_full_access()?;

        // Validate against capacity to prevent duplicate codes
        let capacity = self.capacity();
        if value as u128 >= capacity {
            return Err(PromocryptError::InvalidArgument(format!(
                "Counter value {} exceeds capacity {}. This would cause duplicate codes.",
                value, capacity
            )));
        }

        self.counter.set(value)?;

        // Save to persist counter change (for InBin and File modes)
        if self.path.is_some() {
            self.save()?;
        }

        Ok(())
    }

    /// Calculate the maximum capacity based on alphabet size and code length.
    ///
    /// Capacity = alphabet_size ^ code_length
    pub fn capacity(&self) -> u128 {
        let alphabet_size = self.config.alphabet.len();
        let code_length = self.config.code_length;
        (alphabet_size as u128).pow(code_length as u32)
    }

    /// Reserve a range of counter values atomically (requires FullAccess).
    ///
    /// Returns the starting counter value and increments the stored counter
    /// by `count`. This is useful for parallel code generation where multiple
    /// workers need exclusive counter ranges.
    ///
    /// # Arguments
    /// * `count` - Number of counter values to reserve
    ///
    /// # Returns
    /// The starting counter value of the reserved range.
    ///
    /// # Errors
    /// Returns an error if:
    /// - Access level is not FullAccess
    /// - Counter mode is External (counter not stored)
    /// - Counter overflow would occur
    /// - Reservation would exceed capacity
    /// - IO error during save
    ///
    /// # Example
    /// ```no_run
    /// use promocrypt_core::BinFile;
    ///
    /// let mut bin = BinFile::open_with_secret("campaign.bin", "secret")?;
    ///
    /// // Reserve 10,000 counter values for this worker
    /// let start = bin.reserve_counter_range(10000)?;
    ///
    /// // Generate codes at the reserved counters (without updating counter)
    /// let codes = bin.generate_batch_at(start, 10000)?;
    /// # Ok::<(), promocrypt_core::PromocryptError>(())
    /// ```
    pub fn reserve_counter_range(&mut self, count: u64) -> Result<u64> {
        self.require_full_access()?;

        // Validate against capacity to prevent duplicate codes
        let capacity = self.capacity();
        let current = self.counter.get().unwrap_or(0);
        let end = current.saturating_add(count);
        if end as u128 > capacity {
            return Err(PromocryptError::InvalidArgument(format!(
                "Reserving {} codes would exceed capacity. Current: {}, Capacity: {}",
                count, current, capacity
            )));
        }

        let start = self.counter.reserve(count)?;

        // Save to persist counter change (for InBin and File modes)
        if self.path.is_some() {
            self.save()?;
        }

        Ok(start)
    }

    // ==================== Mastering ====================

    /// Master for a new machine (requires FullAccess).
    pub fn master_for_machine(
        &self,
        output_path: impl AsRef<Path>,
        target_machine_id: &[u8; 32],
    ) -> Result<()> {
        self.require_full_access()?;

        let path = output_path.as_ref();

        // Update config with new mastering info
        let mut new_config = self.config.clone();
        new_config.audit.record_master(target_machine_id);

        // Regenerate file with new machine binding
        let config_json = serde_json::to_vec(&new_config)?;

        // Generate new nonces
        let machine_nonce = generate_nonce()?;
        let data_nonce = generate_nonce()?;

        // Encrypt data_key for new machine
        let machine_encrypted_key = encrypt_data_key(
            &self.data_key,
            target_machine_id,
            &self.salt,
            &machine_nonce,
        )?;

        // Keep existing secret encrypted key from raw data
        let raw_data = self.raw_data.as_ref().ok_or_else(|| {
            PromocryptError::InvalidArgument("No raw data available for mastering".to_string())
        })?;

        let mut secret_nonce = [0u8; NONCE_SIZE];
        secret_nonce
            .copy_from_slice(&raw_data[OFFSET_SECRET_NONCE..OFFSET_SECRET_NONCE + NONCE_SIZE]);

        let mut secret_encrypted = [0u8; ENCRYPTED_KEY_SIZE];
        secret_encrypted
            .copy_from_slice(&raw_data[OFFSET_SECRET_KEY..OFFSET_SECRET_KEY + ENCRYPTED_KEY_SIZE]);

        // Encrypt config
        let encrypted_data = encrypt_data(&self.data_key, &config_json, &data_nonce)?;

        // Build file
        let flags = FLAG_IS_BOUND
            | if self.has_mutable {
                FLAG_HAS_MUTABLE
            } else {
                0
            };

        let mut file_data = Vec::new();

        // Header
        file_data.extend_from_slice(MAGIC);
        file_data.push(VERSION);
        file_data.push(flags);

        // CRC placeholder
        let crc_offset = file_data.len();
        file_data.extend_from_slice(&[0u8; 4]);

        // Salt and keys
        file_data.extend_from_slice(&self.salt);
        file_data.extend_from_slice(&machine_nonce);
        file_data.extend_from_slice(&machine_encrypted_key);
        file_data.extend_from_slice(&secret_nonce);
        file_data.extend_from_slice(&secret_encrypted);

        // Encrypted data
        file_data.extend_from_slice(&data_nonce);
        file_data.extend_from_slice(&(encrypted_data.len() as u32).to_le_bytes());
        file_data.extend_from_slice(&encrypted_data);

        // Mutable section (if needed)
        if self.has_mutable {
            let mutable_nonce = generate_nonce()?;
            let counter_bytes = counter_to_bytes(self.counter.in_bin_value());
            let encrypted_counter = encrypt_data(&self.data_key, &counter_bytes, &mutable_nonce)?;

            file_data.extend_from_slice(&mutable_nonce);
            file_data.extend_from_slice(&(encrypted_counter.len() as u32).to_le_bytes());
            file_data.extend_from_slice(&encrypted_counter);
        }

        // Calculate and write CRC
        let crc = crc32fast::hash(&file_data[0..10]);
        file_data[crc_offset..crc_offset + 4].copy_from_slice(&crc.to_le_bytes());

        // Write file
        let mut file = File::create(path)?;
        file.write_all(&file_data)?;
        file.sync_all()?;

        Ok(())
    }

    /// Export unbound copy (requires FullAccess).
    pub fn export_unbound(&self, output_path: impl AsRef<Path>) -> Result<()> {
        self.require_full_access()?;

        let path = output_path.as_ref();

        // Create config without machine binding
        let mut new_config = self.config.clone();
        new_config.audit.mastered_at = None;
        new_config.audit.mastered_for = None;

        let config_json = serde_json::to_vec(&new_config)?;

        // Generate new nonces
        let data_nonce = generate_nonce()?;

        // Keep existing secret encrypted key
        let raw_data = self
            .raw_data
            .as_ref()
            .ok_or_else(|| PromocryptError::InvalidArgument("No raw data available".to_string()))?;

        let mut secret_nonce = [0u8; NONCE_SIZE];
        secret_nonce
            .copy_from_slice(&raw_data[OFFSET_SECRET_NONCE..OFFSET_SECRET_NONCE + NONCE_SIZE]);

        let mut secret_encrypted = [0u8; ENCRYPTED_KEY_SIZE];
        secret_encrypted
            .copy_from_slice(&raw_data[OFFSET_SECRET_KEY..OFFSET_SECRET_KEY + ENCRYPTED_KEY_SIZE]);

        // Encrypt config
        let encrypted_data = encrypt_data(&self.data_key, &config_json, &data_nonce)?;

        // Build file (no machine key, not bound)
        let flags = if self.has_mutable {
            FLAG_HAS_MUTABLE
        } else {
            0
        };

        let mut file_data = Vec::new();

        // Header
        file_data.extend_from_slice(MAGIC);
        file_data.push(VERSION);
        file_data.push(flags);

        // CRC placeholder
        let crc_offset = file_data.len();
        file_data.extend_from_slice(&[0u8; 4]);

        // Salt and keys (empty machine key)
        file_data.extend_from_slice(&self.salt);
        file_data.extend_from_slice(&[0u8; NONCE_SIZE]); // Empty machine nonce
        file_data.extend_from_slice(&[0u8; ENCRYPTED_KEY_SIZE]); // Empty machine key
        file_data.extend_from_slice(&secret_nonce);
        file_data.extend_from_slice(&secret_encrypted);

        // Encrypted data
        file_data.extend_from_slice(&data_nonce);
        file_data.extend_from_slice(&(encrypted_data.len() as u32).to_le_bytes());
        file_data.extend_from_slice(&encrypted_data);

        // Calculate and write CRC
        let crc = crc32fast::hash(&file_data[0..10]);
        file_data[crc_offset..crc_offset + 4].copy_from_slice(&crc.to_le_bytes());

        // Write file
        let mut file = File::create(path)?;
        file.write_all(&file_data)?;
        file.sync_all()?;

        Ok(())
    }

    // ==================== Storage Encryption ====================

    /// Encrypt a code for database storage (requires FullAccess).
    pub fn encrypt_code(&self, code: &str) -> Result<String> {
        self.require_full_access()?;
        encrypt_code_for_storage(&self.storage_key, code)
    }

    /// Decrypt a code from database storage (requires FullAccess).
    pub fn decrypt_code(&self, encrypted: &str) -> Result<String> {
        self.require_full_access()?;
        decrypt_code_from_storage(&self.storage_key, encrypted)
    }

    /// Encrypt multiple codes for storage (requires FullAccess).
    pub fn encrypt_codes(&self, codes: &[&str]) -> Result<Vec<String>> {
        self.require_full_access()?;
        crate::encryption::encrypt_codes_for_storage(&self.storage_key, codes)
    }

    /// Decrypt multiple codes from storage (requires FullAccess).
    pub fn decrypt_codes(&self, encrypted: &[&str]) -> Result<Vec<String>> {
        self.require_full_access()?;
        crate::encryption::decrypt_codes_from_storage(&self.storage_key, encrypted)
    }

    /// Enable or disable storage encryption (requires FullAccess).
    pub fn set_storage_encryption(&mut self, enabled: bool) -> Result<()> {
        self.require_full_access()?;

        let old_value = self.config.storage_encryption_enabled.to_string();
        let new_value = enabled.to_string();

        if let Some(machine_id) = &self.current_machine_id {
            self.config.audit.history.record_config_change(
                machine_id,
                "storage_encryption_enabled",
                Some(&old_value),
                Some(&new_value),
            );
        }

        self.config.storage_encryption_enabled = enabled;
        Ok(())
    }

    // ==================== Configuration ====================

    /// Update counter mode (requires FullAccess).
    pub fn set_counter_mode(&mut self, mode: CounterMode) -> Result<()> {
        self.require_full_access()?;

        self.config.counter_mode = mode.clone();
        self.counter.set_mode(mode);
        self.save_if_needed()?;

        Ok(())
    }

    /// Update code format (requires FullAccess).
    pub fn set_format(&mut self, format: CodeFormat) -> Result<()> {
        self.require_full_access()?;

        if let Some(machine_id) = &self.current_machine_id {
            self.config.audit.history.record_config_change(
                machine_id,
                "format",
                Some(&serde_json::to_string(&self.config.format).unwrap_or_default()),
                Some(&serde_json::to_string(&format).unwrap_or_default()),
            );
        }

        self.config.format = format;
        Ok(())
    }

    /// Update check position (requires FullAccess).
    pub fn set_check_position(&mut self, position: CheckPosition) -> Result<()> {
        self.require_full_access()?;

        if let Some(machine_id) = &self.current_machine_id {
            self.config.audit.history.record_config_change(
                machine_id,
                "check_position",
                Some(&self.config.check_position.to_string()),
                Some(&position.to_string()),
            );
        }

        self.config.check_position = position;
        Ok(())
    }

    /// Set code prefix (requires FullAccess).
    ///
    /// # Arguments
    /// * `prefix` - Optional prefix to prepend to generated codes
    pub fn set_prefix(&mut self, prefix: Option<String>) -> Result<()> {
        self.require_full_access()?;

        let old_value = self.config.format.prefix.as_deref().map(|s| s.to_string());

        if let Some(machine_id) = &self.current_machine_id {
            self.config.audit.history.record_config_change(
                machine_id,
                "prefix",
                old_value.as_deref(),
                prefix.as_deref(),
            );
        }

        self.config.format.prefix = prefix;
        Ok(())
    }

    /// Set code suffix (requires FullAccess).
    ///
    /// # Arguments
    /// * `suffix` - Optional suffix to append to generated codes
    pub fn set_suffix(&mut self, suffix: Option<String>) -> Result<()> {
        self.require_full_access()?;

        let old_value = self.config.format.suffix.as_deref().map(|s| s.to_string());

        if let Some(machine_id) = &self.current_machine_id {
            self.config.audit.history.record_config_change(
                machine_id,
                "suffix",
                old_value.as_deref(),
                suffix.as_deref(),
            );
        }

        self.config.format.suffix = suffix;
        Ok(())
    }

    /// Set separator character (requires FullAccess).
    ///
    /// # Arguments
    /// * `separator` - Optional separator character to insert at specified positions
    pub fn set_separator(&mut self, separator: Option<char>) -> Result<()> {
        self.require_full_access()?;

        let old_value = self.config.format.separator.map(|c| c.to_string());
        let new_value = separator.map(|c| c.to_string());

        if let Some(machine_id) = &self.current_machine_id {
            self.config.audit.history.record_config_change(
                machine_id,
                "separator",
                old_value.as_deref(),
                new_value.as_deref(),
            );
        }

        self.config.format.separator = separator;
        Ok(())
    }

    /// Set separator positions (requires FullAccess).
    ///
    /// # Arguments
    /// * `positions` - Positions where separator should be inserted (0-based, before the character)
    pub fn set_separator_positions(&mut self, positions: Vec<usize>) -> Result<()> {
        self.require_full_access()?;

        let old_value = serde_json::to_string(&self.config.format.separator_positions).ok();
        let new_value = serde_json::to_string(&positions).ok();

        if let Some(machine_id) = &self.current_machine_id {
            self.config.audit.history.record_config_change(
                machine_id,
                "separator_positions",
                old_value.as_deref(),
                new_value.as_deref(),
            );
        }

        self.config.format.separator_positions = positions;
        Ok(())
    }

    /// Save all configuration changes to the .bin file (requires FullAccess).
    ///
    /// This persists all in-memory configuration changes to disk, including:
    /// - Format changes (prefix, suffix, separator, separator_positions)
    /// - Check position changes
    /// - Storage encryption changes
    /// - Counter mode changes
    /// - History and generation log updates
    ///
    /// # Errors
    /// Returns an error if:
    /// - Access level is not FullAccess
    /// - No file path is associated (in-memory file)
    /// - IO error during write
    pub fn save(&mut self) -> Result<()> {
        self.require_full_access()?;

        let path = self.path.as_ref().ok_or_else(|| {
            PromocryptError::InvalidArgument("Cannot save in-memory file without path".to_string())
        })?;

        // Get existing raw_data to preserve machine encryption
        let raw_data = self.raw_data.as_ref().ok_or_else(|| {
            PromocryptError::InvalidArgument("No raw data available for save".to_string())
        })?;

        // Serialize updated config
        let config_json = serde_json::to_vec(&self.config)?;

        // Generate new data nonce
        let data_nonce = generate_nonce()?;

        // Encrypt config
        let encrypted_data = encrypt_data(&self.data_key, &config_json, &data_nonce)?;

        // Get machine encrypted key from raw data
        let mut machine_nonce = [0u8; NONCE_SIZE];
        machine_nonce
            .copy_from_slice(&raw_data[OFFSET_MACHINE_NONCE..OFFSET_MACHINE_NONCE + NONCE_SIZE]);

        let mut machine_encrypted = [0u8; ENCRYPTED_KEY_SIZE];
        machine_encrypted.copy_from_slice(
            &raw_data[OFFSET_MACHINE_KEY..OFFSET_MACHINE_KEY + ENCRYPTED_KEY_SIZE],
        );

        // Get secret encrypted key from raw data
        let mut secret_nonce = [0u8; NONCE_SIZE];
        secret_nonce
            .copy_from_slice(&raw_data[OFFSET_SECRET_NONCE..OFFSET_SECRET_NONCE + NONCE_SIZE]);

        let mut secret_encrypted = [0u8; ENCRYPTED_KEY_SIZE];
        secret_encrypted
            .copy_from_slice(&raw_data[OFFSET_SECRET_KEY..OFFSET_SECRET_KEY + ENCRYPTED_KEY_SIZE]);

        // Build file
        let flags = (if self.is_bound { FLAG_IS_BOUND } else { 0 })
            | (if self.has_mutable {
                FLAG_HAS_MUTABLE
            } else {
                0
            });

        let mut file_data = Vec::new();

        // Header
        file_data.extend_from_slice(MAGIC);
        file_data.push(VERSION);
        file_data.push(flags);

        // CRC placeholder
        let crc_offset = file_data.len();
        file_data.extend_from_slice(&[0u8; 4]);

        // Salt and keys
        file_data.extend_from_slice(&self.salt);
        file_data.extend_from_slice(&machine_nonce);
        file_data.extend_from_slice(&machine_encrypted);
        file_data.extend_from_slice(&secret_nonce);
        file_data.extend_from_slice(&secret_encrypted);

        // Encrypted data
        file_data.extend_from_slice(&data_nonce);
        file_data.extend_from_slice(&(encrypted_data.len() as u32).to_le_bytes());
        file_data.extend_from_slice(&encrypted_data);

        // Mutable section (if needed)
        if self.has_mutable {
            let mutable_nonce = generate_nonce()?;
            let counter_bytes = counter_to_bytes(self.counter.in_bin_value());
            let encrypted_counter = encrypt_data(&self.data_key, &counter_bytes, &mutable_nonce)?;

            file_data.extend_from_slice(&mutable_nonce);
            file_data.extend_from_slice(&(encrypted_counter.len() as u32).to_le_bytes());
            file_data.extend_from_slice(&encrypted_counter);
        }

        // Calculate and write CRC
        let crc = crc32fast::hash(&file_data[0..10]);
        file_data[crc_offset..crc_offset + 4].copy_from_slice(&crc.to_le_bytes());

        // Write file
        let mut file = File::create(path)?;
        file.write_all(&file_data)?;
        file.sync_all()?;

        // Update raw_data cache
        self.raw_data = Some(file_data);

        // Mark counter as saved since we wrote the whole file
        if self.counter.is_in_bin_modified() {
            self.counter.mark_saved();
        }

        Ok(())
    }

    // ==================== Secret Rotation ====================

    /// Rotate the secret password (requires FullAccess).
    /// Re-encrypts the data_key with the new secret.
    pub fn rotate_secret(&mut self, old_secret: &str, new_secret: &str) -> Result<()> {
        self.require_full_access()?;

        // Verify old secret first (we should already have full access, but verify it matches)
        let path = self.path.as_ref().ok_or_else(|| {
            PromocryptError::InvalidArgument("Cannot rotate secret for in-memory file".to_string())
        })?;

        // Read raw file to get current secret encrypted key
        let raw_data = self
            .raw_data
            .as_ref()
            .ok_or_else(|| PromocryptError::InvalidArgument("No raw data available".to_string()))?;

        // Try to decrypt with old secret to verify it
        let mut secret_nonce = [0u8; NONCE_SIZE];
        secret_nonce
            .copy_from_slice(&raw_data[OFFSET_SECRET_NONCE..OFFSET_SECRET_NONCE + NONCE_SIZE]);

        let mut secret_encrypted = [0u8; ENCRYPTED_KEY_SIZE];
        secret_encrypted
            .copy_from_slice(&raw_data[OFFSET_SECRET_KEY..OFFSET_SECRET_KEY + ENCRYPTED_KEY_SIZE]);

        // Verify old secret
        let _verified_data_key = decrypt_data_key(
            &secret_encrypted,
            old_secret.as_bytes(),
            &self.salt,
            &secret_nonce,
        )
        .map_err(|_| PromocryptError::InvalidArgument("Old secret is incorrect".to_string()))?;

        // Generate new nonce for secret encryption
        let new_secret_nonce = generate_nonce()?;

        // Encrypt data_key with new secret
        let new_secret_encrypted = encrypt_data_key(
            &self.data_key,
            new_secret.as_bytes(),
            &self.salt,
            &new_secret_nonce,
        )?;

        // Record rotation in history
        let old_hash = hash_secret(old_secret);
        let new_hash = hash_secret(new_secret);

        if let Some(machine_id) = &self.current_machine_id {
            self.config
                .audit
                .history
                .record_secret_rotation(machine_id, &old_hash, &new_hash);
        }

        // Rewrite the file with new secret encryption
        let config_json = serde_json::to_vec(&self.config)?;
        let data_nonce = generate_nonce()?;
        let encrypted_data = encrypt_data(&self.data_key, &config_json, &data_nonce)?;

        // Get machine encrypted key from raw data
        let mut machine_nonce = [0u8; NONCE_SIZE];
        machine_nonce
            .copy_from_slice(&raw_data[OFFSET_MACHINE_NONCE..OFFSET_MACHINE_NONCE + NONCE_SIZE]);

        let mut machine_encrypted = [0u8; ENCRYPTED_KEY_SIZE];
        machine_encrypted.copy_from_slice(
            &raw_data[OFFSET_MACHINE_KEY..OFFSET_MACHINE_KEY + ENCRYPTED_KEY_SIZE],
        );

        // Build file
        let flags = (if self.is_bound { FLAG_IS_BOUND } else { 0 })
            | (if self.has_mutable {
                FLAG_HAS_MUTABLE
            } else {
                0
            });

        let mut file_data = Vec::new();

        // Header
        file_data.extend_from_slice(MAGIC);
        file_data.push(VERSION);
        file_data.push(flags);

        // CRC placeholder
        let crc_offset = file_data.len();
        file_data.extend_from_slice(&[0u8; 4]);

        // Salt and keys
        file_data.extend_from_slice(&self.salt);
        file_data.extend_from_slice(&machine_nonce);
        file_data.extend_from_slice(&machine_encrypted);
        file_data.extend_from_slice(&new_secret_nonce);
        file_data.extend_from_slice(&new_secret_encrypted);

        // Encrypted data
        file_data.extend_from_slice(&data_nonce);
        file_data.extend_from_slice(&(encrypted_data.len() as u32).to_le_bytes());
        file_data.extend_from_slice(&encrypted_data);

        // Mutable section (if needed)
        if self.has_mutable {
            let mutable_nonce = generate_nonce()?;
            let counter_bytes = counter_to_bytes(self.counter.in_bin_value());
            let encrypted_counter = encrypt_data(&self.data_key, &counter_bytes, &mutable_nonce)?;

            file_data.extend_from_slice(&mutable_nonce);
            file_data.extend_from_slice(&(encrypted_counter.len() as u32).to_le_bytes());
            file_data.extend_from_slice(&encrypted_counter);
        }

        // Calculate and write CRC
        let crc = crc32fast::hash(&file_data[0..10]);
        file_data[crc_offset..crc_offset + 4].copy_from_slice(&crc.to_le_bytes());

        // Write file
        let mut file = File::create(path)?;
        file.write_all(&file_data)?;
        file.sync_all()?;

        // Update raw_data
        self.raw_data = Some(file_data);

        Ok(())
    }

    // ==================== History & Logs ====================

    /// Export history as JSON.
    pub fn export_history(&self) -> String {
        self.config.audit.export_history()
    }

    /// Export generation log as JSON.
    pub fn export_generation_log(&self) -> String {
        self.config.audit.export_generation_log()
    }

    /// Clear history (requires FullAccess).
    pub fn clear_history(&mut self, keep_last: Option<usize>) -> Result<()> {
        self.require_full_access()?;
        self.config.audit.clear_history(keep_last);
        Ok(())
    }

    /// Clear generation log (requires FullAccess).
    pub fn clear_generation_log(&mut self, keep_last: Option<usize>) -> Result<()> {
        self.require_full_access()?;
        self.config.audit.clear_generation_log(keep_last);
        Ok(())
    }

    // ==================== Statistics ====================

    /// Get statistics about this .bin file.
    pub fn get_stats(&self) -> BinStats {
        BinStats::from_bin_file(self)
    }

    // ==================== Internal ====================

    fn require_full_access(&self) -> Result<()> {
        if self.access_level != AccessLevel::FullAccess {
            return Err(PromocryptError::SecretRequired);
        }
        Ok(())
    }

    fn save_if_needed(&mut self) -> Result<()> {
        if self.counter.is_in_bin_modified() {
            if let Some(path) = &self.path {
                self.save_mutable_section(path)?;
            }
            self.counter.mark_saved();
        }
        Ok(())
    }

    fn save_mutable_section(&self, path: &Path) -> Result<()> {
        if !self.has_mutable {
            return Ok(());
        }

        // Read existing file
        let mut file = OpenOptions::new().read(true).write(true).open(path)?;

        // Find mutable section offset
        let mut header = [0u8; HEADER_SIZE];
        file.read_exact(&mut header)?;

        let data_length = u32::from_le_bytes([
            header[OFFSET_DATA_LENGTH],
            header[OFFSET_DATA_LENGTH + 1],
            header[OFFSET_DATA_LENGTH + 2],
            header[OFFSET_DATA_LENGTH + 3],
        ]) as usize;

        let mutable_offset = OFFSET_DATA + data_length;

        // Generate new mutable section
        let mutable_nonce = generate_nonce()?;
        let counter_bytes = counter_to_bytes(self.counter.in_bin_value());
        let encrypted_counter = encrypt_data(&self.data_key, &counter_bytes, &mutable_nonce)?;

        // Write mutable section
        file.seek(SeekFrom::Start(mutable_offset as u64))?;
        file.write_all(&mutable_nonce)?;
        file.write_all(&(encrypted_counter.len() as u32).to_le_bytes())?;
        file.write_all(&encrypted_counter)?;
        file.sync_all()?;

        Ok(())
    }
}

/// Simple helper to create a BinConfig with defaults.
pub fn create_config(name: &str) -> BinConfig {
    let machine_id = get_machine_id().unwrap_or([0u8; 32]);
    let alphabet = Alphabet::default_alphabet();
    let damm_table = DammTable::new(alphabet.len());

    BinConfig {
        name: name.to_string(),
        alphabet,
        code_length: 9,
        check_position: CheckPosition::End,
        secret_key: String::new(),
        storage_key: String::new(),
        storage_encryption_enabled: false,
        damm_table,
        counter_mode: CounterMode::External,
        format: CodeFormat::default(),
        audit: AuditInfo::new(&machine_id),
    }
}

/// Statistics about a .bin file.
#[derive(Clone, Debug)]
pub struct BinStats {
    /// Name of the configuration.
    pub name: String,
    /// Alphabet size.
    pub alphabet_size: usize,
    /// Base code length (without check digit).
    pub code_length: usize,
    /// Total code length (with check digit, without formatting).
    pub base_code_length: usize,
    /// Total code length (with formatting).
    pub formatted_code_length: usize,
    /// Maximum possible unique codes (alphabet_size ^ code_length).
    pub capacity: u128,
    /// Current counter value.
    pub current_counter: u64,
    /// Total codes generated (from audit).
    pub total_generated: u64,
    /// Utilization percentage (current_counter / capacity * 100).
    pub utilization_percent: f64,
    /// Remaining codes before capacity exhaustion.
    pub remaining_capacity: u128,
    /// Counter mode.
    pub counter_mode: CounterMode,
    /// Has prefix/suffix/separator formatting.
    pub has_formatting: bool,
    /// Storage encryption enabled.
    pub storage_encryption_enabled: bool,
    /// Created timestamp.
    pub created_at: Option<String>,
    /// Last generated timestamp.
    pub last_generated_at: Option<String>,
    /// Number of secret rotations.
    pub secret_rotation_count: usize,
    /// Number of machine masterings.
    pub machine_mastering_count: usize,
    /// Number of config changes.
    pub config_change_count: usize,
    /// Number of generation log entries.
    pub generation_log_count: usize,
}

impl BinStats {
    /// Calculate stats from a BinFile.
    pub fn from_bin_file(bin: &BinFile) -> Self {
        let config = bin.config();
        let audit = bin.audit();

        let alphabet_size = config.alphabet.len();
        let code_length = config.code_length;
        let base_code_length = code_length + 1; // + check digit
        let formatted_code_length = config.format.total_length(base_code_length);

        let capacity = (alphabet_size as u128).pow(code_length as u32);
        let current_counter = bin.get_counter().unwrap_or(0);

        let utilization_percent = if capacity > 0 {
            (current_counter as f64 / capacity as f64) * 100.0
        } else {
            0.0
        };

        let remaining_capacity = capacity.saturating_sub(current_counter as u128);

        let has_formatting = config.format.has_formatting();

        Self {
            name: config.name.clone(),
            alphabet_size,
            code_length,
            base_code_length,
            formatted_code_length,
            capacity,
            current_counter,
            total_generated: audit.generation_count,
            utilization_percent,
            remaining_capacity,
            counter_mode: config.counter_mode.clone(),
            has_formatting,
            storage_encryption_enabled: config.storage_encryption_enabled,
            created_at: Some(audit.created_at.to_rfc3339()),
            last_generated_at: audit.last_generated_at.map(|dt| dt.to_rfc3339()),
            secret_rotation_count: audit.history.secret_rotations.len(),
            machine_mastering_count: audit.history.machine_masterings.len(),
            config_change_count: audit.history.config_changes.len(),
            generation_log_count: audit.generation_log.len(),
        }
    }

    /// Get a human-readable summary.
    pub fn summary(&self) -> String {
        let mut lines = Vec::new();

        lines.push(format!("Name: {}", self.name));
        lines.push(format!("Alphabet size: {}", self.alphabet_size));
        lines.push(format!(
            "Code length: {} (base: {}, formatted: {})",
            self.code_length, self.base_code_length, self.formatted_code_length
        ));
        lines.push(format!("Capacity: {}", self.capacity));
        lines.push(format!("Current counter: {}", self.current_counter));
        lines.push(format!("Total generated: {}", self.total_generated));
        lines.push(format!("Utilization: {:.6}%", self.utilization_percent));
        lines.push(format!("Remaining: {}", self.remaining_capacity));
        lines.push(format!("Counter mode: {:?}", self.counter_mode));
        lines.push(format!("Has formatting: {}", self.has_formatting));
        lines.push(format!(
            "Storage encryption: {}",
            self.storage_encryption_enabled
        ));

        if let Some(ref created) = self.created_at {
            lines.push(format!("Created: {}", created));
        }

        if let Some(ref last) = self.last_generated_at {
            lines.push(format!("Last generated: {}", last));
        }

        if self.secret_rotation_count > 0
            || self.machine_mastering_count > 0
            || self.config_change_count > 0
        {
            lines.push(format!(
                "History: {} rotations, {} masterings, {} config changes",
                self.secret_rotation_count, self.machine_mastering_count, self.config_change_count
            ));
        }

        if self.generation_log_count > 0 {
            lines.push(format!(
                "Generation log entries: {}",
                self.generation_log_count
            ));
        }

        lines.join("\n")
    }
}

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

    fn create_test_config(name: &str) -> BinConfig {
        let alphabet = Alphabet::default_alphabet();
        BinConfig {
            name: name.to_string(),
            alphabet: alphabet.clone(),
            code_length: 9,
            check_position: CheckPosition::End,
            secret_key: String::new(),
            storage_key: String::new(),
            storage_encryption_enabled: false,
            damm_table: DammTable::new(alphabet.len()),
            counter_mode: CounterMode::External,
            format: CodeFormat::default(),
            audit: AuditInfo::default(),
        }
    }

    #[test]
    fn test_create_and_open_with_secret() {
        let temp_dir = TempDir::new().unwrap();
        let path = temp_dir.path().join("test.bin");

        let config = create_test_config("test");
        let _bin = BinFile::create(&path, "my-secret", config).unwrap();

        // Open with secret
        let bin = BinFile::open_with_secret(&path, "my-secret").unwrap();
        assert_eq!(bin.name(), "test");
        assert_eq!(bin.access_level(), AccessLevel::FullAccess);
    }

    #[test]
    fn test_wrong_secret() {
        let temp_dir = TempDir::new().unwrap();
        let path = temp_dir.path().join("test.bin");

        let config = create_test_config("test");
        let _bin = BinFile::create(&path, "correct-secret", config).unwrap();

        // Try wrong secret
        let result = BinFile::open_with_secret(&path, "wrong-secret");
        assert!(result.is_err());
    }

    #[test]
    fn test_generate_and_validate() {
        let temp_dir = TempDir::new().unwrap();
        let path = temp_dir.path().join("test.bin");

        let mut config = create_test_config("test");
        config.counter_mode = CounterMode::InBin;

        let mut bin = BinFile::create(&path, "secret", config).unwrap();

        // Generate codes
        let codes = bin.generate_batch(10).unwrap();
        assert_eq!(codes.len(), 10);

        // Validate all codes
        for code in &codes {
            assert!(bin.is_valid(code));
        }
    }

    #[test]
    fn test_generate_at() {
        let temp_dir = TempDir::new().unwrap();
        let path = temp_dir.path().join("test.bin");

        let config = create_test_config("test");
        let bin = BinFile::create(&path, "secret", config).unwrap();

        // Generate at specific counter
        let code1 = bin.generate_at(1000).unwrap();
        let code2 = bin.generate_at(1000).unwrap();

        assert_eq!(code1, code2); // Same counter = same code
        assert!(bin.is_valid(&code1));
    }

    #[test]
    fn test_readonly_cannot_generate() {
        let temp_dir = TempDir::new().unwrap();
        let path = temp_dir.path().join("test.bin");

        let config = create_test_config("test");
        let _bin = BinFile::create(&path, "secret", config).unwrap();

        // Open readonly
        let mut bin = BinFile::open_readonly(&path).unwrap();
        assert_eq!(bin.access_level(), AccessLevel::ReadOnly);

        // Try to generate
        let result = bin.generate();
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            PromocryptError::SecretRequired
        ));
    }

    #[test]
    fn test_code_length() {
        let temp_dir = TempDir::new().unwrap();
        let path = temp_dir.path().join("test.bin");

        let mut config = create_test_config("test");
        config.code_length = 12;
        config.counter_mode = CounterMode::InBin;

        let mut bin = BinFile::create(&path, "secret", config).unwrap();

        let code = bin.generate().unwrap();
        assert_eq!(code.len(), 13); // 12 + 1 check digit
    }

    #[test]
    fn test_audit_tracking() {
        let temp_dir = TempDir::new().unwrap();
        let path = temp_dir.path().join("test.bin");

        let mut config = create_test_config("test");
        config.counter_mode = CounterMode::InBin;

        let mut bin = BinFile::create(&path, "secret", config).unwrap();

        assert_eq!(bin.audit().generation_count, 0);

        bin.generate_batch(100).unwrap();
        assert_eq!(bin.audit().generation_count, 100);

        bin.generate().unwrap();
        assert_eq!(bin.audit().generation_count, 101);
    }

    #[test]
    fn test_from_bytes() {
        let config = create_test_config("test");
        let data = BinFile::create_in_memory("secret", config).unwrap();

        // Open from bytes
        let bin = BinFile::from_bytes_with_secret(&data, "secret").unwrap();
        assert_eq!(bin.name(), "test");
    }

    #[test]
    fn test_set_counter() {
        let temp_dir = TempDir::new().unwrap();
        let path = temp_dir.path().join("test.bin");

        let mut config = create_test_config("test");
        config.counter_mode = CounterMode::InBin;

        let mut bin = BinFile::create(&path, "secret", config).unwrap();

        // Initial counter should be 0
        assert_eq!(bin.get_counter().unwrap(), 0);

        // Set counter to specific value
        bin.set_counter(1000).unwrap();
        assert_eq!(bin.get_counter().unwrap(), 1000);

        // Reopen and verify persistence
        drop(bin);
        let bin = BinFile::open_with_secret(&path, "secret").unwrap();
        assert_eq!(bin.get_counter().unwrap(), 1000);
    }

    #[test]
    fn test_set_counter_requires_full_access() {
        let temp_dir = TempDir::new().unwrap();
        let path = temp_dir.path().join("test.bin");

        let mut config = create_test_config("test");
        config.counter_mode = CounterMode::InBin;

        let _bin = BinFile::create(&path, "secret", config).unwrap();

        // Open readonly
        let mut bin = BinFile::open_readonly(&path).unwrap();

        // Try to set counter - should fail
        let result = bin.set_counter(100);
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            PromocryptError::SecretRequired
        ));
    }

    #[test]
    fn test_reserve_counter_range() {
        let temp_dir = TempDir::new().unwrap();
        let path = temp_dir.path().join("test.bin");

        let mut config = create_test_config("test");
        config.counter_mode = CounterMode::InBin;

        let mut bin = BinFile::create(&path, "secret", config).unwrap();

        // Initial counter should be 0
        assert_eq!(bin.get_counter().unwrap(), 0);

        // Reserve 100 counter values
        let start = bin.reserve_counter_range(100).unwrap();
        assert_eq!(start, 0);
        assert_eq!(bin.get_counter().unwrap(), 100);

        // Reserve 50 more
        let start2 = bin.reserve_counter_range(50).unwrap();
        assert_eq!(start2, 100);
        assert_eq!(bin.get_counter().unwrap(), 150);

        // Reopen and verify persistence
        drop(bin);
        let bin = BinFile::open_with_secret(&path, "secret").unwrap();
        assert_eq!(bin.get_counter().unwrap(), 150);
    }

    #[test]
    fn test_reserve_counter_range_for_parallel_generation() {
        let temp_dir = TempDir::new().unwrap();
        let path = temp_dir.path().join("test.bin");

        let mut config = create_test_config("test");
        config.counter_mode = CounterMode::InBin;

        let mut bin = BinFile::create(&path, "secret", config).unwrap();

        // Reserve a range
        let start = bin.reserve_counter_range(1000).unwrap();

        // Generate codes at reserved counters (doesn't update counter again)
        let codes = bin.generate_batch_at(start, 10).unwrap();
        assert_eq!(codes.len(), 10);

        // Counter should still be at 1000 (reserved but not incremented again)
        assert_eq!(bin.get_counter().unwrap(), 1000);

        // All generated codes should be valid
        for code in &codes {
            assert!(bin.is_valid(code));
        }
    }

    #[test]
    fn test_reserve_counter_requires_full_access() {
        let temp_dir = TempDir::new().unwrap();
        let path = temp_dir.path().join("test.bin");

        let mut config = create_test_config("test");
        config.counter_mode = CounterMode::InBin;

        let _bin = BinFile::create(&path, "secret", config).unwrap();

        // Open readonly
        let mut bin = BinFile::open_readonly(&path).unwrap();

        // Try to reserve - should fail
        let result = bin.reserve_counter_range(100);
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            PromocryptError::SecretRequired
        ));
    }
}