@onekeyfe/hd-core 1.2.0-alpha.40 → 1.2.0-alpha.41

package/src/api/GetPassphraseState.ts

@@ -1,5 +1,4 @@
 import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
-import { DeviceSessionPinType } from '@onekeyfe/hd-transport';
 
 import { UI_REQUEST } from '../constants/ui-request';
 import { refreshProtocolV2DeviceStatus } from '../protocols/protocol-v2/walletSession';
@@ -25,12 +24,7 @@ export default class GetPassphraseState extends BaseMethod {
     if (isProtocolV2 && this.payload.useEmptyPassphrase !== true) {
       const features = await refreshProtocolV2DeviceStatus(this.device);
       if (features.unlocked === false) {
-        await this.device.unlockDevice(DeviceSessionPinType.Main, {
-          source: 'unlock-coordinator',
-          reason: 'device-locked',
-          deviceOnly: true,
-          method: 'getPassphraseState',
-        });
+        await this.device.unlockDevice();
       }
     }
     const { passphraseState } = await getPassphraseStateWithRefreshDeviceInfo(

package/src/api/OpenWalletSession.ts

@@ -1,5 +1,4 @@
 import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
-import { DeviceSessionPinType } from '@onekeyfe/hd-transport';
 
 import { deviceWalletSessionStore } from '../device/DeviceWalletSessionStore';
 import { getProtocolV2WalletSession } from '../protocols/protocol-v2/walletSession';
@@ -91,40 +90,23 @@ export default class OpenWalletSession extends BaseMethod<OpenWalletSessionParam
 
   async run(): Promise<OpenWalletSessionPayload> {
     const isProtocolV2 = this.device.isProtocolV2();
-    let state = await this.device.getDeviceState({ refreshSections: ['status'] });
+    const state = await this.device.getDeviceState({ refreshSections: ['status'] });
     let currentDeviceId = state.identity.deviceId;
-    const hasAuthoritativeProtocolV2WalletStatus = (candidate: typeof state) =>
-      candidate.status.unlocked === true &&
-      typeof candidate.status.passphraseProtection === 'boolean' &&
-      typeof candidate.status.unlockedAttachPin === 'boolean';
-    const requireAuthoritativeProtocolV2WalletStatus = (candidate: typeof state) => {
-      if (!hasAuthoritativeProtocolV2WalletStatus(candidate)) {
-        throw ERRORS.TypedError(HardwareErrorCode.DeviceInitializeFailed);
-      }
-      return candidate;
-    };
     const requireDeviceId = () => {
       if (!currentDeviceId) {
         throw ERRORS.TypedError(HardwareErrorCode.DeviceInitializeFailed);
       }
       return currentDeviceId;
     };
-    const refreshProtocolV2DeviceState = async () => {
-      state = await this.device.getDeviceState({ refreshSections: ['status'] });
-      currentDeviceId = state.identity.deviceId;
-      return state;
+    const refreshProtocolV2DeviceId = async () => {
+      const refreshedState = await this.device.getDeviceState({ refreshSections: ['status'] });
+      currentDeviceId = refreshedState.identity.deviceId;
+      return requireDeviceId();
     };
-    const ensureProtocolV2WalletStatus = async () => {
-      if (isProtocolV2 && !hasAuthoritativeProtocolV2WalletStatus(state)) {
-        await this.device.unlockDevice(DeviceSessionPinType.Main, {
-          source: 'unlock-coordinator',
-          reason: 'device-locked',
-          deviceOnly: true,
-          method: 'openWalletSession',
-        });
-        requireAuthoritativeProtocolV2WalletStatus(await refreshProtocolV2DeviceState());
+    const unlockProtocolV2IfLocked = async () => {
+      if (isProtocolV2 && state.status.unlocked === false) {
+        await this.device.unlockDevice();
       }
-      return state;
     };
 
     const protocol = isProtocolV2 ? 'V2' : 'V1';
@@ -132,25 +114,13 @@ export default class OpenWalletSession extends BaseMethod<OpenWalletSessionParam
     if (this.params.mode === OpenWalletSessionMode.Standard) {
       this.device.passphraseState = undefined;
       const session = isProtocolV2
-        ? await getProtocolV2WalletSession(this.device, {
-            onlyMainPin: true,
-            deriveCardano: this.payload.deriveCardano,
-            selectMainWalletBeforeRestore:
-              !hasAuthoritativeProtocolV2WalletStatus(state) ||
-              state.status.unlockedAttachPin === true,
-          })
+        ? await getProtocolV2WalletSession(this.device, { onlyMainPin: true })
         : await getPassphraseStateWithRefreshDeviceInfo(this.device, {
             onlyMainPin: true,
             initSession: this.payload.initSession,
           });
-      const refreshedState = isProtocolV2
-        ? requireAuthoritativeProtocolV2WalletStatus(await refreshProtocolV2DeviceState())
-        : state;
-      const deviceId = requireDeviceId();
-      if (
-        session.unlockedAttachPin ||
-        (isProtocolV2 && refreshedState.status.unlockedAttachPin === true)
-      ) {
+      const deviceId = isProtocolV2 ? await refreshProtocolV2DeviceId() : requireDeviceId();
+      if (session.unlockedAttachPin) {
         try {
           await this.device.lockDevice();
         } catch {
@@ -170,8 +140,8 @@ export default class OpenWalletSession extends BaseMethod<OpenWalletSessionParam
 
     if (this.params.mode === OpenWalletSessionMode.ResumeHidden) {
       if (isProtocolV2) {
-        await ensureProtocolV2WalletStatus();
-        const refreshedDeviceId = requireDeviceId();
+        await unlockProtocolV2IfLocked();
+        const refreshedDeviceId = await refreshProtocolV2DeviceId();
         if (refreshedDeviceId !== this.params.deviceId) {
           deviceWalletSessionStore.delete(this.params.deviceId, this.params.passphraseState);
           throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckDeviceIdError);
@@ -196,7 +166,6 @@ export default class OpenWalletSession extends BaseMethod<OpenWalletSessionParam
       const session = isProtocolV2
         ? await getProtocolV2WalletSession(this.device, {
             expectedPassphraseState: this.params.passphraseState,
-            deriveCardano: this.payload.deriveCardano,
           })
         : await getPassphraseStateWithRefreshDeviceInfo(this.device, {
             expectPassphraseState: this.params.passphraseState,
@@ -216,18 +185,12 @@ export default class OpenWalletSession extends BaseMethod<OpenWalletSessionParam
     }
 
     this.device.passphraseState = undefined;
-    await ensureProtocolV2WalletStatus();
+    await unlockProtocolV2IfLocked();
     const session = isProtocolV2
-      ? await getProtocolV2WalletSession(this.device, {
-          forceWalletSelection: true,
-          deriveCardano: this.payload.deriveCardano,
-        })
+      ? await getProtocolV2WalletSession(this.device, { forceWalletSelection: true })
       : await getPassphraseStateWithRefreshDeviceInfo(this.device, { initSession: true });
-    const refreshedState = isProtocolV2
-      ? requireAuthoritativeProtocolV2WalletStatus(await refreshProtocolV2DeviceState())
-      : state;
-    const deviceId = requireDeviceId();
-    if (isProtocolV2 && refreshedState.status.passphraseProtection !== true) {
+    const deviceId = isProtocolV2 ? await refreshProtocolV2DeviceId() : requireDeviceId();
+    if (isProtocolV2 && this.device.getCurrentPassphraseProtection() !== true) {
       this.device.clearInternalState();
       throw ERRORS.TypedError(HardwareErrorCode.DeviceNotOpenedPassphrase);
     }

package/src/api/allnetwork/AllNetworkGetAddressBase.ts

@@ -14,7 +14,6 @@ import { findMethod } from '../utils';
 import { DEVICE, IFRAME, createUiMessage } from '../../events';
 import { UI_REQUEST } from '../../constants/ui-request';
 import { onDeviceButtonHandler } from '../../core';
-import { runMethodWithUnlockPolicy } from '../../protocols/protocol-v2/unlockPolicyRunner';
 import {
   completeRequestContext,
   createRequestContext,
@@ -376,34 +375,16 @@ export default abstract class AllNetworkGetAddressBase extends BaseMethod<
       this.device.on(DEVICE.PASSPHRASE, onSignalAbort);
 
       preCheckDeviceSupport(this.device, method);
-      const response = await runMethodWithUnlockPolicy<any[]>(method, this.device, {
-        context: this.protocolV2UnlockContext,
-        prepare: async () => {
-          if (this.temporarySafetyCheckPrompted) {
-            method.temporarySafetyCheckPrompted = true;
-          } else {
-            const appliedTemporarySafetyCheck = await method.checkSafetyLevelOnTestNet();
-            if (appliedTemporarySafetyCheck) {
-              this.temporarySafetyCheckPrompted = true;
-            }
-          }
-
-          // Protocol V2 hands a wallet session to exactly one blockchain request.
-          // The parent all-network call consumes its first handoff while fetching
-          // the root fingerprint, so each nested chain method must resume the
-          // requested hidden wallet before it sends its own device command.
-          if (this.device.isProtocolV2() && this.payload.passphraseState) {
-            const passphraseStateSafety = await this.device.checkPassphraseStateSafety(
-              this.payload.passphraseState,
-              false,
-              this.payload.skipPassphraseCheck
-            );
-            if (!passphraseStateSafety) {
-              throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckPassphraseStateError);
-            }
-          }
-        },
-      });
+      if (this.temporarySafetyCheckPrompted) {
+        method.temporarySafetyCheckPrompted = true;
+      } else {
+        const appliedTemporarySafetyCheck = await method.checkSafetyLevelOnTestNet();
+        if (appliedTemporarySafetyCheck) {
+          this.temporarySafetyCheckPrompted = true;
+        }
+      }
+
+      const response = await method.run();
 
       if (!Array.isArray(response) || response.length === 0) {
         throw new Error('No response');
@@ -458,9 +439,7 @@ export default abstract class AllNetworkGetAddressBase extends BaseMethod<
       show_display: false,
     });
 
-    if (!this.device.isProtocolV2()) {
-      this.postMessage(createUiMessage(UI_REQUEST.CLOSE_UI_PIN_WINDOW));
-    }
+    this.postMessage(createUiMessage(UI_REQUEST.CLOSE_UI_PIN_WINDOW));
 
     if (res.message.root_fingerprint == null) {
       throw ERRORS.TypedError(HardwareErrorCode.CallMethodInvalidParameter);

package/src/api/device/DeviceUnlock.ts

@@ -21,6 +21,6 @@ export default class DeviceUnlock extends BaseMethod<LockDevice> {
   }
 
   async run() {
-    return this.device.unlockDevice(undefined, { emitUiEvent: false });
+    return this.device.unlockDevice();
   }
 }

package/src/api/device/DeviceUpdateBootloader.ts

@@ -5,15 +5,23 @@ import { UI_REQUEST } from '../../constants/ui-request';
 import { FirmwareUpdateTipMessage } from '../../events/ui-request';
 import { FirmwareUpdateBaseMethod } from '../firmware/FirmwareUpdateBaseMethod';
 import { getSysResourceBinary } from '../firmware/getBinary';
-import { updateBootloader } from '../firmware/uploadFirmware';
+import { updateBootloader, updateBootloaderFromSource } from '../firmware/uploadFirmware';
 import { DeviceModelToTypes } from '../../types';
 import { DataManager } from '../../data-manager';
-import { checkBootloaderLength } from '../firmware/updateBootloader';
+import { checkBootloaderLength, checkBootloaderSourceLength } from '../firmware/updateBootloader';
+import { openFirmwareByteSource } from '../firmware/FirmwareArtifactSource';
+import { resolveFirmwareUpdateHostBinding } from '../firmware/FirmwareHostBinding';
+import {
+  assertFirmwareUpdatePreparedPlanBinding,
+  assertFirmwareUpdatePreparedPlanDeviceIdentity,
+} from '../firmware/FirmwareUpdatePreparedPlan';
+import { getDeviceUUID } from '../../utils';
 
 import type { DeviceUpdateBootloaderParams } from '../../types/api/deviceUpdateBootloader';
 import type { EFirmwareType } from '@onekeyfe/hd-shared';
 import type { Device } from '../../device/Device';
 import type { Features } from '../../types';
+import type { FirmwareByteSource } from '../firmware/FirmwareArtifactSource';
 
 export default class DeviceUpdateBootloader extends FirmwareUpdateBaseMethod<any> {
   init() {
@@ -43,17 +51,68 @@ export default class DeviceUpdateBootloader extends FirmwareUpdateBaseMethod<any
     return true;
   }
 
+  async updateBootloaderWithEmmcFileWriteFromSource(_device: Device, source: FirmwareByteSource) {
+    const filePath = '0:boot/bootloader.bin';
+
+    this.postTipMessage(FirmwareUpdateTipMessage.StartTransferData);
+    await this.emmcCommonUpdateProcessFromSource({
+      source,
+      filePath,
+    });
+    this.postTipMessage(FirmwareUpdateTipMessage.ConfirmOnDevice);
+    await this.reboot(RebootType.Normal);
+    this.postTipMessage(FirmwareUpdateTipMessage.UpdateBootloaderSuccess);
+    return true;
+  }
+
   async updateTouchBootloader({
     device,
     features,
     firmwareType,
+    binary: preparedBinary,
+    source: preparedSource,
   }: {
     device: Device;
     features?: Features;
     firmwareType: EFirmwareType;
+    binary?: ArrayBuffer;
+    source?: FirmwareByteSource;
   }) {
-    let { binary } = this.payload;
+    if (preparedSource) {
+      if (!(await checkBootloaderSourceLength(preparedSource))) {
+        throw ERRORS.TypedError(HardwareErrorCode.CheckDownloadFileError);
+      }
+      if (features && device.isBootloader()) {
+        this.postTipMessage(FirmwareUpdateTipMessage.UpdateBootloader);
+        const result = await this.updateBootloaderWithEmmcFileWriteFromSource(
+          device,
+          preparedSource
+        );
+        return result;
+      }
+      if (features && !device.isBootloader()) {
+        await updateBootloaderFromSource(
+          this.device.getCommands().typedCall.bind(this.device.getCommands()),
+          this.postMessage,
+          device,
+          preparedSource
+        );
+        return true;
+      }
+    }
+
+    let binary = preparedBinary;
     if (!binary) {
+      if (DataManager.getSettings('firmwareManifestMode') === 'external-only') {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.RuntimeError,
+          'Bootloader must be prepared by the external firmware host',
+          {
+            firmwareUpdateCode: 'FirmwareArtifactsNotPrepared',
+            artifactName: 'bootloader',
+          }
+        );
+      }
       this.postTipMessage(FirmwareUpdateTipMessage.CheckLatestUiResource);
       const resourceUrl = features
         ? DataManager.getBootloaderResource(features, firmwareType)
@@ -68,7 +127,7 @@ export default class DeviceUpdateBootloader extends FirmwareUpdateBaseMethod<any
       }
     }
 
-    if (!checkBootloaderLength(binary)) {
+    if (!binary || !checkBootloaderLength(binary)) {
       throw ERRORS.TypedError(HardwareErrorCode.CheckDownloadFileError);
     }
 
@@ -76,7 +135,8 @@ export default class DeviceUpdateBootloader extends FirmwareUpdateBaseMethod<any
     if (features && device.isBootloader()) {
       // Use emmcFileWrite + reboot logic for bootloader mode
       this.postTipMessage(FirmwareUpdateTipMessage.UpdateBootloader);
-      return this.updateBootloaderWithEmmcFileWrite(device, binary);
+      const result = await this.updateBootloaderWithEmmcFileWrite(device, binary);
+      return result;
     }
 
     if (features && !device.isBootloader()) {
@@ -96,13 +156,69 @@ export default class DeviceUpdateBootloader extends FirmwareUpdateBaseMethod<any
     const { features } = device;
 
     const payload = this.payload as DeviceUpdateBootloaderParams;
+    const hostBinding = payload.artifact
+      ? resolveFirmwareUpdateHostBinding(payload.hostBindingGeneration)
+      : undefined;
+    const executionParams = {
+      ...payload,
+      artifactReader: hostBinding?.artifactReader ?? payload.artifactReader,
+    };
+    if (payload.artifact) {
+      assertFirmwareUpdatePreparedPlanDeviceIdentity({
+        preparedPlan: payload.preparedPlan,
+        deviceIdentity: getDeviceUUID(features) || undefined,
+      });
+      assertFirmwareUpdatePreparedPlanBinding({
+        preparedPlan: payload.preparedPlan,
+        executor: 'v2',
+        scopeTargets: ['bootloader'],
+        bindings: [
+          {
+            target: 'bootloader',
+            artifact: payload.artifact,
+          },
+        ],
+      });
+      const source = await openFirmwareByteSource({
+        artifact: payload.artifact,
+        reader: executionParams.artifactReader,
+      });
+      if (!source) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.RuntimeError,
+          'Bootloader artifact is not prepared'
+        );
+      }
+      try {
+        const deviceType = device.getCurrentDeviceType();
+        const deviceFirmwareType = device.getCurrentFirmwareType();
+        const firmwareType = payload.firmwareType ?? deviceFirmwareType;
+        if (DeviceModelToTypes.model_touch.includes(deviceType)) {
+          return await this.updateTouchBootloader({
+            device,
+            features,
+            firmwareType,
+            source,
+          });
+        }
+        return true;
+      } finally {
+        await source.close();
+      }
+    }
 
+    const { binary } = payload;
     const deviceType = device.getCurrentDeviceType();
     const deviceFirmwareType = device.getCurrentFirmwareType();
     const firmwareType = payload.firmwareType ?? deviceFirmwareType;
 
     if (DeviceModelToTypes.model_touch.includes(deviceType)) {
-      return this.updateTouchBootloader({ device, features, firmwareType });
+      return this.updateTouchBootloader({
+        device,
+        features,
+        firmwareType,
+        binary,
+      });
     }
 
     return Promise.resolve(true);

package/src/api/firmware/FirmwareArtifactSource.ts

@@ -0,0 +1,278 @@
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import type {
+  FirmwareArtifactReader,
+  FirmwareArtifactReference,
+} from '../../types/api/firmwareUpdate';
+
+export const MAX_FIRMWARE_ARTIFACT_READ_BYTES = 256 * 1024;
+
+export interface FirmwareByteSource {
+  readonly size: number;
+  readAt(offset: number, length: number): Promise<ArrayBuffer>;
+  close(): Promise<void>;
+}
+
+const artifactError = (
+  code:
+    | 'FirmwareArtifactReceiptMismatch'
+    | 'FirmwareArtifactReaderInvalid'
+    | 'FirmwareArtifactReadOutOfBounds'
+    | 'FirmwareArtifactReadTooLarge',
+  message: string
+): never => {
+  throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, message, {
+    firmwareUpdateCode: code,
+  });
+};
+
+const assertSafeSize = (value: number, name: string) => {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    artifactError('FirmwareArtifactReceiptMismatch', `${name} must be a positive safe integer`);
+  }
+};
+
+export const assertFirmwareArtifactReference = (
+  artifact: FirmwareArtifactReference
+): FirmwareArtifactReference => {
+  if (
+    !artifact ||
+    typeof artifact.artifactRef !== 'string' ||
+    artifact.artifactRef.length === 0 ||
+    artifact.artifactRef.length > 160 ||
+    artifact.artifactRef.includes('/') ||
+    artifact.artifactRef.includes('\\')
+  ) {
+    artifactError(
+      'FirmwareArtifactReceiptMismatch',
+      'Firmware artifactRef must be an opaque identifier'
+    );
+  }
+  assertSafeSize(artifact.size, 'Firmware artifact size');
+  if (typeof artifact.sha256 !== 'string' || !/^[a-f0-9]{64}$/i.test(artifact.sha256)) {
+    artifactError(
+      'FirmwareArtifactReceiptMismatch',
+      'Firmware artifact sha256 must be a 32-byte hexadecimal digest'
+    );
+  }
+  return artifact;
+};
+
+const assertFirmwareArtifactRead = (size: number, offset: number, length: number) => {
+  if (
+    !Number.isSafeInteger(offset) ||
+    offset < 0 ||
+    offset >= size ||
+    !Number.isSafeInteger(length) ||
+    length <= 0 ||
+    offset + length > size
+  ) {
+    artifactError(
+      'FirmwareArtifactReadOutOfBounds',
+      `Firmware artifact read is outside size ${size}: offset=${offset}, length=${length}`
+    );
+  }
+  if (length > MAX_FIRMWARE_ARTIFACT_READ_BYTES) {
+    artifactError(
+      'FirmwareArtifactReadTooLarge',
+      `Firmware artifact read length ${length} exceeds ${MAX_FIRMWARE_ARTIFACT_READ_BYTES}`
+    );
+  }
+};
+
+const createMemoryFirmwareByteSource = (binary: ArrayBuffer): FirmwareByteSource => {
+  let bytes: Uint8Array | null = new Uint8Array(binary);
+  const { byteLength: size } = binary;
+  assertSafeSize(size, 'Firmware binary size');
+  return {
+    size,
+    readAt: (offset, length) => {
+      if (!bytes) {
+        return Promise.reject(
+          ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Firmware byte source is closed', {
+            firmwareUpdateCode: 'FirmwareArtifactReaderInvalid',
+          })
+        );
+      }
+      assertFirmwareArtifactRead(size, offset, length);
+      return Promise.resolve(bytes.slice(offset, offset + length).buffer);
+    },
+    close: () => {
+      bytes = null;
+      return Promise.resolve();
+    },
+  };
+};
+
+class ReaderFirmwareByteSource implements FirmwareByteSource {
+  readonly size: number;
+
+  private closed = false;
+
+  private reading = false;
+
+  private constructor(
+    private readonly reader: FirmwareArtifactReader,
+    private readonly readerId: string,
+    size: number
+  ) {
+    this.size = size;
+  }
+
+  static async open(
+    artifact: FirmwareArtifactReference,
+    reader: FirmwareArtifactReader
+  ): Promise<ReaderFirmwareByteSource> {
+    const opened = await reader.open({ artifactRef: artifact.artifactRef });
+    if (
+      !opened ||
+      typeof opened.readerId !== 'string' ||
+      opened.readerId.length === 0 ||
+      !Number.isSafeInteger(opened.size) ||
+      opened.size !== artifact.size
+    ) {
+      if (opened?.readerId) {
+        await reader.close({ readerId: opened.readerId }).catch(() => undefined);
+      }
+      return artifactError(
+        'FirmwareArtifactReceiptMismatch',
+        `Firmware artifact opened with size ${opened?.size ?? 'unknown'}, expected ${artifact.size}`
+      );
+    }
+    return new ReaderFirmwareByteSource(reader, opened.readerId, opened.size);
+  }
+
+  async readAt(offset: number, length: number): Promise<ArrayBuffer> {
+    if (this.closed) {
+      return artifactError('FirmwareArtifactReaderInvalid', 'Firmware artifact reader is closed');
+    }
+    if (this.reading) {
+      return artifactError(
+        'FirmwareArtifactReaderInvalid',
+        'Firmware artifact reader only permits one in-flight read'
+      );
+    }
+    assertFirmwareArtifactRead(this.size, offset, length);
+    this.reading = true;
+    try {
+      const result = await this.reader.read({
+        readerId: this.readerId,
+        offset,
+        length,
+      });
+      const expectedEof = offset + length === this.size;
+      if (
+        !result ||
+        !(result.data instanceof ArrayBuffer) ||
+        result.data.byteLength !== length ||
+        result.bytesRead !== length ||
+        result.eof !== expectedEof
+      ) {
+        return artifactError(
+          'FirmwareArtifactReaderInvalid',
+          'Firmware artifact reader returned an invalid read result'
+        );
+      }
+      return result.data;
+    } finally {
+      this.reading = false;
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    await this.reader.close({ readerId: this.readerId });
+  }
+}
+
+export const openFirmwareByteSource = async ({
+  binary,
+  artifact,
+  reader,
+}: {
+  binary?: ArrayBuffer;
+  artifact?: FirmwareArtifactReference;
+  reader?: FirmwareArtifactReader;
+}): Promise<FirmwareByteSource | null> => {
+  if (binary && artifact) {
+    return artifactError(
+      'FirmwareArtifactReceiptMismatch',
+      'Firmware input must not contain both binary and artifactRef'
+    );
+  }
+  if (binary) {
+    return createMemoryFirmwareByteSource(binary);
+  }
+  if (!artifact) {
+    return null;
+  }
+  assertFirmwareArtifactReference(artifact);
+  if (!reader) {
+    return artifactError(
+      'FirmwareArtifactReaderInvalid',
+      'Firmware artifact reader is required for artifactRef input'
+    );
+  }
+  return ReaderFirmwareByteSource.open(artifact, reader);
+};
+
+export const readFirmwareByteSourceFully = async (
+  source: FirmwareByteSource
+): Promise<ArrayBuffer> => {
+  const output = new Uint8Array(source.size);
+  let offset = 0;
+  while (offset < source.size) {
+    const length = Math.min(MAX_FIRMWARE_ARTIFACT_READ_BYTES, source.size - offset);
+    output.set(new Uint8Array(await source.readAt(offset, length)), offset);
+    offset += length;
+  }
+  return output.buffer;
+};
+
+export const writeFirmwareByteSource = async ({
+  source,
+  chunkSize,
+  write,
+}: {
+  source: FirmwareByteSource;
+  chunkSize: number;
+  write: (input: {
+    data: ArrayBuffer;
+    sourceOffset: number;
+    length: number;
+    first: boolean;
+  }) => Promise<number>;
+}) => {
+  if (
+    !Number.isSafeInteger(chunkSize) ||
+    chunkSize <= 0 ||
+    chunkSize > MAX_FIRMWARE_ARTIFACT_READ_BYTES
+  ) {
+    return artifactError(
+      'FirmwareArtifactReadTooLarge',
+      `Firmware artifact chunk size must be between 1 and ${MAX_FIRMWARE_ARTIFACT_READ_BYTES}`
+    );
+  }
+  let offset = 0;
+  while (offset < source.size) {
+    const length = Math.min(chunkSize, source.size - offset);
+    const data = await source.readAt(offset, length);
+    const processed = await write({
+      data,
+      sourceOffset: offset,
+      length,
+      first: offset === 0,
+    });
+    if (processed !== length) {
+      return artifactError(
+        'FirmwareArtifactReaderInvalid',
+        `Firmware artifact writer processed ${processed} bytes, expected ${length}`
+      );
+    }
+    offset += length;
+  }
+  return offset;
+};