@ukeyfe/hardware-core 1.1.13

package/src/utils/deviceFeaturesUtils.ts

@@ -0,0 +1,340 @@
+import semver from 'semver';
+import { isNaN } from 'lodash';
+import { EDeviceType, ERRORS, HardwareErrorCode } from '@ukeyfe/hardware-shared';
+import { Enum_Capability } from '@ukeyfe/hardware-transport';
+import { toHardened } from '../api/helpers/pathUtils';
+import { DeviceCommands } from '../device/DeviceCommands';
+import type { Features, SupportFeatureType } from '../types';
+import { DeviceModelToTypes, DeviceTypeToModels } from '../types';
+import DataManager, { IFirmwareField, MessageVersion } from '../data-manager/DataManager';
+import { PROTOBUF_MESSAGE_CONFIG } from '../data-manager/MessagesConfig';
+import { Device } from '../device/Device';
+import { getDeviceType } from './deviceInfoUtils';
+import { getDeviceFirmwareVersion } from './deviceVersionUtils';
+import { existCapability } from './capabilitieUtils';
+
+export const getSupportMessageVersion = (
+  features: Features | undefined
+): { messages: JSON; messageVersion: MessageVersion } => {
+  if (!features)
+    return {
+      messages: DataManager.messages.latest,
+      messageVersion: 'latest',
+    };
+
+  const currentDeviceVersion = getDeviceFirmwareVersion(features).join('.');
+  const deviceType = getDeviceType(features);
+
+  const deviceVersionConfigs =
+    PROTOBUF_MESSAGE_CONFIG[deviceType] ||
+    (DeviceTypeToModels[deviceType] &&
+      DeviceTypeToModels[deviceType]
+        .map(model => PROTOBUF_MESSAGE_CONFIG[model])
+        .find(range => range !== undefined));
+
+  const sortedDeviceVersionConfigs =
+    deviceVersionConfigs?.sort((a, b) => semver.compare(b.minVersion, a.minVersion)) ?? [];
+
+  for (const { minVersion, messageVersion } of sortedDeviceVersionConfigs) {
+    if (semver.gte(currentDeviceVersion, minVersion)) {
+      return {
+        messages: DataManager.messages[messageVersion],
+        messageVersion,
+      };
+    }
+  }
+
+  return {
+    messages: DataManager.messages.latest,
+    messageVersion: 'latest',
+  };
+};
+
+export const supportInputPinOnSoftware = (features: Features): SupportFeatureType => {
+  if (!features) return { support: false };
+
+  const deviceType = getDeviceType(features);
+  if (deviceType === EDeviceType.Touch || deviceType === EDeviceType.Pro) {
+    return { support: false };
+  }
+
+  const currentVersion = getDeviceFirmwareVersion(features).join('.');
+  return { support: semver.gte(currentVersion, '2.3.0'), require: '2.3.0' };
+};
+
+export const supportNewPassphrase = (features?: Features): SupportFeatureType => {
+  if (!features) return { support: false };
+
+  const deviceType = getDeviceType(features);
+  if (deviceType === EDeviceType.Touch || deviceType === EDeviceType.Pro) {
+    return { support: true };
+  }
+
+  const currentVersion = getDeviceFirmwareVersion(features).join('.');
+
+  return { support: semver.gte(currentVersion, '2.4.0'), require: '2.4.0' };
+};
+
+export const getPassphraseStateWithRefreshDeviceInfo = async (
+  device: Device,
+  options?: {
+    expectPassphraseState?: string;
+    onlyMainPin?: boolean;
+  }
+) => {
+  const { features, commands } = device;
+  const locked = features?.unlocked === false;
+
+  const { passphraseState, newSession, unlockedAttachPin } = await getPassphraseState(
+    features,
+    commands,
+    {
+      ...options,
+    }
+  );
+
+  const isModeT =
+    getDeviceType(features) === EDeviceType.Touch || getDeviceType(features) === EDeviceType.Pro;
+
+  // 如果可以获取到 passphraseState，但是设备 features 显示设备未开启 passphrase，需要刷新设备状态
+  // if passphraseState can be obtained, but the device features show that the device has not enabled passphrase, the device status needs to be refreshed
+  const needRefreshWithPassphrase = passphraseState && features?.passphrase_protection !== true;
+  // 如果 Touch/Pro 在之前是锁定状态，刷新设备状态
+  // if Touch/Pro was locked before, refresh the device state
+  const needRefreshWithLocked = isModeT && locked;
+
+  if (needRefreshWithLocked || needRefreshWithPassphrase) {
+    // refresh device state
+    await device.getFeatures();
+  }
+
+  // Attach to pin try to fix internal state
+  if (features?.device_id) {
+    device.updateInternalState(
+      device.features?.passphrase_protection ?? false,
+      passphraseState,
+      device.features?.device_id ?? '',
+      newSession,
+      device.features?.session_id
+    );
+  }
+
+  return { passphraseState, newSession, unlockedAttachPin };
+};
+
+export const getPassphraseState = async (
+  features: Features | undefined,
+  commands: DeviceCommands,
+  options?: {
+    expectPassphraseState?: string;
+    onlyMainPin?: boolean;
+  }
+): Promise<{
+  passphraseState: string | undefined;
+  newSession: string | undefined;
+  unlockedAttachPin: boolean | undefined;
+}> => {
+  if (!features)
+    return { passphraseState: undefined, newSession: undefined, unlockedAttachPin: undefined };
+
+  const firmwareVersion = getDeviceFirmwareVersion(features);
+  const deviceType = getDeviceType(features);
+
+  const supportAttachPinCapability = existCapability(
+    features,
+    Enum_Capability.Capability_AttachToPin
+  );
+  const supportGetPassphraseState =
+    supportAttachPinCapability ||
+    (deviceType === EDeviceType.Pro && semver.gte(firmwareVersion.join('.'), '4.15.0'));
+
+  if (supportGetPassphraseState) {
+    const { message, type } = await commands.typedCall('GetPassphraseState', 'PassphraseState', {
+      passphrase_state: options?.onlyMainPin ? undefined : options?.expectPassphraseState,
+    });
+
+    // @ts-expect-error
+    if (type === 'CallMethodError') {
+      throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Get the passphrase state error');
+    }
+
+    return {
+      passphraseState: message.passphrase_state,
+      newSession: message.session_id,
+      unlockedAttachPin: message.unlocked_attach_pin,
+    };
+  }
+
+  const { message, type } = await commands.typedCall('GetAddress', 'Address', {
+    address_n: [toHardened(44), toHardened(1), toHardened(0), 0, 0],
+    coin_name: 'Testnet',
+    script_type: 'SPENDADDRESS',
+    show_display: false,
+  });
+
+  // @ts-expect-error
+  if (type === 'CallMethodError') {
+    throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Get the passphrase state error');
+  }
+
+  return {
+    passphraseState: message.address,
+    newSession: undefined,
+    unlockedAttachPin: undefined,
+  };
+};
+
+export const supportBatchPublicKey = (
+  features?: Features,
+  options?: {
+    includeNode?: boolean;
+  }
+): boolean => {
+  if (!features) return false;
+  const currentVersion = getDeviceFirmwareVersion(features).join('.');
+
+  const deviceType = getDeviceType(features);
+  // btc batch get public key
+  if (!!options?.includeNode && deviceType === EDeviceType.Pro) {
+    return semver.gte(currentVersion, '4.14.0');
+  }
+  if (!!options?.includeNode && deviceType === EDeviceType.Touch) {
+    return semver.gte(currentVersion, '4.11.0');
+  }
+  if (!!options?.includeNode && DeviceModelToTypes.model_classic1s.includes(deviceType)) {
+    return semver.gte(currentVersion, '3.12.0');
+  }
+  if (!!options?.includeNode && DeviceModelToTypes.model_mini.includes(deviceType)) {
+    return semver.gte(currentVersion, '3.10.0');
+  }
+  if (options?.includeNode) {
+    return false;
+  }
+
+  // support batch get public key
+  if (deviceType === EDeviceType.Touch || deviceType === EDeviceType.Pro) {
+    return semver.gte(currentVersion, '3.1.0');
+  }
+
+  return semver.gte(currentVersion, '2.6.0');
+};
+
+export const supportModifyHomescreen = (features?: Features): SupportFeatureType => {
+  if (!features) return { support: false };
+  const currentVersion = getDeviceFirmwareVersion(features).join('.');
+
+  const deviceType = getDeviceType(features);
+  if (DeviceModelToTypes.model_mini.includes(deviceType)) {
+    return { support: true };
+  }
+
+  return { support: semver.gte(currentVersion, '3.4.0') };
+};
+
+/**
+ *  Since 3.5.0, Touch uses the firmware-v3 field to get firmware release info
+ */
+export const getFirmwareUpdateField = ({
+  features,
+  updateType,
+  targetVersion,
+}: {
+  features: Features;
+  updateType: 'firmware' | 'ble';
+  targetVersion?: string;
+}): 'ble' | IFirmwareField => {
+  const deviceType = getDeviceType(features);
+  const deviceFirmwareVersion = getDeviceFirmwareVersion(features);
+  if (updateType === 'ble') {
+    return 'ble';
+  }
+
+  if (DeviceModelToTypes.model_mini.includes(deviceType)) {
+    return 'firmware-v7';
+  }
+
+  if (deviceType === EDeviceType.Touch) {
+    if (targetVersion) {
+      if (semver.eq(targetVersion, '4.0.0')) return 'firmware-v2';
+      if (semver.gt(targetVersion, '4.0.0')) return 'firmware-v7';
+    }
+
+    if (semver.lt(deviceFirmwareVersion.join('.'), '3.4.0')) return 'firmware';
+
+    return 'firmware-v7';
+  }
+  if (deviceType === EDeviceType.Pro) {
+    return 'firmware-v7';
+  }
+  return 'firmware';
+};
+/**
+ * Returns the optional firmware version
+ * Used in firmware web update
+ * https://firmware.ukey.so/
+ */
+export const getFirmwareUpdateFieldArray = (
+  features: Features,
+  updateType: 'firmware' | 'ble' | 'bootloader'
+): ('firmware' | 'ble' | 'firmware-v2' | 'firmware-v7')[] => {
+  const deviceType = getDeviceType(features);
+  if (updateType === 'ble') {
+    return ['ble'];
+  }
+
+  if (
+    deviceType === 'classic' ||
+    deviceType === 'classic1s' ||
+    deviceType === 'mini' ||
+    deviceType === 'classicpure'
+  ) {
+    return ['firmware-v7'];
+  }
+
+  if (deviceType === 'touch') {
+    const currentVersion = getDeviceFirmwareVersion(features).join('.');
+    if (semver.gt(currentVersion, '4.0.0')) {
+      return ['firmware-v7', 'firmware'];
+    }
+    if (semver.gte(currentVersion, '4.0.0')) {
+      return ['firmware-v2', 'firmware'];
+    }
+    if (!currentVersion || semver.lt(currentVersion, '3.0.0')) {
+      return ['firmware-v7', 'firmware-v2', 'firmware'];
+    }
+    return ['firmware'];
+  }
+
+  if (deviceType === 'pro') {
+    return ['firmware-v7'];
+  }
+
+  return ['firmware'];
+};
+
+export function fixVersion(version: string) {
+  let parts = version.split('.');
+
+  while (parts.length < 3) {
+    parts.push('0');
+  }
+  parts = parts.map(part => (isNaN(parseInt(part, 10)) ? '0' : part));
+
+  return parts.join('.');
+}
+
+export const fixFeaturesFirmwareVersion = (features: Features): Features => {
+  // 修复 Touch、Pro 设备 bootloader 低于 2.5.2 版本时，返回的 features 中没有 firmware_version 错误的问题
+  // fix Touch、Pro device when bootloader version is lower than 2.5.2, the features returned do not have firmware_version error
+  const tempFeatures = { ...features };
+
+  if (tempFeatures.ukey_firmware_version && !semver.valid(tempFeatures.ukey_firmware_version)) {
+    tempFeatures.ukey_firmware_version = fixVersion(tempFeatures.ukey_firmware_version);
+  }
+
+  if (tempFeatures.ukey_version && !semver.valid(tempFeatures.ukey_version)) {
+    tempFeatures.ukey_version = fixVersion(tempFeatures.ukey_version);
+  }
+
+  return tempFeatures;
+};

