@matter/thread-br-client 0.0.1

package/src/dtls/ecjpake/EcJpakeRound.ts

@@ -0,0 +1,279 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "@matter/general";
+import { p256 } from "@noble/curves/nist.js";
+import { DtlsError } from "../channel/DtlsChannel.js";
+import { SchnorrZkp, type SchnorrZkpGenerator } from "./SchnorrZkp.js";
+
+/**
+ * One half of an EC-JPAKE round-1 message: an ephemeral public key plus a Schnorr
+ * proof of knowledge of its private scalar against the curve generator.
+ *
+ * Wire (mbedTLS v3.6.6 `ecjpake_kkp_write`):
+ * ```
+ * uint8 X_len; uint8 X[X_len];          // X_len = 65 for P-256 uncompressed
+ * uint8 V_len; uint8 V[V_len];          // V_len = 65 for P-256 uncompressed
+ * uint8 r_len; uint8 r[r_len];          // r_len is minimal, leading zeros stripped
+ * ```
+ */
+export interface EcJpakeKeyKP {
+    /** SEC1-uncompressed public key `X = x*G`. */
+    X: Uint8Array;
+    /** Schnorr ZKP proving knowledge of `x`. */
+    zkp: SchnorrZkp;
+}
+
+const Point = p256.Point;
+const N = Point.Fn.ORDER;
+const POINT_LEN = 65;
+
+/**
+ * EC-JPAKE participant identifiers used in the ZKP challenge hash. These are the literal
+ * byte strings from mbedTLS `ecjpake_id[]` (mbedtls v3.6.6 `library/ecjpake.c`); the wire
+ * value is a hash input on both sides, so the strings must match between client and server.
+ */
+export const ECJPAKE_ID_CLIENT = "client";
+export const ECJPAKE_ID_SERVER = "server";
+
+function readU8(bytes: Uint8Array, offset: number): number {
+    if (offset >= bytes.length) {
+        throw new DtlsError(`unexpected end of buffer at offset ${offset}`);
+    }
+    return bytes[offset];
+}
+
+function readSlice(bytes: Uint8Array, offset: number, length: number): Uint8Array {
+    if (offset + length > bytes.length) {
+        throw new DtlsError(
+            `buffer too short: need ${length} bytes at offset ${offset}, have ${bytes.length - offset}`,
+        );
+    }
+    // slice (copy) so parse outputs own their bytes; callers can pass subarray views safely.
+    return bytes.slice(offset, offset + length);
+}
+
+function validateKeyKP(keyKP: EcJpakeKeyKP): void {
+    if (keyKP.X.length !== POINT_LEN || keyKP.X[0] !== 0x04) {
+        throw new InternalError("X must be SEC1-uncompressed P-256 (65 bytes, 0x04 prefix)");
+    }
+    if (keyKP.zkp.V.length !== POINT_LEN || keyKP.zkp.V[0] !== 0x04) {
+        throw new InternalError("ZKP.V must be SEC1-uncompressed P-256 (65 bytes, 0x04 prefix)");
+    }
+    if (keyKP.zkp.r.length === 0 || keyKP.zkp.r.length > 255) {
+        throw new InternalError(`ZKP.r length must be 1..255, got ${keyKP.zkp.r.length}`);
+    }
+    // Minimal-encoding invariant: leading byte must be non-zero (except r === 0,
+    // already excluded above). mbedTLS produces the minimal form via mbedtls_mpi_size,
+    // so ours must too if we want byte-identical output.
+    if (keyKP.zkp.r[0] === 0x00) {
+        throw new InternalError("ZKP.r must be minimal big-endian (no leading zero)");
+    }
+}
+
+function keyKpEncodedLength(keyKP: EcJpakeKeyKP): number {
+    return 1 + POINT_LEN + 1 + POINT_LEN + 1 + keyKP.zkp.r.length;
+}
+
+function writeKeyKP(keyKP: EcJpakeKeyKP, out: Uint8Array, offset: number): number {
+    let p = offset;
+    out[p++] = POINT_LEN;
+    out.set(keyKP.X, p);
+    p += POINT_LEN;
+    out[p++] = POINT_LEN;
+    out.set(keyKP.zkp.V, p);
+    p += POINT_LEN;
+    out[p++] = keyKP.zkp.r.length;
+    out.set(keyKP.zkp.r, p);
+    p += keyKP.zkp.r.length;
+    return p;
+}
+
+function readKeyKP(bytes: Uint8Array, offset: number): { kp: EcJpakeKeyKP; nextOffset: number } {
+    let p = offset;
+    const xLen = readU8(bytes, p);
+    p += 1;
+    if (xLen !== POINT_LEN) {
+        throw new DtlsError(`expected P-256 point length ${POINT_LEN}, got ${xLen}`);
+    }
+    const X = readSlice(bytes, p, xLen);
+    p += xLen;
+    const vLen = readU8(bytes, p);
+    p += 1;
+    if (vLen !== POINT_LEN) {
+        throw new DtlsError(`expected P-256 ZKP.V length ${POINT_LEN}, got ${vLen}`);
+    }
+    const V = readSlice(bytes, p, vLen);
+    p += vLen;
+    const rLen = readU8(bytes, p);
+    p += 1;
+    if (rLen === 0) {
+        throw new DtlsError("ZKP.r length must be > 0");
+    }
+    const r = readSlice(bytes, p, rLen);
+    p += rLen;
+
+    return {
+        kp: { X, zkp: { V, r } },
+        nextOffset: p,
+    };
+}
+
+/**
+ * EC-JPAKE round 1 codec on top of the wire format that mbedTLS calls
+ * `ECJPAKEKeyKPPairList`: two `ECJPAKEKeyKP` structures back-to-back, no separator,
+ * no outer length (the carrying TLS extension layer adds the 2-byte length on the wire).
+ *
+ * Mirrors mbedTLS `ecjpake_kkpp_write` / `ecjpake_kkpp_read`.
+ */
+export const EcJpakeRound = {
+    /**
+     * Build a round-1 message for one role from two private scalars and two ephemeral
+     * scalars (one ephemeral per ZKP). Caller-supplied ephemerals make the output
+     * deterministic for testing — production callers must source them from a CSPRNG.
+     *
+     * `id` is `ECJPAKE_ID_CLIENT` for the joiner and `ECJPAKE_ID_SERVER` for the commissioner.
+     */
+    buildRound1(args: { x1: bigint; x2: bigint; v1: bigint; v2: bigint; id: string }): {
+        kp1: EcJpakeKeyKP;
+        kp2: EcJpakeKeyKP;
+    } {
+        const { x1, x2, v1, v2, id } = args;
+        const X1 = Point.BASE.multiply(x1).toBytes(false);
+        const X2 = Point.BASE.multiply(x2).toBytes(false);
+        const zkp1 = SchnorrZkp.generate({ privateKey: x1, publicKey: X1, ephemeral: v1, id });
+        const zkp2 = SchnorrZkp.generate({ privateKey: x2, publicKey: X2, ephemeral: v2, id });
+        return {
+            kp1: { X: X1, zkp: zkp1 },
+            kp2: { X: X2, zkp: zkp2 },
+        };
+    },
+
+    serializeRound1(kp1: EcJpakeKeyKP, kp2: EcJpakeKeyKP): Uint8Array {
+        validateKeyKP(kp1);
+        validateKeyKP(kp2);
+        const out = new Uint8Array(keyKpEncodedLength(kp1) + keyKpEncodedLength(kp2));
+        const after1 = writeKeyKP(kp1, out, 0);
+        writeKeyKP(kp2, out, after1);
+        return out;
+    },
+
+    parseRound1(bytes: Uint8Array): { kp1: EcJpakeKeyKP; kp2: EcJpakeKeyKP } {
+        const first = readKeyKP(bytes, 0);
+        const second = readKeyKP(bytes, first.nextOffset);
+        if (second.nextOffset !== bytes.length) {
+            throw new DtlsError(`trailing bytes after round-1 pair: ${bytes.length - second.nextOffset} extra`);
+        }
+        return { kp1: first.kp, kp2: second.kp };
+    },
+
+    /**
+     * Compute the round-2 composite generator `G' = Xp1 + Xp2 + Xm1` (mbedTLS
+     * `ecjpake_kkpp_write_round_two` / `ecjpake_kkpp_read_round_two`).
+     * Both sides use the same formula by symmetry — for the client `Xp1 = X3`,
+     * `Xp2 = X4`, `Xm1 = X1`; for the server `Xp1 = X1`, `Xp2 = X2`, `Xm1 = X3`.
+     */
+    composeRound2Generator(args: { Xp1: Uint8Array; Xp2: Uint8Array; Xm1: Uint8Array }): SchnorrZkpGenerator {
+        const point = Point.fromBytes(args.Xp1).add(Point.fromBytes(args.Xp2)).add(Point.fromBytes(args.Xm1));
+        if (point.is0()) {
+            throw new DtlsError("round-2 generator G' must not be the point at infinity");
+        }
+        return { point, bytes: point.toBytes(false) };
+    },
+
+    /**
+     * Build round 2 from the second private scalar `xm2`, the password (as the
+     * mbedTLS-style big-endian integer `s`), the composite generator `G'`, and a
+     * deterministic ephemeral `v`. Returns `Xm = (xm2 * s) * G'` plus a Schnorr
+     * ZKP proving knowledge of `xm = xm2 * s mod n` against `G'`.
+     *
+     * Caller-supplied `v` makes output deterministic for testing; production
+     * callers must source `v` from a CSPRNG.
+     */
+    buildRound2(args: { xm2: bigint; s: bigint; v: bigint; id: string; generator: SchnorrZkpGenerator }): EcJpakeKeyKP {
+        const { xm2, s, v, id, generator } = args;
+        if (xm2 <= 0n || xm2 >= N) {
+            throw new InternalError("xm2 must be in [1, n-1]");
+        }
+        if (s <= 0n) {
+            throw new InternalError("s (password as integer) must be positive");
+        }
+        const xm = (xm2 * s) % N;
+        if (xm === 0n) {
+            throw new InternalError("xm = xm2*s mod n must be non-zero");
+        }
+        const Xm = generator.point.multiply(xm);
+        const XmBytes = Xm.toBytes(false);
+        const zkp = SchnorrZkp.generate({
+            privateKey: xm,
+            publicKey: XmBytes,
+            ephemeral: v,
+            id,
+            generator,
+        });
+        return { X: XmBytes, zkp };
+    },
+
+    /**
+     * Serialise a round-2 message. When `prependEcParameters` is true the 3-byte
+     * `ECParameters{ named_curve, secp256r1 }` header is emitted before the
+     * `ECJPAKEKeyKP`. mbedTLS writes it inside `mbedtls_ecjpake_write_round_two`
+     * when role=SERVER (consumed by `ssl_write_server_key_exchange`).
+     * Server-side messages (ServerKeyExchange) use `true`; client-side
+     * (ClientKeyExchange) uses `false`.
+     */
+    serializeRound2(kp: EcJpakeKeyKP, options: { prependEcParameters: boolean }): Uint8Array {
+        validateKeyKP(kp);
+        const headerLen = options.prependEcParameters ? 3 : 0;
+        const out = new Uint8Array(headerLen + keyKpEncodedLength(kp));
+        let p = 0;
+        if (options.prependEcParameters) {
+            out[p++] = 0x03;
+            out[p++] = 0x00;
+            out[p++] = 0x17;
+        }
+        writeKeyKP(kp, out, p);
+        return out;
+    },
+
+    /**
+     * Parse a round-2 message. `expectEcParameters` must be `true` when the parser
+     * is the client reading ServerKeyExchange, and `false` when the parser is the
+     * server reading ClientKeyExchange.
+     */
+    parseRound2(bytes: Uint8Array, options: { expectEcParameters: boolean }): EcJpakeKeyKP {
+        let p = 0;
+        if (options.expectEcParameters) {
+            if (bytes.length < 3) {
+                throw new DtlsError("round-2 message too short for ECParameters header");
+            }
+            if (bytes[0] !== 0x03 || bytes[1] !== 0x00 || bytes[2] !== 0x17) {
+                throw new DtlsError(
+                    `expected ECParameters{named_curve, secp256r1} (03 00 17), got ${Array.from(bytes.subarray(0, 3))
+                        .map(b => b.toString(16).padStart(2, "0"))
+                        .join(" ")}`,
+                );
+            }
+            p = 3;
+        }
+        const { kp, nextOffset } = readKeyKP(bytes, p);
+        if (nextOffset !== bytes.length) {
+            throw new DtlsError(`trailing bytes after round-2 message: ${bytes.length - nextOffset} extra`);
+        }
+        return kp;
+    },
+
+    /**
+     * Verify the embedded round-2 ZKP under the supplied composite generator
+     * and the peer's `id` ("client" or "server"). Returns `false` (does not throw)
+     * on any verification failure — including malformed bytes — to mirror the
+     * round-1 `SchnorrZkp.verify` contract.
+     */
+    verifyRound2Zkp(args: { kp: EcJpakeKeyKP; generator: SchnorrZkpGenerator; peerId: string }): boolean {
+        const { kp, generator, peerId } = args;
+        return SchnorrZkp.verify({ zkp: kp.zkp, publicKey: kp.X, id: peerId, generator });
+    },
+} as const;

