secure_gate/traits/
mod.rs

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

secure_gate/traits/
mod.rs
