@matter/thread-br-client 0.0.1

package/src/discovery/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export type { BorderRouterEntry } from "./BorderRouterEntry.js";
+export { BorderRouterRegistry } from "./BorderRouterRegistry.js";

package/src/dtls/channel/DtlsChannel.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { type Bytes, type ConnectedChannel, MatterError, type Transport } from "@matter/general";
+
+/** DTLS peer/wire/protocol failure (handshake give-up, malformed record, peer alert, ...). */
+export class DtlsError extends MatterError {}
+
+/**
+ * Public channel interface for an established DTLS 1.2 + EC-JPAKE session.
+ *
+ * Modeled on the matter.js {@link ConnectedChannel} contract (framed, fixed-peer,
+ * send/close/onClose plus an inbound {@link AsyncIterable}), but deliberately does
+ * NOT implement it: DTLS runs over UDP and delivers application data unreliably,
+ * so it cannot honor `ConnectedChannel.isReliable: true`. The CoAP layer consumes
+ * only this surface — it sends and receives application-data plaintexts, iterates
+ * inbound records, and closes the session. Handshake, key derivation, record
+ * framing, and transport binding are implementation details.
+ *
+ * Inbound plaintexts are delivered via async iteration with backpressure: the
+ * producer hands each plaintext to a waiting consumer, buffering only a bounded
+ * number of records when no consumer is pending. On close or fatal error the
+ * iterator drains any buffered records, then either ends or throws the stored
+ * {@link DtlsError} to the consumer.
+ *
+ * Single-consumer only: at most one iteration with one outstanding `next()` may
+ * be active at a time. A second concurrent `next()` throws rather than silently
+ * stranding the first.
+ */
+export interface DtlsChannel extends AsyncIterable<Bytes> {
+    /** Encrypt and transmit `bytes` as one DTLS application-data record. */
+    send(bytes: Bytes): Promise<void>;
+
+    /** Send close_notify (best-effort), tear down transport, end inbound iteration. */
+    close(): Promise<void>;
+
+    /** Register a listener for channel close/disconnect. */
+    onClose(listener: () => void): Transport.Listener;
+}

package/src/dtls/channel/DtlsConnectOpts.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Environment } from "@matter/general";
+
+/**
+ * Connection parameters consumed by {@link connectDtls}. The `random` and
+ * `ephemeralScalar` overrides exist for deterministic tests; production callers
+ * leave them unset and the channel wires in {@link Entropy}-backed defaults.
+ */
+export interface DtlsConnectOpts {
+    /** IPv6 (or IPv4) address of the peer's MeshCoP DTLS port. Link-local zone IDs (`%en0`) accepted. */
+    address: string;
+
+    /** UDP port (typically 49191 for the ot-cli simulator's MeshCoP service). */
+    port: number;
+
+    /** EC-JPAKE password (PSKc — 16 bytes for Thread MeshCoP). */
+    password: Uint8Array;
+
+    /** Override the IPv4/IPv6 binding hint; default inferred from `address`. */
+    type?: "udp4" | "udp6";
+
+    /** RFC 6347 §4.2.4 initial retransmit interval. Default 1000ms. */
+    initialRetransmitMs?: number;
+
+    /** RFC 6347 §4.2.4 retransmit cap (doubling stops here). Default 60000ms. */
+    maxRetransmitMs?: number;
+
+    /** Maximum retransmit attempts before giving up. Default 5 (~31s total at default initial). */
+    maxRetransmits?: number;
+
+    /** Path-MTU advisory. Default 1280 — the Thread mesh constraint. */
+    mtu?: number;
+
+    /** Connect timeout. Default 30000ms. */
+    connectTimeoutMs?: number;
+
+    /** Override `random()` for deterministic testing. Production: CSPRNG. */
+    random?: () => Uint8Array;
+
+    /** Override `ephemeralScalar()` for deterministic testing. Production: CSPRNG-backed. */
+    ephemeralScalar?: () => bigint;
+
+    /** Environment providing the {@link Network} used for the UDP transport and the {@link Crypto} entropy source. */
+    environment: Environment;
+}

