@ukeyfe/hardware-core 1.1.13

package/src/device/DeviceList.ts

@@ -0,0 +1,37 @@
+import EventEmitter from 'events';
+import DeviceConnector from './DeviceConnector';
+import { Device, InitOptions } from './Device';
+import { DevicePool } from './DevicePool';
+
+export class DeviceList extends EventEmitter {
+  devices: Record<string, Device> = {};
+
+  connector?: DeviceConnector;
+
+  /**
+   * 获取已连接的设备列表
+   * @returns {UKeyDeviceInfo[]}
+   */
+  async getDeviceLists(connectId?: string, initOptions?: InitOptions) {
+    const deviceDiff = await this.connector?.enumerate();
+    const descriptorList = deviceDiff?.descriptors ?? [];
+
+    this.devices = {};
+
+    const { deviceList, devices } = await DevicePool.getDevices(
+      descriptorList,
+      connectId,
+      initOptions
+    );
+    this.devices = devices;
+    return deviceList;
+  }
+
+  allDevices(): Device[] {
+    return Object.keys(this.devices).map(key => this.devices[key]);
+  }
+
+  getDevice(connectId: string) {
+    return this.devices[connectId];
+  }
+}

package/src/device/DevicePool.ts

@@ -0,0 +1,263 @@
+import EventEmitter from 'events';
+import { UKeyDeviceInfo as DeviceDescriptor } from '@ukeyfe/hardware-transport';
+// eslint-disable-next-line import/no-cycle
+import { Device, InitOptions } from './Device';
+import { DEVICE } from '../events';
+import type DeviceConnector from './DeviceConnector';
+import { getDeviceUUID, getLogger, LoggerNames } from '../utils';
+
+const Log = getLogger(LoggerNames.DevicePool);
+
+export type DeviceDescriptorDiff = {
+  didUpdate: boolean;
+  connected: DeviceDescriptor[];
+  disconnected: DeviceDescriptor[];
+  changedSessions: DeviceDescriptor[];
+  changedDebugSessions: DeviceDescriptor[];
+  acquired: DeviceDescriptor[];
+  debugAcquired: DeviceDescriptor[];
+  released: DeviceDescriptor[];
+  debugReleased: DeviceDescriptor[];
+  descriptors: DeviceDescriptor[];
+};
+
+const getDiff = (
+  current: DeviceDescriptor[],
+  descriptors: DeviceDescriptor[]
+): DeviceDescriptorDiff => {
+  const connected = descriptors.filter(d => current.find(x => x.path === d.path) === undefined);
+  const disconnected = current.filter(d => descriptors.find(x => x.path === d.path) === undefined);
+  const changedSessions = descriptors.filter(d => {
+    const currentDescriptor = current.find(x => x.path === d.path);
+    if (currentDescriptor) {
+      return currentDescriptor.session !== d.session;
+    }
+    return false;
+  });
+  const acquired = changedSessions.filter(d => typeof d.session === 'string');
+  const released = changedSessions.filter(d => typeof d.session !== 'string');
+
+  const changedDebugSessions = descriptors.filter(d => {
+    const currentDescriptor = current.find(x => x.path === d.path);
+    if (currentDescriptor) {
+      return currentDescriptor.debugSession !== d.debugSession;
+    }
+    return false;
+  });
+  const debugAcquired = changedSessions.filter(d => typeof d.debugSession === 'string');
+  const debugReleased = changedSessions.filter(d => typeof d.debugSession !== 'string');
+
+  const didUpdate =
+    connected.length + disconnected.length + changedSessions.length + changedDebugSessions.length >
+    0;
+
+  return {
+    connected,
+    disconnected,
+    changedSessions,
+    acquired,
+    released,
+    changedDebugSessions,
+    debugAcquired,
+    debugReleased,
+    didUpdate,
+    descriptors,
+  };
+};
+
+export class DevicePool extends EventEmitter {
+  static current: DeviceDescriptor[] | null = null;
+
+  static upcoming: DeviceDescriptor[] = [];
+
+  static connectedPool: DeviceDescriptor[] = [];
+
+  static disconnectPool: DeviceDescriptor[] = [];
+
+  static devicesCache: Record<string, Device> = {};
+
+  static emitter = new EventEmitter();
+
+  static connector: DeviceConnector;
+
+  static setConnector(connector: DeviceConnector) {
+    this.connector = connector;
+  }
+
+  static async getDevices(
+    descriptorList: DeviceDescriptor[],
+    connectId?: string,
+    initOptions?: InitOptions
+  ) {
+    // Log.debug('get device list: connectId: ', connectId);
+
+    const devices: Record<string, Device> = {};
+    const deviceList = [];
+
+    // If there is a connectId
+    // it means that you only want to get data from cache
+    if (connectId) {
+      const device = this.devicesCache[connectId];
+      if (device) {
+        const exist = descriptorList.find(d => d.path === device.originalDescriptor.path);
+        if (exist) {
+          // Log.debug('find existed Device: ', connectId);
+          device.updateDescriptor(exist, true);
+          devices[connectId] = device;
+          deviceList.push(device);
+          await this._checkDevicePool(initOptions);
+          return { devices, deviceList };
+        }
+        Log.debug('found device in cache, but path is different: ', connectId);
+      }
+    }
+
+    for await (const descriptor of descriptorList) {
+      const device = await this._createDevice(descriptor, initOptions);
+
+      if (device.features) {
+        const uuid = getDeviceUUID(device.features);
+        if (this.devicesCache[uuid]) {
+          const cache = this.devicesCache[uuid];
+          cache.updateDescriptor(descriptor, true);
+        }
+        this.devicesCache[uuid] = device;
+        devices[uuid] = device;
+      }
+
+      deviceList.push(device);
+    }
+    // Log.debug('get devices result : ', devices, deviceList);
+    // console.log('device poll -> connected: ', this.connectedPool);
+    // console.log('device poll -> disconnected: ', this.disconnectPool);
+    await this._checkDevicePool(initOptions);
+    return { devices, deviceList };
+  }
+
+  static clearDeviceCache(connectId?: string) {
+    // Log.debug('clear device pool cache: connectId', connectId);
+    // Log.debug('clear device pool cache: ', this.devicesCache);
+    if (connectId) {
+      delete this.devicesCache[connectId];
+    }
+  }
+
+  static async _createDevice(descriptor: DeviceDescriptor, initOptions?: InitOptions) {
+    let device = this.getDeviceByPath(descriptor.path);
+    if (!device) {
+      device = Device.fromDescriptor(descriptor);
+      device.deviceConnector = this.connector;
+      await device.connect();
+      await device.initialize(initOptions);
+      await device.release();
+    }
+    return device;
+  }
+
+  static async _checkDevicePool(initOptions?: InitOptions) {
+    await this._sendConnectMessage(initOptions);
+    this._sendDisconnectMessage();
+  }
+
+  static async _sendConnectMessage(initOptions?: InitOptions) {
+    for (let i = this.connectedPool.length - 1; i >= 0; i--) {
+      const descriptor = this.connectedPool[i];
+      const device = await this._createDevice(descriptor, initOptions);
+      Log.debug('emit DEVICE.CONNECT: ', device?.features);
+      this.emitter.emit(DEVICE.CONNECT, device);
+      this.connectedPool.splice(i, 1);
+    }
+  }
+
+  static _sendDisconnectMessage() {
+    for (let i = this.disconnectPool.length - 1; i >= 0; i--) {
+      const descriptor = this.connectedPool[i];
+      const device = descriptor?.path ? this.getDeviceByPath(descriptor.path) : null;
+      if (device) {
+        this.emitter.emit(DEVICE.DISCONNECT, device);
+      }
+      this.disconnectPool.splice(i, 1);
+    }
+  }
+
+  static reportDeviceChange(upcoming: DeviceDescriptor[]) {
+    const diff = getDiff(this.current || [], upcoming);
+
+    this.upcoming = upcoming;
+    this.current = this.upcoming;
+
+    Log.debug('device pool -> current: ', this.current);
+    Log.debug('device pool -> upcomming: ', this.upcoming);
+    Log.debug('DeviceCache.reportDeviceChange diff: ', diff);
+
+    if (!diff.didUpdate) {
+      return;
+    }
+
+    diff.connected.forEach(d => {
+      const device = this.getDeviceByPath(d.path);
+      if (!device) {
+        this._addConnectedDeviceToPool(d);
+        return;
+      }
+      Log.debug('emit DEVICE.CONNECT: ', device.features);
+      this.emitter.emit(DEVICE.CONNECT, device);
+    });
+
+    diff.disconnected.forEach(d => {
+      this._removeDeviceFromConnectedPool(d.path);
+      const device = this.getDeviceByPath(d.path);
+      if (!device) {
+        this._addDisconnectedDeviceToPool(d);
+        return;
+      }
+
+      Log.debug('emit DEVICE.DISCONNECT: ', device.features);
+      this.emitter.emit(DEVICE.DISCONNECT, device);
+    });
+  }
+
+  static getDeviceByPath(path: string) {
+    return Object.values(this.devicesCache).find(d => d.originalDescriptor.path === path);
+  }
+
+  static _addConnectedDeviceToPool(descriptor: DeviceDescriptor) {
+    const existDescriptorIndex = this.connectedPool.findIndex(d => d.path === descriptor.path);
+    if (existDescriptorIndex > -1) {
+      this.connectedPool.splice(existDescriptorIndex, 1, descriptor);
+      return;
+    }
+
+    this.connectedPool.push(descriptor);
+  }
+
+  static _removeDeviceFromConnectedPool(path: string) {
+    const index = this.connectedPool.findIndex(d => d.path === path);
+    if (index > -1) {
+      this.connectedPool.splice(index, 1);
+    }
+  }
+
+  static _addDisconnectedDeviceToPool(descriptor: DeviceDescriptor) {
+    const existDescriptorIndex = this.disconnectPool.findIndex(d => d.path === descriptor.path);
+    if (existDescriptorIndex > -1) {
+      this.disconnectPool.splice(existDescriptorIndex, 1, descriptor);
+      return;
+    }
+
+    this.disconnectPool.push(descriptor);
+  }
+
+  static resetState() {
+    this.current = null;
+    this.upcoming = [];
+    this.connectedPool = [];
+    this.disconnectPool = [];
+    this.devicesCache = {};
+
+    // Clear all event listeners but keep the emitter instance
+    this.emitter.removeAllListeners();
+
+    Log.debug('DevicePool state has been reset');
+  }
+}

