inklog 0.3.0-rc.4

// Copyright (c) 2026 Kirky.X
// SPDX-License-Identifier: MIT
//! Log content sanitization for security.
//!
//! This module provides log content sanitization to prevent log injection attacks
//! and ensure safe log output for SIEM systems.

use regex::Regex;
use std::sync::LazyLock;

/// Pre-compiled regex for ANSI SGR (Select Graphic Rendition) escape sequences.
static ANSI_SGR_REGEX: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"\x1b\[[0-9;]*m").expect("hardcoded ANSI SGR regex is valid"));

/// Escape mode for log content sanitization.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum EscapeMode {
    /// Minimal escaping - only escape newlines and control characters
    #[default]
    Minimal,
    /// Strict escaping - escape all non-printable characters
    Strict,
    /// JSON-safe escaping - escape for JSON output
    JsonSafe,
}

/// Configuration for log sanitization.
#[derive(Debug, Clone)]
pub struct SanitizerConfig {
    /// Escape mode
    pub mode: EscapeMode,
    /// Maximum message length (0 = unlimited)
    pub max_length: usize,
    /// Replace patterns with replacement
    pub sensitive_patterns: Vec<(Regex, String)>,
    /// Custom replacements for specific strings
    pub custom_replacements: Vec<(String, String)>,
}

impl Default for SanitizerConfig {
    fn default() -> Self {
        Self {
            mode: EscapeMode::Minimal,
            max_length: 0,
            sensitive_patterns: Vec::new(),
            custom_replacements: vec![
                ("\r\n".to_string(), "\\n".to_string()),
                ("\n".to_string(), "\\n".to_string()),
                ("\r".to_string(), "\\r".to_string()),
            ],
        }
    }
}

/// Log sanitizer for preventing log injection.
#[derive(Debug, Clone)]
pub struct LogSanitizer {
    config: SanitizerConfig,
    sensitive_regexes: Vec<(Regex, String)>,
}

