@onekeyfe/hd-core 1.2.0-alpha.5 → 1.2.0-alpha.50

package/src/api/evm/EVMSignTransaction.ts

@@ -5,9 +5,9 @@ import { validatePath } from '../helpers/pathUtils';
 import { BaseMethod } from '../BaseMethod';
 import { validateParams } from '../helpers/paramsValidator';
 import { formatAnyHex } from '../helpers/hexUtils';
-import TransportManager from '../../data-manager/TransportManager';
 import { signTransaction } from './latest/signTransaction';
 import { signTransaction as signTransactionLegacyV1 } from './legacyV1/signTransaction';
+import { shouldUseLegacyV1EvmMessages } from './protocol';
 
 import type {
   EVMSignTransactionParams,
@@ -18,6 +18,10 @@ import type {
 import type { SchemaParam } from '../helpers/paramsValidator';
 
 export default class EVMSignTransaction extends BaseMethod {
+  getSupportedProtocols() {
+    return ['V1', 'V2'] as const;
+  }
+
   addressN: number[] = [];
 
   isEIP1559 = false;
@@ -122,7 +126,7 @@ export default class EVMSignTransaction extends BaseMethod {
 
     if (formattedTx == null) throw ERRORS.TypedError('Runtime', 'formattedTx is not set');
 
-    if (TransportManager.getProtocolV1MessageSchema() === 'v1LegacySchema') {
+    if (shouldUseLegacyV1EvmMessages(this.device)) {
       return signTransactionLegacyV1({
         typedCall: this.device.commands.typedCall.bind(this.device.commands),
         addressN,

package/src/api/evm/EVMSignTypedData.ts

@@ -15,8 +15,8 @@ import {
   type EthereumSignTypedDataMessage,
   type EthereumSignTypedDataTypes,
 } from '../../types';
-import TransportManager from '../../data-manager/TransportManager';
 import { signTypedHash as signTypedHashLegacyV1 } from './legacyV1/signTypedHash';
+import { shouldUseLegacyV1EvmMessages } from './protocol';
 import { signTypedHash } from './latest/signTypedHash';
 import { signTypedData as signTypedDataLegacyV1 } from './legacyV1/signTypedData';
 import { signTypedData } from './latest/signTypedData';
@@ -32,9 +32,8 @@ import type {
 } from '@onekeyfe/hd-transport';
 
 /**
- * EthereumTypedDataStructAckOneKey 与 EthereumTypedDataStructAck 的字段结构与
- * 枚举数值完全一致（生成产物的 OneKey/Trezor 双份消息），仅枚举名义类型不同；
- * 这里做无运行时成本的名义转换，避免在调用点散落 any。
+ * EthereumTypedDataStructAckOneKey and EthereumTypedDataStructAck have identical
+ * fields and enum values. This zero-cost nominal conversion avoids scattered `any`.
  */
 const toOneKeyStructAck = (ack: EthereumTypedDataStructAck): EthereumTypedDataStructAckOneKey =>
   ack as unknown as EthereumTypedDataStructAckOneKey;
@@ -57,6 +56,10 @@ const MINI_MAX_ARRAY_TYPE_FIELDS = 24;
 const MINI_MAX_ARRAY_ELEMENTS = 24;
 
 export default class EVMSignTypedData extends BaseMethod<EVMSignTypedDataParams> {
+  getSupportedProtocols() {
+    return ['V1', 'V2'] as const;
+  }
+
   init() {
     this.checkDeviceId = true;
     this.allowDeviceMode = [...this.allowDeviceMode, UI_REQUEST.NOT_INITIALIZE];
@@ -227,8 +230,7 @@ export default class EVMSignTypedData extends BaseMethod<EVMSignTypedDataParams>
     if (response.type === 'EthereumGnosisSafeTxRequest') {
       const { data } = this.params;
       const verifyingContract = data.domain?.verifyingContract;
-      // EthereumGnosisSafeTxAck.verifyingContract 在 proto 中是 required 字段，
-      // Gnosis Safe 签名缺少 verifyingContract 没有意义，这里给出明确的参数错误。
+      // verifyingContract is required by proto and essential to a Gnosis Safe signature.
       if (!verifyingContract) {
         throw ERRORS.TypedError(
           HardwareErrorCode.CallMethodInvalidParameter,
@@ -276,29 +278,23 @@ export default class EVMSignTypedData extends BaseMethod<EVMSignTypedDataParams>
 
     let supportTrezor = false;
     let response: MessageResponse<MessageKey>;
-    switch (TransportManager.getProtocolV1MessageSchema()) {
-      case 'v1LegacySchema':
-        supportTrezor = true;
-        response = await signTypedDataLegacyV1({
-          typedCall: this.device.commands.typedCall.bind(this.device.commands),
-          addressN,
-          data,
-          metamaskV4Compat,
-          chainId,
-        });
-        break;
-
-      case 'v1CurrentSchema':
-      default:
-        supportTrezor = false;
-        response = await signTypedData({
-          typedCall: this.device.commands.typedCall.bind(this.device.commands),
-          addressN,
-          data,
-          metamaskV4Compat,
-          chainId,
-        });
-        break;
+    if (shouldUseLegacyV1EvmMessages(this.device)) {
+      supportTrezor = true;
+      response = await signTypedDataLegacyV1({
+        typedCall: this.device.commands.typedCall.bind(this.device.commands),
+        addressN,
+        data,
+        metamaskV4Compat,
+        chainId,
+      });
+    } else {
+      response = await signTypedData({
+        typedCall: this.device.commands.typedCall.bind(this.device.commands),
+        addressN,
+        data,
+        metamaskV4Compat,
+        chainId,
+      });
     }
 
     return this.handleSignTypedData({
@@ -324,28 +320,24 @@ export default class EVMSignTypedData extends BaseMethod<EVMSignTypedDataParams>
   }) {
     if (!domainHash) throw ERRORS.TypedError('Runtime', 'domainHash is required');
 
-    switch (TransportManager.getProtocolV1MessageSchema()) {
-      case 'v1LegacySchema':
-        return signTypedHashLegacyV1({
-          typedCall,
-          addressN,
-          domainHash,
-          messageHash,
-          chainId,
-          device: this.device,
-        });
-
-      case 'v1CurrentSchema':
-      default:
-        return signTypedHash({
-          typedCall,
-          addressN,
-          domainHash,
-          messageHash,
-          chainId,
-          device: this.device,
-        });
+    if (shouldUseLegacyV1EvmMessages(this.device)) {
+      return signTypedHashLegacyV1({
+        typedCall,
+        addressN,
+        domainHash,
+        messageHash,
+        chainId,
+        device: this.device,
+      });
     }
+    return signTypedHash({
+      typedCall,
+      addressN,
+      domainHash,
+      messageHash,
+      chainId,
+      device: this.device,
+    });
   }
 
   getVersionRange() {

package/src/api/evm/EVMVerifyMessage.ts

@@ -2,13 +2,17 @@ import { UI_REQUEST } from '../../constants/ui-request';
 import { BaseMethod } from '../BaseMethod';
 import { validateParams } from '../helpers/paramsValidator';
 import { formatAnyHex } from '../helpers/hexUtils';
-import TransportManager from '../../data-manager/TransportManager';
 import verifyMessageLegacyV1 from './legacyV1/verifyMessage';
 import verifyMessage from './latest/verifyMessage';
+import { shouldUseLegacyV1EvmMessages } from './protocol';
 
 import type { EthereumVerifyMessageOneKey } from '@onekeyfe/hd-transport';
 
 export default class EVMSignMessage extends BaseMethod<EthereumVerifyMessageOneKey> {
+  getSupportedProtocols() {
+    return ['V1', 'V2'] as const;
+  }
+
   init() {
     this.checkDeviceId = true;
     this.allowDeviceMode = [...this.allowDeviceMode, UI_REQUEST.NOT_INITIALIZE];
@@ -31,7 +35,7 @@ export default class EVMSignMessage extends BaseMethod<EthereumVerifyMessageOneK
   }
 
   async run() {
-    if (TransportManager.getProtocolV1MessageSchema() === 'v1LegacySchema') {
+    if (shouldUseLegacyV1EvmMessages(this.device)) {
       return verifyMessageLegacyV1({
         typedCall: this.device.commands.typedCall.bind(this.device.commands),
         params: this.params,

package/src/api/evm/legacyV1/getAddress.ts

@@ -7,8 +7,8 @@ export default async function ({
   typedCall: TypedCall;
   param: EthereumGetAddressOneKey;
 }): Promise<MessageResponse<'EthereumAddress'>> {
-  // legacy EthereumGetAddress 的生成类型没有 chain_id 字段，但旧固件按 OneKey 扩展
-  // 接受该字段；通过预先声明的对象（非 fresh literal）携带额外字段，保持原有运行时行为。
+  // The generated legacy type omits chain_id, but old firmware accepts the OneKey
+  // extension. A non-fresh object preserves that runtime field without a type cast.
   const message = {
     address_n: param.address_n,
     show_display: param.show_display,

package/src/api/evm/legacyV1/getPublicKey.ts

@@ -11,8 +11,8 @@ export default async function ({
   typedCall: TypedCall;
   param: EthereumGetPublicKeyOneKey;
 }): Promise<MessageResponse<'EthereumPublicKey'>> {
-  // legacy EthereumGetPublicKey 的生成类型没有 chain_id 字段，但旧固件按 OneKey 扩展
-  // 接受该字段；通过预先声明的对象（非 fresh literal）携带额外字段，保持原有运行时行为。
+  // The generated legacy type omits chain_id, but old firmware accepts the OneKey
+  // extension. A non-fresh object preserves that runtime field without a type cast.
   const message = {
     address_n: param.address_n,
     show_display: param.show_display,

package/src/api/evm/legacyV1/signMessage.ts

@@ -11,8 +11,8 @@ export default async function ({
   typedCall: TypedCall;
   params: EthereumSignMessageOneKey;
 }): Promise<EthereumMessageSignature> {
-  // legacy EthereumSignMessage 的生成类型没有 chain_id 字段，但旧固件按 OneKey 扩展
-  // 接受该字段；通过预先声明的对象（非 fresh literal）携带额外字段，保持原有运行时行为。
+  // The generated legacy type omits chain_id, but old firmware accepts the OneKey
+  // extension. A non-fresh object preserves that runtime field without a type cast.
   const message = {
     address_n: params.address_n,
     message: params.message,

package/src/api/evm/legacyV1/signTypedData.ts

@@ -16,8 +16,8 @@ export const signTypedData = async ({
 }) => {
   const { primaryType }: EthereumSignTypedDataMessage<EthereumSignTypedDataTypes> = data;
 
-  // legacy EthereumSignTypedData 的生成类型没有 chain_id 字段，但旧固件按 OneKey 扩展
-  // 接受该字段；通过预先声明的对象（非 fresh literal）携带额外字段，保持原有运行时行为。
+  // The generated legacy type omits chain_id, but old firmware accepts the OneKey
+  // extension. A non-fresh object preserves that runtime field without a type cast.
   const message = {
     address_n: addressN,
     primary_type: primaryType as string,

package/src/api/evm/legacyV1/signTypedHash.ts

@@ -38,8 +38,8 @@ export const signTypedHash = async ({
     }
   }
 
-  // legacy EthereumSignTypedHash 的生成类型没有 chain_id 字段，但旧固件按 OneKey 扩展
-  // 接受该字段；通过预先声明的对象（非 fresh literal）携带额外字段，保持原有运行时行为。
+  // The generated legacy type omits chain_id, but old firmware accepts the OneKey
+  // extension. A non-fresh object preserves that runtime field without a type cast.
   const message = {
     address_n: addressN,
     domain_separator_hash: domainHash ?? '',

package/src/api/evm/legacyV1/verifyMessage.ts

@@ -7,8 +7,8 @@ export default async function ({
   typedCall: TypedCall;
   params: EthereumVerifyMessageOneKey;
 }): Promise<Success> {
-  // legacy EthereumVerifyMessage 的生成类型没有 chain_id 字段，但旧固件按 OneKey 扩展
-  // 接受该字段；通过预先声明的对象（非 fresh literal）携带额外字段，保持原有运行时行为。
+  // The generated legacy type omits chain_id, but old firmware accepts the OneKey
+  // extension. A non-fresh object preserves that runtime field without a type cast.
   const message = {
     signature: params.signature,
     message: params.message,

package/src/api/evm/protocol.ts

@@ -0,0 +1,6 @@
+import TransportManager from '../../data-manager/TransportManager';
+
+import type { Device } from '../../device/Device';
+
+export const shouldUseLegacyV1EvmMessages = (device: Pick<Device, 'isProtocolV2'>): boolean =>
+  !device.isProtocolV2() && TransportManager.getProtocolV1MessageSchema() === 'v1LegacySchema';

package/src/api/filecoin/FilecoinGetAddress.ts

@@ -7,6 +7,10 @@ import type { FilecoinGetAddress as HardwareFilecoinGetAddress } from '@onekeyfe
 import type { FilecoinAddress, FilecoinGetAddressParams } from '../../types';
 
 export default class FilecoinGetAddress extends BaseMethod<HardwareFilecoinGetAddress[]> {
+  getSupportedProtocols() {
+    return ['V1', 'V2'] as const;
+  }
+
   hasBundle = false;
 
   init() {

package/src/api/filecoin/FilecoinSignTransaction.ts

@@ -7,6 +7,10 @@ import type { FilecoinSignTransactionParams } from '../../types';
 import type { FilecoinSignTx as HardwareFilecoinSignTx } from '@onekeyfe/hd-transport';
 
 export default class FilecoinSignTransaction extends BaseMethod<HardwareFilecoinSignTx> {
+  getSupportedProtocols() {
+    return ['V1', 'V2'] as const;
+  }
+
   hasBundle = false;
 
   init() {

package/src/api/firmware/FirmwareUpdateBaseMethod.ts

@@ -8,12 +8,11 @@ import {
 
 import { FirmwareUpdateTipMessage, UI_REQUEST, createUiMessage } from '../../events/ui-request';
 import { DevicePool } from '../../device/DevicePool';
-import { LoggerNames, getDeviceUUID, getLogger, wait } from '../../utils';
+import { LoggerNames, getLogger, wait } from '../../utils';
 import { DeviceModelToTypes } from '../../types';
 import { DataManager } from '../../data-manager';
 import { BaseMethod } from '../BaseMethod';
 import { DEVICE } from '../../events';
-import { createFirmwareProgressThrottle } from './progressThrottle';
 
 import type {
   IFirmwareUpdateProgressType,
@@ -41,8 +40,6 @@ const isDeviceDisconnectedError = (error: unknown) => {
 export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
   checkPromise: Deferred<any> | null = null;
 
-  private shouldPostFirmwareProgress = createFirmwareProgressThrottle();
-
   init(): void {}
 
   run(): Promise<any> {
@@ -86,10 +83,6 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
    * @param progress Post the percentage of the progress
    */
   postProgressMessage = (progress: number, progressType: IFirmwareUpdateProgressType) => {
-    if (!this.shouldPostFirmwareProgress(progress, progressType)) {
-      return;
-    }
-
     this.postMessage(
       createUiMessage(UI_REQUEST.FIRMWARE_PROGRESS, {
         device: this.device.toMessageObject() as KnownDevice,
@@ -198,7 +191,8 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
             await this.device.deviceConnector?.acquire(
               this.device.originalDescriptor.id,
               null,
-              true
+              true,
+              this.payload.connectProtocol ?? this.device.originalDescriptor.protocolType
             );
             await this.device.initialize();
             if (this.device.isBootloader()) {
@@ -232,7 +226,9 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
   ) {
     const deviceDiff = await this.device.deviceConnector?.enumerate();
     const devicesDescriptor = deviceDiff?.descriptors ?? [];
-    const { deviceList } = await DevicePool.getDevices(devicesDescriptor, connectId);
+    const { deviceList } = await DevicePool.getDevices(devicesDescriptor, connectId, {
+      connectProtocol: this.payload.connectProtocol ?? this.device.originalDescriptor.protocolType,
+    });
 
     if (deviceList.length === 1 && deviceList[0]?.isBootloader()) {
       // should update current device from cache
@@ -251,7 +247,7 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
   async enterBootloaderMode() {
     const typedCall = this.device.getCommands().typedCall.bind(this.device.getCommands());
     if (this.device.features && !this.device.isBootloader()) {
-      const uuid = getDeviceUUID(this.device.features);
+      const serialNo = this.device.getCurrentSerialNo();
       const deviceType = this.device.getCurrentDeviceType();
       // auto go to bootloader mode
       try {
@@ -266,7 +262,7 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
 
         // force clean classic device cache so that the device can initialize again
         if (DeviceModelToTypes.model_classic.includes(deviceType)) {
-          DevicePool.clearDeviceCache(uuid);
+          DevicePool.clearDeviceCache(serialNo);
         }
         delete DevicePool.devicesCache[''];
         await this.checkPromise?.promise;
@@ -441,7 +437,12 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
         const env = DataManager.getSettings('env');
         if (DataManager.isBleConnect(env)) {
           await wait(3000);
-          await this.device.deviceConnector?.acquire(this.device.originalDescriptor.id, null, true);
+          await this.device.deviceConnector?.acquire(
+            this.device.originalDescriptor.id,
+            null,
+            true,
+            this.payload.connectProtocol ?? this.device.originalDescriptor.protocolType
+          );
           await this.device.initialize();
         } else if (
           error?.message?.indexOf(SESSION_ERROR) > -1 ||
@@ -449,7 +450,10 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
         ) {
           const deviceDiff = await this.device.deviceConnector?.enumerate();
           const devicesDescriptor = deviceDiff?.descriptors ?? [];
-          const { deviceList } = await DevicePool.getDevices(devicesDescriptor, undefined);
+          const { deviceList } = await DevicePool.getDevices(devicesDescriptor, undefined, {
+            connectProtocol:
+              this.payload.connectProtocol ?? this.device.originalDescriptor.protocolType,
+          });
           if (deviceList.length === 1 && deviceList[0]?.isBootloader()) {
             this.device.updateFromCache(deviceList[0]);
             await this.device.acquire();

package/src/api/firmware/getBinary.ts

@@ -7,9 +7,12 @@ import { findLatestRelease } from '../../utils/release';
 import { getFirmwareUpdateField } from '../../utils/deviceFeaturesUtils';
 
 import type { Features } from '../../types';
+import type { HttpRequestOptions } from '../../utils/networkUtils';
 import type { EFirmwareType } from '@onekeyfe/hd-shared';
 import type { IFirmwareField } from '../../data-manager/DataManager';
 
+export type FirmwareBinary = ArrayBuffer | Buffer;
+
 export interface GetInfoProps {
   features: Features;
   updateType: 'firmware' | 'ble';
@@ -20,6 +23,7 @@ export interface GetInfoProps {
 
 interface GetBinaryProps extends GetInfoProps {
   version?: number[];
+  requestOptions?: HttpRequestOptions;
 }
 
 export const getBinary = async ({
@@ -28,6 +32,7 @@ export const getBinary = async ({
   version,
   isUpdateBootloader,
   firmwareType,
+  requestOptions,
 }: GetBinaryProps) => {
   const releaseInfo = getInfo({
     features,
@@ -55,9 +60,9 @@ export const getBinary = async ({
       : isUpdateBootloader
       ? releaseInfo.bootloaderResource
       : releaseInfo.url;
-  let fw;
+  let fw: FirmwareBinary;
   try {
-    fw = await httpRequest(url, 'binary');
+    fw = await httpRequest(url, 'binary', requestOptions);
   } catch {
     throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Method_FirmwareUpdate_DownloadFailed');
   }
@@ -69,7 +74,7 @@ export const getBinary = async ({
 };
 
 export const getSysResourceBinary = async (url: string) => {
-  let fw;
+  let fw: FirmwareBinary;
   try {
     fw = await httpRequest(url, 'binary');
   } catch {

package/src/api/firmware/uploadFirmware.ts

@@ -322,7 +322,12 @@ const newTouchUpdateProcess = async (
       try {
         if (isBleReconnect) {
           try {
-            await device.deviceConnector?.acquire(device.originalDescriptor.id, null, true);
+            await device.deviceConnector?.acquire(
+              device.originalDescriptor.id,
+              null,
+              true,
+              device.originalDescriptor.protocolType
+            );
             const typedCall = device.getCommands().typedCall.bind(device.getCommands());
             await Promise.race([
               typedCall('Initialize', 'Features', {}),
@@ -341,7 +346,8 @@ const newTouchUpdateProcess = async (
           const devicesDescriptor = deviceDiff?.descriptors ?? [];
           const { deviceList } = await DevicePool.getDevices(
             devicesDescriptor,
-            device.originalDescriptor.id
+            device.originalDescriptor.id,
+            { connectProtocol: device.originalDescriptor.protocolType }
           );
           if (deviceList.length === 1) {
             device.updateFromCache(deviceList[0]);
@@ -416,7 +422,12 @@ const emmcFileWriteWithRetry = async (
       const env = DataManager.getSettings('env');
       if (DataManager.isBleConnect(env)) {
         await wait(3000);
-        await device.deviceConnector?.acquire(device.originalDescriptor.id, null, true);
+        await device.deviceConnector?.acquire(
+          device.originalDescriptor.id,
+          null,
+          true,
+          device.originalDescriptor.protocolType
+        );
         await device.initialize();
       } else if (
         error?.message?.indexOf(SESSION_ERROR) > -1 ||
@@ -424,7 +435,9 @@ const emmcFileWriteWithRetry = async (
       ) {
         const deviceDiff = await device.deviceConnector?.enumerate();
         const devicesDescriptor = deviceDiff?.descriptors ?? [];
-        const { deviceList } = await DevicePool.getDevices(devicesDescriptor, undefined);
+        const { deviceList } = await DevicePool.getDevices(devicesDescriptor, undefined, {
+          connectProtocol: device.originalDescriptor.protocolType,
+        });
         if (deviceList.length === 1 && deviceList[0]?.isBootloader()) {
           device.updateFromCache(deviceList[0]);
           await device.acquire();

package/src/api/helpers/batchGetPublickeys.ts

@@ -27,8 +27,8 @@ export function supportBatchPublicKeyByDevice(
   const currentVersion = device.getCurrentFirmwareVersionString() ?? '0.0.0';
   const deviceType = device.getCurrentDeviceType();
 
-  // Pro2 (Protocol V2) 版本线独立于 Pro 系列，固件从首个版本即支持 batch / include_node，
-  // 不能套用下面 Pro 系列的 4.x 门槛。
+  // Pro2 has an independent version line and supports batch/include_node from its first
+  // firmware version, so the Protocol V1 Pro 4.x threshold does not apply.
   if (device.isProtocolV2() || deviceType === EDeviceType.Pro2) {
     return true;
   }

package/src/api/helpers/filesystemValidation.ts

@@ -10,6 +10,67 @@ export function validateNonEmptyString(value: unknown, name: string): string {
   return value;
 }
 
+const PROTOCOL_V2_FILESYSTEM_VOLUMES = new Set(['vol0', 'vol1']);
+// Bootloader and romloader reserve 128 bytes including the terminating NUL.
+const MAX_PROTOCOL_V2_FILESYSTEM_PATH_BYTES = 127;
+
+function getUtf8ByteLength(value: string) {
+  return Array.from(value).reduce((length, character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    if (codePoint <= 0x7f) return length + 1;
+    if (codePoint <= 0x7ff) return length + 2;
+    if (codePoint <= 0xffff) return length + 3;
+    return length + 4;
+  }, 0);
+}
+
+export function validateProtocolV2FilesystemPath(
+  value: unknown,
+  name: string,
+  options: { allowVolumeRoot?: boolean } = {}
+): string {
+  const rawPath = validateNonEmptyString(value, name).trim();
+  const containsUnsupportedCharacter = Array.from(rawPath).some(character => {
+    const codePoint = character.charCodeAt(0);
+    return codePoint <= 0x1f || codePoint === 0x7f || character === '\\';
+  });
+
+  if (containsUnsupportedCharacter) {
+    throw invalidParameter(`Parameter [${name}] contains unsupported path characters.`);
+  }
+
+  const match = /^([a-zA-Z0-9]+):(.*)$/.exec(rawPath);
+  if (!match) {
+    throw invalidParameter(
+      `Parameter [${name}] must use a supported Protocol V2 filesystem volume.`
+    );
+  }
+
+  const volume = match[1].toLowerCase();
+  if (!PROTOCOL_V2_FILESYSTEM_VOLUMES.has(volume)) {
+    throw invalidParameter(`Parameter [${name}] uses an unsupported filesystem volume.`);
+  }
+
+  const rawSuffix = match[2];
+  if (rawSuffix.length === 0) {
+    if (options.allowVolumeRoot) return `${volume}:`;
+    throw invalidParameter(`Parameter [${name}] must identify a filesystem entry.`);
+  }
+
+  const suffix = rawSuffix.startsWith('/') ? rawSuffix : `/${rawSuffix}`;
+  const segments = suffix.slice(1).split('/');
+  if (segments.some(segment => segment.length === 0 || segment === '.' || segment === '..')) {
+    throw invalidParameter(`Parameter [${name}] contains an invalid path segment.`);
+  }
+
+  const canonicalPath = `${volume}:${rawSuffix.startsWith('/') ? '/' : ''}${segments.join('/')}`;
+  if (getUtf8ByteLength(canonicalPath) > MAX_PROTOCOL_V2_FILESYSTEM_PATH_BYTES) {
+    throw invalidParameter(`Parameter [${name}] exceeds the maximum filesystem path length.`);
+  }
+
+  return canonicalPath;
+}
+
 export function validateNonNegativeInteger(
   value: unknown,
   name: string,

package/src/api/helpers/paramsValidator.ts

@@ -20,7 +20,7 @@ export type SchemaParam = {
   allowNegative?: boolean;
 };
 
-const invalidParameter = (message: string) =>
+export const invalidParameter = (message: string) =>
   ERRORS.TypedError(HardwareErrorCode.CallMethodInvalidParameter, message);
 
 const invalidResponse = (message: string) =>