Hosted wallet connector on Flutter (headless)

import 'dart:async';
import 'dart:convert';
import 'dart:math';

import 'package:flutter/widgets.dart';
import 'package:url_launcher/url_launcher.dart';
import 'package:webview_flutter/webview_flutter.dart';

import 'app_config.dart';
import 'models.dart';

/// Runs the hosted Fireblocks connect logic (the Dynamic SDK) inside a HIDDEN
/// [WebViewWidget], so the app renders its own native wallet list and keeps
/// every bit of connection logic in the web layer.
///
/// For WalletConnect-protocol wallets (MetaMask, Rainbow, Trust, …) the
/// pairing is relay-based — the engine mints a URI, we open the wallet via
/// deeplink, the user approves, and the approval promise resolves over a
/// WebSocket — none of which needs a visible page. Wallets with no such path
/// come back as [ConnectFallbackRequired] so the caller opens the visible
/// [FireblocksConnect] flow.
///
/// ## Setup
///
/// 1. Wrap your home screen with [FireblocksEngineHost]:
///    ```dart
///    home: FireblocksEngineHost(child: ExampleScreen()),
///    ```
///
/// 2. Warm up at app launch (done for you in `main.dart`):
///    ```dart
///    FireblocksHeadlessConnect.shared.prewarm();
///    ```
///
/// 3. Connect a wallet:
///    ```dart
///    final result = await FireblocksHeadlessConnect.shared.connect(
///      walletKey: 'metamask',
///      chain: 'evm',
///    );
///    switch (result) {
///      case ConnectSuccess(:final wallet): ...
///      case ConnectFallbackRequired(:final reason): ...
///      case ConnectFailure(:final code, :final message): ...
///    }
///    ```
class FireblocksHeadlessConnect {
  FireblocksHeadlessConnect._();
  static final shared = FireblocksHeadlessConnect._();

  /// The no-UI engine page. `returnScheme` tells Phantom where to redirect
  /// after the user approves — must match your registered app URL scheme.
  /// Sourced from [AppConfig] so it can be overridden with `--dart-define`
  /// without touching source.
  String engineUrl = AppConfig.engineUrl;

  static const _startupTimeout = Duration(seconds: 20);
  static const _signTimeout = Duration(seconds: 60);

  /// Longer than [_signTimeout]: a send can involve two sequential wallet
  /// approvals (switch network, then send) rather than one, so 60s is too
  /// tight a budget to fail loud on before the user's had a fair chance to
  /// clear both prompts.
  static const _sendTimeout = Duration(seconds: 120);

  /// How long to wait for wallet approval AFTER a connect deeplink has
  /// opened successfully. [_startupTimeout] is cancelled at that point (see
  /// [_openDeeplink]) with nothing to replace it — so a wallet that never
  /// answers (backgrounded relay session that never resumes, wallet-side
  /// bug, user just closes the wallet app) used to leave [connect]'s
  /// `Future` pending forever, no error, no way out but killing the app.
  /// Generous on purpose: switching to a wallet app and back takes real
  /// human time, and a WalletConnect session proposal is normally good for
  /// 5 minutes anyway.
  static const _connectApprovalTimeout = Duration(minutes: 3);

  // Universal-link hosts that must be opened externally from inside WebView.
  // Kept identical to the Android/iOS native harnesses so wallet-open
  // behavior stays in parity across platforms.
  static const _walletHosts = {
    'phantom.app',
    'phantom.com',
    'link.metamask.io',
    'metamask.app.link',
    'link.trustwallet.com',
    'rnbwapp.com',
    'rainbow.me',
    'www.okx.com',
    'link.okx.com',
    'zerion.io',
  };

  // Never opened, whether reached via a nav-delegate interception or an
  // engine-supplied `deeplink` URL — script / data / local-file vectors, plus
  // the authority-bearing schemes (`intent:`, …) Android hands to
  // `startActivity(ACTION_VIEW)` with no further checks. Mirrors
  // `BLOCKED_REDIRECT_SCHEMES` in `src/config.ts` (#27) exactly — keep the
  // two lists in sync if either changes.
  static const _blockedSchemes = {
    'javascript',
    'data',
    'vbscript',
    'file',
    'blob',
    'about',
    'intent',
    'android-app',
    'market',
    'content',
    'chrome',
    'chrome-extension',
    'moz-extension',
    'ftp',
    'ws',
    'wss',
  };

  /// The engine's own origin (`scheme://host:port`). Inbound bridge messages
  /// are only trusted while the WebView's current page is on this origin —
  /// see [_handleMessage].
  late final Uri _trustedOrigin = Uri.parse(engineUrl);

  /// Updated on every navigation (including SPA `pushState`); starts `null`
  /// so no message is trusted before the first real navigation event lands.
  Uri? _currentOrigin;

  late final WebViewController _controller = _buildController();

  /// The hidden WebView widget. Mount via [FireblocksEngineHost] before calling
  /// any other methods.
  Widget get widget => WebViewWidget(controller: _controller);

  bool _ready = false;
  final _pendingReady = <VoidCallback>[];
  final _connectHandlers = <String, void Function(ConnectResult)>{};
  final _signHandlers = <String, void Function(SignResult)>{};
  final _signTxHandlers = <String, void Function(SignTxResult)>{};
  final _sendTxHandlers = <String, void Function(SendResult)>{};
  final _startupTimers = <String, Timer>{};
  final _signTimers = <String, Timer>{};
  final _signTxTimers = <String, Timer>{};
  final _secureRandom = Random.secure();

  List<HeadlessWallet> _wallets = [];

  void Function(List<HeadlessWallet>)? _onWallets;

  /// Called whenever the engine delivers (or re-delivers) the wallet
  /// catalogue. Setting this replays the last-known list immediately if the
  /// catalogue was already received, so a listener that subscribes late
  /// (e.g. a screen that mounts after the engine is already warm) doesn't
  /// spin forever waiting for a message that already happened.
  set onWallets(void Function(List<HeadlessWallet>)? callback) {
    _onWallets = callback;
    if (callback != null && _wallets.isNotEmpty) callback(_wallets);
  }

  void Function(List<HeadlessWallet>)? get onWallets => _onWallets;

  // MARK: – Public API

  /// Build and load the hidden WebView ahead of time so the first connect
  /// isn't slowed by SDK init + relay negotiation. Safe to call more than once.
  void prewarm() {
    _controller; // ignore: unnecessary_statements — triggers lazy init
  }

