@onekeyfe/hd-core 1.2.0-alpha.8 → 1.2.0-alpha.81

package/src/protocols/protocol-v2/features.ts

@@ -1,10 +1,15 @@
 import { DeviceSEState, DeviceSeType } from '@onekeyfe/hd-transport';
 
-import type { DeviceInfoGet, DeviceSEInfo, ProtocolV2DeviceInfo } from '@onekeyfe/hd-transport';
+import type {
+  DeviceInfoGet,
+  DeviceSEInfo,
+  DeviceStatus,
+  ProtocolInfo,
+  ProtocolV2DeviceInfo,
+} from '@onekeyfe/hd-transport';
 import type { DeviceCommands } from '../../device/DeviceCommands';
 
-// 单源类型：直接使用 hd-transport 生成的 ProtocolV2DeviceInfo / DeviceSEInfo /
-// DeviceFirmwareImageInfo（与 firmware-pro2 proto 一致），不再维护手写副本。
+// Use hd-transport generated Protocol V2 types as the single source of truth.
 export type { ProtocolV2DeviceInfo };
 export type { DeviceFirmwareImageInfo as ProtocolV2FirmwareImageInfo } from '@onekeyfe/hd-transport';
 export type { DeviceSEInfo as ProtocolV2SEInfo } from '@onekeyfe/hd-transport';
