Vibecosystem hipaa-compliance

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

install
source · Clone the upstream repo
git clone https://github.com/vibeeval/vibecosystem
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/vibeeval/vibecosystem "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/hipaa-compliance" ~/.claude/skills/vibeeval-vibecosystem-hipaa-compliance && rm -rf "$T"
manifest: skills/hipaa-compliance/SKILL.md
source content

HIPAA Compliance

PHI (Protected Health Information) Identification

What is PHI?

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

18 HIPAA Identifiers

#IdentifierExampleDe-Identification Action
1NamesJohn SmithRemove
2Geographic data (< state)123 Main St, ZIPTruncate ZIP to 3 digits
3Dates (except year)DOB, admission dateGeneralize to year
4Phone numbers(555) 123-4567Remove
5Fax numbers(555) 123-4568Remove
6Email addressesjohn@example.comRemove
7SSN123-45-6789Remove
8Medical record numbersMRN-001234Replace with random ID
9Health plan beneficiary #BEN-98765Remove
10Account numbersACC-12345Remove
11Certificate/license #LIC-54321Remove
12Vehicle identifiersVIN, plate #Remove
13Device identifiersSerial #, IMEIRemove
14Web URLspatient-portal.com/user/123Remove
15IP addresses192.168.1.1Remove
16Biometric identifiersFingerprint, voiceprintRemove
17Full-face photographsProfile photoRemove
18Any unique identifying #Custom patient IDReplace 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: string;
  algorithm: 'sha256';
  computedAt: Date;
}

function computeRecordHash(record: Record<string, unknown>): string {
  const canonical = JSON.stringify(record, Object.keys(record).sort());
  return createHash('sha256').update(canonical).digest('hex');
}

async function verifyIntegrity(recordId: string): Promise<boolean> {
  const record = await db.medicalRecords.findUnique({ where: { id: recordId } });
  const storedHash = await db.integrityRecords.findUnique({ where: { recordId } });

  if (!record || !storedHash) return false;

  const currentHash = computeRecordHash(record);
  return currentHash === storedHash.hash;
}

Transmission Security (164.312(e))

// TLS enforcement for PHI transmission
import https from 'https';
import fs from 'fs';

const tlsOptions: https.ServerOptions = {
  key: fs.readFileSync(process.env.TLS_KEY_PATH!),
  cert: fs.readFileSync(process.env.TLS_CERT_PATH!),
  minVersion: 'TLSv1.2',       // HIPAA minimum
  ciphers: [
    'TLS_AES_256_GCM_SHA384',
    'TLS_CHACHA20_POLY1305_SHA256',
    'ECDHE-RSA-AES256-GCM-SHA384',
  ].join(':'),
  honorCipherOrder: true,
};

// End-to-end encryption for PHI in transit between systems
function encryptPHIForTransmission(phi: string, recipientPublicKey: string): string {
  const symmetricKey = randomBytes(32);
  const encryptedData = encryptAES256GCM(phi, symmetricKey);
  const encryptedKey = publicEncrypt(recipientPublicKey, symmetricKey);
  return JSON.stringify({ encryptedData, encryptedKey: encryptedKey.toString('base64') });
}

Administrative Safeguards (164.308)

Checklist

  • Security Officer designated
  • Privacy Officer designated
  • Risk analysis conducted (annual)
  • Risk management plan documented
  • Sanction policy for violations
  • Information system activity review (regular)
  • Workforce security procedures
  • Security awareness training (annual)
  • Security incident procedures
  • Contingency plan (backup, DR, emergency mode)
  • Evaluation (periodic compliance assessment)
  • Business Associate Agreements (BAA) with all vendors

Workforce Training Requirements

TopicFrequencyAudience
HIPAA overviewAnnualAll staff
PHI handling proceduresAnnualPHI access staff
Security awarenessAnnual + onboardingAll staff
Incident reportingAnnualAll staff
Phishing awarenessQuarterlyAll staff
Role-specific PHI policiesAnnualClinical staff

Physical Safeguards (164.310)

Checklist

  • Facility access controls (badge, biometric)
  • Workstation use policy (screen lock, clean desk)
  • Workstation security (cable locks, positioning)
  • Device and media controls (disposal, reuse, movement)
  • Visitor access logging
  • Server room access restricted and logged
  • Mobile device policy (encryption, remote wipe)

Minimum Necessary Standard

Implementation

// Minimum Necessary middleware
function minimumNecessaryFilter(role: string, endpoint: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    const fieldPermissions = getFieldPermissions(role, endpoint);

    // Override response to filter fields
    const originalJson = res.json.bind(res);
    res.json = (data: unknown) => {
      const filtered = filterFields(data, fieldPermissions);
      return originalJson(filtered);
    };

    next();
  };
}

// Field access matrix
const FIELD_PERMISSIONS: Record<string, Record<string, string[]>> = {
  receptionist: {
    '/api/patients': ['id', 'name', 'dob', 'phone', 'appointmentTime'],
    '/api/patients/:id': ['id', 'name', 'dob', 'phone', 'insuranceId'],
  },
  nurse: {
    '/api/patients': ['id', 'name', 'dob', 'vitals', 'medications', 'allergies'],
    '/api/patients/:id': ['*'], // Full treatment access
  },
  billing: {
    '/api/patients': ['id', 'name', 'insuranceId', 'billingCodes'],
    '/api/patients/:id': ['id', 'name', 'insuranceId', 'billingCodes', 'procedures'],
  },
};

