binary

package
v0.0.0-...-311dae5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 25, 2025 License: MIT-0 Imports: 24 Imported by: 0

Documentation

Overview

Package binary provides functionality for downloading, verifying, and managing the mise and chezmoi binaries that ZERB wraps.

Security Model

Binary management is a critical security component of ZERB. All binaries are:

  • Downloaded only from official GitHub releases
  • Verified using GPG signatures (preferred) or SHA256 checksums (fallback)
  • Never installed without successful verification

Verification Strategy

1. GPG Signature Verification (Preferred)

  • Downloads .sig or .asc signature file
  • Verifies using embedded GPG public keys
  • Provides both authenticity and integrity verification

2. SHA256 Checksum Verification (Fallback)

  • Downloads checksum file from GitHub release
  • Verifies file integrity only (not authenticity)
  • Used when GPG verification unavailable or fails

Usage 

// Create a manager
mgr, err := binary.NewManager("/home/user/.config/zerb", platformInfo)
if err != nil {
    return err
}

// Extract embedded GPG keyrings
if err := mgr.ExtractKeyrings(); err != nil {
    return err
}

// Download and install mise
err = mgr.Install(ctx, binary.DownloadOptions{
    Binary:  binary.BinaryMise,
    Version: binary.DefaultVersions.Mise,
})

Architecture

The package is organized into several components:

  • Manager: High-level orchestration of download, verify, install
  • Downloader: HTTP download with retry logic and caching
  • Verifier: GPG and SHA256 verification
  • Extractor: Archive extraction (tar.gz)
  • Platform: Platform-specific URL construction

Index

Constants

View Source 
const (
	// DefaultTimeout is the default HTTP request timeout
	DefaultTimeout = 5 * time.Minute
	// DefaultRetries is the default number of download retries
	DefaultRetries = 3
	// DefaultUserAgent is the User-Agent header sent with requests
	DefaultUserAgent = "ZERB/1.0"
)

Variables

View Source 
var DefaultVersions = Version{
	Mise:    "2024.12.7",
	Chezmoi: "2.46.1",
}

DefaultVersions contains the hard-coded binary versions used by ZERB These versions are tested and verified to work together

Functions

func SetExecutable 

func SetExecutable(path string) error

SetExecutable sets executable permissions on a file

Types

type Binary 

type Binary string

Binary represents a tool binary managed by ZERB 

const (
	// BinaryMise represents the mise binary
	BinaryMise Binary = "mise"
	// BinaryChezmoi represents the chezmoi binary
	BinaryChezmoi Binary = "chezmoi"
)

func (Binary) String 

func (b Binary) String() string

String returns the string representation of the binary

type Config 

type Config struct {
	// ZerbDir is the root ZERB directory (default: ~/.config/zerb)
	ZerbDir string
	// PlatformInfo contains OS and architecture information
	PlatformInfo *platform.Info
}

Config holds configuration for the binary manager

type DownloadInfo 

type DownloadInfo struct {
	Binary         Binary
	Version        string
	OS             string // "linux", "darwin", etc.
	Arch           string // "amd64", "arm64", etc.
	URL            string // Constructed download URL
	SignatureURL   string // GPG signature URL (may be empty)
	ChecksumURL    string // SHA256 checksum URL (may be empty)
	BundleURL      string // Cosign bundle URL (may be empty)
	BinaryFilename string // Binary filename for checksum lookup (e.g., "mise-v2024.12.7-linux-x64.tar.gz")
}

DownloadInfo contains metadata needed to download a binary

type DownloadOptions 

type DownloadOptions struct {
	Binary  Binary
	Version string
	// SkipGPG skips GPG verification (for testing only)
	SkipGPG bool
	// UseMockDownload uses mock HTTP server (for testing only)
	UseMockDownload bool
}

DownloadOptions configures binary download and installation

type DownloadResult 

type DownloadResult struct {
	Binary       Binary
	Version      string
	Path         string
	Verified     VerificationMethod
	DownloadTime time.Duration
}

DownloadResult contains information about a completed download

type Downloader 

type Downloader struct {
	// contains filtered or unexported fields
}

Downloader handles HTTP downloads with retry logic

func NewDownloader 

func NewDownloader(cacheDir string) *Downloader

NewDownloader creates a new downloader

func (*Downloader) DownloadBinary 

func (d *Downloader) DownloadBinary(ctx context.Context, info *DownloadInfo) (string, error)

