docs: define web auth canonical principal spec

2026-06-18 15:25:26 +00:00
parent 362926118a
commit ccf0138b37
6 changed files with 52 additions and 2 deletions
@@ -37,6 +37,7 @@
 ### 2.2 范围内
 - Cloud Web 工作台、登录后工作流、任务创建、会话入口、trace/result 展示和用户可见资源入口。
 - Cloud Web 通过 `/auth/session` 消费 canonical identity，并以业务 API 返回的 capability/blocker 展示授权状态。
 - HWLAB CLI 的运行端点解析、API key 鉴权入口、同源 API 调用、短连接命令、结构化输出、错误语义和脚本可用性。
 - 通过 HWLAB CLI 覆盖账号/额度、工作台、显式 Agent session、Agent 任务、trace/result、HWPOD/CaseRun 组合入口和必要管理入口的非视觉全流程复验。
 - HTTP API 的同源 path、schema、错误语义、鉴权主体和多端一致性。
@@ -59,6 +60,7 @@
 | API 契约 | HTTP API 和错误语义的稳定调用约定。 |
 | 多客户端一致性 | 不同入口共享同一任务、权限、错误和结果语义。 |
 | 短连接命令 | 发起后快速返回可查询 ID 或紧凑结果，再通过 status、trace、result 或 watch 继续观察的 CLI 命令。 |
 | 前端身份消费 | Cloud Web 只调用 `/auth/session` 读取 canonical identity，并把后端返回的 capability/blocker 显示给用户；不保存、不派生、不输入其他身份凭据。 |
 ## 4. 系统边界和接口
@@ -93,6 +95,8 @@
 Web 工作台只承载用户交互和展示契约。身份真相来自用户管理，任务事实来自 Agent编排，硬件事实来自硬件池，评价语义来自 HarnessRL，公开入口健康来自平台运维。具体工作台框架、会话输入、诊断反馈和响应布局由 [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) 约束。
 Cloud Web 的认证态只能来自 `/auth/session` 返回的 canonical identity。前端不得保存或读取 user-billing token、API key secret、cookie prefix、Bearer token、localStorage authority 或测试专用后门来判断登录；业务页面只能根据后端 capability/blocker 展示可用、未开通、禁止或不可用状态。
 ### 6.2 CLIENT-L1-REQ-002 HWLAB CLI 入口
 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -65,7 +65,8 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同
 | 低噪声展示 | 诊断、trace、状态和辅助信息不抢占主任务区，也不伪装成用户或 Agent 正文。 |
 | 响应式工作台 | 同一工作台在桌面和移动端按不同可视空间重排，但仍优先保证任务输入和状态理解。 |
 | 同源业务入口 | Cloud Web 与 HWLAB CLI 通过同一 Web origin、相对 REST/JSON API path 和业务标识访问 HWLAB 能力的入口。 |
-| 浏览器登录态 | Cloud Web 随同源请求携带的 `hwlab_session` 等 Web session transport；前端只负责传递，不解释权限、project 归属或资源可见性。 |
+| 浏览器登录态 | Cloud Web 随同源请求携带的 `hwlab_session` Web session transport；前端只负责传递，不解释权限、project 归属或资源可见性。 |
 | canonical identity | Web 工作台从 `/auth/session` 读取的最小身份结果，包含 actor、`authMethod`、`identityAuthority`、`sessionKind` 和 capability 摘要；它是 Web shell、导航和业务页面的唯一身份输入。 |
 | Session权威入口 | Web 工作台按 sessionId 或后端认可的 opaque session handle 恢复当前会话消息、turn 摘要、trace 指针和状态的 RESTful detail API。 |
 | 共享 trace renderer | Web trace 面板和 HWLAB CLI `trace --render web` 共用的 trace row 转换语义。 |
 | Trace阅读视图 | 工作台中面向用户阅读 Code Agent trace 的默认视图，只展示用户可理解的助手消息、工具调用、命令输出、最终结果和真实耗时，把运行身份、隐藏统计和原始事件收束到消息详情入口。 |
