@matter/thread-br-client 0.0.1

package/src/tlv/diag/VendorInfo.ts

@@ -0,0 +1,113 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "@matter/general";
+import { ThreadDiagError } from "../../diagnostic/errors.js";
+
+/**
+ * Decoders for the variable-length Network Diagnostic vendor-info TLVs and
+ * the related fixed-size primitive TLVs that round out the default request set.
+ *
+ * | TLV | Type | Layout |
+ * |-----|------|--------|
+ * | Version              | 24 | uint16 BE  — Thread protocol version |
+ * | VendorName           | 25 | UTF-8 string, max 32 bytes |
+ * | VendorModel          | 26 | UTF-8 string, max 32 bytes |
+ * | VendorSwVersion      | 27 | UTF-8 string, max 16 bytes |
+ * | ThreadStackVersion   | 28 | UTF-8 string, max 64 bytes |
+ * | VendorAppUrl         | 35 | UTF-8 string, max 96 bytes |
+ *
+ * String lengths come from OpenThread's `OT_NETWORK_DIAGNOSTIC_MAX_*_TLV_LENGTH`
+ * constants in `include/openthread/netdiag.h`. We tolerate over-length on decode
+ * (real BRs may vary) but enforce on encode.
+ */
+
+const TEXT_DECODER = new TextDecoder("utf-8", { fatal: false });
+const TEXT_ENCODER = new TextEncoder();
+
+function decodeUtf8(value: Uint8Array): string {
+    return TEXT_DECODER.decode(value);
+}
+
+function encodeUtf8(text: string, maxBytes: number, name: string): Uint8Array {
+    const encoded = TEXT_ENCODER.encode(text);
+    if (encoded.length > maxBytes) {
+        throw new InternalError(`${name} value too long: ${encoded.length} bytes (max ${maxBytes})`);
+    }
+    return encoded;
+}
+
+export const VENDOR_NAME_MAX = 32;
+export const VENDOR_MODEL_MAX = 32;
+export const VENDOR_SW_VERSION_MAX = 16;
+export const THREAD_STACK_VERSION_MAX = 64;
+export const VENDOR_APP_URL_MAX = 96;
+
+export namespace Version {
+    export function decode(value: Uint8Array): number {
+        if (value.length !== 2) {
+            throw new ThreadDiagError(`Version TLV must be 2 bytes, got ${value.length}`);
+        }
+        return (value[0] << 8) | value[1];
+    }
+
+    export function encode(version: number): Uint8Array {
+        if (!Number.isInteger(version) || version < 0 || version > 0xffff) {
+            throw new InternalError(`Version TLV out of range: ${version}`);
+        }
+        return new Uint8Array([(version >> 8) & 0xff, version & 0xff]);
+    }
+}
+
+export namespace VendorName {
+    export function decode(value: Uint8Array): string {
+        return decodeUtf8(value);
+    }
+
+    export function encode(name: string): Uint8Array {
+        return encodeUtf8(name, VENDOR_NAME_MAX, "VendorName");
+    }
+}
+
+export namespace VendorModel {
+    export function decode(value: Uint8Array): string {
+        return decodeUtf8(value);
+    }
+
+    export function encode(model: string): Uint8Array {
+        return encodeUtf8(model, VENDOR_MODEL_MAX, "VendorModel");
+    }
+}
+
+export namespace VendorSwVersion {
+    export function decode(value: Uint8Array): string {
+        return decodeUtf8(value);
+    }
+
+    export function encode(version: string): Uint8Array {
+        return encodeUtf8(version, VENDOR_SW_VERSION_MAX, "VendorSwVersion");
+    }
+}
+
+export namespace ThreadStackVersion {
+    export function decode(value: Uint8Array): string {
+        return decodeUtf8(value);
+    }
+
+    export function encode(version: string): Uint8Array {
+        return encodeUtf8(version, THREAD_STACK_VERSION_MAX, "ThreadStackVersion");
+    }
+}
+
+export namespace VendorAppUrl {
+    export function decode(value: Uint8Array): string {
+        return decodeUtf8(value);
+    }
+
+    export function encode(url: string): Uint8Array {
+        return encodeUtf8(url, VENDOR_APP_URL_MAX, "VendorAppUrl");
+    }
+}

