修复认证挑战与可信代理安全边界（07-17-auth-challenge-trusted-proxy-hardening）

deploy/trialrun/checklist.md

@@ -8,11 +8,13 @@
 - [ ] 已在服务器创建 OA 目录（默认 `/opt/hyb-oa-trialrun`）
 - [ ] 已确认常规 SSH 用户为 `deploy`，系统配置用户为 `root`；当前不依赖 `shunli` 登录
 - [ ] 已准备 `deploy/trialrun/.env`，并将 `APP_ORIGIN` 改为 OA 公网域名
+- [ ] 已配置独立、至少 32 字节的 `AUTH_CODE_PEPPER`，且不是仓库示例占位符
+- [ ] 已将 `TRUST_PROXY_HOPS` 固定为 `1`
 - [ ] 已将 `COOKIE_SECURE` 设为 `true`
 - [ ] 已确认 `deploy/trialrun/.env` 作为部署事实源，新增环境变量优先补到该文件
 - [ ] 已尽量使用无引号 env 值；历史带引号值当前兼容，但建议逐步清理
 - [ ] 已将 OA `Caddyfile` 站点块配置到 `/etc/caddy/Caddyfile`
-- [ ] 已确认 `oa.hyinda.com { reverse_proxy 127.0.0.1:3000 }` 生效
+- [ ] 已确认 Caddy 反代到 `127.0.0.1:3000`，并用 `header_up X-Forwarded-For {remote_host}` 覆盖客户端 XFF
 - [ ] 已执行 `systemctl reload caddy`
 - [ ] 已显式提供 `DEPLOY_SERVER`、`REMOTE_DIR`，并从本地执行 `bash scripts/qa/run-release-gate.sh all` 或至少执行 `bash deploy/trialrun/deploy.sh`
 - [ ] 已通过 `https://<oa-domain>/ready` 或首页登录完成最小探活
@@ -36,6 +38,7 @@
 
 ## B. 发布（Deploy）
 - [ ] 本地工作树 clean，目标 commit 已进入 upstream；部署日志中的 commit 与 `/ready.data.buildSha` 一致
+- [ ] **EXTERNAL_GATED**：操作人已在边缘暂停 `/api/auth/forgot-password`、`/api/auth/reset-password`、`/api/auth/email-login/code`、`/api/auth/email-login/verify`；部署脚本不会自动修改边缘配置，未人工确认四端点关闭不得发布，配置预检、迁移、新应用和 smoke 全部通过后才人工恢复
 - [ ] 标准路径已成功刷新 upstream；若因受控离线恢复使用 unpublished override，日志包含批准原因码和 `UNPUBLISHED-OVERRIDE` 标识
 - [ ] 标准发布通过 `bash deploy/trialrun/deploy.sh` 执行；脚本自动注入完整后端 SHA 与 12 位前端 SHA，并完成构建、init 与 smoke
 - [ ] 若为首次初始化或受控应急而直接使用 Compose，已显式设置 `BUILD_SHA=<approved-full-commit>` 与 `VITE_BUILD_SHA=<matching-12-char-commit>`；未使用 `unknown`
@@ -66,6 +69,7 @@
 ## D. 回滚（Rollback）
 > 原则：如果涉及迁移，最快回滚通常是 “恢复备份 + 回到上个 tag”。
 
+- [ ] **EXTERNAL_GATED**：若回滚目标仍包含旧认证挑战逻辑，人工确认边缘继续关闭 `/api/auth/forgot-password`、`/api/auth/reset-password`、`/api/auth/email-login/code`、`/api/auth/email-login/verify`；脚本不会自动改边缘，未确认不得回滚开放，直到安全版本恢复
 - [ ] 停止 server：`docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env stop server`
 - [ ] 恢复 DB：`./scripts/restore-db.sh <db.dump>`
 - [ ] 恢复存储：`./scripts/restore-storage.sh <storage.tar.gz> deploy/trialrun/data/storage`