release_tag.py
python
sha256:ec55e4f4980249bb2c95c8c0615a40a9ded3e1eb1c181fe3de7cefbd8298ff0d
feat(release): #275 safeguard — prove a signed tag can be m…
Sonnet 5.5
patch
7 days ago
| 1 | """Tag a published Muse CLI release at the exact revision its release record names (musehub#275). |
| 2 | |
| 3 | ``deploy/activate_muse_release.sh`` used to run ``muse tag add <tag>`` with no revision (so: whatever the checkout's HEAD |
| 4 | was by then), unsigned, and to treat any failure as a warning after the release was live. Three properties of the CLI make |
| 5 | that worse than it reads: ``tag add`` *overwrites* an existing tag, ``--sign`` without a signing identity only warns and |
| 6 | writes an unsigned tag (exit 0), and HEAD moves. So this step decides everything itself and verifies the result: |
| 7 | |
| 8 | ``check`` (read-only; the script runs it *before* the pointer moves) |
| 9 | 1. the release record for ``--version`` (bucket ``releases/<version>.json``) exists, describes ``--sha256``, and names a |
| 10 | ``source_revision``; that revision is the only commit that is ever tagged; |
| 11 | 2. ``muse verify-commit --strict`` accepts that revision in the Muse repository (present, signed, signature valid); |
| 12 | 3. the SemVer tag derived from the version (``deploy/pep440_to_semver_tag.py``) has a form (no dev/post/local build); |
| 13 | 4. an existing tag of that name must already point at the revision and carry a valid signature; any other existing |
| 14 | tag is a conflict and is refused, never moved. |
| 15 | |
| 16 | ``preflight`` (the operator's repository is only read; the script runs it *before* the pointer moves, instead of ``check``) |
| 17 | ``check``, then the signing capability: can this operator make a signed tag at all? ``tag add --sign`` with no identity |
| 18 | does not fail (it warns and writes an unsigned tag), so the only honest test is to make one. The probe does that in a |
| 19 | throwaway repository created for the purpose, configured with the operator repository's ``[hub] url`` (rc20 looks the |
| 20 | signing identity up by hub), and requires ``tag verify`` to report it signed and valid. No ref in the operator's |
| 21 | repository can move. Refused: no hub URL, no usable identity, a one-shot ``MUSE_AGENT_KEY_FD`` (the probe would spend |
| 22 | the key the real tag needs after activation). |
| 23 | |
| 24 | ``apply`` (after activation and the smoke test) |
| 25 | runs ``check``; if the tag is absent, ``muse tag add <tag> <revision> --sign``; then verifies the tag that is now there |
| 26 | (``tag read``: the revision; ``tag verify``: signed and valid). Any deviation exits non-zero. A tag this step created but |
| 27 | could not verify is left in place for the operator to inspect; nothing is deleted or force-moved. It does not probe: |
| 28 | after activation the real tag is the test, and a second probe would only add a way to fail late. |
| 29 | |
| 30 | Nothing here pushes a tag or touches a remote. |
| 31 | """ |
| 32 | from __future__ import annotations |
| 33 | |
| 34 | import argparse |
| 35 | import json |
| 36 | import os |
| 37 | import subprocess |
| 38 | import sys |
| 39 | import tempfile |
| 40 | from collections.abc import Callable, Mapping |
| 41 | from pathlib import Path |
| 42 | from typing import Any |
| 43 | |
| 44 | from packaging.version import Version |
| 45 | |
| 46 | from deploy.pep440_to_semver_tag import pep440_to_semver_tag |
| 47 | from deploy.release_provenance import ProvenanceError |
| 48 | from deploy.release_safety import DirStorage, ReleaseSafetyError, S3Storage, Storage, release_source_revision |
| 49 | |
| 50 | Runner = Callable[..., "subprocess.CompletedProcess[str]"] |
| 51 | |
| 52 | # The tag the capability probe signs, in its own scratch repository only: a valid SemVer tag name that no release can use. |
| 53 | PROBE_TAG = "v0.0.0-capability-probe" |
| 54 | |
| 55 | |
| 56 | class ReleaseTagError(Exception): |
| 57 | """The release cannot be tagged, or the tag that exists is not the verified one.""" |
| 58 | |
| 59 | |
| 60 | def tag_for(version: str) -> str: |
| 61 | """The SemVer tag for a release version; a version with no tag form is refused, never mapped to a nearby tag.""" |
| 62 | try: |
| 63 | v = Version(version) |
| 64 | # the tag converter before VER-1 mapped a dev build to the *stable* tag (0.2.0.dev1 -> v0.2.0); never let that through |
| 65 | if v.dev is not None or v.post is not None or v.local is not None or v.epoch: |
| 66 | raise ValueError(f"{version!r} is a dev, post-release, local or epoch version") |
| 67 | return pep440_to_semver_tag(version) |
| 68 | except ValueError as exc: # InvalidVersion is a ValueError |
| 69 | raise ReleaseTagError(f"{version}: no release tag form ({exc})") from exc |
| 70 | |
| 71 | |
| 72 | def _muse(muse: str, repo: Path, args: list[str], runner: Runner) -> tuple[int, dict[str, Any] | None]: |
| 73 | argv = [muse, "-C", str(repo), *args, "--json"] |
| 74 | try: |
| 75 | proc = runner(argv, capture_output=True, text=True, timeout=120, check=False) |
| 76 | except (OSError, subprocess.SubprocessError) as exc: |
| 77 | raise ReleaseTagError(f"could not run {muse}: {exc}") from exc |
| 78 | try: |
| 79 | data = json.loads(proc.stdout) if proc.stdout.strip() else None |
| 80 | except ValueError: |
| 81 | data = None |
| 82 | return proc.returncode, data if isinstance(data, dict) else None |
| 83 | |
| 84 | |
| 85 | def _verify_commit(muse: str, repo: Path, revision: str, runner: Runner) -> None: |
| 86 | code, data = _muse(muse, repo, ["verify-commit", "--strict", revision], runner) |
| 87 | if code != 0 or data is None or data.get("valid") is not True or data.get("commit_id") != revision: |
| 88 | raise ReleaseTagError(f"source revision {revision} is not a strictly verified signed commit in {repo} (verify-commit exit {code})") |
| 89 | |
| 90 | |
| 91 | def _existing_tag(muse: str, repo: Path, tag: str, revision: str, runner: Runner) -> bool: |
| 92 | """True if *tag* exists at *revision*; False if absent; a tag anywhere else is a conflict.""" |
| 93 | code, data = _muse(muse, repo, ["tag", "read", tag], runner) |
| 94 | if code != 0: |
| 95 | if data is not None and data.get("error") == "tag_not_found": |
| 96 | return False |
| 97 | raise ReleaseTagError(f"muse tag read {tag} failed (exit {code})") |
| 98 | at = None if data is None else data.get("commit_id") |
| 99 | if at != revision: |
| 100 | raise ReleaseTagError(f"tag {tag} already exists at {at}, not at the release's source revision {revision}; refusing to move it") |
| 101 | return True |
| 102 | |
| 103 | |
| 104 | def _verify_tag(muse: str, repo: Path, tag: str, runner: Runner) -> None: |
| 105 | code, data = _muse(muse, repo, ["tag", "verify", tag], runner) |
| 106 | if code != 0 or data is None or data.get("signed") is not True or data.get("valid") is not True: |
| 107 | raise ReleaseTagError(f"tag {tag} is not signed with a valid signature (tag verify exit {code}); it was left in place, unchanged") |
| 108 | |
| 109 | |
| 110 | def check(storage: Storage, version: str, sha256: str, repo: Path, *, muse: str = "muse", runner: Runner = subprocess.run) -> dict[str, Any]: |
| 111 | """Everything that can be established before the release goes live. Read-only.""" |
| 112 | try: |
| 113 | revision = release_source_revision(storage, version, sha256) |
| 114 | except (ReleaseSafetyError, ProvenanceError) as exc: |
| 115 | raise ReleaseTagError(f"release record for {version}: {exc}") from exc |
| 116 | tag = tag_for(version) |
| 117 | _verify_commit(muse, repo, revision, runner) |
| 118 | present = _existing_tag(muse, repo, tag, revision, runner) |
| 119 | if present: |
| 120 | _verify_tag(muse, repo, tag, runner) |
| 121 | return {"version": version, "tag": tag, "source_revision": revision, "tag_present": present} |
| 122 | |
| 123 | |
| 124 | def capability_check( |
| 125 | repo: Path, *, muse: str = "muse", runner: Runner = subprocess.run, environ: Mapping[str, str] | None = None |
| 126 | ) -> dict[str, Any]: |
| 127 | """Prove this operator can make a signed tag, without writing to *repo* (only ``config get`` runs there). |
| 128 | |
| 129 | The proof is a real signed tag in a throwaway repository that carries *repo*'s hub URL, which is what rc20 resolves the |
| 130 | signing identity from. ``tag add --sign`` exits 0 with no identity (unsigned tag), so success is ``tag verify`` reporting |
| 131 | the probe signed and valid, never the exit code of ``tag add``. |
| 132 | """ |
| 133 | env = os.environ if environ is None else environ |
| 134 | if env.get("MUSE_AGENT_KEY_FD", "").strip(): |
| 135 | raise ReleaseTagError( |
| 136 | "MUSE_AGENT_KEY_FD is set: that key descriptor is read once and closed, so a capability probe would spend the key the " |
| 137 | "release tag needs after activation. Release with an identity in ~/.muse/identity.toml, without MUSE_AGENT_KEY_FD." |
| 138 | ) |
| 139 | code, data = _muse(muse, repo, ["config", "get", "hub.url"], runner) |
| 140 | hub = data.get("value") if code == 0 and data is not None else None |
| 141 | if not isinstance(hub, str) or not hub.strip(): |
| 142 | raise ReleaseTagError(f"no hub url is configured in {repo} (muse config get hub.url, exit {code}); a signing identity cannot be resolved without one") |
| 143 | with tempfile.TemporaryDirectory(prefix="musehub-release-tag-probe-") as tmp: |
| 144 | scratch = Path(tmp) |
| 145 | for label, args in ( |
| 146 | ("init", ["init"]), |
| 147 | ("config set", ["config", "set", "hub.url", hub]), |
| 148 | ("commit", ["commit", "--allow-empty", "-m", "capability probe"]), |
| 149 | ): |
| 150 | code, _ = _muse(muse, scratch, args, runner) |
| 151 | if code != 0: |
| 152 | raise ReleaseTagError(f"capability probe: muse {label} failed in the scratch repository (exit {code})") |
| 153 | code, data = _muse(muse, scratch, ["tag", "add", PROBE_TAG, "--sign", "--message", "capability probe"], runner) |
| 154 | if code != 0 or data is None or data.get("status") != "tagged": |
| 155 | raise ReleaseTagError(f"capability probe: muse tag add failed in the scratch repository (exit {code})") |
| 156 | code, data = _muse(muse, scratch, ["tag", "verify", PROBE_TAG], runner) |
| 157 | if code != 0 or data is None or data.get("signed") is not True or data.get("valid") is not True: |
| 158 | raise ReleaseTagError( |
| 159 | f"no usable signing identity for {hub}: a probe tag signed with --sign came out unsigned or invalid (tag verify exit {code}). " |
| 160 | "Set up an identity (muse auth keygen && muse auth register) before releasing; no release tag can be signed without one" |
| 161 | ) |
| 162 | return {"signing_capable": True, "signer_public_key": data.get("signer_public_key")} |
| 163 | |
| 164 | |
| 165 | def preflight( |
| 166 | storage: Storage, version: str, sha256: str, repo: Path, *, muse: str = "muse", runner: Runner = subprocess.run, |
| 167 | environ: Mapping[str, str] | None = None, |
| 168 | ) -> dict[str, Any]: |
| 169 | """Everything that must hold before the pointer moves: ``check`` (verified exact source revision, no conflicting tag), |
| 170 | then the signing capability. A refusal in ``check`` does no probing.""" |
| 171 | state = check(storage, version, sha256, repo, muse=muse, runner=runner) |
| 172 | return {**state, **capability_check(repo, muse=muse, runner=runner, environ=environ)} |
| 173 | |
| 174 | |
| 175 | def apply(storage: Storage, version: str, sha256: str, repo: Path, *, muse: str = "muse", runner: Runner = subprocess.run) -> dict[str, Any]: |
| 176 | """Create the signed tag if absent, then verify it. Idempotent: a verified tag already at the revision is success.""" |
| 177 | state = check(storage, version, sha256, repo, muse=muse, runner=runner) |
| 178 | tag, revision = state["tag"], state["source_revision"] |
| 179 | if not state["tag_present"]: |
| 180 | code, data = _muse(muse, repo, ["tag", "add", tag, revision, "--sign", "--message", f"release {version}"], runner) |
| 181 | if code != 0 or data is None or data.get("status") != "tagged" or data.get("commit_id") != revision: |
| 182 | raise ReleaseTagError(f"muse tag add {tag} {revision} did not report a new tag at that revision (exit {code})") |
| 183 | if not _existing_tag(muse, repo, tag, revision, runner): |
| 184 | raise ReleaseTagError(f"tag {tag} is not present after tag add") |
| 185 | _verify_tag(muse, repo, tag, runner) |
| 186 | return {**state, "tag_present": True, "created": not state["tag_present"]} |
| 187 | |
| 188 | |
| 189 | def main(argv: list[str] | None = None, *, runner: Runner = subprocess.run) -> int: |
| 190 | parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) |
| 191 | where = parser.add_mutually_exclusive_group(required=True) |
| 192 | where.add_argument("--bucket", help="S3 release bucket") |
| 193 | where.add_argument("--dir", type=Path, help="local directory acting as the bucket (rehearsal)") |
| 194 | parser.add_argument("command", choices=("check", "preflight", "apply")) |
| 195 | parser.add_argument("--version", required=True) |
| 196 | parser.add_argument("--sha256", required=True) |
| 197 | parser.add_argument("--muse-repo", type=Path, required=True) |
| 198 | parser.add_argument("--muse", default="muse", help="the muse executable (default: muse on PATH)") |
| 199 | args = parser.parse_args(argv) |
| 200 | storage: Storage = S3Storage(args.bucket) if args.bucket else DirStorage(args.dir) |
| 201 | try: |
| 202 | result = {"check": check, "preflight": preflight, "apply": apply}[args.command]( |
| 203 | storage, args.version, args.sha256, args.muse_repo, muse=args.muse, runner=runner |
| 204 | ) |
| 205 | except ReleaseTagError as exc: |
| 206 | print(f"release tag: {exc}", file=sys.stderr) |
| 207 | return 1 |
| 208 | print(json.dumps(result, sort_keys=True)) |
| 209 | return 0 |
| 210 | |
| 211 | |
| 212 | if __name__ == "__main__": |
| 213 | raise SystemExit(main()) |
File History
2 commits
sha256:ec55e4f4980249bb2c95c8c0615a40a9ded3e1eb1c181fe3de7cefbd8298ff0d
feat(release): #275 safeguard — prove a signed tag can be m…
Sonnet 5.5
patch
7 days ago
sha256:0ddcb29475cfe996169320691ffb2c5705e510191a4a944487df867959d81b36
fix(release): #275 tag the verified source revision, signed…
Sonnet 5.5
minor
⚠
7 days ago