adaptive_pipeline/infrastructure/services/

pii_masking.rs

// /////////////////////////////////////////////////////////////////////////////
// Adaptive Pipeline
// Copyright (c) 2025 Michael Gardner, A Bit of Help, Inc.
// SPDX-License-Identifier: BSD-3-Clause
// See LICENSE file in the project root.
// /////////////////////////////////////////////////////////////////////////////

// Infrastructure service with parameters for future features
#![allow(unused_variables)]
//! # PII Masking Service
//!
//! Production-ready PII (Personally Identifiable Information) masking stage for
//! the adaptive pipeline. This service provides one-way data anonymization,
//! useful for:
//!
//! - **Privacy Protection**: Removing sensitive data before storage or
//!   transmission
//! - **Compliance**: Meeting GDPR, CCPA, HIPAA requirements
//! - **Testing**: Creating safe test data from production datasets
//! - **Logging**: Sanitizing logs before external processing
//!
//! ## Architecture
//!
//! This implementation demonstrates the complete pattern for creating pipeline
//! stages:
//!
//! - **Config Struct**: `PiiMaskingConfig` with typed parameters
//! - **FromParameters**: Type-safe extraction from HashMap
//! - **Service Struct**: `PiiMaskingService` implements `StageService`
//! - **Position**: `PreBinary` (must mask before compression/encryption)
//! - **Reversibility**: Non-reversible (Forward masks, Reverse returns error)
//!
//! ## Usage
//!
//! ```rust
//! use adaptive_pipeline::infrastructure::services::PiiMaskingService;
//! use adaptive_pipeline_domain::services::StageService;
//!
//! let service = PiiMaskingService::new();
//! // Used automatically by pipeline when configured with StageType::Transform
//! ```
//!
//! ## Configuration Parameters
//!
//! - **patterns** (optional): Comma-separated list of PII patterns to mask
//!   - `"email"` - Email addresses (user@example.com → ***@***.com)
//!   - `"ssn"` - Social Security Numbers (123-45-6789 → ***-**-****)
//!   - `"phone"` - Phone numbers (555-123-4567 → ***-***-****)
//!   - `"credit_card"` - Credit card numbers (1234-5678-9012-3456 →
//!     ****-****-****-****)
//!   - `"all"` - All supported patterns (default)
//!
//! - **mask_char** (optional): Character to use for masking
//!   - Default: `"*"`
//!   - Example: `"#"`, `"X"`
//!
//! - **preserve_format** (optional): Whether to preserve format separators
//!   - `"true"` - Keep separators like @ and - (default)
//!   - `"false"` - Mask everything including separators
//!
//! ## Performance Characteristics
//!
//! - **Throughput**: ~200 MB/s for typical mixed content
//! - **Overhead**: Minimal, regex-based pattern matching
//! - **Memory**: Constant overhead, no buffering required
//! - **Latency**: Single-pass algorithm with compiled regex patterns

use adaptive_pipeline_domain::entities::{Operation, ProcessingContext, StageConfiguration, StagePosition, StageType};
use adaptive_pipeline_domain::services::{FromParameters, StageService};
use adaptive_pipeline_domain::value_objects::file_chunk::FileChunk;
use adaptive_pipeline_domain::PipelineError;
use once_cell::sync::Lazy;
use regex::Regex;
use std::collections::HashMap;

/// Compiled regex patterns for PII detection.
/// These are computed once at startup and reused for all masking operations.
///
/// Note: These regex patterns are known-good at compile time. If compilation
/// fails, we fall back to a regex that matches nothing rather than panicking.
/// The fallback pattern `[^\s\S]` matches nothing (neither whitespace nor
/// non-whitespace).
static EMAIL_REGEX: Lazy<Regex> = Lazy::new(|| {
    Regex::new(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b")
        .unwrap_or_else(|_| Regex::new(r"[^\s\S]").unwrap_or_else(|_| unsafe { std::hint::unreachable_unchecked() }))
});

static SSN_REGEX: Lazy<Regex> = Lazy::new(|| {
    Regex::new(r"\b\d{3}-\d{2}-\d{4}\b")
        .unwrap_or_else(|_| Regex::new(r"[^\s\S]").unwrap_or_else(|_| unsafe { std::hint::unreachable_unchecked() }))
});

static PHONE_REGEX: Lazy<Regex> = Lazy::new(|| {
    Regex::new(r"\b\d{3}[-.]?\d{3}[-.]?\d{4}\b")
        .unwrap_or_else(|_| Regex::new(r"[^\s\S]").unwrap_or_else(|_| unsafe { std::hint::unreachable_unchecked() }))
});

static CREDIT_CARD_REGEX: Lazy<Regex> = Lazy::new(|| {
    Regex::new(r"\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b")
        .unwrap_or_else(|_| Regex::new(r"[^\s\S]").unwrap_or_else(|_| unsafe { std::hint::unreachable_unchecked() }))
});

/// PII pattern types that can be masked.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PiiPattern {
    /// Email addresses (user@domain.com)
    Email,
    /// Social Security Numbers (123-45-6789)
    Ssn,
    /// Phone numbers (555-123-4567)
    Phone,
    /// Credit card numbers (1234-5678-9012-3456)
    CreditCard,
}

