@dysfunctionl/adonis-watchtower v0.0.3

Adonis WatchTower

WatchTower is an addon for Adonis that provides roles and permissions on top of the built in auth. It is also heavily inspired by adonis-acl

Contents

• Main Features
• Setup
  • Install
  • Config
• Usage
  • Working with users
  • Working with roles
  • Working with permissions
• Middleware
• Views
  • @Can

  • @Is

Main Features

• Roles & Permissions
• Middleware (can/is)
• View Tags (@can/@is)

Setup

Install

Install WatchTower

adonis install @dysfunctionl/adonis-watchtower

Like any other provider, you need to register the provider inside start/app.js file.

const providers = [
  '@dysfunctionl/adonis-watchtower/providers/WatchTowerProvider'
]

Register the following middleware inside start/kernel.js file:

const namedMiddleware = {
  can: 'WatchTower/Middleware/Can',
  is: 'WatchTower/Middleware/Is'
}

If you wish to use the view tags (@can/is), register the following:

const globalMiddleware = [
  'WatchTower/Middleware/ViewBinding'
]

Add traits to the app/Models/User.js model:

class User extends Model {
  static get traits () {
    return [
      '@provider:WatchTower/Traits/HasRoles',
      '@provider:WatchTower/Traits/HasPermissions',
      '@provider:WatchTower/Traits/Can',
      '@provider:WatchTower/Traits/Is',
    ]
  }
}

Publish and run the migrations using these commands:

adonis watchtower:setup
adonis migration:run

Start the server

adonis serve --dev

Config

The configuration is saved inside config/watchtower.js file. Tweak it accordingly.

'use strict'

module.exports = {
  'models': {
    // Permission model
    'permission': 'WatchTower/Models/Permission',
    
    // Role model
    'role': 'WatchTower/Models/Role',
    
    // User model
    'user': 'App/Models/User'
  }
}

Usage

Working with users

Fetching roles/permissions

// Roles associated with model
await user.roles().fetch()
// Same as above but slugs only
await user.getRoles()

// Permissions directly associated with model
await user.permissions().fetch()
// Permissions directly and indirectly associated with model as slug
await user.getPermissions()
// Permissions directly associated with model as slug
await user.getDirectPermissions()

Checking roles/permissions

// Pass in an id, slug or model instance, either singularly or multiple in an array
await user.is('administrator')
await user.can(['update-this', 'create-that'])

await user.hasAnyRole(['administrator','moderator'])
await user.hasAllRoles(['administrator','moderator'])

await user.hasPermissionTo('update-this')
await user.hasDirectPermissionTo('create-that')

await user.hasAnyPermission(['update-this', 'create-that'])
await user.hasAllPermissions(['update-this', 'create-that'])

Attaching/Syncing/Removing of role/permissions

// Pass in an id, slug or model instance, either singularly or multiple in an array
await user.assignRoles(['moderator', 'user'])
await user.removeRoles('moderator')
await user.syncRoles(['administrator', 'user'])

await user.givePermissionTo(['update-this', 'create-that'])
await user.revokePermissionTo(['update-this', 'create-that'])
await user.syncPermissions(['update-this', 'create-that'])

Working with roles

Fetching users/permissions

// Users associated with model
await role.users().fetch()
// Same as above
await role.getUsers()

// Permissions directly associated with model
await role.permissions().fetch()
// Permissions directly associated with model as slug
await role.getPermissions()

Checking permissions

// Pass in an id, slug or model instance, either singularly or multiple in an array
await role.hasPermissionTo('update-this')

await role.hasAnyPermission(['update-this', 'create-that'])
await role.hasAllPermissions(['update-this', 'create-that'])

Attaching/Syncing/Removing of permissions

// Pass in an id, slug or model instance, either singularly or multiple in an array
await role.givePermissionTo(['update-this', 'create-that'])
await role.revokePermissionTo(['update-this', 'create-that'])
await role.syncPermissions(['update-this', 'create-that'])

Working with permissions

Fetching users/permissions

// Users associated with model
await permission.users().fetch()
// Same as above
await permission.getUsers()

// Roles associated with model
await permission.roles().fetch()
// Same as above but slugs only
await permission.getRoles()

Checking roles

// Pass in an id, slug or model instance, either singularly or multiple in an array
await permission.hasAnyRole(['administrator','moderator'])
await permission.hasAllRoles(['administrator','moderator'])

Attaching/Syncing/Removing of roles

// Pass in an id, slug or model instance, either singularly or multiple in an array
await permission.assignRoles(['moderator', 'user'])
await permission.removeRoles('moderator')
await permission.syncRoles(['administrator', 'user'])

Middleware

Route.get('/posts', ()=>{})
    .middleware(['can:read-posts, create-posts'])

Route.get('/posts', ()=>{})
    .middleware(['is:admin, user'])

Views

@Can

@can('update-users')
    // Do something if user has permission
@else
    // Otherwise do this
@endcan

@can(['create-posts', 'read-posts'])
    // Do something if user has permissions
@else
    // Otherwise do this
@endcan

@Is

@is('admin')
    // Do something if user has role
@else
    // Otherwise do this
@endis

@is(['admin', 'moderator'])
    // Do something if user has roles
@else
    // Otherwise do this
@endis