# Smail 超级管理员重置与邮箱验证码实施任务清单

## 1. 文档信息

| 项目 | 内容 |
|---|---|
| 文档名称 | Smail 超级管理员重置与邮箱验证码实施任务清单 |
| 文档状态 | 待执行 |
| 当前版本 | 0.3 |
| 编写日期 | 2026-08-25 |
| 需求依据 | `docs/超级管理员重置与邮箱验证码需求文档.md` 0.3 |
| 关联文档 | `docs/配置系统重构需求文档.md`、`docs/配置系统重构技术设计.md`、`docs/配置系统重构实施任务清单.md` |
| 适用目录 | `server`、`frontend`、`docs` 及后续安装脚本目录 |
| 任务总数 | 66 |

本文档用于把超级管理员部署端重置、外部邮箱验证码、登录二次验证和分角色密码恢复拆分为可实施、可测试、可复审、可追踪的任务。本文档只建立执行计划，不代表任何功能已经实现。

---

## 2. 状态、优先级和执行规则

### 2.1 状态枚举

| 状态 | 含义 |
|---|---|
| 未开始 | 尚未进入实施 |
| 进行中 | 正在设计、编码或验证 |
| 待复审 | 实施和自测完成，等待独立复审 |
| 已完成 | 验收标准全部满足且证据完整 |
| 阻塞 | 前置决定、外部环境或安全条件未满足 |

### 2.2 优先级

| 优先级 | 含义 |
|---|---|
| P0 | 安全边界、产品冲突或后续任务的强制前置条件 |
| P1 | 核心功能，未完成时不得进入本轮验收 |
| P2 | 体验、可观测性或运维完整性增强 |

### 2.3 完成标记规则

任务从“未开始”或“进行中”改为“已完成”前，必须同时满足：

1. 前置依赖全部完成；
2. 实施步骤和安全要求全部落实；
3. 自动化测试通过，未跳过失败用例；
4. 涉及页面的任务完成真实浏览器验证；
5. 涉及 Linux 或 Windows 的任务在对应真实平台验证；
6. 验收证据包含命令、结果、关键文件和必要截图；
7. 完成独立安全复审，由“待复审”更新为“已完成”；
8. 未经用户同意不得删除旧文件、数据库列、配置或接口。

### 2.4 全局安全限制

1. 不使用 Docker；
2. 密码、验证码、验证码校验值、进程临时密钥、维护凭据、恢复授权、恢复码和 WebAuthn 私密数据不得进入日志；
3. 验证码任务及其 HMAC 校验值不得进入数据库、文件、Redis、消息队列、指标、追踪、审计详情或备份；
4. `smail-admin` 不读取数据库凭据、配置主密钥，不构造 DSN，不直接修改数据库；
5. 超级管理员自身密码不得通过普通 Web 页面、HTTP API、localhost TCP、公网或局域网 TCP 重置；
6. Linux 只允许 Unix Domain Socket，Windows 只允许 Named Pipe 作为部署端控制通道；
7. 密码统一使用主程序内经过评审的密码策略和 Argon2id 服务，不保留旧算法回退；
8. 邮箱验证码不能单独批准数据库迁移、配置回滚、角色变更、重置其他用户密码等高风险操作；
9. 功能关闭、SMTP 投递失败、服务重启或数据异常时必须安全拒绝，不允许降级绕过；
10. 中文文档、注释、说明和界面文字使用中文，代码标识符使用简洁英文；
11. 文本文件保持 UTF-8 无 BOM；
12. 提交和推送不属于本清单默认动作，需要用户另行指示。

### 2.5 跨文档依赖与任务归属

本清单使用 `AD-001`～`AD-066` 作为超级管理员重置与邮箱验证码详细子任务；`docs/配置系统重构实施任务清单.md` 使用 `CG-001`～`CG-057` 作为总体父任务。执行规则如下：

1. 标记为“基础”的 CG 任务完成后，对应 AD 详细实现才能开始；
2. 标记为“聚合”的 CG 任务只有在对应 AD 子任务完成并具备验收证据后才能标记完成；
3. 状态记录、提交说明、测试报告和验收证据必须使用完整任务编号；
4. 两份清单出现边界不一致时，以已确认需求和技术设计为准，并先修正文档，不得通过代码自行选择较弱边界。

| CG 任务 | 关系 | AD 详细任务 |
|---|---|---|
| CG-029 统一密码服务 | 基础 | AD-016 密码策略接入，之后进入 AD-017～AD-021 重置事务与权限 |
| CG-022 SMTP 和邮箱策略 | 基础 | AD-032～AD-038 |
| CG-027～CG-028 登录认证 | 基础 | AD-039～AD-042、AD-050、AD-052 |
| CG-038～CG-039 恢复流程 | 基础 | AD-043～AD-047、AD-050、AD-053 |
| CG-030 跨用户密码重置 | 聚合 | AD-021、AD-051、AD-055～AD-059 |
| CG-031 部署端重置通道 | 聚合 | AD-006～AD-020、AD-062～AD-063 |
| CG-032 通用账户恢复迁移基础 | 基础 | AD-022～AD-025、AD-035～AD-037 |
| CG-040～CG-045 API 和页面 | 聚合 | AD-048～AD-059、AD-064 |
| CG-048 V1 路由和通用请求守卫 | 基础 | AD-048～AD-051 |
| CG-051 平台部署验证 | 聚合 | AD-011、AD-015 |
| CG-052 完整自动化回归 | 聚合 | AD-060～AD-064 |
| CG-053～CG-056 安全复审 | 基础 | AD-066 最终发布评审 |
| CG-057 最终验收 | 聚合 | AD-066 的聚合验收证据 |

---

## 3. 已确认实施基线

以下实施基线已经确认，后续任务不得重新引入旧冲突：

1. **正式开发范围**：完整实现验证码服务、SMTP 投递、登录邮箱二次验证、外部邮箱密码恢复、外部邮箱管理页面、运营数据和定期清理；
2. **Linux 正式入口**：唯一可写入口为 `systemctl start smail-admin`；`smail-admin` 是执行一次受控重置事务后退出的短时服务，不是常驻网络服务；
3. **安全密码交互**：使用 `systemd-ask-password` 或等效短时受保护本机凭据交互；无可用密码代理时安全拒绝，禁止参数、环境变量、文件、日志、标准输入和标准输出传递密码；
4. **权限矩阵**：超级管理员可重置管理员和普通用户，管理员只可重置普通用户，普通用户仅可重置本人，部署端 `smail-admin` 只可重置超级管理员自身；
5. **源码入口**：独立程序入口固定为 `backend/cmd/smail-admin/main.go`；
6. **持久化边界**：验证码及校验值只存在于签发认证进程内存；非敏感运营数据允许持久化并每 14 天执行一次清理；
7. **验收边界**：systemd 安全交互、本机 IPC、Windows/Ubuntu 适配、三数据库、真实浏览器和安全负向测试均未完成前不得最终验收。

---

## 4. 总体进度

| 阶段 | 任务范围 | 状态 | 完成数/总数 |
|---|---|---|---:|
| 第一阶段 | 产品决定、安全基线和测试基线 | 进行中 | 3/5 |
| 第二阶段 | `smail-admin` 构建、安装和升级 | 未开始 | 0/6 |
| 第三阶段 | Linux/Windows 本机 IPC 与重置会话 | 未开始 | 0/4 |
| 第四阶段 | 超级管理员重置事务与凭据撤销 | 未开始 | 0/6 |
| 第五阶段 | 外部邮箱模型和数据保护 | 未开始 | 0/4 |
| 第六阶段 | 仅内存验证码服务 | 未开始 | 0/6 |
| 第七阶段 | SMTP Relay、限流和定期清理 | 未开始 | 0/7 |
| 第八阶段 | 登录二次验证和分角色恢复 | 未开始 | 0/9 |
| 第九阶段 | 后端 API 和授权边界 | 未开始 | 0/4 |
| 第十阶段 | 前端页面和交互 | 未开始 | 0/5 |
| 第十一阶段 | 审计、监控和告警 | 未开始 | 0/3 |
| 第十二阶段 | 跨平台测试、安全复审和发布验收 | 未开始 | 0/7 |
| **合计** |  | **进行中** | **3/66** |

---

## 5. 第一阶段：产品决定、安全基线和测试基线

### AD-001 统一超级管理员重置入口和进程模型

- **状态**：已完成
- **优先级**：P0
- **依赖**：无
- **需求映射**：第 6、7、8、13.4、22.2、24 章
- **修改范围**：三份配置系统重构文档、本需求文档、本清单
- **实施步骤**：固定 Linux 正式命令为 `systemctl start smail-admin`；确定 `smail-admin` 为短时一次性 systemd 服务；使用 `systemd-ask-password` 或等效安全交互；Windows 使用等价服务启动语义；修正全部冲突文本。
- **安全要求**：新密码不得通过参数、环境变量、配置文件、普通文件、服务名、日志或标准输出传递；不得为了兼容同时保留多个可写重置入口。
- **测试要求**：对最终命令执行威胁建模和可操作性演练，验证无回显输入、超时、退出和失败回传。
- **验收标准**：全部文档只保留一个正式可写入口，辅助命令仅限只读；交互机制在 Ubuntu 22.04、Ubuntu 24.04 和 Windows 上可实现。
- **回退方式**：仅回退文档决定，不进入代码实现。
- **验收证据**：五份文档已统一正式命令、短时服务模型、安全密码交互和跨平台边界；2026-08-25 文档复审通过。

### AD-002 冻结角色权限和密码恢复矩阵

- **状态**：已完成
- **优先级**：P0
- **依赖**：无
- **需求映射**：第 5、9、13、20.3、24 章
- **修改范围**：需求、技术设计、任务清单和权限矩阵
- **实施步骤**：冻结权限矩阵：超级管理员重置管理员和普通用户，管理员重置普通用户，普通用户仅重置本人，部署端只重置超级管理员自身；确认跨用户强制重置后的凭据撤销范围。
- **安全要求**：超级管理员自身只允许部署端重置；管理员不得重置管理员或超级管理员；邮箱验证码不能提升角色或单独批准高风险操作。
- **测试要求**：建立角色×目标角色×恢复方式×操作结果的决策表和拒绝用例。
- **验收标准**：后端、前端、测试和文档使用同一权限矩阵，无互相矛盾条目。
- **回退方式**：默认拒绝未确认能力。
- **验收证据**：两份需求、技术设计和两份清单使用同一权限矩阵；2026-08-25 文档复审通过。

### AD-003 完成威胁模型和敏感数据流设计

- **状态**：已完成，等待复审
- **优先级**：P0
- **依赖**：AD-001、AD-002、CG-001
- **需求映射**：第 3、8、14、15、20、22.4 章
- **修改范围**：`docs` 安全设计、`server` 认证与 IPC 设计
- **实施步骤**：绘制部署端重置、验证码签发、SMTP 投递、验证消费、登录二次验证和密码恢复的数据流；标记信任边界、进程边界、持久化点和攻击面。
- **安全要求**：覆盖本机提权、IPC 冒用、重放、账号枚举、验证码暴力破解、内存耗尽、SMTP 泄露、日志泄露和并发双花。
- **测试要求**：为每项威胁建立对应控制措施和至少一个负向测试。
- **验收标准**：不存在未说明的敏感数据持久化点或网络重置入口。
- **回退方式**：默认关闭相关能力。
- **验收证据**：已新增 `docs/安全威胁模型与敏感数据流设计.md`，完成信任边界、敏感数据生命周期、持久化点、18 项威胁控制措施和负向测试映射；已核对文档引用的测试名称，verification、recovery、credentials、externalemail、adminreset、webauthn、controllers 和 config 相关测试通过；真实 Ubuntu、Windows、SMTP Relay、全局日志哨兵和多实例部署仍由后续任务验收。

### AD-004 建立敏感字段、日志和持久化禁止清单

- **状态**：`[x] 已完成，等待复审`
- **优先级**：P0
- **依赖**：AD-003
- **需求映射**：第 8.5、13.5、15、18.4、19、21 章
- **修改范围**：日志中间件、审计 DTO、指标标签、追踪字段、错误模型和测试
- **实施步骤**：登记密码、验证码、HMAC 校验值、进程临时密钥、维护凭据、恢复授权、完整外部邮箱和凭据材料；建立统一脱敏与拒绝序列化规则。
- **安全要求**：验证码及校验数据不能以明文、密文、摘要或 HMAC 形式进入持久化介质；完整邮箱默认只返回脱敏值。
- **测试要求**：扫描日志、数据库、配置、缓存、队列、指标、追踪和备份；加入敏感词哨兵测试。
- **验收标准**：所有敏感类型都有禁止边界、代码守卫和自动化泄露测试。
- **回退方式**：关闭对应功能并保留拒绝日志，不输出敏感详情。
- **验收证据**：已扩展敏感字段目录并明确密码、验证码、校验数据、临时密钥、恢复授权、外部邮箱和凭据材料的禁止边界；已建立 `encrypted_only`、`reference_only`、`memory_only`、`hashed_only` 四类策略和公共脱敏能力；配置审计导出、配置授权错误和配置管理接口已补充敏感输出测试，错误响应不回显内部错误文本；定向测试、全量 `go test ./...`、`go vet ./...` 和 `git diff --check` 通过。全局日志、指标、追踪、缓存、队列和错误报告的生产哨兵仍未完整覆盖，真实 SMTP、平台 IPC、多实例和多数据库仍待验收。

### AD-005 建立需求追踪和测试矩阵

- **状态**：`[x] 已完成，等待复审`
- **优先级**：P0
- **依赖**：AD-001、AD-002、AD-003
- **需求映射**：第 21、22、24 章
- **修改范围**：`server` 测试、`frontend` 测试、跨平台测试说明、CI
- **实施步骤**：把需求条款映射到单元、集成、并发、故障注入、浏览器、安装升级和跨平台测试；标记 MySQL、PostgreSQL、SQLite 覆盖范围。
- **安全要求**：不得以手工说明代替可自动化的关键安全测试；平台缺口必须阻塞验收。
- **测试要求**：检查每条验收项和 17 条阻塞条件至少映射一个测试或人工审计步骤。
- **验收标准**：测试矩阵完整、可追踪、无孤立需求和无来源测试。
- **回退方式**：缺少覆盖的能力保持关闭。
- **验收证据**：已新增 `docs/超级管理员重置与邮箱验证码测试矩阵.md`，把 AD-001～AD-066 映射到单元、并发、协议、数据库、浏览器、安装升级和跨平台检查；明确 SQLite 自动化结果以及 MySQL、PostgreSQL、Ubuntu 22.04/24.04、Windows 生产服务、真实 SMTP 和真实浏览器的未验证边界。关键负向场景覆盖 nonce 重放、密码参数、验证码降级、并发双花、超级管理员 Web 恢复和敏感数据泄露；发布前仍需补齐真实环境证据。

### 第一阶段验收

- [ ] 重置命令、进程模型和无回显交互方式已经统一；
- [ ] 三级角色重置权限无冲突；
- [ ] 第 24 章未确认项全部关闭或明确阻塞；
- [ ] 威胁模型和敏感数据清单通过安全评审；
- [ ] 测试矩阵覆盖全部验收与阻塞条件。

---

## 6. 第二阶段：`smail-admin` 构建、安装和升级

### AD-006 创建独立管理程序入口和构建目标

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-001
- **需求映射**：第 3.1、6.1、22.1 章
- **修改范围**：`backend/cmd/smail/main.go`、固定入口 `backend/cmd/smail-admin/main.go`、构建配置
- **实施步骤**：将主服务入口和管理程序入口分离；输出 `smail`、`smail-admin` 及 Windows 对应程序；共享版本信息但不共享不必要初始化逻辑。
- **安全要求**：`smail-admin` 不加载插件、HTTP 服务、邮件监听器、数据库配置或主密钥。
- **测试要求**：独立构建、依赖检查、启动副作用检查和二进制符号检查。
- **验收标准**：两个程序可独立构建，管理程序最小化启动且无网络监听。
- **回退方式**：不发布管理程序，保持重置能力关闭。
- **验收证据**：待补充。

### AD-007 实现只读辅助命令和严格命令解析

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-006、AD-001
- **需求映射**：第 8.1 章
- **修改范围**：`backend/cmd/smail-admin` 命令解析和测试
- **实施步骤**：只实现 `version`、`doctor` 等只读辅助命令；正式重置只能由 `systemctl start smail-admin` 触发；未知参数和任何密码参数均拒绝；输出稳定退出码。
- **安全要求**：禁止 `--password`、环境变量密码、脚本化明文标准输入和调试泄露。
- **测试要求**：参数模糊测试、危险参数负向测试、退出码和帮助文本测试。
- **验收标准**：只有 systemd 或 Windows 等价服务启动语义可进入重置流程，辅助命令仅只读且不修改状态。
- **回退方式**：只保留 `version` 和 `doctor`。
- **验收证据**：待补充。

### AD-008 实现部署管理员身份与安全密码代理检查

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-007
- **需求映射**：第 6.3、8.2、8.5、20.1 章
- **修改范围**：管理程序平台适配、安全密码代理组件和测试
- **实施步骤**：Linux 验证 systemd 启动上下文和有效 UID，调用 `systemd-ask-password` 或等效受保护密码代理完成两次不回显输入；Windows 验证 Administrators/SYSTEM 令牌并使用等价受保护交互；使用后及时清理内存。
- **安全要求**：非管理员、密码代理不可用、输入不一致、取消、超时和交互状态异常均安全拒绝，禁止降级读取标准输入、环境变量或文件。
- **测试要求**：普通用户、提权用户、无密码代理、重定向输入、取消、超时和异常退出测试。
- **验收标准**：密码不显示、不落盘、不进入标准输入输出、进程参数和环境变量，密码代理异常时拒绝执行。
- **回退方式**：拒绝执行重置。
- **验收证据**：待补充。

### AD-009 实现 Linux 安装和 systemd 集成

- **状态**：`[~] 进行中`
- **优先级**：P1
- **依赖**：AD-006、AD-001
- **需求映射**：第 6.2、6.3、7、22.1 章
- **修改范围**：Linux 安装脚本、systemd unit、目录权限说明
- **实施步骤**：安装两个程序；注册 `smail` 主服务和短时 `smail-admin` systemd 服务；固定 `systemctl start smail-admin` 为唯一进入重置流程的启动动作，`systemctl stop smail-admin` 只终止事务；配置 `systemd-ask-password` 安全交互；创建 `/run/smail` 运行目录；设置所有者和最小权限；安装和升级时清理历史启用关系。
- **安全要求**：禁止 setuid；普通 `smail` 运行用户不得执行管理程序；`smail-admin` 单元不得包含 `[Install]` 或自动重启策略；安装不得 enable、preset、start 或 restart 管理服务；管理程序必须校验 systemd 调用上下文和当前 Job 类型，拒绝 `restart`、`try-restart`、`reload`、依赖拉起及其他非显式 `start` 动作进入重置流程。
- **测试要求**：Ubuntu 22.04/24.04 安装、权限、重装、卸载边界、无开机自启动、显式 start、stop、restart、try-restart、reload、依赖拉起、只读 status/show/is-active 和服务启动测试。
- **验收标准**：主服务可由 systemctl 管理；管理程序只能由部署管理员通过显式 `systemctl start smail-admin` 触发，`stop` 只终止事务，其他动作不能开启重置；事务后退出且无常驻网络端口。
- **回退方式**：移除新增 unit 或入口，不删除已有配置和数据。
- **验收证据**：已新增无 `[Install]`、`Restart=no`、网络隔离和仅允许 `AF_UNIX` 的 oneshot unit；安装脚本不启用或启动管理服务，并清理历史 enable 关系；管理程序校验 root、PID 1、systemd invocation 和显式 start Job；Go 定向策略测试已通过。
- `[x] 已完成，等待复审`：systemd 单元禁止开机自启动、自动重启和 reload。
- `[x] 已完成，等待复审`：安装脚本禁止自动启动并清理历史 enable 关系。
- `[x] 已完成，等待复审`：管理程序拒绝 restart、try-restart、stop 和非 systemd 启动进入重置流程。
- `[!] 暂缓或存在阻塞`：尚未在 Ubuntu 22.04 和 Ubuntu 24.04 真实 systemd 环境验证 `list-jobs` 在 oneshot `ExecStart` 期间的 Job 类型和生命周期，未验证前不得标记复审通过。

### AD-010 实现 Windows 安装、服务和 ACL

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-006、AD-001
- **需求映射**：第 6.3、21.2、22.1 章
- **修改范围**：Windows 安装脚本、Service 配置、ACL 设置和测试
- **实施步骤**：安装两个 EXE；注册主服务；限制 `smail-admin.exe` 仅 Administrators 和 SYSTEM 执行；配置 Named Pipe 所需运行权限。
- **安全要求**：普通用户和 Smail 服务账户不得替换、修改或执行管理程序；安装不得自动开启通道。
- **测试要求**：管理员、普通用户、服务账户、升级、ACL 继承和路径含空格测试。
- **验收标准**：Windows 权限边界与 Linux 等价，错误 ACL 时拒绝运行。
- **回退方式**：恢复安装前 ACL 和服务定义，不删除配置数据。
- **验收证据**：待补充。

### AD-011 实现版本绑定和原子升级

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-009、AD-010
- **需求映射**：第 6.3、8.2、20.1、22.1 章
- **修改范围**：发布元数据、安装升级流程、IPC 握手字段和测试
- **实施步骤**：为两个程序写入一致版本和协议版本；安装前校验；原子替换；任一失败回滚整个程序对；主程序握手时拒绝不兼容管理程序。
- **安全要求**：禁止半升级状态继续执行重置；版本不兼容不得降级为直连数据库。
- **测试要求**：升级中断、磁盘不足、单文件替换失败、旧客户端连接新服务和新客户端连接旧服务测试。
- **验收标准**：任何失败后两个程序仍为同一兼容版本，重置入口默认关闭。
- **回退方式**：原子恢复上一对已验证程序。
- **验收证据**：待补充。

### 第二阶段验收

- [ ] 两个程序独立构建且版本一致；
- [ ] 管理程序不加载数据库、插件、HTTP 和邮件服务；
- [ ] Linux 和 Windows 安装权限正确；
- [ ] 安装、升级和回滚不会自动开启重置通道；
- [ ] 管理程序密码输入不落盘、不回显。

---

## 7. 第三阶段：Linux/Windows 本机 IPC 与重置会话

### AD-012 定义最小化本机控制协议

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-003、AD-006
- **需求映射**：第 8.2、8.3、8.4 章
- **修改范围**：`server` 本机控制协议、消息类型、版本和测试
- **实施步骤**：定义握手、健康检查、创建会话、提交新密码、消费结果和关闭消息；设置固定类型、字段白名单、长度上限、超时和协议版本。
- **安全要求**：协议不得携带数据库凭据或主密钥；拒绝未知消息、超长帧、重复字段、协议降级和跨版本调用。
- **测试要求**：协议模糊测试、截断帧、超长帧、乱序、重放和版本不匹配测试。
- **验收标准**：协议最小、可审计、无通用命令执行和任意文件访问能力。
- **回退方式**：关闭控制通道。
- **验收证据**：待补充。

### AD-013 实现 Linux Unix Domain Socket 适配器

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-012、AD-015、AD-009
- **需求映射**：第 3.1、8.3、21.2、22.2 章
- **修改范围**：建议 `backend/internal/adminipc` Linux 适配、运行目录和测试
- **实施步骤**：使用 `/run/smail/admin-control.sock`；安全创建和清理 socket；验证目录、所有者、模式和对端 UID/进程凭据；拒绝符号链接和非常规文件。
- **安全要求**：权限位不能替代服务端对端身份验证；不得监听 TCP 或注册 HTTP Router。
- **测试要求**：root、普通用户、Smail 用户、错误所有者、socket 抢占、符号链接、主程序重启和并发连接测试。
- **验收标准**：只有受信部署管理员可建立连接，TCP 扫描无重置端口。
- **回退方式**：删除本次创建的运行时 socket，不删除安装和数据文件。
- **验收证据**：待补充。

