@matter/thread-br-client 0.0.1

package/src/otbr-rest/translation.ts

@@ -0,0 +1,344 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes } from "@matter/general";
+import type { DiagnosticResponse } from "../diagnostic/DiagnosticResponse.js";
+import type { ChildTableEntry } from "../tlv/diag/ChildTable.js";
+import type { Connectivity, ParentPriority } 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 { NetworkData } from "../tlv/diag/NetworkData.js";
+import type { Route64, Route64Entry } from "../tlv/diag/Route64.js";
+import { OtbrRestError } from "./OtbrRestError.js";
+
+const TIMEOUT_EXP_MIN = 4;
+const IPV6_BYTES = 16;
+const IPV6_GROUPS = 8;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function asNumber(value: unknown): number | undefined {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function asString(value: unknown): string | undefined {
+    return typeof value === "string" ? value : undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+    return isRecord(value) ? value : undefined;
+}
+
+function asArray(value: unknown): unknown[] | undefined {
+    return Array.isArray(value) ? value : undefined;
+}
+
+function requireNumber(record: Record<string, unknown>, key: string, where: string): number {
+    const v = asNumber(record[key]);
+    if (v === undefined) throw new OtbrRestError("rest_protocol", `${where}: missing numeric ${key}`);
+    return v;
+}
+
+function parseHexBytes(hex: string, where: string, expectedLen?: number): Uint8Array {
+    if (!/^[0-9a-fA-F]*$/.test(hex)) {
+        throw new OtbrRestError("rest_protocol", `${where}: not hex`);
+    }
+    if (hex.length % 2 !== 0) {
+        throw new OtbrRestError("rest_protocol", `${where}: odd hex length`);
+    }
+    if (expectedLen !== undefined && hex.length !== expectedLen * 2) {
+        throw new OtbrRestError("rest_protocol", `${where}: expected ${expectedLen} bytes, got ${hex.length / 2}`);
+    }
+    return Bytes.of(Bytes.fromHex(hex));
+}
+
+function translateMode(input: Record<string, unknown>): Mode {
+    return {
+        rxOnWhenIdle: requireNumber(input, "rxOnWhenIdle", "mode") !== 0,
+        fullThreadDevice: requireNumber(input, "deviceType", "mode") !== 0,
+        fullNetworkData: requireNumber(input, "networkData", "mode") !== 0,
+    };
+}
+
+function parentPriorityFromInt(raw: number): ParentPriority {
+    if (raw > 0) return 1;
+    if (raw < 0) return -1;
+    return 0;
+}
+
+function translateConnectivity(input: Record<string, unknown>): Connectivity {
+    return {
+        parentPriority: parentPriorityFromInt(requireNumber(input, "parentPriority", "connectivity")),
+        linkQuality3: requireNumber(input, "linkQuality3", "connectivity"),
+        linkQuality2: requireNumber(input, "linkQuality2", "connectivity"),
+        linkQuality1: requireNumber(input, "linkQuality1", "connectivity"),
+        leaderCost: requireNumber(input, "leaderCost", "connectivity"),
+        idSequence: requireNumber(input, "idSequence", "connectivity"),
+        activeRouters: requireNumber(input, "activeRouters", "connectivity"),
+        sedBufferSize: requireNumber(input, "sedBufferSize", "connectivity"),
+        sedDatagramCount: requireNumber(input, "sedDatagramCount", "connectivity"),
+    };
+}
+
+function translateRoute(input: Record<string, unknown>): Route64 {
+    const idSequence = requireNumber(input, "idSequence", "route");
+    const routeData = asArray(input["routeData"]);
+    if (routeData === undefined) {
+        throw new OtbrRestError("rest_protocol", "route: missing routeData array");
+    }
+    const entries = new Array<Route64Entry>();
+    for (const raw of routeData) {
+        const r = asRecord(raw);
+        if (r === undefined) {
+            throw new OtbrRestError("rest_protocol", "route.routeData: entry is not an object");
+        }
+        entries.push({
+            routerId: requireNumber(r, "routeId", "route.routeData"),
+            linkQualityOut: requireNumber(r, "linkQualityOut", "route.routeData"),
+            linkQualityIn: requireNumber(r, "linkQualityIn", "route.routeData"),
+            routeCost: requireNumber(r, "routeCost", "route.routeData"),
+        });
+    }
+    return { idSequence, entries };
+}
+
+function translateLeaderData(input: Record<string, unknown>): LeaderData {
+    return {
+        partitionId: requireNumber(input, "partitionId", "leaderData"),
+        weighting: requireNumber(input, "weighting", "leaderData"),
+        dataVersion: requireNumber(input, "dataVersion", "leaderData"),
+        stableDataVersion: requireNumber(input, "stableDataVersion", "leaderData"),
+        leaderRouterId: requireNumber(input, "leaderRouterId", "leaderData"),
+    };
+}
+
+function translateMacCounters(input: Record<string, unknown>): MacCounters {
+    return {
+        ifInUnknownProtos: requireNumber(input, "ifInUnknownProtos", "macCounters"),
+        ifInErrors: requireNumber(input, "ifInErrors", "macCounters"),
+        ifOutErrors: requireNumber(input, "ifOutErrors", "macCounters"),
+        ifInUcastPkts: requireNumber(input, "ifInUcastPkts", "macCounters"),
+        ifInBroadcastPkts: requireNumber(input, "ifInBroadcastPkts", "macCounters"),
+        ifInDiscards: requireNumber(input, "ifInDiscards", "macCounters"),
+        ifOutUcastPkts: requireNumber(input, "ifOutUcastPkts", "macCounters"),
+        ifOutBroadcastPkts: requireNumber(input, "ifOutBroadcastPkts", "macCounters"),
+        ifOutDiscards: requireNumber(input, "ifOutDiscards", "macCounters"),
+    };
+}
+
+function requireBigInt(record: Record<string, unknown>, key: string, where: string): bigint {
+    const v = record[key];
+    if (typeof v === "bigint") return v;
+    const n = asNumber(v);
+    if (n === undefined) throw new OtbrRestError("rest_protocol", `${where}: missing numeric ${key}`);
+    return BigInt(Math.trunc(n));
+}
+
+function translateMleCounters(input: Record<string, unknown>): MleCounters {
+    return {
+        disabledRole: requireNumber(input, "disabledRole", "mleCounters"),
+        detachedRole: requireNumber(input, "detachedRole", "mleCounters"),
+        childRole: requireNumber(input, "childRole", "mleCounters"),
+        routerRole: requireNumber(input, "routerRole", "mleCounters"),
+        leaderRole: requireNumber(input, "leaderRole", "mleCounters"),
+        attachAttempts: requireNumber(input, "attachAttempts", "mleCounters"),
+        partitionIdChanges: requireNumber(input, "partitionIdChanges", "mleCounters"),
+        betterPartitionAttachAttempts: requireNumber(input, "betterPartitionAttachAttempts", "mleCounters"),
+        parentChanges: requireNumber(input, "parentChanges", "mleCounters"),
+        trackedTime: requireBigInt(input, "trackedTime", "mleCounters"),
+        disabledTime: requireBigInt(input, "disabledTime", "mleCounters"),
+        detachedTime: requireBigInt(input, "detachedTime", "mleCounters"),
+        childTime: requireBigInt(input, "childTime", "mleCounters"),
+        routerTime: requireBigInt(input, "routerTime", "mleCounters"),
+        leaderTime: requireBigInt(input, "leaderTime", "mleCounters"),
+    };
+}
+
+function translateChildTable(input: unknown[]): ChildTableEntry[] {
+    const out = new Array<ChildTableEntry>();
+    for (const raw of input) {
+        const r = asRecord(raw);
+        if (r === undefined) {
+            throw new OtbrRestError("rest_protocol", "childTable: entry is not an object");
+        }
+        const modeRecord = asRecord(r["mode"]);
+        if (modeRecord === undefined) {
+            throw new OtbrRestError("rest_protocol", "childTable: entry missing mode");
+        }
+        const exp = requireNumber(r, "timeout", "childTable.timeout");
+        const clampedExp = exp < TIMEOUT_EXP_MIN ? TIMEOUT_EXP_MIN : exp;
+        out.push({
+            timeoutExponent: exp,
+            timeoutSeconds: 1 << (clampedExp - TIMEOUT_EXP_MIN),
+            // OTBR /diagnostics omits the wire-form 2-bit incoming-link-quality field
+            // for child entries; mirror OpenThread's default of 0.
+            incomingLinkQuality: 0,
+            childId: requireNumber(r, "childId", "childTable"),
+            mode: translateMode(modeRecord),
+        });
+    }
+    return out;
+}
+
+/**
+ * Parse an IPv6 textual address into 16 bytes. Supports full forms and `::`
+ * compression. Does not handle IPv4-mapped (`::ffff:1.2.3.4`) or zone IDs
+ * (`%`); OTBR `IP6AddressList` never returns either.
+ */
+function parseIpv6(text: string): Uint8Array {
+    if (text.includes("%")) {
+        throw new OtbrRestError("rest_protocol", `ipv6: zone ID not supported in ${text}`);
+    }
+    const doubleColonIdx = text.indexOf("::");
+    let leftPart: string;
+    let rightPart: string;
+    if (doubleColonIdx === -1) {
+        leftPart = text;
+        rightPart = "";
+    } else {
+        if (text.indexOf("::", doubleColonIdx + 2) !== -1) {
+            throw new OtbrRestError("rest_protocol", `ipv6: multiple "::" in ${text}`);
+        }
+        leftPart = text.slice(0, doubleColonIdx);
+        rightPart = text.slice(doubleColonIdx + 2);
+    }
+    const leftGroups = leftPart === "" ? [] : leftPart.split(":");
+    const rightGroups = rightPart === "" ? [] : rightPart.split(":");
+
+    if (doubleColonIdx === -1 && leftGroups.length !== IPV6_GROUPS) {
+        throw new OtbrRestError("rest_protocol", `ipv6: expected ${IPV6_GROUPS} groups in ${text}`);
+    }
+    const fillCount = IPV6_GROUPS - leftGroups.length - rightGroups.length;
+    if (fillCount < 0 || (doubleColonIdx !== -1 && fillCount === 0)) {
+        throw new OtbrRestError("rest_protocol", `ipv6: too many groups in ${text}`);
+    }
+
+    const groups = new Array<number>();
+    for (const g of leftGroups) groups.push(parseGroup(g, text));
+    for (let i = 0; i < fillCount; i++) groups.push(0);
+    for (const g of rightGroups) groups.push(parseGroup(g, text));
+
+    const out = new Uint8Array(IPV6_BYTES);
+    for (let i = 0; i < IPV6_GROUPS; i++) {
+        out[i * 2] = (groups[i] >>> 8) & 0xff;
+        out[i * 2 + 1] = groups[i] & 0xff;
+    }
+    return out;
+}
+
+function parseGroup(g: string, text: string): number {
+    if (g.length === 0 || g.length > 4 || !/^[0-9a-fA-F]+$/.test(g)) {
+        throw new OtbrRestError("rest_protocol", `ipv6: bad group "${g}" in ${text}`);
+    }
+    return parseInt(g, 16);
+}
+
+/**
+ * Translate a single OTBR `/diagnostics` entry (already key-normalized to
+ * camelCase) into a {@link DiagnosticResponse}. Skips fields the entry does
+ * not include — REST returns whatever the BR last collected, which differs
+ * per node and per OpenThread build.
+ */
+export function translateNodeJson(json: unknown): DiagnosticResponse {
+    if (!isRecord(json)) {
+        throw new OtbrRestError("rest_protocol", "translateNodeJson: input is not an object");
+    }
+    const result: DiagnosticResponse = { unknown: new Array<{ type: number; value: Uint8Array }>() };
+
+    const extAddress = asString(json["extAddress"]);
+    if (extAddress !== undefined) {
+        result.extMacAddress = parseHexBytes(extAddress, "extAddress", 8);
+    }
+
+    const rloc16 = asNumber(json["rloc16"]);
+    if (rloc16 !== undefined) result.rloc16 = rloc16;
+
+    const mode = asRecord(json["mode"]);
+    if (mode !== undefined) result.mode = translateMode(mode);
+
+    const timeout = asNumber(json["timeout"]);
+    if (timeout !== undefined) result.timeout = timeout;
+
+    const connectivity = asRecord(json["connectivity"]);
+    if (connectivity !== undefined) result.connectivity = translateConnectivity(connectivity);
+
+    const route = asRecord(json["route"]);
+    if (route !== undefined) result.route64 = translateRoute(route);
+
+    const leaderData = asRecord(json["leaderData"]);
+    if (leaderData !== undefined) result.leaderData = translateLeaderData(leaderData);
+
+    const networkData = asString(json["networkData"]);
+    if (networkData !== undefined) {
+        result.networkData = NetworkData.decode(parseHexBytes(networkData, "networkData"));
+    }
+
+    const ip6Addresses = asArray(json["ip6AddressList"]);
+    if (ip6Addresses !== undefined) {
+        const list = new Array<Uint8Array>();
+        for (const entry of ip6Addresses) {
+            const text = asString(entry);
+            if (text === undefined) {
+                throw new OtbrRestError("rest_protocol", "ip6AddressList: entry is not a string");
+            }
+            list.push(parseIpv6(text));
+        }
+        result.ipv6Addresses = list;
+    }
+
+    const macCounters = asRecord(json["macCounters"]);
+    if (macCounters !== undefined) result.macCounters = translateMacCounters(macCounters);
+
+    const mleCounters = asRecord(json["mleCounters"]);
+    if (mleCounters !== undefined) result.mleCounters = translateMleCounters(mleCounters);
+
+    const childTable = asArray(json["childTable"]);
+    if (childTable !== undefined) result.childTable = translateChildTable(childTable);
+
+    const channelPages = asString(json["channelPages"]);
+    if (channelPages !== undefined) {
+        const bytes = parseHexBytes(channelPages, "channelPages");
+        result.channelPages = Array.from(bytes);
+    }
+
+    const maxChildTimeout = asNumber(json["maxChildTimeout"]);
+    if (maxChildTimeout !== undefined) result.maxChildTimeout = maxChildTimeout;
+
+    const eui64 = asString(json["eui64"]);
+    if (eui64 !== undefined) result.eui64 = parseHexBytes(eui64, "eui64", 8);
+
+    const version = asNumber(json["version"]);
+    if (version !== undefined) result.version = version;
+
+    const vendorName = asString(json["vendorName"]);
+    if (vendorName !== undefined) result.vendorName = vendorName;
+
+    const vendorModel = asString(json["vendorModel"]);
+    if (vendorModel !== undefined) result.vendorModel = vendorModel;
+
+    const vendorSwVersion = asString(json["vendorSwVersion"]);
+    if (vendorSwVersion !== undefined) result.vendorSwVersion = vendorSwVersion;
+
+    const threadStackVersion = asString(json["threadStackVersion"]);
+    if (threadStackVersion !== undefined) result.threadStackVersion = threadStackVersion;
+
+    const vendorAppUrl = asString(json["vendorAppUrl"]);
+    if (vendorAppUrl !== undefined) result.vendorAppUrl = vendorAppUrl;
+
+    const batteryLevel = asNumber(json["batteryLevel"]);
+    if (batteryLevel !== undefined) result.batteryLevel = batteryLevel;
+
+    const supplyVoltage = asNumber(json["supplyVoltage"]);
+    if (supplyVoltage !== undefined) result.supplyVoltage = supplyVoltage;
+
+    return result;
+}
+
+export const __testables = { parseIpv6 };

package/src/selection/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export { decodeStateBitmap, rankBrs, selectBr } from "./selectBr.js";
+export type { DecodedStateBitmap } from "./selectBr.js";
+export { selectSource } from "./selectSource.js";
+export type { SelectSourceOpts } from "./selectSource.js";
+export { ExtPanIdLockManager } from "./withExtPanIdLock.js";

package/src/selection/selectBr.ts

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { BorderRouterEntry } from "../discovery/BorderRouterEntry.js";
+
+/**
+ * Decoded subset of the MeshCoP `_meshcop` TXT `sb` (state bitmap) field that
+ * matters for BR selection. Layout per OpenThread's `border_agent_txt_data.hpp`:
+ *   bit 7  BBR Active
+ *   bit 8  BBR Is Primary (only meaningful when BBR Active)
+ */
+export interface DecodedStateBitmap {
+    bbrActive: boolean;
+    bbrPrimary: boolean;
+}
+
+/**
+ * Decode the BBR-relevant bits from a 4-byte state bitmap hex string.
+ *
+ * Returns `{ bbrActive: false, bbrPrimary: false }` for missing or malformed
+ * input — selection treats absence and "no BBR role" as equivalent.
+ */
+export function decodeStateBitmap(hex: string | undefined): DecodedStateBitmap {
+    if (hex === undefined || !/^[0-9a-fA-F]{1,8}$/.test(hex)) {
+        return { bbrActive: false, bbrPrimary: false };
+    }
+    const value = parseInt(hex, 16);
+    if (!Number.isFinite(value)) {
+        return { bbrActive: false, bbrPrimary: false };
+    }
+    return {
+        bbrActive: ((value >> 7) & 0x1) === 1,
+        bbrPrimary: ((value >> 8) & 0x1) === 1,
+    };
+}
+
+function hasLinkLocal(addresses: ReadonlyArray<string>): boolean {
+    for (const addr of addresses) {
+        if (addr.toLowerCase().startsWith("fe80:")) return true;
+    }
+    return false;
+}
+
+function scoreOf(br: BorderRouterEntry): number {
+    const { bbrActive, bbrPrimary } = decodeStateBitmap(br.stateBitmapHex);
+    // State tier dominates link-local so an active BBR always outranks an
+    // ordinary router: primary BBR (4) > active-but-not-primary BBR (2) > rest (0).
+    const stateScore = bbrActive ? (bbrPrimary ? 4 : 2) : 0;
+    const llScore = hasLinkLocal(br.addresses) ? 1 : 0;
+    return stateScore + llScore;
+}
+
+/**
+ * Pick the best BR per spec FR-12 priority:
+ *   1. State bitmap "BBR Active + Primary" (bits 7 and 8) wins.
+ *   2. Then BBR Active but not Primary.
+ *   3. Among equals: BR with at least one IPv6 link-local (`fe80:`) address wins.
+ *   4. Among equals: alphabetical `extAddressHex` ascending (deterministic tie-break).
+ */
+export function selectBr(brs: ReadonlyArray<BorderRouterEntry>): BorderRouterEntry | undefined {
+    return rankBrs(brs)[0];
+}
+
+/**
+ * Rank all candidate BRs best-first using the same priority as {@link selectBr}.
+ * Callers fall back to later entries when the preferred BR is unreachable.
+ */
+export function rankBrs(brs: ReadonlyArray<BorderRouterEntry>): BorderRouterEntry[] {
+    return [...brs].sort((a, b) => {
+        const byScore = scoreOf(b) - scoreOf(a);
+        if (byScore !== 0) return byScore;
+        return a.extAddressHex < b.extAddressHex ? -1 : a.extAddressHex > b.extAddressHex ? 1 : 0;
+    });
+}

package/src/selection/selectSource.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes } from "@matter/general";
+import type { ThreadCredentialsRegistry } from "../credentials/ThreadCredentialsRegistry.js";
+import type { ThreadNetworkCredentials } from "../credentials/ThreadNetworkCredentials.js";
+import type { DiagnosticSource } from "../diagnostic/DiagnosticSource.js";
+import type { BorderRouterEntry } from "../discovery/BorderRouterEntry.js";
+import type { OtbrRestCapability } from "../otbr-rest/OtbrRestCapability.js";
+
+export interface SelectSourceOpts {
+    br: BorderRouterEntry;
+    credentials: Pick<ThreadCredentialsRegistry, "getCredentials">;
+    /** Keyed by `Bytes.toHex(extPanId)` (lowercase). */
+    restCapabilities: ReadonlyMap<string, OtbrRestCapability>;
+    otbrRestEnabled: boolean;
+    /** Factory for the REST source (caller injects to avoid cyclic deps). */
+    makeRestSource: (cap: OtbrRestCapability) => DiagnosticSource;
+    /** Factory for the MeshCoP source (caller injects). */
+    makeMeshcopSource: (creds: ThreadNetworkCredentials, br: BorderRouterEntry) => DiagnosticSource;
+}
+
+/**
+ * Pick the diagnostic source per spec §4.10 priority:
+ *   1. `otbrRestEnabled` AND `restCapabilities` has an entry for this BR's extPanId → REST.
+ *   2. Credentials registered for this BR's extPanId → MeshCoP.
+ *   3. Neither → undefined (Mode B observation only).
+ *
+ * Returns undefined when the BR carries no `extendedPanIdHex`, since both lookups
+ * key on it.
+ */
+export function selectSource(opts: SelectSourceOpts): DiagnosticSource | undefined {
+    const { br, credentials, restCapabilities, otbrRestEnabled, makeRestSource, makeMeshcopSource } = opts;
+    if (br.extendedPanIdHex === undefined) return undefined;
+
+    const extPanId = Bytes.of(Bytes.fromHex(br.extendedPanIdHex));
+    const lookupKey = Bytes.toHex(extPanId);
+
+    if (otbrRestEnabled) {
+        const cap = restCapabilities.get(lookupKey);
+        if (cap !== undefined) return makeRestSource(cap);
+    }
+
+    const creds = credentials.getCredentials(extPanId);
+    if (creds !== undefined) return makeMeshcopSource(creds, br);
+
+    return undefined;
+}

