secure_gate/lib.rs
1// src/lib.rs
2//! # secure-gate: Zero-cost secure wrappers for secrets
3//!
4//! This crate provides safe, ergonomic wrappers for handling sensitive data in memory
5//! with zero runtime overhead. It supports both stack-allocated fixed-size secrets
6//! and heap-allocated dynamic secrets, with optional automatic zeroing on drop.
7//!
8//! Key components:
9//! - [`Fixed<T>`]: Stack-allocated for fixed-size secrets (e.g., keys, nonces).
10//! - [`Dynamic<T>`]: Heap-allocated for dynamic secrets (e.g., passwords, vectors).
11//! - Zeroizing variants: [`FixedZeroizing<T>`] and [`DynamicZeroizing<T>`] for auto-wiping (with `zeroize` feature).
12//! - Macros: [`fixed_alias!`], [`dynamic_alias!`], [`secure!`], [`secure_zeroizing!`] for ergonomic usage.
13//!
14//! # Features
15//!
16//! - `zeroize`: Enables automatic memory wiping on drop via `zeroize` and `secrecy`.
17//! - `rand`: Enables [`SecureRandomExt::random()`] for generating fixed-size secrets.
18//! - `serde`: Optional serialization support (deserialization disabled for `Dynamic<T>` for security).
19//! - Works in `no_std` + `alloc` environments.
20//!
21//! # Quick Start
22//!
23//! ```
24//! use secure_gate::{dynamic_alias, fixed_alias, Dynamic, Fixed};
25//!
26//! fixed_alias!(Aes256Key, 32);
27//! dynamic_alias!(Password, String);
28//!
29//! let key: Aes256Key = [42u8; 32].into();
30//! let pw: Password = "hunter2".into();
31//!
32//! assert_eq!(key.expose_secret()[0], 42);
33//! assert_eq!(pw.expose_secret(), "hunter2");
34//! ```
35//!
36//! See individual modules for detailed documentation.
37
38#![cfg_attr(not(feature = "zeroize"), forbid(unsafe_code))]
39
40extern crate alloc;
41
42// Core modules
43mod dynamic;
44mod fixed;
45mod macros;
46
47// Feature-gated modules
48#[cfg(feature = "zeroize")]
49mod zeroize;
50
51#[cfg(feature = "serde")]
52mod serde;
53
54// Public API
55pub use dynamic::Dynamic;
56pub use fixed::Fixed;
57
58// Zeroize integration (opt-in)
59#[cfg(feature = "zeroize")]
60pub use zeroize::{DynamicZeroizing, FixedZeroizing};
61
62// Re-export Zeroizing cleanly — no privacy conflict
63#[cfg(feature = "zeroize")]
64pub type Zeroizing<T> = ::zeroize::Zeroizing<T>;
65
66// Re-export the trait and marker directly from the zeroize crate
67#[cfg(feature = "zeroize")]
68pub use ::zeroize::{Zeroize, ZeroizeOnDrop};
69
70// RNG integration (opt-in)
71#[cfg(feature = "rand")]
72pub mod rng;
73
74#[cfg(feature = "rand")]
75pub use rng::SecureRandomExt;