fraiseql-confiture 0.3.4__cp311-cp311-win_amd64.whl

confiture/core/anonymization/strategies/date.py

@@ -0,0 +1,218 @@
+"""Date masking anonymization strategy.
+
+Provides flexible date anonymization with preservation options:
+- Preserve year only (replace month/day)
+- Preserve month/year (jitter day)
+- Full anonymization (replace entire date)
+
+Uses seeded randomization for deterministic output and jitter.
+Supports multiple date formats (ISO 8601, US, UK, etc).
+"""
+
+import random
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+
+from confiture.core.anonymization.strategy import AnonymizationStrategy, StrategyConfig
+
+
+@dataclass
+class DateMaskConfig(StrategyConfig):
+    """Configuration for date masking strategy.
+
+    Attributes:
+        seed: Seed for deterministic randomization
+        preserve: What to preserve:
+            - "none": Fully anonymize (replace entire date)
+            - "year": Keep year, jitter month/day
+            - "month": Keep year/month, jitter day (useful for healthcare)
+        jitter_days: Number of days to jitter (default 30)
+        output_format: Output format (default: same as input)
+
+    Example:
+        >>> config = DateMaskConfig(seed=12345, preserve="year", jitter_days=30)
+    """
+
+    preserve: str = "year"  # none, year, month
+    jitter_days: int = 30
+    output_format: str | None = None  # If None, preserve input format
+
+
+class DateMaskingStrategy(AnonymizationStrategy):
+    """Anonymization strategy for masking dates.
+
+    Provides configurable date anonymization with preservation options:
+    - Preserve year but jitter month/day
+    - Preserve year/month but jitter day
+    - Fully replace date
+
+    Features:
+    - Deterministic jitter (same seed = same jitter)
+    - Multiple format support (ISO 8601, US MM/DD/YYYY, UK DD/MM/YYYY)
+    - Preserves date boundaries (valid dates only)
+    - Handles NULL and edge cases
+
+    Example:
+        >>> config = DateMaskConfig(seed=12345, preserve="year", jitter_days=30)
+        >>> strategy = DateMaskingStrategy(config)
+        >>> strategy.anonymize("2020-05-15")
+        '2020-03-22'  # Same year, different month/day
+    """
+
+    config_type = DateMaskConfig
+    strategy_name = "date"
+
+    # Common date formats to try
+    DATE_FORMATS = [
+        "%Y-%m-%d",  # ISO 8601: 2020-05-15
+        "%m/%d/%Y",  # US: 05/15/2020
+        "%d/%m/%Y",  # UK: 15/05/2020
+        "%Y/%m/%d",  # 2020/05/15
+        "%d-%m-%Y",  # 15-05-2020
+        "%B %d, %Y",  # May 15, 2020
+        "%b %d, %Y",  # May 15, 2020
+        "%Y-%m-%d %H:%M:%S",  # ISO with time
+        "%m/%d/%Y %H:%M:%S",  # US with time
+        "%d/%m/%Y %H:%M:%S",  # UK with time
+    ]
+
+    def anonymize(self, value: str | None) -> str | None:
+        """Anonymize a date value.
+
+        Args:
+            value: Date string to anonymize
+
+        Returns:
+            Anonymized date in same format as input
+
+        Example:
+            >>> strategy.anonymize("2020-05-15")
+            '2020-03-22'
+        """
+        if value is None:
+            return None
+
+        if isinstance(value, str) and not value.strip():
+            return value
+
+        # Parse the date
+        parsed_date, detected_format = self._parse_date(value)
+
+        if parsed_date is None:
+            # Could not parse - return as-is
+            return value
+
+        # Apply anonymization based on config
+        if self.config.preserve == "none":
+            anonymized_date = self._anonymize_full(parsed_date)
+        elif self.config.preserve == "year":
+            anonymized_date = self._anonymize_preserve_year(parsed_date)
+        elif self.config.preserve == "month":
+            anonymized_date = self._anonymize_preserve_month(parsed_date)
+        else:
+            raise ValueError(f"Unknown preserve mode: {self.config.preserve}")
+
+        # Format output
+        output_format = self.config.output_format or detected_format
+        return anonymized_date.strftime(output_format)
+
+    def _parse_date(self, value: str) -> tuple[datetime | None, str | None]:
+        """Parse date string in any supported format.
+
+        Args:
+            value: Date string to parse
+
+        Returns:
+            Tuple of (parsed datetime, detected format) or (None, None)
+        """
+        for fmt in self.DATE_FORMATS:
+            try:
+                parsed = datetime.strptime(value.strip(), fmt)
+                return parsed, fmt
+            except ValueError:
+                continue
+
+        # Could not parse
+        return None, None
+
+    def _anonymize_full(self, date: datetime) -> datetime:
+        """Fully anonymize date (replace entire date).
+
+        Args:
+            date: Date to anonymize
+
+        Returns:
+            Anonymized date
+        """
+        # Use seed to generate deterministic jitter
+        rng = random.Random(f"{self.config.seed}:{date.isoformat()}".encode())
+
+        # Random jitter in days
+        jitter = rng.randint(-self.config.jitter_days, self.config.jitter_days)
+
+        return date + timedelta(days=jitter)
+
+    def _anonymize_preserve_year(self, date: datetime) -> datetime:
+        """Anonymize but preserve year.
+
+        Args:
+            date: Date to anonymize
+
+        Returns:
+            Anonymized date with same year
+        """
+        rng = random.Random(f"{self.config.seed}:{date.isoformat()}:year".encode())
+
+        # Random month (1-12)
+        month = rng.randint(1, 12)
+
+        # Random day (1-28 to be safe for all months)
+        day = rng.randint(1, 28)
+
+        try:
+            return date.replace(month=month, day=day)
+        except ValueError:
+            # Invalid date (e.g., Feb 30) - return as-is
+            return date
+
+    def _anonymize_preserve_month(self, date: datetime) -> datetime:
+        """Anonymize but preserve year and month.
+
+        Jitter the day only (useful for healthcare data where month can be significant).
+
+        Args:
+            date: Date to anonymize
+
+        Returns:
+            Anonymized date with same year/month
+        """
+        rng = random.Random(f"{self.config.seed}:{date.isoformat()}:month".encode())
+
+        # Random day within same month
+        # For simplicity, use day 1-28 to be safe
+        day = rng.randint(1, 28)
+
+        try:
+            return date.replace(day=day)
+        except ValueError:
+            # Invalid date - return as-is
+            return date
+
+    def validate(self, value: str) -> bool:
+        """Check if strategy can handle this value type.
+
+        Args:
+            value: Sample value to validate
+
+        Returns:
+            True if value is a string or None
+        """
+        return isinstance(value, str) or value is None
+
+    def short_name(self) -> str:
+        """Return short strategy name for logging.
+
+        Returns:
+            Short name (e.g., "date:preserve_year")
+        """
+        return f"{self.strategy_name}:preserve_{self.config.preserve}"

