fix(installer): survive a proxy/AV-truncated tool download (k3d/kubectl/helm) (#607)

[shujaatTracebloc]

What & why

Any user installing on a filtered corporate network can dead-end here — via the official one-liner, not just a dev build. A proxy or antivirus can truncate or block a GitHub-release binary mid-transfer; install-k8s.ps1 had a single transport (Invoke-WebRequest) and a single after-the-fact signal (the checksum), so a blocked k3d download stopped the install at the cryptic System tool checksum verification failed. This is the field failure behind #578 ("installer must complete on restricted/corporate networks").

This is not specific to how the installer is launched. The kubectl/k3d/helm downloads happen in Step 2 ("Install system tools") of install-k8s.ps1, which runs identically no matter the entry point — the official releases/download/<tag>/install.ps1 one-liner, a .tgz, or a dev branch. Step 2 always fetches the tools from the same upstream URLs (github.com/k3d-io/…, dl.k8s.io, get.helm.sh) over the user's own network, so the same proxy/AV that truncates the transfer fails the install regardless of source. (It happened to surface during testing, but the install method was not the cause — a real user on that network hits it from the official link.)

Also: the k3d winget fallback was dead weight — k3d has no winget manifest, so Rancher.k3d always returned "No package found" before the direct download ran anyway.

Closes#607. Contributes to #578.

PowerShell (install-k8s.ps1)

• Get-VerifiedDownload tries three transports in turn — Invoke-WebRequest → curl.exe → BITS. A different HTTP stack commonly succeeds where one is blocked/truncated (the primary fix).
• Test-DownloadComplete validates each result before the checksum: present, ≥ a per-tool size floor, and the expected magic bytes (MZ for a .exe, PK for the helm zip). A short / error-page / altered payload is caught as a transfer failure (distinct from a checksum mismatch) and the next transport is tried.
• kubectl / k3d / helm all route through it.
• Removed the dead k3d winget branch (verified k3d has no winget manifest — every id variant 404s).
• Every-transport-failure throws one specific, actionable message (allowlist the hosts / exclude the tools dir from AV), not the cryptic checksum error.

Bash parity (lib/common.sh, lib/setup-linux.sh)

• _assert_download_size gates kubectl/k3d/helm on a size floor before the checksum, so a truncated/blocked transfer reports the real reason. (Linux already uses curl.) TB_MIN_DOWNLOAD_BYTES lets the bats fetch mocks — tiny fixture files — relax the floor; the real floor applies in production.

Tests

• Pester:Test-DownloadComplete (7 cases: complete .exe/.zip, truncated, too-small, wrong-magic, missing, magic-skipped) + a guard that the k3d winget branch is gone. Full Pester suite green (436).
• bats:_assert_download_size (4 cases) + the env hook; existing fetch mocks updated to set TB_MIN_DOWNLOAD_BYTES=0. setup-linux / setup-macos / common / check-drift all green; assertion-enforce clean.
• Manifest regenerated (install-k8s.ps1 / common.sh / setup-linux.sh are manifested).

For reference: the field symptom (official-link install on a corporate machine)

Installing k3d (winget): No package found matching input criteria
Downloading k3d binary directly (amd64)... (14:04:04)
ERROR: System tool checksum verification failed (14:04:07 — 3s for a 28 MB binary)

Not auto-fixed (by design)

If AV delivers a complete but rewritten binary (full size, valid magic, altered bytes), the checksum still fails — correctly — and the user gets the clear "proxy/AV may be rewriting the binary → add an exclusion" message. Antivirus-specific auto-exclusion and an internal tools-mirror override were deliberately left out of scope.

🤖 Generated with Claude Code

---

Note

Low Risk
Installer-only download/validation changes with parity tests; no runtime cluster or auth behavior changes.

Overview
Windows (install-k8s.ps1) adds Test-DownloadComplete (size + optional MZ/PK magic) and Get-VerifiedDownload, which retries kubectl/k3d/helm fetches across Invoke-WebRequest → curl.exe → BITS, only accepting complete payloads before checksum. Failed transfers surface an allowlist/AV message instead of a generic checksum error. The dead k3d winget path is removed (no manifest).

Linux/macOS adds _assert_download_size in common.sh and calls it before checksum verification for kubectl, k3d, and Helm in setup-linux.sh, with the same transfer-vs-tampering distinction. TB_MIN_DOWNLOAD_BYTES=0 in bats mocks keeps existing fetch tests working.

Tests cover the new helpers; manifest.sha256 is updated for touched scripts.

^{Reviewed by Cursor Bugbot for commit 1410766. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8b4fc71. Configure here.}