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

Synopsis

Passken.js is an open source password and JWT management library for Node.js to create, encrypt safely.

• Only 1 dependency to check inputs variables
• Very lightweight
• Thoroughly tested
• Imported as EcmaScrypt module
• Works in Javascript and Typescript
• Written in Typescript

Support

• Node.js: 22

This is the oldest targeted versions. The library should not work properly on older versions of Node.js because it uses node:crypto in order to not depend on external dependencies.

Installation

$ npm i @dwtechs/passken

Usage

ES6 / TypeScript

Example of use with Express.js using ES6 module format

import { compare, create, encrypt, sign, verify } from "@dwtechs/passken";

const { PWD_SECRET, TOKEN_SECRET } = process.env;

/**
 * This function checks if a user-provided password matches a stored hashed password in a database.
 * It takes a request object req and a response object res as input, and uses a pass service to compare the password.
 * If the password is correct, it calls the next() function to proceed with the request.
 * If the password is incorrect or missing, it calls next() with an error status and message.
 */
function comparePwd(req, res, next) {
  
  const pwd = req.body.pwd; // from request
  const hash = req.user.hash; //from db
  if (compare(pwd, hash, PWD_SECRET))
    return next();
  
  return next({ status: 401, msg: "Wrong password" });

}

/**
 * Generates random passwords 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 = create(options);
  user.pwdHash = encrypt(user.pwd, PWD_SECRET);
  next();

}

function signToken(req, res, next) {
  res.jwt = sign(req.userId, 3600, TOKEN_SECRET);
  next();
}

function verifyToken(req, res, next) {
  res.jwt = sign(req.userId, 3600, TOKEN_SECRET);
  next();
}

export {
  comparePwd,
  createPwd,
  signToken,
  verifyToken,
};

Configure

Passken will start with the following default password configuration :

  Options = {
    len: 12,
    num: true,
    ucase: true,
    lcase: true,
    sym: false,
    strict: true,
    similarChars: false,
  };

Environment variables

You can update password configuration using the following environment variables :

  PWD_LENGTH,
  PWD_NUMBERS,
  PWD_UPPERCASE,
  PWD_LOWERCASE,
  PWD_SYMBOLS,
  PWD_STRICT,
  PWD_SIMILAR_CHARS,

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 create() method anymore.

API Reference

Types

type Options = {
  len: number,
  num: boolean,
  ucase: boolean,
  lcase: boolean,
  sym: boolean,
  strict: boolean,
  similarChars: boolean,
};

Methods

Password

// Default values
let saltRnds = 12
let digest = "sha256";
let keyLen = 64;

function getSaltRounds(): number {}

function setSaltRounds(rnds: number): number {} // between 12 and 100

function getKeyLen(): number {}

function setKeyLen(r: number): number {} // between 2 and 256

function getDigest(): string {}

function setDigest(d: string): string {} // the list of available digests can be given by getDigests()

function getDigests(): string[] {}

// Encrypt a string peppered with a secret
function encrypt( pwd: string, 
                  secret: string
                ): string | false {}

// Compare a string with a hash
function compare( pwd: string, 
                  hash: string,
                  secret: string
                ): boolean {}

// Create a random password
function randPwd(opts: Partial<Options> = defOpts): string {}

JWT

// Default values
const header {
  alg: "HS256",
  typ: "JWT",
  kid: null,
};

// Create a JWT
function sign( iss: number | string, 
               duration: number, 
               b64Secrets: string[]
             ): string;

// Verify a JWT
function verify( token: string, 
                 b64Secrets: string[]
               ): object | false;

Secret

// Generate a random 256-bit secret
randSecret(length = 32): string

options

Any of these can be passed into the options object for each function.

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.

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.

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