Redaction

redaction helps you keep sensitive values (tokens, secrets, PII) out of places they don't belong by:

Deriving Sensitive on your types with #[derive(Sensitive)]
Marking sensitive fields with #[sensitive] or #[sensitive(Classification)]
Calling .redact() to produce a copy that is safe to log or serialize
Generating Debug output that prints "[REDACTED]" for sensitive fields (independent of policies)

Design (DDD / Clean Architecture friendly)

Classifications are domain concepts: marker types like Secret, Token, or your own InternalId represent what kind of data a field contains.
Policies belong in the application layer: policies are attached to classification types (impl RedactionPolicy for MyClassification) in the layer where you define "what is safe to expose", typically close to logging/serialization boundaries.
Sinks are optional adapters: integrations like slog live behind feature flags; your domain types don't depend on a logging framework.
Layering is optional: you can put classifications, policies, and redaction calls in a single crate if you prefer. The library supports both "clean architecture" layering and simple, pragmatic project layouts.

The Problem

Sensitive data ends up places it shouldn't:

Logging: Structured logs capture request/response bodies containing passwords, tokens, PII
Serialization: API responses, database exports, and message queues include fields that should be hidden
Error reporting: Stack traces and error contexts expose sensitive state
Debug output: #[derive(Debug)] prints everything, including secrets

Once sensitive data reaches these systems, it is often:

Stored long-term (retention policies, backups)
Indexed and searchable
Replicated across environments
Visible to anyone with access to logs/telemetry

#[derive(Debug, serde::Serialize)]
struct LoginRequest {
    username: String,
    password: String,
}

let request = LoginRequest {
    username: "alice".into(),
    password: "hunter2".into(),
};

// Debug output exposes the password
println!("{:?}", request);
// → LoginRequest { username: "alice", password: "hunter2" }

// Serialization also exposes the password
let json = serde_json::to_string(&request).unwrap();
// → {"username":"alice","password":"hunter2"}
//
// (This example uses `serde_json` to make the risk concrete. The same problem
// exists with any serializer that includes `password`.)

The Solution

Mark sensitive fields explicitly. This crate provides:

Safe Debug: sensitive fields print as [REDACTED]
Explicit redaction: call .redact() to get a copy safe for serialization and logging
Policy control: choose how each classification is redacted (full, keep, mask)
External type support: types you don't control (like chrono::DateTime) just work

use redaction::{Redactable, Secret, Token, Sensitive};

#[derive(Clone, Sensitive)]
struct LoginRequest {
    username: String,
    #[sensitive(Secret)]
    password: String,
    #[sensitive(Token)]
    api_key: String,
}

let request = LoginRequest {
    username: "alice".into(),
    password: "hunter2".into(),
    api_key: "tok_live_abcdef".into(),
};

// Get a redacted copy for serialization, APIs, and logging
let safe = request.redact();
assert_eq!(safe.password, "[REDACTED]");       // Secret: fully redacted
assert_eq!(safe.api_key, "***********cdef");  // Token: only last 4 visible
assert_eq!(safe.username, "alice");            // Not sensitive: unchanged

// Debug output is also safe, but it does NOT apply policies:
// it always prints `"[REDACTED]"` for `#[sensitive(...)]` fields.
println!("{:?}", request);
// → LoginRequest { username: "alice", password: "[REDACTED]", api_key: "[REDACTED]" }

Installation

[dependencies]
redaction = "0.1"

Basic Usage

Add #[derive(Clone, Sensitive)] to your type
Mark sensitive fields with #[sensitive] or #[sensitive(Classification)]
Call .redact() before you log, serialize, return, or persist the value

use redaction::{Redactable, Secret, Token, Sensitive};

#[derive(Clone, Sensitive)]
struct ApiCredentials {
    #[sensitive(Secret)]
    password: String,
    #[sensitive(Token)]
    api_key: String,
    user_id: String,  // not sensitive, passed through unchanged
}

let creds = ApiCredentials {
    password: "super_secret".into(),
    api_key: "tok_live_abcdef".into(),
    user_id: "user_42".into(),
};

let redacted = creds.redact();
assert_eq!(redacted.password, "[REDACTED]");  // Secret → fully redacted
assert_eq!(redacted.api_key, "***********cdef"); // Token → only last 4 visible
assert_eq!(redacted.user_id, "user_42");      // unchanged

