@ukeyfe/react-native-nfc-litecard 1.0.0

package/dist/index.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * @ukeyfe/react-native-nfc-litecard
+ *
+ * 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;
+// ---------------------------------------------------------------------------
+// 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; } });
+// ---------------------------------------------------------------------------
+// Reader API
+// ---------------------------------------------------------------------------
+var reader_1 = require("./reader");
+Object.defineProperty(exports, "checkCard", { enumerable: true, get: function () { return reader_1.checkCard; } });
+Object.defineProperty(exports, "readMnemonic", { enumerable: true, get: function () { return reader_1.readMnemonic; } });
+Object.defineProperty(exports, "readUserNickname", { enumerable: true, get: function () { return reader_1.readUserNickname; } });
+Object.defineProperty(exports, "readMnemonicRetryCount", { enumerable: true, get: function () { return reader_1.readMnemonicRetryCount; } });
+Object.defineProperty(exports, "resetRetryCountTo10", { enumerable: true, get: function () { return reader_1.resetRetryCountTo10; } });
+Object.defineProperty(exports, "cardInfoToJson", { enumerable: true, get: function () { return reader_1.cardInfoToJson; } });
+// ---------------------------------------------------------------------------
+// Writer API
+// ---------------------------------------------------------------------------
+var writer_1 = require("./writer");
+Object.defineProperty(exports, "initializeCard", { enumerable: true, get: function () { return writer_1.initializeCard; } });
+Object.defineProperty(exports, "updateCard", { enumerable: true, get: function () { return writer_1.updateCard; } });
+Object.defineProperty(exports, "updatePassword", { enumerable: true, get: function () { return writer_1.updatePassword; } });
+Object.defineProperty(exports, "writeUserNickname", { enumerable: true, get: function () { return writer_1.writeUserNickname; } });
+Object.defineProperty(exports, "resetCard", { enumerable: true, get: function () { return writer_1.resetCard; } });
+// ---------------------------------------------------------------------------
+// NFC lock & cleanup helpers (for app-level lifecycle management)
+// ---------------------------------------------------------------------------
+var nfc_core_1 = require("./nfc-core");
+Object.defineProperty(exports, "isNfcOperationLocked", { enumerable: true, get: function () { return nfc_core_1.isNfcOperationLocked; } });
+Object.defineProperty(exports, "releaseNfcOperationLock", { enumerable: true, get: function () { return nfc_core_1.releaseNfcOperationLock; } });
+Object.defineProperty(exports, "markNfcOperationCancelledByCleanup", { enumerable: true, get: function () { return nfc_core_1.markNfcOperationCancelledByCleanup; } });
+Object.defineProperty(exports, "consumeNfcOperationCancelledByCleanup", { enumerable: true, get: function () { return nfc_core_1.consumeNfcOperationCancelledByCleanup; } });
+Object.defineProperty(exports, "getNfcOperationCancelledByCleanupTimestamp", { enumerable: true, get: function () { return nfc_core_1.getNfcOperationCancelledByCleanupTimestamp; } });
+Object.defineProperty(exports, "clearNfcOperationCancelledByCleanup", { enumerable: true, get: function () { return nfc_core_1.clearNfcOperationCancelledByCleanup; } });
+// ---------------------------------------------------------------------------
+// Constants that apps may need
+// ---------------------------------------------------------------------------
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "DEFAULT_PIN_RETRY_COUNT", { enumerable: true, get: function () { return constants_1.DEFAULT_PIN_RETRY_COUNT; } });