Exceptions to Minimum Necessary

ScenarioMinimum Necessary Applies?
Treatment (doctor-to-doctor)NO - full PHI allowed
Patient's own requestNO - full access to own data
Required by lawNO - as required
Payment/billingYES - only billing-relevant fields
Healthcare operationsYES - limit to necessary
Research (with authorization)YES - de-identified preferred

Business Associate Agreement (BAA)

Required BAA Provisions

## BAA Checklist

- [ ] Permitted uses and disclosures of PHI defined
- [ ] BA will not use/disclose PHI beyond contract
- [ ] BA will implement appropriate safeguards
- [ ] BA will report security incidents and breaches
- [ ] BA will ensure subcontractors comply
- [ ] BA will make PHI available for patient access
- [ ] BA will make PHI available for amendment
- [ ] BA will provide accounting of disclosures
- [ ] BA will make internal practices available to HHS
- [ ] BA will return or destroy PHI at termination
- [ ] CE may terminate if BA violates terms

Common BA Vendors Requiring BAA

Vendor TypeExamplesPHI Exposure
Cloud hostingAWS, GCP, AzureInfrastructure
EHR systemsEpic, CernerFull PHI
Email (if PHI sent)Google Workspace, M365Communication
Payment processingStripe (if health billing)Billing PHI
Analytics (if PHI)Custom analyticsUsage data
Backup servicesVeeam, BackblazeFull PHI
Shredding servicesIron MountainPhysical PHI

De-Identification Methods

Safe Harbor Method (164.514(b)(2))

interface DeIdentifiedRecord {
  randomId: string;  // Not derived from original ID
  ageGroup: string;  // '>89' or age bucket
  zipCode3: string;  // First 3 digits (if population > 20K)
  diagnosisCode: string;
  procedureCode: string;
  // ALL 18 identifiers removed
}

function deIdentifySafeHarbor(record: PatientRecord): DeIdentifiedRecord {
  const age = calculateAge(record.dateOfBirth);

  return {
    randomId: generateRandomId(), // NOT derived from patient ID
    ageGroup: age > 89 ? '90+' : `${Math.floor(age / 10) * 10}-${Math.floor(age / 10) * 10 + 9}`,
    zipCode3: record.zipCode.substring(0, 3),
    diagnosisCode: record.diagnosisCode,
    procedureCode: record.procedureCode,
    // name: REMOVED
    // dob: REMOVED (age bucket only)
    // ssn: REMOVED
    // mrn: REMOVED
    // phone: REMOVED
    // email: REMOVED
    // address: REMOVED (zip3 only)
  };
}

Expert Determination Method (164.514(b)(1))

## Expert Determination Requirements

1. Apply statistical/scientific methods
2. Determine re-identification risk is "very small"
3. Document methods and results
4. Expert must have appropriate knowledge and experience
5. Re-identification risk typically < 0.04 (1 in 25)

PHI Encryption Standards

At Rest

// Column-level encryption for PHI fields
import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'crypto';

const ALGORITHM = 'aes-256-gcm';
const KEY = scryptSync(process.env.PHI_ENCRYPTION_KEY!, 'salt', 32);

function encryptPHIField(value: string): EncryptedField {
  const iv = randomBytes(16);
  const cipher = createCipheriv(ALGORITHM, KEY, iv);
  const encrypted = Buffer.concat([cipher.update(value, 'utf8'), cipher.final()]);
  return {
    data: encrypted.toString('base64'),
    iv: iv.toString('base64'),
    tag: cipher.getAuthTag().toString('base64'),
  };
}

function decryptPHIField(encrypted: EncryptedField): string {
  const decipher = createDecipheriv(
    ALGORITHM,
    KEY,
    Buffer.from(encrypted.iv, 'base64')
  );
  decipher.setAuthTag(Buffer.from(encrypted.tag, 'base64'));
  return decipher.update(encrypted.data, 'base64', 'utf8') + decipher.final('utf8');
}

Key Management

  • Encryption keys stored separately from data
  • Key rotation schedule (annual minimum)
  • Key access limited to security team
  • Key backup and recovery procedure
  • Key destruction procedure for decommissioned systems

HIPAA Violation Penalties

TierDescriptionPenalty Per ViolationAnnual Maximum
1Did not know$100 - $50,000$25,000
2Reasonable cause$1,000 - $50,000$100,000
3Willful neglect (corrected)$10,000 - $50,000$250,000
4Willful neglect (not corrected)$50,000+$1,500,000

Anti-Patterns

Anti-PatternHIPAA ViolationDogru Yol
PHI in logs/debug outputMinimum necessaryFilter PHI before logging
PHI in error messagesMinimum necessaryGeneric error messages
Unencrypted PHI at restTechnical safeguardAES-256 encryption
Shared login credentialsAccess controlIndividual accounts + MFA
No audit trailAudit controlsImmutable access logging
PHI in URL parametersTransmission securityPOST body + TLS
PHI in email (unencrypted)Transmission securityEncrypted messaging or portal
No BAA with cloud vendorAdministrative safeguardExecute BAA before use
No access expirationAccess controlAuto-expire + review
PHI on personal devicesPhysical safeguardMDM + encryption policy