Express User Manager

A user management and authentication library for Express apps.

It automatically creates and adds the following API endpoints to an Express app:

• user registration
• user login
• user logout
• user retrieval
• users listing
• user searching
• user data update
• user account deletion

Additional features include:

• customizable API endpoints
• support for multiple database engines and data-storage mechanisms
• customization of the minimum and maximum length of passwords
• specification of non-secure passwords that should not be allowed for use as passwords

New in V3.0.0: Support for Hooks

Table of Contents

• Installation
• Quick start
• The init method
• Configuration
  • Environment variables
  • The config method
  • Specifying custom API endpoints
• Built-in middlewares
• Hooks
  • Available hooks
    • Request hooks
    • Response hooks
  • Registering request and response hooks
    • Registering hooks: examples
  • Unregistering request and response hooks
    • Unregistering hooks: examples
• Built-in data stores (database drivers)
• Emitted events
  • Events emitted by the database
  • Events emitted by request handlers
  • Events emitted by middlewares
• Password constraints
• Usage as a stand-alone server
• Requests and responses
• Contributing
  • Report a bug
  • Request a new feature
  • Submit a pull request
  • Checkout the Contributing guide
• CHANGELOG
• License
• Author

Installation

npm install --save express-user-manager

Quick start

const express = require('express');
const userManager = require('express-user-manager');
const app = express();

/**
 * Setup the datastore using any of the currently supported database adapters:
 *   - mongoose: for MongoDB
 *   - sequelize: for any of the other supported database engines:
 *     MySQL | MariaDB | SQLite | Microsoft SQL Server | Postgres | In-memory DB
 *     (See the section on "Built-in data stores" for supported database engines)
 */
const dbAdapter = 'mongoose'; // OR 'sequelize'
const store = userManager.getDbAdapter(dbAdapter);

// Bind the routes under [apiMountPoint] (default: ***/api/users***):
userManager.listen(expressApp, apiMountPoint = '/api/users', customRoutes = {});

(async function() {
  const server = http.createServer(app);

  // Establish a connection to the data store
  // Ensure the db is connected before binding the server to the port
  await store.connect({
    host: DB_HOST, // optional, default: 'localhost'
    port: DB_PORT, // optional
    user: DB_USERNAME, // optional
    pass: DB_PASSWORD, // optional
    engine: DB_ENGINE, // optional if the adapter is "mongoose" or if the value is "memory" and the adapter is "sequelize"; required otherwise
    dbName: DB_DBNAME, // optional, default: 'users'
    storagePath: DB_STORAGE_PATH, // optional, required if "engine" is set to "sqlite"
    debug: DB_DEBUG, // optional, default: false
    exitOnFail: EXIT_ON_DB_CONNECT_FAIL // optional, default: true
  });

  // Proceed with normal server initialization tasks
  server.listen(PORT);
  server.on('error', onError);
  server.on('listening', onListening);
 })();

// Optionally listen for and handle events
// (See the Emitted events section for more)
userManager.on(EVENT_NAME, function(data) {
  // do something with data
});

Quick notes

• The expressApp parameter has the following constraints:
  • It must be an express app (that is, an app created using const app = express())
  • It MUST NOT be an express server, that is, it must not have been passed to http.createServer(app)
• The apiMountPoint parameter allows you to specify the base API route. Every request to the API will be relative to this base route. The default is /api/users.

• The customRoutes parameter is an object that allows customization of the routes.

  (See Specifying custom API endpoints for more)

• If your expressApp has its own custom routing in place, make sure to call userManager.listen(expressApp) before setting up your app's custom 404 handler.

  This is because your app's 404 handler is meant to trap requests sent to routes that have no explicit handler in your app's routing system.

  Consequently, if you setup your app's custom 404 handler before calling userManager.listen(), requests to routes handled by the userManager's routing system will never get to it as they will be trapped and handled by your 404 handler.

The init method

The init method provides a shortcut way to perform the setup and initialization steps above.

It is an async function that runs setup and initialization tasks, connects to the database, then starts listening for requests, all in a single step: await init(app, options);.

It takes two parameters:

• an express.js app as the first argument
• an object (with the same signature as the object passed to the config method) as the second argument.

Configuration

express-user-manager can be configured in several ways:

• using environment variables (See the Environment variables section)
• using the config method (See The config method)
• passing configuration options as the second parameter to the init(app, options) method
• using a combination of environment variables and the config method
  • if configuration is not set via config, then configuration values are searched in environment variables.
  • if only some configuration options are set using config, then the others are searched for in environment variables.
  • The configuration options set via config take precedence over environment variables.
  • the arguments passed to the listen or init methods take precedence over configuration options set using config.

