pikasTech-HWLAB/docs/reference/spec-user-access.md

v0.2 用户和权限管理规格

本文是 HWLAB v0.2 用户和权限管理的规格说明。目标是用最少概念支持真实用户使用 code agent session 和管理员分配 device pod 权限，同时避免把用户体系、Kubernetes 租户、设备授权、硬件证据链和审计系统混成一套复杂门禁。

本规格与 spec-device-pod.md 配套：用户和权限规格定义谁可以看见、创建和使用 device pod；device-pod 规格定义 profile authority、REST/job 和硬件执行边界。

登录入口、Keycloak OIDC、Web session、CLI API key 和 AuthPrincipal 归一见 spec-v02-auth.md。本文只定义认证完成后的角色、资源归属、device pod grant 和 code agent owner 授权；正式用户鉴权只有 Web session 与 CLI/API key 两类，除非明确标注为 bootstrap/legacy，不再把本地账号密码登录或 device-pod 系统 key 作为目标登录体验。

实施跟踪见 pikasTech/HWLAB#531，原 docs/plan/v02-multi-user-migration.md 迁移计划全文已迁入该 issue 评论。

在系统中的职责划分

用户和权限管理不是独立微服务，权威实现收敛在 hwlab-cloud-api：它消费 spec-v02-auth.md 产出的 AuthPrincipal，负责角色、device pod grant、用户 API key 和 code agent session owner 校验。hwlab-cloud-web 只提供浏览器 UI 和同源代理；hwlab-device-pod 只执行设备语义；AgentRun v0.1 只消费 cloud-api 传入的 actor/session/device 权限上下文，不成为 HWLAB 用户权限 authority。

Postgres 是该规格的数据持久化边界。Kubernetes namespace、ServiceAccount、Service 直连和 gateway route 都不能替代用户权限模型；普通用户不获得 kubeconfig、内部 Service 直连能力或长期 Secret。

v0.2 本地 bootstrap 管理员账号固定为 admin，默认登录密码固定为 hwlab2026，只作为空库初始化和 legacy fallback。Keycloak 接入后的目标 Web 登录以 OIDC 为准，CLI 以 HWLAB_API_KEY 为准。 运行时仍只通过 hwlab-v02-bootstrap-admin/password-hash SecretRef 注入本地 fallback password hash；Postgres、API 响应、日志、CLI session 和文档不得保存或输出 password hash、session token 原文或 Secret 值。 如果 live Secret 需要重建或旋转，必须保持 /auth/login 这个 legacy/bootstrap 入口可用，但不得把它重新写成目标登录体验。

规格目标

• 只保留两类角色：admin 和 user。
• code agent session 直接归属于创建它的用户；普通用户只能查看、继续和取消自己的 session。
• device pod 由 admin 管理；普通用户只有在被 admin 授权后才能看到和使用对应 device pod。
• device pod 授权不拆分 read、operate 或 capability；授权关系存在即代表该用户拥有该 device pod 的完整使用权限。
• MVP 不新增产品级 audit_events 用户审计表，也不把用户权限依赖到 audit。现有硬件 trace/evidence/audit 字段属于硬件闭环证据，不是多用户权限模型的一部分。
• 强副作用 device-pod job 只额外要求业务 reason；设备互斥由 executor、gateway 和硬件 host 串行化或返回 blocker，不进入用户权限模型。
• 普通用户不获得 Kubernetes 用户、kubeconfig、namespace 管理权或直接访问 device pod Service 的权限；所有用户权限判断在 cloud-api 应用层完成。
• v0.2 权限数据必须与 hwlab-dev/hwlab-prod 运行数据隔离。优先在 hwlab-v02 namespace 内使用独立 Postgres StatefulSet/PVC；若未来显式复用共享 Postgres 实例，也必须使用独立 database 或 schema、独立 Secret 和独立 migration ledger，不得直接复用 hwlab-dev 的 pgdata。

简化边界

