From e3c87fdec5f53513e4c9cdf6300ea39c2a7a6fde Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Tue, 4 Aug 2026 20:05:03 +0800 Subject: [PATCH] docs(tasks): secure T-301 transport boundary --- docs/tasks/T-301.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/tasks/T-301.md b/docs/tasks/T-301.md index 6f91120..86cfb26 100644 --- a/docs/tasks/T-301.md +++ b/docs/tasks/T-301.md @@ -2,7 +2,7 @@ id: T-301 title: 设备凭据与身份隔离（F-013） phase: 3 -deps: [T-201] +deps: [T-201, T-204] status: DOING created: 2026-08-04 vikunja_task_id: 33 @@ -25,7 +25,7 @@ write_paths: - docs/04-architecture.md --- - + ## 问题 / 背景 T-204 已提供设备认证注入点，但生产实现固定拒绝全部设备请求。T-301 为采购工具建立可签发、可撤销、服务端逐请求校验的设备凭据，并把管理员会话与设备 Bearer 能力严格隔离；不提前实现领取、租约或客户端 HTTP 适配。 @@ -34,7 +34,7 @@ T-204 已提供设备认证注入点，但生产实现固定拒绝全部设备 - 功能：F-013。 - 用户故事：US-007。 -- 依赖：T-201；复用 T-204 的证据上传认证入口。 +- 依赖：T-201、T-204；复用 T-204 的证据上传认证入口。 - 后续消费者：T-302 领取/租约、T-303 客户端 HTTP 适配。 ## 方案 @@ -45,7 +45,8 @@ T-204 已提供设备认证注入点，但生产实现固定拒绝全部设备 4. 设备请求必须同时提供且只提供一个 `Authorization: Bearer <64位小写十六进制token>` 与一个 `X-CMBuyer-Device-ID: <小写UUID>`；格式、重复头、空白、未知、token/device 不匹配和已撤销统一 401，不区分原因。 5. 认证器每次请求查询 SQLite，不缓存 ACTIVE 结果，确保撤销立即生效；比较使用常量时间。数据库异常失败闭合且不泄露内部信息。 6. 服务启动改用真实 SQLite 设备认证器；空凭据库仍拒绝全部。管理员 cookie 单独不能调用设备上传；Bearer 单独或与 cookie 并存均不能调用管理建单/开始采购，因为管理端仍只接受管理员 session + CSRF。 -7. 本任务只接通现有证据上传认证，不新增 heartbeat、claim、lease、event、fence、result 路由，不实现客户端保存/发送凭据，不接触真机选择器、提交订单或付款。 +7. MVP 的采购服务与采购工具部署在同一运营电脑，服务进程只监听 127.0.0.1:8080；本机 HTTP 不经过网络。未来若开放非回环访问，必须先建立并验收 HTTPS/TLS 终止与代理信任边界，设备 Bearer 不得经过明文局域网。 +8. 本任务只接通现有证据上传认证，不新增 heartbeat、claim、lease、event、fence、result 路由，不实现客户端保存/发送凭据，不接触真机选择器、提交订单或付款。 ## 验收要点 @@ -60,6 +61,10 @@ T-204 已提供设备认证注入点，但生产实现固定拒绝全部设备 ### 2026-08-04T12:00:56Z · ila 2026-08-04 开始 T-301：依赖 T-201 已完成，任务定义提交 a6ad560。实现范围严格限于设备凭据签发/撤销、逐请求 Bearer+设备 id 认证、身份隔离及接通 T-204 证据上传；不新增领取/租约/事件/围栏/结果接口，不接触真机或提交/付款。工作分支 task/t-301-device-auth。 + +### 2026-08-04T12:04:54Z · ila + +2026-08-04 编码前安全收紧：T-301 实际复用 T-204 认证注入点和 00003 后续迁移，依赖补为 T-201、T-204。MVP 已定为单机部署，生产服务改为仅监听 127.0.0.1:8080；未来非回环访问必须先建立 HTTPS/TLS 终止与代理信任边界，设备 Bearer 不得经过明文局域网。 ## 边界 @@ -70,6 +75,9 @@ T-204 已提供设备认证注入点，但生产实现固定拒绝全部设备 HTTP 响应、Git、Vikunja 和测试 fixture 均不得保存或回显明文 token。数据库只保存 token SHA-256。 - 认证必须同时绑定规范设备 id 与 token，并在解析请求体之前完成。格式错误、重复头、未知凭据、 token/device 不匹配、已撤销和认证存储异常均 fail closed；对外不得泄露具体失败原因。 +- MVP 的采购服务与采购工具部署在同一运营电脑，生产服务必须只监听回环地址；只允许 + `http://127.0.0.1` / `http://localhost` 的本机通信。未来若开放非回环访问，必须先单独建立并验收 + HTTPS/TLS 终止与代理信任边界，不得让设备 Bearer 经过明文局域网。 - 撤销必须逐请求立即生效，不得缓存已认证结果，不得通过重复签发或重复撤销恢复旧 token。轮换属于 后续任务，本任务不提供会让旧 token 重新生效的路径。 - 本任务只把真实设备认证接到 T-204 已有截图上传入口；不得新增 heartbeat、claim、lease、event、