@matter/thread-br-client 0.0.1

package/src/crypto/Pskc.ts

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ImplementationError } from "@matter/general";
+import { pbkdf2AesCmac } from "./Pbkdf2AesCmac.js";
+
+const SALT_PREFIX = new TextEncoder().encode("Thread");
+const EXT_PAN_ID_LENGTH = 8;
+const NETWORK_NAME_MAX_BYTES = 16;
+const PASSPHRASE_MIN_BYTES = 6;
+const PASSPHRASE_MAX_BYTES = 255;
+// Thread spec §8.4 / openthread `meshcop.cpp::GeneratePskc`: 16384 PBKDF2 iterations.
+const ITERATIONS = 16384;
+const PSKC_LENGTH = 16;
+
+/**
+ * Thread MeshCoP PSKc derivation.
+ *
+ * Mirrors `openthread/src/core/meshcop/meshcop.cpp::GeneratePskc`. The salt
+ * concatenation order is `"Thread" || extPanId || networkName` — confirmed
+ * against the openthread main branch (the alternative `extPanId || "Thread"
+ * || networkName` ordering is wrong).
+ */
+export namespace Pskc {
+    export function derive(args: { passphrase: string; extPanId: Uint8Array; networkName: string }): Uint8Array {
+        const password = new TextEncoder().encode(args.passphrase);
+        if (password.length < PASSPHRASE_MIN_BYTES || password.length > PASSPHRASE_MAX_BYTES) {
+            throw new ImplementationError(
+                `passphrase UTF-8 length must be ${PASSPHRASE_MIN_BYTES}..${PASSPHRASE_MAX_BYTES} bytes, got ${password.length}`,
+            );
+        }
+        if (args.extPanId.length !== EXT_PAN_ID_LENGTH) {
+            throw new ImplementationError(`extPanId must be ${EXT_PAN_ID_LENGTH} bytes, got ${args.extPanId.length}`);
+        }
+        const networkNameBytes = new TextEncoder().encode(args.networkName);
+        if (networkNameBytes.length === 0 || networkNameBytes.length > NETWORK_NAME_MAX_BYTES) {
+            throw new ImplementationError(
+                `networkName UTF-8 length must be 1..${NETWORK_NAME_MAX_BYTES} bytes, got ${networkNameBytes.length}`,
+            );
+        }
+
+        const salt = new Uint8Array(SALT_PREFIX.length + EXT_PAN_ID_LENGTH + networkNameBytes.length);
+        salt.set(SALT_PREFIX, 0);
+        salt.set(args.extPanId, SALT_PREFIX.length);
+        salt.set(networkNameBytes, SALT_PREFIX.length + EXT_PAN_ID_LENGTH);
+
+        return pbkdf2AesCmac({
+            password,
+            salt,
+            iterations: ITERATIONS,
+            dkLen: PSKC_LENGTH,
+        });
+    }
+}

package/src/crypto/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export { AesCmac, AesCmacPrf128 } from "./AesCmacPrf128.js";
+export { pbkdf2AesCmac } from "./Pbkdf2AesCmac.js";
+export { Pskc } from "./Pskc.js";

package/src/dataset/OperationalDataset.ts