模块	不采用的复杂方案	v0.2 规格方案
用户角色	platform_admin、device_admin、developer、viewer	admin、user
用户组	groups、group_members	不引入
项目隔离	projects、project_members	不引入
Code Agent 会话	ownerUserId + projectId + sessionId	owner_user_id + session id
Device Pod 管理	平台管理员和设备管理员分工	admin 统一管理
Device Pod 授权	可按 group/project/user 授权	只按具体 user_id 授权
设备权限粒度	device.view、io.read、io.write、debug.reset 等 capability	授权即全权限
Viewer	单独只读角色	不引入
Audit	独立用户审计表	不引入
Lease	权限和互斥可能混用	只作为设备互斥锁

表结构

v0.2 多用户实现复用 cloud-api 和现有 Postgres runtime store，不新增独立用户管理微服务。推荐新增一个 0002_multi_user_access_v1 数据库迁移，保持现有 0001_cloud_core_skeleton.sql 的硬件 runtime 表不被误用为用户权限表。

users

用户身份和角色 source of truth。

CREATE TABLE IF NOT EXISTS users (
  id TEXT PRIMARY KEY,
  username TEXT NOT NULL UNIQUE,
  display_name TEXT NOT NULL DEFAULT '',
  role TEXT NOT NULL CHECK (role IN ('admin', 'user')),
  status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'disabled')),
  password_hash TEXT,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);

• bootstrap 阶段必须至少有一个 admin。
• password_hash 只用于 v0.2 本地 bootstrap/legacy 账号；OIDC identity 扩展字段、api_keys 表和 API key 规则见 spec-v02-auth.md。接入 OIDC 后仍保留 users.id、role 和授权表稳定，不把外部 IdP subject 直接暴露给业务授权。
• disabled 用户不能创建 session、继续 session 或使用 device pod。

user_sessions

浏览器 server session/cookie 的持久状态。cookie 中只保存不可逆 session token；数据库保存 token hash。

CREATE TABLE IF NOT EXISTS user_sessions (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL REFERENCES users(id),
  session_token_hash TEXT NOT NULL UNIQUE,
  created_at TEXT NOT NULL,
  last_seen_at TEXT NOT NULL,
  expires_at TEXT NOT NULL,
  revoked_at TEXT
);

• /auth/session、OIDC callback、API key 认证和 /auth/logout 的最终 authority 是 cloud-api；本地 /auth/login 只作为 bootstrap/legacy fallback。/v1/auth/session、/v1/users/me、/v1/access/status 和 /v1/setup/status 只作为同一 authority 的 REST 状态或兼容入口。cloud-web 可以保留同名浏览器路由，但只能作为静态 UI 或代理层。
• logout 是设置 revoked_at，不是仅删除浏览器本地状态。

agent_sessions

复用现有 agent_sessions 作为 code agent session 归属记录，不再新增同义的 code_agent_sessions 表。v0.2 迁移应在现有表上增加 owner 和 chat/session 绑定字段：

ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS owner_user_id TEXT REFERENCES users(id);
ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS conversation_id TEXT;
ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS thread_id TEXT;
ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS last_trace_id TEXT;
ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS session_json TEXT NOT NULL DEFAULT '{}';
ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS updated_at TEXT;
CREATE INDEX IF NOT EXISTS idx_agent_sessions_owner ON agent_sessions(owner_user_id);
CREATE INDEX IF NOT EXISTS idx_agent_sessions_conversation ON agent_sessions(conversation_id);

• 新建 code agent session 必须写入 owner_user_id。
• 历史 ownerless session 在迁移时可以一次性归属 bootstrap admin 或直接标记为 expired；迁移完成后不再允许 ownerless 活跃 session。

device_pods

设备能力单元的管理表；正式 profile authority 和执行语义以 spec-device-pod.md 为准。profile 定义 device pod，因此 profile 必须由 admin 通过 cloud-api 管理，不能由 code agent 本地 .device-pod/ 文件决定。

CREATE TABLE IF NOT EXISTS device_pods (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL DEFAULT '',
  status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'disabled')),
  profile_json TEXT NOT NULL DEFAULT '{}',
  profile_hash TEXT NOT NULL DEFAULT '',
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);

profile_json 中的 gateway route、host workspace、probe UID、串口端口和 host CLI 都是服务端权威字段；普通用户响应只能看到脱敏 profile 摘要和 profile_hash。

device_pod_grants

普通用户对 device pod 的授权关系；存在即全权限。