### AD-014 实现 Windows Named Pipe 适配器

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-012、AD-015、AD-010
- **需求映射**：第 3.1、8.3、21.2、22.2 章
- **修改范围**：建议 `backend/internal/adminipc` Windows 适配、ACL 和测试
- **实施步骤**：使用 `\\.\pipe\smail-admin-control`；设置仅 Administrators/SYSTEM 的 ACL；服务端模拟客户端并验证访问令牌、管理员组和会话身份。
- **安全要求**：ACL 不能替代服务端令牌验证；拒绝远程管道、普通用户、Smail 服务账户和匿名身份。
- **测试要求**：管理员、UAC 非提权令牌、普通用户、SYSTEM、服务账户、ACL 篡改和并发客户端测试。
- **验收标准**：只有已提升的本机管理员或 SYSTEM 可连接，不存在 TCP 替代路径。
- **回退方式**：关闭并销毁 Named Pipe 实例。
- **验收证据**：待补充。

### AD-015 实现短时一次性重置会话状态机

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-012
- **需求映射**：第 8.4、21.1、22.2、22.4 章
- **修改范围**：主程序重置会话管理、维护凭据校验和并发测试
- **实施步骤**：实现 `closed → open → consumed/expired`；单实例同时只允许一个会话；绑定目标、用途、主程序实例和管理程序实例；默认五分钟；失败阈值、断开和进程退出立即失效。
- **安全要求**：维护凭据使用安全随机源且只保留不可逆校验值；消费前原子标记；终态不可恢复；不得跨进程、用户、环境或主机复用。
- **测试要求**：过期、断开、主程序重启、管理程序退出、并发消费、重复提交、实例切换和失败阈值测试。
- **验收标准**：并发最多一次成功，任何重启后未完成会话全部失效。
- **回退方式**：关闭会话并清除内存状态。
- **验收证据**：待补充。

### 第三阶段验收

- [ ] Linux Unix Domain Socket 和 Windows Named Pipe 均完成真实平台验证；
- [ ] 服务端验证调用者系统身份；
- [ ] 普通用户、Smail 用户、插件和 HTTP Router 均不能调用；
- [ ] 无 TCP 监听、无通用命令执行能力；
- [ ] 重置会话短时、一次性、不可重放且进程退出即失效。
---

## 8. 第四阶段：超级管理员重置事务与凭据撤销

### AD-016 复用统一密码策略和 Argon2id 服务

- **状态**：未开始
- **优先级**：P0
- **依赖**：CG-029、AD-003
- **需求映射**：第 3.1、8.5、8.6、22.2 章
- **修改范围**：`backend/utils/password`、认证服务、管理控制服务和测试
- **实施步骤**：抽取主程序统一密码校验、策略检查和 Argon2id 哈希接口；本机控制服务只调用该接口；统一 Web、管理员强制重置和部署端重置的密码验证结果。
- **安全要求**：不保留旧算法、弱算法或失败后的兼容回退；管理程序不得自行哈希。
- **测试要求**：密码长度、复杂度、拒绝列表、Argon2id 参数、错误处理和跨入口一致性测试。
- **验收标准**：所有密码修改入口使用同一服务和参数，仓库中不存在第二套重置哈希实现。
- **回退方式**：关闭新重置入口，不降低密码算法。
- **验收证据**：待补充。

### AD-017 实现超级管理员目标校验和事务更新

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-015、AD-016
- **需求映射**：第 8.2、8.6、8.7 章
- **修改范围**：用户仓储、认证服务、数据库事务和测试
- **实施步骤**：验证系统已完成最低初始化；查询唯一目标；确认角色为 `super_admin`；在数据库事务中更新密码哈希、密码时间和版本字段。
- **安全要求**：管理程序不直接访问数据库；目标不存在、角色不符、多个超级管理员冲突或数据库异常均拒绝。
- **测试要求**：三种数据库上的正常、目标缺失、角色错误、事务回滚、并发变更和数据库断开测试。
- **验收标准**：只有主程序能完成目标校验和原子密码更新。
- **回退方式**：事务回滚，不保留部分变更。
- **验收证据**：待补充。

### AD-018 原子撤销超级管理员全部安全凭据

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-017
- **需求映射**：第 8.7、22.2、22.4 章
- **修改范围**：Session、WebAuthn、离线恢复码、受信设备、恢复流程和票据服务
- **实施步骤**：递增 Session、Security、Credential 版本；撤销全部 Session、WebAuthn、恢复码、受信设备、长期登录状态和未完成票据；设置下次登录安全检查标记。
- **安全要求**：密码更新与凭据撤销必须处于同一原子业务事务或具备可证明的失败补偿；任何撤销失败不得返回成功。
- **测试要求**：逐项故障注入、并发 Session 使用、旧 WebAuthn、旧恢复码、旧票据和跨设备测试。
- **验收标准**：重置成功后所有旧凭据立即不可用，不存在部分撤销状态。
- **回退方式**：数据库事务回滚；若外部动作已发生，保持更安全的撤销状态并告警。
- **验收证据**：待补充。

### AD-019 实现部署端重置通知和安全审计

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-018、AD-057
- **需求映射**：第 8.7、19 章
- **修改范围**：安全通知、审计服务、管理程序脱敏输出和测试
- **实施步骤**：记录目标 ID、程序版本、平台、调用者系统身份摘要、通道时间、结果和撤销范围；向已验证外部邮箱发送通知；销毁会话。
- **安全要求**：审计不记录密码、维护凭据、完整邮箱和恢复材料；通知失败不恢复旧密码或旧凭据。
- **测试要求**：通知成功、投递失败、审计失败、脱敏输出和会话销毁测试。
- **验收标准**：成功与失败均有可追踪脱敏审计，通知失败产生告警且不破坏已完成事务。
- **回退方式**：保留安全变更，重试通知和审计补偿，不恢复旧凭据。
- **验收证据**：待补充。

### AD-020 清除超级管理员普通 Web 重置路径

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-002
- **需求映射**：第 3.2、5.1、13.4、17、18.2、20.1 章
- **修改范围**：`backend/controllers`、HTTP Router、`frontend` 登录和安全页面、测试
- **实施步骤**：公共恢复流程识别超级管理员后统一拒绝创建任务；禁止 Web 修改超级管理员密码；确认未注册需求列出的三个禁止接口；前端不展示可用恢复入口。
- **安全要求**：不能只靠前端隐藏；响应不得泄露账号存在、角色和恢复方式。
- **测试要求**：路由枚举、直接 API 调用、角色篡改、localhost 请求、存在与不存在账号响应一致性测试。
- **验收标准**：普通 HTTP Router 无任何超级管理员自身密码重置或开启本机通道的能力。
- **回退方式**：保持 Web 入口关闭。
- **验收证据**：待补充。

### AD-021 实现分角色跨用户强制重置

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-002、AD-016、AD-018、CG-025
- **需求映射**：第 9、17、20.3、21.4 章
- **修改范围**：用户管理服务、能力校验、临时密码、前后端和测试
- **实施步骤**：验证操作者能力和近期重新认证或 WebAuthn；超级管理员允许目标为管理员或普通用户，管理员仅允许目标为普通用户；展示目标用户名、主邮箱和角色；拒绝超级管理员目标；生成一次性临时密码；设置强制改密；撤销目标全部安全凭据并通知。
- **安全要求**：临时密码使用安全随机源且只显示一次；操作者不能指定弱密码；不得用邮箱验证码单独批准操作。
- **测试要求**：越权、目标角色、近期认证过期、临时密码一次展示、凭据撤销、通知失败和审计测试。
- **验收标准**：超级管理员可安全重置管理员和普通用户，管理员可安全重置普通用户，普通用户不能调用跨用户入口，超级管理员不能通过该入口重置自己或其他超级管理员。
- **回退方式**：关闭管理后台重置入口，不恢复已撤销凭据。
- **验收证据**：待补充。

### 第四阶段验收

- [ ] 部署端重置只通过主程序统一密码服务和数据库事务完成；
- [ ] 重置后 Session、WebAuthn、离线恢复码、受信设备和票据全部撤销；
- [ ] 超级管理员不存在普通 Web 修改或恢复路径；
- [ ] 强制重置其他用户符合最终角色矩阵和近期认证要求；
- [ ] 通知与审计不泄露敏感数据。

---

## 9. 第五阶段：外部邮箱模型和数据保护

### AD-022 建立外部邮箱数据模型和三数据库迁移

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-002、AD-004、CG-032
- **需求映射**：第 11、15.3 章
- **修改范围**：`backend/models`、迁移、仓储及 MySQL/PostgreSQL/SQLite 测试
- **实施步骤**：保存邮箱密文、邮箱指纹、验证时间、状态、类型和凭据版本；支持主要与备用邮箱；建立用户归属和数量约束。
- **安全要求**：不得保存验证码任务；不得用明文邮箱建立索引；数据库约束与服务端校验同时存在。
- **测试要求**：三数据库迁移、回滚、唯一性、并发绑定、数量上限和异常数据测试。
- **验收标准**：数据模型在三种数据库一致工作，不产生部分绑定状态。
- **回退方式**：停止新写入并保留已迁移数据，不擅自删除列或表。
- **验收证据**：待补充。

### AD-023 实现外部邮箱认证加密和独立指纹

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-022
- **需求映射**：第 15.3、21.3 章
- **修改范围**：凭据保险库、邮箱加密服务、密钥版本和测试
- **实施步骤**：使用随机 nonce 的认证加密保存完整邮箱；使用独立索引密钥计算 HMAC 指纹；实现密钥版本、解密和脱敏输出。
- **安全要求**：索引密钥与加密密钥用途分离；主密钥不与密文存放在同一数据库；篡改时拒绝解密和发送。
- **测试要求**：随机性、相同邮箱指纹稳定性、密文不同性、篡改、错误密钥、密钥版本和日志泄露测试。
- **验收标准**：数据库和 API 不暴露完整邮箱，发送时才短时解密。
- **回退方式**：禁止发送和修改，保留密文，不回退到明文。
- **验收证据**：待补充。

### AD-024 实现归属校验、规范化和脱敏查询

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-023
- **需求映射**：第 5、11.2、17、18.3 章
- **修改范围**：账户安全服务、DTO、仓储和测试
- **实施步骤**：统一邮箱规范化；拒绝与当前 Smail 主邮箱相同；用户只能管理自己；API 默认返回脱敏邮箱、状态和最近发送时间。
- **安全要求**：超级管理员也不能查看完整邮箱；管理员不能查询其他用户邮箱；错误响应不得泄露绑定情况。
- **测试要求**：对象级越权、大小写和 Unicode 规范化、主邮箱冲突、脱敏格式和枚举测试。
- **验收标准**：所有查询和写入都执行后端归属校验，无 IDOR。
- **回退方式**：关闭外部邮箱管理接口。
- **验收证据**：待补充。

### AD-025 实现绑定、更换、删除和关联事务失效

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-024、AD-030
- **需求映射**：第 11.2、11.3 章
- **修改范围**：账户安全服务、验证码服务、恢复事务和通知
- **实施步骤**：绑定前近期重新认证并验证目标邮箱；验证成功后原子保存；更换时原子替换并通知旧邮箱；删除或更换后失效旧邮箱验证码、恢复流程和登录二次验证事务。
- **安全要求**：未验证邮箱不能用于登录、恢复或通知；超级管理员不能替用户直接设置未经验证邮箱。
- **测试要求**：绑定失败不留部分状态、更换并发、旧验证码、旧恢复流程、通知失败和事务回滚测试。
- **验收标准**：邮箱生命周期和关联安全事务始终一致。
- **回退方式**：事务回滚到原绑定状态，不保留未经验证记录。
- **验收证据**：待补充。

