Verificar una versión

Cada versión de zn-gate publicada por el workflow Release se construye una sola vez a partir de una etiqueta (tag) del repositorio usezn/zn. La primera de ellas es la primera publicada después de la 1.5.0-beta.1 (la 1.5.0-beta.2 o la 1.5.0, la que saliera antes). Los mismos archivos se publican después en npm, en PyPI y en la GitHub Release, sin tokens de publicación de larga duración: npm y PyPI los aceptan mediante publicación de confianza (OpenID Connect desde GitHub Actions).

Cada versión incluye:

Cada archivo tiene además una atestación de artefacto de GitHub (procedencia de compilación SLSA), npm muestra una declaración de provenance del paquete y PyPI guarda una atestación de cada archivo de Python.

Qué workflow firmó tu versión

Desde la 1.12.0, los archivos los construye, atesta y firma un workflow reutilizable aparte, build-release.yml, cuyos trabajos de compilación y firma release.yml invoca pero no puede alcanzar. Eso hace que la procedencia de compilación sea SLSA Build Level 3, y build-release.yml es el firmante en los pasos 2 y 3 de abajo. Las versiones hasta la 1.11.x las construyó y firmó el propio release.yml (SLSA Build Level 2: compiladas en un runner alojado por GitHub). El provenance de npm (paso 4) y las atestaciones de PyPI (paso 5) se generan al publicar los archivos, así que en todas las versiones nombran a release.yml en la etiqueta.

Las versiones de Python usan la grafía PEP 440 de la versión de npm: 1.5.0 es 1.5.0 en ambos, y 1.5.0-beta.2 en npm es 1.5.0b2 en PyPI.

La 1.5.0-beta.1 y todas las anteriores se publicaron a mano y no tienen firmas, atestaciones ni provenance. Las comprobaciones de abajo fallan con ellas. Es lo esperado y no significa que los archivos hayan sido manipulados. Para comprobar una de esas versiones, compárala con el código fuente etiquetado del repositorio.

Dist-tags de npm

Una versión preliminar nunca mueve latest. npm install zn-gate instala la última versión final; usa npm install zn-gate@beta (o @next, @alpha) para optar por una versión preliminar.

En los ejemplos de abajo, sustituye v1.12.0 / 1.12.0 por la versión que compruebes, y build-release.yml por release.yml en una versión hasta la 1.11.x.

1. Sumas de verificación

Descarga los archivos y SHA256SUMS de la GitHub Release y ejecuta:

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

Las sumas solo prueban que los archivos coinciden con SHA256SUMS. Comprueba la firma de SHA256SUMS (paso 3) o las atestaciones (paso 2) para saber quién lo produjo.

2. Atestaciones de artefacto de GitHub

Con la CLI de GitHub 2.49 o posterior:

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

Ejecútalo para cada archivo. Comprueba que el archivo lo construyeron los workflows de publicación de usezn/zn a partir de esa etiqueta.

3. Firmas Sigstore

La identidad de firma es el workflow firmante en la etiqueta:

• identidad: https://github.com/usezn/zn/.github/workflows/build-release.yml@refs/tags/v1.12.0 (hasta la 1.11.x: https://github.com/usezn/zn/.github/workflows/release.yml@refs/tags/v1.11.0)
• emisor: https://token.actions.githubusercontent.com

Con 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

Con cosign (2.4 o posterior; cosign 3 no necesita --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

Una firma válida de SHA256SUMS junto con la comprobación de sumas correcta (paso 1) cubre los tres archivos. También puedes verificar cada archivo con su propio bundle de la misma manera.

4. npm

La página del paquete en npmjs.com muestra una sección de provenance que enlaza la versión con el commit y la ejecución del workflow. Desde un proyecto donde esté instalado zn-gate:

npm audit signatures

Comprueba las firmas del registro y las atestaciones de provenance de los paquetes instalados. También puedes consultar las atestaciones directamente:

npm view zn-gate@1.5.0 dist.attestations

5. PyPI

Cada archivo de pypi.org/project/zn-gate tiene una sección de provenance (abre los detalles del archivo en "Download files"). Para comprobarlo desde la línea de comandos con 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. La etiqueta de la versión

Desde la 1.12.0, la etiqueta vX.Y.Z la crea y firma el workflow Tag release con gitsign (firma sin claves de Sigstore): la firma nombra a ese workflow, no a una persona, y el workflow Release se niega a publicar una etiqueta de ese commit sin esa firma. Con gitsign 0.17 o posterior, en un clon del repositorio:

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

Las etiquetas hasta la 1.11.x no están firmadas.

Si algo no coincide

No instales los archivos. Infórmalo en privado como se describe en SECURITY.md.