@matter/node 0.14.0 → 0.14.1-alpha.0-20250606-a9bcd03f9

package/src/behavior/system/network/ServerGroupNetworking.ts

@@ -0,0 +1,150 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Construction, Environment, InternalError, Logger, ObserverGroup, UdpInterface } from "#general";
+import { Fabric, FabricManager } from "#protocol";
+import { FabricIndex, GroupId } from "#types";
+
+const logger = Logger.get("ServerGroupNetworking");
+
+export class ServerGroupNetworking {
+    #construction: Construction<ServerGroupNetworking>;
+    #udpInterface: UdpInterface;
+    #activeGroupMemberships = new Map<FabricIndex, Map<GroupId, string>>();
+    #fabricObservers = new Map<FabricIndex, ObserverGroup>();
+    #observers = new ObserverGroup(this);
+
+    get construction() {
+        return this.#construction;
+    }
+
+    /**
+     * The server group networking is not implemented in the Node.js environment.
+     * This class is a placeholder to maintain compatibility with the Matter.js architecture.
+     */
+    constructor(env: Environment, udpInterface: UdpInterface) {
+        this.#udpInterface = udpInterface;
+        this.#construction = Construction(this);
+        this.#construction.start(env);
+    }
+
+    async [Construction.construct](env: Environment) {
+        const fabrics = env.get(FabricManager);
+
+        for (const fabric of fabrics) {
+            if (this.#activeGroupMemberships.has(fabric.fabricIndex)) {
+                throw new InternalError("Group transport interfaces already initialized for this fabric.");
+            }
+            for (const groupId of fabric.groups.groupKeyIdMap.keys()) {
+                await this.#addGroupMembership(groupId, fabric);
+            }
+
+            this.#registerFabricGroupObserver(fabric);
+        }
+
+        // When new fabric is added we register for group changes - new fabrics cannot have groups already configured
+        this.#observers.on(fabrics.events.added, async fabric => this.#registerFabricGroupObserver(fabric));
+
+        // When fabric is deleted, we remove the group memberships
+        this.#observers.on(fabrics.events.deleted, async fabric => {
+            const fabricIndex = fabric.fabricIndex;
+            this.#observersForFabric(fabricIndex).close();
+            this.#fabricObservers.delete(fabricIndex);
+
+            const memberships = this.#activeGroupMemberships.get(fabricIndex);
+            if (memberships === undefined || memberships.size === 0) {
+                this.#activeGroupMemberships.delete(fabricIndex);
+                return;
+            }
+            for (const groupId of memberships.keys()) {
+                await this.#dropGroupMembership(groupId, fabric);
+            }
+            this.#activeGroupMemberships.delete(fabricIndex);
+        });
+
+        this.#observers.on(fabrics.events.updated, async fabric => {
+            const fabricIndex = fabric.fabricIndex;
+
+            this.#observersForFabric(fabricIndex).close();
+            this.#fabricObservers.delete(fabricIndex);
+            this.#registerFabricGroupObserver(fabric);
+
+            // Sync (add or remove as needed) by new group configuration
+            const { groupKeyIdMap } = fabric.groups;
+            for (const groupId of groupKeyIdMap.keys()) {
+                await this.#addGroupMembership(groupId, fabric);
+            }
+            const memberships = this.#activeGroupMemberships.get(fabricIndex) ?? new Map<GroupId, string>();
+            if (memberships.size !== 0) {
+                for (const groupId of memberships.keys()) {
+                    if (!groupKeyIdMap.has(groupId)) {
+                        await this.#dropGroupMembership(groupId, fabric);
+                    }
+                }
+            }
+        });
+    }
+
+    async #addGroupMembership(groupId: GroupId, fabric: Fabric) {
+        const fabricIndex = fabric.fabricIndex;
+        const memberships = this.#activeGroupMemberships.get(fabricIndex) ?? new Map<GroupId, string>();
+        if (memberships.has(groupId)) {
+            return;
+        }
+        const address = fabric.groups.multicastAddressFor(groupId);
+        logger.debug(
+            `Adding membership for group ${groupId} on fabric ${fabric.fabricId} (index ${fabricIndex}) with address ${address}`,
+        );
+        await this.#udpInterface.addMembership(address);
+        memberships.set(groupId, address);
+        this.#activeGroupMemberships.set(fabricIndex, memberships);
+    }
+
+    async #dropGroupMembership(groupId: GroupId, fabric: Fabric) {
+        const fabricIndex = fabric.fabricIndex;
+        const memberships = this.#activeGroupMemberships.get(fabricIndex);
+        if (memberships === undefined || memberships.size === 0) {
+            return;
+        }
+        const address = fabric.groups.multicastAddressFor(groupId);
+        logger.debug(
+            `Dropping membership for group ${groupId} on fabric ${fabric.fabricId} (index ${fabricIndex}) with address ${address}`,
+        );
+        await this.#udpInterface.dropMembership(address);
+        memberships.delete(groupId);
+        if (!memberships.size) {
+            this.#activeGroupMemberships.delete(fabricIndex);
+        }
+    }
+
+    #observersForFabric(fabricIndex: FabricIndex) {
+        let observers = this.#fabricObservers.get(fabricIndex);
+        if (observers === undefined) {
+            observers = new ObserverGroup(this);
+            this.#fabricObservers.set(fabricIndex, observers);
+        }
+        return observers;
+    }
+
+    #registerFabricGroupObserver(fabric: Fabric) {
+        const fabricIndex = fabric.fabricIndex;
+
+        const observers = this.#observersForFabric(fabricIndex);
+        observers.on(
+            fabric.groups.groupKeyIdMap.added,
+            async groupId => await this.#addGroupMembership(groupId, fabric),
+        );
+
+        observers.on(fabric.groups.groupKeyIdMap.deleted, async groupId => this.#dropGroupMembership(groupId, fabric));
+    }
+
+    close() {
+        this.#construction.close();
+        this.#observers.close();
+        this.#fabricObservers.forEach(observer => observer.close());
+        this.#activeGroupMemberships.clear();
+        this.#fabricObservers.clear();
+    }
+}

