feat(catalog-console): a keys status command, and complete rotation without a red main (#62, #68)

Two problems from issue #68's follow-up review:

1. The maintainer -- the only person who will ever use this tool -- cannot
   reliably tell which of the two signing keys is which or what state
   either is in. He already pasted a private key into a chat window
   because a prompt was ambiguous. That's a defect in this tool, not user
   error.

2. PR #71 rotates bcc_core.CATALOG_PUBKEYS, which makes
   data/catalog.json.sig (signed by the retired key) stop verifying and
   the CI catalog-signature job go red. The Console could previously only
   load/sign against `main`, so the only way through was to merge a red
   PR and fix main afterwards -- normalizing exactly the alarm fatigue
   this whole design exists to prevent.

Task 1 -- `python catalog_console.py keys`:
  A plain-English-first status report for BOTH keys: purpose, where the
  private half lives, whether it exists locally, its fingerprint, whether
  that fingerprint matches every place its public half is expected to be
  committed (bcc_core.CATALOG_PUBKEYS, ci.yml's trust anchor, and
  scripts/sign_checksums.RELEASE_PUBKEYS -- checked independently, since
  issue #68 finding 4 was exactly bcc_core.py and ci.yml silently
  drifting apart), and whether data/catalog.json.sig currently verifies --
  ending with the exact command to run next. Needs no passphrase and never
  touches private key bytes: a plaintext public-key cache
  (store_public_key/load_public_key) is written alongside the existing
  encrypted private blob at keygen time, precisely so this command can
  report a fingerprint without decrypting anything.

  The status/report logic (key_status, render_key_status_report,
  recommend_next_steps, fingerprint_pubkey, extract_pubkey_list_literal,
  extract_ci_trust_anchor_pubkey) is pure and lives in catalog_review.py;
  cmd_keys in catalog_console.py is a thin printer over it, per the
  project's existing pure-core/thin-GUI split.

Task 2 -- rotation completable without a red main:
  ReviewWindow now offers a "current branch" source (auto-detected via
  `current_branch()`, or --ref to name one explicitly) alongside "main"
  and open PRs. Loading it runs the exact same diff-against-last-signed /
  rotation-detection logic "main" always used (_load_own_ref, extracted
  from the old hardcoded-to-main _on_load), just parameterized on the
  ref. Signing now pushes to session.loaded_ref, never a hardcoded "main"
  (commit_and_push_signed_catalog's branch param was already there --
  only the call site was wrong). The ref-list computation itself is a
  pure function (compute_own_refs) so this seam is unit-testable without
  git or Qt. None of can_sign()'s guards (empty-diff, acknowledge-all,
  blocking-risk, TOCTOU) were touched.

  This lets a rotation branch be reviewed, re-attested (every entry,
  since the new key never vouched for any of them -- issue #68 finding 5
  follow-up), signed, and pushed to ITS OWN branch before it's ever
  merged.

Task 3 -- label the keys everywhere:
  PassphraseDialog now shows which key (CATALOG vs RELEASE) and its
  fingerprint before the passphrase field, both in its window title and
  its prompt text -- the exact ambiguity that led to a private key being
  pasted into a chat window. cmd_keygen's stored-key confirmation now
  reads "CATALOG private key encrypted..." / "RELEASE private key
  encrypted..." instead of a capitalized-lowercase kind. The reattest
  banner now says "CATALOG signing key" / "CATALOG key" throughout
  instead of "the key".

PySide6's import is now guarded (try/except -> _PYSIDE6_AVAILABLE) and
every GUI class definition that depends on it moved under
`if _PYSIDE6_AVAILABLE:`. `keygen`, `show-seed-b64`, and the new `keys`
command have no GUI dependency and now work (and are testable) in an
environment without PySide6 -- which is exactly this repo's own `test`
CI job (pytest + cryptography only, no PySide6). `gui` fails with a clear
message instead of an ImportError stack trace if it's missing.

Tests: 26 new pure-function tests in tests/test_catalog_review.py
(fingerprint_pubkey, extract_pubkey_list_literal,
extract_ci_trust_anchor_pubkey, key_status, recommend_next_steps,
render_key_status_report) and a new tests/test_catalog_console_git.py
(14 tests) covering compute_own_refs, current_branch,
commit_and_push_signed_catalog's branch targeting, and
catalog_sig_status_on_disk against real local git repos -- importing
catalog_console.py directly, proving it works without PySide6. 400
passed, 1 skipped (pre-existing). ruff check / ruff format --check clean.

.github/workflows/ci.yml

@@ -62,8 +62,115 @@ jobs:
 
       # bcc_core has no GUI imports, so the test suite needs no PySide6 —
       # keeps CI fast and avoids Qt system-library headaches on the runner.
+      # cryptography is for tests/test_checksums.py (release signing helper).
       - name: Install test dependencies
-        run: pip install pytest
+        run: pip install pytest cryptography
 
       - name: Run tests
         run: python -m pytest -v
+
+  # ── Catalog signature gate (#61) ─────────────────────────────────────────
+  #
+  # data/catalog.json is a list of command+args entries that BCC writes into
+  # the user's Claude config, which Claude then EXECUTES. The catalog is only
+  # trusted if it carries a valid Ed25519 signature from the maintainer key.
+  #
+  # The threat this gate exists for is NOT an outsider pushing to the repo —
+  # it is the maintainer merging a friendly-looking PR without really reading
+  # it. A contributor can change catalog.json but cannot produce a matching
+  # signature, so a blindly-merged PR lands here as a RED BUILD within a
+  # minute, instead of quietly riding into the next release.
+  #
+  # Public-key verification only. No secret is used or needed.
+  catalog-signature:
+    name: Catalog signature
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install cryptography
+
+      # 🔴 TRUST ANCHOR — issue #68 finding 4.
+      #
+      # This step used to do `import bcc_core as c` FROM THE CHECKED-OUT PR
+      # BRANCH and verify the catalog against c.CATALOG_PUBKEYS — i.e. it
+      # trusted the public key shipped in the very diff it was reviewing. A
+      # PR that changed data/catalog.json AND bcc_core.CATALOG_PUBKEYS (to
+      # an attacker key, with a matching signature produced by the attacker's
+      # matching private key) went green, because there was nothing outside
+      # the PR's own content to check the key against. The gate's whole
+      # point is catching a friendly-looking PR the maintainer merges
+      # without really reading it — and that hole made it a two-file diff.
+      #
+      # EXPECTED_CATALOG_PUBKEY_B64 below is hardcoded HERE, in the workflow
+      # file, independent of whatever bcc_core.py says on the PR branch. It
+      # is intentionally the only line in this step that matters for
+      # security review: changing it changes what this gate is willing to
+      # trust. THIS CONSTANT IS A TRUST ANCHOR. A PR that changes this line
+      # in the same diff as a catalog change is exactly the attack this gate
+      # exists to prevent — review a change to this line on its own,
+      # never bundled with a catalog update.
+      #
+      # NOTE for the next key rotation: update EXPECTED_CATALOG_PUBKEY_B64
+      # below to the new key's base64 form, as its own reviewed change.
+      - name: Verify data/catalog.json.sig
+        env:
+          EXPECTED_CATALOG_PUBKEY_B64: "0s24PmkZcTT5yxNDdyTPHl5fyxArrHNPJKBjnXoQd8k="
+        run: |
+          python - <<'PY'
+          import base64, os, pathlib, sys
+          import bcc_core as c
+
+          expected_pubkey_b64 = os.environ["EXPECTED_CATALOG_PUBKEY_B64"]
+
+          raw = pathlib.Path("data/catalog.json").read_bytes()
+          sig_path = pathlib.Path("data/catalog.json.sig")
+
+          if not sig_path.exists():
+              sys.exit("FAIL: data/catalog.json.sig is missing. The catalog must be "
+                       "signed via the Catalog Console (#62) before it can land.")
+
+          if b"\x00" * 32 in c.CATALOG_PUBKEYS:
+              sys.exit("FAIL: CATALOG_PUBKEYS still holds the placeholder key.")
+
+          # Trust anchor check FIRST, before verifying anything against
+          # bcc_core.CATALOG_PUBKEYS: a PR is not allowed to bring its own
+          # key. CATALOG_PUBKEYS on the checked-out branch must be EXACTLY
+          # the key(s) this workflow file itself expects -- no more, no
+          # fewer, no substitutions.
+          actual_pubkeys_b64 = [base64.b64encode(k).decode() for k in c.CATALOG_PUBKEYS]
+          if actual_pubkeys_b64 != [expected_pubkey_b64]:
+              sys.exit(
+                  "FAIL: bcc_core.CATALOG_PUBKEYS on this branch does not match the "
+                  "trust anchor hardcoded in .github/workflows/ci.yml.\n"
+                  f"  expected: {[expected_pubkey_b64]}\n"
+                  f"  actual:   {actual_pubkeys_b64}\n"
+                  "\n"
+                  "This PR is changing (or has changed) the catalog signing key. That "
+                  "change must be reviewed on its own, separately from any catalog "
+                  "content change, and the workflow's EXPECTED_CATALOG_PUBKEY_B64 "
+                  "updated deliberately -- not accepted because it happened to match "
+                  "whatever bcc_core.py says on this branch."
+              )
+
+          if not c.verify_catalog_signature(raw, sig_path.read_bytes(), c.CATALOG_PUBKEYS):
+              sys.exit(
+                  "FAIL: data/catalog.json does NOT match its signature.\n"
+                  "\n"
+                  "The catalog changed without being re-signed. Either someone edited\n"
+                  "it directly (a PR you merged?), or a signing pass was forgotten.\n"
+                  "Re-review and re-sign with the Catalog Console — do not bypass this."
+              )
+
+          problems = c.validate_catalog(c.load_catalog(raw))
+          if problems:
+              sys.exit("FAIL: catalog failed validation:\n  " + "\n  ".join(problems))
+
+          print("OK: catalog signature verifies, the pubkey matches the CI trust anchor, "
+                "and the catalog validates clean.")
+          PY

.github/workflows/release.yml

@@ -95,6 +95,92 @@ jobs:
           name: ${{ matrix.artifact }}
           path: ${{ matrix.artifact }}
 
