fraiseql-confiture 0.3.7__cp311-cp311-macosx_11_0_arm64.whl

confiture/core/anonymization/strategies/name.py

@@ -0,0 +1,298 @@
+"""Name masking anonymization strategy.
+
+Provides deterministic name masking with multiple format options:
+- Preserve initials only (e.g., "John Doe" → "J.D.")
+- Generate random names (deterministic from seed)
+- Generate name from pools (first names + last names)
+
+Uses seeded randomization to ensure same input always produces same output.
+"""
+
+import random
+from dataclasses import dataclass
+
+from confiture.core.anonymization.strategy import AnonymizationStrategy, StrategyConfig
+
+# Common first names (50 names for diversity)
+FIRST_NAMES = [
+    "James",
+    "Mary",
+    "Robert",
+    "Patricia",
+    "Michael",
+    "Jennifer",
+    "William",
+    "Linda",
+    "David",
+    "Barbara",
+    "Richard",
+    "Elizabeth",
+    "Joseph",
+    "Susan",
+    "Charles",
+    "Jessica",
+    "Christopher",
+    "Sarah",
+    "Daniel",
+    "Karen",
+    "Matthew",
+    "Nancy",
+    "Anthony",
+    "Lisa",
+    "Mark",
+    "Betty",
+    "Donald",
+    "Margaret",
+    "Steven",
+    "Sandra",
+    "Paul",
+    "Ashley",
+    "Andrew",
+    "Kimberly",
+    "Joshua",
+    "Emily",
+    "Kenneth",
+    "Donna",
+    "Kevin",
+    "Michelle",
+    "Brian",
+    "Dorothy",
+    "George",
+    "Carol",
+    "Edward",
+    "Amanda",
+    "Ronald",
+    "Melissa",
+    "Timothy",
+    "Deborah",
+    "Jason",
+    "Stephanie",
+    "Jeffrey",
+]
+
+# Common last names (50 names for diversity)
+LAST_NAMES = [
+    "Smith",
+    "Johnson",
+    "Williams",
+    "Brown",
+    "Jones",
+    "Garcia",
+    "Miller",
+    "Davis",
+    "Rodriguez",
+    "Martinez",
+    "Hernandez",
+    "Lopez",
+    "Gonzalez",
+    "Wilson",
+    "Anderson",
+    "Thomas",
+    "Taylor",
+    "Moore",
+    "Jackson",
+    "Martin",
+    "Lee",
+    "Perez",
+    "Thompson",
+    "White",
+    "Harris",
+    "Sanchez",
+    "Clark",
+    "Ramirez",
+    "Lewis",
+    "Robinson",
+    "Walker",
+    "Young",
+    "Allen",
+    "King",
+    "Wright",
+    "Scott",
+    "Torres",
+    "Peterson",
+    "Phillips",
+    "Campbell",
+    "Parker",
+    "Evans",
+    "Edwards",
+    "Collins",
+    "Reyes",
+    "Stewart",
+    "Morris",
+    "Morales",
+    "Murphy",
+    "Rogers",
+    "Morgan",
+    "Peterson",
+    "Cooper",
+]
+
+
+@dataclass
+class NameMaskConfig(StrategyConfig):
+    """Configuration for name masking strategy.
+
+    Attributes:
+        seed: Seed for deterministic randomization
+        format_type: Output format:
+            - "firstname_lastname": "John Doe" → "Michael Patricia" (from name pools)
+            - "initials": "John Doe" → "J.D." (preserve initials)
+            - "random": "John Doe" → "XyZ4qW9" (random string)
+        preserve_initial: If True, keep original first letter
+        case_preserving: If True, preserve original case
+
+    Example:
+        >>> config = NameMaskConfig(seed=12345, format_type="firstname_lastname")
+    """
+
+    format_type: str = "firstname_lastname"  # firstname_lastname, initials, random
+    preserve_initial: bool = False  # Only for firstname_lastname format
+    case_preserving: bool = True  # Preserve original case
+
+
+class NameMaskingStrategy(AnonymizationStrategy):
+    """Anonymization strategy for masking personal names.
+
+    Provides multiple name masking formats with deterministic output based on seed.
+    Same input + same seed = same output (enables foreign key consistency).
+
+    Features:
+    - Format-preserving (maintains name-like structure)
+    - Deterministic (seed-based)
+    - Configurable output format
+    - Handles NULL and edge cases
+
+    Example:
+        >>> config = NameMaskConfig(seed=12345, format_type="firstname_lastname")
+        >>> strategy = NameMaskingStrategy(config)
+        >>> strategy.anonymize("John Doe")
+        'Michael Johnson'
+        >>> strategy.anonymize("John Doe")  # Same seed = same output
+        'Michael Johnson'
+    """
+
+    config_type = NameMaskConfig
+    strategy_name = "name"
+
+    def anonymize(self, value: str | None) -> str | None:
+        """Anonymize a name value.
+
+        Args:
+            value: Name to anonymize
+
+        Returns:
+            Anonymized name in configured format
+
+        Example:
+            >>> strategy.anonymize("John Doe")
+            'Michael Johnson'
+        """
+        if value is None:
+            return None
+
+        if isinstance(value, str) and not value.strip():
+            return value
+
+        config = self.config
+
+        if config.format_type == "firstname_lastname":
+            return self._mask_firstname_lastname(value)
+        elif config.format_type == "initials":
+            return self._mask_initials(value)
+        elif config.format_type == "random":
+            return self._mask_random(value)
+        else:
+            raise ValueError(f"Unknown format_type: {config.format_type}")
+
+    def _mask_firstname_lastname(self, value: str) -> str:
+        """Mask with random first and last name.
+
+        Args:
+            value: Name to mask
+
+        Returns:
+            Anonymized firstname lastname
+        """
+        parts = value.strip().split()
+
+        if not parts:
+            return value
+
+        # Use seed to generate reproducible random names
+        rng = random.Random(f"{self.config.seed}:{value}".encode())
+
+        # Get random first name
+        first_name = rng.choice(FIRST_NAMES)
+
+        # Get random last name
+        last_name = rng.choice(LAST_NAMES)
+
+        # Apply case preservation if needed
+        if self.config.case_preserving and parts:
+            # Preserve case of original first name
+            if parts[0] and parts[0][0].islower():
+                first_name = first_name.lower()
+
+            # Preserve case of original last name (if exists)
+            if len(parts) > 1 and parts[1] and parts[1][0].islower():
+                last_name = last_name.lower()
+
+        return f"{first_name} {last_name}"
+
+    def _mask_initials(self, value: str) -> str:
+        """Mask with initials only.
+
+        Args:
+            value: Name to mask
+
+        Returns:
+            Initials (e.g., "J.D.")
+        """
+        parts = value.strip().split()
+
+        if not parts:
+            return value
+
+        # Get initials from original name
+        initials = [part[0].upper() for part in parts if part]
+
+        return ".".join(initials) + "."
+
+    def _mask_random(self, value: str) -> str:
+        """Mask with random string.
+
+        Args:
+            value: Name to mask
+
+        Returns:
+            Random string of same length as original
+        """
+        if not value:
+            return value
+
+        # Use seed for reproducibility
+        rng = random.Random(f"{self.config.seed}:{value}".encode())
+
+        # Generate random string of same length
+        length = len(value.strip())
+        chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+        return "".join(rng.choices(chars, k=length))
+
+    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., "name:initials")
+        """
+        return f"{self.strategy_name}:{self.config.format_type}"

confiture/core/anonymization/strategies/phone.py

@@ -0,0 +1,119 @@
+"""Phone number masking anonymization strategy.
+
+Generates deterministic fake phone numbers from real ones, useful for:
+    - PII protection in test/staging environments
+    - Preserving phone-like format for testing
+    - Reproducible anonymization (deterministic with seed)
+"""
+
+import hashlib
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from confiture.core.anonymization.strategy import (
+    AnonymizationStrategy,
+    StrategyConfig,
+)
+
+
+@dataclass
+class PhoneMaskConfig(StrategyConfig):
+    """Configuration for PhoneMaskingStrategy.
+
+    Attributes:
+        format: Phone number format template (use {number} placeholder)
+        preserve_country_code: If True, keep original country code
+        seed_env_var: Environment variable containing seed
+        seed: Hardcoded seed (testing only)
+    """
+
+    format: str = "+1-555-{number}"
+    """Phone format template with {number} placeholder."""
+
+    preserve_country_code: bool = False
+    """If True, try to preserve original country code."""
+
+
+class PhoneMaskingStrategy(AnonymizationStrategy):
+    """Generate deterministic fake phone numbers from real ones.
+
+    Features:
+        - Deterministic: Same number + seed = same fake number
+        - Format customizable: Template-based generation
+        - Format preserving: Output looks like a real phone number
+        - Unique: Preserves uniqueness for referential integrity
+
+    Example:
+        >>> config = PhoneMaskConfig(
+        ...     format="+1-555-{number}",
+        ...     seed_env_var='ANONYMIZATION_SEED'
+        ... )
+        >>> strategy = PhoneMaskingStrategy(config)
+        >>> result = strategy.anonymize('+1-202-555-0123')
+        >>> result  # e.g., '+1-555-1234'
+        '+1-555-1234'
+    """
+
+    # Basic phone number regex (allows various formats)
+    PHONE_REGEX = re.compile(r"[\d\s\-\+\(\)]{10,}")
+
+    def __init__(self, config: PhoneMaskConfig | None = None):
+        """Initialize phone masking strategy.
+
+        Args:
+            config: PhoneMaskConfig instance
+        """
+        config = config or PhoneMaskConfig()
+        super().__init__(config)
+        self.config: PhoneMaskConfig = config
+
+    def anonymize(self, value: Any) -> Any:
+        """Generate fake phone number from real number.
+
+        Args:
+            value: Phone number to anonymize
+
+        Returns:
+            Fake phone number with same format as original
+
+        Example:
+            >>> strategy = PhoneMaskingStrategy(PhoneMaskConfig(seed=12345))
+            >>> strategy.anonymize('+1-202-555-0123')
+            '+1-555-1234'
+        """
+        # Handle NULL
+        if value is None:
+            return None
+
+        # Handle empty string
+        value_str = str(value).strip()
+        if not value_str:
+            return ""
+
+        # Create deterministic hash from phone number
+        hash_value = hashlib.sha256(f"{self._seed}:{value_str}".encode()).hexdigest()
+
+        # Extract digits to generate phone number
+        # Use hash to create a 4-digit phone number suffix
+        number_suffix = str(int(hash_value[:8], 16) % 10000).zfill(4)
+
+        # Format output
+        output = self.config.format.format(number=number_suffix)
+
+        return output
+
+    def validate(self, value: Any) -> bool:
+        """Check if value looks like a phone number.
+
+        Args:
+            value: Value to validate
+
+        Returns:
+            True if value matches basic phone pattern
+        """
+        if value is None:
+            return False
+
+        value_str = str(value).strip()
+        return bool(self.PHONE_REGEX.match(value_str))

confiture/core/anonymization/strategies/preserve.py

@@ -0,0 +1,85 @@
+"""Preserve (no-op) anonymization strategy.
+
+Provides a no-operation strategy that returns values unchanged.
+Useful for:
+- Marking columns that should NOT be anonymized
+- Placeholder in strategy chains
+- Configuration clarity (explicit "don't anonymize" intent)
+- Testing and debugging
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+from confiture.core.anonymization.strategy import AnonymizationStrategy, StrategyConfig
+
+
+@dataclass
+class PreserveConfig(StrategyConfig):
+    """Configuration for preserve strategy.
+
+    This strategy has no configuration options beyond base StrategyConfig.
+    It simply returns values unchanged.
+
+    Example:
+        >>> config = PreserveConfig(seed=12345)
+    """
+
+    pass
+
+
+class PreserveStrategy(AnonymizationStrategy):
+    """No-operation anonymization strategy.
+
+    Returns values unchanged. Useful for marking columns that should not
+    be anonymized or as a placeholder in processing chains.
+
+    Features:
+    - Identity operation (returns input unchanged)
+    - Handles all value types
+    - NULL-safe
+    - Useful for explicit "preserve" intent in configurations
+
+    Example:
+        >>> config = PreserveConfig()
+        >>> strategy = PreserveStrategy(config)
+        >>> strategy.anonymize("sensitive_data")
+        'sensitive_data'  # Unchanged
+    """
+
+    config_type = PreserveConfig
+    strategy_name = "preserve"
+
+    def anonymize(self, value):
+        """Return value unchanged.
+
+        Args:
+            value: Any value
+
+        Returns:
+            The same value unchanged
+
+        Example:
+            >>> strategy.anonymize("test@example.com")
+            'test@example.com'
+        """
+        return value
+
+    def validate(self, value: Any) -> bool:  # noqa: ARG002
+        """Check if strategy can handle this value type.
+
+        Args:
+            value: Sample value to validate (unused, preserve accepts any)
+
+        Returns:
+            True (preserve accepts any value type)
+        """
+        return True
+
+    def short_name(self) -> str:
+        """Return short strategy name for logging.
+
+        Returns:
+            Short name (e.g., "preserve")
+        """
+        return self.strategy_name

