verify-release.yml

# The last phase: check the page a person actually sees.
#
# Three phases come before this one. The build checks the tree and hands itself
# over, the signing script checks the build before touching it and confirms the
# draft is complete, and the attestation workflow checks the digest it was given
# against the files it downloads. None of them looks at the published release -
# the one thing a user sees - and that is exactly the gap this fills. In the
# project this ritual came from, that gap let a wrong verification command sit
# in the release notes through two releases.
#
# So this downloads what a user downloads and does what a user is told to do,
# with the commands taken from the notes rather than invented here.
#
# What it does not check: the wording of the published page. The owner writes
# that note by hand, and a list of sentences held against it went red on 0.2.0,
# 0.4.0 and 0.5.0 while every file, sum and signature checked out. So the check
# was removed, by the owner's decision of 2026-10-20. release.yml still holds
# the note it GENERATES to that list, before a person replaces it.
#
# Read only, and that is not a detail: a verifier that can publish is not a
# verifier any more.
name: Verify a published release

on:
  release:
    types: [published]
  # Re-runnable by hand against any published tag, because "does that old
  # release still verify" is worth being able to ask without cutting a new one.
  workflow_dispatch:
    inputs:
      tag:
        description: "Published tag to check, for example v0.2.0"
        required: true

permissions:
  contents: read

