authomatic

    1.0.2 • Public • Published

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

    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:

    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:

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

    Install

    npm i authomatic

    DownloadsWeekly Downloads

    10

    Version

    1.0.2

    License

    MIT

    Unpacked Size

    46.9 kB

    Total Files

    12

    Last publish

    Collaborators

    • amri
    • warp-admin