express-acler/README.md

ACL manager for Express using ACLer

![](assets/logo.png)

## Overview

O express-acler é um middleware para o ExpressJS para utilização de ACL baseado no [acler](https://github.com/enniel/acler).

## Installation

Para adicionar o `express-acler` no seu projeto:

```
npm install express-acler
```

Ou

```
yarn add express-acler
```

## Configurations

Você pode fazer algumas alterações na configuração para adequar o `express-acler` a sua necessidade.
Você tem as seguintes configurações:

| Propriedade            | Tipo     | Default                            | Descrição                                                                           |
| ---------------------- | -------- | ---------------------------------- | ----------------------------------------------------------------------------------- |
| **roles**              | `string` | `user.roles`                       | Caminho das **roles** do seu usuário                                                |
| **permissions**        | `string` | `user.permissions`                 | Caminho das **permissions** do seu usuário                                          |
| **errors.roles**       | `string` | `You not allowed to this resource` | Mensagem de erro apresentada ao usuário por não possuir a **role** necessária       |
| **errors.permissions** | `string` | `You not allowed to this resource` | Mensagem de erro apresentada ao usuário por não possuir a **permission** necessária |

## Important

O `express-acler` precisa que você insira o seu `User` em um `middleware` que o antecede, por padrão o usuário deve ser inserido no `req.user` e as **roles** e **permissions** devem ficar em `req.user.roles` e `req.user.permissions` respectivamente. Essa configuração pode ser alterada quando o `express-acler` for instanciado.

```js
// userMiddleware.js
const User = require("../models/User");

module.exports = async (req, res, next) => {
  req.user = await User.findById(1);
  next();
};
```

O seu usuário deve ter um `Array` contendo as **roles** e as **permissions** e caso alguma **role** possua **permissions** ela deve vir como `Object`. Segue o exemplo da estrutura esperada:

```js
user = {
  username: "Higo Ribeiro",
  get roles() {
    return ["moderator", { moderator: ["read", "write", "delete"] }];
  },
  get permissions() {
    return ["write", "read"];
  }
};
```

## Permissions

Ao tratar das **permissions** o `express-acler` naturalmente pega aquelas definidas nas **roles** do `User`, seguindo o objeto acima apresentado suas permissões são `write`, `read` e `delete`. A `delete` foi automaticamente acrescentada as **permissions** pois é uma das atribuições do `moderator`.

## Usage

```js
const { is, can } = require("express-acler")();
const app = require("express")({
  /* ... configurations */
});

const userMiddleware = require("./userMiddleware");
const postController = require("./controllers/post");

app.use(userMiddleware());

app.use("/app/dashboard", is("administrator"));
app.get("/posts", can("read || read_private"), postController.index);

app.post("/post", is("moderator"), postController.post);
```

## Contribute

Todas as contribuições são bem-vindas.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

## License

MIT © [Rocketseat](https://github.com/Rocketseat)