gui: Gate restores on wallet identity

A checksum-valid recovered seed may not be the operator’s wallet. Ask for the independent record fingerprint before listing wallets, then carry it through existing and newly created destinations so a mismatch stops before unlock, create, or import. Keep the explicit no-record visual fallback, but do not allow its revealed fingerprint back into the recorded route in the same attempt.

Raise the separately enforced GUI review cap to the authorized 2,250 lines for this gate. Keep the combined Python 3.10-3.15 package compatible with the GUI code and passphrase encoding check. Exercise the focused boundary and display walkthrough with synthetic data.

Refs #26 and #28.

Author: codex

docs/developer/api.md

@@ -117,7 +117,7 @@ documentation and enforcement update.
 installed as `codex32[gui]` and started by `codex32-gui`. It is a client of the
 surface above and of the private Core adapter; nothing in `src/codex32/` imports
 it, and the base install keeps its property of having no third-party runtime
-dependency. It carries its own budget of 2,050 logical review lines, separate
+dependency. It carries its own budget of 2,250 logical review lines, separate
 from the 5,200 above. Its own boundaries are documented in
 [`gui.md`](gui.md) and enforced by `tests/test_gui_boundaries.py`.
 

docs/developer/gui.md

@@ -19,7 +19,7 @@ cryptography, entropy source, socket, or file storage.
 
 Review `reading.py`, `wallet_setup.py`, and `work.py` first. Their behavior is
 covered without a display. `tools/gui_walkthrough.py` exercises the real GTK
-screens under Xvfb. `tests/test_gui_boundaries.py` enforces a separate 2,050
+screens under Xvfb. `tests/test_gui_boundaries.py` enforces a separate 2,250
 logical-line GUI budget.
 
 ## Security boundaries

docs/security/model.md

@@ -259,6 +259,16 @@ initialization.
 `codex32_gui/wallet_setup.py`, the only module in that package that imports the
 Core adapter.
 
+Before listing wallets on restore, the GUI asks for the master fingerprint from
+the separate wallet record without showing the recovered value. A mismatch
+stops the attempt. The explicit no-record route reveals the recovered
+fingerprint and backup-identifier assessment, then requires **Restore anyway**;
+after that disclosure, this attempt cannot return to the record-entry route.
+The chosen expected fingerprint is checked again before unlocking or creating
+a destination and at the shared library import boundary. Fresh creation instead
+shows its new fingerprint for the operator to record; there is no earlier
+wallet identity to compare.
+
 | Departure | Required behavior |
 |---|---|
 | Passphrase | The operator may supply a Bitcoin Core wallet passphrase. It reaches `bitcoin-cli` through `-stdinwalletpassphrase`, never through an argument, so it is absent from `/proc` and process listings. It is not stored, not logged, and not written to disk, and a passphrase containing a line break is refused rather than truncated. A passphrase this computer's locale would encode as something other than what Bitcoin-Qt sends is refused, so no half-encoded secret reaches a screen or a traceback. The screen keeps the command line's behavior as an alternative: the operator may unlock in Bitcoin-Qt instead, and the program then only rechecks wallet state. |

docs/user/gui.md

@@ -66,9 +66,11 @@ Copy each card to paper, hide the on-screen original, then type the paper copy
 back. Read-back starts completely empty, including `MS1`. A mismatch highlights
 only the groups you typed differently; the expected text stays hidden.
 
-After all cards are confirmed, choose an empty Bitcoin Core wallet or create a
-new blank one. A passphrase protects the wallet on this computer; the recovery
-cards still recover the seed if that passphrase is lost.
+After all cards are confirmed, write the displayed master fingerprint on your
+wallet record and acknowledge that you have recorded it. Then choose an empty
+Bitcoin Core wallet or create a new blank one. A passphrase protects the wallet
+on this computer; the recovery cards still recover the seed if that passphrase
+is lost.
 
 Copy the final wallet details to the
 [wallet record](wallet-verification-record.html) and store it separately from the
