@matter-server/ws-controller 0.6.8 → 0.7.0-alpha.0-20260516-8ee9631

package/src/controller/WebRtcCallbackBridge.ts

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { WebRtcCallbackData } from "@matter-server/ws-client";
+import { Logger } from "@matter/main";
+import type { WebRtcTransportRequestorServer } from "./behaviors/WebRtcTransportRequestorServer.js";
+
+const logger = Logger.get("WebRtcCallbackBridge");
+
+export function attachWebRtcCallbackBridge(
+    events: WebRtcTransportRequestorServer.Events,
+    emit: (data: WebRtcCallbackData) => void,
+): void {
+    events.offer.on((session, request) => {
+        logger.info(
+            `offer from peer node=${session.peerNodeId} ep=${session.peerEndpointId} session=${session.id} sdpLen=${request.sdp.length}`,
+        );
+        emit({
+            event_type: "offer",
+            webrtc_session_id: session.id,
+            node_id: session.peerNodeId,
+            endpoint_id: session.peerEndpointId,
+            fabric_index: session.fabricIndex,
+            data: {
+                sdp: request.sdp,
+                ice_servers: request.iceServers,
+                ice_transport_policy: request.iceTransportPolicy,
+            },
+        });
+    });
+    events.answer.on((session, sdp) => {
+        logger.info(
+            `answer from peer node=${session.peerNodeId} ep=${session.peerEndpointId} session=${session.id} sdpLen=${sdp.length}`,
+        );
+        emit({
+            event_type: "answer",
+            webrtc_session_id: session.id,
+            node_id: session.peerNodeId,
+            endpoint_id: session.peerEndpointId,
+            fabric_index: session.fabricIndex,
+            data: { sdp },
+        });
+    });
+    events.iceCandidates.on((session, candidates) => {
+        logger.info(
+            `ice_candidates from peer node=${session.peerNodeId} ep=${session.peerEndpointId} session=${session.id} count=${candidates.length}`,
+        );
+        emit({
+            event_type: "ice_candidates",
+            webrtc_session_id: session.id,
+            node_id: session.peerNodeId,
+            endpoint_id: session.peerEndpointId,
+            fabric_index: session.fabricIndex,
+            data: {
+                ice_candidates: candidates.map(c => ({
+                    candidate: c.candidate,
+                    sdpMid: c.sdpMid ?? null,
+                    sdpMLineIndex: c.sdpmLineIndex ?? null,
+                })),
+            },
+        });
+    });
+    events.end.on((session, reason) => {
+        logger.info(
+            `end from peer node=${session.peerNodeId} ep=${session.peerEndpointId} session=${session.id} reason=${reason}`,
+        );
+        emit({
+            event_type: "end",
+            webrtc_session_id: session.id,
+            node_id: session.peerNodeId,
+            endpoint_id: session.peerEndpointId,
+            fabric_index: session.fabricIndex,
+            data: { reason },
+        });
+    });
+}

package/src/controller/behaviors/WebRtcTransportRequestorServer.ts

