wallet: Require the recorded fingerprint before import

BitcoinCore.initialize now takes a required expected_fingerprint and
checks it before any wallet is listed, created, unlocked or imported
into, so the GUI and CLI share one gate. The operator types the value
from the wallet record; a new wallet shows it once and asks for it back.
Without a record, the backup identifier must derive from the seed
(codex32 fingerprint or legacy Bails RIPEMD-160 identifier).

Fixes #26. Fixes #30.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: BenWestgate

docs/developer/api.md

@@ -640,7 +640,11 @@ fingerprint consistency, and network xpub/tpub versions, constructs only the
 fixed descriptor templates, and asks `getdescriptorinfo` to validate and expand
 their external/internal branches. The adapter then compares the exact eight
 active public descriptors against `listdescriptors`. It relocks wallets Core
-reports as encrypted. Master-fingerprint display is likewise delegated to Core:
+reports as encrypted. Before any of this, `initialize` calls `verify_identity`
+with the required `expected_fingerprint`: bytes typed from the wallet record
+(read with `parse_fingerprint`), or `None` when there is no record, which accepts
+only a seed-derived backup identifier. A mismatch raises `FingerprintMismatch`
+before any wallet RPC. Master-fingerprint display is likewise delegated to Core:
 a stateless root P2PKH descriptor is normalized, `deriveaddresses` derives its
 address, and `validateaddress` returns the script hash whose first four bytes are
 the BIP32 fingerprint.

docs/security/invariants.md

@@ -11,6 +11,10 @@ and evidence.
 3. Shared creation uses a separate OS-CSPRNG call for each random initial share,
    gated by confirmation. Input cannot replace entropy or the original secret.
 4. Wallet setup uses the original ceremony result or a validated recovered seed.
+   `BitcoinCore.initialize` requires the master fingerprint typed from the
+   wallet record and refuses a mismatch before any wallet is listed, created,
+   unlocked, or imported into. Without a record, the backup identifier must be
+   derived from the recovered seed.
 5. Correction shares one mass bound and deadline across target lengths. The
    public API fails closed on incomplete required work; CLI searches may return
    one primary-best-so-far eligible candidate at the deadline. Incomplete

docs/security/model.md

@@ -45,8 +45,9 @@ The operator must:
   balances or history;
 - protect recovery cards and store shared cards in different trusted places;
 - confirm every newly recorded secret or share;
-- keep wallet records separate from shares and compare recovered fingerprints,
-  addresses, account, policy, and history with those records;
+- keep wallet records separate from shares, type the master fingerprint from
+  the record before import, and compare addresses, account, policy, and history
+  with those records;
 - compare every correction suggestion with the original codex32 string and stop
   when recovered information and wallet records disagree; and
 - never put recovery text in command arguments or transfer a master seed,
@@ -268,6 +269,19 @@ only while more than one answers. On screen a wallet is chosen by the position o
 its row, never by the text of its label, and Core's text is rendered without
 Pango markup, so a wallet name cannot hide or impersonate another.
 
+Every import, in the window and on the command line, goes through
+`BitcoinCore.initialize`, which requires the master fingerprint the operator
+typed from the wallet record. Core derives the recovered fingerprint
+statelessly, and a mismatch raises `FingerprintMismatch` before any wallet is
+listed, created, unlocked, or imported into. The prompt does not show the
+recovered value, so the operator compares by typing rather than by glancing. A
+new wallet shows its fingerprint once, then asks for it back from the written
+record. An operator without a record may continue only when the backup identifier is
+derived from the recovered seed: the codex32 fingerprint identifier or legacy
+Bails' RIPEMD-160 seed identifier. Both checks catch mistakes such as wrong or
+mixed cards; 32 bits, and 20 bits without a record, do not stop deliberately
+replaced cards.
+
 The program draws no entropy, opens no socket, starts no process of its own, and
 writes no file: no settings, no recent list, no log, and no clipboard write of
 recovery text. Entered recovery text is cleared when its screen is left, subject

docs/user/gui.md

@@ -67,7 +67,11 @@ the paper with the original off the screen. That catches a slip of the pen now
 rather than years from now. If a group does not match, the window says which one;
 correct that group and try again, as many times as you like.
 
-When every card is confirmed, choose the Bitcoin Core wallet that will hold the
+When every card is confirmed, the window shows the master fingerprint. Write it
+on your [wallet record](wallet-verification-record.html), then type it back from
+what you wrote. That catches a writing mistake while it can still be fixed.
+
+Next, choose the Bitcoin Core wallet that will hold the
 keys. Only empty wallets are offered, so no wallet you already use can be
 overwritten. If you have none, the window can ask Bitcoin Core to create one:
 give it a name and a passphrase, and codex32 fills it in and locks it again.
@@ -142,10 +146,15 @@ wallet**, which would make a different backup. If the wallet was part-filled
 before it failed, it is no longer empty, so it will not be offered again: create
 another one, or ask Bitcoin Core for a fresh blank wallet.
 
