@onekeyfe/hd-transport-react-native 1.2.3-alpha.8 → 1.2.3

package/src/__tests__/androidKeyMissing.test.ts

@@ -0,0 +1,307 @@
+import EventEmitter from 'events';
+
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import ReactNativeBleTransport, {
+  ANDROID_KEY_MISSING_GRACE_MS,
+  ANDROID_KEY_MISSING_LINK_WINDOW_MS,
+} from '../index';
+import { SYSTEM_BONDING_RESTART_WINDOW_MS, onDeviceBondState } from '../BleManager';
+import { stopBleKeyMissingTracking } from '../bleKeyMissing';
+import protocolV1Schema from './protocolV1SchemaFixture';
+
+let mockKeyMissingSupported = true;
+let mockEmitKeyMissing: ((event: { id?: string }) => void) | undefined;
+let mockEmitBondState: ((peripheral: unknown) => void) | undefined;
+
+jest.mock(
+  'react-native',
+  () => ({
+    Platform: { OS: 'android', select: (spec: Record<string, unknown>) => spec.android },
+    PermissionsAndroid: {
+      PERMISSIONS: {},
+      RESULTS: {},
+      request: jest.fn(),
+      requestMultiple: jest.fn(),
+    },
+  }),
+  { virtual: true }
+);
+
+jest.mock('react-native-ble-plx', () => ({
+  BleATTErrorCode: { InvalidHandle: 1 },
+  BleError: Error,
+  BleErrorCode: { DeviceDisconnected: 201, OperationStartFailed: 601 },
+  BleManager: jest.fn(),
+  ScanMode: { LowLatency: 2 },
+}));
+
+jest.mock('@onekeyfe/react-native-ble-utils', () => ({
+  __esModule: true,
+  default: {
+    getConnectedPeripherals: jest.fn(() => Promise.resolve([])),
+    getBondedPeripherals: jest.fn(() => Promise.resolve([])),
+    pairDevice: jest.fn(() => Promise.resolve({ bonded: true, bonding: false })),
+    supportsDeviceKeyMissing: jest.fn(() => mockKeyMissingSupported),
+    onDeviceKeyMissing: jest.fn((callback: (event: { id?: string }) => void) => {
+      mockEmitKeyMissing = callback;
+      return () => {
+        mockEmitKeyMissing = undefined;
+      };
+    }),
+    onDeviceBondState: jest.fn((callback: (peripheral: unknown) => void) => {
+      mockEmitBondState = callback;
+      return () => {
+        mockEmitBondState = undefined;
+      };
+    }),
+  },
+}));
+
+const UUID = 'CC:06:1C:FD:48:E9';
+
+const flush = () =>
+  new Promise(resolve => {
+    setImmediate(resolve);
+  });
+
+const advance = async (ms: number) => {
+  jest.advanceTimersByTime(ms);
+  await flush();
+};
+
+// What ble-plx reports when the device drops the link while the first write is queued.
+const peerTerminated = () =>
+  Promise.reject(
+    Object.assign(new Error(`Device ${UUID} was disconnected`), {
+      errorCode: 201,
+      attErrorCode: 19,
+      reason: 'Disconnected with status 19 (GATT_CONN_TERMINATE_PEER_USER)',
+    })
+  );
+
+function createConnectedTransport(linkAgeMs = 0) {
+  const t = new ReactNativeBleTransport({});
+  t.configure(protocolV1Schema);
+  (t as any).deviceProtocol.set(UUID, 'V1');
+  (t as any).getCachedTransport = () => ({
+    writeCharacteristic: { writeWithoutResponse: jest.fn(peerTerminated) },
+  });
+  (t as any).androidLinkStartedAt.set(UUID, Date.now() - linkAgeMs);
+  return t;
+}
+
+const settle = (promise: Promise<unknown>) => {
+  const outcome: { error?: { errorCode?: unknown }; done: boolean } = { done: false };
+  promise.then(
+    () => {
+      outcome.done = true;
+    },
+    error => {
+      outcome.error = error;
+      outcome.done = true;
+    }
+  );
+  return outcome;
+};
+
+describe('Android key missing', () => {
+  beforeEach(() => {
+    jest.useFakeTimers({ doNotFake: ['setImmediate', 'performance'] });
+    mockKeyMissingSupported = true;
+  });
+
+  afterEach(() => {
+    stopBleKeyMissingTracking();
+    jest.clearAllTimers();
+    jest.useRealTimers();
+  });
+
+  describe('link dropped right after connect', () => {
+    test('reports an invalid bond when the system says the keys are missing', async () => {
+      const outcome = settle(createConnectedTransport().call(UUID, 'GetFeatures', {}));
+      await flush();
+      // The broadcast is delivered separately and can trail the GATT disconnect.
+      mockEmitKeyMissing?.({ id: UUID.toLowerCase() });
+      await flush();
+
+      expect(outcome.error?.errorCode).toBe(HardwareErrorCode.BleBondInvalid);
+    });
+
+    test('keeps the original error when no key missing follows', async () => {
+      const outcome = settle(createConnectedTransport().call(UUID, 'GetFeatures', {}));
+      await flush();
+      expect(outcome.done).toBe(false);
+
+      await advance(ANDROID_KEY_MISSING_GRACE_MS);
+
+      expect(outcome.error?.errorCode).toBe(HardwareErrorCode.BleDeviceNotBonded);
+    });
+
+    test('ignores key missing reported for an earlier link', async () => {
+      const transport = createConnectedTransport();
+      const earlier = settle(transport.call(UUID, 'GetFeatures', {}));
+      await flush();
+      mockEmitKeyMissing?.({ id: UUID });
+      await flush();
+      expect(earlier.error?.errorCode).toBe(HardwareErrorCode.BleBondInvalid);
+
+      // The user re-paired; a later link that drops is an ordinary disconnect.
+      await advance(1000);
+      (transport as any).androidLinkStartedAt.set(UUID, Date.now());
+      const later = settle(transport.call(UUID, 'GetFeatures', {}));
+      await flush();
+      await advance(ANDROID_KEY_MISSING_GRACE_MS);
+
+      expect(later.error?.errorCode).toBe(HardwareErrorCode.BleDeviceNotBonded);
+    });
+
+    test('ignores key missing for another device', async () => {
+      const outcome = settle(createConnectedTransport().call(UUID, 'GetFeatures', {}));
+      await flush();
+      mockEmitKeyMissing?.({ id: 'E9:B9:F4:DD:DE:CD' });
+      await advance(ANDROID_KEY_MISSING_GRACE_MS);
+
+      expect(outcome.error?.errorCode).toBe(HardwareErrorCode.BleDeviceNotBonded);
+    });
+
+    test('does not wait on a link that has been up for a while', async () => {
+      const transport = createConnectedTransport(ANDROID_KEY_MISSING_LINK_WINDOW_MS + 1);
+      const outcome = settle(transport.call(UUID, 'GetFeatures', {}));
+      await flush();
+
+      expect(outcome.error?.errorCode).toBe(HardwareErrorCode.BleDeviceNotBonded);
+    });
+
+    test('does not wait when the OS or native build never reports key missing', async () => {
+      mockKeyMissingSupported = false;
+      const outcome = settle(createConnectedTransport().call(UUID, 'GetFeatures', {}));
+      await flush();
+
+      expect(outcome.error?.errorCode).toBe(HardwareErrorCode.BleDeviceNotBonded);
+    });
+  });
+
+  describe('acquire over a bond the device no longer holds', () => {
+    // Android still reports BONDED, so connect, MTU and GATT setup all succeed and the
+    // protocol probe is the first operation to meet the dropped link.
+    function createStaleBondHarness() {
+      const writeCharacteristic = {
+        uuid: '00000002-0000-1000-8000-00805f9b34fb',
+        isWritableWithoutResponse: true,
+        writeWithoutResponse: jest.fn(peerTerminated),
+      };
+      const notifyCharacteristic = {
+        uuid: '00000003-0000-1000-8000-00805f9b34fb',
+        isNotifiable: true,
+        monitor: jest.fn(() => ({ remove: jest.fn() })),
+      };
+      const device = {
+        id: UUID,
+        name: 'Pro 2 48E9',
+        localName: 'Pro 2 48E9',
+        mtu: 247,
+        serviceUUIDs: ['00000001-0000-1000-8000-00805f9b34fb'],
+        isConnected: jest.fn(() => Promise.resolve(true)),
+        cancelConnection: jest.fn(() => Promise.resolve()),
+        discoverAllServicesAndCharacteristics: jest.fn(() => Promise.resolve()),
+        characteristicsForService: jest.fn(() =>
+          Promise.resolve([writeCharacteristic, notifyCharacteristic])
+        ),
+        services: jest.fn(() => Promise.resolve([])),
+        onDisconnected: jest.fn(() => ({ remove: jest.fn() })),
+      };
+      const transport = new ReactNativeBleTransport({});
+      (transport as any).blePlxManager = {
+        devices: jest.fn(() => Promise.resolve([device])),
+        connectedDevices: jest.fn(() => Promise.resolve([])),
+        cancelTransaction: jest.fn(() => Promise.resolve()),
+        cancelDeviceConnection: jest.fn(() => Promise.resolve()),
+        onStateChange: jest.fn((listener: (state: string) => void) => {
+          setImmediate(() => listener('PoweredOn'));
+          return { remove: jest.fn() };
+        }),
+        state: jest.fn(() => Promise.resolve('PoweredOn')),
+      };
+      transport.init(
+        { debug: jest.fn(), error: jest.fn(), warn: jest.fn() } as any,
+        new EventEmitter()
+      );
+      transport.configure(protocolV1Schema);
+      return { transport, write: writeCharacteristic.writeWithoutResponse };
+    }
+
+    async function acquireUntilSettled(keyMissing: boolean) {
+      const { transport, write } = createStaleBondHarness();
+      const outcome = settle(transport.acquire({ uuid: UUID }));
+      for (let i = 0; i < 100 && !outcome.done; i += 1) {
+        // eslint-disable-next-line no-await-in-loop
+        await advance(100);
+        // The broadcast follows the dropped link, which the probe write is first to meet.
+        if (keyMissing && write.mock.calls.length > 0) mockEmitKeyMissing?.({ id: UUID });
+      }
+      expect(write).toHaveBeenCalled();
+      return JSON.parse(JSON.stringify(ERRORS.serializeError({ error: outcome.error })));
+    }
+
+    test('ends as an invalid bond that survives the Core response path', async () => {
+      await expect(acquireUntilSettled(true)).resolves.toEqual({
+        code: HardwareErrorCode.BleBondInvalid,
+        error: expect.stringContaining('Forget the device'),
+        params: { phase: 'connect', reason: 'key_missing' },
+      });
+    });
+
+    test('keeps the legacy error when the system reports nothing', async () => {
+      await expect(acquireUntilSettled(false)).resolves.toMatchObject({
+        code: HardwareErrorCode.BleDeviceNotBonded,
+      });
+    });
+  });
+
+  describe('waiting for bonding', () => {
+    const bondState = (preState: string, state: string) =>
+      mockEmitBondState?.({ id: UUID, bondState: { preState, state } });
+
+    test('fails as an invalid bond when the system re-pair ends in key missing', async () => {
+      const outcome = settle(onDeviceBondState(UUID, undefined, { systemInitiated: true }));
+      mockEmitKeyMissing?.({ id: UUID });
+      await flush();
+
+      expect(outcome.error?.errorCode).toBe(HardwareErrorCode.BleBondInvalid);
+    });
+
+    test('follows a system re-pair that replaces the bond', async () => {
+      const outcome = settle(onDeviceBondState(UUID, undefined, { systemInitiated: true }));
+      bondState('BOND_BONDING', 'BOND_NONE');
+      bondState('BOND_NONE', 'BOND_BONDING');
+      await advance(SYSTEM_BONDING_RESTART_WINDOW_MS);
+      expect(outcome.done).toBe(false);
+
+      bondState('BOND_BONDING', 'BOND_BONDED');
+      await flush();
+
+      expect(outcome.done).toBe(true);
+      expect(outcome.error).toBeUndefined();
+    });
+
+    test('fails a system re-pair that ends without a bond', async () => {
+      const outcome = settle(onDeviceBondState(UUID, undefined, { systemInitiated: true }));
+      bondState('BOND_BONDING', 'BOND_NONE');
+      await flush();
+      expect(outcome.done).toBe(false);
+
+      await advance(SYSTEM_BONDING_RESTART_WINDOW_MS);
+
+      expect(outcome.error?.errorCode).toBe(HardwareErrorCode.BleDeviceNotBonded);
+    });
+
+    test('fails a bonding this transport started as soon as it ends without a bond', async () => {
+      const outcome = settle(onDeviceBondState(UUID));
+      bondState('BOND_BONDING', 'BOND_NONE');
+      await flush();
+
+      expect(outcome.error?.errorCode).toBe(HardwareErrorCode.BleDeviceNotBonded);
+    });
+  });
+});

