@twin.org/crypto 0.0.3-next.2 → 0.0.3-next.22

package/dist/es/helpers/integrityHelper.js

@@ -0,0 +1,67 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Converter, Guards } from "@twin.org/core";
+import { Sha256 } from "../hashes/sha256.js";
+import { Sha512 } from "../hashes/sha512.js";
+import { IntegrityAlgorithm } from "../models/integrityAlgorithm.js";
+/**
+ * Helper class for creating integrity signatures.
+ * @see https://www.w3.org/TR/SRI/
+ */
+export class IntegrityHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "IntegrityHelper";
+    /**
+     * Generate an integrity signature for the given content using the specified hash algorithm.
+     * @param type The hash algorithm to use, either "sha256", "sha384" or "sha512".
+     * @param content The content to hash as a Uint8Array.
+     * @returns The integrity signature in the format "type-base64hash".
+     */
+    static generate(type, content) {
+        Guards.arrayOneOf(IntegrityHelper.CLASS_NAME, "type", type, Object.values(IntegrityAlgorithm));
+        Guards.uint8Array(IntegrityHelper.CLASS_NAME, "content", content);
+        return `${type}-${IntegrityHelper.generateHash(type, content)}`;
+    }
+    /**
+     * Verify an integrity signature for the given content.
+     * @param integrity The integrity signature in the format "type-base64hash".
+     * @param content The content to hash as a Uint8Array.
+     * @returns True if the integrity signature matches the content.
+     * @throws If the integrity signature is invalid.
+     */
+    static verify(integrity, content) {
+        Guards.stringValue(IntegrityHelper.CLASS_NAME, "integrity", integrity);
+        Guards.uint8Array(IntegrityHelper.CLASS_NAME, "content", content);
+        const parts = integrity.split("-");
+        if (parts.length !== 2) {
+            return false;
+        }
+        const [type, hash] = parts;
+        Guards.arrayOneOf(IntegrityHelper.CLASS_NAME, "type", type, Object.values(IntegrityAlgorithm));
+        Guards.stringValue(IntegrityHelper.CLASS_NAME, "hash", hash);
+        return IntegrityHelper.generateHash(type, content) === hash;
+    }
+    /**
+     * Generate a hash for the given content using the specified type.
+     * @param type The hash algorithm to use, either "sha256", "sha384" or "sha512".
+     * @param content The content to hash as a Uint8Array.
+     * @returns The integrity signature in the format "type-base64hash".
+     * @internal
+     */
+    static generateHash(type, content) {
+        let hash;
+        if (type === IntegrityAlgorithm.Sha384) {
+            hash = Sha512.sum384(content);
+        }
+        else if (type === IntegrityAlgorithm.Sha512) {
+            hash = Sha512.sum512(content);
+        }
+        else {
+            hash = Sha256.sum256(content);
+        }
+        return Converter.bytesToBase64(hash);
+    }
+}
+//# sourceMappingURL=integrityHelper.js.map