@@ -103,8 +105,13 @@ exist. The GUI can say “any 2 cards recover the wallet”; it cannot infer “
 3”. `ms32 share` can add another card at any time.
 
 A valid checksum shows that a card is internally consistent. It does not prove
-that the card belongs to your wallet. Restore and compare the master fingerprint
-with your wallet record.
+that the card belongs to your wallet. Before restoring into Bitcoin Core, type
+the master fingerprint from your separate wallet record; a mismatch stops before
+any wallet is opened or created. If you have no record, the GUI instead shows the
+recovered fingerprint and what the backup identifier says about the seed, then
+requires a separate **Restore anyway** choice. This fallback detects some
+mistakes but does not authenticate the intended wallet; check its history and
+addresses before sending funds.
 
 ## Secret handling
 

src/codex32_gui/pages.py

@@ -10,7 +10,7 @@
 import time
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass
-from typing import Literal
+from typing import Literal, TypeVar
 
 from gi.repository import Adw, GLib, Gtk
 
@@ -35,6 +35,7 @@
 Artifact = Share | Secret
 Accept = Callable[[Artifact], None]
 Timestamp = int | Literal["now"]
+Result = TypeVar("Result")
 
 LEVELS = ("dim-label", "error", "warning", "success")
 DONE_ICON = "object-select-symbolic"
@@ -294,7 +295,7 @@ def _working(view: Adw.NavigationView, title: str, message: str) -> Adw.Navigati
     return page
 
 
