@onekeyfe/hd-core 1.2.0-alpha.77 → 1.2.0-alpha.79

package/src/index.ts

@@ -19,6 +19,14 @@ export * from './types';
 export { whitelist, whitelistExtension } from './data/config';
 export { executeCallback, cleanupCallback };
 export { preloadSessionCache } from './device/Device';
+export { projectFeatures as projectDeviceStateFeatures } from './device/DeviceStateProjector';
+export { getMethodSupportedProtocols } from './api/utils';
+export {
+  parseProtocolV2ResourceManifest,
+  prepareProtocolV2ResourceFiles,
+  resolveProtocolV2ResourceManifestFileUrl,
+  selectProtocolV2ResourceManifestFiles,
+} from './protocols/protocol-v2/resources';
 export {
   getFirmwareUpdateHostBindingGeneration,
   registerFirmwareUpdateHostBinding,

package/src/inject.ts

@@ -3,6 +3,7 @@ import {
   prepareFirmwareUpdatePlan,
   validateFirmwareUpdatePreparedPlan,
 } from './api/firmware/FirmwareUpdatePreparedPlan';
+import { prepareProtocolV2ResourceFiles } from './protocols/protocol-v2/resources';
 import {
   getFirmwareUpdateHostBindingGeneration,
   registerFirmwareUpdateHostBinding,
@@ -168,6 +169,7 @@ export const createCoreApi = (
   getFirmwareUpdateHostBindingGeneration,
   prepareFirmwareUpdatePlan,
   validateFirmwareUpdatePreparedPlan,
+  prepareProtocolV2ResourceFiles,
   getLogs: () => call({ method: 'getLogs' }),
   clearSessionCache: params => call({ ...params, method: 'clearSessionCache' }),
   /**

package/src/protocols/protocol-v2/resources.ts

@@ -1,383 +1,252 @@
 import { sha256 } from '@noble/hashes/sha256';
-import { PROTOCOL_V2_BLE_FILE_READ_CHUNK_SIZE } from '@onekeyfe/hd-transport';
 
 import type {
-  IProtocolV2BootResources,
-  IProtocolV2Resource,
-  IProtocolV2ResourceFile,
-  IProtocolV2ResourceType,
+  IProtocolV2ResourceManifest,
+  IProtocolV2ResourceManifestFile,
   IProtocolV2Resources,
 } from '../../types';
-import type { DeviceCommands } from '../../device/DeviceCommands';
+import type { FirmwareUpdateV4Target } from '../../types/api/firmwareUpdate';
 
-export const PROTOCOL_V2_RESOURCE_TYPES = [
-  'images',
-  'animation',
-  'wallpaper',
-  'translations',
-  'roobert',
-  'noto',
-  'firmware_logo',
-] as const satisfies readonly IProtocolV2ResourceType[];
+export const PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_PATH =
+  'vol0:/loaders/bootloader/boot_resource.okpkg';
+export const PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_STAGING_PATH = `${PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_PATH}.staging`;
+export const PROTOCOL_V2_ROM_PARAMS_PACKAGE_PATH = 'vol0:/loaders/rom/params.okpkg';
 
-export const PROTOCOL_V2_RESOURCE_DEVICE_PATHS: Readonly<Record<IProtocolV2ResourceType, string>> =
-  {
-    images: 'vol0:/bundles/images/images.okpkg',
-    animation: 'vol0:/bundles/images/animation.okpkg',
-    wallpaper: 'vol0:/bundles/images/wallpaper.okpkg',
-    translations: 'vol0:/bundles/translations/translations.okpkg',
-    roobert: 'vol0:/bundles/font/roobert.okpkg',
-    noto: 'vol0:/bundles/font/noto.okpkg',
-    firmware_logo: 'vol0:/bundles/firmware_logo.okpkg',
-  };
-
-const RESOURCE_TYPE_SET = new Set<string>(PROTOCOL_V2_RESOURCE_TYPES);
 const SHA256_HEX_LENGTH = 64;
-const SHA3_512_HEX_LENGTH = 128;
-const PROTOCOL_V2_OKPP_HEADER_SIZE = 0x52a0;
-const PROTOCOL_V2_OKPP_TYPE_OFFSET = 0x08;
-const PROTOCOL_V2_OKPP_HEADER_LENGTH_OFFSET = 0x0c;
-const PROTOCOL_V2_OKPP_HEADER_HASH_OFFSET = 0x240;
-const PROTOCOL_V2_OKPP_HASH_SIZE = 64;
-const PROTOCOL_V2_RESOURCE_IDENTITY_READ_SIZE =
-  PROTOCOL_V2_OKPP_HEADER_HASH_OFFSET + PROTOCOL_V2_OKPP_HASH_SIZE;
-const PROTOCOL_V2_MIN_FILE_READ_CHUNK_SIZE = 64;
-export const PROTOCOL_V2_RESOURCE_INVENTORY_TIMEOUT_MS = 5 * 1000;
-
-export type ProtocolV2ResourceInventoryItem = {
-  type: IProtocolV2ResourceType;
-  size: number;
-  headerHash: string;
-};
-
-export type ProtocolV2ResourceUpdateMode = 'application' | 'bootloader-recovery';
 
-export type ProtocolV2ResourceUpdatePlan = {
-  status: 'valid' | 'outdated' | 'unknown';
-  resources: IProtocolV2Resource[];
-};
-
-function toFiniteNumber(value: unknown): number | undefined {
-  if (typeof value === 'number' && Number.isFinite(value)) return value;
-  if (typeof value === 'string') {
-    const numeric = Number(value);
-    return Number.isFinite(numeric) ? numeric : undefined;
+function normalizeHex(value: unknown, expectedLength: number, field: string): string {
+  if (typeof value !== 'string') {
+    throw new Error(`Invalid Pro2 resource ${field}: expected a hexadecimal string`);
   }
-  if (value && typeof value === 'object') {
-    const longLike = value as { toNumber?: () => number };
-    if (typeof longLike.toNumber === 'function') {
-      const numeric = longLike.toNumber();
-      return Number.isFinite(numeric) ? numeric : undefined;
-    }
+  const normalized = value.replace(/^0x/i, '').toLowerCase();
+  if (normalized.length !== expectedLength || !/^[0-9a-f]+$/.test(normalized)) {
+    throw new Error(
+      `Invalid Pro2 resource ${field}: expected ${expectedLength} hexadecimal characters`
+    );
   }
-  return undefined;
+  return normalized;
 }
 
-function toUint8Array(value: unknown): Uint8Array {
-  if (value instanceof Uint8Array) return value;
-  if (value instanceof ArrayBuffer) return new Uint8Array(value);
-  if (ArrayBuffer.isView(value)) {
-    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+/** Validate a complete Pro2 stable resource set from remote configuration. */
+export function parseProtocolV2Resources(value: unknown): IProtocolV2Resources | undefined {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== 'object') {
+    throw new Error('Invalid Pro2 resources config');
   }
-  if (typeof value === 'string') {
-    const hex = value.replace(/^0x/i, '');
-    if (!hex || hex.length % 2 !== 0 || /[^0-9a-f]/i.test(hex)) {
-      return new Uint8Array(0);
-    }
-    const bytes = new Uint8Array(hex.length / 2);
-    for (let index = 0; index < bytes.length; index += 1) {
-      bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
-    }
-    return bytes;
+  const { source } = value as { source?: unknown };
+  if (!source || typeof source !== 'object') {
+    throw new Error('Invalid Pro2 resources config: source is required');
   }
-  return new Uint8Array(0);
-}
-
-function readAscii(bytes: Uint8Array, offset: number, length: number): string {
-  return Array.from(bytes.slice(offset, offset + length), byte => String.fromCharCode(byte)).join(
-    ''
-  );
+  const { manifestUrl } = source as { manifestUrl?: unknown };
+  if (typeof manifestUrl !== 'string' || !manifestUrl.startsWith('https://')) {
+    throw new Error('Invalid Pro2 resources config: source.manifestUrl must use HTTPS');
+  }
+  return {
+    source: { manifestUrl },
+  };
 }
 
-function parseProtocolV2ResourceHeaderHash(bytes: Uint8Array): string | undefined {
-  if (bytes.byteLength < PROTOCOL_V2_RESOURCE_IDENTITY_READ_SIZE) return undefined;
-  if (readAscii(bytes, 0, 4) !== 'OKPP') return undefined;
-  if (readAscii(bytes, PROTOCOL_V2_OKPP_TYPE_OFFSET, 4) !== 'RESC') return undefined;
+const PROTOCOL_V2_RESOURCE_MANIFEST_DEVICE_ROOTS = [
+  'vol0:/bundles/',
+  'vol0:/loaders/rom/',
+] as const;
 
-  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+function isAllowedManifestDevicePath(path: string): boolean {
   if (
-    view.getUint32(PROTOCOL_V2_OKPP_HEADER_LENGTH_OFFSET, true) !== PROTOCOL_V2_OKPP_HEADER_SIZE
+    !path.endsWith('.okpkg') ||
+    path.includes('\\') ||
+    path.includes('//') ||
+    path.split('/').some(part => part === '.' || part === '..')
   ) {
-    return undefined;
+    return false;
   }
-  return bytesToHex(
-    bytes.slice(
-      PROTOCOL_V2_OKPP_HEADER_HASH_OFFSET,
-      PROTOCOL_V2_OKPP_HEADER_HASH_OFFSET + PROTOCOL_V2_OKPP_HASH_SIZE
-    )
-  );
-}
-
-async function readProtocolV2ResourceIdentity({
-  commands,
-  resource,
-  chunkSize,
-  timeoutMs = PROTOCOL_V2_RESOURCE_INVENTORY_TIMEOUT_MS,
-}: {
-  commands: Pick<DeviceCommands, 'typedCall'>;
-  resource: IProtocolV2Resource;
-  chunkSize: number;
-  timeoutMs?: number;
-}): Promise<ProtocolV2ResourceInventoryItem | undefined> {
-  const path = PROTOCOL_V2_RESOURCE_DEVICE_PATHS[resource.type];
-  const pathInfo = await commands.typedCall(
-    'FilesystemPathInfoQuery',
-    'FilesystemPathInfo',
-    { path },
-    { timeoutMs }
-  );
-  const size = toFiniteNumber(pathInfo.message?.size);
-  if (
-    !pathInfo.message?.exist ||
-    pathInfo.message?.directory ||
-    !Number.isSafeInteger(size) ||
-    size !== resource.size ||
-    size < PROTOCOL_V2_OKPP_HEADER_SIZE
-  ) {
-    return undefined;
+  if (path === PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_PATH) {
+    return true;
   }
+  return PROTOCOL_V2_RESOURCE_MANIFEST_DEVICE_ROOTS.some(root => path.startsWith(root));
+}
 
-  const header = new Uint8Array(PROTOCOL_V2_RESOURCE_IDENTITY_READ_SIZE);
-  let offset = 0;
-  while (offset < header.byteLength) {
-    const readLength = Math.min(chunkSize, header.byteLength - offset);
-    const response = await commands.typedCall(
-      'FilesystemFileRead',
-      'FilesystemFile',
-      {
-        file: { path, offset, total_size: 0 },
-        chunk_len: readLength,
-      },
-      { timeoutMs }
-    );
-    const data = toUint8Array(response.message?.data);
-    if (data.byteLength === 0) return undefined;
-    const copied = Math.min(data.byteLength, header.byteLength - offset);
-    header.set(data.subarray(0, copied), offset);
-    offset += copied;
+function assertManifestString(value: unknown, field: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Invalid Pro2 resource manifest ${field}`);
   }
-
-  const headerHash = parseProtocolV2ResourceHeaderHash(header);
-  return headerHash ? { type: resource.type, size, headerHash } : undefined;
+  return value;
 }
 
-/**
- * 使用已发布 Pro2 固件支持的文件系统消息构建资源清单。
- * 缺失、无法读取或格式错误的文件不会进入清单，因此会被选中重写。
- */
-export async function readProtocolV2ResourceInventory({
-  commands,
-  resources,
-  chunkSize = PROTOCOL_V2_BLE_FILE_READ_CHUNK_SIZE,
-  timeoutMs = PROTOCOL_V2_RESOURCE_INVENTORY_TIMEOUT_MS,
-}: {
-  commands: Pick<DeviceCommands, 'typedCall'>;
-  resources: readonly IProtocolV2Resource[];
-  chunkSize?: number;
-  timeoutMs?: number;
-}): Promise<ProtocolV2ResourceInventoryItem[]> {
-  const normalizedChunkSize = Number.isFinite(chunkSize)
-    ? Math.max(Math.floor(chunkSize), PROTOCOL_V2_MIN_FILE_READ_CHUNK_SIZE)
-    : PROTOCOL_V2_BLE_FILE_READ_CHUNK_SIZE;
-  const inventory: ProtocolV2ResourceInventoryItem[] = [];
-  for (const resource of resources) {
-    try {
-      const item = await readProtocolV2ResourceIdentity({
-        commands,
-        resource,
-        chunkSize: normalizedChunkSize,
-        timeoutMs,
-      });
-      if (item) inventory.push(item);
-    } catch {
-      // 单个资源无法读取时按缺失处理，不阻断其余资源的增量检查。
-    }
+function assertManifestRelativePath(value: unknown, field: string): string {
+  const path = assertManifestString(value, field);
+  if (
+    path.startsWith('/') ||
+    path.includes('\\') ||
+    path.includes(':') ||
+    path.split('/').some(part => !part || part === '.' || part === '..')
+  ) {
+    throw new Error(`Invalid Pro2 resource manifest ${field}`);
   }
-  return inventory;
+  return path;
 }
 
-function normalizeHex(value: unknown, expectedLength: number, field: string): string {
-  if (typeof value !== 'string') {
-    throw new Error(`Invalid Pro2 resource ${field}: expected a hexadecimal string`);
+function parseProtocolV2ResourceManifestFile(
+  value: unknown,
+  index: number
+): IProtocolV2ResourceManifestFile {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`Invalid Pro2 resource manifest files[${index}]`);
   }
-  const normalized = value.replace(/^0x/i, '').toLowerCase();
-  if (normalized.length !== expectedLength || !/^[0-9a-f]+$/.test(normalized)) {
-    throw new Error(
-      `Invalid Pro2 resource ${field}: expected ${expectedLength} hexadecimal characters`
-    );
+  const file = value as Partial<IProtocolV2ResourceManifestFile>;
+  const archivePath = assertManifestRelativePath(file.archive_path, `files[${index}].archive_path`);
+  const originalName = assertManifestRelativePath(
+    file.original_name,
+    `files[${index}].original_name`
+  );
+  if (originalName.includes('/')) {
+    throw new Error(`Invalid Pro2 resource manifest files[${index}].original_name`);
   }
-  return normalized;
-}
-
-function validateResource(value: unknown, index: number): IProtocolV2Resource {
-  if (!value || typeof value !== 'object') {
-    throw new Error(`Invalid Pro2 resource at stable[${index}]`);
+  const devicePath = assertManifestString(file.device_path, `files[${index}].device_path`);
+  if (!isAllowedManifestDevicePath(devicePath)) {
+    throw new Error(`Invalid Pro2 resource manifest files[${index}].device_path`);
+  }
+  if (!Number.isSafeInteger(file.size) || Number(file.size) <= 0) {
+    throw new Error(`Invalid Pro2 resource manifest files[${index}].size`);
   }
-  const resource = value as Partial<IProtocolV2Resource>;
-  if (typeof resource.type !== 'string' || !RESOURCE_TYPE_SET.has(resource.type)) {
-    throw new Error(`Invalid Pro2 resource type at stable[${index}]`);
+  const digest = normalizeHex(file.sha256, SHA256_HEX_LENGTH, `files[${index}].sha256`);
+  if (file.signed !== true) {
+    throw new Error(`Invalid Pro2 resource manifest files[${index}].signed`);
   }
-  if (typeof resource.url !== 'string' || !resource.url.startsWith('https://')) {
-    throw new Error(`Invalid Pro2 resource url at stable[${index}]`);
+  if (file.sig_algo !== 'ed25519' && file.sig_algo !== 'mldsa65') {
+    throw new Error(`Invalid Pro2 resource manifest files[${index}].sig_algo`);
   }
-  if (!Number.isSafeInteger(resource.size) || Number(resource.size) <= 0) {
-    throw new Error(`Invalid Pro2 resource size at stable[${index}]`);
+  if (file.payload_version !== null && typeof file.payload_version !== 'string') {
+    throw new Error(`Invalid Pro2 resource manifest files[${index}].payload_version`);
+  }
+  if (!archivePath.endsWith('.okpkg') || !originalName.endsWith('.okpkg')) {
+    throw new Error(`Invalid Pro2 resource manifest files[${index}] package extension`);
   }
   return {
-    type: resource.type,
-    url: resource.url,
-    size: Number(resource.size),
-    fileHash: normalizeHex(resource.fileHash, SHA256_HEX_LENGTH, 'fileHash'),
-    headerHash: normalizeHex(resource.headerHash, SHA3_512_HEX_LENGTH, 'headerHash'),
+    archive_path: archivePath,
+    original_name: originalName,
+    device_path: devicePath,
+    size: Number(file.size),
+    sha256: digest,
+    signed: true,
+    sig_algo: file.sig_algo,
+    payload_version: file.payload_version ?? null,
   };
 }
 
-function validateBootResources(value: unknown): IProtocolV2BootResources {
-  if (!value || typeof value !== 'object') {
-    throw new Error('Invalid Pro2 boot resources config');
-  }
-  const resource = value as Partial<IProtocolV2BootResources>;
-  if (resource.required !== false) {
-    throw new Error('Invalid Pro2 boot resources required flag: expected false');
-  }
-  if (resource.target !== 'RES') {
-    throw new Error('Invalid Pro2 boot resources target: expected RES');
+export function parseProtocolV2ResourceManifest(value: unknown): IProtocolV2ResourceManifest {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Invalid Pro2 resource manifest');
   }
+  const manifest = value as Partial<IProtocolV2ResourceManifest>;
   if (
-    resource.manifestUrl !== undefined &&
-    (typeof resource.manifestUrl !== 'string' || !resource.manifestUrl.startsWith('https://'))
+    manifest.schema !== 1 ||
+    manifest.variant !== 'resource' ||
+    manifest.device_root !== 'vol0:' ||
+    manifest.restore_mode !== 'bootloader_update' ||
+    !Array.isArray(manifest.trees) ||
+    !Array.isArray(manifest.files)
   ) {
-    throw new Error('Invalid Pro2 boot resources manifestUrl');
-  }
-  if (!Array.isArray(resource.files) || resource.files.length === 0) {
-    throw new Error('Invalid Pro2 boot resources files');
+    throw new Error('Invalid Pro2 resource manifest contract');
   }
-  const files = resource.files.map((value, index): IProtocolV2ResourceFile => {
-    if (!value || typeof value !== 'object') {
-      throw new Error(`Invalid Pro2 boot resource file at files[${index}]`);
-    }
-    const file = value as Partial<IProtocolV2ResourceFile>;
-    if (typeof file.url !== 'string' || !file.url.startsWith('https://')) {
-      throw new Error(`Invalid Pro2 boot resource url at files[${index}]`);
-    }
-    if (
-      typeof file.devicePath !== 'string' ||
-      !file.devicePath.startsWith('vol0:/') ||
-      file.devicePath.includes('..') ||
-      file.devicePath.includes('\\')
-    ) {
-      throw new Error(`Invalid Pro2 boot resource devicePath at files[${index}]`);
-    }
-    if (!Number.isSafeInteger(file.size) || Number(file.size) <= 0) {
-      throw new Error(`Invalid Pro2 boot resource size at files[${index}]`);
-    }
-    return {
-      ...(typeof file.name === 'string' && file.name ? { name: file.name } : undefined),
-      url: file.url,
-      devicePath: file.devicePath,
-      size: Number(file.size),
-      fileHash: normalizeHex(file.fileHash, SHA256_HEX_LENGTH, `boot files[${index}].fileHash`),
-    };
-  });
-  if (new Set(files.map(file => file.devicePath)).size !== files.length) {
-    throw new Error('Invalid Pro2 boot resources files: duplicate devicePath');
+  const files = manifest.files.map(parseProtocolV2ResourceManifestFile);
+  const devicePaths = new Set(files.map(file => file.device_path));
+  const archivePaths = new Set(files.map(file => file.archive_path));
+  if (
+    files.length === 0 ||
+    devicePaths.size !== files.length ||
+    archivePaths.size !== files.length ||
+    !devicePaths.has(PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_PATH) ||
+    !files.some(file => file.device_path.startsWith('vol0:/bundles/'))
+  ) {
+    throw new Error('Invalid Pro2 resource manifest file set');
   }
   return {
-    required: false,
-    target: 'RES',
-    ...(resource.manifestUrl ? { manifestUrl: resource.manifestUrl } : undefined),
+    schema: 1,
+    artifact_name: assertManifestString(manifest.artifact_name, 'artifact_name'),
+    release_name: assertManifestString(manifest.release_name, 'release_name'),
+    variant: 'resource',
+    commit: assertManifestString(manifest.commit, 'commit'),
+    short_sha: assertManifestString(manifest.short_sha, 'short_sha'),
+    timestamp_utc: assertManifestString(manifest.timestamp_utc, 'timestamp_utc'),
+    core_version: assertManifestString(manifest.core_version, 'core_version'),
+    key_set: assertManifestString(manifest.key_set, 'key_set'),
+    device_root: 'vol0:',
+    restore_mode: 'bootloader_update',
+    trees: manifest.trees.map((tree, index) => {
+      if (!tree || typeof tree !== 'object') {
+        throw new Error(`Invalid Pro2 resource manifest trees[${index}]`);
+      }
+      const item = tree as { path?: unknown; device?: unknown };
+      return {
+        path: assertManifestRelativePath(item.path, `trees[${index}].path`),
+        device: assertManifestString(item.device, `trees[${index}].device`),
+      };
+    }),
     files,
   };
 }
 
-/** Validate a complete Pro2 stable resource set from remote configuration. */
-export function parseProtocolV2Resources(value: unknown): IProtocolV2Resources | undefined {
-  if (value === undefined) return undefined;
-  if (
-    !value ||
-    typeof value !== 'object' ||
-    !Array.isArray((value as { stable?: unknown }).stable)
-  ) {
-    throw new Error('Invalid Pro2 resources config: stable must be an array');
-  }
-
-  const config = value as { stable: unknown[]; boot?: unknown };
-  const stable = config.stable.map(validateResource);
-  const types = new Set(stable.map(resource => resource.type));
-  if (stable.length !== PROTOCOL_V2_RESOURCE_TYPES.length || types.size !== stable.length) {
-    throw new Error(
-      `Invalid Pro2 resources config: stable must contain ${PROTOCOL_V2_RESOURCE_TYPES.length} unique resource types`
-    );
-  }
-  for (const type of PROTOCOL_V2_RESOURCE_TYPES) {
-    if (!types.has(type)) {
-      throw new Error(`Invalid Pro2 resources config: stable is missing ${type}`);
+export function selectProtocolV2ResourceManifestFiles({
+  manifest,
+  targetsToUpdate,
+}: {
+  manifest: IProtocolV2ResourceManifest;
+  targetsToUpdate: readonly FirmwareUpdateV4Target[];
+}): IProtocolV2ResourceManifestFile[] {
+  const targets = new Set(targetsToUpdate);
+  return manifest.files.filter(file => {
+    if (file.device_path.startsWith('vol0:/bundles/')) {
+      return targets.has('resource');
     }
+    return targets.has('boot_resources');
+  });
+}
+
+export function resolveProtocolV2ResourceManifestFileUrl({
+  manifestUrl,
+  archivePath,
+}: {
+  manifestUrl: string;
+  archivePath: string;
+}): string {
+  const url = new URL(assertManifestRelativePath(archivePath, 'archive_path'), manifestUrl);
+  if (url.protocol !== 'https:') {
+    throw new Error('Invalid Pro2 resource manifest file URL');
   }
-  const boot = config.boot === undefined ? undefined : validateBootResources(config.boot);
-  return {
-    stable: PROTOCOL_V2_RESOURCE_TYPES.map(type => {
-      const resource = stable.find(item => item.type === type);
-      if (!resource) {
-        throw new Error(`Invalid Pro2 resources config: stable is missing ${type}`);
-      }
-      return resource;
-    }),
-    ...(boot ? { boot } : undefined),
-  };
+  return url.toString();
 }
 
-/** 比较文件系统资源清单；恢复模式无法取得清单时回退到全量更新。 */
-export function buildProtocolV2ResourceUpdatePlan({
-  resources,
-  inventory,
-  mode,
-  forced = false,
+export function prepareProtocolV2ResourceFiles({
+  manifest: value,
+  files,
+  targetsToUpdate,
 }: {
-  resources: readonly IProtocolV2Resource[];
-  inventory?: readonly ProtocolV2ResourceInventoryItem[];
-  mode: ProtocolV2ResourceUpdateMode;
-  forced?: boolean;
-}): ProtocolV2ResourceUpdatePlan {
-  if (forced) {
+  manifest: unknown;
+  files: Array<{ archivePath: string; binary: ArrayBuffer }>;
+  targetsToUpdate: readonly FirmwareUpdateV4Target[];
+}): Array<{ binary: ArrayBuffer; devicePath: string; size: number; fileHash: string }> {
+  const manifest = parseProtocolV2ResourceManifest(value);
+  const selected = selectProtocolV2ResourceManifestFiles({ manifest, targetsToUpdate });
+  const binaries = new Map(files.map(file => [file.archivePath, file.binary] as const));
+  return selected.map(file => {
+    const binary = binaries.get(file.archive_path);
+    if (
+      !binary ||
+      !isProtocolV2ResourceFileValid(binary, {
+        size: file.size,
+        fileHash: file.sha256,
+      })
+    ) {
+      throw new Error(`Pro2 resource manifest file verification failed: ${file.archive_path}`);
+    }
     return {
-      status: resources.length > 0 ? 'outdated' : 'valid',
-      resources: [...resources],
+      binary,
+      devicePath: file.device_path,
+      size: file.size,
+      fileHash: file.sha256,
     };
-  }
-  if (!inventory) {
-    return mode === 'bootloader-recovery'
-      ? {
-          status: resources.length > 0 ? 'outdated' : 'valid',
-          resources: [...resources],
-        }
-      : { status: 'unknown', resources: [] };
-  }
-
-  const inventoryByType = new Map(inventory.map(item => [item.type, item]));
-  const changedResources = resources.filter(resource => {
-    const current = inventoryByType.get(resource.type);
-    return (
-      !current ||
-      current.size !== resource.size ||
-      current.headerHash.toLowerCase() !== resource.headerHash.toLowerCase()
-    );
   });
-
-  return {
-    status: changedResources.length === 0 ? 'valid' : 'outdated',
-    resources: changedResources,
-  };
 }
 
 function bytesToHex(bytes: Uint8Array): string {
@@ -387,7 +256,7 @@ function bytesToHex(bytes: Uint8Array): string {
 /** Verify the complete downloaded file before any device mutation. */
 export function isProtocolV2ResourceFileValid(
   binary: ArrayBuffer,
-  resource: Pick<IProtocolV2ResourceFile, 'size' | 'fileHash'>
+  resource: { size: number; fileHash: string }
 ): boolean {
   if (binary.byteLength !== resource.size) return false;
   return bytesToHex(sha256(new Uint8Array(binary))) === resource.fileHash.toLowerCase();

package/src/types/api/checkAllFirmwareRelease.ts

@@ -61,6 +61,7 @@ export type AllFirmwareRelease = {
   hasUpgrade?: boolean;
   required?: boolean;
   resourceStatus?: 'valid' | 'outdated' | 'unknown';
+  resourceManifestUrl?: string;
   currentVersions?: DeviceStateVersions;
   components?: ProtocolV2FirmwareComponentRelease[];
   targetsToUpdate?: FirmwareUpdateV4Target[];

package/src/types/api/export.ts

@@ -49,6 +49,10 @@ export type {
   FirmwareUpdatePreparedEntry,
   FirmwareUpdatePreparedPlan,
 } from './firmwareUpdatePreparedPlan';
+export type {
+  ProtocolV2PreparedResourceFile,
+  ProtocolV2ResourceManifestBinary,
+} from './protocolV2ResourceManifest';
 export type { FirmwareUpdateCapabilities } from './firmwareUpdateCapabilities';
 export type { AllFirmwareRelease } from './checkAllFirmwareRelease';
 export type {

package/src/types/api/index.ts

@@ -41,6 +41,7 @@ import type {
   prepareFirmwareUpdatePlan,
   validateFirmwareUpdatePreparedPlan,
 } from './firmwareUpdatePreparedPlan';
+import type { prepareProtocolV2ResourceFiles } from './protocolV2ResourceManifest';
 import type { promptWebDeviceAccess } from './promptWebDeviceAccess';
 import type { deviceReset } from './deviceReset';
 import type { deviceRecovery } from './deviceRecovery';
@@ -253,6 +254,7 @@ export type CoreApi = {
   getFirmwareUpdateCapabilities: typeof getFirmwareUpdateCapabilities;
   prepareFirmwareUpdatePlan: typeof prepareFirmwareUpdatePlan;
   validateFirmwareUpdatePreparedPlan: typeof validateFirmwareUpdatePreparedPlan;
+  prepareProtocolV2ResourceFiles: typeof prepareProtocolV2ResourceFiles;
   cipherKeyValue: typeof cipherKeyValue;
 
   /**