package/src/dtls/ecjpake/SchnorrZkp.ts

@@ -0,0 +1,193 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "@matter/general";
+import { p256 } from "@noble/curves/nist.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { DtlsError } from "../channel/DtlsChannel.js";
+
+/**
+ * Schnorr zero-knowledge proof of knowledge of `x` such that `X = x*G`,
+ * matching the EC-JPAKE wire shape used by mbedTLS v3.6.6 / draft-cragie-tls-ecjpake-01.
+ *
+ * Wire fields:
+ * - `V`: ephemeral commitment point `v*G`, SEC1 uncompressed (`0x04 || X || Y`, 65 bytes for P-256).
+ * - `r`: scalar response `v - h*x mod n`, minimal big-endian (leading zeros stripped).
+ *
+ * The `h` challenge is hashed over `len(G)||G || len(V)||V || len(X)||X || len(ID)||ID`,
+ * each `len` a 4-byte big-endian integer (mbedTLS `ecjpake_hash`, ecjpake.c v3.6.6 §190-238).
+ */
+export interface SchnorrZkp {
+    /** SEC1-uncompressed encoding of `V = v*G`. */
+    V: Uint8Array;
+    /** Minimal big-endian encoding of `r = v - h*x mod n`. */
+    r: Uint8Array;
+}
+
+const Point = p256.Point;
+const N = Point.Fn.ORDER;
+const POINT_LEN = 65;
+
+function be32(value: number): Uint8Array {
+    const out = new Uint8Array(4);
+    new DataView(out.buffer).setUint32(0, value, false);
+    return out;
+}
+
+function hashChallenge(args: {
+    gBytes: Uint8Array;
+    vBytes: Uint8Array;
+    xBytes: Uint8Array;
+    idBytes: Uint8Array;
+}): bigint {
+    const { gBytes, vBytes, xBytes, idBytes } = args;
+    const total = 4 + gBytes.length + 4 + vBytes.length + 4 + xBytes.length + 4 + idBytes.length;
+    const buf = new Uint8Array(total);
+    let p = 0;
+    buf.set(be32(gBytes.length), p);
+    p += 4;
+    buf.set(gBytes, p);
+    p += gBytes.length;
+    buf.set(be32(vBytes.length), p);
+    p += 4;
+    buf.set(vBytes, p);
+    p += vBytes.length;
+    buf.set(be32(xBytes.length), p);
+    p += 4;
+    buf.set(xBytes, p);
+    p += xBytes.length;
+    buf.set(be32(idBytes.length), p);
+    p += 4;
+    buf.set(idBytes, p);
+
+    const digest = sha256(buf);
+    let h = 0n;
+    for (const byte of digest) {
+        h = (h << 8n) | BigInt(byte);
+    }
+    return h % N;
+}
+
+function bigintToMinimalBE(value: bigint): Uint8Array {
+    if (value < 0n) {
+        throw new InternalError("Schnorr response scalar must be non-negative");
+    }
+    if (value === 0n) {
+        return new Uint8Array(0);
+    }
+    const tmp = new Array<number>();
+    let v = value;
+    while (v > 0n) {
+        tmp.push(Number(v & 0xffn));
+        v >>= 8n;
+    }
+    return Uint8Array.from(tmp.reverse());
+}
+
+function bigintFromBE(bytes: Uint8Array): bigint {
+    let v = 0n;
+    for (const byte of bytes) {
+        v = (v << 8n) | BigInt(byte);
+    }
+    return v;
+}
+
+function getBaseGBytes(): Uint8Array {
+    return Point.BASE.toBytes(false);
+}
+
+function pointFromBytes(bytes: Uint8Array): InstanceType<typeof Point> {
+    if (bytes.length !== POINT_LEN || bytes[0] !== 0x04) {
+        throw new DtlsError(
+            `expected SEC1-uncompressed P-256 point (65 bytes, 0x04 prefix), got len=${bytes.length} head=${bytes[0]}`,
+        );
+    }
+    return Point.fromBytes(bytes);
+}
+
+/**
+ * Optional generator override. When omitted the curve base point `G` is used,
+ * matching round-1 ZKPs. Round 2 passes a composite point (e.g. `X1 + X2 + X3`)
+ * and must supply both `point` (for arithmetic) and `bytes` (for the hash
+ * preimage, since mbedTLS hashes the SEC1-uncompressed encoding verbatim).
+ */
+export interface SchnorrZkpGenerator {
+    point: InstanceType<typeof Point>;
+    bytes: Uint8Array;
+}
+
+function generatorOrBase(g?: SchnorrZkpGenerator): SchnorrZkpGenerator {
+    if (g) {
+        if (g.bytes.length !== POINT_LEN || g.bytes[0] !== 0x04) {
+            throw new InternalError("generator bytes must be SEC1-uncompressed P-256 (65 bytes, 0x04 prefix)");
+        }
+        return g;
+    }
+    return { point: Point.BASE, bytes: getBaseGBytes() };
+}
+
+export const SchnorrZkp = {
+    /**
+     * Generate a Schnorr ZKP for `(x, X = x*G)`. `G` defaults to the curve generator;
+     * pass `generator` for the round-2 composite-generator case.
+     *
+     * The caller must supply both `x` and the SEC1 encoding of `X` to keep the call site
+     * identical to the verification path (no implicit recomputation).
+     *
+     * `ephemeral` is the per-proof scalar `v`; in production it must be sampled
+     * uniformly from `[1, n-1]`. Tests pass a fixed value so the proof is deterministic.
+     */
+    generate(args: {
+        privateKey: bigint;
+        publicKey: Uint8Array;
+        ephemeral: bigint;
+        id: string;
+        generator?: SchnorrZkpGenerator;
+    }): SchnorrZkp {
+        const { privateKey, publicKey, ephemeral, id } = args;
+        if (ephemeral <= 0n || ephemeral >= N) {
+            throw new InternalError("ephemeral scalar must be in [1, n-1]");
+        }
+        if (privateKey <= 0n || privateKey >= N) {
+            throw new InternalError("private key scalar must be in [1, n-1]");
+        }
+        const g = generatorOrBase(args.generator);
+        const V = g.point.multiply(ephemeral);
+        const vBytes = V.toBytes(false);
+        const idBytes = new TextEncoder().encode(id);
+        const h = hashChallenge({ gBytes: g.bytes, vBytes, xBytes: publicKey, idBytes });
+        // r = v - h*x mod n, matching mbedTLS ecjpake_zkp_write.
+        const rBig = (((ephemeral - ((h * privateKey) % N)) % N) + N) % N;
+        return { V: vBytes, r: bigintToMinimalBE(rBig) };
+    },
+
+    verify(args: { zkp: SchnorrZkp; publicKey: Uint8Array; id: string; generator?: SchnorrZkpGenerator }): boolean {
+        const { zkp, publicKey, id } = args;
+        const idBytes = new TextEncoder().encode(id);
+        let g: SchnorrZkpGenerator;
+        let V;
+        let X;
+        try {
+            g = generatorOrBase(args.generator);
+            V = pointFromBytes(zkp.V);
+            X = pointFromBytes(publicKey);
+        } catch {
+            return false;
+        }
+        if (V.is0() || X.is0()) {
+            return false;
+        }
+        const r = bigintFromBE(zkp.r);
+        if (r >= N) {
+            return false;
+        }
+        const h = hashChallenge({ gBytes: g.bytes, vBytes: zkp.V, xBytes: publicKey, idBytes });
+        // mbedTLS ecjpake_zkp_verify computes V' = r*G + h*X via ecp_muladd. multiplyUnsafe is
+        // safe here: r is on the wire (peer-supplied) and h is a hash digest; neither is secret.
+        const lhs = g.point.multiplyUnsafe(r).add(X.multiplyUnsafe(h));
+        return lhs.equals(V);
+    },
+} as const;