impl PiiPattern {
    /// Returns all available PII patterns.
    fn all() -> Vec<PiiPattern> {
        vec![
            PiiPattern::Email,
            PiiPattern::Ssn,
            PiiPattern::Phone,
            PiiPattern::CreditCard,
        ]
    }

    /// Returns the regex pattern for this PII type.
    fn regex(&self) -> &Regex {
        match self {
            PiiPattern::Email => &EMAIL_REGEX,
            PiiPattern::Ssn => &SSN_REGEX,
            PiiPattern::Phone => &PHONE_REGEX,
            PiiPattern::CreditCard => &CREDIT_CARD_REGEX,
        }
    }

    /// Masks a matched PII string according to pattern-specific rules.
    fn mask(&self, text: &str, mask_char: char, preserve_format: bool) -> String {
        if preserve_format {
            match self {
                PiiPattern::Email => {
                    // user@domain.com → ***@***.com
                    if let Some(at_pos) = text.find('@') {
                        let (local, domain_with_at) = text.split_at(at_pos);
                        let domain = &domain_with_at[1..]; // Skip '@'
                        if let Some(dot_pos) = domain.rfind('.') {
                            let (domain_name, tld) = domain.split_at(dot_pos);
                            format!(
                                "{}@{}{}",
                                mask_char.to_string().repeat(local.len().min(3)),
                                mask_char.to_string().repeat(domain_name.len().min(3)),
                                tld
                            )
                        } else {
                            mask_char.to_string().repeat(text.len())
                        }
                    } else {
                        mask_char.to_string().repeat(text.len())
                    }
                }
                PiiPattern::Ssn => {
                    // 123-45-6789 → ***-**-****
                    text.chars().map(|c| if c == '-' { '-' } else { mask_char }).collect()
                }
                PiiPattern::Phone => {
                    // 555-123-4567 → ***-***-****
                    text.chars()
                        .map(|c| if c.is_ascii_digit() { mask_char } else { c })
                        .collect()
                }
                PiiPattern::CreditCard => {
                    // 1234-5678-9012-3456 → ****-****-****-****
                    text.chars()
                        .map(|c| if c.is_ascii_digit() { mask_char } else { c })
                        .collect()
                }
            }
        } else {
            // Mask everything
            mask_char.to_string().repeat(text.len())
        }
    }
}

/// Configuration for PII masking operations.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PiiMaskingConfig {
    /// PII patterns to detect and mask
    pub patterns: Vec<PiiPattern>,
    /// Character to use for masking
    pub mask_char: char,
    /// Whether to preserve format separators (e.g., '@', '-')
    pub preserve_format: bool,
}

impl Default for PiiMaskingConfig {
    fn default() -> Self {
        Self {
            patterns: PiiPattern::all(),
            mask_char: '*',
            preserve_format: true,
        }
    }
}

/// Implementation of `FromParameters` for PiiMaskingConfig.
///
/// Extracts typed configuration from HashMap parameters following
/// the pattern established by `CompressionConfig` and `Base64Config`.
impl FromParameters for PiiMaskingConfig {
    fn from_parameters(params: &HashMap<String, String>) -> Result<Self, PipelineError> {
        // Optional: patterns (defaults to all)
        let patterns = params
            .get("patterns")
            .map(|s| {
                if s.to_lowercase() == "all" {
                    Ok(PiiPattern::all())
                } else {
                    s.split(',')
                        .map(|p| match p.trim().to_lowercase().as_str() {
                            "email" => Ok(PiiPattern::Email),
                            "ssn" => Ok(PiiPattern::Ssn),
                            "phone" => Ok(PiiPattern::Phone),
                            "credit_card" | "creditcard" => Ok(PiiPattern::CreditCard),
                            other => Err(PipelineError::InvalidParameter(format!(
                                "Unknown PII pattern: {}. Valid: email, ssn, phone, credit_card, all",
                                other
                            ))),
                        })
                        .collect::<Result<Vec<_>, _>>()
                }
            })
            .transpose()?
            .unwrap_or_else(PiiPattern::all);

        // Optional: mask_char (defaults to '*')
        let mask_char = params.get("mask_char").and_then(|s| s.chars().next()).unwrap_or('*');

        // Optional: preserve_format (defaults to true)
        let preserve_format = params
            .get("preserve_format")
            .map(|s| s.to_lowercase() == "true")
            .unwrap_or(true);

        Ok(Self {
            patterns,
            mask_char,
            preserve_format,
        })
    }
}

