@matter-server/ws-controller 0.2.0-alpha.0-00000000-000000000

package/src/controller/LegacyDataInjector.ts

@@ -0,0 +1,314 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ImplementationError, MaybePromise, SupportedStorageTypes } from "@matter/general";
+import {
+    Bytes,
+    Crypto,
+    FabricId,
+    FabricIndex,
+    isDeepEqual,
+    isObject,
+    Logger,
+    NodeId,
+    StorageContext,
+    StorageManager,
+} from "@matter/main";
+import { DescriptorCluster } from "@matter/main/clusters";
+import { CertificateAuthority, Fabric, FabricBuilder, Noc } from "@matter/main/protocol";
+import { VendorId } from "@matter/main/types";
+import { ClusterMap } from "../model/ModelMapper.js";
+import { convertWebSocketTagBasedToMatter } from "../server/Converters.js";
+
+const logger = Logger.get("LegacyDataInjector");
+
+/* eslint-disable regexp/no-unused-capturing-group */
+const BASE64_REGEX = /^([0-9a-z+/]{4})*(([0-9a-z+/]{2}==)|([0-9a-z+/]{3}=))?$/i;
+
+const FEATUREMAP_ID = DescriptorCluster.attributes.featureMap.id.toString();
+
+/**
+ * Fabric configuration data extracted from chip.json.
+ * This is a partial representation of Fabric.SyncConfig from @matter/protocol.
+ *
+ * IMPORTANT: The controller's operational keypair is NOT available in chip.json.
+ *
+ * The Python CHIP SDK intentionally does not persist the operational private key to chip.json.
+ * When pychip_OpCreds_AllocateController is called without a keypair parameter, it generates
+ * an ephemeral P256 keypair, creates a NOC for it, but only stores the keypair in memory
+ * (see FabricTable.cpp:190 - "Operational Key is never saved to storage here").
+ *
+ * This means when migrating from Python Matter Server to matter.js:
+ * - The RCAC and ICAC can be reused (they define the fabric's CA chain)
+ * - The NOC must be REPLACED with a new one signed for a new keypair
+ * - A new operational keypair must be generated for the matter.js controller
+ * - The IPK and other fabric data can be preserved
+ *
+ * The ExampleOpCredsCAKey1/ICAKey1 in chip.json are the CA/ICA signing keys (for issuing
+ * certificates to devices), NOT the controller's operational identity key.
+ *
+ * Fields that need to be computed or provided when creating the Fabric:
+ * - keyPair: Must generate a new keypair and issue a new NOC
+ * - globalId: Computed from fabricId + rootPublicKey
+ * - operationalIdentityProtectionKey: Computed from identityProtectionKey + globalId
+ */
+export interface LegacyFabricConfigData {
+    /** Fabric index (1, 2, etc.) */
+    fabricIndex: number;
+    /** Fabric ID from NOC certificate (can be number for small values, bigint for large) */
+    fabricId: number | bigint;
+    /** Node ID from NOC certificate (can be number for small values, bigint for large) */
+    nodeId: number | bigint;
+    /** Root node ID from RCAC certificate (can be number for small values, bigint for large) */
+    rootNodeId: number | bigint;
+    /** Root vendor ID from fabric metadata */
+    rootVendorId: number;
+    /** Root CA certificate (RCAC) as TLV bytes */
+    rootCert: Bytes;
+    /** Root CA public key extracted from RCAC */
+    rootPublicKey: Bytes;
+    /** Identity Protection Key from group key set 0 */
+    identityProtectionKey: Bytes;
+    /** Intermediate CA certificate (ICAC) as TLV bytes, if present */
+    intermediateCACert?: Bytes;
+    /** Node Operational Certificate (NOC) as TLV bytes */
+    operationalCert: Bytes;
+    /** Fabric label */
+    label: string;
+}
+
+/** Vendor info from Python Matter Server */
+export interface LegacyVendorInfo {
+    vendor_id: number;
+    vendor_name: string;
+    company_legal_name: string;
+    company_preferred_name: string;
+    vendor_landing_page_url: string;
+    creator: string;
+}
+
+/** Node data from Python Matter Server nodes map */
+export interface LegacyNodeData {
+    node_id: number;
+    date_commissioned: string;
+    last_interview: string;
+    interview_version: number;
+    available: boolean;
+    is_bridge: boolean;
+    attributes: Record<string, unknown>;
+    attribute_subscriptions: unknown[];
+}
+
+/** Structure of the <compressedFabricId>.json file */
+export interface LegacyServerFile {
+    vendor_info: Record<string, LegacyVendorInfo>;
+    last_node_id: number;
+    nodes: Record<string, LegacyNodeData>;
+}
+
+export type CertificateAuthorityConfiguration = CertificateAuthority.Configuration;
+
+export interface LegacyServerData {
+    credentials?: CertificateAuthority.Configuration;
+    fabric?: LegacyFabricConfigData;
+    nodeData?: LegacyServerFile;
+    vendorId: number;
+    fabricId?: number | bigint;
+}
+
+export namespace LegacyDataInjector {
+    function isPrimitiveType(value: unknown) {
+        return (
+            typeof value === "number" ||
+            value === null ||
+            typeof value == "boolean" ||
+            (typeof value == "string" && !BASE64_REGEX.test(value))
+        );
+    }
+
+    export async function injectCredentials(
+        credentialsStorage: StorageContext,
+        crypto: Crypto,
+        credentialData: CertificateAuthority.Configuration,
+        fabricData?: LegacyFabricConfigData,
+    ) {
+        const rootCertificateAuthority = new CertificateAuthority(crypto, credentialData);
+
+        for (const [key, value] of Object.entries(credentialData)) {
+            if (await credentialsStorage.has(key)) {
+                if (!isDeepEqual(await credentialsStorage.get(key), value)) {
+                    continue;
+                }
+                logger.warn(`Overriding credential ${key} with new value!`);
+            }
+            await credentialsStorage.set(key, value);
+        }
+
+        if (fabricData === undefined) {
+            logger.warn("Credentials injected, but no fabric data provided. Skipping fabric initialization.");
+            return;
+        }
+
+        const {
+            fabricIndex,
+            fabricId,
+            nodeId,
+            rootNodeId,
+            rootCert,
+            intermediateCACert,
+            operationalCert,
+            rootVendorId,
+            rootPublicKey,
+            identityProtectionKey,
+            label,
+        } = fabricData;
+
+        const tempFabric = await Fabric.create(crypto, {
+            fabricIndex: FabricIndex(fabricIndex),
+            fabricId: FabricId(fabricId),
+            nodeId: NodeId(nodeId),
+            rootNodeId: NodeId(rootNodeId),
+            rootCert,
+            intermediateCACert,
+            operationalCert,
+            rootVendorId: VendorId(rootVendorId),
+            rootPublicKey: rootPublicKey,
+            identityProtectionKey: identityProtectionKey,
+            label: label,
+            keyPair: await crypto.createKeyPair(), // Just use a new keypair temporarily because chip data does not have it
+        });
+
+        if (await credentialsStorage.has("fabric")) {
+            const storedFabric = await credentialsStorage.get<Fabric.Config>("fabric");
+            if (!Bytes.areEqual(storedFabric.rootPublicKey!, tempFabric.rootPublicKey)) {
+                logger.warn("Existing fabric root public key changed. Rewriting from legacy data");
+            } else {
+                logger.info("Fabric root public key unchanged. Skipping rewrite.");
+                return;
+            }
+        }
+
+        const builder = await FabricBuilder.create(crypto);
+        builder.initializeFromFabricForUpdate(tempFabric);
+        const {
+            subject: { nodeId: certNodeId, fabricId: certFabricId },
+        } = Noc.fromTlv(tempFabric.operationalCert).cert;
+        if (certNodeId !== nodeId || certFabricId !== fabricId) {
+            throw new ImplementationError(`Cannot rotate NOC for fabric because root node ID changed`);
+        }
+        await builder.setOperationalCert(
+            await rootCertificateAuthority.generateNoc(builder.publicKey, certFabricId, certNodeId),
+            tempFabric.intermediateCACert,
+        );
+        const rootFabric = await builder.build(tempFabric.fabricIndex);
+
+        await credentialsStorage.set("fabric", rootFabric.config);
+    }
+
+    export async function injectNodeData(baseStorage: StorageManager, nodeData?: LegacyServerFile) {
+        const nodesListStorage = baseStorage.createContext("nodes");
+
+        if (nodeData === undefined) {
+            if (!(await nodesListStorage.has("commissionedNodes"))) {
+                await nodesListStorage.set("commissionedNodes", []);
+            }
+            return false;
+        }
+
+        const commissionedNodes = new Array<[NodeId, any]>();
+        let injectedNodes = 0;
+
+        for (const [nodeId, nodeDetails] of Object.entries(nodeData.nodes)) {
+            const nodeStorage = baseStorage.createContext(`node-${nodeId}`);
+            if (nodeId !== nodeDetails.node_id.toString()) {
+                logger.warn(`Node ID mismatch in node data: ${nodeId} != ${nodeDetails.node_id}`);
+            }
+            commissionedNodes.push([NodeId(BigInt(nodeId)), {}]);
+            let newNode = true;
+            logger.info(`Injecting node ${nodeId} into storage`);
+            const nodeWrites = new Array<MaybePromise<void>>();
+            for (const [attributeKey, value] of Object.entries(nodeDetails.attributes)) {
+                let currentEndpointId: string | undefined;
+                let currentClusterId: string | undefined;
+                let endpointStorage: StorageContext | undefined;
+                let clusterStorage: StorageContext | undefined;
+                const [endpointId, clusterId, attributeId] = attributeKey.split("/");
+                if (currentEndpointId !== endpointId) {
+                    endpointStorage = nodeStorage.createContext(endpointId);
+                    currentEndpointId = endpointId;
+                    currentClusterId = undefined;
+                }
+                if (currentClusterId !== clusterId) {
+                    clusterStorage = endpointStorage!.createContext(clusterId);
+                    currentClusterId = clusterId;
+                    if (newNode) {
+                        if (await clusterStorage.has("__version__")) {
+                            logger.info(`Node ${nodeId} already exists. Skipping injection.`);
+                            break;
+                        }
+                        newNode = false;
+                        injectedNodes++;
+                    }
+                    nodeWrites.push(clusterStorage.set("__version__", 1));
+                }
+
+                const clusterModel = ClusterMap[clusterId];
+                const model = clusterModel?.attributes?.[attributeId];
+                if (clusterModel === undefined || model === undefined) {
+                    if (attributeId === FEATUREMAP_ID) {
+                        logger.debug(
+                            `Node ${nodeId}: Attribute ${attributeKey}, unknown featuremap converted to empty featuremap`,
+                        );
+                        nodeWrites.push(clusterStorage!.set(attributeId, { value: {} } as SupportedStorageTypes));
+                    } else if (isPrimitiveType(value) || (Array.isArray(value) && value.every(isPrimitiveType))) {
+                        logger.debug(
+                            `Node ${nodeId}: Attribute ${attributeKey}, unknown primary type converted generically`,
+                            value,
+                        );
+                        nodeWrites.push(clusterStorage!.set(attributeId, { value } as SupportedStorageTypes));
+                    } else {
+                        logger.info(
+                            `Node ${nodeId}: Attribute ${attributeKey}, not found in and unclear value. Skipping injection.`,
+                            value,
+                        );
+                    }
+                } else {
+                    const convertedValue =
+                        isObject(value) && ("TLVValue" in value || "Reason" in value)
+                            ? undefined
+                            : convertWebSocketTagBasedToMatter(value, model, clusterModel.model);
+                    if (convertedValue !== undefined) {
+                        logger.debug(
+                            `Node ${nodeId}: Converted attribute ${attributeKey}:`,
+                            value,
+                            "->",
+                            convertedValue,
+                        );
+                        nodeWrites.push(
+                            clusterStorage!.set(attributeId, { value: convertedValue } as SupportedStorageTypes),
+                        );
+                    } else {
+                        logger.info(`Attribute ${attributeKey} could not be converted. Skipping injection.`);
+                    }
+                }
+            }
+            await Promise.allSettled(nodeWrites);
+            nodeWrites.length = 0;
+        }
+
+        if (injectedNodes > 0) {
+            const knownNodes = await nodesListStorage.get<[bigint | number, any][]>("commissionedNodes", []);
+            for (const [nodeId] of commissionedNodes) {
+                if (!knownNodes.find(([knownNodeId]) => knownNodeId === nodeId)) {
+                    knownNodes.push([nodeId, {}]);
+                }
+            }
+            await nodesListStorage.set("commissionedNodes", knownNodes);
+        }
+
+        return injectedNodes > 0;
+    }
+}

