hipaa-compliance

Recovery Coach 的 HIPAA 合规性

此技能可帮助你在开发处理受保护健康信息（PHI）的功能时遵守 HIPAA 要求。

此应用中的 PHI 是什么？

数据类型	PHI 状态	处理方式
签到时的心情／渴求	PHI	审计所有访问
日记条目	PHI	审计所有访问
聊天对话	PHI	审计所有访问
用户个人资料（姓名、电子邮件）	PHI	审计所有修改
戒酒日期	PHI	审计访问
紧急联系人	PHI	审计访问
使用情况分析（汇总）	非 PHI	无需审计
页面浏览量（不含内容）	非 PHI	无需审计

审计日志要求

何时记录

务必记录以下操作：

• 查看任何 PHI（签到、日记、消息）
• 创建／更新／删除 PHI
• 导出用户数据
• 管理员访问用户信息
• 身份验证失败的尝试
• 安全事件（速率限制、未授权访问）

如何记录

使用 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
);

数据清理

切勿记录以下字段

审计系统会自动清理，但仍需明确注意：

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

已清理字段（自动脱敏）

• password、token、secret、key
• authorization、cookie、session
• credential、content、message、notes

会话安全要求

来自 src/lib/auth.ts：

• 会话超时：无操作 15 分钟（HIPAA 要求）
• 会话最长时长：绝对上限为 8 小时
• 登录失败锁定：尝试 5 次 = 禁止登录 30 分钟
• 密码要求：至少 12 个字符，包含大小写字母、数字和特殊字符

代码模式

带审计日志的 API 路由

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

访问 PHI 的组件

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

合规性检查清单

发布任何涉及 PHI 的功能前：

• 所有 PHI 访问均已记录审计日志
• 日志中不包含 PHI 内容（仅包含 ID 和元数据）
• 访问数据需要通过身份验证
• 管理员访问有单独的审计记录
• 访问失败的尝试均已记录
• 数据导出包含审计记录
• 敏感字段已加密存储
• 已强制执行会话超时

审计日志保留

• 最低期限：6 年（HIPAA 要求）
• 格式：原始日志保留 1 年，此后压缩
• 位置：数据库中的 audit_log 表
• 导出：用于合规审计的加密导出文件

紧急访问（破窗访问）

紧急情况下，请使用破窗访问：

import { requestBreakGlassAccess } from '@/lib/hipaa/break-glass';

// This creates enhanced audit trail
const access = await requestBreakGlassAccess(
  adminId,
  targetUserId,
  'Emergency support required - user reported crisis'
);

破窗访问：

• 需要提供书面理由
• 创建永久审计记录
• 向合规负责人触发警报
• 必须在 24 小时内审核

资源

• HIPAA 安全规则：45 C.F.R. § 164.312
• 审计控制标准：45 C.F.R. § 164.312(b)
• 事件响应计划：docs/INCIDENT-RESPONSE-PLAN.md
• 安全文档：docs/SECURITY-HARDENING.md