@matter/protocol 0.15.0-alpha.0-20250620-16e218ed3 → 0.15.0-alpha.0-20250625-4a4b1be1b

package/src/protocol/ProtocolStatusMessage.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { DataReader, DataWriter, Endian } from "#general";
+import { GeneralStatusCode, Schema } from "#types";
+
+export type ProtocolStatusMessage<T> = {
+    generalStatus: GeneralStatusCode;
+    protocolId: number;
+    protocolStatus: T;
+    protocolData?: Uint8Array;
+};
+
+export abstract class ProtocolStatusMessageSchema<T extends ProtocolStatusMessage<any>> extends Schema<T, Uint8Array> {
+    #protocolId: number;
+    #protocolSpecificDataAllowed: boolean;
+
+    constructor(protocolId: number, protocolSpecificDataAllowed = true) {
+        super();
+        this.#protocolId = protocolId;
+        this.#protocolSpecificDataAllowed = protocolSpecificDataAllowed;
+    }
+
+    override encode(message: Omit<T, "protocolId">): Uint8Array {
+        return super.encode({ ...message, protocolId: this.#protocolId } as T);
+    }
+
+    encodeInternal({ generalStatus, protocolStatus, protocolId, protocolData }: T) {
+        const writer = new DataWriter(Endian.Little);
+        writer.writeUInt16(generalStatus);
+        writer.writeUInt32(protocolId);
+        writer.writeUInt16(protocolStatus);
+        if (this.#protocolSpecificDataAllowed && protocolData !== undefined && protocolData.length > 0) {
+            writer.writeByteArray(protocolData);
+        }
+        return writer.toByteArray();
+    }
+
+    decodeInternal(bytes: Uint8Array) {
+        const reader = new DataReader(bytes, Endian.Little);
+        const generalStatus = reader.readUInt16();
+        const protocolId = reader.readUInt32();
+        const protocolStatus = reader.readUInt16();
+        const remainingBytes = reader.remainingBytesCount > 0 ? reader.remainingBytes : undefined;
+
+        return { generalStatus, protocolId, protocolStatus, remainingBytes } as unknown as T;
+    }
+}

package/src/protocol/index.ts

@@ -13,3 +13,4 @@ export * from "./MessageCounter.js";
 export * from "./MessageExchange.js";
 export * from "./MessageReceptionState.js";
 export * from "./ProtocolHandler.js";
+export * from "./ProtocolStatusMessage.js";

package/src/securechannel/SecureChannelMessenger.ts

@@ -5,13 +5,7 @@
  */
 
 import { Diagnostic, MatterError, UnexpectedDataError } from "#general";
-import {
-    GeneralStatusCode,
-    ProtocolStatusCode,
-    SECURE_CHANNEL_PROTOCOL_ID,
-    SecureMessageType,
-    TlvSchema,
-} from "#types";
+import { GeneralStatusCode, SecureChannelStatusCode, SecureMessageType, TlvSchema } from "#types";
 import { Message } from "../codec/MessageCodec.js";
 import { ExchangeSendOptions, MessageExchange } from "../protocol/MessageExchange.js";
 import { TlvSecureChannelStatusMessage } from "./SecureChannelStatusMessageSchema.js";
@@ -21,10 +15,10 @@ export class ChannelStatusResponseError extends MatterError {
     public constructor(
         message: string,
         public readonly generalStatusCode: GeneralStatusCode,
-        public readonly protocolStatusCode: ProtocolStatusCode,
+        public readonly protocolStatusCode: SecureChannelStatusCode,
     ) {
         super(
-            `(${GeneralStatusCode[generalStatusCode]} (${generalStatusCode}) / ${ProtocolStatusCode[protocolStatusCode]} (${protocolStatusCode})) ${message}`,
+            `(${GeneralStatusCode[generalStatusCode]} (${generalStatusCode}) / ${SecureChannelStatusCode[protocolStatusCode]} (${protocolStatusCode})) ${message}`,
         );
     }
 }
@@ -125,16 +119,16 @@ export class SecureChannelMessenger {
         return payload;
     }
 
-    sendError(code: ProtocolStatusCode) {
-        return this.sendStatusReport(GeneralStatusCode.Failure, code);
+    sendError(code: SecureChannelStatusCode) {
+        return this.#sendStatusReport(GeneralStatusCode.Failure, code);
     }
 
     sendSuccess() {
-        return this.sendStatusReport(GeneralStatusCode.Success, ProtocolStatusCode.Success);
+        return this.#sendStatusReport(GeneralStatusCode.Success, SecureChannelStatusCode.Success);
     }
 
     sendCloseSession() {
-        return this.sendStatusReport(GeneralStatusCode.Success, ProtocolStatusCode.CloseSession, false);
+        return this.#sendStatusReport(GeneralStatusCode.Success, SecureChannelStatusCode.CloseSession, false);
     }
 
     getChannelName() {
@@ -145,23 +139,22 @@ export class SecureChannelMessenger {
         await this.exchange.close();
     }
 
-    private async sendStatusReport(
+    async #sendStatusReport(
         generalStatus: GeneralStatusCode,
-        protocolStatus: ProtocolStatusCode,
+        protocolStatus: SecureChannelStatusCode,
         requiresAck?: boolean,
     ) {
         await this.exchange.send(
             SecureMessageType.StatusReport,
             TlvSecureChannelStatusMessage.encode({
                 generalStatus,
-                protocolId: SECURE_CHANNEL_PROTOCOL_ID,
                 protocolStatus,
             }),
             {
                 requiresAck,
                 logContext: {
                     generalStatus: GeneralStatusCode[generalStatus] ?? Diagnostic.hex(generalStatus),
-                    protocolStatus: ProtocolStatusCode[protocolStatus] ?? Diagnostic.hex(protocolStatus),
+                    protocolStatus: SecureChannelStatusCode[protocolStatus] ?? Diagnostic.hex(protocolStatus),
                 },
             },
         );
@@ -182,7 +175,7 @@ export class SecureChannelMessenger {
                 protocolStatus,
             );
         }
-        if (protocolStatus !== ProtocolStatusCode.Success) {
+        if (protocolStatus !== SecureChannelStatusCode.Success) {
             throw new ChannelStatusResponseError(
                 `Received general success status, but protocol status is not Success${logHint ? ` (${logHint})` : ""}`,
                 generalStatus,

package/src/securechannel/SecureChannelProtocol.ts

@@ -10,8 +10,8 @@ import { ExchangeManager } from "#protocol/ExchangeManager.js";
 import { SessionManager } from "#session/SessionManager.js";
 import {
     GeneralStatusCode,
-    ProtocolStatusCode,
     SECURE_CHANNEL_PROTOCOL_ID,
+    SecureChannelStatusCode,
     SecureMessageType,
     StatusCode,
     StatusResponseError,
@@ -70,7 +70,7 @@ export class StatusReportOnlySecureChannelProtocol implements ProtocolHandler {
                 protocolStatus,
             );
         }
-        if (protocolStatus !== ProtocolStatusCode.CloseSession) {
+        if (protocolStatus !== SecureChannelStatusCode.CloseSession) {
             throw new ChannelStatusResponseError(
                 `Received general success status, but protocol status is not CloseSession`,
                 generalStatus,
@@ -131,7 +131,7 @@ export class SecureChannelProtocol extends StatusReportOnlySecureChannelProtocol
                     // Cleaner to return an error (ok for chip-tool as it seems)?
                     // Formally we should not respond at all which leads to retries and such
                     const messenger = new SecureChannelMessenger(exchange);
-                    await messenger.sendError(ProtocolStatusCode.InvalidParam);
+                    await messenger.sendError(SecureChannelStatusCode.InvalidParam);
                     await messenger.close(); // also closes exchange
                     return;
                 }

package/src/securechannel/SecureChannelStatusMessageSchema.ts

@@ -4,37 +4,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { DataReader, DataWriter, Endian } from "#general";
-import { GeneralStatusCode, ProtocolStatusCode, Schema } from "#types";
+import { ProtocolStatusMessage, ProtocolStatusMessageSchema } from "#protocol/ProtocolStatusMessage.js";
+import { SECURE_CHANNEL_PROTOCOL_ID, SecureChannelStatusCode } from "#types";
 
-export type StatusMessage = {
-    generalStatus: GeneralStatusCode;
-    protocolId: number;
-    protocolStatus: ProtocolStatusCode;
-    protocolData?: Uint8Array;
-};
+export type SecureChannelStatusMessage = ProtocolStatusMessage<SecureChannelStatusCode>;
 
-export class SecureChannelStatusMessageSchema extends Schema<StatusMessage, Uint8Array> {
-    encodeInternal({ generalStatus, protocolId, protocolStatus, protocolData }: StatusMessage) {
-        const writer = new DataWriter(Endian.Little);
-        writer.writeUInt16(generalStatus);
-        writer.writeUInt32(protocolId);
-        writer.writeUInt16(protocolStatus);
-        if (protocolData !== undefined && protocolData.length > 0) {
-            writer.writeByteArray(protocolData);
-        }
-        return writer.toByteArray();
-    }
+export class SecureChannelStatusMessageSchema extends ProtocolStatusMessageSchema<SecureChannelStatusMessage> {}
 
-    decodeInternal(bytes: Uint8Array) {
-        const reader = new DataReader(bytes, Endian.Little);
-        const generalStatus = reader.readUInt16();
-        const protocolId = reader.readUInt32();
-        const protocolStatus = reader.readUInt16();
-        const remainingBytes = reader.remainingBytesCount > 0 ? reader.remainingBytes : undefined;
-
-        return { generalStatus, protocolId, protocolStatus, remainingBytes };
-    }
-}
-
-export const TlvSecureChannelStatusMessage = new SecureChannelStatusMessageSchema();
+export const TlvSecureChannelStatusMessage = new SecureChannelStatusMessageSchema(SECURE_CHANNEL_PROTOCOL_ID);

package/src/session/case/CaseClient.ts

@@ -8,7 +8,7 @@ import { Icac, Noc } from "#certificate/index.js";
 import { Bytes, Logger, PublicKey, UnexpectedDataError } from "#general";
 import { ChannelStatusResponseError } from "#securechannel/index.js";
 import { SessionManager } from "#session/SessionManager.js";
-import { NodeId, ProtocolStatusCode } from "#types";
+import { NodeId, SecureChannelStatusCode } from "#types";
 import { Fabric } from "../../fabric/Fabric.js";
 import { MessageExchange } from "../../protocol/MessageExchange.js";
 import {
@@ -42,7 +42,7 @@ export class CaseClient {
             return await this.#doPair(messenger, exchange, fabric, peerNodeId);
         } catch (error) {
             if (!(error instanceof ChannelStatusResponseError)) {
-                await messenger.sendError(ProtocolStatusCode.InvalidParam);
+                await messenger.sendError(SecureChannelStatusCode.InvalidParam);
             }
             throw error;
         }

package/src/session/case/CaseServer.ts

@@ -8,7 +8,7 @@ import { Noc } from "#certificate/index.js";
 import { Bytes, Crypto, CryptoDecryptError, Logger, PublicKey, UnexpectedDataError } from "#general";
 import { TlvSessionParameters } from "#session/pase/PaseMessages.js";
 import { ResumptionRecord, SessionManager } from "#session/SessionManager.js";
-import { NodeId, ProtocolStatusCode, SECURE_CHANNEL_PROTOCOL_ID, TypeFromSchema } from "#types";
+import { NodeId, SECURE_CHANNEL_PROTOCOL_ID, SecureChannelStatusCode, TypeFromSchema } from "#types";
 import { FabricManager, FabricNotFoundError } from "../../fabric/FabricManager.js";
 import { MessageExchange } from "../../protocol/MessageExchange.js";
 import { ProtocolHandler } from "../../protocol/ProtocolHandler.js";
@@ -51,11 +51,11 @@ export class CaseServer implements ProtocolHandler {
             logger.error("An error occurred during the commissioning", error);
 
             if (error instanceof FabricNotFoundError) {
-                await messenger.sendError(ProtocolStatusCode.NoSharedTrustRoots);
+                await messenger.sendError(SecureChannelStatusCode.NoSharedTrustRoots);
             }
             // If we received a ChannelStatusResponseError we do not need to send one back, so just cancel pairing
             else if (!(error instanceof ChannelStatusResponseError)) {
-                await messenger.sendError(ProtocolStatusCode.InvalidParam);
+                await messenger.sendError(SecureChannelStatusCode.InvalidParam);
             }
         } finally {
             // Destroy the unsecure session used to establish the secure Case session

package/src/session/pase/PaseClient.ts

@@ -6,7 +6,7 @@
 
 import { Bytes, Crypto, ec, Logger, PbkdfParameters, Spake2p, UnexpectedDataError } from "#general";
 import { SessionManager } from "#session/SessionManager.js";
-import { CommissioningOptions, NodeId, ProtocolStatusCode } from "#types";
+import { CommissioningOptions, NodeId, SecureChannelStatusCode } from "#types";
 import { MessageExchange } from "../../protocol/MessageExchange.js";
 import { SessionParameters } from "../Session.js";
 import { DEFAULT_PASSCODE_ID, PaseClientMessenger, SPAKE_CONTEXT } from "./PaseMessenger.js";
@@ -70,7 +70,7 @@ export class PaseClient {
         if (pbkdfParameters === undefined) {
             // Sending this error is not defined in the specs and should normally never happen, but better inform device
             // that we cancel the pairing
-            await messenger.sendError(ProtocolStatusCode.InvalidParam);
+            await messenger.sendError(SecureChannelStatusCode.InvalidParam);
             throw new UnexpectedDataError("Missing requested PbkdfParameters in the response. Commissioning failed.");
         }
 
@@ -94,7 +94,7 @@ export class PaseClient {
         const { y: Y, verifier } = await messenger.readPasePake2();
         const { Ke, hAY, hBX } = await spake2p.computeSecretAndVerifiersFromY(w1, X, Y);
         if (!Bytes.areEqual(verifier, hBX)) {
-            await messenger.sendError(ProtocolStatusCode.InvalidParam);
+            await messenger.sendError(SecureChannelStatusCode.InvalidParam);
             throw new UnexpectedDataError(
                 "Received incorrect key confirmation from the receiver. Commissioning failed.",
             );

package/src/session/pase/PaseServer.ts

@@ -17,7 +17,7 @@ import {
     UnexpectedDataError,
 } from "#general";
 import { SessionManager } from "#session/SessionManager.js";
-import { NodeId, ProtocolStatusCode, SECURE_CHANNEL_PROTOCOL_ID } from "#types";
+import { NodeId, SECURE_CHANNEL_PROTOCOL_ID, SecureChannelStatusCode } from "#types";
 import { MessageExchange } from "../../protocol/MessageExchange.js";
 import { ProtocolHandler } from "../../protocol/ProtocolHandler.js";
 import { ChannelStatusResponseError } from "../../securechannel/SecureChannelMessenger.js";
@@ -186,7 +186,7 @@ export class PaseServer implements ProtocolHandler {
         this.#pairingTimer = undefined;
 
         if (sendError) {
-            await messenger.sendError(ProtocolStatusCode.InvalidParam);
+            await messenger.sendError(SecureChannelStatusCode.InvalidParam);
         }
         await messenger.close();
     }