docs: remove legacy auth residual gates

2026-06-05 14:59:11 +08:00
parent 40b518be80
commit 5c87936c7f
8 changed files with 11 additions and 16 deletions
@@ -14,9 +14,9 @@

 Postgres 是用户、session、业务对象和迁移 ledger 的持久化边界；OpenFGA 是细粒度授权关系与授权判定边界。Kubernetes namespace、ServiceAccount、Service 直连和 gateway route 都不能替代用户权限模型；普通用户不获得 kubeconfig、内部 Service 直连能力、OpenFGA token 或长期 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 入口可用，但不得把它重新写成目标登录体验。
+`v0.2` 本地 bootstrap 管理员账号固定为 `admin`，默认登录密码固定为 `hwlab2026`，只用于空库初始化。Keycloak 接入后的目标 Web 登录以 OIDC 为准，CLI 以 `HWLAB_API_KEY` 为准。
+运行时仍只通过 `hwlab-v02-bootstrap-admin/password-hash` SecretRef 注入本地 bootstrap password hash；Postgres、API 响应、日志、CLI session 和文档不得保存或输出 password hash、session token 原文或 Secret 值。
+如果 live Secret 需要重建或旋转，必须保持目标 OIDC/Web session 与 API key 登录链路可用。

 ## 规格目标