  /// Connect [walletKey] through the headless engine. Resolves once.
  ///
  /// [chain] besides the real chains ('evm', 'solana') accepts the synthetic
  /// picker value 'solana-testmode' (offered by the engine for Phantom):
  /// connects on Solana but binds the wallet session to devnet, for a
  /// Phantom app that's in Testnet Mode. Phantom validates every subsequent
  /// sign request against the session's network and rejects a mismatch
  /// outright — and there's no way to query which mode the app is in, so
  /// the user has to say.
  Future<ConnectResult> connect({
    required String walletKey,
    String? chain,
  }) {
    // A previous attempt is still in flight — reset to a fresh engine state so
    // the new wallet gets a clean slate (avoids stuck WC/Dynamic sessions).
    if (_connectHandlers.isNotEmpty) _resetEngine();
    final requestId = _generateRequestId('req');
    final completer = Completer<ConnectResult>();
    _connectHandlers[requestId] = completer.complete;
    _scheduleStartupTimeout(requestId);
    void work() => _drive(requestId: requestId, walletKey: walletKey, chain: chain);
    if (_ready) {
      work();
    } else {
      _pendingReady.add(work);
    }
    return completer.future;
  }

  /// Abort every in-flight connect (e.g. user backed out of the wallet list).
  /// Any pending [connect] call resolves with a cancelled failure so callers
  /// never await a [Future] that would otherwise never complete.
  void cancel() {
    _safeRunJavaScript("window.headlessConnect && window.headlessConnect.cancel('');");
    _drainConnectHandlers(const ConnectFailure(code: 'cancelled', message: 'Cancelled'));
  }

  /// Sign [message] with the currently-connected wallet. Resolves once.
  ///
  /// Requires the engine URL to point to a build that includes sign support.
  Future<SignResult> sign({required String message}) {
    final requestId = _generateRequestId('sign');
    final completer = Completer<SignResult>();
    _signHandlers[requestId] = completer.complete;
    _scheduleSignTimeout(requestId, _signHandlers);
    final params = json.encode({'requestId': requestId, 'message': message});
    _safeRunJavaScript('window.headlessConnect && window.headlessConnect.sign($params);');
    return completer.future;
  }

  /// Send a transaction with the currently-connected wallet — EVM, Solana,
  /// or Bitcoin. Resolves once. [transaction] is an opaque JSON string (or,
  /// for Solana, opaque base64); its shape depends on which chain the
  /// connected wallet is on — this method itself is chain-agnostic and just
  /// forwards it to the engine.
  ///
  /// The wallet signs AND broadcasts in one step: `eth_sendTransaction` for
  /// EVM (rather than `eth_signTransaction`, which isn't reliably implemented
  /// by mobile wallets — MetaMask rejects it outright), broadcast-after-sign
  /// for Solana, and the wallet's own `sendBitcoin` RPC for Bitcoin.
  ///
  /// [transaction] format (EVM): JSON string
  /// `{"to":"0x…","value":"0x0","data":"0x","chainId":"0x1"}` — `chainId` is
  /// required; the engine verifies it against the wallet's own active network
  /// before sending, using the Dynamic SDK's network-switching support. On a
  /// mismatch it asks the wallet to switch (adding the chain first via the
  /// SDK's own network config if the wallet does not have it configured) and only
  /// proceeds once the wallet confirms it actually moved, rather than
  /// silently sending on the wrong chain. See `SendFailure.error.code`:
  /// `chain_switch_unavailable` (wallet can't switch programmatically),
  /// `chain_not_configured` (chain isn't in this project's network config),
  /// `chain_switch_rejected` (wallet declined the switch/add prompt), or
  /// `chain_mismatch` (wallet claimed success without actually switching).
  ///
  /// [transaction] format (Solana): base64-encoded, pre-built
  /// `VersionedTransaction` (or legacy `Transaction`) bytes — this app is
  /// responsible for building it (a native SOL transfer vs. an SPL-token
  /// transfer for USDC are both just "whatever instructions are already in
  /// the bytes"); the engine only signs and submits. No chain-switch dance
  /// for Solana — there's no wallet-side "active network" to verify, the
  /// transaction already targets whichever cluster its recent blockhash
  /// came from.
  ///
  /// [transaction] format (Bitcoin): JSON string
  /// `{"recipientAddress":"bc1…","amountSats":"12345"}` — `amountSats` is
  /// the amount in satoshis as a decimal-digit string. The wallet's own
  /// `sendBitcoin` RPC signs AND broadcasts; there is no chain-switch step
  /// (Bitcoin has no equivalent of an EVM chainId to mismatch on).
  ///
  /// On success, [SendSuccess.txHash] is the on-chain transaction hash (EVM),
  /// signature (Solana, which IS the transaction's identifier), or
  /// transaction ID (Bitcoin) — it has already been submitted, there is
  /// nothing further to broadcast.
  Future<SendResult> sendTransaction({required String transaction}) {
    final requestId = _generateRequestId('sendtx');
    final completer = Completer<SendResult>();
    _sendTxHandlers[requestId] = completer.complete;
    _signTimers[requestId] = Timer(_sendTimeout, () {
      _signTimers.remove(requestId);
      _sendTxHandlers.remove(requestId)?.call(
            const SendFailure(SignError(
              code: 'timeout',
              message: 'Wallet did not respond in time — if you approved it, the transaction '
                  'may still have been submitted; check the explorer before retrying.',
            )),
          );
    });
    final params = json.encode({'requestId': requestId, 'transaction': transaction});
    // `sendTx` is a newer addition to the engine than everything else this
    // class calls — a deployment that predates it would otherwise leave this
    // request silently unanswered until the 60s timeout, indistinguishable
    // from a dead wallet. Self-report immediately instead, straight over the
    // same `walletNative` channel _handleMessage already listens on.
    _safeRunJavaScript(
      'if (window.headlessConnect && window.headlessConnect.sendTx) {'
      '  window.headlessConnect.sendTx($params);'
      '} else if (window.walletNative && window.walletNative.postMessage) {'
      '  window.walletNative.postMessage(JSON.stringify({'
      '    type: "sentTxFailed",'
      '    requestId: ${json.encode(requestId)},'
      '    code: "unsupported_engine",'
      '    message: "engine build predates sendTx — redeploy connect.dynamicauth.com"'
      '  }));'
      '}',
    );
    return completer.future;
  }

  /// Sign a transaction with the currently-connected wallet without
  /// broadcasting it. Resolves once.
  ///
  /// [transaction] format (EVM): JSON string
  /// `{"to":"0x…","value":"0x0","data":"0x","chainId":"0x1"}`.
  ///
  /// [transaction] format (Solana): base64-encoded, pre-built
  /// `VersionedTransaction` (or legacy `Transaction`) bytes.
  ///
  /// [transaction] format (Bitcoin): JSON string
  /// `{"unsignedPsbtBase64","allowedSighash","signature"}`. The result is a
  /// base64 signed PSBT; the caller must finalize and broadcast it.
  Future<SignTxResult> signTransaction({required String transaction}) {
    final requestId = _generateRequestId('signtx');
    final completer = Completer<SignTxResult>();
    _signTxHandlers[requestId] = completer.complete;
    _signTxTimers[requestId] = Timer(_signTimeout, () {
      _signTxTimers.remove(requestId);
      _signTxHandlers.remove(requestId)?.call(
            const SignTxFailure('timeout', 'Wallet did not respond in time'),
          );
    });
    final params =
        json.encode({'requestId': requestId, 'transaction': transaction});
    _safeRunJavaScript(
      'if (window.headlessConnect && window.headlessConnect.signTx) {'
      '  window.headlessConnect.signTx($params);'
      '} else if (window.walletNative && window.walletNative.postMessage) {'
      '  window.walletNative.postMessage(JSON.stringify({'
      '    type: "signTxFailed",'
      '    requestId: ${json.encode(requestId)},'
      '    code: "unsupported_engine",'
      '    message: "engine build predates signTx — redeploy connect.dynamicauth.com"'
      '  }));'
      '}',
    );
    return completer.future;
  }