package/dist/nfc-core.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Core NFC communication layer – shared by reader and writer.
+ *
+ * Provides:
+ *   - A single global operation lock (prevents reader/writer concurrency)
+ *   - Page-cleanup cancellation flags
+ *   - Low-level transceive with platform-aware retries
+ *   - NFC technology request / release
+ *   - AES 3-pass mutual authentication (MF0AES(H)20 §8.6.1)
+ *   - PIN retry-counter helpers (session-level read/write)
+ */
+import { passwordToAesKey } from './crypto';
+export { passwordToAesKey };
+/**
+ * Acquire the NFC operation lock.
+ * If another operation is in progress, polls every 100 ms for up to 10 s.
+ */
+export declare function acquireNfcLock(): Promise<void>;
+export declare function releaseNfcLock(): void;
+export declare function isNfcOperationLocked(): boolean;
+export declare function releaseNfcOperationLock(): void;
+export declare function markNfcOperationCancelledByCleanup(): void;
+export declare function consumeNfcOperationCancelledByCleanup(): boolean;
+export declare function getNfcOperationCancelledByCleanupTimestamp(): number;
+export declare function clearNfcOperationCancelledByCleanup(): void;
+/**
+ * Send a command to the NFC tag and return the response.
+ *
+ * Retries: Android up to 2 retries (3 total), iOS up to 1 retry (2 total).
+ */
+export declare function transceive(command: number[], _timeoutMs?: number, retryCount?: number): Promise<number[]>;
+/**
+ * Request an NFC technology session (MifareIOS on iOS, NfcA on Android).
+ *
+ * All prior cleanup must be done by the caller BEFORE invoking this.
+ */
+export declare function requestNfcTech(): Promise<void>;
+/**
+ * Release the NFC technology session.
+ * @param forceLongDelay Use a longer post-release delay (e.g. after timeout / tag-lost).
+ */
+export declare function releaseNfcTech(forceLongDelay?: boolean): Promise<void>;
+/**
+ * Perform AES 3-pass mutual authentication (MF0AES(H)20 §8.6.1).
+ *
+ * 1. PCD → PICC : AUTH_PART1 (0x1A) + KeyNo
+ * 2. PICC → PCD : 0xAF + ek(RndB)
+ * 3. PCD decrypts RndB, generates RndA, computes RndB' = rotateLeft8(RndB)
+ * 4. PCD → PICC : AUTH_PART2 (0xAF) + ek(RndA ‖ RndB')
+ * 5. PICC → PCD : 0x00 + ek(RndA')
+ * 6. PCD verifies RndA' === rotateLeft8(RndA)
+ *
+ * @throws AUTH_INVALID_RESPONSE / AUTH_WRONG_PASSWORD / AUTH_VERIFY_FAILED
+ */
+export declare function authenticate(key: Uint8Array): Promise<void>;
+/**
+ * Decrement the on-card retry counter by 1 (clamped to 0).
+ * Must be called within an active NFC session (between requestNfcTech and releaseNfcTech).
+ */
+export declare function decrementRetryCountInSession(): Promise<number | undefined>;
+/**
+ * Write a specific retry count to the on-card counter.
+ * Must be called within an active NFC session.
+ */
+export declare function writeRetryCountInSession(count: number): Promise<void>;

package/dist/nfc-core.js

