Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

authomatic

Package Overview
Dependencies
Maintainers
2
Versions
5
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

authomatic

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

  • 1.0.2
  • latest
  • Source
  • npm
  • Socket score

Version published
Maintainers
2
Created
Source

authomatic

Build Status Maintainability

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

signPromise.<Tokens>

Returns access and refresh tokens

verifyString

Verifies token, might throw jwt.verify errors

refreshPromise.<Tokens>

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

invalidateRefreshTokenPromise.<Boolean>

Invalidates refresh token

invalidateAllRefreshTokensPromise.<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
ParamTypeDescription
userIdString
secretSecret
[content]Objectuser defined properties
[prolong]Booleanif 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]SignOptionsOptions to be passed to jwt.sign

verify ⇒ String

Verifies token, might throw jwt.verify errors

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

ParamTypeDescription
tokenString
secretSecret
[verifyOptions]VerifyOptionsOptions 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:

ParamTypeDescription
refreshTokenString
accessTokenString
secretSecret
signOptionsSignOptionsOptions 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:

ParamType
refreshTokenString

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
ParamType
userIdString

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

NameTypeDescription
accessTokenAccessToken
accessTokenExpiresAtNumberepoch
refreshTokenRefreshToken
refreshTokenExpiresAtNumberepoch

VerifyOptions : Object

Verify options to be used when verifying tokens

Kind: global typedef
Properties

NameTypeDescription
[audience]Array | Stringchecks the aud field
[issuer]String | Arraychecks the iss field
[ignoreExpiration]Booleanif true, ignores the expiration check of access tokens
[ignoreNotBefore]Booleanif true, ignores the not before check of access tokens
[subject]Stringchecks the sub field
[clockTolerance]Number | String
[maxAge]String | Number
[clockTimestamp]Numberoverrides the clock for the verification process

SignOptions : Object

The allowed user options to for signing tokens

Kind: global typedef
Properties

NameType
[nbf]Number
[aud]Array | String
[iss]String
[sub]String

RefreshTokenNotFound : StandardError

The refresh token was not found.

Kind: global typedef
Properties

NameTypeDefault
[name]String'RefreshTokenNotFound'

TokensMismatch : StandardError

The tokens provided do not match

Kind: global typedef
Properties

NameTypeDefault
[name]String'TokensMismatch'

InvalidToken : StandardError

The provided input is not a valid token.

Kind: global typedef
Properties

NameTypeDefault
[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){...}
  1. 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) {...}
  1. 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.

Keywords

FAQs

Package last updated on 08 Feb 2022

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc