@matter/node 0.17.4 → 0.17.5-alpha.0-20260702-a2cd6f764

package/src/behaviors/groupcast/GroupcastServer.ts

@@ -0,0 +1,665 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { AccessControlServer } from "#behaviors/access-control";
+import { GroupKeyManagementServer } from "#behaviors/group-key-management";
+import { NodeLifecycle } from "#node/NodeLifecycle.js";
+import { Bytes, deepCopy, ImplementationError, Logger, ObservableValue, Seconds, Time, Timer } from "@matter/general";
+import { AccessLevel, DataModelPath } from "@matter/model";
+import {
+    AccessControl,
+    assertRemoteActor,
+    Fabric,
+    FabricManager,
+    GroupMessageEventInfo,
+    SessionManager,
+} from "@matter/protocol";
+import { EndpointNumber, FabricIndex, GroupId, NodeId, Status, StatusResponseError } from "@matter/types";
+import { AccessControl as AccessControlTypes } from "@matter/types/clusters/access-control";
+import { Groupcast } from "@matter/types/clusters/groupcast";
+import { GroupcastBehavior } from "./GroupcastBehavior.js";
+
+const logger = Logger.get("GroupcastServer");
+
+/** Membership.KeySetId sentinel indicating the referenced key set no longer exists in GKM. */
+const UNMAPPED_KEYSET_ID = 0xffff;
+
+/** TODO: remove once the Groupcast cluster leaves provisional state in the Matter specification. */
+const GROUPCAST_IS_PROVISIONAL = true;
+
+/**
+ * This is the default server implementation of {@link GroupcastBehavior}.
+ *
+ * The Groupcast cluster is node-scoped and must be placed on the root endpoint.
+ * Use {@link GroupcastServer.with} to enable the desired features (e.g. "Listener", "Sender").
+ *
+ * Key behaviors:
+ * - Manages per-fabric group membership (persistent).
+ * - Drives {@link FabricGroups} with group-to-key-set mappings and multicast address policy.
+ * - Registers an {@link AccessControlServer.AuxAclObservable} to supply synthetic ACL entries for groups
+ *   with `hasAuxiliaryAcl=true`. AccessControlServer calls back to collect entries when needed.
+ * - On first use by a fabric, marks the fabric as "GroupcastAdopted" in GKM, making GroupKeyMap read-only.
+ * - Migrates legacy group data from the Groups cluster on startup.
+ */
+export class GroupcastServer extends GroupcastBehavior {
+    declare internal: GroupcastServer.Internal;
+
+    /** Timer for GroupcastTesting auto-disable. */
+    #testingTimer?: Timer;
+
+    override initialize() {
+        // TODO: remove this guard once the Groupcast cluster leaves provisional state in the Matter specification
+        if (GROUPCAST_IS_PROVISIONAL) {
+            throw new ImplementationError(
+                "The Groupcast cluster is provisional in Matter 1.6. Do not add it to a node.",
+            );
+        }
+
+        const lifecycle = this.endpoint.lifecycle as NodeLifecycle;
+        this.reactTo(lifecycle.online, this.#online);
+    }
+
+    async #online() {
+        // Register the aux ACL observable with AccessControlServer so it can subscribe for updates
+        this.agent.get(AccessControlServer).registerAuxAclProvider(this.internal.auxAcl);
+
+        const fabrics = this.env.get(FabricManager);
+
+        // Sync FabricGroups for all existing fabrics
+        for (const fabric of fabrics) {
+            this.#syncFabricGroups(fabric);
+        }
+
+        // Migrate legacy Groups cluster data to Groupcast Membership
+        await this.#migrate();
+
+        // Reconcile key sets that may have been removed via GKM somehow
+        this.#reconcileUnmappedKeys();
+
+        // Update the derived state once after all sync/migration is done
+        this.#updateUsedMcastAddrCount();
+        this.#emitAuxAcl();
+
+        // Keep in sync as fabrics are added or removed
+        this.reactTo(fabrics.events.added, this.#handleFabricAdded);
+        this.reactTo(fabrics.events.deleted, this.#handleFabricDeleted);
+
+        // When GKM key sets are removed, groupKeyMap is also cleaned up — use that as trigger
+        // to reconcile membership entries whose key set no longer exists (mark as UNMAPPED_KEYSET_ID)
+        const gkmEvents = this.endpoint.eventsOf(GroupKeyManagementServer);
+        this.reactTo(gkmEvents.groupKeyMap$Changed, this.#reconcileUnmappedKeys);
+
+        // React to fabricUnderTest changes to dynamically subscribe/unsubscribe from group message events.
+        // While no fabric is under test, SessionManager.groupMessage emits are a no-op (no listeners).
+        this.reactTo(this.events.fabricUnderTest$Changed, this.#handleFabricUnderTestChanged);
+        if (this.state.fabricUnderTest !== FabricIndex.NO_FABRIC) {
+            this.#attachGroupMessageListener();
+        }
+    }
+
+    /**
+     * Check whether the current session has Admin privileges for this cluster/endpoint.
+     * Key and useAuxiliaryACL fields in Manage-access commands require Admin
+     * privilege to prevent privilege escalation.
+     */
+    #requireAdmin() {
+        // Called only from handlers that already asserted remote actor, safe to narrow
+        const session = this.context as AccessControl.RemoteActorSession;
+        const location: AccessControl.Location = {
+            path: DataModelPath.none,
+            endpoint: this.endpoint.number,
+            cluster: GroupcastBehavior.cluster.id,
+            owningFabric: session.fabric,
+        };
+        if (session.authorityAt(AccessLevel.Administer, location) !== AccessControl.Authority.Granted) {
+            throw new StatusResponseError(
+                "Admin privilege required for key or ACL operations",
+                Status.UnsupportedAccess,
+            );
+        }
+    }
+
+    override async joinGroup(request: Groupcast.JoinGroupRequest) {
+        assertRemoteActor(this.context);
+        const fabricIndex = this.context.session.associatedFabric.fabricIndex;
+        const { groupId, endpoints, keySetId, key, useAuxiliaryAcl, replaceEndpoints, mcastAddrPolicy } = request;
+
+        // Validate groupId range
+        if (groupId < 1 || groupId > 0xfff7) {
+            throw new StatusResponseError("Invalid group ID", Status.ConstraintError);
+        }
+
+        // Privilege escalation prevention: key and useAuxiliaryACL require Admin
+        if (key !== undefined || useAuxiliaryAcl !== undefined) {
+            this.#requireAdmin();
+        }
+
+        // Validate endpoints: ep 0 (root) and ep > 0xFFFE are invalid per spec
+        for (const ep of endpoints) {
+            if (ep === 0 || ep > 0xfffe) {
+                throw new StatusResponseError(`Endpoint ${ep} is invalid`, Status.UnsupportedEndpoint);
+            }
+        }
+
+        // If LN-only (no SD feature), an empty endpoint list is not allowed
+        if (!this.features.sender && endpoints.length === 0) {
+            throw new StatusResponseError("Empty endpoint list requires Sender feature", Status.ConstraintError);
+        }
+
+        // Validate multicast address policy: PerGroup requires PerGroupAddr feature
+        const policy = mcastAddrPolicy ?? Groupcast.MulticastAddrPolicy.IanaAddr;
+        if (policy === Groupcast.MulticastAddrPolicy.PerGroup && !this.features.perGroup) {
+            throw new StatusResponseError(
+                "PerGroup multicast policy requires PerGroupAddr feature",
+                Status.ConstraintError,
+            );
+        }
+
+        await this.#applyKeySet(fabricIndex, keySetId, key);
+
+        const membership = deepCopy(this.state.membership);
+        const existingIdx = membership.findIndex(m => m.groupId === groupId && m.fabricIndex === fabricIndex);
+
+        if (existingIdx >= 0) {
+            // Update existing group membership
+            const existing = membership[existingIdx];
+            const lnFields = this.features.listener
+                ? {
+                      endpoints: replaceEndpoints
+                          ? endpoints
+                          : [...new Set([...(existing.endpoints ?? []), ...endpoints])],
+                      hasAuxiliaryAcl: useAuxiliaryAcl ?? existing.hasAuxiliaryAcl,
+                  }
+                : {};
+            membership[existingIdx] = {
+                ...existing,
+                ...lnFields,
+                keySetId,
+                mcastAddrPolicy: policy,
+            };
+        } else {
+            // New group: check capacity limits
+            const fabricMemberships = membership.filter(m => m.fabricIndex === fabricIndex);
+            const perFabricLimit = Math.floor(this.state.maxMembershipCount / 2);
+            if (fabricMemberships.length >= perFabricLimit) {
+                throw new StatusResponseError("Per-fabric membership limit reached", Status.ResourceExhausted);
+            }
+            if (membership.length >= this.state.maxMembershipCount) {
+                throw new StatusResponseError("Total membership limit reached", Status.ResourceExhausted);
+            }
+
+            // Check MaxMcastAddrCount for new multicast address allocation
+            if (policy === Groupcast.MulticastAddrPolicy.PerGroup) {
+                const currentUsed = this.#computeUsedMcastAddrCount(membership);
+                if (currentUsed >= this.state.maxMcastAddrCount) {
+                    throw new StatusResponseError("MaxMcastAddrCount limit reached", Status.ResourceExhausted);
+                }
+            } else if (policy === Groupcast.MulticastAddrPolicy.IanaAddr) {
+                // IanaAddr pool counts as 1 address; only check if pool not yet allocated
+                const hasIanaAddr = membership.some(m => m.mcastAddrPolicy === Groupcast.MulticastAddrPolicy.IanaAddr);
+                if (!hasIanaAddr) {
+                    const currentUsed = this.#computeUsedMcastAddrCount(membership);
+                    if (currentUsed >= this.state.maxMcastAddrCount) {
+                        throw new StatusResponseError("MaxMcastAddrCount limit reached", Status.ResourceExhausted);
+                    }
+                }
+            }
+
+            const lnFields = this.features.listener ? { endpoints, hasAuxiliaryAcl: useAuxiliaryAcl ?? false } : {};
+            membership.push({
+                groupId,
+                ...lnFields,
+                keySetId,
+                mcastAddrPolicy: policy,
+                fabricIndex,
+            });
+        }
+
+        this.state.membership = membership;
+        this.#updateUsedMcastAddrCount();
+        this.#syncFabricGroups(this.env.get(FabricManager).for(fabricIndex));
+        this.#emitAuxAcl();
+
+        /* Provisional in Matter 1.6.0:
+        const gkm = this.agent.get(GroupKeyManagementServer);
+        gkm.setGroupcastAdopted(fabricIndex, true);
+        */
+    }
+
+    override leaveGroup(request: Groupcast.LeaveGroupRequest): Groupcast.LeaveGroupResponse {
+        assertRemoteActor(this.context);
+        const fabricIndex = this.context.session.associatedFabric.fabricIndex;
+        const { groupId, endpoints: requestedEndpoints } = request;
+
+        // GroupID 0 = wildcard: leave ALL groups for this fabric
+        if (groupId === GroupId.NO_GROUP_ID) {
+            const fabricMemberships = this.state.membership.filter(m => m.fabricIndex === fabricIndex);
+            if (fabricMemberships.length === 0) {
+                throw new StatusResponseError("No groups to leave", Status.NotFound);
+            }
+            this.state.membership = this.state.membership.filter(m => m.fabricIndex !== fabricIndex);
+            this.#updateUsedMcastAddrCount();
+            this.#syncFabricGroups(this.env.get(FabricManager).for(fabricIndex));
+            this.#emitAuxAcl();
+            return { groupId: GroupId.NO_GROUP_ID, endpoints: [] };
+        }
+
+        const membership = deepCopy(this.state.membership);
+        const entryIdx = membership.findIndex(m => m.groupId === groupId && m.fabricIndex === fabricIndex);
+
+        if (entryIdx < 0) {
+            throw new StatusResponseError(`Group ${groupId} not found`, Status.NotFound);
+        }
+
+        const entry = membership[entryIdx];
+        let removedEndpoints: EndpointNumber[];
+
+        if (!requestedEndpoints || requestedEndpoints.length === 0) {
+            // No specific endpoints specified → remove entire entry
+            removedEndpoints = entry.endpoints ?? [];
+            membership.splice(entryIdx, 1);
+        } else {
+            const currentEndpoints = entry.endpoints ?? [];
+            removedEndpoints = requestedEndpoints.filter(ep => currentEndpoints.includes(ep));
+            const remainingEndpoints = currentEndpoints.filter(ep => !requestedEndpoints.includes(ep));
+
+            if (remainingEndpoints.length === 0) {
+                if (this.features.sender) {
+                    // SD feature enabled: keep entry as sender-only (omit endpoints when LN absent)
+                    const { endpoints: _omit, ...entryWithoutEndpoints } = entry;
+                    membership[entryIdx] = this.features.listener ? { ...entry, endpoints: [] } : entryWithoutEndpoints;
+                } else {
+                    // LN-only: remove the entry entirely
+                    membership.splice(entryIdx, 1);
+                }
+            } else {
+                membership[entryIdx] = { ...entry, endpoints: remainingEndpoints };
+            }
+        }
+
+        this.state.membership = membership;
+        this.#updateUsedMcastAddrCount();
+        this.#syncFabricGroups(this.env.get(FabricManager).for(fabricIndex));
+        this.#emitAuxAcl();
+
+        return { groupId, endpoints: removedEndpoints };
+    }
+
+    override async updateGroupKey(request: Groupcast.UpdateGroupKeyRequest) {
+        assertRemoteActor(this.context);
+        const fabricIndex = this.context.session.associatedFabric.fabricIndex;
+        const { groupId, keySetId, key } = request;
+
+        // Privilege escalation prevention: key requires Admin
+        if (key !== undefined) {
+            this.#requireAdmin();
+        }
+
+        const membership = deepCopy(this.state.membership);
+        const entryIdx = membership.findIndex(m => m.groupId === groupId && m.fabricIndex === fabricIndex);
+
+        if (entryIdx < 0) {
+            throw new StatusResponseError(`Group ${groupId} not found`, Status.NotFound);
+        }
+
+        await this.#applyKeySet(fabricIndex, keySetId, key);
+
+        membership[entryIdx] = { ...membership[entryIdx], keySetId };
+        this.state.membership = membership;
+        this.#syncFabricGroups(this.env.get(FabricManager).for(fabricIndex));
+    }
+
+    configureAuxiliaryAcl(request: Groupcast.ConfigureAuxiliaryAclRequest) {
+        assertRemoteActor(this.context);
+        const fabricIndex = this.context.session.associatedFabric.fabricIndex;
+        const { groupId, useAuxiliaryAcl } = request;
+
+        const membership = deepCopy(this.state.membership);
+        const entryIdx = membership.findIndex(m => m.groupId === groupId && m.fabricIndex === fabricIndex);
+
+        if (entryIdx < 0) {
+            throw new StatusResponseError(`Group ${groupId} not found`, Status.NotFound);
+        }
+
+        membership[entryIdx] = { ...membership[entryIdx], hasAuxiliaryAcl: useAuxiliaryAcl };
+        this.state.membership = membership;
+        this.#emitAuxAcl();
+    }
+
+    override groupcastTesting(request: Groupcast.GroupcastTestingRequest) {
+        assertRemoteActor(this.context);
+        const fabricIndex = this.context.session.associatedFabric.fabricIndex;
+        const { testOperation, durationSeconds } = request;
+
+        // Cancel any running auto-disable timer
+        if (this.#testingTimer) {
+            this.#testingTimer.stop();
+            this.#testingTimer = undefined;
+        }
+
+        if (testOperation === Groupcast.GroupcastTesting.DisableTesting) {
+            this.state.fabricUnderTest = FabricIndex.NO_FABRIC;
+            return;
+        }
+
+        // Enable testing: set FabricUnderTest to the current fabric index
+        this.state.fabricUnderTest = fabricIndex;
+
+        // If durationSeconds is provided, auto-disable after that duration
+        if (durationSeconds !== undefined && durationSeconds > 0) {
+            this.#testingTimer = Time.getTimer(
+                `groupcast-testing-${fabricIndex}`,
+                Seconds(durationSeconds),
+                this.callback(this.#testingTimerExpired),
+            );
+            this.#testingTimer.start();
+        }
+    }
+
+    #testingTimerExpired() {
+        this.#testingTimer = undefined;
+        this.state.fabricUnderTest = FabricIndex.NO_FABRIC;
+    }
+
+    #handleFabricUnderTestChanged(value: FabricIndex) {
+        if (value !== FabricIndex.NO_FABRIC) {
+            this.#attachGroupMessageListener();
+        } else {
+            this.#detachGroupMessageListener();
+        }
+    }
+
+    #attachGroupMessageListener() {
+        if (this.internal.groupMessageHandler !== undefined) {
+            return;
+        }
+        const sessions = this.env.get(SessionManager);
+        // SessionManager.onGroupMessage fires after the dispatching action's context has exited, so
+        // wrap the handler with this.callback to acquire a fresh context for state/event access.
+        const handler = this.callback(this.#onGroupMessage);
+        sessions.onGroupMessage.on(handler);
+        this.internal.groupMessageHandler = handler;
+    }
+
+    #detachGroupMessageListener() {
+        if (this.internal.groupMessageHandler === undefined) {
+            return;
+        }
+        const sessions = this.env.get(SessionManager);
+        sessions.onGroupMessage.off(this.internal.groupMessageHandler);
+        this.internal.groupMessageHandler = undefined;
+    }
+
+    #onGroupMessage(info: GroupMessageEventInfo) {
+        // Only emit for the fabric under test
+        if (info.fabric === undefined || info.fabric.fabricIndex !== this.state.fabricUnderTest) {
+            return;
+        }
+        this.events.groupcastTesting?.emit(
+            {
+                groupId: info.groupId,
+                endpointId: info.endpointId,
+                clusterId: info.clusterId,
+                elementId: info.elementId,
+                accessAllowed: info.accessAllowed,
+                groupcastTestResult: info.result,
+                fabricIndex: info.fabric.fabricIndex,
+            },
+            this.context,
+        );
+    }
+
+    /** Sync the FabricGroups instance for a fabric from the current Membership state. */
+    #handleFabricAdded(fabric: Fabric) {
+        this.#syncFabricGroups(fabric);
+    }
+
+    #handleFabricDeleted(fabric: Fabric) {
+        this.#cleanupFabric(fabric.fabricIndex);
+    }
+
+    #syncFabricGroups(fabric: Fabric) {
+        const fabricIndex = fabric.fabricIndex;
+        const fabricMemberships = this.state.membership.filter(m => m.fabricIndex === fabricIndex);
+
+        // Set per-group multicast address policies BEFORE updating groupKeyIdMap. The latter triggers
+        // ServerGroupNetworking to bind the multicast address via multicastAddressFor, which reads the
+        // policy map - so the policy must be in place first or it falls back to PerGroupId-derived.
+        for (const m of fabricMemberships) {
+            const policy = m.mcastAddrPolicy === Groupcast.MulticastAddrPolicy.PerGroup ? "perGroupId" : "ianaAddr";
+            fabric.groups.setGroupMulticastPolicy(m.groupId, policy);
+        }
+
+        // Rebuild group→keySet map
+        const groupKeyIdMap = new Map<GroupId, number>();
+        for (const m of fabricMemberships) {
+            groupKeyIdMap.set(m.groupId, m.keySetId);
+        }
+        fabric.groups.groupKeyIdMap = groupKeyIdMap;
+
+        // Mirror Membership mappings into GKM GroupKeyMap so the attribute read reflects them.
+        // Data dependency: Groupcast owns the group→keySet relationship; GroupKeyMap must reflect it.
+        // GKM's per-fabric cap (maxGroupsPerFabric) and Groupcast's per-fabric cap (floor(maxMembershipCount/2))
+        // must stay aligned so the mirror never exceeds the GKM validator.
+        const gkm = this.agent.get(GroupKeyManagementServer);
+        const otherFabricsMap = gkm.state.groupKeyMap.filter(e => e.fabricIndex !== fabricIndex);
+        const mappings = fabricMemberships
+            .filter(m => m.keySetId !== UNMAPPED_KEYSET_ID)
+            .map(m => ({ groupId: m.groupId, groupKeySetId: m.keySetId, fabricIndex }));
+        gkm.state.groupKeyMap = [...otherFabricsMap, ...mappings];
+
+        // Mirror Membership endpoints to GKM GroupTable (spec attribute) and FabricGroups.endpoints
+        // (runtime dispatch lookup used by InteractionServer for wildcard group commands).
+        const otherFabricsTable = gkm.state.groupTable.filter(e => e.fabricIndex !== fabricIndex);
+        const tableEntries = fabricMemberships
+            .filter(m => m.endpoints !== undefined && m.endpoints.length > 0)
+            .map(m => ({
+                groupId: m.groupId,
+                endpoints: [...m.endpoints!],
+                groupName: "",
+                fabricIndex,
+            }));
+        gkm.state.groupTable = [...otherFabricsTable, ...tableEntries];
+
+        const previousGroupIds = new Set(fabric.groups.endpoints.keys());
+        for (const m of fabricMemberships) {
+            const eps = m.endpoints ?? [];
+            if (eps.length > 0) {
+                fabric.groups.endpoints.set(m.groupId, [...eps]);
+            } else {
+                fabric.groups.endpoints.delete(m.groupId);
+            }
+            previousGroupIds.delete(m.groupId);
+        }
+        for (const gid of previousGroupIds) {
+            fabric.groups.endpoints.delete(gid);
+        }
+    }
+
+    /**
+     * Mark membership entries as unmapped (KeySetId=UNMAPPED_KEYSET_ID) when their referenced key set no longer exists in GKM.
+     * Runs at startup to reconcile state after potential GKM KeySetRemove operations.
+     */
+    #reconcileUnmappedKeys() {
+        const gkmState = this.endpoint.stateOf(GroupKeyManagementServer);
+        const membership = this.state.membership;
+        let dirty = false;
+
+        for (const m of membership) {
+            if (m.keySetId !== UNMAPPED_KEYSET_ID && m.keySetId !== 0) {
+                const exists = gkmState.groupKeySets.some(
+                    ks => ks.fabricIndex === m.fabricIndex && ks.groupKeySetId === m.keySetId,
+                );
+                if (!exists) {
+                    m.keySetId = UNMAPPED_KEYSET_ID;
+                    dirty = true;
+                }
+            }
+        }
+
+        if (dirty) {
+            this.state.membership = [...membership];
+        }
+    }
+
+    /**
+     * Validate and apply a key set for a group operation.
+     * If `key` is provided, validates and creates a new key set in GKM.
+     * Otherwise, validates that the key set already exists.
+     */
+    async #applyKeySet(fabricIndex: FabricIndex, keySetId: number, key: Bytes | undefined) {
+        const gkm = this.agent.get(GroupKeyManagementServer);
+        if (key !== undefined) {
+            if (key.byteLength !== 16) {
+                throw new StatusResponseError("Key must be exactly 16 bytes", Status.ConstraintError);
+            }
+            if (gkm.validateKeySetId(fabricIndex, keySetId)) {
+                throw new StatusResponseError(`KeySet ${keySetId} already exists for fabric`, Status.AlreadyExists);
+            }
+            await gkm.createKeySetForGroupcast(this.env.get(FabricManager).for(fabricIndex), keySetId, Bytes.of(key));
+        } else {
+            if (!gkm.validateKeySetId(fabricIndex, keySetId)) {
+                throw new StatusResponseError(`KeySet ${keySetId} not found for fabric`, Status.NotFound);
+            }
+        }
+    }
+
+    /** Recompute auxiliary ACL entries and emit them via the observable so AccessControlServer updates. */
+    #emitAuxAcl() {
+        if (!this.endpoint.behaviors.has(AccessControlServer)) return;
+        const entries: AccessControlTypes.AccessControlEntry[] = this.state.membership
+            .filter(m => m.hasAuxiliaryAcl)
+            .map(m => ({
+                privilege: AccessControlTypes.AccessControlEntryPrivilege.Operate,
+                authMode: AccessControlTypes.AccessControlEntryAuthMode.Group,
+                subjects: [NodeId(BigInt(m.groupId))],
+                targets:
+                    m.endpoints?.map(ep => ({
+                        cluster: null,
+                        endpoint: ep,
+                        deviceType: null,
+                    })) ?? null,
+                auxiliaryType: AccessControlTypes.AccessControlAuxiliaryType.Groupcast,
+                fabricIndex: m.fabricIndex,
+            }));
+
+        this.internal.auxAcl.emit(entries, this.context);
+    }
+
+    /**
+     * Compute UsedMcastAddrCount from a membership array:
+     * - Each PerGroup group contributes 1 unique address
+     * - All IanaAddr groups together share 1 address
+     */
+    #computeUsedMcastAddrCount(membership: Groupcast.Membership[]): number {
+        const perGroupCount = membership.filter(
+            m => m.mcastAddrPolicy === Groupcast.MulticastAddrPolicy.PerGroup,
+        ).length;
+        const hasIanaAddr = membership.some(m => m.mcastAddrPolicy === Groupcast.MulticastAddrPolicy.IanaAddr);
+        return perGroupCount + (hasIanaAddr ? 1 : 0);
+    }
+
+    /** Recompute and update the UsedMcastAddrCount attribute. */
+    #updateUsedMcastAddrCount() {
+        this.state.usedMcastAddrCount = this.#computeUsedMcastAddrCount(this.state.membership);
+    }
+
+    /** Remove all state for a departed fabric. */
+    #cleanupFabric(fabricIndex: FabricIndex) {
+        this.state.membership = this.state.membership.filter(m => m.fabricIndex !== fabricIndex);
+        this.#updateUsedMcastAddrCount();
+        this.#emitAuxAcl();
+    }
+
+    /**
+     * Migrate legacy group data from the GKM groupTable into Groupcast Membership entries.
+     * Only migrates fabrics that have existing GKM groups but no Membership entries yet.
+     * Legacy groups are assigned PerGroup multicast policy for backwards compatibility.
+     */
+    async #migrate() {
+        const fabrics = this.env.get(FabricManager);
+        const gkmState = this.endpoint.stateOf(GroupKeyManagementServer);
+        let migrated = false;
+
+        for (const fabric of fabrics) {
+            const fi = fabric.fabricIndex;
+            const hasMembership = this.state.membership.some(m => m.fabricIndex === fi);
+            if (hasMembership) continue; // already has Groupcast membership
+
+            const fabricGroups = gkmState.groupTable.filter(g => g.fabricIndex === fi);
+            if (fabricGroups.length === 0) continue; // no legacy groups
+
+            logger.info(`Migrating ${fabricGroups.length} legacy group(s) for fabric ${fi} to Groupcast`);
+
+            const newEntries: Groupcast.Membership[] = fabricGroups.map(group => {
+                const keyMapping = gkmState.groupKeyMap.find(m => m.fabricIndex === fi && m.groupId === group.groupId);
+                // Use PerGroup policy for legacy compat only if PGA feature is enabled
+                const mcastAddrPolicy = this.features.perGroup
+                    ? Groupcast.MulticastAddrPolicy.PerGroup
+                    : Groupcast.MulticastAddrPolicy.IanaAddr;
+                const lnFields = this.features.listener
+                    ? {
+                          endpoints: group.endpoints.filter(ep => ep !== EndpointNumber(0)),
+                          hasAuxiliaryAcl: false,
+                      }
+                    : {};
+                return {
+                    groupId: group.groupId,
+                    ...lnFields,
+                    keySetId: keyMapping?.groupKeySetId ?? 0,
+                    mcastAddrPolicy,
+                    fabricIndex: fi,
+                };
+            });
+
+            this.state.membership = [...this.state.membership, ...newEntries];
+            this.#syncFabricGroups(fabric);
+            /* Provisional in Matter 1.6.0:
+            const gkm = this.agent.get(GroupKeyManagementServer);
+            gkm.setGroupcastAdopted(fi, true);
+            */
+            migrated = true;
+        }
+
+        if (migrated) {
+            this.#updateUsedMcastAddrCount();
+            logger.info("Groupcast migration complete");
+        }
+    }
+
+    override async [Symbol.asyncDispose]() {
+        this.#testingTimer?.stop();
+        this.#testingTimer = undefined;
+        this.#detachGroupMessageListener();
+        await super[Symbol.asyncDispose]?.();
+    }
+}
+
+export namespace GroupcastServer {
+    /** Non-persistent internal state for GroupcastServer. */
+    export class Internal {
+        /**
+         * Observable that holds all auxiliary ACL entries supplied by this cluster.
+         * AccessControlServer subscribes to this and rebuilds its ACL cache whenever it emits.
+         */
+        auxAcl: AccessControlServer.AuxAclObservable = ObservableValue([]);
+
+        /** Active subscription handler on SessionManager.groupMessage while fabricUnderTest is set. */
+        groupMessageHandler?: (info: GroupMessageEventInfo) => void;
+    }
+
+    /** Default state overrides for GroupcastServer. */
+    export class State extends GroupcastBehavior.State {
+        /**
+         * Implementation-defined maximum membership count (min 10 per spec).
+         * Set to 2 * GKM.maxGroupsPerFabric (44) so per-fabric quota floor(44/2)=22 aligns exactly
+         * with GKM's per-fabric cap. Even number avoids spillover semantics.
+         */
+        override maxMembershipCount = 44;
+        /** Implementation-defined maximum multicast address count (min 1 per spec). */
+        override maxMcastAddrCount = 44;
+    }
+}

package/src/behaviors/groupcast/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*** THIS FILE WILL BE REGENERATED IF YOU DO NOT REMOVE THIS MESSAGE ***/
+
+export * from "./GroupcastBehavior.js";
+export * from "./GroupcastServer.js";
+export * from "./GroupcastClient.js";