# Verifique uma versão

> Confira a assinatura, os checksums, a proveniência e os digests da imagem de uma versão publicada.

Source: https://alexgalhardo.github.io/vukem-video/pt-br/docs/self-hosting/verify-a-release/

## O que você vai aprender

- o que é assinado e atestado em uma versão;
- os comandos que verificam o arquivo compactado e a imagem;
- o que uma falha significa.

## A ideia

Toda versão é construída por um único workflow, `release.yml`, no GitHub. Ele assina o `checksums.txt` com o cosign (sem chave, pelo Sigstore), anexa uma atestação de proveniência da construção e assina e atesta os digests da imagem de contêiner nos dois registros. Você verifica que o arquivo que tem em mãos é o que aquele workflow construiu a partir de uma tag, sem confiar no download.

Instale o `cosign`, a CLI do GitHub `gh` e, para a imagem, o `docker`.

## Início rápido

Defina a versão, depois baixe e verifique o arquivo compactado da sua plataforma:

```bash
VERSION=vX.Y.Z
V="${VERSION#v}"
REPO=AlexGalhardo/vukem-video
ARCHIVE="vukem-video_${V}_linux_amd64.tar.gz"
IDENTITY="^https://github[.]com/$REPO/[.]github/workflows/release[.]yml@refs/tags/v"
ISSUER=https://token.actions.githubusercontent.com
gh release download "$VERSION" -R "$REPO" -p checksums.txt -p checksums.txt.sigstore.json \
  -p "$ARCHIVE" -p "$ARCHIVE.sbom.json"
cosign verify-blob checksums.txt --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp "$IDENTITY" --certificate-oidc-issuer "$ISSUER"
sha256sum --ignore-missing -c checksums.txt
gh attestation verify "$ARCHIVE" -R "$REPO"
```

No macOS, use `shasum -a 256 -c` para a conferência dos checksums. A versão também anexa o pacote de proveniência, `vukem-video.intoto.jsonl`, e uma lista de materiais de software (SBOM) para cada arquivo compactado.

Verifique a imagem de contêiner nos dois registros. Os dois digests impressos precisam ser iguais, porque uma única construção é enviada aos dois:

```bash
for image in ghcr.io/alexgalhardo/vukem-video alexgalhardo/vukem-video; do
  digest="$(docker buildx imagetools inspect "$image:$V" --format "{{.Manifest.Digest}}")"
  cosign verify "$image@$digest" \
    --certificate-identity-regexp "$IDENTITY" --certificate-oidc-issuer "$ISSUER"
  echo "$image $digest"
done
docker run --rm "ghcr.io/alexgalhardo/vukem-video:$V" version
```

O último comando imprime `vukem-video vX.Y.Z`. Os instaladores de Windows e macOS não são assinados com um certificado pago de assinatura de código; o `checksums.txt` assinado é como você os verifica.

## Os instaladores do BETA não são assinados

O BETA não tem assinatura de código paga: não há Apple Developer ID nem notarização, e não há certificado de assinatura de código do Windows. Isso vale para os instaladores do servidor local e para os instaladores do [aplicativo desktop](/docs/guide/desktop) (`vukem-video-desktop_X.Y.Z_windows_amd64_setup.exe`, `..._darwin_arm64.dmg`, `..._darwin_amd64.dmg` e `..._linux_amd64.deb`). A assinatura paga será decidida de novo antes da 1.0. Até lá, a prova de que um arquivo é o que o projeto construiu é a assinatura do `checksums.txt` e a atestação do arquivo, e o seu sistema avisa antes de executá-lo:

- **O SmartScreen do Windows** mostra "O Windows protegeu seu PC". Escolha **Mais informações** e depois **Executar assim mesmo**. O publicador aparece como desconhecido porque não há certificado.
- **O Gatekeeper do macOS** diz que o app ou o pacote não pode ser aberto porque a Apple não consegue verificá-lo. Clique com o botão direito (ou com Control), escolha **Abrir** e depois **Abrir** de novo; ou execute `xattr -d com.apple.quarantine <caminho do arquivo ou do app>`.

Um aviso não é um veredito, e a ausência de aviso não é prova. Verifique o arquivo antes; as conferências abaixo não dependem do que o sistema diz.

Baixe o instalador e execute, com a versão e o nome do arquivo do seu sistema:

```bash
FILE="vukem-video-desktop_${V}_windows_amd64_setup.exe"
gh release download "$VERSION" -R "$REPO" -p "$FILE"
bash scripts/desktop-verify.sh "$VERSION" "$FILE"
```

O `scripts/desktop-verify.sh` está no repositório (clone-o, ou baixe-o a partir da tag). Ele baixa o `checksums.txt` e a assinatura dele, verifica a assinatura com o cosign, confere que o SHA-256 do seu arquivo é igual à linha dele no `checksums.txt` e executa `gh attestation verify` no arquivo. Ele não usa `codesign` nem `signtool`, porque não há assinatura de código para conferir. Sem o script, faça o mesmo à mão com os comandos do início rápido, usando `$FILE` onde eles usam `$ARCHIVE`.

### O feed de atualização

O aplicativo desktop pode procurar uma versão mais nova, mas só quando você ativa: a configuração `update.check` vem desligada e, desligada, o aplicativo não abre nenhuma conexão. Ele lê um único arquivo assinado, `feed.json`, do site do projeto no GitHub Pages (`<site>/updates/feed.json`), e os instaladores que ele lista vêm do mesmo endereço. O feed e cada instalador são assinados com uma chave Ed25519 cuja metade pública está embutida no aplicativo; um arquivo que não bate com a assinatura ou com o digest é recusado. A versão também anexa o `feed.json`, e `bash scripts/release-verify.sh vX.Y.Z` confere que cada digest dele é igual ao do `checksums.txt`.

## Erros comuns

- Pular o `cosign verify-blob` e executar apenas o `sha256sum`: um arquivo de checksums que você não verificou não prova nada.
- Mudar a regexp de identidade para aceitar qualquer workflow. Mantenha-a exata: a identidade é a prova de quem construiu o arquivo.
- Uma execução de recuperação assinada a partir de um branch em vez de uma tag tem a identidade `@refs/heads/<branch>`; a regexp acima a rejeita de propósito. Use a próxima versão com tag.

## Próximos passos

- [Execute a imagem Docker](/docs/self-hosting/docker)
- [O processo de versionamento](/docs/contributing/releases)
