@matter-server/ble-proxy 0.0.1

package/dist/esm/BleProxyProtocol.js

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const BLE_PROXY_PROTOCOL_VERSION = 1;
+const BleProxyCommand = {
+  StartScan: "start_scan",
+  StopScan: "stop_scan",
+  Connect: "connect",
+  Disconnect: "disconnect",
+  DiscoverServices: "discover_services",
+  DiscoverCharacteristics: "discover_characteristics",
+  ReadCharacteristic: "read_characteristic",
+  WriteCharacteristic: "write_characteristic",
+  SubscribeCharacteristic: "subscribe_characteristic",
+  UnsubscribeCharacteristic: "unsubscribe_characteristic",
+  RequestMtu: "request_mtu"
+};
+const BleProxyEvent = {
+  DeviceDiscovered: "device_discovered",
+  Disconnected: "disconnected",
+  ScanStopped: "scan_stopped",
+  CharacteristicNotification: "characteristic_notification"
+};
+const BleProxyErrorCode = {
+  BluetoothUnavailable: "bluetooth_unavailable",
+  AlreadyScanning: "already_scanning",
+  NotScanning: "not_scanning",
+  DeviceNotFound: "device_not_found",
+  ConnectionFailed: "connection_failed",
+  AlreadyConnected: "already_connected",
+  NotConnected: "not_connected",
+  Timeout: "timeout",
+  ServiceNotFound: "service_not_found",
+  CharacteristicNotFound: "characteristic_not_found",
+  ReadFailed: "read_failed",
+  WriteFailed: "write_failed",
+  SubscribeFailed: "subscribe_failed",
+  NotSubscribed: "not_subscribed",
+  NotifyNotSupported: "notify_not_supported",
+  MtuRequestFailed: "mtu_request_failed",
+  DiscoveryFailed: "discovery_failed",
+  InternalError: "internal_error"
+};
+const BinaryFrameOpcode = {
+  /** Server -> Client: write payload to the active write characteristic */
+  WriteData: 1,
+  /** Client -> Server: notification data from a subscribed characteristic */
+  Notification: 2,
+  /** Client -> Server: response data for a read_characteristic command */
+  ReadResponse: 3
+};
+const BINARY_FRAME_HEADER_SIZE = 3;
+function encodeBinaryFrame(opcode, connectionHandle, payload) {
+  const frame = new Uint8Array(BINARY_FRAME_HEADER_SIZE + payload.length);
+  frame[0] = opcode & 255;
+  frame[1] = connectionHandle >> 8 & 255;
+  frame[2] = connectionHandle & 255;
+  frame.set(payload, BINARY_FRAME_HEADER_SIZE);
+  return frame;
+}
+function decodeBinaryFrame(data) {
+  if (data.length < BINARY_FRAME_HEADER_SIZE) {
+    throw new Error(`Binary frame too short: ${data.length} bytes, minimum ${BINARY_FRAME_HEADER_SIZE}`);
+  }
+  return {
+    opcode: data[0],
+    connectionHandle: data[1] << 8 | data[2],
+    payload: data.subarray(BINARY_FRAME_HEADER_SIZE)
+  };
+}
+export {
+  BLE_PROXY_PROTOCOL_VERSION,
+  BinaryFrameOpcode,
+  BleProxyCommand,
+  BleProxyErrorCode,
+  BleProxyEvent,
+  decodeBinaryFrame,
+  encodeBinaryFrame
+};
+//# sourceMappingURL=BleProxyProtocol.js.map

