@zwave-js/cc 15.31.2 → 15.32.0

package/build/esm/cc/UserCredentialCC.js

@@ -2,7 +2,7 @@ import { __esDecorate, __runInitializers } from "tslib";
 import * as __validateArgs from "./UserCredentialCC._validateArgs.js";
 const { validateArgs_UserCredentialCCAPI_setUser, validateArgs_UserCredentialCCAPI_getUser, validateArgs_UserCredentialCCAPI_setCredential, validateArgs_UserCredentialCCAPI_getCredential, validateArgs_UserCredentialCCAPI_startCredentialLearn, validateArgs_UserCredentialCCAPI_setUserCredentialAssociation, validateArgs_UserCredentialCCAPI_getUserChecksum, validateArgs_UserCredentialCCAPI_getCredentialChecksum, validateArgs_UserCredentialCCAPI_setAdminPinCode, validateArgs_UserCredentialCCAPI_setKeyLockerEntry, validateArgs_UserCredentialCCAPI_getKeyLockerEntry, validateArgs_UserCredentialCCAPI_sendUserCapabilitiesReport, validateArgs_UserCredentialCCAPI_sendCredentialCapabilitiesReport, validateArgs_UserCredentialCCAPI_sendKeyLockerCapabilitiesReport, validateArgs_UserCredentialCCAPI_sendUserReport, validateArgs_UserCredentialCCAPI_sendCredentialReport, validateArgs_UserCredentialCCAPI_sendCredentialLearnReport, validateArgs_UserCredentialCCAPI_sendUserCredentialAssociationReport, validateArgs_UserCredentialCCAPI_sendAllUsersChecksumReport, validateArgs_UserCredentialCCAPI_sendUserChecksumReport, validateArgs_UserCredentialCCAPI_sendCredentialChecksumReport, validateArgs_UserCredentialCCAPI_sendAdminPinCodeReport, validateArgs_UserCredentialCCAPI_sendKeyLockerEntryReport } = __validateArgs;
 import { CommandClasses, MessagePriority, ZWaveError, ZWaveErrorCodes, encodeBitMask, parseBitMask, validatePayload, } from "@zwave-js/core";
-import { Bytes, getEnumMemberName, pick, stringToUint8ArrayUTF16BE, uint8ArrayToStringUTF16BE, } from "@zwave-js/shared";
+import { Bytes, stripControlCharacters, getEnumMemberName, pick, stringToUint8ArrayUTF16BE, uint8ArrayToStringUTF16BE, } from "@zwave-js/shared";
 import { CCAPI, PhysicalCCAPI } from "../lib/API.js";
 import { CommandClass, getEffectiveCCVersion, } from "../lib/CommandClass.js";
 import { API, CCCommand, ccValueProperty, ccValues, commandClass, expectedCCResponse, implementedVersion, useSupervision, } from "../lib/CommandClassDecorators.js";
