feat(backup): port the reminder engine and redesigned backup screen

Brings SatoshiPortal#2453 (13 commits) into the Get Paid
stack. The screen is a merge, not a copy: the fork already wraps a second
cubit and renders the inline "Bull backup" metadata card, so the upstream
skeleton is rebuilt around both.

The reminder engine is new to the fork. It answers one question — if this
phone vanished right now, could you get your money back? — and each posture
gets exactly one verb:

  - vault only, no physical: every 90 days, "add a physical backup"
  - physical done (± vault): every 365 days since the last test
  - a one-time popup the first time the device-key balance is observed at or
    above 10,000,000 sats
  - zero backup makes NO decision here; that state stays owned by the
    existing every-launch backup warning overlay

Each cadence is anchored on the clock of the thing being urged, so a fresh
vault write cannot silence a stale physical backup. Dismissing snoozes the
popup for a full cycle and never touches last_tested, so the screen keeps
telling the truth while the popup is quiet. There is deliberately no PIN or
vault-freshness reminder and no both-verified "review" nag: neither has an
action behind it.

The screen becomes status rows -> posture hero -> Start Backup button ->
menu rows, each section built by its own function so the fork's metadata
insertions land without disturbing the others. Start Backup is a button
rather than a settings row, and it is suppressed only in the zero-backup
state where the hero already offers it.

Recoverbull: the vault permission gate is gone (nothing else in the fork
consumed FetchPermission/AllowPermission), a custom key server URL now warns
before it is saved, and user-facing "Recoverbull" vocabulary is retired in
favour of "encrypted vault" — while keeping the recoverbull.com domain
strings and the four server-product strings.

Localization follows the fork rule: retired wording is deleted from every
locale and re-added EN-only so stale translations cannot resurface;
unchanged wording keeps its translations. 9 keys deleted, 4 reworded,
21 added.

Author: FrancisPouliot

FEATURES.md

@@ -85,6 +85,7 @@ graph TB
     BACKUPS --> WALLET_BACKUP
     BACKUPS --> WALLETS
     BTC_PRICE --> SETTINGS
+    ONBOARDING --> BACKUPS
     BTCPAY --> BIP85_REGISTRY
     BTCPAY --> DETERMINISTIC_WALLETS
     BTCPAY --> KEYCHAIN_MANIFEST

README.md

@@ -70,6 +70,7 @@ Automated selection of the wallet can be overridden by the user at any time. Thi
 - BIP39 passphrase is also stored in secure storage, and can be viewed only via the application.
 - When initializing the app, a single-sig hot wallet wallet is created. By default, this wallet does not have a BIP39 passphrase.
 - A warning is displayed until the user has tested their backup by successfully entering the mnemonic.
+- Verified backups receive periodic health reminders based on elapsed time and mainnet hot-wallet balance milestones. See [Backup health reminders](docs/backup-health-reminders.md) for the exact behavior.
 
 ### Hardware wallets and watch-only wallets
 

docs/backup-health-reminders.md

