Add first-run local administrator onboarding

[1012839419a-alt]

⚠️ 状态（2026-08-08）

Draft 停留超 48h。已按 7 commits 拆成 4 个独立主题（T1 本地管理员 onboarding / T2 agent 可观测+持久化 / T3 dev 工具链 / T4 固定 API 镜像），详见评论区拆解。 建议：T1 拆出独立 PR 优先推进；本 PR 保留为草稿或标记 superseded。

---

Summary

• make local administrator password setup the primary first-run path for self-hosted installs
• keep OIDC optional and move Bootstrap access behind an explicit emergency-recovery disclosure
• persist a single salted scrypt credential and issue server-signed 12-hour local sessions
• allow only the exact status/setup/login endpoints through the unauthenticated Fleet boundary, with per-client failure limiting
• accept a valid local administrator session even when an upgraded browser also sends a stale Fleet transport token
• document the decision, installer flow, design states, and verification evidence

Why

A fresh deployment currently asks the operator for an organization account or opaque deployment tokens. Single-operator installs often have no OIDC provider, and a Bootstrap credential should not be the everyday browser login.

The new flow is: deploy, enter Bootstrap once and choose a password, then use the password for normal login. Static Fleet tokens remain machine credentials and Bootstrap remains available for recovery.

During live upgrade verification, the browser retained an older Fleet token in addition to the new local session. FleetAuth previously selected the stale X-API-Token first and rejected the request without considering the valid local bearer session. The middleware now evaluates both presented credentials and accepts the request when either one is valid.

Security notes

• setup still requires BOOTSTRAP_ADMIN_TOKEN and can create only the fixed local-admin record
• passwords require 12-256 characters and are stored only as salted scrypt hashes with fixed work parameters
• sessions are HS256 tokens signed by SECRET_KEY and expire after 12 hours
• failed setup/login attempts are bounded per client; tracked-client memory is bounded
• concurrent first-run setup is guarded by the database primary key and returns 409
• a stale invalid Fleet header cannot override an independently valid local session
• no registration, invitation, multi-user local accounts, or password-reset subsystem is introduced

Verification

• 43 tests passed across the original local-auth, Fleet-auth, identity, and identity-model suite
• 36 focused local-auth and Fleet-auth tests passed after the stale-header regression fix
• targeted Ruff checks passed
• TypeScript type-check passed
• targeted frontend ESLint passed
• login regression suite: 4 passed
• Next.js production build passed
• Alembic reports one head; a fresh SQLite database upgraded through the full chain to the new migration
• live Docker deployment migrated the existing SQLite database and remained healthy
• real browser login reached the Studio project page and a full refresh preserved the authenticated session
• design and motion foundation checks passed

Docker note

A clean Compose image build was attempted locally after the application checks. Docker Desktop's BuildKit data store became read-only while committing downloaded base-image layers, before project compilation inside Docker. The failed cache was cleared and the installed release images were reused with the reviewed D-drive application code mounted for live verification. CI or a clean Docker builder should repeat the full image build.

[repowise-bot]

⏳ Repowise has not indexed this repository yet

No analysis on this PR because there is no index to compare against. Indexing usually runs automatically after install; if this persists, start it from the dashboard.

Index 2233admin/opencli-Razormind · Docs

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 02654446-f29c-4b3e-81a9-b182d03db18c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[1012839419a-alt]

收尾拆解（2026-08-08）— 建议按主题拆分

Draft 停留超过 48h、无 review request，先按 7 个 commit 做主题拆解，供后续拆分 PR 或收尾决策：

7 commits → 4 个独立主题

