Hipaa compliance

HIPAA Compliance

Use this as the HIPAA-specific entrypoint when a task is clearly about US healthcare compliance. This skill intentionally stays thin and canonical:

• healthcare-phi-compliance remains the primary implementation skill for PHI/PII handling, data classification, audit logging, encryption, and leak prevention.
• healthcare-reviewer remains the specialized reviewer when code, architecture, or product behavior needs a healthcare-aware second pass.
• security-review still applies for general auth, input-handling, secrets, API, and deployment hardening.

When to Use

• The request explicitly mentions HIPAA, PHI, covered entities, business associates, or BAAs
• Building or reviewing US healthcare software that stores, processes, exports, or transmits PHI
• Assessing whether logging, analytics, LLM prompts, storage, or support workflows create HIPAA exposure
• Designing patient-facing or clinician-facing systems where minimum necessary access and auditability matter

How It Works

Treat HIPAA as an overlay on top of the broader healthcare privacy skill:

1. Start with healthcare-phi-compliance for the concrete implementation rules.
2. Apply HIPAA-specific decision gates:
   • Is this data PHI?
   • Is this actor a covered entity or business associate?
   • Does a vendor or model provider require a BAA before touching the data?
   • Is access limited to the minimum necessary scope?
   • Are read/write/export events auditable?
3. Escalate to healthcare-reviewer if the task affects patient safety, clinical workflows, or regulated production architecture.

HIPAA-Specific Guardrails

• Never place PHI in logs, analytics events, crash reports, prompts, or client-visible error strings.
• Never expose PHI in URLs, browser storage, screenshots, or copied example payloads.
• Require authenticated access, scoped authorization, and audit trails for PHI reads and writes.
• Treat third-party SaaS, observability, support tooling, and LLM providers as blocked-by-default until BAA status and data boundaries are clear.
• Follow minimum necessary access: the right user should only see the smallest PHI slice needed for the task.
• Prefer opaque internal IDs over names, MRNs, phone numbers, addresses, or other identifiers.

Examples

Example 1: Product request framed as HIPAA

User request:

Add AI-generated visit summaries to our clinician dashboard. We serve US clinics and need to stay HIPAA compliant.

Response pattern:

• Activate hipaa-compliance
• Use healthcare-phi-compliance to review PHI movement, logging, storage, and prompt boundaries
• Verify whether the summarization provider is covered by a BAA before any PHI is sent
• Escalate to healthcare-reviewer if the summaries influence clinical decisions

Example 2: Vendor/tooling decision

User request:

Can we send support transcripts and patient messages into our analytics stack?

Response pattern:

• Assume those messages may contain PHI
• Block the design unless the analytics vendor is approved for HIPAA-bound workloads and the data path is minimized
• Require redaction or a non-PHI event model when possible

Related Skills

• healthcare-phi-compliance
• healthcare-reviewer
• healthcare-emr-patterns
• healthcare-eval-FRM
• security-review

---

PHI Handling Patterns

Healthcare PHI/PII Compliance Patterns

Patterns for protecting patient data, clinician data, and financial data in healthcare applications. Applicable to HIPAA (US), DISHA (India), GDPR (EU), and general healthcare data protection.

When to Use

• Building any feature that touches patient records
• Implementing access control or authentication for clinical systems
• Designing database schemas for healthcare data
• Building APIs that return patient or clinician data
• Implementing audit trails or logging
• Reviewing code for data exposure vulnerabilities
• Setting up Row-Level Security (RLS) for multi-tenant healthcare systems

How It Works

Healthcare data protection operates on three layers: classification (what is sensitive), access control (who can see it), and audit (who did see it).

Data Classification

PHI (Protected Health Information) — any data that can identify a patient AND relates to their health: patient name, date of birth, address, phone, email, national ID numbers (SSN, Aadhaar, NHS number), medical record numbers, diagnoses, medications, lab results, imaging, insurance policy and claim details, appointment and admission records, or any combination of the above.

