expacl/README.md

Express Access Control List middleware

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));
```