Field Attributes

The #[sensitive(...)] attribute controls how each field is handled:

Attribute	Use For	Behavior
(none)	Non-sensitive fields, external types	Pass through unchanged
`#[sensitive]`	Scalars OR nested `Sensitive` types	Walk containers, or redact scalars to default
`#[sensitive(Class)]`	String-like leaf values	Apply classification's redaction policy

Classifications are for string-like leaf values; the field type must implement SensitiveValue and Classifiable.

Examples

use redaction::{Redactable, Secret, Sensitive};

#[derive(Clone, Sensitive)]
struct Address {
    #[sensitive(Secret)]
    street: String,
    city: String,        // Not sensitive
}

#[derive(Clone, Sensitive)]
struct User {
    #[sensitive(Secret)]
    ssn: String,         // Leaf value: apply Secret policy
    
    #[sensitive]
    address: Address,    // Nested struct: walk into it
    
    #[sensitive]
    age: i32,            // Scalar: redact to default (0)
    
    created_at: DateTime<Utc>,  // External type: passes through unchanged
    balance: Decimal,           // External type: passes through unchanged
}

External Types Just Work

Fields without #[sensitive] pass through unchanged. This means external types like chrono::DateTime, rust_decimal::Decimal, uuid::Uuid, or any type you don't control work automatically. Do not add #[sensitive] unless the type implements SensitiveType.

use chrono::{DateTime, Utc};

#[derive(Clone, Sensitive)]
struct Transaction {
    #[sensitive(Secret)]
    account_number: String,
    
    // No annotation needed - external types pass through!
    timestamp: DateTime<Utc>,
    amount: Decimal,
    id: Uuid,
}

Nested Sensitive Types

When a field's type also derives Sensitive, use #[sensitive] to walk into it:

#[derive(Clone, Sensitive)]
struct Credentials {
    #[sensitive(Secret)]
    password: String,
}

#[derive(Clone, Sensitive)]
struct User {
    #[sensitive]  // Walk into Credentials
    creds: Credentials,
}

Important: Without #[sensitive], nested structs pass through unchanged (even if they derive Sensitive). This is by design - you explicitly choose what to redact.

Nested Wrapper Classifications

Classifications work on nested wrapper types like Option<Vec<String>> automatically:

#[derive(Clone, Sensitive)]
struct User {
    #[sensitive(Pii)]
    emails: Option<Vec<String>>,  // Works! Recursively applies Pii to each String
    
    #[sensitive(Secret)]
    backup_codes: Vec<Option<String>>,  // Also works!
    
    #[sensitive(Secret)]
    metadata: HashMap<String, Vec<String>>,  // Maps work too!
}

The classification is applied recursively through any nesting depth of:

Option<T>
Vec<T>
Box<T>
HashMap<K, V> (values only)
BTreeMap<K, V> (values only)
HashSet<T> / BTreeSet<T>
Result<T, E>

Built-in Classifications

Each classification has a default redaction policy. Use the one that matches your data:

Classification	Use for	Example output
`Secret`	Passwords, private keys	`[REDACTED]`
`Token`	API keys, bearer tokens	`…abcd` (last 4)
`Email`	Email addresses	`jo…` (first 2)
`CreditCard`	Card numbers (PANs)	`…1234` (last 4)
`Pii`	Generic PII	`…_doe` (last 4)
`PhoneNumber`	Phone numbers	`…12` (last 2)
`NationalId`	SSN, passport numbers	`…6789` (last 4)
`AccountId`	Account identifiers	`…abcd` (last 4)
`SessionId`	Session tokens	`…wxyz` (last 4)
`IpAddress`	IP addresses	`…1.1` (last 4 chars)
`DateOfBirth`	Birth dates	`[REDACTED]`
`BlockchainAddress`	Wallet addresses	`…abc123` (last 6)

Custom Classifications

When built-in classifications don't fit, create your own:

use redaction::{Classification, RedactionPolicy, TextRedactionPolicy};

#[derive(Clone, Copy)]
struct InternalId;
impl Classification for InternalId {}

impl RedactionPolicy for InternalId {
    fn policy() -> TextRedactionPolicy {
        TextRedactionPolicy::keep_last(2)  // Show only last 2 characters
    }
}

