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

sign ⇒ Promise.<Tokens>

Returns access and refresh tokens

verify ⇒ String

Verifies token, might throw jwt.verify errors

refresh ⇒ Promise.<Tokens>

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

invalidateRefreshToken ⇒ Promise.<Boolean>

Invalidates refresh token

invalidateAllRefreshTokens ⇒ Promise.<Boolean>

Invalidates all refresh tokens

Typedefs

Secret : String

a string greater than 20 characters

AccessToken : String

Regular JWT token. Its payload looks like this:

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

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"
 }

Tokens : Object

Token pairs

VerifyOptions : Object

Verify options to be used when verifying tokens

SignOptions : Object

The allowed user options to for signing tokens

RefreshTokenNotFound : StandardError

The refresh token was not found.

TokensMismatch : StandardError

The tokens provided do not match

InvalidToken : StandardError

The provided input is not a valid token.

sign ⇒ Promise.<Tokens>

Returns access and refresh tokens

Kind: global variable
Throws:

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

Param	Type	Description
userId	String
secret	Secret
[content]	Object	user defined properties
[prolong]	Boolean	if true, the refreshToken will last 4 days and accessToken 1 hour, otherwise the refresh token will last 25 minutes and the accessToken 15 minutes.
[signOptions]	SignOptions	Options to be passed to jwt.sign

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

Param	Type	Description
token	String
secret	Secret
[verifyOptions]	VerifyOptions	Options to pass to jwt.verify.

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

Param	Type	Description
refreshToken	String
accessToken	String
secret	Secret
signOptions	SignOptions	Options passed to jwt.sign, ignoreExpiration will be set to true

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

Param	Type
refreshToken	String

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

Param	Type
userId	String

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

Name	Type	Description
accessToken	AccessToken
accessTokenExpiresAt	Number	epoch
refreshToken	RefreshToken
refreshTokenExpiresAt	Number	epoch

VerifyOptions : Object

Verify options to be used when verifying tokens

Kind: global typedef
Properties

Name	Type	Description
[audience]	Array | String	checks the aud field
[issuer]	String | Array	checks the iss field
[ignoreExpiration]	Boolean	if true, ignores the expiration check of access tokens
[ignoreNotBefore]	Boolean	if true, ignores the not before check of access tokens
[subject]	String	checks the sub field
[clockTolerance]	Number | String
[maxAge]	String | Number
[clockTimestamp]	Number	overrides the clock for the verification process

SignOptions : Object

The allowed user options to for signing tokens

Kind: global typedef
Properties

Name	Type
[nbf]	Number
[aud]	Array | String
[iss]	String
[sub]	String

RefreshTokenNotFound : StandardError

The refresh token was not found.

Kind: global typedef
Properties

Name	Type	Default
[name]	String	'RefreshTokenNotFound'

TokensMismatch : StandardError

The tokens provided do not match

Kind: global typedef
Properties

Name	Type	Default
[name]	String	'TokensMismatch'

InvalidToken : StandardError

The provided input is not a valid token.

Kind: global typedef
Properties

Name	Type	Default
[name]	String	'InvalidToken'

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.