### 第五阶段验收

- [ ] 外部邮箱密文和指纹用途分离；
- [ ] MySQL、PostgreSQL、SQLite 迁移通过；
- [ ] 用户只能管理自己的主要和备用邮箱；
- [ ] 未验证邮箱不能用于任何认证或通知；
- [ ] 更换、删除会原子失效所有旧邮箱关联事务。

---

## 10. 第六阶段：仅内存验证码服务

### AD-026 生成并隔离进程临时 HMAC 密钥

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-004
- **需求映射**：第 15.1、21.3、22.4 章
- **修改范围**：认证进程启动、验证码内存服务和测试
- **实施步骤**：每次认证进程启动使用操作系统安全随机源生成至少 256 位临时密钥；只保存在进程内存；为密钥访问建立不可导出接口。
- **安全要求**：不得写入数据库、文件、配置、环境变量、日志、诊断、指标或插件接口；进程退出立即失效。
- **测试要求**：重启密钥变化、序列化拒绝、诊断和日志扫描、插件不可访问、随机源失败安全拒绝测试。
- **验收标准**：无任何持久化或导出路径，随机源失败时验证码服务保持关闭。
- **回退方式**：关闭验证码功能。
- **验收证据**：待补充。

### AD-027 实现有容量上限的内存任务仓库

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-026
- **需求映射**：第 14.2、15.1、21.3 章
- **修改范围**：建议 `backend/services/verification` 内存仓库、索引和测试
- **实施步骤**：保存需求定义字段；按用户、用途和任务 ID 建立受控索引；设置全局容量、每用户容量和内存预算；达到上限安全拒绝。
- **安全要求**：任务只存在于签发实例；不得为每个任务创建无限 goroutine；内存转储风险纳入运维控制。
- **测试要求**：容量边界、并发创建、索引一致性、内存增长、随机淘汰禁止和压力测试。
- **验收标准**：达到上限不会无限增长、覆盖有效任务或绕过验证。
- **回退方式**：拒绝新任务并告警，保留已有有效任务至到期。
- **验收证据**：待补充。

### AD-028 实现安全验证码生成和 HMAC 校验值

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-027
- **需求映射**：第 14、15.1 章
- **修改范围**：验证码生成、邮件载荷构建、HMAC 校验和测试
- **实施步骤**：默认生成八位数字；任务 ID 至少 128 位；HMAC-SHA-256 绑定任务 ID、用户 ID、用途、邮箱指纹和验证码；投递后尽最大努力覆盖明文缓冲区。
- **安全要求**：禁止时间戳、递增序列和普通伪随机数；明文只在生成、邮件构建、SMTP 交付和计算校验值阶段短暂存在。
- **测试要求**：随机分布基本检查、绑定字段变更、缓冲生命周期、日志哨兵和错误随机源测试。
- **验收标准**：内存任务只保存 HMAC 校验值，不保存验证码明文或可逆密文。
- **回退方式**：停止签发验证码。
- **验收证据**：待补充。

### AD-029 实现签发、重发和用途绑定

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-028、AD-035、AD-033
- **需求映射**：第 10、14.1、14.2 章
- **修改范围**：验证码编排服务、用途策略和测试
- **实施步骤**：支持四种正式用途；拒绝 `sensitive_operation`；同用户同用途只保留最新任务；重发时原子删除旧任务；绑定请求上下文和凭据版本。
- **安全要求**：不同用户、用途、邮箱、环境和浏览器事务不得复用；未知角色和用途默认拒绝。
- **测试要求**：四用途正向、跨用途、跨邮箱、重发竞态、旧码失效和禁用用途测试。
- **验收标准**：任何时刻同用户同用途最多一个有效任务。
- **回退方式**：按用途关闭签发。
- **验收证据**：待补充。

### AD-030 实现恒定比较、错误计数和原子消费

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-029
- **需求映射**：第 14.1、14.2、15.1、21.3 章
- **修改范围**：验证码验证服务、锁或原子状态机和并发测试
- **实施步骤**：恒定时间比较 HMAC；默认最多错误五次；验证成功前原子标记消费；过期、达到错误阈值、凭据版本变化或流程结束立即删除。
- **安全要求**：并发提交最多一次成功；错误响应不区分不存在、错误、过期等可枚举细节。
- **测试要求**：并发双花、错误计数竞态、过期边界、版本变化、重复提交和时序差异测试。
- **验收标准**：单次消费和失败阈值在并发下保持正确。
- **回退方式**：失效相关任务并要求重新签发。
- **验收证据**：待补充。

### AD-031 实现统一过期清理、重启失效和单实例守卫

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-030
- **需求映射**：第 14.2、15.1、21.3、22.4 章
- **修改范围**：验证码清理器、认证实例启动检查和测试
- **实施步骤**：使用统一定时器或分桶结构删除过期任务；进程停止、崩溃模拟、升级和重启后不恢复任务；首版强制单认证实例或明确阻止错误多实例部署。
- **安全要求**：不得从数据库、文件或外部缓存恢复；签发实例退出后直接失效，不允许验证绕过。
- **测试要求**：正常停止、强制终止、重启、升级、实例切换、清理延迟和大量过期任务测试。
- **验收标准**：重启后旧验证码全部无效，清理器不会造成 goroutine 或内存无限增长。
- **回退方式**：关闭验证码功能并清空内存任务。
- **验收证据**：待补充。

### 第六阶段验收

- [ ] 验证码任务和校验值只存在于签发认证进程内存；
- [ ] 进程临时密钥每次启动重新生成且不可导出；
- [ ] 验证码按用户、用途、邮箱、环境和凭据版本绑定；
- [ ] 重发、过期、错误阈值和并发单次消费正确；
- [ ] 容量上限、统一清理器和单实例边界生效；
- [ ] 服务重启后旧验证码不能恢复或绕过。
---

## 11. 第七阶段：SMTP Relay、限流和定期清理

### AD-032 接入统一 SMTP Relay 和验证码策略配置

- **状态**：未开始
- **优先级**：P1
- **依赖**：CG-022、AD-004
- **需求映射**：第 16、18.4、20.1 章
- **修改范围**：统一配置管理器、SMTP Relay 引用、验证码策略和测试
- **实施步骤**：验证码配置通过 `transportProfileId` 引用 SMTP Relay；支持开关、发件人、长度、有效期、错误次数、限流和角色策略；默认关闭。
- **安全要求**：不重复保存 SMTP 密码；未完成 Relay 验证、测试邮件、凭据加密、限流和审计检查时禁止启用。
- **测试要求**：配置校验、缺失引用、禁用 Relay、Secret 脱敏、配置更新和重启应用测试。
- **验收标准**：验证码策略与 SMTP 凭据分离，启用前置检查完整。
- **回退方式**：关闭验证码配置，不删除 Relay 配置。
- **验收证据**：待补充。

### AD-033 实现不持久化验证码的 SMTP 投递路径

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-032、AD-028
- **需求映射**：第 15.1、16、21.3 章
- **修改范围**：SMTP 发送服务、邮件模板、队列边界和测试
- **实施步骤**：在内存构建验证码邮件并直接交给投递组件；确认本地重试、死信、磁盘队列和消息队列不会保存验证码邮件正文；投递结果只保留分类数据。
- **安全要求**：Smail 控制范围内不得把验证码或含验证码的邮件正文写入磁盘、队列、日志、追踪或审计；完整目标邮箱只在发送阶段短时解密。
- **测试要求**：SMTP 成功、超时、拒收、重试、崩溃、调试日志、抓取本地队列和敏感词哨兵测试。
- **验收标准**：除发送给外部 SMTP Relay 的必要传输外，本地无验证码持久化副本。
- **回退方式**：投递失败并失效任务，不降级到持久化队列。
- **验收证据**：待补充。

### AD-034 实现测试邮件、失败分类和安全降级

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-032、AD-057
- **需求映射**：第 16、17、18.4 章
- **修改范围**：测试邮件接口、投递状态、告警和前端
- **实施步骤**：实现超级管理员测试邮件；区分配置、认证、连接、超时、拒收等脱敏失败分类；公共恢复始终返回统一提示。
- **安全要求**：测试邮件不包含真实验证码；失败不得绕过登录或恢复验证；错误不得回显 SMTP Secret。
- **测试要求**：各失败分类、超时、功能关闭、权限、CSRF、限流和日志脱敏测试。
- **验收标准**：可诊断投递状态但不泄露账号、邮箱或凭据。
- **回退方式**：关闭测试邮件入口。
- **验收证据**：待补充。

### AD-035 实现多维持久化限流和防绕过

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-023
- **需求映射**：第 14.1、15.2、20.2、21.3 章
- **修改范围**：限流服务、数据库模型、规范化标识和测试
- **实施步骤**：覆盖来源 IP、规范化登录标识、用户 ID、邮箱指纹、用途和浏览器事务；实现小时、每日、重发间隔和最近发送时间；服务重启后计数继续有效。
- **安全要求**：计数不包含验证码和完整邮箱；用户名/邮箱切换、主要/备用邮箱切换、恢复方式切换不能绕过；并发计数原子。
- **测试要求**：各维度边界、跨入口共享、并发突发、时钟边界、重启、三数据库一致性和 IPv4/IPv6 规范化测试。
- **验收标准**：默认 60 秒、5 次/小时、10 次/日、20 次/IP/小时策略准确执行。
- **回退方式**：采用更严格的内存拒绝策略，不允许关闭限流。
- **验收证据**：待补充。

### AD-036 建立非敏感运营数据和保留策略模型

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-035、AD-057
- **需求映射**：第 15.2、19 章
- **修改范围**：限流、投递、聚合、审计和清理任务数据库模型
- **实施步骤**：只持久化限流计数、脱敏投递结果、验证结果、用途、操作者 ID、邮箱指纹或脱敏摘要、安全告警和清理执行记录；增加到期时间与调查保留标记。
- **安全要求**：不得持久化验证码任务使用的 `challenge_id`；如需关联只使用不具备验证能力的审计关联 ID。
- **测试要求**：字段白名单、禁止字段序列化、保留期限计算、调查保留和迁移测试。
- **验收标准**：详细数据通常 30 天、聚合 90 天、安全审计至少 365 天，逻辑到期后不再参与业务判断。
- **回退方式**：停止新增明细并保留合规审计，不删除未确认数据。
- **验收证据**：待补充。

### AD-037 实现每 14 天执行的分批清理任务

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-036
- **需求映射**：第 15.2、19、21.3、22.3 章
- **修改范围**：`backend/listen/cron_server` 或独立调度服务、租约、告警和测试
- **实施步骤**：首次安装默认启用；每 14 天运行；启动时补执行错过任务；失败每 6 小时重试；同环境单实例执行；每批最多删除 1000 条；记录脱敏结果。
- **安全要求**：不删除活动窗口和调查保留数据；清理失败不影响登录、邮件或内存验证码；清理器不读取验证码内存仓库。
- **测试要求**：周期、补执行、重试、租约竞争、分批、失败恢复、调查保留和服务可用性测试。
- **验收标准**：清理任务幂等、可重试、不会长时间锁表或扩大认证权限。
- **回退方式**：暂停物理删除并告警，逻辑过期仍保持有效。
- **验收证据**：待补充。

### AD-038 实现三数据库安全清理和空间复用

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-037
- **需求映射**：第 15.2、21.3、22.4 章
- **修改范围**：MySQL、PostgreSQL、SQLite 清理仓储和测试环境
- **实施步骤**：分别实现批量删除和安全空间复用策略；不得在定期任务中执行阻塞式全表压缩；验证租约和删除条件在三数据库语义一致。
- **安全要求**：不能误删 365 天审计、活动限流和调查保留记录；失败不得回滚为延长已过期认证状态。
- **测试要求**：三数据库大数据量、锁竞争、批次边界、时区、失败重试和空间复用测试。
- **验收标准**：三数据库均通过清理测试，在线业务无不可接受阻塞。
- **回退方式**：停用物理回收，只保留安全批量删除或逻辑过期。
- **验收证据**：待补充。

