M4-T09: document login hardening, finalize OpenAPI and roadmap
This commit is contained in:
+191
-82
@@ -1,120 +1,229 @@
|
||||
# 基础鉴权说明
|
||||
# 鉴权说明
|
||||
|
||||
本文档说明当前 Python 重构项目里已经落地的第一版鉴权基座。
|
||||
|
||||
这一轮只解决：
|
||||
|
||||
- 登录页
|
||||
- 登录 / 登出流程
|
||||
- server-side session
|
||||
- 一个最小受保护页面
|
||||
|
||||
这一轮明确不解决：
|
||||
|
||||
- 完整 config persistence
|
||||
- 完整 config CRUD
|
||||
- 多用户权限系统
|
||||
- OAuth / SSO / RBAC
|
||||
本文档说明当前已落地的鉴权基座（基础 session 鉴权 + M4 登录加固）。
|
||||
|
||||
## 当前 auth 模型
|
||||
|
||||
- 认证方式：`username/password`
|
||||
- 认证方式：`username/password`（可选启用 TOTP 二次验证）
|
||||
- 会话方式：server-side session
|
||||
- 客户端凭据：session cookie
|
||||
- 页面形态：Jinja server-side template
|
||||
|
||||
## 当前持久化
|
||||
## 持久化
|
||||
|
||||
当前新增一个共享 App DB：
|
||||
所有 auth 相关数据存放在单一 App DB（`APP_DATABASE_URL`，默认 `sqlite:///./data/app.db`）中：
|
||||
|
||||
- `APP_DATABASE_URL`
|
||||
- 默认值：`sqlite:///./data/app.db`
|
||||
|
||||
当前 auth 相关数据存放在这个 DB 中：
|
||||
|
||||
- `auth_users`
|
||||
- `auth_sessions`
|
||||
- `app_config`
|
||||
|
||||
当前没有把 auth 数据和 `location` / `poo` DB 混放。
|
||||
|
||||
当前这部分现在也走 Alembic 管理：
|
||||
|
||||
- Alembic 环境：`alembic_app.ini` + `alembic_app/`
|
||||
- 初始化脚本：`python scripts/app_db_adopt.py`
|
||||
|
||||
当前没有 legacy app DB，所以这一版脚本只负责初始化新库，不负责 legacy adoption。
|
||||
|
||||
`app_config` 现在承接运行时配置持久化。
|
||||
|
||||
其中：
|
||||
|
||||
- `.env` 负责 bootstrap / fallback
|
||||
- `app_config` 表负责运行时配置覆盖
|
||||
- 登录密码仍然属于认证数据，使用 Argon2 哈希，不存进 `app_config`
|
||||
- `auth_users`：用户表（含 TOTP 字段 `totp_secret` / `totp_enabled`）
|
||||
- `auth_sessions`：session token 哈希与过期时间
|
||||
- `auth_login_throttle`：登录失败退避状态（按 IP / username 双键）
|
||||
- `auth_recovery_code`：TOTP 恢复码哈希（一次性）
|
||||
- `app_config`：runtime 配置持久化
|
||||
|
||||
## 首次启动与 bootstrap
|
||||
|
||||
如果 auth DB 中还没有任何用户，应用启动时会要求：
|
||||
如果 auth DB 中还没有任何用户，应用启动时会使用：
|
||||
|
||||
- `AUTH_BOOTSTRAP_USERNAME`
|
||||
- `AUTH_BOOTSTRAP_PASSWORD`
|
||||
|
||||
并创建首个 admin 用户。
|
||||
|
||||
当前默认 bootstrap 值就是：
|
||||
创建首个 admin 用户。当前默认 bootstrap 值为：
|
||||
|
||||
- username: `admin`
|
||||
- password: `admin`
|
||||
|
||||
首次登录后，系统会强制要求修改密码。
|
||||
|
||||
如果你希望在首次启动前就覆盖默认值，可以直接设置环境变量：
|
||||
## 基础安全设计
|
||||
|
||||
- `AUTH_BOOTSTRAP_USERNAME`
|
||||
- `AUTH_BOOTSTRAP_PASSWORD`
|
||||
|
||||
建议流程是：
|
||||
|
||||
1. 配好 `.env`
|
||||
2. 运行 `python scripts/app_db_adopt.py`
|
||||
3. 启动应用
|
||||
4. 用 `admin / admin` 首次登录
|
||||
5. 立即修改密码
|
||||
|
||||
## 安全设计
|
||||
|
||||
当前这版已经落实的基础安全点：
|
||||
当前这版已经落实的安全点：
|
||||
|
||||
- 密码不明文存储，使用 Argon2 哈希
|
||||
- session cookie 为 `HttpOnly`
|
||||
- cookie 使用 `SameSite=Lax`
|
||||
- `Secure` cookie 在非 `development` 环境默认开启
|
||||
- 登录表单与登出表单都有基础 CSRF 校验
|
||||
- 写请求（POST/PUT/PATCH/DELETE）需携带 `X-CSRF-Token` header（SameSite=Lax + 自定义 header 纵深防御，无需 per-session token 值比对）
|
||||
- session token 为随机生成，服务端只持久化 token hash
|
||||
- session 有过期时间与显式失效机制
|
||||
- session 有过期时间（默认 12 小时）与显式失效机制
|
||||
|
||||
## 当前受保护范围
|
||||
---
|
||||
|
||||
当前这轮只保护了页面入口：
|
||||
## M4 登录加固
|
||||
|
||||
- `GET /config`
|
||||
- `POST /config`
|
||||
- `POST /config/change-password`
|
||||
- `POST /logout`
|
||||
M4 在基础鉴权之上叠加了三层防御：防爆破/指数退避、CLI 逃生通道、可选 TOTP 二次验证。
|
||||
|
||||
相关流程：
|
||||
### 1. 防爆破 / 指数退避
|
||||
|
||||
- `GET /login`
|
||||
- `POST /login`
|
||||
#### 机制
|
||||
|
||||
未登录访问 `/config` 时会被重定向到 `/login`。
|
||||
登录失败按指数增长延迟，目标是拖垮暴力枚举，同时不因此永久锁定账号。
|
||||
|
||||
## 下一步不在本轮内
|
||||
**退避是延迟（429 + Retry-After），不是永久封号**——单 admin 场景下永久锁会被攻击者反向用来故意打锁，所以退避只增加等待时间，CLI 是最终逃生口。
|
||||
|
||||
后续可以在这个基座上继续做：
|
||||
#### 双键计算
|
||||
|
||||
- 配置页面接入
|
||||
- config persistence
|
||||
- 更细的受保护路由范围
|
||||
- 用户初始化 / 密码轮换的更正式 runbook
|
||||
每次登录请求同时按 **client IP** 和 **username** 各记一套失败计数，本次需等待时间 = 两者退避的**较大值**。
|
||||
|
||||
- 按 IP：堵单点暴力（攻击 IP 越敲越慢，合法用户换 IP 不受影响）
|
||||
- 按 username：全局兜底（即便攻击者分布式换 IP 也有一层保护）
|
||||
|
||||
#### 指数公式
|
||||
|
||||
```
|
||||
N_FREE = 3 — 前 3 次失败不延迟（免费次数）
|
||||
BASE = 1 秒
|
||||
CAP = 900 秒（15 分钟）
|
||||
|
||||
wait = min(CAP, BASE × 2^(failures - N_FREE)) （failures > N_FREE 时生效）
|
||||
```
|
||||
|
||||
延迟示意：
|
||||
|
||||
| 累计失败次数 | 等待时间 |
|
||||
| --- | --- |
|
||||
| 1–3 | 0 秒（免费） |
|
||||
| 4 | 2 秒 |
|
||||
| 5 | 4 秒 |
|
||||
| 6 | 8 秒 |
|
||||
| 7 | 16 秒 |
|
||||
| … | … |
|
||||
| 13+ | 900 秒（封顶） |
|
||||
|
||||
成功登录后，该 IP 和 username 的退避状态**立即清零**。
|
||||
|
||||
#### 登录端点行为（`POST /api/auth/login`）
|
||||
|
||||
1. 先查退避（在窗口内直接 `429`，**不验密码**，节省 Argon2 计算并防止枚举）
|
||||
2. 验密码失败 → 记一次失败（IP + username 各记），返回 `401`
|
||||
3. 密码正确但 TOTP 启用且缺少 `totp_code` → 返回 `401 {totp_required: true}`，**不记失败**（这是正常两步流程的第一步，不是攻击信号）
|
||||
4. 密码正确但 TOTP 验证失败 → 记一次失败，返回 `401`
|
||||
5. 全部通过 → 清零退避状态，发 session cookie
|
||||
|
||||
#### 配置项
|
||||
|
||||
| 配置项 | 类型 | 默认 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `AUTH_LOGIN_THROTTLE_ENABLED` | bool（CONFIG_FIELDS） | `true` | 全局开关，关闭后整个退避机制 no-op |
|
||||
| `AUTH_TRUST_FORWARDED_FOR` | bool（`.env` 部署级） | `false` | `true` 时取 `X-Forwarded-For` 最左作为 client IP；**反代后必须显式开启**，否则反代 IP 全视为同一 IP，按 IP 退避失效 |
|
||||
|
||||
> **反代部署注意**：`AUTH_TRUST_FORWARDED_FOR` 默认 `false`（直接用 socket IP）。部署在 nginx 等反代后面时，应设 `AUTH_TRUST_FORWARDED_FOR=true`，并确保反代正确设置 `X-Forwarded-For`。
|
||||
|
||||
---
|
||||
|
||||
### 2. CLI 逃生通道
|
||||
|
||||
#### 设计原则
|
||||
|
||||
CLI 通过 **直连本地 DB**（`get_session_local()`）工作，**无需 HTTP 服务器运行、无需任何已存凭据**（密码、恢复码均不需要）。拿到服务器 CLI 权限本身就意味着对系统有完全控制，因此这是可接受且必须存在的最终逃生口。
|
||||
|
||||
CLI 只动 auth 相关行（`auth_users` 的密码/TOTP 字段、`auth_login_throttle`、`auth_recovery_code`），**绝不**触碰用户数据表（`location`、`poo_records`、`public_ip_state` 等）。
|
||||
|
||||
入口：`python -m scripts.admin_cli <command>`
|
||||
|
||||
#### 子命令
|
||||
|
||||
| 命令 | 用途 | 逃生场景 |
|
||||
| --- | --- | --- |
|
||||
| `reset-password <username> [--password <pwd>]` | 重置密码（不带 `--password` 则交互式输入，不回显） | 忘记密码 |
|
||||
| `unlock [--all \| --ip <ip> \| --username <u>]` | 清 `auth_login_throttle` 行 | 被退避锁住（429）时解锁 |
|
||||
| `disable-totp <username>` | 关停 TOTP（清 secret + 删全部恢复码），**零凭据可执行** | 恢复码全丢也能进 |
|
||||
| `reissue-totp <username>` | 生成新 TOTP secret 并打印 `otpauth://` URI | 设备丢失、需重新注册 Authenticator |
|
||||
| `list-admin` | 列出所有用户与状态列 | 排障用 |
|
||||
|
||||
#### 使用示例
|
||||
|
||||
```bash
|
||||
# 重置密码（不带 --password 时交互式 prompt，不回显）
|
||||
python -m scripts.admin_cli reset-password admin
|
||||
|
||||
# 重置密码（非交互，脚本里用）
|
||||
python -m scripts.admin_cli reset-password admin --password "newpassword"
|
||||
|
||||
# 解锁所有退避
|
||||
python -m scripts.admin_cli unlock --all
|
||||
|
||||
# 解锁特定 IP
|
||||
python -m scripts.admin_cli unlock --ip 1.2.3.4
|
||||
|
||||
# 解锁特定 username
|
||||
python -m scripts.admin_cli unlock --username admin
|
||||
|
||||
# 关停 TOTP（零凭据，最终逃生口）
|
||||
python -m scripts.admin_cli disable-totp admin
|
||||
|
||||
# 重新发放 TOTP secret（打印新 otpauth:// URI，扫码重新注册）
|
||||
python -m scripts.admin_cli reissue-totp admin
|
||||
|
||||
# 查看用户列表
|
||||
python -m scripts.admin_cli list-admin
|
||||
```
|
||||
|
||||
在 Docker 容器内执行：
|
||||
|
||||
```bash
|
||||
docker compose exec app python -m scripts.admin_cli <command>
|
||||
```
|
||||
|
||||
#### `reissue-totp` 语义说明
|
||||
|
||||
- 对**已启用** TOTP 的用户：新 secret **立即在登录时生效**，旧 Authenticator 生成的码立即失效；**无需**再走 web `enable` 步骤。
|
||||
- 现有恢复码**不被删除**——恢复码是独立的随机哈希值，与 TOTP secret 无密码学绑定，reissue 后恢复码依然有效（仍可用于登录）。
|
||||
- 如果需要完整清理（secret + 所有恢复码），使用 `disable-totp`。
|
||||
|
||||
---
|
||||
|
||||
### 3. 可选 TOTP 二次验证
|
||||
|
||||
#### 设计
|
||||
|
||||
- TOTP 遵循 RFC 6238，使用 `pyotp` 库。
|
||||
- 二维码在**前端**由 `qrcode.react` 渲染（后端只返回 `otpauth://` URI，不引图像依赖）。
|
||||
- `totp_secret` 明文存库（与项目其他 secret 处理一致，靠数据库文件权限保护）。
|
||||
- 恢复码以 Argon2 哈希存库，一次性（使用后标记 `used_at`）。
|
||||
|
||||
#### 启用流程
|
||||
|
||||
1. **setup**（`POST /api/auth/totp/setup`）：生成 pending secret，返回 secret、`otpauth://` URI、10 个明文恢复码（**仅此一次**）；此时 `totp_enabled` 仍为 `false`。
|
||||
2. **扫码**：用 Authenticator App 扫前端渲染的二维码（或手动输入 secret）。
|
||||
3. **enable**（`POST /api/auth/totp/enable`）：输入当前 6 位码确认 → `totp_enabled` 变为 `true`。
|
||||
4. 妥善保存恢复码（不会再次展示）。
|
||||
|
||||
#### 停用流程
|
||||
|
||||
**web 停用**（`POST /api/auth/totp/disable`）：需提供当前密码或当前 6 位 TOTP 码。成功后清 secret、删全部恢复码，恢复纯密码登录。
|
||||
|
||||
**CLI 停用**（逃生口，恢复码全丢时）：`python -m scripts.admin_cli disable-totp admin`，零凭据，立即生效。
|
||||
|
||||
#### 登录二步流程
|
||||
|
||||
1. 提交 `POST /api/auth/login {username, password}` → 密码正确但 TOTP 已启用 → `401 {totp_required: true}`（不发 session）
|
||||
2. 前端切到第二屏，提交 `POST /api/auth/login {username, password, totp_code}` → 通过 → 发 session cookie
|
||||
|
||||
`totp_code` 可以是 6 位 TOTP 动态码，也可以是 `xxxx-xxxx` 格式恢复码（命中即消费，不可复用）。
|
||||
|
||||
#### API 端点
|
||||
|
||||
| 端点 | 用途 |
|
||||
| --- | --- |
|
||||
| `POST /api/auth/totp/setup` | 生成 pending secret + URI + 恢复码（一次性明文返回） |
|
||||
| `POST /api/auth/totp/enable` | 带当前 6 位码确认启用 |
|
||||
| `POST /api/auth/totp/disable` | 带密码或当前码停用 |
|
||||
| `GET /api/auth/totp` | 返回当前 TOTP 状态（`{enabled: bool}`），不返回 secret/恢复码 |
|
||||
|
||||
全部端点需要 session cookie（`GET /api/auth/totp` 不需 CSRF；其余写端点需 `X-CSRF-Token`）。
|
||||
|
||||
#### 配置项
|
||||
|
||||
| 配置项 | 类型 | 默认 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `AUTH_TOTP_ISSUER` | str（`.env` 部署级） | 空（回退 `app_name`） | 显示在 Authenticator App 里的 issuer 标签 |
|
||||
|
||||
---
|
||||
|
||||
## 受保护范围
|
||||
|
||||
当前 JSON API 端点（`/api/*`）需要 session cookie；写端点需额外携带 `X-CSRF-Token` header。
|
||||
|
||||
裸 ingestion 端点（`/location/record`、`/poo/record` 等设备调用端点）暂未收口到 session 保护（M3 计划引入 token 鉴权）。
|
||||
|
||||
## 下一步（不在当前范围）
|
||||
|
||||
- M3：token 鉴权（供脚本 / 设备 / 移动端调用 API），ingestion 端点收口。
|
||||
|
||||
Reference in New Issue
Block a user