@onekeyfe/hd-shared 1.2.0-alpha.147 → 1.2.0-alpha.149

package/dist/constants.d.ts

@@ -8,6 +8,10 @@ export declare const ONEKEY_WEBUSB_FILTER: {
     vendorId: number;
     productId: number;
 }[];
+export declare const ONEKEY_PROTOCOL_V2_USB_IDS: readonly [{
+    readonly vendorId: 4617;
+    readonly productId: 20300;
+}];
 type WebUsbIdentityDescriptor = {
     vendorId?: number;
     productId?: number;
@@ -47,6 +51,14 @@ export declare const ONEKEY_WRITE_CHARACTERISTIC_UUID = "00000002-0000-1000-8000
 export declare const ONEKEY_NOTIFY_CHARACTERISTIC_UUID = "00000003-0000-1000-8000-00805f9b34fb";
 export declare const isHeaderChunk: (chunk: Buffer | Uint8Array) => boolean;
 export declare const isOnekeyDevice: (name: string | null, id?: string) => boolean;
+export declare const inferProtocolHintFromUsbId: (vendorId?: number | null, productId?: number | null) => "V2" | undefined;
+type UsbDevicePathInput = {
+    serialNumber?: string | null;
+    vendorId?: number;
+    productId?: number;
+    productName?: string | null;
+};
+export declare const resolveOneKeyUsbDevicePath: (device: UsbDevicePathInput) => string | undefined;
 type BluetoothDeviceIdentity = {
     id?: string;
     name?: string | null;

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";AAEA,eAAO,MAAM,yBAAyB;;;CAG5B,CAAC;AAEX,MAAM,MAAM,uBAAuB,GACjC,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,OAAO,yBAAyB,CAAC,CAAC;AAE7E,eAAO,MAAM,oBAAoB;;;GAOhC,CAAC;AAEF,KAAK,wBAAwB,GAAG;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC,CAAC;AAIF,eAAO,MAAM,yBAAyB,eAAgB,wBAAwB,KAAG,OAQhF,CAAC;AAMF,eAAO,MAAM,2BAA2B,mDAS9B,CAAC;AAMX,eAAO,MAAM,8BAA8B,qBAGjC,CAAC;AAGX,oBAAY,qBAAqB;IAE/B,UAAU,uBAAuB;IACjC,iBAAiB,8BAA8B;IAC/C,aAAa,0BAA0B;IACvC,kBAAkB,+BAA+B;IACjD,cAAc,2BAA2B;IACzC,oBAAoB,iCAAiC;IAGrD,mBAAmB,gCAAgC;IACnD,oBAAoB,iCAAiC;IAGrD,aAAa,0BAA0B;IACvC,oBAAoB,iCAAiC;IAGrD,uBAAuB,oCAAoC;IAC3D,sBAAsB,mCAAmC;IAGzD,mBAAmB,gCAAgC;IACnD,mBAAmB,gCAAgC;IACnD,oBAAoB,iCAAiC;IACrD,iBAAiB,8BAA8B;IAG/C,iBAAiB,8BAA8B;IAC/C,oBAAoB,iCAAiC;IACrD,eAAe,4BAA4B;IAC3C,mBAAmB,gCAAgC;IACnD,qBAAqB,kCAAkC;IACvD,sBAAsB,mCAAmC;IACzD,qBAAqB,kCAAkC;IACvD,wBAAwB,qCAAqC;CAC9D;AAED,eAAO,MAAM,mBAAmB,yCAAyC,CAAC;AAC1E,eAAO,MAAM,gCAAgC,yCAAyC,CAAC;AACvF,eAAO,MAAM,iCAAiC,yCAAyC,CAAC;AAIxF,eAAO,MAAM,aAAa,UAAW,MAAM,GAAG,UAAU,KAAG,OAa1D,CAAC;AAkBF,eAAO,MAAM,cAAc,SAAU,MAAM,GAAG,IAAI,OAAO,MAAM,KAAG,OAuBjE,CAAC;AAEF,KAAK,uBAAuB,GAAG;IAC7B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC;CACxD,CAAC;AAIF,eAAO,MAAM,gBAAgB,UAAW,MAAM,GAAG,IAAI,WACP,CAAC;AAE/C,eAAO,MAAM,yBAAyB,SAAU,MAAM,KAAG,YAAY,MAAM,CAc1E,CAAC;AAEF,eAAO,MAAM,mBAAmB,eAClB,MAAM,GAAG,IAAI,GAAG,SAAS,WAC5B,YAAY,MAAM,CAAC,YACgB,CAAC;AAkC/C,eAAO,MAAM,6BAA6B,WAAY,MAAM,GAAG,IAAI,YAWlE,CAAC;AAEF,eAAO,MAAM,oCAAoC,UAAW,MAAM,WAejE,CAAC;AAEF,eAAO,MAAM,6BAA6B,iBAC1B,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,YAIhE,CAAC;AAEJ,eAAO,MAAM,uBAAuB,2CAKjC,uBAAuB,KAAG,OAiB5B,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -7,6 +7,11 @@ declare const ONEKEY_WEBUSB_FILTER: {
     vendorId: number;
     productId: number;
 }[];
+/** USB IDs whose first probe should be Protocol V2. Shared Pro/Touch PIDs stay unhinted. */
+declare const ONEKEY_PROTOCOL_V2_USB_IDS: readonly [{
+    readonly vendorId: 4617;
+    readonly productId: 20300;
+}];
 type WebUsbIdentityDescriptor = {
     vendorId?: number;
     productId?: number;
@@ -54,6 +59,14 @@ declare const ONEKEY_WRITE_CHARACTERISTIC_UUID = "00000002-0000-1000-8000-00805f
 declare const ONEKEY_NOTIFY_CHARACTERISTIC_UUID = "00000003-0000-1000-8000-00805f9b34fb";
 declare const isHeaderChunk: (chunk: Buffer | Uint8Array) => boolean;
 declare const isOnekeyDevice: (name: string | null, id?: string) => boolean;
+declare const inferProtocolHintFromUsbId: (vendorId?: number | null, productId?: number | null) => "V2" | undefined;
+type UsbDevicePathInput = {
+    serialNumber?: string | null;
+    vendorId?: number;
+    productId?: number;
+    productName?: string | null;
+};
+declare const resolveOneKeyUsbDevicePath: (device: UsbDevicePathInput) => string | undefined;
 type BluetoothDeviceIdentity = {
     id?: string;
     name?: string | null;
@@ -531,4 +544,4 @@ declare enum EDeviceType {
     Neo = "neo"
 }
 
-export { CreateErrorByMessage, CreateHardwareErrorByBridgeError, Deferred, EDeviceType, EFirmwareType, EOneKeyBleMessageKeys, HardwareError$1 as ERRORS, ERROR_CODES_REQUIRE_DISCONNECT, ERROR_CODES_REQUIRE_RELEASE, HARDWARE_CONNECT_PROTOCOL, HardwareConnectProtocol, HardwareError, HardwareErrorCode, HardwareErrorCodeMessage, IHardwareError, ONEKEY_NOTIFY_CHARACTERISTIC_UUID, ONEKEY_SERVICE_UUID, ONEKEY_WEBUSB_FILTER, ONEKEY_WRITE_CHARACTERISTIC_UUID, TypedError, createDefectiveFirmwareError, createDeferred, createDeprecatedHardwareError, createDeviceNotSupportMethodError, createKnownBleUuidAliases, createNeedUpgradeFirmwareHardwareError, createNewFirmwareForceUpdateHardwareError, createNewFirmwareUnReleaseHardwareError, hasOnekeyCommunicationService, isHeaderChunk, isKnownTrezorWebUsbDevice, isOnekeyBluetoothDevice, isOnekeyDevice, isPro2FindMyAdvertisementName, matchesKnownBleUuid, normalizeBleUuid, normalizePro2FindMyAdvertisementName, serializeError, wait };
+export { CreateErrorByMessage, CreateHardwareErrorByBridgeError, Deferred, EDeviceType, EFirmwareType, EOneKeyBleMessageKeys, HardwareError$1 as ERRORS, ERROR_CODES_REQUIRE_DISCONNECT, ERROR_CODES_REQUIRE_RELEASE, HARDWARE_CONNECT_PROTOCOL, HardwareConnectProtocol, HardwareError, HardwareErrorCode, HardwareErrorCodeMessage, IHardwareError, ONEKEY_NOTIFY_CHARACTERISTIC_UUID, ONEKEY_PROTOCOL_V2_USB_IDS, ONEKEY_SERVICE_UUID, ONEKEY_WEBUSB_FILTER, ONEKEY_WRITE_CHARACTERISTIC_UUID, TypedError, createDefectiveFirmwareError, createDeferred, createDeprecatedHardwareError, createDeviceNotSupportMethodError, createKnownBleUuidAliases, createNeedUpgradeFirmwareHardwareError, createNewFirmwareForceUpdateHardwareError, createNewFirmwareUnReleaseHardwareError, hasOnekeyCommunicationService, inferProtocolHintFromUsbId, isHeaderChunk, isKnownTrezorWebUsbDevice, isOnekeyBluetoothDevice, isOnekeyDevice, isPro2FindMyAdvertisementName, matchesKnownBleUuid, normalizeBleUuid, normalizePro2FindMyAdvertisementName, resolveOneKeyUsbDevicePath, serializeError, wait };

package/dist/index.js

@@ -399,6 +399,7 @@ const ONEKEY_WEBUSB_FILTER = [
     { vendorId: 0x1209, productId: 0x4f4b },
     { vendorId: 0x1209, productId: 0x4f4c },
 ];
+const ONEKEY_PROTOCOL_V2_USB_IDS = [{ vendorId: 0x1209, productId: 0x4f4c }];
 const TREZOR_WEBUSB_MANUFACTURER_NAMES = new Set(['trezor', 'trezor company', 'satoshilabs']);
 const isKnownTrezorWebUsbDevice = (descriptor) => {
     var _a;
@@ -495,12 +496,36 @@ const isOnekeyDevice = (name, id) => {
         return true;
     if (normalizedName.startsWith('touch ') ||
         normalizedName.startsWith('pro ') ||
-        normalizedName.startsWith('pro2 ') ||
-        normalizedName.startsWith('neo ')) {
+        normalizedName.startsWith('pro2') ||
+        normalizedName.startsWith('neo')) {
+        return true;
+    }
+    const compactName = compactBleName(normalizedName);
+    if (PRO2_COMPACT_NAME_PATTERN.test(compactName) || NEO_COMPACT_NAME_PATTERN.test(compactName)) {
         return true;
     }
     return isOneKeyShortName(normalizedName);
 };
+const inferProtocolHintFromUsbId = (vendorId, productId) => ONEKEY_PROTOCOL_V2_USB_IDS.some(id => id.vendorId === vendorId && id.productId === productId)
+    ? 'V2'
+    : undefined;
+const resolveOneKeyUsbDevicePath = (device) => {
+    var _a, _b, _c, _d;
+    const serial = (_a = device.serialNumber) === null || _a === void 0 ? void 0 : _a.trim();
+    if (serial)
+        return serial;
+    if (device.vendorId == null && device.productId == null && !device.productName) {
+        return undefined;
+    }
+    const vendorId = ((_b = device.vendorId) !== null && _b !== void 0 ? _b : 0).toString(16).padStart(4, '0');
+    const productId = ((_c = device.productId) !== null && _c !== void 0 ? _c : 0).toString(16).padStart(4, '0');
+    const product = ((_d = device.productName) !== null && _d !== void 0 ? _d : 'onekey')
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, '-')
+        .replace(/[^a-z0-9-]/g, '');
+    return `usb-${vendorId}-${productId}-${product || 'onekey'}`;
+};
 const BLUETOOTH_BASE_UUID_SUFFIX = '00001000800000805f9b34fb';
 const normalizeBleUuid = (uuid) => (uuid !== null && uuid !== void 0 ? uuid : '').replace(/-/g, '').toLowerCase();
 const createKnownBleUuidAliases = (uuid) => {
@@ -520,6 +545,7 @@ const matchesKnownBleUuid = (actualUuid, aliases) => aliases.has(normalizeBleUui
 const ONEKEY_COMMUNICATION_SERVICE_ALIASES = createKnownBleUuidAliases(ONEKEY_SERVICE_UUID);
 const FIDO_SERVICE_ALIASES = createKnownBleUuidAliases('0000fffd-0000-1000-8000-00805f9b34fb');
 const PRO2_COMPACT_NAME_PATTERN = /^(?:onekey)?pro2[a-f0-9]{4}$/i;
+const NEO_COMPACT_NAME_PATTERN = /^(?:onekey)?neo[a-f0-9]{4}$/i;
 const FIND_MY_COMPACT_SUFFIXES = [
     'findemy',
     'findem',
@@ -669,6 +695,7 @@ exports.HardwareError = HardwareError;
 exports.HardwareErrorCode = HardwareErrorCode;
 exports.HardwareErrorCodeMessage = HardwareErrorCodeMessage;
 exports.ONEKEY_NOTIFY_CHARACTERISTIC_UUID = ONEKEY_NOTIFY_CHARACTERISTIC_UUID;
+exports.ONEKEY_PROTOCOL_V2_USB_IDS = ONEKEY_PROTOCOL_V2_USB_IDS;
 exports.ONEKEY_SERVICE_UUID = ONEKEY_SERVICE_UUID;
 exports.ONEKEY_WEBUSB_FILTER = ONEKEY_WEBUSB_FILTER;
 exports.ONEKEY_WRITE_CHARACTERISTIC_UUID = ONEKEY_WRITE_CHARACTERISTIC_UUID;
@@ -682,6 +709,7 @@ exports.createNeedUpgradeFirmwareHardwareError = createNeedUpgradeFirmwareHardwa
 exports.createNewFirmwareForceUpdateHardwareError = createNewFirmwareForceUpdateHardwareError;
 exports.createNewFirmwareUnReleaseHardwareError = createNewFirmwareUnReleaseHardwareError;
 exports.hasOnekeyCommunicationService = hasOnekeyCommunicationService;
+exports.inferProtocolHintFromUsbId = inferProtocolHintFromUsbId;
 exports.isHeaderChunk = isHeaderChunk;
 exports.isKnownTrezorWebUsbDevice = isKnownTrezorWebUsbDevice;
 exports.isOnekeyBluetoothDevice = isOnekeyBluetoothDevice;
@@ -690,5 +718,6 @@ exports.isPro2FindMyAdvertisementName = isPro2FindMyAdvertisementName;
 exports.matchesKnownBleUuid = matchesKnownBleUuid;
 exports.normalizeBleUuid = normalizeBleUuid;
 exports.normalizePro2FindMyAdvertisementName = normalizePro2FindMyAdvertisementName;
+exports.resolveOneKeyUsbDevicePath = resolveOneKeyUsbDevicePath;
 exports.serializeError = serializeError;
 exports.wait = wait;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hd-shared",
-  "version": "1.2.0-alpha.147",
+  "version": "1.2.0-alpha.149",
   "description": "Hardware SDK's shared tool library",
   "keywords": [
     "Hardware-SDK",
@@ -26,5 +26,5 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix"
   },
-  "gitHead": "a34e98865e6be227cf3e00d486146e6592761db0"
+  "gitHead": "0c2b72c1edbafb2b738e3eb0b9ecdad8d8b92df7"
 }

package/src/constants.test.ts

@@ -1,12 +1,14 @@
 import {
   createKnownBleUuidAliases,
   hasOnekeyCommunicationService,
+  inferProtocolHintFromUsbId,
   isKnownTrezorWebUsbDevice,
   isOnekeyBluetoothDevice,
   isOnekeyDevice,
   isPro2FindMyAdvertisementName,
   matchesKnownBleUuid,
   normalizePro2FindMyAdvertisementName,
+  resolveOneKeyUsbDevicePath,
 } from './constants';
 
 describe('hardware device identity filters', () => {
@@ -14,6 +16,9 @@ describe('hardware device identity filters', () => {
     expect(isOnekeyDevice('Touch A1B2')).toBe(true);
     expect(isOnekeyDevice('Pro A1B2')).toBe(true);
     expect(isOnekeyDevice('Neo A1B2')).toBe(true);
+    expect(isOnekeyDevice('Pro2A1B2')).toBe(true);
+    expect(isOnekeyDevice('OneKeyPro2A1B2')).toBe(true);
+    expect(isOnekeyDevice('Neo22D8')).toBe(true);
     expect(isOnekeyDevice('K1234')).toBe(true);
     expect(isOnekeyDevice('S8')).toBe(true);
   });
@@ -136,6 +141,32 @@ describe('hardware device identity filters', () => {
     expect(hasOnekeyCommunicationService(['abcd0001-1234-5678-9012-abcdefabcdef'])).toBe(false);
   });
 
+  it('hints Protocol V2 from the current Pro2/Neo USB ID only', () => {
+    expect(inferProtocolHintFromUsbId(0x1209, 0x4f4c)).toBe('V2');
+    expect(inferProtocolHintFromUsbId(0x1209, 0x53c1)).toBeUndefined();
+    expect(inferProtocolHintFromUsbId(0x1209, 0x4f4a)).toBeUndefined();
+    expect(inferProtocolHintFromUsbId(0x1209, 0x4f4b)).toBeUndefined();
+  });
+
+  it('uses the USB serial when present and synthesizes a path when firmware omits it', () => {
+    expect(
+      resolveOneKeyUsbDevicePath({
+        vendorId: 0x1209,
+        productId: 0x4f4c,
+        productName: 'OneKey Pro 2',
+        serialNumber: 'PRO2-SERIAL',
+      })
+    ).toBe('PRO2-SERIAL');
+    expect(
+      resolveOneKeyUsbDevicePath({
+        vendorId: 0x1209,
+        productId: 0x4f4c,
+        productName: 'OneKey Neo',
+        serialNumber: '',
+      })
+    ).toBe('usb-1209-4f4c-onekey-neo');
+  });
+
   it('only filters WebUSB descriptors that are explicitly identified as Trezor', () => {
     expect(
       isKnownTrezorWebUsbDevice({

package/src/constants.ts

@@ -13,10 +13,13 @@ export const ONEKEY_WEBUSB_FILTER = [
   { vendorId: 0x1209, productId: 0x53c1 }, // Classic/Classic1s/Mini/Pro/Touch firmware and legacy Pro2; keep for existing devices
   { vendorId: 0x1209, productId: 0x4f4a }, // Pro bootloader, Touch bootloader, Pro2
   { vendorId: 0x1209, productId: 0x4f4b }, // Pro/Touch firmware (Trezor not implemented), Pro2
-  { vendorId: 0x1209, productId: 0x4f4c }, // Pro board and Pro2 with the new firmware PID
+  { vendorId: 0x1209, productId: 0x4f4c }, // Pro2 / Neo current firmware, all modes
   // { vendorId: 0x1209, productId: 0x4f50 }, // Touch Board
 ];
 
+/** USB IDs whose first probe should be Protocol V2. Shared Pro/Touch PIDs stay unhinted. */
+export const ONEKEY_PROTOCOL_V2_USB_IDS = [{ vendorId: 0x1209, productId: 0x4f4c }] as const;
+
 type WebUsbIdentityDescriptor = {
   vendorId?: number;
   productId?: number;
@@ -152,14 +155,47 @@ export const isOnekeyDevice = (name: string | null, id?: string): boolean => {
   if (
     normalizedName.startsWith('touch ') ||
     normalizedName.startsWith('pro ') ||
-    normalizedName.startsWith('pro2 ') ||
-    normalizedName.startsWith('neo ')
+    normalizedName.startsWith('pro2') ||
+    normalizedName.startsWith('neo')
   ) {
     return true;
   }
+  const compactName = compactBleName(normalizedName);
+  if (PRO2_COMPACT_NAME_PATTERN.test(compactName) || NEO_COMPACT_NAME_PATTERN.test(compactName)) {
+    return true;
+  }
   return isOneKeyShortName(normalizedName);
 };
 
+export const inferProtocolHintFromUsbId = (vendorId?: number | null, productId?: number | null) =>
+  ONEKEY_PROTOCOL_V2_USB_IDS.some(id => id.vendorId === vendorId && id.productId === productId)
+    ? ('V2' as const)
+    : undefined;
+
+type UsbDevicePathInput = {
+  serialNumber?: string | null;
+  vendorId?: number;
+  productId?: number;
+  productName?: string | null;
+};
+
+export const resolveOneKeyUsbDevicePath = (device: UsbDevicePathInput): string | undefined => {
+  const serial = device.serialNumber?.trim();
+  if (serial) return serial;
+  if (device.vendorId == null && device.productId == null && !device.productName) {
+    return undefined;
+  }
+
+  const vendorId = (device.vendorId ?? 0).toString(16).padStart(4, '0');
+  const productId = (device.productId ?? 0).toString(16).padStart(4, '0');
+  const product = (device.productName ?? 'onekey')
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9-]/g, '');
+  return `usb-${vendorId}-${productId}-${product || 'onekey'}`;
+};
+
 type BluetoothDeviceIdentity = {
   id?: string;
   name?: string | null;
@@ -196,6 +232,7 @@ export const matchesKnownBleUuid = (
 const ONEKEY_COMMUNICATION_SERVICE_ALIASES = createKnownBleUuidAliases(ONEKEY_SERVICE_UUID);
 const FIDO_SERVICE_ALIASES = createKnownBleUuidAliases('0000fffd-0000-1000-8000-00805f9b34fb');
 const PRO2_COMPACT_NAME_PATTERN = /^(?:onekey)?pro2[a-f0-9]{4}$/i;
+const NEO_COMPACT_NAME_PATTERN = /^(?:onekey)?neo[a-f0-9]{4}$/i;
 const FIND_MY_COMPACT_SUFFIXES = [
   'findemy',
   'findem',