@matter/protocol 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/peer/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./ControllerCommissioner.js";
+export * from "./ControllerCommissioningFlow.js";
+export * from "./ControllerDiscovery.js";
+export * from "./OperationalPeer.js";
+export * from "./PeerAddress.js";
+export * from "./PeerSet.js";
+export * from "./PeerStore.js";

package/src/protocol/ChannelManager.ts

@@ -0,0 +1,168 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Channel, Environment, Environmental, Logger, MatterError } from "#general";
+import { PeerAddress, PeerAddressMap } from "#peer/PeerAddress.js";
+import { SecureSession } from "../session/SecureSession.js";
+import { Session } from "../session/Session.js";
+import { MessageChannel } from "./ExchangeManager.js";
+
+const logger = Logger.get("ChannelManager");
+
+export class NoChannelError extends MatterError {}
+
+export class ChannelManager {
+    readonly #channels = new PeerAddressMap<MessageChannel[]>();
+    readonly #paseChannels = new Map<Session, MessageChannel>();
+    #caseSessionsPerFabricAndNode: number;
+
+    // TODO evaluate with controller the effects of limiting the entries just for FabricIndex and not also NodeId
+    constructor(caseSessionsPerFabricAndNode = 3) {
+        this.#caseSessionsPerFabricAndNode = caseSessionsPerFabricAndNode;
+    }
+
+    [Environmental.create](env: Environment) {
+        const instance = new ChannelManager();
+        env.set(ChannelManager, this);
+        return instance;
+    }
+
+    set caseSessionsPerFabricAndNode(count: number) {
+        this.#caseSessionsPerFabricAndNode = count;
+    }
+
+    #findLeastActiveChannel(channels: MessageChannel[]) {
+        let oldest = channels[0];
+        for (const channel of channels) {
+            if (channel.session.timestamp < oldest.session.timestamp) {
+                oldest = channel;
+            }
+        }
+        return oldest;
+    }
+
+    async setChannel(address: PeerAddress, channel: MessageChannel) {
+        channel.closeCallback = async () => this.removeChannel(address, channel.session);
+        const currentChannels = this.#channels.get(address) ?? [];
+        currentChannels.push(channel);
+        this.#channels.set(address, currentChannels);
+        if (currentChannels.length > this.#caseSessionsPerFabricAndNode) {
+            const oldestChannel = this.#findLeastActiveChannel(currentChannels);
+
+            const { session: oldSession } = oldestChannel;
+            // Should always be the case
+            if (channel.session.id !== oldSession.id) {
+                await oldSession.destroy(false, false);
+            }
+            logger.info(`Close oldest channel for fabric ${PeerAddress(address)} (from session ${oldSession.id})`);
+            await oldestChannel.close();
+        }
+    }
+
+    hasChannel(address: PeerAddress) {
+        return !!this.#channels.get(address)?.length;
+    }
+
+    getChannel(address: PeerAddress, session?: Session) {
+        let results = this.#channels.get(address) ?? [];
+        if (session !== undefined) {
+            results = results.filter(channel => channel.session.id === session.id);
+        }
+        if (results.length === 0)
+            throw new NoChannelError(
+                `Can't find a channel to ${PeerAddress(address)}${session !== undefined ? ` session ${session.id}` : ""}`,
+            );
+        return results[results.length - 1]; // Return the latest added channel (or the one belonging to the session requested)
+    }
+
+    /**
+     * Returns the last established session for a Fabric and Node
+     */
+    getChannelForSession(session: Session) {
+        if (session.isSecure && !session.isPase) {
+            const secureSession = session as SecureSession;
+            const fabric = secureSession.fabric;
+            const nodeId = secureSession.peerNodeId;
+            if (fabric === undefined) {
+                return this.#paseChannels.get(session);
+            }
+            return this.getChannel(fabric.addressOf(nodeId), session);
+        }
+        return this.#paseChannels.get(session);
+    }
+
+    async removeAllNodeChannels(address: PeerAddress) {
+        const channelsToRemove = this.#channels.get(address) ?? [];
+        for (const channel of channelsToRemove) {
+            await channel.close();
+        }
+    }
+
+    async removeChannel(address: PeerAddress, session: Session) {
+        const fabricChannels = this.#channels.get(address) ?? [];
+        const channelEntryIndex = fabricChannels.findIndex(
+            ({ session: entrySession }) => entrySession.id === session.id,
+        );
+        if (channelEntryIndex === -1) {
+            // Seems already removed
+            return;
+        }
+        const channelEntry = fabricChannels.splice(channelEntryIndex, 1)[0];
+        if (channelEntry === undefined) {
+            return;
+        }
+        await channelEntry.close();
+        this.#channels.set(address, fabricChannels);
+    }
+
+    private getOrCreateAsPaseChannel(byteArrayChannel: Channel<Uint8Array>, session: Session) {
+        const msgChannel = new MessageChannel(
+            byteArrayChannel,
+            session,
+            async () => void this.#paseChannels.delete(session),
+        );
+        this.#paseChannels.set(session, msgChannel);
+        return msgChannel;
+    }
+
+    async getOrCreateChannel(byteArrayChannel: Channel<Uint8Array>, session: Session) {
+        if (!session.isSecure) {
+            return this.getOrCreateAsPaseChannel(byteArrayChannel, session);
+        }
+        const secureSession = session as SecureSession;
+        const fabric = secureSession.fabric;
+        const nodeId = secureSession.peerNodeId;
+        if (fabric === undefined) {
+            return this.getOrCreateAsPaseChannel(byteArrayChannel, session);
+        }
+
+        // Try to get
+        const address = fabric.addressOf(nodeId);
+        try {
+            return this.getChannel(address, session);
+        } catch (e) {
+            NoChannelError.accept(e);
+        }
+
+        // Need to create
+        const result = new MessageChannel(byteArrayChannel, session, async () => this.removeChannel(address, session));
+        await this.setChannel(address, result);
+        return result;
+    }
+
+    async close() {
+        for (const channel of this.#paseChannels.values()) {
+            await channel.close();
+        }
+        this.#paseChannels.clear();
+        for (const channels of this.#channels.values()) {
+            for (const channel of channels) {
+                await channel.close();
+            }
+        }
+        this.#channels.clear();
+    }
+}