package/src/selection/withExtPanIdLock.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes } from "@matter/general";
+
+/**
+ * Per-extPanId FIFO mutex for diagnostic flows.
+ *
+ * Two callers targeting the same Thread network (same extPanId) run sequentially;
+ * callers targeting different networks run concurrently. The MeshCoP commissioner
+ * petition is single-session per BR, so serialising same-network access prevents
+ * petition collisions when the controller fans out queries.
+ */
+export class ExtPanIdLockManager {
+    readonly #queues = new Map<string, Promise<unknown>>();
+
+    /**
+     * Run `fn` with mutual exclusion against any other invocation for the same `extPanId`.
+     * Errors thrown by `fn` propagate to the caller but never poison the queue —
+     * the next caller for the same key still runs.
+     */
+    withLock<T>(extPanId: Uint8Array, fn: () => Promise<T>): Promise<T> {
+        const key = Bytes.toHex(extPanId);
+        const previous = this.#queues.get(key) ?? Promise.resolve();
+        const result = previous.then(() => fn());
+        const chained: Promise<unknown> = result
+            .catch(() => undefined)
+            .finally(() => {
+                // Only clear when this promise is still the tail — a later call may have already chained.
+                if (this.#queues.get(key) === chained) {
+                    this.#queues.delete(key);
+                }
+            });
+        this.#queues.set(key, chained);
+        return result;
+    }
+}

