feat(electrum): route onion servers through isolated Tor

Author: ethicnology

lib/core/electrum/adapters/electrum_servers_adapter.dart

@@ -1,25 +1,29 @@
 import 'package:bb_mobile/core/electrum/domain/electrum_fallback_runner.dart';
 import 'package:bb_mobile/core/electrum/domain/errors/electrum_fallback_exception.dart';
 import 'package:bb_mobile/core/electrum/domain/ports/electrum_servers_port.dart';
+import 'package:bb_mobile/core/electrum/domain/ports/electrum_tor_session_port.dart';
 import 'package:bb_mobile/core/electrum/domain/repositories/electrum_server_repository.dart';
 import 'package:bb_mobile/core/electrum/domain/repositories/electrum_settings_repository.dart';
 import 'package:bb_mobile/core/electrum/domain/value_objects/electrum_connection.dart';
 import 'package:bb_mobile/core/electrum/domain/value_objects/electrum_server_network.dart';
+import 'package:bb_mobile/core/electrum/domain/value_objects/electrum_server_url.dart';
 import 'package:bb_mobile/core/settings/domain/repositories/settings_repository.dart';
 
 /// Concrete [ElectrumServersPort]. Owns the only place in the app where the
-/// active server list is resolved, merged with electrum + Tor settings, and
+/// active server list is resolved, merged with Electrum + Orbot settings, and
 /// iterated — there is no other path consumers can take to reach an Electrum
 /// server, which is what enforces the R1/R2/R2a privacy rule by construction.
 class ElectrumServersAdapter implements ElectrumServersPort {
   final ElectrumServerRepository _serverRepository;
   final ElectrumSettingsRepository _settingsRepository;
   final SettingsRepository _appSettingsRepository;
+  final ElectrumTorSessionPort _torSessionPort;
 
   ElectrumServersAdapter({
     required this._serverRepository,
     required this._settingsRepository,
     required this._appSettingsRepository,
+    required this._torSessionPort,
   });
 
   @override
@@ -54,11 +58,6 @@ class ElectrumServersAdapter implements ElectrumServersPort {
       throw NoElectrumServersConfiguredException(network);
     }
 
-    // Tor proxy applies to Bitcoin only, never Liquid.
-    final socks5 = (appSettings.useTorProxy && !network.isLiquid)
-        ? (settings.socks5 ?? '127.0.0.1:${appSettings.torProxyPort}')
-        : settings.socks5;
-
     final connections = servers
         .map(
           (server) => ElectrumConnection(
@@ -68,7 +67,7 @@ class ElectrumServersAdapter implements ElectrumServersPort {
             stopGap: settings.stopGap,
             validateDomain: settings.validateDomain,
             isCustom: server.isCustom,
-            socks5: socks5,
+            socks5: settings.socks5,
           ),
         )
         .toList();
@@ -77,8 +76,39 @@ class ElectrumServersAdapter implements ElectrumServersPort {
       servers: connections,
       urlOf: (c) => c.url,
       isCustomOf: (c) => c.isCustom,
-      operation: operation,
-      isTransient: isTransient,
+      operation: (connection) async {
+        final route = await _torSessionPort.open(
+          network: network,
+          serverUrl: connection.url,
+          externalProxyEnabled: appSettings.useTorProxy,
+          externalProxyPort: appSettings.torProxyPort,
+        );
+        try {
+          final routed = connection.withSocks5(
+            route?.endpoint.authority ?? connection.socks5,
+          );
+          // The chokepoint that makes the invariant unavoidable: not every
+          // consumer goes through our socket connector — BDK and LWK open
+          // their own — so refusing here is the only check they all share.
+          if (_isUnroutableOnion(routed)) {
+            throw OnionServerWithoutTorException(routed.url);
+          }
+          return await operation(routed);
+        } finally {
+          await route?.close();
+        }
+      },
+      // An unroutable onion server is skipped, not fatal: the rest of the
+      // active set may still be reachable. Callers narrowing `isTransient` to
+      // their own error type must not turn that into a hard stop.
+      isTransient: isTransient == null
+          ? null
+          : (error) =>
+                error is OnionServerWithoutTorException || isTransient(error),
     );
   }
+
+  static bool _isUnroutableOnion(ElectrumConnection connection) =>
+      ElectrumServerUrl(connection.url).isOnion &&
+      (connection.socks5?.isEmpty ?? true);
 }

lib/core/electrum/adapters/electrum_tor_session_adapter.dart

