@onekeyfe/react-native-lite-card 6.7.0-alpha.475 → 6.8.0-2
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.
package/README.md
CHANGED
|
@@ -1,16 +1,39 @@
|
|
|
1
|
-
|
|
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
|
-
|
|
3
|
+
# @onekeyfe/react-native-lite-card
|
|
9
4
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
[
|
|
5
|
+
**OneKey Lite NFC card operations — inspect, back up and restore, change the PIN — from React Native.**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/@onekeyfe/react-native-lite-card)
|
|
8
|
+
[](LICENSE)
|
|
9
|
+

|
|
10
|
+

|
|
11
|
+

|
|
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
|
|
22
|
-
|
|
23
|
-
|
|
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
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
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
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
[src/
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
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
|
|
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.
|
|
@@ -4,7 +4,7 @@ export type CallbackError = {
|
|
|
4
4
|
message: string | null;
|
|
5
5
|
} | null;
|
|
6
6
|
export type CardInfo = {
|
|
7
|
-
hasBackup: boolean;
|
|
7
|
+
hasBackup: boolean | null;
|
|
8
8
|
isNewCard: boolean;
|
|
9
9
|
serialNum: string;
|
|
10
10
|
pinRetryCount: number;
|
|
@@ -39,7 +39,7 @@ export declare enum CardErrors {
|
|
|
39
39
|
NotInitializedError = 4002
|
|
40
40
|
}
|
|
41
41
|
type KeyValuePair = {
|
|
42
|
-
code:
|
|
42
|
+
code: number;
|
|
43
43
|
message: string;
|
|
44
44
|
};
|
|
45
45
|
export interface Spec extends TurboModule {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@onekeyfe/react-native-lite-card",
|
|
3
|
-
"version": "6.
|
|
3
|
+
"version": "6.8.0-2",
|
|
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
|
},
|
|
@@ -7,7 +7,7 @@ import {
|
|
|
7
7
|
export type CallbackError = { code: number; message: string | null } | null;
|
|
8
8
|
|
|
9
9
|
export type CardInfo = {
|
|
10
|
-
hasBackup: boolean;
|
|
10
|
+
hasBackup: boolean | null;
|
|
11
11
|
isNewCard: boolean;
|
|
12
12
|
serialNum: string;
|
|
13
13
|
pinRetryCount: number;
|
|
@@ -49,7 +49,7 @@ export enum CardErrors {
|
|
|
49
49
|
}
|
|
50
50
|
|
|
51
51
|
type KeyValuePair = {
|
|
52
|
-
code:
|
|
52
|
+
code: number;
|
|
53
53
|
message: string;
|
|
54
54
|
};
|
|
55
55
|
|