mailgo/security_todo.md

安全漏洞修复 TODO

依据 2026-08-19 首轮安全审计（代码静态审计 + mail.lmve.net 线上验证）、2026-08-20 第二轮审计、2026-08-28 第三轮审计（代码静态审计）整理。

按优先级排列：P0 立即修复，P1 尽快修复，P2 排期修复，P3 加固项。条目编号为发现顺序（跨轮次唯一，非严重度排序）；第三轮发现（#19-#26）已按等级归并至下列 P1-P3 区块，标题注明轮次与日期。

第三轮（2026-08-28）结论：未发现 SQL 注入、路径穿越、开放中继、越权访问、XSS 等高危漏洞，前两轮修复（#1-#18）均验证到位；新发现问题集中在资源滥用/配额记账缺陷与防御深度缺失两类。执行顺序注意：#20 必须先于（或随）#19 落地——配额退还先于配额强制，否则用户会因幽灵占用被误拒收。

P0 严重：可被完全接管

1. 会话签名密钥硬编码，可伪造任意管理员会话

• 位置：internal/web/server.go:176
• 现状：cookie.NewStore([]byte("mail-go-secret-key-change-in-production"))，密钥写死在源码中且无配置项可更换。源码公开 = 任何人可签发 userID=1, isAdmin=true 的合法 cookie，直接以管理员身份进入线上后台。
• 修复方案：
  • config.Config 新增 [web] secret_key 字段。
  • LoadConfig() 首次启动时用 crypto/rand 生成 32 字节随机密钥（hex 编码）写入配置文件；配置文件权限收紧为 0600（兼顾原有的中继密码等敏感字段）。
  • 支持环境变量 MAILGO_SECRET_KEY 覆盖（覆盖值不落盘，便于容器部署）。
  • 启动时校验：密钥为空 / 等于旧硬编码默认值 / 短于 16 字节时拒绝启动（config.ValidateSecretKey + NewWebServer 返回 error）。
• 验证：
  • 重启后旧 cookie 全部失效（登录态被踢下线）。
  • 用旧硬编码密钥手工签发的 cookie 无法通过认证（TestLegacyHardcodedKeyCannotForgeSession：伪造 userID=1, isAdmin=true 的 cookie 被拒，302 回登录页）。
  • config.LoadConfig() 单测：首启生成、二次读取保持不变、旧配置补全、旧默认值替换、env 覆盖不落盘、文件权限 0600（config/config_test.go）。
• 已完成（2026-08-19）。注：部署新版后所有用户需重新登录；配置文件权限由 0644 收紧为 0600。

P1 高危

2. OAuth2 state 固定值且回调不校验（登录 CSRF / 授权码注入）

• 位置：internal/web/handlers/auth.go（原硬编码 mailgo_oauth2_state、OAuth2Callback 不校验 state）
• 现状：当前部署未启用 OAuth2，属休眠漏洞，启用前必须修复。
• 修复方案：
  • OAuth2Start 用 crypto/rand 生成 16 字节随机 state，写入独立的短期 SameSite=Lax cookie（mail_go_oauth2_state，10 分钟过期，HttpOnly+Secure）。注意主会话 cookie 是 SameSite=Strict，跨站回调导航不会携带，故不能放主会话。
  • OAuth2Callback 读取 c.Query("state") 与 cookie 值做 subtle.ConstantTimeCompare 比对，缺失/不匹配返回 403。
  • 比对后立即清除 cookie（MaxAge=-1），保证一次性使用。
• 验证：
  • 单测：state 缺失/不匹配/无 cookie 均 403；start 设置的 cookie 与 URL state 一致且每次不同；有效 state 通过校验进入后续流程（oauth2_state_test.go）。
  • 手工走完一次 OAuth2 流程（Google/GitHub）确认正常登录。

3. Gin 信任所有代理，ClientIP() 可伪造（封禁绕过 / 爆破）

• 位置：internal/web/server.go（未调用 SetTrustedProxies）
• 现状：gin 默认信任 0.0.0.0/0，X-Forwarded-For 可任意伪造。线上 8080 端口当前被防火墙挡住，属纵深防御缺失；一旦 8080/socket 可达：伪造不同 IP 即可绕过登录失败封禁无限爆破，也可恶意封禁任意 IP 造成 DoS。
• 修复方案：
  • 统一 engine.SetTrustedProxies([]string{"127.0.0.1", "::1"})：外部直连时 XFF 完全不可信（防伪造/防封禁污染）；本机 Caddy/Nginx 转发时 XFF 仍可信（保留真实客户端 IP）。注意 gin 对 Unix socket 监听无条件信任转发头，socket 必须保持仅本机可达。
  • install.sh 文档注明：8080 端口必须保持仅本机可达（防火墙/绑定 127.0.0.1）。