package/src/dtls/ecjpake/index.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Production EC-JPAKE crypto core (P-256 / draft-cragie-tls-ecjpake-01, mbedTLS-compatible).
+ *
+ * Hardening applied (Phase 3 sub-batch 1):
+ * - Constant-time scalar multiplication on password-derived secrets (`EcJpakePms.derive`
+ *   uses `Point.multiply`; `SchnorrZkp.verify` keeps `multiplyUnsafe` only on peer-supplied
+ *   `r` and the hash digest `h`, neither of which is secret).
+ * - Single pre-sized `Uint8Array` allocation in `EcJpakeRound.serializeRound1` /
+ *   `serializeRound2` (replaces ~330 `Array.push` calls per round-1 message).
+ * - Defensive copies on parse outputs: `EcJpakeRound.parseRound1` / `parseRound2` slice
+ *   the input so returned `Uint8Array`s own their backing buffer.
+ * - Hoisted participant identifiers `ECJPAKE_ID_CLIENT` / `ECJPAKE_ID_SERVER`.
+ *
+ * Constant-time guarantees rest on noble's `Point.multiply` implementation; if upstream
+ * drops that property, revisit `EcJpakePms.derive`.
+ *
+ * Internal to `dtls/`; not re-exported from the package public API surface.
+ */
+
+export { ECJPAKE_ID_CLIENT, ECJPAKE_ID_SERVER, EcJpakeRound } from "./EcJpakeRound.js";
+export type { EcJpakeKeyKP } from "./EcJpakeRound.js";
+export { SchnorrZkp } from "./SchnorrZkp.js";
+export type { SchnorrZkp as SchnorrZkpType } from "./SchnorrZkp.js";

