docs(stage-1): API key control-plane default-deny design spec

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-28 21:05:14 +08:00
parent cdd9d6701f
commit a173d4f93c
1 changed files with 181 additions and 0 deletions
@@ -0,0 +1,181 @@
+# API Key 控制平面 default-deny 收口 · 设计
+
+> 写于 2026-06-28。收口 Stage 1 final review 记录的最小权限缺口（[stage-1 design §8.1](../../multi-tenant-redesign/01-redesign/stage-1-headless-api-pattern-a-auth-foundation-design.zh-CN.md)）。
+>
+> **承接：** [Stage 1 · Headless API Pattern A 鉴权地基](../plans/2026-06-28-stage-1-headless-api-pattern-a-auth-foundation.md)（已完成）。本设计是轨道二的安全补丁，不是新功能。
+
+## 1. 背景与问题
+
+Stage 1 让业务系统用 workspace-scoped API key（`Authorization: Bearer dfk_...`）server-to-server 直调 Gateway。鉴权热路径在 `AuthMiddleware` 的 bearer 分支解析 token → `ServicePrincipal`，并把 `(user_id=SA.id, workspace_id)` 写进 contextvar，使下游隔离与真人同构。
+
+落地后的整体安全复核（2026-06-28）发现一处最小权限缺口（stage-1 design §8.1）：
+
+- **scope 只在 `@require_permission` 装饰的路由上生效。** `AuthContext.permissions`（由 key 的 scopes 填充）只被 `@require_permission` 读取，而该装饰器目前只挂在 threads/runs/uploads/artifacts/feedback/suggestions 上。
+- `mcp`（`PUT /api/v1/mcp/config`）、`skills`（`POST /api/v1/skills/install`）、`channels`（`restart`）、`models`、`agents`、`memory` 等路由**只校验"已认证",不校验 scope/role**。
+- 后果：一把 `scopes="threads:read"` 的 key 仍能改全局 MCP 配置、装技能、重启 channel。
+- 更严重：这些目标是**进程级全局资源**（`extensions_config.json`、磁盘上的 skills、channel 进程），不是 workspace 分区的。对它们而言 workspace 隔离也不成立——一个租户的 key 改的是所有租户共享的配置。
+
+### 根因再定位
+
+这不是"几条路由忘了加 scope 检查"。真正的原因是：`_ALL_PERMISSIONS` 里**只有 6 个 `threads:*` / `runs:*` 权限**——控制平面路由从来就不在权限模型里。真人能访问它们，仅仅是因为它们未被装饰。API key 出现后，这些"对所有已认证者开放"的全局控制路由,意外地也对 service principal 开放了。
+
+## 2. 目标与非目标
+
+**目标**
+- service principal（API key 请求）只能访问**数据平面**;任何控制平面路由 → 403。
+- 真人 / cookie 请求行为**完全不变**。
+- 默认拒绝（default-deny）：将来新增控制平面路由,自动被拦,不复现本次"忘了保护"的缺陷。
+- 读、写一律拒（不区分 method）。
+
+**非目标（明确推后）**
+- 不引入 per-scope 细粒度授权（`scopes=["mcp:write"]` 之类的词汇升级）——留到 external_user 透传 / scope 升级 PR（stage-1 design D4 已推后）。
+- 不把控制平面资源改成 workspace 分区(那是更大的多租户改造)。
+- 不动 `@require_permission` / `_ALL_PERMISSIONS` 现有语义。
+- 不处理 Pattern B（短期 JWT / service-token 分支）——但要为其留好复用接缝。
+
+## 3. 设计
+
+### 3.1 数据平面边界
+
+> **关键前提（已验证）：** nginx 把 `/api/langgraph/(.*)` **rewrite 成 `/api/$1`** 后才转给 gateway(见 `docker/nginx/nginx.local.conf` L48-51);IM channels 也直连 gateway 的 `/api/*`(`langgraph_url` 默认 `http://localhost:8001/api`)。因此 `AuthMiddleware` **永远看不到 `/api/langgraph` 前缀**——LangGraph-SDK 的调用到达中间件时就是 `/api/threads`、`/api/runs`、`/api/assistants` 这些真实 router 路径。gateway 本身没有挂任何 `/api/langgraph` 路由,该前缀是纯 nginx 别名,放进白名单是死代码。
+
+对照 Gateway 路由表(`app/gateway/app.py` include_router + 各 router prefix),**数据平面 / SDK 接口只落在三个前缀下**：
+
+| 前缀 | 覆盖的 router | 性质 |
+|---|---|---|
+| `threads*` | threads、thread-runs、uploads（`/threads/{id}/uploads`）、artifacts、suggestions、feedback(均 `/threads/...`) | 数据平面 |
+| `runs*` | 无状态 runs（`/runs`） | 数据平面 |
+| `/api/assistants` | `assistants_compat`——**langgraph-sdk 客户端 init 必需**(`assistants.search()`/`get()`),只读元数据,单挂(无 `/api/v1` twin) | SDK init |
+
+因此 service principal 的白名单很小且稳定：
+
+```
+/api/threads      /api/v1/threads
+/api/runs         /api/v1/runs
+/api/assistants
+```
+
+> 不放 `/api/langgraph`(死代码,见上)。`assistants` 单挂故只有一条 `/api/assistants`(无版本)。
+
+**其余一律拒绝**（对 SA）：`models`、`mcp`、`memory`、`skills`、`channels`、`agents`,以及 `service-accounts`、`api-keys`、`auth`。
+
+- 管理类 endpoint（`service-accounts`/`api-keys`）本来就因 `require_workspace_admin`(SA role=member)对 SA 返回 403。default-deny 让它**更早、更统一**地 403,不改变可达性结论。
+- `auth`（`/api/v1/auth/*`）当前对 SA 无意义,拒掉无副作用。
+
+### 3.2 enforce 位置
+
+在 `app/gateway/auth_middleware.py` 的 `AuthMiddleware.dispatch` bearer 分支内,`result` 校验通过之后、写 contextvar / `call_next` 之前插入路径检查：
+
+```python
+if auth_header.startswith("Bearer dfk_"):
+    ...
+    if result is None:
+        return JSONResponse(status_code=401, ...)  # 现有
+    # ↓ 新增：service principal 只能走数据平面
+    if not _is_dataplane_path(request.url.path):
+        return JSONResponse(
+            status_code=403,
+            content={"detail": AuthErrorResponse(
+                code=AuthErrorCode.INSUFFICIENT_SCOPE,
+                message="API keys cannot access this endpoint",
+            ).model_dump()},
+        )
+    request.state.user = result.principal
+    ...
+```
+
+放在 bearer 分支内的理由：
+- 真人 cookie 路径根本不进这段,天然不受影响。
+- 检查发生在 `_is_public` 早退之后——公共路径(`/health` 等)即便带 bearer 头也先被 `_is_public` 放行,不进此分支,符合预期。
+
+### 3.3 辅助函数
+
+仿照现有 `_is_public(path)` / `_PUBLIC_PATH_PREFIXES`,在同文件新增模块级常量与函数：
+
+```python
+_DATAPLANE_PREFIXES = (
+    "/api/threads",
+    "/api/v1/threads",
+    "/api/runs",
+    "/api/v1/runs",
+    "/api/assistants",  # langgraph-sdk client init (assistants.search/get), 只读
+)
+
+
+def _is_dataplane_path(path: str) -> bool:
+    """service principal 允许访问的数据平面 / SDK 路由前缀。
+
+    数据平面挂在 threads / runs 下;langgraph-sdk init 需要 assistants。
+    其余(全局控制平面:models/mcp/memory/skills/channels/agents 与
+    管理/auth 端点)对 API key 一律拒绝。注意 `/api/langgraph` 被 nginx
+    rewrite 掉,中间件看不到,故不在表内。将来 Pattern B 的 service-token
+    分支可复用本函数。
+    """
+    return any(path.startswith(p) for p in _DATAPLANE_PREFIXES)
+```
+
+> **前缀匹配的精度**：用 `startswith`,与 `_is_public` 一致。`/api/threads` 前缀不会误放行 `/api/threads-foo` 之类的路径吗?当前路由表无此类同名前缀冲突(控制平面均为独立段:`/api/models`、`/api/mcp` 等),故 `startswith` 安全。若未来出现冲突,改为带边界的匹配即可——本设计不预防尚不存在的冲突(YAGNI)。
+
+### 3.4 错误口径
+
+新增 `AuthErrorCode.INSUFFICIENT_SCOPE = "insufficient_scope"`（`app/gateway/auth/errors.py`）。该枚举定位是"穷举所有 auth 失败条件",新增一个符合既有模式。
+
+- HTTP 403(已认证但无权),区别于无效 key 的 401。
+- 响应体 `{"detail": {"code": "insufficient_scope", "message": ...}}`,与现有 401 `AuthErrorResponse` 完全同构。
+
+## 4. 测试影响
+
+### 4.1 现有探针测试需调整(有意,非绕过)
+
+`tests/test_auth_middleware_api_key.py` 与 `tests/test_headless_api_smoke.py` 用 `/api/probe` 作探针路由。该路径不属数据平面,default-deny 会把它 403——但这些探针的**本意**就是"SA 访问一个受保护的数据平面路由"。
+
+处理:把探针路径挪到数据平面前缀下(如 `/api/v1/threads/_probe`)。这是让测试反映真实约束的正确修正。涉及:
+- `test_valid_bearer_sets_sa_contextvars`(探针仍应 200,验证 contextvar)
+- `test_headless_api_smoke` 的 `_probe_app`(mint→use 链路仍应 200)
+- 其余 401/revoked 用例不受影响(它们本就期望非 200)
+
+### 4.2 新增 `tests/test_api_key_control_plane.py`
+
+| 用例 | 期望 |
+|---|---|
+| SA bearer → `PUT /api/v1/mcp/config` | 403 `insufficient_scope` |
+| SA bearer → `GET /api/v1/models` | 403(**读也拒**) |
+| SA bearer → `POST /api/v1/skills/install` | 403 |
+| SA bearer → `/api/mcp`(无版本旧路径) | 403 |
+| SA bearer → `/api/v1/channels/...`、`/api/v1/agents`、`/api/v1/memory` | 403 |
+| SA bearer → `/api/v1/threads/_probe` | 放行(数据平面) |
+| SA bearer → `/api/assistants/search`(SDK init) | 放行 |
+| cookie/真人 → `/api/v1/mcp`(或任一控制平面) | 不受影响(回归守护——不进 bearer 分支) |
+| `_is_dataplane_path` 表驱动单元 | threads/runs(含 `/api` 与 `/api/v1` 双形态)、`/api/assistants` → True;控制平面前缀(含 `/api/langgraph`,死代码也应 False)→ False |
+
+### 4.3 回归
+
+- `make test` 全绿(含 stage-1 的 13 个文件)。
+- `make lint` clean、`test_harness_boundary` PASS(本改动全在 app 层)。
+
+## 5. 文件清单
+
+**修改**
+- `backend/app/gateway/auth/errors.py` — 加 `AuthErrorCode.INSUFFICIENT_SCOPE`
+- `backend/app/gateway/auth_middleware.py` — 加 `_DATAPLANE_PREFIXES` + `_is_dataplane_path` + bearer 分支 403 检查
+- `backend/tests/test_auth_middleware_api_key.py` — 探针路径挪到 `/api/v1/threads/_probe`
+- `backend/tests/test_headless_api_smoke.py` — 同上
+
+**新增**
+- `backend/tests/test_api_key_control_plane.py`
+
+**文档**
+- `docs/multi-tenant-redesign/01-redesign/stage-1-headless-api-pattern-a-auth-foundation-design.zh-CN.md` — §8.1 从"已知限制"翻成"已解决",指向本 PR
+
+## 6. 不可逆 / 需想清楚的点
+
+| 决策 | 取舍 |
+|---|---|
+| 数据平面边界 = threads/runs/assistants 三前缀 | 业务系统已接入后收窄白名单 = 破坏调用方;故白名单只增不减。本次定的是最小集,后续按需 **加**(如 Pattern B 的 `exchange-token`)。 |
+| 读也拒(`GET /api/v1/models` 对 SA 403) | 若将来业务方需要列模型选型,再单独 allowlist 该 GET;default-deny 下"放开"比"收紧"安全。 |
+| 错误码 `insufficient_scope` | 接入方可能据此分支处理;改名要联调。早定。 |
+
+## 7. 与后续 PR 的接缝
+
+- **Pattern B（service-token 分支）**:复用 `_is_dataplane_path`。新增的 `exchange-token` endpoint 若需 SA 调用,记得把其路径加入 `_DATAPLANE_PREFIXES`(或单独放行)。
+- **scope 词汇升级**（`scopes=["mcp:write"]`):若将来要让特定 SA 受控访问某控制平面路由,在本 default-deny 之上叠加"白名单内再按 scope 细分"即可,不与本设计冲突。