qinglong/docs/adr/ADR-0500-short-lived-cluster-security-administration-command.md

ADR-0500：短生命周期 Cluster Security Administration 产品命令

• 状态：Accepted
• 日期：2026-08-25
• 决策：D-405
• 关联：ADR-0049、ADR-0050、ADR-0051、ADR-0276、ADR-0301

背景

ADR-0050 已把 Identity register/enable/disable、API credential issue/rotate/revoke、不可变 mutation ledger、强 actor、同事务 audit 与有界 audit query 收口到独立的 @qinglong/cluster-admin authority，并明确禁止常驻 cluster-control 获得 admin 数据库角色。但原切片只有 application service，没有受审产品入口。部署用户只能自行编写 composition root，容易重新引入常驻高权限进程、宽泛数据库连接池、secret stdout 或未经隔离的认证用途。

QingLong 3.0 同时面向低性能路由设备和 Cluster 节点。该入口只属于 Cluster Admin 镜像；不能进入 Edge/Standalone 制品，也不能为了操作便利新增 listener、daemon、timer、watcher 或常驻连接池。

决策

1. 在既有 Cluster Admin package 内增加短生命周期命令

@qinglong/cluster-admin 增加 ql3-security-admin，并由 ql3-cluster-admin security facade 到达同一安装内的固定目标。它继续位于 ADR-0301 已确定的 security-administration/ 领域目录，不为一个共享相同镜像、依赖、升级和故障生命周期的 composition root 新建 workspace package。纯命令协议/runner 与 POSIX/PostgreSQL production runtime 分成两个领域内文件，避免再形成根目录平铺或单个超大 composition 文件。

命令不监听端口，也不读取 home、ambient Kubernetes context 或默认凭据。每次调用只执行一个 exact-shape JSON operation，然后关闭 PostgreSQL authority：

• identity.register、identity.enable、identity.disable；
• credential.issue、credential.rotate、credential.revoke；
• audit.list。

未知字段、相对路径、非规范路径、无界 audit query 和 operation/request shape 混淆都在获得数据库 authority 前失败关闭。

2. 独立强身份用途

管理命令只接受 dedicated JWT assertion profile：

• typ=ql3-security-administration+jwt；
• purpose=security-administration；
• 独立 audience 与 keyset generation/revocation ledger；
• 复用既有强认证规则，只接受当前、未撤销且满足 assurance 的 principal。

Plugin Package、Worker Credential、Automation、Approval、Run、Provider Credential 或其他管理面的 assertion 不能跨用途复用。assertion、keyset、pepper 与 command 都必须是显式绝对文件；私有材料拒绝 group/world 权限，读取时拒绝 symlink、大小越界和读中变更。

3. Admin 数据库 authority 保持一次性和最小化

命令使用独立的 QL3_POSTGRES_ADMIN_* 配置，只打开 admin role，Pool 上限为一个连接，并设置短 connection/idle/lifetime 边界。默认要求 PostgreSQL verify-full 与显式 DNS server name；只有同时指定 TLS_MODE=disable 和明确的不安全 opt-in 才允许测试环境禁用 TLS。

启动先验证 ADR-0050 admin schema/readiness，随后复用既有 Repository 与 ClusterAdministrationService。成功、拒绝、异常和 readiness 失败都关闭数据库 authority。runtime、migration 与 admin credential 仍不得混用。

4. Credential 只交付到私有 no-replace 文件

issue/rotate 的一次性 bearer token 不写 stdout、stderr、日志、audit 或命令结果。调用者必须提供一个尚不存在的 delivery path，其父目录必须是真实私有目录。publisher 在同目录创建 0600 临时文件，完整写入并 fsync，再以 hard-link no-replace 发布并同步父目录；已有目标永不覆盖。

stdout 只返回 delivery basename 与内容 SHA-256。语义重放仍遵循 ADR-0050：数据库返回 token=null 时不得重新生成或重新发布材料。若首次成功后的交付响应丢失，操作者只能以新的 mutation ID 执行 rotate，不能恢复旧 secret。

5. 本切片不是远程管理平面

该命令关闭“已有 administration service 但没有受审产品入口”的缺口，但不增加 HTTP/API/UI、远程 listener、全局 quota 或后台 retention/export。生产使用仍应由一次性 Job、受控运维工作站或等价的短生命周期执行环境注入 assertion、keyset、pepper 与 admin database credential，并在完成后销毁运行环境。

双人复核、break-glass、pepper rotation、audit retention/export/alert 和完整 Kubernetes Job ceremony 仍是后续门禁，不能由本命令的存在推断为已经完成。

被拒绝的替代方案

把命令加入 Cluster Control HTTP API

拒绝。它会让常驻业务进程获得 admin 数据库权限，并把 credential 签发和 audit 读取暴露到远程攻击面。

新建一个 workspace package 或常驻 Admin Deployment

拒绝。该 composition root 与 cluster-admin 共享镜像、依赖、权限和升级生命周期；拆包只会制造单文件 package，常驻 Deployment 则扩大高权限驻留时间和资源占用。

把 token 返回 stdout 或保存进 PostgreSQL

拒绝。shell history、日志采集、CI 输出和数据库备份都会成为 bearer custody 面，且破坏 ADR-0050 的不可恢复语义。

自动发现默认 keyset、pepper 或数据库凭据

拒绝。ambient authority 会让同一命令在工作站、Pod 和路由设备上取得不同且不可审计的权限来源。

验证

• 新命令测试覆盖强身份注入、authority 必关闭、敏感 Buffer 清零、credential 私有交付、精确重放不再发布、有界 audit query、widened shape 拒绝，以及真实 0600 no-replace 文件语义。
• keyset 测试证明 Security Administration 的 type、purpose 与 audience 不能和其他管理面混用。
• product facade 与 admin-image live contract 冻结固定 target、无 shell delegation、--help 和无网络/只读容器运行边界。
• @qinglong/cluster-admin 完整回归为 448 total / 445 pass / 3 conditional skip / 0 fail。
• 18-package clean build/test 退出 0；backend 为 1575 total / 1573 pass / 2 conditional skip / 0 fail。
• 真实 arm64 Cluster Admin 镜像在 non-root、read-only rootfs、network=none、cap-drop=ALL、no-new-privileges、32 PID、128 MiB 和 0.25 CPU 下通过 12 个产品命令 live contract。PostgreSQL 18.6 arm64 physical HA 在 timeline 1→2 promotion 后通过 147 gates，content-free report SHA-256 为 8fbb606773080dae15de5e31db5726abb8700862b51e4616b5f3f50e0b8374f3。
• package boundary 保持 18 packages、singleSourcePackages=[]、shallowSourcePackages=[]；Cluster dependency、122-module Edge import、Cluster deployment、image release 与 service-manager bridge 审计全部 compatible。

影响与剩余门禁

D-405 提供了第一个可直接使用、默认无 listener 的 Cluster Identity/API Credential/Audit 管理入口，同时不改变 Edge/Standalone package、依赖或常驻资源。它只关闭 ADR-0050 的产品入口缺口；远程管理 API/UI、双人复核或 break-glass、pepper 生命周期、audit retention/export/alert 和生产部署 ceremony 仍需后续 ADR 独立证明。