@ukeyfe/hardware-transport-web-device 1.1.13

package/src/electron-ble-transport.ts

@@ -0,0 +1,413 @@
+import transport, { COMMON_HEADER_SIZE, LogBlockCommand } from '@ukeyfe/hardware-transport';
+import {
+  ERRORS,
+  HardwareErrorCode,
+  HardwareErrorCodeMessage,
+  Deferred,
+  createDeferred,
+  isHeaderChunk,
+} from '@ukeyfe/hardware-shared';
+import type EventEmitter from 'events';
+// Import DesktopAPI type from hd-transport-electron
+import type { DesktopAPI } from '@ukeyfe/hardware-transport-electron';
+
+const { parseConfigure, buildBuffers, receiveOne, check } = transport;
+
+// Noble BLE specific API interface
+declare global {
+  interface Window {
+    desktopApi?: DesktopAPI;
+  }
+}
+
+export type BleAcquireInput = {
+  uuid: string;
+  forceCleanRunPromise?: boolean;
+};
+
+// Packet processing result interface
+interface PacketProcessResult {
+  isComplete: boolean;
+  completePacket?: string;
+  error?: string;
+}
+
+export default class ElectronBleTransport {
+  _messages: ReturnType<typeof transport.parseConfigure> | undefined;
+
+  name = 'ElectronBleTransport';
+
+  configured = false;
+
+  runPromise: Deferred<any> | null = null;
+
+  Log?: any;
+
+  emitter?: EventEmitter;
+
+  // Cache for connected devices
+  private connectedDevices: Set<string> = new Set();
+
+  // Data processing state
+  private dataBuffers: Map<string, { buffer: number[]; bufferLength: number }> = new Map();
+
+  // Notification cleanup functions
+  private notificationCleanups: Map<string, () => void> = new Map();
+
+  // Disconnect listener cleanup functions
+  private disconnectCleanups: Map<string, () => void> = new Map();
+
+  // Handle bluetooth related errors with proper error code mapping
+  private handleBluetoothError(error: any): never {
+    if (error && typeof error === 'object') {
+      // Check for specific bluetooth error codes
+      if ('code' in error) {
+        if (error.code === HardwareErrorCode.BlePoweredOff) {
+          throw ERRORS.TypedError(HardwareErrorCode.BlePoweredOff);
+        }
+        if (error.code === HardwareErrorCode.BleUnsupported) {
+          throw ERRORS.TypedError(HardwareErrorCode.BleUnsupported);
+        }
+        if (error.code === HardwareErrorCode.BlePermissionError) {
+          throw ERRORS.TypedError(HardwareErrorCode.BlePermissionError);
+        }
+      }
+      // Check for error message containing bluetooth state related text using predefined messages
+      const errorMessage = error.message || String(error);
+      const poweredOffMessage = HardwareErrorCodeMessage[HardwareErrorCode.BlePoweredOff];
+      const unsupportedMessage = HardwareErrorCodeMessage[HardwareErrorCode.BleUnsupported];
+      const permissionMessage = HardwareErrorCodeMessage[HardwareErrorCode.BlePermissionError];
+
+      if (errorMessage.includes(poweredOffMessage) || errorMessage.includes('poweredOff')) {
+        throw ERRORS.TypedError(HardwareErrorCode.BlePoweredOff);
+      }
+      if (errorMessage.includes(unsupportedMessage) || errorMessage.includes('unsupported')) {
+        throw ERRORS.TypedError(HardwareErrorCode.BleUnsupported);
+      }
+      if (errorMessage.includes(permissionMessage) || errorMessage.includes('unauthorized')) {
+        throw ERRORS.TypedError(HardwareErrorCode.BlePermissionError);
+      }
+    }
+
+    throw error;
+  }
+
+  // Clean up all device state and listeners - unified cleanup function
+  private cleanupDeviceState(deviceId: string): void {
+    this.connectedDevices.delete(deviceId);
+    this.dataBuffers.delete(deviceId);
+
+    // Clean up notification listener
+    const notifyCleanup = this.notificationCleanups.get(deviceId);
+    if (notifyCleanup) {
+      notifyCleanup();
+      this.notificationCleanups.delete(deviceId);
+    }
+
+    // Clean up disconnect listener
+    const disconnectCleanup = this.disconnectCleanups.get(deviceId);
+    if (disconnectCleanup) {
+      disconnectCleanup();
+      this.disconnectCleanups.delete(deviceId);
+    }
+  }
+
+  init(logger: any, emitter?: EventEmitter) {
+    this.Log = logger;
+    this.emitter = emitter;
+
+    // Check if Noble BLE API is available
+    if (!window.desktopApi?.nobleBle) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.RuntimeError,
+        'Noble BLE API is not available. Please ensure you are running in Electron with Noble support.'
+      );
+    }
+
+    this.Log?.debug('[Transport] Noble BLE Transport initialized');
+  }
+
+  configure(signedData: any) {
+    const messages = parseConfigure(signedData);
+    this.configured = true;
+    this._messages = messages;
+  }
+
+  listen() {}
+
+  async enumerate(): Promise<{ id: string; name: string }[]> {
+    try {
+      if (!window.desktopApi?.nobleBle) {
+        throw new Error('Noble BLE API not available');
+      }
+
+      const devices = await window.desktopApi.nobleBle.enumerate();
+      return devices;
+    } catch (error) {
+      this.Log?.error('[Transport] Noble BLE enumerate failed:', error);
+      this.handleBluetoothError(error);
+    }
+  }
+
+  async acquire(input: BleAcquireInput) {
+    const { uuid, forceCleanRunPromise } = input;
+
+    if (!uuid) {
+      throw ERRORS.TypedError(HardwareErrorCode.BleRequiredUUID);
+    }
+
+    // Force clean running Promise
+    if (forceCleanRunPromise && this.runPromise) {
+      this.runPromise.reject(ERRORS.TypedError(HardwareErrorCode.BleForceCleanRunPromise));
+    }
+
+    try {
+      if (!window.desktopApi?.nobleBle) {
+        throw new Error('Noble BLE API not available');
+      }
+
+      // Check if device is available
+      const device = await window.desktopApi.nobleBle.getDevice(uuid);
+      if (!device) {
+        throw ERRORS.TypedError(HardwareErrorCode.DeviceNotFound, `Device ${uuid} not found`);
+      }
+
+      // Connect to device
+      try {
+        await window.desktopApi.nobleBle.connect(uuid);
+        this.connectedDevices.add(uuid);
+      } catch (error) {
+        this.handleBluetoothError(error);
+      }
+
+      // Initialize data buffer for this device
+      this.dataBuffers.set(uuid, { buffer: [], bufferLength: 0 });
+
+      // Subscribe to notifications
+      await window.desktopApi.nobleBle.subscribe(uuid);
+
+      // Set up notification listener
+      const cleanup = window.desktopApi.nobleBle.onNotification(
+        (deviceId: string, data: string) => {
+          if (deviceId === uuid) {
+            this.handleNotificationData(uuid, data);
+          }
+        }
+      );
+      this.notificationCleanups.set(uuid, cleanup);
+
+      // Set up disconnect listener
+      const disconnectCleanup = window.desktopApi.nobleBle.onDeviceDisconnected(
+        (disconnectedDevice: any) => {
+          if (disconnectedDevice.id === uuid) {
+            this.cleanupDeviceState(uuid);
+
+            // Trigger disconnect event
+            this.emitter?.emit('device-disconnect', {
+              name: disconnectedDevice.name,
+              id: disconnectedDevice.id,
+              connectId: disconnectedDevice.id,
+            });
+          }
+        }
+      );
+      this.disconnectCleanups.set(uuid, disconnectCleanup);
+
+      // Trigger connect event
+      this.emitter?.emit('device-connect', {
+        name: device.name,
+        id: device.id,
+        connectId: device.id,
+      });
+
+      return { uuid, path: uuid };
+    } catch (error) {
+      this.Log?.error('[Transport] Noble BLE acquire failed:', error);
+      throw error;
+    }
+  }
+
+  async release(id: string) {
+    try {
+      if (this.connectedDevices.has(id)) {
+        // Unsubscribe from notifications
+        if (window.desktopApi?.nobleBle) {
+          await window.desktopApi.nobleBle.unsubscribe(id);
+        }
+
+        // Disconnect device
+        if (window.desktopApi?.nobleBle) {
+          await window.desktopApi.nobleBle.disconnect(id);
+        }
+
+        // Clean up all device state
+        this.cleanupDeviceState(id);
+      }
+    } catch (error) {
+      this.Log?.error('[Transport] Noble BLE release failed:', error);
+      // Clean up local state even if release fails
+      this.cleanupDeviceState(id);
+    }
+  }
+
+  // Handle notification data from Noble BLE
+  private handleNotificationData(deviceId: string, hexData: string): void {
+    // Check for pairing rejection
+    if (hexData === 'PAIRING_REJECTED') {
+      this.Log?.debug('[Transport] Pairing rejection detected for device:', deviceId);
+      if (this.runPromise) {
+        this.runPromise.reject(ERRORS.TypedError(HardwareErrorCode.BleDeviceBondedCanceled));
+      }
+      return;
+    }
+
+    const result = this.processNotificationPacket(deviceId, hexData);
+
+    if (result.error) {
+      this.Log?.error('[Transport] Packet processing error:', result.error);
+      if (this.runPromise) {
+        this.runPromise.reject(ERRORS.TypedError(HardwareErrorCode.BleWriteCharacteristicError));
+      }
+      return;
+    }
+
+    if (result.isComplete && result.completePacket) {
+      if (this.runPromise) {
+        this.runPromise.resolve(result.completePacket);
+      }
+    }
+  }
+
+  async call(uuid: string, name: string, data: Record<string, unknown>) {
+    if (this._messages == null) {
+      throw ERRORS.TypedError(HardwareErrorCode.TransportNotConfigured);
+    }
+
+    const forceRun = name === 'Initialize' || name === 'Cancel';
+
+    if (this.runPromise && !forceRun) {
+      throw ERRORS.TypedError(HardwareErrorCode.TransportCallInProgress);
+    }
+
+    if (!this.connectedDevices.has(uuid)) {
+      throw ERRORS.TypedError(HardwareErrorCode.TransportNotFound, `Device ${uuid} not connected`);
+    }
+
+    this.runPromise = createDeferred();
+    const messages = this._messages;
+
+    // Log different types of commands appropriately
+    if (name === 'ResourceUpdate' || name === 'ResourceAck') {
+      this.Log?.debug('[Transport] Noble BLE call', 'name:', name, 'data:', {
+        file_name: data?.file_name,
+        hash: data?.hash,
+      });
+    } else if (LogBlockCommand.has(name)) {
+      this.Log?.debug('[Transport] Noble BLE call', 'name:', name);
+    } else {
+      this.Log?.debug('[Transport] Noble BLE call', 'name:', name, 'data:', data);
+    }
+
+    const buffers = buildBuffers(messages, name, data);
+
+    try {
+      if (!window.desktopApi?.nobleBle) {
+        throw new Error('Noble BLE write API not available');
+      }
+
+      // Write each buffer to the device
+      for (let i = 0; i < buffers.length; i++) {
+        const buffer = buffers[i];
+
+        if (!buffer || typeof buffer.toString !== 'function') {
+          this.Log?.error(`[Transport] Noble BLE buffer ${i + 1} is invalid:`, buffer);
+          throw new Error(`Buffer ${i + 1} is invalid`);
+        }
+
+        // Use ByteBuffer's toString('hex') method directly, similar to other transports
+        const hexString = buffer.toString('hex');
+
+        if (hexString.length === 0) {
+          this.Log?.error(`[Transport] Noble BLE buffer ${i + 1} generated empty hex string`);
+          throw new Error(`Buffer ${i + 1} is empty`);
+        }
+
+        await window.desktopApi.nobleBle.write(uuid, hexString);
+      }
+
+      // Wait for response
+      const response = await this.runPromise.promise;
+
+      if (typeof response !== 'string') {
+        throw new Error('Returning data is not string.');
+      }
+
+      const jsonData = receiveOne(messages, response);
+      return check.call(jsonData);
+    } catch (e) {
+      this.Log?.error('[Transport] Noble BLE call error:', e);
+      throw e;
+    } finally {
+      this.runPromise = null;
+    }
+  }
+
+  // Process hex data from notification with validation and packet reassembly
+  private processNotificationPacket(deviceId: string, hexData: string): PacketProcessResult {
+    try {
+      // Validate input
+      if (typeof hexData !== 'string') {
+        return { isComplete: false, error: 'Invalid hexData type' };
+      }
+
+      // Clean and validate hex format
+      const cleanHexData = hexData.replace(/\s+/g, '');
+      if (!/^[0-9A-Fa-f]*$/.test(cleanHexData)) {
+        return { isComplete: false, error: 'Invalid hex data format' };
+      }
+
+      // Convert hex string to Uint8Array
+      const hexMatch = cleanHexData.match(/.{1,2}/g);
+      if (!hexMatch) {
+        return { isComplete: false, error: 'Failed to parse hex data' };
+      }
+
+      const data = new Uint8Array(hexMatch.map(byte => parseInt(byte, 16)));
+
+      // Get buffer state
+      const bufferState = this.dataBuffers.get(deviceId);
+      if (!bufferState) {
+        return { isComplete: false, error: 'No buffer state for device' };
+      }
+
+      // Process header or data chunk
+      if (isHeaderChunk(data)) {
+        const dataView = new DataView(data.buffer);
+        bufferState.bufferLength = dataView.getInt32(5, false);
+        bufferState.buffer = [...data.subarray(3)];
+      } else {
+        bufferState.buffer = bufferState.buffer.concat([...data]);
+      }
+
+      // Check if packet is complete
+      if (bufferState.buffer.length - COMMON_HEADER_SIZE >= bufferState.bufferLength) {
+        const completeBuffer = new Uint8Array(bufferState.buffer);
+
+        // Reset buffer state
+        bufferState.bufferLength = 0;
+        bufferState.buffer = [];
+
+        // Convert to hex string
+        const hexString = Array.from(completeBuffer)
+          .map(b => b.toString(16).padStart(2, '0'))
+          .join('');
+
+        return { isComplete: true, completePacket: hexString };
+      }
+
+      return { isComplete: false };
+    } catch (error) {
+      return { isComplete: false, error: `Packet processing error: ${error}` };
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+import WebUsbTransport from './webusb';
+import ElectronBleTransport from './electron-ble-transport';
+
+export { WebUsbTransport, ElectronBleTransport };

package/src/webusb.ts

@@ -0,0 +1,298 @@
+/* eslint-disable no-undef */
+import transport, { AcquireInput, LogBlockCommand } from '@ukeyfe/hardware-transport';
+import { ERRORS, HardwareErrorCode, UKEY_WEBUSB_FILTER, wait } from '@ukeyfe/hardware-shared';
+import ByteBuffer from 'bytebuffer';
+
+const { parseConfigure, buildEncodeBuffers, decodeProtocol, receiveOne, check } = transport;
+
+const CONFIGURATION_ID = 1;
+const INTERFACE_ID = 0;
+const ENDPOINT_ID = 1;
+const PACKET_SIZE = 64;
+const HEADER_LENGTH = 6;
+
+/**
+ * Device information with path and WebUSB device instance
+ */
+interface DeviceInfo {
+  path: string;
+  device: USBDevice;
+}
+
+export default class WebUsbTransport {
+  messages: ReturnType<typeof transport.parseConfigure> | undefined;
+
+  name = 'WebUsbTransport';
+
+  stopped = false;
+
+  configured = false;
+
+  Log?: any;
+
+  usb?: USB;
+
+  /**
+   * Cached list of connected devices
+   * This is essential for maintaining device references between operations
+   */
+  deviceList: Array<DeviceInfo> = [];
+
+  configurationId = CONFIGURATION_ID;
+
+  endpointId = ENDPOINT_ID;
+
+  interfaceId = INTERFACE_ID;
+
+  /**
+   * Initialize WebUSB transport
+   */
+  init(logger: any) {
+    this.Log = logger;
+
+    const { usb } = navigator;
+    if (!usb) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.RuntimeError,
+        'WebUSB is not supported by current browsers'
+      );
+    }
+    this.usb = usb;
+  }
+
+  /**
+   * Configure transport protocol
+   */
+  configure(signedData: any) {
+    const messages = parseConfigure(signedData);
+    this.configured = true;
+    this.messages = messages;
+  }
+
+  /**
+   * Request user to select a device
+   * This method must be called in response to a user action
+   * to comply with WebUSB security requirements
+   */
+  async promptDeviceAccess() {
+    if (!this.usb) return null;
+    try {
+      const device = await this.usb.requestDevice({ filters: UKEY_WEBUSB_FILTER });
+      return device;
+    } catch (e) {
+      this.Log.debug('requestDevice error: ', e);
+      return null;
+    }
+  }
+
+  /**
+   * Enumerate already connected devices
+   * This method only returns devices that are already authorized by the browser
+   * It does NOT prompt the user to select a device
+   */
+  async enumerate() {
+    await this.getConnectedDevices();
+    return this.deviceList;
+  }
+
+  /**
+   * Get list of connected devices
+   */
+  async getConnectedDevices() {
+    if (!this.usb) return [];
+
+    const devices = await this.usb.getDevices();
+    const ukeyDevices = devices.filter(dev => {
+      const isUKey = UKEY_WEBUSB_FILTER.some(
+        desc => dev.vendorId === desc.vendorId && dev.productId === desc.productId
+      );
+      const hasSerialNumber = typeof dev.serialNumber === 'string' && dev.serialNumber.length > 0;
+      return isUKey && hasSerialNumber;
+    });
+
+    this.deviceList = ukeyDevices.map(device => ({
+      path: device.serialNumber as string,
+      device,
+    }));
+
+    return this.deviceList;
+  }
+
+  /**
+   * Acquire device control
+   */
+  async acquire(input: AcquireInput) {
+    if (!input.path) return;
+    try {
+      await this.connect(input.path ?? '', true);
+      return await Promise.resolve(input.path);
+    } catch (e) {
+      this.Log.debug('acquire error: ', e);
+      throw e;
+    }
+  }
+
+  /**
+   * Find device by path
+   */
+  async findDevice(path: string) {
+    // If device list is empty, refresh it first
+    if (this.deviceList.length === 0) {
+      await this.getConnectedDevices();
+    }
+
+    let device = this.deviceList.find(d => d.path === path);
+
+    // If device not found after first attempt, try refreshing the list once more
+    if (device == null) {
+      await this.getConnectedDevices();
+      device = this.deviceList.find(d => d.path === path);
+
+      if (device == null) {
+        throw new Error('Action was interrupted.');
+      }
+    }
+
+    return device.device;
+  }
+
+  /**
+   * Connect to device with retry mechanism
+   */
+  async connect(path: string, first: boolean) {
+    const maxRetries = 5;
+    for (let i = 0; i < maxRetries; i++) {
+      try {
+        return await this.connectToDevice(path, first);
+      } catch (e) {
+        if (i === maxRetries - 1) {
+          throw e;
+        }
+        await wait(i * 200);
+      }
+    }
+  }
+
+  /**
+   * Connect to specific device
+   */
+  async connectToDevice(path: string, first: boolean) {
+    const device: USBDevice = await this.findDevice(path);
+    await device.open();
+
+    if (first) {
+      await device.selectConfiguration(this.configurationId);
+      try {
+        await device.reset();
+      } catch (error) {
+        // Ignore reset errors
+      }
+    }
+
+    await device.claimInterface(this.interfaceId);
+  }
+
+  async post(session: string, name: string, data: Record<string, unknown>) {
+    await this.call(session, name, data);
+  }
+
+  /**
+   * Call device method
+   */
+  async call(path: string, name: string, data: Record<string, unknown>) {
+    if (this.messages == null) {
+      throw ERRORS.TypedError(HardwareErrorCode.TransportNotConfigured);
+    }
+
+    const device = await this.findDevice(path);
+    if (!device) {
+      throw ERRORS.TypedError(HardwareErrorCode.DeviceNotFound);
+    }
+
+    const { messages } = this;
+    if (LogBlockCommand.has(name)) {
+      this.Log.debug('call-', ' name: ', name);
+    } else {
+      this.Log.debug('call-', ' name: ', name, ' data: ', data);
+    }
+    const encodeBuffers = buildEncodeBuffers(messages, name, data);
+
+    for (const buffer of encodeBuffers) {
+      const newArray: Uint8Array = new Uint8Array(PACKET_SIZE);
+      newArray[0] = 63;
+      newArray.set(new Uint8Array(buffer), 1);
+      // console.log('send packet: ', newArray);
+
+      if (!device.opened) {
+        await this.connect(path, false);
+      }
+      await device.transferOut(this.endpointId, newArray);
+    }
+
+    const resData = await this.receiveData(path);
+    if (typeof resData !== 'string') {
+      throw ERRORS.TypedError(HardwareErrorCode.NetworkError, 'Returning data is not string.');
+    }
+    const jsonData = receiveOne(messages, resData);
+    return check.call(jsonData);
+  }
+
+  /**
+   * Receive data from device
+   */
+  async receiveData(path: string) {
+    const device: USBDevice = await this.findDevice(path);
+    if (!device.opened) {
+      await this.connect(path, false);
+    }
+
+    const firstPacket = await device.transferIn(this.endpointId, PACKET_SIZE);
+    const firstData = firstPacket.data?.buffer.slice(1);
+    console.log('receive first packet: ', firstPacket);
+    const { length, typeId, restBuffer } = decodeProtocol.decodeChunked(firstData as ArrayBuffer);
+
+    console.log('chunk length: ', length);
+
+    // eslint-disable-next-line @typescript-eslint/restrict-plus-operands
+    const lengthWithHeader = Number(length + HEADER_LENGTH);
+    const decoded = new ByteBuffer(lengthWithHeader);
+    decoded.writeUint16(typeId);
+    decoded.writeUint32(length);
+    if (length) {
+      decoded.append(restBuffer);
+    }
+    console.log('first decoded: ', decoded);
+
+    while (decoded.offset < lengthWithHeader) {
+      const res = await device.transferIn(this.endpointId, PACKET_SIZE);
+
+      if (!res.data) {
+        throw new Error('no data');
+      }
+      if (res.data.byteLength === 0) {
+        // empty data
+        console.warn('empty data');
+      }
+      const buffer = res.data.buffer.slice(1);
+      if (lengthWithHeader - decoded.offset >= PACKET_SIZE) {
+        decoded.append(buffer as unknown as ArrayBuffer);
+      } else {
+        decoded.append(
+          buffer.slice(0, lengthWithHeader - decoded.offset) as unknown as ArrayBuffer
+        );
+      }
+    }
+    decoded.reset();
+    const result = decoded.toBuffer();
+    return Buffer.from(result as unknown as ArrayBuffer).toString('hex');
+  }
+
+  /**
+   * Release device
+   */
+  async release(path: string) {
+    const device: USBDevice = await this.findDevice(path);
+    await device.releaseInterface(this.interfaceId);
+    await device.close();
+  }
+}