@fateforge/archery-cli 1.0.5 → 1.0.6

package/.agent/CLI-SPEC.md

@@ -134,6 +134,7 @@ Error codes and exit codes must align:
 - `E_CONFLICT` -> 6
 - `E_NETWORK` / `E_RATE_LIMITED` / `E_SERVER` -> 7
 - `E_TIMEOUT` -> 8
+- `E_INTEGRITY` -> 1 (release integrity failure: missing/invalid signature or checksum mismatch; **non-retryable**, see §14)
 - `E_HUMAN_REQUIRED` -> 9 (optional, only when §16.3 is enabled)
 
 When the failure comes from an upstream HTTP call, map the status onto the
@@ -635,17 +636,31 @@ Version notification contract:
 
 Release verification baseline:
 
-- Verify the archive/package against `checksums.txt`; checksum mismatch, missing
-  checksum file, or missing archive entry fails closed.
-- Signed releases should sign `checksums.txt` with Sigstore/Cosign keyless
-  signing from the tagged GitHub Actions release workflow. Verifiers should
-  validate the bundle against the expected repository workflow identity and the
-  GitHub OIDC issuer.
-- Update results carry `signature_status` (a short string describing where
-  release integrity verification happened: e.g. `verified`, `not_checked`,
-  `handled_by_npm_installer`, `manual_release_verification_required`) and
-  `signature_verified` (true only when local Sigstore verification actually
-  ran and succeeded). Never imply checksum verification is a signature.
+- **Mandatory signature verification, no skip path**: the binary self-update path
+  MUST verify the Sigstore signature on `checksums.txt` in-process, then verify
+  the archive SHA256 against it. A missing signature bundle, a signature that does
+  not verify, or a checksum mismatch all fail closed — there is no "can't verify,
+  proceed anyway" degradation. The whole chain surfaces `E_INTEGRITY` (exit 1,
+  non-retryable): a forged or corrupt release is not a transient blip to retry.
+- **Verifier embedded, no user-environment dependency**: verification happens
+  inside the tool binary (Go via `sigstore-go`, Python inside the frozen binary
+  via `sigstore`) with **no external cosign** and nothing pre-installed on the
+  machine. The TUF trust root is bootstrapped from the library's embedded
+  `root.json`, not fetched on first-use trust (TOFU).
+- **New bundle format**: the signing side produces a Sigstore protobuf bundle
+  (`checksums.txt.sigstore.json`) via `cosign sign-blob --new-bundle-format`, which
+  the in-process verifier consumes; the legacy cosign bundle format is not accepted.
+- **Identity binding**: verifiers bind the certificate SAN to this repo's tagged
+  release workflow (`…/release.yml@refs/tags/v*`, anchored `^…$`) and validate the
+  GitHub OIDC issuer. When the target tag is known, pin the exact identity (stronger
+  than a regexp).
+- **Cross-language parity**: Go binaries and Python frozen binaries follow the same
+  self-update contract — download archive → in-process signature verify → checksum
+  → replace binary. Package managers do not own integrity.
+- Update results carry `signature_status` (`verified` on success; any failure exits
+  via the error envelope) and `signature_verified` (true only when in-process
+  Sigstore verification actually ran and succeeded). Never imply checksum
+  verification is a signature.
 
 - After `update --confirm <token>` succeeds, return `previous_version` and `current_version` in `data`.
 - Also hint in the result: `run "changelog --since <previous_version>" to see what changed`.

package/.agent/CLI-SPEC_zh.md

@@ -131,6 +131,7 @@
 - `E_CONFLICT` -> 6
 - `E_NETWORK` / `E_RATE_LIMITED` / `E_SERVER` -> 7
 - `E_TIMEOUT` -> 8
+- `E_INTEGRITY` -> 1（发布完整性失败：签名缺失/无效或 checksum 不符；**非重试**，见 §14）
 - `E_HUMAN_REQUIRED` -> 9（可选，仅启用 §16.3 时）
 
 当错误来自上游 HTTP 调用时，按状态码映射到错误码，让 agent 能从 `error.code` +
@@ -583,9 +584,12 @@ update 必须遵守的契约：
 
 release 校验基线：
 