package/src/protocol/DeviceAdvertiser.ts

@@ -0,0 +1,208 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { CommissioningMode, CommissioningModeInstanceData, InstanceBroadcaster } from "#common/InstanceBroadcaster.js";
+import { Fabric } from "#fabric/Fabric.js";
+import { FabricManager } from "#fabric/FabricManager.js";
+import {
+    AsyncObservable,
+    Diagnostic,
+    Environment,
+    Environmental,
+    Logger,
+    Mutex,
+    ObserverGroup,
+    Time,
+    Timer,
+} from "#general";
+import { SessionManager } from "#session/SessionManager.js";
+import { DEVICE_ANNOUNCEMENT_DURATION_MS, DEVICE_ANNOUNCEMENT_INTERVAL_MS } from "#types";
+
+const logger = Logger.get("DeviceAdvertiser");
+
+/**
+ * Interfaces the {@link DeviceAdvertiser} with other components.
+ */
+export interface DeviceAdvertiserContext {
+    fabrics: FabricManager;
+    sessions: SessionManager;
+}
+
+/**
+ * Advertises a node for commissioning (if uncommissioned) or operationally (if commissioned).
+ */
+export class DeviceAdvertiser {
+    readonly #context: DeviceAdvertiserContext;
+    readonly #broadcasters = new Set<InstanceBroadcaster>();
+    readonly #timedOut = AsyncObservable<[]>();
+    readonly #operationalModeEnded = new AsyncObservable<[]>();
+    readonly #observers = new ObserverGroup();
+    #interval: Timer;
+    #startTime: number | null = null;
+    #isClosing = false;
+    #commissioningMode = CommissioningMode.NotCommissioning;
+
+    // Currently we do not put much effort into synchronizing announcements as it probably isn't really necessary.  But
+    // this mutex prevents automated announcements from piling up and allows us to ensure announcements are complete on
+    // close
+    #mutex = new Mutex(this);
+
+    constructor(context: DeviceAdvertiserContext) {
+        this.#context = context;
+
+        this.#interval = Time.getPeriodicTimer("Server node announcement", DEVICE_ANNOUNCEMENT_INTERVAL_MS, () =>
+            // Announcement needs to await a previous announcement because otherwise in testing at least announcement
+            // may crash if started simultaneously
+            this.#mutex.run(() => this.advertise()),
+        );
+
+        this.#observers.on(this.#context.fabrics.events.deleted, async () => {
+            if (this.#context.fabrics.getFabrics().length === 0) {
+                // Last fabric got removed, so expire all announcements
+                await this.#exitOperationalMode();
+            }
+        });
+
+        this.#observers.on(this.#context.sessions.resubmissionStarted, (nodeId?) => {
+            logger.debug(`Resubmission started, re-announce node ${nodeId}`);
+            this.advertise(true).catch(error => logger.warn("Error sending announcement:", error));
+        });
+
+        this.#observers.on(this.#context.sessions.subscriptionsChanged, (_session, subscription) => {
+            if (subscription.isCanceledByPeer) {
+                logger.debug(`Subscription canceled by peer, re-announce`);
+                this.startAdvertising().catch(error => logger.warn("Error sending announcement:", error));
+            }
+        });
+    }
+
+    [Environmental.create](env: Environment) {
+        const instance = new DeviceAdvertiser({
+            fabrics: env.get(FabricManager),
+            sessions: env.get(SessionManager),
+        });
+        env.set(DeviceAdvertiser, instance);
+        return instance;
+    }
+
+    /**
+     * Emitted when the advertising window closes with no response.
+     */
+    get timedOut() {
+        return this.#timedOut;
+    }
+
+    /**
+     * Emitted when the device stops advertising due to decommissioning.
+     */
+    get operationalModeEnded() {
+        return this.#operationalModeEnded;
+    }
+
+    async enterCommissioningMode(mode: CommissioningMode, deviceData: CommissioningModeInstanceData) {
+        this.#commissioningMode = mode;
+        for (const broadcaster of this.#broadcasters) {
+            await broadcaster.setCommissionMode(mode, deviceData);
+        }
+        await this.startAdvertising();
+    }
+
+    async exitCommissioningMode() {
+        this.#commissioningMode = CommissioningMode.NotCommissioning;
+        this.#interval.stop();
+        this.#startTime = null;
+        for (const broadcaster of this.#broadcasters) {
+            await broadcaster.expireCommissioningAnnouncement();
+        }
+    }
+
+    async startAdvertising() {
+        if (this.#isClosing) return;
+        if (this.#interval.isRunning) {
+            this.#interval.stop();
+        }
+        this.#startTime = Time.nowMs();
+        this.#interval.start();
+        await this.advertise();
+    }
+
+    async advertise(once = false) {
+        if (!once) {
+            // Stop announcement if duration is reached
+            if (this.#startTime !== null && Time.nowMs() - this.#startTime > DEVICE_ANNOUNCEMENT_DURATION_MS) {
+                logger.debug("Announcement duration reached, stop announcing");
+                await this.#timedOut.emit();
+                return;
+            }
+
+            if (this.#commissioningMode !== CommissioningMode.NotCommissioning) {
+                // Re-Announce but do not reset Fabrics
+                for (const broadcaster of this.#broadcasters) {
+                    await broadcaster.announce();
+                }
+                return;
+            }
+        }
+
+        const fabrics = this.#context.fabrics.getFabrics();
+
+        if (fabrics.length) {
+            let fabricsWithoutSessions = 0;
+            for (const fabric of fabrics) {
+                const session = this.#context.sessions.getSessionForNode(fabric.addressOf(fabric.rootNodeId));
+                if (session === undefined || !session.isSecure || session.subscriptions.size === 0) {
+                    fabricsWithoutSessions++;
+                    logger.debug("Announcing", Diagnostic.dict({ fabric: fabric.fabricId }));
+                }
+            }
+            for (const broadcaster of this.#broadcasters) {
+                await broadcaster.setFabrics(fabrics);
+                if (fabricsWithoutSessions > 0 || this.#commissioningMode !== CommissioningMode.NotCommissioning) {
+                    await broadcaster.announce();
+                }
+            }
+        } else {
+            // Expire operational Fabric announcements (if fabric got just deleted)
+            await this.#exitOperationalMode();
+            await this.#operationalModeEnded.emit();
+        }
+    }
+
+    async advertiseFabrics(fabrics: Fabric[], expireCommissioningAnnouncement = false) {
+        for (const broadcaster of this.#broadcasters) {
+            await broadcaster.setFabrics(fabrics, expireCommissioningAnnouncement);
+            await broadcaster.announce();
+        }
+    }
+
+    async #exitOperationalMode() {
+        for (const broadcaster of this.#broadcasters) {
+            await broadcaster.expireFabricAnnouncement();
+        }
+    }
+
+    async close() {
+        await this.#mutex;
+        this.#observers.close();
+        for (const broadcaster of this.#broadcasters) {
+            await broadcaster.close();
+        }
+    }
+
+    hasBroadcaster(broadcaster: InstanceBroadcaster) {
+        return this.#broadcasters.has(broadcaster);
+    }
+
+    addBroadcaster(broadcaster: InstanceBroadcaster) {
+        this.#broadcasters.add(broadcaster);
+    }
+
+    async deleteBroadcaster(broadcaster: InstanceBroadcaster) {
+        if (this.#broadcasters.delete(broadcaster)) {
+            await broadcaster.expireAllAnnouncements();
+        }
+    }
+}