  /// Tear down the session. Clears localStorage so stale Dynamic SDK state
  /// doesn't bleed into the next connect, then reloads the engine page.
  /// Any handlers still pending are drained with a cancelled result first.
  Future<void> disconnect() async {
    _drainConnectHandlers(const ConnectFailure(code: 'disconnected', message: 'Disconnected'));
    _drainSignHandlers();
    _ready = false;
    _pendingReady.clear();
    _wallets = [];
    _onWallets?.call(_wallets);
    // Clear storage before reload — equivalent to the iOS ephemeral WebView teardown.
    await _safeRunJavaScript('localStorage.clear(); sessionStorage.clear();');
    try {
      await _controller.reload();
    } catch (_) {
      // Page may not have finished its initial load yet — ignore, the
      // subsequent loadRequest inside _buildController already covers cold start.
    }
  }

  /// Forward a Phantom (or other redirect-wallet) return URL from the app's
  /// deep-link handler into the engine. Returns `true` if the URL was consumed.
  ///
  /// Call this from your app's `app_links` listener:
  /// ```dart
  /// AppLinks().uriLinkStream.listen((uri) {
  ///   FireblocksHeadlessConnect.shared.handleReturnUrl(uri);
  /// });
  /// ```
  bool handleReturnUrl(Uri uri) {
    if (uri.host.toLowerCase() != 'phantom-headless') return false;
    void deliver() {
      final js =
          'window.headlessConnect && window.headlessConnect.handleReturnURL(${json.encode(uri.toString())});';
      _safeRunJavaScript(js);
    }

    // On a cold start (app launched *by* this deep link) the engine page
    // hasn't finished loading yet — `window.headlessConnect` wouldn't exist
    // and the call would silently no-op. Queue it behind the same `ready`
    // gate `connect()` uses so it fires once the engine is actually up.
    if (_ready) {
      deliver();
    } else {
      _pendingReady.add(deliver);
    }
    return true;
  }

  // MARK: – Private

  WebViewController _buildController() {
    return WebViewController()
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      // `walletNative` matches the Android @JavascriptInterface name (and the
      // generic `window.walletNative.postMessage` fallback checked by the web
      // bridge) — no engine changes needed for Flutter.
      ..addJavaScriptChannel(
        'walletNative',
        onMessageReceived: (msg) => _handleMessage(msg.message),
      )
      ..setNavigationDelegate(NavigationDelegate(
        // Tracks the page actually loaded, for the origin check in
        // _handleMessage — `onNavigationRequest` alone tells us what was
        // *requested*, not what's live once redirects/SPA routing settle.
        onPageStarted: _updateCurrentOrigin,
        onUrlChange: (change) => _updateCurrentOrigin(change.url),
        onNavigationRequest: _onNavigationRequest,
      ))
      ..loadRequest(Uri.parse(engineUrl));
  }

  void _updateCurrentOrigin(String? url) {
    _currentOrigin = url == null ? null : Uri.tryParse(url);
  }

  /// Deny-by-default, including subframes — mirrors the bridge fix in PR #26
  /// ("Navigation is deny-by-default, including subframes"). Only the
  /// engine's own origin is ever allowed to load, in any frame; a
  /// cross-origin subframe (e.g. an XSS'd `<iframe>` on the engine's own
  /// page) is refused outright rather than handed to url_launcher, and a
  /// cross-origin *main*-frame navigation either hands off to an installed
  /// app (subject to [_blockedSchemes]) or is dropped — it never gets to
  /// load inside this privileged WebView and inherit the `walletNative`
  /// channel.
  ///
  /// Known gap: `webview_flutter`'s `onNavigationRequest` has historically
  /// not fired for every subframe load on Android (`shouldOverrideUrlLoading`
  /// skips some iframe navigations) — this closes the main-frame redirect
  /// path with certainty; treat subframe coverage as defense-in-depth, not
  /// a proven guarantee, until verified on-device per platform.
  NavigationDecision _onNavigationRequest(NavigationRequest req) {
    final uri = Uri.tryParse(req.url);
    if (uri == null) {
      debugPrint('[FireblocksHeadlessConnect] blocked unparsable navigation target');
      return NavigationDecision.prevent;
    }
    if (_isEngineOrigin(uri)) return NavigationDecision.navigate;
    if (!req.isMainFrame) {
      debugPrint('[FireblocksHeadlessConnect] blocked cross-origin subframe: ${req.url}');
      return NavigationDecision.prevent;
    }
    if (_isBlockedScheme(uri)) {
      debugPrint('[FireblocksHeadlessConnect] blocked scheme in navigation: ${req.url}');
      return NavigationDecision.prevent;
    }
    if (_shouldOpenExternally(uri)) _openExternally(uri);
    return NavigationDecision.prevent;
  }

  bool _isEngineOrigin(Uri uri) =>
      uri.scheme.toLowerCase() == _trustedOrigin.scheme.toLowerCase() &&
      uri.host.toLowerCase() == _trustedOrigin.host.toLowerCase() &&
      _effectivePort(uri) == _effectivePort(_trustedOrigin);

  int _effectivePort(Uri uri) =>
      uri.hasPort ? uri.port : (uri.scheme.toLowerCase() == 'https' ? 443 : 80);

  /// Never-allowed schemes — see [_blockedSchemes]'s doc comment.
  bool _isBlockedScheme(Uri uri) => _blockedSchemes.contains(uri.scheme.toLowerCase());

  bool _shouldOpenExternally(Uri uri) {
    final scheme = uri.scheme.toLowerCase();
    if (scheme != 'http' && scheme != 'https') return true; // custom schemes (fbapp://, metamask://)
    final host = uri.host.toLowerCase();
    return _walletHosts.any((h) => host == h || host.endsWith('.$h'));
  }

  /// Cryptographically-random per-call request id — deliberately not a
  /// sequential counter. A guessable id lets whatever's currently loaded in
  /// the WebView (attacker-controlled content, if the origin/navigation
  /// checks above were ever bypassed) forge a reply that completes a
  /// *different* pending request. Mirrors the per-connect UUIDs PR #26 added
  /// to the iOS/Android bridges; implemented with `dart:math`'s
  /// `Random.secure()` rather than a `uuid` package dependency.
  String _generateRequestId(String prefix) {
    final bytes = List<int>.generate(16, (_) => _secureRandom.nextInt(256));
    final hex = bytes.map((b) => b.toRadixString(16).padLeft(2, '0')).join();
    return '$prefix-$hex';
  }