@@ -0,0 +1,326 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes } from "@matter/general";
+import { type BasicTlvEntry, BasicTlv } from "../tlv/BasicTlvCodec.js";
+import { ThreadDatasetError } from "./errors.js";
+import { MeshCopTlvType } from "./meshcopTlvTypes.js";
+import { SecurityPolicy } from "./SecurityPolicy.js";
+
+export { ThreadDatasetError } from "./errors.js";
+
+/**
+ * Decoded Thread Operational Dataset.
+ *
+ * Each named accessor mirrors a MeshCoP TLV defined in {@link MeshCopTlvType}.
+ * Unknown TLVs survive a decode/encode round-trip via {@link unknownTlvs}.
+ *
+ * Datasets returned by {@link OperationalDataset.decode} also carry hidden
+ * replay state so {@link OperationalDataset.encode} can reproduce the source
+ * bytes verbatim when no field has been mutated — preserving non-canonical
+ * encodings (legacy 1-byte CHANNEL forms, vendor-specific orderings) emitted
+ * by real Border Routers.
+ */
+export interface OperationalDataset {
+    channel?: number;
+    panId?: number;
+    extPanId?: Uint8Array;
+    networkName?: string;
+    pskc?: Uint8Array;
+    networkKey?: Uint8Array;
+    meshLocalPrefix?: Uint8Array;
+    securityPolicy?: SecurityPolicy;
+    activeTimestamp?: Uint8Array;
+    pendingTimestamp?: Uint8Array;
+    delayTimer?: number;
+    channelMask?: Uint8Array;
+    unknownTlvs: Array<{ type: number; value: Uint8Array }>;
+    raw: Uint8Array;
+}
+
+export namespace OperationalDataset {
+    /**
+     * Decodes a Thread Operational Dataset from either raw bytes or a hex string.
+     *
+     * Accepts a whitespace-tolerant hex string (whitespace is stripped before
+     * parsing) or pre-parsed `Bytes` (e.g. a `Uint8Array`) of MeshCoP TLV bytes. Unknown TLVs survive the
+     * round-trip via {@link OperationalDataset.unknownTlvs}. Throws on malformed
+     * input (bad hex or TLV structure violations).
+     */
+    export function decode(input: Bytes | string): OperationalDataset {
+        const blob = typeof input === "string" ? Bytes.of(Bytes.fromHex(input.replace(/\s+/g, ""))) : Bytes.of(input);
+        const entries = BasicTlv.walk(blob);
+        const unknownTlvs = new Array<{ type: number; value: Uint8Array }>();
+        const originalTlvs = entries.map(e => ({ type: e.type, value: e.value.slice() }));
+        const ds: OperationalDataset = {
+            unknownTlvs,
+            raw: blob.slice(),
+        };
+        ORIGINAL_TLVS.set(ds, originalTlvs);
+
+        for (const entry of entries) {
+            applyKnownTlvToDataset(ds, entry, unknownTlvs);
+        }
+
+        return ds;
+    }
+
+    /**
+     * Encode a Thread Operational Dataset to MeshCoP TLV bytes.
+     *
+     * Datasets produced by {@link decode} are re-encoded with replay fidelity:
+     * unmodified known TLVs reproduce their original bytes (preserving non-canonical
+     * encodings from real Border Routers), while mutated fields are re-encoded
+     * canonically. Datasets constructed directly (without a prior `decode`) are
+     * always encoded in canonical form.
+     *
+     * @param ds - Dataset to encode; may be a decoded or manually constructed object.
+     * @returns MeshCoP TLV byte sequence.
+     */
+    export function encode(ds: OperationalDataset): Uint8Array {
+        const originals = ORIGINAL_TLVS.get(ds);
+        if (originals !== undefined) {
+            return encodeWithReplay(ds, originals);
+        }
+        return BasicTlv.encode(canonicalEntries(ds));
+    }
+
+    /**
+     * Return a copy of the dataset with `pskc` and `networkKey` cleared.
+     *
+     * Safe to log or expose via the public API — secret material is removed
+     * while all other fields (channel, network name, timestamps, etc.) are retained.
+     *
+     * @param ds - Source dataset; not mutated.
+     * @returns Shallow copy with secret fields set to `undefined`.
+     */
+    export function redact(ds: OperationalDataset): OperationalDataset {
+        return { ...ds, pskc: undefined, networkKey: undefined };
+    }
+}
+
+/**
+ * Replay state for {@link OperationalDataset.encode}. Held off-interface so the
+ * public type stays a plain dataset shape; the entry is reclaimed automatically
+ * when the dataset is garbage-collected.
+ */
+const ORIGINAL_TLVS = new WeakMap<OperationalDataset, ReadonlyArray<BasicTlvEntry>>();
+
+function applyKnownTlvToDataset(
+    ds: OperationalDataset,
+    entry: BasicTlvEntry,
+    unknownTlvs: Array<{ type: number; value: Uint8Array }>,
+): void {
+    switch (entry.type) {
+        case MeshCopTlvType.CHANNEL:
+            ds.channel = decodeChannel(entry.value);
+            break;
+        case MeshCopTlvType.PANID:
+            if (entry.value.length !== 2) {
+                throw new ThreadDatasetError(`PANID TLV must be 2 bytes, got ${entry.value.length}`);
+            }
+            ds.panId = (entry.value[0] << 8) | entry.value[1];
+            break;
+        case MeshCopTlvType.EXTPANID:
+            if (entry.value.length !== 8) {
+                throw new ThreadDatasetError(`EXTPANID TLV must be 8 bytes, got ${entry.value.length}`);
+            }
+            ds.extPanId = entry.value.slice();
+            break;
+        case MeshCopTlvType.NETWORK_NAME:
+            ds.networkName = new TextDecoder("utf-8").decode(entry.value);
+            break;
+        case MeshCopTlvType.PSKC:
+            ds.pskc = entry.value.slice();
+            break;
+        case MeshCopTlvType.NETWORK_KEY:
+            if (entry.value.length !== 16) {
+                throw new ThreadDatasetError(`NETWORK_KEY TLV must be 16 bytes, got ${entry.value.length}`);
+            }
+            ds.networkKey = entry.value.slice();
+            break;
+        case MeshCopTlvType.MESH_LOCAL_PREFIX:
+            if (entry.value.length !== 8) {
+                throw new ThreadDatasetError(`MESH_LOCAL_PREFIX TLV must be 8 bytes, got ${entry.value.length}`);
+            }
+            ds.meshLocalPrefix = entry.value.slice();
+            break;
+        case MeshCopTlvType.SECURITY_POLICY:
+            ds.securityPolicy = SecurityPolicy.decode(entry.value);
+            break;
+        case MeshCopTlvType.ACTIVE_TIMESTAMP:
+            if (entry.value.length !== 8) {
+                throw new ThreadDatasetError(`ACTIVE_TIMESTAMP TLV must be 8 bytes, got ${entry.value.length}`);
+            }
+            ds.activeTimestamp = entry.value.slice();
+            break;
+        case MeshCopTlvType.PENDING_TIMESTAMP:
+            if (entry.value.length !== 8) {
+                throw new ThreadDatasetError(`PENDING_TIMESTAMP TLV must be 8 bytes, got ${entry.value.length}`);
+            }
+            ds.pendingTimestamp = entry.value.slice();
+            break;
+        case MeshCopTlvType.DELAY_TIMER:
+            if (entry.value.length !== 4) {
+                throw new ThreadDatasetError(`DELAY_TIMER TLV must be 4 bytes, got ${entry.value.length}`);
+            }
+            ds.delayTimer = (entry.value[0] << 24) | (entry.value[1] << 16) | (entry.value[2] << 8) | entry.value[3];
+            break;
+        case MeshCopTlvType.CHANNEL_MASK:
+            ds.channelMask = entry.value.slice();
+            break;
+        default:
+            unknownTlvs.push({ type: entry.type, value: entry.value.slice() });
+            break;
+    }
+}
+
+function encodeWithReplay(ds: OperationalDataset, originals: ReadonlyArray<BasicTlvEntry>): Uint8Array {
+    const seenKnownTypes = new Set<number>();
+    const unknownCursor = new Map<number, number>();
+    const out = new Array<BasicTlvEntry>();
+    const scratch: OperationalDataset = { unknownTlvs: [], raw: EMPTY_BYTES };
+
+    for (const original of originals) {
+        const known = KNOWN_TLV_HANDLERS.get(original.type);
+        if (known !== undefined) {
+            seenKnownTypes.add(original.type);
+            const canonical = known.encodeCurrent(ds);
+            if (canonical === undefined) continue;
+            // Compare named values rather than bytes so non-canonical encodings (e.g. the
+            // legacy 1-byte CHANNEL form) replay unchanged when the caller hasn't mutated.
+            applyKnownTlvToDataset(scratch, original, scratch.unknownTlvs);
+            if (known.equalsCurrent(ds, scratch)) {
+                out.push({ type: original.type, value: original.value });
+            } else {
+                out.push({ type: original.type, value: canonical });
+            }
+            continue;
+        }
+        const start = unknownCursor.get(original.type) ?? 0;
+        const matchIdx = ds.unknownTlvs.findIndex(
+            (u, i) => i >= start && u.type === original.type && Bytes.areEqual(u.value, original.value),
+        );
+        if (matchIdx === -1) continue;
+        unknownCursor.set(original.type, matchIdx + 1);
+        out.push({ type: original.type, value: original.value });
+    }
+
+    for (const known of KNOWN_TLV_HANDLERS.values()) {
+        if (seenKnownTypes.has(known.type)) continue;
+        const canonical = known.encodeCurrent(ds);
+        if (canonical === undefined) continue;
+        out.push({ type: known.type, value: canonical });
+    }
+
+    return BasicTlv.encode(out);
+}
+
+const EMPTY_BYTES = new Uint8Array();
+
+function canonicalEntries(ds: OperationalDataset): BasicTlvEntry[] {
+    const out = new Array<BasicTlvEntry>();
+    for (const known of KNOWN_TLV_HANDLERS.values()) {
+        const canonical = known.encodeCurrent(ds);
+        if (canonical === undefined) continue;
+        out.push({ type: known.type, value: canonical });
+    }
+    for (const u of ds.unknownTlvs) {
+        out.push({ type: u.type, value: u.value.slice() });
+    }
+    return out;
+}
+
+/**
+ * Each handler erases its field type behind a closure so the heterogeneous
+ * registry can live in a single Map without per-field casts at the call site.
+ */
+interface KnownTlvHandler {
+    type: number;
+    /** Returns the canonical encoding of the named accessor, or undefined when unset. */
+    encodeCurrent(ds: OperationalDataset): Uint8Array | undefined;
+    /** Whether ds[field] structurally equals other[field]. Used for replay decisions. */
+    equalsCurrent(ds: OperationalDataset, other: OperationalDataset): boolean;
+}
+
+function handler<K extends keyof OperationalDataset>(
+    type: number,
+    field: K,
+    encodeValue: (value: OperationalDataset[K] & {}) => Uint8Array,
+    equals: (a: OperationalDataset[K] & {}, b: OperationalDataset[K] & {}) => boolean,
+): KnownTlvHandler {
+    return {
+        type,
+        encodeCurrent(ds) {
+            const value = ds[field];
+            if (value === undefined) return undefined;
+            return encodeValue(value);
+        },
+        equalsCurrent(ds, other) {
+            const a = ds[field];
+            const b = other[field];
+            if (a === undefined || b === undefined) return a === b;
+            return equals(a, b);
+        },
+    };
+}
+
+const eqNumber = (a: number, b: number): boolean => a === b;
+const eqString = (a: string, b: string): boolean => a === b;
+const eqBytes = (a: Uint8Array, b: Uint8Array): boolean => Bytes.areEqual(a, b);
+const eqSecurityPolicy = (a: SecurityPolicy, b: SecurityPolicy): boolean =>
+    a.rotationTime === b.rotationTime && a.flags === b.flags;
+
+const KNOWN_TLV_HANDLERS: Map<number, KnownTlvHandler> = (() => {
+    const list: KnownTlvHandler[] = [
+        handler(
+            MeshCopTlvType.CHANNEL,
+            "channel",
+            value => new Uint8Array([0x00, (value >> 8) & 0xff, value & 0xff]),
+            eqNumber,
+        ),
+        handler(MeshCopTlvType.PANID, "panId", value => new Uint8Array([(value >> 8) & 0xff, value & 0xff]), eqNumber),
+        handler(MeshCopTlvType.EXTPANID, "extPanId", value => value, eqBytes),
+        handler(MeshCopTlvType.NETWORK_NAME, "networkName", value => new TextEncoder().encode(value), eqString),
+        handler(MeshCopTlvType.PSKC, "pskc", value => value, eqBytes),
+        handler(MeshCopTlvType.NETWORK_KEY, "networkKey", value => value, eqBytes),
+        handler(MeshCopTlvType.MESH_LOCAL_PREFIX, "meshLocalPrefix", value => value, eqBytes),
+        handler(
+            MeshCopTlvType.SECURITY_POLICY,
+            "securityPolicy",
+            value => SecurityPolicy.encode(value),
+            eqSecurityPolicy,
+        ),
+        handler(MeshCopTlvType.ACTIVE_TIMESTAMP, "activeTimestamp", value => value, eqBytes),
+        handler(MeshCopTlvType.PENDING_TIMESTAMP, "pendingTimestamp", value => value, eqBytes),
+        handler(
+            MeshCopTlvType.DELAY_TIMER,
+            "delayTimer",
+            value => new Uint8Array([(value >> 24) & 0xff, (value >> 16) & 0xff, (value >> 8) & 0xff, value & 0xff]),
+            eqNumber,
+        ),
+        handler(MeshCopTlvType.CHANNEL_MASK, "channelMask", value => value, eqBytes),
+    ];
+    list.sort((a, b) => a.type - b.type);
+    const map = new Map<number, KnownTlvHandler>();
+    for (const h of list) map.set(h.type, h);
+    return map;
+})();
+
+/**
+ * Real-world OpenThread datasets sometimes encode CHANNEL as a single byte
+ * (the channel number directly) instead of the spec-conformant 3-byte form
+ * (channel-page:1 + channel:2). Both forms are accepted on decode.
+ */
+function decodeChannel(value: Uint8Array): number {
+    if (value.length === 1) {
+        return value[0];
+    }
+    if (value.length === 3) {
+        return (value[1] << 8) | value[2];
+    }
+    throw new ThreadDatasetError(`CHANNEL TLV must be 1 or 3 bytes, got ${value.length}`);
+}

