qinglong/docs/adr/ADR-0242-approved-worker-credential-management-and-execution.md

ADR-0242：受批 Worker Credential 管理与一次性执行边界

• 状态：Proposed
• 日期：2026-08-01
• 关联 RFC：QL-RFC-0001 D-23、D-58、D-175、D-207、D-224、D-225、D-226
• 关联 ADR：ADR-0141、ADR-0142、ADR-0185、ADR-0217、ADR-0234、ADR-0240、ADR-0241
• 承接：ADR-0241 尚未完成的强 User、双人批准与 TokenRequest session 产品组合

背景

ADR-0241 已把 Kubernetes delivery capability 收敛为 callback-scoped、内存中的一次性 TokenRequest session，但它只解决“已获得执行授权后如何安全签发和销毁 token”。如果产品入口 直接让调用者构造 delivery 参数，仍会缺少三个关键事实：谁申请、批准的精确目标是什么、执行时 是否仍与批准内容和 Project authority 一致。

该问题也不能通过新增一组细粒度 workspace package 或常驻 credential controller 解决。 QingLong 同时面向低配路由设备与集群节点：前者不应安装 PostgreSQL/Kubernetes SDK、连接池和 后台轮换循环；后者则必须把可被网络调用的管理 authority 与持有 Kubernetes delivery capability 的执行 authority 分开。

决策

1. 产品链固定为四段持久事实

Cluster Worker credential 的 issue|rotate 固定执行：

1. 强 User principal 在 Authority Project 内通过 worker.manage，创建最长 15 分钟、不可变且 不含 token/Secret/kubeconfig 的 management plan；
2. 同一申请者基于 plan digest 发起 high risk、separation_of_duty ApprovalRequest；
3. 另一名具有 approval.decide 的强 User 对 exact action/plan/preview digest 作出决定；
4. caller-driven executor 重新读取 plan/approval/Project fence，原子 consume approval 并取得 durable dispatch 后，才进入一次性 TokenRequest session 和可恢复 delivery issuer。

approval、dispatch、credential mutation 与 delivery 都使用稳定 identity 和 exact replay。token 只存在于 session callback 内，不能进入 plan、approval、PostgreSQL、结果、日志或审计事件。

2. Manager 与 Executor 使用不同数据库角色

ql3_worker_credential_manager 只读 Project/RoleBinding/schema facts，可创建 plan、 ApprovalRequest 和 Audit；它不得读写 credential、delivery、stage discard 或 dispatch。

ql3_worker_credential_executor 只读 plan 与 Project authority，可 consume ApprovalRequest、追加 dispatch/credential/mutation/delivery/stage-discard/Audit；它不能创建或改写 plan，也不能取得其他 runtime、Package 或 migration authority。两个角色都不是 superuser、owner、createdb、createrole、 replication 或 bypassrls；每个部署连接上限为 4，并只执行 approval policy fence function。

迁移 pg-0047 建立 immutable plan 与上述 grant，control-core 推进到 v46；pg-0048 只调整 credential lifetime check，使批准时刻早于实际创建时刻仍可执行，同时要求 expiry 晚于 GREATEST(createdAt, notBefore)，并推进到 v47；pg-0049 把 durable execution receipt 的 SELECT/INSERT/UPDATE 仅授予 executor 并推进到 v48；pg-0050 再建立使用数据库时钟、 exact replay receipt 的 manager quota bucket，把共享 identity keyset ledger 的 authority 严格扩展为 Plugin Package/Worker Credential 两值，并仅给 Worker manager 相应读写权限，推进到 v49。历史迁移 不原地改写。

共享 approved_action_executions 表的 dispatcher 必须把自身注册 handler 的 action types 下推到 repository 查询。没有匹配 handler 的 executor 不得领取、租约或 block 其他 authority 的动作。

3. 批准时间与执行时间必须分离

