qinglong/docs/adr/ADR-0175-private-authenticated-local-model-price-catalog-cli.md

# ADR-0175：私有认证 Local Model Price Catalog CLI

- 状态：Accepted
- 日期：2026-07-27
- 关联：RFC D-49、D-73、D-84、D-85、D-156、D-162、D-163、D-164、D-165；ADR-0085、ADR-0143、ADR-0167、ADR-0173、ADR-0174

## 背景

ADR-0174 已完成授权型 Model Price Catalog facade、双方言 9006 原子授权事实与
Profile 决策模式，但本机用户仍没有受审产品入口。若直接把 repository 暴露给脚本，
调用方就可以伪造 actor、Policy、assurance 或授权结果；若让常驻 edge runtime 或
`local-admin` 根入口静态导入 AI，则禁用 AI 的路由设备仍要支付模块加载和制品成本。

本机入口还存在两个真实竞态：

1. local-console 在事务外验证 credential 后，credential、pepper、User 或 Owner
   binding 可能在 catalog transaction 开始前被撤销；
2. 同一私有命令文件在进程退出或响应丢失后重试，会建立新的认证时间窗。若把该时间
   漂移当作 durable authorization 漂移，已经提交的命令无法安全收敛。

AI migration 是显式 feature stream。产品 CLI 不能为了“方便”在运行时自动执行
9001–9006 DDL，否则只读检查、低资源设备和生产变更控制都会失去边界。

## 决策

### 1. 复用现有短生命周期 CLI package

在现有 `@qinglong/local-owner-cli` 增加：

- 显式子路径 `@qinglong/local-owner-cli/model-price-command`；
- 二进制 `ql3-model-price`；
- `model-price.publish|activate|deactivate|revoke|inspect` 五种 operation。

不新增 workspace package、第三方依赖、daemon、listener、timer、watcher、缓存或数据库
连接。只增加 `local-owner-cli → @qinglong/ai` workspace 依赖；通用
`local-admin`、`cluster-admin`、默认 edge/standalone runtime 和基础制品不得反向导入
AI。命令执行完成后关闭单一 SQLite authority。

CLI 只接受：

```text
ql3-model-price run --command-file /absolute/private-command.json
```

命令文件必须是私有、规范化、有界绝对路径上的 exact-shape JSON。body 只能包含公开
intent、CAS fence、幂等 ID 和失败审计 event ID，不得包含 principal、subject、
authentication ID、assurance、Policy、decision mode、catalog/result digest 或任意
authority seam。输出只含 publication/head 与低敏授权摘要，不返回 credential、
principal 或认证 ID。

### 2. 显式 feature activation，运行时不执行 DDL

入口打开已经通过主 SQLite readiness 的数据库后，只读核对：

- 9001–9006 六条 AI migration history、stream identity 与 checksum；
- 11 张 Model Invocation/Price Catalog 业务表；
- 独立 `QingLong3AiSchemaMigrations` history 表。

任一缺失或漂移均以 `LOCAL_MODEL_INVOCATION_FEATURE_NOT_READY` 失败，并且在认证前停止。
CLI 不创建、修补或迁移 schema。部署者必须通过受审 feature activation ceremony 先行
执行 AI migration。

### 3. 本机强认证与平台 Owner 资格

所有 operation 复用 local-console POSIX/private-file proof、API credential、
credential-version pepper provenance 和 `local_console` assurance。请求不得指定 User。

edge/standalone 当前以 `default` Project 的最新 active `owner` binding 证明该本机 User
是产品平台 Owner。这个 binding 只作为本机 operator 资格证据，不把价格数据变成
Project-scoped 资源：catalog、Policy、authorization 和 resolver 中仍不存在 Project ID。
`inspect` 也要求当前 Owner，避免该管理入口成为普通本机 User 的旁路。

本机平台 Policy 固定为：

- revision `local_console_platform_owner_v1`；
- allow reason `local_console_confirmed`；
- decision mode `human_confirmation`。

Policy、assurance、principal 和 result digest 均由受信 composition 派生。

### 4. SQLite transaction 内二次围栏

`publishAuthorized`/`transitionAuthorized` 在取得 `BEGIN IMMEDIATE` 后、读取 replay 或
写入任何 catalog/authorization 行前调用同步 transaction hook。hook 在同一 connection
和 transaction 内精确复验：

- credential ID/version、active state、secret digest 与有效期；
- active User identity；
- credential-to-pepper binding、active/retired pepper state 与 material digest；
- `default` Project active 状态和该 User 最新 active Owner binding。

任一撤销、版本、摘要、时间或角色漂移都回滚 publication/head/authorization 全部写入。
进程时钟和事务外 `confirm()` 只用于早拒绝，不能代替数据库 fence。

