@onekeyfe/hd-core 1.1.34-alpha.2 → 1.1.34-alpha.3

package/src/api/protocol-v2/DeviceInfoGet.ts

@@ -0,0 +1,145 @@
+import { createDeviceNotSupportMethodError } from '@onekeyfe/hd-shared';
+
+import { UI_REQUEST } from '../../constants/ui-request';
+import { PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS } from '../../protocols/protocol-v2';
+import { BaseMethod } from '../BaseMethod';
+import { invalidParameter } from '../helpers/filesystemValidation';
+
+export type DeviceInfoGetTargets = {
+  hw?: boolean;
+  fw?: boolean;
+  coprocessor?: boolean;
+  se1?: boolean;
+  se2?: boolean;
+  se3?: boolean;
+  se4?: boolean;
+};
+
+export type DeviceInfoGetTypes = {
+  version?: boolean;
+  build_id?: boolean;
+  hash?: boolean;
+  specific?: boolean;
+};
+
+export type DeviceInfoGetParams = {
+  targets?: DeviceInfoGetTargets;
+  types?: DeviceInfoGetTypes;
+};
+
+const TARGET_KEYS: (keyof DeviceInfoGetTargets)[] = [
+  'hw',
+  'fw',
+  'coprocessor',
+  'se1',
+  'se2',
+  'se3',
+  'se4',
+];
+
+const TYPE_KEYS: (keyof DeviceInfoGetTypes)[] = ['version', 'build_id', 'hash', 'specific'];
+
+const DEFAULT_TARGETS: DeviceInfoGetTargets = {
+  hw: true,
+  fw: true,
+  coprocessor: true,
+};
+
+const DEFAULT_TYPES: DeviceInfoGetTypes = {
+  version: true,
+  specific: true,
+};
+
+function pickBooleanKeys<T extends Record<string, boolean | undefined>>(
+  value: unknown,
+  keys: (keyof T)[]
+): T | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const source = value as Record<string, unknown>;
+  const result = {} as T;
+  let hasKey = false;
+  for (const key of keys) {
+    if (source[key as string]) {
+      result[key] = true as T[keyof T];
+      hasKey = true;
+    }
+  }
+  return hasKey ? result : undefined;
+}
+
+function assertKnownKeys(value: unknown, keys: string[], name: string) {
+  if (value == null) return;
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw invalidParameter(`Parameter [${name}] must be an object.`);
+  }
+  const allowed = new Set(keys);
+  const unknownKeys = Object.keys(value).filter(key => !allowed.has(key));
+  if (unknownKeys.length > 0) {
+    throw invalidParameter(
+      `Parameter [${name}] contains unsupported key(s): ${unknownKeys.join(', ')}.`
+    );
+  }
+}
+
+function normalizeTargets(value: unknown): DeviceInfoGetTargets | undefined {
+  assertKnownKeys(
+    value,
+    TARGET_KEYS.map(key => String(key)),
+    'targets'
+  );
+  return pickBooleanKeys<DeviceInfoGetTargets>(value, TARGET_KEYS);
+}
+
+function normalizeTypes(value: unknown): DeviceInfoGetTypes | undefined {
+  assertKnownKeys(
+    value,
+    TYPE_KEYS.map(key => String(key)),
+    'types'
+  );
+  return pickBooleanKeys<DeviceInfoGetTypes>(value, TYPE_KEYS);
+}
+
+/**
+ * Raw DeviceInfoGet command for Protocol V2 only.
+ *
+ * The SDK builds targets/types on demand and returns the raw DeviceInfo message.
+ * This command is internal; integrations should use getDeviceState.
+ */
+export default class DeviceInfoGet extends BaseMethod<{
+  targets: DeviceInfoGetTargets;
+  types: DeviceInfoGetTypes;
+}> {
+  init() {
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
+    this.requireProtocolV2 = true;
+    this.unlockPolicy = 'none';
+    this.allowDeviceMode = [
+      ...this.allowDeviceMode,
+      UI_REQUEST.NOT_INITIALIZE,
+      UI_REQUEST.BOOTLOADER,
+    ];
+    this.useDevicePassphraseState = false;
+    this.skipForceUpdateCheck = true;
+    this.params = {
+      targets: normalizeTargets(this.payload.targets) ?? DEFAULT_TARGETS,
+      types: normalizeTypes(this.payload.types) ?? DEFAULT_TYPES,
+    };
+  }
+
+  async run() {
+    if (!this.device.isProtocolV2()) {
+      throw createDeviceNotSupportMethodError(this.name, this.device.getCurrentFirmwareType());
+    }
+
+    const res = await this.device.commands.typedCall(
+      'DeviceInfoGet',
+      'DeviceInfo',
+      {
+        targets: this.params.targets,
+        types: this.params.types,
+      },
+      { timeoutMs: PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS }
+    );
+    return Promise.resolve(res.message);
+  }
+}

