{"id":23764445,"url":"https://github.com/chaqchase/lyrol","last_synced_at":"2026-03-07T00:30:54.811Z","repository":{"id":65876952,"uuid":"601688990","full_name":"chaqchase/lyrol","owner":"chaqchase","description":"lyrol is fully featured role management library for node.js. It allows you to easily create roles and manage permissions and authorize your users, and it supports express, koa, next.js and react","archived":false,"fork":false,"pushed_at":"2023-04-08T17:09:13.000Z","size":247,"stargazers_count":12,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-09-05T08:46:34.736Z","etag":null,"topics":["acl","authentication","authorization","nodejs","permissions","role","rolemanagement"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/lyrol","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/chaqchase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2023-02-14T15:55:09.000Z","updated_at":"2025-05-07T12:51:02.000Z","dependencies_parsed_at":"2023-07-06T14:00:30.180Z","dependency_job_id":null,"html_url":"https://github.com/chaqchase/lyrol","commit_stats":{"total_commits":30,"total_committers":2,"mean_commits":15.0,"dds":"0.19999999999999996","last_synced_commit":"f43aa85138a9fbc12cdd62242f7978457a370d95"},"previous_names":["chaqchase/lyrol"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/chaqchase/lyrol","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaqchase%2Flyrol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaqchase%2Flyrol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaqchase%2Flyrol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaqchase%2Flyrol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chaqchase","download_url":"https://codeload.github.com/chaqchase/lyrol/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaqchase%2Flyrol/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30204154,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"ssl_error","status_checked_at":"2026-03-06T18:57:34.882Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["acl","authentication","authorization","nodejs","permissions","role","rolemanagement"],"created_at":"2024-12-31T22:18:11.468Z","updated_at":"2026-03-07T00:30:54.791Z","avatar_url":"https://github.com/chaqchase.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lyrol - A role management library for node.js\n\n[![Rate this package](https://badges.openbase.com/js/rating/lyrol.svg?style=openbase\u0026token=FjWdZk+GM9XSAbnKGtvMPP4+B452l84xBXsBZnQFHxw=)](https://openbase.com/js/lyrol?utm_source=embedded\u0026utm_medium=badge\u0026utm_campaign=rate-badge)\n![CI](https://github.com/triyanox/lyrol/workflows/CI/badge.svg)\n[![npm version](https://badge.fury.io/js/lyrol.svg)](https://badge.fury.io/js/lyrol)\n\nLyrol is fully featured role management library for node.js. It allows you to easily create roles and manage permissions and authorize your users, and it supports various frameworks like\n`express`, `koa` and `next.js`.\n\n## Table of Contents\n\n- [lyrol - A role management library for node.js](#lyrol---a-role-management-library-for-nodejs)\n  - [Table of Contents](#table-of-contents)\n  - [Installation](#installation)\n  - [Create Roles](#create-roles)\n    - [Basic Usage](#basic-usage)\n    - [Extend a role](#extend-a-role)\n    - [Overwrite a permission in extended role](#overwrite-a-permission-in-extended-role)\n    - [Save the role to a database](#save-the-role-to-a-database)\n    - [Load the role from a database](#load-the-role-from-a-database)\n  - [Authorize a user](#authorize-a-user)\n    - [Express Middleware](#express-middleware)\n    - [Koa Middleware](#koa-middleware)\n    - [Next.js Middleware](#nextjs-middleware)\n  - [LICENSE](#license)\n\n## Installation\n\nYou can install lyrol using npm:\n\n```bash\nnpm install lyrol\n```\n\nor yarn:\n\n```bash\nyarn add lyrol\n```\n\n## Create Roles\n\n### Basic Usage\n\n```ts\nimport { Role } from 'lyrol';\n\nconst role = new Role([\n  {\n    resource: 'user',\n    scopes: 'cr---',\n  },\n  {\n    resource: 'post',\n    scopes: 'crudl',\n  },\n  {\n    resource: 'comment',\n    scopes: 'crudl',\n  },\n]);\n\nconsole.log(role.canCreate('user')); // true\nconsole.log(role.canRead('user')); // true\nconsole.log(role.canUpdate('user')); // false\nconsole.log(role.can('create', 'user')); // true\n```\n\n### Extend a role\n\nYou can extend a role by using the `extend` method. This will create a new role with the same permissions as the original role, plus any additional permissions you specify.\n\n```ts\nimport { Role } from 'lyrol';\n\nconst role = new Role([\n  {\n    resource: 'user',\n    scopes: 'cr---',\n  },\n  {\n    resource: 'post',\n    scopes: 'crudl',\n  },\n  {\n    resource: 'comment',\n    scopes: 'crudl',\n  },\n]);\n\nconst admin = new Role().extend(role).addPermissions([\n  {\n    resource: 'group',\n    scopes: 'crudl',\n  },\n]);\n```\n\nor you can pass an array as a second argument to the `extend` method instead of using the `addPermissions` method.\n\n```ts\nimport { Role } from 'lyrol';\n\nconst role = new Role([\n  {\n    resource: 'user',\n    scopes: 'cr---',\n  },\n  {\n    resource: 'post',\n    scopes: 'crudl',\n  },\n  {\n    resource: 'comment',\n    scopes: 'crudl',\n  },\n]);\n\nconst admin = new Role().extend(role, [\n  {\n    resource: 'group',\n    scopes: 'crudl',\n  },\n]);\n```\n\n### Overwrite a permission in extended role\n\nThe `extend` method takes optional options as a second parameter. You can use the `overwrite` option to overwrite a permission in the extended role add pass the new permissions as the `permissions` .\n\n```ts\nimport { Role } from 'lyrol';\n\nconst role = new Role([\n  {\n    resource: 'user',\n    scopes: 'cr---',\n  },\n  {\n    resource: 'post',\n    scopes: 'crudl',\n  },\n  {\n    resource: 'comment',\n    scopes: 'crudl',\n  },\n]);\n\nconst admin = new Role().extend(role, {\n  overwrite: true,\n  permissions: [\n    {\n      resource: 'user',\n      scopes: 'crudl',\n    },\n  ],\n});\n\nconsole.log(admin.canDelete('user')); // true\n```\n\n### Save the role to a database\n\nYou can save the role to a database by using the `toJSON` method. This will return JSON stringified permissions.\n\n```ts\nimport { Role } from 'lyrol';\n\nconst role = new Role([\n  {\n    resource: 'user',\n    scopes: 'cr---',\n  },\n  {\n    resource: 'post',\n    scopes: 'crudl',\n  },\n  {\n    resource: 'comment',\n    scopes: 'crudl',\n  },\n]);\n\nconst permissions = role.toJSON();\n```\n\nor use the `toObject` for a javascript object.\n\n```ts\nimport { Role } from 'lyrol';\n\nconst role = new Role([\n  {\n    resource: 'user',\n    scopes: 'cr---',\n  },\n  {\n    resource: 'post',\n    scopes: 'crudl',\n  },\n  {\n    resource: 'comment',\n    scopes: 'crudl',\n  },\n]);\n\nconst permissions = role.toObject();\n```\n\nor use use the `generate` method and pass the output type as the first argument.\n\n```ts\nimport { Role } from 'lyrol';\n\nconst role = new Role([\n  {\n    resource: 'user',\n    scopes: 'cr---',\n  },\n  {\n    resource: 'post',\n    scopes: 'crudl',\n  },\n  {\n    resource: 'comment',\n    scopes: 'crudl',\n  },\n]);\n\nconst permissions = role.generate('json');\n```\n\n### Load the role from a database\n\nYou can load the role from your database by using the `fromJSON` or `fromObject` method.\n\n```ts\nimport { Role } from 'lyrol';\n\nconst role = Role.fromJSON(\n  '{\"user\":{\"create\":false,\"read\":false,\"update\":false,\"delete\":false,\"list\":true},\"post\":{\"create\":true,\"read\":true,\"update\":true,\"delete\":true,\"list\":true},\"comment\":{\"create\":true,\"read\":true,\"update\":true,\"delete\":true,\"list\":true},\"page\":{\"create\":true,\"read\":true,\"update\":true,\"delete\":true,\"list\":true},\"picture\":{\"create\":false,\"read\":false,\"update\":true,\"delete\":true,\"list\":true}}'\n);\n\nrole.canCreate('user'); // false\n```\n\nor\n\n```ts\nimport { Role } from 'lyrol';\n\nconst role = Role.fromObject({\n  user: {\n    create: false,\n    read: false,\n    update: false,\n    delete: false,\n    list: true,\n  },\n  post: { create: true, read: true, update: true, delete: true, list: true },\n  comment: {\n    create: true,\n    read: true,\n    update: true,\n    delete: true,\n    list: true,\n  },\n  page: { create: true, read: true, update: true, delete: true, list: true },\n  picture: {\n    create: false,\n    read: false,\n    update: true,\n    delete: true,\n    list: true,\n  },\n});\n\nrole.canCreate('user'); // false\n```\n\n## Authorize a user\n\n### Express Middleware\n\nYou can create a new instance of the `ExpressRoleManager` class and use the `authorize` method to authorize a user.\n\n```ts\nimport { ExpressRoleManager, Role } from 'lyrol';\nimport express from 'express';\n\nconst app = express();\n\nconst user = new Role([\n  {\n    resource: 'post',\n    scopes: 'crudl',\n  },\n  {\n    resource: 'comment',\n    scopes: 'crudl',\n  },\n]);\n\nconst roleManager = new ExpressRoleManager({\n  roles: {\n    user,\n  },\n  resources: ['post', 'comment'],\n});\n\ninterface IAuthRequest {\n  role: string;\n  permissions: any;\n}\n\napp.get(\n  '/comment',\n  (req, res, next) =\u003e {\n    (req as unknown as IAuthRequest).role = 'role1';\n    next();\n  },\n  roleManager.authorize({\n    resource: 'comment',\n    action: ['read', 'list'],\n  }),\n  (req, res) =\u003e {\n    res.send('Hello World!');\n  }\n);\n\napp.listen(3000, () =\u003e {\n  console.log('Example app listening on port 3000!');\n});\n```\n\nThe `authorize` method takes multiple options as a parameter.\n\n- `resource` - The resource to be accessed. Can be a string or an array of strings.\n- `action` - The action to authorize. Can be a string or an array of strings.\n- `roleKey` - The key of the role in the request object. Default is `role`.\n- `usePermissionKey` - It's a boolean value. If set to `true` the `authorize` with create a role from the permissions in the request object. Default is `false`.\n- `permissionKey` - The key of the permissions in the request object. Default is `permissions`.\n- `loose` - It's a boolean value. If set to `true` the `authorize` method will authorize the user if the user has any of the actions. Default is `false`.\n\nYou can pass a custom error handler and success handler to the instance of the `ExpressRoleManager` class.\n\n```ts\nimport { ExpressRoleManager, Role } from 'lyrol';\n\nconst roleManager = new ExpressRoleManager({\n  roles: {\n    user,\n  },\n  resources: ['post', 'comment'],\n  onError: (err, req, res, next) =\u003e {\n    res.status(403).send('Forbidden');\n  },\n  onSucess: (req, res, next) =\u003e {\n    res.send('Hello World!');\n  },\n});\n```\n\n### Koa Middleware\n\nYou can create a new instance of the `KoaRoleManager` class and use the `authorize` method to authorize a user.\n\n```ts\nimport { KoaRoleManager, Role } from 'lyrol';\nimport Koa from 'koa';\nimport Router from 'koa-router';\n\nconst app = new Koa();\n\nconst user = new Role([\n  {\n    resource: 'post',\n    scopes: 'crudl',\n  },\n  {\n    resource: 'comment',\n    scopes: 'crudl',\n  },\n]);\n\nconst roleManager = new KoaRoleManager({\n  roles: {\n    user,\n  },\n  resources: ['post', 'comment'],\n  onError: (err, ctx, next) =\u003e {\n    ctx.status = 403;\n    ctx.body = 'Forbidden';\n  },\n  onSucess: (ctx, next) =\u003e {\n    ctx.body = 'Hello World!';\n  },\n});\n\ninterface IAuthCtx {\n  role: string;\n  permissions: any;\n}\n\nconst router = new Router();\n\nrouter.get(\n  '/comment',\n  async (ctx, next) =\u003e {\n    (ctx as unknown as IAuthCtx).role = 'role1';\n    await next();\n  },\n  roleManager.authorize({\n    resource: 'comment',\n    action: ['read', 'list'],\n  }),\n  async (ctx) =\u003e {\n    ctx.body = 'Hello World!';\n  }\n);\n\napp.use(router.routes());\n\napp.listen(3000, () =\u003e {\n  console.log('Example app listening on port 3000!');\n});\n```\n\nThe `authorize` method takes the same options as the `authorize` method of the `ExpressRoleManager` class.\n\n### Next.js Middleware\n\nYou can create a new instance of the `NextRoleManager` class and use the `authorize` method to authorize a user.\n\n```ts\nimport { NextRoleManager, Role } from 'lyrol';\nimport { NextApiRequest, NextApiResponse, NextApiHandler } from 'next';\n\nconst user = new Role([\n  {\n    resource: 'post',\n    scopes: 'crudl',\n  },\n  {\n    resource: 'comment',\n    scopes: 'crudl',\n  },\n]);\n\nconst roleManager = new NextRoleManager({\n  roles: {\n    user,\n  },\n  resources: ['post', 'comment'],\n  onError: (err, req, res) =\u003e {\n    res.status(403).send('Forbidden');\n  },\n});\n\nconst withAuth = (handler: NextApiHandler) =\u003e {\n  return (req: NextApiRequest, res: NextApiResponse) =\u003e {\n    (req as any).role = 'user';\n    handler(req, res);\n  };\n};\n\nconst handler = roleManager.authorize(\n  {\n    resource: 'comment',\n    action: ['create', 'update'],\n  },\n  (req, res) =\u003e {\n    res.status(200).send('Hello World!');\n  }\n);\n\nexport default withAuth(handler);\n```\n\n## LICENSE\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchaqchase%2Flyrol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchaqchase%2Flyrol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchaqchase%2Flyrol/lists"}