@@ -0,0 +1,35 @@
+import 'dart:io';
+
+import 'package:bb_mobile/core/electrum/domain/ports/electrum_tor_session_port.dart';
+import 'package:bb_mobile/core/electrum/domain/value_objects/electrum_server_network.dart';
+import 'package:bb_mobile/core/electrum/domain/value_objects/electrum_server_url.dart';
+import 'package:bull_tor/tor.dart';
+
+final class ElectrumTorSessionAdapter implements ElectrumTorSessionPort {
+  final Tor Function() _tor;
+
+  const ElectrumTorSessionAdapter(this._tor);
+
+  @override
+  Future<ElectrumTorRoute?> open({
+    required ElectrumServerNetwork network,
+    required String serverUrl,
+    required bool externalProxyEnabled,
+    required int externalProxyPort,
+  }) async {
+    if (network.isLiquid || !ElectrumServerUrl(serverUrl).isOnion) return null;
+
+    if (externalProxyEnabled) {
+      return ElectrumTorRoute(
+        TorProxyEndpoint(
+          host: InternetAddress.loopbackIPv4.address,
+          port: externalProxyPort,
+        ),
+        () async {},
+      );
+    }
+
+    final session = await _tor().embedded.sessions.open();
+    return ElectrumTorRoute(session.endpoint, session.close);
+  }
+}

lib/core/electrum/adapters/server_status_adapter.dart

@@ -1,14 +1,17 @@
-import 'dart:async';
 import 'dart:convert';
-import 'dart:io';
 
+import 'package:bb_mobile/core/electrum/data/electrum_socket_connector.dart';
 import 'package:bb_mobile/core/electrum/domain/ports/server_status_port.dart';
 import 'package:bb_mobile/core/electrum/domain/value_objects/electrum_server_network.dart';
 import 'package:bb_mobile/core/electrum/domain/value_objects/electrum_server_status.dart';
+import 'package:bb_mobile/core/electrum/domain/value_objects/electrum_server_url.dart';
 import 'package:bb_mobile/core/utils/logger.dart';