package/src/api/protocol-v2/DeviceReboot.ts

@@ -0,0 +1,26 @@
+import { BaseMethod } from '../BaseMethod';
+import { normalizeRebootType } from './helpers';
+
+import type { DeviceRebootParams } from './helpers';
+
+export default class DeviceReboot extends BaseMethod<DeviceRebootParams> {
+  init() {
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
+    this.requireProtocolV2 = true;
+    this.skipForceUpdateCheck = true;
+    this.useDevicePassphraseState = false;
+    this.params = {
+      rebootType: this.payload.rebootType,
+      reboot_type: this.payload.reboot_type,
+    };
+  }
+
+  async run() {
+    const rebootType = normalizeRebootType(this.params.reboot_type ?? this.params.rebootType);
+    const res = await this.device.commands.typedCall('DeviceReboot', 'Success', {
+      reboot_type: rebootType,
+    });
+    this.device.markProtocolV2Reboot(rebootType);
+    return Promise.resolve(res.message);
+  }
+}

package/src/api/protocol-v2/DeviceSessionOpen.ts

@@ -0,0 +1,102 @@
+import { assertCompleteDeviceSession } from '../../protocols/protocol-v2/deviceSession';
+import { BaseMethod } from '../BaseMethod';
+import { invalidParameter } from '../helpers/filesystemValidation';
+
+import type {
+  DeviceAttachPinOnDevice,
+  DeviceHostPassphrase,
+  DevicePassphraseOnDevice,
+  DeviceSessionResume,
+} from '@onekeyfe/hd-transport';
+
+type HiddenWalletSelection =
+  | {
+      host_passphrase: DeviceHostPassphrase;
+      passphrase_on_device?: never;
+      attach_pin_on_device?: never;
+    }
+  | {
+      host_passphrase?: never;
+      passphrase_on_device: DevicePassphraseOnDevice;
+      attach_pin_on_device?: never;
+    }
+  | {
+      host_passphrase?: never;
+      passphrase_on_device?: never;
+      attach_pin_on_device: DeviceAttachPinOnDevice;
+    };
+
+export type DeviceSessionOpenParams =
+  | { resume: DeviceSessionResume; select?: never }
+  | { resume?: never; select: HiddenWalletSelection };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === 'object' && !Array.isArray(value);
+
+const normalizeParams = (payload: Record<string, unknown>): DeviceSessionOpenParams => {
+  const hasResume = payload.resume !== undefined;
+  const hasSelect = payload.select !== undefined;
+  if (hasResume === hasSelect) {
+    throw invalidParameter('DeviceSessionOpen requires exactly one of [resume] or [select].');
+  }
+
+  if (hasResume) {
+    if (!isRecord(payload.resume) || typeof payload.resume.session_id !== 'string') {
+      throw invalidParameter('Parameter [resume.session_id] must be a non-empty string.');
+    }
+    const sessionId = payload.resume.session_id.trim();
+    if (!sessionId) {
+      throw invalidParameter('Parameter [resume.session_id] must be a non-empty string.');
+    }
+    return { resume: { session_id: sessionId } };
+  }
+
+  if (!isRecord(payload.select)) {
+    throw invalidParameter('Parameter [select] must be a hidden-wallet selection object.');
+  }
+  const { select } = payload;
+  const accessKeys = ['host_passphrase', 'passphrase_on_device', 'attach_pin_on_device'] as const;
+  const selected = accessKeys.filter(key => select[key] !== undefined);
+  const unknown = Object.keys(select).filter(
+    key => !accessKeys.includes(key as (typeof accessKeys)[number])
+  );
+  if (unknown.length > 0 || selected.length !== 1) {
+    throw invalidParameter('Parameter [select] requires exactly one hidden-wallet access mode.');
+  }
+
+  if (selected[0] === 'host_passphrase') {
+    const host = select.host_passphrase;
+    if (!isRecord(host) || typeof host.passphrase !== 'string') {
+      throw invalidParameter('Parameter [select.host_passphrase.passphrase] is required.');
+    }
+    const passphrase = host.passphrase.normalize('NFKD');
+    if (!passphrase || passphrase.includes('\0') || passphrase.length > 50) {
+      throw invalidParameter('Parameter [select.host_passphrase.passphrase] is invalid.');
+    }
+    return { select: { host_passphrase: { passphrase } } };
+  }
+
+  if (selected[0] === 'passphrase_on_device') {
+    return { select: { passphrase_on_device: {} } };
+  }
+  return { select: { attach_pin_on_device: {} } };
+};
+
+export default class DeviceSessionOpen extends BaseMethod<DeviceSessionOpenParams> {
+  init() {
+    this.requireProtocolV2 = true;
+    this.useDevicePassphraseState = false;
+    this.skipForceUpdateCheck = true;
+    this.params = normalizeParams(this.payload as unknown as Record<string, unknown>);
+  }
+
+  async run() {
+    const { message } = await this.device.commands.typedCall(
+      'DeviceSessionOpen',
+      'DeviceSession',
+      this.params
+    );
+    assertCompleteDeviceSession(message);
+    return message;
+  }
+}

