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

package/README.md

@@ -1,41 +1,41 @@
 # @ukeyfe/react-native-nfc-litecard
 
-[English](./README.en.md) | 中文
+English | [中文](./README.zh.md)
 
-基于 **MIFARE Ultralight AES** (MF0AES(H)20) 的 React Native NFC 读写库，用于 LiteCard 助记词存储。
+React Native NFC read/write library for **MIFARE Ultralight AES** (MF0AES(H)20), designed for LiteCard mnemonic storage.
 
-> **设计原则**：库只返回状态码 (`code`) 和数据 (`data`)，**不提供用户提示文案**。调用方根据 `ResultCode` 自行处理本地化提示。
+> **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
 
-| 功能 | 方法 | 说明 |
-|------|------|------|
-| 检测卡片 | `checkCard()` | 判断卡片是空卡还是已有数据 |
-| 读取助记词 | `readMnemonic()` | 密码认证后读取 BIP-39 助记词 |
-| 读取昵称 | `readUserNickname()` | 读取卡片上的用户昵称 |
-| 读取重试次数 | `readMnemonicRetryCount()` | 读取 PIN 重试计数器 |
-| 重置重试次数 | `resetRetryCountTo10()` | 重置 PIN 重试计数器为默认值 10 |
-| 初始化卡片 | `initializeCard()` | 向空卡写入助记词并设置密码保护 |
-| 更新卡片 | `updateCard()` | 更新助记词和密码（需要旧密码） |
-| 修改密码 | `updatePassword()` | 仅修改密码（需要旧密码） |
-| 写入昵称 | `writeUserNickname()` | 写入用户昵称到卡片 |
-| 重置卡片 | `resetCard()` | 清空数据，密码重置为 "000000" |
+| 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 mnemonic data, set a new password |
 
-## 安装
+## Installation
 
 ```bash
 npm install @ukeyfe/react-native-nfc-litecard
 ```
 
-### 前置依赖
+### Peer Dependencies
 
-本库需要以下 peer dependencies，请确保项目中已安装：
+This library requires the following peer dependencies:
 
 ```bash
 npm install react-native react-native-nfc-manager
 ```
 
-## 快速上手
+## Quick Start
 
 ```typescript
 import {
@@ -53,70 +53,85 @@ import {
 } from '@ukeyfe/react-native-nfc-litecard';
 ```
 
-## API 文档
+## API Reference
 
-### `checkCard(onCardIdentified?)`
+### `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)
 }
 ```
 
-**参数：**
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `onCardIdentified` | `() => void` | 否 | 卡片识别成功后的回调 |
+**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
+}
+```
 
-**返回值 (`NfcResult`)：**
-| code | 含义 |
-|------|------|
-| `ResultCode.CHECK_EMPTY` (10104) | 空卡 |
-| `ResultCode.CHECK_HAS_DATA` (10105) | 有数据 |
-| `ResultCode.NFC_CONNECT_FAILED` (40001) | NFC 连接失败 |
+**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('助记词:', result.data?.mnemonic);
-  console.log('类型:', result.data?.type);           // "12 words (128-bit)"
-  console.log('昵称:', result.data?.nickname);
-  console.log('剩余重试:', result.data?.retryCount);
+  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);
 }
 ```
 
-**参数：**
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `password` | `string` | 是 | 卡片保护密码 |
-| `onCardIdentified` | `() => void` | 否 | 认证成功后的回调 |
-
-**返回 `data` 字段：**
-| 字段 | 说明 |
-|------|------|
-| `mnemonic` | BIP-39 助记词 |
-| `type` | 助记词类型（如 "12 words (128-bit)"） |
-| `entropyHex` | 熵的十六进制 |
-| `rawBytes` | 原始数据十六进制 |
-| `nickname` | 用户昵称（如果有） |
-| `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(
@@ -124,120 +139,172 @@ const result = await initializeCard(
   'your-password'
 );
 if (result.code === ResultCode.INIT_SUCCESS) {
-  console.log('初始化成功');
+  console.log('Initialization successful');
 }
 ```
 
-**参数：**
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `mnemonic` | `string` | 是 | BIP-39 助记词（12/15/18/21/24 词） |
-| `password` | `string` | 是 | 要设置的保护密码 |
-| `onCardIdentified` | `() => void` | 否 | 开始写入前的回调 |
+**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?)`
+### `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('更新成功');
+  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');
 }
 ```
 
-**参数：**
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `oldPassword` | `string` | 是 | 当前密码 |
-| `newPassword` | `string` | 是 | 新密码 |
-| `newMnemonic` | `string` | 是 | 新助记词 |
-| `onCardIdentified` | `() => void` | 否 | 认证成功后的回调 |
+**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('密码修改成功');
+  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)`
+### `writeUserNickname(password, nickname, onCardIdentified?)`
 
