Verificar uma versão

Cada versão do zn-gate publicada pelo workflow Release é construída uma única vez a partir de uma tag do repositório usezn/zn. A primeira delas é a primeira publicada depois da 1.5.0-beta.1 (a 1.5.0-beta.2 ou a 1.5.0, a que saísse primeiro). Os mesmos arquivos são então publicados no npm, no PyPI e na GitHub Release, sem tokens de publicação de longa duração: o npm e o PyPI os aceitam por meio de publicação confiável (OpenID Connect do GitHub Actions).

Cada versão tem:

Cada arquivo também tem um atestado de artefato do GitHub (procedência de build SLSA), o npm mostra uma declaração de provenance do pacote e o PyPI guarda um atestado de cada arquivo Python.

Qual workflow assinou a sua versão

A partir da 1.12.0, os arquivos são construídos, atestados e assinados por um workflow reutilizável separado, build-release.yml, cujos jobs de build e de assinatura o release.yml chama, mas não consegue alcançar. Isso faz com que a procedência de build seja SLSA Build Level 3, e build-release.yml é o signatário nos passos 2 e 3 abaixo. As versões até a 1.11.x foram construídas e assinadas pelo próprio release.yml (SLSA Build Level 2: construídas em um runner hospedado pelo GitHub). O provenance do npm (passo 4) e os atestados do PyPI (passo 5) são gerados quando os arquivos são publicados; por isso, em todas as versões eles citam release.yml na tag.

As versões Python usam a grafia PEP 440 da versão do npm: 1.5.0 é 1.5.0 nos dois, e 1.5.0-beta.2 no npm é 1.5.0b2 no PyPI.

A 1.5.0-beta.1 e todas as anteriores foram publicadas à mão e não têm assinaturas, atestados nem provenance. As verificações abaixo falham para elas. Isso é esperado e não significa que os arquivos foram adulterados. Para conferir uma dessas versões, compare-a com o código-fonte marcado com a tag no repositório.

Dist-tags do npm

Uma pré-versão nunca move o latest. npm install zn-gate instala a última versão final; use npm install zn-gate@beta (ou @next, @alpha) para optar por uma pré-versão.

Nos exemplos abaixo, substitua v1.12.0 / 1.12.0 pela versão que você está conferindo, e build-release.yml por release.yml em uma versão até a 1.11.x.

1. Somas de verificação

Baixe os arquivos e o SHA256SUMS da GitHub Release e execute:

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

As somas só provam que os arquivos correspondem ao SHA256SUMS. Confira a assinatura do SHA256SUMS (passo 3) ou os atestados (passo 2) para saber quem o produziu.

2. Atestados de artefato do GitHub

Com a CLI do GitHub 2.49 ou 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

Execute para cada arquivo. Ele confere que o arquivo foi construído pelos workflows de publicação do usezn/zn a partir dessa tag.

3. Assinaturas Sigstore

A identidade de assinatura é o workflow signatário na tag:

• identidade: https://github.com/usezn/zn/.github/workflows/build-release.yml@refs/tags/v1.12.0 (até a 1.11.x: https://github.com/usezn/zn/.github/workflows/release.yml@refs/tags/v1.11.0)
• emissor: https://token.actions.githubusercontent.com

Com o 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

Com o cosign (2.4 ou posterior; o cosign 3 não precisa 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

Uma assinatura válida no SHA256SUMS junto com a verificação de somas aprovada (passo 1) cobre os três arquivos. Você também pode verificar cada arquivo com o seu próprio bundle da mesma forma.

4. npm

A página do pacote no npmjs.com mostra uma seção de provenance que liga a versão ao commit e à execução do workflow. A partir de um projeto em que o zn-gate está instalado:

npm audit signatures

Ele confere as assinaturas do registro e os atestados de provenance dos pacotes instalados. Você também pode consultar os atestados diretamente:

npm view zn-gate@1.5.0 dist.attestations

5. PyPI

Cada arquivo em pypi.org/project/zn-gate tem uma seção de provenance (abra os detalhes do arquivo em "Download files"). Para conferir pela linha de comando com o 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. A tag da versão

A partir da 1.12.0, a tag vX.Y.Z é criada e assinada pelo workflow Tag release com o gitsign (assinatura sem chaves do Sigstore): a assinatura cita esse workflow, não uma pessoa, e o workflow Release se recusa a publicar uma tag desse commit sem essa assinatura. Com o gitsign 0.17 ou posterior, em um clone do repositório:

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

As tags até a 1.11.x não são assinadas.

Se algo não coincidir

Não instale os arquivos. Informe em particular, como descrito em SECURITY.md.