@matter/thread-br-client 0.0.1

package/src/commissioner/Commissioner.ts

@@ -0,0 +1,205 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { type Duration, Logger, MatterError, Millis, Seconds, Time, TimeoutError, type Timer } from "@matter/general";
+import type { CoapClient } from "../coap/CoapClient.js";
+import { MeshCopTlvType } from "../dataset/meshcopTlvTypes.js";
+import { BasicTlv } from "../tlv/BasicTlvCodec.js";
+import { LeadKa } from "./LeadKa.js";
+import { LeadPet } from "./LeadPet.js";
+
+const logger = Logger.get("Commissioner");
+
+/** Thrown by {@link Commissioner.petition} when the Border Router explicitly rejects the petition. */
+export class CommissionerRejectedError extends MatterError {
+    constructor() {
+        super("Commissioner petition rejected by Border Router");
+        this.name = "CommissionerRejectedError";
+    }
+}
+
+/** Thrown by {@link Commissioner.petition} when the petition is still pending after one retry. */
+export class CommissionerTimeoutError extends TimeoutError {
+    constructor() {
+        super("Commissioner petition timed out (still pending after retry)");
+        this.name = "CommissionerTimeoutError";
+    }
+}
+
+/** Thrown by {@link Commissioner.keepAlive} when the Border Router answers with a non-accept state. */
+export class CommissionerKeepAliveError extends MatterError {}
+
+export interface CommissionerOpts {
+    /** Override the 30s pending-retry delay. Intended for testing. */
+    pendingRetryDelayMs?: number;
+}
+
+/**
+ * Thread MeshCoP Commissioner — petitions for, maintains, and releases a
+ * commissioner session over an already-connected CoAP transport.
+ *
+ * Callers should prefer {@link Commissioner.withSession} for the full
+ * petition → keep-alive → release lifecycle. Use `petition`/`keepAlive`/`release`
+ * directly only when finer-grained control is needed.
+ */
+export class Commissioner {
+    static readonly COMMISSIONER_ID = "matter-server";
+    static readonly #KA_INTERVAL = Seconds(40);
+    static readonly #PENDING_RETRY_DELAY = Seconds(30);
+
+    readonly #coap: CoapClient;
+    readonly #pendingRetryDelay: Duration;
+
+    /**
+     * @param coap - CoAP transport connected to the target Border Router.
+     * @param opts - Optional overrides (e.g. `pendingRetryDelayMs` for tests).
+     */
+    constructor(coap: CoapClient, opts?: CommissionerOpts) {
+        this.#coap = coap;
+        this.#pendingRetryDelay =
+            opts?.pendingRetryDelayMs !== undefined
+                ? Millis(opts.pendingRetryDelayMs)
+                : Commissioner.#PENDING_RETRY_DELAY;
+    }
+
+    /**
+     * Send a MeshCoP `COMM_PET` (commissioner petition) request.
+     *
+     * When the BR responds `pending`, retries once after `pendingRetryDelayMs`
+     * (default 30 s). Accepts on the first `accept` response.
+     *
+     * @returns The commissioner session ID assigned by the Border Router.
+     * @throws {@link CommissionerRejectedError} when the BR returns `reject` on
+     *   the initial petition or on the retry.
+     * @throws {@link CommissionerTimeoutError} when the BR returns `pending` on
+     *   both the initial petition and the retry.
+     * @throws `Error` on CoAP transport or TLV parse failure.
+     */
+    async petition(): Promise<number> {
+        const response = await this.#coap.request({
+            type: "CON",
+            code: "0.02",
+            uriPath: ["c", "cp"],
+            payload: LeadPet.buildRequest(Commissioner.COMMISSIONER_ID),
+        });
+
+        logger.debug(`[ThreadDiag] COMM_PET response code=${response.code} payloadLen=${response.payload.length}`);
+        const parsed = LeadPet.parseResponse(response.payload);
+
+        if (parsed.state === "accept") {
+            return parsed.sessionId!;
+        }
+
+        if (parsed.state === "reject") {
+            throw new CommissionerRejectedError();
+        }
+
+        // pending: wait and retry once
+        await Time.sleep("commissioner-pending-retry", this.#pendingRetryDelay);
+
+        const retryResponse = await this.#coap.request({
+            type: "CON",
+            code: "0.02",
+            uriPath: ["c", "cp"],
+            payload: LeadPet.buildRequest(Commissioner.COMMISSIONER_ID),
+        });
+
+        const retryParsed = LeadPet.parseResponse(retryResponse.payload);
+
+        if (retryParsed.state === "accept") {
+            return retryParsed.sessionId!;
+        }
+
+        if (retryParsed.state === "reject") {
+            throw new CommissionerRejectedError();
+        }
+
+        throw new CommissionerTimeoutError();
+    }
+
+    /**
+     * Send a MeshCoP `COMM_KA` (commissioner keep-alive) request.
+     *
+     * Must be called periodically (typically every ~40 s) while the session is
+     * active; the BR will revoke the session if no keep-alive is received within
+     * its timeout window. Prefer {@link Commissioner.withSession}, which schedules
+     * keep-alives automatically.
+     *
+     * @param sessionId - Session ID returned by {@link petition}.
+     * @throws {@link CommissionerKeepAliveError} when the BR rejects the keep-alive; propagates CoAP errors.
+     */
+    async keepAlive(sessionId: number): Promise<void> {
+        const response = await this.#coap.request({
+            type: "CON",
+            code: "0.02",
+            uriPath: ["c", "ka"],
+            payload: LeadKa.buildRequest(sessionId),
+        });
+
+        const parsed = LeadKa.parseResponse(response.payload);
+        if (parsed.state !== "accept") {
+            throw new CommissionerKeepAliveError(`Commissioner keep-alive rejected: state=${parsed.state}`);
+        }
+    }
+
+    /**
+     * Send a MeshCoP `COMM_REL` (commissioner release) request.
+     *
+     * Best-effort — CoAP errors are logged at `warn` level and swallowed so a
+     * failed release does not block teardown. The BR will expire the session on
+     * its own if the release is lost.
+     *
+     * @param sessionId - Session ID returned by {@link petition}.
+     */
+    async release(sessionId: number): Promise<void> {
+        try {
+            // COMM_REL requires both COMMISSIONER_SESSION_ID and COMMISSIONER_ID (Thread spec Table 8-16).
+            const sessionBytes = new Uint8Array(2);
+            sessionBytes[0] = (sessionId >> 8) & 0xff;
+            sessionBytes[1] = sessionId & 0xff;
+            const releasePayload = BasicTlv.encode([
+                { type: MeshCopTlvType.COMMISSIONER_SESSION_ID, value: sessionBytes },
+                { type: MeshCopTlvType.COMMISSIONER_ID, value: new TextEncoder().encode(Commissioner.COMMISSIONER_ID) },
+            ]);
+            await this.#coap.request({
+                type: "CON",
+                code: "0.02",
+                uriPath: ["c", "cr"],
+                payload: releasePayload,
+            });
+        } catch (err) {
+            logger.warn("Commissioner release failed (best-effort):", err);
+        }
+    }
+
+    /**
+     * Run `fn` inside a commissioner session, managing petition, keep-alive, and
+     * release automatically.
+     *
+     * Keep-alive requests fire every ~40 s while `fn` is executing. The session is
+     * released in a `finally` block regardless of whether `fn` resolves or rejects.
+     *
+     * @param fn - Async callback receiving the active session ID.
+     * @returns The value resolved by `fn`.
+     * @throws {@link CommissionerRejectedError} or {@link CommissionerTimeoutError}
+     *   when the petition fails (before `fn` is invoked).
+     */
+    async withSession<T>(fn: (sessionId: number) => Promise<T>): Promise<T> {
+        const sessionId = await this.petition();
+        const kaInterval: Timer = Time.getPeriodicTimer("commissioner-keepalive", Commissioner.#KA_INTERVAL, () => {
+            void this.keepAlive(sessionId).catch(err => {
+                logger.warn("Commissioner keep-alive error:", err);
+            });
+        }).start();
+
+        try {
+            return await fn(sessionId);
+        } finally {
+            kaInterval.stop();
+            await this.release(sessionId);
+        }
+    }
+}