/// Default sensitive patterns compiled once and shared across all LogSanitizer instances.
/// Using LazyLock avoids recompiling these stable regex patterns on every constructor call.
static DEFAULT_SENSITIVE_PATTERNS: LazyLock<Vec<(Regex, String)>> = LazyLock::new(|| {
    vec![
        (
            Regex::new(r"\b\d{13,16}\b").expect("hardcoded card number regex is valid"),
            "[CARD_NUM]".to_string(),
        ),
        (
            Regex::new(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b")
                .expect("hardcoded email regex is valid"),
            "[EMAIL]".to_string(),
        ),
        (
            Regex::new(r"\b\d{3}-\d{2}-\d{4}\b").expect("hardcoded SSN regex is valid"),
            "[SSN]".to_string(),
        ),
        (
            Regex::new(r"(?i)password\s*[=:]\s*\S+").expect("hardcoded password regex is valid"),
            "password=[REDACTED]".to_string(),
        ),
        (
            Regex::new(r"(?i)token\s*[=:]\s*\S+").expect("hardcoded token regex is valid"),
            "token=[REDACTED]".to_string(),
        ),
        (
            Regex::new(r"(?i)api[_-]?key\s*[=:]\s*\S+").expect("hardcoded api_key regex is valid"),
            "api_key=[REDACTED]".to_string(),
        ),
        (
            Regex::new(r"Bearer\s+[A-Za-z0-9\-\.]+")
                .expect("hardcoded Bearer token regex is valid"),
            "Bearer [TOKEN]".to_string(),
        ),
        (
            Regex::new(r"Basic\s+[A-Za-z0-9+/=]+").expect("hardcoded Basic auth regex is valid"),
            "Basic [AUTH]".to_string(),
        ),
    ]
});

impl LogSanitizer {
    /// Create a new LogSanitizer with default configuration.
    pub fn new() -> Self {
        Self {
            config: SanitizerConfig::default(),
            sensitive_regexes: Self::default_sensitive_patterns(),
        }
    }

    /// Create with custom configuration.
    /// User-provided `sensitive_patterns` are merged with default patterns.
    pub fn with_config(mut config: SanitizerConfig) -> Self {
        let mut sensitive_regexes = Self::default_sensitive_patterns();
        sensitive_regexes.append(&mut config.sensitive_patterns);
        Self {
            config,
            sensitive_regexes,
        }
    }

    /// Clone from the shared LazyLock cache to avoid recompiling regexes.
    /// Each caller gets its own owned copy so mutations (add_pattern) don't affect others.
    fn default_sensitive_patterns() -> Vec<(Regex, String)> {
        DEFAULT_SENSITIVE_PATTERNS.clone()
    }

    /// Sanitize a log message.
    ///
    /// # Processing Order Contract
    ///
    /// 1. ANSI escape sequences are stripped first.
    /// 2. Custom string replacements run next.
    /// 3. Sensitive-pattern redaction runs **last** (before escape-mode
    ///    encoding). This ordering is deliberate: a custom replacement could
    ///    otherwise re-introduce sensitive content into the output after
    ///    redaction had already run, so redaction is positioned as the final
    ///    content transform.
    ///
    /// # Marker Idempotency Contract
    ///
    /// Step 3 is skipped entirely when the message already contains a
    /// redaction/masking marker (`***REDACTED`、`***MASKED`、`[REDACTED]`):
    /// the message is treated as already redacted by an upstream entry point
    /// （`InklogError::safe_message` 或 `DataMasker::mask`），避免产生
    /// REDACTED 套 REDACTED 的嵌套标记。注入防护不受短路影响——ANSI 剥离
    /// 与 escape 转义仍然执行。
    pub fn sanitize(&self, message: &str) -> String {
        // Strip ANSI escape sequences before any other processing
        let mut result = self.strip_ansi(message).into_owned();

        for (from, to) in &self.config.custom_replacements {
            result = result.replace(from, to);
        }

        // 标记幂等短路（契约见 doc）：已含脱敏/掩码标记的输入跳过敏感正则
        // 再次脱敏；注入防护（ANSI 剥离、自定义替换、escape 转义）照常执行。
        if !contains_redaction_marker(&result) {
            for (pattern, replacement) in &self.sensitive_regexes {
                result = pattern
                    .replace_all(&result, replacement.as_str())
                    .to_string();
            }
        }

        match self.config.mode {
            EscapeMode::Minimal => {
                result = self.escape_minimal(&result);
            }
            EscapeMode::Strict => {
                result = self.escape_strict(&result);
            }
            EscapeMode::JsonSafe => {
                result = self.escape_json(&result);
            }
        }

        if self.config.max_length > 0 && result.len() > self.config.max_length {
            // Find a safe UTF-8 char boundary to avoid splitting multi-byte characters
            let mut end = self.config.max_length;
            while end > 0 && !result.is_char_boundary(end) {
                end -= 1;
            }
            result.truncate(end);
            result.push_str("...[truncated]");
        }

        result
    }

    fn escape_minimal(&self, s: &str) -> String {
        let mut result = String::with_capacity(s.len());
        for c in s.chars() {
            match c {
                '\n' => result.push_str("\\n"),
                '\r' => result.push_str("\\r"),
                '\t' => result.push_str("\\t"),
                c if c.is_control() && c != '\n' && c != '\r' && c != '\t' => {
                    result.push_str(&format!("\\x{:02x}", c as u8));
                }
                _ => result.push(c),
            }
        }
        result
    }

    /// Strict escape mode: converts control characters and quotes to `\uXXXX` form.
    ///
    /// This method is idempotent: calling it twice on the same input produces
    /// the same output, because already-escaped `\uXXXX` sequences are detected
    /// and not re-escaped.
    fn escape_strict(&self, s: &str) -> String {
        let mut result = String::with_capacity(s.len());
        let mut chars = s.chars().peekable();
        while let Some(c) = chars.next() {
            // Check if this backslash starts an existing \uXXXX escape sequence
            if c == '\\' {
                if chars.peek() == Some(&'u') {
                    // Pass through existing \uXXXX sequences unchanged
                    result.push(c);
                } else {
                    // Escape standalone backslashes
                    result.push_str(&format!("\\u{:04x}", c as u32));
                }
            } else if c.is_control() || c == '"' {
                result.push_str(&format!("\\u{:04x}", c as u32));
            } else {
                result.push(c);
            }
        }
        result
    }

    fn escape_json(&self, s: &str) -> String {
        let mut result = String::with_capacity(s.len());
        for c in s.chars() {
            match c {
                '"' => result.push_str("\\\""),
                '\\' => result.push_str("\\\\"),
                '\n' => result.push_str("\\n"),
                '\r' => result.push_str("\\r"),
                '\t' => result.push_str("\\t"),
                c if c.is_control() => {
                    result.push_str(&format!("\\u{:04x}", c as u32));
                }
                _ => result.push(c),
            }
        }
        result
    }

    /// Add a custom sensitive pattern.
    pub fn add_pattern(&mut self, pattern: Regex, replacement: String) {
        self.sensitive_regexes.push((pattern, replacement));
    }

    /// Add a custom string replacement.
    pub fn add_replacement(&mut self, from: String, to: String) {
        self.config.custom_replacements.push((from, to));
    }

    /// Strip ANSI SGR escape sequences from the input string.
    ///
    /// Fast path: if the input contains no `\x1b` (ESC) character,
    /// returns the original string without any allocation.
    pub fn strip_ansi<'a>(&self, input: &'a str) -> std::borrow::Cow<'a, str> {
        if !input.contains('\x1b') {
            return std::borrow::Cow::Borrowed(input);
        }
        std::borrow::Cow::Owned(ANSI_SGR_REGEX.replace_all(input, "").into_owned())
    }
}

