Vérifier une version

Chaque version de zn-gate publiée par le workflow Release est construite une seule fois à partir d'un tag du dépôt usezn/zn. La première de ces versions est la première publiée après la 1.5.0-beta.1 (la 1.5.0-beta.2 ou la 1.5.0, selon la première sortie). Les mêmes fichiers sont ensuite publiés sur npm, sur PyPI et dans la GitHub Release, sans jeton de publication de longue durée : npm et PyPI les acceptent grâce à la publication de confiance (OpenID Connect depuis GitHub Actions).

Chaque version contient :

Chaque fichier a aussi une attestation d'artefact GitHub (provenance de build SLSA), npm affiche une déclaration de provenance pour le paquet et PyPI conserve une attestation pour chaque fichier Python.

Quel workflow a signé votre version

À partir de la 1.12.0, les fichiers sont construits, attestés et signés par un workflow réutilisable distinct, build-release.yml, dont release.yml appelle les jobs de build et de signature sans pouvoir y accéder. La provenance de build atteint ainsi le niveau SLSA Build Level 3, et build-release.yml est le signataire aux étapes 2 et 3 ci-dessous. Les versions jusqu'à la 1.11.x ont été construites et signées par release.yml lui-même (SLSA Build Level 2 : construites sur un runner hébergé par GitHub). La provenance npm (étape 4) et les attestations PyPI (étape 5) sont créées à la publication des fichiers ; pour toutes les versions, elles désignent donc release.yml au tag.

Les versions Python utilisent l'écriture PEP 440 de la version npm : 1.5.0 est 1.5.0 des deux côtés, et 1.5.0-beta.2 sur npm devient 1.5.0b2 sur PyPI.

La 1.5.0-beta.1 et toutes les versions antérieures ont été publiées à la main et n'ont ni signature, ni attestation, ni provenance. Les vérifications ci-dessous échouent pour elles. C'est normal et cela ne signifie pas que les fichiers ont été altérés. Pour vérifier l'une de ces versions, comparez-la avec le code source taggé du dépôt.

Dist-tags npm

Une préversion ne déplace jamais latest. npm install zn-gate installe la dernière version finale ; utilisez npm install zn-gate@beta (ou @next, @alpha) pour choisir une préversion.

Dans les exemples ci-dessous, remplacez v1.12.0 / 1.12.0 par la version que vous vérifiez, et build-release.yml par release.yml pour une version jusqu'à la 1.11.x.

1. Sommes de contrôle

Téléchargez les fichiers et SHA256SUMS depuis la GitHub Release, puis :

sha256sum --ignore-missing -c SHA256SUMS      # Linux
shasum -a 256 --ignore-missing -c SHA256SUMS  # macOS

Les sommes de contrôle prouvent seulement que les fichiers correspondent à SHA256SUMS. Vérifiez la signature de SHA256SUMS (étape 3) ou les attestations (étape 2) pour savoir qui l'a produit.

2. Attestations d'artefact GitHub

Avec la CLI GitHub 2.49 ou plus récente :

gh attestation verify zn-gate-1.12.0.tgz \
  --repo usezn/zn \
  --signer-workflow usezn/zn/.github/workflows/build-release.yml \
  --source-ref refs/tags/v1.12.0

Lancez-la pour chaque fichier. Elle vérifie que le fichier a été construit par les workflows de publication de usezn/zn à partir de ce tag.

3. Signatures Sigstore

L'identité de signature est le workflow signataire au tag :

• identité : https://github.com/usezn/zn/.github/workflows/build-release.yml@refs/tags/v1.12.0 (jusqu'à la 1.11.x : https://github.com/usezn/zn/.github/workflows/release.yml@refs/tags/v1.11.0)
• émetteur : https://token.actions.githubusercontent.com

Avec sigstore-python :

python -m pip install sigstore
python -m sigstore verify identity \
  --bundle SHA256SUMS.sigstore.json \
  --cert-identity https://github.com/usezn/zn/.github/workflows/build-release.yml@refs/tags/v1.12.0 \
  --cert-oidc-issuer https://token.actions.githubusercontent.com \
  SHA256SUMS

Avec cosign (2.4 ou plus récent ; cosign 3 n'a pas besoin de --new-bundle-format) :

cosign verify-blob SHA256SUMS \
  --bundle SHA256SUMS.sigstore.json \
  --new-bundle-format \
  --certificate-identity https://github.com/usezn/zn/.github/workflows/build-release.yml@refs/tags/v1.12.0 \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Une signature valide sur SHA256SUMS associée à une vérification de sommes réussie (étape 1) couvre les trois fichiers. Vous pouvez aussi vérifier chaque fichier avec son propre bundle de la même manière.

4. npm

La page du paquet sur npmjs.com affiche une section de provenance qui relie la version au commit et à l'exécution du workflow. Depuis un projet où zn-gate est installé :

npm audit signatures

Cette commande vérifie les signatures du registre et les attestations de provenance des paquets installés. Vous pouvez aussi consulter directement les attestations :

npm view zn-gate@1.5.0 dist.attestations

5. PyPI

Chaque fichier sur pypi.org/project/zn-gate a une section de provenance (ouvrez les détails du fichier sous « Download files »). Pour la vérifier en ligne de commande avec pypi-attestations :

python -m pip install pypi-attestations
pypi-attestations verify pypi \
  --repository https://github.com/usezn/zn \
  pypi:zn_gate-1.5.0-py3-none-any.whl

6. Le tag de la version

À partir de la 1.12.0, le tag vX.Y.Z est créé et signé par le workflow Tag release avec gitsign (signature sans clé Sigstore) : la signature désigne ce workflow, pas une personne, et le workflow Release refuse de publier un tag de ce commit sans cette signature. Avec gitsign 0.17 ou plus récent, dans un clone du dépôt :

git fetch origin tag v1.12.0
gitsign verify-tag v1.12.0 \
  --certificate-identity https://github.com/usezn/zn/.github/workflows/tag-release.yml@refs/heads/main \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Les tags jusqu'à la 1.11.x ne sont pas signés.

Si quelque chose ne correspond pas

N'installez pas les fichiers. Signalez-le en privé comme décrit dans SECURITY.md.