package/src/tlv/diag/index.ts

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Each TLV decoder file exports an `interface` and a same-named `namespace`.
+// Declaration merging means a single re-export carries both the type and the
+// value (decode/encode functions) under one identifier.
+
+export { ChildIpv6AddressList } from "./ChildIpv6AddressList.js";
+export type { ChildIpv6Addresses } from "./ChildIpv6AddressList.js";
+
+export { ChildTable } from "./ChildTable.js";
+export type { ChildTableEntry } from "./ChildTable.js";
+
+export { Connectivity } from "./Connectivity.js";
+export type { ParentPriority } from "./Connectivity.js";
+
+export { Ipv6AddressList } from "./Ipv6AddressList.js";
+
+export { LeaderData } from "./LeaderData.js";
+
+export { MacCounters } from "./MacCounters.js";
+
+export { MleCounters } from "./MleCounters.js";
+
+export { Mode } from "./Mode.js";
+
+export { NetworkData } from "./NetworkData.js";
+export type {
+    BorderRouterEntry,
+    HasRouteEntry,
+    NetworkDataEntry,
+    NetworkDataPrefix,
+    NetworkDataServer,
+    NetworkDataService,
+    ThreadNetworkData,
+} from "./NetworkData.js";
+
+export {
+    Address16,
+    BatteryLevel,
+    ChannelPages,
+    Eui64,
+    ExtMacAddress,
+    MaxChildTimeout,
+    SupplyVoltage,
+} from "./Primitives.js";
+
+export { Route64 } from "./Route64.js";
+export type { Route64Entry } from "./Route64.js";
+
+export { RouterNeighbor } from "./RouterNeighbor.js";
+export type { RouterNeighborEntry } from "./RouterNeighbor.js";
+
+export { Timeout } from "./Timeout.js";
+
+export { ThreadStackVersion, VendorAppUrl, VendorModel, VendorName, VendorSwVersion, Version } from "./VendorInfo.js";

package/src/tlv/meshcop/Ip6AddressTlv.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ThreadTlvError } from "../BasicTlvCodec.js";
+
+/**
+ * IPv6 Address TLV value codec (MeshCoP TLV type 49).
+ *
+ * The value is a raw 16-byte IPv6 address — the UDP-proxy target (a mesh-local
+ * unicast address or a multicast group) on the request side, and the
+ * responder's source address on the reply side. The outer type/length framing
+ * is applied by {@link BasicTlv.encode}.
+ *
+ * Source: Thread spec §8.10 (UDP Proxy) and OpenThread
+ * `src/core/meshcop/meshcop_tlvs.hpp` `IPv6AddressTlv` (`kIPv6Address = 49`).
+ */
+export namespace Ip6AddressTlv {
+    export function encode(addr: Uint8Array): Uint8Array {
+        assertLength(addr);
+        return addr.slice();
+    }
+
+    export function decode(bytes: Uint8Array): Uint8Array {
+        assertLength(bytes);
+        return bytes.slice();
+    }
+}
+
+function assertLength(addr: Uint8Array): void {
+    if (addr.length !== 16) {
+        throw new ThreadTlvError(`Ip6AddressTlv: address must be 16 bytes, got ${addr.length}`);
+    }
+}