package/src/dtls/handshake/ChangeCipherSpec.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { DtlsError } from "../channel/DtlsChannel.js";
+
+/**
+ * ChangeCipherSpec is *not* a handshake message — it sits at the record layer
+ * under its own ContentType (20) and consists of a single byte 0x01
+ * (RFC 5246 §7.1). The state machine wraps {@link CHANGE_CIPHER_SPEC_BODY}
+ * in a `DtlsRecord` with `type = ContentType.CHANGE_CIPHER_SPEC`, NOT in a
+ * handshake envelope, and the bytes do not feed the handshake-transcript
+ * hash (RFC 5246 §7.4.9).
+ *
+ * Kept as a shared 1-byte buffer so the state machine can pass it directly
+ * to `DtlsRecord.encode` without per-call allocation. (Typed arrays cannot
+ * be `Object.freeze`d while their element storage is live, so the readonly
+ * guarantee is type-only.)
+ */
+export const CHANGE_CIPHER_SPEC_BODY: Readonly<Uint8Array> = new Uint8Array([0x01]);
+
+export const ChangeCipherSpec = {
+    parse(body: Uint8Array): void {
+        if (body.length !== 1 || body[0] !== 0x01) {
+            throw new DtlsError(
+                `ChangeCipherSpec must be a single 0x01 byte, got len=${body.length} first=${body[0] ?? "undefined"}`,
+            );
+        }
+    },
+} as const;

