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

package/src/protocol/ExchangeManager.ts

@@ -15,18 +15,18 @@ import {
     MatterAggregateError,
     MatterError,
     MatterFlowError,
-    NotImplementedError,
     ObserverGroup,
     TransportInterface,
     TransportInterfaceSet,
     UdpInterface,
+    UnexpectedDataError,
 } from "#general";
 import { PeerAddress } from "#peer/PeerAddress.js";
 import { NodeId, SECURE_CHANNEL_PROTOCOL_ID, SecureMessageType } from "#types";
-import { Message, MessageCodec, SessionType } from "../codec/MessageCodec.js";
+import { DecodedMessage, Message, MessageCodec, SessionType } from "../codec/MessageCodec.js";
 import { SecureChannelMessenger } from "../securechannel/SecureChannelMessenger.js";
 import { SecureChannelProtocol } from "../securechannel/SecureChannelProtocol.js";
-import { SecureSession } from "../session/SecureSession.js";
+import { NodeSession } from "../session/NodeSession.js";
 import { Session } from "../session/Session.js";
 import { SessionManager, UNICAST_UNSECURE_SESSION_ID } from "../session/SessionManager.js";
 import { ChannelManager } from "./ChannelManager.js";
@@ -73,7 +73,7 @@ export class MessageChannel implements Channel<Message> {
         return this.channel.maxPayloadSize;
     }
 
