next-key-server

Handles authentication in the server, you usually don't need to use this package directly, instead choose an http implementation of this package

• next-key-micro: Handles authentication for Micro.js, Micro is almost the same as a basic http server
• next-key-express: Handles authentication for Express

How to use

Install it with npm or yarn

npm install next-key-server

Create a new instance of the authentication server

import { AuthServer } from 'next-key-server'
// this works too
// import AuthServer from 'next-key-server'

const AuthServer = new AuthServer({ ... })

API

AuthServer

constructor(options: AuthServerOptions<CookieOptions>): AuthServer

AuthServerOptions accepts the following fields:

accessToken

required

This is the accessToken implementation that will be used by your server

accessToken: AuthAccessToken<CookieOptions>

AuthAccessToken<CookieOptions> is an interface defined here and accepts the following fields:

accessToken.cookie

Name of the cookie for the accessToken, only used by http implementations of this package

accessToken.cookieOptions

Cookie options that will be used before creating or removing an accessToken as a cookie, it can be a function that receives the accessToken and returns the cookie options, the function will receive an empty string when removing. Only used by http implementations of this package

cookieOptions?: CookieOptions | ((accessToken: string) => CookieOptions);

accessToken.getPayload

Returns the payload that will be used for an accessToken based in data, not defining this method will leave data as the payload

getPayload?(data: { [key: string]: any }): { [key: string]: any }

accessToken.create

Creates the accessToken

create?(payload: { [key: string]: any }): Promise<string>

accessToken.verify

Verifies an accessToken and returns its payload

verify?(accessToken: string): { [key: string]: any }

refreshToken

This is the refreshToken implementation that will be used by your server, is very similar to accessToken and it's not required

refreshToken?: AuthRefreshToken<CookieOptions>

AuthRefreshToken<CookieOptions> is an interface defined here and accepts the following fields:

refreshToken.cookie

Name of the cookie for the refreshToken, only used by http implementations of this package

refreshToken.cookieOptions

Cookie options that will be used before creating or removing an refeshToken as a cookie, it can be a function that receives the refeshToken and returns the cookie options, the function will receive an empty string when removing. Only used by http implementations of this package

cookieOptions?: CookieOptions | ((refreshToken: string) => CookieOptions);

refreshToken.getPayload

Returns the payload in a refreshToken that can be used to create a new accessToken, the first parameter is the refreshToken and the second a reset function that can be used to refresh the cookie saved for the refreshToken

getPayload(
  refreshToken: string,
  reset: () => void
): Promise<{ [key: string]: any } | void

refreshToken.create

Creates a refreshToken

create(data: { [key: string]: any }): Promise<string>

refreshToken.remove

Removes a refreshToken

remove(refreshToken: string): Promise<boolean> | boolean

payload

default: new Payload()

This allows you to modify the payload before saving it to the accessToken and parse it back too. The default behaviour will leave the payload as it is, look at Payload to see what can you do with it

payload?: AuthPayload = new Payload()

scope

default: new Scope()

Manages a scope for the accessToken, to see how it works look at Scope

scope?: AuthScope = new Scope()

After creating an instance of AuthServer the following methods are available

createAccessToken(data)

Creates a new accessToken, data is the user that will be saved as the payload of the accessToken, it returns an object with the accessToken and resulting payload inside

createAccessToken(data: { [key: string]: any }): {
    accessToken: string;
    payload: { [key: string]: any };
}

createRefreshToken(data): Promise<string>

Creates a new refreshToken, it returns a Promise that resolves with the refreshToken

createTokens(data)

Creates both accessToken and refreshToken, it returns a Promise that resolves with the tokens in an object

createTokens(data: { [key: string]: any }): Promise<{
  refreshToken: string;
  accessToken: string;
  payload: StringAnyMap;
}>

verify(accessToken: string): { [key: string]: any } | null

Decodes and returns the payload of an accessToken

removeRefreshRoken(refreshToken: string): boolean | Promise<boolean>

Removes an active refreshToken

Payload

constructor(payload: { [key: string]: string }): AuthPayload

Aims to rename the keys of an accessToken payload, useful for example if you want to have shorter keys in the payload.

payload receives an object where the key is the key you want to have and the value is the actual key

import { Payload } from 'next-key-server'

const userPayload = {
  id: 'user_123',
  companyId: 'company_123',
  scope: 'a:r:w',
  name: 'Luis'
}

const tokenPayload = {
  uId: 'user_123',
  cId: 'company_123',
  scope: 'a:r:w'
}

const payload = new Payload({
  uId: 'id',
  cId: 'companyId',
  scope: 'scope'
})

payload.create(userPayload) // -> tokenPayload

payload.parse(tokenPayload) // -> userPayload without 'name'

Keys not defined in payload will be excluded after create()

AuthServer will use create() and parse() for you

Scope