secure_gate/traits/
expose_secret_mut.rs

1//! # Mutable Secret Exposure Traits
2//!
3//! This module defines the trait for mutable access to secrets.
4//!
5//! ## Key Traits
6//!
7//! - [`ExposeSecretMut`]: Mutable access to secret values
8//!
9//! ## Security Model
10//!
11//! - **Mutable access**: Only core wrappers ([`crate::Fixed`], [`crate::Dynamic`]) implement [`ExposeSecretMut`]
12//! - **Zero-cost**: All implementations use `#[inline(always)]`
13use crate::ExposeSecret;
14
15/// ## Usage
16///
17/// Import this trait to enable `.with_secret_mut()` and `.expose_secret_mut()`.
18/// Extends [`ExposeSecret`], so read access and metadata are also available.
19/// Trait for mutable access to secrets.
20///
21/// Extends [`ExposeSecret`], so metadata and read access are included.
22/// Inherits `.len()` and `.is_empty()` from [`ExposeSecret`].
23/// Import this for `.with_secret_mut()` and `.expose_secret_mut()`.
24///
25/// ## Security Note
26///
27/// Prefer `with_secret_mut` for scoped access to avoid accidental leaks through long-lived borrows.
28/// `expose_secret_mut` is provided for cases where a direct mutable reference is needed, but use with caution.
29pub trait ExposeSecretMut: ExposeSecret {
30    /// Provide scoped mutable access to the secret.
31    ///
32    /// This is the preferred method for mutating secrets, as it prevents accidental leaks
33    /// through long-lived mutable borrows. The closure receives a mutable reference to the inner secret
34    /// and returns a value.
35    ///
36    /// # Examples
37    ///
38    /// ```
39    /// use secure_gate::{Fixed, ExposeSecretMut};
40    /// let mut secret = Fixed::new([0u8; 4]);
41    /// secret.with_secret_mut(|bytes| {
42    ///     bytes[0] = 42;
43    /// });
44    /// ```
45    fn with_secret_mut<F, R>(&mut self, f: F) -> R
46    where
47        F: FnOnce(&mut Self::Inner) -> R;
48
49    /// Expose the secret for mutable access.
50    ///
51    /// # Security Warning
52    ///
53    /// This returns a direct mutable reference that can be accidentally leaked. Prefer `with_secret_mut`
54    /// for most use cases to ensure the secret is only mutated within a controlled scope.
55    fn expose_secret_mut(&mut self) -> &mut Self::Inner;
56}
secure_gate/traits/expose_secret_mut.rs

secure_gate/traits/
expose_secret_mut.rs
