Password Validator

A lightweight JavaScript library for validating passwords against common security rules.
The validator checks string type, length, character requirements, blacklist, and more.

Student project disclaimer

This is a project made entirely by me, Alex Palm, for the university course 1DV610 at Linneuniversitetet. This is a disclaimer because of that fact. If you were to use this library, use it with caution. However feel free to let me know if there are improvements to be made through the available communication channels here.

Table of Contents

• Install
• Usage
• API
• Rules
• Testing
• Roadmap
• License

Install

npm install password-validator-ap

Usage/code examples

Basic usage (no config file):

import PasswordValidator from "password-validator-ap";

const validator = new PasswordValidator(); 
validator.setMinLength(6) // Set the minimum length of the password
validator.setMaxLength(80) // Set the maximum length of the password

try {
	validator.validate("MyPassword123!", "myusername");
	console.log("Password is valid!");
} catch (err) {
	console.error("Validation error:", err.message);
}

Usage with config file (async):

import PasswordValidator from "password-validator-ap";

(async () => {
	const validator = await PasswordValidator.loadConfig(); // Loads the config file if present
	try {
		validator.validate("MyPassword123!", "myusername"); // Send arguments for validation
		console.log("Password is valid!");
	} catch (err) {
		console.error("Validation error:", err.message);
	}
})();

Checking min/max range and blacklist:

console.log("Min length:", validator.getMinLength()); // get set minimum length for valid password
console.log("Max length:", validator.getMaxLength()); // get set maximum length for valid password
console.log("Blacklist:", validator.getBlacklist()); // get list of blacklisted passwords

Example of config file

<password-validator.config.js>

export default {
  minLength: 66,
  maxLength: 99,
  blacklist: ["password", "admin", "abc123"], // Add strings to be blacklisted or import array with strings
};

API

Constructor

new PasswordValidator(config = {})

Creates a new instance.

• config (object, optional): Configuration object. Supports minLength, maxLength, and blacklist.

static async loadConfig() Loads configuration from password-validator.config.js and returns a PasswordValidator instance.

• Returns: Promise<PasswordValidator>

validate(password, username) Validates a password against all rules.

• password (string): The password to validate.
• username (string): The username to compare against.
• Returns: boolean (true if valid)
• Throws: Error, TypeError, or RangeError if validation fails.

setMinLength(min) Sets the minimum password length.

• min (number): Minimum length.

setMaxLength(max) Sets the maximum password length.

• max (number): Maximum length.

getMinLength() Returns the current minimum password length.

• Returns: number

getMaxLength() Returns the current maximum password length.

• Returns: number

getBlacklist() Returns the current blacklist of disallowed passwords.

• Returns: string[]

Validation Methods (Advanced Usage) You can use these methods directly for custom validation flows:

• validateString(str) — Throws if not a string.
• validateLength(str, minLength, maxLength) — Throws if length is invalid.
• containsUppercase(str) — Throws if no uppercase letter.
• containsLowercase(str) — Throws if no lowercase letter.
• containsDigit(str) — Throws if no digit.
• containsSpecialChar(str) — Throws if no special character.
• doesNotContainWhitespace(str) — Throws if whitespace is present.
• containsSameCharacter(str) — Throws if all characters are the same.
• passwordEqualToUsername(password, username) — Throws if password equals username.
• passwordIsBlacklisted(str) — Throws if password is blacklisted.

Rules in validator

| Rule | Description | |------------------------|-----------------------------------------------------------------------------| | String type | Password must be a string value. Throws an error if not a string. | | Length check | Password length must be between 6 and 80 characters. | | Uppercase requirement | Password must contain at least one uppercase letter (A–Z). | | Lowercase requirement | Password must contain at least one lowercase letter (a–z). | | Digit requirement | Password must contain at least one digit (0–9). | | Special character | Password must contain at least one special character (e.g. !@#$%^&*). | | Whitespace restriction | Password must not contain whitespace (spaces, tabs, newlines). | | Unique characters | Password must not consist of just a single repeated character. | | Not equal to username | Password must not be the same as the provided username. | | Blacklist restriction | Password must not appear in the configured blacklist of common passwords.|

Bugs/feedback

• List off known bugs to be aware off * To send feedback on this library, such as constructive feedback and points of improvement, create a issue on the Github page:

Testing/coverage

Automatic testing is done with the Jest framework. As off version 1.0.2 the application has 60-70% coverage.

Roadmap

• Allow custom validation rules
• Support multiple errors at once instead of failing on the first
• Add configuration options (e.g., set custom min/max length)

License

MIT License. See for details