bhwi_async_transport/

lib.rs

//! Native discovery and I/O for asynchronous hardware-wallet sessions.
//!
//! [`NativeSource`] discovers device types enabled by Cargo features, using HID,
//! serial ports, native USB, and optional emulator probes. Compiled support does
//! not imply that a device is attached or accessible. The `webusb` backend uses
//! `nusb`, not the browser WebUSB API.
//!
//! Shared discovery types and [`Info`] are reexported from [`bhwi_async`].

use async_trait::async_trait;
use futures::future::join_all;

#[cfg(feature = "bitbox")]
use crate::bitbox::BitBoxDevice;
#[cfg(feature = "coldcard")]
use crate::coldcard::ColdcardDevice;
#[cfg(feature = "jade")]
use crate::jade::JadeDevice;
#[cfg(feature = "keepkey")]
use crate::keepkey::KeepKeyDevice;
#[cfg(feature = "ledger")]
use crate::ledger::LedgerDevice;
#[cfg(feature = "specter")]
use crate::specter::SpecterDevice;
#[cfg(feature = "trezor")]
use crate::trezor::TrezorDevice;

#[cfg(feature = "bitbox")]
pub mod bitbox;
#[cfg(feature = "coldcard")]
pub mod coldcard;
#[cfg(any(feature = "keepkey", feature = "trezor"))]
pub mod emulator;
pub mod error;
#[cfg(any(
    feature = "bitbox",
    feature = "coldcard",
    feature = "keepkey",
    feature = "ledger",
    feature = "trezor"
))]
pub mod hid;
#[cfg(feature = "jade")]
pub mod jade;
#[cfg(feature = "keepkey")]
pub mod keepkey;
#[cfg(feature = "ledger")]
pub mod ledger;
#[cfg(any(feature = "jade", feature = "specter"))]
mod serial;
#[cfg(feature = "specter")]
pub mod specter;
#[cfg(feature = "trezor")]
pub mod trezor;
#[cfg(target_os = "linux")]
pub mod udev;
#[cfg(any(feature = "keepkey", feature = "trezor"))]
pub mod webusb;

pub use bhwi_async::Info;
pub use bhwi_async::device::{
    Device, DeviceCandidate, DeviceManager, DeviceScan, DeviceSelector, DeviceSource, DeviceType,
    HostInteractionFactory, NoUsableDevice, PairingCodePrompt, ScanEntry, SelectError,
    SkippedDevice, can_sign_taproot, classify_error, is_user_cancelled, networks_string, no_device,
    reports_device_info,
};
pub use error::{NativeError, NativeResult};

/// A native device-discovery source with optional broad-scan exclusions.
///
/// The default scans all compiled device types. Exclusions apply only when
/// [`DeviceSelector::device_type`] is unset; explicitly naming a type still
/// selects it. Listing can probe emulators when requested by the selector.
/// If any candidates are found, listing ignores failures from other device
/// types; otherwise it returns the first discovery error, if any.
#[derive(Default)]
pub struct NativeSource {
    excluded: Vec<DeviceType>,
}

impl NativeSource {
    /// Creates a source that omits `excluded` types from broad discovery.
    pub fn excluding(excluded: impl IntoIterator<Item = DeviceType>) -> Self {
        Self {
            excluded: excluded.into_iter().collect(),
        }
    }

    /// Returns whether support for `device_type` was compiled into this build.
    ///
    /// This does not check for attached devices, permissions, or usable wallets.
    pub fn is_supported(device_type: DeviceType) -> bool {
        match device_type {
            DeviceType::BitBox02 => cfg!(feature = "bitbox"),
            DeviceType::Coldcard => cfg!(feature = "coldcard"),
            DeviceType::Jade => cfg!(feature = "jade"),
            DeviceType::KeepKey => cfg!(feature = "keepkey"),
            DeviceType::Ledger => cfg!(feature = "ledger"),
            DeviceType::Specter => cfg!(feature = "specter"),
            DeviceType::Trezor => cfg!(feature = "trezor"),
        }
    }

