npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@ruanitto/adonis-acl

v1.2.0

Published

Adonis ACL system

Downloads

4

Readme

Adonis ACL

Adonis ACL adds role based permissions to built in Auth System of Adonis Framework.

NPM Version GitHub license Build Status Coverage Status

Installation

  1. Add package:
$ adonis install @rocketseat/adonis-acl
  1. Register ACL providers inside the your start/app.js file.
const providers = [
  ...
  '@rocketseat/adonis-acl/providers/AclProvider',
  ...
]

const aceProviders = [
  ...
  '@rocketseat/adonis-acl/providers/CommandsProvider',
  ...
]
  1. Setting up traits to User model.
class User extends Model {
  ...
  static get traits () {
    return [
      '@provider:Adonis/Acl/HasRole',
      '@provider:Adonis/Acl/HasPermission'
    ]
  }
  ...
}
  1. Setting up middlewares inside start/kernel.js file.
const namedMiddleware = {
  ...
  is: 'Adonis/Acl/Is',
  can: 'Adonis/Acl/Can',
  acl: 'Adonis/Acl/Acl',
  scope: 'Adonis/Acl/Scope'
  ...
}

For using in views

const globalMiddleware = [
  ...
  'Adonis/Acl/Init'
  ...
]
  1. Publish the package migrations to your application and run these with adonis migration:run.
$ adonis acl:setup

Working With Roles

Create Role

Lets create your first roles.

const roleAdmin = new Role();
roleAdmin.name = "Administrator";
roleAdmin.slug = "administrator";
roleAdmin.description = "manage administration privileges";

await roleAdmin.save();

const roleModerator = new Role();
roleModerator.name = "Moderator";
roleModerator.slug = "moderator";
roleModerator.description = "manage moderator privileges";

await roleModerator.save();

Before, you should do first, use the HasRole trait in Your User Model.

class User extends Model {
  ...
  static get traits () {
    return [
      '@provider:Adonis/Acl/HasRole'
    ]
  }
  ...
}

Attach Role(s) To User

const user = await User.find(1);
await user.roles().attach([roleAdmin.id, roleModerator.id]);

Detach Role(s) From User

const user = await User.find(1);
await user.roles().detach([roleAdmin.id]);

Get User Roles

Get roles assigned to a user.

const user = await User.first();
const roles = await user.getRoles(); // ['administrator', 'moderator']

Working With Permissions

Create Role Permissions

const createUsersPermission = new Permission();
createUsersPermission.slug = "create_users";
createUsersPermission.name = "Create Users";
createUsersPermission.description = "create users permission";
await createUsersPermission.save();

const updateUsersPermission = new Permission();
updateUsersPermission.slug = "update_users";
updateUsersPermission.name = "Update Users";
updateUsersPermission.description = "update users permission";
await updateUsersPermission.save();

const deleteUsersPermission = new Permission();
deleteUsersPermission.slug = "delete_users";
deleteUsersPermission.name = "Delete Users";
deleteUsersPermission.description = "delete users permission";
await deleteUsersPermission.save();

const readUsersPermission = new Permission();
readUsersPermission.slug = "read_users";
readUsersPermission.name = "Read Users";
readUsersPermission.description = "read users permission";
await readUsersPermission.save();

Before, you should do first, use the HasPermission trait in Your User Model.

class User extends Model {
  ...
  static get traits () {
    return [
      '@provider:Adonis/Acl/HasPermission'
    ]
  }
  ...
}

Attach Permissions to Role

const roleAdmin = await Role.find(1);
await roleAdmin
  .permissions()
  .attach([
    createUsersPermission.id,
    updateUsersPermission.id,
    deleteUsersPermission.is,
    readUsersPermission.id
  ]);

Detach Permissions from Role

const roleAdmin = await Role.find(1);
await roleAdmin
  .permissions()
  .detach([
    createUsersPermission.id,
    updateUsersPermission.id,
    deleteUsersPermission.is,
    readUsersPermission.id
  ]);

Get User Permissions

Get permissions assigned to a role.

const roleAdmin = await Role.find(1);
// ['create_users', 'update_users', 'delete_users', 'read_users']
await roleAdmin.getPermissions();

or

const roleAdmin = await Role.find(1);
// collection of permissions
await roleAdmin.permissions().fetch();

Protect Routes

Syntax:

and - administrator and moderator

or - administrator or moderator

not (!) - administrator and !moderator

// check roles
Route.get("/users").middleware([
  "auth:jwt",
  "is:(administrator or moderator) and !customer"
]);

// check permissions
Route.get("/posts").middleware(["auth:jwt", "can:read_posts"]);

// check roles and permissions
Route.put("/posts").middleware(["auth:jwt", "acl:admin or update_posts"]);

// scopes (using permissions table for scopes)
Route.get("/posts").middleware(["auth:jwt", "scope:posts.*"]);

The acl middleware is used to verify both a role and a permission at the same time, but for it to work properly it is necessary that a role and a permission doesn't share the same name.

Vow trait

adonis-acl has a trait to make it easy to use it while testing with adonis-vow. To enable the addRoles and addPermissions methods, you need to add the trait Acl/Client.

The arguments must be your roles or permissions.

const [admin, moderator] = await Role.all();
addRole(admin, moderator);
const [create, read, update, del] = await Permission.all();
addPermission(create, read, update, del);

Here's an example of how to use it inside a test:

const { test, trait } = use("Test/Suite")("Awesome test");

trait("Test/ApiClient");
trait("Auth/Client");
trait("Acl/Client");

test("awesome some test", async ({ client }) => {
  const role = await Role.find(1);
  const permission = await Permission.find(1);
  const user = await User.find(1);

  const response = await client
    .put("/posts/1")
    .loginVia(user)
    .addRoles(role)
    .addPermissions(permission)
    .end();
});

Both addRoles and addPermissions inject roles and permissions on the user that was passed by loginVia method, so it is vital to call them after loginVia as seen on the example above.

It is also crucial that trait("Auth/Client") is called before trait("Acl/Client").

Using commands

| Command | Description | Options | | --------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | adonis acl:setup | Publish the package migrations to your application | | | adonis acl:role <slug> [name][description] | Make a new role | --permissions=<slug list of permissions separated by comma> Attach permissions to the role | | adonis acl:permissions <slug> [name][description] | Make a new permission or updates the name and description if the slug was found | |

Using in Views

@loggedIn
  @is('administrator')
    <h2>Protected partial</h2>
  @endis
@endloggedIn

or

@loggedIn
  @can('create_posts or delete_posts')
    <h2>Protected partial</h2>
  @endcan
@endloggedIn

or

@loggedIn
  @scope('posts.create', 'posts.delete')
    <h2>Protected partial</h2>
  @endscope
@endloggedIn

Credits

Support

Having trouble? Open an issue!

License

The MIT License (MIT). Please see License File for more information.