Welcome to node-firewall’s documentation!¶

https://travis-ci.org/plouc/node-firewall.png

https://coveralls.io/repos/plouc/node-firewall/badge.png?branch=master

https://david-dm.org/plouc/node-firewall.png

https://badge.fury.io/js/node-firewall.png

The firewall module helps to handle authorization based on roles and init authentication process.

It exposes three main components:

A FirewallMap
A Firewall
A middleware to easily plug it to express

This module was build to work in conjunction with passport which is in charge of user authentication.

Contents:

Firewall¶

A firewall have a path, this path determine if it should apply on an incoming request by checking that the request url match it.

Then, if the firewall handle the request, it checks if it have an available rule to apply to it by checking its url and optionally its http method.

A rule is composed of a path (a RegExp), a list of roles (an array) authorized to access the resource, and, as seen previously an optional http method.

FirewallMap¶

A FirewallMap contains one or more firewalls, you’ll often have a single firewall in your application, but if you have more specific needs, you have the ability to add another one.

Usage¶

You can configure a map by using the API.

var FirewallMap = require('node-firewall').FirewallMap,
    Firewall    = require('node-firewall').Firewall;

var map = new FirewallMap();

// create a new firewall
var fw = new Firewall('fw.main', '^/');
fw.add('^/login', null); // allow unauthenticated access on /login
fw.add('^/', 'user');    // all other resources require `user` role

// add it to the map
map.add(fw);

// ...

map.check(req, res, next);

You can also configure the FirewallMap using a plain old javascript object.

var FirewallMap = require('node-firewall').FirewallMap;

var map = new FirewallMap();
map.fromConfig({
    'fw.main': {
        path:  '^/',
        rules: [
            [ '^/login', null   ],
            [ '^/',      ['role', 'user'] ]
        ]
    }
});

// ...

The middleware¶

The module provides an easy way to integrate it to an existing express based application.

Usage¶

var firewall = require('node-firewall');

// configure the firewalls
firewall.map.fromConfig({
    'fw.main': {
        path:  '^/',
        rules: [
            [ '^/login', null   ],
            [ '^/',      ['role', 'user'] ]
        ]
    }
});

// plug it to the application
firewall.use(app);