package/src/utils/deviceInfoUtils.ts

@@ -0,0 +1,166 @@
+import { isEmpty } from 'lodash';
+import { EDeviceType, EFirmwareType } from '@ukeyfe/hardware-shared';
+import { Enum_Capability } from '@ukeyfe/hardware-transport';
+import { DeviceModelToTypes } from '../types';
+
+import type { Features, IDeviceModel, IDeviceType, IVersionRange } from '../types';
+import { existCapability } from './capabilitieUtils';
+
+/**
+ * get device type by features
+ */
+export const getDeviceType = (features?: Features): IDeviceType => {
+  if (!features || typeof features !== 'object') {
+    return EDeviceType.Unknown;
+  }
+
+  // classic1s 3.5.0 pro 4.6.0
+  switch (features.ukey_device_type) {
+    case 'CLASSIC':
+      return EDeviceType.Classic;
+    case 'CLASSIC1S':
+      return EDeviceType.Classic1s;
+    case 'MINI':
+      return EDeviceType.Mini;
+    case 'TOUCH':
+      return EDeviceType.Touch;
+    case 'PRO':
+      return EDeviceType.Pro;
+    case 'PURE':
+      return EDeviceType.ClassicPure;
+    default:
+      // future And old device ukey_device_type is empty
+      if (!isEmpty(features.ukey_serial_no)) {
+        return EDeviceType.Unknown;
+      }
+    // old device type
+  }
+
+  // low version hardware
+  // ukey_serial_no > ukey_serial > serial_no
+  const serialNo = getDeviceUUID(features);
+
+  // not exist serialNo, bootloader mode, model 1 is classic
+  if (isEmpty(serialNo) && features.bootloader_mode === true && features.model === '1') {
+    return EDeviceType.Classic;
+  }
+
+  if (isEmpty(serialNo)) return EDeviceType.Unknown;
+
+  const miniFlag = serialNo.slice(0, 2);
+  // By May 2021, the miniFlag is 'bixin' for all classic devices
+  if (miniFlag.toLowerCase() === 'bi') return EDeviceType.Classic;
+  if (miniFlag.toLowerCase() === 'cl') return EDeviceType.Classic;
+  if (miniFlag.toLowerCase() === 'cp') return EDeviceType.ClassicPure;
+  if (miniFlag.toLowerCase() === 'mi') return EDeviceType.Mini;
+  if (miniFlag.toLowerCase() === 'tc') return EDeviceType.Touch;
+  if (miniFlag.toLowerCase() === 'pr') return EDeviceType.Pro;
+
+  // unknown device
+  return EDeviceType.Unknown;
+};
+
+/**
+ * get device type by ble name
+ * @param name Ble name
+ */
+export const getDeviceTypeByBleName = (name?: string): IDeviceType => {
+  if (!name) return EDeviceType.Unknown;
+
+  if (name.startsWith('BixinKey')) return EDeviceType.Classic;
+  if (name.startsWith('K')) return EDeviceType.Classic;
+
+  if (name.startsWith('T')) return EDeviceType.Touch;
+  if (name.startsWith('Touch')) return EDeviceType.Touch;
+
+  if (name.startsWith('Pro')) return EDeviceType.Pro;
+
+  return EDeviceType.Unknown;
+};
+
+/**
+ * Get Connected Device ble name by features
+ * @returns
+ */
+export const getDeviceBleName = (features?: Features): string | null => {
+  if (features == null) return null;
+  return features.ukey_ble_name || features.ble_name || null;
+};
+
+/**
+ * Get Connected Device UUID by features
+ */
+export const getDeviceUUID = (features: Features) => {
+  const serialNo = features.ukey_serial_no || features.ukey_serial || features.serial_no;
+  return serialNo ?? '';
+};
+
+/**
+ * Get Connected Device label by features
+ */
+export const getDeviceLabel = (features?: Features) => {
+  if (!features) return null;
+
+  const deviceType = getDeviceType(features);
+  if (deviceType == null) return null;
+
+  if (typeof features.label === 'string' && !isEmpty(features.label)) {
+    return features.label;
+  }
+
+  const bleName = getDeviceBleName(features);
+  if (!isEmpty(bleName)) return bleName;
+
+  if (deviceType === EDeviceType.ClassicPure) {
+    return 'UKey Classic 1S';
+  }
+
+  return `UKey ${deviceType.charAt(0).toUpperCase() + deviceType.slice(1)}`;
+};
+
+/**
+ * Get firmware version range by features
+ * Type has a higher priority than Model
+ */
+export const getMethodVersionRange = (
+  features: Features | undefined,
+  getVersionRange: (deviceModel: IDeviceType | IDeviceModel) => IVersionRange | undefined
+): IVersionRange | undefined => {
+  const deviceType = getDeviceType(features);
+  let versionRange: IVersionRange | undefined = getVersionRange(deviceType);
+
+  if (versionRange) {
+    return versionRange;
+  }
+
+  const modelFallbacks: IDeviceModel[] = [
+    'model_classic1s',
+    'model_classic',
+    'model_mini',
+    'model_touch',
+  ];
+  for (const model of modelFallbacks) {
+    if (DeviceModelToTypes[model].includes(deviceType)) {
+      versionRange = getVersionRange(model);
+      if (versionRange) {
+        return versionRange;
+      }
+    }
+  }
+
+  return versionRange;
+};
+
+export const getFirmwareType = (features: Features | undefined) => {
+  if (!features) {
+    return EFirmwareType.Universal;
+  }
+  if (features.fw_vendor === 'UKey Bitcoin-only') {
+    return EFirmwareType.BitcoinOnly;
+  }
+  // old firmware
+  return features?.capabilities?.length > 0 &&
+    !existCapability(features, Enum_Capability.Capability_Bitcoin_like)
+    ? EFirmwareType.BitcoinOnly
+    : EFirmwareType.Universal;
+};

