ADR-0519：Local Console Secret-backed 自动化

状态：Accepted（D-424 双架构 milestone 已交付）
日期：2026-08-29
对应 RFC 切片：D-424
关联：ADR-0069、ADR-0071、ADR-0512、ADR-0516、ADR-0517、ADR-0518

背景

D-423 已让部署者在 Local Console 创建 command Task 并配置 cron Trigger，但需要凭据的自动化仍只能借助受信 CLI。QingLong 3.0 已有 AES-256-GCM Secret custody、immutable version、pinned SecretRef、Task execution-time materialization 和 durable audit；缺口是一个不会暴露明文或复制密钥 authority 的有界产品入口。

该入口必须同时适配小路由设备和普通单节点：默认 headless 不承担 Console/API 成本，opt-in Console 不增加连接、迁移或后台生命周期。Cluster 必须继续使用自己的共享 Secret custody 和 HA authority，不能复用 Local SQLite/POSIX proof。

决策

1. 列表只暴露当前版本元数据

新增固定路由：

GET /api/v3/projects/:projectId/secrets
PUT /api/v3/projects/:projectId/secrets

GET 使用按名称排序的稳定 keyset；Edge 默认 16 条、Standalone 默认 32 条、硬上限 64 条。每个名称只返回当前 version、创建时间和 canonical pinned SecretRef。响应不包含 plaintext、ciphertext、nonce、tag、key ID、mutation ID 或历史版本内容。

Fresh 与 adopted Profile 在既有数据库 close fence 上暴露只读 metadata source；不开第二个 SQLite connection，不新增 table、migration、cache、watcher 或 timer。损坏、关闭或越界查询均失败关闭。

2. Secret mutation 继续使用既有加密 authority

PUT body 精确包含 name、plaintext、mutationId 和 expectedCurrentVersion。请求只接受 User credential、secret.manage Policy 与绑定 exact plaintext digest、Project、credential ID/version、User subject 的两分钟一次性 owner-private proof。

proof 验证后再次确认 credential，并创建 request-scoped credential-fenced Secret repository。既有 Local administration service 在数据库事务外完成 AES-256-GCM 加密，在事务内重验 credential、Identity、RoleBinding、Policy 与 expected current version，再原子追加 immutable Secret version 和 durable audit。HTTP 只返回名称、当前版本、pinned reference 与幂等状态。

plaintext 仅在请求解析、proof 等待的页面内存与加密调用所需的短生命周期中存在；Console 在成功、取消、断开时清空输入和 pending body。它不进入 Cookie、Web Storage、URL、响应、audit 或日志。

3. Task 编辑器只保存 pinned SecretRef

Console 使用逐行 ENV_NAME=secret-name[@version] 绑定。省略 version 时只能从当前有界目录解析并立即固定为当前版本；显式历史版本不得大于目录中的当前版本。未知名称、未来版本、重复环境变量、QL3_ 保留前缀和不安全格式均拒绝。

保存时保留完整 authoring snapshot 中未展示的 public environment 与其他 config/labels，只替换 Console 可识别的 Secret bindings。Task spec 只持久化 canonical SecretRef；执行时继续由既有 runtime materializer 解密，不把明文写回 Task、Run、Event 或 Console。

4. Profile 与部署边界不扩张

默认 Edge/Standalone headless 不开放 Secret HTTP/Console surface，不携带静态资产或 listener；常驻增量仅是复用现有 SQLite connection 的小型 metadata repository。
edge-application-api 与 standalone-application-api 才装配 Secret metadata、presence 与 administration capability；仍是同一 Application 进程和数据库连接。
@qinglong/local-api 仅允许 src/secret/secretRoutes.ts 导入 Local administration，Local Application contract 仅允许 runtime-core 的 metadata contract；Cluster dependency audit 对其他路径继续拒绝。
Cluster 不使用 Local proof、keyring 或 SQLite authority。后续 Cluster Console Secret 管理必须走共享 custody、TLS、RBAC/Approval、PostgreSQL transaction 与 HA fence。

不采用的方案

不让浏览器读取、回显或下载 Secret 明文；轮换也只接受新值，不提供“显示现值”。
不把 ciphertext、key ID 或 mutation metadata 当作“低敏列表字段”；这些都留在 custody 边界内。
不把 Secret value 写入 Task environment、authoring lease、presence challenge 或 audit detail。
不用单因子 Bearer 直接创建或轮换 Secret；长期自动化凭据需要本机 presence 与 credential transaction fence。
不新建只有一两个文件的微包；该能力留在现有 runtime-core contract、Local SQLite repository、Local administration 和 Local API capability 内。
不为低配设备增加 Secret cache、后台清理器或独立进程。

结果与验证边界

定向测试覆盖 current-only metadata、稳定分页、关闭/越界失败、无 ciphertext/key 泄漏、exact presence、plaintext digest 漂移、宽化 body 拒绝、admission delegation、HTTP 路由与真实 SQLite/loopback 创建。集成旅程验证数据库只保存不含 plaintext 的密文，Task spec 保存精确 pinned SecretRef，并出现 secret.create 与 secret.list durable audit。

本地 18-package clean build/test 为 3,052 total / 3,030 pass / 22 conditional、platform 或 external-service skip / 0 fail，其中 Local SQLite 250/250、Local API 76/76、Local Admin 96/96、Local Application 55 total / 51 pass / 4 platform skip / 0 fail。package boundary 保持 18 packages、singleSourcePackages=[]、shallowSourcePackages=[]；122-module Edge source import 与精确 Cluster dependency audit compatible。

三项 Console 静态资产合计 102,182 bytes，低于 192 KiB 总闭包与 96 KiB 单文件门。默认 Edge 为 2,760,847 bytes/332 files/3 packages/59 loaded modules，RSS delta 11,026,432 bytes；opt-in Edge/Standalone Console 为 4,210,024/4,210,168 bytes、482 files/12 packages/111 loaded modules，RSS delta 20,447,232/18,399,232 bytes，均低于既有门。Edge executor benchmark 继续通过。

提交 f46fb44ac9534315b6965865bb3e990715bb2417 的普通主 CI run 33250825989 为 41 success/3 expected artifact-finalizer skip/0 fail，Kubernetes deployment run 33250826046 与 Security Administration Kubernetes run 33250825974 成功。显式 Local Console milestone run 33252179178 为 42 success/2 scope skip/0 fail；同源双架构 Trial Kit 与 milestone 保留至 2026-09-28，下载后三件套 checksum 及双架构 Trial Kit/milestone auditor 均返回 compatible=true。因此 D-424 已是当前可下载、可验真的阶段实物。首次 artifact run 33251389615 触发 x64 router 绝对 RSS 门；同源码 ordinary run 仅有约 1.73 MiB headroom，表现与 runner 基线波动一致。没有提高预算或修改代码，第二次全新 run 对相同 source 通过同一门。该结论不把 Alpha 扩张成公开 release、2.x 生产升级或 Cluster HA 交付。

6.9 KiB Raw Permalink Blame History Unescape Escape