diff --git a/docs/QINGLONG_3_0_ARCHITECTURE_RFC.md b/docs/QINGLONG_3_0_ARCHITECTURE_RFC.md index 2693d16d..c6ee4a6d 100644 --- a/docs/QINGLONG_3_0_ARCHITECTURE_RFC.md +++ b/docs/QINGLONG_3_0_ARCHITECTURE_RFC.md @@ -11,6 +11,7 @@ 最新增量证据（2026-08-16）： +- D-339/ADR-0431（已接受；真实公开 catalog 运行待实际 release tag）：D337 的 deployment-lock CLI 不再接受一份无法证明来源的松散 `--release-set`；Local/Kubernetes create/audit 必须同时接收 exact source repository 和 D338 生成的 owner-private three-file `--consumption-bundle`，先完整离线重建 release-set、raw OCI manifest、catalog plan/receipt、六步 argv/transcript digest 与 self-digest report，再把同一次 audit 读取的 release-set 对象交给 materializer，避免验真后重新按裸路径读取。Local selection 与 Kubernetes lock schema 升为 v2，显式绑定 consumption schema、source repository、exact workflow identity、catalog immutable reference、manifest digest、consumption report digest、release-set digest 和 `discoveryTagAuthority=none`；Cluster 被改写资源与 Pod template 也新增 catalog manifest/report digest annotations。旧 `--release-set`、bundle symlink/open shape、identity/scope/owner/image-count/digest 漂移均在创建任何输出前失败关闭。offline audit 诚实保持 `externalToolResultsReplayed=false`；本 Gate 不联网、不访问 Kubernetes API、不执行 Compose rollout/`kubectl apply`、不修改数据库，也不新增 package、生产依赖或运行期组件。供应链工作仍留在可信工作站，低配设备只接收 catalog-bound Local v2 selection 与一个 immutable image reference；Cluster 复用既有 post-render 流程。完整定向发布链 123/123；backend 共 1,317 项，1,315 pass/2 条件 skip/0 fail；18-package clean build/test 退出 0，package boundary 保持 18 packages、`singleSourcePackages=[]`、`shallowSourcePackages=[]`。10 项架构/部署审计与 14 档 Local artifact 全部 compatible，默认 Edge/Standalone 为 2,589,890/2,589,968 bytes，application+AI 为 4,493,043/4,493,175 bytes，MCP 为 7,315,930/7,316,038 bytes；Cluster Admin pack 保持 250 files、271,238-byte tarball、1,690,196-byte unpacked。本 Gate 不改变数据库或 HA 拓扑，复用紧邻发布 Gate 的 PostgreSQL 18.6 arm64 physical HA 基线而不把它声明为本阶段新证据。公开 GHCR catalog 未实际产生，因此不宣称真实线上验签成功。 - D-338/ADR-0430（已接受；真实公开 catalog 运行待实际 release tag）：发布端的 durable catalog 不再由部署者通过松散 shell 重定向手工消费。可信工作站上的 `ql3-release-catalog-consumption-ceremony.cjs` 从 exact source version/revision/tag、closed `local|cluster|all` scope 与 owner/source repository 推导唯一 discovery ref，前后两次解析必须得到同一 digest，后续只使用 catalog `@sha256:` immutable reference。ceremony 以绝对路径、dev/inode/size/SHA-256 固定 `regctl|cosign|gh`，owner-private token 只进入单个 GitHub provenance verifier；环境、cache/config/tmp 与最终写入均有封闭边界。下载的 canonical release set 经过 standalone identity/family/self-digest inspection，raw OCI manifest 同时按 digest、media type、empty config、单 layer、basename、size/content digest 与四项 annotation 重建 publication plan/receipt。成功后才以 `0700` no-replace 目录和三项 `0600` 文件发布 release set、raw manifest 与 self-digest report；offline audit 要求 exact-three-file，并完全重建结构/manifest/report，同时诚实声明网络签名结果未离线 replay。该 ceremony 无 registry/GitHub mutation、deployment action authority、Compose/Kubernetes apply 或数据库访问；D337 继续只消费审计后的 release set。Local/低配设备不安装任何工作站工具，Cluster 也不新增 controller/CRD/RBAC。独立 ceremony 20/20、完整定向发布链 121/121 已通过；backend 共 1,315 项，1,313 pass/2 条件 skip/0 fail；18-package clean build/test 退出 0，package boundary 保持 18 packages、`singleSourcePackages=[]`、`shallowSourcePackages=[]`。10 项架构/部署审计与 14 档 Local artifact 全部 compatible，默认 Edge/Standalone 为 2,589,890/2,589,968 bytes，application+AI 为 4,493,043/4,493,175 bytes，MCP 为 7,315,930/7,316,038 bytes；Cluster Admin pack 保持 250 files、271,238-byte tarball、1,690,196-byte unpacked。本 Gate 不改变数据库或 HA 拓扑，复用紧邻发布 Gate 的 PostgreSQL 18.6 arm64 physical HA 基线而不把它声明为本阶段新证据。公开 GHCR catalog 仍未实际产生，因此本门不宣称已取得真实 Cosign/GitHub/registry 成功证据。 - D-337/ADR-0429（已接受）：D-336 的 durable release set 现在可以离线物化为最终部署 authority，而不是由运维者手工复制 digest。可信工作站上的 `ql3-deployment-lock-contract.cjs` 不联网、不连接 Kubernetes API、不执行 rollout：Local/All 生成绑定 release-set digest、唯一 Local `@sha256:` 与显式 root policy 的 canonical selection；Cluster/All 先消费 `kubectl kustomize` 的最终多文档 YAML，再只改写封闭的 Pod/Deployment/StatefulSet/DaemonSet/ReplicaSet/Job/CronJob container 字段和 exact Plugin Package admission ConfigMap，生成带输入/输出 digest、各 role occurrence、release annotation 与 self digest 的 locked manifest/report。调用方必须显式声明 required role，未知位置的完整 role authority、畸形 container image、缺失角色、YAML alias/cycle/非 mapping、超限或覆盖输出全部失败关闭；audit 从原 release set 与原 render byte-exact 重建。采用 post-render 是因为真实原型证明外层 Kustomize component 不能可靠覆盖内层已选 repository/digest，且 `images` transformer 不处理 ConfigMap `data.image`。本机 kubectl 1.36.1/Kustomize 5.8.1 已真实渲染 CloudNativePG Core、Cluster AI、Worker node 与 Plugin Package Executor 四类清单，内层零 digest 均被同一 release set 的精确引用替换；定向 deployment-lock 11/11、发布链路联动 101/101，静态审计冻结 224 个 YAML、31 个直接 role image 引用与两个 admission authority。工具只在工作站运行，低配路由器只消费 Local selection，不新增 Node/YAML/Kubernetes/registry 工具、package、依赖、常驻进程或资源；Cluster 也不新增 controller/webhook/CRD/RBAC。完整 backend 共 1,295 项，1,293 pass/2 条件 skip/0 fail；18-package clean build/test 退出 0，package boundary 保持 18 packages、`singleSourcePackages=[]`、`shallowSourcePackages=[]`，10 项架构/部署审计与 14 档 Local artifact 全部 compatible。默认 Edge/Standalone 为 2,589,890/2,589,968 bytes，application+AI 为 4,493,043/4,493,175 bytes，MCP 为 7,315,930/7,316,038 bytes；Cluster Admin pack 保持 250 files、271,238-byte tarball、1,690,196-byte unpacked。本 Gate 不改数据库或 HA 拓扑。 - D-336/ADR-0428（已接受；公开发布结果待实际 tag）：D-335 的 90 天 workflow artifact 不再是长期唯一发布入口。完整 release set 现以单层 OCI artifact 发布到专用 `ghcr.io//qinglong3-release-catalog`，固定 artifact/file media type、basename、四项 annotation 和 byte-exact round trip；`v-` 仅作发现且 authority 明确为 `none`，部署权威是验证后的 catalog `@sha256:` immutable reference。发布后先按 digest 取回并逐字节比较、审计 raw manifest，再为该 digest 生成 exact workflow identity 的 keyless Cosign signature 与绑定 source tag/revision 的 GitHub OCI provenance；验证成功后才生成 canonical receipt 并为 receipt 增加 file provenance。release-set 新增不依赖短期 candidate/image-record 的 standalone inspect，重算结构、身份、Local/Cluster 镜像闭包与 self digest，同时显式声明未重放 source records。低配路由器可在可信工作站完成 registry/签名/provenance/Node 验真，只消费 `local` JSON 与镜像 digest，设备不增加工具、package、依赖或常驻资源；Cluster 使用同一 catalog 锁定 control、control-ai、worker、admin 四角色。真实本机 `ocidir://` 实验确认同一文件来自两个不同绝对目录时，`--file-title --strip-dirs` 产生相同 manifest digest `sha256:0443422e34edd448499a61f4580b01b9578dc35a117668c948c51a16638e4e9d`，immutable get 与源文件逐字节一致。定向发布契约/静态 workflow/Console 联动测试 93/93；backend 1282 项为 1280 pass、2 条件 skip、0 fail；18-package clean build/test 退出 0，package boundary 保持 18 packages、`singleSourcePackages=[]`、`shallowSourcePackages=[]`，release version、dependency、Edge import、Cluster/Worker deployment、image release、Local image 与 Console distribution 审计全部 compatible。14 档 Local artifact 均 compatible，默认 Edge/Standalone 为 2,589,890/2,589,968 bytes，MCP 为 7,315,930/7,316,038 bytes；Cluster Admin pack 保持 250 files、271,238-byte tarball、1,690,196-byte unpacked。本 Gate 无数据库/HA 拓扑变化，复用 D-331/D-333 PostgreSQL 18.6 arm64 142/142、timeline `1→2` 基线。公开 GHCR push、签名和 attestation 尚未执行，且 GHCR 保留/删除仍属于组织治理，因此不宣称 catalog 为 WORM 或已完成线上发布。 diff --git a/docs/adr/ADR-0431-catalog-bound-deployment-lock-chain.md b/docs/adr/ADR-0431-catalog-bound-deployment-lock-chain.md new file mode 100644 index 00000000..d2d27c6a --- /dev/null +++ b/docs/adr/ADR-0431-catalog-bound-deployment-lock-chain.md @@ -0,0 +1,84 @@ +# ADR-0431：Catalog-bound Deployment Lock 证据链 + +- 状态：Accepted（实现与定向契约门完成；真实公开 catalog 运行待实际 release tag） +- 日期：2026-08-16 +- 关联 RFC：QL-RFC-0001 D-03、D-14、D-337、D-338、D-339 +- 关联 ADR：ADR-0427、ADR-0428、ADR-0429、ADR-0430 + +## 上下文 + +ADR-0430 已把 discovery、签名、provenance、release-set 与 OCI manifest 收敛到一个可离线复验的 three-file +consumption bundle；ADR-0429 的 deployment-lock materializer 却仍接受任意独立 `--release-set` 文件。两份文件即使内容相同， +materializer 也无法证明它读取的是刚刚通过 catalog ceremony 验真的那份 byte authority，输出中也没有 catalog immutable +reference、manifest digest 或 consumption report digest。文档约定不能替代机器约束。 + +直接让 release workflow 部署，或让 deployment lock 重新联网验签，都会混合发布、部署与网络 authority。把完整 Node、Cosign、 +GitHub CLI、regctl 或 Kustomize 下沉到低配路由器同样不成立。 + +## 决策 + +1. `ql3-deployment-lock-contract.cjs` 的 Local/Kubernetes create/audit CLI 删除松散 `--release-set` 输入，改为同时要求 + `--consumption-bundle` 与 exact `--source-repository`。旧参数是失败关闭的非法开放输入，不提供兼容旁路。 +2. materializer 首先调用 ADR-0430 的完整 offline bundle audit：目录必须是 canonical、current-owner、`0700`，且只能包含三项 + canonical/current-owner `0600` 文件；release-set、raw OCI manifest、reconstructed plan/receipt、六步 argv/transcript digest 与 + self-digest report 必须重新闭合。只有同一次 audit 实际读取的 release-set 对象可以继续进入 lock materialization，避免审计后 + 再从松散路径读取造成新的 TOCTOU 窗口。 +3. Local selection 与 Kubernetes lock schema 升为 v2，并写入同一 catalog authority：consumption schema、source repository、 + exact workflow identity、immutable catalog reference、manifest digest、consumption report digest、release-set digest 和 + `discoveryTagAuthority=none`。任一 identity、scope、owner、image count 或 digest 不一致均失败关闭。 +4. Kubernetes 被改写的 workload/Pod template 与固定 Plugin Package admission ConfigMap 除 release-set/version/revision 外，还写入 + catalog manifest 与 consumption report digest annotation。最终 apply 的 YAML 因而不能脱离其验真来源；lock report 继续绑定 + 输入/输出 manifest digest、角色闭包与自身 digest。 +5. offline audit 明确记录 `catalogConsumption=offline_reconstructed` 和 `externalToolResultsReplayed=false`。它验证已保存证据的一致性， + 不谎称重新执行过网络签名或 provenance verifier。 +6. 本 Gate 仍没有部署 action authority：不访问 registry/GitHub/Kubernetes API，不执行 Compose rollout 或 `kubectl apply`，不修改 + 数据库。Local/Cluster 的最终行动继续由独立、显式授权步骤完成。 + +## 部署与资源影响 + +- 不新增 workspace package、生产依赖、数据库、migration、SQL、Pool、Pod、controller、CRD、RBAC、listener、timer 或 watcher。 +- Node、regctl、Cosign、GitHub CLI 和 Kustomize 只存在于可信维护工作站。低配设备只接收 catalog-bound Local v2 selection 与 + immutable Local image reference，不下载 Cluster 镜像或加载集群依赖。 +- Cluster 复用既有离线 post-render 路径；新增字段只增加少量 JSON/YAML 字节，不增加运行期 CPU、内存或网络开销。 + +## 失败与恢复 + +- bundle 缺项、多项、symlink、权限/owner/路径漂移，release-set/manifest/report 任一字节漂移，以及 source identity 或 catalog + binding 不一致，都会在任何 output 创建前失败。 +- create 输出保持 `0600`、no-replace；结果未知时使用同一 bundle、identity、原 render 和原输出路径执行 audit，不改用裸 + release-set，也不手工删除或覆盖证据。 +- catalog discovery tag 移动不改变已绑定 immutable reference；若需要发布另一 digest，必须执行新的 online ceremony 并生成新的 + bundle/selection/lock，而不是修改旧报告。 + +## 被拒绝的替代方案 + +### 继续依赖文档规定同一 release-set 路径 + +拒绝。路径约定无法证明文件属于已验真的 three-file bundle，也无法被 CI 或 offline audit 强制执行。 + +### 在 materializer 中重新联网验签 + +拒绝。会扩大网络、凭据和工具面，并让离线重放不可用；ADR-0430 已提供职责单一的在线 ceremony。 + +### 把 catalog 工具安装到路由设备 + +拒绝。低资源目标不应承担供应链工作站成本；设备只消费由工作站生成的最小、digest-bound 结果。 + +### 验真成功后自动 apply + +拒绝。可信输入不等于部署授权，发布/验真身份不能自动获得生产 Local 或 Kubernetes mutation authority。 + +## 验证 + +- deployment-lock 与 catalog-consumption 联合正负契约覆盖 Local/Cluster、真实 four-overlay Kustomize render、bundle symlink/open + arguments、旧 `--release-set` 旁路、catalog/release-set mismatch、no-replace 与 output alias；完整定向发布链 123/123； +- 共享 supply-chain CI 已固定运行两个测试文件，删除任一门都会使 image-release 静态审计失败； +- 完整 backend 共 1,317 项，1,315 pass、2 条件 skip、0 fail；18-package clean build/test 退出 0，package boundary 仍为 + 18 packages，`singleSourcePackages=[]`、`shallowSourcePackages=[]`； +- release version、deployment lock surfaces、package boundary、cluster dependency、Edge import、Cluster/Worker deployment、image + release、Local image 与 Console distribution 共 10 项审计全部 compatible；14 档 Local artifact 全部 compatible，默认 + Edge/Standalone 为 2,589,890/2,589,968 bytes，application+AI 为 4,493,043/4,493,175 bytes，MCP 为 + 7,315,930/7,316,038 bytes； +- Cluster Admin pack dry-run 保持 250 files、271,238-byte tarball、1,690,196-byte unpacked； +- 本 Gate 不改变数据库或 HA 拓扑，复用紧邻发布 Gate 的 PostgreSQL 18.6 arm64 physical HA 基线，不把未重跑结果声明为本阶段 + 新证据。 diff --git a/docs/adr/README.md b/docs/adr/README.md index dd5b832d..c04c313b 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -434,6 +434,7 @@ | [ADR-0428](./ADR-0428-durable-oci-release-catalog.md) | 持久化 OCI Release Catalog 与独立部署验真 | Accepted | | [ADR-0429](./ADR-0429-offline-release-set-deployment-lock-materialization.md) | 离线 Release-set Deployment Lock 物化 | Accepted | | [ADR-0430](./ADR-0430-auditable-release-catalog-consumption-ceremony.md) | 可审计的 Release Catalog 消费工作站 Ceremony | Accepted（真实公开 catalog 运行待实际 release tag） | +| [ADR-0431](./ADR-0431-catalog-bound-deployment-lock-chain.md) | Catalog-bound Deployment Lock 证据链 | Accepted（真实公开 catalog 运行待实际 release tag） | ## 规则 diff --git a/docs/operations/ql3-release-set-deployment.md b/docs/operations/ql3-release-set-deployment.md index 0ec27cd6..c9235019 100644 --- a/docs/operations/ql3-release-set-deployment.md +++ b/docs/operations/ql3-release-set-deployment.md @@ -73,7 +73,6 @@ node scripts/ql3-release-catalog-consumption-ceremony.cjs \ --source-repository="${repository}" \ --output-directory="${bundle}" -release_set="${bundle}/qinglong3-release-set-${version}-${scope}.json" catalog_manifest="${bundle}/qinglong3-release-catalog-manifest-${version}-${scope}.json" consumption_report="${bundle}/qinglong3-release-catalog-consumption-${version}-${scope}.json" ``` @@ -87,9 +86,9 @@ ceremony，也不能与在线 ceremony 下载的文件混合后伪造成同一 t ## 生成离线 deployment lock -`inspect` 成功后，不要手工复制 digest，也不要直接修改仓库中的 Kustomize 占位符。deployment-lock -materializer 在可信工作站离线运行，只读取已经验证的 release set 与本地清单；它不访问 registry、不连接 Kubernetes -API，也不会执行 `kubectl apply`。 +`audit` 成功后，不要从 bundle 中抽出 release-set 再作为独立输入，不要手工复制 digest，也不要直接修改仓库中的 +Kustomize 占位符。deployment-lock materializer 在可信工作站离线运行，必须重新审计完整 three-file bundle，并让同一次审计 +读取的 release set 直接进入物化；它不访问 registry、不连接 Kubernetes API，也不会执行 `kubectl apply`。 ### Local / Compose @@ -105,7 +104,8 @@ node scripts/ql3-deployment-lock-contract.cjs \ --source-ref="${source_ref}" \ --release-scope="${scope}" \ --repository-owner="${owner}" \ - --release-set="${release_set}" \ + --source-repository="${repository}" \ + --consumption-bundle="${bundle}" \ --allow-root-service=false \ --output="${selection}" @@ -116,13 +116,15 @@ node scripts/ql3-deployment-lock-contract.cjs \ --source-ref="${source_ref}" \ --release-scope="${scope}" \ --repository-owner="${owner}" \ - --release-set="${release_set}" \ + --source-repository="${repository}" \ + --consumption-bundle="${bundle}" \ --allow-root-service=false \ --selection="${selection}" ``` -把已审计的 `service.image` 和 `service.allowRootService` 交给现有 Local private prepare/rollout 入口。selection -本身不修改 Compose 文件，也不启动容器。是否允许 root service 必须显式给出，不能由设备默认值推断。 +v2 selection 同时绑定 catalog immutable reference、manifest digest、consumption report digest 与 release-set digest。把已审计的 +`service.image` 和 `service.allowRootService` 交给现有 Local private prepare/rollout 入口。selection 本身不修改 Compose 文件， +也不启动容器。是否允许 root service 必须显式给出，不能由设备默认值推断。 ### Kubernetes / Cluster / Worker @@ -144,7 +146,8 @@ node scripts/ql3-deployment-lock-contract.cjs \ --source-ref="${source_ref}" \ --release-scope="${scope}" \ --repository-owner="${owner}" \ - --release-set="${release_set}" \ + --source-repository="${repository}" \ + --consumption-bundle="${bundle}" \ --manifest="${rendered}" \ --required-images=control \ --output-manifest="${locked}" \ @@ -157,7 +160,8 @@ node scripts/ql3-deployment-lock-contract.cjs \ --source-ref="${source_ref}" \ --release-scope="${scope}" \ --repository-owner="${owner}" \ - --release-set="${release_set}" \ + --source-repository="${repository}" \ + --consumption-bundle="${bundle}" \ --manifest="${rendered}" \ --locked-manifest="${locked}" \ --report="${lock_report}" \ @@ -166,9 +170,9 @@ node scripts/ql3-deployment-lock-contract.cjs \ materializer 只改写 Pod、Deployment、StatefulSet、DaemonSet、ReplicaSet、Job、CronJob 的 `containers`/`initContainers`/`ephemeralContainers`，以及固定名称 -`ql3-plugin-package-secret-action-admission` ConfigMap 的 `data.image`。每个改写资源及其 Pod template 都绑定 -release-set digest、source revision 与 version annotation；未知位置的完整 QingLong role image authority、畸形已知 -container image、缺少 required role、YAML alias/cycle/非 mapping、超限输入或已有输出文件都会失败关闭。 +`ql3-plugin-package-secret-action-admission` ConfigMap 的 `data.image`。每个改写资源及其 Pod template 都绑定 release-set、catalog +manifest、consumption report digest、source revision 与 version annotation；未知位置的完整 QingLong role image authority、畸形 +已知 container image、缺少 required role、YAML alias/cycle/非 mapping、超限输入或已有输出文件都会失败关闭。 审计成功并完成人工差异检查后，才由有权限的独立步骤执行 `kubectl apply -f "${locked}"`。不要直接 apply `${rendered}`，也不要使用 `kubectl apply -k` 绕过 deployment lock。 @@ -177,20 +181,20 @@ container image、缺少 required role、YAML alias/cycle/非 mapping、超限 1. 只接受已验证 Cosign exact workflow identity 与 GitHub source tag/revision provenance 的 catalog immutable reference；discovery tag 无 authority。 -2. `schema` 必须为 `qinglong/release-set@v1`；`release.version`、`release.sourceRef`、 - `release.sourceRevision`、`release.scope` 必须与变更单一致。 +2. materializer 只能接受完整 `qinglong/release-catalog-consumption-ceremony@v1` bundle，不能接受旧的松散 `--release-set`；其中 + `qinglong/release-set@v1` 的 `release.version`、`release.sourceRef`、`release.sourceRevision`、`release.scope` 必须与变更单一致。 3. 镜像集合必须与上表精确相等；每个 `reference` 必须是 digest reference，且 owner/repository 与部署目标一致。 -4. Kubernetes 必须先渲染 overlay，再用离线 post-render materializer 生成和复验 locked manifest；嵌套 overlay 的 - `newName`/digest 不是最终 authority。Local 必须生成并审计 service selection。两族最终都只能消费 release set 中的 - `@sha256:` reference。 +4. Kubernetes 必须先渲染 overlay，再用离线 post-render materializer 生成和复验 v2 locked manifest；嵌套 overlay 的 + `newName`/digest 不是最终 authority。Local 必须生成并审计 v2 service selection。两族输出都必须绑定同一 catalog manifest、 + consumption report 与 release-set digest，并且只能消费 release set 中的 `@sha256:` reference。 5. rollout 前再次确认 catalog receipt/immutable reference 与已检查文件一致。version/source/catalog tag 都只能用于 发现；部署始终以 release set 中的镜像 digest 为准。 ## 低资源设备 路由器或其他低配 Edge 设备不需要安装 Node、regctl、Cosign、GitHub CLI、Kustomize 或 materializer。维护者在可信工作站 -完成上述 ceremony 和 Local selection 审计，再向设备传输已检查的 canonical JSON，并只把 `local` family 的 immutable -image reference 写入 compose/rollout。 +完成上述 ceremony 和 Local v2 selection 审计，再向设备传输已检查的 catalog-bound canonical JSON，并只把 `local` family 的 +immutable image reference 写入 compose/rollout。 设备不下载 Cluster 四镜像，也不加载 Kubernetes、CloudNativePG、PostgreSQL driver 或 Worker 私有发布证据。 如果设备本身不运行容器 registry client，可由工作站按 digest 拉取并通过既有离线交付渠道传送镜像；离线包的哈希与 diff --git a/scripts/ql3-deployment-lock-contract.cjs b/scripts/ql3-deployment-lock-contract.cjs index f4e467a6..66bbeb23 100644 --- a/scripts/ql3-deployment-lock-contract.cjs +++ b/scripts/ql3-deployment-lock-contract.cjs @@ -6,11 +6,16 @@ const crypto = require('node:crypto'); const fs = require('node:fs'); const path = require('node:path'); const yaml = require('js-yaml'); +const { + SCHEMA: CATALOG_CONSUMPTION_SCHEMA, + auditCeremonyBundle, + catalogIdentity, +} = require('./ql3-release-catalog-consumption-ceremony.cjs'); const { inspectReleaseSet } = require('./ql3-release-set-contract.cjs'); const DEFAULT_ROOT = path.resolve(__dirname, '..'); -const LOCAL_SELECTION_SCHEMA = 'qinglong/local-compose-release-image@v1'; -const KUBERNETES_LOCK_SCHEMA = 'qinglong/kubernetes-deployment-lock@v1'; +const LOCAL_SELECTION_SCHEMA = 'qinglong/local-compose-release-image@v2'; +const KUBERNETES_LOCK_SCHEMA = 'qinglong/kubernetes-deployment-lock@v2'; const MAX_RELEASE_SET_BYTES = 1024 * 1024; const MAX_MANIFEST_BYTES = 8 * 1024 * 1024; const MAX_RESOURCE_COUNT = 2048; @@ -137,6 +142,41 @@ function inspectInputReleaseSet(releaseSet, options) { }); } +function catalogAuthority(releaseSet, options) { + const consumption = options.consumption; + const manifestDigest = consumption?.catalogManifestDigest; + const expectedCatalog = catalogIdentity(options); + if ( + consumption === null || + typeof consumption !== 'object' || + consumption.compatible !== true || + consumption.releaseScope !== options.releaseScope || + consumption.sourceRepository !== options.sourceRepository || + consumption.workflowIdentity !== expectedCatalog.workflowIdentity || + consumption.releaseSetDigest !== releaseSet.releaseSetDigest || + !/^sha256:[a-f0-9]{64}$/u.test(manifestDigest || '') || + consumption.immutableReference !== + `${expectedCatalog.repository}@${manifestDigest}` || + consumption.imageCount !== releaseSet.images.length || + consumption.discoveryTagAuthority !== 'none' || + consumption.externalToolResultsReplayed !== false || + consumption.deploymentMutation !== false || + !/^sha256:[a-f0-9]{64}$/u.test(consumption.contentDigest || '') + ) { + fail('release catalog consumption authority is invalid'); + } + return Object.freeze({ + schema: CATALOG_CONSUMPTION_SCHEMA, + sourceRepository: consumption.sourceRepository, + workflowIdentity: consumption.workflowIdentity, + immutableReference: consumption.immutableReference, + manifestDigest, + consumptionReportDigest: consumption.contentDigest, + releaseSetDigest: consumption.releaseSetDigest, + discoveryTagAuthority: 'none', + }); +} + function imageByName(releaseSet, name) { const matches = releaseSet.images.filter((entry) => entry.name === name); if (matches.length !== 1) fail(`release image is unavailable: ${name}`); @@ -145,6 +185,7 @@ function imageByName(releaseSet, name) { function createLocalSelection(releaseSet, options) { const inspection = inspectInputReleaseSet(releaseSet, options); + const catalog = catalogAuthority(releaseSet, options); if (!['local', 'all'].includes(options.releaseScope)) { fail('local selection requires a local or all release set'); } @@ -157,6 +198,7 @@ function createLocalSelection(releaseSet, options) { schema: LOCAL_SELECTION_SCHEMA, release: { ...releaseSet.release }, releaseSetDigest: releaseSet.releaseSetDigest, + catalog, deploymentFamily: 'local', service: { kind: 'compose', @@ -166,6 +208,8 @@ function createLocalSelection(releaseSet, options) { verification: { releaseSet: inspection.verification, sourceRecordsReplayed: inspection.sourceRecordsReplayed, + catalogConsumption: 'offline_reconstructed', + externalToolResultsReplayed: false, networkAccess: false, deploymentMutation: false, }, @@ -186,6 +230,8 @@ function auditLocalSelection(actual, releaseSet, options) { deploymentFamily: 'local', releaseSetDigest: actual.releaseSetDigest, selectionDigest: actual.selectionDigest, + catalogManifestDigest: actual.catalog.manifestDigest, + immutableReference: actual.catalog.immutableReference, image: actual.service.image, networkAccess: false, deploymentMutation: false, @@ -310,7 +356,7 @@ function podSpecFor(resource) { return undefined; } -function ensureAnnotations(target, releaseSet) { +function ensureAnnotations(target, releaseSet, catalog) { if (target === null || typeof target !== 'object' || Array.isArray(target)) { fail('rewritten resource metadata is invalid'); } @@ -329,6 +375,9 @@ function ensureAnnotations(target, releaseSet) { metadata.annotations = { ...(metadata.annotations ?? {}), 'qinglong.io/release-set-digest': releaseSet.releaseSetDigest, + 'qinglong.io/release-catalog-manifest-digest': catalog.manifestDigest, + 'qinglong.io/release-catalog-report-digest': + catalog.consumptionReportDigest, 'qinglong.io/release-source-revision': releaseSet.release.sourceRevision, 'qinglong.io/release-version': releaseSet.release.version, }; @@ -407,7 +456,12 @@ function scanForUnhandledRoleImages( } } -function rewriteKubernetesResources(resources, releaseSet, requiredImages) { +function rewriteKubernetesResources( + resources, + releaseSet, + requiredImages, + catalog, +) { const references = Object.fromEntries( ROLE_ORDER.map((role) => [role, imageByName(releaseSet, role).reference]), ); @@ -459,7 +513,7 @@ function rewriteKubernetesResources(resources, releaseSet, requiredImages) { changed += 1; } if (changed > 0) { - ensureAnnotations(resource, releaseSet); + ensureAnnotations(resource, releaseSet, catalog); const template = resource.kind === 'CronJob' ? resource.spec?.jobTemplate?.spec?.template @@ -470,7 +524,7 @@ function rewriteKubernetesResources(resources, releaseSet, requiredImages) { ) ? resource.spec?.template : undefined; - if (template) ensureAnnotations(template, releaseSet); + if (template) ensureAnnotations(template, releaseSet, catalog); changedResources += 1; } } @@ -493,6 +547,7 @@ function rewriteKubernetesResources(resources, releaseSet, requiredImages) { function createKubernetesLock(releaseSet, manifestContents, options) { const inspection = inspectInputReleaseSet(releaseSet, options); + const catalog = catalogAuthority(releaseSet, options); if (!['cluster', 'all'].includes(options.releaseScope)) { fail('Kubernetes materialization requires a cluster or all release set'); } @@ -502,6 +557,7 @@ function createKubernetesLock(releaseSet, manifestContents, options) { parsed, releaseSet, requiredImages, + catalog, ); const outputManifest = renderManifest(rewritten.resources); if (Buffer.byteLength(outputManifest, 'utf8') > MAX_MANIFEST_BYTES) { @@ -512,6 +568,7 @@ function createKubernetesLock(releaseSet, manifestContents, options) { schema: KUBERNETES_LOCK_SCHEMA, release: { ...releaseSet.release }, releaseSetDigest: releaseSet.releaseSetDigest, + catalog, deploymentFamily: 'cluster', requiredImages: [...requiredImages], imageOccurrences: ROLE_ORDER.map((name) => ({ @@ -529,6 +586,8 @@ function createKubernetesLock(releaseSet, manifestContents, options) { verification: { releaseSet: inspection.verification, sourceRecordsReplayed: inspection.sourceRecordsReplayed, + catalogConsumption: 'offline_reconstructed', + externalToolResultsReplayed: false, unknownImageAuthorities: 0, mutableQingLongImages: 0, networkAccess: false, @@ -561,6 +620,8 @@ function auditKubernetesLock( deploymentFamily: 'cluster', releaseSetDigest: actualReport.releaseSetDigest, lockDigest: actualReport.lockDigest, + catalogManifestDigest: actualReport.catalog.manifestDigest, + immutableReference: actualReport.catalog.immutableReference, outputManifestDigest: actualReport.manifest.outputDigest, requiredImages: Object.freeze([...actualReport.requiredImages]), networkAccess: false, @@ -642,12 +703,13 @@ function parseArguments(argv) { } const identity = [ 'mode', + 'consumption-bundle', 'release-scope', 'repository-owner', + 'source-repository', 'source-ref', 'source-revision', 'version', - 'release-set', ]; const expected = values.mode === 'local-create' @@ -685,7 +747,8 @@ function parseArguments(argv) { sourceRef: values['source-ref'], releaseScope: values['release-scope'], repositoryOwner: values['repository-owner'], - releaseSet: values['release-set'], + sourceRepository: values['source-repository'], + consumptionBundle: values['consumption-bundle'], ...(values['allow-root-service'] ? { allowRootService: @@ -722,13 +785,14 @@ function runCli(argv, root = DEFAULT_ROOT, output = process.stdout) { output.write(canonicalJson(audit)); return audit; } - const releaseSet = readCanonicalJson( - options.releaseSet, - 'release set', - MAX_RELEASE_SET_BYTES, - ).value; + const consumption = auditCeremonyBundle({ + ...options, + outputDirectory: options.consumptionBundle, + }); + const releaseSet = consumption.releaseSet; + const boundOptions = Object.freeze({ ...options, consumption }); if (options.mode === 'local-create') { - const selection = createLocalSelection(releaseSet, options); + const selection = createLocalSelection(releaseSet, boundOptions); const target = preflightOutput(options.output, 'output'); writeNoReplace(target, canonicalJson(selection)); output.write(canonicalJson(selection)); @@ -740,7 +804,7 @@ function runCli(argv, root = DEFAULT_ROOT, output = process.stdout) { 'local selection', MAX_RELEASE_SET_BYTES, ).value; - const audit = auditLocalSelection(selection, releaseSet, options); + const audit = auditLocalSelection(selection, releaseSet, boundOptions); output.write(canonicalJson(audit)); return audit; } @@ -758,7 +822,11 @@ function runCli(argv, root = DEFAULT_ROOT, output = process.stdout) { if (manifestTarget === reportTarget) { fail('output manifest and report paths must differ'); } - const created = createKubernetesLock(releaseSet, sourceManifest, options); + const created = createKubernetesLock( + releaseSet, + sourceManifest, + boundOptions, + ); writeNoReplace(manifestTarget, created.outputManifest); writeNoReplace(reportTarget, canonicalJson(created.report)); output.write(canonicalJson(created.report)); @@ -779,7 +847,7 @@ function runCli(argv, root = DEFAULT_ROOT, output = process.stdout) { report, releaseSet, sourceManifest, - options, + boundOptions, ); output.write(canonicalJson(audit)); return audit; diff --git a/scripts/ql3-release-catalog-consumption-ceremony.cjs b/scripts/ql3-release-catalog-consumption-ceremony.cjs index f2a2dfd2..aceb80df 100644 --- a/scripts/ql3-release-catalog-consumption-ceremony.cjs +++ b/scripts/ql3-release-catalog-consumption-ceremony.cjs @@ -812,6 +812,8 @@ function auditCeremonyBundle(options) { return Object.freeze({ compatible: true, releaseScope: identity.releaseScope, + sourceRepository: identity.sourceRepository, + workflowIdentity: catalog.workflowIdentity, releaseSetDigest: releaseSet.value.releaseSetDigest, catalogManifestDigest: manifestDigest, immutableReference: `${catalog.repository}@${manifestDigest}`, @@ -820,6 +822,7 @@ function auditCeremonyBundle(options) { externalToolResultsReplayed: false, deploymentMutation: false, contentDigest: expected.contentDigest, + releaseSet: releaseSet.value, }); } diff --git a/test/back/ql3DeploymentLockContract.test.cjs b/test/back/ql3DeploymentLockContract.test.cjs index 36b1ad71..abeaca76 100644 --- a/test/back/ql3DeploymentLockContract.test.cjs +++ b/test/back/ql3DeploymentLockContract.test.cjs @@ -1,6 +1,7 @@ 'use strict'; const assert = require('node:assert/strict'); +const crypto = require('node:crypto'); const fs = require('node:fs'); const os = require('node:os'); const path = require('node:path'); @@ -16,6 +17,17 @@ const { parseArguments, runCli, } = require('../../scripts/ql3-deployment-lock-contract.cjs'); +const { + ARTIFACT_TYPE, + FILE_MEDIA_TYPE, + OCI_EMPTY_CONFIG_DIGEST, + OCI_EMPTY_CONFIG_MEDIA_TYPE, + OCI_MANIFEST_MEDIA_TYPE, + createCatalogPlan, +} = require('../../scripts/ql3-release-catalog-contract.cjs'); +const { + runCeremony, +} = require('../../scripts/ql3-release-catalog-consumption-ceremony.cjs'); const { createReleaseSet, createVerifiedImageRecord, @@ -34,6 +46,7 @@ const identity = Object.freeze({ sourceRevision: 'd'.repeat(40), sourceRef: `refs/tags/v${version}`, repositoryOwner: 'qinglong-release', + sourceRepository: 'qinglong-release/qinglong', }); const roleOrder = Object.freeze(['control', 'control-ai', 'admin', 'worker']); @@ -85,10 +98,35 @@ function releaseSet(scope) { }); } -function options(scope, extra = {}) { +function sha256(value) { + return `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`; +} + +function consumptionAuthority(set) { + const manifestDigest = sha256( + Buffer.from(`catalog:${set.release.scope}`, 'utf8'), + ); + return Object.freeze({ + compatible: true, + releaseScope: set.release.scope, + sourceRepository: identity.sourceRepository, + workflowIdentity: `https://github.com/${identity.sourceRepository}/.github/workflows/ql3-image-release.yml@${identity.sourceRef}`, + releaseSetDigest: set.releaseSetDigest, + catalogManifestDigest: manifestDigest, + immutableReference: `ghcr.io/${identity.repositoryOwner}/qinglong3-release-catalog@${manifestDigest}`, + imageCount: set.images.length, + discoveryTagAuthority: 'none', + externalToolResultsReplayed: false, + deploymentMutation: false, + contentDigest: sha256(Buffer.from(`report:${set.release.scope}`, 'utf8')), + }); +} + +function options(set, extra = {}) { return Object.freeze({ ...identity, - releaseScope: scope, + releaseScope: set.release.scope, + consumption: consumptionAuthority(set), ...extra, }); } @@ -189,12 +227,88 @@ function temporaryDirectory(t) { return directory; } -function writeCanonical(filePath, value) { - fs.writeFileSync(filePath, `${JSON.stringify(value)}\n`, { mode: 0o600 }); +function catalogManifest(set) { + const plan = createCatalogPlan(set, { + ...identity, + releaseScope: set.release.scope, + }); + return { + schemaVersion: 2, + mediaType: OCI_MANIFEST_MEDIA_TYPE, + artifactType: ARTIFACT_TYPE, + config: { + mediaType: OCI_EMPTY_CONFIG_MEDIA_TYPE, + digest: OCI_EMPTY_CONFIG_DIGEST, + size: 2, + }, + layers: [ + { + mediaType: FILE_MEDIA_TYPE, + digest: plan.releaseSet.contentDigest, + size: plan.releaseSet.bytes, + annotations: { + 'org.opencontainers.image.title': plan.releaseSet.fileName, + }, + }, + ], + annotations: { ...plan.catalog.annotations }, + }; } -function kubernetesOptions(extra = {}) { - return options('cluster', { +function consumptionBundle(t, parent, name, set) { + const toolRoot = path.join(parent, `${name}-tools`); + fs.mkdirSync(toolRoot, { mode: 0o700 }); + const releaseText = `${JSON.stringify(set)}\n`; + const manifestText = JSON.stringify(catalogManifest(set)); + const manifestDigest = sha256(Buffer.from(manifestText, 'utf8')); + const tools = {}; + for (const toolName of ['regctl', 'cosign', 'gh']) { + const toolPath = path.join(toolRoot, toolName); + const behavior = + toolName === 'regctl' + ? ` +if (args[0] === 'image' && args[1] === 'digest') { + process.stdout.write(${JSON.stringify(`${manifestDigest}\n`)}); +} else if (args[0] === 'artifact' && args[1] === 'get') { + process.stdout.write(${JSON.stringify(releaseText)}); +} else if (args[0] === 'manifest' && args[1] === 'get') { + process.stdout.write(${JSON.stringify(manifestText)}); +} else { + process.exitCode = 7; +} +` + : ''; + fs.writeFileSync( + toolPath, + `#!${process.execPath}\n'use strict';\nconst args = process.argv.slice(2);\n${behavior}`, + { mode: 0o700 }, + ); + tools[toolName] = toolPath; + } + const tokenFile = path.join(toolRoot, 'github-token'); + fs.writeFileSync(tokenFile, 'github_pat_deployment_lock_fixture', { + mode: 0o600, + }); + const outputDirectory = path.join(parent, `${name}-bundle`); + runCeremony({ + ...identity, + releaseScope: set.release.scope, + outputDirectory, + regctl: tools.regctl, + cosign: tools.cosign, + gh: tools.gh, + githubTokenFile: tokenFile, + }); + t.after(() => { + if (fs.existsSync(outputDirectory)) { + fs.rmSync(outputDirectory, { recursive: true, force: true }); + } + }); + return outputDirectory; +} + +function kubernetesOptions(set, extra = {}) { + return options(set, { requiredImages: roleOrder.join(','), ...extra, }); @@ -205,21 +319,36 @@ test('selects one immutable Local Compose image without adding device work', () const set = releaseSet(scope); const selection = createLocalSelection( set, - options(scope, { allowRootService: false }), + options(set, { allowRootService: false }), ); assert.equal(selection.deploymentFamily, 'local'); + assert.equal(selection.schema, 'qinglong/local-compose-release-image@v2'); assert.equal(selection.releaseSetDigest, set.releaseSetDigest); + assert.equal( + selection.catalog.releaseSetDigest, + selection.releaseSetDigest, + ); + assert.match( + selection.catalog.immutableReference, + /^ghcr\.io\/qinglong-release\/qinglong3-release-catalog@sha256:[a-f0-9]{64}$/u, + ); + assert.equal(selection.catalog.discoveryTagAuthority, 'none'); assert.equal(selection.service.kind, 'compose'); assert.equal(selection.service.image, references(set).local); assert.equal(selection.service.allowRootService, false); assert.equal(selection.verification.networkAccess, false); assert.equal(selection.verification.deploymentMutation, false); + assert.equal( + selection.verification.catalogConsumption, + 'offline_reconstructed', + ); + assert.equal(selection.verification.externalToolResultsReplayed, false); assert.match(selection.selectionDigest, /^sha256:[a-f0-9]{64}$/u); assert.equal( auditLocalSelection( selection, set, - options(scope, { allowRootService: false }), + options(set, { allowRootService: false }), ).compatible, true, ); @@ -232,18 +361,18 @@ test('Local selection rejects cluster scope, implicit root policy and drift', () () => createLocalSelection( clusterSet, - options('cluster', { allowRootService: false }), + options(clusterSet, { allowRootService: false }), ), /local or all release set/, ); const localSet = releaseSet('local'); assert.throws( - () => createLocalSelection(localSet, options('local')), + () => createLocalSelection(localSet, options(localSet)), /explicit boolean/, ); const selection = createLocalSelection( localSet, - options('local', { allowRootService: true }), + options(localSet, { allowRootService: true }), ); const drifted = JSON.parse(JSON.stringify(selection)); drifted.service.image = 'ghcr.io/example/qinglong3-local:latest'; @@ -252,19 +381,45 @@ test('Local selection rejects cluster scope, implicit root policy and drift', () auditLocalSelection( drifted, localSet, - options('local', { allowRootService: true }), + options(localSet, { allowRootService: true }), ), /differs from the verified release set/, ); }); +test('deployment materialization rejects missing or mismatched catalog authority', () => { + const set = releaseSet('local'); + assert.throws( + () => + createLocalSelection(set, { + ...identity, + releaseScope: 'local', + allowRootService: false, + }), + /catalog consumption authority is invalid/, + ); + const drifted = { + ...consumptionAuthority(set), + contentDigest: `sha256:${'0'.repeat(64)}`, + releaseSetDigest: `sha256:${'1'.repeat(64)}`, + }; + assert.throws( + () => + createLocalSelection(set, { + ...options(set, { allowRootService: false }), + consumption: drifted, + }), + /catalog consumption authority is invalid/, + ); +}); + test('materializes every supported Kubernetes image authority from one release set', () => { const set = releaseSet('cluster'); const expectedReferences = references(set); const created = createKubernetesLock( set, fixtureManifest(), - kubernetesOptions(), + kubernetesOptions(set), ); const resources = []; yaml.loadAll(created.outputManifest, (resource) => resources.push(resource)); @@ -288,6 +443,8 @@ test('materializes every supported Kubernetes image authority from one release s ], ); assert.equal(created.report.manifest.resources, 6); + assert.equal(created.report.schema, 'qinglong/kubernetes-deployment-lock@v2'); + assert.equal(created.report.catalog.releaseSetDigest, set.releaseSetDigest); assert.equal(created.report.manifest.changedResources, 5); assert.equal(created.report.manifest.admissionAuthorityCount, 1); assert.equal(created.report.verification.unknownImageAuthorities, 0); @@ -314,6 +471,18 @@ test('materializes every supported Kubernetes image authority from one release s resource.metadata.annotations['qinglong.io/release-set-digest'], set.releaseSetDigest, ); + assert.equal( + resource.metadata.annotations[ + 'qinglong.io/release-catalog-manifest-digest' + ], + created.report.catalog.manifestDigest, + ); + assert.equal( + resource.metadata.annotations[ + 'qinglong.io/release-catalog-report-digest' + ], + created.report.catalog.consumptionReportDigest, + ); } assert.equal( created.outputManifest.includes('qinglong3-cluster-control:source'), @@ -325,7 +494,7 @@ test('materializes every supported Kubernetes image authority from one release s created.report, set, fixtureManifest(), - kubernetesOptions(), + kubernetesOptions(set), ).compatible, true, ); @@ -336,7 +505,7 @@ test('Kubernetes materialization rejects unsupported scope and incomplete role c assert.throws( () => createKubernetesLock(localSet, fixtureManifest(), { - ...options('local'), + ...options(localSet), requiredImages: 'control', }), /cluster or all release set/, @@ -347,7 +516,12 @@ test('Kubernetes materialization rejects unsupported scope and incomplete role c '', ); assert.throws( - () => createKubernetesLock(clusterSet, withoutWorker, kubernetesOptions()), + () => + createKubernetesLock( + clusterSet, + withoutWorker, + kubernetesOptions(clusterSet), + ), /required image was not rendered: worker/, ); }); @@ -358,7 +532,7 @@ test('rejects mutable, malformed and hidden QingLong image authorities', () => { references(set).control }\n`; assert.throws( - () => createKubernetesLock(set, hidden, kubernetesOptions()), + () => createKubernetesLock(set, hidden, kubernetesOptions(set)), /unhandled QingLong image authority: data.image/, ); assert.throws( @@ -369,7 +543,7 @@ test('rejects mutable, malformed and hidden QingLong image authorities', () => { 'qinglong3-cluster-control@sha256:', 'qinglong3-cluster-control-not-an-image@sha256:', ), - kubernetesOptions(), + kubernetesOptions(set), ), /unhandled QingLong image authority|container image is malformed/, ); @@ -381,7 +555,7 @@ test('rejects mutable, malformed and hidden QingLong image authorities', () => { 'qinglong3-worker:source', 'qinglong3-worker', ), - kubernetesOptions(), + kubernetesOptions(set), ), /container image is malformed/, ); @@ -394,7 +568,7 @@ test('rejects unsafe YAML structure and invalid admission authority', () => { createKubernetesLock( set, 'apiVersion: v1\nkind: Pod\nkind: Job\n', - kubernetesOptions({ requiredImages: 'control' }), + kubernetesOptions(set, { requiredImages: 'control' }), ), /duplicate-free YAML/, ); @@ -403,7 +577,7 @@ test('rejects unsafe YAML structure and invalid admission authority', () => { createKubernetesLock( set, '- not\n- a\n- resource\n', - kubernetesOptions({ requiredImages: 'control' }), + kubernetesOptions(set, { requiredImages: 'control' }), ), /resource must be one mapping/, ); @@ -415,7 +589,7 @@ test('rejects unsafe YAML structure and invalid admission authority', () => { 'data:\n image: qinglong3-cluster-admin', 'data:\n image: busybox', ), - kubernetesOptions(), + kubernetesOptions(set), ), /admission image authority is invalid/, ); @@ -426,7 +600,7 @@ test('audit detects source, locked manifest and report drift', () => { const created = createKubernetesLock( set, fixtureManifest(), - kubernetesOptions(), + kubernetesOptions(set), ); const report = JSON.parse(JSON.stringify(created.report)); report.manifest.resources += 1; @@ -437,7 +611,7 @@ test('audit detects source, locked manifest and report drift', () => { report, set, fixtureManifest(), - kubernetesOptions(), + kubernetesOptions(set), ), /differs from the verified release set/, ); @@ -448,7 +622,7 @@ test('audit detects source, locked manifest and report drift', () => { created.report, set, fixtureManifest(), - kubernetesOptions(), + kubernetesOptions(set), ), /differs from the verified release set/, ); @@ -459,7 +633,7 @@ test('audit detects source, locked manifest and report drift', () => { created.report, set, `${fixtureManifest()}\n`, - kubernetesOptions(), + kubernetesOptions(set), ), /differs from the verified release set/, ); @@ -469,16 +643,16 @@ test('CLI creates and audits no-replace Local and Kubernetes outputs', (t) => { const directory = temporaryDirectory(t); const output = { write() {} }; const localSet = releaseSet('local'); - const localSetPath = path.join(directory, 'local-set.json'); + const localBundle = consumptionBundle(t, directory, 'local', localSet); const selectionPath = path.join(directory, 'selection.json'); - writeCanonical(localSetPath, localSet); const localIdentity = [ `--version=${version}`, `--source-revision=${identity.sourceRevision}`, `--source-ref=${identity.sourceRef}`, '--release-scope=local', `--repository-owner=${identity.repositoryOwner}`, - `--release-set=${localSetPath}`, + `--source-repository=${identity.sourceRepository}`, + `--consumption-bundle=${localBundle}`, '--allow-root-service=false', ]; runCli( @@ -506,11 +680,10 @@ test('CLI creates and audits no-replace Local and Kubernetes outputs', (t) => { ); const clusterSet = releaseSet('cluster'); - const clusterSetPath = path.join(directory, 'cluster-set.json'); + const clusterBundle = consumptionBundle(t, directory, 'cluster', clusterSet); const sourcePath = path.join(directory, 'rendered.yaml'); const lockedPath = path.join(directory, 'locked.yaml'); const reportPath = path.join(directory, 'lock.json'); - writeCanonical(clusterSetPath, clusterSet); fs.writeFileSync(sourcePath, fixtureManifest(), { mode: 0o600 }); const clusterIdentity = [ `--version=${version}`, @@ -518,7 +691,8 @@ test('CLI creates and audits no-replace Local and Kubernetes outputs', (t) => { `--source-ref=${identity.sourceRef}`, '--release-scope=cluster', `--repository-owner=${identity.repositoryOwner}`, - `--release-set=${clusterSetPath}`, + `--source-repository=${identity.sourceRepository}`, + `--consumption-bundle=${clusterBundle}`, `--manifest=${sourcePath}`, `--required-images=${roleOrder.join(',')}`, ]; @@ -551,10 +725,10 @@ test('CLI creates and audits no-replace Local and Kubernetes outputs', (t) => { test('CLI rejects symlinks, open arguments, output aliasing and policy ambiguity', (t) => { const directory = temporaryDirectory(t); - const localSetPath = path.join(directory, 'local-set.json'); - const linkedSetPath = path.join(directory, 'linked-set.json'); - writeCanonical(localSetPath, releaseSet('local')); - fs.symlinkSync(localSetPath, linkedSetPath); + const localSet = releaseSet('local'); + const localBundle = consumptionBundle(t, directory, 'local', localSet); + const linkedBundle = path.join(directory, 'linked-bundle'); + fs.symlinkSync(localBundle, linkedBundle, 'dir'); const base = [ '--mode=local-create', `--version=${version}`, @@ -562,13 +736,14 @@ test('CLI rejects symlinks, open arguments, output aliasing and policy ambiguity `--source-ref=${identity.sourceRef}`, '--release-scope=local', `--repository-owner=${identity.repositoryOwner}`, - `--release-set=${linkedSetPath}`, + `--source-repository=${identity.sourceRepository}`, + `--consumption-bundle=${linkedBundle}`, '--allow-root-service=false', `--output=${path.join(directory, 'selection.json')}`, ]; assert.throws( () => runCli(base, root, { write() {} }), - /canonical regular file/, + /canonical directory/, ); assert.throws( () => parseArguments([...base, '--extra=value']), @@ -585,11 +760,22 @@ test('CLI rejects symlinks, open arguments, output aliasing and policy ambiguity ), /must be true or false/, ); + assert.throws( + () => + parseArguments( + base.map((argument) => + argument.startsWith('--consumption-bundle=') + ? `--release-set=${path.join(directory, 'loose-release-set.json')}` + : argument, + ), + ), + /arguments are invalid/, + ); - const clusterSetPath = path.join(directory, 'cluster-set.json'); + const clusterSet = releaseSet('cluster'); + const clusterBundle = consumptionBundle(t, directory, 'cluster', clusterSet); const sourcePath = path.join(directory, 'rendered.yaml'); const aliasedOutput = path.join(directory, 'same-output'); - writeCanonical(clusterSetPath, releaseSet('cluster')); fs.writeFileSync(sourcePath, fixtureManifest(), { mode: 0o600 }); assert.throws( () => @@ -601,7 +787,8 @@ test('CLI rejects symlinks, open arguments, output aliasing and policy ambiguity `--source-ref=${identity.sourceRef}`, '--release-scope=cluster', `--repository-owner=${identity.repositoryOwner}`, - `--release-set=${clusterSetPath}`, + `--source-repository=${identity.sourceRepository}`, + `--consumption-bundle=${clusterBundle}`, `--manifest=${sourcePath}`, `--required-images=${roleOrder.join(',')}`, `--output-manifest=${aliasedOutput}`, @@ -636,6 +823,19 @@ test('source-surface audit freezes every reviewed cluster and worker authority', ); }); +test('deployment-lock CLI cannot regress to a loose release-set input', () => { + const source = fs.readFileSync( + path.join(root, 'scripts/ql3-deployment-lock-contract.cjs'), + 'utf8', + ); + assert.match(source, /auditCeremonyBundle\(/u); + assert.match(source, /'consumption-bundle'/u); + assert.match(source, /'source-repository'/u); + assert.doesNotMatch(source, /['"]release-set['"]/u); + assert.match(source, /qinglong\/local-compose-release-image@v2/u); + assert.match(source, /qinglong\/kubernetes-deployment-lock@v2/u); +}); + test( 'real Kustomize renders are locked after nested overlay transforms', { skip: kubectlPath ? false : 'kubectl is unavailable' }, @@ -678,7 +878,7 @@ test( const created = createKubernetesLock( set, rendered.stdout, - kubernetesOptions({ + kubernetesOptions(set, { requiredImages: entry.requiredImages.join(','), }), );