@@ -219,6 +220,8 @@ Web工作台应提供登录后的稳定 shell，使用户能够在同一浏览
 工作台框架负责浏览器层面的布局、导航、topbar 状态和页面切换反馈。用户身份和 session 有效性由用户管理提供；公开入口和运行健康由平台运维提供。工作台不得用旧页面块、临时状态行或原始运行日志替代稳定导航与反馈。
 Web 工作台的 auth store 只能从 `/auth/session` 建立 canonical identity。路由 guard、topbar、admin 入口、Workbench、Usage、Billing 和 API keys 页面不得读取 user-billing token、API key secret、cookie prefix、Bearer token、localStorage authority 或旧测试后门。未登录时展示登录入口；已登录但能力不可用时展示后端结构化 blocker；前端不得通过二次登录、API key 输入或 fallback endpoint 修补身份。
 ### 6.2 CLIENT-WB-REQ-002 会话输入
 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -229,6 +232,8 @@ Web工作台应让用户在主任务区直接选择或创建会话、阅读用
 会话输入只负责用户可见的交互和消息呈现。基本 Agent 调用必须进入 Agent编排提供的执行生命周期，并返回用户可查询的 run、command、session 或等价状态入口；用户权限和会话有效性由用户管理提供。单条用户消息、trace 详情或状态摘要不得在默认视图中抢占主任务区，使用户难以继续输入。
 Workbench 业务 API 的可见性只能由后端从 canonical principal 和 Workbench/Code Agent capability 判断。Web 不得把 billing 状态、API key 是否存在、project/workspace localStorage、session tab cache 或 conversation metadata 当作身份 authority；capability 不可用时必须保留当前身份并显示业务 blocker。
 Web工作台必须使用显式 Agent session：无 session 时先让用户创建或选择 session，session failed、stale 或 canceled 时保留失败状态并要求用户显式切换或新建。刷新页面、重新打开工作台或短连接 result 轮询只能恢复已选 session、thread 和 trace 状态；除非用户登出或主动清空对话，不得自动生成新 conversation、替换 session 或用历史 prompt 拼接出续跑表象。
 会话列表、当前消息头、composer 主按钮和运行态动效必须先确定唯一权威 API，再由 Web 展示该 API 的结果；不得让 workspace selected conversation、snapshot、stub、localStorage、message 派生状态、trace 快照或浏览器临时缓存与权威 API 并列竞争、互相覆盖或按失败路径 fallback 成另一套数据源。已经定下来的 authority 不变量如下：浏览器登录态只作为请求 transport；资源归属、project 可见性和权限由后端从当前 Web session/AuthPrincipal 判定；session rail 会话集合的主入口是 `/v1/workbench/sessions`，当前 session 消息本体的主入口是 `/v1/workbench/sessions/{sessionId}/messages`，session metadata 的主入口是 `/v1/workbench/sessions/{sessionId}`，turn 状态的主入口是 `TurnSnapshot`，Trace 阅读状态的主入口是 `TraceEventPage`。`projectId`、`workspaceId` 和 `conversationId` 可以作为后端返回的上下文字段、显式筛选字段或迁移期 metadata，但不得成为前端鉴权、资源可见性、active session 或 deep link 的 authority。深链恢复、刷新、从其他 session 切回和 route watcher 应走同一 session detail/message page 加显式 select/update 路径，不得先用 workspace selected snapshot、列表摘要或空 stub 覆盖当前 `messages`，再等待另一路请求补齐。
@@ -269,6 +274,8 @@ Web工作台应与 HWLAB CLI 共享 Code Agent composer policy、trace renderer
 Web只负责浏览器交互与展示；CLI负责命令入口和结构化输出；API契约负责 path、schema 和错误语义；Agent编排负责执行事实。Web trace row 错乱、final response 缺失或发送状态异常等问题，应能先通过 CLI `trace --render web`、同源 REST request 和显式 Agent session 命令定位到共享 renderer、API 契约或浏览器表现层，不能让 Web 和 CLI 各自维护一套 trace 解释。
 同源体验中的身份验证以 `/auth/session` 为最小验收端点。D601 线上 web-probe 和 fake-server Playwright 都应先覆盖 fresh login、刷新后 identity 一致、未登录结构化 unauthenticated 和脱敏边界，再进入 Workbench、Usage、Billing 或 API keys 的业务消费回归。业务页面碰巧可用不能替代最小身份验证通过。
 工作台在增量刷新 trace、message 或 status 时，应保持用户已展开的详情状态和滚动位置。trace 压缩、sourceSeq 窗口或 event cap 只能影响默认摘要，不得吞掉可读 message、tool call、stderr/error 或 terminal 边界；需要完整事件时，Web 应通过 RESTful trace resource 自动请求完整可读事件，而不是让用户手工从原始日志中恢复上下文。RESTful trace resource 返回 `hasMore`、`nextSinceSeq` 或等价游标时，Web 必须继续通过同一资源入口分片请求，并在每个片段到达后立即合并渲染；不得等所有片段全部拉完才一次性显示，也不得为了补齐事件切换到 JSON-RPC、回放 Trace、内部 manager 或前端 fallback 路径。
 ### 6.6 CLIENT-WB-REQ-006 Trace阅读
