Verahelm/verahelm-decision-envelope

# Verahelm Decision Envelope  测试结果、安全发现、策略决策和审查记录显示了检查的内容。它们本身并未记录谁授权了特定的变更、该授权的范围，或其何时过期。 Verahelm 的托管 API 可以针对特定的主体版本签发已签名的 Decision Envelope。该 envelope 以可移植对象的形式记录授权方、范围、条件、签发、过期、撤销和替代。首个支持的工作流是针对拉取请求（pull request）和代理（agent）的变更门控（change gating）；该 API 在同一契约下记录了十三种门控配置。 公开契约接受结构化摘要和摘要值（digest）。它不定义任何用于仓库、源代码、提示词（prompt）、追踪（trace）、文件、数据集或原始记录的字段。 ## 运行示例 ``` node cli/verahelm.mjs demo ``` 该命令会加载四个虚构的 envelope，并检查有效、阻塞、过期和被篡改的结果。它在本地运行，无需网络访问。 ## 将验证器添加到拉取请求 ``` permissions: contents: read steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 - name: Bind expected pull-request subject id: subject env: SUBJECT_ID: ${{ github.repository }} SUBJECT_REVISION: ${{ github.event.pull_request.head.sha }} run: printf 'version=sha256:%s\n' "$(printf '%s' \"$SUBJECT_ID@$SUBJECT_REVISION\" | sha256sum | cut -d' ' -f1)" >> "$GITHUB_OUTPUT" - uses: Verahelm/verahelm-decision-envelope@33ca2a95808491a1f0d13a5aa2433e911d4582c3 with: envelope: path/to/decision-envelope.json public-key: path/to/public-key.pem public-key-sha256: ${{ vars.VERAHELM_PUBLIC_KEY_SHA256 }} subject-id: ${{ github.repository }} subject-version: ${{ steps.subject.outputs.version }} authority-id: ${{ vars.VERAHELM_AUTHORITY_ID }} scope-environment: ${{ vars.VERAHELM_SCOPE_ENVIRONMENT }} scope-change: pull-request-${{ github.event.pull_request.number }} ``` 该 Action 会验证提供的 envelope；它不会调用托管 API 或签发决策。请将 `VERAHELM_PUBLIC_KEY_SHA256` 配置为包含 `sha256:` 及受信任密钥文件的 SHA-256 指纹的仓库 Actions 变量。拉取请求的内容不得控制此值。 使用 `node cli/verahelm.mjs fingerprint PUBLIC_KEY` 生成该值。同时将预期的授权方和环境配置为受保护的仓库变量。签名的 `scope.change` 必须与 `pull-request-` 匹配。 请使用 [`template/verahelm-change-gate.yml`](template/verahelm-change-gate.yml) 中受基础控制（base-controlled）的完整工作流；它不会执行拉取请求中的代码。 对于依赖当前生命周期状态的门控，请提供签名的状态文件和 `status-max-age-seconds`。如果没有足够最新的状态，离线验证将无法发现后续的服务器端撤销或替代。 该 Action 会匹配预期的主体、版本、授权方、环境和变更。调用方工作流仍须强制执行每一个已签名的条件。 ## 本地命令 ``` node cli/verahelm.mjs demo node cli/verahelm.mjs validate fixtures/pass.json node cli/verahelm.mjs verify fixtures/pass.json --key fixtures/fixture-public-key.pem node cli/verahelm.mjs explain fixtures/pass.json node cli/verahelm.mjs fingerprint fixtures/fixture-public-key.pem ``` 所有五个命令均在无网络或子进程访问权限的情况下运行。命令行为和退出代码记录在 [docs/CLI.md](docs/CLI.md) 中。 ## 结果处理 有效的通过 envelope 退出代码为零。阻塞、过期、撤销、替代和被篡改的 envelope 退出代码为非零。可选的预期主体和版本会将验证绑定到正在审查的拉取请求。[虚构的拉取请求示例](demo-pr/README.md) 展示了从阻塞的 envelope 到新的通过 envelope 的转换。 ## 托管 API 配置 托管 API 将拉取请求门控、代理变更门控、工具准入、迁移就绪、重新测试、故障覆盖及相关检查归类于同一契约下。输入由调用方提供的摘要组成。Verahelm 声明这些由调用方提供的凭证并未经过独立验证，且不签发认证、合规批准、安全发现或生产授权。 ## 在工具链中的角色 评估、可观测性、安全、治理、策略、溯源和仓库工具会产生凭证。Verahelm 记录了选定的凭证如何绑定到主体版本、客户授权、范围、条件和生命周期。[来源对比](docs/COMPARISON.md) 描述了这些工作之间的边界。 ## 已发布的组件 本仓库包含公开 schema、离线验证器、仅用于验证的 GitHub Action、虚构的测试夹具（fixtures）和一致性测试。它不包含 Verahelm 的托管决策引擎或其私有实现。 请勿提交源代码、提示词、输出、日志、数据集、凭证、个人数据、客户资料或第三方机密信息。请参阅 [PRIVACY_BOUNDARY.md](PRIVACY_BOUNDARY.md)。 ## 验证器属性 - Ed25519 验证离线运行。 - 该 Action 仅需 `contents: read` 权限。 - 位于拉取请求内容之外的受信任密钥指纹可防止信任密钥被替换。签名验证以及预期的主体、授权方和范围匹配会拒绝 payload 修改和跨上下文替换。 - 未知字段、不支持的版本、无效签名和无效的生命周期状态将执行失败关闭（fail closed）。 - 夹具是虚构的，仅用于测试已发布的验证契约。 - 发布清单会拒绝未列出的文件和仓库历史记录。 ## 定价 | 计划 | 价格 | 包含单元数 | 限制 | |---|---|---|---| | Developer | $49/月 | 60次/月；10次/天 | 5 次请求/10 秒；30次/分钟；并发数 2；1 个密钥；12,288 字节；6 秒 | | Professional | $149/月 | 300次/月；34次/天 | 13 次请求/10 秒；90次/分钟；并发数 5；5 个密钥；16,384 字节；8 秒；元数据导出 | 基础配置消耗为 1、2 或 3 个单元。每增加一个已开始的 4,096 字节请求块增加一个单元；边界压力测试在首次之后每增加一个样本增加一个单元。 单元数不予累积，且没有自动超额费用。邮件支持为尽力而为，不提供响应时间 SLA。 ## 文档 - [API 契约](https://www.verahelm.com/api-docs) - [申请非生产测试密钥](https://www.verahelm.com/access#testing-key) - [Decision Envelope 规范](SPECIFICATION.md) - [威胁模型](THREAT_MODEL.md) - [版本控制策略](VERSIONING.md) - [GitHub 与证明集成](docs/INTEGRATIONS.md#github-change-enforcement) 可重用的公开代码仅按照 [LICENSE](LICENSE) 中所述进行许可。

标签：GitHub Actions, MITM代理, 决策引擎, 变更授权, 数字签名验证, 数据可视化, 文档结构分析, 策略即代码, 聊天机器人安全, 自动笔记, 自定义脚本