HIPAA Compliance Coding Guidelines

1. Overview

HIPAA (Health Insurance Portability and Accountability Act) applies to Covered Entities (healthcare providers, health plans, healthcare clearinghouses) and Business Associates (any entity that creates, receives, maintains, or transmits PHI on behalf of a Covered Entity). Three rules: the Privacy Rule (who can access PHI), the Security Rule (technical/admin/physical safeguards for ePHI), and the Breach Notification Rule (requirements when unsecured PHI is compromised). Penalties: $137-$68,928 per violation, annual caps of $2,067,813 per violation category, criminal penalties up to $250,000 and 10 years imprisonment.

2. What is PHI (Protected Health Information)?

PHI is individually identifiable health information relating to health condition, healthcare provision, or payment that identifies or could identify the individual. ePHI = PHI in electronic form (databases, APIs, files, logs, backups) — the developer’s primary concern.

Critical distinction: Health data alone is NOT PHI. A blood pressure of 140/90 is not PHI. A blood pressure of 140/90 linked to patient John Smith, DOB 1985-03-15, IS PHI. PHI exists only when health data is linked to identifiers.

The 18 HIPAA Identifiers

3. The Three Rules (Developer View)

4. Technical Safeguards (45 CFR 164.312) — The Developer Core

Full code examples: resources/technical-safeguards.md

5. Administrative Safeguards for Developers (45 CFR 164.308)

Full code examples: resources/technical-safeguards.md

• Risk Analysis (164.308(a)(1)) — Map every location where ePHI lives: database tables, file storage, cache layers, message queues, log files, backups, third-party services, temporary files.
• Access Management (164.308(a)(4)) — RBAC with minimum necessary. Define granular per-role permission maps (e.g., receptionist: read:demographics only; physician: full clinical access; billing: billing fields only; researcher: de-identified only).
• Incident Response (164.308(a)(6)) — Anomaly detection: alert when a user’s access count exceeds 3x their baseline in a 1-hour window.
• Contingency Plan (164.308(a)(7)) — Encrypted backups with SHA-256 checksum verification. Log all backup operations. Test restore procedures regularly.

6. De-identification (Safe Harbor Method)

Full code examples: resources/deidentification.md

Remove all 18 identifiers per 45 CFR 164.514(b). De-identified data is NOT PHI. Key techniques:

• SQL views that replace identifiers with research IDs (MD5 hash with separate salt), truncate ZIP to 3 digits (000 if population < 20K), keep only year from dates, cap age at 90
• PHI detection patterns — regex scanning for SSN, phone, email, MRN, dates, IPs before logging or exporting
• Date shifting — deterministic per-patient offset (-365 to +365 days) preserving relative intervals
• Complete de-identification — strip all 18 identifiers, keep clinical data (diagnoses, procedures, labs, medications)

7. Minimum Necessary Rule

Full code examples: resources/deidentification.md

Query only needed fields. No SELECT * on PHI tables. Return only fields required for the user’s role.

• Billing staff see only: id, insurance_provider, policy_number, billing_code
• Nurses see only: id, name, dob, vitals (blood_pressure, heart_rate, temperature)
• Physicians see: id, name, dob, vitals, diagnoses, lab results
• Receptionists see only: id, name, phone, appointment date

Filter responses server-side based on role before returning to client. Use ORM scopes to enforce column restrictions at the query level.

8. BAA (Business Associate Agreement) Requirements

A BAA is required whenever a third party creates, receives, maintains, or transmits PHI on your behalf. Using a service without a BAA to process PHI is a violation regardless of breach.

Important: Scrub PHI from error tracking payloads before sending to any service. Redact request data, strip local variables from stack frames.

9. Mobile and API Considerations

• No PHI in push notifications — visible on lock screen. Use generic messages (“You have a new message from your care team”) and require auth before displaying PHI content.
• No PHI in client-side storage without encryption — never use localStorage/sessionStorage for PHI. Store reference IDs only; fetch PHI on demand with auth.
• No PHI in URLs — use POST with body. PHI in URLs leaks to browser history, server logs, Referer headers.
• Rate limiting on PHI endpoints to detect bulk extraction (e.g., 60 reads/min, 5 exports/hour).

10. Breach Response Coding Patterns

Full code examples: resources/breach-response.md

• Detection — Monitor for: bulk access (>100 records), off-hours access, new IP addresses. Log all breach indicators. Auto-alert security team on high-severity indicators.
• Containment — Immediately: revoke all sessions, revoke all tokens, lock user account, snapshot audit logs. Log all containment actions.
• Breach Log — Track: detection time, detector, breach type, severity, affected record count/type, containment actions, notification status (HHS within 60 days, individuals, media if 500+ records), resolution.

11. Common Mistakes

12. Quick Reference

DO

• Encrypt ePHI at rest (AES-256) and in transit (TLS 1.2+)
• Assign unique user IDs to every person/system accessing ePHI
• Implement MFA for ePHI access
• Log every ePHI access: who, what, when, where, outcome
• Enforce automatic session timeout (15 minutes or less)
• Use POST for PHI data; never put PHI in URLs
• Apply RBAC with minimum necessary field filtering
• Sign BAAs with every third-party service handling PHI
• Encrypt all backups containing ePHI
• Strip EXIF metadata from medical images
• Implement “break glass” emergency access with audit trail
• Retain audit logs for 6+ years
• Map all ePHI locations via risk analysis
• De-identify using Safe Harbor (remove all 18 identifiers) for research
• Rate-limit PHI endpoints to detect bulk extraction
• Implement HMAC integrity checks on ePHI records
• Build breach detection and containment capabilities
• Send generic push notifications; require auth before showing PHI

DON’T

• Don’t log PHI content in application/error/debug logs
• Don’t put PHI in URLs, query parameters, or fragments
• Don’t use SELECT * on tables containing PHI
• Don’t use shared accounts for ePHI access
• Don’t send PHI through services lacking a signed BAA
• Don’t store PHI in localStorage/sessionStorage/cookies unencrypted
• Don’t include PHI in push notifications or email subject lines
• Don’t send PHI in analytics events or tracking pixels
• Don’t transmit PHI over plain HTTP
• Don’t return PHI in error messages or stack traces
• Don’t skip audit logging for any ePHI operation
• Don’t store unencrypted backups of ePHI
• Don’t cache PHI in unprotected layers (CDN, browser cache, shared Redis)
• Don’t use SMS for PHI transmission (not end-to-end encrypted)
• Don’t retain PHI longer than necessary; enforce data retention policies

Resources

• Technical Safeguards Code Examples — Access control, audit logging, integrity checks, authentication, transmission security, admin safeguard implementations
• De-identification Code Examples — Safe Harbor SQL views, PHI detection regex, date shifting, complete de-identification function, minimum necessary role-scoped queries
• Breach Response Code Examples — Detection patterns, containment procedures, breach log schema, notification tracking