@matter/react-native 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/ble/ReactNativeBleChannel.ts

@@ -0,0 +1,313 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    Bytes,
+    Channel,
+    ChannelType,
+    InternalError,
+    Logger,
+    NetInterface,
+    ServerAddress,
+    Time,
+    TransportInterface,
+    createPromise,
+} from "#general";
+import {
+    BLE_MATTER_C1_CHARACTERISTIC_UUID,
+    BLE_MATTER_C2_CHARACTERISTIC_UUID,
+    BLE_MATTER_C3_CHARACTERISTIC_UUID,
+    BLE_MATTER_SERVICE_UUID,
+    BLE_MAXIMUM_BTP_MTU,
+    BTP_CONN_RSP_TIMEOUT_MS,
+    BTP_MAXIMUM_WINDOW_SIZE,
+    BTP_SUPPORTED_VERSIONS,
+    Ble,
+    BleChannel,
+    BleError,
+    BtpCodec,
+    BtpFlowError,
+    BtpSessionHandler,
+} from "#protocol";
+import {
+    BleErrorCode,
+    Characteristic,
+    Device,
+    BleError as ReactNativeBleError,
+    Subscription,
+} from "react-native-ble-plx";
+import { BleScanner } from "./BleScanner.js";
+
+const logger = Logger.get("BleChannel");
+
+export class ReactNativeBleCentralInterface implements NetInterface {
+    private openChannels: Map<ServerAddress, Device> = new Map();
+    private onMatterMessageListener: ((socket: Channel<Uint8Array>, data: Uint8Array) => void) | undefined;
+
+    async openChannel(address: ServerAddress): Promise<Channel<Uint8Array>> {
+        if (address.type !== "ble") {
+            throw new InternalError(`Unsupported address type ${address.type}.`);
+        }
+        if (this.onMatterMessageListener === undefined) {
+            throw new InternalError(`Network Interface was not added to the system yet.`);
+        }
+
+        // Get the peripheral by address and connect to it.
+        const { peripheral, hasAdditionalAdvertisementData } = (
+            Ble.get().getBleScanner() as BleScanner
+        ).getDiscoveredDevice(address.peripheralAddress);
+        if (this.openChannels.has(address)) {
+            throw new BleError(
+                `Peripheral ${address.peripheralAddress} is already connected. Only one connection supported right now.`,
+            );
+        }
+        logger.debug(`Connect to Peripheral now`);
+        let device: Device;
+        try {
+            device = await peripheral.connect();
+        } catch (error) {
+            if (error instanceof ReactNativeBleError && error.errorCode === BleErrorCode.DeviceAlreadyConnected) {
+                device = peripheral;
+            } else {
+                throw new BleError(`Error connecting to peripheral: ${(error as any).message}`);
+            }
+        }
+        logger.debug(`Peripheral connected successfully, MTU = ${device.mtu}`);
+
+        // Once the peripheral has been connected, then discover the services and characteristics of interest.
+        device = await device.discoverAllServicesAndCharacteristics();
+
+        const services = await device.services();
+
+        for (const service of services) {
+            logger.debug(`found service: ${service.uuid}`);
+            if (service.uuid !== BLE_MATTER_SERVICE_UUID) continue;
+
+            // So, discover its characteristics.
+            const characteristics = await device.characteristicsForService(service.uuid);
+
+            let characteristicC1ForWrite: Characteristic | undefined;
+            let characteristicC2ForSubscribe: Characteristic | undefined;
+            let additionalCommissioningRelatedData: Uint8Array | undefined;
+
+            for (const characteristic of characteristics) {
+                // Loop through each characteristic and match them to the UUIDs that we know about.
+                logger.debug("found characteristic:", characteristic.uuid);
+
+                switch (characteristic.uuid) {
+                    case BLE_MATTER_C1_CHARACTERISTIC_UUID:
+                        logger.debug("found C1 characteristic");
+                        characteristicC1ForWrite = characteristic;
+                        break;
+
+                    case BLE_MATTER_C2_CHARACTERISTIC_UUID:
+                        logger.debug("found C2 characteristic");
+                        characteristicC2ForSubscribe = characteristic;
+                        break;
+
+                    case BLE_MATTER_C3_CHARACTERISTIC_UUID:
+                        logger.debug("found C3 characteristic");
+                        if (hasAdditionalAdvertisementData) {
+                            logger.debug("reading additional commissioning related data");
+                            const characteristicWithValue = await service.readCharacteristic(characteristic.uuid);
+                            if (characteristicWithValue.value !== null) {
+                                additionalCommissioningRelatedData = Bytes.fromBase64(characteristicWithValue.value);
+                            } else {
+                                logger.debug("no value in characteristic C3");
+                            }
+                        }
+                }
+            }
+
+            if (!characteristicC1ForWrite || !characteristicC2ForSubscribe) {
+                logger.debug("missing characteristics");
+                continue;
+            }
+
+            this.openChannels.set(address, peripheral);
+            return await ReactNativeBleChannel.create(
+                peripheral,
+                characteristicC1ForWrite,
+                characteristicC2ForSubscribe,
+                this.onMatterMessageListener,
+                additionalCommissioningRelatedData,
+            );
+        }
+
+        throw new BleError(`No Matter service found on peripheral ${peripheral.id}`);
+    }
+
+    onData(listener: (socket: Channel<Uint8Array>, data: Uint8Array) => void): TransportInterface.Listener {
+        this.onMatterMessageListener = listener;
+        return {
+            close: async () => await this.close(),
+        };
+    }
+
+    async close() {
+        for (const peripheral of this.openChannels.values()) {
+            await peripheral.cancelConnection();
+        }
+    }
+
+    supports(type: ChannelType) {
+        return type === ChannelType.BLE;
+    }
+}
+
+export class ReactNativeBleChannel extends BleChannel<Uint8Array> {
+    static async create(
+        peripheral: Device,
+        characteristicC1ForWrite: Characteristic,
+        characteristicC2ForSubscribe: Characteristic,
+        onMatterMessageListener: (socket: Channel<Uint8Array>, data: Uint8Array) => void,
+        _additionalCommissioningRelatedData?: Uint8Array,
+    ): Promise<ReactNativeBleChannel> {
+        let mtu = peripheral.mtu ?? 0;
+        if (mtu > BLE_MAXIMUM_BTP_MTU) {
+            mtu = BLE_MAXIMUM_BTP_MTU;
+        }
+        logger.debug(`Using MTU=${mtu} (Peripheral MTU=${peripheral.mtu})`);
+        const btpHandshakeRequest = BtpCodec.encodeBtpHandshakeRequest({
+            versions: BTP_SUPPORTED_VERSIONS,
+            attMtu: mtu,
+            clientWindowSize: BTP_MAXIMUM_WINDOW_SIZE,
+        });
+        logger.debug(`sending BTP handshake request: ${Logger.toJSON(btpHandshakeRequest)}`);
+        characteristicC1ForWrite = await characteristicC1ForWrite.writeWithResponse(
+            Bytes.toBase64(btpHandshakeRequest),
+        );
+
+        const btpHandshakeTimeout = Time.getTimer("BLE handshake timeout", BTP_CONN_RSP_TIMEOUT_MS, async () => {
+            await peripheral.cancelConnection();
+            logger.debug("Handshake Response not received. Disconnected from peripheral");
+        }).start();
+
+        logger.debug("subscribing to C2 characteristic");
+
+        const { promise: handshakeResponseReceivedPromise, resolver } = createPromise<Uint8Array>();
+
+        let handshakeReceived = false;
+        const handshakeSubscription = characteristicC2ForSubscribe.monitor((error, characteristic) => {
+            if (error !== null || characteristic === null) {
+                if (error instanceof ReactNativeBleError && error.errorCode === 2 && handshakeReceived) {
+                    // Subscription got removed after handshake was received, all good
+                    return;
+                }
+                logger.debug("Error while monitoring C2 characteristic", error);
+                return;
+            }
+            const characteristicData = characteristic.value;
+            if (characteristicData === null) {
+                logger.debug("C2 characteristic value is null");
+                return;
+            }
+            const data = Bytes.fromBase64(characteristicData);
+            logger.debug(`received first data on C2: ${Bytes.toHex(data)}`);
+
+            if (data[0] === 0x65 && data[1] === 0x6c && data.length === 6) {
+                // Check if the first two bytes and length match the Matter handshake
+                logger.info(`Received Matter handshake response: ${Bytes.toHex(data)}.`);
+                btpHandshakeTimeout.stop();
+                resolver(data);
+            }
+        });
+
+        const handshakeResponse = await handshakeResponseReceivedPromise;
+        handshakeReceived = true;
+        handshakeSubscription.remove();
+
+        let connectionCloseExpected = false;
+        const btpSession = await BtpSessionHandler.createAsCentral(
+            new Uint8Array(handshakeResponse),
+            // callback to write data to characteristic C1
+            async data => {
+                characteristicC1ForWrite = await characteristicC1ForWrite.writeWithResponse(Bytes.toBase64(data));
+            },
+            // callback to disconnect the BLE connection
+            async () => {
+                connectionCloseExpected = true;
+                dataSubscription.remove();
+                await peripheral.cancelConnection();
+                logger.debug("disconnected from peripheral");
+            },
+
+            // callback to forward decoded and de-assembled Matter messages to ExchangeManager
+            async data => {
+                if (onMatterMessageListener === undefined) {
+                    throw new InternalError(`No listener registered for Matter messages`);
+                }
+                onMatterMessageListener(bleChannel, data);
+            },
+        );
+
+        const dataSubscription = characteristicC2ForSubscribe.monitor((error, characteristic) => {
+            if (error !== null || characteristic === null) {
+                if (error instanceof ReactNativeBleError && error.errorCode === 2 && connectionCloseExpected) {
+                    // Subscription got removed and received, all good
+                    return;
+                }
+                logger.debug("Error while monitoring C2 characteristic", error);
+                return;
+            }
+            const characteristicData = characteristic.value;
+            if (characteristicData === null) {
+                logger.debug("C2 characteristic value is null");
+                return;
+            }
+            const data = Bytes.fromBase64(characteristicData);
+            logger.debug(`received data on C2: ${Bytes.toHex(data)}`);
+
+            void btpSession.handleIncomingBleData(new Uint8Array(data));
+        });
+
+        const bleChannel = new ReactNativeBleChannel(peripheral, btpSession);
+        return bleChannel;
+    }
+
+    private connected = true;
+    private disconnectSubscription: Subscription;
+
+    constructor(
+        private readonly peripheral: Device,
+        private readonly btpSession: BtpSessionHandler,
+    ) {
+        super();
+        this.disconnectSubscription = peripheral.onDisconnected(error => {
+            logger.debug(`Disconnected from peripheral ${peripheral.id}: ${error}`);
+            this.connected = false;
+            this.disconnectSubscription.remove();
+            void this.btpSession.close();
+        });
+    }
+
+    /**
+     * Send a Matter message to the connected device - need to do BTP assembly first.
+     *
+     * @param data
+     */
+    async send(data: Uint8Array) {
+        if (!this.connected) {
+            logger.debug("Cannot send data because not connected to peripheral.");
+            return;
+        }
+        if (this.btpSession === undefined) {
+            throw new BtpFlowError(`Cannot send data, no BTP session initialized`);
+        }
+        await this.btpSession.sendMatterMessage(data);
+    }
+
+    // Channel<Uint8Array>
+    get name() {
+        return `ble://${this.peripheral.id}`;
+    }
+
+    async close() {
+        await this.btpSession.close();
+        this.disconnectSubscription.remove();
+        await this.peripheral.cancelConnection();
+    }
+}

