fraiseql-confiture 0.3.7__cp311-cp311-macosx_11_0_arm64.whl

confiture/scenarios/healthcare.py

@@ -0,0 +1,315 @@
+"""Healthcare PHI (Protected Health Information) anonymization scenario.
+
+Real-world use case: Compliant anonymization for research across multiple regions.
+
+Supports multiple data protection regulations:
+- HIPAA (USA) - Safe Harbor rules for de-identification
+- GDPR (EU/EEA) - General Data Protection Regulation
+- PIPEDA (Canada) - Personal Information Protection Act
+- LGPD (Brazil) - Lei Geral de Proteção de Dados
+- PIPL (China) - Personal Information Protection Law
+- Privacy Act (Australia) - Privacy Act 1988
+- POPIA (South Africa) - Protection of Personal Information Act
+
+Data Types (PHI - Protected Health Information):
+- Patient names (PII)
+- Social security numbers / Tax IDs (SSN)
+- Dates of birth (sensitive)
+- Medical record numbers (identifiers)
+- Diagnosis codes (sensitive)
+- Medication information (sensitive)
+- Provider names (PII)
+- Facility names (may be identifying)
+- Visit dates (sensitive)
+- Vital signs (may need masking)
+- Test results (sensitive)
+
+Strategy:
+- Names: Complete masking
+- SSN/Tax IDs: Pattern redaction
+- Birth dates: Year masking
+- Medical record numbers: Hash-based replacement
+- Diagnoses: Preserve ICD codes
+- Medications: Preserve as-is
+- Dates: Preserve year only
+- IP addresses: Complete masking
+- Facilities: Preserve facility ID but mask name
+"""
+
+from confiture.core.anonymization.factory import StrategyFactory, StrategyProfile
+from confiture.scenarios.compliance import (
+    ComplianceVerifier,
+    RegulationType,
+)
+
+
+class HealthcareScenario:
+    """Healthcare PHI anonymization scenario supporting multiple regulations.
+
+    Demonstrates anonymization for research across different regions with
+    compliance verification for various data protection regulations.
+
+    Example (Default - HIPAA):
+        >>> scenario = HealthcareScenario()
+        >>> data = {
+        ...     "patient_id": "PAT-00123",
+        ...     "patient_name": "John Smith",
+        ...     "ssn": "123-45-6789",
+        ...     "date_of_birth": "1965-03-12",
+        ...     "medical_record_number": "MRN-999888",
+        ...     "diagnosis": "E11",  # Type 2 diabetes
+        ...     "medication": "Metformin 500mg",
+        ...     "visit_date": "2024-12-15",
+        ...     "provider_name": "Dr. Sarah Johnson",
+        ...     "facility_name": "St. Mary's Hospital",
+        ... }
+        >>> anonymized = scenario.anonymize(data)
+        >>> # PHI masked, clinical data preserved
+
+    Example (GDPR):
+        >>> anonymized = scenario.anonymize(data, regulation=RegulationType.GDPR)
+        >>> compliant = scenario.verify_compliance(data, anonymized, RegulationType.GDPR)
+    """
+
+    # Default seed for reproducibility
+    DEFAULT_SEED = 42
+
+    @staticmethod
+    def get_profile(regulation: RegulationType = RegulationType.GDPR) -> StrategyProfile:
+        """Get healthcare anonymization profile for specified regulation.
+
+        Args:
+            regulation: Target data protection regulation. Defaults to GDPR.
+
+        Returns:
+            StrategyProfile configured for healthcare PHI anonymization.
+
+        Strategy Mapping (applies to all regulations):
+            - patient_id: preserve (study identifier)
+            - patient_name: name masking (complete)
+            - ssn: text redaction (SSN pattern)
+            - date_of_birth: date masking (year conversion to safe range)
+            - medical_record_number: custom hash
+            - diagnosis: preserve (ICD code)
+            - medication: preserve (clinical)
+            - visit_date: date masking (year only)
+            - provider_name: name masking
+            - facility_name: name masking
+            - vital signs: preserve (clinical)
+            - test results: preserve (clinical)
+        """
+        profile_name = f"healthcare_{regulation.value}"
+        return StrategyProfile(
+            name=profile_name,
+            seed=HealthcareScenario.DEFAULT_SEED,  # Fixed seed for reproducibility
+            columns={
+                # Study/research identifiers - preserve
+                "patient_id": "preserve",
+                "study_id": "preserve",
+                "record_id": "preserve",
+                # PII - mask completely
+                "patient_name": "name",
+                "first_name": "name",
+                "last_name": "name",
+                "provider_name": "name",
+                "provider_first": "name",
+                "provider_last": "name",
+                # Identifiers - redact/mask
+                "ssn": "text_redaction",
+                "social_security_number": "text_redaction",
+                "medical_record_number": "text_redaction",
+                "mrn": "text_redaction",
+                # Contact - redact
+                "email": "text_redaction",
+                "phone": "text_redaction",
+                "phone_number": "text_redaction",
+                "address": "address",
+                # Sensitive dates - mask to year only
+                "date_of_birth": "date",
+                "birth_date": "date",
+                "dob": "date",
+                "admission_date": "date",
+                "discharge_date": "date",
+                "visit_date": "date",
+                "appointment_date": "date",
+                "procedure_date": "date",
+                "test_date": "date",
+                # Clinical data - preserve
+                "diagnosis": "preserve",
+                "diagnosis_code": "preserve",
+                "icd_code": "preserve",
+                "procedure": "preserve",
+                "procedure_code": "preserve",
+                "medication": "preserve",
+                "drug_name": "preserve",
+                "dosage": "preserve",
+                "route": "preserve",
+                "frequency": "preserve",
+                # Vital signs - preserve
+                "temperature": "preserve",
+                "heart_rate": "preserve",
+                "blood_pressure": "preserve",
+                "respiratory_rate": "preserve",
+                "oxygen_saturation": "preserve",
+                "weight": "preserve",
+                "height": "preserve",
+                "bmi": "preserve",
+                # Lab results - preserve
+                "test_name": "preserve",
+                "test_value": "preserve",
+                "test_result": "preserve",
+                "lab_result": "preserve",
+                "reference_range": "preserve",
+                # Facility - preserve facility ID but mask name
+                "facility_id": "preserve",
+                "facility_name": "name",
+                "facility_code": "preserve",
+                "department": "preserve",
+                "ward": "preserve",
+                # Location - generalize
+                "city": "preserve",
+                "state": "preserve",
+                "country": "preserve",
+                # Metadata - preserve
+                "encounter_type": "preserve",
+                "admission_type": "preserve",
+                "discharge_disposition": "preserve",
+                "status": "preserve",
+                # IP/technical - mask
+                "ip_address": "ip_address",
+                "device_id": "preserve",
+            },
+            defaults="preserve",
+        )
+
+    @classmethod
+    def create_factory(cls, regulation: RegulationType = RegulationType.GDPR) -> StrategyFactory:
+        """Create factory for healthcare anonymization.
+
+        Args:
+            regulation: Target data protection regulation. Defaults to GDPR.
+
+        Returns:
+            Configured StrategyFactory for healthcare PHI.
+        """
+        profile = cls.get_profile(regulation)
+        return StrategyFactory(profile)
+
+    @classmethod
+    def anonymize(cls, data: dict, regulation: RegulationType = RegulationType.GDPR) -> dict:
+        """Anonymize healthcare PHI data according to specified regulation.
+
+        Args:
+            data: Patient/encounter data dictionary.
+            regulation: Target data protection regulation. Defaults to GDPR.
+
+        Returns:
+            Compliant anonymized data with PHI masked.
+
+        Example:
+            >>> data = {
+            ...     "patient_id": "PAT-00123",
+            ...     "patient_name": "John Smith",
+            ...     "ssn": "123-45-6789",
+            ...     "diagnosis": "E11",
+            ...     "medication": "Metformin 500mg",
+            ... }
+            >>> result = HealthcareScenario.anonymize(data)
+            >>> result["patient_id"]  # Preserved
+            'PAT-00123'
+            >>> result["patient_name"]  # Anonymized
+            'Michael Johnson'
+            >>> result["ssn"]  # Redacted
+            '[REDACTED]'
+            >>> result["diagnosis"]  # Preserved
+            'E11'
+
+            >>> # Use different regulation
+            >>> result_ccpa = HealthcareScenario.anonymize(data, RegulationType.CCPA)
+        """
+        factory = cls.create_factory(regulation)
+        return factory.anonymize(data)
+
+    @classmethod
+    def anonymize_batch(
+        cls, data_list: list[dict], regulation: RegulationType = RegulationType.GDPR
+    ) -> list[dict]:
+        """Anonymize batch of healthcare records.
+
+        Args:
+            data_list: List of patient/encounter records.
+            regulation: Target data protection regulation. Defaults to GDPR.
+
+        Returns:
+            List of compliant anonymized records.
+        """
+        factory = cls.create_factory(regulation)
+        return [factory.anonymize(record) for record in data_list]
+
+    @classmethod
+    def get_strategy_info(cls) -> dict:
+        """Get information about strategies used.
+
+        Returns:
+            Dictionary mapping column names to strategy names.
+        """
+        profile = cls.get_profile()
+        factory = StrategyFactory(profile)
+        return factory.list_column_strategies()
+
+    @classmethod
+    def verify_compliance(
+        cls, original: dict, anonymized: dict, regulation: RegulationType = RegulationType.GDPR
+    ) -> dict:
+        """Verify compliance of anonymized data with specified regulation.
+
+        Checks that sensitive fields have been properly masked according to
+        the regulation's requirements.
+
+        Args:
+            original: Original data before anonymization.
+            anonymized: Anonymized data.
+            regulation: Target data protection regulation. Defaults to GDPR.
+
+        Returns:
+            Dictionary with compliance verification results including:
+            - compliant: Boolean indicating compliance status
+            - regulation: Name of regulation checked
+            - masked_fields: List of fields that were anonymized
+            - preserved_fields: List of fields that were preserved
+            - issues: List of compliance issues if any
+            - masked_count: Number of masked fields
+            - preserved_count: Number of preserved fields
+
+        Example:
+            >>> data = {
+            ...     "patient_id": "PAT-123",
+            ...     "patient_name": "John Smith",
+            ...     "ssn": "123-45-6789",
+            ... }
+            >>> anon = HealthcareScenario.anonymize(data, RegulationType.GDPR)
+            >>> result = HealthcareScenario.verify_compliance(data, anon, RegulationType.GDPR)
+            >>> print(result["compliant"])
+            True
+        """
+        verifier = ComplianceVerifier(regulation)
+        return verifier.verify_anonymization(original, anonymized)
+
+    @classmethod
+    def get_compliance_requirements(cls, regulation: RegulationType = RegulationType.GDPR) -> dict:
+        """Get compliance requirements for specified regulation.
+
+        Args:
+            regulation: Target data protection regulation. Defaults to GDPR.
+
+        Returns:
+            Dictionary with regulation requirements including applicable
+            data categories and consent requirements.
+
+        Example:
+            >>> reqs = HealthcareScenario.get_compliance_requirements(RegulationType.GDPR)
+            >>> print(reqs["total_categories"])  # Number of applicable categories
+            15
+        """
+        verifier = ComplianceVerifier(regulation)
+        return verifier.get_requirements()

