@onekeyfe/hardware-cli 1.2.0-alpha.4 → 1.2.0-alpha.40

package/src/deviceSelection.ts

@@ -0,0 +1,13 @@
+export function selectSearchDevice<T extends { connectId?: string | null }>(
+  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/pinentry.ts

@@ -73,6 +73,7 @@ export function findPinentry(): string | null {
 export interface PinentryResult {
   value: string;
   passphraseOnDevice: boolean;
+  attachPinOnDevice?: boolean;
 }
 
 // CLI-variant policy differs from app-monorepo: we fall back to on-device

package/src/sdk.ts

@@ -5,8 +5,8 @@
  * Passphrase flow aligns with app-monorepo CLI:
  *   - Standard wallet: --use-empty-passphrase, auto-respond
  *   - Hidden wallet: interactive 1/2/3 selection (standard / pinentry / on-device)
- *   - Session caching: passphraseState + sessionId stored in OS keychain,
- *     preloaded via preloadSessionCache on next invocation
+ *   - Legacy session caching: existing OS keychain entries may still be preloaded,
+ *     but public SDK responses never expose new device session ids
  */
 
 import * as readline from 'node:readline';
@@ -16,7 +16,7 @@ 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 {
@@ -59,9 +59,15 @@ let sdkReadyPromise: Promise<typeof HardwareSDK> | null = null;
  *   2. Hidden wallet — enter passphrase via pinentry (secure OS dialog)
  *   3. Hidden wallet — enter passphrase on device screen
  */
-function resolvePassphraseByChoice(choice: '1' | '2' | '3'): Promise<PinentryResult> {
+export function resolvePassphraseByChoice(choice: '1' | '2' | '3' | '4'): Promise<PinentryResult> {
   if (choice === '1') return Promise.resolve({ value: '', passphraseOnDevice: false });
   if (choice === '2') return promptPassphraseViaPinentry();
+  if (choice === '4')
+    return Promise.resolve({
+      value: '',
+      passphraseOnDevice: false,
+      attachPinOnDevice: true,
+    });
   return Promise.resolve({ value: '', passphraseOnDevice: true });
 }
 
@@ -84,18 +90,19 @@ function promptPassphraseMode(): Promise<PinentryResult> {
           '  1. Standard wallet (no passphrase)',
           '  2. Hidden wallet — enter passphrase on this computer (pinentry)',
           '  3. Hidden wallet — enter passphrase on device screen',
+          '  4. Attach PIN wallet — enter Attach PIN on device screen',
           '',
         ].join('\n')
       );
 
       rl.question('Enter selection [1/2/3]: ', answer => {
-        const n = answer.trim() as '1' | '2' | '3';
-        if (n === '1' || n === '2' || n === '3') {
+        const n = answer.trim() as '1' | '2' | '3' | '4';
+        if (n === '1' || n === '2' || n === '3' || n === '4') {
           rl.close();
           resolvePassphraseByChoice(n).then(resolve);
           return;
         }
-        process.stderr.write('Invalid selection. Enter 1, 2, or 3.\n');
+        process.stderr.write('Invalid selection. Enter 1, 2, 3, or 4.\n');
         prompt();
       });
     };
@@ -143,6 +150,7 @@ function registerEventHandlers(sdk: typeof HardwareSDK): void {
             payload: {
               value: result.value,
               passphraseOnDevice: result.passphraseOnDevice,
+              attachPinOnDevice: result.attachPinOnDevice,
               save: false,
             },
           });
@@ -169,12 +177,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`);
   });
@@ -231,7 +239,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/session.ts

@@ -1,11 +1,8 @@
 /**
  * Passphrase session management for hd-cli.
  *
- * Aligns with app-monorepo's CLI pattern:
- *   Login:   getPassphraseState → passphraseState + sessionId → keychain
- *   Command: keychain → preloadSessionCache → SDK call (no passphrase prompt)
- *   Stale:   error 112 → clear keychain → re-prompt → retry
- *   Logout:  keychain delete
+ * Existing keychain entries remain readable for compatibility, but the public
+ * SDK no longer exposes new device session ids for persistence.
  */
 
 import { preloadSessionCache } from '@onekeyfe/hd-core';
@@ -55,25 +52,6 @@ export async function preloadSessionFromKeychain(deviceId: string): Promise<stri
   return undefined;
 }
 
-/**
- * Save passphraseState + sessionId to keychain for next CLI invocation.
- */
-export async function saveSessionToKeychain(
-  deviceId: string,
-  passphraseState: string,
-  sessionId: string
-): Promise<void> {
-  try {
-    const storage = getStorage();
-    await Promise.all([
-      storage.set(psKey(deviceId), Buffer.from(passphraseState, 'utf-8')),
-      storage.set(sidKey(deviceId), Buffer.from(sessionId, 'utf-8')),
-    ]);
-  } catch {
-    // Non-fatal — session still works in-memory for this invocation
-  }
-}
-
 /**
  * Clear cached session from keychain.
  */

package/src/transports/nobleBlePlugin.ts

@@ -1,9 +1,13 @@
 import {
   ERRORS,
   HardwareErrorCode,
+  ONEKEY_NOTIFY_CHARACTERISTIC_UUID,
   ONEKEY_SERVICE_UUID,
-  isOnekeyDevice,
-  wait,
+  ONEKEY_WRITE_CHARACTERISTIC_UUID,
+  createKnownBleUuidAliases,
+  hasOnekeyCommunicationService,
+  isOnekeyBluetoothDevice,
+  matchesKnownBleUuid,
 } from '@onekeyfe/hd-shared';
 
 import type { LowLevelDevice, LowlevelTransportSharedPlugin } from '@onekeyfe/hd-transport';
@@ -28,21 +32,28 @@ type CharacteristicPair = {
   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 ONEKEY_SERVICE_UUID_ALIASES = createKnownBleUuidAliases(ONEKEY_SERVICE_UUID);
+const ONEKEY_WRITE_UUID_ALIASES = createKnownBleUuidAliases(ONEKEY_WRITE_CHARACTERISTIC_UUID);
+const ONEKEY_NOTIFY_UUID_ALIASES = createKnownBleUuidAliases(ONEKEY_NOTIFY_CHARACTERISTIC_UUID);
 
 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_WRITE_DELAY = 5;
 const BLE_ENCRYPTION_ERROR_PATTERNS = [/encryption is insufficient/i, /insufficient encryption/i];
 
 let noble: NobleModule | null = null;
@@ -50,42 +61,80 @@ 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 notificationQueue: string[] = [];
-const pendingReceivers: Array<(data: string) => void> = [];
+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 isOneKeyPeripheral(peripheral: Peripheral) {
+  const serviceUuids = peripheral.advertisement?.serviceUuids;
+  return (
+    hasOnekeyCommunicationService(serviceUuids) &&
+    isOnekeyBluetoothDevice({
+      id: peripheral.id,
+      localName: peripheral.advertisement?.localName,
+      serviceUuids,
+    })
+  );
 }
 
-function isGenericBleService(uuid?: string | null) {
-  return ['1800', '1801', '180a', '180f'].includes(getBleUuidKey(uuid));
+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 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 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 isOneKeyPeripheral(peripheral: Peripheral) {
-  const deviceName = peripheral.advertisement?.localName || null;
-  return isOnekeyDevice(deviceName, peripheral.id) || hasOneKeyAdvertisementService(peripheral);
+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 enqueueNotification(data: Buffer) {
-  const hex = data.toString('hex');
-  const receiver = pendingReceivers.shift();
-  if (receiver) {
-    receiver(hex);
-    return;
-  }
-  notificationQueue.push(hex);
+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() {
@@ -169,7 +218,7 @@ async function scanDevices(targetDeviceId?: string) {
 
     const onDiscover = (peripheral: Peripheral) => {
       if (targetDeviceId && peripheral.id !== targetDeviceId) return;
-      if (!targetDeviceId && !isOneKeyPeripheral(peripheral)) return;
+      if (!isOneKeyPeripheral(peripheral)) return;
 
       discoveredDevices.set(peripheral.id, peripheral);
       found.set(peripheral.id, peripheral);
@@ -224,13 +273,7 @@ async function discoverCharacteristics(peripheral: Peripheral): Promise<Characte
     });
   });
 
-  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];
-  }
+  const service = services.find(s => matchesKnownBleUuid(s.uuid, ONEKEY_SERVICE_UUID_ALIASES));
   if (!service) {
     throw ERRORS.TypedError(HardwareErrorCode.BleServiceNotFound, 'No BLE service found');
   }
@@ -249,10 +292,9 @@ async function discoverCharacteristics(peripheral: Peripheral): Promise<Characte
   let writeCharacteristic: Characteristic | undefined;
   let notifyCharacteristic: Characteristic | undefined;
   for (const characteristic of characteristics) {
-    const uuidKey = getBleUuidKey(characteristic.uuid);
-    if (uuidKey === NORMALIZED_WRITE_UUID) {
+    if (matchesKnownBleUuid(characteristic.uuid, ONEKEY_WRITE_UUID_ALIASES)) {
       writeCharacteristic = characteristic;
-    } else if (uuidKey === NORMALIZED_NOTIFY_UUID) {
+    } else if (matchesKnownBleUuid(characteristic.uuid, ONEKEY_NOTIFY_UUID_ALIASES)) {
       notifyCharacteristic = characteristic;
     }
   }
@@ -270,10 +312,12 @@ async function discoverCharacteristics(peripheral: Peripheral): Promise<Characte
   };
 }
 
-function subscribeNotifications(deviceId: string, notifyCharacteristic: Characteristic) {
-  return new Promise<void>(resolve => {
-    notifyCharacteristic.unsubscribe(() => resolve());
-  })
+function subscribeNotifications(
+  deviceId: string,
+  generation: number,
+  notifyCharacteristic: Characteristic
+) {
+  return waitForNobleCleanup(callback => notifyCharacteristic.unsubscribe(callback))
     .then(
       () =>
         new Promise<void>((resolve, reject) => {
@@ -303,7 +347,7 @@ function subscribeNotifications(deviceId: string, notifyCharacteristic: Characte
     )
     .then(() => {
       notifyCharacteristic.removeAllListeners('data');
-      notifyCharacteristic.on('data', enqueueNotification);
+      notifyCharacteristic.on('data', data => enqueueNotification(deviceId, generation, data));
     })
     .catch(error => {
       notifyCharacteristic.removeAllListeners('data');
@@ -314,9 +358,13 @@ function subscribeNotifications(deviceId: string, notifyCharacteristic: Characte
     });
 }
 
-function writeCharacteristic(characteristic: Characteristic, buffer: Buffer) {
+function writeCharacteristic(
+  characteristic: Characteristic,
+  buffer: Buffer,
+  withoutResponse: boolean
+) {
   return new Promise<void>((resolve, reject) => {
-    characteristic.write(buffer, true, (error?: Error) => {
+    characteristic.write(buffer, withoutResponse, (error?: Error) => {
       if (error) {
         reject(error);
         return;
@@ -329,23 +377,18 @@ function writeCharacteristic(characteristic: Characteristic, buffer: Buffer) {
 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 new Promise<void>(resolve => {
-      characteristics.notify.unsubscribe(() => resolve());
-    });
+    await waitForNobleCleanup(callback => characteristics.notify.unsubscribe(callback));
   }
 
   connectedDevices.delete(uuid);
   deviceCharacteristics.delete(uuid);
-  notificationQueue.length = 0;
-  pendingReceivers.splice(0).forEach(resolve => resolve(''));
 
   if (!peripheral || peripheral.state === 'disconnected') return;
 
-  await new Promise<void>(resolve => {
-    peripheral.disconnect(() => resolve());
-  });
+  await waitForNobleCleanup(callback => peripheral.disconnect(callback));
 }
 
 export function createNobleBlePlugin(): LowlevelTransportSharedPlugin {
@@ -375,17 +418,31 @@ export function createNobleBlePlugin(): LowlevelTransportSharedPlugin {
       }
 
       await connectPeripheral(peripheral);
-      const characteristics = await discoverCharacteristics(peripheral);
-      await subscribeNotifications(uuid, characteristics.notify);
-      connectedDevices.set(uuid, peripheral);
-      deviceCharacteristics.set(uuid, characteristics);
+      let characteristics: CharacteristicPair | undefined;
+      try {
+        characteristics = await discoverCharacteristics(peripheral);
+        const notificationState = createNotificationState(uuid);
+        await subscribeNotifications(uuid, notificationState.generation, characteristics.notify);
+        connectedDevices.set(uuid, peripheral);
+        deviceCharacteristics.set(uuid, characteristics);
+      } catch (error) {
+        clearNotificationState(uuid, `BLE notification subscription failed: ${uuid}`);
+        if (characteristics) {
+          characteristics.notify.removeAllListeners('data');
+          await waitForNobleCleanup(callback => characteristics?.notify.unsubscribe(callback));
+        }
+        if (peripheral.state !== 'disconnected') {
+          await waitForNobleCleanup(callback => peripheral?.disconnect(callback));
+        }
+        throw error;
+      }
     },
 
     async disconnect(uuid: string) {
       await disconnectDevice(uuid);
     },
 
-    async send(uuid: string, data: string) {
+    async send(uuid: string, data: string, options?: { withoutResponse?: boolean }) {
       const characteristics = deviceCharacteristics.get(uuid);
       if (!characteristics) {
         throw ERRORS.TypedError(
@@ -395,20 +452,35 @@ export function createNobleBlePlugin(): LowlevelTransportSharedPlugin {
       }
 
       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);
-        if (offset + BLE_PACKET_SIZE < buffer.length) {
-          await wait(BLE_WRITE_DELAY);
-        }
+        await writeCharacteristic(characteristics.write, chunk, withoutResponse);
       }
     },
 
-    async receive() {
-      const queued = notificationQueue.shift();
+    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 => {
-        pendingReceivers.push(resolve);
+      return new Promise<string>((resolve, reject) => {
+        state.pendingReceivers.add({ resolve, reject });
       });
     },
   };