@@ -18,12 +18,30 @@ function credentialToLogString(credential) {
  * credentials (biometric data, BLE/NFC/RFID identifiers, ...) as raw bytes.
  */
 export function normalizeCredentialData(credentialType, credentialData) {
-    if (credentialType === UserCredentialType.PINCode
-        || credentialType === UserCredentialType.Password) {
+    if (credentialType === UserCredentialType.PINCode) {
         return credentialData.toString("utf8");
     }
+    if (credentialType === UserCredentialType.Password) {
+        // Passwords are UTF-16BE on the wire (CC:0083.01.0A.11.021). Received
+        // commands with an odd length are rejected when they are parsed.
+        return uint8ArrayToStringUTF16BE(credentialData);
+    }
     return credentialData;
 }
+/**
+ * Converts a credential to the bytes transmitted to the node. Strings are
+ * encoded according to the credential type, the inverse of
+ * {@link normalizeCredentialData}.
+ */
+export function encodeCredentialData(credentialType, credentialData) {
+    if (typeof credentialData !== "string")
+        return Bytes.from(credentialData);
+    if (credentialType === UserCredentialType.Password) {
+        // CC:0083.01.0A.11.021
+        return Bytes.from(stringToUint8ArrayUTF16BE(credentialData));
+    }
+    return Bytes.from(credentialData, "utf-8");
+}
 import { UserCredentialCCValues } from "./_CCValues.generated.js";
 export { UserCredentialCCValues };
 // API class
@@ -213,6 +231,20 @@ let UserCredentialCCAPI = (() => {
          */
         async setUser(options) {
             this.assertSupportsCommand(UserCredentialCommand, UserCredentialCommand.UserSet);
+            if (options.operationType !== UserCredentialOperationType.Delete
+                && options.nameEncoding == undefined) {
+                const userName = options.userName ?? "";
+                const supportedEncodings = this.tryGetValueDB()?.getValue(UserCredentialCCValues.supportedUserNameEncodings.endpoint(this.endpoint.index)) ?? [
+                    UserCredentialNameEncoding.ASCII,
+                    UserCredentialNameEncoding.ExtendedASCII,
+                    UserCredentialNameEncoding.UTF16BE,
+                ];
+                const nameEncoding = chooseNameEncoding(userName, supportedEncodings);
+                if (nameEncoding == undefined) {
+                    throw new ZWaveError(`The user name "${userName}" cannot be encoded with any of the encodings supported by the node`, ZWaveErrorCodes.Argument_Invalid);
+                }
+                options = { ...options, nameEncoding };
+            }
             const cc = new UserCredentialCCUserSet({
                 nodeId: this.endpoint.nodeId,
                 endpointIndex: this.endpoint.index,
@@ -1179,6 +1211,43 @@ function testResponseForUserCredentialUserSet(sent, received) {
     return (received.reportType !== UserCredentialUserReportType.ResponseToGet
         && received.userId === sent.userId);
 }
+// ASCII and Extended ASCII user names use a single byte per character, so they are
+// interpreted as ISO-8859-1, whose code points match the byte values
+function decodeSingleByteName(data) {
+    return String.fromCharCode(...data);
+}
+function encodeSingleByteName(name, encoding) {
+    const maxCharCode = encoding === UserCredentialNameEncoding.ExtendedASCII ? 0xff : 0x7f;
+    const ret = new Bytes(name.length);
+    for (let i = 0; i < name.length; i++) {
+        const code = name.charCodeAt(i);
+        if (code > maxCharCode) {
+            throw new ZWaveError(`The user name "${name}" cannot be encoded as ${encoding === UserCredentialNameEncoding.ExtendedASCII
+                ? "Extended ASCII"
+                : "ASCII"}`, ZWaveErrorCodes.Argument_Invalid);
+        }
+        ret[i] = code;
+    }
+    return ret;
+}
+/** Returns the most compact encoding out of `supported` that can represent the user name */
+function chooseNameEncoding(name, supported) {
+    let maxCharCode = 0;
+    for (let i = 0; i < name.length; i++) {
+        maxCharCode = Math.max(maxCharCode, name.charCodeAt(i));
+    }
+    if (maxCharCode <= 0x7f
+        && supported.includes(UserCredentialNameEncoding.ASCII)) {
+        return UserCredentialNameEncoding.ASCII;
+    }
+    else if (maxCharCode <= 0xff
+        && supported.includes(UserCredentialNameEncoding.ExtendedASCII)) {
+        return UserCredentialNameEncoding.ExtendedASCII;
+    }
+    else if (supported.includes(UserCredentialNameEncoding.UTF16BE)) {
+        return UserCredentialNameEncoding.UTF16BE;
+    }
+}
 let UserCredentialCCUserSet = (() => {
     let _classDecorators = [CCCommand(UserCredentialCommand.UserSet), expectedCCResponse(() => UserCredentialCCUserReport, testResponseForUserCredentialUserSet)];
     let _classDescriptor;
@@ -1243,13 +1312,13 @@ let UserCredentialCCUserSet = (() => {
             validatePayload(raw.payload.length >= 10 + nameLength);
             let userName;
             if (nameEncoding === UserCredentialNameEncoding.UTF16BE) {
+                validatePayload(nameLength % 2 === 0);
                 userName = uint8ArrayToStringUTF16BE(raw.payload.subarray(10, 10 + nameLength));
             }
             else {
-                userName = raw.payload
-                    .subarray(10, 10 + nameLength)
-                    .toString("ascii");
+                userName = decodeSingleByteName(raw.payload.subarray(10, 10 + nameLength));
             }
+            userName = stripControlCharacters(userName);
             if (userType === UserCredentialUserType.Expiring) {
                 return new this({
                     nodeId: ctx.sourceNodeId,
@@ -1288,6 +1357,9 @@ let UserCredentialCCUserSet = (() => {
             if (this.active == undefined) {
                 throw new ZWaveError(`${this.constructor.name}: The active flag must be set for Add/Modify operations`, ZWaveErrorCodes.Argument_Invalid);
             }
+            if (this.nameEncoding == undefined) {
+                throw new ZWaveError(`${this.constructor.name}: name encoding must be set for Add/Modify operations`, ZWaveErrorCodes.Argument_Invalid);
+            }
             // Credential rule defaults to Single
             const credentialRule = this.credentialRule ?? UserCredentialRule.Single;
             // Expiring timeout MUST be 0 for non-Expiring user types
@@ -1301,16 +1373,18 @@ let UserCredentialCCUserSet = (() => {
             else {
                 expiringTimeoutMinutes = 0;
             }
-            // Name encoding defaults to ASCII
-            const nameEncoding = this.nameEncoding ?? UserCredentialNameEncoding.ASCII;
             // User name defaults to empty string
             const userName = this.userName ?? "";
+            const nameEncoding = this.nameEncoding;
             let nameBuffer;
             if (nameEncoding === UserCredentialNameEncoding.UTF16BE) {
                 nameBuffer = stringToUint8ArrayUTF16BE(userName);
             }
+            else if (nameEncoding === UserCredentialNameEncoding.ExtendedASCII) {
+                nameBuffer = encodeSingleByteName(userName, UserCredentialNameEncoding.ExtendedASCII);
+            }
             else {
-                nameBuffer = Bytes.from(userName, "ascii");
+                nameBuffer = encodeSingleByteName(userName, UserCredentialNameEncoding.ASCII);
             }
             this.payload = Bytes.alloc(10 + nameBuffer.length);
             this.payload[0] = this.operationType & 0b11;
@@ -1403,13 +1477,13 @@ let UserCredentialCCUserReport = (() => {
             validatePayload(raw.payload.length >= 15 + nameLength);
             let userName;
             if (nameEncoding === UserCredentialNameEncoding.UTF16BE) {
+                validatePayload(nameLength % 2 === 0);
                 userName = uint8ArrayToStringUTF16BE(raw.payload.subarray(15, 15 + nameLength));
             }
             else {
-                userName = raw.payload
-                    .subarray(15, 15 + nameLength)
-                    .toString("ascii");
+                userName = decodeSingleByteName(raw.payload.subarray(15, 15 + nameLength));
             }
+            userName = stripControlCharacters(userName);
             const common = {
                 nodeId: ctx.sourceNodeId,
                 modifierType,
@@ -1443,8 +1517,11 @@ let UserCredentialCCUserReport = (() => {
             if (this.nameEncoding === UserCredentialNameEncoding.UTF16BE) {
                 nameBuffer = stringToUint8ArrayUTF16BE(this.userName);
             }
+            else if (this.nameEncoding === UserCredentialNameEncoding.ExtendedASCII) {
+                nameBuffer = encodeSingleByteName(this.userName, UserCredentialNameEncoding.ExtendedASCII);
+            }
             else {
-                nameBuffer = Bytes.from(this.userName, "ascii");
+                nameBuffer = encodeSingleByteName(this.userName, UserCredentialNameEncoding.ASCII);
             }
             this.payload = Bytes.alloc(15 + nameBuffer.length);
             this.payload[0] = this.reportType;
@@ -1690,6 +1767,9 @@ let UserCredentialCCCredentialSet = (() => {
             if (raw.payload.length >= 7) {
                 const credentialLength = raw.payload[6];
                 validatePayload(raw.payload.length >= 7 + credentialLength);
+                // Passwords are UTF-16BE (CC:0083.01.0A.11.021)
+                validatePayload(credentialType !== UserCredentialType.Password
+                    || credentialLength % 2 === 0);
                 credentialData = Bytes.from(raw.payload.subarray(7, 7 + credentialLength));
             }
             return new this({
@@ -1783,6 +1863,16 @@ let UserCredentialCCCredentialReport = (() => {
             const credentialReadBack = !!(raw.payload[6] & 128);
             const credentialLength = raw.payload[7];
             validatePayload(raw.payload.length >= 8 + credentialLength + 6);
+            if (credentialType === UserCredentialType.Password
+                && credentialLength % 2 !== 0) {
+                // CC:0083.01.0C.11.000: If the credential cannot be read back
+                // (CRB is zero), the node MUST instead report a hash sum of the credential.
+                if (credentialReadBack) {
+                    // CC:0083.01.0A.11.021: Passwords MUST be transmitted in Unicode
+                    // UTF-16 format, in big endian order.
+                    validatePayload.fail("Password credentials must have an even length");
+                }
+            }
             const offset = 8 + credentialLength;
             const modifierType = raw.payload[offset];
             const modifierNodeId = raw.payload.readUInt16BE(offset + 1);