envigil 0.2.0

Keep vigil over your environment — load, parse, and validate env vars with zero dependencies.
Documentation
//! A wrapper that prevents accidental leakage of sensitive values.
//!
//! [`Secret<T>`] implements `Debug` and `Display` as `[REDACTED]`,
//! so credentials never appear in logs, panic messages, or error
//! output by accident.
//!
//! # Examples
//!
//! ```
//! use envigil::Secret;
//!
//! let token = Secret::new("s3cret".to_owned());
//!
//! // Debug and Display are redacted:
//! assert_eq!(format!("{token:?}"), "Secret([REDACTED])");
//! assert_eq!(format!("{token}"), "[REDACTED]");
//!
//! // The inner value is available explicitly:
//! assert_eq!(token.expose(), "s3cret");
//! ```

use std::fmt;
use std::hash::{Hash, Hasher};

/// A wrapper that redacts its inner value in `Debug` and `Display`.
///
/// Use this for passwords, tokens, DSNs, and any value that must not
/// appear in logs.
///
/// # Examples
///
/// ```
/// use envigil::Secret;
///
/// let s = Secret::new("s3cret".to_owned());
/// assert_eq!(s.expose(), "s3cret");
/// assert_eq!(format!("{s:?}"), "Secret([REDACTED])");
/// ```
#[derive(Clone)]
pub struct Secret<T>(T);

impl<T> Secret<T> {
    /// Wrap a value.
    pub fn new(value: T) -> Self {
        Self(value)
    }

    /// Access the inner value.
    ///
    /// The name is deliberately verbose: every call site that reads
    /// a secret is visible in code review.
    pub fn expose(&self) -> &T {
        &self.0
    }

    /// Consume the wrapper and return the inner value.
    pub fn into_inner(self) -> T {
        self.0
    }

    /// Transform the inner value, preserving the wrapper.
    ///
    /// # Examples
    ///
    /// ```
    /// use envigil::Secret;
    ///
    /// let s = Secret::new("abc".to_owned());
    /// let len = s.map(|s| s.len());
    /// assert_eq!(*len.expose(), 3);
    /// ```
    pub fn map<U>(self, f: impl FnOnce(T) -> U) -> Secret<U> {
        Secret(f(self.0))
    }
}

impl<T: Default> Default for Secret<T> {
    fn default() -> Self {
        Self(T::default())
    }
}

impl<T> From<T> for Secret<T> {
    fn from(value: T) -> Self {
        Self(value)
    }
}

impl<T> AsRef<T> for Secret<T> {
    fn as_ref(&self) -> &T {
        &self.0
    }
}

impl<T> fmt::Debug for Secret<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("Secret([REDACTED])")
    }
}

impl<T> fmt::Display for Secret<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("[REDACTED]")
    }
}

impl<T: PartialEq> PartialEq for Secret<T> {
    fn eq(&self, other: &Self) -> bool {
        self.0 == other.0
    }
}

impl<T: Eq> Eq for Secret<T> {}

impl<T: Hash> Hash for Secret<T> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.0.hash(state);
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::collections::hash_map::DefaultHasher;

    #[test]
    fn debug_is_redacted() {
        let s = Secret::new("password123".to_owned());
        assert_eq!(format!("{s:?}"), "Secret([REDACTED])");
    }

    #[test]
    fn display_is_redacted() {
        let s = Secret::new("password123".to_owned());
        assert_eq!(format!("{s}"), "[REDACTED]");
    }

    #[test]
    fn expose_returns_inner() {
        let s = Secret::new(42u32);
        assert_eq!(*s.expose(), 42);
    }

    #[test]
    fn into_inner_consumes() {
        let s = Secret::new("token".to_owned());
        let inner: String = s.into_inner();
        assert_eq!(inner, "token");
    }

    #[test]
    fn map_transforms() {
        let s = Secret::new("abc".to_owned());
        let len = s.map(|s| s.len());
        assert_eq!(*len.expose(), 3);
        // The mapped value is also redacted:
        assert_eq!(format!("{len:?}"), "Secret([REDACTED])");
    }

    #[test]
    fn clone_works() {
        let s = Secret::new("x".to_owned());
        let s2 = s.clone();
        assert_eq!(s, s2);
    }

    #[test]
    fn partial_eq_compares_inner() {
        assert_eq!(Secret::new(1), Secret::new(1));
        assert_ne!(Secret::new(1), Secret::new(2));
    }

    #[test]
    fn from_conversion() {
        let s: Secret<String> = "hello".to_owned().into();
        assert_eq!(s.expose(), "hello");
    }

    #[test]
    fn as_ref_works() {
        let s = Secret::new(vec![1, 2, 3]);
        let v: &Vec<i32> = s.as_ref();
        assert_eq!(v.len(), 3);
    }

    #[test]
    fn default_works() {
        let s: Secret<String> = Secret::default();
        assert_eq!(s.expose(), "");
    }

    #[test]
    fn hash_delegates_to_inner() {
        let mut h1 = DefaultHasher::new();
        let mut h2 = DefaultHasher::new();

        Secret::new("same").hash(&mut h1);
        "same".hash(&mut h2);

        assert_eq!(h1.finish(), h2.finish());
    }

    #[test]
    fn secret_is_send_sync_when_t_is() {
        fn assert_send_sync<T: Send + Sync>() {}
        assert_send_sync::<Secret<String>>();
        assert_send_sync::<Secret<u64>>();
    }

    #[test]
    fn nested_secret_still_redacted() {
        let s = Secret::new(Secret::new("deep".to_owned()));
        // Outer Debug is redacted regardless of inner:
        assert_eq!(format!("{s:?}"), "Secret([REDACTED])");
        // Inner is accessible:
        assert_eq!(s.expose().expose(), "deep");
    }
}