package/src/ble/ReactNativeBleClient.ts

@@ -0,0 +1,132 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, Logger, MatterError } from "#general";
+import { BLE_MATTER_SERVICE_UUID } from "#protocol";
+import { BleError, BleErrorCode, BleManager, State as BluetoothState, Device } from "react-native-ble-plx";
+
+const logger = Logger.get("ReactNativeBleClient");
+
+export class BluetoothUnauthorizedError extends MatterError {}
+export class BluetoothUnsupportedError extends MatterError {}
+
+export class ReactNativeBleClient {
+    private readonly bleManager = new BleManager();
+    private readonly discoveredPeripherals = new Map<string, { peripheral: Device; matterServiceData: Uint8Array }>();
+    private shouldScan = false;
+    private isScanning = false;
+    private bleState = BluetoothState.Unknown;
+    private deviceDiscoveredCallback: ((peripheral: Device, manufacturerData: Uint8Array) => void) | undefined;
+
+    constructor() {
+        // this.bleMnager.setLogLevel(LogLevel.Verbose)
+        const subscription = this.bleManager.onStateChange(state => {
+            this.bleState = state;
+            logger.debug(`BLE state changed to ${state}`);
+            switch (state) {
+                case BluetoothState.PoweredOff:
+                    this.bleManager.enable().catch(error => {
+                        subscription.remove();
+                        if (error instanceof BleError && error.errorCode === BleErrorCode.BluetoothUnauthorized) {
+                            throw new BluetoothUnauthorizedError("Bluetooth is unauthorized");
+                        }
+                        throw error;
+                    });
+                    break;
+                case BluetoothState.PoweredOn:
+                    subscription.remove();
+                    if (this.shouldScan) {
+                        void this.startScanning();
+                    }
+                    break;
+                case BluetoothState.Unauthorized:
+                    subscription.remove();
+                    throw new BluetoothUnauthorizedError("Bluetooth is unauthorized");
+                case BluetoothState.Unsupported:
+                    subscription.remove();
+                    throw new BluetoothUnsupportedError("Bluetooth is unsupported");
+                default:
+                    logger.error("Unexpected BLE state", state);
+                    subscription.remove();
+                    void this.stopScanning();
+            }
+        });
+    }
+
+    public setDiscoveryCallback(callback: (peripheral: Device, manufacturerData: Uint8Array) => void) {
+        this.deviceDiscoveredCallback = callback;
+        for (const { peripheral, matterServiceData } of this.discoveredPeripherals.values()) {
+            this.deviceDiscoveredCallback(peripheral, matterServiceData);
+        }
+    }
+
+    public async startScanning() {
+        if (this.isScanning) return;
+
+        this.shouldScan = true;
+        if (this.bleState === BluetoothState.PoweredOn) {
+            logger.debug("Start BLE scanning for Matter Services ...");
+            this.isScanning = true;
+            await this.bleManager.startDeviceScan([BLE_MATTER_SERVICE_UUID], {}, (error, peripheral) => {
+                if (error !== null || peripheral === null) {
+                    this.isScanning = false;
+                    logger.error("Error while scanning for BLE devices", error);
+                    if (this.shouldScan) {
+                        this.startScanning().catch(error =>
+                            logger.error("Error while restarting scanning after error", error),
+                        );
+                    } else {
+                        this.stopScanning().catch(error =>
+                            logger.error("Error while stopping scanning after error", error),
+                        );
+                    }
+                    return;
+                }
+                this.handleDiscoveredDevice(peripheral);
+            });
+        } else {
+            logger.debug("ble state is not poweredOn ... delay scanning till poweredOn");
+        }
+    }
+
+    public async stopScanning() {
+        this.shouldScan = false;
+        logger.debug("Stop BLE scanning for Matter Services ...");
+        await this.bleManager.stopDeviceScan();
+        this.isScanning = false;
+    }
+
+    private handleDiscoveredDevice(peripheral: Device) {
+        // The advertisement data contains a name, power level (if available), certain advertised service uuids,
+        // as well as manufacturer data.
+        // {"localName":"MATTER-3840","serviceData":[{"uuid":"fff6","data":{"type":"Buffer","data":[0,0,15,241,255,1,128,0]}}],"serviceUuids":["fff6"],"solicitationServiceUuids":[],"serviceSolicitationUuids":[]}
+        logger.debug(
+            `Found peripheral ${peripheral.id} (${peripheral.localName}) with serviceData ${Logger.toJSON(peripheral.serviceData)}`,
+        );
+
+        if (!peripheral.isConnectable) {
+            logger.info(`Peripheral ${peripheral.id} is not connectable ... ignoring`);
+            return;
+        }
+        const matterServiceDataBase64 = peripheral.serviceData?.[BLE_MATTER_SERVICE_UUID];
+        if (matterServiceDataBase64 === undefined) {
+            logger.info(`Peripheral ${peripheral.id} does not advertise Matter Service ... ignoring`);
+            return;
+        }
+        const matterServiceData = Bytes.fromBase64(matterServiceDataBase64);
+        if (matterServiceData.length !== 8) {
+            logger.info(`Peripheral ${peripheral.id} does not advertise Matter Service ... ignoring`);
+            return;
+        }
+
+        this.discoveredPeripherals.set(peripheral.id, {
+            peripheral,
+            matterServiceData: matterServiceData,
+        });
+
+        this.deviceDiscoveredCallback?.(peripheral, matterServiceData);
+    }
+}

