@matter/thread-br-client 0.0.1

package/src/dtls/record/AesCcm8.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "@matter/general";
+import { createCipheriv, createDecipheriv } from "node:crypto";
+import { DtlsError } from "../channel/DtlsChannel.js";
+
+const KEY_LEN = 16;
+const TAG_LEN = 8;
+
+/**
+ * AES-128-CCM with an 8-octet authentication tag, the AEAD primitive used by the
+ * `TLS_ECJPAKE_WITH_AES_128_CCM_8` cipher suite (RFC 6655 §3, RFC 3610).
+ *
+ * Wraps Node's `aes-128-ccm` with a fixed 8-byte tag length and returns
+ * `ciphertext || tag` to match the wire layout expected by the DTLS record layer.
+ *
+ * The 12-byte nonce length implies CCM L=3 (15 - 12), giving a 2^24 byte payload
+ * limit per record — well above the DTLS 16 KiB record cap.
+ */
+export namespace AesCcm8 {
+    export interface EncryptArgs {
+        key: Uint8Array;
+        nonce: Uint8Array;
+        aad: Uint8Array;
+        plaintext: Uint8Array;
+    }
+
+    export interface DecryptArgs {
+        key: Uint8Array;
+        nonce: Uint8Array;
+        aad: Uint8Array;
+        ciphertextWithTag: Uint8Array;
+    }
+
+    export function encrypt({ key, nonce, aad, plaintext }: EncryptArgs): Uint8Array {
+        if (key.length !== KEY_LEN) {
+            throw new InternalError(`AES-128-CCM-8 key must be ${KEY_LEN} bytes, got ${key.length}`);
+        }
+        const cipher = createCipheriv("aes-128-ccm", key, nonce, { authTagLength: TAG_LEN });
+        cipher.setAAD(aad, { plaintextLength: plaintext.length });
+        const body = cipher.update(plaintext);
+        const tail = cipher.final();
+        const tag = cipher.getAuthTag();
+
+        const out = new Uint8Array(plaintext.length + TAG_LEN);
+        out.set(body, 0);
+        if (tail.length > 0) {
+            out.set(tail, body.length);
+        }
+        out.set(tag, plaintext.length);
+        return out;
+    }
+
+    export function decrypt({ key, nonce, aad, ciphertextWithTag }: DecryptArgs): Uint8Array {
+        if (key.length !== KEY_LEN) {
+            throw new InternalError(`AES-128-CCM-8 key must be ${KEY_LEN} bytes, got ${key.length}`);
+        }
+        if (ciphertextWithTag.length < TAG_LEN) {
+            throw new DtlsError(`AES-128-CCM-8 input shorter than ${TAG_LEN}-byte tag`);
+        }
+        const ctLen = ciphertextWithTag.length - TAG_LEN;
+        const ct = ciphertextWithTag.subarray(0, ctLen);
+        const tag = ciphertextWithTag.subarray(ctLen);
+
+        const decipher = createDecipheriv("aes-128-ccm", key, nonce, { authTagLength: TAG_LEN });
+        decipher.setAAD(aad, { plaintextLength: ctLen });
+        decipher.setAuthTag(tag);
+        const body = decipher.update(ct);
+        // CCM .final() throws on tag mismatch; bubble up unchanged.
+        const tail = decipher.final();
+
+        const out = new Uint8Array(ctLen);
+        out.set(body, 0);
+        if (tail.length > 0) {
+            out.set(tail, body.length);
+        }
+        return out;
+    }
+}

