From 41881e81f3a601a0f838e93c57339ed816ba816d Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Tue, 4 Aug 2026 20:06:23 +0800 Subject: [PATCH] docs(tasks): define T-301 auth failure semantics --- docs/tasks/T-301.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/tasks/T-301.md b/docs/tasks/T-301.md index 86cfb26..39610b7 100644 --- a/docs/tasks/T-301.md +++ b/docs/tasks/T-301.md @@ -25,7 +25,7 @@ write_paths: - docs/04-architecture.md --- - + ## 问题 / 背景 T-204 已提供设备认证注入点，但生产实现固定拒绝全部设备请求。T-301 为采购工具建立可签发、可撤销、服务端逐请求校验的设备凭据，并把管理员会话与设备 Bearer 能力严格隔离；不提前实现领取、租约或客户端 HTTP 适配。 @@ -40,10 +40,10 @@ T-204 已提供设备认证注入点，但生产实现固定拒绝全部设备 ## 方案 1. 新增通用 `deviceauth` 包，提供设备主体和认证接口；把 T-204 位于 evidence 包内的临时接口迁出，证据上传改用通用主体，避免后续设备路由重复定义身份。 -2. SQLite 新增设备凭据表：设备 id 为规范小写 UUID，显示名为非秘密元数据，token 只保存 SHA-256，状态仅 ACTIVE/REVOKED，并用时间字段约束撤销状态一致性。 +2. SQLite 新增设备凭据表：设备 id 为规范小写 UUID，显示名为非秘密元数据，token 只保存 32 字节 SHA-256 BLOB，状态仅 ACTIVE/REVOKED，并用时间字段约束撤销状态一致性。 3. 凭据签发生成 32 字节加密随机 token，对外只显示一次 64 位小写十六进制明文；数据库、日志、错误、HTTP 响应均不得保存或回显 token 明文。提供显式数据库路径的管理 CLI，支持 issue、list、revoke；list 不显示 token/hash，重复 revoke 不得恢复凭据。 4. 设备请求必须同时提供且只提供一个 `Authorization: Bearer <64位小写十六进制token>` 与一个 `X-CMBuyer-Device-ID: <小写UUID>`；格式、重复头、空白、未知、token/device 不匹配和已撤销统一 401，不区分原因。 -5. 认证器每次请求查询 SQLite，不缓存 ACTIVE 结果，确保撤销立即生效；比较使用常量时间。数据库异常失败闭合且不泄露内部信息。 +5. 认证器每次请求查询 SQLite，不缓存 ACTIVE 结果，确保撤销立即生效；比较使用常量时间。请求头非法、未知、错配或已撤销统一返回空 401；SQLite 查询/连接故障返回空 503。两类都在读取请求体前失败闭合且不泄露内部信息。 6. 服务启动改用真实 SQLite 设备认证器；空凭据库仍拒绝全部。管理员 cookie 单独不能调用设备上传；Bearer 单独或与 cookie 并存均不能调用管理建单/开始采购，因为管理端仍只接受管理员 session + CSRF。 7. MVP 的采购服务与采购工具部署在同一运营电脑，服务进程只监听 127.0.0.1:8080；本机 HTTP 不经过网络。未来若开放非回环访问，必须先建立并验收 HTTPS/TLS 终止与代理信任边界，设备 Bearer 不得经过明文局域网。 8. 本任务只接通现有证据上传认证，不新增 heartbeat、claim、lease、event、fence、result 路由，不实现客户端保存/发送凭据，不接触真机选择器、提交订单或付款。 @@ -51,7 +51,7 @@ T-204 已提供设备认证注入点，但生产实现固定拒绝全部设备 ## 验收要点 - 迁移升级/重开/约束/回滚安全测试通过；数据库中不存在 token 明文。 -- 覆盖签发随机性与一次显示、规范格式、错误头矩阵、token/device 绑定、撤销即时生效、重复撤销、并发认证/撤销和数据库故障失败闭合。 +- 覆盖签发随机性与一次显示、规范格式、错误头矩阵、token/device 绑定、撤销即时生效、重复撤销、并发认证/撤销，以及数据库故障在 body 零读取下返回空 503。 - 覆盖身份隔离：管理员 cookie 不能上传证据；设备 Bearer 不能建单或开始采购；混合凭据不扩大任一身份权限。 - 现有证据上传在有效设备身份下保持原幂等/归属语义，认证仍先于 Content-Type 和 body 读取。 - `go test ./...`、`go test -race ./...`、`go vet ./...`、`go build ./...`、完整 init、上下文校验与 diff-check 全部通过。 @@ -65,6 +65,10 @@ T-204 已提供设备认证注入点，但生产实现固定拒绝全部设备 ### 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 不得经过明文局域网。 + +### 2026-08-04T12:06:14Z · ila + +2026-08-04 编码前错误语义定值：请求头非法、未知、token/device 错配和已撤销统一空 401；SQLite 查询/连接故障统一空 503。两类都必须在读取 body 和调用业务处理器前失败闭合，响应不含内部原因。token_sha256 采用 32 字节 BLOB。 ## 边界 @@ -74,7 +78,8 @@ T-204 已提供设备认证注入点，但生产实现固定拒绝全部设备 - 设备 token 必须由加密安全随机源生成，只在签发成功时向操作者显示一次；SQLite、日志、错误响应、 HTTP 响应、Git、Vikunja 和测试 fixture 均不得保存或回显明文 token。数据库只保存 token SHA-256。 - 认证必须同时绑定规范设备 id 与 token，并在解析请求体之前完成。格式错误、重复头、未知凭据、 - token/device 不匹配、已撤销和认证存储异常均 fail closed；对外不得泄露具体失败原因。 + token/device 不匹配和已撤销统一返回空 `401`；认证存储异常返回空 `503`。两类失败都必须 + fail closed、不得调用业务处理器或读取请求体，也不得泄露具体原因。 - MVP 的采购服务与采购工具部署在同一运营电脑，生产服务必须只监听回环地址；只允许 `http://127.0.0.1` / `http://localhost` 的本机通信。未来若开放非回环访问，必须先单独建立并验收 HTTPS/TLS 终止与代理信任边界，不得让设备 Bearer 经过明文局域网。