@onekeyfe/react-native-lite-card 6.7.0-46 → 6.7.0-47

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +134 -53
  2. package/package.json +2 -1
package/README.md CHANGED
@@ -1,16 +1,39 @@
1
- # @onekeyfe/react-native-lite-card
2
-
3
- OneKey Lite NFC card operations for React Native on iOS and Android. The package
4
- wraps native callbacks in promises for card inspection, PIN changes, mnemonic
5
- backup/retrieval and reset. It also exposes native NFC connection UI events.
6
- The application owns the user flow and handling sensitive card data.
1
+ <div align="center">
7
2
 
8
- ## Native SDK source recovery
3
+ # @onekeyfe/react-native-lite-card
9
4
 
10
- The restored GPChannel source is in [sdk/](sdk/README.md). CocoaPods compiles it
11
- on iOS, and Android's CMake build produces the JNI library from the same source.
12
- No precompiled GPChannel framework or JNI library is included. See
13
- [docs/SPEC.md](docs/SPEC.md) for the native ownership and recovery contract.
5
+ **OneKey Lite NFC card operations — inspect, back up and restore, change the PIN — from React Native.**
6
+
7
+ [![npm](https://img.shields.io/npm/v/%40onekeyfe%2Freact-native-lite-card?label=npm&color=4D6BFE)](https://www.npmjs.com/package/@onekeyfe/react-native-lite-card)
8
+ [![license](https://img.shields.io/npm/l/%40onekeyfe%2Freact-native-lite-card?label=license&color=4D6BFE)](LICENSE)
9
+ ![iOS](https://img.shields.io/badge/iOS-000000?logo=apple&logoColor=white)
10
+ ![Android](https://img.shields.io/badge/Android-3DDC84?logo=android&logoColor=white)
11
+ ![TurboModule](https://img.shields.io/badge/TurboModule-4D6BFE)
12
+
13
+ </div>
14
+
15
+ A TurboModule that drives the OneKey Lite NFC card: card information, mnemonic
16
+ backup and retrieval, PIN changes and reset. Native callbacks are wrapped in
17
+ promises and every result carries the native error, data and card state instead
18
+ of throwing on card-level failures. The recovered GPChannel core is compiled from
19
+ source in [`sdk/`](sdk/README.md) — no precompiled framework or JNI library ships
20
+ in the package. The application owns the user flow and the handling of mnemonic
21
+ and PIN values.
22
+
23
+ ## Features
24
+
25
+ - **Card inspection** — `getLiteInfo()` reports the serial, backup state, new-card
26
+ state and remaining PIN retries.
27
+ - **Full backup lifecycle** — write a mnemonic with an overwrite choice, read it
28
+ back with the PIN, change the PIN and reset the card.
29
+ - **Optional write identity guard** — pass `expectedSerial` to `setMnemonic` or
30
+ `changePin` and a mismatch with the freshly read card returns `DeviceMismatch`
31
+ before any PIN or write phase.
32
+ - **Connection UI events** — `addConnectListener` streams the native NFC prompt
33
+ state and returns a subscription with `remove()`.
34
+ - **Auditable native source** — the SDK, iOS bridge and Android JNI build from
35
+ checked-in C/C++/Objective-C/Kotlin, with debug logging disabled in recovered
36
+ builds.
14
37
 
15
38
  ## Installation
16
39
 
@@ -18,59 +41,117 @@ No precompiled GPChannel framework or JNI library is included. See
18
41
  yarn add @onekeyfe/react-native-lite-card
19
42
  ```
20
43
 
21
- Install the application's iOS pods and rebuild the native application. NFC
22
- hardware, platform permissions and host configuration are required; card
23
- operations cannot be validated through a JavaScript-only development session.
44
+ Install the native peer packages this package links as well:
45
+
46
+ ```sh
47
+ yarn add @onekeyfe/react-native-native-logger
48
+ ```
49
+
50
+ The package ships native code and changes the TurboModule ABI, so install the
51
+ application's iOS pods and rebuild the native binary; a JavaScript-only update
52
+ cannot add it.
53
+
54
+ ### iOS
55
+
56
+ Add `NFCReaderUsageDescription` to `Info.plist` and enable the Near Field
57
+ Communication Tag Reading capability (the reader-session entitlement) for the
58
+ app target. The package compiles its SDK sources through CocoaPods.
59
+
60
+ ### Android
61
+
62
+ The host application declares `<uses-permission android:name="android.permission.NFC" />`
63
+ and an NFC-capable device is required. The package builds its JNI library from
64
+ the same recovered sources with CMake.
65
+
66
+ NFC hardware, permissions and host configuration cannot be exercised from a
67
+ JavaScript-only development session.
24
68
 
25
69
  ## Usage
26
70
 
27
71
  ```ts
28
72
  import onekeyLite from '@onekeyfe/react-native-lite-card';
29
73
 
30
- const result = await onekeyLite.checkNFCPermission();
31
- if (result.error) {
32
- // Handle the native error code and message in the application's NFC flow.
33
- } else {
34
- const permissionAvailable = result.data;
74
+ const subscription = onekeyLite.addConnectListener(({ code, message }) => {
75
+ // Render the native NFC prompt state in the app's sheet.
76
+ });
77
+
78
+ const permission = await onekeyLite.checkNFCPermission();
79
+ if (permission.error) {
80
+ // Compare permission.error.code against CardErrors.
81
+ } else if (permission.data) {
82
+ const { error, data: cardInfo } = await onekeyLite.getLiteInfo();
83
+ if (!error && cardInfo) {
84
+ // cardInfo.serialNum / hasBackup / isNewCard / pinRetryCount
85
+ }
35
86
  }
87
+
88
+ subscription.remove(); // when the owner finishes
36
89
  ```
37
90
 
91
+ Never log mnemonics or PINs.
92
+
38
93
  ## API
39
94
 
40
- - `getLiteInfo()` returns card information including serial number, backup
41
- state, new-card status and remaining PIN retries.
42
- - `setMnemonic(mnemonic, pwd, overwrite)` and `getMnemonicWithPin(pwd)` manage
43
- the backup; `overwrite` defaults to `false`.
44
- - `changePin(oldPin, newPin, expectedSerial?)` checks a supplied card serial before
45
- changing the PIN; `reset()` resets the card's state. The identity guard requires
46
- a native rebuild on iOS and Android.
47
- - `addConnectListener(listener)` subscribes to NFC UI events and returns the
48
- native subscription. Keep it and call `remove()` when the owner finishes.
49
- - `cancel()` invokes native cancellation on Android; `intoSetting()` opens
50
- the platform settings path.
51
-
52
- Operation promises resolve an object containing `error`, `data` and `cardInfo`.
53
- Check `error` before consuming data: a resolved promise does not imply a successful
54
- card operation. `CardErrors` provides the exported native error codes. PIN retry
55
- and destructive reset behavior belong in the application's explicit card flow.
56
-
57
- See [src/index.tsx](src/index.tsx) and
58
- [src/NativeReactNativeLiteCard.ts](src/NativeReactNativeLiteCard.ts) for the wrapper
59
- and callback/result types.
60
-
61
- ## Result and subscription ownership
62
-
63
- `PromiseResult<T>` has nullable `error`, `data` and `cardInfo` fields. Inspect
64
- `error.code` against `CardErrors` before using `data`; a missing card-information
65
- field is not an empty successful card. The exported `CardInfo` includes
66
- `hasBackup`, `isNewCard`, `serialNum` and `pinRetryCount`.
67
-
68
- `addAccordListener()` also returns a native event subscription. Remove returned
69
- subscriptions explicitly: the current `removeConnectListeners()` wrapper is
70
- empty and is not a substitute for a subscription's `remove()` method.
71
- Keep mnemonic and PIN values out of diagnostic messages and event logs.
95
+ | Method | Result | Platforms | Description |
96
+ | --- | --- | :-: | --- |
97
+ | `getLiteInfo()` | `Promise<PromiseResult<CardInfo>>` | iOS, Android | Reads serial, backup, new-card and PIN-retry state. |
98
+ | `checkNFCPermission()` | `Promise<PromiseResult<boolean>>` | iOS, Android | Whether NFC is available and authorized. |
99
+ | `setMnemonic(mnemonic, pwd, overwrite?, expectedSerial?)` | `Promise<PromiseResult<boolean>>` | iOS, Android | Writes the backup; `overwrite` defaults to `false`. |
100
+ | `getMnemonicWithPin(pwd)` | `Promise<PromiseResult<string>>` | iOS, Android | Reads the backup with the card PIN. |
101
+ | `changePin(oldPin, newPin, expectedSerial?)` | `Promise<PromiseResult<boolean>>` | iOS, Android | Changes the PIN, optionally guarded by card serial. |
102
+ | `reset()` | `Promise<PromiseResult<boolean>>` | iOS, Android | Resets the card to its initial state. |
103
+ | `addConnectListener(listener)` | subscription with `remove()` | iOS, Android | NFC connection UI events (`code`, `message`). |
104
+ | `addAccordListener()` | subscription | iOS, Android | Native NFC active-connection event. |
105
+ | `cancel()` | `void` | Android | Cancels the current native operation. |
106
+ | `intoSetting()` | `void` | iOS, Android | Opens platform settings (Android native NFC settings, iOS app settings). |
107
+ | `CardErrors` | enum | iOS, Android | Native error codes (`1000`–`4002`). |
108
+
109
+ `PromiseResult<T>` is `{ error, data, cardInfo }`, each nullable. `CardInfo`
110
+ carries `serialNum`, `isNewCard`, `pinRetryCount` and `hasBackup`
111
+ (`boolean | null`; iOS returns `null` when the state is unknown). PIN and
112
+ destructive-reset rules belong to the application's explicit card flow. See
113
+ [`src/index.tsx`](src/index.tsx) and
114
+ [`src/NativeReactNativeLiteCard.ts`](src/NativeReactNativeLiteCard.ts) for the
115
+ wrapper and result types.
116
+
117
+ ## Platform support
118
+
119
+ | Capability | iOS | Android | Web |
120
+ | --- | :-: | :-: | :-: |
121
+ | Card info and NFC permission check | ✅ | ✅ | — |
122
+ | Mnemonic backup / retrieval | ✅ | ✅ | — |
123
+ | PIN change and card reset | ✅ | ✅ | — |
124
+ | Write identity guard (`expectedSerial`) | ✅ | ✅ | — |
125
+ | NFC connection events | ✅ | ✅ | — |
126
+ | `cancel()` native operation | — | ✅ | — |
127
+
128
+ The package targets iOS and Android only; desktop and web consumers are
129
+ unchanged and receive no native implementation.
130
+
131
+ ## Caveats
132
+
133
+ > [!IMPORTANT]
134
+ > A resolved promise does not mean the card operation succeeded. Inspect
135
+ > `result.error` against `CardErrors` before reading `data`, and treat a null
136
+ > `cardInfo` as an unknown card rather than an empty one.
137
+
138
+ > [!WARNING]
139
+ > Serialize whole card operations. The native GPChannel library owns one
140
+ > process-wide session and SCP03 counter, so interleaved operations across JS
141
+ > runtimes are not safe even though each call is individually guarded.
142
+
143
+ > [!NOTE]
144
+ > `removeConnectListeners()` is an empty wrapper. Keep the subscription returned
145
+ > by `addConnectListener()` and call its `remove()` when the owner finishes.
146
+
147
+ ## References
148
+
149
+ - [Package spec](docs/SPEC.md)
150
+ - [Recovered SDK notes](sdk/README.md)
151
+ - [Example page](../../example/react-native/pages/LiteCardTestPage.tsx)
152
+ - [Changelog](../../CHANGELOG.md)
72
153
 
73
154
  ## License
74
155
 
75
- The React Native wrapper is MIT licensed. Vendored SDK sources retain their
76
- upstream notices and are not relicensed by the wrapper.
156
+ The React Native wrapper is MIT licensed. See [LICENSE](LICENSE). Vendored SDK
157
+ sources retain their upstream notices and are not relicensed by the wrapper.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onekeyfe/react-native-lite-card",
3
- "version": "6.7.0-46",
3
+ "version": "6.7.0-47",
4
4
  "description": "OneKey Lite NFC card operations and connection events for React Native",
5
5
  "main": "./lib/module/index.js",
6
6
  "types": "./lib/typescript/src/index.d.ts",
@@ -87,6 +87,7 @@
87
87
  "typescript": "^5.9.2"
88
88
  },
89
89
  "peerDependencies": {
90
+ "@onekeyfe/react-native-native-logger": "*",
90
91
  "react": "*",
91
92
  "react-native": "*"
92
93
  },