### 第七阶段验收

- [ ] SMTP Relay 引用和验证码策略分离；
- [ ] 本地投递路径不持久化验证码或验证码邮件正文；
- [ ] 多维限流重启后仍有效且不能通过切换标识绕过；
- [ ] 清理任务每 14 天执行、失败每 6 小时重试、每批最多 1000 条；
- [ ] 30/90/365 天保留策略和调查保留生效；
- [ ] 三种数据库清理均通过且不执行阻塞式全表压缩。

---

## 12. 第八阶段：登录二次验证和分角色恢复

### AD-039 统一用户名和完整邮箱的第一步密码认证

- **状态**：未开始
- **优先级**：P0
- **依赖**：CG-027、AD-035
- **需求映射**：第 2、12.1、21.4 章
- **修改范围**：`backend/controllers/login.go`、认证服务、规范化和测试
- **实施步骤**：用户名和完整 Smail 邮箱进入同一账号解析、密码校验、角色和二次验证策略；密码错误时不创建验证码任务、不发送邮件。
- **安全要求**：两种登录标识错误响应和时间边界一致；不允许旧认证路径绕过验证码策略。
- **测试要求**：用户名、完整邮箱、大小写、未知账号、错误密码、锁定账号和策略一致性测试。
- **验收标准**：两种登录方式使用统一认证管线和统一安全结果。
- **回退方式**：关闭新登录流程，不放宽原认证要求。
- **验收证据**：待补充。

### AD-040 实现登录前置事务和受限会话

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-039、AD-029
- **需求映射**：第 12.1、17、21.4 章
- **修改范围**：登录事务、Session 服务、Cookie 和测试
- **实施步骤**：密码成功后创建短时登录事务而非完整 Session；签发 `login_step_up` 验证码；验证成功后原子升级为完整 Session。
- **安全要求**：受限事务不能访问邮箱、设置和管理 API；令牌不进入浏览器持久化存储；验证码未通过不能创建完整 Session。
- **测试要求**：权限隔离、事务过期、重放、并发升级、Cookie 属性、CSRF 和 Session 固定攻击测试。
- **验收标准**：完整 Session 只在第二步成功后创建。
- **回退方式**：失效登录事务并要求重新登录。
- **验收证据**：待补充。

### AD-041 实现 `off`、`always`、`new_device` 策略

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-040、AD-002
- **需求映射**：第 12.2、18.3 章
- **修改范围**：全局策略、用户策略、设备识别和测试
- **实施步骤**：用户可提高但不能降低全局强制策略；定义新设备识别、受信设备期限、撤销和版本绑定；首版不依赖复杂 IP 地理判断。
- **安全要求**：客户端提交的设备标识不能单独决定受信；清除凭据或版本变化后受信设备失效。
- **测试要求**：策略优先级、伪造设备 ID、Cookie 删除、跨浏览器、版本变化和全局策略更新测试。
- **验收标准**：三种策略行为稳定，用户无法绕过全局要求。
- **回退方式**：安全收紧为 `always` 或禁用登录邮箱验证功能并使用其他已确认强认证策略。
- **验收证据**：待补充。

### AD-042 实现登录验证码重发、WebAuthn 替代和失败封闭

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-041、AD-030
- **需求映射**：第 12.3、16、18.1、21.4 章
- **修改范围**：登录验证编排、WebAuthn 集成和前端接口
- **实施步骤**：只发送到已验证外部邮箱；重发使旧码失效；SMTP 失败时允许使用已配置 WebAuthn；没有可用替代方式时拒绝登录。
- **安全要求**：不得发送到 Smail 主邮箱、未验证邮箱、临时邮箱、管理人员指定邮箱或插件邮箱；不得降级为仅密码登录。
- **测试要求**：SMTP 失败、重发、外部邮箱失效、WebAuthn 替代、无替代方式和策略关闭测试。
- **验收标准**：失败场景保持认证强度，不形成绕过。
- **回退方式**：拒绝本次登录并提示使用已配置安全方式。
- **验收证据**：待补充。

### AD-043 实现防账号枚举的公共恢复起始流程

- **状态**：未开始
- **优先级**：P0
- **依赖**：CG-038、AD-039、AD-035
- **需求映射**：第 13.1、17、20.2、21.4 章
- **修改范围**：密码恢复服务、统一响应、浏览器事务和测试
- **实施步骤**：允许输入用户名或完整邮箱；存在与不存在账号均返回统一提示；内部按角色和能力决定是否创建恢复事务并发送信息。
- **安全要求**：响应、状态码、长度和可观测时间不得明显泄露账号存在、角色、邮箱绑定和投递结果。
- **测试要求**：存在/不存在账号时序统计、不同角色、未绑定邮箱、限流和 SMTP 失败一致性测试。
- **验收标准**：公共接口无法用于可靠账号枚举。
- **回退方式**：关闭公共恢复并保留部署端管理入口。
- **验收证据**：待补充。

### AD-044 实现普通用户多路径密码恢复

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-043、AD-030、AD-046
- **需求映射**：第 13.2、13.6、21.4 章
- **修改范围**：恢复编排、密保、离线恢复码、WebAuthn 和邮箱验证码服务
- **实施步骤**：支持密保问答+离线恢复码、WebAuthn、已验证外部邮箱验证码、管理员或超级管理员强制重置；邮箱验证成功后只签发短时重置授权。
- **安全要求**：路径之间不能拼接绕过；恢复事务绑定用户、路径、凭据版本和浏览器上下文。
- **测试要求**：每条路径、切换路径、并发恢复、旧验证码、旧授权和跨账号测试。
- **验收标准**：普通用户只能通过已确认且完整满足条件的单一路径获得重置授权。
- **回退方式**：按路径关闭，保留已验证的强恢复方式。
- **验收证据**：待补充。

### AD-045 实现管理员组合恢复和超级管理员拒绝

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-043、AD-030、AD-046
- **需求映射**：第 13.3、13.4、21.4 章
- **修改范围**：角色恢复策略、组合验证状态机和测试
- **实施步骤**：管理员支持 WebAuthn、密保+恢复码、外部邮箱验证码+恢复码、超级管理员强制重置；超级管理员不创建任何公开恢复任务。
- **安全要求**：管理员仅凭邮箱验证码不得恢复；组合因素必须绑定同一事务、同一用户和同一凭据版本；顺序和并发不能绕过。
- **测试要求**：缺少恢复码、不同用户因素拼接、因素重放、顺序交换、角色篡改和超级管理员拒绝测试。
- **验收标准**：管理员组合恢复不可拆分或跨事务复用，超级管理员 Web 恢复始终拒绝。
- **回退方式**：关闭邮箱恢复，保留 WebAuthn 或部署端强制重置。
- **验收证据**：待补充。

### AD-046 实现短时一次性密码重置授权

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-043
- **需求映射**：第 13.5、21.4 章
- **修改范围**：恢复授权服务、存储策略、浏览器交互和并发测试
- **实施步骤**：使用安全随机源；服务端只保存不可逆校验值；绑定用户、路径、用途、凭据版本和请求上下文；默认五分钟；消费前原子标记；密码或标识变化后失效。
- **安全要求**：授权不得进入日志、URL、浏览器持久化存储和审计详情；必须明确授权校验值的存储位置、生命周期和清理方式，不能与验证码任务混淆。
- **测试要求**：过期、重放、并发消费、版本变化、跨路径、跨用户、浏览器存储和日志泄露测试。
- **验收标准**：授权只能消费一次，且不能用于验证码验证之外的用途。
- **回退方式**：失效全部未完成授权。
- **验收证据**：待补充。

### AD-047 实现用户自行恢复后的凭据处理

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-044、AD-045、AD-046、AD-016
- **需求映射**：第 13.6、21.4、24 章
- **修改范围**：密码更新、Session 撤销、安全提示和通知
- **实施步骤**：更新密码并递增 Session 版本；撤销旧 Session 和未完成票据；按最终确认保留现有 WebAuthn 和有效恢复码；通知主要与备用邮箱；下次登录提示安全检查。
- **安全要求**：外部邮箱攻击者不能借恢复流程自动移除用户原有强恢复凭据；通知失败不回滚密码更新。
- **测试要求**：旧 Session、WebAuthn、恢复码、未完成票据、通知失败和主动撤销入口测试。
- **验收标准**：恢复后旧会话失效，强恢复凭据处理符合已确认策略。
- **回退方式**：保留更安全的 Session 撤销状态，不恢复旧密码。
- **验收证据**：待补充。

### 第八阶段验收

- [ ] 用户名和完整邮箱登录执行同一策略；
- [ ] 密码错误不发送验证码，验证码未通过不创建完整 Session；
- [ ] `off`、`always`、`new_device` 策略不能被客户端绕过；
- [ ] 普通用户和管理员恢复严格符合角色矩阵；
- [ ] 管理员不能仅凭邮箱验证码恢复；
- [ ] 超级管理员不能创建公开恢复任务；
- [ ] 重置授权短时、一次性、不可重放。

---

## 13. 第九阶段：后端 API 和授权边界

### AD-048 建立统一安全 DTO、错误码和请求守卫

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-004、AD-035、CG-048
- **需求映射**：第 17、20 章
- **修改范围**：`backend/controllers`、DTO、响应、CSRF、Session 和限流中间件
- **实施步骤**：为验证码、外部邮箱、恢复和管理员接口定义稳定 DTO 与错误码；统一执行能力、对象归属、Session、CSRF、限流和请求大小检查。
- **安全要求**：默认拒绝未知用途、角色和字段；禁止批量赋值；公共恢复响应防枚举。
- **测试要求**：越权、CSRF、字段注入、超长请求、未知枚举、错误码稳定性和敏感响应测试。
- **验收标准**：所有新增接口经过同一后端安全守卫，不依赖前端控制。
- **回退方式**：不注册新增路由。
- **验收证据**：待补充。

### AD-049 实现外部邮箱账户安全接口

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-048、AD-025
- **需求映射**：第 17、18.3 章
- **修改范围**：外部邮箱查询、挑战、验证和删除 Controller
- **实施步骤**：实现需求列出的查询、发送挑战、验证和删除接口；所有资源从当前 Session 推导用户，不接受跨用户目标 ID。
- **安全要求**：只返回脱敏邮箱；删除和变更要求近期重新认证；禁止 IDOR。
- **测试要求**：所有权、CSRF、重放、近期认证过期、并发变更和脱敏测试。
- **验收标准**：用户只能完成自己的外部邮箱生命周期操作。
- **回退方式**：关闭路由并保留数据。
- **验收证据**：待补充。

### AD-050 实现登录验证和密码恢复接口

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-048、AD-042、AD-047
- **需求映射**：第 17、18.1、18.2 章
- **修改范围**：登录挑战、验证、恢复开始、邮箱验证和完成接口
- **实施步骤**：实现需求推荐接口；使用服务端事务标识；统一重发、过期和替代 WebAuthn 流程；恢复完成只接受一次性授权。
- **安全要求**：不返回验证码、完整邮箱、角色或内部投递结果；不能通过接口顺序变化绕过状态机。
- **测试要求**：状态机乱序、跨浏览器、跨用户、重放、CSRF、防枚举和完整 Session 创建测试。
- **验收标准**：API 只能按合法状态迁移，非法请求安全失败。
- **回退方式**：禁用路由并失效相关事务。
- **验收证据**：待补充。

### AD-051 实现超级管理员验证码配置和分角色用户重置接口

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-048、AD-034、AD-021、AD-058
- **需求映射**：第 5.1、17、18.4、20.3 章
- **修改范围**：管理安全 Controller、能力校验、审计和测试
- **实施步骤**：实现状态、审计、配置、测试邮件和重置用户接口；配置更新执行近期重新认证或 WebAuthn；重置接口拒绝超级管理员目标。
- **安全要求**：不得提供超级管理员自身 Web 重置、开启本机通道或删除审计接口；邮箱验证码不能单独授权管理操作。
- **测试要求**：角色越权、目标篡改、近期认证、WebAuthn、CSRF、审计、Secret 脱敏和禁止路由测试。
- **验收标准**：只有具备对应能力的超级管理员可调用，禁止接口在 Router 中不存在。
- **回退方式**：关闭管理路由，不影响本机重置程序。
- **验收证据**：待补充。

