pikasTech-HWLAB/docs/reference/spec-v02-openfga-authorization.md

v0.2 OpenFGA 授权与 Admin Access 管理规格

本文是 HWLAB v0.2 细粒度资源授权、OpenFGA 接入、管理员 Access WebUI 和同路径 CLI 的长期规格。Keycloak 只回答“用户是谁”；OpenFGA 回答“该用户能不能对该对象做该动作”；hwlab-cloud-api 是唯一应用层 enforcement point 和授权写入口。

当前 HWPOD 快速闭环阶段只管理用户、Code Agent session 和工具能力，不为旧设备对象保留 OpenFGA type、relation、API 或 CLI。

在系统中的职责划分

组件	职责
Keycloak	身份认证、注册、OIDC issuer；不直接授予 HWLAB 功能权限。
hwlab-cloud-api	AuthPrincipal 恢复、OpenFGA store/model bootstrap、授权 check、授权写 API、enforce 策略、AgentRun transient env 过滤和审计摘要。
OpenFGA	hwlab-v02 namespace 内部 PDP 和 relationship tuple store；只接受 cloud-api 调用，不向浏览器、CLI、AgentRun runner 或公网暴露。
HWLAB v0.2 Postgres	业务对象、用户、session、API key、access_tuples 摘要、OpenFGA store/model 指针和迁移 ledger 的 durable source。
hwlab-cloud-web	Admin Access 页面和同源 API proxy；不直接调用 OpenFGA。
hwlab-cli client	Web 等价非视觉授权管理入口；通过 19666 Cloud Web 同源 path 调 cloud-api，不直连 OpenFGA。
AgentRun v0.1 runner	只消费 cloud-api 根据用户权限注入的短期工具环境；不持有跨用户共享 key、GitHub token 或 UniDesk SSH token。

授权模型

对象命名必须稳定、可从业务 ID 直接推导，并在日志/trace 中可脱敏展示：

对象	例子	说明
用户	user:usr_123	HWLAB users.id，不是 Keycloak sub。
系统	system:hwlab	平台级 admin、access 管理和全局工具授权。
Code Agent session	agent_session:ags_123	会话 owner/collaborator/viewer 判定。
工具	tool:hwpod、tool:unidesk_ssh、tool:github_pr、tool:trans_cmd	AgentRun runner 可注入或可调用的功能能力。

目标关系模型：

model
  schema 1.1

type user

type system
  relations
    define admin: [user]
    define access_manager: admin
    define can_manage_users: admin
    define can_manage_tools: admin

type agent_session
  relations
    define owner: [user]
    define viewer: [user] or owner or admin from system
    define operator: [user] or owner or admin from system
    define admin: admin from system

type tool
  relations
    define can_use: [user] or admin from system
    define admin: admin from system

实现可以在第一版用等价模型名称和 relation 名称，但必须保持以下能力语义：

功能	Check
管理用户和权限	user:<id> access_manager system:hwlab 或 admin system:hwlab
查看自己的 Code Agent session	viewer agent_session:<id>
继续/取消 Code Agent session	operator agent_session:<id>
使用 HWPOD 工具	can_use tool:hwpod
注入 UniDesk SSH 透传能力	can_use tool:unidesk_ssh
允许 trans 透传 cmd	can_use tool:trans_cmd，且仍受 UniDesk route/operation 边界限制
GitHub PR/issue 写操作工具	can_use tool:github_pr 或更细工具对象

admin/user 仍保留为 UX 和 bootstrap 角色，但 runtime 授权必须逐步迁移到 OpenFGA check。users.role='admin' 必须镜像为 system:hwlab#admin@user:<id> tuple；降级 admin 时必须同步删除 tuple。Keycloak realm role、group、claim 不能直接变成 OpenFGA tuple，除非由 HWLAB admin API 明确写入。

Cloud API 授权策略

hwlab-cloud-api 是唯一 policy enforcement point。所有用户态请求按以下顺序处理：

authenticate -> AuthPrincipal -> load domain object -> openfga check -> execute

enforce 是唯一正式运行模式。OpenFGA 不可达、store/model 未就绪或 check 超时时，高风险写操作 fail closed；低风险只读可以返回 degraded blocker，不得静默放行。

tuple 写入必须由 cloud-api admin API 统一完成，并和 Postgres domain state 保持事务级或可恢复一致：

• 用户创建、禁用、角色提升/降级时同步写 users 和 system:hwlab tuples。
• Code Agent session 创建时写 agent_session:<id>#owner@user:<owner>；取消/归档不删除 owner tuple，便于 trace 回放。
• API key scopes_json 只能作为用户权限的收窄条件，不能授予超过 OpenFGA 的能力。

Admin Access API

Cloud Web 和 CLI 只能通过 cloud-api 的 admin API 管理授权。第一版 API surface：

