M4-T09: document login hardening, finalize OpenAPI and roadmap

README.md

@@ -6,7 +6,7 @@
 
 - FastAPI Web 应用（React SPA 前端 + JSON API）
 - SQLite + SQLAlchemy + Alembic 的单库结构
-- username/password + server-side session 鉴权
+- username/password + server-side session 鉴权（含登录加固，见下文）
 - runtime config 页面与 app DB 持久化
 - public IPv4 monitor、历史持久化与定时检查
 - SMTP 配置、测试发信与 public IPv4 changed 邮件通知
@@ -228,6 +228,59 @@ React SPA 主要页面路由（客户端路由，均由 FastAPI fallback 到 `in
 
 无论是本地 `host:port` 还是反向代理后的域名访问，登录成功后进入 SPA 首页（`/`）。
 
+## M4 登录加固
+
+M4 在基础鉴权之上叠加了三层防御，详细说明见 [`docs/auth.md`](./docs/auth.md)。
+
+### 防爆破 / 指数退避
+
+登录失败超过 3 次后进入指数退避（`wait = min(900s, 1s × 2^(failures-3))`），期间请求返回 `429 Too Many Requests`（含 `Retry-After` 响应头）；成功登录后自动清零。退避按 **client IP** 与 **username** 双键取较大值，不会因此永久锁定账号（只是延迟，不是封号）。
+
+- 全局开关：`AUTH_LOGIN_THROTTLE_ENABLED`（CONFIG_FIELDS，默认 `true`）
+- 反代后需要 `AUTH_TRUST_FORWARDED_FOR=true` 才会读 `X-Forwarded-For`（`.env` 部署级配置，默认 `false`）
+
+### CLI 逃生通道
+
+拿到服务器 CLI 权限时，可以在**不依赖任何已存凭据**（无需密码、恢复码）的情况下重置密码、解锁退避、关停 TOTP：
+
+```bash
+# 重置密码（不加 --password 则交互式输入，不回显）
+python -m scripts.admin_cli reset-password admin
+
+# 解锁退避（被 429 挡住时使用）
+python -m scripts.admin_cli unlock --all            # 清所有退避行
+python -m scripts.admin_cli unlock --ip 1.2.3.4    # 按 IP 清
+python -m scripts.admin_cli unlock --username admin # 按 username 清
+
+# TOTP 相关（需要先启用，见下文）
+python -m scripts.admin_cli disable-totp admin     # 关停 TOTP（零凭据，逃生口）
+python -m scripts.admin_cli reissue-totp admin     # 重新发放 TOTP secret（打印新 URI）
+
+# 查看用户列表
+python -m scripts.admin_cli list-admin
+```
+
+在 Docker 容器内执行时：
+
+```bash
+docker compose exec app python -m scripts.admin_cli <command>
+```
+
+### 可选 TOTP 二次验证
+
+admin 可在 React SPA 设置页（`/config`）自选启用 RFC 6238 TOTP：
+
+1. 设置页点「启用 TOTP」→ 后端生成 `otpauth://` URI，前端渲染二维码（`qrcode.react`）
+2. 用 Authenticator App（如 Google Authenticator、Authy）扫码
+3. 输入当前 6 位动态码确认 → TOTP 启用
+4. 妥善保存一次性展示的 10 个恢复码（格式 `xxxx-xxxx`）
+
+启用后，登录需要两步：密码 → 6 位动态码（或恢复码，一次性）。不启用则维持纯密码登录，行为不变。
+
+恢复码丢失时，可用 CLI 逃生：`python -m scripts.admin_cli disable-totp admin`，随后即可纯密码登录。
+
+TOTP issuer 标签（显示在 Authenticator 里）通过 `AUTH_TOTP_ISSUER` 环境变量配置（`.env` 部署级），默认回退 `app_name`。
+
 ## Config 持久化
 
 当前 config 页面不会把修改写回 `.env`。