qinglong/docs/adr/ADR-0356-optional-authenticated-cluster-approval-management.md

# ADR-0356：可选、受认证且独立授权的 Cluster Approval 管理面

- 状态：Accepted
- 日期：2026-08-10
- 关联 RFC：QL-RFC-0001 D-05、D-06、D-08、D-13、D-17、D-28、D-75、D-85、D-87、D-123、D-127、D-157、D-257、D-259、D-260、D-263、D-265、D-266、D-267、D-268
- 关联 ADR：ADR-0031、ADR-0125、ADR-0129、ADR-0138、ADR-0353、ADR-0354、ADR-0355

## 背景

ADR-0355 已建立 Profile-neutral Approval inspect/decide 服务和本机 `ql3-approval` Owner CLI，但有意没有注册
Cluster 远程 route。Cluster 操作者若只能在进程内组合 service，就没有可部署、可认证、可限流、可审计且能在数据库故障时
摘流的产品入口；若把入口塞进 `cluster-control`，又会让调度/执行控制面取得人类决定 authority。另一方面，Edge/Standalone
尤其是低配路由设备不能因为 Cluster 能力而增加 HTTPS listener、证书、OIDC keyset 或 PostgreSQL Pool。

## 决策

1. Cluster Approval 管理面是独立、默认不部署的 `cluster-admin` process，固定只服务
   `POST /api/v3/approvals/management`、`/livez` 与 `/readyz`。它不注册到 `cluster-control`，也不进入
   Edge/Standalone artifact 的启动图。
2. 公共业务操作仅为 schema v1 的 `approval.inspect` 与 `approval.decide`。inspect 返回 canonical action binding 和既有
   redacted preview；decide 必须带回完整 `expectedAction`、固定 `expectedVersion: 1`、稳定 decision ID 和有界 reason code。
3. 每次业务请求都必须同时通过 TLS 1.3 mTLS 与短期 OIDC。断言固定
   `aud=qinglong3-approval-management`、`typ=ql3-approval-management+jwt`、
   `ql3_purpose=approval-management`，主体只能是具有 `multi_factor` 或 `hardware` assurance 的 User。其他 management
   plane 的 assertion 即使 issuer/key 相同也不能复用。
4. Transport 在 service 前后都重新认证。初次认证失败写 `authentication_rejected`；第二次认证漂移、Policy 或 credential
   fence 失败写 `denied`，并保持低敏错误响应。成功 inspect/decide 继续使用领域层的 durable audit 与原子状态转换。
5. PostgreSQL `pg-0054-approval-management-boundary` 将 control-core 推进到 capability v53，新增非 superuser、非
   CREATEDB/CREATEROLE/REPLICATION/BYPASSRLS 的 `ql3_approval_manager`。它只读 Project/RoleBinding、Approval、preview
   Artifact metadata，能追加安全审计、更新 Approval、维护本 authority 的 identity keyset ledger，并执行专用 Approval
   Policy lock；不得取得 runtime、package executor、migration、AI credential 或 Secret authority。
6. 进程只能使用 `role: approval-manager` 打开一个调用方拥有的 Pool；默认/生产清单每 Pod 最多 2 条连接。任何 Pool、schema
   readiness 或 writable-primary 失败都单向撤销 `/readyz` 与 admission，完成有界 drain 后退出，由 Deployment 创建新实例；
   不在原进程透明重连或重放不确定决定。
7. 生产 base 固定 2 Pod、required hostname anti-affinity、PDB `minAvailable: 1`、只读 root、UID/GID 10001、drop ALL、无
   ServiceAccount token。Service 为 ClusterIP 8447；base 只允许 DNS egress，CloudNativePG overlay 只增加 exact database
   Pod 的 TCP 5432。
8. ingress 只接受同 namespace 且带 `qinglong.io/approval-management-client=true` 的 Pod。server TLS、client CA/CRL、
   OIDC public keyset 与 PostgreSQL CA 使用分离的只读投影；私有 overlay 必须替换 CA/CRL annotation digest 和全零 Admin
   image digest。
