Skip to main content

dataexcept/
redaction.rs

1//! Credential redaction compatible with the `DataExcept` wire contract.
2//!
3//! The helpers in this module preserve operational context such as URL scheme,
4//! host, port, and optionally path while removing credentials from userinfo,
5//! sensitive query parameters, sensitive fragment parameters, and free-form
6//! text containing URLs.
7
8use std::{collections::BTreeMap, sync::OnceLock};
9
10use form_urlencoded::Serializer;
11use regex::Regex;
12use serde_json::Value;
13use sha2::{Digest, Sha256};
14
15/// Visible marker used in place of credentials.
16pub const PLACEHOLDER: &str = "***";
17
18/// Minimum secret length for safe substring replacement in free-form text.
19pub const MIN_REMOVABLE_SECRET_LENGTH: usize = 8;
20
21const SENSITIVE_PARAM_TOKENS: &[&str] = &[
22    "apikey",
23    "auth",
24    "authorization",
25    "bearer",
26    "credential",
27    "credentials",
28    "hmac",
29    "jwt",
30    "key",
31    "keys",
32    "passphrase",
33    "passwd",
34    "password",
35    "pwd",
36    "sas",
37    "secret",
38    "secrets",
39    "session",
40    "sig",
41    "signature",
42    "token",
43    "tokens",
44];
45
46fn url_regex() -> &'static Regex {
47    static URL_REGEX: OnceLock<Regex> = OnceLock::new();
48    URL_REGEX.get_or_init(|| {
49        Regex::new(r#"[a-zA-Z][a-zA-Z0-9+.\-]*://[^\s'"<>,;)\]}]*[^\s'"<>,;)\]}.:!?]"#)
50            .expect("DataExcept URL regex must compile")
51    })
52}
53
54fn tokens(name: &str) -> Vec<String> {
55    let mut result = Vec::new();
56    let mut current = String::new();
57    let mut previous_lower_or_digit = false;
58
59    for character in name.chars() {
60        if !character.is_ascii_alphanumeric() {
61            if !current.is_empty() {
62                result.push(std::mem::take(&mut current));
63            }
64            previous_lower_or_digit = false;
65            continue;
66        }
67
68        if character.is_ascii_uppercase() && previous_lower_or_digit && !current.is_empty() {
69            result.push(std::mem::take(&mut current));
70        }
71
72        current.push(character.to_ascii_lowercase());
73        previous_lower_or_digit = character.is_ascii_lowercase() || character.is_ascii_digit();
74    }
75
76    if !current.is_empty() {
77        result.push(current);
78    }
79
80    result
81}
82
83fn is_sensitive(name: &str) -> bool {
84    tokens(name)
85        .iter()
86        .any(|token| SENSITIVE_PARAM_TOKENS.contains(&token.as_str()))
87}
88
89/// Returns a short, one-way SHA-256 fingerprint.
90#[must_use]
91pub fn fingerprint(value: &str) -> String {
92    let digest = Sha256::digest(value.as_bytes());
93    format!("{digest:x}")[..8].to_owned()
94}
95
96/// Replaces an optional secret with a placeholder and fingerprint.
97#[must_use]
98pub fn redact_secret(value: Option<&str>) -> Option<String> {
99    value.map(|secret| {
100        if secret.is_empty() {
101            PLACEHOLDER.to_owned()
102        } else {
103            format!("{PLACEHOLDER}({})", fingerprint(secret))
104        }
105    })
106}
107
108/// Removes a known secret from free-form text.
109#[must_use]
110pub fn remove_secret(text: &str, secret: Option<&str>) -> String {
111    let Some(secret) = secret else {
112        return text.to_owned();
113    };
114
115    if secret.is_empty() || text.is_empty() || secret.len() < MIN_REMOVABLE_SECRET_LENGTH {
116        return text.to_owned();
117    }
118
119    text.replace(secret, &format!("{PLACEHOLDER}({})", fingerprint(secret)))
120}
121
122fn redact_params(query: &str) -> (String, bool) {
123    if query.is_empty() {
124        return (query.to_owned(), false);
125    }
126
127    let pairs: Vec<(String, String)> = form_urlencoded::parse(query.as_bytes())
128        .into_owned()
129        .collect();
130
131    if !pairs.iter().any(|(key, _)| is_sensitive(key)) {
132        return (query.to_owned(), false);
133    }
134
135    let mut serializer = Serializer::new(String::new());
136    for (key, value) in pairs {
137        let replacement = if is_sensitive(&key) {
138            PLACEHOLDER
139        } else {
140            &value
141        };
142        serializer.append_pair(&key, replacement);
143    }
144
145    (serializer.finish(), true)
146}
147
148fn split_once_owned(value: &str, delimiter: char) -> (&str, Option<&str>) {
149    value
150        .split_once(delimiter)
151        .map_or((value, None), |(head, tail)| (head, Some(tail)))
152}
153
154fn valid_scheme(scheme: &str) -> bool {
155    let mut chars = scheme.chars();
156    let Some(first) = chars.next() else {
157        return false;
158    };
159
160    first.is_ascii_alphabetic()
161        && chars.all(|character| {
162            character.is_ascii_alphanumeric() || matches!(character, '+' | '.' | '-')
163        })
164}
165
166/// Strips credentials from a URL while preserving useful routing information.
167#[must_use]
168pub fn redact_url(url: &str, keep_path: bool) -> String {
169    if url.is_empty() {
170        return String::new();
171    }
172
173    let Some((scheme, remainder)) = url.split_once("://") else {
174        return url.to_owned();
175    };
176
177    if !valid_scheme(scheme) {
178        return url.to_owned();
179    }
180
181    let (without_fragment, fragment) = split_once_owned(remainder, '#');
182    let (without_query, query) = split_once_owned(without_fragment, '?');
183
184    let (authority, path) = without_query
185        .split_once('/')
186        .map_or((without_query, ""), |(authority, _)| {
187            (authority, &without_query[authority.len()..])
188        });
189
190    if authority.is_empty() {
191        return url.to_owned();
192    }
193
194    let mut redacted = false;
195    let mut output_authority = authority.to_owned();
196
197    if let Some((_, host)) = authority.rsplit_once('@') {
198        output_authority = format!("{PLACEHOLDER}:{PLACEHOLDER}@{host}");
199        redacted = true;
200    }
201
202    let output_query = query.map(|value| {
203        let (redacted_query, changed) = redact_params(value);
204        redacted |= changed;
205        redacted_query
206    });
207
208    let output_fragment = fragment.map(|value| {
209        if value.contains('=') {
210            let (redacted_fragment, changed) = redact_params(value);
211            redacted |= changed;
212            redacted_fragment
213        } else {
214            value.to_owned()
215        }
216    });
217
218    let output_path = if !keep_path && !path.trim_matches('/').is_empty() {
219        redacted = true;
220        format!("/{PLACEHOLDER}")
221    } else {
222        path.to_owned()
223    };
224
225    if !redacted {
226        return url.to_owned();
227    }
228
229    let mut result = format!("{scheme}://{output_authority}{output_path}");
230    if let Some(query) = output_query {
231        result.push('?');
232        result.push_str(&query);
233    }
234    if let Some(fragment) = output_fragment {
235        result.push('#');
236        result.push_str(&fragment);
237    }
238
239    result
240}
241
242/// Redacts a value only when it contains a URL scheme delimiter.
243#[must_use]
244pub fn redact_if_url(value: &str, keep_path: bool) -> String {
245    if value.contains("://") {
246        redact_url(value, keep_path)
247    } else {
248        value.to_owned()
249    }
250}
251
252/// Redacts every URL found in free-form text.
253#[must_use]
254pub fn redact_urls_in_text(text: &str, keep_path: bool) -> String {
255    if text.is_empty() || !text.contains("://") {
256        return text.to_owned();
257    }
258
259    url_regex()
260        .replace_all(text, |captures: &regex::Captures<'_>| {
261            redact_url(&captures[0], keep_path)
262        })
263        .into_owned()
264}
265
266pub(crate) fn redact_json_value(value: Value, keep_path: bool) -> Value {
267    match value {
268        Value::String(text) => Value::String(redact_urls_in_text(&text, keep_path)),
269        Value::Array(values) => Value::Array(
270            values
271                .into_iter()
272                .map(|item| redact_json_value(item, keep_path))
273                .collect(),
274        ),
275        Value::Object(values) => Value::Object(
276            values
277                .into_iter()
278                .map(|(key, item)| (key, redact_json_value(item, keep_path)))
279                .collect(),
280        ),
281        other => other,
282    }
283}
284
285pub(crate) fn redact_attributes(
286    attributes: BTreeMap<String, Value>,
287    keep_path: bool,
288) -> BTreeMap<String, Value> {
289    attributes
290        .into_iter()
291        .map(|(key, value)| (key, redact_json_value(value, keep_path)))
292        .collect()
293}
294
295#[cfg(test)]
296mod tests {
297    use super::{fingerprint, redact_secret, redact_url, redact_urls_in_text, remove_secret};
298
299    #[test]
300    fn fingerprint_matches_sha256_prefix() {
301        assert_eq!(fingerprint("secret"), "2bb80d53");
302    }
303
304    #[test]
305    fn redact_secret_handles_empty_and_present_values() {
306        assert_eq!(redact_secret(None), None);
307        assert_eq!(redact_secret(Some("")), Some("***".to_owned()));
308        assert_eq!(
309            redact_secret(Some("secret")),
310            Some("***(2bb80d53)".to_owned())
311        );
312    }
313
314    #[test]
315    fn known_short_secret_is_not_removed_from_text() {
316        assert_eq!(
317            remove_secret("authentication token", Some("tok")),
318            "authentication token"
319        );
320    }
321
322    #[test]
323    fn userinfo_is_removed() {
324        assert_eq!(
325            redact_url("https://user:hunter2@host/path", true),
326            "https://***:***@host/path"
327        );
328    }
329
330    #[test]
331    fn sensitive_query_is_removed_and_ordinary_query_survives() {
332        assert_eq!(
333            redact_url("https://h/p?token=SECRETVALUE&page=2", true),
334            "https://h/p?token=***&page=2"
335        );
336    }
337
338    #[test]
339    fn sensitive_fragment_is_removed() {
340        assert_eq!(
341            redact_url("https://h/p#access_token=SECRETVALUE", true),
342            "https://h/p#access_token=***"
343        );
344    }
345
346    #[test]
347    fn path_can_be_removed() {
348        assert_eq!(
349            redact_url("https://hooks.example.com/a/b/c?team=data", false),
350            "https://hooks.example.com/***?team=data"
351        );
352    }
353
354    #[test]
355    fn free_text_keeps_trailing_punctuation() {
356        assert_eq!(
357            redact_urls_in_text("see https://h/p?token=SECRETVALUE: retry", true),
358            "see https://h/p?token=***: retry"
359        );
360    }
361
362    #[test]
363    fn url_after_word_character_is_found() {
364        assert_eq!(
365            redact_urls_in_text("feature_https://h/p?token=SECRETVALUE", true),
366            "feature_https://h/p?token=***"
367        );
368    }
369}