package/src/events/call.ts

@@ -0,0 +1,94 @@
+import { serializeError } from '@ukeyfe/hardware-shared';
+import { IFRAME } from './iframe';
+import { CommonParams, CoreApi, ConnectSettings } from '../types';
+
+type UnwrappedResponse<T> = T extends Promise<infer R>
+  ? R extends { success: true; payload: infer P }
+    ? P
+    : never
+  : void;
+
+type OverloadedMethod<T, E extends Record<string, string>> = T extends {
+  (params: infer P1): infer R1;
+  (params: infer P2): infer R2;
+}
+  ? ((params: P1 & E) => R1) | ((params: P2 & E) => R2) // - method IS overloaded, result depends on params (example: getAddress)
+  : T extends (...args: infer P) => infer R
+  ? (params: E & P[0]) => R // - method in NOT overloaded, one set of params and one set of result (example: signTransaction)
+  : never;
+
+type UnwrappedMethod<T, M extends Record<string, string>> = T extends () => infer R
+  ? (params: M & CommonParams) => R // - method doesn't have params (example: dispose, disableWebUSB)
+  : OverloadedMethod<T, M>;
+
+type IsMethodCallable<T> = T extends (...args: any[]) => infer R
+  ? R extends Promise<{ success: boolean }>
+    ? R
+    : never
+  : never;
+
+type CallApi = {
+  [K in keyof CoreApi]: IsMethodCallable<CoreApi[K]> extends never
+    ? never
+    : UnwrappedMethod<CoreApi[K], { method: K }>;
+};
+
+export type CallMethodUnion = CallApi[keyof CallApi];
+export type CallMethodPayload = Parameters<CallMethodUnion>[0];
+export type CallMethodResponse<M extends keyof CallApi> = UnwrappedResponse<ReturnType<CallApi[M]>>;
+export type CallMethodAnyResponse = ReturnType<CallMethodUnion>;
+
+export type CallMethod = (params: CallMethodPayload) => Promise<any>;
+
+export interface IFrameCallMessage {
+  event: typeof IFRAME.CALL;
+  type: typeof IFRAME.CALL;
+  payload: CallMethodPayload;
+}
+
+export interface IFrameCancelMessage {
+  event: typeof IFRAME.CANCEL;
+  type: typeof IFRAME.CANCEL;
+  payload: { connectId?: string };
+}
+
+export interface IFrameSwitchTransportMessage {
+  event: typeof IFRAME.SWITCH_TRANSPORT;
+  type: typeof IFRAME.SWITCH_TRANSPORT;
+  payload: { env: ConnectSettings['env'] };
+}
+
+export interface IFrameCallbackMessage {
+  event: typeof IFRAME.CALLBACK;
+  type: typeof IFRAME.CALLBACK;
+  payload: {
+    callbackId: string;
+    data?: any;
+    error?: any;
+  };
+}
+
+export const RESPONSE_EVENT = 'RESPONSE_EVENT';
+
+export interface MethodResponseMessage {
+  event: typeof RESPONSE_EVENT;
+  type: typeof RESPONSE_EVENT;
+  id: number;
+  success: boolean;
+  payload: any;
+}
+
+export const createResponseMessage = (
+  id: number,
+  success: boolean,
+  payload: any
+): MethodResponseMessage => ({
+  event: RESPONSE_EVENT,
+  type: RESPONSE_EVENT,
+  id,
+  success,
+
+  payload: success ? payload : serializeError(payload),
+});
+
+export type CallMethodKeys = keyof CoreApi;