package/src/utils/deviceVersionUtils.ts

@@ -0,0 +1,78 @@
+import semver from 'semver';
+import type { Features, IVersionArray } from '../types';
+
+/**
+ * Get Connected Device version by features
+ */
+export const getDeviceFirmwareVersion = (features: Features | undefined): IVersionArray => {
+  if (!features) return [0, 0, 0];
+
+  if (semver.valid(features.ukey_firmware_version)) {
+    return features.ukey_firmware_version?.split('.') as unknown as IVersionArray;
+  }
+
+  if (semver.valid(features.ukey_version)) {
+    return features.ukey_version?.split('.') as unknown as IVersionArray;
+  }
+
+  return [0, 0, 0];
+};
+
+/**
+ * Get Connected Device bluetooth firmware version by features
+ */
+export const getDeviceBLEFirmwareVersion = (features: Features): IVersionArray => {
+  const bleVer = features?.ukey_ble_version || features?.ble_ver;
+
+  if (!bleVer) {
+    return [0, 0, 0];
+  }
+
+  if (!semver.valid(bleVer)) {
+    return [0, 0, 0];
+  }
+
+  if (bleVer) {
+    return bleVer.split('.').map(Number) as IVersionArray;
+  }
+  return [0, 0, 0];
+};
+
+/**
+ * Get Connected Device bootloader version by features
+ */
+export const getDeviceBootloaderVersion = (features: Features | undefined): IVersionArray => {
+  if (!features) return [0, 0, 0];
+
+  // classic1s 3.5.0 pro 4.6.0
+  if (semver.valid(features.ukey_boot_version)) {
+    return features.ukey_boot_version?.split('.') as unknown as IVersionArray;
+  }
+
+  // low version hardware
+  if (!features.bootloader_version) {
+    if (features.bootloader_mode) {
+      return [
+        features?.major_version ?? 0,
+        features?.minor_version ?? 0,
+        features?.patch_version ?? 0,
+      ];
+    }
+    return [0, 0, 0];
+  }
+  if (semver.valid(features.bootloader_version)) {
+    return features.bootloader_version?.split('.') as unknown as IVersionArray;
+  }
+  return [0, 0, 0];
+};
+
+/**
+ * Get Connected Device boardloader version by features
+ */
+export const getDeviceBoardloaderVersion = (features: Features): IVersionArray => {
+  if (semver.valid(features?.ukey_board_version)) {
+    return features?.ukey_board_version?.split('.') as unknown as IVersionArray;
+  }
+
+  return [0, 0, 0];
+};

