# Contract: Vendor Installer Verification

Version: 1.0

## Purpose

Rules for downloading and verifying proprietary vendor installers (`.run`, `.exe`, `.tar.gz`)
where the vendor publishes a checksum alongside the binary.
Applies to: NVIDIA drivers, vendor CLI tools, firmware packages.

---

## Download Order

Always download the checksum file **before** the installer:

```sh
BASE_URL="https://vendor.example.com/downloads/${VERSION}"
BIN_FILE="/var/cache/vendor-${VERSION}.run"
SHA_FILE="/var/cache/vendor-${VERSION}.run.sha256sum"

# 1. Download checksum first
wget -q -O "$SHA_FILE" "${BASE_URL}/vendor-${VERSION}.run.sha256sum"

# 2. Download installer
wget --show-progress -O "$BIN_FILE" "${BASE_URL}/vendor-${VERSION}.run"

# 3. Verify
cd /var/cache
sha256sum -c "$SHA_FILE" || { echo "ERROR: sha256 mismatch"; rm -f "$BIN_FILE"; exit 1; }
```

Reason: if the download is interrupted, you have the expected checksum to verify against on retry.

---

## Cache with Verification

Never assume a cached file is valid — a previous download may have been interrupted (0-byte file):

```sh
verify_cached() {
    [ -s "$SHA_FILE" ] || return 1   # sha256 file missing or empty
    [ -s "$BIN_FILE" ] || return 1   # binary missing or empty
    cd "$(dirname "$BIN_FILE")"
    sha256sum -c "$SHA_FILE" --status 2>/dev/null
}

if ! verify_cached; then
    rm -f "$BIN_FILE" "$SHA_FILE"
    # ... download and verify
else
    echo "verified from cache"
fi
```

**Never check only for file existence.** Check that the file is non-empty (`-s`) AND passes checksum.

---

## Version Validation

Before writing build scripts, verify the version URL actually exists:

```sh
curl -sIL "https://vendor.example.com/downloads/${VERSION}/installer.run" \
    | grep -i 'http/\|content-length'
```

A `404` or `content-length: 0` means the version does not exist on that CDN.
Vendor version numbering may have gaps (e.g. NVIDIA skips minor versions on some CDNs).

---

## Rules

- Download checksum before installer — never after.
- Verify checksum before extracting or executing.
- On mismatch: delete the file, exit with error. Never proceed with a bad installer.
- Cache by `version` + any secondary key (e.g. kernel version for compiled modules).
- Never commit installer files to git — always download at build time.
- Log the expected hash when downloading so failures are diagnosable.