From 2bf7e66790912536dedad2d37bec320e500ff44b Mon Sep 17 00:00:00 2001 From: star-nebula <105629895+star-nebula@users.noreply.github.com> Date: Fri, 2 Oct 2026 22:35:47 +0800 Subject: [PATCH] fix(upgrade): verify the release archive before replacing the binary (#335) * refactor(version): own the release checksum helpers The UI asset download already verifies its tarball against the release checksums file, but the fetch, parse, and hashing helpers were private to `internal/uidist`, so a second caller had nothing to reuse: `internal/version` builds the checksums URL and `internal/utils` already hashes files. Move the parser and the fetcher next to the URL they consume, keep the same messages, and drop uidist's private SHA-256 duplicate in favour of `utils.FileHash`. No behavior change. * fix(upgrade): verify the release archive before replacing the binary `skillshare upgrade --cli` streamed the release archive straight into the extractor and renamed the result over the live executable, so an archive that did not match the release was installed anyway. The UI asset download in the same product has always refused on a mismatch, and the release workflow checks every asset against checksums.txt before publishing, so the published hashes were the one integrity signal this path did not consult. Stage the archive to a temp file, compare its SHA-256 with the entry for the downloaded asset name, and extract only when they agree. A mismatch, an entry for a different file, or an unreachable checksums.txt stops the upgrade and leaves the running binary untouched. This guards against damaged or mismatched downloads rather than a release whose assets and checksums were replaced together. Tests use a local server and build the archive each platform extracts, so all four outcomes are covered without network access. The sudo child re-enters this same function, so elevated upgrades are covered too. --------- Co-authored-by: Willie --- cmd/skillshare/upgrade.go | 73 ++++++-- cmd/skillshare/upgrade_checksum_test.go | 164 ++++++++++++++++++ internal/uidist/uidist.go | 57 +----- internal/uidist/uidist_test.go | 20 --- internal/version/checksum.go | 43 +++++ internal/version/checksum_test.go | 51 ++++++ website/docs/reference/commands/upgrade.md | 4 + .../current/reference/commands/upgrade.md | 2 + .../current/reference/commands/upgrade.md | 4 + .../current/reference/commands/upgrade.md | 4 + .../current/reference/commands/upgrade.md | 2 + 11 files changed, 339 insertions(+), 85 deletions(-) create mode 100644 cmd/skillshare/upgrade_checksum_test.go create mode 100644 internal/version/checksum.go create mode 100644 internal/version/checksum_test.go diff --git a/cmd/skillshare/upgrade.go b/cmd/skillshare/upgrade.go index 8b66405e7..21a62e67c 100644 --- a/cmd/skillshare/upgrade.go +++ b/cmd/skillshare/upgrade.go @@ -11,6 +11,7 @@ import ( "net/http" "os" "os/exec" + "path" "path/filepath" "runtime" "strings" @@ -253,7 +254,9 @@ func downloadBinary(execPath, targetVersion string) error { downloadLabel := fmt.Sprintf("Downloading v%s...", targetVersion) downloadSpinner := ui.StartTreeSpinner(downloadLabel, false) - if err := downloadAndReplace(downloadURL, execPath, downloadProgress(downloadLabel, downloadSpinner.Update)); err != nil { + err = downloadAndReplace(downloadURL, versionpkg.BuildChecksumsURL(targetVersion), execPath, + downloadProgress(downloadLabel, downloadSpinner.Update)) + if err != nil { downloadSpinner.Fail("Failed to download") return fmt.Errorf("failed to upgrade: %w", err) } @@ -398,25 +401,75 @@ func downloadProgress(label string, update func(string)) utils.ProgressFunc { } } -func downloadAndReplace(url, destPath string, onProgress utils.ProgressFunc) error { - // Bounds the whole download; the release archive is ~10MB. +// maxArchiveSize bounds the staged release archive; the archives are ~10MB. +const maxArchiveSize = 100 * 1024 * 1024 + +// downloadAndReplace verifies the release archive against the release +// checksums file before replacing the binary. The archive is staged to a temp +// file first because checksums.txt covers the compressed asset, not the binary +// extracted from it. +func downloadAndReplace(downloadURL, checksumsURL, destPath string, onProgress utils.ProgressFunc) error { + expectedHash, err := versionpkg.FetchChecksum(checksumsURL, path.Base(downloadURL)) + if err != nil { + return fmt.Errorf("failed to fetch checksum: %w", err) + } + + archivePath, err := downloadArchive(downloadURL, onProgress) + if err != nil { + return err + } + defer os.Remove(archivePath) + + actualHash, err := utils.FileHash(archivePath) + if err != nil { + return fmt.Errorf("failed to compute checksum: %w", err) + } + if actualHash != expectedHash { + return fmt.Errorf("checksum mismatch: expected %s, got %s", expectedHash, actualHash) + } + + archive, err := os.Open(archivePath) + if err != nil { + return err + } + defer archive.Close() + + // Windows uses zip, others use tar.gz + if runtime.GOOS == "windows" { + return extractFromZip(archive, destPath) + } + return extractFromTarGz(archive, destPath) +} + +func downloadArchive(url string, onProgress utils.ProgressFunc) (string, error) { client := &http.Client{Timeout: 5 * time.Minute} resp, err := client.Get(url) if err != nil { - return err + return "", err } defer resp.Body.Close() if resp.StatusCode != 200 { - return fmt.Errorf("download failed with status %d", resp.StatusCode) + return "", fmt.Errorf("download failed with status %d", resp.StatusCode) } - body := utils.NewProgressReader(resp.Body, resp.ContentLength, onProgress) - // Windows uses zip, others use tar.gz - if runtime.GOOS == "windows" { - return extractFromZip(body, destPath) + tmp, err := os.CreateTemp("", "skillshare-upgrade-archive-*") + if err != nil { + return "", err } - return extractFromTarGz(body, destPath) + defer tmp.Close() + + limited := io.LimitReader(utils.NewProgressReader(resp.Body, resp.ContentLength, onProgress), maxArchiveSize+1) + n, err := io.Copy(tmp, limited) + if err != nil { + os.Remove(tmp.Name()) + return "", err + } + if n > maxArchiveSize { + os.Remove(tmp.Name()) + return "", fmt.Errorf("archive exceeds the maximum size (%d MB)", maxArchiveSize/(1024*1024)) + } + return tmp.Name(), nil } func extractFromTarGz(r io.Reader, destPath string) error { diff --git a/cmd/skillshare/upgrade_checksum_test.go b/cmd/skillshare/upgrade_checksum_test.go new file mode 100644 index 000000000..677c995b1 --- /dev/null +++ b/cmd/skillshare/upgrade_checksum_test.go @@ -0,0 +1,164 @@ +package main + +import ( + "archive/tar" + "archive/zip" + "bytes" + "compress/gzip" + "crypto/sha256" + "encoding/hex" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "runtime" + "strings" + "testing" +) + +const releaseAsset = "skillshare_1.0.0_linux_amd64.tar.gz" + +// releaseArchive builds the platform asset the self-uploader expects: a zip +// holding skillshare.exe on Windows, a tar.gz holding skillshare elsewhere. +func releaseArchive(t *testing.T, payload string) []byte { + t.Helper() + + var buf bytes.Buffer + if runtime.GOOS == "windows" { + zw := zip.NewWriter(&buf) + w, err := zw.Create("skillshare.exe") + if err != nil { + t.Fatal(err) + } + if _, err := w.Write([]byte(payload)); err != nil { + t.Fatal(err) + } + if err := zw.Close(); err != nil { + t.Fatal(err) + } + return buf.Bytes() + } + + gw := gzip.NewWriter(&buf) + tw := tar.NewWriter(gw) + if err := tw.WriteHeader(&tar.Header{Name: "skillshare", Mode: 0755, Size: int64(len(payload))}); err != nil { + t.Fatal(err) + } + if _, err := tw.Write([]byte(payload)); err != nil { + t.Fatal(err) + } + if err := tw.Close(); err != nil { + t.Fatal(err) + } + if err := gw.Close(); err != nil { + t.Fatal(err) + } + return buf.Bytes() +} + +func sha256Hex(b []byte) string { + sum := sha256.Sum256(b) + return hex.EncodeToString(sum[:]) +} + +// upgradeServer serves the archive and a checksums file written independently, +// so a test can put the two out of agreement. An empty checksums body 404s. +func upgradeServer(t *testing.T, archive []byte, checksums string) *httptest.Server { + t.Helper() + + mux := http.NewServeMux() + mux.HandleFunc("/"+releaseAsset, func(w http.ResponseWriter, _ *http.Request) { + if _, err := w.Write(archive); err != nil { + t.Error(err) + } + }) + mux.HandleFunc("/checksums.txt", func(w http.ResponseWriter, _ *http.Request) { + if checksums == "" { + w.WriteHeader(http.StatusNotFound) + return + } + if _, err := w.Write([]byte(checksums)); err != nil { + t.Error(err) + } + }) + + srv := httptest.NewServer(mux) + t.Cleanup(srv.Close) + return srv +} + +func runningBinary(t *testing.T) string { + t.Helper() + + dest := filepath.Join(t.TempDir(), "skillshare") + if err := os.WriteFile(dest, []byte("old binary"), 0755); err != nil { + t.Fatal(err) + } + return dest +} + +func readBinary(t *testing.T, dest string) string { + t.Helper() + + data, err := os.ReadFile(dest) + if err != nil { + t.Fatal(err) + } + return string(data) +} + +func TestDownloadAndReplace_VerifiedArchiveReplacesBinary(t *testing.T) { + archive := releaseArchive(t, "new binary") + srv := upgradeServer(t, archive, sha256Hex(archive)+" "+releaseAsset+"\n") + dest := runningBinary(t) + + if err := downloadAndReplace(srv.URL+"/"+releaseAsset, srv.URL+"/checksums.txt", dest, nil); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got := readBinary(t, dest); got != "new binary" { + t.Errorf("dest = %q, want the archive payload", got) + } +} + +func TestDownloadAndReplace_MismatchedChecksumLeavesBinaryAlone(t *testing.T) { + archive := releaseArchive(t, "tampered payload") + expected := sha256Hex(releaseArchive(t, "genuine payload")) + srv := upgradeServer(t, archive, expected+" "+releaseAsset+"\n") + dest := runningBinary(t) + + err := downloadAndReplace(srv.URL+"/"+releaseAsset, srv.URL+"/checksums.txt", dest, nil) + if err == nil || !strings.Contains(err.Error(), "checksum mismatch") { + t.Fatalf("err = %v, want a checksum mismatch", err) + } + if got := readBinary(t, dest); got != "old binary" { + t.Errorf("the running binary was replaced despite the mismatch: %q", got) + } +} + +func TestDownloadAndReplace_AbsentAssetEntryLeavesBinaryAlone(t *testing.T) { + archive := releaseArchive(t, "new binary") + srv := upgradeServer(t, archive, sha256Hex(archive)+" other_asset.tar.gz\n") + dest := runningBinary(t) + + err := downloadAndReplace(srv.URL+"/"+releaseAsset, srv.URL+"/checksums.txt", dest, nil) + if err == nil || !strings.Contains(err.Error(), "not found in checksums.txt") { + t.Fatalf("err = %v, want the asset to be reported missing", err) + } + if got := readBinary(t, dest); got != "old binary" { + t.Errorf("dest = %q, want the running binary untouched", got) + } +} + +func TestDownloadAndReplace_UnreachableChecksumsLeavesBinaryAlone(t *testing.T) { + archive := releaseArchive(t, "new binary") + srv := upgradeServer(t, archive, "") + dest := runningBinary(t) + + err := downloadAndReplace(srv.URL+"/"+releaseAsset, srv.URL+"/checksums.txt", dest, nil) + if err == nil || !strings.Contains(err.Error(), "checksums.txt returned HTTP 404") { + t.Fatalf("err = %v, want the checksums.txt status reported", err) + } + if got := readBinary(t, dest); got != "old binary" { + t.Errorf("dest = %q, want the running binary untouched", got) + } +} diff --git a/internal/uidist/uidist.go b/internal/uidist/uidist.go index cfafae009..598fc7871 100644 --- a/internal/uidist/uidist.go +++ b/internal/uidist/uidist.go @@ -2,10 +2,7 @@ package uidist import ( "archive/tar" - "bufio" "compress/gzip" - "crypto/sha256" - "encoding/hex" "fmt" "io" "net/http" @@ -45,7 +42,7 @@ func Download(ver string, onProgress utils.ProgressFunc) error { dir := CacheDir(ver) // Fetch expected checksum - expectedHash, err := fetchChecksum(ver) + expectedHash, err := version.FetchChecksum(version.BuildChecksumsURL(ver), AssetName) if err != nil { return fmt.Errorf("failed to fetch checksum: %w", err) } @@ -59,7 +56,7 @@ func Download(ver string, onProgress utils.ProgressFunc) error { defer os.Remove(tmpFile) // Verify checksum - actualHash, err := fileSHA256(tmpFile) + actualHash, err := utils.FileHash(tmpFile) if err != nil { return fmt.Errorf("failed to compute checksum: %w", err) } @@ -116,41 +113,6 @@ func cleanOldVersions(currentVer string) error { return nil } -// fetchChecksum downloads checksums.txt and parses the SHA256 for AssetName. -func fetchChecksum(ver string) (string, error) { - url := version.BuildChecksumsURL(ver) - client := &http.Client{Timeout: 30 * time.Second} - resp, err := client.Get(url) - if err != nil { - return "", err - } - defer resp.Body.Close() - - if resp.StatusCode != http.StatusOK { - return "", fmt.Errorf("checksums.txt returned HTTP %d", resp.StatusCode) - } - - return parseChecksum(resp.Body, AssetName) -} - -// parseChecksum reads a checksums.txt (format: "hash filename\n") and returns -// the hash for the given target filename. -func parseChecksum(r io.Reader, target string) (string, error) { - scanner := bufio.NewScanner(r) - for scanner.Scan() { - line := scanner.Text() - // GoReleaser format: " " - parts := strings.Fields(line) - if len(parts) == 2 && parts[1] == target { - return parts[0], nil - } - } - if err := scanner.Err(); err != nil { - return "", err - } - return "", fmt.Errorf("checksum for %s not found in checksums.txt", target) -} - // maxDownloadSize limits the UI dist download to prevent unexpected disk usage. const maxDownloadSize = 100 * 1024 * 1024 // 100 MB @@ -187,21 +149,6 @@ func downloadToTemp(url string, onProgress utils.ProgressFunc) (string, error) { return tmp.Name(), nil } -// fileSHA256 computes the SHA-256 hex digest of a file. -func fileSHA256(path string) (string, error) { - f, err := os.Open(path) - if err != nil { - return "", err - } - defer f.Close() - - h := sha256.New() - if _, err := io.Copy(h, f); err != nil { - return "", err - } - return hex.EncodeToString(h.Sum(nil)), nil -} - // maxFileSize limits individual file extraction to prevent decompression bombs. const maxFileSize = 50 * 1024 * 1024 // 50 MB per file diff --git a/internal/uidist/uidist_test.go b/internal/uidist/uidist_test.go index 4fd08907f..5c34a7d97 100644 --- a/internal/uidist/uidist_test.go +++ b/internal/uidist/uidist_test.go @@ -6,7 +6,6 @@ import ( "compress/gzip" "os" "path/filepath" - "strings" "testing" ) @@ -52,25 +51,6 @@ func TestIsCached_Present(t *testing.T) { } } -func TestParseChecksum(t *testing.T) { - input := "abc123 skillshare_1.0.0_linux_amd64.tar.gz\ndef456 skillshare-ui-dist.tar.gz\n" - hash, err := parseChecksum(strings.NewReader(input), "skillshare-ui-dist.tar.gz") - if err != nil { - t.Fatal(err) - } - if hash != "def456" { - t.Errorf("got %s, want def456", hash) - } -} - -func TestParseChecksum_NotFound(t *testing.T) { - input := "abc123 other-file.tar.gz\n" - _, err := parseChecksum(strings.NewReader(input), "skillshare-ui-dist.tar.gz") - if err == nil { - t.Error("expected error for missing checksum") - } -} - func TestExtractTarGz(t *testing.T) { // Create an in-memory tar.gz with test files tarball := createTestTarGz(t, map[string]string{ diff --git a/internal/version/checksum.go b/internal/version/checksum.go new file mode 100644 index 000000000..55a235b07 --- /dev/null +++ b/internal/version/checksum.go @@ -0,0 +1,43 @@ +package version + +import ( + "bufio" + "fmt" + "io" + "net/http" + "strings" + "time" +) + +// FetchChecksum downloads the release checksums file at url and returns the +// hash recorded for asset. url normally comes from BuildChecksumsURL. +func FetchChecksum(url, asset string) (string, error) { + client := &http.Client{Timeout: 30 * time.Second} + resp, err := client.Get(url) + if err != nil { + return "", err + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + return "", fmt.Errorf("checksums.txt returned HTTP %d", resp.StatusCode) + } + + return ParseChecksum(resp.Body, asset) +} + +// ParseChecksum reads a checksums file (" ", the format +// GoReleaser writes) and returns the hash for the given target filename. +func ParseChecksum(r io.Reader, target string) (string, error) { + scanner := bufio.NewScanner(r) + for scanner.Scan() { + parts := strings.Fields(scanner.Text()) + if len(parts) == 2 && parts[1] == target { + return parts[0], nil + } + } + if err := scanner.Err(); err != nil { + return "", err + } + return "", fmt.Errorf("checksum for %s not found in checksums.txt", target) +} diff --git a/internal/version/checksum_test.go b/internal/version/checksum_test.go new file mode 100644 index 000000000..9a0388082 --- /dev/null +++ b/internal/version/checksum_test.go @@ -0,0 +1,51 @@ +package version + +import ( + "net/http" + "net/http/httptest" + "strings" + "testing" +) + +func TestParseChecksum(t *testing.T) { + input := "abc123 skillshare_1.0.0_linux_amd64.tar.gz\ndef456 skillshare-ui-dist.tar.gz\n" + hash, err := ParseChecksum(strings.NewReader(input), "skillshare-ui-dist.tar.gz") + if err != nil { + t.Fatal(err) + } + if hash != "def456" { + t.Errorf("got %s, want def456", hash) + } +} + +func TestParseChecksum_NotFound(t *testing.T) { + input := "abc123 other-file.tar.gz\n" + _, err := ParseChecksum(strings.NewReader(input), "skillshare-ui-dist.tar.gz") + if err == nil { + t.Error("expected error for missing checksum") + } +} + +func TestFetchChecksum(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if strings.HasSuffix(r.URL.Path, "checksums.txt") { + w.Write([]byte("aaa111 skillshare_1.0.0_linux_amd64.tar.gz\n")) + return + } + w.WriteHeader(http.StatusNotFound) + })) + defer srv.Close() + + got, err := FetchChecksum(srv.URL+"/checksums.txt", "skillshare_1.0.0_linux_amd64.tar.gz") + if err != nil { + t.Fatal(err) + } + if got != "aaa111" { + t.Errorf("got %q, want aaa111", got) + } + + _, err = FetchChecksum(srv.URL+"/missing.txt", "skillshare_1.0.0_linux_amd64.tar.gz") + if err == nil || !strings.Contains(err.Error(), "returned HTTP 404") { + t.Errorf("err = %v, want the checksums.txt status to be reported", err) + } +} diff --git a/website/docs/reference/commands/upgrade.md b/website/docs/reference/commands/upgrade.md index caa7c81b8..bd319132f 100644 --- a/website/docs/reference/commands/upgrade.md +++ b/website/docs/reference/commands/upgrade.md @@ -102,6 +102,10 @@ skillshare sync # Distribute to all targets The `skillshare` executable itself. Downloads from GitHub releases. +The archive is verified against the release's `checksums.txt` before your running binary is +replaced, so a damaged or mismatched download stops the upgrade instead of installing itself. +The current binary stays untouched, and the error names the mismatch. + In a terminal, the download shows how much has arrived, so a slow connection does not look like a hang. The Web UI assets below show the same. diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/upgrade.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/upgrade.md index 5221dae29..76290e60b 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/upgrade.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/upgrade.md @@ -102,6 +102,8 @@ skillshare sync # すべての Target に配布 `skillshare` 実行ファイル自体です。GitHub releases からダウンロードされます。 +実行中のバイナリを置き換える前に、リリースの `checksums.txt` と照合してアーカイブを検証します。そのため、破損したり一致しないダウンロードはインストールされるのではなく、アップグレードが中止されます。現在のバイナリはそのまま残り、エラーが不一致を示します。 + ターミナルでは、ダウンロード済みの量が表示されるため、回線が遅くてもハングしたようには見えません。下記の Web UI アセットでも同じ表示になります。 ``` diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/upgrade.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/upgrade.md index 6d27813b0..0fe975ae7 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/upgrade.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/upgrade.md @@ -102,6 +102,10 @@ skillshare sync # 모든 target으로 배포 `skillshare` 실행 파일 자체입니다. GitHub 릴리스에서 다운로드합니다. +실행 중인 바이너리를 교체하기 전에 릴리스의 `checksums.txt` 와 대조해 아카이브를 검증하므로, +손상되었거나 일치하지 않는 다운로드는 설치되는 대신 업그레이드가 중단됩니다. 현재 바이너리는 +그대로 유지되고, 오류 메시지가 불일치를 알려 줍니다. + 터미널에서는 다운로드가 얼마나 받아졌는지 표시하므로, 연결이 느려도 멈춘 것처럼 보이지 않습니다. 아래의 Web UI 에셋도 동일하게 표시합니다. diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/upgrade.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/upgrade.md index 3826d57f4..abacf8087 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/upgrade.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/upgrade.md @@ -102,6 +102,10 @@ skillshare sync # 分发到所有 targets `skillshare` 可执行文件本身。从 GitHub releases 下载。 +在替换你正在运行的可执行文件之前,会先按 release 的 `checksums.txt` 校验下载的压缩包, +所以损坏或不匹配的下载只会中止升级,而不是把自己装上。当前的可执行文件保持原样, +错误信息会指明不匹配之处。 + 在终端中,下载时会显示已经下载了多少,这样网络较慢时就不会看起来像是卡住了。 下面的 Web UI 资源也会以同样的方式显示。 diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/upgrade.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/upgrade.md index d1c36c3c0..ff714f729 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/upgrade.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/upgrade.md @@ -102,6 +102,8 @@ skillshare sync # 分發到所有 targets `skillshare` 執行檔本身。從 GitHub releases 下載。 +取代你正在執行的二進位檔之前,會先依 release 的 `checksums.txt` 驗證下載的壓縮檔,所以損毀或比對不一致的下載只會中止升級,不會把自己安裝上去。現行二進位檔維持原樣,錯誤訊息會指出不一致的地方。 + 在終端機中,下載時會顯示已下載的大小,因此連線較慢時不會看起來像是卡住。下方的 Web UI 資源也會顯示相同的進度。 ```