@onekeyfe/hd-core 1.2.0-alpha.162 → 1.2.0-alpha.164

package/dist/utils/deviceInfoUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deviceInfoUtils.d.ts","sourceRoot":"","sources":["../../src/utils/deviceInfoUtils.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAKlE,eAAO,MAAM,aAAa,cAAe,mBAAmB,KAAG,WAClC,CAAC;AAM9B,eAAO,MAAM,sBAAsB,UAAW,MAAM,KAAG,WAqBtD,CAAC;AAMF,eAAO,MAAM,gBAAgB,cAAe,mBAAmB,KAAG,MAAM,GAAG,IAC3C,CAAC;AAKjC,eAAO,MAAM,iBAAiB,cAAe,mBAAmB,KAAG,MAClC,CAAC;AAKlC,eAAO,MAAM,aAAa,cANmB,mBAAmB,KAAG,MAMrB,CAAC;AAK/C,eAAO,MAAM,cAAc,cAAe,mBAAmB,kBAkB5D,CAAC;AAMF,eAAO,MAAM,qBAAqB,aACtB,mBAAmB,GAAG,SAAS,iCACV,WAAW,GAAG,YAAY,KAAK,aAAa,GAAG,SAAS,KACtF,aAAa,GAAG,SAyBlB,CAAC;AAEF,eAAO,MAAM,eAAe,cAAe,mBAAmB,gDACzB,CAAC"}
+{"version":3,"file":"deviceInfoUtils.d.ts","sourceRoot":"","sources":["../../src/utils/deviceInfoUtils.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAKlE,eAAO,MAAM,aAAa,cAAe,mBAAmB,KAAG,WAClC,CAAC;AAM9B,eAAO,MAAM,sBAAsB,UAAW,MAAM,KAAG,WAmBtD,CAAC;AAMF,eAAO,MAAM,gBAAgB,cAAe,mBAAmB,KAAG,MAAM,GAAG,IAC3C,CAAC;AAKjC,eAAO,MAAM,iBAAiB,cAAe,mBAAmB,KAAG,MAClC,CAAC;AAKlC,eAAO,MAAM,aAAa,cANmB,mBAAmB,KAAG,MAMrB,CAAC;AAK/C,eAAO,MAAM,cAAc,cAAe,mBAAmB,kBAkB5D,CAAC;AAMF,eAAO,MAAM,qBAAqB,aACtB,mBAAmB,GAAG,SAAS,iCACV,WAAW,GAAG,YAAY,KAAK,aAAa,GAAG,SAAS,KACtF,aAAa,GAAG,SAyBlB,CAAC;AAEF,eAAO,MAAM,eAAe,cAAe,mBAAmB,gDACzB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hd-core",
-  "version": "1.2.0-alpha.162",
+  "version": "1.2.0-alpha.164",
   "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.162",
-    "@onekeyfe/hd-transport": "1.2.0-alpha.162",
+    "@onekeyfe/hd-shared": "1.2.0-alpha.164",
+    "@onekeyfe/hd-transport": "1.2.0-alpha.164",
     "axios": "1.15.2",
     "bignumber.js": "^9.0.2",
     "buffer": "^6.0.3",
@@ -46,5 +46,5 @@
     "@types/w3c-web-usb": "^1.0.10",
     "@types/web-bluetooth": "^0.0.21"
   },
-  "gitHead": "f4aa654b350931d68ed9ba3f77c4cc8faa161218"
+  "gitHead": "8a6f829b0ea1544d2c5f7a1fd0cc0f08d6df7dcd"
 }

package/src/api/FirmwareUpdateV4.ts

