skill-sign

• 版本: 1.0.0
• 许可证: MIT
• 作者: <通过 OSG_AUTHOR_NAME / git config 设置>
• 代码仓库: https://github.com//build-better-skills (stage: sign)

使用 Ed25519 对技能目录进行密码学签名，使接收方可验证其真实性并检测篡改行为——即使在从未与作者建立过任何联系的机器上亦可完成。

为何需要真实签名（而不仅是哈希值）

对技能目录直接计算 SHA-256 哈希仅能检测意外修改，但任何人都可重新计算该哈希，并以你的名义再次发布。而 Ed25519 签名同时保证完整性与作者身份 —— 验证方只需持有你的 公钥（可安全公开分发），无需接触私钥。

依赖项

• Python ≥ 3.9（仅使用标准库： hashlib、json、base64、pathlib、argparse）
• 内嵌的 Ed25519 实现：scripts/_vendor/ed25519_rfc8032.py
  • 来源：RFC 8032 附录 A（公共领域）
  • 这不是一个 pip 包 —— 它随本技能目录一同分发，无需执行 pip install。
• 读取的环境变量（全部为可选）：XDG_CONFIG_HOME、USER、USERNAME

安全模型 —— 请务必首先阅读

信任公钥的通道由你自行负责。 请从可信渠道获取作者的公钥（例如其官方 GitHub README、经验证博客中发布的密钥指纹、当面交付的密钥文件等）。一旦获得该公钥，此后所有使用该密钥进行的验证均具备强保障。

该信任模型与 git commit -S、PGP 签名发布的软件包以及 Sigstore 完全一致；其共通前提为：你必须通过你所信任的带外（out-of-band）信道，一次性完成对公钥的信任建立。

首次设置（每台机器仅需一次）

python3 scripts/init.py

将在以下路径生成一对 Ed25519 密钥：

• ~/.config/skill-sign/private.key —— 务必保密（建议权限设为 600）
• ~/.config/skill-sign/public.key —— 可自由分发
• ~/.config/skill-sign/public.key.txt —— 同一公钥的 base64 编码文本格式，便于复制粘贴

🛡️ 请务必备份 private.key 至安全位置（如加密 U 盘、密码管理器等）。若丢失，则无法以相同身份重新签名。

为技能签名（发布者）

python3 scripts/sign.py /path/to/your-skill --version 1.0.0

将在技能目录内写入 sign.key 文件。请将技能目录与 sign.key 一并分发。同时，请将你的公钥（通过运行 scripts/export_public.py 获取）发布至接收方可信赖的位置（如 GitHub README 等）。

验证技能（接收者）

自验证（仅证明自签名后内容未被更改，但无法确认签名者身份）：

python3 scripts/verify.py /path/to/skill

信任验证（同时证明完整性与作者身份）：

# 方式 A：以内联字符串形式指定受信任公钥
python3 scripts/verify.py /path/to/skill 
  --trust-key-string ed25519:abc123...

# 方式 B：从文件加载受信任公钥
python3 scripts/verify.py /path/to/skill 
  --trust-key ~/.config/skill-sign/trusted/alice.pub

退出码含义：0 = 通过，1 = 失败（内容被篡改 / 公钥不受信任），2 = 错误。

sign.key 格式

{
  "skill_name": "glic-check",
  "version": "1.0.1",
  "signed_by": "alice",
  "signed_at": "2026-06-21T22:00:00+08:00",
  "algorithm": "ed25519",
  "public_key": "ed25519:",
  "content_hash": "sha256:<十六进制>",
  "signature": ""
}

该签名覆盖了上述所有元数据字段（不含 signature 自身）按字典序排序后的规范 JSON 表示。对文件内容或任意元数据的任何修改，都将使签名失效。

参与哈希计算的内容

包含：技能目录下所有文件（递归遍历，按路径字典序排序）。

排除：sign.key 文件自身、.git/、__pycache__/、node_modules/、*.pyc、*.pyo、*.bak、*.swp、.DS_Store、macOS 的 ._* 资源分支文件。

限制（v1.0）

• 不支持密钥轮换：--rotate-key 参数已预留；当前需手动完成（运行 init --force → 逐个重新签名所有技能）。
• 不支持密钥吊销：若私钥泄露，你必须发布新的公钥，并通知所有接收者重新建立对该新公钥的信任。本方案无中心化注册机制。
• 纯 Python 实现的 Ed25519 性能较低且未做旁路攻击防护：每次签名/验证耗时约 5ms。适用于技能发布场景（每个版本仅需数次操作）；不适用于高频调用或敌对环境。如需更高性能与安全性，可替换为 cryptography.hazmat —— sign.key 格式完全兼容。

在技能中心（skill hub）发布的工作流程

1. 运行 scripts/init.py（仅需一次）
2. 运行 scripts/sign.py my-skill --version 1.0.0
3. 将 sign.key 与技能一同提交并发布。
4. 在技能的 README 中注明：Signed with: ed25519:abc123...（由 export_public.py --skill-md 输出）
5. 接收者通过你经过验证的 GitHub 主页首次信任你的公钥，之后每个版本均可使用 verify.py --trust-key 进行验证。

脚本列表

• scripts/init.py —— 生成 Ed25519 密钥对
• scripts/sign.py —— 对技能目录签名
• scripts/verify.py —— 验证已签名的技能
• scripts/export_public.py —— 输出用于分发的公钥
• scripts/_lib.py —— 共享工具函数（文件遍历、哈希计算、编码等）
• scripts/_vendor/ed25519_rfc8032.py —— RFC 8032 规范定义的 Ed25519 参考实现（公共领域）