@onekeyfe/hd-core 1.2.0-alpha.81 → 1.2.0-alpha.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hd-core",
-  "version": "1.2.0-alpha.81",
+  "version": "1.2.0-alpha.84",
   "description": "Core processes and APIs for communicating with OneKey hardware devices.",
   "author": "OneKey",
   "homepage": "https://github.com/OneKeyHQ/hardware-js-sdk#readme",
@@ -25,8 +25,8 @@
     "url": "https://github.com/OneKeyHQ/hardware-js-sdk/issues"
   },
   "dependencies": {
-    "@onekeyfe/hd-shared": "1.2.0-alpha.81",
-    "@onekeyfe/hd-transport": "1.2.0-alpha.81",
+    "@onekeyfe/hd-shared": "1.2.0-alpha.84",
+    "@onekeyfe/hd-transport": "1.2.0-alpha.84",
     "axios": "1.15.2",
     "bignumber.js": "^9.0.2",
     "bytebuffer": "^5.0.1",
@@ -44,5 +44,5 @@
     "@types/w3c-web-usb": "^1.0.10",
     "@types/web-bluetooth": "^0.0.21"
   },
-  "gitHead": "8f6b4dca4ab97dc0a83f7ace61c24a0f0e193016"
+  "gitHead": "577746142ef64d2c97de487c7a9cc8a5a0422e0b"
 }

package/src/api/CheckAllFirmwareRelease.ts