Environment variables

• NODE_ENV (string): The environment in which the app is running: development, production, staging, test, etc.
• API_MOUNT_POINT (string): The route under which to listen for API requests, default is: /api/users
• PORT: The port on which the server is running (or should run, if using as a stand-alone server)
• DB_ENGINE: The database engine to use. Should be one of the supported databases. (See Built-in data stores)
• DB_ADAPTER: The adapter to use. Set it to mongoose if using MongoDB; Set it to sequelize otherwise.
• DB_STORAGE_PATH: Define this only when the DB_ENGINE is set to sqlite.
• DB_HOST: The database host
• DB_USERNAME: The database user
• DB_PASSWORD: The database user's password
• DB_DBNAME: The name of the database
• DB_PORT: The port on which the database is running
• DB_DEBUG: Set to true or a non-zero integer to display debug output for the database.
• EXIT_ON_DB_CONNECT_FAIL: Set to true or a non-zero integer if the app should exit if it is unable to establish a connection to the database.
• SESSION_SECRET (string)
• AUTH_TOKEN_SECRET (string)
• AUTH_TOKEN_EXPIRY (number): Authorization token expiry (in seconds)
• PASSWORD_MIN_LENGTH (number)
• PASSWORD_MAX_LENGTH (number)
• DISALLOWED_PASSWORDS: (array): A comma-separated list of weak/non-secure passwords that should not allowed to be used as passwords

Note: express-user-manager uses the dotenv package, so a quick and easy way to define the above variables is to create a .env file at the root of your project directory, and add them to the file and they will automatically be picked up. Sample .env file

The config method

As stated earlier in the Configuration section, one of the ways you can configure express-user-manager is by using the config method.

This method provides an alternate way to pass configuration values to *express-user-manager** if you haven't done (or are unable to do) so via environment variables.

Below is an example touching on every setting:

• apiMountPoint: (string) specifies the users API routes base route
• password: (object) for configuring minimum and maximum password length, as well as disallowed passwords
• routes: (object) for setting up custom API endpoints
• db: (object) encapsulating database connection information
• security: (object) for configuring session and authorization tokens and expiry

const express = require('express');
const userManager = require('express-user-manager');
const app = express();
const dbAdapter = 'mongoose'; // OR 'sequelize'

// Call config(options) to configure the app
userManager.config({
  apiMountPoint: {string}, // The base route under which to listen for API requests

  password: { // {object} for password configuration
    minLength: {number}, // minimum length of user passwords, default: 6,
    maxLength: {number}, // maximum length of user passwords, default: 20
    disallowed: {string | array}, // comma-separated string or array of strings considered weak/non-secure passwords
  },

  routes: { // {object} for configuring custom routes, with members
    list: {string}, // specifies the path for getting users listing
    search: {string}, // specifies the path for searching users
    getUser: {string}, // specifies the path for getting a user's details via their username, a /:{username} is appended to this path
    signup: {string}, // specifies the user registration path
    login: {string}, // specifies user authentication path,
    logout: {string}, // defines the logout path
    updateUser: {string}, // specifies the path for updating a user's data
    deleteUser: {string} // specifies the path for deleting a user, a /:{userId} is appended to this path
  },

  db: { // {object} for configuring the database connection
    adapter: {string}, // the adapter to use. valid values include 'mongoose', 'sequelize'
    host: {mixed}, // database host
    port: {number}, // database port
    user: {string}, // database user
    pass: {string}, // database user's password
    engine: {string}, // the database engine, when the adapter is set to "sequelize". values: 'memory', 'mariadb', 'mssql', 'mysql', 'postgres', 'sqlite'
    dbName: {string}, // name of the database to connect to
    storagePath: {string}, // the database storage path, only valid when "engine" is "sqlite". combined with `dbName`: `${storagePath}/${dbName}.sqlite`
    debug: {boolean}, // a value of true outputs database debug info
    exitOnFail: {boolean}, // set to true to kill the Node process if database connection fails
  },

  security: { // {object} for configuring security
    sessionSecret: {string}, // a key for encrypting the session
    authTokenSecret: {string}, // a key for signing the authorization token
    authTokenExpiry: {number}, // the expiry time of the authorization token (in seconds), example: 60 * 60 * 24
  }
});