-写入用户昵称到卡片（最长 12 字节，UTF-8 编码）。
+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('昵称写入成功');
+  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?)`
+### `readUserNickname(password?, onCardIdentified?)`
 
-读取卡片上的用户昵称。如果卡片开启了读保护，需要传密码。
+Read the user nickname from the card.
 
 ```typescript
 const result = await readUserNickname('your-password');
 if (result.success) {
-  console.log('昵称:', result.data?.nickname);
+  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?)`
+### `resetCard(password, newPassword, onCardIdentified?)`
 
-重置卡片：清空所有用户数据，密码设为 `"000000"`。
+Reset the card: wipe mnemonic data, set a new password, and disable read/write protection. Nickname is preserved.
 
 ```typescript
-const result = await resetCard('your-password');
+const result = await resetCard('old-password', 'new-password');
 if (result.code === ResultCode.RESET_SUCCESS) {
-  console.log('重置成功');
+  console.log('Reset successful');
 }
 ```
 
-> ⚠️ 重置操作不可逆，请谨慎使用。
+> ⚠️ This operation is irreversible; mnemonic data on the card is permanently erased.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `password` | `string \| undefined` | No | Current card password. Required if the card is protected; pass `undefined` otherwise. The retry counter is decremented automatically before authentication. |
+| `newPassword` | `string` | Yes | Password to set after reset. |
+| `onCardIdentified` | `() => void` | No | Called after successful authentication |
 
 ---
 
-### `readMnemonicRetryCount()`
+### `readMnemonicRetryCount(onCardIdentified?)`
 
-读取当前 PIN 重试计数器的值。
+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('剩余重试次数:', result.data?.retryCount);
+  console.log('Remaining retries:', result.data?.retryCount);
 }
 ```
 
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `onCardIdentified` | `() => void` | No | Called after the NFC session is established |
+
 ---
 
-### `resetRetryCountTo10()`
+### `resetRetryCountTo10(onCardIdentified?)`
 
-将 PIN 重试计数器重置为默认值 10。
+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 锁管理
+### NFC Lock Management
 
-用于 App 页面生命周期中的 NFC 会话管理：
+For app-level NFC session lifecycle management:
 
 ```typescript
 import {
@@ -248,22 +315,22 @@ import {
 } from '@ukeyfe/react-native-nfc-litecard';
 ```
 
-| 方法 | 说明 |
-|------|------|
-| `isNfcOperationLocked()` | 检查 NFC 操作锁是否被持有 |
-| `releaseNfcOperationLock()` | 强制释放锁（页面关闭时使用） |
-| `markNfcOperationCancelledByCleanup()` | 标记当前操作被页面清理中断 |
-| `consumeNfcOperationCancelledByCleanup()` | 消费清理标记（返回是否被中断） |
+| 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 返回结构
+## NfcResult Structure
 
-所有 API 统一返回 `NfcResult`：
+All APIs return a unified `NfcResult`:
 
 ```typescript
 interface NfcResult {
-  code: number;       // 状态码，与 ResultCode 常量比较
-  success: boolean;   // 操作是否成功
-  data?: {            // 可选数据，仅部分操作返回
+  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;
@@ -276,7 +343,7 @@ interface NfcResult {
 }
 ```
 
-## 错误处理示例
+## Error Handling Example
 
 ```typescript
 import { ResultCode, readMnemonic } from '@ukeyfe/react-native-nfc-litecard';
@@ -285,105 +352,110 @@ const result = await readMnemonic('password');
 
 switch (result.code) {
   case ResultCode.READ_SUCCESS:
-    console.log('读取成功:', result.data?.mnemonic);
+    console.log('Read successful:', result.data?.mnemonic);
     break;
   case ResultCode.AUTH_WRONG_PASSWORD:
-    alert('密码错误');
+    alert('Wrong password');
     break;
   case ResultCode.NFC_CONNECT_FAILED:
-    alert('NFC 连接失败，请重新贴卡');
+    alert('NFC connection failed, please re-tap the card');
     break;
   case ResultCode.NFC_USER_CANCELED:
-    // iOS 用户取消，静默处理
+    // iOS user cancelled – handle silently
     break;
   case ResultCode.READ_TIMEOUT:
-    alert('读取超时，请将卡片移开后重新贴近');
+    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('操作失败');
+    alert('Operation failed');
 }
 ```
 
