sync from GitHub 75f7da8: security: comprehensive audit report (round 2) - 14 new findings

security_best_practices_report.md

@@ -1,270 +1,530 @@
-# XTC Backend (Hugging Face) 安全审计与加固报告
+# XTC Backend (Hugging Face) 安全审计报告（第二轮）
 
 - 审计时间：2026-07-21
-- 审计对象：`xtc-backend-hf`（FastAPI + SQLite + HF Hub 备份）
-- 审计范围：鉴权 / 限流 / CORS / SSRF / 信息泄露 / 输入校验 / 日志脱敏
-- 提交基线：`cfe155f feat: add package.json for wrangler and update worker.mjs to handle client IP`
+- 审计对象：`xtc-backend-hf`（FastAPI 0.115.6 + SQLite + HF Hub 备份 + JWT HS256 + bcrypt）
+- 审计范围：跨域 / 鉴权 / 跨用户文件 / Token 泄露 / 管理面板 / 数据库 / 日志 / DoS / 信息泄露
+- 审计方法：基于 OWASP API Top 10 (2023) + FastAPI 安全规范（FASTAPI-* 规则集）逐文件人工审查
+- 参考规范：`/data/user/skills/security-best-practices/references/python-fastapi-web-server-security.md`
+- 第一轮报告基线：`security_best_practices_report.md`（C1-C4 / H1-H5 / L1-L2 已修复，本轮不再重复）
 
 ---
 
-## 一、问题分级汇总
+## 0) 执行摘要（Executive Summary）
 
-| 级别 | 数量 | 说明 |
-|------|------|------|
-| Critical | 4 | 直接导致凭据泄露 / 内网探测 / 任意跨域读取 |
-| High | 5 | 暴力破解 / 数据刷屏 / 配置默认值 |
-| Low | 2 | 信息暴露面 / 配置文档缺失 |
+本轮重点对第一轮未覆盖的端点、中间件、Token 流转链路做深度审查，新发现 **3 个 Critical、4 个 High、4 个 Medium、3 个 Low** 共 14 项问题。最严重的 3 项分别是：
+
+- **NC1**：用户 JWT 与 admin 页面门禁 token 均可通过 URL query 参数传递，会在浏览器历史、Referer、server access log、CDN 日志、Webhook 等多处长期泄露，令牌一旦泄露即可在 7 天 TTL 内被任意利用。
+- **NC2**：当部署时未配置 `XTC_ACCESS_KEY` 时，`verify_access_key` 直接放行，**整套 `/v1/*` 业务接口处于完全无鉴权状态**，所有用户的对话、Token 用量、上游 API Key 池都可被任意未授权访问。
+- **NC3**：管理员可通过 `/admin/api/files/{key}/download` 下载任意用户的文件/备份内容、通过 `/admin/api/request-log` 查看任意用户的对话明文，**且无任何审计日志记录**，admin key 一旦泄露即等于全量数据失陷且无可追溯。
+
+所有发现均按 OWASP API Top 10 (2023) 类别归类，详见 §一至 §四。
 
 ---
 
-## 二、Critical 级别问题与修复
+## 一、Critical 级别问题
 
-### C1. 通配 CORS（`Access-Control-Allow-Origin: *`）允许任意第三方页面跨域读响应
+### NC1. Token 通过 URL Query 参数传递 → 多通道泄露（FASTAPI-AUTH-002）
 
 **位置**
-- `app/main.py` `create_app()` 中 `CORSMiddleware` 配置：`allow_origins=["*"]`
-- `app/main.py` `validation_error_handler`、`cors_preflight`：硬编码 `*`
-- `app/errors.py` `_CORS_HEADERS`、`make_error_response`、`make_upstream_error_response`：硬编码 `*`
-- `app/api/_common.py` `CORS_HEADERS`：硬编码 `*`
-- `app/middleware.py` `RateLimitMiddleware` 429 响应：硬编码 `*`
+- `app/api/user_files.py:130-140` `_extract_token()`：
+  ```python
+  def _extract_token(request: Request) -> str:
+      # 优先 query 参数（小天才手表等平台会拦截自定义 header，只能走 query）
+      q = request.query_params.get("token") or ""
+      q = q.strip()
+      if q:
+          return q
+      ...
+  ```
+- `app/admin_html.py:19-35` `admin_page()`：以 `?k=<token>` 作为 `/admin` 页面门禁
+  ```python
+  @router.get("/admin", response_class=HTMLResponse)
+  async def admin_page(request: Request, k: str | None = Query(default=None)) -> Response:
+      settings = get_settings()
+      if settings.has_admin_access_token:
+          provided = (k or "").strip()
+          expected = settings.xtc_admin_access_token
+          if not provided or not secrets.compare_digest(provided, expected):
+              return JSONResponse(status_code=404, ...)
+  ```
+- 用户 JWT 默认 TTL = 7 天（`app/api/user_files.py:51` `TOKEN_TTL_SEC = 7 * 24 * 3600`）
 
 **风险**
