hakki

An opinionated, modern, and scalable alternative to node_acl.

Features

• Provides the same functionality with node_acl except for middleware
• Works with promises and async/await out of the box instead of callbacks
• Requires and works with mongoose
• Built specifically for MongoDB with aggregation features
• Scalable architecture to support millions of operations
• Supports wildcard resources for a lighter database

Migrating from v1 to v2

As of version 2 hakki runs with an in-memory backend by default. This means mongoose is an optional dependency, and one can use hakki in projects that don't use MongoDB. This is particularly useful for unit testing purposes where hakki is required but running MongoDB isn't feasible.

In-memory backend is now the default and users are required to import and then call hakki with an options object. Check out Providing mongoose for instructions on how to use the mongoose backend. Simply requiring hakki without calling it with an options object will result in the default behavior of using in-memory backend.

Motivation

node_acl is great until you need to scale it with MongoDB. It's originally built for redis, and MongoDB backend is problematic at scale where you modify the same document that holds 200,000 properties in it. The fact that it works on a MongoDB connection makes it hard to operate it with clusters, as well.

hakki addresses these concerns, respects your MongoDB connection logic with mongoose, and offers a modern, scalable experience both during development and for your infrastructure.

Usage

Installation

npm install hakki

Providing mongoose

Since mongoose and MongoDB in general has a lot of connection options, and hakki only wants to focus on ACL, it expects you to have a working mongoose connection. It will create four collections in the database of your connection: acl_allows, acl_role_parents, acl_role_users and acl_users.

Just require mongoose and connect to database however you wish:

const mongoose = require('mongoose')
const hakki = require('hakki')({ backend: 'mongoose' })

mongoose.connect('mongodb://localhost:27017/acl', { useNewUrlParser: true })

After this point, hakki is ready to use.

Example

await hakki.allow(['developer', 'guest'], ['branches', 'tags'], ['list', 'fetch'])
await hakki.allow('master', ['branches', 'tags'], 'push')
await hakki.addRoleParents('master', ['developer', 'guest'])
await hakki.addUserRoles('user1', 'master')

let perms = await hakki.allowedPermissions('user1', ['branches', 'tags'])
console.log(perms)
/*
{
tags: [ 'fetch', 'push', 'list' ],
branches: [ 'fetch', 'push', 'list' ]
}
*/

API

Hakki supports the same API footprint as node_acl with the following functions:

• addUserRoles

• removeUserRoles

• userRoles

• roleUsers

• hasRole

• removeRole

• allow

• removeAllow

• allowedPermissions

• isAllowed

• areAnyRolesAllowed

• whatResources

• removeResource

• addRoleParents

• removeRoleParents

• isRole

• getDistinctRoles

• getDistinctPermissions

  isRole is a new API that mimicks the behavior of a hasRole call for a user for parent roles as well. Technically when one uses addRoleParents, a child role attains an is-a relationship with the parent. However, this isn't reflected in userRoles or hasRole, but in isAllowed or allowedPermissions. isRole is introduced to at least partially cover for this.

  getDistinctRoles & getDistinctPermissions are added as helper functions to be able to check the possible options before creating new roles and permissions.

All the functions use promises and no callbacks. So if you rely on callbacks with node_acl, then you will have to refactor your code to use promises, and better yet, async / await.

Also, currently there's no Express middleware support.

Please refer to node_acl's README for detailed documentation.

MIT License

Copyright (c) 2018 Armagan Amcalar

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.