diff --git a/docs/QINGLONG_3_0_ARCHITECTURE_RFC.md b/docs/QINGLONG_3_0_ARCHITECTURE_RFC.md index d4088d15..2b6c7e06 100644 --- a/docs/QINGLONG_3_0_ARCHITECTURE_RFC.md +++ b/docs/QINGLONG_3_0_ARCHITECTURE_RFC.md @@ -11,6 +11,7 @@ 最新增量证据(2026-08-15): +- D-318/ADR-0410(已接受):Cluster Copilot diagnosis Model output 获得独立的只读 projected key authority。canonical `qinglong/copilot-failure-diagnosis-output-projected-keyring@v1` manifest 只允许一个 active key 与最多 16 个 historical 32-byte key;每次 `active()`/`resolve()` 都重新执行 Cluster 私有投影文件的 direct-root、根内 atomic symlink、single-link、mode、dev/inode/size/mtime 与双 realpath fence,不使用 cache、watcher、timer 或 Kubernetes API。该 authority 以结构兼容的本地窄端口位于既有 `cluster-control/copilot/failure-diagnosis/`,只通过 `failure-diagnosis-output-keyring` subpath 发布,避免 Cluster Control 默认源码反向依赖 AI;它不复用 Prompt output、Tool invocation/result 或 Provider credential key domain,也不提前声称 Copilot 产品入口已可达。定向回归 13/13、Cluster Control 239 pass/2 条件 skip、backend 1,207 pass/2 条件 skip、18-package clean build/test、四项架构审计与 14 档 Local artifact 全部通过;workspace 仍无单文件/浅平 package,Cluster Control 58 个源码中 56 个位于嵌套领域目录。默认 Edge/Standalone 保持 2,589,890/2,589,968 bytes,Edge/Standalone AI 保持 3,061,009/3,061,099 bytes,证明 Cluster-only subpath 被裁掉。本 Gate 不改 migration/schema/role/SQL/连接/HA 拓扑,因此数据库基线继续引用 ADR-0409 的 PostgreSQL 18.6 arm64 HA 130/130、timeline `1→2`;下一 Gate 是默认关闭的完整 Cluster Copilot composition,随后补齐 Tool failure、日志 missing/retired、Model admission 前 deadline/cancel 与 outcome-unknown 的 durable terminalization/recovery。 - D-316/ADR-0408(已接受):Cluster Copilot 现在能够从 ADR-0407 的 durable admission 恢复 exact `qinglong.run.log.excerpt@1.0.0` authority,复用通用 Trusted Tool start barrier、加密 success/failure completion、result catalog/rekey 和内建日志 adapter;确定性 start/completion identity 让 response-loss replay 直接打开既有证据,不重复读取日志或执行 adapter。Cluster invocation Artifact 使用独立 projected keyring,提供 active+historical material,但每次读取均重新执行 canonical path/symlink/mode/inode/realpath fence,且不取得 PostgreSQL Tool result generation authority。只有 exact `succeeded` completion 才能通过 `pg-9019` 的 SERIALIZABLE 事务把 Model Step 从 `pending` 原子推进到 `ready`,同时写 RunEvent、StepRunMutation 和 append-only unlock receipt;`failed|timed_out` 不解锁。本 Gate 不执行模型、不终态化 diagnosis Run,下一 Gate 是 ADR-0405 builder + Model Gateway + Copilot encrypted model completion/terminalization。实现仍为 18 个 package,无单文件/浅平 package;AI 175 个源码中 174 个、Cluster Control 56 个中 54 个位于嵌套目录,不新增依赖、进程、连接、timer/watcher/cache 或默认 Edge 成本。18-package clean build/test 全绿,AI 229 pass/3 条件 skip、backend 1,207 pass/2 条件 skip,四项架构审计零 finding;14 档 Local artifact 全通过,默认 Edge/Standalone 为 2,589,890/2,589,968 bytes。PostgreSQL 18.4 arm64 HA 130/130、timeline `1→2`,首次执行只读两次日志、密文不含敏感 fixture,提升后 exact replay 零日志读取;报告 SHA-256 为 `d525a303696e178d777b021b376729bd2c5382fb5eb7bc98466a2b79d3940517`,独立审计与 Docker 清理通过。 - D-317/ADR-0409(已接受):已解锁的 Cluster failure-diagnosis Model Step 现在从 durable encrypted Tool completion 重开受信日志投影,经 ADR-0405 builder 和既有 Model Gateway 执行;只有显式安装的 Copilot success sink 可以接管成功返回。Copilot `GenerateResult` 使用独立 AES-256-GCM Artifact,绑定 plan、Tool completion、egress evidence 与 Model identity,公开 reference、ModelInvocation completion、RunEvent 和审计均不含明文。通用 `DurableModelInvocationCoordinator` 已改为领域无关的 `ModelInvocationAtomicSuccess`,消除对 Plugin Prompt Artifact 的反向依赖;Plugin Prompt 通过 adapter 保持兼容。`pg-9020` 在一个 SERIALIZABLE 事务中原子提交 ciphertext、Model completion、StepRun/Event 与 usage/pricing/quota settlement,再由可重放 finalization 事务把 diagnosis Run 推进为 `succeeded|failed|timed_out`;两事务间崩溃只补 finalization,existing start/completion/finalization replay 均不重复调用 Provider。当前仍不自动终态化 Tool failure、日志 missing/retired、Model admission 前 deadline/cancel,也不把 `outcome_unknown` 冒充失败;Cluster 专用 output projected keyring 与产品 composition 完成前该入口保持不可达。实现仍在既有 18 个 package 的嵌套领域目录内,不新增进程、队列、timer/watcher/cache 或默认 Edge 成本。最终 AI 233 pass/3 条件 skip、18-package clean build/test 与 backend 1,207 pass/2 条件 skip/0 fail,四项架构审计零 finding;workspace 无单文件或浅平 package,AI 183 个源码中 182 个位于嵌套目录。14 档 Local Profile artifact 全部通过,默认 Edge/Standalone 为 2,589,890/2,589,968 bytes,Edge/Standalone AI 为 3,061,009/3,061,099 bytes。PostgreSQL 18.6 arm64 HA 130/130、timeline `1→2`,报告 SHA-256 为 `8401634f30635b45bfb583b02e94ac41f023bf8a0bdbcfd9744ebf459ab0d8f8`,独立证据审计与 Docker 零残留。 - D-315/ADR-0407(已接受):Cluster Copilot 故障诊断不修改或重新打开终态源 Run,而是用源 Run/version、最新已结束 Attempt/status 与日志 Artifact 建立 exact fence,原子创建独立 `copilot_failure_diagnosis` Run、admission event、`ready` 的 `qinglong.run.log.excerpt@1.0.0` Tool Step、以其为父节点的 `pending` Model Step 和不可变 receipt。计划只接受 `cluster-control` 的 reviewed snapshot/binding/Policy/subject authority;`approval_required`、Tool contract/输入漂移或未显式允许的模型出口均在写库前失败关闭。`ql3_ai` 新增有界 admission ledger 与仅授予 runtime 的 `SECURITY DEFINER` source snapshot,在 SERIALIZABLE 事务内重验 active Project/binding 和源 Run/Attempt;response-loss replay 对 JSONB 做结构 exact 比较而不依赖无语义的对象键序。Copilot/Plugin 这类 StepRun 聚合从通用 Task orphan recovery 排除,后续由各自状态机恢复,不能伪造顶层 Attempt 或被错误终态化。本阶段只 admission,不执行 Tool/模型、不授予行动权;Tool encrypted completion、Model 解锁和 Copilot encrypted model completion 是下一 Gate。最终 18-package clean build/test 与 backend 1,207 pass/2 条件 skip/0 fail,四项边界审计零 finding且 workspace 仍为 18 package、无单文件/浅平 package;14 档 Local Profile artifact 全通过,默认 Edge/Standalone 不引入 Cluster admission。PostgreSQL 18.4 arm64 HA 128/128、timeline `1→2`,报告 SHA-256 为 `a4ed1edec783e3f5b42507c0f8e11b94c59dbe44a57e691017d1445ec9d115e2`,证据审计与 Docker 清理通过。 diff --git a/docs/adr/ADR-0410-cluster-copilot-failure-diagnosis-output-key-authority.md b/docs/adr/ADR-0410-cluster-copilot-failure-diagnosis-output-key-authority.md new file mode 100644 index 00000000..9cdeb834 --- /dev/null +++ b/docs/adr/ADR-0410-cluster-copilot-failure-diagnosis-output-key-authority.md @@ -0,0 +1,76 @@ +# ADR-0410:Cluster Copilot Failure Diagnosis Output Key Authority + +- 状态:Accepted +- 日期:2026-08-15 +- 关联 RFC:QL-RFC-0001 D-318、Phase 2 +- 关联 ADR:ADR-0405、ADR-0406、ADR-0408、ADR-0409 + +## 问题 + +ADR-0409 已定义 Copilot diagnosis Model output 的独立 AES-256-GCM Artifact 与 key provider 端口, +但 Cluster 产品还没有可以注入该端口的部署密钥 authority。若复用 Plugin Prompt output、Tool +invocation 或 Tool result keyring,会让一次轮换或退役跨越不同数据域,并使最小权限部署无法证明 +哪个进程能够加解密诊断结果。 + +同时,路由设备不应因为 Cluster Copilot 能力增加任何 keyring、watcher 或常驻内存;Cluster 节点 +也不能把 Kubernetes Secret/CSI projection 的瞬时路径、可写文件或跨目录 symlink 当成可信密钥。 + +## 决策 + +1. 新增独立 schema `qinglong/copilot-failure-diagnosis-output-projected-keyring@v1`。manifest 只包含 + 一个 `activeKeyId` 和最多 16 个 canonical 32-byte key;key ID 有界,JSON 必须 exact 且 canonical。 +2. `ClusterCopilotFailureDiagnosisOutputProjectedKeyring` 实现 ADR-0409 的 `active()` 与 + `resolve(keyId)` 端口。每次操作重新打开 projection,不持有 cache、watcher、timer、Kubernetes + API client 或轮换权限;返回的 key material 由调用者使用后清零。 +3. 文件读取复用 Cluster Control package-private `PrivateProjectedFileReader`:配置根必须是 direct + absolute directory;允许 Kubernetes atomic-writer 的根内 symlink,但最终 regular file 必须单链接、 + 只读、不可执行、other-inaccessible,并在读取前后复验 dev/inode/size/mtime 与双 realpath fence。 +4. Copilot output key ID/material 不得与 Plugin Prompt output、Tool invocation、Tool result 或 Provider + credential 互换。不同 schema 即使 key bytes 相同也拒绝;部署文档必须要求独立 Secret 和 mount root。 +5. 能力内聚在现有 `@qinglong/cluster-control` 的 `copilot/failure-diagnosis/` 目录,只通过显式 + `failure-diagnosis-output-keyring` subpath 发布;不新增 workspace package、依赖、进程、Pod、连接、 + route 或默认 Profile import。 +6. 本 Gate 只建立 runtime key custody,不提前伪造产品可用性。完整 Copilot composition 仍需同时装配 + admission、Tool invocation/result keyring、Artifact/log reader、Model Gateway、PostgreSQL repository + 与恢复状态机;该入口在后续 Gate 完成前保持不可达。 + +## 被否决方案 + +1. **复用 Plugin Prompt output keyring**:两个产品域的 retention、授权和泄漏半径不同。 +2. **复用 Tool invocation/result keyring**:混淆请求、Tool 结果与模型结论的加密用途。 +3. **从环境变量读取 base64 key**:密钥进入进程环境与诊断面,且无法安全保留历史 key。 +4. **启动时读取一次并永久缓存**:轮换无法生效,退役和文件漂移也无法失败关闭。 +5. **为 keyring 新建 package**:没有独立部署进程或依赖边界,只会增加薄包。 + +## 验证标准 + +1. 覆盖 canonical manifest、active rotation、historical resolve、missing key、wrong schema、缺失 active、 + 非 32-byte material、可写 projection 与根外 symlink。 +2. Cluster Control 完整构建/测试、package/dependency/Edge import/Cluster deployment 审计全部通过。 +3. workspace 保持 18 个 package、无单文件或浅平 package;14 档 Local Profile artifact 证明默认 + Edge/Standalone 与本地 AI/MCP 不携带该 Cluster-only subpath。 + +## 后续门禁 + +1. 在独立默认关闭的 Cluster Copilot composition 中同时装配 admission、Tool、Model 与本 keyring, + 不能把 Plugin Prompt gateway 的 completion sink 当作 Copilot sink。 +2. 建立 Tool failure、日志 missing/retired、Model admission 前 deadline/cancel 与 outcome-unknown + resolution 的 durable terminalization/recovery。 +3. 再开放经 authentication、Policy、audit 和 exact source fence 的 Cluster API/CLI/UI/MCP 入口。 + +## 当前验证 + +1. 定向 keyring 与 package-boundary 回归 13/13;Cluster Control 完整测试 241 项中 239 pass、2 条 + 环境条件 skip、0 fail。 +2. 18 个 QL3 package 从清理 `dist` 开始顺序构建并执行全部 package tests,退出码为 0;backend + 全量 1,209 项中 1,207 pass、2 条环境条件 skip、0 fail。 +3. package boundary、dependency firewall、Edge import 与 Cluster deployment 四项架构审计均为 + `compatible: true`、零 finding。workspace 仍为 18 个 package,`singleSourcePackages` 与 + `shallowSourcePackages` 均为空;Cluster Control 的 58 个源码中,56 个位于嵌套领域目录,根层仅 + 保留 2 个 binary entry。 +4. 14 档 Local Profile artifact 全部通过。默认 Edge/Standalone 仍为 + 2,589,890/2,589,968 bytes,Edge/Standalone AI 仍为 3,061,009/3,061,099 bytes;新增 + Cluster-only subpath 未进入默认、本地 AI 或 MCP 产品闭包。 +5. 本 Gate 不修改 migration、schema、PostgreSQL role、SQL、连接或 HA 拓扑,因此不重复制造一份与 + 变更无关的数据库实证;ADR-0409 的 PostgreSQL 18.6 arm64 HA 130/130、timeline `1→2` 仍是当前 + 数据库基线。 diff --git a/docs/adr/README.md b/docs/adr/README.md index 77e9cefa..33f0b337 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -413,6 +413,7 @@ | [ADR-0407](./ADR-0407-cluster-copilot-failure-diagnosis-run-admission.md) | Cluster Copilot Failure Diagnosis Run Admission | Accepted | | [ADR-0408](./ADR-0408-cluster-copilot-failure-diagnosis-tool-execution.md) | Cluster Copilot Failure Diagnosis Tool Execution 与原子 Model 解锁 | Accepted | | [ADR-0409](./ADR-0409-cluster-copilot-failure-diagnosis-model-execution.md) | Cluster Copilot Failure Diagnosis Model Execution、密文输出与 Run 终态化 | Accepted | +| [ADR-0410](./ADR-0410-cluster-copilot-failure-diagnosis-output-key-authority.md) | Cluster Copilot Failure Diagnosis Output Projected Key Authority | Accepted | ## 规则 diff --git a/packages/ql3-cluster-control/package.json b/packages/ql3-cluster-control/package.json index 53f29168..690b9375 100644 --- a/packages/ql3-cluster-control/package.json +++ b/packages/ql3-cluster-control/package.json @@ -35,6 +35,11 @@ "require": "./dist/application-runtime/aiProductionApplication.js", "default": "./dist/application-runtime/aiProductionApplication.js" }, + "./failure-diagnosis-output-keyring": { + "types": "./dist/copilot/failure-diagnosis/outputProjectedKeyring.d.ts", + "require": "./dist/copilot/failure-diagnosis/outputProjectedKeyring.js", + "default": "./dist/copilot/failure-diagnosis/outputProjectedKeyring.js" + }, "./http": { "types": "./dist/transport/httpSurface.d.ts", "require": "./dist/transport/httpSurface.js", diff --git a/packages/ql3-cluster-control/src/copilot/failure-diagnosis/outputKeyringManifest.ts b/packages/ql3-cluster-control/src/copilot/failure-diagnosis/outputKeyringManifest.ts new file mode 100644 index 00000000..fddc26cf --- /dev/null +++ b/packages/ql3-cluster-control/src/copilot/failure-diagnosis/outputKeyringManifest.ts @@ -0,0 +1,196 @@ +import { Buffer } from 'node:buffer'; +import { createHash } from 'node:crypto'; + +export const CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_KEYRING_MANIFEST_SCHEMA = + 'qinglong/copilot-failure-diagnosis-output-projected-keyring@v1' as const; +export const MAX_CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_KEYRING_BYTES = + 64 * 1024; +export const MAX_CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_PROJECTED_KEYS = 16; + +const KEY_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/; +const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/; +const PROJECTION_DIGEST_DOMAIN = Buffer.from( + 'qinglong/copilot-failure-diagnosis-output-projected-keyring-digest@v1\0', + 'utf8', +); + +export interface ClusterCopilotFailureDiagnosisOutputKeyringManifest { + readonly schema: typeof CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_KEYRING_MANIFEST_SCHEMA; + readonly activeKeyId: string; + readonly keys: Readonly>; +} + +export interface ClusterCopilotFailureDiagnosisOutputKeyringSummary { + readonly schemaVersion: 1; + readonly activeKeyId: string; + readonly keyIds: readonly string[]; + readonly projectionDigest: string; +} + +export interface ClusterCopilotFailureDiagnosisOutputKeyMaterial { + readonly keyId: string; + readonly key: Uint8Array; +} + +export class InvalidClusterCopilotFailureDiagnosisOutputKeyringManifestError extends TypeError { + readonly code = + 'QL3_CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_KEYRING_MANIFEST_INVALID'; + + constructor() { + super('Cluster Copilot failure diagnosis output keyring manifest is invalid'); + this.name = + 'InvalidClusterCopilotFailureDiagnosisOutputKeyringManifestError'; + } +} + +function invalid(): never { + throw new InvalidClusterCopilotFailureDiagnosisOutputKeyringManifestError(); +} + +function dataRecord(value: unknown): Record { + if ( + !value || + typeof value !== 'object' || + Array.isArray(value) || + Object.getPrototypeOf(value) !== Object.prototype + ) { + return invalid(); + } + return value as Record; +} + +function exactKeys(value: object, expected: readonly string[]): boolean { + const actual = Object.keys(value).sort(); + const canonical = [...expected].sort(); + return ( + actual.length === canonical.length && + actual.every((key, index) => key === canonical[index]) + ); +} + +export function normalizeClusterCopilotFailureDiagnosisOutputKeyringManifest( + value: unknown, +): Readonly { + const manifest = dataRecord(value); + if ( + !exactKeys(manifest, ['activeKeyId', 'keys', 'schema']) || + manifest.schema !== + CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_KEYRING_MANIFEST_SCHEMA || + typeof manifest.activeKeyId !== 'string' || + !KEY_ID_PATTERN.test(manifest.activeKeyId) + ) { + return invalid(); + } + const keys = dataRecord(manifest.keys); + const entries = Object.entries(keys).sort(([left], [right]) => + left < right ? -1 : left > right ? 1 : 0, + ); + if ( + entries.length < 1 || + entries.length > + MAX_CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_PROJECTED_KEYS + ) { + return invalid(); + } + const normalized: (readonly [string, string])[] = []; + for (const [keyId, encoded] of entries) { + let material: Buffer | undefined; + try { + if ( + !KEY_ID_PATTERN.test(keyId) || + typeof encoded !== 'string' || + !BASE64URL_PATTERN.test(encoded) + ) { + return invalid(); + } + material = Buffer.from(encoded, 'base64url'); + if ( + material.byteLength !== 32 || + material.toString('base64url') !== encoded + ) { + return invalid(); + } + normalized.push(Object.freeze([keyId, encoded] as const)); + } finally { + material?.fill(0); + } + } + const normalizedKeys = Object.freeze(Object.fromEntries(normalized)); + if (normalizedKeys[manifest.activeKeyId] === undefined) return invalid(); + return Object.freeze({ + schema: + CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_KEYRING_MANIFEST_SCHEMA, + activeKeyId: manifest.activeKeyId, + keys: normalizedKeys, + }); +} + +export function parseClusterCopilotFailureDiagnosisOutputKeyringManifest( + bytes: Buffer, +): Readonly { + try { + if ( + !Buffer.isBuffer(bytes) || + bytes.byteLength < 1 || + bytes.byteLength > + MAX_CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_KEYRING_BYTES + ) { + return invalid(); + } + return normalizeClusterCopilotFailureDiagnosisOutputKeyringManifest( + JSON.parse(bytes.toString('utf8')), + ); + } catch (error) { + if ( + error instanceof + InvalidClusterCopilotFailureDiagnosisOutputKeyringManifestError + ) { + throw error; + } + return invalid(); + } +} + +export function canonicalClusterCopilotFailureDiagnosisOutputKeyringManifest( + value: ClusterCopilotFailureDiagnosisOutputKeyringManifest, +): Buffer { + const manifest = + normalizeClusterCopilotFailureDiagnosisOutputKeyringManifest(value); + return Buffer.from(`${JSON.stringify(manifest)}\n`, 'utf8'); +} + +export function resolveClusterCopilotFailureDiagnosisOutputKeyringMaterial( + value: ClusterCopilotFailureDiagnosisOutputKeyringManifest, + keyId: string, +): Readonly | null { + if (typeof keyId !== 'string' || !KEY_ID_PATTERN.test(keyId)) { + return invalid(); + } + const manifest = + normalizeClusterCopilotFailureDiagnosisOutputKeyringManifest(value); + const encoded = manifest.keys[keyId]; + if (encoded === undefined) return null; + const key = Buffer.from(encoded, 'base64url'); + if (key.byteLength !== 32 || key.toString('base64url') !== encoded) { + key.fill(0); + return invalid(); + } + return Object.freeze({ keyId, key }); +} + +export function summarizeClusterCopilotFailureDiagnosisOutputKeyringManifest( + value: ClusterCopilotFailureDiagnosisOutputKeyringManifest, +): Readonly { + const manifest = + normalizeClusterCopilotFailureDiagnosisOutputKeyringManifest(value); + const keyIds = Object.freeze(Object.keys(manifest.keys).sort()); + return Object.freeze({ + schemaVersion: 1 as const, + activeKeyId: manifest.activeKeyId, + keyIds, + projectionDigest: createHash('sha256') + .update(PROJECTION_DIGEST_DOMAIN) + .update(JSON.stringify(manifest)) + .digest('hex'), + }); +} diff --git a/packages/ql3-cluster-control/src/copilot/failure-diagnosis/outputProjectedKeyring.ts b/packages/ql3-cluster-control/src/copilot/failure-diagnosis/outputProjectedKeyring.ts new file mode 100644 index 00000000..7cf57793 --- /dev/null +++ b/packages/ql3-cluster-control/src/copilot/failure-diagnosis/outputProjectedKeyring.ts @@ -0,0 +1,176 @@ +import { Buffer } from 'node:buffer'; + +import { PrivateProjectedFileReader } from '../../security/privateProjectedFile'; +import { + MAX_CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_KEYRING_BYTES, + canonicalClusterCopilotFailureDiagnosisOutputKeyringManifest, + parseClusterCopilotFailureDiagnosisOutputKeyringManifest, + resolveClusterCopilotFailureDiagnosisOutputKeyringMaterial, + summarizeClusterCopilotFailureDiagnosisOutputKeyringManifest, + type ClusterCopilotFailureDiagnosisOutputKeyMaterial, + type ClusterCopilotFailureDiagnosisOutputKeyringManifest, + type ClusterCopilotFailureDiagnosisOutputKeyringSummary, +} from './outputKeyringManifest'; + +const DATA_FILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,252}$/; + +export { + CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_KEYRING_MANIFEST_SCHEMA, + MAX_CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_KEYRING_BYTES, + MAX_CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_PROJECTED_KEYS, + InvalidClusterCopilotFailureDiagnosisOutputKeyringManifestError, + canonicalClusterCopilotFailureDiagnosisOutputKeyringManifest, + normalizeClusterCopilotFailureDiagnosisOutputKeyringManifest, + parseClusterCopilotFailureDiagnosisOutputKeyringManifest, + resolveClusterCopilotFailureDiagnosisOutputKeyringMaterial, + summarizeClusterCopilotFailureDiagnosisOutputKeyringManifest, + type ClusterCopilotFailureDiagnosisOutputKeyringManifest, + type ClusterCopilotFailureDiagnosisOutputKeyringSummary, +} from './outputKeyringManifest'; + +export interface ClusterCopilotFailureDiagnosisOutputProjectedKeyringOptions { + readonly rootDirectory: string; + readonly dataFileName?: string; +} + +export interface ClusterCopilotFailureDiagnosisOutputKeyProvider { + active(): Promise; + resolve( + keyId: string, + ): Promise; +} + +export class ClusterCopilotFailureDiagnosisOutputProjectedKeyringUnavailableError extends Error { + readonly code = + 'QL3_CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_PROJECTED_KEYRING_UNAVAILABLE'; + + constructor(options?: ErrorOptions) { + super( + 'Projected Cluster Copilot failure diagnosis output keyring is unavailable', + options, + ); + this.name = + 'ClusterCopilotFailureDiagnosisOutputProjectedKeyringUnavailableError'; + } +} + +function unavailable( + cause?: unknown, +): ClusterCopilotFailureDiagnosisOutputProjectedKeyringUnavailableError { + return new ClusterCopilotFailureDiagnosisOutputProjectedKeyringUnavailableError( + { cause: cause instanceof Error ? cause : undefined }, + ); +} + +function dataFileName(value: unknown): string { + if (typeof value !== 'string' || !DATA_FILE_NAME.test(value)) { + throw unavailable(); + } + return value; +} + +async function readManifest( + reader: PrivateProjectedFileReader, + fileName: string, +): Promise> { + let bytes: Buffer | undefined; + let canonical: Buffer | undefined; + try { + bytes = await reader.read(fileName); + const manifest = + parseClusterCopilotFailureDiagnosisOutputKeyringManifest(bytes); + canonical = + canonicalClusterCopilotFailureDiagnosisOutputKeyringManifest(manifest); + if (!canonical.equals(bytes)) throw unavailable(); + return manifest; + } catch (cause) { + throw cause instanceof + ClusterCopilotFailureDiagnosisOutputProjectedKeyringUnavailableError + ? cause + : unavailable(cause); + } finally { + bytes?.fill(0); + canonical?.fill(0); + } +} + +/** Read-only, no-cache Copilot diagnosis output key authority. */ +export class ClusterCopilotFailureDiagnosisOutputProjectedKeyring + implements ClusterCopilotFailureDiagnosisOutputKeyProvider +{ + readonly #reader: PrivateProjectedFileReader; + readonly #dataFileName: string; + + constructor( + options: ClusterCopilotFailureDiagnosisOutputProjectedKeyringOptions, + ) { + if (!options || typeof options !== 'object' || Array.isArray(options)) { + throw unavailable(); + } + try { + this.#reader = new PrivateProjectedFileReader({ + rootDirectory: options.rootDirectory, + minimumBytes: 1, + maximumBytes: + MAX_CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_KEYRING_BYTES, + access: 'read_only_keyring', + }); + this.#dataFileName = dataFileName(options.dataFileName ?? 'keyring.json'); + } catch (cause) { + throw unavailable(cause); + } + } + + async verify(): Promise< + Readonly + > { + return summarizeClusterCopilotFailureDiagnosisOutputKeyringManifest( + await readManifest(this.#reader, this.#dataFileName), + ); + } + + async active(): Promise { + try { + const manifest = await readManifest(this.#reader, this.#dataFileName); + const material = + resolveClusterCopilotFailureDiagnosisOutputKeyringMaterial( + manifest, + manifest.activeKeyId, + ); + if (!material) throw unavailable(); + return material; + } catch (cause) { + throw cause instanceof + ClusterCopilotFailureDiagnosisOutputProjectedKeyringUnavailableError + ? cause + : unavailable(cause); + } + } + + async resolve( + keyId: string, + ): Promise { + try { + return resolveClusterCopilotFailureDiagnosisOutputKeyringMaterial( + await readManifest(this.#reader, this.#dataFileName), + keyId, + ); + } catch (cause) { + throw cause instanceof + ClusterCopilotFailureDiagnosisOutputProjectedKeyringUnavailableError + ? cause + : unavailable(cause); + } + } +} + +export async function createClusterCopilotFailureDiagnosisOutputProjectedKeyring( + options: ClusterCopilotFailureDiagnosisOutputProjectedKeyringOptions, +): Promise< + Readonly +> { + const provider = + new ClusterCopilotFailureDiagnosisOutputProjectedKeyring(options); + await provider.verify(); + return provider; +} diff --git a/packages/ql3-cluster-control/test/copilot-failure-diagnosis-output-projected-keyring.test.cjs b/packages/ql3-cluster-control/test/copilot-failure-diagnosis-output-projected-keyring.test.cjs new file mode 100644 index 00000000..eaf64500 --- /dev/null +++ b/packages/ql3-cluster-control/test/copilot-failure-diagnosis-output-projected-keyring.test.cjs @@ -0,0 +1,178 @@ +const assert = require('node:assert/strict'); +const fs = require('node:fs/promises'); +const os = require('node:os'); +const path = require('node:path'); +const { afterEach, test } = require('node:test'); + +const rootExport = require('@qinglong/cluster-control'); +const { + CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_KEYRING_MANIFEST_SCHEMA, + ClusterCopilotFailureDiagnosisOutputProjectedKeyring, + ClusterCopilotFailureDiagnosisOutputProjectedKeyringUnavailableError, + InvalidClusterCopilotFailureDiagnosisOutputKeyringManifestError, + canonicalClusterCopilotFailureDiagnosisOutputKeyringManifest, + createClusterCopilotFailureDiagnosisOutputProjectedKeyring, + normalizeClusterCopilotFailureDiagnosisOutputKeyringManifest, +} = require('@qinglong/cluster-control/failure-diagnosis-output-keyring'); + +const roots = []; + +afterEach(async () => { + await Promise.all( + roots + .splice(0) + .map((root) => fs.rm(root, { recursive: true, force: true })), + ); +}); + +async function tempRoot(label = 'ql3-copilot-output-keyring-') { + const root = await fs.mkdtemp(path.join(os.tmpdir(), label)); + roots.push(root); + return root; +} + +function manifest(activeKeyId, keys) { + return Object.freeze({ + schema: + CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_KEYRING_MANIFEST_SCHEMA, + activeKeyId, + keys: Object.freeze(keys), + }); +} + +async function publish(root, generationName, value, mode = 0o440) { + const generation = path.join(root, generationName); + await fs.mkdir(generation, { mode: 0o750 }); + const target = path.join(generation, 'keyring.json'); + await fs.writeFile( + target, + canonicalClusterCopilotFailureDiagnosisOutputKeyringManifest(value), + { mode }, + ); + await fs.chmod(target, mode); + const next = path.join(root, '..data-next'); + await fs.symlink(generationName, next); + await fs.rename(next, path.join(root, '..data')); + try { + await fs.symlink('..data/keyring.json', path.join(root, 'keyring.json')); + } catch (error) { + if (error.code !== 'EEXIST') throw error; + } +} + +test('projected Copilot output keyring rotates active material without caching', async () => { + const root = await tempRoot(); + const keyOne = Buffer.alloc(32, 0x31); + const keyTwo = Buffer.alloc(32, 0x32); + await publish( + root, + '..2026_08_15_01', + manifest('copilot-output-one', { + 'copilot-output-one': keyOne.toString('base64url'), + }), + ); + const provider = + await createClusterCopilotFailureDiagnosisOutputProjectedKeyring({ + rootDirectory: root, + }); + const first = await provider.active(); + assert.equal(first.keyId, 'copilot-output-one'); + assert.deepEqual(Buffer.from(first.key), keyOne); + first.key.fill(0); + + await publish( + root, + '..2026_08_15_02', + manifest('copilot-output-two', { + 'copilot-output-one': keyOne.toString('base64url'), + 'copilot-output-two': keyTwo.toString('base64url'), + }), + ); + const second = await provider.active(); + assert.equal(second.keyId, 'copilot-output-two'); + assert.deepEqual(Buffer.from(second.key), keyTwo); + second.key.fill(0); + const historical = await provider.resolve('copilot-output-one'); + assert.ok(historical); + assert.deepEqual(Buffer.from(historical.key), keyOne); + historical.key.fill(0); + assert.equal(await provider.resolve('missing-key'), null); + + const summary = await provider.verify(); + assert.deepEqual(summary.keyIds, [ + 'copilot-output-one', + 'copilot-output-two', + ]); + assert.equal(summary.activeKeyId, 'copilot-output-two'); + assert.match(summary.projectionDigest, /^[0-9a-f]{64}$/); +}); + +test('manifest rejects missing active, wrong domains and non-canonical material', () => { + const key = Buffer.alloc(32, 0x41).toString('base64url'); + assert.throws( + () => + normalizeClusterCopilotFailureDiagnosisOutputKeyringManifest({ + ...manifest('missing-key', { 'copilot-output-one': key }), + }), + InvalidClusterCopilotFailureDiagnosisOutputKeyringManifestError, + ); + assert.throws( + () => + normalizeClusterCopilotFailureDiagnosisOutputKeyringManifest({ + ...manifest('copilot-output-one', { 'copilot-output-one': key }), + schema: 'qinglong/cluster-tool-invocation-projected-keyring@v1', + }), + InvalidClusterCopilotFailureDiagnosisOutputKeyringManifestError, + ); + assert.throws( + () => + normalizeClusterCopilotFailureDiagnosisOutputKeyringManifest( + manifest('copilot-output-one', { + 'copilot-output-one': Buffer.alloc(31, 0x41).toString('base64url'), + }), + ), + InvalidClusterCopilotFailureDiagnosisOutputKeyringManifestError, + ); + assert.equal( + rootExport.ClusterCopilotFailureDiagnosisOutputProjectedKeyring, + undefined, + ); +}); + +test('projected Copilot output keyring rejects writable and escaping files', async () => { + const writableRoot = await tempRoot(); + const key = Buffer.alloc(32, 0x51).toString('base64url'); + await publish( + writableRoot, + '..2026_08_15_01', + manifest('copilot-output-one', { 'copilot-output-one': key }), + 0o640, + ); + await assert.rejects( + () => + new ClusterCopilotFailureDiagnosisOutputProjectedKeyring({ + rootDirectory: writableRoot, + }).verify(), + ClusterCopilotFailureDiagnosisOutputProjectedKeyringUnavailableError, + ); + + const escapeRoot = await tempRoot(); + const outsideRoot = await tempRoot('ql3-copilot-output-outside-'); + const outsideFile = path.join(outsideRoot, 'keyring.json'); + await fs.writeFile( + outsideFile, + canonicalClusterCopilotFailureDiagnosisOutputKeyringManifest( + manifest('copilot-output-one', { 'copilot-output-one': key }), + ), + { mode: 0o440 }, + ); + await fs.chmod(outsideFile, 0o440); + await fs.symlink(outsideFile, path.join(escapeRoot, 'keyring.json')); + await assert.rejects( + () => + new ClusterCopilotFailureDiagnosisOutputProjectedKeyring({ + rootDirectory: escapeRoot, + }).verify(), + ClusterCopilotFailureDiagnosisOutputProjectedKeyringUnavailableError, + ); +}); diff --git a/test/back/ql3PackageBoundaryAudit.test.cjs b/test/back/ql3PackageBoundaryAudit.test.cjs index e416597e..e2a82dc2 100644 --- a/test/back/ql3PackageBoundaryAudit.test.cjs +++ b/test/back/ql3PackageBoundaryAudit.test.cjs @@ -385,10 +385,10 @@ test('current QL3 workspace has exactly eighteen reviewed package boundaries', ( rootSourceFileRoles: clusterControl.rootSourceFileRoles, }, { - sourceFiles: 56, + sourceFiles: 58, rootSourceFiles: 2, rootSourceLines: 195, - nestedSourceFiles: 54, + nestedSourceFiles: 56, rootSourceFileRoles: { 'aiCli.ts': 'binary_entry', 'cli.ts': 'binary_entry',