package/src/controller/MatterController.ts

@@ -0,0 +1,265 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { SharedEnvironmentServices, Timestamp } from "@matter/general";
+import {
+    Bytes,
+    CommissioningClient,
+    Crypto,
+    Environment,
+    FabricId,
+    GlobalFabricId,
+    Logger,
+    NodeId,
+    SoftwareUpdateManager,
+} from "@matter/main";
+import { DclCertificateService, DclOtaUpdateService, DclVendorInfoService, VendorInfo } from "@matter/main/protocol";
+import { VendorId } from "@matter/main/types";
+import { CommissioningController } from "@project-chip/matter.js";
+import { Readable } from "node:stream";
+import { ConfigStorage } from "../server/ConfigStorage.js";
+import { ControllerCommandHandler } from "./ControllerCommandHandler.js";
+import { LegacyDataInjector, LegacyServerData } from "./LegacyDataInjector.js";
+
+const logger = Logger.get("MatterController");
+
+export async function computeCompressedNodeId(
+    crypto: Crypto,
+    fabricId: number | bigint,
+    caKey: Bytes,
+): Promise<string> {
+    return (await GlobalFabricId.compute(crypto, FabricId(fabricId), caKey)).toString();
+}
+
+export interface MatterControllerOptions {
+    enableTestNetDcl?: boolean;
+    disableOtaProvider?: boolean;
+}
+
+// Storage ID used for the Matter server
+const MATTER_SERVER_ID = "server";
+
+export class MatterController {
+    #env: Environment;
+    #services?: SharedEnvironmentServices;
+    #controllerInstance?: CommissioningController;
+    #commandHandler?: ControllerCommandHandler;
+    #config: ConfigStorage;
+    #legacyCommissionedDates?: Map<string, Timestamp>;
+    #enableTestNetDcl = false;
+    #disableOtaProvider = true;
+
+    static async create(
+        environment: Environment,
+        config: ConfigStorage,
+        options: MatterControllerOptions,
+        legacyData?: LegacyServerData,
+    ) {
+        const instance = new MatterController(environment, config, options);
+
+        const commissionedDates = new Map<string, Timestamp>();
+        if (legacyData !== undefined) {
+            const crypto = environment.get(Crypto);
+            const baseStorage = await config.service.open(MATTER_SERVER_ID);
+            if (legacyData.credentials && legacyData.fabricId) {
+                await LegacyDataInjector.injectCredentials(
+                    baseStorage.createContext("credentials"),
+                    crypto,
+                    legacyData.credentials,
+                    legacyData.fabric,
+                );
+            }
+            if (
+                (await LegacyDataInjector.injectNodeData(baseStorage, legacyData.nodeData)) &&
+                legacyData.nodeData !== undefined
+            ) {
+                for (const [nodeIdStr, data] of Object.entries(legacyData.nodeData.nodes)) {
+                    const { date_commissioned: commissionedAt } = data;
+                    commissionedDates.set(nodeIdStr, Timestamp(new Date(commissionedAt).getTime()));
+                }
+            }
+            await baseStorage.close();
+        }
+
+        await instance.initialize(legacyData?.vendorId, legacyData?.fabricId, commissionedDates);
+        return instance;
+    }
+
+    constructor(environment: Environment, config: ConfigStorage, options: MatterControllerOptions) {
+        this.#env = environment;
+        this.#config = config;
+        this.#enableTestNetDcl = options.enableTestNetDcl ?? this.#enableTestNetDcl;
+        this.#disableOtaProvider = options.disableOtaProvider ?? this.#disableOtaProvider;
+    }
+
+    protected async initialize(
+        vendorId?: number,
+        fabricId?: number | bigint,
+        legacyCommissionedDates?: Map<string, Timestamp>,
+    ) {
+        this.#legacyCommissionedDates = legacyCommissionedDates?.size ? legacyCommissionedDates : undefined;
+        this.#controllerInstance = new CommissioningController({
+            environment: {
+                environment: this.#env,
+                id: MATTER_SERVER_ID,
+            },
+            autoConnect: false, // Do not auto-connect to the commissioned nodes
+            adminFabricLabel: this.#config.fabricLabel,
+            adminVendorId: vendorId !== undefined ? VendorId(vendorId) : undefined,
+            adminFabricId: fabricId !== undefined ? FabricId(fabricId) : undefined,
+            enableOtaProvider: !this.#disableOtaProvider,
+        });
+
+        // Start loading and initialization of meta data
+        /* eslint-disable @typescript-eslint/no-unused-expressions */
+        this.vendorInfoService;
+        /* eslint-disable @typescript-eslint/no-unused-expressions */
+        this.certificateService;
+    }
+
+    get commandHandler() {
+        if (this.#controllerInstance === undefined) {
+            throw new Error("Controller not initialized");
+        }
+        if (this.#commandHandler === undefined) {
+            this.#commandHandler = new ControllerCommandHandler(
+                this.#controllerInstance,
+                this.#env.vars.get("ble.enable", false),
+                !this.#disableOtaProvider,
+            );
+
+            this.#commandHandler.events.started.once(async () => {
+                if (this.#legacyCommissionedDates !== undefined) {
+                    await this.injectCommissionedDates();
+                }
+
+                if (!this.#disableOtaProvider && this.#enableTestNetDcl) {
+                    await this.#enableTestOtaImages();
+                }
+            });
+        }
+
+        return this.#commandHandler;
+    }
+
+    /**
+     * Get the shared environment services instance.
+     */
+    get services(): SharedEnvironmentServices {
+        if (this.#services === undefined) {
+            this.#services = this.#env.asDependent();
+        }
+        return this.#services;
+    }
+
+    /**
+     * Get the DCL vendor info service instance.
+     * Lazily initializes the service if not already present.
+     */
+    get vendorInfoService(): DclVendorInfoService {
+        if (!this.#env.has(DclVendorInfoService)) {
+            new DclVendorInfoService(this.#env);
+        }
+        return this.services.get(DclVendorInfoService);
+    }
+
+    /**
+     * Get the DCL certificate service instance
+     * Lazily initializes the service if not already present.
+     */
+    get certificateService() {
+        if (!this.#env.has(DclCertificateService)) {
+            new DclCertificateService(this.#env, { fetchTestCertificates: this.#enableTestNetDcl });
+        }
+        return this.services.get(DclCertificateService);
+    }
+
+    /**
+     * Get vendor information by vendor ID.
+     * Returns undefined if the vendor is not found.
+     */
+    async getVendorInfo(vendorId: number): Promise<VendorInfo | undefined> {
+        await this.vendorInfoService.construction;
+        return this.vendorInfoService.infoFor(vendorId);
+    }
+
+    /**
+     * Get all vendor information from the DCL service.
+     */
+    async getAllVendors(): Promise<ReadonlyMap<number, VendorInfo>> {
+        await this.vendorInfoService.construction;
+        return this.vendorInfoService.vendors;
+    }
+
+    async injectCommissionedDates() {
+        if (this.#controllerInstance === undefined || this.#legacyCommissionedDates === undefined) {
+            return;
+        }
+        for (const [nodeIdStr, commissionedAt] of this.#legacyCommissionedDates) {
+            try {
+                const peerAddress = this.#controllerInstance.fabric.addressOf(NodeId(BigInt(nodeIdStr)));
+                const node = await this.#controllerInstance.node.peers.forAddress(peerAddress);
+                const commissioningState = node.maybeStateOf(CommissioningClient);
+                if (commissioningState !== undefined && commissioningState.commissionedAt === undefined) {
+                    await node.setStateOf(CommissioningClient, { commissionedAt });
+                    logger.info(`Injected commissioned date for node ${nodeIdStr}`);
+                }
+            } catch (error) {
+                logger.warn(`Error injecting commissioned date for node ${nodeIdStr}`, error);
+            }
+        }
+    }
+
+    async stop() {
+        await this.#commandHandler?.close(); // This closes also the controller instance if started
+        await this.#services?.close();
+    }
+
+    /**
+     * Enable test OTA images (test-net DCL).
+     * Must be called after the controller is started.
+     */
+    async #enableTestOtaImages() {
+        if (this.#controllerInstance === undefined) {
+            throw new Error("Controller not initialized");
+        }
+        await this.#controllerInstance.otaProvider.setStateOf(SoftwareUpdateManager, { allowTestOtaImages: true });
+        logger.info("Enabled test OTA images (test-net DCL)");
+    }
+
+    /**
+     * Store an OTA image file from a file path.
+     * @param filePath - Path to the OTA file
+     * @returns true if stored successfully
+     */
+    async storeOtaImageFromFile(filePath: string): Promise<boolean> {
+        const { createReadStream } = await import("node:fs");
+        const { pathToFileURL } = await import("node:url");
+        const otaService = this.services.get(DclOtaUpdateService);
+
+        // Convert file path to file:// URL for the OTA service
+        const fileUrl = pathToFileURL(filePath).href;
+
+        // Read the file twice - once for info, once for storage
+        const infoStream = Readable.toWeb(createReadStream(filePath)) as ReadableStream<Uint8Array>;
+        const updateInfo = await otaService.updateInfoFromStream(infoStream, fileUrl);
+
+        logger.info(
+            `Storing OTA image from ${filePath}: vendorId=0x${updateInfo.vid.toString(16)}, productId=0x${updateInfo.pid.toString(16)}, version=${updateInfo.softwareVersion} (${updateInfo.softwareVersionString})`,
+        );
+
+        const storeStream = Readable.toWeb(createReadStream(filePath)) as ReadableStream<Uint8Array>;
+        await otaService.store(storeStream, updateInfo, false);
+        return true;
+    }
+
+    /**
+     * Close the services when shutting down.
+     */
+    async closeServices() {
+        await this.#services?.close();
+    }
+}

