Signed Object

A config driven tool for signing objects, using the same algorithm implemented by Facebook.

Install

$ npm install signed-object --save

Documentation

'new Vault(options)'

options {Object}

Optional. This defaults to your config.signedObject options, and is extended by the passed options. Hence, this can be entirely maintained solely within your config settings.

• secret {String OR Function}

The secret is used a cryptographic HMAC key. This ensures that your payload cannot be tampered with, as any changes will result in a signature that doesn't match the one produced against your secret.

If a function is passed as the secret, every time sign or verify are invoked, the secret function will be called with the signature (data, cb), where data is the object being signed or verified. For example, this could be used to lookup a secret based off of a key present in your object. When using a function instead of a string, sign and verify both will return promises.

• ttl {Number}

Optional. If present, any signed object that doesn't already contain an expires property will be appended with a Unix Timestamp relative to the current time, and TTL (Time to Live). This uses milliseconds.

Vault.prototype.sign(data)

Sign the given object, according to options. This will return a string that can be publicly passed around and later verified securely.

Vault.prototype.verify(data)

Sign the given string, according to options. This will return an object if valid, otherwise undefined.

Vault.prototype.inspect(data)

inspects the given signed string, returning it's body as an object regardless of wether it's valid.

Example A

// .
// ├── config
// │   ├── default.json
// │   └── test.json

// test.json
// {
//  ...
//   "signedObject" : {
//     "secret" : "2xYJR\"&QNV6#t4B23*W4Yv5$\"TL),aLsTz9H0(v8d0+zJO8ulw4v495haK*'RD1b",
//     "ttl" : 3600000
//   },
//   ...
// }

var vault = require('signed-object')();

var signed = vault.sign({
  decree: "Install me... and tip",
}); // 'zRWK61EWt66RgLlERkW7sxzJhmb7Rfvax67beDnPXd8.eyJleHBpcmVzIjoxNDM5NDI5Mzg2NzMyLCJkZWNyZWUiOiJJbnN0YWxsIG1lLi4uIGFuZCB0aXAifQ'

var verified = vault.verify(signed);

Example B

var client = require('redis-client-pool').utility;

var vault = require('signed-object')({
  secret: function( data, cb ) {
    client.hget('partner:keys', data.key, cb);
  }
});

...

vault.sign({
  decree: "I'm a little tea pot",
  key: 'https://gratipay.com/Bajix' // fill me up
}).nodeify(cb);

...

vault.verify(signed).nodeify(cb);