  void _drive({required String requestId, required String walletKey, String? chain}) {
    final params = <String, dynamic>{'requestId': requestId, 'walletKey': walletKey};
    if (chain != null) params['chain'] = chain;
    _safeRunJavaScript(
      'window.headlessConnect && window.headlessConnect.connect(${json.encode(params)});',
    );
  }

  void _resetEngine() {
    _drainConnectHandlers(const ConnectFailure(code: 'reset', message: 'Superseded by a new connect request'));
    _ready = false;
    _pendingReady.clear();
    try {
      _controller.reload();
    } catch (_) {
      // Ignore — next connect() will retry once the reload settles.
    }
  }

  /// Every inbound bridge message is checked against the engine's own origin
  /// before being trusted — mirrors PR #26 ("Origin-check every inbound
  /// message against the engine URL; drop anything else"). `webview_flutter`
  /// injects the `walletNative` channel into every frame on the page, and
  /// doesn't expose which frame a given message came from, so this checks
  /// the *page* (via [_currentOrigin], updated by the navigation delegate)
  /// rather than the sender — the deny-by-default nav delegate in
  /// [_onNavigationRequest] is what stops a cross-origin frame from loading
  /// in the first place; this is the second layer, not a substitute for it.
  void _handleMessage(String jsonStr) {
    final origin = _currentOrigin;
    if (origin == null || !_isEngineOrigin(origin)) {
      debugPrint('[FireblocksHeadlessConnect] dropped bridge message from untrusted origin: $origin');
      return;
    }

    final Map<String, dynamic> obj;
    try {
      obj = json.decode(jsonStr) as Map<String, dynamic>;
    } catch (_) {
      return;
    }

    switch (obj['type'] as String?) {
      case 'ready':
        _ready = true;
        final work = List<VoidCallback>.of(_pendingReady);
        _pendingReady.clear();
        for (final fn in work) {
          fn();
        }

      case 'wallets':
        final raw = obj['wallets'];
        if (raw is List) {
          _wallets = raw.whereType<Map<String, dynamic>>().map(HeadlessWallet.fromJson).toList();
          _onWallets?.call(_wallets);
          // Which chains the engine is actually offering per wallet is
          // otherwise invisible from the device, and it's the first thing you
          // need when a wallet+chain combination misbehaves (a Phantom "EVM"
          // entry that no connection path backed went unnoticed exactly
          // because of this blind spot).
          for (final w in _wallets) {
            debugPrint('[FireblocksHeadlessConnect] wallet ${w.key}: '
                'chains=${w.chains} mode=${w.mode}');
          }
        }

      case 'deeplink':
        // Engine produced a WalletConnect / MetaMask URI — open the wallet.
        _openDeeplink(obj['requestId'] as String?, obj['url'] as String?);

      case 'openWallet':
        // A WalletConnect sign/send request is waiting — wake the wallet app
        // so its approval prompt surfaces (the request itself already went
        // over the relay; without this it sits invisibly until the user
        // opens the wallet by hand). requestId here is a sign/send id, not a
        // connect attempt — pass null so no connect bookkeeping is touched.
        _openDeeplink(null, obj['url'] as String?);

      case 'opening':
        // Wallet being opened via WebView navigation (Phantom redirect protocol).
        _cancelStartupTimer(obj['requestId'] as String?);

      case 'connected':
        final address = obj['address'] as String?;
        // A `connected` message with no address used to succeed with `''`
        // silently — Finding 19 in the PR #26 stack. Fail loud instead: an
        // engine bug (or a message that slipped past the origin check above)
        // should never read to the caller as "the user connected wallet ''".
        _finishConnect(
          obj['requestId'] as String?,
          (address == null || address.isEmpty)
              ? const ConnectFailure(
                  code: 'malformed_result',
                  message: 'Engine sent connected with no address')
              : ConnectSuccess(WalletConnection(
                  address: address,
                  chain: obj['chain'] as String? ?? '',
                  network: obj['network'] as String?,
                  walletName: obj['walletName'] as String? ?? '',
                  walletImage: obj['walletImage'] as String? ?? '',
                )),
        );

      case 'fallback':
        _finishConnect(
          obj['requestId'] as String?,
          ConnectFallbackRequired(obj['reason'] as String? ?? ''),
        );

      case 'error':
        _finishConnect(
          obj['requestId'] as String?,
          ConnectFailure(
            code: obj['code'] as String? ?? 'unknown',
            message: obj['message'] as String? ?? '',
          ),
        );

      case 'signed':
        _finishSign(obj['requestId'] as String?, SignSuccess(obj['signature'] as String? ?? ''));

      case 'signFailed':
        _finishSign(
          obj['requestId'] as String?,
          SignFailure(SignError(
            code: obj['code'] as String? ?? 'unknown',
            message: obj['message'] as String? ?? '',
          )),
        );

      case 'signedTx':
        _finishSignTx(
          obj['requestId'] as String?,
          SignTxSuccess(
            obj['signedTransaction'] as String? ?? '',
            obj['chain'] as String? ?? '',
          ),
        );

      case 'signTxFailed':
        _finishSignTx(
          obj['requestId'] as String?,
          SignTxFailure(
            obj['code'] as String? ?? 'unknown',
            obj['message'] as String? ?? '',
          ),
        );

      case 'sentTx':
        _finishSendTx(
          obj['requestId'] as String?,
          SendSuccess(obj['txHash'] as String? ?? '', chain: obj['chain'] as String? ?? ''),
        );

      case 'sentTxFailed':
        _finishSendTx(
          obj['requestId'] as String?,
          SendFailure(SignError(
            code: obj['code'] as String? ?? 'unknown',
            message: obj['message'] as String? ?? '',
          )),
        );

      case 'event':
        // The engine's diagnostic timeline (wallet_selected, deeplink_opened,
        // fallback, connected, wallet_action_requested, error …). Logged rather
        // than dropped: the resolved chain and the exact fallback reason only
        // exist here, and without them a failed connect looks identical from
        // the device whether it never found a path, opened the wrong app, or
        // was rejected in the wallet. Swap the debugPrint for an analytics
        // hook if you want these off-device.
        debugPrint('[FireblocksHeadlessConnect] event ${obj['event']} '
            '${obj['requestId'] ?? ''} ${obj['data'] ?? ''}');

    }
  }