@@ -12,8 +17,8 @@ export type { DeviceSEInfo as ProtocolV2SEInfo } from '@onekeyfe/hd-transport';
 export type ProtocolV2SeStateLabel = 'BOOT' | 'APP_FACTORY' | 'APP';
 
 /**
- * 传输层沿用历史 decode 语义：单值 proto enum 输出为名称字符串。
- * 这里按 SDK decode 后的字符串语义处理，同时接受数字枚举，便于低层调用复用。
+ * The transport historically decodes scalar proto enums as name strings.
+ * Accept both that SDK representation and numeric enums for low-level callers.
  */
 const normalizeEnumValue = <T extends Record<string | number, string | number>>(
   enumObject: T,
@@ -26,8 +31,8 @@ const normalizeEnumValue = <T extends Record<string | number, string | number>>(
 };
 
 /**
- * DeviceSEInfo.state → 可读标签。SDK 内唯一的 SE 状态映射实现，
- * DeviceProfile 与标准 Features 构建都从这里取。
+ * Map DeviceSEInfo.state to a readable label. This is the SDK's canonical mapping
+ * used by DeviceState and the legacy Features projection.
  */
 export const getProtocolV2SeState = (se?: DeviceSEInfo): ProtocolV2SeStateLabel | null => {
   const label = normalizeEnumValue(DeviceSEState, se?.state);
@@ -44,21 +49,64 @@ export const getProtocolV2SeState = (se?: DeviceSEInfo): ProtocolV2SeStateLabel
 };
 
 /**
- * DeviceSEInfo.type → 可读标签（如 'THD89'）。DeviceProfile / Features
- * 的 SE 类型归一化从这里取。
+ * Map DeviceSEInfo.type to a readable label such as `THD89`.
  */
 export const getProtocolV2SeType = (se?: DeviceSEInfo): string | null =>
   normalizeEnumValue(DeviceSeType, se?.type);
 
-export const isProtocolV2BootloaderDeviceInfo = (deviceInfo?: ProtocolV2DeviceInfo | null) =>
-  !!deviceInfo && deviceInfo.status == null;
+export type ProtocolV2RuntimeMode = 'normal' | 'bootloader' | 'romloader';
+
+/**
+ * Protocol V2 fingerprints use:
+ * <binary>__<version>__<commit>__<PROD|DEV>__<DEBUG|RELEASE>
+ */
+export type ProtocolV2BuildFingerprint = {
+  binary: 'application' | 'bootloader' | 'romloader';
+  version: string;
+  commit: string;
+  environment: 'PROD' | 'DEV';
+  buildType: 'DEBUG' | 'RELEASE';
+};
+
+export const parseProtocolV2BuildFingerprint = (
+  buildFingerprint: string | null | undefined
+): ProtocolV2BuildFingerprint | null => {
+  if (!buildFingerprint) return null;
+  const [binary, version, commit, environment, buildType, ...extra] = buildFingerprint.split('__');
+  if (
+    extra.length > 0 ||
+    (binary !== 'application' && binary !== 'bootloader' && binary !== 'romloader') ||
+    !version ||
+    !commit ||
+    (environment !== 'PROD' && environment !== 'DEV') ||
+    (buildType !== 'DEBUG' && buildType !== 'RELEASE')
+  ) {
+    return null;
+  }
+  return { binary, version, commit, environment, buildType };
+};
+
+export const getProtocolV2RuntimeMode = (
+  protocolInfo: ProtocolInfo
+): ProtocolV2RuntimeMode | undefined => {
+  const binary = parseProtocolV2BuildFingerprint(protocolInfo.build_fingerprint)?.binary;
+  if (binary === 'application') return 'normal';
+  return binary;
+};
+
+// MessageType_DeviceStatusGet in the Protocol V2 protobuf registry.
+export const PROTOCOL_V2_DEVICE_STATUS_GET_MESSAGE_TYPE = 60602;
+
+export const supportsProtocolV2Message = (
+  protocolInfo: ProtocolInfo,
+  messageType: number
+): boolean => protocolInfo.supported_messages.includes(messageType);
 
 export const PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST = {
   targets: {
     hw: true,
     fw: true,
     coprocessor: true,
-    status: true,
   },
   types: {
     version: true,
@@ -67,23 +115,9 @@ export const PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST = {
 };
 
 /**
- * 轻量状态刷新请求（每次 run 前使用）。
- *
- * status 提供 init_states / passphrase_enabled 等会在设备端变化的字段；
- * hw / coprocessor 提供 serialNo / bleName 等身份字段；不含 fw/SE targets，单帧请求开销很小。
+ * Version probe used after firmware update completion.
+ * It reads hardware and firmware component data without requesting DeviceStatus.
  */
-export const PROTOCOL_V2_STATUS_DEVICE_INFO_REQUEST = {
-  targets: {
-    hw: true,
-    coprocessor: true,
-    status: true,
-  },
-  types: {
-    version: true,
-    specific: true,
-  },
-};
-
 export const PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST = {
   targets: {
     hw: true,
@@ -93,7 +127,6 @@ export const PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST = {
     se2: true,
     se3: true,
     se4: true,
-    status: true,
   },
   types: {
     version: true,
@@ -110,7 +143,6 @@ export const PROTOCOL_V2_FULL_DEVICE_INFO_REQUEST = {
     se2: true,
     se3: true,
     se4: true,
-    status: true,
   },
   types: {
     version: true,
@@ -121,7 +153,28 @@ export const PROTOCOL_V2_FULL_DEVICE_INFO_REQUEST = {
 };
 
 export const PROTOCOL_V2_DEVICE_INFO_REQUEST = PROTOCOL_V2_FULL_DEVICE_INFO_REQUEST;
-export const PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS = 10 * 1000;
+export const PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS = 30 * 1000;
+
+export async function requestProtocolV2ProtocolInfo({
+  commands,
+  timeoutMs,
+}: {
+  commands: DeviceCommands;
+  timeoutMs?: number;
+}): Promise<ProtocolInfo> {
+  const response =
+    timeoutMs === undefined
+      ? await commands.typedCall('ProtocolInfoRequest', 'ProtocolInfo', {
+          eventless_wallet_session: true,
+        })
+      : await commands.typedCall(
+          'ProtocolInfoRequest',
+          'ProtocolInfo',
+          { eventless_wallet_session: true },
+          { timeoutMs }
+        );
+  return response.message;
+}
 
 export async function requestProtocolV2DeviceInfo({
   commands,
@@ -135,7 +188,21 @@ export async function requestProtocolV2DeviceInfo({
   const { message } = await commands.typedCall('DeviceInfoGet', 'DeviceInfo', request, {
     timeoutMs,
   });
-  // 'DeviceInfo' 在生成类型里是 V1 DeviceInfo | ProtocolV2DeviceInfo 的合并；
-  // DeviceInfoGet 是 V2-only 消息，这里收窄到 V2 形态。
+  // Generated DeviceInfo is a V1/V2 union; DeviceInfoGet narrows it to the V2 shape.
   return message as ProtocolV2DeviceInfo;
 }
+
+export async function requestProtocolV2DeviceStatus({
+  commands,
+  timeoutMs,
+}: {
+  commands: DeviceCommands;
+  timeoutMs?: number;
+}): Promise<DeviceStatus> {
+  const response =
+    timeoutMs === undefined
+      ? await commands.typedCall('DeviceStatusGet', 'DeviceStatus', {})
+      : await commands.typedCall('DeviceStatusGet', 'DeviceStatus', {}, { timeoutMs });
+  const { message } = response;
+  return message;
+}

package/src/protocols/protocol-v2/firmware.ts

@@ -1,5 +1,5 @@
 /**
- * 当前 firmware-pro2 子模块的 DeviceFirmwareTargetType。
+ * DeviceFirmwareTargetType from the current firmware-pro2 submodule.
  */
 export const ProtocolV2FirmwareTargetType = {
   FW_MGMT_TARGET_INVALID: 0,
@@ -15,5 +15,7 @@ export const ProtocolV2FirmwareTargetType = {
   FW_MGMT_TARGET_SE04: 10,
 } as const;
 
+// 这里有意同时导出同名值与类型，以保持现有公共 API 不变。
+// eslint-disable-next-line @typescript-eslint/no-redeclare
 export type ProtocolV2FirmwareTargetType =
   (typeof ProtocolV2FirmwareTargetType)[keyof typeof ProtocolV2FirmwareTargetType];

package/src/protocols/protocol-v2/index.ts

@@ -1,16 +1,23 @@
 export {
   PROTOCOL_V2_DEVICE_INFO_REQUEST,
   PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS,
+  PROTOCOL_V2_DEVICE_STATUS_GET_MESSAGE_TYPE,
   PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST,
-  PROTOCOL_V2_STATUS_DEVICE_INFO_REQUEST,
   PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
+  getProtocolV2RuntimeMode,
   getProtocolV2SeState,
   getProtocolV2SeType,
+  parseProtocolV2BuildFingerprint,
+  requestProtocolV2ProtocolInfo,
+  supportsProtocolV2Message,
 } from './features';
 export type {
+  ProtocolV2BuildFingerprint,
   ProtocolV2DeviceInfo,
   ProtocolV2FirmwareImageInfo,
   ProtocolV2SEInfo,
   ProtocolV2SeStateLabel,
+  ProtocolV2RuntimeMode,
 } from './features';
 export * from './firmware';
+export * from './walletSession';

package/src/protocols/protocol-v2/resources.ts

@@ -0,0 +1,257 @@
+import { sha256 } from '@noble/hashes/sha256';
+
+import type {
+  IProtocolV2ResourceManifest,
+  IProtocolV2ResourceManifestFile,
+  IProtocolV2Resources,
+} from '../../types';
+import type { FirmwareUpdateV4Target } from '../../types/api/firmwareUpdate';
+
+export const PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_PATH =
+  'vol0:/loaders/bootloader/boot_resource.okpkg';
+export const PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_STAGING_PATH = `${PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_PATH}.staging`;
+export const PROTOCOL_V2_ROM_PARAMS_PACKAGE_PATH = 'vol0:/loaders/rom/params.okpkg';
+
+const SHA256_HEX_LENGTH = 64;
+
+function normalizeHex(value: unknown, expectedLength: number, field: string): string {
+  if (typeof value !== 'string') {
+    throw new Error(`Invalid Pro2 resource ${field}: expected a hexadecimal string`);
+  }
+  const normalized = value.replace(/^0x/i, '').toLowerCase();
+  if (normalized.length !== expectedLength || !/^[0-9a-f]+$/.test(normalized)) {
+    throw new Error(
+      `Invalid Pro2 resource ${field}: expected ${expectedLength} hexadecimal characters`
+    );
+  }
+  return normalized;
+}
+
+/** Validate a complete Pro2 stable resource set from remote configuration. */
+export function parseProtocolV2Resources(value: unknown): IProtocolV2Resources | undefined {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== 'object') {
+    throw new Error('Invalid Pro2 resources config');
+  }
+  const { source } = value as { source?: unknown };
+  if (!source || typeof source !== 'object') {
+    throw new Error('Invalid Pro2 resources config: source is required');
+  }
+  const { archiveUrl, archiveSha256, archiveSize } = source as {
+    archiveUrl?: unknown;
+    archiveSha256?: unknown;
+    archiveSize?: unknown;
+  };
+  if (typeof archiveUrl !== 'string' || !archiveUrl.startsWith('https://')) {
+    throw new Error('Invalid Pro2 resources config: source.archiveUrl must use HTTPS');
+  }
+  if (typeof archiveSha256 !== 'string' || !/^[0-9a-fA-F]{64}$/.test(archiveSha256)) {
+    throw new Error('Invalid Pro2 resources config: source.archiveSha256 must be a SHA-256 digest');
+  }
+  if (!Number.isSafeInteger(archiveSize) || (archiveSize as number) <= 0) {
+    throw new Error('Invalid Pro2 resources config: source.archiveSize must be a positive integer');
+  }
+  return {
+    source: {
+      archiveUrl,
+      archiveSha256: archiveSha256.toLowerCase(),
+      archiveSize: archiveSize as number,
+    },
+  };
+}
+
+const PROTOCOL_V2_RESOURCE_MANIFEST_DEVICE_ROOTS = [
+  'vol0:/bundles/',
+  'vol0:/loaders/rom/',
+] as const;
+
+function isAllowedManifestDevicePath(path: string): boolean {
+  if (
+    !path.endsWith('.okpkg') ||
+    path.includes('\\') ||
+    path.includes('//') ||
+    path.split('/').some(part => part === '.' || part === '..')
+  ) {
+    return false;
+  }
+  if (path === PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_PATH) {
+    return true;
+  }
+  return PROTOCOL_V2_RESOURCE_MANIFEST_DEVICE_ROOTS.some(root => path.startsWith(root));
+}
+
+function assertManifestString(value: unknown, field: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Invalid Pro2 resource manifest ${field}`);
+  }
+  return value;
+}
+
+function assertManifestRelativePath(value: unknown, field: string): string {
+  const path = assertManifestString(value, field);
+  if (
+    path.startsWith('/') ||
+    path.includes('\\') ||
+    path.includes(':') ||
+    path.split('/').some(part => !part || part === '.' || part === '..')
+  ) {
+    throw new Error(`Invalid Pro2 resource manifest ${field}`);
+  }
+  return path;
+}
+
+function parseProtocolV2ResourceManifestFile(
+  value: unknown,
+  index: number
+): IProtocolV2ResourceManifestFile {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`Invalid Pro2 resource manifest files[${index}]`);
+  }
+  const file = value as Partial<IProtocolV2ResourceManifestFile>;
+  const archivePath = assertManifestRelativePath(file.archive_path, `files[${index}].archive_path`);
+  const originalName = assertManifestRelativePath(
+    file.original_name,
+    `files[${index}].original_name`
+  );
+  if (originalName.includes('/')) {
+    throw new Error(`Invalid Pro2 resource manifest files[${index}].original_name`);
+  }
+  const devicePath = assertManifestString(file.device_path, `files[${index}].device_path`);
+  if (!isAllowedManifestDevicePath(devicePath)) {
+    throw new Error(`Invalid Pro2 resource manifest files[${index}].device_path`);
+  }
+  if (!Number.isSafeInteger(file.size) || Number(file.size) <= 0) {
+    throw new Error(`Invalid Pro2 resource manifest files[${index}].size`);
+  }
+  const digest = normalizeHex(file.sha256, SHA256_HEX_LENGTH, `files[${index}].sha256`);
+  if (file.signed !== true) {
+    throw new Error(`Invalid Pro2 resource manifest files[${index}].signed`);
+  }
+  if (file.sig_algo !== 'ed25519' && file.sig_algo !== 'mldsa65') {
+    throw new Error(`Invalid Pro2 resource manifest files[${index}].sig_algo`);
+  }
+  if (file.payload_version !== null && typeof file.payload_version !== 'string') {
+    throw new Error(`Invalid Pro2 resource manifest files[${index}].payload_version`);
+  }
+  if (!archivePath.endsWith('.okpkg') || !originalName.endsWith('.okpkg')) {
+    throw new Error(`Invalid Pro2 resource manifest files[${index}] package extension`);
+  }
+  return {
+    archive_path: archivePath,
+    original_name: originalName,
+    device_path: devicePath,
+    size: Number(file.size),
+    sha256: digest,
+    signed: true,
+    sig_algo: file.sig_algo,
+    payload_version: file.payload_version ?? null,
+  };
+}
+
+export function parseProtocolV2ResourceManifest(value: unknown): IProtocolV2ResourceManifest {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Invalid Pro2 resource manifest');
+  }
+  const manifest = value as Partial<IProtocolV2ResourceManifest>;
+  if (
+    manifest.schema !== 1 ||
+    manifest.variant !== 'resource' ||
+    manifest.device_root !== 'vol0:' ||
+    manifest.restore_mode !== 'bootloader_update' ||
+    !Array.isArray(manifest.trees) ||
+    !Array.isArray(manifest.files)
+  ) {
+    throw new Error('Invalid Pro2 resource manifest contract');
+  }
+  const files = manifest.files.map(parseProtocolV2ResourceManifestFile);
+  const devicePaths = new Set(files.map(file => file.device_path));
+  const archivePaths = new Set(files.map(file => file.archive_path));
+  if (
+    files.length === 0 ||
+    devicePaths.size !== files.length ||
+    archivePaths.size !== files.length ||
+    !devicePaths.has(PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_PATH) ||
+    !files.some(file => file.device_path.startsWith('vol0:/bundles/'))
+  ) {
+    throw new Error('Invalid Pro2 resource manifest file set');
+  }
+  return {
+    schema: 1,
+    artifact_name: assertManifestString(manifest.artifact_name, 'artifact_name'),
+    release_name: assertManifestString(manifest.release_name, 'release_name'),
+    variant: 'resource',
+    commit: assertManifestString(manifest.commit, 'commit'),
+    short_sha: assertManifestString(manifest.short_sha, 'short_sha'),
+    timestamp_utc: assertManifestString(manifest.timestamp_utc, 'timestamp_utc'),
+    core_version: assertManifestString(manifest.core_version, 'core_version'),
+    key_set: assertManifestString(manifest.key_set, 'key_set'),
+    device_root: 'vol0:',
+    restore_mode: 'bootloader_update',
+    trees: manifest.trees.map((tree, index) => {
+      if (!tree || typeof tree !== 'object') {
+        throw new Error(`Invalid Pro2 resource manifest trees[${index}]`);
+      }
+      const item = tree as { path?: unknown; device?: unknown };
+      return {
+        path: assertManifestRelativePath(item.path, `trees[${index}].path`),
+        device: assertManifestString(item.device, `trees[${index}].device`),
+      };
+    }),
+    files,
+  };
+}
+
+export function selectProtocolV2ResourceManifestFiles({
+  manifest,
+  targetsToUpdate,
+}: {
+  manifest: IProtocolV2ResourceManifest;
+  targetsToUpdate: readonly FirmwareUpdateV4Target[];
+}): IProtocolV2ResourceManifestFile[] {
+  return targetsToUpdate.includes('resource') ? [...manifest.files] : [];
+}
+
+export function prepareProtocolV2ResourceFiles({
+  manifest: value,
+  files,
+  targetsToUpdate,
+}: {
+  manifest: unknown;
+  files: Array<{ archivePath: string; binary: ArrayBuffer }>;
+  targetsToUpdate: readonly FirmwareUpdateV4Target[];
+}): Array<{ binary: ArrayBuffer; devicePath: string; size: number; fileHash: string }> {
+  const manifest = parseProtocolV2ResourceManifest(value);
+  const selected = selectProtocolV2ResourceManifestFiles({ manifest, targetsToUpdate });
+  const binaries = new Map(files.map(file => [file.archivePath, file.binary] as const));
+  return selected.map(file => {
+    const binary = binaries.get(file.archive_path);
+    if (
+      !binary ||
+      !isProtocolV2ResourceFileValid(binary, {
+        size: file.size,
+        fileHash: file.sha256,
+      })
+    ) {
+      throw new Error(`Pro2 resource manifest file verification failed: ${file.archive_path}`);
+    }
+    return {
+      binary,
+      devicePath: file.device_path,
+      size: file.size,
+      fileHash: file.sha256,
+    };
+  });
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+}
+
+/** Verify the complete downloaded file before any device mutation. */
+export function isProtocolV2ResourceFileValid(
+  binary: ArrayBuffer,
+  resource: { size: number; fileHash: string }
+): boolean {
+  if (binary.byteLength !== resource.size) return false;
+  return bytesToHex(sha256(new Uint8Array(binary))) === resource.fileHash.toLowerCase();
+}

package/src/protocols/protocol-v2/settingsUnlockPolicy.ts

@@ -0,0 +1,65 @@
+import type { DeviceSettings, DeviceSettingsPage } from '@onekeyfe/hd-transport';
+import type { UnlockPolicy } from '../../api/BaseMethod';
+import type { ProtocolV2InteractionDescriptor } from './uiInteraction';
+
+export const PROTOCOL_V2_LOCK_FREE_DEVICE_SETTINGS = [
+  'language',
+  'brightness',
+  'animation_enable',
+  'tap_to_wake',
+  'haptic_feedback',
+  'device_name_display_enabled',
+] as const satisfies readonly (keyof DeviceSettings)[];
+
+const lockFreeDeviceSettings = new Set<keyof DeviceSettings>(PROTOCOL_V2_LOCK_FREE_DEVICE_SETTINGS);
+
+export const getProtocolV2SettingsUnlockPolicy = (settings: DeviceSettings): UnlockPolicy =>
+  Object.keys(settings).every(key => lockFreeDeviceSettings.has(key as keyof DeviceSettings))
+    ? 'none'
+    : 'unlock-before-run';
+
+export type ProtocolV2SettingsOperation =
+  | {
+      kind: 'direct';
+      settings: DeviceSettings;
+    }
+  | {
+      kind: 'page';
+      page: DeviceSettingsPage;
+    };
+
+export const getProtocolV2SettingsBehavior = (
+  operation: ProtocolV2SettingsOperation
+): {
+  unlockPolicy: UnlockPolicy;
+  uiInteraction?: ProtocolV2InteractionDescriptor;
+} => {
+  if (operation.kind === 'page') {
+    return {
+      unlockPolicy: 'unlock-before-run',
+      uiInteraction: {
+        request: 'button',
+        source: 'method-lifecycle',
+        reason: 'settings-page',
+        completion: 'operation-completed',
+        deviceOnly: true,
+        page: operation.page,
+      },
+    };
+  }
+
+  return {
+    unlockPolicy: getProtocolV2SettingsUnlockPolicy(operation.settings),
+    uiInteraction:
+      typeof operation.settings.label === 'string'
+        ? {
+            request: 'button',
+            source: 'method-lifecycle',
+            reason: 'device-management',
+            completion: 'operation-completed',
+            deviceOnly: true,
+            operation: 'change-label',
+          }
+        : undefined,
+  };
+};