@onekeyfe/hd-core 1.2.0-alpha.1 → 1.2.0-alpha.100

package/src/api/protocol-v2/DeviceUploadNft.ts

@@ -0,0 +1,197 @@
+import { ERRORS, HardwareErrorCode, createDeviceNotSupportMethodError } from '@onekeyfe/hd-shared';
+
+import { UI_REQUEST, createUiMessage } from '../../events/ui-request';
+import { supportsProtocolV2Message } from '../../protocols/protocol-v2/features';
+import {
+  PRO2_NFT_DEFAULT_CHUNK_SIZE,
+  PRO2_NFT_DEFAULT_PACE_MS,
+  PRO2_NFT_DEFAULT_TIMEOUT_MS,
+  PRO2_NFT_DIRECTORY,
+  PRO2_NFT_MAX_CHUNK_SIZE,
+  PRO2_NFT_MAX_ITEMS,
+  PRO2_NFT_MIN_CHUNK_SIZE,
+  type Pro2NftBundle,
+  type Pro2NftImage,
+  buildPro2NftBundle,
+  getCompletePro2NftBasenames,
+} from '../../utils/pro2Nft';
+import { BaseMethod } from '../BaseMethod';
+import { invalidParameter } from '../helpers/filesystemValidation';
+import { writeProtocolV2File } from '../helpers/protocolV2FileWrite';
+
+export type DeviceUploadNftParams = {
+  image: Pro2NftImage;
+  thumbnail: Pro2NftImage;
+  title: string;
+  subtitle: string;
+  timestampMs?: number;
+  chunkSize?: number;
+  paceMs?: number;
+  timeoutMs?: number;
+};
+
+export type DeviceUploadNftResponse = {
+  basename: string;
+  imagePath: string;
+  thumbnailPath: string;
+  metadataPath: string;
+  totalSize: number;
+  nftUpdated: true;
+  message?: string;
+};
+
+const FILESYSTEM_PATH_INFO_QUERY_MESSAGE_TYPE = 60802;
+const FILESYSTEM_FILE_WRITE_MESSAGE_TYPE = 60805;
+const FILESYSTEM_DIR_LIST_MESSAGE_TYPE = 60808;
+const NFT_UPDATE_MESSAGE_TYPE = 61500;
+
+export default class DeviceUploadNft extends BaseMethod<DeviceUploadNftParams> {
+  private bundle?: Pro2NftBundle;
+
+  getSupportedProtocols() {
+    return ['V2'] as const;
+  }
+
+  init() {
+    const {
+      image,
+      thumbnail,
+      title,
+      subtitle,
+      timestampMs = Date.now(),
+      chunkSize = PRO2_NFT_DEFAULT_CHUNK_SIZE,
+      paceMs = PRO2_NFT_DEFAULT_PACE_MS,
+      timeoutMs = PRO2_NFT_DEFAULT_TIMEOUT_MS,
+    } = this.payload;
+    if (
+      !Number.isInteger(chunkSize) ||
+      chunkSize < PRO2_NFT_MIN_CHUNK_SIZE ||
+      chunkSize > PRO2_NFT_MAX_CHUNK_SIZE
+    ) {
+      throw invalidParameter(
+        `Parameter [chunkSize] must be an integer between ${PRO2_NFT_MIN_CHUNK_SIZE} and ${PRO2_NFT_MAX_CHUNK_SIZE}.`
+      );
+    }
+    if (!Number.isInteger(paceMs) || paceMs < 0) {
+      throw invalidParameter('Parameter [paceMs] must be a non-negative integer.');
+    }
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+      throw invalidParameter('Parameter [timeoutMs] must be a positive integer.');
+    }
+
+    this.bundle = buildPro2NftBundle({ image, thumbnail, title, subtitle, timestampMs });
+    this.params = { image, thumbnail, title, subtitle, timestampMs, chunkSize, paceMs, timeoutMs };
+    this.unlockPolicy = 'none';
+    this.skipForceUpdateCheck = true;
+    this.useDevicePassphraseState = false;
+  }
+
+  private async assertCapabilities() {
+    const protocolInfo = await this.device.ensureProtocolV2RuntimeContext();
+    const hasFileWrite = supportsProtocolV2Message(
+      protocolInfo,
+      FILESYSTEM_FILE_WRITE_MESSAGE_TYPE
+    );
+    const hasPathInfo = supportsProtocolV2Message(
+      protocolInfo,
+      FILESYSTEM_PATH_INFO_QUERY_MESSAGE_TYPE
+    );
+    const hasDirList = supportsProtocolV2Message(protocolInfo, FILESYSTEM_DIR_LIST_MESSAGE_TYPE);
+    const hasNftUpdate = supportsProtocolV2Message(protocolInfo, NFT_UPDATE_MESSAGE_TYPE);
+    if (!hasFileWrite || !hasPathInfo || !hasDirList || !hasNftUpdate) {
+      throw createDeviceNotSupportMethodError(this.name, this.device.getCurrentFirmwareType());
+    }
+  }
+
+  private async assertStorageCapacity(basename: string) {
+    const { message: pathInfo } = await this.device.commands.typedCall(
+      'FilesystemPathInfoQuery',
+      'FilesystemPathInfo',
+      { path: PRO2_NFT_DIRECTORY },
+      { timeoutMs: this.params.timeoutMs }
+    );
+    if (!pathInfo.exist) return;
+
+    const { message } = await this.device.commands.typedCall(
+      'FilesystemDirList',
+      'FilesystemDir',
+      { path: PRO2_NFT_DIRECTORY, depth: 1 },
+      { timeoutMs: this.params.timeoutMs }
+    );
+    const existingBasenames = getCompletePro2NftBasenames(message.child_files);
+    if (existingBasenames.size >= PRO2_NFT_MAX_ITEMS && !existingBasenames.has(basename)) {
+      throw ERRORS.TypedError(HardwareErrorCode.NftStorageLimitReached, undefined, {
+        count: existingBasenames.size,
+        limit: PRO2_NFT_MAX_ITEMS,
+      });
+    }
+  }
+
+  private async updateNft(basename: string) {
+    return this.device.commands.typedCall(
+      'NftUpdate',
+      'Success',
+      { file_name_no_ext: basename },
+      { timeoutMs: this.params.timeoutMs }
+    );
+  }
+
+  async run(): Promise<DeviceUploadNftResponse> {
+    const { bundle } = this;
+    if (!bundle) throw invalidParameter('NFT data has not been initialized.');
+
+    await this.assertCapabilities();
+    this.throwIfAborted();
+    await this.assertStorageCapacity(bundle.basename);
+    this.throwIfAborted();
+
+    const files = [
+      { path: `${PRO2_NFT_DIRECTORY}/${bundle.basename}.bin`, data: bundle.image },
+      { path: `${PRO2_NFT_DIRECTORY}/${bundle.basename}_m.bin`, data: bundle.thumbnail },
+      { path: `${PRO2_NFT_DIRECTORY}/${bundle.basename}.json`, data: bundle.metadata },
+    ];
+    const totalSize = files.reduce((sum, file) => sum + file.data.byteLength, 0);
+    let transferredBeforeFile = 0;
+
+    for (const file of files) {
+      const transferredAtFileStart = transferredBeforeFile;
+      await writeProtocolV2File({
+        commands: this.device.commands,
+        path: file.path,
+        data: file.data,
+        totalSize: file.data.byteLength,
+        chunkSize: this.params.chunkSize,
+        timeoutMs: this.params.timeoutMs,
+        paceMs: this.params.paceMs,
+        overwrite: true,
+        append: false,
+        throwIfAborted: () => this.throwIfAborted(),
+        onProgress: progress => {
+          if (typeof this.postMessage !== 'function') return;
+          const transferredBytes = transferredAtFileStart + progress.transferredBytes;
+          this.postMessage(
+            createUiMessage(UI_REQUEST.DEVICE_PROGRESS, {
+              ...progress,
+              progress: Math.floor((transferredBytes / totalSize) * 100),
+              transferredBytes,
+              totalBytes: totalSize,
+            })
+          );
+        },
+      });
+      transferredBeforeFile += file.data.byteLength;
+    }
+
+    this.throwIfAborted();
+    const response = await this.updateNft(bundle.basename);
+    return {
+      basename: bundle.basename,
+      imagePath: files[0].path,
+      thumbnailPath: files[1].path,
+      metadataPath: files[2].path,
+      totalSize,
+      nftUpdated: true,
+      message: response.message?.message,
+    };
+  }
+}