  /// Attempt to open a wallet deeplink produced by the engine. On success the
  /// startup timer is REPLACED with the longer [_connectApprovalTimeout]
  /// (the user is now away in their wallet app, approving) — not just
  /// cancelled outright, or a wallet that never answers back would leave
  /// [connect]'s `Future` pending forever (see that constant's doc comment).
  /// On failure the engine is told immediately via `onDeeplinkFailed` so it
  /// can fall back to the visible flow rather than waiting out the full
  /// startup timeout — the startup timer itself is left running as a backstop
  /// in case the engine doesn't respond to that call.
  Future<void> _openDeeplink(String? requestId, String? url) async {
    if (url == null) return;
    final uri = Uri.tryParse(url);
    if (uri == null) return;
    // Belt-and-braces: this URL comes from the engine, which has already
    // passed the origin check by the time this fires, but native enforces
    // the scheme block-list on every hand-off to the OS regardless of
    // source — see [_blockedSchemes]'s doc comment.
    if (_isBlockedScheme(uri)) {
      debugPrint('[FireblocksHeadlessConnect] blocked scheme in deeplink: $url');
      return;
    }
    var opened = false;
    try {
      opened = await launchUrl(uri, mode: LaunchMode.externalApplication);
    } catch (_) {
      opened = false;
    }
    if (opened) {
      // requestId is null for a sign/send wake-up (see the 'openWallet' case
      // above) — nothing to reschedule there, sign/send have their own
      // timers already running.
      if (requestId != null) {
        _scheduleConnectApprovalTimeout(requestId);
      } else {
        _cancelStartupTimer(requestId);
      }
    } else if (requestId != null) {
      _safeRunJavaScript(
        'window.headlessConnect && window.headlessConnect.onDeeplinkFailed && '
        'window.headlessConnect.onDeeplinkFailed(${json.encode(requestId)});',
      );
    }
  }

  Future<void> _openExternally(Uri uri) async {
    try {
      await launchUrl(uri, mode: LaunchMode.externalApplication);
    } catch (_) {
      // No app to handle it — nothing to recover to from a bare navigation
      // interception (there's no requestId here), matching Android's stance.
    }
  }

  void _finishConnect(String? requestId, ConnectResult result) {
    if (requestId == null) return;
    final handler = _connectHandlers.remove(requestId);
    _cancelStartupTimer(requestId);
    if (handler == null) {
      debugPrint('[FireblocksHeadlessConnect] dropped connect reply for unknown requestId: $requestId');
      return;
    }
    handler(result);
  }

  void _finishSign(String? requestId, SignResult result) {
    if (requestId == null) return;
    _signTimers.remove(requestId)?.cancel();
    final handler = _signHandlers.remove(requestId);
    if (handler == null) {
      debugPrint('[FireblocksHeadlessConnect] dropped sign reply for unknown requestId: $requestId');
      return;
    }
    handler(result);
  }

  void _finishSignTx(String? requestId, SignTxResult result) {
    if (requestId == null) return;
    _signTxTimers.remove(requestId)?.cancel();
    final handler = _signTxHandlers.remove(requestId);
    if (handler == null) {
      debugPrint('[FireblocksHeadlessConnect] dropped signTx reply for unknown requestId: $requestId');
      return;
    }
    handler(result);
  }

  void _finishSendTx(String? requestId, SendResult result) {
    if (requestId == null) return;
    _signTimers.remove(requestId)?.cancel();
    final handler = _sendTxHandlers.remove(requestId);
    if (handler == null) {
      debugPrint('[FireblocksHeadlessConnect] dropped sendTx reply for unknown requestId: $requestId');
      return;
    }
    handler(result);
  }

  void _drainConnectHandlers(ConnectResult result) {
    final handlers = Map<String, void Function(ConnectResult)>.of(_connectHandlers);
    _connectHandlers.clear();
    for (final id in handlers.keys) {
      _cancelStartupTimer(id);
    }
    for (final handler in handlers.values) {
      handler(result);
    }
  }

  void _drainSignHandlers() {
    for (final timer in _signTimers.values) {
      timer.cancel();
    }
    _signTimers.clear();
    const result = SignFailure(SignError(code: 'disconnected', message: 'Disconnected'));
    final signHandlers = Map<String, void Function(SignResult)>.of(_signHandlers);
    _signHandlers.clear();
    for (final handler in signHandlers.values) {
      handler(result);
    }
    for (final timer in _signTxTimers.values) {
      timer.cancel();
    }
    _signTxTimers.clear();
    const signTxResult = SignTxFailure('disconnected', 'Disconnected');
    final signTxHandlers =
        Map<String, void Function(SignTxResult)>.of(_signTxHandlers);
    _signTxHandlers.clear();
    for (final handler in signTxHandlers.values) {
      handler(signTxResult);
    }
    const sendResult = SendFailure(SignError(code: 'disconnected', message: 'Disconnected'));
    final sendHandlers = Map<String, void Function(SendResult)>.of(_sendTxHandlers);
    _sendTxHandlers.clear();
    for (final handler in sendHandlers.values) {
      handler(sendResult);
    }
  }

  void _scheduleStartupTimeout(String requestId) {
    _startupTimers[requestId]?.cancel();
    _startupTimers[requestId] = Timer(_startupTimeout, () {
      _startupTimers.remove(requestId);
      _finishConnect(requestId, const ConnectFallbackRequired('headless startup timeout'));
    });
  }

  void _cancelStartupTimer(String? requestId) {
    if (requestId == null) return;
    _startupTimers.remove(requestId)?.cancel();
  }

  /// Reuses [_startupTimers] (same map, same cancel-on-`_finishConnect` path)
  /// with [_connectApprovalTimeout]'s longer budget — see that constant's
  /// doc comment for why this exists at all.
  void _scheduleConnectApprovalTimeout(String requestId) {
    _startupTimers[requestId]?.cancel();
    _startupTimers[requestId] = Timer(_connectApprovalTimeout, () {
      _startupTimers.remove(requestId);
      _finishConnect(
        requestId,
        const ConnectFailure(code: 'timeout', message: 'Wallet did not respond in time'),
      );
    });
  }

  void _scheduleSignTimeout(
    String requestId,
    Map<String, void Function(SignResult)> handlers,
  ) {
    _signTimers[requestId] = Timer(_signTimeout, () {
      _signTimers.remove(requestId);
      handlers.remove(requestId)?.call(
            const SignFailure(SignError(code: 'timeout', message: 'Wallet did not respond in time')),
          );
    });
  }

  Future<void> _safeRunJavaScript(String js) async {
    try {
      await _controller.runJavaScript(js);
    } catch (_) {
      // WebView not attached / navigation in progress — safe to drop; the
      // caller has already scheduled its own timeout as a backstop.
    }
  }
}

/// Mounts the hidden engine WebView while rendering [child].
///
/// Place near the root of your app so the engine is always alive regardless of
/// which screen is active:
///
/// ```dart
/// MaterialApp(
///   home: FireblocksEngineHost(child: ExampleScreen()),
/// )
/// ```
class FireblocksEngineHost extends StatelessWidget {
  final Widget child;
  const FireblocksEngineHost({super.key, required this.child});

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        child,
        // Hidden 1×1 — positioned off-screen to avoid intercepting touch events
        // while staying in the tree so Flutter doesn't throttle / suspend it.
        Positioned(
          left: -1,
          top: -1,
          width: 1,
          height: 1,
          child: FireblocksHeadlessConnect.shared.widget,
        ),
      ],
    );
  }
}

/// A wallet entry in the native list, delivered live by the engine.
/// [mode] is `"headless"` (silent connection) or `"fallback"` (visible flow needed).
class HeadlessWallet {
  final String key;
  final String name;
  final String icon;
  final List<String> chains;
  final String mode;
  final bool featured;