package/src/tlv/BasicTlvCodec.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError, MatterError } from "@matter/general";
+
+/** Low-level MeshCoP/base TLV codec parse failure (truncated stream, bad length, ...). */
+export class ThreadTlvError extends MatterError {}
+
+/**
+ * MeshCoP TLV stream (Thread spec §8.10) is a sequence of [type:1][length:1][value:length] frames.
+ * Length 0xFF escapes to a 2-byte big-endian extended length following the type byte.
+ */
+export interface BasicTlvEntry {
+    type: number;
+    value: Uint8Array;
+}
+
+export namespace BasicTlv {
+    export function walk(blob: Uint8Array): BasicTlvEntry[] {
+        const out = new Array<BasicTlvEntry>();
+        let offset = 0;
+        while (offset < blob.length) {
+            if (offset + 2 > blob.length) {
+                throw new ThreadTlvError(`Truncated TLV header at offset ${offset}`);
+            }
+            const type = blob[offset];
+            const lenByte = blob[offset + 1];
+            let length: number;
+            let valueStart: number;
+            if (lenByte === 0xff) {
+                if (offset + 4 > blob.length) {
+                    throw new ThreadTlvError(`Truncated extended-length TLV header at offset ${offset}`);
+                }
+                length = (blob[offset + 2] << 8) | blob[offset + 3];
+                valueStart = offset + 4;
+            } else {
+                length = lenByte;
+                valueStart = offset + 2;
+            }
+            const valueEnd = valueStart + length;
+            if (valueEnd > blob.length) {
+                throw new ThreadTlvError(`Truncated TLV value at offset ${offset} (type=${type}, length=${length})`);
+            }
+            out.push({ type, value: blob.slice(valueStart, valueEnd) });
+            offset = valueEnd;
+        }
+        return out;
+    }
+
+    export function encode(entries: ReadonlyArray<BasicTlvEntry>): Uint8Array {
+        let totalLength = 0;
+        for (const entry of entries) {
+            if (!Number.isInteger(entry.type) || entry.type < 0 || entry.type > 0xff) {
+                throw new InternalError(`Invalid TLV type ${entry.type}: must be 0..255`);
+            }
+            const valueLen = entry.value.length;
+            if (valueLen > 0xffff) {
+                throw new InternalError(`Invalid TLV length ${valueLen}: must be <= 0xFFFF`);
+            }
+            totalLength += valueLen + (valueLen >= 0xff ? 4 : 2);
+        }
+
+        const out = new Uint8Array(totalLength);
+        let offset = 0;
+        for (const entry of entries) {
+            const valueLen = entry.value.length;
+            out[offset++] = entry.type;
+            if (valueLen >= 0xff) {
+                out[offset++] = 0xff;
+                out[offset++] = (valueLen >> 8) & 0xff;
+                out[offset++] = valueLen & 0xff;
+            } else {
+                out[offset++] = valueLen;
+            }
+            out.set(entry.value, offset);
+            offset += valueLen;
+        }
+        return out;
+    }
+}