package/src/__tests__/enumerate.test.ts

@@ -25,6 +25,21 @@ jest.mock('../BleManager', () => ({
   pairDevice: jest.fn(),
 }));
 
+// The native facade is replaced wholesale above; key missing and link encryption are covered
+// by their own suites.
+jest.mock('../bleKeyMissing', () => ({
+  isBleKeyMissingSupported: jest.fn(() => false),
+  startBleKeyMissingTracking: jest.fn(() => false),
+  stopBleKeyMissingTracking: jest.fn(),
+  waitForBleKeyMissing: jest.fn(() => Promise.resolve(false)),
+}));
+jest.mock('../bleEncryption', () => ({
+  markBleLinkEncrypted: jest.fn(),
+  startBleEncryptionTracking: jest.fn(() => false),
+  stopBleEncryptionTracking: jest.fn(),
+  waitForAndroidLinkEncryption: jest.fn(() => Promise.resolve('unresolved')),
+}));
+
 jest.mock('../subscribeBleOn', () => ({
   subscribeBleOn: jest.fn(() => Promise.resolve()),
 }));

package/src/__tests__/protocolV2Link.test.ts

@@ -45,6 +45,21 @@ jest.mock('../BleManager', () => ({
   pairDevice: jest.fn(() => Promise.resolve({ bonded: true, bonding: false })),
 }));
 