confiture/core/anonymization/strategies/redact.py

@@ -0,0 +1,101 @@
+"""Simple redaction anonymization strategy.
+
+One-size-fits-all redaction for sensitive data that should be completely hidden,
+not anonymized to a plausible value.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+from confiture.core.anonymization.strategy import (
+    AnonymizationStrategy,
+    StrategyConfig,
+)
+
+
+@dataclass
+class RedactConfig(StrategyConfig):
+    """Configuration for SimpleRedactStrategy.
+
+    Attributes:
+        replacement: Text to replace sensitive values with
+        seed_env_var: Environment variable containing seed (unused for redaction)
+        seed: Hardcoded seed (unused for redaction)
+    """
+
+    replacement: str = "[REDACTED]"
+    """Text to use for all redacted values."""
+
+
+class SimpleRedactStrategy(AnonymizationStrategy):
+    """Simple one-size-fits-all redaction strategy.
+
+    Features:
+        - Fast: No hashing or computation
+        - Complete: All data values replaced with same text
+        - Safe: Zero information leakage
+        - Simple: Easy to understand and audit
+
+    Use when:
+        - PII is highly sensitive (no testing needed with real-like data)
+        - You don't need to preserve data format (testing doesn't rely on structure)
+        - You want maximum privacy with zero complexity
+
+    Don't use when:
+        - You need to preserve uniqueness for testing (FK constraints)
+        - You need format-preserving anonymization (testing email-like values)
+        - You need to correlate anonymized data across tables
+
+    Example:
+        >>> config = RedactConfig(replacement="[HIDDEN]")
+        >>> strategy = SimpleRedactStrategy(config)
+        >>> strategy.anonymize("secret data")
+        '[HIDDEN]'
+    """
+
+    def __init__(self, config: RedactConfig | None = None):
+        """Initialize redaction strategy.
+
+        Args:
+            config: RedactConfig instance
+        """
+        config = config or RedactConfig()
+        super().__init__(config)
+        self.config: RedactConfig = config
+
+    def anonymize(self, value: Any) -> Any:
+        """Redact value to replacement text.
+
+        Args:
+            value: Value to redact
+
+        Returns:
+            Replacement text (same for all values)
+
+        Example:
+            >>> strategy = SimpleRedactStrategy()
+            >>> strategy.anonymize("anything")
+            '[REDACTED]'
+            >>> strategy.anonymize("123")
+            '[REDACTED]'
+            >>> strategy.anonymize(None)  # Special case: NULL stays NULL
+        """
+        # Special case: NULL stays NULL
+        if value is None:
+            return None
+
+        # All other values replaced with redaction text
+        return self.config.replacement
+
+    def validate(self, value: Any) -> bool:
+        """Redaction works for any value type.
+
+        Args:
+            value: Value to validate (not really used)
+
+        Returns:
+            Always True (redaction works for all types)
+        """
+        # Redaction works for all types
+        del value
+        return True