NextEdu/SECURITY.md

安全策略

报告安全漏洞

请不要通过 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 标记豁免权限校验：

/**
 * 注册 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、个人身份信息）