@ukeyfe/react-native-nfc-litecard 1.0.0

package/README.md

@@ -0,0 +1,390 @@
+# @ukeyfe/react-native-nfc-litecard
+
+[English](./README.en.md) | 中文
+
+基于 **MIFARE Ultralight AES** (MF0AES(H)20) 的 React Native NFC 读写库，用于 LiteCard 助记词存储。
+
+> **设计原则**：库只返回状态码 (`code`) 和数据 (`data`)，**不提供用户提示文案**。调用方根据 `ResultCode` 自行处理本地化提示。
+
+## 功能概览
+
+| 功能 | 方法 | 说明 |
+|------|------|------|
+| 检测卡片 | `checkCard()` | 判断卡片是空卡还是已有数据 |
+| 读取助记词 | `readMnemonic()` | 密码认证后读取 BIP-39 助记词 |
+| 读取昵称 | `readUserNickname()` | 读取卡片上的用户昵称 |
+| 读取重试次数 | `readMnemonicRetryCount()` | 读取 PIN 重试计数器 |
+| 重置重试次数 | `resetRetryCountTo10()` | 重置 PIN 重试计数器为默认值 10 |
+| 初始化卡片 | `initializeCard()` | 向空卡写入助记词并设置密码保护 |
+| 更新卡片 | `updateCard()` | 更新助记词和密码（需要旧密码） |
+| 修改密码 | `updatePassword()` | 仅修改密码（需要旧密码） |
+| 写入昵称 | `writeUserNickname()` | 写入用户昵称到卡片 |
+| 重置卡片 | `resetCard()` | 清空数据，密码重置为 "000000" |
+
+## 安装
+
+```bash
+npm install @ukeyfe/react-native-nfc-litecard
+```
+
+### 前置依赖
+
+本库需要以下 peer dependencies，请确保项目中已安装：
+
+```bash
+npm install react-native react-native-nfc-manager
+```
+
+## 快速上手
+
+```typescript
+import {
+  ResultCode,
+  checkCard,
+  readMnemonic,
+  initializeCard,
+  updateCard,
+  updatePassword,
+  writeUserNickname,
+  readUserNickname,
+  resetCard,
+  readMnemonicRetryCount,
+  resetRetryCountTo10,
+} from '@ukeyfe/react-native-nfc-litecard';
+```
+
+## API 文档
+
+### `checkCard(onCardIdentified?)`
+
+检测卡片状态（空卡 / 有数据）。
+
+```typescript
+const result = await checkCard();
+if (result.code === ResultCode.CHECK_EMPTY) {
+  // 空卡，可以初始化
+} else if (result.code === ResultCode.CHECK_HAS_DATA) {
+  // 有数据，需要密码读取或更新
+}
+```
+
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `onCardIdentified` | `() => void` | 否 | 卡片识别成功后的回调 |
+
+**返回值 (`NfcResult`)：**
+| code | 含义 |
+|------|------|
+| `ResultCode.CHECK_EMPTY` (10104) | 空卡 |
+| `ResultCode.CHECK_HAS_DATA` (10105) | 有数据 |
+| `ResultCode.NFC_CONNECT_FAILED` (40001) | NFC 连接失败 |
+
+---
+
+### `readMnemonic(password, onCardIdentified?)`
+
+读取助记词（需要密码认证）。
+
+```typescript
+const result = await readMnemonic('your-password');
+if (result.success) {
+  console.log('助记词:', result.data?.mnemonic);
+  console.log('类型:', result.data?.type);           // "12 words (128-bit)"
+  console.log('昵称:', result.data?.nickname);
+  console.log('剩余重试:', result.data?.retryCount);
+}
+```
+
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `password` | `string` | 是 | 卡片保护密码 |
+| `onCardIdentified` | `() => void` | 否 | 认证成功后的回调 |
+
+**返回 `data` 字段：**
+| 字段 | 说明 |
+|------|------|
+| `mnemonic` | BIP-39 助记词 |
+| `type` | 助记词类型（如 "12 words (128-bit)"） |
+| `entropyHex` | 熵的十六进制 |
+| `rawBytes` | 原始数据十六进制 |
+| `nickname` | 用户昵称（如果有） |
+| `retryCount` | 认证成功后重置的重试次数 |
+
+---
+
+### `initializeCard(mnemonic, password, onCardIdentified?)`
+
+初始化空卡：写入助记词 + 设置密码保护。
+
+```typescript
+const result = await initializeCard(
+  'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
+  'your-password'
+);
+if (result.code === ResultCode.INIT_SUCCESS) {
+  console.log('初始化成功');
+}
+```
+
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `mnemonic` | `string` | 是 | BIP-39 助记词（12/15/18/21/24 词） |
+| `password` | `string` | 是 | 要设置的保护密码 |
+| `onCardIdentified` | `() => void` | 否 | 开始写入前的回调 |
+
+---
+
+### `updateCard(oldPassword, newPassword, newMnemonic, onCardIdentified?)`
+
+更新卡片内容：使用旧密码认证后写入新助记词和新密码。
+
+```typescript
+const result = await updateCard('old-password', 'new-password', 'new mnemonic words ...');
+if (result.code === ResultCode.WRITE_SUCCESS) {
+  console.log('更新成功');
+}
+```
+
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `oldPassword` | `string` | 是 | 当前密码 |
+| `newPassword` | `string` | 是 | 新密码 |
+| `newMnemonic` | `string` | 是 | 新助记词 |
+| `onCardIdentified` | `() => void` | 否 | 认证成功后的回调 |
+
+---
+
+### `updatePassword(oldPassword, newPassword, onCardIdentified?)`
+
+仅修改密码，不更改助记词数据。
+
+```typescript
+const result = await updatePassword('old-password', 'new-password');
+if (result.code === ResultCode.UPDATE_PASSWORD_SUCCESS) {
+  console.log('密码修改成功');
+}
+```
+
+---
+
+### `writeUserNickname(password, nickname)`
+
+写入用户昵称到卡片（最长 12 字节，UTF-8 编码）。
+
+```typescript
+const result = await writeUserNickname('your-password', 'MyCard');
+if (result.code === ResultCode.WRITE_NICKNAME_SUCCESS) {
+  console.log('昵称写入成功');
+}
+```
+
+---
+
+### `readUserNickname(password?)`
+
+读取卡片上的用户昵称。如果卡片开启了读保护，需要传密码。
+
+```typescript
+const result = await readUserNickname('your-password');
+if (result.success) {
+  console.log('昵称:', result.data?.nickname);
+}
+```
+
+---
+
+### `resetCard(password?, onCardIdentified?)`
+
+重置卡片：清空所有用户数据，密码设为 `"000000"`。
+
+```typescript
+const result = await resetCard('your-password');
+if (result.code === ResultCode.RESET_SUCCESS) {
+  console.log('重置成功');
+}
+```
+
+> ⚠️ 重置操作不可逆，请谨慎使用。
+
+---
+
+### `readMnemonicRetryCount()`
+
+读取当前 PIN 重试计数器的值。
+
+```typescript
+const result = await readMnemonicRetryCount();
+if (result.success) {
+  console.log('剩余重试次数:', result.data?.retryCount);
+}
+```
+
+---
+
+### `resetRetryCountTo10()`
+
+将 PIN 重试计数器重置为默认值 10。
+
+```typescript
+const result = await resetRetryCountTo10();
+```
+
+---
+
+### NFC 锁管理
+
+用于 App 页面生命周期中的 NFC 会话管理：
+
+```typescript
+import {
+  isNfcOperationLocked,
+  releaseNfcOperationLock,
+  markNfcOperationCancelledByCleanup,
+  consumeNfcOperationCancelledByCleanup,
+} from '@ukeyfe/react-native-nfc-litecard';
+```
+
+| 方法 | 说明 |
+|------|------|
+| `isNfcOperationLocked()` | 检查 NFC 操作锁是否被持有 |
+| `releaseNfcOperationLock()` | 强制释放锁（页面关闭时使用） |
+| `markNfcOperationCancelledByCleanup()` | 标记当前操作被页面清理中断 |
+| `consumeNfcOperationCancelledByCleanup()` | 消费清理标记（返回是否被中断） |
+
+## NfcResult 返回结构
+
+所有 API 统一返回 `NfcResult`：
+
+```typescript
+interface NfcResult {
+  code: number;       // 状态码，与 ResultCode 常量比较
+  success: boolean;   // 操作是否成功
+  data?: {            // 可选数据，仅部分操作返回
+    mnemonic?: string;
+    type?: string;
+    entropyHex?: string;
+    rawBytes?: string;
+    nickname?: string;
+    retryCount?: number;
+    aesKeyHex?: string;
+    crc16?: number;
+  };
+}
+```
+
+## 错误处理示例
+
+```typescript
+import { ResultCode, readMnemonic } from '@ukeyfe/react-native-nfc-litecard';
+
+const result = await readMnemonic('password');
+
+switch (result.code) {
+  case ResultCode.READ_SUCCESS:
+    console.log('读取成功:', result.data?.mnemonic);
+    break;
+  case ResultCode.AUTH_WRONG_PASSWORD:
+    alert('密码错误');
+    break;
+  case ResultCode.NFC_CONNECT_FAILED:
+    alert('NFC 连接失败，请重新贴卡');
+    break;
+  case ResultCode.NFC_USER_CANCELED:
+    // iOS 用户取消，静默处理
+    break;
+  case ResultCode.READ_TIMEOUT:
+    alert('读取超时，请将卡片移开后重新贴近');
+    break;
+  default:
+    alert('操作失败');
+}
+```
+
+## 返回码一览
+
+### 成功码
+
+| 常量 | 值 | 说明 |
+|------|------|------|
+| `READ_SUCCESS` | 10102 | 读取助记词成功 |
+| `READ_NICKNAME_SUCCESS` | 10103 | 读取昵称成功 |
+| `CHECK_EMPTY` | 10104 | 空卡 |
+| `CHECK_HAS_DATA` | 10105 | 卡片有数据 |
+| `READ_RETRY_COUNT_SUCCESS` | 10106 | 读取重试次数成功 |
+| `INIT_SUCCESS` | 10201 | 初始化成功 |
+| `WRITE_SUCCESS` | 10203 | 写入/更新成功 |
+| `UPDATE_PASSWORD_SUCCESS` | 10204 | 修改密码成功 |
+| `WRITE_NICKNAME_SUCCESS` | 10205 | 写入昵称成功 |
+| `RESET_SUCCESS` | 10206 | 重置卡片成功 |
+
+### 错误码
+
+| 常量 | 值 | 说明 |
+|------|------|------|
+| `NFC_CONNECT_FAILED` | 40001 | NFC 连接失败 |
+| `AUTH_WRONG_PASSWORD` | 40002 | 密码错误 |
+| `AUTH_INVALID_RESPONSE` | 40003 | 认证响应无效 |
+| `AUTH_VERIFY_FAILED` | 40004 | 认证验证失败 |
+| `READ_FAILED` | 40005 | 读取失败 |
+| `WRITE_FAILED` | 40006 | 写入失败 |
+| `INVALID_MNEMONIC` | 40007 | 无效的助记词 |
+| `UNSUPPORTED_MNEMONIC_LENGTH` | 40008 | 不支持的助记词长度 |
+| `INVALID_CARD_DATA` | 40009 | 卡片数据无效 |
+| `UNKNOWN_ERROR` | 40010 | 未知错误 |
+| `NFC_USER_CANCELED` | 40011 | 用户取消 NFC 扫描 (iOS) |
+| `READ_TIMEOUT` | 40012 | 读取超时 |
+| `NFC_LOCK_TIMEOUT` | 40013 | NFC 锁超时 |
+| `CRC16_CHECK_FAILED` | 40014 | CRC16 校验失败 |
+
+## 存储格式
+
+卡片使用 BIP-39 熵压缩存储助记词：
+
+```
+[类型 1字节] [熵数据 16-32字节] [CRC16 2字节]
+```
+
+| 类型值 | 助记词长度 | 熵长度 |
+|--------|-----------|--------|
+| 0x01 | 12 词 | 16 字节 (128-bit) |
+| 0x02 | 15 词 | 20 字节 (160-bit) |
+| 0x03 | 18 词 | 24 字节 (192-bit) |
+| 0x04 | 21 词 | 28 字节 (224-bit) |
+| 0x05 | 24 词 | 32 字节 (256-bit) |
+
+## 安全机制
+
+- **AES-128 硬件级双向认证**（3-pass mutual authentication）
+- **SHA-256 密钥派生**：用户密码 → SHA-256 → 取前 16 字节作为 AES 密钥
+- **CRC16-Modbus 校验**：数据完整性验证
+- **PIN 重试计数器**：密码错误自动递减，成功后恢复为 10
+- **安全随机数**：认证使用 `crypto.getRandomValues()`（需 Hermes ≥ 0.72 或 `react-native-get-random-values` polyfill）
+
+## 项目结构
+
+```
+src/
+├── index.ts        # 公共 API 导出
+├── constants.ts    # 共享常量（页地址、NFC 命令、助记词类型）
+├── types.ts        # 统一 ResultCode、NfcResult 接口、错误映射
+├── crypto.ts       # AES 加解密、密钥派生、安全随机数生成
+├── utils.ts        # CRC16、hex 转换、数组工具
+├── nfc-core.ts     # NFC 锁、transceive、认证、重试计数器
+├── reader.ts       # 读卡 API
+└── writer.ts       # 写卡 API
+```
+
+## 平台支持
+
+| 平台 | 技术 | 说明 |
+|------|------|------|
+| iOS | MifareIOS | 需要 iPhone 7 及以上 |
+| Android | NfcA | 需要设备支持 NFC |
+
+## License
+
+MIT