async(() => {
  /**
   * The dbAdapter argument is not required if it is either:  
   *   - specified in the db section of the call to config or as
   *   - set using the DB_ADAPTER environment variable
   */
  const store = userManager.getDbAdapter([dbAdapter]);

  /**
   * The connectionOptions are not required if the values:
   *   - are already specified in the db section of the call to config
   *   - are set using the DB_* environment variables
   */
  await store.connect([connectionOptions]);

  // If the dbAdapter and connection values are already specified
  // via config or via environment variables,
  // then the above two calls can be tersely combined in a single call:
  // await userManager.getDbAdapter().connect();
});

// Bind request listeners
userManager.listen(expressApp);

Notes on configuration settings:

• Any of the above settings can be omitted in the call to config if they are already defined using environment variables. The exception to this is routes, which cannot be set via an environment variable. However, you can set it using the third parameter to the call to listen(app, apiMountPoint, routes).
• If a setting is defined as an environment variable and also set in the call to config, the value set in config will take precedence and be used instead.
• The apiMountPoint can be set (in increasing order of precedence):
  • using the environment variable API_MOUNT_POINT
  • using the apiMountPoint key in the options to config
  • as the second parameter to the call to listen(app, apiMountPoint, routes)

Specifying custom API endpoints

To customize the request paths, either:

• pass a routes property with the API endpoints to config:

  userManager.config({
  routes: customApiEndpoints
  });
  
  userManager.listen(expressApp, apiMountPoint);

• pass an object with the API endpoints as the last parameter to userManager.listen: userManager.listen(expressApp, apiMountPoint, customApiEndpoints)

Below is the default definition of the API Endpoints, which can be modified for your custom routes:

const customApiEndpoints = {
  list       : '/',       // Resolves to [apiMountPoint]/
  search     : '/search', // Resolves to [apiMountPoint]/search
  getUser    : '/user',   // Resolves to [apiMountPoint]/user/:username
  signup     : '/',       // Resolves to [apiMountPoint]/
  login      : '/login',  // Resolves to [apiMountPoint]/login
  logout     : '/logout', // Resolves to [apiMountPoint]/logout
  updateUser : '/',       // Resolves to [apiMountPoint]/
  deleteUser : '/user',   // Resolves to [apiMountPoint]/user/:userId
};

API endpoints object properties

As seen above, the default object has a number of properties, each corresponding to a request path:

• list : Specifies the path to get users listing
• search : Specifies the path to search for users
• getUser : Specifies the path to get a user by username (a /:username is automatically appended to the end of this route)
• signup : Specifies the path for creating (i.e., registering) a new user
• login : Specifies the path for logging in a user (an authorization key is returned on successful login)
• logout : Specifies the path to log out a user
• updateUser: Specifies the path for updating user information
• deleteUser : Specifies the path for deleting user by id (a /:userId is automatically appended to the end of this route)

Built-in middlewares

The userManager module provides some middlewares. You can get them by calling: userManager.get('middlewares');. This will return an object with the following middlewares:

• authorized: For protected resources. It ensures an access/authorization token is sent along with the request using the Authorization header.
• loadUser: Loads the current user (identified by username) into the request, to that it is available to every other middleware in the middleware chain. The username is sent as part of the request parameters (request.params)
• loggedIn: Ensures a user is logged in before they can perform the requested action.
• notLoggedIn Ensures that the target action is available only to users who are not logged in. For example, registration and login should (normally) not be permissible if the current user is already logged in.
• restrictUserToSelf: Constrains a user to performing certain actions only on their own account.

Hooks

Hooks are a mechanism to allow you hook into different parts of the application's lifecycle.

Available hooks

• Request hooks: allow you define and register custom request middlewares. They give you the ability to modify the request any way you see fit.

  Request hooks are called first before any other middleware in the middleware chain is called. This gives you great flexibility in modifying the request before handing it over to other middleware functions in the chain.

• Response hooks: let you define and register custom response-modifying functions.

  Response hooks are called just before the response is sent back to the client, giving you the ability to modify the response before it gets to the client.

  Note: Currently, response hooks are only fired when the HTTP response status code is 200.

You can register a request or response hook for a single route, for multiple routes, or for all routes.

Registering request and response hooks

To register a request or response hook:

• define a middleware, which is just a fancy word for a function that takes three parameters: req, res, next.

  If you intend to hand over processing to the next handler in the chain (recommended), remember to call next() from within your middleware when you are done; Or call next(error) to pass execution to the error handler.

• decide on which route (or routes) the middleware should be registered for: single-route, multi-route, global. The route(s) should correspond to a key or keys in the API endpoints configuration object.

  Multiple hooks can be registered on a given route.

