zwave-js 13.2.0 → 13.3.1

package/build/lib/driver/Driver.js

@@ -209,6 +209,17 @@ function checkOptions(options) {
             throw new core_1.ZWaveError(`The inclusionUserCallbacks must contain the following functions: grantSecurityClasses, validateDSKAndEnterPIN, abort!`, core_1.ZWaveErrorCodes.Driver_InvalidOptions);
         }
     }
+    if (options.joinNetworkUserCallbacks) {
+        if (!(0, typeguards_1.isObject)(options.joinNetworkUserCallbacks)) {
+            throw new core_1.ZWaveError(`The joinNetworkUserCallbacks must be an object!`, core_1.ZWaveErrorCodes.Driver_InvalidOptions);
+        }
+        else if (typeof options.joinNetworkUserCallbacks.showDSK
+            !== "function"
+            || typeof options.joinNetworkUserCallbacks.done
+                !== "function") {
+            throw new core_1.ZWaveError(`The joinNetworkUserCallbacks must contain the following functions: showDSK, done!`, core_1.ZWaveErrorCodes.Driver_InvalidOptions);
+        }
+    }
     if (options.rf != undefined) {
         if (options.rf.region != undefined) {
             if (typeof options.rf.region !== "number"
@@ -450,6 +461,24 @@ class Driver extends shared_1.TypedEventEmitter {
         const isLongRange = (0, core_1.isLongRangeNodeId)(nodeId);
         return isLongRange ? this.securityManagerLR : this.securityManager2;
     }
+    _learnModeAuthenticatedKeyPair;
+    /** @internal */
+    getLearnModeAuthenticatedKeyPair() {
+        if (this._learnModeAuthenticatedKeyPair == undefined) {
+            // Try restoring from cache
+            const privateKey = this.cacheGet(NetworkCache_1.cacheKeys.controller.privateKey);
+            if (privateKey) {
+                this._learnModeAuthenticatedKeyPair =
+                    (0, core_1.keyPairFromRawECDHPrivateKey)(privateKey);
+            }
+            else {
+                // Not found in cache, create a new one and cache it
+                this._learnModeAuthenticatedKeyPair = (0, core_1.generateECDHKeyPair)();
+                this.cacheSet(NetworkCache_1.cacheKeys.controller.privateKey, (0, core_1.extractRawECDHPrivateKey)(this._learnModeAuthenticatedKeyPair.privateKey));
+            }
+        }
+        return this._learnModeAuthenticatedKeyPair;
+    }
     /**
      * **!!! INTERNAL !!!**
      *
@@ -604,13 +633,16 @@ class Driver extends shared_1.TypedEventEmitter {
             "disableOptimisticValueUpdate",
             "emitValueUpdateAfterSetValue",
             "inclusionUserCallbacks",
+            "joinNetworkUserCallbacks",
             "interview",
             "preferences",
             "vendor",
         ]);
         // Create a new deep-merged copy of the options so we can check them for validity
-        // without affecting our own options
-        const newOptions = (0, shared_1.mergeDeep)((0, shared_1.cloneDeep)(this._options), safeOptions, true);
+        // without affecting our own options. logConfig is potentially unsafe to clone, so just preserve it.
+        const { logConfig, ...rest } = this._options;
+        const newOptions = (0, shared_1.mergeDeep)((0, shared_1.cloneDeep)(rest), safeOptions, true);
+        newOptions.logConfig = logConfig;
         checkOptions(newOptions);
         if (options.userAgent && !(0, typeguards_1.isObject)(options.userAgent)) {
             throw new core_1.ZWaveError(`The userAgent property must be an object!`, core_1.ZWaveErrorCodes.Driver_InvalidOptions);
@@ -903,7 +935,10 @@ class Driver extends shared_1.TypedEventEmitter {
             this._controller
                 .on("node added", this.onNodeAdded.bind(this))
                 .on("node removed", this.onNodeRemoved.bind(this))
-                .on("status changed", this.onControllerStatusChanged.bind(this));
+                .on("status changed", this.onControllerStatusChanged.bind(this))
+                .on("network found", this.onNetworkFound.bind(this))
+                .on("network joined", this.onNetworkJoined.bind(this))
+                .on("network left", this.onNetworkLeft.bind(this));
         }
         if (!this._options.testingHooks?.skipControllerIdentification) {
             // Determine what the controller can do
@@ -942,66 +977,128 @@ class Driver extends shared_1.TypedEventEmitter {
             await this.initValueDBs(this.controller.homeId);
             await this.performCacheMigration();
             // Initialize all nodes and restore the data from cache
-            await this._controller.initNodes(nodeIds, lrNodeIds ?? [], async () => {
+            await this.controller.initNodes(nodeIds, lrNodeIds ?? [], async () => {
                 // Try to restore the network information from the cache
                 if (process.env.NO_CACHE !== "true") {
                     await this.restoreNetworkStructureFromCache();
                 }
             });
-            // Auto-enable smart start inclusion
-            this._controller.autoProvisionSmartStart();
-        }
-        // Set up the S0 security manager. We can only do that after the controller
-        // interview because we need to know the controller node id.
-        const S0Key = this._options.securityKeys?.S0_Legacy;
-        if (S0Key) {
-            this.driverLog.print("Network key for S0 configured, enabling S0 security manager...");
-            this._securityManager = new core_1.SecurityManager({
-                networkKey: S0Key,
-                ownNodeId: this._controller.ownNodeId,
-                nonceTimeout: this._options.timeouts.nonce,
-            });
+            if (this.controller.role === core_1.ControllerRole.Primary) {
+                // Auto-enable smart start inclusion
+                this.controller.autoProvisionSmartStart();
+            }
         }
         else {
-            this.driverLog.print("No network key for S0 configured, communication with secure (S0) devices won't work!", "warn");
-        }
-        // The S2 security manager could be initialized earlier, but we do it here for consistency
-        if (this._options.securityKeys
-            // Only set it up if we have security keys for at least one S2 security class
-            && Object.keys(this._options.securityKeys).some((key) => key.startsWith("S2_")
-                && key in core_1.SecurityClass
-                && (0, core_1.securityClassIsS2)(core_1.SecurityClass[key]))) {
-            this.driverLog.print("At least one network key for S2 configured, enabling S2 security manager...");
-            this._securityManager2 = new core_1.SecurityManager2();
-            // Set up all keys
-            for (const secClass of [
-                "S2_Unauthenticated",
-                "S2_Authenticated",
-                "S2_AccessControl",
-                "S0_Legacy",
-            ]) {
-                const key = this._options.securityKeys[secClass];
-                if (key) {
-                    this._securityManager2.setKey(core_1.SecurityClass[secClass], key);
+            // When skipping the controller identification, set the flags to consider the controller a primary
+            this.controller["_wasRealPrimary"] = true;
+            this.controller["_isSUC"] = true;
+            this.controller["_isSISPresent"] = true;
+            this.controller["_sucNodeId"] = 1;
+        }
+        if (this.controller.role === core_1.ControllerRole.Primary) {
+            // Set up the S0 security manager. We can only do that after the controller
+            // interview because we need to know the controller node id.
+            const S0Key = this._options.securityKeys?.S0_Legacy;
+            if (S0Key) {
+                this.driverLog.print("Network key for S0 configured, enabling S0 security manager...");
+                this._securityManager = new core_1.SecurityManager({
+                    networkKey: S0Key,
+                    ownNodeId: this._controller.ownNodeId,
+                    nonceTimeout: this._options.timeouts.nonce,
+                });
+            }
+            else {
+                this.driverLog.print("No network key for S0 configured, communication with secure (S0) devices won't work!", "warn");
+            }
+            // The S2 security manager could be initialized earlier, but we do it here for consistency
+            if (this._options.securityKeys
+                // Only set it up if we have security keys for at least one S2 security class
+                && Object.keys(this._options.securityKeys).some((key) => key.startsWith("S2_")
+                    && key in core_1.SecurityClass
+                    && (0, core_1.securityClassIsS2)(core_1.SecurityClass[key]))) {
+                this.driverLog.print("At least one network key for S2 configured, enabling S2 security manager...");
+                this._securityManager2 = new core_1.SecurityManager2();
+                // Set up all keys
+                for (const secClass of [
+                    "S2_Unauthenticated",
+                    "S2_Authenticated",
+                    "S2_AccessControl",
+                    "S0_Legacy",
+                ]) {
+                    const key = this._options.securityKeys[secClass];
+                    if (key) {
+                        this._securityManager2.setKey(core_1.SecurityClass[secClass], key);
+                    }
                 }
             }
-        }
-        else {
-            this.driverLog.print("No network key for S2 configured, communication with secure (S2) devices won't work!", "warn");
-        }
-        if (this._options.securityKeysLongRange?.S2_AccessControl
-            || this._options.securityKeysLongRange?.S2_Authenticated) {
-            this.driverLog.print("At least one network key for Z-Wave Long Range configured, enabling security manager...");
-            this._securityManagerLR = new core_1.SecurityManager2();
-            if (this._options.securityKeysLongRange?.S2_AccessControl) {
-                this._securityManagerLR.setKey(core_1.SecurityClass.S2_AccessControl, this._options.securityKeysLongRange.S2_AccessControl);
+            else {
+                this.driverLog.print("No network key for S2 configured, communication with secure (S2) devices won't work!", "warn");
+            }
+            if (this._options.securityKeysLongRange?.S2_AccessControl
+                || this._options.securityKeysLongRange?.S2_Authenticated) {
+                this.driverLog.print("At least one network key for Z-Wave Long Range configured, enabling security manager...");
+                this._securityManagerLR = new core_1.SecurityManager2();
+                if (this._options.securityKeysLongRange?.S2_AccessControl) {
+                    this._securityManagerLR.setKey(core_1.SecurityClass.S2_AccessControl, this._options.securityKeysLongRange.S2_AccessControl);
+                }
+                if (this._options.securityKeysLongRange?.S2_Authenticated) {
+                    this._securityManagerLR.setKey(core_1.SecurityClass.S2_Authenticated, this._options.securityKeysLongRange.S2_Authenticated);
+                }
             }
-            if (this._options.securityKeysLongRange?.S2_Authenticated) {
-                this._securityManagerLR.setKey(core_1.SecurityClass.S2_Authenticated, this._options.securityKeysLongRange.S2_Authenticated);
+            else {
+                this.driverLog.print("No network key for Z-Wave Long Range configured, communication won't work!", "warn");
             }
         }
         else {
-            this.driverLog.print("No network key for Z-Wave Long Range configured, communication won't work!", "warn");
+            // Secondary controller - load security keys from cache.
+            // Either LR or S2+S0, not both
+            if ((0, core_1.isLongRangeNodeId)(this.controller.ownNodeId)) {
+                const securityKeysLongRange = [
+                    core_1.SecurityClass.S2_AccessControl,
+                    core_1.SecurityClass.S2_Authenticated,
+                ].map((sc) => [
+                    sc,
+                    this.cacheGet(NetworkCache_1.cacheKeys.controller.securityKeysLongRange(sc)),
+                ]).filter((v) => v[1] != undefined);
+                if (securityKeysLongRange.length) {
+                    this.driverLog.print("At least one network key for Z-Wave Long Range found in cache, enabling security manager...");
+                    this._securityManagerLR = new core_1.SecurityManager2();
+                    for (const [sc, key] of securityKeysLongRange) {
+                        this._securityManagerLR.setKey(sc, key);
+                    }
+                }
+                else {
+                    this.driverLog.print("No network key for Z-Wave Long Range configured, communication won't work!", "warn");
+                }
+            }
+            else {
+                const s0Key = this.cacheGet(NetworkCache_1.cacheKeys.controller.securityKeys(core_1.SecurityClass.S0_Legacy));
+                if (s0Key) {
+                    this.driverLog.print("Network key for S0 found in cache, enabling S0 security manager...");
+                    this._securityManager = new core_1.SecurityManager({
+                        networkKey: s0Key,
+                        ownNodeId: this._controller.ownNodeId,
+                        nonceTimeout: this._options.timeouts.nonce,
+                    });
+                }
+                else {
+                    this.driverLog.print("No network key for S0 found in cache, communication with secure (S0) devices won't work!", "warn");
+                }
+                const securityKeys = core_1.securityClassOrder.map((sc) => [
+                    sc,
+                    this.cacheGet(NetworkCache_1.cacheKeys.controller.securityKeys(sc)),
+                ]).filter((v) => v[1] != undefined);
+                if (securityKeys.length) {
+                    this.driverLog.print("At least one network key for S2 found in cache, enabling S2 security manager...");
+                    this._securityManager2 = new core_1.SecurityManager2();
+                    for (const [sc, key] of securityKeys) {
+                        this._securityManager2.setKey(sc, key);
+                    }
+                }
+                else {
+                    this.driverLog.print("No network key for S2 found in cache, communication with secure (S2) devices won't work!", "warn");
+                }
+            }
         }
         // in any case we need to emit the driver ready event here
         this._controllerInterviewed = true;
@@ -1011,56 +1108,96 @@ class Driver extends shared_1.TypedEventEmitter {
         for (const node of this._controller.nodes.values()) {
             this.addNodeEventHandlers(node);
         }
-        // Before interviewing nodes reset our knowledge about their ready state
-        this._nodesReady.clear();
-        this._nodesReadyEventEmitted = false;
-        if (!this._options.testingHooks?.skipNodeInterview) {
-            // Now interview all nodes
-            // First complete the controller interview
-            const controllerNode = this._controller.nodes.get(this._controller.ownNodeId);
-            await this.interviewNodeInternal(controllerNode);
-            // The controller node is always alive
-            controllerNode.markAsAlive();
-            // Then do all the nodes in parallel, but prioritize nodes that are more likely to be ready
-            const nodeInterviewOrder = [...this._controller.nodes.values()]
-                .filter((n) => n.id !== this._controller.ownNodeId)
-                .sort((a, b) => 
-            // Fully-interviewed devices first (need the least amount of communication now)
-            (b.interviewStage - a.interviewStage)
-                // Always listening -> FLiRS -> sleeping
-                || ((b.isListening ? 2 : b.isFrequentListening ? 1 : 0)
-                    - (a.isListening ? 2 : a.isFrequentListening ? 1 : 0))
-                // Then by last seen, more recently first
-                || ((b.lastSeen?.getTime() ?? 0)
-                    - (a.lastSeen?.getTime() ?? 0))
-                // Lastly ascending by node ID
-                || (a.id - b.id));
-            this.controllerLog.print(`Interviewing nodes and/or determining their status: ${nodeInterviewOrder.map((n) => n.id).join(", ")}`);
-            for (const node of nodeInterviewOrder) {
-                if (node.id === this._controller.ownNodeId) {
-                    continue;
+        if (this.controller.role === core_1.ControllerRole.Primary) {
+            // Before interviewing nodes reset our knowledge about their ready state
+            this._nodesReady.clear();
+            this._nodesReadyEventEmitted = false;
+            if (!this._options.testingHooks?.skipNodeInterview) {
+                // Now interview all nodes
+                // First complete the controller interview
+                const controllerNode = this._controller.nodes.get(this._controller.ownNodeId);
+                await this.interviewNodeInternal(controllerNode);
+                // The controller node is always alive
+                controllerNode.markAsAlive();
+                // Then do all the nodes in parallel, but prioritize nodes that are more likely to be ready
+                const nodeInterviewOrder = [...this._controller.nodes.values()]
+                    .filter((n) => n.id !== this._controller.ownNodeId)
+                    .sort((a, b) => 
+                // Fully-interviewed devices first (need the least amount of communication now)
+                (b.interviewStage - a.interviewStage)
+                    // Always listening -> FLiRS -> sleeping
+                    || ((b.isListening ? 2 : b.isFrequentListening ? 1 : 0)
+                        - (a.isListening
+                            ? 2
+                            : a.isFrequentListening
+                                ? 1
+                                : 0))
+                    // Then by last seen, more recently first
+                    || ((b.lastSeen?.getTime() ?? 0)
+                        - (a.lastSeen?.getTime() ?? 0))
+                    // Lastly ascending by node ID
+                    || (a.id - b.id));
+                if (nodeInterviewOrder.length) {
+                    this.controllerLog.print(`Interviewing nodes and/or determining their status: ${nodeInterviewOrder.map((n) => n.id).join(", ")}`);
+                    for (const node of nodeInterviewOrder) {
+                        if (node.canSleep) {
+                            // A node that can sleep should be assumed to be sleeping after resuming from cache
+                            node.markAsAsleep();
+                        }
+                        void (async () => {
+                            // Continue the interview if necessary. If that is not necessary, at least
+                            // determine the node's status
+                            if (node.interviewStage < _Types_1.InterviewStage.Complete) {
+                                await this.interviewNodeInternal(node);
+                            }
+                            else if (node.isListening || node.isFrequentListening) {
+                                // Ping non-sleeping nodes to determine their status
+                                await node.ping();
+                            }
+                        })();
+                    }
                 }
-                else if (node.canSleep) {
-                    // A node that can sleep should be assumed to be sleeping after resuming from cache
-                    node.markAsAsleep();
+            }
+        }
+        else {
+            if (!this._options.testingHooks?.skipNodeInterview) {
+                // We're a secondary controller. Just determine if nodes are ready and do the interview at another time.
+                // First complete the controller "interview"
+                const controllerNode = this._controller.nodes.get(this._controller.ownNodeId);
+                await this.interviewNodeInternal(controllerNode);
+                // The controller node is always alive
+                controllerNode.markAsAlive();
+                // Query the protocol information from the controller
+                for (const node of this._controller.nodes.values()) {
+                    if (node.isControllerNode)
+                        continue;
+                    await node["queryProtocolInfo"]();
                 }
-                void (async () => {
-                    // Continue the interview if necessary. If that is not necessary, at least
-                    // determine the node's status
-                    if (node.interviewStage < _Types_1.InterviewStage.Complete) {
-                        await this.interviewNodeInternal(node);
-                    }
-                    else if (node.isListening || node.isFrequentListening) {
-                        // Ping non-sleeping nodes to determine their status
-                        await node.ping();
+                // Then ping (frequently) listening nodes to determine their status
+                const nodeInterviewOrder = [...this._controller.nodes.values()]
+                    .filter((n) => n.id !== this._controller.ownNodeId)
+                    .filter((n) => n.isListening || n.isFrequentListening)
+                    .sort((a, b) => 
+                // Always listening -> FLiRS
+                ((b.isListening ? 1 : 0)
+                    - (a.isListening ? 1 : 0))
+                    // Then by last seen, more recently first
+                    || ((b.lastSeen?.getTime() ?? 0)
+                        - (a.lastSeen?.getTime() ?? 0))
+                    // Lastly ascending by node ID
+                    || (a.id - b.id));
+                if (nodeInterviewOrder.length) {
+                    this.controllerLog.print(`Determining node status: ${nodeInterviewOrder.map((n) => n.id).join(", ")}`);
+                    for (const node of nodeInterviewOrder) {
+                        void node.ping();
                     }
-                })();
+                }
             }
-            // If we only have sleeping nodes or a controller-only network, the send
-            // thread is idle before the driver gets marked ready, the idle tasks won't be triggered.
-            // So do it manually.
-            this.handleQueueIdleChange(this.queueIdle);
         }
+        // If we only have sleeping nodes or a controller-only network, the send
+        // thread is idle before the driver gets marked ready, the idle tasks won't be triggered.
+        // So do it manually.
+        this.handleQueueIdleChange(this.queueIdle);
     }
     autoRefreshNodeValueTimers = new Map();
     retryNodeInterviewTimeouts = new Map();
@@ -1451,6 +1588,36 @@ class Driver extends shared_1.TypedEventEmitter {
     onControllerStatusChanged(_status) {
         this.triggerQueues();
     }
+    async onNetworkFound(homeId, _ownNodeId) {
+        try {
+            this.driverLog.print(`Joined network with home ID ${(0, shared_1.num2hex)(homeId)}, switching to new network cache...`);
+            await this.recreateNetworkCacheAndValueDBs();
+        }
+        catch (e) {
+            this.driverLog.print(`Recreating the network cache and value DBs failed: ${(0, shared_1.getErrorMessage)(e)}`, "error");
+        }
+    }
+    onNetworkJoined() {
+        this.driverLog.print(`Finished joining network`);
+    }
+    async onNetworkLeft() {
+        try {
+            this.driverLog.print(`Left the previous network, switching network cache to new home ID ${(0, shared_1.num2hex)(this.controller.homeId)}...`);
+            await this.recreateNetworkCacheAndValueDBs();
+        }
+        catch (e) {
+            this.driverLog.print(`Recreating the network cache and value DBs failed: ${(0, shared_1.getErrorMessage)(e)}`, "error");
+        }
+    }
+    async recreateNetworkCacheAndValueDBs() {
+        await this._networkCache?.close();
+        await this._valueDB?.close();
+        await this._metadataDB?.close();
+        // Reopen with the new home ID
+        await this.initNetworkCache(this.controller.homeId);
+        await this.initValueDBs(this.controller.homeId);
+        await this.performCacheMigration();
+    }
     /**
      * Returns the time in seconds to actually wait after a firmware upgrade, depending on what the device said.
      * This number will always be a bit greater than the advertised duration, because devices have been found to take longer to actually reboot.
@@ -1897,6 +2064,8 @@ class Driver extends shared_1.TypedEventEmitter {
             this.controllerLog.print(message, "error");
             throw new core_1.ZWaveError(message, core_1.ZWaveErrorCodes.FirmwareUpdateCC_NetworkBusy);
         }
+        // Preserve the private key for the authenticated learn mode ECDH key pair
+        const oldPrivateKey = this.cacheGet(NetworkCache_1.cacheKeys.controller.privateKey);
         // Update the controller NIF prior to hard resetting
         await this.controller.setControllerNIF();
         await this.controller.hardReset();
@@ -1914,6 +2083,12 @@ class Driver extends shared_1.TypedEventEmitter {
         }
         this._controllerInterviewed = false;
         void this.initializeControllerAndNodes();
+        // Save the key pair in the new cache again
+        if (oldPrivateKey) {
+            this.once("driver ready", () => {
+                this.cacheSet(NetworkCache_1.cacheKeys.controller.privateKey, oldPrivateKey);
+            });
+        }
     }
     /**
      * Instructs the Z-Wave API to shut down in order to safely remove the power.
@@ -4681,7 +4856,7 @@ ${handlers.length} left`);
         }
     }
     /** Computes the maximum net CC payload size for the given CC or SendDataRequest */
-    computeNetCCPayloadSize(commandOrMsg) {
+    computeNetCCPayloadSize(commandOrMsg, ignoreEncapsulation = false) {
         // Recreate the correct encapsulation structure
         let msg;
         if ((0, SendDataShared_1.isSendDataSinglecast)(commandOrMsg)) {
@@ -4691,7 +4866,9 @@ ${handlers.length} left`);
             const SendDataConstructor = this.getSendDataSinglecastConstructor();
             msg = new SendDataConstructor(this, { command: commandOrMsg });
         }
-        msg.command = this.encapsulateCommands(msg.command);
+        if (!ignoreEncapsulation) {
+            msg.command = this.encapsulateCommands(msg.command);
+        }
         return msg.command.getMaxPayloadLength(this.getMaxPayloadLength(msg));
     }
     /** Computes the maximum payload size that can be transmitted with the given message */
@@ -5062,6 +5239,22 @@ ${handlers.length} left`);
             };
         }
     }
+    /**
+     * Resets the S2 singlecast encryption state (SPAN) for the given node, which forces
+     * a re-synchronization on the next communication attempt.
+     */
+    resetSPAN(nodeId) {
+        this.getSecurityManager2(nodeId)?.deleteNonce(nodeId);
+    }
+    /**
+     * Resets the S2 singlecast encryption state (SPAN) for all nodes, which forces
+     * a re-synchronization on the next communication attempt.
+     */
+    resetAllSPANs() {
+        for (const nodeId of this.controller.nodes.keys()) {
+            this.resetSPAN(nodeId);
+        }
+    }
 }
 exports.Driver = Driver;
 //# sourceMappingURL=Driver.js.map