9. 对操作者提供独立 `ql3-approval-client` 和 opt-in `approval-management-client` Job。Job 无 RBAC/token、
   `backoffLimit: 0`，init 只重试 mTLS `/readyz`，main 只执行一次业务命令；command/assertion/client key 分离为 immutable
   Secret，只有 server CA 可使用 ConfigMap。
10. 响应丢失不等于回滚。inspect 使用新的 request/audit identity 重读；decide 只能用完全相同的 decision ID、决定、reason、
    User 与 action binding 精确重放。客户端、Kubernetes 或 HTTP 层不得自动生成新业务身份重试。
11. identity keyset generation 只能前进；同 generation rewrite、隐式 key 删除、撤销回退均失败关闭。HA gate 必须证明
    Approval ledger 在双实例竞争、COMMIT response loss、物理复制、promotion 与进程重启后仍收敛。
12. MCP 永久保持 Approval 只读，Cluster management 决定也不会 consume、dispatch 或 execute Approved Action。外部副作用仍由
    对应执行面自己的 start barrier、receipt 和恢复协议负责。

## Package 与低配资源裁决

- 不新增 workspace package。Profile-neutral inspection/decision 归 `runtime-core/approved-action`；PostgreSQL authority 归
  `cluster-postgres/approval-management`；transport/process/client 归 `cluster-admin/approval-management`。
- 这是 authority、部署和依赖边界内的包内领域目录，不按文件数制造微包，也不把写 authority 暴露到宽 root barrel。
- Edge/Standalone 仍使用短生命周期、单 SQLite connection 的 `ql3-approval`；未调用时资源为零。Cluster 的两个 listener 和
  最多四条 aggregate PostgreSQL connection 只在显式应用 operation 时存在。
- 十二档 artifact 预算不放宽。当前最紧的 Standalone Application AI 为 6,284,121 / 6,291,456 bytes，仅余 7,335 bytes；
  后续默认闭包增加必须先裁剪或重新评审，不把本次“通过”解释为充裕余量。

## 被否决方案

1. 把 decide 加入 MCP：混合 Agent read authority 与 Human write authority。
2. 把 route 加进 `cluster-control`：调度/执行进程会取得人类决策、OIDC 与 client trust authority。
3. 让 Approval manager 使用 `ql3_admin` 或 runtime role：最小权限和故障域失效。
4. 使用 bearer-only 或 mTLS-only：分别缺少 possession factor 或可审计的人类身份/assurance。
5. 为两个 Cluster 文件另建 package：没有独立依赖、版本或 artifact 生命周期收益，会重新制造微包。
6. Kubernetes Job 自动重试决定：会把未知 COMMIT 结果误当失败并制造双重语义。
7. 为路由器统一启动同一 HTTPS manager：把只属于 Cluster 的证书、监听与数据库成本强加给低配部署。

## 验证证据

- Runtime Core 459/459；Cluster Admin 271 项中 269 pass、2 条件 skip；Cluster PostgreSQL 293 项中 292 pass、1 条件 skip。
- Cluster deployment 47/47；package boundary、cluster dependency、edge import、CloudNativePG role、base/CNPG/client Kustomize
  render 与十二档 artifact 全部 compatible。
- 17 package / 994 source，968 个位于领域子目录、26 个根入口；没有单源或 shallow package，package 数未增加。
- PostgreSQL 18.4 arm64 HA gate `gates.passed=true`，覆盖 `remote_apply`、复制链分区、promotion guard、旧主 fencing、
  timeline 1→2、`pg_rewind` 只读同步重入、Approval manager readiness 与 Approval identity keyset ledger；结束后容器、网络、
  卷均零残留。
- 当前证据不是生产 Kubernetes control-plane HA、基础设施 STONITH、外部 IdP ceremony 或真实多故障域容量结论。