@onekeyfe/hardware-cli 1.2.0-alpha.2 → 1.2.0-alpha.21

package/src/deviceSelection.ts

@@ -0,0 +1,13 @@
+export function selectSearchDevice<T extends { connectId?: string }>(
+  devices: T[],
+  preferredConnectId?: string
+): T | undefined {
+  if (preferredConnectId) {
+    return (
+      devices.find(device => device.connectId === preferredConnectId) ??
+      ({ connectId: preferredConnectId } as T)
+    );
+  }
+
+  return devices[0];
+}

package/src/deviceStateCommands.ts

@@ -0,0 +1,71 @@
+import type { CoreApi, DeviceStateScope, KnownDevice, SearchDevice } from '@onekeyfe/hd-core';
+
+type DeviceStateSdk = Pick<CoreApi, 'searchDevices' | 'getDeviceState' | 'getFeatures'>;
+
+type DiscoveredDevice = SearchDevice & Partial<Pick<KnownDevice, 'features' | 'state'>>;
+
+const createDeviceNotFoundResult = (connectId?: string) => ({
+  success: false as const,
+  payload: {
+    code: 'DEVICE_NOT_FOUND',
+    error: connectId ? `Device not found: ${connectId}` : 'No device found',
+  },
+});
+
+const resolveSearchDevice = async (sdk: DeviceStateSdk, connectId?: string) => {
+  const searchResult = await sdk.searchDevices();
+  if (!searchResult.success) return searchResult;
+
+  const devices = searchResult.payload as DiscoveredDevice[];
+  const device = connectId ? devices.find(item => item.connectId === connectId) : devices[0];
+
+  if (!device?.connectId) return createDeviceNotFoundResult(connectId);
+  return { success: true as const, payload: device };
+};
+
+/**
+ * Unified state entry for the new CLI. Resolve the user-facing connectId through
+ * discovery so V1 serial IDs map to the process-local USB path.
+ */
+export const getCanonicalDeviceState = async (
+  sdk: DeviceStateSdk,
+  connectId: string | undefined,
+  scope: DeviceStateScope
+) => {
+  const deviceResult = await resolveSearchDevice(sdk, connectId);
+  if (!deviceResult.success) return deviceResult;
+
+  if (scope === 'runtime' && deviceResult.payload.state) {
+    return { success: true as const, payload: deviceResult.payload.state };
+  }
+
+  const resolvedConnectId = deviceResult.payload.connectId ?? undefined;
+  if (!resolvedConnectId) return createDeviceNotFoundResult();
+  return sdk.getDeviceState(resolvedConnectId, { scope });
+};
+
+/**
+ * Legacy CLI only: retain getFeatures for V1 and reuse the discovery projection for V2.
+ * Public SDK.getFeatures remains V1-only.
+ */
+export const getCompatibleFeatures = async (sdk: DeviceStateSdk, connectId?: string) => {
+  const deviceResult = await resolveSearchDevice(sdk, connectId);
+  if (!deviceResult.success) return deviceResult;
+
+  const device = deviceResult.payload;
+  const protocol = device.state?.protocol ?? device.features?.protocol;
+  if (protocol === 'V2') {
+    if (!device.features) {
+      return {
+        success: false as const,
+        payload: {
+          code: 'DEVICE_FEATURES_UNAVAILABLE',
+          error: 'Protocol V2 compatibility features are unavailable',
+        },
+      };
+    }
+    return { success: true as const, payload: device.features };
+  }
+
+  return sdk.getFeatures(device.connectId ?? '');
+};

package/src/sdk.ts

@@ -14,14 +14,17 @@ import HardwareSDK from '@onekeyfe/hd-common-connect-sdk';
 import { DEVICE, UI_EVENT, UI_REQUEST, UI_RESPONSE } from '@onekeyfe/hd-core';
 
 import { promptPassphraseViaPinentry } from './pinentry';
+import { createNobleBlePlugin } from './transports/nobleBlePlugin';
 
