mordiaky/vouchspec

# VouchSpec VouchSpec 是一个独立的证据索引的临时公开测试版名称，用于精确的 Agent Skill 版本。该名称已通过 $0 的明显冲突筛查；尚未获得正式的法律或商标许可。 当前的 Stage A 目录包含了 **12 个 GitHub repository owner 下的 25 个精心挑选的公开 Agent Skill**。每个条目都固定到完整的 Git commit 和确切的目录 digest，在不执行 artifact 代码的情况下进行静态检查，封装在 DSSE v1.0.2 envelope 中，并使用 Ed25519 进行签名。一个单独的 root key 对机器可读的 lifecycle feed 进行签名。 这是证据，而非安全认证。这 25 个真实世界 skill 中有六个未能通过至少一项当前的结构规则；它们仍然被索引并附带失败证据，且未被标记为 `STRUCTURE_VALIDATED`。 ## 公开的 Stage A 分发 - Repository 和安装源： - 机器可读发现： - 托管的 agent API： - 托管 API 发现： - Agent 快速入门： - 托管在 TLS 上的已签名索引： - Root 签名的 lifecycle feed： - 带外 root/issuer key 发布： 静态分发返回确切的已签入签名字节，启用 CORS 并拒绝写入。下载已签名的索引，在本地进行过滤，然后通过 ID 从 `catalog/public/receipts/` 检索 receipt。对于不可变检索，请将 `main` 替换为目录快照 `4404b7a9a2d3dc45b621ea694d2ca7ad666b9898`。带外 Gist 独立于 repository，但共享其 GitHub 账号，因此账号级别的入侵仍然需要一个新的受信任通道。 ## 产品阶段 - **Stage A — 公开 artifact 索引（在线）：** 仅限精选的公开 artifact；已签名的 receipt 和只读 REST/MCP 检索；不提供上传、私有 repository 或客户机密内容。 - **Stage B — 公开 repository 验证（公开 testnet 沙箱）：** 允许列表公开 host，完整 commit，显式子目录，有界不可变检索，隔离的无 egress worker，单独的无 egress 签名，持久化的 tenant/order/payment 状态，经过身份验证的托管 API，以及使用 Base Sepolia 上的 test USDC 进行精确的 x402 结算。Testnet 订单是自助式的并完全完成；mainnet 结算仍处于禁用状态。 - **Stage C — 私有/任意输入（推迟）：** 仅在需求和收入证明其合理性后，才提供私有存储、身份验证、tenant 隔离、删除策略以及扩展的法律/事件控制。 Stage C 不是 Stage A 或 B 的先决条件。Stage A 服务器或 MCP 工具中不存在任意上传路由。 ## Publisher CI — 完整的自助示例 公开的 [publisher-CI demo](https://github.com/mordiaky/vouchspec-demo) 展示了完整的可信工作流路径：不可变的 action pin，精确 commit 检查，两个 GitHub artifact 证明，可下载的证据，以及独立的 `gh attestation verify` 命令。最新的 [verified matrix run](https://github.com/mordiaky/vouchspec-demo/actions/runs/29331787790) 通过了一个结构性通过案例和一个故意的结构性失败案例。其四个下载的证据文件均通过 `gh attestation verify` 独立验证。该 demo 由运营商控制，不计入外部采用。 请在其不可变的、保留证据的快照中使用该 action： ``` - id: vouchspec uses: mordiaky/vouchspec/distribution/github-action@ed812a14cbc62333d59bac319f79d897f14d1b64 with: skill-path: path/to/skill ``` 对于结构性通过和显式的结构性失败，该 action 都会输出一个 receipt 草案和 publisher/workflow 绑定。请参阅[完整的固定工作流、权限、验证和故障排除指南](distribution/github-action/README.md)。 ## 证据标签 Receipt 使用显式标签，从不使用通用的 `VERIFIED` 徽章： - `DIGEST_PINNED` - `STRUCTURE_VALIDATED`（仅当结构配置通过时） - `STATIC_INSPECTION_COMPLETED` - `INDEPENDENT_STATIC_SCAN`（仅适用于精选的运营商运行配置） `PUBLISHER_CI_ATTESTED`、`SANDBOX_BEHAVIOR_OBSERVED` 和 `TASK_EVALUATED` 保留给实际已生成的单独证据。静态检查绝不暗示它们。 ## 独立验证公开 receipt 验证器在解析 JSON 之前对确切的解码后的 receipt 字节进行身份验证，验证 receipt schema 和内部一致性 digest，然后可选地应用 root 签名的 lifecycle feed。 ``` vouchspec verify catalog\public\receipts\RECEIPT_ID.dsse.json ` --key catalog\public\keys\issuer.jwk.json ` --lifecycle catalog\public\lifecycle.dsse.json ` --root-key catalog\public\keys\root.jwk.json ``` Lifecycle 结果包括 `CURRENT`、`SUPERSEDED`、`EXPIRED`、`REVOKED_EVALUATOR_DEFECT`、`REVOKED_KEY_COMPROMISE`，或者保守的 `SIGNATURE_VALID_LIFECYCLE_UNKNOWN`。签名 key ID 仅作为查找提示；公共 JWK 必须通过独立可信的路径获取或固定。 ## 只读目录 API ``` vouchspec serve-catalog --catalog-root catalog\public --port 8788 ` --trusted-root-key C:\independently-provisioned\root.jwk.json ``` 可用的 `GET` 路由： - `/health` - `/v1/index`（issuer 签名的 DSSE 索引 envelope） - `/v1/quote?operation=...`（价格/可用性响应；付费订单仍处于禁用状态） - `/v1/receipts?q=...&repository_owner=...&limit=...` - `/v1/receipts/{receipt_id}` - `/v1/receipts/{receipt_id}/status` - `/v1/lifecycle` - `/v1/keys/root` - `/v1/keys/issuer` 所有 `POST` 请求都将收到 `405 read_only`。内置服务器具有连接限制、截止时间强制执行，并且仅限 loopback；公开部署必须将其置于具有平台 ingress 限制的托管 TLS 代理之后。每个进程服务于一个完全验证的不可变目录快照；通过重启进程来部署新的 lifecycle/index 生成。观察到的最高 root-feed 序列号及其 payload digest 通过跨进程锁持久化。 本地目录价格卡路由报告商业价格假设，但不接受订单。对于严格的、特定于请求的本地预览： ``` vouchspec quote-fresh-validation docs\examples\fresh-validation-request.json ``` 预实验证了与托管 API 使用的相同的请求结构。公开沙箱价格被故意设为水龙头大小的 **1.00 test USDC**；商业 mainnet 价格仍然是一个未经验证的 **USD $49.00 假设**。 ## 仅限 Agent 的 x402 沙箱 位于 `https://vouchspec-sandbox.plyrium.com` 的公共服务没有卡表单、托管结账或人工批准步骤。Agent 需要： 1. 在 `POST /api/vouchspec/v1/tenants` 接受条款版本 `vouchspec-stage-b-2026-07-14`，并存储一次性 tenant bearer key； 2. 使用 `Authorization` 和唯一的 `Idempotency-Key` 将严格的新鲜验证请求发送到 `POST /api/vouchspec/v1/quotes`； 3. 在 `POST /api/vouchspec/v1/orders` 创建一个 order，并存储返回的 delivery token； 4. 调用该 order 的 `purchase_path`，读取 x402 v2 `PAYMENT-REQUIRED` 挑战，在 Base Sepolia 上签署确切的 1.00 test-USDC 付款，并使用 `PAYMENT-SIGNATURE` 重试； 5. 轮询经过身份验证的 order，检索确切的 DSSE 结果，并使用公共 issuer JWK 进行验证。 成功的 envelope 也会在内容寻址的无需身份验证的 URL 上发布。Agent 可以缓存和共享这些不可变的字节。失效被故意分开处理：每次使用 receipt 进行新决策时，请检查相应的 no-store `/status` URL。[机器可读发现文档](distribution/discovery.json)包含所有路由模板、标头、网络、价格、信任、缓存和产品边界字段。 托管的证明由所有者控制且仅限 testnet，因此它演示了机制但不计为客户、请求、买方或收入。请参阅 [Stage B 运营边界](docs/stage-b-operations.md)、[支付流程](docs/payment-flow.md)、[托管部署边界](deploy/README.md)和[退款政策](docs/refund-policy.md)。 ## 本地商业测试环境 该 repository 仍然包含一个用于回归和安全测试的 loopback 测试环境。它存储带有关键字的凭据 digest，从不存储明文 token，并将每个 quote 和 order 绑定到一个不透明的 tenant。使用批准的 secret manager 生成两个不同的 32 字节 secret，仅将它们的十六进制值公开给该进程，然后配置一个本地沙箱凭据： ``` $env:VOUCHSPEC_AUTH_PEPPER_HEX = '<64 hex characters>' $env:VOUCHSPEC_DELIVERY_SECRET_HEX = '' vouchspec provision-commerce-tenant --database C:\vouchspec\sandbox-commerce.db vouchspec serve-commerce-sandbox --database C:\vouchspec\sandbox-commerce.db --port 8789 ``` 本地 API 绑定到 `127.0.0.1`，没有 CORS 限制，并公开经过身份验证的 quote、order、status、signed-result、capability-rotation 和 capability-revocation 路由。其模拟支付通道永远不会结算，并且每个生成的 order 保持为 `counts_for_goal: false`。 一个明确不结算的 Stripe-test adapter 仍然仅用于回归覆盖。它不是 VouchSpec 的发布通道，也不会被托管 agent 服务公开： ``` vouchspec serve-commerce-stripe-test ` --database C:\vouchspec\stripe-test-commerce.db --port 8789 ``` 不要直接公开该内置监听器。Mainnet 激活使用 x402、单独的实时状态和 secret，以及[部署边界](deploy/README.md)中的实时网关。 ## 只读目录 MCP 公开安装： ``` git clone https://github.com/mordiaky/vouchspec.git cd vouchspec python -m venv .venv .venv\Scripts\python -m pip install . .venv\Scripts\vouchspec mcp-catalog --catalog-root catalog\public ` --trusted-root-key C:\independently-provisioned\root.jwk.json ``` ``` vouchspec mcp-catalog --catalog-root catalog\public ` --trusted-root-key C:\independently-provisioned\root.jwk.json ``` 工具包括 `search_receipts`、`get_receipt`、`get_receipt_status`、`get_verification_material` 和 `get_price_quote`。它们仅接受标识符、搜索文本和指定的价格卡操作，不接受 artifact 内容。此本地只读 MCP 不下付费订单；agent 使用托管的 x402 API 进行新鲜验证。 ## 本地检查器和构建器 开发安装： ``` python -m venv .venv .venv\Scripts\python -m pip install -e ".[dev]" ``` 兼容性命令和 Python 包名称 `capabilityproof` 与公开的 `vouchspec` 命令一起保持可用。 ``` vouchspec inspect C:\path\to\skill --output receipt.json vouchspec inspect-git C:\checkout\skills\example ` --repository-root C:\checkout --output receipt.json ``` 本地检查从不安装、导入、渲染或执行 artifact 内容。签入的目录构建器仅接受精选清单和处于完整 40 字符 commit 下的公共 HTTPS GitHub repository。收集无需 key，issuer 签名是一个单独的无网络阶段，而 recovery-root lifecycle 签名是一个单独的离线阶段。 加密的私钥保留在此 repository 之外；仅发布 RFC 8037 公共 JWK。请参阅[方法论](docs/methodology.md)、[receipt schema](src/capabilityproof/schemas/capability-receipt.schema.json) 和[威胁模型](research/mvp-threat-model.md)。

标签：CVE, 依赖管理, 后端开发, 完整性校验, 数字签名, 软件溯源, 逆向工具