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

| 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.