• Synopsis
• Support
• Installation
• Usage
  • Configure
  • Environment variables
• API Reference
• options
• Logs
• Contributors
• Stack

Synopsis

Passken-express.js is an open source password management library for Express.js.
It includes @dwtechs/passken and adds Express middlewares to be used in a node.js service.

• 🪶 Very lightweight
• 🧪 Thoroughly tested
• 🚚 Shipped as EcmaScrypt Express module
• 📝 Written in Typescript

Support

• node: 22

This is the oldest targeted versions.

Installation

$ npm i @dwtechs/passken-express

Usage

import * as pk from "@dwtechs/passken-express";
import express from "express";
const router = express.Router();

import user from "../controllers/user.js";
import mail from "../controllers/mail.js";
import consumer from "../controllers/consumer.js";

const passwordOptions = {
  len: 14,
  num: true,
  ucase: false,
  lcase: false,
  sym: false,
  strict: true,
  similarChars: true,
};
pk.init(passwordOptions);

// middleware sub-stacks

// add users
const addMany = [
  user.validate,
  pk.create,
  user.addMany,
  mail.sendRegistration,
];

// Login user
const login = [
  user.validate,
  user.getPwd,
  pk.compare,
  user.isActive,
];


// Routes

// log a user with his email & password
router.post("/", login);

// Add new users
router.post("/", addMany);

Configure

You do not need to initialise the library using pwd.init() if the default config is fine for you.

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 do not need to intialise the library using pwd.init() if you are using the following environment variables:

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

These environment variables will update the default values of the lib at start up. So you do not need to init the library in the code.

Note that PWD_SECRET is mandatory.

API Reference

Types

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

PWD Functions

/**
 * Initializes the password generation options for the Passken-express library.
 * 
 * This function sets the global password options that will be used by the `create` function
 * when generating random passwords. The options control password characteristics such as
 * length, character sets, and complexity requirements.
 * 
 * @param {Options} options - Password generation options from @dwtechs/passken
 * @param {number}  options.len - Password length (minimum characters)
 * @param {boolean} options.num - Include numbers in password
 * @param {boolean} options.ucase - Include uppercase letters
 * @param {boolean} options.lcase - Include lowercase letters  
 * @param {boolean} options.sym - Include symbols in password
 * @param {boolean} options.strict - Password must include at least one character from each enabled pool
 * @param {boolean} options.similarChars - Allow visually similar characters (l, I, 1, o, O, 0)
 * 
 * @returns {void}
 * 
 * **Input Properties:**
 * - `options` (Options object) - Password generation configuration
 * 
 * **Output Properties:**
 * - None (sets global configuration)
 * 
 * @example
 * ```typescript
 * import { init } from '@dwtechs/passken-express';
 * 
 * // Initialize with custom password options
 * init({
 *   len: 16,
 *   num: true,
 *   ucase: true,
 *   lcase: true,
 *   sym: true,
 *   strict: true,
 *   similarChars: false
 * });
 * ```
 */
function init(options: Options): void {}

/**
 * Express middleware to compare a user-provided password with a stored hashed password.
 * 
 * This middleware validates that a plaintext password from the request matches a hashed
 * password from the database. It extracts the password from the request body and the
 * hash from either the response rows or response object, then uses Passken's secure
 * comparison function to verify the match.
 * 
 * @param {Request} req - Express request object containing the password
 * @param {MyResponse} res - Express response object containing the database hash
 * @param {NextFunction} next - Express next function to continue middleware chain
 * 
 * @returns {void} Calls next() to continue, or next(error) on failure
 * 
 * @throws {InvalidPasswordError} If the password is invalid or does not match the hash (HTTP 400)
 * @throws {InvalidBase64SecretError} If the secret is not a valid base64 string (HTTP 400)
 * @throws {Object} Will call next() with error object containing:
 *   - statusCode: 400 - When password is missing from request body
 *   - statusCode: 400 - When hash is missing from response data
 *   - statusCode: 401 - When password doesn't match the stored hash
 * 
 * @example
 * ```typescript
 * import { compare } from '@dwtechs/passken-express';
 * 
 * // Usage in Express route after database query
 * app.post('/login', getUserFromDB, compare, (req, res) => {
 *   res.json({ message: 'Login successful' });
 * });
 * 
 * // Request body should contain:
 * // { "password": "user-password" } or { "pwd": "user-password" }
 * 
 * // Response should contain hash from database:
 * // res.rows[0].password or res.rows[0].pwd or res.password or res.pwd
 * ```
 */
function compare(req: Request, res: MyResponse, next: NextFunction): void {}

/**
 * Express middleware to generate random passwords and encrypt them for multiple users.
 * 
 * This middleware generates secure random passwords for multiple user records and encrypts
 * them using Passken's encryption function. It processes an array of user objects in the
 * request body, adding both plaintext and encrypted password fields to each record.
 * The plaintext passwords can be sent to users (e.g., via email) while encrypted passwords
 * are stored in the database.
 * 
 * @param {Request} req - Express request object containing user records in body.rows
 * @param {Response} _res - Express response object (not used in this function)
 * @param {NextFunction} next - Express next function to continue middleware chain
 * 
 * @returns {void} Calls next() to continue, or next(error) on failure
 * 
 * @throws {InvalidPasswordError} If password generation or encryption fails (HTTP 400)
 * @throws {InvalidBase64SecretError} If the secret is not a valid base64 string (HTTP 400)
 * @throws {Object} Will call next() with error object containing:
 *   - statusCode: 400 - When req.body.rows is missing or not an array
 * 
 * @example
 * ```typescript
 * import { create } from '@dwtechs/passken-express';
 * 
 * // Usage in Express route for bulk user creation
 * app.post('/users/bulk', create, saveUsersToDatabase, (req, res) => {
 *   // Send plaintext passwords to users via email
 *   req.body.rows.forEach(user => {
 *     sendPasswordEmail(user.email, user.pwd);
 *   });
 *   res.json({ message: 'Users created successfully' });
 * });
 * 
 * // Request body should contain:
 * // { "rows": [{ "name": "User1", "email": "[email protected]" }, ...] }
 * 
 * // After processing, each row will have:
 * // { "name": "User1", "email": "[email protected]", "pwd": "generated-password", "encryptedPwd": "encrypted-hash" }
 * ```
 */
function create(req: Request, res: Response, next: NextFunction): void {}

Password Comparison

The function will look for a password value from the client request body :

const pwd = req.body?.password || req.body?.pwd || req.body?.pwdHash.

It will then look for the hashed password stored in the database :

const hash = res.password 
  || res.pwd 
  || res.pwdHash
  || res.rows[0].password 
  || res.rows[0].pwd 
  || res.rows[0].pwdHash
  || res.locals.rows[0].password 
  || res.locals.rows[0].pwd 
  || res.locals.rows[0].pwdHash;

Password generation

The function will loop through an array in req.body.rows.

It will throw an error if req.body.rows is missing or empty.

New passwords will be added into req.body.rows[i].pwd. Encrypted passwords will be added into req.body.rows[i].encryptedPwd .

PWD 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

Logs

Passken-express.js uses @dwtechs/Winstan library for logging. All logs are in debug mode. Meaning they should not appear in production mode.

Contributors

Passken-express.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 | advanced module bundler for ES6 modules | | unit testing | Jest | delightful testing with a focus on simplicity |