node-selftoken

node-selftoken

Generation and verification of integrity-protected and time-constrained tokens usable when directing a user through a web-based workflow.

For example, web pages part of the workflow can include a hidden form input field to pass validated context information from one page to another when the user completes a submission:

<form method="POST">
  <input type="hidden" name="continue" value="#token#">

</form>

Tokens generated by node-selftoken are inspired to the principles set forth with JWS and JWT. However, they deliberately differ from the JOSE standards for the following reasons:

• The target use case assumes that the tokens are both generated and validated by the same server, thus making unnecessary any type of header/descriptor embedded in the tokens themselves;
• The target use case requires a moderate level of protection, which can be achieved with a limited number of options.

Tokens generated by node-selftoken are integrity-protected, not encrypted. The input string is obfuscated through the use of URL-safe base64 encoding but remains accessible. Integrity-protection is provided through a SHA-256 HMAC. The HMAC key is derived from a 32-octet long-term password using PBKDF2 with SHA-256 digest. A new 16-octet salt is randomly generated for each new token and embedded in the token itself.

Installation

$ npm install node-selftoken

The package has no dependencies.

Token handler instantiation

Instantiate a selftoken handler as follows:

const TokenHandler = require('node-selftoken');

var options: {
  tokenLifecycle: 180,
  pbkdf2Iterations: 1,
  hmacLength: 16
}

var selftoken = new TokenHandler(options);

If the options object is omitted, then default values are used for all the parameters.

The following options are defined:

Options	Use
tokenLifecycle	Validity of the tokens in seconds; default value is 180 seconds (3 minutes). Token validation fails after the token lifecycle has expired. Enforcement of time validity is disabled if tokenLifecycle is equal to 0. This choice may be suitable if the input string already contains a timestamp which is checked elsewhere in the server code
pbkdf2Iterations	Number of SHA-256 iterations used to derive the HMAC key from the long-term password; default value is 1 to save resources; a decent level of protection of the long-term password is anyhow provided by the use of a different random salt at each token generation
hmacLength	Number of SHA-256 HMAC octets that are actually used; default value is 16 (HMAC truncated to 16 octets); allowed values are in the range [16..32]

The long-term password is auto-generated when the token handler is instantiated. Therefore, there is no option to configure it.

Token handler use

All the APIs are asynchronous.

selftoken.generate(inputString, callback)

---

The callback returns either an error or the newly generated token. Example:

selftoken.generate(inputString, (error, token) => {

  console.log('Here is the token:', token);

});

There are no plausible reasons for errors if the token generation API is correctly called with a string as input parameter. Therefore, the error return value can be loosely managed.

selftoken.verify(token, callback)

---

The callback returns either an error or the validated string extracted from the token. Example:

selftoken.verify(token, (error, outputString) => {

  console.log('Here is the validated string:', outputString);

});

Note than token validation fails - and an error is returned - both in case the token has been tampered and in case the token has expired.

selftoken.verify(token, (error, outputString) => {
  if (error && error.message === 'Expired token') {
    // Expired token

  } else if (error) {
    // Tampered token

  } else {
    // validated outputString

  }
});

One case in which a web workflow token may expire if when the user leaves the workflow unattended for longer than acceptable (e.g. by not completing a form submission). Therefore, the most common reaction to an expired token is to direct the user back to the beginning of the workflow and start again.

Token length

For a given string, tokens generated by node-selftoken have size comparable to that of the base64-encoding of the string. The following example can be used for reference.

Object to be conveyed through the token:

var example = {
  transactionId: '123e4567-e89b-12d3-a456-426655440000',
  paymentId: '550e8400-e29b-11d4-a716-446655440000',
  user: 'mailto:[e-mail]'
}

The use of JSON.stringify(example) produces a 148-character string, which represents the payload of the token.

var payload = JSON.stringify(example);

console.log(payload.length);
// 148

console.log(Buffer.from(payload).toString('base64').length);
// 200

selftoken.generate(payload, (error, token) => {
  console.log(token);
  // eyJwIjoie1widHJhbnNhY3Rpb25JZFwiOlwiMTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjU1NDQwMDAwXCIsXCJwYXltZW50SWRcIjpcIjU1MGU4NDAwLWUyOWItMTFkNC1hNzE2LTQ0NjY1NTQ0MDAwMFwiLFwidXNlclwiOlwibWFpbHRvOmphY2suc3BhcnJvd0BleGFtcGxlLmNvbVwifSIsImUiOjE0NzgxNDU5MDU1MzB9.Cp8jJnUiR4YQXnAnGmtnI8NyCBU6JwCU5xjKmBrgDAk
  console.log(token.length);
  // 292 (with tokenLifecycle > 0 and default hmacLength)
});

The longer the payload, the more negligible the difference in size between the token and the simple base64-encoding.