A powerful, operation based, access and permission middleware for Express.

Downloads in past


201.0.24 years ago4 years agoMinified + gzip package size for express-guard in KB


Express Guard
Build Status Coverage Status

Express Guard (express-guard) allows you to manage the requests made to your express server. It's built to be simple and has a powerful syntax.
With Express Guard, you only have to define allowed Features (such as 'viewPosts', 'removePost'...) for different user Roles (such as 'admin', 'postOwner').
Then when a request is made to your server, the middleware will check the corresponding access policy and return a result based on the user's permissions.

Getting started

  1. Import Guard and define your roles

const Guard = require('express-guard');

const authenticated = new Guard.Role('authenticated', {
  can: ['viewPost', 'editPost', 'logout'],
  func: async (req) => {
    // Perform some logic to compute your role policy.
    const result = await Promise.resolve('someresult');
    if (result === 'someresult') {
      return true; // will have role 'authenticated'
    return false; // will not match this role

const guest = new Guard.Role('guest', {
  can: ['login'], // they can't do anything except login
  func: async (req) => {
    // because we define roles one by one, we can use
    // a previously defined role to compute this one.
    // Here a guest is someone who is not authenticated.
    const res = await !authenticated.func(req);
    return res;

// Because we define roles one by one, we can use
// a previously defined role to compute this one.
const admin = new Guard.Role('admin', {
  can: ['*'], // An admin can do everything!
  func(req) { return unauthenticated.func(req); },

  1. Add your roles to guard instance

const guard = new Guard();

// Add roles one by one

// Or using an array
guard.roles = [authenticated, admin];

  1. Use guard middleware

const app = express();
const router = express.Router();

// example 1
// regarding our config both admin and authenticated users
// have access to this route.
guard.requireAny('viewPost', '*'),
(req, res) => {
  // your route handler

// example 2
// regarding our config, only admin has access to this route
guard.requireAny('removePost', '*'),
(req, res) => {
  // your route handler

Error handling

Since Guard acts as a middleware it calls next(err). The err argument is nothing but an Error() instance.
This instance contains a property called isGuard which is a Boolean. It can help you to catch the error in an error handler middleware as follow:
// Your error handler file
const errorHandler = (err, req, res, next) => {
  if (err.isGuard) {
    // custom logic if error comes from Guard.
    // Yout want probably send a forbidden status
    // with a custom message. Something like:
    // res.status = 403;
    // res.send({ message: 'You can not access this ressource' });
  // Other stuff here.