  const HeadlessWallet({
    required this.key,
    required this.name,
    required this.icon,
    required this.chains,
    required this.mode,
    required this.featured,
  });

  factory HeadlessWallet.fromJson(Map<String, dynamic> json) => HeadlessWallet(
        key: json['key'] as String? ?? '',
        name: json['name'] as String? ?? '',
        icon: json['icon'] as String? ?? '',
        chains: (json['chains'] as List<dynamic>?)?.cast<String>() ?? const [],
        mode: json['mode'] as String? ?? 'fallback',
        featured: json['featured'] as bool? ?? false,
      );

  bool get isMultiChain => chains.length > 1;
  bool get isHeadless => mode == 'headless';
}

/// A successfully connected wallet account.
class WalletConnection {
  final String address;
  final String chain;
  final String walletName;
  final String walletImage;

  /// `true` for wallets connected through the hidden WebView engine;
  /// `false` for the visible ASWebAuth / Chrome Custom Tabs fallback flow.
  final bool connectedHeadlessly;

  /// The [HeadlessWallet.key] that produced this connection, e.g. `"metamask"`.
  ///
  /// NOT part of the engine's wire protocol (the `connected` bridge message
  /// carries no wallet key) — set locally by the caller that made the
  /// `connect()` call, so the UI can offer a one-tap "Reconnect" to the same
  /// wallet on a later app launch. `null` when unknown.
  final String? walletKey;

  const WalletConnection({
    required this.address,
    required this.chain,
    required this.walletName,
    required this.walletImage,
    this.connectedHeadlessly = true,
    this.walletKey,
  });

  WalletConnection copyWith({String? walletKey}) => WalletConnection(
        address: address,
        chain: chain,
        walletName: walletName,
        walletImage: walletImage,
        connectedHeadlessly: connectedHeadlessly,
        walletKey: walletKey ?? this.walletKey,
      );
}

/// Describes a failed sign operation.
class SignError {
  final String code;
  final String message;

  const SignError({required this.code, required this.message});

  @override
  String toString() => '[$code] $message';
}

// ── Connect result ───────────────────────────────────────────────────────────

sealed class ConnectResult {
  const ConnectResult();
}

final class ConnectSuccess extends ConnectResult {
  final WalletConnection wallet;
  const ConnectSuccess(this.wallet);
}

/// The wallet can't go headless; caller should open [FireblocksConnect.connect].
final class ConnectFallbackRequired extends ConnectResult {
  final String reason;
  const ConnectFallbackRequired(this.reason);
}

final class ConnectFailure extends ConnectResult {
  final String code;
  final String message;
  const ConnectFailure({required this.code, required this.message});
}

// ── Sign result ──────────────────────────────────────────────────────────────

/// Result of [FireblocksHeadlessConnect.sign].
sealed class SignResult {
  const SignResult();
}

final class SignSuccess extends SignResult {
  /// Signed message: hex signature string.
  /// Signed message (Bitcoin): base64. Signed tx (EVM): RLP-encoded hex.
  /// Signed tx (Solana): base64.
  final String value;
  const SignSuccess(this.value);
}

final class SignFailure extends SignResult {
  final SignError error;
  const SignFailure(this.error);
}

// ── Sign transaction result ──────────────────────────────────────────────────

/// Result of [FireblocksHeadlessConnect.signTransaction]. This operation signs
/// without broadcasting; a Bitcoin success contains a signed PSBT that the
/// caller finalizes and broadcasts.
sealed class SignTxResult {
  const SignTxResult();
}

final class SignTxSuccess extends SignTxResult {
  /// Signed transaction: RLP-encoded hex (EVM), base64 (Solana), or a base64
  /// signed PSBT (Bitcoin).
  final String signedTransaction;

  /// "evm", "solana", or "bitcoin".
  final String chain;

  const SignTxSuccess(this.signedTransaction, this.chain);
}

final class SignTxFailure extends SignTxResult {
  final String code;
  final String message;

  const SignTxFailure(this.code, this.message);
}

// ── Send result ──────────────────────────────────────────────────────────────

/// Result of [FireblocksHeadlessConnect.sendTransaction] (headless, EVM,
/// Solana, or Bitcoin). Unlike [SignResult] (sign-only, nothing broadcast),
/// this wallet call signs AND broadcasts the transaction; a [SendSuccess]
/// means it's already on-chain.
sealed class SendResult {
  const SendResult();
}

final class SendSuccess extends SendResult {
  /// The on-chain transaction hash (EVM), signature (Solana, which IS the
  /// transaction's identifier), or transaction ID (Bitcoin) — already
  /// submitted, not a raw signed tx.
  final String txHash;

  /// "evm", "solana", or "bitcoin". Empty for the visible-flow path, which is
  /// EVM-only and doesn't echo a chain back.
  final String chain;

  const SendSuccess(this.txHash, {this.chain = ''});
}

final class SendFailure extends SendResult {
  final SignError error;
  const SendFailure(this.error);
}

/// Central configuration for the app's URL scheme and hosted engine URLs.
///
/// Kept in one place (rather than duplicated string literals across
/// `main.dart` / `example_screen.dart` / native manifests) because the
/// scheme in particular must match exactly in three other places:
///
///  - `ios/Runner/Info.plist`               → `CFBundleURLSchemes`
///  - `android/app/src/main/AndroidManifest.xml` → `<data android:scheme="…">`
///  - the hosted engine's `returnScheme` query param (baked into [engineUrl])
///
/// Override any of these at build/run time without touching source:
/// ```bash
/// flutter run \
///   --dart-define=WALLET_SCHEME=myapp \
///   --dart-define=ENGINE_BASE_URL=https://connect.dynamicauth.com/headless.html \
///   --dart-define=FLOW_URL=https://connect.dynamicauth.com/ \
///   --dart-define=DYNAMIC_ENVIRONMENT_ID=b1e3aca9-0646-411a-b4ab-c31ce49935b3
/// ```
abstract final class AppConfig {
  /// The app's registered custom URL scheme. Must be a valid RFC 3986 scheme:
  /// lowercase letters/digits/`+`/`-`/`.` only, starting with a letter — no
  /// underscores (required by `flutter_web_auth_2`'s `callbackUrlScheme`).
  static const scheme = String.fromEnvironment('WALLET_SCHEME', defaultValue: 'fbapp');

  static const _engineBaseUrl = String.fromEnvironment(
    'ENGINE_BASE_URL',
    defaultValue: 'https://connect.dynamicauth.com/headless.html',
  );

  /// The visible, hosted connect page used by the ASWebAuth / Chrome Custom
  /// Tabs fallback flow ([FireblocksConnect]).
  static const flowUrl = String.fromEnvironment(
    'FLOW_URL',
    defaultValue: 'https://connect.dynamicauth.com/',
  );

