@matter/thread-br-client 0.0.1

package/src/diagnostic/connectMeshcop.ts

@@ -0,0 +1,122 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { type Environment, ImplementationError, Logger } from "@matter/general";
+import { CoapClient } from "../coap/CoapClient.js";
+import { Commissioner } from "../commissioner/Commissioner.js";
+import type { ThreadNetworkCredentials } from "../credentials/ThreadNetworkCredentials.js";
+import type { BorderRouterEntry } from "../discovery/BorderRouterEntry.js";
+import { connectDtls } from "../dtls/channel/connectDtls.js";
+import type { DtlsChannel } from "../dtls/channel/DtlsChannel.js";
+import type { DtlsConnectOpts } from "../dtls/channel/DtlsConnectOpts.js";
+import type { DiagnosticSource } from "./DiagnosticSource.js";
+import { MeshCopDiagnosticSource } from "./MeshCopDiagnosticSource.js";
+
+const logger = Logger.get("ConnectMeshcop");
+
+export interface ConnectMeshcopOpts {
+    creds: ThreadNetworkCredentials;
+    br: BorderRouterEntry;
+    /** Override the BR address selection. Bypasses the link-local guard. */
+    address?: string;
+    /** Override the BR port. Defaults to {@link BorderRouterEntry.meshcopPort}. */
+    port?: number;
+    /** Environment providing the {@link Network} and {@link Crypto} for the DTLS UDP transport. */
+    environment: Environment;
+    /** @internal — for testing. Override the DTLS connect seam. */
+    makeConnect?: (opts: DtlsConnectOpts) => Promise<DtlsChannel>;
+}
+
+export interface MeshcopHandle {
+    source: DiagnosticSource;
+    close: () => Promise<void>;
+}
+
+/**
+ * Set up the per-network MeshCoP plumbing for diagnostic queries:
+ * DTLS-EC-JPAKE handshake → CoAP client → Commissioner → MeshCopDiagnosticSource.
+ *
+ * Pure link-local (`fe80::/10`) IPv6 addresses are skipped: scope IDs are not
+ * preserved through every mDNS resolver path, and the main HA SkyConnect /
+ * Yellow / Green deployments always advertise a ULA address. If only
+ * link-local addresses are present, this throws with a clear message.
+ */
+export async function connectMeshcop(opts: ConnectMeshcopOpts): Promise<MeshcopHandle> {
+    const address = opts.address ?? selectBrAddress(opts.br.addresses);
+    const port = opts.port ?? opts.br.meshcopPort;
+    if (port === undefined) {
+        throw new ImplementationError("connectMeshcop: BR has no meshcopPort and no opts.port override");
+    }
+
+    logger.debug(`[ThreadDiag] connectMeshcop START ${address}:${port}`);
+    const dtlsStart = Date.now();
+    const channel = await (opts.makeConnect ?? connectDtls)({
+        address,
+        port,
+        password: opts.creds.pskc,
+        type: address.includes(":") ? "udp6" : "udp4",
+        environment: opts.environment,
+    });
+    logger.debug(`[ThreadDiag] DTLS handshake OK ${address}:${port} duration=${Date.now() - dtlsStart}ms`);
+
+    try {
+        const coap = new CoapClient(channel, opts.environment);
+        const commissioner = new Commissioner(coap);
+        const source = new MeshCopDiagnosticSource(commissioner, coap, opts.environment, opts.creds.meshLocalPrefix);
+        return {
+            source,
+            close: async () => {
+                logger.debug(`[ThreadDiag] connectMeshcop CLOSE ${address}:${port}`);
+                await coap.close();
+            },
+        };
+    } catch (err) {
+        logger.warn(`[ThreadDiag] connectMeshcop post-DTLS setup FAIL ${address}:${port}: ${err}`);
+        await channel.close().catch(() => {});
+        throw err;
+    }
+}
+
+function selectBrAddress(addresses: readonly string[]): string {
+    if (addresses.length === 0) {
+        throw new ImplementationError("connectMeshcop: BR has no addresses");
+    }
+
+    const usable = new Array<string>();
+    for (const addr of addresses) {
+        if (!isLinkLocal(addr)) usable.push(addr);
+    }
+    if (usable.length === 0) {
+        throw new ImplementationError(
+            "connectMeshcop: BR has only link-local addresses; scoped addresses not yet supported",
+        );
+    }
+
+    return rankAddress(usable)[0];
+}
+
+function isLinkLocal(addr: string): boolean {
+    const lower = addr.toLowerCase();
+    if (lower.startsWith("fe8") || lower.startsWith("fe9") || lower.startsWith("fea") || lower.startsWith("feb")) {
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Order: ULA IPv6 → other IPv6 → IPv4. ULA covers `fc00::/7` (`fc??`/`fd??`),
+ * which is what the OpenThread / OTBR routing prefix lives in.
+ */
+function rankAddress(addresses: readonly string[]): string[] {
+    const tier = (addr: string): number => {
+        const lower = addr.toLowerCase();
+        if (!lower.includes(":")) return 2;
+        if (lower.startsWith("fc") || lower.startsWith("fd")) return 0;
+        return 1;
+    };
+
+    return [...addresses].sort((a, b) => tier(a) - tier(b));
+}

package/src/diagnostic/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 MeshCoP diagnostic response carries malformed or missing TLVs. */
+export class ThreadDiagError extends MatterError {}

package/src/diagnostic/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export { connectMeshcop } from "./connectMeshcop.js";
+export type { ConnectMeshcopOpts, MeshcopHandle } from "./connectMeshcop.js";
+export { DefaultTlvSet } from "./DefaultTlvSet.js";
+export type { DiagnosticResponse } from "./DiagnosticResponse.js";
+export type { DiagnosticSource, QueryMulticastHandle, QueryMulticastOptions } from "./DiagnosticSource.js";
+export { MeshCopDiagnosticSource, ThreadDiagError } from "./MeshCopDiagnosticSource.js";
+export type { EnergyScanEntry, EnergyScanOpts, PanIdConflict, PanIdQueryOpts } from "./MeshCopDiagnosticSource.js";

package/src/discovery/BorderRouterEntry.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Single Thread Border Router record discovered via mDNS.
+ *
+ * The extended address (xa) is the 64-bit Thread MAC of the border agent and serves as
+ * the primary key. It is the same value as ThreadNetworkDiagnostics.NeighborTable.extAddress
+ * for a BR that is itself a Thread router, which is what allows the dashboard to join
+ * BRs onto external-device entries seen in commissioned-node neighbor tables.
+ */
+export interface BorderRouterEntry {
+    /** 16-char uppercase hex of the 64-bit Thread MAC. Primary key. */
+    extAddressHex: string;
+    /** 16-char uppercase hex of the extended PAN ID, when known. */
+    extendedPanIdHex?: string;
+    /** Friendly Thread network name (`_meshcop` TXT "nn"). */
+    networkName?: string;
+    /** Vendor name (`_meshcop` TXT "vn"). */
+    vendorName?: string;
+    /** Model name (`_meshcop` TXT "mn"). */
+    modelName?: string;
+    /** mDNS hostname from the SRV target, e.g. "Kuche.local.". */
+    hostname?: string;
+    /** Sorted IPv4 + IPv6 addresses resolved from the SRV target's A/AAAA records. */
+    addresses: string[];
+    /** Service port from the `_meshcop` SRV record. */
+    meshcopPort?: number;
+    /** Service port from the `_trel` SRV record. */
+    trelPort?: number;
+    /** Thread version, e.g. "1.3.0" (`_meshcop` TXT "tv"). */
+    threadVersion?: string;
+    /** Software/firmware version of the Border Router (`_meshcop` TXT "sv"). Vendor-extension. */
+    swVersion?: string;
+    /** MeshCoP TXT record format version (`_meshcop` TXT "rv"). */
+    recordVersion?: string;
+    /** Border agent ID hex (`_meshcop` TXT "dd" or "ai"); not always present. */
+    borderAgentIdHex?: string;
+    /** Raw 4-byte state bitmap as hex (`_meshcop` TXT "sb"). Flag parsing left to dashboard. */
+    stateBitmapHex?: string;
+    /** Active timestamp as hex (`_meshcop` TXT "at"). */
+    activeTimestampHex?: string;
+    /** Partition ID as hex (`_meshcop` TXT "pt"). */
+    partitionIdHex?: string;
+    /** Vendor-specific data domain name (`_meshcop` TXT "dn"). */
+    domainName?: string;
+    /** Which mDNS source(s) contributed to this entry. */
+    sources: ("meshcop" | "trel")[];
+    /** Epoch milliseconds of the most recent record install or update. */
+    lastSeen: number;
+}