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

package/__tests__/protocol-v2.test.ts

@@ -61,6 +61,7 @@ import { createCoreApi } from '../src/inject';
 import { Device, preloadSessionCache } from '../src/device/Device';
 import { deviceWalletSessionStore } from '../src/device/DeviceWalletSessionStore';
 import { DevicePool } from '../src/device/DevicePool';
+import { DEVICE } from '../src/events';
 import { UI_REQUEST } from '../src/events/ui-request';
 import {
   PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS,
@@ -70,15 +71,18 @@ import {
   getProtocolV2RuntimeMode,
   parseProtocolV2BuildFingerprint,
   requestProtocolV2DeviceInfo,
-  requestProtocolV2ProtocolInfo,
   requestProtocolV2DeviceStatus,
+  requestProtocolV2ProtocolInfo,
   supportsProtocolV2Message,
 } from '../src/protocols/protocol-v2/features';
 import {
   getProtocolV2WalletSession,
   refreshProtocolV2DeviceStatus,
 } from '../src/protocols/protocol-v2/walletSession';
-import { runMethodWithUnlockRetry } from '../src/protocols/protocol-v2/unlockRetry';
+import {
+  createProtocolV2UnlockContext,
+  runMethodWithUnlockPolicy,
+} from '../src/protocols/protocol-v2/unlockPolicyRunner';
 import { BaseMethod } from '../src/api/BaseMethod';
 import {
   buildProtocolV1FeaturesPayload,
@@ -240,7 +244,7 @@ describe('UploadPortfolio', () => {
     (method as any).device = device;
 
     method.init();
-    await runMethodWithUnlockRetry(method, device as any);
+    await runMethodWithUnlockPolicy(method, device as any);
 
     expect(unlockDevice).not.toHaveBeenCalled();
     expect(typedCall).toHaveBeenNthCalledWith(
@@ -416,14 +420,16 @@ function stubDevice<T extends Record<string, any>>(device: T): T {
     }
     return d.features;
   };
+  d.ensureProtocolV2RuntimeContext ??= (timeoutMs?: number) =>
+    requestProtocolV2ProtocolInfo({
+      commands: d.getCommands?.() ?? d.commands,
+      timeoutMs,
+    });
   d.probeProtocolV2RuntimeState ??= async (
     deviceInfo: ProtocolV2DeviceInfo,
     timeoutMs?: number
   ) => {
-    const protocolInfo = await requestProtocolV2ProtocolInfo({
-      commands: d.getCommands(),
-      timeoutMs,
-    });
+    const protocolInfo = await d.ensureProtocolV2RuntimeContext(timeoutMs);
     const runtimeMode = getProtocolV2RuntimeMode(protocolInfo);
     if (runtimeMode === 'bootloader' || runtimeMode === 'romloader') {
       return d.updateProtocolV2Features(deviceInfo, null, runtimeMode, protocolInfo);
@@ -804,7 +810,7 @@ describe('Protocol V2 feature adapter', () => {
     ).resolves.toEqual({
       passphraseState: 'state-1',
       newSession: 'session-1',
-      unlockedAttachPin: undefined,
+      unlockedAttachPin: false,
       resumed: false,
     });
     expect(typedCall).toHaveBeenCalledWith('ProtocolInfoRequest', 'ProtocolInfo', {
@@ -1552,6 +1558,70 @@ describe('Protocol V2 feature adapter', () => {
     expect(device.getInternalState()).toBeUndefined();
   });
 
+  test.each([false, true])(
+    'rejects a different Attach PIN wallet when Pro2 lock failure is %s',
+    async lockFails => {
+      const deviceId = 'attach-mismatch-device';
+      const device = Device.fromDescriptor({ ...descriptor, protocolType: 'V2' } as any);
+      (device as any).features = normalizeProtocolV2Features(
+        { ...descriptor, protocolType: 'V2' } as any,
+        {
+          status: {
+            device_id: deviceId,
+            unlocked: true,
+            passphrase_enabled: true,
+            attach_to_pin_enabled: true,
+            unlocked_by_attach_to_pin: false,
+          },
+        }
+      );
+      device.passphraseState = 'expected-state';
+
+      const typedCall = jest.fn((request: string) => {
+        if (request === 'ProtocolInfoRequest') return { message: { version: 2 } };
+        if (request === 'DeviceSessionAskPin') return { message: { message: 'PIN verified' } };
+        if (request === 'DeviceStatusGet') {
+          return {
+            message: {
+              device_id: deviceId,
+              unlocked: true,
+              passphrase_enabled: true,
+              attach_to_pin_enabled: true,
+              unlocked_by_attach_to_pin: true,
+            },
+          };
+        }
+        if (request === 'DeviceSessionGet') {
+          return {
+            message: {
+              btc_test_address: 'wrong-attach-state',
+              session_id: 'wrong-attach-session',
+            },
+          };
+        }
+        if (request === 'LockDevice') {
+          if (lockFails) throw new Error('Lock unsupported');
+          return { message: { message: 'Device locked' } };
+        }
+        throw new Error(`Unexpected request: ${request}`);
+      });
+      const promptPassphrase = jest.fn().mockResolvedValue({ attachPinOnDevice: true });
+      (device as any).commands = { typedCall, promptPassphrase };
+
+      await expect(
+        getProtocolV2WalletSession(device, { expectedPassphraseState: 'expected-state' })
+      ).rejects.toMatchObject({
+        errorCode: HardwareErrorCode.DeviceCheckUnlockTypeError,
+      });
+
+      expect(promptPassphrase).not.toHaveBeenCalled();
+      expect(typedCall).toHaveBeenCalledWith('DeviceSessionGet', 'DeviceSession', {});
+      expect(typedCall).toHaveBeenCalledWith('LockDevice', 'Success', {});
+      expect(typedCall.mock.calls.filter(call => call[0] === 'DeviceSessionGet')).toHaveLength(1);
+      expect(device.getInternalState()).toBeUndefined();
+    }
+  );
+
   test('recovers an expired Attach PIN wallet through the unified wallet selector', async () => {
     const device = Device.fromDescriptor({
       id: 'cache-device-attach-recovery',
@@ -1608,7 +1678,17 @@ describe('Protocol V2 feature adapter', () => {
       }),
       { cancelDeviceOnReject: false }
     );
-    expect(unlockDevice).toHaveBeenCalledWith(DeviceSessionPinType.AttachToPin);
+    expect(unlockDevice).toHaveBeenCalledWith(
+      DeviceSessionPinType.AttachToPin,
+      expect.objectContaining({
+        emitUiEvent: false,
+        interaction: expect.objectContaining({
+          phase: 'pin',
+          transition: 'start',
+          protocol: 'V2',
+        }),
+      })
+    );
     expect(device.getInternalState()).toBe('new-attach-session');
   });
 
@@ -1892,12 +1972,10 @@ describe('Protocol V2 feature adapter', () => {
     expect(getFeatures).not.toHaveBeenCalled();
   });
 
-  test('marks an interactive cache miss as a wallet-session recovery', async () => {
+  test('uses the cached wallet address when the local session is missing', async () => {
     const typedCall = jest
       .fn()
       .mockResolvedValueOnce({ message: { version: 2 } })
-      .mockResolvedValueOnce({ message: { message: 'Passphrase prepared' } })
-      .mockResolvedValueOnce({ message: { unlocked: true, unlocked_attach_pin: false } })
       .mockResolvedValueOnce({
         message: {
           btc_test_address: 'expected-state',
@@ -1925,16 +2003,8 @@ describe('Protocol V2 feature adapter', () => {
     await expect(
       getProtocolV2WalletSession(device, { expectedPassphraseState: 'expected-state' })
     ).resolves.toMatchObject({ passphraseState: 'expected-state' });
-    expect(promptPassphrase).toHaveBeenCalledWith(
-      {
-        existsAttachPinUser: false,
-        deviceOnly: false,
-        source: 'wallet-session-coordinator',
-        reason: 'session-recovery',
-        expectedPassphraseState: 'expected-state',
-      },
-      { cancelDeviceOnReject: false }
-    );
+    expect(typedCall).toHaveBeenCalledWith('DeviceSessionGet', 'DeviceSession', {});
+    expect(promptPassphrase).not.toHaveBeenCalled();
   });
 
   test('reuses the Pro2 session opened by legacy getPassphraseState on the next App call', async () => {
@@ -2000,7 +2070,6 @@ describe('Protocol V2 feature adapter', () => {
       true
     );
     expect(typedCall.mock.calls).toEqual([
-      ['ProtocolInfoRequest', 'ProtocolInfo', { eventless_wallet_session: true }],
       ['DeviceSessionGet', 'DeviceSession', { session_id: 'session-pro2-app' }],
     ]);
   });
@@ -2268,12 +2337,13 @@ describe('Protocol V2 feature adapter', () => {
     );
 
     expect(device.getInternalState()).toBeUndefined();
-    expect(typedCall).toHaveBeenNthCalledWith(2, 'DeviceSessionAskPassphrase', 'Success', {
+    expect(typedCall).toHaveBeenCalledWith('DeviceSessionGet', 'DeviceSession', {});
+    expect(typedCall).toHaveBeenCalledWith('DeviceSessionAskPassphrase', 'Success', {
       passphrase: 'host hidden wallet',
       on_device: false,
     });
-    expect(typedCall).toHaveBeenNthCalledWith(3, 'DeviceStatusGet', 'DeviceStatus', {});
-    expect(typedCall).toHaveBeenNthCalledWith(4, 'DeviceSessionGet', 'DeviceSession', {});
+    expect(typedCall).toHaveBeenCalledWith('DeviceStatusGet', 'DeviceStatus', {});
+    expect(typedCall).toHaveBeenCalledWith('DeviceSessionGet', 'DeviceSession', {});
   });
 
   test('useEmptyPassphrase ignores a stale hidden-wallet state during Protocol V2 safety check', async () => {
@@ -2310,6 +2380,9 @@ describe('Protocol V2 feature adapter', () => {
     expect(typedCall).toHaveBeenCalledWith('ProtocolInfoRequest', 'ProtocolInfo', {
       eventless_wallet_session: true,
     });
+    expect(typedCall).toHaveBeenCalledWith('DeviceSessionAskPin', 'Success', {
+      type: DeviceSessionPinType.Main,
+    });
   });
 
   test('marks fallback features as unavailable when DeviceInfo is missing', () => {
@@ -2680,7 +2753,9 @@ describe('Protocol V2 feature adapter', () => {
         timeoutMs: PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS,
       }
     );
-    expect(typedCall).toHaveBeenNthCalledWith(2, 'ProtocolInfoRequest', 'ProtocolInfo', {});
+    expect(typedCall).toHaveBeenNthCalledWith(2, 'ProtocolInfoRequest', 'ProtocolInfo', {
+      eventless_wallet_session: true,
+    });
     expect(typedCall).toHaveBeenNthCalledWith(3, 'DeviceStatusGet', 'DeviceStatus', {});
   });
 
@@ -2718,7 +2793,9 @@ describe('Protocol V2 feature adapter', () => {
       }),
       expect.anything()
     );
-    expect(typedCall).toHaveBeenNthCalledWith(2, 'ProtocolInfoRequest', 'ProtocolInfo', {});
+    expect(typedCall).toHaveBeenNthCalledWith(2, 'ProtocolInfoRequest', 'ProtocolInfo', {
+      eventless_wallet_session: true,
+    });
     expect(typedCall).not.toHaveBeenCalledWith('DeviceStatusGet', 'DeviceStatus', {});
     expect(device.features).toMatchObject({
       deviceId: null,
@@ -2839,6 +2916,59 @@ describe('Protocol V2 feature adapter', () => {
     });
   });
 
+  test('maps an explicit unsupported DeviceStatusGet response to bootloader for an unknown fingerprint', async () => {
+    const device = Device.fromDescriptor({
+      path: 'usb-path',
+      protocolType: 'V2',
+    } as any);
+    const protocolInfo = {
+      ...protocolV2ApplicationInfo,
+      build_fingerprint: 'legacy-fingerprint',
+    };
+    const typedCall = jest
+      .fn()
+      .mockResolvedValueOnce({ type: 'ProtocolInfo', message: protocolInfo })
+      .mockRejectedValueOnce(new Error('Failure_UnexpectedMessage,Unknown message'));
+    (device as any).commands = { typedCall };
+
+    await device.probeProtocolV2RuntimeState({
+      hw: { Device_type: DeviceType.PRO2, serial_no: 'PR2SERIAL' },
+      fw: { bootloader: { version: '0.2.0' } },
+    });
+
+    expect(device.features).toMatchObject({
+      mode: 'bootloader',
+      bootloaderMode: true,
+      initialized: null,
+    });
+  });
+
+  test('propagates DeviceStatusGet link failures instead of mapping them to bootloader', async () => {
+    const device = Device.fromDescriptor({
+      path: 'usb-path',
+      protocolType: 'V2',
+    } as any);
+    const protocolInfo = {
+      ...protocolV2ApplicationInfo,
+      build_fingerprint: 'legacy-fingerprint',
+    };
+    const linkError = new Error('Protocol V2 CRC mismatch');
+    const typedCall = jest
+      .fn()
+      .mockResolvedValueOnce({ type: 'ProtocolInfo', message: protocolInfo })
+      .mockRejectedValueOnce(linkError);
+    (device as any).commands = { typedCall };
+
+    await expect(
+      device.probeProtocolV2RuntimeState({
+        hw: { Device_type: DeviceType.PRO2, serial_no: 'PR2SERIAL' },
+        fw: { application: { version: '1.2.3' } },
+      })
+    ).rejects.toBe(linkError);
+
+    expect(device.features).toBeUndefined();
+  });
+
   test('fails safely when runtime fingerprint and capabilities are both unknown', async () => {
     const device = Device.fromDescriptor({
       path: 'usb-path',
@@ -2931,10 +3061,6 @@ describe('Protocol V2 feature adapter', () => {
           fw: { application: { version: '1.2.4' } },
         },
       })
-      .mockResolvedValueOnce({
-        type: 'ProtocolInfo',
-        message: protocolV2ApplicationInfo,
-      })
       .mockResolvedValueOnce({
         type: 'DeviceStatus',
         message: { init_states: true, unlocked: true },
@@ -2956,7 +3082,7 @@ describe('Protocol V2 feature adapter', () => {
       firmwareVersion: '1.2.4',
       passphraseProtection: null,
     });
-    expect(typedCall).toHaveBeenCalledTimes(6);
+    expect(typedCall).toHaveBeenCalledTimes(5);
     expect(typedCall).toHaveBeenNthCalledWith(
       4,
       'DeviceInfoGet',
@@ -3070,9 +3196,23 @@ describe('Protocol V2 feature adapter', () => {
         status: { init_states: true },
       }
     );
+    const pinOnDevice = jest.fn();
+    device.on(DEVICE.PIN_ON_DEVICE, pinOnDevice);
 
     const features = await device.unlockDevice();
 
+    expect(pinOnDevice).toHaveBeenCalledWith(
+      device,
+      DeviceSessionPinType.Main,
+      expect.objectContaining({
+        source: 'unlock-coordinator',
+        reason: 'device-unlock',
+        deviceOnly: true,
+      })
+    );
+    expect(pinOnDevice.mock.invocationCallOrder[0]).toBeLessThan(
+      typedCall.mock.invocationCallOrder[0]
+    );
     expect(typedCall.mock.calls).toEqual([
       ['DeviceSessionAskPin', 'Success', { type: DeviceSessionPinType.Main }],
       ['DeviceStatusGet', 'DeviceStatus', {}],
@@ -3118,9 +3258,12 @@ describe('Protocol V2 feature adapter', () => {
       throw new Error(`Unexpected request: ${requestType}`);
     });
     (device as any).commands = { typedCall };
+    const pinOnDevice = jest.fn();
+    device.on(DEVICE.PIN_ON_DEVICE, pinOnDevice);
 
-    await device.unlockDevice();
+    await device.unlockDevice(DeviceSessionPinType.Main, { emitUiEvent: false });
 
+    expect(pinOnDevice).not.toHaveBeenCalled();
     expect(typedCall.mock.calls).toEqual([
       ['DeviceSessionAskPin', 'Success', { type: DeviceSessionPinType.Main }],
       ['DeviceStatusGet', 'DeviceStatus', {}],
@@ -4339,6 +4482,19 @@ describe('Protocol V2 firmware update targets', () => {
       )
     ).toBe(true);
 
+    (method.postProgressMessage as jest.Mock).mockClear();
+    expect(
+      (method as any).assertProtocolV2TargetStatus(
+        [
+          { target_id: 4, status: 'FW_MGMT_UPDATER_TASK_STATUS_FINISHED' },
+          { target_id: 4, status: 'FW_MGMT_UPDATER_TASK_STATUS_FINISHED' },
+        ],
+        new Set([4, 10])
+      )
+    ).toBe(false);
+    expect(method.postProgressMessage).toHaveBeenCalledWith(50, 'installingFirmware');
+    expect(method.postProgressMessage).not.toHaveBeenCalledWith(100, 'installingFirmware');
+
     expect(
       (method as any).assertProtocolV2TargetStatus([{ target_id: 4, status: 1 }], expectedTargetIds)
     ).toBe(false);
@@ -4944,7 +5100,7 @@ describe('Protocol V2 firmware update targets', () => {
     (method as any).captureProtocolV2PhysicalIdentity = jest.fn().mockResolvedValue(undefined);
 
     const order: string[] = [];
-    const resourceBinary = new Uint8Array([1, 2, 3]).buffer;
+    const resourceBinary = buildOkppHeader().buffer as ArrayBuffer;
     const getSysResourceBinarySpy = jest
       .spyOn(firmwareBinaryApi, 'getSysResourceBinary')
       .mockImplementation(() => {
@@ -5012,6 +5168,31 @@ describe('Protocol V2 firmware update targets', () => {
     getFirmwareLatestReleaseSpy.mockRestore();
   });
 
+  test('rejects a remote RESC bundle without an OKPP header when metadata is absent', async () => {
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+      },
+    });
+    const getSysResourceBinarySpy = jest
+      .spyOn(firmwareBinaryApi, 'getSysResourceBinary')
+      .mockResolvedValue({ binary: new Uint8Array([1, 2, 3]).buffer });
+
+    await expect(
+      (method as any).prefetchProtocolV2ResourceBundles([
+        {
+          name: 'images',
+          binary: new ArrayBuffer(0),
+          devicePath: 'vol0:/resource/images/images.okpkg',
+          url: 'https://example.com/images.okpkg',
+        },
+      ])
+    ).rejects.toThrow('Invalid Protocol V2 RESC bundle header: images');
+
+    getSysResourceBinarySpy.mockRestore();
+  });
+
   test('rejects an empty remote RESC bundle before entering bootloader', async () => {
     const method = new FirmwareUpdateV4({
       id: 1,
@@ -6012,311 +6193,230 @@ describe('Protocol V2 protected method execution', () => {
     expect(method.unlockPolicy).toBe('none');
   });
 
-  test('unlocks and retries an opted-in Protocol V2 method once', async () => {
+  test('checks fresh status for a wallet business method without a name allowlist', async () => {
     const calls: string[] = [];
+    const features = { unlocked: true };
     const method = {
-      name: 'testBusinessMethod',
-      unlockPolicy: 'retry-on-locked',
-      protocolV2UiInteraction: { reason: 'settings-page' },
-      run: jest
-        .fn()
-        .mockImplementationOnce(() => {
-          calls.push('run-1');
-          return Promise.reject(deviceLockedError());
-        })
-        .mockImplementationOnce(() => {
-          calls.push('run-2');
-          return Promise.resolve({ message: 'ok' });
-        }),
+      name: 'confluxSignMessageCIP23',
+      unlockPolicy: 'none',
+      useDevicePassphraseState: true,
+      protocolV2UiInteraction: { reason: 'address-confirmation' },
+      run: jest.fn(() => {
+        calls.push('run');
+        return Promise.resolve({ address: '0x1' });
+      }),
     };
     const device = {
+      features,
+      commands: {
+        typedCall: jest.fn(() => {
+          calls.push('status');
+          return Promise.resolve({ message: { unlocked: true } });
+        }),
+      },
       isProtocolV2: () => true,
-      unlockDevice: jest.fn(() => {
-        calls.push('unlock');
-        return Promise.resolve();
+      isBootloader: () => false,
+      isRomloader: () => false,
+      updateProtocolV2Status: jest.fn((status: { unlocked?: boolean }) => {
+        features.unlocked = status.unlocked === true;
+        return features;
       }),
+      unlockDevice: jest.fn(),
     };
     const uiCoordinator = {
       enterMethodInteraction: jest.fn(() => calls.push('method-prompt')),
-      enterUnlockInteraction: jest.fn(() => calls.push('unlock-prompt')),
-      resumeMethodInteraction: jest.fn(() => calls.push('method-prompt')),
+      enterUnlockInteraction: jest.fn(),
     };
 
     await expect(
-      runMethodWithUnlockRetry(method as any, device as any, uiCoordinator as any)
-    ).resolves.toEqual({ message: 'ok' });
-    expect(calls).toEqual([
-      'method-prompt',
-      'run-1',
-      'unlock-prompt',
-      'unlock',
-      'method-prompt',
-      'run-2',
-    ]);
+      runMethodWithUnlockPolicy(method as any, device as any, {
+        uiCoordinator: uiCoordinator as any,
+      })
+    ).resolves.toEqual({ address: '0x1' });
+
+    expect(calls).toEqual(['status', 'method-prompt', 'run']);
+    expect(device.commands.typedCall).toHaveBeenCalledWith('DeviceStatusGet', 'DeviceStatus', {});
+    expect(device.unlockDevice).not.toHaveBeenCalled();
+    expect(method.run).toHaveBeenCalledTimes(1);
   });
 
-  test('restores the expected hidden-wallet session before retrying after unlock', async () => {
+  test('validates the fresh device identity before starting unlock', async () => {
     const calls: string[] = [];
+    const identityError = new Error('Unexpected device');
     const method = {
       name: 'evmSignMessage',
-      payload: { passphraseState: 'hidden-state' },
+      unlockPolicy: 'none',
       useDevicePassphraseState: true,
-      unlockPolicy: 'retry-on-locked',
-      run: jest
-        .fn()
-        .mockImplementationOnce(() => {
-          calls.push('run-1');
-          return Promise.reject(deviceLockedError());
-        })
-        .mockImplementationOnce(() => {
-          calls.push('run-2');
-          return Promise.resolve({ message: 'ok' });
-        }),
+      run: jest.fn(),
     };
-    const typedCall = jest.fn((requestType: string, _responseType: string, request: any) => {
-      if (requestType === 'ProtocolInfoRequest') {
-        calls.push('negotiate-session');
-        return Promise.resolve({ message: { version: 2 } });
-      }
-      if (requestType === 'DeviceSessionGet') {
-        calls.push('resume-hidden-session');
-        expect(request).toEqual({ session_id: 'hidden-session' });
-        return Promise.resolve({
-          message: {
-            session_id: 'hidden-session',
-            btc_test_address: 'hidden-state',
-          },
-        });
-      }
-      throw new Error(`Unexpected request: ${requestType}`);
-    });
+    const features = { unlocked: false };
     const device = {
-      features: { unlocked: true, passphraseProtection: true },
-      passphraseState: 'hidden-state',
-      commands: { typedCall },
+      features,
+      commands: {
+        typedCall: jest.fn(() => {
+          calls.push('status');
+          return Promise.resolve({ message: { unlocked: false } });
+        }),
+      },
       isProtocolV2: () => true,
-      unlockDevice: jest.fn(() => {
-        calls.push('unlock');
-        return Promise.resolve();
-      }),
-      getCurrentPassphraseProtection: () => true,
-      getInternalState: () => 'hidden-session',
-      clearInternalState: jest.fn(),
-      getCurrentDeviceId: () => 'wallet-device-id',
-      updateInternalState: jest.fn(() => calls.push('validate-hidden-session')),
+      isBootloader: () => false,
+      isRomloader: () => false,
+      updateProtocolV2Status: jest.fn(() => features),
+      unlockDevice: jest.fn(),
     };
 
-    await expect(runMethodWithUnlockRetry(method as any, device as any)).resolves.toEqual({
-      message: 'ok',
-    });
-    expect(calls).toEqual([
-      'run-1',
-      'unlock',
-      'negotiate-session',
-      'resume-hidden-session',
-      'validate-hidden-session',
-      'run-2',
-    ]);
-  });
-
-  test('does not replay a business method when the hidden-wallet session cannot be restored after unlock', async () => {
-    const initialError = deviceLockedError();
-    const restoreError = new Error('Invalid wallet session');
-    const method = {
-      name: 'evmSignMessage',
-      payload: { passphraseState: 'hidden-state' },
-      useDevicePassphraseState: true,
-      unlockPolicy: 'retry-on-locked',
-      run: jest.fn().mockRejectedValueOnce(initialError),
-    };
-    const typedCall = jest.fn((requestType: string) => {
-      if (requestType === 'ProtocolInfoRequest') {
-        return Promise.resolve({ message: { version: 2 } });
-      }
-      if (requestType === 'DeviceSessionGet') {
-        return Promise.reject(restoreError);
-      }
-      throw new Error(`Unexpected request: ${requestType}`);
-    });
-    const device = {
-      features: { unlocked: true, passphraseProtection: true },
-      passphraseState: 'hidden-state',
-      commands: { typedCall },
-      isProtocolV2: () => true,
-      unlockDevice: jest.fn().mockResolvedValue(undefined),
-      getCurrentPassphraseProtection: () => true,
-      getInternalState: () => 'hidden-session',
-      clearInternalState: jest.fn(),
-      getCurrentDeviceId: () => 'wallet-device-id',
-      updateInternalState: jest.fn(),
-    };
+    await expect(
+      runMethodWithUnlockPolicy(method as any, device as any, {
+        afterStatusBeforeUnlock: () => {
+          calls.push('identity');
+          throw identityError;
+        },
+      })
+    ).rejects.toBe(identityError);
 
-    await expect(runMethodWithUnlockRetry(method as any, device as any)).rejects.toBe(restoreError);
-    expect(method.run).toHaveBeenCalledTimes(1);
-    expect(device.unlockDevice).toHaveBeenCalledTimes(1);
-    expect(device.clearInternalState).toHaveBeenCalledTimes(1);
-    expect(device.updateInternalState).not.toHaveBeenCalled();
+    expect(calls).toEqual(['status', 'identity']);
+    expect(device.unlockDevice).not.toHaveBeenCalled();
+    expect(method.run).not.toHaveBeenCalled();
   });
 
-  test('restores the expected hidden-wallet session after pre-unlock without selecting Attach PIN', async () => {
+  test('unlocks before business and never replays the callback', async () => {
     const calls: string[] = [];
+    const features = { unlocked: true };
     const method = {
       name: 'evmSignMessage',
-      payload: { passphraseState: 'hidden-state' },
-      useDevicePassphraseState: true,
-      unlockPolicy: 'retry-on-locked',
+      unlockPolicy: 'unlock-before-run',
+      protocolV2UiInteraction: { reason: 'signing-confirmation' },
       run: jest.fn(() => {
         calls.push('run');
-        return Promise.resolve({ message: 'ok' });
+        return Promise.resolve({ signature: 'signed' });
       }),
     };
-    const typedCall = jest.fn((requestType: string, _responseType: string, request: any) => {
-      if (requestType === 'ProtocolInfoRequest') {
-        calls.push('negotiate-session');
-        return Promise.resolve({ message: { version: 2 } });
-      }
-      if (requestType === 'DeviceSessionGet') {
-        calls.push('resume-hidden-session');
-        expect(request).toEqual({ session_id: 'hidden-session' });
-        return Promise.resolve({
-          message: {
-            session_id: 'hidden-session',
-            btc_test_address: 'hidden-state',
-          },
-        });
-      }
-      throw new Error(`Unexpected request: ${requestType}`);
-    });
-    const features = {
-      unlocked: false,
-      unlockedAttachPin: true,
-      passphraseProtection: true,
-    };
     const device = {
       features,
-      passphraseState: 'hidden-state',
-      commands: { typedCall },
+      commands: {
+        typedCall: jest.fn(() => {
+          calls.push('status');
+          return Promise.resolve({ message: { unlocked: false } });
+        }),
+      },
       isProtocolV2: () => true,
+      isBootloader: () => false,
+      isRomloader: () => false,
+      updateProtocolV2Status: jest.fn((status: { unlocked?: boolean }) => {
+        features.unlocked = status.unlocked === true;
+        return features;
+      }),
       unlockDevice: jest.fn(() => {
-        calls.push('unlock-main');
+        calls.push('unlock');
         features.unlocked = true;
-        features.unlockedAttachPin = false;
-        return Promise.resolve();
+        return Promise.resolve(features);
+      }),
+    };
+    const uiCoordinator = {
+      enterMethodInteraction: jest.fn(() => calls.push('method-prompt')),
+      enterUnlockInteraction: jest.fn(() => {
+        calls.push('unlock-prompt');
+        return undefined;
       }),
-      getCurrentPassphraseProtection: () => true,
-      getInternalState: () => 'hidden-session',
-      clearInternalState: jest.fn(),
-      getCurrentDeviceId: () => 'wallet-device-id',
-      updateInternalState: jest.fn(() => calls.push('validate-hidden-session')),
     };
 
-    await expect(runMethodWithUnlockRetry(method as any, device as any)).resolves.toEqual({
-      message: 'ok',
-    });
-    expect(device.unlockDevice).toHaveBeenCalledWith();
+    await expect(
+      runMethodWithUnlockPolicy(method as any, device as any, {
+        uiCoordinator: uiCoordinator as any,
+        prepare: () => {
+          calls.push('wallet-session');
+          return Promise.resolve();
+        },
+      })
+    ).resolves.toEqual({ signature: 'signed' });
+
     expect(calls).toEqual([
-      'unlock-main',
-      'negotiate-session',
-      'resume-hidden-session',
-      'validate-hidden-session',
+      'status',
+      'unlock-prompt',
+      'unlock',
+      'wallet-session',
+      'method-prompt',
       'run',
     ]);
+    expect(device.unlockDevice).toHaveBeenCalledTimes(1);
+    expect(method.run).toHaveBeenCalledTimes(1);
   });
 
-  test('does not restore a hidden-wallet session for a standard-wallet pre-unlock', async () => {
+  test('fails closed when fresh status does not explicitly report unlocked state', async () => {
     const method = {
       name: 'evmGetAddress',
-      payload: { useEmptyPassphrase: true },
-      useDevicePassphraseState: true,
-      unlockPolicy: 'retry-on-locked',
-      run: jest.fn().mockResolvedValue({ address: 'standard-wallet-address' }),
+      unlockPolicy: 'unlock-before-run',
+      run: jest.fn(),
     };
     const device = {
-      features: { unlocked: false },
-      passphraseState: 'stale-hidden-state',
+      features: { unlocked: undefined },
+      commands: { typedCall: jest.fn().mockResolvedValue({ message: {} }) },
       isProtocolV2: () => true,
-      unlockDevice: jest.fn().mockResolvedValue(undefined),
+      isBootloader: () => false,
+      isRomloader: () => false,
+      updateProtocolV2Status: jest.fn(() => ({ unlocked: undefined })),
+      unlockDevice: jest.fn(),
     };
 
-    await expect(runMethodWithUnlockRetry(method as any, device as any)).resolves.toEqual({
-      address: 'standard-wallet-address',
+    await expect(runMethodWithUnlockPolicy(method as any, device as any)).rejects.toMatchObject({
+      errorCode: HardwareErrorCode.RuntimeError,
     });
-    expect(device.unlockDevice).toHaveBeenCalledTimes(1);
-    expect(method.run).toHaveBeenCalledTimes(1);
+    expect(device.unlockDevice).not.toHaveBeenCalled();
+    expect(method.run).not.toHaveBeenCalled();
   });
 
-  test('refreshes status and unlocks before a protected Protocol V2 method', async () => {
-    const calls: string[] = [];
+  test('returns a business DeviceLocked error without unlocking or replaying', async () => {
+    const error = deviceLockedError();
     const method = {
-      name: 'deviceSettingsPageShow',
+      name: 'evmSignMessage',
       unlockPolicy: 'unlock-before-run',
-      protocolV2UiInteraction: { reason: 'settings-page' },
-      run: jest.fn(() => {
-        calls.push('run');
-        return Promise.resolve({ message: 'ok' });
-      }),
+      run: jest.fn().mockRejectedValue(error),
     };
     const features = { unlocked: true };
     const device = {
       features,
-      commands: {
-        typedCall: jest.fn(() => {
-          calls.push('refresh-status');
-          return Promise.resolve({ message: { unlocked: false } });
-        }),
-      },
+      commands: { typedCall: jest.fn().mockResolvedValue({ message: { unlocked: true } }) },
       isProtocolV2: () => true,
-      updateProtocolV2Status: jest.fn((status: { unlocked?: boolean }) => {
-        features.unlocked = status.unlocked ?? features.unlocked;
-        return features;
-      }),
-      unlockDevice: jest.fn(() => {
-        calls.push('unlock');
-        features.unlocked = true;
-        return Promise.resolve();
-      }),
-    };
-    const uiCoordinator = {
-      enterMethodInteraction: jest.fn(() => calls.push('method-prompt')),
-      enterUnlockInteraction: jest.fn(() => calls.push('unlock-prompt')),
-      resumeMethodInteraction: jest.fn(() => calls.push('method-prompt')),
+      isBootloader: () => false,
+      isRomloader: () => false,
+      updateProtocolV2Status: jest.fn(() => features),
+      unlockDevice: jest.fn(),
     };
 
-    await expect(
-      runMethodWithUnlockRetry(method as any, device as any, uiCoordinator as any)
-    ).resolves.toEqual({ message: 'ok' });
-    expect(calls).toEqual(['refresh-status', 'unlock-prompt', 'unlock', 'method-prompt', 'run']);
-    expect(device.commands.typedCall).toHaveBeenCalledWith('DeviceStatusGet', 'DeviceStatus', {});
+    await expect(runMethodWithUnlockPolicy(method as any, device as any)).rejects.toBe(error);
+    expect(device.unlockDevice).not.toHaveBeenCalled();
     expect(method.run).toHaveBeenCalledTimes(1);
-    expect(uiCoordinator.enterMethodInteraction).toHaveBeenCalledTimes(1);
-    expect(uiCoordinator.resumeMethodInteraction).not.toHaveBeenCalled();
   });
 
-  test('uses refreshed unlocked status instead of a stale locked cache', async () => {
-    const features = { unlocked: false };
-    const method = {
-      name: 'deviceSettings',
+  test('reuses one lightweight preflight context across nested protected methods', async () => {
+    const features = { unlocked: true };
+    const context = createProtocolV2UnlockContext();
+    const firstMethod = {
+      name: 'allNetworkGetAddress',
       unlockPolicy: 'unlock-before-run',
-      run: jest.fn().mockResolvedValue({ message: 'ok' }),
+      run: jest.fn().mockResolvedValue({ root: true }),
+    };
+    const nestedMethod = {
+      name: 'evmGetAddress',
+      unlockPolicy: 'unlock-before-run',
+      run: jest.fn().mockResolvedValue({ address: '0x1' }),
     };
     const device = {
       features,
-      commands: {
-        typedCall: jest.fn().mockResolvedValue({ message: { unlocked: true } }),
-      },
+      commands: { typedCall: jest.fn().mockResolvedValue({ message: { unlocked: true } }) },
       isProtocolV2: () => true,
-      updateProtocolV2Status: jest.fn((status: { unlocked?: boolean }) => {
-        features.unlocked = status.unlocked ?? features.unlocked;
-        return features;
-      }),
+      isBootloader: () => false,
+      isRomloader: () => false,
+      updateProtocolV2Status: jest.fn(() => features),
       unlockDevice: jest.fn(),
     };
 
-    await expect(runMethodWithUnlockRetry(method as any, device as any)).resolves.toEqual({
-      message: 'ok',
-    });
-    expect(device.unlockDevice).not.toHaveBeenCalled();
-    expect(method.run).toHaveBeenCalledTimes(1);
+    await runMethodWithUnlockPolicy(firstMethod as any, device as any, { context });
+    await runMethodWithUnlockPolicy(nestedMethod as any, device as any, { context });
+
+    expect(device.commands.typedCall).toHaveBeenCalledTimes(1);
+    expect(firstMethod.run).toHaveBeenCalledTimes(1);
+    expect(nestedMethod.run).toHaveBeenCalledTimes(1);
   });
 
   test.each(['bootloader', 'romloader'] as const)(
@@ -6336,7 +6436,7 @@ describe('Protocol V2 protected method execution', () => {
         unlockDevice: jest.fn(),
       };
 
-      await expect(runMethodWithUnlockRetry(method as any, device as any)).resolves.toEqual({
+      await expect(runMethodWithUnlockPolicy(method as any, device as any)).resolves.toEqual({
         message: 'updating',
       });
       expect(device.commands.typedCall).not.toHaveBeenCalled();
@@ -6345,157 +6445,30 @@ describe('Protocol V2 protected method execution', () => {
     }
   );
 
-  test('infers a signing interaction before running a Protocol V2 business method', async () => {
-    const method = {
-      name: 'evmSignMessage',
-      params: { message: 'not-exposed-in-event' },
-      payload: {},
-      unlockPolicy: 'retry-on-locked',
-      run: jest.fn().mockResolvedValue({ signature: 'test' }),
-    };
-    const device = {
-      isProtocolV2: () => true,
-      unlockDevice: jest.fn(),
-    };
-    const uiCoordinator = {
-      enterMethodInteraction: jest.fn(),
-      enterUnlockInteraction: jest.fn(),
-      resumeMethodInteraction: jest.fn(),
-    };
-
-    await runMethodWithUnlockRetry(method as any, device as any, uiCoordinator as any);
-
-    expect(uiCoordinator.enterMethodInteraction).toHaveBeenCalledWith({
-      request: 'button',
-      source: 'method-lifecycle',
-      reason: 'signing-confirmation',
-      completion: 'operation-completed',
-      deviceOnly: true,
-      operation: 'evmSignMessage',
-    });
-  });
-
-  test('does not unlock a Protocol V1 device or a method without the policy', async () => {
+  test('keeps Protocol V1 and lock-free methods outside the preflight path', async () => {
     for (const [isProtocolV2, unlockPolicy] of [
-      [false, 'retry-on-locked'],
+      [false, 'unlock-before-run'],
       [true, 'none'],
     ] as const) {
-      const error = deviceLockedError();
       const method = {
         unlockPolicy,
-        run: jest.fn().mockRejectedValue(error),
+        useDevicePassphraseState: false,
+        run: jest.fn().mockResolvedValue({ message: 'ok' }),
       };
       const device = {
+        commands: { typedCall: jest.fn() },
         isProtocolV2: () => isProtocolV2,
         unlockDevice: jest.fn(),
       };
 
-      await expect(runMethodWithUnlockRetry(method as any, device as any)).rejects.toBe(error);
+      await expect(runMethodWithUnlockPolicy(method as any, device as any)).resolves.toEqual({
+        message: 'ok',
+      });
+      expect(device.commands.typedCall).not.toHaveBeenCalled();
       expect(device.unlockDevice).not.toHaveBeenCalled();
       expect(method.run).toHaveBeenCalledTimes(1);
     }
   });
-
-  test('runs lock-free eventless methods without unlocking or synthesized UI', async () => {
-    const method = {
-      name: 'uploadPortfolio',
-      unlockPolicy: 'none',
-      protocolV2UiMode: 'none',
-      run: jest.fn().mockResolvedValue({ message: 'ok' }),
-    };
-    const device = {
-      features: { unlocked: false },
-      isProtocolV2: () => true,
-      unlockDevice: jest.fn().mockResolvedValue(undefined),
-    };
-    const uiCoordinator = {
-      enterMethodInteraction: jest.fn(),
-      enterUnlockInteraction: jest.fn(),
-      resumeMethodInteraction: jest.fn(),
-    };
-
-    await expect(
-      runMethodWithUnlockRetry(method as any, device as any, uiCoordinator as any)
-    ).resolves.toEqual({ message: 'ok' });
-    expect(device.unlockDevice).not.toHaveBeenCalled();
-    expect(uiCoordinator.enterMethodInteraction).not.toHaveBeenCalled();
-    expect(uiCoordinator.enterUnlockInteraction).not.toHaveBeenCalled();
-    expect(uiCoordinator.resumeMethodInteraction).not.toHaveBeenCalled();
-  });
-
-  test('does not unlock or replay a lock-free state-changing method after a locked response', async () => {
-    const error = deviceLockedError();
-    const method = {
-      name: 'uploadPortfolio',
-      unlockPolicy: 'none',
-      run: jest.fn().mockRejectedValue(error),
-    };
-    const device = {
-      features: { unlocked: true },
-      isProtocolV2: () => true,
-      unlockDevice: jest.fn(),
-    };
-
-    await expect(runMethodWithUnlockRetry(method as any, device as any)).rejects.toBe(error);
-    expect(method.run).toHaveBeenCalledTimes(1);
-    expect(device.unlockDevice).not.toHaveBeenCalled();
-  });
-
-  test('does not retry when unlock fails or when the retry is still locked', async () => {
-    const initialError = deviceLockedError();
-    const unlockError = new Error('PIN cancelled');
-    const unlockFailMethod = {
-      unlockPolicy: 'retry-on-locked',
-      run: jest.fn().mockRejectedValue(initialError),
-    };
-    const unlockFailDevice = {
-      isProtocolV2: () => true,
-      unlockDevice: jest.fn().mockRejectedValue(unlockError),
-    };
-    const unlockFailCoordinator = {
-      enterMethodInteraction: jest.fn(),
-      enterUnlockInteraction: jest.fn(),
-      resumeMethodInteraction: jest.fn(),
-    };
-
-    await expect(
-      runMethodWithUnlockRetry(
-        unlockFailMethod as any,
-        unlockFailDevice as any,
-        unlockFailCoordinator as any
-      )
-    ).rejects.toBe(unlockError);
-    expect(unlockFailMethod.run).toHaveBeenCalledTimes(1);
-    expect(unlockFailCoordinator.enterUnlockInteraction).toHaveBeenCalledTimes(1);
-    expect(unlockFailCoordinator.resumeMethodInteraction).not.toHaveBeenCalled();
-
-    const retryError = deviceLockedError();
-    const retryFailMethod = {
-      unlockPolicy: 'retry-on-locked',
-      run: jest.fn().mockRejectedValueOnce(initialError).mockRejectedValueOnce(retryError),
-    };
-    const retryFailDevice = {
-      isProtocolV2: () => true,
-      unlockDevice: jest.fn().mockResolvedValue(undefined),
-    };
-    const retryFailCoordinator = {
-      enterMethodInteraction: jest.fn(),
-      enterUnlockInteraction: jest.fn(),
-      resumeMethodInteraction: jest.fn(),
-    };
-
-    await expect(
-      runMethodWithUnlockRetry(
-        retryFailMethod as any,
-        retryFailDevice as any,
-        retryFailCoordinator as any
-      )
-    ).rejects.toBe(retryError);
-    expect(retryFailMethod.run).toHaveBeenCalledTimes(2);
-    expect(retryFailDevice.unlockDevice).toHaveBeenCalledTimes(1);
-    expect(retryFailCoordinator.enterUnlockInteraction).toHaveBeenCalledTimes(1);
-    expect(retryFailCoordinator.resumeMethodInteraction).toHaveBeenCalledTimes(1);
-  });
 });
 
 describe('Protocol V2 current low-level methods', () => {
@@ -6627,7 +6600,9 @@ describe('Protocol V2 current low-level methods', () => {
 
     await method.run();
 
-    expect(typedCall).toHaveBeenCalledWith('ProtocolInfoRequest', 'ProtocolInfo', {});
+    expect(typedCall).toHaveBeenCalledWith('ProtocolInfoRequest', 'ProtocolInfo', {
+      eventless_wallet_session: true,
+    });
   });
 
   test('sends DeviceFactoryInfoSet and DeviceFactoryInfoGet', async () => {