• 验证：
  • 单测：外部直连 + 伪造 X-Forwarded-For 时封禁记录落在真实 IP 上；回环代理 + XFF 时记录 XFF 中的真实客户端 IP（trustedproxy_test.go）。
  • 线上回归：Caddy 反代路径下管理后台封禁列表仍显示真实客户端 IP。

4. Web 写信 CRLF 邮件头注入

• 位置：internal/web/handlers/mail.go（原 to/cc/subject 直接拼头、附件文件名拼进 Content-Disposition/Content-Type）
• 现状：信封收件人经 ParseAddress 校验无法注入，但注入的头（如 Reply-To）会随邮件存储并外发，可被用于钓鱼。
• 修复方案：
  • 新增 sanitizeHeaderField：strip \r、\n、NUL，应用于 From/To/Cc 头。
  • subject 经 sanitizeHeaderField + RFC 2047（mime.QEncoding）编码非 ASCII 内容。
  • 附件名经 mime.FormatMediaType 生成 Content-Disposition/Content-Type name 参数（RFC 2231 编码，中和 CRLF 注入）。
  • 消息构建抽出为 buildOutgoingMessage 纯函数（可单测）；DownloadAttachment/AdminDownloadAttachment 的响应头同步改用 formatContentDisposition。
• 验证：
  • 单测：to/cc/subject 携带 CRLF 注入载荷时 RawData 无独立注入头；文件名含 CRLF/引号时头结构完好；非 ASCII 主题正确编码（mail_injection_test.go）。
  • 含特殊字符附件名的邮件实测收发正常。

19. SMTP 入站投递不强制配额 —— 磁盘耗尽 DoS（第三轮，2026-08-28）

• 位置：internal/smtp_server/server.go:493（saveMessage，记账在 532 行）
• 现状：入站邮件附件直接落盘，UpdateUsedBytes 只记账不检查配额。对比 Web 上传路径有 TryReserveQuota 原子预扣（user_store.go:191），入站路径配额形同虚设。任何外部发件人可投递 64MB（MaxMessage）× 无限封邮件（附件落盘 + RawData 整封入库双份存储）直到磁盘写满，导致全部用户服务中断；多用户租户场景配额承诺无法兑现。
• 修复方案：
  • saveMessage 前调用 TryReserveQuota 预扣附件总大小（无附件时跳过）。→ 实现 reserveLocalQuota：按用户聚合预扣（重复 RCPT TO 投递多份），任一收件人不足则回退全部已预扣量，整封原子拒收
  • 超限返回 smtp.SMTPError{Code: 452, ...}（insufficient storage，临时失败语义，发件方按退避重试）。注意：go-smtp 对 Data() 返回的普通 error 一律映射为 554 永久失败（conn.go dataErrorToStatus），语义错误会导致对方服务器直接退信。
  • 入库/落盘失败时补偿回退预扣字节。→ saveMessage 返回实际落库字节数，reconcileQuota 对账退还差额（覆盖收件人被删/落库失败/部分附件失败）；Sent 副本为尽力而为：预扣失败仅跳过副本并记日志，不回滚整封
• 验证：
  • 单测：配额已满时入站投递被拒（452）、used_bytes 不变；配额充足时正常投递记账。（TestInboundQuotaRejectsOverQuotaRecipient / TestInboundQuotaDeliversWithinQuota / TestInboundQuotaReconcilesRefund）
  • 回归：本地投递 + 外发队列 + Sent 副本路径不受影响。（go test ./... 全量通过）
• 已完成（2026-08-28）。

20. 删除邮件不删附件文件、不退配额 —— 幽灵配额（第三轮新发现，2026-08-28）

