magus v0.4.3 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
2 min read

Verify a release

Alongside the binary tarballs, each release ships SHA256SUMS (the manifest) and SHA256SUMS.sig (its Ed25519 signature). All artifacts, plus the signing key, are attached to each GitHub release; /public/ indexes the releases and the machine-readable manifest.

Already running magus? Use the built-in verifier:

magus self update --dry-run

The trust chain runs through your already-trusted binary. Nothing else to do.

First install: verify by hand. Do not verify a fresh magus with itself: a tampered build carries the attacker's key and self-reports success. Use OpenSSL with the key served from this HTTPS page.

  1. Save the key. Either download magus-release.pem, or copy the PEM block below into magus-release.pem.

  2. Verify the manifest signature (requires OpenSSL 3.0+):

    openssl pkeyutl -verify -pubin -inkey magus-release.pem \
  -rawin -in SHA256SUMS -sigfile SHA256SUMS.sig
# Signature Verified Successfully

  3. Only if the signature verifies, check the artifact hash:

    sha256sum --ignore-missing -c SHA256SUMS
# macOS: shasum -a 256 --ignore-missing -c SHA256SUMS

    --ignore-missing skips manifest entries for artifacts you did not download, so the output stays limited to the file you fetched, without piping through grep, which would replace the command's exit status with grep's and let a failed check report success.

Order matters. Checking a hash against an unverified manifest proves nothing. The whole procedure in one picture: each merged cell consumes everything beside it, and the tarball deliberately skips the first step, because nothing signs the tarball directly:

Have OpenSSL 3.0+ with Ed25519 support on PATH
magus-release.pem: the key, from this HTTPS page verify the signature
openssl pkeyutl -verify		 check the hash
sha256sum -c		 a release
you can trust
SHA256SUMS: the manifest, from the release
SHA256SUMS.sig: its signature, from the release
magus-<os>-<arch>.tar.gz: the artifact you downloaded

Release signing key (Ed25519)

-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEA/7uPpvNidN79EoiAk8ajIsJTK8VFAW9JWrSVXey2Z3k=
-----END PUBLIC KEY-----

Raw base64 (32 bytes):

/7uPpvNidN79EoiAk8ajIsJTK8VFAW9JWrSVXey2Z3k=

The key is embedded in every magus binary via //go:embed, so magus self update trusts it transitively. A planned rotation first ships a release signed by the current key that embeds the replacement key; later releases can use the replacement. Older binaries cannot be remotely revoked if the current key is compromised. The maintainer procedure is in the contributing guide.

SetupInstall magus from a signed release, verify it, set up your shell, and keep it current with magus self update. ChangelogEvery change to magus, newest first, in Keep a Changelog format, starting with the unreleased entries. Generated from changes/unreleased/ and releases/*.yaml. Cache modelHow magus computes a content-addressed cache key from a target's declared inputs, replays outputs on a hit without rerunning the body, and stores it all as plain files under .magus. Knowledge graphThe knowledge graph is a deterministic, cache-backed graph of the magus domain (projects, targets, spells, ops, charms, modules, diagnostics, docs, and buzz sources) that agents and humans query instead of grepping. This page covers the schema, the verbs, the file layout, and how to point external graph tools at an export.
verifysignatureed25519sha256opensslreleasesecurity
Last updated (895d94e4)
Earlier changes on this page (2)

Full history ↗ · Blame source ↗

Glossary

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). See operations.

Manifest

The file that declares what a package is: its name, dependencies, entry points and tool config (go.mod, package.json, pyproject.toml, Cargo.toml). How the workspace builds, tests and lints the package belongs in the magusfile, not in the manifest's scripts. See spells.

Ward

A coded diagnostic that inspects a resolved op and nudges or blocks an anti-pattern before it runs. See wards.

Span

OpenTelemetry's name for one unit of work under a trace: a target execution, whose sub-operations are child spans. An output reference points at a span's captured output. See telemetry.

Run

One target executing under one magus invocation, such as magus run test web or magus affected ci. A run keeps its captured output behind an output reference. Every magus run is a run whether or not any job asked for it; see Job for how the two relate.

Lease

The grant a holder takes on a job: the write and read paths that job declared, enforced in the checkout that took it with magus job exec. A job is the piece of work; a lease is permission over it.

Conventions

Placeholders

Angle brackets mark a value you replace with your own; never type the brackets:

magus run <target>
magus completion <shell>    # e.g. bash, zsh, fish

<target>, <path>, <shell>, <name> and the like are stand-ins, not literal text.