/hipaa-compliance

name: hipaa-compliance
description: HIPAA compliance - PHI protection, technical/administrative/physical safeguards, minimum necessary standard, BAA requirements, de-identification, access logging

HIPAA Compliance

PHI (Protected Health Information) Identification

What is PHI?

PHI = Individually identifiable health information transmitted or maintained in any form.

18 HIPAA Identifiers

| # | Identifier | Example | De-Identification Action | |---|-----------|---------|-------------------------| | 1 | Names | John Smith | Remove | | 2 | Geographic data (< state) | 123 Main St, ZIP | Truncate ZIP to 3 digits | | 3 | Dates (except year) | DOB, admission date | Generalize to year | | 4 | Phone numbers | (555) 123-4567 | Remove | | 5 | Fax numbers | (555) 123-4568 | Remove | | 6 | Email addresses | john@example.com | Remove | | 7 | SSN | 123-45-6789 | Remove | | 8 | Medical record numbers | MRN-001234 | Replace with random ID | | 9 | Health plan beneficiary # | BEN-98765 | Remove | | 10 | Account numbers | ACC-12345 | Remove | | 11 | Certificate/license # | LIC-54321 | Remove | | 12 | Vehicle identifiers | VIN, plate # | Remove | | 13 | Device identifiers | Serial #, IMEI | Remove | | 14 | Web URLs | patient-portal.com/user/123 | Remove | | 15 | IP addresses | 192.168.1.1 | Remove | | 16 | Biometric identifiers | Fingerprint, voiceprint | Remove | | 17 | Full-face photographs | Profile photo | Remove | | 18 | Any unique identifying # | Custom patient ID | Replace with random |

PHI Detection

interface PHIDetectionResult {
  field: string;
  identifierType: string;
  confidence: 'high' | 'medium' | 'low';
  recommendation: 'encrypt' | 'remove' | 'truncate' | 'pseudonymize';
}

const PHI_PATTERNS: Record<string, RegExp> = {
  ssn: /\b\d{3}-\d{2}-\d{4}\b/,
  phone: /\b\(?(\d{3})\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/,
  email: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/,
  mrn: /\bMRN[-\s]?\d{4,}\b/i,
  dob: /\b(0[1-9]|1[0-2])\/(0[1-9]|[12]\d|3[01])\/\d{4}\b/,
  ip: /\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/,
};

function scanForPHI(text: string): PHIDetectionResult[] {
  const results: PHIDetectionResult[] = [];
  for (const [type, pattern] of Object.entries(PHI_PATTERNS)) {
    if (pattern.test(text)) {
      results.push({
        field: type,
        identifierType: type,
        confidence: 'high',
        recommendation: 'encrypt',
      });
    }
  }
  return results;
}

Technical Safeguards (164.312)

Access Control (164.312(a))

// Role-Based Access Control for PHI
interface HIPAARole {
  name: string;
  phiAccess: 'none' | 'minimum_necessary' | 'treatment' | 'admin';
  allowedOperations: ('read' | 'write' | 'delete' | 'export')[];
  requiresMFA: boolean;
}

const HIPAA_ROLES: Record<string, HIPAARole> = {
  receptionist: {
    name: 'Receptionist',
    phiAccess: 'minimum_necessary',
    allowedOperations: ['read'],
    requiresMFA: true,
  },
  nurse: {
    name: 'Nurse',
    phiAccess: 'treatment',
    allowedOperations: ['read', 'write'],
    requiresMFA: true,
  },
  physician: {
    name: 'Physician',
    phiAccess: 'treatment',
    allowedOperations: ['read', 'write'],
    requiresMFA: true,
  },
  admin: {
    name: 'System Admin',
    phiAccess: 'admin',
    allowedOperations: ['read', 'write', 'delete', 'export'],
    requiresMFA: true,
  },
  billing: {
    name: 'Billing Staff',
    phiAccess: 'minimum_necessary',
    allowedOperations: ['read'],
    requiresMFA: true,
  },
};

function enforceMinimumNecessary(
  role: HIPAARole,
  requestedFields: string[],
  allFields: string[]
): string[] {
  if (role.phiAccess === 'treatment') {
    return requestedFields; // Treatment = full access to relevant PHI
  }
  if (role.phiAccess === 'minimum_necessary') {
    // Only return non-clinical fields
    const nonClinicalFields = ['patientId', 'name', 'dob', 'insuranceId'];
    return requestedFields.filter((f) => nonClinicalFields.includes(f));
  }
  return [];
}

Audit Controls (164.312(b))

interface HIPAAAuditLog {
  id: string;
  timestamp: string;
  userId: string;
  userRole: string;
  action: 'view' | 'create' | 'update' | 'delete' | 'export' | 'print';
  patientId: string;
  resourceType: string;          // 'medical_record', 'lab_result', 'prescription'
  resourceId: string;
  accessReason: string;          // 'treatment', 'payment', 'operations'
  ipAddress: string;
  userAgent: string;
  sessionId: string;
  success: boolean;
  details?: string;
}

async function logPHIAccess(entry: HIPAAAuditLog): Promise<void> {
  // HIPAA requires immutable, tamper-evident logs
  // Minimum 6 yil retention
  await auditStore.append({
    ...entry,
    integrity: computeHMAC(entry),
  });

  // Alert on suspicious access patterns
  if (await isAnomalousAccess(entry)) {
    await alertSecurityTeam({
      type: 'suspicious_phi_access',
      entry,
      reason: 'Anomalous access pattern detected',
    });
  }
}

async function isAnomalousAccess(entry: HIPAAAuditLog): Promise<boolean> {
  const recentAccess = await auditStore.getRecent(entry.userId, '1h');
  // Flag: >50 records in 1 hour (potential data exfiltration)
  if (recentAccess.length > 50) return true;
  // Flag: access outside business hours
  const hour = new Date(entry.timestamp).getHours();
  if (hour < 6 || hour > 22) return true;
  // Flag: accessing patient not in user's care
  if (entry.accessReason === 'treatment') {
    const isAssigned = await isPatientAssigned(entry.userId, entry.patientId);
    if (!isAssigned) return true;
  }
  return false;
}

Integrity Controls (164.312(c))

// Data integrity verification for PHI
import { createHash } from 'crypto';

interface IntegrityRecord {
  recordId: string;
  hash: str