package/src/dtls/record/AntiReplayWindow.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "@matter/general";
+
+const WINDOW_SIZE = 64n;
+const WINDOW_MASK = (1n << WINDOW_SIZE) - 1n;
+const MAX_SEQ = (1n << 48n) - 1n;
+
+/**
+ * DTLS 1.2 sliding-window anti-replay tracker (RFC 6347 §4.1.2.6).
+ *
+ * Maintains the rightmost (highest) accepted sequence number and a 64-bit
+ * bitmap of which prior numbers within the window have been seen. `check`
+ * combines the "is this in-window?" / "is this fresh?" / "mark as seen" steps
+ * into a single atomic update so callers can use it as a guard:
+ *
+ * ```ts
+ * if (!window.check(seqNum)) {
+ *   // discard or alert
+ * }
+ * ```
+ *
+ * Per the RFC, the window is initialised empty (no sequence numbers seen yet)
+ * and the first valid record sets the rightmost edge.
+ */
+export class AntiReplayWindow {
+    /** Highest sequence number observed so far, or `-1n` if none. */
+    #rightmost = -1n;
+    /**
+     * Bitmap of accepted sequence numbers in the closed range [rightmost-63, rightmost].
+     * Bit 0 represents `rightmost`, bit 1 represents `rightmost-1`, etc.
+     */
+    #window = 0n;
+
+    /** Window size as defined by RFC 6347 §4.1.2.6 (typically 32 or 64; we use 64). */
+    static readonly WINDOW_SIZE = Number(WINDOW_SIZE);
+
+    /** Highest sequence number recorded so far, or `-1n` before the first acceptance. */
+    get rightmost(): bigint {
+        return this.#rightmost;
+    }
+
+    /**
+     * Test+mark a sequence number. Returns `true` and records it on first sight,
+     * `false` if the number is a replay or older than the trailing edge.
+     *
+     * Throws on a negative or out-of-48-bit input — DTLS sequence numbers are
+     * 48-bit unsigned by construction; anything else is a programming error.
+     */
+    check(seqNum: bigint): boolean {
+        if (seqNum < 0n || seqNum > MAX_SEQ) {
+            throw new InternalError(`AntiReplayWindow: seqNum ${seqNum} out of 48-bit range`);
+        }
+
+        if (seqNum > this.#rightmost) {
+            // Slide the window forward by `shift` positions and record the new rightmost.
+            if (this.#rightmost >= 0n) {
+                const shift = seqNum - this.#rightmost;
+                if (shift >= WINDOW_SIZE) {
+                    this.#window = 1n;
+                } else {
+                    this.#window = ((this.#window << shift) | 1n) & WINDOW_MASK;
+                }
+            } else {
+                this.#window = 1n;
+            }
+            this.#rightmost = seqNum;
+            return true;
+        }
+
+        const offset = this.#rightmost - seqNum;
+        if (offset >= WINDOW_SIZE) {
+            // Older than the trailing edge — RFC 6347 mandates discard.
+            return false;
+        }
+        const bit = 1n << offset;
+        if ((this.#window & bit) !== 0n) {
+            return false;
+        }
+        this.#window |= bit;
+        return true;
+    }
+}

package/src/dtls/record/ContentType.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * DTLS 1.2 ContentType values (RFC 6347 §4.1, RFC 5246 §6.2.1).
+ * The four values listed below are the only ones we encode or accept on the wire;
+ * any other byte triggers a decode error.
+ */
+export const ContentType = {
+    CHANGE_CIPHER_SPEC: 20,
+    ALERT: 21,
+    HANDSHAKE: 22,
+    APPLICATION_DATA: 23,
+} as const;
+
+export type ContentType = (typeof ContentType)[keyof typeof ContentType];
+
+export function isContentType(value: number): value is ContentType {
+    return value === 20 || value === 21 || value === 22 || value === 23;
+}

package/src/dtls/record/DtlsCipherState.ts

@@ -0,0 +1,202 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "@matter/general";
+import { AntiReplayWindow } from "./AntiReplayWindow.js";
+import { ContentType } from "./ContentType.js";
+import { DTLS_1_2_VERSION, type DtlsRecordCipherState } from "./DtlsRecord.js";
+
+/**
+ * Materials a TLS 1.2 key block produces for `*_WITH_AES_128_CCM_8` (RFC 6655 §3,
+ * RFC 5246 §6.3): two AES-128 keys (`{client,server}_write_key`) and two 4-byte
+ * implicit-IV salts (`{client,server}_write_IV`). The PRF that derives them lands
+ * in sub-batch 4; sub-batch 2 only consumes the four byte arrays.
+ */
+export interface DtlsCipherStateInputs {
+    /** 16-byte AES key the client uses to encrypt outbound records. */
+    clientWriteKey: Uint8Array;
+    /** 16-byte AES key the server uses to encrypt outbound records. */
+    serverWriteKey: Uint8Array;
+    /** 4-byte client implicit-IV salt (`client_write_IV`). */
+    clientWriteSalt: Uint8Array;
+    /** 4-byte server implicit-IV salt (`server_write_IV`). */
+    serverWriteSalt: Uint8Array;
+}
+
+const KEY_LEN = 16;
+const SALT_LEN = 4;
+const NONCE_LEN = 12;
+const AAD_LEN = 13;
+const MAX_EPOCH = 0xffff;
+const MAX_SEQ = (1n << 48n) - 1n;
+
+function copyExpect(name: string, value: Uint8Array, expectedLen: number): Uint8Array {
+    if (value.length !== expectedLen) {
+        throw new InternalError(`DtlsCipherState ${name} must be ${expectedLen} bytes, got ${value.length}`);
+    }
+    return new Uint8Array(value);
+}
+
+/**
+ * Per-connection DTLS 1.2 record-layer cipher state for `TLS_ECJPAKE_WITH_AES_128_CCM_8`.
+ *
+ * Holds:
+ * - the four key-block byte arrays,
+ * - the local role (controls which write key/salt is used for encrypt vs decrypt),
+ * - per-direction epoch and sequence counters,
+ * - and a per-read-epoch {@link AntiReplayWindow} (RFC 6347 §4.1.2.6).
+ *
+ * Both epochs start at 0 (plaintext handshake records). After ChangeCipherSpec the
+ * sender bumps its own epoch and resets its sequence counter to 0; the handshake
+ * layer drives that via {@link advanceWriteEpoch} / {@link advanceReadEpoch}. The
+ * read window is allocated lazily for any epoch > 0 because plaintext records carry
+ * no AEAD tag and therefore cannot meaningfully participate in anti-replay.
+ */
+export class DtlsCipherState implements DtlsRecordCipherState {
+    readonly role: "client" | "server";
+    readonly #clientWriteKey: Uint8Array;
+    readonly #serverWriteKey: Uint8Array;
+    readonly #clientWriteSalt: Uint8Array;
+    readonly #serverWriteSalt: Uint8Array;
+    #writeEpoch = 0;
+    #writeSeq = 0n;
+    #readEpoch = 0;
+    #readWindow: AntiReplayWindow | undefined;
+
+    constructor(role: "client" | "server", inputs: DtlsCipherStateInputs) {
+        this.role = role;
+        this.#clientWriteKey = copyExpect("clientWriteKey", inputs.clientWriteKey, KEY_LEN);
+        this.#serverWriteKey = copyExpect("serverWriteKey", inputs.serverWriteKey, KEY_LEN);
+        this.#clientWriteSalt = copyExpect("clientWriteSalt", inputs.clientWriteSalt, SALT_LEN);
+        this.#serverWriteSalt = copyExpect("serverWriteSalt", inputs.serverWriteSalt, SALT_LEN);
+    }
+
+    get writeEpoch(): number {
+        return this.#writeEpoch;
+    }
+
+    get readEpoch(): number {
+        return this.#readEpoch;
+    }
+
+    /** Most recently allocated outbound seq, or `-1n` before the first allocation in the current epoch. */
+    get lastWriteSeq(): bigint {
+        return this.#writeSeq - 1n;
+    }
+
+    /**
+     * Allocate the next outbound sequence number for the current write epoch and bump
+     * the counter. Throws if the 48-bit space is exhausted within an epoch.
+     */
+    nextWriteSeq(): bigint {
+        if (this.#writeSeq > MAX_SEQ) {
+            throw new InternalError(
+                `DtlsCipherState write sequence_number space exhausted at epoch ${this.#writeEpoch}`,
+            );
+        }
+        const seq = this.#writeSeq;
+        this.#writeSeq += 1n;
+        return seq;
+    }
+
+    /**
+     * Increment the outbound epoch (called once after sending ChangeCipherSpec) and reset
+     * the seq counter to 0 (RFC 6347 §4.1.2.5).
+     */
+    advanceWriteEpoch(): void {
+        if (this.#writeEpoch >= MAX_EPOCH) {
+            throw new InternalError(`DtlsCipherState write epoch overflow`);
+        }
+        this.#writeEpoch += 1;
+        this.#writeSeq = 0n;
+    }
+
+    /**
+     * Increment the inbound epoch (called once after receiving ChangeCipherSpec) and
+     * reset the read-side anti-replay window for the new epoch.
+     */
+    advanceReadEpoch(): void {
+        if (this.#readEpoch >= MAX_EPOCH) {
+            throw new InternalError(`DtlsCipherState read epoch overflow`);
+        }
+        this.#readEpoch += 1;
+        this.#readWindow = new AntiReplayWindow();
+    }
+
+    /**
+     * Test+mark an inbound (epoch, seqNum) pair. Returns false on replay or wrong epoch
+     * so callers can drop the record per RFC 6347 §4.1.2.6. Plaintext epoch=0 records
+     * are accepted unconditionally — they carry no MAC and replay is meaningless.
+     */
+    acceptIncoming(epoch: number, seqNum: bigint): boolean {
+        if (epoch !== this.#readEpoch) {
+            return false;
+        }
+        if (epoch === 0) {
+            return true;
+        }
+        if (this.#readWindow === undefined) {
+            this.#readWindow = new AntiReplayWindow();
+        }
+        return this.#readWindow.check(seqNum);
+    }
+
+    encryptParams(): { key: Uint8Array; salt: Uint8Array } {
+        return this.role === "client"
+            ? { key: this.#clientWriteKey, salt: this.#clientWriteSalt }
+            : { key: this.#serverWriteKey, salt: this.#serverWriteSalt };
+    }
+
+    decryptParams(): { key: Uint8Array; salt: Uint8Array } {
+        return this.role === "client"
+            ? { key: this.#serverWriteKey, salt: this.#serverWriteSalt }
+            : { key: this.#clientWriteKey, salt: this.#clientWriteSalt };
+    }
+
+    nonceFor(salt: Uint8Array, epoch: number, seqNum: bigint): Uint8Array {
+        if (salt.length !== SALT_LEN) {
+            throw new InternalError(`DtlsCipherState nonceFor: salt must be ${SALT_LEN} bytes, got ${salt.length}`);
+        }
+        if (epoch < 0 || epoch > MAX_EPOCH) {
+            throw new InternalError(`DtlsCipherState nonceFor: epoch ${epoch} out of range`);
+        }
+        if (seqNum < 0n || seqNum > MAX_SEQ) {
+            throw new InternalError(`DtlsCipherState nonceFor: seqNum ${seqNum} out of range`);
+        }
+        const out = new Uint8Array(NONCE_LEN);
+        out.set(salt, 0);
+        out[4] = (epoch >>> 8) & 0xff;
+        out[5] = epoch & 0xff;
+        for (let i = 0; i < 6; i++) {
+            out[6 + i] = Number((seqNum >> BigInt((5 - i) * 8)) & 0xffn);
+        }
+        return out;
+    }
+
+    aadFor(type: ContentType, epoch: number, seqNum: bigint, plaintextLen: number): Uint8Array {
+        if (epoch < 0 || epoch > MAX_EPOCH) {
+            throw new InternalError(`DtlsCipherState aadFor: epoch ${epoch} out of range`);
+        }
+        if (seqNum < 0n || seqNum > MAX_SEQ) {
+            throw new InternalError(`DtlsCipherState aadFor: seqNum ${seqNum} out of range`);
+        }
+        if (plaintextLen < 0 || plaintextLen > 0xffff) {
+            throw new InternalError(`DtlsCipherState aadFor: plaintextLen ${plaintextLen} out of range`);
+        }
+        const out = new Uint8Array(AAD_LEN);
+        out[0] = (epoch >>> 8) & 0xff;
+        out[1] = epoch & 0xff;
+        for (let i = 0; i < 6; i++) {
+            out[2 + i] = Number((seqNum >> BigInt((5 - i) * 8)) & 0xffn);
+        }
+        out[8] = type;
+        out[9] = DTLS_1_2_VERSION.major;
+        out[10] = DTLS_1_2_VERSION.minor;
+        out[11] = (plaintextLen >>> 8) & 0xff;
+        out[12] = plaintextLen & 0xff;
+        return out;
+    }
+}

package/src/dtls/record/DtlsRecord.ts

@@ -0,0 +1,249 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError, MatterError } from "@matter/general";
+import { DtlsError } from "../channel/DtlsChannel.js";
+import { AesCcm8 } from "./AesCcm8.js";
+import { ContentType, isContentType } from "./ContentType.js";
+
+/**
+ * DTLS 1.2 protocol version on the wire is `{ major: 0xfe, minor: 0xfd }`,
+ * the 1's-complement convention TLS uses (RFC 6347 §4.1).
+ */
+export const DTLS_1_2_VERSION = Object.freeze({ major: 0xfe, minor: 0xfd });
+
+/** Maximum length of the DTLSCiphertext.fragment field (RFC 6347 §4.1). */
+export const DTLS_MAX_FRAGMENT_LEN = 1 << 14;
+
+/** 8-byte explicit AEAD nonce + 8-byte CCM-8 tag overhead per RFC 6655 §3. */
+export const DTLS_AEAD_OVERHEAD = 16;
+
+/** Length of the DTLS record header (RFC 6347 §4.1). */
+export const DTLS_HEADER_LEN = 13;
+
+/**
+ * Minimal cipher-state surface the record codec needs. The full {@link DtlsCipherState}
+ * class implements this and adds key-block bookkeeping; this interface lets the codec
+ * accept either the class or a stand-in test double without forcing a circular import.
+ *
+ * `acceptIncoming`, when present, is invoked after a successful AEAD decrypt to apply
+ * the RFC 6347 §4.1.2.6 anti-replay window. Returning `false` causes the codec to throw
+ * a {@link DtlsReplayError}.
+ */
+export interface DtlsRecordCipherState {
+    /** AES key + 4-byte salt to use for outbound (encrypt) records. */
+    encryptParams(): { key: Uint8Array; salt: Uint8Array };
+    /** AES key + 4-byte salt to use for inbound (decrypt) records. */
+    decryptParams(): { key: Uint8Array; salt: Uint8Array };
+    /** Build the 12-byte CCM nonce: salt(4) || epoch(2) || seq(6). */
+    nonceFor(salt: Uint8Array, epoch: number, seqNum: bigint): Uint8Array;
+    /** Build the 13-byte DTLS AAD: epoch||seq(8) || type(1) || version(2) || plaintextLen(2). */
+    aadFor(type: ContentType, epoch: number, seqNum: bigint, plaintextLen: number): Uint8Array;
+    /** Optional read-side replay-window check; absent on test doubles or pre-handshake states. */
+    acceptIncoming?(epoch: number, seqNum: bigint): boolean;
+}
+
+/**
+ * Thrown by {@link DtlsRecord.decode} when a successfully-decrypted record is rejected
+ * by the read-side anti-replay window. Distinguishable from AEAD failures so the caller
+ * can log/drop without treating the record as a fatal error.
+ */
+export class DtlsReplayError extends MatterError {
+    readonly epoch: number;
+    readonly sequenceNumber: bigint;
+
+    constructor(epoch: number, sequenceNumber: bigint) {
+        super(`DTLS replay or wrong-epoch record at epoch=${epoch} seq=${sequenceNumber}`);
+        this.name = "DtlsReplayError";
+        this.epoch = epoch;
+        this.sequenceNumber = sequenceNumber;
+    }
+}
+
+/**
+ * Decoded DTLS 1.2 record (RFC 6347 §4.1).
+ * `fragment` is always the *plaintext* payload — for epoch=0 records it is the wire bytes
+ * verbatim, for epoch>0 records it is the AEAD-decrypted body.
+ */
+export interface DtlsRecord {
+    type: ContentType;
+    epoch: number;
+    sequenceNumber: bigint;
+    fragment: Uint8Array;
+}
+
+const MAX_EPOCH = 0xffff;
+const MAX_SEQ = (1n << 48n) - 1n;
+
+function writeUint16BE(buf: Uint8Array, offset: number, value: number): void {
+    buf[offset] = (value >>> 8) & 0xff;
+    buf[offset + 1] = value & 0xff;
+}
+
+function readUint16BE(buf: Uint8Array, offset: number): number {
+    return (buf[offset] << 8) | buf[offset + 1];
+}
+
+function writeUint48BE(buf: Uint8Array, offset: number, value: bigint): void {
+    if (value < 0n || value > MAX_SEQ) {
+        throw new InternalError(`DTLS sequence_number out of range: ${value}`);
+    }
+    buf[offset] = Number((value >> 40n) & 0xffn);
+    buf[offset + 1] = Number((value >> 32n) & 0xffn);
+    buf[offset + 2] = Number((value >> 24n) & 0xffn);
+    buf[offset + 3] = Number((value >> 16n) & 0xffn);
+    buf[offset + 4] = Number((value >> 8n) & 0xffn);
+    buf[offset + 5] = Number(value & 0xffn);
+}
+
+function readUint48BE(buf: Uint8Array, offset: number): bigint {
+    let v = 0n;
+    for (let i = 0; i < 6; i++) {
+        v = (v << 8n) | BigInt(buf[offset + i]);
+    }
+    return v;
+}
+
+/**
+ * DTLS 1.2 record-layer codec.
+ *
+ * `encode` frames a record as `header(13) || fragment`; for `epoch > 0` the fragment is
+ * `explicit_nonce(8) || ciphertext(plaintext_len) || tag(8)` per RFC 6655 §3.
+ *
+ * `decode` parses one record off the front of the buffer and returns it together with
+ * the number of consumed bytes, so a caller can split multiple records concatenated in
+ * one UDP datagram. When the supplied state implements {@link DtlsRecordCipherState.acceptIncoming},
+ * decode invokes it after AEAD success and throws {@link DtlsReplayError} on rejection.
+ */
+export namespace DtlsRecord {
+    export function encode(record: DtlsRecord, state?: DtlsRecordCipherState): Uint8Array {
+        if (record.epoch < 0 || record.epoch > MAX_EPOCH) {
+            throw new InternalError(`DTLS epoch out of range: ${record.epoch}`);
+        }
+        if (record.sequenceNumber < 0n || record.sequenceNumber > MAX_SEQ) {
+            throw new InternalError(`DTLS sequence_number out of range: ${record.sequenceNumber}`);
+        }
+        if (!isContentType(record.type)) {
+            throw new InternalError(`DTLS unknown ContentType: ${record.type}`);
+        }
+
+        let fragment: Uint8Array;
+        if (record.epoch === 0) {
+            if (record.fragment.length > DTLS_MAX_FRAGMENT_LEN) {
+                throw new InternalError(
+                    `DTLS plaintext fragment too large: ${record.fragment.length} > ${DTLS_MAX_FRAGMENT_LEN}`,
+                );
+            }
+            fragment = record.fragment;
+        } else {
+            if (state === undefined) {
+                throw new InternalError(`DTLS encode at epoch ${record.epoch} requires cipher state`);
+            }
+            const plaintextLen = record.fragment.length;
+            if (plaintextLen + DTLS_AEAD_OVERHEAD > DTLS_MAX_FRAGMENT_LEN) {
+                throw new InternalError(
+                    `DTLS encrypted fragment too large: ${plaintextLen + DTLS_AEAD_OVERHEAD} > ${DTLS_MAX_FRAGMENT_LEN}`,
+                );
+            }
+            const { key, salt } = state.encryptParams();
+            const nonce = state.nonceFor(salt, record.epoch, record.sequenceNumber);
+            const aad = state.aadFor(record.type, record.epoch, record.sequenceNumber, plaintextLen);
+            const cipherWithTag = AesCcm8.encrypt({ key, nonce, aad, plaintext: record.fragment });
+
+            fragment = new Uint8Array(8 + cipherWithTag.length);
+            // Explicit nonce on the wire mirrors the (epoch || seq) bytes of the AAD/nonce.
+            fragment[0] = (record.epoch >>> 8) & 0xff;
+            fragment[1] = record.epoch & 0xff;
+            writeUint48BE(fragment, 2, record.sequenceNumber);
+            fragment.set(cipherWithTag, 8);
+        }
+
+        const out = new Uint8Array(DTLS_HEADER_LEN + fragment.length);
+        out[0] = record.type;
+        out[1] = DTLS_1_2_VERSION.major;
+        out[2] = DTLS_1_2_VERSION.minor;
+        writeUint16BE(out, 3, record.epoch);
+        writeUint48BE(out, 5, record.sequenceNumber);
+        writeUint16BE(out, 11, fragment.length);
+        out.set(fragment, DTLS_HEADER_LEN);
+        return out;
+    }
+
+    export interface DecodeResult {
+        record: DtlsRecord;
+        consumed: number;
+    }
+
+    export function decode(bytes: Uint8Array, state?: DtlsRecordCipherState): DecodeResult {
+        if (bytes.length < DTLS_HEADER_LEN) {
+            throw new DtlsError(`DTLS record header truncated: have ${bytes.length}, need ${DTLS_HEADER_LEN}`);
+        }
+        const type = bytes[0];
+        if (!isContentType(type)) {
+            throw new DtlsError(`DTLS unknown ContentType: ${type}`);
+        }
+        const major = bytes[1];
+        const minor = bytes[2];
+        if (major !== DTLS_1_2_VERSION.major || minor !== DTLS_1_2_VERSION.minor) {
+            throw new DtlsError(
+                `DTLS unsupported version ${major.toString(16)}.${minor.toString(16)}; only DTLS 1.2 is supported`,
+            );
+        }
+        const epoch = readUint16BE(bytes, 3);
+        const sequenceNumber = readUint48BE(bytes, 5);
+        const length = readUint16BE(bytes, 11);
+        if (length > DTLS_MAX_FRAGMENT_LEN) {
+            throw new DtlsError(`DTLS fragment length ${length} exceeds limit ${DTLS_MAX_FRAGMENT_LEN}`);
+        }
+        const total = DTLS_HEADER_LEN + length;
+        if (bytes.length < total) {
+            throw new DtlsError(`DTLS record truncated: header says ${length}, have ${bytes.length - DTLS_HEADER_LEN}`);
+        }
+
+        let fragment: Uint8Array;
+        if (epoch === 0) {
+            fragment = bytes.slice(DTLS_HEADER_LEN, total);
+        } else {
+            if (state === undefined) {
+                throw new InternalError(`DTLS decode at epoch ${epoch} requires cipher state`);
+            }
+            if (length < DTLS_AEAD_OVERHEAD) {
+                throw new DtlsError(
+                    `DTLS encrypted fragment ${length} bytes < ${DTLS_AEAD_OVERHEAD}-byte AEAD overhead`,
+                );
+            }
+            // Wire layout: explicit_nonce(8) || ciphertext(N) || tag(8); plaintext length is N.
+            const explicitNonce = bytes.subarray(DTLS_HEADER_LEN, DTLS_HEADER_LEN + 8);
+            const cipherWithTag = bytes.subarray(DTLS_HEADER_LEN + 8, total);
+            const plaintextLen = cipherWithTag.length - 8;
+
+            const { key, salt } = state.decryptParams();
+            const wireEpoch = (explicitNonce[0] << 8) | explicitNonce[1];
+            let wireSeq = 0n;
+            for (let i = 2; i < 8; i++) {
+                wireSeq = (wireSeq << 8n) | BigInt(explicitNonce[i]);
+            }
+            if (wireEpoch !== epoch || wireSeq !== sequenceNumber) {
+                throw new DtlsError(
+                    `DTLS explicit nonce ${wireEpoch}/${wireSeq} disagrees with header ${epoch}/${sequenceNumber}`,
+                );
+            }
+            const nonce = state.nonceFor(salt, epoch, sequenceNumber);
+            const aad = state.aadFor(type, epoch, sequenceNumber, plaintextLen);
+            fragment = AesCcm8.decrypt({ key, nonce, aad, ciphertextWithTag: cipherWithTag });
+            // Anti-replay applies only to AEAD-protected records; epoch=0 plaintext has
+            // no integrity check that a replay tracker could meaningfully gate.
+            if (state.acceptIncoming !== undefined && !state.acceptIncoming(epoch, sequenceNumber)) {
+                throw new DtlsReplayError(epoch, sequenceNumber);
+            }
+        }
+
+        return {
+            record: { type, epoch, sequenceNumber, fragment },
+            consumed: total,
+        };
+    }
+}

package/src/dtls/record/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * DTLS 1.2 record layer 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.
+ */
+
+export { AntiReplayWindow } from "./AntiReplayWindow.js";
+export { ContentType, isContentType } from "./ContentType.js";
+export { DtlsCipherState, type DtlsCipherStateInputs } from "./DtlsCipherState.js";
+export {
+    DTLS_1_2_VERSION,
+    DTLS_AEAD_OVERHEAD,
+    DTLS_HEADER_LEN,
+    DTLS_MAX_FRAGMENT_LEN,
+    DtlsRecord,
+    DtlsReplayError,
+    type DtlsRecordCipherState,
+} from "./DtlsRecord.js";
+// AesCcm8 is intentionally NOT exported — keep the AEAD primitive internal so the
+// only path to it is through DtlsRecord.encode/decode under a DtlsCipherState.