@matter-server/ble-proxy 0.0.1

package/package.json

@@ -0,0 +1,46 @@
+{
+    "name": "@matter-server/ble-proxy",
+    "version": "0.0.1",
+    "type": "module",
+    "description": "BLE proxy implementation for matter.js - proxies BLE operations over WebSocket",
+    "bugs": {
+        "url": "https://github.com/matter-js/matterjs-server/issues"
+    },
+    "homepage": "https://github.com/matter-js/matterjs-server",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/matter-js/matterjs-server.git"
+    },
+    "author": "Open Home Foundation",
+    "main": "dist/esm/index.js",
+    "scripts": {
+        "clean": "nacho-build clean",
+        "build": "nacho-build",
+        "build-clean": "nacho-build --clean",
+        "noble-ble-proxy": "nacho-run src/example/noble-ble-proxy.ts"
+    },
+    "engines": {
+        "node": ">=20.19.0 <22.0.0 || >=22.13.0"
+    },
+    "dependencies": {
+        "@matter/main": "0.17.0-alpha.0-20260520-0ab980a16",
+        "@matter-server/ws-controller": "*",
+        "ws": "^8.20.1"
+    },
+    "optionalDependencies": {
+        "@matter/nodejs-ble": "0.17.0-alpha.0-20260520-0ab980a16"
+    },
+    "devDependencies": {
+        "@types/node": "^25.9.1",
+        "@types/ws": "^8.18.1"
+    },
+    "files": [
+        "dist/**/*",
+        "src/**/*",
+        "LICENSE",
+        "README.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/BleProxyHandler.ts

@@ -0,0 +1,345 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { WebServerHandler } from "@matter-server/ws-controller";
+import { createPromise, Logger, Observable, Seconds, Time, Timer, withTimeout } from "@matter/main";
+import type { createServer } from "node:http";
+import { WebSocket, WebSocketServer } from "ws";
+import {
+    BLE_PROXY_PROTOCOL_VERSION,
+    decodeBinaryFrame,
+    encodeBinaryFrame,
+    type BinaryFrame,
+    type BleProxyCommandMap,
+    type BleProxyCommandName,
+    type BleProxyEventName,
+    type CommandMessage,
+    type EventMessage,
+    type HelloMessage,
+    type ResponseMessage,
+} from "./BleProxyProtocol.js";
+
+type HttpServer = ReturnType<typeof createServer>;
+
+const logger = Logger.get("BleProxyHandler");
+
+const HANDSHAKE_TIMEOUT = Seconds(10);
+/**
+ * Default per-command timeout. Long enough to cover the slowest BLE
+ * commissioning ops (peripheral connect ≤ 30 s, service discovery on
+ * Android-side adapters can take several seconds), short enough that an
+ * unresponsive-but-still-connected proxy client doesn't hang commissioning
+ * indefinitely.
+ */
+const COMMAND_TIMEOUT = Seconds(60);
+
+/**
+ * WebSocket server handler for the /ble BLE proxy endpoint.
+ *
+ * Accepts a single client connection, performs the protocol handshake,
+ * and routes commands/events/binary frames between the proxy implementation
+ * and the connected BLE proxy client.
+ */
+export class BleProxyHandler implements WebServerHandler {
+    #wss?: WebSocketServer;
+    /** Upgrade listener removers, one per HTTP server `register()` call (multi-bind). */
+    #removeUpgradeListeners: (() => void)[] = [];
+    #client?: WebSocket;
+    #handshakeComplete = false;
+    #pendingCommands = new Map<
+        number,
+        { resolver: (result: Record<string, unknown> | undefined) => void; rejecter: (reason?: unknown) => void }
+    >();
+    /** Command ID counter. Rolls over at 0xFFFF to stay in safe integer range. */
+    #nextCommandId = 0;
+    #closed = false;
+
+    /** Emitted when a JSON event is received from the BLE proxy client. */
+    readonly eventReceived = new Observable<[event: BleProxyEventName, data: Record<string, unknown>]>();
+
+    /** Emitted when a binary frame is received from the BLE proxy client. */
+    readonly binaryFrameReceived = new Observable<[frame: BinaryFrame]>();
+
+    get connected(): boolean {
+        return this.#handshakeComplete && this.#client?.readyState === WebSocket.OPEN;
+    }
+
+    async register(server: HttpServer): Promise<void> {
+        // Use noServer mode with a path-filtered upgrade listener.
+        // ws 8.x calls handleUpgrade unconditionally from its own upgrade listener, which
+        // sends HTTP 400 for non-matching paths and destroys the socket — breaking other
+        // WebSocket endpoints on the same server.
+        const wss = (this.#wss = new WebSocketServer({ noServer: true }));
+        const upgradeHandler = (
+            req: { url?: string; _matterHandledUpgrade?: boolean },
+            socket: unknown,
+            head: unknown,
+        ) => {
+            logger.debug(`Upgrade request received: ${req.url}`);
+            const path = req.url?.split("?")[0];
+            if (path === "/ble") {
+                req._matterHandledUpgrade = true;
+                wss.handleUpgrade(
+                    req as Parameters<typeof wss.handleUpgrade>[0],
+                    socket as Parameters<typeof wss.handleUpgrade>[1],
+                    head as Parameters<typeof wss.handleUpgrade>[2],
+                    ws => wss.emit("connection", ws, req),
+                );
+            }
+        };
+        server.on("upgrade", upgradeHandler);
+        this.#removeUpgradeListeners.push(() => server.removeListener("upgrade", upgradeHandler));
+        logger.info("BLE proxy WebSocket endpoint registered on /ble");
+
+        wss.on("connection", ws => {
+            if (this.#closed) {
+                ws.close();
+                return;
+            }
+
+            if (this.#client) {
+                logger.warn("Rejecting new BLE proxy client - only one connection allowed");
+                ws.close(4000, "Only one BLE proxy client allowed");
+                return;
+            }
+
+            logger.info("BLE proxy client connected, waiting for handshake");
+            this.#client = ws;
+            this.#handshakeComplete = false;
+
+            const handshakeTimer = Time.getTimer("BLE proxy handshake timeout", HANDSHAKE_TIMEOUT, () => {
+                if (!this.#handshakeComplete) {
+                    logger.warn("BLE proxy handshake timeout - closing connection");
+                    ws.close(4001, "Handshake timeout");
+                    this.#cleanupClient();
+                }
+            }).start();
+
+            ws.on("message", (data, isBinary) => {
+                if (isBinary) {
+                    this.#handleBinaryMessage(data as Buffer);
+                } else {
+                    this.#handleTextMessage(data.toString(), handshakeTimer);
+                }
+            });
+
+            ws.on("close", () => {
+                handshakeTimer.stop();
+                logger.info("BLE proxy client disconnected");
+                this.#cleanupClient();
+            });
+
+            ws.on("error", err => {
+                logger.error("BLE proxy WebSocket error:", err);
+                handshakeTimer.stop();
+                this.#cleanupClient();
+            });
+        });
+    }
+
+    unregister(): Promise<void> {
+        if (!this.#wss || this.#closed) {
+            return Promise.resolve();
+        }
+
+        this.#closed = true;
+        for (const remove of this.#removeUpgradeListeners) remove();
+        this.#removeUpgradeListeners = [];
+
+        // Close the connected client
+        if (this.#client && this.#client.readyState === WebSocket.OPEN) {
+            this.#client.close();
+        }
+        this.#cleanupClient();
+
+        const wss = this.#wss;
+        this.#wss = undefined;
+
+        // Close all clients connected to the WSS (safety net)
+        wss.clients.forEach(client => {
+            if (client.readyState === WebSocket.OPEN) {
+                client.close();
+            }
+        });
+
+        // Wait for the WebSocket server to close properly
+        return new Promise<void>((resolve, reject) => {
+            wss.close(err => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve();
+                }
+            });
+        });
+    }
+
+    /**
+     * Send a typed command to the BLE proxy client and wait for the response.
+     * The return type is inferred from the command name via BleProxyCommandMap.
+     * Rejects if no client is connected or the client disconnects before responding.
+     */
+    async sendCommand<C extends BleProxyCommandName>(
+        command: C,
+        ...rest: BleProxyCommandMap[C]["args"] extends undefined ? [] : [args: BleProxyCommandMap[C]["args"]]
+    ): Promise<BleProxyCommandMap[C]["result"]> {
+        if (!this.connected || !this.#client) {
+            throw new Error("BLE proxy client not connected");
+        }
+
+        const args = rest[0];
+        const id = this.#nextCommandId;
+        this.#nextCommandId = (this.#nextCommandId + 1) & 0xffff;
+        const message: CommandMessage = { id, command };
+        if (args !== undefined) {
+            message.args = args as Record<string, unknown>;
+        }
+
+        const { promise, resolver, rejecter } = createPromise<Record<string, unknown> | undefined>();
+        this.#pendingCommands.set(id, { resolver, rejecter });
+
+        this.#client.send(JSON.stringify(message), err => {
+            if (err) {
+                this.#pendingCommands.delete(id);
+                rejecter(new Error(`Failed to send command ${command}: ${err.message}`));
+            }
+        });
+
+        return withTimeout(COMMAND_TIMEOUT, promise, () => this.#pendingCommands.delete(id)) as Promise<
+            BleProxyCommandMap[C]["result"]
+        >;
+    }
+
+    /**
+     * Send a binary frame to the BLE proxy client.
+     */
+    sendBinaryFrame(opcode: number, connectionHandle: number, payload: Uint8Array): void {
+        if (!this.connected || !this.#client) {
+            throw new Error("BLE proxy client not connected");
+        }
+        const frame = encodeBinaryFrame(opcode, connectionHandle, payload);
+        this.#client.send(frame);
+    }
+
+    #handleTextMessage(raw: string, handshakeTimer: Timer): void {
+        let parsed: unknown;
+        try {
+            parsed = JSON.parse(raw);
+        } catch {
+            logger.warn("Received invalid JSON from BLE proxy client");
+            return;
+        }
+
+        const msg = parsed as Record<string, unknown>;
+
+        // Handle handshake
+        if (!this.#handshakeComplete) {
+            this.#handleHandshake(msg, handshakeTimer);
+            return;
+        }
+
+        // Handle response to a pending command
+        if ("id" in msg && "success" in msg) {
+            this.#handleResponse(msg as unknown as ResponseMessage);
+            return;
+        }
+
+        // Handle event
+        if ("event" in msg && "data" in msg) {
+            this.#handleEvent(msg as unknown as EventMessage);
+            return;
+        }
+
+        logger.warn("Received unknown message from BLE proxy client:", msg);
+    }
+
+    #handleHandshake(msg: Record<string, unknown>, handshakeTimer: Timer): void {
+        if (msg.type !== "hello") {
+            logger.warn(`Expected hello message, got: ${JSON.stringify(msg)}`);
+            this.#client?.close(4002, "Expected hello message");
+            this.#cleanupClient();
+            return;
+        }
+
+        const hello = msg as unknown as HelloMessage;
+        handshakeTimer.stop();
+
+        if (hello.version !== BLE_PROXY_PROTOCOL_VERSION) {
+            logger.warn(
+                `BLE proxy client version ${hello.version} not supported (server supports ${BLE_PROXY_PROTOCOL_VERSION})`,
+            );
+            this.#client?.send(
+                JSON.stringify({
+                    type: "hello_response",
+                    version: BLE_PROXY_PROTOCOL_VERSION,
+                    error: "unsupported_version",
+                    message: `Server supports protocol version ${BLE_PROXY_PROTOCOL_VERSION}, client sent version ${hello.version}`,
+                }),
+            );
+            this.#client?.close(4003, "Unsupported protocol version");
+            this.#cleanupClient();
+            return;
+        }
+
+        this.#handshakeComplete = true;
+        this.#client?.send(
+            JSON.stringify({
+                type: "hello_response",
+                version: BLE_PROXY_PROTOCOL_VERSION,
+            }),
+        );
+        logger.info(`BLE proxy handshake complete (version ${BLE_PROXY_PROTOCOL_VERSION})`);
+    }
+
+    #handleResponse(msg: ResponseMessage): void {
+        const pending = this.#pendingCommands.get(msg.id);
+        if (!pending) {
+            logger.warn(`Received response for unknown command id ${msg.id}`);
+            return;
+        }
+        this.#pendingCommands.delete(msg.id);
+
+        if (msg.success) {
+            pending.resolver(msg.result);
+        } else {
+            pending.rejecter(new Error(`${msg.error}: ${msg.message}`));
+        }
+    }
+
+    #handleEvent(msg: EventMessage): void {
+        this.eventReceived.emit(msg.event, msg.data);
+    }
+
+    #handleBinaryMessage(data: Buffer): void {
+        if (!this.#handshakeComplete) {
+            logger.warn("Received binary frame before handshake");
+            return;
+        }
+
+        try {
+            const frame = decodeBinaryFrame(new Uint8Array(data));
+            this.binaryFrameReceived.emit(frame);
+        } catch (err) {
+            logger.error("Failed to decode binary frame:", err);
+        }
+    }
+
+    #cleanupClient(): void {
+        if (this.#client) {
+            if (this.#client.readyState === WebSocket.OPEN) {
+                this.#client.close();
+            }
+            this.#client = undefined;
+        }
+        this.#handshakeComplete = false;
+
+        // Reject all pending commands
+        for (const [id, pending] of this.#pendingCommands) {
+            pending.rejecter(new Error("BLE proxy client disconnected"));
+            this.#pendingCommands.delete(id);
+        }
+    }
+}

