qinglong/docs/adr/ADR-0030-legacy-panel-authentication-and-stable-user-identity.md

ADR-0030：Legacy Panel 认证与稳定 User Identity

• 状态：Proposed
• 日期：2026-07-19
• 关联：QL-RFC-0001、ADR-0028、ADR-0029

上下文

QingLong 2.x 是单用户面板，但没有稳定的 User ID。Auths 的 authConfig JSON 保存可修改 username、密码和当前 token；JWT payload 只有随机 data、iat、exp，不包含 subject。Express 先验证 HS384 JWT，再按 desktop/mobile 到当前 token 列表中查找。仅把 username 当 3.0 ActorRef 会在改名后漂移；仅验证 JWT 签名会让已经 logout、被 token 列表移除的 credential 重新获得权限；把 system App token 当 User 则会混淆 API App 与交互用户。

ADR-0029 的 owner claim 只接受 AuthenticatedPrincipal，因此必须先建立一个不复制 credential、不自动授予角色、能够在 edge 上点查并在 cluster 中替换 adapter 的稳定身份映射。

同时，当前部署并不存在可靠的在线“本机管理员”边界。Alpine 镜像和大量存量部署让控制面与用户脚本以同一 UID、同一文件系统运行；即使 Debian 镜像使用 qinglong 用户，控制面和脚本通常仍共享该用户。TTY、loopback、0600 文件、环境变量或 Unix peer UID 都可能被同权限任务读取或调用，不能直接产生 assurance=local_console。

决策

1. Legacy 单用户映射为固定内部 User，不使用 username

0019-identity-directory 新增：

• IdentitySubjects：稳定 subject、active|disabled、version 和时间；
• IdentityAuthenticationBindings：(provider,provider_subject,version) append-only binding，状态为 active|revoked；
• current 和 subject 反向索引均为有界点查。

baseline 固定为：

IdentitySubject: user/usr_legacy_primary
AuthenticationBinding: legacy_panel/singleton@1 -> usr_legacy_primary

usr_legacy_primary 是实例内 opaque identifier，不是用户名、数据库行号、JWT data、IP 或设备名。migration 不读取或复制 username、password、two-factor secret、JWT、system App credential 或 token list，也不创建任何 Project RoleBinding。改名只改变 2.x 显示/登录字段，不改变 3.0 ActorRef。

未来原生多用户可以创建新的 opaque User ID 和 provider binding，但不得重用 username 作为主键。cluster-control 必须提供保持相同 current-version、disable/revoke 和 fail-closed 语义的 PostgreSQL adapter。

2. Legacy session authority 是三个条件的交集

LegacyPanelAuthenticationService 只有同时满足以下条件才返回 principal：

1. token 是有界 canonical JWT，签名算法精确为 HS384；
2. payload 精确包含 data/iat/exp，签名、iat <= now < exp 均有效；
3. token 仍存在于当前 2.x primary token 或请求 platform 对应的 token list；
4. legacy_panel/singleton 最新 binding active；
5. 对应 IdentitySubject 为 active user。

签名有效但已 logout、platform 错位、binding revoked、subject disabled 或 identity 损坏都 fail closed。JWT/request 不得自报 subject、role、scope、assurance 或 Project。authenticationId 是 legacy_panel: 加 token SHA-256，只用于非 Secret 关联；原 token 不进入 identity 表、RoleBinding、错误或审计字段。

session source 兼容 2.x primary string、platform string 和 TokenInfo[] 三种现存格式；候选数量和单 token 字节数有硬上限，损坏/超载返回 unavailable，不能降级成“只要签名正确”。比较使用 SHA-256 后的 constant-time equality。

3. Legacy assurance 永远是 single_factor

2.x token 没有不可篡改的 amr/acr 或“本次签发已完成 TOTP”声明。当前 twoFactorActivated=true 只描述账号现在启用了 TOTP，不能证明一个较早签发且尚未 logout 的 token 完成过第二因素。

因此所有 legacy panel principal 固定为 assurance=single_factor。未来只有新认证协议在 credential 内绑定并验证 factor evidence 后，才能返回 multi_factor；不得根据当前设置、UI 路径或调用者参数推导。

4. Identity disable 与 authentication binding revoke 分离

• disable IdentitySubject：停止该 User 的所有 provider authentication；
• revoke AuthenticationBinding：只停止某 provider/external subject 的映射；
• logout/token removal：只停止对应 session；
• RoleBinding revoke：只撤销某 Project 权限，不改变身份认证。

四者不得互相替代。当前切片只实现 baseline、current resolve 和认证读取，不开放 identity mutation API；未来 mutation 必须 append binding version、使用 subject CAS 并追加低敏审计。

