@onekeyfe/hd-core 1.2.0-alpha.2 → 1.2.0-alpha.21

package/src/device/DeviceStateMapper.ts

@@ -0,0 +1,349 @@
+import { EDeviceType, EFirmwareType } from '@onekeyfe/hd-shared';
+
+import { buildProtocolV1FeaturesPayload } from '../deviceProfile/buildDeviceFeatures';
+import {
+  mapLanguageFromProtocolV2,
+  mapLanguageToProtocolV2,
+  normalizeSafetyCheckLevel,
+} from '../utils/deviceSettings';
+
+import type {
+  ApplySettings,
+  DeviceFirmwareImageInfo,
+  DeviceSettings,
+  DeviceStatus,
+  ProtocolV2DeviceInfo,
+} from '@onekeyfe/hd-transport';
+import type { PROTO } from '../constants';
+import type {
+  DeviceFeaturesVerify,
+  DeviceStateMode,
+  DeviceStatePatch,
+  Features,
+  OnekeyFeatures,
+} from '../types';
+import type { DeviceSettingsParams } from '../types/api/deviceSettings';
+
+const definedEntries = <T extends Record<string, unknown>>(value: T): T =>
+  Object.fromEntries(
+    Object.entries(value).filter(([, fieldValue]) => fieldValue !== undefined)
+  ) as T;
+
+const imageVersion = (image?: DeviceFirmwareImageInfo | null) => image?.version ?? undefined;
+
+const bytesToHex = (value: unknown): string | undefined => {
+  if (!value) return undefined;
+  if (typeof value === 'string') return value;
+  if (value instanceof Uint8Array || Array.isArray(value)) {
+    return Array.from(value)
+      .map(byte => Number(byte).toString(16).padStart(2, '0'))
+      .join('');
+  }
+  return undefined;
+};
+
+const imageBuildId = (image?: DeviceFirmwareImageInfo | null) => image?.build_id ?? undefined;
+const imageHash = (image?: DeviceFirmwareImageInfo | null) => bytesToHex(image?.hash);
+
+const getFeaturesMode = (features: Features): DeviceStateMode | undefined => {
+  if (features.mode !== undefined && features.mode !== null) return features.mode;
+  if (features.bootloaderMode === true) return 'bootloader';
+  if (features.initialized === false) return 'notInitialized';
+  if (features.initialized === true) return 'normal';
+  return undefined;
+};
+
+const getProtocolV2StatusMode = (initialized?: boolean | null): DeviceStateMode | undefined => {
+  if (initialized === false) return 'notInitialized';
+  if (initialized === true) return 'normal';
+  return undefined;
+};
+
+export const mapFeaturesToState = (features: Features): DeviceStatePatch => ({
+  protocol: features.protocol,
+  protocolVersion: features.protocolVersion,
+  identity: {
+    deviceType: features.deviceType,
+    firmwareType: features.firmwareType,
+    model: features.model,
+    vendor: features.vendor,
+    deviceId: features.deviceId,
+    serialNo: features.serialNo,
+    label: features.label,
+    bleName: features.bleName,
+  },
+  status: {
+    mode: getFeaturesMode(features),
+    initialized: features.initialized,
+    unlocked: features.unlocked,
+    firmwarePresent: features.firmwarePresent,
+    backupRequired: features.backupRequired,
+    noBackup: features.noBackup,
+    unfinishedBackup: features.unfinishedBackup,
+    recoveryMode: features.recoveryMode,
+    passphraseProtection: features.passphraseProtection,
+    pinProtection: features.pinProtection,
+    attachToPinEnabled: features.attachToPinEnabled ?? null,
+    unlockedAttachPin: features.unlockedAttachPin ?? null,
+  },
+  settings: {
+    language: features.language,
+    bleEnabled: features.bleEnabled,
+    sdCardPresent: features.sdCardPresent,
+    sdProtection: features.sdProtection,
+    wipeCodeProtection: features.wipeCodeProtection,
+    passphraseAlwaysOnDevice: features.passphraseAlwaysOnDevice,
+    safetyChecks: features.safetyChecks,
+    autoLockDelayMs: features.autoLockDelayMs,
+    autoShutdownDelayMs: features.autoShutdownDelayMs,
+    displayRotation: features.displayRotation,
+    experimentalFeatures: features.experimentalFeatures,
+    wallpaperPath: features.wallpaperPath,
+    brightness: features.brightness,
+    animationEnabled: features.animationEnabled,
+    tapToWake: features.tapToWake,
+    hapticFeedback: features.hapticFeedback,
+    deviceNameDisplayEnabled: features.deviceNameDisplayEnabled,
+    airgapMode: features.airgapMode,
+    fidoEnabled: features.fidoEnabled,
+    usbLockEnabled: features.usbLockEnabled,
+    randomKeypad: features.randomKeypad,
+  },
+  versions: {
+    firmware: features.firmwareVersion,
+    bootloader: features.bootloaderVersion,
+    board: features.boardVersion,
+    ble: features.bleVersion,
+    // Legacy devices expose one SE version; project it to se01 and keep se as an alias.
+    se: features.seVersion,
+    se01: features.se01Version ?? features.seVersion,
+    se02: features.se02Version,
+    se03: features.se03Version,
+    se04: features.se04Version,
+    se01Boot: features.se01BootVersion,
+    se02Boot: features.se02BootVersion,
+    se03Boot: features.se03BootVersion,
+    se04Boot: features.se04BootVersion,
+  },
+  capabilities: features.capabilities,
+  verification: definedEntries(features.verify ?? {}),
+  raw: features.raw,
+});
+
+export const mapProtocolV1FeaturesToState = (
+  protocolV1Features: PROTO.Features
+): DeviceStatePatch => mapFeaturesToState(buildProtocolV1FeaturesPayload(protocolV1Features));
+
+const meaningfulVersion = (version?: string | null) => {
+  if (!version || version === '0.0.0') return undefined;
+  const parts = version.split('.');
+  while (parts.length < 3) parts.push('0');
+  return parts.map(part => (Number.isNaN(Number.parseInt(part, 10)) ? '0' : part)).join('.');
+};
+
+export const mapProtocolV1OnekeyFeaturesToState = (features: OnekeyFeatures): DeviceStatePatch => {
+  const verification = definedEntries<DeviceFeaturesVerify>({
+    firmwareBuildId: features.onekey_firmware_build_id,
+    firmwareHash: features.onekey_firmware_hash,
+    bootloaderBuildId: features.onekey_boot_build_id,
+    bootloaderHash: features.onekey_boot_hash,
+    boardBuildId: features.onekey_board_build_id,
+    boardHash: features.onekey_board_hash,
+    bleBuildId: features.onekey_ble_build_id,
+    bleHash: features.onekey_ble_hash,
+    se01BuildId: features.onekey_se01_build_id,
+    se01Hash: features.onekey_se01_hash,
+    se02BuildId: features.onekey_se02_build_id,
+    se02Hash: features.onekey_se02_hash,
+    se03BuildId: features.onekey_se03_build_id,
+    se03Hash: features.onekey_se03_hash,
+    se04BuildId: features.onekey_se04_build_id,
+    se04Hash: features.onekey_se04_hash,
+    se01BootBuildId: features.onekey_se01_boot_build_id,
+    se01BootHash: features.onekey_se01_boot_hash,
+    se02BootBuildId: features.onekey_se02_boot_build_id,
+    se02BootHash: features.onekey_se02_boot_hash,
+    se03BootBuildId: features.onekey_se03_boot_build_id,
+    se03BootHash: features.onekey_se03_boot_hash,
+    se04BootBuildId: features.onekey_se04_boot_build_id,
+    se04BootHash: features.onekey_se04_boot_hash,
+  });
+
+  return {
+    versions: definedEntries({
+      firmware: meaningfulVersion(features.onekey_firmware_version),
+      bootloader: meaningfulVersion(features.onekey_boot_version),
+      board: meaningfulVersion(features.onekey_board_version),
+      ble: meaningfulVersion(features.onekey_ble_version),
+      se01: meaningfulVersion(features.onekey_se01_version),
+      se02: meaningfulVersion(features.onekey_se02_version),
+      se03: meaningfulVersion(features.onekey_se03_version),
+      se04: meaningfulVersion(features.onekey_se04_version),
+      se01Boot: meaningfulVersion(features.onekey_se01_boot_version),
+      se02Boot: meaningfulVersion(features.onekey_se02_boot_version),
+      se03Boot: meaningfulVersion(features.onekey_se03_boot_version),
+      se04Boot: meaningfulVersion(features.onekey_se04_boot_version),
+    }),
+    ...(Object.keys(verification).length > 0 ? { verification } : {}),
+    raw: { protocolV1OneKeyFeatures: features },
+  };
+};
+
+export const mapProtocolV2DeviceInfoToState = (
+  info: ProtocolV2DeviceInfo,
+  mode: DeviceStateMode = 'unknown'
+): DeviceStatePatch => {
+  const loader = mode === 'bootloader' || mode === 'romloader';
+
+  return {
+    protocol: 'V2',
+    protocolVersion: info.protocol_version,
+    identity: definedEntries({
+      deviceType: EDeviceType.Pro2,
+      firmwareType: EFirmwareType.Universal,
+      model: 'pro2',
+      vendor: 'onekey.so',
+      serialNo: info.hw?.serial_no,
+      bleName: info.coprocessor?.bt_adv_name,
+      deviceId: loader ? null : undefined,
+    }),
+    status: loader
+      ? {
+          mode,
+          initialized: null,
+          unlocked: null,
+          firmwarePresent: null,
+          backupRequired: null,
+          noBackup: null,
+          unfinishedBackup: null,
+          recoveryMode: null,
+          passphraseProtection: null,
+          pinProtection: null,
+          attachToPinEnabled: null,
+          unlockedAttachPin: null,
+        }
+      : { mode },
+    versions: definedEntries({
+      firmware: imageVersion(info.fw?.application),
+      bootloader: imageVersion(info.fw?.bootloader),
+      board: imageVersion(info.fw?.romloader),
+      ble: imageVersion(info.coprocessor?.application),
+      se01: imageVersion(info.se1?.application),
+      se02: imageVersion(info.se2?.application),
+      se03: imageVersion(info.se3?.application),
+      se04: imageVersion(info.se4?.application),
+      se01Boot: imageVersion(info.se1?.bootloader),
+      se02Boot: imageVersion(info.se2?.bootloader),
+      se03Boot: imageVersion(info.se3?.bootloader),
+      se04Boot: imageVersion(info.se4?.bootloader),
+    }),
+    verification: definedEntries({
+      firmwareBuildId: imageBuildId(info.fw?.application),
+      firmwareHash: imageHash(info.fw?.application),
+      bootloaderBuildId: imageBuildId(info.fw?.bootloader),
+      bootloaderHash: imageHash(info.fw?.bootloader),
+      boardBuildId: imageBuildId(info.fw?.romloader),
+      boardHash: imageHash(info.fw?.romloader),
+      bleBuildId: imageBuildId(info.coprocessor?.application),
+      bleHash: imageHash(info.coprocessor?.application),
+      se01BuildId: imageBuildId(info.se1?.application),
+      se01Hash: imageHash(info.se1?.application),
+      se02BuildId: imageBuildId(info.se2?.application),
+      se02Hash: imageHash(info.se2?.application),
+      se03BuildId: imageBuildId(info.se3?.application),
+      se03Hash: imageHash(info.se3?.application),
+      se04BuildId: imageBuildId(info.se4?.application),
+      se04Hash: imageHash(info.se4?.application),
+      se01BootBuildId: imageBuildId(info.se1?.bootloader),
+      se01BootHash: imageHash(info.se1?.bootloader),
+      se02BootBuildId: imageBuildId(info.se2?.bootloader),
+      se02BootHash: imageHash(info.se2?.bootloader),
+      se03BootBuildId: imageBuildId(info.se3?.bootloader),
+      se03BootHash: imageHash(info.se3?.bootloader),
+      se04BootBuildId: imageBuildId(info.se4?.bootloader),
+      se04BootHash: imageHash(info.se4?.bootloader),
+    }),
+    raw: {
+      protocolV2DeviceInfo: info,
+      ...(loader ? { protocolV2DeviceStatus: null } : {}),
+    },
+  };
+};
+
+export const mapProtocolV2DeviceStatusToState = (status: DeviceStatus): DeviceStatePatch => ({
+  identity: definedEntries({ deviceId: status.device_id }),
+  status: definedEntries({
+    mode: getProtocolV2StatusMode(status.init_states),
+    initialized: status.init_states,
+    unlocked: status.unlocked,
+    passphraseProtection: status.unlocked === true ? status.passphrase_enabled ?? null : undefined,
+    backupRequired: status.backup_required,
+    attachToPinEnabled: status.attach_to_pin_enabled,
+    unlockedAttachPin: status.unlocked_by_attach_to_pin,
+  }),
+  raw: { protocolV2DeviceStatus: status },
+});
+
+export const mapApplySettingsToState = (settings: ApplySettings): DeviceStatePatch => {
+  const identity = definedEntries({ label: settings.label });
+  const status = definedEntries({ passphraseProtection: settings.use_passphrase });
+  const stateSettings = definedEntries({
+    language: settings.language,
+    autoLockDelayMs: settings.auto_lock_delay_ms,
+    autoShutdownDelayMs: settings.auto_shutdown_delay_ms,
+    displayRotation: settings.display_rotation,
+    passphraseAlwaysOnDevice: settings.passphrase_always_on_device,
+    safetyChecks: normalizeSafetyCheckLevel(settings.safety_checks),
+    experimentalFeatures: settings.experimental_features,
+    hapticFeedback: settings.haptic_feedback,
+    bleEnabled: settings.use_ble,
+  });
+  return {
+    ...(Object.keys(identity).length ? { identity } : {}),
+    ...(Object.keys(status).length ? { status } : {}),
+    ...(Object.keys(stateSettings).length ? { settings: stateSettings } : {}),
+  };
+};
+
+export const mapDeviceSettingsToState = (settings: DeviceSettings): DeviceStatePatch => {
+  const identity = definedEntries({ label: settings.label });
+  const status = definedEntries({ passphraseProtection: settings.passphrase_enable });
+  const stateSettings = definedEntries({
+    bleEnabled: settings.bt_enable,
+    language: mapLanguageFromProtocolV2(settings.language),
+    wallpaperPath: settings.wallpaper_path,
+    brightness: settings.brightness,
+    autoLockDelayMs: settings.autolock_delay_ms,
+    autoShutdownDelayMs: settings.autoshutdown_delay_ms,
+    animationEnabled: settings.animation_enable,
+    tapToWake: settings.tap_to_wake,
+    hapticFeedback: settings.haptic_feedback,
+    deviceNameDisplayEnabled: settings.device_name_display_enabled,
+    airgapMode: settings.airgap_mode,
+    fidoEnabled: settings.fido_enabled,
+    usbLockEnabled: settings.usb_lock_enable,
+    randomKeypad: settings.random_keypad,
+  });
+  return {
+    ...(Object.keys(identity).length ? { identity } : {}),
+    ...(Object.keys(status).length ? { status } : {}),
+    ...(Object.keys(stateSettings).length ? { settings: stateSettings } : {}),
+  };
+};
+
+export const mapCommonSettingsToProtocolV2 = (settings: DeviceSettingsParams): DeviceSettings =>
+  definedEntries({
+    label: settings.label,
+    bt_enable: settings.bluetoothEnabled,
+    language: mapLanguageToProtocolV2(settings.language),
+    brightness: settings.brightness,
+    autolock_delay_ms: settings.autoLockDelayMs,
+    autoshutdown_delay_ms: settings.autoShutdownDelayMs,
+    animation_enable: settings.animationEnabled,
+    tap_to_wake: settings.tapToWake,
+    haptic_feedback: settings.hapticFeedback,
+    device_name_display_enabled: settings.deviceNameDisplayEnabled,
+    fido_enabled: settings.fidoEnabled,
+    usb_lock_enable: settings.usbLockEnabled,
+    random_keypad: settings.randomKeypad,
+  });

