# Kylin Auth - 法律合规文档

## 一、适用法律法规

### 1.1 等保 2.0 (GB/T 22239-2019)

| 控制点 | 要求 | 合规要点 |
|------|------|----------|
| 身份鉴别 (8.1.4.2) | 应对登录的用户进行身份标识和鉴别，身份标识具有唯一性 | 支持邮箱/手机/用户名唯一标识登录 |
| 身份鉴别 (8.1.4.2) | 应具有登录失败处理功能，应配置并启用结束会话、限制非法登录次数和当登录连接超时自动退出等相关措施 | 登录失败锁定（max_attempts=5, lockout=30min），会话超时（session_lifetime=120min） |
| 身份鉴别 (8.1.4.2) | 当进行远程管理时，应采取必要措施防止鉴别信息在网络传输过程中被窃听 | 全站 HTTPS + Token 认证 |
| 访问控制 (8.1.4.3) | 应授予不同账户为完成各自承担任务所需的最小权限 | 基于 RBAC 的角色权限控制 |
| 安全审计 (8.1.4.6) | 应启用安全审计功能 | 登录日志记录登录时间、IP、设备信息 |
| 密码策略 | 密码复杂度应满足要求：长度 >= 8，含大小写字母、数字、特殊字符 | 密码复杂度配置 + 登录时校验 |

### 1.2 《中华人民共和国网络安全法》(2017.6.1)

| 条款 | 要求 | 合规要点 |
|------|------|----------|
| 第二十一条 | 采取身份认证等安全保护措施 | 多因子认证（密码 + 验证码） |
| 第二十四条 | 网络运营者为用户提供信息发布、即时通讯等服务，应当要求用户提供真实身份信息 | 实名认证流程 |
| 第四十二条 | 不得泄露、篡改、毁损其收集的个人信息 | 密码 Bcrypt 哈希存储，不可逆加密 |

### 1.3 《中华人民共和国个人信息保护法》(2021.11.1)

| 条款 | 要求 | 合规要点 |
|------|------|----------|
| 第六条 | 收集个人信息应当限于实现处理目的的最小范围 | 登录仅收集必要信息（账号、密码） |
| 第二十八条 | 敏感个人信息需单独同意 | 密码属于敏感信息，Bcrypt 加密存储 |
| 第四十四条 | 个人对其个人信息处理享有知情权、决定权 | 提供注销账号、退出登录功能 |

### 1.4 《中华人民共和国密码法》(2020.1.1)

| 条款 | 要求 | 合规要点 |
|------|------|----------|
| 第十二条 | 密码分为核心密码、普通密码和商用密码 | 密码存储使用国家认可的商用密码算法（Bcrypt/SHA-256） |
| 第二十七条 | 关键信息基础设施应当使用商用密码进行保护 | 密码哈希使用 Bcrypt（Blowfish 算法） |

### 1.5 《中华人民共和国数据安全法》(2021.9.1)

| 条款 | 要求 | 合规要点 |
|------|------|----------|
| 第二十七条 | 开展数据处理活动应当加强风险监测 | 登录失败监控、异常登录检测 |
| 第二十九条 | 开展数据处理活动应当加强风险监测，发现数据安全缺陷、漏洞等风险时，应当立即采取补救措施 | 密码过期强制修改机制 |

### 1.6 《信息安全技术 个人信息安全规范》(GB/T 35273-2020)

| 条款 | 要求 | 合规要点 |
|------|------|----------|
| 6.1 | 个人信息收集的合法性 | 注册时需同意隐私政策 |
| 7.1 | 个人信息访问控制措施 | 基于角色的登录权限控制 |

---

## 二、行业规范

### 2.1 企业级 SaaS 认证

- 依据 **《云计算服务安全评估办法》**（2019），云服务应提供多因子认证
- 依据 OWASP ASVS 4.0，认证模块应满足 V2 认证验证要求
- Token 应设置合理过期时间，支持刷新机制

### 2.2 密码安全规范

- 依据 **NIST SP 800-63B** 数字身份指南：
  - 密码最小长度 8 位
  - 支持所有可打印 ASCII 字符及 Unicode
  - 不应定期强制修改密码（除非有泄露迹象）
  - 但等保 2.0 要求密码定期更换，两者冲突时优先满足等保要求