package/dist/es/helpers/integrityHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrityHelper.js","sourceRoot":"","sources":["../../../src/helpers/integrityHelper.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAErE;;;GAGG;AACH,MAAM,OAAO,eAAe;IAC3B;;OAEG;IACI,MAAM,CAAU,UAAU,qBAAqC;IAEtE;;;;;OAKG;IACI,MAAM,CAAC,QAAQ,CAAC,IAAwB,EAAE,OAAmB;QACnE,MAAM,CAAC,UAAU,CAChB,eAAe,CAAC,UAAU,UAE1B,IAAI,EACJ,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CACjC,CAAC;QACF,MAAM,CAAC,UAAU,CAAC,eAAe,CAAC,UAAU,aAAmB,OAAO,CAAC,CAAC;QAExE,OAAO,GAAG,IAAI,IAAI,eAAe,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;IACjE,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,MAAM,CAAC,SAAiB,EAAE,OAAmB;QAC1D,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,UAAU,eAAqB,SAAS,CAAC,CAAC;QAC7E,MAAM,CAAC,UAAU,CAAC,eAAe,CAAC,UAAU,aAAmB,OAAO,CAAC,CAAC;QAExE,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,KAAK,CAAC;QACd,CAAC;QAED,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,KAAK,CAAC;QAE3B,MAAM,CAAC,UAAU,CAChB,eAAe,CAAC,UAAU,UAE1B,IAA0B,EAC1B,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CACjC,CAAC;QACF,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,UAAU,UAAgB,IAAI,CAAC,CAAC;QAEnE,OAAO,eAAe,CAAC,YAAY,CAAC,IAA0B,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACnF,CAAC;IAED;;;;;;OAMG;IACK,MAAM,CAAC,YAAY,CAAC,IAAwB,EAAE,OAAmB;QACxE,IAAI,IAAI,CAAC;QACT,IAAI,IAAI,KAAK,kBAAkB,CAAC,MAAM,EAAE,CAAC;YACxC,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC;aAAM,IAAI,IAAI,KAAK,kBAAkB,CAAC,MAAM,EAAE,CAAC;YAC/C,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC;aAAM,CAAC;YACP,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,SAAS,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Converter, Guards } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { Sha256 } from \"../hashes/sha256.js\";\nimport { Sha512 } from \"../hashes/sha512.js\";\nimport { IntegrityAlgorithm } from \"../models/integrityAlgorithm.js\";\n\n/**\n * Helper class for creating integrity signatures.\n * @see https://www.w3.org/TR/SRI/\n */\nexport class IntegrityHelper {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<IntegrityHelper>();\n\n\t/**\n\t * Generate an integrity signature for the given content using the specified hash algorithm.\n\t * @param type The hash algorithm to use, either \"sha256\", \"sha384\" or \"sha512\".\n\t * @param content The content to hash as a Uint8Array.\n\t * @returns The integrity signature in the format \"type-base64hash\".\n\t */\n\tpublic static generate(type: IntegrityAlgorithm, content: Uint8Array): string {\n\t\tGuards.arrayOneOf(\n\t\t\tIntegrityHelper.CLASS_NAME,\n\t\t\tnameof(type),\n\t\t\ttype,\n\t\t\tObject.values(IntegrityAlgorithm)\n\t\t);\n\t\tGuards.uint8Array(IntegrityHelper.CLASS_NAME, nameof(content), content);\n\n\t\treturn `${type}-${IntegrityHelper.generateHash(type, content)}`;\n\t}\n\n\t/**\n\t * Verify an integrity signature for the given content.\n\t * @param integrity The integrity signature in the format \"type-base64hash\".\n\t * @param content The content to hash as a Uint8Array.\n\t * @returns True if the integrity signature matches the content.\n\t * @throws If the integrity signature is invalid.\n\t */\n\tpublic static verify(integrity: string, content: Uint8Array): boolean {\n\t\tGuards.stringValue(IntegrityHelper.CLASS_NAME, nameof(integrity), integrity);\n\t\tGuards.uint8Array(IntegrityHelper.CLASS_NAME, nameof(content), content);\n\n\t\tconst parts = integrity.split(\"-\");\n\t\tif (parts.length !== 2) {\n\t\t\treturn false;\n\t\t}\n\n\t\tconst [type, hash] = parts;\n\n\t\tGuards.arrayOneOf(\n\t\t\tIntegrityHelper.CLASS_NAME,\n\t\t\tnameof(type),\n\t\t\ttype as IntegrityAlgorithm,\n\t\t\tObject.values(IntegrityAlgorithm)\n\t\t);\n\t\tGuards.stringValue(IntegrityHelper.CLASS_NAME, nameof(hash), hash);\n\n\t\treturn IntegrityHelper.generateHash(type as IntegrityAlgorithm, content) === hash;\n\t}\n\n\t/**\n\t * Generate a hash for the given content using the specified type.\n\t * @param type The hash algorithm to use, either \"sha256\", \"sha384\" or \"sha512\".\n\t * @param content The content to hash as a Uint8Array.\n\t * @returns The integrity signature in the format \"type-base64hash\".\n\t * @internal\n\t */\n\tprivate static generateHash(type: IntegrityAlgorithm, content: Uint8Array): string {\n\t\tlet hash;\n\t\tif (type === IntegrityAlgorithm.Sha384) {\n\t\t\thash = Sha512.sum384(content);\n\t\t} else if (type === IntegrityAlgorithm.Sha512) {\n\t\t\thash = Sha512.sum512(content);\n\t\t} else {\n\t\t\thash = Sha256.sum256(content);\n\t\t}\n\t\treturn Converter.bytesToBase64(hash);\n\t}\n}\n"]}