package/dist/esm/BleProxyProtocol.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../src/BleProxyProtocol.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAaO,MAAM,6BAA6B;AAoBnC,MAAM,kBAAkB;AAAA,EAC3B,WAAW;AAAA,EACX,UAAU;AAAA,EACV,SAAS;AAAA,EACT,YAAY;AAAA,EACZ,kBAAkB;AAAA,EAClB,yBAAyB;AAAA,EACzB,oBAAoB;AAAA,EACpB,qBAAqB;AAAA,EACrB,yBAAyB;AAAA,EACzB,2BAA2B;AAAA,EAC3B,YAAY;AAChB;AAMO,MAAM,gBAAgB;AAAA,EACzB,kBAAkB;AAAA,EAClB,cAAc;AAAA,EACd,aAAa;AAAA,EACb,4BAA4B;AAChC;AA+JO,MAAM,oBAAoB;AAAA,EAC7B,sBAAsB;AAAA,EACtB,iBAAiB;AAAA,EACjB,aAAa;AAAA,EACb,gBAAgB;AAAA,EAChB,kBAAkB;AAAA,EAClB,kBAAkB;AAAA,EAClB,cAAc;AAAA,EACd,SAAS;AAAA,EACT,iBAAiB;AAAA,EACjB,wBAAwB;AAAA,EACxB,YAAY;AAAA,EACZ,aAAa;AAAA,EACb,iBAAiB;AAAA,EACjB,eAAe;AAAA,EACf,oBAAoB;AAAA,EACpB,kBAAkB;AAAA,EAClB,iBAAiB;AAAA,EACjB,eAAe;AACnB;AAMO,MAAM,oBAAoB;AAAA;AAAA,EAE7B,WAAW;AAAA;AAAA,EAEX,cAAc;AAAA;AAAA,EAEd,cAAc;AAClB;AAaA,MAAM,2BAA2B;AAQ1B,SAAS,kBAAkB,QAAgB,kBAA0B,SAAiC;AACzG,QAAM,QAAQ,IAAI,WAAW,2BAA2B,QAAQ,MAAM;AACtE,QAAM,CAAC,IAAI,SAAS;AACpB,QAAM,CAAC,IAAK,oBAAoB,IAAK;AACrC,QAAM,CAAC,IAAI,mBAAmB;AAC9B,QAAM,IAAI,SAAS,wBAAwB;AAC3C,SAAO;AACX;AAEO,SAAS,kBAAkB,MAA+B;AAC7D,MAAI,KAAK,SAAS,0BAA0B;AACxC,UAAM,IAAI,MAAM,2BAA2B,KAAK,MAAM,mBAAmB,wBAAwB,EAAE;AAAA,EACvG;AACA,SAAO;AAAA,IACH,QAAQ,KAAK,CAAC;AAAA,IACd,kBAAmB,KAAK,CAAC,KAAK,IAAK,KAAK,CAAC;AAAA,IACzC,SAAS,KAAK,SAAS,wBAAwB;AAAA,EACnD;AACJ;",
+  "names": []
+}

package/dist/esm/ProxyBle.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type Environment, type Transport } from "@matter/main";
+import { Ble, type BlePeripheralInterface, type Scanner } from "@matter/main/protocol";
+import type { BleProxyHandler } from "./BleProxyHandler.js";
+/**
+ * BLE implementation that proxies all operations over a WebSocket connection.
+ * Replaces NodeJsBle for environments where BLE hardware is accessed through
+ * a remote proxy client (e.g. Home Assistant with ESPHome BLE proxies).
+ *
+ * Only central (client) mode is supported. Peripheral mode throws.
+ */
+export declare class ProxyBle extends Ble {
+    #private;
+    constructor(handler: BleProxyHandler, environment?: Environment);
+    get peripheralInterface(): BlePeripheralInterface;
+    get centralInterface(): Transport;
+    get scanner(): Scanner;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=ProxyBle.d.ts.map

package/dist/esm/ProxyBle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProxyBle.d.ts","sourceRoot":"","sources":["../../src/ProxyBle.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAuB,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AACrF,OAAO,EAAE,GAAG,EAAE,KAAK,sBAAsB,EAAE,KAAK,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAK5D;;;;;;GAMG;AACH,qBAAa,QAAS,SAAQ,GAAG;;IAO7B,YAAY,OAAO,EAAE,eAAe,EAAE,WAAW,CAAC,EAAE,WAAW,EAM9D;IAED,IAAI,mBAAmB,IAAI,sBAAsB,CAEhD;IAED,IAAI,gBAAgB,IAAI,SAAS,CAKhC;IAED,IAAI,OAAO,IAAI,OAAO,CAQrB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAM3B;CACJ"}

package/dist/esm/ProxyBle.js

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ImplementationError } from "@matter/main";
+import { Ble } from "@matter/main/protocol";
+import { ProxyBleCentralInterface } from "./ProxyBleChannel.js";
+import { ProxyBleClient } from "./ProxyBleClient.js";
+import { ProxyBleScanner } from "./ProxyBleScanner.js";
+class ProxyBle extends Ble {
+  #handler;
+  #proxyBleClient;
+  #bleScanner;
+  #bleCentralInterface;
+  #closed = false;
+  constructor(handler, environment) {
+    super();
+    this.#handler = handler;
+    environment?.runtime.add(this);
+  }
+  get peripheralInterface() {
+    throw new ImplementationError("BLE Proxy only supports central mode, not peripheral");
+  }
+  get centralInterface() {
+    if (!this.#bleCentralInterface) {
+      this.#bleCentralInterface = new ProxyBleCentralInterface(this.scanner, this.#handler);
+    }
+    return this.#bleCentralInterface;
+  }
+  get scanner() {
+    if (!this.#bleScanner) {
+      if (!this.#proxyBleClient) {
+        this.#proxyBleClient = new ProxyBleClient(this.#handler);
+      }
+      this.#bleScanner = new ProxyBleScanner(this.#proxyBleClient);
+    }
+    return this.#bleScanner;
+  }
+  async close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    await this.#bleCentralInterface?.close();
+    await this.#bleScanner?.close();
+  }
+}
+export {
+  ProxyBle
+};
+//# sourceMappingURL=ProxyBle.js.map