-## 返回码一览
-
-### 成功码
-
-| 常量 | 值 | 说明 |
-|------|------|------|
-| `READ_SUCCESS` | 10102 | 读取助记词成功 |
-| `READ_NICKNAME_SUCCESS` | 10103 | 读取昵称成功 |
-| `CHECK_EMPTY` | 10104 | 空卡 |
-| `CHECK_HAS_DATA` | 10105 | 卡片有数据 |
-| `READ_RETRY_COUNT_SUCCESS` | 10106 | 读取重试次数成功 |
-| `INIT_SUCCESS` | 10201 | 初始化成功 |
-| `WRITE_SUCCESS` | 10203 | 写入/更新成功 |
-| `UPDATE_PASSWORD_SUCCESS` | 10204 | 修改密码成功 |
-| `WRITE_NICKNAME_SUCCESS` | 10205 | 写入昵称成功 |
-| `RESET_SUCCESS` | 10206 | 重置卡片成功 |
-
-### 错误码
-
-| 常量 | 值 | 说明 |
-|------|------|------|
-| `NFC_CONNECT_FAILED` | 40001 | NFC 连接失败 |
-| `AUTH_WRONG_PASSWORD` | 40002 | 密码错误 |
-| `AUTH_INVALID_RESPONSE` | 40003 | 认证响应无效 |
-| `AUTH_VERIFY_FAILED` | 40004 | 认证验证失败 |
-| `READ_FAILED` | 40005 | 读取失败 |
-| `WRITE_FAILED` | 40006 | 写入失败 |
-| `INVALID_MNEMONIC` | 40007 | 无效的助记词 |
-| `UNSUPPORTED_MNEMONIC_LENGTH` | 40008 | 不支持的助记词长度 |
-| `INVALID_CARD_DATA` | 40009 | 卡片数据无效 |
-| `UNKNOWN_ERROR` | 40010 | 未知错误 |
-| `NFC_USER_CANCELED` | 40011 | 用户取消 NFC 扫描 (iOS) |
-| `READ_TIMEOUT` | 40012 | 读取超时 |
-| `NFC_LOCK_TIMEOUT` | 40013 | NFC 锁超时 |
-| `CRC16_CHECK_FAILED` | 40014 | CRC16 校验失败 |
-
-## 存储格式
-
-卡片使用 BIP-39 熵压缩存储助记词：
+## 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:
 
 ```
-[类型 1字节] [熵数据 16-32字节] [CRC16 2字节]
+[type 1B] [entropy 16-32B] [CRC16 2B]
 ```
 
-| 类型值 | 助记词长度 | 熵长度 |
-|--------|-----------|--------|
-| 0x01 | 12 词 | 16 字节 (128-bit) |
-| 0x02 | 15 词 | 20 字节 (160-bit) |
-| 0x03 | 18 词 | 24 字节 (192-bit) |
-| 0x04 | 21 词 | 28 字节 (224-bit) |
-| 0x05 | 24 词 | 32 字节 (256-bit) |
+| 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 硬件级双向认证**（3-pass mutual authentication）
-- **SHA-256 密钥派生**：用户密码 → SHA-256 → 取前 16 字节作为 AES 密钥
-- **CRC16-Modbus 校验**：数据完整性验证
-- **PIN 重试计数器**：密码错误自动递减，成功后恢复为 10
-- **安全随机数**：认证使用 `crypto.getRandomValues()`（需 Hermes ≥ 0.72 或 `react-native-get-random-values` polyfill）
+- **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        # 公共 API 导出
-├── constants.ts    # 共享常量（页地址、NFC 命令、助记词类型）
-├── types.ts        # 统一 ResultCode、NfcResult 接口、错误映射
-├── crypto.ts       # AES 加解密、密钥派生、安全随机数生成
-├── utils.ts        # CRC16、hex 转换、数组工具
-├── nfc-core.ts     # NFC 锁、transceive、认证、重试计数器
-├── reader.ts       # 读卡 API
-└── writer.ts       # 写卡 API
+├── 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
 
-| 平台 | 技术 | 说明 |
-|------|------|------|
-| iOS | MifareIOS | 需要 iPhone 7 及以上 |
-| Android | NfcA | 需要设备支持 NFC |
+| Platform | Technology | Requirements |
+|----------|-----------|--------------|
+| iOS | MifareIOS | iPhone 7 or later |
+| Android | NfcA | NFC-capable device |
 
 ## License