package/dist/constants.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared constants for MIFARE Ultralight AES (MF0AES(H)20) NFC operations.
+ */
+/** READ command - reads 4 pages (16 bytes) starting from the specified page */
+export declare const CMD_READ = 48;
+/** WRITE command - writes a single page (4 bytes) */
+export declare const CMD_WRITE = 162;
+/** FAST_READ command - reads a range of pages in one shot */
+export declare const CMD_FAST_READ = 58;
+/** AES authentication part 1 */
+export declare const CMD_AUTH_PART1 = 26;
+/** AES authentication part 2 */
+export declare const CMD_AUTH_PART2 = 175;
+/** Data protection key slot (Key0) */
+export declare const KEY_NO_DATA_PROT = 0;
+/** Bytes per page */
+export declare const PAGE_SIZE = 4;
+/** User memory start page (page 8) */
+export declare const USER_PAGE_START = 8;
+/** User memory end page (page 39) */
+export declare const USER_PAGE_END = 39;
+/** Card info start page – first usable page in user memory */
+export declare const USER_CARD_INFO_PAGE_START = 4;
+/** Card info end page (4 pages, 16 bytes) */
+export declare const USER_CARD_INFO_PAGE_END = 7;
+/** Configuration page 0 – contains AUTH0 */
+export declare const PAGE_CFG0 = 41;
+/** Configuration page 1 – contains PROT bit */
+export declare const PAGE_CFG1 = 42;
+/** AES Key0 start page */
+export declare const PAGE_AES_KEY0_START = 48;
+/** Total user memory: (0x27 - 0x08 + 1) * 4 = 128 bytes */
+export declare const USER_MEMORY_SIZE: number;
+/** Card info area size: (0x07 - 0x04 + 1) * 4 = 16 bytes */
+export declare const USER_CARD_INFO_SIZE: number;
+/** 12-word mnemonic (128-bit entropy, 16 bytes) */
+export declare const MNEMONIC_TYPE_12 = 1;
+/** 15-word mnemonic (160-bit entropy, 20 bytes) */
+export declare const MNEMONIC_TYPE_15 = 2;
+/** 18-word mnemonic (192-bit entropy, 24 bytes) */
+export declare const MNEMONIC_TYPE_18 = 3;
+/** 21-word mnemonic (224-bit entropy, 28 bytes) */
+export declare const MNEMONIC_TYPE_21 = 4;
+/** 24-word mnemonic (256-bit entropy, 32 bytes) */
+export declare const MNEMONIC_TYPE_24 = 5;
+/** Nickname start page */
+export declare const USER_NICKNAME_PAGE_START: number;
+/** Nickname end page */
+export declare const USER_NICKNAME_PAGE_END = 39;
+/** Max nickname length in bytes (3 pages × 4 bytes) */
+export declare const USER_NICKNAME_MAX_LENGTH = 12;
+/** Retry counter page (one page before mnemonic data) */
+export declare const RETRY_COUNTER_PAGE: number;
+/** Byte offset of the counter within the page (last byte) */
+export declare const RETRY_COUNTER_OFFSET: number;
+/** Default retry limit, restored after a successful authentication */
+export declare const DEFAULT_PIN_RETRY_COUNT = 10;