5. 不提供伪安全的在线 local-console issuer

本 ADR 明确拒绝在当前同 UID 执行模型中用下列信号直接构造 system/owner-bootstrap + local_console：

• 请求来自 loopback；
• CLI 进程有 TTY；
• capability 文件模式为 0600；
• 调用者 Unix UID 与控制面相同；
• 某个环境变量或命令行 flag 存在。

这些条件同样可能被用户脚本满足。可接受的后续实现必须选择并验证至少一种真实隔离：

当前 2.x 启动顺序也不存在可直接复用的 HTTP claim 安全窗口：cluster master 完成 migration 后先 fork gRPC worker，再 fork HTTP worker；HTTP worker 在 listen 前执行 initData() 和 initTask()，其中 system token task 可 runImmediately=true，已有 Cron 也会在 loader 阶段注册/启动。也就是说，在首个 HTTP 请求到达前，同 UID 任务已经可能运行。可信首装 ceremony 必须移动到 cluster master 的任何 worker pre-fork gate，或先完成 Executor 独立 UID 隔离；不能只新增一个“仅首次启动可访问”的 HTTP route。

1. 在任何用户任务/Executor 启用前完成一次性安装 ceremony，并在启用任务前销毁 issuer capability；
2. 使用用户任务不可达的独立 UID/host agent，通过 peer credential 提供一次性签发；
3. 服务完全停止且持有可验证的 offline maintenance lease，保证没有任务进程和控制面竞争；
4. deployment orchestrator 注入硬件/平台证明，且该证明不暴露给 Executor。

在上述边界落地前，owner bootstrap issue 继续 production unreachable。legacy panel authentication core 只能为未来 claim/wire adapter提供稳定 user，不能自行签发 challenge。

6. 当前切片保持 production unreachable

本切片实现 0019、schema ownership、Identity Directory SQLite resolver、legacy Auth snapshot parser 和 authentication service，但没有：

• shareStore/Express 到 session source 的生产装配；
• /api/v3 middleware 或 bootstrap claim route；
• local-console issuer、安装向导或 offline maintenance lease；
• identity disable/revoke 管理 API 和审计事件；
• PostgreSQL adapter 与跨方言 contract suite；
• 原生多用户、MCP/API App/Agent authentication adapter。

因此现有 /api/* 行为不变，default Project 仍没有 owner。新增 baseline identity 只是稳定映射候选，不产生任何权限或外部可达能力。

影响

正面影响：

• legacy 用户改名不会改变 3.0 审计主体；
• logout、token platform 和 identity revoke/disable 都能独立 fail closed；
• 不复制 credential，edge 只增加两张小表和一次有界点查；
• 2FA assurance 不会被当前设置错误提升；
• 明确暴露同 UID 部署的信任限制，避免不安全 CLI 进入生产。

代价与风险：

• 所有 2.x panel session 暂时映射到同一 singleton User，无法区分共享账号背后的自然人；
• 每次 3.0 认证在现有 session 检查外增加一次 identity 点查；
• 当前 core 不接路由，用户仍不能完成 owner claim；
• 真正 local-console ceremony 可能要求启动顺序、UID 隔离或停机运维变化。

未选择的方案

1. username 作为 User ID：可修改、可能复用，审计漂移，拒绝。
2. JWT data 作为 User ID：每次登录随机变化且属于 credential，拒绝。
3. 只验证 HS384 签名：logout 后 token 仍可能在到期前通过，拒绝。
4. system App 映射为 User：把机器 credential 提升成交互用户，拒绝。
5. twoFactorActivated 推导 MFA：不能证明 token 签发时完成过 TOTP，拒绝。
6. migration 自动创建 owner binding：身份迁移不等于授权同意，拒绝。
7. 同 UID 在线 CLI 视为 local console：用户任务具有相同能力，拒绝。

验证要求

• migration baseline 与 username/token/password/TOTP 完全无关，不创建 RoleBinding；
• username 变化不改变 user/usr_legacy_primary；
• HS384、精确 payload、毫秒级 active window 和 current-session membership 全部验证；
• logout、platform drift、wrong signature/algorithm、extensible JWT/request 在 identity 副作用前拒绝；
• legacy primary string、platform string 和 TokenInfo[] 兼容且有硬上限；
• authentication ID 只包含 token digest，错误不泄漏 token；
• binding revoke、subject disable、损坏 storage/session source fail closed；
• assurance 始终为 single_factor；
• Node 22/24 全量测试、类型检查、schema audit 和 GitNexus reachability 通过；
• app/loaders/api/services/shared/data 不得导入或装配本切片。