@onekeyfe/hd-core 1.2.0-alpha.35 → 1.2.0-alpha.37

package/__tests__/open-wallet-session.test.ts

@@ -5,6 +5,7 @@ import GetPassphraseState from '../src/api/GetPassphraseState';
 import OpenWalletSession from '../src/api/OpenWalletSession';
 import { Device } from '../src/device/Device';
 import { deviceWalletSessionStore } from '../src/device/DeviceWalletSessionStore';
+import { ensureProtocolV2WalletSessionUnlocked } from '../src/protocols/protocol-v2/walletSession';
 
 jest.mock('../src/data/config', () => ({
   getSDKVersion: jest.fn(() => '1.0.0'),
@@ -26,6 +27,7 @@ const createDevice = ({
       unlocked: true,
       passphraseProtection,
       attachToPinEnabled: false,
+      unlockedAttachPin: false,
     },
     commands: {
       typedCall: jest.fn((request: string, ...args: unknown[]) => {
@@ -43,10 +45,21 @@ const createDevice = ({
       }),
       promptPassphrase,
     },
-    getDeviceState: jest.fn().mockResolvedValue({
-      identity: { deviceId: 'device-1' },
-      status: { passphraseProtection },
-    }),
+    ensureProtocolV2RuntimeContext: jest.fn(() =>
+      device.commands.typedCall('ProtocolInfoRequest', 'ProtocolInfo', {
+        eventless_wallet_session: true,
+      })
+    ),
+    getDeviceState: jest.fn(() =>
+      Promise.resolve({
+        identity: { deviceId: 'device-1' },
+        status: {
+          unlocked: device.features.unlocked,
+          passphraseProtection: device.features.passphraseProtection,
+          unlockedAttachPin: device.features.unlockedAttachPin,
+        },
+      })
+    ),
     getCurrentDeviceId: () => 'device-1',
     getCurrentPassphraseProtection: () => passphraseProtection,
     getInternalState: () =>
@@ -82,6 +95,50 @@ describe('openWalletSession', () => {
     deviceWalletSessionStore.clear();
   });
 
+  test('unlocks a locked Protocol V2 device before restoring a wallet session', async () => {
+    const device = {
+      commands: {
+        typedCall: jest.fn().mockResolvedValue({ message: { unlocked: false } }),
+      },
+      isBootloader: jest.fn().mockReturnValue(false),
+      isProtocolV2: jest.fn().mockReturnValue(true),
+      isRomloader: jest.fn().mockReturnValue(false),
+      state: { status: { unlocked: false } },
+      unlockDevice: jest.fn().mockResolvedValue(undefined),
+      updateProtocolV2Status: jest.fn(function updateProtocolV2Status(
+        this: { state: { status: { unlocked: boolean } } },
+        status: { unlocked?: boolean }
+      ) {
+        this.state.status.unlocked = status.unlocked ?? this.state.status.unlocked;
+      }),
+    };
+
+    await expect(ensureProtocolV2WalletSessionUnlocked(device as any)).resolves.toBe(true);
+    expect(device.commands.typedCall).toHaveBeenCalledWith('DeviceStatusGet', 'DeviceStatus', {});
+    expect(device.unlockDevice).toHaveBeenCalledWith(DeviceSessionPinType.Main, {
+      source: 'unlock-coordinator',
+      reason: 'device-locked',
+      deviceOnly: true,
+    });
+  });
+
+  test('does not request PIN when wallet-session recovery finds the device unlocked', async () => {
+    const device = {
+      commands: {
+        typedCall: jest.fn().mockResolvedValue({ message: { unlocked: true } }),
+      },
+      isBootloader: jest.fn().mockReturnValue(false),
+      isProtocolV2: jest.fn().mockReturnValue(true),
+      isRomloader: jest.fn().mockReturnValue(false),
+      state: { status: { unlocked: true } },
+      unlockDevice: jest.fn(),
+      updateProtocolV2Status: jest.fn(),
+    };
+
+    await expect(ensureProtocolV2WalletSessionUnlocked(device as any)).resolves.toBe(false);
+    expect(device.unlockDevice).not.toHaveBeenCalled();
+  });
+
   test.each([{ useEmptyPassphrase: true }, { initSession: true }, {}])(
     'requires the explicit mode in the new public API: %p',
     legacyParams => {
@@ -273,10 +330,24 @@ describe('openWalletSession', () => {
       typedCall,
       promptPassphrase: jest.fn().mockResolvedValue({ passphraseOnDevice: true }),
     });
-    device.getDeviceState = jest.fn().mockResolvedValue({
-      identity: { deviceId: 'device-1' },
-      status: { unlocked: false, passphraseProtection: true },
-    });
+    device.getDeviceState = jest
+      .fn()
+      .mockResolvedValueOnce({
+        identity: { deviceId: 'device-1' },
+        status: {
+          unlocked: false,
+          passphraseProtection: null,
+          unlockedAttachPin: null,
+        },
+      })
+      .mockResolvedValue({
+        identity: { deviceId: 'device-1' },
+        status: {
+          unlocked: true,
+          passphraseProtection: true,
+          unlockedAttachPin: false,
+        },
+      });
     method.device = device as any;
 
     await expect(method.run()).resolves.toMatchObject({
@@ -330,6 +401,12 @@ describe('openWalletSession', () => {
         status.passphrase_enabled ?? device.features.passphraseProtection;
       return device.features;
     });
+    device.unlockDevice = jest.fn().mockImplementation(() => {
+      device.features.unlocked = true;
+      device.features.passphraseProtection = true;
+      device.features.unlockedAttachPin = false;
+      return Promise.resolve(device.features);
+    });
     method.device = device as any;
 
     await expect(method.run()).resolves.toEqual({
@@ -339,10 +416,98 @@ describe('openWalletSession', () => {
       passphraseState: 'hidden-state-after-unlock',
       resumed: false,
     });
-    expect(device.unlockDevice).not.toHaveBeenCalled();
+    expect(device.unlockDevice).toHaveBeenCalledTimes(1);
     expect(promptPassphrase).toHaveBeenCalledTimes(1);
   });
 
+  test('unlocks before wallet selection when the Protocol V2 wallet status is unknown', async () => {
+    const typedCall = jest
+      .fn()
+      .mockResolvedValueOnce({ message: { version: 2 } })
+      .mockResolvedValueOnce({ message: {} })
+      .mockResolvedValueOnce({
+        message: {
+          btc_test_address: 'hidden-state-after-unknown-status',
+          session_id: 'hidden-session-after-unknown-status',
+        },
+      });
+    const promptPassphrase = jest.fn().mockResolvedValue({ passphrase: 'host hidden wallet' });
+    const method = new OpenWalletSession({
+      payload: { method: 'openWalletSession', connectId: 'connect-id', mode: 'select-hidden' },
+    });
+    method.init();
+    const device = createDevice({ typedCall, promptPassphrase });
+    device.getDeviceState = jest
+      .fn()
+      .mockResolvedValueOnce({
+        identity: { deviceId: 'device-1' },
+        status: {
+          unlocked: undefined,
+          passphraseProtection: null,
+          unlockedAttachPin: null,
+        },
+      })
+      .mockResolvedValue({
+        identity: { deviceId: 'device-1' },
+        status: {
+          unlocked: true,
+          passphraseProtection: true,
+          unlockedAttachPin: false,
+        },
+      });
+    device.unlockDevice = jest.fn().mockImplementation(() => {
+      device.features.unlocked = true;
+      device.features.passphraseProtection = true;
+      device.features.unlockedAttachPin = false;
+      return Promise.resolve(device.features);
+    });
+    method.device = device as any;
+
+    await expect(method.run()).resolves.toMatchObject({
+      walletType: 'hidden',
+      passphraseState: 'hidden-state-after-unknown-status',
+    });
+    expect(device.unlockDevice).toHaveBeenCalledTimes(1);
+    expect(device.unlockDevice.mock.invocationCallOrder[0]).toBeLessThan(
+      promptPassphrase.mock.invocationCallOrder[0]
+    );
+  });
+
+  test('rejects wallet selection when the post-unlock Protocol V2 status remains incomplete', async () => {
+    const typedCall = jest
+      .fn()
+      .mockResolvedValueOnce({ message: { version: 2 } })
+      .mockResolvedValueOnce({ message: {} })
+      .mockResolvedValueOnce({
+        message: {
+          btc_test_address: 'hidden-state-from-incomplete-status',
+          session_id: 'hidden-session-from-incomplete-status',
+        },
+      });
+    const promptPassphrase = jest.fn().mockResolvedValue({ passphrase: 'host hidden wallet' });
+    const method = new OpenWalletSession({
+      payload: { method: 'openWalletSession', connectId: 'connect-id', mode: 'select-hidden' },
+    });
+    method.init();
+    const device = createDevice({ typedCall, promptPassphrase });
+    device.getDeviceState = jest.fn().mockResolvedValue({
+      identity: { deviceId: 'device-1' },
+      status: {
+        unlocked: true,
+        passphraseProtection: null,
+        unlockedAttachPin: null,
+      },
+    });
+    device.unlockDevice = jest.fn().mockResolvedValue(device.features);
+    method.device = device as any;
+
+    await expect(method.run()).rejects.toMatchObject({
+      errorCode: HardwareErrorCode.DeviceInitializeFailed,
+    });
+    expect(device.unlockDevice).toHaveBeenCalledTimes(1);
+    expect(promptPassphrase).not.toHaveBeenCalled();
+  });
+
   test('rejects a Pro2 standard-wallet fallback after selecting a hidden wallet', async () => {
     const typedCall = jest
       .fn()
@@ -656,7 +821,11 @@ describe('openWalletSession', () => {
     expect(typedCall).toHaveBeenCalledWith('ProtocolInfoRequest', 'ProtocolInfo', {
       eventless_wallet_session: true,
     });
-    expect(device.unlockDevice).toHaveBeenCalledWith(DeviceSessionPinType.Main);
+    expect(device.unlockDevice).toHaveBeenCalledWith(DeviceSessionPinType.Main, {
+      source: 'wallet-session-coordinator',
+      reason: 'open-wallet',
+      deviceOnly: true,
+    });
     expect(typedCall).toHaveBeenCalledWith('DeviceSessionGet', 'DeviceSession', {});
     expect(promptPassphrase).not.toHaveBeenCalled();
     expect(device.passphraseState).toBeUndefined();
@@ -686,7 +855,11 @@ describe('openWalletSession', () => {
       })
       .mockResolvedValueOnce({
         identity: { deviceId: 'device-1' },
-        status: { passphraseProtection: true },
+        status: {
+          unlocked: true,
+          passphraseProtection: true,
+          unlockedAttachPin: false,
+        },
       });
     device.unlockDevice = jest.fn().mockImplementation(() => {
       device.features.unlocked = true;
@@ -701,7 +874,11 @@ describe('openWalletSession', () => {
       passphraseState: null,
       resumed: false,
     });
-    expect(device.unlockDevice).toHaveBeenCalledWith(DeviceSessionPinType.Main);
+    expect(device.unlockDevice).toHaveBeenCalledWith(DeviceSessionPinType.Main, {
+      source: 'wallet-session-coordinator',
+      reason: 'open-wallet',
+      deviceOnly: true,
+    });
     expect(device.getDeviceState).toHaveBeenCalledTimes(2);
   });
 
@@ -721,6 +898,24 @@ describe('openWalletSession', () => {
     method.init();
     const device = createDevice({ typedCall });
     device.features.unlockedAttachPin = true;
+    device.getDeviceState = jest
+      .fn()
+      .mockResolvedValueOnce({
+        identity: { deviceId: 'device-1' },
+        status: {
+          unlocked: true,
+          unlockedAttachPin: true,
+          passphraseProtection: true,
+        },
+      })
+      .mockResolvedValue({
+        identity: { deviceId: 'device-1' },
+        status: {
+          unlocked: true,
+          unlockedAttachPin: false,
+          passphraseProtection: true,
+        },
+      });
     device.unlockDevice = jest.fn().mockImplementation(() => {
       device.features.unlockedAttachPin = false;
       return Promise.resolve(device.features);
@@ -731,7 +926,11 @@ describe('openWalletSession', () => {
       walletType: 'standard',
       passphraseState: null,
     });
-    expect(device.unlockDevice).toHaveBeenCalledWith(DeviceSessionPinType.Main);
+    expect(device.unlockDevice).toHaveBeenCalledWith(DeviceSessionPinType.Main, {
+      source: 'wallet-session-coordinator',
+      reason: 'open-wallet',
+      deviceOnly: true,
+    });
     expect(typedCall).toHaveBeenCalledWith('DeviceSessionGet', 'DeviceSession', {});
   });
 
@@ -939,7 +1138,9 @@ describe('openWalletSession', () => {
       },
       { cancelDeviceOnReject: false }
     );
-    expect(device.unlockDevice).toHaveBeenCalledWith(DeviceSessionPinType.AttachToPin);
+    expect(device.unlockDevice).toHaveBeenCalledWith(DeviceSessionPinType.AttachToPin, {
+      emitUiEvent: false,
+    });
     expect(typedCall).toHaveBeenCalledWith('DeviceSessionGet', 'DeviceSession', {});
   });
 
@@ -1215,7 +1416,11 @@ describe('openWalletSession', () => {
       })
       .mockResolvedValueOnce({
         identity: { deviceId: 'device-1' },
-        status: { passphraseProtection: true },
+        status: {
+          unlocked: true,
+          passphraseProtection: true,
+          unlockedAttachPin: false,
+        },
       });
     device.unlockDevice = jest.fn().mockImplementation(() => {
       device.features.unlocked = true;
@@ -1271,7 +1476,11 @@ describe('openWalletSession', () => {
       })
       .mockResolvedValueOnce({
         identity: { deviceId: 'other-device' },
-        status: { passphraseProtection: true },
+        status: {
+          unlocked: true,
+          passphraseProtection: true,
+          unlockedAttachPin: false,
+        },
       });
     device.unlockDevice = jest.fn().mockImplementation(() => {
       device.features.unlocked = true;
@@ -1335,7 +1544,6 @@ describe('openWalletSession', () => {
     const typedCall = jest
       .fn()
       .mockResolvedValueOnce({ message: { version: 2 } })
-      .mockResolvedValueOnce({ message: {} })
       .mockResolvedValueOnce({
         message: {
           btc_test_address: 'hidden-state',
@@ -1362,7 +1570,40 @@ describe('openWalletSession', () => {
       passphraseState: 'hidden-state',
       resumed: false,
     });
-    expect(promptPassphrase).toHaveBeenCalledTimes(1);
+    expect(typedCall).toHaveBeenCalledWith('DeviceSessionGet', 'DeviceSession', {});
+    expect(promptPassphrase).not.toHaveBeenCalled();
     expect(deviceWalletSessionStore.get('device-1', 'hidden-state')).toBe('new-session');
   });
+
+  test.each([false, true])('keeps deriveCardano API compatibility: %s', async deriveCardano => {
+    const typedCall = jest
+      .fn()
+      .mockResolvedValueOnce({ message: { version: 2 } })
+      .mockResolvedValueOnce({ message: {} })
+      .mockResolvedValueOnce({
+        message: {
+          btc_test_address: 'hidden-state',
+          session_id: 'new-session',
+        },
+      });
+    const method = new OpenWalletSession({
+      payload: {
+        method: 'openWalletSession',
+        connectId: 'connect-id',
+        mode: 'select-hidden',
+        deriveCardano,
+      },
+    });
+    method.init();
+    method.device = createDevice({
+      typedCall,
+      promptPassphrase: jest.fn().mockResolvedValue({ passphrase: 'host hidden wallet' }),
+    }) as any;
+
+    await expect(method.run()).resolves.toMatchObject({
+      walletType: 'hidden',
+      passphraseState: 'hidden-state',
+    });
+    expect(typedCall).toHaveBeenCalledWith('DeviceSessionGet', 'DeviceSession', {});
+  });
 });

package/__tests__/pro2Nft.test.ts

@@ -0,0 +1,108 @@
+import { blake2s } from '@noble/hashes/blake2s';
+import { bytesToHex } from '@noble/hashes/utils';
+
+import {
+  PRO2_NFT_IMAGE_HEIGHT,
+  PRO2_NFT_IMAGE_WIDTH,
+  PRO2_NFT_THUMBNAIL_HEIGHT,
+  PRO2_NFT_THUMBNAIL_WIDTH,
+  buildPro2NftBundle,
+} from '../src/utils/pro2Nft';
+
+const rgba = (width: number, height: number, alpha = 0xff) => {
+  const data = new Uint8Array(width * height * 4);
+  for (let index = 3; index < data.length; index += 4) data[index] = alpha;
+  return data;
+};
+
+describe('buildPro2NftBundle', () => {
+  test('builds the exact Pro2 RGB565 triplet and basename', () => {
+    const bundle = buildPro2NftBundle({
+      image: {
+        width: PRO2_NFT_IMAGE_WIDTH,
+        height: PRO2_NFT_IMAGE_HEIGHT,
+        rgba: rgba(PRO2_NFT_IMAGE_WIDTH, PRO2_NFT_IMAGE_HEIGHT),
+      },
+      thumbnail: {
+        width: PRO2_NFT_THUMBNAIL_WIDTH,
+        height: PRO2_NFT_THUMBNAIL_HEIGHT,
+        rgba: rgba(PRO2_NFT_THUMBNAIL_WIDTH, PRO2_NFT_THUMBNAIL_HEIGHT),
+      },
+      title: 'CryptoPunk #3100',
+      subtitle: 'CryptoPunks',
+      timestampMs: 1_760_000_000_000,
+    });
+
+    expect(bundle.image.byteLength).toBe(583_212);
+    expect(bundle.thumbnail.byteLength).toBe(138_876);
+    expect(Array.from(bundle.image.slice(0, 12))).toEqual([
+      0x19, 0x12, 0, 0, 28, 2, 28, 2, 56, 4, 0, 0,
+    ]);
+    expect(Array.from(bundle.thumbnail.slice(0, 12))).toEqual([
+      0x19, 0x12, 0, 0, 7, 1, 7, 1, 16, 2, 0, 0,
+    ]);
+    expect(new TextDecoder().decode(bundle.metadata)).toBe(
+      '{"title":"CryptoPunk #3100","subtitle":"CryptoPunks"}'
+    );
+    expect(bytesToHex(blake2s(bundle.image))).toBe(
+      'af4b5f8fe216cfd0ef4a9162a42b5c66a73466f2491066f66f756c4e28cc869e'
+    );
+    expect(bytesToHex(blake2s(bundle.thumbnail))).toBe(
+      '44591afae1163cc14651d77644501c6a110f96506889b825cab0351ff4de857d'
+    );
+    expect(bytesToHex(blake2s(bundle.metadata))).toBe(
+      'e30d4dc2cddd441c9f1438c783e05a623ccf76f2f6219d4281769dda1b3635b5'
+    );
+    expect(bundle.basename).toBe('nft-af4b5f8f-1760000000000');
+  });
+
+  test('composites transparent pixels onto black without an alpha plane', () => {
+    const image = rgba(PRO2_NFT_IMAGE_WIDTH, PRO2_NFT_IMAGE_HEIGHT);
+    image.set([255, 255, 255, 0], 0);
+    const bundle = buildPro2NftBundle({
+      image: { width: PRO2_NFT_IMAGE_WIDTH, height: PRO2_NFT_IMAGE_HEIGHT, rgba: image },
+      thumbnail: {
+        width: PRO2_NFT_THUMBNAIL_WIDTH,
+        height: PRO2_NFT_THUMBNAIL_HEIGHT,
+        rgba: rgba(PRO2_NFT_THUMBNAIL_WIDTH, PRO2_NFT_THUMBNAIL_HEIGHT, 0),
+      },
+      title: 'NFT',
+      subtitle: '',
+      timestampMs: 1,
+    });
+
+    expect(bundle.image[1]).toBe(0x12);
+    expect(Array.from(bundle.image.slice(12, 14))).toEqual([0, 0]);
+    expect(bundle.thumbnail.byteLength).toBe(138_876);
+  });
+
+  test('rejects invalid dimensions and metadata byte lengths', () => {
+    const validThumbnail = {
+      width: PRO2_NFT_THUMBNAIL_WIDTH,
+      height: PRO2_NFT_THUMBNAIL_HEIGHT,
+      rgba: rgba(PRO2_NFT_THUMBNAIL_WIDTH, PRO2_NFT_THUMBNAIL_HEIGHT),
+    };
+    expect(() =>
+      buildPro2NftBundle({
+        image: { width: 1, height: 1, rgba: new Uint8Array(4) },
+        thumbnail: validThumbnail,
+        title: 'NFT',
+        subtitle: '',
+        timestampMs: 1,
+      })
+    ).toThrow('540x540');
+    expect(() =>
+      buildPro2NftBundle({
+        image: {
+          width: PRO2_NFT_IMAGE_WIDTH,
+          height: PRO2_NFT_IMAGE_HEIGHT,
+          rgba: rgba(PRO2_NFT_IMAGE_WIDTH, PRO2_NFT_IMAGE_HEIGHT),
+        },
+        thumbnail: validThumbnail,
+        title: 'a'.repeat(64),
+        subtitle: '',
+        timestampMs: 1,
+      })
+    ).toThrow('1 to 63');
+  });
+});

package/__tests__/protocol-v2-ui-lifecycle.test.ts

@@ -0,0 +1,56 @@
+import { DeviceSessionPinType } from '@onekeyfe/hd-transport';
+
+import { DEVICE } from '../src/events';
+import { Device } from '../src/device/Device';
+
+jest.mock('../src/data/config', () => ({
+  getSDKVersion: jest.fn(() => '1.0.0-test'),
+  DEFAULT_DOMAIN: 'https://example.com/',
+}));
+
+describe('Protocol V2 UI interaction lifecycle', () => {
+  test('emits a matching PIN phase completion after DeviceSessionAskPin succeeds', async () => {
+    const device = new Device({ id: 'connect-1' } as any);
+    device.isProtocolV2 = jest.fn(() => true);
+    device.updateProtocolV2Status = jest.fn(() => undefined as any);
+    device.commands = {
+      typedCall: jest.fn().mockResolvedValue({
+        message: { unlocked: true },
+      }),
+    } as any;
+    device.beginProtocolV2UiInteraction();
+
+    const starts: unknown[] = [];
+    const completions: unknown[] = [];
+    device.on(DEVICE.PIN_ON_DEVICE, (...args) => starts.push(args));
+    device.on(DEVICE.PIN_ON_DEVICE_COMPLETE, (...args) => completions.push(args));
+
+    await device.unlockDevice(DeviceSessionPinType.Main, {
+      source: 'unlock-coordinator',
+      reason: 'device-locked',
+      deviceOnly: true,
+    });
+
+    const startMetadata = (starts[0] as unknown[])[2] as Record<string, unknown>;
+    const completionMetadata = (completions[0] as unknown[])[1] as Record<string, unknown>;
+    expect(startMetadata.interaction).toMatchObject({
+      phase: 'pin',
+      transition: 'start',
+      protocol: 'V2',
+    });
+    expect(completionMetadata).toMatchObject({
+      interactionId: (startMetadata.interaction as { interactionId: string }).interactionId,
+      phaseId: (startMetadata.interaction as { phaseId: string }).phaseId,
+      phase: 'pin',
+      transition: 'complete',
+      outcome: 'succeeded',
+      protocol: 'V2',
+    });
+    expect(completionMetadata.sequence).toBeGreaterThan(
+      (startMetadata.interaction as { sequence: number }).sequence
+    );
+    expect(completionMetadata.phaseId).toBe(
+      (startMetadata.interaction as { phaseId: string }).phaseId
+    );
+  });
+});

package/__tests__/protocol-v2-unlock-policy.test.ts

@@ -1,45 +1,96 @@
-import * as publicMethods from '../src/api';
-import {
-  PROTOCOL_V2_RETRY_ON_LOCKED_METHODS,
-  getProtocolV2UnlockPolicy,
-} from '../src/protocols/protocol-v2/unlockPolicy';
+import ConfluxSignMessageCIP23 from '../src/api/conflux/ConfluxSignMessageCIP23';
+import DeviceLock from '../src/api/device/DeviceLock';
+import { runMethodWithUnlockPolicy } from '../src/protocols/protocol-v2/unlockPolicyRunner';
 
 jest.mock('../src/data/config', () => ({
   DEFAULT_DOMAIN: 'https://example.com/',
   getSDKVersion: () => '0.0.0-test',
 }));
 
-describe('Protocol V2 public method unlock policy', () => {
-  test('classifies the complete public method table with an explicit replay allowlist', () => {
-    const publicMethodNames = Object.keys(publicMethods);
-    const retryMethodNames = new Set<string>(PROTOCOL_V2_RETRY_ON_LOCKED_METHODS);
-
-    expect(publicMethodNames.length).toBeGreaterThan(100);
-    expect(new Set(PROTOCOL_V2_RETRY_ON_LOCKED_METHODS).size).toBe(
-      PROTOCOL_V2_RETRY_ON_LOCKED_METHODS.length
-    );
-
-    for (const methodName of PROTOCOL_V2_RETRY_ON_LOCKED_METHODS) {
-      expect(publicMethods).toHaveProperty(methodName);
-    }
-
-    for (const methodName of publicMethodNames) {
-      expect(getProtocolV2UnlockPolicy(methodName)).toBe(
-        retryMethodNames.has(methodName) ? 'retry-on-locked' : 'none'
-      );
-    }
+describe('Protocol V2 unlock semantics', () => {
+  test('wallet business methods inherit the wallet-session unlock requirement', () => {
+    const method = new ConfluxSignMessageCIP23({
+      id: 1,
+      payload: { method: 'confluxSignMessageCIP23' },
+    });
+
+    expect(method.useDevicePassphraseState).toBe(true);
+    expect(method.unlockPolicy).toBe('none');
+    expect(method.getSupportedProtocols()).toContain('V2');
+  });
+
+  test('lock-free Protocol V2 controls explicitly opt out of wallet-session handling', () => {
+    const method = new DeviceLock({
+      id: 1,
+      payload: { method: 'deviceLock' },
+    });
+
+    method.init();
+
+    expect(method.useDevicePassphraseState).toBe(false);
+    expect(method.unlockPolicy).toBe('none');
   });
 
-  test.each([
-    'deviceUnlock',
-    'deviceLock',
-    'deviceWipe',
-    'deviceChangePin',
-    'deviceSettings',
-    'firmwareUpdateV4',
-    'deviceUploadWallpaper',
-    'uploadPortfolio',
-  ])('does not make the state-changing method %s replayable by default', methodName => {
-    expect(getProtocolV2UnlockPolicy(methodName)).toBe('none');
+  test('pre-unlocks an unregistered wallet business method', async () => {
+    const features = { unlocked: false };
+    const method = {
+      name: 'newWalletBusinessMethod',
+      unlockPolicy: 'none',
+      useDevicePassphraseState: true,
+      run: jest.fn().mockResolvedValue({ message: 'ok' }),
+    };
+    const device = {
+      features,
+      commands: {
+        typedCall: jest.fn().mockResolvedValue({ message: { unlocked: false } }),
+      },
+      isProtocolV2: () => true,
+      isBootloader: () => false,
+      isRomloader: () => false,
+      updateProtocolV2Status: jest.fn(() => features),
+      unlockDevice: jest.fn().mockImplementation(() => {
+        features.unlocked = true;
+        return Promise.resolve(features);
+      }),
+    };
+
+    await expect(runMethodWithUnlockPolicy(method as any, device as any)).resolves.toEqual({
+      message: 'ok',
+    });
+    expect(device.unlockDevice).toHaveBeenCalledTimes(1);
+    expect(method.run).toHaveBeenCalledTimes(1);
+  });
+
+  test('runs fresh-status validation before starting unlock', async () => {
+    const identityError = new Error('Unexpected device');
+    const method = {
+      name: 'walletBusinessMethod',
+      unlockPolicy: 'none',
+      useDevicePassphraseState: true,
+      run: jest.fn(),
+    };
+    const features = { unlocked: false };
+    const device = {
+      features,
+      commands: {
+        typedCall: jest.fn().mockResolvedValue({ message: { unlocked: false } }),
+      },
+      isProtocolV2: () => true,
+      isBootloader: () => false,
+      isRomloader: () => false,
+      updateProtocolV2Status: jest.fn(() => features),
+      unlockDevice: jest.fn(),
+    };
+
+    await expect(
+      runMethodWithUnlockPolicy(method as any, device as any, {
+        afterStatusBeforeUnlock: () => {
+          throw identityError;
+        },
+      })
+    ).rejects.toBe(identityError);
+
+    expect(device.unlockDevice).not.toHaveBeenCalled();
+    expect(method.run).not.toHaveBeenCalled();
   });
 });