CREATE TABLE IF NOT EXISTS device_pod_grants (
  device_pod_id TEXT NOT NULL REFERENCES device_pods(id) ON DELETE CASCADE,
  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  created_by_admin_id TEXT NOT NULL REFERENCES users(id),
  created_at TEXT NOT NULL,
  PRIMARY KEY (device_pod_id, user_id)
);

• 不包含 capability、scope、expires_at。
• 撤销授权就是删除对应行；撤销后该用户通过普通 session/cookie 不再看到或使用该 device pod。
• AgentRun runner 不使用跨用户共享的 device-pod 系统 key。runner 内 hwpod 只能使用映射到 Code Agent session owner 的 HWLAB_API_KEY，并按同一用户的 device_pod_grants 授权。

权限矩阵

操作	admin	user
管理用户	可以	不可以
创建自己的 code agent session	可以	可以
查看、继续、取消自己的 code agent session	可以	可以
查看、取消别人的 code agent session	可以	不可以
创建、更新、删除 device pod	可以	不可以
给用户授权或撤销 device pod	可以	不可以
查看 device pod	可以查看全部	只能查看被授权的 device pod
使用 device pod 的 workspace/debug/io 能力	可以使用全部	只能使用被授权的 device pod
提交强副作用 device-pod job	必须填写 reason	被授权后必须填写 reason

请求链路

cloud-api 每个用户态请求都按同一顺序处理：

authenticate -> actor -> authorize(actor, action, resource) -> reason check for mutating device jobs -> execute

登录、API key 和 session 恢复

browser
-> Keycloak OIDC login/callback
-> cloud-api auth controller
-> users issuer+sub/status/role mapping
-> user_sessions insert token hash
-> Set-Cookie httpOnly sameSite
-> browser

cli
-> Authorization: Bearer hwl_live_...
-> cloud-api api_keys lookup
-> users status/role check
-> AuthPrincipal(authMethod='api-key')

登录、Keycloak issuer、CLI API key 和 24 小时 Web session 规则见 spec-v02-auth.md。资源授权模块只消费已经恢复出的 actor/AuthPrincipal。/auth/session 使用 cookie 查 user_sessions，再查 users 得到 actor；API key 认证直接从 api_keys -> users 得到同一 actor。/auth/logout 标记 user_sessions.revoked_at。Keycloak access token、refresh token、realm role 和 device-pod 内部系统 key 都不能绕过这里的 actor 恢复与资源授权。

admin 创建用户

browser admin UI
-> cloud-web proxy
-> cloud-api POST /v1/admin/users
-> authenticate admin
-> insert users(role='user')
-> return redacted user record

普通用户请求该接口必须返回 403。响应不得返回 password_hash、session token 或 Secret 值。

admin 授权 device pod

browser admin UI
-> cloud-api POST /v1/admin/device-pod-grants
-> authenticate admin
-> validate users.status='active'
-> validate device_pods.status='active'
-> upsert device_pod_grants(device_pod_id, user_id)
-> return grant summary

撤销授权走 DELETE /v1/admin/device-pod-grants/{devicePodId}/{userId}，删除后该用户通过普通 session/cookie 不再能看到或使用该 device pod。

用户列出 device pod

browser or code agent tool
-> cloud-api GET /v1/device-pods
-> authenticate actor
-> if admin: list all active device_pods
-> if user: inner join device_pod_grants by actor.id
-> return visible device pod summaries

未授权普通用户看到空列表或对单个未授权 device pod 收到 403；不得回退到 fake default device pod。

用户创建或继续 code agent session

browser
-> cloud-api POST /v1/agent/chat
-> authenticate actor
-> find or create agent_sessions(owner_user_id=actor.id, conversation_id)
-> run code agent turn
-> persist last_trace_id/thread_id/session_json
-> return 202 trace/result polling pointer

GET /v1/agent/chat/result/{traceId}、GET /v1/agent/chat/trace/{traceId} 和 POST /v1/agent/chat/cancel 必须通过 agent_sessions.owner_user_id 校验 owner；admin 可跨用户查看和取消。

code agent 使用 device pod

code agent turn
-> cloud-api device operation route
-> authenticate actor from owning session or user API key in runner
-> verify agent_sessions.owner_user_id == actor.id
-> authorize device_pod_grants/admin
-> require reason for mutating operations
-> cloud-api -> hwlab-device-pod internal Service
-> gateway/device-host-cli/hardware path

