@ukeyfe/react-native-nfc-litecard 1.0.1 → 1.0.3

package/README.zh.md

@@ -0,0 +1,499 @@
+# @ukeyfe/react-native-nfc-litecard
+
+[English](./README.md) | 中文
+
+React Native NFC 读写库，适用于 **MIFARE Ultralight AES**（MF0AES(H)20），专为 LiteCard 助记词存储设计。
+
+> **设计原则**：库只返回状态码（`code`）和数据（`data`），**不**提供面向用户的提示文案。调用方应根据 `NfcStatusCode` 自行映射本地化字符串。
+
+## 功能概览
+
+| 功能 | 方法 | 说明 |
+|------|------|------|
+| 检测卡片 | `checkCard()` | 检测卡片是否为空或已有数据 |
+| 读取助记词 | `readMnemonic()` | 读取 BIP-39 助记词（需密码） |
+| 读取昵称 | `readUserNickname()` | 读取卡片上的用户昵称 |
+| 读取重试次数 | `readMnemonicRetryCount()` | 读取 PIN 重试计数器 |
+| 重置重试次数 | `resetRetryCountTo10()` | 将 PIN 重试计数器重置为默认值（10） |
+| 初始化卡片 | `initializeCard()` | 用出厂密码认证，写入助记词 + 设置新密码 |
+| 更新卡片 | `updateCard()` | 更新助记词和密码（需旧密码） |
+| 修改密码 | `updatePassword()` | 仅修改密码（需旧密码） |
+| 写入昵称 | `writeUserNickname()` | 写入用户昵称 |
+| 重置卡片 | `resetCard()` | 清除助记词数据，设置新密码，保持保护开启 |
+| 卡片版本 | `getCardVersion()` | 读取卡片产品版本信息（无需认证） |
+| 真伪校验 | `readOriginality()` | 读取 ECC 原厂签名，验证 NXP 正品 |
+
+## 安装
+
+```bash
+npm install @ukeyfe/react-native-nfc-litecard
+```
+
+### 对等依赖
+
+本库需要以下对等依赖：
+
+```bash
+npm install react-native react-native-nfc-manager
+```
+
+## 快速开始
+
+```typescript
+import {
+  NfcStatusCode,
+  checkCard,
+  readMnemonic,
+  initializeCard,
+  updateCard,
+  updatePassword,
+  writeUserNickname,
+  readUserNickname,
+  resetCard,
+  readMnemonicRetryCount,
+  resetRetryCountTo10,
+  getCardVersion,
+  readOriginality,
+} from '@ukeyfe/react-native-nfc-litecard';
+```
+
+## API 文档
+
+### `checkCard(password?, onCardIdentified?)`
+
+检测卡片状态（空卡 / 有数据）。
+
+**无密码（快速探测）：**
+```typescript
+const result = await checkCard();
+if (result.code === NfcStatusCode.CHECK_EMPTY) {
+  // 空卡 – 可以初始化
+} else if (result.code === NfcStatusCode.CHECK_HAS_DATA) {
+  // 有数据（或已读保护，无法确定）
+}
+```
+
+**有密码（认证后深度检测，适用于读保护卡）：**
+```typescript
+const result = await checkCard('password');
+if (result.code === NfcStatusCode.CHECK_EMPTY) {
+  // 空卡 – 可以写入
+} else if (result.code === NfcStatusCode.CHECK_HAS_DATA) {
+  // 已有合法助记词备份，类型：result.data?.type
+} else if (result.code === NfcStatusCode.AUTH_WRONG_PASSWORD) {
+  // 密码错误
+}
+```
+
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `password` | `string` | 否 | 卡片保护密码。不传时直接读取（适合未加密卡片）；传入时先进行 AES 认证，再读取全量数据并 CRC16 校验（适合读保护卡，结果更准确）。 |
+| `onCardIdentified` | `() => void` | 否 | NFC 会话建立后回调，可用于 UI 提示如"已检测到卡片"。 |
+
+**返回状态码：**
+| 状态码 | 含义 |
+|--------|------|
+| `NfcStatusCode.CHECK_EMPTY` (10104) | 空卡 – 无助记词数据 |
+| `NfcStatusCode.CHECK_HAS_DATA` (10105) | 卡片有数据。传入密码时，`data.type` 包含助记词类型（如 `"12 words (128-bit)"`）。 |
+| `NfcStatusCode.AUTH_WRONG_PASSWORD` (40002) | 密码错误（仅在传入密码时可能出现） |
+| `NfcStatusCode.NFC_CONNECT_FAILED` (40001) | NFC 连接失败 – 未贴卡或设备不支持 |
+
+---
+
+### `readMnemonic(password, onCardIdentified?)`
+
+读取助记词（需密码认证）。认证前自动递减重试计数器，认证成功后重置为 10。
+
+```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` | 是 | 卡片保护密码，用于 AES-128 认证 |
+| `onCardIdentified` | `() => void` | 否 | 认证成功、开始读取前回调，可用于 UI 提示如"正在读取"。 |
+
+**返回 `data` 字段：**
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `mnemonic` | `string` | BIP-39 助记词（如 `"abandon abandon ... about"`） |
+| `type` | `string` | 助记词类型（如 `"12 words (128-bit)"`、`"24 words (256-bit)"`） |
+| `entropyHex` | `string` | 熵的十六进制字符串 |
+| `rawBytes` | `string` | 卡上原始数据的十六进制字符串（类型 + 熵） |
+| `nickname` | `string` | 用户昵称（如卡上已设置） |
+| `retryCount` | `number` | 认证成功后的重试次数（正常为 10） |
+
+---
+
+### `initializeCard(mnemonic, newPassword, defaultPassword, onCardIdentified?)`
+
+初始化卡片：用出厂默认密码认证，写入助记词，设置新密码。卡片必须已启用 AES 保护（出厂默认）。
+
+```typescript
+const result = await initializeCard(
+  'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
+  'your-password',
+  '000000'  // 出厂默认密码
+);
+if (result.code === NfcStatusCode.INIT_SUCCESS) {
+  console.log('初始化成功');
+}
+```
+
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `mnemonic` | `string` | 是 | BIP-39 助记词，支持 12/15/18/21/24 个词。库会转为熵 + CRC16 写入卡片。 |
+| `newPassword` | `string` | 是 | 新保护密码，用于派生 AES-128 密钥写入卡片。 |
+| `defaultPassword` | `string` | 是 | 卡片当前（出厂默认）密码，用于认证。 |
+| `onCardIdentified` | `() => void` | 否 | 认证成功、开始写入前回调，可用于 UI 提示如"正在写入"。 |
+
+---
+
+### `updateCard(oldPassword, newPassword, newMnemonic, onCardIdentified?, options?)`
+
+更新卡片：使用旧密码认证后，写入新助记词和新密码。认证前自动递减重试计数器。
+
+```typescript
+const result = await updateCard('old-password', 'new-password', 'new mnemonic words ...');
+if (result.code === NfcStatusCode.WRITE_SUCCESS) {
+  console.log('更新成功');
+}
+```
+
+**预检查已有备份：**
+
+```typescript
+const result = await updateCard('old-password', 'new-password', 'mnemonic ...', undefined, {
+  precheckExistingMnemonic: true,
+});
+if (result.code === NfcStatusCode.PRECHECK_HAS_BACKUP) {
+  // 卡片已有合法助记词备份，跳过写入
+  console.log('已有备份，类型:', result.data?.type);
+} else if (result.code === NfcStatusCode.WRITE_SUCCESS) {
+  console.log('写入成功');
+}
+```
+
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `oldPassword` | `string` | 是 | 当前卡片密码，用于 AES 认证 |
+| `newPassword` | `string` | 是 | 新密码，写入后卡片使用此密码保护 |
+| `newMnemonic` | `string` | 是 | 新 BIP-39 助记词（12/15/18/21/24 个词） |
+| `onCardIdentified` | `() => void` | 否 | 认证成功后回调，可用于 UI 提示如"正在写入"。 |
+| `options.precheckExistingMnemonic` | `boolean` | 否 | 为 `true` 时，认证后先读取卡片数据并校验 CRC16，若已有合法助记词则返回 `PRECHECK_HAS_BACKUP`，不执行写入。 |
+
+---
+
+### `updatePassword(oldPassword, newPassword, onCardIdentified?)`
+
+仅修改密码，卡片上的助记词数据不变。认证前自动递减重试计数器。
+
+```typescript
+const result = await updatePassword('old-password', 'new-password');
+if (result.code === NfcStatusCode.UPDATE_PASSWORD_SUCCESS) {
+  console.log('密码修改成功');
+}
+```
+
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `oldPassword` | `string` | 是 | 当前卡片密码，用于 AES 认证 |
+| `newPassword` | `string` | 是 | 新密码，修改后卡片使用此密码 |
+| `onCardIdentified` | `() => void` | 否 | 认证成功后回调 |
+
+---
+
+### `writeUserNickname(password, nickname, onCardIdentified?)`
+
+写入用户昵称。昵称以 UTF-8 编码，最大 12 字节（超出部分截断）。
+
+```typescript
+const result = await writeUserNickname('your-password', 'MyCard');
+if (result.code === NfcStatusCode.WRITE_NICKNAME_SUCCESS) {
+  console.log('昵称写入成功');
+}
+```
+
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `password` | `string` | 是 | 卡片保护密码，用于 AES 认证 |
+| `nickname` | `string` | 是 | 用户昵称；UTF-8 最大 12 字节（约 4 个中文字符或 12 个英文字母） |
+| `onCardIdentified` | `() => void` | 否 | 认证成功后回调 |
+
+---
+
+### `readUserNickname(password?, onCardIdentified?)`
+
+读取卡片上的用户昵称。
+
+```typescript
+const result = await readUserNickname('your-password');
+if (result.success) {
+  console.log('昵称:', result.data?.nickname);
+}
+```
+
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `password` | `string` | 否 | 卡片密码。读保护启用时（`PROT=1`）必填，否则可选。 |
+| `onCardIdentified` | `() => void` | 否 | 认证成功后回调 |
+
+---
+
+### `resetCard(password, newPassword, onCardIdentified?)`
+
+重置卡片：清除助记词数据，设置新密码，关闭读写保护。昵称保留不变。
+
+```typescript
+const result = await resetCard('old-password', 'new-password');
+if (result.code === NfcStatusCode.RESET_SUCCESS) {
+  console.log('重置成功');
+}
+```
+
+> ⚠️ 此操作不可逆，卡片上的助记词数据将被永久擦除。
+
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `password` | `string \| undefined` | 否 | 当前卡片密码。卡片已保护时必填，否则传 `undefined`。认证前自动递减重试计数器。 |
+| `newPassword` | `string` | 是 | 重置后要设置的密码。 |
+| `onCardIdentified` | `() => void` | 否 | 认证成功后回调 |
+
+---
+
+### `readMnemonicRetryCount(onCardIdentified?)`
+
+读取卡片上的 PIN 重试计数器。无需密码认证（计数器页面在保护区域之外）。
+
+```typescript
+const result = await readMnemonicRetryCount();
+if (result.success) {
+  console.log('剩余重试次数:', result.data?.retryCount);
+}
+```
+
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `onCardIdentified` | `() => void` | 否 | NFC 会话建立后回调 |
+
+---
+
+### `resetRetryCountTo10(onCardIdentified?)`
+
+将 PIN 重试计数器重置为默认值（10）。无需密码认证。
+
+```typescript
+const result = await resetRetryCountTo10();
+```
+
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `onCardIdentified` | `() => void` | 否 | NFC 会话建立后回调 |
+
+---
+
+### `getCardVersion(onCardIdentified?)`
+
+读取卡片产品版本信息。无需密码认证。
+
+```typescript
+const result = await getCardVersion();
+if (result.success) {
+  console.log('厂商:', result.data?.version?.vendorId);   // 0x04 = NXP
+  console.log('类型:', result.data?.version?.productType);   // 0x03 = Ultralight
+  console.log('版本:', result.data?.version?.majorVersion); // 0x04 = AES
+}
+```
+
+---
+
+### `readOriginality(onCardIdentified?)`
+
+读取 ECC 原厂签名，验证卡片是否为 NXP 正品。无需密码认证。
+
+```typescript
+const result = await readOriginality();
+if (result.success) {
+  console.log('签名:', result.data?.signature); // 96 字符 hex 字符串
+}
+```
+
+---
+
+### NFC 锁管理
+
+用于应用层 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;       // 状态码 – 与 NfcStatusCode 比较
+  success: boolean;   // 操作是否成功
+  data?: {            // 可选数据，仅部分操作返回
+    mnemonic?: string;
+    type?: string;
+    entropyHex?: string;
+    rawBytes?: string;
+    nickname?: string;
+    retryCount?: number;
+    aesKeyHex?: string;
+    crc16?: number;
+  };
+}
+```
+
+## 错误处理示例
+
+```typescript
+import { NfcStatusCode, readMnemonic } from '@ukeyfe/react-native-nfc-litecard';
+
+const result = await readMnemonic('password');
+
+switch (result.code) {
+  case NfcStatusCode.READ_SUCCESS:
+    console.log('读取成功:', result.data?.mnemonic);
+    break;
+  case NfcStatusCode.AUTH_WRONG_PASSWORD:
+    alert('密码错误');
+    break;
+  case NfcStatusCode.NFC_CONNECT_FAILED:
+    alert('NFC 连接失败，请重新贴卡');
+    break;
+  case NfcStatusCode.NFC_USER_CANCELED:
+    // iOS 用户取消 – 静默处理
+    break;
+  case NfcStatusCode.READ_TIMEOUT:
+    alert('读取超时 – 请移开卡片后重新贴卡');
+    break;
+  case NfcStatusCode.RETRY_COUNT_EXHAUSTED:
+    alert('重试次数已耗尽 – 卡片已锁定');
+    break;
+  default:
+    alert('操作失败');
+}
+```
+
+## 状态码
+
+### 成功码
+
+| 常量 | 值 | 说明 |
+|------|------|------|
+| `READ_SUCCESS` | 10102 | 助记词读取成功 |
+| `READ_NICKNAME_SUCCESS` | 10103 | 昵称读取成功 |
+| `CHECK_EMPTY` | 10104 | 空卡 |
+| `CHECK_HAS_DATA` | 10105 | 卡片有数据 |
+| `READ_RETRY_COUNT_SUCCESS` | 10106 | 重试次数读取成功 |
+| `GET_VERSION_SUCCESS` | 10107 | 卡片版本读取成功 |
+| `READ_SIG_SUCCESS` | 10108 | 原厂签名读取成功 |
+| `INIT_SUCCESS` | 10201 | 初始化成功 |
+| `WRITE_SUCCESS` | 10203 | 写入/更新成功 |
+| `UPDATE_PASSWORD_SUCCESS` | 10204 | 密码修改成功 |
+| `WRITE_NICKNAME_SUCCESS` | 10205 | 昵称写入成功 |
+| `RESET_SUCCESS` | 10206 | 卡片重置成功 |
+| `PRECHECK_HAS_BACKUP` | 10207 | 卡片已有合法备份，跳过写入 |
+
+### 错误码
+
+| 常量 | 值 | 说明 |
+|------|------|------|
+| `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 校验失败 |
+| `RETRY_COUNT_EXHAUSTED` | 40015 | PIN 重试次数耗尽，卡片已锁定 |
+
+## 存储格式
+
+卡片使用熵压缩方式存储 BIP-39 助记词：
+
+```
+[类型 1B] [熵 16-32B] [CRC16 2B]
+```
+
+| 类型 | 助记词长度 | 熵大小 |
+|------|-----------|--------|
+| 0x01 | 12 个词 | 16 字节（128 位） |
+| 0x02 | 15 个词 | 20 字节（160 位） |
+| 0x03 | 18 个词 | 24 字节（192 位） |
+| 0x04 | 21 个词 | 28 字节（224 位） |
+| 0x05 | 24 个词 | 32 字节（256 位） |
+
+## 安全性
+
+- **AES-128 硬件级双向认证**（3-pass）
+- **SHA-256 密钥派生**：密码 → SHA-256 → 取前 16 字节作为 AES 密钥
+- **CRC16-Modbus 校验和**：数据完整性校验
+- **CMAC 安全消息**：认证后所有命令附带 AES-CMAC（NIST 800-38B）防篡改
+- **PIN 重试计数器**：密码错误时自动递减，认证成功后重置为 10
+- **安全随机数**：认证使用 `crypto.getRandomValues()`（需要 Hermes ≥ 0.72 或 `react-native-get-random-values` polyfill）
+
+## 项目结构
+
+```
+src/
+├── index.ts        # 公共 API 导出
+├── constants.ts    # 共享常量（页地址、NFC 指令、助记词类型）
+├── types.ts        # 统一 NfcStatusCode、NfcResult 接口、错误映射
+├── crypto.ts       # AES 加解密、密钥派生、安全随机数
+├── utils.ts        # CRC16、十六进制转换、数组工具
+├── nfc-core.ts     # NFC 锁、transceive、认证、重试计数器
+├── reader.ts       # 读取 API
+└── writer.ts       # 写入 API
+```
+
+## 平台支持
+
+| 平台 | 技术 | 要求 |
+|------|------|------|
+| iOS | MifareIOS | iPhone 7 及以上 |
+| Android | NfcA | 支持 NFC 的设备 |
+
+## 许可证
+
+MIT