• Register the hook:

  • call userManager.addRequestHook(target, middlewareFn) to register a request hook
  • call userManager.addResponseHook(target, middlewareFn) to register a response hook

  The first parameter to addRequestHook or addResponseHook is a string or an array of strings that specify the target of the hook. Possible values include:

  • *: represents a global hook, which will register the hook for every path
  • pathName, e.g login: represents a single-route hook, which will register the hook for the specified route
  • list of pathNames, e.g ['login', 'signup', ...]: represents multi-route hooks, which will register the hook for every path in the array

Registering hooks: examples

• Register a request hook for every route:

  userManager.addRequestHook('*', function(req, res, next) {
  // Do something interesting here, with the request or the response.
  req.accessTime = Date.now();
  
  // Call next to pass control onto the next middleware function
  next();
  });

• Register a response hook for the signup route:

  userManager.addResponseHook('signup', function(req, res, next) {
  // You can for example set/append custom response headers:
  res.append('Access-Control-Allow-Headers', '<CUSTOM_HEADER>');
  });

• Register a response hook for multiple (login and signup) routes:

  userManager.addResponseHook(['login', 'signup'], function(req, res, next) {
  // Do something tangible
  res.body.data.authenticated = true;
  });

• Register a list of request hooks along with their corresponding function identifiers:

  userManager.addRequestHook(['login', 'signup'], ['loginFnId', 'signupFnId'])

• Register multiple response hooks for a single (signup) route:

  userManager.addResponseHook('signup', [callback1, callback2, ...]);

Unregistering request and response hooks

You also have the ability to unregister a hook when the hook is no longer needed. And you can unregister hooks globally, for only some routes, or for a single route.

• To unregister a request hook, call userManager.removeRequestHook(route [, callback]).

  If the optional callback parameter is not specified, every hook registered to that route will be removed. Otherwise, only the particular callback function specified for the hook is removed.

• To unregister a response hook, call userManager.removeResponseHook(route, [callback]);

  If the optional callback parameter is not specified, every hook registered to that route will be removed. Otherwise, only the particular callback function specified for the hook is removed.

Unregistering hooks: examples

• Unregister every request hook:

  userManager.removeRequestHook('*');

• Unregister every response hook for the user signup route:

  userManager.removeResponseHook('signup');

• Unregister only a request callback hook for the signup route:

  UserManager.removeRequestHook('signup', fn);

  fn should be a named function registered with userManager.addRequestHook('signup', fn);

  Anonymous functions cannot be unregistered this way.

• Unregister a list of request hooks along with their corresponding function identifiers:

  userManager.removeRequestHook(['login', 'signup'], ['loginFnId', 'signupFnId']);

• Unregister every response hook for the passed routes list:

  userManager.removeRequestHook(['login', 'signup']);

• Unregister multiple request hooks for a single (login) route:

  userManager.removeRequestHook('login', [fn1, fn2, ...]);

Built-in data stores (database adapters and engines)

• In-memory (Adapter: sequelize)
  • Note: In-memory storage should be used solely for quick prototyping and testing purposes. It is not recommended for use in production.
• MariaDB (Adapter: sequelize, Engine: mariadb)
• Microsoft SQL Server (Adapter: sequelize, Engine: mssql)
• MongoDB (Adapter: mongoose)
• MysQL (Adapter: sequelize, Engine: mysql)
• Postgres (Adapter: sequelize, Engine: postgres)
• SQLite (Adapter: sequelize, Engine: sqlite)

Emitted events

Events emitted by the database

• dbConnection
• dbDisconnect
• createUser

Events emitted by request handlers

• signupError
• signupSuccess
• loginError
• loginSuccess
• logoutSuccess
• getUsersError
• getUsersSuccess
• searchUsersError
• searchUsersSuccess
• getUserSuccess
• updateUserError
• updateUserSuccess
• deleteUserError
• deleteUserSuccess

Events emitted by middlewares

• actionNotPermittedError
• authorizationError
• authenticationError

Password constraints

• minimum length of PASSWORD_MIN_LENGTH environment variable
• maximum length of PASSWORD_MAX_LENGTH environment variable
• must contain at least one number
• must contain at least an uppercase character
• must contain at least a lowercase character
• must not be among the values specified in the DISALLOWED_PASSWORDS environment variable

Usage as a stand-alone server

The package comes with a built-in express server that allows you run it as a stand-alone server.

To run it as a stand-alone server, do the following:

