@onekeyfe/hwk-desktop-noble-ble 1.2.3-alpha.2

package/dist/index.d.ts

@@ -0,0 +1,357 @@
+import { ElectronBleScanOptions, ElectronBleConnectOptions } from '@onekeyfe/hwk-adapter-core';
+export { THIRD_PARTY_BLE_CHANNELS, THIRD_PARTY_BLE_DEVICE_TTL_MS, THIRD_PARTY_BLE_POWER_ON_TIMEOUT_MS, THIRD_PARTY_BLE_SCAN_DURATION_MS, THIRD_PARTY_BLE_SCAN_IDLE_STOP_MS, ThirdPartyBleChannel } from './constants.js';
+
+type BleDebugLogLevel = 'debug' | 'info' | 'warn' | 'error';
+type BleDebugLogEntry = {
+    level: BleDebugLogLevel;
+    scope: string;
+    event: string;
+    data?: Record<string, unknown>;
+};
+type BleDebugLogger = (entry: BleDebugLogEntry) => void;
+/** Replace sensitive values in place; everything else is forwarded verbatim. */
+declare function redactBleDebugLogData(data?: Record<string, unknown>): Record<string, unknown> | undefined;
+
+/**
+ * Shape of the API the renderer process talks to. In a real Electron app
+ * this is normally exposed via `contextBridge.exposeInMainWorld('desktopApi',
+ * { trezorBle: ... })`, but the transport accepts the bridge directly so
+ * non-Electron hosts (and unit tests) can plug in their own implementation.
+ */
+interface ThirdPartyBleDeviceInfo {
+    /** Stable id (noble peripheral.id) used as connectId. */
+    id: string;
+    name?: string;
+    rssi?: number;
+    advertisedServiceUuids?: string[];
+    /** Same as `name`, kept explicit to mirror noble's `advertisement.localName`. */
+    localName?: string;
+    /** Whether the peripheral advertised itself as connectable. */
+    isConnectable?: boolean | null;
+    serviceSolicitationUuids?: string[];
+    txPowerLevel?: number;
+    /** Manufacturer-specific advertisement data, hex-encoded (may embed a serial). */
+    manufacturerDataHex?: string;
+    /** Per-service advertisement data, each hex-encoded. */
+    serviceData?: Array<{
+        uuid: string;
+        dataHex: string;
+    }>;
+    /** BLE MAC/address when the OS exposes it separately from `id`. */
+    address?: string;
+    addressType?: string;
+    /** noble peripheral connection state at scan time. */
+    state?: string;
+}
+interface ThirdPartyBleAvailability {
+    available: boolean;
+    /** noble state: `poweredOn` / `poweredOff` / `unauthorized` / `unsupported` / `resetting` / `unknown`. */
+    state: string;
+    initialized: boolean;
+}
+/** One definition of the scan contract; the IPC shape lives in adapter-core. */
+type ThirdPartyBleScanOptions = ElectronBleScanOptions;
+interface ThirdPartyBleApi {
+    scan(options?: ThirdPartyBleScanOptions): Promise<ThirdPartyBleDeviceInfo[]>;
+    stopScan(): Promise<void>;
+    connect(id: string, options: ElectronBleConnectOptions): Promise<{
+        id: string;
+        name?: string;
+    }>;
+    disconnect(id: string): Promise<void>;
+    /** Subscribe to the BLE notify characteristic for `id`. */
+    subscribe(id: string): Promise<void>;
+    unsubscribe(id: string): Promise<void>;
+    /**
+     * Write an already-framed payload. The main process applies the framing rule
+     * recorded at connect time — splitting and zero-padding for `padded`, or
+     * writing the buffer as given for `raw`.
+     */
+    write(id: string, hexData: string): Promise<void>;
+    checkAvailability(): Promise<ThirdPartyBleAvailability>;
+    /** Look up a previously-scanned device by id without re-scanning. */
+    getDevice(id: string): Promise<ThirdPartyBleDeviceInfo | null>;
+    /** Read current RSSI (dBm) of a *connected* peripheral. */
+    readRssi(id: string): Promise<number>;
+    /** Stop scan + disconnect every in-flight connection. */
+    cancelPairing(): Promise<void>;
+    /** Register a listener for incoming BLE notifications. Returns an unsubscribe fn. */
+    onNotification(handler: (id: string, hexData: string) => void): () => void;
+    /** Register a listener for unexpected disconnects. Returns an unsubscribe fn. */
+    onDeviceDisconnected(handler: (id: string) => void): () => void;
+}
+
+/**
+ * Subset of @stoprocent/noble we touch. We type as `any` to keep the package
+ * installable without the native module — it's loaded lazily inside main().
+ */
+interface NobleLike {
+    state: string;
+    on(event: string, handler: (...args: any[]) => void): NobleLike;
+    removeListener(event: string, handler: (...args: any[]) => void): NobleLike;
+    startScanningAsync(serviceUuids: string[], allowDuplicates: boolean): Promise<void>;
+    stopScanningAsync(): Promise<void>;
+    stop?(): void;
+    /**
+     * Connect by id/address with NO scan. Both native backends support this and
+     * emit a `discover` for the peripheral as a side effect: Windows synthesizes
+     * one for an unknown address (`BLEManager::Connect`, lib/win/src/ble_manager.cc)
+     * and macOS resolves it via `retrievePeripheralsWithIdentifiers`
+     * (lib/mac/src/ble_manager.mm). Optional so a stub noble can omit it.
+     */
+    connectAsync?(idOrAddress: string): Promise<NoblePeripheralLike | undefined>;
+    cancelConnect?(idOrAddress: string): void;
+    reset?(): Promise<void>;
+}
+interface NoblePeripheralLike {
+    id: string;
+    advertisement: {
+        localName?: string;
+        serviceUuids?: string[];
+        manufacturerData?: Buffer;
+        serviceData?: Array<{
+            uuid: string;
+            data: Buffer;
+        }>;
+        txPowerLevel?: number;
+        serviceSolicitationUuids?: string[];
+    };
+    /** Some noble builds expose the BLE MAC/address separately from `id`. */
+    address?: string;
+    addressType?: string;
+    connectable?: boolean;
+    rssi: number;
+    state: string;
+    connectAsync(): Promise<void>;
+    cancelConnect?(): void;
+    disconnectAsync(): Promise<void>;
+    discoverSomeServicesAndCharacteristicsAsync(serviceUuids: string[], characteristicUuids: string[]): Promise<{
+        characteristics: NobleCharacteristicLike[];
+    }>;
+    /** Read live RSSI from the connected peripheral. Returns dBm. */
+    updateRssiAsync?(): Promise<number>;
+    on(event: string, handler: (...args: any[]) => void): NoblePeripheralLike;
+    removeListener(event: string, handler: (...args: any[]) => void): NoblePeripheralLike;
+}
+interface NobleCharacteristicLike {
+    uuid: string;
+    subscribeAsync(): Promise<void>;
+    unsubscribeAsync(): Promise<void>;
+    writeAsync(data: Buffer, withoutResponse: boolean): Promise<void>;
+    on(event: 'data', handler: (data: Buffer, isNotification: boolean) => void): NobleCharacteristicLike;
+    removeListener(event: 'data', handler: (data: Buffer, isNotification: boolean) => void): NobleCharacteristicLike;
+}
+type NobleFactory = () => NobleLike;
+interface NobleBleHandlerOptions {
+    /** Override for tests; defaults to `require('@stoprocent/noble')`. */
+    nobleFactory?: NobleFactory;
+    /** Override the overall connect timeout (tests only; defaults to 31s). */
+    connectTimeoutMs?: number;
+    logger?: BleDebugLogger;
+}
+/**
+ * Core BLE logic, decoupled from Electron's IPC layer so it can be unit
+ * tested with a fake noble. Mirrors the OneKey `noble-ble-handler.ts`
+ * pattern (a single class that owns the peripheral cache + disconnect
+ * callbacks), but trimmed to the minimum surface we expose.
+ */
+declare class NobleBleHandler {
+    private _noble;
+    private readonly _factory;
+    private readonly _connectTimeoutMs;
+    private readonly _logger?;
+    private readonly _discovered;
+    private readonly _lastSeen;
+    private readonly _connected;
+    private _discoverHandler?;
+    private _scanning;
+    private _idleStopTimer?;
+    private _onNotification?;
+    private _onDeviceDisconnected?;
+    private _initialized;
+    private _disposed;
+    private _disposePromise?;
+    private _releasePromise?;
+    private _initPromise?;
+    private readonly _nobleInstances;
+    private readonly _pendingCancellations;
+    private readonly _connectAttempts;
+    private _nativeReleased;
+    private _lastNobleRecoverAt?;
+    /** The connect currently in flight, so cancelPairing can abandon it. */
+    private _activeConnect?;
+    constructor(options?: NobleBleHandlerOptions);
+    setNotificationListener(handler: (id: string, hexData: string) => void): void;
+    setDisconnectedListener(handler: (id: string) => void): void;
+    init(): Promise<void>;
+    checkAvailability(): Promise<ThirdPartyBleAvailability>;
+    /**
+     * Lazy-start a continuous scan and return the current snapshot immediately.
+     *
+     * Scans UNFILTERED and applies the caller's match criteria in `_snapshot()` instead. A
+     * service-UUID filter cannot be used here: noble's Windows backend applies it
+     * per RECEIVED PACKET (`BLEManager::OnScanResult`, lib/win/src/ble_manager.cc),
+     * and a Safe 7's ADV packet carries only its name — the service UUID lives in
+     * the scan response, which arrives as a separate, irregularly-timed event. So
+     * a filtered scan drops every ADV packet and the device appears to be
+     * undiscoverable for minutes at a time while it is plainly on air. (OneKey's
+     * own devices do advertise their service UUID, which is why the same filter is
+     * safe in `hd-transport-electron` and was copied here by mistake.)
+     */
+    scan(options?: ElectronBleScanOptions): Promise<ThirdPartyBleDeviceInfo[]>;
+    /**
+     * Current in-range devices for the asking vendor, dropping any that aged past
+     * the liveness TTL. The match test replaces the service-UUID scan filter we cannot use
+     * (see `scan`): it matches the name from the ADV packet, or the service UUID
+     * once a scan response has merged into the same peripheral.
+     *
+     * Note the TTL only prunes what the CALLER sees. `_discovered` is a cache, not
+     * the source of truth for reachability — a device missing from here can still
+     * be connected to by id (`_directConnect`).
+     */
+    private _snapshot;
+    /** A noble instance with its own bindings, so a stuck one can be replaced. */
+    private _createFreshNoble;
+    /**
+     * Rebuild noble when its adapter state is stuck. Re-enumerating the Windows
+     * BLE stack (pairing, or removing the device from OS settings) can catch
+     * noble's RadioWatcher mid-churn: it latches `unsupported` and never
+     * re-evaluates, so every later scan fails until the process restarts. Fresh
+     * bindings restart that watcher, which is the in-process equivalent of the
+     * app restart that is otherwise the only cure.
+     */
+    private _recoverNobleIfStuck;
+    private _armIdleStop;
+    private _clearIdleStop;
+    /** Stop scanning but keep the discovered cache (used before connect). */
+    private _pauseScan;
+    /** Stop scanning and forget discovered devices (idle timeout / teardown). */
+    private _stopContinuousScan;
+    /**
+     * Stops the process-wide scan no matter which vendor asked. Scan *results*
+     * are filtered per vendor, but the radio is not: one vendor's stopScan ends
+     * the other's discovery too. That is safe only because the adapter job queue
+     * serializes discovery across vendors, so two are never scanning at once.
+     * Anything that breaks that — a background presence probe, say — needs
+     * per-vendor refcounting here first.
+     */
+    stopScan(): Promise<void>;
+    /**
+     * Look up a previously-scanned device by id (no extra BLE traffic).
+     * Returns null if the device hasn't been seen by a recent scan.
+     */
+    getDevice(id: string): ThirdPartyBleDeviceInfo | null;
+    /**
+     * Read the current RSSI (in dBm) for a connected peripheral. Requires
+     * the device to be connected — noble can't read RSSI off a scan-only
+     * peripheral. Falls back to the cached scan-time rssi when the noble
+     * peripheral doesn't expose updateRssiAsync.
+     */
+    readRssi(id: string): Promise<number>;
+    /**
+     * Abort the in-flight pairing flow: abandon a connect that is still running,
+     * stop scanning, disconnect every peripheral the host currently has open.
+     * Caller is responsible for surfacing the cancellation to the upper UI layer.
+     *
+     * Abandoning the connect is what actually ends the flow. Pairing happens
+     * inside connectAsync and the entry only reaches _connected after service
+     * discovery, so the loop below never sees the device being paired — without
+     * the abandon the caller waits out the full connect timeout, which is sized
+     * to the OS pairing window and so feels like a hang.
+     */
+    cancelPairing(): Promise<void>;
+    /**
+     * Scan for a specific peripheral id and resolve THE MOMENT it's discovered,
+     * stopping the scan immediately (don't wait out the full window). The fast
+     * reconnect path for a stored connectId when the device IS advertising.
+     *
+     * This used to be the only reconnect path, on two assumptions that are both
+     * false: that noble cannot connect by id without a scan (it can — see
+     * `_directConnect`), and that "the device advertises continuously" (a bonded
+     * Safe 7 does not — it holds the link and goes silent). Callers must fall
+     * back to `_directConnect` when this returns undefined.
+     */
+    private _scanUntilFound;
+    /**
+     * Connect by id with no scan and no advertisement.
+     *
+     * This is the ONLY path that reaches a device which is connected but silent.
+     * A linked peripheral stops advertising while it HOLDS A LINK (standard BLE; a Safe 7's
+     * screen says "wait connection") — field-verified: bonding/THP handshake
+     * alone does NOT silence it, holding the connection does. So while a link is
+     * up, no amount of scanning will rediscover it — `_scanUntilFound` alone
+     * dead-ends with "device not found" on a device that is sitting right there,
+     * connected and reachable.
+     *
+     * noble supports this: `noble.connectAsync(id)` needs no prior `discover`,
+     * because both native backends materialize the peripheral themselves (Windows
+     * synthesizes one for an unknown address, macOS retrieves it by identifier)
+     * and then emit a `discover`, which our own handler turns back into a
+     * `_discovered` entry. OneKey's own noble handler calls this "direct
+     * connection mode"; Trezor Suite's equivalent is asking the adapter for its
+     * peripheral list instead of keeping a cache.
+     *
+     * Returns undefined (not throw) so the caller reports the normal
+     * "device not found" rather than a confusing noble-internal error.
+     */
+    private _directConnect;
+    private _safeDisconnect;
+    connect(id: string, options: ElectronBleConnectOptions): Promise<{
+        id: string;
+        name?: string;
+    }>;
+    private _connectInner;
+    disconnect(id: string): Promise<void>;
+    subscribe(id: string): Promise<void>;
+    unsubscribe(id: string): Promise<void>;
+    write(id: string, hexData: string): Promise<void>;
+    /** Retire a renderer's handler without stopping a process-wide native manager. */
+    dispose(): Promise<void>;
+    /**
+     * Terminal native release, including instances replaced by adapter recovery.
+     * A host sharing Noble must defer stop() until all transports have disposed,
+     * and deduplicate instances passed to releaseNoble across those transports.
+     */
+    disposeForAppQuit(releaseNoble?: (instance: {
+        stop?(): void;
+    }) => void): Promise<void>;
+    private _assertActive;
+    private _cleanupDevice;
+    private _requireEntry;
+    private _requireNoble;
+    private _waitForPoweredOn;
+    private _log;
+}
+
+/** Minimal slice of Electron's `WebContents` we use (kept duck-typed so we
+ * don't take a hard dep on `electron`). */
+interface WebContentsLike {
+    send(channel: string, ...args: unknown[]): void;
+    on?(event: string, listener: (...args: any[]) => void): void;
+}
+/** Minimal slice of Electron's `ipcMain` we use. */
+interface IpcMainLike {
+    handle(channel: string, listener: (event: unknown, ...args: any[]) => Promise<unknown> | unknown): void;
+    removeHandler(channel: string): void;
+}
+interface InitThirdPartyBleSupportOptions extends NobleBleHandlerOptions {
+    /** Inject your own `ipcMain` (defaults to `require('electron').ipcMain`). */
+    ipcMain?: IpcMainLike;
+}
+interface ThirdPartyBleSupportHandle {
+    handler: NobleBleHandler;
+    dispose(): Promise<void>;
+    disposeForAppQuit(releaseNoble?: (instance: {
+        stop?(): void;
+    }) => void): Promise<void>;
+}
+/**
+ * Wire a `NobleBleHandler` to Electron's IPC so the renderer can drive BLE
+ * via `window.desktopApi.trezorBle`. Call once from the main process after
+ * `BrowserWindow` is ready.
+ *
+ * Call dispose() when retiring a renderer and disposeForAppQuit() before Node teardown.
+ */
+declare function initThirdPartyBleSupport(webContents: WebContentsLike, options?: InitThirdPartyBleSupportOptions): ThirdPartyBleSupportHandle;
+
+export { type BleDebugLogEntry, type BleDebugLogLevel, type BleDebugLogger, type InitThirdPartyBleSupportOptions, type IpcMainLike, NobleBleHandler, type NobleBleHandlerOptions, type ThirdPartyBleApi, type ThirdPartyBleAvailability, type ThirdPartyBleDeviceInfo, type ThirdPartyBleSupportHandle, initThirdPartyBleSupport, redactBleDebugLogData };