Tokenstore

Session tokens for Node.js

Version: 0.0.4

Use Case

Use Tokenstore to create tokens for your app to issue to a client.

Each token stores a reference to your entity ids and a JSON blob. Use them to map a token to entities in your system.

Tokenstore uses Redis to store tokens and data.

Install

npm install tokenstore

Usage

var config = {
  prefix: 'token',
  redis: {
    host: '127.0.0.1',
    port: 6379
  }
};
var Tokenstore = require('tokenstore');
var tokens = Tokenstore(config);

All config fields are optional. The defaults are shown in the config above. If you don't pass in a config object the defaults will be used.

var opts = {
  owner_id: 'some-id',
  attrs: {foo: 'bar'}
};
tokens.add(opts, function(err, res){
  // res = {token: 'xxx...'}
}

When you make the token, you need to supply an owner_id (this will map to user_id or something similar in your database -- a unique ID for the entity the token is being issued for.

attrs is arbitrary JSON. Probably best you keep it short.

The part of your app that uses Tokenstore should be using attrs as a starting point for a database query to get full details on the entity.

API

• reset
• quit
• add
• getKey
• get
• set
• del
• delKey
• list
• makeHash
• getHash
• delHash

All methods take a callback that is called with err and result.

Deletes all data

Closes the Redis connection and exits.

Adds a token and passes a key for you to reference the saved data.

token is an object describing what data to save

{ key: 'xxxx', // optional to force the use of a specific key
  owner_id: 'xxxx',
  attrs: {} }

Generally you will not supply key -- Tokenstore will make one for you. keys are 24 characters, generated by the uid2 module as uid(24).

owner_id is an arbitrary string. It is intended to be a uuid.

attrs is a plain javascript object. It will be stringified and stored in Redis.

The option to provide a key exists so you can recreate tokens if required. e.g. for restoring a lost database. The key you supply must conform to the the length requirement (default is 24 characters).

The done callback will be passed (err, token). Token is an object like {key: 'xxxxxxxxxxxxxxxxxxxxxxxx'} containing the generated key.

Example returned token:

{ owner_id: 'testowner',
  attrs: { foo: 'bar' },
  key: 'BRRljWrPjD3OLEHHvy2vMFiA',
  id: '47fcb93b-34ed-4790-96d9-b6570f08626e' }

ids are provided so you can reference tokens without exposing the key. Your app should be presenting ids when talking to the user about tokens (e.g. listing all tokens you have issued them in a management screen). keys should only be used at the transport layer.

Give you the token object found by key.

Example

{ owner_id: 'testowner',
  attrs: { foo: 'bar', baz: 'quxx' },
  key: 'BeCLPziIdGDjAI3pKUPz3Tfg',
  id: '96ced110-a499-4b8f-940d-b4849e7f9738' }

Give you the token object found by token_id.

Overwrites the existing attrs object of token_id.

Deletes token by key.

Deletes token id by token_id.

Gives done an array of tokens owned by owner_id.

Example:

[ { key: 'forced678901234567890123',
    owner_id: 'testowner',
    attrs: { ping: 'pong' },
    id: 'c3b575f1-06ce-48fb-ac30-9ff50413560d' },
  { owner_id: 'testowner',
    attrs: { foo: 'bar', baz: 'quxx' },
    key: 'BeCLPziIdGDjAI3pKUPz3Tfg',
    id: '96ced110-a499-4b8f-940d-b4849e7f9738' } ]

The Hash commands allow you to store some data and get back a hash referencing it.

Pass in your value, an optional ttl in seconds (hash will expire after this many seconds) and you will be given back an 8 character hash.

done(err, hash)

You can use this to implement things like Lost My Password system. Once you have looked up a user by email address, makeHash, email them the hash. Then you can use getHash to confirm they are valid and to look up their user details.

Pass in a hash created by makeHash and get back the data you passed in.

done(err, val)

Delete the hash and it's data.

Hacking

Install and run the tests

git clone [email protected]:simonswain/tokenstore.git
cd tokenstore
npm install
grunt

Release History

• 27/10/2014 0.0.2
• 04/11/2014 0.0.3
• 26/02/2015 0.0.4 Removed Hiredis

License

Copyright (c) 2014 Simon Swain

Licensed under the MIT license.