@onekeyfe/hd-transport 1.2.0-alpha.21 → 1.2.0-alpha.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hd-transport",
-  "version": "1.2.0-alpha.21",
+  "version": "1.2.0-alpha.23",
   "description": "Transport layer abstractions and utilities for OneKey hardware SDK.",
   "author": "OneKey",
   "homepage": "https://github.com/OneKeyHQ/hardware-js-sdk#readme",
@@ -28,5 +28,5 @@
     "long": "^4.0.0",
     "protobufjs": "^6.11.2"
   },
-  "gitHead": "efe594367fb3b196a5126baee7e2aba3e94986cd"
+  "gitHead": "7cadb40ca6414053a488756f28a9f413164b235d"
 }

package/scripts/protobuf-types.js

@@ -69,6 +69,9 @@ const ENUM_KEYS = [
   'ProtocolV2Capability',
 ];
 
+// Safety checks are accepted as both protobuf enum names and numeric legacy values.
+const ENUM_KEYS_WITH_NUMERIC_VALUES = ['SafetyCheckLevel'];
+
 const parseEnumTypescript = (itemName, item) => {
   const value = [];
   const IS_KEY = ENUM_KEYS.includes(itemName);
@@ -87,7 +90,10 @@ const parseEnumTypescript = (itemName, item) => {
   value.push('}');
 
   if (IS_KEY) {
-    value.push(`export type ${itemName} = keyof typeof Enum_${itemName};`);
+    const numericValue = ENUM_KEYS_WITH_NUMERIC_VALUES.includes(itemName)
+      ? ` | Enum_${itemName}`
+      : '';
+    value.push(`export type ${itemName} = keyof typeof Enum_${itemName}${numericValue};`);
   }
   // empty line
   value.push('');

package/src/constants.ts

@@ -48,3 +48,11 @@ export const PROTOCOL_V2_CHANNEL_SOCKET = 2;
 
 /** packet_src for protobuf commands; firmware routes zero to the protobuf dispatcher. */
 export const PROTOCOL_V2_PACKET_SRC_COMMAND = 0;
+
+/**
+ * Shared upper bound for a Protocol V2 request without a method-specific timeout.
+ * Interactive and signing calls may wait on the device UI, so keep this longer than
+ * ordinary transport timeouts while still preventing a stalled link from blocking
+ * the per-device queue forever.
+ */
+export const PROTOCOL_V2_DEFAULT_RESPONSE_TIMEOUT_MS = 5 * 60 * 1000;

package/src/protocols/index.ts

@@ -6,7 +6,12 @@ import { decodeMessage as decodeV1Message } from './v1/receive';
 import { createMessageFromName, createMessageFromType } from '../serialization/protobuf/messages';
 import { encode as encodeProtobuf } from '../serialization/protobuf/encode';
 import { decode as decodeProtobuf } from '../serialization/protobuf/decode';
-import { decodeFrame as decodeV2Frame, encodeProtobufFrame, isAckFrame } from './v2';
+import {
+  decodeFrame as decodeV2Frame,
+  encodeProtobufFrame,
+  inspectFrameHeader,
+  isAckFrame,
+} from './v2';
 
 import type { Root } from 'protobufjs/light';
 
@@ -71,15 +76,19 @@ export const ProtocolV1 = {
 
 export const ProtocolV2 = {
   isAckFrame,
+  inspectFrameHeader,
 
   inspectFrame(schemas: ProtocolV2Schemas, frame: Uint8Array) {
-    const { messageTypeId, pbPayload, seq } = decodeV2Frame(frame);
+    const { messageTypeId, pbPayload, seq, router, packetSrc, dataType } = decodeV2Frame(frame);
     const { messageName } = createProtocolV2MessageFromType(messageTypeId, schemas);
     return {
       messageName,
       messageTypeId,
       pbPayload,
       seq,
+      router,
+      packetSrc,
+      dataType,
       type: messageName,
     };
   },

package/src/protocols/v2/decode.ts

@@ -1,4 +1,9 @@
-import { PROTO_DATA_TYPE_ACK, PROTO_HEAD_CRC_SIZE, PROTO_HEAD_SOF } from './constants';
+import {
+  PROTO_DATA_TYPE_ACK,
+  PROTO_DATA_TYPE_PACKET,
+  PROTO_HEAD_CRC_SIZE,
+  PROTO_HEAD_SOF,
+} from './constants';
 import { crc8 } from './crc8';
 
 export interface ProtoV2Frame {
@@ -8,9 +13,23 @@ export interface ProtoV2Frame {
   pbPayload: Uint8Array;
   /** Sequence number from the frame header */
   seq: number;
+  /** Routing channel from the frame header */
+  router: number;
+  /** Packet source from the frame header */
+  packetSrc: number;
+  /** Packet or ACK discriminator from the frame header */
+  dataType: number;
 }
 
-function validateFrame(data: Uint8Array): number {
+export type ProtoV2FrameHeader = {
+  frameLen: number;
+  router: number;
+  packetSrc: number;
+  dataType: number;
+  seq: number;
+};
+
+export function inspectFrameHeader(data: Uint8Array): ProtoV2FrameHeader {
   if (data.length < PROTO_HEAD_CRC_SIZE) {
     throw new Error(`Protocol V2 frame too short: ${data.length} bytes`);
   }
@@ -23,8 +42,10 @@ function validateFrame(data: Uint8Array): number {
 
   const frameLen = data[1] + data[2] * 256;
 
-  if (data.length < frameLen) {
-    throw new Error(`Frame truncated: expected ${frameLen} bytes, got ${data.length}`);
+  if (data.length !== frameLen) {
+    throw new Error(
+      `Protocol V2 frame length mismatch: expected ${frameLen} bytes, got ${data.length}`
+    );
   }
 
   const expectedHeaderCrc = crc8(data, 3);
@@ -45,7 +66,22 @@ function validateFrame(data: Uint8Array): number {
     );
   }
 
-  return frameLen;
+  // eslint-disable-next-line no-bitwise
+  const dataType = data[5] & 0x03;
+  // eslint-disable-next-line no-bitwise
+  const packetSrc = (data[5] >> 2) & 0x0f;
+  const seq = data[6];
+  if (seq === 0) {
+    throw new Error('Invalid Protocol V2 sequence: 0 is reserved');
+  }
+
+  return {
+    frameLen,
+    router: data[4],
+    packetSrc,
+    dataType,
+    seq,
+  };
 }
 
 export function isAckFrame(data: Uint8Array): boolean {
@@ -54,9 +90,9 @@ export function isAckFrame(data: Uint8Array): boolean {
     return false;
   }
 
-  const frameLen = validateFrame(data);
-  if (frameLen !== PROTO_HEAD_CRC_SIZE) {
-    throw new Error(`Invalid Protocol V2 ACK frame length: ${frameLen}`);
+  const header = inspectFrameHeader(data);
+  if (header.frameLen !== PROTO_HEAD_CRC_SIZE) {
+    throw new Error(`Invalid Protocol V2 ACK frame length: ${header.frameLen}`);
   }
   return true;
 }
@@ -72,9 +108,10 @@ export function isAckFrame(data: Uint8Array): boolean {
  * Returns the decoded messageTypeId, raw protobuf payload, and sequence number.
  */
 export function decodeFrame(data: Uint8Array): ProtoV2Frame {
-  const frameLen = validateFrame(data);
-
-  const seq = data[6];
+  const { frameLen, router, packetSrc, dataType, seq } = inspectFrameHeader(data);
+  if (dataType !== PROTO_DATA_TYPE_PACKET) {
+    throw new Error(`Invalid Protocol V2 data type: expected packet, got ${dataType}`);
+  }
   // Payload spans bytes 7 to frameLen-2 (inclusive), excluding final CRC byte
   const payloadData = data.slice(7, frameLen - 1);
 
@@ -85,5 +122,5 @@ export function decodeFrame(data: Uint8Array): ProtoV2Frame {
   const messageTypeId = payloadData[0] + payloadData[1] * 256;
   const pbPayload = payloadData.slice(2);
 
-  return { messageTypeId, pbPayload, seq };
+  return { messageTypeId, pbPayload, seq, router, packetSrc, dataType };
 }

package/src/protocols/v2/errors.ts

@@ -0,0 +1,23 @@
+export type ProtocolV2LinkErrorCode =
+  | 'response-timeout'
+  | 'router'
+  | 'packet-source'
+  | 'ack-sequence'
+  | 'response-sequence'
+  | 'frame';
+
+export class ProtocolV2LinkError extends Error {
+  readonly code: ProtocolV2LinkErrorCode;
+
+  readonly cause?: unknown;
+
+  constructor(code: ProtocolV2LinkErrorCode, message: string, cause?: unknown) {
+    super(message);
+    this.name = 'ProtocolV2LinkError';
+    this.code = code;
+    this.cause = cause;
+  }
+}
+
+export const isProtocolV2LinkError = (error: unknown): error is ProtocolV2LinkError =>
+  error instanceof ProtocolV2LinkError;

package/src/protocols/v2/frame-assembler.ts

@@ -1,6 +1,7 @@
 import { PROTOCOL_V2_FRAME_MAX_BYTES } from '../../constants';
 import { PROTO_HEAD_CRC_SIZE, PROTO_HEAD_SOF, PROTO_PRE_HEAD_SIZE } from './constants';
 import { crc8 } from './crc8';
+import { ProtocolV2LinkError } from './errors';
 
 export function concatUint8Arrays(arrays: Uint8Array[]): Uint8Array {
   const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
@@ -58,7 +59,7 @@ export class ProtocolV2FrameAssembler {
 
     if (this.buffer[0] !== PROTO_HEAD_SOF) {
       this.reset();
-      throw new Error('Invalid Protocol V2 SOF');
+      throw new ProtocolV2LinkError('frame', 'Invalid Protocol V2 SOF');
     }
 
     const expectedLen = this.buffer[1] + this.buffer[2] * 256;
@@ -67,11 +68,11 @@ export class ProtocolV2FrameAssembler {
       // complete frame: without resetting, this poison prefix would stay in
       // the buffer forever and deadlock the caller's drain loop.
       this.reset();
-      throw new Error(`Protocol V2 frame length too small: ${expectedLen}`);
+      throw new ProtocolV2LinkError('frame', `Protocol V2 frame length too small: ${expectedLen}`);
     }
     if (expectedLen > this.maxFrameBytes) {
       this.reset();
-      throw new Error(`Protocol V2 frame too large: ${expectedLen}`);
+      throw new ProtocolV2LinkError('frame', `Protocol V2 frame too large: ${expectedLen}`);
     }
 
     if (this.buffer.length < PROTO_PRE_HEAD_SIZE) return undefined;
@@ -82,7 +83,8 @@ export class ProtocolV2FrameAssembler {
     const expectedHeaderCrc = crc8(this.buffer, 3);
     if (this.buffer[3] !== expectedHeaderCrc) {
       this.reset();
-      throw new Error(
+      throw new ProtocolV2LinkError(
+        'frame',
         `Protocol V2 header CRC mismatch: expected 0x${expectedHeaderCrc
           .toString(16)
           .padStart(2, '0')}`

package/src/protocols/v2/index.ts

@@ -2,4 +2,5 @@ export * from './constants';
 export * from './crc8';
 export * from './encode';
 export * from './decode';
+export * from './errors';
 export * from './frame-assembler';

package/src/protocols/v2/session.ts

@@ -1,6 +1,10 @@
-import { PROTOCOL_V2_PACKET_SRC_COMMAND } from '../../constants';
+import {
+  PROTOCOL_V2_DEFAULT_RESPONSE_TIMEOUT_MS,
+  PROTOCOL_V2_PACKET_SRC_COMMAND,
+} from '../../constants';
 import { ProtocolV2FrameAssembler, concatUint8Arrays } from './frame-assembler';
 import { ProtocolV2SequenceCursor } from './sequence-cursor';
+import { ProtocolV2LinkError } from './errors';
 import { ProtocolV2 } from '..';
 import * as check from '../../utils/highlevel-checks';
 import { LogBlockCommand } from '../../utils/logBlockCommand';
@@ -8,6 +12,8 @@ import { LogBlockCommand } from '../../utils/logBlockCommand';
 import type { Root } from 'protobufjs/light';
 import type { MessageFromOneKey } from '../../types';
 
+export * from './errors';
+
 export type ProtocolV2Schemas = {
   protocolV1: Root;
   protocolV2: Root;
@@ -18,6 +24,7 @@ export type ProtocolV2CallContext = {
   timeoutMs?: number;
   highVolume: boolean;
   generation: number;
+  signal: AbortSignal;
 };
 
 type ProtocolLogger = {
@@ -114,11 +121,13 @@ export async function withProtocolTimeout<T>(
   promise: Promise<T>,
   timeoutMs: number | undefined,
   createTimeoutError: () => Error,
-  onTimeout?: () => void
+  onTimeout?: () => void,
+  abortSignal?: AbortSignal
 ): Promise<T> {
   if (!timeoutMs) return promise;
 
   let timer: ReturnType<typeof setTimeout> | undefined;
+  let abortHandler: (() => void) | undefined;
   try {
     return await Promise.race([
       promise,
@@ -130,9 +139,26 @@ export async function withProtocolTimeout<T>(
           reject(createTimeoutError());
         }, timeoutMs);
       }),
+      ...(abortSignal
+        ? [
+            new Promise<never>((_, reject) => {
+              abortHandler = () => {
+                reject(new Error('Protocol V2 operation aborted'));
+              };
+              if (abortSignal.aborted) {
+                abortHandler();
+              } else {
+                abortSignal.addEventListener('abort', abortHandler, { once: true });
+              }
+            }),
+          ]
+        : []),
     ]);
   } finally {
     if (timer) clearTimeout(timer);
+    if (abortHandler) {
+      abortSignal?.removeEventListener('abort', abortHandler);
+    }
   }
 }
 
@@ -145,6 +171,8 @@ export class ProtocolV2Session {
   // in-flight calls on the same session would steal each other's responses.
   private pendingCall: Promise<unknown> = Promise.resolve();
 
+  private lastResponseSequence?: number;
+
   constructor(options: ProtocolV2SessionOptions) {
     this.options = options;
     this.sequenceCursor = options.sequenceCursor ?? new ProtocolV2SequenceCursor();
@@ -163,7 +191,7 @@ export class ProtocolV2Session {
     return result;
   }
 
-  private async executeCall(
+  private executeCall(
     name: string,
     data: Record<string, unknown>,
     callOptions: ProtocolV2CallOptions
@@ -181,78 +209,105 @@ export class ProtocolV2Session {
       createTimeoutError,
       generation = 0,
     } = this.options;
+    const timeoutMs =
+      callOptions.timeoutMs && callOptions.timeoutMs > 0
+        ? callOptions.timeoutMs
+        : PROTOCOL_V2_DEFAULT_RESPONSE_TIMEOUT_MS;
+    const abortController = new AbortController();
 
     const shouldReduceDebug = shouldReduceProtocolV2Debug(name);
-    const callContext: ProtocolV2CallContext = {
+    const baseCallContext: ProtocolV2CallContext = {
       messageName: name,
-      timeoutMs: callOptions.timeoutMs,
+      timeoutMs,
       highVolume: shouldReduceDebug,
       generation,
+      signal: abortController.signal,
     };
-    await prepareCall?.(callContext);
-    const protoSeq = this.sequenceCursor.next();
-    const frame = ProtocolV2.encodeFrame(schemas, name, data, {
-      packetSrc,
-      router,
-      seq: protoSeq,
-    });
-    // Suppress Protocol V2 TX frame logs to avoid excessive transport diagnostics.
-    /*
-    const txMetadata = ProtocolV2.inspectFrame(schemas, frame);
-
-    if (!shouldReduceDebug) {
-      logger?.debug?.(`[${logPrefix}] TX`, {
-        method: name,
-        type: name,
-        typeId: txMetadata.messageTypeId,
-        seq: txMetadata.seq,
-        bytes: frame.length,
-      });
-    }
-    */
 
-    if (maxFrameBytes !== undefined && frame.length > maxFrameBytes) {
-      throw new Error(
-        `Protocol V2 frame too large for transport: ${frame.length} > ${maxFrameBytes}`
-      );
-    }
+    const runCall = async (): Promise<MessageFromOneKey> => {
+      await prepareCall?.(baseCallContext);
+      const protoSeq = this.sequenceCursor.next();
+      const frame = ProtocolV2.encodeFrame(schemas, name, data, {
+        packetSrc,
+        router,
+        seq: protoSeq,
+      });
 
-    await writeFrame(frame, callContext);
+      if (maxFrameBytes !== undefined && frame.length > maxFrameBytes) {
+        throw new Error(
+          `Protocol V2 frame too large for transport: ${frame.length} > ${maxFrameBytes}`
+        );
+      }
 
-    // Cancellation flag for the read loop: when the response timeout fires,
-    // Promise.race alone would leave this loop running as a zombie that keeps
-    // consuming frames meant for the next call. The timeout callback flips the
-    // flag so the loop exits and discards any late frame.
-    const cancellation = { cancelled: false };
+      await writeFrame(frame, baseCallContext);
 
-    const readResponse = async (): Promise<MessageFromOneKey> => {
       // 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.
-      while (!cancellation.cancelled) {
-        const rxFrame = await readFrame(callContext);
-        if (cancellation.cancelled) {
-          // Timed out while waiting: drop the late frame and stop reading.
-          break;
+      while (!abortController.signal.aborted) {
+        const rxFrame = await readFrame(baseCallContext);
+        if (abortController.signal.aborted) break;
+
+        let header: ReturnType<typeof ProtocolV2.inspectFrameHeader>;
+        try {
+          header = ProtocolV2.inspectFrameHeader(rxFrame);
+        } catch (cause) {
+          throw new ProtocolV2LinkError(
+            'frame',
+            `Protocol V2 frame validation failed: ${getErrorMessage(cause)}`,
+            cause
+          );
+        }
+        if (header.router !== router) {
+          throw new ProtocolV2LinkError(
+            'router',
+            `Protocol V2 router mismatch: expected ${router}, got ${header.router}`
+          );
+        }
+        if (header.packetSrc !== packetSrc) {
+          throw new ProtocolV2LinkError(
+            'packet-source',
+            `Protocol V2 packet source mismatch: expected ${packetSrc}, got ${header.packetSrc}`
+          );
         }
-        const isAck = ProtocolV2.isAckFrame(rxFrame);
-        if (!isAck) {
-          // Suppress Protocol V2 RX frame logs to avoid excessive transport diagnostics.
-          /*
-          const rxMetadata = ProtocolV2.inspectFrame(schemas, rxFrame);
-
-          if (!shouldReduceDebug) {
-            logger?.debug?.(`[${logPrefix}] RX`, {
-              method: name,
-              type: rxMetadata.type,
-              typeId: rxMetadata.messageTypeId,
-              seq: rxMetadata.seq,
-              bytes: rxFrame.length,
-            });
-          }
-          */
 
-          const decoded = ProtocolV2.decodeFrame(schemas, rxFrame);
+        let isAck: boolean;
+        try {
+          isAck = ProtocolV2.isAckFrame(rxFrame);
+        } catch (cause) {
+          throw new ProtocolV2LinkError(
+            'frame',
+            `Protocol V2 ACK validation failed: ${getErrorMessage(cause)}`,
+            cause
+          );
+        }
+        if (isAck) {
+          if (header.seq !== protoSeq) {
+            throw new ProtocolV2LinkError(
+              'ack-sequence',
+              `Protocol V2 ACK sequence mismatch: expected ${protoSeq}, got ${header.seq}`
+            );
+          }
+        } else {
+          let decoded: ReturnType<typeof ProtocolV2.decodeFrame>;
+          try {
+            decoded = ProtocolV2.decodeFrame(schemas, rxFrame);
+          } catch (cause) {
+            throw new ProtocolV2LinkError(
+              'frame',
+              `Protocol V2 frame decode failed: ${getErrorMessage(cause)}`,
+              cause
+            );
+          }
+          // Firmware owns one TX sequence across all channels and packet sources,
+          // so frames routed elsewhere create valid gaps in this session.
+          if (this.lastResponseSequence === decoded.seq) {
+            throw new ProtocolV2LinkError(
+              'response-sequence',
+              `Protocol V2 duplicate response sequence: ${decoded.seq}`
+            );
+          }
+          this.lastResponseSequence = decoded.seq;
 
           const response = check.call(decoded);
           if (callOptions.intermediateTypes?.includes(response.type)) {
@@ -268,20 +323,19 @@ export class ProtocolV2Session {
           }
         }
       }
-      // Only reachable after cancellation; the outer promise has already been
-      // rejected by the timeout, so this rejection is consumed by the race.
+
       throw new Error(`Protocol V2 read loop cancelled after timeout for ${name}`);
     };
 
     return withProtocolTimeout(
-      readResponse(),
-      callOptions.timeoutMs,
+      runCall(),
+      timeoutMs,
       () =>
         createTimeoutError
-          ? createTimeoutError(name, callOptions.timeoutMs ?? 0)
-          : new Error(`Protocol V2 response timeout after ${callOptions.timeoutMs}ms for ${name}`),
+          ? createTimeoutError(name, timeoutMs)
+          : new Error(`Protocol V2 response timeout after ${timeoutMs}ms for ${name}`),
       () => {
-        cancellation.cancelled = true;
+        abortController.abort();
       }
     );
   }
@@ -312,7 +366,10 @@ export async function probeProtocolV2({
     const response = await call(
       'Ping',
       { message: 'protocol-v2-probe' },
-      { timeoutMs, expectedTypes: ['Success'] }
+      {
+        timeoutMs,
+        expectedTypes: ['Success'],
+      }
     );
     if (response.type === 'Success') {
       return true;

package/src/types/messages.ts

@@ -4744,7 +4744,9 @@ export type ViewVerifyPage = {
 };
 
 // ProtocolInfoRequest
-export type ProtocolInfoRequest = {};
+export type ProtocolInfoRequest = {
+  eventless_wallet_session?: boolean;
+};
 
 // ProtocolInfo
 export type ProtocolInfo = {
@@ -5049,6 +5051,15 @@ export type ProtocolV2DeviceInfo = {
   status?: DeviceStatus;
 };
 
+export enum DeviceSessionErrorCode {
+  DeviceSessionError_None = 0,
+  DeviceSessionError_UserCancelled = 1,
+  DeviceSessionError_InvalidSession = 2,
+  DeviceSessionError_AttachPinUnavailable = 3,
+  DeviceSessionError_PassphraseDisabled = 4,
+  DeviceSessionError_Busy = 5,
+}
+
 // DeviceSessionGet
 export type DeviceSessionGet = {
   session_id?: string;
@@ -5060,8 +5071,19 @@ export type DeviceSession = {
   btc_test_address?: string;
 };
 
+export enum DeviceSessionPinType {
+  Any = 1,
+  Main = 2,
+  AttachToPin = 3,
+}
+
 // DeviceSessionAskPin
-export type DeviceSessionAskPin = {};
+export type DeviceSessionAskPin = {
+  type?: DeviceSessionPinType;
+};
+
+// DeviceSessionAskPassphrase
+export type DeviceSessionAskPassphrase = {};
 
 export enum DeviceSessionAskPin_FailureSubCodes {
   UserCancel = 1,
@@ -5884,6 +5906,7 @@ export type MessageType = {
   DeviceSessionGet: DeviceSessionGet;
   DeviceSession: DeviceSession;
   DeviceSessionAskPin: DeviceSessionAskPin;
+  DeviceSessionAskPassphrase: DeviceSessionAskPassphrase;
   DeviceStatus: DeviceStatus;
   DeviceStatusGet: DeviceStatusGet;
   DevOnboardingSetupStatus: DevOnboardingSetupStatus;