Healthcare PHI Compliance Skill

I. Skill Overview
This skill is used for building functionality involving patient records, implementing access control for clinical systems, designing database schemas for healthcare data, building APIs that return patient or clinician data, implementing audit trails or logging, and reviewing code for data exposure vulnerabilities. It operates on a three‑layer protection model: Classification (identifying which data is sensitive), Access Control (who can view it), and Auditing (who has viewed it).

Applicable regulatory scope: HIPAA (USA), DISHA (India), GDPR (EU), and general healthcare data protection.

II. Core Functions
1. Data Classification
The skill clearly defines the types of data that need to be protected in healthcare systems:

2. Row‑Level Security
The skill provides implementation patterns for access control based on PostgreSQL RLS:

-- Enable RLS
ALTER TABLE patients ENABLE ROW LEVEL SECURITY;

-- Restrict 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);

3. Audit Trail
Every PHI access or modification must be logged. The skill provides a standard audit entry interface:

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;
}

4. Common Leakage Vector Protection
The skill explicitly lists data leakage pathways that must be guarded against:

5. Database Schema Tagging
Mark PHI/PII columns at the database 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';

6. Code Examples
Example 1: Safe vs unsafe error handling

// ❌ Unsafe – leaks PHI
throw new Error(`Patient ${patient.name} not found in ${patient.facility}`);

// ✅ Safe – generic error, details logged server‑side
logger.error('Patient lookup failed', { recordId: patient.id, facilityId });
throw new Error('Record not found');

Example 3: Safe logging

// ❌ Unsafe – logs patient‑identifiable data
console.log('Processing patient:', patient);

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

III. Primary Use Cases

• Healthcare data system development – establish compliance protections when building functionality involving patient records, clinical systems, or healthcare APIs

• Access control and authentication design – implement authentication, authorisation, and row‑level security policies for clinical systems

• Database schema design – identify and tag PHI/PII columns when designing healthcare data table structures

• Code review and vulnerability排查 – review code for data exposure vulnerabilities

• Multi‑tenant healthcare system isolation – set up RLS to ensure cross‑facility data isolation

• Audit trail implementation – establish tamper‑proof audit logs for all data modifications and accesses

IV. Pre‑Deployment Checklist
Before each deployment, each item must be confirmed:

• Error messages and stack traces contain no PHI

• console.log/console.error contain no PHI

• URL parameters contain no PHI

• Browser storage contains no PHI

• Client‑side code contains no service_role keys

• RLS is enabled on all PHI/PII tables

• Audit trail exists for all data modifications

• Session timeout is configured

• All PHI endpoints have API authentication

• Cross‑facility data isolation has been verified

V. Important Principles

• Classify first – identify which data is PHI/PII before designing protection measures

• RLS enforces isolation – use database row‑level security as the last line of defence for access control

• Audit trail must be tamper‑proof – audit logs should be insert‑only, with no updates or deletions allowed

• Never log full patient objects – use opaque UUIDs instead of identifiable information

• Never use service_role client‑side – always control access via RLS

• Sanitise error messages – return only generic errors to users; details are visible only server‑side

• Defence in depth – classification, access control, and auditing work together across three layers

• Database‑level tagging – mark PHI/PII columns at the schema level to facilitate automated scanning and compliance auditing

VI. Summary
Healthcare PHI Compliance is a comprehensive set of practical practices for healthcare data compliance and PHI/PII protection, covering core areas such as data classification, row‑level security (RLS), audit trails, leakage vector protection, database schema tagging, and deployment checks. It provides directly usable SQL policy templates, audit interface definitions, and code examples, applicable to multiple regulatory frameworks including HIPAA, DISHA, and GDPR. This skill is suitable for healthcare system developers, architects, and security reviewers in scenarios such as building systems involving patient data, implementing access controls, designing database schemas, and auditing code.