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

package/README.en.md

@@ -1,461 +0,0 @@
-# @ukeyfe/react-native-nfc-litecard
-
-English | [中文](./README.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.
-
-## Features
-
-| Feature | Method | Description |
-|---------|--------|-------------|
-| Check card | `checkCard()` | Detect whether the card is empty or contains data |
-| Read mnemonic | `readMnemonic()` | Read BIP-39 mnemonic (password required) |
-| 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 |
-| 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 data, reset password to "000000" |
-
-## Installation
-
-```bash
-npm install @ukeyfe/react-native-nfc-litecard
-```
-
-### Peer Dependencies
-
-This library requires the following peer dependencies:
-
-```bash
-npm install react-native react-native-nfc-manager
-```
-
-## Quick Start
-
-```typescript
-import {
-  ResultCode,
-  checkCard,
-  readMnemonic,
-  initializeCard,
-  updateCard,
-  updatePassword,
-  writeUserNickname,
-  readUserNickname,
-  resetCard,
-  readMnemonicRetryCount,
-  resetRetryCountTo10,
-} from '@ukeyfe/react-native-nfc-litecard';
-```
-
-## API Reference
-
-### `checkCard(password?, onCardIdentified?)`
-
-Detect card status (empty / has data).
-
-**Without password (quick probe):**
-```typescript
-const result = await checkCard();
-if (result.code === ResultCode.CHECK_EMPTY) {
-  // Empty card – ready to initialize
-} else if (result.code === ResultCode.CHECK_HAS_DATA) {
-  // Has data (or read-protected, cannot determine)
-}
-```
-
-**With password (authenticated deep check, for read-protected cards):**
-```typescript
-const result = await checkCard('password');
-if (result.code === ResultCode.CHECK_EMPTY) {
-  // Empty card – ready to write
-} else if (result.code === ResultCode.CHECK_HAS_DATA) {
-  // Valid mnemonic backup exists, type: result.data?.type
-} else if (result.code === ResultCode.AUTH_WRONG_PASSWORD) {
-  // Wrong password
-}
-```
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `password` | `string` | No | Card protection password. If omitted, the library reads directly (suited for unencrypted cards). If provided, AES authentication runs first, then full data is read and CRC16 is verified (suited for read-protected cards; more accurate). |
-| `onCardIdentified` | `() => void` | No | Called after the NFC session is established; use for UI such as “card detected”. |
-
-**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 |
-
----
-
-### `readMnemonic(password, onCardIdentified?)`
-
-Read the mnemonic (password authentication required). The retry counter is decremented before authentication and reset to 10 after a successful authentication.
-
-```typescript
-const result = await readMnemonic('your-password');
-if (result.success) {
-  console.log('Mnemonic:', result.data?.mnemonic);
-  console.log('Type:', result.data?.type);           // "12 words (128-bit)"
-  console.log('Nickname:', result.data?.nickname);
-  console.log('Retry count:', result.data?.retryCount);
-}
-```
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `password` | `string` | Yes | Card protection password for AES-128 authentication |
-| `onCardIdentified` | `() => void` | No | Called after successful authentication and before reading data; use for UI such as “reading”. |
-
-**Returned `data` fields:**
-| Field | Type | Description |
-|-------|------|-------------|
-| `mnemonic` | `string` | BIP-39 mnemonic (e.g. `"abandon abandon ... about"`) |
-| `type` | `string` | Mnemonic type (e.g. `"12 words (128-bit)"`, `"24 words (256-bit)"`) |
-| `entropyHex` | `string` | Entropy as a hexadecimal string |
-| `rawBytes` | `string` | Hex string of raw on-card data (type + entropy) |
-| `nickname` | `string` | User nickname if set on the card |
-| `retryCount` | `number` | Retry count after successful authentication (normally 10) |
-
----
-
-### `initializeCard(mnemonic, password, 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.
-
-```typescript
-const result = await initializeCard(
-  'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
-  'your-password'
-);
-if (result.code === ResultCode.INIT_SUCCESS) {
-  console.log('Initialization successful');
-}
-```
-
-**Parameters:**
-| 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”. |
-
----
-
-### `updateCard(oldPassword, newPassword, newMnemonic, onCardIdentified?, options?)`
-
-Update the card: authenticate with the old password, then write the new mnemonic and new password. The retry counter is decremented automatically before authentication.
-
-```typescript
-const result = await updateCard('old-password', 'new-password', 'new mnemonic words ...');
-if (result.code === ResultCode.WRITE_SUCCESS) {
-  console.log('Update successful');
-}
-```
-
-**Pre-check for existing backup:**
-
-```typescript
-const result = await updateCard('old-password', 'new-password', 'mnemonic ...', undefined, {
-  precheckExistingMnemonic: true,
-});
-if (result.code === ResultCode.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) {
-  console.log('Write successful');
-}
-```
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `oldPassword` | `string` | Yes | Current card password for AES authentication |
-| `newPassword` | `string` | Yes | New password; the card will be protected with this password after the write |
-| `newMnemonic` | `string` | Yes | New BIP-39 mnemonic (12/15/18/21/24 words) |
-| `onCardIdentified` | `() => void` | No | Called after successful authentication; use for UI such as “writing”. |
-| `options.precheckExistingMnemonic` | `boolean` | No | When `true`, after authentication the library reads card data and verifies CRC16. If a valid mnemonic already exists, returns `PRECHECK_HAS_BACKUP` and does not write. |
-
----
-
-### `updatePassword(oldPassword, newPassword, onCardIdentified?)`
-
-Change the password only; mnemonic data on the card is unchanged. The retry counter is decremented automatically before authentication.
-
-```typescript
-const result = await updatePassword('old-password', 'new-password');
-if (result.code === ResultCode.UPDATE_PASSWORD_SUCCESS) {
-  console.log('Password updated');
-}
-```
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `oldPassword` | `string` | Yes | Current card password for AES authentication |
-| `newPassword` | `string` | Yes | New password; the card will use this password after the change |
-| `onCardIdentified` | `() => void` | No | Called after successful authentication |
-
----
-
-### `writeUserNickname(password, nickname, onCardIdentified?)`
-
-Write a user nickname to the card. The nickname is UTF-8 encoded, max 12 bytes (longer input is truncated).
-
-```typescript
-const result = await writeUserNickname('your-password', 'MyCard');
-if (result.code === ResultCode.WRITE_NICKNAME_SUCCESS) {
-  console.log('Nickname written');
-}
-```
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `password` | `string` | Yes | Card protection password for AES authentication |
-| `nickname` | `string` | Yes | User nickname; UTF-8 max 12 bytes (roughly 4 CJK characters or 12 Latin letters) |
-| `onCardIdentified` | `() => void` | No | Called after successful authentication |
-
----
-
-### `readUserNickname(password?, onCardIdentified?)`
-
-Read the user nickname from the card.
-
-```typescript
-const result = await readUserNickname('your-password');
-if (result.success) {
-  console.log('Nickname:', result.data?.nickname);
-}
-```
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `password` | `string` | No | Card password. Required if read protection is enabled (`PROT=1`); otherwise optional. |
-| `onCardIdentified` | `() => void` | No | Called after successful authentication |
-
----
-
-### `resetCard(password?, onCardIdentified?)`
-
-Reset the card: wipe all user data (mnemonic, nickname), set password to `"000000"`, and disable read/write protection.
-
-```typescript
-const result = await resetCard('your-password');
-if (result.code === ResultCode.RESET_SUCCESS) {
-  console.log('Reset successful');
-}
-```
-
-> ⚠️ This operation is irreversible; mnemonic data on the card is permanently erased.
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `password` | `string` | No | Current card password. Required if the card is protected; otherwise optional. The retry counter is decremented automatically before authentication. |
-| `onCardIdentified` | `() => void` | No | Called after successful authentication |
-
----
-
-### `readMnemonicRetryCount(onCardIdentified?)`
-
-Read the PIN retry counter on the card. No password authentication is required (the counter page is outside the protected area).
-
-```typescript
-const result = await readMnemonicRetryCount();
-if (result.success) {
-  console.log('Remaining retries:', result.data?.retryCount);
-}
-```
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `onCardIdentified` | `() => void` | No | Called after the NFC session is established |
-
----
-
-### `resetRetryCountTo10(onCardIdentified?)`
-
-Reset the PIN retry counter to its default value (10). No password authentication is required.
-
-```typescript
-const result = await resetRetryCountTo10();
-```
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `onCardIdentified` | `() => void` | No | Called after the NFC session is established |
-
----
-
-### NFC Lock Management
-
-For app-level NFC session lifecycle management:
-
-```typescript
-import {
-  isNfcOperationLocked,
-  releaseNfcOperationLock,
-  markNfcOperationCancelledByCleanup,
-  consumeNfcOperationCancelledByCleanup,
-} from '@ukeyfe/react-native-nfc-litecard';
-```
-
-| Method | Description |
-|--------|-------------|
-| `isNfcOperationLocked()` | Check if the NFC operation lock is held |
-| `releaseNfcOperationLock()` | Force-release the lock (use on page unmount) |
-| `markNfcOperationCancelledByCleanup()` | Mark current operation as interrupted by cleanup |
-| `consumeNfcOperationCancelledByCleanup()` | Consume the cleanup flag (returns whether it was set) |
-
-## NfcResult Structure
-
-All APIs return a unified `NfcResult`:
-
-```typescript
-interface NfcResult {
-  code: number;       // Status code – compare against ResultCode
-  success: boolean;   // Whether the operation succeeded
-  data?: {            // Optional data, only present for some operations
-    mnemonic?: string;
-    type?: string;
-    entropyHex?: string;
-    rawBytes?: string;
-    nickname?: string;
-    retryCount?: number;
-    aesKeyHex?: string;
-    crc16?: number;
-  };
-}
-```
-
-## Error Handling Example
-
-```typescript
-import { ResultCode, readMnemonic } from '@ukeyfe/react-native-nfc-litecard';
-
-const result = await readMnemonic('password');
-
-switch (result.code) {
-  case ResultCode.READ_SUCCESS:
-    console.log('Read successful:', result.data?.mnemonic);
-    break;
-  case ResultCode.AUTH_WRONG_PASSWORD:
-    alert('Wrong password');
-    break;
-  case ResultCode.NFC_CONNECT_FAILED:
-    alert('NFC connection failed, please re-tap the card');
-    break;
-  case ResultCode.NFC_USER_CANCELED:
-    // iOS user cancelled – handle silently
-    break;
-  case ResultCode.READ_TIMEOUT:
-    alert('Read timeout – remove and re-tap the card');
-    break;
-  case ResultCode.RETRY_COUNT_EXHAUSTED:
-    alert('Retry count exhausted – card is locked');
-    break;
-  default:
-    alert('Operation failed');
-}
-```
-
-## Result Codes
-
-### Success Codes
-
-| Constant | Value | Description |
-|----------|-------|-------------|
-| `READ_SUCCESS` | 10102 | Mnemonic read successful |
-| `READ_NICKNAME_SUCCESS` | 10103 | Nickname read successful |
-| `CHECK_EMPTY` | 10104 | Empty card |
-| `CHECK_HAS_DATA` | 10105 | Card has data |
-| `READ_RETRY_COUNT_SUCCESS` | 10106 | Retry count read successful |
-| `INIT_SUCCESS` | 10201 | Initialization successful |
-| `WRITE_SUCCESS` | 10203 | Write/update successful |
-| `UPDATE_PASSWORD_SUCCESS` | 10204 | Password change successful |
-| `WRITE_NICKNAME_SUCCESS` | 10205 | Nickname written |
-| `RESET_SUCCESS` | 10206 | Card reset successful |
-| `PRECHECK_HAS_BACKUP` | 10207 | Card already has a valid backup; write was skipped |
-
-### Error Codes
-
-| Constant | Value | Description |
-|----------|-------|-------------|
-| `NFC_CONNECT_FAILED` | 40001 | NFC connection failed |
-| `AUTH_WRONG_PASSWORD` | 40002 | Wrong password |
-| `AUTH_INVALID_RESPONSE` | 40003 | Invalid authentication response |
-| `AUTH_VERIFY_FAILED` | 40004 | Authentication verification failed |
-| `READ_FAILED` | 40005 | Read failed |
-| `WRITE_FAILED` | 40006 | Write failed |
-| `INVALID_MNEMONIC` | 40007 | Invalid mnemonic |
-| `UNSUPPORTED_MNEMONIC_LENGTH` | 40008 | Unsupported mnemonic length |
-| `INVALID_CARD_DATA` | 40009 | Invalid card data |
-| `UNKNOWN_ERROR` | 40010 | Unknown error |
-| `NFC_USER_CANCELED` | 40011 | User cancelled NFC scan (iOS) |
-| `READ_TIMEOUT` | 40012 | Read timeout |
-| `NFC_LOCK_TIMEOUT` | 40013 | NFC lock timeout |
-| `CRC16_CHECK_FAILED` | 40014 | CRC16 check failed |
-| `RETRY_COUNT_EXHAUSTED` | 40015 | PIN retry count exhausted, card locked |
-
-## Storage Format
-
-The card stores BIP-39 mnemonics using entropy compression:
-
-```
-[type 1B] [entropy 16-32B] [CRC16 2B]
-```
-
-| Type | Mnemonic Length | Entropy Size |
-|------|----------------|--------------|
-| 0x01 | 12 words | 16 bytes (128-bit) |
-| 0x02 | 15 words | 20 bytes (160-bit) |
-| 0x03 | 18 words | 24 bytes (192-bit) |
-| 0x04 | 21 words | 28 bytes (224-bit) |
-| 0x05 | 24 words | 32 bytes (256-bit) |
-
-## Security
-
-- **AES-128 hardware-level mutual authentication** (3-pass)
-- **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
-- **Secure random**: authentication uses `crypto.getRandomValues()` (requires Hermes ≥ 0.72 or `react-native-get-random-values` polyfill)
-
-## Project Structure
-
-```
-src/
-├── index.ts        # Public API exports
-├── constants.ts    # Shared constants (page addresses, NFC commands, mnemonic types)
-├── types.ts        # Unified ResultCode, 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
-├── reader.ts       # Reader API
-└── writer.ts       # Writer API
-```
-
-## Platform Support
-
-| Platform | Technology | Requirements |
-|----------|-----------|--------------|
-| iOS | MifareIOS | iPhone 7 or later |
-| Android | NfcA | NFC-capable device |
-
-## License
-
-MIT