@matter/thread-br-client 0.0.1 → 0.17.5-alpha.0-20260706-fd4c49e2e

package/src/otbr-rest/OtbrRestClient.ts

@@ -6,8 +6,9 @@
 
 import { Bytes, type Duration, ImplementationError, Millis, Seconds, Time, Timer } from "@matter/general";
 import { OperationalDataset } from "../dataset/OperationalDataset.js";
-import { normalizeKeys } from "./caseNormalizer.js";
+import { detectKeyFormat, normalizeKeys } from "./caseNormalizer.js";
 import { OtbrRestError, type OtbrRestErrorCode } from "./OtbrRestError.js";
+import { parseHexBytes, parseRloc16 } from "./parseHexBytes.js";
 
 export interface OtbrLeaderData {
     partitionId: number;
@@ -18,15 +19,16 @@ export interface OtbrLeaderData {
 }
 
 export interface OtbrNodeInfo {
-    baId: Uint8Array;
+    baId: Bytes;
     state: string;
-    numOfRouter: number;
+    /** Router count. Undefined on builds that omit both `numOfRouter` and its post-2024 alias `routerCount`. */
+    numOfRouter?: number;
     rlocAddress: string;
-    extAddress: Uint8Array;
+    extAddress: Bytes;
     networkName: string;
     rloc16: number;
     leaderData: OtbrLeaderData;
-    extPanId: Uint8Array;
+    extPanId: Bytes;
 }
 
 export interface OtbrDatasetHex {
@@ -80,6 +82,7 @@ function errorCodeForStatus(status: number): OtbrRestErrorCode {
 interface FetchedJson {
     status: number;
     body: unknown;
+    keyFormat: "camel" | "pascal" | null;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -102,6 +105,23 @@ function expectNumber(record: Record<string, unknown>, key: string, where: strin
     return value;
 }
 
+/** First finite number found under any of `keys`, else `undefined`. */
+function optionalNumber(record: Record<string, unknown>, ...keys: string[]): number | undefined {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "number" && Number.isFinite(value)) return value;
+    }
+    return undefined;
+}
+
+function expectRloc16(record: Record<string, unknown>, where: string): number {
+    const parsed = parseRloc16(record["rloc16"]);
+    if (parsed === undefined) {
+        throw new OtbrRestError("rest_protocol", `${where}: missing or invalid field rloc16`);
+    }
+    return parsed;
+}
+
 function expectRecord(record: Record<string, unknown>, key: string, where: string): Record<string, unknown> {
     const value = record[key];
     if (!isRecord(value)) {
@@ -110,16 +130,6 @@ function expectRecord(record: Record<string, unknown>, key: string, where: strin
     return value;
 }
 
-function parseHexBytes(hex: string, expectedLen: number, where: string): Uint8Array {
-    if (!/^[0-9a-fA-F]*$/.test(hex)) {
-        throw new OtbrRestError("rest_protocol", `${where}: not hex`);
-    }
-    if (hex.length !== expectedLen * 2) {
-        throw new OtbrRestError("rest_protocol", `${where}: expected ${expectedLen} bytes, got ${hex.length / 2}`);
-    }
-    return Bytes.of(Bytes.fromHex(hex));
-}
-
 /**
  * Thin HTTP client for the OpenThread Border Router (OTBR) REST API.
  *
@@ -155,7 +165,7 @@ export class OtbrRestClient {
     /**
      * Fetch the current node summary from the OTBR `/node` endpoint.
      *
-     * @returns Parsed node info with typed fields (binary fields as `Uint8Array`).
+     * @returns Parsed node info with typed fields (binary fields as `Bytes`).
      * @throws {@link OtbrRestError} with code `"rest_unreachable"` on network error or timeout.
      * @throws {@link OtbrRestError} with code `"rest_protocol"` when the response is
      *   not a valid JSON object or a required field is missing or has the wrong type.
@@ -175,15 +185,39 @@ export class OtbrRestClient {
             leaderRouterId: expectNumber(leaderRaw, "leaderRouterId", `${where}.leaderData`),
         };
         return {
-            baId: parseHexBytes(expectString(body, "baId", where), 16, `${where}.baId`),
+            baId: parseHexBytes(expectString(body, "baId", where), `${where}.baId`, 16),
             state: expectString(body, "state", where),
-            numOfRouter: expectNumber(body, "numOfRouter", where),
+            numOfRouter: optionalNumber(body, "numOfRouter", "routerCount"),
             rlocAddress: expectString(body, "rlocAddress", where),
-            extAddress: parseHexBytes(expectString(body, "extAddress", where), 8, `${where}.extAddress`),
+            extAddress: parseHexBytes(expectString(body, "extAddress", where), `${where}.extAddress`, 8),
             networkName: expectString(body, "networkName", where),
-            rloc16: expectNumber(body, "rloc16", where),
+            rloc16: expectRloc16(body, where),
             leaderData,
-            extPanId: parseHexBytes(expectString(body, "extPanId", where), 8, `${where}.extPanId`),
+            extPanId: parseHexBytes(expectString(body, "extPanId", where), `${where}.extPanId`, 8),
+        };
+    }
+
+    /**
+     * Lightweight probe of the `/node` endpoint for {@link OtbrRestProbe}.
+     *
+     * Fetches `/node` once and returns only the fields needed to identify an
+     * OTBR REST surface — the observed key casing plus the network name and
+     * Extended PAN ID. Unlike {@link getNode} it does not validate the full
+     * node schema, so a build that reshapes non-essential fields still probes
+     * cleanly.
+     *
+     * @throws {@link OtbrRestError} `"rest_protocol"` when the response is not an
+     *   OTBR node object or lacks `networkName`/`extPanId`.
+     */
+    async probeNode(): Promise<{ keyFormat: "camel" | "pascal"; networkName: string; extPanId: Bytes }> {
+        const { body, keyFormat } = await this.#fetchJson("/node");
+        if (!isRecord(body) || keyFormat === null) {
+            throw new OtbrRestError("rest_protocol", "/node did not return an OTBR node object");
+        }
+        return {
+            keyFormat,
+            networkName: expectString(body, "networkName", "/node"),
+            extPanId: parseHexBytes(expectString(body, "extPanId", "/node"), "/node.extPanId", 8),
         };
     }
 
@@ -268,15 +302,15 @@ export class OtbrRestClient {
     /**
      * Fetch the 8-byte IEEE EUI-64 extended address from `/node/ext-address`.
      */
-    async getExtAddress(): Promise<Uint8Array> {
-        return parseHexBytes(await this.#getJsonString("/node/ext-address"), 8, "/node/ext-address");
+    async getExtAddress(): Promise<Bytes> {
+        return parseHexBytes(await this.#getJsonString("/node/ext-address"), "/node/ext-address", 8);
     }
 
     /**
      * Fetch the 8-byte Extended PAN ID from `/node/ext-panid`.
      */
-    async getExtPanId(): Promise<Uint8Array> {
-        return parseHexBytes(await this.#getJsonString("/node/ext-panid"), 8, "/node/ext-panid");
+    async getExtPanId(): Promise<Bytes> {
+        return parseHexBytes(await this.#getJsonString("/node/ext-panid"), "/node/ext-panid", 8);
     }
 
     /**
@@ -284,8 +318,8 @@ export class OtbrRestClient {
      *
      * @throws {@link OtbrRestError} `"rest_unsupported"` on older firmware that lacks this endpoint (404).
      */
-    async getBorderAgentId(): Promise<Uint8Array> {
-        return parseHexBytes(await this.#getJsonString("/node/ba-id"), 16, "/node/ba-id");
+    async getBorderAgentId(): Promise<Bytes> {
+        return parseHexBytes(await this.#getJsonString("/node/ba-id"), "/node/ba-id", 16);
     }
 
     /**
@@ -555,7 +589,7 @@ export class OtbrRestClient {
     async #fetchJson(path: string): Promise<FetchedJson> {
         const response = await this.#doFetch(path, "application/json");
         if (response.status === HTTP_NO_CONTENT) {
-            return { status: response.status, body: null };
+            return { status: response.status, body: null, keyFormat: null };
         }
         if (!response.ok) {
             throw new OtbrRestError(errorCodeForStatus(response.status), `GET ${path} returned ${response.status}`, {
@@ -570,7 +604,8 @@ export class OtbrRestClient {
                 cause: err instanceof Error ? err : undefined,
             });
         }
-        return { status: response.status, body: normalizeKeys(parsed) };
+        const keyFormat = isRecord(parsed) ? detectKeyFormat(parsed) : null;
+        return { status: response.status, body: normalizeKeys(parsed), keyFormat };
     }
 
     async #fetchText(path: string): Promise<string | undefined> {

package/src/otbr-rest/OtbrRestDiagnosticSource.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Bytes, Logger, Observable } from "@matter/general";
+import { Bytes, errorOf, Logger, Observable } from "@matter/general";
 import type { DiagnosticResponse } from "../diagnostic/DiagnosticResponse.js";
 import type { DiagnosticSource, QueryMulticastHandle, QueryMulticastOptions } from "../diagnostic/DiagnosticSource.js";
 import { DEFAULT_RESET_TLV_TYPES } from "../diagnostic/DiagnosticSource.js";
@@ -49,7 +49,7 @@ export class OtbrRestDiagnosticSource implements DiagnosticSource {
      *
      * @param extPanId - 8-byte Extended PAN ID of the network to query.
      */
-    canQuery(extPanId: Uint8Array): boolean {
+    canQuery(extPanId: Bytes): boolean {
         return Bytes.areEqual(extPanId, this.#capability.extPanId);
     }
 
@@ -116,17 +116,17 @@ export class OtbrRestDiagnosticSource implements DiagnosticSource {
         });
 
         const start = Date.now();
-        logger.debug(`[ThreadDiag] REST GET /diagnostics ${this.#capability.baseUrl}`);
+        logger.debug(`REST GET /diagnostics ${this.#capability.baseUrl}`);
         void (async () => {
             try {
                 const list = await this.#client.getDiagnostics();
                 for (const entry of list) {
                     onNode.emit(translateNodeJson(entry));
                 }
-                logger.debug(`[ThreadDiag] REST /diagnostics OK nodes=${list.length} duration=${Date.now() - start}ms`);
+                logger.debug(`REST /diagnostics OK nodes=${list.length} duration=${Date.now() - start}ms`);
                 resolveDone();
             } catch (err) {
-                const e = err instanceof Error ? err : new Error(String(err));
+                const e = errorOf(err);
                 onError.emit(e);
                 rejectDone(e);
             }

package/src/otbr-rest/OtbrRestProbe.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Bytes, Logger, Millis, Seconds, Time, Timer } from "@matter/general";
+import { Bytes, Logger, Seconds } from "@matter/general";
 import type { OtbrRestCapability } from "./OtbrRestCapability.js";
 import { OtbrRestClient } from "./OtbrRestClient.js";
 import { OtbrRestError } from "./OtbrRestError.js";
@@ -14,16 +14,15 @@ const logger = Logger.get("OtbrRestProbe");
 const DEFAULT_PROBE_PORT = 8081;
 const DEFAULT_PROBE_TIMEOUT = Seconds(1);
 
-const HTTP_OK = 200;
-const HTTP_NOT_FOUND = 404;
-
 export class OtbrRestProbe {
     /**
      * Probe a host:port for OTBR REST. Returns the detected capability or
-     * `null` if the endpoint is not OTBR or not reachable within
-     * `timeoutMs`. Detection mirrors python-otbr-api: a 200 on
-     * `/api/actions` indicates the modern camelCase backend, a 404 the
-     * legacy pascalCase backend; everything else is "not OTBR".
+     * `null` if the endpoint is not OTBR or not reachable within `timeoutMs`.
+     *
+     * A single `GET /node` both confirms the endpoint is OTBR and reveals its
+     * key casing: legacy builds emit PascalCase keys, post-2024 builds
+     * camelCase. Anything that is not a JSON object carrying `networkName` and
+     * `extPanId` is treated as "not OTBR".
      */
     static async probe(
         host: string,
@@ -32,54 +31,20 @@ export class OtbrRestProbe {
     ): Promise<OtbrRestCapability | null> {
         const client = new OtbrRestClient({ host, port, timeoutMs });
         const baseUrl = client.baseUrl;
-        logger.debug(`[ThreadDiag] probe START ${baseUrl} timeout=${timeoutMs}ms`);
-
-        const keyFormat = await detectCase(baseUrl, timeoutMs);
-        if (keyFormat === null) {
-            logger.debug(`[ThreadDiag] probe MISS ${baseUrl} (case detect failed)`);
-            return null;
-        }
+        logger.debug(`probe START ${baseUrl} timeout=${timeoutMs}ms`);
 
         try {
-            const node = await client.getNode();
+            const { keyFormat, networkName, extPanId } = await client.probeNode();
             logger.debug(
-                `[ThreadDiag] probe OK ${baseUrl} keyFormat=${keyFormat} xp=${Bytes.toHex(node.extPanId).toUpperCase()} network="${node.networkName}"`,
+                `probe OK ${baseUrl} keyFormat=${keyFormat} xp=${Bytes.toHex(extPanId).toUpperCase()} network="${networkName}"`,
             );
-            return {
-                baseUrl,
-                keyFormat,
-                probedAt: Date.now(),
-                networkName: node.networkName,
-                extPanId: node.extPanId,
-            };
+            return { baseUrl, keyFormat, probedAt: Date.now(), networkName, extPanId };
         } catch (err) {
             if (err instanceof OtbrRestError) {
-                logger.debug(`[ThreadDiag] probe MISS ${baseUrl} /node ${err.code} (${err.message})`);
+                logger.debug(`probe MISS ${baseUrl} /node ${err.code} (${err.message})`);
                 return null;
             }
             throw err;
         }
     }
 }
-
-async function detectCase(baseUrl: string, timeoutMs: number): Promise<"camel" | "pascal" | null> {
-    const controller = new AbortController();
-    const timer: Timer = Time.getTimer("otbr-probe-timeout", Millis(timeoutMs), () => controller.abort()).start();
-    try {
-        const response = await fetch(`${baseUrl}/api/actions`, {
-            method: "GET",
-            headers: { Accept: "application/json" },
-            signal: controller.signal,
-        });
-        if (response.status === HTTP_OK) return "camel";
-        if (response.status === HTTP_NOT_FOUND) return "pascal";
-        logger.debug(`probe of ${baseUrl} rejected: /api/actions returned ${response.status}`);
-        return null;
-    } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        logger.debug(`probe of ${baseUrl} rejected: /api/actions ${message}`);
-        return null;
-    } finally {
-        timer.stop();
-    }
-}

package/src/otbr-rest/caseNormalizer.ts

@@ -29,6 +29,23 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
     return proto === Object.prototype || proto === null;
 }
 
+/**
+ * Classify an OTBR REST response object by its key casing: legacy builds emit
+ * PascalCase (`NetworkName`), post-2024 builds camelCase (`networkName`). Any
+ * uppercase-first key marks the object as pascal; a non-empty object with only
+ * lowercase-first keys is camel. An empty object yields `null` — no signal.
+ */
+export function detectKeyFormat(raw: Record<string, unknown>): "camel" | "pascal" | null {
+    let sawKey = false;
+    for (const key of Object.keys(raw)) {
+        if (key.length === 0) continue;
+        sawKey = true;
+        const first = key.charCodeAt(0);
+        if (first >= 65 && first <= 90) return "pascal";
+    }
+    return sawKey ? "camel" : null;
+}
+
 /**
  * Recursively rewrites object keys from PascalCase (or already-camelCase) to
  * camelCase. Idempotent — running it twice yields identical output. Arrays,

package/src/otbr-rest/parseHexBytes.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes } from "@matter/general";
+import { OtbrRestError } from "./OtbrRestError.js";
+
+/**
+ * Decode a hex string into {@link Bytes}, rejecting non-hex characters, odd
+ * length, and (if `expectedLen` is given) a wrong byte count.
+ *
+ * `Bytes.fromHex` does not itself reject non-hex characters, so this
+ * validation is load-bearing.
+ */
+export function parseHexBytes(hex: string, where: string, expectedLen?: number): Bytes {
+    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.fromHex(hex);
+}
+
+const RLOC16_MAX = 0xffff;
+const RLOC16_STRING = /^(?:0x[0-9a-fA-F]{1,4}|[0-9]{1,5})$/;
+
+/**
+ * Parse a 16-bit RLOC, accepting either a JSON number (legacy builds) or a hex
+ * string like `"0x4800"` (post-2024 builds). Returns `undefined` for absent,
+ * malformed, or out-of-16-bit-range input — callers decide whether that is an
+ * error (`/node`) or a skippable field (`/diagnostics`).
+ */
+export function parseRloc16(value: unknown): number | undefined {
+    const parsed =
+        typeof value === "number"
+            ? value
+            : typeof value === "string" && RLOC16_STRING.test(value)
+              ? Number(value)
+              : NaN;
+    return Number.isInteger(parsed) && parsed >= 0 && parsed <= RLOC16_MAX ? parsed : undefined;
+}

package/src/otbr-rest/translation.ts

@@ -15,6 +15,7 @@ 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";
+import { parseHexBytes, parseRloc16 } from "./parseHexBytes.js";
 
 const TIMEOUT_EXP_MIN = 4;
 const IPV6_BYTES = 16;
@@ -46,19 +47,6 @@ function requireNumber(record: Record<string, unknown>, key: string, where: stri
     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,
@@ -133,12 +121,26 @@ function translateMacCounters(input: Record<string, unknown>): MacCounters {
     };
 }
 
+const UINT64_MAX = 18446744073709551615n;
+
 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));
+    let n: bigint;
+    if (typeof v === "bigint") {
+        n = v;
+    } else if (typeof v === "string" && /^\d+$/.test(v)) {
+        // 64-bit counters exceed 2^53, so some producers emit them as decimal
+        // strings; decode those directly to preserve full precision.
+        n = BigInt(v);
+    } else {
+        const num = asNumber(v);
+        if (num === undefined) throw new OtbrRestError("rest_protocol", `${where}: missing numeric ${key}`);
+        n = BigInt(Math.trunc(num));
+    }
+    // These fields are defined as uint64; reject anything outside that range
+    // regardless of how it was encoded.
+    if (n < 0n || n > UINT64_MAX) throw new OtbrRestError("rest_protocol", `${where}: ${key} outside uint64 range`);
+    return n;
 }
 
 function translateMleCounters(input: Record<string, unknown>): MleCounters {
@@ -192,7 +194,7 @@ function translateChildTable(input: unknown[]): ChildTableEntry[] {
  * compression. Does not handle IPv4-mapped (`::ffff:1.2.3.4`) or zone IDs
  * (`%`); OTBR `IP6AddressList` never returns either.
  */
-function parseIpv6(text: string): Uint8Array {
+function parseIpv6(text: string): Bytes {
     if (text.includes("%")) {
         throw new OtbrRestError("rest_protocol", `ipv6: zone ID not supported in ${text}`);
     }
@@ -250,14 +252,14 @@ 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 result: DiagnosticResponse = { unknown: new Array<{ type: number; value: Bytes }>() };
 
     const extAddress = asString(json["extAddress"]);
     if (extAddress !== undefined) {
         result.extMacAddress = parseHexBytes(extAddress, "extAddress", 8);
     }
 
-    const rloc16 = asNumber(json["rloc16"]);
+    const rloc16 = parseRloc16(json["rloc16"]);
     if (rloc16 !== undefined) result.rloc16 = rloc16;
 
     const mode = asRecord(json["mode"]);
@@ -282,7 +284,7 @@ export function translateNodeJson(json: unknown): DiagnosticResponse {
 
     const ip6Addresses = asArray(json["ip6AddressList"]);
     if (ip6Addresses !== undefined) {
-        const list = new Array<Uint8Array>();
+        const list = new Array<Bytes>();
         for (const entry of ip6Addresses) {
             const text = asString(entry);
             if (text === undefined) {
@@ -305,7 +307,7 @@ export function translateNodeJson(json: unknown): DiagnosticResponse {
     const channelPages = asString(json["channelPages"]);
     if (channelPages !== undefined) {
         const bytes = parseHexBytes(channelPages, "channelPages");
-        result.channelPages = Array.from(bytes);
+        result.channelPages = Array.from(Bytes.of(bytes));
     }
 
     const maxChildTimeout = asNumber(json["maxChildTimeout"]);

package/src/selection/selectBr.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { ServerAddress } from "@matter/general";
 import type { BorderRouterEntry } from "../discovery/BorderRouterEntry.js";
 
 /**
@@ -38,10 +39,16 @@ export function decodeStateBitmap(hex: string | undefined): DecodedStateBitmap {
 }
 
 function hasLinkLocal(addresses: ReadonlyArray<string>): boolean {
-    for (const addr of addresses) {
-        if (addr.toLowerCase().startsWith("fe80:")) return true;
-    }
-    return false;
+    return addresses.some(ServerAddress.isIpv6LinkLocal);
+}
+
+/**
+ * A BR is dialable only if it exposes at least one non-link-local address:
+ * `connectMeshcop` rejects link-local-only BRs (scope IDs are not preserved
+ * through every mDNS resolver path).
+ */
+function hasDialableAddress(addresses: ReadonlyArray<string>): boolean {
+    return addresses.some(addr => !ServerAddress.isIpv6LinkLocal(addr));
 }
 
 function scoreOf(br: BorderRouterEntry): number {
@@ -54,10 +61,11 @@ function scoreOf(br: BorderRouterEntry): number {
 }
 
 /**
- * Pick the best BR per spec FR-12 priority:
+ * Pick the best dialable BR. BRs without a non-link-local address are excluded
+ * (see {@link rankBrs}); the rest are ordered by 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.
+ *   3. Among equals: BR with at least one IPv6 link-local (`fe80::/10`) address wins.
  *   4. Among equals: alphabetical `extAddressHex` ascending (deterministic tie-break).
  */
 export function selectBr(brs: ReadonlyArray<BorderRouterEntry>): BorderRouterEntry | undefined {
@@ -65,13 +73,18 @@ export function selectBr(brs: ReadonlyArray<BorderRouterEntry>): BorderRouterEnt
 }
 
 /**
- * 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.
+ * Rank dialable candidate BRs best-first using the same priority as
+ * {@link selectBr}. BRs without a non-link-local address are dropped — they
+ * can never be dialed (see {@link hasDialableAddress}), so returning them would
+ * only waste a connect attempt. 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;
-    });
+    return brs
+        .filter(br => hasDialableAddress(br.addresses))
+        .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/withExtPanIdLock.ts

@@ -22,7 +22,7 @@ export class ExtPanIdLockManager {
      * 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> {
+    withLock<T>(extPanId: Bytes, fn: () => Promise<T>): Promise<T> {
         const key = Bytes.toHex(extPanId);
         const previous = this.#queues.get(key) ?? Promise.resolve();
         const result = previous.then(() => fn());

package/src/tlv/BasicTlvCodec.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { InternalError, MatterError } from "@matter/general";
+import { Bytes, InternalError, MatterError } from "@matter/general";
 
 /** Low-level MeshCoP/base TLV codec parse failure (truncated stream, bad length, ...). */
 export class ThreadTlvError extends MatterError {}
@@ -15,48 +15,49 @@ export class ThreadTlvError extends MatterError {}
  */
 export interface BasicTlvEntry {
     type: number;
-    value: Uint8Array;
+    value: Bytes;
 }
 
 export namespace BasicTlv {
-    export function walk(blob: Uint8Array): BasicTlvEntry[] {
+    export function walk(blob: Bytes): BasicTlvEntry[] {
+        const buf = Bytes.of(blob);
         const out = new Array<BasicTlvEntry>();
         let offset = 0;
-        while (offset < blob.length) {
-            if (offset + 2 > blob.length) {
+        while (offset < buf.length) {
+            if (offset + 2 > buf.length) {
                 throw new ThreadTlvError(`Truncated TLV header at offset ${offset}`);
             }
-            const type = blob[offset];
-            const lenByte = blob[offset + 1];
+            const type = buf[offset];
+            const lenByte = buf[offset + 1];
             let length: number;
             let valueStart: number;
             if (lenByte === 0xff) {
-                if (offset + 4 > blob.length) {
+                if (offset + 4 > buf.length) {
                     throw new ThreadTlvError(`Truncated extended-length TLV header at offset ${offset}`);
                 }
-                length = (blob[offset + 2] << 8) | blob[offset + 3];
+                length = (buf[offset + 2] << 8) | buf[offset + 3];
                 valueStart = offset + 4;
             } else {
                 length = lenByte;
                 valueStart = offset + 2;
             }
             const valueEnd = valueStart + length;
-            if (valueEnd > blob.length) {
+            if (valueEnd > buf.length) {
                 throw new ThreadTlvError(`Truncated TLV value at offset ${offset} (type=${type}, length=${length})`);
             }
-            out.push({ type, value: blob.slice(valueStart, valueEnd) });
+            out.push({ type, value: buf.slice(valueStart, valueEnd) });
             offset = valueEnd;
         }
         return out;
     }
 
-    export function encode(entries: ReadonlyArray<BasicTlvEntry>): Uint8Array {
+    export function encode(entries: ReadonlyArray<BasicTlvEntry>): Bytes {
         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;
+            const valueLen = entry.value.byteLength;
             if (valueLen > 0xffff) {
                 throw new InternalError(`Invalid TLV length ${valueLen}: must be <= 0xFFFF`);
             }
@@ -66,7 +67,8 @@ export namespace BasicTlv {
         const out = new Uint8Array(totalLength);
         let offset = 0;
         for (const entry of entries) {
-            const valueLen = entry.value.length;
+            const value = Bytes.of(entry.value);
+            const valueLen = value.length;
             out[offset++] = entry.type;
             if (valueLen >= 0xff) {
                 out[offset++] = 0xff;
@@ -75,7 +77,7 @@ export namespace BasicTlv {
             } else {
                 out[offset++] = valueLen;
             }
-            out.set(entry.value, offset);
+            out.set(value, offset);
             offset += valueLen;
         }
         return out;