@@ -19,7 +19,7 @@
 | 短名 | API契约 |
 | 层级 | L2 课题 |
 | 状态 | 已生效 |
-| 实现引用版本 | draft-2026-06-18-r1; PJ2026-0104010803 唯一投影 draft-2026-06-18-p0-unique-projection |
+| 实现引用版本 | draft-2026-06-18-r1; PJ2026-0104010803 唯一投影 draft-2026-06-18-p0-unique-projection; PJ2026-01050105 Web鉴权 draft-2026-06-18-p0-auth |
 | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
 | 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) |
 | 规格治理索引 | [规格治理](spec-governance.md) |
@@ -57,6 +57,7 @@ API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 RE
 | 同源 API | Cloud Web origin 下的相对 REST/JSON HTTP API path，供浏览器和 HWLAB CLI 使用。 |
 | route policy | 哪些 path 可以通过 Cloud Web 代理、哪些只能作为显式 Cloud API 诊断或内部服务调用的边界规则。 |
 | AuthPrincipal | 后端根据 Web session 或 API key 恢复出的用户主体摘要。 |
 | CanonicalPrincipal | `/auth/session` 和受保护业务 route 共享的最小身份结果，包含 `authMethod`、`identityAuthority`、`sessionKind`、actor 摘要和后端 capability 摘要；它是业务 route 的唯一身份输入。 |
 | 业务标识 | sessionId、turnId、traceId、runId、commandId、caseId 等用户可继续查询的稳定标识；projectId、workspaceId 和 conversationId 只能作为筛选、metadata 或兼容映射字段，不作为前端鉴权 authority。 |
 | 错误语义 | HTTP status、错误码、blocker、failureKind、route 和下一步提示组成的可定位失败表达。 |
 | Session detail | `GET /v1/workbench/sessions/{sessionId}` 这类按稳定 sessionId 或后端认可 opaque session handle 查询当前会话 metadata、消息指针和状态的 RESTful detail resource。 |
@@ -129,6 +130,22 @@ API契约应以 AuthPrincipal 摘要表达 Web session 和 API key 恢复出的
 鉴权主体的真相由用户管理负责。API 响应只输出 actor、authMethod、requiredAuthMethod、role/status、scope 摘要和错误分类，不输出 session token、完整 API key、password hash、Secret value 或可复用凭据。
 `/auth/session` 是 Cloud Web 的最小身份验证端点。浏览器请求只依赖同源 `hwlab_session` cookie transport；前端不得向该端点传入 API key、user-billing token、cookie prefix、localStorage token 或第二套 authority。该端点成功时必须返回 canonical principal，至少包含：
 | 字段 | 语义 | 脱敏边界 |
 | --- | --- | --- |
 | `authenticated` | 当前请求是否已通过认证 | 布尔值 |
 | `authMethod` | 认证 transport 来源，例如 `web-session`、`user-billing-session`、`user-billing-api-key`、`local-bootstrap` | 枚举，不输出 token |
 | `identityAuthority` | 身份事实归属，例如 `hwlab-local`、`user-billing`、`bootstrap-recovery` | 枚举，不输出底层凭据 |
 | `sessionKind` | 调用形态，例如 `browser`、`api-key`、`recovery` | 枚举 |
 | `actor` | 当前用户摘要，至少包含稳定 id、role、status；可包含 username/displayName | 不输出 password hash、session secret、完整邮箱验证 payload |
 | `capabilities` | 后端授权摘要，例如 `web`、`workbench`、`codeAgent`、`billing`、`admin` | 只输出 `available`、`forbidden`、`unlinked`、`unavailable` 或等价短枚举 |
 | `valuesRedacted` | 响应是否遵守脱敏边界 | 必须为 true |
 未登录请求必须返回 401 和结构化 unauthenticated 结果；禁用、撤销或 recovery 能力不足必须返回 403 或业务 blocker，并保留 `authMethod`、`identityAuthority`、`sessionKind` 的可诊断摘要。响应不得输出 cookie、session token、API key secret、完整 user-billing token、provider Secret、DB DSN 或 raw dependency payload。
 业务 route 只能消费认证层产生的 canonical principal 和权限配额的 capability 结果。Usage、Billing、API keys、Workbench、Code Agent 和 Admin route 不得自行调用 token/cookie 抽取函数来决定用户身份；如果需要访问 user-billing、API key 或账单后台，应由后端以 principal 为输入桥接业务服务，并把 `available/forbidden/unlinked/unavailable` 或结构化 blocker 返回给客户端。
 ### 6.3 CLIENT-API-REQ-003 Agent 用户接口
 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -40,6 +40,7 @@ D601 v0.3 当前已具备 app-local 注册、登录、登出、会话检查、
 - 会话与用户状态、角色和禁用状态的一致校验。
 - 邮箱验证、找回密码、多因素认证、账号绑定和登录安全通知的规格边界。
 - Web session、API key principal 和内部服务 principal 对同一用户身份的消费边界。
 - 浏览器同源 `hwlab_session` 到 canonical principal 的唯一解释通道，以及 recovery/bootstrap 身份的显式边界。
 ### 2.3 范围外
