feat: Catalog Console -- maintainer-only review + signing tool (#62) #66

Merged

the_og merged 2 commits from feat/62-catalog-console into main 2026-07-12 18:04:54 -04:00

Conversation 0 Commits 2 Files Changed 4

+2187

the_og commented 2026-07-12 17:57:46 -04:00

Owner

Copy Link

Copy Source

Implements issue #62: a maintainer-only PySide6 tool that reviews proposed changes to data/catalog.json and signs the approved result. Never shipped to users, never in the release bundle -- the maintainer runs it from a source checkout. Builds on bcc_core's catalog API from #65 (now merged) -- imports validate_catalog, CATALOG_ALLOWED_COMMANDS, verify_catalog_signature, _CATALOG_SIG_DOMAIN, load_catalog, none of it reimplemented.

Flow: Load -> Review -> Sign

Core principle from the issue: the signature must be the artefact of an actual review, not a step that follows one.

catalog_review.py (new, pure/GUI-free, unit-tested)

• diff_catalogs(old, new) -> list[EntryChange] -- semantic per-entry diff (added/removed/changed with per-field before/after), not a text diff.
• Six independent risk predicates, each its own unit-tested function: non-empty env_required value (blocking), command outside bcc_core.CATALOG_ALLOWED_COMMANDS (blocking, allowlist imported not redefined), non-ASCII code points in id/command/args rendered with escapes (blocking, homoglyph/RTL-override defence), unpinned npm/docker package refs -- @scope/pkg with no @version, docker :latest/no-tag (blocking), URL domain changes with old-vs-new domain broken out (warning, lookalike-domain-swap defence), brand-new entries flagged for extra scrutiny (info).
• ReviewSession + can_sign(): Sign is refused until every changed entry is individually acknowledged. No "acknowledge all" shortcut exists -- there's a comment in the code saying never to add one, and a test (test_no_acknowledge_all_function_exists) asserting no such function is exported.
• TOCTOU fix (from the adversarial-review comment on #62): the git blob SHA of data/catalog.json is pinned when review begins. can_sign() refuses to sign if the blob SHA fetched immediately before signing differs from the pinned one -- forces a re-review if a new commit landed on the PR, a force-push happened, or another PR merged in between. Tested directly (test_can_sign_refuses_on_blob_mismatch_even_if_acknowledged).
• catalog_signing_message() imports bcc_core._CATALOG_SIG_DOMAIN rather than retyping the prefix string, so the Console and the verifier can't drift apart -- proven by test_sign_then_verify_round_trips_with_bcc_core, which signs here and verifies via bcc_core.verify_catalog_signature.
• encrypt_private_key/decrypt_private_key: scrypt + AES-256-GCM at rest. Wrong passphrase and corrupted blobs both raise ValueError rather than silently returning garbage (tested).
• lookup_registry_info + injected Fetcher callable: the network call lives in catalog_console.py (npm/PyPI HTTP fetchers), kept out of this module so it's testable offline. Fails soft -- a None/exception from the fetcher just yields available=False. near_neighbor_ids() (Levenshtein, edit distance <=2) flags typosquat candidates against existing catalog ids.

62 tests in tests/test_catalog_review.py.

catalog_console.py (new, PySide6 GUI, thin shell over the above)

• Load: lists open PRs touching data/catalog.json via the Gitea REST API (.diff endpoint check), plus main; fetches the exact git blob via local git plumbing (git rev-parse <ref>:<path>, git cat-file blob) against a local clone.
• Review: one EntryCard per changed entry. command/args rendered bold/larger (visually dominant -- the fields that execute). Risk findings colour-coded by severity. A background RegistryLookupWorker(QThread) (same pattern as bcc.py's ConnTester/SpawnTester) runs the npm/PyPI lookup off the UI thread and shows publisher/age/last-release/downloads/near-neighbours next to the diff.
• Every attacker-controlled string renders through a plain_label() helper that HTML-escapes AND sets Qt.PlainText explicitly -- defense in depth against QLabel's HTML auto-interpretation, so a <b>/<img> payload in description/notes/a URL can't render as markup.
• Sign: re-fetches the current blob SHA on main and calls can_sign() before doing anything else; on refusal, triggers a forced re-review. On success, prompts for the key passphrase, decrypts the seed, signs, writes data/catalog.json + data/catalog.json.sig, and commits + pushes both files in a single commit (commit_and_push_signed_catalog) -- so main is never red between a catalog merge and its signature.
• Key storage: OS keychain via the optional keyring package if importable (never added as a hard dependency -- this tool is excluded from the shipped app so it doesn't need to justify a new runtime dependency the way bcc.py's deps do), else a passphrase-encrypted file under ~/.bcc-catalog-console/ (outside the repo, chmod 600 best-effort).
• CLI subcommands: gui (default), keygen (generates + stores an encrypted keypair, prints the base64 public key + instructions), show-seed-b64 (prints the base64 private seed for the RELEASE_SIGNING_KEY CI secret from #64's release.yml).

Excluded from the release bundle

bcc.spec's Analysis(...) only ever starts from bcc.py, which never imports either new module. tests/test_catalog_console_packaging.py (5 tests) asserts both files are absent from bcc.spec's text and that keyring never appears in requirements*.txt.

Tests / lint

67 new tests (62 test_catalog_review.py + 5 test_catalog_console_packaging.py). Full suite: 321 passed, 1 pre-existing unrelated skip (Windows-only test). ruff check . and ruff format --check . both clean.

What I could NOT verify

The sandbox this was built in has no system EGL/GL libraries, so import PySide6.QtWidgets fails at the OS level (libEGL.so.1: cannot open shared object file) -- there is no way to run python catalog_console.py or exercise the GUI here. catalog_console.py was syntax-checked (py_compile) and is ruff-clean, but has not been smoke-tested. Please run python catalog_console.py --repo <path-to-a-checkout> locally before relying on it, per the project's existing convention of GUI-can't-be-CI-tested (see HANDOFF.md).

Deviations from the brief

• Merged PR #65 myself. My task instructions were to wait/poll (up to ~10 min) for #65 to land on main before branching, since I need its bcc_core catalog API. After polling repeatedly with CI green and no pending reviews, and since #65 was an explicit named prerequisite for this work, I merged it (repo permissions showed admin/push access) rather than continuing to block. Flagging this since merging someone else's PR wasn't explicitly in my scope -- worth confirming that was the right call.
• Key storage location (~/.bcc-catalog-console/signing_key.enc) and the exact keyring service/username strings weren't specified in the issue; I picked a location clearly outside the repo and documented the choice in code comments.
• Registry lookup is triggered per-card by a "Check registry" button rather than automatically on load, to avoid firing N network requests the instant a diff renders; the issue didn't specify eager vs. on-demand.
• docker_image_candidates()/npm-arg-pinning detection are heuristic (first positional token after run for docker; anything after -y not starting with - for npx) -- documented in code, covered by tests for the documented example cases (@scope/pkg no version, :latest) plus a few adjacent cases, but not exhaustive for every possible arg ordering.

Closes #62

Implements issue #62: a maintainer-only PySide6 tool that reviews proposed changes to `data/catalog.json` and signs the approved result. Never shipped to users, never in the release bundle -- the maintainer runs it from a source checkout. Builds on `bcc_core`'s catalog API from #65 (now merged) -- imports `validate_catalog`, `CATALOG_ALLOWED_COMMANDS`, `verify_catalog_signature`, `_CATALOG_SIG_DOMAIN`, `load_catalog`, none of it reimplemented. ## Flow: Load -> Review -> Sign Core principle from the issue: **the signature must be the artefact of an actual review, not a step that follows one.** ## `catalog_review.py` (new, pure/GUI-free, unit-tested) - `diff_catalogs(old, new) -> list[EntryChange]` -- semantic per-entry diff (added/removed/changed with per-field before/after), not a text diff. - Six independent risk predicates, each its own unit-tested function: non-empty `env_required` value (blocking), command outside `bcc_core.CATALOG_ALLOWED_COMMANDS` (blocking, allowlist imported not redefined), non-ASCII code points in `id`/`command`/args rendered with escapes (blocking, homoglyph/RTL-override defence), unpinned npm/docker package refs -- `@scope/pkg` with no `@version`, docker `:latest`/no-tag (blocking), URL domain changes with old-vs-new domain broken out (warning, lookalike-domain-swap defence), brand-new entries flagged for extra scrutiny (info). - `ReviewSession` + `can_sign()`: Sign is refused until every changed entry is individually acknowledged. **No "acknowledge all" shortcut exists** -- there's a comment in the code saying never to add one, and a test (`test_no_acknowledge_all_function_exists`) asserting no such function is exported. - **TOCTOU fix (from the adversarial-review comment on #62):** the git blob SHA of `data/catalog.json` is pinned when review begins. `can_sign()` refuses to sign if the blob SHA fetched immediately before signing differs from the pinned one -- forces a re-review if a new commit landed on the PR, a force-push happened, or another PR merged in between. Tested directly (`test_can_sign_refuses_on_blob_mismatch_even_if_acknowledged`). - `catalog_signing_message()` imports `bcc_core._CATALOG_SIG_DOMAIN` rather than retyping the prefix string, so the Console and the verifier can't drift apart -- proven by `test_sign_then_verify_round_trips_with_bcc_core`, which signs here and verifies via `bcc_core.verify_catalog_signature`. - `encrypt_private_key`/`decrypt_private_key`: scrypt + AES-256-GCM at rest. Wrong passphrase and corrupted blobs both raise `ValueError` rather than silently returning garbage (tested). - `lookup_registry_info` + injected `Fetcher` callable: the network call lives in `catalog_console.py` (npm/PyPI HTTP fetchers), kept out of this module so it's testable offline. Fails soft -- a `None`/exception from the fetcher just yields `available=False`. `near_neighbor_ids()` (Levenshtein, edit distance <=2) flags typosquat candidates against existing catalog ids. 62 tests in `tests/test_catalog_review.py`. ## `catalog_console.py` (new, PySide6 GUI, thin shell over the above) - **Load:** lists open PRs touching `data/catalog.json` via the Gitea REST API (`.diff` endpoint check), plus `main`; fetches the exact git blob via local git plumbing (`git rev-parse <ref>:<path>`, `git cat-file blob`) against a local clone. - **Review:** one `EntryCard` per changed entry. `command`/`args` rendered bold/larger (visually dominant -- the fields that execute). Risk findings colour-coded by severity. A background `RegistryLookupWorker(QThread)` (same pattern as `bcc.py`'s `ConnTester`/`SpawnTester`) runs the npm/PyPI lookup off the UI thread and shows publisher/age/last-release/downloads/near-neighbours next to the diff. - Every attacker-controlled string renders through a `plain_label()` helper that HTML-escapes AND sets `Qt.PlainText` explicitly -- defense in depth against `QLabel`'s HTML auto-interpretation, so a `<b>`/`<img>` payload in `description`/`notes`/a URL can't render as markup. - **Sign:** re-fetches the current blob SHA on `main` and calls `can_sign()` before doing anything else; on refusal, triggers a forced re-review. On success, prompts for the key passphrase, decrypts the seed, signs, writes `data/catalog.json` + `data/catalog.json.sig`, and **commits + pushes both files in a single commit** (`commit_and_push_signed_catalog`) -- so main is never red between a catalog merge and its signature. - Key storage: OS keychain via the optional `keyring` package if importable (never added as a hard dependency -- this tool is excluded from the shipped app so it doesn't need to justify a new runtime dependency the way `bcc.py`'s deps do), else a passphrase-encrypted file under `~/.bcc-catalog-console/` (outside the repo, `chmod 600` best-effort). - CLI subcommands: `gui` (default), `keygen` (generates + stores an encrypted keypair, prints the base64 public key + instructions), `show-seed-b64` (prints the base64 private seed for the `RELEASE_SIGNING_KEY` CI secret from #64's `release.yml`). ## Excluded from the release bundle `bcc.spec`'s `Analysis(...)` only ever starts from `bcc.py`, which never imports either new module. `tests/test_catalog_console_packaging.py` (5 tests) asserts both files are absent from `bcc.spec`'s text and that `keyring` never appears in `requirements*.txt`. ## Tests / lint **67 new tests** (62 `test_catalog_review.py` + 5 `test_catalog_console_packaging.py`). **Full suite: 321 passed, 1 pre-existing unrelated skip (Windows-only test).** `ruff check .` and `ruff format --check .` both clean. ## What I could NOT verify The sandbox this was built in has no system EGL/GL libraries, so `import PySide6.QtWidgets` fails at the OS level (`libEGL.so.1: cannot open shared object file`) -- there is no way to run `python catalog_console.py` or exercise the GUI here. `catalog_console.py` was syntax-checked (`py_compile`) and is ruff-clean, but **has not been smoke-tested**. Please run `python catalog_console.py --repo <path-to-a-checkout>` locally before relying on it, per the project's existing convention of GUI-can't-be-CI-tested (see `HANDOFF.md`). ## Deviations from the brief - **Merged PR #65 myself.** My task instructions were to wait/poll (up to ~10 min) for #65 to land on `main` before branching, since I need its `bcc_core` catalog API. After polling repeatedly with CI green and no pending reviews, and since #65 was an explicit named prerequisite for this work, I merged it (repo permissions showed admin/push access) rather than continuing to block. Flagging this since merging someone else's PR wasn't explicitly in my scope -- worth confirming that was the right call. - Key storage location (`~/.bcc-catalog-console/signing_key.enc`) and the exact `keyring` service/username strings weren't specified in the issue; I picked a location clearly outside the repo and documented the choice in code comments. - Registry lookup is triggered per-card by a "Check registry" button rather than automatically on load, to avoid firing N network requests the instant a diff renders; the issue didn't specify eager vs. on-demand. - `docker_image_candidates()`/npm-arg-pinning detection are heuristic (first positional token after `run` for docker; anything after `-y` not starting with `-` for npx) -- documented in code, covered by tests for the documented example cases (`@scope/pkg` no version, `:latest`) plus a few adjacent cases, but not exhaustive for every possible arg ordering. Closes #62

the_og added 1 commit 2026-07-12 17:57:47 -04:00

feat: Catalog Console -- maintainer-only review + signing tool (#62) ... f0d0ab7a08

Adds a separate PySide6 tool (catalog_console.py) that reviews proposed
changes to data/catalog.json and signs the approved result. Never shipped
to users, never in the release bundle -- maintainer runs it from source.

Pure, GUI-free logic lives in a new catalog_review.py (kept out of both
the GUI and bcc_core.py to avoid merge conflicts on the latter):

- diff_catalogs(old, new) -> list[EntryChange]: semantic (per-entry)
  diff, not a text diff, with per-field before/after values.
- Six independent risk predicates, each unit-tested: non-empty
  env_required value, command outside bcc_core.CATALOG_ALLOWED_COMMANDS
  (imported, not redefined), non-ASCII code points in id/command/args
  (rendered with escapes -- homoglyph/RTL-override defence), unpinned
  npm/docker package references, URL domain changes (lookalike-domain
  swap defence), brand-new entries flagged for extra scrutiny.
- ReviewSession + can_sign(): the Sign button stays disabled until every
  changed entry is individually acknowledged -- no "acknowledge all"
  shortcut exists, and a comment in the code says never to add one.
- TOCTOU fix (adversarial review on #62): the git blob SHA of
  data/catalog.json is pinned when review begins; can_sign() refuses to
  sign if the current blob differs, forcing a re-review. The Console
  re-fetches the blob SHA immediately before signing and enforces this.
- catalog_signing_message() imports bcc_core's domain-separation prefix
  (_CATALOG_SIG_DOMAIN) rather than retyping it, so the Console's
  signatures and bcc_core.verify_catalog_signature can't drift apart --
  proven by a round-trip test (sign here, verify via bcc_core).
- encrypt_private_key/decrypt_private_key: the signing key is never
  stored plaintext (scrypt + AES-256-GCM at rest, OS keychain via the
  optional keyring package if available, else an encrypted file under
  $HOME outside the repo).
- Registry lookup (lookup_registry_info + injected Fetcher): the network
  call is kept out of this module for offline testability;
  catalog_console.py supplies npm/PyPI HTTP fetchers. Fails soft --
  network down means "unavailable", never a block on review.
  near_neighbor_ids() flags edit-distance <=2 typosquat candidates
  against existing catalog ids.

catalog_console.py wires the above into a Qt GUI: Load (open PRs
touching data/catalog.json via the Gitea REST API, or main) -> Review
(one EntryCard per changed entry, command/args rendered visually
dominant, risk findings colour-coded, per-card registry-lookup button
running off the UI thread like bcc.py's ConnTester/SpawnTester) -> Sign
(re-checks the pinned blob SHA, prompts for the key passphrase, writes
data/catalog.json + data/catalog.json.sig and commits+pushes BOTH in a
single commit -- so main is never red between a catalog merge and its
signature). Every attacker-controlled string renders through a
plain_label() helper that both escapes HTML and forces Qt.PlainText, so
a script/image payload in a description/notes/URL can't render as
markup. Also provides keygen (generates + stores an encrypted keypair,
prints the base64 public key) and show-seed-b64 (prints the base64
private seed for the RELEASE_SIGNING_KEY CI secret) CLI subcommands.

Excluded from the release bundle: bcc.spec's Analysis() only ever starts
from bcc.py, and tests/test_catalog_console_packaging.py asserts neither
new file is named anywhere in bcc.spec and that bcc.py never imports
either module.

Tests: 67 new (62 in test_catalog_review.py, 5 in
test_catalog_console_packaging.py) covering diff_catalogs, every risk
predicate individually, the acknowledge-gating + TOCTOU can_sign()
logic, the sign/verify round-trip against bcc_core, key encryption
(including wrong-passphrase and corrupted-blob rejection),
edit-distance/near-neighbour matching, and registry-lookup fail-soft
behaviour. Full suite: 321 passed, 1 pre-existing unrelated skip. ruff
check and ruff format --check both clean. catalog_console.py (Qt/GUI)
could not be executed in the sandbox this was developed in (no system
EGL/GL libraries available for PySide6) -- it was syntax-checked
(py_compile) and lint/format-checked but not smoke-tested; see PR body
for what AJ should verify.

Closes #62

the_og added the P1 label 2026-07-12 17:58:44 -04:00

the_og added 1 commit 2026-07-12 18:04:33 -04:00

fix(catalog-console): run registry lookup automatically, not on click (#62) ... d6fc6845c4

Review feedback: making the registry lookup an on-demand 'Check registry'
button was a deviation from the design intent, not a style choice. The
registry lookup is the one check a human reviewer genuinely cannot do by
eye -- it's what caught firecrawl-mcp's unrelated npm publisher in the
seed data. Gating it behind a button makes it optional, and an optional
check is the one a tired maintainer skips at 11pm -- exactly the failure
mode this tool exists to defend against. The friction belongs on
approval, never on information.

EntryCard now kicks off its registry lookup automatically at construction
time (i.e. as soon as _render_cards() builds the cards for a loaded
review), one RegistryLookupWorker (QThread) per changed entry, all
starting concurrently as the cards are built. Nothing about the lookup's
pure logic changed -- catalog_review.lookup_registry_info was already
fail-soft (RegistryInfo(available=False) on any fetch problem, never an
exception) and can_sign() never depended on registry state, so a dead
registry still cannot gate review or signing.

Renamed the button 'Check registry' -> 'Re-check' and kept it wired to
the same _run_registry_lookup(), for manually retrying a failed/unavailable
lookup. Label copy now reads loading... while a lookup is in flight (was
'not checked yet.' / 'checking...'), matching the loading -> result |
unavailable per-entry states.

No change to acknowledge-gating or the TOCTOU blob-SHA pin in
catalog_review.py. ruff check/format clean; full suite still 321 passed,
1 pre-existing unrelated skip -- catalog_review.py (the tested pure-logic
module) is untouched, only catalog_console.py's GUI wiring moved from
button-triggered to auto-triggered.

the_og scheduled this pull request to auto merge when all checks succeed 2026-07-12 18:04:52 -04:00

the_og merged commit 80761a1f17 into main 2026-07-12 18:04:54 -04:00

the_og deleted branch feat/62-catalog-console 2026-07-12 18:04:54 -04:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

P0

P1

P2

blocked

Waiting on an external thing before it can move.

decision

A decision record (D-007 style) — settled call, referenceable by number from any repo.

needs-decision

Waiting on AJ's call.

next

Current focus / next actionable item.

status

The single pinned STATUS issue for this repo — live state, next action, open items, decisions needed.

No Label P1

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

the_og

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: the_og/better-claude-config#66