package/src/dtls/channel/DtlsRetransmitTimer.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ImplementationError, Millis, Time, type Timer } from "@matter/general";
+
+/**
+ * Per-flight DTLS 1.2 retransmit timer (RFC 6347 §4.2.4).
+ *
+ * On `armNewFlight()` the timer is scheduled at `initialMs`. On each fire it
+ * invokes `onRetransmit`, doubles the next interval (capped at `maxMs`), and
+ * increments the attempt counter. After `maxRetransmits` attempts the timer
+ * stops and `onGiveUp` is invoked instead. `cancel()` (e.g. when the next
+ * inbound flight implicitly acknowledges the previous one) is idempotent.
+ *
+ * Tests use MockTime to control timer advancement deterministically.
+ */
+export interface DtlsRetransmitTimerOpts {
+    /** Initial delay before the first retransmit fires. */
+    initialMs: number;
+    /** Cap on the doubling sequence — RFC 6347 §4.2.4 default 60_000ms. */
+    maxMs: number;
+    /** Maximum retransmits before invoking `onGiveUp`. */
+    maxRetransmits: number;
+    /** Fired each retransmit (caller re-emits the last flight). */
+    onRetransmit: () => void;
+    /** Fired once after `maxRetransmits` attempts have elapsed without acknowledgement. */
+    onGiveUp: () => void;
+}
+
+export class DtlsRetransmitTimer {
+    readonly #initialMs: number;
+    readonly #maxMs: number;
+    readonly #maxRetransmits: number;
+    readonly #onRetransmit: () => void;
+    readonly #onGiveUp: () => void;
+
+    #timer: Timer | undefined;
+    #attempt = 0;
+    #nextDelayMs: number;
+
+    constructor(opts: DtlsRetransmitTimerOpts) {
+        if (opts.initialMs <= 0) {
+            throw new ImplementationError(`DtlsRetransmitTimer initialMs must be > 0, got ${opts.initialMs}`);
+        }
+        if (opts.maxMs < opts.initialMs) {
+            throw new ImplementationError(
+                `DtlsRetransmitTimer maxMs ${opts.maxMs} must be >= initialMs ${opts.initialMs}`,
+            );
+        }
+        if (opts.maxRetransmits < 1) {
+            throw new ImplementationError(
+                `DtlsRetransmitTimer maxRetransmits must be >= 1, got ${opts.maxRetransmits}`,
+            );
+        }
+        this.#initialMs = opts.initialMs;
+        this.#maxMs = opts.maxMs;
+        this.#maxRetransmits = opts.maxRetransmits;
+        this.#onRetransmit = opts.onRetransmit;
+        this.#onGiveUp = opts.onGiveUp;
+        this.#nextDelayMs = opts.initialMs;
+    }
+
+    /**
+     * Arm or re-arm the timer for a freshly emitted flight, resetting the attempt
+     * counter and the doubling delay back to `initialMs`.
+     */
+    armNewFlight(): void {
+        this.cancel();
+        this.#attempt = 0;
+        this.#nextDelayMs = this.#initialMs;
+        this.#schedule();
+    }
+
+    /** Cancel any pending timer. Safe to call when not armed. */
+    cancel(): void {
+        this.#timer?.stop();
+        this.#timer = undefined;
+    }
+
+    isArmed(): boolean {
+        return this.#timer !== undefined;
+    }
+
+    /** Visible for tests — current attempt count (0 before the first fire). */
+    get attempt(): number {
+        return this.#attempt;
+    }
+
+    #schedule(): void {
+        const delay = this.#nextDelayMs;
+        this.#timer = Time.getTimer("dtls-retransmit", Millis(delay), () => {
+            this.#timer = undefined;
+            this.#attempt += 1;
+            if (this.#attempt > this.#maxRetransmits) {
+                this.#onGiveUp();
+                return;
+            }
+            this.#onRetransmit();
+            // RFC 6347 §4.2.4 — double the next interval, capped at maxMs.
+            this.#nextDelayMs = Math.min(this.#nextDelayMs * 2, this.#maxMs);
+            this.#schedule();
+        }).start();
+    }
+}