### 第九阶段验收

- [ ] 新增 API 均执行能力、对象归属、Session、CSRF 和限流；
- [ ] 用户资源不接受可越权的目标用户 ID；
- [ ] 公共恢复响应不泄露账号和投递状态；
- [ ] 禁止的三个超级管理员重置 Web 接口未注册；
- [ ] 超级管理员管理操作不能仅凭邮箱验证码授权。
---

## 14. 第十阶段：前端页面和交互

### AD-052 实现登录邮箱二次验证页面

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-050
- **需求映射**：第 18.1 章
- **修改范围**：`frontend/src/views`、认证状态、路由守卫和浏览器测试
- **实施步骤**：实现密码登录后的验证码输入、脱敏邮箱、倒计时、重发、过期、失败提示和 WebAuthn 替代入口；刷新后按安全状态恢复或失效事务。
- **安全要求**：不在 localStorage、sessionStorage、URL 或前端日志保存验证码和重置授权；前端不能自行升级 Session。
- **测试要求**：桌面、移动、低高度视口；重发、过期、刷新、后退、并发标签页和无障碍测试。
- **验收标准**：页面只展示脱敏信息，所有状态由后端事务决定。
- **回退方式**：禁用邮箱二次验证入口并保持后端安全拒绝。
- **验收证据**：待补充。

### AD-053 实现防枚举忘记密码页面

- **状态**： [~] 进行中
- **优先级**：P1
- **依赖**：AD-050、AD-002
- **需求映射**：第 13、18.2 章
- **修改范围**：`frontend` 忘记密码视图、恢复方式组件和测试
- **实施步骤**：允许用户名或完整邮箱；始终显示统一提交结果；按后端签发事务展示可用的 WebAuthn、密保+恢复码或外部邮箱流程；启用功能并配置有效域名或 IP 后，通过大小写敏感的 `/Reset` 固定入口加载独立恢复页面。
- **安全要求**：超级管理员不能看到或调用可用 Web 恢复路径；页面不得泄露账号存在、角色、邮箱绑定和投递结果。
- **测试要求**：三角色、不存在账号、无恢复方式、SMTP 失败、直接路由、刷新和浏览器存储检查；覆盖域名、IPv4、IPv6、关闭开关、`GET` 方法限制和路径大小写。
- **验收标准**：视觉和网络响应均无法可靠区分账号是否存在。
- **回退方式**：关闭忘记密码入口。
- **验收证据**：`frontend/src/views/RecoveryView.vue`、`frontend/src/views/LoginView.vue`、`backend/listen/http_server/reset_entry_test.go`、`backend/controllers/security_reset_entry_test.go`；2026-08-27 `go test ./...`、`go vet ./...`、`yarn.cmd build` 通过。恢复页面和登录弹窗统一为单页面表单，使用“切换验证方式”按钮切换安全密钥与外部邮箱验证码，并在切换时清理另一方式的验证码会话和输入状态。真实浏览器和三角色完整流程仍待 AD-064 复审。

- [x] 已完成，等待复审：域名/IP 配置与功能开关共同控制 `/Reset` 页面和恢复 API；关闭时页面返回 404，API 安全拒绝。
- [x] 已完成，等待复审：新增独立恢复页面，验证码、恢复票据不写入 URL、localStorage 或 sessionStorage。
- [x] 已完成，等待复审：恢复页面和登录弹窗不使用并列页签，点击按钮切换验证方式，切换时清理验证码、恢复码和验证码会话。
- [!] 暂缓或存在阻塞：密保问答路径和真实浏览器三角色端到端验收未完成，AD-053 整体不得标记复审通过。

### AD-054 实现账户安全和外部邮箱管理页面

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-049、AD-041
- **需求映射**：第 18.3 章
- **修改范围**：`frontend/src/components/SecuritySettings.vue` 或独立安全页面
- **实施步骤**：管理主要和备用外部邮箱；显示脱敏地址、验证状态和最近发送时间；设置登录邮箱二次验证；关联离线恢复码和 WebAuthn 管理入口。
- **安全要求**：更换和删除前要求近期重新认证；完整邮箱和敏感票据不进入页面状态快照和错误报告。
- **测试要求**：绑定、更换、删除、重认证过期、双邮箱上限、角色差异和 XSS 测试。
- **验收标准**：用户只能看到和操作自己的数据，超级管理员只显示通知用途。
- **回退方式**：隐藏写入口并由后端继续拒绝。
- **验收证据**：待补充。

### AD-055 实现超级管理员验证码配置和审计页面

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-051、AD-059
- **需求映射**：第 18.4、19 章
- **修改范围**：`frontend` 管理安全页面、配置表单、统计和审计列表
- **实施步骤**：配置开关、Relay 引用、发件人、限流和角色策略；发送测试邮件；展示脱敏状态、投递统计、审计和清理任务状态。
- **安全要求**：不显示 SMTP 密码、验证码、完整邮箱、恢复授权和删除审计入口；敏感配置修改要求近期重新认证或 WebAuthn。
- **测试要求**：权限、CSRF、脱敏、审计分页、配置校验、失败告警和浏览器缓存检查。
- **验收标准**：超级管理员可完成合规管理，但不能通过页面开启自身重置通道。
- **回退方式**：页面只读，后端写接口关闭。
- **验收证据**：待补充。

### AD-056 实现强制重置后的首次登录安全引导

- **状态**：未开始
- **优先级**：P2
- **依赖**：AD-018、AD-021、AD-050
- **需求映射**：第 8.7、9、13.6、18.3 章
- **修改范围**：首次登录路由、强制改密、安全凭据引导和测试
- **实施步骤**：目标用户使用临时密码后强制设置新密码；提示重新生成离线恢复码、重新绑定 WebAuthn、检查外部邮箱和退出全部设备；超级管理员按部署端重置结果显示安全检查。
- **安全要求**：未完成强制改密前只能访问必要页面；一次性临时密码不能再次使用；不得强制超级管理员配置离线恢复码。
- **测试要求**：路由绕过、刷新、后退、多标签页、临时密码重放和超级管理员豁免恢复码测试。
- **验收标准**：被强制重置用户不能跳过必要安全步骤进入完整系统。
- **回退方式**：保持账户受限并由部署管理员处理。
- **验收证据**：待补充。

### 第十阶段验收

- [ ] 登录、忘记密码、账户安全和超级管理员配置页面可完整操作；
- [ ] 页面只显示脱敏邮箱和非敏感状态；
- [ ] 浏览器持久化存储、URL、控制台和错误报告不含敏感数据；
- [ ] 超级管理员不存在 Web 自助重置入口；
- [ ] 桌面、低高度和移动视口完成真实浏览器验证。

---

## 15. 第十一阶段：审计、监控和告警

### AD-057 建立统一安全审计事件模型

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-004、AD-003
- **需求映射**：第 19 章
- **修改范围**：安全审计服务、事件枚举、DTO、数据库模型和测试
- **实施步骤**：定义部署端重置、验证码签发结果、验证结果、限流、外部邮箱变更、恢复、用户强制重置和凭据撤销事件；使用不可用于验证的关联 ID。
- **安全要求**：禁止密码、验证码、维护凭据、完整邮箱、恢复码、WebAuthn 私密数据和恢复授权进入审计。
- **测试要求**：事件完整性、字段白名单、脱敏、审计失败、并发顺序和敏感哨兵测试。
- **验收标准**：关键安全动作均有稳定事件，字段满足最小必要原则。
- **回退方式**：安全写操作在审计不可用时按风险策略拒绝或进入明确补偿队列，补偿内容不得含敏感数据。
- **验收证据**：待补充。

### AD-058 实现审计保留、只读查询和防删除保护

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-057、AD-036
- **需求映射**：第 17、19、22.3 章
- **修改范围**：审计仓储、查询 API、访问控制和清理策略
- **实施步骤**：安全审计至少保留 365 天；提供超级管理员脱敏只读查询；普通 Web API 不提供删除审计和清理执行记录的接口；导出如后续实现必须单独审计。
- **安全要求**：查询要求超级管理员能力；禁止完整邮箱和敏感详情；调查保留数据不得自动删除。
- **测试要求**：365 天边界、越权查询、删除路由枚举、分页、导出禁用和调查保留测试。
- **验收标准**：审计可追踪、不可由普通 Web 接口删除且保留期限达标。
- **回退方式**：关闭查询，不缩短保留期限。
- **验收证据**：待补充。

### AD-059 实现脱敏指标、告警和运行状态

- **状态**：未开始
- **优先级**：P2
- **依赖**：AD-057、AD-037、AD-034
- **需求映射**：第 16、18.4、19 章
- **修改范围**：指标、告警、管理状态接口和页面
- **实施步骤**：统计发送成功率、失败分类、限流命中、内存任务数量和容量比例、清理执行、重试、审计写入失败和 IPC 拒绝；设置阈值告警。
- **安全要求**：指标标签不得包含验证码、完整邮箱、登录标识、IP 明文和高基数字段；诊断接口不能读取内存任务详情或临时密钥。
- **测试要求**：指标脱敏、容量告警、清理失败、SMTP 失败、审计失败和权限测试。
- **验收标准**：运维人员能识别异常，但不能通过指标还原用户或验证秘密。
- **回退方式**：关闭有风险指标，保留最小健康状态。
- **验收证据**：待补充。

### 第十一阶段验收

- [ ] 全部关键安全动作具有脱敏审计；
- [ ] 安全审计至少保留 365 天；
- [ ] 普通 Web API 无删除审计能力；
- [ ] 指标、告警和诊断不泄露验证码、邮箱或凭据；
- [ ] 清理、SMTP、容量和 IPC 异常可被发现。

---

## 16. 第十二阶段：跨平台测试、安全复审和发布验收

### AD-060 完成后端单元、并发和故障注入测试

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-011、AD-015、AD-019、AD-020、AD-021、AD-025、AD-031、AD-034、AD-038、AD-042、AD-047、AD-051、AD-058、AD-059
- **需求映射**：第 21.1、21.3、21.4 章
- **修改范围**：`server` 各模块测试和竞态测试
- **实施步骤**：覆盖密码服务、IPC 协议、会话状态机、内存验证码、原子消费、限流、恢复授权、凭据撤销、审计和清理；在关键事务点注入失败。
- **安全要求**：不得跳过竞态、超时、重放和失败路径；测试日志使用假凭据并确认脱敏。
- **测试要求**：执行 Go 单元测试、竞态检测、模糊测试和故障注入套件。
- **验收标准**：关键模块无数据竞争，并发最多一次成功，失败后状态安全一致。
- **回退方式**：对应功能保持关闭。
- **验收证据**：待补充。

### AD-061 完成 MySQL、PostgreSQL、SQLite 集成测试

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-022、AD-035、AD-038、AD-018、AD-047
- **需求映射**：第 15.2、21.3、22.4 章
- **修改范围**：三数据库测试环境、迁移、事务、租约和清理测试
- **实施步骤**：在三种真实数据库分别运行模型迁移、密码重置事务、并发限流、凭据撤销、审计保留、租约和分批清理。
- **安全要求**：不得用 SQLite 结果替代 MySQL/PostgreSQL；测试凭据不得进入仓库。
- **测试要求**：记录数据库版本、连接方式、测试命令、锁等待和结果。
- **验收标准**：三数据库均通过，无未说明语义差异。
- **回退方式**：阻止未通过数据库类型启用本功能。
- **验收证据**：待补充。