@@ -55,6 +56,7 @@ D601 v0.3 当前已具备 app-local 注册、登录、登出、会话检查、
 | app-local 账号 | HWLAB 自身维护的账号体系，不依赖 Keycloak 作为主身份源。 |
 | Web session | 浏览器登录后由服务端签发并可校验的会话状态。 |
 | principal | 内部服务消费的已认证调用主体，包含用户、角色、状态和来源。 |
 | canonical principal | 认证层把 Web session、API key 或受控 recovery 身份解释后产出的最小身份主体，包含 `authMethod`、`identityAuthority`、`sessionKind`、actor 摘要和后端授权摘要。 |
 | 当前用户 | 通过 session 或 API key 校验后得到的用户身份事实。 |
 | 身份恢复 | 用户在忘记密码、邮箱验证或账号安全事件后恢复访问的受控流程。 |
@@ -79,6 +81,7 @@ D601 v0.3 当前已具备 app-local 注册、登录、登出、会话检查、
 | PJ2026-01050102 | 会话状态 | 本规格 6.2 | session 检查、当前用户和禁用状态生效 | 注册登录、平台 Secret | API key、Agent编排、客户端 |
 | PJ2026-01050103 | Profile安全 | 本规格 6.3 | profile、密码修改和安全设置 | 用户身份、客户端账户入口 | 用户自服务、admin 用户管理 |
 | PJ2026-01050104 | 身份恢复 | 本规格 6.4 | 邮箱验证、找回密码和多因素认证边界 | 邮件/通知能力、平台配置 | 用户恢复、运营支持 |
 | PJ2026-01050105 | Web鉴权 | 本规格 6.5 | 浏览器 session transport、canonical principal 和 recovery 身份边界 | 注册登录、会话状态、权限配额 | API契约、Web工作台、业务 API |
 ## 6. 原子需求
