qinglong/docs/adr/ADR-0144-cluster-plugin-package-management-transport-boundary.md

# ADR-0144：Cluster Plugin Package 管理 Transport 与双 Authority 边界

- 状态：Proposed（transport-neutral 强认证适配器、源码边界、manager/executor
  PostgreSQL 角色拆分、dedicated assertion/keyset、TLS 1.3 HTTP process、可选
  management Kubernetes overlay、静态权限门和 PostgreSQL 18.4
  physical-promotion readiness、durable distributed quota 与全副本重启
  keyset anti-rollback 已实现；真实四眼与 live ingress 证据尚未实现）
- 日期：2026-07-25
- 关联 RFC：QL-RFC-0001 D-05、D-08、D-09、D-49、D-85、D-127、D-139 至 D-142

## 上下文

ADR-0142 已在 `@qinglong/cluster-admin/plugin-package-management` 组合
PostgreSQL proposal、Approval、Project Policy 和 caller-driven dispatcher，并固定
`separation_of_duty`。这仍只是认证后的 application service，不是可公开的管理 API。

现有 `cluster-control` Bearer credential authenticator 对 User 只产生
`single_factor` principal；它适合普通控制面 API，但不能被 transport 自行升级为
`multi_factor`。现有 cluster-admin recovery Job 又同时具备 admin PostgreSQL、
Registry credential 和 Kubernetes ConfigMap publish authority。若直接给该 Job
增加长驻 HTTP listener，一个 transport 漏洞将同时取得数据库准入、供应链下载和
资源发布权限。

## 决策

### 1. 不新增 package，不复用 cluster-control

Cluster 管理 transport 留在既有 `@qinglong/cluster-admin`，使用显式子路径和独立
process binary。它不从 package root 导出，也不进入 `cluster-control`、Worker、
edge 或 standalone 闭包。

部署上它是独立且默认关闭的 management Deployment/Service，不复用 recovery Job
Pod。使用同一 workspace package 不代表使用同一 ServiceAccount、数据库角色、
Secret 投影或进程入口。

第一阶段只实现
`@qinglong/cluster-admin/plugin-package-management-transport` 的
transport-neutral command adapter，不监听 socket、不解析 HTTP、不打开 PostgreSQL，
也不直接导入 Kubernetes、Registry 或 Package execution authority。源码门禁只允许
它依赖共享 Approval、Package proposal/management 与 Security contract；其他 package
不得导入该管理子路径。这样先冻结公开操作和 Principal 注入形状，再选择具体协议，
避免临时 HTTP handler 先成为事实标准。

### 2. 人类路由与系统执行分离

公开路由只允许：

- propose：提交 exact Package install action，生成 immutable proposal 与 pending
  Approval；
- decide：由另一名强认证 User approve/reject；
- inspect：只返回 proposal、Approval 与 installation 的低敏摘要。

`consume` 和 `dispatch` 不公开为人类 HTTP 路由。它们由受信 composition 注入固定
system consumer，并通过独立 caller-driven Job/process 执行。外部请求不能提供
consumer subject、authentication ID、ceremony、数据库时间或 dispatcher identity。

### 3. Transport 注入强 Principal

请求 body 不得携带 `principal`。认证 adapter 必须验证部署显式配置的 issuer、
audience、签名 key、有效期、not-before、不可变 subject 与 step-up fact，然后只
映射为 active User 的 `multi_factor` 或 `hardware` principal。

现有 cluster-control API credential 对 User 生成的 `single_factor` principal 必须
失败关闭；service credential 不能替代人类 decide。Cluster ceremony 永久固定为
`separation_of_duty`，requester 与 approver 必须是不同 User。

具体 OIDC、mTLS+step-up 或企业 IdP adapter 在后续 ADR 中选择；在 assertion
验证、key rotation 与撤销证据完成前，本管理 Deployment 保持关闭。

首个 assertion contract 已通过
`@qinglong/cluster-admin/plugin-package-identity-assertion` 固定为专用 compact
JWS，而不是直接信任通用 access token：

- protected header 必须精确为
  `typ=ql3-plugin-package-management+jwt`、reviewed `kid` 与 key-bound
  `EdDSA|ES256|RS256`，拒绝算法降级、未知 key 和额外 header；
- issuer 是 canonical HTTPS URL，audience 与
  `ql3_purpose=plugin-package-management` 必须精确匹配，claim 集合固定且有总字节
  上限；
- key set 最多 8 把，可用新旧 key 重叠完成 restart-based rotation；每把 JWK 必须
  是 exact public signing key，RSA 仅接受 2048–4096 bit/65537，EC 仅 P-256，
  OKP 仅 Ed25519，私钥字段或未知字段均拒绝；
