Xiongxiong

Bearer token codec.

Installation

Install from NPM:

npm install xiongxiong

Xiongxiong?

"熊" (xiong, /ɕjʊ̌ŋ/) is Mandarin Chinese for "bear" (as in the mammal). Reduplication in Mandarin acts as a diminutiviser, so "熊熊" means something like "little bear".

Bear, bearer, bearer token... Yeah, it's tenuous, but deal with it!

Documentation

The module must be instantiated with a private key and, optionally, a token lifetime (in seconds; defaults to 3600) and hashing algorithm (defaults to sha1). These can be provided as positional arguments, or as a hash.

For example:

var fs         = require('fs'),
    privateKey = fs.readFileSync('/path/to/private.key');

var xiongxiong = require('xiongxiong')(privateKey, 3600, 'md5');

...or:

var xiongxiong = require('xiongxiong')({
  privateKey: 'My hovercraft is full of eels!',
  lifetime:   300,
  algorithm:  'whirlpool'
});

The private key can be any buffer or string; it needn't be read from the filesystem (but that's probably a good idea). A simple key generation script is also provided (see below).

An error will be thrown if the specified hashing algorithm is not supported by your system.

xiongxiong.encode(data, callback)

Alias xiongxiong.create

Asynchronously encode the bearer token generated by the seed data and pass it to the callback. The callback follows the "error first" pattern, with any error in the first argument (null, otherwise) and the token data in the second.

The data provided to the function must be a string or an array of strings. In the latter case, the array is flattened with interposing : characters.

The token data available to the callback is a frozen hash, with keys:

• expiration The token's expiration time (Unix epoch)
• accessToken The token itself
• basicLogin Basic authentication login
• basicPassword Basic authentication password

basicLogin is the Base64 encoding of the seed data, with a cryptographic salt, as a fallback for when HTTP Bearer authentication is not available. basicPassword is the HMAC of basicLogin with the private key using the specified hashing algorithm. The accessToken is simply these two pieces concatenated, again with an interposed :.

For example:

xiongxiong.encode([userName, sessionID], function(err, token) {
  if (err) {
    throw err;
  }

  console.log(JSON.stringify(token, null, '  '));
});

n.b., Don't put :s in your seed data; they act as delimiters and spurious ones will probably mess up with the validation.

xiongxiong.decode(accessToken)

xiongxiong.decode(basicLogin, basicPassword)

Alias xiongxiong.extract

Decode the seed data, expiration and validate from the bearer token/basic authentication pair. Returns a frozen hash with the following keys:

• data The original seed data, which will be an array split by : characters, wherever possible (a string, otherwise).
• expiration The expiration time (Date object).
• valid The validity of the token/basic pair (Boolean).

For example:

var tokenData = xiongxiong.decode(someBearerToken);

if (tokenData.valid) {
  console.log('Token expires in %d seconds.',
              Math.floor((tokenData.expiration - Date.now()) / 1000));
}

The validity property (valid) will return false if the token can't be authenticated, otherwise it will test whether the token has passed its best before date.

Testing

A simple testing suite is defined in test.js, which can be run via NPM:

npm test

Decoders

Besides the codec for Node.js, other decoders are available for different languages and environments:

• Python (2 and 3)

n.b., These decoders are not available in the NPM repository, for brevity's sake, but can always be found on GitHub.

Made a decoder for your favourite language? Then why not submit a pull request!

Decoder Testing

If you plan on writing a decoder, then the getTestToken.js script will be of interest to you. This is a tokeniser implementation, using Xiongxiong, that reads JSON from standard input and outputs the JSON token data (per the above) to standard output. It can thus be called easily to create tokens to test against with your own decoder implementations.

Usage:
getTestToken.js KEY [LIFETIME] [ALGORITHM]

Options:
  KEY        The private key, in plain-text or a file path
  LIFETIME   Token lifetime, in seconds (default 3600)
  ALGORITHM  HMAC hashing algorithm (default sha1)

Note that the JSON input must be a string or an array of strings. Otherwise, or if the tokeniser fails for any other reason, a non-zero exit code will be rendered.

make-key.sh

A simple wrapper script around dd to create a private key file from /dev/random.

Usage:
make-key.sh [OPTIONS]

Options:
  -s SIZE     Key size, in bytes (default 256)
  -o KEYFILE  Key file (default private.key)
  -h          This useful message

License

Copyright (c) 2014, 2015 Genome Research Limited

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses/.