@matter/protocol 0.15.1 → 0.15.2-alpha.0-20250704-2715344f0

package/src/mdns/MdnsScanner.ts

@@ -96,13 +96,12 @@ const START_ANNOUNCE_INTERVAL_SECONDS = 1.5;
 /**
  * Interface to add criteria for MDNS discovery a node is interested in
  *
- * This interface is used to define criteria for mDNS scanner targets.
- * It includes the information if commissionable devices are relevant for the target
- * and a list of operational targets. Operational targets can consist of operational IDs
- * and optional node IDs.
+ * This interface is used to define criteria for mDNS scanner targets. It includes the information if commissionable
+ * devices are relevant for the target and a list of operational targets. Operational targets can consist of operational
+ * IDs and optional node IDs.
  *
- * When no commissionable devices are relevant and no operational targets are defined, it is
- * not required to add a criteria to the scanner.
+ * When no commissionable devices are relevant and no operational targets are defined, it is not required to add a
+ * criteria to the scanner.
  */
 export interface MdnsScannerTargetCriteria {
     /** Are commissionable MDNS records relevant? */

package/src/peer/ControllerCommissioner.ts

@@ -34,8 +34,8 @@ import { ControllerDiscovery, PairRetransmissionLimitReachedError } from "#peer/
 import { ExchangeManager } from "#protocol/ExchangeManager.js";
 import { DedicatedChannelExchangeProvider } from "#protocol/ExchangeProvider.js";
 import { MessageChannel } from "#protocol/MessageChannel.js";
-import { ChannelStatusResponseError } from "#securechannel/index.js";
-import { PaseClient } from "#session/index.js";
+import { ChannelStatusResponseError } from "#securechannel/SecureChannelMessenger.js";
+import { PaseClient } from "#session/pase/PaseClient.js";
 import { SessionManager } from "#session/SessionManager.js";
 import { DiscoveryCapabilitiesBitmap, NodeId, SECURE_CHANNEL_PROTOCOL_ID, TypeFromPartialBitSchema } from "#types";
 import { PeerAddress } from "./PeerAddress.js";

package/src/peer/ControllerCommissioningFlow.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { X509Base } from "#certificate/index.js";
+import { X509Base } from "#certificate/kinds/X509Base.js";
 import { BasicInformation } from "#clusters/basic-information";
 import { Descriptor } from "#clusters/descriptor";
 import { GeneralCommissioning } from "#clusters/general-commissioning";

package/src/peer/OperationalPeer.ts

@@ -6,7 +6,7 @@
 
 import { DiscoveryData } from "#common/Scanner.js";
 import { ServerAddressIp } from "#general";
-import { PeerDataStore } from "#peer/PeerAddressStore.js";
+import type { PeerDataStore } from "#peer/PeerAddressStore.js";
 import { SessionParameters } from "#session/Session.js";
 import { PeerAddress } from "./PeerAddress.js";
 

package/src/peer/PeerAddress.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { FabricIndex, NodeId } from "#types";
+import { FabricIndex, GroupId, NodeId } from "#types";
 
 /**
  * This is the "logical" address of a peer node consisting of a fabric and node ID.
@@ -66,7 +66,7 @@ export namespace PeerAddress {
     }
 
     export function isGroup(address: PeerAddress): boolean {
-        return NodeId.isGroupNodeId(address.nodeId);
+        return GroupId.isGroupNodeId(address.nodeId);
     }
 }
 

package/src/peer/PeerAddressStore.ts

@@ -5,7 +5,7 @@
  */
 
 import { Construction, MaybePromise } from "#general";
-import { DecodedAttributeReportValue } from "#interaction/index.js";
+import { DecodedAttributeReportValue } from "#interaction/AttributeDataDecoder.js";
 import { AttributeId, ClusterId, EndpointNumber, EventNumber } from "#types";
 import { OperationalPeer } from "./OperationalPeer.js";
 import { PeerAddress } from "./PeerAddress.js";

package/src/peer/PeerSet.ts

@@ -33,12 +33,14 @@ import { SubscriptionClient } from "#interaction/SubscriptionClient.js";
 import { MdnsScanner } from "#mdns/MdnsScanner.js";
 import { PeerAddress, PeerAddressMap } from "#peer/PeerAddress.js";
 import { ChannelManager } from "#protocol/ChannelManager.js";
-import { ChannelNotConnectedError, ExchangeManager } from "#protocol/ExchangeManager.js";
+import { ExchangeManager } from "#protocol/ExchangeManager.js";
 import { DedicatedChannelExchangeProvider, ReconnectableExchangeProvider } from "#protocol/ExchangeProvider.js";
-import { MessageChannel } from "#protocol/MessageChannel.js";
+import { ChannelNotConnectedError, MessageChannel } from "#protocol/MessageChannel.js";
 import { MessageExchange, RetransmissionLimitReachedError } from "#protocol/MessageExchange.js";
-import { ChannelStatusResponseError } from "#securechannel/index.js";
-import { CaseClient, SecureSession, Session } from "#session/index.js";
+import { ChannelStatusResponseError } from "#securechannel/SecureChannelMessenger.js";
+import { CaseClient } from "#session/case/CaseClient.js";
+import { SecureSession } from "#session/SecureSession.js";
+import { Session } from "#session/Session.js";
 import { SessionManager } from "#session/SessionManager.js";
 import { GroupId, NodeId, SECURE_CHANNEL_PROTOCOL_ID, SecureChannelStatusCode } from "#types";
 import { ControllerDiscovery, DiscoveryError, PairRetransmissionLimitReachedError } from "./ControllerDiscovery.js";

package/src/protocol/ChannelManager.ts

@@ -4,16 +4,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { AsyncObservable, Channel, Environment, Environmental, Logger, MatterError } from "#general";
+import { AsyncObservable, Channel, Environment, Environmental, Logger } from "#general";
 import { PeerAddress, PeerAddressMap } from "#peer/PeerAddress.js";
 import { MessageChannel } from "#protocol/MessageChannel.js";
-import { NodeSession } from "#session/NodeSession.js";
+import { NoChannelError, NodeSession } from "#session/NodeSession.js";
 import { Session } from "#session/Session.js";
 
 const logger = Logger.get("ChannelManager");
 
-export class NoChannelError extends MatterError {}
-
 export class ChannelManager {
     readonly #channels = new PeerAddressMap<MessageChannel[]>();
     readonly #paseChannels = new Map<Session, MessageChannel>();

package/src/protocol/DeviceCommissioner.ts

@@ -20,7 +20,8 @@ import {
     ObserverGroup,
 } from "#general";
 import { SecureChannelProtocol } from "#securechannel/SecureChannelProtocol.js";
-import { PaseServer, SessionManager } from "#session/index.js";
+import { PaseServer } from "#session/pase/PaseServer.js";
+import { SessionManager } from "#session/SessionManager.js";
 import { CommissioningOptions, StatusCode, StatusResponseError } from "#types";
 import type { ControllerCommissioner } from "../peer/ControllerCommissioner.js";
 import { DeviceAdvertiser } from "./DeviceAdvertiser.js";
@@ -162,9 +163,7 @@ export class DeviceCommissioner {
         );
     }
 
-    async beginTimed(failsafeContext: FailsafeContext) {
-        await failsafeContext.construction;
-
+    beginTimed(failsafeContext: FailsafeContext) {
         this.#failsafeContext = failsafeContext;
 
         this.#context.fabrics.events.added.on(fabric => {
@@ -246,10 +245,7 @@ export class DeviceCommissioner {
         this.#activeDiscriminator = discriminator;
 
         // MDNS is sent in parallel
-        // TODO - untracked promise
-        this.#enterCommissioningMode(windowStatus, discriminator).catch(error =>
-            logger.warn("Error sending announcement:", error),
-        );
+        await this.#enterCommissioningMode(windowStatus, discriminator);
     }
 
     async endCommissioning() {

package/src/protocol/ExchangeManager.ts

@@ -23,15 +23,19 @@ import {
     UnexpectedDataError,
 } from "#general";
 import { PeerAddress } from "#peer/PeerAddress.js";
-import { MessageChannel } from "#protocol/MessageChannel.js";
+import {
+    ChannelNotConnectedError,
+    DEFAULT_EXPECTED_PROCESSING_TIME_MS,
+    MessageChannel,
+} from "#protocol/MessageChannel.js";
 import { SecureChannelMessenger } from "#securechannel/SecureChannelMessenger.js";
-import { SecureChannelProtocol } from "#securechannel/SecureChannelProtocol.js";
+import { UNICAST_UNSECURE_SESSION_ID } from "#session/InsecureSession.js";
 import { NodeSession } from "#session/NodeSession.js";
 import { Session } from "#session/Session.js";
-import { SessionManager, UNICAST_UNSECURE_SESSION_ID } from "#session/SessionManager.js";
+import { SessionManager } from "#session/SessionManager.js";
 import { NodeId, SECURE_CHANNEL_PROTOCOL_ID, SecureMessageType } from "#types";
 import { ChannelManager } from "./ChannelManager.js";
-import { DEFAULT_EXPECTED_PROCESSING_TIME_MS, MessageExchange, MessageExchangeContext } from "./MessageExchange.js";
+import { MessageExchange, MessageExchangeContext } from "./MessageExchange.js";
 import { DuplicateMessageError } from "./MessageReceptionState.js";
 import { ProtocolHandler } from "./ProtocolHandler.js";
 
@@ -39,8 +43,6 @@ const logger = Logger.get("ExchangeManager");
 
 const MAXIMUM_CONCURRENT_EXCHANGES_PER_SESSION = 5;
 
-export class ChannelNotConnectedError extends MatterError {}
-
 /**
  * Interfaces {@link ExchangeManager} with other components.
  */
@@ -217,7 +219,7 @@ export class ExchangeManager {
             exchange = undefined;
         }
 
-        const isStandaloneAck = SecureChannelProtocol.isStandaloneAck(
+        const isStandaloneAck = SecureMessageType.isStandaloneAck(
             message.payloadHeader.protocolId,
             message.payloadHeader.messageType,
         );

package/src/protocol/ExchangeProvider.ts

@@ -6,9 +6,13 @@
 import { ChannelType, Observable } from "#general";
 import { PeerAddress } from "#peer/PeerAddress.js";
 import { ChannelManager } from "#protocol/ChannelManager.js";
-import { ChannelNotConnectedError, ExchangeManager } from "#protocol/ExchangeManager.js";
-import { MessageChannel } from "#protocol/MessageChannel.js";
-import { DEFAULT_EXPECTED_PROCESSING_TIME_MS, MessageExchange } from "#protocol/MessageExchange.js";
+import { ExchangeManager } from "#protocol/ExchangeManager.js";
+import {
+    ChannelNotConnectedError,
+    DEFAULT_EXPECTED_PROCESSING_TIME_MS,
+    MessageChannel,
+} from "#protocol/MessageChannel.js";
+import { MessageExchange } from "#protocol/MessageExchange.js";
 import { ProtocolHandler } from "#protocol/ProtocolHandler.js";
 import { Session } from "#session/Session.js";
 import { INTERACTION_PROTOCOL_ID } from "#types";

package/src/protocol/MessageChannel.ts

@@ -1,10 +1,25 @@
-import { Message, MessageCodec } from "#codec/index.js";
-import { Channel, Logger, MatterFlowError } from "#general";
-import { DEFAULT_EXPECTED_PROCESSING_TIME_MS, ExchangeLogContext } from "#protocol/MessageExchange.js";
-import { Session, SessionParameters } from "#session/index.js";
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Message, MessageCodec } from "#codec/MessageCodec.js";
+import { Channel, Logger, MatterError, MatterFlowError } from "#general";
+import type { ExchangeLogContext } from "#protocol/MessageExchange.js";
+import { Session, SessionParameters } from "#session/Session.js";
 
 const logger = new Logger("MessageChannel");
 
+export class ChannelNotConnectedError extends MatterError {}
+
+/**
+ * Default expected processing time for a messages in milliseconds. The value is derived from kExpectedIMProcessingTime
+ * from chip implementation. This is basically the default used with different names, also kExpectedLowProcessingTime or
+ * kExpectedSigma1ProcessingTime.
+ */
+export const DEFAULT_EXPECTED_PROCESSING_TIME_MS = 2000;
+
 /**
  * The buffer time in milliseconds to add to the peer response time to also consider network delays and other factors.
  * TODO: This is a pure guess and should be adjusted in the future.

package/src/protocol/MessageExchange.ts

@@ -19,8 +19,12 @@ import {
     Time,
     Timer,
 } from "#general";
-import { MessageChannel, MRP } from "#protocol/MessageChannel.js";
-import { SecureChannelProtocol } from "#securechannel/SecureChannelProtocol.js";
+import {
+    ChannelNotConnectedError,
+    DEFAULT_EXPECTED_PROCESSING_TIME_MS,
+    MessageChannel,
+    MRP,
+} from "#protocol/MessageChannel.js";
 import { GroupSession } from "#session/GroupSession.js";
 import {
     SESSION_ACTIVE_INTERVAL_MS,
@@ -36,7 +40,6 @@ import {
     StatusCode,
     StatusResponseError,
 } from "#types";
-import { ChannelNotConnectedError } from "./ExchangeManager.js";
 
 const logger = Logger.get("MessageExchange");
 
@@ -87,13 +90,6 @@ export type ExchangeSendOptions = {
     logContext?: ExchangeLogContext;
 };
 
-/**
- * Default expected processing time for a messages in milliseconds. The value is derived from kExpectedIMProcessingTime
- * from chip implementation. This is basically the default used with different names, also kExpectedLowProcessingTime or
- * kExpectedSigma1ProcessingTime.
- */
-export const DEFAULT_EXPECTED_PROCESSING_TIME_MS = 2_000;
-
 /**
  * Message size overhead of a Matter message:
  * 26 (Matter Message Header) + 12 (Matter Payload Header) taken from https://github.com/project-chip/connectedhomeip/blob/2d97cda23024e72f36216900ca667bf1a0d9499f/src/system/SystemConfig.h#L327
@@ -285,7 +281,7 @@ export class MessageExchange {
             payloadHeader: { requiresAck, ackedMessageId, protocolId, messageType },
         } = message;
 
-        const isStandaloneAck = SecureChannelProtocol.isStandaloneAck(protocolId, messageType);
+        const isStandaloneAck = SecureMessageType.isStandaloneAck(protocolId, messageType);
         if (protocolId !== this.#protocolId && !isStandaloneAck) {
             throw new MatterFlowError(
                 `Drop received a message for an unexpected protocol. Expected: ${this.#protocolId}, received: ${protocolId}`,
@@ -468,7 +464,7 @@ export class MessageExchange {
             const {
                 payloadHeader: { protocolId, messageType },
             } = responseMessage;
-            if (expectAckOnly && !SecureChannelProtocol.isStandaloneAck(protocolId, messageType)) {
+            if (expectAckOnly && !SecureMessageType.isStandaloneAck(protocolId, messageType)) {
                 throw new UnexpectedMessageError("Expected ack only", responseMessage);
             }
         }

package/src/securechannel/SecureChannelMessenger.ts

@@ -60,6 +60,7 @@ export class SecureChannelMessenger {
 
     /**
      * Waits for the next message and returns it.
+     *
      * When no expectedProcessingTimeMs is provided, the default value of EXPECTED_CRYPTO_PROCESSING_TIME_MS is used.
      */
     async #nextMessage(
@@ -82,6 +83,7 @@ export class SecureChannelMessenger {
 
     /**
      * Waits for the next message and decodes it.
+     *
      * When no expectedProcessingTimeMs is provided, the default value of EXPECTED_CRYPTO_PROCESSING_TIME_MS is used.
      */
     async nextMessageDecoded<T>(
@@ -94,6 +96,7 @@ export class SecureChannelMessenger {
 
     /**
      * Waits for the next message and returns it.
+     *
      * When no expectedProcessingTimeMs is provided, the default value of EXPECTED_CRYPTO_PROCESSING_TIME_MS is used.
      */
     async waitForSuccess(
@@ -106,6 +109,7 @@ export class SecureChannelMessenger {
 
     /**
      * Sends a message of the given type with the given payload.
+     *
      * If no ExchangeSendOptions are provided, the expectedProcessingTimeMs will be set to
      * EXPECTED_CRYPTO_PROCESSING_TIME_MS.
      */

package/src/securechannel/SecureChannelProtocol.ts

@@ -150,8 +150,4 @@ export class SecureChannelProtocol extends StatusReportOnlySecureChannelProtocol
                 await super.onNewExchange(exchange, message);
         }
     }
-
-    static isStandaloneAck(protocolId: number, messageType: number) {
-        return protocolId === SECURE_CHANNEL_PROTOCOL_ID && messageType === SecureMessageType.StandaloneAck;
-    }
 }

package/src/session/GroupSession.ts

@@ -4,7 +4,7 @@
  * 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 { DecodedMessage, DecodedPacket, Message, MessageCodec, Packet, SessionType } from "#codec/MessageCodec.js";
 import { Fabric } from "#fabric/Fabric.js";
 import { FabricManager } from "#fabric/FabricManager.js";
 import {

package/src/session/InsecureSession.ts

@@ -12,10 +12,12 @@ import { MessageCounter } from "../protocol/MessageCounter.js";
 import { MessageReceptionStateUnencryptedWithRollover } from "../protocol/MessageReceptionState.js";
 import { NoAssociatedFabricError } from "./NodeSession.js";
 import { Session, SessionParameterOptions } from "./Session.js";
-import { SessionManager, UNICAST_UNSECURE_SESSION_ID } from "./SessionManager.js";
+import type { SessionManager } from "./SessionManager.js";
 
 const logger = Logger.get("InsecureSession");
 
+export const UNICAST_UNSECURE_SESSION_ID = 0x0000;
+
 export class InsecureSession extends Session {
     readonly #initiatorNodeId: NodeId;
     readonly closingAfterExchangeFinished = false;

package/src/session/NodeSession.ts

@@ -7,22 +7,32 @@
 import { Subject } from "#action/server/Subject.js";
 import { DecodedMessage, DecodedPacket, Message, MessageCodec, Packet, SessionType } from "#codec/MessageCodec.js";
 import { Fabric } from "#fabric/Fabric.js";
-import { BasicSet, Bytes, CRYPTO_SYMMETRIC_KEY_LENGTH, Crypto, Diagnostic, Logger, MatterFlowError } from "#general";
-import { Subscription } from "#interaction/Subscription.js";
+import {
+    BasicSet,
+    Bytes,
+    CRYPTO_SYMMETRIC_KEY_LENGTH,
+    Crypto,
+    Diagnostic,
+    Logger,
+    MatterError,
+    MatterFlowError,
+} from "#general";
+import type { Subscription } from "#interaction/Subscription.js";
 import { PeerAddress } from "#peer/PeerAddress.js";
-import { NoChannelError } from "#protocol/ChannelManager.js";
 import { MessageCounter } from "#protocol/MessageCounter.js";
 import { MessageReceptionStateEncryptedWithoutRollover } from "#protocol/MessageReceptionState.js";
 import { CaseAuthenticatedTag, FabricIndex, NodeId, StatusCode, StatusResponseError } from "#types";
 import { SecureSession } from "./SecureSession.js";
 import { Session, SessionParameterOptions } from "./Session.js";
-import { type SessionManager } from "./SessionManager.js";
+import type { SessionManager } from "./SessionManager.js";
 
 const logger = Logger.get("SecureSession");
 
 const SESSION_KEYS_INFO = Bytes.fromString("SessionKeys");
 const SESSION_RESUMPTION_KEYS_INFO = Bytes.fromString("SessionResumptionKeys");
 
+export class NoChannelError extends MatterError {}
+
 export class NoAssociatedFabricError extends StatusResponseError {
     constructor(message: string) {
         super(message, StatusCode.UnsupportedAccess);

package/src/session/SessionManager.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { DecodedPacket } from "#codec/index.js";
+import { DecodedPacket } from "#codec/MessageCodec.js";
 import { FabricManager } from "#fabric/FabricManager.js";
 import {
     BasicSet,
@@ -62,8 +62,6 @@ const DEFAULT_SESSION_PARAMETERS = {
     maxTcpMessageSize: FALLBACK_MAX_TCP_MESSAGE_SIZE,
 };
 
-export const UNICAST_UNSECURE_SESSION_ID = 0x0000;
-
 export interface ResumptionRecord {
     sharedSecret: Uint8Array;
     resumptionId: Uint8Array;

package/src/session/case/CaseClient.ts

@@ -4,9 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Icac, Noc } from "#certificate/index.js";
+import { Icac } from "#certificate/kinds/Icac.js";
+import { Noc } from "#certificate/kinds/Noc.js";
 import { Bytes, Logger, PublicKey, UnexpectedDataError } from "#general";
-import { ChannelStatusResponseError } from "#securechannel/index.js";
+import { ChannelStatusResponseError } from "#securechannel/SecureChannelMessenger.js";
 import { SessionManager } from "#session/SessionManager.js";
 import { NodeId, SecureChannelStatusCode } from "#types";
 import { Fabric } from "../../fabric/Fabric.js";

package/src/session/case/CaseServer.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Noc } from "#certificate/index.js";
+import { Noc } from "#certificate/kinds/Noc.js";
 import { Bytes, Crypto, CryptoDecryptError, Logger, PublicKey, UnexpectedDataError } from "#general";
 import { TlvSessionParameters } from "#session/pase/PaseMessages.js";
 import { ResumptionRecord, SessionManager } from "#session/SessionManager.js";

package/src/session/pase/PaseMessages.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { SupportedTransportsBitmap } from "#common/index.js";
+import { SupportedTransportsBitmap } from "#common/Scanner.js";
 import { CRYPTO_HASH_LEN_BYTES, CRYPTO_PUBLIC_KEY_SIZE_BYTES } from "#general";
 import {
     TlvBitmap,