package/src/tlv/NetworkDiagnosticTlv.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { BasicTlv, type BasicTlvEntry } from "./BasicTlvCodec.js";
+
+/**
+ * One Network Diagnostic TLV entry as walked from the response payload.
+ *
+ * The {@link type} numeric values are listed in {@link NetworkDiagTlvType}.
+ * {@link value} holds the raw inner bytes; per-TLV typed decoders in
+ * `./diag/` interpret it.
+ */
+export type NetworkDiagnosticEntry = BasicTlvEntry;
+
+/**
+ * Outer Network Diagnostic TLV codec.
+ *
+ * MGMT_DIAG_GET responses (and `.qry` payloads, on the request side) are a
+ * concatenation of TLVs framed by the same basic + extended-length scheme as
+ * MeshCoP. This namespace just specializes {@link BasicTlv} for the diagnostic
+ * registry so callers get an idiomatic name.
+ *
+ * Unknown TLV types are preserved as raw {@link NetworkDiagnosticEntry}
+ * records; per-TLV typed decoders are layered on top in `./diag/`.
+ */
+export namespace NetworkDiagnosticTlv {
+    export function decode(blob: Uint8Array): NetworkDiagnosticEntry[] {
+        return BasicTlv.walk(blob);
+    }
+
+    export function encode(entries: ReadonlyArray<NetworkDiagnosticEntry>): Uint8Array {
+        return BasicTlv.encode(entries);
+    }
+}