#	主题	commits	文件/规模	评估
T1	本地管理员 onboarding（核心）	6c65f69 + 9873519	backend/api/v1/local_auth.py +81、fleet_auth.py +22/-5、alembic z7a8b9c0d1e2、tests/unit/security/test_local_auth.py +105、openspec `local-admin-onboarding/	🟡 前端 + 后端 + 迁移一体的功能主题，可独立 PR；但与 T1 无依赖
T3	开发体验（dev doctor + 标准化命令）	8517817 + e68cbbb	scripts/dev-environment.mjs +147 + 测试、CI/README/package.json 微调	🟢 纯工具链，风险最低，随时可提
T4	固定 API 镜像（运维）	bc1891f	docker-compose.yml +3	🟢 3 行，与 0.4.1 alembic 打包 bug 的本地绕过配套（0.4.1-fixed）

建议路径

1. T1 独立 PR（推荐最先提）：把 6c65f69+9873519 cherry-pick 到新分支 → 新 PR，引用本 PR 关闭或标记 superseded。理由：onboarding 是自述的核心价值，且 body 里的验证证据（43+36 测试、live browser login）就是为它准备的。
2. T2 独立 PR：agent 执行可观测性，与 onboarding 零依赖。
3. T3 + T4 可合成一个 dev-tooling PR，或各自单独提。
4. 若上游近期无空，至少把 T1 拆出来，其余保持 draft。

要不要我直接把 T1（local admin onboarding）拆成新 PR？

[1012839419a-alt]

收尾拆解（2026-08-08）— 建议按主题拆分

Draft 停留超过 48h、无 review request，先按 7 个 commit 做主题拆解，供后续拆分 PR 或收尾决策：

7 commits → 4 个独立主题

#	主题	commits	文件/规模	评估
T1	本地管理员 onboarding（核心）	6c65f69 + 9873519	backend/api/v1/local_auth.py +81、fleet_auth.py +22/-5、alembic z7a8b9c0d1e2、tests/unit/security/test_local_auth.py +105、openspec local-admin-onboarding/	✅ 独立可合的最小单元，安全边界清晰（setup 仍要 BOOTSTRAP_ADMIN_TOKEN、scrypt + 12h 会话、无注册/邀请）
T2	agent 执行可观测 + 持久化	cde5ff8 + 80fb22d	backend/api/v1/chat.py +283、global-agent-dock.tsx +211、models/agent_run.py +52、alembic a8b9c0d1e2f3、openspec agent-execution-experience/	🟡 前端 + 后端 + 迁移一体的功能主题，可独立 PR；与 T1 无依赖
T3	开发体验（dev doctor + 标准化命令）	8517817 + e68cbbb	scripts/dev-environment.mjs +147 + 测试、CI/README/package.json 微调	🟢 纯工具链，风险最低，随时可提
T4	固定 API 镜像（运维）	bc1891f	docker-compose.yml +3	🟢 3 行，与 0.4.1 alembic 打包 bug 的本地绕过配套（0.4.1-fixed）

建议路径

1. T1 独立 PR（推荐最先提）：把 6c65f69+9873519 cherry-pick 到新分支 → 新 PR，引用本 PR 关闭或标记 superseded。理由：onboarding 是自述的核心价值，且 body 里的验证证据（43+36 测试、live browser login）就是为它准备的。
2. T2 独立 PR：agent 执行可观测性，与 onboarding 零依赖。
3. T3 + T4 可合成一个 dev-tooling PR，或各自单独提。
4. 若上游近期无空，至少把 T1 拆出来，其余保持 draft。

要不要我直接把 T1（local admin onboarding）拆成新 PR？

[1012839419a-alt]

T1 已拆出为独立 PR → #68

按评论区拆解方案，T1（本地管理员 onboarding）已拆成独立聚焦 PR：#68

• 分支：feat/local-admin-onboarding（fork），base main，仅包含本 PR 最底部 2 个 commit：
  • 6c65f69 Add local administrator onboarding
  • 9873519 accept local sessions with stale fleet headers
• 分离方式：从 main（Scope workflow execution to the active trigger graph #60 之后）cherry-pick 上述 2 个 commit，零冲突；diff 与原始 T1 范围完全一致（30 files, +876/-96）。
• 验证（2026-08-08 在独立 worktree 重跑）：local-auth + Fleet-auth + identity + identity-model 套件 43 passed；ruff 全过。与 Add first-run local administrator onboarding #61 body 中原始验证证据一致。
• T1 与 T2/T3/T4 无文件重叠，是干净可独立合并的单元。

剩余主题处理建议

• 本 PR（Add first-run local administrator onboarding #61）保持 draft 状态，不关闭——它仍是 T2/T3/T4 的载体。
• T2（agent 可观测 + 持久化，cde5ff8 + 80fb22d）：与 T1 无重叠，建议在 feat(auth): first-run local administrator onboarding #68 合并后以同样方式拆出（从 main 起 cherry-pick，零冲突预期）。
• T3（dev 工具链，8517817 + e68cbbb）与 T4（固定 API 镜像，bc1891f）：建议随后依次拆出，或在本 PR 内按主题分批 review。
• 拆分完成后本 PR 可标记 superseded 并关闭。

拆解过程在独立 git worktree 完成，未改动本 PR 的 head 分支（agent/local-admin-onboarding）内容。

[1012839419a-alt]

T2 已拆出为独立 PR → #70

按评论区拆解方案，T2（agent 执行可观测 + 持久化）已拆成独立聚焦 PR：#70

• 分支：feat/agent-execution-experience（fork），base=main
• 组成：cde5ff8（observable agent execution）+ 80fb22d（persist interactive agent runs），cherry-pick 到 main（7838811）零冲突
• 与 T1 关系：不功能性依赖 T1（chat.py 用到的 _optional_request_identity 等 base 已有）；alembic 迁移 a8b9c0d1e2f3 的 down_revision 已从 T1 的 z7a8b9c0d1e2 改指 main 实际前置 k8l9m0n1o2p3，迁移链独立自洽
• 验证：pytest 50 passed（code-intel 选的候选套件）；ruff 无净新增（27 处剩余全为基线存量）；code-intel change risk=medium，testAsymmetry 0（新持久化代码暂无专门单测，已列入后续）
• code-intel pipeline：doctor ✅ / lite graph ✅ / change risk + agenda + edit impact 均已跑

剩余

• T3（dev 工具链：8517817+e68cbbb，dev doctor + 标准化命令）待拆
• T4（固定 API 镜像：bc1891f，3 行 compose）待拆
• 全部拆完后本 PR 可标记 superseded 关闭