Basic Usage
Checking Access
Check roles and permissions on your models.
Prefer checking permissions over roles. Roles are just groups of permissions.
Permissions
await user.can('edit articles') // boolean
await user.cannot('edit articles') // boolean
await user.hasPermissionTo('edit articles') // boolean
await user.checkPermissionTo('edit articles') // true or throws
await user.hasAnyPermission('edit articles', 'delete articles')
await user.hasAllPermissions('edit articles', 'delete articles')
can() and hasPermissionTo() check direct permissions and permissions inherited from roles. To be specific:
await user.hasDirectPermission('edit articles')
await user.hasPermissionViaRole('edit articles')
await user.getDirectPermissions() // permission models
await user.getPermissionsViaRoles() // permission models
await user.getAllPermissions() // direct + via roles
await user.getPermissionNames() // string[] (direct)
Roles
await user.hasRole('writer')
await user.hasRole(['writer', 'admin']) // any of them
await user.hasAnyRole('writer', 'admin')
await user.hasAllRoles('writer', 'admin')
await user.hasExactRoles('writer', 'admin') // exactly these roles
await user.getRoleNames() // string[]
Role permissions
await role.hasPermissionTo('edit articles')
await role.hasAnyPermission('edit articles', 'delete articles')
await role.getPermissionNames()
Edge
Edge tags are registered automatically when Edge is available. They use auth.user from the template state:
@can('edit articles')
<a href="/articles/1/edit">Edit</a>
@end
@cannot('edit articles')
<p>Read only</p>
@end
@role('admin')
<a href="/admin">Admin panel</a>
@end
@hasrole('admin')
...
@end
Error
Middlewares and checkPermissionTo() throw E_PERMISSION_UNAUTHORIZED_ACCESS with status 403. When requested as JSON it renders { errors: [{ code, status, message }] }; otherwise it sends the message as plain text. You can handle it in your exception handler like any other error:
import { E_PERMISSION_UNAUTHORIZED_ACCESS } from '@eienjs/adonisjs-permission'
if (error instanceof E_PERMISSION_UNAUTHORIZED_ACCESS) {
// custom handling
}