plan 固定批准的 credentialNotBeforeAtMs 与 credentialExpiresAtMs。执行因人工审批延迟时， 不得把 not-before 改成当前时间，否则批准摘要失效；也不得创建已经到期的 credential。执行端 要求当前时间仍早于 plan、dispatch 和 credential expiry，再按批准的原始时间签发。rotation 还必须确认 predecessor 是同一 Worker 当前有效 credential。

4. 不按源码文件拆 workspace package

本能力分别落在既有 package 的显式 subpath：

• runtime-core/worker-credential-management-plan：Profile-neutral plan contract；
• cluster-postgres/worker-credential-manager：manager-only repository/readiness；
• cluster-postgres/worker-credential-executor：executor-only repository/readiness；
• cluster-admin/worker-credential-management：强 User 管理 facade；
• cluster-admin/worker-credential-management-executor：一次性执行组合。

它们不是新的发布、部署或 dependency root，因此不建立单文件 package。只有出现独立制品、独立 第三方重依赖、必须从常驻闭包排除的 authority，或三个以上 package 需要稳定依赖反转时，才允许 重新评审 package 边界。

5. Edge/Standalone 与 Cluster 不共担部署成本

Edge/Standalone 不导入上述 PostgreSQL/Kubernetes 管理 subpath，不创建这两个角色、连接池、 TokenRequest client、timer 或常驻进程；本机身份和 credential ceremony 继续由短生命周期 Owner CLI 与 SQLite authority 完成。路由设备运行 Worker 时仍使用同一受预算约束的 Worker runtime， 但 Cluster 管理 SDK 不进入其制品闭包。

Cluster 可提供独立认证后的 manager transport，但 executor 必须保持一次一命令/一次 Job 的 caller-driven 生命周期：打开至多一个受限数据库资源，consume durable approval，创建一次 TokenRequest session，执行或重放 delivery，然后销毁 Kubernetes client 并关闭数据库。不得把 executor 变为常驻 controller、轮换 timer、watcher、leader election 或 sidecar。

不采用方案

把 manager 与 executor 合成一个 admin role/process

拒绝。网络管理入口一旦被利用，就会同时获得 approval 创建和 Kubernetes delivery capability， separation-of-duty 只剩应用层约定，无法由数据库 grant 和部署凭据证明。

每个 plan/repository/service 新建一个 package

拒绝。这些模块没有独立部署、发布或第三方依赖边界，会增加 importer、lock、SBOM、build 和升级 成本，却不能进一步缩小运行时 authority；显式 subpath 已能提供需要的可见性和审计门。

常驻 controller 自动签发和轮换

拒绝。它会长期持有 issuer、delivery 与数据库 authority，并增加 timer、重试、leader 和连接 生命周期；低配设备不需要这套成本，Cluster 的低频高风险操作也更适合显式受批执行。

批准后把 not-before 重写为执行时间

拒绝。它会改变已批准 plan 的语义与 digest；若不重写 digest 就是越权，若重写 digest 则必须 重新审批。正确做法是保留批准时间并验证执行时尚未过期。

影响

• CloudNativePG 数据库角色由六个增至八个，新增两个离散 credential Secret 示例；
• workspace package 数不增加，Edge/Standalone production closure 不增加 Cluster 依赖；
• Cluster Admin 在同一 package 内增加 management transport/HTTP/client/process 显式 subpath、 manager/client/executor CLI binary、opt-in 双副本 Kubernetes Deployment 与 caller-driven Job； 不增加 workspace package。 manager process 使用独立 Worker manager Pool、durable quota 与 authority-scoped identity ledger， 不取得 executor、Kubernetes API、Secret 或 pepper authority；executor Job 只取得显式 600 秒 issuer token、exact delivery ServiceAccount 的 TokenRequest 和 executor PostgreSQL role；
• 运维工作站通过独立 opt-in management client Job 发起单条命令；该 Job 无 RBAC/API token， 只把不可变 request、短期强 User assertion 与受审 CA 分离投影，预检仅重试 TLS 1.3 /readyz，生产 client 主进程不自动重试业务请求；
• executor 在 approval consume 后失败时保留 durable dispatch，后续以同一 identity 恢复，不重新 请求人工批准，也不重签不同语义的计划；
• executor 对 execution baseline 执行 claim→start→complete；成功回执精确绑定 delivery identity 与 publication digest，重放只读 durable delivery，不再次进入 TokenRequest session；
• plan 与 PostgreSQL 只持目标、摘要、时间和低敏证据，不持 bearer token。

