@onekeyfe/hd-core 1.2.0-alpha.99 → 1.2.1-alpha.0

package/src/api/firmware/FirmwareUpdatePlan.ts

@@ -328,8 +328,8 @@ export const assertFirmwareUpdatePlan = (value: unknown): FirmwareUpdatePlan =>
     }
     assertExactKeys(
       artifact,
-      ['artifactId', 'role', 'target', 'url', 'container', 'expectedSize', 'expectedSha256'],
-      ['logicalName', 'targetVersion']
+      ['artifactId', 'role', 'target', 'url', 'container'],
+      ['logicalName', 'expectedSize', 'expectedSha256', 'targetVersion']
     );
     const artifactId = assertBoundedString(artifact.artifactId, 'artifact id', 160);
     if (artifactIds.has(artifactId)) {
@@ -348,15 +348,25 @@ export const assertFirmwareUpdatePlan = (value: unknown): FirmwareUpdatePlan =>
     if (artifact.logicalName !== undefined) {
       assertBoundedString(artifact.logicalName, 'logical name', 256);
     }
-    if (!Number.isSafeInteger(artifact.expectedSize) || (artifact.expectedSize as number) <= 0) {
+    if (
+      artifact.expectedSize !== undefined &&
+      (!Number.isSafeInteger(artifact.expectedSize) || (artifact.expectedSize as number) <= 0)
+    ) {
       return planError('Firmware update plan artifact size is invalid');
     }
     if (
-      typeof artifact.expectedSha256 !== 'string' ||
-      !/^[a-f0-9]{64}$/u.test(artifact.expectedSha256)
+      artifact.expectedSha256 !== undefined &&
+      (typeof artifact.expectedSha256 !== 'string' ||
+        !/^[a-f0-9]{64}$/u.test(artifact.expectedSha256))
     ) {
       return planError('Firmware update plan artifact digest is invalid');
     }
+    if (
+      plan.executor === 'v4' &&
+      (artifact.expectedSize === undefined || artifact.expectedSha256 === undefined)
+    ) {
+      return planError('Protocol V2 firmware artifact integrity metadata is invalid');
+    }
     if (artifact.targetVersion !== undefined) {
       assertBoundedString(artifact.targetVersion, 'target version', 64);
     }
@@ -644,47 +654,6 @@ const finalizeFirmwareUpdatePlan = ({
   });
 };
 
-export type ProtocolV2LocalFirmwareUpdatePlanArtifact = {
-  artifactId: string;
-  target: Exclude<FirmwareUpdateV4Target, 'boot_resources'>;
-  container: 'raw' | 'zip';
-  logicalName: string;
-  expectedSize: number;
-  expectedSha256: string;
-  targetVersion?: string;
-};
-
-export const buildProtocolV2LocalFirmwareUpdatePlan = ({
-  features,
-  firmwareType,
-  platform,
-  artifacts,
-}: {
-  features: Features;
-  firmwareType: EFirmwareType;
-  platform: FirmwareUpdatePlatform;
-  artifacts: ProtocolV2LocalFirmwareUpdatePlanArtifact[];
-}): FirmwareUpdatePlan => {
-  if (artifacts.length === 0) {
-    return planError('Protocol V2 local firmware plan has no artifacts');
-  }
-  const plan = finalizeFirmwareUpdatePlan({
-    features,
-    firmwareType,
-    platform,
-    artifacts: artifacts.map(artifact => ({
-      ...artifact,
-      role: artifact.target === 'resource' ? 'resourceBundle' : 'component',
-      url: `https://local-firmware.invalid/${encodeURIComponent(artifact.artifactId)}`,
-    })),
-    targetsToUpdate: artifacts.map(artifact => artifact.target),
-  });
-  if (plan.executor !== 'v4') {
-    return planError('Protocol V2 local firmware plan requires executor v4');
-  }
-  return plan;
-};
-
 export const buildProtocolV2FirmwareUpdatePlan = ({
   features,
   firmwareType,
@@ -822,13 +791,10 @@ export const buildFirmwareUpdatePlan = ({
   } else {
     if (isUpgrade(bootloader) || forcedTargets.has('bootloader')) {
       const bootloaderRelease = asRelease(bootloader);
-      const integrity = requireArtifactIntegrity(
-        {
-          size: bootloaderRelease?.bootloaderExpectedSize,
-          sha256: bootloaderRelease?.bootloaderFingerprint,
-        },
-        'Bootloader release'
-      );
+      const integrity = asIntegrity({
+        size: bootloaderRelease?.bootloaderExpectedSize,
+        sha256: bootloaderRelease?.bootloaderFingerprint,
+      });
       artifacts.push({
         artifactId: 'bootloader',
         role: 'bootloader',
@@ -850,10 +816,10 @@ export const buildFirmwareUpdatePlan = ({
         });
       }
       if (shouldUpdateFirmware) {
-        const integrity = requireArtifactIntegrity(
-          { size: firmwareRelease.expectedSize, sha256: firmwareRelease.fingerprint },
-          'Firmware release'
-        );
+        const integrity = asIntegrity({
+          size: firmwareRelease.expectedSize,
+          sha256: firmwareRelease.fingerprint,
+        });
         artifacts.push({
           artifactId: 'firmware',
           role: 'firmware',
@@ -873,19 +839,16 @@ export const buildFirmwareUpdatePlan = ({
           platform,
         });
         if (resourceUrl) {
-          const integrity = requireArtifactIntegrity(
-            {
-              size:
-                resourceUrl === asString(firmwareRelease.fullResource)
-                  ? firmwareRelease.fullResourceExpectedSize
-                  : firmwareRelease.resourceExpectedSize,
-              sha256:
-                resourceUrl === asString(firmwareRelease.fullResource)
-                  ? firmwareRelease.fullResourceFingerprint
-                  : firmwareRelease.resourceFingerprint,
-            },
-            'Legacy resource archive'
-          );
+          const integrity = asIntegrity({
+            size:
+              resourceUrl === asString(firmwareRelease.fullResource)
+                ? firmwareRelease.fullResourceExpectedSize
+                : firmwareRelease.resourceExpectedSize,
+            sha256:
+              resourceUrl === asString(firmwareRelease.fullResource)
+                ? firmwareRelease.fullResourceFingerprint
+                : firmwareRelease.resourceFingerprint,
+          });
           artifacts.push({
             artifactId: 'resource',
             role: 'resource',
@@ -899,13 +862,10 @@ export const buildFirmwareUpdatePlan = ({
     }
     if (isUpgrade(ble) || isRecoveryInstall(ble) || forcedTargets.has('ble')) {
       const bleRelease = asRelease(ble);
-      const integrity = requireArtifactIntegrity(
-        {
-          size: bleRelease?.expectedSize,
-          sha256: bleRelease?.fingerprintWeb ?? bleRelease?.fingerprint,
-        },
-        'BLE release'
-      );
+      const integrity = asIntegrity({
+        size: bleRelease?.expectedSize,
+        sha256: bleRelease?.fingerprintWeb ?? bleRelease?.fingerprint,
+      });
       artifacts.push({
         artifactId: 'ble',
         role: 'ble',

package/src/api/firmware/FirmwareUpdatePreparedPlan.ts

@@ -71,6 +71,13 @@ export const getFirmwareUpdateResourceName = (value: unknown): string => {
   return resourceName;
 };
 
+const getPreparedEntryIdentity = (entryName: unknown): string => {
+  getFirmwareUpdateResourceName(entryName);
+  // Protocol V2 resource ZIPs can ship the same basename from different
+  // directories, such as rom/params.okpkg and bootloader/params.okpkg.
+  return (entryName as string).toLowerCase();
+};
+
 const assertPreparedEntry = (value: unknown): FirmwareUpdatePreparedEntry => {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     return preparedPlanError('Firmware prepared plan entry must be an object');
@@ -141,11 +148,8 @@ const assertPreparedArtifacts = ({
     }
     if (
       materializedEntries &&
-      new Set(
-        materializedEntries.map(entry =>
-          getFirmwareUpdateResourceName(entry.entryName).toLowerCase()
-        )
-      ).size !== materializedEntries.length
+      new Set(materializedEntries.map(entry => getPreparedEntryIdentity(entry.entryName))).size !==
+        materializedEntries.length
     ) {
       return preparedPlanError('Firmware prepared plan contains duplicate entry names');
     }
@@ -281,7 +285,7 @@ export const validateFirmwareUpdatePreparedPlan = (value: unknown): FirmwareUpda
     const materializedEntryNames =
       artifact.materializedEntries?.map(entry => {
         assertPreparedEntry(entry);
-        return getFirmwareUpdateResourceName(entry.entryName).toLowerCase();
+        return getPreparedEntryIdentity(entry.entryName);
       }) ?? [];
     if (new Set(materializedEntryNames).size !== materializedEntryNames.length) {
       return preparedPlanError('Firmware prepared plan contains duplicate entry names');

package/src/api/firmware/protocolV2Release.ts

@@ -77,11 +77,16 @@ export async function loadProtocolV2FirmwareReleaseContext({
   }
 
   const firmwareType = firmwareTypeParam ?? state.identity.firmwareType ?? EFirmwareType.Universal;
+  const normalizedFeatures: Features = {
+    ...features,
+    deviceType: state.identity.deviceType,
+    firmwareType,
+  };
   return {
     state: state as ProtocolV2FirmwareReleaseContext['state'],
-    features,
+    features: normalizedFeatures,
     firmwareType,
-    release: DataManager.getFirmwareLatestRelease(features, firmwareType),
+    release: DataManager.getFirmwareLatestRelease(normalizedFeatures, firmwareType),
   };
 }
 

package/src/api/helpers/base64Data.ts

@@ -0,0 +1,85 @@
+import { Buffer } from 'buffer';
+import { decode as decodeJpeg } from 'jpeg-js';
+
+import { invalidParameter } from './filesystemValidation';
+
+const BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+const JPEG_CONTAINER_OVERHEAD_BYTES = 64 * 1024;
+const JPEG_MAX_MEMORY_USAGE_IN_MB = 32;
+const JPEG_MAX_RESOLUTION_IN_MP = 1;
+
+export function decodeCanonicalBase64({
+  value,
+  parameterName,
+  maxBytes,
+}: {
+  value: unknown;
+  parameterName: string;
+  maxBytes: number;
+}): Uint8Array {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw invalidParameter(`Parameter [${parameterName}] must be a non-empty Base64 string.`);
+  }
+  if (value.length > Math.ceil(maxBytes / 3) * 4) {
+    throw invalidParameter(`Parameter [${parameterName}] exceeds the maximum supported size.`);
+  }
+  if (value.length % 4 !== 0 || !BASE64_PATTERN.test(value)) {
+    throw invalidParameter(`Parameter [${parameterName}] must use canonical Base64 encoding.`);
+  }
+
+  const decoded = Buffer.from(value, 'base64');
+  if (decoded.byteLength === 0 || decoded.byteLength > maxBytes) {
+    throw invalidParameter(`Parameter [${parameterName}] exceeds the maximum supported size.`);
+  }
+  if (decoded.toString('base64') !== value) {
+    throw invalidParameter(`Parameter [${parameterName}] must use canonical Base64 encoding.`);
+  }
+  return Uint8Array.from(decoded);
+}
+
+export function decodeJpegBase64ToRgba({
+  jpegBase64,
+  parameterName,
+  expectedWidth,
+  expectedHeight,
+}: {
+  jpegBase64: unknown;
+  parameterName: string;
+  expectedWidth: number;
+  expectedHeight: number;
+}): { width: number; height: number; data: Uint8Array } {
+  const jpegBytes = decodeCanonicalBase64({
+    value: jpegBase64,
+    parameterName,
+    maxBytes: expectedWidth * expectedHeight * 8 + JPEG_CONTAINER_OVERHEAD_BYTES,
+  });
+  if (jpegBytes[0] !== 0xff || jpegBytes[1] !== 0xd8) {
+    throw invalidParameter(`Parameter [${parameterName}] must contain a JPEG image.`);
+  }
+
+  let decoded: { width: number; height: number; data: Uint8Array };
+  try {
+    decoded = decodeJpeg(jpegBytes, {
+      useTArray: true,
+      formatAsRGBA: true,
+      tolerantDecoding: false,
+      maxResolutionInMP: JPEG_MAX_RESOLUTION_IN_MP,
+      maxMemoryUsageInMB: JPEG_MAX_MEMORY_USAGE_IN_MB,
+    });
+  } catch {
+    throw invalidParameter(`Parameter [${parameterName}] must contain a valid JPEG image.`);
+  }
+
+  if (decoded.width !== expectedWidth || decoded.height !== expectedHeight) {
+    throw invalidParameter(
+      `Parameter [${parameterName}] must contain a ${expectedWidth}x${expectedHeight} JPEG image.`
+    );
+  }
+  const expectedLength = expectedWidth * expectedHeight * 4;
+  if (decoded.data.byteLength !== expectedLength) {
+    throw invalidParameter(
+      `Decoded parameter [${parameterName}] must contain ${expectedLength} RGBA bytes.`
+    );
+  }
+  return decoded;
+}

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

@@ -25,7 +25,7 @@ export default class DeviceFactoryInfoSet extends BaseMethod<DeviceFactoryInfoSe
       info: {
         version: this.params.version,
         serial_number: this.params.serial_number,
-        burn_in_completed: this.params.burn_in_completed,
+        factory_burn_in_completed: this.params.burn_in_completed,
         factory_test_completed: this.params.factory_test_completed,
         manufacture_time: this.params.manufacture_time,
       },

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

@@ -1,14 +1,6 @@
 import { BaseMethod } from '../BaseMethod';
-import {
-  PROTOCOL_V2_FIRMWARE_UPDATE_OPTIONS,
-  PROTOCOL_V2_FIRMWARE_UPDATE_RESPONSE_TYPES,
-  isProtocolV2DeviceDisconnectedError,
-  normalizeFirmwareTargets,
-} from './helpers';
-import { UI_REQUEST, createUiMessage } from '../../events/ui-request';
+import { isProtocolV2DeviceDisconnectedError, normalizeFirmwareTargets } from './helpers';
 
-import type { KnownDevice } from '../../types';
-import type { MessageFromOneKey } from '@onekeyfe/hd-transport';
 import type { DeviceFirmwareUpdateParams } from './helpers';
 
 export default class DeviceFirmwareUpdate extends BaseMethod<DeviceFirmwareUpdateParams> {
@@ -31,27 +23,13 @@ export default class DeviceFirmwareUpdate extends BaseMethod<DeviceFirmwareUpdat
   async run() {
     const targets = normalizeFirmwareTargets(this.params);
     try {
-      const res = await this.device.commands.typedCall(
+      await this.device.commands.typedCall('DeviceFirmwareUpdateStage', 'Success', { targets });
+      await this.device.commands.call(
         'DeviceFirmwareUpdateRequest',
-        PROTOCOL_V2_FIRMWARE_UPDATE_RESPONSE_TYPES,
-        {
-          targets,
-        },
-        {
-          ...PROTOCOL_V2_FIRMWARE_UPDATE_OPTIONS,
-          onIntermediateResponse: (response: MessageFromOneKey) => {
-            if (response.type !== 'DeviceFirmwareUpdateStatus') return;
-            this.postMessage(
-              createUiMessage(UI_REQUEST.FIRMWARE_PROGRESS, {
-                device: this.device.toMessageObject() as KnownDevice,
-                progress: 99,
-                progressType: 'installingFirmware',
-              })
-            );
-          },
-        }
+        {},
+        { returnAfterWrite: true }
       );
-      return res.message;
+      return { message: 'Device firmware update started' };
     } catch (error) {
       if (isProtocolV2DeviceDisconnectedError(error)) {
         return {

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

@@ -4,7 +4,13 @@ import { invalidParameter } from '../helpers/filesystemValidation';
 import type { DeviceFirmwareUpdateStatusGetParams } from './helpers';
 import type { DeviceFirmwareUpdateRecordFields } from '@onekeyfe/hd-transport';
 
-const DEVICE_FIRMWARE_UPDATE_STATUS_FIELDS = ['status', 'payload_version', 'path'] as const;
+const DEVICE_FIRMWARE_UPDATE_STATUS_FIELDS = [
+  'status',
+  'progress_percent',
+  'phase_info',
+  'payload_version',
+  'path',
+] as const;
 
 function normalizeStatusFields(
   fields: DeviceFirmwareUpdateStatusGetParams['fields']

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

@@ -5,7 +5,7 @@ import { invalidParameter } from '../helpers/filesystemValidation';
 
 export type DeviceInfoGetTargets = {
   hw?: boolean;
-  fw?: boolean;
+  main_mcu?: boolean;
   coprocessor?: boolean;
   se1?: boolean;
   se2?: boolean;
@@ -27,7 +27,7 @@ export type DeviceInfoGetParams = {
 
 const TARGET_KEYS: (keyof DeviceInfoGetTargets)[] = [
   'hw',
-  'fw',
+  'main_mcu',
   'coprocessor',
   'se1',
   'se2',
@@ -39,7 +39,7 @@ const TYPE_KEYS: (keyof DeviceInfoGetTypes)[] = ['version', 'build_id', 'hash',
 
 const DEFAULT_TARGETS: DeviceInfoGetTargets = {
   hw: true,
-  fw: true,
+  main_mcu: true,
   coprocessor: true,
 };
 

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

@@ -1,3 +1,5 @@
+import { DeviceSessionPinType } from '@onekeyfe/hd-transport';
+
 import { BaseMethod } from '../BaseMethod';
 import { normalizeRebootType } from './helpers';
 
@@ -11,6 +13,9 @@ export default class DeviceReboot extends BaseMethod<DeviceRebootParams> {
   init() {
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
+    this.unlockPolicy = 'unlock-before-run';
+    // Device-management action: main PIN or Attach PIN may authorize reboot.
+    this.protocolV2PreUnlockPinType = DeviceSessionPinType.Any;
     this.params = {
       rebootType: this.payload.rebootType,
       reboot_type: this.payload.reboot_type,

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

@@ -1,4 +1,5 @@
 import { ERRORS, HardwareErrorCode, createDeviceNotSupportMethodError } from '@onekeyfe/hd-shared';
+import { DeviceSessionPinType } from '@onekeyfe/hd-transport';
 
 import { UI_REQUEST, createUiMessage } from '../../events/ui-request';
 import { supportsProtocolV2Message } from '../../protocols/protocol-v2/features';
@@ -7,21 +8,26 @@ import {
   PRO2_NFT_DEFAULT_PACE_MS,
   PRO2_NFT_DEFAULT_TIMEOUT_MS,
   PRO2_NFT_DIRECTORY,
+  PRO2_NFT_IMAGE_HEIGHT,
+  PRO2_NFT_IMAGE_WIDTH,
   PRO2_NFT_MAX_CHUNK_SIZE,
   PRO2_NFT_MAX_ITEMS,
   PRO2_NFT_MIN_CHUNK_SIZE,
+  PRO2_NFT_THUMBNAIL_HEIGHT,
+  PRO2_NFT_THUMBNAIL_WIDTH,
   type Pro2NftBundle,
-  type Pro2NftImage,
-  buildPro2NftBundle,
+  buildPro2NftBundleFromEncodedImages,
   getCompletePro2NftBasenames,
 } from '../../utils/pro2Nft';
+import { encodePro2Image } from '../../utils/pro2Wallpaper';
 import { BaseMethod } from '../BaseMethod';
+import { decodeJpegBase64ToRgba } from '../helpers/base64Data';
 import { invalidParameter } from '../helpers/filesystemValidation';
 import { writeProtocolV2File } from '../helpers/protocolV2FileWrite';
 
 export type DeviceUploadNftParams = {
-  image: Pro2NftImage;
-  thumbnail: Pro2NftImage;
+  imageJpegBase64: string;
+  thumbnailJpegBase64: string;
   title: string;
   subtitle: string;
   timestampMs?: number;
@@ -54,8 +60,8 @@ export default class DeviceUploadNft extends BaseMethod<DeviceUploadNftParams> {
 
   init() {
     const {
-      image,
-      thumbnail,
+      imageJpegBase64,
+      thumbnailJpegBase64,
       title,
       subtitle,
       timestampMs = Date.now(),
@@ -79,9 +85,55 @@ export default class DeviceUploadNft extends BaseMethod<DeviceUploadNftParams> {
       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';
+    const encodedImage = (() => {
+      const decoded = decodeJpegBase64ToRgba({
+        jpegBase64: imageJpegBase64,
+        parameterName: 'imageJpegBase64',
+        expectedWidth: PRO2_NFT_IMAGE_WIDTH,
+        expectedHeight: PRO2_NFT_IMAGE_HEIGHT,
+      });
+      return encodePro2Image({
+        width: PRO2_NFT_IMAGE_WIDTH,
+        height: PRO2_NFT_IMAGE_HEIGHT,
+        rgba: decoded.data,
+        alphaMode: 'black-background',
+      }).data;
+    })();
+    const encodedThumbnail = (() => {
+      const decoded = decodeJpegBase64ToRgba({
+        jpegBase64: thumbnailJpegBase64,
+        parameterName: 'thumbnailJpegBase64',
+        expectedWidth: PRO2_NFT_THUMBNAIL_WIDTH,
+        expectedHeight: PRO2_NFT_THUMBNAIL_HEIGHT,
+      });
+      return encodePro2Image({
+        width: PRO2_NFT_THUMBNAIL_WIDTH,
+        height: PRO2_NFT_THUMBNAIL_HEIGHT,
+        rgba: decoded.data,
+        alphaMode: 'black-background',
+      }).data;
+    })();
+    this.bundle = buildPro2NftBundleFromEncodedImages({
+      image: encodedImage,
+      thumbnail: encodedThumbnail,
+      title,
+      subtitle,
+      timestampMs,
+    });
+    this.params = {
+      imageJpegBase64,
+      thumbnailJpegBase64,
+      title,
+      subtitle,
+      timestampMs,
+      chunkSize,
+      paceMs,
+      timeoutMs,
+    };
+    this.unlockPolicy = 'unlock-before-run';
+    // File writes and NftUpdate require an unlocked device. Either PIN may
+    // authorize this device-management action.
+    this.protocolV2PreUnlockPinType = DeviceSessionPinType.Any;
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
   }

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

@@ -1,10 +1,15 @@
 import { blake2s } from '@noble/hashes/blake2s';
 import { bytesToHex } from '@noble/hashes/utils';
+import { createDeviceNotSupportMethodError } from '@onekeyfe/hd-shared';
+import { DeviceSessionPinType } from '@onekeyfe/hd-transport';
 
 import { BaseMethod } from '../BaseMethod';
+import { decodeJpegBase64ToRgba } from '../helpers/base64Data';
 import { invalidParameter } from '../helpers/filesystemValidation';
 import { writeProtocolV2File } from '../helpers/protocolV2FileWrite';
 import { UI_REQUEST, createUiMessage } from '../../events/ui-request';
+import { supportsProtocolV2Message } from '../../protocols/protocol-v2/features';
+import { LoggerNames, getLogger } from '../../utils';
 import {
   PRO2_WALLPAPER_HEIGHT,
   PRO2_WALLPAPER_WIDTH,
@@ -13,9 +18,7 @@ import {
 } from '../../utils/pro2Wallpaper';
 
 export type DeviceUploadWallpaperParams = {
-  width: number;
-  height: number;
-  rgba: Uint8Array | ArrayBuffer;
+  jpegBase64: string;
   fileName?: string;
   chunkSize?: number;
 };
@@ -29,6 +32,10 @@ export type DeviceUploadWallpaperResponse = {
 
 const WALLPAPER_DIRECTORY = 'vol1:/wallpapers';
 const SAFE_FILE_NAME = /^[A-Za-z0-9_-]+(?:\.bin)?$/;
+const DEVICE_SETTINGS_SET_MESSAGE_TYPE = 60412;
+const FILESYSTEM_FILE_WRITE_MESSAGE_TYPE = 60805;
+const FILESYSTEM_DIR_MAKE_MESSAGE_TYPE = 60809;
+const Log = getLogger(LoggerNames.Method);
 
 function normalizeFileName(fileName: string | undefined, data: Uint8Array): string {
   if (fileName !== undefined && (!fileName || !SAFE_FILE_NAME.test(fileName))) {
@@ -54,31 +61,48 @@ export default class DeviceUploadWallpaper extends BaseMethod<DeviceUploadWallpa
   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.');
-    }
+    const { jpegBase64, fileName, chunkSize } = this.payload;
     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 });
+    const decoded = decodeJpegBase64ToRgba({
+      jpegBase64,
+      parameterName: 'jpegBase64',
+      expectedWidth: PRO2_WALLPAPER_WIDTH,
+      expectedHeight: PRO2_WALLPAPER_HEIGHT,
+    });
+    this.encoded = encodePro2Wallpaper({
+      width: PRO2_WALLPAPER_WIDTH,
+      height: PRO2_WALLPAPER_HEIGHT,
+      rgba: decoded.data,
+    });
     this.path = `${WALLPAPER_DIRECTORY}/${normalizeFileName(fileName, this.encoded.data)}`;
-    this.params = { width, height, rgba: rgbaBytes, fileName, chunkSize };
-    this.unlockPolicy = 'none';
+    this.params = { jpegBase64, fileName, chunkSize };
+    this.unlockPolicy = 'unlock-before-run';
+    // File writes and wallpaper apply require an unlocked device. Either PIN
+    // may authorize this device-management action.
+    this.protocolV2PreUnlockPinType = DeviceSessionPinType.Any;
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
   }
 
+  private async assertCapabilities() {
+    const protocolInfo = await this.device.ensureProtocolV2RuntimeContext();
+    const requiredMessageTypes = [
+      DEVICE_SETTINGS_SET_MESSAGE_TYPE,
+      FILESYSTEM_FILE_WRITE_MESSAGE_TYPE,
+      FILESYSTEM_DIR_MAKE_MESSAGE_TYPE,
+    ];
+    if (
+      requiredMessageTypes.some(
+        messageType => !supportsProtocolV2Message(protocolInfo, messageType)
+      )
+    ) {
+      throw createDeviceNotSupportMethodError(this.name, this.device.getCurrentFirmwareType());
+    }
+  }
+
   private async ensureDirectory() {
     if (this.directoryReady) return;
     try {
@@ -119,11 +143,21 @@ export default class DeviceUploadWallpaper extends BaseMethod<DeviceUploadWallpa
   async run(): Promise<DeviceUploadWallpaperResponse> {
     const { encoded } = this;
     if (!encoded) throw invalidParameter('Wallpaper data has not been initialized.');
+    await this.assertCapabilities();
     await this.ensureDirectory();
     await this.upload();
     const response = await this.device.commands.typedCall('DeviceSettingsSet', 'Success', {
       settings: { wallpaper_path: this.path },
     });
+    try {
+      await this.device.refreshProtocolV2SettingsAfterMutation();
+    } catch (error) {
+      // The wallpaper is already applied. A transient read-back failure must not
+      // make callers retry the completed file upload.
+      Log.warn('Protocol V2 wallpaper settings refresh failed after apply', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
     return {
       path: this.path,
       size: encoded.data.byteLength,

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

@@ -1,4 +1,5 @@
 import { DeviceRebootType } from '@onekeyfe/hd-transport';
+import { HardwareErrorCode } from '@onekeyfe/hd-shared';
 
 import { invalidParameter, validateNonEmptyString } from '../helpers/filesystemValidation';
 import { ProtocolV2FirmwareTargetType } from '../../protocols/protocol-v2/firmware';
@@ -103,6 +104,13 @@ export const getProtocolV2UnknownErrorText = (error: unknown) => {
 };
 
 export const isProtocolV2DeviceDisconnectedError = (error: unknown) => {
+  const errorCode =
+    error && typeof error === 'object'
+      ? (error as { errorCode?: number; code?: number }).errorCode ??
+        (error as { errorCode?: number; code?: number }).code
+      : undefined;
+  if (errorCode === HardwareErrorCode.BleDeviceDisconnected) return true;
+
   const message = getProtocolV2UnknownErrorText(error).toLowerCase();
   const compactMessage = message.replace(/\s+/g, '');
   return (