• 位置：internal/imap_server/session.go:956（Expunge）、internal/pop3_server/server.go:551（expungeDeleted）
• 现状：两处只调 Mails.Delete/DeleteMany，不删附件文件、不回退 UsedBytes——配额只增不减。Web 侧 purgeMessages（web/handlers/mail.go:103）是完整实现（storage.Delete + DeleteByMessage + UpdateUsedBytes 回退），协议侧缺失。与 #19 配套必须修复，否则强制配额后用户会因幽灵占用被拒收且无法自助恢复。
• 修复方案：
  • 抽取共享清理入口（store 层）：删附件记录前先 Attachments.ListByMessage 取文件路径，storage.Delete + UpdateUsedBytes(userID, -FileSize) 回退，再删记录与邮件。→ 新增 store.PurgeMessages（Web/IMAP/POP3 同源）
  • IMAP Expunge（含 UID EXPUNGE 分支）与 POP3 expungeDeleted 接入。
  • IMAP 服务器需注入 AttachmentStorage（NewIMAPServer 当前无此依赖）；注意 pop3_server_test.go:29 直接构造 POP3Server{stores:...}、imap_server 两个测试文件直接构造服务器的用例需同步。→ NewIMAPServer/NewPOP3Server 增参，main.go 与三个测试文件已同步
• 验证：
  • 单测：带附件邮件经 IMAP EXPUNGE / POP3 DELE+QUIT 删除后附件文件消失、used_bytes 回退。（TestExpungeDeletedRemovesAttachmentsAndRefundsQuota 覆盖 POP3 路径与共享入口；IMAP EXPUNGE 为同一入口的薄接线）
• 已完成（2026-08-28）。注：Web 侧 purgeMessages 改为委托同一入口，消除三处重复实现。

P2 中危

5. 会话 Cookie 缺 Secure 标志

• 位置：internal/web/server.go
• 修复方案：
  • sessions.Options 增加 Secure: cfg.CookieSecure；新增配置项 [web].cookie_secure（默认 true，仅本地 HTTP 调试时改 false；缺失字段按默认 true 处理，参照 relay_starttls 的原始文件检查）。
  • 修正 SameSite 注释（3 = Strict）。
  • 测试：会话 cookie 断言 HttpOnly+Secure+SameSite=Strict。
• 验证：
  • 测试断言 cookie 标志。
  • 线上登录后检查 Set-Cookie 包含 Secure; HttpOnly; SameSite=Strict。

6. SMTP/IMAP/POP3 认证无速率限制

• 位置：internal/smtp_server/server.go、internal/imap_server/、internal/pop3_server/server.go
• 修复方案：
  • store.RecordAuthFailure(ip, maxFail, minutes)：认证失败计数复用 BanStore，达到 ban.max_fail_attempts 阈值即封禁 ban.ban_duration_min 分钟（与 Web 登录共用封禁记录）。
  • SMTP：NewSession 记录 c.Conn().RemoteAddr() 提取 IP；Auth 回调失败计数 + 封禁 IP 拒绝认证。
  • IMAP：Login(connInfo,...) 从 connInfo.RemoteAddr 取 IP；失败计数 + 封禁拒绝。
  • POP3：handleConn 开头检查封禁直接拒绝；handlePASS 失败计数。
  • 三个服务器构造函数注入 config.BanConfig。
• 验证：
  • store 层单测：达到阈值封禁、空 IP 无副作用、与 Web 共用封禁记录（auth_guard_test.go）。
  • 线上用错误密码连续尝试触发封禁后，SMTP/IMAP/POP3 认证被拒。

7. 附件存储路径遍历防护无效

• 位置：internal/storage/attachment.go
• 修复方案：
  • FullPath 改为白名单校验（UUID 文件名正则），非法路径返回错误；兜底校验最终路径仍在 baseDir 内。
  • Save 的扩展名白名单化（safeExt，丢弃 CR/LF、路径分隔符等）。
• 验证：
  • 单测：../、绝对路径、Windows 分隔符、空路径、注入文件名全部拒绝；合法文件名正常读写删（attachment_test.go）。

8. 默认管理员 admin@example.com/admin

• 位置：main.go（ensureAdminUser）
• 修复方案：
  • 初始密码改为：环境变量 MAILGO_ADMIN_PASSWORD 显式指定，否则生成 16 位随机密码打印一次。
  • User 模型新增 MustChangePassword：初始管理员、管理员重置密码的用户在登录后强制跳转设置页改密，改密后清除标记（UpdatePassword 顺带清除）。
  • AuthMiddleware 拦截（除 /settings、/logout），settings 页显示提示横幅。
• 验证：
  • 全新数据库启动后 admin/admin 无法登录（密码为随机值）；登录后强制改密流程生效。
  • 线上验证新装机流程。