验证

当前实现证据：

1. manager/executor PostgreSQL readiness 正向与越权负向测试通过，两个 package entrypoint 的 capability 集合互斥；
2. management 的 plan/propose/decide/inspect happy path 已覆盖强 User、Project worker.manage/approval.decide、双人决定、immutable exact replay 与配置收窄；
3. runtime/admin/delivery 已覆盖审批延迟后仍按原 not-before 创建、已过期拒绝与 delivery recovery；
4. PostgreSQL migration/schema/manifest 全量测试通过，pg-0047/pg-0048/pg-0049/pg-0050 有独立 predecessor、capability 和 grant/constraint 契约；control-core 已到 v49；
5. CloudNativePG deployment audit 已验证八角色和 Secret 映射；
6. 真实 K3s v1.34.3+k3s1 + PostgreSQL 18 纵切面完成两次 plan、职责分离批准、consume、 TokenRequest、delivery 与 succeeded execution receipt；同一 execution 的精确重放没有再次签发 token；
7. PostgreSQL 18.4 arm64 physical HA 在 v49 上通过 remote_apply、timeline 1→2、旧主 fencing、 未确认分区提交排除、pg_rewind 只读同步重入、fresh control replicas 与全部领域 gate。
8. management transport 仅公开 plan/propose/decide/inspect，认证失败、弱 assurance、扩展 shape 与 内部 execute 均在管理 authority 前拒绝；响应只含 plan/approval 低敏摘要；
9. Worker HTTPS host 复用既有 TLS 1.3、认证前连接/peer/global shield、并发/超时/body/response 上限，但路径固定为 /api/v3/worker-credentials/management，Plugin Package 路径在同一实例返回 404；Worker/Plugin HTTP 11 项联合回归与原普通/Kubernetes tunnel client 15 项回归通过；
10. Worker client/CLI 复用 canonical 私有文件、CA/servername、TLS 1.3、无 redirect、单请求与 bounded response 实现，四类结果 exact-validate，附加 authentication ID、secret-bearing shape 或 内部 execute 结果失败关闭；本能力未新增 package，ADR-0243 删除孤立 cutover 后当前为 19；
11. manager durable quota 在 Project Policy 后、任何 plan/approval state read 前执行，四类 operation 使用数据库时钟、固定窗口与有界 receipt ledger；精确重放不重复计数，拒绝映射为 HTTP 429；
12. Worker manager process/CLI 已接入专用 role readiness、authority=worker-credential-management identity ledger、quota、TLS 1.3 HTTP 与有序 drain/close；禁用态只读 enable 开关且零文件/数据库 副作用。新旧 manager 进程 14/14；caller-driven executor process/CLI 已固定 exact command、私有 32-byte pepper、单连接 Pool、两次 issuer authorization confirmation、一次 TokenRequest session 与 失败保真销毁与低敏 CLI 输出，专项 7/7；cluster-admin 全量 174 pass/1 条件 skip；
13. opt-in Kubernetes base/CloudNativePG overlay 已完成双副本、PDB、required anti-affinity、零 ServiceAccount token、只读 TLS/identity/CA 投影、label-only ingress、DNS/PostgreSQL-only egress、 manager-only CNPG credential 与 fail-closed image digest；独立 executor base/CNPG operation 采用 caller-driven Job、backoffLimit=0、600 秒投影 issuer token、existing exact TokenRequest RoleBinding、 command/pepper/CA 分离只读投影、executor-only CNPG credential、无 ingress 与 DNS-only base egress； Kubernetes API 必须由私有 overlay 指定 exact CNI destination。独立 management client operation 固定 backoffLimit=0、零 token/RBAC、DNS + manager:8444-only egress、不可变三输入和独立 fail-closed digest；deployment audit 28/28 变异测试通过；
14. PostgreSQL 18.4 arm64 physical HA 在 v49 再次运行，八角色专用 readiness 在 promotion 前后均 通过；新增 Worker manager 双数据库实例矩阵以 16 个并发请求证明 8 admitted/8 limited、重放 零额外计数、autocommit response loss 精确收敛，并把 identity ledger 推进到 generation 3，证明 restart rollback、same-generation rewrite、implicit removal 拒绝与 COMMIT response loss 收敛。 remote_apply、timeline 1→2、fencing/partition/pg_rewind/只读同步重入和总 gate 均继续为 true； 该证据不冒充真实 Kubernetes Pod、HTTP listener 或外部 IdP 演练。
15. 真实 K3s v1.34.3+k3s1 + PostgreSQL 18 门已用生产 cluster-admin 镜像运行第三次 caller-driven credential rotation：首次 Job 返回 published 且 tokenRequestUsed=true，第二个 独立 Job 精确重放相同 command 时返回 existing 且 tokenRequestUsed=false。两个 Job 均使用 backoffLimit=0、executor-only 单连接数据库凭据、无 automount token、600 秒投影 issuer token、 无 ingress 和精确 API Service/backend/PostgreSQL /32 egress。最终 3 个 plan/consumed approval/ dispatch/succeeded execution/credential/published delivery、12 条安全审计、Recreate stop-before-start、 Bound PVC journal 与 identity generation rollout 全部收敛，总 gate 为 true。
16. 三节点 K3s + PostgreSQL 18 的独立 manager 门以两个 required anti-affinity Pod、生产 Worker management client 和 TLS 1.3 精确 Pod 寻址完成 8 admitted/8 limited；配额已满后的 跨 Pod exact replay 返回 existing，最终 plan/consumed/receipt 均为 8。identity projection 依次覆盖 generation 1、2 overlap、3 revoke，generation 2 rollback surge 以 exit 1 失败关闭且 两个旧 Pod 保持 Ready。停库后两个业务请求均为 503、Ready 均为 503、Live 均为 200；数据库 重启不允许旧实例原地解除 availability fence，只有 fresh rollout 的两个 Pod 返回 200。一次性 client Job 仅对没有远端响应的 transport failure 复用同一幂等命令做有界重试，不重试任何 HTTP 业务拒绝。该门同时发现并修复计划 repository 把 plannedAtMs、expiresAtMs 与派生 digest 错当为调用方语义、导致跨 Pod exact replay 500 的问题；不同 target/requester 仍冲突。facade 同时把无效计划和 semantic conflict 分别稳定映射为 HTTP 400/409，不再泄漏成 500。
17. 同一三节点 K3s 门现在直接加载仓库内 management client ServiceAccount、NetworkPolicy 与 Job， 只把镜像替换为本次构建的生产 Admin image。固定 qinglong3-system DNS、TLS 1.3 /readyz init、不可变 request/assertion/CA、零 projected token 条件下，init/main 均 exit 0，client restartCount=0，worker-credential.inspect Job Complete；报告新增 gates.committedOneShotClientOperation=true 且总 passed=true。该证据不依赖 kubelet 日志代理， 以 Kubernetes Job/Pod 终态证明执行，避免把管理响应复制到 termination message。

仍未完成

• 外部 OIDC/client certificate 双 User ceremony、撤销审计与真实生产 ingress；
• 多节点 Kubernetes API/CSI 故障矩阵，以及固定 x64/arm64 路由设备与集群节点资源报告。