@ledgerhq/device-transport-kit-react-native-hid 0.0.0-rn-hid-20250221112139 → 0.0.0-rn-hid-20250221115747

package/android/src/main/kotlin/com/ledger/devicesdk/shared/androidMain/transport/usb/model/ProductId.kt

@@ -0,0 +1,11 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Ledger SAS
+ * SPDX-License-Identifier: LicenseRef-LEDGER
+ */
+
+package com.ledger.devicesdk.shared.androidMain.transport.usb.model
+
+@JvmInline
+public value class ProductId(
+    public val id: Int,
+)

package/android/src/main/kotlin/com/ledger/devicesdk/shared/androidMain/transport/usb/model/UsbPermissionEvent.kt

@@ -0,0 +1,14 @@
+/*
+ * SPDX-FileCopyrightText: 2023 Ledger SAS
+ * SPDX-License-Identifier: LicenseRef-LEDGER
+ */
+
+package com.ledger.devicesdk.shared.androidMain.transport.usb.model
+
+internal sealed class UsbPermissionEvent {
+    data class PermissionGranted(
+        val ledgerUsbDevice: LedgerUsbDevice,
+    ) : UsbPermissionEvent()
+
+    data object PermissionDenied : UsbPermissionEvent()
+}

package/android/src/main/kotlin/com/ledger/devicesdk/shared/androidMain/transport/usb/model/UsbState.kt

@@ -0,0 +1,16 @@
+/*
+ * SPDX-FileCopyrightText: 2023 Ledger SAS
+ * SPDX-License-Identifier: LicenseRef-LEDGER
+ */
+
+package com.ledger.devicesdk.shared.androidMain.transport.usb.model
+
+internal sealed class UsbState {
+    data class Detached(
+        val ledgerUsbDevice: LedgerUsbDevice,
+    ) : UsbState()
+
+    data class Attached(
+        val ledgerUsbDevice: LedgerUsbDevice,
+    ): UsbState()
+}

package/android/src/main/kotlin/com/ledger/devicesdk/shared/androidMain/transport/usb/model/VendorId.kt

@@ -0,0 +1,11 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Ledger SAS
+ * SPDX-License-Identifier: LicenseRef-LEDGER
+ */
+
+package com.ledger.devicesdk.shared.androidMain.transport.usb.model
+
+@JvmInline
+internal value class VendorId(
+    val id: Int,
+)

package/android/src/main/kotlin/com/ledger/devicesdk/shared/androidMain/transport/usb/utils/UsbDeviceMapper.kt

@@ -0,0 +1,55 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Ledger SAS
+ * SPDX-License-Identifier: LicenseRef-LEDGER
+ */
+
+package com.ledger.devicesdk.shared.androidMain.transport.usb.utils
+
+import com.ledger.devicesdk.shared.api.device.LedgerDevice
+import com.ledger.devicesdk.shared.androidMain.transport.usb.model.ProductId
+
+internal fun ProductId.toLedgerDevice(): LedgerDevice? =
+    when {
+        this.id.isLedgerDeviceProductId(LedgerDevice.NanoS)
+        -> {
+            LedgerDevice.NanoS
+        }
+
+        this.id.isLedgerDeviceProductId(LedgerDevice.NanoSPlus)
+        -> {
+            LedgerDevice.NanoSPlus
+        }
+
+        this.id.isLedgerDeviceProductId(LedgerDevice.NanoX)
+        -> {
+            LedgerDevice.NanoX
+        }
+
+        this.id.isLedgerDeviceProductId(LedgerDevice.Stax)
+        -> {
+            LedgerDevice.Stax
+        }
+
+        this.id.isLedgerDeviceProductId(LedgerDevice.Flex)
+        -> {
+            LedgerDevice.Flex
+        }
+
+        else -> {
+            null
+        }
+    }
+
+private fun Int.isLedgerDeviceProductId(device: LedgerDevice): Boolean {
+    val productId = device.usbInfo.productIdMask.sdkHexToInt()
+    val shiftedId = this shr 8
+    return shiftedId == productId
+}
+
+@OptIn(ExperimentalStdlibApi::class)
+public fun String.sdkHexToInt(withPrefix: Boolean = true): Int =
+    if (withPrefix) {
+        this.substring(2).hexToInt()
+    } else {
+        this.hexToInt()
+    }