9. Smarthost 中继 TLS 不验证证书（凭据可被 MITM 截获）

• 位置：internal/outbound/mailer.go
• 修复方案：
  • 直投 MX 保持机会式 TLS（InsecureSkipVerify=true，业界常规）；relay 路径默认验证证书（InsecureSkipVerify=false），IP literal 时以 IP 作为 ServerName 校验 IP SAN。
  • 新增配置 outbound.relay_tls_insecure（默认 false），供自签证书内网中继显式放行。
• 验证：
  • 集成测试：自签证书 STARTTLS 中继默认握手失败（certificate 错误）、开启开关后完整 SMTP 流程成功（mailer_test.go 两个新测试）。

10. 缺安全响应头（点击劫持/降级风险）

• 位置：internal/web/middleware/security.go（新中间件，全局注册）
• 修复方案：
  • Strict-Transport-Security: max-age=31536000; includeSubDomains
  • X-Frame-Options: DENY + CSP frame-ancestors 'none'（点击劫持）
  • X-Content-Type-Options: nosniff
  • Referrer-Policy: strict-origin-when-cross-origin
  • 基础 CSP：default-src 'self' + 放宽项（内联脚本/样式必须 unsafe-inline；img-src https: 允许邮件远程图片；connect-src 'self'/form-action 'self' 防数据外泄）。CSP 具体策略在 security.go 顶部注释说明。
• 验证：
  • 单测：5 个头均存在，关键值抽查（security_test.go）。
  • 线上回归：登录/收件箱/管理页功能不受 CSP 影响；邮件远程图片正常加载。

11. LDAP/OAuth 错误信息泄露与用户枚举

• 位置：internal/web/handlers/auth.go
• 修复方案：
  • 错误提示统一为通用文案（"LDAP 认证失败…"、"LDAP 账号未接入本系统…"、"OAuth2 认证失败…"），原始 err 只写日志，不回显页面；不再在提示中回显用户邮箱。
• 验证：
  • 现有 OAuth2 测试仍通过（错误页文案不含内部细节）。
  • 线上（启用 LDAP/OAuth 后）验证失败页面不含内部地址/DN/原始错误串。

21. Web 发信配额预扣泄漏（第三轮，2026-08-28）

• 位置：internal/web/handlers/mail.go:278（预扣）→ 367 / 390 / 416（泄漏点）
• 现状：TryReserveQuota 预扣附件配额后，三处提前 return 不回退：外部收件人入队失败（367）、本地投递失败（390）、Sent 副本保存失败（416）。文件读取失败（310）与附件保存失败（426）有回退，上述路径漏了。用户反复提交含无效外部地址的带附件邮件，可把自己配额扣光且无对应文件占用（配额"凭空消失"，需管理员改库恢复）。
• 修复方案：
  • defer + 成功标志统一补偿：未走到"附件记录全部落库"终点即回退剩余预扣量；或各失败分支显式回退。
  • 注意 367 处入队失败时可能已成功入队部分外部收件人，只回退附件未消耗部分。
• 验证：
  • 单测：外部入队失败 / 本地投递失败路径退出后 used_bytes 恢复原值。

22. OAuth2 登录不校验邮箱 verified 状态（第三轮，2026-08-28）

• 位置：internal/auth/oauth2.go:111-127
• 现状：GitHub /user/emails 响应含 verified 字段但未检查，取 primary 首个即用；Google 未检查 email_verified。当前 GitHub 该 API 实际只返回已验证邮箱，现实可利用性低，但属依赖 IdP 实现细节；自建 provider（代码 33-36 行支持任意 host）场景下未验证邮箱可登录他人账号。
• 修复方案：
  • GitHub：过滤 verified == true（primary 优先），无已验证邮箱返回错误。
  • Google：解析 email_verified，false 或缺失时拒绝。
• 验证：
  • 单测：构造含未验证邮箱的响应被拒。

P3 低危 / 加固

12. Referer 开放重定向

• 位置：internal/web/handlers/mail.go（Delete/MarkRead）
• 修复：新增 safeRedirectPath——仅接受以 / 开头且非 // 的同站相对路径，外部 URL/协议跳转一律回退 /inbox。
• 验证：
  • 单测：https://evil.com/、//evil.com、javascript: 等拒绝，相对路径放行（TestSafeRedirectPath）。

