@ukeyfe/react-native-nfc-litecard 1.0.5 → 1.0.7

package/dist/index.d.ts

@@ -1,10 +1,242 @@
 /**
- * @ukeyfe/react-native-nfc-litecard
+ * Unified result codes, NfcResult interface, and error mapping helpers.
  *
- * NFC read/write library for MIFARE Ultralight AES (LiteCard mnemonic storage).
+ * All codes are unique across reader and writer to prevent ambiguity.
+ *   - Reader success : 101xx
+ *   - Writer success : 102xx
+ *   - Failure        : 4xxxx (shared)
+ *
+ * This library does NOT provide user-facing messages.
+ * The caller should map NfcStatusCode to their own localised strings.
+ */
+declare const NfcStatusCode: {
+    readonly READ_SUCCESS: 10102;
+    readonly READ_NICKNAME_SUCCESS: 10103;
+    readonly CHECK_EMPTY: 10104;
+    readonly CHECK_HAS_DATA: 10105;
+    readonly READ_RETRY_COUNT_SUCCESS: 10106;
+    readonly GET_VERSION_SUCCESS: 10107;
+    readonly READ_SIG_SUCCESS: 10108;
+    readonly INIT_SUCCESS: 10201;
+    readonly WRITE_SUCCESS: 10203;
+    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;
+    readonly AUTH_VERIFY_FAILED: 40004;
+    readonly READ_FAILED: 40005;
+    readonly WRITE_FAILED: 40006;
+    readonly INVALID_MNEMONIC: 40007;
+    readonly UNSUPPORTED_MNEMONIC_LENGTH: 40008;
+    readonly INVALID_CARD_DATA: 40009;
+    readonly UNKNOWN_ERROR: 40010;
+    readonly NFC_USER_CANCELED: 40011;
+    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;
+    /** CMAC verification failed – response integrity compromised */
+    readonly CMAC_VERIFY_FAILED: 40016;
+};
+interface NfcResult {
+    /** Numeric result code – compare against NfcStatusCode constants */
+    code: number;
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Returned data (optional, only present for some operations) */
+    data?: {
+        mnemonic?: string;
+        type?: string;
+        entropyHex?: string;
+        rawBytes?: string;
+        nickname?: string;
+        retryCount?: number;
+        aesKeyHex?: string;
+        crc16?: number;
+        version?: {
+            vendorId: number;
+            productType: number;
+            productSubtype: number;
+            majorVersion: number;
+            minorVersion: number;
+            storageSize: number;
+            protocolType: number;
+        };
+        signature?: string;
+    };
+}
+/**
+ * Unified failure result when the PIN retry counter has reached 0.
+ * Used by readMnemonic, updateCard, updatePassword, and resetCard.
+ */
+declare function nfcResultRetryCountExhausted(): NfcResult;
+
+/** Default retry limit, restored after a successful authentication */
+declare const DEFAULT_PIN_RETRY_COUNT = 10;
+
+/**
+ * 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)
+ */
+
+declare function isNfcOperationLocked(): boolean;
+declare function releaseNfcOperationLock(): void;
+declare function markNfcOperationCancelledByCleanup(): void;
+declare function consumeNfcOperationCancelledByCleanup(): boolean;
+declare function getNfcOperationCancelledByCleanupTimestamp(): number;
+declare function clearNfcOperationCancelledByCleanup(): void;
+
+/**
+ * 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.
+ */
+
+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. */
+declare function cardInfoToJson(cardInfo: ReturnType<typeof parseCardInfo>, pretty?: boolean): string;
+/**
+ * Detect whether the card is empty or already contains data.
+ *
+ * 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, 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
+ */
+declare function checkCard(password?: string, 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
+ */
+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.
+ */
+declare function readUserNickname(password?: string, onCardIdentified?: () => void): Promise<NfcResult>;
+/** Read the current PIN retry counter from the card. */
+declare function readMnemonicRetryCount(onCardIdentified?: () => void): Promise<NfcResult>;
+/** Reset the PIN retry counter to the default value (10). */
+declare function resetRetryCountTo10(onCardIdentified?: () => void): Promise<NfcResult>;
+/**
+ * Read card product version info (GET_VERSION command).
+ * No authentication required.
+ */
+declare function getCardVersion(onCardIdentified?: () => void): Promise<NfcResult>;
+/**
+ * Read the ECC originality signature (READ_SIG command).
+ * Verifies the card is a genuine NXP product.
+ * No authentication required (unless Random ID is enabled).
+ */
+declare function readOriginality(onCardIdentified?: () => void): Promise<NfcResult>;
+
+/**
+ * NFC Writer Module
+ *
+ * Public API:
+ *   - initializeCard()     – write mnemonic + set password on a blank card
+ *   - updateCard()         – update mnemonic & password (old password required)
+ *   - updatePassword()     – change password only
+ *   - writeUserNickname()  – write user nickname (password required)
+ *   - resetCard()          – wipe card and set password to "000000"
+ *
+ * Based on MIFARE Ultralight AES (MF0AES(H)20) datasheet.
+ */
+
+/**
+ * Initialize a card: authenticate with the default password, then write
+ * mnemonic and set a new password.
+ *
+ * @param mnemonic       BIP-39 mnemonic to write.
+ * @param newPassword    Password to protect the card with after initialization.
+ * @param defaultPassword Current (factory-default) password on the card.
+ */
+declare function initializeCard(mnemonic: string, newPassword: string, defaultPassword: 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.
+ */
+declare function updateCard(oldPassword: string, newPassword: string, newMnemonic: string, onCardIdentified?: () => void, options?: {
+    precheckExistingMnemonic?: boolean;
+}): Promise<NfcResult>;
+/** Change password only (old password required). */
+declare function updatePassword(oldPassword: string, newPassword: string, onCardIdentified?: () => void): Promise<NfcResult>;
+/** Write a user nickname (password required for authentication). */
+declare function writeUserNickname(password: string, nickname: string, onCardIdentified?: () => void): Promise<NfcResult>;
+/**
+ * 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 { NfcStatusCode, type NfcResult, nfcResultRetryCountExhausted, } from './types';
-export { checkCard, readMnemonic, readUserNickname, readMnemonicRetryCount, resetRetryCountTo10, cardInfoToJson, getCardVersion, readOriginality, } from './reader';
-export { initializeCard, updateCard, updatePassword, writeUserNickname, resetCard, } from './writer';
-export { isNfcOperationLocked, releaseNfcOperationLock, markNfcOperationCancelledByCleanup, consumeNfcOperationCancelledByCleanup, getNfcOperationCancelledByCleanupTimestamp, clearNfcOperationCancelledByCleanup, } from './nfc-core';
-export { DEFAULT_PIN_RETRY_COUNT } from './constants';
+declare function resetCard(password: string | undefined, newPassword: string, onCardIdentified?: () => void): Promise<NfcResult>;
+
+export { DEFAULT_PIN_RETRY_COUNT, type NfcResult, NfcStatusCode, cardInfoToJson, checkCard, clearNfcOperationCancelledByCleanup, consumeNfcOperationCancelledByCleanup, getCardVersion, getNfcOperationCancelledByCleanupTimestamp, initializeCard, isNfcOperationLocked, markNfcOperationCancelledByCleanup, nfcResultRetryCountExhausted, readMnemonic, readMnemonicRetryCount, readOriginality, readUserNickname, releaseNfcOperationLock, resetCard, resetRetryCountTo10, updateCard, updatePassword, writeUserNickname };