Add redaction control based on environment variables

Cargo.toml

@@ -7,7 +7,19 @@ license = "MIT"
 repository = "https://github.com/primait/veil"
 
 [workspace]
-members = ["veil-macros", "veil-tests"]
+members = [
+    "veil-macros",
+    "veil-tests",
+    "veil-tests/environment-aware",
+    "veil-tests/environment-aware-fallback-on",
+    "veil-tests/environment-aware-fallback-off",
+    "veil-tests/environment-aware-fallback-panic",
+    "veil-tests/environment-aware-disable",
+]
+
+[features]
+environment-aware = ["veil-macros/environment-aware", "lazy_static"]
 
 [dependencies]
-veil-macros = { path = "veil-macros" }
+veil-macros = { path = "veil-macros" }
+lazy_static = { version = "1", optional = true }

README.md

@@ -85,3 +85,40 @@ enum InsuranceStatus {
     },
 }
 ```
+
+# Environment Awareness
+
+You can configure Veil to redact or skip redacting data based on environment variables. Enable the `environment-aware` Cargo feature like so in your Cargo.toml:
+
+```toml
+[dependencies]
+veil = { version = "0.1", features = ["environment-aware"] }
+```
+
+## `VEIL_DISABLE_REDACTION`
+
+Redaction can be completely disabled by setting the `VEIL_DISABLE_REDACTION` environment variable. This is only checked once during the program lifetime for security purposes.
+
+## `.veil.toml`
+
+Redaction can also be configured on a per-project basis using a `.veil.toml` file. Put this file in your crate or workspace root and Veil will read it at compile time.
+
+**Please note, if you change the file, Veil won't see the changes until you do a clean build of your crate.**
+
+### Example
+
+`APP_ENV` is just an example here. You can match multiple environment variables with any UTF-8 name and value(s).
+
+```toml
+[env.APP_ENV]
+redact = ["production", "staging"] # redact data if "APP_ENV" is set to any of these values
+skip-redact = ["dev", "qa"] # SKIP redacting data if "APP_ENV" is set to any of these values
+
+# If "APP_ENV" isn't set or isn't recognised...
+[fallback]
+redact = true # do redact data (default)
+# OR
+redact = false # don't redact data
+# OR
+redact = "panic" # panic at runtime
+```

src/lib.rs

@@ -199,6 +199,43 @@
 //! }
 //! ```
 //!
+//! # Environment Awareness
+//!
+//! You can configure Veil to redact or skip redacting data based on environment variables. Enable the `environment-aware` Cargo feature like so in your Cargo.toml:
+//!
+//! ```toml
+//! [dependencies]
+//! veil = { version = "0.1", features = ["environment-aware"] }
+//! ```
+//!
+//! ## `VEIL_DISABLE_REDACTION`
+//!
+//! Redaction can be completely disabled by setting the `VEIL_DISABLE_REDACTION` environment variable. This is only checked once during the program lifetime for security purposes.
+//!
+//! ## `.veil.toml`
+//!
+//! Redaction can also be configured on a per-project basis using a `.veil.toml` file. Put this file in your crate or workspace root and Veil will read it at compile time.
+//!
+//! **Please note, if you change the file, Veil won't see the changes until you do a clean build of your crate.**
+//!
+//! ### Example
+//!
+//! `APP_ENV` is just an example here. You can match multiple environment variables with any UTF-8 name and value(s).
+//!
+//! ```toml
+//! [env.APP_ENV]
+//! redact = ["production", "staging"] # redact data if "APP_ENV" is set to any of these values
+//! skip-redact = ["dev", "qa"] # SKIP redacting data if "APP_ENV" is set to any of these values
+//!
+//! ## If "APP_ENV" isn't set or isn't recognised...
+//! [fallback]
+//! redact = true # do redact data (default)
+//! ## OR
+//! redact = false # don't redact data
+//! ## OR
+//! redact = "panic" # panic at runtime
+//! ```
+//!
 //! # Limitations
 //!
 //! Currently, this macro only supports [`std::fmt::Debug`] formatting with no modifiers (`{:?}`) or the "alternate" modifier (`{:#?}`).

src/private.rs

@@ -107,9 +107,22 @@ impl RedactFlags {
     }
 }
 
-pub fn redact(this: &dyn Debug, flags: RedactFlags) -> DisplayDebug {
+pub fn redact(
+    this: &dyn Debug,
+    flags: RedactFlags,
+    #[cfg(feature = "environment-aware")] env_is_redaction_enabled: bool,
+) -> DisplayDebug {
     let mut redacted = String::new();
 
+    #[cfg(feature = "environment-aware")]
+    if !env_is_redaction_enabled {
+        return DisplayDebug(if flags.debug_alternate {
+            format!("{:#?}", this)
+        } else {
+            format!("{:?}", this)
+        });
+    }
+
     (|| {
         if flags.fixed > 0 {
             flags.redact_fixed(flags.fixed as usize, &mut redacted);
@@ -152,3 +165,25 @@ pub fn redact(this: &dyn Debug, flags: RedactFlags) -> DisplayDebug {
 
     DisplayDebug(redacted)
 }
+
+#[cfg(feature = "environment-aware")]
+pub fn env_is_redaction_enabled() -> Option<bool> {
+    // First check VEIL_DISABLE_REDACTION, which overrides any config file
+    lazy_static::lazy_static! {
+        // We deliberately only look this up once.
+        // If an attacker somehow is able to change environment variables, we don't want to give them a way of revealing sensitive data.
+        static ref IS_REDACTION_DISABLED: bool = std::env::var("VEIL_DISABLE_REDACTION").is_ok();
+    }
+    if *IS_REDACTION_DISABLED {
+        return Some(false);
+    }
+
+    // We'll run the `env_is_redaction_enabled!` macro here
+    // This is handled by the `fmt` module
+    // This is needed because we need CARGO_MANIFEST_DIR to be set by the crate being built,
+    // rather than this crate itself!
+    None
+}
+
+#[cfg(feature = "environment-aware")]
+pub use veil_macros::env_is_redaction_enabled;