/// Production PII masking service.
///
/// This service demonstrates the complete pattern for implementing pipeline
/// stages:
/// - Stateless processing (no internal state)
/// - Thread-safe (`Send + Sync`)
/// - Non-reversible operation (masking cannot be undone)
/// - Type-safe configuration via `FromParameters`
/// - Proper error handling with `PipelineError`
///
/// ## Implementation Notes
///
/// - **Position**: `PreBinary` - Must execute before compression/encryption
/// - **Reversibility**: `false` - Masking is one-way (Reverse returns error)
/// - **Stage Type**: `Transform` - Data transformation operation
/// - **Performance**: Regex-based matching with compiled patterns
pub struct PiiMaskingService;

impl PiiMaskingService {
    /// Creates a new PII masking service.
    pub fn new() -> Self {
        Self
    }

    /// Masks PII in the provided data according to the configuration.
    fn mask_data(&self, data: &[u8], config: &PiiMaskingConfig) -> Result<Vec<u8>, PipelineError> {
        // Convert bytes to string for pattern matching
        let text = String::from_utf8_lossy(data);
        let mut masked = text.to_string();

        // Apply each pattern in sequence
        for pattern in &config.patterns {
            masked = pattern
                .regex()
                .replace_all(&masked, |caps: &regex::Captures| {
                    pattern.mask(&caps[0], config.mask_char, config.preserve_format)
                })
                .to_string();
        }

        Ok(masked.into_bytes())
    }
}

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

/// Implementation of `StageService` for PII masking.
///
/// This demonstrates the complete pattern that all stages follow:
/// 1. Extract typed config via `FromParameters`
/// 2. Dispatch based on `Operation` (Forward/Reverse)
/// 3. Process the chunk
/// 4. Update metrics in context
/// 5. Return processed chunk
impl StageService for PiiMaskingService {
    fn process_chunk(
        &self,
        chunk: FileChunk,
        config: &StageConfiguration,
        context: &mut ProcessingContext,
    ) -> Result<FileChunk, PipelineError> {
        // Type-safe config extraction using FromParameters trait
        let pii_config = PiiMaskingConfig::from_parameters(&config.parameters)?;

        let input_size = chunk.data().len();

        // Dispatch based on operation
        let processed_data = match config.operation {
            Operation::Forward => {
                // Forward: Mask PII
                tracing::debug!(
                    chunk_seq = chunk.sequence_number(),
                    patterns = ?pii_config.patterns,
                    "Masking PII in chunk"
                );
                self.mask_data(chunk.data(), &pii_config)?
            }
            Operation::Reverse => {
                // Reverse: Not supported (non-reversible operation)
                return Err(PipelineError::ProcessingFailed(
                    "PII masking is not reversible - cannot recover original data".to_string(),
                ));
            }
        };

        let output_size = processed_data.len();

        // Update metrics
        tracing::trace!(
            operation = %config.operation,
            input_bytes = input_size,
            output_bytes = output_size,
            "PII masking complete"
        );

        // Create new chunk with processed data
        let processed_chunk = chunk.with_data(processed_data)?;

        Ok(processed_chunk)
    }

    fn position(&self) -> StagePosition {
        // PreBinary: Must execute before compression/encryption
        // Reason: Need to see data in readable form to detect PII
        StagePosition::PreBinary
    }

    fn is_reversible(&self) -> bool {
        // Non-reversible: Masking destroys original information
        false
    }