package/src/api/protocol-v2/DeviceUploadWallpaper.ts

@@ -0,0 +1,134 @@
+import { blake2s } from '@noble/hashes/blake2s';
+import { bytesToHex } from '@noble/hashes/utils';
+
+import { BaseMethod } from '../BaseMethod';
+import { invalidParameter } from '../helpers/filesystemValidation';
+import { writeProtocolV2File } from '../helpers/protocolV2FileWrite';
+import { UI_REQUEST, createUiMessage } from '../../events/ui-request';
+import {
+  PRO2_WALLPAPER_HEIGHT,
+  PRO2_WALLPAPER_WIDTH,
+  type Pro2WallpaperColorFormat,
+  encodePro2Wallpaper,
+} from '../../utils/pro2Wallpaper';
+
+export type DeviceUploadWallpaperParams = {
+  width: number;
+  height: number;
+  rgba: Uint8Array | ArrayBuffer;
+  fileName?: string;
+  chunkSize?: number;
+};
+
+export type DeviceUploadWallpaperResponse = {
+  path: string;
+  size: number;
+  colorFormat: Pro2WallpaperColorFormat;
+  message?: string;
+};
+
+const WALLPAPER_DIRECTORY = 'vol1:/wallpapers';
+const SAFE_FILE_NAME = /^[A-Za-z0-9_-]+(?:\.bin)?$/;
+
+function normalizeFileName(fileName: string | undefined, data: Uint8Array): string {
+  if (fileName !== undefined && (!fileName || !SAFE_FILE_NAME.test(fileName))) {
+    throw invalidParameter(
+      'Parameter [fileName] may only contain letters, numbers, underscores, hyphens and an optional .bin suffix.'
+    );
+  }
+  const baseName = fileName ?? `wallpaper-${bytesToHex(blake2s(data)).slice(0, 12)}`;
+  return baseName.endsWith('.bin') ? baseName : `${baseName}.bin`;
+}
+
+export default class DeviceUploadWallpaper extends BaseMethod<DeviceUploadWallpaperParams> {
+  getSupportedProtocols() {
+    return ['V2'] as const;
+  }
+
+  private encoded?: { data: Uint8Array; colorFormat: Pro2WallpaperColorFormat };
+
+  private directoryReady = false;
+
+  private uploaded = false;
+
+  private path = '';
+
+  init() {
+    const { width, height, rgba, fileName, chunkSize } = this.payload;
+    if (width !== PRO2_WALLPAPER_WIDTH || height !== PRO2_WALLPAPER_HEIGHT) {
+      throw invalidParameter(
+        `Pro2 wallpaper dimensions must be ${PRO2_WALLPAPER_WIDTH}x${PRO2_WALLPAPER_HEIGHT}.`
+      );
+    }
+    if (!(rgba instanceof ArrayBuffer) && !ArrayBuffer.isView(rgba)) {
+      throw invalidParameter('Parameter [rgba] must be an ArrayBuffer or Uint8Array.');
+    }
+    if (chunkSize !== undefined && (!Number.isInteger(chunkSize) || chunkSize <= 0)) {
+      throw invalidParameter('Parameter [chunkSize] must be a positive integer.');
+    }
+
+    const rgbaBytes =
+      rgba instanceof ArrayBuffer
+        ? rgba
+        : new Uint8Array(rgba.buffer, rgba.byteOffset, rgba.byteLength);
+    this.encoded = encodePro2Wallpaper({ width, height, rgba: rgbaBytes });
+    this.path = `${WALLPAPER_DIRECTORY}/${normalizeFileName(fileName, this.encoded.data)}`;
+    this.params = { width, height, rgba: rgbaBytes, fileName, chunkSize };
+    this.unlockPolicy = 'none';
+    this.skipForceUpdateCheck = true;
+    this.useDevicePassphraseState = false;
+  }
+
+  private async ensureDirectory() {
+    if (this.directoryReady) return;
+    try {
+      await this.device.commands.typedCall('FilesystemDirMake', 'Success', {
+        path: WALLPAPER_DIRECTORY,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (!/exist/i.test(message)) throw error;
+    }
+    this.directoryReady = true;
+  }
+
+  private async upload() {
+    if (this.uploaded) return;
+    const { encoded } = this;
+    if (!encoded) throw invalidParameter('Wallpaper data has not been initialized.');
+
+    await writeProtocolV2File({
+      commands: this.device.commands,
+      path: this.path,
+      data: encoded.data,
+      totalSize: encoded.data.byteLength,
+      chunkSize: this.params.chunkSize,
+      maxChunkRetries: 3,
+      overwrite: true,
+      append: false,
+      throwIfAborted: () => this.throwIfAborted(),
+      onProgress: payload => {
+        if (typeof this.postMessage === 'function') {
+          this.postMessage(createUiMessage(UI_REQUEST.DEVICE_PROGRESS, payload));
+        }
+      },
+    });
+    this.uploaded = true;
+  }
+
+  async run(): Promise<DeviceUploadWallpaperResponse> {
+    const { encoded } = this;
+    if (!encoded) throw invalidParameter('Wallpaper data has not been initialized.');
+    await this.ensureDirectory();
+    await this.upload();
+    const response = await this.device.commands.typedCall('DeviceSettingsSet', 'Success', {
+      settings: { wallpaper_path: this.path },
+    });
+    return {
+      path: this.path,
+      size: encoded.data.byteLength,
+      colorFormat: encoded.colorFormat,
+      message: response.message?.message,
+    };
+  }
+}

package/src/api/protocol-v2/FilesystemFormat.ts

@@ -1,16 +1,22 @@
 import { BaseMethod } from '../BaseMethod';
 
 export default class FilesystemFormat extends BaseMethod {
+  getSupportedProtocols() {
+    return ['V2'] as const;
+  }
+
   init() {
-    // Protocol V2 (Pro2) 专属方法，core 调度层统一做非 V2 设备守卫
-    this.requireProtocolV2 = true;
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
     this.params = undefined;
   }
 
   async run() {
-    const res = await this.device.commands.typedCall('FilesystemFormat', 'Success', {});
+    const res = await this.device.commands.typedCall('FilesystemFormat', 'Success', {
+      data: true,
+      user: true,
+    });
     return Promise.resolve(res.message);
   }
 }

package/src/api/protocol-v2/{FilesystemFixPermission.ts → FilesystemPermissionFix.ts}

@@ -1,16 +1,19 @@
 import { BaseMethod } from '../BaseMethod';
 
-export default class FilesystemFixPermission extends BaseMethod {
+export default class FilesystemPermissionFix extends BaseMethod {
+  getSupportedProtocols() {
+    return ['V2'] as const;
+  }
+
   init() {
-    // Protocol V2 (Pro2) 专属方法，core 调度层统一做非 V2 设备守卫
-    this.requireProtocolV2 = true;
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
     this.params = undefined;
   }
 
   async run() {
-    const res = await this.device.commands.typedCall('FilesystemFixPermission', 'Success', {});
+    const res = await this.device.commands.typedCall('FilesystemPermissionFix', 'Success', {});
     return Promise.resolve(res.message);
   }
 }

package/src/api/protocol-v2/Ping.ts

@@ -1,12 +1,46 @@
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
 import { BaseMethod } from '../BaseMethod';
 
+// nanopb max_size:64 includes the terminating NUL for string fields.
+export const PROTOCOL_V2_PING_MAX_MESSAGE_BYTES = 63;
+
+const getUtf8ByteLength = (value: string) =>
+  Array.from(value).reduce((length, character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    if (codePoint <= 0x7f) return length + 1;
+    if (codePoint <= 0x7ff) return length + 2;
+    if (codePoint <= 0xffff) return length + 3;
+    return length + 4;
+  }, 0);
+
+export function validateProtocolV2PingMessage(value: unknown): string {
+  if (value !== undefined && typeof value !== 'string') {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.CallMethodInvalidParameter,
+      'Protocol V2 Ping message must be a string.'
+    );
+  }
+  const message = value ?? '';
+  if (getUtf8ByteLength(message) > PROTOCOL_V2_PING_MAX_MESSAGE_BYTES) {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.CallMethodInvalidParameter,
+      `Protocol V2 Ping message must not exceed ${PROTOCOL_V2_PING_MAX_MESSAGE_BYTES} UTF-8 bytes.`
+    );
+  }
+  return message;
+}
+
 export default class Ping extends BaseMethod<{ message?: string }> {
+  getSupportedProtocols() {
+    return ['V2'] as const;
+  }
+
   init() {
-    // Protocol V2 (Pro2) 专属方法，core 调度层统一做非 V2 设备守卫
-    this.requireProtocolV2 = true;
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
-    this.params = { message: this.payload.message };
+    this.params = { message: validateProtocolV2PingMessage(this.payload.message) };
   }
 
   async run() {

package/src/api/protocol-v2/ProtocolInfoRequest.ts

@@ -0,0 +1,21 @@
+import { BaseMethod } from '../BaseMethod';
+
+export default class ProtocolInfoRequest extends BaseMethod {
+  getSupportedProtocols() {
+    return ['V2'] as const;
+  }
+
+  init() {
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
+    this.skipForceUpdateCheck = true;
+    this.useDevicePassphraseState = false;
+    this.params = undefined;
+  }
+
+  async run() {
+    const res = await this.device.commands.typedCall('ProtocolInfoRequest', 'ProtocolInfo', {
+      eventless_wallet_session: true,
+    });
+    return Promise.resolve(res.message);
+  }
+}

package/src/api/protocol-v2/helpers.ts

@@ -1,18 +1,16 @@
-import { DevRebootType } from '@onekeyfe/hd-transport';
+import { DeviceRebootType } from '@onekeyfe/hd-transport';
 
 import { invalidParameter, validateNonEmptyString } from '../helpers/filesystemValidation';
+import { ProtocolV2FirmwareTargetType } from '../../protocols/protocol-v2/firmware';
 
 import type {
-  DevFirmwareTarget,
-  DevFirmwareTargetType,
+  DeviceFirmwareTarget,
+  DeviceFirmwareTargetType,
+  DeviceFirmwareUpdateRecordFields,
   TransportCallOptions,
 } from '@onekeyfe/hd-transport';
 
-export type RebootTypeInput =
-  | DevRebootType
-  | keyof typeof DevRebootType
-  | string
-  | number;
+export type RebootTypeInput = DeviceRebootType | keyof typeof DeviceRebootType | string | number;
 
 export type DeviceRebootParams = {
   rebootType?: RebootTypeInput;
@@ -20,48 +18,58 @@ export type DeviceRebootParams = {
 };
 
 export type DeviceFirmwareTargetInput =
-  | DevFirmwareTarget
+  | DeviceFirmwareTarget
   | {
-      targetId?: DevFirmwareTargetType | string | number;
-      target_id?: DevFirmwareTargetType | string | number;
+      targetId?: DeviceFirmwareTargetType | string | number;
+      target_id?: DeviceFirmwareTargetType | string | number;
       path: string;
     };
 
 export type DeviceFirmwareUpdateParams = {
   targets?: DeviceFirmwareTargetInput[];
-  targetId?: DevFirmwareTargetType | string | number;
-  target_id?: DevFirmwareTargetType | string | number;
+  targetId?: DeviceFirmwareTargetType | string | number;
+  target_id?: DeviceFirmwareTargetType | string | number;
   path?: string;
 };
 
-export type FactoryDeviceInfoSettingsParams = {
-  serial_no?: string;
-  serialNo?: string;
-  cpu_info?: string;
-  cpuInfo?: string;
-  pre_firmware?: string;
-  preFirmware?: string;
+export type DeviceFirmwareUpdateStatusGetParams = {
+  fields?: DeviceFirmwareUpdateRecordFields;
 };
 
-const DEV_REBOOT_TYPES: Record<string, DevRebootType> = {
-  Normal: DevRebootType.Normal,
-  normal: DevRebootType.Normal,
-  Romloader: DevRebootType.Boardloader,
-  romloader: DevRebootType.Boardloader,
-  Boardloader: DevRebootType.Boardloader,
-  boardloader: DevRebootType.Boardloader,
-  Bootloader: DevRebootType.Bootloader,
-  bootloader: DevRebootType.Bootloader,
+export type DeviceFactoryInfoSetParams = {
+  version?: number;
+  serial_number?: string;
+  burn_in_completed?: boolean;
+  factory_test_completed?: boolean;
+  manufacture_time?: {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+  };
+};
+
+const DEVICE_REBOOT_TYPES: Record<string, DeviceRebootType> = {
+  Normal: DeviceRebootType.Normal,
+  normal: DeviceRebootType.Normal,
+  Romloader: DeviceRebootType.Romloader,
+  romloader: DeviceRebootType.Romloader,
+  Boardloader: DeviceRebootType.Romloader,
+  boardloader: DeviceRebootType.Romloader,
+  Bootloader: DeviceRebootType.Bootloader,
+  bootloader: DeviceRebootType.Bootloader,
 };
 
 export const PROTOCOL_V2_FIRMWARE_UPDATE_OPTIONS: TransportCallOptions = {
-  intermediateTypes: ['DevFirmwareInstallProgress'],
+  intermediateTypes: ['DeviceFirmwareUpdateStatus'],
 };
 
 export const PROTOCOL_V2_FIRMWARE_UPDATE_RESPONSE_TYPES: (
   | 'Success'
-  | 'DevFirmwareUpdateStatus'
-)[] = ['Success', 'DevFirmwareUpdateStatus'];
+  | 'DeviceFirmwareUpdateStatus'
+)[] = ['Success', 'DeviceFirmwareUpdateStatus'];
 
 export const getProtocolV2UnknownErrorText = (error: unknown) => {
   if (!error) {
@@ -110,9 +118,7 @@ export const isProtocolV2DeviceDisconnectedError = (error: unknown) => {
     message.includes('connection has timed out unexpectedly') ||
     message.includes('connection error has occured') ||
     message.includes('connection error has occurred') ||
-    message.includes('transferIn') ||
-    message.includes('transferin') ||
-    message.includes('usbdevice') ||
+    message.includes('react native ble transport released') ||
     message.includes('multiplatformbleadapter') ||
     message.includes('multipalformebleadapter') ||
     compactMessage.includes('rxerrorerror6') ||
@@ -120,40 +126,55 @@ export const isProtocolV2DeviceDisconnectedError = (error: unknown) => {
   );
 };
 
-export function normalizeRebootType(value: RebootTypeInput | undefined): DevRebootType {
+export function normalizeRebootType(value: RebootTypeInput | undefined): DeviceRebootType {
   if (typeof value === 'number') return value;
   if (typeof value === 'string') {
     const numeric = Number(value);
     if (Number.isFinite(numeric)) return numeric;
-    if (value in DEV_REBOOT_TYPES) return DEV_REBOOT_TYPES[value];
+    if (value in DEVICE_REBOOT_TYPES) return DEVICE_REBOOT_TYPES[value];
   }
-  return DevRebootType.Normal;
+  return DeviceRebootType.Normal;
 }
 
-// 当前 firmware-pro2 子模块的 DevFirmwareTargetType 合法值。
-const VALID_FIRMWARE_TARGET_IDS = new Set<number>([0, 1, 2, 3, 4, 5, 6, 10]);
+// 与 firmware-pro2 的 proto_target_to_firmware_target 安装白名单保持一致。
+const INSTALLABLE_FIRMWARE_TARGET_IDS = new Set<number>([
+  ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_BOOTLOADER,
+  ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_APPLICATION_P1,
+  ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_APPLICATION_P2,
+  ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_COPROCESSOR,
+  ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE01,
+  ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE02,
+  ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE03,
+  ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE04,
+]);
+const FIRMWARE_TARGET_ID_BY_NAME = new Map<string, DeviceFirmwareTargetType>(
+  Object.entries(ProtocolV2FirmwareTargetType).flatMap(([key, value]) =>
+    INSTALLABLE_FIRMWARE_TARGET_IDS.has(value) ? [[key, value as DeviceFirmwareTargetType]] : []
+  )
+);
 
 function normalizeTargetId(
-  value: DevFirmwareTargetType | string | number | undefined,
+  value: DeviceFirmwareTargetType | string | number | undefined,
   name: string
-): DevFirmwareTargetType {
+): DeviceFirmwareTargetType {
   if (value === undefined || value === null) {
     throw invalidParameter(`Missing required parameter: ${name}`);
   }
-  const numeric = typeof value === 'number' ? value : Number(value);
-  // 校验值域：仅接受 DevFirmwareTargetType 中定义的 target id，
-  // 不再放行任意非负整数。
-  if (Number.isSafeInteger(numeric) && VALID_FIRMWARE_TARGET_IDS.has(numeric)) {
-    return numeric as DevFirmwareTargetType;
+  const named = typeof value === 'string' ? FIRMWARE_TARGET_ID_BY_NAME.get(value) : undefined;
+  const numeric = named ?? (typeof value === 'number' ? value : Number(value));
+  if (Number.isSafeInteger(numeric) && INSTALLABLE_FIRMWARE_TARGET_IDS.has(numeric)) {
+    return numeric as DeviceFirmwareTargetType;
   }
   throw invalidParameter(
-    `Parameter [${name}] must be a valid firmware target id (one of ${[
-      ...VALID_FIRMWARE_TARGET_IDS,
+    `Parameter [${name}] must be an installable firmware target id (one of ${[
+      ...INSTALLABLE_FIRMWARE_TARGET_IDS,
     ].join(', ')}).`
   );
 }
 
-export function normalizeFirmwareTargets(params: DeviceFirmwareUpdateParams): DevFirmwareTarget[] {
+export function normalizeFirmwareTargets(
+  params: DeviceFirmwareUpdateParams
+): DeviceFirmwareTarget[] {
   const targets =
     params.targets ??
     (params.path

package/src/api/scdo/ScdoGetAddress.ts

@@ -40,10 +40,6 @@ export default class ScdoGetAddress extends BaseMethod<HardwareScdoGetAddress[]>
 
   getVersionRange(): DeviceFirmwareRange {
     return {
-      pro2: {
-        min: '0.0.0',
-        unsupported: true,
-      },
       model_touch: {
         min: '4.10.0',
       },

package/src/api/scdo/ScdoSignMessage.ts

@@ -31,10 +31,6 @@ export default class ScdoSignMessage extends BaseMethod<HardwareScdoSignMessage>
 
   getVersionRange(): DeviceFirmwareRange {
     return {
-      pro2: {
-        min: '0.0.0',
-        unsupported: true,
-      },
       model_touch: {
         min: '4.10.0',
       },

package/src/api/scdo/ScdoSignTransaction.ts

@@ -53,10 +53,6 @@ export default class ScdoSignTransaction extends BaseMethod<HardwareScdoSignTx>
 
   getVersionRange(): DeviceFirmwareRange {
     return {
-      pro2: {
-        min: '0.0.0',
-        unsupported: true,
-      },
       model_touch: {
         min: '4.10.0',
       },