package/src/protocol/DeviceCommissioner.ts

@@ -0,0 +1,280 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { AdministratorCommissioning } from "#clusters/administrator-commissioning";
+import { FailsafeContext } from "#common/FailsafeContext.js";
+import { CommissioningMode } from "#common/InstanceBroadcaster.js";
+import { FabricManager } from "#fabric/FabricManager.js";
+import {
+    Crypto,
+    Diagnostic,
+    Environment,
+    Environmental,
+    InternalError,
+    Lifecycle,
+    Logger,
+    MatterFlowError,
+    ObserverGroup,
+} from "#general";
+import { SecureChannelProtocol } from "#securechannel/SecureChannelProtocol.js";
+import { PaseServer, SessionManager } from "#session/index.js";
+import { CommissioningOptions, StatusCode, StatusResponseError } from "#types";
+import type { ControllerCommissioner } from "../peer/ControllerCommissioner.js";
+import { DeviceAdvertiser } from "./DeviceAdvertiser.js";
+
+const logger = Logger.get("DeviceCommissioner");
+
+/**
+ * The component allows commissioning configuration to change after the {@link DeviceCommissioner} is initialized.
+ */
+export abstract class CommissioningConfigProvider {
+    abstract values: CommissioningOptions.Configuration;
+}
+
+/**
+ * Interfaces the {@link DeviceCommissioner} with other components.
+ */
+export interface DeviceCommissionerContext {
+    fabrics: FabricManager;
+    sessions: SessionManager;
+    advertiser: DeviceAdvertiser;
+    secureChannelProtocol: SecureChannelProtocol;
+    commissioningConfig: CommissioningConfigProvider;
+}
+
+/**
+ * Implements commissioning for devices.
+ *
+ * Note this implements commissioning for a *local* device; use {@link ControllerCommissioner} to commission a *remote*
+ * device.
+ */
+export class DeviceCommissioner {
+    #context: DeviceCommissionerContext;
+    #failsafeContext?: FailsafeContext;
+    #windowStatus = AdministratorCommissioning.CommissioningWindowStatus.WindowNotOpen;
+    #activeDiscriminator?: number;
+    #activeCommissioningEndCallback?: () => void;
+    #observers = new ObserverGroup(this);
+
+    constructor(context: DeviceCommissionerContext) {
+        this.#context = context;
+
+        this.#observers.on(this.#context.advertiser.timedOut, this.endCommissioning);
+
+        // If a commissioning window is open then we reannounce this because it was ended as fabric got added
+        this.#observers.on(this.#context.fabrics.events.deleted, this.reactivateAdvertiser);
+
+        // No fabric paired yet, so announce as "ready for commissioning"
+        this.#observers.on(this.#context.advertiser.operationalModeEnded, this.allowBasicCommissioning);
+
+        // Cancel commissioning when there are too many PASE errors
+        this.#observers.on(this.#context.secureChannelProtocol.tooManyPaseErrors, async () => {
+            logger.info("Maximum number of PASE pairing errors reached, canceling commissioning");
+            await this.endCommissioning();
+        });
+
+        this.#observers.on(this.#context.sessions.sessions.deleted, session => {
+            const currentFabricIndex = session.fabric?.fabricIndex;
+
+            // Verify if the session associated fabric still exists
+            const existingSessionFabric =
+                currentFabricIndex === undefined
+                    ? undefined
+                    : this.#context.fabrics.findByIndex(currentFabricIndex)?.fabricIndex;
+
+            // When a session closes, announce existing fabrics again so that controller can detect the device again.
+            // When session was closed and no fabric exist anymore then this is triggering a factory reset in upper
+            // layer and it would be not good to announce a commissionable device and then reset that again with the
+            // factory reset
+            if (this.#context.fabrics.getFabrics().length > 0 || session.isPase || !existingSessionFabric) {
+                this.#context.advertiser
+                    .startAdvertising()
+                    .catch(error => logger.warn(`Error while announcing`, error));
+            }
+        });
+    }
+
+    [Environmental.create](env: Environment) {
+        const instance = new DeviceCommissioner({
+            fabrics: env.get(FabricManager),
+            sessions: env.get(SessionManager),
+            advertiser: env.get(DeviceAdvertiser),
+            secureChannelProtocol: env.get(SecureChannelProtocol),
+            commissioningConfig: env.get(CommissioningConfigProvider),
+        });
+        env.set(DeviceCommissioner, instance);
+        return instance;
+    }
+
+    get failsafeContext() {
+        this.assertFailsafeArmed();
+        return this.#failsafeContext!;
+    }
+
+    async allowEnhancedCommissioning(
+        discriminator: number,
+        paseServer: PaseServer,
+        commissioningEndCallback: () => void,
+    ) {
+        if (this.#windowStatus === AdministratorCommissioning.CommissioningWindowStatus.BasicWindowOpen) {
+            throw new MatterFlowError(
+                "Basic commissioning window is already open! Cannot set Enhanced commissioning mode.",
+            );
+        }
+
+        this.#context.secureChannelProtocol.setPaseCommissioner(paseServer);
+        await this.#becomeCommissionable(
+            AdministratorCommissioning.CommissioningWindowStatus.EnhancedWindowOpen,
+            commissioningEndCallback,
+            discriminator,
+        );
+    }
+
+    async allowBasicCommissioning(commissioningEndCallback?: () => void) {
+        if (this.#windowStatus === AdministratorCommissioning.CommissioningWindowStatus.EnhancedWindowOpen) {
+            throw new MatterFlowError(
+                "Enhanced commissioning window is already open! Cannot set Basic commissioning mode.",
+            );
+        }
+
+        this.#context.secureChannelProtocol.setPaseCommissioner(
+            await PaseServer.fromPin(this.#context.sessions, this.#context.commissioningConfig.values.passcode, {
+                iterations: 1000,
+                salt: Crypto.get().getRandomData(32),
+            }),
+        );
+
+        await this.#becomeCommissionable(
+            AdministratorCommissioning.CommissioningWindowStatus.BasicWindowOpen,
+            commissioningEndCallback,
+        );
+    }
+
+    async beginTimed(failsafeContext: FailsafeContext) {
+        await failsafeContext.construction;
+
+        this.#failsafeContext = failsafeContext;
+
+        this.#context.fabrics.events.added.on(fabric => {
+            const fabrics = this.#context.fabrics.getFabrics();
+            this.#context.advertiser
+                .advertiseFabrics(fabrics, true)
+                .catch(error =>
+                    logger.warn(`Error sending Fabric announcement for Index ${fabric.fabricIndex}`, error),
+                );
+            logger.info("Announce done", Diagnostic.dict({ fabric: fabric.fabricId, fabricIndex: fabric.fabricIndex }));
+        });
+
+        failsafeContext.commissioned.on(async () => await this.endCommissioning());
+
+        failsafeContext.construction.change.on(status => {
+            if (status === Lifecycle.Status.Destroyed) {
+                this.#failsafeContext = undefined;
+            }
+        });
+    }
+
+    get isFailsafeArmed() {
+        return this.#failsafeContext !== undefined;
+    }
+
+    assertFailsafeArmed(message?: string) {
+        if (this.isFailsafeArmed) return;
+        throw new StatusResponseError(
+            message ?? "Failsafe timer needs to be armed to execute this action.",
+            StatusCode.FailsafeRequired,
+        );
+    }
+
+    reactivateAdvertiser() {
+        if (this.#windowStatus === AdministratorCommissioning.CommissioningWindowStatus.WindowNotOpen) {
+            return;
+        }
+        this.#enterCommissioningMode(this.#windowStatus, this.#activeDiscriminator).catch(error =>
+            logger.warn("Error sending announcement:", error),
+        );
+    }
+
+    async #enterCommissioningMode(
+        windowStatus: AdministratorCommissioning.CommissioningWindowStatus,
+        discriminator?: number,
+    ) {
+        this.#windowStatus = windowStatus;
+        const commissioningConfig = this.#context.commissioningConfig.values;
+        await this.#context.advertiser.enterCommissioningMode(
+            windowStatus === AdministratorCommissioning.CommissioningWindowStatus.EnhancedWindowOpen
+                ? CommissioningMode.Enhanced
+                : CommissioningMode.Basic,
+            {
+                ...commissioningConfig.productDescription,
+                discriminator: discriminator ?? commissioningConfig.discriminator,
+            },
+        );
+    }
+
+    async #becomeCommissionable(
+        windowStatus: AdministratorCommissioning.CommissioningWindowStatus,
+        activeCommissioningEndCallback?: () => void,
+        discriminator?: number,
+    ) {
+        if (
+            this.#windowStatus === windowStatus &&
+            (discriminator === undefined || discriminator === this.#activeDiscriminator)
+        ) {
+            // We want to re-announce
+            return this.reactivateAdvertiser();
+        }
+        if (this.#windowStatus !== AdministratorCommissioning.CommissioningWindowStatus.WindowNotOpen) {
+            throw new InternalError(`Commissioning window already open with different mode (${this.#windowStatus})!`);
+        }
+        if (this.#activeCommissioningEndCallback !== undefined) {
+            throw new InternalError("Commissioning window already open with different callback!");
+        }
+        this.#activeCommissioningEndCallback = activeCommissioningEndCallback;
+        this.#activeDiscriminator = discriminator;
+
+        // MDNS is sent in parallel
+        // TODO - untracked promise
+        this.#enterCommissioningMode(windowStatus, discriminator).catch(error =>
+            logger.warn("Error sending announcement:", error),
+        );
+    }
+
+    async endCommissioning() {
+        if (this.#windowStatus === AdministratorCommissioning.CommissioningWindowStatus.WindowNotOpen) {
+            return;
+        }
+
+        logger.debug("Commissioning mode ended, stop announcements.");
+        // Remove PASE responder when we close enhanced commissioning window or node is commissioned
+        if (
+            this.#windowStatus === AdministratorCommissioning.CommissioningWindowStatus.EnhancedWindowOpen ||
+            this.#context.fabrics.getFabrics().length > 0
+        ) {
+            this.#context.secureChannelProtocol.removePaseCommissioner();
+        }
+        this.#windowStatus = AdministratorCommissioning.CommissioningWindowStatus.WindowNotOpen;
+
+        if (this.#activeCommissioningEndCallback !== undefined) {
+            const activeCommissioningEndCallback = this.#activeCommissioningEndCallback;
+            this.#activeCommissioningEndCallback = undefined;
+            activeCommissioningEndCallback();
+        }
+
+        await this.#context.advertiser.exitCommissioningMode();
+
+        logger.info("All announcements stopped");
+    }
+
+    async close() {
+        this.#observers.close();
+        await this.endCommissioning();
+        if (this.#failsafeContext) {
+            await this.#failsafeContext.close();
+            this.#failsafeContext = undefined;
+        }
+    }
+}