@jumpitt/retake NPM

Retake : REacT sAfe toKEn

Retake is a highly opinionated and experimental API auth package for Koa

This package saves your access_token ,refresh_token in a database of your election and returns a UUID through a cookie you can use in a JS app

####Installation

npm i @jumpitt/retake

Add this to your index.js or similar file of your koa app

const Koa = require('koa');
const app = new Koa();
const Auth = require('@jumpitt/retake')
app.context.auth_id = 'any_string_you_want';

const auth = new Auth(app // -> Instance of your koa app, {
  baseURL: '' , // -> base url of your auth service,
  cookieName: 'uuid_session' // ->  The cookie name for your JS app ,
  authSuffix: 'oauth/token' // -> suffix for your service login,
  
  
  // Your service secrets
  secrets: {
    client_id: 123,
    client_secret: 1234,
  },
  // Your database credentials
  db: { 
    client: 'pg',
    connection: {
      host: 127.0.0.1,
      user: 'user',
      password: 'password',
      database: 'database',
      tableName: 'tokens' // -> any name you want to set your token table,
    },
  },
});

Required

This package needs a unique identifier to work app.context.auth_id = '' should be set before instantiation

This package needs a table in your database that is complaint with this db schema. Maybe you could leave some of the fields nullable but access_token , refresh_token , valid,ip, shouldn't

   table.uuid('id').unsigned().primary()'));
   table.string('access_token', 999).notNullable();
   table.string('refresh_token', 255).notNullable();
   table.string('scope', 255).notNullable();
   table.string('token_type', 255).notNullable();
   table.string('ip', 255).notNullable();
   table.boolean('valid').defaultTo(1 // -> true);
   table.integer('expires_in', 11).notNullable();
   table.timestamps(true, true);

Your Auth service

this package expects your service to respond with this schema/json when authenticating

{
 "access_token": "",// -> required
 "token_type": "Bearer",// -> optional
 "expires_in": 3600 // -> optional,
 "refresh_token": "" // -> required,
 "scope": "users:r" // -> optional
}

####Usage

In this code example im using koa-router and koa-body

After instantiation this package exposes 3 routes

login
logout
refresh

this routes control the auth flow of your app and they accept a callback The callback is neccesary because all the routes are awaiting a next() method. In the case you miss the callback the route will render a http 404

const Router = require('koa-router')
const kb = require('koa-body')

const router = new Router() //- > Koa router

router.post('/login', kb(), auth.login, ctx => {
  ctx.status = 201;
  ctx.body = 'Success';
});
router.post('/logout', auth.logout, ctx => {
  ctx.status = 200;
  ctx.body = 'Success';
});
router.post('/refresh', auth.refresh, ctx => {
  ctx.status = 200;
  ctx.body = 'Success';
})

####Retrieving the token

This package also has a method to get the token. When ctx is available you will have a way to retrieve the token with this method

router.get('/user', kb(), async (ctx) => {
   const uuid = ctx.cookies.get('uuid_session');
   if (!uuid) {
    ctx.throw(401, 'Unauthorized');
   }
   //This is where we use the unique identifier that was set before
   const { access_token, valid } = await ctx[ctx.auth_id].token(uuid); 
})

Now we are using our auth_id context to get our token

A note on the database client

This package uses knex to connect to your database. That means if you want to use a client you have to install the dependency. You can pick one of these to use with this package

# add a --save flag
$ npm install pg
$ npm install sqlite3
$ npm install mysql
$ npm install mysql2
$ npm install oracle
$ npm install mssql

A note on UUID

In the case of Postgres before using uuid an extension should be installed CREATE EXTENSION IF NOT EXISTS "uuid-ossp";. This returns a uuid instead of a regular id which is more safe

In the case of other clients/engines it should be kinda like the same method.

####Todos