Skip to content

Commit 649844c

Browse files
rzhkjrrzhkjr
committed
feat: Initial release
0 parents  commit 649844c

19 files changed

+10853
-0
lines changed

‎.github/workflows/release.yml

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Release
2+
permissions:
3+
contents: write
4+
on:
5+
push:
6+
branches:
7+
- master
8+
9+
jobs:
10+
release:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- name: Checkout code
15+
uses: actions/checkout@v3
16+
17+
- name: Set up Node.js
18+
uses: actions/setup-node@v3
19+
with:
20+
node-version: ">=20.8.1"
21+
cache: "npm"
22+
23+
- name: Install dependencies
24+
run: npm ci
25+
26+
- name: Run tests
27+
run: npm run test
28+
29+
- name: Build
30+
run: npm run build
31+
32+
- name: Run semantic-release
33+
env:
34+
GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
35+
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
36+
run: npx semantic-release

‎.gitignore

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
pnpm-debug.log*
8+
lerna-debug.log*
9+
10+
node_modules
11+
dist-ssr
12+
*.local
13+
14+
15+
.vscode/*
16+
!.vscode/extensions.json
17+
.idea
18+
.DS_Store
19+
*.suo
20+
*.ntvs*
21+
*.njsproj
22+
*.sln
23+
*.sw?

‎.npmignore

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
node_modules
2+
.env
3+
*.env
4+
*.local
5+
test
6+
tests
7+
__tests__
8+
coverage
9+
docs
10+
example
11+
examples
12+
*.log
13+
*.tsbuildinfo
14+
*.swp
15+
*.swo
16+
*.idea
17+
*.vscode
18+
.DS_Store
19+
npm-debug.log*
20+
src/**/*.ts
21+
src/**/*.tsx
22+
.git
23+
.github
24+
.gitignore
25+
.gitlab-ci.yml

‎.releaserc

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"branches": ["master"],
3+
"plugins": [
4+
"@semantic-release/commit-analyzer",
5+
"@semantic-release/release-notes-generator",
6+
"@semantic-release/changelog",
7+
"@semantic-release/npm",
8+
"@semantic-release/github",
9+
"@semantic-release/git"
10+
]
11+
}

‎README.md

