@twin.org/crypto 0.0.3-next.14 → 0.0.3-next.16

package/dist/es/passwords/passwordGenerator.js

@@ -1,28 +1,84 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-import { RandomHelper } from "@twin.org/core";
+import { Converter, Guards, RandomHelper } from "@twin.org/core";
+import { Blake2b } from "../hashes/blake2b.js";
 /**
  * Generate random passwords.
  */
 export class PasswordGenerator {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "PasswordGenerator";
+    /**
+     * The minimum password length, 15 to match owasp rules.
+     * @see https://www.owasp.org/index.php/Authentication_Cheat_Sheet#Implement_Proper_Password_Strength_Controls .
+     * @internal
+     */
+    static _DEFAULT_MIN_PASSWORD_LENGTH = 15;
     /**
      * Generate a password of given length.
-     * @param length The length of the password to generate.
+     * @param length The length of the password to generate, default to 15.
      * @returns The random password.
      */
-    static generate(length) {
-        const alphabet = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
-        const alphabet2 = `${alphabet}0123456789!#$£%^&*+=@~?}`;
+    static generate(length = PasswordGenerator._DEFAULT_MIN_PASSWORD_LENGTH) {
+        const lower = "abcdefghijklmnopqrstuvwxyz";
+        const upper = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+        const digits = "0123456789";
+        const specials = "!#$£%^&*+=@~?}";
+        const alphabet = `${lower}${upper}`;
+        const allChars = `${alphabet}${digits}${specials}`;
+        const targetLength = Math.max(length, PasswordGenerator._DEFAULT_MIN_PASSWORD_LENGTH);
         const chars = [];
-        while (chars.length < length) {
-            const charSet = chars.length === 0 ? alphabet : alphabet2;
-            let b = 0;
-            do {
-                b = RandomHelper.generate(1)[0];
-            } while (b >= charSet.length);
-            chars.push(charSet[b]);
+        // Ensure required character classes are present.
+        PasswordGenerator.pushChar(chars, lower);
+        PasswordGenerator.pushChar(chars, upper);
+        PasswordGenerator.pushChar(chars, digits);
+        PasswordGenerator.pushChar(chars, specials);
+        while (chars.length < targetLength) {
+            const charSet = chars.length === 0 ? alphabet : allChars;
+            PasswordGenerator.pushChar(chars, charSet);
         }
         return chars.join("");
     }
+    /**
+     * Hash the password for the user.
+     * @param passwordBytes The password bytes.
+     * @param saltBytes The salt bytes.
+     * @returns The hashed password.
+     */
+    static async hashPassword(passwordBytes, saltBytes) {
+        Guards.uint8Array(PasswordGenerator.CLASS_NAME, "passwordBytes", passwordBytes);
+        Guards.uint8Array(PasswordGenerator.CLASS_NAME, "saltBytes", saltBytes);
+        const combined = new Uint8Array(saltBytes.length + passwordBytes.length);
+        combined.set(saltBytes);
+        combined.set(passwordBytes, saltBytes.length);
+        const hashedPassword = Blake2b.sum256(combined);
+        return Converter.bytesToBase64(hashedPassword);
+    }
+    /**
+     * Get a random character from the given character set.
+     * @param charSet The character set to get a random character from.
+     * @returns A random character from the given character set.
+     */
+    static getRandomChar(charSet) {
+        let b = 0;
+        do {
+            b = RandomHelper.generate(1)[0];
+        } while (b >= charSet.length);
+        return charSet[b];
+    }
+    /**
+     * Push a random character from the given character set to the chars array, ensuring no three repeated characters in a row.
+     * @param chars The array to push the character to.
+     * @param charSet The character set to get a random character from.
+     */
+    static pushChar(chars, charSet) {
+        let next = PasswordGenerator.getRandomChar(charSet);
+        while (chars.length >= 2 && next === chars.at(-1) && next === chars.at(-2)) {
+            next = PasswordGenerator.getRandomChar(charSet);
+        }
+        chars.push(next);
+    }
 }
 //# sourceMappingURL=passwordGenerator.js.map

package/dist/es/passwords/passwordGenerator.js.map

@@ -1 +1 @@
-{"version":3,"file":"passwordGenerator.js","sourceRoot":"","sources":["../../../src/passwords/passwordGenerator.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;GAEG;AACH,MAAM,OAAO,iBAAiB;IAC7B;;;;OAIG;IACI,MAAM,CAAC,QAAQ,CAAC,MAAc;QACpC,MAAM,QAAQ,GAAG,sDAAsD,CAAC;QACxE,MAAM,SAAS,GAAG,GAAG,QAAQ,0BAA0B,CAAC;QAExD,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,OAAO,KAAK,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC;YAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;YAC1D,IAAI,CAAC,GAAG,CAAC,CAAC;YACV,GAAG,CAAC;gBACH,CAAC,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACjC,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,MAAM,EAAE;YAC9B,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACxB,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvB,CAAC;CACD","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { RandomHelper } from \"@twin.org/core\";\n\n/**\n * Generate random passwords.\n */\nexport class PasswordGenerator {\n\t/**\n\t * Generate a password of given length.\n\t * @param length The length of the password to generate.\n\t * @returns The random password.\n\t */\n\tpublic static generate(length: number): string {\n\t\tconst alphabet = \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n\t\tconst alphabet2 = `${alphabet}0123456789!#$£%^&*+=@~?}`;\n\n\t\tconst chars: string[] = [];\n\n\t\twhile (chars.length < length) {\n\t\t\tconst charSet = chars.length === 0 ? alphabet : alphabet2;\n\t\t\tlet b = 0;\n\t\t\tdo {\n\t\t\t\tb = RandomHelper.generate(1)[0];\n\t\t\t} while (b >= charSet.length);\n\t\t\tchars.push(charSet[b]);\n\t\t}\n\n\t\treturn chars.join(\"\");\n\t}\n}\n"]}
+{"version":3,"file":"passwordGenerator.js","sourceRoot":"","sources":["../../../src/passwords/passwordGenerator.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Converter, Guards, RandomHelper } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { Blake2b } from \"../hashes/blake2b.js\";\n\n/**\n * Generate random passwords.\n */\nexport class PasswordGenerator {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<PasswordGenerator>();\n\n\t/**\n\t * The minimum password length, 15 to match owasp rules.\n\t * @see https://www.owasp.org/index.php/Authentication_Cheat_Sheet#Implement_Proper_Password_Strength_Controls .\n\t * @internal\n\t */\n\tprivate static readonly _DEFAULT_MIN_PASSWORD_LENGTH: number = 15;\n\n\t/**\n\t * Generate a password of given length.\n\t * @param length The length of the password to generate, default to 15.\n\t * @returns The random password.\n\t */\n\tpublic static generate(length: number = PasswordGenerator._DEFAULT_MIN_PASSWORD_LENGTH): string {\n\t\tconst lower = \"abcdefghijklmnopqrstuvwxyz\";\n\t\tconst upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n\t\tconst digits = \"0123456789\";\n\t\tconst specials = \"!#$£%^&*+=@~?}\";\n\t\tconst alphabet = `${lower}${upper}`;\n\t\tconst allChars = `${alphabet}${digits}${specials}`;\n\n\t\tconst targetLength = Math.max(length, PasswordGenerator._DEFAULT_MIN_PASSWORD_LENGTH);\n\t\tconst chars: string[] = [];\n\n\t\t// Ensure required character classes are present.\n\t\tPasswordGenerator.pushChar(chars, lower);\n\t\tPasswordGenerator.pushChar(chars, upper);\n\t\tPasswordGenerator.pushChar(chars, digits);\n\t\tPasswordGenerator.pushChar(chars, specials);\n\n\t\twhile (chars.length < targetLength) {\n\t\t\tconst charSet = chars.length === 0 ? alphabet : allChars;\n\t\t\tPasswordGenerator.pushChar(chars, charSet);\n\t\t}\n\n\t\treturn chars.join(\"\");\n\t}\n\n\t/**\n\t * Hash the password for the user.\n\t * @param passwordBytes The password bytes.\n\t * @param saltBytes The salt bytes.\n\t * @returns The hashed password.\n\t */\n\tpublic static async hashPassword(\n\t\tpasswordBytes: Uint8Array,\n\t\tsaltBytes: Uint8Array\n\t): Promise<string> {\n\t\tGuards.uint8Array(PasswordGenerator.CLASS_NAME, nameof(passwordBytes), passwordBytes);\n\t\tGuards.uint8Array(PasswordGenerator.CLASS_NAME, nameof(saltBytes), saltBytes);\n\n\t\tconst combined = new Uint8Array(saltBytes.length + passwordBytes.length);\n\t\tcombined.set(saltBytes);\n\t\tcombined.set(passwordBytes, saltBytes.length);\n\n\t\tconst hashedPassword = Blake2b.sum256(combined);\n\n\t\treturn Converter.bytesToBase64(hashedPassword);\n\t}\n\n\t/**\n\t * Get a random character from the given character set.\n\t * @param charSet The character set to get a random character from.\n\t * @returns A random character from the given character set.\n\t */\n\tprivate static getRandomChar(charSet: string): string {\n\t\tlet b = 0;\n\t\tdo {\n\t\t\tb = RandomHelper.generate(1)[0];\n\t\t} while (b >= charSet.length);\n\t\treturn charSet[b];\n\t}\n\n\t/**\n\t * Push a random character from the given character set to the chars array, ensuring no three repeated characters in a row.\n\t * @param chars The array to push the character to.\n\t * @param charSet The character set to get a random character from.\n\t */\n\tprivate static pushChar(chars: string[], charSet: string): void {\n\t\tlet next = PasswordGenerator.getRandomChar(charSet);\n\t\twhile (chars.length >= 2 && next === chars.at(-1) && next === chars.at(-2)) {\n\t\t\tnext = PasswordGenerator.getRandomChar(charSet);\n\t\t}\n\t\tchars.push(next);\n\t}\n}\n"]}

package/dist/es/passwords/passwordValidator.js

@@ -1,25 +1,35 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-import { Validation } from "@twin.org/core";
+import { Converter, Guards, Validation } from "@twin.org/core";
 /**
  * Test password strength.
- * Ref https://www.owasp.org/index.php/Authentication_Cheat_Sheet#Implement_Proper_Password_Strength_Controls .
+ * @see https://www.owasp.org/index.php/Authentication_Cheat_Sheet#Implement_Proper_Password_Strength_Controls .
  */
 export class PasswordValidator {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "PasswordValidator";
+    /**
+     * The minimum password length, 15 to match owasp rules.
+     * @see https://www.owasp.org/index.php/Authentication_Cheat_Sheet#Implement_Proper_Password_Strength_Controls .
+     * @internal
+     */
+    static _DEFAULT_MIN_PASSWORD_LENGTH = 15;
     /**
      * Test the strength of the password.
      * @param property The name of the property.
      * @param password The password to test.
      * @param failures The list of failures to add to.
      * @param options Options to configure the testing.
-     * @param options.minLength The minimum length of the password, defaults to 8.
+     * @param options.minLength The minimum length of the password, defaults to 15, can be 8 if MFA is enabled.
      * @param options.maxLength The minimum length of the password, defaults to 128.
      * @param options.minPhraseLength The minimum length of the password for it to be considered a pass phrase.
      */
     static validate(property, password, failures, options) {
         const isString = Validation.stringValue(property, password, failures);
         if (isString) {
-            const minLength = options?.minLength ?? 8;
+            const minLength = options?.minLength ?? PasswordValidator._DEFAULT_MIN_PASSWORD_LENGTH;
             if (password.length < minLength) {
                 failures.push({
                     property,
@@ -77,5 +87,59 @@ export class PasswordValidator {
             }
         }
     }
+    /**
+     * Validate the password against security policy.
+     * @param password The password to validate.
+     * @param options Options to configure the testing.
+     * @param options.minLength The minimum length of the password, defaults to 15.
+     * @param options.maxLength The minimum length of the password, defaults to 128.
+     * @param options.minPhraseLength The minimum length of the password for it to be considered a pass phrase.
+     * @throws Error if the password does not meet the requirements.
+     */
+    static validatePassword(password, options) {
+        Guards.stringValue(PasswordValidator.CLASS_NAME, "password", password);
+        const failures = [];
+        PasswordValidator.validate("password", password, failures, options);
+        Validation.asValidationError(PasswordValidator.CLASS_NAME, "password", failures);
+    }
+    /**
+     * Compare two password byte arrays in constant time to prevent timing attacks.
+     * @param hashedPasswordBytes The computed password bytes to compare.
+     * @param storedPasswordBytes The stored password bytes to compare against.
+     * @returns True if the bytes match, false otherwise.
+     */
+    static comparePasswordBytes(hashedPasswordBytes, storedPasswordBytes) {
+        Guards.uint8Array(PasswordValidator.CLASS_NAME, "hashedPasswordBytes", hashedPasswordBytes);
+        Guards.uint8Array(PasswordValidator.CLASS_NAME, "storedPasswordBytes", storedPasswordBytes);
+        // Return immediately if lengths differ
+        if (hashedPasswordBytes.length !== storedPasswordBytes.length) {
+            return false;
+        }
+        // Compare bytes in constant time
+        let result = 0;
+        for (let i = 0; i < hashedPasswordBytes.length; i++) {
+            // eslint-disable-next-line no-bitwise
+            result |= hashedPasswordBytes[i] ^ storedPasswordBytes[i];
+        }
+        return result === 0;
+    }
+    /**
+     * Compare two hashed passwords in constant time to prevent timing attacks.
+     * @param hashedPassword The computed hash to compare.
+     * @param storedPassword The stored hash to compare against.
+     * @returns True if the hashes match, false otherwise.
+     */
+    static comparePasswordHashes(hashedPassword, storedPassword) {
+        Guards.stringValue(PasswordValidator.CLASS_NAME, "hashedPassword", hashedPassword);
+        Guards.stringValue(PasswordValidator.CLASS_NAME, "storedPassword", storedPassword);
+        // Return immediately if lengths differ
+        if (hashedPassword.length !== storedPassword.length) {
+            return false;
+        }
+        // Decode base64 strings to bytes
+        const hashedBytes = Converter.base64ToBytes(hashedPassword);
+        const storedBytes = Converter.base64ToBytes(storedPassword);
+        return PasswordValidator.comparePasswordBytes(hashedBytes, storedBytes);
+    }
 }
 //# sourceMappingURL=passwordValidator.js.map

package/dist/es/passwords/passwordValidator.js.map

@@ -1 +1 @@
-{"version":3,"file":"passwordValidator.js","sourceRoot":"","sources":["../../../src/passwords/passwordValidator.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAA2B,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAErE;;;GAGG;AACH,MAAM,OAAO,iBAAiB;IAC7B;;;;;;;;;OASG;IACI,MAAM,CAAC,QAAQ,CACrB,QAAgB,EAChB,QAAgB,EAChB,QAA8B,EAC9B,OAIC;QAED,MAAM,QAAQ,GAAG,UAAU,CAAC,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAEtE,IAAI,QAAQ,EAAE,CAAC;YACd,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,CAAC,CAAC;YAC1C,IAAI,QAAQ,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;gBACjC,QAAQ,CAAC,IAAI,CAAC;oBACb,QAAQ;oBACR,MAAM,EAAE,8BAA8B;oBACtC,UAAU,EAAE;wBACX,SAAS;wBACT,YAAY,EAAE,QAAQ,CAAC,MAAM;qBAC7B;iBACD,CAAC,CAAC;YACJ,CAAC;YAED,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,GAAG,CAAC;YAC5C,IAAI,QAAQ,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;gBACjC,QAAQ,CAAC,IAAI,CAAC;oBACb,QAAQ;oBACR,MAAM,EAAE,8BAA8B;oBACtC,UAAU,EAAE;wBACX,SAAS;wBACT,YAAY,EAAE,QAAQ,CAAC,MAAM;qBAC7B;iBACD,CAAC,CAAC;YACJ,CAAC;YAED,IAAI,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAChC,QAAQ,CAAC,IAAI,CAAC;oBACb,QAAQ;oBACR,MAAM,EAAE,+BAA+B;iBACvC,CAAC,CAAC;YACJ,CAAC;YAED,0DAA0D;YAC1D,MAAM,eAAe,GAAG,OAAO,EAAE,eAAe,IAAI,EAAE,CAAC;YAEvD,IAAI,QAAQ,CAAC,MAAM,GAAG,eAAe,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC7B,QAAQ,CAAC,IAAI,CAAC;wBACb,QAAQ;wBACR,MAAM,EAAE,gCAAgC;qBACxC,CAAC,CAAC;gBACJ,CAAC;gBAED,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC7B,QAAQ,CAAC,IAAI,CAAC;wBACb,QAAQ;wBACR,MAAM,EAAE,gCAAgC;qBACxC,CAAC,CAAC;gBACJ,CAAC;gBAED,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC1B,QAAQ,CAAC,IAAI,CAAC;wBACb,QAAQ;wBACR,MAAM,EAAE,6BAA6B;qBACrC,CAAC,CAAC;gBACJ,CAAC;gBAED,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;oBACnC,QAAQ,CAAC,IAAI,CAAC;wBACb,QAAQ;wBACR,MAAM,EAAE,kCAAkC;qBAC1C,CAAC,CAAC;gBACJ,CAAC;YACF,CAAC;QACF,CAAC;IACF,CAAC;CACD","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { type IValidationFailure, Validation } from \"@twin.org/core\";\n\n/**\n * Test password strength.\n * Ref https://www.owasp.org/index.php/Authentication_Cheat_Sheet#Implement_Proper_Password_Strength_Controls .\n */\nexport class PasswordValidator {\n\t/**\n\t * Test the strength of the password.\n\t * @param property The name of the property.\n\t * @param password The password to test.\n\t * @param failures The list of failures to add to.\n\t * @param options Options to configure the testing.\n\t * @param options.minLength The minimum length of the password, defaults to 8.\n\t * @param options.maxLength The minimum length of the password, defaults to 128.\n\t * @param options.minPhraseLength The minimum length of the password for it to be considered a pass phrase.\n\t */\n\tpublic static validate(\n\t\tproperty: string,\n\t\tpassword: string,\n\t\tfailures: IValidationFailure[],\n\t\toptions?: {\n\t\t\tminLength?: number;\n\t\t\tmaxLength?: number;\n\t\t\tminPhraseLength?: number;\n\t\t}\n\t): void {\n\t\tconst isString = Validation.stringValue(property, password, failures);\n\n\t\tif (isString) {\n\t\t\tconst minLength = options?.minLength ?? 8;\n\t\t\tif (password.length < minLength) {\n\t\t\t\tfailures.push({\n\t\t\t\t\tproperty,\n\t\t\t\t\treason: \"validation.minLengthRequired\",\n\t\t\t\t\tproperties: {\n\t\t\t\t\t\tminLength,\n\t\t\t\t\t\tactualLength: password.length\n\t\t\t\t\t}\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst maxLength = options?.maxLength ?? 128;\n\t\t\tif (password.length > maxLength) {\n\t\t\t\tfailures.push({\n\t\t\t\t\tproperty,\n\t\t\t\t\treason: \"validation.maxLengthRequired\",\n\t\t\t\t\tproperties: {\n\t\t\t\t\t\tmaxLength,\n\t\t\t\t\t\tactualLength: password.length\n\t\t\t\t\t}\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tif (/(.)\\1{2,}/.test(password)) {\n\t\t\t\tfailures.push({\n\t\t\t\t\tproperty,\n\t\t\t\t\treason: \"validation.repeatedCharacters\"\n\t\t\t\t});\n\t\t\t}\n\n\t\t\t// If this looks like a phrase then apply additional rules\n\t\t\tconst minPhraseLength = options?.minPhraseLength ?? 20;\n\n\t\t\tif (password.length < minPhraseLength || !password.includes(\" \")) {\n\t\t\t\tif (!/[a-z]/.test(password)) {\n\t\t\t\t\tfailures.push({\n\t\t\t\t\t\tproperty,\n\t\t\t\t\t\treason: \"validation.atLeastOneLowerCase\"\n\t\t\t\t\t});\n\t\t\t\t}\n\n\t\t\t\tif (!/[A-Z]/.test(password)) {\n\t\t\t\t\tfailures.push({\n\t\t\t\t\t\tproperty,\n\t\t\t\t\t\treason: \"validation.atLeastOneUpperCase\"\n\t\t\t\t\t});\n\t\t\t\t}\n\n\t\t\t\tif (!/\\d/.test(password)) {\n\t\t\t\t\tfailures.push({\n\t\t\t\t\t\tproperty,\n\t\t\t\t\t\treason: \"validation.atLeastOneNumber\"\n\t\t\t\t\t});\n\t\t\t\t}\n\n\t\t\t\tif (!/[^\\dA-Za-z]/.test(password)) {\n\t\t\t\t\tfailures.push({\n\t\t\t\t\t\tproperty,\n\t\t\t\t\t\treason: \"validation.atLeastOneSpecialChar\"\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"passwordValidator.js","sourceRoot":"","sources":["../../../src/passwords/passwordValidator.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Converter, Guards, type IValidationFailure, Validation } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\n\n/**\n * Test password strength.\n * @see https://www.owasp.org/index.php/Authentication_Cheat_Sheet#Implement_Proper_Password_Strength_Controls .\n */\nexport class PasswordValidator {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<PasswordValidator>();\n\n\t/**\n\t * The minimum password length, 15 to match owasp rules.\n\t * @see https://www.owasp.org/index.php/Authentication_Cheat_Sheet#Implement_Proper_Password_Strength_Controls .\n\t * @internal\n\t */\n\tprivate static readonly _DEFAULT_MIN_PASSWORD_LENGTH: number = 15;\n\n\t/**\n\t * Test the strength of the password.\n\t * @param property The name of the property.\n\t * @param password The password to test.\n\t * @param failures The list of failures to add to.\n\t * @param options Options to configure the testing.\n\t * @param options.minLength The minimum length of the password, defaults to 15, can be 8 if MFA is enabled.\n\t * @param options.maxLength The minimum length of the password, defaults to 128.\n\t * @param options.minPhraseLength The minimum length of the password for it to be considered a pass phrase.\n\t */\n\tpublic static validate(\n\t\tproperty: string,\n\t\tpassword: string,\n\t\tfailures: IValidationFailure[],\n\t\toptions?: {\n\t\t\tminLength?: number;\n\t\t\tmaxLength?: number;\n\t\t\tminPhraseLength?: number;\n\t\t}\n\t): void {\n\t\tconst isString = Validation.stringValue(property, password, failures);\n\n\t\tif (isString) {\n\t\t\tconst minLength = options?.minLength ?? PasswordValidator._DEFAULT_MIN_PASSWORD_LENGTH;\n\t\t\tif (password.length < minLength) {\n\t\t\t\tfailures.push({\n\t\t\t\t\tproperty,\n\t\t\t\t\treason: \"validation.minLengthRequired\",\n\t\t\t\t\tproperties: {\n\t\t\t\t\t\tminLength,\n\t\t\t\t\t\tactualLength: password.length\n\t\t\t\t\t}\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst maxLength = options?.maxLength ?? 128;\n\t\t\tif (password.length > maxLength) {\n\t\t\t\tfailures.push({\n\t\t\t\t\tproperty,\n\t\t\t\t\treason: \"validation.maxLengthRequired\",\n\t\t\t\t\tproperties: {\n\t\t\t\t\t\tmaxLength,\n\t\t\t\t\t\tactualLength: password.length\n\t\t\t\t\t}\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tif (/(.)\\1{2,}/.test(password)) {\n\t\t\t\tfailures.push({\n\t\t\t\t\tproperty,\n\t\t\t\t\treason: \"validation.repeatedCharacters\"\n\t\t\t\t});\n\t\t\t}\n\n\t\t\t// If this looks like a phrase then apply additional rules\n\t\t\tconst minPhraseLength = options?.minPhraseLength ?? 20;\n\n\t\t\tif (password.length < minPhraseLength || !password.includes(\" \")) {\n\t\t\t\tif (!/[a-z]/.test(password)) {\n\t\t\t\t\tfailures.push({\n\t\t\t\t\t\tproperty,\n\t\t\t\t\t\treason: \"validation.atLeastOneLowerCase\"\n\t\t\t\t\t});\n\t\t\t\t}\n\n\t\t\t\tif (!/[A-Z]/.test(password)) {\n\t\t\t\t\tfailures.push({\n\t\t\t\t\t\tproperty,\n\t\t\t\t\t\treason: \"validation.atLeastOneUpperCase\"\n\t\t\t\t\t});\n\t\t\t\t}\n\n\t\t\t\tif (!/\\d/.test(password)) {\n\t\t\t\t\tfailures.push({\n\t\t\t\t\t\tproperty,\n\t\t\t\t\t\treason: \"validation.atLeastOneNumber\"\n\t\t\t\t\t});\n\t\t\t\t}\n\n\t\t\t\tif (!/[^\\dA-Za-z]/.test(password)) {\n\t\t\t\t\tfailures.push({\n\t\t\t\t\t\tproperty,\n\t\t\t\t\t\treason: \"validation.atLeastOneSpecialChar\"\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * Validate the password against security policy.\n\t * @param password The password to validate.\n\t * @param options Options to configure the testing.\n\t * @param options.minLength The minimum length of the password, defaults to 15.\n\t * @param options.maxLength The minimum length of the password, defaults to 128.\n\t * @param options.minPhraseLength The minimum length of the password for it to be considered a pass phrase.\n\t * @throws Error if the password does not meet the requirements.\n\t */\n\tpublic static validatePassword(\n\t\tpassword: string,\n\t\toptions?: {\n\t\t\tminLength?: number;\n\t\t\tmaxLength?: number;\n\t\t\tminPhraseLength?: number;\n\t\t}\n\t): void {\n\t\tGuards.stringValue(PasswordValidator.CLASS_NAME, nameof(password), password);\n\n\t\tconst failures: IValidationFailure[] = [];\n\n\t\tPasswordValidator.validate(nameof(password), password, failures, options);\n\n\t\tValidation.asValidationError(PasswordValidator.CLASS_NAME, nameof(password), failures);\n\t}\n\n\t/**\n\t * Compare two password byte arrays in constant time to prevent timing attacks.\n\t * @param hashedPasswordBytes The computed password bytes to compare.\n\t * @param storedPasswordBytes The stored password bytes to compare against.\n\t * @returns True if the bytes match, false otherwise.\n\t */\n\tpublic static comparePasswordBytes(\n\t\thashedPasswordBytes: Uint8Array,\n\t\tstoredPasswordBytes: Uint8Array\n\t): boolean {\n\t\tGuards.uint8Array(\n\t\t\tPasswordValidator.CLASS_NAME,\n\t\t\tnameof(hashedPasswordBytes),\n\t\t\thashedPasswordBytes\n\t\t);\n\t\tGuards.uint8Array(\n\t\t\tPasswordValidator.CLASS_NAME,\n\t\t\tnameof(storedPasswordBytes),\n\t\t\tstoredPasswordBytes\n\t\t);\n\n\t\t// Return immediately if lengths differ\n\t\tif (hashedPasswordBytes.length !== storedPasswordBytes.length) {\n\t\t\treturn false;\n\t\t}\n\n\t\t// Compare bytes in constant time\n\t\tlet result = 0;\n\t\tfor (let i = 0; i < hashedPasswordBytes.length; i++) {\n\t\t\t// eslint-disable-next-line no-bitwise\n\t\t\tresult |= hashedPasswordBytes[i] ^ storedPasswordBytes[i];\n\t\t}\n\n\t\treturn result === 0;\n\t}\n\n\t/**\n\t * Compare two hashed passwords in constant time to prevent timing attacks.\n\t * @param hashedPassword The computed hash to compare.\n\t * @param storedPassword The stored hash to compare against.\n\t * @returns True if the hashes match, false otherwise.\n\t */\n\tpublic static comparePasswordHashes(hashedPassword: string, storedPassword: string): boolean {\n\t\tGuards.stringValue(PasswordValidator.CLASS_NAME, nameof(hashedPassword), hashedPassword);\n\t\tGuards.stringValue(PasswordValidator.CLASS_NAME, nameof(storedPassword), storedPassword);\n\n\t\t// Return immediately if lengths differ\n\t\tif (hashedPassword.length !== storedPassword.length) {\n\t\t\treturn false;\n\t\t}\n\n\t\t// Decode base64 strings to bytes\n\t\tconst hashedBytes = Converter.base64ToBytes(hashedPassword);\n\t\tconst storedBytes = Converter.base64ToBytes(storedPassword);\n\n\t\treturn PasswordValidator.comparePasswordBytes(hashedBytes, storedBytes);\n\t}\n}\n"]}

package/dist/types/passwords/passwordGenerator.d.ts

@@ -2,10 +2,33 @@
  * Generate random passwords.
  */
 export declare class PasswordGenerator {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
     /**
      * Generate a password of given length.
-     * @param length The length of the password to generate.
+     * @param length The length of the password to generate, default to 15.
      * @returns The random password.
      */
-    static generate(length: number): string;
+    static generate(length?: number): string;
+    /**
+     * Hash the password for the user.
+     * @param passwordBytes The password bytes.
+     * @param saltBytes The salt bytes.
+     * @returns The hashed password.
+     */
+    static hashPassword(passwordBytes: Uint8Array, saltBytes: Uint8Array): Promise<string>;
+    /**
+     * Get a random character from the given character set.
+     * @param charSet The character set to get a random character from.
+     * @returns A random character from the given character set.
+     */
+    private static getRandomChar;
+    /**
+     * Push a random character from the given character set to the chars array, ensuring no three repeated characters in a row.
+     * @param chars The array to push the character to.
+     * @param charSet The character set to get a random character from.
+     */
+    private static pushChar;
 }

package/dist/types/passwords/passwordValidator.d.ts

@@ -1,16 +1,20 @@
 import { type IValidationFailure } from "@twin.org/core";
 /**
  * Test password strength.
- * Ref https://www.owasp.org/index.php/Authentication_Cheat_Sheet#Implement_Proper_Password_Strength_Controls .
+ * @see https://www.owasp.org/index.php/Authentication_Cheat_Sheet#Implement_Proper_Password_Strength_Controls .
  */
 export declare class PasswordValidator {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
     /**
      * Test the strength of the password.
      * @param property The name of the property.
      * @param password The password to test.
      * @param failures The list of failures to add to.
      * @param options Options to configure the testing.
-     * @param options.minLength The minimum length of the password, defaults to 8.
+     * @param options.minLength The minimum length of the password, defaults to 15, can be 8 if MFA is enabled.
      * @param options.maxLength The minimum length of the password, defaults to 128.
      * @param options.minPhraseLength The minimum length of the password for it to be considered a pass phrase.
      */
@@ -19,4 +23,32 @@ export declare class PasswordValidator {
         maxLength?: number;
         minPhraseLength?: number;
     }): void;
+    /**
+     * Validate the password against security policy.
+     * @param password The password to validate.
+     * @param options Options to configure the testing.
+     * @param options.minLength The minimum length of the password, defaults to 15.
+     * @param options.maxLength The minimum length of the password, defaults to 128.
+     * @param options.minPhraseLength The minimum length of the password for it to be considered a pass phrase.
+     * @throws Error if the password does not meet the requirements.
+     */
+    static validatePassword(password: string, options?: {
+        minLength?: number;
+        maxLength?: number;
+        minPhraseLength?: number;
+    }): void;
+    /**
+     * Compare two password byte arrays in constant time to prevent timing attacks.
+     * @param hashedPasswordBytes The computed password bytes to compare.
+     * @param storedPasswordBytes The stored password bytes to compare against.
+     * @returns True if the bytes match, false otherwise.
+     */
+    static comparePasswordBytes(hashedPasswordBytes: Uint8Array, storedPasswordBytes: Uint8Array): boolean;
+    /**
+     * Compare two hashed passwords in constant time to prevent timing attacks.
+     * @param hashedPassword The computed hash to compare.
+     * @param storedPassword The stored hash to compare against.
+     * @returns True if the hashes match, false otherwise.
+     */
+    static comparePasswordHashes(hashedPassword: string, storedPassword: string): boolean;
 }

package/docs/changelog.md

@@ -1,5 +1,43 @@
 # @twin.org/crypto - Changelog
 
+## [0.0.3-next.16](https://github.com/twinfoundation/framework/compare/crypto-v0.0.3-next.15...crypto-v0.0.3-next.16) (2026-02-06)
+
+
+### Features
+
+* improved password generation and validation ([#232](https://github.com/twinfoundation/framework/issues/232)) ([ca4e18f](https://github.com/twinfoundation/framework/commit/ca4e18f388b1882cdfb774fc0d0921b8530fac33))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.15 to 0.0.3-next.16
+    * @twin.org/nameof bumped from 0.0.3-next.15 to 0.0.3-next.16
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.15 to 0.0.3-next.16
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.15 to 0.0.3-next.16
+    * @twin.org/validate-locales bumped from 0.0.3-next.15 to 0.0.3-next.16
+
+## [0.0.3-next.15](https://github.com/twinfoundation/framework/compare/crypto-v0.0.3-next.14...crypto-v0.0.3-next.15) (2026-01-29)
+
+
+### Miscellaneous Chores
+
+* **crypto:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.14 to 0.0.3-next.15
+    * @twin.org/nameof bumped from 0.0.3-next.14 to 0.0.3-next.15
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.14 to 0.0.3-next.15
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.14 to 0.0.3-next.15
+    * @twin.org/validate-locales bumped from 0.0.3-next.14 to 0.0.3-next.15
+
 ## [0.0.3-next.14](https://github.com/twinfoundation/framework/compare/crypto-v0.0.3-next.13...crypto-v0.0.3-next.14) (2026-01-22)
 
 

package/docs/reference/classes/PasswordGenerator.md

@@ -12,6 +12,14 @@ Generate random passwords.
 
 `PasswordGenerator`
 
+## Properties
+
+### CLASS\_NAME
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
 ## Methods
 
 ### generate()
@@ -24,12 +32,40 @@ Generate a password of given length.
 
 ##### length
 
-`number`
+`number` = `PasswordGenerator._DEFAULT_MIN_PASSWORD_LENGTH`
 
-The length of the password to generate.
+The length of the password to generate, default to 15.
 
 #### Returns
 
 `string`
 
 The random password.
+
+***
+
+### hashPassword()
+
+> `static` **hashPassword**(`passwordBytes`, `saltBytes`): `Promise`\<`string`\>
+
+Hash the password for the user.
+
+#### Parameters
+
+##### passwordBytes
+
+`Uint8Array`
+
+The password bytes.
+
+##### saltBytes
+
+`Uint8Array`
+
+The salt bytes.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The hashed password.

package/docs/reference/classes/PasswordValidator.md

@@ -1,7 +1,10 @@
 # Class: PasswordValidator
 
 Test password strength.
-Ref https://www.owasp.org/index.php/Authentication_Cheat_Sheet#Implement_Proper_Password_Strength_Controls .
+
+## See
+
+https://www.owasp.org/index.php/Authentication_Cheat_Sheet#Implement_Proper_Password_Strength_Controls .
 
 ## Constructors
 
@@ -13,6 +16,14 @@ Ref https://www.owasp.org/index.php/Authentication_Cheat_Sheet#Implement_Proper_
 
 `PasswordValidator`
 
+## Properties
+
+### CLASS\_NAME
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
 ## Methods
 
 ### validate()
@@ -49,7 +60,49 @@ Options to configure the testing.
 
 `number`
 
-The minimum length of the password, defaults to 8.
+The minimum length of the password, defaults to 15, can be 8 if MFA is enabled.
+
+###### maxLength?
+
+`number`
+
+The minimum length of the password, defaults to 128.
+
+###### minPhraseLength?
+
+`number`
+
+The minimum length of the password for it to be considered a pass phrase.
+
+#### Returns
+
+`void`
+
+***
+
+### validatePassword()
+
+> `static` **validatePassword**(`password`, `options?`): `void`
+
+Validate the password against security policy.
+
+#### Parameters
+
+##### password
+
+`string`
+
+The password to validate.
+
+##### options?
+
+Options to configure the testing.
+
+###### minLength?
+
+`number`
+
+The minimum length of the password, defaults to 15.
 
 ###### maxLength?
 
@@ -66,3 +119,63 @@ The minimum length of the password for it to be considered a pass phrase.
 #### Returns
 
 `void`
+
+#### Throws
+
+Error if the password does not meet the requirements.
+
+***
+
+### comparePasswordBytes()
+
+> `static` **comparePasswordBytes**(`hashedPasswordBytes`, `storedPasswordBytes`): `boolean`
+
+Compare two password byte arrays in constant time to prevent timing attacks.
+
+#### Parameters
+
+##### hashedPasswordBytes
+
+`Uint8Array`
+
+The computed password bytes to compare.
+
+##### storedPasswordBytes
+
+`Uint8Array`
+
+The stored password bytes to compare against.
+
+#### Returns
+
+`boolean`
+
+True if the bytes match, false otherwise.
+
+***
+
+### comparePasswordHashes()
+
+> `static` **comparePasswordHashes**(`hashedPassword`, `storedPassword`): `boolean`
+
+Compare two hashed passwords in constant time to prevent timing attacks.
+
+#### Parameters
+
+##### hashedPassword
+
+`string`
+
+The computed hash to compare.
+
+##### storedPassword
+
+`string`
+
+The stored hash to compare against.
+
+#### Returns
+
+`boolean`
+
+True if the hashes match, false otherwise.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/crypto",
-	"version": "0.0.3-next.14",
+	"version": "0.0.3-next.16",
 	"description": "Contains helper methods and classes which implement cryptographic functions",
 	"repository": {
 		"type": "git",
@@ -20,8 +20,8 @@
 		"@scure/base": "2.0.0",
 		"@scure/bip32": "2.0.1",
 		"@scure/bip39": "2.0.1",
-		"@twin.org/core": "0.0.3-next.14",
-		"@twin.org/nameof": "0.0.3-next.14",
+		"@twin.org/core": "0.0.3-next.16",
+		"@twin.org/nameof": "0.0.3-next.16",
 		"crypto-browserify": "3.12.1",
 		"micro-key-producer": "0.8.2"
 	},