strajah-token v2.0.4

cipherToken

A method to create ciphered accessToken based on the following principles:

• must include id information.
• must include expiration information.
• must be a designed token to transport, but not to store it.

NodeJS

Require

const cipherToken = require('cipherToken');

Usage

cipherToken is designed to be used as a module.

Initiate the token generator for a set of settings

const accessTokenCreator = cipherToken(settings);

Tokens are created this way

const cipheredToken = accessTokenCreator.create.userId('my-id12').data({'some': 'data'}).encode();

and can be decoded back to a more readable state with

const decodedToken = accessTokenCreator.decode(cipheredToken);

Settings

Settings is a hash with the following properties

• cipherKey : (required) used to cipher the accessToken
• firmKey : (required) used to firm the accessToken
• tokenExpirationMinutes : minutes of accessToken life (90 minutes by default)
• cipherAlgorithm : algorithm used to cipher the token (aes-256-cbc by default)
• hmacAlgorithm : algorithm used to build the hmac (md5 by default)
• hmacDigestEncoding : encoding used in the outbound of the hmac digest (hex by default)
• plainEncoding : encoding used in the data content in the token (utf8 by default)
• tokenEncoding : encoding used in the token format (base64 by default)
• enableSessionId : sessionId of an accessToken, can be preset at accessToken creation

Settings must be passed to cipherToken in each call. Only cipherKey and firmKey are required.

Create tokens

First thing you need is a cipherToken for your settings

const accessTokenCreator = cipherToken(settings);

After that you'll create a set for a given user which will contain data to be encoded in the token

const cipheredToken = accessTokenCreator.set.userId('my-id12').data({'some': 'data'}).sessionId('my-previous-session-id').encode();

UserId can be an username or any other thing you use to identify your customers. SessionId is only to be submitted when you want to create a token associated to the same session of another token (usually near expiration). If you have enableSessionId in your settings enabled but that's the first time creating a token for a new session, then you don't need to use the method 'sessionId' and a random UUID v4 will be generated. Data is to encode the payload you want to travel with the token.

The result, cipheredToken, is an object which for now has only two properties

• token: contains the token itself
• error: only when there was an error during encoding process

Decode tokens

You'll need an accessTokenCreator (still looking for a better name) initialized with the same settings as the ones used in the encoding process

const decodedToken = accessTokenCreator.decode(validToken.token);

decodedToken has the following properties

• set: the data encoded within the token, contains: userId, expiresAtTimestamp, data and sessionId if enabled
• error: if an error occurred during decoding

The only one added by cipherToken is expiresAtTimestamp: at creation, gets the actual time and add to it the time expiration to calculate when will the token expire. Cipher token doesn't care if the token has expired or not.

Example

const cipherToken = require('cipherToken');

const settings = {
    cipherKey: 'myCipherKey123',
    firmKey:  'myFirmKey123'
};

const accessTokenCreator = cipherToken(settings);

const cipheredToken = accessTokenCreator.create.userId('John Spartan').data('validData').encode();
const decodedToken = accessTokenCreator.decode(cipheredToken);

console.log(decodedToken.set.userId)
console.log(decodedToken.set.expiresAtTimestamp)
console.log(decodedToken.set.data)
console.log(decodedToken.set.sessionId)