@@ -0,0 +1,149 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Observable } from "@matter/general";
+import { Logger, Node } from "@matter/main";
+import type { ServerNode } from "@matter/main";
+import { AccessControlServer } from "@matter/node/behaviors/access-control";
+import { WebRtcTransportRequestorBehavior } from "@matter/node/behaviors/web-rtc-transport-requestor";
+import { assertRemoteActor, FabricAuthority, NodeSession } from "@matter/protocol";
+import { Status, StatusResponseError } from "@matter/types";
+import { AccessControl } from "@matter/types/clusters/access-control";
+import { WebRtcTransportDefinitions } from "@matter/types/clusters/web-rtc-transport-definitions";
+import { WebRtcTransportRequestor } from "@matter/types/clusters/web-rtc-transport-requestor";
+
+type WebRtcSession = WebRtcTransportDefinitions.WebRtcSession;
+
+const logger = Logger.get("WebRtcTransportRequestorServer");
+
+export class WebRtcTransportRequestorServer extends WebRtcTransportRequestorBehavior {
+    declare state: WebRtcTransportRequestorServer.State;
+    declare events: WebRtcTransportRequestorServer.Events;
+
+    upsertSession(session: WebRtcSession): void {
+        const enriched: WebRtcSession = {
+            ...session,
+            videoStreamId: session.videoStreams?.[0] ?? null,
+            audioStreamId: session.audioStreams?.[0] ?? null,
+        };
+        const sessions = this.state.currentSessions;
+        const idx = sessions.findIndex(s => s.id === session.id);
+        if (idx === -1) {
+            this.state.currentSessions = [...sessions, enriched];
+        } else {
+            this.state.currentSessions = sessions.map((s, i) => (i === idx ? enriched : s));
+        }
+    }
+
+    removeSession(id: number): void {
+        this.state.currentSessions = this.state.currentSessions.filter(s => s.id !== id);
+    }
+
+    override async offer(request: WebRtcTransportRequestor.OfferRequest): Promise<void> {
+        logger.info(`incoming Offer webRtcSessionId=${request.webRtcSessionId} sdpLen=${request.sdp.length}`);
+        const session = this.#findSessionStrict(request.webRtcSessionId);
+        this.events.offer.emit(session, request);
+    }
+
+    override async answer(request: WebRtcTransportRequestor.AnswerRequest): Promise<void> {
+        logger.info(`incoming Answer webRtcSessionId=${request.webRtcSessionId} sdpLen=${request.sdp.length}`);
+        const session = this.#findSessionStrict(request.webRtcSessionId);
+        this.events.answer.emit(session, request.sdp);
+    }
+
+    override async iceCandidates(request: WebRtcTransportRequestor.IceCandidatesRequest): Promise<void> {
+        logger.info(
+            `incoming ICECandidates webRtcSessionId=${request.webRtcSessionId} count=${request.iceCandidates.length}`,
+        );
+        if (request.iceCandidates.length === 0) {
+            throw new StatusResponseError("ICE candidates list must not be empty", Status.InvalidCommand);
+        }
+        const session = this.#findSessionStrict(request.webRtcSessionId);
+        this.events.iceCandidates.emit(session, request.iceCandidates);
+    }
+
+    override async end(request: WebRtcTransportRequestor.EndRequest): Promise<void> {
+        logger.info(`incoming End webRtcSessionId=${request.webRtcSessionId} reason=${request.reason}`);
+        const session = this.#findSessionStrict(request.webRtcSessionId);
+        this.removeSession(request.webRtcSessionId);
+        this.events.end.emit(session, request.reason);
+    }
+
+    override async initialize() {
+        const node = Node.forEndpoint(this.endpoint) as ServerNode;
+        logger.info(
+            `initialized on endpoint=${this.endpoint.number} (id="${this.endpoint.id}") cluster=0x${WebRtcTransportRequestor.id.toString(16)}`,
+        );
+        this.reactTo(node.lifecycle.online, this.#nodeOnline);
+        if (node.lifecycle.isOnline) {
+            await this.#nodeOnline();
+        }
+    }
+
+    async #nodeOnline() {
+        const fabricAuthority = this.env.get(FabricAuthority);
+        const ownFabric = fabricAuthority.fabrics[0];
+        if (!ownFabric) {
+            // void: fabricAdded is a synchronous observable; awaiting #nodeOnline here deadlocks setStateOf.
+            fabricAuthority.fabricAdded.once(() => void this.#nodeOnline());
+            return;
+        }
+
+        const node = Node.forEndpoint(this.endpoint) as ServerNode;
+        await node.act(agent => agent.load(AccessControlServer));
+        if (node.behaviors.has(AccessControlServer)) {
+            if (
+                !node
+                    .stateOf(AccessControlServer)
+                    .acl.some(
+                        ({ fabricIndex, privilege, authMode, subjects, targets }) =>
+                            fabricIndex === ownFabric.fabricIndex &&
+                            privilege === AccessControl.AccessControlEntryPrivilege.Operate &&
+                            authMode === AccessControl.AccessControlEntryAuthMode.Case &&
+                            subjects?.length === 0 &&
+                            targets?.length === 1 &&
+                            targets[0].endpoint === this.endpoint.number &&
+                            targets[0].cluster === WebRtcTransportRequestor.id,
+                    )
+            ) {
+                const acl = [
+                    ...node.stateOf(AccessControlServer).acl,
+                    {
+                        fabricIndex: ownFabric.fabricIndex,
+                        privilege: AccessControl.AccessControlEntryPrivilege.Operate,
+                        authMode: AccessControl.AccessControlEntryAuthMode.Case,
+                        subjects: [],
+                        targets: [{ endpoint: this.endpoint.number, cluster: WebRtcTransportRequestor.id }],
+                    },
+                ];
+                await node.setStateOf(AccessControlServer, { acl });
+            }
+        }
+    }
+
+    #findSessionStrict(id: number): WebRtcSession {
+        assertRemoteActor(this.context);
+        NodeSession.assert(this.context.session);
+        const peer = this.context.session.peerAddress;
+        const session = this.state.currentSessions.find(s => s.id === id);
+        if (session === undefined || session.fabricIndex !== peer.fabricIndex || session.peerNodeId !== peer.nodeId) {
+            throw new StatusResponseError(`WebRTC session ${id} not found`, Status.NotFound);
+        }
+        return session;
+    }
+}
+
+export namespace WebRtcTransportRequestorServer {
+    export class State extends WebRtcTransportRequestorBehavior.State {
+        override currentSessions: WebRtcSession[] = new Array<WebRtcSession>();
+    }
+    export class Events extends WebRtcTransportRequestorBehavior.Events {
+        offer = Observable<[session: WebRtcSession, args: WebRtcTransportRequestor.OfferRequest]>();
+        answer = Observable<[session: WebRtcSession, sdp: string]>();
+        iceCandidates = Observable<[session: WebRtcSession, candidates: WebRtcTransportDefinitions.IceCandidate[]]>();
+        end = Observable<[session: WebRtcSession, reason: WebRtcTransportDefinitions.WebRtcEndReason]>();
+    }
+}