package/android/src/main/kotlin/com/ledger/devicesdk/shared/androidMain/transport/usb/utils/UsbMapper.kt

@@ -0,0 +1,56 @@
+/*
+ * SPDX-FileCopyrightText: 2023 Ledger SAS
+ * SPDX-License-Identifier: LicenseRef-LEDGER
+ */
+
+package com.ledger.devicesdk.shared.androidMain.transport.usb.utils
+
+import android.content.Intent
+import android.hardware.usb.UsbManager
+import android.os.Build
+import com.ledger.devicesdk.shared.api.device.LedgerDevice
+import com.ledger.devicesdk.shared.api.discovery.ConnectivityType
+import com.ledger.devicesdk.shared.api.discovery.DiscoveryDevice
+import com.ledger.devicesdk.shared.androidMain.transport.usb.model.VendorId
+import com.ledger.devicesdk.shared.androidMain.transport.usb.model.ProductId
+import com.ledger.devicesdk.shared.androidMain.transport.usb.model.LedgerUsbDevice
+
+internal fun LedgerUsbDevice.toScannedDevice() =
+   DiscoveryDevice(
+        uid = this.uid,
+        name = this.name,
+        ledgerDevice = this.ledgerDevice,
+        connectivityType = ConnectivityType.Usb,
+    )
+
+internal fun List<android.hardware.usb.UsbDevice>.toUsbDevices(): List<LedgerUsbDevice> = mapNotNull { it.toLedgerUsbDevice() }
+
+internal fun android.hardware.usb.UsbDevice.toLedgerUsbDevice(): LedgerUsbDevice? {
+    val productId = ProductId(this.productId)
+    val vendorId = VendorId(this.vendorId)
+
+    val ledgerDevice = productId.toLedgerDevice()
+    return if (vendorId.id == LedgerDevice.LEDGER_USB_VENDOR_ID.toProductIdInt() && ledgerDevice != null) {
+        return LedgerUsbDevice(
+            uid = this.deviceId.toString(),
+            name = ledgerDevice.name,
+            vendorId = vendorId,
+            productId = productId,
+            ledgerDevice = ledgerDevice,
+        )
+    } else {
+        null
+    }
+}
+
+private fun String.toProductIdInt(): Int = this.substring(2).toInt(16)
+
+internal fun Intent.getAndroidUsbDevice(): android.hardware.usb.UsbDevice {
+    val device =
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            getParcelableExtra(UsbManager.EXTRA_DEVICE, android.hardware.usb.UsbDevice::class.java)
+        } else {
+            getParcelableExtra(UsbManager.EXTRA_DEVICE)
+        }
+    return checkNotNull(device)
+}

package/android/src/main/kotlin/com/ledger/devicesdk/shared/androidMainInternal/transport/UsbConst.android.kt

@@ -0,0 +1,8 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Ledger SAS
+ * SPDX-License-Identifier: LicenseRef-LEDGER
+ */
+
+package com.ledger.devicesdk.shared.androidMainInternal.transport
+
+internal val USB_MTU: Int = 64

package/android/src/main/kotlin/com/ledger/devicesdk/shared/androidMainInternal/transport/deviceconnection/DeviceApduSender.kt

@@ -0,0 +1,13 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Ledger SAS
+ * SPDX-License-Identifier: LicenseRef-LEDGER
+ */
+
+package com.ledger.devicesdk.shared.androidMainInternal.transport.deviceconnection
+
+import com.ledger.devicesdk.shared.api.apdu.SendApduResult
+
+internal interface DeviceApduSender<Dependencies> {
+    suspend fun send(apdu: ByteArray): SendApduResult
+    val dependencies: Dependencies
+}

package/android/src/main/kotlin/com/ledger/devicesdk/shared/androidMainInternal/transport/deviceconnection/DeviceConnection.kt

