{"id":13528326,"url":"https://github.com/onury/accesscontrol","last_synced_at":"2025-04-09T02:16:17.854Z","repository":{"id":37665020,"uuid":"68128662","full_name":"onury/accesscontrol","owner":"onury","description":"Role and Attribute based Access Control for Node.js","archived":false,"fork":false,"pushed_at":"2024-06-21T03:26:21.000Z","size":435,"stargazers_count":2243,"open_issues_count":46,"forks_count":181,"subscribers_count":47,"default_branch":"master","last_synced_at":"2025-04-02T01:14:18.942Z","etag":null,"topics":["abac","access-control","acl","attributes","authorization","nodejs","permissions","rbac","roles","security"],"latest_commit_sha":null,"homepage":"https://onury.io/accesscontrol","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onury.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-13T16:56:53.000Z","updated_at":"2025-04-01T12:29:39.000Z","dependencies_parsed_at":"2024-09-30T19:40:25.863Z","dependency_job_id":null,"html_url":"https://github.com/onury/accesscontrol","commit_stats":{"total_commits":249,"total_committers":4,"mean_commits":62.25,"dds":"0.028112449799196804","last_synced_commit":"23543146e57702cc82687a08421091323cc2af4f"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onury%2Faccesscontrol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onury%2Faccesscontrol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onury%2Faccesscontrol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onury%2Faccesscontrol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onury","download_url":"https://codeload.github.com/onury/accesscontrol/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247962605,"owners_count":21024871,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["abac","access-control","acl","attributes","authorization","nodejs","permissions","rbac","roles","security"],"created_at":"2024-08-01T06:02:25.688Z","updated_at":"2025-04-09T02:16:17.830Z","avatar_url":"https://github.com/onury.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Authorization","security","Authorization Development"],"sub_categories":["\u003ca name=\"authZ-node\"\u003e\u003c/a\u003eNode.js"],"readme":"\u003ch1 align=\"center\"\u003e\n    \u003ca href=\"https://github.com/onury/accesscontrol\"\u003e\u003cimg width=\"465\" height=\"170\" src=\"https://raw.github.com/onury/accesscontrol/master/ac-logo.png\" alt=\"AccessControl.js\" /\u003e\u003c/a\u003e\n\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://travis-ci.org/onury/accesscontrol\"\u003e\u003cimg src=\"https://img.shields.io/travis/onury/accesscontrol.svg?branch=master\u0026style=flat-square\" alt=\"Build Status\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://coveralls.io/github/onury/accesscontrol?branch=master\"\u003e\u003cimg src=\"https://img.shields.io/coveralls/github/onury/accesscontrol/master.svg?style=flat-square\" alt=\"Coverage Status\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://david-dm.org/onury/accesscontrol\"\u003e\u003cimg src=\"https://david-dm.org/onury/accesscontrol.svg?style=flat-square\" alt=\"Dependencies\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://snyk.io/test/github/onury/accesscontrol\"\u003e\u003cimg src=\"https://snyk.io/test/github/onury/accesscontrol/badge.svg?style=flat-square\" alt=\"Known Vulnerabilities\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/onury/accesscontrol/graphs/commit-activity\"\u003e\u003cimg src=\"https://img.shields.io/maintenance/yes/2019.svg?style=flat-square\" alt=\"Maintained\" /\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://www.npmjs.com/package/accesscontrol\"\u003e\u003cimg src=\"http://img.shields.io/npm/v/accesscontrol.svg?style=flat-square\" alt=\"npm\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/onury/accesscontrol\"\u003e\u003cimg src=\"https://img.shields.io/github/release/onury/accesscontrol.svg?style=flat-square\" alt=\"Release\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/accesscontrol\"\u003e\u003cimg src=\"http://img.shields.io/npm/dm/accesscontrol.svg?style=flat-square\" alt=\"Downloads/mo.\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/onury/accesscontrol/blob/master/LICENSE\"\u003e\u003cimg src=\"http://img.shields.io/npm/l/accesscontrol.svg?style=flat-square\" alt=\"License\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.typescriptlang.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/written%20in-%20TypeScript%20-6575ff.svg?style=flat-square\" alt=\"TypeScript\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://onury.io/accesscontrol/?api=ac\"\u003e\u003cimg src=\"https://img.shields.io/badge/documentation-click_to_read-c27cf4.svg?documentation=click_to_read\u0026style=flat-square\" alt=\"Documentation\" /\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003csub\u003e© 2019, Onur Yıldırım (\u003cb\u003e\u003ca href=\"https://github.com/onury\"\u003e@onury\u003c/a\u003e\u003c/b\u003e).\u003c/sub\u003e\n\u003c/p\u003e\n\u003cbr /\u003e\n\n\n### Role and Attribute based Access Control for Node.js  \n\nMany [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).\n\nWith 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.\n\n\u003ctable\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth\u003e\u003ca href=\"#installation\"\u003eInstall\u003c/a\u003e\u003c/th\u003e\n      \u003cth\u003e\u003ca href=\"#guide\"\u003eExamples\u003c/a\u003e\u003c/th\u003e\n      \u003cth\u003e\u003ca href=\"#roles\"\u003eRoles\u003c/a\u003e\u003c/th\u003e\n      \u003cth\u003e\u003ca href=\"#actions-and-action-attributes\"\u003eActions\u003c/a\u003e\u003c/th\u003e\n      \u003cth\u003e\u003ca href=\"#resources-and-resource-attributes\"\u003eResources\u003c/a\u003e\u003c/th\u003e\n      \u003cth\u003e\u003ca href=\"#checking-permissions-and-filtering-attributes\"\u003ePermissions\u003c/a\u003e\u003c/th\u003e\n      \u003cth\u003e\u003ca href=\"#defining-all-grants-at-once\"\u003eMore\u003c/a\u003e\u003c/th\u003e\n      \u003cth\u003e\u003ca href=\"https://github.com/onury/accesscontrol/blob/master/docs/FAQ.md\"\u003eF.A.Q.\u003c/a\u003e\u003c/th\u003e\n      \u003cth\u003e\u003ca href=\"https://onury.io/accesscontrol?api=ac\"\u003eAPI Reference\u003c/a\u003e\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n\u003c/table\u003e\n\n## Core Features\n\n- Chainable, friendly API.  \ne.g. `ac.can(role).create(resource)`\n- Role hierarchical **inheritance**.\n- Define grants **at once** (e.g. from database result) or **one by one**.\n- Grant/deny permissions by attributes defined by **glob notation** (with nested object support).\n- Ability to **filter** data (model) instance by allowed attributes.\n- Ability to control access on **own** or **any** resources.\n- Ability to **lock** underlying grants model.\n- No **silent** errors.\n- **Fast**. (Grants are stored in memory, no database queries.)\n- Brutally **tested**.\n- TypeScript support.\n\n_In order to build on more solid foundations, this library (v1.5.0+) is completely re-written in TypeScript._\n\n## Installation\n\nwith [**npm**](https://www.npmjs.com/package/accesscontrol): `npm i accesscontrol --save`  \nwith [**yarn**](https://yarn.pm/accesscontrol): `yarn add accesscontrol`\n\n## Guide\n\n```js\nconst AccessControl = require('accesscontrol');\n// or:\n// import { AccessControl } from 'accesscontrol';\n```\n\n### Basic Example\n\nDefine roles and grants one by one.\n```js\nconst ac = new AccessControl();\nac.grant('user')                    // define new or modify existing role. also takes an array.\n    .createOwn('video')             // equivalent to .createOwn('video', ['*'])\n    .deleteOwn('video')\n    .readAny('video')\n  .grant('admin')                   // switch to another role without breaking the chain\n    .extend('user')                 // inherit role capabilities. also takes an array\n    .updateAny('video', ['title'])  // explicitly defined attributes\n    .deleteAny('video');\n\nconst permission = ac.can('user').createOwn('video');\nconsole.log(permission.granted);    // —\u003e true\nconsole.log(permission.attributes); // —\u003e ['*'] (all attributes)\n\npermission = ac.can('admin').updateAny('video');\nconsole.log(permission.granted);    // —\u003e true\nconsole.log(permission.attributes); // —\u003e ['title']\n```\n\n### Express.js Example\n\nCheck role permissions for the requested resource and action, if granted; respond with filtered attributes.\n\n```js\nconst ac = new AccessControl(grants);\n// ...\nrouter.get('/videos/:title', function (req, res, next) {\n    const permission = ac.can(req.user.role).readAny('video');\n    if (permission.granted) {\n        Video.find(req.params.title, function (err, data) {\n            if (err || !data) return res.status(404).end();\n            // filter data by permission attributes and send.\n            res.json(permission.filter(data));\n        });\n    } else {\n        // resource is forbidden for this user/role\n        res.status(403).end();\n    }\n});\n```\n\n## Roles\n\nYou can create/define roles simply by calling `.grant(\u003crole\u003e)` or `.deny(\u003crole\u003e)` methods on an `AccessControl` instance.  \n\n- Roles can extend other roles.\n\n```js\n// user role inherits viewer role permissions\nac.grant('user').extend('viewer');\n// admin role inherits both user and editor role permissions\nac.grant('admin').extend(['user', 'editor']);\n// both admin and superadmin roles inherit moderator permissions\nac.grant(['admin', 'superadmin']).extend('moderator');\n```\n\n- Inheritance is done by reference, so you can grant resource permissions before or after extending a role. \n\n```js\n// case #1\nac.grant('admin').extend('user') // assuming user role already exists\n  .grant('user').createOwn('video');\n\n// case #2\nac.grant('user').createOwn('video')\n  .grant('admin').extend('user');\n\n// below results the same for both cases\nconst permission = ac.can('admin').createOwn('video');\nconsole.log(permission.granted); // true\n```\n\nNotes on inheritance:  \n- A role cannot extend itself.\n- Cross-inheritance is not allowed.  \ne.g. `ac.grant('user').extend('admin').grant('admin').extend('user')` will throw.\n- 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')`\n\n## Actions and Action-Attributes\n\n[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*.\n\nFor 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.\n\n\u003ctable\u003e\n    \u003cthead\u003e\n        \u003ctr\u003e\n            \u003cth\u003eAction\u003c/th\u003e\n            \u003cth\u003ePossession\u003c/th\u003e\n        \u003c/tr\u003e\n    \u003c/thead\u003e\n    \u003ctbody\u003e\n        \u003ctr\u003e\n            \u003ctd rowspan=\"2\"\u003e\n            \u003cb\u003eC\u003c/b\u003ereate\u003cbr /\u003e\n            \u003cb\u003eR\u003c/b\u003eead\u003cbr /\u003e\n            \u003cb\u003eU\u003c/b\u003epdate\u003cbr /\u003e\n            \u003cb\u003eD\u003c/b\u003eelete\u003cbr /\u003e\n            \u003c/td\u003e\n            \u003ctd\u003eOwn\u003c/td\u003e\n            \u003ctd\u003eThe C|R|U|D action is (or not) to be performed on own resource(s) of the current subject.\u003c/td\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\n            \u003ctd\u003eAny\u003c/td\u003e\n            \u003ctd\u003eThe C|R|U|D action is (or not) to be performed on any resource(s); including own.\u003c/td\u003e\n        \u003c/tr\u003e   \n    \u003c/tbody\u003e\n\u003c/table\u003e\n\n```js\nac.grant('role').readOwn('resource');\nac.deny('role').deleteAny('resource');\n```\n\n_Note that **own** requires you to also check for the actual possession. See [this](https://github.com/onury/accesscontrol/issues/14#issuecomment-328316670) for more._\n\n## Resources and Resource-Attributes\n\nMultiple 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.  \n\nThis is possible by resource attributes. You can use Glob notation to define allowed or denied attributes.\n\nFor example, we have a `video` resource that has the following attributes: `id`, `title` and `runtime`.\nAll attributes of *any* `video` resource can be read by an `admin` role:\n```js\nac.grant('admin').readAny('video', ['*']);\n// equivalent to:\n// ac.grant('admin').readAny('video');\n```\nBut the `id` attribute should not be read by a `user` role.  \n```js\nac.grant('user').readOwn('video', ['*', '!id']);\n// equivalent to:\n// ac.grant('user').readOwn('video', ['title', 'runtime']);\n```\n\nYou can also use nested objects (attributes).\n```js\nac.grant('user').readOwn('account', ['*', '!record.id']);\n```\n\n## Checking Permissions and Filtering Attributes\n\nYou can call `.can(\u003crole\u003e).\u003caction\u003e(\u003cresource\u003e)` on an `AccessControl` instance to check for granted permissions for a specific resource and action.\n\n```js\nconst permission = ac.can('user').readOwn('account');\npermission.granted;       // true\npermission.attributes;    // ['*', '!record.id']\npermission.filter(data);  // filtered data (without record.id)\n```\nSee [express.js example](#expressjs-example).\n\n## Defining All Grants at Once\n\nYou can pass the grants directly to the `AccessControl` constructor.\nIt accepts either an `Object`:\n\n```js\n// This is actually how the grants are maintained internally.\nlet grantsObject = {\n    admin: {\n        video: {\n            'create:any': ['*', '!views'],\n            'read:any': ['*'],\n            'update:any': ['*', '!views'],\n            'delete:any': ['*']\n        }\n    },\n    user: {\n        video: {\n            'create:own': ['*', '!rating', '!views'],\n            'read:own': ['*'],\n            'update:own': ['*', '!rating', '!views'],\n            'delete:own': ['*']\n        }\n    }\n};\nconst ac = new AccessControl(grantsObject);\n```\n... or an `Array` (useful when fetched from a database):\n```js\n// grant list fetched from DB (to be converted to a valid grants object, internally)\nlet grantList = [\n    { role: 'admin', resource: 'video', action: 'create:any', attributes: '*, !views' },\n    { role: 'admin', resource: 'video', action: 'read:any', attributes: '*' },\n    { role: 'admin', resource: 'video', action: 'update:any', attributes: '*, !views' },\n    { role: 'admin', resource: 'video', action: 'delete:any', attributes: '*' },\n\n    { role: 'user', resource: 'video', action: 'create:own', attributes: '*, !rating, !views' },\n    { role: 'user', resource: 'video', action: 'read:any', attributes: '*' },\n    { role: 'user', resource: 'video', action: 'update:own', attributes: '*, !rating, !views' },\n    { role: 'user', resource: 'video', action: 'delete:own', attributes: '*' }\n];\nconst ac = new AccessControl(grantList);\n```\nYou can set grants any time...\n```js\nconst ac = new AccessControl();\nac.setGrants(grantsObject);\nconsole.log(ac.getGrants());\n```\n...unless you lock it:\n```js\nac.lock().setGrants({}); // throws after locked\n```\n\n## Documentation\n\nYou can read the full [**API reference**][docs] with lots of details, features and examples.  \nAnd more at the [F.A.Q. section][faq].\n\n## Change-Log\n\nSee [CHANGELOG][changelog].\n\n## Contributing\n\nClone original project:\n\n```sh\ngit clone https://github.com/onury/accesscontrol.git\n```\n\nInstall dependencies:\n\n```sh\nnpm install\n```\n\nAdd tests to relevant file under [/test](test/) directory and run:  \n\n```sh\nnpm run build \u0026\u0026 npm run cover\n```\n\nUse included `tslint.json` and `editorconfig` for style and linting.  \nTravis build should pass, coverage should not degrade.\n\n## License\n\n[**MIT**][license].\n\n[docs]:http://onury.io/accesscontrol/?api=ac\n[faq]:http://onury.io/accesscontrol/?content=faq\n[rbac]:https://en.wikipedia.org/wiki/Role-based_access_control\n[abac]:https://en.wikipedia.org/wiki/Attribute-Based_Access_Control\n[crud]:https://en.wikipedia.org/wiki/Create,_read,_update_and_delete\n[nist-paper]:http://csrc.nist.gov/groups/SNS/rbac/documents/kuhn-coyne-weil-10.pdf\n[changelog]:https://github.com/onury/accesscontrol/blob/master/CHANGELOG.md\n[license]:https://github.com/onury/accesscontrol/blob/master/LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonury%2Faccesscontrol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonury%2Faccesscontrol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonury%2Faccesscontrol/lists"}