package/dist/constants.d.ts

@@ -11,6 +11,10 @@ export declare const CMD_FAST_READ = 58;
 export declare const CMD_AUTH_PART1 = 26;
 /** AES authentication part 2 */
 export declare const CMD_AUTH_PART2 = 175;
+/** GET_VERSION command - retrieve product version info */
+export declare const CMD_GET_VERSION = 96;
+/** READ_SIG command - read ECC originality signature */
+export declare const CMD_READ_SIG = 60;
 /** Data protection key slot (Key0) */
 export declare const KEY_NO_DATA_PROT = 0;
 /** Bytes per page */
@@ -43,6 +47,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 */
@@ -55,3 +63,25 @@ export declare const RETRY_COUNTER_PAGE: number;
 export declare const RETRY_COUNTER_OFFSET: number;
 /** Default retry limit, restored after a successful authentication */
 export declare const DEFAULT_PIN_RETRY_COUNT = 10;
+/** SEC_MSG_ACT bit mask in CFG0 byte 0 (bit 1) */
+export declare const SEC_MSG_ACT_MASK = 2;
+export declare const DELAY: {
+    /** Delay after requestNfcTech on Android */
+    readonly ANDROID_POST_TECH: 300;
+    /** Delay after releaseNfcTech (normal) */
+    readonly IOS_POST_RELEASE: 100;
+    readonly ANDROID_POST_RELEASE: 800;
+    /** Delay after releaseNfcTech (forced, e.g. after timeout) */
+    readonly IOS_POST_RELEASE_FORCED: 300;
+    readonly ANDROID_POST_RELEASE_FORCED: 1000;
+    /** Delay between page writes on iOS */
+    readonly IOS_PAGE_WRITE: 20;
+    /** Delay between AES key page writes on iOS */
+    readonly IOS_KEY_WRITE: 10;
+    /** Delay between nickname page writes on iOS */
+    readonly IOS_NICKNAME_WRITE: 100;
+    /** Delay between config operations on iOS */
+    readonly IOS_CONFIG: 80;
+    /** Keep-alive frequency (every N pages) during writes */
+    readonly KEEPALIVE_FREQ: 4;
+};

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.DELAY = exports.SEC_MSG_ACT_MASK = 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_READ_SIG = exports.CMD_GET_VERSION = exports.CMD_AUTH_PART2 = exports.CMD_AUTH_PART1 = exports.CMD_FAST_READ = exports.CMD_WRITE = exports.CMD_READ = void 0;
 // ---------------------------------------------------------------------------
 // NFC command codes
 // ---------------------------------------------------------------------------