package/src/tlv/TypeListTlv.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "@matter/general";
+
+/**
+ * Type List TLV value codec (Network Diagnostic TLV type 18).
+ *
+ * The "value" of a Type List TLV is just the concatenation of the TLV-type
+ * bytes the requester wants — one byte per requested type. The outer TLV(18,
+ * ...) framing comes from the regular {@link NetworkDiagnosticTlv.encode}
+ * caller, e.g.:
+ *
+ *   NetworkDiagnosticTlv.encode([{ type: NetworkDiagTlvType.TYPE_LIST, value: TypeListTlv.encode([0, 1, 5]) }])
+ *
+ * Source: OpenThread `network_diagnostic_tlvs.hpp` `TypeListTlv` (a plain
+ * `TlvInfo<kTypeList>`) and `network_diagnostic.cpp` request payload handling.
+ */
+export namespace TypeListTlv {
+    export function encode(types: ReadonlyArray<number>): Uint8Array {
+        const out = new Uint8Array(types.length);
+        for (let i = 0; i < types.length; i++) {
+            const t = types[i];
+            if (!Number.isInteger(t) || t < 0 || t > 0xff) {
+                throw new InternalError(`TypeList entry out of range: ${t}`);
+            }
+            out[i] = t;
+        }
+        return out;
+    }
+
+    export function decode(value: Uint8Array): number[] {
+        return Array.from(value);
+    }
+}