Clean architecture note:

Put the classification type (InternalId) in your domain crate/module.
Put the policy implementation (impl RedactionPolicy for InternalId) in your application or infrastructure layer (where you define what is safe to expose and where logging/serialization happens).

Then use it like any built-in:

#[derive(Clone, Sensitive)]
struct Record {
    #[sensitive(InternalId)]
    id: String,
}

Policies

Three policy types control how values are transformed:

Full: replace the entire value with a placeholder

TextRedactionPolicy::default_full()           // → "[REDACTED]"
TextRedactionPolicy::full_with("<hidden>")    // → "<hidden>"

Keep: keep specified characters visible, mask everything else

TextRedactionPolicy::keep_first(4)            // "secret123" → "secr*****"
TextRedactionPolicy::keep_last(4)             // "secret123" → "*****t123"
TextRedactionPolicy::keep_with(KeepConfig::both(2, 2))  // "secret" → "se**et"

Mask: mask specified characters, keep the rest visible

TextRedactionPolicy::mask_first(4)            // "secret123" → "****et123"
TextRedactionPolicy::mask_last(4)             // "secret123" → "secre****"

Logging with slog

With the slog feature, Sensitive types automatically redact when logged as structured JSON:

[dependencies]
redaction = { version = "0.1", features = ["slog"] }

#[derive(Clone, Sensitive)]
#[cfg_attr(feature = "slog", derive(serde::Serialize))]
struct LoginEvent {
    #[sensitive(Secret)]
    password: String,
    username: String,
}

// Redacts automatically (no explicit .redact() needed)
slog::info!(logger, "login"; "event" => event);

Structured JSON requirements (why they exist):

Type must implement Clone so the redacted JSON payload can be built without consuming the original value.
Type must implement serde::Serialize because structured logging emits JSON derived from the redacted copy.
The slog adapter uses IntoRedactedJson, which is auto-implemented for Redactable + Serialize.

If those bounds are too strict, use SensitiveError instead to log a redacted string without requiring Serialize.

Logging errors without Serialize

For types that cannot or should not derive Serialize, use SensitiveError. It emits the same redacted Debug output, but logs as a string using a redacted display template rather than JSON:

use redaction::{Secret, SensitiveError};

#[derive(SensitiveError)]
enum LoginError {
    #[error("invalid login for {username} {password}")]
    InvalidCredentials {
        username: String,
        #[sensitive(Secret)]
        password: String,
    },
    Io(std::io::Error), // not serializable
}

slog::error!(logger, "login failed"; "error" => err);

This path does not require Serialize on the type. SensitiveError generates a RedactedDisplay implementation used by the slog adapter, so your error’s normal Display (from thiserror or displaydoc) can remain unchanged while logs still use a redacted string.

Template rules and bounds:

Template required: #[error("...")] or doc comments (derive fails otherwise)
Pass-through {field} uses Display; {field:?} uses Debug
#[sensitive(Classification)] in template: Clone + Display (or Debug for :?)
#[sensitive] scalars use defaults (no extra bounds)
#[sensitive] non-scalars in template must derive SensitiveError

Feature flags

classification (default): built-in classification types
policy (default): redaction policies and .redact()
slog: structured logging adapter
testing: unredacted Debug output in tests

Reference

Trait Bound Summary

Traversal: #[sensitive] on non-scalars requires SensitiveType
Classification: #[sensitive(Classification)] requires Classifiable
Debug: fields shown in Debug output require Debug
slog JSON (Sensitive): the type itself requires Clone + Serialize + IntoRedactedJson
slog string (SensitiveError): see template rules above (bounds are template-dependent)

Trait Concepts

The library uses these core traits, organized by layer:

Domain Layer (what is sensitive):

Trait	Purpose	Implemented By
`SensitiveType`	Types that contain sensitive data	Structs/enums deriving `Sensitive`
`SensitiveValue`	Types that are sensitive data	`String`, `Cow<str>`, custom newtypes

Policy Layer (how to redact):

Trait	Purpose	Implemented By
`RedactionPolicy`	Maps classification → redaction strategy	Your custom classifications
`TextRedactionPolicy`	Concrete string transformations	Built-in (Full, Keep, Mask)

Application Layer (redaction machinery):