package/dist/esm/ProxyBle.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../src/ProxyBle.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAA2B,2BAA2C;AACtE,SAAS,WAAsD;AAE/D,SAAS,gCAAgC;AACzC,SAAS,sBAAsB;AAC/B,SAAS,uBAAuB;AASzB,MAAM,iBAAiB,IAAI;AAAA,EACrB;AAAA,EACT;AAAA,EACA;AAAA,EACA;AAAA,EACA,UAAU;AAAA,EAEV,YAAY,SAA0B,aAA2B;AAC7D,UAAM;AACN,SAAK,WAAW;AAGhB,iBAAa,QAAQ,IAAI,IAAI;AAAA,EACjC;AAAA,EAEA,IAAI,sBAA8C;AAC9C,UAAM,IAAI,oBAAoB,sDAAsD;AAAA,EACxF;AAAA,EAEA,IAAI,mBAA8B;AAC9B,QAAI,CAAC,KAAK,sBAAsB;AAC5B,WAAK,uBAAuB,IAAI,yBAAyB,KAAK,SAA4B,KAAK,QAAQ;AAAA,IAC3G;AACA,WAAO,KAAK;AAAA,EAChB;AAAA,EAEA,IAAI,UAAmB;AACnB,QAAI,CAAC,KAAK,aAAa;AACnB,UAAI,CAAC,KAAK,iBAAiB;AACvB,aAAK,kBAAkB,IAAI,eAAe,KAAK,QAAQ;AAAA,MAC3D;AACA,WAAK,cAAc,IAAI,gBAAgB,KAAK,eAAe;AAAA,IAC/D;AACA,WAAO,KAAK;AAAA,EAChB;AAAA,EAEA,MAAM,QAAuB;AACzB,QAAI,KAAK,QAAS;AAClB,SAAK,UAAU;AACf,UAAM,KAAK,sBAAsB,MAAM;AAEvC,UAAM,KAAK,aAAa,MAAM;AAAA,EAClC;AACJ;",
+  "names": []
+}