package/src/controller/Nodes.ts

@@ -0,0 +1,115 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { NodeId } from "@matter/main";
+import { ClusterClientObj } from "@matter/main/protocol";
+import { ClusterId, ClusterType, EndpointNumber } from "@matter/main/types";
+import { InteractionClient } from "@project-chip/matter.js/cluster";
+import { PairedNode } from "@project-chip/matter.js/device";
+import { ServerError } from "../types/WebSocketMessageTypes.js";
+import { AttributeDataCache } from "./AttributeDataCache.js";
+
+/**
+ * Manages node storage and provides access to nodes and their clients.
+ *
+ * This class handles:
+ * - Storage of PairedNode instances
+ * - Node retrieval and existence checking
+ * - Access to interaction clients and cluster clients
+ * - Attribute data caching
+ */
+export class Nodes {
+    #nodes = new Map<NodeId, PairedNode>();
+    #attributeCache = new AttributeDataCache();
+
+    /**
+     * Get the attribute cache instance.
+     */
+    get attributeCache(): AttributeDataCache {
+        return this.#attributeCache;
+    }
+
+    /**
+     * Get all node IDs.
+     */
+    getIds(): NodeId[] {
+        return Array.from(this.#nodes.keys());
+    }
+
+    /**
+     * Get a node by ID.
+     * @throws ServerError if node not found
+     */
+    get(nodeId: NodeId): PairedNode {
+        const node = this.#nodes.get(nodeId);
+        if (node === undefined) {
+            throw ServerError.nodeNotExists(nodeId);
+        }
+        return node;
+    }
+
+    /**
+     * Check if a node exists.
+     */
+    has(nodeId: NodeId): boolean {
+        return this.#nodes.has(nodeId);
+    }
+
+    /**
+     * Add or update a node in storage.
+     */
+    set(nodeId: NodeId, node: PairedNode): void {
+        this.#nodes.set(nodeId, node);
+    }
+
+    /**
+     * Remove a node from storage and clear its attribute cache.
+     */
+    delete(nodeId: NodeId): void {
+        this.#nodes.delete(nodeId);
+        this.#attributeCache.delete(nodeId);
+    }
+
+    /**
+     * Get the interaction client for a node.
+     */
+    interactionClientFor(nodeId: NodeId): Promise<InteractionClient> {
+        return this.get(nodeId).getInteractionClient();
+    }
+
+    /**
+     * Get a cluster client by cluster ID for a specific endpoint on a node.
+     * @throws Error if endpoint or cluster not found
+     */
+    clusterClientByIdFor(nodeId: NodeId, endpointId: EndpointNumber, clusterId: ClusterId): ClusterClientObj<any> {
+        const node = this.get(nodeId);
+
+        const endpoint = endpointId === 0 ? node.getRootEndpoint() : node.getDeviceById(endpointId);
+
+        if (endpoint === undefined) {
+            throw new Error(`Endpoint ${endpointId} on node ${nodeId} not found`);
+        }
+
+        const client = endpoint.getClusterClientById(clusterId);
+
+        if (client === undefined) {
+            throw new Error(`Cluster ${clusterId} on endpoint ${endpointId} on node ${nodeId} not found`);
+        }
+
+        return client;
+    }
+
+    /**
+     * Get a typed cluster client for a specific endpoint on a node.
+     */
+    clusterClientFor<const T extends ClusterType>(
+        nodeId: NodeId,
+        endpointId: EndpointNumber,
+        cluster: T,
+    ): ClusterClientObj<T> {
+        return this.clusterClientByIdFor(nodeId, endpointId, cluster.id) as ClusterClientObj<T>;
+    }
+}