package/src/device/DeviceStateProjector.ts

@@ -0,0 +1,95 @@
+import { cloneDeviceState } from './cloneDeviceState';
+
+import type { DeviceFeaturesRaw, DeviceState, Features } from '../types';
+
+type StoredDeviceState = DeviceState & {
+  raw?: DeviceFeaturesRaw;
+};
+
+const getBootloaderMode = (state: StoredDeviceState) =>
+  state.status.mode === 'bootloader' || state.status.mode === 'romloader';
+
+export const projectFeatures = (state: StoredDeviceState): Features => {
+  const snapshot = cloneDeviceState(state);
+  const rawFeatures = snapshot.raw?.protocolV1Features ?? {};
+  const publicRawFeatures = { ...rawFeatures } as Record<string, unknown>;
+  delete publicRawFeatures.session_id;
+  delete publicRawFeatures.sessionId;
+  delete publicRawFeatures.passphraseState;
+  const rawOneKeyFeatures = snapshot.raw?.protocolV1OneKeyFeatures ?? {};
+  const bootloaderMode =
+    snapshot.protocol === 'V1'
+      ? (rawFeatures as { bootloader_mode?: boolean | null }).bootloader_mode ?? null
+      : getBootloaderMode(snapshot);
+
+  return {
+    ...publicRawFeatures,
+    ...rawOneKeyFeatures,
+    protocol: snapshot.protocol,
+    protocolVersion: snapshot.protocolVersion ?? (snapshot.protocol === 'V1' ? 1 : null),
+    deviceType: snapshot.identity.deviceType,
+    firmwareType: snapshot.identity.firmwareType,
+    model: snapshot.identity.model,
+    vendor: snapshot.identity.vendor,
+    deviceId: snapshot.identity.deviceId,
+    serialNo: snapshot.identity.serialNo,
+    label: snapshot.identity.label,
+    bleName: snapshot.identity.bleName,
+    capabilities: snapshot.capabilities,
+    mode: snapshot.status.mode,
+    initialized: snapshot.status.initialized,
+    bootloaderMode,
+    unlocked: snapshot.status.unlocked,
+    firmwarePresent: snapshot.status.firmwarePresent,
+    passphraseProtection: snapshot.status.passphraseProtection,
+    pinProtection: snapshot.status.pinProtection,
+    backupRequired: snapshot.status.backupRequired,
+    noBackup: snapshot.status.noBackup,
+    unfinishedBackup: snapshot.status.unfinishedBackup,
+    recoveryMode: snapshot.status.recoveryMode,
+    attachToPinEnabled: snapshot.status.attachToPinEnabled,
+    unlockedAttachPin: snapshot.status.unlockedAttachPin ?? undefined,
+    language: snapshot.settings.language,
+    bleEnabled: snapshot.settings.bleEnabled,
+    sdCardPresent: snapshot.settings.sdCardPresent,
+    sdProtection: snapshot.settings.sdProtection,
+    wipeCodeProtection: snapshot.settings.wipeCodeProtection,
+    passphraseAlwaysOnDevice: snapshot.settings.passphraseAlwaysOnDevice,
+    safetyChecks: snapshot.settings.safetyChecks,
+    autoLockDelayMs: snapshot.settings.autoLockDelayMs,
+    autoShutdownDelayMs: snapshot.settings.autoShutdownDelayMs,
+    displayRotation: snapshot.settings.displayRotation,
+    experimentalFeatures: snapshot.settings.experimentalFeatures,
+    wallpaperPath: snapshot.settings.wallpaperPath,
+    brightness: snapshot.settings.brightness,
+    animationEnabled: snapshot.settings.animationEnabled,
+    tapToWake: snapshot.settings.tapToWake,
+    hapticFeedback: snapshot.settings.hapticFeedback,
+    deviceNameDisplayEnabled: snapshot.settings.deviceNameDisplayEnabled,
+    airgapMode: snapshot.settings.airgapMode,
+    fidoEnabled: snapshot.settings.fidoEnabled,
+    usbLockEnabled: snapshot.settings.usbLockEnabled,
+    randomKeypad: snapshot.settings.randomKeypad,
+    firmwareVersion: snapshot.versions.firmware,
+    bootloaderVersion: snapshot.versions.bootloader,
+    boardVersion: snapshot.versions.board,
+    bleVersion: snapshot.versions.ble,
+    se01Version: snapshot.versions.se01,
+    se02Version: snapshot.versions.se02,
+    se03Version: snapshot.versions.se03,
+    se04Version: snapshot.versions.se04,
+    se01BootVersion: snapshot.versions.se01Boot,
+    se02BootVersion: snapshot.versions.se02Boot,
+    se03BootVersion: snapshot.versions.se03Boot,
+    se04BootVersion: snapshot.versions.se04Boot,
+    seVersion: snapshot.versions.se ?? null,
+    verify: snapshot.verification,
+    raw: snapshot.raw,
+    device_id: snapshot.identity.deviceId ?? undefined,
+    ble_name: snapshot.identity.bleName ?? undefined,
+    passphrase_protection: snapshot.status.passphraseProtection ?? undefined,
+    bootloader_mode: bootloaderMode,
+    sessionId: null,
+    session_id: null,
+  } as unknown as Features;
+};

