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

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

@@ -0,0 +1,424 @@
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+import { DeviceSessionPinType, DeviceSessionSeedDomain } from '@onekeyfe/hd-transport';
+
+import { DEVICE } from '../../events';
+import { assertCompleteDeviceSession } from './deviceSession';
+
+import type { DeviceSessionAskPassphrase, DeviceSessionGet } from '@onekeyfe/hd-transport';
+import type { Device } from '../../device/Device';
+
+const HOST_PASSPHRASE_MAX_BYTES = 50;
+
+const isWalletSessionInvalidError = (error: unknown) =>
+  typeof error === 'object' &&
+  error !== null &&
+  'errorCode' in error &&
+  (error as { errorCode?: unknown }).errorCode === HardwareErrorCode.WalletSessionInvalid;
+
+const utf8ByteLength = (value: string): number | undefined => {
+  let length = 0;
+  for (const character of value) {
+    const codePoint = character.codePointAt(0) ?? 0;
+    if (codePoint >= 0xd800 && codePoint <= 0xdfff) return undefined;
+    if (codePoint <= 0x7f) length += 1;
+    else if (codePoint <= 0x7ff) length += 2;
+    else if (codePoint <= 0xffff) length += 3;
+    else length += 4;
+  }
+  return length;
+};
+
+export async function requestProtocolV2DeviceStatus(device: Device) {
+  const { message } = await device.commands.typedCall('DeviceStatusGet', 'DeviceStatus', {});
+  return message;
+}
+
+export async function refreshProtocolV2DeviceStatus(device: Device) {
+  const status = await requestProtocolV2DeviceStatus(device);
+  return device.updateProtocolV2Status(status);
+}
+
+export async function ensureProtocolV2WalletSessionUnlocked(device: Device) {
+  if (!device.isProtocolV2() || device.isBootloader?.() || device.isRomloader?.()) {
+    return false;
+  }
+
+  await refreshProtocolV2DeviceStatus(device);
+  if (device.state?.status.unlocked !== false) {
+    return false;
+  }
+
+  await device.unlockDevice(DeviceSessionPinType.Main, {
+    source: 'unlock-coordinator',
+    reason: 'device-locked',
+    deviceOnly: true,
+  });
+  return true;
+}
+
+const negotiateEventlessWalletSession = async (device: Device) => {
+  await device.ensureProtocolV2RuntimeContext();
+};
+
+const getDeviceSession = async (device: Device, request: DeviceSessionGet) =>
+  device.commands.typedCall('DeviceSessionGet', 'DeviceSession', request);
+
+const buildDeviceSessionGetRequest = ({
+  sessionId,
+  expectedPassphraseState,
+  deriveCardano,
+}: {
+  sessionId?: string;
+  expectedPassphraseState?: string;
+  deriveCardano?: boolean;
+} = {}): DeviceSessionGet => ({
+  ...(sessionId ? { session_id: sessionId } : {}),
+  ...(expectedPassphraseState ? { btc_test_address: expectedPassphraseState } : {}),
+  seed_domains:
+    deriveCardano === undefined
+      ? []
+      : [
+          DeviceSessionSeedDomain.SeedDomain_Standard,
+          ...(deriveCardano ? [DeviceSessionSeedDomain.SeedDomain_Cardano] : []),
+        ],
+});
+
+const askDevicePassphrase = async (device: Device, requestPayload: DeviceSessionAskPassphrase) => {
+  await device.commands.typedCall('DeviceSessionAskPassphrase', 'Success', requestPayload);
+  await refreshProtocolV2DeviceStatus(device);
+};
+
+const selectDeviceSession = async (
+  device: Device,
+  expectedPassphraseState?: string,
+  deriveCardano?: boolean
+) => {
+  const existsAttachPinUser = device.features?.attachToPinEnabled === true;
+  const metadata = {
+    source: 'wallet-session-coordinator' as const,
+    reason: expectedPassphraseState ? ('session-recovery' as const) : ('open-wallet' as const),
+    ...(expectedPassphraseState ? { expectedPassphraseState } : {}),
+  };
+  const passphraseInteraction = device.createProtocolV2UiPhaseMetadata?.('passphrase', 'start');
+  const response = await device.commands.promptPassphrase(
+    {
+      existsAttachPinUser,
+      deviceOnly: false,
+      ...metadata,
+      ...(passphraseInteraction ? { interaction: passphraseInteraction } : {}),
+    },
+    { cancelDeviceOnReject: false }
+  );
+  const hostPassphrase =
+    typeof response.passphrase === 'string' ? response.passphrase.normalize('NFKD') : undefined;
+  const hasHostPassphrase = typeof hostPassphrase === 'string' && hostPassphrase.length > 0;
+  const hostPassphraseByteLength = hasHostPassphrase ? utf8ByteLength(hostPassphrase) : undefined;
+  if (
+    hasHostPassphrase &&
+    (hostPassphrase.includes('\0') ||
+      hostPassphraseByteLength === undefined ||
+      hostPassphraseByteLength > HOST_PASSPHRASE_MAX_BYTES)
+  ) {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      `Host passphrase must contain 1 to ${HOST_PASSPHRASE_MAX_BYTES} valid UTF-8 bytes without NUL.`
+    );
+  }
+  const selections = [
+    hasHostPassphrase,
+    response.passphraseOnDevice === true,
+    response.attachPinOnDevice === true,
+  ].filter(Boolean).length;
+
+  if (selections !== 1) {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      'Wallet selection must contain exactly one passphrase access mode.'
+    );
+  }
+
+  if (response.attachPinOnDevice) {
+    if (!existsAttachPinUser) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.RuntimeError,
+        'Attach PIN wallet selection is unavailable on this device.'
+      );
+    }
+    const attachPinInteraction = device.createProtocolV2UiPhaseMetadata?.('pin', 'start');
+    device.emit(DEVICE.ATTACH_PIN_ON_DEVICE, device, {
+      ...metadata,
+      ...(attachPinInteraction ? { interaction: attachPinInteraction } : {}),
+    });
+    await device.unlockDevice(DeviceSessionPinType.AttachToPin, {
+      emitUiEvent: false,
+      interaction: attachPinInteraction,
+    });
+    return getDeviceSession(device, buildDeviceSessionGetRequest({ deriveCardano }));
+  }
+
+  if (hasHostPassphrase) {
+    await askDevicePassphrase(device, {
+      passphrase: hostPassphrase,
+      on_device: false,
+    });
+    return getDeviceSession(device, buildDeviceSessionGetRequest({ deriveCardano }));
+  }
+
+  const passphraseOnDeviceInteraction = device.createProtocolV2UiPhaseMetadata?.(
+    'passphrase-on-device',
+    'start'
+  );
+  device.emit(DEVICE.PASSPHRASE_ON_DEVICE, device, {
+    ...metadata,
+    ...(passphraseOnDeviceInteraction ? { interaction: passphraseOnDeviceInteraction } : {}),
+  });
+  await askDevicePassphrase(device, { on_device: true });
+  return getDeviceSession(device, buildDeviceSessionGetRequest({ deriveCardano }));
+};
+
+export async function getProtocolV2WalletSession(
+  device: Device,
+  options?: {
+    forceWalletSelection?: boolean;
+    /** @deprecated 兼容旧 getPassphraseState；新流程使用 forceWalletSelection。 */
+    initSession?: boolean;
+    expectedPassphraseState?: string;
+    onlyMainPin?: boolean;
+    selectMainWalletBeforeRestore?: boolean;
+    resumeOnly?: boolean;
+    deriveCardano?: boolean;
+  }
+) {
+  const forceWalletSelection =
+    options?.forceWalletSelection === true || options?.initSession === true;
+
+  if (forceWalletSelection) {
+    if (options.onlyMainPin) {
+      device.clearStandardInternalState?.();
+    } else {
+      device.clearInternalState();
+    }
+    device.passphraseState = undefined;
+  }
+
+  await negotiateEventlessWalletSession(device);
+
+  if (options?.onlyMainPin) {
+    device.passphraseState = undefined;
+  }
+  let expectedPassphraseState = options?.onlyMainPin
+    ? undefined
+    : options?.expectedPassphraseState ?? device.passphraseState;
+
+  const cachedStandardSession = options?.onlyMainPin
+    ? device.getStandardInternalState?.()
+    : undefined;
+  const cachedSessionId =
+    !options?.onlyMainPin && typeof device.getInternalState === 'function'
+      ? device.getInternalState()
+      : undefined;
+  let response;
+  let resumed = false;
+  let mainPinSelected =
+    options?.onlyMainPin === true &&
+    device.features?.unlocked === true &&
+    device.features?.unlockedAttachPin === false;
+
+  const clearCurrentWalletSession = () => {
+    if (options?.onlyMainPin) {
+      device.clearStandardInternalState?.();
+    } else {
+      device.clearInternalState();
+    }
+  };
+
+  const rejectMismatchedAttachPinWallet = async () => {
+    const features = await refreshProtocolV2DeviceStatus(device);
+    if (features.unlockedAttachPin !== true) {
+      return;
+    }
+
+    try {
+      await device.lockDevice();
+    } catch {
+      // Reject the mismatched Attach PIN wallet even when older firmware cannot lock.
+    }
+    clearCurrentWalletSession();
+    throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckUnlockTypeError);
+  };
+
+  const selectMainPin = async (force = false) => {
+    if (force || !mainPinSelected) {
+      await device.unlockDevice(DeviceSessionPinType.Main, {
+        source: 'wallet-session-coordinator',
+        reason: expectedPassphraseState ? 'session-recovery' : 'open-wallet',
+        deviceOnly: true,
+      });
+      mainPinSelected = true;
+    }
+  };
+
+  const selectStandardWallet = async () => {
+    // Main PIN authenticates the device; an empty host passphrase selects the standard derivation.
+    await selectMainPin();
+    if (device.features?.passphraseProtection === true) {
+      await askDevicePassphrase(device, {
+        passphrase: '',
+        on_device: false,
+      });
+    }
+  };
+
+  if (options?.onlyMainPin) {
+    expectedPassphraseState = cachedStandardSession?.passphraseState;
+    if (cachedStandardSession) {
+      try {
+        if (options?.selectMainWalletBeforeRestore) {
+          await selectMainPin();
+        }
+        response = await getDeviceSession(
+          device,
+          buildDeviceSessionGetRequest({
+            sessionId: cachedStandardSession.sessionId,
+            expectedPassphraseState,
+            deriveCardano: options?.deriveCardano,
+          })
+        );
+        resumed = true;
+      } catch (error) {
+        device.clearStandardInternalState?.();
+        if (!isWalletSessionInvalidError(error)) {
+          throw error;
+        }
+        resumed = false;
+      }
+    }
+
+    if (!response) {
+      await selectStandardWallet();
+      response = await getDeviceSession(
+        device,
+        buildDeviceSessionGetRequest({ deriveCardano: options?.deriveCardano })
+      );
+    }
+  } else if (cachedSessionId && expectedPassphraseState) {
+    try {
+      response = await getDeviceSession(
+        device,
+        buildDeviceSessionGetRequest({
+          sessionId: cachedSessionId,
+          expectedPassphraseState,
+          deriveCardano: options?.deriveCardano,
+        })
+      );
+      resumed = true;
+    } catch (error) {
+      device.clearInternalState();
+      if (options?.resumeOnly || !isWalletSessionInvalidError(error)) {
+        throw error;
+      }
+      resumed = false;
+    }
+  } else if (expectedPassphraseState) {
+    try {
+      response = await getDeviceSession(
+        device,
+        buildDeviceSessionGetRequest({
+          expectedPassphraseState,
+          deriveCardano: options?.deriveCardano,
+        })
+      );
+    } catch (error) {
+      if (options?.resumeOnly || !isWalletSessionInvalidError(error)) {
+        throw error;
+      }
+    }
+  }
+
+  if (!response) {
+    if (options?.resumeOnly) {
+      device.clearInternalState();
+      throw ERRORS.TypedError(HardwareErrorCode.WalletSessionInvalid);
+    }
+    response = await selectDeviceSession(device, expectedPassphraseState, options?.deriveCardano);
+  }
+
+  let { message } = response;
+  try {
+    assertCompleteDeviceSession(message);
+  } catch (error) {
+    if (options?.onlyMainPin) {
+      device.clearStandardInternalState?.();
+    } else {
+      device.clearInternalState();
+    }
+    throw error;
+  }
+  if (expectedPassphraseState && expectedPassphraseState !== message.btc_test_address) {
+    resumed = false;
+    await rejectMismatchedAttachPinWallet();
+    if (options?.resumeOnly) {
+      device.clearInternalState();
+      throw ERRORS.TypedError(HardwareErrorCode.WalletSessionInvalid);
+    }
+    if (options?.onlyMainPin) {
+      device.clearStandardInternalState?.();
+      await selectStandardWallet();
+      response = await getDeviceSession(
+        device,
+        buildDeviceSessionGetRequest({ deriveCardano: options?.deriveCardano })
+      );
+    } else {
+      device.clearInternalState();
+      response = await selectDeviceSession(device, expectedPassphraseState, options?.deriveCardano);
+    }
+    message = response.message;
+    try {
+      assertCompleteDeviceSession(message);
+    } catch (error) {
+      if (options?.onlyMainPin) {
+        device.clearStandardInternalState?.();
+      } else {
+        device.clearInternalState();
+      }
+      throw error;
+    }
+    if (expectedPassphraseState !== message.btc_test_address) {
+      await rejectMismatchedAttachPinWallet();
+      clearCurrentWalletSession();
+      throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckPassphraseStateError);
+    }
+  }
+
+  const internalStateArgs = [
+    true,
+    message.btc_test_address,
+    device.getCurrentDeviceId(),
+    message.session_id,
+    forceWalletSelection ? null : cachedSessionId ?? null,
+  ] as const;
+  if (options?.onlyMainPin) {
+    device.updateInternalState(...internalStateArgs, 'standard');
+  } else {
+    device.updateInternalState(...internalStateArgs);
+  }
+
+  return {
+    passphraseState: message.btc_test_address,
+    newSession: message.session_id,
+    unlockedAttachPin: mainPinSelected ? false : undefined,
+    resumed,
+  };
+}
+
+export async function restoreProtocolV2WalletSession(
+  device: Device,
+  expectedPassphraseState: string,
+  deriveCardano?: boolean
+) {
+  return getProtocolV2WalletSession(device, {
+    expectedPassphraseState,
+    resumeOnly: true,
+    deriveCardano,
+  });
+}

