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

package/README.md

@@ -1,45 +1,47 @@
 # @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 `NfcStatusCode` 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()` | 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, 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
 
 ```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 {
-  ResultCode,
+  NfcStatusCode,
   checkCard,
   readMnemonic,
   initializeCard,
@@ -50,259 +52,293 @@ import {
   resetCard,
   readMnemonicRetryCount,
   resetRetryCountTo10,
+  getCardVersion,
+  readOriginality,
 } from '@ukeyfe/react-native-nfc-litecard';
 ```
 
-## API 文档
+## 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) {
-  // 空卡，可以初始化
-} else if (result.code === ResultCode.CHECK_HAS_DATA) {
-  // 有数据（或卡开了读保护无法确定）
+if (result.code === NfcStatusCode.CHECK_EMPTY) {
+  // Empty card – ready to initialize
+} else if (result.code === NfcStatusCode.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) {
-  // 空卡，可以写入
-} else if (result.code === ResultCode.CHECK_HAS_DATA) {
-  // 有合法助记词备份，类型: result.data?.type
-} else if (result.code === ResultCode.AUTH_WRONG_PASSWORD) {
-  // 密码错误
+if (result.code === NfcStatusCode.CHECK_EMPTY) {
+  // Empty card – ready to write
+} else if (result.code === NfcStatusCode.CHECK_HAS_DATA) {
+  // Valid mnemonic backup exists, type: result.data?.type
+} else if (result.code === NfcStatusCode.AUTH_WRONG_PASSWORD) {
+  // Wrong password
 }
 ```
 
-**参数：**
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `password` | `string` | 否 | 卡片保护密码。不传时直接尝试读取（适合未加密的卡）；传入后先用密码进行 AES 认证再读取完整数据并校验 CRC16（适合开了读保护的卡，结果更准确） |
-| `onCardIdentified` | `() => void` | 否 | NFC 连接建立后的回调，可用于 UI 提示"已识别到卡片" |
+**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". |
 
-**返回值 (`NfcResult`)：**
-| code | 含义 |
-|------|------|
-| `ResultCode.CHECK_EMPTY` (10104) | 空卡，没有助记词数据 |
-| `ResultCode.CHECK_HAS_DATA` (10105) | 卡上有数据。传密码时 `data.type` 包含助记词类型（如 "12 words (128-bit)"） |
-| `ResultCode.AUTH_WRONG_PASSWORD` (40002) | 密码错误（仅传密码时可能返回） |
-| `ResultCode.NFC_CONNECT_FAILED` (40001) | NFC 连接失败，卡片未贴近或设备不支持 |
+**Result codes:**
+| Code | Meaning |
+|------|---------|
+| `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 |
 
 ---
 
 ### `readMnemonic(password, onCardIdentified?)`
 
-读取助记词（需要密码认证）。认证前会自动递减重试计数器，认证成功后重置为 10。
+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` | 是 | 卡片保护密码，用于 AES-128 认证 |
-| `onCardIdentified` | `() => void` | 否 | 认证成功后、开始读取数据前的回调，可用于 UI 提示"正在读取" |
-
-**返回 `data` 字段：**
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `mnemonic` | `string` | BIP-39 助记词（如 "abandon abandon ... about"） |
-| `type` | `string` | 助记词类型（如 "12 words (128-bit)"、"24 words (256-bit)"） |
-| `entropyHex` | `string` | 熵数据的十六进制字符串 |
-| `rawBytes` | `string` | 卡上原始数据（类型+熵）的十六进制字符串 |
-| `nickname` | `string` | 用户昵称（如果卡上有设置） |
-| `retryCount` | `number` | 认证成功后重置的重试次数（正常为 10） |
+**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?)`
+### `initializeCard(mnemonic, newPassword, defaultPassword, onCardIdentified?)`
 
-初始化空卡：将助记词转为 BIP-39 熵写入卡片，设置 AES 密码保护，开启读写认证。
+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) {
-  console.log('初始化成功');
+if (result.code === NfcStatusCode.INIT_SUCCESS) {
+  console.log('Initialization successful');
 }
 ```
 
-**参数：**
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `mnemonic` | `string` | 是 | BIP-39 助记词，支持 12/15/18/21/24 词。库会自动转为熵 + CRC16 写入卡片 |
-| `password` | `string` | 是 | 要设置的保护密码，用于生成 AES-128 密钥并写入卡片 |
-| `onCardIdentified` | `() => void` | 否 | NFC 连接建立后、开始写入前的回调，可用于 UI 提示"正在写入" |
+**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. |
+| `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". |
 
 ---
 
 ### `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('更新成功');
+if (result.code === NfcStatusCode.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) {
-  console.log('卡上已有备份，未写入。类型:', result.data?.type);
-} else if (result.code === ResultCode.WRITE_SUCCESS) {
-  console.log('写入成功');
+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 === NfcStatusCode.WRITE_SUCCESS) {
+  console.log('Write successful');
 }
 ```
 
-**参数：**
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `oldPassword` | `string` | 是 | 当前卡片密码，用于 AES 认证 |
-| `newPassword` | `string` | 是 | 新密码，写入后卡片将使用此密码保护 |
-| `newMnemonic` | `string` | 是 | 新的 BIP-39 助记词（12/15/18/21/24 词） |
-| `onCardIdentified` | `() => void` | 否 | 认证成功后的回调，可用于 UI 提示"正在写入" |
-| `options.precheckExistingMnemonic` | `boolean` | 否 | 设为 `true` 时，认证后先读取卡片数据并校验 CRC16。如果已有合法助记词，返回 `PRECHECK_HAS_BACKUP` 不执行写入 |
+**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('密码修改成功');
+if (result.code === NfcStatusCode.UPDATE_PASSWORD_SUCCESS) {
+  console.log('Password updated');
 }
 ```
 
-**参数：**
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `oldPassword` | `string` | 是 | 当前卡片密码，用于 AES 认证 |
-| `newPassword` | `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 use this password after the change |
+| `onCardIdentified` | `() => void` | No | Called after successful authentication |
 
 ---
 
 ### `writeUserNickname(password, nickname, onCardIdentified?)`
 
-写入用户昵称到卡片。昵称使用 UTF-8 编码，最长 12 字节（超出自动截断）。
+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('昵称写入成功');
+if (result.code === NfcStatusCode.WRITE_NICKNAME_SUCCESS) {
+  console.log('Nickname written');
 }
 ```
 
-**参数：**
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `password` | `string` | 是 | 卡片保护密码，用于 AES 认证 |
-| `nickname` | `string` | 是 | 用户昵称，UTF-8 编码最长 12 字节。中文约 4 个字，英文 12 个字符 |
-| `onCardIdentified` | `() => void` | 否 | 认证成功后的回调 |
+**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('昵称:', result.data?.nickname);
+  console.log('Nickname:', result.data?.nickname);
 }
 ```
 
-**参数：**
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `password` | `string` | 否 | 卡片密码。如果卡开了读保护（PROT=1）则必须传入，否则可省略 |
-| `onCardIdentified` | `() => void` | 否 | 认证成功后的回调 |
+**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');
-if (result.code === ResultCode.RESET_SUCCESS) {
-  console.log('重置成功');
+const result = await resetCard('old-password', 'new-password');
+if (result.code === NfcStatusCode.RESET_SUCCESS) {
+  console.log('Reset successful');
 }
 ```
 
-> ⚠️ 重置操作不可逆，卡上的助记词数据将被永久清除。
+> ⚠️ This operation is irreversible; mnemonic data on the card is permanently erased.
 
-**参数：**
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `password` | `string` | 否 | 当前卡片密码。如果卡开了保护则必须传入，否则可省略。认证前自动递减重试计数器 |
-| `onCardIdentified` | `() => void` | 否 | 认证成功后的回调 |
+**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(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);
 }
 ```
 
-**参数：**
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `onCardIdentified` | `() => void` | 否 | NFC 连接建立后的回调 |
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `onCardIdentified` | `() => void` | No | Called after the NFC session is established |
 
 ---
 
 ### `resetRetryCountTo10(onCardIdentified?)`
 
-将 PIN 重试计数器重置为默认值 10。不需要密码认证。
+Reset the PIN retry counter to its default value (10). No password authentication is required.
 
 ```typescript
 const result = await resetRetryCountTo10();
 ```
 
-**参数：**
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `onCardIdentified` | `() => void` | 否 | NFC 连接建立后的回调 |
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `onCardIdentified` | `() => void` | No | Called after the NFC session is established |
 
 ---
 
-### NFC 锁管理
+### `getCardVersion(onCardIdentified?)`
 
-用于 App 页面生命周期中的 NFC 会话管理：
+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:
 
 ```typescript
 import {
@@ -313,22 +349,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 NfcStatusCode
+  success: boolean;   // Whether the operation succeeded
+  data?: {            // Optional data, only present for some operations
     mnemonic?: string;
     type?: string;
     entropyHex?: string;
@@ -341,119 +377,122 @@ 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:
-    console.log('读取成功:', result.data?.mnemonic);
+  case NfcStatusCode.READ_SUCCESS:
+    console.log('Read successful:', result.data?.mnemonic);
     break;
-  case ResultCode.AUTH_WRONG_PASSWORD:
-    alert('密码错误');
+  case NfcStatusCode.AUTH_WRONG_PASSWORD:
+    alert('Wrong password');
     break;
-  case ResultCode.NFC_CONNECT_FAILED:
-    alert('NFC 连接失败，请重新贴卡');
+  case NfcStatusCode.NFC_CONNECT_FAILED:
+    alert('NFC connection failed, please re-tap the card');
     break;
-  case ResultCode.NFC_USER_CANCELED:
-    // iOS 用户取消，静默处理
+  case NfcStatusCode.NFC_USER_CANCELED:
+    // iOS user cancelled – handle silently
     break;
-  case ResultCode.READ_TIMEOUT:
-    alert('读取超时，请将卡片移开后重新贴近');
+  case NfcStatusCode.READ_TIMEOUT:
+    alert('Read timeout – remove and re-tap the card');
     break;
-  case ResultCode.RETRY_COUNT_EXHAUSTED:
-    alert('重试次数已用完，卡片已锁定');
+  case NfcStatusCode.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 | 重置卡片成功 |
-| `PRECHECK_HAS_BACKUP` | 10207 | 卡上已有合法备份，写入被跳过 |
-
-### 错误码
-
-| 常量 | 值 | 说明 |
-|------|------|------|
-| `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 校验失败 |
-| `RETRY_COUNT_EXHAUSTED` | 40015 | PIN 重试次数已用完，卡片锁定 |
-
-## 存储格式
-
-卡片使用 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 |
+| `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 |
+| `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
+- **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
 
 ```
 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 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
+├── 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