package/src/device/DeviceStateStore.ts

@@ -0,0 +1,201 @@
+import { EDeviceType, EFirmwareType } from '@onekeyfe/hd-shared';
+
+import { cloneDeviceState } from './cloneDeviceState';
+
+import type {
+  DeviceFeaturesRaw,
+  DeviceState,
+  DeviceStateIdentity,
+  DeviceStatePatch,
+  DeviceStateUpdateSource,
+} from '../types';
+
+type StoredDeviceState = DeviceState & {
+  raw?: DeviceFeaturesRaw;
+};
+
+export type DeviceStateUpdateResult = {
+  state: StoredDeviceState;
+  revision: number;
+  source: DeviceStateUpdateSource;
+  changedKeys: string[];
+};
+
+export function createEmptyDeviceState(
+  identity: Partial<DeviceStateIdentity> = {}
+): StoredDeviceState {
+  const normalizedIdentity: DeviceStateIdentity = {
+    deviceType: EDeviceType.Unknown,
+    firmwareType: EFirmwareType.Universal,
+    model: null,
+    vendor: null,
+    deviceId: null,
+    serialNo: '',
+    label: null,
+    bleName: null,
+    ...identity,
+  };
+
+  return {
+    schemaVersion: 1,
+    revision: 0,
+    updatedAt: Date.now(),
+    protocol: 'unknown',
+    protocolVersion: null,
+    identity: normalizedIdentity,
+    status: {
+      mode: 'unknown',
+      initialized: null,
+      unlocked: null,
+      firmwarePresent: null,
+      backupRequired: null,
+      noBackup: null,
+      unfinishedBackup: null,
+      recoveryMode: null,
+      passphraseProtection: null,
+      pinProtection: null,
+      attachToPinEnabled: null,
+      unlockedAttachPin: null,
+    },
+    settings: {
+      language: null,
+      bleEnabled: null,
+      sdCardPresent: null,
+      sdProtection: null,
+      wipeCodeProtection: null,
+      passphraseAlwaysOnDevice: null,
+      safetyChecks: null,
+      autoLockDelayMs: null,
+      autoShutdownDelayMs: null,
+      displayRotation: null,
+      experimentalFeatures: null,
+      wallpaperPath: null,
+      brightness: null,
+      animationEnabled: null,
+      tapToWake: null,
+      hapticFeedback: null,
+      deviceNameDisplayEnabled: null,
+      airgapMode: null,
+      fidoEnabled: null,
+      usbLockEnabled: null,
+      randomKeypad: null,
+    },
+    versions: {
+      firmware: null,
+      bootloader: null,
+      board: null,
+      ble: null,
+    },
+    capabilities: [],
+  };
+}
+
+const isEqual = (left: unknown, right: unknown) => JSON.stringify(left) === JSON.stringify(right);
+
+const applySectionPatch = <T extends object>(
+  target: T,
+  patch: Partial<T>,
+  prefix: string,
+  changedKeys: string[]
+) => {
+  for (const [key, value] of Object.entries(patch) as [keyof T, T[keyof T] | undefined][]) {
+    if (value !== undefined && !isEqual(target[key], value)) {
+      target[key] = value;
+      changedKeys.push(`${prefix}.${String(key)}`);
+    }
+  }
+};
+
+export class DeviceStateStore {
+  private state: StoredDeviceState | undefined;
+
+  constructor(initial?: StoredDeviceState) {
+    this.state = initial ? cloneDeviceState(initial) : undefined;
+  }
+
+  getState() {
+    return this.state;
+  }
+
+  replace(state: StoredDeviceState, source: DeviceStateUpdateSource): DeviceStateUpdateResult {
+    const revision = (this.state?.revision ?? 0) + 1;
+    this.state = {
+      ...cloneDeviceState(state),
+      revision,
+      updatedAt: Date.now(),
+    };
+    return {
+      state: this.state,
+      revision,
+      source,
+      changedKeys: ['*'],
+    };
+  }
+
+  update(patch: DeviceStatePatch, source: DeviceStateUpdateSource): DeviceStateUpdateResult {
+    const next = cloneDeviceState(this.state ?? createEmptyDeviceState());
+    const changedKeys: string[] = [];
+
+    if (patch.protocol !== undefined && patch.protocol !== next.protocol) {
+      next.protocol = patch.protocol;
+      changedKeys.push('protocol');
+    }
+    if (patch.protocolVersion !== undefined && patch.protocolVersion !== next.protocolVersion) {
+      next.protocolVersion = patch.protocolVersion;
+      changedKeys.push('protocolVersion');
+    }
+    if (patch.identity) applySectionPatch(next.identity, patch.identity, 'identity', changedKeys);
+    if (patch.status) applySectionPatch(next.status, patch.status, 'status', changedKeys);
+    if (patch.settings) applySectionPatch(next.settings, patch.settings, 'settings', changedKeys);
+    if (patch.versions) applySectionPatch(next.versions, patch.versions, 'versions', changedKeys);
+
+    if (patch.capabilities !== undefined && !isEqual(next.capabilities, patch.capabilities)) {
+      next.capabilities = cloneDeviceState(patch.capabilities);
+      changedKeys.push('capabilities');
+    }
+    if (patch.verification !== undefined) {
+      const mergedVerification = {
+        ...cloneDeviceState(next.verification ?? {}),
+        ...cloneDeviceState(patch.verification),
+      };
+      if (!isEqual(next.verification, mergedVerification)) {
+        next.verification = mergedVerification;
+        changedKeys.push('verification');
+      }
+    }
+    if (patch.raw !== undefined) {
+      const mergedRaw = cloneDeviceState(next.raw ?? {});
+      for (const [key, value] of Object.entries(patch.raw)) {
+        if (value === null) {
+          delete mergedRaw[key as keyof typeof mergedRaw];
+        } else if (value !== undefined) {
+          mergedRaw[key as keyof typeof mergedRaw] = cloneDeviceState(value) as never;
+        }
+      }
+      if (!isEqual(next.raw, mergedRaw)) {
+        next.raw = mergedRaw;
+        changedKeys.push('raw');
+      }
+    }
+    if (changedKeys.length > 0) {
+      next.revision = (this.state?.revision ?? 0) + 1;
+      next.updatedAt = Date.now();
+      this.state = next;
+    } else if (!this.state) {
+      this.state = next;
+    }
+
+    return {
+      state: this.state,
+      revision: this.state.revision,
+      source,
+      changedKeys,
+    };
+  }
+}
+
+export const createPublicDeviceState = (state: StoredDeviceState): DeviceState => {
+  const snapshot = cloneDeviceState(state);
+  delete snapshot.raw;
+  return snapshot;
+};