code agent prompt、runner 或 worker 不得直接绕过 cloud-api 调用 device pod Service。device pod 服务只信任来自 cloud-api 的内部调用，不做最终用户权限判断。

内部架构

hwlab-cloud-api 内部应按 auth/session/API key、authorization、agent session owner、device-pod grant 和 admin API 模块分层。所有模块共享同一 Postgres runtime store 和 migration ledger，避免拆出早期 hwlab-user-api 造成跨服务一致性成本。

user_sessions 存浏览器 session token hash；api_keys 存映射到用户的 CLI/runner API key；agent_sessions.owner_user_id 绑定 Code Agent session；device_pods 存 profile authority；device_pod_grants 表示普通用户对 device pod 的完整使用权。不得再引入对所有正式 device pod 授权的共享用户 key；HWLAB_DEVICE_POD_API_KEY 如仍存在，只能作为 cloud-api 到 device-pod 的内部服务凭据。

API 接口说明

接口	说明
GET /auth/oidc/login、GET /auth/oidc/callback	Web 登录入口；按 spec-v02-auth.md 接入 Keycloak 并写入 24 小时 user_sessions token hash。
POST /auth/login	本地账号密码 bootstrap/legacy fallback；不作为目标 Web/CLI 登录体验。
GET /auth/session	从 cookie 恢复 actor、role 和 session 状态；API key actor 摘要见 /v1/users/me。
GET /v1/auth/session、GET /v1/users/me、GET /v1/access/status、GET /v1/setup/status	REST 状态和兼容入口；不得读取或返回 password hash、session token 原文或 Secret 值。
GET/POST /v1/api-keys...	用户 API key 管理入口；CLI HWLAB_API_KEY 规则见 spec-v02-auth.md。
POST /v1/setup/first-admin	仅当 users 表为空时创建第一个 admin 并建立 session；可选 devicePod 或 devicePods[] 一次性种下首批服务端权威 profile 并授权给首个 admin；一旦已有用户必须返回 409 setup_already_completed。该入口不读取 Kubernetes Secret，不替代正常 admin API。
POST /auth/logout	设置 revoked_at，撤销当前 browser session。
POST /v1/admin/users	admin 创建用户，响应不得返回 password_hash 或 token。
POST /v1/admin/device-pods、PUT /v1/admin/device-pods/{devicePodId}	admin 管理 device pod profile authority。
POST /v1/admin/device-pod-grants、DELETE /v1/admin/device-pod-grants/{devicePodId}/{userId}	admin 授权或撤销普通用户使用 device pod。
GET /v1/device-pods 和 device-pod 操作 API	按 actor role 和 grant 过滤可见/可用 device pod。
POST /v1/agent/chat 及 result/trace/cancel	必须校验 agent_sessions.owner_user_id；admin 可跨用户查看和取消。

POST /v1/setup/first-admin 的 device-pod 初始化只用于空库首次进入系统，不能作为长期 profile 管理入口。每个 seed 必须包含 devicePodId 和 object profile；cloud-api 会写入 device_pods.profile_json/profile_hash 并创建 device_pod_grants(device_pod_id, first_admin_user_id)。响应只能返回脱敏 profile、profileHash 和 grant summary，不得返回 gatewaySessionId、hostWorkspaceRoot、password 或 session token 原文。

微服务设计

v0.2 不新增独立用户管理微服务。Keycloak 是独立身份提供方，不是 HWLAB 应用层授权服务；用户映射、session/API key 消费、device pod grant 和 code agent owner 校验全部放在 hwlab-cloud-api 内，理由是：