-- 按 `checksums.txt` 校验归档/包；checksum 不匹配、缺失 checksum 文件、或缺少当前归档条目，都必须失败关闭。
-- 已签名 release 应由 tagged GitHub Actions release workflow 使用 Sigstore/Cosign keyless 模式签署 `checksums.txt`。验证端应绑定到预期仓库 workflow 身份和 GitHub OIDC issuer。
-- update 结果携带 `signature_status`（一个短字符串说明发布完整性在哪里被验证：如 `verified`、`not_checked`、`handled_by_npm_installer`、`manual_release_verification_required`）与 `signature_verified`（仅当本地 Sigstore 验证真实执行且成功时为 true）。不能把 checksum 校验伪装成签名校验。
+- **强制签名验证，无跳过路径**：二进制自更新路径必须在进程内验证 `checksums.txt` 的 Sigstore 签名，再用它校验归档 SHA256。签名 bundle 缺失、签名验不过、checksum 不符，一律**失败关闭**，不存在"验不了就放行"的降级。整条链对外返回 `E_INTEGRITY`（exit 1，非重试）——伪造或损坏的发布不该被当成可重试的瞬时错误。
+- **验证器内置、不依赖用户环境**：验证在工具二进制内完成（Go 用 `sigstore-go`，Python 冻结二进制内用 `sigstore`），**不外挂 cosign**，不依赖机器上预装任何东西。TUF 信任根从库内嵌的 `root.json` 引导（不是 TOFU 现拉现信）。
+- **新版 bundle 格式**：签名侧用 `cosign sign-blob --new-bundle-format` 产出 Sigstore protobuf bundle（`checksums.txt.sigstore.json`），与进程内验证器对齐；旧版 cosign bundle 格式不被接受。
+- **身份绑定**：验证端把证书 SAN 绑定到本仓库的 tagged release workflow（`…/release.yml@refs/tags/v*`，锚定 `^…$`）并校验 GitHub OIDC issuer。已知目标 tag 时可绑精确身份，强于正则。
+- **跨语言统一**：Go 二进制与 Python 冻结二进制走同一套自更新契约——都是"下载归档 → 进程内验签 → checksum → 替换二进制"，包管理器不参与完整性。
+- update 结果携带 `signature_status`（成功即 `verified`；异常一律走 error envelope 中止）与 `signature_verified`（仅当进程内 Sigstore 验证真实执行且成功时为 true）。不能把 checksum 校验伪装成签名校验。
 
 - `update --confirm <token>` 成功后，结果 `data` 中返回 `previous_version` 与 `current_version`。
 - 同时在结果中提示：`run "changelog --since <previous_version>" to see what changed`。

package/.agent/SEC-SPEC.md

@@ -97,15 +97,20 @@ Fallback and channel rules:
 
 ## 5. Supply chain (applies to anything distributed)
 
-- **Integrity verification**: install scripts and self-update commands pulling a
-  binary must verify checksums, **hard-fail on mismatch**, and report signature
-  verification status explicitly. A checksum proves bytes match a checksum file;
-  it does not prove the checksum file came from the publisher.
-- **Signed release material**: release pipelines should sign `checksums.txt`
-  with Sigstore/Cosign keyless signing from the tagged GitHub Actions release
-  workflow, publishing the bundle alongside the checksum file. Verification must
-  bind the signature to the expected repository workflow identity and GitHub OIDC
-  issuer.
+- **Integrity verification, mandatory and no-skip**: binary self-update MUST verify
+  the Sigstore signature on `checksums.txt` **in-process** (the verifier is embedded
+  in the tool binary — Go via `sigstore-go`, Python inside the frozen binary via
+  `sigstore` — with **no external cosign** and no user-environment dependency), then
+  verify the archive SHA256. A missing/invalid signature or a checksum mismatch
+  **fails closed** with no "can't verify, proceed anyway" degradation, surfacing
+  `E_INTEGRITY` (non-retryable). A checksum proves bytes match a checksum file; only
+  the signature proves the checksum file came from the publisher.
+- **Signed release material**: release pipelines sign `checksums.txt` with
+  Sigstore/Cosign keyless signing from the tagged GitHub Actions release workflow
+  using `--new-bundle-format` (a Sigstore protobuf bundle the in-process verifier
+  consumes). Verification binds the signature to the expected repository workflow
+  identity (anchored `^…$`) and GitHub OIDC issuer; the TUF trust root is
+  bootstrapped from the library's embedded root, not TOFU.
 - **Dependency locking + audit**: commit a lockfile; CI runs `npm audit` / `pip-audit` and blocks high-severity dependencies.
 - **Traceable builds**: release artifacts are built by CI from tagged source, no hand-uploaded unknown binaries.
 - **No remote scripts in postinstall**: don't execute code freshly pulled from the network at install time.