DownloadBinary downloads a binary archive to the cache directory

func (*Downloader) DownloadBundle 

func (d *Downloader) DownloadBundle(ctx context.Context, info *DownloadInfo) (string, error)

DownloadBundle downloads a cosign bundle file

func (*Downloader) DownloadChecksums 

func (d *Downloader) DownloadChecksums(ctx context.Context, info *DownloadInfo) (string, error)

DownloadChecksums downloads a checksum file

func (*Downloader) DownloadSignature 

func (d *Downloader) DownloadSignature(ctx context.Context, info *DownloadInfo) (string, error)

DownloadSignature downloads a GPG signature file

func (*Downloader) DownloadToFile 

func (d *Downloader) DownloadToFile(ctx context.Context, url, destPath string) error

DownloadToFile downloads a URL to a specific file path

type Extractor 

type Extractor struct{}

Extractor handles archive extraction

func NewExtractor 

func NewExtractor() *Extractor

NewExtractor creates a new extractor

func (*Extractor) ExtractBinary 

func (e *Extractor) ExtractBinary(archivePath, destPath, binaryName string) error

ExtractBinary extracts a specific binary file from a tar.gz archive This is optimized for extracting just the binary we need

func (*Extractor) ExtractTarGz 

func (e *Extractor) ExtractTarGz(archivePath, destDir string) error

ExtractTarGz extracts a .tar.gz archive to a destination directory

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager orchestrates binary download, verification, and installation

func NewManager 

func NewManager(config Config) (*Manager, error)

NewManager creates a new binary manager

func (*Manager) Download 

func (m *Manager) Download(ctx context.Context, opts DownloadOptions) (*DownloadResult, error)

Download downloads and verifies a binary (but doesn't install it)

func (*Manager) EnsureKeyrings 

func (m *Manager) EnsureKeyrings() error

EnsureKeyrings extracts embedded GPG keyrings to disk This is idempotent - safe to call multiple times

func (*Manager) GetBinaryPath 

func (m *Manager) GetBinaryPath(binary Binary) string

GetBinaryPath returns the filesystem path to an installed binary

func (*Manager) GetInstalledVersion 

func (m *Manager) GetInstalledVersion(binary Binary) (string, error)

GetInstalledVersion returns the version of an installed binary For now, this returns the hard-coded version since we know what we installed

func (*Manager) Install 

func (m *Manager) Install(ctx context.Context, opts DownloadOptions) error

Install downloads, verifies, extracts, and installs a binary

func (*Manager) InstallAll 

func (m *Manager) InstallAll(ctx context.Context) error

InstallAll installs both mise and chezmoi binaries

func (*Manager) IsInstalled 

func (m *Manager) IsInstalled(binary Binary) (bool, error)

IsInstalled checks if a binary is already installed and executable

type VerificationMethod 

type VerificationMethod int

VerificationMethod indicates how a binary was verified 

const (
	// VerificationNone indicates no verification (should never happen in production)
	VerificationNone VerificationMethod = iota
	// VerificationGPG indicates GPG signature verification was used
	VerificationGPG
	// VerificationSHA256 indicates SHA256 checksum verification was used
	VerificationSHA256
	// VerificationCosign indicates cosign (Sigstore) verification was used
	VerificationCosign
)

func (VerificationMethod) String 

func (v VerificationMethod) String() string

String returns the string representation of the verification method

type VerificationResult 

type VerificationResult struct {
	Method  VerificationMethod
	Success bool
	Error   error
}

VerificationResult contains the outcome of a verification attempt

type Verifier 

type Verifier struct {
	// contains filtered or unexported fields
}

Verifier handles cryptographic verification of binaries

func NewVerifier 

func NewVerifier(keyringDir string) *Verifier

NewVerifier creates a new verifier

func (*Verifier) VerifyFile 

func (v *Verifier) VerifyFile(binaryPath, signaturePath, checksumPath, bundlePath string, info *DownloadInfo) (*VerificationResult, error)

VerifyFile verifies a downloaded binary file It uses the appropriate verification method based on the binary type: - mise: REQUIRES GPG verification (no fallback) - chezmoi: Uses cosign verification if bundlePath provided, falls back to SHA256

type Version 

type Version struct {
	Mise    string
	Chezmoi string
}

Version specifies hard-coded versions for mise and chezmoi

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.