package/src/dataset/SecurityPolicy.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ImplementationError } from "@matter/general";
+import { ThreadDatasetError } from "./errors.js";
+
+/**
+ * MeshCoP Security Policy TLV (type 12) is a fixed 4-byte payload: 2-byte
+ * big-endian rotation time (hours) followed by 2 bytes of policy flags.
+ *
+ * Flag bits track the version-dependent layout in Thread spec §8.10.1.15;
+ * we expose the raw 16-bit value so callers can interpret bits as needed
+ * without locking the codec to a particular Thread revision.
+ */
+export interface SecurityPolicy {
+    rotationTime: number;
+    flags: number;
+}
+
+export namespace SecurityPolicy {
+    export function decode(value: Uint8Array): SecurityPolicy {
+        if (value.length !== 4) {
+            throw new ThreadDatasetError(`Security policy must be 4 bytes, got ${value.length}`);
+        }
+        return {
+            rotationTime: (value[0] << 8) | value[1],
+            flags: (value[2] << 8) | value[3],
+        };
+    }
+
+    export function encode(policy: SecurityPolicy): Uint8Array {
+        if (policy.rotationTime < 0 || policy.rotationTime > 0xffff) {
+            throw new ImplementationError(`Security policy rotationTime out of range: ${policy.rotationTime}`);
+        }
+        if (policy.flags < 0 || policy.flags > 0xffff) {
+            throw new ImplementationError(`Security policy flags out of range: ${policy.flags}`);
+        }
+        return new Uint8Array([
+            (policy.rotationTime >> 8) & 0xff,
+            policy.rotationTime & 0xff,
+            (policy.flags >> 8) & 0xff,
+            policy.flags & 0xff,
+        ]);
+    }
+}