package/.agent/SEC-SPEC_zh.md

@@ -88,8 +88,8 @@ Agent 侧约定（同时写进 SKILL-SPEC 的用法）：
 
 ## 5. 供应链（凡分发即适用）
 
-- **完整性校验**：安装脚本和自更新命令拉取二进制时必须校验 checksum，**不匹配硬失败**，并显式返回签名校验状态。checksum 只能证明字节与 checksum 文件一致，不能证明 checksum 文件来自发布者。
-- **签名发布材料**：release pipeline 应由 tagged GitHub Actions release workflow 使用 Sigstore/Cosign keyless 模式签署 `checksums.txt`，并把 bundle 与 checksum 一起发布。验证时必须绑定到预期仓库 workflow 身份和 GitHub OIDC issuer。
+- **完整性校验，强制且无跳过**：二进制自更新必须**在进程内**验证 `checksums.txt` 的 Sigstore 签名（验证器内置工具二进制，Go 用 `sigstore-go`、Python 冻结二进制内用 `sigstore`，**不外挂 cosign**、不依赖用户环境），再用它校验归档 SHA256。签名缺失/验不过/checksum 不符一律**失败关闭**，没有"验不了就放行"的降级；对外返回 `E_INTEGRITY`（非重试）。checksum 只能证明字节与 checksum 文件一致，签名才能证明 checksum 文件来自发布者。
+- **签名发布材料**：release pipeline 由 tagged GitHub Actions release workflow 用 Sigstore/Cosign keyless 模式以 `--new-bundle-format` 签署 `checksums.txt`（产出 Sigstore protobuf bundle），与进程内验证器对齐。验证时绑定到预期仓库 workflow 身份（锚定 `^…$`）和 GitHub OIDC issuer；TUF 信任根从库内嵌 root 引导，不 TOFU。
 - **依赖锁定 + 审计**：提交 lockfile；CI 跑 `npm audit` / `pip-audit` 一类，高危依赖阻断。
 - **构建可追溯**：发布产物由 CI 从打了 tag 的源码构建，不手工上传不明二进制。
 - **不在 postinstall 跑远程脚本**：安装期不执行从网络现拉的代码。

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.6] - 2026-06-16
+
+### Changed
+
+- `update` now verifies the release Sigstore signature on `checksums.txt` **in-process** (embedded `sigstore-go`, bootstrapped from the embedded TUF trust root) instead of shelling out to an external `cosign`. Verification is mandatory and fail-closed: a missing signature bundle, a signature that does not verify against this repo's tagged release-workflow identity, or a checksum mismatch all refuse the update — there is no skip path. Releases are now signed with `cosign sign-blob --new-bundle-format`.
+
+### Security
+
+- Release-integrity failures (missing/invalid signature or checksum mismatch) now return the non-retryable `E_INTEGRITY` error code (exit 1) instead of a retryable network code, so an agent treats a possible supply-chain issue as a hard stop rather than retrying.
+
 ## [1.0.5] - 2026-06-16
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fateforge/archery-cli",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Archery SQL audit CLI for AI Agents - manage SQL workflows, queries, instances, diagnostics, and data dictionaries with a machine-readable contract",
   "keywords": [
     "archery",

package/skills/archery-cli/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: archery-cli
-version: "1.0.5"
+version: "1.0.6"
 description: "Archery SQL audit platform CLI for managing SQL workflows, queries, instances, diagnostics. Use when the user asks about SQL审核, database operations, Archery platform management, or needs to submit/review/execute SQL against database instances."
 license: MIT
 user-invocable: true
-metadata: {"requires":{"bins":["archery-cli"],"min_version":"1.0.5"}}
+metadata: {"requires":{"bins":["archery-cli"],"min_version":"1.0.6"}}
 ---
 
 # archery-cli