### AD-062 完成 Ubuntu 22.04 和 24.04 安装与 IPC 测试

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-011、AD-013、AD-019
- **需求映射**：第 6、8、21.2、22.1、22.2 章
- **修改范围**：Ubuntu 安装包、systemd、Unix Socket 和安全测试
- **实施步骤**：真实安装、升级、回滚；验证 root 与普通用户；验证对端 UID、socket 抢占、权限篡改、重启失效和无 TCP 端口。
- **安全要求**：两个 Ubuntu 版本都必须通过，不允许用容器结果替代真实系统验证。
- **测试要求**：记录 systemctl 状态、文件权限、socket 信息、端口扫描和完整重置结果。
- **验收标准**：Ubuntu 22.04/24.04 安全边界一致，安装失败不会留下半升级。
- **回退方式**：恢复上一版程序并保持重置入口关闭。
- **验收证据**：待补充。

### AD-063 完成 Windows 安装与 Named Pipe 测试

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-011、AD-014、AD-019
- **需求映射**：第 6、8、21.2、22.1、22.2 章
- **修改范围**：Windows 安装、Service、ACL、Named Pipe 和安全测试
- **实施步骤**：真实安装、升级、回滚；验证提升管理员、未提升管理员、普通用户、SYSTEM 和 Smail 服务账户；检查管道 ACL、令牌验证和无 TCP 端口。
- **安全要求**：普通用户或服务账户不能替换、执行管理程序或连接管道。
- **测试要求**：记录 ACL、服务状态、进程令牌、管道连接、端口扫描和重置结果。
- **验收标准**：Windows 适配达到与 Linux 等价的安全边界。
- **回退方式**：恢复上一版程序和 ACL，关闭管理入口。
- **验收证据**：待补充。

### AD-064 完成真实浏览器端到端验证

- **状态**：未开始
- **优先级**：P1
- **依赖**：AD-052、AD-053、AD-054、AD-055、AD-056
- **需求映射**：第 18、21.4 章
- **修改范围**：前端 E2E、浏览器截图和网络记录
- **实施步骤**：覆盖登录二次验证、重发、WebAuthn 替代、忘记密码、外部邮箱生命周期、超级管理员配置、强制改密和安全引导。
- **安全要求**：检查 URL、DOM、控制台、网络响应、Cookie 和浏览器存储无敏感数据。
- **测试要求**：桌面 1440×900、低高度和移动视口；至少覆盖主流 Chromium 浏览器。
- **验收标准**：功能、权限、脱敏、无滚动阻塞和错误状态均符合需求。
- **回退方式**：关闭未通过页面入口。
- **验收证据**：待补充。

### AD-065 完成安全负向测试和泄露扫描

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-060、AD-061、AD-062、AD-063、AD-064
- **需求映射**：第 20、21、22.4 章
- **修改范围**：安全测试、端口扫描、路由检查、日志与持久化扫描
- **实施步骤**：测试非管理员调用、TCP/HTTP 路径、IPC 冒用、协议模糊、重放、账号枚举、IDOR、CSRF、暴力破解、验证码跨用途、内存容量、SMTP 失败降级和敏感数据泄露。
- **安全要求**：发现 P0/P1 风险必须回到对应任务整改，不得以文档说明接受明显漏洞。
- **测试要求**：扫描数据库、文件、队列、日志、审计、指标、追踪、备份、进程参数和环境变量。
- **验收标准**：无公开超级管理员重置路径、无验证码持久化、无认证绕过和无明显敏感泄露。
- **回退方式**：禁止发布并关闭受影响能力。
- **验收证据**：待补充。

### AD-066 同步上游文档并完成最终发布评审

- **状态**：未开始
- **优先级**：P0
- **依赖**：AD-065、CG-053、CG-054、CG-055、CG-056
- **需求映射**：第 1、22、23、24、25 章
- **修改范围**：五份需求/设计/任务文档、发布说明和安全评审报告
- **实施步骤**：同步配置系统重构三份文档；复核 66 项任务状态和证据；检查发布阻塞条件；形成允许或禁止发布结论，并为 CG-057 提供聚合验收证据。
- **安全要求**：不得把“已编码”当作“已验收”；不得隐藏失败测试、未验证平台、命令冲突或已知风险。
- **测试要求**：抽查证据可重复；复跑关键安全测试；检查 Git 差异无真实凭据和未经许可的文件删除。
- **验收标准**：全部 P0/P1 任务完成，Windows、Ubuntu 22.04/24.04 和三数据库验收通过，所有阻塞条件关闭。
- **回退方式**：结论为禁止发布，继续整改，不修改状态掩盖问题。
- **验收证据**：待补充。

### 第十二阶段验收

- [ ] 后端单元、竞态、模糊和故障注入测试通过；
- [ ] MySQL、PostgreSQL、SQLite 集成测试通过；
- [ ] Ubuntu 22.04、Ubuntu 24.04 和 Windows 真实平台测试通过；
- [ ] 浏览器端到端和敏感数据检查通过；
- [ ] 不存在公开超级管理员重置入口和验证码持久化；
- [ ] 全部任务状态、证据和复审记录准确；
- [ ] 最终安全评审明确允许发布。

---

## 17. 关键依赖链

```text
AD-001 + AD-002
├── AD-003 → AD-004 → AD-005
├── AD-006 → AD-007 → AD-008
│           ├── AD-009
│           └── AD-010
│               └── AD-009 + AD-010 → AD-011
├── AD-012 → AD-015
│      ├── AD-009 + AD-015 → AD-013
│      └── AD-010 + AD-015 → AD-014
├── CG-029 + AD-003 → AD-016
│      └── AD-015 + AD-016 → AD-017 → AD-018
│                                      ├── AD-019
│                                      └── CG-025 + AD-002 + AD-016 → AD-021
└── AD-020

AD-022 → AD-023 → AD-024
AD-026 → AD-027 → AD-028
AD-032 → AD-033
AD-024 + AD-028 → AD-035
AD-035 + AD-033 → AD-029 → AD-030 → AD-031
AD-030 + AD-024 → AD-025

AD-057 → AD-058
AD-035 + AD-057 → AD-036 → AD-037 → AD-038
AD-034 + AD-037 + AD-057 → AD-059

AD-039 → AD-040 → AD-041 → AD-042
AD-043 → AD-046
AD-043 + AD-030 + AD-046 → AD-044 + AD-045 → AD-047

AD-048 → AD-049 + AD-050 + AD-051
AD-049 → AD-054
AD-050 → AD-052 + AD-053 + AD-056
AD-051 + AD-059 → AD-055

全部实现 → AD-060 + AD-061 + AD-062 + AD-063 + AD-064
AD-060～AD-064 → CG-052
全部测试 → AD-065
AD-065 + CG-053～CG-056 → AD-066 → CG-057
```

> 阶段编号用于管理进度，不代表必须完全串行。存在后置阶段基础任务被前置阶段业务任务依赖时，应按上图依赖链先完成基础任务，例如先完成 `AD-057` 再完成 `AD-019`。

---

## 18. 需求覆盖矩阵

| 需求章节 | 主要任务 |
|---|---|
| 第 3—5 章：目标、非目标、角色 | AD-001、AD-002、AD-003、AD-020、AD-021 |
| 第 6—8 章：程序、安装、部署端重置 | AD-006—AD-011、AD-012—AD-015、AD-016—AD-019 |
| 第 9 章：重置其他用户 | AD-002、AD-021、AD-051、AD-056 |
| 第 10—11 章：用途和外部邮箱 | AD-022—AD-025、AD-029、AD-049、AD-054 |
| 第 12 章：登录二次验证 | AD-039—AD-042、AD-050、AD-052 |
| 第 13 章：密码恢复 | AD-043—AD-047、AD-020、AD-050、AD-053 |
| 第 14—15.1 章：验证码和内存生命周期 | AD-026—AD-031、AD-004、AD-060、AD-065 |
| 第 15.2 章：运营数据和清理 | AD-035、AD-036—AD-038、AD-061 |
| 第 15.3 章：外部邮箱保护 | AD-022—AD-024、AD-004 |
| 第 16 章：SMTP Relay | AD-032—AD-034、AD-035、AD-059 |
| 第 17 章：API | AD-048—AD-051、AD-020 |
| 第 18 章：页面 | AD-052—AD-056、AD-064 |
| 第 19 章：审计 | AD-057、AD-058、AD-059、AD-036 |
| 第 20 章：安全要求 | AD-003、AD-004、AD-035、AD-048、AD-065 |
| 第 21—22 章：测试和验收 | AD-005、AD-060—AD-065、AD-066 |
| 第 23—25 章：顺序、决定、评审 | AD-001、AD-002、AD-066 |

---

## 19. 每轮实施记录模板

每次开始一组任务时追加记录，不得覆盖历史记录：

```text
日期：
执行任务：
开始状态：
修改文件：
实施摘要：
测试命令：
测试结果：
安全检查：
跨平台或数据库覆盖：
遗留问题：
回退验证：
结束状态：进行中 / 待复审 / 已完成 / 阻塞
复审人：
```

### 2026-08-27 AD-003 实施记录

日期：2026-08-27
执行任务：AD-003 完成威胁模型和敏感数据流设计
开始状态：未开始
修改文件：`docs/安全威胁模型与敏感数据流设计.md`、`docs/超级管理员重置与邮箱验证码实施任务清单.md`
实施摘要：完成部署端超级管理员重置、外部安全邮箱绑定、登录二次验证、邮箱密码恢复、WebAuthn、SMTP 投递、限流与审计的数据流设计；标记 HTTP、主服务、管理进程、本机 IPC、SMTP、数据库、内存和观测信任边界；登记允许持久化和禁止持久化的数据；建立 18 项威胁、控制措施与负向测试矩阵，并修正文档中不存在的测试名称引用。
测试命令：`go test ./services/verification ./services/recovery ./services/credentials ./services/externalemail ./services/adminreset ./services/webauthn ./controllers/...`；`go test ./...`；`go vet ./...`；`git diff --check`
测试结果：定向测试、全量测试、vet 和 diff 检查均通过；文档均通过严格 UTF-8 解码且无 BOM；文档引用的测试函数均已核对存在。
安全检查：确认超级管理员自身没有网络重置入口；验证码、恢复票据、IPC nonce 和 WebAuthn ceremony 的内存与一次性消费边界已记录；外部邮箱、凭据和运营数据的加密、哈希或指纹持久化边界已记录；未把真实平台和生产观测能力误记为已验收。
跨平台或数据库覆盖：自动化测试覆盖现有 SQLite 夹具及平台条件测试；真实 Ubuntu 22.04/24.04、Windows Named Pipe、SMTP Relay、多数据库和多实例路由尚未完成。
遗留问题：全局日志、指标、追踪和错误报告的统一敏感字段哨兵待 AD-004、AD-057、AD-059；真实平台 IPC 待 AD-011、AD-015、AD-062、AD-063；真实 SMTP 链路待 AD-034、AD-035、AD-038；多实例粘性路由或单实例部署约束待后续部署验收。
回退验证：本轮只修改设计文档和任务状态，未修改业务代码；如复审不通过，可回退 AD-003 文档和状态记录，不影响现有运行程序。
结束状态：待复审
复审人：

---

## 2026-08-27 AD-004 实施记录

- **日期**：2026-08-27
- **执行任务**：AD-004 建立敏感字段、日志和持久化禁止清单
- **开始状态**：未开始
- **修改文件**：`backend/config/sensitive.go`、`backend/config/sensitive_test.go`、`backend/controllers/config.go`、`backend/controllers/config_error_test.go`、`backend/services/access/authorize.go`、`backend/services/access/capability.go`、`backend/services/access/catalog.go`、`backend/services/access/access_test.go`、`backend/services/access/matrix_test.go`、`backend/listen/http_server/http_server.go`、`backend/listen/http_server/config_route_test.go`
- **实施摘要**：扩展敏感字段目录和持久化禁止策略；增加公共脱敏能力；将配置、审计和回滚 API 纳入能力目录；恢复配置更新 `PUT` 路由；统一授权错误的稳定错误码并防止内部错误文本进入响应；增加配置路由、授权矩阵和敏感响应负向测试。
- **测试命令**：`go test ./services/access ./config ./controllers ./listen/http_server`、`go test ./...`、`go vet ./...`、`git diff --check`
- **测试结果**：定向测试、全量测试和 `go vet ./...` 通过；`git diff --check` 未发现空白错误。
- **安全检查**：敏感字段按策略禁止明文持久化或通用序列化；配置错误响应仅返回稳定错误码和中文安全提示；配置备份使用回滚能力授权；未登记能力默认拒绝。
- **遗留问题**：全局日志、指标、追踪、缓存、队列和错误报告的生产哨兵尚未完整覆盖；真实 SMTP、真实平台 IPC、多实例、多数据库和生产部署仍未验收。
- **回退验证**：未删除既有文件、配置或数据；保留旧配置读取路径，新增能力可按默认拒绝策略关闭。
- **结束状态**：待复审
- **复审人**：