@@ -32,13 +32,11 @@ import {
 } from '../protocols/protocol-v2';
 import { requestProtocolV2DeviceInfo } from '../protocols/protocol-v2/features';
 import {
-  PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_PATH,
   PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_STAGING_PATH,
   PROTOCOL_V2_RESOURCE_PACKAGE_HEADER_SIZE,
-  type ProtocolV2ResourcePackageHeader,
-  isProtocolV2ResourceArchiveEntryName,
   parseProtocolV2ResourcePackage,
   parseProtocolV2ResourcePackageHeader,
+  type ProtocolV2ResourcePackageHeader,
 } from '../protocols/protocol-v2/resources';
 import {
   getProtocolV2UnknownErrorText,
@@ -49,12 +47,20 @@ import {
   readFirmwareByteSourceFully,
   writeFirmwareByteSource,
 } from './firmware/FirmwareArtifactSource';
-import { resolveFirmwareUpdateHostBinding } from './firmware/FirmwareHostBinding';
+import {
+  registerFirmwareUpdateHostBinding,
+  resolveFirmwareUpdateHostBinding,
+  unregisterFirmwareUpdateHostBinding,
+} from './firmware/FirmwareHostBinding';
 import {
   assertFirmwareUpdatePreparedPlanBinding,
   assertFirmwareUpdatePreparedPlanDeviceIdentity,
+  prepareFirmwareUpdatePlan,
   validateFirmwareUpdatePreparedPlan,
 } from './firmware/FirmwareUpdatePreparedPlan';
+import { prepareFirmwareUpdateV4MemoryHost } from './firmware/FirmwareMemoryHost';
+import { buildProtocolV2LocalFirmwareUpdatePlan } from './firmware/FirmwareUpdatePlan';
+
 import type {
   FirmwareArtifactReference,
   FirmwareUpdateV4Params,
@@ -71,6 +77,11 @@ import type {
   KnownDevice,
 } from '../types';
 import type { FirmwareByteSource } from './firmware/FirmwareArtifactSource';
+import type {
+  FirmwareMemoryArtifact,
+  FirmwareMemoryArtifactEntry,
+  FirmwareUpdateV4MemoryHost,
+} from './firmware/FirmwareMemoryHost';
 
 const Log = getLogger(LoggerNames.Method);
 
@@ -219,6 +230,7 @@ type ProtocolV2ResourceBundleSource = {
 
 type ProtocolV2LocalResourceArchive = {
   binary: ArrayBuffer;
+  materializedEntries: FirmwareMemoryArtifactEntry[];
   resources: Array<{
     entryName: string;
     binary: ArrayBuffer;
@@ -780,7 +792,15 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
       this.params.resourceArchiveBinary &&
       this.params.targetsToUpdate?.includes('resource')
     ) {
-      return this.runProtocolV2DirectArtifacts({});
+      const localMemoryHost = await this.prepareProtocolV2LocalMemoryHost({
+        features: deviceFeatures,
+        firmwareType,
+      });
+      try {
+        return await this.runProtocolV2PreparedArtifacts(deviceFeatures, firmwareType);
+      } finally {
+        localMemoryHost.release();
+      }
     }
 
     const hasPreparedComponentArtifacts = Object.values(this.params.componentArtifacts ?? {}).some(
@@ -793,12 +813,12 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     let fwBinaryMap: ProtocolV2TargetBinary[] = [];
     let bootloaderBinary: ArrayBuffer | null = null;
     let installItems: ProtocolV2InstallItem[] | undefined;
-    let explicitInstallItems: ProtocolV2InstallItem[] | undefined;
+    let resourceMemoryHost: FirmwareUpdateV4MemoryHost | undefined;
     try {
       this.postTipMessage(FirmwareUpdateTipMessage.StartDownloadFirmware);
       fwBinaryMap = this.collectExplicitTargetBinaries();
       bootloaderBinary = this.prepareBootloaderBinary();
-      explicitInstallItems = this.buildProtocolV2InstallItems({
+      const explicitInstallItems = this.buildProtocolV2InstallItems({
         bootloaderBinary,
         fwBinaryMap,
       });
@@ -854,9 +874,15 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
           deviceFeatures,
           firmwareType
         );
+        resourceMemoryHost = await this.prepareProtocolV2LocalMemoryHost({
+          features: deviceFeatures,
+          firmwareType,
+          availableInstallItems: installItems ?? explicitInstallItems,
+        });
       }
       this.postTipMessage(FirmwareUpdateTipMessage.FinishDownloadFirmware);
     } catch (err) {
+      resourceMemoryHost?.release();
       if (
         typeof err === 'object' &&
         err !== null &&
@@ -871,11 +897,12 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
       throw normalizeFirmwarePreparationError(err);
     }
 
-    if (wantsResources && this.params.resourceArchiveBinary) {
-      return this.runProtocolV2DirectArtifacts({
-        availableInstallItems: installItems ?? explicitInstallItems,
-        announceDownload: false,
-      });
+    if (resourceMemoryHost) {
+      try {
+        return await this.runProtocolV2PreparedArtifacts(deviceFeatures, firmwareType, false);
+      } finally {
+        resourceMemoryHost.release();
+      }
     }
 
     if (!bootloaderBinary && fwBinaryMap.length === 0 && !installItems?.length) {
@@ -1028,69 +1055,133 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     return installSources;
   }
 
-  private async runProtocolV2DirectArtifacts({
-    availableInstallItems,
-    announceDownload = true,
+  private async prepareProtocolV2LocalMemoryHost({
+    features,
+    firmwareType,
+    availableInstallItems = this.buildProtocolV2InstallItems({
+      bootloaderBinary: this.prepareBootloaderBinary(),
+      fwBinaryMap: this.collectExplicitTargetBinaries(),
+    }),
   }: {
+    features: Features;
+    firmwareType: EFirmwareType;
     availableInstallItems?: ProtocolV2InstallItem[];
-    announceDownload?: boolean;
-  }) {
-    try {
-      if (announceDownload) {
-        this.postTipMessage(FirmwareUpdateTipMessage.StartDownloadFirmware);
-      }
-      const installItems = this.filterProtocolV2LocalInstallItems(
-        availableInstallItems ??
-          this.buildProtocolV2InstallItems({
-            bootloaderBinary: this.prepareBootloaderBinary(),
-            fwBinaryMap: this.collectExplicitTargetBinaries(),
-          })
-      );
-      const installSources = await Promise.all(
-        installItems.map(async item => ({
-          fileName: item.fileName,
-          source: await this.openProtocolV2MemorySource(item.binary),
-          targetId: item.targetId,
-          kind: item.kind,
-        }))
+  }): Promise<FirmwareUpdateV4MemoryHost> {
+    const requestedComponentTargets = new Set(
+      (this.params.targetsToUpdate ?? []).filter(
+        (target): target is Exclude<FirmwareUpdateV4Target, 'resource' | 'boot_resources'> =>
+          target !== 'resource' && target !== 'boot_resources'
+      )
+    );
+    const localComponentTargets = new Set(
+      availableInstallItems.flatMap(item => {
+        const target = PROTOCOL_V2_UPDATE_TARGET_BY_TARGET_ID.get(item.targetId);
+        return target ? [target] : [];
+      })
+    );
+    const missingTarget = Array.from(requestedComponentTargets).find(
+      target => !localComponentTargets.has(target)
+    );
+    if (missingTarget) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.RuntimeError,
+        `Protocol V2 local update has no binary for requested target ${missingTarget}`,
+        {
+          firmwareUpdateCode: 'FirmwareArtifactsNotPrepared',
+          artifactName: missingTarget,
+        }
       );
-      const resourceSources = this.params.resourceArchiveBinary
-        ? await this.createProtocolV2ResourceSourcesFromArchive(this.params.resourceArchiveBinary)
-        : [];
-      if (installSources.length === 0 && resourceSources.length === 0) {
+    }
+    const installItems = this.filterProtocolV2LocalInstallItems(availableInstallItems);
+
+    const planArtifacts: Parameters<typeof buildProtocolV2LocalFirmwareUpdatePlan>[0]['artifacts'] =
+      [];
+    const memoryArtifacts: FirmwareMemoryArtifact[] = [];
+    for (const item of installItems) {
+      const target = PROTOCOL_V2_UPDATE_TARGET_BY_TARGET_ID.get(item.targetId);
+      if (!target || item.binary.byteLength <= 0) {
         throw ERRORS.TypedError(
-          HardwareErrorCode.FirmwareUpdateDownloadFailed,
-          'No firmware to update'
+          HardwareErrorCode.RuntimeError,
+          `Protocol V2 local firmware artifact is invalid: ${item.fileName}`,
+          { firmwareUpdateCode: 'FirmwareArtifactsNotPrepared' }
         );
       }
-      if (announceDownload) {
-        this.postTipMessage(FirmwareUpdateTipMessage.FinishDownloadFirmware);
-      }
-      return await this.executeProtocolV2SourceUpdate({
-        installSources,
-        resourceSources,
+      const artifactId = `component:${target}`;
+      planArtifacts.push({
+        artifactId,
+        target,
+        container: 'raw',
+        logicalName: item.fileName,
+        expectedSize: item.binary.byteLength,
+        expectedSha256: bytesToHex(sha256(new Uint8Array(item.binary))),
+        ...(this.params.expectedTargetVersions?.[target]
+          ? { targetVersion: this.params.expectedTargetVersions[target] }
+          : {}),
       });
-    } finally {
-      await this.closeProtocolV2PreparedSources();
+      memoryArtifacts.push({ artifactId, binary: item.binary });
     }
-  }
 
-  private async createProtocolV2ResourceSourcesFromArchive(
-    binary: ArrayBuffer
-  ): Promise<ProtocolV2ResourceBundleSource[]> {
-    const archive = await this.prepareProtocolV2LocalResourceArchive(binary);
-    const sources: ProtocolV2ResourceBundleSource[] = [];
-    for (const resource of archive.resources) {
-      sources.push({
-        name: resource.entryName.split('/').pop() ?? resource.entryName,
-        source: await this.openProtocolV2MemorySource(resource.binary),
-        devicePath: resource.header.devicePath,
-        version: resource.header.version,
-        payloadHash: resource.header.payloadHash,
-        headerHash: resource.header.headerHash,
+    const resourceArchive = await this.prepareProtocolV2LocalResourceArchive(
+      this.params.resourceArchiveBinary as ArrayBuffer
+    );
+    const resourceArtifactId = 'resource:archive';
+    planArtifacts.push({
+      artifactId: resourceArtifactId,
+      target: 'resource',
+      container: 'zip',
+      logicalName: 'protocol-v2-local-resource-archive',
+      expectedSize: resourceArchive.binary.byteLength,
+      expectedSha256: bytesToHex(sha256(new Uint8Array(resourceArchive.binary))),
+    });
+    memoryArtifacts.push({
+      artifactId: resourceArtifactId,
+      binary: resourceArchive.binary,
+      materializedEntries: resourceArchive.materializedEntries,
+    });
+
+    const plan = buildProtocolV2LocalFirmwareUpdatePlan({
+      features,
+      firmwareType,
+      platform: this.params.platform,
+      artifacts: planArtifacts,
+    });
+    let memoryHost: FirmwareUpdateV4MemoryHost | undefined;
+    try {
+      memoryHost = prepareFirmwareUpdateV4MemoryHost({
+        sdk: {
+          prepareFirmwareUpdatePlan,
+          registerFirmwareUpdateHostBinding,
+          unregisterFirmwareUpdateHostBinding,
+        },
+        plan,
+        artifacts: memoryArtifacts,
       });
+      const preparedPlan = validateFirmwareUpdatePreparedPlan(memoryHost.preparedPlan);
+      assertFirmwareUpdatePreparedPlanBinding({
+        preparedPlan,
+        executor: 'v4',
+        platform: this.params.platform,
+        scopeTargets: [],
+        bindings: [],
+      });
+      assertFirmwareUpdatePreparedPlanDeviceIdentity({
+        preparedPlan,
+        deviceIdentity: this.protocolV2ExpectedSerialNumber,
+        deviceModel: this.getProtocolV2PreparedPlanDeviceModel(features),
+      });
+      const hostBinding = resolveFirmwareUpdateHostBinding(
+        memoryHost.hostBindingGeneration,
+        preparedPlan.preparedPlanDigest
+      );
+      this.params.preparedPlan = preparedPlan;
+      this.params.targetsToUpdate = [...preparedPlan.targetsToUpdate] as FirmwareUpdateV4Target[];
+      this.params.artifactReader = hostBinding.artifactReader;
+      this.params.componentArtifacts = undefined;
+      return memoryHost;
+    } catch (error) {
+      memoryHost?.release();
+      throw error;
     }
-    return sources;
   }
 
   private async prepareProtocolV2LocalResourceArchive(
@@ -1115,7 +1206,7 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     }
     const zipEntries = Object.values(zip.files);
     const resourceEntries = zipEntries.filter(
-      entry => !entry.dir && isProtocolV2ResourceArchiveEntryName(entry.name)
+      entry => !entry.dir && entry.name.toLowerCase().endsWith('.okpkg')
     );
     if (
       resourceEntries.length === 0 ||
@@ -1129,6 +1220,7 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     }
 
     let totalSize = 0;
+    const materializedEntries: FirmwareMemoryArtifactEntry[] = [];
     const resources: ProtocolV2LocalResourceArchive['resources'] = [];
     const devicePaths = new Set<string>();
     for (const entry of resourceEntries) {
@@ -1172,9 +1264,10 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
         );
       }
       devicePaths.add(canonicalDevicePath);
+      materializedEntries.push({ entryName: entry.name, binary: fileBinary });
       resources.push({ entryName: entry.name, binary: fileBinary, header });
     }
-    return { binary, resources };
+    return { binary, materializedEntries, resources };
   }
 
   private async prepareProtocolV2ResourceSources(): Promise<ProtocolV2ResourceBundleSource[]> {
@@ -1241,7 +1334,20 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
 
     // The verified ZIP bytes are authoritative. Non-okpkg entries are release
     // metadata only; each RESOURCE package carries its own device path.
-    return this.createProtocolV2ResourceSourcesFromArchive(archiveBinary);
+    const verifiedArchive = await this.prepareProtocolV2LocalResourceArchive(archiveBinary);
+    const sources: ProtocolV2ResourceBundleSource[] = [];
+    for (const resource of verifiedArchive.resources) {
+      const source = await this.openProtocolV2MemorySource(resource.binary);
+      sources.push({
+        name: resource.entryName.split('/').pop() ?? resource.entryName,
+        source,
+        devicePath: resource.header.devicePath,
+        version: resource.header.version,
+        payloadHash: resource.header.payloadHash,
+        headerHash: resource.header.headerHash,
+      });
+    }
+    return sources;
   }
 
   private async runProtocolV2PreparedArtifacts(
@@ -1725,12 +1831,6 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     return `vol0:/${path}`;
   }
 
-  private getProtocolV2ResourceComparePath(devicePath: string) {
-    return isProtocolV2BootResourcePackagePath(devicePath)
-      ? PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_PATH
-      : devicePath;
-  }
-
   private async readProtocolV2DeviceFileHeader(path: string, expectedSize?: number) {
     const typedCall = this.device.getCommands().typedCall.bind(this.device.getCommands());
     const filePath = this.getProtocolV2ResourceFilePath(path);
@@ -1793,7 +1893,7 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
 
     try {
       const header = await this.readProtocolV2DeviceFileHeader(
-        this.getProtocolV2ResourceComparePath(bundle.devicePath),
+        bundle.devicePath,
         bundle.source.size
       );
       if (!header) return false;
@@ -2052,7 +2152,11 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     let totalSize = installSources.reduce((total, item) => total + item.source.size, 0);
     const resourcesToSync: ProtocolV2ResourceBundleSource[] = [];
     for (const resource of resourceSources) {
-      if (await this.isProtocolV2ResourceBundleUpToDate(resource)) {
+      // Early boot promotes this mounted package's staging file. Always replace any
+      // stale staging bytes with the artifact approved by the current PreparedPlan,
+      // even when the mounted final file itself is already current.
+      const requiresFreshStaging = isProtocolV2BootResourcePackagePath(resource.devicePath);
+      if (!requiresFreshStaging && (await this.isProtocolV2ResourceBundleUpToDate(resource))) {
         Log.log(`[FirmwareUpdateV4] skip RESC bundle ${resource.name}; already up to date`);
       } else {
         resourcesToSync.push(resource);

package/src/api/SearchDevices.ts

@@ -1,4 +1,4 @@
-import { canonicalizePro2BleAdvertisementName } from '@onekeyfe/hd-shared';
+import { normalizePro2FindMyAdvertisementName } from '@onekeyfe/hd-shared';
 
 import { BaseMethod } from './BaseMethod';
 import TransportManager from '../data-manager/TransportManager';
@@ -40,7 +40,7 @@ export default class SearchDevices extends BaseMethod {
           seenIds.add(lowerId);
           const rawBleName =
             device.name ?? (device as unknown as { localName?: string }).localName ?? '';
-          const bleName = canonicalizePro2BleAdvertisementName(rawBleName);
+          const bleName = normalizePro2FindMyAdvertisementName(rawBleName);
           devices.push({
             ...device,
             connectId: device.id,

package/src/api/firmware/FirmwareMemoryHost.ts

@@ -0,0 +1,143 @@
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex } from '@noble/hashes/utils';
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import type { CoreApi } from '../../types/api';
+import type {
+  FirmwareArtifactReader,
+  FirmwareArtifactReference,
+} from '../../types/api/firmwareUpdate';
+import type { FirmwareUpdatePlan } from '../../types/api/firmwareUpdatePlan';
+
+export type FirmwareMemoryArtifactEntry = {
+  entryName: string;
+  binary: ArrayBuffer;
+};
+
+export type FirmwareMemoryArtifact = {
+  artifactId: string;
+  binary: ArrayBuffer;
+  materializedEntries?: FirmwareMemoryArtifactEntry[];
+};
+
+export type FirmwareUpdateV4MemoryHost = {
+  preparedPlan: ReturnType<CoreApi['prepareFirmwareUpdatePlan']>;
+  hostBindingGeneration: number;
+  release: () => void;
+};
+
+let memoryHostSequence = 0;
+
+const createReference = (binary: ArrayBuffer, prefix: string): FirmwareArtifactReference => {
+  const digest = bytesToHex(sha256(new Uint8Array(binary)));
+  return {
+    artifactRef: `fwmem:${prefix}:${digest.slice(0, 32)}`,
+    size: binary.byteLength,
+    sha256: digest,
+  };
+};
+
+export function prepareFirmwareUpdateV4MemoryHost({
+  sdk,
+  plan,
+  artifacts,
+}: {
+  sdk: Pick<
+    CoreApi,
+    | 'prepareFirmwareUpdatePlan'
+    | 'registerFirmwareUpdateHostBinding'
+    | 'unregisterFirmwareUpdateHostBinding'
+  >;
+  plan: FirmwareUpdatePlan;
+  artifacts: FirmwareMemoryArtifact[];
+}): FirmwareUpdateV4MemoryHost {
+  if (plan.executor !== 'v4') {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      'Firmware memory host only supports V4 plans'
+    );
+  }
+  memoryHostSequence += 1;
+  const hostId = `${Date.now()}:${memoryHostSequence}`;
+  const binaries = new Map<string, Uint8Array>();
+  const inputs = artifacts.map((input, artifactIndex) => {
+    const artifactBinary = new Uint8Array(input.binary).slice();
+    const artifact = createReference(
+      artifactBinary.buffer as ArrayBuffer,
+      `${hostId}:artifact:${artifactIndex}`
+    );
+    binaries.set(artifact.artifactRef, artifactBinary);
+    const materializedEntries = input.materializedEntries?.map((entry, entryIndex) => {
+      const entryArtifact = createReference(
+        entry.binary,
+        `${hostId}:entry:${artifactIndex}:${entryIndex}`
+      );
+      // Entry references are compact receipts for bytes that will be re-derived
+      // from the verified archive. Retaining another readable copy here doubles
+      // resource memory without adding an execution trust boundary.
+      return {
+        entryName: entry.entryName,
+        artifact: entryArtifact,
+      };
+    });
+    return {
+      artifactId: input.artifactId,
+      artifact,
+      ...(materializedEntries?.length ? { materializedEntries } : {}),
+    };
+  });
+  const preparedPlan = sdk.prepareFirmwareUpdatePlan({
+    plan,
+    leaseRef: `fwmemlease:${hostId}`,
+    artifacts: inputs,
+  });
+  const readers = new Map<string, Uint8Array>();
+  let readerSequence = 0;
+  const artifactReader: FirmwareArtifactReader = {
+    open({ artifactRef }) {
+      const binary = binaries.get(artifactRef);
+      if (!binary) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.RuntimeError,
+          'Firmware memory artifact is unavailable'
+        );
+      }
+      readerSequence += 1;
+      const readerId = `fwmemreader:${hostId}:${readerSequence}`;
+      readers.set(readerId, binary);
+      return Promise.resolve({ readerId, size: binary.byteLength });
+    },
+    read({ readerId, offset, length }) {
+      const binary = readers.get(readerId);
+      if (!binary || offset < 0 || length <= 0 || offset + length > binary.byteLength) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.RuntimeError,
+          'Firmware memory artifact read is invalid'
+        );
+      }
+      const data = binary.slice(offset, offset + length).buffer;
+      return Promise.resolve({
+        data,
+        bytesRead: data.byteLength,
+        eof: offset + length === binary.byteLength,
+      });
+    },
+    close({ readerId }) {
+      readers.delete(readerId);
+      return Promise.resolve();
+    },
+  };
+  const hostBindingGeneration = sdk.registerFirmwareUpdateHostBinding({
+    artifactReader,
+    preparedPlanDigest: preparedPlan.preparedPlanDigest,
+  });
+  return {
+    preparedPlan,
+    hostBindingGeneration,
+    release: () => {
+      sdk.unregisterFirmwareUpdateHostBinding(hostBindingGeneration);
+      readers.clear();
+      binaries.clear();
+    },
+  };
+}

package/src/api/firmware/FirmwareUpdatePlan.ts

@@ -654,6 +654,47 @@ 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,

package/src/api/firmware/FirmwareUpdatePreparedPlan.ts

@@ -71,13 +71,6 @@ 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');
@@ -148,8 +141,11 @@ const assertPreparedArtifacts = ({
     }
     if (
       materializedEntries &&
-      new Set(materializedEntries.map(entry => getPreparedEntryIdentity(entry.entryName))).size !==
-        materializedEntries.length
+      new Set(
+        materializedEntries.map(entry =>
+          getFirmwareUpdateResourceName(entry.entryName).toLowerCase()
+        )
+      ).size !== materializedEntries.length
     ) {
       return preparedPlanError('Firmware prepared plan contains duplicate entry names');
     }
@@ -285,7 +281,7 @@ export const validateFirmwareUpdatePreparedPlan = (value: unknown): FirmwareUpda
     const materializedEntryNames =
       artifact.materializedEntries?.map(entry => {
         assertPreparedEntry(entry);
-        return getPreparedEntryIdentity(entry.entryName);
+        return getFirmwareUpdateResourceName(entry.entryName).toLowerCase();
       }) ?? [];
     if (new Set(materializedEntryNames).size !== materializedEntryNames.length) {
       return preparedPlanError('Firmware prepared plan contains duplicate entry names');