  /// Which Dynamic environment the hosted pages should use, sent as
  /// `?environmentId=<uuid>` on both [engineUrl] and the visible flow URL.
  ///
  /// Empty (the default) means "don't send the param", and the hosted page falls
  /// back to the environment it was built with. The page ignores anything that
  /// isn't a UUID.
  static const environmentId = String.fromEnvironment('DYNAMIC_ENVIRONMENT_ID');

  /// The no-UI engine page loaded into the hidden WebView. `returnScheme`
  /// tells Phantom (and other redirect-protocol wallets) where to send the
  /// user back after they approve.
  static String get engineUrl => withEnvironmentId(
        Uri.parse(_engineBaseUrl).replace(queryParameters: {
          ...Uri.parse(_engineBaseUrl).queryParameters,
          'returnScheme': scheme,
        }).toString(),
      );

  /// Add `environmentId` to [url] when one is configured, preserving any params
  /// already on it. A no-op when [environmentId] is empty.
  static String withEnvironmentId(String url) {
    if (environmentId.isEmpty) return url;
    final base = Uri.parse(url);
    return base.replace(queryParameters: {
      ...base.queryParameters,
      'environmentId': environmentId,
    }).toString();
  }
}

import 'dart:async';
import 'dart:math';

import 'package:flutter/foundation.dart';
import 'package:url_launcher/url_launcher.dart';

import 'fireblocks_connect.dart' show FireblocksConnectCancelled, FireblocksConnectError;
import 'models.dart';

/// Drives the hosted visible flow **inside a wallet's own in-app browser**.
///
/// ## Why this exists (and why it isn't [FireblocksConnect])
///
/// [FireblocksConnect] opens the hosted page in the SYSTEM browser
/// (`flutter_web_auth_2` → Chrome Custom Tabs / ASWebAuthenticationSession).
/// That works for any wallet reachable by WalletConnect, a deeplink, or an SDK
/// (Base Account). It cannot work for a wallet whose only mobile surface for a
/// given chain is the provider it injects into its OWN browser — because that
/// provider simply isn't there in the system browser.
///
/// Phantom on EVM is exactly that case, and it's why "Phantom EVM" never
/// worked here: no `phantom*` wallet-book entry has a WalletConnect block, and
/// `phantomevm` carries no mobile deeplink at all — its only surface is
/// `window.phantom.ethereum`, injected inside Phantom's in-app browser (see
/// `classifyChain`'s doc comment in `src/redirect.ts`). So the page has to be
/// opened THERE, and the result handed back to this app over its custom
/// scheme.
///
/// ## Mechanics
///
/// 1. Build the hosted-page URL (`?wallet=…&chain=evm`, or an
///    `?intent=signMessage|sendTx` variant) with
///    `redirect_uri=<scheme>://[callbackHost]` and a fresh nonce.
/// 2. Wrap it in the wallet's in-app-browser template (`{{encodedDappURI}}`,
///    replaced everywhere — Phantom's uses it twice) and hand it to the OS.
///    The template comes from the engine's wallet catalogue
///    ([HeadlessWallet.inAppBrowserUrl]), i.e. from Dynamic's wallet book —
///    never hard-coded here.
/// 3. The wallet opens its browser on the page, the user connects/signs with
///    the injected provider, and the page redirects to
///    `<scheme>://[callbackHost]?…`.
/// 4. That link arrives through `app_links` (NOT through `flutter_web_auth_2`,
///    which only intercepts callbacks inside its own session — this is why the
///    callback host must differ from the visible flow's `wallet-callback`, and
///    why [handleReturnUrl] has to be wired up in `main.dart`).
///
/// ## Caveats worth knowing before you ship this
///
/// - The hand-off in step 2 is an `https` universal/app link. It reaches the
///   wallet only if the OS routes that domain to the wallet app: iOS honours
///   universal links from `UIApplication.open`, but on Android an unverified
///   app link can land in Chrome instead — where the wallet injects nothing
///   and the page correctly reports that the wallet has no path for this
///   chain. "No connection path" seen in a browser that ISN'T the wallet means
///   the hand-off went to the wrong app, not that the wallet can't do it.
/// - Whether a wallet's browser honours a custom-scheme navigation is the
///   wallet's choice, not ours. The hosted page always ALSO renders a "Return
///   to the app" anchor for custom-scheme targets (a real tap is the reliable
///   path where a programmatic navigation is ignored), so the user has a way
///   back either way.
/// - Nothing here is silent: expect the wallet app to come to the foreground
///   with a web page in it, plus the wallet's own approval prompt.
abstract final class FireblocksWalletBrowser {
  /// Host of the callback URL this flow listens for — deliberately NOT
  /// `wallet-callback`, which `flutter_web_auth_2`'s `CallbackActivity` claims
  /// on Android for the system-browser flow. A link arriving from the wallet's
  /// app has no `flutter_web_auth_2` session to belong to, so it must be
  /// delivered as a plain app link and routed here instead.
  static const callbackHost = 'wallet-browser';

  /// How long to wait for the return link before giving up. The user is in
  /// another app for this whole window (connect, approve, come back), so this
  /// is generous by design; it exists so an abandoned flow can't leave a
  /// [Future] pending for the process lifetime.
  static const timeout = Duration(minutes: 5);

  static _Pending? _pending;

  /// Connect [walletKey] on [chain] inside the wallet's own browser.
  ///
  /// [walletBrowserUrl] — the wallet's in-app-browser template, from
  /// [HeadlessWallet.inAppBrowserUrl].
  /// [flowUrl] / [scheme] / [environmentId] — as [FireblocksConnect.connect].
  ///
  /// The returned [WalletConnection] carries [WalletConnection.walletBrowserUrl]
  /// so later sign/send calls can be routed back into the same browser — the
  /// connection lives with that injected provider and nowhere else.
  static Future<WalletConnection> connect({
    required String flowUrl,
    required String scheme,
    required String walletBrowserUrl,
    required String walletKey,
    String chain = 'evm',
    String environmentId = '',
  }) async {
    final callback = await _run(
      flowUrl: flowUrl,
      scheme: scheme,
      walletBrowserUrl: walletBrowserUrl,
      environmentId: environmentId,
      params: {'wallet': walletKey, 'chain': chain},
    );
    final address = callback.uri.queryParameters['address'] ?? '';
    if (address.isEmpty) {
      throw const FireblocksConnectError('No address in callback URL');
    }
    return WalletConnection(
      address: address,
      chain: callback.uri.queryParameters['chain'] ?? chain,
      walletName: callback.uri.queryParameters['walletName'] ?? '',
      walletImage: callback.uri.queryParameters['walletImage'] ?? '',
      connectedHeadlessly: false,
      walletKey: walletKey,
      walletBrowserUrl: walletBrowserUrl,
    );
  }