+import 'package:bull_tor/tor.dart';
 
 class ServerStatusAdapter implements ServerStatusPort {
-  const ServerStatusAdapter();
+  final ElectrumSocketConnector _socketConnector;
+
+  const ServerStatusAdapter(this._socketConnector);
 
   /// Bitcoin pizza day — first real-world BTC purchase, May 22 2010.
   static const _bitcoinMainnetProbeTxid =
@@ -22,8 +25,7 @@ class ServerStatusAdapter implements ServerStatusPort {
   Future<ElectrumServerStatus> checkSocket({
     required String url,
     int? timeout,
-    bool useTorProxy = false,
-    int torProxyPort = 9050,
+    TorProxyEndpoint? proxyEndpoint,
   }) async {
     try {
       if (url.isEmpty) return ElectrumServerStatus.unknown;
@@ -33,23 +35,18 @@ class ServerStatusAdapter implements ServerStatusPort {
 
       final effectiveTimeout = _resolveTimeout(uri, timeout);
 
-      final isConnectable = useTorProxy
-          ? await _checkThroughSocks5(
-              uri: uri,
-              proxyPort: torProxyPort,
-              timeoutSeconds: effectiveTimeout,
-            )
-          : await _checkRawSocket(uri: uri, timeoutSeconds: effectiveTimeout);
-
-      return isConnectable
-          ? ElectrumServerStatus.online
-          : ElectrumServerStatus.offline;
-    } catch (e) {
-      log.severe(
-        message: 'Error checking server socket for $url',
-        error: e,
-        trace: StackTrace.current,
+      final socket = await _socketConnector.connect(
+        server: uri,
+        proxy: proxyEndpoint,
+        timeout: Duration(seconds: effectiveTimeout),
+        allowBadCertificate: true,
       );
+      socket.destroy();
+      return ElectrumServerStatus.online;
+    } catch (e) {
+      // A server we cannot reach is the expected answer of this check, not a
+      // fault: `severe` would report every offline server to Sentry.
+      log.warning('Socket check failed for $url - $e');
       return ElectrumServerStatus.offline;
     }
   }
@@ -60,6 +57,7 @@ class ServerStatusAdapter implements ServerStatusPort {
     required ElectrumServerNetwork network,
     required bool validateDomain,
     int? timeout,
+    TorProxyEndpoint? proxyEndpoint,
   }) async {
     try {
       if (url.isEmpty) return ElectrumServerStatus.unknown;
@@ -81,6 +79,7 @@ class ServerStatusAdapter implements ServerStatusPort {
         request: request,
         timeoutSeconds: effectiveTimeout,
         validateDomain: validateDomain,
+        proxyEndpoint: proxyEndpoint,
       );
 
       if (response.isEmpty) return ElectrumServerStatus.offline;
@@ -126,34 +125,30 @@ class ServerStatusAdapter implements ServerStatusPort {
   /// Onion addresses need longer timeouts due to Tor circuit building.
   /// Default: 5 seconds for clearnet, 30 seconds for .onion addresses.
   int _resolveTimeout(Uri uri, int? timeout) {
-    final isOnion = uri.host.endsWith('.onion');
+    final isOnion = ElectrumServerUrl.isOnionHost(uri.host);
     return timeout ?? (isOnion ? 30 : 5);
   }
 
-  /// Sends a JSON-RPC request and returns the raw response line.
-  /// [SecureSocket] extends [Socket], so both branches share the same
-  /// write/read logic after construction.
+  /// Sends a JSON-RPC request and returns the raw response line. Plain, TLS
+  /// and proxied sockets all arrive as a [Socket], so the read/write path
+  /// below is the same for every transport.
   Future<String> _sendRequest({
     required Uri uri,
     required String request,
     required int timeoutSeconds,
     required bool validateDomain,
+    TorProxyEndpoint? proxyEndpoint,
   }) async {
-    // A null onBadCertificate callback enforces strict CA validation. The
-    // flag comes from the user's electrum settings, so the probe accepts
-    // exactly the certificates the BDK/LWK sync would accept.
-    final Socket socket = uri.scheme == 'ssl'
-        ? await SecureSocket.connect(
-            uri.host,
-            uri.port,
-            timeout: Duration(seconds: timeoutSeconds),
-            onBadCertificate: validateDomain ? null : (_) => true,
-          )
-        : await Socket.connect(
-            uri.host,
-            uri.port,
-            timeout: Duration(seconds: timeoutSeconds),
-          );
+    // Certificates follow the user's `validateDomain` setting rather than
+    // being blanket-accepted: probing laxer than the sync reports a server
+    // online that the sync will then refuse, and probing stricter hides a
+    // server that would have worked.
+    final socket = await _socketConnector.connect(
+      server: uri,
+      proxy: proxyEndpoint,
+      timeout: Duration(seconds: timeoutSeconds),
+      allowBadCertificate: !validateDomain,
+    );
 
     try {
       socket.write(request);
@@ -167,127 +162,4 @@ class ServerStatusAdapter implements ServerStatusPort {
       socket.destroy();
     }
   }
-
-  Future<bool> _checkRawSocket({
-    required Uri uri,
-    required int timeoutSeconds,
-  }) async {
-    try {
-      final socket = await Socket.connect(
-        uri.host,
-        uri.port,
-        timeout: Duration(seconds: timeoutSeconds),
-      );
-      socket.destroy();
-      return true;
-    } on SocketException catch (e) {
-      log.warning('Socket connection failed for $uri - $e');
-      return false;
-    } catch (e) {
-      log.severe(
-        message: 'Unexpected error checking socket for $uri',
-        error: e,
-        trace: StackTrace.current,
-      );
-      return false;
-    }
-  }
-
-  /// Checks connectivity through a SOCKS5 proxy (used for Tor).
-  Future<bool> _checkThroughSocks5({
-    required Uri uri,
-    required int proxyPort,
-    required int timeoutSeconds,
-  }) async {
-    Socket? socket;
-    StreamSubscription<List<int>>? subscription;
-    try {
-      socket = await Socket.connect(
-        '127.0.0.1',
-        proxyPort,
-        timeout: Duration(seconds: timeoutSeconds),
-      );
-
-      final handshakeCompleter = Completer<List<int>>();
-      final connectCompleter = Completer<List<int>>();
-      var isHandshakeDone = false;
-
-      subscription = socket.listen(
-        (List<int> data) {
-          if (!isHandshakeDone) {
-            handshakeCompleter.complete(data);
-            isHandshakeDone = true;
-          } else {
-            connectCompleter.complete(data);
-          }
-        },
-        onError: (Object error) {
-          if (!handshakeCompleter.isCompleted) {
-            handshakeCompleter.completeError(error);
-          }
-          if (!connectCompleter.isCompleted) {
-            connectCompleter.completeError(error);
-          }
-        },
-        cancelOnError: true,
-      );
-
-      // SOCKS5 handshake: version 5, 1 auth method (no auth)
-      socket.add([0x05, 0x01, 0x00]);
-
-      final handshakeResponse = await handshakeCompleter.future.timeout(
-        Duration(seconds: timeoutSeconds),
-      );
-
-      if (handshakeResponse.length < 2 || handshakeResponse[0] != 0x05) {
-        log.warning('Invalid SOCKS5 handshake response');
-        return false;
-      }
-
-      socket.add(_buildSocks5ConnectRequest(uri));
-
-      final connectResponse = await connectCompleter.future.timeout(
-        Duration(seconds: timeoutSeconds),
-      );
-
-      if (connectResponse.length < 2 ||
-          connectResponse[0] != 0x05 ||
-          connectResponse[1] != 0x00) {
-        log.severe(
-          error: Exception('SOCKS5 connection failed'),
-          trace: StackTrace.current,
-        );
-        return false;
-      }
-
-      return true;
-    } catch (e) {
-      log.severe(
-        message: 'SOCKS5 connection check failed for $uri',
-        error: e,
-        trace: StackTrace.current,
-      );
-      return false;
-    } finally {
-      await subscription?.cancel();
-      socket?.destroy();
-    }
-  }
-
-  /// Builds a SOCKS5 CONNECT request.
-  /// Format: [version, command, reserved, address_type, address, port]
-  List<int> _buildSocks5ConnectRequest(Uri uri) {
-    final request = <int>[
-      0x05, // SOCKS version 5
-      0x01, // CONNECT command
-      0x00, // Reserved
-      0x03, // Address type: domain name
-    ];
-    final hostBytes = uri.host.codeUnits;
-    request.add(hostBytes.length);
-    request.addAll(hostBytes);
-    request.add((uri.port >> 8) & 0xFF);
-    request.add(uri.port & 0xFF);
-    return request;
-  }
 }