package/src/dtls/handshake/ClientHelloMessage.ts

@@ -0,0 +1,150 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * DTLS 1.2 ClientHello body builder for `TLS_ECJPAKE_WITH_AES_128_CCM_8`
+ * (RFC 6347 §4.2.1, RFC 5246 §7.4.1.2). The shape is fixed:
+ *
+ * ```
+ * ProtocolVersion client_version    // 2 bytes = 0xfe 0xfd (DTLS 1.2)
+ * Random random                     // 32 bytes (caller-supplied)
+ * opaque session_id<0..32>          // length(1) || body — always empty for us
+ * opaque cookie<0..2^8-1>           // length(1) || body (DTLS-only, RFC 6347 §4.2.2)
+ * CipherSuite cipher_suites<2..>    // length(2) || N×2 bytes — exactly [0xC0, 0xFF]
+ * opaque compression<1..>           // length(1) || N bytes — exactly [0x00]
+ * Extension extensions<0..2^16-1>   // length(2) || extension entries
+ * ```
+ *
+ * Each Extension is `uint16 extension_type || opaque extension_data<0..2^16-1>`.
+ * Required extensions:
+ * - `ecjpake_kkpp` (0x0100, draft-cragie-tls-ecjpake-01) — round-1 ECJPAKEKeyKPPairList payload
+ * - `supported_groups` (0x000a, RFC 8422 §5.1.1) — peer requires this even though the cipher
+ *   suite hardcodes P-256, otherwise mbedtls rejects with "no common elliptic curve"
+ * - `ec_point_formats` (0x000b, RFC 8422 §5.1.2) — uncompressed-only; mbedtls is lenient if
+ *   omitted but real BRs may not be
+ */
+
+import { InternalError } from "@matter/general";
+
+/** TLS extension type for `ecjpake_kkpp` (draft-cragie-tls-ecjpake-01 §3). */
+export const EXTENSION_TYPE_ECJPAKE_KKPP = 0x0100;
+
+/** TLS extension type for `supported_groups` (RFC 8422 §5.1.1, formerly `elliptic_curves`). */
+export const EXTENSION_TYPE_SUPPORTED_GROUPS = 0x000a;
+
+/** TLS extension type for `ec_point_formats` (RFC 8422 §5.1.2). */
+export const EXTENSION_TYPE_EC_POINT_FORMATS = 0x000b;
+
+/** Named-curve identifier for `secp256r1` (P-256, RFC 8422 §5.1.1). */
+export const NAMED_CURVE_SECP256R1 = 0x0017;
+
+/** TLS cipher-suite identifier for `TLS_ECJPAKE_WITH_AES_128_CCM_8` (mbedTLS, experimental). */
+export const CIPHER_SUITE_ECJPAKE_WITH_AES_128_CCM_8 = 0xc0ff;
+
+const DTLS_1_2_MAJOR = 0xfe;
+const DTLS_1_2_MINOR = 0xfd;
+const RANDOM_LEN = 32;
+const COMPRESSION_NULL = 0x00;
+const MAX_COOKIE_LEN = 0xff;
+
+export interface ClientHelloFields {
+    /** 32 random bytes that will become `ClientHello.random`. */
+    random: Uint8Array;
+    /**
+     * DTLS cookie returned by `HelloVerifyRequest`, or empty on the first ClientHello
+     * (RFC 6347 §4.2.1).
+     */
+    cookie: Uint8Array;
+    /** `ecjpake_kkpp` extension payload — the round-1 ECJPAKEKeyKPPairList bytes. */
+    ecjpakeKkpp: Uint8Array;
+}
+
+function writeUint16BE(buf: Uint8Array, offset: number, value: number): void {
+    buf[offset] = (value >>> 8) & 0xff;
+    buf[offset + 1] = value & 0xff;
+}
+
+export const ClientHelloMessage = {
+    /**
+     * Serialise a ClientHello body. Caller wraps the result in a
+     * {@link HandshakeMessage} and a `DtlsRecord` of `ContentType.HANDSHAKE`.
+     */
+    build(fields: ClientHelloFields): Uint8Array {
+        const { random, cookie, ecjpakeKkpp } = fields;
+        if (random.length !== RANDOM_LEN) {
+            throw new InternalError(`ClientHello random must be ${RANDOM_LEN} bytes, got ${random.length}`);
+        }
+        if (cookie.length > MAX_COOKIE_LEN) {
+            throw new InternalError(`ClientHello cookie must be <= ${MAX_COOKIE_LEN} bytes, got ${cookie.length}`);
+        }
+        const ecjpakeExtLen = 2 + 2 + ecjpakeKkpp.length;
+        const supportedGroupsExtLen = 2 + 2 + 2 + 2; // header(4) + list_len(2) + secp256r1(2)
+        const ecPointFormatsExtLen = 2 + 2 + 1 + 1; // header(4) + list_len(1) + uncompressed(1)
+        const extEntryLen = ecjpakeExtLen + supportedGroupsExtLen + ecPointFormatsExtLen;
+        const extensionsBlockLen = 2 + extEntryLen;
+
+        const totalLen =
+            2 + // version
+            RANDOM_LEN +
+            1 + // session_id length (always 0)
+            1 +
+            cookie.length + // cookie length + body
+            2 +
+            2 + // cipher_suites length(2) + 2 bytes for the suite
+            1 +
+            1 + // compression length(1) + 1 byte (null)
+            extensionsBlockLen;
+
+        const out = new Uint8Array(totalLen);
+        let p = 0;
+        out[p++] = DTLS_1_2_MAJOR;
+        out[p++] = DTLS_1_2_MINOR;
+        out.set(random, p);
+        p += RANDOM_LEN;
+        out[p++] = 0; // session_id length, no body
+        out[p++] = cookie.length;
+        out.set(cookie, p);
+        p += cookie.length;
+        // cipher_suites: length=2, body=[0xC0, 0xFF]
+        writeUint16BE(out, p, 2);
+        p += 2;
+        out[p++] = (CIPHER_SUITE_ECJPAKE_WITH_AES_128_CCM_8 >>> 8) & 0xff;
+        out[p++] = CIPHER_SUITE_ECJPAKE_WITH_AES_128_CCM_8 & 0xff;
+        // compression_methods: length=1, body=[0x00]
+        out[p++] = 1;
+        out[p++] = COMPRESSION_NULL;
+        // extensions block
+        writeUint16BE(out, p, extEntryLen);
+        p += 2;
+        // ecjpake_kkpp
+        writeUint16BE(out, p, EXTENSION_TYPE_ECJPAKE_KKPP);
+        p += 2;
+        writeUint16BE(out, p, ecjpakeKkpp.length);
+        p += 2;
+        out.set(ecjpakeKkpp, p);
+        p += ecjpakeKkpp.length;
+        // supported_groups: list_len=2, [secp256r1]
+        writeUint16BE(out, p, EXTENSION_TYPE_SUPPORTED_GROUPS);
+        p += 2;
+        writeUint16BE(out, p, 4); // ext data: list_len(2) + 1 curve(2)
+        p += 2;
+        writeUint16BE(out, p, 2); // list_len = 2 bytes (one curve)
+        p += 2;
+        writeUint16BE(out, p, NAMED_CURVE_SECP256R1);
+        p += 2;
+        // ec_point_formats: list_len=1, [uncompressed=0x00]
+        writeUint16BE(out, p, EXTENSION_TYPE_EC_POINT_FORMATS);
+        p += 2;
+        writeUint16BE(out, p, 2); // ext data: list_len(1) + 1 format(1)
+        p += 2;
+        out[p++] = 1; // list_len = 1 byte (one format)
+        out[p++] = 0x00; // uncompressed
+        if (p !== totalLen) {
+            throw new InternalError(`ClientHello internal length mismatch: wrote ${p}, expected ${totalLen}`);
+        }
+        return out;
+    },
+} as const;