npm package: @frappy/node-authentication
Description: Express endpoints for Authentication and User Management
Author: Peter Ilfrich
Latest version: 1.5.0

# NodeJS Authentication

NodeJS Endpoints and Functionality For Authentication and User Management

- `authMiddleware` - Express middleware to facilitate authentication and permission checks
- `registerEndpoints` - Express endpoints to handle login, authentication check and user management

## Usage

```javascript
import { registerEndpoints, authMiddleware } from "@frappy/node-authentication"
import express from "express"
import bodyParser from "body-parser"

const app = express()  // create your express app
app.use(bodyParser.json({ limit: "10mb" }))  // provide JSON parser with 10 MB payload limit

// entirely optional userOptions (see README for defaults)
const options = {
    tokenExpiration: 24 * 60 * 60,  // session expires after one day
    defaultPermissions: ["view"],  // new users (first login) will receive this permission
    apiKeys: true, // use API keys in this app
}

// cache to hold authentication token (will be populated by auth endpoints)
const tokenCache = {}

// register module
registerEndpoints(app, userStore, userTokenStore, tokenCache, options)

// provide some custom endpoint with authentication and permission check
app.get("/my/custom/endpoint", authMiddleware(["view", "manage"], tokenCache), (req, res) => {
    // only enter this, if the user is authenticated and has "manage" and "view" permissions
    res.send({ foo: "bar" })
})
```

**`registerEndpoints(app, userStore, userTokenStore, tokenCache, options)`**

- `app` - your express app
- `userStore` a MongoDB or MySQL store providing functions: `login`, `getAll`, `get`, `delete`, `getByUid`, `count`, 
`getByUsername`, `create` and `updatePermissions`
- `userTokenStore` **optional**, a Mongo or MySQL store providing functions: `removeExpired`, `storeToken` and `getAll`. 
 If this is not provided, all tokens will be invalidated on server restart. 
- `tokenCache` a JSON object that will hold auth tokens and their respective owners (users), required for 
`authMiddleware`
- `options` **optional**, a JSON object that provides the options (see [Options](#options))

**`authMiddleware(requiredPermissions, tokenCache, allowApiKey = false)`**

- `requiredPermissions` - **optional** a single string representing a permission the user has to fulfill **or** a list of permissions 
that all have to be fulfilled. 
- `tokenCache` a JSON object holding the authentication tokens. This is the same object that is passed into the 
`registerEndpoints` function.
- `allowApiKey` a boolean flag indicating whether the current endpoint can be accessed using an API key instead of a 
 regular auth header token. The API key needs to be provided as `Authorization` header with value `Token $KEY` 
 (replacing `$KEY` with the actual key generated by the system). 

## Options

The `registerEndpoint` function has a parameter to pass options. All options are optional. The following options are 
supported:

- `apiPrefix` (default: `/api/user`) - a prefix for all endpoints provided, this will generate:
    - POST `/api/user/login` - to log in (using username, password as JSON payload)
    - GET `/api/user` - general login check, has to provide `Authorization` header
    - GET|POST|DELETE `/api/user/users[/:userId|/permissions]` - a set of endpoints for user management
- `tokenExpiration` (default: `1209600` = 14 days) - the lifetime of a login session before the token gets invalidated 
 in seconds
- `userAdminPermission` (default: `admin`) - the label for the admin privilege that allows to manage users
- `defaultPermissions` (default: `[]` - none) - a list of user permissions newly created users will receive
- `noUserManagement` (default `false`) - a flag indicating whether to register user management endpoints (get all users, 
 update permissions, delete user and create user)
- `apiKeys` (default `false`) - a flag indicating whether API keys are available in the system for creating and revoking
 keys as well as recognising API keys during login.
- `allowOwnProfileEdit` (default `false`) - a flag that when set to true allows any logged in user to update *their own* 
 profile information (`user.profile`).
- `pageSize` (default `25`) - the maximum number of users to return with the `/users` endpoint.