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

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";

package/src/interaction/AccessControlManager.ts

@@ -3,8 +3,9 @@
  * Copyright 2022-2023 Project CHIP Authors
  * SPDX-License-Identifier: Apache-2.0
  */
+import { Subject } from "#action/server/Subject.js";
 import { AccessControl } from "#clusters/access-control";
-import { Logger, MatterFlowError, toHex } from "#general";
+import { MatterFlowError } from "#general";
 import { AccessLevel } from "#model";
 import {
     CaseAuthenticatedTag,
@@ -15,11 +16,9 @@ import {
     NodeId,
     StatusCode,
     StatusResponseError,
+    SubjectId,
 } from "#types";
-import { Fabric } from "../fabric/Fabric.js";
-import { SecureSession } from "../session/SecureSession.js";
-
-const logger = Logger.get("AccessControlManager");
+import { AccessControl as AccessControlContext } from "../action/server/AccessControl.js";
 
 export type AclEntry = Omit<AccessControl.AccessControlEntry, "privilege"> & {
     privilege: AccessLevel;
@@ -49,7 +48,7 @@ enum AuthModeNone {
 export type IncomingSubjectDescriptor = {
     isCommissioning: boolean;
     authMode: AccessControl.AccessControlEntryAuthMode | AuthModeNone;
-    subjects: NodeId[];
+    subjects: SubjectId[];
     fabricIndex: FabricIndex;
 };
 
@@ -98,22 +97,24 @@ export class AccessControlManager {
     /**
      * Get the Access Control List for a given fabric.
      */
-    #getAccessControlEntriesForFabric(fabric: Fabric): AclList {
-        return this.#aclList.filter(entry => entry.fabricIndex === fabric.fabricIndex);
+    #getAccessControlEntriesForFabric(fabricIndex: FabricIndex): AclList {
+        return this.#aclList.filter(entry => entry.fabricIndex === fabricIndex);
     }
 
     /**
      * Subjects must match exactly, or both are CAT with matching CAT ID and acceptable CAT version
      */
-    #subjectMatches(aclSubject: NodeId, isdSubject: NodeId): boolean {
-        if (aclSubject === isdSubject) {
+    #subjectMatches(aclSubject: SubjectId, isdSubject: SubjectId): boolean {
+        if (BigInt(aclSubject) === BigInt(isdSubject)) {
             return true;
         }
-        if (!NodeId.isCaseAuthenticatedTag(aclSubject) || !NodeId.isCaseAuthenticatedTag(isdSubject)) {
+        const aclNode = NodeId(aclSubject);
+        const isdNode = NodeId(isdSubject);
+        if (!NodeId.isCaseAuthenticatedTag(aclNode) || !NodeId.isCaseAuthenticatedTag(isdNode)) {
             return false;
         }
-        const aclSubjectCat = NodeId.extractAsCaseAuthenticatedTag(aclSubject);
-        const isdSubjectCat = NodeId.extractAsCaseAuthenticatedTag(isdSubject);
+        const aclSubjectCat = NodeId.extractAsCaseAuthenticatedTag(aclNode);
+        const isdSubjectCat = NodeId.extractAsCaseAuthenticatedTag(isdNode);
         return (
             CaseAuthenticatedTag.getIdentifyValue(aclSubjectCat) ===
                 CaseAuthenticatedTag.getIdentifyValue(isdSubjectCat) &&
@@ -149,40 +150,16 @@ export class AccessControlManager {
     }
 
     /**
-     * Check if the given ACL entry is allowed to be used for the given subject descriptor, endpoint, and cluster ID.
+     * Determines the granted privileges for the given session, endpoint, and cluster ID and returns them.
      */
-    allowsPrivilege(
-        session: SecureSession,
+    getGrantedPrivileges(
+        context: AccessControlContext.Session,
         endpoint: AclEndpointContext,
         clusterId: ClusterId,
-        privilege: AccessLevel,
-    ): boolean {
-        const grantedPrivileges = this.getGrantedPrivileges(session, endpoint, clusterId);
-        if (grantedPrivileges.includes(privilege)) {
-            return true;
-        }
-
-        logger.notice(
-            `Failed access control check for ${endpoint.id}/0x${toHex(clusterId)} and fabricIndex ${session.associatedFabric.fabricIndex}, acl=`,
-            this.#getAccessControlEntriesForFabric(session.associatedFabric),
-            "with ISD=",
-            this.#getIsdFromMessage(session),
-            "granted privileges=",
-            grantedPrivileges,
-            "not contains",
-            privilege,
-        );
-
-        return false;
-    }
-
-    /**
-     * Determines the granted privileges for the given session, endpoint, and cluster ID and returns them.
-     */
-    getGrantedPrivileges(session: SecureSession, endpoint: AclEndpointContext, clusterId: ClusterId): AccessLevel[] {
+    ): AccessLevel[] {
         const endpointId = endpoint.id;
-        const fabric = session.fabric;
-        const subjectDesc = this.#getIsdFromMessage(session);
+        const fabric = context.fabric;
+        const subjectDesc = this.#getIsdFromMessage(context);
         const acl = fabric ? this.#getAccessControlEntriesForFabric(fabric) : [ImplicitDefaultPaseAclEntry];
 
         // Granted privileges set is initially empty
@@ -203,17 +180,11 @@ export class AccessControlManager {
             // other than the implicit PASE entry, which we will not see explicitly in the
             // access control list
             if (aclEntry.fabricIndex === FabricIndex.NO_FABRIC || aclEntry.fabricIndex !== subjectDesc.fabricIndex) {
-                logger.debug(
-                    "Skipping ACL entry with mismatched fabric index",
-                    aclEntry.fabricIndex,
-                    subjectDesc.fabricIndex,
-                );
                 continue;
             }
 
             // Auth mode must match
             if (aclEntry.authMode !== subjectDesc.authMode) {
-                logger.debug("Skipping ACL entry with mismatched auth mode", aclEntry.authMode, subjectDesc.authMode);
                 continue;
             }
 
@@ -304,50 +275,47 @@ export class AccessControlManager {
     /**
      * Determines the Incoming Subject Descriptor (ISD) from the given session.
      */
-    #getIsdFromMessage(session: SecureSession) {
-        const fabric = session.fabric;
+    #getIsdFromMessage(session: AccessControlContext.Session) {
+        const fabricIndex = session.fabric;
         const isd: IncomingSubjectDescriptor = {
             isCommissioning: false,
             authMode: AuthModeNone.None,
-            subjects: new Array<NodeId>(),
+            subjects: new Array<SubjectId>(),
             fabricIndex: FabricIndex.NO_FABRIC,
         };
 
-        if (session.isPase) {
+        const { subject } = session;
+        if (subject === undefined) {
+            throw new MatterFlowError("ACL error: ACL checks require an authorized subject");
+        }
+        if (subject.id === NodeId.UNSPECIFIED_NODE_ID) {
+            // Pase Session
             isd.authMode = AccessControl.AccessControlEntryAuthMode.Pase;
             isd.isCommissioning = true; // Or how "commissioning channel" is defined?
-            isd.subjects.push(NodeId(0)); // Default Commissioning Passcode ID
-            if (fabric) {
-                isd.fabricIndex = fabric.fabricIndex;
+            isd.subjects.push(NodeId.UNSPECIFIED_NODE_ID); // Default Commissioning Passcode ID
+            if (fabricIndex !== undefined && fabricIndex !== FabricIndex.NO_FABRIC) {
+                isd.fabricIndex = fabricIndex;
             }
-        } else {
-            // TODO Add Group session handling when implementing groups
-            // if (session instanceof SecureGroupSession) {
-            //   Groups
-            //   # Message is assumed to have been decrypted and matched properly prior to
-            //       # this procedure occurring.
-            //       group_id = message.get_dst_group_id()
-            //       group_key_id = sessions_metadata.get_group_key_id(message)
-            //       # Group membership must be verified against Group Key Management Cluster
-            //       if group_key_management_cluster.group_key_map_has_mapping(group_id, group_key_id):
-            //         isd.AuthMode = AuthModeEnum.Group
-            //         isd.Subjects.append(group_id)
-            //         isd.FabricIndex = sessions_metadata.get_fabric_index(message)
-            //         assert(isd.FabricIndex != 0) # cannot be zero
-            //
-            //     isd.authMode = AccessControl.AccessControlEntryAuthMode.Group;
-            // } else {
-
+        } else if (Subject.isGroup(subject)) {
+            if (fabricIndex === undefined || fabricIndex === FabricIndex.NO_FABRIC) {
+                throw new MatterFlowError("ACL error: fabric needs to be associated for group sessions");
+            }
+            if (subject.hasValidMapping) {
+                isd.authMode = AccessControl.AccessControlEntryAuthMode.Group;
+                isd.subjects.push(subject.id);
+                isd.fabricIndex = fabricIndex;
+            }
+        } else if (Subject.isNode(subject)) {
             // CASE session
+            if (fabricIndex === undefined || fabricIndex === FabricIndex.NO_FABRIC) {
+                throw new MatterFlowError("ACL error: Case session must be associated with a fabric");
+            }
             isd.authMode = AccessControl.AccessControlEntryAuthMode.Case;
-            isd.subjects.push(session.peerNodeId);
-            // Append CASE session CATs which also serve as subjects
-            session.caseAuthenticatedTags.forEach(cat => isd.subjects.push(NodeId.fromCaseAuthenticatedTag(cat)));
-            // }
-            if (fabric === undefined) {
-                throw new MatterFlowError("ACL error: fabric is undefined");
+            isd.subjects.push(subject.id);
+            if (subject.catSubjects !== undefined) {
+                isd.subjects.push(...subject.catSubjects);
             }
-            isd.fabricIndex = fabric.fabricIndex;
+            isd.fabricIndex = fabricIndex;
         }
 
         return isd;