- 每个受信 `acr` 必须由部署配置显式映射到 `multi_factor|hardware`，并列出全部
  required `amr`，verifier 不从任意字符串自行推断 assurance；
- assertion lifetime、authentication age、not-before 与 clock skew 都有硬上限；
  subject 只生成 User Principal，原始 `jti` 通过 issuer-domain-separated SHA-256
  派生内部 authentication ID，不进入 service request、审计响应或低敏结果；
- verifier 只使用 Node 24 `node:crypto` 和 profile-neutral Security contract，不读取
  网络、数据库、Kubernetes 或 Registry authority；源码门禁止其他 package
  import 此子路径。

ADR-0145 已将 verifier 绑定到有界 keyset 文件和独立 HTTP process。keyset 支持
overlap rotation、显式 revocation、同进程 generation rollback/rewrite 拒绝和每请求
重新读取；HTTP 先处理 Authorization 再读取 content/body，只开放 reviewed command
endpoint，并由可选 Kubernetes operation 部署。management Service 仍不进入默认
Kustomize。ADR-0146 已关闭 durable quota 缺口，ADR-0147 又关闭全副本重启
anti-rollback；在真实 IdP 与 live ingress 证据完成前仍不得接入生产 ingress。

### 4. PostgreSQL Authority 拆分

现有广义 admin role 必须收敛为至少两个不共享 LOGIN credential 的部署角色：

- manager：只允许 proposal、Approval、Project Policy 与低敏 Audit 所需的 exact
  SELECT/INSERT/UPDATE/function EXECUTE；
- executor：只允许 consume、execution/start barrier、Package installation、
  recovery 与发布所需的 exact authority。

management Pod 不挂载 Registry credential，不授予 Kubernetes write RBAC，不取得
stage/publish Secret。executor/recovery Job 不暴露 HTTP Service。

角色拆分必须通过 reviewed PostgreSQL migration、schema readiness、unknown-grant
拒绝、连接角色回读和 PostgreSQL 18 physical-promotion 门；不能在启动脚本中使用
superuser 动态 GRANT。

`pg-0022-plugin-package-authority-split` 已把 control-core capability 推进至 v21，
并执行以下收敛：

- `ql3_admin` 撤销全部 Package proposal、Approval/dispatch/execution、
  installation/head/mutation/admission table authority，以及两个 Package fence
  function 的 EXECUTE；
- `ql3_package_manager` 只取得 Project/RoleBinding 读取、Audit
  SELECT/INSERT、proposal SELECT/INSERT、Approval SELECT/INSERT/UPDATE 和 Approval
  policy fence；
- `ql3_package_executor` 只取得 Project/RoleBinding/proposal 读取、Audit
  SELECT/INSERT、Approval consume、dispatch/execution、Package install/head/
  mutation/admission 和两个所需 fence；
- 两个角色都是独立非特权 LOGIN，不得 `SUPERUSER`、`CREATEDB`、`CREATEROLE`、
  `REPLICATION` 或 `BYPASSRLS`，也没有 schema CREATE、owner 或 DELETE authority。

`pg-0023-plugin-package-management-quota` 又将 capability 推进至 v22，只增加
`plugin_package_management_quota_buckets`。该表仅允许 `ql3_package_manager`
SELECT/INSERT/UPDATE；admin、executor、runtime 与 worker-ingress 均为零权限。
`pg-0024-plugin-package-identity-keyset-ledger` 继续推进至 v23，增加一行有界
`plugin_package_identity_keyset_ledger`，以数据库事务固定 trust domain、
generation、active/revoked key 集合和 digest。

ADR-0151 的后续 `pg-0025-plugin-package-materialized-revisions` 已推进至 v24；
新增 immutable revision 表只允许 `ql3_package_executor` SELECT/INSERT，
manager/admin/runtime/worker-ingress/PUBLIC 均无权限。

Cluster recovery process 已只从
`@qinglong/cluster-postgres/package-executor` 导入连接与 readiness，并只接受
`QL3_POSTGRES_PACKAGE_EXECUTOR_*`。CloudNativePG 清单固定六个数据库角色，恢复
Job 不再投影 `ql3_admin` credential。

### 5. 有界请求、配额和低敏响应

- request body 最大 256 KiB，JSON 深度、节点数、字符串和数组均使用现有 Package
  contract 上限；
- 认证前只使用进程内有界并发/连接/超时 shield，避免为匿名流量访问数据库；
- 认证后以 PostgreSQL 数据库时钟、Project+subject+operation key 执行 durable
  quota，多 Pod 共享同一裁决；
