@onekeyfe/hd-transport 1.2.0-alpha.99 → 1.2.0

package/src/protocols/v2/session.ts

@@ -4,7 +4,12 @@ import {
 } from '../../constants';
 import { ProtocolV2FrameAssembler, concatUint8Arrays } from './frame-assembler';
 import { ProtocolV2SequenceCursor } from './sequence-cursor';
-import { ProtocolV2LinkError } from './errors';
+import {
+  ProtocolV2LinkError,
+  createProtocolV2LinkDisabledError,
+  isProtocolV2LinkDisabledError,
+  isProtocolV2LinkDisabledFailure,
+} from './errors';
 import { ProtocolV2 } from '..';
 import * as check from '../../utils/highlevel-checks';
 import { LogBlockCommand } from '../../utils/logBlockCommand';
@@ -54,6 +59,8 @@ export type ProtocolV2CallOptions = {
   intermediateTypes?: string[];
   onIntermediateResponse?: (response: MessageFromOneKey) => void;
   onWriteCompleted?: (metrics: TransportWriteMetrics) => void;
+  returnAfterWrite?: boolean;
+  onResponseAfterWrite?: (response: MessageFromOneKey) => void;
   writeWithResponse?: boolean;
 };
 
@@ -75,6 +82,33 @@ export function hexToBytes(hex: string): Uint8Array {
   return bytes;
 }
 
