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

package/src/bleKeyMissing.ts

@@ -0,0 +1,106 @@
+import { Platform } from 'react-native';
+import BleUtils from '@onekeyfe/react-native-ble-utils';
+
+/**
+ * Android 16+ keeps its side of a bond the device no longer has keys for, and reports it
+ * with ACTION_KEY_MISSING instead of a GATT status. The device then drops the link, so
+ * without this signal a wiped device is indistinguishable from any other disconnect.
+ *
+ * The signal only describes the link that was being encrypted when it fired. Callers must
+ * bound it to their own connection attempt with `sinceMs`; reusing an older one would turn
+ * an ordinary disconnect (a firmware-update reboot, for example) into a terminal bond error.
+ */
+
+// An app can still resolve a react-native-ble-utils older than 0.1.8, and the JS bundle can
+// run on a native build that predates the event, so neither method is assumed to exist.
+type KeyMissingCapableBleUtils = Partial<
+  Pick<typeof BleUtils, 'supportsDeviceKeyMissing' | 'onDeviceKeyMissing'>
+>;
+
+type KeyMissingListener = (deviceId: string) => void;
+
+const lastKeyMissingAt = new Map<string, number>();
+const listeners = new Set<KeyMissingListener>();
+let unsubscribeNative: (() => void) | undefined;
+
+const normalizeDeviceId = (deviceId: string) => deviceId.toLowerCase();
+
+const getCapableBleUtils = (): KeyMissingCapableBleUtils | undefined => {
+  if (Platform.OS !== 'android') return undefined;
+  const bleUtils: KeyMissingCapableBleUtils = BleUtils;
+  if (
+    typeof bleUtils.supportsDeviceKeyMissing !== 'function' ||
+    typeof bleUtils.onDeviceKeyMissing !== 'function'
+  ) {
+    return undefined;
+  }
+  return bleUtils.supportsDeviceKeyMissing() ? bleUtils : undefined;
+};
+
+/** False means the event can never fire here, so nothing should wait for it. */
+export const isBleKeyMissingSupported = () => getCapableBleUtils() !== undefined;
+
+/** Idempotent. Returns whether the signal is available on this OS and native build. */
+export const startBleKeyMissingTracking = (): boolean => {
+  if (unsubscribeNative) return true;
+  const bleUtils = getCapableBleUtils();
+  if (!bleUtils?.onDeviceKeyMissing) return false;
+
+  unsubscribeNative = bleUtils.onDeviceKeyMissing(event => {
+    if (typeof event?.id !== 'string') return;
+    const deviceId = normalizeDeviceId(event.id);
+    lastKeyMissingAt.set(deviceId, Date.now());
+    listeners.forEach(listener => listener(deviceId));
+  });
+  return true;
+};
+
+export const stopBleKeyMissingTracking = () => {
+  unsubscribeNative?.();
+  unsubscribeNative = undefined;
+  lastKeyMissingAt.clear();
+  listeners.clear();
+};
+
+export const hasBleKeyMissingSince = (deviceId: string, sinceMs: number): boolean => {
+  const at = lastKeyMissingAt.get(normalizeDeviceId(deviceId));
+  return at !== undefined && at >= sinceMs;
+};
+
+/** Calls back for every later signal on this device until the returned cleanup runs. */
+export const onBleKeyMissing = (deviceId: string, callback: () => void): (() => void) => {
+  const target = normalizeDeviceId(deviceId);
+  const listener: KeyMissingListener = id => {
+    if (id === target) callback();
+  };
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+/**
+ * Resolves true once a signal at or after `sinceMs` exists for the device, false when
+ * none arrives within `timeoutMs`. The broadcast and the GATT disconnect it explains are
+ * delivered on separate paths, so the disconnect can reach JS first.
+ */
+export const waitForBleKeyMissing = (
+  deviceId: string,
+  sinceMs: number,
+  timeoutMs: number
+): Promise<boolean> => {
+  if (!startBleKeyMissingTracking()) return Promise.resolve(false);
+  if (hasBleKeyMissingSince(deviceId, sinceMs)) return Promise.resolve(true);
+
+  return new Promise(resolve => {
+    const settle = (found: boolean) => {
+      clearTimeout(timer);
+      cleanup();
+      resolve(found);
+    };
+    const cleanup = onBleKeyMissing(deviceId, () => {
+      if (hasBleKeyMissingSince(deviceId, sinceMs)) settle(true);
+    });
+    const timer = setTimeout(() => settle(false), timeoutMs);
+  });
+};

package/src/index.ts

@@ -47,6 +47,18 @@ import {
   getInfosForServiceUuid,
   isSameBleUuid,
 } from './constants';
+import {
+  isBleKeyMissingSupported,
+  startBleKeyMissingTracking,
+  stopBleKeyMissingTracking,
+  waitForBleKeyMissing,
+} from './bleKeyMissing';
+import {
+  markBleLinkEncrypted,
+  startBleEncryptionTracking,
+  stopBleEncryptionTracking,
+  waitForAndroidLinkEncryption,
+} from './bleEncryption';
 import { isNativeBleDisconnectError, toBleDisconnectHardwareError } from './bleNativeDisconnect';
 import {
   isBleStaleBondHardwareError,
@@ -62,6 +74,7 @@ import type { Deferred } from '@onekeyfe/hd-shared';
 import type { Characteristic, Device, Subscription } from 'react-native-ble-plx';
 import type EventEmitter from 'events';
 import type { BleAcquireInput, TransportOptions } from './types';
+import type { AndroidLinkEncryption } from './bleEncryption';
 
 type FirmwareInstallBleAcquireInput = BleAcquireInput & {
   /**
@@ -188,6 +201,38 @@ const shouldRethrowProtocolProbeError = (error: unknown): boolean => {
     code === HardwareErrorCode.BleWriteCharacteristicError
   );
 };
+/**
+ * Android reports a lost bond (ACTION_KEY_MISSING) while it encrypts a new link, so only
+ * a failure this soon after the link started can be explained by it. Later disconnects,
+ * such as a firmware-update reboot, must keep their own meaning.
+ */
+export const ANDROID_KEY_MISSING_LINK_WINDOW_MS = 10_000;
+/** The broadcast and the GATT disconnect it explains travel separately; either can land first. */
+export const ANDROID_KEY_MISSING_GRACE_MS = 500;
+/**
+ * Android reports a bonded link's first encryption result within about half a second of
+ * connecting. Past this, the result is treated as unknown and the link is used as before.
+ */
+export const ANDROID_ENCRYPTION_RESULT_TIMEOUT_MS = 1500;
+/**
+ * A system re-pairing needs the user to accept a pairing request and confirm the code on the
+ * device. The Bluetooth stack gives up after 30s and then reports key missing.
+ */
+export const ANDROID_SYSTEM_REPAIR_TIMEOUT_MS = 35_000;
+/**
+ * How a link dropped by a device that refuses a stale bond reaches JS. A wedged write is
+ * excluded: the system is still re-pairing then and has not reported key missing yet.
+ */
+const isAndroidLinkLossError = (error: unknown): boolean => {
+  const code = (error as { errorCode?: unknown })?.errorCode;
+  return (
+    isNativeBleDisconnectError(error) ||
+    code === HardwareErrorCode.BleDeviceNotBonded ||
+    code === HardwareErrorCode.BleDeviceDisconnected ||
+    code === HardwareErrorCode.BleCharacteristicNotifyError ||
+    code === HardwareErrorCode.BleConnectedError
+  );
+};
 /** Consecutive wedged writes on one device before the BLE manager itself is recreated. */
 export const BLE_WRITE_TIMEOUT_MANAGER_RESET_THRESHOLD = 2;
 const DEVICE_SCAN_TIMEOUT_MS = 3000;
@@ -540,6 +585,9 @@ export default class ReactNativeBleTransport {
    */
   private staleBondErrors: Map<string, Error> = new Map();
 
+  /** When the current Android link attempt began; bounds which key-missing signals apply. */
+  private androidLinkStartedAt: Map<string, number> = new Map();
+
   /** Strict or previously confirmed V2 target while acquire installs notifications. */
   private acquiringProtocolV2 = new Set<string>();
 
@@ -604,6 +652,11 @@ export default class ReactNativeBleTransport {
   init(logger: any, emitter: EventEmitter) {
     setBleLogger(logger);
     this.emitter = emitter;
+    if (Platform.OS === 'android') {
+      // Link security events are only meaningful if they were observed since the link came up.
+      startBleKeyMissingTracking();
+      startBleEncryptionTracking();
+    }
   }
 
   configure(signedData: any) {
@@ -1055,7 +1108,13 @@ export default class ReactNativeBleTransport {
       throw ERRORS.TypedError(HardwareErrorCode.BleRequiredUUID);
     }
 
-    return this.runLifecycleOperation(uuid, () => this.acquireUnlocked(input));
+    return this.runLifecycleOperation(uuid, async () => {
+      try {
+        return await this.acquireUnlocked(input);
+      } catch (error) {
+        throw await this.resolveAndroidBondInvalid(uuid, error);
+      }
+    });
   }
 
   private async acquireUnlocked(input: FirmwareInstallBleAcquireInput) {
@@ -1135,6 +1194,8 @@ export default class ReactNativeBleTransport {
 
     let device: Device | null = null;
     const isAndroid = Platform.OS === 'android';
+    // Only a bond that existed before this acquire can have been lost by the device.
+    let androidBondedBeforeConnect = false;
     // A firmware-install reconnect always refreshes: the new firmware may expose a different table.
     const refreshAndroidGattCache =
       isAndroid && (!!skipProtocolProbe || this.androidGattCacheRefreshes.has(uuid));
@@ -1166,11 +1227,19 @@ export default class ReactNativeBleTransport {
 
     if (this.stopped) throw ERRORS.TypedError(HardwareErrorCode.BleDeviceDisconnected);
     if (Platform.OS === 'android') {
+      // Subscribe before the link exists: key missing is broadcast while Android encrypts it.
+      startBleKeyMissingTracking();
+      startBleEncryptionTracking();
+      // Failures before the new link starts must not be read against the previous link.
+      this.androidLinkStartedAt.delete(uuid);
       // Initiate bonding locally before GATT can trigger peripheral-initiated pairing.
       try {
         const bondState = await pairDevice(uuid);
+        androidBondedBeforeConnect = !bondState.bonding && bondState.bonded;
         if (bondState.bonding) {
-          await onDeviceBondState(uuid, this.bondAbortController.signal);
+          await onDeviceBondState(uuid, this.bondAbortController.signal, {
+            systemInitiated: bondState.initiated === false,
+          });
         } else if (!bondState.bonded) {
           throw ERRORS.TypedError(HardwareErrorCode.BleDeviceNotBonded, 'device is not bonded');
         }
@@ -1182,6 +1251,7 @@ export default class ReactNativeBleTransport {
         });
         throw error;
       }
+      this.androidLinkStartedAt.set(uuid, Date.now());
     }
     if (this.stopped) throw ERRORS.TypedError(HardwareErrorCode.BleDeviceDisconnected);
 
@@ -1369,7 +1439,13 @@ export default class ReactNativeBleTransport {
       this.acquiringProtocolV2.add(uuid);
     }
 
+    let linkEncryption: AndroidLinkEncryption | undefined;
     try {
+      // A firmware-install reconnect keeps its existing sequence.
+      if (androidBondedBeforeConnect && !skipProtocolProbe) {
+        linkEncryption = await this.waitForAndroidLinkSecurity(uuid);
+        if (this.stopped) throw ERRORS.TypedError(HardwareErrorCode.BleDeviceDisconnected);
+      }
       await this.installTransportForAcquire(uuid, acquiredDevice, {
         writeCharacteristic,
         notifyCharacteristic,
@@ -1421,6 +1497,11 @@ export default class ReactNativeBleTransport {
         throw ERRORS.TypedError(HardwareErrorCode.TransportNotFound);
       }
       this.attachDisconnectSubscription(currentTransport, currentTransport.device, uuid);
+      if (linkEncryption === 'unresolved') {
+        // Notifications and the probe only work on an encrypted link, so the next reuse of this
+        // link needs no result that was reported before tracking started.
+        markBleLinkEncrypted(uuid);
+      }
       return { uuid, protocolType };
     } catch (error) {
       // A failed acquire must retire the physical link before Core retries. Logical
@@ -1689,16 +1770,77 @@ export default class ReactNativeBleTransport {
         `Device protocol has not been detected for ${uuid}`
       );
     }
-    if (protocol === 'V2') {
-      return this.callProtocolV2(uuid, name, data, options);
-    }
-
     const forceRun = name === 'Initialize' || name === 'Cancel';
-    if (this.runPromise && !forceRun) {
+    if (protocol !== 'V2' && this.runPromise && !forceRun) {
       throw ERRORS.TypedError(HardwareErrorCode.TransportCallInProgress);
     }
 
-    return this.callProtocolV1(uuid, name, data, options);
+    try {
+      return protocol === 'V2'
+        ? await this.callProtocolV2(uuid, name, data, options)
+        : await this.callProtocolV1(uuid, name, data, options);
+    } catch (error) {
+      // An expected-V1 acquire skips the probe, so the first call is what meets the dropped link.
+      throw await this.resolveAndroidBondInvalid(uuid, error);
+    }
+  }
+
+  /**
+   * Android 16+ keeps a bond the device no longer holds keys for. The device drops the link
+   * and the only structured evidence is ACTION_KEY_MISSING, so a link loss right after
+   * connect is re-read as an invalid bond when that signal belongs to the same attempt.
+   */
+  private async resolveAndroidBondInvalid(uuid: string, error: unknown): Promise<unknown> {
+    if (Platform.OS !== 'android' || !isBleKeyMissingSupported()) return error;
+    if (isBleStaleBondHardwareError(error) || !isAndroidLinkLossError(error)) return error;
+    const linkStartedAt = this.androidLinkStartedAt.get(uuid);
+    if (
+      linkStartedAt === undefined ||
+      Date.now() - linkStartedAt > ANDROID_KEY_MISSING_LINK_WINDOW_MS
+    ) {
+      return error;
+    }
+    if (!(await waitForBleKeyMissing(uuid, linkStartedAt, ANDROID_KEY_MISSING_GRACE_MS))) {
+      return error;
+    }
+    Log?.debug('[ReactNativeBleTransport] Android key missing, bond is invalid:', uuid);
+    return ERRORS.TypedError(HardwareErrorCode.BleBondInvalid, undefined, {
+      phase: 'connect',
+      reason: 'key_missing',
+    });
+  }
+
+  /**
+   * Android 16+ encrypts a bonded link on its own right after connecting. Subscribing to
+   * notifications before that finishes gets the CCCD write rejected, and the framework's retry
+   * encrypts again with the same stale key; firmware that allows one failure per link then drops
+   * it before the system can re-pair. Holding GATT until the result lets a lost bond be re-paired
+   * in place. Without the platform signal this resolves immediately.
+   */
+  private async waitForAndroidLinkSecurity(uuid: string): Promise<AndroidLinkEncryption> {
+    const linkStartedAt = this.androidLinkStartedAt.get(uuid);
+    if (linkStartedAt === undefined) return 'unresolved';
+    const waitStartedAt = Date.now();
+    const result = await waitForAndroidLinkEncryption({
+      deviceId: uuid,
+      linkStartedAt,
+      resultTimeoutMs: ANDROID_ENCRYPTION_RESULT_TIMEOUT_MS,
+      repairTimeoutMs: ANDROID_SYSTEM_REPAIR_TIMEOUT_MS,
+      keyMissingGraceMs: ANDROID_KEY_MISSING_GRACE_MS,
+      signal: this.bondAbortController.signal,
+      onRepairStarted: () => {
+        Log?.debug(
+          '[ReactNativeBleTransport] Android bond lost, waiting for system re-pairing:',
+          uuid
+        );
+      },
+    });
+    Log?.debug('[ReactNativeBleTransport] Android link encryption', {
+      connectIdSuffix: uuid.slice(-8),
+      result,
+      waitedMs: Date.now() - waitStartedAt,
+    });
+    return result;
   }
 
   private async callProtocolV1(
@@ -1966,6 +2108,9 @@ export default class ReactNativeBleTransport {
     this.androidPriorityResetTimers.forEach(timeout => clearTimeout(timeout));
     this.androidPriorityResetTimers.clear();
     this.androidHighPriorityDevices.clear();
+    this.androidLinkStartedAt.clear();
+    stopBleKeyMissingTracking();
+    stopBleEncryptionTracking();
     const error = ERRORS.TypedError(HardwareErrorCode.BleDeviceDisconnected);
     this.runPromise?.reject(error);
     this.runPromise = null;