add capacity to decode by header-specified kid

[akdor1154]

The JWT header parameter kid can specify a key id with which the token should be verified. (JWT Spec). This PR adds this functionality to the library, by allowing the key parameter to decode to take a dictionary of {[keyId]: key}, and allowing the kid parameter of header to specify which key to decode with.

For example, if the header of token looks like

{ alg: 'RS256', kid: 'keyId123' }

then

jwt.decode(token, {keyId123: secret})

is equivalent to

jwt.decode(token, secret)

.

This is useful for interacting with third party JWT issuers, for example AWS Cognito. With these, you do not necessarily know which secret will be used to sign a token in advance. The only way to use these services with this library currently is

var header = JSON.parse(new Buffer(token.split('.')[0], 'base64').toString()) // can't get header with jwt-simple
var keys = getKeys() // say this returns { key1: 'key...', key2: 'key2...' }
var token = jwt.decode(token, keys[header.kid]);

Caveats

The kid parameter will generally refer to a key specified in an array of JWKs, which look like this. It's possible you might want the keys parameter to take an array of JWKs instead of the dictionary of {[kid]:key}. IMO it's not worth the complexity, but if you want me to change it to work like this then I can do that. Note however that this would add dependencies to this module as the conversion from JWK to pem is non-trivial.

[DevBrent]

If you were aiming for something, I would recommend JWKS but unfortunately most versions of Node don't support keys in the JWK format. I think as jwt-simple is designed to be simple, adding in JWKS support is a bit out of scope.

jwt-simple currently supports Node 0.5 or so it says.