@@ -17,6 +17,10 @@ exports.CMD_FAST_READ = 0x3a;
 exports.CMD_AUTH_PART1 = 0x1a;
 /** AES authentication part 2 */
 exports.CMD_AUTH_PART2 = 0xaf;
+/** GET_VERSION command - retrieve product version info */
+exports.CMD_GET_VERSION = 0x60;
+/** READ_SIG command - read ECC originality signature */
+exports.CMD_READ_SIG = 0x3c;
 /** Data protection key slot (Key0) */
 exports.KEY_NO_DATA_PROT = 0x00;
 // ---------------------------------------------------------------------------
@@ -59,6 +63,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 */
@@ -76,3 +87,31 @@ exports.RETRY_COUNTER_PAGE = exports.USER_PAGE_START - 1; // 0x07
 exports.RETRY_COUNTER_OFFSET = exports.PAGE_SIZE - 1;
 /** Default retry limit, restored after a successful authentication */
 exports.DEFAULT_PIN_RETRY_COUNT = 10;
+// ---------------------------------------------------------------------------
+// Secure messaging (CMAC)
+// ---------------------------------------------------------------------------
+/** SEC_MSG_ACT bit mask in CFG0 byte 0 (bit 1) */
+exports.SEC_MSG_ACT_MASK = 0x02;
+// ---------------------------------------------------------------------------
+// Platform-specific delays (ms)
+// ---------------------------------------------------------------------------
+exports.DELAY = {
+    /** Delay after requestNfcTech on Android */
+    ANDROID_POST_TECH: 300,
+    /** Delay after releaseNfcTech (normal) */
+    IOS_POST_RELEASE: 100,
+    ANDROID_POST_RELEASE: 800,
+    /** Delay after releaseNfcTech (forced, e.g. after timeout) */
+    IOS_POST_RELEASE_FORCED: 300,
+    ANDROID_POST_RELEASE_FORCED: 1000,
+    /** Delay between page writes on iOS */
+    IOS_PAGE_WRITE: 20,
+    /** Delay between AES key page writes on iOS */
+    IOS_KEY_WRITE: 10,
+    /** Delay between nickname page writes on iOS */
+    IOS_NICKNAME_WRITE: 100,
+    /** Delay between config operations on iOS */
+    IOS_CONFIG: 80,
+    /** Keep-alive frequency (every N pages) during writes */
+    KEEPALIVE_FREQ: 4,
+};