@@ -0,0 +1,96 @@
+package com.ledger.devicesdk.shared.androidMainInternal.transport.deviceconnection
+
+import com.ledger.devicesdk.shared.api.apdu.SendApduResult
+import com.ledger.devicesdk.shared.internal.service.logger.LoggerService
+import com.ledger.devicesdk.shared.internal.service.logger.buildSimpleErrorLogInfo
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.launch
+import kotlin.coroutines.resume
+import kotlin.coroutines.suspendCoroutine
+import kotlin.time.Duration
+
+internal class DeviceConnection<Dependencies>(
+    val sessionId: String,
+    private var deviceApduSender: DeviceApduSender<Dependencies>,
+    isFatalSendApduFailure: (SendApduResult.Failure) -> Boolean,
+    reconnectionTimeoutDuration: Duration,
+    private val onTerminated: (DeviceConnection<Dependencies>) -> Unit,
+    private val coroutineScope: CoroutineScope,
+    private val loggerService: LoggerService,
+) {
+    private val stateMachine: DeviceConnectionStateMachine
+
+    init {
+        stateMachine = DeviceConnectionStateMachine(
+            sendApduFn = {
+                coroutineScope.launch {
+                    val res = deviceApduSender.send(it)
+                    handleApduResult(res)
+                }
+            },
+            onTerminated = {
+                onTerminated(this)
+            },
+            isFatalSendApduFailure = isFatalSendApduFailure,
+            reconnectionTimeoutDuration = reconnectionTimeoutDuration,
+            coroutineScope = coroutineScope,
+            onError = {
+                loggerService.log(
+                    buildSimpleErrorLogInfo(
+                        "DeviceConnection",
+                        "State machine error $it"
+                    )
+                )
+            },
+            loggerService = loggerService,
+        )
+    }
+
+
+    private fun handleApduResult(result: SendApduResult) {
+        stateMachine.handleApduResult(result)
+    }
+
+    public fun setApduSender(apduSender: DeviceApduSender<Dependencies>) {
+        deviceApduSender = apduSender
+    }
+
+    public fun getApduSender(): DeviceApduSender<Dependencies> {
+        return deviceApduSender
+    }
+
+    public fun handleDeviceConnected() {
+        stateMachine.handleDeviceConnected()
+    }
+
+    public fun handleDeviceDisconnected() {
+        stateMachine.handleDeviceDisconnected()
+    }
+
+    public suspend fun requestSendApdu(apdu: ByteArray): SendApduResult =
+        suspendCoroutine { cont ->
+            stateMachine.requestSendApdu(
+                DeviceConnectionStateMachine.SendApduRequestContent(
+                    apdu = apdu,
+                    triggersDisconnection = apduTriggersDisconnection(apdu),
+                    resultCallback = cont::resume
+                )
+            )
+        }
+
+    public fun requestCloseConnection() {
+        stateMachine.requestCloseConnection()
+    }
+
+    private fun apduTriggersDisconnection(apdu: ByteArray): Boolean {
+        val apduMap = mapOf(
+            "openApp" to byteArrayOf(0xe0.toByte(), 0xd8.toByte(), 0x00, 0x00),
+            "closeApp" to byteArrayOf(0xb0.toByte(), 0xa7.toByte(), 0x00, 0x00)
+        )
+
+        return apduMap.values.any { known ->
+            (0 until 4).all { i -> known[i] == apdu[i] }
+        }
+    }
+
+}

package/android/src/main/kotlin/com/ledger/devicesdk/shared/androidMainInternal/transport/deviceconnection/DeviceConnectionStateMachine.kt

