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

deploy/trialrun/runbook.md

@@ -7,6 +7,7 @@
 - OA 新增独立二级域名，例如 `oa.hyinda.com`。
 - OA 部署目录由受控环境中的 `REMOTE_DIR` 指定，不在仓库固化机器路径。
 - OA 推荐访问方式：`Caddy(443) -> 127.0.0.1:3000 -> docker-compose(server)`。
+- Caddy 必须覆盖客户端传入的 `X-Forwarded-For`。OA 站点的 `reverse_proxy` 中应设置 `header_up X-Forwarded-For {remote_host}`，不得保留不可信客户端链。
 - 首次初始化时：
   1. 服务器以 root 执行 `bash deploy/trialrun/setup-server.sh`
   2. 手工创建 `deploy/trialrun/.env`
@@ -36,6 +37,8 @@ cp deploy/trialrun/.env.example deploy/trialrun/.env
 
 必须修改：
 - `JWT_SECRET`
+- `AUTH_CODE_PEPPER`（独立随机秘密，至少 32 字节，不得沿用示例占位符或 JWT secret）
+- `TRUST_PROXY_HOPS=1`（当前单跳 Caddy/Nginx 部署固定为 1）
 - `APP_ORIGIN`（建议与对外域名一致，例如 `https://oa.example.com`）
 
 环境变量约束：
@@ -44,6 +47,7 @@ cp deploy/trialrun/.env.example deploy/trialrun/.env
 - 推荐使用无引号值，例如 `COOKIE_SECURE=true`、`PORT=3000`。
 - 历史上已经写成带引号的 `.env` 当前仍兼容，但建议后续逐步改成无引号。
 - 正式部署前可先执行 `node deploy/trialrun/validate-env-contract.js` 做静态契约检查。
+- **EXTERNAL_GATED**：涉及认证安全迁移时，发布或回滚前必须由操作人先在边缘暂停 `/api/auth/forgot-password`、`/api/auth/reset-password`、`/api/auth/email-login/code`、`/api/auth/email-login/verify` 四个 challenge 端点，再执行“新镜像配置预检 -> additive migration -> 新应用切换”。部署脚本不会自动修改边缘配置；未人工确认四端点已关闭不得发布或回滚开放。仅在安全版本及 smoke 全部通过后人工恢复；若回滚到旧认证代码，四端点必须继续关闭。
 
 作业系统建议：
 - 试运行默认 `JOB_DRIVER=pgboss`（基于 Postgres 的队列调度，单机/多进程语义更稳）
@@ -61,6 +65,8 @@ node deploy/trialrun/validate-env-contract.js
 export BUILD_SHA="<approved-full-commit>"
 export VITE_BUILD_SHA="<matching-12-char-commit>"
 docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d db
+docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env build init
+docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env run --rm init
 docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d --build server
 ```
 
@@ -88,6 +94,7 @@ docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/
 
 说明：
 - `init` 是一次性任务：`migrate:deploy + seed:config + seed:trialrun`。
+- 初始化必须发生在依赖新增列的新 server 切换之前；正式部署脚本会先用新 init 镜像校验生产配置并执行迁移，再替换 server。
 - 若 `TRIALRUN_ADMIN_PASSWORD` 为空，seed 会生成一次性口令并输出到控制台（请立刻保存）。
 - 正式启用前，推荐先保持“空基线 + 默认种子”，不要直接导入开发库、测试库或旧 OA 整库备份。
 - 如确需导入，仅导入最小必要主数据：部门、员工、角色、在用资产、活跃项目、合同元数据。