package/src/events/core.ts

@@ -0,0 +1,64 @@
+import { HardwareError } from '@ukeyfe/hardware-shared';
+import { Unsuccessful } from '../types/params';
+import {
+  IFrameCallMessage,
+  IFrameCancelMessage,
+  IFrameSwitchTransportMessage,
+  IFrameCallbackMessage,
+} from './call';
+import { DeviceEventMessage } from './device';
+import { IFrameEventMessage } from './iframe';
+import { UiEventMessage } from './ui-request';
+import { UiResponseMessage } from './ui-response';
+import { LogEventMessage } from './log';
+import { FirmwareMessage } from './firmware';
+
+export const CORE_EVENT = 'CORE_EVENT';
+
+export type CoreMessage = {
+  id?: string;
+  success?: true | false;
+} & (
+  | IFrameEventMessage
+  | IFrameCallMessage
+  | IFrameCancelMessage
+  | IFrameSwitchTransportMessage
+  | IFrameCallbackMessage
+  | UiResponseMessage
+  | UiEventMessage
+  | DeviceEventMessage
+  | LogEventMessage
+  | FirmwareMessage
+);
+
+export type PostMessageEvent = MessageEvent<any>;
+
+export const parseMessage = (messageData: any): CoreMessage => {
+  const { data } = messageData;
+  const message: CoreMessage = {
+    event: data.event,
+    type: data.type,
+    payload: data.payload,
+  };
+
+  if (typeof messageData.id === 'number') {
+    message.id = messageData.id;
+  }
+
+  if (typeof message.success === 'boolean') {
+    message.success = data.success;
+  }
+
+  return message;
+};
+
+export const createErrorMessage = (error: Error & { code?: string | number }): Unsuccessful => {
+  let payload = { error: error.message, code: error.code };
+  if (error instanceof HardwareError) {
+    payload = { error: error.message, code: error.errorCode };
+  }
+  return {
+    success: false,
+    payload,
+  };
+};

