@ukeyfe/react-native-nfc-litecard 1.0.2 → 1.0.3

package/README.md

@@ -4,7 +4,7 @@ English | [中文](./README.zh.md)
 
 React Native NFC read/write library for **MIFARE Ultralight AES** (MF0AES(H)20), designed for LiteCard mnemonic storage.
 
-> **Design principle**: The library only returns status codes (`code`) and data (`data`). It does **not** provide user-facing messages. The caller should map `ResultCode` to their own localised strings.
+> **Design principle**: The library only returns status codes (`code`) and data (`data`). It does **not** provide user-facing messages. The caller should map `NfcStatusCode` to their own localised strings.
 
 ## Features
 
@@ -15,11 +15,13 @@ React Native NFC read/write library for **MIFARE Ultralight AES** (MF0AES(H)20),
 | Read nickname | `readUserNickname()` | Read user nickname from card |
 | Read retry count | `readMnemonicRetryCount()` | Read PIN retry counter |
 | Reset retry count | `resetRetryCountTo10()` | Reset PIN retry counter to default (10) |
-| Initialize card | `initializeCard()` | Write mnemonic + set password on a blank card |
+| Initialize card | `initializeCard()` | Authenticate with default password, write mnemonic + set new password |
 | Update card | `updateCard()` | Update mnemonic & password (old password required) |
 | Change password | `updatePassword()` | Change password only (old password required) |
 | Write nickname | `writeUserNickname()` | Write user nickname to card |
-| Reset card | `resetCard()` | Wipe mnemonic data, set a new password |
+| Reset card | `resetCard()` | Wipe mnemonic data, set a new password, keep protection enabled |
+| Card version | `getCardVersion()` | Read card product version info (no auth required) |
+| Originality check | `readOriginality()` | Read ECC originality signature for NXP authenticity verification |
 
 ## Installation
 
@@ -39,7 +41,7 @@ npm install react-native react-native-nfc-manager
 
 ```typescript
 import {
-  ResultCode,
+  NfcStatusCode,
   checkCard,
   readMnemonic,
   initializeCard,
@@ -50,6 +52,8 @@ import {
   resetCard,
   readMnemonicRetryCount,
   resetRetryCountTo10,
+  getCardVersion,
+  readOriginality,
 } from '@ukeyfe/react-native-nfc-litecard';
 ```
 
@@ -62,9 +66,9 @@ Detect card status (empty / has data).
 **Without password (quick probe):**
 ```typescript
 const result = await checkCard();
-if (result.code === ResultCode.CHECK_EMPTY) {
+if (result.code === NfcStatusCode.CHECK_EMPTY) {
   // Empty card – ready to initialize
-} else if (result.code === ResultCode.CHECK_HAS_DATA) {
+} else if (result.code === NfcStatusCode.CHECK_HAS_DATA) {
   // Has data (or read-protected, cannot determine)
 }
 ```
