fraiseql-confiture 0.3.4__cp311-cp311-win_amd64.whl

confiture/core/anonymization/strategies/email.py

@@ -0,0 +1,141 @@
+"""Email masking anonymization strategy.
+
+Generates deterministic fake emails from real ones, useful for:
+    - PII protection in test/staging environments
+    - Preserving email-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 EmailMaskConfig(StrategyConfig):
+    """Configuration for EmailMaskingStrategy.
+
+    Attributes:
+        format: Email format template (use {hash} placeholder)
+        hash_length: Length of hash in generated email
+        preserve_domain: If True, keep original domain (not recommended)
+        seed_env_var: Environment variable containing seed
+        seed: Hardcoded seed (testing only)
+    """
+
+    format: str = "user_{hash}@example.com"
+    """Email format template with {hash} placeholder."""
+
+    hash_length: int = 8
+    """Length of hash portion (e.g., 8 = user_12345678@example.com)."""
+
+    preserve_domain: bool = False
+    """If True, keep original domain (security risk, not recommended)."""
+
+
+class EmailMaskingStrategy(AnonymizationStrategy):
+    """Generate deterministic fake emails from real ones.
+
+    Features:
+        - Deterministic: Same email + seed = same fake email
+        - Format customizable: Template-based generation
+        - Format preserving: Output looks like a real email
+        - Unique: Preserves uniqueness for referential integrity
+
+    Security Note:
+        - preserve_domain=False (default) is more secure
+        - preserve_domain=True leaks organizational information
+        - Should always use seed from environment variable
+
+    Example:
+        >>> config = EmailMaskConfig(
+        ...     format="user_{hash}@example.com",
+        ...     hash_length=8,
+        ...     seed_env_var='ANONYMIZATION_SEED'
+        ... )
+        >>> strategy = EmailMaskingStrategy(config)
+        >>> result = strategy.anonymize('john@example.com')
+        >>> result  # e.g., 'user_a1b2c3d4@example.com'
+        'user_a1b2c3d4@example.com'
+    """
+
+    # Simple email regex for validation
+    EMAIL_REGEX = re.compile(r"^[^@]+@[^@]+\.[^@]+$")
+
+    def __init__(self, config: EmailMaskConfig | None = None):
+        """Initialize email masking strategy.
+
+        Args:
+            config: EmailMaskConfig instance
+        """
+        config = config or EmailMaskConfig()
+        super().__init__(config)
+        self.config: EmailMaskConfig = config
+
+    def anonymize(self, value: Any) -> Any:
+        """Generate fake email from real email.
+
+        Args:
+            value: Email address to anonymize
+
+        Returns:
+            Fake email with same format as original
+
+        Example:
+            >>> strategy = EmailMaskingStrategy(EmailMaskConfig(seed=12345))
+            >>> strategy.anonymize('alice@example.com')
+            'user_a1b2c3d4@example.com'
+        """
+        # 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 email
+        hash_value = hashlib.sha256(f"{self._seed}:{value_str}".encode()).hexdigest()[
+            : self.config.hash_length
+        ]
+
+        # Extract domain if preserving (not recommended)
+        if self.config.preserve_domain:
+            try:
+                _, domain = value_str.split("@", 1)
+            except ValueError:
+                # Not a valid email, use example domain
+                domain = "example.com"
+        else:
+            domain = "example.com"
+
+        # Format output
+        output = self.config.format.format(hash=hash_value)
+
+        # Replace example.com with actual domain if requested
+        if self.config.preserve_domain:
+            output = output.replace("example.com", domain)
+
+        return output
+
+    def validate(self, value: Any) -> bool:
+        """Check if value looks like an email address.
+
+        Args:
+            value: Value to validate
+
+        Returns:
+            True if value matches basic email pattern
+        """
+        if value is None:
+            return False
+
+        value_str = str(value).strip()
+        return bool(self.EMAIL_REGEX.match(value_str))

confiture/core/anonymization/strategies/format_preserving_encryption.py

@@ -0,0 +1,310 @@
+"""Format-Preserving Encryption (FPE) strategy.
+
+Provides encryption that preserves input format/length/type, making encrypted
+data look like original data. Uses FF3 cipher for format-preserving encryption.
+
+Features:
+- Format preservation: Encrypted length = original length
+- Type preservation: Type of encrypted output matches input
+- Deterministic: Same input + key = same ciphertext
+- Reversible: Can decrypt with proper key
+- KMS-managed keys: Uses KMS for encryption key management
+
+Format preservation examples:
+    Email: 16 chars → 16 char email-like value
+    Credit Card: 4111-1111-1111-1111 → 4XXX-XXXX-XXXX-XXXX
+    SSN: 123-45-6789 → XXX-XX-XXXX
+    Phone: +1-555-123-4567 → +1-XXX-XXX-XXXX
+
+Use cases:
+- Database encryption in-place (migrate without schema changes)
+- Deterministic encryption (same plaintext = same ciphertext)
+- Compliance scenarios (need to preserve format)
+- Reversible but with key protection (unlike hashing)
+
+Security:
+- Reversible with proper key (unlike hashing)
+- Format preservation may leak some information
+- NOT suitable for highest security levels
+- Better than masking for compliance
+- Requires KMS key protection
+
+Note on FF3:
+    FF3 is NIST-approved format-preserving encryption cipher (SP 800-38G)
+    - Deterministic: same plaintext + key = same ciphertext
+    - Length-preserving: ciphertext length = plaintext length
+    - Format-preserving: ciphertext looks like plaintext format
+    - Slower than regular encryption (iterative)
+    - Not streaming-capable (process entire value at once)
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+from confiture.core.anonymization.security.kms_manager import KMSClient
+from confiture.core.anonymization.strategy import (
+    AnonymizationStrategy,
+    StrategyConfig,
+)
+
+
+@dataclass
+class FPEConfig(StrategyConfig):
+    """Configuration for FormatPreservingEncryptionStrategy.
+
+    Attributes:
+        algorithm: FPE algorithm to use (e.g., 'ff3-1')
+        key_id: KMS key ID for encryption
+        tweak: Optional tweak value for additional context
+        preserve_length: If True, output length = input length
+        preserve_type: If True, output type = input type
+    """
+
+    algorithm: str = "ff3-1"
+    """FPE algorithm: ff3-1 (NIST SP 800-38G Rev 1)."""
+
+    key_id: str = "fpe-key"
+    """KMS key ID for encryption."""
+
+    tweak: str = ""
+    """Optional tweak value for additional context."""
+
+    preserve_length: bool = True
+    """Output length equals input length."""
+
+    preserve_type: bool = True
+    """Output type equals input type (numeric, alphanumeric, etc.)."""
+
+
+class FormatPreservingEncryptionStrategy(AnonymizationStrategy):
+    """Format-preserving encryption using FF3 cipher.
+
+    Encrypts data while preserving format, making encrypted data
+    indistinguishable from original in terms of format. Requires
+    KMS key management and is reversible with proper key.
+
+    Features:
+        - Format preservation: Length, type preserved
+        - Deterministic: Same input = same ciphertext
+        - Reversible: Can decrypt with proper KMS key
+        - KMS-managed: Keys stored securely
+        - Compliance-ready: NIST-approved algorithm
+
+    Algorithm Details:
+        - Uses FF3-1 cipher (NIST SP 800-38G Rev 1)
+        - Deterministic (same plaintext → same ciphertext)
+        - Length-preserving (output length = input length)
+        - Format-preserving (output looks like input)
+        - Requires KMS key access
+
+    Security Considerations:
+        - REVERSIBLE (unlike hashing) - requires strong key protection
+        - Format preservation may leak information
+        - Deterministic means identical inputs produce same output
+        - Not suitable for one-time pads or streaming
+        - Requires KMS key rotations for re-encryption
+
+    Implementation Note:
+        This is a placeholder for FF3 implementation. Real implementation
+        would use cryptography library with ff3 module or pyffx.
+
+    Example:
+        >>> from confiture.core.anonymization.security.kms_manager import (
+        ...     KMSFactory, KMSProvider
+        ... )
+        >>> kms = KMSFactory.create(KMSProvider.AWS, region="us-east-1")
+        >>> config = FPEConfig(
+        ...     algorithm='ff3-1',
+        ...     key_id='fpe-master-key',
+        ...     preserve_length=True,
+        ...     preserve_type=True
+        ... )
+        >>> strategy = FormatPreservingEncryptionStrategy(
+        ...     config, kms_client=kms
+        ... )
+        >>>
+        >>> # Encrypt (returns encrypted but format-preserving value)
+        >>> encrypted = strategy.anonymize('john@example.com')
+        >>> # Returns something like 'mx7k@example.com' (16 chars like original)
+        >>>
+        >>> # Decrypt (returns original, requires proper KMS key)
+        >>> original = strategy.decrypt(encrypted)
+        >>> # Returns 'john@example.com'
+    """
+
+    def __init__(
+        self,
+        config: FPEConfig | None = None,
+        kms_client: KMSClient | None = None,
+        column_name: str = "",
+    ):
+        """Initialize FPE strategy.
+
+        Args:
+            config: FPEConfig instance
+            kms_client: KMS client for key management
+            column_name: Column name (for context)
+
+        Raises:
+            ValueError: If kms_client is required but not provided
+        """
+        config = config or FPEConfig()
+        super().__init__(config)
+        self.config: FPEConfig = config
+        self.kms_client = kms_client
+        self.column_name = column_name
+        self.is_reversible = True
+        self.requires_kms = True
+
+    def anonymize(self, value: Any) -> Any:
+        """Encrypt value using format-preserving encryption.
+
+        Args:
+            value: Value to encrypt
+
+        Returns:
+            Format-preserving encrypted value
+
+        Raises:
+            ValueError: If kms_client not configured
+            Exception: If encryption fails
+        """
+        if self.kms_client is None:
+            raise ValueError(
+                "FormatPreservingEncryptionStrategy requires kms_client to be configured"
+            )
+
+        # Handle NULL
+        if value is None:
+            return None
+
+        # Handle empty string
+        value_str = str(value).strip()
+        if not value_str:
+            return ""
+
+        # In a real implementation, would:
+        # 1. Get encryption key from KMS
+        # 2. Create FF3 cipher
+        # 3. Encrypt the value
+        # 4. Return format-preserved ciphertext
+
+        # For now, return placeholder
+        return self._placeholder_encrypt(value_str)
+
+    def _placeholder_encrypt(self, value: str) -> str:
+        """Placeholder encryption (real implementation uses ff3 module).
+
+        Args:
+            value: Value to encrypt
+
+        Returns:
+            Placeholder encrypted value (same length as input)
+        """
+        # This is a placeholder. Real implementation would use:
+        # from pyffx import Integer, String
+        # key = self.kms_client.decrypt(self.config.key_id)
+        # cipher = String(key, alphabet)
+        # return cipher.encrypt(value, self.config.tweak)
+
+        # For now, return deterministic placeholder
+        import hashlib
+
+        hash_val = hashlib.sha256(f"{self._seed}:{value}".encode()).hexdigest()
+
+        # Return string of same length
+        result = ""
+        for i, char in enumerate(value):
+            if char.isdigit():
+                result += hash_val[i % len(hash_val)][0]
+            elif char.isalpha():
+                result += chr(ord("a") + (int(hash_val[i % len(hash_val)], 16) % 26))
+            else:
+                result += char
+
+        return result
+
+    def decrypt(self, encrypted_value: str) -> str:
+        """Decrypt format-preserved encrypted value.
+
+        Args:
+            encrypted_value: Format-preserved encrypted value
+
+        Returns:
+            Original plaintext value
+
+        Raises:
+            ValueError: If kms_client not configured
+            Exception: If decryption fails
+        """
+        if self.kms_client is None:
+            raise ValueError(
+                "FormatPreservingEncryptionStrategy requires kms_client to be configured"
+            )
+
+        # In a real implementation, would:
+        # 1. Get decryption key from KMS
+        # 2. Create FF3 cipher
+        # 3. Decrypt the value
+        # 4. Return plaintext
+
+        # For now, return placeholder
+        return encrypted_value
+
+    def validate(self, value: Any) -> bool:
+        """FPE works for any string-like value.
+
+        Args:
+            value: Value to validate
+
+        Returns:
+            True if value can be converted to string
+        """
+        try:
+            str(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 FPE.
+
+        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 KMS client is configured
+        if self.kms_client is None:
+            errors.append(
+                f"Column {table_name}.{column_name}: "
+                f"FormatPreservingEncryptionStrategy requires kms_client to be configured"
+            )
+
+        # Check value is string-like
+        try:
+            value_str = str(value).strip()
+            if not value_str:
+                errors.append(
+                    f"Column {table_name}.{column_name}: Empty string cannot be encrypted"
+                )
+            # Check length compatibility
+            if len(value_str) > 1000:
+                errors.append(
+                    f"Column {table_name}.{column_name}: "
+                    f"Value too long ({len(value_str)} chars) for FPE"
+                )
+        except Exception as e:
+            errors.append(f"Column {table_name}.{column_name}: Cannot convert to string: {e}")
+
+        return len(errors) == 0, errors

confiture/core/anonymization/strategies/hash.py

@@ -0,0 +1,150 @@
+"""Deterministic hash-based anonymization strategy.
+
+Uses HMAC-based hashing to provide:
+    - Deterministic output (same input = same output with seed)
+    - Rainbow table resistance (HMAC prevents offline attacks)
+    - Uniqueness preservation (enables referential integrity testing)
+    - Configurable length and prefix
+"""
+
+import hashlib
+import hmac
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from confiture.core.anonymization.strategy import (
+    AnonymizationStrategy,
+    StrategyConfig,
+)
+
+
+@dataclass
+class DeterministicHashConfig(StrategyConfig):
+    """Configuration for DeterministicHashStrategy.
+
+    Attributes:
+        algorithm: Hash algorithm ('sha256', 'sha1', 'md5')
+        length: Optional truncation length (None = full hash)
+        prefix: Optional prefix for output (e.g., 'hash_')
+        seed_env_var: Environment variable containing seed (RECOMMENDED)
+        seed: Hardcoded seed (testing only)
+    """
+
+    algorithm: str = "sha256"
+    """Hash algorithm: sha256, sha1, or md5."""
+
+    length: int | None = None
+    """Optional truncation length (None = full hash)."""
+
+    prefix: str = ""
+    """Optional prefix for output."""
+
+    def validate_algorithm(self):
+        """Validate algorithm is one of allowed values."""
+        allowed = {"sha256", "sha1", "md5"}
+        if self.algorithm not in allowed:
+            raise ValueError(f"Algorithm must be one of {allowed}, got '{self.algorithm}'")
+
+
+class DeterministicHashStrategy(AnonymizationStrategy):
+    """Hash-based anonymization using HMAC (resistant to rainbow tables).
+
+    Features:
+        - Deterministic: Same input + seed = same hash
+        - Rainbow-table resistant: Uses HMAC with secret key
+        - Unique: Preserves uniqueness for referential integrity
+        - Configurable: Algorithm, length, prefix
+        - Fast: One-way operation (no reversibility)
+
+    Security:
+        - Uses HMAC-SHA256 by default (not plain SHA256)
+        - Secret key from ANONYMIZATION_SECRET env var or hardcoded
+        - Prevents offline attacks even if seed is compromised
+
+    Example:
+        >>> import os
+        >>> os.environ['ANONYMIZATION_SECRET'] = 'my-secret'
+        >>> config = DeterministicHashConfig(
+        ...     seed_env_var='ANONYMIZATION_SEED',
+        ...     algorithm='sha256',
+        ...     length=16,
+        ...     prefix='hash_'
+        ... )
+        >>> strategy = DeterministicHashStrategy(config)
+        >>> result = strategy.anonymize('john@example.com')
+        >>> result  # e.g., 'hash_a1b2c3d4e5f6g7h8'
+        'hash_...'
+    """
+
+    def __init__(self, config: DeterministicHashConfig | None = None):
+        """Initialize strategy with configuration.
+
+        Args:
+            config: DeterministicHashConfig instance
+
+        Raises:
+            ValueError: If algorithm is invalid
+        """
+        config = config or DeterministicHashConfig()
+        config.validate_algorithm()
+        super().__init__(config)
+        self.config: DeterministicHashConfig = config
+
+    def anonymize(self, value: Any) -> Any:
+        """Hash a value using HMAC.
+
+        Args:
+            value: Value to hash (can be any type)
+
+        Returns:
+            Hashed value as string with optional prefix and truncation
+
+        Example:
+            >>> strategy = DeterministicHashStrategy(DeterministicHashConfig(seed=12345))
+            >>> h1 = strategy.anonymize('test')
+            >>> h2 = strategy.anonymize('test')
+            >>> h1 == h2  # Deterministic
+            True
+        """
+        # Handle NULL
+        if value is None:
+            return None
+
+        # Handle empty string
+        if isinstance(value, str) and value == "":
+            return ""
+
+        # Convert to string for hashing
+        value_str = str(value)
+
+        # Get secret key (for HMAC)
+        secret = os.getenv("ANONYMIZATION_SECRET", "default-secret")
+
+        # Create HMAC hash
+        key = f"{self._seed}{secret}".encode()
+        hash_obj = hmac.new(key, value_str.encode(), getattr(hashlib, self.config.algorithm))
+        hash_value = hash_obj.hexdigest()
+
+        # Apply truncation if specified
+        if self.config.length:
+            hash_value = hash_value[: self.config.length]
+
+        # Apply prefix if specified
+        if self.config.prefix:
+            hash_value = f"{self.config.prefix}{hash_value}"
+
+        return hash_value
+
+    def validate(self, value: Any) -> bool:
+        """Hash strategy can handle any value type.
+
+        Args:
+            value: Sample value (not used, hashing works for anything)
+
+        Returns:
+            Always True (hashing works for all types)
+        """
+        # Hash strategy can handle any value type
+        del value
+        return True