package/src/api/protocol-v2/DeviceSettingsGet.ts

@@ -0,0 +1,18 @@
+import { BaseMethod } from '../BaseMethod';
+import { mapDeviceSettingsToState } from '../../device/DeviceStateMapper';
+
+export default class DeviceSettingsGet extends BaseMethod {
+  init() {
+    this.requireProtocolV2 = true;
+    this.unlockPolicy = 'none';
+    this.skipForceUpdateCheck = true;
+    this.useDevicePassphraseState = false;
+    this.params = undefined;
+  }
+
+  async run() {
+    const res = await this.device.commands.typedCall('DeviceSettingsGet', 'DeviceSettings', {});
+    this.device.updateState(mapDeviceSettingsToState(res.message), 'apply-settings');
+    return Promise.resolve(res.message);
+  }
+}

package/src/api/protocol-v2/DeviceSettingsPageShow.ts

@@ -0,0 +1,70 @@
+import { DeviceSettingsPage } from '@onekeyfe/hd-transport';
+
+import { BaseMethod } from '../BaseMethod';
+import { invalidParameter } from '../helpers/filesystemValidation';
+import { getProtocolV2SettingsBehavior } from '../../protocols/protocol-v2/settingsUnlockPolicy';
+
+export type SupportedDeviceSettingsPage = DeviceSettingsPage;
+
+export type DeviceSettingsPageShowParams = {
+  page?:
+    | SupportedDeviceSettingsPage
+    | 'DeviceReset'
+    | 'DevicePinChange'
+    | 'DevicePassphrase'
+    | 'DeviceAirgap';
+  fieldName?: string;
+  field_name?: string;
+};
+
+const SUPPORTED_PAGES = new Set<number>([
+  DeviceSettingsPage.DeviceReset,
+  DeviceSettingsPage.DevicePinChange,
+  DeviceSettingsPage.DevicePassphrase,
+  DeviceSettingsPage.DeviceAirgap,
+]);
+
+function normalizePage(value: DeviceSettingsPageShowParams['page']): SupportedDeviceSettingsPage {
+  const page = typeof value === 'string' ? DeviceSettingsPage[value] : value;
+  if (page !== undefined && SUPPORTED_PAGES.has(page)) {
+    return page;
+  }
+  throw invalidParameter(
+    'Parameter [page] must be DeviceReset, DevicePinChange, DevicePassphrase, or DeviceAirgap.'
+  );
+}
+
+export default class DeviceSettingsPageShow extends BaseMethod<{
+  page: SupportedDeviceSettingsPage;
+  field_name?: string;
+}> {
+  init() {
+    this.requireProtocolV2 = true;
+    this.skipForceUpdateCheck = true;
+    this.useDevicePassphraseState = false;
+    this.params = {
+      page: normalizePage(this.payload.page),
+      field_name: this.payload.field_name ?? this.payload.fieldName,
+    };
+    const behavior = getProtocolV2SettingsBehavior({
+      kind: 'page',
+      page: this.params.page,
+    });
+    this.unlockPolicy = behavior.unlockPolicy;
+    this.protocolV2UiInteraction = behavior.uiInteraction;
+  }
+
+  async run() {
+    const res = await this.device.commands.typedCall(
+      'DeviceSettingsPageShow',
+      'Success',
+      this.params
+    );
+    if (this.params.page === DeviceSettingsPage.DevicePassphrase) {
+      await this.device.getDeviceState({ refreshSections: ['status'] });
+    } else if (this.params.page === DeviceSettingsPage.DeviceAirgap) {
+      await this.device.getDeviceState({ refreshSections: ['settings'] });
+    }
+    return Promise.resolve(res.message);
+  }
+}