package/src/events/device.ts

@@ -0,0 +1,91 @@
+import type { PROTO } from '../constants';
+import type { Features, KnownDevice as Device, SupportFeatures } from '../types/device';
+import { MessageFactoryFn } from './utils';
+
+export const DEVICE_EVENT = 'DEVICE_EVENT';
+export const DEVICE = {
+  // device list events
+  CONNECT: 'device-connect',
+  CONNECT_UNACQUIRED: 'device-connect_unacquired',
+  DISCONNECT: 'device-disconnect',
+  CHANGED: 'device-changed',
+  ACQUIRE: 'device-acquire',
+  RELEASE: 'device-release',
+  ACQUIRED: 'device-acquired',
+  RELEASED: 'device-released',
+  USED_ELSEWHERE: 'device-used_elsewhere',
+  UNREADABLE: 'unreadable-device',
+
+  LOADING: 'device-loading',
+
+  // ukey-transport events in protobuf format
+  BUTTON: 'button',
+  PIN: 'pin',
+  PASSPHRASE: 'passphrase',
+  PASSPHRASE_ON_DEVICE: 'passphrase_on_device',
+  WORD: 'word',
+  SUPPORT_FEATURES: 'support_features',
+  SELECT_DEVICE_IN_BOOTLOADER_FOR_WEB_DEVICE: 'select_device_in_bootloader_for_web_device',
+
+  FEATURES: 'features',
+} as const;
+
+export interface DeviceConnnectRequest {
+  type: typeof DEVICE.CONNECT;
+  payload: { device: Device };
+}
+
+export interface DeviceDisconnnectRequest {
+  type: typeof DEVICE.DISCONNECT;
+  payload: { device: Device };
+}
+
+export interface DeviceButtonRequestPayload extends Omit<PROTO.ButtonRequest, 'code'> {
+  code?: PROTO.ButtonRequest['code'] | 'ButtonRequest_FirmwareUpdate';
+}
+
+export type PassphraseRequestPayload = {
+  existsAttachPinUser?: boolean;
+};
+
+export interface DeviceButtonRequest {
+  type: typeof DEVICE.BUTTON;
+  payload: DeviceButtonRequestPayload & { device: Device | null };
+}
+
+export type DeviceFeaturesPayload = Features;
+
+export interface DeviceSendFeatures {
+  type: typeof DEVICE.FEATURES;
+  payload: DeviceFeaturesPayload;
+}
+
+export type DeviceSupportFeaturesPayload = SupportFeatures & { device: Device | null };
+export interface DeviceSendSupportFeatures {
+  type: typeof DEVICE.SUPPORT_FEATURES;
+  payload: DeviceSupportFeaturesPayload;
+}
+
+export type DeviceEvent =
+  | DeviceButtonRequest
+  | DeviceSendFeatures
+  | DeviceSendSupportFeatures
+  | DeviceDisconnnectRequest
+  | DeviceConnnectRequest;
+
+export type DeviceEventMessage = DeviceEvent & { event: typeof DEVICE_EVENT };
+
+export type DeviceEventListenerFn = (
+  type: typeof DEVICE_EVENT,
+  cb: (event: DeviceEventMessage) => void
+) => void;
+
+export const createDeviceMessage: MessageFactoryFn<typeof DEVICE_EVENT, DeviceEvent> = (
+  type,
+  payload
+) =>
+  ({
+    event: DEVICE_EVENT,
+    type,
+    payload,
+  } as any);

