@matter/thread-br-client 0.0.1 → 0.17.5-alpha.0-20260706-fd4c49e2e

package/src/dtls/handshake/DtlsClient.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { ImplementationError, InternalError } from "@matter/general";
+import { Bytes, Crypto, ImplementationError, InternalError } from "@matter/general";
 import { DtlsError } from "../channel/DtlsChannel.js";
 import { EcJpakePms } from "../ecjpake/EcJpakePms.js";
 import { ECJPAKE_ID_CLIENT, ECJPAKE_ID_SERVER, EcJpakeRound } from "../ecjpake/EcJpakeRound.js";
@@ -52,10 +52,12 @@ export type DtlsClientState =
     | "failed";
 
 export interface DtlsClientConfig {
+    /** Crypto backend threaded through record codec, EC-JPAKE, PRF and transcript. */
+    crypto: Crypto;
     /** EC-JPAKE password (PSKc bytes for Thread). Hashed by mbedTLS as the integer of these bytes. */
-    password: Uint8Array;
+    password: Bytes;
     /** Returns 32 bytes for `ClientHello.random`. Production: CSPRNG. */
-    random: () => Uint8Array;
+    random: () => Bytes;
     /**
      * Returns a fresh scalar in [1, n-1]. Called five times per attempt:
      * x1, x2 (round-1 private keys), v1, v2 (round-1 ZKP ephemerals), v3 (round-2 ZKP ephemeral).
@@ -71,7 +73,7 @@ export interface DtlsClientConfig {
 
 export interface DtlsClientStep {
     /** Records to emit on the wire (already framed as DTLS records). */
-    records: Uint8Array[];
+    records: Bytes[];
 }
 
 const RANDOM_LEN = 32;
