From 90c7f73d658bf07c51761d644ed626d8d634840b Mon Sep 17 00:00:00 2001 From: beardedeagle Date: Tue, 10 Nov 2026 12:02:20 -0600 Subject: [PATCH 1/3] ci: publish signed and attested binary releases --- .github/CONTRIBUTING.md | 11 + .github/release/install-minisign.sh | 17 ++ .github/release/publish.sh | 32 +++ .github/release/release.py | 273 ++++++++++++++++++++++++ .github/release/sign.sh | 19 ++ .github/release/test_release.py | 310 ++++++++++++++++++++++++++++ .github/workflows/release.yml | 191 +++++++++++++++++ CHANGELOG.md | 5 + Justfile | 24 +++ README.md | 4 + docs/src/SUMMARY.md | 1 + docs/src/development/releases.md | 138 +++++++++++++ 12 files changed, 1025 insertions(+) create mode 100644 .github/release/install-minisign.sh create mode 100644 .github/release/publish.sh create mode 100644 .github/release/release.py create mode 100644 .github/release/sign.sh create mode 100644 .github/release/test_release.py create mode 100644 .github/workflows/release.yml create mode 100644 docs/src/development/releases.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index e13e85c..675de7b 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -59,6 +59,17 @@ just audit # advisory database check, warnings fail ## Submitting a change +Release tooling has its own focused checks: + +```sh +just release-test +just release-build aarch64-apple-darwin # select the native target +``` + +These require Python 3.11 or newer; the tooling tests also require Minisign. +The [release guide](../docs/src/development/releases.md) describes signing +configuration, tag/manual publication, and consumer verification. + 1. Branch off `main` (`git switch -c fix/short-description`). 2. Make the change and add tests where needed. 3. Run the full `just ci`. diff --git a/.github/release/install-minisign.sh b/.github/release/install-minisign.sh new file mode 100644 index 0000000..2d31d6d --- /dev/null +++ b/.github/release/install-minisign.sh @@ -0,0 +1,17 @@ +#!/usr/bin/env bash +# Install the verified official Minisign 0.12 Linux x86-64 binary for release jobs. +set -euo pipefail + +tool_dir="$(mktemp -d)" +trap 'rm -rf "$tool_dir"' EXIT +curl --fail --silent --show-error --location --retry 3 \ + https://github.com/jedisct1/minisign/releases/download/0.12/minisign-0.12-linux.tar.gz \ + --output "$tool_dir/minisign.tar.gz" +printf '%s %s\n' \ + 9a599b48ba6eb7b1e80f12f36b94ceca7c00b7a5173c95c3efc88d9822957e73 \ + "$tool_dir/minisign.tar.gz" | sha256sum --check --status +tar -xzf "$tool_dir/minisign.tar.gz" -C "$tool_dir" minisign-linux/x86_64/minisign +mkdir -p "$HOME/.local/bin" +install -m 0755 "$tool_dir/minisign-linux/x86_64/minisign" "$HOME/.local/bin/minisign" +echo "$HOME/.local/bin" >> "$GITHUB_PATH" +"$HOME/.local/bin/minisign" -v diff --git a/.github/release/publish.sh b/.github/release/publish.sh new file mode 100644 index 0000000..70c7dc0 --- /dev/null +++ b/.github/release/publish.sh @@ -0,0 +1,32 @@ +#!/usr/bin/env bash +# Publish only after downloading and verifying every signed draft asset. +# Args: tag (string), source commit (SHA), artifact directory (path). +# Requires GH_TOKEN, MINISIGN_PUBLIC_KEY and the GitHub workflow identity variables. +set -euo pipefail + +tag="$1" +commit="$2" +directory="$3" +if gh release view "$tag" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then + echo "Release already exists; refusing to replace its assets" >&2 + exit 1 +fi +release_flags=() +if [[ "$tag" == *-* ]]; then + release_flags+=(--prerelease) +fi +gh release create "$tag" "$directory"/* \ + --repo "$GITHUB_REPOSITORY" --verify-tag --draft \ + --title "$tag" --generate-notes "${release_flags[@]}" +download_dir="$(mktemp -d)" +trap 'rm -rf "$download_dir"' EXIT +gh release download "$tag" --repo "$GITHUB_REPOSITORY" --dir "$download_dir" +just release-verify "$tag" "$commit" "$download_dir" +minisign -V -H -P "$MINISIGN_PUBLIC_KEY" -m "$download_dir/SHA256SUMS" +for artifact in "$download_dir"/*; do + gh attestation verify "$artifact" --repo "$GITHUB_REPOSITORY" \ + --signer-workflow "$GITHUB_REPOSITORY/.github/workflows/release.yml" \ + --source-digest "$GITHUB_SHA" --source-ref "$GITHUB_REF" \ + --deny-self-hosted-runners +done +gh release edit "$tag" --repo "$GITHUB_REPOSITORY" --draft=false diff --git a/.github/release/release.py b/.github/release/release.py new file mode 100644 index 0000000..eb7f9eb --- /dev/null +++ b/.github/release/release.py @@ -0,0 +1,273 @@ +"""Validate release sources and package and verify the distributed files.""" + +import argparse +import gzip +import hashlib +import json +import os +import re +import shutil +import subprocess +import tarfile +import tempfile +import tomllib +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +TARGETS = ( + "x86_64-unknown-linux-gnu", + "x86_64-unknown-linux-musl", + "aarch64-unknown-linux-gnu", + "x86_64-apple-darwin", + "aarch64-apple-darwin", +) + + +def git(root: Path, *args: str) -> str: + """Run Git in the source checkout. + + Args: + root (Path): Checkout directory. + *args (str): Git arguments. + + Returns: + str: Standard output with trailing whitespace removed. + + Raises: + subprocess.CalledProcessError: Git rejects the operation. + """ + return subprocess.check_output(["git", *args], cwd=root, text=True).strip() + + +def validate_tag(tag: str, version: str) -> None: + """Require a version tag matching the Cargo package. + + Args: + tag (str): Release tag, including its v prefix. + version (str): Cargo package version. + + Raises: + ValueError: The tag is malformed or differs from the package version. + """ + if not re.fullmatch(r"v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?", tag): + raise ValueError( + "release tag must be vMAJOR.MINOR.PATCH with an optional prerelease" + ) + if tag != f"v{version}": + raise ValueError("release tag does not match Cargo.toml") + + +def plan(root: Path, tag: str, preview: bool) -> tuple[str, str]: + """Resolve the immutable source revision for a release or PR build. + + Args: + root (Path): Checkout with fetched tags and origin/main. + tag (str): Existing release tag; unused for a PR preview. + preview (bool): Whether to build the checked-out PR revision. + + Returns: + tuple[str, str]: Validated tag and source commit SHA. + + Raises: + ValueError: The tag/version is invalid or its commit is outside main. + subprocess.CalledProcessError: A required Git ref is unavailable. + """ + if preview: + manifest = tomllib.loads((root / "Cargo.toml").read_text()) + tag = f"v{manifest['package']['version']}" + commit = git(root, "rev-parse", "HEAD") + else: + # Validate before using the supplied tag as a Git revision. + validate_tag(tag, tag.removeprefix("v")) + commit = git(root, "rev-parse", "--verify", f"refs/tags/{tag}^{{commit}}") + if subprocess.run( + ["git", "merge-base", "--is-ancestor", commit, "origin/main"], + cwd=root, + check=False, + ).returncode: + raise ValueError("release tag must point to a commit reachable from main") + manifest = tomllib.loads(git(root, "show", f"{commit}:Cargo.toml")) + validate_tag(tag, manifest["package"]["version"]) + return tag, commit + + +def archive_names(tag: str) -> set[str]: + """Return the complete set of versioned archive names. + + Args: + tag (str): Validated release tag. + + Returns: + set[str]: One archive filename for each supported target. + """ + return {f"postmaster-{tag}-{target}.tar.gz" for target in TARGETS} + + +def verify_archive(path: Path, root: Path | None = None) -> None: + """Check archive contents and optionally execute the extracted binary. + + Args: + path (Path): Release archive to inspect. + root (Path | None): Source checkout for an optional packaged-binary smoke check. + + Raises: + ValueError: Entries include unexpected paths, links, or permissions. + subprocess.CalledProcessError: The packaged binary fails its smoke check. + """ + with tarfile.open(path, "r:gz") as archive: + members = archive.getmembers() + if [entry.name for entry in members] != ["postmaster", "LICENSE"]: + raise ValueError("archive must contain exactly postmaster and LICENSE") + if any(not entry.isfile() for entry in members): + raise ValueError("archive entries must be regular files") + if [entry.mode for entry in members] != [0o755, 0o644]: + raise ValueError("archive permissions differ from the release contract") + if root is not None: + with tempfile.TemporaryDirectory(prefix="postmaster-release-") as directory: + binary = Path(directory) / "postmaster" + with ( + archive.extractfile(members[0]) as source, + binary.open("wb") as output, + ): + shutil.copyfileobj(source, output) + binary.chmod(0o755) + version = tomllib.loads((root / "Cargo.toml").read_text())["package"][ + "version" + ] + actual = subprocess.check_output( + [str(binary), "--version"], text=True + ).strip() + if actual != f"postmaster {version}": + raise ValueError("packaged binary reports the wrong version") + subprocess.run( + [ + str(binary), + "exec", + "--config", + str(root / "docs/examples/exec-env.json"), + "--check", + ], + check=True, + ) + + +def package(root: Path, target: str) -> Path: + """Package a built release binary and smoke-test the resulting archive. + + Args: + root (Path): Built source checkout. + target (str): Supported Rust target triple. + + Returns: + Path: Verified archive under target/release-artifacts. + + Raises: + ValueError: The target or binary type is invalid, or verification fails. + OSError: An input cannot be read or the archive cannot be written. + """ + if target not in TARGETS: + raise ValueError("unsupported release target") + version = tomllib.loads((root / "Cargo.toml").read_text())["package"]["version"] + tag = f"v{version}" + validate_tag(tag, version) + binary = root / "target" / target / "release/postmaster" + if binary.is_symlink() or not binary.is_file(): + raise ValueError("release binary must be a regular file") + directory = root / "target/release-artifacts" + directory.mkdir(parents=True, exist_ok=True) + path = directory / f"postmaster-{tag}-{target}.tar.gz" + timestamp = int(git(root, "show", "-s", "--format=%ct", "HEAD")) + with ( + path.open("wb") as output, + gzip.GzipFile(fileobj=output, mode="wb", filename="", mtime=0) as compressed, + tarfile.open(fileobj=compressed, mode="w") as archive, + ): + for source, name, mode in [ + (binary, "postmaster", 0o755), + (root / "LICENSE", "LICENSE", 0o644), + ]: + info = tarfile.TarInfo(name) + info.size = source.stat().st_size + info.mode = mode + info.mtime = timestamp + with source.open("rb") as data: + archive.addfile(info, data) + verify_archive(path, root) + return path + + +def release_files(directory: Path, tag: str, commit: str, verify: bool) -> None: + """Create or verify a complete release manifest and its bound source metadata. + + Args: + directory (Path): Release files, without nested directories. + tag (str): Release tag matching the source manifest. + commit (str): Exact tagged source commit. + verify (bool): Verify existing metadata/checksums instead of creating them. + + Raises: + ValueError: Files, metadata, archive contents, or hashes are inconsistent. + OSError: Release files cannot be read or written. + """ + validate_tag(tag, tag.removeprefix("v")) + if not re.fullmatch(r"[0-9a-f]{40}", commit): + raise ValueError("release source must be an exact commit SHA") + archives = archive_names(tag) + expected = archives | ( + {"release.json", "SHA256SUMS", "SHA256SUMS.minisig"} if verify else set() + ) + if {p.name for p in directory.iterdir()} != expected: + raise ValueError("release files do not match the complete target set") + if any(p.is_symlink() or not p.is_file() for p in directory.iterdir()): + raise ValueError("release files must be regular files") + for name in sorted(archives): + verify_archive(directory / name) + metadata = {"tag": tag, "commit": commit, "targets": list(TARGETS)} + metadata_path = directory / "release.json" + if verify: + if json.loads(metadata_path.read_text()) != metadata: + raise ValueError( + "release metadata does not match its tag and source commit" + ) + else: + metadata_path.write_text(json.dumps(metadata, indent=2) + "\n") + checksums = [] + for name in sorted(archives | {"release.json"}): + with (directory / name).open("rb") as data: + digest = hashlib.file_digest(data, "sha256").hexdigest() + checksums.append(f"{digest} {name}\n") + manifest = directory / "SHA256SUMS" + if verify: + if manifest.read_text() != "".join(checksums): + raise ValueError("release checksums do not match the distributed files") + else: + manifest.write_text("".join(checksums)) + + +def main() -> None: + """Dispatch release tooling; invalid input terminates with a nonzero status.""" + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("command", choices=["plan", "package", "manifest", "verify"]) + parser.add_argument("args", nargs="*") + args = parser.parse_args() + if args.command == "plan": + event = os.environ.get("GITHUB_EVENT_NAME", "workflow_dispatch") + if ( + event == "workflow_dispatch" + and os.environ.get("GITHUB_REF", "refs/heads/main") != "refs/heads/main" + ): + raise ValueError("manual releases must run the workflow from main") + tag, commit = plan( + ROOT, os.environ.get("RELEASE_TAG", ""), event == "pull_request" + ) + print(f"tag={tag}\ncommit={commit}") + elif args.command == "package": + (target,) = args.args + print(package(ROOT, target)) + else: + tag, commit, directory = args.args + release_files(Path(directory), tag, commit, args.command == "verify") + + +if __name__ == "__main__": + main() diff --git a/.github/release/sign.sh b/.github/release/sign.sh new file mode 100644 index 0000000..4a4fd30 --- /dev/null +++ b/.github/release/sign.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env bash +# Sign the complete release manifest using a dedicated, noninteractive key. +# Args: tag (string), source commit (SHA), artifact directory (path). +# Requires MINISIGN_SECRET_KEY and MINISIGN_PUBLIC_KEY; failure stops publication. +set -euo pipefail +umask 077 + +tag="$1" +commit="$2" +directory="$3" +: "${MINISIGN_SECRET_KEY:?Configure the dedicated release signing secret}" +: "${MINISIGN_PUBLIC_KEY:?Configure the trusted release public key}" +key_dir="$(mktemp -d)" +trap 'rm -rf "$key_dir"' EXIT +printf '%s\n' "$MINISIGN_SECRET_KEY" > "$key_dir/minisign.key" +unset MINISIGN_SECRET_KEY +minisign -S -W -s "$key_dir/minisign.key" -m "$directory/SHA256SUMS" \ + -t "postmaster $tag source $commit" +minisign -V -H -P "$MINISIGN_PUBLIC_KEY" -m "$directory/SHA256SUMS" diff --git a/.github/release/test_release.py b/.github/release/test_release.py new file mode 100644 index 0000000..93a2c36 --- /dev/null +++ b/.github/release/test_release.py @@ -0,0 +1,310 @@ +"""Exercise release source authorization, archive integrity and real signatures.""" + +import io +import json +import os +import subprocess +import tarfile +import tempfile +import unittest +from pathlib import Path + +import release + + +class ReleaseTests(unittest.TestCase): + def setUp(self): + self.directory = tempfile.TemporaryDirectory(prefix="postmaster-release-test-") + self.addCleanup(self.directory.cleanup) + self.root = Path(self.directory.name) + self.tag = "v0.1.0" + self.commit = "a" * 40 + + def archive(self, path, binary=b"binary", name="postmaster", kind=tarfile.REGTYPE): + with tarfile.open(path, "w:gz") as archive: + for entry, data, mode in [ + (name, binary, 0o755), + ("LICENSE", b"license", 0o644), + ]: + info = tarfile.TarInfo(entry) + info.mode = mode + info.type = kind if entry == name else tarfile.REGTYPE + info.size = len(data) if info.isfile() else 0 + archive.addfile(info, io.BytesIO(data) if info.isfile() else None) + + def files(self): + for name in release.archive_names(self.tag): + self.archive(self.root / name) + + def keypair(self, name): + secret = self.root / f"{name}.key" + public = self.root / f"{name}.pub" + subprocess.run( + ["minisign", "-G", "-W", "-s", str(secret), "-p", str(public)], + check=True, + capture_output=True, + ) + return secret.read_text(), public.read_text().splitlines()[-1] + + def test_tag_resolves_its_own_manifest_and_rejects_unmerged_commit(self): + release.git(self.root, "init", "-b", "main") + manifest = self.root / "Cargo.toml" + manifest.write_text('[package]\nversion = "0.1.0"\n') + release.git(self.root, "add", "Cargo.toml") + commit_args = [ + "-c", + "commit.gpgsign=false", + "-c", + "core.hooksPath=/dev/null", + "-c", + "user.name=Release test", + "-c", + "user.email=release@example.invalid", + "commit", + "-m", + "fixture", + ] + release.git(self.root, *commit_args) + release.git(self.root, "tag", self.tag) + original = release.git(self.root, "rev-parse", "HEAD") + manifest.write_text('[package]\nversion = "0.2.0"\n') + release.git(self.root, "add", "Cargo.toml") + release.git(self.root, *commit_args) + release.git(self.root, "update-ref", "refs/remotes/origin/main", "HEAD") + self.assertEqual(release.plan(self.root, self.tag, False), (self.tag, original)) + release.git(self.root, "checkout", "-b", "unmerged") + manifest.write_text('[package]\nversion = "0.3.0"\n') + release.git(self.root, "add", "Cargo.toml") + release.git(self.root, *commit_args) + release.git(self.root, "tag", "v0.3.0") + with self.assertRaisesRegex(ValueError, "reachable from main"): + release.plan(self.root, "v0.3.0", False) + release.git(self.root, "tag", "v0.9.0", original) + with self.assertRaisesRegex(ValueError, "Cargo.toml"): + release.plan(self.root, "v0.9.0", False) + + def test_tag_rejects_revision_syntax_and_shell_input(self): + for tag in ["main", "v0.1.0^{commit}", "v0.1.0;exit", "v0.1.0\n", "v../0.1.0"]: + with self.subTest(tag=tag), self.assertRaises(ValueError): + release.validate_tag(tag, "0.1.0") + + def test_archive_rejects_traversal_links_and_duplicate_entries(self): + for name, kind in [ + ("../postmaster", tarfile.REGTYPE), + ("postmaster", tarfile.SYMTYPE), + ("LICENSE", tarfile.REGTYPE), + ]: + path = self.root / "bad.tar.gz" + self.archive(path, name=name, kind=kind) + with self.subTest(name=name, kind=kind), self.assertRaises(ValueError): + release.verify_archive(path) + + def test_manifest_rejects_missing_and_unexpected_targets(self): + self.files() + extra = self.root / "unexpected.tar.gz" + extra.write_bytes(b"unexpected") + with self.assertRaisesRegex(ValueError, "complete target set"): + release.release_files(self.root, self.tag, self.commit, False) + extra.unlink() + (self.root / next(iter(release.archive_names(self.tag)))).unlink() + with self.assertRaisesRegex(ValueError, "complete target set"): + release.release_files(self.root, self.tag, self.commit, False) + + def test_manifest_binds_source_and_rejects_changed_archive(self): + self.files() + release.release_files(self.root, self.tag, self.commit, False) + (self.root / "SHA256SUMS.minisig").write_text("signature checked separately") + release.release_files(self.root, self.tag, self.commit, True) + with self.assertRaisesRegex(ValueError, "source commit"): + release.release_files(self.root, self.tag, "b" * 40, True) + self.archive( + self.root / min(release.archive_names(self.tag)), binary=b"changed" + ) + with self.assertRaisesRegex(ValueError, "checksums"): + release.release_files(self.root, self.tag, self.commit, True) + + def test_real_signature_rejects_tampered_manifest_and_wrong_key(self): + secret, public = self.keypair("release") + _, other_public = self.keypair("other") + manifest = self.root / "SHA256SUMS" + manifest.write_text("original manifest\n") + env = os.environ | { + "MINISIGN_SECRET_KEY": secret, + "MINISIGN_PUBLIC_KEY": public, + } + command = [ + "bash", + str(release.ROOT / ".github/release/sign.sh"), + self.tag, + self.commit, + str(self.root), + ] + subprocess.run(command, env=env, check=True, capture_output=True) + verify = ["minisign", "-V", "-H", "-P", public, "-m", str(manifest)] + self.assertEqual( + subprocess.run(verify, check=False, capture_output=True).returncode, 0 + ) + manifest.write_text("tampered manifest\n") + self.assertNotEqual( + subprocess.run(verify, check=False, capture_output=True).returncode, 0 + ) + manifest.write_text("original manifest\n") + verify[4] = other_public + self.assertNotEqual( + subprocess.run(verify, check=False, capture_output=True).returncode, 0 + ) + + def test_signing_refuses_missing_configuration(self): + env = os.environ.copy() + env.pop("MINISIGN_SECRET_KEY", None) + env.pop("MINISIGN_PUBLIC_KEY", None) + command = [ + "bash", + str(release.ROOT / ".github/release/sign.sh"), + self.tag, + self.commit, + str(self.root), + ] + self.assertNotEqual( + subprocess.run( + command, env=env, check=False, capture_output=True + ).returncode, + 0, + ) + self.assertFalse((self.root / "SHA256SUMS.minisig").exists()) + + def test_complete_signed_release_and_manual_branch_guard(self): + secret, public = self.keypair("release") + directory = self.root / "dist" + directory.mkdir() + for name in release.archive_names(self.tag): + self.archive(directory / name) + release.release_files(directory, self.tag, self.commit, False) + env = os.environ | { + "MINISIGN_SECRET_KEY": secret, + "MINISIGN_PUBLIC_KEY": public, + } + subprocess.run( + [ + "bash", + str(release.ROOT / ".github/release/sign.sh"), + self.tag, + self.commit, + str(directory), + ], + env=env, + check=True, + capture_output=True, + ) + release.release_files(directory, self.tag, self.commit, True) + env = os.environ | { + "GITHUB_EVENT_NAME": "workflow_dispatch", + "GITHUB_REF": "refs/heads/untrusted", + "RELEASE_TAG": self.tag, + } + result = subprocess.run( + ["python3", str(release.ROOT / ".github/release/release.py"), "plan"], + env=env, + check=False, + capture_output=True, + text=True, + ) + self.assertNotEqual(result.returncode, 0) + self.assertIn("workflow from main", result.stderr) + + def test_publication_requires_verified_downloads_and_preserves_existing_release( + self, + ): + secret, public = self.keypair("release") + directory = self.root / "dist" + directory.mkdir() + for name in release.archive_names(self.tag): + self.archive(directory / name) + release.release_files(directory, self.tag, self.commit, False) + env = os.environ | { + "MINISIGN_SECRET_KEY": secret, + "MINISIGN_PUBLIC_KEY": public, + } + subprocess.run( + [ + "bash", + str(release.ROOT / ".github/release/sign.sh"), + self.tag, + self.commit, + str(directory), + ], + env=env, + check=True, + capture_output=True, + ) + tools = self.root / "bin" + tools.mkdir() + fake = tools / "gh" + fake.write_text("""#!/usr/bin/env python3 +import json, os, shutil, sys +from pathlib import Path +args = sys.argv[1:] +with Path(os.environ["GH_TEST_LOG"]).open("a") as log: + log.write(json.dumps(args) + "\\n") +if args[:2] == ["release", "view"]: + sys.exit(0 if os.environ.get("GH_TEST_EXISTING") else 1) +if args[:2] == ["release", "download"]: + target = Path(args[args.index("--dir") + 1]) + for source in Path(os.environ["GH_TEST_ASSETS"]).iterdir(): + shutil.copyfile(source, target / source.name) + if os.environ.get("GH_TEST_CORRUPT"): + (target / "release.json").write_text("{}") +if args[:2] == ["attestation", "verify"] and os.environ.get("GH_TEST_BAD_ATTESTATION"): + sys.exit(1) +""") + fake.chmod(0o755) + log = self.root / "gh.log" + env = os.environ | { + "PATH": str(tools) + os.pathsep + os.environ["PATH"], + "GH_TEST_LOG": str(log), + "GH_TEST_ASSETS": str(directory), + "GITHUB_REPOSITORY": "beardedeagle/postmaster", + "GITHUB_SHA": self.commit, + "GITHUB_REF": "refs/tags/" + self.tag, + "MINISIGN_PUBLIC_KEY": public, + "JUST_NO_DOTENV": "true", + } + command = [ + "bash", + str(release.ROOT / ".github/release/publish.sh"), + self.tag, + self.commit, + str(directory), + ] + for failure in [ + "GH_TEST_CORRUPT", + "GH_TEST_EXISTING", + "GH_TEST_BAD_ATTESTATION", + ]: + with self.subTest(failure=failure): + log.write_text("") + result = subprocess.run( + command, + cwd=release.ROOT, + env=env | {failure: "1"}, + check=False, + capture_output=True, + ) + self.assertNotEqual(result.returncode, 0) + self.assertNotIn('"edit"', log.read_text()) + if failure == "GH_TEST_EXISTING": + self.assertNotIn('"create"', log.read_text()) + log.write_text("") + subprocess.run( + command, cwd=release.ROOT, env=env, check=True, capture_output=True + ) + calls = [json.loads(line) for line in log.read_text().splitlines()] + self.assertEqual(calls[-1][:2], ["release", "edit"]) + self.assertIn("--draft=false", calls[-1]) + self.assertEqual( + sum(call[:2] == ["attestation", "verify"] for call in calls), 8 + ) + + +if __name__ == "__main__": + unittest.main() diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..5ceb6d7 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,191 @@ +name: Release + +on: + push: + tags: ["v*"] + workflow_dispatch: + inputs: + tag: + description: Existing version tag to release (vMAJOR.MINOR.PATCH) + required: true + type: string + pull_request: + paths: + - ".github/workflows/release.yml" + - ".github/release/**" + - ".github/actions/setup-rust/**" + - "Cargo.toml" + - "Cargo.lock" + - "src/**" + - "tests/**" + - "Justfile" + +concurrency: + group: release-${{ inputs.tag || github.ref_name }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +permissions: + contents: read + +env: + JUST_NO_DOTENV: "true" + CARGO_TERM_COLOR: always + +jobs: + plan: + name: Validate release source + runs-on: ubuntu-24.04 + timeout-minutes: 15 + outputs: + tag: ${{ steps.source.outputs.tag }} + commit: ${{ steps.source.outputs.commit }} + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + persist-credentials: false + - name: Setup Python + uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: "3.14" + - name: Setup Rust and just + uses: ./.github/actions/setup-rust + - name: Install Minisign + run: bash .github/release/install-minisign.sh + - name: Test release tooling + run: just release-test + - name: Resolve source + id: source + env: + RELEASE_TAG: ${{ inputs.tag || github.ref_name }} + run: just release-plan >> "$GITHUB_OUTPUT" + + build: + name: Build ${{ matrix.target }} + needs: plan + runs-on: ${{ matrix.os }} + timeout-minutes: 30 + permissions: + contents: read + id-token: write + attestations: write + strategy: + fail-fast: false + matrix: + include: + - os: ubuntu-24.04 + target: x86_64-unknown-linux-gnu + - os: ubuntu-24.04 + target: x86_64-unknown-linux-musl + - os: ubuntu-24.04-arm + target: aarch64-unknown-linux-gnu + - os: macos-15-intel + target: x86_64-apple-darwin + - os: macos-15 + target: aarch64-apple-darwin + steps: + - name: Checkout validated source + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ needs.plan.outputs.commit }} + persist-credentials: false + - name: Setup Python + uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: "3.14" + - name: Setup Rust and just + uses: ./.github/actions/setup-rust + with: + targets: ${{ matrix.target }} + - name: Install musl linker + if: matrix.target == 'x86_64-unknown-linux-musl' + run: | + sudo apt-get update + sudo apt-get install --yes musl-tools + - name: Build, test and package release binary + env: + RELEASE_TARGET: ${{ matrix.target }} + run: just release-build "$RELEASE_TARGET" + - name: Attest the built archive + if: github.event_name != 'pull_request' + uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2 + with: + subject-path: target/release-artifacts/*.tar.gz + create-storage-record: false + - name: Upload release archive + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: release-${{ matrix.target }} + path: target/release-artifacts/*.tar.gz + if-no-files-found: error + retention-days: 7 + + publish: + name: Sign, verify and publish + if: github.event_name != 'pull_request' + needs: [plan, build] + runs-on: ubuntu-24.04 + timeout-minutes: 20 + environment: release + permissions: + contents: write + id-token: write + attestations: write + env: + RELEASE_TAG: ${{ needs.plan.outputs.tag }} + RELEASE_COMMIT: ${{ needs.plan.outputs.commit }} + MINISIGN_PUBLIC_KEY: ${{ vars.MINISIGN_PUBLIC_KEY }} + steps: + - name: Checkout validated source + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ needs.plan.outputs.commit }} + fetch-depth: 0 + persist-credentials: false + - name: Setup Python + uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: "3.14" + - name: Setup Rust and just + uses: ./.github/actions/setup-rust + - name: Install Minisign + run: bash .github/release/install-minisign.sh + - name: Download built archives + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + pattern: release-* + merge-multiple: true + path: target/release-artifacts + - name: Check tag and build attestations + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + just release-plan > "$RUNNER_TEMP/release-source" + grep -Fx "commit=$RELEASE_COMMIT" "$RUNNER_TEMP/release-source" + for archive in target/release-artifacts/*.tar.gz; do + gh attestation verify "$archive" --repo "$GITHUB_REPOSITORY" \ + --signer-workflow "$GITHUB_REPOSITORY/.github/workflows/release.yml" \ + --source-digest "$GITHUB_SHA" --source-ref "$GITHUB_REF" \ + --deny-self-hosted-runners + done + just release-manifest "$RELEASE_TAG" "$RELEASE_COMMIT" + - name: Sign the manifest + env: + MINISIGN_SECRET_KEY: ${{ secrets.MINISIGN_SECRET_KEY }} + run: just release-sign "$RELEASE_TAG" "$RELEASE_COMMIT" + - name: Verify signed release files + run: just release-verify "$RELEASE_TAG" "$RELEASE_COMMIT" + - name: Attest signed release metadata + uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2 + with: + subject-path: | + target/release-artifacts/SHA256SUMS + target/release-artifacts/SHA256SUMS.minisig + target/release-artifacts/release.json + create-storage-record: false + - name: Verify downloaded release before publication + env: + GH_TOKEN: ${{ github.token }} + run: just release-publish "$RELEASE_TAG" "$RELEASE_COMMIT" diff --git a/CHANGELOG.md b/CHANGELOG.md index e820825..fa0d4c6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -136,6 +136,11 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - Provides native and cross builds through the Justfile build matrix. Cross builds use `cargo zigbuild`; builds preserve compiler flags and profile overrides, and `max` builds remap source paths. +- Builds five Linux and macOS release targets from version tags or manual + runs. Runs release-profile tests and packaged-binary checks, signs SHA-256 + manifests with Minisign, and generates GitHub artifact attestations. + Verifies downloaded draft assets before publication and refuses to + overwrite existing releases. - Uses Justfile recipes for local checks and GitHub workflow definitions. In-repo setup actions refresh stable before resolving the repository's components and targets. Nix installation verifies diff --git a/Justfile b/Justfile index 54d98ae..515f82e 100644 --- a/Justfile +++ b/Justfile @@ -83,6 +83,30 @@ audit: ci-rust: fmt-check clippy clippy-release clippy-linux build test ci: ci-rust flake-check +# Release tooling is shared by local checks and the release workflow. +release-test: + python3 -B -m unittest discover -s .github/release -p 'test_*.py' -v + +release-plan: + python3 .github/release/release.py plan + +release-build target: + cargo +{{stable_toolchain}} test --locked --release --target {{quote(target)}} + cargo +{{stable_toolchain}} build --locked --release --target {{quote(target)}} + python3 .github/release/release.py package {{quote(target)}} + +release-manifest tag commit directory="target/release-artifacts": + python3 .github/release/release.py manifest {{quote(tag)}} {{quote(commit)}} {{quote(directory)}} + +release-sign tag commit directory="target/release-artifacts": + bash .github/release/sign.sh {{quote(tag)}} {{quote(commit)}} {{quote(directory)}} + +release-verify tag commit directory="target/release-artifacts": + python3 .github/release/release.py verify {{quote(tag)}} {{quote(commit)}} {{quote(directory)}} + +release-publish tag commit directory="target/release-artifacts": + bash .github/release/publish.sh {{quote(tag)}} {{quote(commit)}} {{quote(directory)}} + # ============================================================================= # Build Matrix — Cross-platform builds with varying optimization levels # ============================================================================= diff --git a/README.md b/README.md index 157f7dd..b5f2b5b 100644 --- a/README.md +++ b/README.md @@ -145,6 +145,10 @@ $ just build-matrix max macos-arm # optimized release Source builds require Rust 1.99.1 or newer. `just build-help` lists the optimization levels and cross-compilation targets. +[Release instructions](docs/src/development/releases.md) cover signed +checksums, GitHub attestations, binary installation, and tag or manual +publication. + Cross builds use `cargo zigbuild` and require the Rust target, `cargo-zigbuild`, and Zig to be installed; Darwin cross builds also require a macOS SDK. The matrix preserves compiler flags and profile environment overrides. Its diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 37fe6ec..2f55079 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -32,4 +32,5 @@ # Development +- [Releases](./development/releases.md) - [Changelog](./changelog.md) diff --git a/docs/src/development/releases.md b/docs/src/development/releases.md new file mode 100644 index 0000000..dbe8826 --- /dev/null +++ b/docs/src/development/releases.md @@ -0,0 +1,138 @@ +# Releases + +Version-tag pushes and manual runs publish the same release artifacts. +The tag must match the version in its `Cargo.toml`, and its commit must be +reachable from `main`. Manual runs use the workflow on `main` and select +an existing tag. + +Each release contains archives for these Rust targets: + +| Platform | Target | +| --- | --- | +| Linux x86-64 | `x86_64-unknown-linux-gnu` | +| Linux x86-64, static musl | `x86_64-unknown-linux-musl` | +| Linux ARM64 | `aarch64-unknown-linux-gnu` | +| macOS Intel | `x86_64-apple-darwin` | +| macOS Apple Silicon | `aarch64-apple-darwin` | + +The workflow runs release-profile tests on each target, packages the binary +and license, then runs the extracted binary's version and configuration +checks. GitHub attestations identify the workflow that builds each archive. +The publisher checks those attestations, signs the complete SHA-256 manifest +with Minisign, and attests the signed release metadata. It downloads the +draft release and verifies every asset before making the release public. + +## Signing setup + +Create a `release` GitHub environment that allows the `main` branch and +`v*` tags. Keep the dedicated signing key in that environment. Build jobs +receive no Minisign private key. + +Generate the release key outside the checkout, with a private directory +and an offline backup: + +```sh +umask 077 +mkdir -p "$HOME/.config/postmaster-release" +minisign -G -W \ + -s "$HOME/.config/postmaster-release/minisign.key" \ + -p "$HOME/.config/postmaster-release/minisign.pub" +``` + +The unattended signer uses a key without a passphrase. GitHub encrypts the +environment secret at rest. Configure the secret and public-key variable +without printing the private key: + +```sh +gh secret set MINISIGN_SECRET_KEY --repo beardedeagle/postmaster \ + --env release < "$HOME/.config/postmaster-release/minisign.key" +gh variable set MINISIGN_PUBLIC_KEY --repo beardedeagle/postmaster \ + --env release \ + --body "$(tail -n 1 "$HOME/.config/postmaster-release/minisign.pub")" +``` + +Publish the public key through a trusted channel before the first release. +Consumers must establish trust in that key independently of the files they +are about to verify. A public key downloaded alongside an archive does not +establish who signed it. Publication fails when either signing input is +missing or the public key does not match the private key. + +The signing job can use the release key. A compromised signing workflow can +therefore sign a malicious release; signatures do not replace source review +or the workflow's source restrictions. + +## Publish a version + +Commit the version and changelog, merge to `main`, then tag that commit: + +```sh +git tag v0.1.0 +git push origin v0.1.0 +``` + +To run manually for an existing tag: + +```sh +gh workflow run release.yml --repo beardedeagle/postmaster \ + --ref main -f tag=v0.1.0 +``` + +The workflow refuses to replace an existing release. If verification leaves +a failed draft, inspect it and remove that draft before retrying. Do not move +a published version tag or overwrite its assets. The workflow marks tags +with a prerelease suffix as prereleases. + +Pull requests exercise source validation, release tooling and all five +builds. They upload preview archives without signing, attesting or publishing +a release. Local recipes are `just release-test` and +`just release-build `; Python 3.11 or newer and Minisign are required +for the release-tool tests. + +## Verify and install + +Download the archive, `SHA256SUMS`, and `SHA256SUMS.minisig` for the chosen +version. This example selects Apple Silicon: + +```sh +version=v0.1.0 +archive="postmaster-${version}-aarch64-apple-darwin.tar.gz" +base="https://github.com/beardedeagle/postmaster/releases/download/${version}" +curl --fail --location --remote-name "$base/$archive" +curl --fail --location --remote-name "$base/SHA256SUMS" +curl --fail --location --remote-name "$base/SHA256SUMS.minisig" +``` + +Set `POSTMASTER_RELEASE_PUBLIC_KEY` to the independently trusted public key, +then verify the manifest signature and the selected archive's checksum: + +```sh +minisign -V -H -P "$POSTMASTER_RELEASE_PUBLIC_KEY" -m SHA256SUMS +awk -v file="$archive" '$2 == file { print }' SHA256SUMS > selected.sha256 +test "$(wc -l < selected.sha256 | tr -d ' ')" = 1 +shasum -a 256 -c selected.sha256 +gh attestation verify "$archive" --repo beardedeagle/postmaster \ + --signer-workflow beardedeagle/postmaster/.github/workflows/release.yml \ + --deny-self-hosted-runners +tar -xzf "$archive" postmaster LICENSE +mkdir -p "$HOME/.local/bin" +install -m 0755 postmaster "$HOME/.local/bin/postmaster" +``` + +`release.json` records the tagged source commit and complete target set. +Its checksum is covered by the same signed manifest. A manual run's +attestation identifies its triggering `main` revision; `release.json` +identifies the selected tagged source revision. + +macOS binaries have no Apple Developer ID signature or notarization. +Minisign and attestations provide release authenticity and build provenance; +they do not satisfy Gatekeeper. `curl` downloads and local builds generally +avoid browser-applied quarantine. Browser downloads can still prompt or be +blocked. The workflow does not disable Gatekeeper or remove quarantine. + +To build locally instead: + +```sh +cargo build --locked --release +mkdir -p "$HOME/.local/bin" +install -m 0755 target/release/postmaster "$HOME/.local/bin/postmaster" +``` From 2cefaa0bf6d5b2edb9702b5385c88e7f825c11bb Mon Sep 17 00:00:00 2001 From: beardedeagle Date: Tue, 10 Nov 2026 12:13:17 -0600 Subject: [PATCH 2/3] docs: stop installation when release verification fails --- .github/release/test_release.py | 48 ++++++++++++++++++++++++++ docs/src/development/releases.md | 59 ++++++++++++++++---------------- 2 files changed, 78 insertions(+), 29 deletions(-) diff --git a/.github/release/test_release.py b/.github/release/test_release.py index 93a2c36..3347a55 100644 --- a/.github/release/test_release.py +++ b/.github/release/test_release.py @@ -173,6 +173,54 @@ def test_signing_refuses_missing_configuration(self): ) self.assertFalse((self.root / "SHA256SUMS.minisig").exists()) + def test_install_instructions_stop_on_failed_verification(self): + guide = (release.ROOT / "docs/src/development/releases.md").read_text() + snippet = ( + guide.split("## Verify and install", 1)[1] + .split("```sh\n", 1)[1] + .split("```", 1)[0] + ) + tools = self.root / "bin" + tools.mkdir() + program = tools / "stub" + program.write_text("""#!/usr/bin/env python3 +import os, sys +from pathlib import Path +name = Path(sys.argv[0]).name +if name == "install": + Path("installed").touch() +sys.exit(1 if os.environ.get("REJECT") == name else 0) +""") + program.chmod(0o755) + for name in ["curl", "minisign", "shasum", "gh", "tar", "mkdir", "install"]: + (tools / name).symlink_to(program) + (self.root / "SHA256SUMS").write_text( + "a" * 64 + " postmaster-v0.1.0-aarch64-apple-darwin.tar.gz\n" + ) + env = os.environ | { + "PATH": str(tools) + os.pathsep + os.environ["PATH"], + "POSTMASTER_RELEASE_PUBLIC_KEY": "fixture", + } + for failure in ["curl", "minisign", "shasum", "gh"]: + with self.subTest(failure=failure): + result = subprocess.run( + ["sh", "-c", snippet], + cwd=self.root, + env=env | {"REJECT": failure}, + check=False, + capture_output=True, + ) + self.assertNotEqual(result.returncode, 0) + self.assertFalse((self.root / "installed").exists()) + subprocess.run( + ["sh", "-c", snippet], + cwd=self.root, + env=env, + check=True, + capture_output=True, + ) + self.assertTrue((self.root / "installed").exists()) + def test_complete_signed_release_and_manual_branch_guard(self): secret, public = self.keypair("release") directory = self.root / "dist" diff --git a/docs/src/development/releases.md b/docs/src/development/releases.md index dbe8826..5407a25 100644 --- a/docs/src/development/releases.md +++ b/docs/src/development/releases.md @@ -66,8 +66,7 @@ or the workflow's source restrictions. Commit the version and changelog, merge to `main`, then tag that commit: ```sh -git tag v0.1.0 -git push origin v0.1.0 +git tag v0.1.0 && git push origin v0.1.0 ``` To run manually for an existing tag: @@ -90,32 +89,31 @@ for the release-tool tests. ## Verify and install -Download the archive, `SHA256SUMS`, and `SHA256SUMS.minisig` for the chosen -version. This example selects Apple Silicon: +Set `POSTMASTER_RELEASE_PUBLIC_KEY` to the independently trusted public key. +Then download, verify and install the selected archive. This example selects +Apple Silicon. The subshell stops on the first failed command, before +extraction or installation: ```sh -version=v0.1.0 -archive="postmaster-${version}-aarch64-apple-darwin.tar.gz" -base="https://github.com/beardedeagle/postmaster/releases/download/${version}" -curl --fail --location --remote-name "$base/$archive" -curl --fail --location --remote-name "$base/SHA256SUMS" -curl --fail --location --remote-name "$base/SHA256SUMS.minisig" -``` - -Set `POSTMASTER_RELEASE_PUBLIC_KEY` to the independently trusted public key, -then verify the manifest signature and the selected archive's checksum: - -```sh -minisign -V -H -P "$POSTMASTER_RELEASE_PUBLIC_KEY" -m SHA256SUMS -awk -v file="$archive" '$2 == file { print }' SHA256SUMS > selected.sha256 -test "$(wc -l < selected.sha256 | tr -d ' ')" = 1 -shasum -a 256 -c selected.sha256 -gh attestation verify "$archive" --repo beardedeagle/postmaster \ - --signer-workflow beardedeagle/postmaster/.github/workflows/release.yml \ - --deny-self-hosted-runners -tar -xzf "$archive" postmaster LICENSE -mkdir -p "$HOME/.local/bin" -install -m 0755 postmaster "$HOME/.local/bin/postmaster" +( + set -eu + version=v0.1.0 + archive="postmaster-${version}-aarch64-apple-darwin.tar.gz" + base="https://github.com/beardedeagle/postmaster/releases/download/${version}" + curl --fail --location --remote-name "$base/$archive" + curl --fail --location --remote-name "$base/SHA256SUMS" + curl --fail --location --remote-name "$base/SHA256SUMS.minisig" + minisign -V -H -P "$POSTMASTER_RELEASE_PUBLIC_KEY" -m SHA256SUMS + awk -v file="$archive" '$2 == file { print }' SHA256SUMS > selected.sha256 + test "$(wc -l < selected.sha256 | tr -d ' ')" = 1 + shasum -a 256 -c selected.sha256 + gh attestation verify "$archive" --repo beardedeagle/postmaster \ + --signer-workflow beardedeagle/postmaster/.github/workflows/release.yml \ + --deny-self-hosted-runners + tar -xzf "$archive" postmaster LICENSE + mkdir -p "$HOME/.local/bin" + install -m 0755 postmaster "$HOME/.local/bin/postmaster" +) ``` `release.json` records the tagged source commit and complete target set. @@ -132,7 +130,10 @@ blocked. The workflow does not disable Gatekeeper or remove quarantine. To build locally instead: ```sh -cargo build --locked --release -mkdir -p "$HOME/.local/bin" -install -m 0755 target/release/postmaster "$HOME/.local/bin/postmaster" +( + set -eu + cargo build --locked --release + mkdir -p "$HOME/.local/bin" + install -m 0755 target/release/postmaster "$HOME/.local/bin/postmaster" +) ``` From 6d6e28f7b9aded2aa0217511c49e2423d2bffb58 Mon Sep 17 00:00:00 2001 From: beardedeagle Date: Thu, 12 Nov 2026 10:30:56 -0600 Subject: [PATCH 3/3] ci: verify releases with GitHub attestations --- .github/CONTRIBUTING.md | 11 +- .github/release/install-minisign.sh | 17 --- .github/release/publish.sh | 5 +- .github/release/release.py | 4 +- .github/release/sign.sh | 19 --- .github/release/test_release.py | 223 ++++++++++++---------------- .github/workflows/release.yml | 17 +-- CHANGELOG.md | 4 +- Justfile | 3 - README.md | 4 +- docs/src/development/releases.md | 72 +++------ 11 files changed, 138 insertions(+), 241 deletions(-) delete mode 100644 .github/release/install-minisign.sh delete mode 100644 .github/release/sign.sh diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 675de7b..a495bd3 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -39,7 +39,10 @@ just --list # see every available recipe ## The development loop Run the Rust gate before pushing. It includes native and release checks, -Linux-target Clippy, a locked build, and tests: +Linux-target Clippy, a locked build, and tests. + +The `Quality (ubuntu-latest)` and `Quality (macos-latest)` checks are required +on `main`. ```sh just ci-rust # fmt-check, native/release/Linux clippy, build, test @@ -66,9 +69,9 @@ just release-test just release-build aarch64-apple-darwin # select the native target ``` -These require Python 3.11 or newer; the tooling tests also require Minisign. -The [release guide](../docs/src/development/releases.md) describes signing -configuration, tag/manual publication, and consumer verification. +These require Python 3.11 or newer. +The [release guide](../docs/src/development/releases.md) describes GitHub +attestations, tag/manual publication, and consumer verification. 1. Branch off `main` (`git switch -c fix/short-description`). 2. Make the change and add tests where needed. diff --git a/.github/release/install-minisign.sh b/.github/release/install-minisign.sh deleted file mode 100644 index 2d31d6d..0000000 --- a/.github/release/install-minisign.sh +++ /dev/null @@ -1,17 +0,0 @@ -#!/usr/bin/env bash -# Install the verified official Minisign 0.12 Linux x86-64 binary for release jobs. -set -euo pipefail - -tool_dir="$(mktemp -d)" -trap 'rm -rf "$tool_dir"' EXIT -curl --fail --silent --show-error --location --retry 3 \ - https://github.com/jedisct1/minisign/releases/download/0.12/minisign-0.12-linux.tar.gz \ - --output "$tool_dir/minisign.tar.gz" -printf '%s %s\n' \ - 9a599b48ba6eb7b1e80f12f36b94ceca7c00b7a5173c95c3efc88d9822957e73 \ - "$tool_dir/minisign.tar.gz" | sha256sum --check --status -tar -xzf "$tool_dir/minisign.tar.gz" -C "$tool_dir" minisign-linux/x86_64/minisign -mkdir -p "$HOME/.local/bin" -install -m 0755 "$tool_dir/minisign-linux/x86_64/minisign" "$HOME/.local/bin/minisign" -echo "$HOME/.local/bin" >> "$GITHUB_PATH" -"$HOME/.local/bin/minisign" -v diff --git a/.github/release/publish.sh b/.github/release/publish.sh index 70c7dc0..2488fca 100644 --- a/.github/release/publish.sh +++ b/.github/release/publish.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash -# Publish only after downloading and verifying every signed draft asset. +# Publish only after checking every draft asset's integrity and GitHub attestation. # Args: tag (string), source commit (SHA), artifact directory (path). -# Requires GH_TOKEN, MINISIGN_PUBLIC_KEY and the GitHub workflow identity variables. +# Requires GH_TOKEN and the GitHub workflow identity variables. set -euo pipefail tag="$1" @@ -22,7 +22,6 @@ download_dir="$(mktemp -d)" trap 'rm -rf "$download_dir"' EXIT gh release download "$tag" --repo "$GITHUB_REPOSITORY" --dir "$download_dir" just release-verify "$tag" "$commit" "$download_dir" -minisign -V -H -P "$MINISIGN_PUBLIC_KEY" -m "$download_dir/SHA256SUMS" for artifact in "$download_dir"/*; do gh attestation verify "$artifact" --repo "$GITHUB_REPOSITORY" \ --signer-workflow "$GITHUB_REPOSITORY/.github/workflows/release.yml" \ diff --git a/.github/release/release.py b/.github/release/release.py index eb7f9eb..ec9daf6 100644 --- a/.github/release/release.py +++ b/.github/release/release.py @@ -213,9 +213,7 @@ def release_files(directory: Path, tag: str, commit: str, verify: bool) -> None: if not re.fullmatch(r"[0-9a-f]{40}", commit): raise ValueError("release source must be an exact commit SHA") archives = archive_names(tag) - expected = archives | ( - {"release.json", "SHA256SUMS", "SHA256SUMS.minisig"} if verify else set() - ) + expected = archives | ({"release.json", "SHA256SUMS"} if verify else set()) if {p.name for p in directory.iterdir()} != expected: raise ValueError("release files do not match the complete target set") if any(p.is_symlink() or not p.is_file() for p in directory.iterdir()): diff --git a/.github/release/sign.sh b/.github/release/sign.sh deleted file mode 100644 index 4a4fd30..0000000 --- a/.github/release/sign.sh +++ /dev/null @@ -1,19 +0,0 @@ -#!/usr/bin/env bash -# Sign the complete release manifest using a dedicated, noninteractive key. -# Args: tag (string), source commit (SHA), artifact directory (path). -# Requires MINISIGN_SECRET_KEY and MINISIGN_PUBLIC_KEY; failure stops publication. -set -euo pipefail -umask 077 - -tag="$1" -commit="$2" -directory="$3" -: "${MINISIGN_SECRET_KEY:?Configure the dedicated release signing secret}" -: "${MINISIGN_PUBLIC_KEY:?Configure the trusted release public key}" -key_dir="$(mktemp -d)" -trap 'rm -rf "$key_dir"' EXIT -printf '%s\n' "$MINISIGN_SECRET_KEY" > "$key_dir/minisign.key" -unset MINISIGN_SECRET_KEY -minisign -S -W -s "$key_dir/minisign.key" -m "$directory/SHA256SUMS" \ - -t "postmaster $tag source $commit" -minisign -V -H -P "$MINISIGN_PUBLIC_KEY" -m "$directory/SHA256SUMS" diff --git a/.github/release/test_release.py b/.github/release/test_release.py index 3347a55..5b6af23 100644 --- a/.github/release/test_release.py +++ b/.github/release/test_release.py @@ -1,8 +1,9 @@ -"""Exercise release source authorization, archive integrity and real signatures.""" +"""Exercise release source authorization, archive integrity and attestation policy.""" import io import json import os +import re import subprocess import tarfile import tempfile @@ -36,16 +37,6 @@ def files(self): for name in release.archive_names(self.tag): self.archive(self.root / name) - def keypair(self, name): - secret = self.root / f"{name}.key" - public = self.root / f"{name}.pub" - subprocess.run( - ["minisign", "-G", "-W", "-s", str(secret), "-p", str(public)], - check=True, - capture_output=True, - ) - return secret.read_text(), public.read_text().splitlines()[-1] - def test_tag_resolves_its_own_manifest_and_rejects_unmerged_commit(self): release.git(self.root, "init", "-b", "main") manifest = self.root / "Cargo.toml" @@ -113,7 +104,6 @@ def test_manifest_rejects_missing_and_unexpected_targets(self): def test_manifest_binds_source_and_rejects_changed_archive(self): self.files() release.release_files(self.root, self.tag, self.commit, False) - (self.root / "SHA256SUMS.minisig").write_text("signature checked separately") release.release_files(self.root, self.tag, self.commit, True) with self.assertRaisesRegex(ValueError, "source commit"): release.release_files(self.root, self.tag, "b" * 40, True) @@ -123,56 +113,6 @@ def test_manifest_binds_source_and_rejects_changed_archive(self): with self.assertRaisesRegex(ValueError, "checksums"): release.release_files(self.root, self.tag, self.commit, True) - def test_real_signature_rejects_tampered_manifest_and_wrong_key(self): - secret, public = self.keypair("release") - _, other_public = self.keypair("other") - manifest = self.root / "SHA256SUMS" - manifest.write_text("original manifest\n") - env = os.environ | { - "MINISIGN_SECRET_KEY": secret, - "MINISIGN_PUBLIC_KEY": public, - } - command = [ - "bash", - str(release.ROOT / ".github/release/sign.sh"), - self.tag, - self.commit, - str(self.root), - ] - subprocess.run(command, env=env, check=True, capture_output=True) - verify = ["minisign", "-V", "-H", "-P", public, "-m", str(manifest)] - self.assertEqual( - subprocess.run(verify, check=False, capture_output=True).returncode, 0 - ) - manifest.write_text("tampered manifest\n") - self.assertNotEqual( - subprocess.run(verify, check=False, capture_output=True).returncode, 0 - ) - manifest.write_text("original manifest\n") - verify[4] = other_public - self.assertNotEqual( - subprocess.run(verify, check=False, capture_output=True).returncode, 0 - ) - - def test_signing_refuses_missing_configuration(self): - env = os.environ.copy() - env.pop("MINISIGN_SECRET_KEY", None) - env.pop("MINISIGN_PUBLIC_KEY", None) - command = [ - "bash", - str(release.ROOT / ".github/release/sign.sh"), - self.tag, - self.commit, - str(self.root), - ] - self.assertNotEqual( - subprocess.run( - command, env=env, check=False, capture_output=True - ).returncode, - 0, - ) - self.assertFalse((self.root / "SHA256SUMS.minisig").exists()) - def test_install_instructions_stop_on_failed_verification(self): guide = (release.ROOT / "docs/src/development/releases.md").read_text() snippet = ( @@ -184,34 +124,44 @@ def test_install_instructions_stop_on_failed_verification(self): tools.mkdir() program = tools / "stub" program.write_text("""#!/usr/bin/env python3 -import os, sys +import json, os, sys from pathlib import Path name = Path(sys.argv[0]).name if name == "install": Path("installed").touch() +if name == "gh": + with Path("verified.jsonl").open("a") as log: + log.write(json.dumps(sys.argv[1:]) + "\\n") + if os.environ.get("REJECT_ARTIFACT") == sys.argv[3]: + sys.exit(1) sys.exit(1 if os.environ.get("REJECT") == name else 0) """) program.chmod(0o755) - for name in ["curl", "minisign", "shasum", "gh", "tar", "mkdir", "install"]: + for name in ["curl", "shasum", "gh", "tar", "mkdir", "install"]: (tools / name).symlink_to(program) - (self.root / "SHA256SUMS").write_text( - "a" * 64 + " postmaster-v0.1.0-aarch64-apple-darwin.tar.gz\n" - ) + archive = "postmaster-v0.1.0-aarch64-apple-darwin.tar.gz" + (self.root / "SHA256SUMS").write_text("a" * 64 + f" {archive}\n") env = os.environ | { "PATH": str(tools) + os.pathsep + os.environ["PATH"], - "POSTMASTER_RELEASE_PUBLIC_KEY": "fixture", } - for failure in ["curl", "minisign", "shasum", "gh"]: + for failure in [ + {"REJECT": "curl"}, + {"REJECT": "shasum"}, + {"REJECT_ARTIFACT": "SHA256SUMS"}, + {"REJECT_ARTIFACT": archive}, + ]: with self.subTest(failure=failure): result = subprocess.run( ["sh", "-c", snippet], cwd=self.root, - env=env | {"REJECT": failure}, + env=env | failure, check=False, capture_output=True, ) self.assertNotEqual(result.returncode, 0) self.assertFalse((self.root / "installed").exists()) + log = self.root / "verified.jsonl" + log.write_text("") subprocess.run( ["sh", "-c", snippet], cwd=self.root, @@ -220,31 +170,44 @@ def test_install_instructions_stop_on_failed_verification(self): capture_output=True, ) self.assertTrue((self.root / "installed").exists()) - - def test_complete_signed_release_and_manual_branch_guard(self): - secret, public = self.keypair("release") - directory = self.root / "dist" - directory.mkdir() - for name in release.archive_names(self.tag): - self.archive(directory / name) - release.release_files(directory, self.tag, self.commit, False) - env = os.environ | { - "MINISIGN_SECRET_KEY": secret, - "MINISIGN_PUBLIC_KEY": public, - } - subprocess.run( + calls = [json.loads(line) for line in log.read_text().splitlines()] + self.assertEqual( + [call[:3] for call in calls], [ - "bash", - str(release.ROOT / ".github/release/sign.sh"), - self.tag, - self.commit, - str(directory), + ["attestation", "verify", "SHA256SUMS"], + ["attestation", "verify", archive], ], - env=env, - check=True, - capture_output=True, ) - release.release_files(directory, self.tag, self.commit, True) + identity = ( + "https://github.com/beardedeagle/postmaster/.github/workflows/release.yml@" + ) + for call in calls: + self.assertEqual(call[call.index("--repo") + 1], "beardedeagle/postmaster") + self.assertEqual( + call[call.index("--signer-workflow") + 1], + "beardedeagle/postmaster/.github/workflows/release.yml", + ) + self.assertIn("--deny-self-hosted-runners", call) + pattern = call[call.index("--cert-identity-regex") + 1] + for ref in ["refs/heads/main", "refs/tags/v0.1.0", "refs/tags/v0.1.0-rc.1"]: + self.assertIsNotNone(re.fullmatch(pattern, identity + ref)) + for ref in [ + "refs/pull/15/merge", + "refs/heads/untrusted", + "refs/tags/untrusted", + "refs/tags/v0.1.0/untrusted", + "refs/heads/untrusted@refs/heads/main", + "refs/tags/v0.1.0@refs/heads/main", + ]: + self.assertIsNone(re.fullmatch(pattern, identity + ref)) + self.assertIsNone( + re.fullmatch( + pattern, + identity.replace("postmaster/", "other/") + "refs/heads/main", + ) + ) + + def test_manual_release_rejects_untrusted_branch(self): env = os.environ | { "GITHUB_EVENT_NAME": "workflow_dispatch", "GITHUB_REF": "refs/heads/untrusted", @@ -263,28 +226,11 @@ def test_complete_signed_release_and_manual_branch_guard(self): def test_publication_requires_verified_downloads_and_preserves_existing_release( self, ): - secret, public = self.keypair("release") directory = self.root / "dist" directory.mkdir() for name in release.archive_names(self.tag): self.archive(directory / name) release.release_files(directory, self.tag, self.commit, False) - env = os.environ | { - "MINISIGN_SECRET_KEY": secret, - "MINISIGN_PUBLIC_KEY": public, - } - subprocess.run( - [ - "bash", - str(release.ROOT / ".github/release/sign.sh"), - self.tag, - self.commit, - str(directory), - ], - env=env, - check=True, - capture_output=True, - ) tools = self.root / "bin" tools.mkdir() fake = tools / "gh" @@ -302,7 +248,9 @@ def test_publication_requires_verified_downloads_and_preserves_existing_release( shutil.copyfile(source, target / source.name) if os.environ.get("GH_TEST_CORRUPT"): (target / "release.json").write_text("{}") -if args[:2] == ["attestation", "verify"] and os.environ.get("GH_TEST_BAD_ATTESTATION"): + if os.environ.get("GH_TEST_MISSING"): + (target / os.environ["GH_TEST_MISSING"]).unlink() +if args[:2] == ["attestation", "verify"] and Path(args[2]).name == os.environ.get("GH_TEST_BAD_ATTESTATION"): sys.exit(1) """) fake.chmod(0o755) @@ -314,7 +262,6 @@ def test_publication_requires_verified_downloads_and_preserves_existing_release( "GITHUB_REPOSITORY": "beardedeagle/postmaster", "GITHUB_SHA": self.commit, "GITHUB_REF": "refs/tags/" + self.tag, - "MINISIGN_PUBLIC_KEY": public, "JUST_NO_DOTENV": "true", } command = [ @@ -324,34 +271,58 @@ def test_publication_requires_verified_downloads_and_preserves_existing_release( self.commit, str(directory), ] + files = release.archive_names(self.tag) | {"SHA256SUMS", "release.json"} for failure in [ - "GH_TEST_CORRUPT", - "GH_TEST_EXISTING", - "GH_TEST_BAD_ATTESTATION", + {"GH_TEST_CORRUPT": "1"}, + {"GH_TEST_EXISTING": "1"}, + {"GH_TEST_MISSING": min(files)}, + *({"GH_TEST_BAD_ATTESTATION": name} for name in sorted(files)), ]: with self.subTest(failure=failure): log.write_text("") result = subprocess.run( command, cwd=release.ROOT, - env=env | {failure: "1"}, + env=env | failure, check=False, capture_output=True, ) self.assertNotEqual(result.returncode, 0) self.assertNotIn('"edit"', log.read_text()) - if failure == "GH_TEST_EXISTING": + if "GH_TEST_EXISTING" in failure: self.assertNotIn('"create"', log.read_text()) - log.write_text("") - subprocess.run( - command, cwd=release.ROOT, env=env, check=True, capture_output=True - ) - calls = [json.loads(line) for line in log.read_text().splitlines()] - self.assertEqual(calls[-1][:2], ["release", "edit"]) - self.assertIn("--draft=false", calls[-1]) - self.assertEqual( - sum(call[:2] == ["attestation", "verify"] for call in calls), 8 - ) + for ref, digest in [ + (env["GITHUB_REF"], self.commit), + ("refs/heads/main", "b" * 40), + ]: + with self.subTest(ref=ref): + log.write_text("") + subprocess.run( + command, + cwd=release.ROOT, + env=env | {"GITHUB_REF": ref, "GITHUB_SHA": digest}, + check=True, + capture_output=True, + ) + calls = [json.loads(line) for line in log.read_text().splitlines()] + self.assertEqual(calls[-1][:2], ["release", "edit"]) + self.assertIn("--draft=false", calls[-1]) + verified = [ + call for call in calls if call[:2] == ["attestation", "verify"] + ] + self.assertEqual({Path(call[2]).name for call in verified}, files) + self.assertEqual(len(verified), len(files)) + for call in verified: + self.assertEqual( + call[call.index("--repo") + 1], "beardedeagle/postmaster" + ) + self.assertEqual( + call[call.index("--signer-workflow") + 1], + "beardedeagle/postmaster/.github/workflows/release.yml", + ) + self.assertEqual(call[call.index("--source-digest") + 1], digest) + self.assertEqual(call[call.index("--source-ref") + 1], ref) + self.assertIn("--deny-self-hosted-runners", call) if __name__ == "__main__": diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 5ceb6d7..d23f946 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -14,6 +14,7 @@ on: - ".github/workflows/release.yml" - ".github/release/**" - ".github/actions/setup-rust/**" + - "docs/src/development/releases.md" - "Cargo.toml" - "Cargo.lock" - "src/**" @@ -51,8 +52,6 @@ jobs: python-version: "3.14" - name: Setup Rust and just uses: ./.github/actions/setup-rust - - name: Install Minisign - run: bash .github/release/install-minisign.sh - name: Test release tooling run: just release-test - name: Resolve source @@ -122,7 +121,7 @@ jobs: retention-days: 7 publish: - name: Sign, verify and publish + name: Verify and publish if: github.event_name != 'pull_request' needs: [plan, build] runs-on: ubuntu-24.04 @@ -135,7 +134,6 @@ jobs: env: RELEASE_TAG: ${{ needs.plan.outputs.tag }} RELEASE_COMMIT: ${{ needs.plan.outputs.commit }} - MINISIGN_PUBLIC_KEY: ${{ vars.MINISIGN_PUBLIC_KEY }} steps: - name: Checkout validated source uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 @@ -149,8 +147,6 @@ jobs: python-version: "3.14" - name: Setup Rust and just uses: ./.github/actions/setup-rust - - name: Install Minisign - run: bash .github/release/install-minisign.sh - name: Download built archives uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 with: @@ -171,18 +167,13 @@ jobs: --deny-self-hosted-runners done just release-manifest "$RELEASE_TAG" "$RELEASE_COMMIT" - - name: Sign the manifest - env: - MINISIGN_SECRET_KEY: ${{ secrets.MINISIGN_SECRET_KEY }} - run: just release-sign "$RELEASE_TAG" "$RELEASE_COMMIT" - - name: Verify signed release files + - name: Verify release files run: just release-verify "$RELEASE_TAG" "$RELEASE_COMMIT" - - name: Attest signed release metadata + - name: Attest release metadata uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2 with: subject-path: | target/release-artifacts/SHA256SUMS - target/release-artifacts/SHA256SUMS.minisig target/release-artifacts/release.json create-storage-record: false - name: Verify downloaded release before publication diff --git a/CHANGELOG.md b/CHANGELOG.md index fa0d4c6..c31d80d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -137,8 +137,8 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Cross builds use `cargo zigbuild`; builds preserve compiler flags and profile overrides, and `max` builds remap source paths. - Builds five Linux and macOS release targets from version tags or manual - runs. Runs release-profile tests and packaged-binary checks, signs SHA-256 - manifests with Minisign, and generates GitHub artifact attestations. + runs. Runs release-profile tests and packaged-binary checks, and generates + GitHub attestations for archives, SHA-256 manifests, and source metadata. Verifies downloaded draft assets before publication and refuses to overwrite existing releases. - Uses Justfile recipes for local checks and GitHub workflow definitions. diff --git a/Justfile b/Justfile index 515f82e..c171062 100644 --- a/Justfile +++ b/Justfile @@ -98,9 +98,6 @@ release-build target: release-manifest tag commit directory="target/release-artifacts": python3 .github/release/release.py manifest {{quote(tag)}} {{quote(commit)}} {{quote(directory)}} -release-sign tag commit directory="target/release-artifacts": - bash .github/release/sign.sh {{quote(tag)}} {{quote(commit)}} {{quote(directory)}} - release-verify tag commit directory="target/release-artifacts": python3 .github/release/release.py verify {{quote(tag)}} {{quote(commit)}} {{quote(directory)}} diff --git a/README.md b/README.md index b5f2b5b..b8c321b 100644 --- a/README.md +++ b/README.md @@ -145,8 +145,8 @@ $ just build-matrix max macos-arm # optimized release Source builds require Rust 1.99.1 or newer. `just build-help` lists the optimization levels and cross-compilation targets. -[Release instructions](docs/src/development/releases.md) cover signed -checksums, GitHub attestations, binary installation, and tag or manual +[Release instructions](docs/src/development/releases.md) cover attested +checksums and archives, binary installation, and tag or manual publication. Cross builds use `cargo zigbuild` and require the Rust target, `cargo-zigbuild`, diff --git a/docs/src/development/releases.md b/docs/src/development/releases.md index 5407a25..e1d5f91 100644 --- a/docs/src/development/releases.md +++ b/docs/src/development/releases.md @@ -18,48 +18,17 @@ Each release contains archives for these Rust targets: The workflow runs release-profile tests on each target, packages the binary and license, then runs the extracted binary's version and configuration checks. GitHub attestations identify the workflow that builds each archive. -The publisher checks those attestations, signs the complete SHA-256 manifest -with Minisign, and attests the signed release metadata. It downloads the +The publisher checks those attestations, creates the complete SHA-256 manifest, +and attests the manifest and source metadata. It downloads the draft release and verifies every asset before making the release public. -## Signing setup +## Release setup Create a `release` GitHub environment that allows the `main` branch and -`v*` tags. Keep the dedicated signing key in that environment. Build jobs -receive no Minisign private key. - -Generate the release key outside the checkout, with a private directory -and an offline backup: - -```sh -umask 077 -mkdir -p "$HOME/.config/postmaster-release" -minisign -G -W \ - -s "$HOME/.config/postmaster-release/minisign.key" \ - -p "$HOME/.config/postmaster-release/minisign.pub" -``` - -The unattended signer uses a key without a passphrase. GitHub encrypts the -environment secret at rest. Configure the secret and public-key variable -without printing the private key: - -```sh -gh secret set MINISIGN_SECRET_KEY --repo beardedeagle/postmaster \ - --env release < "$HOME/.config/postmaster-release/minisign.key" -gh variable set MINISIGN_PUBLIC_KEY --repo beardedeagle/postmaster \ - --env release \ - --body "$(tail -n 1 "$HOME/.config/postmaster-release/minisign.pub")" -``` - -Publish the public key through a trusted channel before the first release. -Consumers must establish trust in that key independently of the files they -are about to verify. A public key downloaded alongside an archive does not -establish who signed it. Publication fails when either signing input is -missing or the public key does not match the private key. - -The signing job can use the release key. A compromised signing workflow can -therefore sign a malicious release; signatures do not replace source review -or the workflow's source restrictions. +`v*` tags. GitHub signs attestations using the workflow's OpenID Connect +identity. No release signing secret or public-key configuration is required. +Verification trusts GitHub's identity for this repository and release workflow; +attestations do not replace source review or the workflow's source restrictions. ## Publish a version @@ -82,33 +51,38 @@ a published version tag or overwrite its assets. The workflow marks tags with a prerelease suffix as prereleases. Pull requests exercise source validation, release tooling and all five -builds. They upload preview archives without signing, attesting or publishing +builds. They upload preview archives without attesting or publishing a release. Local recipes are `just release-test` and -`just release-build `; Python 3.11 or newer and Minisign are required +`just release-build `; Python 3.11 or newer is required for the release-tool tests. ## Verify and install -Set `POSTMASTER_RELEASE_PUBLIC_KEY` to the independently trusted public key. -Then download, verify and install the selected archive. This example selects -Apple Silicon. The subshell stops on the first failed command, before -extraction or installation: +Install and authenticate the GitHub CLI, then download, verify and install +the selected archive. Verification accepts this repository's release workflow +on `main` or a version tag, and rejects pull-request and feature-branch +identities. This example selects Apple Silicon. The subshell stops on the +first failed command, before extraction or installation: ```sh ( set -eu version=v0.1.0 + identity='^https://github\.com/beardedeagle/postmaster/\.github/workflows/release\.yml@refs/(heads/main|tags/v[^/]+)$' archive="postmaster-${version}-aarch64-apple-darwin.tar.gz" base="https://github.com/beardedeagle/postmaster/releases/download/${version}" curl --fail --location --remote-name "$base/$archive" curl --fail --location --remote-name "$base/SHA256SUMS" - curl --fail --location --remote-name "$base/SHA256SUMS.minisig" - minisign -V -H -P "$POSTMASTER_RELEASE_PUBLIC_KEY" -m SHA256SUMS + gh attestation verify SHA256SUMS --repo beardedeagle/postmaster \ + --signer-workflow beardedeagle/postmaster/.github/workflows/release.yml \ + --cert-identity-regex "$identity" \ + --deny-self-hosted-runners awk -v file="$archive" '$2 == file { print }' SHA256SUMS > selected.sha256 test "$(wc -l < selected.sha256 | tr -d ' ')" = 1 shasum -a 256 -c selected.sha256 gh attestation verify "$archive" --repo beardedeagle/postmaster \ --signer-workflow beardedeagle/postmaster/.github/workflows/release.yml \ + --cert-identity-regex "$identity" \ --deny-self-hosted-runners tar -xzf "$archive" postmaster LICENSE mkdir -p "$HOME/.local/bin" @@ -117,13 +91,13 @@ extraction or installation: ``` `release.json` records the tagged source commit and complete target set. -Its checksum is covered by the same signed manifest. A manual run's +Its checksum is covered by the same attested manifest. A manual run's attestation identifies its triggering `main` revision; `release.json` identifies the selected tagged source revision. macOS binaries have no Apple Developer ID signature or notarization. -Minisign and attestations provide release authenticity and build provenance; -they do not satisfy Gatekeeper. `curl` downloads and local builds generally +Attestations provide release authenticity and build provenance; they do not +satisfy Gatekeeper. `curl` downloads and local builds generally avoid browser-applied quarantine. Browser downloads can still prompt or be blocked. The workflow does not disable Gatekeeper or remove quarantine.