package/src/commissioner/LeadKa.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MatterError } from "@matter/general";
+import { MeshCopTlvType } from "../dataset/meshcopTlvTypes.js";
+import { BasicTlv } from "../tlv/BasicTlvCodec.js";
+
+/** Thrown when a commissioner BR response (LeadKa/LeadPet) cannot be parsed. */
+export class CommissionerProtocolError extends MatterError {}
+
+export interface LeadKaResponse {
+    state: "accept" | "reject" | "pending";
+}
+
+/** MeshCoP State TLV value for an "alive" keep-alive (Thread spec Table 8-11). */
+const STATE_ACCEPT = 0x01;
+
+export namespace LeadKa {
+    export function buildRequest(sessionId: number): Uint8Array {
+        const sessionBytes = new Uint8Array(2);
+        sessionBytes[0] = (sessionId >> 8) & 0xff;
+        sessionBytes[1] = sessionId & 0xff;
+        // MGMT_COMMISSIONER_KA.req carries a State TLV (accept) ahead of the
+        // session id; without it the Border Agent treats the keep-alive as
+        // malformed and lets the commissioner session expire.
+        return BasicTlv.encode([
+            { type: MeshCopTlvType.STATE, value: new Uint8Array([STATE_ACCEPT]) },
+            { type: MeshCopTlvType.COMMISSIONER_SESSION_ID, value: sessionBytes },
+        ]);
+    }
+
+    export function parseResponse(payload: Uint8Array): LeadKaResponse {
+        const entries = BasicTlv.walk(payload);
+        for (const entry of entries) {
+            if (entry.type === MeshCopTlvType.STATE) {
+                const byte = entry.value[0];
+                if (byte === 0x01) return { state: "accept" };
+                if (byte === 0xff) return { state: "reject" };
+                if (byte === 0x00) return { state: "pending" };
+                throw new CommissionerProtocolError(`LeadKa: unknown state byte ${byte}`);
+            }
+        }
+        throw new CommissionerProtocolError("LeadKa: response missing STATE TLV");
+    }
+}

