@matter/protocol 0.16.0-alpha.0-20250812-285b75d83 → 0.16.0-alpha.0-20250815-ac9fd6eb0

package/src/protocol/MessageExchange.ts

@@ -7,6 +7,7 @@
 import { Message, MessageCodec, PacketHeader, SessionType } from "#codec/MessageCodec.js";
 import {
     AsyncObservable,
+    Bytes,
     createPromise,
     CRYPTO_AEAD_MIC_LENGTH_BYTES,
     DataReadQueue,
@@ -344,7 +345,7 @@ export class MessageExchange {
         await this.#messagesQueue.write(message);
     }
 
-    async send(messageType: number, payload: Uint8Array, options?: ExchangeSendOptions) {
+    async send(messageType: number, payload: Bytes, options?: ExchangeSendOptions) {
         if (options?.requiresAck && !this.channel.usesMrp) {
             options.requiresAck = false;
         }

package/src/protocol/ProtocolStatusMessage.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { DataReader, DataWriter, Endian } from "#general";
+import { Bytes, DataReader, DataWriter, Endian } from "#general";
 import { GeneralStatusCode, Schema, VendorId } from "#types";
 
 export type ProtocolStatusMessage<T> = {
@@ -12,10 +12,10 @@ export type ProtocolStatusMessage<T> = {
     protocolId: number;
     vendorId: VendorId;
     protocolStatus: T;
-    protocolData?: Uint8Array;
+    protocolData?: Bytes;
 };
 
-export abstract class ProtocolStatusMessageSchema<T extends ProtocolStatusMessage<any>> extends Schema<T, Uint8Array> {
+export abstract class ProtocolStatusMessageSchema<T extends ProtocolStatusMessage<any>> extends Schema<T, Bytes> {
     #protocolId: number;
     #vendorId: number;
     #protocolSpecificDataAllowed: boolean;
@@ -32,7 +32,7 @@ export abstract class ProtocolStatusMessageSchema<T extends ProtocolStatusMessag
         this.#protocolSpecificDataAllowed = protocolSpecificDataAllowed;
     }
 
-    override encode(message: Omit<T, "protocolId" | "vendorId">): Uint8Array {
+    override encode(message: Omit<T, "protocolId" | "vendorId">): Bytes {
         return super.encode({ ...message, protocolId: this.#protocolId, vendorId: this.#vendorId } as T);
     }
 
@@ -41,13 +41,13 @@ export abstract class ProtocolStatusMessageSchema<T extends ProtocolStatusMessag
         writer.writeUInt16(generalStatus);
         writer.writeUInt32((vendorId << 16) | protocolId);
         writer.writeUInt16(protocolStatus);
-        if (this.#protocolSpecificDataAllowed && protocolData !== undefined && protocolData.length > 0) {
+        if (this.#protocolSpecificDataAllowed && protocolData !== undefined && protocolData.byteLength > 0) {
             writer.writeByteArray(protocolData);
         }
         return writer.toByteArray();
     }
 
-    decodeInternal(bytes: Uint8Array) {
+    decodeInternal(bytes: Bytes) {
         const reader = new DataReader(bytes, Endian.Little);
         const generalStatus = reader.readUInt16();
         const vendorProtocolId = reader.readUInt32();

package/src/session/GroupSession.ts

@@ -28,7 +28,7 @@ export class GroupSession extends SecureSession {
     readonly #id: number;
     readonly #fabric: Fabric;
     readonly #peerNodeId: NodeId;
-    readonly #operationalGroupKey: Uint8Array;
+    readonly #operationalGroupKey: Bytes;
     readonly supportsMRP = false;
     readonly closingAfterExchangeFinished = false; // Group sessions do not close after exchange finished, they are long-lived
 
@@ -40,7 +40,7 @@ export class GroupSession extends SecureSession {
         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.
+        operationalGroupKey: Bytes; // The Operational Group Key that was used to encrypt the incoming group message.
     }) {
         const { manager, fabric, operationalGroupKey, id, peerNodeId, keySetId } = args;
         super({
@@ -103,7 +103,7 @@ export class GroupSession extends SecureSession {
         // Group sessions do not have a specific activity notification, so we do nothing here
     }
 
-    override updateMessageCounter(messageCounter: number, sourceNodeId: NodeId, operationalKey: Uint8Array) {
+    override updateMessageCounter(messageCounter: number, sourceNodeId: NodeId, operationalKey: Bytes) {
         if (sourceNodeId === undefined || operationalKey === undefined) {
             throw new InternalError("Source Node ID is required for GroupSession updateMessageCounter.");
         }
@@ -141,10 +141,10 @@ export class GroupSession extends SecureSession {
     static decode(
         fabrics: FabricManager,
         { header, applicationPayload, messageExtension }: DecodedPacket,
-        aad: Uint8Array,
+        aad: Bytes,
     ): {
         message: DecodedMessage;
-        key: Uint8Array;
+        key: Bytes;
         sessionId: number;
         sourceNodeId: NodeId;
         keySetId: number;
@@ -162,7 +162,7 @@ export class GroupSession extends SecureSession {
         }
         const nonce = Session.generateNonce(header.securityFlags, header.messageId, sourceNodeId);
         const sessionId = header.sessionId;
-        const keys = new Array<{ key: Uint8Array; keySetId: number; fabric: Fabric }>();
+        const keys = new Array<{ key: Bytes; keySetId: number; fabric: Fabric }>();
         for (const fabric of fabrics) {
             const sessions = fabric.groups.sessions.get(sessionId);
             if (sessions?.length) {
@@ -175,7 +175,7 @@ export class GroupSession extends SecureSession {
             throw new MatterFlowError("No key candidate found for group session decryption.");
         }
         let message: DecodedMessage | undefined;
-        let key: Uint8Array | undefined;
+        let key: Bytes | undefined;
         let fabric: Fabric | undefined;
         let keySetId: number | undefined;
         let found = false;

package/src/session/InsecureSession.ts

@@ -57,7 +57,7 @@ export class InsecureSession extends Session {
         return MessageCodec.encodePayload(message);
     }
 
-    get attestationChallengeKey(): Uint8Array {
+    get attestationChallengeKey(): BufferSource {
         throw new MatterFlowError("Not supported on an unsecure session");
     }
 

package/src/session/NodeSession.ts

@@ -49,9 +49,9 @@ export class NodeSession extends SecureSession {
     #fabric: Fabric | undefined;
     readonly #peerNodeId: NodeId;
     readonly #peerSessionId: number;
-    readonly #decryptKey: Uint8Array;
-    readonly #encryptKey: Uint8Array;
-    readonly #attestationKey: Uint8Array;
+    readonly #decryptKey: Bytes;
+    readonly #encryptKey: Bytes;
+    readonly #attestationKey: Bytes;
     #caseAuthenticatedTags: CaseAuthenticatedTag[];
     #isClosing = false;
     readonly supportsMRP = true;
@@ -64,8 +64,8 @@ export class NodeSession extends SecureSession {
         fabric: Fabric | undefined;
         peerNodeId: NodeId;
         peerSessionId: number;
-        sharedSecret: Uint8Array;
-        salt: Uint8Array;
+        sharedSecret: Bytes;
+        salt: Bytes;
         isInitiator: boolean;
         isResumption: boolean;
         peerSessionParameters?: SessionParameterOptions;
@@ -85,11 +85,13 @@ export class NodeSession extends SecureSession {
             peerSessionParameters,
             caseAuthenticatedTags,
         } = args;
-        const keys = await args.crypto.createHkdfKey(
-            sharedSecret,
-            salt,
-            isResumption ? SESSION_RESUMPTION_KEYS_INFO : SESSION_KEYS_INFO,
-            CRYPTO_SYMMETRIC_KEY_LENGTH * 3,
+        const keys = Bytes.of(
+            await args.crypto.createHkdfKey(
+                sharedSecret,
+                salt,
+                isResumption ? SESSION_RESUMPTION_KEYS_INFO : SESSION_KEYS_INFO,
+                CRYPTO_SYMMETRIC_KEY_LENGTH * 3,
+            ),
         );
         const decryptKey = isInitiator ? keys.slice(16, 32) : keys.slice(0, 16);
         const encryptKey = isInitiator ? keys.slice(0, 16) : keys.slice(16, 32);
@@ -117,9 +119,9 @@ export class NodeSession extends SecureSession {
         fabric: Fabric | undefined;
         peerNodeId: NodeId;
         peerSessionId: number;
-        decryptKey: Uint8Array;
-        encryptKey: Uint8Array;
-        attestationKey: Uint8Array;
+        decryptKey: Bytes;
+        encryptKey: Bytes;
+        attestationKey: Bytes;
         sessionParameters?: SessionParameterOptions;
         caseAuthenticatedTags?: CaseAuthenticatedTag[];
         isInitiator: boolean;
@@ -229,7 +231,7 @@ export class NodeSession extends SecureSession {
         await this.end(true, closeAfterExchangeFinished);
     }
 
-    decode({ header, applicationPayload, messageExtension }: DecodedPacket, aad: Uint8Array): DecodedMessage {
+    decode({ header, applicationPayload, messageExtension }: DecodedPacket, aad: Bytes): DecodedMessage {
         if (header.hasMessageExtensions) {
             logger.info(
                 `Message extensions are not supported. Ignoring ${messageExtension ? Bytes.toHex(messageExtension) : undefined}`,
@@ -265,7 +267,7 @@ export class NodeSession extends SecureSession {
         };
     }
 
-    get attestationChallengeKey(): Uint8Array {
+    get attestationChallengeKey(): Bytes {
         return this.#attestationKey;
     }
 

package/src/session/Session.ts

@@ -5,7 +5,7 @@
  */
 
 import { SupportedTransportsBitmap } from "#common/SupportedTransportsBitmap.js";
-import { AsyncObservable, DataWriter, Endian, InternalError, Time } from "#general";
+import { AsyncObservable, Bytes, DataWriter, Endian, InternalError, Time } from "#general";
 import { NodeId, TypeFromPartialBitSchema } from "#types";
 import { DecodedMessage, DecodedPacket, Message, Packet, SessionType } from "../codec/MessageCodec.js";
 import { Fabric } from "../fabric/Fabric.js";
@@ -149,7 +149,7 @@ export abstract class Session {
         return this.messageCounter.getIncrementedCounter();
     }
 
-    updateMessageCounter(messageCounter: number, _sourceNodeId?: NodeId, _operationalKey?: Uint8Array) {
+    updateMessageCounter(messageCounter: number, _sourceNodeId?: NodeId, _operationalKey?: Bytes) {
         if (this.messageReceptionState === undefined) {
             throw new InternalError("MessageReceptionState is not defined for this session");
         }
@@ -200,7 +200,7 @@ export abstract class Session {
     abstract associatedFabric: Fabric;
     abstract supportsMRP: boolean; // TODO: always false for Group Sessions
 
-    abstract decode(packet: DecodedPacket, aad?: Uint8Array): DecodedMessage;
+    abstract decode(packet: DecodedPacket, aad?: Bytes): DecodedMessage;
     abstract encode(message: Message): Packet;
     abstract end(sendClose: boolean): Promise<void>;
     abstract destroy(sendClose?: boolean, closeAfterExchangeFinished?: boolean): Promise<void>;

package/src/session/SessionManager.ts

@@ -59,8 +59,8 @@ const DEFAULT_SESSION_PARAMETERS = {
 };
 
 export interface ResumptionRecord {
-    sharedSecret: Uint8Array;
-    resumptionId: Uint8Array;
+    sharedSecret: Bytes;
+    resumptionId: Bytes;
     fabric: Fabric;
     peerNodeId: NodeId;
     sessionParameters: SessionParameters;
@@ -69,8 +69,8 @@ export interface ResumptionRecord {
 
 type ResumptionStorageRecord = {
     nodeId: NodeId;
-    sharedSecret: Uint8Array;
-    resumptionId: Uint8Array;
+    sharedSecret: Bytes;
+    resumptionId: Bytes;
     fabricId: FabricId;
     peerNodeId: NodeId;
     sessionParameters: {
@@ -265,8 +265,8 @@ export class SessionManager {
         fabric: Fabric | undefined;
         peerNodeId: NodeId;
         peerSessionId: number;
-        sharedSecret: Uint8Array;
-        salt: Uint8Array;
+        sharedSecret: Bytes;
+        salt: Bytes;
         isInitiator: boolean;
         isResumption: boolean;
         peerSessionParameters?: SessionParameterOptions;
@@ -408,8 +408,7 @@ export class SessionManager {
         //TODO: It can have multiple sessions for one node ...
         return [...this.#sessions].find(session => {
             if (!session.isSecure) return false;
-            const secureSession = session;
-            return secureSession.peerIs(address);
+            return session.peerIs(address);
         });
     }
 
@@ -471,7 +470,7 @@ export class SessionManager {
      * Creates or Returns the Group session based on an incoming packet.
      * The Session ID is determined by trying to decrypt te packet with possible keys.
      */
-    groupSessionFromPacket(packet: DecodedPacket, aad: Uint8Array) {
+    groupSessionFromPacket(packet: DecodedPacket, aad: Bytes) {
         const groupId = packet.header.destGroupId;
         if (groupId === undefined) {
             throw new UnexpectedDataError("Group ID is required for GroupSession fromPacket.");
@@ -517,7 +516,7 @@ export class SessionManager {
         }
     }
 
-    findResumptionRecordById(resumptionId: Uint8Array) {
+    findResumptionRecordById(resumptionId: Bytes) {
         this.#construction.assert();
         return [...this.#resumptionRecords.values()].find(record => Bytes.areEqual(record.resumptionId, resumptionId));
     }

package/src/session/case/CaseServer.ts

@@ -305,22 +305,22 @@ export class CaseServer implements ProtocolHandler {
 class Sigma1Context {
     crypto: Crypto;
     messenger: CaseServerMessenger;
-    bytes: Uint8Array;
+    bytes: Bytes;
     peerSessionId: number;
-    peerResumptionId?: Uint8Array;
-    peerResumeMic?: Uint8Array;
-    destinationId: Uint8Array;
-    peerRandom: Uint8Array;
-    peerEcdhPublicKey: Uint8Array;
+    peerResumptionId?: Bytes;
+    peerResumeMic?: Bytes;
+    destinationId: Bytes;
+    peerRandom: Bytes;
+    peerEcdhPublicKey: Bytes;
     peerSessionParams?: TypeFromSchema<typeof TlvSessionParameters>;
     resumptionRecord?: ResumptionRecord;
 
-    #localResumptionId?: Uint8Array;
+    #localResumptionId?: Bytes;
 
     constructor(
         crypto: Crypto,
         messenger: CaseServerMessenger,
-        bytes: Uint8Array,
+        bytes: Bytes,
         sigma1: TypeFromSchema<typeof TlvCaseSigma1>,
         resumptionRecord?: ResumptionRecord,
     ) {

package/src/session/pase/PaseServer.ts

@@ -46,18 +46,19 @@ export class PaseServer implements ProtocolHandler {
 
     static fromVerificationValue(
         sessions: SessionManager,
-        verificationValue: Uint8Array,
+        verificationValue: Bytes,
         pbkdfParameters?: PbkdfParameters,
     ) {
-        const w0 = bytesToNumberBE(verificationValue.slice(0, 32));
-        const L = verificationValue.slice(32, 32 + 65);
+        const verificationData = Bytes.of(verificationValue);
+        const w0 = bytesToNumberBE(verificationData.slice(0, 32));
+        const L = verificationData.slice(32, 32 + 65);
         return new PaseServer(sessions, w0, L, pbkdfParameters);
     }
 
     constructor(
         private sessions: SessionManager,
         private readonly w0: bigint,
-        private readonly L: Uint8Array,
+        private readonly L: Bytes,
         private readonly pbkdfParameters?: PbkdfParameters,
     ) {}