jobs:
  # macOS is checked on a Mac for the same reason Windows is checked on Windows:
  # a checksum says the bytes did not move and says nothing about who signed
  # them, and nothing but a Mac can read a notarisation ticket.
  verify-macos:
    name: check the macOS downloads the way a Mac does
    runs-on: macos-latest
    timeout-minutes: 20
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - name: which release this is
        id: which
        shell: bash
        env:
          EVENT_TAG: ${{ github.event.release.tag_name }}
          INPUT_TAG: ${{ inputs.tag }}
        run: |
          set -euo pipefail
          tag="${EVENT_TAG:-$INPUT_TAG}"
          test -n "$tag" || { echo "no tag to check"; exit 1; }
          echo "tag=$tag" >> "$GITHUB_OUTPUT"
          echo "checking $tag"

      - name: download the macOS archives
        shell: bash
        env:
          GH_TOKEN: ${{ github.token }}
          TAG: ${{ steps.which.outputs.tag }}
        run: |
          set -euo pipefail
          mkdir -p published
          cd published
          gh release download "$TAG" --repo "$GITHUB_REPOSITORY" --pattern '*macos*.tar.gz'
          ls -l

      - name: every macOS bundle is signed, stapled and by OUR certificate
        shell: bash
        working-directory: published
        run: |
          set -euo pipefail

          # Read out of the Go source rather than written here, so there is one
          # copy of the digest rather than two that can drift apart.
          pinned="$(sed -n 's/.*AppleDeveloperIDSHA256 = "\([0-9a-f]\{64\}\)".*/\1/p' \
                     ../internal/legal/codesign.go)"
          test -n "$pinned" || {
            echo "could not read the pinned Apple certificate out of internal/legal/codesign.go"
            exit 1
          }
          echo "pinned  : $pinned"

          archives=()
          while IFS= read -r line; do archives+=("$line"); done < <(ls *macos*.tar.gz | sort)
          if [ "${#archives[@]}" -ne 2 ]; then
            echo "expected two macOS archives, found ${#archives[@]}"
            exit 1
          fi

          for archive in "${archives[@]}"; do
            work="unpacked_${archive%%.tar.gz}"
            rm -rf "$work"; mkdir -p "$work"
            tar -xzf "$archive" -C "$work"

            app="$(find "$work" -maxdepth 1 -name '*.app' -type d | head -1)"
            if [ -z "$app" ]; then
              echo "$archive holds no .app bundle, so nothing in it can carry a ticket"
              exit 1
            fi

            # What is beside the bundle has to be a link. A copy of the binary
            # out there is refused by Gatekeeper with "invalid resource
            # directory", and ln makes one silently where symlinks do not work.
            name="$(basename "$app" .app)"
            if [ -e "$work/$name" ] && [ ! -L "$work/$name" ]; then
              echo "$archive carries a COPY of $name beside the bundle, not a link"
              exit 1
            fi

            codesign --verify --strict --deep "$app"
            # The ticket, read out of the file itself. This one does not depend
            # on Gatekeeper being switched on, which is why it comes first.
            xcrun stapler validate "$app"

            certs="$(mktemp -d)"
            ( cd "$certs" && codesign -d --extract-certificates=cert "$OLDPWD/$app" >/dev/null 2>&1 )
            actual="$(shasum -a 256 "$certs/cert0" | awk '{print $1}')"
            rm -rf "$certs"
            if [ "$actual" != "$pinned" ]; then
              echo "$archive was signed by a DIFFERENT certificate: $actual"
              exit 1
            fi
            echo "$archive -> $(basename "$app"): signed by the pinned certificate, stapled"
          done

          # Gatekeeper last, and only when it is actually on. A runner with it
          # disabled answers "accepted" to everything, and a check that cannot
          # fail is worse than no check - it reads like proof.
          if spctl --status 2>/dev/null | grep -q "assessments enabled"; then
            for archive in "${archives[@]}"; do
              app="$(find "unpacked_${archive%%.tar.gz}" -maxdepth 1 -name '*.app' -type d | head -1)"
              spctl -a -vv -t exec "$app"
            done
            echo "Gatekeeper accepts both bundles"
          else
            echo "NOTE: Gatekeeper assessments are off on this runner, so spctl was not asked."
            echo "The ticket and the certificate were checked above, and neither needs it."
          fi

  verify:
    name: download what users download, then check it
    # Windows, because one of these questions cannot be asked anywhere else: a
    # checksum says the bytes did not change and says nothing about who signed
    # them.
    runs-on: windows-latest
    timeout-minutes: 20
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - name: which release this is
        id: which
        shell: bash
        env:
          EVENT_TAG: ${{ github.event.release.tag_name }}
          INPUT_TAG: ${{ inputs.tag }}
        run: |
          set -euo pipefail
          tag="${EVENT_TAG:-$INPUT_TAG}"
          test -n "$tag" || { echo "no tag to check"; exit 1; }
          echo "tag=$tag" >> "$GITHUB_OUTPUT"
          echo "checking $tag"

      - name: download every published asset
        shell: bash
        env:
          GH_TOKEN: ${{ github.token }}
          TAG: ${{ steps.which.outputs.tag }}
        run: |
          set -euo pipefail
          mkdir -p published
          cd published
          gh release download "$TAG" --repo "$GITHUB_REPOSITORY"
          ls -l

      - name: everything a release is made of is there
        id: assets
        continue-on-error: true
        shell: bash
        working-directory: published
        env:
          TAG: ${{ steps.which.outputs.tag }}
        # A release missing one file looks almost exactly like a finished one,
        # which is why this counts rather than glances. Eight archives, the
        # installer, the checksums, the bill of materials and the two statements.
        run: |
          set -euo pipefail
          archives="$(ls -1 -- *.zip *.tar.gz 2>/dev/null | wc -l)"
          echo "archives: $archives"
          test "$archives" = "8" || { echo "expected eight archives"; exit 1; }
          # One installer for a release and none for a release candidate - a
          # tag with a hyphen, the rule release.yml and sign_release.py use.
          # Windows Installer reads only the three numbers of a version, so a
          # candidate's installer would carry the release's own version.
          shopt -s nullglob
          installers=(*.msi)
          echo "installers: ${#installers[@]}"
          case "$TAG" in
            *-*) test "${#installers[@]}" = "0" || { echo "a release candidate carries an installer"; exit 1; } ;;
            *) test "${#installers[@]}" = "1" && test -f "tfg-setup_${TAG#v}_windows_amd64.msi" ||
                 { echo "expected one installer, tfg-setup_${TAG#v}_windows_amd64.msi"; exit 1; } ;;
          esac
          shopt -u nullglob
          # Named with the verify- prefix rather than by suffix alone, because
          # the prefix is the only thing keeping these four at the end of the
          # download list, and a suffix is happy with a file that lost it.
          for needed in verify-SHA256SUMS.txt verify-*.spdx.json verify-*.provenance.sigstore.json verify-*.sbom.sigstore.json; do
            ls -1 -- $needed >/dev/null || { echo "missing: $needed"; exit 1; }
          done
          echo "every expected asset is published"

      - name: the checksum a user is told to compare
        id: checksums
        continue-on-error: true
        shell: bash
        working-directory: published
        run: |
          set -euo pipefail
          sha256sum -c verify-SHA256SUMS.txt

      - name: the two commands the notes tell people to run
        id: commands_api
        continue-on-error: true
        shell: bash
        working-directory: published
        env:
          GH_TOKEN: ${{ github.token }}
        # Run against a real download, exactly as written on the release page.
        # The provenance one answers for the five archives nothing signed - the
        # Windows ones changed bytes when a person signed them, and the notes
        # say so. The predicate type is given because gh asks for provenance
        # unless told otherwise, and a wrong URI answers "no attestation found",
        # which reads like a broken release rather than a wrong flag.
        run: |
          set -euo pipefail
          linux="$(ls -1 -- *linux_amd64.tar.gz | head -1)"
          windows="$(ls -1 -- *windows_amd64.zip | head -1)"
          echo "provenance, on a file nothing signed: $linux"
          gh attestation verify "$linux" -R "$GITHUB_REPOSITORY"
          echo "what is inside, on a signed file: $windows"
          gh attestation verify "$windows" -R "$GITHUB_REPOSITORY" \
            --predicate-type https://spdx.dev/Document/v2.3

      - name: the same two commands with no network to the API
        id: commands_offline
        continue-on-error: true
        shell: bash
        working-directory: published
        # The notes promise these work offline with --bundle, and a person
        # behind a proxy that blocks the API is exactly who needs them to.
        run: |
          set -euo pipefail
          linux="$(ls -1 -- *linux_amd64.tar.gz | head -1)"
          windows="$(ls -1 -- *windows_amd64.zip | head -1)"
          gh attestation verify "$linux" -R "$GITHUB_REPOSITORY" \
            --bundle ./*.provenance.sigstore.json
          gh attestation verify "$windows" -R "$GITHUB_REPOSITORY" \
            --bundle ./*.sbom.sigstore.json \
            --predicate-type https://spdx.dev/Document/v2.3

      - name: every Windows program is signed, stamped, and by OUR certificate
        id: signatures
        continue-on-error: true
        shell: pwsh
        working-directory: published
        # This is the step the whole job runs on Windows for. All three, not the
        # first one found: signing two of three and publishing the third
        # unsigned is a mistake that looks like nothing at all on the page.
        #
        # Every library beside a program as well, since 2026-09-17: the window's
        # archive carries the software renderer in opengl\, two files the
        # window loads by path when the driver offers no OpenGL 2.1, and a
        # library beside a signed program is the one file a tamperer would
        # swap. The two are named from the registry the notices are rendered
        # from, so an archive that lost them - the signing repack used to drop
        # a subdirectory's contents without a word - is refused here, on the
        # bytes a person downloads.
        run: |
          $line = Select-String -Path ../internal/legal/codesign.go `
                    -Pattern 'CodeSigningSHA256 = "([0-9a-f]{64})"'
          if (-not $line) { throw "could not read the pinned certificate out of internal/legal/codesign.go" }
          $pinned = $line.Matches[0].Groups[1].Value
          "pinned  : $pinned"

          $beside = Select-String -Path ../internal/legal/companions.go `
                      -Pattern '\{Path: "([^"]+)", Size: [0-9]+, SHA256: "[0-9a-f]{64}"\}' -AllMatches
          $renderer = @($beside.Matches | ForEach-Object { $_.Groups[1].Value })
          if ($renderer.Count -lt 1) { throw "could not read the software renderer's files out of internal/legal/companions.go" }
          "renderer: $($renderer -join ', ')"

          $zips = Get-ChildItem -Filter *windows*.zip
          if ($zips.Count -ne 3) { throw "expected three Windows archives, found $($zips.Count)" }

          $checked = 0
          foreach ($zip in $zips) {
            $into = Join-Path $PWD ("unpacked_" + $zip.BaseName)
            Expand-Archive -LiteralPath $zip.FullName -DestinationPath $into -Force
            $signed = @(Get-ChildItem -Path $into -Recurse -Include *.exe, *.dll)
            if (-not ($signed | Where-Object { $_.Extension -eq '.exe' })) { throw "no program inside $($zip.Name)" }

            if ($zip.Name -like 'tfg-gui_*_windows_amd64.zip') {
              foreach ($rel in $renderer) {
                $file = Join-Path $into ($rel -replace '/', '\')
                if (-not (Test-Path -LiteralPath $file)) { throw "$($zip.Name) does not carry $rel, which the window loads when the driver offers no OpenGL 2.1" }
              }
              "$($zip.Name) carries the software renderer: $($renderer -join ', ')"
            }

            foreach ($file in $signed) {
              $sig = Get-AuthenticodeSignature -LiteralPath $file.FullName
              $rel = $file.FullName.Substring($into.Length + 1)
              "$($zip.Name) -> ${rel}: $($sig.Status)"
              if ($sig.Status -ne 'Valid') { throw "${rel}: signature status is $($sig.Status)" }

              # Without a timestamp the signature dies when the certificate
              # expires, so its absence is a defect rather than a detail.
              if (-not $sig.TimeStamperCertificate) { throw "${rel}: the signature carries no timestamp" }

              $bytes = [System.Security.Cryptography.SHA256]::Create().ComputeHash($sig.SignerCertificate.RawData)
              $actual = ($bytes | ForEach-Object { $_.ToString('x2') }) -join ''
              if ($actual -ne $pinned) {
                throw "$rel was signed by a DIFFERENT certificate: $actual"
              }
              $checked++
            }
          }
          if ($checked -lt 3) { throw "only $checked signed file(s) were checked across three archives" }
          "$checked file(s) signed by the pinned certificate, each with a timestamp"

      - name: the installer is signed, stamped, and by OUR certificate
        id: installer_signature
        continue-on-error: true
        shell: pwsh
        working-directory: published
        # A step of its own rather than a fourth file in the one above, so a
        # release candidate - which carries no installer - leaves that one as
        # it was, and an unsigned installer is its own line in the verdict. The
        # installer is what an administrator runs with the machine's highest
        # rights. Whether there is one at all is the asset count's question,
        # so this checks every installer published and nothing else.
        run: |
          $line = Select-String -Path ../internal/legal/codesign.go `
                    -Pattern 'CodeSigningSHA256 = "([0-9a-f]{64})"'
          if (-not $line) { throw "could not read the pinned certificate out of internal/legal/codesign.go" }
          $pinned = $line.Matches[0].Groups[1].Value
          $installers = @(Get-ChildItem -Filter *.msi)
          if ($installers.Count -eq 0) { "no installer is published, so there is no signature to check"; exit 0 }
          foreach ($msi in $installers) {
            $sig = Get-AuthenticodeSignature -LiteralPath $msi.FullName
            "$($msi.Name): $($sig.Status)"
            if ($sig.Status -ne 'Valid') { throw "$($msi.Name): signature status is $($sig.Status)" }
            if (-not $sig.TimeStamperCertificate) { throw "$($msi.Name): the signature carries no timestamp" }
            $bytes = [System.Security.Cryptography.SHA256]::Create().ComputeHash($sig.SignerCertificate.RawData)
            $actual = ($bytes | ForEach-Object { $_.ToString('x2') }) -join ''
            if ($actual -ne $pinned) { throw "$($msi.Name) was signed by a DIFFERENT certificate: $actual" }
          }
          "$($installers.Count) installer(s) signed by the pinned certificate, with a timestamp"

      - name: a full release has to be the one people are offered
        id: latest
        continue-on-error: true
        shell: bash
        env:
          GH_TOKEN: ${{ github.token }}
          TAG: ${{ steps.which.outputs.tag }}
        # The site and the readme point at /releases/latest, so "published" and
        # "what people get" are the same thing only while this holds. Asked of
        # the API rather than of the event payload, because a dispatch has no
        # payload and a pre-release is supposed to fail this.
        run: |
          set -euo pipefail
          prerelease="$(gh release view "$TAG" --repo "$GITHUB_REPOSITORY" --json isPrerelease --jq .isPrerelease)"
          if [ "$prerelease" = "true" ]; then
            echo "$TAG is a pre-release, so it must not be latest and is not checked here"
            exit 0
          fi
          latest="$(gh api "repos/$GITHUB_REPOSITORY/releases/latest" --jq .tag_name)"
          echo "latest is $latest, this release is $TAG"
          test "$latest" = "$TAG"

      - name: one verdict, not the first failure
        if: always()
        shell: bash
        # Every check above carries continue-on-error, so this step is reached
        # whatever happened, and this step is the one that decides. A person
        # reads a release page once and wants the whole list of what is wrong
        # with it, not the first line - the same rule a recipe follows when it
        # refuses (RC7).
        #
        # Measured on the v0.2.0 publish, 2026-08-28: the offline command step
        # went red and the three checks after it never ran at all. One of those
        # three would have gone red too, because the published notes carry none
        # of the three sentences the notes check looks for. So the run reported
        # one problem where there were at least two, and nothing on the page
        # said the rest had not been asked.
        #
        # outcome and not conclusion. continue-on-error rewrites conclusion to
        # success and leaves outcome alone, so reading conclusion here would
        # report every check as passing however they went.
        env:
          ASSETS: ${{ steps.assets.outcome }}
          CHECKSUMS: ${{ steps.checksums.outcome }}
          COMMANDS_API: ${{ steps.commands_api.outcome }}
          COMMANDS_OFFLINE: ${{ steps.commands_offline.outcome }}
          SIGNATURES: ${{ steps.signatures.outcome }}
          INSTALLER_SIGNATURE: ${{ steps.installer_signature.outcome }}
          LATEST: ${{ steps.latest.outcome }}
        run: |
          set -euo pipefail
          failed=0
          report() {
            printf '  %-52s %s\n' "$2" "$1"
            if [ "$1" != "success" ]; then
              failed=1
            fi
          }
          echo "what this release page answers for:"
          report "$ASSETS" "everything a release is made of is there"
          report "$CHECKSUMS" "the checksum a user is told to compare"
          report "$COMMANDS_API" "the commands the notes tell people to run"
          report "$COMMANDS_OFFLINE" "the same commands with no network"
          report "$SIGNATURES" "every Windows program by our certificate"
          report "$INSTALLER_SIGNATURE" "the installer by our certificate"
          report "$LATEST" "a full release is the one people are offered"
          echo
          if [ "$failed" != "0" ]; then
            echo "This release page does not answer for itself."
            echo "Every line above that is not success is a separate thing to fix,"
            echo "and they are all listed rather than found one release at a time."
            exit 1
          fi
          echo "the release page answers for itself"