@@ -67,7 +67,7 @@ CREATE TABLE IF NOT EXISTS users (
 ```

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

 ### `user_sessions`
@@ -86,7 +86,7 @@ CREATE TABLE IF NOT EXISTS user_sessions (
 );
 ```

- `/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 或代理层。
+- `/auth/session`、OIDC callback、API key 认证和 `/auth/logout` 的最终 authority 是 cloud-api。`/v1/auth/session`、`/v1/users/me`、`/v1/access/status` 和 `/v1/setup/status` 只作为同一 authority 的 REST 状态入口。cloud-web 可以保留同名浏览器路由，但只能作为静态 UI 或代理层。
 - logout 是设置 `revoked_at`，不是仅删除浏览器本地状态。

 ### `agent_sessions`
@@ -250,7 +250,6 @@ code agent prompt、runner 或 worker 不得直接绕过 cloud-api 调用 device
 | 接口 | 说明 |
 | --- | --- |
 | `GET /auth/oidc/login`、`GET /auth/oidc/callback` | Web 登录入口；按 [spec-v02-auth.md](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](spec-v02-auth.md)。 |
@@ -233,7 +233,6 @@ API key 行为：
 | `GET /auth/oidc/callback` | 校验 code、issuer、nonce 和 state，映射用户，发行 24 小时 Web session。 |
 | `GET /auth/session` | 从 Web cookie 恢复 actor；API key 用户摘要使用 `/v1/users/me`。 |
 | `POST /auth/logout` | revoke 当前 Web session 并清 cookie。 |
-| `POST /auth/login` | 本地账号密码 legacy/bootstrap fallback；目标 Web/CLI 登录不依赖该入口。 |
 | `GET /v1/users/me` | 返回当前 `AuthPrincipal` 的脱敏摘要。 |
 | `GET /v1/api-keys` | 列出当前用户 API key metadata；目标状态不返回完整 key。 |
 | `GET /v1/api-keys/default` | 返回或创建默认 API key；目标状态只在新建时返回一次完整 key。 |
@@ -61,7 +61,7 @@ Code Agent session 是显式资源，不再由普通 `client agent send`、Workb
 - `tools/hwlab-cli/bin/hwlab-cli.ts` 是唯一可执行入口，使用 Bun 运行。
 - `tools/src/hwlab-cli-lib.ts` 承载参数解析、cookie jar、HTTP 请求、轮询和 JSON 输出。
 - `tools/hwlab-cli/bin/hwlab-cli.mjs` 只允许作为兼容 shim 调用 Bun TS 入口；新功能不得继续写入 `.mjs` 旧库。
- 目标认证状态来自 `HWLAB_API_KEY` 环境变量；CLI 不默认把用户 API key 写入 `.state/hwlab-cli/session.json`。现有 cookie session 文件只作为 legacy 兼容，状态只保存 base URL、cookie、actor 摘要和过期时间，不保存 password、完整 API key 或 Secret 原文。
+- 目标认证状态来自 `HWLAB_API_KEY` 环境变量；CLI 不默认把用户 API key 写入 `.state/hwlab-cli/session.json`。本地状态只保存 base URL、cookie、actor 摘要和过期时间，不保存 password、完整 API key 或 Secret 原文。
 - 所有 `client` 子命令都是短连接；长耗时 Code Agent 只提交 async request 并短轮询 result/trace，单次命令必须有 timeout 和中间状态输出。

 ## API 接口说明
@@ -70,8 +70,7 @@ Code Agent session 是显式资源，不再由普通 `client agent send`、Workb
 | --- | --- | --- |
 | `hwlab-cli client auth status` | 本地 env + `GET /v1/users/me` | 显示 runtime endpoint、是否检测到 `HWLAB_API_KEY`、key prefix 和当前 actor 摘要；不得输出完整 key。 |
 | `hwlab-cli client auth whoami` | `GET /v1/users/me` | 使用 `HWLAB_API_KEY` 恢复当前 actor/AuthPrincipal；纯 CLI，无浏览器跳转。 |
-| `hwlab-cli client auth login` | `POST /auth/login` | legacy/bootstrap fallback；不作为目标一等 CLI 登录体验。 |
-| `hwlab-cli client auth session` | `GET /auth/session` | legacy cookie session 恢复或 Web session debug。 |
+| `hwlab-cli client auth session` | `GET /auth/session` | Web session debug。 |
 | `hwlab-cli client auth profiles` | 本地状态读取 | 列出同一 base URL 下的本地 profile state，用于账号切换可见性。 |
 | `hwlab-cli client auth logout` | `POST /auth/logout` | 撤销 server session 并清理本地 cookie。 |
 | `hwlab-cli client access summary` | `GET /v1/admin/access/summary` | Admin Access 总览，显示 OpenFGA mode/readiness/store/model、用户/tool/device-pod 数量和 mismatch 摘要。 |
@@ -42,7 +42,6 @@
 | `POST /v1/rpc/{method}` | REST 到 JSON-RPC 的桥接入口。 |
 | `GET /v1/device-pods...` | 经 cloud-api 鉴权后读取服务端 profile/OpenFGA relation/job authority；probe GET 会创建只读 device job 并经 `hwlab-device-pod` executor/gateway 执行或返回同源 blocker，不会回退到 fake device pod 数据。 |
 | `GET /auth/oidc/login`、`GET /auth/oidc/callback`、`GET /auth/session`、`POST /auth/logout` | Keycloak OIDC、Web session 24 小时轮换和 logout 入口，最终规格见 [spec-v02-auth.md](spec-v02-auth.md)。 |
-| `POST /auth/login` | 本地账号密码 bootstrap/legacy fallback；目标 Web/CLI 登录不依赖该入口。 |
 | `GET /v1/auth/session`、`GET /v1/users/me`、`GET /v1/access/status`、`GET /v1/setup/status` | v0.2 用户/session/setup 的 REST 状态和兼容入口；响应不得暴露 password hash、session token 原文或 Secret 值。 |
 | `GET/POST /v1/api-keys...` | 用户 API key 管理入口；CLI 和 AgentRun runner 内 `hwpod` 都使用 `HWLAB_API_KEY`，映射到用户后再按权限表授权。 |
 | `POST /v1/admin/users`、`POST/PUT /v1/admin/device-pods` | `admin` 管理用户和 device pod profile 的入口。 |
@@ -7,7 +7,7 @@
 - 向用户提供 Cloud Workbench、Code Agent 对话、live status、device-pod 右侧面板、trace 展示和帮助内容。
 - 只消费 `hwlab-cloud-api`，不直接访问 Postgres、gateway、device-pod Service、FRP、Kubernetes 或 provider Secret。
 - 为浏览器提供同源代理，避免前端直接跨域调用内部 ClusterIP。
- Web 登录按 [spec-v02-auth.md](spec-v02-auth.md) 走 Keycloak OIDC；未登录用户进入 Keycloak 登录/注册，callback 后由 cloud-api 发行 24 小时 `hwlab_session`。本地账号密码表单和自动 admin 登录只允许作为 legacy/bootstrap fallback，不是目标体验。
+- Web 登录按 [spec-v02-auth.md](spec-v02-auth.md) 走 Keycloak OIDC；未登录用户进入 Keycloak 登录/注册，callback 后由 cloud-api 发行 24 小时 `hwlab_session`。
 - Cloud Web 提供 API key 管理入口，让用户查看默认 API key、创建新 key、revoke 或 regenerate；浏览器日常请求仍使用 Web session，不要求用户手动输入 API key。
 - Cloud Web 提供 admin-only Access 页面，让管理员按用户管理 role/status、device pod relation、Code Agent session 可见性和工具 capability；页面只调用 cloud-api `/v1/admin/access*` 同源 API，不直接访问 OpenFGA、Postgres、Kubernetes 或 Keycloak admin API。
 - Cloud Web 与 `hwlab-cli client` 必须共享同一组非视觉业务 API。浏览器遇到的 Code Agent continuation、trace/result、device-pod list/status 和 device-pod job 问题，必须能通过 `hwlab-cli client` 走同一 `19666` Cloud Web path 复现；不能让 CLI 长期绕到 `19667` Cloud API 后把 Web 路径缺口误判为业务已通过。
@@ -6,7 +6,7 @@

 - 向 `hwlab-cloud-api` 注册 gateway session、resource 和 capability。
 - 通过主动轮询 `/v1/gateway/poll` 获取 cloud-api 分发的 `hardware.invoke.shell` 请求，并把结果回传 `/v1/gateway/result`。
- 只做 transport 和 bounded command execution，不理解用户权限、device-pod grant 或业务授权。
+- 只做 transport 和 bounded command execution，不理解用户权限或业务授权。
 - transport 稳定性是 P0 基础能力：大 stdout、长单行 stdout、stderr flood、命令 timeout、gateway 超容量并发和结果回传失败都必须返回结构化 JSON 状态；禁止让 poll/result、Cloud API request、Code Agent commandExecution 或 `hwlab-cli` 调用进入无 stdout、无 trace、无 terminal status 的黑洞。

 ## 内部架构
@@ -55,6 +55,5 @@
 | bounded shell execution | 已实现 | 受 env 开关、timeout 和 output limit 约束。 |
 | gateway 压测闭环 | 已实现 | `hwlab-cli client gateway pressure` 覆盖大输出、timeout 和并发背压，不依赖 shell pipe 裁剪。 |
 | v02 environment 标记 | 已实现 | response meta、audit 和 evidence 从请求 meta 或 gateway env 派生，不把 v02 dispatch 证据落回 `dev`。 |
-| device-pod grant/API key | 不在本服务 | 由 cloud-api/device-pod 负责。 |
 | 生产级 gateway 多租户隔离 | 未完全实现 | 当前是 demo/transport skeleton。 |

@@ -162,7 +162,7 @@ Cloud Web 新增 ActivityRail 顶层入口 `Access`，只对具备 access manage

 交互规则：

- 初始加载先调用 `GET /v1/admin/access/summary` 和用户列表；OpenFGA degraded 时页面必须显示 blocker，不允许静默按旧 grant 表展示为通过。
+- 初始加载先调用 `GET /v1/admin/access/summary` 和用户列表；OpenFGA degraded 时页面必须显示 blocker。
 - 修改权限时先在本地形成 pending diff；保存后逐项调用对应 PATCH/PUT/DELETE API，并刷新 effective matrix。
 - 页面不暴露 OpenFGA tuple 原文作为主要操作面；需要排障时只在详情中显示 redacted object/relation。
 - 普通用户或未登录用户访问 Access route 时显示授权 blocker 或跳登录，不渲染空管理表。