update

Documentation

Index

• Constants
• func CheckLatestVersion() (string, error)
• func DownloadAndReplace(version string) (string, error)
• func DownloadAndReplaceMain(ctx context.Context, opts PrereleaseOptions) (string, string, error)
• func DownloadAndReplaceMainVersion(ctx context.Context, version string, opts PrereleaseOptions) (string, string, error)
• func DownloadAndReplacePR(ctx context.Context, prNumber int, opts PrereleaseOptions) (string, string, error)
• func DownloadAndReplacePRVersion(ctx context.Context, version string, opts PrereleaseOptions) (string, string, error)
• func DownloadAndReplaceWithOptions(version string, opts UpdateOptions) (string, error)
• func IsMainVersion(version string) bool
• func IsNewer(current, latest string) bool
• func IsPrereleaseVersion(version string) bool
• func PackageManagerInstall() (manager, path string)
• func ParseMainVersion(version string) (shortSHA string, err error)
• func ParsePrereleaseVersion(version string) (prNumber int, shortSHA string, err error)
• type PrereleaseOptions
• type SignatureVerifier
  • func DefaultSignatureVerifier() (*SignatureVerifier, error)
  • func SignatureVerifierForMain() (*SignatureVerifier, error)
  • func SignatureVerifierForPullRequest(prNumber int) (*SignatureVerifier, error)
  • func SignatureVerifierForVersion(version string) (*SignatureVerifier, error)
  • func (v *SignatureVerifier) Verify(checksumsBytes []byte, sigBase64, leafPEM []byte) error
• type UpdateOptions

Constants

const PackageManagerHomebrew = "homebrew"

PackageManagerHomebrew is the manager string returned by PackageManagerInstall when the running binary lives inside a Homebrew Cellar.

const PackageManagerHomebrewCask = "homebrew-cask"

PackageManagerHomebrewCask is the manager string returned by PackageManagerInstall when the running binary lives inside a Homebrew Caskroom staging directory.

const (

	// UnsignedReleaseEnv lets callers opt into SHA-only verification for
	// releases that predate the cosign signing pipeline. When we're
	// confident every supported release is signed, flip the default and
	// this variable becomes a no-op.
	UnsignedReleaseEnv = "LEO_ALLOW_UNSIGNED_RELEASE"
)

Functions

func CheckLatestVersion

func CheckLatestVersion() (string, error)

CheckLatestVersion returns the latest release tag from GitHub (e.g. "v0.5.2").

func DownloadAndReplace

func DownloadAndReplace(version string) (string, error)

DownloadAndReplace is the strict-verification entrypoint. Signature verification is mandatory; pass DownloadAndReplaceWithOptions to relax.

func DownloadAndReplaceMain

func DownloadAndReplaceMain(ctx context.Context, opts PrereleaseOptions) (string, string, error)

DownloadAndReplaceMain fetches the most-recent successful main-branch build from the unstable workflow, verifies its checksum + cosign signature, and atomically replaces the running binary. Returns the path that was replaced and the version string (e.g. "main-a1b2c3d").

func DownloadAndReplaceMainVersion

func DownloadAndReplaceMainVersion(ctx context.Context, version string, opts PrereleaseOptions) (string, string, error)

DownloadAndReplaceMainVersion installs a specific main-<sha> build.

func DownloadAndReplacePR

func DownloadAndReplacePR(ctx context.Context, prNumber int, opts PrereleaseOptions) (string, string, error)

DownloadAndReplacePR fetches the most-recent successful prerelease build for the given PR, verifies its checksum + cosign signature, and atomically replaces the running binary. Returns the path that was replaced and the version string (e.g. "pr-42-a1b2c3d") so the caller can report it.

func DownloadAndReplacePRVersion

func DownloadAndReplacePRVersion(ctx context.Context, version string, opts PrereleaseOptions) (string, string, error)

DownloadAndReplacePRVersion resolves a pinned `pr-<n>-<sha>` version to the workflow run that produced it, then runs the same verify+install flow as DownloadAndReplacePR. Used by `leo update --version pr-…`.

func DownloadAndReplaceWithOptions

func DownloadAndReplaceWithOptions(version string, opts UpdateOptions) (string, error)

DownloadAndReplaceWithOptions downloads the release archive for the current platform, verifies its cosign signature, verifies its SHA-256 against the release's checksums.txt, extracts the binary, and atomically replaces the running binary. Returns the path that was replaced. Any signature mismatch, checksum mismatch, missing checksums file, or missing entry aborts the update before the binary is replaced.

If opts.AllowUnsigned is set, a missing signature file degrades to SHA-only verification with a warning — but a present-and-invalid signature still aborts.

func IsMainVersion

func IsMainVersion(version string) bool

IsMainVersion reports whether a version string targets a main build.

func IsNewer

func IsNewer(current, latest string) bool

IsNewer returns true if latest is a newer version than current. Handles "dev" as always older. Both versions may have a "v" prefix.

func IsPrereleaseVersion

func IsPrereleaseVersion(version string) bool

IsPrereleaseVersion reports whether a version string targets a PR build rather than a tagged release.

func PackageManagerInstall

func PackageManagerInstall() (manager, path string)

PackageManagerInstall reports whether the running binary was installed by a system package manager that owns its lifecycle. It returns the manager name (e.g. PackageManagerHomebrew) and the resolved binary path, or ("", "") if no package manager is detected.