package/src/commissioner/LeadPet.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes } from "@matter/general";
+import { MeshCopTlvType } from "../dataset/meshcopTlvTypes.js";
+import { BasicTlv } from "../tlv/BasicTlvCodec.js";
+import { CommissionerProtocolError } from "./LeadKa.js";
+
+export interface LeadPetResponse {
+    state: "accept" | "reject" | "pending";
+    sessionId?: number;
+}
+
+export namespace LeadPet {
+    export function buildRequest(commissionerId: string): Uint8Array {
+        return BasicTlv.encode([
+            { type: MeshCopTlvType.COMMISSIONER_ID, value: new TextEncoder().encode(commissionerId) },
+        ]);
+    }
+
+    export function parseResponse(payload: Uint8Array): LeadPetResponse {
+        const entries = BasicTlv.walk(payload);
+        let state: "accept" | "reject" | "pending" | undefined;
+        let sessionId: number | undefined;
+
+        for (const entry of entries) {
+            if (entry.type === MeshCopTlvType.STATE) {
+                const byte = entry.value[0];
+                if (byte === 0x01) state = "accept";
+                else if (byte === 0xff) state = "reject";
+                else if (byte === 0x00) state = "pending";
+                else throw new CommissionerProtocolError(`LeadPet: unknown state byte ${byte}`);
+            } else if (entry.type === MeshCopTlvType.COMMISSIONER_SESSION_ID) {
+                sessionId = (entry.value[0] << 8) | entry.value[1];
+            }
+        }
+
+        if (state === undefined) {
+            const tlvSummary =
+                entries.length === 0
+                    ? "none"
+                    : entries.map(e => `t=0x${e.type.toString(16)}/${e.value.length}b`).join(",");
+            throw new CommissionerProtocolError(
+                `LeadPet: response missing STATE TLV (payload=${Bytes.toHex(payload)}, tlvs=[${tlvSummary}])`,
+            );
+        }
+
+        return state === "accept" ? { state, sessionId } : { state };
+    }
+}

package/src/commissioner/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export {
+    Commissioner,
+    CommissionerKeepAliveError,
+    CommissionerRejectedError,
+    CommissionerTimeoutError,
+} from "./Commissioner.js";
+export type { CommissionerOpts } from "./Commissioner.js";
+export { CommissionerProtocolError, LeadKa } from "./LeadKa.js";
+export type { LeadKaResponse } from "./LeadKa.js";
+export { LeadPet } from "./LeadPet.js";
+export type { LeadPetResponse } from "./LeadPet.js";

