技能包签名¶

impeccable install、update 和 check 会在解压远程技能 ZIP 之前对其进行身份验证。universal.zip.sig.json 是对该 ZIP 的 SHA-256 摘要、字节长度、发布版本、产物名称和密钥 ID 所做的 Ed25519 签名。引擎只信任编译进二进制文件的 scripts/bundle-signing-keys.json。签名无法引入新的受信任密钥。

impeccable.style 上的下载端点会重定向到带版本号的 GitHub release。安装程序仅解析该重定向一次，并从同一个 release 下载 ZIP 及其签名。之后的所有重定向必须使用 HTTPS。缺少签名、未知密钥、元数据变更以及 ZIP 字节变更都会在解压或写入已安装技能之前终止操作。临时下载目录在失败时会被删除。

签署发布版本¶

安装 1Password CLI，并启用其桌面应用集成。签名条目将 PKCS#8 Ed25519 私钥保存在隐蔽的 private-key 字段中。在 shell 中设置引用，而不是密钥材料：

export OP_ACCOUNT='<account ID or sign-in address>'
export IMPECCABLE_SIGNING_KEY_REF='op://<vault ID>/<item ID>/private-key'
bun run release:skill

若要在你的机器上进行持久化设置，请改用本地 Git 配置：

git config --local impeccable.signingAccount '<account ID or sign-in address>'
git config --local impeccable.signingKeyRef 'op://<vault ID>/<item ID>/private-key'

这些值保存在 .git/config 中，不在版本控制之内。环境变量优先。这两个设置都不包含私钥。

release 命令会重新构建 ZIP，通过 op read 读取密钥，检查其公钥是否受信任，并在创建任何 tag 或 release 之前写入 sidecar。ZIP 和 sidecar 会一起上传。密钥永远不会作为命令参数传递、写入临时文件或打印输出。它只会在本地签名进程的内存中短暂存在。1Password 的失败信息会被报告，但不会转发子进程输出。

--dry-run 不会访问 1Password，也不会创建签名。它会检查常规的 release 前置条件，并在上传计划中展示这两个资源；但它不能证明签名凭据可用。

要为首次发布签署一个已发布的 release，请下载并检查所发布的确切 universal.zip，然后运行：

node scripts/sign-bundle.mjs 4.2.0 /path/to/universal.zip

使用 Rust 验证器和编译内置公钥检查生成的 sidecar：

IMPECCABLE_VERIFY_BUNDLE=/path/to/universal.zip \
IMPECCABLE_VERIFY_BUNDLE_VERSION=4.2.0 \
cargo test -p impeccable-skills verifies_reviewed_release_with_production_keyring -- --ignored

这只会在本地创建 sidecar。它既不会上传 sidecar，也不会替换 ZIP。切勿重新生成旧的 ZIP，并把那些不同的字节签名为旧 release。上传 sidecar 是一个独立的维护者审批步骤。

发布与轮换¶

在发布强制验证引擎之前，请先在 impeccable.style 当前提供的确切 ZIP 旁边发布有效签名。使用本地构建的引擎验证这对文件，然后发布引擎、其 npm 平台包以及 CLI/技能固定版本。在整个过程中保持现有 release 可用。不要发布空密钥环的强制验证引擎，也不要在所提供 ZIP 未签名时发布该引擎。

对于计划中的密钥轮换，请先发布一个同时信任旧公钥和新公钥的引擎，然后再使用新密钥签名。不知道新密钥的旧引擎会拒绝下载并提示升级 CLI。密钥泄露时，需要更新引擎以移除该公钥；仅从网站移除它并不会撤销已安装二进制文件中的信任。请将专用签名条目与 GitHub 及部署凭据分开保管。

适用范围¶

此机制用于防止攻击者在能够更改下载端点、release 资源或两者兼有，但无法使用签名密钥或替换受信任引擎的情况下，进行包替换。它不是新鲜性协议：之前已签名的 release 仍可能被重放。带签名的时间戳元数据和回滚状态属于独立的工作。签名并不能证明所编写的技能内容是安全的，也不能验证单独下载的引擎二进制文件（这些文件目前使用其现有的 SHA-256 sidecar）。

IMPECCABLE_BUNDLE_PATH 和 impeccable link 是显式的本地开发信任路径。它们仍然接受未签名的本地文件/目录。不要使用这些覆盖项来绕过失败的远程验证。没有未签名网络回退或跳过签名标志。

传输格式¶

JSON sidecar 字段：schema（1）、keyId、version、artifact（universal.zip）、size、sha256、signature。十六进制字符串为小写；公钥为 32 字节，签名为 64 字节。未知或重复字段会被拒绝。签名负载为 UTF-8，使用 LF 行尾，并以一个 LF 结尾：

impeccable-skill-bundle-v1
<keyId>
skill-v<version>
universal.zip
<size as decimal>
<sha256 as lowercase hex>

Node 签名器和 Rust 验证器共享位于 tests/fixtures/bundle-signature.json 的固定测试向量。其确定性测试密钥绝不能添加到生产密钥环中。