13. Web 发信配额检查 TOCTOU

• 位置：internal/web/handlers/mail.go、internal/store/user_store.go
• 修复：新增 UserStore.TryReserveQuota（单条原子 SQL UPDATE ... WHERE used_bytes + ? <= quota_bytes），DoSend 先原子预扣全部附件大小，超配额即拒发；后续读取/保存/落库失败的附件按大小补偿回退。
• 验证：
  • 单测：预扣到配额上限、超额拒绝且不部分扣费、释放后可再扣、非正 delta 拒绝（TestTryReserveQuota*）。

14. compose 页 safeJS 在 JS 上下文绕过转义（自 XSS）

• 位置：internal/web/templates/compose.html、internal/web/server.go
• 修复：新增 jsonify 模板函数（json.Marshal，默认转义 < > & 为 \u003c 等，无法逃出 </script>）；quill.root.innerHTML 改用 jsonify。移除 templateFuncs 中危险的 safeHTML/safeJS；view/admin 模板的 srcdoc 改回默认属性转义（行为一致，前已实测）。
• 验证：
  • 单测：</script> 载荷不产生裸逃逸、控制字符转义、输出为合法字符串字面量（TestJsonifyEscapesScriptBreakout）；全模板渲染测试通过。

15. Content-Disposition 文件名未编码

• 位置：internal/web/handlers/mail.go、internal/web/handlers/admin.go
• 修复：随 P1 #4 一并完成——formatContentDisposition 使用 mime.FormatMediaType（RFC 2231），两处下载端点均已应用，并有 TestFormatContentDisposition 覆盖。

16. 会话治理

• 位置：internal/web/handlers/auth.go、internal/web/middleware/auth.go
• 修复：登录成功（Web/LDAP/OAuth2 三处）先 session.Clear() 清旧状态再写入；会话记录 loginAt，AuthMiddleware 实施绝对过期 7 天（超时强制登出）+ 滑动续期（活跃会话每 12 小时写回刷新）。
• 验证：
  • 单测：8 天前的会话被重定向登录页；1 小时前的会话正常访问（用配置密钥签名构造会话，TestSessionAbsoluteExpiryForcesRelogin/TestSessionWithinExpiryWorks）。

23. 管理员建用户/域名无格式校验（第三轮，2026-08-28）

• 位置：internal/web/handlers/admin.go（CreateUser:612 / UpdateUser:737 / CreateDomain:222）
• 现状：username 可含 @、空格、控制字符；域名无任何校验。用户名 a@evil 生成邮箱 a@evil@example.com，GetByEmail 的 SplitN("@", 2)（user_store.go:75）解析错位，认证与投递路由混乱；畸形数据也会进入 IMAP 邮箱视图。
• 修复方案：
  • 用户名白名单 ^[a-zA-Z0-9._-]+$、长度 ≤64；域名小写字母数字/连字符/至少一个点、长度 ≤253。
  • UpdateUser 改名/换域名同样校验；错误回显走 i18n。
• 验证：
  • 单测：a@evil、含空格/控制字符用户名被拒；畸形域名被拒；合法输入通过。

24. 密码无最小长度要求（第三轮，2026-08-28）

• 位置：internal/web/handlers/mail.go:849（自助修改）、internal/web/handlers/admin.go:638/771（创建/重置）
• 现状：新密码仅检查非空，1 位密码也接受，与系统整体安全水位不匹配。
• 修复方案：
  • 统一最小长度 8（NIST SP 800-63B：长度优先于复杂度），三处共用校验函数 + i18n 文案。
• 验证：
  • 单测：7 位拒绝、8 位通过。

25. POP3/IMAP 允许明文认证（第三轮，2026-08-28）

• 位置：internal/pop3_server/server.go:390（handlePASS）、internal/imap_server/session.go:212（Login）
• 现状：非 TLS 连接上 USER/PASS、LOGIN 明文传输无限制，被动嗅探可截获密码。自签证书总是自动生成，STLS/STARTTLS 能力具备（POP3 CAPA 已宣告 STLS）。
• 修复方案：
  • 回环来源放行（本地调试）；非回环要求连接已 TLS（POP3 tlsActive / IMAP NetConn() 为 *tls.Conn）才接受认证，否则提示先执行 STLS/STARTTLS。
  • 加配置项控制（默认强制），不破坏极端明文内网部署。
