build: reproducible build and signed release digest

Closes #2.

Author: m0wer

.github/workflows/release.yaml

@@ -96,6 +96,10 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Get reproducible build timestamp
+        id: source_date
+        run: echo "epoch=$(git log -1 --pretty=%ct)" >> $GITHUB_OUTPUT
+
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
@@ -112,22 +116,23 @@ jobs:
           GOOS: ${{ matrix.goos }}
           GOARCH: ${{ matrix.goarch }}
           CGO_ENABLED: 0
+          SOURCE_DATE_EPOCH: ${{ steps.source_date.outputs.epoch }}
         run: |
           VERSION=${{ needs.create-release.outputs.version }}
-          BUILD_TIME=$(date -u '+%Y-%m-%d_%H:%M:%S')
-          COMMIT_HASH=$(git rev-parse --short HEAD)
 
           go build \
-            -ldflags="-s -w -X main.version=${VERSION} -X main.buildTime=${BUILD_TIME} -X main.commit=${COMMIT_HASH}" \
+            -trimpath \
+            -buildvcs=false \
+            -ldflags="-buildid= -s -w -X main.version=${VERSION}" \
             -o ${{ matrix.output }} \
             ./cmd/neutrinod
 
-      - name: Upload Release Asset
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          gh release upload ${{ needs.create-release.outputs.version }} \
-            "neutrino_server/${{ matrix.output }}"
+      - name: Upload binary artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: binary-${{ matrix.output }}
+          path: neutrino_server/${{ matrix.output }}
+          if-no-files-found: error
 
   build-docker:
     needs: create-release
@@ -189,26 +194,42 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Download release assets
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          mkdir -p artifacts
-          cd artifacts
-          gh release download ${{ needs.create-release.outputs.version }} \
-            --repo ${{ github.repository }} \
-            --pattern 'neutrinod-*'
+      - name: Download built binaries
+        uses: actions/download-artifact@v4
+        with:
+          pattern: binary-*
+          path: artifacts
+          merge-multiple: true
 
       - name: Generate checksums
         run: |
           cd artifacts
-          sha256sum * > SHA256SUMS
+          sha256sum neutrinod-* | sort > SHA256SUMS
           cat SHA256SUMS
 
