fix(transactions): verify server data before labels, binding and export

Addresses the TXUI findings from the security audit:
- #2624: exchange labels are written only from an explicit
  order-completion event through the new TransactionsFacade, wired to
  the buy and sell completion paths — never from history reads; only
  completed buy/sell orders are labeled
- #2625: neutralize CSV cells starting with =, +, -, @, tab or CR so
  server-provided swap strings cannot inject spreadsheet formulas
- #2663: validate exchange-order binding against on-chain address,
  amount and direction instead of the server-provided tx id alone
- #2664: validate swap binding against the wallet and amount, and
  deduplicate by verified on-chain identity instead of server ids
- #2665: map aggregation failures to a sealed TransactionFailure with
  a generic localized message instead of rendering raw exception text

Regression tests: test/security_audit/issue_2624_test.dart,
issue_2625_test.dart, issue_2663_test.dart, issue_2664_test.dart,
issue_2665_test.dart

Author: ethicnology

FEATURES.md

@@ -74,6 +74,7 @@ graph TB
     BUY --> EXCHANGE
     BUY --> RECEIVE
     BUY --> BULL_PAYJOIN
+    BUY --> TX_HISTORY
     COINS --> UTXO_MGMT
     COINS --> LABELS
     COINS --> WALLETS
@@ -94,6 +95,7 @@ graph TB
     SECRETS --> CORE
     SELL --> EXCHANGE
     SELL --> BULL_PAYJOIN
+    SELL --> TX_HISTORY
     SEND --> CONSOLIDATION
     SEND --> FEES
     SEND --> NETWORK

lib/features/buy/buy_locator.dart

@@ -8,6 +8,8 @@ import 'package:bb_mobile/core/wallet/domain/usecases/get_receive_address_usecas
 import 'package:bb_mobile/core/wallet/domain/usecases/get_wallets_usecase.dart';
 import 'package:bb_mobile/features/buy/domain/accelerate_buy_order_usecase.dart';
 import 'package:bb_mobile/features/buy/domain/cancel_abandoned_buy_payjoin_usecase.dart';
+import 'package:bb_mobile/features/buy/domain/label_completed_buy_order_usecase.dart';
+import 'package:bb_mobile/features/transactions/transactions_facade.dart';
 import 'package:bb_mobile/features/buy/domain/confirm_buy_order_usecase.dart';
 import 'package:bb_mobile/features/buy/domain/create_buy_order_usecase.dart';
 import 'package:bb_mobile/features/buy/domain/get_buy_payjoin_enabled_usecase.dart';
@@ -40,6 +42,11 @@ class BuyLocator {
     locator.registerFactory<GetBuyPayjoinEnabledUsecase>(
       () => GetBuyPayjoinEnabledUsecase(locator<PayjoinPolicyAccess>()),
     );
+    locator.registerFactory<LabelCompletedBuyOrderUsecase>(
+      () => LabelCompletedBuyOrderUsecase(
+        transactionsFacade: locator<TransactionsFacade>(),
+      ),
+    );
     registerBlocs(locator);
   }
 
@@ -60,6 +67,7 @@ class BuyLocator {
         cancelAbandonedBuyPayjoinUsecase:
             locator<CancelAbandonedBuyPayjoinUsecase>(),
         getBuyPayjoinEnabledUsecase: locator<GetBuyPayjoinEnabledUsecase>(),
+        labelCompletedBuyOrderUsecase: locator<LabelCompletedBuyOrderUsecase>(),
       ),
     );
   }

lib/features/buy/domain/label_completed_buy_order_usecase.dart

@@ -0,0 +1,15 @@
+import 'package:bb_mobile/core/exchange/domain/entity/order.dart';
+import 'package:bb_mobile/features/transactions/transactions_facade.dart';
+
+/// Writes the privileged exchange-buy labels when a buy order explicitly
+/// completes (issue #2624: labels must never be written from history reads).
+class LabelCompletedBuyOrderUsecase {
+  final TransactionsFacade _transactionsFacade;
+
+  LabelCompletedBuyOrderUsecase({required this._transactionsFacade});
+
+  Future<void> execute({required Order order}) async {
+    if (order.orderStatus != OrderStatus.completed) return;
+    await _transactionsFacade.labelCompletedExchangeOrders([order]);
+  }
+}

