appliedblockchain / mantle-auth

Authorization functionality for Koa routers, for both blockchain (integrated with Mantle) and non-blockchain applications

Mantle Auth

Authorization functionality for Koa routers

Usage

Details

The purpose of Mantle Auth is to generate Koa middleware Functions that will perform various authorization related tasks. It can generate individual route middleware, but as a convenience is also capable of creating definition Objects that can be used as routes by joi-router, or even a joi-router instance with those routes already created.

Most (possibly all) of these tasks require data storage that persists between requests, so Mantle Auth makes use of Adapters in an effort to add a level of abstraction between the route handling logic and data management. Before any of the middleware Functions are called an adapter must be created and set, and the adapter chosen will control where data is persisted to / retrieved from.

Router

A router creation Function can be found here:

const { create } = require('@appliedblockchain/mantle-auth/router')

Invoking it will create a joi-router instance. See ./router.js or Examples below for usage

Route Definitions

These are Objects that are suitable for input to the joi-router route method. The route definition functionality is stored here:

const route_name = require('@appliedblockchain/mantle-auth/routes/route_name')
// OR
const { route_name } = require('@appliedblockchain/mantle-auth/routes')

Each route definition has the following exports:

• definition: joi-router definition Object without a handler
• createHandler: Function that will create a Koa middleware for the route. It can also be added as the handler of 'definition'.
• createRoute: Helper Function that will create a handler, append it to the definition and return the result

Middleware

More specifically, middleware that passes requests along to other middleware rather than perform request resolution. They are stored here:

const middleware_name = require('@appliedblockchain/mantle-auth/middleware/middleware_name')
// OR
const { middleware_name } = require('@appliedblockchain/mantle-auth/middleware')

Each middleware has the following exports:

• middleware: a Koa compatible middleware function

Adapters

Adapters are stored here:

const adapter_name = require('@appliedblockchain/mantle-auth/storage/adapters/adapter_name')
// OR
const { adapter_name } = require('@appliedblockchain/mantle-auth/storage/adapters')

Each adapter exports a class that can be used to instantiate new adapters They can be get/set with the methods obtained from here:

const { getAdapter, setAdapter } = require('@appliedblockchain/mantle-auth/adapters')

Examples

Routes

Quick:

const { create } = require('@appliedblockchain/mantle-auth/router')

const router = create({
  psqlConnect: 'postgres://user:pass@localhost:5432/mydb',
  routeOptions: {
    login: {
      jwt: { secret: 'MY JWT SECRET' }
    }
  }
})

const server = new (require('koa'))()
  .use(router.middleware())
  .listen(1337)

Full:

const { create } = require('@appliedblockchain/mantle-auth/router')
const { createRoute } = require('@appliedblockchain/mantle-auth/routes/login')
const { setAdapter } = require('@appliedblockchain/mantle-auth/storage/adapters')
const PsqlAdapter = require('@appliedblockchain/mantle-auth/storage/adapters/psql')

const router = create({
  routeList: [
    createRoute({
      jwt: { secret: 'MY JWT SECRET' }
    })
  ]
})

const adapter = new PsqlAdapter({
  dbNameMap: { table: 'admin_user' },
  connection: {
    database: 'mydb',
    host: 'localhost',
    password: 'pass',
    port: 5432,
    user: 'user'
  }
})

setAdapter(adapter)

const server = new (require('koa'))()
  .use(router.middleware())
  .listen(1337)

Middleware

const {
  handle: { jwt },
  middleware
} = require('@appliedblockchain/mantle-auth/middleware/authorization')

const checkAuth = middleware({ handle: jwt('MY JWT SECRET') })

const server = new (require('koa'))()
  .use(checkAuth)
  // other routes go here
  .listen(1337)

Development

See Development.md

mantle-auth's Issues

The array definition of the `returning` selector for the login route doesn't seem to be working

When defining a login route in the following context:

const { create } = require('@appliedblockchain/mantle-auth/router')
const { createRoute } = require('@appliedblockchain/mantle-auth/routes/login')
const { setAdapter } = require('@appliedblockchain/mantle-auth/storage/adapters')
const PsqlAdapter = require('@appliedblockchain/mantle-auth/storage/adapters/psql')

const router = create({
  routeList: [
    createRoute({
      jwt: { secret: config.get('jwt.jwtSecret') },
      returning: [ 'name', 'surname', 'email'  ]
    })
  ]
})

The login response does not include the user object, while passing a function as the selector works fine:

createRoute({
      jwt: { secret: config.get('jwt.jwtSecret') },
      returning: (userMap) => {
        return {
          fullName: `${userMap.name} ${userMap.surname}`,
          email: userMap.email
        }
      }
    })

Am I doing something wrong or is the array selector not synchronously injecting the attributes in the response?

JWT being sent as response - use server-side cookie instead?

The login endpoint currently returns a JWT - this promotes doing something like storing the jwt client-side in an insecure location like local/session storage/client-side cookies etc, which are vulnerable to XSS attacks.

Is it worth looking into setting a server-side cookie with httpOnly enabled to make the login more secure?

The 'joi-definition' exclude function does not work for routes with a path that contains regex or named parameters

Can't control the hashing method that the login route uses to verify passwords

The current implementation only works if passwords are stored hashed with a specific algorithm; Really the user should be able to use whatever hashing method they want and configure mantle-auth to work with it.