+export function detectProtocolV2LinkDisabledError({
+  schemas,
+  assembler,
+  bytes,
+}: {
+  schemas: ProtocolV2Schemas;
+  assembler: ProtocolV2FrameAssembler;
+  bytes: Uint8Array;
+}) {
+  try {
+    for (const frame of assembler.drain(bytes)) {
+      const response = check.call(ProtocolV2.decodeFrame(schemas, frame));
+      if (response.type === 'Failure') {
+        const failureCode = response.message?.code;
+        const firmwareMessage = response.message?.message;
+        if (isProtocolV2LinkDisabledFailure(failureCode, firmwareMessage)) {
+          return createProtocolV2LinkDisabledError(failureCode, firmwareMessage);
+        }
+      }
+    }
+  } catch {
+    // Cross-protocol detection may receive a normal Protocol V1 notification.
+    assembler.reset();
+  }
+  return undefined;
+}
+
 export function bytesToHex(bytes: Uint8Array): string {
   return Array.from(bytes)
     .map(b => b.toString(16).padStart(2, '0'))
@@ -189,6 +223,15 @@ export class ProtocolV2Session {
   // in-flight calls on the same session would steal each other's responses.
   private pendingCall: Promise<unknown> = Promise.resolve();
 
+  // Flow-control messages may interrupt a call that is waiting for a device UI
+  // response, but their frames must never interleave with the active request write.
+  private pendingWrite: Promise<unknown> = Promise.resolve();
+
+  private pendingResponseAfterWrite?: {
+    expectedTypes: Set<string>;
+    onResponse?: (response: MessageFromOneKey) => void;
+  };
+
   private lastResponseSequence?: number;
 
   constructor(options: ProtocolV2SessionOptions) {
@@ -209,6 +252,47 @@ export class ProtocolV2Session {
     return result;
   }
 
+  sendFlowControl(name: string, data: Record<string, unknown>): Promise<MessageFromOneKey> {
+    const {
+      schemas,
+      router,
+      packetSrc = PROTOCOL_V2_PACKET_SRC_COMMAND,
+      maxFrameBytes,
+      writeFrame,
+      generation = 0,
+    } = this.options;
+    const abortController = new AbortController();
+    const context: ProtocolV2CallContext = {
+      messageName: name,
+      highThroughput: false,
+      generation,
+      signal: abortController.signal,
+    };
+    const protoSeq = this.sequenceCursor.next();
+    const frame = ProtocolV2.encodeFrame(schemas, name, data, {
+      packetSrc,
+      router,
+      seq: protoSeq,
+    });
+
+    if (maxFrameBytes !== undefined && frame.length > maxFrameBytes) {
+      return Promise.reject(
+        new Error(`Protocol V2 frame too large for transport: ${frame.length} > ${maxFrameBytes}`)
+      );
+    }
+
+    return this.serializeWrite(() => writeFrame(frame, context)).then(() => ({
+      type: 'WriteCompleted',
+      message: {},
+    }));
+  }
+
+  private serializeWrite<T>(write: () => Promise<T>): Promise<T> {
+    const result = this.pendingWrite.then(write, write);
+    this.pendingWrite = result.catch(() => undefined);
+    return result;
+  }
+
   private executeCall(
     name: string,
     data: Record<string, unknown>,
@@ -246,7 +330,11 @@ export class ProtocolV2Session {
     };
 
     const runCall = async (): Promise<MessageFromOneKey> => {
-      await prepareCall?.(baseCallContext);
+      // A write-only call may still have a terminal response in flight. Preserve
+      // the continuous receive queue until the next call consumes that response.
+      if (!this.pendingResponseAfterWrite) {
+        await prepareCall?.(baseCallContext);
+      }
       const protoSeq = this.sequenceCursor.next();
       const frame = ProtocolV2.encodeFrame(schemas, name, data, {
         packetSrc,
@@ -261,7 +349,7 @@ export class ProtocolV2Session {
       }
 
       const writeStartedAt = Date.now();
-      await writeFrame(frame, baseCallContext);
+      await this.serializeWrite(() => writeFrame(frame, baseCallContext));
       try {
         callOptions.onWriteCompleted?.({
           elapsedMs: Math.max(Date.now() - writeStartedAt, 0),
@@ -271,6 +359,16 @@ export class ProtocolV2Session {
         logger?.error?.(`${logPrefix} write metrics callback failed: ${String(error)}`);
       }
 
+      if (callOptions.returnAfterWrite) {
+        if (callOptions.expectedTypes?.length) {
+          this.pendingResponseAfterWrite = {
+            expectedTypes: new Set(callOptions.expectedTypes),
+            onResponse: callOptions.onResponseAfterWrite,
+          };
+        }
+        return { type: 'WriteCompleted', message: {} };
+      }
+
       // Some Protocol V2 operations emit progress notifications before the
       // terminal response. Consume those frames here so callers still see a
       // request/terminal-response shaped API.
@@ -340,7 +438,26 @@ export class ProtocolV2Session {
           this.lastResponseSequence = decoded.seq;
 
           const response = check.call(decoded);
-          if (callOptions.intermediateTypes?.includes(response.type)) {
+          const { pendingResponseAfterWrite } = this;
+          let belongsToWriteOnlyCall = false;
+          if (pendingResponseAfterWrite) {
+            belongsToWriteOnlyCall = pendingResponseAfterWrite.expectedTypes.has(response.type);
+            if (belongsToWriteOnlyCall || COMMON_TERMINAL_RESPONSE_TYPES.has(response.type)) {
+              this.pendingResponseAfterWrite = undefined;
+              if (belongsToWriteOnlyCall) {
+                try {
+                  pendingResponseAfterWrite.onResponse?.(response);
+                } catch (error) {
+                  logger?.error?.(
+                    `${logPrefix} delayed response callback failed: ${String(error)}`
+                  );
+                }
+              }
+            }
+          }
+          if (belongsToWriteOnlyCall) {
+            // The delayed response belongs to the preceding write-only call.
+          } else if (callOptions.intermediateTypes?.includes(response.type)) {
             callOptions.onIntermediateResponse?.(response);
           } else if (isExpectedTerminalResponse(response, callOptions.expectedTypes)) {
             return response;
@@ -378,6 +495,7 @@ export async function probeProtocolV2({
   logPrefix = 'ProtocolV2',
   onBeforeProbe,
   onProbeFailed,
+  shouldRethrow,
 }: {
   call: (
     name: string,
@@ -389,6 +507,7 @@ export async function probeProtocolV2({
   logPrefix?: string;
   onBeforeProbe?: () => Promise<void> | void;
   onProbeFailed?: (error: unknown) => Promise<void> | void;
+  shouldRethrow?: (error: unknown) => boolean;
 }) {
   let probeError: unknown;
   try {
@@ -404,8 +523,18 @@ export async function probeProtocolV2({
     if (response.type === 'Success') {
       return true;
     }
+    if (response.type === 'Failure') {
+      const failureCode = response.message?.code;
+      const firmwareMessage = response.message?.message;
+      if (isProtocolV2LinkDisabledFailure(failureCode, firmwareMessage)) {
+        throw createProtocolV2LinkDisabledError(failureCode, firmwareMessage);
+      }
+    }
     probeError = new Error(`unexpected response type ${response.type}`);
   } catch (error) {
+    if (isProtocolV2LinkDisabledError(error) || shouldRethrow?.(error)) {
+      throw error;
+    }
     probeError = error;
   }
 

package/src/protocols/v2/usb-transport-base.ts

@@ -93,6 +93,19 @@ export abstract class ProtocolV2UsbTransportBase<Key> {
     );
   }
 
+  protected sendProtocolV2UsbFlowControl(
+    key: Key,
+    name: string,
+    data: Record<string, unknown>
+  ): Promise<MessageFromOneKey> {
+    return this.protocolV2UsbLinks.sendFlowControl(
+      key,
+      () => this.createProtocolV2UsbAdapter(key),
+      name,
+      data
+    );
+  }
+
   protected invalidateProtocolV2UsbLink(key: Key, reason: string): Promise<void> {
     return this.protocolV2UsbLinks.invalidateLink(key, reason);
   }

package/src/types/messages.ts

@@ -1950,6 +1950,8 @@ export type EthereumSignTxOneKey = {
   data_length?: number;
   chain_id: number;
   tx_type?: number;
+  expected_address?: string;
+  source_fingerprint?: number;
 };
 
 // EthereumAccessListOneKey
@@ -1971,6 +1973,8 @@ export type EthereumSignTxEIP1559OneKey = {
   data_length: number;
   chain_id: number;
   access_list: EthereumAccessListOneKey[];
+  expected_address?: string;
+  source_fingerprint?: number;
 };
 
 // EthereumAuthorizationSignature
@@ -2023,6 +2027,7 @@ export type EthereumSignMessageOneKey = {
   address_n: number[];
   message: string;
   chain_id?: number;
+  source_fingerprint?: number;
 };
 
 // EthereumMessageSignatureOneKey
@@ -3815,6 +3820,7 @@ export type SolanaSignTx = {
   address_n: number[];
   raw_tx: string;
   extra_info?: SolanaTxExtraInfo;
+  source_fingerprint?: number;
 };
 
 // SolanaSignedTx
@@ -3838,12 +3844,14 @@ export type SolanaSignOffChainMessage = {
   message_version?: SolanaOffChainMessageVersion;
   message_format?: SolanaOffChainMessageFormat;
   application_domain?: string;
+  source_fingerprint?: number;
 };
 
 // SolanaSignUnsafeMessage
 export type SolanaSignUnsafeMessage = {
   address_n: number[];
   message: string;
+  source_fingerprint?: number;
 };
 
 // SolanaMessageSignature
@@ -4594,6 +4602,7 @@ export type EthereumSignTypedDataQR = {
   chain_id?: number;
   metamask_v4_compat?: boolean;
   request_id?: string;
+  source_fingerprint?: number;
 };
 
 // SetBusy
@@ -4766,6 +4775,19 @@ export type DeviceMiscUsbMscControl = {
   enable: boolean;
 };
 
+// DeviceFindMyTokenUpdate
+export type DeviceFindMyTokenUpdate = {
+  token: string;
+};
+
+// DeviceFindMyTokenStateGet
+export type DeviceFindMyTokenStateGet = {};
+
+// DeviceFindMyTokenState
+export type DeviceFindMyTokenState = {
+  burned: boolean;
+};
+
 export enum DeviceFactoryAck {
   FACTORY_ACK_SUCCESS = 0,
   FACTORY_ACK_FAIL = 1,
@@ -4785,8 +4807,8 @@ export type DeviceFactoryInfoManufactureTime = {
 export type DeviceFactoryInfo = {
   version?: number;
   serial_number?: string;
-  burn_in_completed?: boolean;
   factory_test_completed?: boolean;
+  factory_burn_in_completed?: boolean;
   manufacture_time?: DeviceFactoryInfoManufactureTime;
 };
 
@@ -4837,21 +4859,40 @@ export enum DeviceFirmwareUpdateTaskStatus {
   FW_MGMT_UPDATER_TASK_STATUS_FAILED_ENTRY_OUT_OF_BOUNDS = 10,
 }
 
+export enum DeviceFirmwareUpdatePhase {
+  FW_MGMT_UPDATER_PHASE_PREPARE = 0,
+  FW_MGMT_UPDATER_PHASE_INSTALL = 1,
+  FW_MGMT_UPDATER_PHASE_VERIFY = 2,
+}
+
 // DeviceFirmwareTarget
 export type DeviceFirmwareTarget = {
   target_id: DeviceFirmwareTargetType;
   path: string;
 };
 
+// DeviceFirmwareUpdateStage
+export type DeviceFirmwareUpdateStage = {
+  targets: DeviceFirmwareTarget[];
+};
+
 // DeviceFirmwareUpdateRequest
 export type DeviceFirmwareUpdateRequest = {
-  targets: DeviceFirmwareTarget[];
+  reboot_after_update?: boolean;
+};
+
+// DeviceFirmwareUpdatePhaseInfo
+export type DeviceFirmwareUpdatePhaseInfo = {
+  phase: DeviceFirmwareUpdatePhase;
+  progress_percent: number;
 };
 
 // DeviceFirmwareUpdateRecord
 export type DeviceFirmwareUpdateRecord = {
   target_id: DeviceFirmwareTargetType;
   status?: DeviceFirmwareUpdateTaskStatus;
+  progress_percent?: number;
+  phase_info?: DeviceFirmwareUpdatePhaseInfo;
   payload_version?: number;
   path?: string;
 };
@@ -4859,6 +4900,8 @@ export type DeviceFirmwareUpdateRecord = {
 // DeviceFirmwareUpdateRecordFields
 export type DeviceFirmwareUpdateRecordFields = {
   status?: boolean;
+  progress_percent?: boolean;
+  phase_info?: boolean;
   payload_version?: boolean;
   path?: boolean;
 };
@@ -4937,7 +4980,7 @@ export type DeviceSEInfo = {
 // DeviceInfoTargets
 export type DeviceInfoTargets = {
   hw?: boolean;
-  fw?: boolean;
+  main_mcu?: boolean;
   coprocessor?: boolean;
   se1?: boolean;
   se2?: boolean;
@@ -4963,7 +5006,7 @@ export type DeviceInfoGet = {
 export type ProtocolV2DeviceInfo = {
   protocol_version: number;
   hw?: DeviceHardwareInfo;
-  fw?: DeviceMainMcuInfo;
+  main_mcu?: DeviceMainMcuInfo;
   coprocessor?: DeviceCoprocessorInfo;
   se1?: DeviceSEInfo;
   se2?: DeviceSEInfo;
@@ -5215,7 +5258,9 @@ export enum ViewTipType {
 // ViewTip
 export type ViewTip = {
   type: ViewTipType;
-  text: string;
+  text?: string;
+  text_id?: number;
+  text_arg?: string;
 };
 
 // ViewRawData
@@ -5235,23 +5280,27 @@ export enum ViewSignLayout {
 
 // ViewSignPage
 export type ViewSignPage = {
-  title: string;
+  title?: string;
   amount?: UintType;
   general: ViewDetail[];
   tip?: ViewTip;
   raw_data?: ViewRawData;
   slide_to_confirm?: boolean;
   layout?: ViewSignLayout;
+  title_id?: number;
+  title_arg?: string;
 };
 
 // ViewVerifyPage
 export type ViewVerifyPage = {
-  title: string;
+  title?: string;
   address: string;
   path: string;
   network?: string;
   derive_type?: string;
   value_key?: number;
+  title_id?: number;
+  chain_id?: number;
 };
 
 export enum ProtocolV2FailureType {
@@ -5881,6 +5930,9 @@ export type MessageType = {
   DeviceCertificateSignature: DeviceCertificateSignature;
   DeviceCertificateSign: DeviceCertificateSign;
   DeviceMiscUsbMscControl: DeviceMiscUsbMscControl;
+  DeviceFindMyTokenUpdate: DeviceFindMyTokenUpdate;
+  DeviceFindMyTokenStateGet: DeviceFindMyTokenStateGet;
+  DeviceFindMyTokenState: DeviceFindMyTokenState;
   DeviceFactoryInfoManufactureTime: DeviceFactoryInfoManufactureTime;
   DeviceFactoryInfo: DeviceFactoryInfo;
   DeviceFactoryInfoSet: DeviceFactoryInfoSet;
@@ -5888,7 +5940,9 @@ export type MessageType = {
   DeviceFactoryPermanentLock: DeviceFactoryPermanentLock;
   DeviceFactoryTest: DeviceFactoryTest;
   DeviceFirmwareTarget: DeviceFirmwareTarget;
+  DeviceFirmwareUpdateStage: DeviceFirmwareUpdateStage;
   DeviceFirmwareUpdateRequest: DeviceFirmwareUpdateRequest;
+  DeviceFirmwareUpdatePhaseInfo: DeviceFirmwareUpdatePhaseInfo;
   DeviceFirmwareUpdateRecord: DeviceFirmwareUpdateRecord;
   DeviceFirmwareUpdateRecordFields: DeviceFirmwareUpdateRecordFields;
   DeviceFirmwareUpdateStatusGet: DeviceFirmwareUpdateStatusGet;

package/src/types/transport.ts

@@ -54,6 +54,13 @@ export type AcquireInput = {
   forceCleanRunPromise?: boolean;
   expectedProtocol?: ProtocolType;
   protocolHint?: ProtocolType;
+  /**
+   * Explicit recovery/discovery (e.g. detectDeviceConnectProtocol): the
+   * transport must probe the protocol on the wire, bypassing any cached result.
+   */
+  forceProtocolDetection?: boolean;
+  /** Reuse expectedProtocol only when this transport previously confirmed it for the same endpoint. */
+  skipProtocolProbe?: boolean;
 };
 
 export type MessageFromOneKey = { type: string; message: Record<string, any> };
@@ -70,6 +77,10 @@ export type TransportCallOptions = {
   onIntermediateResponse?: (response: MessageFromOneKey) => void;
   /** Called after the complete request frame has been submitted to the transport. */
   onWriteCompleted?: (metrics: TransportWriteMetrics) => void;
+  /** Resolve after the complete request frame is written without waiting for a response. */
+  returnAfterWrite?: boolean;
+  /** Observe the delayed terminal response of a write-only call while a later call is active. */
+  onResponseAfterWrite?: (response: MessageFromOneKey) => void;
   /** Prefer acknowledged BLE characteristic writes for this call when supported. */
   writeWithResponse?: boolean;
 };