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

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,14 +19,23 @@ 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".
+ * Reset card: wipe mnemonic data and set a new password.
  * @param password – current card password (required if protection is enabled).
+ * @param newPassword – password to set after reset.
+ * @param onCardIdentified – callback when card is identified.
  */
-export declare function resetCard(password?: string, onCardIdentified?: () => void): Promise<NfcResult>;
+export declare function resetCard(password: string | undefined, newPassword: string, onCardIdentified?: () => void): Promise<NfcResult>;

package/dist/writer.js

@@ -77,13 +77,14 @@ async function writePage(page, data) {
     await (0, nfc_core_1.transceive)([constants_1.CMD_WRITE, page, ...data]);
 }
 /**
- * Write data to user memory (pages 0x08–0x27).
+ * Write data to mnemonic area (pages 0x08–0x24).
+ * Does NOT touch the nickname area (pages 0x25–0x27).
  * iOS: inserts small delays and periodic keep-alive reads.
  */
 async function writeUserMemory(data) {
-    const buffer = new Uint8Array(constants_1.USER_MEMORY_SIZE);
-    buffer.set(data, 0);
-    const totalPages = constants_1.USER_PAGE_END - constants_1.USER_PAGE_START + 1;
+    const buffer = new Uint8Array(constants_1.MNEMONIC_MEMORY_SIZE);
+    buffer.set(data.slice(0, constants_1.MNEMONIC_MEMORY_SIZE), 0);
+    const totalPages = constants_1.MNEMONIC_PAGE_END - constants_1.USER_PAGE_START + 1;
     for (let i = 0; i < totalPages; i++) {
         const page = constants_1.USER_PAGE_START + i;
         const offset = i * constants_1.PAGE_SIZE;
@@ -101,6 +102,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 +281,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)();
     }
@@ -291,22 +304,57 @@ async function updateCard(oldPassword, newPassword, newMnemonic, onCardIdentifie
             return { code: types_1.ResultCode.NFC_CONNECT_FAILED, success: false };
         }
         try {
-            const entropyResult = mnemonicToEntropyWithCRC(newMnemonic);
             try {
                 const n = await (0, nfc_core_1.decrementRetryCountInSession)();
                 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)();
+                }
+                // Communication failure — counter was not decremented, continue to auth
+            }
             const oldKey = (0, crypto_1.passwordToAesKey)(oldPassword);
             await (0, nfc_core_1.authenticate)(oldKey);
             try {
                 await (0, nfc_core_1.writeRetryCountInSession)(constants_1.DEFAULT_PIN_RETRY_COUNT);
+                retryCountAfterPreDecrement = constants_1.DEFAULT_PIN_RETRY_COUNT;
             }
             catch { /* non-fatal */ }
             onCardIdentified?.();
-            await disableAuth();
+            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 };
+                    }
+                }
+            }
+            const entropyResult = mnemonicToEntropyWithCRC(newMnemonic);
             await writeUserMemory(entropyResult.data);
+            await disableAuth();
             const newKey = (0, crypto_1.passwordToAesKey)(newPassword);
             const aesKeyHex = (0, utils_1.bytesToHex)(newKey);
             await writeAesKey(newKey);
@@ -366,11 +414,20 @@ 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)();
+                }
+                // Communication failure — counter was not decremented, continue to auth
+            }
             const oldKey = (0, crypto_1.passwordToAesKey)(oldPassword);
             await (0, nfc_core_1.authenticate)(oldKey);
             try {
                 await (0, nfc_core_1.writeRetryCountInSession)(constants_1.DEFAULT_PIN_RETRY_COUNT);
+                retryCountAfterPreDecrement = constants_1.DEFAULT_PIN_RETRY_COUNT;
             }
             catch { /* non-fatal */ }
             onCardIdentified?.();
@@ -404,7 +461,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 +479,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();
@@ -445,10 +503,12 @@ async function writeUserNickname(password, nickname) {
     }
 }
 /**
- * Reset card: wipe user data, set password to "000000".
+ * Reset card: wipe mnemonic data and set a new password.
  * @param password – current card password (required if protection is enabled).
+ * @param newPassword – password to set after reset.
+ * @param onCardIdentified – callback when card is identified.
  */
-async function resetCard(password, onCardIdentified) {
+async function resetCard(password, newPassword, onCardIdentified) {
     try {
         await (0, nfc_core_1.acquireNfcLock)();
     }
@@ -471,12 +531,21 @@ 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)();
+                    }
+                    // Communication failure — counter was not decremented, continue to auth
+                }
                 const aesKey = (0, crypto_1.passwordToAesKey)(password);
                 try {
                     await (0, nfc_core_1.authenticate)(aesKey);
                     try {
                         await (0, nfc_core_1.writeRetryCountInSession)(constants_1.DEFAULT_PIN_RETRY_COUNT);
+                        retryCountAfterPreDecrement = constants_1.DEFAULT_PIN_RETRY_COUNT;
                     }
                     catch { /* non-fatal */ }
                 }
@@ -507,11 +576,11 @@ async function resetCard(password, onCardIdentified) {
                 }
                 onCardIdentified?.();
             }
-            // Wipe user memory
-            await writeUserMemory(new Uint8Array(constants_1.USER_MEMORY_SIZE));
-            // Set default password "000000"
-            const defaultKey = (0, crypto_1.passwordToAesKey)('000000');
-            await writeAesKey(defaultKey);
+            // Wipe mnemonic data (nickname is preserved)
+            await writeUserMemory(new Uint8Array(constants_1.MNEMONIC_MEMORY_SIZE));
+            // Set new password
+            const resetKey = (0, crypto_1.passwordToAesKey)(newPassword);
+            await writeAesKey(resetKey);
             // Ensure protection is disabled
             try {
                 await disableAuth();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ukeyfe/react-native-nfc-litecard",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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.zh.md"
   ]
 }