@techteamer/acl

The ACL Package
=============

* Install
* Usage options
* ACLService
* Define rules
* Create rules
* Import rules
* Setup logging
* Public methods
* ACLManager
* Import ACLService
* Import ACL config
* Checking roles and rules
* Usage example
* Setup logging
* Public methods
* Unit tests

Install

``
$ npm i @techteamer/acl --save
`

Usage options

After installing the package there are two ways you can use it.

$3

`
accept.rule
`

Start your rule with ! flag to create a reject rule

`
!reject.rule
`

Start your role or rule with @ flag to ignore it

`
@ignored.rule
`

$3

`js
const { ACLService } = require('@techteamer/acl')

// create ACL instance
const acl = new ACLService()

// create a role
acl.createRole('admin')

// create an accept rule
acl.createRule('users.create', 'admin')

// check rule access; returns true
acl.isAllowed('users.create', 'admin')
`

$3

`js
const { ACLService } = require('@techteamer/acl')

// create ACL instance
const acl = new ACLService()

// import roles and rules
acl.import({
"admin":[
"users.*",
"system.*"
],
"supervisor":[
"users.*",
"!users.delete",
"system.*",
"!system.shutdown",
"@ignored"
],
"@ignored":[
"users.list"
]
})

// returns true
acl.isAllowed('users.create', 'supervisor')

// returns false *
acl.isAllowed('users.delete', 'supervisor')
`

$3

__Logging disabled by default! ( acl.logger = false )__

Single callback as logger

`js
acl.logger = function(level, message){
// available log levels:
// - debug: verbose process messages
// - info: general informations
// - warn: warning messages (not critical)
// - error: error messages (critical)
...
}
`

Object (or any class instance) with public methods

`js
acl.logger = {
info: function(message){ ... },
warn: function(message){ ... },
...
}
`

Public methods

$3

Import roles and rules as an object. Import is an append based method, if you want to overwrite previous rules, first use the clear method. After import completed, result cache automatically cleared.

__Arguments__

`js
settings {Object} {
role {String}: rules {Array},
...
}
`

$3

Create a single role.\
Throws an ACLError when role already exists.

__Arguments__

`js
name {String} Role name.
`

$3

Create a single accept or reject rule. After rule created, result cache automatically cleared.\
Throws an ACLError when rule already exists in provided role or role not exists.

__Arguments__

`js
name {String} Rule name.
role {String} Role name.
`

$3

Returns with true, when role exists, otherwise false.

__Arguments__

`js
name {String} Role name.
`

$3

Returns the list of available roles as a string array.

$3

Returns with true, when rule accepted, otherwise false. All results are stored in the result cache!\
Throws an ACLError when role not exists.

__Arguments__

`js
rule {String} Rule name.
role {String} Role name.
`

$3

Returns with true, when all rule accepted, otherwise false. If access list is empty, returns false. All results are stored in the result cache! Throws an ACLError when role not exists.

__Arguments__

`js
rules {Array} Rule names.
role {String} Role name.
`

$3

Returns with true, when any rule accepted, otherwise false. If access list is empty, returns false. All results are stored in the result cache! Throws an ACLError when role not exists.

__Arguments__

`js
rules {Array} Rule names.
role {String} Role name.
`

$3

Clear all results from result cache.

$3

Clear all roles, rules and results from ACL instance.

ACLManager

$3

`js
const { ACLManager, ACLService } = require('@techteamer/acl')

// create ACL instance
const acl = new ACLService()

// import roles and rules to ACLService
acl.import({
"admin":[
"users.*",
"system.*"
],
"supervisor":[
"users.*",
"!users.delete",
"system.*",
"!system.shutdown",
"@ignored"
],
"@ignored":[
"users.list"
]
})

// Import ACLService to ACLManager:
const acm = new ACLManager()
acm.import(acl)

// Use the ACLManager instead of the ACLService
// returns true
acm.isAllowed('users.create', 'supervisor')

// returns false
acm.isAllowed('users.delete', 'supervisor')
`

$3

`js
const { ACLManager } = require('@techteamer/acl')

// Import ACL config directly into the ACLManager:
const acm = new ACLManager()
acm.importConfig({
"admin":[
"users.*",
"system.*"
],
"supervisor":[
"users.*",
"!users.delete",
"system.*",
"!system.shutdown",
"@ignored"
],
"@ignored":[
"users.list"
]
})

// Use the ACLManager instead of the ACLService
// returns true
acm.isAllowed('users.create', 'supervisor')

// returns false
acm.isAllowed('users.delete', 'supervisor')
`


$3

To check for roles and rules you can use the same methods:
- isAllowed(rule, role)
- areAllowed(rules, role)
- anyAllowed(rules, role)

#### Usage example:
`js
const { ACLManager } = require('@techteamer/acl')

// Import ACL config directly into the ACLManager:
const acm = new ACLManager()
// Lower priority
acm.importConfig({
"admin":[
// Any rule listed here will be ignored...
"system.shutdown"
],
"supervisor":[
// Every 'supervisor' role check will fallback to this rule list:
"users.*",
"!users.delete"
]
})

// Higher priority (added later)
acm.importConfig({
"admin":[
// Rules here will take precedence over the ones listed in the first ACL config's 'admin' role section.
"users.*",
]
})

// returns true
acm.isAllowed('users.create', 'supervisor') // Fallback
acm.isAllowed('users.delete', 'admin') // No fallback

// returns false
acm.isAllowed('users.delete', 'supervisor') // Fallback
acm.isAllowed('system.shutdown', 'admin') // No fallback!!! Only rule in admin role is: 'users.*'

`

$3

__Logging disabled by default!__

> NOTE: The logger will be set to all managed ACLService instances as well!

Single callback as logger

`js
acm.logger = function(level, message) {
// available log levels:
// - debug: verbose process messages
// - info: general informations
// - warn: warning messages (not critical)
// - error: error messages (critical)
...
}
`

Object (or any class instance) with public methods

`js
acm.logger = {
info: function(message){ ... },
warn: function(message){ ... },
...
}
`

Public methods

The ACL manager has the same API as the ACLService except these methods:
- createRole
- createRule
- clearResultCache

Build

`
yarn run build
`

Unit tests

To run the test suites, first install the dependencies, then run the tests:

`
$ npm install
$ npm test
``