package/src/api/protocol-v2/DeviceSettingsSet.ts

@@ -0,0 +1,44 @@
+import { BaseMethod } from '../BaseMethod';
+import { mapDeviceSettingsToState } from '../../device/DeviceStateMapper';
+import { getProtocolV2SettingsBehavior } from '../../protocols/protocol-v2/settingsUnlockPolicy';
+import { invalidParameter } from '../helpers/filesystemValidation';
+
+import type { DeviceSettings } from '@onekeyfe/hd-transport';
+
+export type DeviceSettingsSetParams = {
+  settings?: Omit<DeviceSettings, 'passphrase_enable' | 'airgap_mode'>;
+};
+
+export default class DeviceSettingsSet extends BaseMethod<{
+  settings: Omit<DeviceSettings, 'passphrase_enable' | 'airgap_mode'>;
+}> {
+  init() {
+    const { settings } = this.payload;
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+      throw invalidParameter('Parameter [settings] must be an object.');
+    }
+
+    const {
+      passphrase_enable: _passphraseEnable,
+      airgap_mode: _airgapMode,
+      ...supported
+    } = settings as DeviceSettings;
+    if (Object.keys(supported).length === 0) {
+      throw invalidParameter('Parameter [settings] must contain at least one supported setting.');
+    }
+
+    this.requireProtocolV2 = true;
+    const behavior = getProtocolV2SettingsBehavior({ kind: 'direct', settings: supported });
+    this.unlockPolicy = behavior.unlockPolicy;
+    this.skipForceUpdateCheck = true;
+    this.useDevicePassphraseState = false;
+    this.params = { settings: supported };
+    this.protocolV2UiInteraction = behavior.uiInteraction;
+  }
+
+  async run() {
+    const res = await this.device.commands.typedCall('DeviceSettingsSet', 'Success', this.params);
+    this.device.updateState(mapDeviceSettingsToState(this.params.settings), 'apply-settings');
+    return Promise.resolve(res.message);
+  }
+}

package/src/api/protocol-v2/DeviceStatusGet.ts

@@ -0,0 +1,16 @@
+import { BaseMethod } from '../BaseMethod';
+
+export default class DeviceStatusGet extends BaseMethod {
+  init() {
+    this.requireProtocolV2 = true;
+    this.unlockPolicy = 'none';
+    this.useDevicePassphraseState = false;
+    this.skipForceUpdateCheck = true;
+  }
+
+  async run() {
+    const { message } = await this.device.commands.typedCall('DeviceStatusGet', 'DeviceStatus', {});
+    this.device.updateProtocolV2Status(message);
+    return message;
+  }
+}

