From 5c87936c7f020bdbe809d739cfdb5800c0d87488 Mon Sep 17 00:00:00 2001 From: Codex Agent Date: Fri, 5 Jun 2026 14:59:11 +0800 Subject: [PATCH] docs: remove legacy auth residual gates --- docs/reference/spec-user-access.md | 11 +++++------ docs/reference/spec-v02-auth.md | 1 - docs/reference/spec-v02-hwlab-cli.md | 5 ++--- docs/reference/spec-v02-hwlab-cloud-api.md | 1 - docs/reference/spec-v02-hwlab-cloud-web.md | 2 +- docs/reference/spec-v02-hwlab-gateway.md | 3 +-- docs/reference/spec-v02-openfga-authorization.md | 2 +- internal/cloud/code-agent-session-registry.test.ts | 2 +- 8 files changed, 11 insertions(+), 16 deletions(-) diff --git a/docs/reference/spec-user-access.md b/docs/reference/spec-user-access.md index b4356d73..0e9e3773 100644 --- a/docs/reference/spec-user-access.md +++ b/docs/reference/spec-user-access.md @@ -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)。 | diff --git a/docs/reference/spec-v02-auth.md b/docs/reference/spec-v02-auth.md index c4c3163b..1b3edd30 100644 --- a/docs/reference/spec-v02-auth.md +++ b/docs/reference/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。 | diff --git a/docs/reference/spec-v02-hwlab-cli.md b/docs/reference/spec-v02-hwlab-cli.md index d7d5e971..e80c67bf 100644 --- a/docs/reference/spec-v02-hwlab-cli.md +++ b/docs/reference/spec-v02-hwlab-cli.md @@ -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 摘要。 | diff --git a/docs/reference/spec-v02-hwlab-cloud-api.md b/docs/reference/spec-v02-hwlab-cloud-api.md index ac71fead..c430df18 100644 --- a/docs/reference/spec-v02-hwlab-cloud-api.md +++ b/docs/reference/spec-v02-hwlab-cloud-api.md @@ -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 的入口。 | diff --git a/docs/reference/spec-v02-hwlab-cloud-web.md b/docs/reference/spec-v02-hwlab-cloud-web.md index 2e96c7e5..0e81d7d9 100644 --- a/docs/reference/spec-v02-hwlab-cloud-web.md +++ b/docs/reference/spec-v02-hwlab-cloud-web.md @@ -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 路径缺口误判为业务已通过。 diff --git a/docs/reference/spec-v02-hwlab-gateway.md b/docs/reference/spec-v02-hwlab-gateway.md index fb0820f8..39a5bd59 100644 --- a/docs/reference/spec-v02-hwlab-gateway.md +++ b/docs/reference/spec-v02-hwlab-gateway.md @@ -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。 | diff --git a/docs/reference/spec-v02-openfga-authorization.md b/docs/reference/spec-v02-openfga-authorization.md index 8d209fe5..71a6ef2f 100644 --- a/docs/reference/spec-v02-openfga-authorization.md +++ b/docs/reference/spec-v02-openfga-authorization.md @@ -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 或跳登录，不渲染空管理表。 diff --git a/internal/cloud/code-agent-session-registry.test.ts b/internal/cloud/code-agent-session-registry.test.ts index de1c4cef..2e5d2fc1 100644 --- a/internal/cloud/code-agent-session-registry.test.ts +++ b/internal/cloud/code-agent-session-registry.test.ts @@ -213,7 +213,7 @@ test("code agent session registry stores bounded non-sensitive conversation fact assert.match(facts.summary, /workspace=\/workspace\/hwlab/u); }); -test("Codex child env carries only device-pod API key needed by Code Agent tools", () => { +test("Codex child env carries only user API key needed by Code Agent tools", () => { const child = childProcessEnv({ PATH: "/usr/bin", CODEX_HOME: "/tmp/codex-home",