package/src/ble/export.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./BleReactNative.js";
+export * from "./BleScanner.js";

package/src/crypto/ReactNativeCrypto.ts

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { install } from "react-native-quick-crypto";
+
+install(); // Install the react-native crypto module
+
+import { CRYPTO_HASH_ALGORITHM, CryptoDsaEncoding, CryptoVerifyError } from "#general";
+import { NodeJsCrypto } from "#nodejs";
+import jwk2pem from "jwk-to-pem";
+
+// @ts-expect-error No types but all fine
+crypto.hkdf = (
+    digest: "sha1" | "sha256" | "sha384" | "sha512",
+    ikm: Uint8Array,
+    salt: Uint8Array,
+    info: Uint8Array,
+    keylen: number,
+) => {
+    const hashlen = parseInt(digest.substr(3), 10) >> 3 || 20;
+    const prk = crypto
+        // @ts-expect-error No types but all fine
+        .createHmac(digest, salt.byteLength ? salt : new Uint8Array(hashlen))
+        .update(ikm)
+        .digest();
+
+    // T(0) = empty
+    // T(1) = HMAC(PRK, T(0) | info | 0x01)
+    // T(2) = HMAC(PRK, T(1) | info | 0x02)
+    // T(3) = HMAC(PRK, T(2) | info | 0x03)
+    // ...
+    // T(N) = HMAC(PRK, T(N-1) | info | N)
+
+    const N = Math.ceil(keylen / hashlen);
+
+    // Single T buffer to accomodate T = T(1) | T(2) | T(3) | ... | T(N)
+    // with a little extra for info | N during T(N)
+    const T = new Uint8Array(hashlen * N + info.byteLength + 1);
+    let prev = 0;
+    let start = 0;
+    for (let c = 1; c <= N; c++) {
+        T.set(info, start);
+        T[start + info.byteLength] = c;
+
+        T.set(
+            crypto
+                // @ts-expect-error No types but all fine
+                .createHmac(digest, prk)
+                .update(T.subarray(prev, start + info.byteLength + 1))
+                .digest(),
+            start,
+        );
+
+        prev = start;
+        start += hashlen;
+    }
+
+    // OKM, releasing T
+    return T.slice(0, keylen);
+};
+
+export class CryptoReactNative extends NodeJsCrypto {
+    override sign(
+        privateKey: JsonWebKey,
+        data: Uint8Array | Uint8Array[],
+        dsaEncoding: CryptoDsaEncoding = "ieee-p1363",
+    ): Uint8Array {
+        // @ts-expect-error No types but all fine
+        const signer = crypto.createSign(CRYPTO_HASH_ALGORITHM);
+        if (Array.isArray(data)) {
+            data.forEach(chunk => signer.update(chunk));
+        } else {
+            signer.update(data);
+        }
+        return new Uint8Array(
+            signer.sign({
+                key: jwk2pem(privateKey as jwk2pem.JWK, { private: true }),
+                format: "pem",
+                type: "pkcs8",
+                dsaEncoding,
+            }),
+        );
+    }
+
+    override verify(
+        publicKey: JsonWebKey,
+        data: Uint8Array,
+        signature: Uint8Array,
+        dsaEncoding: CryptoDsaEncoding = "ieee-p1363",
+    ) {
+        // @ts-expect-error No types but all fine
+        const verifier = crypto.createVerify(CRYPTO_HASH_ALGORITHM);
+        verifier.update(data);
+        const success = verifier.verify(
+            {
+                key: jwk2pem(publicKey as jwk2pem.JWK),
+                format: "pem",
+                type: "spki",
+                dsaEncoding,
+            },
+            signature,
+        );
+        if (!success) throw new CryptoVerifyError("Signature verification failed");
+    }
+}

