qinglong/docs/adr/ADR-0264-dedicated-cluster-model-provider-credential-management-boundary.md

# ADR-0264：独立 Cluster Model Provider Credential 管理边界

- 状态：Accepted
- 日期：2026-08-02
- 关联：RFC D-08、D-12、D-85、D-159；ADR-0169、ADR-0263

## 背景

ADR-0263 已交付 append-only Provider credential catalog、durable use audit、只读
projected material 和显式 Cluster AI composition，但 binding 配置仍没有产品管理 ceremony。
直接让常驻 control 或通用 `ql3_ai_maintenance` 执行 binding mutation 都不合理：

- control 会从 runtime read/audit authority 升格为 credential mutation authority；
- `ql3_ai_maintenance` 同时拥有 Prompt output GC/key-retirement 权限，常驻管理服务复用它会
  取得与 credential binding 无关的 Artifact 删除能力；
- 只在 HTTP 层检查 Policy、再用 raw repository 写 transition，会留下授权撤销 TOCTOU 和
  mutation 已提交但允许审计缺失的窗口；
- 请求体自报 actor、Policy decision 或 fence 无法形成可信产品入口。

## 决策

### 1. 使用独立数据库角色但不新增 workspace package

CloudNativePG 增加 `ql3_ai_credential_manager`，connection limit 为 4。该角色只取得：

- `ql3.projects`、`ql3.project_role_bindings`、`ql3.security_audit_events` 的 SELECT；
- `ql3.security_audit_events` 的 INSERT；
- `ql3_ai.ai_schema_migrations`、credential binding/transition/use-audit 的 SELECT；
- credential binding/transition 的 INSERT。

它没有 UPDATE/DELETE、schema CREATE、Prompt output、price catalog、invocation、runtime、
Worker、Package 或 migration authority。`pg-9013` 只追加这一 ACL boundary，不修改
`pg-9001`–`pg-9012` checksum。`pg-9014` 再增加固定
`model-provider-credential-management` authority 的 identity keyset ledger；manager 只有
SELECT/INSERT/UPDATE，没有 DELETE，`ql3_ai_maintenance` 也不能读取或改写它。

### 2. Credential transition 与允许审计必须同事务

`@qinglong/ai/model-provider-credential-administration` 定义 authorized mutation：

- catalog command；
- server-derived User actor；
- exact Project/RoleBinding fence；
- operation/project/actor/authentication/fence-bound allowed SecurityAudit。

PostgreSQL repository 的 `commitAuthorized` 在同一 SERIALIZABLE transaction 中取得
Project+Provider advisory lock，复验 active Project 与当前 User binding fence，执行 generation
CAS，append immutable binding/transition 和 SecurityAudit，再统一 COMMIT。exact replay 必须
同时匹配 catalog command 与原 authorization audit；孤立 audit、孤立 transition、身份漂移、
generation 漂移和 fence 漂移都失败关闭。

raw `commit` 暂时保留给 migration/HA 证据和受控内部测试，但产品 composition 只能取得
`commitAuthorized` repository。

### 3. Cluster Admin facade 不接受调用方 authority

能力留在现有 `@qinglong/cluster-admin`：

- 只接受五分钟内的 MFA/hardware User；
- 固定对 exact Project 请求 `secret.manage`；
- actor、`changedBy`、Policy decision、reasons、fence 和 audit 全由服务端派生；
- bind 固定 `bearer` scheme 并要求 canonical Project-bound SecretRef；
- revoke 不接受 binding/material；
- transport 只返回 Project、Provider、generation、active revision/digest、transition digest 和
  时间，不返回 SecretRef、Secret name、token、header 或 raw error。

transport 暴露 `provider-credential.bind|revoke|audit.list`。audit query 复用同一强 User、
`secret.manage` 和 Project/RoleBinding fence，但只返回 bind/revoke 的 actor、fence、时间与游标；
查询访问审计与读取 snapshot 在同一 SERIALIZABLE transaction 中提交。inspect 和 test
connection 在取得同等级隔离执行、rate/quota 与 content-free response 门之前保持关闭。

### 4. 产品部署已实现但保持默认关闭

以下接受门已经全部完成：

1. ~~独立 TLS 1.3/mTLS + purpose-bound OIDC management process；~~ 已完成，断言使用独立
   JWT type/purpose/audience，keyset generation/revocation 由 `pg-9014` 耐久围栏；
