authomatic v1.0.2

authomatic

Description

An authentication library that uses JWT for access and refresh tokens with sensible defaults.

Install

npm install authomatic

Available stores

Redis

Please create an issue if you need another store.

Examples

Koa Example

Quickstart

const Store = require('authomatic-redis');
const Authomatic = require('authomatic');
const store = Store();
const authomatic = new Authomatic({store});

// Use authomatic functions

Test

npm test

Notes about migrating from version 0.0.1 to 1

1. Access and refresh tokens from those old versions will not work with the new ones. If you just upgraded, users will be required to relog. If that is undesirable, and you want a seamless transition use two instances of Authomatic, but do not sign new tokens (or refresh) with the old instance.
2. The refresh method now accepts a 4th argument, verify options.
3. The invalidate refresh token method now requires a secret.
4. aud in sign options and audience in verify options are now strictly an array.
5. RefreshTokenExpiredOrNotFound became RefreshTokenNotFound, the expiration error is throw by the 'jsonwebtoken' library.
6. InvalidAccessToken became InvalidToken, it is for both refresh and access tokens.
7. TokensMismatch error is thrown if refresh and access token do not match.

The example has been updated to reflect all the new changes.

Documentation

Members

Typedefs

sign ⇒ Promise.<Tokens>

Returns access and refresh tokens

Kind: global variable
Throws:

• TypeError typeError if any param was not sent exactly as specified

verify ⇒ String

Verifies token, might throw jwt.verify errors

Kind: global variable
Returns: String - decoded token
Throws:

• InvalidToken invalidToken
• TypeError typeError if any param was not sent exactly as specified
• JsonWebTokenError
• TokenExpiredError Error info at https://www.npmjs.com/package/jsonwebtoken#errors--codes

refresh ⇒ Promise.<Tokens>

Issues a new access token using a refresh token and an old token (can be expired).

Kind: global variable
Throws:

• RefreshTokenNotFound refreshTokenNotFound
• TokensMismatch tokensMismatch
• TypeError typeError if any param was not sent exactly as specified
• JsonWebTokenError
• TokenExpiredError Error info at https://www.npmjs.com/package/jsonwebtoken#errors--codes

invalidateRefreshToken ⇒ Promise.<Boolean>

Invalidates refresh token

Kind: global variable
Returns: Promise.<Boolean> - true if successful, false otherwise.
Throws:

• TypeError typeError if any param was not sent exactly as specified
• InvalidToken invalidToken
• JsonWebTokenError
• TokenExpiredError Error info at https://www.npmjs.com/package/jsonwebtoken#errors--codes

invalidateAllRefreshTokens ⇒ Promise.<Boolean>

Invalidates all refresh tokens

Kind: global variable
Returns: Promise.<Boolean> - true if successful, false otherwise.
Throws:

• TypeError typeError if any param was not sent exactly as specified

Secret : String

a string greater than 20 characters

Kind: global typedef

AccessToken : String

Regular JWT token. Its payload looks like this:

{
 "t": "Authomatic-AT",
 "uid": "userId",
 "exp": "someNumber",
 "jti": "randomBytes",
 ...otherClaims,
 "pld": {
   ...otherUserContent
 }
}

Kind: global typedef

RefreshToken : String

regular JWT token. Its payload looks like this:

{
  "t": "Authomatic-RT",
  "iss": "Authomatic",
  "aud": ["Authomatic"]
  "uid": "userId",
  "exp": "someNumber",
  "jti": "randomBytes",
  "accessTokenJTI": "randomBytes"
}

Kind: global typedef

Tokens : Object

Token pairs

Kind: global typedef
Properties

VerifyOptions : Object

Verify options to be used when verifying tokens

Kind: global typedef
Properties

SignOptions : Object

The allowed user options to for signing tokens

Kind: global typedef
Properties

RefreshTokenNotFound : StandardError

The refresh token was not found.

Kind: global typedef
Properties

TokensMismatch : StandardError

The tokens provided do not match

Kind: global typedef
Properties

InvalidToken : StandardError

The provided input is not a valid token.

Kind: global typedef
Properties

Creating a store

If you want to create a new store you need to expose the following functions:

1. add

/**
* Register token and refresh token to the user
* @param {String} userId
* @param {String} refreshTokenJTI
* @param {String} accessTokenJTI
* @param {Number} ttl time to live in ms
* @returns {Promise<Boolean>} returns true when created.
*/
function add(userId, refreshTokenJTI, accessTokenJTI, ttl){...}

2. remove

/**
* Remove a single refresh token from the user
* @param userId
* @param refreshTokenJTI
* @returns {Promise<Boolean>} true if found and deleted, otherwise false.
*/
function remove(userId, refreshTokenJTI) {...}

3. removeAll

/**
* Removes all tokens for a particular user
* @param userId
* @returns {Promise<Boolean>} true if any were found and delete, false otherwise
*/
function removeAll(userId) {...}

You may need to expose a reference to the store if the user may need to handle connections during testing for example.