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

package/README.en.md

@@ -55,36 +55,51 @@ import {
 
 ## 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 – need password to read or update
+  // 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 |
 |-----------|------|----------|-------------|
-| `onCardIdentified` | `() => void` | No | Callback after card is identified |
+| `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 |
-| `ResultCode.CHECK_HAS_DATA` (10105) | Card has data |
-| `ResultCode.NFC_CONNECT_FAILED` (40001) | NFC connection failed |
+| `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 mnemonic from a password-protected card.
+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');
@@ -99,24 +114,24 @@ if (result.success) {
 **Parameters:**
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `password` | `string` | Yes | Card protection password |
-| `onCardIdentified` | `() => void` | No | Callback after successful authentication |
+| `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 | 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 |
+| 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: write mnemonic + set password protection.
+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(
@@ -131,15 +146,15 @@ if (result.code === ResultCode.INIT_SUCCESS) {
 **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 |
+| `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 card: authenticate with old password, then write new mnemonic + new password.
+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 ...');
@@ -148,19 +163,34 @@ if (result.code === ResultCode.WRITE_SUCCESS) {
 }
 ```
 
+**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 password |
-| `newPassword` | `string` | Yes | New password |
-| `newMnemonic` | `string` | Yes | New mnemonic |
-| `onCardIdentified` | `() => void` | No | Callback after successful authentication |
+| `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 password only, without modifying mnemonic data.
+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');
@@ -169,11 +199,18 @@ if (result.code === ResultCode.UPDATE_PASSWORD_SUCCESS) {
 }
 ```
 
+**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?)`
 
-Write a user nickname to the card (max 12 bytes, UTF-8 encoded).
+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');
@@ -182,11 +219,18 @@ if (result.code === ResultCode.WRITE_NICKNAME_SUCCESS) {
 }
 ```
 
+**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 user nickname from the card. Supply password if read-protection is enabled.
+Read the user nickname from the card.
 
 ```typescript
 const result = await readUserNickname('your-password');
@@ -195,11 +239,17 @@ if (result.success) {
 }
 ```
 
+**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 card: wipe all user data, set password to `"000000"`.
+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');
@@ -208,13 +258,19 @@ if (result.code === ResultCode.RESET_SUCCESS) {
 }
 ```
 
-> ⚠️ This operation is irreversible. Use with caution.
+> ⚠️ 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()`
+### `readMnemonicRetryCount(onCardIdentified?)`
 
-Read the current PIN retry counter value.
+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();
@@ -223,16 +279,26 @@ if (result.success) {
 }
 ```
 
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `onCardIdentified` | `() => void` | No | Called after the NFC session is established |
+
 ---
 
-### `resetRetryCountTo10()`
+### `resetRetryCountTo10(onCardIdentified?)`
 
-Reset the PIN retry counter to its default value (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 Lock Management
@@ -299,6 +365,9 @@ switch (result.code) {
   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');
 }
@@ -320,6 +389,7 @@ switch (result.code) {
 | `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
 
@@ -339,6 +409,7 @@ switch (result.code) {
 | `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
 
@@ -364,13 +435,6 @@ The card stores BIP-39 mnemonics using entropy compression:
 - **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
 
 ```
@@ -379,12 +443,19 @@ src/
 ├── 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
+├── 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

package/README.md

@@ -55,36 +55,51 @@ import {
 
 ## API 文档
 
-### `checkCard(onCardIdentified?)`
+### `checkCard(password?, onCardIdentified?)`
 
 检测卡片状态（空卡 / 有数据）。
 
+**不传密码（快速探测）：**
 ```typescript
 const result = await checkCard();
 if (result.code === ResultCode.CHECK_EMPTY) {
   // 空卡，可以初始化
 } else if (result.code === ResultCode.CHECK_HAS_DATA) {
-  // 有数据，需要密码读取或更新
+  // 有数据（或卡开了读保护无法确定）
+}
+```
+
+**传密码（认证后深度检查，适用于开了读保护的卡）：**
+```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) {
+  // 密码错误
 }
 ```
 
 **参数：**
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `onCardIdentified` | `() => void` | 否 | 卡片识别成功后的回调 |
+| `password` | `string` | 否 | 卡片保护密码。不传时直接尝试读取（适合未加密的卡）；传入后先用密码进行 AES 认证再读取完整数据并校验 CRC16（适合开了读保护的卡，结果更准确） |
+| `onCardIdentified` | `() => void` | 否 | NFC 连接建立后的回调，可用于 UI 提示"已识别到卡片" |
 
 **返回值 (`NfcResult`)：**
 | code | 含义 |
 |------|------|
-| `ResultCode.CHECK_EMPTY` (10104) | 空卡 |
-| `ResultCode.CHECK_HAS_DATA` (10105) | 有数据 |
-| `ResultCode.NFC_CONNECT_FAILED` (40001) | NFC 连接失败 |
+| `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 连接失败，卡片未贴近或设备不支持 |
 
 ---
 
 ### `readMnemonic(password, onCardIdentified?)`
 
-读取助记词（需要密码认证）。
+读取助记词（需要密码认证）。认证前会自动递减重试计数器，认证成功后重置为 10。
 
 ```typescript
 const result = await readMnemonic('your-password');
@@ -99,24 +114,24 @@ if (result.success) {
 **参数：**
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `password` | `string` | 是 | 卡片保护密码 |
-| `onCardIdentified` | `() => void` | 否 | 认证成功后的回调 |
+| `password` | `string` | 是 | 卡片保护密码，用于 AES-128 认证 |
+| `onCardIdentified` | `() => void` | 否 | 认证成功后、开始读取数据前的回调，可用于 UI 提示"正在读取" |
 
 **返回 `data` 字段：**
-| 字段 | 说明 |
-|------|------|
-| `mnemonic` | BIP-39 助记词 |
-| `type` | 助记词类型（如 "12 words (128-bit)"） |
-| `entropyHex` | 熵的十六进制 |
-| `rawBytes` | 原始数据十六进制 |
-| `nickname` | 用户昵称（如果有） |
-| `retryCount` | 认证成功后重置的重试次数 |
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `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） |
 
 ---
 
 ### `initializeCard(mnemonic, password, onCardIdentified?)`
 
-初始化空卡：写入助记词 + 设置密码保护。
+初始化空卡：将助记词转为 BIP-39 熵写入卡片，设置 AES 密码保护，开启读写认证。
 
 ```typescript
 const result = await initializeCard(
@@ -131,15 +146,15 @@ if (result.code === ResultCode.INIT_SUCCESS) {
 **参数：**
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `mnemonic` | `string` | 是 | BIP-39 助记词（12/15/18/21/24 词） |
-| `password` | `string` | 是 | 要设置的保护密码 |
-| `onCardIdentified` | `() => void` | 否 | 开始写入前的回调 |
+| `mnemonic` | `string` | 是 | BIP-39 助记词，支持 12/15/18/21/24 词。库会自动转为熵 + CRC16 写入卡片 |
+| `password` | `string` | 是 | 要设置的保护密码，用于生成 AES-128 密钥并写入卡片 |
+| `onCardIdentified` | `() => void` | 否 | NFC 连接建立后、开始写入前的回调，可用于 UI 提示"正在写入" |
 
 ---
 
-### `updateCard(oldPassword, newPassword, newMnemonic, onCardIdentified?)`
+### `updateCard(oldPassword, newPassword, newMnemonic, onCardIdentified?, options?)`
 
-更新卡片内容：使用旧密码认证后写入新助记词和新密码。
+更新卡片：用旧密码认证后，写入新助记词和新密码。认证前自动递减重试计数器。
 
 ```typescript
 const result = await updateCard('old-password', 'new-password', 'new mnemonic words ...');
@@ -148,19 +163,33 @@ if (result.code === ResultCode.WRITE_SUCCESS) {
 }
 ```
 
+**写入前检查是否已有备份：**
+
+```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('写入成功');
+}
+```
+
 **参数：**
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `oldPassword` | `string` | 是 | 当前密码 |
-| `newPassword` | `string` | 是 | 新密码 |
-| `newMnemonic` | `string` | 是 | 新助记词 |
-| `onCardIdentified` | `() => void` | 否 | 认证成功后的回调 |
+| `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` 不执行写入 |
 
 ---
 
 ### `updatePassword(oldPassword, newPassword, onCardIdentified?)`
 
-仅修改密码，不更改助记词数据。
+仅修改密码，不更改卡上的助记词数据。认证前自动递减重试计数器。
 
 ```typescript
 const result = await updatePassword('old-password', 'new-password');
@@ -169,11 +198,18 @@ if (result.code === ResultCode.UPDATE_PASSWORD_SUCCESS) {
 }
 ```
 
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `oldPassword` | `string` | 是 | 当前卡片密码，用于 AES 认证 |
+| `newPassword` | `string` | 是 | 新密码，修改后卡片将使用此密码保护 |
+| `onCardIdentified` | `() => void` | 否 | 认证成功后的回调 |
+
 ---
 
-### `writeUserNickname(password, nickname)`
+### `writeUserNickname(password, nickname, onCardIdentified?)`
 
-写入用户昵称到卡片（最长 12 字节，UTF-8 编码）。
+写入用户昵称到卡片。昵称使用 UTF-8 编码，最长 12 字节（超出自动截断）。
 
 ```typescript
 const result = await writeUserNickname('your-password', 'MyCard');
@@ -182,11 +218,18 @@ if (result.code === ResultCode.WRITE_NICKNAME_SUCCESS) {
 }
 ```
 
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `password` | `string` | 是 | 卡片保护密码，用于 AES 认证 |
+| `nickname` | `string` | 是 | 用户昵称，UTF-8 编码最长 12 字节。中文约 4 个字，英文 12 个字符 |
+| `onCardIdentified` | `() => void` | 否 | 认证成功后的回调 |
+
 ---
 
-### `readUserNickname(password?)`
+### `readUserNickname(password?, onCardIdentified?)`
 
-读取卡片上的用户昵称。如果卡片开启了读保护，需要传密码。
+读取卡片上的用户昵称。
 
 ```typescript
 const result = await readUserNickname('your-password');
@@ -195,11 +238,17 @@ if (result.success) {
 }
 ```
 
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `password` | `string` | 否 | 卡片密码。如果卡开了读保护（PROT=1）则必须传入，否则可省略 |
+| `onCardIdentified` | `() => void` | 否 | 认证成功后的回调 |
+
 ---
 
 ### `resetCard(password?, onCardIdentified?)`
 
-重置卡片：清空所有用户数据，密码设为 `"000000"`。
+重置卡片：清空所有用户数据（助记词、昵称），密码重置为 `"000000"`，关闭读写保护。
 
 ```typescript
 const result = await resetCard('your-password');
@@ -208,13 +257,19 @@ if (result.code === ResultCode.RESET_SUCCESS) {
 }
 ```
 
-> ⚠️ 重置操作不可逆，请谨慎使用。
+> ⚠️ 重置操作不可逆，卡上的助记词数据将被永久清除。
+
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `password` | `string` | 否 | 当前卡片密码。如果卡开了保护则必须传入，否则可省略。认证前自动递减重试计数器 |
+| `onCardIdentified` | `() => void` | 否 | 认证成功后的回调 |
 
 ---
 
-### `readMnemonicRetryCount()`
+### `readMnemonicRetryCount(onCardIdentified?)`
 
-读取当前 PIN 重试计数器的值。
+读取卡片上的 PIN 重试计数器值。不需要密码认证（计数器页不在保护区域内）。
 
 ```typescript
 const result = await readMnemonicRetryCount();
@@ -223,16 +278,26 @@ if (result.success) {
 }
 ```
 
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `onCardIdentified` | `() => void` | 否 | NFC 连接建立后的回调 |
+
 ---
 
-### `resetRetryCountTo10()`
+### `resetRetryCountTo10(onCardIdentified?)`
 
-将 PIN 重试计数器重置为默认值 10。
+将 PIN 重试计数器重置为默认值 10。不需要密码认证。
 
 ```typescript
 const result = await resetRetryCountTo10();
 ```
 
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `onCardIdentified` | `() => void` | 否 | NFC 连接建立后的回调 |
+
 ---
 
 ### NFC 锁管理
@@ -299,6 +364,9 @@ switch (result.code) {
   case ResultCode.READ_TIMEOUT:
     alert('读取超时，请将卡片移开后重新贴近');
     break;
+  case ResultCode.RETRY_COUNT_EXHAUSTED:
+    alert('重试次数已用完，卡片已锁定');
+    break;
   default:
     alert('操作失败');
 }
@@ -320,6 +388,7 @@ switch (result.code) {
 | `UPDATE_PASSWORD_SUCCESS` | 10204 | 修改密码成功 |
 | `WRITE_NICKNAME_SUCCESS` | 10205 | 写入昵称成功 |
 | `RESET_SUCCESS` | 10206 | 重置卡片成功 |
+| `PRECHECK_HAS_BACKUP` | 10207 | 卡上已有合法备份，写入被跳过 |
 
 ### 错误码
 
@@ -339,6 +408,7 @@ switch (result.code) {
 | `READ_TIMEOUT` | 40012 | 读取超时 |
 | `NFC_LOCK_TIMEOUT` | 40013 | NFC 锁超时 |
 | `CRC16_CHECK_FAILED` | 40014 | CRC16 校验失败 |
+| `RETRY_COUNT_EXHAUSTED` | 40015 | PIN 重试次数已用完，卡片锁定 |
 
 ## 存储格式
 

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  *
  * NFC read/write library for MIFARE Ultralight AES (LiteCard mnemonic storage).
  */
-export { ResultCode, type NfcResult } from './types';
+export { ResultCode, type NfcResult, nfcResultRetryCountExhausted, } from './types';
 export { checkCard, readMnemonic, readUserNickname, readMnemonicRetryCount, resetRetryCountTo10, cardInfoToJson, } from './reader';
 export { initializeCard, updateCard, updatePassword, writeUserNickname, resetCard, } from './writer';
 export { isNfcOperationLocked, releaseNfcOperationLock, markNfcOperationCancelledByCleanup, consumeNfcOperationCancelledByCleanup, getNfcOperationCancelledByCleanupTimestamp, clearNfcOperationCancelledByCleanup, } from './nfc-core';

package/dist/index.js

@@ -5,12 +5,13 @@
  * NFC read/write library for MIFARE Ultralight AES (LiteCard mnemonic storage).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_PIN_RETRY_COUNT = exports.clearNfcOperationCancelledByCleanup = exports.getNfcOperationCancelledByCleanupTimestamp = exports.consumeNfcOperationCancelledByCleanup = exports.markNfcOperationCancelledByCleanup = exports.releaseNfcOperationLock = exports.isNfcOperationLocked = exports.resetCard = exports.writeUserNickname = exports.updatePassword = exports.updateCard = exports.initializeCard = exports.cardInfoToJson = exports.resetRetryCountTo10 = exports.readMnemonicRetryCount = exports.readUserNickname = exports.readMnemonic = exports.checkCard = exports.ResultCode = void 0;
+exports.DEFAULT_PIN_RETRY_COUNT = exports.clearNfcOperationCancelledByCleanup = exports.getNfcOperationCancelledByCleanupTimestamp = exports.consumeNfcOperationCancelledByCleanup = exports.markNfcOperationCancelledByCleanup = exports.releaseNfcOperationLock = exports.isNfcOperationLocked = exports.resetCard = exports.writeUserNickname = exports.updatePassword = exports.updateCard = exports.initializeCard = exports.cardInfoToJson = exports.resetRetryCountTo10 = exports.readMnemonicRetryCount = exports.readUserNickname = exports.readMnemonic = exports.checkCard = exports.nfcResultRetryCountExhausted = exports.ResultCode = void 0;
 // ---------------------------------------------------------------------------
 // Unified types & constants (consumers can use a single ResultCode)
 // ---------------------------------------------------------------------------
 var types_1 = require("./types");
 Object.defineProperty(exports, "ResultCode", { enumerable: true, get: function () { return types_1.ResultCode; } });
+Object.defineProperty(exports, "nfcResultRetryCountExhausted", { enumerable: true, get: function () { return types_1.nfcResultRetryCountExhausted; } });
 // ---------------------------------------------------------------------------
 // Reader API
 // ---------------------------------------------------------------------------

package/dist/nfc-core.js

@@ -257,7 +257,9 @@ async function decrementRetryCountInSession() {
     const page = pageBlock.slice(0, constants_1.PAGE_SIZE);
     const raw = page[constants_1.RETRY_COUNTER_OFFSET];
     const current = typeof raw === 'number' ? raw & 0xff : 0;
-    const next = current > 0 ? current - 1 : 0;
+    if (current <= 0)
+        throw new Error('RETRY_COUNT_EXHAUSTED');
+    const next = current - 1;
     page[constants_1.RETRY_COUNTER_OFFSET] = next & 0xff;
     await transceive([constants_1.CMD_WRITE, constants_1.RETRY_COUNTER_PAGE, ...page]);
     return next;

package/dist/reader.d.ts

@@ -58,12 +58,17 @@ export declare function cardInfoToJson(cardInfo: ReturnType<typeof parseCardInfo
 /**
  * Detect whether the card is empty or already contains data.
  *
- * Logic:
+ * Without password: tries to read without auth.
  *   - Read succeeds & first byte is a valid mnemonic type → HAS_DATA
  *   - Read succeeds & first byte is other → EMPTY
- *   - Read fails (auth required) → HAS_DATA (read-protection is on)
+ *   - Read fails (auth required) → HAS_DATA (read-protection is on, cannot determine)
+ *
+ * With password: authenticates first, then reads and validates with CRC16.
+ *   - Valid mnemonic payload → HAS_DATA (with type info)
+ *   - Empty or invalid data → EMPTY
+ *   - Auth failure → AUTH_WRONG_PASSWORD
  */
-export declare function checkCard(onCardIdentified?: () => void): Promise<NfcResult>;
+export declare function checkCard(password?: string, onCardIdentified?: () => void): Promise<NfcResult>;
 /**
  * Read the mnemonic from a password-protected card.
  *
@@ -75,8 +80,8 @@ export declare function readMnemonic(password: string, onCardIdentified?: () =>
  * Read the user nickname from the card.
  * @param password – supply if the card has read-protection enabled.
  */
-export declare function readUserNickname(password?: string): Promise<NfcResult>;
+export declare function readUserNickname(password?: string, onCardIdentified?: () => void): Promise<NfcResult>;
 /** Read the current PIN retry counter from the card. */
-export declare function readMnemonicRetryCount(): Promise<NfcResult>;
+export declare function readMnemonicRetryCount(onCardIdentified?: () => void): Promise<NfcResult>;
 /** Reset the PIN retry counter to the default value (10). */
-export declare function resetRetryCountTo10(): Promise<NfcResult>;
+export declare function resetRetryCountTo10(onCardIdentified?: () => void): Promise<NfcResult>;

package/dist/reader.js

@@ -228,12 +228,17 @@ function cardInfoToJson(cardInfo, pretty = true) {
 /**
  * Detect whether the card is empty or already contains data.
  *
- * Logic:
+ * Without password: tries to read without auth.
  *   - Read succeeds & first byte is a valid mnemonic type → HAS_DATA
  *   - Read succeeds & first byte is other → EMPTY
- *   - Read fails (auth required) → HAS_DATA (read-protection is on)
+ *   - Read fails (auth required) → HAS_DATA (read-protection is on, cannot determine)
+ *
+ * With password: authenticates first, then reads and validates with CRC16.
+ *   - Valid mnemonic payload → HAS_DATA (with type info)
+ *   - Empty or invalid data → EMPTY
+ *   - Auth failure → AUTH_WRONG_PASSWORD
  */
-async function checkCard(onCardIdentified) {
+async function checkCard(password, onCardIdentified) {
     try {
         await (0, nfc_core_1.acquireNfcLock)();
     }
@@ -248,25 +253,54 @@ async function checkCard(onCardIdentified) {
             (0, nfc_core_1.releaseNfcLock)();
             return { code: types_1.ResultCode.NFC_CONNECT_FAILED, success: false };
         }
-        onCardIdentified?.();
-        let response = null;
         try {
-            response = await (0, nfc_core_1.transceive)([constants_1.CMD_READ, constants_1.USER_PAGE_START]);
+            if (password) {
+                // Authenticated check: authenticate → read full memory → validate CRC16
+                const aesKey = (0, crypto_1.passwordToAesKey)(password);
+                await (0, nfc_core_1.authenticate)(aesKey);
+                onCardIdentified?.();
+                const data = await readUserMemory();
+                try {
+                    const decoded = (0, utils_1.validateMnemonicPayload)(data);
+                    await (0, nfc_core_1.releaseNfcTech)();
+                    (0, nfc_core_1.releaseNfcLock)();
+                    return { code: types_1.ResultCode.CHECK_HAS_DATA, success: true, data: { type: decoded.type } };
+                }
+                catch {
+                    await (0, nfc_core_1.releaseNfcTech)();
+                    (0, nfc_core_1.releaseNfcLock)();
+                    return { code: types_1.ResultCode.CHECK_EMPTY, success: true };
+                }
+            }
+            else {
+                // Unauthenticated check: try to read first page directly
+                onCardIdentified?.();
+                let response = null;
+                try {
+                    response = await (0, nfc_core_1.transceive)([constants_1.CMD_READ, constants_1.USER_PAGE_START]);
+                }
+                catch { /* read-protected */ }
+                await (0, nfc_core_1.releaseNfcTech)();
+                (0, nfc_core_1.releaseNfcLock)();
+                if (response && response.length >= 4) {
+                    const first = response[0];
+                    const hasData = first === constants_1.MNEMONIC_TYPE_12 ||
+                        first === constants_1.MNEMONIC_TYPE_15 ||
+                        first === constants_1.MNEMONIC_TYPE_18 ||
+                        first === constants_1.MNEMONIC_TYPE_21 ||
+                        first === constants_1.MNEMONIC_TYPE_24;
+                    return { code: hasData ? types_1.ResultCode.CHECK_HAS_DATA : types_1.ResultCode.CHECK_EMPTY, success: true };
+                }
+                // Read failed = protection is on, assume has data
+                return { code: types_1.ResultCode.CHECK_HAS_DATA, success: true };
+            }
         }
-        catch { /* read-protected */ }
-        await (0, nfc_core_1.releaseNfcTech)();
-        (0, nfc_core_1.releaseNfcLock)();
-        if (response && response.length >= 4) {
-            const first = response[0];
-            const hasData = first === constants_1.MNEMONIC_TYPE_12 ||
-                first === constants_1.MNEMONIC_TYPE_15 ||
-                first === constants_1.MNEMONIC_TYPE_18 ||
-                first === constants_1.MNEMONIC_TYPE_21 ||
-                first === constants_1.MNEMONIC_TYPE_24;
-            const code = hasData ? types_1.ResultCode.CHECK_HAS_DATA : types_1.ResultCode.CHECK_EMPTY;
-            return { code, success: true };
+        catch (error) {
+            await (0, nfc_core_1.releaseNfcTech)();
+            (0, nfc_core_1.releaseNfcLock)();
+            const code = (0, types_1.errorToCode)(error);
+            return { code, success: false };
         }
-        return { code: types_1.ResultCode.CHECK_HAS_DATA, success: true };
     }
     catch (error) {
         (0, nfc_core_1.releaseNfcLock)();
@@ -302,7 +336,14 @@ async function readMnemonic(password, onCardIdentified) {
                 if (typeof next === 'number')
                     retryCountAfterPreDecrement = next;
             }
-            catch { /* non-fatal */ }
+            catch (error) {
+                const code = (0, types_1.errorToCode)(error);
+                if (code === types_1.ResultCode.RETRY_COUNT_EXHAUSTED) {
+                    await (0, nfc_core_1.releaseNfcTech)();
+                    (0, nfc_core_1.releaseNfcLock)();
+                    return (0, types_1.nfcResultRetryCountExhausted)();
+                }
+            }
             const aesKey = (0, crypto_1.passwordToAesKey)(password);
             await (0, nfc_core_1.authenticate)(aesKey);
             onCardIdentified?.();
@@ -359,7 +400,7 @@ async function readMnemonic(password, onCardIdentified) {
  * Read the user nickname from the card.
  * @param password – supply if the card has read-protection enabled.
  */
-async function readUserNickname(password) {
+async function readUserNickname(password, onCardIdentified) {
     try {
         await (0, nfc_core_1.acquireNfcLock)();
     }
@@ -379,6 +420,7 @@ async function readUserNickname(password) {
                 const aesKey = (0, crypto_1.passwordToAesKey)(password);
                 await (0, nfc_core_1.authenticate)(aesKey);
             }
+            onCardIdentified?.();
             const nickname = await readUserNicknameInternal();
             await (0, nfc_core_1.releaseNfcTech)();
             (0, nfc_core_1.releaseNfcLock)();
@@ -401,7 +443,7 @@ async function readUserNickname(password) {
     }
 }
 /** Read the current PIN retry counter from the card. */
-async function readMnemonicRetryCount() {
+async function readMnemonicRetryCount(onCardIdentified) {
     try {
         await (0, nfc_core_1.acquireNfcLock)();
     }
@@ -417,6 +459,7 @@ async function readMnemonicRetryCount() {
             return { code: types_1.ResultCode.NFC_CONNECT_FAILED, success: false };
         }
         try {
+            onCardIdentified?.();
             const pageBlock = await (0, nfc_core_1.transceive)([constants_1.CMD_READ, constants_1.RETRY_COUNTER_PAGE]);
             if (!pageBlock || pageBlock.length < constants_1.PAGE_SIZE) {
                 await (0, nfc_core_1.releaseNfcTech)();
@@ -449,7 +492,7 @@ async function readMnemonicRetryCount() {
     }
 }
 /** Reset the PIN retry counter to the default value (10). */
-async function resetRetryCountTo10() {
+async function resetRetryCountTo10(onCardIdentified) {
     try {
         await (0, nfc_core_1.acquireNfcLock)();
     }
@@ -465,6 +508,7 @@ async function resetRetryCountTo10() {
             return { code: types_1.ResultCode.NFC_CONNECT_FAILED, success: false };
         }
         try {
+            onCardIdentified?.();
             await (0, nfc_core_1.writeRetryCountInSession)(constants_1.DEFAULT_PIN_RETRY_COUNT);
             await (0, nfc_core_1.releaseNfcTech)();
             (0, nfc_core_1.releaseNfcLock)();

package/dist/types.d.ts

@@ -20,6 +20,8 @@ export declare const ResultCode: {
     readonly UPDATE_PASSWORD_SUCCESS: 10204;
     readonly WRITE_NICKNAME_SUCCESS: 10205;
     readonly RESET_SUCCESS: 10206;
+    /** Card already has a valid mnemonic backup; write was skipped */
+    readonly PRECHECK_HAS_BACKUP: 10207;
     readonly NFC_CONNECT_FAILED: 40001;
     readonly AUTH_WRONG_PASSWORD: 40002;
     readonly AUTH_INVALID_RESPONSE: 40003;
@@ -34,6 +36,8 @@ export declare const ResultCode: {
     readonly READ_TIMEOUT: 40012;
     readonly NFC_LOCK_TIMEOUT: 40013;
     readonly CRC16_CHECK_FAILED: 40014;
+    /** PIN retry counter is 0; no authentication attempts left */
+    readonly RETRY_COUNT_EXHAUSTED: 40015;
 };
 export interface NfcResult {
     /** Numeric result code – compare against ResultCode constants */
@@ -52,6 +56,11 @@ export interface NfcResult {
         crc16?: number;
     };
 }
+/**
+ * Unified failure result when the PIN retry counter has reached 0.
+ * Used by readMnemonic, updateCard, updatePassword, and resetCard.
+ */
+export declare function nfcResultRetryCountExhausted(): NfcResult;
 /**
  * Derive a ResultCode from an error thrown during NFC operations.
  * Handles iOS-specific cancel detection, known error strings, and fallback.

package/dist/types.js

@@ -12,6 +12,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ResultCode = void 0;
+exports.nfcResultRetryCountExhausted = nfcResultRetryCountExhausted;
 exports.errorToCode = errorToCode;
 const react_native_1 = require("react-native");
 // ---------------------------------------------------------------------------
@@ -30,6 +31,8 @@ exports.ResultCode = {
     UPDATE_PASSWORD_SUCCESS: 10204,
     WRITE_NICKNAME_SUCCESS: 10205,
     RESET_SUCCESS: 10206,
+    /** Card already has a valid mnemonic backup; write was skipped */
+    PRECHECK_HAS_BACKUP: 10207,
     // Failure (4xxxx – shared by reader & writer)
     NFC_CONNECT_FAILED: 40001,
     AUTH_WRONG_PASSWORD: 40002,
@@ -45,7 +48,20 @@ exports.ResultCode = {
     READ_TIMEOUT: 40012,
     NFC_LOCK_TIMEOUT: 40013,
     CRC16_CHECK_FAILED: 40014,
+    /** PIN retry counter is 0; no authentication attempts left */
+    RETRY_COUNT_EXHAUSTED: 40015,
 };
+/**
+ * Unified failure result when the PIN retry counter has reached 0.
+ * Used by readMnemonic, updateCard, updatePassword, and resetCard.
+ */
+function nfcResultRetryCountExhausted() {
+    return {
+        code: exports.ResultCode.RETRY_COUNT_EXHAUSTED,
+        success: false,
+        data: { retryCount: 0 },
+    };
+}
 // ---------------------------------------------------------------------------
 // Error → code mapping (internal use)
 // ---------------------------------------------------------------------------
@@ -71,6 +87,7 @@ function errorToCode(error) {
     if (msg.includes('NFC_USER_CANCELED_SIGNAL'))
         return exports.ResultCode.NFC_USER_CANCELED;
     const keywords = [
+        ['RETRY_COUNT_EXHAUSTED', exports.ResultCode.RETRY_COUNT_EXHAUSTED],
         ['AUTH_WRONG_PASSWORD', exports.ResultCode.AUTH_WRONG_PASSWORD],
         ['AUTH_INVALID_RESPONSE', exports.ResultCode.AUTH_INVALID_RESPONSE],
         ['AUTH_VERIFY_FAILED', exports.ResultCode.AUTH_VERIFY_FAILED],

package/dist/utils.d.ts

@@ -15,3 +15,13 @@ export declare function crc16ToBytes(crc16: number): Uint8Array;
  * @throws if buffer is shorter than 2 bytes.
  */
 export declare function extractCRC16(data: Uint8Array): number;
+/**
+ * Validate whether raw card data contains a valid mnemonic payload.
+ * Checks type byte, length, and CRC16 — does NOT decode the mnemonic.
+ *
+ * @throws INVALID_CARD_DATA / EMPTY_CARD / CRC16_CHECK_FAILED
+ * @returns The mnemonic type description string.
+ */
+export declare function validateMnemonicPayload(data: Uint8Array): {
+    type: string;
+};

package/dist/utils.js

@@ -8,6 +8,8 @@ exports.hexToBytes = hexToBytes;
 exports.calculateCRC16 = calculateCRC16;
 exports.crc16ToBytes = crc16ToBytes;
 exports.extractCRC16 = extractCRC16;
+exports.validateMnemonicPayload = validateMnemonicPayload;
+const constants_1 = require("./constants");
 // ---------------------------------------------------------------------------
 // Hex ↔ bytes
 // ---------------------------------------------------------------------------
@@ -61,3 +63,54 @@ function extractCRC16(data) {
     }
     return data[data.length - 2] | (data[data.length - 1] << 8);
 }
+// ---------------------------------------------------------------------------
+// Mnemonic payload validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate whether raw card data contains a valid mnemonic payload.
+ * Checks type byte, length, and CRC16 — does NOT decode the mnemonic.
+ *
+ * @throws INVALID_CARD_DATA / EMPTY_CARD / CRC16_CHECK_FAILED
+ * @returns The mnemonic type description string.
+ */
+function validateMnemonicPayload(data) {
+    if (data.length < 19)
+        throw new Error('INVALID_CARD_DATA');
+    if (data.every(b => b === 0))
+        throw new Error('EMPTY_CARD');
+    const typeId = data[0];
+    let entropyLength;
+    let typeStr;
+    switch (typeId) {
+        case constants_1.MNEMONIC_TYPE_12:
+            entropyLength = 16;
+            typeStr = '12 words (128-bit)';
+            break;
+        case constants_1.MNEMONIC_TYPE_15:
+            entropyLength = 20;
+            typeStr = '15 words (160-bit)';
+            break;
+        case constants_1.MNEMONIC_TYPE_18:
+            entropyLength = 24;
+            typeStr = '18 words (192-bit)';
+            break;
+        case constants_1.MNEMONIC_TYPE_21:
+            entropyLength = 28;
+            typeStr = '21 words (224-bit)';
+            break;
+        case constants_1.MNEMONIC_TYPE_24:
+            entropyLength = 32;
+            typeStr = '24 words (256-bit)';
+            break;
+        default: throw new Error('INVALID_CARD_DATA');
+    }
+    const expectedTotal = 1 + entropyLength + 2;
+    if (data.length < expectedTotal)
+        throw new Error('INVALID_CARD_DATA');
+    const dataBlock = data.slice(0, 1 + entropyLength);
+    const storedCRC = extractCRC16(data.slice(1 + entropyLength, expectedTotal));
+    const calcCRC = calculateCRC16(dataBlock);
+    if (storedCRC !== calcCRC)
+        throw new Error('CRC16_CHECK_FAILED');
+    return { type: typeStr };
+}

package/dist/writer.d.ts

@@ -19,12 +19,19 @@ export { ResultCode, type NfcResult, isNfcOperationLocked, releaseNfcOperationLo
 export declare function initializeCard(mnemonic: string, password: string, onCardIdentified?: () => void): Promise<NfcResult>;
 /**
  * Update card: authenticate with old password, then write new mnemonic + new password.
+ *
+ * When `options.precheckExistingMnemonic` is true, the card is read after authentication.
+ * If a valid mnemonic backup already exists, the write is skipped and PRECHECK_HAS_BACKUP
+ * is returned (`success: true` — operation completed; distinguish outcome by `code`).
+ * Otherwise the normal write flow proceeds.
  */
-export declare function updateCard(oldPassword: string, newPassword: string, newMnemonic: string, onCardIdentified?: () => void): Promise<NfcResult>;
+export declare function updateCard(oldPassword: string, newPassword: string, newMnemonic: string, onCardIdentified?: () => void, options?: {
+    precheckExistingMnemonic?: boolean;
+}): Promise<NfcResult>;
 /** Change password only (old password required). */
 export declare function updatePassword(oldPassword: string, newPassword: string, onCardIdentified?: () => void): Promise<NfcResult>;
 /** Write a user nickname (password required for authentication). */
-export declare function writeUserNickname(password: string, nickname: string): Promise<NfcResult>;
+export declare function writeUserNickname(password: string, nickname: string, onCardIdentified?: () => void): Promise<NfcResult>;
 /**
  * Reset card: wipe user data, set password to "000000".
  * @param password – current card password (required if protection is enabled).

package/dist/writer.js

@@ -101,6 +101,13 @@ async function writeUserMemory(data) {
         }
     }
 }
+/** FAST_READ pages 0x08–0x27 (user memory). */
+async function readUserMemory() {
+    const response = await (0, nfc_core_1.transceive)([constants_1.CMD_FAST_READ, constants_1.USER_PAGE_START, constants_1.USER_PAGE_END]);
+    if (!response || response.length < constants_1.USER_MEMORY_SIZE)
+        throw new Error('READ_FAILED');
+    return new Uint8Array(response.slice(0, constants_1.USER_MEMORY_SIZE));
+}
 /**
  * Write a 16-byte AES key to AES_KEY0 (pages 0x30–0x33).
  * Byte order is reversed per the datasheet.
@@ -273,8 +280,13 @@ async function initializeCard(mnemonic, password, onCardIdentified) {
 }
 /**
  * Update card: authenticate with old password, then write new mnemonic + new password.
+ *
+ * When `options.precheckExistingMnemonic` is true, the card is read after authentication.
+ * If a valid mnemonic backup already exists, the write is skipped and PRECHECK_HAS_BACKUP
+ * is returned (`success: true` — operation completed; distinguish outcome by `code`).
+ * Otherwise the normal write flow proceeds.
  */
-async function updateCard(oldPassword, newPassword, newMnemonic, onCardIdentified) {
+async function updateCard(oldPassword, newPassword, newMnemonic, onCardIdentified, options) {
     try {
         await (0, nfc_core_1.acquireNfcLock)();
     }
@@ -297,7 +309,14 @@ async function updateCard(oldPassword, newPassword, newMnemonic, onCardIdentifie
                 if (typeof n === 'number')
                     retryCountAfterPreDecrement = n;
             }
-            catch { /* non-fatal */ }
+            catch (error) {
+                const code = (0, types_1.errorToCode)(error);
+                if (code === types_1.ResultCode.RETRY_COUNT_EXHAUSTED) {
+                    await (0, nfc_core_1.releaseNfcTech)();
+                    (0, nfc_core_1.releaseNfcLock)();
+                    return (0, types_1.nfcResultRetryCountExhausted)();
+                }
+            }
             const oldKey = (0, crypto_1.passwordToAesKey)(oldPassword);
             await (0, nfc_core_1.authenticate)(oldKey);
             try {
@@ -305,6 +324,32 @@ async function updateCard(oldPassword, newPassword, newMnemonic, onCardIdentifie
             }
             catch { /* non-fatal */ }
             onCardIdentified?.();
+            if (options?.precheckExistingMnemonic) {
+                try {
+                    const data = await readUserMemory();
+                    const decoded = (0, utils_1.validateMnemonicPayload)(data);
+                    await (0, nfc_core_1.releaseNfcTech)();
+                    (0, nfc_core_1.releaseNfcLock)();
+                    return {
+                        code: types_1.ResultCode.PRECHECK_HAS_BACKUP,
+                        success: true,
+                        data: { type: decoded.type, retryCount: constants_1.DEFAULT_PIN_RETRY_COUNT },
+                    };
+                }
+                catch (e) {
+                    const c = (0, types_1.errorToCode)(e);
+                    if (c === types_1.ResultCode.CHECK_EMPTY ||
+                        c === types_1.ResultCode.CRC16_CHECK_FAILED ||
+                        c === types_1.ResultCode.INVALID_CARD_DATA) {
+                        // No valid mnemonic on card — fall through to write
+                    }
+                    else {
+                        await (0, nfc_core_1.releaseNfcTech)();
+                        (0, nfc_core_1.releaseNfcLock)();
+                        return { code: c, success: false };
+                    }
+                }
+            }
             await disableAuth();
             await writeUserMemory(entropyResult.data);
             const newKey = (0, crypto_1.passwordToAesKey)(newPassword);
@@ -366,7 +411,14 @@ async function updatePassword(oldPassword, newPassword, onCardIdentified) {
                 if (typeof n === 'number')
                     retryCountAfterPreDecrement = n;
             }
-            catch { /* non-fatal */ }
+            catch (error) {
+                const code = (0, types_1.errorToCode)(error);
+                if (code === types_1.ResultCode.RETRY_COUNT_EXHAUSTED) {
+                    await (0, nfc_core_1.releaseNfcTech)();
+                    (0, nfc_core_1.releaseNfcLock)();
+                    return (0, types_1.nfcResultRetryCountExhausted)();
+                }
+            }
             const oldKey = (0, crypto_1.passwordToAesKey)(oldPassword);
             await (0, nfc_core_1.authenticate)(oldKey);
             try {
@@ -404,7 +456,7 @@ async function updatePassword(oldPassword, newPassword, onCardIdentified) {
     }
 }
 /** Write a user nickname (password required for authentication). */
-async function writeUserNickname(password, nickname) {
+async function writeUserNickname(password, nickname, onCardIdentified) {
     try {
         await (0, nfc_core_1.acquireNfcLock)();
     }
@@ -422,6 +474,7 @@ async function writeUserNickname(password, nickname) {
         try {
             const aesKey = (0, crypto_1.passwordToAesKey)(password);
             await (0, nfc_core_1.authenticate)(aesKey);
+            onCardIdentified?.();
             await disableAuth();
             await writeNicknameToCard(nickname);
             await configureAuth();
@@ -471,7 +524,14 @@ async function resetCard(password, onCardIdentified) {
                     if (typeof n === 'number')
                         retryCountAfterPreDecrement = n;
                 }
-                catch { /* non-fatal */ }
+                catch (error) {
+                    const code = (0, types_1.errorToCode)(error);
+                    if (code === types_1.ResultCode.RETRY_COUNT_EXHAUSTED) {
+                        await (0, nfc_core_1.releaseNfcTech)();
+                        (0, nfc_core_1.releaseNfcLock)();
+                        return (0, types_1.nfcResultRetryCountExhausted)();
+                    }
+                }
                 const aesKey = (0, crypto_1.passwordToAesKey)(password);
                 try {
                     await (0, nfc_core_1.authenticate)(aesKey);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ukeyfe/react-native-nfc-litecard",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "NFC read/write for MIFARE Ultralight AES (LiteCard mnemonic storage)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,6 +27,7 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "README.en.md"
   ]
 }