confiture/core/anonymization/strategies/differential_privacy.py

@@ -0,0 +1,398 @@
+"""Differential privacy anonymization strategy.
+
+Provides mathematical privacy guarantee using noise addition. Adds carefully
+calibrated random noise to numerical data to prevent individual re-identification.
+
+Features:
+- Mathematical privacy guarantee (epsilon-delta privacy)
+- Noise calibration: Scale noise to data sensitivity
+- Budget tracking: Track privacy budget consumption
+- Configurable mechanisms: Laplace, Gaussian, Exponential
+- Utility-privacy tradeoff: Control accuracy vs privacy
+
+Mathematical Background:
+    Differential privacy: For any two adjacent datasets D and D',
+    P(M(D) ∈ S) ≤ e^ε * P(M(D') ∈ S) + δ
+
+    Where:
+    - M: privacy mechanism (adds noise)
+    - ε (epsilon): privacy parameter (lower = more private)
+    - δ (delta): failure probability (usually ≈ 1/n)
+    - S: set of possible outputs
+
+Use Cases:
+    - Statistical aggregate queries (average age, sum of purchases)
+    - Census data (count distributions)
+    - Salary data (ranges, distributions)
+    - Location data (geographic aggregates)
+    - Sensor data (aggregate statistics)
+
+Privacy Levels:
+    ε = 10: Strong privacy, significant noise, utility degraded
+    ε = 1:  Very strong privacy, significant noise impact
+    ε = 0.1: Extremely strong privacy, high noise, low utility
+    ε = ∞: No privacy (no noise added)
+
+Example:
+    Age: 35 → 35 + noise ≈ 37.2 (with ε=1, Δf=1)
+    Salary: 50000 → 50000 + noise ≈ 50241.5 (with ε=0.5, Δf=1000)
+
+Mechanisms:
+    - Laplace: Fast, simple, works well for small datasets
+    - Gaussian: Better utility for large datasets
+    - Exponential: For exponential-family distributions
+
+NOT suitable for:
+    - Individual records (differential privacy is for aggregates)
+    - Categorical data (use hashing instead)
+    - Small datasets (noise makes utility poor)
+    - Real-time applications (budget tracking needed)
+    - High-accuracy requirements (inherent noise trade-off)
+"""
+
+import random
+from dataclasses import dataclass
+from typing import Any
+
+from confiture.core.anonymization.strategy import (
+    AnonymizationStrategy,
+    StrategyConfig,
+)
+
+
+@dataclass
+class DifferentialPrivacyConfig(StrategyConfig):
+    """Configuration for DifferentialPrivacyStrategy.
+
+    Attributes:
+        epsilon: Privacy budget (lower = more private)
+        delta: Failure probability (usually 1/dataset_size)
+        mechanism: Noise mechanism ('laplace', 'gaussian', 'exponential')
+        data_type: Type of data ('numeric', 'categorical', 'location')
+        sensitivity: Data sensitivity (max change in one record)
+        budget_total: Total privacy budget available
+        budget_per_value: Budget per anonymization operation
+    """
+
+    epsilon: float = 1.0
+    """Privacy budget (lower = more private, 0.1-10 typical)."""
+
+    delta: float = 1e-5
+    """Failure probability (typically 1/dataset_size)."""
+
+    mechanism: str = "laplace"
+    """Noise mechanism: laplace, gaussian, exponential."""
+
+    data_type: str = "numeric"
+    """Type of data: numeric, categorical, location."""
+
+    sensitivity: float = 1.0
+    """Data sensitivity (max change from one record)."""
+
+    budget_total: float = 10.0
+    """Total privacy budget available."""
+
+    budget_per_value: float = 0.1
+    """Budget consumed per anonymization operation."""
+
+
+class DifferentialPrivacyStrategy(AnonymizationStrategy):
+    """Differential privacy using noise addition.
+
+    Provides formal mathematical privacy guarantee by adding noise to
+    numerical data. Suitable for aggregate data and statistical queries,
+    NOT for individual records.
+
+    Features:
+        - Math privacy: ε-δ differential privacy guarantee
+        - Noise calibration: Automatic scale to data
+        - Budget tracking: Monitor privacy budget
+        - Mechanism choice: Laplace, Gaussian, Exponential
+        - Configurable: Control privacy-utility tradeoff
+
+    Privacy Mathematics:
+        Differential privacy ensures:
+        P(M(D) ∈ S) ≤ e^ε * P(M(D') ∈ S) + δ
+
+        Interpretation:
+        - Small ε: Difficult to determine if specific person in data
+        - Large ε: Easy to determine presence
+        - ε = 1: Strong but not extreme privacy
+        - ε = 10: Weaker privacy, less noise
+
+    How It Works:
+        1. Calculate data sensitivity (max change from one record)
+        2. Calculate noise scale based on ε and sensitivity
+        3. Sample noise from chosen distribution
+        4. Add noise to value
+        5. Track privacy budget consumption
+
+    Privacy Budget:
+        Each anonymization consumes budget:
+        budget_remaining -= budget_per_value
+
+        When budget exhausted: Stop anonymization or reject operations
+
+    NOT Suitable For:
+        - Individual PII (use hashing or FPE)
+        - Identifying records (differential privacy for aggregates)
+        - Categorical data (use hashing)
+        - Exact values needed (noise decreases accuracy)
+        - Real-time systems (budget tracking overhead)
+
+    Suitable For:
+        - Statistical queries (avg age, sum amounts)
+        - Census data (population counts)
+        - Aggregate salary data (salary ranges, distributions)
+        - Location heatmaps (aggregate geographic data)
+        - Sensor networks (aggregate sensor readings)
+
+    Example:
+        >>> config = DifferentialPrivacyConfig(
+        ...     epsilon=1.0,
+        ...     delta=1e-5,
+        ...     mechanism='laplace',
+        ...     data_type='numeric',
+        ...     sensitivity=1.0,
+        ...     budget_total=10.0,
+        ...     budget_per_value=0.1
+        ... )
+        >>> strategy = DifferentialPrivacyStrategy(config)
+        >>>
+        >>> # Anonymize numeric values
+        >>> values = [35, 42, 28, 55]  # Ages
+        >>> anonymized = [strategy.anonymize(v) for v in values]
+        >>> # [36.2, 40.8, 27.5, 56.1] (with noise added)
+        >>>
+        >>> # Budget tracking
+        >>> print(f"Budget remaining: {strategy.budget_remaining:.1f}")
+        >>> # Budget remaining: 9.6
+    """
+
+    budget_remaining: float = 0.0
+    """Remaining privacy budget (decreases as values processed)."""
+
+    def __init__(self, config: DifferentialPrivacyConfig | None = None):
+        """Initialize differential privacy strategy.
+
+        Args:
+            config: DifferentialPrivacyConfig instance
+
+        Raises:
+            ValueError: If configuration invalid
+        """
+        config = config or DifferentialPrivacyConfig()
+        super().__init__(config)
+        self.config: DifferentialPrivacyConfig = config
+        self.budget_remaining = config.budget_total
+        self._validate_config()
+
+    def _validate_config(self) -> None:
+        """Validate configuration values.
+
+        Raises:
+            ValueError: If invalid values
+        """
+        if self.config.epsilon <= 0:
+            raise ValueError("Epsilon must be positive")
+
+        if self.config.delta < 0 or self.config.delta >= 1:
+            raise ValueError("Delta must be in [0, 1)")
+
+        if self.config.sensitivity <= 0:
+            raise ValueError("Sensitivity must be positive")
+
+        if self.config.mechanism not in {"laplace", "gaussian", "exponential"}:
+            raise ValueError("Mechanism must be laplace, gaussian, or exponential")
+
+        if self.config.data_type not in {"numeric", "categorical", "location"}:
+            raise ValueError("Data type must be numeric, categorical, or location")
+
+    def anonymize(self, value: Any) -> Any:
+        """Add noise to value using differential privacy.
+
+        Args:
+            value: Numeric value to anonymize
+
+        Returns:
+            Noisy value (float)
+
+        Raises:
+            ValueError: If value is not numeric or privacy budget exhausted
+        """
+        # Check budget
+        if self.budget_remaining <= 0:
+            raise ValueError("Privacy budget exhausted. Cannot anonymize more values.")
+
+        # Handle NULL
+        if value is None:
+            return None
+
+        # Validate numeric
+        try:
+            numeric_value = float(value)
+        except (TypeError, ValueError) as e:
+            raise ValueError(
+                f"DifferentialPrivacyStrategy only works with numeric values, "
+                f"got {type(value).__name__}: {value}"
+            ) from e
+
+        # Calculate noise scale
+        noise_scale = self._calculate_noise_scale()
+
+        # Sample noise
+        noise = self._sample_noise(noise_scale)
+
+        # Consume budget
+        self.budget_remaining -= self.config.budget_per_value
+
+        # Return noisy value
+        return numeric_value + noise
+
+    def _calculate_noise_scale(self) -> float:
+        """Calculate scale for noise distribution.
+
+        Scale depends on:
+        - Epsilon (privacy parameter)
+        - Sensitivity (max change from one record)
+        - Mechanism type
+
+        Returns:
+            Scale for noise distribution
+        """
+        # Scale = Δf / ε
+        # Where Δf is sensitivity, ε is privacy budget
+        scale = self.config.sensitivity / self.config.epsilon
+
+        return scale
+
+    def _sample_noise(self, scale: float) -> float:
+        """Sample noise from chosen distribution.
+
+        Args:
+            scale: Scale parameter for distribution
+
+        Returns:
+            Sampled noise value
+        """
+        if self.config.mechanism == "laplace":
+            # Laplace distribution: symmetric around 0
+            # Variance = 2 * scale^2
+            u = random.uniform(-0.5, 0.5)
+            noise = (
+                -scale
+                * (1 if u > 0 else -1)
+                * sum(1 for _ in range(int(-scale * __import__("math").log(2 * abs(u)))))
+            )
+            # Simplified: use exponential approximation
+            noise = (
+                scale * __import__("math").log(random.random())
+                if random.random() > 0.5
+                else -scale * __import__("math").log(random.random())
+            )
+            return noise
+
+        elif self.config.mechanism == "gaussian":
+            # Gaussian distribution: normal distribution
+            # Variance = 2 * scale^2 / delta (for (ε, δ)-DP)
+            import math
+
+            variance = 2 * (scale**2) / self.config.delta
+            stddev = math.sqrt(variance)
+            noise = random.gauss(0, stddev)
+            return noise
+
+        elif self.config.mechanism == "exponential":
+            # Exponential mechanism: for exponential-family distributions
+            scale_exp = 2 * scale / self.config.epsilon
+            noise = random.expovariate(1 / scale_exp)
+            if random.random() > 0.5:
+                noise = -noise
+            return noise
+
+        return 0.0
+
+    def validate(self, value: Any) -> bool:
+        """Differential privacy only works with numeric values.
+
+        Args:
+            value: Value to validate
+
+        Returns:
+            True if value is numeric
+        """
+        try:
+            float(value)
+            return True
+        except (TypeError, ValueError):
+            return False
+
+    def validate_comprehensive(
+        self,
+        value: Any,
+        column_name: str = "",
+        table_name: str = "",
+    ) -> tuple[bool, list[str]]:
+        """Comprehensive validation for differential privacy.
+
+        Args:
+            value: Value to validate
+            column_name: Column name (for error context)
+            table_name: Table name (for error context)
+
+        Returns:
+            Tuple of (is_valid: bool, errors: list[str])
+        """
+        errors = []
+
+        # Check numeric
+        try:
+            numeric_value = float(value)
+            if numeric_value != numeric_value:  # NaN check
+                errors.append(f"Column {table_name}.{column_name}: NaN value cannot be anonymized")
+        except (TypeError, ValueError):
+            errors.append(
+                f"Column {table_name}.{column_name}: "
+                f"DifferentialPrivacyStrategy requires numeric values, "
+                f"got {type(value).__name__}"
+            )
+
+        # Check budget
+        if self.budget_remaining <= 0:
+            errors.append(
+                f"Column {table_name}.{column_name}: "
+                f"Privacy budget exhausted (remaining: {self.budget_remaining:.1f})"
+            )
+
+        # Check epsilon validity
+        if self.config.epsilon > 10:
+            errors.append(
+                f"Column {table_name}.{column_name}: "
+                f"Epsilon {self.config.epsilon} is high (privacy may be weak)"
+            )
+
+        return len(errors) == 0, errors
+
+    @property
+    def is_reversible(self) -> bool:
+        """Differential privacy is irreversible.
+
+        Returns:
+            False (noise is irreversible)
+        """
+        return False
+
+    def get_budget_status(self) -> dict[str, float]:
+        """Get privacy budget status.
+
+        Returns:
+            Dict with budget information
+        """
+        return {
+            "total": self.config.budget_total,
+            "remaining": self.budget_remaining,
+            "consumed": self.config.budget_total - self.budget_remaining,
+            "percentage": (
+                100 * (self.config.budget_total - self.budget_remaining) / self.config.budget_total
+            ),
+        }