@@ -72,11 +76,11 @@ if (result.code === ResultCode.CHECK_EMPTY) {
 **With password (authenticated deep check, for read-protected cards):**
 ```typescript
 const result = await checkCard('password');
-if (result.code === ResultCode.CHECK_EMPTY) {
+if (result.code === NfcStatusCode.CHECK_EMPTY) {
   // Empty card – ready to write
-} else if (result.code === ResultCode.CHECK_HAS_DATA) {
+} else if (result.code === NfcStatusCode.CHECK_HAS_DATA) {
   // Valid mnemonic backup exists, type: result.data?.type
-} else if (result.code === ResultCode.AUTH_WRONG_PASSWORD) {
+} else if (result.code === NfcStatusCode.AUTH_WRONG_PASSWORD) {
   // Wrong password
 }
 ```
@@ -90,10 +94,10 @@ if (result.code === ResultCode.CHECK_EMPTY) {
 **Result codes:**
 | Code | Meaning |
 |------|---------|
-| `ResultCode.CHECK_EMPTY` (10104) | Empty card – no mnemonic data |
-| `ResultCode.CHECK_HAS_DATA` (10105) | Card has data. When a password is supplied, `data.type` contains the mnemonic type (e.g. `"12 words (128-bit)"`). |
-| `ResultCode.AUTH_WRONG_PASSWORD` (40002) | Wrong password (only possible when a password is provided) |
-| `ResultCode.NFC_CONNECT_FAILED` (40001) | NFC connection failed – card not tapped or device unsupported |
+| `NfcStatusCode.CHECK_EMPTY` (10104) | Empty card – no mnemonic data |
+| `NfcStatusCode.CHECK_HAS_DATA` (10105) | Card has data. When a password is supplied, `data.type` contains the mnemonic type (e.g. `"12 words (128-bit)"`). |
+| `NfcStatusCode.AUTH_WRONG_PASSWORD` (40002) | Wrong password (only possible when a password is provided) |
+| `NfcStatusCode.NFC_CONNECT_FAILED` (40001) | NFC connection failed – card not tapped or device unsupported |
 
 ---
 
@@ -129,16 +133,17 @@ if (result.success) {
 
 ---
 
-### `initializeCard(mnemonic, password, onCardIdentified?)`
+### `initializeCard(mnemonic, newPassword, defaultPassword, onCardIdentified?)`
 
-Initialize a blank card: convert the mnemonic to BIP-39 entropy, write it to the card, enable AES password protection, and require read/write authentication.
+Initialize a card: authenticate with the factory-default password, write the mnemonic, and set a new password. The card must already have AES protection enabled (factory default).
 
 ```typescript
 const result = await initializeCard(
   'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
-  'your-password'
+  'your-password',
+  '000000'  // factory default password
 );
-if (result.code === ResultCode.INIT_SUCCESS) {
+if (result.code === NfcStatusCode.INIT_SUCCESS) {
   console.log('Initialization successful');
 }
 ```
@@ -147,8 +152,9 @@ if (result.code === ResultCode.INIT_SUCCESS) {
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `mnemonic` | `string` | Yes | BIP-39 mnemonic; supports 12/15/18/21/24 words. The library converts to entropy + CRC16 and writes to the card. |
-| `password` | `string` | Yes | Protection password to set; used to derive the AES-128 key written to the card. |
-| `onCardIdentified` | `() => void` | No | Called after NFC connection is established and before writing begins; use for UI such as "writing". |
+| `newPassword` | `string` | Yes | New protection password; used to derive the AES-128 key written to the card. |
+| `defaultPassword` | `string` | Yes | Current (factory-default) password on the card for authentication. |
+| `onCardIdentified` | `() => void` | No | Called after successful authentication and before writing begins; use for UI such as "writing". |
 
 ---
 
@@ -158,7 +164,7 @@ Update the card: authenticate with the old password, then write the new mnemonic
 
 ```typescript
 const result = await updateCard('old-password', 'new-password', 'new mnemonic words ...');
-if (result.code === ResultCode.WRITE_SUCCESS) {
+if (result.code === NfcStatusCode.WRITE_SUCCESS) {
   console.log('Update successful');
 }
 ```
@@ -169,10 +175,10 @@ if (result.code === ResultCode.WRITE_SUCCESS) {
 const result = await updateCard('old-password', 'new-password', 'mnemonic ...', undefined, {
   precheckExistingMnemonic: true,
 });
-if (result.code === ResultCode.PRECHECK_HAS_BACKUP) {
+if (result.code === NfcStatusCode.PRECHECK_HAS_BACKUP) {
   // Card already has a valid mnemonic backup; write was skipped
   console.log('Backup exists, type:', result.data?.type);
-} else if (result.code === ResultCode.WRITE_SUCCESS) {
+} else if (result.code === NfcStatusCode.WRITE_SUCCESS) {
   console.log('Write successful');
 }
 ```
@@ -194,7 +200,7 @@ Change the password only; mnemonic data on the card is unchanged. The retry coun
 
 ```typescript
 const result = await updatePassword('old-password', 'new-password');
-if (result.code === ResultCode.UPDATE_PASSWORD_SUCCESS) {
+if (result.code === NfcStatusCode.UPDATE_PASSWORD_SUCCESS) {
   console.log('Password updated');
 }
 ```
@@ -214,7 +220,7 @@ Write a user nickname to the card. The nickname is UTF-8 encoded, max 12 bytes (
 
 ```typescript
 const result = await writeUserNickname('your-password', 'MyCard');
-if (result.code === ResultCode.WRITE_NICKNAME_SUCCESS) {
+if (result.code === NfcStatusCode.WRITE_NICKNAME_SUCCESS) {
   console.log('Nickname written');
 }
 ```
@@ -253,7 +259,7 @@ Reset the card: wipe mnemonic data, set a new password, and disable read/write p
 
 ```typescript
 const result = await resetCard('old-password', 'new-password');
-if (result.code === ResultCode.RESET_SUCCESS) {
+if (result.code === NfcStatusCode.RESET_SUCCESS) {
   console.log('Reset successful');
 }
 ```
@@ -302,6 +308,34 @@ const result = await resetRetryCountTo10();
 
 ---
 
+### `getCardVersion(onCardIdentified?)`
+
+Read card product version info. No authentication required.
+
+```typescript
+const result = await getCardVersion();
+if (result.success) {
+  console.log('Vendor:', result.data?.version?.vendorId);   // 0x04 = NXP
+  console.log('Type:', result.data?.version?.productType);   // 0x03 = Ultralight
+  console.log('Version:', result.data?.version?.majorVersion); // 0x04 = AES
+}
+```
+
+---
+
+### `readOriginality(onCardIdentified?)`
+
+Read the ECC originality signature to verify the card is a genuine NXP product. No authentication required.
+
+```typescript
+const result = await readOriginality();
+if (result.success) {
+  console.log('Signature:', result.data?.signature); // 96-char hex string
+}
+```
+
+---
+
 ### NFC Lock Management
 
 For app-level NFC session lifecycle management:
@@ -328,7 +362,7 @@ All APIs return a unified `NfcResult`:
 
 ```typescript
 interface NfcResult {
-  code: number;       // Status code – compare against ResultCode
+  code: number;       // Status code – compare against NfcStatusCode
   success: boolean;   // Whether the operation succeeded
   data?: {            // Optional data, only present for some operations
     mnemonic?: string;
@@ -346,27 +380,27 @@ interface NfcResult {
 ## Error Handling Example
 
 ```typescript
-import { ResultCode, readMnemonic } from '@ukeyfe/react-native-nfc-litecard';
+import { NfcStatusCode, readMnemonic } from '@ukeyfe/react-native-nfc-litecard';
 
 const result = await readMnemonic('password');
 
 switch (result.code) {
-  case ResultCode.READ_SUCCESS:
+  case NfcStatusCode.READ_SUCCESS:
     console.log('Read successful:', result.data?.mnemonic);
     break;
-  case ResultCode.AUTH_WRONG_PASSWORD:
+  case NfcStatusCode.AUTH_WRONG_PASSWORD:
     alert('Wrong password');
     break;
-  case ResultCode.NFC_CONNECT_FAILED:
+  case NfcStatusCode.NFC_CONNECT_FAILED:
     alert('NFC connection failed, please re-tap the card');
     break;
-  case ResultCode.NFC_USER_CANCELED:
+  case NfcStatusCode.NFC_USER_CANCELED:
     // iOS user cancelled – handle silently
     break;
-  case ResultCode.READ_TIMEOUT:
+  case NfcStatusCode.READ_TIMEOUT:
     alert('Read timeout – remove and re-tap the card');
     break;
-  case ResultCode.RETRY_COUNT_EXHAUSTED:
+  case NfcStatusCode.RETRY_COUNT_EXHAUSTED:
     alert('Retry count exhausted – card is locked');
     break;
   default:
@@ -385,6 +419,8 @@ switch (result.code) {
 | `CHECK_EMPTY` | 10104 | Empty card |
 | `CHECK_HAS_DATA` | 10105 | Card has data |
 | `READ_RETRY_COUNT_SUCCESS` | 10106 | Retry count read successful |
+| `GET_VERSION_SUCCESS` | 10107 | Card version read successful |
+| `READ_SIG_SUCCESS` | 10108 | Originality signature read successful |
 | `INIT_SUCCESS` | 10201 | Initialization successful |
 | `WRITE_SUCCESS` | 10203 | Write/update successful |
 | `UPDATE_PASSWORD_SUCCESS` | 10204 | Password change successful |
@@ -434,6 +470,7 @@ The card stores BIP-39 mnemonics using entropy compression:
 - **SHA-256 key derivation**: password → SHA-256 → first 16 bytes as AES key
 - **CRC16-Modbus checksum**: data integrity verification
 - **PIN retry counter**: auto-decrements on wrong password, resets to 10 on success
+- **CMAC secure messaging**: all commands after authentication are protected with AES-CMAC (NIST 800-38B) to prevent tampering
 - **Secure random**: authentication uses `crypto.getRandomValues()` (requires Hermes ≥ 0.72 or `react-native-get-random-values` polyfill)
 
 ## Project Structure
@@ -442,7 +479,7 @@ The card stores BIP-39 mnemonics using entropy compression:
 src/
 ├── index.ts        # Public API exports
 ├── constants.ts    # Shared constants (page addresses, NFC commands, mnemonic types)
-├── types.ts        # Unified ResultCode, NfcResult interface, error mapping
+├── types.ts        # Unified NfcStatusCode, NfcResult interface, error mapping
 ├── crypto.ts       # AES encrypt/decrypt, key derivation, secure random
 ├── utils.ts        # CRC16, hex conversion, array utilities
 ├── nfc-core.ts     # NFC lock, transceive, authentication, retry counter