qinglong/docs/adr/ADR-0210-owner-fenced-local-identity-credential-inspection.md

ADR-0210：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、D-200
• 关联 ADR：ADR-0074、ADR-0075、ADR-0077、ADR-0086、ADR-0185、 ADR-0207、ADR-0208、ADR-0209

背景

ADR-0209 已提供 Identity/Credential mutation 的产品入口，但每次 mutation 都要求 expectedCurrentVersion。部署者若只能直接查询 SQLite 才能取得该版本，会产生三个 问题：

• 运维流程必须知道存储表结构，产品契约与实现泄漏；
• 普通 credential 行包含 secret digest 和 pepper provenance，直接查询扩大敏感面；
• 查询没有复用 Owner authorization、credential fence 与 Security Audit。

单纯在服务层 authorize 后调用普通 resolve 也不安全。actor credential 或 Owner RoleBinding 可能在 authorization 与读取之间变化，造成已撤权主体继续读取管理状态。

决策

1. 扩展既有边界，不新增 package 或 migration

能力分别进入既有精确 subpath：

• runtime-core 定义 authorized inspection repository contract；
• local-admin 提供 Owner-only inspection service；
• local-sqlite 实现事务围栏读取与 audit；
• local-owner-cli 在既有 ql3-identity 增加产品命令。

不新增第 23 个 package、数据库表、第三方依赖、daemon、timer、watcher、listener 或 远程管理 API。Edge/Standalone 常驻 application closure 不导入该 authority。

2. v1 只提供精确查询

开放：

• identity.inspect：按 exact {subject.type, subject.id} 查询；
• credential.inspect：按 exact credential ID 查询。

command 使用 current UID 0600 private file。request 只包含 projectId、target 或 credential ID、requestId 和 UUIDv4 auditEventId。查询不是 mutation，不接受 mutation ID、failure-audit ID 或 expected version。

本切片不提供 list/search/pagination。精确查询足以获得后续 CAS 所需版本，同时避免 为低配设备引入目录扫描、游标状态或大结果集。

3. Owner authorization 与读取在最终事务重新围栏

服务要求 strong User Principal，并固定申请 project.manage。deny、 approval-required 和 policy-unavailable 先写低敏 audit，再返回统一错误。

SQLite 使用 BEGIN IMMEDIATE，在读取前重新验证：

1. 本命令认证 credential 的 version/state、Identity、时间窗与 pepper provenance；
2. Project active 状态和 Policy fence project version；
3. actor 最新 RoleBinding 的 version/state/Owner role。

随后读取最新 Identity 或 credential revision、写入 allowed audit，并一次提交。任一 围栏漂移都回滚读取对应的 allowed audit，并失败关闭。

4. 不存在语义和输出必须低敏

只有完成 Owner authorization 与事务围栏后，精确对象不存在才返回 found:false。 未授权请求不得根据对象是否存在返回不同结果。

允许输出：

• Identity：subject、status、version、created/updated time；
• credential：ID、subject、subject status、state、version、created/not-before/ expires time。

禁止输出 secret digest、pepper key ID、token、credential presentation、数据库路径、 绝对交付路径或内部 mutation/audit 行。

替代方案

直接提供 SQLite 查询文档

拒绝。它把 schema 变成产品 API，绕过权限与 audit，并暴露本来无需展示的敏感列。

authorize 后调用普通 repository resolve

拒绝。authorization 与读取不共享最终数据库 transaction，存在 credential revoke 或 Owner demotion TOCTOU。

新建只读管理 daemon 或 HTTP API

拒绝。当前需求是本机短生命周期运维；常驻进程会增加路由设备内存、端口和攻击面， Cluster 也有独立 transport/authority。

立即提供 Identity/Credential list

暂不采用。list 需要分页、稳定 cursor、容量与枚举策略；精确 inspect 已解决 CAS 版本发现，不应扩大本切片。

影响

正向影响：

• 部署者不再直接访问 SQLite 即可完成 inspect → CAS mutation；
• 查询与 mutation 使用相同 Owner、credential 和 Policy fence；
• 已授权 not-found 有明确机器可读语义，输出不暴露 credential 验证材料；
• 低配设备没有新增常驻成本，workspace 保持 22 package。

代价与限制：

• 每次 inspect 都是短写事务，因为 allowed audit 必须与读取 authority 同事务；
• 相同 auditEventId 不作为可重复消费的查询 cursor，重复人工执行应生成新 command；
• v1 不支持批量列表，operator 必须知道 exact subject 或 credential ID；
• Cluster 仍需独立实现 PostgreSQL/RBAC 查询 transport。

验证

• strict targeted TypeScript 编译覆盖 runtime contract、local-admin、local-sqlite 与 CLI；
• service 测试证明 Owner allow、admin/non-Owner deny 与 deny audit；
• 真实 SQLite/CLI 测试证明 Identity/Credential 当前 version、已授权 found:false、allowed audit 与低敏 JSON；
• TOCTOU 测试在 policy authorize 后追加较新 non-Owner binding，最终 transaction 必须抛出 authorization fence conflict；
• dependency audit 继续证明能力没有进入 Edge/Standalone 常驻 closure；
• 完整 workspace、artifact/RSS 与 PostgreSQL HA 门在锁定依赖恢复后重跑。