{"id":13807733,"url":"https://github.com/Bagaar/ember-permissions","last_synced_at":"2025-05-14T00:32:02.188Z","repository":{"id":38483877,"uuid":"168197192","full_name":"Bagaar/ember-permissions","owner":"Bagaar","description":"Permission management for Ember applications.","archived":false,"fork":false,"pushed_at":"2024-09-23T22:45:56.000Z","size":2621,"stargazers_count":14,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-11T22:38:22.585Z","etag":null,"topics":["ember-addon","permissions"],"latest_commit_sha":null,"homepage":"","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/Bagaar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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":"2019-01-29T17:29:31.000Z","updated_at":"2024-07-05T16:36:00.000Z","dependencies_parsed_at":"2024-02-01T20:08:14.127Z","dependency_job_id":"a57cdc0b-71fc-492d-aed1-79e1e34de971","html_url":"https://github.com/Bagaar/ember-permissions","commit_stats":{"total_commits":221,"total_committers":4,"mean_commits":55.25,"dds":"0.15384615384615385","last_synced_commit":"cec208f7a88638e08fb151471c56de98a8d9758a"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bagaar%2Fember-permissions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bagaar%2Fember-permissions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bagaar%2Fember-permissions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bagaar%2Fember-permissions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bagaar","download_url":"https://codeload.github.com/Bagaar/ember-permissions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254046394,"owners_count":22005584,"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":["ember-addon","permissions"],"created_at":"2024-08-04T01:01:29.635Z","updated_at":"2025-05-14T00:31:57.165Z","avatar_url":"https://github.com/Bagaar.png","language":"TypeScript","funding_links":[],"categories":["Packages"],"sub_categories":["Security"],"readme":"# @bagaar/ember-permissions\n\n[![CI](https://github.com/bagaar/ember-permissions/workflows/CI/badge.svg)](https://github.com/bagaar/ember-permissions/actions?query=workflow%3ACI)\n[![NPM Version](https://badge.fury.io/js/%40bagaar%2Fember-permissions.svg)](https://badge.fury.io/js/%40bagaar%2Fember-permissions)\n\nPermission management for Ember applications.\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Compatibility](#compatibility)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Public API](#public-api)\n  - [`permissions` Service](#permissions-service)\n    - [`setPermissions`](#setpermissions)\n    - [`setRoutePermissions`](#setroutepermissions)\n    - [`hasPermissions`](#haspermissions)\n    - [`hasSomePermissions`](#hassomepermissions)\n    - [`canAccessRoute`](#canaccessroute)\n    - [`enableRouteValidation`](#enableroutevalidation)\n    - [`addRouteAccessDeniedHandler`](#addrouteaccessdeniedhandler)\n    - [`removeRouteAccessDeniedHandler`](#removerouteaccessdeniedhandler)\n  - [Helpers](#helpers)\n    - [`has-permissions`](#has-permissions)\n    - [`has-some-permissions`](#has-some-permissions)\n    - [`can-access-route`](#can-access-route)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Introduction\n\n`@bagaar/ember-permissions` is an addon that allows you to **manage and validate permissions** for the current session. It also allows you to **define required permissions per route** so you can protect specific parts of your application. Instead of using a mixin to protect your routes, the addon allows you to define the required permissions per route in a single file. Specific handlers can be added to determine what needs to happen when a transition occurs that is denied.\n\n## Compatibility\n\n- Ember.js v4.8 or above\n- Embroider or ember-auto-import v2\n\n## Installation\n\n```shell\nnpm install -D @bagaar/ember-permissions\n```\n\n```shell\npnpm add -D @bagaar/ember-permissions\n```\n\n```shell\nyarn add -D @bagaar/ember-permissions\n```\n\n## Usage\n\n### 1\\. Setting up Session Permissions\n\nFirst, we need to let the `permissions` service know which permissions are available for the current session. In the example below, we're using an additional `api` service to request the permissions from an API. Afterwards, we pass along the permissions to the `permissions` service via the [`setPermissions`](#setpermissions) method.\n\n```javascript\n// app/routes/protected.js\n\nimport Route from '@ember/routing/route';\nimport { service } from '@ember/service';\n\nexport default class ProtectedRoute extends Route {\n  @service('api') apiService;\n  @service('permissions') permissionsService;\n\n  async beforeModel() {\n    const permissions = await this.apiService.request('/permissions');\n\n    this.permissionsService.setPermissions(permissions);\n  }\n}\n```\n\nOnce the permissions are set, we can start checking their presence. In the example below, we use the [`has-permissions`](#has-permissions) helper to conditionally render a delete button based on the presence of the `delete-users` permission.\n\n```handlebars\n{{! app/templates/users/index.hbs }}\n\n{{#if (has-permissions \"delete-users\")}}\n  \u003cbutton type=\"button\"\u003e\n    Delete User\n  \u003c/button\u003e\n{{/if}}\n```\n\n\u003e **NOTE:** If you need to validate permissions inside a JavaScript file, you can use the [`hasPermissions`](#haspermissions) or the [`hasSomePermissions`](#hassomepermissions) method on the `permissions` service instead.\n\n### 2\\. Setting up Route Permissions\n\nStart off with defining the required permissions per route. You're free to define them where you want, as long as the format is the same as shown below.\n\n```javascript\n// app/route-permissions.js\n\nexport default {\n  'users.index': ['view-users'],\n  'users.create': ['create-users'],\n  'users.edit': ['edit-users'],\n};\n```\n\nNext, edit the `protected` route from step 1 as follows:\n\n1. Use the [`setRoutePermissions`](#setroutepermissions) method to pass along the required permissions per route to the `permissions` service\n2. Add a route-access-denied handler to determine what needs to happen when a transition occurs that is denied\n3. Call [`enableRouteValidation`](#enableroutevalidation) with the initial transition\n\n```javascript\n// app/routes/protected.js\n\nimport { registerDestructor } from '@ember/destroyable';\nimport Route from '@ember/routing/route';\nimport { service } from '@ember/service';\nimport ROUTE_PERMISSIONS from 'app-name/route-permissions';\n\nexport default class ProtectedRoute extends Route {\n  @service('api') apiService;\n  @service('permissions') permissionsService;\n  @service('router') routerService;\n\n  async beforeModel(transition) {\n    const permissions = await this.apiService.request('/permissions');\n\n    this.permissionsService.setPermissions(permissions);\n    this.permissionsService.setRoutePermissions(ROUTE_PERMISSIONS);\n\n    const handler = (/* deniedTransition */) =\u003e {\n      // Handle the denied transition.\n      // E.g. redirect to a generic error route:\n      this.routerService.replaceWith('error', { error: 'access-denied' });\n    };\n\n    this.permissionsService.addRouteAccessDeniedHandler(handler);\n\n    registerDestructor(this, () =\u003e {\n      this.permissionsService.removeRouteAccessDeniedHandler(handler);\n    });\n\n    this.permissionsService.enableRouteValidation(transition);\n  }\n}\n```\n\nNow, each transition will be validated (including the provided initial transition) against the required permissions per route. If a transition is denied, the added route-access-denied handler will be called with the denied transition.\n\nSince the required permissions per route are now set, we can start checking if routes can be accessed. In the example below, we use the [`can-access-route`](#can-access-route) helper to do so.\n\n```handlebars\n{{! app/components/menu.hbs }}\n\n{{#if (can-access-route \"users.index\")}}\n  \u003cli\u003e\n    \u003cLinkTo @route=\"users.index\"\u003e\n      Users\n    \u003c/LinkTo\u003e\n  \u003c/li\u003e\n{{/if}}\n```\n\n\u003e **NOTE:** If you need to validate if a route can be accessed inside a JavaScript file, you can use the [`canAccessRoute`](#canaccessroute) method on the `permissions` service instead.\n\n## Public API\n\n### `permissions` Service\n\n#### Methods\n\n##### `setPermissions`\n\nSet the permissions for the current session.\n\n###### Arguments\n\nAn array of permissions.\n\n###### Returns\n\n/\n\n###### Example\n\n```javascript\npermissionsService.setPermissions([\n  'view-users',\n  'create-users',\n  'edit-users',\n]);\n```\n\n##### `setRoutePermissions`\n\nSet the required permissions per route.\n\n###### Arguments\n\nAn object of which the keys are route names and the values are arrays of required permissions.\n\n###### Returns\n\n/\n\n###### Example\n\n```javascript\npermissionsService.setRoutePermissions({\n  'users.index': ['view-users'],\n  'users.create': ['create-users'],\n  'users.edit': ['edit-users'],\n});\n```\n\n##### `hasPermissions`\n\nCheck if all the provided permissions are available for the current session.\n\n###### Arguments\n\nAn array of permissions.\n\n###### Returns\n\nReturns `true` if all the provided permissions are available for the current session, `false` if otherwise.\n\n###### Example\n\n```javascript\npermissionsService.hasPermissions([\n  'view-users',\n  'create-users',\n  'edit-users',\n]);\n```\n\n##### `hasSomePermissions`\n\nCheck if some of the provided permissions are available for the current session.\n\n###### Arguments\n\nAn array of permissions.\n\n###### Returns\n\nReturns `true` if some of the provided permissions are available for the current session, `false` if otherwise.\n\n###### Example\n\n```javascript\npermissionsService.hasSomePermissions([\n  'view-users',\n  'create-users',\n  'edit-users',\n]);\n```\n\n##### `canAccessRoute`\n\nCheck if the provided route can be accessed.\n\n###### Arguments\n\nA route's name.\n\n###### Returns\n\nReturns `true` if the provided route can be accessed, `false` if otherwise.\n\n###### Example\n\n```javascript\npermissionsService.canAccessRoute('users.index');\n```\n\n##### `enableRouteValidation`\n\nTell the `permissions` service that it should start validating each transition (including the provided initial transition) and confirm that it's allowed based on the required permissions per route. If a transition is denied, all added route-access-denied handlers will be called with the denied transtion.\n\n###### Arguments\n\nThe initial transition.\n\n###### Returns\n\n/\n\n###### Example\n\n```javascript\npermissionsService.enableRouteValidation(transition);\n```\n\n##### `addRouteAccessDeniedHandler`\n\nAdd a route-access-denied handler.\n\n###### Arguments\n\nA handler.\n\n###### Returns\n\n/\n\n###### Example\n\n```javascript\nconst handler = (/* deniedTransition */) =\u003e {\n  // Handle the denied transition.\n  // E.g. redirect to a generic error route:\n  this.routerService.replaceWith('error', { error: 'access-denied' });\n};\n\nthis.permissionsService.addRouteAccessDeniedHandler(handler);\n```\n\n##### `removeRouteAccessDeniedHandler`\n\nRemove a previously added route-access-denied handler.\n\n###### Arguments\n\nA handler.\n\n###### Returns\n\n/\n\n###### Example\n\n```javascript\nconst handler = (/* deniedTransition */) =\u003e {\n  // Handle the denied transition.\n  // E.g. redirect to a generic error route:\n  this.routerService.replaceWith('error', { error: 'access-denied' });\n};\n\nthis.permissionsService.removeRouteAccessDeniedHandler(handler);\n```\n\n### Helpers\n\n#### `has-permissions`\n\nCheck if all the provided permissions are available for the current session.\n\n###### Arguments\n\nSeparate permissions.\n\n###### Returns\n\nReturns `true` if all the provided permissions are available for the current session, `false` if otherwise.\n\n###### Example\n\n```handlebars\n{{has-permissions \"view-users\" \"create-users\" \"edit-users\"}}\n```\n\n#### `has-some-permissions`\n\nCheck if some of the provided permissions are available for the current session.\n\n###### Arguments\n\nSeparate permissions.\n\n###### Returns\n\nReturns `true` if some of the provided permissions are available for the current session, `false` if otherwise.\n\n###### Example\n\n```handlebars\n{{has-some-permissions \"view-users\" \"create-users\" \"edit-users\"}}\n```\n\n#### `can-access-route`\n\nCheck if the provided route can be accessed.\n\n###### Arguments\n\nA route's name.\n\n###### Returns\n\nReturns `true` if the provided route can be accessed, `false` if otherwise.\n\n###### Example\n\n```handlebars\n{{can-access-route \"users.index\"}}\n```\n\n## Contributing\n\nSee the [Contributing](CONTRIBUTING.md) guide for details.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBagaar%2Fember-permissions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBagaar%2Fember-permissions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBagaar%2Fember-permissions/lists"}