HIPAA Compliance for Recovery Coach
This skill helps you maintain HIPAA compliance when developing features that handle Protected Health Information (PHI).
What is PHI in This Application? Data Type PHI Status Handling Check-in mood/cravings PHI Audit all access Journal entries PHI Audit all access Chat conversations PHI Audit all access User profile (name, email) PHI Audit modifications Sobriety date PHI Audit access Emergency contacts PHI Audit access Usage analytics (aggregated) NOT PHI No audit needed Page views (no content) NOT PHI No audit needed Audit Logging Requirements When to Log
Always log these operations:
Viewing any PHI (check-ins, journal, messages) Creating/updating/deleting PHI Exporting user data Admin access to user information Failed authentication attempts Security events (rate limiting, unauthorized access) How to Log
Use the audit logging utilities in src/lib/hipaa/audit.ts:
import { logPHIAccess, logPHIModification, logSecurityEvent, logAdminAction } from '@/lib/hipaa/audit';
// Viewing PHI await logPHIAccess( userId, 'checkin', // targetType checkinId, // targetId AuditAction.PHI_VIEW );
// Modifying PHI await logPHIModification( userId, 'journal', journalId, AuditAction.PHI_UPDATE, { field: 'content' } // Never include actual content! );
// Security event await logSecurityEvent( userId, AuditAction.RATE_LIMIT, { path: '/api/chat', attempts: 60 } );
// Admin action await logAdminAction( adminId, AuditAction.ADMIN_USER_VIEW, 'user', targetUserId );
Data Sanitization Never Log These Fields
The audit system automatically sanitizes, but be explicit:
// BAD - Contains PHI await logPHIAccess(userId, 'journal', id, action, { content: journalEntry.content // NEVER DO THIS });
// GOOD - Only metadata await logPHIAccess(userId, 'journal', id, action, { wordCount: journalEntry.content.length, hasAttachments: false });
Sanitized Fields (Auto-Redacted) password, token, secret, key authorization, cookie, session credential, content, message, notes Session Security Requirements
From src/lib/auth.ts:
Session timeout: 15 minutes of inactivity (HIPAA requirement) Max session: 8 hours absolute maximum Failed login lockout: 5 attempts = 30 minute ban Password requirements: 12+ chars, mixed case, numbers, special chars Code Patterns API Route with Audit Logging import { getSession, requireAuth } from '@/lib/auth'; import { logPHIAccess } from '@/lib/hipaa/audit';
export async function GET(request: Request) { const session = await getSession(); if (!session) { return Response.json({ error: 'Unauthorized' }, { status: 401 }); }
// Fetch the data const data = await fetchUserData(session.userId);
// Log the access await logPHIAccess( session.userId, 'userdata', session.userId, AuditAction.PHI_VIEW );
return Response.json(data); }
Component with PHI Access 'use client';
import { useEffect } from 'react';
export function JournalViewer({ entryId }: { entryId: string }) { useEffect(() => { // Log view on mount (server-side preferred, but client backup) fetch('/api/audit/log', { method: 'POST', body: JSON.stringify({ action: 'PHI_VIEW', targetType: 'journal', targetId: entryId }) }); }, [entryId]);
// ... render }
Compliance Checklist
Before shipping any feature that touches PHI:
All PHI access is audit logged No PHI content in logs (only IDs and metadata) Data access requires authentication Admin access has separate audit trail Failed access attempts are logged Data export includes audit entry Sensitive fields are encrypted at rest Session timeout is enforced Audit Log Retention Minimum: 6 years (HIPAA requirement) Format: Raw logs for 1 year, compressed thereafter Location: audit_log table in database Export: Encrypted exports for compliance audits Emergency Access (Break Glass)
For emergency situations, use break-glass access:
import { requestBreakGlassAccess } from '@/lib/hipaa/break-glass';
// This creates enhanced audit trail const access = await requestBreakGlassAccess( adminId, targetUserId, 'Emergency support required - user reported crisis' );
Break glass access:
Requires written justification Creates permanent audit record Triggers alert to compliance officer Must be reviewed within 24 hours Resources HIPAA Security Rule: 45 C.F.R. § 164.312 Audit controls standard: 45 C.F.R. § 164.312(b) Incident response plan: docs/INCIDENT-RESPONSE-PLAN.md Security documentation: docs/SECURITY-HARDENING.md