Bifröst, Access control for node.js, as simple as that. Suited for building SaaS apps due to the concept of scope.

Note: Works with MongoDB only (more databases coming, you're welcome to contribute)

Installation

Usage

Import the library to your project and create an instance

const Bifrost = require ( ' node-bifrost ' ) ; const bifrost = new Bifrost ( ' mongodb://localhost:27017/mydb ' , { cb ( ) { } , err_cb ( err ) { } , } ) ;

Define ACL

bifrost . allow ( ' librarian ' , ' books ' , ' create ' ) ; bifrost . allow ( ' librarian ' , ' books ' , ' read ' ) ; bifrost . allow ( ' librarian ' , ' books ' , ' update ' ) ; bifrost . allow ( ' librarian ' , ' books ' , ' delete ' ) ; bifrost . allow ( ' librarian ' , ' books ' , [ ' create ' , ' read ' , ' update ' , ' delete ' ] ) ; bifrost . allow ( ' member ' , ' books ' , ' read ' ) ; bifrost . allow ( ' member ' , ' reviews ' , [ ' create ' , ' read ' , ' update ' ] ) ;

Here we allowed the librarian role to create , read , update and delete the books resource.

We allowed the member role to just read the books and create , read and update the reviews resource.

The roles and resources are created implicitly, i.e. they are automatically created if they don't exist.

Assign roles to users

Assume that we have three users, john , rajesh and alfred .

john is a librarian rajesh is a member alfred is both a librarian and a member

We can implement this as follows:

await bifrost . assign ( ' john ' , ' librarian ' ) ; await bifrost . assign ( ' rajesh ' , ' member ' ) ; await bifrost . assign ( ' alfred ' , ' librarian ' ) ; await bifrost . assign ( ' alfred ' , ' member ' ) ;

Finally, check for permission

await bifrost . allowed ( ' john ' , ' books ' , ' create ' ) ; await bifrost . allowed ( ' john ' , ' reviews ' , ' update ' ) ; await bifrost . allowed ( ' rajesh ' , ' books ' , ' delete ' ) ; await bifrost . allowed ( ' rajesh ' , ' reviews ' , ' read ' ) ; await bifrost . allowed ( ' alfred ' , ' books ' , ' update ' ) ; await bifrost . allowed ( ' alfred ' , ' reviews ' , ' create ' ) ; await bifrost . allowed ( ' alfred ' , ' issues ' , ' create ' ) ;

Note: Every action on every resource is denied to every user unless explicitly allowed.

Wildcard support

You can use * to give wildcard permission. for example,

bifrost . allow ( ' accountant ' , ' fees ' , ' * ' ) ; bifrost . allow ( ' vice-principal ' , ' * ' , ' update ' ) ; bifrost . allow ( ' principal ' , ' * ' , ' * ' ) ;

Concept of scope

In some applications, especially SaaS, there is a need to implement a multi-tenancy architecture. In those apps, a user should not be able access resources belonging to other tenants.

For example, assume we have a library management system as a SaaS offering. There will be multiple libraries, and every library will have its own set of users, even though the roles are same across schools (i.e. Librarian, Accountant, Member etc.). We wouldn't want, for example, the librarian of Library A to have librarian privileges at Library B.

Here comes in Scope. When assigning role using bifrost.assign , you can pass a third argument called scope . e.g.

bifrost . assign ( ' john ' , ' librarian ' , ' library-a ' ) ;

Now, john is declared as a librarian of only the library-a scope. When checking for permission using bifrost.allowed , you can pass a fourth argument called scope . e.g.

await bifrost . allowed ( ' john ' , ' books ' , ' create ' , ' library-a ' ) ; await bifrost . allowed ( ' john ' , ' books ' , ' create ' , ' library-b ' ) ;

Scope hierarchy

Sometimes there is a need to implement hierarchy for scopes. For example, lets say there are several kingdoms under an empire. Then the emperor of the empire should have access over the kindgoms but not the other way around i.e. the kings of the kingdoms shouldn't have power over the empire.

bifrost . allow ( ' emperor ' , ' * ' , ' * ' ) ; bifrost . allow ( ' king ' , ' subjects ' , ' * ' ) ; await bifrost . assign ( ' aurangzeb ' , ' emperor ' , ' mughal-empire ' ) ; await bifrost . assign ( ' shivaji ' , ' king ' , ' maratha-kingdom ' ) ; await bifrost . assign ( ' godapani ' , ' king ' , ' ahom-kingdom ' ) ; await bifrost . addParentScope ( ' maratha-kingdom ' , ' mughal-empire ' ) ; await bifrost . allowed ( ' aurangzeb ' , ' finance ' , ' update ' , ' maratha-kingdom ' ) ; await bifrost . allowed ( ' aurangzeb ' , ' finance ' , ' update ' , ' ahom-kingdom ' ) ;

Note: The hierarchy is a transitive relation. i.e. If A is a parent of B, and B is a parent of C, then A is also parent of C.