package/src/events/firmware.ts

@@ -0,0 +1,40 @@
+import { MessageFactoryFn } from './utils';
+import { getBleFirmwareReleaseInfo, getFirmwareReleaseInfo } from '../api/firmware/releaseHelper';
+import type { KnownDevice as Device } from '../types/device';
+
+export const FIRMWARE_EVENT = 'FIRMWARE_EVENT';
+export const FIRMWARE = {
+  RELEASE_INFO: 'firmware-release-info',
+  BLE_RELEASE_INFO: 'ble-firmware-release-info',
+} as const;
+
+export type ReleaseInfoPayload = ReturnType<typeof getFirmwareReleaseInfo> & {
+  device?: Device | null;
+};
+export interface ReleaseInfoEvent {
+  type: typeof FIRMWARE.RELEASE_INFO;
+  payload: ReleaseInfoPayload;
+}
+
+export type BleReleaseInfoPayload = ReturnType<typeof getBleFirmwareReleaseInfo> & {
+  device?: Device | null;
+};
+
+export interface BleReleaseInfoEvent {
+  type: typeof FIRMWARE.BLE_RELEASE_INFO;
+  payload: BleReleaseInfoPayload;
+}
+
+export type FirmwareEvent = ReleaseInfoEvent | BleReleaseInfoEvent;
+
+export type FirmwareMessage = FirmwareEvent & { event: typeof FIRMWARE_EVENT };
+
+export const createFirmwareMessage: MessageFactoryFn<typeof FIRMWARE_EVENT, FirmwareEvent> = (
+  type,
+  payload
+) =>
+  ({
+    event: FIRMWARE_EVENT,
+    type,
+    payload,
+  } as any);