@@ -0,0 +1,311 @@
+package com.ledger.devicesdk.shared.androidMainInternal.transport.deviceconnection
+
+import com.ledger.devicesdk.shared.api.apdu.SendApduFailureReason
+import com.ledger.devicesdk.shared.api.apdu.SendApduResult
+import com.ledger.devicesdk.shared.internal.service.logger.LoggerService
+import com.ledger.devicesdk.shared.internal.service.logger.buildSimpleDebugLogInfo
+import com.ledger.devicesdk.shared.internal.service.logger.buildSimpleInfoLogInfo
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.launch
+import kotlin.time.Duration
+
+internal class DeviceConnectionStateMachine(
+    private val sendApduFn: (apdu: ByteArray) -> Unit,
+    private val onTerminated: () -> Unit,
+    private val isFatalSendApduFailure: (SendApduResult.Failure) -> Boolean,
+    private val reconnectionTimeoutDuration: Duration,
+    private val coroutineScope: CoroutineScope,
+    private val onError: (Throwable) -> Unit,
+    private val loggerService: LoggerService,
+) {
+
+    private var state: State = State.Connected
+
+    private fun pushState(newState: State) {
+        when (newState) {
+            is State.Connected -> {}
+            is State.SendingApdu -> {
+                sendApduFn(newState.requestContent.apdu)
+            }
+
+            is State.WaitingForReconnection -> {
+                startReconnectionTimeout()
+            }
+
+            is State.WaitingForReconnectionWithQueuedApdu -> {}
+            is State.Terminated -> {
+                onTerminated()
+            }
+        }
+        this.state = newState
+    }
+
+    private fun handleEvent(event: Event) {
+        val currentState = state
+        when (currentState) {
+            is State.Connected -> {
+                when (event) {
+                    is Event.SendApduRequested -> {
+                        pushState(State.SendingApdu(event.requestContent))
+                    }
+
+                    is Event.CloseConnectionRequested -> {
+                        pushState(State.Terminated)
+                    }
+
+                    is Event.DeviceDisconnected -> {
+                        pushState(State.WaitingForReconnection)
+                    }
+
+                    else -> {
+                        onError(Exception("Unhandled event: $event in state: $currentState"))
+                    }
+                }
+            }
+
+            is State.SendingApdu -> {
+                when (event) {
+                    is Event.ApduResultReceived -> {
+                        when (event.result) {
+                            is SendApduResult.Failure -> {
+                                if (isFatalSendApduFailure(event.result)) {
+                                    pushState(State.Terminated)
+                                } else {
+                                    pushState(State.Connected)
+                                }
+                            }
+
+                            is SendApduResult.Success -> {
+                                // check if last 2 bytes of APDU are [0x90,OxO0]
+                                val apdu = event.result.apdu
+                                val apduSize = apdu.size
+                                val isSuccessApdu =
+                                    apdu.size >= 2 &&
+                                            apdu[apduSize - 2] == 0x90.toByte() &&
+                                            apdu[apduSize - 1] == 0x00.toByte()
+
+                                if (isSuccessApdu && currentState.requestContent.triggersDisconnection) {
+                                    pushState(State.WaitingForReconnection)
+                                } else {
+                                    pushState(State.Connected)
+                                }
+                            }
+                        }
+                        currentState.requestContent.resultCallback(event.result)
+                    }
+
+                    is Event.CloseConnectionRequested -> {
+                        pushState(State.Terminated)
+                        currentState.requestContent.resultCallback(
+                            SendApduResult.Failure(
+                                SendApduFailureReason.DeviceDisconnected
+                            )
+                        )
+                    }
+
+                    is Event.DeviceDisconnected -> {
+                        pushState(State.WaitingForReconnection)
+                        currentState.requestContent.resultCallback(
+                            SendApduResult.Failure(
+                                SendApduFailureReason.DeviceDisconnected
+                            )
+                        )
+                    }
+
+                    is Event.SendApduRequested -> {
+                        event.requestContent.resultCallback(
+                            SendApduResult.Failure(
+                                SendApduFailureReason.DeviceBusy
+                            )
+                        )
+                    }
+
+                    else -> {
+                        onError(Exception("Unhandled event: $event in state: $currentState"))
+                    }
+                }
+            }
+
+            is State.WaitingForReconnection -> {
+                when (event) {
+                    is Event.DeviceConnected -> {
+                        pushState(State.Connected)
+                        cancelReconnectionTimeout()
+                    }
+
+                    is Event.SendApduRequested -> {
+                        pushState(State.WaitingForReconnectionWithQueuedApdu(event.requestContent))
+                    }
+
+                    is Event.WaitingForReconnectionTimedOut,
+                    is Event.CloseConnectionRequested -> {
+                        pushState(State.Terminated)
+                        cancelReconnectionTimeout()
+                    }
+
+                    is Event.DeviceDisconnected -> {
+                        /**
+                         * Do nothing, this will happen if we send an apdu that triggers a
+                         * disconnection, because we will move to this state before the disconnection
+                         * is detected:
+                         *
+                         * 1. APDU that triggers a disconnection is sent.
+                         * 2. We receive a 0x9000 (success) response.
+                         *      -> We go to State.WaitingForReconnection.
+                         * 3. Device disconnection is finally detected:
+                         *      -> Event.DeviceDisconnected is received here.
+                         */
+                    }
+
+                    else -> {
+                        onError(Exception("Unhandled event: $event in state: $currentState"))
+                    }
+                }
+            }
+
+            is State.WaitingForReconnectionWithQueuedApdu -> {
+                when (event) {
+                    is Event.DeviceConnected -> {
+                        pushState(State.SendingApdu(currentState.requestContent))
+                        cancelReconnectionTimeout()
+                    }
+
+                    is Event.CloseConnectionRequested,
+                    is Event.WaitingForReconnectionTimedOut -> {
+                        pushState(State.Terminated)
+                        currentState.requestContent.resultCallback(
+                            SendApduResult.Failure(
+                                SendApduFailureReason.DeviceDisconnected
+                            )
+                        )
+                        cancelReconnectionTimeout()
+                    }
+
+                    is Event.SendApduRequested -> {
+                        event.requestContent.resultCallback(
+                            SendApduResult.Failure(
+                                SendApduFailureReason.DeviceBusy
+                            )
+                        )
+                    }
+
+                    is Event.DeviceDisconnected -> {
+                        /**
+                         * Do nothing, this will happen if we send an apdu that triggers a
+                         * disconnection, because we will move to this state before the disconnection
+                         * is detected:
+                         *
+                         * 1. APDU that triggers a disconnection is sent.
+                         * 2. We receive a 0x9000 (success) response
+                         *      -> We go to State.WaitingForReconnection in anticipation of the disconnection event.
+                         * 3. We receive Event.SendApduRequested
+                         *      -> We go to WaitingForReconnectionWithQueuedApdu
+                         * 4. Device disconnection is finally detected:
+                         *      -> Event.DeviceDisconnected is received here.
+                         *
+                         * It can also happen if the device is disconnected while we are sending an APDU.
+                         * cf. description of event below.
+                         */
+                    }
+
+                    is Event.ApduResultReceived -> {
+                        /**
+                         * Do nothing, this will happen if while an APDU is being sent,
+                         * the device disconnection is detected.
+                         * 1. APDU is sent
+                         * 2. Device disconnection is detected
+                         *      -> Event.DeviceDisconnected is received in SendingApdu state.
+                         *      -> We move to WaitingForReconnection state.
+                         * 3. The function to send the APDU returns an error because the device is disconnected.
+                         *      -> Event.ApduResultReceived(result=Failure()) is received in the
+                         *      current state.
+                         *
+                         *  It's a race condition between step 2 and 3.
+                         */
+                    }
+                }
+            }
+
+            is State.Terminated -> {
+                onError(Exception("Unhandled event: $event in state: $currentState"))
+            }
+        }
+        val logMessage = """
+            Received event:
+            In state:       $currentState
+            -> Event:       $event
+            -> New state:   $state
+        """.trimIndent()
+        loggerService.log(buildSimpleDebugLogInfo("DeviceConnectionStateMachine", logMessage))
+    }
+
+    private var timeoutJob: Job? = null
+    private fun startReconnectionTimeout() {
+        // start a timeout and at the end, emit a WaitingForReconnectionTimedOut event
+        timeoutJob = coroutineScope.launch {
+            kotlinx.coroutines.delay(reconnectionTimeoutDuration)
+            handleEvent(Event.WaitingForReconnectionTimedOut)
+        }
+    }
+
+    private fun cancelReconnectionTimeout() {
+        timeoutJob?.cancel()
+        timeoutJob = null
+    }
+
+    public fun requestSendApdu(requestContent: SendApduRequestContent) {
+        handleEvent(Event.SendApduRequested(requestContent))
+    }
+
+    public fun requestCloseConnection() {
+        handleEvent(Event.CloseConnectionRequested)
+    }
+
+    public fun handleApduResult(result: SendApduResult) {
+        handleEvent(Event.ApduResultReceived(result))
+    }
+
+    public fun handleDeviceConnected() {
+        handleEvent(Event.DeviceConnected)
+    }
+
+    public fun handleDeviceDisconnected() {
+        handleEvent(Event.DeviceDisconnected)
+    }
+
+    data class SendApduRequestContent(
+        val apdu: ByteArray,
+        val triggersDisconnection: Boolean,
+        val resultCallback: (SendApduResult) -> Unit
+    )
+
+    sealed class Event {
+        data object DeviceConnected : Event()
+
+        data object DeviceDisconnected : Event()
+
+        data class SendApduRequested(
+            val requestContent: SendApduRequestContent
+        ) : Event()
+
+        data object CloseConnectionRequested : Event()
+
+        data class ApduResultReceived(val result: SendApduResult) : Event()
+
+        data object WaitingForReconnectionTimedOut : Event()
+    }
+
+    sealed class State {
+        data object Connected : State()
+
+        data class SendingApdu(val requestContent: SendApduRequestContent) : State()
+
+        data object WaitingForReconnection : State()
+
+        data class WaitingForReconnectionWithQueuedApdu(val requestContent: SendApduRequestContent) :
+            State()
+
+        data object Terminated : State()
+    }
+}

