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

package/src/fabric/FabricManager.ts

@@ -167,6 +167,9 @@ export class FabricManager {
                 }
             });
         };
+        if (this.#storage !== undefined) {
+            fabric.storage = this.#storage.createContext(`fabric-${fabricIndex}`);
+        }
         if (this.#initializationDone) {
             this.#events.added.emit(fabric);
         }
@@ -182,6 +185,7 @@ export class FabricManager {
             );
         this.#fabrics.delete(fabricIndex);
         await this.persistFabrics();
+        await fabric.storage?.clearAll();
         this.#events.deleted.emit(fabric);
     }
 
@@ -213,9 +217,10 @@ export class FabricManager {
         this.#construction.assert();
 
         for (const fabric of this.#fabrics.values()) {
-            const candidateDestinationId = await fabric.getDestinationId(fabric.nodeId, initiatorRandom);
-            if (!Bytes.areEqual(candidateDestinationId, destinationId)) continue;
-            return fabric;
+            const candidateDestinationIds = await fabric.destinationIdsFor(fabric.nodeId, initiatorRandom);
+            if (candidateDestinationIds.some(candidate => Bytes.areEqual(candidate, destinationId))) {
+                return fabric;
+            }
         }
 
         throw new FabricNotFoundError();
@@ -233,7 +238,9 @@ export class FabricManager {
     }
 
     findByIndex(index: FabricIndex) {
-        return Array.from(this.#fabrics.values()).find(fabric => fabric.fabricIndex === index);
+        this.#construction.assert();
+
+        return this.#fabrics.get(index);
     }
 
     async updateFabric(fabric: Fabric) {

package/src/groups/FabricGroupsManager.ts

@@ -0,0 +1,164 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Fabric } from "#fabric/Fabric.js";
+import { BasicMap, Bytes, Crypto, InternalError, MatterFlowError, StorageContext } from "#general";
+import { GroupKeySet, KeySets, OperationalKeySet } from "#groups/KeySets.js";
+import { MessagingState } from "#groups/MessagingState.js";
+import { GroupId } from "#types";
+import { Groups } from "./Groups.js";
+
+export const GROUP_SECURITY_INFO = Bytes.fromString("GroupKey v1.0");
+
+/**
+ * Class that contains an operational view on the Group Keys for a fabric
+ */
+export class FabricGroupsManager {
+    #fabric: Fabric;
+    #groups: Groups;
+    #messagingState: MessagingState;
+
+    /** Operationally enhanced variants of the group key sets based on their ID. */
+    #keySets = new KeySets();
+
+    constructor(fabric: Fabric, storage?: StorageContext) {
+        this.#fabric = fabric;
+        this.#groups = new Groups(fabric, this.#keySets);
+        this.#messagingState = new MessagingState(storage);
+
+        // KeySet with ID 0 is always the Fabric IPK, so we initialize from there because this is not stored
+        // in Key Management Cluster
+        this.#keySets.add({
+            groupKeySetId: 0,
+            epochKey0: fabric.identityProtectionKey,
+            operationalEpochKey0: fabric.operationalIdentityProtectionKey,
+            epochStartTime0: 0, // 0 is always ok, but only for the IPK key
+            groupSessionId0: null,
+            epochKey1: null,
+            operationalEpochKey1: null,
+            epochStartTime1: null,
+            groupSessionId1: null,
+            epochKey2: null,
+            operationalEpochKey2: null,
+            epochStartTime2: null,
+            groupSessionId2: null,
+            groupKeySecurityPolicy: 0, // GroupKeyManagement.GroupKeySecurityPolicy.TrustFirst, the other option is provisional
+            groupKeyMulticastPolicy: 0, // GroupKeyManagement.GroupKeyMulticastPolicy.PerGroupId, provisional!
+        });
+        if (storage !== undefined) {
+            this.storage = storage;
+        }
+    }
+
+    set storage(storage: StorageContext) {
+        this.#messagingState.storage = storage;
+    }
+
+    /** Operative lookup of the group key sets by their id. */
+    get keySets(): KeySets<OperationalKeySet> {
+        return this.#keySets;
+    }
+
+    get messaging(): MessagingState {
+        return this.#messagingState;
+    }
+
+    /** Operative lookup of the group key set id and the key by a group session Id. */
+    get sessions() {
+        return this.#keySets.sessions;
+    }
+
+    get groupKeyIdMap(): BasicMap<GroupId, number> {
+        return this.#groups.idMap;
+    }
+
+    set groupKeyIdMap(map: Map<GroupId, number>) {
+        this.#groups.idMap = map;
+    }
+
+    get endpoints() {
+        return this.#groups.endpointMap;
+    }
+
+    currentKeyForGroup(groupId: GroupId) {
+        return this.#groups.currentKeyForId(groupId);
+    }
+
+    subjectForGroup(id: GroupId, keySetId: number) {
+        return this.#groups.subjectForGroup(id, keySetId);
+    }
+
+    multicastAddressFor(groupId: GroupId): string {
+        return this.#groups.multicastAddress(groupId);
+    }
+
+    /*
+    TODO for Controller to generate new epochs
+    addGroupEpoch(groupKeySetId: number, startTimeMs = Time.nowMs()) {
+        // TODO for Controller to generate new epochs
+        const epochKey = Crypto.getRandomData(CRYPTO_SYMMETRIC_KEY_LENGTH);
+        const operationalEpochKey = Crypto.hkdf(epochKey, this.#fabric.operationalId, GROUP_SECURITY_INFO);
+        const epochStartTime = startTimeMs * 1000;
+        logger.debug(`addGroupEpoch: epochStartTime=${epochStartTime}`, operationalEpochKey);
+        // TODO extend in structure and such
+    }
+    */
+
+    /**
+     * Sets new group key set data and pre-calculates all operative data like session ids and operational keys.
+     * Overwriting the existing one if it exists.
+     */
+    async setFromGroupKeySet(groupKeySet: GroupKeySet) {
+        const { groupKeySetId, epochKey0, epochKey1, epochKey2 } = groupKeySet;
+
+        if (epochKey0 === null) {
+            throw new MatterFlowError("EpochKey0 must be set"); // checked before, but to make typing happy
+        }
+
+        // Clean up the counters and data from old keys, will be initialized again on next use
+        await this.#cleanUpCounters(groupKeySetId);
+
+        // Lets pre-calculate the operational keys
+        const operationalId = this.#fabric.operationalId;
+        const operationalEpochKey0 = await Crypto.hkdf(epochKey0, operationalId, GROUP_SECURITY_INFO);
+        const operationalEpochKey1 =
+            epochKey1 !== null ? await Crypto.hkdf(epochKey1, operationalId, GROUP_SECURITY_INFO) : null;
+        const operationalEpochKey2 =
+            epochKey2 !== null ? await Crypto.hkdf(epochKey2, operationalId, GROUP_SECURITY_INFO) : null;
+        this.#keySets.add({
+            ...groupKeySet,
+            operationalEpochKey0,
+            groupSessionId0: await this.#keySets.sessionIdFromKey(operationalEpochKey0),
+            operationalEpochKey1,
+            groupSessionId1:
+                operationalEpochKey1 !== null ? await this.#keySets.sessionIdFromKey(operationalEpochKey1) : null,
+            operationalEpochKey2,
+            groupSessionId2:
+                operationalEpochKey2 !== null ? await this.#keySets.sessionIdFromKey(operationalEpochKey2) : null,
+        });
+    }
+
+    /** Removes a group key set by its id and cleans up the counters and data. */
+    async removeGroupKeySet(groupKeySetId: number) {
+        if (groupKeySetId === 0) {
+            throw new InternalError("Cannot remove the group key set 0.");
+        }
+        await this.#cleanUpCounters(groupKeySetId, true);
+        return this.#keySets.delete("groupKeySetId", groupKeySetId);
+    }
+
+    /** Cleans up the counters and data for a group key set by its id. */
+    async #cleanUpCounters(groupKeySetId: number, forDelete = false) {
+        if (this.#keySets.forId(groupKeySetId) === undefined) {
+            return;
+        }
+
+        // Clean up counters for the group key set
+        const operationalKeys = this.#keySets.allKeysForId(groupKeySetId);
+        for (const { key } of operationalKeys) {
+            await this.#messagingState.removeCounter(key, forDelete);
+        }
+    }
+}