package/src/credentials/ThreadCredentialsRegistry.ts

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, ImplementationError, Observable } from "@matter/general";
+import type { OperationalDataset } from "../dataset/OperationalDataset.js";
+import type { ThreadNetworkCredentials } from "./ThreadNetworkCredentials.js";
+
+/**
+ * In-memory registry of {@link ThreadNetworkCredentials} keyed by extended PAN ID.
+ *
+ * Source of truth for "what credentials do we have to talk to which Thread network".
+ * Diagnostic flows look up entries by extPanId; the network key is dropped on
+ * registration so the registry never holds it.
+ */
+export class ThreadCredentialsRegistry {
+    readonly #byExtPanId = new Map<string, ThreadNetworkCredentials>();
+    readonly events = {
+        registered: new Observable<[creds: ThreadNetworkCredentials]>(),
+        unregistered: new Observable<[extPanId: Uint8Array]>(),
+    };
+
+    /**
+     * Register credentials extracted from a parsed Operational Dataset.
+     *
+     * `networkKey` is intentionally dropped on the way in — the registry stores
+     * only what's needed for diagnostic queries (extPanId, networkName, pskc,
+     * activeTimestamp). Smaller blast radius for the most sensitive secret.
+     *
+     * Replaces any existing entry for the same extPanId; throws if the dataset
+     * lacks extPanId, networkName, or pskc.
+     */
+    register(dataset: OperationalDataset): void {
+        if (dataset.extPanId === undefined) {
+            throw new ImplementationError("Cannot register credentials: dataset is missing extPanId");
+        }
+        if (dataset.networkName === undefined) {
+            throw new ImplementationError("Cannot register credentials: dataset is missing networkName");
+        }
+        if (dataset.pskc === undefined) {
+            throw new ImplementationError("Cannot register credentials: dataset is missing pskc");
+        }
+        this.registerCredentials({
+            extPanId: dataset.extPanId,
+            networkName: dataset.networkName,
+            pskc: dataset.pskc,
+            meshLocalPrefix: dataset.meshLocalPrefix,
+            activeTimestamp: dataset.activeTimestamp === undefined ? undefined : bytesToBigint(dataset.activeTimestamp),
+        });
+    }
+
+    /**
+     * Register credentials directly. Intended for tests and external sources
+     * that don't carry a full dataset. Same replacement semantics as {@link register}.
+     *
+     * Replacement always fires `registered` once with the new entry; the old entry
+     * is silently overwritten because consumers care about "what is current", not
+     * about churn. Intentional even when the new dataset's `activeTimestamp` is
+     * older — losing an update is worse than a noisy log line.
+     */
+    registerCredentials(creds: ThreadNetworkCredentials): void {
+        const stored: ThreadNetworkCredentials = {
+            extPanId: creds.extPanId.slice(),
+            networkName: creds.networkName,
+            pskc: creds.pskc.slice(),
+            meshLocalPrefix: creds.meshLocalPrefix?.slice(),
+            activeTimestamp: creds.activeTimestamp,
+        };
+        this.#byExtPanId.set(keyOf(stored.extPanId), stored);
+        // Emit a fresh copy so a listener mutating the typed-array views can't reach back into the stored entry.
+        this.events.registered.emit(snapshot(stored));
+    }
+
+    /** Remove an entry. No-op if absent. */
+    unregister(extPanId: Uint8Array): void {
+        const key = keyOf(extPanId);
+        if (!this.#byExtPanId.has(key)) return;
+        this.#byExtPanId.delete(key);
+        this.events.unregistered.emit(extPanId.slice());
+    }
+
+    /** Lookup by extPanId. Comparison is by Uint8Array equality, not reference. */
+    getCredentials(extPanId: Uint8Array): ThreadNetworkCredentials | undefined {
+        return this.#byExtPanId.get(keyOf(extPanId));
+    }
+
+    /** Defensive snapshot — caller cannot mutate the registry through it. */
+    list(): ReadonlyArray<ThreadNetworkCredentials> {
+        return Array.from(this.#byExtPanId.values());
+    }
+}
+
+function keyOf(extPanId: Uint8Array): string {
+    return Bytes.toHex(extPanId);
+}
+
+function snapshot(creds: ThreadNetworkCredentials): ThreadNetworkCredentials {
+    return {
+        extPanId: creds.extPanId.slice(),
+        networkName: creds.networkName,
+        pskc: creds.pskc.slice(),
+        meshLocalPrefix: creds.meshLocalPrefix?.slice(),
+        activeTimestamp: creds.activeTimestamp,
+    };
+}
+
+// matter.js exposes `Bytes.fromBigInt` but no inverse `Bytes.toBigInt` yet —
+// dataset's activeTimestamp is a fixed-width 8-byte BE field so the loop is safe.
+function bytesToBigint(bytes: Uint8Array): bigint {
+    let result = 0n;
+    for (const b of bytes) {
+        result = (result << 8n) | BigInt(b);
+    }
+    return result;
+}

package/src/credentials/ThreadNetworkCredentials.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Credentials needed to authenticate against a Thread network's commissioner.
+ *
+ * Holds only what the diagnostic flow actually needs — the network key is
+ * intentionally absent because nothing in this codebase ever sends or uses it,
+ * keeping the blast radius of an in-memory leak as small as possible.
+ */
+export interface ThreadNetworkCredentials {
+    /** 8-byte extended PAN ID — primary registry key. */
+    extPanId: Uint8Array;
+    /** Thread network name (UTF-8, ≤16 bytes). */
+    networkName: string;
+    /** 16-byte EC-JPAKE password (PSKc). Sensitive — redact when logging. */
+    pskc: Uint8Array;
+    /** 8-byte mesh-local prefix, used to derive node mesh-local addresses for
+     *  UDP-proxy unicast diagnostics. Absent if the dataset omits it. */
+    meshLocalPrefix?: Uint8Array;
+    /** Active timestamp from the dataset, used for change detection. */
+    activeTimestamp?: bigint;
+}

package/src/credentials/index.ts

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

package/src/crypto/AesCmacPrf128.ts

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "@matter/general";
+import { createCipheriv } from "node:crypto";
+
+const BLOCK_SIZE = 16;
+const RB = 0x87;
+const ZERO_BLOCK = new Uint8Array(BLOCK_SIZE);
+
+function aesEcbEncryptBlock(key: Uint8Array, block: Uint8Array): Uint8Array {
+    const cipher = createCipheriv("aes-128-ecb", key, null);
+    cipher.setAutoPadding(false);
+    const out = cipher.update(block);
+    cipher.final();
+    return new Uint8Array(out.buffer, out.byteOffset, out.byteLength);
+}
+
+function leftShift1(input: Uint8Array): Uint8Array {
+    const out = new Uint8Array(input.length);
+    let carry = 0;
+    for (let i = input.length - 1; i >= 0; i--) {
+        const b = input[i];
+        out[i] = ((b << 1) & 0xff) | carry;
+        carry = (b & 0x80) >> 7;
+    }
+    return out;
+}
+
+function xorInto(target: Uint8Array, source: Uint8Array, offset = 0): void {
+    for (let i = 0; i < BLOCK_SIZE; i++) {
+        target[i] ^= source[offset + i];
+    }
+}
+
+function generateSubkeys(key: Uint8Array): { k1: Uint8Array; k2: Uint8Array } {
+    const l = aesEcbEncryptBlock(key, ZERO_BLOCK);
+    const k1 = leftShift1(l);
+    if ((l[0] & 0x80) !== 0) k1[BLOCK_SIZE - 1] ^= RB;
+    const k2 = leftShift1(k1);
+    if ((k1[0] & 0x80) !== 0) k2[BLOCK_SIZE - 1] ^= RB;
+    return { k1, k2 };
+}
+
+/**
+ * AES-CMAC per RFC 4493.
+ *
+ * Block-cipher-based MAC with a 128-bit AES key and a 16-byte tag. Empty messages
+ * are explicitly supported and pad to a single all-zero block XORed with K2.
+ */
+export namespace AesCmac {
+    export function compute(key: Uint8Array, message: Uint8Array): Uint8Array {
+        if (key.length !== 16) {
+            throw new InternalError(`AES-CMAC key must be 16 bytes, got ${key.length}`);
+        }
+        const { k1, k2 } = generateSubkeys(key);
+
+        const numBlocks = Math.max(1, Math.ceil(message.length / BLOCK_SIZE));
+        const lastBlockComplete = message.length > 0 && message.length % BLOCK_SIZE === 0;
+
+        const lastBlock = new Uint8Array(BLOCK_SIZE);
+        const lastBlockOffset = (numBlocks - 1) * BLOCK_SIZE;
+        if (lastBlockComplete) {
+            lastBlock.set(message.subarray(lastBlockOffset, lastBlockOffset + BLOCK_SIZE));
+            xorInto(lastBlock, k1);
+        } else {
+            const remaining = message.length - lastBlockOffset;
+            lastBlock.set(message.subarray(lastBlockOffset, lastBlockOffset + remaining));
+            lastBlock[remaining] = 0x80;
+            xorInto(lastBlock, k2);
+        }
+
+        const x = new Uint8Array(BLOCK_SIZE);
+        for (let i = 0; i < numBlocks - 1; i++) {
+            xorInto(x, message, i * BLOCK_SIZE);
+            const enc = aesEcbEncryptBlock(key, x);
+            x.set(enc);
+        }
+        xorInto(x, lastBlock);
+        return aesEcbEncryptBlock(key, x);
+    }
+}
+
+/**
+ * AES-CMAC-PRF-128 per RFC 4615.
+ *
+ * Lifts AES-CMAC into a variable-length-key PRF: a 16-byte key is used directly,
+ * any other key is first compressed via CMAC under an all-zero key.
+ */
+export namespace AesCmacPrf128 {
+    export function compute(key: Uint8Array, message: Uint8Array): Uint8Array {
+        if (key.length === 16) {
+            return AesCmac.compute(key, message);
+        }
+        const derivedKey = AesCmac.compute(ZERO_BLOCK, key);
+        return AesCmac.compute(derivedKey, message);
+    }
+}

package/src/crypto/Pbkdf2AesCmac.ts

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ImplementationError } from "@matter/general";
+import { AesCmacPrf128 } from "./AesCmacPrf128.js";
+
+const HLEN = 16;
+
+/**
+ * PBKDF2 (RFC 8018 §5.2) using AES-CMAC-PRF-128 as the underlying PRF.
+ *
+ * Hand-rolled because Node's `crypto.pbkdf2` is hardwired to HMAC. The PRF here
+ * always emits 16 bytes, so each output block needs one PRF call per iteration.
+ */
+export function pbkdf2AesCmac(args: {
+    password: Uint8Array;
+    salt: Uint8Array;
+    iterations: number;
+    dkLen: number;
+}): Uint8Array {
+    const { password, salt, iterations, dkLen } = args;
+    if (!Number.isInteger(iterations) || iterations <= 0) {
+        throw new ImplementationError(`iterations must be a positive integer, got ${iterations}`);
+    }
+    if (!Number.isInteger(dkLen) || dkLen <= 0) {
+        throw new ImplementationError(`dkLen must be a positive integer, got ${dkLen}`);
+    }
+    // PBKDF2 caps the derived-key length at (2^32 - 1) * hLen bytes (RFC 8018).
+    if (dkLen > 0xffffffff * HLEN) {
+        throw new ImplementationError(`dkLen ${dkLen} exceeds PBKDF2 maximum`);
+    }
+
+    const numBlocks = Math.ceil(dkLen / HLEN);
+    const out = new Uint8Array(numBlocks * HLEN);
+    const saltedBlock = new Uint8Array(salt.length + 4);
+    saltedBlock.set(salt, 0);
+
+    for (let i = 1; i <= numBlocks; i++) {
+        saltedBlock[salt.length] = (i >>> 24) & 0xff;
+        saltedBlock[salt.length + 1] = (i >>> 16) & 0xff;
+        saltedBlock[salt.length + 2] = (i >>> 8) & 0xff;
+        saltedBlock[salt.length + 3] = i & 0xff;
+
+        let u = AesCmacPrf128.compute(password, saltedBlock);
+        const t = new Uint8Array(u);
+        for (let j = 1; j < iterations; j++) {
+            u = AesCmacPrf128.compute(password, u);
+            for (let k = 0; k < HLEN; k++) t[k] ^= u[k];
+        }
+        out.set(t, (i - 1) * HLEN);
+    }
+
+    return out.subarray(0, dkLen);
+}