+  # ── Signing-key smoke test (workflow_dispatch only) ─────────────────────
+  #
+  # The Publish job is gated on a tag, so a manual run never exercises the
+  # signing step — which means a wrong/missing RELEASE_SIGNING_KEY secret
+  # would only be discovered at the worst possible moment: during a real
+  # release. This job signs a throwaway manifest with the secret and verifies
+  # the result against scripts/sign_checksums.RELEASE_PUBKEYS.
+  #
+  # IMPORTANT (issue #68 finding 5): this must verify against the RELEASE
+  # public key, never bcc_core.CATALOG_PUBKEYS. The catalog key is the
+  # offline, maintainer-held root of trust for what BCC executes; it must
+  # NEVER be compared against a value that lives in a CI secret, because
+  # that comparison is itself a way to smuggle a catalog-trusted key through
+  # CI review ("does this repo secret match the catalog key" is a question
+  # this workflow must never even ask). The release key is a SEPARATE
+  # keypair, generated via `catalog_console.py keygen --release`, that only
+  # ever signs release SHA256SUMS manifests -- a CI/secret compromise burns
+  # this key, not the catalog key.
+  #
+  # It proves the two halves of the RELEASE keypair actually match, without
+  # publishing anything. Run it from the Actions tab after setting or
+  # rotating the secret.
+  signing-smoke-test:
+    name: Signing key smoke test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install cryptography
+
+      - name: Sign a throwaway manifest and verify against the RELEASE pubkey
+        env:
+          RELEASE_SIGNING_KEY: ${{ secrets.RELEASE_SIGNING_KEY }}
+        run: |
+          if [ -z "$RELEASE_SIGNING_KEY" ]; then
+            echo "FAIL: RELEASE_SIGNING_KEY secret is not set."
+            echo "Generate the RELEASE key (NOT the catalog key) with:"
+            echo "    python catalog_console.py keygen --release"
+            echo "then add its seed under Settings -> Actions -> Secrets, via:"
+            echo "    python catalog_console.py show-seed-b64 --release"
+            exit 1
+          fi
+          mkdir -p smoke && echo "smoke test payload" > smoke/hello.txt
+          python3 scripts/sign_checksums.py generate smoke --out smoke/SHA256SUMS
+          python3 scripts/sign_checksums.py sign --sums smoke/SHA256SUMS --out smoke/SHA256SUMS.sig
+          python - <<'PY'
+          import pathlib, sys
+          from scripts.sign_checksums import RELEASE_PUBKEYS, verify_checksums_against_any
+
+          # Deliberately does NOT import bcc_core / CATALOG_PUBKEYS at all --
+          # this smoke test must never be able to compare the CI secret
+          # against the catalog's root of trust (issue #68 finding 5). Only
+          # RELEASE_PUBKEYS (scripts/sign_checksums.py) is a legitimate
+          # target for a CI-resident key.
+          if not RELEASE_PUBKEYS:
+              sys.exit(
+                  "FAIL: scripts/sign_checksums.RELEASE_PUBKEYS is empty.\n"
+                  "\n"
+                  "Generate the release keypair with:\n"
+                  "    python catalog_console.py keygen --release\n"
+                  "then paste the printed public key into RELEASE_PUBKEYS in\n"
+                  "scripts/sign_checksums.py and commit that change."
+              )
+
+          sums = pathlib.Path("smoke/SHA256SUMS").read_text()
+          sig = pathlib.Path("smoke/SHA256SUMS.sig").read_bytes()
+
+          if not verify_checksums_against_any(RELEASE_PUBKEYS, sums, sig):
+              sys.exit(
+                  "FAIL: the signature produced by RELEASE_SIGNING_KEY does NOT verify\n"
+                  "against any key in scripts/sign_checksums.RELEASE_PUBKEYS.\n"
+                  "\n"
+                  "The secret and the shipped release public key are different keypairs.\n"
+                  "Downloaders would reject every signature this CI produces. Re-copy the\n"
+                  "seed from `catalog_console.py show-seed-b64 --release`, or update\n"
+                  "RELEASE_PUBKEYS with the matching public key."
+              )
+          print("OK: RELEASE_SIGNING_KEY matches a key in RELEASE_PUBKEYS.")
+          PY
+
   # ── Create GitHub Release with all three artifacts ──────────────────────
 
   release:
@@ -107,11 +193,76 @@ jobs:
       contents: write
 
     steps:
+      # Needed for scripts/sign_checksums.py — the release job otherwise
+      # only downloads build artifacts, it doesn't check out the repo.
+      - name: Checkout
+        uses: actions/checkout@v4
+
       - name: Download all artifacts
         uses: actions/download-artifact@v3
         with:
           path: artifacts
 
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # download-artifact@v3 nests each artifact under a directory named
+      # after it (artifacts/<name>/<name>). Flatten into one directory so
+      # SHA256SUMS lists plain filenames, matching what `sha256sum -c`
+      # expects when run from inside an extracted release download.
+      - name: Collect release files
+        run: |
+          mkdir -p release-files
+          find artifacts -type f -exec cp {} release-files/ \;
+          ls -la release-files
+
+      - name: Generate SHA256SUMS
+        run: python3 scripts/sign_checksums.py generate release-files --out release-files/SHA256SUMS
+
+      # ── Sign the checksum manifest (best-effort) ──────────────────────
+      #
+      # BCC binaries are not code-signed (no budget for a paid cert). This
+      # is the free half: a checksum manifest, detached-signed with
+      # Ed25519, so a tampered download is detectable by anyone who
+      # checks. It does NOT remove Gatekeeper/SmartScreen warnings.
+      #
+      # The private key is a repo secret (RELEASE_SIGNING_KEY, base64 raw
+      # Ed25519 seed) for the RELEASE key -- a SEPARATE keypair from the
+      # catalog key, generated via `python catalog_console.py keygen
+      # --release` (issue #68 finding 5; #62). This key is intentionally
+      # CI-resident and signs ONLY this checksum manifest; it is never
+      # trusted to sign data/catalog.json. If it's not set, we still
+      # publish the release — just without a .sig — rather than fail the
+      # release outright.
+      - name: Check for signing key
+        id: signing
+        run: |
+          if [ -n "${{ secrets.RELEASE_SIGNING_KEY }}" ]; then
+            echo "has_key=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_key=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Install signing dependencies
+        if: steps.signing.outputs.has_key == 'true'
+        run: pip install cryptography
+
+      - name: Sign SHA256SUMS
+        if: steps.signing.outputs.has_key == 'true'
+        env:
+          RELEASE_SIGNING_KEY: ${{ secrets.RELEASE_SIGNING_KEY }}
+        run: |
+          python3 scripts/sign_checksums.py sign \
+            --sums release-files/SHA256SUMS \
+            --out release-files/SHA256SUMS.sig
+
+      - name: Warn — release will be unsigned
+        if: steps.signing.outputs.has_key != 'true'
+        run: |
+          echo "::warning::RELEASE_SIGNING_KEY secret is not set — this release is being published WITHOUT a signed SHA256SUMS.sig. Generate the RELEASE key (python catalog_console.py keygen --release) and add its seed (python catalog_console.py show-seed-b64 --release) as this secret before the next tag."
+
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
@@ -119,7 +270,9 @@ jobs:
           draft: false
           prerelease: false
           generate_release_notes: false
-          files: artifacts/**/*
+          files: |
+            artifacts/**/*
+            release-files/SHA256SUMS*
           body: |
             ## Better Claude Config ${{ github.ref_name }}
 
@@ -139,5 +292,8 @@ jobs:
             xattr -cr /Applications/BetterClaudeConfig.app
             ```
 
+            ### Verifying your download
+            Every release includes `SHA256SUMS` (and, when the signing key is configured, a detached `SHA256SUMS.sig`). See [Verifying your download](https://git.avezzano.io/the_og/better-claude-config#verifying-your-download) in the README for commands. This proves you got the file we published — it does not remove Gatekeeper/SmartScreen warnings.
+
             ### Requirements
             No Python installation needed — the app is self-contained.

README.md

@@ -19,6 +19,135 @@ Pre-built self-contained binaries are attached to every [GitHub Release](../../r
 
 > **macOS Gatekeeper note:** the app is not notarized. On first launch, right-click → **Open**, or run `xattr -cr /Applications/BetterClaudeConfig.app` in a terminal.
 
+## Verifying your download
+
+BCC isn't code-signed — there's no budget for a paid certificate (macOS
+Developer ID, Windows Authenticode). Instead, every release publishes a
+`SHA256SUMS` file listing the checksum of each archive, detached-signed with
+Ed25519 as `SHA256SUMS.sig`. Both are attached to the release alongside the
+binaries.
+
+**What this proves:** the file you downloaded is byte-for-byte what we
+published, and the manifest itself was signed by our release key.
+
+**What this does NOT do:** it does not make the binary "safe," and it does
+**not** remove the macOS Gatekeeper or Windows SmartScreen warning — those
+are only suppressed by a paid OS-vendor certificate, which this project
+doesn't have. Verifying checksums is about detecting tampering in transit or
+on a mirror, not about vouching for the software.
+
+This manifest is signed with BCC's **release key**, which is a different
+key from the one that signs the MCP server catalog — see
+[Signing keys](#signing-keys) below for why, and for the public key value
+to use with `--pubkey-b64` below.
+
+### macOS / Linux
+
+```bash
+# From inside the folder you downloaded the release files into:
+sha256sum -c SHA256SUMS
+```
+
+If your `sha256sum` complains about missing files, download `SHA256SUMS`
+into the same directory as the archive you downloaded — it lists every
+platform's archive, and only the one(s) present will be checked.
+
+To also verify the manifest's signature (optional, requires Python +
+`pip install cryptography` and a checkout of this repo):
+
+```bash
+python3 scripts/sign_checksums.py verify \
+  --sums SHA256SUMS --sig SHA256SUMS.sig \
+  --pubkey-b64 "<the release public key from Signing keys, below>"
+```
+
+### Windows (PowerShell)
+
+```powershell
+Get-FileHash .\BetterClaudeConfig-Windows.zip -Algorithm SHA256
+```
+
+Compare the printed hash (case-insensitively) against the matching line in
+`SHA256SUMS`.
+
+### If a release has no `SHA256SUMS.sig`
+
+The signing key is a repo secret that has to be configured manually; if a
+release is missing the `.sig` file, the checksums themselves are still
+valid and safe to check against — the release workflow only skips signing,
+never checksum generation.
+
+## Signing keys
+
+BCC uses **two separate Ed25519 keypairs**, deliberately never the same
+key, because they protect different things and live in different places:
+
+| | Catalog key | Release key |
+|---|---|---|
+| Signs | `data/catalog.json` (the MCP server catalog every user's app trusts) | `SHA256SUMS` (the checksum manifest for release binaries) |
+| Verified by | `bcc_core.CATALOG_PUBKEYS` | `scripts/sign_checksums.RELEASE_PUBKEYS` |
+| Lives | Offline, passphrase-encrypted, maintainer's machine only (OS keychain or an encrypted file outside the repo — see the [Catalog Console](#files), issue #62) | A Gitea Actions repo secret, `RELEASE_SIGNING_KEY` — **intentionally CI-resident** |
+| Generated with | `python catalog_console.py keygen` | `python catalog_console.py keygen --release` |
+| Exported for CI with | *(never — there is no supported way to export this key)* | `python catalog_console.py show-seed-b64 --release` |
+
+**Confused about which key is which, or what state either is in?** Run:
+
+```bash
+python catalog_console.py keys
+```
+
+It needs no passphrase (it never touches private key bytes) and prints a
+plain-English report for both keys: where each private half lives, whether
+it's present on this machine, its fingerprint, whether that fingerprint
+matches what's actually committed in `bcc_core.py`, `ci.yml`'s trust
+anchor, and `scripts/sign_checksums.py`, and whether
+`data/catalog.json.sig` currently verifies — ending with the exact command
+to run next for whatever state it finds. This is the check that would have
+caught [issue #68](../../issues/68)'s finding 5 incident before it happened.
+
+**Why two keys:** the catalog key is the root of trust for what BCC
+actually *executes* on a user's machine — every `command`/`args` pair in
+the shipped catalog is only there because this key signed it. If that key
+and the release-checksum key were the same (as they briefly were — see
+[issue #68](../../issues/68)), then anything that can exfiltrate a Gitea
+Actions secret (a malicious workflow-file PR, a compromised runner, a leaky
+log) could sign a catalog every user's copy of BCC would trust, not just a
+checksum manifest. Splitting them means **a CI/secret compromise burns the
+release key, never the catalog key** — checksums for a future release could
+be forged, which is bad, but no attacker gains the ability to make BCC run
+arbitrary commands on installs that trust the catalog. That asymmetry is
+the entire point of having two keys instead of one.
+
+The catalog key is **never** meant to leave the maintainer's machine: it's
+generated, stored, unlocked, and used to sign entirely inside the Catalog
+Console (`catalog_console.py`), and `catalog_console.py show-seed-b64`
+refuses to run without `--release` specifically so the catalog seed can't
+be exported by habit or muscle memory.
+
+**Release signing public key** (Ed25519, base64, raw 32 bytes) — this is
+the RELEASE key, which signs `SHA256SUMS` (release checksums). It does
+**not** sign `data/catalog.json` and is not the key `bcc_core.CATALOG_PUBKEYS`
+trusts:
+
+```
+6BnPgJEHJFyVltFoLTCNadIsehjy00iiW8IRlC1TfhA=
+```
+
+The catalog public key (Ed25519, base64, raw 32 bytes) — this is the key
+that signs `data/catalog.json` and is trusted via `bcc_core.CATALOG_PUBKEYS`
+and the CI trust anchor in `.github/workflows/ci.yml`. It is listed here
+for completeness, not because you need it to verify a download — use the
+*release* key above for that:
+
+```
+0s24PmkZcTT5yxNDdyTPHl5fyxArrHNPJKBjnXoQd8k=
+```
+
+Both keys above were rotated 2026-07 — see [issue #68](../../issues/68)
+finding 5. The prior (shared) key is retired and is deliberately **not**
+kept in either trust list; retaining a burned key would defeat the point
+of rotating it.
+
 ## Run from source
 
 ```bash