package/src/crypto/export.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./ReactNativeCrypto.js";

package/src/crypto/register.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Crypto, NoProviderError, singleton } from "@matter/general";
+import { CryptoReactNative } from "./ReactNativeCrypto.js";
+
+// Check if Crypto singleton is already registered and auto register if not
+try {
+    Crypto.get();
+} catch (error) {
+    NoProviderError.accept(error);
+    Crypto.get = singleton(() => new CryptoReactNative());
+}

package/src/environment/ReactNativeEnvironment.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Environment, Network, StorageService, VariableService } from "#general";
+import { NetworkReactNative } from "../net/NetworkReactNative.js";
+import { StorageBackendAsyncStorage } from "../storage/StorageBackendAsyncStorage.js";
+
+/**
+ * This is the default environment implementation for React-native:
+ *
+ * - Uses AsyncStorage for storage
+ */
+export function ReactNativeEnvironment() {
+    const env = new Environment("default");
+
+    loadVariables(env);
+    configureStorage(env);
+    configureNetwork(env);
+
+    return env;
+}
+
+function loadVariables(env: Environment) {
+    const vars = env.vars;
+
+    // Install defaults
+    vars.addConfigStyle(getDefaults(vars));
+}
+
+function configureStorage(env: Environment) {
+    const service = env.get(StorageService);
+
+    env.vars.use(() => {
+        service.location = "Memory";
+    });
+
+    service.factory = namespace => new StorageBackendAsyncStorage(namespace);
+}
+
+function configureNetwork(env: Environment) {
+    env.set(Network, new NetworkReactNative());
+}
+
+export function getDefaults(vars: VariableService) {
+    const envName = vars.get("environment", "default");
+
+    return {
+        environment: envName,
+    };
+}

package/src/environment/export.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./ReactNativeEnvironment.js";

package/src/environment/register.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Environment } from "@project-chip/matter.js/environment";
+import { ReactNativeEnvironment } from "./ReactNativeEnvironment.js";
+
+// Mainly import TextEncoder and TextDecoder polyfill
+// @ts-expect-error No types but all fine
+import { polyfill } from "react-native-polyfill-globals/src/encoding";
+
+polyfill();
+
+Environment.default = ReactNativeEnvironment();

package/src/export.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import "./net/register.js";
+
+import "./crypto/register.js";
+
+import "./environment/register.js";