package/src/dataset/errors.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MatterError } from "@matter/general";
+
+/** Thrown when a Thread Operational Dataset cannot be decoded from malformed MeshCoP TLV bytes. */
+export class ThreadDatasetError extends MatterError {}

package/src/dataset/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export { MeshCopTlvType, MeshCopTlvTypeName } from "./meshcopTlvTypes.js";
+export { OperationalDataset, ThreadDatasetError } from "./OperationalDataset.js";
+export { SecurityPolicy } from "./SecurityPolicy.js";

package/src/dataset/meshcopTlvTypes.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * MeshCoP TLV type identifiers (Thread 1.4 spec §8.10 plus the Agners' Python
+ * reference parser https://gist.github.com/agners/0338576e0003318b63ec1ea75adc90f9).
+ *
+ * Used to decode operational dataset blobs and to drive both the named-accessor
+ * mapping and reverse lookup for diagnostics.
+ */
+export const MeshCopTlvType = {
+    CHANNEL: 0,
+    PANID: 1,
+    EXTPANID: 2,
+    NETWORK_NAME: 3,
+    PSKC: 4,
+    NETWORK_KEY: 5,
+    NETWORK_KEY_SEQUENCE: 6,
+    MESH_LOCAL_PREFIX: 7,
+    STEERING_DATA: 8,
+    BORDER_AGENT_LOCATOR: 9,
+    COMMISSIONER_ID: 10,
+    COMMISSIONER_SESSION_ID: 11,
+    SECURITY_POLICY: 12,
+    GET: 13,
+    ACTIVE_TIMESTAMP: 14,
+    COMMISSIONER_UDP_PORT: 15,
+    STATE: 16,
+    JOINER_DTLS_ENCAPSULATION: 17,
+    JOINER_UDP_PORT: 18,
+    JOINER_IID: 19,
+    JOINER_ROUTER_LOCATOR: 20,
+    JOINER_ROUTER_KEK: 21,
+    DURATION: 23,
+    PROVISIONING_URL: 32,
+    VENDOR_NAME: 33,
+    VENDOR_MODEL: 34,
+    VENDOR_SW_VERSION: 35,
+    VENDOR_DATA: 36,
+    VENDOR_STACK_VERSION: 37,
+    UDP_ENCAPSULATION: 48,
+    IPV6_ADDRESS: 49,
+    PENDING_TIMESTAMP: 51,
+    DELAY_TIMER: 52,
+    CHANNEL_MASK: 53,
+    COUNT: 54,
+    PERIOD: 55,
+    SCAN_DURATION: 56,
+    ENERGY_LIST: 57,
+    THREAD_DOMAIN_NAME: 59,
+    WAKEUP_CHANNEL: 74,
+    DISCOVERY_REQUEST: 128,
+    DISCOVERY_RESPONSE: 129,
+    JOINER_ADVERTISEMENT: 241,
+} as const;
+
+export type MeshCopTlvTypeKey = keyof typeof MeshCopTlvType;
+export type MeshCopTlvTypeValue = (typeof MeshCopTlvType)[MeshCopTlvTypeKey];
+
+export const MeshCopTlvTypeName: Record<number, MeshCopTlvTypeKey> = (() => {
+    const out: Record<number, MeshCopTlvTypeKey> = {};
+    for (const [key, value] of Object.entries(MeshCopTlvType) as Array<[MeshCopTlvTypeKey, MeshCopTlvTypeValue]>) {
+        out[value] = key;
+    }
+    return out;
+})();

package/src/diagnostic/DefaultTlvSet.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { NetworkDiagTlvType } from "../tlv/networkDiagTlvTypes.js";
+
+/** Default diagnostic TLV set: spec §4.9 core topology + identity + health (counters, power, firmware). */
+export const DefaultTlvSet: ReadonlyArray<number> = [
+    NetworkDiagTlvType.EXT_MAC_ADDRESS,
+    NetworkDiagTlvType.ADDRESS16,
+    NetworkDiagTlvType.MODE,
+    NetworkDiagTlvType.CONNECTIVITY,
+    NetworkDiagTlvType.ROUTE64,
+    NetworkDiagTlvType.LEADER_DATA,
+    NetworkDiagTlvType.IPV6_ADDRESS_LIST,
+    NetworkDiagTlvType.CHILD_TABLE,
+    NetworkDiagTlvType.VERSION,
+    NetworkDiagTlvType.VENDOR_NAME,
+    NetworkDiagTlvType.VENDOR_MODEL,
+    NetworkDiagTlvType.VENDOR_SW_VERSION,
+    NetworkDiagTlvType.TIMEOUT,
+    NetworkDiagTlvType.MAC_COUNTERS,
+    NetworkDiagTlvType.MLE_COUNTERS,
+    NetworkDiagTlvType.BATTERY_LEVEL,
+    NetworkDiagTlvType.SUPPLY_VOLTAGE,
+    NetworkDiagTlvType.MAX_CHILD_TIMEOUT,
+    NetworkDiagTlvType.EUI64,
+    NetworkDiagTlvType.THREAD_STACK_VERSION,
+];

package/src/diagnostic/DiagnosticResponse.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ChildIpv6Addresses } from "../tlv/diag/ChildIpv6AddressList.js";
+import type { ChildTableEntry } from "../tlv/diag/ChildTable.js";
+import type { Connectivity } from "../tlv/diag/Connectivity.js";
+import type { LeaderData } from "../tlv/diag/LeaderData.js";
+import type { MacCounters } from "../tlv/diag/MacCounters.js";
+import type { MleCounters } from "../tlv/diag/MleCounters.js";
+import type { Mode } from "../tlv/diag/Mode.js";
+import type { ThreadNetworkData } from "../tlv/diag/NetworkData.js";
+import type { Route64 } from "../tlv/diag/Route64.js";
+import type { RouterNeighborEntry } from "../tlv/diag/RouterNeighbor.js";
+
+export interface DiagnosticResponse {
+    extMacAddress?: Uint8Array;
+    rloc16?: number;
+    mode?: Mode;
+    timeout?: number;
+    connectivity?: Connectivity;
+    route64?: Route64;
+    leaderData?: LeaderData;
+    networkData?: ThreadNetworkData;
+    ipv6Addresses?: Uint8Array[];
+    macCounters?: MacCounters;
+    batteryLevel?: number;
+    supplyVoltage?: number;
+    childTable?: ChildTableEntry[];
+    childIpv6Addresses?: ChildIpv6Addresses;
+    routerNeighbors?: RouterNeighborEntry[];
+    channelPages?: number[];
+    maxChildTimeout?: number;
+    eui64?: Uint8Array;
+    version?: number;
+    vendorName?: string;
+    vendorModel?: string;
+    vendorSwVersion?: string;
+    threadStackVersion?: string;
+    vendorAppUrl?: string;
+    mleCounters?: MleCounters;
+    unknown: Array<{ type: number; value: Uint8Array }>;
+}