package/src/utils/findDefectiveBatchDevice.ts

@@ -0,0 +1,38 @@
+import type { Features } from '../types';
+import { getDeviceUUID, getDeviceType } from './deviceInfoUtils';
+
+/**
+ * 检测故障固件设备
+ * 检测规则：
+ * - 序列号范围：21032200001 到 21032201500 (从 ukey_serial 字段提取)
+ * - SE版本为 1.1.0.2
+ *
+ * 对齐之前版本的检测逻辑
+ */
+export const findDefectiveBatchDevice = (features: Features) => {
+  if (!features) return;
+
+  const { ukey_serial: ukeySerial, se_ver: seVer } = features;
+  if (!ukeySerial) return;
+
+  const versionNum = +ukeySerial.slice(5);
+  if (Number.isNaN(versionNum)) return;
+
+  return versionNum >= 21032200001 && versionNum <= 21032201500 && seVer === '1.1.0.2';
+};
+
+/**
+ * 获取故障设备的详细信息
+ */
+export const getDefectiveDeviceInfo = (features: Features) => {
+  if (!findDefectiveBatchDevice(features)) return null;
+  const serialNo = getDeviceUUID(features);
+  const deviceType = getDeviceType(features);
+  const seVersion = features.se_ver;
+
+  return {
+    serialNo,
+    seVersion,
+    deviceType: deviceType || 'Unknown',
+  };
+};