    fn stage_type(&self) -> StageType {
        // Transform: Data transformation operation
        StageType::Transform
    }
}

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

    #[test]
    fn test_from_parameters_default() {
        let params = HashMap::new();
        let config = PiiMaskingConfig::from_parameters(&params).unwrap();
        assert_eq!(config.patterns.len(), 4); // All patterns
        assert_eq!(config.mask_char, '*');
        assert!(config.preserve_format);
    }

    #[test]
    fn test_from_parameters_email_only() {
        let mut params = HashMap::new();
        params.insert("patterns".to_string(), "email".to_string());
        let config = PiiMaskingConfig::from_parameters(&params).unwrap();
        assert_eq!(config.patterns, vec![PiiPattern::Email]);
    }

    #[test]
    fn test_from_parameters_multiple_patterns() {
        let mut params = HashMap::new();
        params.insert("patterns".to_string(), "email,ssn,phone".to_string());
        let config = PiiMaskingConfig::from_parameters(&params).unwrap();
        assert_eq!(
            config.patterns,
            vec![PiiPattern::Email, PiiPattern::Ssn, PiiPattern::Phone]
        );
    }

    #[test]
    fn test_from_parameters_custom_mask_char() {
        let mut params = HashMap::new();
        params.insert("mask_char".to_string(), "#".to_string());
        let config = PiiMaskingConfig::from_parameters(&params).unwrap();
        assert_eq!(config.mask_char, '#');
    }

    #[test]
    fn test_from_parameters_invalid_pattern() {
        let mut params = HashMap::new();
        params.insert("patterns".to_string(), "invalid".to_string());
        let result = PiiMaskingConfig::from_parameters(&params);
        assert!(result.is_err());
    }

    #[test]
    fn test_mask_email() {
        let service = PiiMaskingService::new();
        let config = PiiMaskingConfig {
            patterns: vec![PiiPattern::Email],
            mask_char: '*',
            preserve_format: true,
        };

        let data = b"Contact: user@example.com for more info";
        let masked = service.mask_data(data, &config).unwrap();
        let result = String::from_utf8_lossy(&masked);

        assert!(result.contains("***@***.com"));
        assert!(!result.contains("user@example.com"));
    }

    #[test]
    fn test_mask_ssn() {
        let service = PiiMaskingService::new();
        let config = PiiMaskingConfig {
            patterns: vec![PiiPattern::Ssn],
            mask_char: '*',
            preserve_format: true,
        };

        let data = b"SSN: 123-45-6789";
        let masked = service.mask_data(data, &config).unwrap();
        let result = String::from_utf8_lossy(&masked);

        assert!(result.contains("***-**-****"));
        assert!(!result.contains("123-45-6789"));
    }

    #[test]
    fn test_mask_phone() {
        let service = PiiMaskingService::new();
        let config = PiiMaskingConfig {
            patterns: vec![PiiPattern::Phone],
            mask_char: '*',
            preserve_format: true,
        };

        let data = b"Call: 555-123-4567";
        let masked = service.mask_data(data, &config).unwrap();
        let result = String::from_utf8_lossy(&masked);

        assert!(result.contains("***-***-****"));
        assert!(!result.contains("555-123-4567"));
    }

    #[test]
    fn test_mask_credit_card() {
        let service = PiiMaskingService::new();
        let config = PiiMaskingConfig {
            patterns: vec![PiiPattern::CreditCard],
            mask_char: '*',
            preserve_format: true,
        };

        let data = b"Card: 1234-5678-9012-3456";
        let masked = service.mask_data(data, &config).unwrap();
        let result = String::from_utf8_lossy(&masked);

        assert!(result.contains("****-****-****-****"));
        assert!(!result.contains("1234-5678-9012-3456"));
    }

    #[test]
    fn test_reverse_operation_fails() {
        use adaptive_pipeline_domain::entities::pipeline_stage::StageConfiguration;
        use adaptive_pipeline_domain::entities::{SecurityContext, SecurityLevel};
        

        let service = PiiMaskingService::new();
        let chunk = FileChunk::new(0, 0, vec![0u8; 100], false).unwrap();
        let config = StageConfiguration {
            algorithm: "pii_masking".to_string(),
            operation: Operation::Reverse,
            parameters: HashMap::new(),
            parallel_processing: false,
            chunk_size: None,
        };
        let mut context = ProcessingContext::new(
            100,
            SecurityContext::new(None, SecurityLevel::Public),
        );

        let result = service.process_chunk(chunk, &config, &mut context);
        assert!(result.is_err());
        assert!(result.unwrap_err().to_string().contains("not reversible"));
    }

    #[test]
    fn test_stage_service_properties() {
        let service = PiiMaskingService::new();

        assert_eq!(service.position(), StagePosition::PreBinary);
        assert!(!service.is_reversible());
        assert_eq!(service.stage_type(), StageType::Transform);
    }
}