Merge pull request #2551 from SatoshiPortal/last-mnemonic-word-prediction

feat(mnemonic): checksum-aware last word entry and leak hardening

Author: ethicnology

lib/core/failures/mnemonic_entry_failure.dart

@@ -0,0 +1,35 @@
+import 'package:bb_mobile/core/failures/failure.dart';
+
+/// Why a typed mnemonic could not be accepted.
+///
+/// No variant carries a word, on purpose. The sentence being validated *is* the
+/// secret, and [Failure.logMessage] is documented as going to logs and Sentry.
+/// `bip39_mnemonic` builds its exception messages out of the offending word
+/// (`Mnemonic word "$word" does not exist in $language`,
+/// `Mnemonic checksum ${words.last} is invalid`), so those strings must be
+/// dropped where the exception is caught and never forwarded into a failure.
+sealed class MnemonicEntryFailure extends Failure {
+  const MnemonicEntryFailure([super.logMessage]);
+}
+
+/// At least one field is still blank.
+final class MnemonicEntryIncompleteFailure extends MnemonicEntryFailure {
+  const MnemonicEntryIncompleteFailure();
+}
+
+/// Every word is in the wordlist, but the sentence does not close its checksum
+/// — the transcription error the checksum exists to catch.
+final class MnemonicEntryInvalidChecksumFailure extends MnemonicEntryFailure {
+  const MnemonicEntryInvalidChecksumFailure();
+}
+
+/// At least one word is not in the wordlist of the selected language.
+final class MnemonicEntryUnknownWordFailure extends MnemonicEntryFailure {
+  const MnemonicEntryUnknownWordFailure();
+}
+
+/// Catch-all. [logMessage] holds the exception's *runtime type only* — never
+/// its message, which would carry a word.
+final class MnemonicEntryUnexpectedFailure extends MnemonicEntryFailure {
+  const MnemonicEntryUnexpectedFailure([super.logMessage]);
+}

lib/core/seed/data/repository/word_list_repository.dart

@@ -1,9 +1,7 @@
 import 'package:bb_mobile/core/seed/data/datasources/seed_datasource.dart';
 import 'package:bb_mobile/core/seed/data/repository/seed_repository.dart';
-import 'package:bb_mobile/core/seed/data/repository/word_list_repository.dart';
 import 'package:bb_mobile/core/seed/data/services/mnemonic_generator.dart';
 import 'package:bb_mobile/core/seed/domain/usecases/delete_seed_usecase.dart';
-import 'package:bb_mobile/core/seed/domain/usecases/find_mnemonic_words_usecase.dart';
 import 'package:bb_mobile/core/seed/domain/usecases/get_default_seed_usecase.dart';
 import 'package:bb_mobile/core/seed/domain/usecases/process_and_separate_seeds_usecase.dart';
 import 'package:bb_mobile/core/storage/data/datasources/key_value_storage/key_value_storage_datasource.dart';
@@ -26,10 +24,6 @@ class SeedLocator {
     locator.registerLazySingleton<SeedRepository>(
       () => SeedRepository(source: locator<SeedDatasource>()),
     );
-
-    locator.registerLazySingleton<WordListRepository>(
-      () => WordListRepository(),
-    );
   }
 
   static void registerServices(GetIt locator) {
@@ -39,12 +33,6 @@ class SeedLocator {
   }
 
   static void registerUsecases(GetIt locator) {
-    locator.registerFactory<FindMnemonicWordsUsecase>(
-      () => FindMnemonicWordsUsecase(
-        wordListRepository: locator<WordListRepository>(),
-      ),
-    );
-
     locator.registerFactory<GetDefaultSeedUsecase>(
       () => GetDefaultSeedUsecase(
         walletRepository: locator<WalletRepository>(),

lib/core/seed/domain/usecases/find_mnemonic_words_usecase.dart

@@ -1,5 +1,26 @@
 import 'package:bip39_mnemonic/bip39_mnemonic.dart' as bip39;
 
 class Bip39WordList {
-  static List<String> english() => bip39.Language.english.list;
+  /// The words that give [words] a valid checksum once appended to it.
+  ///
+  /// The last word of a sentence carries the whole checksum, so only a small
+  /// share of the wordlist can ever close it: 128 words for a 12 word
+  /// sentence, down to 8 for a 24 word one.
+  ///
+  /// Returns null when the question does not apply — [words] must hold every
+  /// word of the sentence but the last, and each of them must belong to
+  /// [language].
+  static List<String>? lastWordCandidates({
+    required List<String> words,
+    bip39.Language language = bip39.Language.english,
+  }) {
+    try {
+      return bip39.Mnemonic.lastWordCandidates(
+        words: words,
+        language: language,
+      );
+    } on bip39.MnemonicException {
+      return null;
+    }
+  }
 }

lib/core/seed/seed_locator.dart

@@ -0,0 +1,17 @@
+import 'package:bb_mobile/core/failures/mnemonic_entry_failure.dart';
+import 'package:bb_mobile/core/utils/build_context_x.dart';
+import 'package:flutter/widgets.dart';
+
+/// The only place a [MnemonicEntryFailure] becomes a user-facing string, so the
+/// failure family itself stays Flutter-free. The `sealed` switch makes a missing
+/// message a compile error.
+extension MnemonicEntryFailureL10n on MnemonicEntryFailure {
+  String toTranslated(BuildContext context) => switch (this) {
+    MnemonicEntryIncompleteFailure() => context.loc.emptyMnemonicWordsError,
+    MnemonicEntryInvalidChecksumFailure() =>
+      context.loc.mnemonicInvalidChecksumError,
+    MnemonicEntryUnknownWordFailure() => context.loc.mnemonicUnknownWordError,
+    // Never `logMessage`: generic message only, per rule #11.
+    MnemonicEntryUnexpectedFailure() => context.loc.oopsSomethingWentWrong,
+  };
+}