-When you restore, the window asks you to **check** the wallet details against
-your record rather than copy them onto it. That comparison — the master
-fingerprint above all — is the only thing that proves the cards you just typed
-belong to that wallet. It shows no creation date on that screen, because the
+When you restore, the window first asks you to type the master fingerprint from
+your wallet record. If it does not match, nothing is written to Bitcoin Core:
+check what you typed, and if it still does not match, these cards are not that
+wallet. If you have no record, **I have no wallet record** checks only that the
+backup identifier comes from the recovered seed. That works for backups made by
+Bails, but it cannot catch cards someone replaced on purpose.
+
+After the restore, **check** the remaining wallet details against your record
+rather than copy them onto it. It shows no creation date on that screen, because the
 real one is already on your record and today's would replace it.
 
 The window always uses account 0, which is what it writes onto your wallet

docs/user/guide.md

@@ -168,9 +168,10 @@ wallet should be trusted until initialization completes.
 
 ### 4. Complete the record and store the cards
 
-Copy the displayed backup identifier, wallet name, Bitcoin Core version,
-master fingerprint, derivation standards, and account number to the wallet
-record. Add the approximate
+Before the wallet is filled, write the displayed master fingerprint on the
+wallet record and type it back from what you wrote. Then copy the displayed
+backup identifier, wallet name, Bitcoin Core version, derivation standards, and
+account number to the wallet record. Add the approximate
 creation / earliest-use date. Do not put a descriptor timestamp on a recovery
 card; Core's public descriptor export preserves its stored timestamps.
 
