@matter/protocol 0.16.0-alpha.0-20251203-aaf94bca8 → 0.16.0-alpha.0-20251207-37e501b18

package/src/protocol/ProtocolMocks.ts

@@ -0,0 +1,302 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Message } from "#codec/MessageCodec.js";
+import { Fabric as RealFabric } from "#fabric/Fabric.js";
+import {
+    AsyncObservable,
+    b$,
+    Bytes,
+    Channel,
+    ChannelType,
+    Crypto,
+    DataReadQueue,
+    Environment,
+    ImplementationError,
+    IpNetworkChannel,
+    Lifetime,
+    MAX_UDP_MESSAGE_SIZE,
+    MaybePromise,
+    MockCrypto,
+    Observable,
+    ServerAddressUdp,
+} from "#general";
+import { MessageType } from "#interaction/InteractionMessenger.js";
+import { NodeSession as RealNodeSession } from "#session/NodeSession.js";
+import { Session } from "#session/Session.js";
+import { SessionParameters } from "#session/SessionParameters.js";
+import { FabricId, FabricIndex, NodeId, SECURE_CHANNEL_PROTOCOL_ID, Status, TlvStatusResponse, VendorId } from "#types";
+import { Specification } from "@matter/model";
+import { MessageChannel as RealMessageChannel } from "./MessageChannel.js";
+import { MessageExchange, MessageExchangeContext } from "./MessageExchange.js";
+
+export namespace ProtocolMocks {
+    /**
+     * A fabric that will fill any fields not provided with placeholder values.
+     */
+    export class Fabric extends RealFabric {
+        constructor(config?: Partial<RealFabric.Config>, crypto?: Crypto) {
+            if (!crypto) {
+                crypto = Environment.default.maybeGet(Crypto);
+                if (!(crypto instanceof MockCrypto)) {
+                    crypto = MockCrypto();
+                }
+            }
+
+            const keyPair = config?.keyPair ?? crypto.createKeyPair();
+            if (MaybePromise.is(keyPair)) {
+                throw new ImplementationError("Must provide key pair with async crypto");
+            }
+
+            super(crypto, {
+                ...Fabric.defaults,
+                ...config,
+                keyPair,
+            });
+        }
+    }
+
+    export namespace Fabric {
+        export const defaults: RealFabric.Config = {
+            fabricId: FabricId(0x2906c908d115d362n),
+            fabricIndex: FabricIndex(1),
+            identityProtectionKey: Bytes.empty,
+            intermediateCACert: Bytes.empty,
+            keyPair: { publicKey: Bytes.empty, privateKey: Bytes.empty },
+            label: "test-fabric",
+            nodeId: NodeId(0xcd5544aa7b13ef14n),
+            operationalCert: Bytes.empty,
+            operationalId: Bytes.empty,
+            operationalIdentityProtectionKey: b$`9bc61cd9c62a2df6d64dfcaa9dc472d4`,
+            rootCert: Bytes.empty,
+            rootNodeId: NodeId(1),
+            rootPublicKey: b$`044a9f42b1ca4840d37292bbc7f6a7e11e22200c976fc900dbc98a7a383a641cb8254a2e56d4e295a847943b4e3897c4a773e930277b4d9fbede8a052686bfacfa`,
+            rootVendorId: VendorId(1),
+        };
+    }
+
+    /**
+     * A mock {@link NodeSession} that supports functional tests without full mock networking.
+     */
+    export class NodeSession extends RealNodeSession {
+        constructor(config?: NodeSession.Config) {
+            const index = config?.index ?? 1;
+            const fabricIndex = (config?.fabricIndex ?? 1) as FabricIndex;
+            const crypto = config?.crypto ?? Environment.default.get(Crypto);
+            const fabric = config && "fabric" in config ? config.fabric : new Fabric({ fabricIndex });
+            const maxPayloadSize = config?.maxPayloadSize;
+
+            // Channel is optional so support "channel: undefined" to disable the default channel
+            let channel;
+            if (config && "channel" in config) {
+                channel = config.channel;
+            } else {
+                channel = new NetworkChannel({ index, maxPayloadSize });
+            }
+
+            const fullConfig = {
+                id: index,
+                peerNodeId: NodeId(index),
+                attestationKey: Bytes.empty,
+                caseAuthenticatedTags: [],
+                peerSessionId: index,
+                decryptKey: Bytes.empty,
+                encryptKey: Bytes.empty,
+                isInitiator: true,
+                ...config,
+                crypto,
+                fabric,
+            };
+            delete fullConfig.channel;
+
+            super(fullConfig);
+
+            // Initialize with a mocked message channel
+            this.channel = new MessageChannel({ channel, session: this });
+
+            // ...and mock lifetime
+            this.lifetime = Lifetime.mock;
+        }
+
+        static override async create(config: NodeSession.CreateConfig) {
+            const crypto = config?.crypto ?? config?.manager?.crypto ?? Environment.default.get(Crypto);
+            const index = config?.index ?? 1;
+            return RealNodeSession.create.call(this, {
+                id: index,
+                crypto,
+                peerNodeId: NodeId(0),
+                peerSessionId: index,
+                sharedSecret: Bytes.empty,
+                salt: Bytes.empty,
+                isInitiator: true,
+                isResumption: false,
+                ...config,
+            });
+        }
+    }
+
+    export namespace NodeSession {
+        export type Config = Partial<RealNodeSession.Config> & MockSessionConfig;
+        export type CreateConfig = Partial<RealNodeSession.CreateConfig & MockSessionConfig>;
+    }
+
+    /**
+     * A mock channel that can act as a placeholder without full mock networking.
+     */
+    export class NetworkChannel implements IpNetworkChannel<Bytes> {
+        maxPayloadSize: number;
+        isReliable = true;
+        supportsLargeMessages = false;
+        name = "mock-byte-channel";
+        type = ChannelType.UDP;
+        networkAddress: ServerAddressUdp;
+
+        constructor(config: MockNetworkConfig) {
+            const index = config.index ?? 1;
+            this.maxPayloadSize = config.maxPayloadSize ?? MAX_UDP_MESSAGE_SIZE;
+            this.networkAddress = { type: "udp", ip: `::${index}`, port: 5540 };
+        }
+
+        async send(): Promise<void> {
+            // Currently we just ignore transmissions
+        }
+
+        async close() {}
+    }
+
+    /**
+     * A mock message channel that stores outbound messages for later analysis.
+     */
+    export class MessageChannel extends RealMessageChannel {
+        #requests = new DataReadQueue<Message>();
+        #readReady?: AsyncObservable<[]>;
+
+        constructor(config?: {
+            channel?: Channel<Bytes>;
+            session?: Session;
+            onClose?: () => MaybePromise<void>;
+            index?: number;
+            fabricIndex?: number;
+        }) {
+            const index = config?.index ?? 1;
+            const fabricIndex = config?.fabricIndex ?? 1;
+            const channel = config?.channel ?? new NetworkChannel({ index });
+            const session = config?.session ?? new NodeSession({ index, fabricIndex });
+            super(channel, session, config?.onClose);
+        }
+
+        override async send(message: Message) {
+            this.#requests.write(message);
+            await this.#readReady?.emit();
+        }
+
+        read() {
+            return this.#requests.read();
+        }
+
+        get readReady() {
+            return (this.#readReady ??= new Observable());
+        }
+    }
+
+    /**
+     * A mock message exchange that "transports" messages via internal queues.
+     */
+    export class Exchange extends MessageExchange {
+        #responses = new DataReadQueue<Message>();
+
+        constructor(
+            config?: Omit<Partial<MessageExchange.Config>, "context"> &
+                MockSessionConfig & {
+                    context?: Partial<MessageExchangeContext>;
+                    fabric?: Fabric;
+                },
+        ) {
+            const context = config?.context;
+
+            const index = config?.index ?? 1;
+            const fabricIndex = config?.fabricIndex ?? 1;
+            const maxPayloadSize = config?.maxPayloadSize;
+
+            super({
+                isInitiator: true,
+                exchangeId: index,
+                peerSessionId: index,
+                protocolId: config?.protocolId ?? SECURE_CHANNEL_PROTOCOL_ID,
+
+                ...config,
+
+                context: {
+                    session: context?.session ?? new NodeSession({ index, fabricIndex, maxPayloadSize }),
+                    localSessionParameters: SessionParameters(
+                        context?.localSessionParameters ?? SessionParameters.defaults,
+                    ),
+                    retry() {},
+                },
+            });
+        }
+
+        /**
+         * Enqueue a mock response.
+         */
+        async write(message: Message) {
+            this.#responses.write(message);
+        }
+
+        /**
+         * Enqueue a mock status response.
+         */
+        async writeStatus(status = Status.Success) {
+            await this.write({
+                packetHeader: {
+                    messageId: 123,
+                },
+                payloadHeader: {
+                    messageType: MessageType.StatusResponse,
+                },
+                payload: TlvStatusResponse.encode({
+                    status,
+                    interactionModelRevision: Specification.INTERACTION_MODEL_REVISION,
+                }),
+            } as Message);
+        }
+
+        /**
+         * Wait for a mock request.
+         */
+        read() {
+            return this.#mockChannel.read();
+        }
+
+        /**
+         * Emits when read() won't block.
+         */
+        get readReady() {
+            return this.#mockChannel.readReady;
+        }
+
+        override nextMessage() {
+            return this.#responses.read();
+        }
+
+        get #mockChannel() {
+            const channel = this.channel;
+            if (!(channel instanceof MessageChannel)) {
+                throw new ImplementationError("Message channel is not mocked");
+            }
+            return channel;
+        }
+    }
+
+    export interface MockNetworkConfig {
+        index?: number;
+        maxPayloadSize?: number;
+    }
+
+    export interface MockSessionConfig extends MockNetworkConfig {
+        fabricIndex?: number;
+    }
+}

