• Synopsis
• Support
• Installation
• Usage
  • Configure
• API Reference
• Error Handling
• options
• Express.js
• Contributors
• Stack

Synopsis

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

$ npm i @dwtechs/passken

Usage

Usage example of use with Express.js using ES6 module format

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 :

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 :

  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 :

  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 :

  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 :

  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

---

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

/**
 * Generate a random password.
 * 
 * @param {Partial<Options>} opts - The options to generate the password.
 * @returns {string} The generated password.
 * 
 */
function randomPwd(opts: Partial<RandomOptions> = 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<ValidationOptions> = 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. 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 for detailed installation guide.

Stack

Purpose	Choice	Motivation
repository	Github	hosting for software development version control using Git
package manager	npm	default node.js package manager
language	TypeScript	static type checking along with the latest ECMAScript features
module bundler	Rollup.js	advanced module bundler for ES6 modules
unit testing	Jest	delightful testing with a focus on simplicity