@@ -0,0 +1,277 @@
+"use strict";
+/**
+ * Core NFC communication layer – shared by reader and writer.
+ *
+ * Provides:
+ *   - A single global operation lock (prevents reader/writer concurrency)
+ *   - Page-cleanup cancellation flags
+ *   - Low-level transceive with platform-aware retries
+ *   - NFC technology request / release
+ *   - AES 3-pass mutual authentication (MF0AES(H)20 §8.6.1)
+ *   - PIN retry-counter helpers (session-level read/write)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.passwordToAesKey = void 0;
+exports.acquireNfcLock = acquireNfcLock;
+exports.releaseNfcLock = releaseNfcLock;
+exports.isNfcOperationLocked = isNfcOperationLocked;
+exports.releaseNfcOperationLock = releaseNfcOperationLock;
+exports.markNfcOperationCancelledByCleanup = markNfcOperationCancelledByCleanup;
+exports.consumeNfcOperationCancelledByCleanup = consumeNfcOperationCancelledByCleanup;
+exports.getNfcOperationCancelledByCleanupTimestamp = getNfcOperationCancelledByCleanupTimestamp;
+exports.clearNfcOperationCancelledByCleanup = clearNfcOperationCancelledByCleanup;
+exports.transceive = transceive;
+exports.requestNfcTech = requestNfcTech;
+exports.releaseNfcTech = releaseNfcTech;
+exports.authenticate = authenticate;
+exports.decrementRetryCountInSession = decrementRetryCountInSession;
+exports.writeRetryCountInSession = writeRetryCountInSession;
+const react_native_nfc_manager_1 = __importStar(require("react-native-nfc-manager"));
+const react_native_1 = require("react-native");
+const constants_1 = require("./constants");
+const crypto_1 = require("./crypto");
+Object.defineProperty(exports, "passwordToAesKey", { enumerable: true, get: function () { return crypto_1.passwordToAesKey; } });
+// ===========================================================================
+// Global NFC operation lock (single instance for both reader & writer)
+// ===========================================================================
+let nfcOperationLock = false;
+/**
+ * Acquire the NFC operation lock.
+ * If another operation is in progress, polls every 100 ms for up to 10 s.
+ */
+async function acquireNfcLock() {
+    const maxWait = 10000;
+    const interval = 100;
+    let waited = 0;
+    while (nfcOperationLock) {
+        if (waited >= maxWait)
+            throw new Error('NFC_LOCK_TIMEOUT');
+        await new Promise(r => setTimeout(r, interval));
+        waited += interval;
+    }
+    nfcOperationLock = true;
+    clearNfcOperationCancelledByCleanup();
+}
+function releaseNfcLock() {
+    nfcOperationLock = false;
+}
+function isNfcOperationLocked() {
+    return nfcOperationLock;
+}
+function releaseNfcOperationLock() {
+    releaseNfcLock();
+}
+// ===========================================================================
+// Page-cleanup cancellation flag
+// ===========================================================================
+let nfcCancelledByCleanup = false;
+let nfcCancelledByCleanupTimestamp = 0;
+function markNfcOperationCancelledByCleanup() {
+    nfcCancelledByCleanup = true;
+    nfcCancelledByCleanupTimestamp = Date.now();
+}
+function consumeNfcOperationCancelledByCleanup() {
+    const cancelled = nfcCancelledByCleanup;
+    nfcCancelledByCleanup = false;
+    nfcCancelledByCleanupTimestamp = 0;
+    return cancelled;
+}
+function getNfcOperationCancelledByCleanupTimestamp() {
+    return nfcCancelledByCleanupTimestamp;
+}
+function clearNfcOperationCancelledByCleanup() {
+    nfcCancelledByCleanup = false;
+    nfcCancelledByCleanupTimestamp = 0;
+}
+// ===========================================================================
+// Low-level NFC transceive
+// ===========================================================================
+/**
+ * Send a command to the NFC tag and return the response.
+ *
+ * Retries: Android up to 2 retries (3 total), iOS up to 1 retry (2 total).
+ */
+async function transceive(command, _timeoutMs = 2000, retryCount = 0) {
+    try {
+        const result = react_native_1.Platform.OS === 'ios'
+            ? await react_native_nfc_manager_1.default.sendMifareCommandIOS(command)
+            : await react_native_nfc_manager_1.default.nfcAHandler.transceive(command);
+        return result;
+    }
+    catch (error) {
+        const maxRetries = react_native_1.Platform.OS === 'ios' ? 1 : 2;
+        if (retryCount < maxRetries) {
+            const wait = 200 * (retryCount + 1);
+            await new Promise(r => setTimeout(r, wait));
+            return transceive(command, _timeoutMs, retryCount + 1);
+        }
+        throw error;
+    }
+}
+// ===========================================================================
+// NFC technology connect / disconnect
+// ===========================================================================
+/**
+ * Request an NFC technology session (MifareIOS on iOS, NfcA on Android).
+ *
+ * All prior cleanup must be done by the caller BEFORE invoking this.
+ */
+async function requestNfcTech() {
+    await new Promise(r => setTimeout(r, 100));
+    if (react_native_1.Platform.OS === 'ios') {
+        await react_native_nfc_manager_1.default.requestTechnology(react_native_nfc_manager_1.NfcTech.MifareIOS);
+    }
+    else {
+        await react_native_nfc_manager_1.default.requestTechnology(react_native_nfc_manager_1.NfcTech.NfcA);
+    }
+    if (react_native_1.Platform.OS === 'android') {
+        await new Promise(r => setTimeout(r, 300));
+    }
+    else {
+        // iOS: probe connection availability
+        try {
+            await react_native_nfc_manager_1.default.sendMifareCommandIOS([constants_1.CMD_READ, 0x00]);
+        }
+        catch (_) {
+            // Non-fatal – continue even if the probe fails
+        }
+    }
+}
+/**
+ * Release the NFC technology session.
+ * @param forceLongDelay Use a longer post-release delay (e.g. after timeout / tag-lost).
+ */
+async function releaseNfcTech(forceLongDelay = false) {
+    try {
+        await react_native_nfc_manager_1.default.cancelTechnologyRequest();
+        const delay = react_native_1.Platform.OS === 'ios'
+            ? (forceLongDelay ? 300 : 100)
+            : (forceLongDelay ? 1000 : 800);
+        await new Promise(r => setTimeout(r, delay));
+    }
+    catch (error) {
+        console.warn('[nfc-core] releaseNfcTech failed:', error?.message);
+    }
+}
+// ===========================================================================
+// AES 3-pass mutual authentication
+// ===========================================================================
+/**
+ * Perform AES 3-pass mutual authentication (MF0AES(H)20 §8.6.1).
+ *
+ * 1. PCD → PICC : AUTH_PART1 (0x1A) + KeyNo
+ * 2. PICC → PCD : 0xAF + ek(RndB)
+ * 3. PCD decrypts RndB, generates RndA, computes RndB' = rotateLeft8(RndB)
+ * 4. PCD → PICC : AUTH_PART2 (0xAF) + ek(RndA ‖ RndB')
+ * 5. PICC → PCD : 0x00 + ek(RndA')
+ * 6. PCD verifies RndA' === rotateLeft8(RndA)
+ *
+ * @throws AUTH_INVALID_RESPONSE / AUTH_WRONG_PASSWORD / AUTH_VERIFY_FAILED
+ */
+async function authenticate(key) {
+    const iv0 = new Uint8Array(16);
+    // Step 1
+    const response1 = await transceive([constants_1.CMD_AUTH_PART1, constants_1.KEY_NO_DATA_PROT]);
+    if (!response1 || response1.length < 17 || response1[0] !== 0xaf) {
+        throw new Error('AUTH_INVALID_RESPONSE');
+    }
+    // Step 2 – decrypt RndB
+    const ekRndB = new Uint8Array(response1.slice(1, 17));
+    const rndB = (0, crypto_1.aesDecrypt)(key, ekRndB, iv0);
+    // Step 3
+    const rndBRot = (0, crypto_1.rotateLeft8)(rndB);
+    const rndA = (0, crypto_1.generateRandom16)();
+    // Step 4 – encrypt RndA ‖ RndB' (CBC, two 16-byte blocks)
+    const rndAB = new Uint8Array(32);
+    rndAB.set(rndA, 0);
+    rndAB.set(rndBRot, 16);
+    const ekPart1 = (0, crypto_1.aesEncrypt)(key, rndAB.slice(0, 16), iv0);
+    const ekPart2 = (0, crypto_1.aesEncrypt)(key, rndAB.slice(16, 32), ekPart1);
+    const ekRndAB = new Uint8Array(32);
+    ekRndAB.set(ekPart1, 0);
+    ekRndAB.set(ekPart2, 16);
+    // Step 5
+    let response2 = null;
+    try {
+        response2 = await transceive([constants_1.CMD_AUTH_PART2, ...Array.from(ekRndAB)]);
+    }
+    catch (_) {
+        // AUTH_PART2 transceive failure usually means wrong password
+        throw new Error('AUTH_WRONG_PASSWORD');
+    }
+    if (!response2 || response2.length < 17 || response2[0] !== 0x00) {
+        throw new Error('AUTH_WRONG_PASSWORD');
+    }
+    // Step 6 – verify RndA'
+    const ekRndARot = new Uint8Array(response2.slice(1, 17));
+    const rndARot = (0, crypto_1.aesDecrypt)(key, ekRndARot, iv0);
+    const expectedRndARot = (0, crypto_1.rotateLeft8)(rndA);
+    if (!(0, crypto_1.arraysEqual)(rndARot, expectedRndARot)) {
+        throw new Error('AUTH_VERIFY_FAILED');
+    }
+}
+// ===========================================================================
+// PIN retry-counter session helpers
+// ===========================================================================
+/**
+ * Decrement the on-card retry counter by 1 (clamped to 0).
+ * Must be called within an active NFC session (between requestNfcTech and releaseNfcTech).
+ */
+async function decrementRetryCountInSession() {
+    const pageBlock = await transceive([constants_1.CMD_READ, constants_1.RETRY_COUNTER_PAGE]);
+    if (!pageBlock || pageBlock.length < constants_1.PAGE_SIZE)
+        return undefined;
+    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;
+    page[constants_1.RETRY_COUNTER_OFFSET] = next & 0xff;
+    await transceive([constants_1.CMD_WRITE, constants_1.RETRY_COUNTER_PAGE, ...page]);
+    return next;
+}
+/**
+ * Write a specific retry count to the on-card counter.
+ * Must be called within an active NFC session.
+ */
+async function writeRetryCountInSession(count) {
+    const safeCount = Math.max(0, Math.min(0xff, count | 0));
+    const pageBlock = await transceive([constants_1.CMD_READ, constants_1.RETRY_COUNTER_PAGE]);
+    if (!pageBlock || pageBlock.length < constants_1.PAGE_SIZE)
+        throw new Error('READ_FAILED');
+    const page = pageBlock.slice(0, constants_1.PAGE_SIZE);
+    page[constants_1.RETRY_COUNTER_OFFSET] = safeCount & 0xff;
+    await transceive([constants_1.CMD_WRITE, constants_1.RETRY_COUNTER_PAGE, ...page]);
+}