package/src/behavior/system/network/ServerNetworkRuntime.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { SubscriptionBehavior } from "#behavior/system/subscription/index.js";
+import { SubscriptionBehavior } from "#behavior/system/subscription/SubscriptionBehavior.js";
 import {
     Construction,
     InterfaceType,
@@ -20,7 +20,7 @@ import {
     UdpInterface,
 } from "#general";
 import type { ServerNode } from "#node/ServerNode.js";
-import { NodePeerAddressStore } from "#node/index.js";
+import { NodePeerAddressStore } from "#node/client/NodePeerAddressStore.js";
 import { InteractionServer } from "#node/server/InteractionServer.js";
 import {
     Ble,
@@ -43,6 +43,7 @@ import { CommissioningServer } from "../commissioning/CommissioningServer.js";
 import { ProductDescriptionServer } from "../product-description/ProductDescriptionServer.js";
 import { SessionsBehavior } from "../sessions/SessionsBehavior.js";
 import { NetworkRuntime } from "./NetworkRuntime.js";
+import { ServerGroupNetworking } from "./ServerGroupNetworking.js";
 
 const logger = Logger.get("ServerNetworkRuntime");
 
@@ -62,8 +63,10 @@ export class ServerNetworkRuntime extends NetworkRuntime {
     #mdnsBroadcaster?: MdnsInstanceBroadcaster;
     #bleBroadcaster?: InstanceBroadcaster;
     #bleTransport?: TransportInterface;
+    #ipv6UdpInterface?: UdpInterface;
     #observers = new ObserverGroup(this);
     #formerSubscriptionsHandled = false;
+    #groupNetworking?: ServerGroupNetworking;
 
     override get owner() {
         return super.owner as ServerNode;
@@ -148,15 +151,15 @@ export class ServerNetworkRuntime extends NetworkRuntime {
 
         const port = this.owner.state.network.port;
         try {
-            const ipv6Intf = await UdpInterface.create(
+            this.#ipv6UdpInterface = await UdpInterface.create(
                 this.owner.env.get(Network),
                 "udp6",
                 port ? port : undefined,
                 netconf.listeningAddressIpv6,
             );
-            interfaces.add(ipv6Intf);
+            interfaces.add(this.#ipv6UdpInterface);
 
-            await this.owner.set({ network: { operationalPort: ipv6Intf.port } });
+            await this.owner.set({ network: { operationalPort: this.#ipv6UdpInterface.port } });
         } catch (error) {
             NoAddressAvailableError.accept(error);
             logger.info(`IPv6 UDP interface not created because IPv6 is not available, but required my Matter.`);
@@ -285,6 +288,8 @@ export class ServerNetworkRuntime extends NetworkRuntime {
             maxPathsPerInvoke: this.owner.state.basicInformation.maxPathsPerInvoke,
         };
 
+        await this.#initializeGroupNetworking();
+
         // Install our interaction server
         const interactionServer = new InteractionServer(this.owner, env.get(SessionManager));
         env.set(InteractionServer, interactionServer);
@@ -359,6 +364,9 @@ export class ServerNetworkRuntime extends NetworkRuntime {
 
         await this.owner.prepareRuntimeShutdown();
 
+        this.#groupNetworking?.close();
+        this.#groupNetworking = undefined;
+
         // Now all sessions are closed, so we wait for Advertiser to be gone
         await advertisementShutdown;
 
@@ -393,4 +401,18 @@ export class ServerNetworkRuntime extends NetworkRuntime {
             agent.get(SubscriptionBehavior).reestablishFormerSubscriptions(env.get(InteractionServer)),
         );
     }
+
+    async #initializeGroupNetworking() {
+        if (this.#groupNetworking) {
+            logger.warn("Group networking already initialized, skipping.");
+            return;
+        }
+        if (this.#ipv6UdpInterface === undefined) {
+            logger.warn("No IPv6 UDP interface available, skipping group networking initialization.");
+            return;
+        }
+
+        this.#groupNetworking = new ServerGroupNetworking(this.owner.env, this.#ipv6UdpInterface);
+        await this.#groupNetworking.construction;
+    }
 }

package/src/behavior/system/sessions/SessionsBehavior.ts

@@ -6,7 +6,7 @@
 
 import { EventEmitter, Observable } from "#general";
 import type { ServerNode } from "#node/ServerNode.js";
-import { ExposedFabricInformation, SecureSession, SessionManager, Subscription } from "#protocol";
+import { ExposedFabricInformation, NodeSession, SessionManager, Subscription } from "#protocol";
 import { NodeId } from "#types";
 import { NodeLifecycle } from "../../../node/NodeLifecycle.js";
 import { Behavior } from "../../Behavior.js";
@@ -28,7 +28,7 @@ export class SessionsBehavior extends Behavior {
         this.reactTo((this.endpoint.lifecycle as NodeLifecycle).offline, this.#enterOfflineMode);
     }
 
-    #convertToExposedSession(session: SecureSession): SessionsBehavior.Session {
+    #convertToExposedSession(session: NodeSession): SessionsBehavior.Session {
         return {
             name: session.name,
             nodeId: session.nodeId,
@@ -49,7 +49,7 @@ export class SessionsBehavior extends Behavior {
         this.reactTo(sessions.subscriptionsChanged, this.#subscriptionsChanged, { lock: true });
     }
 
-    #sessionOpened(session: SecureSession) {
+    #sessionOpened(session: NodeSession) {
         if (session.isPase) {
             return;
         }
@@ -58,7 +58,7 @@ export class SessionsBehavior extends Behavior {
         this.events.opened.emit(exposedSession);
     }
 
-    #sessionClosed(session: SecureSession) {
+    #sessionClosed(session: NodeSession) {
         if (!(session.id in this.state.sessions)) {
             return;
         }
@@ -67,7 +67,7 @@ export class SessionsBehavior extends Behavior {
         this.events.closed.emit(this.#convertToExposedSession(session));
     }
 
-    #subscriptionsChanged(session: SecureSession, subscription: Subscription) {
+    #subscriptionsChanged(session: NodeSession, subscription: Subscription) {
         if (session.isPase) {
             return;
         }

package/src/behaviors/access-control/AccessControlServer.ts

@@ -15,6 +15,8 @@ import {
     AclEndpointContext,
     FabricManager,
     IncomingSubjectDescriptor,
+    NodeSession,
+    SecureSession,
 } from "#protocol";
 import {
     CaseAuthenticatedTag,
@@ -159,7 +161,7 @@ export class AccessControlServer extends AccessControlBehavior.with("Extension")
 
                 if (subjects !== null) {
                     for (const subject of subjects) {
-                        if (GroupId(subject) === GroupId.UNSPECIFIED_GROUP_ID) {
+                        if (GroupId(Number(subject)) === GroupId.NO_GROUP_ID) {
                             throw new StatusResponseError(
                                 "Subject must be a valid GroupId for Group ACLs",
                                 StatusCode.ConstraintError,
@@ -202,6 +204,21 @@ export class AccessControlServer extends AccessControlBehavior.with("Extension")
         }
     }
 
+    /**
+     * Determine and return the adminPassCodeId and adminNodeId from the node that initiated the ACL change.
+     * it is either the root node of the fabric or 0 if the session is undefined or a PASE session.
+     */
+    #adminDataFromSession(session: SecureSession | undefined) {
+        if (session === undefined || (NodeSession.is(session) && session.isPase)) {
+            return { adminPasscodeId: 0, adminNodeId: null };
+        }
+        const adminNodeId = session?.associatedFabric.rootNodeId;
+        if (adminNodeId === undefined) {
+            throw new InternalError("Admin Node ID is undefined, should never happen");
+        }
+        return { adminPasscodeId: null, adminNodeId };
+    }
+
     #handleAccessControlListChange(
         value: AccessControlTypes.AccessControlEntry[],
         oldValue: AccessControlTypes.AccessControlEntry[],
@@ -218,12 +235,7 @@ export class AccessControlServer extends AccessControlBehavior.with("Extension")
         if (relevantFabricIndex === undefined || this.events.accessControlEntryChanged === undefined) {
             return;
         }
-        const adminPasscodeId = session === undefined || session?.isPase ? 0 : null;
-        const adminNodeId = adminPasscodeId === null ? session?.associatedFabric.rootNodeId : null;
-        if (adminNodeId === undefined) {
-            // Should never happen
-            return;
-        }
+        const { adminPasscodeId, adminNodeId } = this.#adminDataFromSession(session);
         const fabricAcls = value.filter(entry => entry.fabricIndex === relevantFabricIndex);
         const oldFabricAcls = oldValue.filter(entry => entry.fabricIndex === relevantFabricIndex);
 
@@ -302,12 +314,7 @@ export class AccessControlServer extends AccessControlBehavior.with("Extension")
         if (relevantFabricIndex === undefined || this.events.accessControlExtensionChanged === undefined) {
             return;
         }
-        const adminPasscodeId = session === undefined || session?.isPase ? 0 : null;
-        const adminNodeId = adminPasscodeId === null ? session?.associatedFabric.rootNodeId : null;
-        if (adminNodeId === undefined) {
-            // Should never happen
-            return;
-        }
+        const { adminPasscodeId, adminNodeId } = this.#adminDataFromSession(session);
 
         const fabricExtensions = value.filter(entry => entry.fabricIndex === relevantFabricIndex);
         const oldFabricExtensions = oldValue.filter(entry => entry.fabricIndex === relevantFabricIndex);
@@ -360,7 +367,7 @@ export class AccessControlServer extends AccessControlBehavior.with("Extension")
             return [AccessLevel.View];
         }
 
-        return this.aclManager.getGrantedPrivileges(context.session, endpoint, location.cluster);
+        return this.aclManager.getGrantedPrivileges(context, endpoint, location.cluster);
     }
 
     /**

package/src/behaviors/color-control/ColorControlServer.ts

@@ -4,15 +4,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Behavior } from "#behavior/Behavior.js";
 import { ActionContext } from "#behavior/context/ActionContext.js";
-import { Behavior } from "#behavior/index.js";
 import { Transitions } from "#behavior/Transitions.js";
 import { GeneralDiagnosticsBehavior } from "#behaviors/general-diagnostics";
 import { OnOffServer } from "#behaviors/on-off";
 import { ColorControl } from "#clusters/color-control";
 import { GeneralDiagnostics } from "#clusters/general-diagnostics";
 import { Endpoint } from "#endpoint/Endpoint.js";
-import { RootEndpoint } from "#endpoints/root";
 import {
     addValueWithOverflow,
     AsyncObservable,
@@ -21,6 +20,7 @@ import {
     Logger,
     MaybePromise,
 } from "#general";
+import { ServerNode } from "#node/ServerNode.js";
 import { Val } from "#protocol";
 import { ClusterType, StatusCode, StatusResponseError, TypeFromPartialBitSchema } from "#types";
 import { ColorControlBehavior } from "./ColorControlBehavior.js";
@@ -1726,8 +1726,8 @@ export class ColorControlBaseServer extends ColorControlBase {
     }
 
     #getBootReason() {
-        const rootEndpoint = this.endpoint.ownerOfType(RootEndpoint);
-        if (rootEndpoint !== undefined && rootEndpoint.behaviors.has(GeneralDiagnosticsBehavior)) {
+        const rootEndpoint = this.env.get(ServerNode);
+        if (rootEndpoint.behaviors.has(GeneralDiagnosticsBehavior)) {
             return rootEndpoint.stateOf(GeneralDiagnosticsBehavior).bootReason;
         }
     }

package/src/behaviors/general-commissioning/GeneralCommissioningServer.ts

@@ -9,8 +9,8 @@ import { BasicInformationServer } from "#behaviors/basic-information";
 import { AdministratorCommissioning } from "#clusters/administrator-commissioning";
 import { GeneralCommissioning } from "#clusters/general-commissioning";
 import { Logger, MatterFlowError, MaybePromise } from "#general";
-import { ServerNode } from "#node/ServerNode.js";
-import { assertSecureSession, DeviceCommissioner, FabricManager, SecureSession, SessionManager } from "#protocol";
+import type { ServerNode } from "#node/ServerNode.js";
+import { DeviceCommissioner, FabricManager, GroupSession, NodeSession, SecureSession, SessionManager } from "#protocol";
 import { GeneralCommissioningBehavior } from "./GeneralCommissioningBehavior.js";
 import { ServerNodeFailsafeContext } from "./ServerNodeFailsafeContext.js";
 
@@ -45,7 +45,7 @@ export class GeneralCommissioningServer extends GeneralCommissioningBehavior {
     }
 
     /** As required by Commissioning Flows any new PASE session needs to arm the failsafe for 60s. */
-    async #handleAddedPaseSessions(session: SecureSession) {
+    async #handleAddedPaseSessions(session: NodeSession) {
         if (
             !session.isPase || // Only PASE sessions
             session.fabric !== undefined // That does not have an assigned fabric (can never happen in real usecases)
@@ -60,7 +60,7 @@ export class GeneralCommissioningServer extends GeneralCommissioningBehavior {
         { breadcrumb, expiryLengthSeconds }: GeneralCommissioning.ArmFailSafeRequest,
         session: SecureSession,
     ) {
-        assertSecureSession(session, "armFailSafe can only be called on a secure session");
+        NodeSession.assert(session, "armFailSafe can only be called on a secure session");
         const commissioner = this.env.get(DeviceCommissioner);
 
         try {
@@ -195,10 +195,11 @@ export class GeneralCommissioningServer extends GeneralCommissioningBehavior {
     }
 
     override async commissioningComplete() {
-        if (this.session.isPase) {
+        const session = this.session;
+        if ((NodeSession.is(session) && session.isPase) || GroupSession.is(session)) {
             return {
                 errorCode: GeneralCommissioning.CommissioningError.InvalidAuthentication,
-                debugText: "Command not executed over CASE session.",
+                debugText: "Command must be executed over CASE session.",
             };
         }
 
@@ -211,7 +212,7 @@ export class GeneralCommissioningServer extends GeneralCommissioningBehavior {
         }
         const failsafeContext = commissioner.failsafeContext;
 
-        assertSecureSession(this.session, "commissioningComplete can only be called on a secure session");
+        SecureSession.assert(session, "commissioningComplete can only be called on a secure session");
 
         const timedFabric = failsafeContext.associatedFabric?.fabricIndex;
         if (fabric.fabricIndex !== timedFabric) {

package/src/behaviors/general-commissioning/ServerNodeFailsafeContext.ts

@@ -7,7 +7,7 @@
 import { NetworkCommissioningBehavior } from "#behaviors/network-commissioning";
 import { Endpoint } from "#endpoint/Endpoint.js";
 import { Immutable, Lifecycle, UnsupportedDependencyError } from "#general";
-import { ServerNode } from "#node/ServerNode.js";
+import type { ServerNode } from "#node/ServerNode.js";
 import { Fabric, FabricManager, FailsafeContext } from "#protocol";
 
 /**