### 5. 成功事实、失败审计与重放

成功 mutation 继续只由 9006 authorization 与 publication/head 在同一事务证明。
transport 不先写一条“成功 security audit”，避免双事务裂缝。

下列失败写入现有低敏 `QingLong3SecurityAuditEvents`：

- credential authentication rejection；
- credential/User/pepper transaction fence rejection；
- 当前平台 Owner 资格 rejection；
- Policy deny 或 quota deny。

审计只保存 caller 提供的独立 event ID、request/operation、nullable authenticated
subject/authentication ID、固定 outcome/reason 和本地时间；不保存 token、secret、
价格 body、stack 或 raw error。相同失败 event ID 的精确重放忽略观察时间差并收敛为
一条事实。

对于已提交 mutation，同一 authorization/request/catalog command、同一 User、同一
credential proof authentication ID、assurance、Policy 和 decision mode，可以在当前
transaction fence 再次通过后使用新的认证时间窗重放。repository 返回首次提交的不可变
authorization，不重写其时间或摘要；不同 User、authentication proof、Policy、ID 或
catalog command 仍然 conflict。

## 拒绝方案

1. **新增 `ql3-model-price-cli` package**：没有独立部署或权限边界，只会继续制造单文件
   package，拒绝。
2. **把 CLI 放进常驻 edge runtime**：会扩大默认导入闭包和攻击面，拒绝。
3. **由 CLI 自动运行 AI migration**：把产品调用升级为 DDL authority，拒绝。
4. **只做事务外 local-console confirm**：无法关闭撤权竞态，拒绝。
5. **把调用方 body 当作 Policy 或 User 来源**：可伪造授权，拒绝。
6. **把价格目录挂到 `default` Project**：全局 catalog 会形成虚假租户边界，拒绝；
   Owner binding 只证明本机 operator 资格。
7. **因新认证时间窗拒绝已提交重放**：会让响应丢失无法收敛，拒绝。
8. **用新认证覆盖首次授权事实**：会改写历史，拒绝。
9. **现在开放 Cluster CLI/HTTP**：尚无 TLS identity assertion、平台 Policy
   repository、耐久 quota 与双人 ceremony，拒绝。

## 当前证据

- `@qinglong/ai` 92 项：90 pass，2 条真实 PostgreSQL 条件 skip；新增 AI readiness、
  transaction hook 与 fresh-reauth replay 测试；
- `@qinglong/local-owner-cli` 16/16，覆盖 publish replay、activate、inspect、真实
  product binary、无敏感输出、未激活 schema、widened body、认证失败审计精确重放、
  过期强认证、precheck 后 credential revoke 和非 Owner rollback；
- 受影响 AI/local-sqlite/local-owner-console/local-owner-cli 均通过 TypeScript build；
- 22 个 QL3 package 已完成干净全量 build/test，0 fail；22-importer dependency audit
  覆盖 AI 20 个、Owner CLI 8 个源码文件且 `findings=[]`，edge 121-module import gate
  无 AI/cluster 越界；
- 默认 edge/standalone 仍为 3,910,465/3,910,525 bytes、478 files；显式
  edge-ai/standalone-ai 为 4,555,506/4,555,578 bytes、520 files。禁用态三个 Profile
  的 storage/provider/management loader 全为 0，模块加载 RSS 增量 475,136 bytes；
- PostgreSQL 18.4 arm64 physical HA 总门通过：9001–9006、11 张 AI 表和最小 ACL
  在 timeline 1→2 后一致，physical streaming、`remote_apply`、partition guard、
  fencing、promotion、`pg_rewind` rejoin 与全部 domain gate 为 true；临时 Docker
  资源已清理；
- workspace 仍为 22 个 QL3 package；没有新增第三方生产依赖或长期资源。

## 后续门禁

1. 独立、显式的 AI feature activation/deactivation 产品 ceremony（ADR-0176 已完成）；
2. 私有命令模板、operator 文档、备份/恢复和真实低配 Linux 设备证据；
3. Model Price Catalog mutation 专属 SQLite crash/COMMIT-response-loss 矩阵；
4. Cluster TLS/identity assertion、平台 Policy repository、耐久 quota、双人发布/激活
   ceremony 与 deny/unavailable audit；
5. Cluster 产品入口完成后重新运行 PostgreSQL 三角色 integration 与 physical HA 门。

## 后续状态

第 1 项已由 ADR-0176 完成：本机 9007 append-only active/inactive head、
`ql3-ai-feature`、migration plan/data-safety fence、Owner transaction fence 和
invocation/price 写事务内 active fence 已实现。其余门禁保持不变。