- mutation 必须使用 caller 提供的稳定业务 ID，但时间由认证后的 authority 生成；
- response 不回显 bearer/assertion、完整 Manifest、source locator、Registry
  credential、DSN、authentication ID 或底层数据库错误。

进程内 shield 不是分布式 rate limit，durable quota 也不能取代 ingress 层容量保护。

## Package 粒度影响

本决策不创建 `cluster-package-api` 一文件包。`cluster-admin` 已拥有独立镜像、Node
engine、Kubernetes/PostgreSQL 第三方闭包和管理供应链生命周期；新的 transport 是
同一部署域内的显式子路径。真正需要拆分的是运行时 credential、数据库 GRANT、
ServiceAccount 和 process，而不是再增加 workspace importer。

## 验证门禁

1. single-factor User 和 service principal 都不能 decide；
2. 同一 User propose+decide 在数据库 mutation 前拒绝；
3. 两名强认证 User 可完成 propose+decide，且 body 中不存在 principal；
4. 公开路由不存在 consume/dispatch，伪造 system consumer 失败；
5. manager role 无 installation/recovery/Kubernetes authority，executor role 无公开
   management route；
6. 多 Pod durable quota 使用数据库时间保持一致，COMMIT response loss 可重放；
7. 256 KiB body、并发、超时、低敏错误和 audit 门通过；
8. manager/executor role readiness、未知 GRANT 拒绝和 PostgreSQL HA promotion 后
   重新连接门通过；
9. management Kubernetes overlay 不挂载 Registry credential，RoleBinding 不含
   ConfigMap/Secret 写权限；
10. workspace importer 仍为 21，cluster-control/edge/worker 制品闭包不变化。

当前已经通过第 1、3、4、5、6、7、8、9、10 项的适用子集：

- 专用 assertion 已验证 EdDSA、ES256、RS256，固定 issuer/audience/purpose、
  ACR+AMR、短 lifetime 与 key-bound algorithm；签名篡改、unknown key、通用 JWT、
  weak RSA、额外 claim/header、过期/未来 token、弱 assurance、非 User 与空
  principal 都在 service 访问前失败；
- 公开 command union 不包含 consume/dispatch，未知 operation 在认证前失败；
- command body 不能携带 principal 或 authority time；proposal 半提交恢复复用
  durable `createdAtMs`；exact decision replay 不重复 mutation；
- 结果不回显完整 manifest、source locator、Secret permission 或 authentication ID；
- v24 migration、manager/executor exact readiness、旧 admin Package 权限否定、
  六角色 CloudNativePG 部署审计和 executor-only recovery binding 已通过；
- PostgreSQL 18.4 physical streaming fixture 已在原 primary 和 promotion 后的新
  primary 分别用 manager/executor credential 重新连接并通过 readiness；同一门还继续
  通过 fencing、`pg_rewind`、双控制副本恢复与既有 COMMIT-response-loss 矩阵。
- bounded keyset 已通过 overlap/revoke、rollback/rewrite、implicit removal、
  append-only revocation、malformed/private/oversized 与 no-stale-fallback 门；
- TLS 1.3 HTTPS host 默认 body 64 KiB、硬上限 256 KiB，并通过 auth-before-body、
  peer/global shield、并发、keyset unavailable、readiness withdraw 与 drain 门；
- management operation 固定双副本、零 ServiceAccount token/RBAC、独立 TLS/
  keyset/CA 投影、manager-only CloudNativePG credential、HTTPS probe、NetworkPolicy
  与 fail-closed admin image digest；两个 Kustomize 层均可实际 render。
- durable quota 使用数据库 `clock_timestamp()` 和单语句 UPSERT；同一 window 的
  receipt 与 count 共同行锁、最多 1000 项。PostgreSQL 18.4 HA fixture 已用两个独立
  manager 实例并发 16 个请求，精确 8 allow/8 reject；exact replay 不重复计数，
  autocommit response loss 后回读仍为 1，数据库时钟窗口可重置。
- durable keyset ledger 已以两个 manager 实例验证并发同代观察、全新 repository
  重启后的旧代拒绝、同代 rewrite/隐式移除拒绝，以及 COMMIT response-loss 后
  generation 3 精确收敛。

第 2、3 的真实双 User/实际 IdP 部分，以及第 7、9 项的真实双
Pod/ingress/rotation live evidence仍未完成。

## 后续

- 取得真实双 User、双 Pod、ingress/rotation 和权限否定证据；
- 在管理入口稳定后再实现 UI，UI 不复制 Policy/Approval 协议。