• 当前权限模型只有 admin/user、session owner 和 device grant 三类判断，拆服务会增加网络、部署、Secret、迁移和一致性成本。
• cloud-api 已经是 /v1/agent/*、/v1/device-pods/* 和 runtime store 的统一入口，最适合做应用层授权收口。
• 后续若出现组织、计费、批量用户导入或跨产品用户中心，再把 cloud-api 内的 user/auth 模块抽成 hwlab-user-api；抽服务前接口和表结构仍以本文和 spec-v02-auth.md 为准。

各服务职责如下：

服务	v0.2 职责
hwlab-cloud-web	Keycloak 登录入口、普通用户工作台、API key 管理入口和 admin 用户/授权 UI；浏览器 /auth/* 可由 cloud-web 代理到 cloud-api。
hwlab-cloud-api	用户映射、Web session/API key 消费、授权、device grant、code agent owner 校验和对 device pod 的受控转发。
AgentRun v0.1 runner	执行 code agent session；接收 cloud-api 提供的 owner/session/device 上下文方便观测，但不作为最终权限 authority。
hwlab-device-pod	暴露设备语义 API；不保存用户权限，不直接面向浏览器或普通用户 session Pod。
hwlab-edge-proxy	公网/FRP 入口和 HTTP 转发；不做业务权限，只转发 cookie/header，不注入伪 actor。
Postgres	v0.2 用户、session、授权、device pod 和既有 runtime durable state。

Kubernetes 落点

Kubernetes 只做运行时隔离和资源兜底，不承载 HWLAB 用户权限模型：

• v0.2 使用 hwlab-v02 namespace，不按用户创建 namespace。
• 普通用户不直接持有 Kubernetes RBAC、ServiceAccount token 或 kubeconfig。
• hwlab-v02 优先拥有独立 Postgres StatefulSet/PVC，例如 data-hwlab-v02-postgres-0；不得把 hwlab-dev/data-hwlab-g14-postgres-0 当作 v0.2 权限数据源。
• code agent worker、session Pod/PVC/Job 必须带稳定 label，例如 hwlab.pikastech.local/owner-user-id、hwlab.pikastech.local/session-id。
• device pod 工作负载必须带 hwlab.pikastech.local/device-pod-id label，并通过 Service 暴露稳定内部地址。
• code agent 到 device pod 的访问应收敛到 code agent -> cloud-api -> device-pod，避免普通 session Pod 直接调用 device pod Service 绕过应用层授权。
• Keycloak 按 spec-v02-auth.md 作为独立 keycloak namespace 的外部身份源接入；Kubernetes 租户隔离第一轮仍不引入 Dex、oauth2-proxy、OpenFGA、Capsule、vCluster、Kyverno 或 service mesh。

当前态、差距和迁移步骤已迁入 pikasTech/HWLAB#531 评论。

测试规格

T1

阅读 docs/reference/spec-user-access.md 和 docs/reference/spec-v02-auth.md，然后用 Web session 或 HWLAB_API_KEY 访问 /v1/users/me，确认响应包含 actor、role 和 active auth method，不包含 password hash、session token 原文、完整 API key 或 Secret 值。空库 bootstrap fallback 可额外验证 /auth/login，但不得把它作为目标登录体验。

T2

阅读 docs/reference/spec-user-access.md，然后用 cli 手动测试以下内容：用 admin 创建普通用户和 device pod grant，再用普通用户列出 /v1/device-pods，确认只能看到被授权 device pod；撤销授权后同一用户不能再看到或使用该 device pod。

T3

阅读 docs/reference/spec-user-access.md，然后用 cli 手动测试以下内容：普通用户创建 Code Agent session 后，只能读取、继续和取消自己的 trace/result；另一个普通用户访问该 session 必须失败，admin 可以跨用户查看或取消。

规格的实现情况

规格项	状态	说明
admin/user 两角色模型	部分实现	cloud-api 已实现 /auth/*、bootstrap admin、admin/user 创建和 admin-only 路由。
users、user_sessions、grant 和 job 表	部分实现	0001 schema 和 access-control bootstrap 覆盖 users、sessions、device_pods、grants 和 jobs；Device Pod 强副作用 job 已接入 reason 校验，真实硬件执行仍依赖 gateway/device-host-cli 在线。
Code Agent owner 绑定	已实现	已在 agent_sessions 写入 owner_user_id、conversation/thread/trace 和脱敏 session evidence；trace/result cache 也按 owner/admin 限制访问。
device pod 授权模型	部分实现	cloud-api 已实现 admin profile/grant、普通用户可见性和 job 持久化；无在线 gateway/device-host-cli 时返回 blocker。
不用 Kubernetes 表达用户权限	已实现/持续约束	规格明确禁止普通用户持有 kubeconfig 或直连 Service 权限。