package/src/api/protocol-v2/DeviceUploadWallpaper.ts

@@ -0,0 +1,131 @@
+import { blake2s } from '@noble/hashes/blake2s';
+import { bytesToHex } from '@noble/hashes/utils';
+
+import { BaseMethod } from '../BaseMethod';
+import { invalidParameter } from '../helpers/filesystemValidation';
+import { writeProtocolV2File } from '../helpers/protocolV2FileWrite';
+import { UI_REQUEST, createUiMessage } from '../../events/ui-request';
+import {
+  PRO2_WALLPAPER_HEIGHT,
+  PRO2_WALLPAPER_WIDTH,
+  type Pro2WallpaperColorFormat,
+  encodePro2Wallpaper,
+} from '../../utils/pro2Wallpaper';
+
+export type DeviceUploadWallpaperParams = {
+  width: number;
+  height: number;
+  rgba: Uint8Array | ArrayBuffer;
+  fileName?: string;
+  chunkSize?: number;
+};
+
+export type DeviceUploadWallpaperResponse = {
+  path: string;
+  size: number;
+  colorFormat: Pro2WallpaperColorFormat;
+  message?: string;
+};
+
+const WALLPAPER_DIRECTORY = 'vol1:/wallpapers';
+const SAFE_FILE_NAME = /^[A-Za-z0-9_-]+(?:\.bin)?$/;
+
+function normalizeFileName(fileName: string | undefined, data: Uint8Array): string {
+  if (fileName !== undefined && (!fileName || !SAFE_FILE_NAME.test(fileName))) {
+    throw invalidParameter(
+      'Parameter [fileName] may only contain letters, numbers, underscores, hyphens and an optional .bin suffix.'
+    );
+  }
+  const baseName = fileName ?? `wallpaper-${bytesToHex(blake2s(data)).slice(0, 12)}`;
+  return baseName.endsWith('.bin') ? baseName : `${baseName}.bin`;
+}
+
+export default class DeviceUploadWallpaper extends BaseMethod<DeviceUploadWallpaperParams> {
+  private encoded?: { data: Uint8Array; colorFormat: Pro2WallpaperColorFormat };
+
+  private directoryReady = false;
+
+  private uploaded = false;
+
+  private path = '';
+
+  init() {
+    const { width, height, rgba, fileName, chunkSize } = this.payload;
+    if (width !== PRO2_WALLPAPER_WIDTH || height !== PRO2_WALLPAPER_HEIGHT) {
+      throw invalidParameter(
+        `Pro2 wallpaper dimensions must be ${PRO2_WALLPAPER_WIDTH}x${PRO2_WALLPAPER_HEIGHT}.`
+      );
+    }
+    if (!(rgba instanceof ArrayBuffer) && !ArrayBuffer.isView(rgba)) {
+      throw invalidParameter('Parameter [rgba] must be an ArrayBuffer or Uint8Array.');
+    }
+    if (chunkSize !== undefined && (!Number.isInteger(chunkSize) || chunkSize <= 0)) {
+      throw invalidParameter('Parameter [chunkSize] must be a positive integer.');
+    }
+
+    const rgbaBytes =
+      rgba instanceof ArrayBuffer
+        ? rgba
+        : new Uint8Array(rgba.buffer, rgba.byteOffset, rgba.byteLength);
+    this.encoded = encodePro2Wallpaper({ width, height, rgba: rgbaBytes });
+    this.path = `${WALLPAPER_DIRECTORY}/${normalizeFileName(fileName, this.encoded.data)}`;
+    this.params = { width, height, rgba: rgbaBytes, fileName, chunkSize };
+    this.requireProtocolV2 = true;
+    this.unlockPolicy = 'retry-on-locked';
+    this.skipForceUpdateCheck = true;
+    this.useDevicePassphraseState = false;
+  }
+
+  private async ensureDirectory() {
+    if (this.directoryReady) return;
+    try {
+      await this.device.commands.typedCall('FilesystemDirMake', 'Success', {
+        path: WALLPAPER_DIRECTORY,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (!/exist/i.test(message)) throw error;
+    }
+    this.directoryReady = true;
+  }
+
+  private async upload() {
+    if (this.uploaded) return;
+    const { encoded } = this;
+    if (!encoded) throw invalidParameter('Wallpaper data has not been initialized.');
+
+    await writeProtocolV2File({
+      commands: this.device.commands,
+      path: this.path,
+      data: encoded.data,
+      totalSize: encoded.data.byteLength,
+      chunkSize: this.params.chunkSize,
+      maxChunkRetries: 3,
+      overwrite: true,
+      append: false,
+      throwIfAborted: () => this.throwIfAborted(),
+      onProgress: payload => {
+        if (typeof this.postMessage === 'function') {
+          this.postMessage(createUiMessage(UI_REQUEST.DEVICE_PROGRESS, payload));
+        }
+      },
+    });
+    this.uploaded = true;
+  }
+
+  async run(): Promise<DeviceUploadWallpaperResponse> {
+    const { encoded } = this;
+    if (!encoded) throw invalidParameter('Wallpaper data has not been initialized.');
+    await this.ensureDirectory();
+    await this.upload();
+    const response = await this.device.commands.typedCall('DeviceSettingsSet', 'Success', {
+      settings: { wallpaper_path: this.path },
+    });
+    return {
+      path: this.path,
+      size: encoded.data.byteLength,
+      colorFormat: encoded.colorFormat,
+      message: response.message?.message,
+    };
+  }
+}

package/src/api/protocol-v2/FilesystemFormat.ts

@@ -0,0 +1,19 @@
+import { BaseMethod } from '../BaseMethod';
+
+export default class FilesystemFormat extends BaseMethod {
+  init() {
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
+    this.requireProtocolV2 = true;
+    this.skipForceUpdateCheck = true;
+    this.useDevicePassphraseState = false;
+    this.params = undefined;
+  }
+
+  async run() {
+    const res = await this.device.commands.typedCall('FilesystemFormat', 'Success', {
+      data: true,
+      user: true,
+    });
+    return Promise.resolve(res.message);
+  }
+}

package/src/api/protocol-v2/FilesystemPermissionFix.ts

@@ -0,0 +1,16 @@
+import { BaseMethod } from '../BaseMethod';
+
+export default class FilesystemPermissionFix extends BaseMethod {
+  init() {
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
+    this.requireProtocolV2 = true;
+    this.skipForceUpdateCheck = true;
+    this.useDevicePassphraseState = false;
+    this.params = undefined;
+  }
+
+  async run() {
+    const res = await this.device.commands.typedCall('FilesystemPermissionFix', 'Success', {});
+    return Promise.resolve(res.message);
+  }
+}

package/src/api/protocol-v2/Ping.ts

@@ -0,0 +1,18 @@
+import { BaseMethod } from '../BaseMethod';
+
+export default class Ping extends BaseMethod<{ message?: string }> {
+  init() {
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
+    this.requireProtocolV2 = true;
+    this.skipForceUpdateCheck = true;
+    this.useDevicePassphraseState = false;
+    this.params = { message: this.payload.message };
+  }
+
+  async run() {
+    const res = await this.device.commands.typedCall('Ping', 'Success', {
+      message: this.params.message ?? '',
+    });
+    return Promise.resolve(res.message);
+  }
+}

package/src/api/protocol-v2/ProtocolInfoRequest.ts

@@ -0,0 +1,16 @@
+import { BaseMethod } from '../BaseMethod';
+
+export default class ProtocolInfoRequest extends BaseMethod {
+  init() {
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
+    this.requireProtocolV2 = true;
+    this.skipForceUpdateCheck = true;
+    this.useDevicePassphraseState = false;
+    this.params = undefined;
+  }
+
+  async run() {
+    const res = await this.device.commands.typedCall('ProtocolInfoRequest', 'ProtocolInfo', {});
+    return Promise.resolve(res.message);
+  }
+}