    fn walked(&self, selector: &DeviceSelector) -> Vec<DeviceType> {
        match selector.device_type {
            Some(device_type) => vec![device_type],
            None => DeviceType::ALL
                .into_iter()
                .filter(|d| Self::is_supported(*d) && !self.excluded.contains(d))
                .collect(),
        }
    }

    async fn list_device_type(
        device_type: DeviceType,
        selector: &DeviceSelector,
    ) -> NativeResult<Vec<DeviceCandidate>> {
        Ok(match device_type {
            #[cfg(feature = "bitbox")]
            DeviceType::BitBox02 => BitBoxDevice::list(selector).await?,
            #[cfg(feature = "ledger")]
            DeviceType::Ledger => LedgerDevice::list(selector).await?,
            #[cfg(feature = "coldcard")]
            DeviceType::Coldcard => ColdcardDevice::list(selector).await?,
            #[cfg(feature = "jade")]
            DeviceType::Jade => JadeDevice::list(selector).await?,
            #[cfg(feature = "keepkey")]
            DeviceType::KeepKey => KeepKeyDevice::list(selector).await?,
            #[cfg(feature = "specter")]
            DeviceType::Specter => SpecterDevice::list(selector).await?,
            #[cfg(feature = "trezor")]
            DeviceType::Trezor => TrezorDevice::list(selector).await?,
            #[allow(unreachable_patterns)]
            _ => return Err(NativeError::NotCompiled(device_type)),
        })
    }
}

#[async_trait(?Send)]
impl DeviceSource for NativeSource {
    type Error = NativeError;

    async fn list(&self, selector: &DeviceSelector) -> NativeResult<Vec<DeviceCandidate>> {
        let results = join_all(
            self.walked(selector)
                .into_iter()
                .map(|device_type| Self::list_device_type(device_type, selector)),
        )
        .await;
        collect_candidates(results)
    }

    async fn open(
        &self,
        candidate: &DeviceCandidate,
        selector: &DeviceSelector,
        pairing_code: Option<&PairingCodePrompt>,
        host_interaction: Option<&HostInteractionFactory>,
    ) -> NativeResult<Device> {
        match candidate.device_type {
            #[cfg(feature = "bitbox")]
            DeviceType::BitBox02 => {
                BitBoxDevice::open(candidate, selector, pairing_code, host_interaction).await
            }
            #[cfg(feature = "ledger")]
            DeviceType::Ledger => {
                LedgerDevice::open(candidate, selector, pairing_code, host_interaction).await
            }
            #[cfg(feature = "coldcard")]
            DeviceType::Coldcard => {
                ColdcardDevice::open(candidate, selector, pairing_code, host_interaction).await
            }
            #[cfg(feature = "jade")]
            DeviceType::Jade => {
                JadeDevice::open(candidate, selector, pairing_code, host_interaction).await
            }
            #[cfg(feature = "keepkey")]
            DeviceType::KeepKey => {
                KeepKeyDevice::open(candidate, selector, pairing_code, host_interaction).await
            }
            #[cfg(feature = "specter")]
            DeviceType::Specter => {
                SpecterDevice::open(candidate, selector, pairing_code, host_interaction).await
            }
            #[cfg(feature = "trezor")]
            DeviceType::Trezor => {
                TrezorDevice::open(candidate, selector, pairing_code, host_interaction).await
            }
            #[allow(unreachable_patterns)]
            device_type => Err(NativeError::NotCompiled(device_type)),
        }
    }
}

/// One bus failing does not hide what the others found; finding nothing reports why.
fn collect_candidates(
    results: Vec<NativeResult<Vec<DeviceCandidate>>>,
) -> NativeResult<Vec<DeviceCandidate>> {
    let mut candidates = Vec::new();
    let mut first_error = None;
    for result in results {
        match result {
            Ok(found) => candidates.extend(found),
            Err(err) if first_error.is_none() => first_error = Some(err),
            Err(_) => {}
        }
    }
    if candidates.is_empty()
        && let Some(err) = first_error
    {
        return Err(err);
    }
    Ok(candidates)
}