package/src/protocol/errors.ts

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Message } from "#codec/MessageCodec.js";
+import type { Session } from "#session/Session.js";
+import { Status, StatusResponseError } from "#types";
+import { MatterError, NoResponseTimeoutError } from "@matter/general";
+
+/**
+ * Indicates MRP retries were exhausted without a response from the client.
+ *
+ * TODO - we use this error far too broadly and throw in places that do not involve MRP
+ */
+export class RetransmissionLimitReachedError extends NoResponseTimeoutError {}
+
+/**
+ * Thrown when we receive a message on an exchange that we did not expect.
+ */
+export class UnexpectedMessageError extends MatterError {
+    public constructor(
+        message: string,
+        session: Session,
+        public readonly receivedMessage: Message,
+    ) {
+        super(`(${Message.diagnosticsOf(session, receivedMessage)}) ${message}`);
+    }
+}
+
+/**
+ * Thrown for communication attempts on closed sessions.
+ */
+export class SessionClosedError extends MatterError {}
+
+/**
+ * Thrown for operations that are illegal because a session is not associated with a fabric.
+ */
+export class NoAssociatedFabricError extends StatusResponseError {
+    constructor(message: string) {
+        super(message, Status.UnsupportedAccess);
+    }
+}

package/src/protocol/index.ts