impl Default for LogSanitizer {
    fn default() -> Self {
        Self::new()
    }
}

/// 已脱敏/已掩码标记（脱敏幂等契约）。
///
/// 三处脱敏入口共享同一分工与契约：
/// - `InklogError::safe_message`（src/error.rs）：错误消息出口脱敏
/// - [`LogSanitizer`]（本模块）：日志注入防护（CWE-117）与转义
/// - `DataMasker::mask`（src/support/processing/masking.rs）：PII 掩码
///
/// 双开关叠加时同一条消息会先后经过多个入口。输入包含任一标记
/// （`***REDACTED***`、`***MASKED***`、`[REDACTED]` 等，含各自变体前缀）
/// 即视为已被上游处理过，入口必须短路跳过再次脱敏，避免产生
/// REDACTED 套 REDACTED 的嵌套标记。
pub(crate) const REDACTION_MARKERS: &[&str] = &["***REDACTED", "***MASKED", "[REDACTED]"];

/// 判断消息是否已包含脱敏/掩码标记（幂等短路判定）。
pub(crate) fn contains_redaction_marker(message: &str) -> bool {
    REDACTION_MARKERS
        .iter()
        .any(|marker| message.contains(marker))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_newline_escaping() {
        let sanitizer = LogSanitizer::new();

        let result = sanitizer.sanitize("Hello\nWorld");
        assert!(result.contains("\\n"));
        assert!(!result.contains('\n'));
    }

    #[test]
    fn test_sensitive_data_redaction() {
        let sanitizer = LogSanitizer::new();

        let result = sanitizer.sanitize("User password=secret123");
        assert!(result.contains("[REDACTED]"));
        assert!(!result.contains("secret123"));

        let result = sanitizer.sanitize("api_key=sk-1234567890");
        assert!(result.contains("[REDACTED]"));
        assert!(!result.contains("sk-1234567890"));
    }

    #[test]
    fn test_email_redaction() {
        let sanitizer = LogSanitizer::new();

        let result = sanitizer.sanitize("Contact user@example.com");
        assert!(result.contains("[EMAIL]"));
        assert!(!result.contains("user@example.com"));
    }

    #[test]
    fn test_escape_modes() {
        let config = SanitizerConfig {
            mode: EscapeMode::JsonSafe,
            ..Default::default()
        };
        let sanitizer = LogSanitizer::with_config(config);

        let result = sanitizer.sanitize("Hello\"World");
        assert!(result.contains("\\\""));
    }

    #[test]
    fn test_max_length() {
        let config = SanitizerConfig {
            max_length: 10,
            ..Default::default()
        };
        let sanitizer = LogSanitizer::with_config(config);

        let result = sanitizer.sanitize("This is a very long message");
        assert!(result.len() <= 10 + "...[truncated]".len());
        assert!(result.contains("...[truncated]"));
    }

    #[test]
    fn test_control_character_escaping() {
        let sanitizer = LogSanitizer::new();

        let result = sanitizer.sanitize("Hello\x00World");
        assert!(result.contains("\\x00"));
    }

    #[test]
    fn test_default_log_sanitizer() {
        let sanitizer = LogSanitizer::default();
        let result = sanitizer.sanitize("test\nmessage");
        assert!(result.contains("\\n"));
        assert!(!result.contains('\n'));
    }

    #[test]
    fn test_strict_escape_mode() {
        let config = SanitizerConfig {
            mode: EscapeMode::Strict,
            custom_replacements: Vec::new(),
            ..Default::default()
        };
        let sanitizer = LogSanitizer::with_config(config);

        let result = sanitizer.sanitize("Hello\nWorld");
        assert!(result.contains("\\u000a"));
        assert!(!result.contains('\n'));
    }

    #[test]
    fn test_escape_strict_with_backslash_and_quote() {
        let config = SanitizerConfig {
            mode: EscapeMode::Strict,
            custom_replacements: Vec::new(),
            ..Default::default()
        };
        let sanitizer = LogSanitizer::with_config(config);

        let result = sanitizer.sanitize("path\\to\"file");
        assert!(result.contains("\\u005c"));
        assert!(result.contains("\\u0022"));
        // The raw backslash and quote should be replaced by escape sequences
        // Note: escape sequences themselves contain backslashes, so we verify
        // the escape sequences are present rather than checking for absence of '\'
        assert!(!result.contains("\""));
    }

    #[test]
    fn test_escape_strict_preserves_printable() {
        let config = SanitizerConfig {
            mode: EscapeMode::Strict,
            custom_replacements: Vec::new(),
            ..Default::default()
        };
        let sanitizer = LogSanitizer::with_config(config);

        let result = sanitizer.sanitize("Hello World 123");
        assert_eq!(result, "Hello World 123");
    }

    #[test]
    fn test_escape_minimal_with_newline_tab_carriage_return() {
        let config = SanitizerConfig {
            mode: EscapeMode::Minimal,
            custom_replacements: Vec::new(),
            ..Default::default()
        };
        let sanitizer = LogSanitizer::with_config(config);

        let result = sanitizer.sanitize("line1\nline2\r\ttabbed");
        assert_eq!(result, "line1\\nline2\\r\\ttabbed");
        assert!(!result.contains('\n'));
        assert!(!result.contains('\r'));
        assert!(!result.contains('\t'));
    }

    #[test]
    fn test_escape_json_all_special_chars() {
        let config = SanitizerConfig {
            mode: EscapeMode::JsonSafe,
            custom_replacements: Vec::new(),
            ..Default::default()
        };
        let sanitizer = LogSanitizer::with_config(config);

        let input = "quote\"backslash\\newline\ncarriage\rtab\t";
        let result = sanitizer.sanitize(input);
        assert!(result.contains("\\\""));
        assert!(result.contains("\\\\"));
        assert!(result.contains("\\n"));
        assert!(result.contains("\\r"));
        assert!(result.contains("\\t"));
        assert!(!result.contains('\n'));
        assert!(!result.contains('\r'));
        assert!(!result.contains('\t'));
    }

    #[test]
    fn test_escape_json_control_character() {
        let config = SanitizerConfig {
            mode: EscapeMode::JsonSafe,
            custom_replacements: Vec::new(),
            ..Default::default()
        };
        let sanitizer = LogSanitizer::with_config(config);

        let result = sanitizer.sanitize("null\x00byte");
        assert!(result.contains("\\u0000"));
    }

    #[test]
    fn test_add_pattern() {
        let mut sanitizer = LogSanitizer::new();
        let pattern = Regex::new(r"SECRET-\d+").expect("valid regex");
        sanitizer.add_pattern(pattern, "[SECRET]".to_string());

        let result = sanitizer.sanitize("found SECRET-12345 here");
        assert!(result.contains("[SECRET]"));
        assert!(!result.contains("SECRET-12345"));
    }

    #[test]
    fn test_add_replacement() {
        let mut sanitizer = LogSanitizer::new();
        sanitizer.add_replacement("foo".to_string(), "bar".to_string());

        let result = sanitizer.sanitize("hello foo world");
        assert!(result.contains("bar"));
        assert!(!result.contains("foo"));
    }

    #[test]
    fn test_add_pattern_and_replacement_combined() {
        let mut sanitizer = LogSanitizer::new();
        let pattern = Regex::new(r"\bPHONE-\d+\b").expect("valid regex");
        sanitizer.add_pattern(pattern, "[PHONE]".to_string());
        sanitizer.add_replacement("internal".to_string(), "external".to_string());

        let result = sanitizer.sanitize("call PHONE-555 internal line");
        assert!(result.contains("[PHONE]"));
        assert!(result.contains("external"));
        assert!(!result.contains("PHONE-555"));
        assert!(!result.contains("internal"));
    }

    #[test]
    fn test_custom_replacement_reintroduced_content_is_redacted() {
        // 顺序契约：自定义替换先执行、敏感正则脱敏最后执行（安全后置）。
        // 若正则先执行，自定义替换重新拼出的敏感内容将绕过脱敏直接泄漏。
        let mut sanitizer = LogSanitizer::new();
        sanitizer.add_replacement("MYSECRET".to_string(), "password".to_string());

        // 原文不命中任何敏感正则；替换后 "password=..." 必须被再掩码
        let result = sanitizer.sanitize("MYSECRET=opensesame123");
        assert!(
            result.contains("[REDACTED]"),
            "reassembled sensitive content must be redacted: {}",
            result
        );
        assert!(!result.contains("opensesame123"));
    }

    #[test]
    fn test_email_redaction_does_not_swallow_pipe_suffix() {
        // 修复前 TLD 字符类 [A-Z|a-z] 中的 "|" 是字面量，会把邮箱后的
        // "|" 及后续字母吞进 [EMAIL]；修复后管道符保持原样
        let sanitizer = LogSanitizer::new();
        let result = sanitizer.sanitize("mail user@example.com|tail");
        assert_eq!(result, "mail [EMAIL]|tail");
    }

    #[test]
    fn test_sanitize_truncate_respects_utf8_boundaries() {
        let mut config = super::SanitizerConfig::default();
        config.max_length = 7;
        let sanitizer = super::LogSanitizer::with_config(config);
        let result = sanitizer.sanitize("你好世界");
        assert!(result.starts_with("你好"));
        assert!(result.contains("...[truncated]"));
    }

    #[test]
    fn test_strip_ansi_sgr_sequence() {
        let sanitizer = LogSanitizer::new();
        assert_eq!(sanitizer.strip_ansi("\x1b[31mERROR\x1b[0m"), "ERROR");
    }

    #[test]
    fn test_strip_ansi_multiple_sequences() {
        let sanitizer = LogSanitizer::new();
        assert_eq!(sanitizer.strip_ansi("\x1b[1;32mOK\x1b[0m"), "OK");
    }

    #[test]
    fn test_strip_ansi_fast_path_no_esc() {
        let sanitizer = LogSanitizer::new();
        let input = "no ansi here";
        let result = sanitizer.strip_ansi(input);
        assert_eq!(result, "no ansi here");
        assert!(matches!(result, std::borrow::Cow::Borrowed(_)));
    }

    #[test]
    fn test_strip_ansi_nested_sequences() {
        let sanitizer = LogSanitizer::new();
        assert_eq!(
            sanitizer.strip_ansi("\x1b[1m\x1b[31mBOLD RED\x1b[0m\x1b[0m"),
            "BOLD RED"
        );
    }

    #[test]
    fn test_strip_ansi_empty_input() {
        let sanitizer = LogSanitizer::new();
        assert_eq!(sanitizer.strip_ansi(""), "");
    }

    #[test]
    fn test_strip_ansi_only_esc_char() {
        let sanitizer = LogSanitizer::new();
        let result = sanitizer.strip_ansi("\x1b");
        assert_eq!(result, "\x1b");
    }

    #[test]
    fn test_sanitize_strips_ansi_before_processing() {
        let sanitizer = LogSanitizer::new();
        let result = sanitizer.sanitize("\x1b[31mERROR\x1b[0m");
        assert_eq!(result, "ERROR");
        assert!(!result.contains('\x1b'));
    }

    #[test]
    fn test_sanitize_marker_idempotency() {
        let sanitizer = LogSanitizer::new();

        // 已含 ***MASKED*** 标记的输入：跳过敏感正则再次脱敏，标记原样保留
        // （修复前 token=***MASKED*** 会被 token= 规则改写为 token=[REDACTED]）
        let marked = "token=***MASKED***";
        assert_eq!(
            sanitizer.sanitize(marked),
            marked,
            "masking marker must pass through unchanged"
        );

        // 已脱敏消息再次进入本入口：幂等，不产生嵌套标记
        let once = sanitizer.sanitize("user password=supersecret123 login");
        assert!(once.contains("[REDACTED]"));
        assert_eq!(
            sanitizer.sanitize(&once),
            once,
            "re-sanitizing already redacted text must be a no-op"
        );

        // 短路只跳过脱敏：注入防护（换行转义）对标记输入仍然执行
        let mixed = sanitizer.sanitize("password=[REDACTED]\nnext line");
        assert!(
            mixed.contains("[REDACTED]"),
            "marker must be preserved, got: {mixed}"
        );
        assert!(
            !mixed.contains('\n'),
            "injection protection must still run for marked input"
        );
    }
}