package/src/tlv/meshcop/UdpEncapsulationTlv.ts

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "@matter/general";
+import { ThreadTlvError } from "../BasicTlvCodec.js";
+
+/**
+ * UDP Encapsulation TLV value codec (MeshCoP TLV type 48).
+ *
+ * The value is a 2-byte big-endian source port, a 2-byte big-endian
+ * destination port, and the raw encapsulated UDP payload (an inner CoAP
+ * message, for the diagnostic UDP-proxy flow). The outer type/length framing
+ * is applied by {@link BasicTlv.encode}.
+ *
+ * Source: Thread spec §8.10 (UDP Proxy) and OpenThread
+ * `src/core/meshcop/meshcop_tlvs.hpp` `UdpEncapsulationTlv` (`kUdpEncapsulation
+ * = 48`).
+ */
+export interface UdpEncapsulation {
+    sourcePort: number;
+    destinationPort: number;
+    payload: Uint8Array;
+}
+
+export namespace UdpEncapsulationTlv {
+    export function encode({ sourcePort, destinationPort, payload }: UdpEncapsulation): Uint8Array {
+        assertPort(sourcePort, "sourcePort");
+        assertPort(destinationPort, "destinationPort");
+        const out = new Uint8Array(4 + payload.length);
+        out[0] = (sourcePort >> 8) & 0xff;
+        out[1] = sourcePort & 0xff;
+        out[2] = (destinationPort >> 8) & 0xff;
+        out[3] = destinationPort & 0xff;
+        out.set(payload, 4);
+        return out;
+    }
+
+    export function decode(bytes: Uint8Array): UdpEncapsulation {
+        if (bytes.length < 4) {
+            throw new ThreadTlvError(`UdpEncapsulationTlv: value must be at least 4 bytes, got ${bytes.length}`);
+        }
+        return {
+            sourcePort: (bytes[0] << 8) | bytes[1],
+            destinationPort: (bytes[2] << 8) | bytes[3],
+            payload: bytes.slice(4),
+        };
+    }
+}
+
+function assertPort(port: number, name: string): void {
+    if (!Number.isInteger(port) || port < 0 || port > 0xffff) {
+        throw new InternalError(`UdpEncapsulationTlv: ${name} out of range: ${port}`);
+    }
+}