@@ -228,16 +229,19 @@ its public wallet data with the separate wallet record.
    ms32 wallet --timestamp 0
    ```
 
-5. Select and confirm that wallet. If it is locked, follow the displayed
+5. Type the master fingerprint from the wallet record. A mismatch stops before
+   Bitcoin Core is changed. Press Enter with nothing typed only if there is no
+   record; then only a seed-derived backup identifier is accepted.
+6. Select and confirm that wallet. If it is locked, follow the displayed
    Bitcoin-Qt Console instructions; codex32 waits and continues automatically.
    It imports the private descriptors, verifies the public set, and relocks an
    encrypted wallet.
-6. If you need an online watch-only counterpart, keep the restored signer
+7. If you need an online watch-only counterpart, keep the restored signer
    offline and follow Bitcoin Core v32's
    [offline-signing tutorial](https://github.com/bitcoin/bitcoin/blob/v32.0rc1/doc/offline-signing-tutorial.md)
    to export and restore the watch-only wallet. Let the online node synchronize,
-   then compare the recovered fingerprint, account, policy, addresses, balance,
-   and transaction history with the wallet record.
+   then compare the account, policy, addresses, balance, and transaction
+   history with the wallet record.
 
 A timestamp of zero safely scans all history and may take time; it belongs in
 the recovery command, not on a paper card. During an emergency recovery, move

src/codex32/_bitcoin_core.py

@@ -1,15 +1,19 @@
 from __future__ import annotations
 
+import hashlib
 import json
 import re
 import shutil
+import string
 import subprocess
 from collections.abc import Callable
 from dataclasses import dataclass
 from time import sleep
 from typing import Literal
 
 from codex32._bip32 import _master_xprv_from_seed
+from codex32.bech32 import _u5_to_chars, convertbits
+from codex32.generation import _fingerprint_identifier
 from codex32.profiles.ms32 import MasterSeed
 from codex32.wallet import _descriptor_records, core_descriptors
 
@@ -18,6 +22,10 @@ class BitcoinCoreError(Exception):
     pass
 
 
+class FingerprintMismatch(BitcoinCoreError):
+    """The recovered seed is not the wallet the operator's record describes."""
+
+
 _CHAINS = (
     ("main", "mainnet"),
     ("test", "testnet3"),
@@ -31,6 +39,25 @@ class BitcoinCoreError(Exception):
 _PURPOSES = (44, 49, 84, 86)
 
 
+def parse_fingerprint(text: str) -> bytes:
+    """Read a master fingerprint as written on a wallet record: 8 hex digits, any case or spacing."""
+    compact = "".join(text.split())
+    if len(compact) != 8 or not all(character in string.hexdigits for character in compact):
+        raise ValueError("A master fingerprint is 8 characters, each 0-9 or A-F.")
+    return bytes.fromhex(compact)
+
+
+def _seed_identifiers(seed: bytes, fingerprint: bytes) -> tuple[str, str]:
+    """Return the backup identifiers that only this seed produces.
+
+    codex32 uses the first 20 bits of the BIP32 fingerprint. Bails' legacy
+    bails-wallet used the first 20 bits of RIPEMD-160 of the seed and offered
+    no way to change it.
+    """
+    legacy = hashlib.new("ripemd160", seed).digest()
+    return _fingerprint_identifier(fingerprint), _u5_to_chars(tuple(convertbits(legacy, 8, 5, pad=True)[:4]))
+
+
 @dataclass(frozen=True)
 class BitcoinCore:
     executable: str
@@ -153,6 +180,26 @@ def fingerprint(self, secret: MasterSeed) -> bytes:
             raise TypeError("wallet operations accept only MasterSeed")
         return self.fingerprint_seed(secret.seed_bytes)
 
+    def verify_identity(self, secret: MasterSeed, expected_fingerprint: bytes | None) -> None:
+        """Refuse a recovered seed that is not the recorded wallet, before any wallet is touched.
+
+        `expected_fingerprint` is what the operator typed from the wallet record.
+        `None` means there is no record: the backup identifier must then be one
+        derived from this seed, which catches mistakes but not replaced cards.
+        """
+        fingerprint = self.fingerprint(secret)
+        if expected_fingerprint is None:
+            if secret.header.identifier not in _seed_identifiers(secret.seed_bytes, fingerprint):
+                raise FingerprintMismatch(
+                    "This backup's identifier does not come from the recovered seed, so it cannot be "
+                    "checked without the wallet record. Bitcoin Core was not changed."
+                )
+        elif fingerprint != expected_fingerprint:
+            raise FingerprintMismatch(
+                "The recovered master fingerprint does not match the one from the wallet record. "
+                "Bitcoin Core was not changed."
+            )
+
     def _root_xpub(self, wallet: str) -> str:
         result = self._rpc("gethdkeys", wallet=wallet)
         if not isinstance(result, list) or len(result) != 1 or not isinstance(result[0], dict):
@@ -299,9 +346,16 @@ def initialize(
         ask: Callable[[str], str],
         tell: Callable[[str], None],
         *,
+        expected_fingerprint: bytes | None,
         account: int = 0,
         timestamp: int | Literal["now"] = "now",
     ) -> str:
+        """Import the recovered keys into one empty wallet the operator chooses.
+
+        The wallet record is checked first, so a wrong seed is refused before any
+        wallet is listed, created, unlocked or imported into.
+        """
+        self.verify_identity(secret, expected_fingerprint)
         while True:
             name = self._select(ask, tell)
             state = self._target(name)

src/codex32/cli.py

@@ -8,7 +8,7 @@
 from collections.abc import Callable, Sequence
 from typing import Literal, NamedTuple, cast
 
-from codex32._bitcoin_core import BitcoinCore, BitcoinCoreError
+from codex32._bitcoin_core import BitcoinCore, BitcoinCoreError, FingerprintMismatch, parse_fingerprint
 from codex32._cli_input import (
     CorrectionDeclined,
     InteractiveConfirmationRequired,
@@ -333,6 +333,43 @@ def _generated_secret(
     )
 
 
+def _show_fingerprint(core: BitcoinCore, secret: MasterSeed, action: str) -> None:
+    _print(f"\nMaster fingerprint: {core.fingerprint(secret).hex().upper()}", err=True)
+    _text(f"{action}, then press Enter", optional=True, prompt_end=". ")
+    if sys.stderr.isatty():
+        _print("\x1b[3J\x1b[2J\x1b[H", err=True)
+
+
+def _recorded_fingerprint(core: BitcoinCore, secret: MasterSeed, fresh: bool) -> bytes | None:
+    """Take the master fingerprint from the wallet record until the library accepts it."""
+    if fresh:
+        _show_fingerprint(core, secret, "Write it on the wallet record")
+    prompt = "Type the master fingerprint from your wallet record" + ("" if fresh else " (Enter if none)")
+    while True:
+        text = _text(prompt, optional=True)
+        expected: bytes | None = None
+        if text or fresh:
+            try:
+                expected = parse_fingerprint(text)
+            except ValueError as error:
+                _print(str(error), err=True)
+                continue
+        elif _text(
+            "Without the record, only the backup identifier can be checked. Continue? [y/N]", optional=True
+        ).lower() not in ("y", "yes"):
+            continue
+        try:
+            core.verify_identity(secret, expected)
+        except FingerprintMismatch as error:
+            if expected is None:
+                raise
+            _print(str(error), err=True)
+            if fresh:
+                _show_fingerprint(core, secret, "Check the wallet record against it")
+            continue
+        return expected
+
+
 def _initialize_wallet(
     core: BitcoinCore,
     secret: MasterSeed,
@@ -346,10 +383,12 @@ def _initialize_wallet(
     try:
         if confirmed:
             _print("Master-seed backup confirmed.\n", err=True)
+        expected = _recorded_fingerprint(core, secret, fresh)
         name = core.initialize(
             secret,
             lambda prompt: _text(prompt, optional=True),
             lambda message: _print(message, err=True),
+            expected_fingerprint=expected,
             account=account,
             timestamp=timestamp,
         )