package/dist/crypto.d.ts

@@ -23,6 +23,28 @@ export declare function aesEncrypt(key: Uint8Array, data: Uint8Array, iv: Uint8A
 export declare function rotateLeft8(data: Uint8Array): Uint8Array;
 /** Compare two Uint8Arrays for equality. */
 export declare function arraysEqual(a: Uint8Array, b: Uint8Array): boolean;
+/** AES-128 ECB encrypt a single 16-byte block. */
+export declare function aesEcbEncrypt(key: Uint8Array, data: Uint8Array): Uint8Array;
+/**
+ * Generate CMAC subkeys K1 and K2 (NIST 800-38B §6.1).
+ */
+export declare function generateCmacSubkeys(key: Uint8Array): {
+    k1: Uint8Array;
+    k2: Uint8Array;
+};
+/**
+ * Compute AES-CMAC (NIST 800-38B §6.2).
+ * Returns full 16-byte MAC.
+ */
+export declare function aesCmac(key: Uint8Array, message: Uint8Array): Uint8Array;
+/**
+ * Derive SesAuthMACKey from authentication key and random numbers.
+ * (MF0AES(H)20 §8.8.1)
+ *
+ * SV2 = 5Ah||A5h||00h||01h||00h||80h||RndA[15..14]||(RndA[13..8] XOR RndB[15..10])||RndB[9..0]||RndA[7..0]
+ * SesAuthMACKey = AES-CMAC(Kx, SV2)
+ */
+export declare function deriveSessionKey(authKey: Uint8Array, rndA: Uint8Array, rndB: Uint8Array): Uint8Array;
 /**
  * Generate a 16-byte cryptographically-secure random value.
  *