/// A selected path names one backend, so the other bus is not walked at all.
#[cfg(any(feature = "keepkey", feature = "trezor"))]
pub(crate) fn uses_backend(selected_path: Option<&str>, prefix: &str) -> bool {
    selected_path.is_none_or(|path| path.starts_with(prefix))
}

/// Native discovery and opening for one device type.
///
/// Futures need not be `Send`. Implementations may use different native I/O
/// backends and emulator probes.
#[async_trait(?Send)]
pub trait DeviceEnumerator {
    /// Lists candidates matching the selector without opening hardware devices.
    ///
    /// Emulator discovery may connect or send a probe; a listed candidate is not
    /// guaranteed to remain available or contain the requested wallet.
    async fn list(selector: &DeviceSelector) -> NativeResult<Vec<DeviceCandidate>>;

    /// Opens a candidate using the selector's device-specific session options.
    ///
    /// Opening may perform protocol I/O, such as a Specter fingerprint probe.
    /// Pairing and host-interaction callbacks are used only by backends that
    /// support them. Opening does not generally unlock the device or verify the
    /// selector's fingerprint.
    async fn open(
        candidate: &DeviceCandidate,
        selector: &DeviceSelector,
        pairing_code: Option<&PairingCodePrompt>,
        host_interaction: Option<&HostInteractionFactory>,
    ) -> NativeResult<Device>;
}

#[cfg(test)]
mod tests {
    use super::*;

    fn candidate(path: &str) -> DeviceCandidate {
        DeviceCandidate {
            device_type: DeviceType::Coldcard,
            name: "Coldcard".to_owned(),
            model: "coldcard".to_owned(),
            path: path.to_owned(),
            is_emulated: false,
        }
    }

    fn error(message: &'static str) -> NativeError {
        NativeError::MissingDeviceId(message)
    }

    #[cfg(feature = "specter")]
    #[test]
    fn an_excluded_device_is_skipped_only_when_not_named() {
        let source = NativeSource::excluding([DeviceType::Specter]);
        assert!(
            !source
                .walked(&DeviceSelector::default())
                .contains(&DeviceType::Specter)
        );
        assert!(
            NativeSource::default()
                .walked(&DeviceSelector::default())
                .contains(&DeviceType::Specter)
        );
        let named = DeviceSelector {
            device_type: Some(DeviceType::Specter),
            ..DeviceSelector::default()
        };
        assert_eq!(source.walked(&named), vec![DeviceType::Specter]);
    }

    #[test]
    fn a_list_keeps_what_the_other_buses_found() {
        let results = vec![
            Ok(vec![candidate("hid:1")]),
            Err(error("unrelated")),
            Ok(vec![candidate("hid:2")]),
        ];

        let found = collect_candidates(results).expect("one bus failing is tolerated");
        assert_eq!(found.len(), 2);
    }

    #[test]
    fn a_list_that_found_nothing_reports_the_first_failure() {
        let results = vec![Err(error("first")), Err(error("second"))];

        let err = collect_candidates(results).expect_err("a list that found nothing reports why");
        assert_eq!(err.to_string(), "first");
    }

    #[test]
    fn one_bus_failing_alone_reports_the_failure() {
        let results = vec![Err(error("path failed"))];

        let err = collect_candidates(results).expect_err("a list that found nothing reports why");
        assert_eq!(err.to_string(), "path failed");
    }

    #[test]
    fn a_list_that_found_something_ignores_the_failure() {
        let results = vec![Err(error("unrelated")), Ok(vec![candidate("hid:1")])];

        let found = collect_candidates(results).expect("a found device wins over an error");
        assert_eq!(found.len(), 1);
    }
}