package/src/index.ts

@@ -9,6 +9,7 @@
  */
 
 // Export controller components
+export * from "./controller/behaviors/WebRtcTransportRequestorServer.js";
 export * from "./controller/ControllerCommandHandler.js";
 export * from "./controller/LegacyDataInjector.js";
 export * from "./controller/MatterController.js";

package/src/server/ConfigStorage.ts

@@ -114,6 +114,26 @@ export class ConfigStorage {
         }
     }
 
+    async removeWifiCredentials() {
+        if (!this.#configStore) {
+            throw new Error("Storage not open");
+        }
+        this.#data.wifiSsid = undefined;
+        this.#data.wifiCredentials = undefined;
+        await this.#configStore.delete("wifiSsid");
+        await this.#configStore.delete("wifiCredentials");
+        logger.info("Removed WiFi credentials");
+    }
+
+    async removeThreadDataset() {
+        if (!this.#configStore) {
+            throw new Error("Storage not open");
+        }
+        this.#data.threadDataset = undefined;
+        await this.#configStore.delete("threadDataset");
+        logger.info("Removed Thread dataset");
+    }
+
     async close() {
         if (this.#storage) {
             await this.#storage.close();

package/src/server/WebSocketControllerHandler.ts

@@ -84,6 +84,7 @@ export class WebSocketControllerHandler implements WebServerHandler {
     #wss?: WebSocketServer;
     #closed = false;
     #shuttingDown = false;
+    #serverObservers = new ObserverGroup();
     /** Circular buffer for recent node events (max 25) */
     #eventHistory: MatterNodeEvent[] = [];
     /** Track when each node was last interviewed (connected) - keyed by nodeId */
@@ -142,6 +143,13 @@ export class WebSocketControllerHandler implements WebServerHandler {
     async register(server: HttpServer) {
         logger.info(`Starting server: matter-server/${this.#serverVersion} (matter.js/${MATTER_VERSION})`);
         const wss = (this.#wss = new WebSocketServer({ server: server, path: "/ws" }));
+
+        // WebRTC callbacks fan out to every connected client, so subscribe once at the server
+        // level rather than per-connection.
+        this.#serverObservers.on(this.#commandHandler.events.webRtcCallback, data => {
+            this.#broadcastEvent("webrtc_callback", data);
+        });
+
         wss.on("connection", ws => {
             if (this.#closed || this.#shuttingDown) {
                 try {
@@ -372,6 +380,7 @@ export class WebSocketControllerHandler implements WebServerHandler {
         }
 
         this.#closed = true;
+        this.#serverObservers.close();
         // Send server_shutdown event to all connected clients before closing
         const shutdownMessage = toBigIntAwareJson({ event: "server_shutdown", data: {} });
         this.#wss.clients.forEach(client => {
@@ -445,6 +454,9 @@ export class WebSocketControllerHandler implements WebServerHandler {
                 case "device_command":
                     result = await this.#handleDeviceCommand(args);
                     break;
+                case "send_webrtc_provider_command":
+                    result = await this.#handleSendWebRtcProviderCommand(args);
+                    break;
                 case "write_attribute":
                     result = await this.#handleWriteAttribute(args);
                     break;
@@ -470,6 +482,12 @@ export class WebSocketControllerHandler implements WebServerHandler {
                 case "set_thread_dataset":
                     result = await this.#handleSetThreadDataset(args);
                     break;
+                case "remove_wifi_credentials":
+                    result = await this.#handleRemoveWifiCredentials();
+                    break;
+                case "remove_thread_dataset":
+                    result = await this.#handleRemoveThreadDataset();
+                    break;
                 case "get_thread_border_routers":
                     result = this.#controller.borderRouters.list();
                     break;
@@ -558,6 +576,7 @@ export class WebSocketControllerHandler implements WebServerHandler {
             min_supported_schema_version: SCHEMA_VERSION,
             sdk_version: `matter-server/${this.#serverVersion} (matter.js/${MATTER_VERSION})`,
             wifi_credentials_set: !!(this.#config.wifiSsid && this.#config.wifiCredentials),
+            wifi_ssid: this.#config.wifiSsid && this.#config.wifiCredentials ? this.#config.wifiSsid : undefined,
             thread_credentials_set: !!this.#config.threadDataset,
             bluetooth_enabled: this.#commandHandler.bleEnabled,
         };
@@ -631,6 +650,9 @@ export class WebSocketControllerHandler implements WebServerHandler {
             }
         }
 
+        // Ensure certificates are loaded and initialized
+        await this.#controller.certificateService();
+
         await this.#config.set({
             nextNodeId: typeof nextNodeId === "bigint" ? nextNodeId + 1n : nextNodeId + 1,
         });
@@ -688,6 +710,9 @@ export class WebSocketControllerHandler implements WebServerHandler {
                 break;
         }
 
+        // Ensure certificates are loaded and initialized
+        await this.#controller.certificateService();
+
         await this.#config.set({
             nextNodeId: typeof nextNodeId === "bigint" ? nextNodeId + 1n : nextNodeId + 1,
         });
@@ -853,6 +878,18 @@ export class WebSocketControllerHandler implements WebServerHandler {
         return cmdResult;
     }
 
+    async #handleSendWebRtcProviderCommand(
+        args: ArgsOf<"send_webrtc_provider_command">,
+    ): Promise<ResponseOf<"send_webrtc_provider_command">> {
+        const { node_id, endpoint_id, command_name, payload } = args;
+        return this.#commandHandler.sendWebRtcProviderCommand({
+            nodeId: NodeId(node_id),
+            endpointId: EndpointNumber(endpoint_id),
+            commandName: command_name,
+            payload,
+        });
+    }
+
     async #handleInterviewNode(args: ArgsOf<"interview_node">): Promise<ResponseOf<"interview_node">> {
         const { node_id } = args;
         const nodeId = NodeId(node_id);
@@ -927,6 +964,26 @@ export class WebSocketControllerHandler implements WebServerHandler {
         return {};
     }
 
+    async #handleRemoveWifiCredentials(): Promise<ResponseOf<"remove_wifi_credentials">> {
+        await this.#config.removeWifiCredentials();
+        try {
+            await this.#broadcastServerInfoUpdated();
+        } catch (error) {
+            logger.warn("Failed to broadcast server info update", error);
+        }
+        return {};
+    }
+
+    async #handleRemoveThreadDataset(): Promise<ResponseOf<"remove_thread_dataset">> {
+        await this.#config.removeThreadDataset();
+        try {
+            await this.#broadcastServerInfoUpdated();
+        } catch (error) {
+            logger.warn("Failed to broadcast server info update", error);
+        }
+        return {};
+    }
+
     async #handleOpenCommissioningWindow(
         args: ArgsOf<"open_commissioning_window">,
     ): Promise<ResponseOf<"open_commissioning_window">> {