• 验证：
  • 单测：非 TLS 非回环认证被拒并提示；TLS 后成功；回环明文可用。

26. 加固建议（第三轮，2026-08-28，可选排期）

• CSP script-src 'unsafe-inline'（middleware/security.go:19）：长期改 nonce 方案，恢复 XSS 纵深防御。
• 邮件远程图片（CSP img-src https:）：默认屏蔽、点击加载，防追踪像素泄露收件人 IP/UA。
• 入站邮件 SPF/DKIM/DMARC 验证：当前伪造发件人的钓鱼邮件原样入库展示。
• Unix socket 0666（web/server.go:493）：本地多用户主机依赖目录权限兜底，可收紧 0660。
• RawData 双份存储（附件落盘 + 整封 RawData 入库）：存储翻倍，放大 #19 的 DoS 效果。

27. IncrementFail 并发首建窗口丢失更新（第三轮修复过程中发现，存量问题）

• 位置：internal/store/ban_store.go（IncrementFail）
• 现状：UPDATE 未命中（RowsAffected=0）后 INSERT 用 OnConflict DoNothing 兜底——两个 goroutine 的 UPDATE 可都在记录存在前提交，随后 INSERT 竞争，败者被 DoNothing 吞掉、自增丢失，最终 fail_count 少 1。生产影响极小（仅同 IP 首次失败瞬时并发时计数少 1，后续自增自愈），但 TestIncrementFailConcurrent（16×5 并发，断言精确 80）会因此偶发失败：-race 多包并行时观察到一次；干净树验证非第三轮改动引入（改动仅新增 purge.go，未被该测试触及）。
• 修复方案：
  • 失败 INSERT 改为冲突时自增：OnConflict{Columns: ip_address, DoUpdates: fail_count = fail_count + 1}（SQLite ≥3.24 / MySQL 均支持，约 3 行改动），消除首建窗口的丢失更新。
• 验证：
  • go test -race -count=N ./internal/store/ 多轮稳定通过。

已确认安全、无需改动

• bcrypt 密码哈希；GORM 全参数化查询（无 SQL 注入）。
• SMTP 非开放中继、认证用户强制 From=登录身份。
• LDAP 过滤器已 EscapeFilter。
• 邮件 HTML 经 sandbox iframe（无 allow-scripts）渲染，srcdoc 属性转义经实测有效，无存储型 XSS。
• Web 登录错误提示不区分用户是否存在（无枚举）。

第三轮（2026-08-28）复查确认：

• 存储层 GORM 全参数化（无 SQL 注入）；附件路径 UUID 白名单 + 前缀校验（无路径穿越）。
• SMTP 非开放中继、认证用户强制 From=登录身份；Web/管理端路由权限校验全链路到位。
• 邮件 HTML 经 sandbox iframe 渲染 + jsonify 转义（无存储型 XSS）；会话 SameSite=Strict + 7 天绝对过期 + 滑动续期。
• 邮件头 CRLF 注入过滤；OAuth2 state 常量时间比较 + 一次性；LDAP EscapeFilter；Referer 同站回跳。
• 配置密钥治理（旧硬编码拒绝启动、配置 0600、env 覆盖不落盘）；仅信任回环代理。

修复顺序建议

1. #1（P0） 已完成 2026-08-19
2. #2、#3、#4（P1） 已完成 2026-08-19
3. #5-#11（P2） 已完成 2026-08-19
4. #12-#16（P3） 已完成 2026-08-19
5. #17（P4）、#18（P5，方案 A） 已完成 2026-08-20
6. 第三轮（#19-#26，2026-08-28）待实施，已按安全等级归并至上文 P1-P3 区块；实施顺序见文末「第三轮修复顺序建议」。

P4 低危：第二轮审计发现（2026-08-20，8ea4a62..37b4816）

17. 手动封禁 Create 非 upsert，与阶段性封禁体系数据错位

• 位置：internal/web/handlers/admin.go（DisconnectConnection）、internal/store/ban_store.go、internal/db/models.go、internal/db/db.go
• 现状：f2493da 阶段性封禁已改为"每 IP 一条记录 upsert"（RecordAuthFailure 内部 GetByIP + Update），但管理员"断开并封禁"仍直接 Create。ip_address 无唯一索引，当目标 IP 已有失败计数记录时会插入第二条记录，造成：
  • IncrementFail 用 First（默认主键升序）更新旧行，GetByIP 用 Order("id DESC") 返回新行 -> 自动封禁的档位判定（BanCount）与失败计数（FailCount）读写错行；
  • UnbanIP 按 ID 删除一行后另一行仍在，可能出现"解封后仍被旧记录挡住/计数异常"。