---

## 20. 任务状态变更记录

| 日期 | 任务 | 原状态 | 新状态 | 说明 |
|---|---|---|---|---|
| 2026-08-25 | 全部实施任务 | 无 | 未开始 | 根据需求文档创建任务清单，尚未开始编码实施 |
| 2026-08-25 | AD-001 | 未开始 | 已完成 | 统一 Linux 正式入口为 `systemctl start smail-admin`，确定短时服务和安全密码代理边界 |
| 2026-08-25 | AD-002 | 未开始 | 已完成 | 冻结超级管理员、管理员、普通用户和部署端的密码重置权限矩阵 |
| 2026-08-27 | AD-003 | 未开始 | 已完成，等待复审 | 完成安全威胁模型、敏感数据流、持久化边界和 18 项威胁测试映射；自动化检查通过，真实平台和生产验收保留为后续任务 |
| 2026-08-27 | AD-004 | 未开始 | 已完成，等待复审 | 完成敏感字段、脱敏和持久化禁止边界；配置授权与路由测试通过，生产哨兵和真实平台验收仍待完成 |
| 2026-08-25 | 文档清单 | 0.2 | 0.3 | 建立 CG/AD 双向可追踪的单向依赖，修正统一密码服务顺序并完成 P0/P1 文档复审 |
| 2026-08-25 | 文档清单 | 0.3 | 0.3 | 二次复审清理验证码预留表述，补充 CG-032、CG-048 基础依赖并验证联合依赖图无缺失和循环 |

---

## 21. 发布阻塞条件

出现以下任一情况，不允许把本轮任务标记为完成或进入生产发布：

1. 正式入口不是唯一的 `systemctl start smail-admin`，或短时服务、安全密码代理模型被弱化；
2. 权限实现不符合“超级管理员重置管理员和普通用户、管理员重置普通用户、普通用户仅重置本人、部署端仅重置超级管理员自身”；
3. 超级管理员存在普通 Web 修改密码或公开忘记密码路径；
4. 超级管理员重置通道监听 TCP、注册 HTTP Router 或可由插件访问；
5. Linux Unix Domain Socket 或 Windows Named Pipe 任一平台未完成；
6. 本机 IPC 只依赖文件权限或 ACL，未验证调用者系统身份；
7. `smail-admin` 能读取数据库凭据、配置主密钥、构造 DSN 或直接修改数据库；
8. 密码能通过参数、环境变量、URL、配置文件、服务名、日志或标准输出传递；
9. 主程序和管理程序版本不兼容时仍可重置；
10. 重置会话能重复消费、跨进程复用或在主程序重启后继续有效；
11. 密码修改未使用统一 Argon2id 服务，或存在旧弱算法回退；
12. 超级管理员部署端重置后旧 Session、WebAuthn、恢复码、受信设备或票据仍有效；
13. 超级管理员强制重置其他用户时未按确认策略撤销安全凭据；
14. 验证码明文、密文、摘要、HMAC 校验值、任务或进程临时密钥进入任何持久化介质；
15. 验证码任务可在服务重启后恢复或通过外部存储跨实例共享；
16. 内存验证码没有容量上限、统一过期清理、错误阈值或原子单次消费；
17. 验证码可以跨用户、用途、邮箱、环境或凭据版本使用；
18. 密码错误时发送验证码，或验证码未通过时创建完整 Session；
19. 功能关闭、SMTP 失败或数据异常时可以降级绕过认证；
20. 管理员可以仅凭邮箱验证码恢复密码；
21. 超级管理员可以通过邮箱验证码恢复自己的密码；
22. 邮箱验证码可以单独批准高风险操作；
23. 公共恢复接口能够枚举账号、角色、邮箱绑定或投递结果；
24. 用户可越权读取或修改其他用户的外部邮箱、验证码或恢复事务；
25. 完整外部邮箱以明文存储、进入普通日志，或密文篡改后仍可发送；
26. SMTP 本地队列、消息队列、死信或重试文件持久化验证码邮件正文；
27. 多维限流可通过切换用户名/邮箱、主要/备用邮箱或恢复方式绕过；
28. 14 天清理、6 小时失败重试、1000 条分批和三数据库测试任一未完成；
29. 验证码安全审计或超级管理员重置审计保留不足 365 天；
30. 普通 Web API 可以删除安全审计或清理任务记录；
31. Ubuntu 22.04、Ubuntu 24.04 或 Windows 真实平台测试未通过；
32. MySQL、PostgreSQL 或 SQLite 任一数据库集成测试未通过；
33. 日志、审计、指标、追踪、备份、浏览器存储或错误响应泄露敏感数据；
34. 存在未关闭的 P0/P1 安全漏洞或未说明的失败测试；
35. 未经用户许可删除文件、旧配置、数据库列或旧数据。

完成全部 66 项任务并关闭以上 35 项发布阻塞条件后，才能进入最终发布评审。

## 2026-08-29 本轮开发完成记录

- **状态**：`[x] 已完成，等待复审`
- **已完成内容**：补充插件 V1 接口的登录校验、请求字段边界、乐观锁版本冲突、Bot 信息脱敏和测试消息不落库验证；修正 V1 插件页面的 iframe 安全响应头识别；移除前端对已停用旧版插件保存接口的调用。
- **本地验证**：服务端全量 `go test ./... -count=1` 通过；插件控制器和 HTTP 安全头专项测试通过。
- **未完成真实验收**：超级管理员本机重置通道仍需在 Ubuntu 22.04、Windows 部署端和实际权限模型中复审；邮箱验证码、SMTP 投递、WebAuthn、真实浏览器和多实例流程不得标记为最终通过。
- **复审日期**：2026-08-29（本机自动化复审）。

## 2026-08-31 全量代码状态复核

> 本节是 2026-08-31 对当前代码库的增量状态口径。原任务条目中的“未开始”保留为历史计划文本，不再代表当前实现状态；未完成真实平台或外部系统验收的任务不得标记为 `[✓]`。

| 任务范围 | 当前状态 | 复核结论 |
|---|---|---|
| AD-001～AD-008 | `[x] 已完成，等待复审` | 进程模型、权限矩阵、威胁模型、敏感字段、测试矩阵、独立管理程序、严格命令解析和部署管理员检查均已有实现与自动化测试。 |
| AD-009～AD-011 | `[x] 已完成，等待实机复审` | systemd、Windows 服务/ACL、版本绑定和升级约束已有代码或部署文件；真实 Ubuntu 与 Windows 服务环境尚未验收。 |
| AD-012～AD-021 | `[x] 已完成，等待实机复审` | 最小控制协议、UDS、Named Pipe、一次性 nonce、统一密码策略、事务重置、凭据撤销、审计及 Web 超级管理员恢复拒绝均已有实现和负向测试。 |
| AD-022～AD-025 | `[x] 已完成，等待复审` | 外部邮箱模型、加密存储、独立指纹、归属校验、脱敏查询和绑定失效事务已实现。 |
| AD-026～AD-031 | `[x] 已完成，等待复审` | 临时 HMAC 密钥、容量上限、验证码生成、用途绑定、恒定比较、原子消费、统一清理和重启失效已实现。 |
| AD-032～AD-037 | `[x] 已完成，等待外部系统复审` | SMTP Relay 接入、验证码不落盘投递、失败分类、多维限流、运营数据和 14 天分批清理已实现并具备自动化测试。 |
| AD-038 | `[!] 暂缓或存在阻塞` | 三数据库清理代码和方言已具备；真实 MySQL、PostgreSQL 的清理、空间复用和故障恢复尚未执行。 |
| AD-039～AD-059 | `[x] 已完成，等待浏览器与 SMTP 复审` | 统一登录标识、受限会话、二次验证策略、防枚举恢复、分角色恢复、一次性授权、V1 API、前端页面、审计和告警边界均已有实现。 |
| AD-060 | `[x] 已完成，等待复审` | 单元、并发和故障路径自动化测试已建立。 |
| AD-061～AD-064 | `[!] 暂缓或存在阻塞` | 真实三数据库、Ubuntu、Windows、真实浏览器三角色流程需要对应环境和人工交互验收。 |
| AD-065 | `[x] 已完成，等待独立安全复审` | 关键负向、重放、越权、枚举、降级和敏感数据测试已覆盖；生产观测链路仍需复核。 |
| AD-066 | `[!] 暂缓或存在阻塞` | 最终发布评审依赖 AD-038、AD-061～AD-064 以及真实 SMTP、多实例和生产安全审查。 |

### 当前实现证据

- 管理程序与本机控制通道：`backend/cmd/smail-admin`、`backend/services/adminreset`、`deploy/systemd`。
- 外部邮箱与验证码：`backend/services/externalemail`、`backend/services/verification`。
- 恢复和强认证：`backend/services/recovery`、`backend/services/webauthn`、`backend/services/totp`、`backend/services/credentials`。
- API 与前端：`backend/controllers/security.go`、`backend/controllers/webauthn.go`、`backend/listen/http_server/api_v1_compat.go`、`frontend/src/views` 下登录验证、密码恢复、账户安全和强制改密页面。
- 自动化复核：服务端全量、竞态和静态检查以及前端 ESLint、生产构建在本轮最终提交前统一执行并记录。

### 发布结论

三份清单要求的可在当前工作区完成的代码实现已进入待复审状态；真实 Ubuntu 22.04/24.04、Windows Service/ACL/Named Pipe、真实 SMTP Relay、MySQL、PostgreSQL、浏览器三角色、多实例和最终发布安全评审保持阻塞。超级管理员自身重置仍只允许受保护的 UDS 或 Named Pipe，本轮未增加 HTTP、localhost TCP、局域网或公网 TCP 重置入口。


## 2026-09-01 Windows 部署脚本兼容性复核记录

- **关联任务**：AD-009～AD-011、AD-061～AD-063。
- **本轮状态**：`[x] 已完成，等待 Windows 实机复审`。
- **发现并修复**：Windows PowerShell 5.1 直接执行时，原部署脚本因中文内容缺少 UTF-8 BOM 发生解析错误；安装脚本的 `$PSScriptRoot` 参数默认值在参数绑定阶段为空；ACL 在创建 `NT SERVICE\Smail` 服务 SID 前执行，存在真实安装失败风险。
- **修改内容**：为 `deploy/install-windows.ps1` 和 `deploy/uninstall-windows.ps1` 增加 UTF-8 BOM；将安装脚本的 `PackageRoot` 改为参数绑定后回退到 `$PSScriptRoot`；创建或配置 `Smail` 服务后先执行 `sc.exe sidtype Smail unrestricted`，再应用服务 ACL。
- **自动化验证**：`go test ./cmd/smail-admin -count=1 -v` 通过；两个脚本使用 Windows PowerShell 5.1 解析并进入预期的管理员权限拒绝分支；`git diff --check` 通过。
- **未完成真实验收**：当前用户不是管理员，尚未执行真实 SCM 注册、服务 SID、ACL 拒绝和升级失败回滚验收；Ubuntu、MySQL、PostgreSQL、真实 SMTP、浏览器三角色和最终安全评审仍保持原阻塞。
- **复审日期**：2026-09-01（本机自动化复核）。