@doko/react-native-yubikit 0.0.2

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Quan Pham
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+react-native-yubikit
+
+A React Native TurboModule wrapper around Yubico's native [YubiKit Android](https://developers.yubico.com/yubikit-android/) and [YubiKit iOS](https://developers.yubico.com/yubikit-ios/) SDKs, for talking to YubiKey hardware over USB and NFC.
+
+[![npm version](https://img.shields.io/npm/v/@doko/react-native-yubikit?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@doko/react-native-yubikit)
+[![Monthly downloads](https://img.shields.io/npm/dm/@doko/react-native-yubikit?style=for-the-badge)](https://www.npmjs.com/package/@doko/react-native-yubikit)
+[![New Architecture](https://img.shields.io/badge/New%20Architecture-Only-5f3dc4?style=for-the-badge)](https://reactnative.dev/docs/the-new-architecture/landing-page)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Supported-3178C6?style=for-the-badge)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-2f9e44?style=for-the-badge)](LICENSE)
+[![iOS](https://img.shields.io/badge/iOS-16%2B-000000?style=for-the-badge&logo=apple)](https://developer.apple.com/ios/)
+[![Android](https://img.shields.io/badge/Android-API%2024%2B-3DDC84?style=for-the-badge&logo=android&logoColor=white)](https://developer.android.com/)
+
+📖 **Full documentation:** [doko.aniviet.com/oss/react-native-yubikey](https://doko.aniviet.com/oss/react-native-yubikey)
+
+The docs site covers requirements, installation (including the iOS Podfile override you need), usage examples for every module, security notes, advanced patterns, and troubleshooting. This README is deliberately short - start there for anything beyond a quick look.
+
+---
+
+## Features
+
+- 🔌 **USB + NFC discovery** - attach/detach events via a single `YubiKeyEvent` stream
+- 🧩 **8 native modules**, exposed as namespaces: `Core`, `Support`, `Management`, `Oath`, `Piv`, `OpenPgp`, `YubiOtp`, `Fido`
+- 🪝 **`YubiKeyProvider` + `useYubiKey()`** - drop-in device discovery/selection state, no boilerplate required
+- 🔐 **PIV** - PIN/PUK, slot metadata, certificates, key generation, raw sign/decrypt
+- 🔑 **FIDO2/WebAuthn** - authenticator info, registration, authentication
+- ⏱️ **OATH** - TOTP/HOTP credential management and code calculation
+- 🆕 **New Architecture only** - built as Fabric/TurboModules with Codegen, no old-bridge fallback
+
+---
+
+## Platform support
+
+Android has full parity across every module. iOS is missing OpenPGP entirely, YubiOTP slot programming, and FIDO2 resident-credential management - these gaps come from the underlying YubiKit iOS SDK itself, not from this wrapper. See the [full platform support table](https://doko.aniviet.com/oss/react-native-yubikey) on the docs site for the exact per-method breakdown.
+
+| Module         | Android | iOS                                     |
+| -------------- | ------- | --------------------------------------- |
+| Core / Support | Full    | Full                                    |
+| Management     | Full    | Partial                                 |
+| OATH           | Full    | Full                                    |
+| PIV            | Full    | Full (no RSA3072/4096 raw sign/decrypt) |
+| OpenPGP        | Full    | Not available                           |
+| YubiOTP        | Full    | Partial (HMAC-SHA1 only)                |
+| FIDO2          | Full    | Partial (no credential management)      |
+
+---
+
+## Requirements
+
+|              | Minimum                                                                                                                                                        |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| React Native | 0.74+ with the **New Architecture enabled**                                                                                                                    |
+| iOS          | 16.4+ recommended ([Podfile override required](https://doko.aniviet.com/oss/react-native-yubikey/installation) - the CocoaPods-trunk `YubiKit` pod is too old) |
+| Android      | `minSdkVersion` 24                                                                                                                                             |
+
+---
+
+## Installation
+
+```sh
+npm install @doko/react-native-yubikit
+# or
+yarn add @doko/react-native-yubikit
+# or
+pnpm add @doko/react-native-yubikit
+```
+
+iOS needs a Podfile override and a few entitlements depending on which transports you use; Android needs USB/NFC manifest entries. See [Installation](https://doko.aniviet.com/oss/react-native-yubikey/installation) for the exact steps.
+
+---
+
+## Quick start
+
+```tsx
+import { YubiKeyProvider, useYubiKey } from '@doko/react-native-yubikit';
+
+export default function App() {
+  return (
+    <YubiKeyProvider>
+      <DeviceScreen />
+    </YubiKeyProvider>
+  );
+}
+
+function DeviceScreen() {
+  const { devices, selectedDevice, startUsbDiscovery, stopUsbDiscovery } =
+    useYubiKey();
+
+  // startUsbDiscovery({ handlePermissions: true }) to begin listening,
+  // then read/write against selectedDevice.handle with any module below.
+}
+```
+
+```ts
+import { Management, Oath, Piv } from '@doko/react-native-yubikit';
+
+const info = await Management.getDeviceInfo(deviceHandle);
+await Piv.verifyPin(deviceHandle, '123456');
+const { credentials } = await Oath.getCredentials(deviceHandle);
+```
+
+More examples for every module are in [Usage Examples](https://doko.aniviet.com/oss/react-native-yubikey/usage).
+
+---
+
+## Example app
+
+A runnable example app is included in [`example/`](./example) (Expo Router, demonstrates every supported module).
+
+```sh
+pnpm install
+pnpm example start
+```
+
+Then press `a` for Android or `i` for iOS.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow, build instructions, and how to send a pull request.
+
+---
+
+## License
+
+MIT

package/RNYubikit.podspec

@@ -0,0 +1,22 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "RNYubikit"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/Doko-Demo-Doa/react-native-yubikit.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  s.private_header_files = "ios/**/*.h"
+
+  s.dependency "YubiKit"
+
+  install_modules_dependencies(s)
+end

package/android/build.gradle

@@ -0,0 +1,63 @@
+buildscript {
+  ext.Yubikit = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return Yubikit[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.yubikit"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+
+  def yubikitVersion = "3.1.0"
+  implementation "com.yubico.yubikit:android:${yubikitVersion}"
+  implementation "com.yubico.yubikit:core:${yubikitVersion}"
+  implementation "com.yubico.yubikit:fido:${yubikitVersion}"
+  implementation "com.yubico.yubikit:fido-android-ui:${yubikitVersion}"
+  implementation "com.yubico.yubikit:management:${yubikitVersion}"
+  implementation "com.yubico.yubikit:yubiotp:${yubikitVersion}"
+  implementation "com.yubico.yubikit:openpgp:${yubikitVersion}"
+  implementation "com.yubico.yubikit:oath:${yubikitVersion}"
+  implementation "com.yubico.yubikit:piv:${yubikitVersion}"
+  implementation "com.yubico.yubikit:support:${yubikitVersion}"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,9 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <!-- YubiKey USB support -->
+  <uses-feature android:name="android.hardware.usb.host" android:required="false" />
+  <uses-permission android:name="android.permission.NFC" />
+
+  <application>
+    <!-- YubiKit uses USB device detection via the host APIs; no manifest receivers are required. -->
+  </application>
+</manifest>

package/android/src/main/java/com/yubikit/YubiKitManagerHolder.kt

@@ -0,0 +1,330 @@
+package com.yubikit
+
+import android.app.Activity
+import android.content.Context
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.yubico.yubikit.android.YubiKitManager
+import com.yubico.yubikit.android.transport.nfc.NfcConfiguration
+import com.yubico.yubikit.android.transport.nfc.NfcNotAvailable
+import com.yubico.yubikit.android.transport.nfc.NfcYubiKeyDevice
+import com.yubico.yubikit.android.transport.usb.UsbConfiguration
+import com.yubico.yubikit.android.transport.usb.UsbYubiKeyDevice
+import com.yubico.yubikit.core.YubiKeyConnection
+import com.yubico.yubikit.core.YubiKeyDevice
+import com.yubico.yubikit.core.fido.FidoConnection
+import com.yubico.yubikit.core.otp.OtpConnection
+import com.yubico.yubikit.core.smartcard.SmartCardConnection
+import com.yubikit.utils.YubikitUtils.toWritableMap
+import java.io.IOException
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * Singleton holder for the YubiKitManager and discovered devices/connections.
+ */
+object YubiKitManagerHolder {
+    @Volatile
+    private var manager: YubiKitManager? = null
+
+    private val devices = ConcurrentHashMap<String, YubiKeyDevice>()
+    private val connections = ConcurrentHashMap<String, YubiKeyConnection>()
+    private val connectionReleaseLatches = ConcurrentHashMap<String, CountDownLatch>()
+
+    private var usbConfiguration = UsbConfiguration()
+    private var nfcConfiguration = NfcConfiguration()
+
+    @JvmStatic
+    fun initialize(context: Context) {
+        if (manager == null) {
+            synchronized(this) {
+                if (manager == null) {
+                    manager = YubiKitManager(context.applicationContext)
+                }
+            }
+        }
+    }
+
+    @JvmStatic
+    fun getManager(): YubiKitManager {
+        return manager ?: throw IllegalStateException("YubiKitManager not initialized")
+    }
+
+    @JvmStatic
+    fun putDevice(device: YubiKeyDevice): String {
+        val handle = UUID.randomUUID().toString()
+        devices[handle] = device
+        return handle
+    }
+
+    @JvmStatic
+    fun getDevice(handle: String): YubiKeyDevice {
+        return devices[handle] ?: throw IllegalArgumentException("Unknown device handle: $handle")
+    }
+
+    @JvmStatic
+    fun removeDevice(handle: String) {
+        devices.remove(handle)
+    }
+
+    @JvmStatic
+    fun listDevices(): List<Pair<String, YubiKeyDevice>> {
+        return devices.toList()
+    }
+
+    @JvmStatic
+    fun putConnection(connection: YubiKeyConnection): String {
+        val handle = UUID.randomUUID().toString()
+        connections[handle] = connection
+        return handle
+    }
+
+    @JvmStatic
+    fun getConnection(handle: String): YubiKeyConnection {
+        return connections[handle]
+            ?: throw IllegalArgumentException("Unknown connection handle: $handle")
+    }
+
+    @JvmStatic
+    fun removeConnection(handle: String) {
+        connections.remove(handle)?.close()
+        // Wakes up the requestConnection() call still blocked on this handle's
+        // latch below, letting its try-with-resources finally close.
+        connectionReleaseLatches.remove(handle)?.countDown()
+    }
+
+    @JvmStatic
+    fun closeAllConnections() {
+        connections.values.forEach { try { it.close() } catch (_: IOException) {} }
+        connections.clear()
+    }
+
+    @JvmStatic
+    fun setUsbConfiguration(config: UsbConfiguration) {
+        usbConfiguration = config
+    }
+
+    @JvmStatic
+    fun getUsbConfiguration(): UsbConfiguration = usbConfiguration
+
+    @JvmStatic
+    fun setNfcConfiguration(config: NfcConfiguration) {
+        nfcConfiguration = config
+    }
+
+    @JvmStatic
+    fun getNfcConfiguration(): NfcConfiguration = nfcConfiguration
+
+    // Set by YubikitCoreModule while the TurboModule instance is alive, so device
+    // attach/detach/failure can be routed to its generated emitOnYubiKeyEvent(...).
+    @Volatile
+    private var eventHandler: ((WritableMap) -> Unit)? = null
+
+    @JvmStatic
+    fun setEventHandler(handler: ((WritableMap) -> Unit)?) {
+        eventHandler = handler
+    }
+
+    @JvmStatic
+    fun emitDeviceAttached(handle: String, device: YubiKeyDevice) {
+        val params = Arguments.createMap().apply {
+            putString("type", "attached")
+            putMap("device", deviceToBundle(handle, device).toWritableMap())
+        }
+        eventHandler?.invoke(params)
+    }
+
+    @JvmStatic
+    fun emitDeviceDetached(handle: String) {
+        removeDevice(handle)
+        val params = Arguments.createMap().apply {
+            putString("type", "detached")
+            putString("handle", handle)
+        }
+        eventHandler?.invoke(params)
+    }
+
+    @JvmStatic
+    fun emitError(error: String) {
+        val params = Arguments.createMap().apply {
+            putString("type", "error")
+            putString("error", error)
+        }
+        eventHandler?.invoke(params)
+    }
+
+    @JvmStatic
+    fun deviceToBundle(handle: String, device: YubiKeyDevice): android.os.Bundle {
+        return android.os.Bundle().apply {
+            putString("handle", handle)
+            putString("transport", device.transport.name.lowercase())
+            putStringArrayList(
+                "supportedConnections",
+                ArrayList(
+                    listOfNotNull(
+                        if (device.supportsConnection(SmartCardConnection::class.java)) "SmartCardConnection" else null,
+                        if (device.supportsConnection(OtpConnection::class.java)) "OtpConnection" else null,
+                        if (device.supportsConnection(FidoConnection::class.java)) "FidoConnection" else null
+                    )
+                )
+            )
+        }
+    }
+
+    @JvmStatic
+    fun startUsbDiscovery() {
+        getManager().startUsbDiscovery(usbConfiguration) { device: UsbYubiKeyDevice ->
+            val handle = putDevice(device)
+            device.setOnClosed {
+                emitDeviceDetached(handle)
+            }
+            emitDeviceAttached(handle, device)
+        }
+    }
+
+    @JvmStatic
+    fun stopUsbDiscovery() {
+        getManager().stopUsbDiscovery()
+    }
+
+    @JvmStatic
+    @Throws(NfcNotAvailable::class)
+    fun startNfcDiscovery(activity: Activity) {
+        getManager().startNfcDiscovery(nfcConfiguration, activity) { device: NfcYubiKeyDevice ->
+            val handle = putDevice(device)
+            emitDeviceAttached(handle, device)
+        }
+    }
+
+    @JvmStatic
+    fun stopNfcDiscovery(activity: Activity) {
+        getManager().stopNfcDiscovery(activity)
+    }
+
+    /**
+     * Open a connection synchronously. Must not be called on the UI thread.
+     */
+    @JvmStatic
+    fun <T : YubiKeyConnection> openConnection(
+        deviceHandle: String,
+        connectionType: Class<T>
+    ): Pair<String, T> {
+        val device = getDevice(deviceHandle)
+        val connection = device.openConnection(connectionType)
+        val handle = putConnection(connection)
+        return handle to connection
+    }
+
+    // Non-OTP connections are opened by the SDK inside a try-with-resources block that
+    // closes the connection the instant device.requestConnection()'s callback returns
+    // (see UsbYubiKeyDevice.requestConnection). Since this module's requestConnection/
+    // sendApdu/closeConnection are exposed as three separate, independently-timed JS
+    // calls, the callback below is kept alive on a latch until closeConnection() (or
+    // this timeout) releases it, so the connection stays open across those calls.
+    private const val CONNECTION_HOLD_TIMEOUT_MS = 120_000L
+
+    /**
+     * Open a connection asynchronously and return the handle.
+     */
+    @JvmStatic
+    fun requestConnection(
+        deviceHandle: String,
+        connectionType: Class<out YubiKeyConnection>,
+        callback: (Result<Pair<String, YubiKeyConnection>>) -> Unit
+    ) {
+        val device = getDevice(deviceHandle)
+        device.requestConnection(connectionType) { result ->
+            var handle: String? = null
+            try {
+                val connection = result.value
+                handle = putConnection(connection)
+                val releaseLatch = CountDownLatch(1)
+                connectionReleaseLatches[handle] = releaseLatch
+                callback(Result.success(handle to connection))
+                releaseLatch.await(CONNECTION_HOLD_TIMEOUT_MS, TimeUnit.MILLISECONDS)
+            } catch (e: Exception) {
+                callback(Result.failure(e))
+            } finally {
+                // No-op if closeConnection() already removed it; guards against the
+                // timeout case where the JS side never explicitly released it.
+                handle?.let { connections.remove(it)?.close(); connectionReleaseLatches.remove(it) }
+            }
+        }
+    }
+
+    /**
+     * Run a synchronous operation on a connection inside a requestConnection callback.
+     * This is the preferred pattern because it automatically closes the connection.
+     */
+    @JvmStatic
+    fun <T : YubiKeyConnection, R> withConnection(
+        deviceHandle: String,
+        connectionType: Class<T>,
+        timeoutMs: Long = 30000,
+        block: (T) -> R
+    ): R {
+        val device = getDevice(deviceHandle)
+        val latch = CountDownLatch(1)
+        val resultRef = AtomicReference<Result<R>>()
+
+        device.requestConnection(connectionType) { result ->
+            try {
+                val connection = result.value
+                connection.use {
+                    resultRef.set(Result.success(block(connection)))
+                }
+            } catch (e: Exception) {
+                resultRef.set(Result.failure(e))
+            } finally {
+                latch.countDown()
+            }
+        }
+
+        if (!latch.await(timeoutMs, TimeUnit.MILLISECONDS)) {
+            throw IOException("Timeout waiting for YubiKey connection")
+        }
+
+        return resultRef.get().getOrThrow()
+    }
+
+    @JvmStatic
+    fun <R> withSmartCard(deviceHandle: String, block: (SmartCardConnection) -> R): R {
+        return withConnection(deviceHandle, SmartCardConnection::class.java, block = block)
+    }
+
+    @JvmStatic
+    fun <R> withOtp(deviceHandle: String, block: (OtpConnection) -> R): R {
+        return withConnection(deviceHandle, OtpConnection::class.java, block = block)
+    }
+
+    @JvmStatic
+    fun <R> withFido(deviceHandle: String, block: (FidoConnection) -> R): R {
+        return withConnection(deviceHandle, FidoConnection::class.java, block = block)
+    }
+
+    /**
+     * Opens whichever of SmartCard/Otp/Fido the device actually supports, in that
+     * preference order. Several sessions (ManagementSession, Ctap2Session) accept more
+     * than one connection type, and hardcoding a single type breaks devices/transports
+     * that don't support it (e.g. NFC devices only ever support SmartCardConnection).
+     */
+    @JvmStatic
+    fun <R> withAnyConnection(
+        deviceHandle: String,
+        preferredOrder: List<Class<out YubiKeyConnection>>,
+        block: (YubiKeyConnection) -> R
+    ): R {
+        val device = getDevice(deviceHandle)
+        val connectionType = preferredOrder.firstOrNull { device.supportsConnection(it) }
+            ?: throw IllegalArgumentException("Device does not support any of: ${preferredOrder.map { it.simpleName }}")
+        return when (connectionType) {
+            SmartCardConnection::class.java -> withConnection(deviceHandle, SmartCardConnection::class.java) { block(it) }
+            OtpConnection::class.java -> withConnection(deviceHandle, OtpConnection::class.java) { block(it) }
+            FidoConnection::class.java -> withConnection(deviceHandle, FidoConnection::class.java) { block(it) }
+            else -> throw IllegalArgumentException("Unsupported connection type: $connectionType")
+        }
+    }
+}