package/src/diagnostic/DiagnosticSource.ts

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Observable } from "@matter/general";
+import { NetworkDiagTlvType } from "../tlv/networkDiagTlvTypes.js";
+import type { DiagnosticResponse } from "./DiagnosticResponse.js";
+
+export interface QueryMulticastOptions {
+    tlvTypes: number[];
+    /** Total window during which responses are accepted. Default 20_000 ms. */
+    windowMs?: number;
+}
+
+/** Default TLV types zeroed by {@link DiagnosticSource.resetCounters} when none are specified. */
+export const DEFAULT_RESET_TLV_TYPES: ReadonlyArray<number> = [
+    NetworkDiagTlvType.MAC_COUNTERS,
+    NetworkDiagTlvType.MLE_COUNTERS,
+];
+
+/**
+ * Live handle for a streaming multicast diagnostic query.
+ *
+ * Implementations emit one `onNode` event per decoded response and resolve
+ * `done` once the collection window closes (or `close()` is called). The
+ * consumer is free to act on each arrival immediately and may accumulate a
+ * snapshot at any time.
+ */
+export interface QueryMulticastHandle {
+    /** Fired once per parsed `DiagnosticResponse`. */
+    readonly onNode: Observable<[DiagnosticResponse]>;
+    /** Transport-level errors that did not abort the handle (e.g. one decode failure). */
+    readonly onError: Observable<[Error]>;
+    /** Resolves when the window has fully elapsed or `close()` completed. */
+    readonly done: Promise<void>;
+    /** Tear down the underlying listener/DTLS session early. Idempotent. */
+    close(): Promise<void>;
+}
+
+export interface DiagnosticSource {
+    readonly kind: "meshcop" | "otbr-rest";
+    canQuery(extPanId: Uint8Array): boolean;
+    queryUnicast(target: { rloc16?: number; ip?: string }, tlvTypes: number[]): Promise<DiagnosticResponse>;
+    /**
+     * Issue a multicast diagnostic query (DIAG_GET for MeshCoP, /diagnostics
+     * snapshot for REST) and stream parsed responses through the returned
+     * handle. The handle remains open for `opts.windowMs` (default 20_000)
+     * unless closed explicitly.
+     */
+    queryMulticast(scope: "ff03::1" | "ff03::2", opts: QueryMulticastOptions): QueryMulticastHandle;
+    /**
+     * Zero MAC and MLE counters on a single mesh node (MGMT_DIAG_RESET).
+     *
+     * Sends a DIAG_RESET command to the target node. Only counter TLV types
+     * are meaningful here; non-counter types in `tlvTypes` are passed through
+     * unchanged and the node will ignore them. Mutating but low-risk —
+     * counters only, no network state is altered.
+     *
+     * @param target - Node to reset. `rloc16` is required for both sources.
+     * @param tlvTypes - TLV type IDs to include in the TypeList. Defaults to
+     *   `[MAC_COUNTERS, MLE_COUNTERS]` (types 9 and 34).
+     */
+    resetCounters(target: { rloc16?: number; ip?: string }, tlvTypes?: ReadonlyArray<number>): Promise<void>;
+}