Accesscontrol
Role and Attribute based Access Control for Node.js
Install / Use
/learn @onury/AccesscontrolREADME
Role and Attribute based Access Control for Node.js
Many [RBAC][rbac] (Role-Based Access Control) implementations differ, but the basics is widely adopted since it simulates real life role (job) assignments. But while data is getting more and more complex; you need to define policies on resources, subjects or even environments. This is called [ABAC][abac] (Attribute-Based Access Control).
With the idea of merging the best features of the two (see this [NIST paper][nist-paper]); this library implements RBAC basics and also focuses on resource and action attributes.
<table> <thead> <tr> <th><a href="#installation">Install</a></th> <th><a href="#guide">Examples</a></th> <th><a href="#roles">Roles</a></th> <th><a href="#actions-and-action-attributes">Actions</a></th> <th><a href="#resources-and-resource-attributes">Resources</a></th> <th><a href="#checking-permissions-and-filtering-attributes">Permissions</a></th> <th><a href="#defining-all-grants-at-once">More</a></th> <th><a href="https://github.com/onury/accesscontrol/blob/master/docs/FAQ.md">F.A.Q.</a></th> <th><a href="https://onury.io/accesscontrol?api=ac">API Reference</a></th> </tr> </thead> </table>Core Features
- Chainable, friendly API.
e.g.ac.can(role).create(resource) - Role hierarchical inheritance.
- Define grants at once (e.g. from database result) or one by one.
- Grant/deny permissions by attributes defined by glob notation (with nested object support).
- Ability to filter data (model) instance by allowed attributes.
- Ability to control access on own or any resources.
- Ability to lock underlying grants model.
- No silent errors.
- Fast. (Grants are stored in memory, no database queries.)
- Brutally tested.
- TypeScript support.
In order to build on more solid foundations, this library (v1.5.0+) is completely re-written in TypeScript.
Installation
with npm: npm i accesscontrol --save
with yarn: yarn add accesscontrol
Guide
const AccessControl = require('accesscontrol');
// or:
// import { AccessControl } from 'accesscontrol';
Basic Example
Define roles and grants one by one.
const ac = new AccessControl();
ac.grant('user') // define new or modify existing role. also takes an array.
.createOwn('video') // equivalent to .createOwn('video', ['*'])
.deleteOwn('video')
.readAny('video')
.grant('admin') // switch to another role without breaking the chain
.extend('user') // inherit role capabilities. also takes an array
.updateAny('video', ['title']) // explicitly defined attributes
.deleteAny('video');
const permission = ac.can('user').createOwn('video');
console.log(permission.granted); // —> true
console.log(permission.attributes); // —> ['*'] (all attributes)
permission = ac.can('admin').updateAny('video');
console.log(permission.granted); // —> true
console.log(permission.attributes); // —> ['title']
Express.js Example
Check role permissions for the requested resource and action, if granted; respond with filtered attributes.
const ac = new AccessControl(grants);
// ...
router.get('/videos/:title', function (req, res, next) {
const permission = ac.can(req.user.role).readAny('video');
if (permission.granted) {
Video.find(req.params.title, function (err, data) {
if (err || !data) return res.status(404).end();
// filter data by permission attributes and send.
res.json(permission.filter(data));
});
} else {
// resource is forbidden for this user/role
res.status(403).end();
}
});
Roles
You can create/define roles simply by calling .grant(<role>) or .deny(<role>) methods on an AccessControl instance.
- Roles can extend other roles.
// user role inherits viewer role permissions
ac.grant('user').extend('viewer');
// admin role inherits both user and editor role permissions
ac.grant('admin').extend(['user', 'editor']);
// both admin and superadmin roles inherit moderator permissions
ac.grant(['admin', 'superadmin']).extend('moderator');
- Inheritance is done by reference, so you can grant resource permissions before or after extending a role.
// case #1
ac.grant('admin').extend('user') // assuming user role already exists
.grant('user').createOwn('video');
// case #2
ac.grant('user').createOwn('video')
.grant('admin').extend('user');
// below results the same for both cases
const permission = ac.can('admin').createOwn('video');
console.log(permission.granted); // true
Notes on inheritance:
- A role cannot extend itself.
- Cross-inheritance is not allowed.
e.g.ac.grant('user').extend('admin').grant('admin').extend('user')will throw. - A role cannot (pre)extend a non-existing role. In other words, you should first create the base role. e.g.
ac.grant('baseRole').grant('role').extend('baseRole')
Actions and Action-Attributes
[CRUD][crud] operations are the actions you can perform on a resource. There are two action-attributes which define the possession of the resource: own and any.
For example, an admin role can create, read, update or delete (CRUD) any account resource. But a user role might only read or update its own account resource.
ac.grant('role').readOwn('resource');
ac.deny('role').deleteAny('resource');
Note that own requires you to also check for the actual possession. See this for more.
Resources and Resource-Attributes
Multiple roles can have access to a specific resource. But depending on the context, you may need to limit the contents of the resource for specific roles.
This is possible by resource attributes. You can use Glob notation to define allowed or denied attributes.
For example, we have a video resource that has the following attributes: id, title and runtime.
All attributes of any video resource can be read by an admin role:
ac.grant('admin').readAny('video', ['*']);
// equivalent to:
// ac.grant('admin').readAny('video');
But the id attribute should not be read by a user role.
ac.grant('user').readOwn('video', ['*', '!id']);
// equivalent to:
// ac.grant('user').readOwn('video', ['title', 'runtime']);
You can also use nested objects (attributes).
ac.grant('user').readOwn('account', ['*', '!record.id']);
Checking Permissions and Filtering Attributes
You can call .can(<role>).<action>(<resource>) on an AccessControl instance to check for granted permissions for a specific resource and action.
const permission = ac.can('user').readOwn('account');
permission.granted; // true
permission.attributes; // ['*', '!record.id']
permission.filter(data
Related Skills
healthcheck
334.1kHost security hardening and risk-tolerance configuration for OpenClaw deployments
node-connect
334.1kDiagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps
prose
334.1kOpenProse VM skill pack. Activate on any `prose` command, .prose files, or OpenProse mentions; orchestrates multi-agent workflows.
frontend-design
82.1kCreate distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
