//! # SecMem
//!
//! A high-assurance, attack-resistant cryptographic memory allocator for Rust. 
//!
//! Designed to aggressively protect sensitive data (cryptographic keys, passwords, PII) 
//! from OS-level exploits, memory dumping, buffer overflows, and side-channel attacks.
//!
//! ## Feature Flags
//!
//! | Feature | Description | Default |
//! |---------|-------------|---------|
//! | `sec_mem` | Enables `SecMem`, the OS-level memory hardening container. Requires `libc` and Linux. | **Yes** |
//! | `encryption` | Enables ChaCha20/XOR-blinded encrypt-at-rest for `SecMem`. Stores the master key in `memfd_secret`. | **Yes** |
//! | `key_shielding`| Enables OpenSSH-style 16 KiB pre-key `blake3` derivation to heavily defend against side-channels. | **No** |
//! 
//! *(Note: `SecretBox` is always available and fully `no_std` compatible, regardless of features).*
//!
//! ## 1. Hardware-Accelerated OS Hardening (`SecMem`)
//! 
//! Available with the `sec_mem` feature. Uses raw Linux syscalls to create hardware-isolated memory.
//! 
//! *   **XOR-Blinded Encrypt-at-Rest**: Memory is dynamically ChaCha20/XOR masked.
//! *   **Optional Key Shielding**: Defeats Spectre/Rowhammer using an optional 16 KiB XOR-split pre-key and dynamic `blake3` derivation (`key_shielding` feature).
//! *   **Intel MPK**: Grants zero-syscall hardware isolation using `pkey_mprotect` and `WRPKRU`.
//! *   **Memory Sealing**: Uses `mseal` to permanently lock guard pages and permissions.
//! *   **mlock & Anti-Tracing**: Forces `mlock`, `MADV_DONTDUMP`, `MADV_DONTFORK`, and `PR_SET_DUMPABLE(0)`.
//!
//! ```rust
//! # #[cfg(feature = "sec_mem")]
//! # {
//! use sec_mem::SecMem;
//!
//! let mut secure_key = SecMem::new([0xAAu8; 32]);
//! secure_key.access_mut(|key| {
//!     key[0] = 0xBB;
//! }); // Hardware locks instantly engage on closure drop.
//! # }
//! ```
//! 
//! ## 2. Software-Enforced Memory Hardening (`SecretBox`)
//! 
//! A highly portable, stack-native, software-only wrapper requiring zero OS syscalls.
//! 
//! *   **Dynamic Volatile Canaries**: Generates randomized canaries at startup (`libc::getrandom` or `RDRAND`), verified via `core::ptr::read_volatile`.
//! *   **Strict Exclusive Access**: Enforces `&mut self` to mathematically eliminate concurrency race conditions.
//! *   **Closure-Restricted Lifetimes**: No `expose_secret()`. Uses strictly scoped injection closures (`.with_secret()`).
//!
//! ```rust
//! use sec_mem::SecretBox;
//! 
//! let mut portable_box = SecretBox::new(42u32);
//! portable_box.with_secret(|val| {
//!    assert_eq!(*val, 42);
//! }); // Stack canaries verified via volatile reads!
//! ```

#![cfg_attr(not(feature = "sec_mem"), no_std)]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![warn(missing_debug_implementations, missing_docs, rust_2018_idioms)]

#[cfg(feature = "sec_mem")]
mod sec_mem;
mod secret_box;

#[cfg(feature = "sec_mem")]
pub use sec_mem::{SecMem, SecretAccess, harden_process};
pub use secret_box::SecretBox;
pub use zeroize;