package/src/groups/Groups.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Subject } from "#action/index.js";
+import { Fabric } from "#fabric/Fabric.js";
+import { BasicMap, DataWriter, ImplementationError, ipv6BytesToString } from "#general";
+import { EndpointNumber, GroupId } from "#types";
+import { KeySets, OperationalKeySet } from "./KeySets.js";
+
+export class Groups {
+    #fabric: Fabric;
+    #keySets: KeySets<OperationalKeySet>;
+
+    /** Operational variant of the group key map attribute from Group Key Management cluster, maps group Ids to key sets. */
+    readonly #groupKeyIdMap = new BasicMap<GroupId, number>();
+
+    /** Operational variant of the group table, maps group Ids to a list of enabled endpoints. */
+    readonly endpointMap = new Map<GroupId, EndpointNumber[]>();
+
+    constructor(fabric: Fabric, keySets: KeySets<OperationalKeySet>) {
+        this.#fabric = fabric;
+        this.#keySets = keySets;
+    }
+
+    /** Operative lookup of the group key sets by a group id and to react on added removed groups. */
+    get idMap(): BasicMap<GroupId, number> {
+        return this.#groupKeyIdMap;
+    }
+
+    /** Updates the group key id map when changed in Group Key Management Cluster. Only changes are taken over. */
+    set idMap(map: Map<GroupId, number>) {
+        for (const [groupId, keySetId] of map.entries()) {
+            this.#groupKeyIdMap.set(groupId, keySetId);
+        }
+        for (const groupId of this.#groupKeyIdMap.keys()) {
+            if (!map.has(groupId)) {
+                // If the groupId is not in the new map, we remove it from the groupKeyIdMap
+                this.#groupKeyIdMap.delete(groupId);
+            }
+        }
+    }
+
+    subjectForGroup(id: GroupId, keySetId: number) {
+        return Subject.Group({
+            id,
+            hasValidMapping: this.idMap.get(id) === keySetId,
+            endpoints: this.endpointMap.get(id) ?? [],
+        });
+    }
+
+    /** Returns the multicast address for a given group id for this fabric. */
+    multicastAddress(groupId: GroupId) {
+        GroupId.assertGroupId(groupId);
+
+        // If GroupKeyMulticastPolicy ever becomes non-provisional then we need to adjust logic here, but so far we
+        // just use the default which is PerGroupId, which means we use the GroupId to create the multicast address.
+
+        const writer = new DataWriter();
+        writer.writeUInt16(0xff35);
+        writer.writeUInt16(0x0040);
+        writer.writeUInt8(0xfd);
+        writer.writeUInt64(this.#fabric.fabricId);
+        writer.writeUInt8(0x00);
+        writer.writeUInt16(GroupId(groupId));
+        return ipv6BytesToString(writer.toByteArray());
+    }
+
+    /**
+     * Returns the current operational group key for a given group id and returns the keys, start time and
+     * their session IDs.
+     */
+    currentKeyForId(groupId: GroupId) {
+        const keySetId = this.#groupKeyIdMap.get(groupId);
+        if (keySetId === undefined) {
+            throw new ImplementationError(`No group key set found for groupId ${groupId}.`);
+        }
+        return { ...this.#keySets.currentKeyForId(keySetId), keySetId };
+    }
+}

package/src/groups/KeySets.ts

@@ -0,0 +1,194 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { GroupKeyManagement } from "#clusters/group-key-management";
+import { BasicSet, Bytes, Crypto, DataReader, ImplementationError, MatterFlowError, Time } from "#general";
+
+export const GROUP_KEY_INFO = Bytes.fromString("GroupKeyHash");
+
+export class KeySets<T extends OperationalKeySet> extends BasicSet<T> {
+    /** Operational enhanced structure for fast access based on the group session id. */
+    readonly #sessions = new Map<number, { keySetId: number; key: Uint8Array }[]>();
+
+    get sessions() {
+        return this.#sessions;
+    }
+
+    override add(item: T): void {
+        this.delete("groupKeySetId", item.groupKeySetId); // Remove any existing item with the same groupKeySetId
+        super.add(item);
+        this.#updateSessions();
+    }
+
+    override delete<F extends keyof T>(itemOrField: T | F, value?: T[F]): boolean {
+        const deleted = super.delete(itemOrField as any, value as any);
+        if (deleted) {
+            this.#updateSessions();
+        }
+        return deleted;
+    }
+
+    forId(groupKeySetId: number): OperationalKeySet | undefined {
+        return this.get("groupKeySetId", groupKeySetId);
+    }
+
+    /**
+     * Return an operative list of operational keys, start time and their session IDs for a specified
+     * group key set id. This is mainly used for receiving messages.
+     */
+    allKeysForId(keySetId: number) {
+        const groupKeySet = this.forId(keySetId);
+        if (groupKeySet === undefined) {
+            throw new MatterFlowError(`GroupKeySet for groupKeySet ${keySetId} not found.`);
+        }
+        const operationalKeys = Array<{ key: Uint8Array; sessionId?: number; startTime: number | bigint }>();
+        const {
+            operationalEpochKey0,
+            groupSessionId0,
+            epochStartTime0,
+            operationalEpochKey1,
+            groupSessionId1,
+            epochStartTime1,
+            operationalEpochKey2,
+            groupSessionId2,
+            epochStartTime2,
+        } = groupKeySet;
+        if (operationalEpochKey0 === null || epochStartTime0 === null || (keySetId !== 0 && groupSessionId0 === null)) {
+            // should never happen, but just in case
+            throw new MatterFlowError(`EpochKey0 for groupKeySet ${keySetId} not found.`);
+        }
+        operationalKeys.push({
+            key: operationalEpochKey0,
+            sessionId: groupSessionId0 !== null ? groupSessionId0 : undefined,
+            startTime: epochStartTime0,
+        });
+        if (operationalEpochKey1 !== null && groupSessionId1 !== null && epochStartTime1 !== null) {
+            operationalKeys.push({ key: operationalEpochKey1, sessionId: groupSessionId1, startTime: epochStartTime1 });
+        }
+        if (operationalEpochKey2 !== null && groupSessionId2 !== null && epochStartTime2 !== null) {
+            operationalKeys.push({ key: operationalEpochKey2, sessionId: groupSessionId2, startTime: epochStartTime2 });
+        }
+        return operationalKeys;
+    }
+
+    /**
+     * Returns the current operational group key for a given group KeySet Id and returns the keys, start time and
+     * their session IDs. This is mainly used for sending messages.
+     */
+    currentKeyForId(keySetId: number) {
+        const operationalKeys = this.allKeysForId(keySetId);
+        if (operationalKeys.length === 0) {
+            throw new MatterFlowError(`No operational keys found for groupKeySet ${keySetId}.`);
+        }
+        if (keySetId === 0) {
+            // Groups: For the generation of the Destination Identifier, the originator SHALL use the operational group key with
+            // the second newest EpochStartTime, if one exists, otherwise it SHALL use the single operational group key available.
+            // @see {@link MatterSpecification.v14.Core} § 4.14.2.6.
+            if (operationalKeys.length > 2) {
+                return operationalKeys[1];
+            }
+            return operationalKeys[0];
+        } else {
+            // Nodes sending group messages SHALL use operational group keys that are derived from the current
+            // epoch key (specifically, the epoch key with the latest start time that is not in the future).
+            // TODO Nodes that cannot reliably keep track of time calculate the current epoch key as described in
+            //  Section 4.17.3.4, “Epoch Key Rotation without Time Synchronization”.
+            const now = Time.nowUs();
+            const relevantKeys = operationalKeys.filter(({ startTime }) => startTime <= now);
+            if (relevantKeys.length === 0) {
+                throw new ImplementationError(
+                    `No operational keys found for groupKeySet ${keySetId} that are not in the future.`,
+                );
+            }
+            return relevantKeys[operationalKeys.length - 1];
+        }
+    }
+
+    /**
+     * Returns the group key set for a given group key set id in the official data format from the Group key Management
+     * cluster.
+     */
+    asGroupKeySet(groupKeySetId: number) {
+        const groupKeySet = this.forId(groupKeySetId);
+        if (groupKeySet === undefined) {
+            return undefined;
+        }
+
+        const {
+            epochKey0,
+            epochStartTime0,
+            epochKey1,
+            epochStartTime1,
+            epochKey2,
+            epochStartTime2,
+            groupKeySecurityPolicy,
+            groupKeyMulticastPolicy,
+        } = groupKeySet;
+        return {
+            groupKeySetId,
+            epochKey0,
+            epochStartTime0,
+            epochKey1,
+            epochStartTime1,
+            epochKey2,
+            epochStartTime2,
+            groupKeySecurityPolicy,
+            groupKeyMulticastPolicy,
+        };
+    }
+
+    /** Calculates a group session id based on the operational group key. */
+    async sessionIdFromKey(operationalGroupKey: Uint8Array) {
+        // GroupKeyHash is an array of 2 bytes (16 bits) per Crypto_KDF
+        const groupKeyHash = await Crypto.hkdf(operationalGroupKey, new Uint8Array(), GROUP_KEY_INFO, 2);
+
+        // GroupSessionId is computed by considering the GroupKeyHash as a Big-Endian value. GroupSessionId is a scalar.
+        // Its use in fields within messages may cause a re-serialization into a different byte order than the one used
+        // for initial generation.
+        return new DataReader(groupKeyHash).readUInt16();
+    }
+
+    /**
+     * Updates the group session map based on the current group key sets.
+     * This is used to quickly find the operational keys by their group session id.
+     */
+    #updateSessions() {
+        this.#sessions.clear();
+        for (const [id, keySet] of this.mapOf("groupKeySetId").entries()) {
+            if (id === 0) {
+                // Skip the default group key set (0), as it is not used for operational keys
+                continue;
+            }
+            if (keySet.groupSessionId0 !== null) {
+                const list = this.#sessions.get(keySet.groupSessionId0) ?? [];
+                list.push({ key: keySet.operationalEpochKey0, keySetId: id });
+                this.#sessions.set(keySet.groupSessionId0, list);
+            }
+            if (keySet.groupSessionId1 !== null && keySet.operationalEpochKey1 !== null) {
+                const list = this.#sessions.get(keySet.groupSessionId1) ?? [];
+                list.push({ key: keySet.operationalEpochKey1, keySetId: id });
+                this.#sessions.set(keySet.groupSessionId1, list);
+            }
+            if (keySet.groupSessionId2 !== null && keySet.operationalEpochKey2 !== null) {
+                const list = this.#sessions.get(keySet.groupSessionId2) ?? [];
+                list.push({ key: keySet.operationalEpochKey2, keySetId: id });
+                this.#sessions.set(keySet.groupSessionId2, list);
+            }
+        }
+    }
+}
+
+export type GroupKeySet = GroupKeyManagement.GroupKeySet;
+
+/** Enhanced structure of GroupKeySet to include operational data for easier operational processing. */
+export type OperationalKeySet = GroupKeySet & {
+    operationalEpochKey0: Uint8Array;
+    groupSessionId0: number | null;
+    operationalEpochKey1: Uint8Array | null;
+    groupSessionId1: number | null;
+    operationalEpochKey2: Uint8Array | null;
+    groupSessionId2: number | null;
+};

package/src/groups/MessagingState.ts

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Bytes, ImplementationError, InternalError, StorageContext } from "#general";
+import { PersistedMessageCounter } from "#protocol/MessageCounter.js";
+import { MessageReceptionStateEncryptedWithRollover } from "#protocol/MessageReceptionState.js";
+import { NodeId } from "#types";
+
+export class MessagingState {
+    /**
+     * Message counter for sending data messages to a group per Operational key. No need to scope to a source node
+     * because we are the sending node
+     * TODO: For management: Make sure to start rotating the key early enough that a former counter-value is not used
+     *  again for the same key.
+     */
+    readonly #groupDataCounters = new Map<string, PersistedMessageCounter>();
+
+    /** Message reception state for data messages per Operational key and source node. */
+    readonly #messageDataReceptionState = new Map<string, Map<NodeId, MessageReceptionStateEncryptedWithRollover>>();
+    #storage?: StorageContext;
+
+    constructor(storage?: StorageContext) {
+        if (storage !== undefined) {
+            this.#storage = storage;
+        }
+    }
+
+    set storage(storage: StorageContext) {
+        if (this.#storage !== undefined) {
+            throw new InternalError("Storage context can only be set once.");
+        }
+        this.#storage = storage;
+    }
+
+    /**
+     * Return the message counter for sending messages to a group with the given operational key.
+     */
+    counterFor(operationalKey: Uint8Array) {
+        if (!this.#storage) {
+            throw new ImplementationError("Group session cannot be created without storage context.");
+        }
+        const operationalKeyHex = Bytes.toHex(operationalKey);
+        let counter = this.#groupDataCounters.get(operationalKeyHex);
+        if (counter === undefined) {
+            counter = new PersistedMessageCounter(this.#storage, `${operationalKeyHex}-data`);
+            this.#groupDataCounters.set(operationalKeyHex, counter);
+        }
+        return counter;
+    }
+
+    async removeCounter(key: Uint8Array, forDelete = false) {
+        const operationalKeyHex = Bytes.toHex(key);
+        this.#groupDataCounters.delete(operationalKeyHex);
+        if (forDelete) {
+            // If we are deleting the group key set, also delete the persisted counter values
+            await this.#storage?.delete(`${operationalKeyHex}-data`);
+        }
+    }
+
+    /**
+     * Returns the message reception state for a given source node id and operational key.
+     */
+    receptionStateFor(sourceNodeId: NodeId, operationalKey: Uint8Array) {
+        const operationalKeyHex = Bytes.toHex(operationalKey);
+        let receptionState = this.#messageDataReceptionState.get(operationalKeyHex)?.get(sourceNodeId);
+        if (receptionState === undefined) {
+            receptionState = new MessageReceptionStateEncryptedWithRollover();
+            const keyMap = this.#messageDataReceptionState.get(operationalKeyHex) ?? new Map();
+            keyMap.set(sourceNodeId, receptionState);
+            this.#messageDataReceptionState.set(operationalKeyHex, keyMap);
+        }
+        return receptionState;
+    }
+}

package/src/groups/index.ts

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

package/src/index.ts

@@ -12,6 +12,7 @@ export * from "./codec/index.js";
 export * from "./common/index.js";
 export * from "./events/index.js";
 export * from "./fabric/index.js";
+export * from "./groups/index.js";
 export * from "./interaction/index.js";
 export * from "./mdns/index.js";
 export * from "./peer/index.js";