@@ -0,0 +1,120 @@
+# Backup health reminders
+
+Every backup surface answers one question: **if this phone vanished right now, could you get your money back?** Each state has exactly one honest answer and exactly one thing to do about it.
+
+| Situation | Honest answer | The one action |
+| --- | --- | --- |
+| Nothing backed up | No — the money is gone | Back up, urgently |
+| Encrypted Vault only | Probably — it needs the server up and your PIN | Add a physical backup |
+| Physical backup done (with or without a vault) | Yes — if the words are still findable and correct | Occasionally confirm that is still true |
+
+## One surface per state
+
+Three surfaces, three tenses, no overlap:
+
+- the **every-launch warning** (`backup_warning_overlay.dart`) means "you are unprotected right now". Zero-backup only, unchanged by this feature.
+- the **reminder popup** means "it has been a while, or something changed". Every posture except zero-backup.
+- the **Backup Settings hero** means "here is your standing situation". Always available on the screen you visit deliberately.
+
+So zero backup gets the warning and the hero, never the popup; every other state gets the popup and the hero, never the warning. One popup asks one question and offers one action.
+
+## Reminder matrix
+
+The reminder is evaluated for the default mainnet hot-wallet seed once at least one backup method has been verified.
+
+| Verified backup posture | Reminder | Action |
+| --- | --- | --- |
+| No verified backup | None. The existing no-backup warning owns this state. | — |
+| Encrypted Vault only | Every 90 days: without a physical backup you cannot recover if the vault server is unavailable. | Add a physical backup |
+| Physical backup, with or without a vault | Every 365 days since the physical backup was last tested. | Test the backup |
+
+There is deliberately **no vault-freshness or PIN reminder**. A vault-only wallet's real exposure is depending on someone else for its only recovery path, and the fix for that is a physical backup, not a PIN rehearsal. Once a physical backup exists, PIN rot cannot cost the user their money.
+
+## Timing
+
+A scheduled reminder is anchored on the clock of the thing being urged:
+
+- vault only — the latest vault backup, or the last acknowledgement;
+- physical backup present — the latest *physical* backup test, or the last acknowledgement. A fresh vault does not buy silence about words that were last read two years ago.
+
+A verified backup with no completion timestamp is due immediately.
+
+Dismissing a reminder snoozes it for a full cycle (90 or 365 days). It never writes a tested timestamp, so the Backup Settings screen keeps saying how long ago the backup was really tested while the popup is quiet. Only completing a verification flow resets that date; creating a backup counts as tested on day zero, because the creation flow tests it.
+
+The popup is shown on the wallet home screen only, and only once the higher-priority no-backup and legacy-storage warnings are clear. A deep link or payment intent lands on its own route, so nothing ever stands between a payment and its completion.
+
+## Balance milestone
+
+The first time an evaluation observes an eligible balance of **10,000,000 sats or more**, the reminder is shown once, whatever the schedule says, with the posture-appropriate ask. The comparison is inclusive: exactly 10,000,000 sats counts.
+
+That notice is retired for the lifetime of the wallet as soon as the user either dismisses it or acts on it. A balance later dropping below the threshold and crossing it again changes nothing — a wallet is told once.
+
+## Eligible wallets and balances
+
+Only mainnet wallets whose keys are held on the device participate in reminder evaluation and in the balance total.
+
+Included:
+
+- default Bitcoin and Liquid hot-wallet balances;
+- imported hot wallets that sign locally; and
+- the Ark balance, which is mainnet-only in the app.
+
+Excluded:
+
+- every testnet wallet and testnet backup record;
+- watch-only wallets;
+- watch-signer wallets; and
+- hardware wallets.
+
+## Backup completion timestamps
+
+Backup timestamps represent successful completion, not the start of a flow.
+
+Physical backup verification records one completion time after the mnemonic has been entered in the correct order and the updated backup state has been persisted. Wallets in the active environment that share the verified master fingerprint receive the same completion time.
+
+Recoverbull records completion only after both the encrypted vault file and its server-held recovery key have been stored successfully. The completion update targets the exact wallet used to create the vault, preventing a testnet backup from changing mainnet backup state.
+
+## Evaluation and persistence
+
+The overlay evaluates when wallet data or the Ark balance changes, after its first frame, and when the app resumes. An empty or ineligible wallet list hides any previously visible reminder.
+
+Reminder state is stored locally in a versioned SharedPreferences record keyed by master fingerprint. It contains only:
+
+- the last acknowledgement time; and
+- whether the balance milestone has been shown.
+
+No mnemonic, seed, private key, vault key, or other secret is stored or logged by the reminder. Keys written by an earlier shape of the record are ignored rather than rejected. Malformed, unsupported, or unreadable records are replaced with an empty in-memory record, which favors showing another reminder over suppressing one indefinitely. The underlying read failure is logged without exposing it to the user.
+
+If a reminder action cannot be persisted, the overlay stays visible so the user can retry. A localized "close for now" action is then available as a session-only escape; it does not acknowledge the reminder, so the app evaluates it again on the next launch.
+
+## Backup Settings screen
+
+The screen is composed top to bottom as status rows, then at most one hero, then the settings menu:
+
+1. **Status rows** — Physical Backup and Encrypted Vault, each Tested or Not tested, with a muted "Last tested …" line under a tested physical backup.
+2. **Hero** — the single most useful action right now, or nothing at all: an urgent *Back up your wallet* card when nothing is backed up, *add a physical backup* for a vault-only wallet, *test your backup* once the physical test is over a year old, and no card when the physical backup is fresh. The hero derives its posture from the same domain code the reminder uses, so the two can never disagree.
+3. **Menu** — Encrypted vault settings, Labels, Transaction History, plus the vault-key and test-backup entries when they apply. There is no "Start Backup" row: the zero-backup hero is the way in.
+
+## Architecture
+
+The feature follows the repository flow described in `ARCHITECTURE.md`:
+
+```text
+overlay -> cubit -> use cases -> reminder repository -> SharedPreferences
+```
+
+The repository boundary uses a domain entity and a separate persistence model. Recoverable errors cross the UI boundary as typed failures and are translated in the presentation layer. Cross-feature calls use the public test-wallet-backup facade and route contract.
+
+## Tests
+
+The focused suite covers the posture matrix, both cadences and their exact boundaries, the anchor rule (a fresh vault must not silence a stale physical backup), the inclusive milestone threshold and its once-per-wallet guarantee, dismissal snoozing without recording a test, testnet and non-local-signer exclusions, persistence corruption, and each hero the screen can render.
+
+Run it with:
+
+```sh
+fvm flutter test test/features/backup_settings \
+  test/features/onboarding/domain/complete_physical_backup_verification_usecase_test.dart \
+  test/features/test_wallet_backup/domain/complete_physical_backup_verification_usecase_test.dart \
+  test/features/recoverbull/domain/complete_encrypted_vault_backup_usecase_test.dart \
+  test/features/recoverbull/recoverbull_bloc_test.dart
+```

