ypreiser
NIST Password Validator Library
A lightweight, zero-dependency open-source password validator adhering to NIST guidelines.
Try it out: Test the library with a user-friendly front-end demo site.
Introduction
This library provides a robust solution for password validation based on the NIST Digital Identity Guidelines (SP 800-63B). It promotes modern password security with support for Unicode, breach checks, customizable rules, and advanced features like error limits for flexible feedback.
Why NIST Guidelines?
Passwords are a cornerstone of digital security. The National Institute of Standards and Technology (NIST) has established guidelines to improve password policies with principles like:
- Minimum Length: At least 8 characters; 15+ recommended.
- Maximum Length: Support up to 64+ characters.
- No Arbitrary Composition Rules: Avoid forcing special characters or case mixing.
- Unicode Support: Inclusive acceptance of all Unicode characters.
- Compromised Password Checks: Block passwords found in breaches.
- Blocklist with Fuzzy Matching: Prevent predictable or context-specific terms.
This library implements these principles to enhance security and usability.
Features
- NIST-Compliant Validation:
- Unicode-based minimum/maximum length checks.
- Smart whitespace handling.
- Error Limiting:
- Control the number of errors returned for a password.
- Balance detailed feedback and performance.
- HIBP Integration:
- Check passwords against the Have I Been Pwned (HIBP) breach database.
- Blocklist with Fuzzy Matching:
- Detect passwords similar to blocklisted terms.
- Customizable sensitivity and matching rules.
- Flexible Configuration:
- Adjustable length limits, blocklists, and sensitivity.
- Toggle HIBP checks for local environments.
Installation
Install via npm:
npm install nist-password-validatorUsage
Basic Example
import { validatePassword } from "nist-password-validator";
async function checkPassword() {
const result = await validatePassword("examplepassword");
if (!result.isValid) {
console.log("Password validation failed:", result.errors);
} else {
console.log("Password is valid!");
}
}
checkPassword();Using the PasswordValidator Class
For scenarios where you need to reuse the same validation configuration or update it dynamically:
import { PasswordValidator } from "nist-password-validator";
// Create a validator with initial options
const validator = new PasswordValidator({
minLength: 8,
maxLength: 64,
blocklist: ["password", "admin"],
});
// Validate a password
async function validateWithClass() {
const result = await validator.validate("mypassword123");
console.log(result.isValid ? "Valid!" : "Invalid:", result.errors);
}
// Update configuration as needed
validator.updateConfig({
minLength: 12, // This will merge with existing config
errorLimit: 2,
});
// Validate again with new config
validateWithClass();The PasswordValidator class provides several benefits:
- Reusable Configuration: Create a validator instance with your preferred settings
- Dynamic Updates: Change validation rules on the fly with
updateConfig - Consistent Validation: Ensure the same rules are applied across multiple password checks
- Memory Efficient: Reuse the same validator instance instead of creating new configurations
Methods:
constructor(options?: ValidationOptions): Create a new validator with optional initial optionsvalidate(password: string): Promise<ValidationResult>: Validate a password using current configurationupdateConfig(options: ValidationOptions): void: Update the current configuration by merging new options
Custom Configuration
async function checkCustomPassword() {
const result = await validatePassword("myp@ssw0rd!", {
minLength: 10, // Custom minimum length (default: 15)
maxLength: 500000, // Custom maximum length (default: 100K)
hibpCheck: false, // Disable HIBP check if using local hash database
blocklist: ["password"], // Custom blocklist
matchingSensitivity: 0.2, // Custom matching sensitivity (default: 0.25)
trimWhitespace: true, // Handle leading/trailing whitespace (default: true)
errorLimit: 3, // Amount of errors to check before stopping (defult: infinty)
});
if (!result.isValid) {
console.log("Password validation failed:", result.errors);
} else {
console.log("Password is valid!");
}
}
checkCustomPassword();Error Limit Feature
The errorLimit option allows users to control how many errors are returned during validation. This helps balance:
- Performance: Avoid unnecessary checks after reaching the limit.
- Feedback: Provide detailed insights without overwhelming users.
Example Usage
const result = await validatePassword("mypassword", {
errorLimit: 2, // Report up to 2 errors
});
console.log(result.errors); // Returns a maximum of 2 errors- Default: Unlimited errors (
errorLimitdefaults toInfinity). - Customizable: Adjust based on user needs or environment constraints.
Validators
1. Length Validation
Ensures the password meets specified length requirements based on Unicode code points.
import { lengthValidator } from "nist-password-validator";
const result = lengthValidator("mypassword", 8, 64);
console.log(result.errors);2. Blocklist Validation
Prevents passwords that resemble blocked terms using fuzzy matching.
import { blocklistValidator } from "nist-password-validator";
const result = blocklistValidator("myp@ssword", ["password"], {
matchingSensitivity: 0.25,
});
console.log(result.errors);3. HIBP Validation
Checks passwords against the Have I Been Pwned breach database.
import { hibpValidator } from "nist-password-validator";
hibpValidator("mypassword123").then((result) => console.log(result.errors));Whitespace Handling
Handles leading/trailing whitespace in passwords for NIST compliance. Enabled by default.
// Default: Trims whitespace
const result1 = await validatePassword(" mypassword ");
// Disable trimming
const result2 = await validatePassword(" mypassword ", {
trimWhitespace: false,
});Security Considerations
- Normalize passwords to UTF-8 before hashing.
- Use local hash databases for HIBP checks in high-security environments.
- Customize blocklists with sensitive or organization-specific terms.
- Implement rate limiting for external API calls.
Publishing
This package uses automated npm publishing via GitHub Actions. To publish a new version:
- Update version:
npm version patch|minor|major(this updates package.json and creates a git tag) - Push with tags:
git push origin master --tags - The GitHub Action will automatically:
- Run tests and linting
- Build the package
- Publish to npm with provenance
First-time Setup
To enable automated publishing, add your npm token to GitHub:
- Generate an npm access token:
- Go to npmjs.com
- Account Settings → Access Tokens → Generate New Token
- Select "Automation" type (for CI/CD)
- Add token to GitHub:
- Go to your repository → Settings → Secrets and variables → Actions
- Click "New repository secret"
- Name:
NPM_TOKEN - Value: (paste your npm token)
Contributing
We welcome contributions! Fork the repo, create a branch, and submit a pull request.
License
This library is released under the MIT License.