hipaa-compliance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HIPAA Compliance for Recovery Coach

康复教练系统的HIPAA合规指南

This skill helps you maintain HIPAA compliance when developing features that handle Protected Health Information (PHI).

本Skill可帮助你在开发处理受保护健康信息（PHI）的功能时，维持HIPAA合规性。

What is PHI in This Application?

本应用中的PHI定义

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

数据类型	PHI状态	处理要求
签到情绪/成瘾渴望	属于PHI	审计所有访问行为
日志条目	属于PHI	审计所有访问行为
聊天对话	属于PHI	审计所有访问行为
用户资料（姓名、邮箱）	属于PHI	审计所有修改操作
戒酒日期	属于PHI	审计所有访问行为
紧急联系人	属于PHI	审计所有访问行为
使用分析数据（聚合后）	不属于PHI	无需审计
页面浏览记录（无内容）	不属于PHI	无需审计

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)

以下操作必须记录日志：

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

How to Log

日志记录方式

Use the audit logging utilities in

src/lib/hipaa/audit.ts

typescript

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

使用

src/lib/hipaa/audit.ts

中的审计日志工具：

typescript

import {
  logPHIAccess,
  logPHIModification,
  logSecurityEvent,
  logAdminAction
} from '@/lib/hipaa/audit';

// 查看PHI数据
await logPHIAccess(
  userId,
  'checkin',        // targetType
  checkinId,        // targetId
  AuditAction.PHI_VIEW
);

// 修改PHI数据
await logPHIModification(
  userId,
  'journal',
  journalId,
  AuditAction.PHI_UPDATE,
  { field: 'content' }  // 绝对不要包含实际内容！
);

// 安全事件
await logSecurityEvent(
  userId,
  AuditAction.RATE_LIMIT,
  { path: '/api/chat', attempts: 60 }
);

// 管理员操作
await logAdminAction(
  adminId,
  AuditAction.ADMIN_USER_VIEW,
  'user',
  targetUserId
);

Data Sanitization

数据脱敏要求

Never Log These Fields

禁止记录的字段

The audit system automatically sanitizes, but be explicit:

typescript

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

审计系统会自动脱敏，但需明确遵循：

typescript

// 错误示例 - 包含PHI数据
await logPHIAccess(userId, 'journal', id, action, {
  content: journalEntry.content  // 绝对不要这样做
});

// 正确示例 - 仅记录元数据
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
```

```
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

来自

src/lib/auth.ts

的规定：

会话超时：15分钟无活动（HIPAA强制要求）
最长会话时长：绝对不超过8小时
登录失败锁定：5次尝试后锁定30分钟
密码要求：12位以上，包含大小写字母、数字、特殊字符

Code Patterns

代码实现模式

API Route with Audit Logging

带审计日志的API路由

typescript

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

typescript

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

  // 获取数据
  const data = await fetchUserData(session.userId);

  // 记录访问日志
  await logPHIAccess(
    session.userId,
    'userdata',
    session.userId,
    AuditAction.PHI_VIEW
  );

  return Response.json(data);
}

Component with PHI Access

访问PHI数据的组件

typescript

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

typescript

'use client';

import { useEffect } from 'react';

export function JournalViewer({ entryId }: { entryId: string }) {
  useEffect(() => {
    // 组件挂载时记录访问日志（优先服务端实现，客户端作为备份）
    fetch('/api/audit/log', {
      method: 'POST',
      body: JSON.stringify({
        action: 'PHI_VIEW',
        targetType: 'journal',
        targetId: entryId
      })
    });
  }, [entryId]);

  // ... 渲染逻辑
}

Compliance Checklist

合规检查清单

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

最短保留时长：6年（HIPAA强制要求）
存储格式：原始日志保留1年，之后转为压缩格式
存储位置：数据库中的
```
audit_log
```
表
导出要求：合规审计时需提供加密的日志导出文件

Emergency Access (Break Glass)

紧急访问（Break Glass机制）

For emergency situations, use break-glass access:

typescript

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

在紧急情况下，使用Break Glass紧急访问机制：

typescript

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

// 此操作会生成增强型审计轨迹
const access = await requestBreakGlassAccess(
  adminId,
  targetUserId,
  'Emergency support required - user reported crisis'
);

Break Glass紧急访问规则：

需提供书面理由
生成永久审计记录
触发合规负责人警报
必须在24小时内完成审核

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
```

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