package/dist/esm/ProxyBleChannel.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type Bytes, type Channel, ChannelType, ServerAddress, type Transport } from "@matter/main";
+import { BleChannel, BtpSessionHandler } from "@matter/main/protocol";
+import type { BleProxyHandler } from "./BleProxyHandler.js";
+import type { ProxyBleScanner } from "./ProxyBleScanner.js";
+/**
+ * ConnectionlessTransport implementation that opens BLE channels through the proxy WebSocket.
+ * Replaces NobleBleCentralInterface from @matter/nodejs-ble.
+ */
+export declare class ProxyBleCentralInterface implements Transport {
+    #private;
+    constructor(bleScanner: ProxyBleScanner, handler: BleProxyHandler);
+    openChannel(address: ServerAddress): Promise<Channel<Bytes>>;
+    onData(listener: (socket: Channel<Bytes>, data: Bytes) => void): Transport.Listener;
+    close(): Promise<void>;
+    supports(type: ChannelType, _address?: string): type is ChannelType.BLE;
+}
+/**
+ * BLE channel that communicates through the proxy WebSocket.
+ * Replaces NobleBleChannel from @matter/nodejs-ble.
+ */
+export declare class ProxyBleChannel extends BleChannel<Bytes> {
+    #private;
+    constructor(peripheralAddress: string, btpSession: BtpSessionHandler, cleanupObservers: () => void);
+    get connected(): boolean;
+    markDisconnected(): void;
+    pushMessage(data: Bytes): void;
+    onClose(listener: () => void): Transport.Listener;
+    [Symbol.asyncIterator](): AsyncIterator<Bytes>;
+    send(data: Bytes): Promise<void>;
+    get name(): string;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=ProxyBleChannel.d.ts.map

package/dist/esm/ProxyBleChannel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProxyBleChannel.d.ts","sourceRoot":"","sources":["../../src/ProxyBleChannel.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACH,KAAK,KAAK,EACV,KAAK,OAAO,EACZ,WAAW,EAKX,aAAa,EAEb,KAAK,SAAS,EACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,UAAU,EAAoC,iBAAiB,EAAa,MAAM,uBAAuB,CAAC;AACnH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAgC5D;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,SAAS;;IAMtD,YAAY,UAAU,EAAE,eAAe,EAAE,OAAO,EAAE,eAAe,EAGhE;IAEK,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CA2NjE;IAED,MAAM,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,KAAK,KAAK,IAAI,GAAG,SAAS,CAAC,QAAQ,CAKlF;IAEK,KAAK,kBAEV;IAED,QAAQ,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,MAAM,2BAE5C;CACJ;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,UAAU,CAAC,KAAK,CAAC;;IAWlD,YAAY,iBAAiB,EAAE,MAAM,EAAE,UAAU,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,IAAI,EAOjG;IAED,IAAI,SAAS,YAEZ;IAED,gBAAgB,SAEf;IAED,WAAW,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,CAQ7B;IAED,OAAO,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAOhD;IAED,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,KAAK,CAAC,CAc7C;IAUK,IAAI,CAAC,IAAI,EAAE,KAAK,iBASrB;IAED,IAAI,IAAI,WAEP;IAEK,KAAK,kBAUV;CACJ"}

package/dist/esm/ProxyBleChannel.js

@@ -0,0 +1,314 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+  ChannelType,
+  createPromise,
+  InternalError,
+  Logger,
+  NetworkError,
+  ServerAddress,
+  Time
+} from "@matter/main";
+import { BleChannel, BleError, BtpCodec, BtpFlowError, BtpSessionHandler, MatterBle } from "@matter/main/protocol";
+import { BinaryFrameOpcode, BleProxyCommand, BleProxyEvent } from "./BleProxyProtocol.js";
+const logger = Logger.get("ProxyBleChannel");
+const BTP_HANDSHAKE_RESPONSE_OPCODE_1 = 101;
+const BTP_HANDSHAKE_RESPONSE_OPCODE_2 = 108;
+const BTP_HANDSHAKE_RESPONSE_LENGTH = 6;
+function toCanonicalUuid(uuid) {
+  const upper = uuid.toUpperCase();
+  if (upper.length === 32) {
+    return [
+      upper.substring(0, 8),
+      upper.substring(8, 12),
+      upper.substring(12, 16),
+      upper.substring(16, 20),
+      upper.substring(20, 32)
+    ].join("-");
+  }
+  return upper;
+}
+class ProxyBleCentralInterface {
+  #bleScanner;
+  #handler;
+  #onMatterMessageListener;
+  #closed = false;
+  constructor(bleScanner, handler) {
+    this.#bleScanner = bleScanner;
+    this.#handler = handler;
+  }
+  async openChannel(address) {
+    if (this.#closed) {
+      throw new NetworkError("Network interface is closed");
+    }
+    if (!ServerAddress.isBle(address)) {
+      throw new InternalError(`Unsupported address type for BLE channel.`);
+    }
+    if (this.#onMatterMessageListener === void 0) {
+      throw new InternalError("Network Interface was not added to the system yet.");
+    }
+    const { peripheralAddress } = address;
+    const { hasAdditionalAdvertisementData } = this.#bleScanner.getDiscoveredDevice(peripheralAddress);
+    if (!this.#handler.connected) {
+      throw new BleError("BLE proxy client not connected");
+    }
+    logger.debug(`Connecting to peripheral ${peripheralAddress} via proxy`);
+    const { connection_handle, mtu: peripheralMtu } = await this.#handler.sendCommand(BleProxyCommand.Connect, {
+      address: peripheralAddress
+    });
+    let mtu = peripheralMtu ?? 0;
+    if (mtu > MatterBle.MAXIMUM_BTP_MTU) {
+      mtu = MatterBle.MAXIMUM_BTP_MTU;
+    }
+    logger.debug(`Connected to ${peripheralAddress}, handle=${connection_handle}, mtu=${mtu}`);
+    try {
+      const { services } = await this.#handler.sendCommand(BleProxyCommand.DiscoverServices, {
+        connection_handle
+      });
+      const matterService = services.find((s) => MatterBle.isServiceUuid(s.uuid));
+      if (!matterService) {
+        throw new BleError(`Peripheral ${peripheralAddress} does not have Matter BLE service`);
+      }
+      const { characteristics } = await this.#handler.sendCommand(BleProxyCommand.DiscoverCharacteristics, {
+        connection_handle,
+        service_uuid: matterService.uuid
+      });
+      let c1Uuid;
+      let c2Uuid;
+      let c3Uuid;
+      for (const char of characteristics) {
+        const canonical = toCanonicalUuid(char.uuid);
+        if (canonical === MatterBle.C1_CHARACTERISTIC_UUID) {
+          c1Uuid = char.uuid;
+        } else if (canonical === MatterBle.C2_CHARACTERISTIC_UUID) {
+          c2Uuid = char.uuid;
+        } else if (canonical === MatterBle.C3_CHARACTERISTIC_UUID) {
+          c3Uuid = char.uuid;
+        }
+      }
+      if (!c1Uuid || !c2Uuid) {
+        throw new BleError(`Peripheral ${peripheralAddress} missing required Matter characteristics (C1/C2)`);
+      }
+      if (c3Uuid && hasAdditionalAdvertisementData) {
+        logger.debug(`Reading additional commissioning data from C3`);
+        await this.#handler.sendCommand(BleProxyCommand.ReadCharacteristic, {
+          connection_handle,
+          characteristic_uuid: c3Uuid
+        });
+      }
+      const btpHandshakeRequest = BtpCodec.encodeBtpHandshakeRequest({
+        versions: MatterBle.BTP_SUPPORTED_VERSIONS,
+        attMtu: mtu,
+        clientWindowSize: MatterBle.BTP_MAXIMUM_WINDOW_SIZE
+      });
+      logger.debug(`Sending BTP handshake request on C1`);
+      await this.#handler.sendCommand(BleProxyCommand.WriteCharacteristic, {
+        connection_handle,
+        characteristic_uuid: c1Uuid,
+        value: Buffer.from(btpHandshakeRequest).toString("base64"),
+        response: true
+      });
+      await this.#handler.sendCommand(BleProxyCommand.SubscribeCharacteristic, {
+        connection_handle,
+        characteristic_uuid: c2Uuid
+      });
+      const {
+        promise: handshakePromise,
+        resolver: handshakeResolver,
+        rejecter: handshakeRejecter
+      } = createPromise();
+      const btpHandshakeTimeout = Time.getTimer(
+        "BLE proxy handshake timeout",
+        MatterBle.BTP_CONN_RSP_TIMEOUT,
+        () => {
+          handshakeRejecter(new BleError(`BTP handshake response not received from ${peripheralAddress}`));
+        }
+      ).start();
+      const handshakeObserver = (frame) => {
+        if (frame.connectionHandle === connection_handle && frame.opcode === BinaryFrameOpcode.Notification) {
+          const data = new Uint8Array(frame.payload);
+          if (data[0] === BTP_HANDSHAKE_RESPONSE_OPCODE_1 && data[1] === BTP_HANDSHAKE_RESPONSE_OPCODE_2 && data.length === BTP_HANDSHAKE_RESPONSE_LENGTH) {
+            btpHandshakeTimeout.stop();
+            handshakeResolver(data);
+          }
+        }
+      };
+      this.#handler.binaryFrameReceived.on(handshakeObserver);
+      let handshakeResponse;
+      try {
+        handshakeResponse = await handshakePromise;
+      } finally {
+        this.#handler.binaryFrameReceived.off(handshakeObserver);
+        btpHandshakeTimeout.stop();
+      }
+      const onMatterMessageListener = this.#onMatterMessageListener;
+      const channelRef = {};
+      const btpSession = await BtpSessionHandler.createAsCentral(
+        handshakeResponse,
+        // Write callback: send binary frame to proxy client
+        async (data) => {
+          const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+          this.#handler.sendBinaryFrame(BinaryFrameOpcode.WriteData, connection_handle, bytes);
+        },
+        // Disconnect callback
+        async () => {
+          if (!channelRef.channel?.connected) return;
+          logger.debug(`Disconnecting from ${peripheralAddress} via proxy`);
+          try {
+            await this.#handler.sendCommand(BleProxyCommand.Disconnect, { connection_handle });
+          } catch (error) {
+            logger.debug(
+              `Peripheral ${peripheralAddress}: Error sending Disconnect to proxy client`,
+              error
+            );
+          }
+        },
+        // Matter message callback
+        async (data) => {
+          if (channelRef.channel) {
+            channelRef.channel.pushMessage(data);
+            onMatterMessageListener(channelRef.channel, data);
+          }
+        }
+      );
+      const binaryObserver = (frame) => {
+        if (frame.connectionHandle === connection_handle && frame.opcode === BinaryFrameOpcode.Notification) {
+          btpSession.handleIncomingBleData(new Uint8Array(frame.payload)).catch(
+            (error) => logger.warn(`Peripheral ${peripheralAddress}: Error handling incoming BLE data`, error)
+          );
+        }
+      };
+      this.#handler.binaryFrameReceived.on(binaryObserver);
+      const eventObserver = (event, data) => {
+        if (event === BleProxyEvent.Disconnected && typeof data.connection_handle === "number" && data.connection_handle === connection_handle) {
+          logger.info(`Peripheral ${peripheralAddress} disconnected unexpectedly`);
+          channelRef.channel?.markDisconnected();
+          channelRef.channel?.close().catch((error) => logger.debug(`Peripheral ${peripheralAddress}: Error closing channel`, error));
+        }
+      };
+      this.#handler.eventReceived.on(eventObserver);
+      const cleanupObservers = () => {
+        this.#handler.binaryFrameReceived.off(binaryObserver);
+        this.#handler.eventReceived.off(eventObserver);
+      };
+      const proxyChannel = new ProxyBleChannel(peripheralAddress, btpSession, cleanupObservers);
+      channelRef.channel = proxyChannel;
+      return proxyChannel;
+    } catch (error) {
+      try {
+        await this.#handler.sendCommand(BleProxyCommand.Disconnect, { connection_handle });
+      } catch (cleanupError) {
+        logger.debug(`Peripheral ${peripheralAddress}: Error during connect-failure cleanup`, cleanupError);
+      }
+      throw error;
+    }
+  }
+  onData(listener) {
+    this.#onMatterMessageListener = listener;
+    return {
+      close: async () => await this.close()
+    };
+  }
+  async close() {
+    this.#closed = true;
+  }
+  supports(type, _address) {
+    return type === ChannelType.BLE;
+  }
+}
+class ProxyBleChannel extends BleChannel {
+  #connected = true;
+  #peripheralAddress;
+  #btpSession;
+  #cleanupObservers;
+  #onBtpSessionClosed;
+  #closeListeners = /* @__PURE__ */ new Set();
+  #iteratorQueue = new Array();
+  #iteratorWaiter;
+  #iteratorDone = false;
+  constructor(peripheralAddress, btpSession, cleanupObservers) {
+    super();
+    this.#peripheralAddress = peripheralAddress;
+    this.#btpSession = btpSession;
+    this.#cleanupObservers = cleanupObservers;
+    this.#onBtpSessionClosed = () => this.emitClosed();
+    btpSession.closed.on(this.#onBtpSessionClosed);
+  }
+  get connected() {
+    return this.#connected;
+  }
+  markDisconnected() {
+    this.#connected = false;
+  }
+  pushMessage(data) {
+    if (this.#iteratorWaiter) {
+      const resolve = this.#iteratorWaiter;
+      this.#iteratorWaiter = void 0;
+      resolve({ value: data, done: false });
+    } else if (!this.#iteratorDone) {
+      this.#iteratorQueue.push(data);
+    }
+  }
+  onClose(listener) {
+    this.#closeListeners.add(listener);
+    return {
+      close: async () => {
+        this.#closeListeners.delete(listener);
+      }
+    };
+  }
+  [Symbol.asyncIterator]() {
+    return {
+      next: () => {
+        if (this.#iteratorQueue.length > 0) {
+          return Promise.resolve({ value: this.#iteratorQueue.shift(), done: false });
+        }
+        if (this.#iteratorDone || !this.#connected) {
+          return Promise.resolve({ value: void 0, done: true });
+        }
+        return new Promise((resolve) => {
+          this.#iteratorWaiter = resolve;
+        });
+      }
+    };
+  }
+  #terminateIterator() {
+    if (!this.#iteratorDone) {
+      this.#iteratorDone = true;
+      this.#iteratorWaiter?.({ value: void 0, done: true });
+      this.#iteratorWaiter = void 0;
+    }
+  }
+  async send(data) {
+    if (!this.#connected) {
+      logger.debug(`Cannot send data - not connected to ${this.#peripheralAddress}`);
+      return;
+    }
+    if (this.#btpSession === void 0) {
+      throw new BtpFlowError(`Cannot send data, no BTP session initialized`);
+    }
+    await this.#btpSession.sendMatterMessage(data);
+  }
+  get name() {
+    return `ble-proxy://${this.#peripheralAddress}`;
+  }
+  async close() {
+    this.#connected = false;
+    this.#cleanupObservers();
+    this.#terminateIterator();
+    for (const listener of this.#closeListeners) {
+      listener();
+    }
+    this.#btpSession.closed.off(this.#onBtpSessionClosed);
+    await this.#btpSession.close();
+    this.emitClosed();
+  }
+}
+export {
+  ProxyBleCentralInterface,
+  ProxyBleChannel
+};
+//# sourceMappingURL=ProxyBleChannel.js.map

package/dist/esm/ProxyBleChannel.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../src/ProxyBleChannel.ts"],
+  "mappings": "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",
+  "names": []
+}

package/dist/esm/ProxyBleClient.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BleProxyHandler } from "./BleProxyHandler.js";
+/**
+ * Represents a BLE peripheral discovered through the proxy.
+ * Replaces Noble's Peripheral type - stores the data received from the proxy client.
+ */
+export interface ProxyPeripheral {
+    address: string;
+    name?: string;
+    rssi?: number;
+    connectable: boolean;
+    serviceData: Map<string, Uint8Array>;
+    mtu?: number;
+}
+/**
+ * BLE client that communicates over the BLE proxy WebSocket protocol.
+ * Replaces NobleBleClient - instead of using Noble directly, sends scan commands
+ * to the proxy client and receives device_discovered events.
+ */
+export declare class ProxyBleClient {
+    #private;
+    constructor(handler: BleProxyHandler);
+    setDiscoveryCallback(callback: (peripheral: ProxyPeripheral, matterServiceData: Uint8Array) => void): void;
+    startScanning(): Promise<void>;
+    stopScanning(): Promise<void>;
+    close(): void;
+}
+//# sourceMappingURL=ProxyBleClient.d.ts.map

package/dist/esm/ProxyBleClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProxyBleClient.d.ts","sourceRoot":"","sources":["../../src/ProxyBleClient.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAK5D;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,qBAAa,cAAc;;IAevB,YAAY,OAAO,EAAE,eAAe,EAGnC;IAED,oBAAoB,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,eAAe,EAAE,iBAAiB,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAKzG;IAEK,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAgBnC;IAEK,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAalC;IAED,KAAK,IAAI,IAAI,CAGZ;CAyCJ"}