package/dist/constants.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * 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;
+// ---------------------------------------------------------------------------
+// NFC command codes
+// ---------------------------------------------------------------------------
+/** READ command - reads 4 pages (16 bytes) starting from the specified page */
+exports.CMD_READ = 0x30;
+/** WRITE command - writes a single page (4 bytes) */
+exports.CMD_WRITE = 0xa2;
+/** FAST_READ command - reads a range of pages in one shot */
+exports.CMD_FAST_READ = 0x3a;
+/** AES authentication part 1 */
+exports.CMD_AUTH_PART1 = 0x1a;
+/** AES authentication part 2 */
+exports.CMD_AUTH_PART2 = 0xaf;
+/** Data protection key slot (Key0) */
+exports.KEY_NO_DATA_PROT = 0x00;
+// ---------------------------------------------------------------------------
+// Page addresses
+// ---------------------------------------------------------------------------
+/** Bytes per page */
+exports.PAGE_SIZE = 4;
+/** User memory start page (page 8) */
+exports.USER_PAGE_START = 0x08;
+/** User memory end page (page 39) */
+exports.USER_PAGE_END = 0x27;
+/** Card info start page – first usable page in user memory */
+exports.USER_CARD_INFO_PAGE_START = 0x04;
+/** Card info end page (4 pages, 16 bytes) */
+exports.USER_CARD_INFO_PAGE_END = 0x07;
+/** Configuration page 0 – contains AUTH0 */
+exports.PAGE_CFG0 = 0x29;
+/** Configuration page 1 – contains PROT bit */
+exports.PAGE_CFG1 = 0x2a;
+/** AES Key0 start page */
+exports.PAGE_AES_KEY0_START = 0x30;
+// ---------------------------------------------------------------------------
+// Computed sizes
+// ---------------------------------------------------------------------------
+/** Total user memory: (0x27 - 0x08 + 1) * 4 = 128 bytes */
+exports.USER_MEMORY_SIZE = (exports.USER_PAGE_END - exports.USER_PAGE_START + 1) * exports.PAGE_SIZE;
+/** Card info area size: (0x07 - 0x04 + 1) * 4 = 16 bytes */
+exports.USER_CARD_INFO_SIZE = (exports.USER_CARD_INFO_PAGE_END - exports.USER_CARD_INFO_PAGE_START + 1) * exports.PAGE_SIZE;
+// ---------------------------------------------------------------------------
+// Mnemonic type identifiers
+// ---------------------------------------------------------------------------
+/** 12-word mnemonic (128-bit entropy, 16 bytes) */
+exports.MNEMONIC_TYPE_12 = 0x01;
+/** 15-word mnemonic (160-bit entropy, 20 bytes) */
+exports.MNEMONIC_TYPE_15 = 0x02;
+/** 18-word mnemonic (192-bit entropy, 24 bytes) */
+exports.MNEMONIC_TYPE_18 = 0x03;
+/** 21-word mnemonic (224-bit entropy, 28 bytes) */
+exports.MNEMONIC_TYPE_21 = 0x04;
+/** 24-word mnemonic (256-bit entropy, 32 bytes) */
+exports.MNEMONIC_TYPE_24 = 0x05;
+// ---------------------------------------------------------------------------
+// User nickname area (last 3 pages of user memory)
+// ---------------------------------------------------------------------------
+/** Nickname start page */
+exports.USER_NICKNAME_PAGE_START = exports.USER_PAGE_END - 2; // 0x25
+/** Nickname end page */
+exports.USER_NICKNAME_PAGE_END = exports.USER_PAGE_END; // 0x27
+/** Max nickname length in bytes (3 pages × 4 bytes) */
+exports.USER_NICKNAME_MAX_LENGTH = 12;
+// ---------------------------------------------------------------------------
+// PIN retry counter
+// ---------------------------------------------------------------------------
+/** Retry counter page (one page before mnemonic data) */
+exports.RETRY_COUNTER_PAGE = exports.USER_PAGE_START - 1; // 0x07
+/** Byte offset of the counter within the page (last byte) */
+exports.RETRY_COUNTER_OFFSET = exports.PAGE_SIZE - 1;
+/** Default retry limit, restored after a successful authentication */
+exports.DEFAULT_PIN_RETRY_COUNT = 10;

package/dist/crypto.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Cryptographic helpers for MIFARE Ultralight AES authentication.
+ *
+ * - AES-128 CBC encrypt / decrypt (via crypto-js)
+ * - Password → AES key derivation (SHA-256, first 16 bytes)
+ * - Cryptographically-secure 16-byte random generation
+ * - Byte-array comparison & rotation
+ */
+/**
+ * Derive a 16-byte AES-128 key from a password string.
+ * SHA-256 the password, then take the first 16 bytes.
+ */
+export declare function passwordToAesKey(password: string): Uint8Array;
+/** AES-128 CBC decrypt (no padding). Both key, data, iv must be 16 bytes. */
+export declare function aesDecrypt(key: Uint8Array, data: Uint8Array, iv: Uint8Array): Uint8Array;
+/** AES-128 CBC encrypt (no padding). Both key, data, iv must be 16 bytes. */
+export declare function aesEncrypt(key: Uint8Array, data: Uint8Array, iv: Uint8Array): Uint8Array;
+/**
+ * Left-rotate a byte array by 8 bits (1 byte).
+ * e.g. [1,2,3,4] → [2,3,4,1]
+ * Used in AES 3-pass auth to compute RndB' and verify RndA'.
+ */
+export declare function rotateLeft8(data: Uint8Array): Uint8Array;
+/** Compare two Uint8Arrays for equality. */
+export declare function arraysEqual(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * Generate a 16-byte cryptographically-secure random value.
+ *
+ * Uses `crypto.getRandomValues` when available (Hermes ≥ 0.72, or
+ * the `react-native-get-random-values` polyfill).  Falls back to
+ * `Math.random()` with a console warning if the API is missing.
+ */
+export declare function generateRandom16(): Uint8Array;

package/dist/crypto.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Cryptographic helpers for MIFARE Ultralight AES authentication.
+ *
+ * - AES-128 CBC encrypt / decrypt (via crypto-js)
+ * - Password → AES key derivation (SHA-256, first 16 bytes)
+ * - Cryptographically-secure 16-byte random generation
+ * - Byte-array comparison & rotation
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.passwordToAesKey = passwordToAesKey;
+exports.aesDecrypt = aesDecrypt;
+exports.aesEncrypt = aesEncrypt;
+exports.rotateLeft8 = rotateLeft8;
+exports.arraysEqual = arraysEqual;
+exports.generateRandom16 = generateRandom16;
+const crypto_js_1 = __importDefault(require("crypto-js"));
+// ---------------------------------------------------------------------------
+// Key derivation
+// ---------------------------------------------------------------------------
+/**
+ * Derive a 16-byte AES-128 key from a password string.
+ * SHA-256 the password, then take the first 16 bytes.
+ */
+function passwordToAesKey(password) {
+    const safePassword = password || '';
+    const hash = crypto_js_1.default.SHA256(String(safePassword)).toString();
+    const key = new Uint8Array(16);
+    for (let i = 0; i < 16; i++) {
+        key[i] = parseInt(hash.substr(i * 2, 2), 16);
+    }
+    return key;
+}
+// ---------------------------------------------------------------------------
+// AES-128 CBC
+// ---------------------------------------------------------------------------
+/** AES-128 CBC decrypt (no padding). Both key, data, iv must be 16 bytes. */
+function aesDecrypt(key, data, iv) {
+    const keyWords = crypto_js_1.default.lib.WordArray.create(key);
+    const ivWords = crypto_js_1.default.lib.WordArray.create(iv);
+    const dataWords = crypto_js_1.default.lib.WordArray.create(data);
+    const decrypted = crypto_js_1.default.AES.decrypt({ ciphertext: dataWords }, keyWords, { iv: ivWords, mode: crypto_js_1.default.mode.CBC, padding: crypto_js_1.default.pad.NoPadding });
+    const hex = decrypted.toString();
+    const result = new Uint8Array(16);
+    for (let i = 0; i < 16; i++) {
+        result[i] = parseInt(hex.substr(i * 2, 2), 16);
+    }
+    return result;
+}
+/** AES-128 CBC encrypt (no padding). Both key, data, iv must be 16 bytes. */
+function aesEncrypt(key, data, iv) {
+    const keyWords = crypto_js_1.default.lib.WordArray.create(key);
+    const ivWords = crypto_js_1.default.lib.WordArray.create(iv);
+    const dataWords = crypto_js_1.default.lib.WordArray.create(data);
+    const encrypted = crypto_js_1.default.AES.encrypt(dataWords, keyWords, {
+        iv: ivWords,
+        mode: crypto_js_1.default.mode.CBC,
+        padding: crypto_js_1.default.pad.NoPadding,
+    });
+    const hex = encrypted.ciphertext.toString();
+    const result = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < result.length; i++) {
+        result[i] = parseInt(hex.substr(i * 2, 2), 16);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Byte-array helpers
+// ---------------------------------------------------------------------------
+/**
+ * Left-rotate a byte array by 8 bits (1 byte).
+ * e.g. [1,2,3,4] → [2,3,4,1]
+ * Used in AES 3-pass auth to compute RndB' and verify RndA'.
+ */
+function rotateLeft8(data) {
+    const result = new Uint8Array(data.length);
+    for (let i = 0; i < data.length - 1; i++) {
+        result[i] = data[i + 1];
+    }
+    result[data.length - 1] = data[0];
+    return result;
+}
+/** Compare two Uint8Arrays for equality. */
+function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Secure random
+// ---------------------------------------------------------------------------
+/**
+ * Generate a 16-byte cryptographically-secure random value.
+ *
+ * Uses `crypto.getRandomValues` when available (Hermes ≥ 0.72, or
+ * the `react-native-get-random-values` polyfill).  Falls back to
+ * `Math.random()` with a console warning if the API is missing.
+ */
+function generateRandom16() {
+    const arr = new Uint8Array(16);
+    if (typeof globalThis.crypto !== 'undefined' &&
+        typeof globalThis.crypto.getRandomValues === 'function') {
+        globalThis.crypto.getRandomValues(arr);
+    }
+    else {
+        console.warn('[nfc-litecard] crypto.getRandomValues is not available. ' +
+            'Falling back to Math.random() which is NOT cryptographically secure. ' +
+            'Consider adding the react-native-get-random-values polyfill.');
+        for (let i = 0; i < 16; i++) {
+            arr[i] = Math.floor(Math.random() * 256);
+        }
+    }
+    return arr;
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @ukeyfe/react-native-nfc-litecard
+ *
+ * NFC read/write library for MIFARE Ultralight AES (LiteCard mnemonic storage).
+ */
+export { ResultCode, type NfcResult } 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';
+export { DEFAULT_PIN_RETRY_COUNT } from './constants';