@matter/protocol 0.16.0-alpha.0-20251016-b56cf5683 → 0.16.0-alpha.0-20251018-dd1ea6a8a

package/src/protocol/ExchangeManager.ts

@@ -225,6 +225,12 @@ export class ExchangeManager {
             message.payloadHeader.protocolId,
             message.payloadHeader.messageType,
         );
+        const messageDiagnostics = Diagnostic.dict({
+            message: messageId,
+            protocol: message.payloadHeader.protocolId,
+            exId: message.payloadHeader.exchangeId,
+            via: channel.name,
+        });
         if (exchange !== undefined) {
             if (
                 exchange.requiresSecureSession !== session.isSecure ||
@@ -232,14 +238,15 @@ export class ExchangeManager {
                 (exchange.isClosing && !isStandaloneAck)
             ) {
                 logger.debug(
-                    `Ignoring message ${messageId} for protocol ${message.payloadHeader.protocolId} and exchange id ${message.payloadHeader.exchangeId} on channel ${channel.name} because ${
-                        exchange.isClosing
-                            ? "exchange is closing"
-                            : exchange.session.id !== packet.header.sessionId
-                              ? `session ID mismatch ${exchange.session.id} vs ${packet.header.sessionId}`
-                              : `session security requirements (${exchange.requiresSecureSession}) not fulfilled`
-                    }`,
+                    "Ignore « message because",
+                    exchange.isClosing
+                        ? "exchange is closing"
+                        : exchange.session.id !== packet.header.sessionId
+                          ? `session ID mismatch ${exchange.session.id} vs ${packet.header.sessionId}`
+                          : `session security requirements (${exchange.requiresSecureSession}) not fulfilled`,
+                    messageDiagnostics,
                 );
+
                 await exchange.send(SecureMessageType.StandaloneAck, new Uint8Array(0), {
                     includeAcknowledgeMessageId: message.packetHeader.messageId,
                     protocolId: SECURE_CHANNEL_PROTOCOL_ID,
@@ -259,15 +266,15 @@ export class ExchangeManager {
 
             const protocolHandler = this.#protocols.get(message.payloadHeader.protocolId);
 
+            const handlerSecurityMismatch =
+                protocolHandler?.requiresSecureSession !== undefined &&
+                protocolHandler.requiresSecureSession !== session.isSecure;
             // Having a "Secure Session" means it is encrypted in our internal working
             // TODO When adding Group sessions, we need to check how to adjust that handling
-            if (
-                protocolHandler !== undefined &&
-                protocolHandler.requiresSecureSession !== session.isSecure &&
-                !isStandaloneAck
-            ) {
+            if (handlerSecurityMismatch) {
                 logger.debug(
-                    `Ignoring message ${messageId} for protocol ${message.payloadHeader.protocolId} and exchange id ${message.payloadHeader.exchangeId} on channel ${channel.name} because not matching the security requirements.`,
+                    `Ignore « message because not matching the security requirements (${protocolHandler.requiresSecureSession} vs. ${session.isSecure})`,
+                    messageDiagnostics,
                 );
             }
 
@@ -275,12 +282,10 @@ export class ExchangeManager {
                 protocolHandler !== undefined &&
                 message.payloadHeader.isInitiatorMessage &&
                 !isDuplicate &&
-                protocolHandler.requiresSecureSession === session.isSecure
+                !handlerSecurityMismatch
             ) {
                 if (isStandaloneAck && !message.payloadHeader.requiresAck) {
-                    logger.debug(
-                        `Ignoring unsolicited standalone ack message ${messageId} for protocol ${message.payloadHeader.protocolId} and exchange id ${message.payloadHeader.exchangeId} on channel ${channel.name}`,
-                    );
+                    logger.debug("Ignore « unsolicited standalone ack message", messageDiagnostics);
                     return;
                 }
 
@@ -302,9 +307,7 @@ export class ExchangeManager {
                     protocolId: SECURE_CHANNEL_PROTOCOL_ID,
                 });
                 await exchange.close();
-                logger.debug(
-                    `Ignoring unsolicited message ${messageId} for protocol ${message.payloadHeader.protocolId} on channel ${channel.name}`,
-                );
+                logger.debug("Ignore « unsolicited message", messageDiagnostics);
             } else {
                 if (protocolHandler === undefined) {
                     throw new MatterFlowError(`Unsupported protocol ${message.payloadHeader.protocolId}`);
@@ -312,17 +315,12 @@ export class ExchangeManager {
                 if (isDuplicate) {
                     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}`,
-                        );
+                        logger.debug("Ignore « duplicate message", messageDiagnostics);
                     }
                     return;
-                } else if (!isStandaloneAck) {
-                    logger.info(
-                        `Discarding unexpected message ${messageId} for protocol ${
-                            message.payloadHeader.protocolId
-                        }, exchangeIndex ${exchangeIndex} and sessionId ${session.id} on channel ${channel.name}: ${Diagnostic.json(message)}`,
-                    );
+                }
+                if (!isStandaloneAck) {
+                    logger.info("Discard « unexpected message", messageDiagnostics, Diagnostic.json(message));
                 }
             }
         }

package/src/protocol/MessageChannel.ts

@@ -5,7 +5,7 @@
  */
 
 import { Message, MessageCodec } from "#codec/MessageCodec.js";
-import { Bytes, Channel, Duration, Logger, MatterError, MatterFlowError, Millis, Seconds } from "#general";
+import { Bytes, Channel, Diagnostic, Duration, Logger, MatterError, MatterFlowError, Millis, Seconds } from "#general";
 import type { ExchangeLogContext } from "#protocol/MessageExchange.js";
 import { Session, SessionParameters } from "#session/Session.js";
 
@@ -101,7 +101,7 @@ export class MessageChannel implements Channel<Message> {
     }
 
     get name() {
-        return `${this.channel.name} on session ${this.session.name}`;
+        return Diagnostic.via(`${this.session.name}@${this.channel.name}`);
     }
 
     async close() {

package/src/protocol/MessageExchange.ts

@@ -30,6 +30,7 @@ import {
     MRP,
 } from "#protocol/MessageChannel.js";
 import { GroupSession } from "#session/GroupSession.js";
+import { SecureSession } from "#session/SecureSession.js";
 import { SessionParameters } from "#session/Session.js";
 import {
     GroupId,
@@ -199,8 +200,8 @@ export class MessageExchange {
         logger.debug(
             "New exchange",
             isInitiator ? "»" : "«",
+            channel.name,
             Diagnostic.dict({
-                channel: channel.name,
                 protocol: this.#protocolId,
                 exId: this.#exchangeId,
                 sess: session.name,
@@ -582,12 +583,16 @@ export class MessageExchange {
                 StatusCode.InvalidAction,
             );
         }
+
         logger.debug(
-            `Starting timed interaction with Transaction ID ${this.#exchangeId} for ${Duration.format(timeout)} from ${this.channel.name}`,
+            "Starting timed interaction «",
+            this.channel.name,
+            Diagnostic.dict({ exId: this.#exchangeId, timeout: Duration.format(timeout) }),
         );
         this.#timedInteractionTimer = Time.getTimer("Timed interaction", timeout, () => {
             logger.debug(
-                `Timed interaction with Transaction ID ${this.#exchangeId} from ${this.channel.name} timed out`,
+                "Timed interaction timeout!",
+                Diagnostic.dict({ exId: this.#exchangeId, via: this.channel.name }),
             );
         }).start();
     }
@@ -595,7 +600,8 @@ export class MessageExchange {
     clearTimedInteraction() {
         if (this.#timedInteractionTimer !== undefined) {
             logger.debug(
-                `Clearing timed interaction with Transaction ID ${this.#exchangeId} from ${this.channel.name}`,
+                "Clearing timed interaction",
+                Diagnostic.dict({ exId: this.#exchangeId, via: this.channel.name }),
             );
             this.#timedInteractionTimer.stop();
             this.#timedInteractionTimer = undefined;
@@ -679,4 +685,12 @@ export class MessageExchange {
         this.#messagesQueue.close();
         await this.#closed.emit();
     }
+
+    get via() {
+        if (this.session == undefined || !this.session.isSecure) {
+            return this.channel.name; // already formatted as "via"
+        }
+
+        return Diagnostic.via(`${(this.session as SecureSession).peerAddress.toString()}#${this.session.id}`);
+    }
 }

package/src/protocol/ProtocolHandler.ts

@@ -11,8 +11,13 @@ export interface ProtocolHandler {
     /** Protocol ID that this handler implements */
     readonly id: number;
 
-    /** Indicates whether this protocol requires a secure session to be established before it can be used */
-    readonly requiresSecureSession: boolean;
+    /**
+     * Indicates whether this protocol requires a secure session to be established before it can be used.
+     * When `true`, the protocol can only be used over secure sessions.
+     * When `false`, the protocol can only be used without a secure session.
+     * When `undefined`, the protocol can be used with or without a secure session and it is up to the handler to check
+     */
+    readonly requiresSecureSession: boolean | undefined;
 
     /** Called on a new exchange that uses this protocol. The message is the first message of the exchange. */
     onNewExchange(exchange: MessageExchange, message: Message): Promise<void>;

package/src/securechannel/SecureChannelProtocol.ts

@@ -29,7 +29,9 @@ const logger = Logger.get("SecureChannelProtocol");
 
 export class StatusReportOnlySecureChannelProtocol implements ProtocolHandler {
     readonly id = SECURE_CHANNEL_PROTOCOL_ID;
-    readonly requiresSecureSession = false;
+
+    // We need to check the message details to decide if ok or not, so we take them all
+    readonly requiresSecureSession = undefined;
 
     async onNewExchange(exchange: MessageExchange, message: Message) {
         const messageType = message.payloadHeader.messageType;
@@ -70,6 +72,8 @@ export class StatusReportOnlySecureChannelProtocol implements ProtocolHandler {
                 protocolStatus,
             );
         }
+
+        // CloseSession is the only case where a StatusReport comes as initial message
         if (protocolStatus !== SecureChannelStatusCode.CloseSession) {
             throw new ChannelStatusResponseError(
                 `Received general success status, but protocol status is not CloseSession`,

package/src/session/GroupSession.ts

@@ -16,8 +16,9 @@ import {
     MatterFlowError,
     UnexpectedDataError,
 } from "#general";
+import { PeerAddress } from "#peer/PeerAddress.js";
 import type { SessionManager } from "#session/SessionManager.js";
-import { GroupId, NodeId } from "#types";
+import { FabricIndex, GroupId, NodeId } from "#types";
 import { SecureSession } from "./SecureSession.js";
 import { Session } from "./Session.js";
 
@@ -92,6 +93,16 @@ export class GroupSession extends SecureSession {
         return this.#fabric;
     }
 
+    /**
+     * The peer group's address.
+     */
+    get peerAddress() {
+        return PeerAddress({
+            fabricIndex: this.#fabric?.fabricIndex ?? FabricIndex.NO_FABRIC,
+            nodeId: this.#peerNodeId,
+        });
+    }
+
     subjectFor(message?: Message): Subject {
         if (message === undefined || message.packetHeader.destGroupId === undefined) {
             throw new ImplementationError("GroupSession requires a message with destGroupId");

package/src/session/NodeSession.ts

@@ -22,6 +22,7 @@ import type { Subscription } from "#interaction/Subscription.js";
 import { PeerAddress } from "#peer/PeerAddress.js";
 import { MessageCounter } from "#protocol/MessageCounter.js";
 import { MessageReceptionStateEncryptedWithoutRollover } from "#protocol/MessageReceptionState.js";
+import { SecureChannelMessenger } from "#securechannel/SecureChannelMessenger.js";
 import { CaseAuthenticatedTag, FabricIndex, NodeId, StatusCode, StatusResponseError } from "#types";
 import { SecureSession } from "./SecureSession.js";
 import { Session, SessionParameterOptions } from "./Session.js";
@@ -392,4 +393,24 @@ export namespace NodeSession {
     export function is(session?: Session): session is NodeSession {
         return session?.type === SessionType.Unicast;
     }
+
+    export function logNew(
+        logger: Logger,
+        operation: "New" | "Resumed",
+        session: NodeSession,
+        messenger: SecureChannelMessenger,
+        fabric: Fabric,
+        peerNodeId: NodeId,
+    ) {
+        logger.info(
+            `${operation} session with`,
+            Diagnostic.strong(PeerAddress({ fabricIndex: fabric.fabricIndex, nodeId: peerNodeId }).toString()),
+            Diagnostic.dict({
+                id: session.id,
+                address: messenger.channelName,
+                fabric: `${NodeId.toHexString(fabric.nodeId)} (#${fabric.fabricIndex})`,
+                ...session.parameterDiagnostics,
+            }),
+        );
+    }
 }

package/src/session/SecureSession.ts

@@ -7,11 +7,13 @@ import { Subject } from "#action/server/Subject.js";
 import { Message } from "#codec/MessageCodec.js";
 import { Fabric } from "#fabric/Fabric.js";
 import { MatterFlowError } from "#general";
+import { PeerAddress } from "#peer/PeerAddress.js";
 import { Session } from "./Session.js";
 
 export abstract class SecureSession extends Session {
     readonly isSecure = true;
     abstract fabric: Fabric | undefined;
+    abstract peerAddress: PeerAddress;
     abstract subjectFor(message?: Message): Subject;
 }
 

package/src/session/case/CaseClient.ts

@@ -7,8 +7,7 @@
 import { Icac } from "#certificate/kinds/Icac.js";
 import { Noc } from "#certificate/kinds/Noc.js";
 import { Fabric } from "#fabric/Fabric.js";
-import { Bytes, Diagnostic, Duration, Logger, PublicKey, UnexpectedDataError } from "#general";
-import { PeerAddress } from "#peer/PeerAddress.js";
+import { Bytes, Duration, Logger, PublicKey, UnexpectedDataError } from "#general";
 import { MessageExchange, RetransmissionLimitReachedError } from "#protocol/MessageExchange.js";
 import { ChannelStatusResponseError } from "#securechannel/SecureChannelMessenger.js";
 import { NodeSession } from "#session/NodeSession.js";
@@ -135,7 +134,7 @@ export class CaseClient {
                 caseAuthenticatedTags,
             });
             await messenger.sendSuccess();
-            this.#logNewSession("Resumed", secureSession, messenger, fabric, peerNodeId);
+            NodeSession.logNew(logger, "Resumed", secureSession, messenger, fabric, peerNodeId);
 
             resumptionRecord.resumptionId = resumptionId; /* update resumptionId */
             resumptionRecord.sessionParameters = secureSession.parameters; /* update mrpParams */
@@ -246,7 +245,7 @@ export class CaseClient {
                 peerSessionParameters,
                 caseAuthenticatedTags: sessionCaseAuthenticatedTags,
             });
-            this.#logNewSession("New", secureSession, messenger, fabric, peerNodeId);
+            NodeSession.logNew(logger, "New", secureSession, messenger, fabric, peerNodeId);
             resumptionRecord = {
                 fabric,
                 peerNodeId,
@@ -262,25 +261,6 @@ export class CaseClient {
 
         return { session: secureSession, resumed };
     }
-
-    #logNewSession(
-        operation: "New" | "Resumed",
-        session: NodeSession,
-        messenger: CaseClientMessenger,
-        fabric: Fabric,
-        peerNodeId: NodeId,
-    ) {
-        logger.info(
-            `${operation} session with`,
-            Diagnostic.strong(PeerAddress({ fabricIndex: fabric.fabricIndex, nodeId: peerNodeId }).toString()),
-            Diagnostic.dict({
-                id: session.id,
-                address: messenger.channelName,
-                fabric: `${NodeId.toHexString(fabric.nodeId)} (#${fabric.fabricIndex})`,
-                ...session.parameterDiagnostics,
-            }),
-        );
-    }
 }
 
 export namespace CaseClient {

package/src/session/case/CaseServer.ts

@@ -5,10 +5,11 @@
  */
 
 import { Noc } from "#certificate/kinds/Noc.js";
-import { Bytes, Crypto, CryptoDecryptError, Logger, PublicKey, UnexpectedDataError } from "#general";
+import { Bytes, Crypto, CryptoDecryptError, Diagnostic, Logger, PublicKey, UnexpectedDataError } from "#general";
+import { NodeSession } from "#session/NodeSession.js";
 import { SessionParametersWithDurations } from "#session/pase/PaseMessages.js";
 import { ResumptionRecord, SessionManager } from "#session/SessionManager.js";
-import { NodeId, SECURE_CHANNEL_PROTOCOL_ID, SecureChannelStatusCode } from "#types";
+import { SECURE_CHANNEL_PROTOCOL_ID, SecureChannelStatusCode } from "#types";
 import { FabricManager, FabricNotFoundError } from "../../fabric/FabricManager.js";
 import { MessageExchange } from "../../protocol/MessageExchange.js";
 import { ProtocolHandler } from "../../protocol/ProtocolHandler.js";
@@ -64,7 +65,7 @@ export class CaseServer implements ProtocolHandler {
     }
 
     async #handleSigma1(messenger: CaseServerMessenger) {
-        logger.info(`Received pairing request from ${messenger.channelName}`);
+        logger.info("Received pairing request «", Diagnostic.via(messenger.channelName));
 
         // Initialize context with information from peer
         const { sigma1Bytes, sigma1 } = await messenger.readSigma1();
@@ -86,9 +87,12 @@ export class CaseServer implements ProtocolHandler {
         }
 
         logger.info(
-            `Invalid resumption ID or resume MIC received from ${messenger.channelName}`,
-            context.peerResumptionId,
-            context.peerResumeMic,
+            "Invalid resumption ID or resume MIC received from",
+            messenger.channelName,
+            Diagnostic.dict({
+                resumptionId: context.peerResumptionId,
+                resumeMic: context.peerResumeMic,
+            }),
         );
 
         throw new UnexpectedDataError("Invalid resumption ID or resume MIC.");
@@ -152,13 +156,8 @@ export class CaseServer implements ProtocolHandler {
             throw error;
         }
 
-        logger.info(
-            `Session ${secureSession.id} resumed with ${cx.messenger.channelName} for Fabric ${NodeId.toHexString(
-                fabric.nodeId,
-            )} (index ${fabric.fabricIndex}) and PeerNode ${NodeId.toHexString(peerNodeId)}`,
-            "with CATs",
-            caseAuthenticatedTags,
-        );
+        NodeSession.logNew(logger, "Resumed", secureSession, cx.messenger, fabric, peerNodeId);
+
         cx.resumptionRecord.resumptionId = cx.localResumptionId; /* Update the ID */
 
         // Wait for success on the peer side
@@ -274,13 +273,9 @@ export class CaseServer implements ProtocolHandler {
             peerSessionParameters: cx.peerSessionParams,
             caseAuthenticatedTags,
         });
-        logger.info(
-            `Session ${secureSession.id} created with ${cx.messenger.channelName} for Fabric ${NodeId.toHexString(
-                fabric.nodeId,
-            )} (index ${fabric.fabricIndex}) and PeerNode ${NodeId.toHexString(peerNodeId)}`,
-            "with CATs",
-            caseAuthenticatedTags,
-        );
+
+        NodeSession.logNew(logger, "New", secureSession, cx.messenger, fabric, peerNodeId);
+
         await cx.messenger.sendSuccess();
 
         const resumptionRecord = {

package/src/session/pase/PaseClient.ts

@@ -106,7 +106,7 @@ export class PaseClient {
             peerSessionParameters,
         });
         await messenger.close();
-        logger.info(`Pase client: Paired successfully with ${messenger.channelName}.`);
+        logger.info("Paired successfully »", messenger.channelName);
 
         return secureSession;
     }

package/src/session/pase/PaseServer.ts

@@ -7,6 +7,7 @@
 import {
     Bytes,
     Crypto,
+    Diagnostic,
     ec,
     Logger,
     MatterFlowError,
@@ -104,7 +105,7 @@ export class PaseServer implements ProtocolHandler {
     }
 
     private async handlePairingRequest(crypto: Crypto, messenger: PaseServerMessenger) {
-        logger.info(`Received pairing request from ${messenger.channelName}.`);
+        logger.info("Received pairing request «", Diagnostic.via(messenger.channelName));
 
         this.#pairingTimer = Time.getTimer("PASE pairing timeout", PASE_PAIRING_TIMEOUT_MS, () =>
             this.cancelPairing(messenger),
@@ -167,7 +168,7 @@ export class PaseServer implements ProtocolHandler {
             isResumption: false,
             peerSessionParameters: initiatorSessionParams,
         });
-        logger.info(`Session ${responderSessionId} created with ${messenger.channelName}.`);
+        logger.info(Diagnostic.strong(`Session ${responderSessionId} created`), "with", messenger.channelName);
 
         await messenger.sendSuccess();
         await messenger.close();