# expacl

> Express Access Control List middleware

Latest version **0.0.4** (published 2018-04-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install expacl
pnpm add expacl
yarn add expacl
bun add expacl
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.4 |
| Published | 2018-04-26 |
| First published | 2018-04-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | * |
| Dependencies | 0 |
| Unpacked size | 26.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Stanislav Oaserele |
| Maintainers | soaserele |
| Keywords | express-acl, acl, accesscontrol |

## Links

- npm: https://www.npmjs.com/package/expacl
- npm.io page: https://npm.io/package/expacl

## Recent versions

- 0.0.4 (latest) — 2018-04-26
- 0.0.3 — 2018-04-24
- 0.0.2 — 2018-04-24
- 0.0.1 — 2018-04-24

## README

Express based Access Control List middleware
============================================

Express Access Control List (expacl) enable you to manage the access to resources served by your express server 
and to protect routes four anauthenticated/unauthorized access. 

ACLs defines which user roles are granted access to a specified resource

Expacl checks the corresponding access policy against user's request to verify if the user has is as authenticated 
and/or has the necessary access privileges.

Installation
------------

Using npm:

```javascript
npm install expacl
```

Using yarn:

```javascript
yarn add expacl
```

Options
-------
*Required:* 
```javascript
    routes: ACLRoute[], /* An array with Access Control List routes */
```

*Optional:* 
```javascript
    resource: (req: Request) => string, /* This is the resource that we are either giving access to. Defaults to req.url */
    roles: (req: Request) => string[] | undefined, /* This property returns an array of strings that define the user roles. Defaults to req.user.roles */
    authenticated: (req: Request) => boolean, /* This property returns true if user is authenticated. Defaults to !!req.user */
    missingRoute: Action, /* This property tells expacl what action to perform if requested route is not defined in routes array. Defaults to deny */
    defaultAction: Action, /* This property tells expacl what action to perform if requested route is found but no action is defined for the route. Defaults to allow */
    onNotAuthenticated: (req: Request, res: Response, next: NextFunction) => any /* This method is invoked when requested route is denied and user is not authenticated. Defaults to res.status(401).send("401 Not authenticated"); */
    onNotAuthorized: (req: Request, res: Response, next: NextFunction) => any /* This method is invoked when requested route is denied and user is not authenticated. Defaults to res.status(403).send("403 Not authorized"); */
```
Examples
--------

```javascript
import middleware from 'expacl';

const opts = {
    routes: [
        {
            path: '/',
            subroutes: [
                {
                    path: '/page1',
                    methods: 'GET',
                    roles: '*',
                }, /* /page1 route will be accessible by all users via a GET */
                {
                    path: '/page1/submit',
                    methods: 'POST',
                    roles: 'authenticated',
                }, /* /page1/submit route will be accessible by users with 'authenticated' role via a POST */
                {
                    path: '/page2',
                    roles: '*',
                    subroutes: [
                        {
                            path: '/submit',
                            methods: 'POST',
                            roles: 'authenticated',
                        }
                    ]
                }, /* the same rights as above, but declaring ACL using nested structure */
                {
                    path: '/api/v1',
                    transient: true, /* /api/v1 route is marked as transient. Not a valid resource */
                    subroutes: [
                        {
                            path: '/resource',
                            methods: 'GET',
                            roles: ['*'], /* /api/v1/resource route is accessible by all users via GET */
                            subroutes: [
                                {
                                    path: /^[a-f\d]{24}$/i, /* path can also be described as a regular expression */
                                    methods: 'GET',
                                    roles: ['*'], /* /api/v1/resource/[^[a-f\d]{24}$] route is accessible by all users via GET */
                                },
                                {
                                    path: /^[a-f\d]{24}$/i,
                                    methods: ['POST', 'DELETE'],
                                    roles: 'admin', /* /api/v1/resource/[^[a-f\d]{24}$] route is accessible only by an user with admin role via POST or DELETE */
                                }
                            ]
                        },
                    ]
                },
            ]
        }
    ]
};
app.use(middleware(opts));
```

---
_Source: https://npm.io/package/expacl · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._