-    send(message: Message, logContext?: ExchangeLogContext): Promise<void> {
+    async send(message: Message, logContext?: ExchangeLogContext) {
         logger.debug("Message »", MessageCodec.messageDiagnostics(message, logContext));
         const packet = this.session.encode(message);
         const bytes = MessageCodec.encodePacket(packet);
@@ -83,7 +83,7 @@ export class MessageChannel implements Channel<Message> {
             );
         }
 
-        return this.channel.send(bytes);
+        return await this.channel.send(bytes);
     }
 
     get name() {
@@ -202,11 +202,13 @@ export class ExchangeManager {
 
     private async onMessage(channel: Channel<Uint8Array>, messageBytes: Uint8Array) {
         const packet = MessageCodec.decodePacket(messageBytes);
+        const aad = messageBytes.slice(0, messageBytes.length - packet.applicationPayload.length); // Header+Extensions
 
-        if (packet.header.sessionType === SessionType.Group)
-            throw new NotImplementedError("Group messages are not supported");
+        const messageId = packet.header.messageId;
 
+        let isDuplicate: boolean;
         let session: Session | undefined;
+        let message: DecodedMessage | undefined;
         if (packet.header.sessionType === SessionType.Unicast) {
             if (packet.header.sessionId === UNICAST_UNSECURE_SESSION_ID) {
                 if (this.#closing) return;
@@ -219,35 +221,46 @@ export class ExchangeManager {
             } else {
                 session = this.#sessionManager.getSession(packet.header.sessionId);
             }
+
+            if (session === undefined) {
+                throw new MatterFlowError(
+                    `Cannot find a session for ID ${packet.header.sessionId}${
+                        packet.header.sourceNodeId !== undefined
+                            ? ` and source NodeId ${packet.header.sourceNodeId}`
+                            : ""
+                    }`,
+                );
+            }
+
+            message = session.decode(packet, aad);
+
+            try {
+                session.updateMessageCounter(messageId);
+                isDuplicate = false;
+            } catch (e) {
+                DuplicateMessageError.accept(e);
+                isDuplicate = true;
+            }
         } else if (packet.header.sessionType === SessionType.Group) {
             if (this.#closing) return;
-            if (packet.header.sourceNodeId !== undefined) {
-                //session = this.sessionManager.findGroupSession(packet.header.destGroupId, packet.header.sessionId);
+            if (packet.header.sourceNodeId === undefined) {
+                throw new UnexpectedDataError("Group session message must include a source NodeId");
             }
-            // if (packet.header.destGroupId !== undefined) { ???
-        }
 
-        if (session === undefined) {
-            throw new MatterFlowError(
-                `Cannot find a session for ID ${packet.header.sessionId}${
-                    packet.header.sourceNodeId !== undefined ? ` and source NodeId ${packet.header.sourceNodeId}` : ""
-                }`,
-            );
-        }
-
-        const messageId = packet.header.messageId;
+            let key: Uint8Array;
+            ({ session, message, key } = this.#sessionManager.groupSessionFromPacket(packet, aad));
 
-        let isDuplicate;
-        try {
-            session.updateMessageCounter(packet.header.messageId, packet.header.sourceNodeId);
-            isDuplicate = false;
-        } catch (e) {
-            DuplicateMessageError.accept(e);
-            isDuplicate = true;
+            try {
+                session.updateMessageCounter(messageId, packet.header.sourceNodeId, key);
+                isDuplicate = false;
+            } catch (e) {
+                DuplicateMessageError.accept(e);
+                isDuplicate = true;
+            }
+        } else {
+            throw new MatterFlowError(`Unsupported session type: ${packet.header.sessionType}`);
         }
 
-        const aad = messageBytes.slice(0, messageBytes.length - packet.applicationPayload.length); // Header+Extensions
-        const message = session.decode(packet, aad);
         const exchangeIndex = message.payloadHeader.isInitiatorMessage
             ? message.payloadHeader.exchangeId
             : message.payloadHeader.exchangeId | 0x10000;
@@ -343,9 +356,12 @@ export class ExchangeManager {
                     throw new MatterFlowError(`Unsupported protocol ${message.payloadHeader.protocolId}`);
                 }
                 if (isDuplicate) {
-                    logger.info(
-                        `Ignoring duplicate message ${messageId} (requires no ack) for protocol ${message.payloadHeader.protocolId} on channel ${channel.name}`,
-                    );
+                    if (message.packetHeader.destGroupId === undefined) {
+                        // Duplicate Non-Group messages are still interesting to log to know them
+                        logger.info(
+                            `Ignoring duplicate message ${messageId} (requires no ack) for protocol ${message.payloadHeader.protocolId} on channel ${channel.name}`,
+                        );
+                    }
                     return;
                 } else {
                     logger.info(
@@ -365,12 +381,12 @@ export class ExchangeManager {
             return;
         }
         const { session } = exchange;
-        if (session.isSecure && session.closingAfterExchangeFinished) {
+        if (NodeSession.is(session) && session.closingAfterExchangeFinished) {
             logger.debug(
                 `Exchange index ${exchangeIndex} Session ${session.name} is already marked for closure. Close session now.`,
             );
             try {
-                await this.#closeSession(session as SecureSession);
+                await this.#closeSession(session);
             } catch (error) {
                 logger.error(`Error closing session ${session.name}. Ignoring.`, error);
             }
@@ -378,7 +394,7 @@ export class ExchangeManager {
         this.#exchanges.delete(exchangeIndex);
     }
 
-    async #closeSession(session: SecureSession) {
+    async #closeSession(session: NodeSession) {
         const sessionId = session.id;
         const sessionName = session.name;
 

package/src/protocol/MessageExchange.ts

@@ -18,8 +18,16 @@ import {
     Timer,
     createPromise,
 } from "#general";
-import { NodeId, SECURE_CHANNEL_PROTOCOL_ID, SecureMessageType, StatusCode, StatusResponseError } from "#types";
-import { Message, MessageCodec, SessionType } from "../codec/MessageCodec.js";
+import { GroupSession } from "#session/index.js";
+import {
+    GroupId,
+    NodeId,
+    SECURE_CHANNEL_PROTOCOL_ID,
+    SecureMessageType,
+    StatusCode,
+    StatusResponseError,
+} from "#types";
+import { Message, MessageCodec, PacketHeader, SessionType } from "../codec/MessageCodec.js";
 import { SecureChannelProtocol } from "../securechannel/SecureChannelProtocol.js";
 import {
     SESSION_ACTIVE_INTERVAL_MS,
@@ -404,18 +412,43 @@ export class MessageExchange {
             }
         }
 
-        // TODO Add support to also send controlMessages for Group messages, use different messagecounter!
-        const message: Message = {
-            packetHeader: {
+        let packetHeader: PacketHeader;
+        if (this.session.type === SessionType.Unicast) {
+            packetHeader = {
                 sessionId: this.#peerSessionId,
-                sessionType: SessionType.Unicast, // TODO: support multicast/groups
+                sessionType: SessionType.Unicast,
                 messageId: await this.session.getIncrementedMessageCounter(),
                 destNodeId: this.#peerNodeId,
                 sourceNodeId: this.#nodeId,
                 hasPrivacyEnhancements: false,
                 isControlMessage: false,
                 hasMessageExtensions: false,
-            },
+            };
+        } else if (this.session.type === SessionType.Group) {
+            const session = this.session;
+            if (!GroupSession.is(session)) {
+                throw new InternalError("Session is not a GroupSession, but session type is Group.");
+            }
+            const destGroupId = GroupId.fromNodeId(this.#peerNodeId!); // TODO !!! Where get from?
+            if (destGroupId === 0) {
+                throw new InternalError(`Invalid GroupId extracted from NodeId ${this.#peerNodeId}`);
+            }
+            packetHeader = {
+                sessionId: this.#peerSessionId,
+                sessionType: SessionType.Group,
+                messageId: await session.getIncrementedMessageCounter(),
+                destGroupId,
+                sourceNodeId: this.#nodeId, // We are the source node, so use our NodeId
+                hasPrivacyEnhancements: false,
+                isControlMessage: false,
+                hasMessageExtensions: false,
+            };
+        } else {
+            throw new InternalError(`Unknown session type: ${this.session.type}`);
+        }
+
+        const message: Message = {
+            packetHeader,
             payloadHeader: {
                 exchangeId: this.#exchangeId,
                 protocolId:
@@ -466,6 +499,8 @@ export class MessageExchange {
         let timeout: number;
         if (options?.timeoutMs !== undefined) {
             timeout = options.timeoutMs;
+        } else if (this.#messagesQueue.size > 0) {
+            timeout = 0; // If we have messages in the queue, we can return them immediately
         } else {
             switch (this.channel.type) {
                 case "tcp":

package/src/protocol/MessageReceptionState.ts

@@ -21,7 +21,7 @@ export abstract class MessageReceptionState {
 
 /**
  * Implements a message reception state for encrypted messages without rollover.
- * A counter in the range [(max_message_counter + 1) to (232 - 1)] SHALL be considered new, and cause the
+ * A counter in the range [(max_message_counter + 1) to (2^31 - 1)] SHALL be considered new, and cause the
  * max_message_counter value to be updated.
  * Message counters within the range of the bitmap SHALL be considered duplicate if the corresponding bit
  * offset is set to true. All other message counters SHALL be considered duplicate.
@@ -121,7 +121,7 @@ export class MessageReceptionStateEncryptedWithoutRollover extends MessageRecept
         }
 
         const diff = this.calculateDiff(messageCounter);
-        // A counter in the range [(max_message_counter + 1) to (232 - 1)] SHALL be considered new, and cause the
+        // A counter in the range [(max_message_counter + 1) to (2^31 - 1)] SHALL be considered new, and cause the
         // max_message_counter value to be updated.
         // Message counters within the range of the bitmap SHALL be considered duplicate if the corresponding bit
         // offset is set to true. All other message counters SHALL be considered duplicate.

package/src/securechannel/SecureChannelProtocol.ts

@@ -19,7 +19,7 @@ import {
 import { Message } from "../codec/MessageCodec.js";
 import { MessageExchange } from "../protocol/MessageExchange.js";
 import { ProtocolHandler } from "../protocol/ProtocolHandler.js";
-import { assertSecureSession } from "../session/SecureSession.js";
+import { SecureSession } from "../session/SecureSession.js";
 import { CaseServer } from "../session/case/CaseServer.js";
 import { MaximumPasePairingErrorsReachedError, PaseServer } from "../session/pase/PaseServer.js";
 import { ChannelStatusResponseError, SecureChannelMessenger } from "./SecureChannelMessenger.js";
@@ -79,7 +79,7 @@ export class StatusReportOnlySecureChannelProtocol implements ProtocolHandler {
         }
 
         const { session } = exchange;
-        assertSecureSession(session);
+        SecureSession.assert(session);
         logger.debug(`Peer requested to close session ${session.name}. Remove session now.`);
         // TODO: and do more - see Core Specs 5.5
         await session.destroy(false, false);

package/src/session/GroupSession.ts

@@ -0,0 +1,223 @@
+/**
+ * @license
+ * Copyright 2022-2023 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Subject } from "#action/server/Subject.js";
+import { DecodedMessage, DecodedPacket, Message, MessageCodec, Packet, SessionType } from "#codec/index.js";
+import { Fabric } from "#fabric/Fabric.js";
+import { FabricManager } from "#fabric/FabricManager.js";
+import {
+    Bytes,
+    Crypto,
+    CryptoDecryptError,
+    ImplementationError,
+    InternalError,
+    Logger,
+    MatterFlowError,
+    UnexpectedDataError,
+} from "#general";
+import type { SessionManager } from "#session/SessionManager.js";
+import { GroupId, NodeId } from "#types";
+import { SecureSession } from "./SecureSession.js";
+import { Session } from "./Session.js";
+
+const logger = Logger.get("SecureGroupSession");
+
+/** Secure Group session instance */
+export class GroupSession extends SecureSession {
+    readonly #id: number;
+    readonly #fabric: Fabric;
+    readonly #peerNodeId: NodeId;
+    readonly #operationalGroupKey: Uint8Array;
+    readonly supportsMRP = false;
+    readonly closingAfterExchangeFinished = false; // Group sessions do not close after exchange finished, they are long-lived
+
+    readonly keySetId: number;
+
+    constructor(args: {
+        manager?: SessionManager;
+        id: number; // Records the Group Session ID derived from the Operational Group Key used to encrypt the message.
+        fabric: Fabric;
+        keySetId: number; // The Group Key Set ID that was used to encrypt the incoming group message.
+        peerNodeId: NodeId; //The Target Group Node Id
+        operationalGroupKey: Uint8Array; // The Operational Group Key that was used to encrypt the incoming group message.
+    }) {
+        const { manager, fabric, operationalGroupKey, id, peerNodeId, keySetId } = args;
+        super({
+            ...args,
+            setActiveTimestamp: false, // We always set the active timestamp for Secure sessions TODO Check
+            messageCounter: fabric.groups.messaging.counterFor(operationalGroupKey),
+        });
+        this.#id = id;
+        this.#fabric = fabric;
+        this.#peerNodeId = peerNodeId;
+        this.keySetId = keySetId;
+        this.#operationalGroupKey = operationalGroupKey;
+
+        manager?.registerGroupSession(this);
+        fabric.addSession(this);
+
+        logger.debug(`Created secure GROUP session for fabric index ${fabric.fabricIndex}`, this.name);
+    }
+
+    override get type() {
+        return SessionType.Group;
+    }
+
+    get fabric(): Fabric {
+        return this.#fabric;
+    }
+
+    get id() {
+        return this.#id;
+    }
+
+    get peerSessionId(): number {
+        return this.#id; // we use the same peer session ID then ours because should be the same keys
+    }
+
+    get name() {
+        return `group/${this.#id}`;
+    }
+
+    get nodeId() {
+        return this.#fabric.nodeId;
+    }
+
+    get peerNodeId() {
+        return this.#peerNodeId;
+    }
+
+    get associatedFabric(): Fabric {
+        return this.#fabric;
+    }
+
+    subjectFor(message?: Message): Subject {
+        if (message === undefined || message.packetHeader.destGroupId === undefined) {
+            throw new ImplementationError("GroupSession requires a message with destGroupId");
+        }
+        return this.fabric.groups.subjectForGroup(GroupId(message.packetHeader.destGroupId), this.keySetId);
+    }
+
+    override notifyActivity(_messageReceived: boolean) {
+        // Group sessions do not have a specific activity notification, so we do nothing here
+    }
+
+    override updateMessageCounter(messageCounter: number, sourceNodeId: NodeId, operationalKey: Uint8Array) {
+        if (sourceNodeId === undefined || operationalKey === undefined) {
+            throw new InternalError("Source Node ID is required for GroupSession updateMessageCounter.");
+        }
+        const receptionState = this.#fabric.groups.messaging.receptionStateFor(sourceNodeId, operationalKey);
+        receptionState.updateMessageCounter(messageCounter);
+    }
+
+    encode(message: Message): Packet {
+        message.packetHeader.sessionId = this.#id;
+        const { header, applicationPayload } = MessageCodec.encodePayload(message);
+        if (header.destGroupId === undefined) {
+            // Just to be sure
+            throw new UnexpectedDataError("Group ID is required for GroupSession encode.");
+        }
+
+        const headerBytes = MessageCodec.encodePacketHeader(message.packetHeader);
+        const securityFlags = headerBytes[3];
+        const nonce = Session.generateNonce(securityFlags, header.messageId, this.#fabric.nodeId);
+
+        return {
+            header,
+            applicationPayload: Crypto.encrypt(this.#operationalGroupKey, applicationPayload, nonce, headerBytes),
+        };
+    }
+
+    decode(): DecodedMessage {
+        throw new InternalError("GroupSession does not support decode on instance.");
+    }
+
+    static decode(
+        fabrics: FabricManager,
+        { header, applicationPayload, messageExtension }: DecodedPacket,
+        aad: Uint8Array,
+    ): {
+        message: DecodedMessage;
+        key: Uint8Array;
+        sessionId: number;
+        sourceNodeId: NodeId;
+        keySetId: number;
+        fabric: Fabric;
+    } {
+        if (header.hasMessageExtensions) {
+            logger.info(
+                `Message extensions are not supported. Ignoring ${messageExtension ? Bytes.toHex(messageExtension) : undefined}`,
+            );
+        }
+        const sourceNodeId = header.sourceNodeId;
+        if (sourceNodeId === undefined) {
+            // Already checked on decoding, but validate twice
+            throw new UnexpectedDataError("Source Node ID is required for GroupSession decode.");
+        }
+        const nonce = Session.generateNonce(header.securityFlags, header.messageId, sourceNodeId);
+        const sessionId = header.sessionId;
+        const keys = new Array<{ key: Uint8Array; keySetId: number; fabric: Fabric }>();
+        for (const fabric of fabrics) {
+            const sessions = fabric.groups.sessions.get(sessionId);
+            if (sessions?.length) {
+                for (const session of sessions) {
+                    keys.push({ ...session, fabric });
+                }
+            }
+        }
+        if (keys.length === 0) {
+            throw new MatterFlowError("No key candidate found for group session decryption.");
+        }
+        let message: DecodedMessage | undefined;
+        let key: Uint8Array | undefined;
+        let fabric: Fabric | undefined;
+        let keySetId: number | undefined;
+        let found = false;
+        for ({ key, keySetId, fabric } of keys) {
+            try {
+                message = MessageCodec.decodePayload({
+                    header,
+                    applicationPayload: Crypto.decrypt(key, applicationPayload, nonce, aad),
+                });
+                found = true;
+                break; // Exit loop on first successful decryption
+            } catch (error) {
+                CryptoDecryptError.accept(error);
+            }
+        }
+        if (!found || !message || !key || !keySetId || !fabric) {
+            throw new MatterFlowError("Failed to decode group message with any key candidate.");
+        }
+
+        if (message.payloadHeader.hasSecuredExtension) {
+            logger.info(
+                `Secured extensions are not supported. Ignoring ${message.securityExtension ? Bytes.toHex(message.securityExtension) : undefined}`,
+            );
+        }
+
+        return { message, key, sessionId, sourceNodeId, keySetId, fabric };
+    }
+
+    async destroy() {
+        logger.info(`End group session ${this.name}`);
+        this.manager?.removeGroupSession(this);
+    }
+
+    end() {
+        return this.destroy();
+    }
+}
+
+export namespace GroupSession {
+    export function assert(session?: Session, errorText?: string): asserts session is GroupSession {
+        if (!is(session)) {
+            throw new MatterFlowError(errorText ?? "Insecure session in secure context");
+        }
+    }
+
+    export function is(session?: Session): session is GroupSession {
+        return session?.type === SessionType.Group;
+    }
+}

package/src/session/InsecureSession.ts

@@ -6,11 +6,11 @@
 
 import { Logger, MatterFlowError } from "#general";
 import { NodeId } from "#types";
-import { DecodedMessage, DecodedPacket, Message, MessageCodec, Packet } from "../codec/MessageCodec.js";
+import { DecodedMessage, DecodedPacket, Message, MessageCodec, Packet, SessionType } from "../codec/MessageCodec.js";
 import { Fabric } from "../fabric/Fabric.js";
 import { MessageCounter } from "../protocol/MessageCounter.js";
 import { MessageReceptionStateUnencryptedWithRollover } from "../protocol/MessageReceptionState.js";
-import { NoAssociatedFabricError } from "./SecureSession.js";
+import { NoAssociatedFabricError } from "./NodeSession.js";
 import { Session, SessionParameterOptions } from "./Session.js";
 import { SessionManager, UNICAST_UNSECURE_SESSION_ID } from "./SessionManager.js";
 
@@ -20,6 +20,7 @@ export class InsecureSession extends Session {
     readonly #initiatorNodeId: NodeId;
     readonly closingAfterExchangeFinished = false;
     readonly supportsMRP = true;
+    readonly type = SessionType.Unicast;
 
     constructor(args: {
         manager?: SessionManager;