• Ensure you have a server running for your preferred database engine. (See Setting up test databases for some examples)
• Define the environment variables listed in the Environment variables section.
• start the server, using one of these two methods:
  • Run node express-user-manager/src/server from within the parent directory containing the express-user-manager package.
  • require('express-user-manager/src/server')(); from within a node.js script. For example, inside an index.js file. Then run the file using node: node index.js.

Note: The built-in server runs using the default route/path settings. That means:

• it runs under the /api/users base route (mount point).
• it uses the default request paths. (See the section on Requests and responses)

Requests and responses

Every route below is assumed to begin (i.e., prefixed) with the base API route (or mount point). The default base API route is /api/users.

• Create user
  • route: POST /
  • protected: false
  • request headers: none
  • request parameters: none
  • request body: { firstname, lastname, username, email, password, confirmPassword }
  • response:

    {
    "data": {
      "user": { id, firstname, lastname, fullname, email, username, signupDate }
    }
    }

• Get user details by username
  • route: GET /user/USERNAME
  • protected: false
  • request headers: none
  • request parameters: none
  • request body: none
  • response:

    {
    "data": {
      "user": { id, firstname, lastname, fullname, email, username, signupDate }
    }
    }

• Retrieve list of users
  • route: GET /
  • protected: false
  • request headers: none
  • request parameters:
    • firstname (string, optional): get users matching {firstname}
    • lastname (string, optional): get users matching {lastname}
    • sort (string, optional)
    • page (number, optional, default = 1)
    • limit (number, optional, default = 20)
  • request body: none
  • response:

    {
    "data": {
      "total": TOTAL_COUNT_OF_MATCHING_RESULTS,
      "length": COUNT_OF_CURRENT_RESULTS_RETURNED, // determined by "page" and "limit"
      "users": [
        { id, firstname, lastname, fullname, email, username, signupDate },
        { id, firstname, lastname, fullname, email, username, signupDate },
        ...
      ]
    }
    }

• Search for users

  • route: GET /search?query=SEARCH_TERM
  • protected: false
  • request headers: none
  • request parameters:
    • query (string, required)
    • sort (string, optional)
    • by (string, optional)
    • page (number, optional, default = 1)
    • limit (number, optional, default = 20)
  • request body: none
  • response:

    {
    "data": {
      "total": TOTAL_COUNT_OF_MATCHING_RESULTS,
      "length": COUNT_OF_CURRENT_RESULTS_RETURNED, // determined by "page" and "limit"
      "users": [
        { id, firstname, lastname, fullname, email, username, signupDate },
        { id, firstname, lastname, fullname, email, username, signupDate },
        ...
      ]
    }
    }

  • examples:

    • Search for users with james in their firstname, lastname, username, or email:

      GET HOST:PORT/api/users/search?query=james

    • Search for users with james in their username or email:

      GET HOST:PORT/api/users/search?query=james&by=username:email

    • Sort by firstname (asc), lastname (asc), email (desc), creationDate (asc):

      GET HOST:PORT/api/users/search?query=james&sort=firstname:asc=lastname=email:desc=creationDate

    • Return the 3rd page of results and limit returned results to a maximum of 15 users:

      GET HOST:PORT/api/users/search?query=james&page=3&limit=15

• Login
  • route: POST /login
  • protected: false
  • request headers: none
  • request parameters: none
  • request body:

    {
    "login": EMAIL | USERNAME,
    "password": USER_PASSWORD,
    }

  • response:

    {
    "data": {
      "user": { id, firstname, lastname, fullname, email, username, signupDate },
      "authorization": {
        "token": "Bearer TOKEN_STRING",
        "expiresIn": "86400s"
      }
    }
    }

• Logout
  • route: GET /logout
  • protected: false
  • request headers: none
  • request body: none
  • request parameters: none
  • response: {}
• Update user data
  • route: PUT /
  • protected: true
  • request headers:

    {
    "Authorization": "Bearer TOKEN_STRING"
    }

  • request parameters: none
  • request body: { id, firstname, lastname, username, email }
  • response:

    {
    "data": {
      "user": { id, firstname, lastname, fullname, email, username, signupDate }
    }
    }

• Delete user by ID
  • route: DELETE /user/USER_ID
  • protected: true
  • request headers:

    {
    "Authorization": "Bearer TOKEN_STRING"
    }

  • request body:

    {
    "userId": USER_ID
    }

  • response {}

Contributing

• Report a bug
• Request a new feature
• Submit a pull request
• Checkout the Contributing guide

CHANGELOG

See CHANGELOG

License

MIT License

Author

Simplymichael (simplymichaelorji@gmail.com)