+// The native facade is replaced wholesale above; key missing and link encryption are covered
+// by their own suites.
+jest.mock('../bleKeyMissing', () => ({
+  isBleKeyMissingSupported: jest.fn(() => false),
+  startBleKeyMissingTracking: jest.fn(() => false),
+  stopBleKeyMissingTracking: jest.fn(),
+  waitForBleKeyMissing: jest.fn(() => Promise.resolve(false)),
+}));
+jest.mock('../bleEncryption', () => ({
+  markBleLinkEncrypted: jest.fn(),
+  startBleEncryptionTracking: jest.fn(() => false),
+  stopBleEncryptionTracking: jest.fn(),
+  waitForAndroidLinkEncryption: jest.fn(() => Promise.resolve('unresolved')),
+}));
+
 jest.mock('../subscribeBleOn', () => ({
   subscribeBleOn: jest.fn(() => Promise.resolve()),
 }));

package/src/bleEncryption.ts

@@ -0,0 +1,267 @@
+import { Platform } from 'react-native';
+import BleUtils from '@onekeyfe/react-native-ble-utils';
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import {
+  hasBleKeyMissingSince,
+  onBleKeyMissing,
+  startBleKeyMissingTracking,
+} from './bleKeyMissing';
+
+/**
+ * Android 16+ starts encrypting a bonded LE link on its own right after connecting, with the
+ * stored key. A GATT request that needs encryption and is sent before that attempt finishes is
+ * rejected by the peer, and the framework retries it by encrypting again with the same key. When
+ * the peer has lost the bond, that second failure makes firmware that tolerates a single one per
+ * link drop the connection, before the system's own re-pairing can finish.
+ *
+ * Tracking the link's encryption result lets the transport hold GATT until then, so a lost bond
+ * is re-paired in place (the system shows a pairing request) instead of failing.
+ */
+
+/** HCI "PIN or Key Missing": the peer no longer has the keys of the stored bond. */
+export const HCI_PIN_OR_KEY_MISSING = 0x06;
+
+export type AndroidLinkEncryption =
+  /** This link was encrypted with the stored bond. */
+  | 'encrypted'
+  /** The link was reused and had already been encrypted. */
+  | 'already-encrypted'
+  /** The stored bond was lost and the system re-paired on this link. */
+  | 're-paired'
+  /** No result arrived in time; callers proceed as if nothing was known. */
+  | 'unresolved';
+
+type EncryptionRecord = { at: number; status: number; enabled: boolean };
+
+// An app can still resolve an older react-native-ble-utils, and the JS bundle can run on a native
+// build that predates the events, so none of these members is assumed to exist.
+type EncryptionCapableBleUtils = Partial<
+  Pick<
+    typeof BleUtils,
+    'supportsDeviceEncryptionChange' | 'onDeviceEncryptionChange' | 'onDeviceAclDisconnected'
+  >
+>;
+
+type LinkListener = (deviceId: string) => void;
+
+const lastEncryption = new Map<string, EncryptionRecord>();
+const lastAclDisconnectAt = new Map<string, number>();
+const listeners = new Set<LinkListener>();
+let unsubscribeNative: Array<() => void> | undefined;
+
+const normalizeDeviceId = (deviceId: string) => deviceId.toLowerCase();
+
+const isEncrypted = (record: EncryptionRecord) => record.status === 0 && record.enabled;
+
+const getCapableBleUtils = (): EncryptionCapableBleUtils | undefined => {
+  if (Platform.OS !== 'android') return undefined;
+  const bleUtils: EncryptionCapableBleUtils = BleUtils;
+  if (
+    typeof bleUtils.supportsDeviceEncryptionChange !== 'function' ||
+    typeof bleUtils.onDeviceEncryptionChange !== 'function' ||
+    typeof bleUtils.onDeviceAclDisconnected !== 'function'
+  ) {
+    return undefined;
+  }
+  return bleUtils.supportsDeviceEncryptionChange() ? bleUtils : undefined;
+};
+
+const notify = (deviceId: string) => {
+  listeners.forEach(listener => listener(deviceId));
+};
+
+/** False means the encryption result can never be observed here, so nothing should wait for it. */
+export const isBleEncryptionTrackingSupported = () => getCapableBleUtils() !== undefined;
+
+/** Idempotent. Returns whether encryption results are observable on this OS and native build. */
+export const startBleEncryptionTracking = (): boolean => {
+  if (unsubscribeNative) return true;
+  const bleUtils = getCapableBleUtils();
+  if (!bleUtils?.onDeviceEncryptionChange || !bleUtils.onDeviceAclDisconnected) return false;
+
+  unsubscribeNative = [
+    bleUtils.onDeviceEncryptionChange(event => {
+      if (typeof event?.id !== 'string') return;
+      const deviceId = normalizeDeviceId(event.id);
+      lastEncryption.set(deviceId, {
+        at: Date.now(),
+        status: Number(event.status),
+        enabled: event.enabled === true,
+      });
+      notify(deviceId);
+    }),
+    bleUtils.onDeviceAclDisconnected(event => {
+      if (typeof event?.id !== 'string') return;
+      const deviceId = normalizeDeviceId(event.id);
+      lastAclDisconnectAt.set(deviceId, Date.now());
+      notify(deviceId);
+    }),
+  ];
+  return true;
+};
+
+export const stopBleEncryptionTracking = () => {
+  unsubscribeNative?.forEach(unsubscribe => unsubscribe());
+  unsubscribeNative = undefined;
+  lastEncryption.clear();
+  lastAclDisconnectAt.clear();
+  listeners.clear();
+};
+
+/**
+ * Records a link that carried requests needing encryption, so reusing it later does not wait for
+ * an encryption result that was reported before tracking started.
+ */
+export const markBleLinkEncrypted = (deviceId: string) => {
+  if (!unsubscribeNative) return;
+  lastEncryption.set(normalizeDeviceId(deviceId), { at: Date.now(), status: 0, enabled: true });
+};
+
+export type WaitForAndroidLinkEncryptionOptions = {
+  deviceId: string;
+  /** When the current link attempt began; earlier results describe another link. */
+  linkStartedAt: number;
+  /** How long to wait for the first encryption result of this link. */
+  resultTimeoutMs: number;
+  /** How long a system re-pairing may take once the stored bond was reported lost. */
+  repairTimeoutMs: number;
+  /** After the link drops during re-pairing, how long to wait for the key-missing report. */
+  keyMissingGraceMs: number;
+  signal?: AbortSignal;
+  onRepairStarted?: () => void;
+};
+
+/**
+ * Resolves once the link can carry requests that need encryption. Rejects with `BleBondInvalid`
+ * when the system reports that re-pairing failed, with `BleDeviceDisconnected` when the link drops
+ * during re-pairing, and with `BleDeviceNotBonded` when re-pairing does not finish in time.
+ */
+export const waitForAndroidLinkEncryption = ({
+  deviceId,
+  linkStartedAt,
+  resultTimeoutMs,
+  repairTimeoutMs,
+  keyMissingGraceMs,
+  signal,
+  onRepairStarted,
+}: WaitForAndroidLinkEncryptionOptions): Promise<AndroidLinkEncryption> => {
+  if (!startBleEncryptionTracking()) return Promise.resolve('unresolved');
+  startBleKeyMissingTracking();
+  const target = normalizeDeviceId(deviceId);
+
+  const previous = lastEncryption.get(target);
+  const previousDropAt = lastAclDisconnectAt.get(target);
+  if (
+    previous &&
+    previous.at < linkStartedAt &&
+    isEncrypted(previous) &&
+    (previousDropAt === undefined || previousDropAt < previous.at)
+  ) {
+    return Promise.resolve('already-encrypted');
+  }
+
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(ERRORS.TypedError(HardwareErrorCode.BleDeviceDisconnected));
+      return;
+    }
+
+    /** Set once this link's first encryption failed because the peer lost the bond. */
+    let repairStartedAt: number | undefined;
+    let droppedDuringRepair = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let settled = false;
+
+    const cleanup = () => {
+      settled = true;
+      if (timer) clearTimeout(timer);
+      listeners.delete(onLinkEvent);
+      cleanupKeyMissing();
+      signal?.removeEventListener('abort', onAbort);
+    };
+    const finish = (result: AndroidLinkEncryption) => {
+      cleanup();
+      resolve(result);
+    };
+    const fail = (error: Error) => {
+      cleanup();
+      reject(error);
+    };
+    const arm = (ms: number, onExpire: () => void) => {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(onExpire, ms);
+    };
+    const bondInvalid = () =>
+      ERRORS.TypedError(HardwareErrorCode.BleBondInvalid, undefined, {
+        phase: 'connect',
+        reason: 'key_missing',
+      });
+
+    const evaluate = () => {
+      if (settled) return;
+      const record = lastEncryption.get(target);
+      const dropAt = lastAclDisconnectAt.get(target);
+
+      if (repairStartedAt === undefined) {
+        if (hasBleKeyMissingSince(target, linkStartedAt)) {
+          fail(bondInvalid());
+          return;
+        }
+        if (dropAt !== undefined && dropAt >= linkStartedAt) {
+          // The link is gone; the caller's next request reports it with its usual error.
+          finish('unresolved');
+          return;
+        }
+        if (!record || record.at < linkStartedAt) return;
+        if (isEncrypted(record)) {
+          finish('encrypted');
+          return;
+        }
+        if (record.status !== HCI_PIN_OR_KEY_MISSING) {
+          finish('unresolved');
+          return;
+        }
+        // The system re-pairs on its own after a lost bond. Nothing may touch GATT until then.
+        repairStartedAt = record.at;
+        onRepairStarted?.();
+        arm(repairTimeoutMs, () =>
+          fail(
+            ERRORS.TypedError(HardwareErrorCode.BleDeviceNotBonded, 'Bluetooth pairing timed out', {
+              phase: 'bond',
+              reason: 'timeout',
+            })
+          )
+        );
+        return;
+      }
+
+      if (hasBleKeyMissingSince(target, repairStartedAt)) {
+        fail(bondInvalid());
+        return;
+      }
+      if (record && record.at > repairStartedAt && isEncrypted(record)) {
+        finish('re-paired');
+        return;
+      }
+      if (!droppedDuringRepair && dropAt !== undefined && dropAt >= repairStartedAt) {
+        droppedDuringRepair = true;
+        // A failed re-pairing drops the link and reports key missing right after.
+        arm(keyMissingGraceMs, () =>
+          fail(ERRORS.TypedError(HardwareErrorCode.BleDeviceDisconnected))
+        );
+      }
+    };
+
+    const onLinkEvent: LinkListener = id => {
+      if (id === target) evaluate();
+    };
+    const onAbort = () => fail(ERRORS.TypedError(HardwareErrorCode.BleDeviceDisconnected));
+
+    listeners.add(onLinkEvent);
+    const cleanupKeyMissing = onBleKeyMissing(target, evaluate);
+    signal?.addEventListener('abort', onAbort, { once: true });
+    arm(resultTimeoutMs, () => finish('unresolved'));
+    evaluate();
+  });
+};