@@ -11,7 +11,9 @@ import {
 } from './firmware/releaseHelper';
 import {
   buildFirmwareUpdatePlan,
+  buildProtocolV2FirmwareUpdatePlan,
   validateFirmwareUpdatePlanForceTargets,
+  validateProtocolV2FirmwareUpdateTargets,
 } from './firmware/FirmwareUpdatePlan';
 import {
   PROTOCOL_V2_BLE_TARGETS,
@@ -26,6 +28,7 @@ import { getBridgeReleaseInfo } from '../utils/bridgeUpdate';
 import {
   LoggerNames,
   getDeviceFirmwareVersion,
+  getDeviceSerialNo,
   getDeviceType,
   getFirmwareType,
   getLogger,
@@ -384,8 +387,17 @@ export default class CheckAllFirmwareRelease extends BaseMethod {
   }
 
   private async runProtocolV2(): Promise<AllFirmwareRelease> {
-    const { checkFirmwareHash = false, firmwareType: firmwareTypeParam } = this
-      .payload as CheckAllFirmwareReleaseParams;
+    const {
+      checkFirmwareHash = false,
+      firmwareType: firmwareTypeParam,
+      platform,
+      forceUpdateTargets,
+      protocolV2ForceUpdateTargets,
+    } = this.payload as CheckAllFirmwareReleaseParams;
+    const validatedForceUpdateTargets = validateFirmwareUpdatePlanForceTargets(forceUpdateTargets);
+    const validatedProtocolV2ForceUpdateTargets = validateProtocolV2FirmwareUpdateTargets(
+      protocolV2ForceUpdateTargets
+    );
     const { state, features, firmwareType, release } = await loadProtocolV2FirmwareReleaseContext({
       device: this.device,
       firmwareType: firmwareTypeParam,
@@ -405,12 +417,70 @@ export default class CheckAllFirmwareRelease extends BaseMethod {
     const resourceSource = DataManager.getProtocolV2ResourceSource(resourceDeviceType);
     const resourceStatus = 'unknown' as const;
     const resourcePreparationRequired = !!resourceSource;
+    const detectedComponentTargets = validatedForceUpdateTargets.includes('firmware')
+      ? plan.components.flatMap(component =>
+          component.updateTarget ? [component.updateTarget] : []
+        )
+      : plan.targetsToUpdate;
+    const componentTargetsToUpdate = Array.from(
+      new Set([
+        ...detectedComponentTargets,
+        ...validatedProtocolV2ForceUpdateTargets.filter(target => target !== 'resource'),
+      ])
+    );
+    const forceResourceUpdate =
+      validatedForceUpdateTargets.includes('resource') ||
+      validatedProtocolV2ForceUpdateTargets.includes('resource');
     const targetsToUpdate = Array.from(
       new Set([
-        ...plan.targetsToUpdate,
-        ...(resourcePreparationRequired ? (['resource'] as const) : []),
+        ...componentTargetsToUpdate,
+        ...(resourcePreparationRequired || forceResourceUpdate ? (['resource'] as const) : []),
       ])
     );
+    let firmwareUpdatePlan: FirmwareUpdatePlan | undefined;
+    try {
+      const shouldBuildFirmwareUpdatePlan =
+        componentTargetsToUpdate.length > 0 ||
+        validatedForceUpdateTargets.some(target => target !== 'resource') ||
+        validatedProtocolV2ForceUpdateTargets.some(target => target !== 'resource') ||
+        (forceResourceUpdate && !resourcePreparationRequired);
+      const requestedPlatform = platform ?? 'web';
+      const requiresDeviceIdentity =
+        requestedPlatform === 'native' || requestedPlatform === 'desktop';
+      const canBindPreparedPlan = !requiresDeviceIdentity || !!getDeviceSerialNo(features);
+      if (shouldBuildFirmwareUpdatePlan) {
+        const validatedPlan = buildProtocolV2FirmwareUpdatePlan({
+          features,
+          firmwareType,
+          platform: canBindPreparedPlan ? requestedPlatform : 'web',
+          release,
+          targetsToUpdate,
+          forceUpdateTargets: validatedForceUpdateTargets,
+          resourceArchiveAvailable: resourcePreparationRequired,
+        });
+        firmwareUpdatePlan = canBindPreparedPlan ? validatedPlan : undefined;
+        if (!canBindPreparedPlan) {
+          Log.warn(
+            '[CheckAllFirmwareRelease] Protocol V2 device identity is unavailable; using the release result without a prepared Plan'
+          );
+        }
+      } else {
+        firmwareUpdatePlan = undefined;
+      }
+    } catch (error) {
+      if (
+        validatedForceUpdateTargets.length > 0 ||
+        validatedProtocolV2ForceUpdateTargets.length > 0 ||
+        !(error instanceof HardwareError) ||
+        error.params?.firmwareUpdateCode !== 'FirmwarePlanInvalid'
+      ) {
+        throw error;
+      }
+      Log.warn(
+        '[CheckAllFirmwareRelease] Optional Protocol V2 firmware Plan is unavailable; using the release result'
+      );
+      firmwareUpdatePlan = undefined;
+    }
     const firmwarePlan = summarizeProtocolV2FirmwareRelease(
       plan,
       PROTOCOL_V2_MAIN_FIRMWARE_TARGETS
@@ -442,8 +512,9 @@ export default class CheckAllFirmwareRelease extends BaseMethod {
       resourceStatus,
       resourceArchive: resourceSource,
       resourcePreparationRequired,
-      hasUpgrade: plan.hasUpgrade || resourcePreparationRequired,
+      hasUpgrade: targetsToUpdate.length > 0,
       targetsToUpdate,
+      firmwareUpdatePlan,
     };
   }
 }

package/src/api/CheckBLEFirmwareRelease.ts

@@ -1,5 +1,3 @@
-import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
-
 import { BaseMethod } from './BaseMethod';
 import { UI_REQUEST } from '../constants/ui-request';
 import { getBleFirmwareReleaseInfo } from './firmware/releaseHelper';
@@ -28,6 +26,8 @@ export default class CheckBLEFirmwareRelease extends BaseMethod {
   }
 
   async run() {
+    if (!this.device.features) return null;
+
     if (this.device.isProtocolV2()) {
       const { state, firmwareType, release } = await loadProtocolV2FirmwareReleaseContext({
         device: this.device,
@@ -49,13 +49,7 @@ export default class CheckBLEFirmwareRelease extends BaseMethod {
       });
     }
 
-    if (this.device.features) {
-      const releaseInfo = getBleFirmwareReleaseInfo(this.device.features);
-      return releaseInfo;
-    }
-    throw ERRORS.TypedError(
-      HardwareErrorCode.RuntimeError,
-      'checkBLEFirmwareRelease requires initialized device features'
-    );
+    const releaseInfo = getBleFirmwareReleaseInfo(this.device.features);
+    return releaseInfo;
   }
 }

package/src/api/CheckBootloaderRelease.ts

@@ -1,5 +1,3 @@
-import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
-
 import { BaseMethod } from './BaseMethod';
 import { UI_REQUEST } from '../constants/ui-request';
 import { getBootloaderReleaseInfo } from './firmware/releaseHelper';
@@ -26,12 +24,7 @@ export default class CheckBootloaderRelease extends BaseMethod {
   }
 
   async run() {
-    if (!this.device.features) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        'checkBootloaderRelease requires initialized device features'
-      );
-    }
+    if (!this.device.features) return null;
     const { features } = this.device;
     const payload = this.payload as CheckBootloaderReleaseParams;
 

package/src/api/CheckFirmwareRelease.ts

@@ -1,5 +1,3 @@
-import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
-
 import { BaseMethod } from './BaseMethod';
 import { UI_REQUEST } from '../constants/ui-request';
 import { getFirmwareReleaseInfo } from './firmware/releaseHelper';
@@ -31,6 +29,8 @@ export default class CheckFirmwareRelease extends BaseMethod {
   async run() {
     const payload = this.payload as CheckFirmwareReleaseParams;
 
+    if (!this.device.features) return null;
+
     if (this.device.isProtocolV2()) {
       const { state, firmwareType, release } = await loadProtocolV2FirmwareReleaseContext({
         device: this.device,
@@ -49,16 +49,10 @@ export default class CheckFirmwareRelease extends BaseMethod {
       return toProtocolV2FirmwareReleaseInfo({ plan, state, release });
     }
 
-    if (this.device.features) {
-      const deviceFirmwareType = this.device.getCurrentFirmwareType();
-      const firmwareType = payload.firmwareType ?? deviceFirmwareType;
+    const deviceFirmwareType = this.device.getCurrentFirmwareType();
+    const firmwareType = payload.firmwareType ?? deviceFirmwareType;
 
-      const releaseInfo = getFirmwareReleaseInfo(this.device.features, firmwareType);
-      return releaseInfo;
-    }
-    throw ERRORS.TypedError(
-      HardwareErrorCode.RuntimeError,
-      'checkFirmwareRelease requires initialized device features'
-    );
+    const releaseInfo = getFirmwareReleaseInfo(this.device.features, firmwareType);
+    return releaseInfo;
   }
 }

package/src/api/FirmwareUpdateV4.ts

@@ -683,7 +683,14 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
       resourceBundles = this.prepareExplicitProtocolV2ResourceFiles();
       fwBinaryMap = this.collectExplicitTargetBinaries();
       bootloaderBinary = this.prepareBootloaderBinary();
-      const needsRemoteFirmware = !this.hasExplicitProtocolV2Payload(fwBinaryMap);
+      const explicitInstallItems = this.buildProtocolV2InstallItems({
+        bootloaderBinary,
+        fwBinaryMap,
+      });
+      const missingFirmwareTargets = this.getMissingProtocolV2FirmwareTargets(explicitInstallItems);
+      const needsRemoteFirmware = this.params.targetsToUpdate?.length
+        ? missingFirmwareTargets.length > 0
+        : !this.hasExplicitProtocolV2Payload(explicitInstallItems);
       if (needsPreparedResources) {
         throw ERRORS.TypedError(
           HardwareErrorCode.RuntimeError,
@@ -713,7 +720,8 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
       if (needsRemoteFirmware) {
         const remoteBinaries = await this.prepareRemoteProtocolV2Binaries(
           firmwareType,
-          deviceFeatures
+          deviceFeatures,
+          explicitInstallItems
         );
         bootloaderBinary = remoteBinaries.bootloaderBinary;
         fwBinaryMap = remoteBinaries.fwBinaryMap;
@@ -1110,11 +1118,19 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     return this.params.bootloaderBinary ?? null;
   }
 
-  private hasExplicitProtocolV2Payload(fwBinaryMap: ProtocolV2TargetBinary[]) {
-    return (
-      !!this.params.resourceFiles?.length ||
-      !!this.params.bootloaderBinary ||
-      fwBinaryMap.length > 0
+  private hasExplicitProtocolV2Payload(installItems: ProtocolV2InstallItem[]) {
+    return !!this.params.resourceFiles?.length || installItems.length > 0;
+  }
+
+  private getMissingProtocolV2FirmwareTargets(installItems: ProtocolV2InstallItem[]) {
+    const preparedTargets = new Set(
+      installItems.flatMap(item => {
+        const target = PROTOCOL_V2_UPDATE_TARGET_BY_TARGET_ID.get(item.targetId);
+        return target ? [target] : [];
+      })
+    );
+    return (this.params.targetsToUpdate ?? []).filter(
+      target => target !== 'resource' && !preparedTargets.has(target)
     );
   }
 
@@ -1210,7 +1226,11 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     };
   }
 
-  private async prepareRemoteProtocolV2Binaries(firmwareType: EFirmwareType, features: Features) {
+  private async prepareRemoteProtocolV2Binaries(
+    firmwareType: EFirmwareType,
+    features: Features,
+    explicitInstallItems: ProtocolV2InstallItem[] = []
+  ) {
     const release = DataManager.getFirmwareLatestRelease(features, firmwareType);
 
     let bootloaderBinary: ArrayBuffer | null = null;
@@ -1218,6 +1238,15 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     const installItems: ProtocolV2InstallItem[] = [];
 
     if (!release) {
+      const missingFirmwareTargets = this.getMissingProtocolV2FirmwareTargets(explicitInstallItems);
+      if (missingFirmwareTargets.length > 0) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.RuntimeError,
+          `Protocol V2 firmware release is unavailable for requested targets: ${missingFirmwareTargets.join(
+            ', '
+          )}`
+        );
+      }
       return {
         bootloaderBinary,
         fwBinaryMap,
@@ -1227,6 +1256,10 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
 
     const entries = this.getRemoteComponentEntries(release);
     const targetsToUpdate = new Set(this.params.targetsToUpdate ?? []);
+    const explicitInstallItemByTargetId = new Map(
+      explicitInstallItems.map(item => [item.targetId, item] as const)
+    );
+    const preparedTargets = new Set<FirmwareUpdateV4Target>();
 
     for (const [key, component] of entries) {
       const targetName = component.target?.toUpperCase();
@@ -1235,27 +1268,34 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
         ? PROTOCOL_V2_UPDATE_TARGET_BY_TARGET_ID.get(target.targetId)
         : undefined;
       if (updateTarget && targetsToUpdate.has(updateTarget)) {
-        const remoteBinary = await this.downloadRemoteProtocolV2Component(key, component);
-        if (remoteBinary.kind === 'bootloader') {
-          bootloaderBinary = remoteBinary.binary;
-          installItems.push({
-            fileName: remoteBinary.fileName,
-            binary: remoteBinary.binary,
-            targetId: remoteBinary.targetId,
-            kind: remoteBinary.kind,
-          });
+        const explicitInstallItem = explicitInstallItemByTargetId.get(target.targetId);
+        const installItem =
+          explicitInstallItem ?? (await this.downloadRemoteProtocolV2Component(key, component));
+        if (installItem.kind === 'bootloader') {
+          bootloaderBinary = installItem.binary;
         } else {
           const binaryEntry = {
-            fileName: remoteBinary.fileName,
-            binary: remoteBinary.binary,
-            targetId: remoteBinary.targetId,
+            fileName: installItem.fileName,
+            binary: installItem.binary,
+            targetId: installItem.targetId,
           };
           fwBinaryMap.push(binaryEntry);
-          installItems.push({ ...binaryEntry, kind: remoteBinary.kind });
         }
+        installItems.push({ ...installItem });
+        preparedTargets.add(updateTarget);
       }
     }
 
+    const missingTarget = Array.from(targetsToUpdate).find(
+      target => target !== 'resource' && !preparedTargets.has(target)
+    );
+    if (missingTarget) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.RuntimeError,
+        `Protocol V2 release does not contain requested target ${missingTarget}`
+      );
+    }
+
     return {
       bootloaderBinary,
       fwBinaryMap,

package/src/api/firmware/FirmwareUpdatePlan.ts

@@ -10,6 +10,7 @@ import {
   getDeviceFirmwareVersion,
 } from '../../utils/deviceVersionUtils';
 
+import type { FirmwareUpdateV4Target } from '../../types/api/firmwareUpdate';
 import type {
   FirmwareUpdatePlan,
   FirmwareUpdatePlanArtifact,
@@ -62,6 +63,11 @@ const PROTOCOL_V2_TARGETS: Readonly<
   SE04: 'se04',
 };
 
+const PROTOCOL_V2_FIRMWARE_UPDATE_TARGETS = new Set<FirmwareUpdateV4Target>([
+  ...Object.values(PROTOCOL_V2_TARGETS),
+  'resource',
+]);
+
 const asRecord = (value: unknown): Record<string, unknown> | undefined =>
   value && typeof value === 'object' && !Array.isArray(value)
     ? (value as Record<string, unknown>)
@@ -191,6 +197,23 @@ export const validateFirmwareUpdatePlanForceTargets = (
   return [...value] as FirmwareUpdatePlanForceTarget[];
 };
 
+export const validateProtocolV2FirmwareUpdateTargets = (
+  value: unknown
+): FirmwareUpdateV4Target[] => {
+  if (value === undefined) {
+    return [];
+  }
+  if (
+    !Array.isArray(value) ||
+    value.length > PROTOCOL_V2_FIRMWARE_UPDATE_TARGETS.size ||
+    value.some(target => !PROTOCOL_V2_FIRMWARE_UPDATE_TARGETS.has(target)) ||
+    new Set(value).size !== value.length
+  ) {
+    return planError('Protocol V2 firmware update targets are invalid');
+  }
+  return [...value] as FirmwareUpdateV4Target[];
+};
+
 const assertExactKeys = (
   value: Record<string, unknown>,
   required: readonly string[],
@@ -405,7 +428,7 @@ const selectResourceUrl = ({
 
 const getExecutor = (features: Features): FirmwareUpdatePlan['executor'] => {
   const deviceType = getDeviceType(features);
-  if (deviceType === EDeviceType.Pro2) {
+  if (deviceType === EDeviceType.Pro2 || deviceType === EDeviceType.Neo) {
     return 'v4';
   }
   if (
@@ -422,9 +445,11 @@ const buildProtocolV2Artifacts = (
   {
     includeComponents = true,
     includeResources = true,
+    componentTargets: selectedComponentTargets,
   }: {
     includeComponents?: boolean;
     includeResources?: boolean;
+    componentTargets?: ReadonlySet<FirmwareUpdatePlanTarget>;
   } = {}
 ): {
   artifacts: FirmwareUpdatePlanArtifact[];
@@ -445,12 +470,21 @@ const buildProtocolV2Artifacts = (
     includeComponents && components
       ? [...installOrder, ...Object.keys(components).filter(key => !installOrder.includes(key))]
       : [];
+  const selectedComponentKeys = selectedComponentTargets
+    ? componentKeys.filter(key => {
+        const component = asRecord(components?.[key]);
+        const targetName = asString(component?.target)?.toUpperCase();
+        const target = targetName ? PROTOCOL_V2_TARGETS[targetName] : undefined;
+        return !!target && selectedComponentTargets.has(target);
+      })
+    : componentKeys;
   const artifacts: FirmwareUpdatePlanArtifact[] = [];
   const targets: FirmwareUpdatePlanTarget[] = [];
-  const componentTargets = new Set<FirmwareUpdatePlanTarget>();
-  for (const key of componentKeys) {
+  const componentTargetSet = new Set<FirmwareUpdatePlanTarget>();
+  for (const key of selectedComponentKeys) {
     const component = asRecord(components?.[key]);
     const targetName = asString(component?.target)?.toUpperCase();
+    const target = targetName ? PROTOCOL_V2_TARGETS[targetName] : undefined;
     if (targetName === 'ROMLOADER') {
       throw ERRORS.TypedError(
         HardwareErrorCode.RuntimeError,
@@ -458,7 +492,6 @@ const buildProtocolV2Artifacts = (
         { firmwareUpdateCode: 'FirmwarePlanInvalid' }
       );
     }
-    const target = targetName ? PROTOCOL_V2_TARGETS[targetName] : undefined;
     if (!component || !target) {
       throw ERRORS.TypedError(
         HardwareErrorCode.RuntimeError,
@@ -466,14 +499,14 @@ const buildProtocolV2Artifacts = (
         { firmwareUpdateCode: 'FirmwarePlanInvalid' }
       );
     }
-    if (componentTargets.has(target)) {
+    if (componentTargetSet.has(target)) {
       throw ERRORS.TypedError(
         HardwareErrorCode.RuntimeError,
         `Protocol V2 component ${key} duplicates target ${target}`,
         { firmwareUpdateCode: 'FirmwarePlanInvalid' }
       );
     }
-    componentTargets.add(target);
+    componentTargetSet.add(target);
     artifacts.push({
       artifactId: `component:${target}`,
       role: 'component',
@@ -587,6 +620,119 @@ const assertForcedTargetsRepresented = ({
   }
 };
 
+const finalizeFirmwareUpdatePlan = ({
+  features,
+  firmwareType,
+  platform,
+  artifacts,
+  targetsToUpdate,
+}: {
+  features: Features;
+  firmwareType: EFirmwareType;
+  platform: FirmwareUpdatePlatform;
+  artifacts: FirmwareUpdatePlanArtifact[];
+  targetsToUpdate: FirmwareUpdatePlanTarget[];
+}): FirmwareUpdatePlan => {
+  const executor = getExecutor(features);
+  const bootloaderMode = resolveDeviceBootloaderMode(features);
+  // 'unavailable' is the reserved degraded-identity sentinel; a device-reported
+  // serial must never be able to collide with it.
+  const reportedIdentity = getDeviceUUID(features);
+  const deviceIdentity = reportedIdentity === 'unavailable' ? '' : reportedIdentity;
+  // Bootloader-mode classic-family devices (executor v2, e.g. classic1s) cannot report
+  // a serial number, so their recovery plans fall back to the degraded 'unavailable'
+  // identity. Binding is then enforced against the live device at install time instead
+  // (assertFirmwareUpdatePreparedPlanDeviceIdentity), and plan integrity by the digest.
+  // Pro (v3), Pro2, and Neo (v4) report a serial even in loader mode and stay strict.
+  if (
+    artifacts.length > 0 &&
+    (platform === 'native' || platform === 'desktop') &&
+    !deviceIdentity &&
+    !(bootloaderMode && executor === 'v2')
+  ) {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      'Prepared firmware update requires a stable device identity',
+      { firmwareUpdateCode: 'FirmwarePlanInvalid' }
+    );
+  }
+  const planWithoutDigest: Omit<FirmwareUpdatePlan, 'planDigest'> = {
+    schemaVersion: 2,
+    executor,
+    deviceIdentity: deviceIdentity || 'unavailable',
+    deviceModel: String(getDeviceType(features)),
+    firmwareType,
+    platform,
+    artifacts,
+    targetsToUpdate,
+  };
+  return assertFirmwareUpdatePlan({
+    ...planWithoutDigest,
+    planDigest: digestFirmwareUpdatePlan(planWithoutDigest),
+  });
+};
+
+export const buildProtocolV2FirmwareUpdatePlan = ({
+  features,
+  firmwareType,
+  platform,
+  release,
+  targetsToUpdate,
+  forceUpdateTargets,
+  resourceArchiveAvailable,
+}: {
+  features: Features;
+  firmwareType: EFirmwareType;
+  platform: FirmwareUpdatePlatform;
+  release: ReleaseRecord | undefined;
+  targetsToUpdate: readonly FirmwareUpdateV4Target[];
+  forceUpdateTargets?: FirmwareUpdatePlanForceTarget[];
+  resourceArchiveAvailable: boolean;
+}): FirmwareUpdatePlan => {
+  const validatedForceTargets = validateFirmwareUpdatePlanForceTargets(forceUpdateTargets);
+  if (validatedForceTargets.some(target => target === 'ble' || target === 'bootloader')) {
+    planError('Protocol V2 does not support forced BLE or legacy bootloader targets');
+  }
+
+  const requestedComponentTargets = new Set<FirmwareUpdatePlanTarget>(
+    targetsToUpdate.filter(target => target !== 'resource')
+  );
+  if (
+    getDeviceType(features) === EDeviceType.Neo &&
+    (requestedComponentTargets.has('se03') || requestedComponentTargets.has('se04'))
+  ) {
+    planError('Neo does not support Protocol V2 targets se03 or se04');
+  }
+  const protocolV2 = buildProtocolV2Artifacts(release ?? {}, {
+    includeComponents: requestedComponentTargets.size > 0,
+    includeResources: false,
+    componentTargets: requestedComponentTargets,
+  });
+  const representedTargets = new Set(protocolV2.targets);
+  const missingTarget = Array.from(requestedComponentTargets).find(
+    target => !representedTargets.has(target)
+  );
+  if (missingTarget) {
+    planError(`Protocol V2 release does not contain requested target ${missingTarget}`);
+  }
+  if (validatedForceTargets.includes('firmware') && protocolV2.targets.length === 0) {
+    planError('Forced firmware update target firmware is not represented by the plan');
+  }
+  if (validatedForceTargets.includes('resource') && !resourceArchiveAvailable) {
+    planError('Forced firmware update target resource has no Protocol V2 resource archive');
+  }
+
+  // Protocol V2 resource archives are materialized by the host into explicit
+  // resourceFiles. The prepared artifact plan therefore binds firmware components only.
+  return finalizeFirmwareUpdatePlan({
+    features,
+    firmwareType,
+    platform,
+    artifacts: protocolV2.artifacts,
+    targetsToUpdate: protocolV2.targets,
+  });
+};
+
 export const buildFirmwareUpdatePlan = ({
   features,
   firmwareType,
@@ -733,40 +879,11 @@ export const buildFirmwareUpdatePlan = ({
     artifacts,
     targetsToUpdate,
   });
-
-  // 'unavailable' is the reserved degraded-identity sentinel; a device-reported
-  // serial must never be able to collide with it.
-  const reportedIdentity = getDeviceUUID(features);
-  const deviceIdentity = reportedIdentity === 'unavailable' ? '' : reportedIdentity;
-  // Bootloader-mode classic-family devices (executor v2, e.g. classic1s) cannot report
-  // a serial number, so their recovery plans fall back to the degraded 'unavailable'
-  // identity. Binding is then enforced against the live device at install time instead
-  // (assertFirmwareUpdatePreparedPlanDeviceIdentity), and plan integrity by the digest.
-  // Pro (v3) and Pro2 (v4) report a serial even in bootloader mode and stay strict.
-  if (
-    artifacts.length > 0 &&
-    (platform === 'native' || platform === 'desktop') &&
-    !deviceIdentity &&
-    !(bootloaderMode && executor === 'v2')
-  ) {
-    throw ERRORS.TypedError(
-      HardwareErrorCode.RuntimeError,
-      'Prepared firmware update requires a stable device identity',
-      { firmwareUpdateCode: 'FirmwarePlanInvalid' }
-    );
-  }
-  const planWithoutDigest: Omit<FirmwareUpdatePlan, 'planDigest'> = {
-    schemaVersion: 2,
-    executor,
-    deviceIdentity: deviceIdentity || 'unavailable',
-    deviceModel: String(getDeviceType(features)),
+  return finalizeFirmwareUpdatePlan({
+    features,
     firmwareType,
     platform,
     artifacts,
     targetsToUpdate,
-  };
-  return assertFirmwareUpdatePlan({
-    ...planWithoutDigest,
-    planDigest: digestFirmwareUpdatePlan(planWithoutDigest),
   });
 };

package/src/api/firmware/protocolV2Release.ts

@@ -135,6 +135,8 @@ export function toProtocolV2FirmwareReleaseInfo({
   return {
     shouldUpdate: plan.hasUpgrade,
     status: plan.status === 'unavailable' ? 'unknown' : plan.status,
+    // Protocol V2 components share package-set release notes. The optional
+    // bootloaderChangelog field belongs to the legacy Protocol V1 release model.
     changelog: plan.release ? [plan.release.changelog] : [],
     release,
     bootloaderMode: state.status.mode === 'bootloader' || state.status.mode === 'romloader',

package/src/types/api/checkAllFirmwareRelease.ts

@@ -89,6 +89,7 @@ export type CheckAllFirmwareReleaseParams = {
   firmwareType?: EFirmwareType;
   platform?: 'native' | 'desktop' | 'ext' | 'web' | 'web-embed';
   forceUpdateTargets?: FirmwareUpdatePlanForceTarget[];
+  protocolV2ForceUpdateTargets?: FirmwareUpdateV4Target[];
 };
 
 export declare function checkAllFirmwareRelease(

package/src/types/api/checkBLEFirmwareRelease.ts

@@ -3,4 +3,4 @@ import type { FirmwareReleaseCheckResult } from './checkAllFirmwareRelease';
 
 export declare function checkBLEFirmwareRelease(
   connectId?: string
-): Response<FirmwareReleaseCheckResult>;
+): Response<FirmwareReleaseCheckResult | null>;

package/src/types/api/checkBootloaderRelease.ts

@@ -2,7 +2,7 @@ import type { EFirmwareType } from '@onekeyfe/hd-shared';
 import type { CommonParams, Response } from '../params';
 import type { FirmwareReleaseCheckResult } from './checkAllFirmwareRelease';
 
-export type CheckBootloaderReleaseResponse = FirmwareReleaseCheckResult;
+export type CheckBootloaderReleaseResponse = FirmwareReleaseCheckResult | null;
 
 export type CheckBootloaderReleaseParams = {
   willUpdateFirmwareVersion?: string;