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//! - `conversions`: **Optional** — adds `.to_hex()`, `.to_hex_upper()`, `.to_base64url()`, and `.ct_eq()` to all fixed-size secrets.
19//! - `serde`: Optional serialization support (deserialization disabled for `Dynamic<T>` for security).
20//! - Works in `no_std` + `alloc` environments.
21//!
22//! # Quick Start
23//!
24//! ```
25//! use secure_gate::{fixed_alias, dynamic_alias};
26//!
27//! fixed_alias!(Aes256Key, 32);
28//! dynamic_alias!(Password, String);
29//!
30//! // With `rand` feature
31//! #[cfg(feature = "rand")]
32//! {
33//! use secure_gate::SecureRandomExt;
34//! let key = Aes256Key::random(); // cryptographically secure
35//! let _ = key.expose_secret();
36//! }
37//!
38//! // With `conversions` feature
39//! #[cfg(all(feature = "rand", feature = "conversions"))]
40//! {
41//! use secure_gate::{SecureConversionsExt, SecureRandomExt};
42//! let key = Aes256Key::random();
43//! let hex = key.to_hex(); // "a1b2c3d4..."
44//! let b64 = key.to_base64url(); // safe for JSON
45//! assert!(key.ct_eq(&key)); // constant-time equality
46//! }
47//!
48//! // Heap secrets — beautiful ergonomics
49//! let pw: Password = "hunter2".into();
50//! assert_eq!(pw.expose_secret(), "hunter2");
51//! ```
52//!
53//! See individual modules for detailed documentation.
54
55#![cfg_attr(not(feature = "zeroize"), forbid(unsafe_code))]
56extern crate alloc;
57
58// Core modules
59mod dynamic;
60mod fixed;
61mod macros;
62
63// Feature-gated modules
64#[cfg(feature = "zeroize")]
65mod zeroize;
66
67#[cfg(feature = "serde")]
68mod serde;
69
70#[cfg(feature = "conversions")]
71mod conversions;
72
73// Public API
74pub use dynamic::Dynamic;
75pub use fixed::Fixed;
76
77// Zeroize integration (opt-in)
78#[cfg(feature = "zeroize")]
79pub use zeroize::{DynamicZeroizing, FixedZeroizing};
80
81// Re-export Zeroizing cleanly — no privacy conflict
82#[cfg(feature = "zeroize")]
83pub type Zeroizing<T> = ::zeroize::Zeroizing<T>;
84
85#[cfg(feature = "zeroize")]
86pub use ::zeroize::{Zeroize, ZeroizeOnDrop};
87
88// RNG integration (opt-in)
89#[cfg(feature = "rand")]
90pub mod rng;
91
92#[cfg(feature = "rand")]
93pub use rng::SecureRandomExt;
94
95// Conversions integration (opt-in)
96#[cfg(feature = "conversions")]
97pub use conversions::SecureConversionsExt;