@@ -121,3 +124,15 @@ profile 安全设置只拥有账号资料和登录安全事实。余额通知、
 账号会话应定义邮箱验证、找回密码、多因素认证和账号绑定的恢复边界，使用户在安全事件或凭据丢失后有受控恢复路径。
 身份恢复必须通过用户管理状态机更新账号事实，并由平台运维提供邮件、Secret 和运行支撑。未实现的恢复能力不得由临时 admin SQL、直接改库或客户端本地状态替代。
 ### 6.5 USER-ACCT-REQ-005 Web 鉴权唯一通道
 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
 | USER-ACCT-REQ-005 | Web鉴权 | PJ2026-01050105 Web鉴权 | [API契约](PJ2026-010403-api-contract.md)、[客户端](PJ2026-0104-client.md)、[权限配额](PJ2026-010503-access-quota.md) |
 账号会话应把浏览器同源 `hwlab_session` 视为 Web session transport，由后端唯一认证入口解释为 canonical principal。Cloud Web、Workbench、Usage、Billing、Admin 和 Code Agent 等业务面只能消费这个 principal 与后端 capability 摘要，不得在页面、route 或业务 handler 中重新解析 cookie prefix、Bearer、`hws_`、API key secret、user-billing token 或 localStorage authority 来定义用户身份。
 canonical principal 至少应表达 `authenticated`、`authMethod`、`identityAuthority`、`sessionKind`、actor 摘要和脱敏 capability 摘要。`authMethod` 用于说明 transport 来源，例如 Web session、user-billing session、API key 或 local-bootstrap；`identityAuthority` 用于说明身份事实归属，例如 `hwlab-local`、`user-billing` 或 `bootstrap-recovery`；`sessionKind` 用于区分浏览器、API key 和 recovery 身份。local/bootstrap 或 recovery 身份不能静默伪装成完整业务用户，必须在 canonical principal 中显式标记其能力边界和 blocker。
 身份验证和业务授权必须分层：账号会话先证明“当前调用主体是谁”；权限配额、账单后台、Agent编排、Workbench 和 Admin 再判断“该主体能做什么”。billing、usage、API key、Workbench 或 Code Agent 的业务 capability 不得反过来决定 Web 是否已登录。未登录、禁用、撤销或能力不可用必须返回结构化错误或 blocker，不能让前端通过二次登录、API key 输入、cookie prefix 判断或 fallback endpoint 补救身份。
@@ -59,6 +59,7 @@ D601 v0.3 当前已具备 admin role、默认 plan、`code_agent` / `aipod` / `h
 | quota | 用户在周期或资源类型上的可消费额度。 |
 | concurrency | 同一用户或组织可同时占用的资源数量上限。 |
 | RPM | 单位时间内允许发起的请求频率约束。 |
 | capability | 后端基于 canonical principal、role、plan、entitlement 和业务状态产出的短授权摘要，用于告诉客户端某个业务面是 `available`、`forbidden`、`unlinked` 还是 `unavailable`。 |
 ## 4. 系统边界和接口
@@ -94,6 +95,8 @@ D601 v0.3 当前已具备 admin role、默认 plan、`code_agent` / `aipod` / `h
 管理操作必须通过用户管理的角色权限判断，不得由前端路由、临时脚本或业务模块本地列表替代。
 角色权限的输入必须是账号会话产出的 canonical principal 或 API key 对应的后端主体。Cloud Web 页面、业务 route 和 fake-server 测试不得通过 cookie prefix、localStorage、user-billing token 或 API key secret 自行推断 admin/user 身份。
 ### 6.2 USER-AUTHZ-REQ-002 Plan 与 entitlement 模型
 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -123,3 +126,5 @@ plan 模型是用户管理的业务事实。平台运维只负责持久化和配
 权限配额应输出稳定的未授权、未开通、额度不足、并发超限和频率超限错误，使 Web、CLI、HTTP API 和内部模块可以一致处理失败。
 授权错误必须阻止后续资源占用和计费扣减。客户端负责解释和展示错误，不得把错误映射成成功、排队中或未知状态。
 capability 摘要是授权结果的脱敏表达，不是前端自行维护的权限表。`web` capability 表示当前浏览器身份是否成立；`workbench`、`codeAgent`、`billing`、`apiKeys`、`admin` 等 capability 表示对应业务面是否可消费。`billing=unlinked`、`billing=unavailable` 或 `billing=forbidden` 不得让 Web 登录态失效；它只影响账单后台或账务页面的业务状态展示。业务能力不可用时必须返回结构化 blocker，禁止要求前端补 token、输入 API key 或切换到旧鉴权路径。
@@ -93,6 +93,8 @@ D601 v0.3 当前已具备用户 billing summary、admin usage/ledger filter、CS
 用户账单摘要只聚合用户管理事实，不在客户端或 Cloud API 中创建平行余额、quota 或 ledger。
 账单后台是 canonical principal 之后的业务消费面，不是 Web 登录态的来源。浏览器身份是否成立由账号会话和 `/auth/session` 证明；账单后台只能基于后端传入的 principal 查询或返回 billing capability、summary 和 blocker。`billing=unlinked`、`billing=unavailable`、provider 未配置或 user-billing 暂时不可达时，应返回结构化业务状态，不得要求前端补 user-billing token、API key 或 cookie prefix 来重新定义登录。
 ### 6.2 USER-BILL-REQ-002 管理查询与导出
 | 编号 | 短名 | 主责模块 | 关联模块 |