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

package/__tests__/protocolV2FileWrite.test.ts

@@ -0,0 +1,92 @@
+import { HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import { writeProtocolV2File } from '../src/api/helpers/protocolV2FileWrite';
+
+jest.mock('../src/data/config', () => ({
+  getSDKVersion: jest.fn(() => '1.0.0'),
+  DEFAULT_DOMAIN: 'https://jssdk.onekey.so/1.0.0/',
+}));
+
+describe('writeProtocolV2File', () => {
+  test('按分片写入并只在首片设置 overwrite', async () => {
+    const data = new Uint8Array(4097);
+    const typedCall = jest.fn().mockResolvedValue({ message: {} });
+    const onProgress = jest.fn();
+
+    const result = await writeProtocolV2File({
+      commands: { typedCall } as any,
+      path: 'vol1:/wallpapers/test.bin',
+      data,
+      totalSize: data.byteLength,
+      overwrite: true,
+      onProgress,
+    });
+
+    expect(typedCall).toHaveBeenCalledTimes(2);
+    expect(typedCall.mock.calls[0][2]).toMatchObject({
+      file: { offset: 0, total_size: 4097, data: data.slice(0, 4000) },
+      overwrite: true,
+      append: false,
+      ui_percentage: 0,
+    });
+    expect(typedCall.mock.calls[1][2]).toMatchObject({
+      file: { offset: 4000, total_size: 4097, data: data.slice(4000) },
+      overwrite: false,
+      append: false,
+      ui_percentage: 100,
+    });
+    expect(result).toMatchObject({ processed_byte: 4097, chunks: 2 });
+    expect(onProgress).toHaveBeenLastCalledWith(
+      expect.objectContaining({ progress: 100, transferredBytes: 4097, totalBytes: 4097 })
+    );
+  });
+
+  test('拒绝越过文件末尾的 processed_byte', async () => {
+    const typedCall = jest.fn().mockResolvedValue({ message: { processed_byte: 10 } });
+
+    await expect(
+      writeProtocolV2File({
+        commands: { typedCall } as any,
+        path: 'vol1:/wallpapers/test.bin',
+        data: new Uint8Array([1]),
+      })
+    ).rejects.toMatchObject({ errorCode: HardwareErrorCode.RuntimeError });
+  });
+
+  test('设备返回未前进的绝对 processed_byte 时立即失败', async () => {
+    const typedCall = jest.fn().mockResolvedValue({ message: { processed_byte: 0 } });
+
+    await expect(
+      writeProtocolV2File({
+        commands: { typedCall } as any,
+        path: 'vol1:/wallpapers/test.bin',
+        data: new Uint8Array([1, 2, 3]),
+      })
+    ).rejects.toMatchObject({ errorCode: HardwareErrorCode.RuntimeError });
+  });
+
+  test('BLE 响应超时时原偏移重试且不重复上报进度', async () => {
+    const timeoutError = Object.assign(new Error('Lowlevel response timeout'), {
+      errorCode: HardwareErrorCode.BleTimeoutError,
+    });
+    const typedCall = jest
+      .fn()
+      .mockRejectedValueOnce(timeoutError)
+      .mockResolvedValueOnce({ message: { processed_byte: 3 } });
+    const onProgress = jest.fn();
+
+    await expect(
+      writeProtocolV2File({
+        commands: { typedCall } as any,
+        path: 'vol1:/wallpapers/test.bin',
+        data: new Uint8Array([1, 2, 3]),
+        maxChunkRetries: 2,
+        onProgress,
+      })
+    ).resolves.toMatchObject({ processed_byte: 3, chunks: 1 });
+
+    expect(typedCall).toHaveBeenCalledTimes(2);
+    expect(typedCall.mock.calls[1][2]).toEqual(typedCall.mock.calls[0][2]);
+    expect(onProgress).toHaveBeenCalledTimes(1);
+  });
+});

package/__tests__/protocolV2UiInteraction.test.ts

@@ -0,0 +1,266 @@
+import { UI_REQUEST } from '../src/events';
+import {
+  ProtocolV2UiInteractionCoordinator,
+  isProtocolV2UiEnabled,
+  resolveProtocolV2UiInteraction,
+} from '../src/protocols/protocol-v2/uiInteraction';
+
+const createDevice = (protocolV2 = true) => ({
+  isProtocolV2: jest.fn(() => protocolV2),
+  toMessageObject: jest.fn(() => ({ connectId: 'pro2-test', deviceType: 'pro2' })),
+});
+
+const changePinInteraction = {
+  request: 'button',
+  source: 'method-lifecycle',
+  reason: 'change-pin',
+  completion: 'page-accepted',
+  deviceOnly: true,
+} as const;
+
+describe('ProtocolV2UiInteractionCoordinator', () => {
+  test('does not synthesize UI events for Protocol V1 devices', () => {
+    const postMessage = jest.fn();
+    const coordinator = new ProtocolV2UiInteractionCoordinator(
+      createDevice(false) as any,
+      postMessage
+    );
+
+    coordinator.enterMethodInteraction(changePinInteraction);
+    coordinator.enterUnlockInteraction('deviceChangePin');
+    coordinator.close();
+
+    expect(postMessage).not.toHaveBeenCalled();
+  });
+
+  test('synthesizes and deduplicates a Protocol V2 method interaction', () => {
+    const postMessage = jest.fn();
+    const device = createDevice();
+    const coordinator = new ProtocolV2UiInteractionCoordinator(device as any, postMessage);
+
+    coordinator.enterMethodInteraction(changePinInteraction);
+    coordinator.enterMethodInteraction(changePinInteraction);
+
+    expect(postMessage).toHaveBeenCalledTimes(1);
+    expect(postMessage).toHaveBeenCalledWith({
+      event: 'UI_EVENT',
+      type: UI_REQUEST.REQUEST_BUTTON,
+      payload: {
+        device: { connectId: 'pro2-test', deviceType: 'pro2' },
+        source: 'method-lifecycle',
+        reason: 'change-pin',
+        completion: 'page-accepted',
+        deviceOnly: true,
+      },
+    });
+  });
+
+  test('synthesizes a PIN prompt for an explicit Protocol V2 unlock method', () => {
+    const postMessage = jest.fn();
+    const coordinator = new ProtocolV2UiInteractionCoordinator(createDevice() as any, postMessage);
+
+    coordinator.enterMethodInteraction({
+      request: 'pin',
+      source: 'method-lifecycle',
+      reason: 'device-unlock',
+      completion: 'operation-completed',
+      deviceOnly: true,
+      operation: 'unlock-device',
+    });
+
+    expect(postMessage.mock.calls.map(([message]) => message.type)).toEqual([
+      UI_REQUEST.REQUEST_PIN,
+    ]);
+  });
+
+  test('switches to unlock prompt and restores the method interaction', () => {
+    const postMessage = jest.fn();
+    const coordinator = new ProtocolV2UiInteractionCoordinator(createDevice() as any, postMessage);
+
+    coordinator.enterMethodInteraction(changePinInteraction);
+    coordinator.enterUnlockInteraction('deviceChangePin');
+    coordinator.resumeMethodInteraction();
+
+    expect(postMessage.mock.calls.map(([message]) => message.type)).toEqual([
+      UI_REQUEST.REQUEST_BUTTON,
+      UI_REQUEST.REQUEST_PIN,
+      UI_REQUEST.REQUEST_BUTTON,
+    ]);
+    expect(postMessage.mock.calls[1][0]).toEqual({
+      event: 'UI_EVENT',
+      type: UI_REQUEST.REQUEST_PIN,
+      payload: {
+        device: { connectId: 'pro2-test', deviceType: 'pro2' },
+        source: 'unlock-coordinator',
+        reason: 'device-locked',
+        deviceOnly: true,
+        method: 'deviceChangePin',
+      },
+    });
+  });
+
+  test('only closes an opened interaction once', () => {
+    const postMessage = jest.fn();
+    const idleCoordinator = new ProtocolV2UiInteractionCoordinator(
+      createDevice() as any,
+      postMessage
+    );
+
+    idleCoordinator.close();
+    expect(postMessage).not.toHaveBeenCalled();
+
+    const coordinator = new ProtocolV2UiInteractionCoordinator(createDevice() as any, postMessage);
+    coordinator.enterMethodInteraction(changePinInteraction);
+    coordinator.close();
+    coordinator.close();
+
+    expect(postMessage.mock.calls.map(([message]) => message.type)).toEqual([
+      UI_REQUEST.REQUEST_BUTTON,
+      UI_REQUEST.CLOSE_UI_WINDOW,
+    ]);
+  });
+
+  test('does not emit interaction events for methods without metadata such as Portfolio', () => {
+    const postMessage = jest.fn();
+    const coordinator = new ProtocolV2UiInteractionCoordinator(createDevice() as any, postMessage);
+
+    coordinator.enterMethodInteraction(undefined);
+    coordinator.close();
+
+    expect(postMessage).not.toHaveBeenCalled();
+  });
+
+  test('disables both synthesized prompts and compatibility close events for Portfolio', () => {
+    expect(isProtocolV2UiEnabled({ protocolV2UiMode: 'none' })).toBe(false);
+    expect(isProtocolV2UiEnabled({ protocolV2UiMode: 'auto' })).toBe(true);
+    expect(isProtocolV2UiEnabled({})).toBe(true);
+  });
+});
+
+describe('resolveProtocolV2UiInteraction', () => {
+  test('keeps explicit method metadata as the highest-priority policy', () => {
+    expect(
+      resolveProtocolV2UiInteraction({
+        name: 'evmSignMessage',
+        params: {},
+        protocolV2UiInteraction: changePinInteraction,
+      })
+    ).toBe(changePinInteraction);
+  });
+
+  test.each([
+    ['evmGetAddress', 'address-confirmation'],
+    ['btcGetPublicKey', 'public-key-confirmation'],
+  ])('synthesizes display confirmation metadata for %s', (name, reason) => {
+    expect(
+      resolveProtocolV2UiInteraction({
+        name,
+        params: [{ show_display: false }, { show_display: true }],
+      })
+    ).toEqual({
+      request: 'button',
+      source: 'method-lifecycle',
+      reason,
+      completion: 'operation-completed',
+      deviceOnly: true,
+      operation: name,
+    });
+  });
+
+  test.each(['evmGetAddress', 'btcGetPublicKey'])('keeps non-display %s calls eventless', name => {
+    expect(
+      resolveProtocolV2UiInteraction({
+        name,
+        params: [{ show_display: false }],
+      })
+    ).toBeUndefined();
+  });
+
+  test('uses the public address payload for aggregate address methods', () => {
+    expect(
+      resolveProtocolV2UiInteraction({
+        name: 'allNetworkGetAddress',
+        params: undefined,
+        payload: {
+          bundle: [{ showOnOneKey: false }, { showOnOneKey: true }],
+        },
+      })
+    ).toMatchObject({
+      reason: 'address-confirmation',
+      operation: 'allNetworkGetAddress',
+    });
+  });
+
+  test('covers the loop-based aggregate address method', () => {
+    expect(
+      resolveProtocolV2UiInteraction({
+        name: 'allNetworkGetAddressByLoop',
+        payload: { bundle: [{ showOnOneKey: true }] },
+      })
+    ).toMatchObject({
+      reason: 'address-confirmation',
+      operation: 'allNetworkGetAddressByLoop',
+    });
+  });
+
+  test.each([
+    'evmSignMessage',
+    'evmSignTransaction',
+    'btcSignPsbt',
+    'nostrSignEvent',
+    'tonSignProof',
+    'lnurlAuth',
+    'btcVerifyMessage',
+    'evmVerifyMessage',
+    'starcoinVerifyMessage',
+  ])('synthesizes one generic signing confirmation for %s', name => {
+    expect(resolveProtocolV2UiInteraction({ name, params: {} })).toEqual({
+      request: 'button',
+      source: 'method-lifecycle',
+      reason: 'signing-confirmation',
+      completion: 'operation-completed',
+      deviceOnly: true,
+      operation: name,
+    });
+  });
+
+  test.each(['nostrEncryptMessage', 'nostrDecryptMessage'])(
+    'uses the display flag for interactive cryptographic method %s',
+    name => {
+      expect(
+        resolveProtocolV2UiInteraction({ name, params: { show_display: true } })
+      ).toMatchObject({
+        reason: 'signing-confirmation',
+        operation: name,
+      });
+      expect(
+        resolveProtocolV2UiInteraction({ name, params: { show_display: false } })
+      ).toBeUndefined();
+    }
+  );
+
+  test('only prompts for cipherKeyValue when the active direction asks for confirmation', () => {
+    expect(
+      resolveProtocolV2UiInteraction({
+        name: 'cipherKeyValue',
+        params: [{ encrypt: true, ask_on_encrypt: true, ask_on_decrypt: false }],
+      })
+    ).toMatchObject({
+      reason: 'signing-confirmation',
+      operation: 'cipherKeyValue',
+    });
+    expect(
+      resolveProtocolV2UiInteraction({
+        name: 'cipherKeyValue',
+        params: [{ encrypt: false, ask_on_encrypt: true, ask_on_decrypt: false }],
+      })
+    ).toBeUndefined();
+  });
+
+  test.each(['deviceVerify', 'deviceStatusGet', 'uploadPortfolio'])(
+    'does not infer an interaction for %s',
+    name => {
+      expect(resolveProtocolV2UiInteraction({ name, params: {} })).toBeUndefined();
+    }
+  );
+});

package/__tests__/public-device-state-api.test.ts

@@ -0,0 +1,253 @@
+import * as publicMethods from '../src/api';
+import GetFeatures from '../src/api/GetFeatures';
+import GetOnekeyFeatures from '../src/api/GetOnekeyFeatures';
+import DeviceInfoGet from '../src/api/protocol-v2/DeviceInfoGet';
+import DeviceSettingsGet from '../src/api/protocol-v2/DeviceSettingsGet';
+import DeviceStatusGet from '../src/api/protocol-v2/DeviceStatusGet';
+import { createEmptyDeviceState } from '../src/device/DeviceStateStore';
+import { findMethod } from '../src/api/utils';
+import { createCoreApi } from '../src/inject';
+
+import type { CoreApi } from '../src/types/api';
+
+jest.mock('../src/data/config', () => ({
+  DEFAULT_DOMAIN: 'https://example.com/',
+  getSDKVersion: () => '0.0.0-test',
+}));
+
+describe('public device state API boundary', () => {
+  test('exposes canonical device state operations and development Protocol V2 methods', () => {
+    const api = createCoreApi(jest.fn() as CoreApi['call']) as Record<string, unknown>;
+
+    expect(api.getDeviceState).toBeInstanceOf(Function);
+    expect(api.getPassphraseState).toBeInstanceOf(Function);
+    expect(api.openWalletSession).toBeInstanceOf(Function);
+    expect(api.clearSessionCache).toBeInstanceOf(Function);
+    expect(api.deviceGetOnboardingStatus).toBeInstanceOf(Function);
+    expect(api.uploadPortfolio).toBeInstanceOf(Function);
+    expect(api).not.toHaveProperty('refreshDeviceState');
+    expect(api.getFeatures).toBeInstanceOf(Function);
+    expect(api.getOnekeyFeatures).toBeInstanceOf(Function);
+    expect(api).not.toHaveProperty('getDeviceInfo');
+    expect(api.deviceInfoGet).toBeInstanceOf(Function);
+    expect(api.deviceStatusGet).toBeInstanceOf(Function);
+    expect(api.deviceSettingsGet).toBeInstanceOf(Function);
+    expect(api).not.toHaveProperty('deviceSessionOpen');
+    expect(api.deviceSettingsSet).toBeInstanceOf(Function);
+    expect(api.deviceSettingsPageShow).toBeInstanceOf(Function);
+    expect(api.deviceFirmwareUpdate).toBeInstanceOf(Function);
+    expect(api.deviceGetFirmwareUpdateStatus).toBeInstanceOf(Function);
+    expect(api.deviceFactoryInfoSet).toBeInstanceOf(Function);
+    expect(api.deviceFactoryInfoGet).toBeInstanceOf(Function);
+    expect(api.filesystemPermissionFix).toBeInstanceOf(Function);
+    expect(api.filesystemFormat).toBeInstanceOf(Function);
+    expect(api.fileRead).toBeInstanceOf(Function);
+    expect(api.fileWrite).toBeInstanceOf(Function);
+    expect(api).not.toHaveProperty('filesystemFileRead');
+    expect(api).not.toHaveProperty('filesystemDirList');
+
+    expect(publicMethods).not.toHaveProperty('getDeviceInfo');
+    expect(publicMethods).toHaveProperty('deviceInfoGet');
+    expect(publicMethods).toHaveProperty('deviceStatusGet');
+    expect(publicMethods).toHaveProperty('deviceSettingsGet');
+    expect(publicMethods).not.toHaveProperty('deviceSessionOpen');
+    expect(publicMethods).toHaveProperty('deviceSettingsSet');
+    expect(publicMethods).toHaveProperty('deviceSettingsPageShow');
+    expect(publicMethods).toHaveProperty('filesystemPermissionFix');
+    expect(publicMethods).toHaveProperty('filesystemFormat');
+    expect(publicMethods).toHaveProperty('fileRead');
+    expect(publicMethods).toHaveProperty('fileWrite');
+    expect(publicMethods).not.toHaveProperty('filesystemFileRead');
+  });
+
+  test('forwards the V1 compatibility API and the explicit V2 wallet session API', async () => {
+    const call = jest.fn().mockResolvedValue({ success: true, payload: {} });
+    const api = createCoreApi(call as CoreApi['call']) as CoreApi;
+
+    await api.getPassphraseState('device-1', {
+      initSession: true,
+      useEmptyPassphrase: false,
+    });
+    await api.openWalletSession('device-2', {
+      mode: 'resume-hidden',
+      deviceId: 'wallet-device-1',
+      passphraseState: 'wallet-state-1',
+    });
+    await api.clearSessionCache({
+      deviceId: 'wallet-device-1',
+      passphraseState: 'wallet-state-1',
+    });
+
+    expect(call).toHaveBeenNthCalledWith(1, {
+      connectId: 'device-1',
+      initSession: true,
+      useEmptyPassphrase: false,
+      method: 'getPassphraseState',
+    });
+    expect(call).toHaveBeenNthCalledWith(2, {
+      connectId: 'device-2',
+      mode: 'resume-hidden',
+      deviceId: 'wallet-device-1',
+      passphraseState: 'wallet-state-1',
+      method: 'openWalletSession',
+    });
+    expect(call).toHaveBeenNthCalledWith(3, {
+      deviceId: 'wallet-device-1',
+      passphraseState: 'wallet-state-1',
+      method: 'clearSessionCache',
+    });
+  });
+
+  test('forwards only the semantic scope through getDeviceState', async () => {
+    const call = jest.fn().mockResolvedValue({ success: true, payload: {} });
+    const api = createCoreApi(call as CoreApi['call']) as CoreApi;
+
+    await api.getDeviceState('device-1');
+    await (api.getDeviceState as any)('device-1', {
+      scope: 'settings',
+      refresh: ['status'],
+      includeRaw: true,
+    });
+
+    expect(call).toHaveBeenNthCalledWith(1, {
+      connectId: 'device-1',
+      method: 'getDeviceState',
+    });
+    expect(call).toHaveBeenNthCalledWith(2, {
+      connectId: 'device-1',
+      method: 'getDeviceState',
+      scope: 'settings',
+    });
+  });
+
+  test('keeps Protocol V2 command implementations available inside the SDK', () => {
+    expect(DeviceInfoGet).toBeDefined();
+    expect(DeviceStatusGet).toBeDefined();
+    expect(DeviceSettingsGet).toBeDefined();
+  });
+
+  test.each([
+    ['deviceInfoGet', DeviceInfoGet],
+    ['deviceStatusGet', DeviceStatusGet],
+    ['deviceSettingsGet', DeviceSettingsGet],
+  ])('allows the dispatcher to run the public development method %s', (name, Method) => {
+    const instance = findMethod({
+      id: 1,
+      payload: { method: name },
+    } as any);
+
+    expect(instance).toBeInstanceOf(Method);
+  });
+
+  test.each([
+    'protocolInfoRequest',
+    'ping',
+    'deviceFirmwareUpdate',
+    'deviceGetFirmwareUpdateStatus',
+    'deviceFactoryInfoSet',
+    'deviceFactoryInfoGet',
+    'deviceSettingsSet',
+    'deviceSettingsPageShow',
+  ])('keeps the public development method %s available to the dispatcher', name => {
+    expect(
+      findMethod({
+        id: 1,
+        payload: { method: name },
+      } as any)
+    ).toBeDefined();
+  });
+
+  test('rejects raw deviceSessionOpen while exposing openWalletSession', () => {
+    expect(() =>
+      findMethod({
+        id: 1,
+        payload: { method: 'deviceSessionOpen' },
+      } as any)
+    ).toThrow('Method deviceSessionOpen is not set');
+  });
+
+  test.each(['filesystemPermissionFix', 'filesystemFormat'])(
+    'keeps the development maintenance method %s available to the dispatcher',
+    name => {
+      expect(
+        findMethod({
+          id: 1,
+          payload: { method: name },
+        } as any)
+      ).toBeDefined();
+    }
+  );
+
+  test('projects getFeatures from the canonical state for Protocol V1 compatibility', async () => {
+    const state = createEmptyDeviceState({
+      deviceId: 'device-1',
+      serialNo: 'SERIAL-1',
+      label: 'Unified',
+    });
+    const getDeviceState = jest.fn().mockResolvedValue(state);
+    const method = new GetFeatures({ id: 1, payload: { method: 'getFeatures' } });
+    method.init();
+    expect(method.unlockPolicy).toBe('none');
+    (method as any).device = {
+      getDeviceState,
+      getCurrentFirmwareType: () => 'universal',
+      isBootloader: () => false,
+      isProtocolV2: () => false,
+    };
+
+    await expect(method.run()).resolves.toMatchObject({
+      deviceId: 'device-1',
+      label: 'Unified',
+    });
+    expect(getDeviceState).toHaveBeenCalledWith({
+      includeRaw: true,
+    });
+  });
+
+  test('rejects getFeatures for Protocol V2 devices', async () => {
+    const getDeviceState = jest.fn();
+    const method = new GetFeatures({ id: 1, payload: { method: 'getFeatures' } });
+    method.init();
+    expect(method.unlockPolicy).toBe('none');
+    (method as any).device = {
+      getDeviceState,
+      getCurrentFirmwareType: () => 'universal',
+      isBootloader: () => false,
+      isProtocolV2: () => true,
+    };
+
+    await expect(method.run()).rejects.toMatchObject({
+      errorCode: expect.any(Number),
+    });
+    expect(getDeviceState).not.toHaveBeenCalled();
+  });
+
+  test('rejects getOnekeyFeatures for Protocol V2 devices', async () => {
+    const typedCall = jest.fn();
+    const method = new GetOnekeyFeatures({ id: 1, payload: { method: 'getOnekeyFeatures' } });
+    method.init();
+    expect(method.unlockPolicy).toBe('none');
+    (method as any).device = {
+      commands: { typedCall },
+      getCurrentFirmwareType: () => 'universal',
+      isProtocolV2: () => true,
+    };
+
+    await expect(method.run()).rejects.toMatchObject({
+      errorCode: expect.any(Number),
+    });
+    expect(typedCall).not.toHaveBeenCalled();
+  });
+});
+
+// 这些临时 Pro2 查询不再属于 CoreApi；若重新暴露，下列断言会产生未使用的 ts-expect-error。
+// @ts-expect-error getDeviceInfo 已从公共 API 删除
+type RemovedGetDeviceInfo = CoreApi['getDeviceInfo'];
+// @ts-expect-error deviceInfoGet 已从公共 API 删除
+type RemovedDeviceInfoGet = CoreApi['deviceInfoGet'];
+// @ts-expect-error deviceStatusGet 已从公共 API 删除
+type RemovedDeviceStatusGet = CoreApi['deviceStatusGet'];
+// @ts-expect-error deviceSettingsGet 已从公共 API 删除
+type RemovedDeviceSettingsGet = CoreApi['deviceSettingsGet'];
+// @ts-expect-error refreshDeviceState 已被 getDeviceState scope 取代
+type RemovedRefreshDeviceState = CoreApi['refreshDeviceState'];

package/__tests__/public-pro2-api-boundary.test.ts

@@ -0,0 +1,91 @@
+import * as publicMethods from '../src/api';
+import { findMethod } from '../src/api/utils';
+import { createCoreApi } from '../src/inject';
+
+import type { CoreApi } from '../src/types/api';
+
+jest.mock('../src/data/config', () => ({
+  DEFAULT_DOMAIN: 'https://example.com/',
+  getSDKVersion: () => '0.0.0-test',
+}));
+
+const publicDevelopmentMethodNames = [
+  'deviceInfoGet',
+  'deviceStatusGet',
+  'deviceSettingsGet',
+  'protocolInfoRequest',
+  'ping',
+  'deviceFirmwareUpdate',
+  'deviceGetFirmwareUpdateStatus',
+  'deviceFactoryInfoSet',
+  'deviceFactoryInfoGet',
+  'deviceSettingsSet',
+  'deviceSettingsPageShow',
+] as const;
+
+const publicFilesystemMethodNames = [
+  'filesystemPermissionFix',
+  'filesystemFormat',
+  'fileRead',
+  'fileWrite',
+  'fileDelete',
+  'dirList',
+  'dirMake',
+  'dirRemove',
+  'pathInfo',
+] as const;
+
+const unpublishedFilesystemAliases = [
+  'filesystemFileRead',
+  'filesystemFileWrite',
+  'filesystemFileDelete',
+  'filesystemDirList',
+  'filesystemDirMake',
+  'filesystemDirRemove',
+  'filesystemPathInfoQuery',
+] as const;
+
+describe('public Pro2 API boundary', () => {
+  test('exposes the explicit development surface without the raw wallet session command', () => {
+    const api = createCoreApi(jest.fn() as CoreApi['call']) as Record<string, unknown>;
+
+    expect(api.deviceGetOnboardingStatus).toBeInstanceOf(Function);
+    expect(api.uploadPortfolio).toBeInstanceOf(Function);
+
+    publicDevelopmentMethodNames.forEach(name => {
+      expect(api).toHaveProperty(name, expect.any(Function));
+      expect(publicMethods).toHaveProperty(name);
+    });
+    publicFilesystemMethodNames.forEach(name => {
+      expect(api).toHaveProperty(name, expect.any(Function));
+      expect(publicMethods).toHaveProperty(name);
+    });
+    expect(api).not.toHaveProperty('deviceSessionOpen');
+    expect(publicMethods).not.toHaveProperty('deviceSessionOpen');
+    unpublishedFilesystemAliases.forEach(name => {
+      expect(api).not.toHaveProperty(name);
+      expect(publicMethods).not.toHaveProperty(name);
+    });
+  });
+
+  test.each([...publicDevelopmentMethodNames, ...publicFilesystemMethodNames])(
+    'keeps %s available to the dispatcher',
+    name => {
+      expect(
+        findMethod({
+          id: 1,
+          payload: { method: name },
+        } as any)
+      ).toBeDefined();
+    }
+  );
+
+  test('rejects deviceSessionOpen at the SDK dispatcher boundary', () => {
+    expect(() =>
+      findMethod({
+        id: 1,
+        payload: { method: 'deviceSessionOpen' },
+      } as any)
+    ).toThrow('Method deviceSessionOpen is not set');
+  });
+});