docs(tasks): define T-301 device identity

docs/tasks/T-301.md

@@ -0,0 +1,77 @@
+---
+id: T-301
+title: 设备凭据与身份隔离（F-013）
+phase: 3
+deps: [T-201]
+status: TODO
+created: 2026-08-04
+vikunja_task_id: 33
+context_ref: 6a5547b
+work_branch: task/t-301-device-auth
+needs_device: false
+needs_human_review: false
+write_paths:
+  - docs/tasks/T-301.md
+  - admin/migrations/00004_device_credentials.sql
+  - admin/internal/migrations/migrations_test.go
+  - admin/internal/deviceauth/**
+  - admin/internal/evidence/**
+  - admin/internal/storage/evidence/**
+  - admin/internal/server/**
+  - admin/cmd/device-credentials/**
+  - admin/cmd/server/**
+  - admin/README.md
+  - docs/api.md
+  - docs/04-architecture.md
+  - docs/current-state.md
+---
+
+<!-- BEGIN VIKUNJA EXPORT id=33 synced=2026-08-04T12:00:29Z sha256=f42e17b9c709203841238be96f3cfb25ea7ff0b6da2d29aba71b512eecc2528c -->
+## 问题 / 背景
+
+T-204 已提供设备认证注入点，但生产实现固定拒绝全部设备请求。T-301 为采购工具建立可签发、可撤销、服务端逐请求校验的设备凭据，并把管理员会话与设备 Bearer 能力严格隔离；不提前实现领取、租约或客户端 HTTP 适配。
+
+## 关联需求与交互
+
+- 功能：F-013。
+- 用户故事：US-007。
+- 依赖：T-201；复用 T-204 的证据上传认证入口。
+- 后续消费者：T-302 领取/租约、T-303 客户端 HTTP 适配。
+
+## 方案
+
+1. 新增通用 `deviceauth` 包，提供设备主体和认证接口；把 T-204 位于 evidence 包内的临时接口迁出，证据上传改用通用主体，避免后续设备路由重复定义身份。
+2. SQLite 新增设备凭据表：设备 id 为规范小写 UUID，显示名为非秘密元数据，token 只保存 SHA-256，状态仅 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 结果，确保撤销立即生效；比较使用常量时间。数据库异常失败闭合且不泄露内部信息。
+6. 服务启动改用真实 SQLite 设备认证器；空凭据库仍拒绝全部。管理员 cookie 单独不能调用设备上传；Bearer 单独或与 cookie 并存均不能调用管理建单/开始采购，因为管理端仍只接受管理员 session + CSRF。
+7. 本任务只接通现有证据上传认证，不新增 heartbeat、claim、lease、event、fence、result 路由，不实现客户端保存/发送凭据，不接触真机选择器、提交订单或付款。
+
+## 验收要点
+
+- 迁移升级/重开/约束/回滚安全测试通过；数据库中不存在 token 明文。
+- 覆盖签发随机性与一次显示、规范格式、错误头矩阵、token/device 绑定、撤销即时生效、重复撤销、并发认证/撤销和数据库故障失败闭合。
+- 覆盖身份隔离：管理员 cookie 不能上传证据；设备 Bearer 不能建单或开始采购；混合凭据不扩大任一身份权限。
+- 现有证据上传在有效设备身份下保持原幂等/归属语义，认证仍先于 Content-Type 和 body 读取。
+- `go test ./...`、`go test -race ./...`、`go vet ./...`、`go build ./...`、完整 init、上下文校验与 diff-check 全部通过。
+
+## 执行记录
+
+（暂无）
+<!-- END VIKUNJA EXPORT -->
+
+## 边界
+
+- 设备身份与管理员身份必须保持能力隔离：设备 Bearer 不得建单、开始采购、重置或调和；管理员
+  session 不得代替设备领取、上传或调用后续设备接口。两类凭据同时出现也不得扩大任何一方权限。
+- 设备 token 必须由加密安全随机源生成，只在签发成功时向操作者显示一次；SQLite、日志、错误响应、
+  HTTP 响应、Git、Vikunja 和测试 fixture 均不得保存或回显明文 token。数据库只保存 token SHA-256。
+- 认证必须同时绑定规范设备 id 与 token，并在解析请求体之前完成。格式错误、重复头、未知凭据、
+  token/device 不匹配、已撤销和认证存储异常均 fail closed；对外不得泄露具体失败原因。
+- 撤销必须逐请求立即生效，不得缓存已认证结果，不得通过重复签发或重复撤销恢复旧 token。轮换属于
+  后续任务，本任务不提供会让旧 token 重新生效的路径。
+- 本任务只把真实设备认证接到 T-204 已有截图上传入口；不得新增 heartbeat、claim、lease、event、
+  submission-fence 或 result 路由，不实现客户端凭据持久化和 HTTP 适配。
+- 不接触拼多多页面判据、规格选择、数量、确认页或真机流程；不编写点击“提交订单”、支付、免密支付、
+  先用后付或任何扣款控件的代码。