@onekeyfe/hd-core 1.2.0-alpha.98 → 1.2.0

package/src/api/firmware/FirmwareUpdateBaseMethod.ts

@@ -41,9 +41,15 @@ const FIRMWARE_UPDATE_CONFIRM = 'Firmware install confirmed';
  */
 export const BOOTLOADER_POLL_INITIALIZE_TIMEOUT_MS = 5000;
 
-type FirmwareTransferMetrics = Pick<
+type FirmwareProgressMetadata = Pick<
   FirmwareProgress['payload'],
-  'transferredBytes' | 'totalBytes' | 'rateBytesPerSecond' | 'elapsedMs'
+  | 'transferredBytes'
+  | 'totalBytes'
+  | 'rateBytesPerSecond'
+  | 'elapsedMs'
+  | 'installTargetId'
+  | 'installPhase'
+  | 'installPhaseProgress'
 >;
 
 const isDeviceDisconnectedError = (error: unknown) => {
@@ -103,7 +109,7 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
   postProgressMessage = (
     progress: number,
     progressType: IFirmwareUpdateProgressType,
-    metrics?: FirmwareTransferMetrics
+    metrics?: FirmwareProgressMetadata
   ) => {
     this.postMessage(
       createUiMessage(UI_REQUEST.FIRMWARE_PROGRESS, {
@@ -167,92 +173,141 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
     let checkCount = 0;
     let hasPromptedWebDevice = false;
     let isPromptingWebDevice = false;
-    // eslint-disable-next-line prefer-const
+    let isFinished = false;
+    let intervalTimer: ReturnType<typeof setInterval> | undefined;
     let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
 
     const isTouchOrProDevice =
       this?.device?.getCurrentDeviceType() === EDeviceType.Touch ||
       this?.device?.getCurrentDeviceType() === EDeviceType.Pro;
 
-    const intervalTimer: ReturnType<typeof setInterval> | undefined = setInterval(
-      async () => {
-        checkCount += 1;
-        Log.log('FirmwareUpdateBaseMethod [checkDeviceToBootloader] isFirstCheck: ', isFirstCheck);
-        if (isTouchOrProDevice && isFirstCheck) {
-          isFirstCheck = false;
-          Log.log('FirmwareUpdateBaseMethod [checkDeviceToBootloader] wait 3000ms');
-          await wait(3000);
-        }
+    const clearPollingTimers = () => {
+      if (intervalTimer !== undefined) {
+        clearInterval(intervalTimer);
+        intervalTimer = undefined;
+      }
+      if (timeoutTimer !== undefined) {
+        clearTimeout(timeoutTimer);
+        timeoutTimer = undefined;
+      }
+    };
 
-        if (
-          checkCount > 4 &&
-          DataManager.isBrowserWebUsb(DataManager.getSettings('env')) &&
-          !this.payload.skipWebDevicePrompt &&
-          !hasPromptedWebDevice &&
-          !isPromptingWebDevice
-        ) {
-          clearInterval(intervalTimer);
-          clearTimeout(timeoutTimer);
-          isPromptingWebDevice = true;
-          try {
-            this.postTipMessage(FirmwareUpdateTipMessage.SelectDeviceInBootloaderForWebDevice);
-            const confirmed = await this._promptDeviceInBootloaderForWebDevice();
-            hasPromptedWebDevice = true;
-            if (confirmed) {
-              await this._checkDeviceInBootloaderMode(connectId, intervalTimer, timeoutTimer);
-            }
-          } catch (e) {
-            clearInterval(intervalTimer);
-            clearTimeout(timeoutTimer);
-            Log.log(
-              'FirmwareUpdateBaseMethod [checkDeviceToBootloader] _promptDeviceInBootloaderForWebDevice failed: ',
-              e
-            );
-            this.checkPromise?.reject(e);
-          } finally {
-            isPromptingWebDevice = false;
+    const checkForBootloader = async (clearActiveTimers: boolean) => {
+      const found = await this._checkDeviceInBootloaderMode(
+        connectId,
+        clearActiveTimers ? intervalTimer : undefined,
+        clearActiveTimers ? timeoutTimer : undefined
+      );
+      if (found) {
+        isFinished = true;
+        clearPollingTimers();
+      }
+      return found;
+    };
+
+    let startPolling: () => void = () => undefined;
+    const pollForBootloader = async () => {
+      if (isFinished || isPromptingWebDevice) return;
+      checkCount += 1;
+      Log.log('FirmwareUpdateBaseMethod [checkDeviceToBootloader] isFirstCheck: ', isFirstCheck);
+      if (isTouchOrProDevice && isFirstCheck) {
+        isFirstCheck = false;
+        Log.log('FirmwareUpdateBaseMethod [checkDeviceToBootloader] wait 3000ms');
+        await wait(3000);
+      }
+
+      if (
+        checkCount > 4 &&
+        DataManager.isBrowserWebUsb(DataManager.getSettings('env')) &&
+        !this.payload.skipWebDevicePrompt &&
+        !hasPromptedWebDevice &&
+        !isPromptingWebDevice
+      ) {
+        clearPollingTimers();
+        isPromptingWebDevice = true;
+        try {
+          this.postTipMessage(FirmwareUpdateTipMessage.SelectDeviceInBootloaderForWebDevice);
+          const confirmed = await this._promptDeviceInBootloaderForWebDevice();
+          hasPromptedWebDevice = true;
+          if (confirmed) {
+            await checkForBootloader(false);
+          }
+          // WebUSB enumeration can still be empty immediately after the chooser
+          // resolves. Resume a fresh bounded polling window instead of leaving the
+          // deferred check pending forever after the original timers were paused.
+          if (!isFinished) {
+            startPolling();
           }
-          return;
+        } catch (e) {
+          isFinished = true;
+          clearPollingTimers();
+          Log.log(
+            'FirmwareUpdateBaseMethod [checkDeviceToBootloader] _promptDeviceInBootloaderForWebDevice failed: ',
+            e
+          );
+          this.checkPromise?.reject(e);
+        } finally {
+          isPromptingWebDevice = false;
         }
+        return;
+      }
 
-        if (isBleReconnect) {
-          if (bleProbeInFlight) return;
-          bleProbeInFlight = true;
-          try {
-            await this.device.deviceConnector?.acquire(
-              this.device.originalDescriptor.id,
-              null,
-              true,
-              this.payload.connectProtocol ?? this.device.originalDescriptor.protocolType
-            );
-            // Bound each probe so a request the rebooting device never received
-            // frees the slot for the next tick instead of hanging into the
-            // 30s reboot budget.
-            await this.device.initialize({ timeoutMs: BOOTLOADER_POLL_INITIALIZE_TIMEOUT_MS });
-            if (this.device.isBootloader()) {
-              clearInterval(intervalTimer);
-              this.checkPromise?.resolve(true);
-            }
-          } catch (e) {
-            // ignore error because of device is not connected
-            Log.log('catch Bluetooth error when device is restarting: ', e);
-          } finally {
-            bleProbeInFlight = false;
+      if (isBleReconnect) {
+        if (bleProbeInFlight) return;
+        bleProbeInFlight = true;
+        try {
+          await this.device.deviceConnector?.acquire(
+            this.device.originalDescriptor.id,
+            null,
+            true,
+            this.payload.connectProtocol ?? this.device.originalDescriptor.protocolType
+          );
+          // Bound each probe so a request the rebooting device never received
+          // frees the slot for the next tick instead of hanging into the
+          // 30s reboot budget.
+          await this.device.initialize({ timeoutMs: BOOTLOADER_POLL_INITIALIZE_TIMEOUT_MS });
+          if (this.device.isBootloader()) {
+            isFinished = true;
+            clearPollingTimers();
+            this.checkPromise?.resolve(true);
           }
-        } else {
-          await this._checkDeviceInBootloaderMode(connectId, intervalTimer, timeoutTimer);
+        } catch (e) {
+          // ignore error because of device is not connected
+          Log.log('catch Bluetooth error when device is restarting: ', e);
+        } finally {
+          bleProbeInFlight = false;
         }
-      },
-      isBleReconnect ? 3000 : 2000
-    );
-
-    // check goto bootloader mode timeout and throw error
-    timeoutTimer = setTimeout(() => {
-      if (this.checkPromise) {
-        clearInterval(intervalTimer);
-        this.checkPromise.reject(new Error());
+      } else {
+        await checkForBootloader(true);
       }
-    }, 30000);
+    };
+
+    startPolling = () => {
+      if (isFinished) return;
+      clearPollingTimers();
+      intervalTimer = setInterval(
+        () => {
+          pollForBootloader().catch(error => {
+            if (isFinished) return;
+            isFinished = true;
+            clearPollingTimers();
+            this.checkPromise?.reject(error);
+          });
+        },
+        isBleReconnect ? 3000 : 2000
+      );
+      // Each automatic polling phase is bounded. Time spent in the browser's
+      // permission chooser is intentionally excluded from this deadline.
+      timeoutTimer = setTimeout(() => {
+        if (!isFinished && this.checkPromise) {
+          isFinished = true;
+          clearPollingTimers();
+          this.checkPromise.reject(new Error());
+        }
+      }, 30000);
+    };
+
+    startPolling();
   }
 
   private async _checkDeviceInBootloaderMode(

package/src/api/firmware/FirmwareUpdatePlan.ts

@@ -216,15 +216,20 @@ export const validateProtocolV2FirmwareUpdateTargets = (
   if (value === undefined) {
     return [];
   }
+  if (!Array.isArray(value)) {
+    return planError('Protocol V2 firmware update targets are invalid');
+  }
+  const normalizedTargets = value.map(target =>
+    target === 'boot_resources' ? 'resource' : target
+  );
   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
+    normalizedTargets.length > PROTOCOL_V2_FIRMWARE_UPDATE_TARGETS.size ||
+    normalizedTargets.some(target => !PROTOCOL_V2_FIRMWARE_UPDATE_TARGETS.has(target)) ||
+    new Set(normalizedTargets).size !== normalizedTargets.length
   ) {
     return planError('Protocol V2 firmware update targets are invalid');
   }
-  return [...value] as FirmwareUpdateV4Target[];
+  return normalizedTargets as FirmwareUpdateV4Target[];
 };
 
 const assertExactKeys = (
@@ -323,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)) {
@@ -343,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);
     }
@@ -639,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,
@@ -817,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',
@@ -845,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',
@@ -868,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',
@@ -894,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',
@@ -916,6 +881,14 @@ export const buildFirmwareUpdatePlan = ({
     targetsToUpdate = [...new Set(artifacts.map(artifact => artifact.target))];
   }
 
+  if (
+    executor !== 'v4' &&
+    targetsToUpdate.includes('resource') &&
+    !targetsToUpdate.includes('firmware')
+  ) {
+    planError('Legacy resource updates require a firmware target');
+  }
+
   assertForcedTargetsRepresented({
     executor,
     forcedTargets: validatedForceTargets,

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');
@@ -321,23 +325,34 @@ export const getFirmwareUpdatePreparedRawArtifact = ({
 
 /**
  * Identity observed on the live device while a degraded recovery plan runs, keyed by
- * the plan's opaque lease. Bootloader recovery starts with no serial and the device
- * reports one only after the firmware phase reboots it, so the later phases of the
- * SAME workflow must be allowed to continue — but only for the device that first
- * answered, never for a second one that appears mid-recovery.
+ * the approved prepared-plan digest. Bootloader recovery starts with no serial and
+ * the device reports one only after the firmware phase reboots it, so the later
+ * phases of the SAME workflow must be allowed to continue — but only for the device
+ * that first answered, never for a second one that appears mid-recovery.
  */
 const degradedPlanIdentityPins = new Map<string, string>();
 /** Keep the pin map from growing without bound across many workflows. */
 const DEGRADED_PLAN_IDENTITY_PIN_LIMIT = 32;
 
-const pinDegradedPlanIdentity = (leaseRef: string, deviceIdentity: string) => {
-  if (degradedPlanIdentityPins.size >= DEGRADED_PLAN_IDENTITY_PIN_LIMIT) {
+const pinDegradedPlanIdentity = (preparedPlanDigest: string, deviceIdentity: string) => {
+  const key = preparedPlanDigest.toLowerCase();
+  if (
+    !degradedPlanIdentityPins.has(key) &&
+    degradedPlanIdentityPins.size >= DEGRADED_PLAN_IDENTITY_PIN_LIMIT
+  ) {
     const oldest = degradedPlanIdentityPins.keys().next();
     if (!oldest.done) {
       degradedPlanIdentityPins.delete(oldest.value);
     }
   }
-  degradedPlanIdentityPins.set(leaseRef, deviceIdentity);
+  degradedPlanIdentityPins.set(key, deviceIdentity);
+};
+
+/** Release recovery identity state when its digest-bound host workflow ends. */
+export const clearFirmwareUpdatePreparedPlanDeviceIdentityPin = (
+  preparedPlanDigest: string
+): void => {
+  degradedPlanIdentityPins.delete(preparedPlanDigest.toLowerCase());
 };
 
 export const assertFirmwareUpdatePreparedPlanDeviceIdentity = ({
@@ -364,7 +379,9 @@ export const assertFirmwareUpdatePreparedPlanDeviceIdentity = ({
     if (deviceModel === undefined || preparedPlan.deviceModel !== deviceModel) {
       throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckDeviceIdError);
     }
-    const pinnedIdentity = degradedPlanIdentityPins.get(preparedPlan.leaseRef);
+    const pinnedIdentity = degradedPlanIdentityPins.get(
+      preparedPlan.preparedPlanDigest.toLowerCase()
+    );
     if (!deviceIdentity) {
       // V4 设备可能尚未写入序列号；V2 则只允许 bootloader 恢复流程缺少身份。
       if (preparedPlan.executor !== 'v4' && bootloaderMode !== true) {
@@ -375,7 +392,7 @@ export const assertFirmwareUpdatePreparedPlanDeviceIdentity = ({
     // The recovered device now reports a serial: bind this recovery to it, and hold
     // every later phase to the same one.
     if (!pinnedIdentity) {
-      pinDegradedPlanIdentity(preparedPlan.leaseRef, deviceIdentity);
+      pinDegradedPlanIdentity(preparedPlan.preparedPlanDigest, deviceIdentity);
       return preparedPlan;
     }
     if (pinnedIdentity !== deviceIdentity) {

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,
       },