+200
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# pwd-strength-validator
2+
`pwd-strength-validator` is a utility for evaluating the strength of passwords. It provides a customizable and easy-to-use way to validate password strength, calculate entropy, and assign scores based on predefined rules. This tool can be used independently of any frameworks or libraries, making it versatile for various applications.
3+
4+
The validator is based on **entropy calculations** and **predefined regular expression rules**. These features ensure that password strength is assessed rigorously according to established security criteria.
5+
6+
- [Demo](#demo)
7+
- [Features](#features)
8+
- [Installation](#installation)
9+
- [Configuration Options](#configuration-options)
10+
- [Usage](#usage)
11+
- [Basic Usage](#basic-usage)
12+
- [Example of Customized Usage](#example-of-customized-usage)
13+
- [API](#api)
14+
- [`validatePasswordStrength`](#validatepasswordstrengthpassword-string-params-ivalidatepasswordstrengthoptions-ivalidatepasswordstrengthresponse)
15+
- [License](#license)
16+
- [Contributing](#contributing)
17+
18+
19+
## Features
20+
21+
- **Entropy Calculation:** Compute the entropy of the password to gauge its strength.
22+
- **Score Calculation:** Assign a score to the password based on entropy and configurable parameters.
23+
- **Flexible Modes:** Choose between **strict**, **regex**, or **score** based validation modes.
24+
- **Configurable Messages:** Customize the messages displayed for different validation rules.
25+
- **TypeScript Support:** Fully typed for improved development experience with TypeScript.
26+
- **100% Test Coverage:** Ensures that all code is thoroughly tested, providing high reliability and stability for the product.
27+
28+
29+
## Installation
30+
31+
### To install the package, use npm:
32+
33+
```bash
34+
npm install pwd-strength-validator
35+
```
36+
37+
### Install via Browser Script Tag using UNPKG
38+
39+
```html
40+
<script src="https://unpkg.com/pwd-strength-validator/dist/pwd-strength-validator.umd.js"></script>
41+
<script type="text/javascript">
42+
const password: string = "ZAQ!2wsx!";
43+
const result = validatePasswordStrength(password);
44+
</script>
45+
```
46+
47+
## Configuration Options
48+
49+
You can configure the hook with various options:
50+
51+
- **`maxScore`**:
52+
53+
- _Type_: `number`
54+
- _Description_: Maximum score that can be assigned to the password.
55+
- _Default_: `5`
56+
57+
- **`minBestEntropy`**:
58+
59+
- _Type_: `number`
60+
- _Description_: Minimum entropy required for a top score.
61+
- _Default_: `80`
62+
63+
- **`minRequiredScore`**:
64+
65+
- _Type_: `number`
66+
- _Description_: Minimum score required for a valid password.
67+
- _Default_: `3`
68+
69+
- **`mode`**:
70+
71+
- _Type_: `"strict" | "regex" | "score"`
72+
- _Description_: Validation mode. Choose from:
73+
- `"strict"`: Requires both high score and specific point thresholds.
74+
- `"regex"`: Requires specific point thresholds.
75+
- `"score"`: Requires a minimum score to be valid.
76+
- _Default_: `"strict"`
77+
78+
- **`configMessages`**:
79+
- _Type_: `IValidationMessages`
80+
- _Description_: Custom validation messages for different rules. You can provide custom messages for:
81+
- `minLowercaseMessage`: Message for lowercase letter requirement.
82+
- `minUppercaseMessage`: Message for uppercase letter requirement.
83+
- `minSpecialCharMessage`: Message for special character requirement.
84+
- `minNumberMessage`: Message for number requirement.
85+
- `minLengthMessage`: Message for minimum length requirement.
86+
87+
## Usage
88+
89+
### Basic Usage
90+
91+
Here's a basic example of how to use the `validatePasswordStrength`:
92+
93+
```typescript
94+
import { validatePasswordStrength } from "pwd-strength-validator";
95+
96+
const password: string = "ZAQ!2wsx!";
97+
98+
const result = validatePasswordStrength(password);
99+
100+
console.log("Password:", result.password);
101+
console.log("Score:", result.score);
102+
console.log("Entropy:", result.entropy);
103+
console.log("Is Valid:", result.isValid);
104+
console.log("Validation Result:", result.validationResult);
105+
106+
// result:
107+
// {
108+
// "validationResult": [
109+
// { "regex": /[a-z]/, "points": 26, "message": "At least 1 lowercase letter", "passed": true },
110+
// { "regex": /[A-Z]/, "points": 26, "message": "At least 1 uppercase letter", "passed": true },
111+
// { "regex": /[ !@#$%^&*()_+\-=[\]{};':"\\|,.<>/?~]/, "points": 33, "message": "At least 1 special character", "passed": true },
112+
// { "regex": /[0-9]/, "points": 10, "message": "At least 1 number", "passed": true },
113+
// { "regex": /.{8,}/, "points": 1, "message": "At least 8 characters long", "passed": true }
114+
// ],
115+
// "score": 3,
116+
// "entropy": 52.67970000576925,
117+
// "password": "ZAQ!2wsx!",
118+
// "isValid": true
119+
// }
120+
```
121+
122+
### Example of Customized Usage
123+
124+
Here's an example of how to use the `validatePasswordStrength` with customized options:
125+
126+
```typescript
127+
import { validatePasswordStrength } from "pwd-strength-validator";
128+
129+
const password: string = "ZAQ!2wsx@1"; // Keep the password at 10 characters
130+
131+
const result = validatePasswordStrength(password, {
132+
maxScore: 7, // Set the maximum score
133+
minBestEntropy: 90, // Minimum entropy
134+
minRequiredScore: 4, // Minimum required score
135+
mode: "strict", // Validation mode
136+
configMessages: {
137+
minLowercaseMessage: "Must include at least one lowercase letter", // Message for lowercase requirement
138+
minUppercaseMessage: "Must include at least one uppercase letter", // Message for uppercase requirement
139+
minSpecialCharMessage: "Must include at least one special character", // Message for special character requirement
140+
minNumberMessage: "Must include at least one number", // Message for number requirement
141+
minLengthMessage: "Must be at least 10 characters long", // Message for length requirement
142+
},
143+
});
144+
145+
console.log("Password:", result.password);
146+
console.log("Score:", result.score);
147+
console.log("Entropy:", result.entropy);
148+
console.log("Is Valid:", result.isValid);
149+
console.log("Validation Result:", result.validationResult);
150+
151+
// Expected result
152+
// {
153+
// "validationResult": [
154+
// { "regex": /[a-z]/, "points": 26, "message": "Must include at least one lowercase letter", "passed": true },
155+
// { "regex": /[A-Z]/, "points": 26, "message": "Must include at least one uppercase letter", "passed": true },
156+
// { "regex": /[ !@#$%^&*()_+\-=[\]{};':"\\|,.<>/?~]/, "points": 33, "message": "Must include at least one special character", "passed": true },
157+
// { "regex": /[0-9]/, "points": 10, "message": "Must include at least one number", "passed": true },
158+
// { "regex": /.{10,}/, "points": 1, "message": "Must be at least 10 characters long", "passed": true }
159+
// ],
160+
// "score": 4,
161+
// "entropy": 90.25142590365954, // Entropy may vary
162+
// "password": "ZAQ!2wsx@1",
163+
// "isValid": true
164+
// }
165+
```
166+
167+
## API
168+
169+
### `validatePasswordStrength(password: string, params?: IValidatePasswordStrengthOptions): IValidatePasswordStrengthResponse`
170+
171+
#### Parameters
172+
173+
- **`password`** (`string`): The password to be validated.
174+
175+
- **`params`** (`optional`): Configuration options for the function. You can customize validation rules, set minimum entropy, adjust the scoring system, and provide custom messages.
176+
177+
#### Returns
178+
179+
- **`validationResult`** (`IValidationRule[]`): An array of validation rules with their status. Each rule contains:
180+
181+
- **`regex`** (`RegExp`): Regular expression used for validation.
182+
- **`points`** (`number`): Points assigned for passing the rule.
183+
- **`message`** (`string`): Message to display when the rule is not passed.
184+
- **`passed`** (`boolean`): Boolean indicating whether the rule was passed.
185+
186+
- **`score`** (`number`): The score assigned to the password based on its entropy and the configured scoring system.
187+
188+
- **`entropy`** (`number`): The entropy of the password, representing its strength and complexity.
189+
190+
- **`password`** (`string`): The current password being evaluated by the function.
191+
192+
- **`isValid`** (`boolean`): Boolean indicating whether the password meets the configured criteria.
193+
194+
## License
195+
196+
MIT — use for any purpose. Would be great if you could leave a note about the original developers. Thanks!
197+
198+
## Contributing
199+
200+
If you'd like to contribute to this project, please fork the repository and submit a pull request with your changes. Make sure to follow the code style and include tests for new features or bug fixes.

‎eslint.config.js

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
import js from "@eslint/js";
2+
import globals from "globals";
3+
import tseslint from "typescript-eslint";
4+
5+
export default tseslint.config(
6+
{ ignores: ["dist"] },
7+
{
8+
extends: [js.configs.recommended, ...tseslint.configs.recommended],
9+
files: ["**/*.{ts,tsx}"],
10+
languageOptions: {
11+
ecmaVersion: 2020,
12+
globals: globals.browser,
13+
},
14+
}
15+
);

0 commit comments

Comments
 (0)