Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

release: confirm the published checksums.txt pair in finalize and retry it in verifiers

Claudeb3ae587c0082
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index d3be82f9..b0753d31 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -505,9 +505,14 @@ jobs:
sha256sum --check checksums.txt --ignore-missing
# GoReleaser already signed the checksums.txt it published. The step above extends it, so it is
- # signed again here, before it is uploaded: the new checksums.txt and its .sig go up together,
- # and a failure before that leaves GoReleaser's matching pair in place. Inert, like the package
- # signing, until the BEACON_LINUX_SIGNING_KEY secret exists.
+ # signed again here before anything is uploaded; a failure before the upload leaves GoReleaser's
+ # matching pair in place. GitHub replaces release assets one at a time, so the two uploads below
+ # leave a few seconds in which a client can pair files from different uploads (install.sh and
+ # the self-updater fetch both again once before refusing), and a failure between them would
+ # leave a mismatched pair on a public release. So the step reads back what is published and
+ # re-uploads until the pair on the release is exactly what was signed and gpgv accepts it,
+ # failing loudly if it never is. Inert, like the package signing, until the
+ # BEACON_LINUX_SIGNING_KEY secret exists.
- name: Sign and upload checksums.txt
working-directory: dist/release
env:
@@ -545,7 +550,26 @@ jobs:
# Check against the public key GoReleaser attached, the one installers download.
gh release download "$TAG" --repo "$REPO" --pattern beacon-release-key.gpg --clobber
gpgv --keyring "$PWD/beacon-release-key.gpg" checksums.txt.sig checksums.txt
- gh release upload "$TAG" checksums.txt checksums.txt.sig --repo "$REPO" --clobber
+ published="$RUNNER_TEMP/published"
+ for attempt in 1 2 3; do
+ # checksums.txt first: its old signature then fails for at most the one upload, and a
+ # signature is never published ahead of the file it covers.
+ gh release upload "$TAG" checksums.txt --repo "$REPO" --clobber &&
+ gh release upload "$TAG" checksums.txt.sig --repo "$REPO" --clobber ||
+ echo "::warning::upload attempt ${attempt} failed"
+ rm -rf "$published" && mkdir -p "$published"
+ if gh release download "$TAG" --repo "$REPO" --dir "$published" \
+ --pattern checksums.txt --pattern checksums.txt.sig &&
+ cmp -s checksums.txt "$published/checksums.txt" &&
+ cmp -s checksums.txt.sig "$published/checksums.txt.sig" &&
+ gpgv --keyring "$PWD/beacon-release-key.gpg" "$published/checksums.txt.sig" "$published/checksums.txt"; then
+ exit 0
+ fi
+ echo "::warning::the published checksums.txt and checksums.txt.sig do not match what was signed (attempt ${attempt})"
+ sleep $((attempt * 5))
+ done
+ echo "::error title=checksums.txt and its signature do not match::${TAG} is left with a checksums.txt and checksums.txt.sig that pinned installers refuse. Rerun this job."
+ exit 1
- name: Download every file checksums.txt lists
working-directory: dist/release
diff --git a/CLAUDE.md b/CLAUDE.md
index ef281da5..a2cc89cb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -299,8 +299,12 @@ A pushed `v*` tag runs the full release end-to-end via
workflow's OIDC token) for every file `checksums.txt` lists. It needs
`id-token: write` and `attestations: write`, and runs in the `release`
environment only so that, when `BEACON_LINUX_SIGNING_KEY` exists, it can sign
- the extended `checksums.txt` again before uploading it, in one upload with its
- `.sig`; a failure before that leaves GoReleaser's matching pair in place.
+ the extended `checksums.txt` again before uploading it; a failure before that
+ leaves GoReleaser's matching pair in place. GitHub replaces assets one at a time,
+ so it uploads `checksums.txt` then its `.sig`, reads both back and re-uploads
+ until the published pair is what it signed, and fails loudly otherwise;
+ `install.sh` and the self-updater fetch the pair once more before refusing a
+ signature that does not verify, which covers the seconds between the uploads.
Anything else that rewrites `checksums.txt` must come before that step.
Every third-party action in `release.yml`, `release-extension.yml` and
diff --git a/cli/beacon/internal/endpoint/selfupdate/linuxsig.go b/cli/beacon/internal/endpoint/selfupdate/linuxsig.go
index 35457233..6fd6c6e3 100644
--- a/cli/beacon/internal/endpoint/selfupdate/linuxsig.go
+++ b/cli/beacon/internal/endpoint/selfupdate/linuxsig.go
@@ -3,11 +3,13 @@ package selfupdate
import (
"context"
_ "embed"
+ "errors"
"fmt"
"os"
"os/exec"
"path/filepath"
"strings"
+ "time"
)
// pinnedReleaseKeys holds the OpenPGP fingerprints, one per line, of the keys allowed to sign a
@@ -27,6 +29,12 @@ var releaseKeyFingerprints = strings.Fields(pinnedReleaseKeys)
// fingerprint.
const releaseKeyAsset = "beacon-release-key.gpg"
+// releaseSignatureRetryDelay is how long verifyReleaseSignature waits before fetching checksums.txt
+// and its signature a second time. The release's finalize job replaces both after the release is
+// public, and GitHub replaces assets one at a time, so for a few seconds a client can download a
+// checksums.txt and a signature from different uploads; a second fetch gets a matching pair.
+var releaseSignatureRetryDelay = 5 * time.Second
+
// verifyReleaseSignature checks that checksums.txt beside the package is signed by a pinned key
// and lists the package's file name with the downloaded bytes' SHA-256.
func (a *Applier) verifyReleaseSignature(ctx context.Context, pkgURL, pkgPath string) error {
@@ -40,30 +48,60 @@ func (a *Applier) verifyReleaseSignature(ctx context.Context, pkgURL, pkgPath st
return err
}
defer os.RemoveAll(dir)
+ if err := a.fetchSignedChecksums(ctx, base, dir); err != nil {
+ var mismatch *signatureMismatchError
+ if !errors.As(err, &mismatch) {
+ return err
+ }
+ select {
+ case <-ctx.Done():
+ return err
+ case <-time.After(releaseSignatureRetryDelay):
+ }
+ if err := a.fetchSignedChecksums(ctx, base, dir); err != nil {
+ return err
+ }
+ }
+ want, err := checksumFor(filepath.Join(dir, "checksums.txt"), name)
+ if err != nil {
+ return err
+ }
+ return verifySHA256(pkgPath, want)
+}
+
+// signatureMismatchError is a checksums.txt whose signature does not verify, the one failure a
+// second fetch can fix.
+type signatureMismatchError struct{ msg string }
+
+func (e *signatureMismatchError) Error() string { return e.msg }
+
+// fetchSignedChecksums downloads checksums.txt, its signature and the release key into dir and
+// checks that a pinned key signed that checksums.txt.
+func (a *Applier) fetchSignedChecksums(ctx context.Context, base, dir string) error {
for _, f := range []string{"checksums.txt", "checksums.txt.sig", releaseKeyAsset} {
if err := a.download(ctx, base+"/"+f, filepath.Join(dir, f)); err != nil {
return fmt.Errorf("download %s: %w", f, err)
}
}
- sums := filepath.Join(dir, "checksums.txt")
// Status is read from stdout alone, because stderr repeats the key's user ID and the release
// supplies the key.
var stderr strings.Builder
cmd := exec.CommandContext(ctx, "gpgv", "--homedir", dir, "--keyring", filepath.Join(dir, releaseKeyAsset),
- "--status-fd", "1", filepath.Join(dir, "checksums.txt.sig"), sums)
+ "--status-fd", "1", filepath.Join(dir, "checksums.txt.sig"), filepath.Join(dir, "checksums.txt"))
cmd.Stderr = &stderr
out, err := cmd.Output()
if err != nil {
- return fmt.Errorf("checksums.txt signature does not verify: %v: %s", err, strings.TrimSpace(stderr.String()))
+ var exit *exec.ExitError
+ msg := fmt.Sprintf("checksums.txt signature does not verify: %v: %s", err, strings.TrimSpace(stderr.String()))
+ if errors.As(err, &exit) {
+ return &signatureMismatchError{msg: msg}
+ }
+ return errors.New(msg)
}
if !validSigFrom(string(out), releaseKeyFingerprints) {
return fmt.Errorf("checksums.txt is not signed by a Beacon release key (%s)", strings.Join(releaseKeyFingerprints, ", "))
}
- want, err := checksumFor(sums, name)
- if err != nil {
- return err
- }
- return verifySHA256(pkgPath, want)
+ return nil
}
// validSigFrom reports whether gpgv's status output has a good signature whose primary key is one
diff --git a/cli/beacon/internal/endpoint/selfupdate/linuxsig_test.go b/cli/beacon/internal/endpoint/selfupdate/linuxsig_test.go
index ff359c25..58ba5e55 100644
--- a/cli/beacon/internal/endpoint/selfupdate/linuxsig_test.go
+++ b/cli/beacon/internal/endpoint/selfupdate/linuxsig_test.go
@@ -23,14 +23,25 @@ func TestVerifyReleaseSignature(t *testing.T) {
t.Skip("gpgv is not installed")
}
tampered := false
+ // staleChecksums makes the next N checksums.txt downloads come from a different upload than
+ // the signature, as a client sees while finalize replaces the pair.
+ staleChecksums := 0
+ checksumFetches := 0
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
data, err := os.ReadFile(filepath.Join("testdata", "signed-release", filepath.Base(r.URL.Path)))
if err != nil {
http.NotFound(w, r)
return
}
- if tampered && strings.HasSuffix(r.URL.Path, "/checksums.txt") {
- data = []byte(strings.Replace(string(data), "ffff", "eeee", 1))
+ if strings.HasSuffix(r.URL.Path, "/checksums.txt") {
+ checksumFetches++
+ stale := staleChecksums > 0
+ if stale {
+ staleChecksums--
+ }
+ if tampered || stale {
+ data = []byte(strings.Replace(string(data), "ffff", "eeee", 1))
+ }
}
w.Write(data)
}))
@@ -39,6 +50,9 @@ func TestVerifyReleaseSignature(t *testing.T) {
old := releaseKeyFingerprints
releaseKeyFingerprints = []string{testReleaseKeyFingerprint}
defer func() { releaseKeyFingerprints = old }()
+ oldDelay := releaseSignatureRetryDelay
+ releaseSignatureRetryDelay = 0
+ defer func() { releaseSignatureRetryDelay = oldDelay }()
verify := func() error {
a := NewApplier("1.0.0")
a.StageDir = t.TempDir()
@@ -52,6 +66,24 @@ func TestVerifyReleaseSignature(t *testing.T) {
if err := verify(); err != nil {
t.Fatalf("validly signed package refused: %v", err)
}
+
+ // One mismatched fetch, as during finalize's swap: the second fetch gets a matching pair.
+ staleChecksums, checksumFetches = 1, 0
+ if err := verify(); err != nil {
+ t.Fatalf("package refused after a mismatched pair was fetched once: %v", err)
+ }
+ if checksumFetches != 2 {
+ t.Fatalf("checksums.txt fetched %d times, want 2", checksumFetches)
+ }
+ // Mismatched on both fetches: refused, with no third attempt.
+ staleChecksums, checksumFetches = 2, 0
+ if err := verify(); err == nil {
+ t.Fatal("mismatched pair accepted")
+ }
+ if checksumFetches != 2 {
+ t.Fatalf("checksums.txt fetched %d times, want 2", checksumFetches)
+ }
+
tampered = true
if err := verify(); err == nil {
t.Fatal("tampered checksums.txt accepted")
diff --git a/packaging/linux/install.sh b/packaging/linux/install.sh
index 4da2858f..fab722d8 100755
--- a/packaging/linux/install.sh
+++ b/packaging/linux/install.sh
@@ -85,8 +85,19 @@ if [[ -n "$release_key_fingerprints" ]]; then
curl -fsSL "${base}/checksums.txt.sig" -o "${tmp}/checksums.txt.sig" || fail "${tag} has no checksums.txt.sig."
curl -fsSL "${base}/beacon-release-key.gpg" -o "${tmp}/beacon-release-key.gpg" || fail "${tag} has no beacon-release-key.gpg."
mkdir -m 0700 "${tmp}/gnupg"
- status="$(gpgv --homedir "${tmp}/gnupg" --keyring "${tmp}/beacon-release-key.gpg" --status-fd 1 \
- "${tmp}/checksums.txt.sig" "${tmp}/checksums.txt" 2>/dev/null)" || fail "checksums.txt signature does not verify."
+ verify_checksums() {
+ gpgv --homedir "${tmp}/gnupg" --keyring "${tmp}/beacon-release-key.gpg" --status-fd 1 \
+ "${tmp}/checksums.txt.sig" "${tmp}/checksums.txt" 2>/dev/null
+ }
+ # The release's finalize job replaces checksums.txt and its signature after the release is public,
+ # one asset at a time, so a download in those few seconds can pair files from different uploads.
+ # Fetch both once more before giving up.
+ if ! status="$(verify_checksums)"; then
+ sleep 5
+ curl -fsSL "${base}/checksums.txt" -o "${tmp}/checksums.txt" || fail "${tag} has no checksums.txt."
+ curl -fsSL "${base}/checksums.txt.sig" -o "${tmp}/checksums.txt.sig" || fail "${tag} has no checksums.txt.sig."
+ status="$(verify_checksums)" || fail "checksums.txt signature does not verify."
+ fi
# The key file comes from the release too, so only the pinned fingerprint makes it Beacon's.
awk -v fprs="$release_key_fingerprints" 'BEGIN { n = split(toupper(fprs), pinned, ",") }
$1 == "[GNUPG:]" && $2 == "VALIDSIG" { for (i = 1; i <= n; i++) if (toupper($NF) == pinned[i]) ok = 1 }