接口	说明
GET /v1/admin/access/summary	返回 mode、OpenFGA readiness、storeId/modelId、user/tool 数量和最近 mismatch 摘要。
GET /v1/admin/access/users	列出用户、role/status、Keycloak 绑定摘要、API key 数量和 effective capability 摘要。
GET /v1/admin/access/users/{userId}	返回单个用户的 agent session 和 tool 权限矩阵。
PATCH /v1/admin/access/users/{userId}	更新用户 role/status，并同步 OpenFGA admin tuple。
PUT /v1/admin/access/users/{userId}/tools/{toolId}/can-use	授予工具能力，例如 hwpod、unidesk_ssh、github_pr、trans_cmd。
DELETE /v1/admin/access/users/{userId}/tools/{toolId}/can-use	撤销工具能力。
POST /v1/admin/access/check	管理员调试单次 authorization check；响应必须标明 actor/object/relation/mode，但不得泄漏 token。

所有 write API 必须要求当前 actor 具备 access_manager system:hwlab 或 admin tuple；普通 user 不可调用。响应必须包含结构化 authorization 字段：mode、allowed、decisionSource、storeId、modelId、relation、object 和 redacted actor。

Admin Access WebUI

Cloud Web 的 Access 页面只管理用户 role/status、Code Agent session 可见性和工具 capability。页面不暴露 OpenFGA tuple 原文作为主要操作面；需要排障时只在详情中显示 redacted object/relation。

同路径 CLI

hwlab-cli client 必须提供与 WebUI 同一 API surface 的非视觉入口，默认由 runtime namespace/lane 解析到 19666 Cloud Web origin：

CLI	Web/API 等价
client access summary	GET /v1/admin/access/summary
client access users list	GET /v1/admin/access/users
client access users inspect USER	GET /v1/admin/access/users/{userId}
`client access users set-role USER --role admin	user`
client access tools grant USER TOOL	PUT /v1/admin/access/users/{userId}/tools/{toolId}/can-use
client access tools revoke USER TOOL	DELETE /v1/admin/access/users/{userId}/tools/{toolId}/can-use
client access check --user USER --relation REL --object OBJECT	POST /v1/admin/access/check

CLI 输出必须是 JSON，包含 runtimeEndpoint、HTTP route、actor 摘要、mode、decision 和变更后的 effective matrix 摘要。它不能直接调用 OpenFGA API，不能手动传 OpenFGA token，不能把 --base-url 19667 作为 WebUI 等价验收路径。

AgentRun 工具能力边界

Cloud API 在创建 AgentRun command/runner 时必须按 OpenFGA 决策装配 transient env 和工具说明：

• 用户没有 can_use tool:hwpod 时，不注入 HWLAB_API_KEY 给 hwpod，也不在 prompt/tools 中声明 HWPOD 操作可用。
• 用户没有 can_use tool:unidesk_ssh 时，不注入 UniDesk SSH client token、workspace route 或相关 alias。
• tool:trans_cmd 只代表允许通过受控 UniDesk route 调用透传命令；它不绕过 UniDesk CLI 的 route/operation 安全边界。
• GitHub issue/PR 写入能力必须单独由工具对象授权；拥有 Code Agent session 不等于拥有 GitHub 写权限。

测试规格

T1

阅读 docs/reference/spec-v02-openfga-authorization.md，然后访问 GET /health/live 和 GET /v1/admin/access/summary，确认响应显示 openfga.mode、readiness、storeId/modelId 摘要和 degraded reason；响应不得包含 OpenFGA token、Postgres URL 或 Secret 值。

T2

阅读 docs/reference/spec-v02-openfga-authorization.md，然后撤销普通用户的 tool:hwpod 或 tool:unidesk_ssh，创建新的 Code Agent session 并检查 trace/runner env 摘要，确认对应工具 alias/env 未注入；尝试调用时返回结构化 authorization blocker。

T3

阅读 docs/reference/spec-v02-openfga-authorization.md，然后从浏览器打开 Access 页面，确认只有 admin/access manager 可见 ActivityRail 入口；普通用户访问 route 显示授权 blocker。

T4

阅读 docs/reference/spec-v02-openfga-authorization.md，然后在 runtime endpoint locked 环境运行 hwlab-cli client access summary/users/check/grant/revoke，确认全部走 Cloud Web 同源 19666 path，输出 JSON、route、actor、mode、decision 和 effective matrix；不手动传 OpenFGA URL/token，不直连 19667 作为最终 Web 等价验收。

规格的实现情况

规格项	状态	说明
OpenFGA 作为 v0.2 内部授权服务	已实现/持续约束	v0.2 runtime 以 enforce 模式运行，summary 暴露 redacted store/model 和 readiness；OpenFGA 不向公网、浏览器或 CLI 暴露。
Cloud API OpenFGA client/bootstrap/check/write	已实现	Admin Access API 可 check/write tuple，响应包含 structured decision 和 redacted OpenFGA 状态。
session / tool 授权	核心已实现/持续扩展	Code Agent session 和 tool capability 是当前授权来源。
同路径 CLI	已实现	client access ... 走 Cloud Web 同源 path，覆盖 summary、users、check 和 tool grant/revoke。