2. ~~bounded HTTP body/concurrency/peer/rate limit 和 caller-driven client；~~ 已完成，固定
   `/api/v3/provider-credentials/management`，认证先于 body，客户端零自动 retry；
3. ~~opt-in Kubernetes Deployment、NetworkPolicy、PDB、独立 Secret/CA 与 digest-pinned admin
   image；~~ 已完成，双副本 manager 与 caller-driven Job 均不进入默认 operations；
4. ~~PostgreSQL 真库最小 ACL、COMMIT-response-loss、并发单赢家和 physical HA 晋升证据；~~
   已由 PostgreSQL 18.4 arm64 HA 门完成；
5. ~~content-free audit query 与明确不保存/返回 SecretRef 的检查；~~ 已完成，固定只读
   bind/revoke operation，单页 1–32、降序 keyset；响应删除 Provider/SecretRef、binding/transition
   digest 与 authentication identity，查询访问审计和 authorization fence 复验同事务；
6. ~~test connection 的 provider allowlist、deadline、零 retry、audit-before-network 和费用/限流
   预算，或继续保持关闭。~~ 已由 ADR-0265 完成：manager 只签发 server-derived content-free
   plan，独立 one-shot tester 才能读取投影 Secret 和访问 exact provider endpoint。

## 被否决方案

1. **复用 `ql3_ai_maintenance`**：把 credential manager 扩权到 Prompt Artifact 删除。
2. **复用 Cluster Control runtime role**：让常驻请求处理进程取得 binding mutation。
3. **新建 credential-manager workspace package**：部署差异由同一 admin image 的独立
   entrypoint/Deployment 表达，代码仍属于已有能力包，不满足第 20 个 importer 门。
4. **只写 transition、不写允许审计**：无法证明谁在什么 Project fence 下授权。
5. **先 audit 后独立写 transition**：崩溃会产生虚假允许事实或未审计 mutation。
6. **提前开放 inspect/test**：会绕过尚未完成的审计、网络和 Provider 费用边界。

## 当前验证

- AI 全量 176 项：173 通过、3 条外部 PostgreSQL 条件跳过；
- Cluster Admin 全量 242 项：240 通过、2 条外部条件跳过；
- 新增 administration/facade/transport/process/HTTP/client 定向门全部通过；
- dependency audit `findings=[]`，workspace 保持 19；
- CloudNativePG deployment/backup/DR 静态门 24/24；
- `pg-9013` checksum：
  `c02a4c6b2953cc331580b6287283d33739c30c2e189d011f392c13ecea497224`；
- `pg-9014` checksum：
  `02098fad764199bc5a7750483d050be5e5acdbcecd05c0975c3fe4e5be03c782`；
- PostgreSQL 18.4 arm64 physical HA 门完成 `remote_apply`、timeline 1→2、旧主 fencing、
  `pg_rewind` 只读重入和 fresh controls，总 gate `passed=true`；credential management 子门
  证明 4 条 content-free SecurityAudit、bind/revoke/rebind、同 generation 双 manager 并发单赢家、
  陈旧 CAS 拒绝、COMMIT-response-loss exact replay、专用 manager ACL 和旧 maintenance deny，
  且晋升后全部存活；同轮还证明两个 manager 对 identity generation 竞争收敛、回滚/同代改写/
  隐式移除拒绝、COMMIT-response-loss 恢复和 generation 3 跨晋升存活；
- manager 与 client 两套 Kustomize 均可渲染；独立 deployment audit 正向与 pool 扩权负向
  2/2，dependency audit `findings=[]`；
- content-free audit query 定向 3/3，facade/transport/client/process 联合定向 18/18；PostgreSQL
  18.4 arm64 HA 进一步证明 4 条管理记录的两页 keyset、2 条访问审计、COMMIT-response-loss
  exact replay，以及 timeline 1→2 后重放不新增 WAL/审计且响应仍不含 SecretRef、Provider、
  authentication identity 或 transition/binding digest；
- 首次真库运行发现并修复 migration plan 已登记 `pg-9013`、history identity 白名单漏登记的
  fail-closed 漂移；
- ADR-0265 的受预算 test connection 已完成纯协议、manager plan/quota、one-shot executor、
  Kubernetes 静态部署边界和 PostgreSQL 18.4 physical HA 证据；真实外部 IdP、证书轮换、
  provider 网络与多节点 Kubernetes 纵切面仍是发布证据，因此 Accepted 只表示架构决策与当前
  实现门闭合，不表示 credential management 已可生产使用。