# Distribution Channels

OpenPass is distributed through multiple channels to support different platforms and workflows.

## Supported Platforms

| OS | Arch | Formats |
|----|------|---------|
| Linux | amd64, arm64 | tar.gz, deb, rpm, apk |
| macOS | amd64, arm64 | tar.gz, Homebrew |
| Windows | amd64, arm64 | zip |
| FreeBSD | amd64, arm64 | tar.gz |
| NixOS / Nix | amd64, arm64 | Nix flake |

**Notes:**
- **FreeBSD**: Prebuilt binaries are built with `CGO_ENABLED=0`, which disables OS keyring integration. Instead, OpenPass uses an in-memory encrypted session cache (AES-256-GCM) with a 15-minute TTL. See [docs/troubleshooting.md](troubleshooting.md#freebsd) for details.

## First-Class Channels

### GitHub Releases (Primary)

Pre-built binaries are published to GitHub Releases on every tagged release.

**Download:** https://github.com/danieljustus/OpenPass/releases/latest

Each release includes:
- `OpenPass_<version>_<os>_<arch>.tar.gz` (Linux/macOS)
- `OpenPass_<version>_windows_<arch>.zip` (Windows)
- `openpass_<version>_<os>_<arch>.deb` (Debian/Ubuntu)
- `openpass_<version>_<os>_<arch>.rpm` (Fedora/RHEL)
- `openpass_<version>_<os>_<arch>.apk` (Alpine)
- `OpenPass_<version>_checksums.txt` (SHA-256 checksums)

### Homebrew (macOS/Linux)

Install from the official tap:

```bash
brew tap danieljustus/tap
brew install openpass
```

Or install in one line:

```bash
brew install danieljustus/tap/openpass
```

The formula is generated by GoReleaser and published to `danieljustus/homebrew-tap`.

### Linux Packages

#### Debian/Ubuntu (.deb)

```bash
# Download the .deb for your arch
curl -LO https://github.com/danieljustus/OpenPass/releases/latest/download/openpass_<version>_linux_<arch>.deb

# Install
sudo dpkg -i openpass_<version>_linux_<arch>.deb
```

#### Fedora/RHEL (.rpm)

```bash
# Download the .rpm for your arch
curl -LO https://github.com/danieljustus/OpenPass/releases/latest/download/openpass_<version>_linux_<arch>.rpm

# Install
sudo rpm -i openpass_<version>_linux_<arch>.rpm
```

#### Alpine (.apk)

```bash
# Download the .apk for your arch
curl -LO https://github.com/danieljustus/OpenPass/releases/latest/download/openpass_<version>_linux_<arch>.apk

# Install
sudo apk add --allow-untrusted openpass_<version>_linux_<arch>.apk
```

### Binary Archives

Download and extract the archive for your platform:

```bash
# Linux/macOS
tar xzf OpenPass_<version>_<os>_<arch>.tar.gz
sudo mv OpenPass_<version>_<os>_<arch>/openpass /usr/local/bin/

# Windows (PowerShell)
Expand-Archive OpenPass_<version>_windows_<arch>.zip
Move-Item OpenPass_<version>_windows_<arch>\openpass.exe C:\Windows\System32\
```

### Nix Flake

OpenPass provides a Nix flake for NixOS and Nix users:

```bash
# Run directly (no install needed)
nix run github:danieljustus/OpenPass

# Or add as a flake input in your flake.nix:
#   inputs.openpass.url = "github:danieljustus/OpenPass";
```

> **Note:** Go module dependencies are pinned via `vendorHash` in `flake.nix`. If updating dependencies, run `go mod vendor && nix hash path --sri vendor/` and update the hash.

### Go Install

```bash
go install github.com/danieljustus/OpenPass@latest
```

### Build from Source

```bash
git clone https://github.com/danieljustus/OpenPass
cd OpenPass
make build
sudo mv openpass /usr/local/bin/
```

## Build Pipeline

All artifacts are built by [GoReleaser](https://goreleaser.com/) via the release workflow (`.github/workflows/release.yml`).

The pipeline:
1. Runs tests and govulncheck
2. Runs lint and security gates (fmt-check, golangci-lint, gosec)
3. Builds cross-platform binaries
4. Creates archives (tar.gz/zip)
5. Creates Linux packages (deb/rpm/apk) via nfpms
6. Generates Homebrew formula
7. Publishes GitHub Release with all artifacts and checksums

## Release Verification

### Checksum File

Every release includes `OpenPass_<version>_checksums.txt` containing SHA-256 hashes of all artifacts.

### Verifying a Download

```bash
# Download the checksum file
curl -LO https://github.com/danieljustus/OpenPass/releases/latest/download/OpenPass_<version>_checksums.txt

# Verify a specific artifact
sha256sum -c OpenPass_<version>_checksums.txt --ignore-missing
```

Or manually:

```bash
# Compute hash of downloaded file
sha256sum OpenPass_<version>_linux_amd64.tar.gz

# Compare against the value in OpenPass_<version>_checksums.txt
```

### Verifying Binary Metadata

OpenPass embeds build metadata in the binary:

```bash
openpass version
# openpass v1.2.3 (commit: abc1234, built: 2025-01-15T10:30:00Z)
```

The `commit` value should match the git tag's commit SHA on GitHub.

## Smoke Test Matrix

The following matrix shows which distribution channels have automated vs. manual smoke tests:

| Platform | Format | Status | Notes |
|----------|--------|--------|-------|
| Linux amd64 | tar.gz | Automated | `smoke-test-linux` job |
| Linux amd64 | deb | Automated | `smoke-test-deb` job |
| Linux amd64 | rpm | Manual | See manual procedure below |
| Linux amd64 | apk | Manual | Alpine package |
| Linux arm64 | All | Manual | Cross-compile target |
| macOS amd64 | tar.gz | Automated | `smoke-test-macos` job |
| macOS arm64 | tar.gz | Manual | Apple Silicon (M1/M2/M3) |
| macOS | Homebrew | Manual | Tap-based install |
| Windows amd64 | zip | Manual | Windows Server test |
| FreeBSD amd64 | tar.gz | Manual | No GA runner available |
| FreeBSD arm64 | tar.gz | Manual | No GA runner available |

### Automated Smoke Tests

Release workflow runs automated smoke tests for the primary targets:
- Linux amd64 archive (`smoke-test-linux`)
- Linux amd64 deb package (`smoke-test-deb`)
- macOS amd64 archive (`smoke-test-macos`)

See `.github/workflows/release.yml` for test implementation.

### Manual Smoke Test Procedure

After installing OpenPass from any channel, verify:

```bash
# 1. Binary is in PATH and executable
openpass version

# 2. Help output is correct
openpass --help | head -5

# 3. Can initialize a test vault
TMPDIR=$(mktemp -d)
OPENPASS_VAULT="$TMPDIR/test-vault" openpass init --non-interactive
rm -rf "$TMPDIR"
```

For package-based installs, also verify:

```bash
# Debian/Ubuntu
dpkg -s openpass | grep Status

# Fedora/RHEL
rpm -q openpass

# Alpine
apk info openpass
```