PII (Non-patient-sensitive data) in healthcare systems: clinician/staff personal details, doctor fee structures and payout amounts, employee salary and bank details, vendor payment information.

Access Control: Row-Level Security

ALTER TABLE patients ENABLE ROW LEVEL SECURITY;

-- Scope access by facility
CREATE POLICY "staff_read_own_facility"
  ON patients FOR SELECT TO authenticated
  USING (facility_id IN (
    SELECT facility_id FROM staff_assignments
    WHERE user_id = auth.uid() AND role IN ('doctor','nurse','lab_tech','admin')
  ));

-- Audit log: insert-only (tamper-proof)
CREATE POLICY "audit_insert_only" ON audit_log FOR INSERT
  TO authenticated WITH CHECK (user_id = auth.uid());
CREATE POLICY "audit_no_modify" ON audit_log FOR UPDATE USING (false);
CREATE POLICY "audit_no_delete" ON audit_log FOR DELETE USING (false);

Audit Trail

Every PHI access or modification must be logged:

interface AuditEntry {
  timestamp: string;
  user_id: string;
  patient_id: string;
  action: 'create' | 'read' | 'update' | 'delete' | 'print' | 'export';
  resource_type: string;
  resource_id: string;
  changes?: { before: object; after: object };
  ip_address: string;
  session_id: string;
}

Common Leak Vectors

Error messages: Never include patient-identifying data in error messages thrown to the client. Log details server-side only.

Console output: Never log full patient objects. Use opaque internal record IDs (UUIDs) — not medical record numbers, national IDs, or names.

URL parameters: Never put patient-identifying data in query strings or path segments that could appear in logs or browser history. Use opaque UUIDs only.

Browser storage: Never store PHI in localStorage or sessionStorage. Keep PHI in memory only, fetch on demand.

Service role keys: Never use the service_role key in client-side code. Always use the anon/publishable key and let RLS enforce access.

Logs and monitoring: Never log full patient records. Use opaque record IDs only (not medical record numbers). Sanitize stack traces before sending to error tracking services.

Database Schema Tagging

Mark PHI/PII columns at the schema level:

COMMENT ON COLUMN patients.name IS 'PHI: patient_name';
COMMENT ON COLUMN patients.dob IS 'PHI: date_of_birth';
COMMENT ON COLUMN patients.aadhaar IS 'PHI: national_id';
COMMENT ON COLUMN doctor_payouts.amount IS 'PII: financial';

Deployment Checklist

Before every deployment:

• No PHI in error messages or stack traces
• No PHI in console.log/console.error
• No PHI in URL parameters
• No PHI in browser storage
• No service_role key in client code
• RLS enabled on all PHI/PII tables
• Audit trail for all data modifications
• Session timeout configured
• API authentication on all PHI endpoints
• Cross-facility data isolation verified

Examples

Example 1: Safe vs Unsafe Error Handling

// BAD — leaks PHI in error
throw new Error(`Patient ${patient.name} not found in ${patient.facility}`);

// GOOD — generic error, details logged server-side with opaque IDs only
logger.error('Patient lookup failed', { recordId: patient.id, facilityId });
throw new Error('Record not found');

Example 2: RLS Policy for Multi-Facility Isolation

-- Doctor at Facility A cannot see Facility B patients
CREATE POLICY "facility_isolation"
  ON patients FOR SELECT TO authenticated
  USING (facility_id IN (
    SELECT facility_id FROM staff_assignments WHERE user_id = auth.uid()
  ));

-- Test: login as doctor-facility-a, query facility-b patients
-- Expected: 0 rows returned

Example 3: Safe Logging

// BAD — logs identifiable patient data
console.log('Processing patient:', patient);

// GOOD — logs only opaque internal record ID
console.log('Processing record:', patient.id);
// Note: even patient.id should be an opaque UUID, not a medical record number