confiture/scenarios/multi_tenant.py

@@ -0,0 +1,340 @@
+"""Multi-tenant data isolation and anonymization scenario.
+
+Real-world use case: Anonymizing tenant data while ensuring data isolation across
+customers in multi-tenant systems.
+
+Data Types:
+- Tenant identifiers (preserve for data isolation)
+- Tenant names (sensitive - may be identifying)
+- User names (PII)
+- Email addresses (PII)
+- Organization information (sensitive)
+- Tenant-specific data (anonymize per tenant config)
+- Cross-tenant shared data (preserve for auditing)
+
+Architecture:
+- Each tenant has isolated data
+- Global seed by tenant ensures consistent hashing across tables
+- Tenant metadata preserved for data isolation
+- Customer names and PII masked
+- Business metrics preserved
+
+Strategy:
+- Tenant identifiers: Preserve (data isolation key)
+- Tenant names: Mask with initials
+- User data: Per-tenant anonymization
+- Cross-cutting data: Preserve for auditing
+- Relationships: Maintain via deterministic hashing
+"""
+
+from confiture.core.anonymization.factory import StrategyFactory, StrategyProfile
+
+
+class MultiTenantScenario:
+    """Multi-tenant data anonymization scenario.
+
+    Demonstrates anonymizing multi-tenant data while maintaining data isolation
+    and cross-table consistency through deterministic seeding.
+
+    Example:
+        >>> scenario = MultiTenantScenario()
+        >>> tenant_a_data = {
+        ...     "tenant_id": "TENANT-A",
+        ...     "user_id": "USER-001",
+        ...     "user_name": "john.smith",
+        ...     "text_redaction": "john@companya.com",
+        ...     "organization": "Company A",
+        ...     "department": "Engineering",
+        ... }
+        >>> tenant_b_data = {
+        ...     "tenant_id": "TENANT-B",
+        ...     "user_id": "USER-001",  # Same user ID, different tenant
+        ...     "user_name": "jane.doe",
+        ...     "text_redaction": "jane@companyb.com",
+        ...     "organization": "Company B",
+        ...     "department": "Sales",
+        ... }
+        >>> anon_a = scenario.anonymize(tenant_a_data)
+        >>> anon_b = scenario.anonymize(tenant_b_data)
+        >>> # Tenant IDs preserved, user data anonymized differently per tenant
+    """
+
+    @staticmethod
+    def get_profile(tenant_id: str) -> StrategyProfile:
+        """Get multi-tenant anonymization profile.
+
+        Uses tenant ID to create deterministic seed for cross-table consistency
+        within tenant boundaries.
+
+        Args:
+            tenant_id: Tenant identifier for seed generation.
+
+        Returns:
+            StrategyProfile configured for multi-tenant data with tenant-specific seed.
+
+        Strategy Mapping:
+            - tenant_id: preserve (data isolation key)
+            - user_id: preserve (tenant-scoped identifier)
+            - user_name: anonymize
+            - email: redact
+            - organization_name: mask
+            - department: preserve (business metadata)
+            - created_by: anonymize
+            - updated_by: anonymize
+            - tenant_metadata: preserve (for auditing)
+            - business_metrics: preserve (for analytics)
+        """
+        # Create deterministic seed from tenant ID
+        # This ensures same seed for all records in same tenant
+        tenant_seed = hash(tenant_id) & 0x7FFFFFFF  # Positive integer
+
+        return StrategyProfile(
+            name=f"multi_tenant_{tenant_id}",
+            seed=tenant_seed,  # Tenant-specific seed
+            columns={
+                # Tenant identifiers - preserve for data isolation
+                "tenant_id": "preserve",
+                "tenant_uuid": "preserve",
+                "account_id": "preserve",
+                "workspace_id": "preserve",
+                "client_id": "preserve",
+                "customer_id": "preserve",
+                # User identifiers - preserve (tenant-scoped)
+                "user_id": "preserve",
+                "user_uuid": "preserve",
+                "employee_id": "preserve",
+                "member_id": "preserve",
+                # User PII - anonymize
+                "user_name": "text_redaction",
+                "username": "text_redaction",
+                "first_name": "name",
+                "last_name": "name",
+                "full_name": "name",
+                "display_name": "name",
+                "email": "text_redaction",
+                "phone": "text_redaction",
+                "phone_number": "text_redaction",
+                # Organization/Tenant info - mask names
+                "organization_name": "name",
+                "tenant_name": "name",
+                "company_name": "name",
+                "department": "preserve",  # Business metadata
+                "team": "preserve",
+                "division": "preserve",
+                # Address - mask
+                "address": "address",
+                "city": "preserve",
+                "state": "preserve",
+                "country": "preserve",
+                # Relationships - anonymize names but preserve IDs
+                "created_by": "text_redaction",
+                "created_by_user_id": "preserve",
+                "updated_by": "text_redaction",
+                "updated_by_user_id": "preserve",
+                "assigned_to": "text_redaction",
+                "assigned_to_user_id": "preserve",
+                "manager": "text_redaction",
+                "manager_id": "preserve",
+                # Tenant metadata - preserve
+                "tenant_type": "preserve",
+                "tenant_status": "preserve",
+                "tenant_tier": "preserve",
+                "industry": "preserve",
+                "region": "preserve",
+                "timezone": "preserve",
+                # Business metrics - preserve
+                "active_users": "preserve",
+                "total_users": "preserve",
+                "data_storage": "preserve",
+                "api_quota": "preserve",
+                "monthly_cost": "preserve",
+                "annual_contract_value": "preserve",
+                # Dates - preserve for audit trail
+                "created_at": "preserve",
+                "updated_at": "preserve",
+                "deleted_at": "preserve",
+                "last_login": "date",
+                "contract_start": "preserve",
+                "contract_end": "preserve",
+                "billing_cycle": "preserve",
+                # Content/Data - preserve
+                "description": "preserve",
+                "notes": "preserve",
+                "tags": "preserve",
+                "status": "preserve",
+                "data_classification": "preserve",
+                # IP/Technical - mask
+                "ip_address": "ip_address",
+                "device_id": "preserve",
+                "browser": "preserve",
+                # Audit fields
+                "change_log": "preserve",
+                "audit_trail": "preserve",
+            },
+            defaults="preserve",
+        )
+
+    @classmethod
+    def create_factory(cls, tenant_id: str) -> StrategyFactory:
+        """Create tenant-specific factory for anonymization.
+
+        Args:
+            tenant_id: Tenant identifier for isolation.
+
+        Returns:
+            Configured StrategyFactory for the tenant.
+        """
+        profile = cls.get_profile(tenant_id)
+        return StrategyFactory(profile)
+
+    @classmethod
+    def anonymize(cls, data: dict) -> dict:
+        """Anonymize multi-tenant data.
+
+        Extracts tenant ID from data and uses tenant-specific seed for
+        deterministic anonymization within tenant boundaries.
+
+        Args:
+            data: Record containing tenant_id and other fields.
+
+        Returns:
+            Anonymized data with PII masked and tenant isolation maintained.
+
+        Raises:
+            ValueError: If tenant_id not in data.
+
+        Example:
+            >>> data = {
+            ...     "tenant_id": "TENANT-A",
+            ...     "user_id": "USER-001",
+            ...     "text_redaction": "john@example.com",
+            ...     "organization_name": "Company A",
+            ... }
+            >>> result = MultiTenantScenario.anonymize(data)
+            >>> result["tenant_id"]  # Preserved
+            'TENANT-A'
+            >>> result["text_redaction"]  # Redacted
+            '[EMAIL]'
+            >>> result["organization_name"]  # Masked
+            'CA'
+        """
+        if "tenant_id" not in data:
+            raise ValueError("Data must contain 'tenant_id' field for multi-tenant anonymization")
+
+        tenant_id = data["tenant_id"]
+        factory = cls.create_factory(tenant_id)
+        return factory.anonymize(data)
+
+    @classmethod
+    def anonymize_batch(cls, data_list: list[dict]) -> list[dict]:
+        """Anonymize batch of multi-tenant records.
+
+        Creates per-tenant factories to maintain data isolation while
+        anonymizing deterministically within each tenant.
+
+        Args:
+            data_list: List of records from potentially multiple tenants.
+
+        Returns:
+            List of anonymized records maintaining tenant isolation.
+
+        Example:
+            >>> data = [
+            ...     {"tenant_id": "TENANT-A", "user_id": "U1", ...},
+            ...     {"tenant_id": "TENANT-A", "user_id": "U2", ...},
+            ...     {"tenant_id": "TENANT-B", "user_id": "U1", ...},
+            ... ]
+            >>> results = MultiTenantScenario.anonymize_batch(data)
+            >>> # TENANT-A records use TENANT-A seed, TENANT-B uses TENANT-B seed
+        """
+        results = []
+        factories_cache = {}
+
+        for record in data_list:
+            tenant_id = record.get("tenant_id")
+            if not tenant_id:
+                raise ValueError("All records must contain 'tenant_id' field")
+
+            # Cache factories by tenant to avoid recreating
+            if tenant_id not in factories_cache:
+                factories_cache[tenant_id] = cls.create_factory(tenant_id)
+
+            factory = factories_cache[tenant_id]
+            results.append(factory.anonymize(record))
+
+        return results
+
+    @classmethod
+    def get_strategy_info(cls, tenant_id: str) -> dict:
+        """Get strategies for specific tenant.
+
+        Args:
+            tenant_id: Tenant identifier.
+
+        Returns:
+            Dictionary mapping columns to strategy names for tenant.
+        """
+        profile = cls.get_profile(tenant_id)
+        factory = StrategyFactory(profile)
+        return factory.list_column_strategies()
+
+    @classmethod
+    def verify_data_isolation(cls, data_list: list[dict], original_list: list[dict]) -> dict:
+        """Verify data isolation across tenants.
+
+        Checks that same user IDs in different tenants produce different
+        anonymized results due to tenant-specific seeding.
+
+        Args:
+            data_list: Anonymized records.
+            original_list: Original records.
+
+        Returns:
+            Dictionary with isolation verification results.
+        """
+        results = {
+            "isolated": True,
+            "issues": [],
+            "cross_tenant_checks": [],
+        }
+
+        # Group by tenant
+        by_tenant = {}
+        for record in data_list:
+            tenant = record.get("tenant_id", "UNKNOWN")
+            if tenant not in by_tenant:
+                by_tenant[tenant] = []
+            by_tenant[tenant].append(record)
+
+        # Check isolation: same user_id in different tenants should have different PII
+        user_by_tenant = {}
+        for i, record in enumerate(original_list):
+            tenant = record.get("tenant_id")
+            user_id = record.get("user_id")
+            key = (user_id,)
+
+            if key not in user_by_tenant:
+                user_by_tenant[key] = {}
+
+            user_by_tenant[key][tenant] = {
+                "original": record,
+                "anonymized": data_list[i],
+            }
+
+        # Verify same user in different tenants has different anonymizations
+        for (user_id,), tenants_data in user_by_tenant.items():
+            if len(tenants_data) > 1:
+                anon_values = [
+                    tenants_data[t]["anonymized"].get("text_redaction") for t in tenants_data
+                ]
+                if len(set(anon_values)) != len(anon_values):
+                    results["isolated"] = False
+                    results["issues"].append(
+                        f"User {user_id} has same anonymization in different tenants"
+                    )
+                else:
+                    results["cross_tenant_checks"].append(
+                        f"User {user_id}: ✓ Properly isolated across {len(tenants_data)} tenants"
+                    )
+
+        return results