qinglong/docs/adr/ADR-0208-authenticated-local-project-role-policy-cli.md

ADR-0208：强认证 Local Project Role Policy CLI 与防锁死交接

• 状态：Accepted
• 日期：2026-07-29
• 关联 RFC：QL-RFC-0001 D-05、D-27、D-37、D-65、D-72、D-73、D-175、 D-197、D-198
• 关联 ADR：ADR-0028、ADR-0074、ADR-0086、ADR-0185、ADR-0193、ADR-0207

背景

Fresh Setup 与首 Owner ceremony 已创建 default Project 和首个 Owner， ADR-0207 也让 Secret 管理具备正式 CLI。但 Project RoleBinding 仍只有 repository 和 Policy Engine，没有强认证产品入口。部署者不能把 viewer/operator/admin 权限 交给另一个已登记主体，也不能以受支持方式交接 Owner。

直接把 ProjectPolicyRepository.append() 暴露给 CLI 不可接受：

• 它不验证 actor 的 project.manage；
• RoleBinding、allowed audit 和 credential/Policy fence 不在同一事务；
• admin 持有 policy.manage，若产品误用该 permission，可把自己提升为 owner；
• 只数 Owner binding 会允许把 Owner 交给没有 active credential 的 User，随后撤销 原 Owner，形成不可恢复的假交接。

决策

1. 复用现有四个 package，不新增 importer

• @qinglong/runtime-core/local-project-policy-administration 只定义原子 repository contract 和低敏错误；
• @qinglong/local-sqlite/project-policy-administration 是一次命令、一个连接的短生命 周期 composition；
• @qinglong/local-admin/project-policy-administration 拥有认证后领域服务；
• @qinglong/local-owner-cli/project-policy-command 和 ql3-policy 提供私有 command file 产品入口。

workspace 继续是 22 个 package。常驻 local-application、Profile、Worker 和 Cluster 均不能导入两个 mutation authority。依赖审计只允许 exact projectPolicyCommand.ts 使用它们。

2. v1 只管理既有 Project 的 RoleBinding

开放两个 operation：

• policy.role-binding.put：创建或更新 active binding；
• policy.role-binding.revoke：追加 revoked binding。

两者都要求 target、expected current version、UUIDv4 mutation、request ID 和独立 failure-audit UUID。成功只返回 Project、target、version、state、可选 role 和 inserted|existing，不返回 credential、token、pepper、路径或内部 Policy 细节。

本切片不创建/归档 Project，不注册 Identity，不签发 credential，不提供远程 HTTP 入口，也不把常规 ProjectPolicyRepository.append() 变成产品 API。

3. 只有当前强认证 Owner 可以修改 RoleBinding

CLI 使用现有 private 0600 command file、Owner credential presentation、 pepper provenance 和 POSIX proof 建立 local_console Principal。服务固定请求 project.manage，不能改为 policy.manage：

• owner 允许；
• admin/operator/viewer 拒绝；
• admin 不能借管理 RoleBinding 把自己升级为 owner；
• deny/approval/unavailable 先写低敏 audit，再返回固定错误。

4. 最终写事务内复验三重 fence

SQLite 在 BEGIN IMMEDIATE 已取得写锁后按顺序复验：

1. authenticated credential version/state、User status、有效期、pepper state 与 material digest；
2. Project active/version；
3. actor 最新 RoleBinding version/state/owner role；
4. target RoleBinding expected version 与 mutation replay；
5. Owner 连续性。

随后 RoleBinding revision 与 allowed security audit 在同一事务插入。任何 fence、 版本、mutation、audit 或约束失败都回滚。相同 mutation 的语义重放返回 existing；时间戳不参与 response-loss 的语义相等判断。

5. Owner 交接必须同时防止“最后一个 Owner”和“不可登录 Owner”

• active owner 只能授予 user subject；
• owner grant 在同一事务确认目标 Identity active，并至少存在一条当前有效的 active API credential、pepper binding 和 active/retired pepper catalog；
• 撤销或降级当前 active User owner 前，必须仍有另一条最新 active User owner binding；
• 因此正确流程是先为目标 User 完成 Identity/credential ceremony，再 grant owner， 用目标 credential 验证登录，最后 revoke 原 owner。

这不证明目标 credential 的外部 presentation file 仍在；operator 仍必须在交接前 用目标身份完成一次真实认证。

低配路由器与集群影响

• 管理命令仅人工调用时加载，结束后关闭单 SQLite authority；
• 不新增 migration、表、daemon、timer、watcher、listener、socket 或第三方依赖；
• Edge/Standalone 常驻 artifact closure 不导入 local-admin policy service 或 Owner CLI；
• Cluster 继续使用独立 PostgreSQL/RBAC/管理 host 设计，不能复用本地文件 credential CLI。

不采用方案

暴露常规 ProjectPolicyRepository.append

缺少 actor Policy、credential fence 和同事务 audit，且会扩大任意 caller 的写权限。

使用 policy.manage

admin 本来拥有该 permission；允许其签发 owner 会形成直接提权路径。产品固定使用 owner-only project.manage。

只禁止删除最后一行 Owner

RoleBinding 是 append-only，必须检查每个 subject 的最新 revision；历史 owner 行 不能计入当前 owner 数。

只检查第二个 Owner binding

无 active Identity/credential 的 Owner 不能接管系统。将其计入连续性会制造锁死。

验收证据

• ql3-policy 真实 SQLite/CLI 专项 6/6：
  • grant、exact replay、role update、revoke；
  • admin 自提升拒绝；
  • 最后一个 active User owner 撤销拒绝；
  • 无 active credential 的 owner target 拒绝；
  • 有 credential 的 owner handover 后允许撤销原 owner；
  • credential 在预检后 revoke 时事务回滚。
• dependency/source boundary 34/34，包含 mutation authority 的 exact-file 正负向 契约；
• runtime-core contract、SQLite repository、local-admin service 和 Owner CLI 的 strict targeted TypeScript 编译通过；
• workspace 仍为 22 package，无新增 dependency 或 migration。

完整 workspace build、artifact 预算和 PostgreSQL HA 门仍需在锁定依赖恢复后重跑； 不能用本专项门替代。

后续

• Identity register/disable 与 credential issue/rotate/revoke 的本机产品入口；
• Project lifecycle/query 已由 ADR-0212/0213 完成，RoleBinding current query 已由 ADR-0214 完成；仍需 rename、authority transfer 与 RoleBinding history query；
• bounded local audit query 已由 ADR-0215 完成；仍需 export/retention/signing/alert；
• RoleBinding change approval/break-glass 和恢复流程；
• Cluster PostgreSQL 对等管理 transport；
• 固定 Edge 设备上的 CLI RSS、闪存写入和断电恢复证据。