package/src/topLevelInject.ts

@@ -1,6 +1,6 @@
 import EventEmitter from 'events';
 
-import { createCoreApi } from './inject';
+import { createCoreApi, createProtocolAwareCall } from './inject';
 
 import type { ConnectSettings } from './types/settings';
 import type { CoreApi } from './types/api';
@@ -19,6 +19,7 @@ export const topLevelInject = () => {
     if (!lowLevelApi) return Promise.resolve(undefined);
     return lowLevelApi.call(params);
   };
+  const protocolAwareCall = createProtocolAwareCall(call);
   const api: CoreApi = {
     on: <T extends string, P extends (...args: any[]) => any>(type: T, fn: P) => {
       eventEmitter.on(type, fn);
@@ -37,9 +38,11 @@ export const topLevelInject = () => {
       return lowLevelApi?.init(settings) ?? Promise.resolve(false);
     },
 
-    call,
+    call: protocolAwareCall.call,
 
-    ...createCoreApi(call),
+    setDeviceConnectProtocol: protocolAwareCall.setDeviceConnectProtocol,
+
+    ...createCoreApi(protocolAwareCall.call),
 
     removeAllListeners: type => {
       eventEmitter.removeAllListeners(type);

package/src/types/api/checkAllFirmwareRelease.ts

@@ -1,8 +1,17 @@
-import type { IBLEFirmwareReleaseInfo } from '../settings';
 import type { EFirmwareType } from '@onekeyfe/hd-shared';
-import type { Features } from '@onekeyfe/hd-transport';
 import type { CommonParams, Response } from '../params';
-import type { IDeviceBLEFirmwareStatus, IDeviceFirmwareStatus } from '../device';
+import type {
+  DeviceStateVersions,
+  Features,
+  IDeviceBLEFirmwareStatus,
+  IDeviceFirmwareStatus,
+} from '../device';
+import type {
+  IBLEFirmwareReleaseInfo,
+  IFirmwareReleaseInfo,
+  IProtocolV2FirmwareComponentTarget,
+} from '../settings';
+import type { FirmwareUpdateV4Target } from './firmwareUpdate';
 
 export type FirmwareRelease = {
   shouldUpdate?: boolean;
@@ -11,16 +20,50 @@ export type FirmwareRelease = {
     'zh-CN': string;
     'en-US': string;
   }[];
-  release: IDeviceBLEFirmwareStatus | IBLEFirmwareReleaseInfo;
+  release: IDeviceBLEFirmwareStatus | IBLEFirmwareReleaseInfo | IFirmwareReleaseInfo;
   bootloaderMode?: boolean;
 };
 
+export type ProtocolV2FirmwareComponentReleaseStatus =
+  | 'valid'
+  | 'outdated'
+  | 'unknown'
+  | 'unsupported';
+
+export type ProtocolV2FirmwareReleaseStatus =
+  | 'unavailable'
+  | 'valid'
+  | 'unknown'
+  | 'outdated'
+  | 'required';
+
+export type ProtocolV2FirmwareComponentRelease = {
+  configKey: string;
+  componentTarget: IProtocolV2FirmwareComponentTarget;
+  updateTarget: FirmwareUpdateV4Target | null;
+  currentVersion: string | null;
+  targetVersion: string | null;
+  status: ProtocolV2FirmwareComponentReleaseStatus;
+  required: boolean;
+};
+
 export type AllFirmwareRelease = {
   firmware: FirmwareRelease;
   ble: FirmwareRelease;
   bootloader?: FirmwareRelease;
   bridge?: FirmwareRelease;
   features?: Features;
+  protocol?: 'V1' | 'V2';
+  deviceType?: 'pro2';
+  firmwareType?: EFirmwareType;
+  status?: ProtocolV2FirmwareReleaseStatus;
+  hasUpgrade?: boolean;
+  required?: boolean;
+  resourceStatus?: 'valid' | 'outdated' | 'unknown';
+  currentVersions?: DeviceStateVersions;
+  components?: ProtocolV2FirmwareComponentRelease[];
+  targetsToUpdate?: FirmwareUpdateV4Target[];
+  release?: IFirmwareReleaseInfo;
 };
 
 export type CheckAllFirmwareReleaseParams = {

package/src/types/api/detectDeviceConnectProtocol.ts

@@ -0,0 +1,7 @@
+import type { HardwareConnectProtocol } from '@onekeyfe/hd-shared';
+
+import type { Response } from '../params';
+
+export declare function detectDeviceConnectProtocol(
+  connectId: string
+): Response<HardwareConnectProtocol>;

package/src/types/api/deviceSettings.ts

@@ -1,20 +1,44 @@
-import type { SafetyCheckLevel, Success } from '@onekeyfe/hd-transport';
+import type { Enum_SafetyCheckLevel, Success } from '@onekeyfe/hd-transport';
 import type { CommonParams, Response } from '../params';
 
 export type DeviceSettingsParams = {
   language?: string;
   label?: string;
   usePassphrase?: boolean;
+  /** Protocol V1 only. */
   homescreen?: string;
+  /** Protocol V1 only. */
   passphraseSource?: number;
   autoLockDelayMs?: number;
+  /** Protocol V1 only. */
   displayRotation?: number;
+  /** Protocol V1 only. */
   passphraseAlwaysOnDevice?: boolean;
-  safetyChecks?: SafetyCheckLevel;
+  /** Protocol V1 only. Uses Enum_SafetyCheckLevel numeric values. */
+  safetyChecks?: Enum_SafetyCheckLevel;
+  /** Protocol V1 only; the current Protocol V2 schema has no matching field. */
   experimentalFeatures?: boolean;
   autoShutdownDelayMs?: number;
+  /** Protocol V1 only; opens the legacy device-side brightness flow. */
   changeBrightness?: boolean;
+  /** Protocol V2 only. */
+  brightness?: number;
   hapticFeedback?: boolean;
+  bluetoothEnabled?: boolean;
+  /** Protocol V2 only; changed through an on-device confirmation page. */
+  airgapMode?: boolean;
+  /** Protocol V2 only. */
+  animationEnabled?: boolean;
+  /** Protocol V2 only. */
+  tapToWake?: boolean;
+  /** Protocol V2 only. */
+  deviceNameDisplayEnabled?: boolean;
+  /** Protocol V2 only. */
+  fidoEnabled?: boolean;
+  /** Protocol V2 only. */
+  usbLockEnabled?: boolean;
+  /** Protocol V2 only. */
+  randomKeypad?: boolean;
 };
 
 export declare function deviceSettings(

package/src/types/api/deviceUnlock.ts

@@ -1,4 +1,4 @@
-import type { Features } from '@onekeyfe/hd-transport';
+import type { Features } from '../device';
 import type { CommonParams, Response } from '../params';
 
 export declare function deviceUnlock(connectId: string, params?: CommonParams): Response<Features>;

package/src/types/api/export.ts

@@ -29,8 +29,14 @@ export type {
   FirmwareUpdateBinaryParams,
   FirmwareUpdateV3Params,
   FirmwareUpdateV4Params,
+  FirmwareUpdateV4Target,
 } from './firmwareUpdate';
 export type { AllFirmwareRelease } from './checkAllFirmwareRelease';
+export type {
+  ProtocolV2FirmwareComponentRelease,
+  ProtocolV2FirmwareComponentReleaseStatus,
+  ProtocolV2FirmwareReleaseStatus,
+} from './checkAllFirmwareRelease';
 
 export type { AllNetworkAddressParams, AllNetworkGetAddressParams } from './allNetworkGetAddress';
 
@@ -161,6 +167,8 @@ export type {
   KaspaSignTransactionParams,
   KaspaSignInputParams,
   KaspaSignOutputParams,
+  KaspaStreamingSignInputParams,
+  KaspaStreamingSignOutputParams,
 } from './kaspaSignTransaction';
 
 export type { NexaAddress, NexaGetAddressParams } from './nexaGetAddress';

package/src/types/api/firmwareUpdate.ts

@@ -58,18 +58,33 @@ export interface FirmwareUpdateV3Params {
 }
 
 /**
- * firmwareUpdateV4（Protocol V2）按 DeviceFirmwareTargetType 拆分的目标二进制。
- * 除 romloader 外，每个字段对应一个 bootloader 可接受的固件升级 target。
+ * firmwareUpdateV4 target binaries grouped by DeviceFirmwareTargetType.
+ * Except for romloader, each field maps to a target accepted by bootloader.
  */
+export type FirmwareUpdateV4Target =
+  | 'boot'
+  | 'boot_resources'
+  | 'app_v1'
+  | 'app_v2'
+  | 'coprocessor'
+  | 'resource'
+  | 'se01'
+  | 'se02'
+  | 'se03'
+  | 'se04';
+
 export interface FirmwareUpdateV4Params {
   platform: IPlatform;
   chunkSize?: number;
   firmwareType?: EFirmwareType;
+  targetsToUpdate?: FirmwareUpdateV4Target[];
 
-  /** FW_MGMT_TARGET_ROMLOADER = 2；当前 Pro2 bootloader 不接受通过 firmwareUpdateV4 安装 */
+  /** FW_MGMT_TARGET_ROMLOADER = 2; Pro2 cannot install it through firmwareUpdateV4. */
   romloaderBinary?: ArrayBuffer;
   /** FW_MGMT_TARGET_BOOTLOADER = 3 */
   bootloaderBinary?: ArrayBuffer;
+  /** FW_MGMT_TARGET_CRATE = 1; optional Pro2 startup resources. */
+  bootResourcesBinary?: ArrayBuffer;
   /** FW_MGMT_TARGET_APPLICATION_P1 = 4 */
   applicationP1Binary?: ArrayBuffer;
   /** FW_MGMT_TARGET_APPLICATION_P2 = 5 */
@@ -81,9 +96,15 @@ export interface FirmwareUpdateV4Params {
   se02Binary?: ArrayBuffer;
   se03Binary?: ArrayBuffer;
   se04Binary?: ArrayBuffer;
-  /** 资源包通过 FW_MGMT_TARGET_CRATE = 1 安装；每个元素是一个独立资源包 */
-  resourceBinaries?: ArrayBuffer[];
   forcedUpdateRes?: boolean;
+  /**
+   * RESC bundle okpkg files written directly to devicePath through FilesystemFileWrite.
+   * Manual mode installs them without version comparison.
+   */
+  resourceBundleFiles?: Array<{
+    binary: ArrayBuffer;
+    devicePath: string;
+  }>;
 }
 
 export declare function firmwareUpdateV3(

package/src/types/api/getDeviceState.ts

@@ -0,0 +1,19 @@
+import type { DeviceState, DeviceStateSection } from '../device';
+import type { CommonParams, Response } from '../params';
+
+export type DeviceStateScope = 'runtime' | 'settings' | 'firmware';
+
+export type GetDeviceStateParams = CommonParams & {
+  scope?: DeviceStateScope;
+};
+
+/** Internal state-read options, not part of the public CoreApi. */
+export type DeviceStateReadOptions = {
+  refreshSections?: DeviceStateSection[];
+  includeRaw?: boolean;
+};
+
+export declare function getDeviceState(
+  connectId?: string,
+  params?: GetDeviceStateParams
+): Response<DeviceState>;

package/src/types/api/getFeatures.ts

@@ -1,4 +1,7 @@
 import type { CommonParams, Response } from '../params';
 import type { Features } from '../device';
 
+/**
+ * @deprecated Use `getDeviceState` for both Protocol V1 and Protocol V2 devices.
+ */
 export declare function getFeatures(connectId?: string, params?: CommonParams): Response<Features>;