  /// Sign [message] with a wallet connected through [connect].
  ///
  /// [expectedAddress] is REQUIRED and checked by the page itself: the page
  /// connects again inside the wallet's browser before signing, and without
  /// this it would sign with whatever account happens to connect.
  static Future<SignResult> signMessage({
    required String flowUrl,
    required String scheme,
    required String walletBrowserUrl,
    required String walletKey,
    required String message,
    required String expectedAddress,
    String environmentId = '',
  }) async {
    final callback = await _run(
      flowUrl: flowUrl,
      scheme: scheme,
      walletBrowserUrl: walletBrowserUrl,
      environmentId: environmentId,
      params: {
        'intent': 'signMessage',
        'walletKey': walletKey,
        'message': message,
        'expectedAddress': expectedAddress,
      },
    );
    if (callback.uri.queryParameters['error'] == '1') {
      return SignFailure(SignError(
        code: callback.uri.queryParameters['code'] ?? 'unknown',
        message: callback.uri.queryParameters['message'] ?? '',
      ));
    }
    final signature = callback.uri.queryParameters['signature'] ?? '';
    if (signature.isEmpty) {
      throw const FireblocksConnectError('No signature in callback URL');
    }
    return SignSuccess(signature);
  }

  /// Send an EVM transaction with a wallet connected through [connect].
  ///
  /// [to] / [chainId] / [value] / [data] / [gasLimit] are `0x`-prefixed hex,
  /// same contract as [FireblocksConnect.sendTransaction]. The wallet signs
  /// AND broadcasts: a [SendSuccess] is already on-chain.
  static Future<SendResult> sendTransaction({
    required String flowUrl,
    required String scheme,
    required String walletBrowserUrl,
    required String walletKey,
    required String to,
    required String chainId,
    required String expectedAddress,
    String value = '0x0',
    String data = '0x',
    String? gasLimit,
    String environmentId = '',
  }) async {
    final callback = await _run(
      flowUrl: flowUrl,
      scheme: scheme,
      walletBrowserUrl: walletBrowserUrl,
      environmentId: environmentId,
      params: {
        'intent': 'sendTx',
        'walletKey': walletKey,
        'to': to,
        'value': value,
        'data': data,
        'chainId': chainId,
        if (gasLimit != null) 'gasLimit': gasLimit,
        'expectedAddress': expectedAddress,
      },
    );
    if (callback.uri.queryParameters['error'] == '1') {
      return SendFailure(SignError(
        code: callback.uri.queryParameters['code'] ?? 'unknown',
        message: callback.uri.queryParameters['message'] ?? '',
      ));
    }
    final txHash = callback.uri.queryParameters['txHash'] ?? '';
    if (txHash.isEmpty) {
      throw const FireblocksConnectError('No txHash in callback URL');
    }
    return SendSuccess(txHash, chain: 'evm');
  }

  /// Feed an inbound deep link to this flow. Returns `true` when the URL was
  /// this flow's callback (consumed, whether or not a request was waiting for
  /// it), so callers can chain handlers:
  ///
  /// ```dart
  /// if (FireblocksHeadlessConnect.shared.handleReturnUrl(uri)) return;
  /// FireblocksWalletBrowser.handleReturnUrl(uri);
  /// ```
  static bool handleReturnUrl(Uri uri) {
    if (uri.host.toLowerCase() != callbackHost) return false;
    final pending = _pending;
    if (pending == null) {
      debugPrint('[FireblocksWalletBrowser] callback with no request in flight: $uri');
      return true;
    }
    // Nonce mismatch is NOT completed as a failure: a stale callback (the
    // user re-opened an old page in the wallet's browser) must not resolve
    // the request that IS in flight. Drop it and keep waiting.
    if (uri.queryParameters['nonce'] != pending.nonce) {
      debugPrint('[FireblocksWalletBrowser] dropped callback with mismatched nonce');
      return true;
    }
    _pending = null;
    pending.timer.cancel();
    if (!pending.completer.isCompleted) {
      pending.completer.complete(_Callback(uri));
    }
    return true;
  }

  /// Abandon the in-flight request (e.g. the user navigated away in this app).
  /// Its [Future] completes with [FireblocksConnectCancelled].
  static void cancel() => _abandon(const FireblocksConnectCancelled());

  // MARK: – Private

  static Future<_Callback> _run({
    required String flowUrl,
    required String scheme,
    required String walletBrowserUrl,
    required String environmentId,
    required Map<String, String> params,
  }) async {
    // One request at a time — the callback carries no request id beyond its
    // nonce, and two overlapping flows in the same wallet browser would race
    // for the same return link.
    _abandon(const FireblocksConnectCancelled());

    final nonce = _randomHex(16);
    final base = Uri.parse(flowUrl);
    final pageUrl = base.replace(queryParameters: {
      ...base.queryParameters,
      ...params,
      'redirect_uri': '$scheme://$callbackHost',
      'nonce': nonce,
      // The page runs inside a wallet's WebView here — tell it so explicitly
      // rather than leaving it to user-agent guessing (see `getEnvInfo` in
      // `src/env.ts`): among other things this stops it offering a deeplink
      // connector that would try to bounce out of that browser.
      'embedded': '1',
      // Tells the page it's ALREADY inside walletKey's own browser (see
      // App.tsx's openedInsideWalletBrowser doc comment) — so if the
      // provider still isn't detected, it shows a clear message on THIS
      // load instead of re-offering the same in-app-browser link (which,
      // tapped from inside that browser, is a dead loop).
      'walletBrowser': '1',
      if (environmentId.isNotEmpty) 'environmentId': environmentId,
    }).toString();

    // Some templates (Phantom's) use the placeholder more than once — as both
    // the browse target and the `ref` — so replace every occurrence.
    final target = Uri.tryParse(
      walletBrowserUrl.replaceAll('{{encodedDappURI}}', Uri.encodeComponent(pageUrl)),
    );
    if (target == null) {
      throw FireblocksConnectError('Unusable in-app-browser URL: $walletBrowserUrl');
    }

    final completer = Completer<_Callback>();
    final timer = Timer(timeout, () => _abandon(const FireblocksConnectCancelled()));
    _pending = _Pending(nonce: nonce, completer: completer, timer: timer);

    var opened = false;
    try {
      opened = await launchUrl(target, mode: LaunchMode.externalApplication);
    } catch (_) {
      opened = false;
    }
    if (!opened) {
      _abandon(FireblocksConnectError(
        'Could not open the wallet app for $target — is it installed?',
      ));
    }
    return completer.future;
  }

  /// Fail/cancel the in-flight request, if any, with [error].
  static void _abandon(Exception error) {
    final pending = _pending;
    if (pending == null) return;
    _pending = null;
    pending.timer.cancel();
    if (!pending.completer.isCompleted) {
      pending.completer.completeError(error);
    }
  }

  static String _randomHex(int bytes) {
    final rng = Random.secure();
    return List.generate(bytes, (_) => rng.nextInt(256))
        .map((b) => b.toRadixString(16).padLeft(2, '0'))
        .join();
  }
}

class _Pending {
  final String nonce;
  final Completer<_Callback> completer;
  final Timer timer;
  const _Pending({required this.nonce, required this.completer, required this.timer});
}

class _Callback {
  final Uri uri;
  const _Callback(this.uri);
}