verful/adonis-permissions

Easily manage user roles and permissions on AdonisJS applications

Adonis Permissions

Easily manage user roles and permissions

Pre-requisites

The @verful/permissions package requires @adonisjs/core >= 5 and @adonisjs/lucid >= 16

Setup

Install the package from the npm registry as follows.

npm i @verful/permissions
# or
yarn add @verful/permissions

Next, configure the package by running the following ace command.

node ace configure @verful/permissions

Getting started

Once the package is installed the first thing you want to do is apply the Authorizable mixin from @ioc:Verful/Permissions/Mixins into a model

import { Authorizable } from '@ioc:Verful/Permissions/Mixins'
import { compose } from '@ioc:Adonis/Core/Helpers'
import { BaseModel } from '@ioc:Adonis/Lucid/Orm'

const config = { 
  permissionsPivotTable: 'user_has_permissions',
  rolesPivotTable: 'user_has_roles'
}

export default class User extends compose(BaseModel, Authorizable(config)) {}

Now its time to create the pivot-table migration files

node ace permissions:pivot-table

After the mixin is applied you can do stuff like this

await user.givePermissionTo('view-users')
await user.assignRole('admin')

await role.givePermissionTo('edit-users')

Basic usage

The package allows you to associate Lucid models with roles and permissions. Roles and Permissions are just Lucid models that can be directly managed like any other model

import Permission from '@ioc:Verful/Permissions/Permission'
import Role from '@ioc:Verful/Permissions/Role'

const role = await Role.create({ name: 'writer' })
const permission = await Permission.create({ name: 'edit-posts' })

Managing permissions

You can manage permissions for roles and models using the same methods

// Assigning permissions
await role.givePermissionTo('do-things')

// Removing permissions
await user.revokePermissionTo('do-things')

// Synchronize permissions
await role.syncPermissions('do-things', 'try-things')

Checking for permissions

// Checking permissions
await role.hasPermissionTo('do-things') // returns true or false
await user.checkPermissionTo('do-things') // returns true or throws

// Returns true if the model has any of the given permissions
await role.hasAnyPermission('do-things', 'try-things') 

// Returns true if the model has all of the given permissions
await user.hasAllPermissions('do-things', 'try-things')

// Returns all permission names
await user.getPermissionNames()

Managing Roles

You can manage roles for models using the Authorizable mixin

// Assign role
await user.assignRole('admin')

// Revoke role
await user.revokeRole('admin')

// Synchronize roles
await user.syncRoles('admin', 'writer', role)

Checking for roles

Generally you should be checking against permissions vs checking for roles, but if you want to check against a role instead use one of the following methods

await user.hasRole('admin')

// Returns true if the model has any of the given permissions
await role.hasAnyRoles('admin', 'writer') 

// Returns true if the model has all of the given permissions
await user.hasAllRoles('admin', 'writer')

// Returns all role names
await user.getRoleNames()

Accessing direct and role permissions

// Check if the model has the permission directly
await user.hasDirectPermission('do-things')

// Check if the model has the permission via role
await user.hasPermissionViaRole('do-things')

// Get all direct permissions
await user.getDirectPermissions()

// Get all permissions via roles
await user.getPermissionsViaRoles()

// Get all permissions combined
await user.getAllPermissions()