package/src/BleProxyProtocol.ts

@@ -0,0 +1,287 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * BLE Proxy Protocol constants, types, and codec.
+ * See docs/ble-proxy-protocol.md for the full specification.
+ */
+
+// ─── Protocol Version ────────────────────────────────────────────────────────
+
+export const BLE_PROXY_PROTOCOL_VERSION = 1;
+
+// ─── Handshake Messages ──────────────────────────────────────────────────────
+
+export interface HelloMessage {
+    type: "hello";
+    version: number;
+}
+
+export interface HelloResponseMessage {
+    type: "hello_response";
+    version: number;
+    error?: string;
+    message?: string;
+}
+
+export type HandshakeMessage = HelloMessage | HelloResponseMessage;
+
+// ─── Command Names ───────────────────────────────────────────────────────────
+
+export 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",
+} as const;
+
+export type BleProxyCommandName = (typeof BleProxyCommand)[keyof typeof BleProxyCommand];
+
+// ─── Event Names ─────────────────────────────────────────────────────────────
+
+export const BleProxyEvent = {
+    DeviceDiscovered: "device_discovered",
+    Disconnected: "disconnected",
+    ScanStopped: "scan_stopped",
+    CharacteristicNotification: "characteristic_notification",
+} as const;
+
+export type BleProxyEventName = (typeof BleProxyEvent)[keyof typeof BleProxyEvent];
+
+// ─── Command Args ────────────────────────────────────────────────────────────
+
+export interface StartScanArgs {
+    service_uuids?: string[];
+    allow_duplicates?: boolean;
+}
+
+export interface ConnectArgs {
+    address: string;
+    timeout?: number;
+}
+
+export interface DisconnectArgs {
+    connection_handle: number;
+}
+
+export interface DiscoverServicesArgs {
+    connection_handle: number;
+}
+
+export interface DiscoverCharacteristicsArgs {
+    connection_handle: number;
+    service_uuid: string;
+}
+
+export interface ReadCharacteristicArgs {
+    connection_handle: number;
+    characteristic_uuid: string;
+}
+
+export interface WriteCharacteristicArgs {
+    connection_handle: number;
+    characteristic_uuid: string;
+    value: string; // base64
+    response?: boolean;
+}
+
+export interface SubscribeCharacteristicArgs {
+    connection_handle: number;
+    characteristic_uuid: string;
+}
+
+export interface UnsubscribeCharacteristicArgs {
+    connection_handle: number;
+    characteristic_uuid: string;
+}
+
+export interface RequestMtuArgs {
+    connection_handle: number;
+    mtu: number;
+}
+
+// ─── Command Results ─────────────────────────────────────────────────────────
+
+export interface ConnectResult {
+    connection_handle: number;
+    mtu: number;
+}
+
+export interface DiscoverServicesResult {
+    services: Array<{ uuid: string }>;
+}
+
+export interface DiscoverCharacteristicsResult {
+    characteristics: Array<{
+        uuid: string;
+        properties: string[];
+    }>;
+}
+
+export interface ReadCharacteristicResult {
+    value: string; // base64
+}
+
+export interface RequestMtuResult {
+    mtu: number;
+}
+
+// ─── Event Data ──────────────────────────────────────────────────────────────
+
+export interface DeviceDiscoveredData {
+    address: string;
+    name?: string;
+    rssi?: number;
+    connectable: boolean;
+    service_data?: Record<string, string>; // uuid -> base64
+    manufacturer_data?: Record<string, string>; // id -> base64
+    service_uuids?: string[];
+}
+
+export interface DisconnectedData {
+    connection_handle: number;
+    reason?: string;
+}
+
+export interface ScanStoppedData {
+    reason: string;
+}
+
+export interface CharacteristicNotificationData {
+    connection_handle: number;
+    characteristic_uuid: string;
+    value: string; // base64
+}
+
+// ─── Command Type Map ────────────────────────────────────────────────────────
+
+/** Maps each command name to its args and result types for type-safe sendCommand. */
+export interface BleProxyCommandMap {
+    [BleProxyCommand.StartScan]: { args: StartScanArgs; result: void };
+    [BleProxyCommand.StopScan]: { args: undefined; result: void };
+    [BleProxyCommand.Connect]: { args: ConnectArgs; result: ConnectResult };
+    [BleProxyCommand.Disconnect]: { args: DisconnectArgs; result: void };
+    [BleProxyCommand.DiscoverServices]: { args: DiscoverServicesArgs; result: DiscoverServicesResult };
+    [BleProxyCommand.DiscoverCharacteristics]: {
+        args: DiscoverCharacteristicsArgs;
+        result: DiscoverCharacteristicsResult;
+    };
+    [BleProxyCommand.ReadCharacteristic]: { args: ReadCharacteristicArgs; result: ReadCharacteristicResult };
+    [BleProxyCommand.WriteCharacteristic]: { args: WriteCharacteristicArgs; result: void };
+    [BleProxyCommand.SubscribeCharacteristic]: { args: SubscribeCharacteristicArgs; result: void };
+    [BleProxyCommand.UnsubscribeCharacteristic]: { args: UnsubscribeCharacteristicArgs; result: void };
+    [BleProxyCommand.RequestMtu]: { args: RequestMtuArgs; result: RequestMtuResult };
+}
+
+// ─── JSON Message Envelopes ──────────────────────────────────────────────────
+
+export interface CommandMessage {
+    id: number;
+    command: BleProxyCommandName;
+    args?: Record<string, unknown>;
+}
+
+export interface SuccessResponseMessage {
+    id: number;
+    success: true;
+    result?: Record<string, unknown>;
+}
+
+export interface ErrorResponseMessage {
+    id: number;
+    success: false;
+    error: string;
+    message: string;
+}
+
+export type ResponseMessage = SuccessResponseMessage | ErrorResponseMessage;
+
+export interface EventMessage {
+    event: BleProxyEventName;
+    data: Record<string, unknown>;
+}
+
+// ─── Error Codes ─────────────────────────────────────────────────────────────
+
+export 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",
+} as const;
+
+export type BleProxyErrorCodeValue = (typeof BleProxyErrorCode)[keyof typeof BleProxyErrorCode];
+
+// ─── Binary Frame Opcodes ────────────────────────────────────────────────────
+
+export const BinaryFrameOpcode = {
+    /** Server -> Client: write payload to the active write characteristic */
+    WriteData: 0x01,
+    /** Client -> Server: notification data from a subscribed characteristic */
+    Notification: 0x02,
+    /** Client -> Server: response data for a read_characteristic command */
+    ReadResponse: 0x03,
+} as const;
+
+export type BinaryFrameOpcodeValue = (typeof BinaryFrameOpcode)[keyof typeof BinaryFrameOpcode];
+
+// ─── Binary Frame Codec ──────────────────────────────────────────────────────
+
+/**
+ * Binary frame layout:
+ * [1 byte: opcode] [2 bytes: connection_handle big-endian] [N bytes: payload]
+ *
+ * Minimum frame size: 3 bytes (opcode + handle, empty payload).
+ */
+
+const BINARY_FRAME_HEADER_SIZE = 3;
+
+export interface BinaryFrame {
+    opcode: number;
+    connectionHandle: number;
+    payload: Uint8Array;
+}
+
+export function encodeBinaryFrame(opcode: number, connectionHandle: number, payload: Uint8Array): Uint8Array {
+    const frame = new Uint8Array(BINARY_FRAME_HEADER_SIZE + payload.length);
+    frame[0] = opcode & 0xff;
+    frame[1] = (connectionHandle >> 8) & 0xff;
+    frame[2] = connectionHandle & 0xff;
+    frame.set(payload, BINARY_FRAME_HEADER_SIZE);
+    return frame;
+}
+
+export function decodeBinaryFrame(data: Uint8Array): BinaryFrame {
+    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),
+    };
+}