the_og/better-claude-config
1
0
Fork 0
Code Issues 8 Pull Requests 3 Actions Packages Projects Releases 4 Wiki Activity

fix(catalog-console): close the vacuous review gate; split catalog/release signing keys
CI / Lint (ruff) (pull_request) Successful in 9s
Details
CI / Tests (py3.10 / ubuntu-latest) (pull_request) Successful in 11s
Details
CI / Tests (py3.12 / windows-latest) (pull_request) Successful in 34s
Details
CI / Tests (py3.12 / ubuntu-latest) (pull_request) Successful in 9s
Details
CI / Tests (py3.13 / ubuntu-latest) (pull_request) Successful in 10s
Details
CI / Catalog signature (pull_request) Successful in 6s
Details

Browse Source 
Fixes #68 findings 1 and 5.

Finding 1 -- the review gate signed without reviewing anything:
- ReviewWindow._on_sign hardcoded "main" as the TOCTOU comparison ref, so
  any PR review (where _on_load pins the PR head's blob SHA) could never
  sign; the only working path was main-vs-itself, whose empty diff made
  can_sign() vacuously True (set() <= set()). Commit b08cf21 signed 19
  entries through exactly that path with zero of them reviewed.
- can_sign() now refuses an empty changeset outright, and itself checks
  has_blocking_risk() across every changed entry rather than trusting the
  GUI to have disabled a checkbox.
- ReviewSession now carries loaded_ref (the exact ref reviewed); a new pure
  sign_precondition(session, resolve_blob_sha) resolves the TOCTOU SHA from
  that ref, never a hardcoded "main". _on_load's retry path re-diffs
  instead of re-pinning the same stale SHA, so a blob-mismatch refusal
  can't loop forever.
- source="main" now diffs against the last catalog a maintainer actually
  SIGNED (walking catalog.json's git history until a version verifies
  against the current .sig), not against itself.
- Replaced the theatre-only test_no_acknowledge_all_function_exists (only
  asserted no function was *named* acknowledge_all) with a test that also
  exercises the real gate. Added can_sign/sign_precondition coverage for
  the empty-diff, blocking-risk, and ref-resolution seams -- each verified
  to fail when its guard is removed.

Finding 5 -- the catalog key and release key were the same CI-resident key:
- scripts/sign_checksums.py gets its own RELEASE_PUBKEYS (separate from
  bcc_core.CATALOG_PUBKEYS) and a verify_checksums_against_any() helper.
- release.yml's signing-smoke-test now verifies RELEASE_SIGNING_KEY against
  RELEASE_PUBKEYS only -- it no longer imports bcc_core/CATALOG_PUBKEYS at
  all, so this workflow can never compare a CI secret against the
  catalog's root of trust.
- catalog_console.py: keygen/show-seed-b64 gain --release, with separate
  keychain/file storage per key kind. show-seed-b64 refuses to run without
  --release, so the catalog seed can't be exported to a CI secret by habit.
- README documents both keys' trust properties and the asymmetry: a CI
  compromise burns the release key, never the catalog key.

The maintainer must rotate the catalog key (it was CI-resident, so treat it
as burned for catalog use) and generate a fresh release key -- see the PR
description for the exact steps. No key is generated or committed here.
This commit is contained in:
BCC Fix Agent
2026-07-12 21:25:34 -04:00
parent 6fce19cc67
commit 82483e693d
6 changed files with 628 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files
catalog_console.py
+262 -61
View File
@@ -12,7 +12,12 @@ Flow: Load -> Review -> Sign.
1. Load -- pick a source: an open Gitea PR touching data/catalog.json,
or the current tip of `main`. The Console fetches the exact
git blob (via a local clone's git plumbing) and PINS its
blob SHA for the rest of this review pass.
blob SHA *and the ref it came from* for the rest of this
review pass. For a PR, the diff is against `main`; for
`main`, the diff is against the last catalog a maintainer
actually SIGNED (the bytes covered by the current
data/catalog.json.sig), never against itself -- an empty
diff must mean "nothing to sign", never "sign unlocked".
2. Review -- a semantic diff (catalog_review.diff_catalogs), one card per
changed entry, with risk annotations
(catalog_review.entry_risk_findings). A registry lookup for
@@ -25,20 +30,34 @@ Flow: Load -> Review -> Sign.
changed entry must be individually acknowledged (its
checkbox ticked) before Sign unlocks. There is no
"acknowledge all" -- see catalog_review.py.
3. Sign -- re-fetches the current blob SHA and refuses to sign unless
it still matches the pinned SHA from step 1 (TOCTOU fix:
catalog_review.can_sign). On success, writes
3. Sign -- re-resolves the current blob SHA from the SAME ref that was
reviewed (never a hardcoded "main") and refuses to sign
unless it still matches the pinned SHA from step 1, the diff
is non-empty, and no changed entry has an outstanding
blocking risk finding (catalog_review.sign_precondition /
can_sign -- the TOCTOU fix). On success, writes
data/catalog.json + data/catalog.json.sig and commits BOTH
in a single commit, then pushes -- so main is never red
between a catalog merge and its signature.
between a catalog merge and its signature. Signing uses the
CATALOG key ONLY -- see "Two signing keys" below.
The signature must be the artefact of an actual review, not a step that
follows one. Signing IS the approval act.
Two signing keys (issue #68 finding 5): the CATALOG key (offline,
Console-only, `keygen` / `keygen --release` picks which) is the root of
trust for what BCC executes and must never touch CI. The RELEASE key is
CI-resident and signs ONLY the release SHA256SUMS manifest
(scripts/sign_checksums.py) -- `show-seed-b64 --release` is the only
supported way to get a seed out of this tool, and it refuses to run without
`--release` so the catalog seed can never be exported by habit. See the
README's "Signing keys" section.
"""
from __future__ import annotations
import argparse
import base64
import contextlib
import getpass
import html
@@ -69,8 +88,28 @@ SIG_PATH = "data/catalog.json.sig"
# maintainer-only tool, so a dotfile under $HOME is an acceptable fallback
# when the OS keychain isn't available -- the blob stored there is always
# passphrase-encrypted (see catalog_review.encrypt_private_key), never raw.
#
# Two SEPARATE keys are stored here, never conflated (issue #68 finding 5):
# "catalog" -- offline, Console-only. Verified by bcc_core.CATALOG_PUBKEYS.
# Roots of trust for every catalog entry BCC ships. Must
# NEVER leave this machine, never touch CI, never become an
# env var or a repo secret.
# "release" -- CI-resident. Verified by scripts.sign_checksums.
# RELEASE_PUBKEYS. Signs ONLY the release SHA256SUMS
# manifest. Its private seed is deliberately meant to be
# pasted into the RELEASE_SIGNING_KEY Gitea Actions secret
# (via `show-seed-b64 --release`) -- that is its normal,
# intended flow. A CI compromise burns this key, not the
# catalog key: that asymmetry is the whole point of having
# two keys instead of one.
KEY_STORAGE_DIR = Path.home() / ".bcc-catalog-console"
KEY_STORAGE_FILE = KEY_STORAGE_DIR / "signing_key.enc"
_KEY_KINDS = ("catalog", "release")
def _key_storage_file(kind: str) -> Path:
assert kind in _KEY_KINDS, f"unknown key kind {kind!r}, expected one of {_KEY_KINDS}"
return KEY_STORAGE_DIR / f"signing_key_{kind}.enc"
HTTP_TIMEOUT = 6.0
@@ -97,51 +136,64 @@ def _keyring_module():
_KEYRING_SERVICE = "bcc-catalog-console"
_KEYRING_USERNAME = "signing-key"
def store_encrypted_key(blob: bytes) -> str:
def _keyring_username(kind: str) -> str:
assert kind in _KEY_KINDS, f"unknown key kind {kind!r}, expected one of {_KEY_KINDS}"
return f"signing-key-{kind}"
def store_encrypted_key(blob: bytes, kind: str = "catalog") -> str:
"""Persist an already-encrypted key blob (see
catalog_review.encrypt_private_key). Prefers the OS keychain; falls back
to a file under KEY_STORAGE_DIR (outside the repo) with restrictive
catalog_review.encrypt_private_key) under the given `kind`
("catalog" or "release" -- see the KEY_STORAGE_DIR comment above; the
two are stored under different keychain entries / filenames so they can
never be loaded interchangeably). Prefers the OS keychain; falls back to
a file under KEY_STORAGE_DIR (outside the repo) with restrictive
permissions. Returns a human-readable description of where it went."""
keyring = _keyring_module()
if keyring is not None:
try:
keyring.set_password(_KEYRING_SERVICE, _KEYRING_USERNAME, blob.hex())
keyring.set_password(_KEYRING_SERVICE, _keyring_username(kind), blob.hex())
return "OS keychain (via the `keyring` package)"
except Exception:
pass # fall through to the file-based path
KEY_STORAGE_DIR.mkdir(parents=True, exist_ok=True)
KEY_STORAGE_FILE.write_bytes(blob)
key_file = _key_storage_file(kind)
key_file.write_bytes(blob)
with contextlib.suppress(OSError): # best-effort on platforms without POSIX perm bits
KEY_STORAGE_FILE.chmod(0o600)
return f"encrypted file at {KEY_STORAGE_FILE}"
key_file.chmod(0o600)
return f"encrypted file at {key_file}"
def load_encrypted_key() -> bytes:
"""Load the encrypted key blob from wherever store_encrypted_key() put
it. Raises FileNotFoundError if no key has been generated yet."""
def load_encrypted_key(kind: str = "catalog") -> bytes:
"""Load the encrypted key blob of the given `kind` from wherever
store_encrypted_key() put it. Raises FileNotFoundError if no key of that
kind has been generated yet."""
keyring = _keyring_module()
if keyring is not None:
try:
hex_blob = keyring.get_password(_KEYRING_SERVICE, _KEYRING_USERNAME)
hex_blob = keyring.get_password(_KEYRING_SERVICE, _keyring_username(kind))
if hex_blob:
return bytes.fromhex(hex_blob)
except Exception:
pass
if not KEY_STORAGE_FILE.exists():
key_file = _key_storage_file(kind)
if not key_file.exists():
flag = " --release" if kind == "release" else ""
raise FileNotFoundError(
f"No signing key found (checked the OS keychain and {KEY_STORAGE_FILE}). "
"Run `python catalog_console.py keygen` first."
f"No {kind} signing key found (checked the OS keychain and {key_file}). "
f"Run `python catalog_console.py keygen{flag}` first."
)
return KEY_STORAGE_FILE.read_bytes()
return key_file.read_bytes()
def unlock_signing_key(passphrase: str) -> bytes:
"""Load + decrypt the signing key seed. Raises ValueError on a wrong
passphrase, FileNotFoundError if no key exists yet."""
blob = load_encrypted_key()
def unlock_signing_key(passphrase: str, kind: str = "catalog") -> bytes:
"""Load + decrypt the signing key seed of the given `kind`. Raises
ValueError on a wrong passphrase, FileNotFoundError if no key of that
kind exists yet. Defaults to "catalog" because that's the key
ReviewWindow._on_sign uses -- the GUI never touches the release key."""
blob = load_encrypted_key(kind)
return review.decrypt_private_key(blob, passphrase)
@@ -188,6 +240,49 @@ def read_catalog_at_commit(repo_dir: Path, commit: str) -> tuple[bytes, str]:
return blob_bytes(repo_dir, sha), sha
def catalog_blob_history(repo_dir: Path, ref: str, limit: int = 200) -> list[str]:
"""Blob SHAs of CATALOG_PATH at each commit that touched it, walking
back from `ref`, most-recent-first. Used by last_signed_catalog_raw() to
find "the version of the catalog the current signature actually covers"
without assuming it's the tip commit."""
log_out = _git(repo_dir, "log", f"--max-count={limit}", "--format=%H", ref, "--", CATALOG_PATH)
commits = [line for line in log_out.splitlines() if line]
shas: list[str] = []
for commit in commits:
try:
shas.append(blob_sha_at(repo_dir, commit, CATALOG_PATH))
except GitError:
continue
return shas
def last_signed_catalog_raw(repo_dir: Path, commit: str) -> bytes | None:
"""The raw data/catalog.json bytes that verify against
data/catalog.json.sig as of `commit` -- i.e. "the last catalog a
maintainer actually signed", found by walking the catalog's git history
on that ref until a version verifies against the *current* signature.
This is what source="main (current tip)" diffs against (issue #68
finding 1): if main's tip catalog.json already matches its .sig, this
returns that same content and the diff is correctly empty (nothing new
to sign). If someone merged a catalog change to main without running it
through the Console -- the exact bypass that produced commit b08cf21 --
the signature still covers the OLDER content, so this returns that older
version and the diff surfaces exactly what was never actually reviewed.
Returns None if there's no signature yet, or none of the recent history
verifies against it (caller should treat this as "diff against nothing
ever signed", i.e. every current entry shows as newly added).
"""
try:
sig_sha = blob_sha_at(repo_dir, commit, SIG_PATH)
except GitError:
return None
sig_bytes = blob_bytes(repo_dir, sig_sha)
candidates = [blob_bytes(repo_dir, sha) for sha in catalog_blob_history(repo_dir, commit)]
return review.find_last_signed_catalog_raw(candidates, sig_bytes, core.CATALOG_PUBKEYS)
def commit_and_push_signed_catalog(
repo_dir: Path, raw_bytes: bytes, signature: bytes, *, branch: str = "main"
) -> str:
@@ -644,28 +739,50 @@ class ReviewWindow(QMainWindow):
row = self.source_list.currentRow()
try:
if row <= 0:
commit = fetch_ref(self.repo_dir, "main")
old_commit = None # main vs itself has no "old" -- nothing to diff without a base
# source = main: diff against the last catalog a maintainer
# actually SIGNED (the bytes covered by the current
# data/catalog.json.sig), never against itself. Diffing
# main-vs-main is what made an empty diff -> instantly
# "signable" in the first place (issue #68 finding 1) --
# this is the only path that reaches sign_catalog_bytes(),
# so if it can't be trusted nothing can.
loaded_ref = "main"
commit = fetch_ref(self.repo_dir, loaded_ref)
new_raw, new_blob_sha = read_catalog_at_commit(self.repo_dir, commit)
new_catalog = core.load_catalog(new_raw)
old_raw = last_signed_catalog_raw(self.repo_dir, commit)
old_catalog = (
core.load_catalog(old_raw)
if old_raw is not None
else {
"schema": 1,
"version": 0,
"servers": [],
}
)
else:
pr = self._prs[row - 1]
commit = fetch_ref(self.repo_dir, pr.head_ref)
loaded_ref = pr.head_ref
commit = fetch_ref(self.repo_dir, loaded_ref)
old_commit = fetch_ref(self.repo_dir, "main")
new_raw, new_blob_sha = read_catalog_at_commit(self.repo_dir, commit)
new_catalog = core.load_catalog(new_raw)
if old_commit:
new_raw, new_blob_sha = read_catalog_at_commit(self.repo_dir, commit)
new_catalog = core.load_catalog(new_raw)
old_raw, _old_sha = read_catalog_at_commit(self.repo_dir, old_commit)
old_catalog = core.load_catalog(old_raw)
else:
old_catalog = new_catalog
except (GitError, ValueError) as e:
QMessageBox.critical(self, "Load failed", html.escape(str(e)))
return
self._new_raw = new_raw
self.session = review.start_review(new_blob_sha, old_catalog, new_catalog)
# `loaded_ref` is pinned into the session (not just this method's
# local variable) so _on_sign can re-resolve the TOCTOU blob SHA
# from the SAME ref that was reviewed, instead of a hardcoded
# "main" -- see review.sign_precondition and issue #68 finding 1.
self.session = review.start_review(
new_blob_sha, old_catalog, new_catalog, loaded_ref=loaded_ref
)
self._render_cards()
def _render_cards(self):
@@ -706,20 +823,43 @@ class ReviewWindow(QMainWindow):
def _on_sign(self):
assert self.session is not None
def _resolve_blob_sha(ref: str) -> str:
# Re-fetch fresh, immediately before signing, from the SAME ref
# that was reviewed (session.loaded_ref) -- NEVER hardcode
# "main" here. Hardcoding "main" is the bug that made the PR
# review path unable to sign at all: _on_load() pins the PR
# head's blob SHA, so comparing against main's SHA differs by
# definition for any PR that actually changes the catalog, and
# this refused every PR review permanently (see issue #68
# finding 1 and review.sign_precondition's docstring).
return blob_sha_at(self.repo_dir, fetch_ref(self.repo_dir, ref), CATALOG_PATH)
try:
current_sha = blob_sha_at(self.repo_dir, fetch_ref(self.repo_dir, "main"), CATALOG_PATH)
decision = review.sign_precondition(self.session, _resolve_blob_sha)
except GitError as e:
QMessageBox.critical(self, "Sign failed", html.escape(str(e)))
return
decision = review.can_sign(self.session, current_sha)
if not decision.ok:
QMessageBox.warning(self, "Cannot sign", html.escape(decision.reason or ""))
if decision.reason and "changed" in decision.reason.lower():
self._on_load() # force a re-review against the new bytes
# Only the TOCTOU blob-SHA-mismatch reason should trigger a
# reload -- "mismatch" appears ONLY in that reason (deliberately
# checked instead of the broader "changed", which also matches
# "Not every CHANGED entry has been acknowledged yet" and would
# wrongly force a reload -- and with it a fresh review.py
# ReviewSession -- every time a reviewer pauses partway through
# ticking checkboxes).
if decision.reason and "mismatch" in decision.reason.lower():
# Force a genuine re-review against the new bytes -- this
# must call _on_load() (which re-fetches and re-diffs), NOT
# re-invoke the same stale resolver, or this becomes the
# infinite loop described in issue #68 finding 1: re-pinning
# the same wrong SHA forever instead of ever converging.
self._on_load()
return
dialog = PassphraseDialog("Enter signing key passphrase:", self)
dialog = PassphraseDialog("Enter CATALOG signing key passphrase:", self)
if dialog.exec() != QDialog.DialogCode.Accepted:
return
try:
@@ -744,9 +884,17 @@ class ReviewWindow(QMainWindow):
# --------------------------------------------------------------------------- #
def cmd_keygen(_args: argparse.Namespace) -> int:
def cmd_keygen(args: argparse.Namespace) -> int:
# Two SEPARATE keypairs, never conflated (issue #68 finding 5): the
# catalog key is the offline root of trust for what BCC executes and
# must never touch CI; the release key is CI-resident and signs ONLY
# the release SHA256SUMS manifest. Which one this run generates is
# explicit via --release, and the printed instructions differ sharply
# so it's obvious which key is safe to paste into a CI secret (release)
# and which one never is (catalog).
kind = "release" if getattr(args, "release", False) else "catalog"
seed, pubkey = review.generate_keypair()
passphrase = getpass.getpass("Choose a passphrase to encrypt the new signing key: ")
passphrase = getpass.getpass(f"Choose a passphrase to encrypt the new {kind} signing key: ")
confirm = getpass.getpass("Confirm passphrase: ")
if passphrase != confirm:
print("error: passphrases did not match", file=sys.stderr)
@@ -756,31 +904,67 @@ def cmd_keygen(_args: argparse.Namespace) -> int:
return 1
blob = review.encrypt_private_key(seed, passphrase)
where = store_encrypted_key(blob)
pubkey_b64 = __import__("base64").b64encode(pubkey).decode("ascii")
where = store_encrypted_key(blob, kind=kind)
pubkey_b64 = base64.b64encode(pubkey).decode("ascii")
print(f"Private key encrypted and stored in: {where}")
print(f"{kind.capitalize()} private key encrypted and stored in: {where}")
print()
print("Public key (base64, paste into bcc_core.CATALOG_PUBKEYS):")
print(f" {pubkey_b64}")
print()
print(
"Also add it as the Gitea repo secret RELEASE_SIGNING_KEY (base64 of the "
"32-byte private seed) used by release.yml -- get that value with:"
)
print(" python catalog_console.py show-seed-b64 # careful: prints the raw key")
if kind == "catalog":
print(
"This is the CATALOG key. It is the root of trust for every catalog "
"entry BCC ships -- it must stay offline and Console-only. NEVER paste "
"it, its seed, or `show-seed-b64` output into CI, an env var, or a repo "
"secret. (If the key currently in bcc_core.CATALOG_PUBKEYS has ever been "
"pasted into a CI secret, treat it as burned for catalog use -- generate "
"a fresh one with this command and rotate.)"
)
print()
print(
"Public key (base64) -- hand this to whoever maintains bcc_core.py so "
"they can add it to CATALOG_PUBKEYS (this tool does not edit that file):"
)
print(f" {pubkey_b64}")
else:
print(
"This is the RELEASE key. It signs ONLY the release SHA256SUMS "
"manifest in CI -- it is intentionally CI-resident and is NOT trusted "
"to sign the catalog (bcc_core.CATALOG_PUBKEYS does not and must not "
"contain it)."
)
print()
print("1. Public key (base64) -- paste into scripts/sign_checksums.py RELEASE_PUBKEYS:")
print(f" {pubkey_b64}")
print()
print(
"2. Private key -- add it as the Gitea repo secret RELEASE_SIGNING_KEY "
"(base64 of the 32-byte private seed). Get that value with:"
)
print(" python catalog_console.py show-seed-b64 --release # prints the raw key")
return 0
def cmd_show_seed_b64(_args: argparse.Namespace) -> int:
passphrase = getpass.getpass("Signing key passphrase: ")
def cmd_show_seed_b64(args: argparse.Namespace) -> int:
# Deliberately requires --release: this command's whole purpose is to
# produce a value that gets pasted into a CI secret, and the catalog key
# must NEVER be pasted into CI (issue #68 finding 5 -- that is exactly
# how the catalog key ended up burned in the first place). Refusing to
# run without --release makes "export the catalog seed for CI" a
# structurally different, more deliberate action than a typo away.
if not getattr(args, "release", False):
print(
"error: show-seed-b64 only ever exports the RELEASE key -- it is the "
"only key allowed to leave this machine, for the RELEASE_SIGNING_KEY CI "
"secret. Re-run as `show-seed-b64 --release`. The catalog key must never "
"be exported this way; see issue #68 finding 5.",
file=sys.stderr,
)
return 1
passphrase = getpass.getpass("Release signing key passphrase: ")
try:
seed = unlock_signing_key(passphrase)
seed = unlock_signing_key(passphrase, kind="release")
except (FileNotFoundError, ValueError) as e:
print(f"error: {e}", file=sys.stderr)
return 1
import base64
print(base64.b64encode(seed).decode("ascii"))
return 0
@@ -810,11 +994,28 @@ def build_parser() -> argparse.ArgumentParser:
p_gui.add_argument("--repo", default=".", help="path to a BCC git checkout (default: cwd)")
p_gui.set_defaults(func=cmd_gui)
p_keygen = sub.add_parser("keygen", help="generate a new Ed25519 signing keypair")
p_keygen = sub.add_parser(
"keygen", help="generate a new Ed25519 signing keypair (catalog key by default)"
)
p_keygen.add_argument(
"--release",
action="store_true",
help=(
"generate the RELEASE key (CI-resident, signs SHA256SUMS only) instead "
"of the CATALOG key (offline, Console-only, signs data/catalog.json -- "
"see issue #68 finding 5)"
),
)
p_keygen.set_defaults(func=cmd_keygen)
p_seed = sub.add_parser(
"show-seed-b64", help="print the base64 private seed (for the RELEASE_SIGNING_KEY secret)"
"show-seed-b64",
help="print a base64 private seed for a CI secret -- RELEASE key only",
)
p_seed.add_argument(
"--release",
action="store_true",
help="required: only the release key may ever be exported this way",
)
p_seed.set_defaults(func=cmd_show_seed_b64)