- 密码存储必须使用单向哈希（Bcrypt 成本因子 >= 10）
- 密码传输必须通过 HTTPS 加密

### 2.3 会话管理规范

- 依据 OWASP Session Management Cheat Sheet：
  - 会话 ID 应使用安全随机数生成器
  - 会话超时应设置合理时间（建议 15-30 分钟）
  - 退出登录时应销毁会话
  - 不应在 URL 中传递会话 ID

---

## 三、合规检查清单

### 3.1 密码策略

- [x] 密码最小长度 >= 8 位（配置 `min_length = 8`）
- [x] 密码需包含大写字母（`require_uppercase = true`）
- [x] 密码需包含小写字母（`require_lowercase = true`）
- [x] 密码需包含数字（`require_number = true`）
- [x] 密码需包含特殊字符（`require_special = true`）
- [x] 密码 Bcrypt 哈希存储（`Hash::make()`）
- [x] 密码最长有效期 90 天（`max_age_days = 90`）
- [x] 旧密码明文自动迁移为 Bcrypt（`login()` 兼容逻辑）

### 3.2 登录安全

- [x] 登录失败次数限制（`max_attempts = 5`）
- [x] 登录失败锁定时间（`lockout_minutes = 30`）
- [x] 会话超时自动退出（`session_lifetime = 120`）
- [x] 验证码防暴力破解（`captcha.enabled = true`）
- [x] 登录日志记录（IP、时间、设备）

### 3.3 Token 安全

- [x] Token 过期时间合理（默认 60 分钟，`token.expiration`）
- [x] Token 支持刷新机制（`refreshToken()`）
- [x] 退出登录时销毁 Token（`logout()` 删除当前令牌）
- [x] Token 通过 HTTPS 传输（需基础架构层实施）

### 3.4 账号安全

- [x] 账号唯一性校验（`register()` 检查邮箱/手机/用户名唯一）
- [x] 禁用账号不可登录（`UserStatus::Disabled` 检查）
- [x] 锁定账号不可登录（`UserStatus::Locked` 检查）
- [x] 提供注销账号功能（需业务层实现）

---

## 四、代码检测报告

### 4.1 检测结果

| 检测项 | 状态 | 说明 |
|------|------|------|
| 密码复杂度配置 | ✅ 已通过 | 配置含长度/大小写/数字/特殊字符要求 |
| 密码 Bcrypt 存储 | ✅ 已通过 | Hash::make() 使用 Bcrypt，旧密码自动迁移 |
| 登录失败锁定 | ✅ 已通过 | `checkRateLimit()` 使用正确配置键 `kylin-auth.login_security.max_attempts` |
| 密码过期检查 | ✅ 已通过 | `login()` 使用正确配置键 `kylin-auth.password.max_age_days` |
| 密码复杂度校验 | ✅ 已修复 | `LoginRequest` 密码 min:8，`RegisterRequest` 密码 min:8 |
| 注册密码强度 | ✅ 已修复 | `register()` 调用 `validatePasswordComplexity()` 校验复杂度 |
| 限流错误码 | ✅ 已修复 | `checkRateLimit()` 使用 `TooManyAttempts` 错误码，与 `AccountLocked` 区分 |

### 4.2 修复明细

1. **config/kylin-auth.php** — 密码策略、登录安全、Token 配置已完整
2. **Services/AuthService.php** — `checkRateLimit()` 使用正确配置键；`login()` 密码过期检查使用正确配置键；`register()` 调用 `validatePasswordComplexity()` 校验密码复杂度
3. **Requests/LoginRequest.php** — 密码长度校验 `min:8`
4. **Requests/RegisterRequest.php** — 密码长度校验从 `min:6` 提升至 `min:8`
5. **Enums/AuthErrorCode.php** — 新增 `TooManyAttempts` 错误码，与账号锁定区分
6. **Services/AuthService.php** — `checkRateLimit()` 使用 `TooManyAttempts` 错误码

---

## 五、免责声明

本扩展包在代码层面实现了认证模块的合规基础能力，但不构成法律建议。使用方应：

1. 根据自身安全需求配置密码策略和登录安全参数
2. 生产环境启用 HTTPS 并配置 HSTS
3. 定期进行安全渗透测试，确保认证模块安全
4. 咨询专业安全顾问和法律顾问，确保系统整体合规