Trait	Purpose	Implemented By
`Classifiable`	Types that can have classifications applied	`String`, wrappers (`Option`, `Vec`, etc.)
`Redactable`	User-facing `.redact()` method	Auto-implemented for `SensitiveType`
`RedactionMapper`	Internal traversal machinery	`#[doc(hidden)]`

Use #[sensitive] on fields of SensitiveType types (to walk into them)
Use #[sensitive(Classification)] on fields of Classifiable types (supports nested wrappers)

Supported field types

String-like (SensitiveValue): Use #[sensitive(Classification)]:

String
Cow<'_, str> (redaction returns an owned value)

Scalars: Use bare #[sensitive] (no classification):

Integers: i8-i128, u8-u128, isize, usize
Floats: f32, f64
bool → redacts to false
char → redacts to 'X'

Containers (SensitiveType): Use #[sensitive] to walk, or omit for pass-through:

Option<T>: redacts inner value if present
Vec<T>: redacts all elements
Box<T>: redacts inner value
HashMap<K, V>, BTreeMap<K, V>: redacts values only (keys unchanged)
HashSet<T>, BTreeSet<T>: redacts elements
Result<T, E>: redacts both Ok and Err sides

External types: No annotation needed (pass through):

chrono::DateTime<Tz>, rust_decimal::Decimal, uuid::Uuid, etc.
Any type that doesn't implement SensitiveType

PhantomData: Automatically handled (pass through, no trait bounds added).

Compiler Error Messages

The library provides helpful error messages for common mistakes:

Using a classification on a struct:

error[E0277]: `Address` is not a `SensitiveValue`
   = note: classifications like `#[sensitive(Secret)]` are for leaf values (String, etc.)
   = note: if `Address` is a struct that derives `Sensitive`, use `#[sensitive]` instead

Using #[sensitive] on an external type:

error[E0277]: `DateTime<Utc>` does not implement `SensitiveType`
   = note: use `#[derive(Sensitive)]` on the type definition
   = note: or remove the #[sensitive] attribute to pass through unchanged

Policy Behavior

Empty string (""):
- Keep/Mask: returns ""
- Full: returns the placeholder (default: "[REDACTED]")
Keep policies (keep_first, keep_last, KeepConfig::both) operate on Unicode scalar values:
- If visible_prefix + visible_suffix >= length, the value is returned unchanged
Mask policies (mask_first, mask_last, MaskConfig::both) operate on Unicode scalar values:
- If mask_prefix + mask_suffix >= length, the entire value is masked
Length: keep/mask policies preserve the input length (full does not)

Edge Cases

Scalar type aliases: Only bare primitive names (i32, bool) are recognized as scalars. Type aliases like type MyInt = i32 or qualified paths like std::primitive::i32 are treated as non-scalars and require #[sensitive(Classification)] or pass-through.

Boxed trait objects: The derive detects only the simple syntax Box<dyn Trait> and calls redact_boxed. It does not match std::boxed::Box<dyn Trait> or type aliases. The trait object must implement RedactableBoxed.

Foreign string types: For string-like types from other crates, wrap in a newtype:

use redaction::SensitiveValue;

struct WrappedId(external_crate::Id);

impl SensitiveValue for WrappedId {
    fn as_str(&self) -> &str { self.0.as_str() }
    fn from_redacted(s: String) -> Self { WrappedId(external_crate::Id::from(s)) }
}

Map keys: Never redacted. Move sensitive data into values.

Debug vs redact(): The derived Debug formats the type normally, but replaces the values of #[sensitive(...)] fields with the string "[REDACTED]". It does not apply the field's policy. Use .redact() when you need policy-based output.

Testing: Enable the testing feature to get unredacted Debug output in tests:

[dev-dependencies]
redaction = { version = "0.1", features = ["testing"] }

Security Considerations

Length preservation: Keep/Mask policies preserve input length, which can leak information about value size. Use Full redaction for maximum privacy.
Timing: Redaction is not constant-time. Do not use in cryptographic contexts.
Memory: Original values may persist in memory until overwritten. Consider secure memory handling for highly sensitive data.

Documentation

API Documentation

Development

To set up git hooks for pre-commit checks (fmt, clippy, tests):

git config core.hooksPath .githooks

License

Licensed under the MIT license (LICENSE.md or opensource.org/licenses/MIT).

redaction 0.1.9