package/src/utils/getMutex.ts

@@ -0,0 +1,41 @@
+/**
+ * Ensures that since the awaited lock is obtained until unlock return from it
+ * is called, no other part of code can enter the same lock.
+ *
+ * Optionally, it also takes `lockId` param, in which case only actions with
+ * the same lock id are blocking each other.
+ *
+ * Example:
+ *
+ * ```
+ * const lock = getMutex();
+ *
+ * lock().then(unlock => writeToSocket('foo').finally(unlock));
+ * lock().then(unlock => writeToSocket('bar').finally(unlock));
+ * lock('differentLockId').then(unlock => writeToAnotherSocket('baz').finally(unlock));
+ *
+ * const unlock = await lock();
+ * await readFromSocket();
+ * unlock();
+ * ```
+ */
+export const getMutex = () => {
+  // eslint-disable-next-line symbol-description
+  const DEFAULT_ID = Symbol();
+  const locks: Record<keyof any, Promise<void>> = {};
+
+  return async (lockId: keyof any = DEFAULT_ID) => {
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises
+    while (locks[lockId]) {
+      await locks[lockId];
+    }
+    let resolve = () => {};
+    locks[lockId] = new Promise<void>(res => {
+      resolve = res;
+    }).finally(() => {
+      delete locks[lockId];
+    });
+
+    return resolve;
+  };
+};

package/src/utils/getSynchronize.ts

@@ -0,0 +1,25 @@
+import { getMutex } from './getMutex';
+
+/**
+ * Ensures that all async actions passed to the returned function are called
+ * immediately one after another, without interfering with each other.
+ * Optionally, it also takes `lockId` param, in which case only actions with
+ * the same lock id are blocking each other.
+ *
+ * Example:
+ *
+ * ```
+ * const synchronize = getSynchronize();
+ * synchronize(() => asyncAction1());
+ * synchronize(() => asyncAction2());
+ * synchronize(() => asyncAction3(), 'differentLockId');
+ * ```
+ */
+export const getSynchronize = (mutex?: ReturnType<typeof getMutex>) => {
+  const lock = mutex ?? getMutex();
+
+  return <T>(action: () => T, lockId?: keyof any): T extends Promise<unknown> ? T : Promise<T> =>
+    lock(lockId).then(unlock => Promise.resolve().then(action).finally(unlock)) as any;
+};
+
+export type Synchronize = ReturnType<typeof getSynchronize>;