https://github.com/dwtechs/passken.js
Safe pass encryption and other useful tools in Javascript
https://github.com/dwtechs/passken.js
Last synced: 3 months ago
JSON representation
Safe pass encryption and other useful tools in Javascript
- Host: GitHub
- URL: https://github.com/dwtechs/passken.js
- Owner: DWTechs
- License: mit
- Created: 2024-10-21T11:57:30.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-10-15T20:12:21.000Z (8 months ago)
- Last Synced: 2025-10-16T20:00:01.459Z (8 months ago)
- Language: JavaScript
- Size: 346 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/@dwtechs/passken)
[](https://www.npmjs.com/package/@dwtechs/passken)
- [Synopsis](#synopsis)
- [Support](#support)
- [Installation](#installation)
- [Usage](#usage)
- [Configure](#configure)
- [API Reference](#api-reference)
- [Error Handling](#error-handling)
- [options](#options)
- [Express.js](#expressjs)
- [Contributors](#contributors)
- [Stack](#stack)
## Synopsis
**[Passken.js](https://github.com/DWTechs/Passken.js)** is an open source password generation library for Node.js.
- 📦 Only 1 dependency to check inputs variables
- 🪶 Very lightweight
- 🧪 Thoroughly tested
- 🚚 Shipped as EcmaScrypt module
- 📝 Written in Typescript
## Support
- Node.js: 22
This is the oldest targeted versions.
## Installation
```bash
$ npm i @dwtechs/passken
```
## Usage
Usage example of use with Express.js using ES6 module format
```javascript
import { randomPwd } from "@dwtechs/passken";
import { encrypt } from "@dwtechs/hashitaka";
/**
* Generates a random password for a user and encrypts it.
*/
function createPwd(req, res, next) {
const user = req.body.user;
const options = {
len: 14,
num: true,
ucase: true,
lcase: true,
sym: true,
strict: true,
similarChars: true,
};
user.pwd = randomPwd(options);
user.pwdHash = encrypt(user.pwd, PWD_SECRET);
next();
}
export {
createPwd,
};
```
Usage example for password validation :
```javascript
import { isValidPassword } from "@dwtechs/passken";
const PwdOptions = {
lcase: true,
ucase: true,
num: true,
sym: false,
minLen: 12,
maxLen: 16,
};
const password = 'teSt1234';
if (isValidPassword(password, PwdOptions)) {
// check if password is valid compared to PwdOptions
}
```
### Configure
For password creation Passken will start with the following default configuration :
```Javascript
RandomDefaultOptions = {
len: 12,
num: true,
ucase: true,
lcase: true,
sym: false,
strict: true,
similarChars: false,
};
```
For password validation Passken will start with the following default configuration :
```Javascript
ValidationDefaultOptions = {
lcase: true,
ucase: true,
num: true,
sym: true,
minLen: 12,
maxLen: 64,
};
```
### Environment variables
You can update random password configuration using the following environment variables :
```bash
PWD_RAND_LENGTH,
PWD_RAND_NUMBERS,
PWD_RAND_UPPERCASE,
PWD_RAND_LOWERCASE,
PWD_RAND_SYMBOLS,
PWD_RAND_STRICT,
PWD_RAND_SIMILAR_CHARS,
```
You can update password validation configuration using the following environment variables :
```bash
PWD_VALID_MINLENGTH,
PWD_VALID_MAXLENGTH,
PWD_VALID_NUMBERS,
PWD_VALID_UPPERCASE,
PWD_VALID_LOWERCASE,
PWD_VALID_SYMBOLS,
```
These environment variables will update the default values of the lib at start up.
With this strategy you do not need to send options parameter in the randomPwd() method anymore.
## API Reference
### Types
---
```javascript
type RandomOptions = {
len: number,
num: boolean,
ucase: boolean,
lcase: boolean,
sym: boolean,
strict: boolean,
similarChars: boolean,
};
type ValidationOptions = {
lcase: boolean,
ucase: boolean,
num: boolean,
sym: boolean,
maxLen: number,
minLen: number
}
```
### Methods
---
#### Password
```javascript
/**
* Generate a random password.
*
* @param {Partial} opts - The options to generate the password.
* @returns {string} The generated password.
*
*/
function randomPwd(opts: Partial = RandomDefaultOptions): string {}
/**
* Checks if a given password string meets the specified validation criteria.
*
* @param {string} s - The password string to validate.
* @param {PasswordOptions} [options=defaultOptions] - Optional configuration object to specify password validation criteria.
* @param {boolean} [throwErr=false] - If true, throws an error when password does not meet criteria. If false, returns false.
* @returns {boolean} `true` if the password meets all the specified criteria, false if not (when throwErr is false).
* @throws {Error} Throws an error if the password does not meet the specified criteria and throwErr is true.
*
* @example
* ```typescript
* const options = {
* minLen: 8,
* maxLen: 20,
* lcase: true,
* ucase: true,
* num: true,
* sym: true
* };
* const isValid = isValidPassword('Password123!', options);
* console.log(isValid); // true
* ```
*/
function isValidPassword(
s: string,
opts: Partial = ValidationDefaultOptions,
throwErr: boolean = false
): boolean {}
```
## options
**RandomPWD()** :
| Name | type | Description | Default |
| :----------- | :------ | :----------------------------------------------------------- | :------ |
| len | Integer | Minimal length of password | 12 |
| num* | Boolean | use numbers in password | true |
| sym* | Boolean | use symbols in password | true |
| lcase* | Boolean | use lowercase in password | true |
| ucase* | Boolean | use uppercase letters in password | true |
| strict | Boolean | password must include at least one character from each pool | true |
| similarChars | Boolean | allow close looking chars | false |
*At least one of those options must be true.
**isValidPassword()** :
| Name | type | Description | Default |
| :------ | :------ | :--------------------------------- | :------ |
| minLen | Integer | Minimal length of password | 12 |
| maxLen | Integer | Maximal length of password | 64 |
| num | Boolean | use numbers in password | true |
| sym | Boolean | use symbols in password | true |
| lcase | Boolean | use lowercase in password | true |
| ucase | Boolean | use uppercase letters in password | true |
- Symbols used : !@#%*_-+=:?><./()
- Similar characters : l, I, 1, o, O, 0
## Express.js
You can use Passken directly as Express.js middlewares using [@dwtechs/passken-express library](https://www.npmjs.com/package/@dwtechs/passken-express).
This way you do not have to write express controllers yourself to use **Passken**.
**@dwtechs/passken-express** brings middleware features for **@dwtechs/passken** and **@dwtechs/hashitaka** libraries.
## Contributors
**Passken.js** is still in development and we would be glad to get all the help you can provide.
To contribute please read **[contributor.md](https://github.com/DWTechs/Passken.js/blob/main/contributor.md)** for detailed installation guide.
## Stack
| Purpose | Choice | Motivation |
| :-------------- | :------------------------------------------: | -------------------------------------------------------------: |
| repository | [Github](https://github.com/) | hosting for software development version control using Git |
| package manager | [npm](https://www.npmjs.com/get-npm) | default node.js package manager |
| language | [TypeScript](https://www.typescriptlang.org) | static type checking along with the latest ECMAScript features |
| module bundler | [Rollup.js](https://rollupjs.org) | advanced module bundler for ES6 modules |
| unit testing | [Jest](https://jestjs.io/) | delightful testing with a focus on simplicity |