package/src/tlv/networkDiagTlvTypes.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Network Diagnostic TLV type identifiers.
+ *
+ * Numeric values are authoritative per OpenThread `include/openthread/netdiag.h`
+ * (BSD-3, https://github.com/openthread/openthread) and `src/core/thread/network_diagnostic_tlvs.hpp`.
+ *
+ * Note this registry is intentionally separate from {@link MeshCopTlvType}; the
+ * MeshCoP and Network Diagnostic TLV namespaces share the basic length-prefix
+ * framing but assign different meanings to the same numeric type bytes (e.g.
+ * MeshCoP `VENDOR_NAME` is 33, Network Diagnostic `VendorName` is 25).
+ */
+export const NetworkDiagTlvType = {
+    EXT_MAC_ADDRESS: 0,
+    ADDRESS16: 1,
+    MODE: 2,
+    TIMEOUT: 3,
+    CONNECTIVITY: 4,
+    ROUTE64: 5,
+    LEADER_DATA: 6,
+    NETWORK_DATA: 7,
+    IPV6_ADDRESS_LIST: 8,
+    MAC_COUNTERS: 9,
+    BATTERY_LEVEL: 14,
+    SUPPLY_VOLTAGE: 15,
+    CHILD_TABLE: 16,
+    CHANNEL_PAGES: 17,
+    TYPE_LIST: 18,
+    MAX_CHILD_TIMEOUT: 19,
+    EUI64: 23,
+    VERSION: 24,
+    VENDOR_NAME: 25,
+    VENDOR_MODEL: 26,
+    VENDOR_SW_VERSION: 27,
+    THREAD_STACK_VERSION: 28,
+    CHILD: 29,
+    CHILD_IPV6_ADDRESS_LIST: 30,
+    ROUTER_NEIGHBOR: 31,
+    ANSWER: 32,
+    QUERY_ID: 33,
+    MLE_COUNTERS: 34,
+    VENDOR_APP_URL: 35,
+    NON_PREFERRED_CHANNELS: 36,
+    ENHANCED_ROUTE: 37,
+    BR_STATE: 38,
+    BR_IF_ADDRS: 39,
+    BR_LOCAL_OMR_PREFIX: 40,
+    BR_DHCP6_PD_OMR_PREFIX: 41,
+    BR_LOCAL_ON_LINK_PREFIX: 42,
+    BR_FAVORED_ON_LINK_PREFIX: 43,
+} as const;
+
+export type NetworkDiagTlvTypeKey = keyof typeof NetworkDiagTlvType;
+export type NetworkDiagTlvTypeValue = (typeof NetworkDiagTlvType)[NetworkDiagTlvTypeKey];
+
+export const NetworkDiagTlvTypeName: Record<number, NetworkDiagTlvTypeKey> = (() => {
+    const out: Record<number, NetworkDiagTlvTypeKey> = {};
+    for (const [key, value] of Object.entries(NetworkDiagTlvType) as Array<
+        [NetworkDiagTlvTypeKey, NetworkDiagTlvTypeValue]
+    >) {
+        out[value] = key;
+    }
+    return out;
+})();

package/src/tsconfig.json

@@ -0,0 +1,21 @@
+// Managed by nacho-build.  Nacho will update references automatically but otherwise preserves your edits.
+// Use `nacho-build configure` to overwrite with defaults.
+{
+    "extends": "../../../tsc/tsconfig.lib.json",
+    "compilerOptions": {
+        "types": [
+            "node"
+        ]
+    },
+    "references": [
+        {
+            "path": "../../general/src"
+        },
+        {
+            "path": "../../protocol/src"
+        },
+        {
+            "path": "../../testing/src"
+        }
+    ]
+}

package/src/util/meshLocalAddr.ts

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ImplementationError } from "@matter/general";
+
+/**
+ * Realm-local all-Thread-nodes multicast address (`ff03::1`).
+ */
+export const ALL_THREAD_NODES_REALM_LOCAL: Uint8Array = realmLocal(0x01);
+
+/**
+ * Realm-local all-Thread-routers multicast address (`ff03::2`). Diagnostic
+ * multicast queries (`MGMT_DIAG_GET.qry`) target this group.
+ */
+export const ALL_THREAD_ROUTERS_REALM_LOCAL: Uint8Array = realmLocal(0x02);
+
+/**
+ * Derive the mesh-local IPv6 address of a node from its RLOC16.
+ *
+ * Layout: `mlPrefix(8) || 0x0000 00FF FE00 || rloc16(2 BE)` — the well-known
+ * Thread RLOC interface identifier with the locator in the low 16 bits.
+ */
+export function deriveMeshLocalAddress(mlPrefix: Uint8Array, rloc16: number): Uint8Array {
+    if (mlPrefix.length !== 8) {
+        throw new ImplementationError(`deriveMeshLocalAddress: mlPrefix must be 8 bytes, got ${mlPrefix.length}`);
+    }
+    if (!Number.isInteger(rloc16) || rloc16 < 0 || rloc16 > 0xffff) {
+        throw new ImplementationError(`deriveMeshLocalAddress: rloc16 out of range: ${rloc16}`);
+    }
+    const addr = new Uint8Array(16);
+    addr.set(mlPrefix, 0);
+    addr[11] = 0xff;
+    addr[12] = 0xfe;
+    addr[14] = (rloc16 >> 8) & 0xff;
+    addr[15] = rloc16 & 0xff;
+    return addr;
+}
+
+/**
+ * Format a 16-byte IPv6 address as colon-separated hextets with leading zeros
+ * trimmed. No `::` compression — for logs, where unambiguity beats brevity.
+ */
+export function formatIp6(addr: Uint8Array): string {
+    if (addr.length !== 16) {
+        throw new ImplementationError(`formatIp6: address must be 16 bytes, got ${addr.length}`);
+    }
+    const groups = new Array<string>();
+    for (let i = 0; i < 16; i += 2) {
+        groups.push(((addr[i] << 8) | addr[i + 1]).toString(16));
+    }
+    return groups.join(":");
+}
+
+function realmLocal(lastByte: number): Uint8Array {
+    const addr = new Uint8Array(16);
+    addr[0] = 0xff;
+    addr[1] = 0x03;
+    addr[15] = lastByte;
+    return addr;
+}