{ "markdown": "# VouchSpec\n\nVouchSpec is the provisional public-beta name for an independent evidence index for exact\nAgent Skill versions. The name passed a $0 obvious-conflict screen; it has not received\nformal legal or trademark clearance.\n\nThe current Stage A catalog contains **25 deliberately selected public Agent Skills across\n12 GitHub repository owners**. Every entry is pinned to a full Git commit and exact directory digest,\nstatically inspected without executing artifact code, wrapped in a DSSE v1.0.2 envelope,\nand signed with Ed25519. A separate root key signs the machine-readable lifecycle feed.\n\nThis is evidence, not a safety certification. Six of the 25 real-world skills fail at least\none current structural rule; they remain indexed with the failure evidence and are not\nlabeled `STRUCTURE_VALIDATED`.\n\n## Public Stage A distribution\n\n- Repository and install source: \n- Machine-readable discovery: \n- Managed agent API: \n- Managed API discovery: \n- OpenAPI 3.1 contract: \n- LLM-readable contract index: \n- Installable Agent Skill index: \n- Verify-before-install Agent Skill:\n \n- Agentic Resource Discovery catalog (draft/proposal):\n \n- A2A Agent Card: \n- A2A JSON-RPC discovery: \n- Remote agent discovery (MCP): \n- Official MCP Registry API: \n- Agent Tools x402 listing:\n \n- Agent Tools MCP listing:\n \n- Agent Tools A2A listing:\n \n- Agent quickstart: \n- Signed index over managed TLS: \n- Root-signed lifecycle feed: \n- Out-of-band root/issuer key publication: \n\nThe static distribution returns the exact checked-in signed bytes with CORS enabled and\nrejects writes. Download the signed index, filter it locally, then retrieve a receipt by ID\nfrom `catalog/public/receipts/`. For immutable retrieval, replace `main` with catalog snapshot\n`4404b7a9a2d3dc45b621ea694d2ca7ad666b9898`. The out-of-band Gist is separate from the\nrepository but shares its GitHub account, so an account-level compromise still requires a\nnew trusted channel.\n\n## Product stages\n\n- **Stage A — public artifact index (live):** selected public artifacts only; signed\n receipts and read-only REST/MCP retrieval; no uploads, private repositories, or\n customer-confidential content.\n- **Stage B — public repository validation (live mainnet plus public testnet sandbox):** allowlisted public\n host, full commit, explicit subdirectory, bounded immutable retrieval, isolated no-egress\n worker, separate no-egress signing, durable tenant/order/payment state, an authenticated\n managed API, and exact x402 settlement. Commercial orders are live at 0.25 USDC on Base;\n the separate 1.00 test-USDC Base Sepolia sandbox remains available for integration testing.\n- **Stage C — private/arbitrary inputs (deferred):** private storage, authentication,\n tenant isolation, deletion policy, and expanded legal/incident controls only after\n demand and revenue justify them.\n\nStage C is not a prerequisite for Stage A or B. No arbitrary upload route exists in the\nStage A server or MCP tools.\n\n## Publisher CI — complete self-service example\n\nThe public [publisher-CI demo](https://github.com/mordiaky/vouchspec-demo) shows the complete\ntrusted-workflow path: immutable action pins, exact-commit inspection, two GitHub artifact\nattestations, downloadable evidence, and independent `gh attestation verify` commands. The\nlatest [verified matrix run](https://github.com/mordiaky/vouchspec-demo/actions/runs/29331787790)\npasses both a structural-pass case and an intentional structural-failure case. Its four\ndownloaded evidence files independently verified with `gh attestation verify`. The demo is\noperator-controlled and is not counted as external adoption.\n\nUse the action at its immutable evidence-preserving snapshot:\n\n```yaml\n- id: vouchspec\n uses: mordiaky/vouchspec/distribution/github-action@ed812a14cbc62333d59bac319f79d897f14d1b64\n with:\n skill-path: path/to/skill\n```\n\nThe action emits a receipt draft and publisher/workflow binding for both structural passes\nand explicit structural failures. See the [full pinned workflow, permissions, verification,\nand troubleshooting guide](distribution/github-action/README.md).\n\n## Evidence labels\n\nReceipts use explicit labels, never a generic `VERIFIED` badge:\n\n- `DIGEST_PINNED`\n- `STRUCTURE_VALIDATED` (only when the structural profile passes)\n- `STATIC_INSPECTION_COMPLETED`\n- `INDEPENDENT_STATIC_SCAN` (only for the curated operator-run profile)\n\n`PUBLISHER_CI_ATTESTED`, `SANDBOX_BEHAVIOR_OBSERVED`, and `TASK_EVALUATED` are reserved for\nseparate evidence that has actually been produced. Static inspection never implies them.\n\n## Verify a public receipt independently\n\nThe verifier authenticates the exact decoded receipt bytes before parsing JSON, validates\nthe receipt schema and inner consistency digest, then optionally applies the root-signed\nlifecycle feed.\n\n```powershell\nvouchspec verify catalog\\public\\receipts\\RECEIPT_ID.dsse.json `\n --key catalog\\public\\keys\\issuer.jwk.json `\n --lifecycle catalog\\public\\lifecycle.dsse.json `\n --root-key catalog\\public\\keys\\root.jwk.json\n```\n\nLifecycle results are `CURRENT`, `SUPERSEDED`, `EXPIRED`,\n`REVOKED_EVALUATOR_DEFECT`, `REVOKED_KEY_COMPROMISE`, or the conservative\n`SIGNATURE_VALID_LIFECYCLE_UNKNOWN`. The signing key ID is only a lookup hint; the public\nJWK must be obtained or pinned through an independently trusted path.\n\n## Read-only catalog API\n\n```powershell\nvouchspec serve-catalog --catalog-root catalog\\public --port 8788 `\n --trusted-root-key C:\\independently-provisioned\\root.jwk.json\n```\n\nAvailable `GET` routes:\n\n- `/health`\n- `/v1/index` (issuer-signed DSSE index envelope)\n- `/v1/quote?operation=...` (price/availability response; paid orders remain disabled)\n- `/v1/receipts?q=...&repository_owner=...&limit=...`\n- `/v1/receipts/{receipt_id}`\n- `/v1/receipts/{receipt_id}/status`\n- `/v1/lifecycle`\n- `/v1/keys/root`\n- `/v1/keys/issuer`\n\nAll `POST` requests receive `405 read_only`. The built-in server is connection-bounded,\ndeadline-enforced, and loopback-only; a public deployment must place it behind a managed TLS\nproxy with platform ingress limits. Each process serves one fully verified immutable catalog\nsnapshot; deploy a new lifecycle/index generation by restarting the process. The highest\nobserved root-feed sequence and its payload digest are persisted with a cross-process lock.\n\nThe local catalog price-card route reports the commercial price hypothesis without accepting\nan order. For a strict request-specific local preview:\n\n```powershell\nvouchspec quote-fresh-validation docs\\examples\\fresh-validation-request.json\n```\n\nThe preview validates the same request shape used by the managed API. The public sandbox price\nis deliberately faucet-sized at **1.00 test USDC**. Full agent-market research rejected the\nearlier $49 idea; the commercial mainnet launch cohort is an unvalidated **0.25 USDC** per fresh\nvalidation, with the predeclared evidence gates in `PRICING.md`.\n\n## Agent-only x402 mainnet\n\nThe commercial service at `https://vouchspec.plyrium.com` is machine-only and has no card form,\nhosted checkout, account portal, or human approval step. An agent sends the strict immutable\npublic-GitHub request to `POST /api/vouchspec/v1/validate`, receives an x402 v2 challenge for\nexactly **0.25 USDC on Base**, signs it, and retries with `PAYMENT-SIGNATURE`. Successful\nsettlement returns one-time delivery credentials; the scheduled isolated worker then produces\nthe signed, content-addressed receipt. Discovery and health are public, and the Streamable HTTP\nMCP endpoint exposes read-only contract discovery. The same purchase contract is published as\nOpenAPI, `llms.txt`, A2A, x402, and a draft/proposal ARD catalog so agents can enter through the\nprotocol they already index. Remedy execution remains disabled and is not a prerequisite for\naccepting or fulfilling ordinary paid validations.\n\n## Agent-only x402 sandbox\n\nThe public service at `https://vouchspec-sandbox.plyrium.com` has no card form, hosted checkout,\nor human approval step. An agent:\n\n1. accepts terms version `vouchspec-stage-b-2026-07-14` at\n `POST /api/vouchspec/v1/tenants` and stores the one-time tenant bearer key;\n2. sends the strict fresh-validation request to `POST /api/vouchspec/v1/quotes` with\n `Authorization` and a unique `Idempotency-Key`;\n3. creates an order at `POST /api/vouchspec/v1/orders` and stores the returned delivery token;\n4. calls the order's `purchase_path`, reads the x402 v2 `PAYMENT-REQUIRED` challenge, signs the\n exact 1.00 test-USDC payment on Base Sepolia, and retries with `PAYMENT-SIGNATURE`;\n5. polls the authenticated order, retrieves the exact DSSE result, and verifies it with the\n public issuer JWK.\n\nSuccessful envelopes are also published at a content-addressed unauthenticated URL. Agents may\ncache and share those immutable bytes. Invalidation is intentionally separate: check the\ncorresponding no-store `/status` URL each time the receipt is used for a new decision. The\n[machine-readable discovery document](distribution/discovery.json) contains all route templates,\nheaders, network, price, trust, caching, and product-boundary fields.\n\nThe hosted proof is owner-controlled and testnet-only, so it demonstrates mechanics but counts\nas no customer, request, buyer, or revenue. See the [Stage B operating boundary](docs/stage-b-operations.md),\n[payment flow](docs/payment-flow.md), [managed deployment boundary](deploy/README.md), and\n[refund policy](docs/refund-policy.md), and\n[mainnet remedy operations](docs/mainnet-remedy-operations.md).\n\n## Local commerce harness\n\nThe repository still includes a loopback harness for regression and security testing. It stores\nkeyed credential digests, never plaintext tokens, and binds each quote and order to one opaque\ntenant. Generate two distinct 32-byte secrets with an approved secret manager, expose their hex\nvalues only to the process, then provision one local sandbox credential:\n\n```powershell\n$env:VOUCHSPEC_AUTH_PEPPER_HEX = '<64 hex characters>'\n$env:VOUCHSPEC_DELIVERY_SECRET_HEX = ''\nvouchspec provision-commerce-tenant --database C:\\vouchspec\\sandbox-commerce.db\nvouchspec serve-commerce-sandbox --database C:\\vouchspec\\sandbox-commerce.db --port 8789\n```\n\nThe local API binds to `127.0.0.1`, has no CORS allowance, and exposes authenticated quote, order,\nstatus, signed-result, capability-rotation, and capability-revocation routes. Its fake payment\nrail never settles and every resulting order remains `counts_for_goal: false`.\n\nAn explicitly nonsettling Stripe-test adapter remains available for regression coverage only.\nIt is not the VouchSpec launch rail and is not exposed by the managed agent service:\n\n```powershell\nvouchspec serve-commerce-stripe-test `\n --database C:\\vouchspec\\stripe-test-commerce.db --port 8789\n```\n\nDo not expose that built-in listener directly. Mainnet activation uses x402, separate live state\nand secrets, and the live gates in [the deployment boundary](deploy/README.md).\n\n## Read-only catalog MCP\n\nRemote agents can discover the commercial managed contract through the stateless Streamable HTTP endpoint\nat `https://vouchspec.plyrium.com/api/vouchspec/v1/mcp`. It exposes only\n`get_vouchspec_discovery`: an anonymous, read-only tool that returns public route, price, x402,\nreceipt, cache, and invalidation instructions. It cannot submit artifacts, fetch repositories,\nsettle payments, or read private data. Paid validation remains on the managed x402 REST route.\n\nAgents that support the open Agent Skills format can add the repository's exact\nverify-before-install workflow directly:\n\n```powershell\nnpx skills add mordiaky/vouchspec --skill vouchspec-verify-before-install\n```\n\nThe skill is also published through the well-known machine endpoint above. It discovers the live\ncontract before acting, checks existing signed evidence first, and purchases a fresh 0.25 USDC\nvalidation only when the calling agent already has an x402 wallet and explicit spending authority.\nIf either is absent it returns `payment_required`; there is no human checkout or human handoff.\n\nThe checked-in `server.json` describes this remote endpoint for the official MCP Registry under\nthe active name `io.github.mordiaky/vouchspec`. Publication uses GitHub OIDC from a main-only\nmanual workflow, so it needs no portal login, phone code, or dedicated Registry secret.\n\nFor agents that prefer a locally pinned catalog, the stdio server remains available:\n\nPublic install:\n\n```powershell\ngit clone https://github.com/mordiaky/vouchspec.git\ncd vouchspec\npython -m venv .venv\n.venv\\Scripts\\python -m pip install .\n.venv\\Scripts\\vouchspec mcp-catalog --catalog-root catalog\\public `\n --trusted-root-key C:\\independently-provisioned\\root.jwk.json\n```\n\n```powershell\nvouchspec mcp-catalog --catalog-root catalog\\public `\n --trusted-root-key C:\\independently-provisioned\\root.jwk.json\n```\n\nTools are `search_receipts`, `get_receipt`, `get_receipt_status`,\n`get_verification_material`, and `get_price_quote`. They accept identifiers, search text,\nand named price-card operations only, not artifact content. This local read-only MCP does not\nplace paid orders; agents use the managed x402 API for fresh validation.\n\n## Local inspector and builder\n\nDevelopment install:\n\n```powershell\npython -m venv .venv\n.venv\\Scripts\\python -m pip install -e \".[dev]\"\n```\n\nThe compatibility command and Python package name `capabilityproof` remain available\nalongside the public `vouchspec` command.\n\n```powershell\nvouchspec inspect C:\\path\\to\\skill --output receipt.json\nvouchspec inspect-git C:\\checkout\\skills\\example `\n --repository-root C:\\checkout --output receipt.json\n```\n\nLocal inspection never installs, imports, renders, or executes artifact content. The\nchecked-in catalog builder accepts only the curated manifest and public HTTPS GitHub\nrepositories at full 40-character commits. Collection is keyless, issuer signing is a\nseparate no-network phase, and recovery-root lifecycle signing is a separate offline phase.\nEncrypted private keys stay outside this repository; only RFC 8037 public JWKs are published.\n\nSee [methodology](docs/methodology.md), the\n[receipt schema](src/capabilityproof/schemas/capability-receipt.schema.json), and the\n[threat model](research/mvp-threat-model.md).\n", "bytes": 15545, "sha": "6356a3887641e59de5b81403d106eba1c8cd8760472d57488470bbcf2c9bdc7e", "repo_slug": "mordiaky/vouchspec", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_mordiaky_vouchspec_fb0608ff/readme" }