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

package/{README.en.md → README.zh.md}

@@ -1,6 +1,6 @@
 # @ukeyfe/react-native-nfc-litecard
 
-English | [中文](./README.md)
+[English](./README.md) | 中文
 
 React Native NFC read/write library for **MIFARE Ultralight AES** (MF0AES(H)20), designed for LiteCard mnemonic storage.
 
@@ -19,7 +19,7 @@ React Native NFC read/write library for **MIFARE Ultralight AES** (MF0AES(H)20),
 | Update card | `updateCard()` | Update mnemonic & password (old password required) |
 | Change password | `updatePassword()` | Change password only (old password required) |
 | Write nickname | `writeUserNickname()` | Write user nickname to card |
-| Reset card | `resetCard()` | Wipe data, reset password to "000000" |
+| Reset card | `resetCard()` | Wipe mnemonic data, set a new password |
 
 ## Installation
 
@@ -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,26 +239,39 @@ 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?)`
+### `resetCard(password, newPassword, onCardIdentified?)`
 
-Reset card: wipe all user data, set password to `"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('Reset successful');
 }
 ```
 
-> ⚠️ 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 \| 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?)`
 
-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 +280,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 +366,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 +390,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 +410,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 +436,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 +444,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/dist/constants.d.ts

@@ -43,6 +43,10 @@ export declare const MNEMONIC_TYPE_18 = 3;
 export declare const MNEMONIC_TYPE_21 = 4;
 /** 24-word mnemonic (256-bit entropy, 32 bytes) */
 export declare const MNEMONIC_TYPE_24 = 5;
+/** Mnemonic data end page (stops before nickname area) */
+export declare const MNEMONIC_PAGE_END: number;
+/** Mnemonic data size: (0x24 - 0x08 + 1) * 4 = 116 bytes */
+export declare const MNEMONIC_MEMORY_SIZE: number;
 /** Nickname start page */
 export declare const USER_NICKNAME_PAGE_START: number;
 /** Nickname end page */

package/dist/constants.js

@@ -3,7 +3,7 @@
  * Shared constants for MIFARE Ultralight AES (MF0AES(H)20) NFC operations.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_PIN_RETRY_COUNT = exports.RETRY_COUNTER_OFFSET = exports.RETRY_COUNTER_PAGE = exports.USER_NICKNAME_MAX_LENGTH = exports.USER_NICKNAME_PAGE_END = exports.USER_NICKNAME_PAGE_START = exports.MNEMONIC_TYPE_24 = exports.MNEMONIC_TYPE_21 = exports.MNEMONIC_TYPE_18 = exports.MNEMONIC_TYPE_15 = exports.MNEMONIC_TYPE_12 = exports.USER_CARD_INFO_SIZE = exports.USER_MEMORY_SIZE = exports.PAGE_AES_KEY0_START = exports.PAGE_CFG1 = exports.PAGE_CFG0 = exports.USER_CARD_INFO_PAGE_END = exports.USER_CARD_INFO_PAGE_START = exports.USER_PAGE_END = exports.USER_PAGE_START = exports.PAGE_SIZE = exports.KEY_NO_DATA_PROT = exports.CMD_AUTH_PART2 = exports.CMD_AUTH_PART1 = exports.CMD_FAST_READ = exports.CMD_WRITE = exports.CMD_READ = void 0;
+exports.DEFAULT_PIN_RETRY_COUNT = exports.RETRY_COUNTER_OFFSET = exports.RETRY_COUNTER_PAGE = exports.USER_NICKNAME_MAX_LENGTH = exports.USER_NICKNAME_PAGE_END = exports.USER_NICKNAME_PAGE_START = exports.MNEMONIC_MEMORY_SIZE = exports.MNEMONIC_PAGE_END = exports.MNEMONIC_TYPE_24 = exports.MNEMONIC_TYPE_21 = exports.MNEMONIC_TYPE_18 = exports.MNEMONIC_TYPE_15 = exports.MNEMONIC_TYPE_12 = exports.USER_CARD_INFO_SIZE = exports.USER_MEMORY_SIZE = exports.PAGE_AES_KEY0_START = exports.PAGE_CFG1 = exports.PAGE_CFG0 = exports.USER_CARD_INFO_PAGE_END = exports.USER_CARD_INFO_PAGE_START = exports.USER_PAGE_END = exports.USER_PAGE_START = exports.PAGE_SIZE = exports.KEY_NO_DATA_PROT = exports.CMD_AUTH_PART2 = exports.CMD_AUTH_PART1 = exports.CMD_FAST_READ = exports.CMD_WRITE = exports.CMD_READ = void 0;
 // ---------------------------------------------------------------------------
 // NFC command codes
 // ---------------------------------------------------------------------------
@@ -59,6 +59,13 @@ exports.MNEMONIC_TYPE_21 = 0x04;
 /** 24-word mnemonic (256-bit entropy, 32 bytes) */
 exports.MNEMONIC_TYPE_24 = 0x05;
 // ---------------------------------------------------------------------------
+// Mnemonic data area (excludes nickname pages)
+// ---------------------------------------------------------------------------
+/** Mnemonic data end page (stops before nickname area) */
+exports.MNEMONIC_PAGE_END = exports.USER_PAGE_END - 3; // 0x24
+/** Mnemonic data size: (0x24 - 0x08 + 1) * 4 = 116 bytes */
+exports.MNEMONIC_MEMORY_SIZE = (exports.MNEMONIC_PAGE_END - exports.USER_PAGE_START + 1) * exports.PAGE_SIZE;
+// ---------------------------------------------------------------------------
 // User nickname area (last 3 pages of user memory)
 // ---------------------------------------------------------------------------
 /** Nickname start page */

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.