lib/features/buy/presentation/buy_bloc.dart

@@ -11,6 +11,7 @@ import 'package:bb_mobile/core/settings/domain/get_settings_usecase.dart';
 import 'package:bb_mobile/core/settings/domain/settings_entity.dart';
 import 'package:bb_mobile/core/utils/amount_conversions.dart';
 import 'package:bb_mobile/core/utils/logger.dart';
+import 'package:bb_mobile/features/buy/domain/label_completed_buy_order_usecase.dart';
 import 'package:bb_mobile/core/wallet/domain/entities/wallet.dart';
 import 'package:bb_mobile/core/wallet/domain/usecases/get_receive_address_usecase.dart';
 import 'package:bb_mobile/core/wallet/domain/usecases/get_wallets_usecase.dart';
@@ -41,6 +42,7 @@ class BuyBloc extends Bloc<BuyEvent, BuyState> {
     required this._getSettingsUsecase,
     required this._cancelAbandonedBuyPayjoinUsecase,
     required this._getBuyPayjoinEnabledUsecase,
+    required this._labelCompletedBuyOrderUsecase,
   }) : super(const BuyState()) {
     on<_BuyStarted>(_onStarted);
     on<_BuyAmountInputChanged>(_onAmountInputChanged);
@@ -68,6 +70,7 @@ class BuyBloc extends Bloc<BuyEvent, BuyState> {
   final GetSettingsUsecase _getSettingsUsecase;
   final CancelAbandonedBuyPayjoinUsecase _cancelAbandonedBuyPayjoinUsecase;
   final GetBuyPayjoinEnabledUsecase _getBuyPayjoinEnabledUsecase;
+  final LabelCompletedBuyOrderUsecase _labelCompletedBuyOrderUsecase;
 
   Future<void> _onStarted(_BuyStarted event, Emitter<BuyState> emit) async {
     try {
@@ -302,6 +305,10 @@ class BuyBloc extends Bloc<BuyEvent, BuyState> {
 
       if (order.isExpired()) await _cancelAbandonedPayjoin(order);
 
+      // The explicit order-completion event is the only legitimate writer
+      // of privileged exchange labels (issue #2624).
+      await _labelCompletedBuyOrderUsecase.execute(order: order);
+
       emit(state.copyWith(buyOrder: order));
     } catch (e) {
       log.severe(error: e, trace: StackTrace.current);

lib/features/sell/domain/label_completed_sell_order_usecase.dart

@@ -0,0 +1,15 @@
+import 'package:bb_mobile/core/exchange/domain/entity/order.dart';
+import 'package:bb_mobile/features/transactions/transactions_facade.dart';
+
+/// Writes the privileged exchange-sell labels when a sell order explicitly
+/// completes (issue #2624: labels must never be written from history reads).
+class LabelCompletedSellOrderUsecase {
+  final TransactionsFacade _transactionsFacade;
+
+  LabelCompletedSellOrderUsecase({required this._transactionsFacade});
+
+  Future<void> execute({required Order order}) async {
+    if (order.orderStatus != OrderStatus.completed) return;
+    await _transactionsFacade.labelCompletedExchangeOrders([order]);
+  }
+}

lib/features/sell/presentation/bloc/sell_bloc.dart

@@ -23,6 +23,7 @@ import 'package:bb_mobile/core/wallet/domain/entities/wallet_utxo.dart';
 import 'package:bb_mobile/core/wallet/domain/usecases/get_address_at_index_usecase.dart';
 import 'package:bb_mobile/core/wallet/domain/usecases/get_wallet_utxos_usecase.dart';
 import 'package:bb_mobile/features/labels/labels_facade.dart';
+import 'package:bb_mobile/features/sell/domain/label_completed_sell_order_usecase.dart';
 import 'package:bb_mobile/features/sell/domain/create_sell_order_usecase.dart';
 import 'package:bb_mobile/features/sell/domain/refresh_sell_order_usecase.dart';
 import 'package:bb_mobile/features/sell/domain/get_payjoin_usecase.dart';
@@ -72,6 +73,7 @@ class SellBloc extends Bloc<SellEvent, SellState>
     required this._getWalletUtxosUsecase,
     required this._getOrderUsecase,
     required this._labelsFacade,
+    required this._labelCompletedSellOrderUsecase,
     required this._previewBitcoinFeeUsecase,
     required this._previewBitcoinFeePresetsUsecase,
   }) : super(const SellState.initial()) {
@@ -121,6 +123,7 @@ class SellBloc extends Bloc<SellEvent, SellState>
   final GetWalletUtxosUsecase _getWalletUtxosUsecase;
   final GetOrderUsecase _getOrderUsecase;
   final LabelsFacade _labelsFacade;
+  final LabelCompletedSellOrderUsecase _labelCompletedSellOrderUsecase;
   final PreviewBitcoinFeeUsecase _previewBitcoinFeeUsecase;
   final PreviewBitcoinFeePresetsUsecase _previewBitcoinFeePresetsUsecase;
   Timer? _pollingTimer;
@@ -923,6 +926,9 @@ class SellBloc extends Bloc<SellEvent, SellState>
           return;
         }
         await _labelPayjoinSellTransaction(latestOrder, null);
+        // The explicit order-completion event is the only legitimate writer
+        // of privileged exchange labels (issue #2624).
+        await _labelCompletedSellOrderUsecase.execute(order: latestOrder);
         if (!latestOrder.payjoinOutcome.isOngoing) _stopPolling();
         emit(sellSuccessState.copyWith(sellOrder: latestOrder));
       } catch (e) {

lib/features/sell/sell_locator.dart

@@ -10,6 +10,8 @@ import 'package:bb_mobile/core/settings/domain/get_settings_usecase.dart';
 import 'package:bb_mobile/core/wallet/domain/usecases/get_address_at_index_usecase.dart';
 import 'package:bb_mobile/core/wallet/domain/usecases/get_wallet_utxos_usecase.dart';
 import 'package:bb_mobile/features/labels/labels_facade.dart';
+import 'package:bb_mobile/features/sell/domain/label_completed_sell_order_usecase.dart';
+import 'package:bb_mobile/features/transactions/transactions_facade.dart';
 import 'package:bb_mobile/features/sell/domain/create_sell_order_usecase.dart';
 import 'package:bb_mobile/features/sell/domain/get_payjoin_usecase.dart';
 import 'package:bb_mobile/features/sell/domain/refresh_sell_order_usecase.dart';
@@ -68,6 +70,12 @@ class SellLocator {
       ),
     );
 
+    locator.registerFactory<LabelCompletedSellOrderUsecase>(
+      () => LabelCompletedSellOrderUsecase(
+        transactionsFacade: locator<TransactionsFacade>(),
+      ),
+    );
+
     locator.registerFactory<GetAddressAtIndexUsecase>(
       () => GetAddressAtIndexUsecase(walletAddressRepository: locator()),
     );
@@ -102,6 +110,8 @@ class SellLocator {
         getWalletUtxosUsecase: locator<GetWalletUtxosUsecase>(),
         getOrderUsecase: locator<GetOrderUsecase>(),
         labelsFacade: locator<LabelsFacade>(),
+        labelCompletedSellOrderUsecase:
+            locator<LabelCompletedSellOrderUsecase>(),
         previewBitcoinFeeUsecase: locator<PreviewBitcoinFeeUsecase>(),
         previewBitcoinFeePresetsUsecase:
             locator<PreviewBitcoinFeePresetsUsecase>(),

lib/features/transactions/adapters/csv_transaction_export_formatter.dart

@@ -120,11 +120,19 @@ class CsvTransactionExportFormatter implements TransactionExportFormatter {
         swap?.isLnSendSwap == true || swap?.isLnReceiveSwap == true;
     final isChainSwap = swap?.isChainSwap == true;
     final amountSat = tx.amountSat;
+    // Prefer the fee the wallet observed on-chain over the one the swap
+    // provider reports: an export is accounting data and must not carry a
+    // server-controlled figure when the real one is known locally. The
+    // provider value stays as the fallback for a leg whose miner fee the
+    // wallet never saw (0 = unknown here, a broadcast tx always pays a fee).
+    final onChainFeeSat = wt?.feeSat ?? 0;
     final feeSat = isChainSwap
         ? (wt?.isOutgoing == true
-              ? (swap?.fees?.lockupFee ?? wt?.feeSat ?? 0)
+              ? (onChainFeeSat > 0
+                    ? onChainFeeSat
+                    : (swap?.fees?.lockupFee ?? 0))
               : (swap?.fees?.claimFee ?? 0))
-        : (tx.isIncoming ? 0 : (wt?.feeSat ?? 0));
+        : (tx.isIncoming ? 0 : onChainFeeSat);
 
     final type = _resolveType(tx, swap, payjoin);
     final direction = _resolveDirection(tx, wt);
@@ -268,6 +276,11 @@ class CsvTransactionExportFormatter implements TransactionExportFormatter {
   String _btc(int sats) => (sats / 100000000).toStringAsFixed(8);
 
   String _escape(String value) {
+    // Prefix formula-like cells so spreadsheet applications treat them as
+    // text. This applies even when the cell also needs CSV quoting.
+    if (value.isNotEmpty && '=+-@\t\r'.contains(value[0])) {
+      value = "'$value";
+    }
     if (value.contains(',') ||
         value.contains('"') ||
         value.contains('\n') ||

lib/features/transactions/application/usecases/get_transactions_usecase.dart

@@ -3,10 +3,12 @@ import 'package:bb_mobile/core/exchange/domain/repositories/exchange_order_repos
 import 'package:bb_mobile/core/settings/domain/repositories/settings_repository.dart';
 import 'package:bb_mobile/core/swaps/domain/entity/swap.dart';
 import 'package:bb_mobile/core/swaps/domain/repositories/swap_history_repository.dart';
+import 'package:bb_mobile/core/wallet/domain/entities/wallet_transaction.dart';
 import 'package:bb_mobile/core/wallet/domain/repositories/wallet_transaction_repository.dart';
+import 'package:bb_mobile/core/utils/amount_conversions.dart';
 import 'package:bb_mobile/core/utils/logger.dart';
-import 'package:bb_mobile/features/transactions/application/usecases/label_exchange_orders_usecase.dart';
 import 'package:bb_mobile/features/transactions/domain/entities/transaction.dart';
+import 'package:bb_mobile/features/transactions/domain/transaction_failure.dart';
 import 'package:bull_payjoin/bull_payjoin.dart';
 import 'package:primitives/primitives.dart';
 
@@ -17,7 +19,6 @@ class GetTransactionsUsecase {
   final PayjoinSessions _payjoinSessions;
   final ExchangeOrderRepository _mainnetExchangeOrderRepository;
   final ExchangeOrderRepository _testnetExchangeOrderRepository;
-  final LabelExchangeOrdersUsecase _labelExchangeOrdersUsecase;
 
   GetTransactionsUsecase({
     required this._settingsRepository,
@@ -26,7 +27,6 @@ class GetTransactionsUsecase {
     required this._payjoinSessions,
     required this._mainnetExchangeOrderRepository,
     required this._testnetExchangeOrderRepository,
-    required this._labelExchangeOrdersUsecase,
   });
 
   Future<List<Transaction>> execute({
@@ -41,7 +41,6 @@ class GetTransactionsUsecase {
           : _mainnetExchangeOrderRepository;
 
       final orders = await orderRepository.getOrders();
-      await _labelExchangeOrdersUsecase.execute(orders: orders);
 
       // Labels must exist before wallet transactions are hydrated.
       final (walletTransactions, payjoinResult, swaps) = await (
@@ -76,12 +75,16 @@ class GetTransactionsUsecase {
       final broadcastedTransactions = walletTransactions.map((wt) {
         Swap? swap;
         try {
-          swap = swaps.firstWhere(
-            (s) =>
+          swap = swaps.firstWhere((s) {
+            final claimedLeg =
                 (wt.isOutgoing && s.sendTxId == wt.txId) ||
                 (wt.isIncoming &&
-                    (s.receiveTxId == wt.txId || s.refundTxId == wt.txId)),
-          );
+                    (s.receiveTxId == wt.txId || s.refundTxId == wt.txId));
+            return claimedLeg &&
+                s.walletId == wt.walletId &&
+                (s.amountSat == 0 || wt.amountSat <= s.amountSat) &&
+                _transactionPaysSwapAddress(wt, s);
+          });
         } catch (_) {
           // If no swap is found, it means the transaction is not a swap
           swap = null;
@@ -107,7 +110,18 @@ class GetTransactionsUsecase {
 
         Order? order;
         try {
-          order = orders.firstWhere((o) => o.transactionId == wt.txId);
+          order = orders.firstWhere((o) {
+            if (o.transactionId != wt.txId) return false;
+            if (o.toAddress != null && o.toAddress != wt.toAddress) {
+              return false;
+            }
+            final expectedDirection = o is BuyOrder
+                ? wt.isIncoming
+                : o is SellOrder
+                ? wt.isOutgoing
+                : true;
+            return expectedDirection && _transactionCoversOrderAmount(wt, o);
+          });
           // Remove the order from the list of orders to avoid duplication
           //  since it's already included in the broadcasted transaction
           orders.remove(order);
@@ -196,7 +210,66 @@ class GetTransactionsUsecase {
         error: e,
         trace: stackTrace,
       );
-      throw Exception('Failed to fetch transactions: $e');
+      throw TransactionAggregationFailure(e.toString());
+    }
+  }
+
+  /// The exchange tells us which address a completed order paid. Before the
+  /// order is attached to one of the user's transactions, that transaction
+  /// must actually have moved at least what the order claims — otherwise a
+  /// wrong or hostile server figure gets attributed to unrelated funds.
+  ///
+  /// `>=` rather than `==` on purpose: payouts are batched, so one transaction
+  /// can legitimately carry several orders and more sats than a single one.
+  bool _transactionCoversOrderAmount(WalletTransaction wt, Order order) {
+    final double declared;
+    switch (order) {
+      case BuyOrder(:final payoutAmount, :final payoutCurrency):
+        if (payoutCurrency != 'BTC') return true;
+        declared = payoutAmount;
+      case SellOrder(:final payinAmount, :final payinCurrency):
+        if (payinCurrency != 'BTC') return true;
+        declared = payinAmount;
+      default:
+        return true;
     }
+    final declaredSat = ConvertAmount.btcToSats(declared);
+    if (declaredSat <= 0) return true;
+    return wt.amountSat >= declaredSat;
+  }
+
+  /// A swap leg is only this transaction's if the transaction actually pays
+  /// the address the swap is built around. Matching on the server-reported
+  /// txid alone lets a wrong id graft a swap onto an unrelated payment.
+  bool _transactionPaysSwapAddress(WalletTransaction wt, Swap swap) {
+    // Liquid outputs expose the unconfidential address while a swap address is
+    // confidential, so the two are not comparable here; the txid + wallet +
+    // amount checks remain. TODO(swaps): unblind before comparing.
+    if (!wt.isBitcoin) return true;
+
+    final expected = <String>{
+      if (wt.isOutgoing)
+        ...switch (swap) {
+          LnSendSwap(:final paymentAddress) => [paymentAddress],
+          ChainSwap(:final paymentAddress) => [paymentAddress],
+          _ => <String>[],
+        },
+      if (wt.isIncoming)
+        ...switch (swap) {
+          LnReceiveSwap(:final receiveAddress) => [?receiveAddress],
+          ChainSwap(:final receiveAddress, :final refundAddress) => [
+            ?receiveAddress,
+            ?refundAddress,
+          ],
+          LnSendSwap(:final refundAddress) => [?refundAddress],
+        },
+    };
+    // Nothing to compare against (a recovered swap carries no address): fall
+    // back to the other checks rather than dropping a legitimate leg.
+    if (expected.isEmpty) return true;
+
+    return wt.outputs.any(
+      (output) => output.address != null && expected.contains(output.address),
+    );
   }
 }