gabriel / musehub public
release_tag.py python
213 lines 12.3 KB
Raw
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