integration_test/fiat_settlement_funded_witness_test.dart

@@ -314,8 +314,18 @@ Future<bool> _prepareWitnessWallet({
     return true;
   }
 
-  final (mnemonicWords, passphrase) =
-      await locator<GetMnemonicFromFingerprintUsecase>().execute(fingerprint);
+  final (
+    mnemonicWords,
+    passphrase,
+  ) = switch (await locator<GetMnemonicFromFingerprintUsecase>().execute(
+    fingerprint,
+  )) {
+    Ok(:final value) => value,
+    // The witness run cannot capture a seed it could not read.
+    Err(:final failure) => fail(
+      'could not read the witness seed: ${failure.logMessage}',
+    ),
+  };
   final seedPath = await config.writeSeedCapture({
     'schema': 'fiat-witness-seed-capture/v1',
     'run_id': config.runId,

lib/core/recoverbull/data/datasources/recoverbull_settings_datasource.dart

@@ -1,5 +1,4 @@
 import 'package:bb_mobile/core/storage/sqlite_database.dart';
-import 'package:drift/drift.dart';
 
 class RecoverbullSettingsDatasource {
   final SqliteDatabase _sqlite;
@@ -24,17 +23,4 @@ class RecoverbullSettingsDatasource {
         .getSingle();
     return Uri.parse(row.url);
   }
-
-  Future<void> allowPermission(bool isGranted) async {
-    await _sqlite.managers.recoverbull.update(
-      (f) => f(id: const Value(1), isPermissionGranted: Value(isGranted)),
-    );
-  }
-
-  Future<bool> fetchPermission() async {
-    final row = await _sqlite.managers.recoverbull
-        .filter((f) => f.id(1))
-        .getSingle();
-    return row.isPermissionGranted;
-  }
 }

lib/core/recoverbull/data/repository/recoverbull_repository.dart

@@ -147,14 +147,6 @@ class RecoverBullRepository {
     await recoverbullSettingsDatasource.store(url);
   }
 
-  Future<void> allowPermission(bool isGranted) async {
-    await recoverbullSettingsDatasource.allowPermission(isGranted);
-  }
-
-  Future<bool> fetchPermission() async {
-    return await recoverbullSettingsDatasource.fetchPermission();
-  }
-
   // Mirrors the legacy `ServerError.fromException`, null-safe on the 429 path.
   RecoverBullCoreFailure _mapKeyServer(recoverbull.KeyServerException e) {
     final code = e.code;

lib/core/recoverbull/domain/usecases/allow_permission_usecase.dart

@@ -27,7 +27,10 @@ class CreateEncryptedVaultUsecase {
   // repo. The local try/catch is the boundary for the wallet/seed calls; the
   // recoverbull repo already returns a Result that we forward.
   Future<
-    Result<({EncryptedVault vault, String vaultKey}), RecoverBullCoreFailure>
+    Result<
+      ({EncryptedVault vault, String vaultKey, String walletId}),
+      RecoverBullCoreFailure
+    >
   >
   execute() async {
     try {
@@ -44,10 +47,6 @@ class CreateEncryptedVaultUsecase {
 
       // The default wallet is used to derive the backup key
       final defaultWallet = defaultBitcoinWallets.first;
-      await _walletRepository.updateEncryptedBackupTime(
-        time: DateTime.now(),
-        walletId: defaultWallet.id,
-      );
       final defaultSeed = await _seedRepository.get(
         defaultWallet.masterFingerprint,
       );
@@ -90,7 +89,10 @@ class CreateEncryptedVaultUsecase {
             plaintext: plaintext,
             derivationPath: derivationPath,
           )
-          .map((vault) => (vault: vault, vaultKey: backupKey));
+          .map(
+            (vault) =>
+                (vault: vault, vaultKey: backupKey, walletId: defaultWallet.id),
+          );
     } catch (e, st) {
       log.severe(message: 'createEncryptedVault failed', error: e, trace: st);
       return Err(RecoverBullUnexpectedCoreFailure(e.toString()));

lib/core/recoverbull/domain/usecases/create_encrypted_vault_usecase.dart

@@ -5,11 +5,9 @@ import 'package:bb_mobile/core/recoverbull/data/datasources/recoverbull_settings
 import 'package:bb_mobile/core/recoverbull/data/repository/file_system_repository.dart';
 import 'package:bb_mobile/core/recoverbull/data/repository/google_drive_repository.dart';
 import 'package:bb_mobile/core/recoverbull/data/repository/recoverbull_repository.dart';
-import 'package:bb_mobile/core/recoverbull/domain/usecases/allow_permission_usecase.dart';
 import 'package:bb_mobile/core/recoverbull/domain/usecases/check_server_connection_usecase.dart';
 import 'package:bb_mobile/core/recoverbull/domain/usecases/create_encrypted_vault_usecase.dart';
 import 'package:bb_mobile/core/recoverbull/domain/usecases/decrypt_vault_usecase.dart';
-import 'package:bb_mobile/core/recoverbull/domain/usecases/fetch_permission_usecase.dart';
 import 'package:bb_mobile/core/recoverbull/domain/usecases/fetch_recoverbull_url_usecase.dart';
 import 'package:bb_mobile/core/recoverbull/domain/usecases/fetch_vault_key_from_server_usecase.dart';
 import 'package:bb_mobile/core/recoverbull/domain/usecases/google_drive/connect_google_drive_usecase.dart';
@@ -196,15 +194,5 @@ class RecoverbullLocator {
         recoverBullRepository: locator<RecoverBullRepository>(),
       ),
     );
-    locator.registerFactory<AllowPermissionUsecase>(
-      () => AllowPermissionUsecase(
-        recoverBullRepository: locator<RecoverBullRepository>(),
-      ),
-    );
-    locator.registerFactory<FetchPermissionUsecase>(
-      () => FetchPermissionUsecase(
-        recoverBullRepository: locator<RecoverBullRepository>(),
-      ),
-    );
   }
 }