@ukeyfe/react-native-nfc-litecard 1.0.0

package/README.en.md

@@ -0,0 +1,390 @@
+# @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(onCardIdentified?)`
+
+Detect card status (empty / has data).
+
+```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 – need password to read or update
+}
+```
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `onCardIdentified` | `() => void` | No | Callback after card is identified |
+
+**Result codes:**
+| Code | Meaning |
+|------|---------|
+| `ResultCode.CHECK_EMPTY` (10104) | Empty card |
+| `ResultCode.CHECK_HAS_DATA` (10105) | Card has data |
+| `ResultCode.NFC_CONNECT_FAILED` (40001) | NFC connection failed |
+
+---
+
+### `readMnemonic(password, onCardIdentified?)`
+
+Read mnemonic from a password-protected card.
+
+```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 |
+| `onCardIdentified` | `() => void` | No | Callback after successful authentication |
+
+**Returned `data` fields:**
+| Field | Description |
+|-------|-------------|
+| `mnemonic` | BIP-39 mnemonic phrase |
+| `type` | Mnemonic type (e.g. "12 words (128-bit)") |
+| `entropyHex` | Entropy as hex string |
+| `rawBytes` | Raw data as hex string |
+| `nickname` | User nickname (if set) |
+| `retryCount` | Retry count after successful reset |
+
+---
+
+### `initializeCard(mnemonic, password, onCardIdentified?)`
+
+Initialize a blank card: write mnemonic + set password protection.
+
+```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 (12/15/18/21/24 words) |
+| `password` | `string` | Yes | Protection password to set |
+| `onCardIdentified` | `() => void` | No | Callback before writing begins |
+
+---
+
+### `updateCard(oldPassword, newPassword, newMnemonic, onCardIdentified?)`
+
+Update card: authenticate with old password, then write new mnemonic + new password.
+
+```typescript
+const result = await updateCard('old-password', 'new-password', 'new mnemonic words ...');
+if (result.code === ResultCode.WRITE_SUCCESS) {
+  console.log('Update successful');
+}
+```
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `oldPassword` | `string` | Yes | Current password |
+| `newPassword` | `string` | Yes | New password |
+| `newMnemonic` | `string` | Yes | New mnemonic |
+| `onCardIdentified` | `() => void` | No | Callback after successful authentication |
+
+---
+
+### `updatePassword(oldPassword, newPassword, onCardIdentified?)`
+
+Change password only, without modifying mnemonic data.
+
+```typescript
+const result = await updatePassword('old-password', 'new-password');
+if (result.code === ResultCode.UPDATE_PASSWORD_SUCCESS) {
+  console.log('Password updated');
+}
+```
+
+---
+
+### `writeUserNickname(password, nickname)`
+
+Write a user nickname to the card (max 12 bytes, UTF-8 encoded).
+
+```typescript
+const result = await writeUserNickname('your-password', 'MyCard');
+if (result.code === ResultCode.WRITE_NICKNAME_SUCCESS) {
+  console.log('Nickname written');
+}
+```
+
+---
+
+### `readUserNickname(password?)`
+
+Read user nickname from the card. Supply password if read-protection is enabled.
+
+```typescript
+const result = await readUserNickname('your-password');
+if (result.success) {
+  console.log('Nickname:', result.data?.nickname);
+}
+```
+
+---
+
+### `resetCard(password?, onCardIdentified?)`
+
+Reset card: wipe all user data, set password to `"000000"`.
+
+```typescript
+const result = await resetCard('your-password');
+if (result.code === ResultCode.RESET_SUCCESS) {
+  console.log('Reset successful');
+}
+```
+
+> ⚠️ This operation is irreversible. Use with caution.
+
+---
+
+### `readMnemonicRetryCount()`
+
+Read the current PIN retry counter value.
+
+```typescript
+const result = await readMnemonicRetryCount();
+if (result.success) {
+  console.log('Remaining retries:', result.data?.retryCount);
+}
+```
+
+---
+
+### `resetRetryCountTo10()`
+
+Reset the PIN retry counter to its default value (10).
+
+```typescript
+const result = await resetRetryCountTo10();
+```
+
+---
+
+### 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;
+  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 |
+
+### 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 |
+
+## 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)
+
+## Platform Support
+
+| Platform | Technology | Requirements |
+|----------|-----------|--------------|
+| iOS | MifareIOS | iPhone 7 or later |
+| Android | NfcA | NFC-capable device |
+
+## 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
+├── nfc-core.ts     # NFC lock, transceive, authentication, retry counter
+├── reader.ts       # Reader API
+└── writer.ts       # Writer API
+```
+
+## License
+
+MIT