feat: support pre-filling the DSK and scanning DSK-only QRs

packages/core/api.md

@@ -2312,6 +2312,11 @@ export enum TransmitStatus {
     OK = 0
 }
 
+// Warning: (ae-missing-release-tag) "tryParseDSKFromQRCodeString" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public
+export function tryParseDSKFromQRCodeString(qr: string): string | undefined;
+
 // Warning: (ae-missing-release-tag) "TXReport" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)

packages/core/src/security/QR.ts

@@ -2,7 +2,7 @@ import { createHash } from "crypto";
 import { Protocols } from "../capabilities/Protocols";
 import { ZWaveError, ZWaveErrorCodes } from "../error/ZWaveError";
 import { parseBitMask } from "../values/Primitive";
-import { dskToString } from "./DSK";
+import { dskToString, isValidDSK } from "./DSK";
 import { SecurityClass } from "./SecurityClass";
 
 function readNumber(qr: string, offset: number, length: number): number {
@@ -217,6 +217,21 @@ function parseTLV(qr: string): {
 	};
 }
 
+/**
+ * Tries to extract a DSK from a scanned QR code. If the string is a valid DSK (prefixed with "zws2dsk:" or unprefixed), the DSK will be returned.
+ * This can then be used to initiate an S2 inclusion with pre-filled DSK.
+ */
+export function tryParseDSKFromQRCodeString(qr: string): string | undefined {
+	// Trim off whitespace that might have been copied by accident
+	qr = qr.trim();
+	if (qr.startsWith("zws2dsk:")) {
+		qr = qr.slice("zws2dsk:".length);
+	}
+	if (isValidDSK(qr)) {
+		return qr;
+	}
+}
+
 /** Parses a string that has been decoded from a Z-Wave (S2 or SmartStart) QR code */
 export function parseQRCodeString(qr: string): QRProvisioningInformation {
 	// Trim off whitespace that might have been copied by accident

packages/zwave-js/api.md

@@ -526,6 +526,7 @@ export type InclusionOptions = {
     forceSecurity?: boolean;
 } | {
     strategy: InclusionStrategy.Security_S2;
+    dsk?: string;
     userCallbacks?: InclusionUserCallbacks;
 } | {
     strategy: InclusionStrategy.Security_S2;

packages/zwave-js/src/lib/controller/Controller.ts

@@ -34,6 +34,7 @@ import {
 	indexDBsByNode,
 	isRecoverableZWaveError,
 	isTransmissionError,
+	isValidDSK,
 	isZWaveError,
 	NodeType,
 	NODE_ID_BROADCAST,
@@ -2493,13 +2494,23 @@ supported CCs: ${nodeInfo.supportedCCs
 				const tai2RemainingMs =
 					inclusionTimeouts.TAI2 - (Date.now() - timerStartTAI2);
 
-				const pinResult = await Promise.race([
-					wait(tai2RemainingMs, true).then(() => false as const),
-					userCallbacks
-						.validateDSKAndEnterPIN(dsk)
-						// ignore errors in application callbacks
-						.catch(() => false as const),
-				]);
+				let pinResult: string | false;
+				if (
+					"dsk" in inclusionOptions &&
+					typeof inclusionOptions.dsk === "string" &&
+					isValidDSK(inclusionOptions.dsk)
+				) {
+					pinResult = inclusionOptions.dsk.slice(0, 5);
+				} else {
+					pinResult = await Promise.race([
+						wait(tai2RemainingMs, true).then(() => false as const),
+						userCallbacks
+							.validateDSKAndEnterPIN(dsk)
+							// ignore errors in application callbacks
+							.catch(() => false as const),
+					]);
+				}
+
 				if (
 					typeof pinResult !== "string" ||
 					!/^\d{5}$/.test(pinResult)

packages/zwave-js/src/lib/controller/Inclusion.ts

@@ -106,6 +106,11 @@ export type InclusionOptions =
 	  }
 	| {
 			strategy: InclusionStrategy.Security_S2;
+			/**
+			 * Allows pre-filling the DSK, e.g. when a DSK-only QR code has been scanned.
+			 * If this is given, the `validateDSKAndEnterPIN` callback will not be called.
+			 */
+			dsk?: string;
 			/**
 			 * Allows overriding the user callbacks for this inclusion.
 			 * If not given, the inclusion user callbacks of the driver options will be used.