secure_gate/traits/
mod.rs

1//! Traits for polymorphic secret handling.
2//!
3//! > **Note:** All traits in this module are re-exported at the crate root
4//! > (`secure_gate::RevealSecret`, not `secure_gate::traits::RevealSecret`).
5//! > You should never need to import from `secure_gate::traits::*` directly.
6//!
7//! This module defines the core traits that enable generic, zero-cost, and secure
8//! operations across different secret wrapper types (`Fixed<T>`, `Dynamic<T>`, etc.).
9//! These traits allow writing polymorphic code that preserves strong security invariants:
10//! explicit access, controlled mutability, timing safety, and opt-in risk features.
11//!
12//! # Core Traits
13//!
14//! | Trait                  | Purpose                                      | Requires Feature         | Notes                                                                 |
15//! |------------------------|----------------------------------------------|--------------------------|-----------------------------------------------------------------------|
16//! | [`RevealSecret`]       | Read-only scoped / direct access + metadata  | Always available         | Preferred: `with_secret` (scoped); escape hatch: `expose_secret`      |
17//! | [`RevealSecretMut`]    | Mutable scoped / direct access               | Always available         | Same preference: `with_secret_mut` over `expose_secret_mut`           |
18//! | [`SentinelValue`]      | Inert placeholder left by `into_inner`       | Always available         | Implemented for `[T; N]` (any `N`), `String`, `Vec<T>`                |
19//! | [`ConstantTimeEq`]     | Deterministic constant-time equality         | `ct-eq`                  | Timing-attack resistant byte comparison                               |
20//! | [`CloneableSecret`]    | Opt-in marker for safe cloning               | `cloneable`              | Requires explicit impl on inner type; zeroize preserved. See [`SECURITY.md`](https://github.com/Slurp9187/secure-gate/blob/main/SECURITY.md) for opt-in risk details. |
21//! | [`SerializableSecret`] | Opt-in marker for Serde serialization        | `serde-serialize`        | Serialization exposes secret — use with extreme caution. See [`SECURITY.md`](https://github.com/Slurp9187/secure-gate/blob/main/SECURITY.md) for opt-in risk details. |
22//! | [`SecureEncoding`]     | Marker + blanket impl for encoding traits    | Any `encoding-*`         | Enables `ToHex`, `ToBase64Url`, `ToBech32`, `ToBech32m`               |
23//! | [`SecureDecoding`]     | Marker + blanket impl for decoding traits    | Any `encoding-*`         | Enables `FromHexStr`, `FromBase64UrlStr`, `FromBech32Str`, etc.       |
24//!
25//! # Security Guarantees
26//!
27//! - **No implicit access** — All secret data access requires explicit trait methods
28//! - **Scoped preference** — `with_secret` / `with_secret_mut` limit borrow lifetime
29//! - **Zero-cost** — All methods use `#[inline(always)]` where possible
30//! - **Timing safety** — `ConstantTimeEq` provides constant-time equality
31//! - **Opt-in risk** — Cloning and serialization require deliberate marker impls
32//! - **Read-only enforcement** — Encoding wrappers and random types only expose immutable access
33//!
34//! # Feature Gates
35//!
36//! Some traits are only available when their corresponding Cargo features are enabled:
37//!
38//! - `ct-eq`          → [`ConstantTimeEq`]
39//! - `cloneable`      → [`CloneableSecret`]
40//! - `serde-serialize`→ [`SerializableSecret`]
41//! - `encoding-*`     → [`SecureEncoding`], [`SecureDecoding`], and per-format traits
42//!
43//! The encoding traits (`ToHex`, `FromHexStr`, etc.) are re-exported from submodules for convenience.
44//!
45//! See individual trait docs for detailed usage and examples.
46
47pub mod revealed_secrets;
48pub use revealed_secrets::InnerSecret;
49
50#[cfg(feature = "alloc")]
51pub use revealed_secrets::EncodedSecret;
52
53pub mod reveal_secret;
54pub use reveal_secret::RevealSecret;
55
56pub mod reveal_secret_mut;
57pub use reveal_secret_mut::RevealSecretMut;
58
59pub mod sentinel_value;
60pub use sentinel_value::SentinelValue;
61
62#[cfg(feature = "ct-eq")]
63pub mod constant_time_eq;
64#[cfg(feature = "ct-eq")]
65pub use constant_time_eq::ConstantTimeEq;
66
67pub mod decoding;
68pub mod encoding;
69
70// Re-export per-format decoding traits (feature-gated; blanket impls return Vec<u8> — alloc required)
71#[cfg(all(feature = "encoding-base64", feature = "alloc"))]
72pub use decoding::FromBase64UrlStr;
73
74#[cfg(all(feature = "encoding-bech32", feature = "alloc"))]
75pub use decoding::FromBech32Str;
76
77#[cfg(all(feature = "encoding-bech32m", feature = "alloc"))]
78pub use decoding::FromBech32mStr;
79
80#[cfg(all(feature = "encoding-hex", feature = "alloc"))]
81pub use decoding::FromHexStr;
82
83// Re-export per-format encoding traits (feature-gated)
84// Note: blanket impls of ToBase64Url, ToBech32, ToBech32m require alloc (String output).
85// The traits themselves are exported unconditionally so inherent methods on Fixed/Dynamic
86// can call them; the blanket impls gate the alloc dependency.
87#[cfg(all(feature = "encoding-base64", feature = "alloc"))]
88pub use encoding::ToBase64Url;
89
90#[cfg(all(feature = "encoding-bech32", feature = "alloc"))]
91pub use encoding::ToBech32;
92
93#[cfg(all(feature = "encoding-bech32m", feature = "alloc"))]
94pub use encoding::ToBech32m;
95
96#[cfg(all(feature = "encoding-hex", feature = "alloc"))]
97pub use encoding::ToHex;
98
99/// Marker trait for types that support secure encoding operations.
100///
101/// Automatically implemented for any type that implements `AsRef<[u8]>`,
102/// such as `&[u8]`, `Vec<u8>`, `[u8; N]`, etc. This enables blanket impls
103/// of the individual encoding traits (`ToHex`, `ToBase64Url`, `ToBech32`, etc.).
104///
105/// Since this is a marker trait (no methods), it exists only to allow trait
106/// bounds and extension methods to be available where appropriate.
107///
108/// Requires at least one `encoding-*` feature to be enabled.
109#[cfg(any(
110    feature = "encoding-hex",
111    feature = "encoding-base64",
112    feature = "encoding-bech32",
113    feature = "encoding-bech32m",
114))]
115pub trait SecureEncoding {}
116
117#[cfg(any(
118    feature = "encoding-hex",
119    feature = "encoding-base64",
120    feature = "encoding-bech32",
121    feature = "encoding-bech32m",
122))]
123impl<T: AsRef<[u8]> + ?Sized> SecureEncoding for T {}
124
125/// Marker trait for types that support secure decoding operations.
126///
127/// Automatically implemented for any type that implements `AsRef<str>`,
128/// such as `&str`, `String`, etc. This enables blanket impls of the
129/// individual decoding traits (`FromHexStr`, `FromBase64UrlStr`, etc.).
130///
131/// Like `SecureEncoding`, this is a marker trait with no methods — it exists
132/// to allow trait bounds and extension methods where relevant.
133///
134/// Requires at least one `encoding-*` feature to be enabled.
135#[cfg(any(
136    feature = "encoding-hex",
137    feature = "encoding-base64",
138    feature = "encoding-bech32",
139    feature = "encoding-bech32m",
140))]
141pub trait SecureDecoding {}
142
143#[cfg(any(
144    feature = "encoding-hex",
145    feature = "encoding-base64",
146    feature = "encoding-bech32",
147    feature = "encoding-bech32m",
148))]
149impl<T: AsRef<str> + ?Sized> SecureDecoding for T {}
150
151#[cfg(feature = "cloneable")]
152pub mod cloneable_secret;
153#[cfg(feature = "cloneable")]
154pub use cloneable_secret::CloneableSecret;
155
156#[cfg(feature = "serde-serialize")]
157pub mod serializable_secret;
158#[cfg(feature = "serde-serialize")]
159pub use serializable_secret::SerializableSecret;
secure_gate/traits/mod.rs

secure_gate/traits/
mod.rs
