Skip to content

docs: verify releases against the tag being verified, and document the PyPI attestations - #31

Merged
narko4u merged 1 commit into
mainfrom
release/0.4.4-docs
Sep 16, 2026
Merged

narko4u merged 1 commit into
mainfrom
release/0.4.4-docs

Conversation

@narko4u

@narko4u narko4u commented Sep 16, 2026

Copy link
Copy Markdown
Owner

Documentation fixes for the claims this week's releases made untrue.

The verification command was broken, and it is measured, not inferred. The
"Verifying releases" command pinned the signer identity to
@refs/tags/v0.2.1. The certificate for a release names that release's tag,
so copying the command against v0.4.3 or later fails:

Error: none of the expected identities matched what was in the certificate,
got subjects [.../release.yml@refs/tags/v0.4.3 with issuer
https://token.actions.githubusercontent.com]
rc=1

A reader doing the right thing — reading the README and verifying the artifact —
got a red failure from a page whose subject is verifiability. The command now
takes the tag being verified (TAG=v0.4.4), because the identity is the workflow
running under that tag by construction; any fixed tag in the docs is wrong from
the next release on.

The attestation path was missing. Since v0.4.3 the wheel and sdist carry
PEP 740 build attestations over GitHub Actions OIDC. The README never mentioned
them, which left the harder check (install cosign, download four assets) as the
only documented route. Both are now documented, with the attestation check first:

uvx pypi-attestations verify pypi \
  --repository https://github.com/narko4u/mcp-evidence-validator \
  pypi:mcp_evidence_validator-0.4.4-py3-none-any.whl

Run against the live v0.4.3 files, this returns OK: for both the wheel and the
sdist. The negative control is in the docs too — pointed at a different
repository it refuses: provenance was signed by repository "narko4u/mcp-evidence-validator", expected "narko4u/witnessos-verifier".

Two claims I checked before writing them down, and did not change because
they turned out to be false alarms: the relative SECURITY.md / CONTRIBUTING.md
links resolve (PyPI rewrites them to the repository; both return 200), and the
base64-wrapped SHA256SUMS.pem is accepted as-is by cosign v3.1.3 — verified
with cosign verify-blob against the real certificate, Verified OK. The PEM
encoding is noted in passing for anyone feeding a plain PEM to another tool.

Install block. pip install mcp-evidence-validator was still commented
"# from PyPI once published", contradicting the working install button directly
above it.

Version bumped 0.4.4 (pyproject + the source-tree fallback, which the release job
now asserts against the tag), CHANGELOG entry under a new 0.4.4 section.

Local verification on this branch: python -m build produces
mcp_evidence_validator-0.4.4-*, PYTHONPATH=src pytest passes, ruff check src tests clean, and the runtime reports 0.4.4.

…e PyPI attestations

The README's cosign command pinned the signer identity to @refs/tags/v0.2.1, so copying it from the page against any later release failed outright: 'none of the expected identities matched what was in the certificate'. The certificate for a release names that release's tag and nothing else, so the documented command now takes the tag as $TAG rather than freezing the first one it was written for.

Also drops 'from PyPI once published' (it has been published since v0.4.3) and documents the PEP 740 build attestations the wheel and sdist now carry, with the command that checks them and what a refusal looks like. That path needs no signing key and no cosign install, which makes it the cheaper check for someone who has just run pip install.

Signed-off-by: Empire Labs Pty Ltd <narko4u@gmail.com>
@narko4u
narko4u merged commit b3f1270 into main Sep 16, 2026
8 checks passed
@narko4u
narko4u deleted the release/0.4.4-docs branch September 16, 2026 12:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant