Merge PR #2621: Harden install trust model and clarify security guidance

Add SHA256 checksum verification to install scripts and reorder
security verification steps in documentation.

PR: #2621
Author: maphew

Author: steveyegge

README.md

@@ -70,6 +70,16 @@ Beads supports hierarchical IDs for epics:
 
 **Requirements:** Linux, FreeBSD, macOS, or Windows.
 
+### Security And Verification
+
+Before trusting any downloaded binary, verify its checksum against the release `checksums.txt`.
+
+The install scripts verify release checksums before install. For manual installs, do this verification yourself before first run.
+
+On macOS, `scripts/install.sh` preserves the downloaded signature by default. Local ad-hoc re-signing is explicit opt-in via `BEADS_INSTALL_RESIGN_MACOS=1`.
+
+See [docs/ANTIVIRUS.md](docs/ANTIVIRUS.md) for Windows AV false-positive guidance and verification workflow.
+
 ## 🌐 Community Tools
 
 See [docs/COMMUNITY_TOOLS.md](docs/COMMUNITY_TOOLS.md) for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps.

docs/ANTIVIRUS.md

@@ -4,6 +4,8 @@
 
 Some antivirus software may flag beads (`bd` or `bd.exe`) as malicious. This is a **false positive** - beads is a legitimate, open-source command-line tool for issue tracking.
 
+Beads release installers now verify downloaded archives against release `checksums.txt` before installation. For users who manually install binaries, checksum verification should be the first trust step before running `bd` or creating antivirus exclusions.
+
 ## Why This Happens
 
 Go binaries (including beads) are sometimes flagged by antivirus software due to:
@@ -26,7 +28,27 @@ Kaspersky's PDM (Proactive Defense Module) uses behavioral analysis that commonl
 
 ## Solutions for Users
 
-### Option 1: Add Exclusion (Recommended)
+### Option 1: Verify File Integrity (Recommended First)
+
+Before running a downloaded binary or adding antivirus exclusions, verify the file is legitimate:
+
+1. Download beads from the [official GitHub releases](https://github.com/steveyegge/beads/releases)
+2. Verify the SHA256 checksum matches the `checksums.txt` file in the release
+3. If a release includes code signing, verify that signature too
+
+**Verify checksum (Windows PowerShell):**
+```powershell
+Get-FileHash bd.exe -Algorithm SHA256
+```
+
+**Verify checksum (macOS/Linux):**
+```bash
+shasum -a 256 bd
+```
+
+Compare the output with the checksum in `checksums.txt` from the release page.
+
+### Option 2: Add Exclusion (After Verification)
 
 Add beads to your antivirus exclusion list:
 
@@ -47,26 +69,6 @@ Add beads to your antivirus exclusion list:
 - Look for "Exclusions", "Whitelist", or "Trusted Applications" settings
 - Add the beads installation directory or executable
 
-### Option 2: Verify File Integrity
-
-Before adding an exclusion, verify the downloaded file is legitimate:
-
-1. Download beads from the [official GitHub releases](https://github.com/steveyegge/beads/releases)
-2. Verify the SHA256 checksum matches the `checksums.txt` file in the release
-3. Check the file is signed (future releases will include code signing)
-
-**Verify checksum (Windows PowerShell):**
-```powershell
-Get-FileHash bd.exe -Algorithm SHA256
-```
-
-**Verify checksum (macOS/Linux):**
-```bash
-shasum -a 256 bd
-```
-
-Compare the output with the checksum in `checksums.txt` from the release page.
-
 ### Option 3: Report False Positive
 
 Help improve detection accuracy by reporting the false positive:
@@ -150,7 +152,7 @@ However, results vary by antivirus vendor and version.
 
 Yes. Beads is:
 - Open source (all code is auditable on [GitHub](https://github.com/steveyegge/beads))
-- Signed releases include checksums for verification
+- Releases include checksums for verification
 - Used by developers worldwide
 - A simple CLI tool for issue tracking
 
@@ -178,9 +180,9 @@ False positives may still occur with new releases until the certificate builds r
 ### Should I disable my antivirus?
 
 **No.** Instead:
-1. Add beads to your antivirus exclusions (safe and recommended)
+1. Verify release checksums before first run
 2. Keep your antivirus enabled for other threats
-3. Verify checksums of downloaded files before adding exclusions
+3. Add beads to your antivirus exclusions only after verification if detections persist
 
 ## Reporting Issues
 

docs/INSTALLING.md

@@ -79,10 +79,17 @@ curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/insta
 
 The installer will:
 - Detect your platform (macOS/Linux/FreeBSD, amd64/arm64)
+- Verify downloaded release archives against release `checksums.txt`
 - Install via `go install` if Go is available
 - Fall back to building from source if needed
 - Guide you through PATH setup if necessary
 
+On macOS, the script preserves the downloaded binary signature by default. If you explicitly want ad-hoc local re-signing, opt in:
+
+```bash
+BEADS_INSTALL_RESIGN_MACOS=1 curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+```
+
 ### Comparison of Installation Methods
 
 | Method | Best For | Updates | Prerequisites | Notes |
@@ -199,7 +206,7 @@ Beads now ships with native Windows support—no MSYS or MinGW required.
 irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
 ```
 
-The script installs a prebuilt Windows release if available. Go is only required for `go install` or building from source.
+The script installs a prebuilt Windows release if available and verifies the downloaded ZIP checksum against release `checksums.txt`. Go is only required for `go install` or building from source.
 
 **Dolt backend on Windows:** Supported via pure-Go regex backend. Windows builds automatically use Go's stdlib `regexp` instead of ICU regex to avoid CGO/header dependencies. If you need full ICU regex semantics, use Linux/macOS (or WSL) with ICU installed.
 

docs/TROUBLESHOOTING.md

@@ -202,11 +202,7 @@ If you installed via Homebrew, this shouldn't be necessary as the formula alread
 
 **Solutions**:
 
-1. **Add bd to antivirus exclusions** (recommended):
-   - Add the bd installation directory to your antivirus exclusion list
-   - This is safe - beads is open source and checksums are provided
-
-2. **Verify file integrity before excluding**:
+1. **Verify file integrity first**:
    ```bash
    # Windows PowerShell
    Get-FileHash bd.exe -Algorithm SHA256
@@ -216,6 +212,10 @@ If you installed via Homebrew, this shouldn't be necessary as the formula alread
    ```
    Compare with checksums from the [GitHub release page](https://github.com/steveyegge/beads/releases)
 
+2. **Add bd to antivirus exclusions only after verification**:
+   - Add the bd installation directory to your antivirus exclusion list
+   - Keep antivirus enabled for everything else
+
 3. **Report the false positive**:
    - Help improve detection by reporting to your antivirus vendor
    - Most vendors have false positive submission forms
@@ -970,6 +970,10 @@ bd init -v
 
 If macOS blocks bd:
 
+1. Verify the downloaded binary checksum matches the release `checksums.txt`.
+2. If you used `scripts/install.sh`, note that macOS ad-hoc re-signing is now **opt-in** (`BEADS_INSTALL_RESIGN_MACOS=1`).
+3. Use one of the approval paths below.
+
 ```bash
 # Remove quarantine attribute
 xattr -d com.apple.quarantine /usr/local/bin/bd

install.ps1

@@ -136,6 +136,43 @@ function Get-WindowsArch {
     }
 }
 
+function Get-ExpectedReleaseChecksum {
+    param(
+        [Parameter(Mandatory)]$Release,
+        [Parameter(Mandatory)][string]$AssetName,
+        [Parameter(Mandatory)][string]$TempRoot
+    )
+
+    $checksumsAsset = $Release.assets | Where-Object { $_.name -eq "checksums.txt" } | Select-Object -First 1
+    if (-not $checksumsAsset) {
+        Write-WarningMsg "Release does not include checksums.txt; refusing unverified install."
+        return $null
+    }
+
+    $checksumsPath = Join-Path $TempRoot "checksums.txt"
+    try {
+        Invoke-WebRequest -Uri $checksumsAsset.browser_download_url -OutFile $checksumsPath
+    } catch {
+        Write-WarningMsg "Failed to download checksums.txt: $_"
+        return $null
+    }
+
+    foreach ($line in Get-Content -Path $checksumsPath) {
+        $trimmed = $line.Trim()
+        if ($trimmed -eq "") {
+            continue
+        }
+
+        $parts = $trimmed -split '\s+'
+        if ($parts.Count -ge 2 -and $parts[1].TrimStart("*") -eq $AssetName) {
+            return $parts[0].ToLowerInvariant()
+        }
+    }
+
+    Write-WarningMsg "No checksum entry found for $AssetName in checksums.txt"
+    return $null
+}
+
 function Install-FromRelease {
     Write-Info "Installing bd from GitHub releases..."
 
@@ -175,6 +212,20 @@ function Install-FromRelease {
         Write-Info "Downloading $assetName..."
         Invoke-WebRequest -Uri $asset.browser_download_url -OutFile $zipPath
 
+        Write-Info "Verifying release checksum..."
+        $expectedChecksum = Get-ExpectedReleaseChecksum -Release $release -AssetName $assetName -TempRoot $tempRoot
+        if (-not $expectedChecksum) {
+            return $false
+        }
+
+        $actualChecksum = (Get-FileHash -Path $zipPath -Algorithm SHA256).Hash.ToLowerInvariant()
+        if ($actualChecksum -ne $expectedChecksum) {
+            Write-WarningMsg "Checksum mismatch for $assetName; refusing to install."
+            return $false
+        }
+
+        Write-Success "Checksum verified for $assetName"
+
         Write-Info "Extracting archive..."
         Microsoft.PowerShell.Archive\Expand-Archive -Path $zipPath -DestinationPath $tempRoot -Force