@@ -92,6 +221,8 @@ file is also listed, marked *legacy*, so you can copy them over.
 - `test_core.py` — unit suite for the core (`python test_core.py`).
 - `bcc.spec` — PyInstaller build spec (cross-platform).
 - `scripts/build_icons.py` — regenerates `icons/app.icns` and `icons/app.ico` from source PNGs.
+- `scripts/sign_checksums.py` — generates and Ed25519-signs the release `SHA256SUMS` manifest (see [Verifying your download](#verifying-your-download)).
+- `catalog_console.py` / `catalog_review.py` — **maintainer-only**, never shipped to users (excluded from `bcc.spec`; see `tests/test_catalog_console_packaging.py`). The Catalog Console: review + sign `data/catalog.json` (against `main`, an open PR, or the branch you have checked out — `--ref <branch>` to be explicit, e.g. mid key-rotation, so a rotation can be signed and pushed to its own branch *before* it's merged, never forcing a red `main`), generate/manage both signing keys (`keygen`, `keygen --release`), and report on their status (`keys`, no passphrase needed) — see [Signing keys](#signing-keys).
 
 ## Building from source
 

bcc_core.py

@@ -13,6 +13,7 @@ in its original position.
 
 from __future__ import annotations
 
+import base64
 import contextlib
 import difflib
 import functools
@@ -2163,12 +2164,36 @@ def restart_claude_desktop() -> RestartResult:
 # is rejected by validate_catalog() regardless of how plausible it looks.
 CATALOG_ALLOWED_COMMANDS = frozenset({"npx", "uvx", "docker", "node", "python", "python3"})
 
+# Env var keys a catalog entry's config.env must never set. Every one of
+# these is a loader/interpreter override that lets a value walk straight
+# past CATALOG_ALLOWED_COMMANDS and the -e/--eval/-c deny-rule below: e.g.
+# NODE_OPTIONS="--require /tmp/x.js" turns an allowlisted `npx` entry into
+# arbitrary code execution without ever touching config.args, which is the
+# only field the allowlist/deny-rules/ASCII/secret checks used to cover.
+# Matched case-insensitively -- env keys are case-sensitive on POSIX, but a
+# `node_options` lookalike is exactly the kind of thing this must catch.
+CATALOG_DENIED_ENV_KEYS = frozenset(
+    {
+        "NODE_OPTIONS",
+        "PYTHONSTARTUP",
+        "PYTHONPATH",
+        "PYTHONHOME",
+        "LD_PRELOAD",
+        "LD_LIBRARY_PATH",
+        "DYLD_INSERT_LIBRARIES",
+        "DYLD_LIBRARY_PATH",
+        "BROWSER",
+        "PATH",
+        "NODE_REPL_EXTERNAL_MODULE",
+    }
+)
+
 # Ed25519 public keys allowed to sign a catalog, raw 32-byte form. A LIST
 # (not a single key) so keys can be rotated without bricking installs that
 # still trust an older key: verify_catalog_signature() accepts a match
 # against ANY key in this list.
 CATALOG_PUBKEYS: list[bytes] = [
-    b"\x00" * 32,  # TODO: real key from Catalog Console (#62)
+    base64.b64decode("0s24PmkZcTT5yxNDdyTPHl5fyxArrHNPJKBjnXoQd8k="),
 ]
 
 # Domain-separation prefix for the signed message. The signature covers
@@ -2188,6 +2213,36 @@ _CATALOG_SECRET_ARG_RE = re.compile(r"(?i)--api[-_]?key=|--token=|--password=")
 # <PLACEHOLDER>-style tokens the GUI must have the user fill in before Save.
 _PLACEHOLDER_RE = re.compile(r"<[^<>\s]+>")
 
+# A catalog entry's id becomes an mcpServers JSON key AND is interpolated
+# into Qt.AutoText widgets (status bar, QMessageBox) -- an id like
+# "<b>Verified</b>" renders as markup there. Not RCE, but UI spoofing, so
+# ids are constrained to a plain lowercase slug.
+_CATALOG_ID_RE = re.compile(r"^[a-z0-9][a-z0-9._-]{0,63}$")
+
+# Docker flags that consume the next arg as a value (so that value must not
+# be mistaken for the image reference when locating it in config.args).
+_DOCKER_VALUE_FLAGS = frozenset(
+    {
+        "-e",
+        "--env",
+        "-v",
+        "--volume",
+        "-p",
+        "--publish",
+        "--name",
+        "-w",
+        "--workdir",
+        "-u",
+        "--user",
+        "--entrypoint",
+        "--network",
+        "--platform",
+        "--add-host",
+        "-l",
+        "--label",
+    }
+)
+
 # How many versions a single accepted catalog jump may leap in one go. Bounds
 # a "freeze" attack: a compromised/leaked signing key claiming an absurd
 # future version would otherwise permanently outrank every legitimate
@@ -2262,6 +2317,121 @@ def _docker_arg_violations(tag: str, args: list[str]) -> list[str]:
     return problems
 
 
+def _catalog_package_spec_version(spec: str) -> str | None:
+    """
+    Extract the version pin from an npm-style package spec, or None if the
+    spec carries no pin.
+
+    Handles unscoped "name@version" and scoped "@scope/name@version" --
+    scoped names have a leading "@" that is NOT the version separator, so a
+    naive split on the first/only "@" misparses "@scope/pkg" (no version)
+    as pinned to "scope/pkg". Splitting from the right side instead is safe
+    for both forms because a package name may contain "@" only as the
+    scope's leading character.
+    """
+    if spec.startswith("@"):
+        rest = spec[1:]
+        if "@" not in rest:
+            return None
+        _, _, version = rest.rpartition("@")
+        return version or None
+    if "@" not in spec:
+        return None
+    _, _, version = spec.rpartition("@")
+    return version or None
+
+
+def _catalog_package_spec_pinned(spec: str) -> bool:
+    """
+    True if `spec` carries an exact version pin. Covers npm's "name@version"
+    / "@scope/name@version" and uv's documented PyPI pin forms
+    "name@version" and "name==version".
+    """
+    if "==" in spec:
+        _, _, version = spec.partition("==")
+        return bool(version)
+    return bool(_catalog_package_spec_version(spec))
+
+
+def _first_catalog_package_spec(args: list[str]) -> str | None:
+    """
+    The first arg that could plausibly BE a package spec: skip flags
+    (leading "-") and <PLACEHOLDER> tokens (which can't be validated and
+    are filled in by the user later, never shipped by the catalog as the
+    package name itself). Everything after the first hit is ignored --
+    trailing flags, paths, and placeholders are not package specs.
+    """
+    for a in args:
+        if a.startswith("-"):
+            continue
+        if _PLACEHOLDER_RE.fullmatch(a):
+            continue
+        return a
+    return None
+
+
+def _catalog_pin_violations(tag: str, command: str, args: list[str]) -> list[str]:
+    """
+    Version-pinning enforcement (finding #3): a catalog PR can otherwise
+    ship `npx -y @scope/pkg` or `docker run img:latest` and the *next*
+    resolve of that package/image is whatever the registry serves that day
+    -- outside review, outside the signature's meaning. This is the only
+    place that enforces pinning at runtime; catalog_review.py's
+    risk_unpinned_package() is a maintainer-facing hint, not a gate.
+    """
+    if command in ("npx", "uvx"):
+        spec = _first_catalog_package_spec(args)
+        if spec is None:
+            return [f"{tag}: config.args must include a package spec to pin (e.g. name@1.2.3)."]
+        if not _catalog_package_spec_pinned(spec):
+            return [
+                f"{tag}: config.args package {spec!r} is not version-pinned; use "
+                "name@version, @scope/name@version, or name==version."
+            ]
+        return []
+
+    if command == "docker":
+        image = _docker_image_ref(args)
+        if image is None:
+            return [f"{tag}: config.args docker command has no image reference to pin."]
+        _, sep, image_tag = image.rpartition(":")
+        if not sep or "/" in image_tag:
+            return [
+                f"{tag}: config.args docker image {image!r} has no explicit tag; "
+                "pin an exact version (not 'latest', not untagged)."
+            ]
+        if image_tag == "latest":
+            return [
+                f"{tag}: config.args docker image {image!r} uses the 'latest' tag, "
+                "which is not allowed; pin an exact version."
+            ]
+        return []
+
+    return []
+
+
+def _docker_image_ref(args: list[str]) -> str | None:
+    """
+    Locate the image reference in a `docker run ...` args list: skip the
+    "run" subcommand and any flags, including ones that consume the next
+    token as a value (-e, -v, --name, ...) so that value isn't mistaken for
+    the image. The first remaining positional token is the image.
+    """
+    i = 0
+    if i < len(args) and args[i] == "run":
+        i += 1
+    while i < len(args):
+        a = args[i]
+        if a.startswith("-"):
+            if a in _DOCKER_VALUE_FLAGS and "=" not in a:
+                i += 2
+            else:
+                i += 1
+            continue
+        return a
+    return None
+
+
 def _validate_catalog_config(tag: str, config) -> list[str]:
     """Validate the `config` block of a basic-tier catalog entry."""
     if not isinstance(config, dict):
@@ -2282,10 +2452,11 @@ def _validate_catalog_config(tag: str, config) -> list[str]:
             f"({', '.join(sorted(CATALOG_ALLOWED_COMMANDS))})."
         )
 
-    args = config.get("args")
+    raw_args = config.get("args")
-    if not isinstance(args, list) or not all(isinstance(a, str) for a in args):
+    args_ok = isinstance(raw_args, list) and all(isinstance(a, str) for a in raw_args)
+    args = raw_args if args_ok else []
+    if not args_ok:
         problems.append(f"{tag}: config.args must be a list of strings.")
-        args = []
 
     for a in args:
         if not a.isascii():
@@ -2304,11 +2475,55 @@ def _validate_catalog_config(tag: str, config) -> list[str]:
     if command == "docker":
         problems.extend(_docker_arg_violations(tag, args))
 
+    # Version pinning (finding #3) -- only meaningful once command/args are
+    # actually well-formed; a malformed args list already got its own
+    # problem above and has nothing left to pin-check.
+    if args_ok and command in ("npx", "uvx", "docker"):
+        problems.extend(_catalog_pin_violations(tag, command, args))
+
     env = config.get("env")
-    if env is not None and (
+    if env is not None:
-        not isinstance(env, dict) or any(not isinstance(v, str) for v in env.values())
+        env_ok = isinstance(env, dict) and all(
-    ):
+            isinstance(k, str) and isinstance(v, str) for k, v in env.items()
-        problems.append(f"{tag}: config.env must be an object of string values.")
+        )
+        if not env_ok:
+            problems.append(f"{tag}: config.env must be an object of string values.")
+        else:
+            # config.env (finding #2): unlike args, env was previously
+            # type-checked ONLY -- no allowlist, no deny-rule, no ASCII
+            # check, no secret check. That made it the single easiest way
+            # to smuggle a payload past every other guard in this
+            # function: an allowlisted `command: npx` plus
+            # NODE_OPTIONS=--require /tmp/x.js in env walks straight past
+            # the command allowlist AND the -e/--eval/-c deny-rule above,
+            # because neither of those ever looks at env.
+            for key, value in env.items():
+                if not key.isascii():
+                    problems.append(
+                        f"{tag}: config.env key {key!r} must be ASCII "
+                        "(non-ASCII code points rejected)."
+                    )
+                if key.upper() in CATALOG_DENIED_ENV_KEYS:
+                    problems.append(
+                        f"{tag}: config.env key {key!r} is on the catalog deny-list "
+                        "(interpreter/loader override) and is not allowed."
+                    )
+                if not value.isascii():
+                    problems.append(
+                        f"{tag}: config.env value for {key!r} must be ASCII "
+                        "(non-ASCII code points rejected)."
+                    )
+                if _is_secret_value(value):
+                    problems.append(
+                        f"{tag}: config.env[{key!r}] looks like a real secret value; "
+                        "catalog entries must never ship secret values."
+                    )
+                if value != "" and not _PLACEHOLDER_RE.fullmatch(value):
+                    problems.append(
+                        f"{tag}: config.env[{key!r}] must be an empty string or a "
+                        "single <PLACEHOLDER> token -- the catalog declares which env "
+                        "vars a server needs, it never supplies their values."
+                    )
 
     return problems
 
@@ -2328,6 +2543,12 @@ def _validate_catalog_entry(idx: int, entry, seen_ids: set[str]) -> list[str]:
         tag = f"servers[{idx}] ({entry_id!r})"
         if not entry_id.isascii():
             problems.append(f"{tag}: 'id' must be ASCII (non-ASCII code points rejected).")
+        elif not _CATALOG_ID_RE.match(entry_id):
+            problems.append(
+                f"{tag}: 'id' must match ^[a-z0-9][a-z0-9._-]{{0,63}}$ "
+                "(it becomes an mcpServers JSON key and is interpolated into "
+                "Qt.AutoText widgets)."
+            )
         if entry_id in seen_ids:
             problems.append(f"{tag}: duplicate id.")
         seen_ids.add(entry_id)
@@ -2441,15 +2662,32 @@ def verify_catalog_signature(raw: bytes, sig: bytes, pubkeys: list[bytes]) -> bo
     return False
 
 
+def _verify_catalog_candidate(candidate: tuple[bytes, bytes] | None) -> tuple[dict | None, int]:
+    """Verify+load+validate one (raw, sig) candidate. Returns (None, -1) on any failure."""
+    if not candidate:
+        return None, -1
+    raw, sig = candidate
+    if not verify_catalog_signature(raw, sig, CATALOG_PUBKEYS):
+        return None, -1
+    try:
+        data = load_catalog(raw)
+    except (ValueError, TypeError):
+        return None, -1
+    if validate_catalog(data):
+        return None, -1
+    return data, catalog_version(data)
+
+
 def resolve_catalog(
     bundled: tuple[bytes, bytes] | None,
     cached: tuple[bytes, bytes] | None,
     remote: tuple[bytes, bytes] | None,
+    floor: int = 0,
 ) -> dict:
     """
-    Pick the highest-version catalog among bundled/cached/remote. Each
+    Pick the highest-version catalog among bundled/cached/remote. Each of
-    argument is either None (unavailable) or an (raw_bytes, signature_bytes)
+    bundled/cached/remote is either None (unavailable) or an (raw_bytes,
-    pair.
+    signature_bytes) pair.
 
     🔴 SECURITY: every candidate — including `bundled`, the copy frozen into
     this binary — is verified against CATALOG_PUBKEYS and re-validated from
@@ -2460,46 +2698,68 @@ def resolve_catalog(
     by virtue of being local. Signing (and checking the signature at
     runtime, every time) closes that.
 
-    Anti-rollback: a candidate's version is never accepted if it's lower
+    `floor` is a pure, caller-supplied lower bound (e.g. a persisted
-    than the best verified candidate already found in this same resolution
+    "last accepted version" the GUI can load from disk and pass in) — this
-    pass — an attacker replaying an old, since-superseded signed catalog
+    function does no storage of its own.
-    can't downgrade you.
 
-    Anti-freeze: a candidate whose version leaps more than
+    Anti-rollback / anti-freeze, and WHY they apply to every candidate
-    _CATALOG_MAX_VERSION_JUMP past the current best is also rejected. A
+    including the first one evaluated: the previous version of this
-    compromised/leaked signing key claiming an absurd future version would
+    function only ran these checks `if best_version >= 0`, i.e. once a
-    otherwise permanently outrank every legitimate release from then on,
+    candidate had already been accepted in this pass. That let the FIRST
-    since the resolver always prefers the highest verified version — this
+    verified candidate through unconditionally — a signed catalog claiming
-    caps how far a single accepted jump can go.
+    version=999999999 sailed straight past both guards if it happened to be
+    evaluated first, and rollback protection reset on every call anyway
+    (nothing persisted across restarts). Now both guards are anchored to
+    something that doesn't depend on iteration order:
+
+    - The anti-freeze cap is measured against the BUNDLED catalog's version
+      (verified independently, once), not against "whatever was accepted
+      so far in this loop." Bundled ships inside the binary, so it's the
+      one candidate that isn't attacker-supplied at resolve time — the
+      natural trust anchor. If bundled itself doesn't verify, `floor` is
+      the anchor instead.
+    - The anti-rollback floor is max(floor, bundled's version), so a
+      caller that persists `floor` across restarts gets real rollback
+      protection; a caller that doesn't still gets "never below bundled."
+
+    On a version TIE, the bundled candidate wins over cached/remote (it
+    previously lost ties to whichever candidate happened to be evaluated
+    last, silently preferring remote over bundled at equal version).
 
     Returns the winning catalog dict, or {} if nothing verified and
     validated.
     """
+    bundled_data, bundled_version = _verify_catalog_candidate(bundled)
+
+    anchor = bundled_version if bundled_version >= 0 else floor
+    min_accepted = max(floor, bundled_version if bundled_version >= 0 else 0)
+
+    candidates = (
+        ("bundled", bundled_data, bundled_version),
+        ("cached", *_verify_catalog_candidate(cached)),
+        ("remote", *_verify_catalog_candidate(remote)),
+    )
+
     best: dict = {}
     best_version = -1
+    best_is_bundled = False
 
-    for candidate in (bundled, cached, remote):
+    for source, data, version in candidates:
-        if not candidate:
+        if data is None:
-            continue
-        raw, sig = candidate
-        if not verify_catalog_signature(raw, sig, CATALOG_PUBKEYS):
-            continue
-        try:
-            data = load_catalog(raw)
-        except (ValueError, TypeError):
-            continue
-        if validate_catalog(data):
             continue
+        if version < min_accepted:
+            continue  # anti-rollback / below the persisted floor
+        if version > anchor + _CATALOG_MAX_VERSION_JUMP:
+            continue  # anti-freeze, capped against the bundled trust anchor
 
-        version = catalog_version(data)
+        is_bundled = source == "bundled"
-        if best_version >= 0:
+        better = version > best_version or (
-            if version < best_version:
+            version == best_version and is_bundled and not best_is_bundled
-                continue  # anti-rollback
+        )
-            if version > best_version + _CATALOG_MAX_VERSION_JUMP:
+        if better:
-                continue  # anti-freeze
+            best = data
-
+            best_version = version
-        best = data
+            best_is_bundled = is_bundled
-        best_version = version
 
     return best
 

data/catalog.json.sig

@@ -0,0 +1,2 @@
+ы<8¶ђt2ішл„»‰/НЕ0Тjcw&`
+тrH«MўК›єrBL,0AS€!Х2–иже.SТ°ч–'Agm

requirements-dev.txt

@@ -8,3 +8,4 @@ pillow>=10.0        # generates icons/app.ico during CI (Windows build)
 # Test / lint
 pytest>=8.0
 ruff>=0.6
+cryptography>=42.0   # release checksum signing (scripts/sign_checksums.py)

scripts/sign_checksums.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+"""
+Generate a SHA256SUMS file for release artifacts and sign it with Ed25519.
+
+BCC ships PyInstaller binaries that are not code-signed (no budget for a
+macOS Developer ID / Windows Authenticode certificate). This script provides
+the free half of supply-chain integrity: a checksum manifest, detached-signed
+so downloaders can verify the file they got is the file we published.
+
+This does NOT remove Gatekeeper/SmartScreen warnings and does NOT prove the
+binary is safe to run -- only that it matches what the release signing key
+attested to.
+
+Usage:
+    # Hash every file in a directory into a SHA256SUMS-format manifest.
+    python scripts/sign_checksums.py generate <dir> --out SHA256SUMS
+
+    # Sign a manifest, producing a detached signature.
+    # Private key comes from $RELEASE_SIGNING_KEY (base64 raw Ed25519 seed)
+    # unless --key-b64 is given explicitly (mostly for tests).
+    python scripts/sign_checksums.py sign --sums SHA256SUMS --out SHA256SUMS.sig
+
+    # Verify a manifest against a detached signature and a public key.
+    python scripts/sign_checksums.py verify --sums SHA256SUMS --sig SHA256SUMS.sig \
+        --pubkey-b64 <base64 raw Ed25519 public key>
+
+The private key is generated and rotated via the Catalog Console (#62) --
+this script never generates or stores a key itself.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import os
+import sys
+from pathlib import Path
+
+# Domain separation prefix: ties every signature to "a BCC release checksum
+# manifest" so a signature can never be replayed against an unrelated
+# message signed by the same key.
+DOMAIN_PREFIX = b"bcc-release-v1|"
+
+# Public half of the RELEASE signing key(s) -- a SEPARATE keypair from
+# bcc_core.CATALOG_PUBKEYS (issue #68 finding 5). The catalog key is the
+# offline, Console-only root of trust for what BCC executes; this key is
+# CI-resident and signs ONLY the release SHA256SUMS manifest, never the
+# catalog. Keeping them apart means a CI/repo-secret compromise burns the
+# release key -- annoying, but it never lets an attacker sign a catalog a
+# user's binary would trust. A LIST (not a single key), mirroring
+# CATALOG_PUBKEYS, so the release key can be rotated without invalidating
+# the signature on every past release: verification accepts a match against
+# ANY key here.
+#
+# Populated by the maintainer via:
+#     python catalog_console.py keygen --release
+# Rotated 2026-07 (issue #68 finding 5 / #68 CI-exposure incident): the
+# original key was shared with the catalog key and had been exposed to CI,
+# so both keypairs were regenerated as separate, disjoint keys. This list
+# holds only the current release key -- if release.yml's signing-smoke-test
+# ever sees this list empty, it fails closed (loudly) rather than silently
+# verifying against nothing.
+RELEASE_PUBKEYS: list[bytes] = [
+    base64.b64decode("6BnPgJEHJFyVltFoLTCNadIsehjy00iiW8IRlC1TfhA="),
+]
+
+CHUNK_SIZE = 1024 * 1024
+
+
+def sha256_file(path: Path) -> str:
+    """Return the lowercase hex SHA-256 digest of a file's contents."""
+    digest = hashlib.sha256()
+    with open(path, "rb") as fh:
+        while chunk := fh.read(CHUNK_SIZE):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def build_checksums_text(files: dict[str, str]) -> str:
+    """Build a sha256sum(1)-compatible manifest body.
+
+    `files` maps filename -> hex digest. Entries are sorted by filename for
+    a deterministic, diffable output. Format matches `sha256sum` exactly:
+    "<hash>  <filename>\n" (two spaces, no path components).
+    """
+    lines = [f"{digest}  {name}" for name, digest in sorted(files.items())]
+    body = "\n".join(lines)
+    return body + "\n" if body else ""
+
+
+def generate_checksums(directory: Path, *, exclude: set[str] | None = None) -> str:
+    """Hash every regular file directly inside `directory` (non-recursive)
+    and return the SHA256SUMS text. Filenames are recorded without any
+    directory prefix so the manifest can be verified from inside the
+    directory it describes.
+    """
+    exclude = exclude or set()
+    files: dict[str, str] = {}
+    for entry in sorted(directory.iterdir()):
+        if not entry.is_file():
+            continue
+        if entry.name in exclude:
+            continue
+        files[entry.name] = sha256_file(entry)
+    return build_checksums_text(files)
+
+
+def _signing_message(sums_text: str) -> bytes:
+    """The exact bytes that get signed: the domain prefix followed by the
+    raw bytes of the SHA256SUMS file content."""
+    return DOMAIN_PREFIX + sums_text.encode("utf-8")
+
+
+def sign_checksums(seed_b64: str, sums_text: str) -> bytes:
+    """Sign `sums_text` with the Ed25519 private key encoded (base64, raw
+    32-byte seed) in `seed_b64`. Returns the raw 64-byte signature."""
+    # Imported lazily so `generate` mode (used on every CI run) never
+    # requires the `cryptography` package to be installed.
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+    seed = base64.b64decode(seed_b64)
+    if len(seed) != 32:
+        raise ValueError(f"expected a 32-byte raw Ed25519 seed, got {len(seed)} bytes")
+    private_key = Ed25519PrivateKey.from_private_bytes(seed)
+    return private_key.sign(_signing_message(sums_text))
+
+
+def verify_checksums(pubkey_b64: str, sums_text: str, signature: bytes) -> bool:
+    """Verify `signature` over `sums_text` against the base64-encoded raw
+    32-byte Ed25519 public key. Returns True/False; never raises for a bad
+    signature (only for malformed inputs)."""
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+    pubkey_bytes = base64.b64decode(pubkey_b64)
+    if len(pubkey_bytes) != 32:
+        raise ValueError(
+            f"expected a 32-byte raw Ed25519 public key, got {len(pubkey_bytes)} bytes"
+        )
+    public_key = Ed25519PublicKey.from_public_bytes(pubkey_bytes)
+    try:
+        public_key.verify(signature, _signing_message(sums_text))
+        return True
+    except InvalidSignature:
+        return False
+
+
+def public_key_b64_from_seed(seed_b64: str) -> str:
+    """Derive the base64 raw public key from a base64 raw seed. Handy for
+    local key-pair sanity checks; not used by the release workflow."""
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+    from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+
+    seed = base64.b64decode(seed_b64)
+    private_key = Ed25519PrivateKey.from_private_bytes(seed)
+    raw = private_key.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
+    return base64.b64encode(raw).decode("ascii")
+
+
+def verify_checksums_against_any(pubkeys: list[bytes], sums_text: str, signature: bytes) -> bool:
+    """Verify `signature` against ANY key in `pubkeys` (each a raw 32-byte
+    Ed25519 public key). Mirrors bcc_core.verify_catalog_signature's
+    rotation-friendly "any currently-trusted key" semantics, applied to
+    RELEASE_PUBKEYS instead of the catalog's key list. Returns False (never
+    raises) for an empty `pubkeys` list -- fails closed rather than
+    vacuously verifying against nothing."""
+    return any(
+        verify_checksums(base64.b64encode(pk).decode("ascii"), sums_text, signature)
+        for pk in pubkeys
+    )
+
+
+# --------------------------------------------------------------------------- #
+# CLI
+# --------------------------------------------------------------------------- #
+def _cmd_generate(args: argparse.Namespace) -> int:
+    directory = Path(args.directory)
+    exclude = {"SHA256SUMS", "SHA256SUMS.sig"}
+    text = generate_checksums(directory, exclude=exclude)
+    out_path = Path(args.out)
+    out_path.write_text(text, encoding="utf-8")
+    print(f"Wrote {out_path} ({len(text.splitlines())} entries)")
+    return 0
+
+
+def _cmd_sign(args: argparse.Namespace) -> int:
+    seed_b64 = args.key_b64 or os.environ.get(args.key_env, "")
+    if not seed_b64:
+        print(
+            f"error: no signing key provided (checked --key-b64 and ${args.key_env})",
+            file=sys.stderr,
+        )
+        return 1
+    sums_text = Path(args.sums).read_text(encoding="utf-8")
+    signature = sign_checksums(seed_b64, sums_text)
+    Path(args.out).write_bytes(signature)
+    print(f"Wrote {args.out} ({len(signature)} bytes)")
+    return 0
+
+
+def _cmd_verify(args: argparse.Namespace) -> int:
+    pubkey_b64 = args.pubkey_b64 or os.environ.get(args.pubkey_env, "")
+    if not pubkey_b64:
+        print(
+            f"error: no public key provided (checked --pubkey-b64 and ${args.pubkey_env})",
+            file=sys.stderr,
+        )
+        return 1
+    sums_text = Path(args.sums).read_text(encoding="utf-8")
+    signature = Path(args.sig).read_bytes()
+    ok = verify_checksums(pubkey_b64, sums_text, signature)
+    if ok:
+        print("OK: signature is valid")
+        return 0
+    print("FAILED: signature is invalid", file=sys.stderr)
+    return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    sub = parser.add_subparsers(dest="mode", required=True)
+
+    p_gen = sub.add_parser(
+        "generate", help="hash every file in a directory into a SHA256SUMS manifest"
+    )
+    p_gen.add_argument("directory", help="directory whose files should be hashed (non-recursive)")
+    p_gen.add_argument("--out", required=True, help="path to write the SHA256SUMS manifest to")
+    p_gen.set_defaults(func=_cmd_generate)
+
+    p_sign = sub.add_parser("sign", help="detached-sign a SHA256SUMS manifest with Ed25519")
+    p_sign.add_argument("--sums", required=True, help="path to the SHA256SUMS manifest to sign")
+    p_sign.add_argument("--out", required=True, help="path to write the detached signature to")
+    p_sign.add_argument(
+        "--key-b64", default=None, help="base64 raw Ed25519 seed (overrides --key-env)"
+    )
+    p_sign.add_argument(
+        "--key-env",
+        default="RELEASE_SIGNING_KEY",
+        help="environment variable holding the base64 seed (default: RELEASE_SIGNING_KEY)",
+    )
+    p_sign.set_defaults(func=_cmd_sign)
+
+    p_verify = sub.add_parser(
+        "verify", help="verify a SHA256SUMS manifest against a detached signature"
+    )
+    p_verify.add_argument("--sums", required=True, help="path to the SHA256SUMS manifest")
+    p_verify.add_argument("--sig", required=True, help="path to the detached signature")
+    p_verify.add_argument(
+        "--pubkey-b64", default=None, help="base64 raw Ed25519 public key (overrides --pubkey-env)"
+    )
+    p_verify.add_argument(
+        "--pubkey-env",
+        default="RELEASE_SIGNING_PUBKEY",
+        help="environment variable holding the base64 public key (default: RELEASE_SIGNING_PUBKEY)",
+    )
+    p_verify.set_defaults(func=_cmd_verify)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/test_catalog_console_git.py

@@ -0,0 +1,215 @@
+"""Tests for catalog_console.py's non-Qt git plumbing and ref-resolution
+seam (issue #68 rotation-completability fix).
+
+catalog_console.py is importable here WITHOUT PySide6 -- its Qt import is
+guarded (`_PYSIDE6_AVAILABLE`) precisely so `keygen`, `show-seed-b64`,
+`keys`, and this git plumbing stay usable (and testable) wherever PySide6
+isn't installed, including this CI test job, which never installs it. If
+PySide6 genuinely isn't importable in this environment, that itself
+exercises the guard path -- see test_module_imports_without_pyside6.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import catalog_console as cc
+import catalog_review as review
+
+_SEED_CATALOG = b'{"schema": 1, "version": 1, "servers": []}'
+_SEED_SIG = b"\x00" * 64
+
+
+def _run(*args: str, cwd: Path) -> None:
+    subprocess.run(["git", *args], cwd=cwd, check=True, capture_output=True)
+
+
+def _init_bare_and_clone(tmp_path: Path) -> tuple[Path, Path]:
+    """A bare "origin" repo with `main` and `rotation-branch` both seeded
+    with a catalog + (dummy) signature, plus a working clone with `origin`
+    already configured -- mirroring the tokened-remote clone
+    catalog_console.py's git plumbing is always run against."""
+    origin = tmp_path / "origin.git"
+    _run("init", "--bare", str(origin), cwd=tmp_path)
+
+    seed = tmp_path / "seed"
+    _run("clone", str(origin), str(seed), cwd=tmp_path)
+    _run("config", "user.email", "test@example.com", cwd=seed)
+    _run("config", "user.name", "Test", cwd=seed)
+
+    (seed / "data").mkdir()
+    (seed / "data" / "catalog.json").write_bytes(_SEED_CATALOG)
+    (seed / "data" / "catalog.json.sig").write_bytes(_SEED_SIG)
+    _run("add", "-A", cwd=seed)
+    _run("commit", "-m", "seed", cwd=seed)
+    _run("push", "origin", "HEAD:refs/heads/main", cwd=seed)
+    _run("checkout", "-b", "rotation-branch", cwd=seed)
+    _run("push", "origin", "HEAD:refs/heads/rotation-branch", cwd=seed)
+
+    clone = tmp_path / "work"
+    _run("clone", str(origin), str(clone), cwd=tmp_path)
+    _run("config", "user.email", "test@example.com", cwd=clone)
+    _run("config", "user.name", "Test", cwd=clone)
+    return origin, clone
+
+
+# --------------------------------------------------------------------------- #
+# The module must stay importable without PySide6 -- this IS the fix that
+# lets `keys`/`keygen`/`show-seed-b64` (and this whole test file) run
+# somewhere PySide6 isn't installed.
+# --------------------------------------------------------------------------- #
+def test_module_imports_without_pyside6():
+    assert hasattr(cc, "_PYSIDE6_AVAILABLE")
+    # This CI test job never installs PySide6 (see .github/workflows/ci.yml
+    # "Install test dependencies": pytest + cryptography only) -- so on CI,
+    # this assertion is itself proof the guard is doing its job. Locally,
+    # where a maintainer's env DOES have PySide6, it's fine either way; the
+    # only real assertion this test needs is "importing the module never
+    # raises", which happened just by getting this far.
+    assert cc._PYSIDE6_AVAILABLE in (True, False)
+
+
+def test_cmd_gui_fails_soft_without_pyside6(monkeypatch, capsys):
+    if cc._PYSIDE6_AVAILABLE:
+        return  # nothing to prove where PySide6 IS available
+    import argparse
+
+    args = argparse.Namespace(repo=".", ref=None)
+    assert cc.cmd_gui(args) == 1
+    assert "PySide6" in capsys.readouterr().err
+
+
+# --------------------------------------------------------------------------- #
+# compute_own_refs: the PURE ref-resolution seam. No git, no Qt.
+# --------------------------------------------------------------------------- #
+def test_compute_own_refs_defaults_to_main_only():
+    assert cc.compute_own_refs(None, None) == ["main"]
+
+
+def test_compute_own_refs_adds_detected_branch():
+    assert cc.compute_own_refs(None, "chore/68-key-rotation") == [
+        "main",
+        "chore/68-key-rotation",
+    ]
+
+
+def test_compute_own_refs_explicit_ref_overrides_detected_branch():
+    assert cc.compute_own_refs("explicit-branch", "detected-branch") == [
+        "main",
+        "explicit-branch",
+    ]
+
+
+def test_compute_own_refs_does_not_duplicate_main():
+    assert cc.compute_own_refs(None, "main") == ["main"]
+    assert cc.compute_own_refs("main", "some-other-branch") == ["main"]
+
+
+# --------------------------------------------------------------------------- #
+# current_branch: git plumbing, no Qt.
+# --------------------------------------------------------------------------- #
+def test_current_branch_detects_checked_out_branch(tmp_path):
+    _origin, clone = _init_bare_and_clone(tmp_path)
+    _run("fetch", "origin", "rotation-branch", cwd=clone)
+    _run("checkout", "-B", "rotation-branch", "origin/rotation-branch", cwd=clone)
+    assert cc.current_branch(clone) == "rotation-branch"
+
+
+def test_current_branch_none_on_detached_head(tmp_path):
+    _origin, clone = _init_bare_and_clone(tmp_path)
+    commit = cc.fetch_ref(clone, "main")
+    _run("checkout", commit, cwd=clone)
+    assert cc.current_branch(clone) is None
+
+
+# --------------------------------------------------------------------------- #
+# commit_and_push_signed_catalog: MUST target the given branch, never a
+# hardcoded "main" -- issue #68's completability fix. This is exactly the
+# bug that, before the fix, would have made ReviewWindow._on_sign push a
+# PR/branch review's signature straight to main regardless of what was
+# actually reviewed.
+# --------------------------------------------------------------------------- #
+def test_commit_and_push_signed_catalog_targets_the_given_branch_not_main(tmp_path):
+    _origin, clone = _init_bare_and_clone(tmp_path)
+
+    new_raw = b'{"schema": 1, "version": 2, "servers": []}'
+    new_sig = b"\x01" * 64
+    cc.commit_and_push_signed_catalog(clone, new_raw, new_sig, branch="rotation-branch")
+
+    rotation_commit = cc.fetch_ref(clone, "rotation-branch")
+    rotation_raw, _sha = cc.read_catalog_at_commit(clone, rotation_commit)
+    assert rotation_raw == new_raw
+
+    # main on the shared origin must be COMPLETELY untouched by a sign that
+    # was reviewed and pushed against rotation-branch.
+    main_commit = cc.fetch_ref(clone, "main")
+    main_raw, _sha = cc.read_catalog_at_commit(clone, main_commit)
+    assert main_raw == _SEED_CATALOG
+
+
+def test_commit_and_push_signed_catalog_still_defaults_to_main(tmp_path):
+    """Backward-compatible default: callers that don't pass `branch` (there
+    are none left in catalog_console.py itself, but the signature keeps the
+    default for any other caller / test fixture) still push to main."""
+    _origin, clone = _init_bare_and_clone(tmp_path)
+
+    new_raw = b'{"schema": 1, "version": 2, "servers": []}'
+    new_sig = b"\x01" * 64
+    cc.commit_and_push_signed_catalog(clone, new_raw, new_sig)
+
+    main_commit = cc.fetch_ref(clone, "main")
+    main_raw, _sha = cc.read_catalog_at_commit(clone, main_commit)
+    assert main_raw == new_raw
+
+    rotation_commit = cc.fetch_ref(clone, "rotation-branch")
+    rotation_raw, _sha = cc.read_catalog_at_commit(clone, rotation_commit)
+    assert rotation_raw == _SEED_CATALOG  # untouched
+
+
+# --------------------------------------------------------------------------- #
+# catalog_sig_status_on_disk: the check behind `keys`' "does catalog.json.sig
+# currently verify?" line -- this is precisely the check that would have
+# caught the current chore/68-key-rotation state (bcc_core.CATALOG_PUBKEYS
+# rotated, data/catalog.json.sig still signed by the retired key).
+# --------------------------------------------------------------------------- #
+def test_catalog_sig_status_on_disk_valid(tmp_path):
+    seed, pub = review.generate_keypair()
+    raw = b'{"schema": 1, "version": 1, "servers": []}'
+    sig = review.sign_catalog_bytes(raw, seed)
+
+    (tmp_path / "data").mkdir()
+    (tmp_path / "data" / "catalog.json").write_bytes(raw)
+    (tmp_path / "data" / "catalog.json.sig").write_bytes(sig)
+
+    assert cc.catalog_sig_status_on_disk(tmp_path, [pub]) == "valid"
+
+
+def test_catalog_sig_status_on_disk_invalid_when_pubkey_rotated(tmp_path):
+    """The exact chore/68-key-rotation scenario: signed by an OLD key, but
+    the committed pubkey list now only has the NEW key."""
+    old_seed, _old_pub = review.generate_keypair()
+    _new_seed, new_pub = review.generate_keypair()
+    raw = b'{"schema": 1, "version": 1, "servers": []}'
+    sig = review.sign_catalog_bytes(raw, old_seed)
+
+    (tmp_path / "data").mkdir()
+    (tmp_path / "data" / "catalog.json").write_bytes(raw)
+    (tmp_path / "data" / "catalog.json.sig").write_bytes(sig)
+
+    assert cc.catalog_sig_status_on_disk(tmp_path, [new_pub]) == "invalid"
+
+
+def test_catalog_sig_status_on_disk_missing_when_no_sig_file(tmp_path):
+    (tmp_path / "data").mkdir()
+    (tmp_path / "data" / "catalog.json").write_bytes(b"{}")
+    assert cc.catalog_sig_status_on_disk(tmp_path, []) == "missing"
+
+
+def test_catalog_sig_status_on_disk_missing_when_no_catalog_file(tmp_path):
+    (tmp_path / "data").mkdir()
+    (tmp_path / "data" / "catalog.json.sig").write_bytes(b"\x00" * 64)
+    assert cc.catalog_sig_status_on_disk(tmp_path, []) == "missing"

tests/test_catalog_console_packaging.py

@@ -0,0 +1,66 @@
+"""Asserts the maintainer-only Catalog Console (catalog_console.py,
+catalog_review.py) is never bundled into the release binary.
+
+A signing/review tool shipping to end users would be an own-goal (issue
+#62): it has no reason to run on a user's machine, and its presence would
+be a confusing artefact of a build that's supposed to be a thin GUI over
+mcpServers config editing."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SPEC_PATH = REPO_ROOT / "bcc.spec"
+
+_EXCLUDED_FILES = ("catalog_console.py", "catalog_review.py")
+
+
+def test_spec_file_exists():
+    assert SPEC_PATH.exists()
+
+
+def test_console_files_not_named_in_spec():
+    """The spec text must never reference either maintainer-only module --
+    not as the Analysis entry point, not in datas, not anywhere."""
+    spec_text = SPEC_PATH.read_text(encoding="utf-8")
+    for filename in _EXCLUDED_FILES:
+        assert filename not in spec_text, (
+            f"{filename} must never be referenced by bcc.spec -- it is a "
+            "maintainer-only tool and must not ship to users."
+        )
+
+
+def test_spec_analysis_entry_point_is_bcc_py_only():
+    """PyInstaller's Analysis(...) call determines the dependency-scanned
+    entry point(s); it must be bcc.py alone."""
+    spec_text = SPEC_PATH.read_text(encoding="utf-8")
+    assert 'Analysis(\n    ["bcc.py"],' in spec_text or 'Analysis(["bcc.py"]' in spec_text, (
+        "bcc.spec's Analysis(...) entry point changed shape -- re-verify by hand "
+        "that catalog_console.py / catalog_review.py are still excluded."
+    )
+
+
+def test_console_modules_exist_but_are_standalone_top_level_files():
+    """Sanity check the files this test is guarding actually exist as
+    top-level modules (not, say, silently moved into a package PyInstaller's
+    Analysis would still pick up as an implicit import of bcc.py)."""
+    for filename in _EXCLUDED_FILES:
+        assert (REPO_ROOT / filename).exists()
+        # bcc.py must not import them.
+        bcc_text = (REPO_ROOT / "bcc.py").read_text(encoding="utf-8")
+        module_name = filename.removesuffix(".py")
+        assert f"import {module_name}" not in bcc_text
+        assert f"from {module_name}" not in bcc_text
+
+
+def test_requirements_files_do_not_reference_console_only_needs():
+    """catalog_console.py's only import beyond the shipped stack is the
+    optional `keyring` package, which is intentionally NOT added as a hard
+    dependency anywhere a user install would pick it up."""
+    for req_file in ("requirements.txt", "requirements-dev.txt"):
+        path = REPO_ROOT / req_file
+        if not path.exists():
+            continue
+        text = path.read_text(encoding="utf-8").lower()
+        assert "keyring" not in text

tests/test_checksums.py

@@ -0,0 +1,234 @@
+"""Tests for scripts/sign_checksums.py: SHA256SUMS generation and detached
+Ed25519 signing/verification for release artifacts."""
+
+from __future__ import annotations
+
+import base64
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "scripts"))
+
+import sign_checksums as sc
+
+cryptography = pytest.importorskip("cryptography")
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey  # noqa: E402
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat  # noqa: E402
+
+
+def _make_keypair() -> tuple[str, str]:
+    """Return (seed_b64, pubkey_b64) for a fresh Ed25519 keypair."""
+    private_key = Ed25519PrivateKey.generate()
+    seed = private_key.private_bytes_raw()
+    pubkey = private_key.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
+    return base64.b64encode(seed).decode("ascii"), base64.b64encode(pubkey).decode("ascii")
+
+
+# --------------------------------------------------------------------------- #
+# sha256_file / build_checksums_text / generate_checksums
+# --------------------------------------------------------------------------- #
+def test_sha256_file_matches_hashlib(tmp_path):
+    f = tmp_path / "a.txt"
+    f.write_bytes(b"hello world")
+    import hashlib
+
+    assert sc.sha256_file(f) == hashlib.sha256(b"hello world").hexdigest()
+
+
+def test_build_checksums_text_sorted_and_formatted():
+    files = {"zeta.zip": "aa" * 32, "alpha.zip": "bb" * 32}
+    text = sc.build_checksums_text(files)
+    lines = text.splitlines()
+    assert lines[0].endswith("alpha.zip")
+    assert lines[1].endswith("zeta.zip")
+    # Standard sha256sum format: hash, two spaces, filename.
+    assert lines[0] == f"{'bb' * 32}  alpha.zip"
+
+
+def test_build_checksums_text_empty():
+    assert sc.build_checksums_text({}) == ""
+
+
+def test_generate_checksums_from_directory(tmp_path):
+    (tmp_path / "b.bin").write_bytes(b"second")
+    (tmp_path / "a.bin").write_bytes(b"first")
+    (tmp_path / "subdir").mkdir()
+    (tmp_path / "subdir" / "ignored.bin").write_bytes(b"nested, not hashed")
+
+    text = sc.generate_checksums(tmp_path)
+    lines = text.splitlines()
+    assert len(lines) == 2
+    assert lines[0].endswith("a.bin")
+    assert lines[1].endswith("b.bin")
+    assert "subdir" not in text
+
+
+def test_generate_checksums_excludes_manifest_files(tmp_path):
+    (tmp_path / "archive.zip").write_bytes(b"payload")
+    (tmp_path / "SHA256SUMS").write_text("stale")
+    (tmp_path / "SHA256SUMS.sig").write_bytes(b"stale-sig")
+
+    text = sc.generate_checksums(tmp_path, exclude={"SHA256SUMS", "SHA256SUMS.sig"})
+    assert "archive.zip" in text
+    assert "SHA256SUMS" not in text.replace("archive.zip", "")
+
+
+# --------------------------------------------------------------------------- #
+# sign_checksums / verify_checksums
+# --------------------------------------------------------------------------- #
+def test_sign_then_verify_roundtrip():
+    seed_b64, pubkey_b64 = _make_keypair()
+    sums_text = "deadbeef" * 8 + "  BetterClaudeConfig-Linux.tar.gz\n"
+
+    signature = sc.sign_checksums(seed_b64, sums_text)
+    assert len(signature) == 64
+    assert sc.verify_checksums(pubkey_b64, sums_text, signature) is True
+
+
+def test_verify_rejects_tampered_checksums():
+    seed_b64, pubkey_b64 = _make_keypair()
+    sums_text = "aa" * 32 + "  file.zip\n"
+    signature = sc.sign_checksums(seed_b64, sums_text)
+
+    tampered = "bb" * 32 + "  file.zip\n"
+    assert sc.verify_checksums(pubkey_b64, tampered, signature) is False
+
+
+def test_verify_rejects_wrong_key():
+    seed_b64, _ = _make_keypair()
+    _, other_pubkey_b64 = _make_keypair()
+    sums_text = "cc" * 32 + "  file.zip\n"
+    signature = sc.sign_checksums(seed_b64, sums_text)
+
+    assert sc.verify_checksums(other_pubkey_b64, sums_text, signature) is False
+
+
+def test_domain_prefix_is_applied():
+    """The signed message must be prefixed, not the raw manifest bytes --
+    otherwise a signature over this manifest could be replayed as a
+    signature over an unrelated message with the same bytes elsewhere."""
+    seed_b64, pubkey_b64 = _make_keypair()
+    sums_text = "11" * 32 + "  file.zip\n"
+
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey as PK
+
+    seed = base64.b64decode(seed_b64)
+    raw_signature = PK.from_private_bytes(seed).sign(sums_text.encode("utf-8"))
+
+    # A signature over the raw (unprefixed) bytes must NOT verify via our
+    # domain-separated verify function.
+    assert sc.verify_checksums(pubkey_b64, sums_text, raw_signature) is False
+
+    # But our own sign_checksums() output does verify.
+    good_signature = sc.sign_checksums(seed_b64, sums_text)
+    assert sc.verify_checksums(pubkey_b64, sums_text, good_signature) is True
+
+
+def test_sign_checksums_rejects_bad_seed_length():
+    bad_seed_b64 = base64.b64encode(b"too-short").decode("ascii")
+    with pytest.raises(ValueError):
+        sc.sign_checksums(bad_seed_b64, "irrelevant\n")
+
+
+def test_verify_checksums_rejects_bad_pubkey_length():
+    seed_b64, _ = _make_keypair()
+    sig = sc.sign_checksums(seed_b64, "irrelevant\n")
+    bad_pubkey_b64 = base64.b64encode(b"too-short").decode("ascii")
+    with pytest.raises(ValueError):
+        sc.verify_checksums(bad_pubkey_b64, "irrelevant\n", sig)
+
+
+def test_public_key_b64_from_seed_matches_generated_pubkey():
+    seed_b64, pubkey_b64 = _make_keypair()
+    assert sc.public_key_b64_from_seed(seed_b64) == pubkey_b64
+
+
+# --------------------------------------------------------------------------- #
+# CLI (end-to-end, via subprocess so argparse wiring is exercised too)
+# --------------------------------------------------------------------------- #
+SCRIPT = Path(__file__).resolve().parent.parent / "scripts" / "sign_checksums.py"
+
+
+def _run(*args, env=None):
+    return subprocess.run(
+        [sys.executable, str(SCRIPT), *args],
+        capture_output=True,
+        text=True,
+        env=env,
+    )
+
+
+def test_cli_generate_sign_verify_roundtrip(tmp_path, monkeypatch):
+    seed_b64, pubkey_b64 = _make_keypair()
+
+    release_dir = tmp_path / "release-files"
+    release_dir.mkdir()
+    (release_dir / "BetterClaudeConfig-Linux.tar.gz").write_bytes(b"fake archive contents")
+    (release_dir / "BetterClaudeConfig-macOS.zip").write_bytes(b"fake zip contents")
+
+    sums_path = release_dir / "SHA256SUMS"
+    sig_path = release_dir / "SHA256SUMS.sig"
+
+    gen = _run("generate", str(release_dir), "--out", str(sums_path))
+    assert gen.returncode == 0, gen.stderr
+    assert sums_path.exists()
+    body = sums_path.read_text()
+    assert "BetterClaudeConfig-Linux.tar.gz" in body
+    assert "BetterClaudeConfig-macOS.zip" in body
+
+    sign = _run("sign", "--sums", str(sums_path), "--out", str(sig_path), "--key-b64", seed_b64)
+    assert sign.returncode == 0, sign.stderr
+    assert sig_path.exists()
+    assert sig_path.stat().st_size == 64
+
+    verify = _run(
+        "verify",
+        "--sums",
+        str(sums_path),
+        "--sig",
+        str(sig_path),
+        "--pubkey-b64",
+        pubkey_b64,
+    )
+    assert verify.returncode == 0, verify.stderr
+    assert "OK" in verify.stdout
+
+
+def test_cli_sign_without_key_fails_loudly(tmp_path):
+    sums_path = tmp_path / "SHA256SUMS"
+    sums_path.write_text("aa" * 32 + "  file.zip\n")
+    sig_path = tmp_path / "SHA256SUMS.sig"
+
+    import os
+
+    env = {k: v for k, v in os.environ.items() if k != "RELEASE_SIGNING_KEY"}
+    result = _run("sign", "--sums", str(sums_path), "--out", str(sig_path), env=env)
+
+    assert result.returncode != 0
+    assert not sig_path.exists(), "must never write a bogus/empty signature file"
+    assert "no signing key" in result.stderr.lower()
+
+
+def test_cli_verify_detects_tampering(tmp_path):
+    seed_b64, pubkey_b64 = _make_keypair()
+    sums_path = tmp_path / "SHA256SUMS"
+    sums_path.write_text("aa" * 32 + "  file.zip\n")
+    sig_path = tmp_path / "SHA256SUMS.sig"
+
+    _run("sign", "--sums", str(sums_path), "--out", str(sig_path), "--key-b64", seed_b64)
+
+    sums_path.write_text("bb" * 32 + "  file.zip\n")  # tamper after signing
+    verify = _run(
+        "verify",
+        "--sums",
+        str(sums_path),
+        "--sig",
+        str(sig_path),
+        "--pubkey-b64",
+        pubkey_b64,
+    )
+    assert verify.returncode != 0
+    assert "FAILED" in verify.stdout + verify.stderr

tests/test_core.py

@@ -1690,8 +1690,12 @@ def _minimal_catalog(version: int = 1) -> dict:
                 "official": True,
                 "setup": "basic",
                 "config": {
+                    # Pinned on purpose (issue #68 finding 3): an earlier
+                    # version of this fixture used an unpinned package and
+                    # asserted it validated clean, which enshrined the bug
+                    # instead of catching it.
                     "command": "npx",
-                    "args": ["-y", "widget-mcp"],
+                    "args": ["-y", "widget-mcp@1.0.0"],
                 },
                 "placeholders": {},
                 "env_required": {},
@@ -1952,6 +1956,213 @@ def test_validate_catalog_rejects_duplicate_ids():
     assert any("duplicate id" in p for p in problems)
 
 
+# --- validate_catalog: config.env (issue #68 finding 2) -------------------- #
+def test_validate_catalog_rejects_each_denied_env_key():
+    for key in sorted(c.CATALOG_DENIED_ENV_KEYS):
+        data = _catalog_with(
+            {"config": {"command": "npx", "args": ["-y", "widget-mcp@1.0.0"], "env": {key: ""}}}
+        )
+        problems = c.validate_catalog(data)
+        assert any("deny-list" in p for p in problems), (key, problems)
+
+
+def test_validate_catalog_rejects_denied_env_key_case_insensitively():
+    data = _catalog_with(
+        {
+            "config": {
+                "command": "npx",
+                "args": ["-y", "widget-mcp@1.0.0"],
+                "env": {"node_options": ""},
+            }
+        }
+    )
+    problems = c.validate_catalog(data)
+    assert any("deny-list" in p for p in problems)
+
+
+def test_validate_catalog_rejects_nonempty_nonplaceholder_env_value():
+    data = _catalog_with(
+        {
+            "config": {
+                "command": "npx",
+                "args": ["-y", "widget-mcp@1.0.0"],
+                "env": {"FOO_URL": "https://example.com"},
+            }
+        }
+    )
+    problems = c.validate_catalog(data)
+    assert any("empty string or a single <PLACEHOLDER>" in p for p in problems)
+
+
+def test_validate_catalog_accepts_empty_and_placeholder_env_values():
+    data = _catalog_with(
+        {
+            "config": {
+                "command": "npx",
+                "args": ["-y", "widget-mcp@1.0.0"],
+                "env": {"FOO": "", "BAR_URL": "<BAR_URL>"},
+            }
+        }
+    )
+    assert c.validate_catalog(data) == []
+
+
+def test_validate_catalog_rejects_non_ascii_env_key():
+    data = _catalog_with(
+        {
+            "config": {
+                "command": "npx",
+                "args": ["-y", "widget-mcp@1.0.0"],
+                "env": {"FÖO": ""},
+            }
+        }
+    )
+    problems = c.validate_catalog(data)
+    assert any("config.env key" in p and "ASCII" in p for p in problems)
+
+
+def test_validate_catalog_rejects_non_ascii_env_value():
+    data = _catalog_with(
+        {
+            "config": {
+                "command": "npx",
+                "args": ["-y", "widget-mcp@1.0.0"],
+                "env": {"FOO": "<Bäd>"},
+            }
+        }
+    )
+    problems = c.validate_catalog(data)
+    assert any("config.env value" in p and "ASCII" in p for p in problems)
+
+
+def test_validate_catalog_rejects_secret_looking_env_value():
+    data = _catalog_with(
+        {
+            "config": {
+                "command": "npx",
+                "args": ["-y", "widget-mcp@1.0.0"],
+                "env": {"SOME_TOKEN": "ghp_abcdef1234567890"},
+            }
+        }
+    )
+    problems = c.validate_catalog(data)
+    assert any("real secret value" in p for p in problems)
+
+
+def test_validate_catalog_rejects_node_options_env_walking_past_allowlist():
+    # The exact reproduction from issue #68 finding 2: an allowlisted
+    # `npx` command carrying NODE_OPTIONS in env, which previously passed
+    # validation and would have flowed straight into the executed
+    # subprocess via catalog_entry_to_paste_json().
+    data = _catalog_with(
+        {
+            "config": {
+                "command": "npx",
+                "args": ["-y", "widget-mcp@1.0.0"],
+                "env": {"NODE_OPTIONS": "--require /tmp/payload.js"},
+            }
+        }
+    )
+    problems = c.validate_catalog(data)
+    assert problems != []
+
+
+# --- validate_catalog: version pinning (issue #68 finding 3) --------------- #
+def test_validate_catalog_rejects_unpinned_npx_package():
+    data = _catalog_with({"config": {"command": "npx", "args": ["-y", "widget-mcp"]}})
+    problems = c.validate_catalog(data)
+    assert any("not version-pinned" in p for p in problems)
+
+
+def test_validate_catalog_rejects_unpinned_scoped_npx_package():
+    data = _catalog_with({"config": {"command": "npx", "args": ["-y", "@scope/pkg"]}})
+    problems = c.validate_catalog(data)
+    assert any("not version-pinned" in p for p in problems)
+
+
+def test_validate_catalog_accepts_pinned_scoped_npx_package():
+    data = _catalog_with({"config": {"command": "npx", "args": ["-y", "@scope/pkg@1.2.3"]}})
+    assert c.validate_catalog(data) == []
+
+
+def test_validate_catalog_rejects_unpinned_uvx_package():
+    data = _catalog_with({"config": {"command": "uvx", "args": ["some-tool"]}})
+    problems = c.validate_catalog(data)
+    assert any("not version-pinned" in p for p in problems)
+
+
+def test_validate_catalog_accepts_uvx_at_version_pin():
+    data = _catalog_with({"config": {"command": "uvx", "args": ["some-tool@1.0.0"]}})
+    assert c.validate_catalog(data) == []
+
+
+def test_validate_catalog_accepts_uvx_double_equals_pin():
+    data = _catalog_with({"config": {"command": "uvx", "args": ["some-tool==1.0.0"]}})
+    assert c.validate_catalog(data) == []
+
+
+def test_validate_catalog_rejects_docker_latest_tag():
+    data = _catalog_with({"config": {"command": "docker", "args": ["run", "some/image:latest"]}})
+    problems = c.validate_catalog(data)
+    assert any("'latest'" in p for p in problems)
+
+
+def test_validate_catalog_rejects_docker_untagged_image():
+    data = _catalog_with({"config": {"command": "docker", "args": ["run", "some/image"]}})
+    problems = c.validate_catalog(data)
+    assert any("no explicit tag" in p for p in problems)
+
+
+def test_validate_catalog_accepts_pinned_docker_image_with_flags():
+    data = _catalog_with(
+        {
+            "config": {
+                "command": "docker",
+                "args": ["run", "-i", "--rm", "-e", "SOME_TOKEN", "some/image:1.2.3"],
+            }
+        }
+    )
+    assert c.validate_catalog(data) == []
+
+
+def test_validate_catalog_does_not_pin_check_placeholders_flags_or_subcommand():
+    # A pinned uvx spec followed by flags and a <PLACEHOLDER> positional
+    # must not itself get mistaken for an unpinned package.
+    data = _catalog_with(
+        {
+            "config": {
+                "command": "uvx",
+                "args": ["mcp-server-git@2026.7.10", "--repository", "<REPO_PATH>"],
+            }
+        }
+    )
+    assert c.validate_catalog(data) == []
+
+
+# --- validate_catalog: id constraint (issue #68 finding 7) ----------------- #
+def test_validate_catalog_rejects_id_with_markup():
+    data = _catalog_with({"id": "<b>Verified</b>"})
+    problems = c.validate_catalog(data)
+    assert any("must match" in p for p in problems)
+
+
+def test_validate_catalog_rejects_id_with_uppercase():
+    data = _catalog_with({"id": "Widget"})
+    problems = c.validate_catalog(data)
+    assert any("must match" in p for p in problems)
+
+
+def test_validate_catalog_rejects_id_starting_with_dash():
+    data = _catalog_with({"id": "-widget"})
+    problems = c.validate_catalog(data)
+    assert any("must match" in p for p in problems)
+
+
+def test_validate_catalog_accepts_valid_slug_id():
+    data = _catalog_with({"id": "widget-2.thing-ok"})
+    assert c.validate_catalog(data) == []
+
+
 # --- resolve_catalog -------------------------------------------------------- #
 def test_resolve_catalog_nothing_available_returns_empty_dict():
     assert c.resolve_catalog(None, None, None) == {}
@@ -2003,13 +2214,93 @@ def test_resolve_catalog_rejects_absurd_version_jump(monkeypatch):
     pub = priv.public_key().public_bytes_raw()
     monkeypatch.setattr(c, "CATALOG_PUBKEYS", [pub])
 
-    cached = _signed(_minimal_catalog(version=5), priv)
+    # The freeze attempt goes FIRST (as `cached`), the legitimate catalog
+    # SECOND (as `remote`) -- on purpose. Putting the good catalog first
+    # (as an earlier version of this test did) never exercises the
+    # vulnerable path: the old implementation only guarded a candidate
+    # against "the best accepted so far," so whichever candidate was
+    # evaluated FIRST got in unconditionally, uncapped. Ordering the freeze
+    # attempt first is what actually proves the cap holds regardless of
+    # evaluation order.
     freeze_attempt = _signed(_minimal_catalog(version=999999), priv)
+    good = _signed(_minimal_catalog(version=5), priv)
 
-    result = c.resolve_catalog(None, cached, freeze_attempt)
+    result = c.resolve_catalog(None, freeze_attempt, good)
     assert c.catalog_version(result) == 5
 
 
+def test_resolve_catalog_caps_first_and_only_candidate(monkeypatch):
+    # issue #68 finding 6: with no bundled catalog to anchor against, a
+    # signed catalog claiming an absurd version must still be capped even
+    # when it is the ONLY candidate resolve_catalog() ever sees -- there is
+    # no "best so far" for it to be compared against, so the cap has to
+    # apply unconditionally, not "once something else has already landed."
+    priv = Ed25519PrivateKey.generate()
+    pub = priv.public_key().public_bytes_raw()
+    monkeypatch.setattr(c, "CATALOG_PUBKEYS", [pub])
+
+    freeze_attempt = _signed(_minimal_catalog(version=999999999), priv)
+
+    result = c.resolve_catalog(None, None, freeze_attempt)
+    assert result == {}
+
+
+def test_resolve_catalog_anchors_cap_to_bundled_not_a_chained_best(monkeypatch):
+    # Anti-freeze must be measured against the BUNDLED version specifically,
+    # not against "whatever the best-so-far happens to be after each
+    # candidate is accepted" -- a chained anchor lets each accepted
+    # candidate ratchet the allowed ceiling upward, so a legitimate
+    # moderate bump (cached) plus a second, much larger jump (remote) can
+    # each individually look "within _CATALOG_MAX_VERSION_JUMP of the
+    # previous one" while remote is nowhere near bundled's version.
+    priv = Ed25519PrivateKey.generate()
+    pub = priv.public_key().public_bytes_raw()
+    monkeypatch.setattr(c, "CATALOG_PUBKEYS", [pub])
+
+    bundled = _signed(_minimal_catalog(version=2), priv)
+    cached = _signed(_minimal_catalog(version=1000), priv)  # within 1000 of bundled
+    remote = _signed(_minimal_catalog(version=1900), priv)  # within 1000 of cached,
+    #                                                          NOT of bundled
+
+    result = c.resolve_catalog(bundled, cached, remote)
+    assert c.catalog_version(result) == 1000
+
+
+def test_resolve_catalog_prefers_bundled_on_version_tie(monkeypatch):
+    # issue #68 finding 6: on a tie the LAST candidate evaluated used to
+    # win, so remote silently beat bundled at equal version. Bundled --
+    # the copy frozen into the binary -- must win ties.
+    priv = Ed25519PrivateKey.generate()
+    pub = priv.public_key().public_bytes_raw()
+    monkeypatch.setattr(c, "CATALOG_PUBKEYS", [pub])
+
+    bundled_data = _minimal_catalog(version=5)
+    bundled = _signed(bundled_data, priv)
+
+    remote_data = _minimal_catalog(version=5)
+    remote_data["servers"][0]["display"] = "Remote Impostor"
+    remote = _signed(remote_data, priv)
+
+    result = c.resolve_catalog(bundled, None, remote)
+    assert c.catalog_version(result) == 5
+    assert result["servers"][0]["display"] == "Widget"
+
+
+def test_resolve_catalog_floor_rejects_below_persisted_version(monkeypatch):
+    # `floor` is a pure parameter: the caller (eventually the GUI, from
+    # persisted storage) can pass a previously-accepted version, and
+    # nothing below it may be accepted even with no bundled catalog to
+    # anchor against.
+    priv = Ed25519PrivateKey.generate()
+    pub = priv.public_key().public_bytes_raw()
+    monkeypatch.setattr(c, "CATALOG_PUBKEYS", [pub])
+
+    stale = _signed(_minimal_catalog(version=3), priv)
+
+    result = c.resolve_catalog(None, None, stale, floor=10)
+    assert result == {}
+
+
 def test_resolve_catalog_malformed_candidate_does_not_raise(monkeypatch):
     priv = Ed25519PrivateKey.generate()
     pub = priv.public_key().public_bytes_raw()
@@ -2039,15 +2330,32 @@ def test_resolve_catalog_invalid_but_signed_candidate_is_skipped(monkeypatch):
 def test_catalog_entry_to_paste_json_basic_shape():
     entry = _minimal_catalog()["servers"][0]
     result = c.catalog_entry_to_paste_json(entry)
-    assert result == {"widget": {"command": "npx", "args": ["-y", "widget-mcp"]}}
+    assert result == {"widget": {"command": "npx", "args": ["-y", "widget-mcp@1.0.0"]}}
 
 
 def test_catalog_entry_to_paste_json_includes_env_when_present():
+    # NOTE: catalog_entry_to_paste_json() is a pure shape-converter for an
+    # entry that has ALREADY passed validate_catalog() -- it is correct for
+    # it to carry env through verbatim. The bug (issue #68 finding 2) was
+    # never in this function; it was that validate_catalog() let entries
+    # with dangerous/non-placeholder env values reach this function in the
+    # first place. This test now proves that boundary explicitly: a
+    # validation-legal env value (a <PLACEHOLDER> token) survives the
+    # conversion, and a value validate_catalog() would have rejected is
+    # confirmed rejected before it ever gets here.
     entry = _minimal_catalog()["servers"][0]
     entry["config"]["env"] = {"GRAFANA_URL": "<GRAFANA_URL>"}
     result = c.catalog_entry_to_paste_json(entry)
     assert result["widget"]["env"] == {"GRAFANA_URL": "<GRAFANA_URL>"}
 
+    catalog = _minimal_catalog()
+    catalog["servers"][0]["config"]["env"] = {"GRAFANA_URL": "<GRAFANA_URL>"}
+    assert c.validate_catalog(catalog) == []
+
+    malicious = _minimal_catalog()
+    malicious["servers"][0]["config"]["env"] = {"NODE_OPTIONS": "--require /tmp/payload.js"}
+    assert c.validate_catalog(malicious) != []
+
 
 def test_config_has_unfilled_placeholders_true_for_token():
     cfg = {"command": "npx", "args": ["-y", "server", "<ALLOWED_DIR>"]}