package/dist/reader.d.ts

@@ -0,0 +1,82 @@
+/**
+ * NFC Reader Module
+ *
+ * Public API:
+ *   - checkCard()          – detect whether a card is empty or contains data
+ *   - readMnemonic()       – read mnemonic (password required)
+ *   - readUserNickname()   – read user nickname (password optional)
+ *   - readMnemonicRetryCount() – read the PIN retry counter
+ *   - resetRetryCountTo10()    – reset the retry counter to default
+ *   - cardInfoToJson()     – serialise card-info to JSON
+ *
+ * Based on MIFARE Ultralight AES (MF0AES(H)20) datasheet.
+ */
+import { DEFAULT_PIN_RETRY_COUNT } from './constants';
+import { ResultCode, type NfcResult } from './types';
+import { isNfcOperationLocked, releaseNfcOperationLock, markNfcOperationCancelledByCleanup, consumeNfcOperationCancelledByCleanup, getNfcOperationCancelledByCleanupTimestamp, clearNfcOperationCancelledByCleanup } from './nfc-core';
+export { ResultCode, type NfcResult, isNfcOperationLocked, releaseNfcOperationLock, markNfcOperationCancelledByCleanup, consumeNfcOperationCancelledByCleanup, getNfcOperationCancelledByCleanupTimestamp, clearNfcOperationCancelledByCleanup, DEFAULT_PIN_RETRY_COUNT, };
+declare function parseCardInfo(data: Uint8Array): {
+    version: number;
+    cardType: number;
+    rawBytes: string;
+    infoBytes: Uint8Array<ArrayBuffer>;
+    json: {
+        pageInfo: {
+            startPage: number;
+            endPage: number;
+            totalPages: number;
+            totalBytes: number;
+        };
+        version: {
+            value: number;
+            hex: string;
+        };
+        cardType: {
+            value: number;
+            hex: string;
+            description: string;
+            known: boolean;
+        };
+        additionalInfo: {
+            hex: string;
+            bytes: number[];
+        };
+        rawData: {
+            hex: string;
+            bytes: number[];
+            length: number;
+        };
+        pageBreakdown: {
+            page: number;
+            bytes: number[];
+            hex: string;
+        }[];
+    };
+};
+/** Serialise parseCardInfo result to JSON. */
+export declare function cardInfoToJson(cardInfo: ReturnType<typeof parseCardInfo>, pretty?: boolean): string;
+/**
+ * Detect whether the card is empty or already contains data.
+ *
+ * Logic:
+ *   - 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)
+ */
+export declare function checkCard(onCardIdentified?: () => void): Promise<NfcResult>;
+/**
+ * Read the mnemonic from a password-protected card.
+ *
+ * Flow: connect → pre-decrement retry counter → authenticate → read →
+ *       decode entropy → read nickname → reset retry counter → release
+ */
+export declare function readMnemonic(password: string, onCardIdentified?: () => void): Promise<NfcResult>;
+/**
+ * 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>;
+/** Read the current PIN retry counter from the card. */
+export declare function readMnemonicRetryCount(): Promise<NfcResult>;
+/** Reset the PIN retry counter to the default value (10). */
+export declare function resetRetryCountTo10(): Promise<NfcResult>;