feat(kdk-zeroize): add Sensitive + SensitiveMut traits (#7)

* feat(kdk-zeroize): add Sensitive + SensitiveMut traits

Enforce `expose_secret` and `expose_secret_mut` to sensitive types (e.g.
SensitiveMnemonic`).

Fix #6.

* test(kdk-zeroize): added tests for `Sensitive` trait

* chore(kdk-entropy): applied `prelude` call for zeroize on crates

Author: qlrd

crates/kdk-entropy/src/coin.rs

@@ -1,3 +1,4 @@
+use kdk_zeroize::prelude::*;
 use sha2::{Digest, Sha256};
 
 use crate::error::EntropyError;
@@ -32,6 +33,7 @@ pub const fn max_flips<const N: usize>() -> Result<usize, EntropyError> {
 ///
 /// ```
 /// use kdk_entropy::{coin_to_entropy, CoinEntropy};
+/// use kdk_zeroize::prelude::*;
 ///
 /// // SHA-256("0" * 128)[:16].
 /// let flips = [0u8; 128];

crates/kdk-entropy/src/deck.rs

@@ -1,3 +1,4 @@
+use kdk_zeroize::prelude::*;
 use sha2::{Digest, Sha256};
 
 use crate::error::EntropyError;
@@ -46,6 +47,7 @@ pub const fn max_draws<const CARDS: u8, const N: usize>() -> Result<usize, Entro
 ///
 /// ```
 /// use kdk_entropy::{deck_to_entropy, DeckEntropy};
+/// use kdk_zeroize::prelude::*;
 ///
 /// // SHA-256("0-1-2-3-...-24")[:16].
 /// let cards: [u8; 25] = [

crates/kdk-entropy/src/dice.rs

@@ -1,3 +1,4 @@
+use kdk_zeroize::prelude::*;
 use sha2::{Digest, Sha256};
 
 use crate::error::EntropyError;
@@ -38,6 +39,7 @@ pub const fn max_rolls<const FACES: u8, const N: usize>() -> Result<usize, Entro
 ///
 /// ```
 /// use kdk_entropy::{dice_to_entropy, DiceEntropy};
+/// use kdk_zeroize::prelude::*;
 ///
 /// // 50 d6 rolls (all "1") → SHA-256("1"*50) truncated to 16 bytes.
 /// // Same bytes Krux produces for the same input.

crates/kdk-entropy/tests/coin.rs

@@ -1,4 +1,5 @@
 use kdk_entropy::{coin_to_entropy, max_flips, min_flips, CoinEntropy, EntropyError};
+use kdk_zeroize::prelude::*;
 
 macro_rules! min_flips_ok {
     ($name:ident, $n:literal => $expected:literal) => {

crates/kdk-entropy/tests/deck.rs

@@ -1,4 +1,5 @@
 use kdk_entropy::{deck_to_entropy, max_draws, min_draws, DeckEntropy, EntropyError};
+use kdk_zeroize::prelude::*;
 
 macro_rules! min_draws_ok {
     ($name:ident, $cards:literal, $n:literal => $expected:literal) => {

crates/kdk-entropy/tests/dice.rs

@@ -1,4 +1,5 @@
 use kdk_entropy::{dice_to_entropy, max_rolls, min_rolls, DiceEntropy, EntropyError};
+use kdk_zeroize::prelude::*;
 
 macro_rules! min_rolls_ok {
     ($name:ident, $faces:literal, $n:literal => $expected:literal) => {

crates/kdk-zeroize/examples/sensitive.rs

@@ -6,15 +6,73 @@
 //! cargo run --example sensitive_lifecycle -p kdk-zeroize
 //! ```
 
-use kdk_zeroize::SensitiveBytes;
+use kdk_zeroize::prelude::*;
 
 pub enum AesKey {}
 pub enum SeedBytes {}
 
 type AesKey256 = SensitiveBytes<32, AesKey>;
 type Bip39Seed = SensitiveBytes<64, SeedBytes>;
 
-fn main() {
+use kdk_zeroize::wipe_in_place_mut;
+use zeroize::Zeroize;
+
+fn case<const N: usize>(label: &str, mut a: [u8; N], mut b: [u8; N]) {
+    assert_eq!(a, b, "{label}: inputs differ pre-wipe");
+    unsafe { wipe_in_place_mut(&mut a) };
+    b.zeroize();
+    assert_eq!(a, [0u8; N], "{label}: KDK didn't zero");
+    assert_eq!(b, [0u8; N], "{label}: zeroize didn't zero");
+    assert_eq!(a, b, "{label}: KDK and zeroize disagree");
+    println!("  {label}: OK");
+}
+
+fn zeroize_wipe() {
+    println!("kdk_zeroize::wipe_in_place_mut vs zeroize::Zeroize::zeroize");
+
+    case("[u8; 32] all 0xAA", [0xAAu8; 32], [0xAAu8; 32]);
+    case("[u8; 64] all 0xFF", [0xFFu8; 64], [0xFFu8; 64]);
+
+    let mut non_uniform = [0u8; 64];
+    for (i, x) in non_uniform.iter_mut().enumerate() {
+        *x = (i as u8).wrapping_add(0xA5);
+    }
+    case("[u8; 64] non-uniform", non_uniform, non_uniform);
+
+    // From here we will start a lot the `#[repr(C)]` attribute
+    #[repr(C)]
+    #[derive(Copy, Clone, PartialEq, Eq, Debug, Zeroize)]
+    struct Foo {
+        a: u32,
+        b: u64,
+        c: [u8; 8],
+    }
+    let init = Foo {
+        a: 0xDEADBEEF,
+        b: 0xCAFEBABE_F00DBABE,
+        c: [0xFFu8; 8],
+    };
+    let zero = Foo {
+        a: 0,
+        b: 0,
+        c: [0u8; 8],
+    };
+
+    let mut kdk_foo = init;
+    unsafe { wipe_in_place_mut(&mut kdk_foo) };
+    assert_eq!(kdk_foo, zero, "KDK struct wipe");
+
+    let mut zeroize_foo = init;
+    zeroize_foo.zeroize();
+    assert_eq!(zeroize_foo, zero, "zeroize struct wipe");
+
+    assert_eq!(kdk_foo, zeroize_foo, "struct: KDK and zeroize disagree");
+    println!("  Foo (struct): OK");
+
+    println!("PASS: KDK and zeroize produce byte-identical output across all cases.");
+}
+
+fn detach() {
     let key = AesKey256::new([0xAA; 32]);
     let seed = Bip39Seed::new([0x42; 64]);
 
@@ -41,3 +99,8 @@ fn main() {
         mixed.expose_secret()[2]
     );
 }
+
+fn main() {
+    zeroize_wipe();
+    detach();
+}

crates/kdk-zeroize/examples/wipe_vs_zeroize.rs

@@ -1,20 +1,15 @@
 //! SPDX-License-Identifier: MIT
 //!
-//! # Security
-//!
-//! > Every secret byte that touches memory in a KDK-built signer flows through
-//! > types defined here. A bug in this crate — a missed `Drop`, a leaky `Debug`,
-//! > a copy that escapes the wipe — silently breaks the amnesia guarantee across
-//! > EVERY downstream crate.
-//!
-//! # About
-//!
 //! Every KDK crate that touches secret bytes pulls **this** crate
 //! rather than `zeroize` directly. We aim to be an auditable-friendly project
 //! on level at purge secret bytes correctly.
 //!
 //! # Security notice
 //!
+//! > A bug in this crate — a missed `Drop`, a leaky `Debug`, a copy that
+//! > escapes the wipe — silently breaks the amnesia guarantee across
+//! > EVERY downstream crate.
+//!
 //! Treat this crate's API surface as a **published security contract**.
 //! Breaking changes here propagate amnesia regressions
 //! through every downstream crate.
@@ -24,4 +19,8 @@
 
 mod sensitive;
 
-pub use sensitive::{wipe_in_place_mut, SensitiveBytes};
+pub use sensitive::{wipe_in_place_mut, Sensitive, SensitiveBytes, SensitiveMut};
+
+pub mod prelude {
+    pub use crate::{Sensitive, SensitiveBytes, SensitiveMut};
+}

crates/kdk-zeroize/src/lib.rs

@@ -2,26 +2,26 @@ use core::fmt;
 use core::marker::PhantomData;
 use core::sync::atomic;
 
-/// `N` is the byte length and `O` is a chosen zero-sized type that lets the
-/// type system track where the bytes came from (BIP39 seed, dice entropy, AES
-/// key, decrypted KEF payload, etc...).
-///
-/// # Example
-///
-/// ```
-/// use kdk_zeroize::SensitiveBytes;
-///
-/// // A caller-chosen marker type.
-/// pub enum AesKey {}
-///
-/// type AesKey256 = SensitiveBytes<32, AesKey>;
-///
-///
-/// let key = AesKey256::new([0u8; 32]);
-/// ```
-pub struct SensitiveBytes<const N: usize, O> {
-    bytes: [u8; N],
-    _origin: PhantomData<O>,
+/// Disciplines yourself. This trait does NOT enforce:
+/// - `Drop` wipes the storage on out-of-scope.
+/// - Redacting `fmt::Debug` impl (never derive).
+/// - No `Clone` / no `Copy`.
+pub trait Sensitive {
+    /// The type whose bytes are the secret material.
+    type Inner: ?Sized;
+
+    /// Explicit-secret-access getter. Mirrors the inherent
+    /// `expose_secret` every sensitive type provides.
+    fn expose_secret(&self) -> &Self::Inner;
+}
+
+/// Read-only sensitive types (computed/derived values like a wrapped
+/// `bip39::Mnemonic`) impl only [`Sensitive`], not this trait —
+/// generic code that requires mutation takes `<S: SensitiveMut>` and
+/// will refuse those at compile time.
+pub trait SensitiveMut: Sensitive {
+    /// Mutable explicit-secret-access getter.
+    fn expose_secret_mut(&mut self) -> &mut Self::Inner;
 }
 
 /// Caller must ensure that after this function returns, **no code
@@ -46,6 +46,28 @@ pub unsafe fn wipe_in_place_mut<T>(value: &mut T) {
     }
 }
 
+/// `N` is the byte length and `O` is a chosen zero-sized type that lets the
+/// type system track where the bytes came from (BIP39 seed, dice entropy, AES
+/// key, decrypted KEF payload, etc...).
+///
+/// # Example
+///
+/// ```
+/// use kdk_zeroize::SensitiveBytes;
+///
+/// // A caller-chosen marker type.
+/// pub enum AesKey {}
+///
+/// type AesKey256 = SensitiveBytes<32, AesKey>;
+///
+///
+/// let key = AesKey256::new([0u8; 32]);
+/// ```
+pub struct SensitiveBytes<const N: usize, O> {
+    bytes: [u8; N],
+    _origin: PhantomData<O>,
+}
+
 impl<const N: usize, O> SensitiveBytes<N, O> {
     /// Wrap a `[u8; N]` as origin-tagged sensitive bytes.
     pub const fn new(bytes: [u8; N]) -> Self {
@@ -55,20 +77,9 @@ impl<const N: usize, O> SensitiveBytes<N, O> {
         }
     }
 
-    /// Explicit-secret-access getter. Prefer this over `as_slice`
-    /// when the bytes are about to be fed into a cryptographic
-    /// primitive — the name makes the secrecy visible in diffs.
-    pub fn expose_secret(&self) -> &[u8; N] {
-        &self.bytes
-    }
-
-    /// Mutable explicit-secret-access getter
-    pub fn expose_secret_mut(&mut self) -> &mut [u8; N] {
-        &mut self.bytes
-    }
-
-    /// Same bytes as `expose_secret`; the looser name is fine for
-    /// non-cryptographic reads (e.g. equality checks in tests).
+    /// Same bytes as `Sensitive::expose_secret`; the looser `&[u8]`
+    /// return is fine for non-cryptographic reads (e.g. equality
+    /// checks in tests).
     pub fn as_slice(&self) -> &[u8] {
         &self.bytes
     }
@@ -85,3 +96,17 @@ impl<const N: usize, O> fmt::Debug for SensitiveBytes<N, O> {
         f.write_str("SensitiveBytes(REDACTED)")
     }
 }
+
+impl<const N: usize, O> Sensitive for SensitiveBytes<N, O> {
+    type Inner = [u8; N];
+
+    fn expose_secret(&self) -> &[u8; N] {
+        &self.bytes
+    }
+}
+
+impl<const N: usize, O> SensitiveMut for SensitiveBytes<N, O> {
+    fn expose_secret_mut(&mut self) -> &mut [u8; N] {
+        &mut self.bytes
+    }
+}