EP-050: HIPAA Compliance Overview

Summary

EP-050 adds HIPAA (Health Insurance Portability and Accountability Act) compliance controls to the Experimentation Platform. The implementation covers the four primary HIPAA technical safeguard requirements: access controls, audit controls, integrity, and transmission security.

Components

1. PHI Encryption (backend/app/core/phi_encryption.py)

Symmetric encryption for Protected Health Information (PHI) using Fernet (AES-128-CBC + HMAC-SHA256).

Key generation:

from backend.app.core.phi_encryption import PHIEncryption
key = PHIEncryption.generate_key()  # Store this in AWS Secrets Manager

Usage:

enc = PHIEncryption()  # Reads key from settings.PHI_ENCRYPTION_KEY
ciphertext = enc.encrypt("John Smith DOB 1990-01-01")
plaintext  = enc.decrypt(ciphertext)

Properties:

• Each encrypt() call uses a random IV — same plaintext produces different ciphertexts
• HMAC authentication prevents tampered ciphertext from decrypting
• decrypt() raises ValueError on any integrity failure

2. PHI Audit Log (backend/app/models/phi_audit_log.py)

Every PHI access is recorded in experimentation.phi_audit_logs with:

• Who accessed (user_id FK to users)
• What was accessed (resource_type, resource_id)
• What action (READ / WRITE / DELETE / EXPORT)
• Which fields (phi_fields_accessed — HIPAA minimum-necessary principle)
• Why (purpose: treatment / operations / research)
• Network context (ip_address, user_agent)
• Retention marker (retention_years = 6, per HIPAA §164.530(j))

3. BAA Configuration (backend/app/models/baa_config.py)

Business Associate Agreements are tracked in experimentation.baa_configs. Each record stores:

• Covered entity contact (organization_name, signatory_name, signatory_email)
• Agreement period (effective_date, expiry_date)
• Data residency region (e.g., us-east-1)
• PHI categories covered (demographics, diagnosis, treatment, billing)
• Document integrity hash (SHA-256 of signed BAA document)

4. HIPAA Service (backend/app/services/hipaa_service.py)

Central business logic layer:

5. API Endpoints (backend/app/api/v1/endpoints/hipaa.py)

All endpoints at /api/v1/hipaa require ADMIN role (except /encrypt which also allows DEVELOPER).

Configuration

Add these settings to your environment or AWS Secrets Manager:

# Required for PHI encryption
PHI_ENCRYPTION_KEY=<generate with PHIEncryption.generate_key()>

# Enable HIPAA mode
HIPAA_ENABLED=true

# Restrict to HIPAA-compliant AWS regions
HIPAA_ALLOWED_REGIONS=["us-east-1","us-west-2"]

# Audit log retention (HIPAA requires 6 years)
HIPAA_AUDIT_LOG_RETENTION_YEARS=6

HIPAA Readiness Checklist

Use GET /api/v1/hipaa/status to verify all controls are in place:

{
  "has_active_baa": true,
  "phi_encryption_configured": true,
  "audit_logging_enabled": true,
  "data_residency_configured": true,
  "overall_hipaa_ready": true
}

Database Migration

The migration file is at: backend/app/db/migrations/versions/ep050_hipaa.py

It creates two tables:

• experimentation.phi_audit_logs
• experimentation.baa_configs

Do not run the migration until:

1. A valid PHI_ENCRYPTION_KEY is in secrets management
2. A signed BAA has been obtained from each covered entity
3. Data residency has been confirmed for all PHI-processing regions

Test Coverage

Security Notes

• PHI encryption keys must be rotated periodically (Fernet supports key versioning via MultiFernet)
• Audit logs are append-only — no DELETE endpoint is exposed
• Decryption operations are automatically audit-logged
• BAA deactivation is a soft delete — records are preserved for audit history
• The signed_document_hash field (SHA-256) provides integrity verification for BAA documents