package/dist/es/index.js

@@ -17,10 +17,12 @@ export * from "./hashes/sha1.js";
 export * from "./hashes/sha256.js";
 export * from "./hashes/sha3.js";
 export * from "./hashes/sha512.js";
+export * from "./helpers/integrityHelper.js";
 export * from "./helpers/pemHelper.js";
 export * from "./keys/bip32Path.js";
 export * from "./keys/bip39.js";
 export * from "./keys/slip0010.js";
+export * from "./models/integrityAlgorithm.js";
 export * from "./models/keyType.js";
 export * from "./otp/hotp.js";
 export * from "./otp/totp.js";

package/dist/es/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./address/bech32.js\";\nexport * from \"./address/bip44.js\";\nexport * from \"./ciphers/chaCha20Poly1305.js\";\nexport * from \"./curves/ed25519.js\";\nexport * from \"./curves/secp256k1.js\";\nexport * from \"./curves/x25519.js\";\nexport * from \"./curves/zip215.js\";\nexport * from \"./hashes/blake2b.js\";\nexport * from \"./hashes/blake3.js\";\nexport * from \"./hashes/hmacSha1.js\";\nexport * from \"./hashes/hmacSha256.js\";\nexport * from \"./hashes/hmacSha512.js\";\nexport * from \"./hashes/pbkdf2.js\";\nexport * from \"./hashes/sha1.js\";\nexport * from \"./hashes/sha256.js\";\nexport * from \"./hashes/sha3.js\";\nexport * from \"./hashes/sha512.js\";\nexport * from \"./helpers/pemHelper.js\";\nexport * from \"./keys/bip32Path.js\";\nexport * from \"./keys/bip39.js\";\nexport * from \"./keys/slip0010.js\";\nexport * from \"./models/keyType.js\";\nexport * from \"./otp/hotp.js\";\nexport * from \"./otp/totp.js\";\nexport * from \"./passwords/passwordGenerator.js\";\nexport * from \"./passwords/passwordValidator.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./address/bech32.js\";\nexport * from \"./address/bip44.js\";\nexport * from \"./ciphers/chaCha20Poly1305.js\";\nexport * from \"./curves/ed25519.js\";\nexport * from \"./curves/secp256k1.js\";\nexport * from \"./curves/x25519.js\";\nexport * from \"./curves/zip215.js\";\nexport * from \"./hashes/blake2b.js\";\nexport * from \"./hashes/blake3.js\";\nexport * from \"./hashes/hmacSha1.js\";\nexport * from \"./hashes/hmacSha256.js\";\nexport * from \"./hashes/hmacSha512.js\";\nexport * from \"./hashes/pbkdf2.js\";\nexport * from \"./hashes/sha1.js\";\nexport * from \"./hashes/sha256.js\";\nexport * from \"./hashes/sha3.js\";\nexport * from \"./hashes/sha512.js\";\nexport * from \"./helpers/integrityHelper.js\";\nexport * from \"./helpers/pemHelper.js\";\nexport * from \"./keys/bip32Path.js\";\nexport * from \"./keys/bip39.js\";\nexport * from \"./keys/slip0010.js\";\nexport * from \"./models/integrityAlgorithm.js\";\nexport * from \"./models/keyType.js\";\nexport * from \"./otp/hotp.js\";\nexport * from \"./otp/totp.js\";\nexport * from \"./passwords/passwordGenerator.js\";\nexport * from \"./passwords/passwordValidator.js\";\n"]}

