@matter/protocol 0.14.1-alpha.0-20250605-9fc134af0 → 0.14.1-alpha.0-20250607-a93593303

package/src/fabric/Fabric.ts

@@ -10,7 +10,6 @@ import {
     TlvOperationalCertificate,
     TlvRootCertificate,
 } from "#certificate/CertificateManager.js";
-import { GroupKeyManagement } from "#clusters/group-key-management";
 import {
     BinaryKeyPair,
     Bytes,
@@ -25,56 +24,19 @@ import {
     MatterFlowError,
     MaybePromise,
     PrivateKey,
+    StorageContext,
 } from "#general";
+import { FabricGroupsManager, GROUP_SECURITY_INFO } from "#groups/FabricGroupsManager.js";
 import { PeerAddress } from "#peer/PeerAddress.js";
-import { CaseAuthenticatedTag, FabricId, FabricIndex, NodeId, TypeFromSchema, VendorId } from "#types";
-import { SecureSession } from "../session/SecureSession.js";
+import { Session } from "#session/Session.js";
+import { CaseAuthenticatedTag, FabricId, FabricIndex, GroupId, NodeId, VendorId } from "#types";
 
 const logger = Logger.get("Fabric");
 
 const COMPRESSED_FABRIC_ID_INFO = Bytes.fromString("CompressedFabric");
-const GROUP_SECURITY_INFO = Bytes.fromString("GroupKey v1.0");
 
 export class PublicKeyError extends MatterError {}
 
-type OperationalGroupKeySet = TypeFromSchema<typeof GroupKeyManagement.TlvGroupKeySet> & {
-    operationalEpochKey0: Uint8Array;
-    groupSessionId0: number | null;
-    operationalEpochKey1: Uint8Array | null;
-    groupSessionId1: number | null;
-    operationalEpochKey2: Uint8Array | null;
-    groupSessionId2: number | null;
-};
-
-namespace OperationalGroupKeySet {
-    export const asTlvGroupSet = (
-        operationalGroupSet: OperationalGroupKeySet,
-    ): TypeFromSchema<typeof GroupKeyManagement.TlvGroupKeySet> => {
-        const {
-            groupKeySetId,
-            epochKey0,
-            epochStartTime0,
-            epochKey1,
-            epochStartTime1,
-            epochKey2,
-            epochStartTime2,
-            groupKeySecurityPolicy,
-            groupKeyMulticastPolicy,
-        } = operationalGroupSet;
-        return {
-            groupKeySetId,
-            epochKey0,
-            epochStartTime0,
-            epochKey1,
-            epochStartTime1,
-            epochKey2,
-            epochStartTime2,
-            groupKeySecurityPolicy,
-            groupKeyMulticastPolicy,
-        };
-    };
-}
-
 export type ExposedFabricInformation = {
     fabricIndex: FabricIndex;
     fabricId: FabricId;
@@ -97,14 +59,13 @@ export class Fabric {
     readonly operationalIdentityProtectionKey: Uint8Array;
     readonly intermediateCACert: Uint8Array | undefined;
     readonly operationalCert: Uint8Array;
-
     readonly #keyPair: Key;
-
-    readonly #sessions = new Set<SecureSession>();
-
+    readonly #sessions = new Set<Session>();
+    readonly #groupManager: FabricGroupsManager;
     #label: string;
     #removeCallbacks = new Array<() => MaybePromise<void>>();
     #persistCallback: ((isUpdate?: boolean) => MaybePromise<void>) | undefined;
+    #storage?: StorageContext;
 
     constructor(config: Fabric.Config) {
         this.fabricIndex = config.fabricIndex;
@@ -120,8 +81,8 @@ export class Fabric {
         this.intermediateCACert = config.intermediateCACert;
         this.operationalCert = config.operationalCert;
         this.#label = config.label;
-
         this.#keyPair = PrivateKey(config.keyPair);
+        this.#groupManager = new FabricGroupsManager(this);
     }
 
     get config(): Fabric.Config {
@@ -158,6 +119,19 @@ export class Fabric {
         await this.persist();
     }
 
+    set storage(storage: StorageContext) {
+        this.#storage = storage;
+        this.#groupManager.storage = storage;
+    }
+
+    get storage(): StorageContext | undefined {
+        return this.#storage;
+    }
+
+    get groups() {
+        return this.#groupManager;
+    }
+
     get publicKey() {
         return this.#keyPair.publicKey;
     }
@@ -190,20 +164,39 @@ export class Fabric {
         );
     }
 
-    getDestinationId(nodeId: NodeId, random: Uint8Array) {
+    #generateSalt(nodeId: NodeId, random: Uint8Array) {
         const writer = new DataWriter(Endian.Little);
         writer.writeByteArray(random);
         writer.writeByteArray(this.rootPublicKey);
         writer.writeUInt64(this.fabricId);
         writer.writeUInt64(nodeId);
-        return Crypto.hmac(this.operationalIdentityProtectionKey, writer.toByteArray());
+        return writer.toByteArray();
+    }
+
+    /**
+     * Returns the destination IDs for a given nodeId, random value and optional groupId.
+     * When groupId is provided, it returns the time-wise valid operational keys for that groupId.
+     */
+    async currentDestinationIdFor(nodeId: NodeId, random: Uint8Array) {
+        return await Crypto.hmac(this.groups.keySets.currentKeyForId(0).key, this.#generateSalt(nodeId, random));
+    }
+
+    /**
+     * Returns the destination IDs for a given nodeId, random value and optional groupId.
+     * When groupId is provided, it returns all operational keys for that groupId.
+     */
+    async destinationIdsFor(nodeId: NodeId, random: Uint8Array) {
+        const salt = this.#generateSalt(nodeId, random);
+        // Check all keys of keyset 0 - typically it is only the IPK
+        const destinationIds = this.groups.keySets.allKeysForId(0).map(({ key }) => Crypto.hmac(key, salt));
+        return await Promise.all(destinationIds);
     }
 
-    addSession(session: SecureSession) {
+    addSession(session: Session) {
         this.#sessions.add(session);
     }
 
-    removeSession(session: SecureSession) {
+    removeSession(session: Session) {
         this.#sessions.delete(session);
     }
 
@@ -236,39 +229,6 @@ export class Fabric {
         return this.#persistCallback?.(isUpdate);
     }
 
-    getGroupKeySet(groupKeySetId: number) {
-        if (groupKeySetId === 0) {
-            return OperationalGroupKeySet.asTlvGroupSet(this.getGroupSetForIpk());
-        }
-        // TODO add correct group handling later, right now only IPK exists
-        return undefined;
-    }
-
-    private getGroupSetForIpk(): OperationalGroupKeySet {
-        return {
-            groupKeySetId: 0,
-            epochKey0: this.identityProtectionKey,
-            operationalEpochKey0: this.operationalIdentityProtectionKey,
-            epochStartTime0: 0, // or do we need to track Fabric creation date?
-            groupSessionId0: null,
-            epochKey1: null,
-            operationalEpochKey1: null,
-            epochStartTime1: null,
-            groupSessionId1: null,
-            epochKey2: null,
-            operationalEpochKey2: null,
-            epochStartTime2: null,
-            groupSessionId2: null,
-            groupKeySecurityPolicy: GroupKeyManagement.GroupKeySecurityPolicy.TrustFirst,
-            groupKeyMulticastPolicy: GroupKeyManagement.GroupKeyMulticastPolicy.PerGroupId,
-        };
-    }
-
-    getAllGroupKeySets() {
-        // TODO add correct group handling later, right now only IPK exists
-        return [OperationalGroupKeySet.asTlvGroupSet(this.getGroupSetForIpk())];
-    }
-
     get externalInformation(): ExposedFabricInformation {
         return {
             fabricIndex: this.fabricIndex,
@@ -283,6 +243,12 @@ export class Fabric {
     addressOf(nodeId: NodeId) {
         return PeerAddress({ fabricIndex: this.fabricIndex, nodeId });
     }
+
+    groupAddressOf(groupId: GroupId) {
+        GroupId.assertGroupId(groupId);
+
+        return PeerAddress({ fabricIndex: this.fabricIndex, nodeId: NodeId.fromGroupId(groupId) });
+    }
 }
 
 export class FabricBuilder {
@@ -433,7 +399,7 @@ export class FabricBuilder {
             throw new InternalError("operationalCert needs to be set");
 
         this.#fabricIndex = fabricIndex;
-        const saltWriter = new DataWriter(Endian.Big);
+        const saltWriter = new DataWriter();
         saltWriter.writeUInt64(this.#fabricId);
         const operationalId = await Crypto.hkdf(
             this.#rootPublicKey.slice(1),

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 };
+    }
+}