-def _then[Result](
+def _then(
     view: Adw.NavigationView,
     page: Adw.NavigationPage,
     follow: Callable[[Result], Adw.NavigationPage | None],
@@ -687,7 +688,7 @@ def _unshared_page(view: Adw.NavigationView, core: BitcoinCore, secret: MasterSe
         position=0,
         count=1,
         confirm=lambda text: _compare(secret.text, text),
-        after=lambda: _wallets(view, core, secret, "now"),
+        after=lambda: _identity(view, core, secret),
         cancel=lambda page: _abandon(view, page),
     )
 
@@ -731,7 +732,7 @@ def follow(secret: MasterSeed | CoreLightningSecret) -> None:
         if not isinstance(secret, MasterSeed):
             _failure(view, "That ceremony did not produce a Bitcoin master seed.")
             return
-        _wallets(view, core, secret, "now")
+        _identity(view, core, secret)
 
     deliver = _then(view, page, follow, CARDS_SAFE)
     work.run(view, page, ceremony.finish, deliver)
@@ -745,6 +746,7 @@ def _wallets(
     core: BitcoinCore,
     secret: MasterSeed,
     timestamp: Timestamp,
+    expected: bytes | None,
     *,
     restoring: bool = False,
 ) -> None:
@@ -756,7 +758,7 @@ def _wallets(
         _then(
             view,
             page,
-            lambda found: _wallet_page(view, core, secret, found, timestamp, restoring),
+            lambda found: _wallet_page(view, core, secret, found, timestamp, expected, restoring),
             CARDS_SAFE,
         ),
     )
@@ -768,6 +770,7 @@ def _wallet_page(
     secret: MasterSeed,
     found: tuple[wallet_setup.Wallet, ...],
     timestamp: Timestamp,
+    expected: bytes | None,
     restoring: bool,
 ) -> Adw.NavigationPage:
     """Name the wallet that will hold the keys. The library confirms that name again."""
@@ -781,13 +784,13 @@ def go() -> None:
         if index < 0:
             return
         if index == len(current):
-            view.push(_new_wallet_page(view, core, secret, timestamp, restoring))
+            view.push(_new_wallet_page(view, core, secret, timestamp, expected, restoring))
             return
         chosen = current[index]
         if chosen.locked:
-            view.push(_unlock_page(view, core, secret, chosen, timestamp, restoring))
+            view.push(_unlock_page(view, core, secret, chosen, timestamp, expected, restoring))
             return
-        _import(view, core, secret, chosen.name, "", timestamp, restoring)
+        _import(view, core, secret, chosen.name, "", timestamp, expected, restoring)
 
     continue_button = _button("Continue", go, style="suggested-action")
 
@@ -876,6 +879,7 @@ def _new_wallet_page(
     core: BitcoinCore,
     secret: MasterSeed,
     timestamp: Timestamp,
+    expected: bytes | None,
     restoring: bool = False,
 ) -> Adw.NavigationPage:
     """Ask Bitcoin Core for one blank wallet, with a passphrase the operator chooses."""
@@ -893,8 +897,10 @@ def make(passphrase: str) -> None:
         page = _working(view, "Bitcoin Core", "Creating the wallet and writing your keys into it…")
 
         def job() -> Record:
+            if restoring:
+                wallet_setup.verify(core, secret, expected)
             wallet_setup.create(core, chosen, passphrase)
-            return _record(core, secret, chosen, timestamp, passphrase)
+            return _record(core, secret, chosen, timestamp, expected, passphrase)
 
         work.run(
             view,
@@ -948,6 +954,7 @@ def _unlock_page(
     secret: MasterSeed,
     wallet: wallet_setup.Wallet,
     timestamp: Timestamp,
+    expected: bytes | None,
     restoring: bool = False,
 ) -> Adw.NavigationPage:
     """Unlock one already encrypted wallet, or step aside and let Bitcoin Core do it."""
@@ -976,7 +983,7 @@ def check() -> None:
 
         def job() -> Record:
             wallet_setup.require_unlocked(core, wallet.name)
-            return _record(core, secret, wallet.name, timestamp)
+            return _record(core, secret, wallet.name, timestamp, expected)
 
         work.run(
             view,
@@ -986,7 +993,7 @@ def job() -> Record:
         )
 
     def go() -> None:
-        _import(view, core, secret, wallet.name, field.get_text(), timestamp, restoring)
+        _import(view, core, secret, wallet.name, field.get_text(), timestamp, expected, restoring)
 
     content = _column(
         _title(
@@ -1013,9 +1020,14 @@ def go() -> None:
 
 
 def _record(
-    core: BitcoinCore, secret: MasterSeed, name: str, timestamp: Timestamp, passphrase: str = ""
+    core: BitcoinCore,
+    secret: MasterSeed,
+    name: str,
+    timestamp: Timestamp,
+    expected: bytes | None,
+    passphrase: str = "",
 ) -> Record:
-    final = wallet_setup.fill(core, secret, name, passphrase, timestamp=timestamp)
+    final = wallet_setup.fill(core, secret, name, passphrase, expected=expected, timestamp=timestamp)
     return Record(
         secret.header.identifier.upper(),
         final,
@@ -1025,20 +1037,121 @@ def _record(
     )
 
 
+def _identity(
+    view: Adw.NavigationView, core: BitcoinCore, secret: MasterSeed, restoring: bool = False
+) -> None:
+    """Show a fresh identity for recording, or a no-record restore for confirmation."""
+    page = _working(view, "Wallet record", "Asking Bitcoin Core for the master fingerprint…")
+
+    def follow(identity: tuple[str, str]) -> Adw.NavigationPage:
+        fingerprint, note = identity
+        shown = (("Backup identifier", secret.header.identifier.upper()), ("Master fingerprint", fingerprint))
+        if not restoring:
+            return _page(
+                "Wallet record",
+                _column(
+                    _title("Write this on your wallet record", "Keep the record apart from your cards."),
+                    _rows("Identity", shown),
+                ),
+                actions=_actions(
+                    _button(
+                        "I wrote it down",
+                        lambda: _wallets(view, core, secret, "now", None),
+                        style="suggested-action",
+                    )
+                ),
+                can_pop=False,
+            )
+        content = _column(
+            _title("Restore without a wallet record?", "Nothing here can prove these cards are your wallet."),
+            _rows("What the cards say", shown),
+            _note(note, "warning"),
+            _note(wallet_setup.NO_RECORD_WARNING, "warning"),
+        )
+        stop = _button("Stop", lambda: view.replace([home(view)]))
+        anyway = _button(
+            "Restore anyway",
+            lambda: _wallets(view, core, secret, 0, None, restoring=True),
+            style="destructive-action",
+        )
+        return _page("No wallet record", content, actions=_actions(stop, anyway), can_pop=False)
+
+    work.run(view, page, lambda: wallet_setup.identity(core, secret), _then(view, page, follow, CARDS_SAFE))
+
+
+def _fingerprint_page(
+    view: Adw.NavigationView,
+    core: BitcoinCore,
+    secret: MasterSeed,
+    timestamp: Timestamp,
+    *,
+    restoring: bool = False,
+    problem: str = "",
+) -> Adw.NavigationPage:
+    """Ask for the record's fingerprint before any restore wallet is listed."""
+    entered = Adw.EntryRow(title="Master fingerprint from your wallet record")
+    group = Adw.PreferencesGroup()
+    group.add(entered)
+    status = _note(problem, "error" if problem else "")
+
+    def go() -> None:
+        try:
+            expected = wallet_setup.parse_fingerprint(entered.get_text())
+        except ValueError as error:
+            _say(status, str(error), "error")
+            return
+        page = _working(view, "Wallet record", "Checking the wallet record…")
+
+        def job() -> str:
+            try:
+                wallet_setup.verify(core, secret, expected)
+            except wallet_setup.FingerprintMismatch as error:
+                return str(error)
+            return ""
+
+        def follow(mismatch: str) -> Adw.NavigationPage | None:
+            if mismatch:
+                return _fingerprint_page(view, core, secret, timestamp, restoring=restoring, problem=mismatch)
+            _wallets(view, core, secret, timestamp, expected, restoring=restoring)
+            return None
+
+        work.run(view, page, job, _then(view, page, follow, CARDS_SAFE))
+
+    buttons = [_button("Stop", lambda: view.replace([home(view)]))]
+    if restoring:
+        buttons.append(
+            _button("I have no wallet record", lambda: _identity(view, core, secret, restoring=True))
+        )
+    buttons.append(_button("Check and continue", go, style="suggested-action"))
+    content = _column(
+        _title(
+            "Type the master fingerprint", "Copy it from the wallet record you keep apart from the cards."
+        ),
+        group,
+        status,
+        _note(
+            "If it does not match, stop: these cards are not that wallet. Bitcoin Core has not been changed.",
+            "warning",
+        ),
+    )
+    return _page("Wallet record", content, actions=_actions(*buttons), can_pop=False)
+
+
 def _import(
     view: Adw.NavigationView,
     core: BitcoinCore,
     secret: MasterSeed,
     name: str,
     passphrase: str,
     timestamp: Timestamp,
+    expected: bytes | None,
     restoring: bool = False,
 ) -> None:
     page = _working(view, "Bitcoin Core", f"Writing your keys into {name}…")
     work.run(
         view,
         page,
-        lambda: _record(core, secret, name, timestamp, passphrase),
+        lambda: _record(core, secret, name, timestamp, expected, passphrase),
         _then(view, page, lambda record: _finished_page(view, record, restoring), CARDS_SAFE),
     )
 
@@ -1536,7 +1649,7 @@ def _restore(view: Adw.NavigationView, core: BitcoinCore, secret: Secret) -> Non
     if not isinstance(secret, MasterSeed):
         _failure(view, "Only a Bitcoin master-seed backup can restore a wallet.")
         return
-    _wallets(view, core, secret, 0, restoring=True)
+    _replace(view, _fingerprint_page(view, core, secret, 0, restoring=True))
 
 
 def _start_restore(view: Adw.NavigationView) -> None: