@matter/thread-br-client 0.0.1

package/src/dtls/handshake/HandshakeMessage.ts

@@ -0,0 +1,144 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "@matter/general";
+import { DtlsError } from "../channel/DtlsChannel.js";
+import { HandshakeType, isHandshakeType } from "./HandshakeType.js";
+
+/** Length of the DTLS 1.2 handshake message header (RFC 6347 §4.2.2). */
+export const DTLS_HANDSHAKE_HEADER_LEN = 12;
+
+/** Length of the TLS 1.2 handshake message header (RFC 5246 §7.4). */
+export const TLS_HANDSHAKE_HEADER_LEN = 4;
+
+/** Maximum value representable in a 24-bit unsigned big-endian field. */
+export const UINT24_MAX = (1 << 24) - 1;
+
+/** Maximum value representable in a 16-bit unsigned big-endian field. */
+const UINT16_MAX = 0xffff;
+
+/**
+ * One full (unfragmented) DTLS 1.2 handshake message (RFC 6347 §4.2.2). For the
+ * EC-JPAKE handshake we never produce or consume fragmented handshake messages
+ * — every flight fits in the conservative 1280-byte UDP MTU when measured per
+ * record, and mbedTLS does not fragment the messages we exchange — so the
+ * `fragment_offset` is always 0 and `fragment_length` always equals `length`.
+ *
+ * For a fragmented message the body would be only `fragment_length` bytes long;
+ * fragmented input is rejected by {@link HandshakeMessage.decode} until we need
+ * it. (Sub-batch 5 will add a reassembler if real-world traces ever fragment.)
+ */
+export interface HandshakeMessage {
+    msgType: HandshakeType;
+    messageSeq: number;
+    body: Uint8Array;
+}
+
+function writeUint16BE(buf: Uint8Array, offset: number, value: number): void {
+    buf[offset] = (value >>> 8) & 0xff;
+    buf[offset + 1] = value & 0xff;
+}
+
+function writeUint24BE(buf: Uint8Array, offset: number, value: number): void {
+    buf[offset] = (value >>> 16) & 0xff;
+    buf[offset + 1] = (value >>> 8) & 0xff;
+    buf[offset + 2] = value & 0xff;
+}
+
+function readUint16BE(buf: Uint8Array, offset: number): number {
+    return (buf[offset] << 8) | buf[offset + 1];
+}
+
+function readUint24BE(buf: Uint8Array, offset: number): number {
+    return (buf[offset] << 16) | (buf[offset + 1] << 8) | buf[offset + 2];
+}
+
+/**
+ * DTLS 1.2 handshake message envelope codec (RFC 6347 §4.2.2).
+ *
+ * `encode` produces the wire form: `type(1) || length(3) || message_seq(2) ||
+ * fragment_offset(3) || fragment_length(3) || body`. We always emit the
+ * unfragmented form (`fragment_offset=0`, `fragment_length=body.length`).
+ *
+ * `encodeForTranscript` emits the **full DTLS 1.2 form** — same 12-byte header
+ * as `encode` — required by the running handshake-transcript hash. mbedTLS
+ * (and OpenThread BRs built on it) feed the full DTLS handshake bytes
+ * including `message_seq` / `fragment_offset` / `fragment_length` into the
+ * Finished MAC; an earlier reading of RFC 6347 §4.2.6 incorrectly suggested
+ * stripping them. The `fragment_offset`/`fragment_length` are normalised to
+ * the unfragmented form (0 / body.length) regardless of how the message was
+ * actually fragmented on the wire (RFC 6347 §4.2.6 second paragraph).
+ *
+ * `decode` parses one DTLS handshake message off the front of the buffer; it
+ * requires the message to be unfragmented (`fragment_offset=0`,
+ * `fragment_length=length`).
+ */
+export namespace HandshakeMessage {
+    export function encode(message: HandshakeMessage): Uint8Array {
+        const { msgType, messageSeq, body } = message;
+        if (!isHandshakeType(msgType)) {
+            throw new InternalError(`HandshakeMessage unknown msg_type: ${msgType}`);
+        }
+        if (messageSeq < 0 || messageSeq > UINT16_MAX) {
+            throw new InternalError(`HandshakeMessage message_seq ${messageSeq} out of range`);
+        }
+        if (body.length > UINT24_MAX) {
+            throw new InternalError(`HandshakeMessage body length ${body.length} exceeds 24-bit max`);
+        }
+        const out = new Uint8Array(DTLS_HANDSHAKE_HEADER_LEN + body.length);
+        out[0] = msgType;
+        writeUint24BE(out, 1, body.length);
+        writeUint16BE(out, 4, messageSeq);
+        writeUint24BE(out, 6, 0);
+        writeUint24BE(out, 9, body.length);
+        out.set(body, DTLS_HANDSHAKE_HEADER_LEN);
+        return out;
+    }
+
+    export function encodeForTranscript(message: HandshakeMessage): Uint8Array {
+        return encode(message);
+    }
+
+    export interface DecodeResult {
+        message: HandshakeMessage;
+        consumed: number;
+    }
+
+    export function decode(bytes: Uint8Array): DecodeResult {
+        if (bytes.length < DTLS_HANDSHAKE_HEADER_LEN) {
+            throw new DtlsError(
+                `HandshakeMessage header truncated: have ${bytes.length}, need ${DTLS_HANDSHAKE_HEADER_LEN}`,
+            );
+        }
+        const msgType = bytes[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);
+        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) {
+            throw new DtlsError(
+                `HandshakeMessage body truncated: header says ${length}, have ${bytes.length - DTLS_HANDSHAKE_HEADER_LEN}`,
+            );
+        }
+        return {
+            message: {
+                msgType,
+                messageSeq,
+                body: bytes.slice(DTLS_HANDSHAKE_HEADER_LEN, total),
+            },
+            consumed: total,
+        };
+    }
+}

package/src/dtls/handshake/HandshakeType.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * TLS 1.2 / DTLS 1.2 HandshakeType values used by the EC-JPAKE flight diagram
+ * (RFC 5246 §7.4, RFC 6347 §4.2). Only the subset needed for
+ * `TLS_ECJPAKE_WITH_AES_128_CCM_8` is declared; any other byte triggers a
+ * decode error in {@link HandshakeMessage.decode}.
+ *
+ * `HELLO_REQUEST` is included for completeness — we do not send it (we are
+ * always the client) but mbedTLS will silently ignore it from the server side
+ * and we want a known constant if a peer ever sends one.
+ */
+export const HandshakeType = {
+    HELLO_REQUEST: 0,
+    CLIENT_HELLO: 1,
+    SERVER_HELLO: 2,
+    HELLO_VERIFY_REQUEST: 3,
+    CERTIFICATE: 11,
+    SERVER_KEY_EXCHANGE: 12,
+    SERVER_HELLO_DONE: 14,
+    CLIENT_KEY_EXCHANGE: 16,
+    FINISHED: 20,
+} as const;
+
+export type HandshakeType = (typeof HandshakeType)[keyof typeof HandshakeType];
+
+const VALID_TYPES = new Set<number>([0, 1, 2, 3, 11, 12, 14, 16, 20]);
+
+export function isHandshakeType(value: number): value is HandshakeType {
+    return VALID_TYPES.has(value);
+}

package/src/dtls/handshake/HelloVerifyRequestMessage.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * DTLS 1.2 HelloVerifyRequest body parser (RFC 6347 §4.2.1):
+ *
+ * ```
+ * struct {
+ *   ProtocolVersion server_version;   // 2 bytes (server may use {254, 255} for legacy reasons)
+ *   opaque cookie<0..2^8-1>;          // 1-byte length + body
+ * } HelloVerifyRequest;
+ * ```
+ *
+ * Per RFC 6347 §4.2.1 the client MUST echo `server_version` back in the next
+ * ClientHello, but in practice every modern stack (mbedTLS, OpenThread) uses
+ * the same DTLS 1.2 version byte pair the client already advertised, so we
+ * accept any version bytes here without enforcement and let the next
+ * ClientHello carry the spec-mandated DTLS 1.2 version regardless.
+ */
+
+import { DtlsError } from "../channel/DtlsChannel.js";
+
+const MAX_COOKIE_LEN = 0xff;
+
+export const HelloVerifyRequestMessage = {
+    parse(body: Uint8Array): { cookie: Uint8Array } {
+        if (body.length < 2 + 1) {
+            throw new DtlsError(`HelloVerifyRequest body truncated: have ${body.length}, need >= 3`);
+        }
+        // server_version (2 bytes) is intentionally not validated — see jsdoc.
+        const cookieLen = body[2];
+        if (cookieLen > MAX_COOKIE_LEN) {
+            throw new DtlsError(`HelloVerifyRequest cookie length ${cookieLen} exceeds ${MAX_COOKIE_LEN}`);
+        }
+        const expectedLen = 2 + 1 + cookieLen;
+        if (body.length !== expectedLen) {
+            throw new DtlsError(
+                `HelloVerifyRequest body length ${body.length} disagrees with cookie length ${cookieLen} (expected ${expectedLen})`,
+            );
+        }
+        // slice (copy) so the parsed cookie does not alias the inbound datagram buffer.
+        return { cookie: body.slice(3, 3 + cookieLen) };
+    },
+} as const;

package/src/dtls/handshake/ServerHelloDoneMessage.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { DtlsError } from "../channel/DtlsChannel.js";
+
+/**
+ * ServerHelloDone body parser (RFC 5246 §7.4.5). The body is empty; this
+ * exists only so the state machine has a uniform per-message entry point and
+ * 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`);
+        }
+    },
+} as const;

package/src/dtls/handshake/ServerHelloMessage.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { DtlsError } from "../channel/DtlsChannel.js";
+import { CIPHER_SUITE_ECJPAKE_WITH_AES_128_CCM_8, EXTENSION_TYPE_ECJPAKE_KKPP } from "./ClientHelloMessage.js";
+
+/**
+ * DTLS 1.2 ServerHello body parser (RFC 5246 §7.4.1.3, layered into RFC 6347):
+ *
+ * ```
+ * ProtocolVersion server_version    // 2 bytes — must be DTLS 1.2 (0xfe 0xfd)
+ * Random random                     // 32 bytes
+ * opaque session_id<0..32>          // length(1) || body
+ * CipherSuite cipher_suite          // 2 bytes — must be TLS_ECJPAKE_WITH_AES_128_CCM_8 (0xC0FF)
+ * uint8 compression_method          // 1 byte — must be 0x00 (null)
+ * Extension extensions<0..2^16-1>   // length(2) || entries (optional, present when bytes remain)
+ * ```
+ *
+ * Each Extension is `uint16 extension_type || opaque extension_data<0..2^16-1>`.
+ * The parser validates that the cipher suite, compression method and DTLS
+ * version match the ones we sent — anything else is a hard error since the
+ * server has agreed to a configuration we cannot speak — and extracts:
+ *
+ * - `serverRandom`: the 32-byte server random fed into the TLS PRF.
+ * - `ecjpakeKkpp`: the body of the server's `ecjpake_kkpp` extension (the
+ *    round-1 ECJPAKEKeyKPPairList from the server's perspective).
+ *
+ * Unknown extensions are tolerated and skipped; the spec allows servers to
+ * send extensions the client did not request as long as the matching ones
+ * are correct (RFC 5246 §7.4.1.4). We refuse only on missing `ecjpake_kkpp`.
+ */
+
+const DTLS_1_2_MAJOR = 0xfe;
+const DTLS_1_2_MINOR = 0xfd;
+const RANDOM_LEN = 32;
+const COMPRESSION_NULL = 0x00;
+
+function readUint16BE(buf: Uint8Array, offset: number): number {
+    return (buf[offset] << 8) | buf[offset + 1];
+}
+
+export interface ParsedServerHello {
+    /** Server's 32-byte random — feeds the TLS PRF. */
+    serverRandom: Uint8Array;
+    /** Server's `ecjpake_kkpp` extension data (round-1 ECJPAKEKeyKPPairList). */
+    ecjpakeKkpp: Uint8Array;
+}
+
+export const ServerHelloMessage = {
+    parse(body: Uint8Array): ParsedServerHello {
+        if (body.length < 2 + RANDOM_LEN + 1 + 2 + 1) {
+            throw new DtlsError(`ServerHello body truncated: have ${body.length}`);
+        }
+        let p = 0;
+        const major = body[p++];
+        const minor = body[p++];
+        if (major !== DTLS_1_2_MAJOR || minor !== DTLS_1_2_MINOR) {
+            throw new DtlsError(`ServerHello version ${major.toString(16)}.${minor.toString(16)} is not DTLS 1.2`);
+        }
+        // slice (copy) so the parsed random does not alias the inbound datagram buffer.
+        const serverRandom = body.slice(p, p + RANDOM_LEN);
+        p += RANDOM_LEN;
+        const sessionIdLen = body[p++];
+        if (p + sessionIdLen > body.length) {
+            throw new DtlsError(`ServerHello session_id length ${sessionIdLen} overruns body`);
+        }
+        // We don't preserve the session_id — we never resume sessions in this stack.
+        p += sessionIdLen;
+        if (p + 2 + 1 > body.length) {
+            throw new DtlsError(`ServerHello truncated before cipher_suite/compression_method`);
+        }
+        const suite = readUint16BE(body, p);
+        p += 2;
+        if (suite !== CIPHER_SUITE_ECJPAKE_WITH_AES_128_CCM_8) {
+            throw new DtlsError(
+                `ServerHello selected unsupported cipher suite 0x${suite.toString(16).padStart(4, "0")}; require TLS_ECJPAKE_WITH_AES_128_CCM_8 (0xc0ff)`,
+            );
+        }
+        const compression = body[p++];
+        if (compression !== COMPRESSION_NULL) {
+            throw new DtlsError(`ServerHello selected unsupported compression method 0x${compression.toString(16)}`);
+        }
+
+        let ecjpakeKkpp: Uint8Array | undefined;
+        if (p < body.length) {
+            if (p + 2 > body.length) {
+                throw new DtlsError("ServerHello extensions block length truncated");
+            }
+            const extsLen = readUint16BE(body, p);
+            p += 2;
+            const extsEnd = p + extsLen;
+            if (extsEnd > body.length) {
+                throw new DtlsError(`ServerHello extensions length ${extsLen} overruns body`);
+            }
+            while (p < extsEnd) {
+                if (p + 4 > extsEnd) {
+                    throw new DtlsError("ServerHello extension entry truncated");
+                }
+                const extType = readUint16BE(body, p);
+                p += 2;
+                const extDataLen = readUint16BE(body, p);
+                p += 2;
+                if (p + extDataLen > extsEnd) {
+                    throw new DtlsError(`ServerHello extension type 0x${extType.toString(16)} data overruns`);
+                }
+                if (extType === EXTENSION_TYPE_ECJPAKE_KKPP) {
+                    if (ecjpakeKkpp !== undefined) {
+                        throw new DtlsError("ServerHello contains multiple ecjpake_kkpp extensions");
+                    }
+                    ecjpakeKkpp = body.slice(p, p + extDataLen);
+                }
+                p += extDataLen;
+            }
+            if (p !== extsEnd) {
+                throw new DtlsError(`ServerHello extensions block ended at ${p}, expected ${extsEnd}`);
+            }
+        }
+        if (p !== body.length) {
+            throw new DtlsError(`ServerHello has ${body.length - p} trailing bytes after extensions block`);
+        }
+        if (ecjpakeKkpp === undefined) {
+            throw new DtlsError("ServerHello missing required ecjpake_kkpp extension (type 0x0100)");
+        }
+        return { serverRandom, ecjpakeKkpp };
+    },
+} as const;

package/src/dtls/handshake/ServerKeyExchangeMessage.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { type EcJpakeKeyKP, EcJpakeRound } from "../ecjpake/EcJpakeRound.js";
+
+/**
+ * ServerKeyExchange body parser for `TLS_ECJPAKE_WITH_AES_128_CCM_8`
+ * (mbedTLS `ssl_tls12_server.c:2467-2507`):
+ *
+ * ```
+ * ECParameters curve_params         // 0x03 || 0x00 || 0x17  (named_curve, secp256r1)
+ * ECJPAKEKeyKP server_round2        // 1 + 65 + 1 + 65 + 1 + |r| bytes
+ * ```
+ *
+ * The 3-byte ECParameters header is *prepended by the TLS-binding layer*, not
+ * by the EC-JPAKE module — see the architecture notes section 2 — so we
+ * strip it here before handing the remainder to {@link EcJpakeRound.parseRound2}
+ * with `expectEcParameters: false`.
+ */
+
+export const ServerKeyExchangeMessage = {
+    parse(body: Uint8Array): EcJpakeKeyKP {
+        // EcJpakeRound.parseRound2 already validates the 3-byte ECParameters prefix
+        // and the ECJPAKEKeyKP body when `expectEcParameters` is true; deferring keeps
+        // both error paths (bad prefix, bad body) consistent with round-1 parsers.
+        return EcJpakeRound.parseRound2(body, { expectEcParameters: true });
+    },
+} as const;

package/src/dtls/handshake/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * DTLS 1.2 client-side handshake driver for `TLS_ECJPAKE_WITH_AES_128_CCM_8`.
+ * Internal to `dtls/`; not re-exported from the package public API surface
+ * until the {@link DtlsChannel} interface ships in sub-batch 5. The per-message
+ * encoders/parsers (`ClientHelloMessage`, `ServerHelloMessage`, `HandshakeMessage`,
+ * etc.) are deliberately kept private to this module.
+ */
+
+export { DtlsClient, type DtlsClientConfig, type DtlsClientState, type DtlsClientStep } from "./DtlsClient.js";

package/src/dtls/prf/HandshakeTranscript.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "@matter/general";
+import { createHash, type Hash } from "node:crypto";
+
+const SHA256_LEN = 32;
+
+/**
+ * Running SHA-256 over the DTLS 1.2 handshake transcript that feeds the
+ * Finished MAC (RFC 5246 §7.4.9). The transcript covers every handshake
+ * message from the initial ClientHello up to (and EXCLUDING) the Finished
+ * being computed or verified.
+ *
+ * Callers feed the **full DTLS 1.2 handshake message bytes** (12-byte header
+ * including `message_seq` / `fragment_offset` / `fragment_length`, then body).
+ * mbedTLS — and OpenThread BRs built on it — hash the full DTLS form;
+ * stripping the DTLS-only fields makes the Finished MAC mismatch.
+ * `fragment_offset`/`fragment_length` are normalised to the unfragmented form
+ * regardless of how the message was actually fragmented on the wire (RFC 6347
+ * §4.2.6).
+ *
+ * Internal to `dtls/`; not re-exported from the package public API surface.
+ */
+export class HandshakeTranscript {
+    #hash: Hash = createHash("sha256");
+
+    /**
+     * Append a handshake message in DTLS 1.2 form
+     * (`type(1) || length(3) || message_seq(2) || fragment_offset(3) || fragment_length(3) || body`).
+     */
+    appendHandshakeMessage(messageBytes: Uint8Array): void {
+        this.#hash.update(messageBytes);
+    }
+
+    /**
+     * Snapshot the running SHA-256 digest without disturbing the transcript so
+     * the same accumulator can compute Finished for both peers and continue
+     * absorbing later messages. Backed by `Hash.copy()` (Node.js >= 13.10).
+     */
+    digest(): Uint8Array {
+        const snapshot = this.#hash.copy();
+        const out = new Uint8Array(snapshot.digest());
+        if (out.length !== SHA256_LEN) {
+            throw new InternalError(`HandshakeTranscript digest length ${out.length} != ${SHA256_LEN}`);
+        }
+        return out;
+    }
+}

package/src/dtls/prf/TlsPrf.ts

@@ -0,0 +1,173 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "@matter/general";
+import { createHmac } from "node:crypto";
+
+const SHA256_LEN = 32;
+const MASTER_SECRET_LEN = 48;
+const RANDOM_LEN = 32;
+const KEY_LEN = 16;
+const IV_LEN = 4;
+const KEY_BLOCK_LEN = KEY_LEN * 2 + IV_LEN * 2;
+const VERIFY_DATA_LEN = 12;
+
+const ASCII_ENCODER = new TextEncoder();
+
+function hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array {
+    const hmac = createHmac("sha256", key);
+    hmac.update(data);
+    return new Uint8Array(hmac.digest());
+}
+
+function expectLength(name: string, value: Uint8Array, expected: number): void {
+    if (value.length !== expected) {
+        throw new InternalError(`TlsPrf ${name} must be ${expected} bytes, got ${value.length}`);
+    }
+}
+
+function pSha256(secret: Uint8Array, seed: Uint8Array, outputLength: number): Uint8Array {
+    if (outputLength < 0) {
+        throw new InternalError(`TlsPrf outputLength must be non-negative, got ${outputLength}`);
+    }
+    const out = new Uint8Array(outputLength);
+    if (outputLength === 0) {
+        return out;
+    }
+    let a = hmacSha256(secret, seed);
+    const block = new Uint8Array(SHA256_LEN + seed.length);
+    block.set(seed, SHA256_LEN);
+    let written = 0;
+    while (written < outputLength) {
+        block.set(a, 0);
+        const next = hmacSha256(secret, block);
+        const remaining = outputLength - written;
+        const copyLen = Math.min(SHA256_LEN, remaining);
+        out.set(next.subarray(0, copyLen), written);
+        written += copyLen;
+        if (written < outputLength) {
+            a = hmacSha256(secret, a);
+        }
+    }
+    return out;
+}
+
+/**
+ * TLS 1.2 pseudo-random function (RFC 5246 §5) using HMAC-SHA256 — the only PRF
+ * permitted for `TLS_ECJPAKE_WITH_AES_128_CCM_8` (RFC 6655 §3). Mirrors mbedTLS
+ * v3.6.6 `tls_prf_sha256` / `tls_prf_generic`.
+ *
+ * Internal to `dtls/`; not re-exported from the package public API surface.
+ */
+export namespace TlsPrf {
+    /**
+     * P_SHA256 expansion as defined in RFC 5246 §5:
+     *
+     *   P_hash(secret, seed) = HMAC_hash(secret, A(1) || seed) ||
+     *                          HMAC_hash(secret, A(2) || seed) || ...
+     *
+     * with `A(0) = seed`, `A(i) = HMAC_hash(secret, A(i-1))`. The TLS 1.2 PRF
+     * over (label, seed) is `P_SHA256(secret, label || seed)` — label bytes are
+     * concatenated with the seed (no length prefix). The label is ASCII per
+     * RFC 5246; we encode it as UTF-8 which coincides for ASCII-only input.
+     */
+    export function compute(args: {
+        secret: Uint8Array;
+        label: string;
+        seed: Uint8Array;
+        outputLength: number;
+    }): Uint8Array {
+        const { secret, label, seed, outputLength } = args;
+        const labelBytes = ASCII_ENCODER.encode(label);
+        const combined = new Uint8Array(labelBytes.length + seed.length);
+        combined.set(labelBytes, 0);
+        combined.set(seed, labelBytes.length);
+        return pSha256(secret, combined, outputLength);
+    }
+
+    /**
+     * `master_secret = PRF(pre_master_secret, "master secret",
+     *                      ClientHello.random || ServerHello.random)[0..47]`
+     * (RFC 5246 §8.1).
+     */
+    export function masterSecret(args: {
+        premasterSecret: Uint8Array;
+        clientRandom: Uint8Array;
+        serverRandom: Uint8Array;
+    }): Uint8Array {
+        const { premasterSecret, clientRandom, serverRandom } = args;
+        expectLength("clientRandom", clientRandom, RANDOM_LEN);
+        expectLength("serverRandom", serverRandom, RANDOM_LEN);
+        const seed = new Uint8Array(RANDOM_LEN * 2);
+        seed.set(clientRandom, 0);
+        seed.set(serverRandom, RANDOM_LEN);
+        return compute({ secret: premasterSecret, label: "master secret", seed, outputLength: MASTER_SECRET_LEN });
+    }
+
+    /**
+     * Slices of the 40-byte key block for `TLS_ECJPAKE_WITH_AES_128_CCM_8`
+     * (AEAD, no MAC keys; RFC 6655 §3, RFC 5246 §6.3).
+     */
+    export interface KeyBlock {
+        clientWriteKey: Uint8Array;
+        serverWriteKey: Uint8Array;
+        clientWriteIv: Uint8Array;
+        serverWriteIv: Uint8Array;
+    }
+
+    /**
+     * `key_block = PRF(master_secret, "key expansion",
+     *                  ServerHello.random || ClientHello.random)[0..39]`
+     * (RFC 5246 §6.3). Note the seed order is REVERSED relative to
+     * {@link masterSecret} (server then client) — see mbedTLS ssl_tls.c v3.6.6
+     * "Swap the client and server random values" (RFC 5246 6.3 vs 8.1).
+     *
+     * For `TLS_ECJPAKE_WITH_AES_128_CCM_8` the layout is:
+     * `client_write_key (16) || server_write_key (16) ||
+     *  client_write_IV (4)  || server_write_IV (4)`.
+     */
+    export function keyBlock(args: {
+        masterSecret: Uint8Array;
+        clientRandom: Uint8Array;
+        serverRandom: Uint8Array;
+    }): KeyBlock {
+        const { masterSecret: ms, clientRandom, serverRandom } = args;
+        expectLength("masterSecret", ms, MASTER_SECRET_LEN);
+        expectLength("clientRandom", clientRandom, RANDOM_LEN);
+        expectLength("serverRandom", serverRandom, RANDOM_LEN);
+        const seed = new Uint8Array(RANDOM_LEN * 2);
+        seed.set(serverRandom, 0);
+        seed.set(clientRandom, RANDOM_LEN);
+        const block = compute({ secret: ms, label: "key expansion", seed, outputLength: KEY_BLOCK_LEN });
+        return {
+            clientWriteKey: block.slice(0, KEY_LEN),
+            serverWriteKey: block.slice(KEY_LEN, KEY_LEN * 2),
+            clientWriteIv: block.slice(KEY_LEN * 2, KEY_LEN * 2 + IV_LEN),
+            serverWriteIv: block.slice(KEY_LEN * 2 + IV_LEN, KEY_BLOCK_LEN),
+        };
+    }
+
+    /**
+     * Finished `verify_data` (RFC 5246 §7.4.9):
+     *
+     *   verify_data = PRF(master_secret, finished_label,
+     *                     Hash(handshake_messages))[0..11]
+     *
+     * with `finished_label = "client finished"` for the client-sent Finished
+     * and `"server finished"` for the server-sent one.
+     */
+    export function verifyData(args: {
+        masterSecret: Uint8Array;
+        role: "client" | "server";
+        transcriptDigest: Uint8Array;
+    }): Uint8Array {
+        const { masterSecret: ms, role, transcriptDigest } = args;
+        expectLength("masterSecret", ms, MASTER_SECRET_LEN);
+        expectLength("transcriptDigest", transcriptDigest, SHA256_LEN);
+        const label = role === "client" ? "client finished" : "server finished";
+        return compute({ secret: ms, label, seed: transcriptDigest, outputLength: VERIFY_DATA_LEN });
+    }
+}

package/src/dtls/prf/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * TLS 1.2 PRF (P_SHA256) and SHA-256 handshake-transcript helpers used by the
+ * DTLS 1.2 layer. Internal to `dtls/`; not re-exported from the package public
+ * API surface until the {@link DtlsChannel} interface ships in sub-batch 5.
+ */
+
+export { HandshakeTranscript } from "./HandshakeTranscript.js";
+export { TlsPrf } from "./TlsPrf.js";