package/android/src/main/kotlin/com/ledger/devicesdk/shared/api/DeviceAction.kt

@@ -0,0 +1,23 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Ledger SAS
+ * SPDX-License-Identifier: LicenseRef-LEDGER
+ */
+
+package com.ledger.devicesdk.shared.api
+
+public sealed class DeviceAction {
+    public data object GetOsVersion : DeviceAction()
+
+    public data object GetAppAndVersion : DeviceAction()
+
+    public data class InstallApplication(
+        val appName: String,
+    ) : DeviceAction()
+
+    public data object OsUpdate : DeviceAction()
+
+    // fixme will be uncommented once theses device actions be concretely implemented
+//    public data object OpenApplication : DeviceAction()
+//
+//    public data object UpdateApplication : DeviceAction()
+}

package/android/src/main/kotlin/com/ledger/devicesdk/shared/api/apdu/Apdu.kt

@@ -0,0 +1,44 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Ledger SAS
+ * SPDX-License-Identifier: LicenseRef-LEDGER
+ */
+
+package com.ledger.devicesdk.shared.api.apdu
+
+public data class Apdu internal constructor(
+    internal val classInstruction: Byte,
+    internal val instructionMethod: Byte,
+    internal val parameter1: Byte,
+    internal val parameter2: Byte,
+    internal val data: ByteArray?,
+    internal val dataLength: Int,
+) {
+    override fun equals(other: Any?): Boolean {
+        if (this === other) return true
+        if (other == null || this::class != other::class) return false
+
+        other as Apdu
+
+        if (classInstruction != other.classInstruction) return false
+        if (instructionMethod != other.instructionMethod) return false
+        if (parameter1 != other.parameter1) return false
+        if (parameter2 != other.parameter2) return false
+        if (data != null) {
+            if (other.data == null) return false
+            if (!data.contentEquals(other.data)) return false
+        } else if (other.data != null) return false
+        if (dataLength != other.dataLength) return false
+
+        return true
+    }
+
+    override fun hashCode(): Int {
+        var result = classInstruction.toInt()
+        result = 31 * result + instructionMethod
+        result = 31 * result + parameter1
+        result = 31 * result + parameter2
+        result = 31 * result + (data?.contentHashCode() ?: 0)
+        result = 31 * result + dataLength
+        return result
+    }
+}