func ParseMainVersion

func ParseMainVersion(version string) (shortSHA string, err error)

ParseMainVersion extracts the short SHA from a "main-<sha>" version string. Returns an error if the shape doesn't match.

func ParsePrereleaseVersion

func ParsePrereleaseVersion(version string) (prNumber int, shortSHA string, err error)

ParsePrereleaseVersion extracts the PR number and short SHA from a "pr-<n>-<sha>" version string. Returns an error if the shape doesn't match.

Types

type PrereleaseOptions

type PrereleaseOptions struct {
	// Token overrides token resolution; if empty, prereleaseTokenSource
	// is consulted (gh CLI → env vars).
	Token string
	// AllowUnsigned mirrors UpdateOptions.AllowUnsigned: when set, a
	// missing sig/cert pair degrades to SHA-only with a warning instead
	// of aborting. A present-but-invalid signature still aborts.
	AllowUnsigned bool
	// Warn receives advisory messages (auth source, fallbacks). Nil is
	// a no-op.
	Warn func(format string, args ...any)
}

PrereleaseOptions controls the prerelease update flow. The zero value is the strict mode used in production.

type SignatureVerifier

type SignatureVerifier struct {
	// Roots contains the Fulcio root CA(s) used as trust anchors.
	Roots *x509.CertPool
	// Intermediates contains intermediate CA(s) that may chain Fulcio
	// leaf certs to the root. Optional.
	Intermediates *x509.CertPool
	// SANRegex matches the leaf certificate's SAN URI. For GitHub Actions
	// OIDC, this looks like
	//   https://github.com/<owner>/<repo>/.github/workflows/<file>@refs/tags/<tag>
	SANRegex *regexp.Regexp
	// ExpectedIssuer is the OIDC issuer that must appear in the leaf's
	// Fulcio extensions. For GitHub Actions that's
	//   https://token.actions.githubusercontent.com
	ExpectedIssuer string
	// Now returns "verification time" — useful to swap in tests where the
	// fixture certs are long-expired. Defaults to time.Now.
	Now func() time.Time
}

SignatureVerifier checks that checksumsBytes was signed by a Fulcio-issued identity whose SAN URI matches sanRegex and whose OIDC issuer matches expectedIssuer. It is intentionally narrow: it doesn't touch Rekor, doesn't load TUF state, and doesn't need network access. Callers embed the trusted Fulcio roots at build time (see the fulcio subpackage).

func DefaultSignatureVerifier

func DefaultSignatureVerifier() (*SignatureVerifier, error)

DefaultSignatureVerifier builds a verifier trusting the embedded Sigstore public-good Fulcio roots, with SAN regex and issuer tuned for Leo's own GitHub Actions release workflow. It accepts ANY tag matching our tag shape. Callers that know the target version should prefer SignatureVerifierForVersion, which pins the SAN to that exact tag and closes a version-downgrade attack where an attacker serves an old (vulnerable) release's valid signature+cert under a newer release URL.

func SignatureVerifierForMain

func SignatureVerifierForMain() (*SignatureVerifier, error)

SignatureVerifierForMain builds a verifier pinned to the unstable workflow's OIDC identity for main-branch builds. Those signatures are issued by `unstable.yml@refs/heads/main`; pinning the ref to the exact `main` branch (not an arbitrary head) closes the same downgrade window SignatureVerifierForVersion closes for tagged releases.

func SignatureVerifierForPullRequest

func SignatureVerifierForPullRequest(prNumber int) (*SignatureVerifier, error)

SignatureVerifierForPullRequest builds a verifier pinned to the prerelease workflow's OIDC identity for a specific PR. PR build signatures are issued by `prerelease.yml@refs/pull/<n>/merge`; this closes the downgrade window the same way SignatureVerifierForVersion does for tagged releases — a signature minted for a different PR (or for the release workflow) won't satisfy this verifier.

func SignatureVerifierForVersion

func SignatureVerifierForVersion(version string) (*SignatureVerifier, error)

SignatureVerifierForVersion builds a verifier that pins the SAN regex to the exact tag passed in (e.g. "v0.5.0"). The tag is baked into the Fulcio leaf certificate at signing time by GitHub Actions OIDC, so a verifier that demands the caller-supplied version rejects any signature issued for a different release — including stale signatures served via CDN cache/MITM/malicious mirror that would otherwise pass all other checks (chain + issuer + signature) and silently downgrade the user.

func (*SignatureVerifier) Verify

func (v *SignatureVerifier) Verify(checksumsBytes []byte, sigBase64, leafPEM []byte) error

Verify checks that sigBase64 is a valid signature by leafPEM over checksumsBytes, and that leafPEM's identity matches the verifier's policy. Any failure aborts the update — the caller must not proceed to extract or install anything.

type UpdateOptions

type UpdateOptions struct {
	// AllowUnsigned downgrades signature verification to SHA-only with a
	// warning. Used during the rollout window where not every release has
	// a .sig + .pem pair yet. Wire this to a CLI flag or the
	// LEO_ALLOW_UNSIGNED_RELEASE env var.
	AllowUnsigned bool
	// Warn is called when AllowUnsigned causes a fallback. Defaults to a
	// no-op — the caller CLI supplies a real stderr writer.
	Warn func(format string, args ...any)
}

UpdateOptions controls optional knobs on DownloadAndReplace. Zero value means "strict": fetch+verify signature, abort if missing.