@dwtechs/passken

v0.6.0

Published

2 months ago

Open source password generation library for Node.js.

0High
0Medium
0Low

dwtechs

passwords

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() :

*At least one of those options must be true.

isValidPassword() :

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 |