# 安全策略

## 报告安全漏洞

**请不要通过 GitHub Issue 公开报告安全漏洞。**

发现安全漏洞请通过以下渠道私密报告：

- 邮件：security@eazygame.cn
- 内部工单系统：Security 项目 → New Issue

报告时请包含：
1. 漏洞描述和影响范围
2. 复现步骤（最小化示例）
3. 影响的版本号
4. 建议的修复方案（可选）

**响应时间：** 24 小时内确认收到，5 个工作日内给出评估结果。

## 安全架构

### 权限三道防线

```
proxy.ts (路由级 bitmap) → requirePermission (Server Action 级) → usePermission (客户端级)
```

- **路由级**：`src/proxy.ts` 使用 bitmap 快速拦截未授权路由
- **Server Action 级**：每个 Action 必须调用 `requirePermission()`，或用 `@public` JSDoc 标记豁免
- **客户端级**：组件使用 `usePermission().hasPermission()` 控制元素显隐

### 认证与会话

- JWT/session ID 存储在 httpOnly + Secure + SameSite=Strict 的 Cookie 中
- 服务端环境变量不加 `NEXT_PUBLIC_` 前缀
- 环境变量使用 `@t3-oss/env-nextjs` + Zod 校验（`src/env.mjs`）

### 数据访问

- 前端禁止直接访问数据库，所有数据访问必须通过 `data-access.ts` 模块
- Server Action 必须使用 `requirePermission()` 进行权限校验
- 家长路由必须包含 `parentId` 和 `studentId` 双重权限校验，防止信息泄露

### 输入安全

- **禁止 `dangerouslySetInnerHTML`**（如必须使用，先用 DOMPurify 清洗）
- Server Action 输入使用 Zod 验证，验证失败返回结构化错误
- 注册/登录流程实施速率限制，防止暴力破解和邮箱枚举攻击

## 安全审计

### arch:scan 自动检测

`npm run arch:query -- violations` 会自动检测：

- **长文件**（>800 行）：提示拆分，降低维护风险
- **Server Action 权限缺失**：识别未调用 `requirePermission` 的 Server Action（支持递归调用链识别）

### @public 豁免标记

登录前/公开/内部工具 Server Action 可用 `@public` JSDoc 标记豁免权限校验：

```ts
/**
 * 注册 Action，登录前公开调用。
 *
 * @public 登录前公开 Action，豁免 requirePermission 校验。
 */
export async function registerAction(formData: FormData) {
  // ...
}
```

**豁免场景：**
- 登录前 Action（注册、邮箱可用性检查、2FA 预检）
- 内部日志工具（audit-logger、change-logger、login-logger）
- 权限查询工具（isAdminRole、canConfigurePublicAiProvider）
- 登录后必经流程（onboarding 状态查询/完成）

## 依赖安全

- 定期运行 `npm audit` 检查已知漏洞
- CI 流水线包含 Trivy 安全扫描（`.trivyignore` 配置豁免项）
- 依赖升级通过 PR 审核，不允许直接推送 main 分支

## 数据保护

- 数据库备份：每日自动备份，每周 DR 演练
- 敏感数据（密码、2FA 密钥）使用 bcrypt/Argon2 哈希存储
- 日志不记录敏感信息（密码、token、个人身份信息）