-      - name: Upload checksums
+      - name: Verify signed checksums from repository
+        run: |
+          VERSION=${{ needs.create-release.outputs.version }}
+          EXPECTED_DIR="signatures/${VERSION}"
+
+          test -f "${EXPECTED_DIR}/SHA256SUMS"
+          test -f "${EXPECTED_DIR}/SHA256SUMS.asc"
+
+          diff -u "${EXPECTED_DIR}/SHA256SUMS" "artifacts/SHA256SUMS"
+
+          for pubkey in signatures/pubkeys/*.asc; do
+            gpg --import "$pubkey"
+          done
+
+          gpg --verify "${EXPECTED_DIR}/SHA256SUMS.asc" "artifacts/SHA256SUMS"
+
+      - name: Upload binaries, checksums, and signature
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
+          VERSION=${{ needs.create-release.outputs.version }}
           gh release upload ${{ needs.create-release.outputs.version }} \
+            ./artifacts/neutrinod-* \
             ./artifacts/SHA256SUMS \
+            "./signatures/${VERSION}/SHA256SUMS.asc" \
             --repo ${{ github.repository }}

CHANGELOG.md

@@ -9,8 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add reproducible release flow for `neutrinod` binaries with deterministic Go build flags and `SOURCE_DATE_EPOCH`.
+- Add `scripts/release-build-sign.sh` to build release binaries locally, generate `SHA256SUMS`, and create a detached GPG signature.
+- Add `scripts/verify-release-build.sh` as a one-command local reproducibility check against the signed digest.
+- Add release signature infrastructure under `signatures/` with trusted key list and m0wer public key.
 - Add `addPeers` setting, similar to `connectPeers`, that allows specifying peers to connect to without disabling peer discovery.
 
+### Changed
+
+- Update release workflow to rebuild binaries in CI, verify checksums against committed `signatures/<version>/SHA256SUMS`, verify `SHA256SUMS.asc`, and upload binaries plus signed digest files to GitHub releases.
+
 ## [0.7.0] - 2026-03-11
 
 ### Added

README.md

@@ -61,6 +61,27 @@ go build -o neutrinod ./cmd/neutrinod
 ./neutrinod --network=mainnet --listen=0.0.0.0:8334
 ```
 
+## Reproducible Releases
+
+Release binaries are reproducible and tied to a signed digest:
+
+1. Build locally and sign checksums:
+
+```bash
+./scripts/release-build-sign.sh v1.0.0 --key 1C53A412D11EF3051704419C44912E1E03005B31
+```
+
+2. Commit `signatures/v1.0.0/SHA256SUMS` and `signatures/v1.0.0/SHA256SUMS.asc`.
+3. Push the release tag (`v1.0.0`).
+
+The release workflow rebuilds all binaries, verifies the resulting `SHA256SUMS` exactly matches the committed digest, verifies the GPG signature using keys in `signatures/pubkeys/`, and uploads binaries + `SHA256SUMS` + `SHA256SUMS.asc` to the GitHub release.
+
+Anyone can reproduce and verify a release locally with one command:
+
+```bash
+./scripts/verify-release-build.sh v1.0.0
+```
+
 ## Configuration
 
 ### Environment Variables

RELEASE.md

@@ -22,7 +22,19 @@ git commit -m "Prepare release v1.0.0"
 git push origin main
 ```
 
-### 2. Create and Push Tag
+### 2. Build Reproducible Binaries and Sign Digest
+
+```bash
+# Build deterministic binaries and sign checksum file
+./scripts/release-build-sign.sh v1.0.0 --key 1C53A412D11EF3051704419C44912E1E03005B31
+
+# Commit signed digest artifacts
+git add signatures/v1.0.0/
+git commit -m "Add signed checksums for v1.0.0"
+git push origin main
+```
+
+### 3. Create and Push Tag
 
 ```bash
 # Create annotated tag
@@ -40,7 +52,7 @@ Changes:
 git push origin v1.0.0
 ```
 
-### 3. Monitor Release
+### 4. Monitor Release
 
 The GitHub Actions workflow will automatically:
 
@@ -54,8 +66,9 @@ The GitHub Actions workflow will automatically:
    - linux/arm64
 
 3. **Create GitHub Release** with:
-   - All binary archives
+   - All binaries
    - SHA256SUMS file
+   - SHA256SUMS.asc signature
    - Release notes
 
 4. **Push Docker Images** to:
@@ -66,23 +79,33 @@ The GitHub Actions workflow will automatically:
 
 Monitor at: `https://github.com/yourusername/neutrino-api/actions`
 
-### 4. Verify Release
+### 5. Verify Release
 
 ```bash
 # Check GitHub release page
 open https://github.com/yourusername/neutrino-api/releases
 
 # Test binary download
-wget https://github.com/yourusername/neutrino-api/releases/download/v1.0.0/neutrinod-linux-amd64.tar.gz
-tar -xzf neutrinod-linux-amd64.tar.gz
+wget https://github.com/yourusername/neutrino-api/releases/download/v1.0.0/neutrinod-linux-amd64
+chmod +x neutrinod-linux-amd64
 ./neutrinod-linux-amd64 --version
 
+# Verify signed checksums
+wget https://github.com/yourusername/neutrino-api/releases/download/v1.0.0/SHA256SUMS
+wget https://github.com/yourusername/neutrino-api/releases/download/v1.0.0/SHA256SUMS.asc
+gpg --import signatures/pubkeys/1C53A412D11EF3051704419C44912E1E03005B31.asc
+gpg --verify SHA256SUMS.asc SHA256SUMS
+sha256sum -c SHA256SUMS
+
+# Reproduce all binaries locally and compare to the signed digest
+./scripts/verify-release-build.sh v1.0.0
+
 # Test Docker image
 docker pull ghcr.io/yourusername/neutrino-api:v1.0.0
 docker run --rm ghcr.io/yourusername/neutrino-api:v1.0.0 neutrinod --version
 ```
 
-### 5. Announce Release
+### 6. Announce Release
 
 - Update project README if needed
 - Post in relevant communities

VERSIONING.md

@@ -51,7 +51,18 @@ var (
 )
 ```
 
-### 2. Create a Tag
+### 2. Build and Sign Release Digest
+
+Before tagging, build artifacts locally and sign the checksum file:
+
+```bash
+./scripts/release-build-sign.sh v1.0.0 --key 1C53A412D11EF3051704419C44912E1E03005B31
+git add signatures/v1.0.0/
+git commit -m "Add signed checksums for v1.0.0"
+git push origin main
+```
+
+### 3. Create a Tag
 
 Tags should follow the format `v<MAJOR>.<MINOR>.<PATCH>`:
 
@@ -60,14 +71,21 @@ git tag -a v1.0.0 -m "Release v1.0.0 based on Neutrino v0.16.0"
 git push origin v1.0.0
 ```
 
-### 3. Automated Release
+### 4. Automated Release
 
 The GitHub Actions workflow (`.github/workflows/release.yaml`) will:
 
 1. Build binaries for multiple platforms (Linux, macOS, Windows on amd64/arm64)
 2. Create Docker images for multiple architectures
-3. Generate SHA256 checksums
-4. Create a GitHub release with all artifacts
+3. Regenerate SHA256 checksums and verify they exactly match `signatures/<version>/SHA256SUMS`
+4. Verify `signatures/<version>/SHA256SUMS.asc` with keys in `signatures/pubkeys/`
+5. Create a GitHub release with all artifacts, including `SHA256SUMS` and `SHA256SUMS.asc`
+
+Users can reproduce and verify locally with:
+
+```bash
+./scripts/verify-release-build.sh v1.0.0
+```
 
 ## Tracking Upstream Changes
 

scripts/release-build-sign.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+
+usage() {
+    cat <<EOF
+Usage: $(basename "$0") <version> [--key <fingerprint-or-email>]
+
+Build release binaries reproducibly, generate SHA256SUMS, and sign the digest.
+
+Examples:
+  $(basename "$0") v0.8.0
+  $(basename "$0") v0.8.0 --key 1C53A412D11EF3051704419C44912E1E03005B31
+EOF
+}
+
+if [[ $# -lt 1 ]]; then
+    usage
+    exit 1
+fi
+
+VERSION="$1"
+shift
+
+GPG_KEY=""
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --key)
+            GPG_KEY="$2"
+            shift 2
+            ;;
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Unknown argument: $1" >&2
+            usage
+            exit 1
+            ;;
+    esac
+done
+
+for cmd in git go gpg sha256sum; do
+    if ! command -v "$cmd" >/dev/null 2>&1; then
+        echo "Missing required command: $cmd" >&2
+        exit 1
+    fi
+done
+
+SOURCE_DATE_EPOCH="$(git -C "$REPO_ROOT" log -1 --pretty=%ct)"
+BUILD_DIR="$REPO_ROOT/tmp/release-build/$VERSION"
+SIGNED_DIR="$REPO_ROOT/signatures/$VERSION"
+
+rm -rf "$BUILD_DIR"
+mkdir -p "$BUILD_DIR"
+mkdir -p "$SIGNED_DIR"
+
+declare -a TARGETS=(
+    "linux amd64 neutrinod-linux-amd64"
+    "linux arm64 neutrinod-linux-arm64"
+    "darwin amd64 neutrinod-darwin-amd64"
+    "darwin arm64 neutrinod-darwin-arm64"
+    "windows amd64 neutrinod-windows-amd64.exe"
+)
+
+for target in "${TARGETS[@]}"; do
+    read -r GOOS GOARCH OUTPUT <<<"$target"
+    echo "Building $OUTPUT"
+
+    (
+        cd "$REPO_ROOT/neutrino_server"
+        GOOS="$GOOS" \
+        GOARCH="$GOARCH" \
+        CGO_ENABLED=0 \
+        SOURCE_DATE_EPOCH="$SOURCE_DATE_EPOCH" \
+        go build \
+            -trimpath \
+            -buildvcs=false \
+            -ldflags="-buildid= -s -w -X main.version=${VERSION}" \
+            -o "$BUILD_DIR/$OUTPUT" \
+            ./cmd/neutrinod
+    )
+done
+
+(
+    cd "$BUILD_DIR"
+    sha256sum neutrinod-* | sort > SHA256SUMS
+)
+
+cp "$BUILD_DIR/SHA256SUMS" "$SIGNED_DIR/SHA256SUMS"
+
+SIGN_ARGS=(--armor --detach-sign)
+if [[ -n "$GPG_KEY" ]]; then
+    SIGN_ARGS+=(--local-user "$GPG_KEY")
+fi
+
+gpg "${SIGN_ARGS[@]}" \
+    --output "$SIGNED_DIR/SHA256SUMS.asc" \
+    "$SIGNED_DIR/SHA256SUMS"
+
+gpg --verify "$SIGNED_DIR/SHA256SUMS.asc" "$SIGNED_DIR/SHA256SUMS"
+
+echo
+echo "Release digest and signature created:"
+echo "  $SIGNED_DIR/SHA256SUMS"
+echo "  $SIGNED_DIR/SHA256SUMS.asc"
+echo
+echo "Temporary build outputs: $BUILD_DIR"