• 修复方案：
  • BanStore 新增 BanIP(ip, reason, duration)：事务内删除该 IP 全部既有记录（兼容历史脏数据）后插入单条封禁记录，计数清零（与"管理员解封清零"语义一致）；DisconnectConnection 改用该方法。
  • BanEntry.IPAddress 升级为 uniqueIndex；InitDB 在 AutoMigrate 前调用 dedupeBanEntries 清理历史重复行（保留每 IP 最大 id，SQLite/MySQL 兼容的派生表写法），表不存在时静默。
  • IncrementFail 原子化：SQL 侧 fail_count + 1，miss 时 OnConflict DoNothing 插入兜底并发竞态，回读计数。
• 验证：
  • 单测：已有观察记录的 IP 手动封禁后仅一条、计数清零、封禁生效（TestBanIPUpsertSingleRow）。
  • 单测：同 IP 第二条记录被唯一约束拒绝（TestBanEntryUniqueIndex）。
  • 并发单测（-race）：16 协程并发 IncrementFail 计数精确无重复行（TestIncrementFailConcurrent）。
  • db 包单测：旧表重复行清理保留最大 id、表不存在静默（dedupe_test.go）。

P5 备注：产品权衡项（需决策后实施）

18. 阶段性封禁"前 3 次触发不封禁"降低爆破门槛

• 位置：internal/store/auth_guard.go（RecordAuthFailure）、internal/store/user_store.go（LoginExists）、Web/LDAP/SMTP/IMAP/POP3 五处调用点
• 现状：为防误封手机客户端（配置向导探测、裸用户名重试等），达到失败阈值记为一次触发，前 3 次只计数不封禁。副作用：攻击者每次触发前可"免费"尝试 max_fail_attempts（默认 5）次，即约 15 次失败尝试零封禁；第 4 次起才进入 30min -> 3h -> 3 个月 -> 半年的递增档位。长期防护足够，但自动化爆破的起步门槛降低。
• 已实施（方案 A，2026-08-20）：
  • RecordAuthFailure 新增 knownUser bool 参数：用户名存在（真实用户输错）保留前 3 次宽限；用户名不存在（枚举型爆破）跳过宽限、首次触发即按第 1 档封禁，封禁原因注明"未知用户名，跳过宽限"。
  • 新增 UserStore.LoginExists(login)（完整邮箱或裸用户名），五个失败调用点按场景传入：Web 登录查邮箱存在性；SMTP/IMAP/POP3 用登录名查；LDAP 侧存在性无法判定，保守按已知用户处理（防误封）。
• 验证：
  • A：未知用户名第 1 次触发即封（30 分钟，reason 含"未知用户名"）（TestRecordAuthFailureUnknownUserSkipsGrace）。
  • 已知用户名前 3 次触发不封、第 4 次封第 1 档（回归）（TestRecordAuthFailureKnownUserKeepsGrace）。
  • LoginExists 邮箱/裸用户名/不存在/空输入矩阵（TestLoginExists）。
• 决策记录：方案 A（按失败性质区分宽限：真实用户防误封，枚举爆破即时封禁）——在不改变正常用户体验的前提下，让针对不存在账号的字典爆破首次达到阈值即被封，兼顾误封防护与爆破门槛。

部署侧建议（非代码项）

• Caddy 加固（可选，应用层已加安全头）、8080 端口保持仅本机可达。
• GitHub 仓库中 3 个 50MB+ 的 exe 文件（mailgo.exe / mail_go.exe / mailgo_qa.exe）建议改用 Git LFS 或从历史中删除。
• 线上验证：部署新版后检查登录/收件箱/管理页、协议认证封禁、邮件远程图片加载（CSP 影响）。

第三轮修复顺序建议（#19-#27，实施顺序 ≠ 安全等级）

1. #20（先修删除退配额，数据一致性基础） 已完成 2026-08-28
2. #19（入站配额强制，依赖 #20） 已完成 2026-08-28
3. #21（Web 预扣泄漏）
4. #24、#23（一行校验类）
5. #22、#25
6. #26 按需排期
7. #27（存量丢失更新，约 3 行改动，可顺手修）