@@ -85,14 +87,14 @@ interface InboundRecord {
 
 interface InboundHandshake {
     msgType: HandshakeType;
-    body: Uint8Array;
+    body: Bytes;
     /** TLS-form bytes for transcript hashing. */
-    transcriptBytes: Uint8Array;
+    transcriptBytes: Bytes;
 }
 
-function bigintFromBE(bytes: Uint8Array): bigint {
+function bigintFromBE(bytes: Bytes): bigint {
     let v = 0n;
-    for (const byte of bytes) {
+    for (const byte of Bytes.of(bytes)) {
         v = (v << 8n) | BigInt(byte);
     }
     return v;
@@ -100,31 +102,34 @@ function bigintFromBE(bytes: Uint8Array): bigint {
 
 export class DtlsClient {
     readonly #config: DtlsClientConfig;
+    readonly #crypto: Crypto;
 
     #state: DtlsClientState = "initial";
-    #transcript = new HandshakeTranscript();
+    #transcript: HandshakeTranscript;
     #handshakeMessageSeq = 0;
     #recordSeq = 0n;
     #lastFlight = new Array<Uint8Array>();
 
     #x2!: bigint;
-    #X1!: Uint8Array;
-    #X2!: Uint8Array;
+    #X1!: Bytes;
+    #X2!: Bytes;
     /** Round-1 wire bytes — bytes-identical across cookie-exchange retries (mbedTLS `ecjpake_cache`). */
-    #round1Bytes!: Uint8Array;
+    #round1Bytes!: Bytes;
 
     /** 32-byte ClientHello.random — bytes-identical across cookie retries. */
-    #clientRandom!: Uint8Array;
+    #clientRandom!: Bytes;
 
-    #X3?: Uint8Array;
-    #X4?: Uint8Array;
-    #serverRandom?: Uint8Array;
+    #X3?: Bytes;
+    #X4?: Bytes;
+    #serverRandom?: Bytes;
 
     #masterSecret?: Uint8Array;
     #cipherState?: DtlsCipherState;
 
     constructor(config: DtlsClientConfig) {
         this.#config = config;
+        this.#crypto = config.crypto;
+        this.#transcript = new HandshakeTranscript(this.#crypto);
     }
 
     state(): DtlsClientState {
@@ -145,11 +150,11 @@ export class DtlsClient {
     }
 
     /** Initial flight: ClientHello with empty cookie. */
-    start(): DtlsClientStep {
+    async start(): Promise<DtlsClientStep> {
         if (this.#state !== "initial") {
             throw new ImplementationError(`DtlsClient.start() called in state '${this.#state}'`);
         }
-        const random = this.#config.random();
+        const random = Bytes.of(this.#config.random());
         if (random.length !== RANDOM_LEN) {
             throw new ImplementationError(
                 `DtlsClient config.random() returned ${random.length} bytes, need ${RANDOM_LEN}`,
@@ -160,41 +165,42 @@ export class DtlsClient {
         const x2 = this.#config.ephemeralScalar();
         const v1 = this.#config.ephemeralScalar();
         const v2 = this.#config.ephemeralScalar();
-        const round1 = EcJpakeRound.buildRound1({ x1, x2, v1, v2, id: ECJPAKE_ID_CLIENT });
+        const round1 = await EcJpakeRound.buildRound1(this.#crypto, { x1, x2, v1, v2, id: ECJPAKE_ID_CLIENT });
         this.#x2 = x2;
         this.#X1 = round1.kp1.X;
         this.#X2 = round1.kp2.X;
         this.#round1Bytes = EcJpakeRound.serializeRound1(round1.kp1, round1.kp2);
 
-        const records = this.#emitClientHello(new Uint8Array(0), false);
+        const records = await this.#emitClientHello(new Uint8Array(0), false);
         this.#state = "sent_first_clienthello";
         return { records };
     }
 
     /** Re-emit the last flight bytes-identically (RFC 6347 §4.2.4). */
-    onRetransmit(): DtlsClientStep {
+    async onRetransmit(): Promise<DtlsClientStep> {
         if (this.#state === "initial" || this.#state === "established" || this.#state === "failed") {
             throw new ImplementationError(`DtlsClient.onRetransmit() called in state '${this.#state}'`);
         }
         return { records: this.#lastFlight.map(r => r.slice()) };
     }
 
-    onDatagram(bytes: Uint8Array): DtlsClientStep {
+    async onDatagram(bytes: Bytes): Promise<DtlsClientStep> {
         if (this.#state === "established" || this.#state === "failed" || this.#state === "initial") {
             throw new ImplementationError(`DtlsClient.onDatagram() called in state '${this.#state}'`);
         }
+        const buf = Bytes.of(bytes);
         try {
             switch (this.#state) {
                 case "sent_first_clienthello":
-                    return this.#handleHelloVerifyOrServerHello(this.#splitDatagramIntoRecords(bytes));
+                    return await this.#handleHelloVerifyOrServerHello(await this.#splitDatagramIntoRecords(buf));
                 case "sent_clienthello_with_cookie":
-                    return this.#handleServerHelloFlight(this.#splitDatagramIntoRecords(bytes));
+                    return await this.#handleServerHelloFlight(await this.#splitDatagramIntoRecords(buf));
                 case "sent_clientkeyexchange_flight":
                     // Cannot eagerly split this datagram — the encrypted Finished record is at
                     // epoch 1 and needs the CCS earlier in the same datagram to bump the read
                     // epoch first. Walk the record envelopes lazily so CCS arrives before the
                     // AEAD decrypt is attempted.
-                    return this.#handleServerFinishedFlightLazy(bytes);
+                    return await this.#handleServerFinishedFlightLazy(buf);
                 default:
                     throw new InternalError(`DtlsClient: state ${this.#state} cannot consume a datagram`);
             }
@@ -207,12 +213,12 @@ export class DtlsClient {
     // -----------------------------------------------------------------------
     // Datagram / record splitting
 
-    #splitDatagramIntoRecords(bytes: Uint8Array): InboundRecord[] {
+    async #splitDatagramIntoRecords(bytes: Uint8Array): Promise<InboundRecord[]> {
         const out = new Array<InboundRecord>();
         let p = 0;
         while (p < bytes.length) {
-            const { record, consumed } = DtlsRecord.decode(bytes.subarray(p), this.#cipherState);
-            out.push(record);
+            const { record, consumed } = await DtlsRecord.decode(this.#crypto, bytes.subarray(p), this.#cipherState);
+            out.push({ ...record, fragment: Bytes.of(record.fragment) });
             p += consumed;
         }
         return out;
@@ -241,7 +247,7 @@ export class DtlsClient {
     // -----------------------------------------------------------------------
     // Outbound encoding helpers
 
-    #emitClientHello(cookie: Uint8Array, contributesToTranscript: boolean): Uint8Array[] {
+    async #emitClientHello(cookie: Bytes, contributesToTranscript: boolean): Promise<Uint8Array[]> {
         const body = ClientHelloMessage.build({
             random: this.#clientRandom,
             cookie,
@@ -261,12 +267,14 @@ export class DtlsClient {
                 }),
             );
         }
-        const record = DtlsRecord.encode({
-            type: ContentType.HANDSHAKE,
-            epoch: 0,
-            sequenceNumber: this.#recordSeq,
-            fragment: handshake,
-        });
+        const record = Bytes.of(
+            await DtlsRecord.encode(this.#crypto, {
+                type: ContentType.HANDSHAKE,
+                epoch: 0,
+                sequenceNumber: this.#recordSeq,
+                fragment: handshake,
+            }),
+        );
         this.#recordSeq += 1n;
         this.#handshakeMessageSeq += 1;
         this.#lastFlight = [record];
@@ -276,7 +284,7 @@ export class DtlsClient {
     // -----------------------------------------------------------------------
     // State handlers
 
-    #handleHelloVerifyOrServerHello(records: InboundRecord[]): DtlsClientStep {
+    async #handleHelloVerifyOrServerHello(records: InboundRecord[]): Promise<DtlsClientStep> {
         const messages = this.#extractHandshakeMessages(records);
         if (messages.length === 0) {
             throw new DtlsError("DtlsClient: expected handshake message, got none");
@@ -285,14 +293,14 @@ export class DtlsClient {
             const { cookie } = HelloVerifyRequestMessage.parse(messages[0].body);
             // RFC 6347 §4.2.6: the first ClientHello and HelloVerifyRequest are NOT in the
             // transcript; the transcript starts with the second ClientHello.
-            this.#transcript = new HandshakeTranscript();
-            const records2 = this.#emitClientHello(cookie, true);
+            this.#transcript = new HandshakeTranscript(this.#crypto);
+            const records2 = await this.#emitClientHello(cookie, true);
             this.#state = "sent_clienthello_with_cookie";
             return { records: records2 };
         }
         // Cookieless server (mbedTLS always cookies, but the spec allows skipping). Seed the
         // transcript with our first (and only) ClientHello — the bytes match what we sent.
-        this.#transcript = new HandshakeTranscript();
+        this.#transcript = new HandshakeTranscript(this.#crypto);
         const firstHelloBody = ClientHelloMessage.build({
             random: this.#clientRandom,
             cookie: new Uint8Array(0),
@@ -305,15 +313,15 @@ export class DtlsClient {
                 body: firstHelloBody,
             }),
         );
-        return this.#consumeServerFlight(messages);
+        return await this.#consumeServerFlight(messages);
     }
 
-    #handleServerHelloFlight(records: InboundRecord[]): DtlsClientStep {
+    async #handleServerHelloFlight(records: InboundRecord[]): Promise<DtlsClientStep> {
         const messages = this.#extractHandshakeMessages(records);
-        return this.#consumeServerFlight(messages);
+        return await this.#consumeServerFlight(messages);
     }
 
-    #consumeServerFlight(messages: InboundHandshake[]): DtlsClientStep {
+    async #consumeServerFlight(messages: InboundHandshake[]): Promise<DtlsClientStep> {
         if (messages.length < 3) {
             throw new DtlsError(
                 `DtlsClient: server flight needs ServerHello+ServerKeyExchange+ServerHelloDone, got ${messages.length} message(s)`,
@@ -342,20 +350,20 @@ export class DtlsClient {
         this.#X4 = serverRound1.kp2.X;
         // Verify the server's round-1 ZKPs against the curve base point.
         if (
-            !SchnorrZkp.verify({
+            !(await SchnorrZkp.verify(this.#crypto, {
                 zkp: serverRound1.kp1.zkp,
                 publicKey: serverRound1.kp1.X,
                 id: ECJPAKE_ID_SERVER,
-            })
+            }))
         ) {
             throw new DtlsError("DtlsClient: server round-1 KP1 ZKP verification failed");
         }
         if (
-            !SchnorrZkp.verify({
+            !(await SchnorrZkp.verify(this.#crypto, {
                 zkp: serverRound1.kp2.zkp,
                 publicKey: serverRound1.kp2.X,
                 id: ECJPAKE_ID_SERVER,
-            })
+            }))
         ) {
             throw new DtlsError("DtlsClient: server round-1 KP2 ZKP verification failed");
         }
@@ -369,11 +377,11 @@ export class DtlsClient {
             Xm1: this.#X3,
         });
         if (
-            !EcJpakeRound.verifyRound2Zkp({
+            !(await EcJpakeRound.verifyRound2Zkp(this.#crypto, {
                 kp: skeKp,
                 generator: serverGenerator,
                 peerId: ECJPAKE_ID_SERVER,
-            })
+            }))
         ) {
             throw new DtlsError("DtlsClient: server round-2 ZKP verification failed");
         }
@@ -386,14 +394,14 @@ export class DtlsClient {
         this.#transcript.appendHandshakeMessage(shd.transcriptBytes);
 
         this.#state = "received_serverhello_flight";
-        return this.#emitClientFlight(skeKp.X);
+        return await this.#emitClientFlight(skeKp.X);
     }
 
     /**
      * Build the client's CKE + CCS + Finished flight and arm the cipher state.
      * `serverRound2X` is the server's round-2 public point (`Xp` for the PMS derivation).
      */
-    #emitClientFlight(serverRound2X: Uint8Array): DtlsClientStep {
+    async #emitClientFlight(serverRound2X: Bytes): Promise<DtlsClientStep> {
         if (this.#X3 === undefined || this.#X4 === undefined || this.#serverRandom === undefined) {
             throw new InternalError("DtlsClient: emitClientFlight called before server flight was parsed");
         }
@@ -406,7 +414,7 @@ export class DtlsClient {
             Xp2: this.#X4,
             Xm1: this.#X1,
         });
-        const clientRound2 = EcJpakeRound.buildRound2({
+        const clientRound2 = await EcJpakeRound.buildRound2(this.#crypto, {
             xm2: this.#x2,
             s,
             v: v3,
@@ -432,19 +440,21 @@ export class DtlsClient {
         );
 
         // Derive PMS, master_secret, key_block, cipher state.
-        const pms = EcJpakePms.derive({
+        const pms = await EcJpakePms.derive(this.#crypto, {
             Xp: serverRound2X,
             Xp2: this.#X4,
             xm2: this.#x2,
             s,
         });
-        const masterSecret = TlsPrf.masterSecret({
-            premasterSecret: pms,
-            clientRandom: this.#clientRandom,
-            serverRandom: this.#serverRandom,
-        });
+        const masterSecret = Bytes.of(
+            await TlsPrf.masterSecret(this.#crypto, {
+                premasterSecret: pms,
+                clientRandom: this.#clientRandom,
+                serverRandom: this.#serverRandom,
+            }),
+        );
         this.#masterSecret = masterSecret;
-        const keyBlock = TlsPrf.keyBlock({
+        const keyBlock = await TlsPrf.keyBlock(this.#crypto, {
             masterSecret,
             clientRandom: this.#clientRandom,
             serverRandom: this.#serverRandom,
@@ -458,11 +468,13 @@ export class DtlsClient {
         this.#cipherState = cipherState;
 
         // Compute client Finished verify_data over the transcript (CH..SHD..CKE).
-        const verifyData = TlsPrf.verifyData({
-            masterSecret,
-            role: "client",
-            transcriptDigest: this.#transcript.digest(),
-        });
+        const verifyData = Bytes.of(
+            await TlsPrf.verifyData(this.#crypto, {
+                masterSecret,
+                role: "client",
+                transcriptDigest: await this.#transcript.digest(),
+            }),
+        );
         const finishedBody = FinishedMessage.build(verifyData);
         const finishedMsgSeq = this.#handshakeMessageSeq;
         const finishedHandshake = HandshakeMessage.encode({
@@ -481,30 +493,37 @@ export class DtlsClient {
             }),
         );
 
-        const ckeRecord = DtlsRecord.encode({
-            type: ContentType.HANDSHAKE,
-            epoch: 0,
-            sequenceNumber: this.#recordSeq,
-            fragment: ckeHandshake,
-        });
+        const ckeRecord = Bytes.of(
+            await DtlsRecord.encode(this.#crypto, {
+                type: ContentType.HANDSHAKE,
+                epoch: 0,
+                sequenceNumber: this.#recordSeq,
+                fragment: ckeHandshake,
+            }),
+        );
         this.#recordSeq += 1n;
-        const ccsRecord = DtlsRecord.encode({
-            type: ContentType.CHANGE_CIPHER_SPEC,
-            epoch: 0,
-            sequenceNumber: this.#recordSeq,
-            fragment: CHANGE_CIPHER_SPEC_BODY,
-        });
+        const ccsRecord = Bytes.of(
+            await DtlsRecord.encode(this.#crypto, {
+                type: ContentType.CHANGE_CIPHER_SPEC,
+                epoch: 0,
+                sequenceNumber: this.#recordSeq,
+                fragment: CHANGE_CIPHER_SPEC_BODY,
+            }),
+        );
         this.#recordSeq += 1n;
         cipherState.advanceWriteEpoch();
         const finishedSeq = cipherState.nextWriteSeq();
-        const finishedRecord = DtlsRecord.encode(
-            {
-                type: ContentType.HANDSHAKE,
-                epoch: cipherState.writeEpoch,
-                sequenceNumber: finishedSeq,
-                fragment: finishedHandshake,
-            },
-            cipherState,
+        const finishedRecord = Bytes.of(
+            await DtlsRecord.encode(
+                this.#crypto,
+                {
+                    type: ContentType.HANDSHAKE,
+                    epoch: cipherState.writeEpoch,
+                    sequenceNumber: finishedSeq,
+                    fragment: finishedHandshake,
+                },
+                cipherState,
+            ),
         );
 
         const flight = [ckeRecord, ccsRecord, finishedRecord];
@@ -520,14 +539,14 @@ export class DtlsClient {
      * `DtlsRecord.decode` for both records would feed CCS to the codec only after the
      * decrypt of the Finished record had already failed with a wrong-epoch error.
      */
-    #handleServerFinishedFlightLazy(bytes: Uint8Array): DtlsClientStep {
+    async #handleServerFinishedFlightLazy(bytes: Uint8Array): Promise<DtlsClientStep> {
         const cipherState = this.#cipherState;
         const masterSecret = this.#masterSecret;
         if (cipherState === undefined || masterSecret === undefined) {
             throw new InternalError("DtlsClient: server-finished handler reached without armed cipher state");
         }
         let sawCcs = false;
-        let serverFinishedBody: Uint8Array | undefined;
+        let serverFinishedBody: Bytes | undefined;
         let serverFinishedMsgSeq = 0;
         let p = 0;
         while (p < bytes.length) {
@@ -542,7 +561,7 @@ export class DtlsClient {
             }
             const recordBytes = bytes.subarray(p, recordEnd);
             const stateForDecode = epoch === 0 ? undefined : cipherState;
-            const { record } = DtlsRecord.decode(recordBytes, stateForDecode);
+            const { record } = await DtlsRecord.decode(this.#crypto, recordBytes, stateForDecode);
             if (record.type === ContentType.CHANGE_CIPHER_SPEC) {
                 ChangeCipherSpec.parse(record.fragment);
                 cipherState.advanceReadEpoch();
@@ -556,9 +575,10 @@ export class DtlsClient {
                         `DtlsClient: server Finished record at epoch ${record.epoch}, expected ${cipherState.readEpoch}`,
                     );
                 }
+                const fragment = Bytes.of(record.fragment);
                 let q = 0;
-                while (q < record.fragment.length) {
-                    const { message, consumed } = HandshakeMessage.decode(record.fragment.subarray(q));
+                while (q < fragment.length) {
+                    const { message, consumed } = HandshakeMessage.decode(fragment.subarray(q));
                     if (message.msgType !== HandshakeType.FINISHED) {
                         throw new DtlsError(`DtlsClient: expected Finished, got msg_type=${message.msgType}`);
                     }
@@ -577,11 +597,13 @@ export class DtlsClient {
         // Snapshot the transcript BEFORE appending the server's Finished body — the server's
         // verify_data was computed over (CH..SHD..CKE..clientFinished), exactly the digest we
         // already hold from the previous append in #emitClientFlight.
-        const expected = TlsPrf.verifyData({
-            masterSecret,
-            role: "server",
-            transcriptDigest: this.#transcript.digest(),
-        });
+        const expected = Bytes.of(
+            await TlsPrf.verifyData(this.#crypto, {
+                masterSecret,
+                role: "server",
+                transcriptDigest: await this.#transcript.digest(),
+            }),
+        );
         const actual = FinishedMessage.parse(serverFinishedBody).verifyData;
         if (!constantTimeEqual(expected, actual)) {
             throw new DtlsError("DtlsClient: server Finished verify_data mismatch");
@@ -598,7 +620,9 @@ export class DtlsClient {
     }
 }
 
-function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
+function constantTimeEqual(rawA: Bytes, rawB: Bytes): boolean {
+    const a = Bytes.of(rawA);
+    const b = Bytes.of(rawB);
     if (a.length !== b.length || a.length !== FINISHED_VERIFY_DATA_LEN) {
         return false;
     }

package/src/dtls/handshake/FinishedMessage.ts

@@ -11,13 +11,14 @@
  * `TlsPrf.verifyData` and the state machine.
  */
 
-import { InternalError } from "@matter/general";
+import { Bytes, InternalError } from "@matter/general";
 import { DtlsError } from "../channel/DtlsChannel.js";
 
 const VERIFY_DATA_LEN = 12;
 
 export const FinishedMessage = {
-    build(verifyData: Uint8Array): Uint8Array {
+    build(rawVerifyData: Bytes): Bytes {
+        const verifyData = Bytes.of(rawVerifyData);
         if (verifyData.length !== VERIFY_DATA_LEN) {
             throw new InternalError(`Finished verify_data must be ${VERIFY_DATA_LEN} bytes, got ${verifyData.length}`);
         }
@@ -25,7 +26,8 @@ export const FinishedMessage = {
         return verifyData.slice();
     },
 
-    parse(body: Uint8Array): { verifyData: Uint8Array } {
+    parse(rawBody: Bytes): { verifyData: Bytes } {
+        const body = Bytes.of(rawBody);
         if (body.length !== VERIFY_DATA_LEN) {
             throw new DtlsError(`Finished body must be ${VERIFY_DATA_LEN} bytes, got ${body.length}`);
         }

package/src/dtls/handshake/HandshakeMessage.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { InternalError } from "@matter/general";
+import { Bytes, InternalError } from "@matter/general";
 import { DtlsError } from "../channel/DtlsChannel.js";
 import { HandshakeType, isHandshakeType } from "./HandshakeType.js";
 
@@ -34,7 +34,7 @@ const UINT16_MAX = 0xffff;
 export interface HandshakeMessage {
     msgType: HandshakeType;
     messageSeq: number;
-    body: Uint8Array;
+    body: Bytes;
 }
 
 function writeUint16BE(buf: Uint8Array, offset: number, value: number): void {
@@ -77,8 +77,9 @@ function readUint24BE(buf: Uint8Array, offset: number): number {
  * `fragment_length=length`).
  */
 export namespace HandshakeMessage {
-    export function encode(message: HandshakeMessage): Uint8Array {
-        const { msgType, messageSeq, body } = message;
+    export function encode(message: HandshakeMessage): Bytes {
+        const { msgType, messageSeq } = message;
+        const body = Bytes.of(message.body);
         if (!isHandshakeType(msgType)) {
             throw new InternalError(`HandshakeMessage unknown msg_type: ${msgType}`);
         }
@@ -98,7 +99,7 @@ export namespace HandshakeMessage {
         return out;
     }
 
-    export function encodeForTranscript(message: HandshakeMessage): Uint8Array {
+    export function encodeForTranscript(message: HandshakeMessage): Bytes {
         return encode(message);
     }
 
@@ -107,36 +108,37 @@ export namespace HandshakeMessage {
         consumed: number;
     }
 
-    export function decode(bytes: Uint8Array): DecodeResult {
-        if (bytes.length < DTLS_HANDSHAKE_HEADER_LEN) {
+    export function decode(bytes: Bytes): DecodeResult {
+        const buf = Bytes.of(bytes);
+        if (buf.length < DTLS_HANDSHAKE_HEADER_LEN) {
             throw new DtlsError(
-                `HandshakeMessage header truncated: have ${bytes.length}, need ${DTLS_HANDSHAKE_HEADER_LEN}`,
+                `HandshakeMessage header truncated: have ${buf.length}, need ${DTLS_HANDSHAKE_HEADER_LEN}`,
             );
         }
-        const msgType = bytes[0];
+        const msgType = buf[0];
         if (!isHandshakeType(msgType)) {
             throw new DtlsError(`HandshakeMessage unknown msg_type: ${msgType}`);
         }
-        const length = readUint24BE(bytes, 1);
-        const messageSeq = readUint16BE(bytes, 4);
-        const fragmentOffset = readUint24BE(bytes, 6);
-        const fragmentLength = readUint24BE(bytes, 9);
+        const length = readUint24BE(buf, 1);
+        const messageSeq = readUint16BE(buf, 4);
+        const fragmentOffset = readUint24BE(buf, 6);
+        const fragmentLength = readUint24BE(buf, 9);
         if (fragmentOffset !== 0 || fragmentLength !== length) {
             throw new DtlsError(
                 `HandshakeMessage fragmented input not supported: offset=${fragmentOffset} fragLen=${fragmentLength} totalLen=${length}`,
             );
         }
         const total = DTLS_HANDSHAKE_HEADER_LEN + length;
-        if (bytes.length < total) {
+        if (buf.length < total) {
             throw new DtlsError(
-                `HandshakeMessage body truncated: header says ${length}, have ${bytes.length - DTLS_HANDSHAKE_HEADER_LEN}`,
+                `HandshakeMessage body truncated: header says ${length}, have ${buf.length - DTLS_HANDSHAKE_HEADER_LEN}`,
             );
         }
         return {
             message: {
                 msgType,
                 messageSeq,
-                body: bytes.slice(DTLS_HANDSHAKE_HEADER_LEN, total),
+                body: buf.slice(DTLS_HANDSHAKE_HEADER_LEN, total),
             },
             consumed: total,
         };

package/src/dtls/handshake/HelloVerifyRequestMessage.ts

@@ -21,12 +21,14 @@
  * ClientHello carry the spec-mandated DTLS 1.2 version regardless.
  */
 
+import { Bytes } from "@matter/general";
 import { DtlsError } from "../channel/DtlsChannel.js";
 
 const MAX_COOKIE_LEN = 0xff;
 
 export const HelloVerifyRequestMessage = {
-    parse(body: Uint8Array): { cookie: Uint8Array } {
+    parse(rawBody: Bytes): { cookie: Bytes } {
+        const body = Bytes.of(rawBody);
         if (body.length < 2 + 1) {
             throw new DtlsError(`HelloVerifyRequest body truncated: have ${body.length}, need >= 3`);
         }

package/src/dtls/handshake/ServerHelloDoneMessage.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Bytes } from "@matter/general";
 import { DtlsError } from "../channel/DtlsChannel.js";
 
 /**
@@ -12,9 +13,10 @@ import { DtlsError } from "../channel/DtlsChannel.js";
  * a single place to fail loudly if a future BR ever sends payload bytes here.
  */
 export const ServerHelloDoneMessage = {
-    parse(body: Uint8Array): void {
-        if (body.length !== 0) {
-            throw new DtlsError(`ServerHelloDone body must be empty, got ${body.length} bytes`);
+    parse(body: Bytes): void {
+        const length = body.byteLength;
+        if (length !== 0) {
+            throw new DtlsError(`ServerHelloDone body must be empty, got ${length} bytes`);
         }
     },
 } as const;

package/src/dtls/handshake/ServerHelloMessage.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Bytes } from "@matter/general";
 import { DtlsError } from "../channel/DtlsChannel.js";
 import { CIPHER_SUITE_ECJPAKE_WITH_AES_128_CCM_8, EXTENSION_TYPE_ECJPAKE_KKPP } from "./ClientHelloMessage.js";
 
@@ -44,13 +45,14 @@ function readUint16BE(buf: Uint8Array, offset: number): number {
 
 export interface ParsedServerHello {
     /** Server's 32-byte random — feeds the TLS PRF. */
-    serverRandom: Uint8Array;
+    serverRandom: Bytes;
     /** Server's `ecjpake_kkpp` extension data (round-1 ECJPAKEKeyKPPairList). */
-    ecjpakeKkpp: Uint8Array;
+    ecjpakeKkpp: Bytes;
 }
 
 export const ServerHelloMessage = {
-    parse(body: Uint8Array): ParsedServerHello {
+    parse(rawBody: Bytes): ParsedServerHello {
+        const body = Bytes.of(rawBody);
         if (body.length < 2 + RANDOM_LEN + 1 + 2 + 1) {
             throw new DtlsError(`ServerHello body truncated: have ${body.length}`);
         }