@@ -4,9 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-export * from "./ChannelManager.js";
 export * from "./DeviceAdvertiser.js";
 export * from "./DeviceCommissioner.js";
+export * from "./errors.js";
 export * from "./ExchangeManager.js";
 export * from "./ExchangeProvider.js";
 export * from "./MessageChannel.js";
@@ -14,4 +14,5 @@ export * from "./MessageCounter.js";
 export * from "./MessageExchange.js";
 export * from "./MessageReceptionState.js";
 export * from "./ProtocolHandler.js";
+export * from "./ProtocolMocks.js";
 export * from "./ProtocolStatusMessage.js";

package/src/securechannel/SecureChannelMessenger.ts

@@ -133,6 +133,10 @@ export class SecureChannelMessenger {
         return this.exchange.channel.channel.name;
     }
 
+    [Symbol.asyncDispose]() {
+        return this.close();
+    }
+
     async close() {
         await this.exchange.close();
     }

package/src/securechannel/SecureChannelProtocol.ts

@@ -84,8 +84,8 @@ export class StatusReportOnlySecureChannelProtocol implements ProtocolHandler {
 
         const { session } = exchange;
         NodeSession.assert(session);
-        logger.debug(`Peer requested to close session ${session.name}. Remove session now.`);
-        await session.closeByPeer();
+        logger.debug(exchange.via, "Closed by peer");
+        await session.handlePeerClose();
     }
 
     async close() {

package/src/session/GroupSession.ts

@@ -5,22 +5,29 @@
  */
 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 { FabricManager } from "#fabric/FabricManager.js";
+import { Mark } from "#common/Mark.js";
+import type { Fabric } from "#fabric/Fabric.js";
+import type { FabricManager } from "#fabric/FabricManager.js";
 import {
     Bytes,
+    ChannelType,
+    ConnectionlessTransportSet,
     CryptoDecryptError,
+    Diagnostic,
+    hex,
     ImplementationError,
     InternalError,
     Logger,
     MatterFlowError,
+    STANDARD_MATTER_PORT,
     UnexpectedDataError,
 } from "#general";
+import { PairRetransmissionLimitReachedError } from "#peer/ControllerDiscovery.js";
 import { PeerAddress } from "#peer/PeerAddress.js";
-import type { SessionManager } from "#session/SessionManager.js";
 import { FabricIndex, GroupId, NodeId } from "#types";
 import { SecureSession } from "./SecureSession.js";
 import { Session } from "./Session.js";
+import { SessionManager } from "./SessionManager.js";
 
 const logger = Logger.get("SecureGroupSession");
 
@@ -35,17 +42,10 @@ export class GroupSession extends SecureSession {
 
     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: Bytes; // The Operational Group Key that was used to encrypt the incoming group message.
-    }) {
-        const { manager, fabric, operationalGroupKey, id, peerNodeId, keySetId } = args;
+    constructor(config: GroupSession.Config) {
+        const { manager, fabric, operationalGroupKey, id, peerNodeId, keySetId } = config;
         super({
-            ...args,
+            ...config,
             setActiveTimestamp: false, // We always set the active timestamp for Secure sessions TODO Check
             messageCounter: fabric.groups.messaging.counterFor(operationalGroupKey),
         });
@@ -58,7 +58,47 @@ export class GroupSession extends SecureSession {
         manager?.registerGroupSession(this);
         fabric.addSession(this);
 
-        logger.debug(`Created secure GROUP session for fabric index ${fabric.fabricIndex}`, this.name);
+        logger.debug(this.via, `Created secure GROUP session for fabric index ${fabric.fabricIndex}`);
+    }
+
+    /**
+     * Create an outbound group session.
+     */
+    static async create(options: {
+        manager?: SessionManager;
+        transports: ConnectionlessTransportSet;
+        id: number;
+        fabric: Fabric;
+        keySetId: number;
+        groupNodeId: NodeId;
+        operationalGroupKey: Bytes;
+    }) {
+        const { manager, transports, id, fabric, keySetId, groupNodeId, operationalGroupKey } = options;
+
+        const groupId = GroupId.fromNodeId(groupNodeId);
+        const multicastAddress = fabric.groups.multicastAddressFor(groupId);
+
+        const operationalInterface = transports.interfaceFor(ChannelType.UDP, multicastAddress);
+        if (operationalInterface === undefined) {
+            // TODO - better error class
+            throw new PairRetransmissionLimitReachedError(`IPv6 interface not initialized`);
+        }
+
+        const channel = await operationalInterface.openChannel({
+            type: ChannelType.UDP,
+            ip: multicastAddress,
+            port: STANDARD_MATTER_PORT,
+        });
+
+        return new GroupSession({
+            manager,
+            channel,
+            id,
+            fabric,
+            keySetId,
+            peerNodeId: groupNodeId,
+            operationalGroupKey,
+        });
     }
 
     override get type() {
@@ -77,8 +117,8 @@ export class GroupSession extends SecureSession {
         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 via() {
+        return Diagnostic.via(`${Mark.SESSION}group#${hex.word(this.id)}`);
     }
 
     get nodeId() {
@@ -215,20 +255,24 @@ export class GroupSession extends SecureSession {
         return { message, key, sessionId, sourceNodeId, keySetId, fabric };
     }
 
-    async destroy() {
-        logger.info(`End group session ${this.name}`);
+    override async close() {
         this.manager?.removeGroupSession(this);
-    }
-
-    end() {
-        return this.destroy();
+        await super.close();
     }
 }
 
 export namespace GroupSession {
+    export interface Config extends Session.CommonConfig {
+        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: Bytes; // The Operational Group Key that was used to encrypt the incoming group message.
+    }
+
     export function assert(session?: Session, errorText?: string): asserts session is GroupSession {
         if (!is(session)) {
-            throw new MatterFlowError(errorText ?? "Insecure session in secure context");
+            throw new MatterFlowError(errorText ?? "Unsecured session in secure context");
         }
     }