# ADR-0209：Owner 围栏化 Local Identity/Credential 管理与私有交付

- 状态：Accepted
- 日期：2026-07-29
- 关联 RFC：QL-RFC-0001 D-05、D-27、D-37、D-65、D-72、D-73、D-175、
  D-197、D-198、D-199
- 关联 ADR：ADR-0074、ADR-0075、ADR-0077、ADR-0086、ADR-0185、
  ADR-0193、ADR-0207、ADR-0208

## 背景

ADR-0208 已允许 Owner 管理既有 Identity 的 Project RoleBinding，但目标 Identity
和 API credential 仍主要由首 Owner bootstrap/recovery ceremony 创建。部署者缺少
一个受支持的产品入口来：

- 注册、启用或禁用 User/API App/MCP Client/Agent Identity；
- 为这些 Identity 签发、轮换或撤销 API credential；
- 在 CLI 返回丢失、进程崩溃或数据库已经提交时安全重放；
- 不经 stdout、argv、普通 audit 或数据库明文列交付新 token。

直接复用 cluster-admin 的“一次响应返回 token”协议不适合本机产品。数据库提交后
若响应丢失，重放只能看到 mutation 已存在，却无法恢复原 secret；重新生成 secret
又会与已提交 digest 冲突。

## 决策

### 1. 保持 22 个 package，不按文件数拆包或合包

本能力使用现有边界：

- `@qinglong/runtime-core/local-identity-credential-administration`：原子 repository
  contract、delivery acknowledgement 与低敏错误；
- `@qinglong/local-sqlite/identity-credential-administration`：一次命令、一个连接的
  SQLite composition；
- `@qinglong/local-admin/identity-credential-administration`：Owner-only Policy
  service；
- `@qinglong/local-owner-console/credential-administration-delivery`：私有 staged
  delivery；
- `@qinglong/local-owner-cli/identity-credential-command` 与 `ql3-identity`：
  private command-file 产品入口。

不新增第 23 个 package。`local-owner-console` 已是短生命周期、本机敏感交付边界；
交付实现放在其精确 subpath。`local-admin` 与 `local-sqlite` 分别保留领域授权和
事务存储责任。不能因为其中某个实现当前只有一个文件，就把高权限代码合并进常驻
application/Profile。

### 2. v1 操作与输出

`ql3-identity` 只接受 current UID、`0600`、bounded private command file，开放：

- `identity.register|enable|disable`；
- `credential.issue|rotate|revoke`；
- `credential.delivery.acknowledge`。

每个 mutation 使用 expected-current-version CAS、UUIDv4 mutation ID、request ID
和独立 failure-audit UUID。签发/轮换请求传入稳定 `lifetimeMs`，而不是把 secret、
token 或 pepper 放入 command。

成功输出只含 Project、target、version/state、`inserted|existing`，以及签发/轮换
时的 ready file name 和 delivery digest。输出不得包含 token、secret、pepper、
数据库路径或交付目录绝对路径。

### 3. 只有当前强认证 Owner 可以管理 Identity/Credential

CLI 复用 Owner credential presentation、pepper provenance 与 POSIX proof 生成
`local_console` User Principal。服务固定请求 Owner-only `project.manage`：

- admin/operator/viewer 不能注册 Identity 或签发 credential；
- deny/approval/unavailable 只记录低敏 audit；
- transport 不能直接调用普通 Identity/Credential repository 绕过 Policy。

SQLite `BEGIN IMMEDIATE` 取得写锁后再次验证：

1. actor credential version/state、User status、有效期、pepper state/material digest；
2. Project active/version；
3. actor 最新 RoleBinding version/state/owner role；
4. target Identity/credential expected version 与 mutation replay；
5. Owner 连续性。

Identity/Credential revision、管理 mutation、delivery digest 与 allowed audit 同成同败。

### 4. Owner 连续性是数据库不变量

- 仍有任一 Project 最新 active Owner binding 的 User Identity 不能被禁用；
- 撤销 active Owner 的 credential 时，必须存在该 User 的另一把当前有效 credential；
- 有效 credential 必须同时满足 active revision、时间窗、pepper binding 和
  active/retired catalog provenance；
- Issue/rotate 只能指向 active Identity 和当前 active pepper。

因此 operator 必须先签发并验证替代 credential，再撤销旧 credential；不能通过
禁用 Identity 或撤销最后凭据把部署锁死。

### 5. 凭据交付使用 prepare → commit → publish → acknowledge

交付目录必须是规范化、非 symlink、current UID、`0700` 目录，最多 64 个受审条目。
文件必须是 current UID `0600` regular file，并经过 `lstat → O_NOFOLLOW open →
fstat` 身份复核、file fsync 和 directory fsync。

协议顺序：

1. `prepare` 先以 no-replace 方式写 durable pending record；其中包含新 secret，
   但不进入数据库；