-import type { ConnectSettings } from '@onekeyfe/hd-core';
+import type { ConnectSettings, KnownDevice } from '@onekeyfe/hd-core';
 import type { PinentryResult } from './pinentry';
 
 export interface SDKOptions {
   connectId?: string;
   passphraseState?: string;
   useEmptyPassphrase?: boolean;
+  debug?: boolean;
+  transport?: 'usb' | 'ble';
 }
 
 /**
@@ -166,12 +169,12 @@ function registerEventHandlers(sdk: typeof HardwareSDK): void {
     }
   });
 
-  sdk.on(DEVICE.CONNECT, (device: any) => {
+  sdk.on(DEVICE.CONNECT, ({ device }: { device: KnownDevice }) => {
     const name = device?.label || device?.name;
     if (name) process.stderr.write(`[onekey-hw] Device connected: ${name}\n`);
   });
 
-  sdk.on(DEVICE.DISCONNECT, (device: any) => {
+  sdk.on(DEVICE.DISCONNECT, ({ device }: { device: KnownDevice }) => {
     const name = device?.label || device?.name;
     if (name) process.stderr.write(`[onekey-hw] Device disconnected: ${name}\n`);
   });
@@ -182,12 +185,17 @@ function registerEventHandlers(sdk: typeof HardwareSDK): void {
 // ---------------------------------------------------------------------------
 
 async function initSDK(): Promise<typeof HardwareSDK> {
+  const transport = currentOpts.transport ?? 'usb';
   const settings: Partial<ConnectSettings> = {
-    debug: false,
+    debug: currentOpts.debug ?? false,
     fetchConfig: true,
-    env: 'node-usb',
+    env: transport === 'ble' ? 'lowlevel' : 'node-usb',
   };
-  await HardwareSDK.init(settings);
+  await HardwareSDK.init(
+    settings,
+    undefined,
+    transport === 'ble' ? createNobleBlePlugin() : undefined
+  );
 
   // Defensive: strip any stale listeners (e.g. left over from a previous
   // dispose/init cycle in a long-running process) before wiring ours.
@@ -223,7 +231,7 @@ export async function disposeSDK(): Promise<void> {
   if (!sdkReadyPromise) return;
   try {
     const sdk = await sdkReadyPromise;
-    sdk.dispose();
+    await Promise.resolve(sdk.dispose());
   } catch {
     // ignore errors during cleanup
   } finally {

package/src/transports/nobleBlePlugin.ts

@@ -0,0 +1,498 @@
+import {
+  ERRORS,
+  HardwareErrorCode,
+  ONEKEY_SERVICE_UUID,
+  isOnekeyDevice,
+} from '@onekeyfe/hd-shared';
+
+import type { LowLevelDevice, LowlevelTransportSharedPlugin } from '@onekeyfe/hd-transport';
+import type { Characteristic, Peripheral, Service } from '@stoprocent/noble';
+
+type NobleModule = {
+  state: string;
+  startScanning(
+    serviceUUIDs: string[],
+    allowDuplicates: boolean,
+    callback?: (error?: Error) => void
+  ): void;
+  stopScanning(callback?: () => void): void;
+  on(event: 'stateChange', listener: (state: string) => void): void;
+  on(event: 'discover', listener: (peripheral: Peripheral) => void): void;
+  removeListener(event: 'stateChange', listener: (state: string) => void): void;
+  removeListener(event: 'discover', listener: (peripheral: Peripheral) => void): void;
+};
+
+type CharacteristicPair = {
+  write: Characteristic;
+  notify: Characteristic;
+};
+
+type NoblePendingReceiver = {
+  resolve: (data: string) => void;
+  reject: (error: Error) => void;
+};
+
+type NobleNotificationState = {
+  generation: number;
+  queue: string[];
+  pendingReceivers: Set<NoblePendingReceiver>;
+};
+
+const ONEKEY_SERVICE_UUIDS = [ONEKEY_SERVICE_UUID];
+const PRO2_ADVERTISEMENT_SERVICE_UUID_KEYS = new Set(['fffd']);
+const NORMALIZED_WRITE_UUID = '0002';
+const NORMALIZED_NOTIFY_UUID = '0003';
+const NORMALIZED_ONEKEY_SERVICE_UUIDS = new Set([
+  ...ONEKEY_SERVICE_UUIDS.map(uuid => getBleUuidKey(uuid)),
+  '0001',
+]);
+
+const BLUETOOTH_INIT_TIMEOUT = 10_000;
+const DEVICE_SCAN_TIMEOUT = 8_000;
+const CONNECTION_TIMEOUT = 8_000;
+const SERVICE_DISCOVERY_TIMEOUT = 10_000;
+const BLE_CLEANUP_TIMEOUT = 100;
+const BLE_PACKET_SIZE = 192;
+const BLE_ENCRYPTION_ERROR_PATTERNS = [/encryption is insufficient/i, /insufficient encryption/i];
+
+let noble: NobleModule | null = null;
+let nobleReadyPromise: Promise<void> | null = null;
+const discoveredDevices = new Map<string, Peripheral>();
+const connectedDevices = new Map<string, Peripheral>();
+const deviceCharacteristics = new Map<string, CharacteristicPair>();
+const notificationStates = new Map<string, NobleNotificationState>();
+const notificationGenerations = new Map<string, number>();
+
+function getBleUuidKey(uuid?: string | null) {
+  const normalized = (uuid ?? '').replace(/-/g, '').toLowerCase();
+  return normalized.length >= 8 ? normalized.substring(4, 8) : normalized;
+}
+
+function isGenericBleService(uuid?: string | null) {
+  return ['1800', '1801', '180a', '180f'].includes(getBleUuidKey(uuid));
+}
+
+function hasOneKeyAdvertisementService(peripheral: Peripheral) {
+  const serviceUuids = peripheral.advertisement?.serviceUuids ?? [];
+  return serviceUuids.some(uuid => {
+    const uuidKey = getBleUuidKey(uuid);
+    return (
+      NORMALIZED_ONEKEY_SERVICE_UUIDS.has(uuidKey) ||
+      PRO2_ADVERTISEMENT_SERVICE_UUID_KEYS.has(uuidKey)
+    );
+  });
+}
+
+function isOneKeyPeripheral(peripheral: Peripheral) {
+  const deviceName = peripheral.advertisement?.localName || null;
+  return isOnekeyDevice(deviceName, peripheral.id) || hasOneKeyAdvertisementService(peripheral);
+}
+
+function enqueueNotification(deviceId: string, generation: number, data: Buffer) {
+  const state = notificationStates.get(deviceId);
+  if (!state || state.generation !== generation) return;
+
+  const hex = data.toString('hex');
+  const [receiver] = state.pendingReceivers;
+  if (receiver) {
+    state.pendingReceivers.delete(receiver);
+    receiver.resolve(hex);
+    return;
+  }
+  state.queue.push(hex);
+}
+
+function createNotificationState(deviceId: string) {
+  const existing = notificationStates.get(deviceId);
+  if (existing) {
+    const error = new Error(`BLE notification state replaced for ${deviceId}`);
+    existing.pendingReceivers.forEach(receiver => receiver.reject(error));
+  }
+
+  const generation = (notificationGenerations.get(deviceId) ?? 0) + 1;
+  notificationGenerations.set(deviceId, generation);
+  const state: NobleNotificationState = {
+    generation,
+    queue: [],
+    pendingReceivers: new Set(),
+  };
+  notificationStates.set(deviceId, state);
+  return state;
+}
+
+function clearNotificationState(deviceId: string, reason: string) {
+  const state = notificationStates.get(deviceId);
+  if (!state) return;
+
+  notificationStates.delete(deviceId);
+  const error = new Error(reason);
+  state.pendingReceivers.forEach(receiver => receiver.reject(error));
+  state.pendingReceivers.clear();
+  state.queue.length = 0;
+}
+
+function waitForNobleCleanup(registerCallback: (callback: () => void) => void) {
+  return new Promise<void>(resolve => {
+    let completed = false;
+    const complete = () => {
+      if (completed) return;
+      completed = true;
+      clearTimeout(timeout);
+      resolve();
+    };
+    const timeout = setTimeout(complete, BLE_CLEANUP_TIMEOUT);
+    try {
+      registerCallback(complete);
+    } catch {
+      complete();
+    }
+  });
+}
+
+async function initializeNoble() {
+  if (!noble) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
+      noble = require('@stoprocent/noble') as NobleModule;
+    } catch (error) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.BleUnsupported,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+
+  if (noble.state === 'poweredOn') return;
+
+  if (nobleReadyPromise) {
+    await nobleReadyPromise;
+    return;
+  }
+
+  nobleReadyPromise = new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      noble?.removeListener('stateChange', onStateChange);
+      reject(ERRORS.TypedError(HardwareErrorCode.BlePoweredOff, 'Bluetooth is not powered on'));
+    }, BLUETOOTH_INIT_TIMEOUT);
+
+    const onStateChange = (state: string) => {
+      if (state === 'poweredOn') {
+        clearTimeout(timeout);
+        noble?.removeListener('stateChange', onStateChange);
+        resolve();
+      } else if (state === 'unsupported') {
+        clearTimeout(timeout);
+        noble?.removeListener('stateChange', onStateChange);
+        reject(ERRORS.TypedError(HardwareErrorCode.BleUnsupported));
+      }
+    };
+
+    noble?.on('stateChange', onStateChange);
+  }).finally(() => {
+    nobleReadyPromise = null;
+  });
+
+  await nobleReadyPromise;
+}
+
+function stopScanning() {
+  try {
+    noble?.stopScanning();
+  } catch {
+    // ignore best-effort scan cleanup
+  }
+}
+
+async function scanDevices(targetDeviceId?: string) {
+  await initializeNoble();
+  if (!noble) {
+    throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Noble not initialized');
+  }
+
+  if (!targetDeviceId) {
+    discoveredDevices.clear();
+  }
+
+  const nobleInstance = noble;
+  return new Promise<Peripheral[]>((resolve, reject) => {
+    const found = new Map<string, Peripheral>();
+
+    const cleanup = () => {
+      clearTimeout(timeout);
+      nobleInstance.removeListener('discover', onDiscover);
+      stopScanning();
+    };
+
+    const finish = () => {
+      cleanup();
+      resolve([...found.values()]);
+    };
+
+    const onDiscover = (peripheral: Peripheral) => {
+      if (targetDeviceId && peripheral.id !== targetDeviceId) return;
+      if (!targetDeviceId && !isOneKeyPeripheral(peripheral)) return;
+
+      discoveredDevices.set(peripheral.id, peripheral);
+      found.set(peripheral.id, peripheral);
+      if (targetDeviceId) {
+        finish();
+      }
+    };
+
+    const timeout = setTimeout(finish, DEVICE_SCAN_TIMEOUT);
+    nobleInstance.on('discover', onDiscover);
+    nobleInstance.startScanning([], false, (error?: Error) => {
+      if (error) {
+        cleanup();
+        reject(ERRORS.TypedError(HardwareErrorCode.BleScanError, error.message));
+      }
+    });
+  });
+}
+
+function connectPeripheral(peripheral: Peripheral) {
+  if (peripheral.state === 'connected') return Promise.resolve();
+
+  return new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(ERRORS.TypedError(HardwareErrorCode.BleConnectedError, 'Connection timeout'));
+    }, CONNECTION_TIMEOUT);
+
+    peripheral.connect((error?: Error) => {
+      clearTimeout(timeout);
+      if (error) {
+        reject(ERRORS.TypedError(HardwareErrorCode.BleConnectedError, error.message));
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+async function discoverCharacteristics(peripheral: Peripheral): Promise<CharacteristicPair> {
+  const services = await new Promise<Service[]>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(ERRORS.TypedError(HardwareErrorCode.BleServiceNotFound, 'Service discovery timeout'));
+    }, SERVICE_DISCOVERY_TIMEOUT);
+
+    peripheral.discoverServices([], (error, discoveredServices) => {
+      clearTimeout(timeout);
+      if (error) {
+        reject(ERRORS.TypedError(HardwareErrorCode.BleServiceNotFound, error.message));
+        return;
+      }
+      resolve(discoveredServices);
+    });
+  });
+
+  let service = services.find(s => NORMALIZED_ONEKEY_SERVICE_UUIDS.has(getBleUuidKey(s.uuid)));
+  if (!service) {
+    service =
+      services.find(s => PRO2_ADVERTISEMENT_SERVICE_UUID_KEYS.has(getBleUuidKey(s.uuid))) ||
+      services.find(s => !isGenericBleService(s.uuid)) ||
+      services[0];
+  }
+  if (!service) {
+    throw ERRORS.TypedError(HardwareErrorCode.BleServiceNotFound, 'No BLE service found');
+  }
+  const selectedService = service;
+
+  const characteristics = await new Promise<Characteristic[]>((resolve, reject) => {
+    selectedService.discoverCharacteristics([], (error, discoveredCharacteristics) => {
+      if (error) {
+        reject(ERRORS.TypedError(HardwareErrorCode.BleCharacteristicNotFound, error.message));
+        return;
+      }
+      resolve(discoveredCharacteristics);
+    });
+  });
+
+  let writeCharacteristic: Characteristic | undefined;
+  let notifyCharacteristic: Characteristic | undefined;
+  for (const characteristic of characteristics) {
+    const uuidKey = getBleUuidKey(characteristic.uuid);
+    if (uuidKey === NORMALIZED_WRITE_UUID) {
+      writeCharacteristic = characteristic;
+    } else if (uuidKey === NORMALIZED_NOTIFY_UUID) {
+      notifyCharacteristic = characteristic;
+    }
+  }
+
+  if (!writeCharacteristic || !notifyCharacteristic) {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.BleCharacteristicNotFound,
+      'Required OneKey BLE characteristics not found'
+    );
+  }
+
+  return {
+    write: writeCharacteristic,
+    notify: notifyCharacteristic,
+  };
+}
+
+function subscribeNotifications(
+  deviceId: string,
+  generation: number,
+  notifyCharacteristic: Characteristic
+) {
+  return waitForNobleCleanup(callback => notifyCharacteristic.unsubscribe(callback))
+    .then(
+      () =>
+        new Promise<void>((resolve, reject) => {
+          notifyCharacteristic.subscribe((error?: Error) => {
+            if (error) {
+              const errorMessage = error.message || String(error);
+              if (BLE_ENCRYPTION_ERROR_PATTERNS.some(pattern => pattern.test(errorMessage))) {
+                reject(
+                  ERRORS.TypedError(
+                    HardwareErrorCode.BleDeviceNotBonded,
+                    `BLE device ${deviceId} is not paired or the encrypted link is not ready: ${errorMessage}`
+                  )
+                );
+                return;
+              }
+              reject(
+                ERRORS.TypedError(
+                  HardwareErrorCode.BleCharacteristicNotifyChangeFailure,
+                  `Failed to subscribe notifications for ${deviceId}: ${errorMessage}`
+                )
+              );
+              return;
+            }
+            resolve();
+          });
+        })
+    )
+    .then(() => {
+      notifyCharacteristic.removeAllListeners('data');
+      notifyCharacteristic.on('data', data => enqueueNotification(deviceId, generation, data));
+    })
+    .catch(error => {
+      notifyCharacteristic.removeAllListeners('data');
+      if (error) {
+        throw error;
+      }
+      throw ERRORS.TypedError(HardwareErrorCode.BleCharacteristicNotifyChangeFailure);
+    });
+}
+
+function writeCharacteristic(
+  characteristic: Characteristic,
+  buffer: Buffer,
+  withoutResponse: boolean
+) {
+  return new Promise<void>((resolve, reject) => {
+    characteristic.write(buffer, withoutResponse, (error?: Error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+async function disconnectDevice(uuid: string) {
+  const peripheral = connectedDevices.get(uuid);
+  const characteristics = deviceCharacteristics.get(uuid);
+  clearNotificationState(uuid, `BLE device disconnected: ${uuid}`);
+  if (characteristics) {
+    characteristics.notify.removeAllListeners('data');
+    await waitForNobleCleanup(callback => characteristics.notify.unsubscribe(callback));
+  }
+
+  connectedDevices.delete(uuid);
+  deviceCharacteristics.delete(uuid);
+
+  if (!peripheral || peripheral.state === 'disconnected') return;
+
+  await waitForNobleCleanup(callback => peripheral.disconnect(callback));
+}
+
+export function createNobleBlePlugin(): LowlevelTransportSharedPlugin {
+  return {
+    version: 'OneKey-CLI-Noble-1.0',
+
+    async init() {
+      await initializeNoble();
+    },
+
+    async enumerate(): Promise<LowLevelDevice[]> {
+      const devices = await scanDevices();
+      return devices.map(device => ({
+        commType: 'ble',
+        id: device.id,
+        name: device.advertisement?.localName || 'Unknown BLE Device',
+      }));
+    },
+
+    async connect(uuid: string) {
+      let peripheral = discoveredDevices.get(uuid);
+      if (!peripheral) {
+        [peripheral] = await scanDevices(uuid);
+      }
+      if (!peripheral) {
+        throw ERRORS.TypedError(HardwareErrorCode.DeviceNotFound, `BLE device not found: ${uuid}`);
+      }
+
+      await connectPeripheral(peripheral);
+      const characteristics = await discoverCharacteristics(peripheral);
+      const notificationState = createNotificationState(uuid);
+      try {
+        await subscribeNotifications(uuid, notificationState.generation, characteristics.notify);
+      } catch (error) {
+        clearNotificationState(uuid, `BLE notification subscription failed: ${uuid}`);
+        throw error;
+      }
+      connectedDevices.set(uuid, peripheral);
+      deviceCharacteristics.set(uuid, characteristics);
+    },
+
+    async disconnect(uuid: string) {
+      await disconnectDevice(uuid);
+    },
+
+    async send(uuid: string, data: string, options?: { withoutResponse?: boolean }) {
+      const characteristics = deviceCharacteristics.get(uuid);
+      if (!characteristics) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.BleCharacteristicNotFound,
+          `BLE device is not connected: ${uuid}`
+        );
+      }
+
+      const buffer = Buffer.from(data, 'hex');
+      const withoutResponse = options?.withoutResponse ?? true;
+      for (let offset = 0; offset < buffer.length; offset += BLE_PACKET_SIZE) {
+        const chunk = buffer.subarray(offset, Math.min(offset + BLE_PACKET_SIZE, buffer.length));
+        await writeCharacteristic(characteristics.write, chunk, withoutResponse);
+      }
+    },
+
+    async receive(uuid?: string) {
+      const resolvedUuid =
+        uuid ??
+        (notificationStates.size === 1 ? notificationStates.keys().next().value : undefined);
+      if (!resolvedUuid) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.RuntimeError,
+          'BLE receive requires a device UUID when multiple devices are connected'
+        );
+      }
+
+      const state = notificationStates.get(resolvedUuid);
+      if (!state) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.TransportNotFound,
+          `BLE notification state not found: ${resolvedUuid}`
+        );
+      }
+      const queued = state.queue.shift();
+      if (queued !== undefined) return queued;
+      return new Promise<string>((resolve, reject) => {
+        state.pendingReceivers.add({ resolve, reject });
+      });
+    },
+  };
+}