package/src/events/iframe.ts

@@ -0,0 +1,54 @@
+import type { ConnectSettings } from '../types';
+import { UI_EVENT } from './ui-request';
+import { MessageFactoryFn } from './utils';
+
+export const IFRAME = {
+  INIT: 'iframe-init',
+  INIT_BRIDGE: 'iframe-init-bridge',
+  CALL: 'iframe-call',
+  CANCEL: 'iframe-cancel',
+  SWITCH_TRANSPORT: 'iframe-switch-transport',
+  CALLBACK: 'iframe-callback',
+} as const;
+
+export interface IFrameInit {
+  type: typeof IFRAME.INIT;
+  payload: {
+    settings: ConnectSettings;
+  };
+}
+
+export interface IFrameBridge {
+  type: typeof IFRAME.INIT_BRIDGE;
+  payload: unknown;
+}
+
+export interface IFrameSwitchTransport {
+  type: typeof IFRAME.SWITCH_TRANSPORT;
+  payload: {
+    env: ConnectSettings['env'];
+  };
+}
+
+export interface IFrameCallback {
+  type: typeof IFRAME.CALLBACK;
+  payload: {
+    callbackId: string;
+    data?: any;
+    error?: any;
+    finished?: boolean;
+  };
+}
+
+export type IFrameEvent = IFrameInit | IFrameBridge | IFrameSwitchTransport | IFrameCallback;
+export type IFrameEventMessage = IFrameEvent & { event: typeof UI_EVENT };
+
+export const createIFrameMessage: MessageFactoryFn<typeof UI_EVENT, IFrameEvent> = (
+  type,
+  payload
+) =>
+  ({
+    event: UI_EVENT,
+    type,
+    payload,
+  } as any);

package/src/events/index.ts

@@ -0,0 +1,10 @@
+export * from './core';
+export * from './iframe';
+export * from './call';
+export * from './ui-request';
+export * from './ui-promise';
+export * from './ui-response';
+export * from './device';
+export * from './log';
+export * from './firmware';
+export * from './logBlockEvent';

package/src/events/log.ts

@@ -0,0 +1,23 @@
+import type { MessageFactoryFn } from './utils';
+
+export const LOG_EVENT = 'LOG_EVENT';
+
+export const LOG = {
+  OUTPUT: 'log-output',
+} as const;
+
+export interface LogOutput {
+  type: typeof LOG.OUTPUT;
+  payload: any;
+}
+
+export type LogEvent = LogOutput;
+
+export type LogEventMessage = LogEvent & { event: typeof LOG_EVENT };
+
+export const createLogMessage: MessageFactoryFn<typeof LOG_EVENT, LogEvent> = (type, payload) =>
+  ({
+    event: LOG_EVENT,
+    type,
+    payload,
+  } as any);

package/src/events/logBlockEvent.ts

@@ -0,0 +1,6 @@
+import { UI_RESPONSE } from './ui-response';
+
+export const LogBlockEvent: Set<string> = new Set([
+  UI_RESPONSE.RECEIVE_PIN,
+  UI_RESPONSE.RECEIVE_PASSPHRASE,
+]);

package/src/events/ui-promise.ts

@@ -0,0 +1,14 @@
+import type { Deferred } from '@ukeyfe/hardware-shared';
+import type { DEVICE } from './device';
+import type { Device } from '../device/Device';
+import type { UiResponseEvent } from './ui-response';
+
+export type UiPromiseResponse =
+  | UiResponseEvent
+  | { type: typeof DEVICE.DISCONNECT; payload?: undefined };
+
+export type UiPromise<T extends UiPromiseResponse['type']> = Deferred<
+  Extract<UiPromiseResponse, { type: T }>,
+  T,
+  Device
+>;