secure_gate/
macros.rs

1// ==========================================================================
2// src/macros.rs
3// ==========================================================================
4
5/// Creates a type alias for a fixed-size secure secret.
6///
7/// This macro generates a type alias to `Fixed<[u8; N]>` with optional visibility.
8/// The generated type inherits all methods from `Fixed`, including `.expose_secret()`.
9///
10/// # Syntax
11///
12/// - `fixed_alias!(Name, size);` — public alias
13/// - `fixed_alias!(vis Name, size);` — custom visibility (e.g., `pub(crate)`)
14///
15/// # Examples
16///
17/// Basic public alias:
18/// ```
19/// use secure_gate::fixed_alias;
20/// fixed_alias!(Aes256Key, 32);
21/// let key = Aes256Key::new([0u8; 32]);
22/// assert_eq!(key.len(), 32);
23/// ```
24///
25/// With custom visibility:
26/// ```
27/// use secure_gate::fixed_alias;
28///
29/// // crate-visible only
30/// fixed_alias!(pub(crate) InternalKey, 64);
31///
32/// // visible only to the parent module (valid inside a module)
33/// // fixed_alias!(pub(in super) ModuleKey, 16);
34/// ```
35///
36/// `pub(in super)` and other path-based visibilities are fully supported
37/// when used inside real modules, but cannot be demonstrated in top-level doc-tests.
38///
39/// The generated type is zero-cost and works with all features.
40#[macro_export]
41macro_rules! fixed_alias {
42    // Full visibility control
43    ($vis:vis $name:ident, $size:literal) => {
44        #[doc = concat!("Fixed-size secure secret (", $size, " bytes)")]
45        $vis type $name = $crate::Fixed<[u8; $size]>;
46    };
47    // Convenience: default = pub
48    ($name:ident, $size:literal) => {
49        $crate::fixed_alias!(pub $name, $size);
50    };
51}
52
53/// Creates a generic (const-sized) fixed secure buffer type.
54///
55/// This macro generates a type alias to `Fixed<[u8; N]>` with a custom doc string.
56/// Useful for libraries providing generic secret buffers.
57///
58/// # Examples
59///
60/// With custom doc:
61/// ```
62/// use secure_gate::fixed_generic_alias;
63/// fixed_generic_alias!(GenericKey, "Generic secure key buffer");
64/// let key: GenericKey<32> = GenericKey::new([0u8; 32]);
65/// ```
66///
67/// Default doc and visibility:
68/// ```
69/// use secure_gate::fixed_generic_alias;
70/// fixed_generic_alias!(pub(crate) Buffer);
71/// let buf: Buffer<16> = Buffer::new([0u8; 16]);
72/// ```
73#[macro_export]
74macro_rules! fixed_generic_alias {
75    ($vis:vis $name:ident, $doc:literal) => {
76        #[doc = $doc]
77        $vis type $name<const N: usize> = $crate::Fixed<[u8; N]>;
78    };
79    ($name:ident, $doc:literal) => {
80        $crate::fixed_generic_alias!(pub $name, $doc);
81    };
82    ($vis:vis $name:ident) => {
83        #[doc = "Fixed-size secure byte buffer"]
84        $vis type $name<const N: usize> = $crate::Fixed<[u8; N]>;
85    };
86    ($name:ident) => {
87        $crate::fixed_generic_alias!(pub $name);
88    };
89}
90
91/// Creates a type alias for a random-only fixed-size secret.
92///
93/// This macro generates a type alias to `FixedRng<N>`, which can only be
94/// instantiated via `.generate()` (requires the "rand" feature).
95///
96/// # Examples
97///
98/// ```
99/// # #[cfg(feature = "rand")]
100/// # {
101/// use secure_gate::fixed_alias_rng;
102/// fixed_alias_rng!(MasterKey, 32);
103/// let key = MasterKey::generate();
104/// assert_eq!(key.len(), 32);
105/// # }
106/// ```
107#[macro_export]
108macro_rules! fixed_alias_rng {
109    ($vis:vis $name:ident, $size:literal) => {
110        #[doc = concat!("Random-only fixed-size secret (", $size, " bytes)")]
111        $vis type $name = $crate::rng::FixedRng<$size>;
112    };
113    ($name:ident, $size:literal) => {
114        $crate::fixed_alias_rng!(pub $name, $size);
115    };
116}
117
118/// Creates a type alias for a heap-allocated secure secret.
119///
120/// # Examples
121///
122/// ```
123/// use secure_gate::dynamic_alias;
124/// dynamic_alias!(Password, String);
125/// let pw: Password = "hunter2".into();
126/// assert_eq!(pw.expose_secret(), "hunter2");
127/// ```
128#[macro_export]
129macro_rules! dynamic_alias {
130    ($vis:vis $name:ident, $inner:ty) => {
131        #[doc = concat!("Secure heap-allocated ", stringify!($inner))]
132        $vis type $name = $crate::Dynamic<$inner>;
133    };
134    ($name:ident, $inner:ty) => {
135        $crate::dynamic_alias!(pub $name, $inner);
136    };
137}
138
139/// Creates a generic heap-allocated secure secret type alias.
140///
141/// # Examples
142///
143/// ```
144/// use secure_gate::dynamic_generic_alias;
145/// dynamic_generic_alias!(SecureVec, Vec<u8>, "Secure dynamic byte vector");
146/// let vec = SecureVec::new(vec![1, 2, 3]);
147/// assert_eq!(vec.len(), 3);
148/// ```
149#[macro_export]
150macro_rules! dynamic_generic_alias {
151    ($vis:vis $name:ident, $inner:ty, $doc:literal) => {
152        #[doc = $doc]
153        $vis type $name = $crate::Dynamic<$inner>;
154    };
155    ($name:ident, $inner:ty, $doc:literal) => {
156        $crate::dynamic_generic_alias!(pub $name, $inner, $doc);
157    };
158    ($vis:vis $name:ident, $inner:ty) => {
159        $crate::dynamic_generic_alias!(
160            $vis $name,
161            $inner,
162            concat!("Secure heap-allocated ", stringify!($inner))
163        );
164    };
165    ($name:ident, $inner:ty) => {
166        $crate::dynamic_generic_alias!(pub $name, $inner);
167    };
168}
secure_gate/macros.rs

secure_gate/
macros.rs