package/dist/es/models/integrityAlgorithm.js

@@ -0,0 +1,21 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The names of the integrity algorithms.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const IntegrityAlgorithm = {
+    /**
+     * Sha256.
+     */
+    Sha256: "sha256",
+    /**
+     * Sha384.
+     */
+    Sha384: "sha384",
+    /**
+     * Sha512.
+     */
+    Sha512: "sha512"
+};
+//# sourceMappingURL=integrityAlgorithm.js.map

package/dist/es/models/integrityAlgorithm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrityAlgorithm.js","sourceRoot":"","sources":["../../../src/models/integrityAlgorithm.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,kBAAkB,GAAG;IACjC;;OAEG;IACH,MAAM,EAAE,QAAQ;IAEhB;;OAEG;IACH,MAAM,EAAE,QAAQ;IAEhB;;OAEG;IACH,MAAM,EAAE,QAAQ;CACP,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * The names of the integrity algorithms.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const IntegrityAlgorithm = {\n\t/**\n\t * Sha256.\n\t */\n\tSha256: \"sha256\",\n\n\t/**\n\t * Sha384.\n\t */\n\tSha384: \"sha384\",\n\n\t/**\n\t * Sha512.\n\t */\n\tSha512: \"sha512\"\n} as const;\n\n/**\n * Integrity algorithms.\n */\nexport type IntegrityAlgorithm = (typeof IntegrityAlgorithm)[keyof typeof IntegrityAlgorithm];\n"]}

package/dist/es/passwords/passwordGenerator.js

@@ -1,28 +1,86 @@
 // 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.
+     * @internal
+     */
+    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.
+     * @internal
+     */
+    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 * @internal\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 * @internal\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/helpers/integrityHelper.d.ts

@@ -0,0 +1,26 @@
+import { IntegrityAlgorithm } from "../models/integrityAlgorithm.js";
+/**
+ * Helper class for creating integrity signatures.
+ * @see https://www.w3.org/TR/SRI/
+ */
+export declare class IntegrityHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Generate an integrity signature for the given content using the specified hash algorithm.
+     * @param type The hash algorithm to use, either "sha256", "sha384" or "sha512".
+     * @param content The content to hash as a Uint8Array.
+     * @returns The integrity signature in the format "type-base64hash".
+     */
+    static generate(type: IntegrityAlgorithm, content: Uint8Array): string;
+    /**
+     * Verify an integrity signature for the given content.
+     * @param integrity The integrity signature in the format "type-base64hash".
+     * @param content The content to hash as a Uint8Array.
+     * @returns True if the integrity signature matches the content.
+     * @throws If the integrity signature is invalid.
+     */
+    static verify(integrity: string, content: Uint8Array): boolean;
+}

package/dist/types/index.d.ts

@@ -15,10 +15,12 @@ export * from "./hashes/sha1.js";
 export * from "./hashes/sha256.js";
 export * from "./hashes/sha3.js";
 export * from "./hashes/sha512.js";
+export * from "./helpers/integrityHelper.js";
 export * from "./helpers/pemHelper.js";
 export * from "./keys/bip32Path.js";
 export * from "./keys/bip39.js";
 export * from "./keys/slip0010.js";
+export * from "./models/integrityAlgorithm.js";
 export * from "./models/keyType.js";
 export * from "./otp/hotp.js";
 export * from "./otp/totp.js";

package/dist/types/models/integrityAlgorithm.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The names of the integrity algorithms.
+ */
+export declare const IntegrityAlgorithm: {
+    /**
+     * Sha256.
+     */
+    readonly Sha256: "sha256";
+    /**
+     * Sha384.
+     */
+    readonly Sha384: "sha384";
+    /**
+     * Sha512.
+     */
+    readonly Sha512: "sha512";
+};
+/**
+ * Integrity algorithms.
+ */
+export type IntegrityAlgorithm = (typeof IntegrityAlgorithm)[keyof typeof IntegrityAlgorithm];

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

@@ -2,10 +2,21 @@
  * 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>;
 }

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;
 }