2. 对完整 pending record 计算 domain-separated SHA-256 delivery digest；
3. SQLite transaction 把 credential secret digest、delivery digest、mutation 和
   audit 原子提交；
4. commit 成功后才发布可直接作为 `credentialFilePath` 使用的 ready presentation；
5. consumer 验证/接管 ready presentation 后，执行
   `credential.delivery.acknowledge`；
6. acknowledgement 与 audit 先在数据库原子提交，再删除 ready 和 pending。

pending/ready 名称只由 mutation UUID 派生。acknowledgement 删除具备 exact digest
复核，文件均已不存在时返回 `absent`，支持 response-loss replay。

### 6. 崩溃与重放语义

| 崩溃窗口 | 同一 command 的恢复行为 |
| --- | --- |
| pending 后、数据库前 | 复用 pending 中原 secret 与首次有效期 |
| 数据库 commit 后、ready 前 | exact replay 后发布同一 ready token |
| ready 后、CLI response 前 | 返回同一 file name/digest，不生成新 secret |
| acknowledgement commit 后、删除前 | replay acknowledgement 后继续 exact 删除 |
| 删除后、ack response 前 | 返回 `existing + absent` |

mutation 的首次 durable timestamp 是 replay authority。时间推进、target 后续状态变化
或 CLI 重启不能让一个已经提交的相同 mutation 失去可重放性；但不同 operation、
target、version、lifetime、digest 或 request identity 必须冲突失败。

### 7. SQLite capability v36

`0071-local-identity-credential-administration` 增加：

- `QingLong3IdentityAdministrationMutations`；
- `QingLong3ApiCredentialAdministrationMutations`；
- `QingLong3ApiCredentialDeliveryAcknowledgements`；
- credential/credential-version/pepper-key 的唯一 provenance index。

`0072-capability-v36` 把 `local-control-core` 推进至 36，并声明
`local_identity_credential_administration=1`。read/write contract、Compose image
label、rollout/restore evidence 与物理 Edge contract 同步为 36。readiness 只接受
迁移 authority `0071` 与精确 capability JSON。

## 低配路由器与集群影响

- 命令只在人工调用时加载，结束后关闭 SQLite 和文件 authority；
- 不新增 daemon、timer、watcher、listener、socket、线程或第三方依赖；
- 常驻 Edge/Standalone application closure 不导入 Owner CLI、delivery、
  local-admin mutation service 或 executable migration；
- 新增三张 append-only 小型管理表，但 credential 明文只短暂存在于有界私有交付
  目录，不进入 SQLite；
- Cluster 继续使用 PostgreSQL、Kubernetes/RBAC 和独立远程 credential delivery；
  本地 POSIX 文件协议不能成为 cluster transport。

## 不采用方案

### 在 stdout 返回一次 token

响应丢失后无法恢复已提交 secret，并会把 token 暴露给 shell history、日志采集和
父进程管道。

### 数据库保存可恢复明文 secret

扩大数据库备份、查询和运维面的明文 authority，也让 runtime storage 获得不需要的
secret delivery 权限。

### 提交后重新生成 secret

新 secret 与已提交 digest 不一致；静默覆盖会破坏认证和审计的 mutation identity。

### 新增 identity-admin package 或常驻管理 API

没有新的独立部署、第三方依赖或常驻 Profile 边界，会增加 workspace 碎片和路由设备
攻击面。现有 package 的精确 subpath 已能表达权限。

## 验收证据

- 真实 SQLite/CLI 2/2：完整 register → issue → exact replay → acknowledge →
  revoke → disable，并验证 Owner Identity/最后 credential 防锁死；
- staged delivery 2/2：首次 secret/有效期重放、`0600` ready、digest-bound cleanup、
  symlink 与语义漂移拒绝；
- local-admin replay 1/1：时间推进且 Identity 状态已不可重读时仍以 durable mutation
  exact replay；
- SQLite migration/readiness/rollout 20/20，`PRAGMA foreign_key_check` 为空；
- local deployment/rollout/restore 23/23，local image contract audit 通过；
- runtime-core、SQLite、local-admin、delivery 与 CLI strict targeted TypeScript
  编译通过；
- dependency audit 对新增 source 的 exact-import findings 为零，workspace 仍为
  22 package。

完整 workspace build、production artifact/RSS 和 PostgreSQL HA 仍依赖锁文件依赖
恢复；上述专项证据不能替代这些发布门。

## 后续

- bounded Identity/Credential list/inspect 与低敏 audit 查询；
- 未确认 delivery 的显式过期/回收 ceremony；
- credential 使用验证后再 acknowledge 的产品引导；
- Project create/archive；
- Cluster PostgreSQL 对等 Identity/Credential 管理 transport；
- 固定 Edge 设备上的 CLI peak RSS、SQLite 写入和断电恢复报告。