qinglong/docs/adr/ADR-0215-instance-owner-fenced-bounded-local-security-audit-query.md

ADR-0215：实例 Owner 围栏化、有界的 Local Security Audit 查询

• 状态：Accepted
• 日期：2026-07-29
• 关联 RFC：QL-RFC-0001 D-05、D-27、D-37、D-65、D-72、D-73、D-175、 D-198、D-200、D-201、D-203、D-204、D-205
• 关联 ADR：ADR-0049、ADR-0074、ADR-0208、ADR-0211、ADR-0213、ADR-0214

背景

QingLong 3.0 的本机管理入口已经为 Secret、Identity、Credential、Project 和 RoleBinding 的允许、拒绝与最终围栏失败写入 durable security audit，但部署者仍没有 受支持的读取入口。直接查询 SQLite 会把内部 schema 变成产品 API，绕过强认证、 authority、字段脱敏和有界资源契约。

审计记录横跨整个实例，可能包含 Project 拓扑、subject、操作结果和认证关联信息。 它不是普通的 Project-scoped 业务数据，任意 secondary Project Owner 不应因为拥有 自己的 project.manage 就能枚举其他 Project 的安全事件。

决策

1. 在既有 package 内增加独立 subpath 和短生命周期 CLI

新增：

• @qinglong/runtime-core/local-security-audit-query；
• @qinglong/local-sqlite/security-audit-query；
• @qinglong/local-admin/security-audit-query；
• @qinglong/local-owner-cli/security-audit-query-command；
• 一次命令、一次进程的 ql3-audit binary。

这些是已有 package 内的能力边界，不是新的 workspace package。查询不进入常驻 application，不创建 daemon、timer、watcher、listener、连接池、缓存或端口。SQLite contract 保持 v37，workspace 保持 22 个 package。

2. 只有实例 authority Project 的当前强认证 User Owner 可以查询

request 必须携带 authorityProjectId。local-admin 固定以 project.manage 请求 Owner-only decision；SQLite 在同一个 BEGIN IMMEDIATE 内重新验证：

1. authenticated credential、Identity、有效期和 pepper provenance；
2. ADR-0211 instance authority anchor；
3. authority Project 的 active/version；
4. actor 最新 active Owner RoleBinding/version。

secondary Project Owner、admin/operator/viewer、非 User principal 和 foreign authority Project 全部失败关闭。服务授权后 credential、anchor、Project 或 RoleBinding 漂移时，最终事务拒绝且不得提交 allowed audit。

3. 查询形状固定且有界

security.audit.list 复用共享 security audit query 的精确语义：

• limit 为 1–64；共享 Cluster 上限 200 不改变本机更严格上限；
• filter 只允许可选 projectId、精确 subject、精确 outcome；
• cursor 精确为 {occurredAtMs,eventId}；
• 排序固定为 (occurredAtMs DESC,eventId DESC)；
• SQLite 读取 limit + 1，只有实际存在额外记录才返回 nextCursor。

禁止 offset、任意排序、模糊搜索、调用方 SQL、无界数组或历史全量 export。每一页是 一次独立授权、独立审计的 SQLite snapshot，不承诺跨 command 的同一时点视图。

4. 查询与自己的 allowed audit 原子提交

SQLite 先在事务内完成 authority 复验和查询，再写本次 security.audit.list allowed audit，最后 commit。因此返回的 snapshot 不包含本次查询事件；查询成功和审计写入 仍保持原子性。

翻页必须使用新的 request ID 和 audit event ID。查询不是 mutation receipt；不得以 重放旧 audit event ID 的方式请求下一页。

5. 产品输出必须脱敏

ql3-audit 只输出：

• event/request/operation identity；
• nullable Project；
• nullable subject；
• outcome、reasons、nullable policy fence；
• occurred timestamp；
• nullable next cursor。

即使 durable row 中存在，也不得输出 authenticationId。同样不得输出 credential、 pepper、Secret、路径、command 内容或数据库内部字段。认证失败和最终围栏失败只写 低敏 failure audit。

不采用方案

直接开放只读 SQLite 或通用 SQL

拒绝。它无法约束字段、行数、排序、authority 或审计，并把 schema 演进变成外部兼容 承诺。

让每个 Project Owner 查询自己 Project 的原始审计

拒绝。当前 security audit 还包含 nullable/global 和实例管理事件，没有独立的 Project 安全视图、行级投影或字段级 redaction contract。需要时应另行设计 Project-local projection，而不是弱化实例审计 authority。

一次返回全部记录或实现 export

拒绝。Edge 路由设备的内存、闪存和终端输出必须有硬上限。合规 export、签名、保留期 和销毁证明是后续独立能力，不能伪装成大页查询。

新建 audit package 或常驻管理服务

拒绝。该能力与既有 runtime contract、单 SQLite authority、local-admin 和 Owner CLI 共享部署生命周期；新 package/daemon 只会增加低配设备的供应链和空闲成本。

影响

正向影响：

• 部署者不再需要直接读取 SQLite 才能诊断拒绝和围栏失败；
• 实例级审计 authority 与 Project-scoped RoleBinding authority 明确分离；
• 64 条硬上限、keyset 和精确 filter 约束内存、CPU 与输出；
• 同事务 final fence 防止 credential/Policy TOCTOU；
• CLI 删除 authenticationId，避免认证关联标识进入终端或脚本输出；
• 不新增 migration、package、生产依赖或常驻资源。

代价与限制：

• 每页查询都会短暂取得 SQLite write reservation，以原子写查询审计；
• 当前不提供 operation filter、时间范围、聚合、export、retention、签名或告警；
• 每页是独立 snapshot，翻页期间的新事件可能改变后续结果；
• Cluster 继续使用独立 PostgreSQL management authority 和更高的共享页上限。

验证

• GitNexus：共享 normalizeSecurityAuditQuery 上游风险 LOW；高风险 LocalSqliteRunRepository（17 个直接、45 个总上游）未修改，D-205 使用独立 repository/composition；
• D-205 五个新源文件通过隔离 strict TypeScript，启用 exactOptionalPropertyTypes 与 noUncheckedIndexedAccess；
• 定向测试 8/8：
  • instance Owner 授权与 filter/cursor 透传；
  • limit 65 在 repository 前拒绝；
  • non-Owner denial audit；
  • service 后 final policy/credential fence conflict 保留；
  • 真实 SQLite limit + 1、两页降序 keyset 和末页 null cursor；
  • query snapshot 不包含自己的 allowed audit；
  • foreign instance authority 在读取/allowed audit 前拒绝；
  • CLI 删除 authenticationId 并审计 credential fence failure；
• SQLite contract 保持 v37，workspace 保持 22 package；
• 完整 package closure 与 PostgreSQL HA Docker 门仍需在锁定依赖物化后重跑。

后续状态

ADR-0216 已在 SQLite v38 完成实例 Owner 围栏化、64/512 条硬上限的诊断审计压缩。 它只回收无已知引用的拒绝/失败事件和精确只读查询事件；完整领域 retention、签名 export、远端归档与合规销毁证明仍未完成。