From 1d46f5d45b4bb0386a34a8b6d17ebffe0b9ba180 Mon Sep 17 00:00:00 2001 From: Harsh Raj Singhania <40535627+HarshRajSinghania@users.noreply.github.com> Date: Wed, 30 Sep 2026 09:06:40 +0530 Subject: [PATCH 1/5] docs: stop recommending pip --verify-attestations Fixes #520. pip has no such flag; document pypi-attestations instead. --- docs/install/pypi.md | 12 ++++++++---- .../contracts/pypi-publish-contract.md | 2 +- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/install/pypi.md b/docs/install/pypi.md index 8d861dd9..f565c377 100644 --- a/docs/install/pypi.md +++ b/docs/install/pypi.md @@ -35,15 +35,19 @@ The `--extra-index-url` is required so dependencies of darnit that exist only on Every release attaches a [PEP 740](https://peps.python.org/pep-0740/) Sigstore attestation. The signing identity is the GitHub Actions workflow that produced the wheel; you can verify the chain back to the canonical repository without trusting anything in between. -### One-step verification with pip +### Verification with `pypi-attestations` -If your pip is 25.0 or newer, `--verify-attestations` does the whole thing automatically: +pip does not have a `--verify-attestations` flag and does not check PEP 740 attestations at install time. Use the [`pypi-attestations`](https://pypi.org/project/pypi-attestations/) tool against a downloaded wheel: ```bash -pip install --verify-attestations darnit-mcp==0.1.0 +pip install pypi-attestations +pip download --no-deps darnit-mcp==0.1.0 +pypi-attestations verify pypi \ + --repository https://github.com/kusari-oss/darnit \ + darnit_mcp-0.1.0-py3-none-any.whl ``` -pip refuses to install if the attestation is missing or fails to verify against PyPI's public certs. +The `--repository` value must match the repository recorded in the attestation (the same identity used by the `sigstore` commands below). ### Manual verification with `sigstore` diff --git a/specs/012-packaging-distribution/contracts/pypi-publish-contract.md b/specs/012-packaging-distribution/contracts/pypi-publish-contract.md index 16b84b2c..a9cdc654 100644 --- a/specs/012-packaging-distribution/contracts/pypi-publish-contract.md +++ b/specs/012-packaging-distribution/contracts/pypi-publish-contract.md @@ -60,7 +60,7 @@ pip install --index-url $INDEX --pre $PKG==$VERSION darnit --version # for darnit-mcp; "$PKG --help" or import smoke for others ``` -`pip install --verify-attestations $PKG==$VERSION` runs additionally for stable releases on `pypi.org`, where the attestation API is available. +For stable releases on `pypi.org`, additionally download the wheel and run `pypi-attestations verify pypi --repository https://github.com/kusari-oss/darnit $WHEEL` (pip has no `--verify-attestations` flag). ## Pre-flight assertions (per package) From 2c7c68b05222de892795de94d0c250a46a4b6800 Mon Sep 17 00:00:00 2001 From: Harsh Raj Singhania <40535627+HarshRajSinghania@users.noreply.github.com> Date: Wed, 7 Oct 2026 11:13:25 +0530 Subject: [PATCH 2/5] docs: verify attestations against darnitdevorg/darnit --- docs/install/pypi.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/install/pypi.md b/docs/install/pypi.md index f565c377..cbdc2840 100644 --- a/docs/install/pypi.md +++ b/docs/install/pypi.md @@ -43,7 +43,7 @@ pip does not have a `--verify-attestations` flag and does not check PEP 740 atte pip install pypi-attestations pip download --no-deps darnit-mcp==0.1.0 pypi-attestations verify pypi \ - --repository https://github.com/kusari-oss/darnit \ + --repository https://github.com/darnitdevorg/darnit \ darnit_mcp-0.1.0-py3-none-any.whl ``` @@ -74,10 +74,10 @@ with open('attestation.sigstore.json', 'w') as out: json.dump(data['attestation_bundles'][0]['attestations'][0], out) " -# Verify against the canonical kusari-oss/darnit identity +# Verify against the canonical darnitdevorg/darnit identity python -m sigstore verify identity \ --bundle attestation.sigstore.json \ - --cert-identity-regexp '^https://github\.com/kusari-oss/darnit/\.github/workflows/release\.yml@' \ + --cert-identity-regexp '^https://github\.com/darnitdevorg/darnit/\.github/workflows/release\.yml@' \ --cert-oidc-issuer https://token.actions.githubusercontent.com \ darnit_mcp-0.1.0-py3-none-any.whl ``` @@ -85,7 +85,7 @@ python -m sigstore verify identity \ A passing verification proves: - The wheel bytes match exactly what was signed. -- The signer was the `release.yml` workflow in `kusari-oss/darnit`. +- The signer was the `release.yml` workflow in `darnitdevorg/darnit`. - The OIDC issuer was GitHub Actions (not some other identity provider). For TestPyPI pre-releases, substitute `test.pypi.org` for `pypi.org` in the provenance URL. @@ -116,4 +116,4 @@ For most users, `pip install darnit-mcp` is the right command. The other package | `ERROR: Package requires a different Python` | Host Python is older than 3.11. Install Python 3.11+ or use [pipx](https://pipx.pypa.io/) with an explicit `--python` flag. | | `Could not find a version that satisfies the requirement` (for a pre-release) | Missing `--pre` flag or wrong `--index-url`. | | Sigstore verification fails with "no attestation bundles" | The release was published before PEP 740 attestations existed, or the attestation hasn't propagated yet (rare; retry in a few minutes). | -| Sigstore verification fails with "identity mismatch" | The wheel was not signed by `kusari-oss/darnit`'s release workflow. **Do not trust this artifact.** Report it via the project's security policy. | +| Sigstore verification fails with "identity mismatch" | The wheel was not signed by `darnitdevorg/darnit`'s release workflow. **Do not trust this artifact.** Report it via the project's security policy. | From 0361bd21ac84bbb5ea293c7efe9a2184a463c3f6 Mon Sep 17 00:00:00 2001 From: Harsh Raj Singhania <40535627+HarshRajSinghania@users.noreply.github.com> Date: Wed, 7 Oct 2026 11:13:27 +0530 Subject: [PATCH 3/5] docs: point the publish contract at darnitdevorg/darnit --- .../contracts/pypi-publish-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/012-packaging-distribution/contracts/pypi-publish-contract.md b/specs/012-packaging-distribution/contracts/pypi-publish-contract.md index a9cdc654..e9ecac63 100644 --- a/specs/012-packaging-distribution/contracts/pypi-publish-contract.md +++ b/specs/012-packaging-distribution/contracts/pypi-publish-contract.md @@ -60,7 +60,7 @@ pip install --index-url $INDEX --pre $PKG==$VERSION darnit --version # for darnit-mcp; "$PKG --help" or import smoke for others ``` -For stable releases on `pypi.org`, additionally download the wheel and run `pypi-attestations verify pypi --repository https://github.com/kusari-oss/darnit $WHEEL` (pip has no `--verify-attestations` flag). +For stable releases on `pypi.org`, additionally download the wheel and run `pypi-attestations verify pypi --repository https://github.com/darnitdevorg/darnit $WHEEL` (pip has no `--verify-attestations` flag). ## Pre-flight assertions (per package) From a8bd81a02681dd5d78ca8509858ac9c76524a3b8 Mon Sep 17 00:00:00 2001 From: Harsh Raj Singhania <40535627+HarshRajSinghania@users.noreply.github.com> Date: Wed, 7 Oct 2026 11:13:30 +0530 Subject: [PATCH 4/5] docs: drop the nonexistent pip --verify-attestations flag from research notes --- specs/012-packaging-distribution/research.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/012-packaging-distribution/research.md b/specs/012-packaging-distribution/research.md index 913d433c..f298a259 100644 --- a/specs/012-packaging-distribution/research.md +++ b/specs/012-packaging-distribution/research.md @@ -49,7 +49,7 @@ A future hardened-image variant (Chainguard- or distroless-based) is tracked as **Rationale**: - All three mechanisms share the same OIDC identity (the GitHub Actions workflow's identity), so one signing identity covers every artifact across every channel. - No long-lived publishing tokens or signing keys live anywhere — satisfies spec FR-007. -- Sigstore attestations on PyPI are now the default expectation for serious open-source Python projects and integrate with `pip install --verify-attestations` (PEP 740). +- Sigstore attestations on PyPI are now the default expectation for serious open-source Python projects (PEP 740). pip has no `--verify-attestations` flag; verify a downloaded wheel with `pypi-attestations verify pypi`. - cosign + GHCR provides verifiable image signatures consumable by every major policy engine (Kyverno, Connaisseur, Sigstore Policy Controller). - The same cosign workflow signs detached blobs for binary downloads. Users verify with `cosign verify-blob`. From dbccf87dd2fd57cfe8c2cc590ebfea7559538485 Mon Sep 17 00:00:00 2001 From: Harsh Raj Singhania <40535627+HarshRajSinghania@users.noreply.github.com> Date: Thu, 8 Oct 2026 11:17:31 +0530 Subject: [PATCH 5/5] docs: drop the old pip attestation flag from packaging research --- specs/012-packaging-distribution/research.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/012-packaging-distribution/research.md b/specs/012-packaging-distribution/research.md index f298a259..87ccdc73 100644 --- a/specs/012-packaging-distribution/research.md +++ b/specs/012-packaging-distribution/research.md @@ -49,7 +49,7 @@ A future hardened-image variant (Chainguard- or distroless-based) is tracked as **Rationale**: - All three mechanisms share the same OIDC identity (the GitHub Actions workflow's identity), so one signing identity covers every artifact across every channel. - No long-lived publishing tokens or signing keys live anywhere — satisfies spec FR-007. -- Sigstore attestations on PyPI are now the default expectation for serious open-source Python projects (PEP 740). pip has no `--verify-attestations` flag; verify a downloaded wheel with `pypi-attestations verify pypi`. +- Sigstore attestations on PyPI are now the default expectation for serious open-source Python projects (PEP 740). pip does not verify PEP 740 attestations at install time; verify a downloaded wheel with `pypi-attestations verify pypi`. - cosign + GHCR provides verifiable image signatures consumable by every major policy engine (Kyverno, Connaisseur, Sigstore Policy Controller). - The same cosign workflow signs detached blobs for binary downloads. Users verify with `cosign verify-blob`.