pbnightingale 0.2.1__tar.gz

pbnightingale-0.2.1/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"8adf1241-358a-437f-87d1-2fcef27cfd94","pid":382052,"procStart":"3651907","acquiredAt":1789588198490}

pbnightingale-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,172 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+    # Semver tags only (glob syntax — + quantifier not supported by GitHub)
+    tags: ["v[0-9]*.[0-9]*.[0-9]*"]
+  pull_request:
+
+# Cancel in-flight runs for the same ref when a newer push arrives.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ── Tests ────────────────────────────────────────────────────────────────────
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up pixi environment
+        uses: prefix-dev/setup-pixi@v0.10.0
+        with:
+          pixi-version: latest
+          cache: true
+
+      - name: Compile translation catalogues
+        run: pixi run -- pybabel compile -d src/pbnightingale/locale -D pbnightingale
+
+      - name: Run test suite
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: make test
+
+      - name: Upload coverage to Codecov
+        # v6+ is required to pick up codecov-action's own Node 24 runtime
+        # (it was pinned to actions/github-script's Node 20 build through
+        # v5.5.5); no input/behavior change otherwise.
+        uses: codecov/codecov-action@v7
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          fail_ci_if_error: true
+
+  # ── Pre-commit hooks ─────────────────────────────────────────────────────────
+  hooks:
+    name: Pre-commit hooks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up pixi environment
+        uses: prefix-dev/setup-pixi@v0.10.0
+        with:
+          pixi-version: latest
+          cache: true
+
+      - name: Cache pre-commit hook environments
+        uses: actions/cache@v5
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Run hooks on all files
+        run: pixi run -- pre-commit run --all-files
+
+  # ── Documentation ───────────────────────────────────────────────────────────
+  docs:
+    name: Build docs
+    needs: [test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up pixi environment
+        uses: prefix-dev/setup-pixi@v0.10.0
+        with:
+          pixi-version: latest
+          cache: true
+
+      - name: Build HTML documentation
+        run: make docs
+
+      - name: Upload documentation artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: docs-html
+          path: docs/_build/html/
+          if-no-files-found: error
+
+  # ── Build executables ────────────────────────────────────────────────────────
+  build:
+    name: Build / ${{ matrix.os }}
+    needs: [test, hooks]
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up pixi environment
+        uses: prefix-dev/setup-pixi@v0.10.0
+        with:
+          pixi-version: latest
+          cache: true
+
+      - name: Compile translation catalogues
+        # .mo files are gitignored generated artifacts; rebuild from .po sources.
+        run: pixi run -- pybabel compile -d src/pbnightingale/locale -D pbnightingale
+
+      - name: Build with PyInstaller
+        # Call PyInstaller directly to avoid GNU Make portability issues
+        # on Windows runners. Single-line command: the `\` line-continuation
+        # used by bash is not valid PowerShell, the default shell on
+        # windows-latest runners.
+        run: pixi run -- pyinstaller --clean --noconfirm --distpath dist --workpath build/pyinstaller pbnightingale.spec
+
+      - name: Zip .app bundle (macOS)
+        # A .app bundle is a directory; zip it for upload and release attachment.
+        if: runner.os == 'macOS'
+        shell: bash
+        run: |
+          cd dist
+          for app in *.app; do
+            zip -r "${app%.app}.zip" "$app"
+            rm -rf "$app"
+          done
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v7
+        with:
+          # One artifact per runner; merged in the release job.
+          name: build-${{ runner.os }}
+          path: dist/pbnightingale-*
+          if-no-files-found: error
+
+  # ── GitHub release ───────────────────────────────────────────────────────────
+  release:
+    name: Release ${{ github.ref_name }}
+    needs: [build]
+    # Only create a release on semver tags; the tag filter on push already
+    # restricts the trigger, but this guard makes the intent explicit.
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # required to create a release and upload assets
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Download all build artifacts
+        uses: actions/download-artifact@v8
+        with:
+          # Merge all per-OS artifacts into a single flat directory.
+          path: dist
+          merge-multiple: true
+
+      - name: Extract changelog entry for ${{ github.ref_name }}
+        id: changelog
+        run: python3 tools/extract_changelog.py
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v3
+        with:
+          body: ${{ steps.changelog.outputs.body }}
+          files: dist/pbnightingale-*
+          fail_on_unmatched_files: true

pbnightingale-0.2.1/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Sphinx
+docs/_build/
+docs/changelog.rst
+docs/_static/pbnightingale.png
+docs/_static/icons/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Make stamp files
+.translate.stamp
+
+# i18n — generated artifacts, rebuilt on demand by make translate
+*.pot
+*.mo
+tools/_lang_name_stub.py
+
+# Claude Code
+.claude/settings.local.json
+
+# pixi (defensive: environments should live in ~/PIXI/ via the global
+# `pixi config set --global detached-environments`, but this covers
+# machines/accounts where that global config isn't set, so .pixi/
+# never ends up committed)
+.pixi/

pbnightingale-0.2.1/.markdownlint-cli2.yaml

@@ -0,0 +1,12 @@
+config:
+  # Line length not enforced — CHANGELOG bullets and docs are naturally long
+  MD013: false
+  # Duplicate headings allowed when they live under different parent sections
+  # (standard Keep-a-Changelog pattern: ### Added, ### Fixed repeat per release)
+  MD024:
+    siblings_only: true
+
+# CLAUDE.md is intentionally a compact tool-specific file
+ignores:
+  - CLAUDE.md
+  - .pytest_cache/**

pbnightingale-0.2.1/.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        # Default 500 KB is too low for pbnightingale.icns: a macOS .icns
+        # bundles several raster sizes and is a few MB even for a simple
+        # source image — legitimate packaging content, not accidental bloat.
+        args: [--maxkb=3072]
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: debug-statements   # Python only
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.22.1
+    hooks:
+      - id: markdownlint-cli2

pbnightingale-0.2.1/.readthedocs.yaml

@@ -0,0 +1,20 @@
+# Read the Docs configuration
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.14"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - dev
+
+sphinx:
+  configuration: docs/conf.py
+  builder: html
+  fail_on_warning: false

pbnightingale-0.2.1/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.1] - 2026-09-20
+
+### Added
+
+- `-d`/`--debug` and `-q`/`--quiet` CLI flags: `--debug` enables debug-level
+  logging, including a trace of every operation launched through an
+  external program (`gpg`, `gpg-connect-agent`, …); `--quiet` restricts
+  logging to warnings and errors
+- `--print-completion {bash,zsh,tcsh,fish,powershell}` (via `shtab`), in
+  the "tools" option group, to generate a shell completion script
+
+### Changed
+
+- A short program history note added to the README and the user manual
+
+### Fixed
+
+- gpg's purely informational `[GNUPG:] KEYEXPIRED <timestamp>` status
+  lines no longer appear in diagnostic/error messages
+
+### Security
+
+- Passphrases are now carried through the application as a dedicated
+  `Passphrase` wrapper (`core/secret.py`) instead of a bare string:
+  `str()`/`repr()` on it always show a fixed placeholder, so an enhanced
+  traceback tool or debugger dumping a stack frame's local variables can
+  no longer expose a passphrase in the clear
+- Debug-mode tracing of external `gpg` invocations redacts every
+  passphrase from the logged command input; the real value sent to gpg is
+  unaffected
+
+## [0.2.0] - 2026-09-17
+
+### Added
+
+- Sortable main key list: clicking a column header (Name, Email, Key ID,
+  Expires) sorts the keys inside each group, clicking it again reverses the
+  order. The "My keys" and "Other keys" groups themselves keep their fixed
+  order, and keys that never expire always sort last in the Expires column.
+  The list is sorted by name ascending on first launch, and the chosen sort
+  column and direction are remembered across sessions
+- Numpydoc docstring convention adopted project-wide (`core/`, `platform/`,
+  top-level modules, and every `ui/*.py` except `*_ui.py` layout files),
+  documented in CODING.md
+- `pydocstyle` (ruff `D`, `numpy` convention) enforced in lint, scoped to
+  match the documented docstring convention
+
+### Fixed
+
+- Sphinx docs: `napoleon_numpy_docstring` was disabled, so numpydoc
+  sections in docstrings were never actually parsed or rendered
+- CI: bumped `codecov-action` to v7 to pick up its own Node 24 runtime
+  (it was pinned to a deprecated Node 20 build via `actions/github-script`)
+
+## [0.1.0] - 2026-09-16
+
+This program is an evolution (heavily improved) of an older Python
+program, itself an evolution of an ancient (~2014) Perl program.
+
+### Added
+
+- Personal key generation (RSA or ED25519) with a passphrase strength meter
+- Subkey management: add, revoke, export, back up, delete
+- Editable identities: text and photo user IDs
+- Expiration date management for keys and subkeys
+- Passphrase changes, with in-memory caching and show/hide fields
+- Key signing, owner trust, and trust refresh, including a signatures view
+- Key import from a file or a keyserver, with a review step before merging
+- Keyserver search, publish, and refresh
+- French and English interface, with a preferences dialog
+- Packaging (PyInstaller) and Sphinx user documentation
+- GitHub Actions CI: tests, pre-commit hooks, documentation build, per-OS
+  PyInstaller builds, and GitHub Releases cut from this changelog on
+  semver tags
+- Help menu entry opening the online user manual in the interface's
+  current language
+- Keyboard shortcuts for standard actions (new, import, export, back up,
+  delete, settings, help, quit) and a refresh family (F5 for keys,
+  Shift+F5 for trust, Ctrl+F5 for keyservers)

pbnightingale-0.2.1/CLAUDE.md

@@ -0,0 +1,218 @@
+# Mode
+`full-en` — code and all communication in English.
+
+# Project: PBNightingale
+GUI GPG key manager (Linux/Windows/macOS). Python 3.14+, PySide6 (Qt6), src layout.
+Publisher: PBMou | Author: Marcel Spock <mrspock@cardolan.net>
+License: GPLv3 (code); icons under `resources/` (sourced from PBIcons) are
+CC BY-NC-SA 4.0 instead — see LICENSE-ICONS
+
+## Current state
+
+Published to GitHub (`origin` → `git@github.com:ppoilbarbe/PBNightingale.git`,
+`main` tracks `origin/main`). `.github/workflows/ci.yml` runs tests, hooks,
+docs build and per-OS PyInstaller builds on every push/PR, and cuts a
+GitHub release from `CHANGELOG.md` on semver tags. **Still never push without an explicit request from the user**
+(see global CLAUDE.md). `make ci` (lint → hooks → test) remains the local
+gate to run before pushing.
+
+Implementation proceeds milestone by milestone; each milestone is validated
+(`make ci` green + manual check) before the next one starts.
+
+## Stack
+
+- GUI: PySide6; UI layouts hand-written (`*_ui.py`), no Qt Designer
+- GPG backend: `python-gnupg` wrapping the system `gpg` binary (portable;
+  avoids compiling GPGME bindings on Windows/macOS)
+- Password strength: `zxcvbn` (conda-forge), thresholds/tiers ported from
+  KeePassXC's `PasswordHealth` — see CODING.md, "Password strength"
+- Tests: pytest + pytest-qt (`qtbot`; never instantiate `QApplication`
+  manually) — GPG tests run against an isolated temporary `GNUPGHOME`, never
+  the user's real keyring
+- Lint: ruff (line-length 88, target py314), default rule set + `I`/`PGH`/
+  `UP`/`BLE`/`S`/`D` (no explicit `select` — see pyproject.toml comment);
+  `D` uses the `numpy` pydocstyle convention, matching this project's
+  numpydoc docstrings (see CODING.md, "Coding conventions")
+- Env: pixi (conda-forge channel only) — `make venv`
+- CI/CD: GitHub Actions (`.github/workflows/ci.yml`) + `make ci` locally
+  before pushing
+- i18n: French + English only, pybabel/gettext (see `i18n.py`)
+- Auto-update: GitHub-releases self-update, `--auto-update` CLI flag —
+  only meaningful (and only registered) in a PyInstaller-frozen executable
+  (milestone 15); inert everywhere else
+
+## Layout
+
+```text
+src/pbnightingale/
+├── __init__.py           version, author metadata; builtins._ no-op fallback
+├── __main__.py           entry point; --auto-update dispatch (frozen only)
+├── i18n.py               gettext bootstrap (setup(app), language override)
+├── settings.py           config-dir root (configure() override for tests)
+├── preferences.py        general app preferences (preferred key algorithm, …)
+├── locale/               en/fr catalogues (.po committed, .mo gitignored)
+├── core/
+│   ├── gpg_backend.py    GPGBackend (python-gnupg wrapper) + Key/Subkey model;
+│   │                     configure()/default_backend() override for tests
+│   ├── secret.py         Passphrase — frozen wrapper hiding a passphrase from
+│   │                     str()/repr() (e.g. in a traceback's local-var dump)
+│   ├── passphrase_cache.py  in-memory {fingerprint: Passphrase} cache, TTL-based
+│   └── password_strength.py  zxcvbn-based entropy/quality for a new passphrase
+├── platform/
+│   ├── dirs.py           AppDirs factory: XdgDirs / _MacDirs / _WindowsDirs
+│   ├── locale.py         system_language()
+│   └── auto_update.py    perform_auto_update() — GitHub release self-update
+├── resources/            bundled SVG/PNG icons (resources.path(name))
+└── ui/
+    ├── main_window.py    main window: loads keys, signals
+    ├── main_window_ui.py main window layout: actions, toolbars (one per theme), menus
+    ├── key_list_view(_ui).py   central widget: key list + detail panel
+    ├── new_key_wizard(_ui).py  personal key creation wizard
+    ├── password_strength_meter(_ui).py  colored entropy bar for a new passphrase
+    ├── add_subkey_dialog(_ui).py     Add Subkey dialog
+    ├── revoke_subkey_dialog(_ui).py  Revoke Subkey dialog (strong confirmation)
+    ├── change_passphrase_dialog(_ui).py  Change Passphrase dialog
+    ├── add_uid_dialog(_ui).py        Add User ID dialog
+    ├── set_primary_uid_dialog(_ui).py  Set Primary User ID dialog
+    ├── revoke_uid_dialog(_ui).py     Revoke User ID dialog (strong confirmation)
+    ├── add_photo_dialog(_ui).py      Add Photo dialog
+    ├── revoke_photo_dialog(_ui).py   Revoke Photo dialog (strong confirmation)
+    ├── set_expiration_dialog(_ui).py  Set Expiration dialog (key or subkey)
+    ├── sign_key_dialog(_ui).py       Sign Key dialog
+    ├── set_owner_trust_dialog(_ui).py  Set Owner Trust dialog
+    ├── about_dialog(_ui).py
+    ├── settings_dialog(_ui).py  language selector
+    ├── gpg_worker.py     run_async() — QThreadPool bridge for GPGBackend calls
+    ├── window_state.py   persisted window geometry / splitter sizes (QSettings)
+    └── geometry_mixin.py GeometryMixin — wires window_state into a window
+```
+
+`tools/update_icons.py` syncs `resources/` icons from the shared PBIcons
+asset repo (local checkout sibling, else GitHub) — see CODING.md.
+
+## Key conventions
+
+- All OS-specific code goes in `src/pbnightingale/platform/`.
+- Never test against the real user's GPG keyring — always an isolated
+  `GNUPGHOME`. Enforced automatically:
+  `gpg_backend.configure()`/`default_backend()` mirror
+  `settings.configure()` exactly, and `tests/conftest.py`'s autouse
+  `_isolated_gnupghome`/`_isolated_config` fixtures redirect both to a tmp
+  dir for every test — never the real user's keyring or config directory.
+- After any user-visible string change: `make translate`, fill every new
+  `msgstr ""` in both `en` and `fr` `.po` files, `make translate` again to
+  compile. Verify with `python tools/po_check.py --empty` — never grep/msgfmt
+  directly on `.po` files (they can have multi-line entries). Run
+  `po_check.py --empty` even when a milestone feels string-free — milestones
+  6 and 7 both merged without it and left 65 strings untranslated in both
+  languages until milestone 8 caught it.
+- Every top-level window/dialog persists its geometry (and splitter sizes)
+  via `ui/geometry_mixin.py::GeometryMixin` (`self._init_geometry(key,
+  splitters={...})` after `setupUi()`) — apply it to new windows too, except
+  small fixed-purpose dialogs like `AboutDialog`.
+- ED25519 key generation cannot fold `encrypt` usage into the primary key
+  (gpg rejects it outright — EdDSA is signature-only); `NewKeyRequest`/
+  `add_subkey()` always add a dedicated Curve25519 subkey for encryption
+  under ED25519, and the wizard/Add Subkey dialog force-check-and-disable
+  that checkbox accordingly. Don't "simplify" this away — RSA's "fold into
+  primary" behavior genuinely doesn't generalize to ED25519.
+- Subkey revocation has no python-gnupg wrapper — `GPGBackend.
+  revoke_subkey()` drives `gpg --edit-key` directly via `--command-fd`/
+  `--status-fd` scripting. The passphrase line in that script must be
+  positioned exactly where gpg's `GET_HIDDEN passphrase.enter` status
+  appears (right after confirming the revocation reason) — anywhere else in
+  the sequence gets silently consumed as a bogus `keyedit.prompt` command
+  instead. See CODING.md — "Subkey management".
+- `self._gpg.gnupghome` is `None` in production (no `configure()`
+  override) — never assume it's a usable path. Anything that shells out
+  directly (`_restart_agent()`, `revoke_subkey()`) must go through
+  `GPGBackend._homedir_args()` rather than building a `--homedir` arg by
+  hand; a bare `self._gpg.gnupghome` in a `subprocess.run()` arg list
+  crashes with `TypeError: ... not NoneType` in production, since every
+  test's `GPGBackend` has a real temp-dir `gnupghome` and never exercises
+  the `None` case — this class of bug won't show up in `make ci`.
+- `GPGBackend.change_passphrase()` drives gpg's dedicated
+  `--change-passphrase` command (never `--edit-key`'s `passwd`
+  sub-command): unlike `passwd`, a wrong old passphrase there gets a
+  proper machine-readable `[GNUPG:] ERROR keyedit.passwd <code>` status
+  line — but only when a wrong passphrase gets exactly the right number of
+  retries: gpg retries the old-passphrase prompt once per secret-key part
+  (primary + each subkey), and a wrong one can't be told apart from a
+  correct one until each retry has played out, so the script sent is
+  `old`, `new`, then `old` again `_MAX_SECRET_KEY_PARTS` (64) more times as
+  filler. A real 4-subkey-part key with too few retries queued ran the
+  script dry mid-sequence, downgrading the failure to gpg's generic
+  "operation canceled" code (99, not 11) and dumping its whole raw
+  multi-attempt diagnostic text into the dialog instead of a clean
+  message — reported against real usage; see CODING.md. A *correct*
+  passphrase only ever needs the first two lines (`old`, `new`) — no
+  repeat-to-confirm step in the protocol itself, that's the UI's own job
+  (`ChangePassphraseDialog`'s `txtNewPassphrase`/`txtNewPassphraseConfirm`).
+  Always clears gpg-agent's passphrase cache first via `gpg-connect-agent
+  RELOADAGENT` (never `_restart_agent()`'s `gpgconf --kill`, which is async
+  and races the next call) — otherwise an already-cached key silently
+  skips the old-passphrase check and misapplies its value as the new
+  passphrase instead. Only works on a key that already has a real
+  passphrase — an
+  unprotected key given `old_passphrase=""` reports success but stays
+  unprotected (`--edit-key passwd` handles that transition correctly, but
+  loses the machine-readable error code). See CODING.md — "Changing a
+  key's passphrase".
+- Detect a wrong GPG passphrase by the numeric code on gpg's `[GNUPG:]
+  ERROR <location> <code>` status line (`& 0xFFFF == 11`, libgpg-error's
+  `GPG_ERR_BAD_PASSPHRASE`) — never by matching gpg's own human-readable
+  text ("Mauvaise phrase secrète"/"Bad Passphrase"/…), which is localized
+  to the system's own language and has nothing to do with this app's own
+  `en`/`fr` catalogues. See `GPGBackendError`/`BadPassphraseError` in
+  `core/gpg_backend.py`.
+- There is no reliable "primary UID" signal in gpg's plain `--list-keys`
+  output — verified empirically, don't re-derive it: UID listing order
+  looks tempting but isn't a stable stand-in (a clean test with UIDs added
+  in order A, B, C came back as `C, A, B`, not creation or timestamp
+  order). The real primary flag only shows up in `gpg --edit-key`'s own
+  `--with-colons` listing, at the cost of one extra `gpg` subprocess per
+  key — not worth paying for a cosmetic label, so `Uid` has no `primary`
+  field. See CODING.md — "Editable user IDs".
+- python-gnupg's `list_keys()` silently drops photo user IDs ("uat" colon
+  records) — its own record-type allowlist doesn't include them (verified
+  against its source, not just observed). `GPGBackend._load_photos()`
+  works around this with a separate raw `--attribute-file` listing.
+  `addphoto` (scripted via `--edit-key`, like subkey revocation) needs
+  `--no-tty` or it fails outright in any headless/GUI-launched process,
+  and its passphrase line goes right after the file path, *before*
+  `save` — unlike every other scripted `--edit-key` flow in this app,
+  where the passphrase goes last. See CODING.md — "Photo user IDs".
+- `Key.trust` (validity — is the UID/key binding genuine) and
+  `Key.owner_trust` (how much you personally trust this owner to certify
+  *others*) are different gpg concepts that happen to share colon-format
+  letter codes — never conflate them. gpg auto-assigns "ultimate"
+  ownertrust to any key you hold the secret part of unless explicitly
+  overridden, which masks signing's effect on validity in tests unless you
+  override it first. `--min-cert-level` (default 2) disregards level-1
+  signatures for validity, but level 0 is always accepted — a signing
+  dialog defaulting to cert level 0 is a real default, not a placebo. See
+  CODING.md — "Key signing & web of trust".
+- Every passphrase in this codebase is a `core/secret.py::Passphrase`
+  (frozen dataclass), never a bare `str` — `GPGBackend` method parameters,
+  `NewKeyRequest.passphrase`, `passphrase_cache`'s stored values, what a
+  dialog reads off `txtPassphrase`. `str()`/`repr()` on it always print
+  `"**********"`, closing off a leak a bare `str` local doesn't: an
+  enhanced traceback tool or debugger dumping a frame's locals on an
+  unhandled exception would otherwise print the real value at every stack
+  frame it passed through. `bool(passphrase)`/`==` work on the wrapper
+  directly — only unwrap via `.passphrase` at the one point gpg's own
+  protocol needs the raw text (a `--command-fd` script, an `input=`
+  payload, a python-gnupg kwarg, or the widget echoing it back). Don't
+  interpolate a `Passphrase` into an f-string unwrapped — with no
+  `__format__` override it falls back to `str()` and sends the literal
+  `"**********"` to gpg instead of the real passphrase, a real protocol
+  bug, not just a leak. See CODING.md — "GPG backend".
+- New external-program calls in `core/gpg_backend.py` must go through
+  `_traced_run()`/`_traced_popen()`, never a bare `subprocess.run()`/
+  `Popen()` — that's what makes `-d`/`--debug` trace every gpg invocation,
+  and it's also where `_clean_stderr()` strips gpg's purely-informational
+  `[GNUPG:] KEYEXPIRED …` status lines from `result.stderr` before
+  anything (an exception message, a retry check) ever sees them. A
+  passphrase fed via `input=`/a script must be listed in `secrets=` so the
+  debug trace redacts it — the real value sent to gpg is never affected,
+  only what gets logged.