-任意第三方页面（包括恶意站点）发起的跨域请求都能读到本服务响应内容，包括错误响应中可能携带的内部信息、上游错误细节、限流信息等。当 `Access-Control-Allow-Credentials` 同时为 `true` 时还会进一步泄露带凭据请求的响应。
-
-**修复**
-- 新增 `app/cors.py` 作为 CORS 策略中心：
-  - `get_allowed_origins()`：从 `XTC_CORS_ORIGINS` 读取白名单
-  - `is_wildcard()`：是否为通配模式（未配置白名单）
-  - `cors_allow_origin(origin)`：通配模式回 `*`；白名单模式精确匹配
-  - `build_cors_headers(origin)`：构造完整 CORS 响应头（白名单模式下未匹配 origin 返回空字典）
-  - `build_preflight_headers(origin)`：OPTIONS 预检响应头（带 `Max-Age`）
-- 新增 `app/config.py` `xtc_cors_origins` 字段 + `_parse_cors_origins` validator（支持逗号/分号/换行分隔字符串或列表）
-- `app/main.py` `CORSMiddleware` 根据白名单���态配置：白名单模式 `allow_credentials=True` + 精确 origin；通配模式保持 `*` 向后兼容
-- `app/main.py` `validation_error_handler`、`cors_preflight` 改用 `build_cors_headers(origin)` / `build_preflight_headers(origin)`
-- `app/errors.py` `make_error_response`、`make_upstream_error_response` 接受 `origin` 参数并调用 `build_cors_headers`
-- `app/api/_common.py` `CORS_HEADERS` 改为 `build_cors_headers(None)` 计算结果；`ok_json`/`ok_with_cors` 新增 `origin` 可选参数
-- `app/middleware.py` 429 响应改用 `build_cors_headers(request.headers.get("origin"))`
-
-**配置示例**
-```
-XTC_CORS_ORIGINS=https://your-app.example.com,https://admin.example.com
+长生命周期的 access token（用户 JWT 7 天、`XTC_ADMIN_ACCESS_TOKEN` 长期有效）通过 URL query 传递时，会在以下通道泄露：
+1. **浏览器历史记录**：用户/管理员分享设备时被读取
+2. **Referer 头**：页面加载外部资源（图片、字体、CDN）时被带到第三方
+3. **服务器 access log**：`uvicorn.access` 默认记录完整 URL（含 query string）
+4. **反向代理 / CDN 日志**：Cloudflare、nginx 默认记录 query
+5. **Webhook 回调**：上游报错时把请求 URL 拼进 error message 回传
+6. **HF Space 内部链路**：HF 平台访问日志、`x-direct-url` 链路日志
+
+由于 admin token 长期有效、用户 JWT TTL 7 天，泄露窗口极长。攻击者拿到 token 后可冒充该用户上传/下载/删除文件、阅读会话；拿到 admin access token 后可直接进入 `/admin` 登录页（虽然还需 admin key 才能调 API，但已大幅压缩攻击面）。
+
+**修复建议**
+- **用户 JWT**：
+  - 优先保留 `Authorization: Bearer <token>` 头与 `x-xtc-user-token` 头两种方式
+  - `?token=` query 参数仅在确认客户端平台（小天才手表）无法发 header 时才允许，且：
+    - 缩短通过 query 路径签发的 token TTL（例如 5 分钟）
+    - 在响应头加 `Cache-Control: no-store` 防中间缓存
+    - access log 中过滤 `?token=` 参数（参考 `_SENSITIVE_BODY_KEYS` 机制）
+- **Admin 页面门禁 token**：完全废弃 `?k=<token>` query 形式，改为：
+  - 用一个 **短期一次性 nonce**：`GET /admin?n=<nonce>` → 服务端验证 nonce 后下发 `HttpOnly; Secure; SameSite=Strict` Cookie，后续 `/admin` 凭 Cookie 访问
+  - 或者把门禁 token 放到 `Authorization` 头（前端用 fetch 拦截器统一加）
+- **TTL 收紧**：用户 JWT 7 天 TTL 过长，建议改为 1 小时 + refresh token（已有 `/u/api/refresh` 端点，前端需主动调用）
+- **吊销列表**：用户 JWT 当前无服务端吊销机制（access_tokens 表只覆盖 admin 签发的临时令牌），泄露后只能等过期
+
+---
+
+### NC2. 未配置 `XTC_ACCESS_KEY` 时整套 `/v1/*` 业务接口完全无鉴权（FASTAPI-AUTH-001）
+
+**位置**：`app/auth.py:46-68` `verify_access_key()`
+```python
+def verify_access_key(provided: Optional[str]) -> None:
+    settings = get_settings()
+    if not settings.has_access_key:
+        # 未配置 access_key 时放行（开发模式）
+        return
+    if not provided:
+        raise HttpError(...)
+    ...
 ```
 
+**风险**
+HF Space 默认环境变量中不包含 `XTC_ACCESS_KEY`，若部署时遗漏配置：
+- `/v1/chat/completions`、`/v1/xtc/*`、`/v1/models` 等业务接口完全无鉴权
+- 任意匿名用户可消耗上游 Gemini / OpenAI API Key 额度（直接经济损失）
+- 上游 API Key 池（admin 配置的 provider api_keys）可被未授权用户滥用
+- 用户文件接口 `/u/api/*` 虽有独立 JWT 鉴权不受影响，但 `/v1/*` 业务路径全部失守
+- `_warn_insecure_secrets()`（H4 修复）只在启动日志告警，不阻断请求，部署者容易忽略
+
+**修复建议**
+- 生产环境必须强制配置 `XTC_ACCESS_KEY`：在 `lifespan` 启动时若检测到 `ENV=production` 且 `has_access_key=False`，直接 `raise RuntimeError` 拒绝启动
+- 引入显式的 `XTC_DEV_MODE=1` 开关，仅在显式开启时才允许 `has_access_key=False` 放行
+- 启动告警升级为邮件/飞书/Webhook 通知（而不只是 `logging.warning`）
+
 ---
 
-### C2. SSRF：`/v1/xtc/image/fix/test` 任意 URL 拉取未做协议/内网校验
+### NC3. Admin 跨用户数据访问无审计 → Admin Key 泄露即全量失陷且无追溯（FASTAPI-AUTHZ-001 / OWASP API1:2023）
 
-**位置**：`app/api/image_fix.py` `fix_test()` 中 `httpx.AsyncClient().get(image_url)`
+**位置**
+- `app/api/admin_data.py:378-417` `download_any_file()`：管理员下载任意用户文件/备份内容，无 audit log
+  ```python
+  @router.get("/files/{key}/download")
+  async def download_any_file(key: str, _admin: str = Depends(_require_admin)):
+      ...
+      return Response(content=content, ...)
+      # ⚠️ 整个函数无 audit_log_store.append(...) 调用
+  ```
+- `app/api/admin_data.py:470-488` `delete_any_file()`：管理员删除任意用户文件，仅 `logger.info` 不入审计表
+  ```python
+  logger.info("[admin delete] key=%s kind=%s owner=%s", key, kind, owner)
+  ```
+- `app/api/admin_data.py:547-600` `delete_user()`：级联删除用户全部数据，仅 `logger.info`
+- `app/services/request_log_store.py:243-302` `list_records()`：admin 可查询任意用户的对话内容明文（`request_body` / `response_body`），无审计
+- `app/request_log_middleware.py:31` `_RECORDED_PREFIXES = ("/v1/", "/admin/api/", "/u/api/")`：**用户文件 API `/u/api/*` 的请求体也被记录到 SQLite**（含登录密码字段虽被脱敏，但 `/u/api/upload` 的 multipart 被标 `[multipart form-data]`，`/u/api/files` 等不含敏感数据；不过 `/u/api/login` 的 body 中的 `password` 字段在 `_SENSITIVE_BODY_KEYS` 中已脱敏，**但 `/v1/*` 业务请求中用户对话原文被完整保存**）
 
 **风险**
-攻击者可传入：
-- `http://169.254.169.254/latest/meta-data/` 探测云元数据（AWS/Azure/GCP 实例凭据）
-- `http://localhost:port/` 访问本机内网服务（Redis/admin 接口/数据库等）
-- `http://10.0.0.1/`、`http://192.168.x.x/` 扫描内网
-- `file:///etc/passwd`、`gopher://...` 等危险协议
-- 重定向到上述目标绕过校验
-
-**修复**：新增 `_fetch_remote_image_safely(url)`
-- 协议白名单：只允许 `http`/`https`
-- 私网 IP 拦截：`_is_private_ip(host)` 检查 IP 字面量与域名解析结果，拒绝私网/回环/链路本地/保留/组播/未指定地址
-- 重定向重新校验：`follow_redirects=False`，手动跟随，每次重定向目标都重新走 SSRF 校验
-- 重定向循环检测：`seen_urls` 集合
-- 重定向上限：3 次
-- 大小限制：`Content-Length` 与实际 `len(raw)` 双校验，上限 20MB（防内存爆破）
-- 输入长度限制：`body.image` 长度上限 8192
-- 错误信息收敛：`fix_image_bytes` 异常不透出 `str(exc)`，只回固定文案 + 服务端 `logger.exception`
+- Admin key 一旦泄露（如通过 NC1 的 query 参数泄露、或浏览器 localStorage 被读取、或弱密码被爆破），攻击者可：
+  1. 下载任意用户上传的私人文件（`/admin/api/files/{key}/download`）
+  2. 查看任意用户的完整对话历史（`/admin/api/request-log` + `/admin/api/sessions/{id}/messages`）
+  3. 删除任意用户的所有数据且无可追溯（无 audit log）
+- 由于 `audit_log` 表已存在但仅 `config_store` 等少数路径调用，admin 数据 API 完全未接入审计
+- HF Space 单实例 + 无 SIEM，文件级 `logger.info` 在 Space 重建后丢失，等同于"无审计"
+
+**修复建议**
+- 所有 `/admin/api/files/{key}/download`、`/admin/api/files/{key}` (DELETE)、`/admin/api/users/{user_id}` (DELETE)、`/admin/api/sessions/{id}` (DELETE) 路径必须调用 `audit_log_store.append(action="admin.download_file", actor=admin_key_hash, target=key, detail={owner, namespace, size})`
+- 对 `/admin/api/request-log` 查询接口加审计：记录哪个 admin 查看了哪条 request_log
+- 对 admin 操作的 audit_log 单独加表或加 `actor_type='admin'` 字段，防止 admin 自己清空 audit_log 表
+- 在 `request_log_middleware` 中对 `/u/api/*` 路径默认不记录请求体（用户文件接口无需日志回放），或仅记录元信息（method/path/status）不记 body
 
 ---
 
-### C3. `/logs/api/log` 与 `/logs/api/log/batch` 无鉴权，任意人可写入垃圾日志
+## 二、High 级别问题
 
-**位置**：`app/api/logs.py` `post_log`、`post_log_batch`
+### NH1. 用户对话原文以明文持久化到 SQLite，admin 可读且无脱敏（OWASP API2:2023）
+
+**位置**
+- `app/request_log_middleware.py:122-133`：业务请求体被解析后存入 `request_body` 字段
+  ```python
+  if "application/json" in ct:
+      try:
+          req_body_redacted = request_log_store._redact_body(json.loads(request_body_raw))
+      ...
+  ```
+- `app/services/request_log_store.py:59-71` `_redact_body()`：仅对 `_SENSITIVE_BODY_KEYS = {"api_key", "token", "password", ...}` 中的字段脱敏，**用户对话内容（messages 数组中的 user/assistant content）不在脱敏列表**
+- `app/services/request_log_store.py:162-223` `insert()`：完整 body 写入 SQLite `request_log` 表
+- `app/api/request_logs.py`（admin 接口）：admin 可查询任意 request_log 详情，含完整 `request_body` / `response_body`
+- `request_log` 表无用户隔离：所有用户的对话都混在同一张表，admin 查询无过滤
 
 **风险**
-- 任意未鉴权客户端可向 `app_logs` 表写入无限日志，撑爆 SQLite 数据库
-- 字段无长度限制，单条日志可写入数 MB 数据
-- 批量接口无条数上限，一次请求可写入任意条数
-- 攻击者可借此进行 DoS（数据库写入是同步的，会阻塞事件循环）
+- 任意用户的对话内容（可能含 PII：姓名、电话、地址、医疗/金融信息）以明文形式持久化在 `/data/xtc.db`
+- DB 文件本身在 HF Space 容器内，若容器被入侵或 NC2 的无鉴权状态被滥用，攻击者可一次性获取全部历史对话
+- admin（含合法 admin 与被盗 admin key 的攻击者）可无差别浏览所有用户对话
+- `request_log_limit` 默认 500 条但可调至 5000，且不区分用户，足以重建任意用户画像
 
-**修复**
-- 两个端点加 `Depends(require_access_key)` 鉴权
-- 字段长度限制：`level ≤ 32`、`module ≤ 128`、`event ≤ 128`、`trace_id ≤ 128`、`data ≤ 64KB`
-- 批量条数上限：`_MAX_BATCH_SIZE = 200`（超出截断）
-- `rate_limit_store.is_rate_limited_path()` 把 `/logs/api/log`、`/logs/api/log/batch` 纳入限流
+**修复建议**
+- 对 `/v1/chat/completions`、`/v1/xtc/*` 等含对话内容的路径，`request_body` 字段在入库前对 `messages` 数组做哈希或截断（仅保留前 100 字符 + 长度）
+- 把 `messages`、`content`、`prompt`、`text` 等对话相关字段加入 `_SENSITIVE_BODY_KEYS`，或单独引入 `_REDACTED_CONTENT_KEYS` 做部分脱敏（保留长度信息便于排障）
+- admin 查看 request_log 详情时强制审计（参见 NC3）
+- 提供用户级"清除我的对话历史"接口（GDPR/PIPL 合规）
 
 ---
 
-### C4. `unhandled_exception_handler` 把 `str(exc)` 返回给客户端
-
-**位置**：`app/errors.py` `unhandled_exception_handler`
+### NH2. Admin Login 响应区分 401/403/500 → 状态枚举（OWASP API8:2023）
+
+**位置**：`app/auth.py:169-191` `verify_admin_key()`
+```python
+def verify_admin_key(provided: Optional[str]) -> None:
+    settings = get_settings()
+    if not settings.is_admin_enabled:
+        raise HttpError("Admin API disabled (XTC_DISABLE_ADMIN=true)", status=403, code="forbidden")
+    if not settings.has_admin_key:
+        raise HttpError("XTC_ADMIN_KEY not configured", status=500, code="server_misconfigured")
+    if not provided:
+        raise HttpError("Missing admin key: ...", status=401, code="unauthorized")
+    if not _consteq(provided, settings.xtc_admin_key):
+        logger.warning("[auth] invalid admin key")
+        raise HttpError("Invalid admin key", status=401, code="unauthorized")
+```
 
 **风险**
-未捕获异常的 `str(exc)` 可能包含：
-- 内部文件路径（`/workspace/xtc-backend-hf/app/...`）
-- SQL 片段（`sqlite3.OperationalError: no such table: xxx`）
-- 密钥片段（`KeyError: 'hf_token'`）
-- 第三方库版本与端点信息（`httpx.ConnectError: ...`）
+匿名攻击者通过单次 POST `/admin/api/login` 即可区分三种部署状态：
+- `403 forbidden` → admin 已禁用，无需进一步攻击
+- `500 server_misconfigured` → admin 启用但 `XTC_ADMIN_KEY` 为空，可能配合 NC2 形成"admin 接口可调但无 key 校验"的链式利用（实际 `_require_admin` 仍会校验，但泄露了配置错误状态）
+- `401 unauthorized` → admin 启用且配置了 key，可进入暴力破解流程
 
-攻击者通过构造畸形请求触发异常，可获取内部实现细节用于后续攻击。
+这种状态枚举帮助攻击者筛选目标实例（如批量扫描 HF Space 上的部署），降低攻击成本。
 
-**修复**
-- 客户端只返回固定文案 `"Unexpected error"`，不暴露 `str(exc)`
-- 完整 `traceback` 只打到服务端日志（`logging.getLogger().error` + `traceback.print_exc`）
-- 异常处理函数接受 `request`，提取 `request.headers.get("origin")` 走动态 CORS
+**修复建议**
+- 对未鉴权请求统一返回 `401 unauthorized` + 相同错误文案（"authentication required"）
+- 真实状态（disabled / misconfigured）只打到服务端日志
+- 参考第一轮 H1 的"不区分用户不存在和密码错误"做法
 
 ---
 
-## 三、High 级别问题与修复
+### NH3. `_extract_access_key` 接受 Basic auth scheme → 凭据混淆（FASTAPI-AUTH-002）
+
+**位置**：`app/auth.py:29-43` `_extract_access_key()`、`app/middleware.py:19-28`、`app/request_log_middleware.py:48-61`
+```python
+def _extract_access_key(*, authorization, x_access_key) -> Optional[str]:
+    if x_access_key:
+        return x_access_key.strip()
+    if authorization:
+        auth = authorization.strip()
+        if auth.lower().startswith("bearer "):
+            return auth[7:].strip()
+        if auth.lower().startswith("basic "):
+            return auth[6:].strip()  # ⚠️ Basic auth 的 base64(user:pass) 被当作 access_key
+        return auth
+```
 
-### H1. 鉴权类端点无暴力破解防护
+**风险**
+- `Authorization: Basic <base64>` 的语义是"用户名:密码"组合，被这里当作 access_key 整体使用，语义错位
+- 攻击者可构造 `Authorization: Basic <实际 access_key 的 base64>` 来绕过部分 WAF / 日志规则（很多日志工具会自动脱敏 Basic 但不脱敏 Bearer）
+- 在反代场景下，若上游 Basic 被透传，access_key 可能被错误地暴露在 `Authorization: Basic` 形式下被中间件记录
+- access log 中 Basic auth 通常会被自动 base64 解码后脱敏用户名，导致 access_key 被以解码形式记录到日志
+
+**修复建议**
+- 移除 `if auth.lower().startswith("basic "):` 分支，仅接受 Bearer
+- 若需兼容老客户端的"裸 token"形式，可保留 `return auth` 但仅限无 scheme 的情况
+- 中间件与日志层级的 `_extract_access_key` 同步修改
+
+---
 
-**位置**：`/u/api/login`、`/u/api/register`、`/admin/api/login`
+### NH4. 备份分段上传 session 内存表无并发上限 → DoS（FASTAPI-LIMITS-001）
+
+**位置**：`app/api/user_backups.py:55-73`
+```python
+MAX_PART_SIZE = 2 * 1024 * 1024
+_UPLOAD_SESSION_TTL = 3600
+# 内存存储：upload_id -> {user_id, username, alias, parts: {seq: bytes}, created_at}
+_backup_upload_sessions: "dict[str, dict]" = {}
+
+def _cleanup_expired_upload_sessions() -> None:
+    """清理过期的分段上传 session，释放内存。每次创建新 session 时调用。"""
+```
 
 **风险**
-- 没有针对 IP / 用户名的失败计数与锁定
-- 没有比业务接口更严格的限流
-- 攻击者可对单一账号无限尝试密码，或对后台 admin key 进行暴力破解
-
-**修复**：`app/services/rate_limit_store.py` 新增鉴权限流模块
-- `_AUTH_WINDOW_SEC = 60`、`_DEFAULT_AUTH_PER_IP = 10`、`_DEFAULT_AUTH_PER_USERNAME = 5`
-- `_AUTH_FAIL_THRESHOLD = 5`、`_AUTH_FAIL_LOCK_SEC = 15 * 60`
-- 三层防护：
-  1. **失败锁定**：`is_ip_locked(ip)` 检查该 IP 近 15 分钟失败次数，≥5 次直接 429 拒绝
-  2. **per-IP 限流**：`check_auth_rate_limit()` 每 IP 60 秒最多 10 次鉴权请求
-  3. **per-username 限流**：每用户名 60 秒最多 5 次登录尝试（防针对单一账号爆破）
-- `record_auth_failure(ip, username)`：记录失败，达阈值时触发锁定
-- `clear_auth_failures(ip, username)`：登录成功后清零失败计数
-
-**接入点**
-- `app/middleware.py` `RateLimitMiddleware`：鉴权路径走 `check_auth_rate_limit`，POST 方法才计入，429 响应带 `Retry-After` / `X-RateLimit-Scope`
-- `app/api/user_files.py` `register`：用户名冲突 → `record_auth_failure`；成功 → `clear_auth_failures`
-- `app/api/user_files.py` `login`：用户不存在或密码错误 → `record_auth_failure`（不区分两种情况，防账号枚举）；成功 → `clear_auth_failures`
-- `app/api/admin.py` `login`：admin key 校验失败 → `record_auth_failure`；成功 → `clear_auth_failures`
+- `_backup_upload_sessions` 字典无大小上限，每个用户可创建无限个 session
+- 单 session 最大 50MB（`MAX_BACKUP_SIZE`），每 part 2MB；攻击者用合法 token 创建 N 个 session，每个塞 49MB 数据，可轻松耗尽 HF Space 容器内存（免费档通常 16GB）
+- `_cleanup_expired_upload_sessions()` 仅在新建 session 时调用，若攻击者停止创建新 session，旧 session 会一直占内存直到 TTL（1 小时）到期
+- 同样的问题存在于 `_backup_payload_cache: TTLCache(maxsize=32, ttl=60)`（per-user 32 条缓存），攻击者可通过批量下载触发缓存淘汰但每次仍占 60s 内存
+
+**修复建议**
+- 加 per-user 并发 session 上限：`MAX_SESSIONS_PER_USER = 3`，超出返回 429
+- 加全局 session 上限：`MAX_TOTAL_SESSIONS = 1000`，超出触发清理或拒绝
+- `_cleanup_expired_upload_sessions()` 改为后台定时任务（如每 60 秒）+ 每次创建前调用
+- 在 `RateLimitMiddleware` 中对 `/u/api/backups/upload/session` 加更严格的 per-user 限流（如 60 秒 5 次）
 
 ---
 
-### H2. `is_rate_limited_path` 未把鉴权路径与日志写入端点纳入限流
+## 三、Medium 级别问题
+
+### NM1. SQLite DB 文件无加密 + fallback 到 `/tmp/xtc.db` → 共享环境泄露（FASTAPI-FILES-001）
+
+**位置**：`app/database.py:34-48` `_resolve_db_path()`
+```python
+def _resolve_db_path() -> str:
+    settings = get_settings()
+    db_path = settings.db_path  # 默认 /data/xtc.db
+    try:
+        _ensure_parent_dir(db_path)
+        test_path = Path(db_path)
+        test_path.touch(exist_ok=True)
+        if not os.access(db_path, os.W_OK):
+            raise PermissionError(db_path)
+        return db_path
+    except Exception:
+        fallback = "/tmp/xtc.db"
+        logger.error("[database] db_path %s not writable, fallback to %s", db_path, fallback)
+        return fallback
+```
 
-**位置**：`app/services/rate_limit_store.py`
+**风险**
+- `/data/xtc.db` 文件包含：用户密码哈希（bcrypt，但仍敏感）、admin key（明文，见下文）、所有用户文件元信息、对话历史（NH1）、上游 API Key（在 `config_store` 备份中可能含明文）
+- DB 文件无加密，文件系统层面任意能读取该文件的进程/用户都可获取全部数据
+- fallback 到 `/tmp/xtc.db`：`/tmp` 在多数 Linux 默认 1777 权限，**同主机其他用户可读取**（HF Space 容器虽隔离，但多用户共享主机场景下危险）
+- DB 文件无独立访问控制（无 `chmod 600`）
 
-**修复**
-- 加入 `/u/api/login`、`/u/api/register`、`/admin/api/login` 到鉴权限流路径
-- 加入 `/logs/api/log`、`/logs/api/log/batch` 到限流路径
-- 新增 `is_auth_path(path)` 用于区分鉴权限流与业务限流
+**修复建议**
+- DB 文件创建后立即 `os.chmod(db_path, 0o600)` 限制仅 owner 可读写
+- 启动时若 fallback 到 `/tmp`，在 `lifespan` 中 `raise RuntimeError` 拒绝启动生产模式
+- 考虑使用 SQLCipher 对 DB 加密（pip install pysqlcipher3），密钥从 `XTC_DB_KEY` 环境变量读取
+- `XTC_ADMIN_KEY`、上游 API Key 等敏感配置不应持久化到 SQLite（当前 `config_store` 会备份到 Hub），应只保留在内存或加密存储
 
 ---
 
-### H3. 敏感标头脱敏不完整：`x-xtc-user-token` 未脱敏
+### NM2. 用户 JWT 7 天 TTL 过长 + 无服务端吊销机制（FASTAPI-AUTH-004）
+
+**位置**：`app/api/user_files.py:51` `TOKEN_TTL_SEC = 7 * 24 * 3600`
+```python
+TOKEN_TTL_SEC = 7 * 24 * 3600  # 7 天
+...
+def _issue_user_token(user_id: int, username: str) -> str:
+    payload = {
+        "type": "user_file",
+        "sub": str(user_id),
+        "username": username,
+        "iat": now,
+        "exp": now + TOKEN_TTL_SEC,
+    }
+    return jwt.encode(payload, settings.xtc_jwt_secret, algorithm=ALGORITHM)
+```
+
+**风险**
+- 7 天 TTL 远超一般业务需要，token 一旦泄露（参见 NC1 的 query 参数泄露）可在 7 天内被任意利用
+- 用户 JWT **无服务端吊销列表**：`access_tokens` 表只用于 admin 签发的临时令牌（`type="access"`），用户 JWT（`type="user_file"`）不在表中，泄露后无法主动失效
+- `/u/api/refresh` 端点（`user_files.py:362-370`）签发新 token 但不吊销旧 token，**旧 token 仍有效至过期**，相当于"双 token 并存"
+- 用户改密码 / 注销账号后，旧 token 仍可用（注销账号 `_delete_account` 未清理 token，因为根本没有 token 表）
 
-**位置**：`app/services/request_log_store.py` `_SENSITIVE_HEADERS`
+**修复建议**
+- TTL 缩短至 1 小时，配合 refresh token 机制（refresh token 单独存储 + 可吊销）
+- 引入 `user_tokens` 表持久化用户 JWT 的 `jti`，支持吊销
+- 改密码 / 注销账号时批量吊销该用户所有未过期 token
+- `/u/api/refresh` 应吊销旧 token 再签发新 token（token rotation）
+
+---
+
+### NM3. 扫描器拦截中间件 `_WHITELIST_PREFIXES` 死代码 → 误拦风险（FASTAPI-AUTH-001）
+
+**位置**：`app/scanner_block_middleware.py:78-89, 168-225`
+```python
+_WHITELIST_PREFIXES = (
+    "/", "/health", "/v1/", "/admin", "/u/", "/uapi/", "/favicon.ico", "/robots.txt",
+)
+
+def _is_whitelisted_path(path: str) -> bool:  # ⚠️ 函数定义但 dispatch 中从未调用
+    ...
+
+async def dispatch(self, request, call_next):
+    if request.method == "OPTIONS":
+        return await call_next(request)
+    client_ip = _get_client_ip(request)
+    path = request.url.path
+    if _is_internal_ip(client_ip):
+        return await call_next(request)
+    if _is_blacklisted(client_ip):
+        ...
+    if _is_scanner_path(path):  # ⚠️ 直接判断扫描特征，未先检查白名单
+        _blacklist_ip(client_ip, reason=f"path={path}")
+        ...
+```
 
 **风险**
-用户登录后的 JWT 令牌通过 `x-xtc-user-token` 头携带，未脱敏会写入 `request_log` 表，管理员查看请求日志时可读到完整 token，存在凭据泄露面。
+- `_is_whitelisted_path()` 函数与 `_WHITELIST_PREFIXES` 常量定义但 `dispatch` 中从未调用
+- `_SCANNER_PATH_PATTERNS` 中包含 `/admin/config`（第 75 行），这是合法的 admin 配置接口路径前缀
+  ```python
+  _SCANNER_PATH_PATTERNS = [
+      ...
+      "/admin/config",  # ⚠️ 但 /admin/api/config 是合法 admin 接口
+  ]
+  ```
+  虽然当前 `/admin/api/config` 不含 `/admin/config` 子串（含，因为是子串匹配 `pat in lower`），实际上 `/admin/api/config` 包含 `/admin/config`？不，`/admin/api/config` 中找 `/admin/config` 子串不存在（`/admin/` 后是 `api/config`）。**但 `/admin/config` 若被合法客户端访问（如旧版前端），会被错误判定为扫描器并拉黑 IP 5 分钟**
+- 类似的还有 `/api/v1/models`（第 71 行）— 这是合法的 OpenAI 兼容客户端常用探测路径，但被当作扫描特征
+- `/metrics`、`/graphql` 等若业务方未来引入，也会被误拦
+- `_is_scanner_path` 用 `pat in lower` 子串匹配，过于宽泛：`.env` 会匹配任何含 `.env` 的路径（如 `/v1/xtc/environment` 假设性路径）
+
+**修复建议**
+- 在 `dispatch` 中先调用 `_is_whitelisted_path(path)`，命中白名单则跳过扫描检测
+- `_SCANNER_PATH_PATTERNS` 改为更精确的匹配（如 `$` 结尾锚定，或用正则）
+- 移除 `/admin/config`、`/api/v1/models` 等可能与合法路径冲突的条目
+- 加单元测试覆盖：合法路径不被拦，扫描路径被拦
+
+---
+
+### NM4. 用户注销账号 `_delete_account` 未审计 + Hub 备份可能残留（OWASP API8:2023）
 
-**修复**：`_SENSITIVE_HEADERS` 增加 `x-xtc-user-token`；`_SENSITIVE_BODY_KEYS` 增加 `user_token`、`admin_access_token`
+**位置**：`app/api/user_files.py`（基于 summary 引用，未在本次读取的片段中）
+
+**风险**
+- 用户注销账号是 GDPR/PIPL 法定的"删除权"，需保证彻底删除
+- 当前实现删除 SQLite 行 + Hub 内容，但：
+  - 无审计日志记录"谁在何时注销了哪个账号"
+  - Hub 上的 `user_accounts/<username>` 备份若异步推送失败可能残留
+  - `request_log` 表中该用户的对话历史不会被删除（NH1 的连带问题）
+  - `audit_log`、`usage_log`、`session_messages` 等表中该用户的数据不会被清理
+
+**修复建议**
+- 注销账号时写审计日志（actor=用户自己，action=user.account.deleted）
+- 注销时同步清理 `request_log`、`session_messages`、`usage_log`、`audit_log` 中该 user_id / access_key 的记录
+- Hub 删除后做二次验证（list 一次确认无残留）
+- 注销前要求二次密码确认（前端已实现，后端应再校验一次）
 
 ---
 
-### H4. 无启动期弱密钥/默认密钥告警
+## 四、Low 级别问题
+
+### NL1. `request_log_middleware` 与 `rate_limit_store` 客户端 IP 提取不一致
 
-**位置**：`app/main.py` `lifespan`
+**位置**
+- `app/request_log_middleware.py:136` `client_ip = request.client.host if request.client else None`（不读 X-Forwarded-For）
+- `app/services/rate_limit_store.py` `get_client_ip()`（读 X-Forwarded-For）
+- `app/scanner_block_middleware.py:98-106` `_get_client_ip()`（读 X-Forwarded-For）
 
 **风险**
-默认值 `change-me-admin-key` / `change-me-access-key` / `change-me-jwt-secret-strong-random` 容易被遗忘部署到生产环境，且没有提示。
+- 同一请求在不同中间件中记录的 client_ip 不一致
+- request_log 中存的 IP 是反代 IP（如 Cloudflare Worker IP），不是真实客户端 IP，影响基于 IP 的安全分析
+- 鉴权限流用真实 IP，但日志用反代 IP，攻击复盘时无法关联
 
-**修复**：`app/main.py` 新增 `_warn_insecure_secrets()`，启动时检查并 `logging.warning`：
-- 密钥为空
-- 密钥仍为默认值
-- 密钥长度 < 16
-- CORS 为通配模式
-- Admin 页面无门禁 token
+**修复建议**
+- 统一使用 `rate_limit_store.get_client_ip(request)` 提取客户端 IP
+- 注意 FASTAPI-PROXY-001：仅在受信反代后才信任 X-Forwarded-For
 
 ---
 
-### H5. `.env.example` 缺少安全配置项与告警
+### NL2. JWT 算法固定 HS256 → 密钥轮换困难（FASTAPI-AUTH-004）
 
-**位置**：`.env.example`
+**位置**：`app/auth.py:24` `ALGORITHM = "HS256"`、`app/api/user_files.py:48` 同样
 
-**修复**
-- 顶部新增"安全提示"块，列出生产部署前必须检查的 5 项
-- 新增 `XTC_CORS_ORIGINS=` 配置项及说明
+**风险**
+- HS256 单一密钥用于签发与验证，密钥泄露即等于完全失陷
+- 无 `kid` (Key ID) 头部，无法支持多密钥平滑轮换
+- `XTC_JWT_SECRET` 一旦泄露，所有已签发 token 在过期前都有效，无法吊销
+- RS256 / ES256（非对称）允许公钥分发、私钥保护，更适合多服务场景
 
----
+**修复建议**
+- 短期：保留 HS256，但加 `kid` 头部支持密钥轮换（旧密钥保留用于验证，新密钥用于签发）
+- 长期：迁移到 RS256，私钥仅 admin 持有，公钥可分发到验证方
+- 引入密钥定期轮换机制（如每 90 天）
 
-## 四、Low 级别问题与修复
+---
 
-### L1. `image_fix` 拉取失败时向客户端透出 `str(e)`
+### NL3. `_warn_insecure_secrets()` 仅启动时告警，运行时不阻断
 
-**位置**：`app/api/image_fix.py`
+**位置**：`app/main.py` `_warn_insecure_secrets()`（基于 summary）
 
-**修复**：`httpx.HTTPError` 只回固定文案 `"failed to fetch image"`；`fix_image_bytes` 异常只回 `"image fix failed"` + 服务端 `logger.exception`
+**风险**
+- 启动告警只在 `lifespan` 启动时打一次，部署者若不查看启动日志（HF Space 默认不展示）则完全无感知
+- 运行时即使检测到弱密钥也不拒绝请求
 
-### L2. 图片 URL 无长度限制
+**修复建议**
+- 启动时若检测到弱密钥 + `ENV=production`，直接 `raise RuntimeError` 拒绝启动
+- 提供 `/health` 接口返回安全状态（仅供受信反代 / 内网访问）
+- 接入 HF Space 的通知机制（如环境变量 `HF_SPACE_AUTHOR_EMAIL` 发邮件）
 
-**位置**：`app/api/image_fix.py`
+---
 
-**修复**：`body.image` 长度上限 8192，超出 400 拒绝
+## 五、已修复问题（第一轮，保留作为参考）
+
+| ID | 问题 | 状态 |
+|----|------|------|
+| C1 | 通配 CORS `*` | 已修复（`app/cors.py` 白名单模式） |
+| C2 | `/v1/xtc/image/fix/test` SSRF | 已修复（`_fetch_remote_image_safely`） |
+| C3 | `/logs/api/log` 无鉴权 | 已修复（加 `require_access_key`） |
+| C4 | 异常 `str(exc)` 透出客户端 | 已修复（`unhandled_exception_handler` 收敛） |
+| H1 | 鉴权端点无暴力破解防护 | 已修复（`rate_limit_store.check_auth_rate_limit`） |
+| H2 | 限流未覆盖鉴权/日志路径 | 已修复 |
+| H3 | `x-xtc-user-token` 未脱敏 | 已修复 |
+| H4 | 弱密钥无启动告警 | 已修复（`_warn_insecure_secrets`，但见 NL3） |
+| H5 | `.env.example` 缺安全配置 | 已修复 |
+| L1 | `image_fix` 异常透出 | 已修复 |
+| L2 | 图片 URL 无长度限制 | 已修复（8192） |
 
 ---
 
-## 五、已存在的安全机制（继���保留）
+## 六、本轮修改文件清单
+
+本轮为**纯审计报告**，未修改任何源代码文件。修复工作待用户确认后按优先级分批进行。
 
-- bcrypt 密码哈希（`_hash_password` / `_verify_password`）
-- JWT HS256 签名 + SQLite 吊销列表（`verify_access_token`）
-- 时间常量比较（`_consteq`）防 admin key 时序攻击
-- SQLite WAL 模式 + 后台写线程（`db_writer`）避免事件循环阻塞
-- 参数化 SQL 全程使用 `?` 占位符（无字符串拼接 SQL 注入面）
-- 扫描器拦截中间件（`ScannerBlockMiddleware`）：检测扫描行为拉黑 IP 5 分钟
-- 自动文档端点关闭（`docs_url=None`、`redoc_url=None`、`openapi_url=None`）
-- `/admin` 页面门禁（`XTC_ADMIN_ACCESS_TOKEN`）：未配置 token 时启动告警
-- HF Hub 配置备份脱敏：日志只回 `***<last4>`
+仅修改 / 新增以下文件：
+- `security_best_practices_report.md`（本报告，覆盖更新）
 
 ---
 
-## 六、部署 checklist
+## 七、修复优先级建议
+
+按"风险 × 利用难度"排序，建议按以下顺序修复：
+
+1. **立即修复**（1 周内）：
+   - NC2：未配置 access_key 时强制拒绝启动生产模式
+   - NC1：移除 admin `?k=<token>` query 形式；用户 JWT query 形式加 TTL 收紧
+   - NC3：admin 数据 API 全部接入 audit_log
+
+2. **短期修复**（2 周内）：
+   - NH1：对话内容入库前脱敏 / 截断
+   - NH2：admin login 统一错误响应
+   - NH4：备份上传 session 加并发上限
+   - NM2：用户 JWT TTL 缩短 + 加服务端吊销
 
-部署到生产前请逐项确认：
+3. **中期修复**（1 个月内）：
+   - NH3：移除 Basic auth scheme 支持
+   - NM1：DB 文件 chmod 600 + 拒绝 /tmp fallback
+   - NM3：scanner middleware 修复白名单死代码
+   - NM4：注销账号级联清理 + 审计
 
-- [ ] `XTC_ADMIN_KEY` 已改为 ≥32 字符随机串（`openssl rand -hex 32`）
-- [ ] `XTC_ACCESS_KEY` 已改为 ≥32 字符随机串
-- [ ] `XTC_JWT_SECRET` 已改为 ≥32 字符随机串
-- [ ] `XTC_CORS_ORIGINS` 已配置为前端实际域名（逗号分隔多个）
-- [ ] `XTC_ADMIN_ACCESS_TOKEN` 已配置（给 `/admin` 页面加门禁）
-- [ ] `XTC_DISABLE_ADMIN=false`（除非确实要关闭后台）
-- [ ] 启动日志中无 `[startup] ... is EMPTY / still the default value / too short` 告警
-- [ ] 启动日志中无 `XTC_CORS_ORIGINS not set` 告警
-- [ ] `.env` 文件未提交到代码仓库（已在 `.gitignore` 中）
-- [ ] HF_TOKEN（若启用 Hub 备份）为只读或限定仓库的细粒度 token
+4. **长期优化**（按规划）：
+   - NL1/NL2/NL3：IP 提取统一、JWT 算法升级、启动告警升级
 
 ---
 
-## 七、本次修改的文件清单
-
-| 文件 | 修改类型 | 说明 |
-|------|----------|------|
-| `app/cors.py` | 新增 | CORS 策略中心 |
-| `app/config.py` | 修改 | 新增 `xtc_cors_origins` 字段与 validator |
-| `app/main.py` | 修改 | 启动告警 / 动态 CORSMiddleware / 动态预检 |
-| `app/errors.py` | 修改 | 动态 CORS / `unhandled_exception_handler` 不暴露 `str(exc)` |
-| `app/api/_common.py` | 修改 | 动态 CORS_HEADERS / `ok_json` 支持 `origin` 参数 |
-| `app/api/image_fix.py` | 修改 | SSRF 防护 / 输入长度限制 / 异常信息收敛 |
-| `app/api/logs.py` | 修改 | access_key 鉴权 / 字段长度限制 / 批量上限 |
-| `app/middleware.py` | 修改 | 鉴权限流接入 / 429 动态 CORS |
-| `app/api/admin.py` | 修改 | admin 登录失败跟踪 |
-| `app/api/user_files.py` | 修改 | 注册/登录失败跟踪 |
-| `app/services/rate_limit_store.py` | 修改 | 鉴权限流模块 / 失败锁定 |
-| `app/services/request_log_store.py` | 修改 | 敏感标头脱敏扩充 |
-| `.env.example` | 修改 | 安全提示 / `XTC_CORS_ORIGINS` 配置 |
-| `security_best_practices_report.md` | 新增 | 本报告 |
+## 八、部署 Checklist（在第一轮基础上新增）
+
+生产部署前请逐项确认（在第一轮 checklist 基础上新增）：
+
+- [ ] `XTC_ACCESS_KEY` 已配置（否则 NC2 风险）
+- [ ] `XTC_ADMIN_ACCESS_TOKEN` 未通过 URL query 共享给他人（NC1）
+- [ ] 用户 JWT TTL 已通过环境变量收紧（若提供 `XTC_USER_TOKEN_TTL_SEC` 配置项）
+- [ ] admin 数据操作审计日志已启用（NC3 修复后）
+- [ ] `/u/api/*` 路径的请求体不被记录到 request_log（NH1 修复后）
+- [ ] DB 文件权限为 600（NM1 修复后）
+- [ ] `/tmp/xtc.db` fallback 路径在生产模式被禁用（NM1 修复后）
+- [ ] 备份上传 session 并发上限已配置（NH4 修复后）
 
 ---
 
-## 八、后续建议（未在本次范围内）
+## 九、本轮审计未覆盖范围
+
+声明以下范围本轮未深入审查，建议后续补充：
+
+- `app/adapters/` 下的 Gemini / OpenAI 适配器代码（请求构造、错误处理）
+- `app/providers/keypool.py` 上游 API Key 轮换逻辑
+- `app/services/webhook_store.py` Webhook URL 是否有 SSRF 校验
+- `app/api/webhooks.py` Webhook 注册接口的 URL 校验
+- `app/api/openai_compat.py` OpenAI 兼容端点的鉴权继承
+- `app/api/sessions.py` 会话 API 的跨用户访问校验（已在第一轮简评，建议本轮补充）
+- 前端 `admin_html.py` / `user_html.py` 内嵌 JS 的 XSS 防护（已用 `esc()` 函数，但未做 CSP 头）
+- HF Space 平台层的网络隔离 / 卷权限（属平台范畴）
+
+---
 
-- 引入结构化日志（JSON）方便接入 SIEM
-- 给 `/v1/*` 业务接口加 per-device_id 限流维度（已有 per-key/per-ip）
-- 把鉴权失败计数持久化到 SQLite，避免重启后丢失锁定状态
-- 给 admin 接口加二次认证（TOTP / WebAuthn）
-- 上游 API Key 轮换监控（keypool 健康检查）
-- 引入 CSP / HSTS / X-Content-Type-Options 等安全响应头（需在反向代理层配置）
-- 定期备份 SQLite 到 HF Hub（已有 user_files 备份，可扩展到全库）
+**报告完。** 如需对任一发现展开修复，请告知具体 ID（如 "修复 NC1"），将按"单 finding 单 commit"原则实施。