kitten-jwt

Kitten JWT

Keep It Simple, Stupid, Secure and Fast JWT module

Maintained by https://www.easilys.com and https://carbone.io

Philosophy and why

• Keep it Simple Stupid
• Performance & Security focused
• Light, low dependency

Most of the time, people uses node-jsonwebtoken and express-jwt without using a cache mechanism to verify tokens. This requires a lot of CPU for each request on server-side! On client-side, the token is generated once with an infinite expiration timestamp, which is not very secure. The first purpose of this module is to solve these two problems.

When discovering JWT, you do not know what signing algorithm to choose and where to put your data (issuer, audience, ...). This module solves this for you. It chooses a highly secured algorithm by default. If you want another algorithm, fork it.

To save extra bandwidth, it let you define only two parameters : a client id ("Alice", issuer), and a server id ("Bob", audience). The generated token allows only Alice (clientId) to speak exclusively to Bob (serverId).

Main purpose : be plug'n'play for developers who do not have a lot of time.

Features

• Follows JWT RFC
• Ultra-fast JWT generator with automatic renewal every 12-hours for client side: 1 Million per second
• Ultra-fast JWT verification using LRU-cache for server side: 0.5 Million per second
• Fastify, Restify or Express authentication middleware
• Highly secured by default with assymetric ECDSA keys (ES512)
• ECDSA Public / Private key generator

Installation

  npm install kitten-jwt --save

Getting started

• On client-side

  var jwt = require('kitten-jwt');

  // Generate an ephemeral jwt token (short expiration date), auto-renewed every 12-hour by default
  // This function is very fast (uses cache), it can be called for every HTTP request
  var header = jwt.getToken('client-id-1220202', 'server-app-name', 'privKeyOfTheClient');

  // Insert the token in HTTP Header, it will be parsed by jwt.verifyHTTPHeaderFn automatically
  request.setHeader('Authorization', 'Bearer ' + header);

• On server-side

  var jwt = require('kitten-jwt');

  // custom method to get the client public key, kitten-jwt caches the result automatically
  function getPublicKeyFn(req, res, payload, callback) {
    var _clientId = payload.iss;
    // do whatever you want: db query, file read
    return callback('pubKeyOfTheClient');
  }

  // use the helper function to verify token in an express middleware
  // This function is very fast (uses lru-cache)
  express().use(jwt.verifyHTTPHeaderFn('server-app-name', getPublicKeyFn));

  // if the public key changes
  jwt.resetCache();

  // In other middleware, you can print JWT payload object, added by verifyHTTPHeaderFn
  console.log(req.jwtPayload);

API Usage

Token generated by kitten-jwt are quite compact (limited) for performance reasons, and follows JWT RFC

• header

  {
    alg : 'ES512',
    typ : JWT
  }

• payload

  {
    iss  : clientId,                  // issuer
    aud  : serverId,                  // audience, tenand id, etc...
    exp  : (Date.now() + expiresIn)   // expiration timestamp UTC
  }

Why it is important to have a serverId? If the audience is not defined, the same token can be used for another web-service which have the same clientId and public key.

High-level API

These functions uses cache to be as fast as possible

• jwt.getToken (clientId, serverId, privKey)

  Generate a token for the tuple clientId-serverId, which expires in about 12 hours (+- random)
  Re-use this same token during about 12 hours if called more than twice
  Generate a new token automatically before expiration (20-minute before) or if privKey change

  • clientId : JWT issuer, token.iss
  • serverId : JWT audience, token.aud
  • privKey : private key

• jwt.verifyHTTPHeaderFn (serverId, getPublicKeyFn)

  Generate a function(req, req, next)
  Set req.jwtPayload

  • getPublicKeyFn : Function(req, res, payload, callback) which returns publicKey in callback(pubKey)
  • serverId : JWT audience, token.aud if the token is invalid, next(err) is called. Thus you can catch the error in another 4-parameter middlewares.

• jwt.resetCache (clientId, callback) : invalidate cache

Low-level API

These APIs should not be used direclty in a web app because nothing is cached (slow).

• jwt.generate (clientId, serverId, expiresIn, privKey, data) : generate a token

  • clientId : JWT issuer, token.iss
  • serverId : JWT audience, token.aud
  • expiresIn : JWT duration in number of seconds
  • privKey : private key
  • data : accessible in token.data

  It returns a signed base64 url encoded string of the token.

• jwt.verify (jwt, pubKey, callback) : verify the signature of a token

  • jwt : JSON Web token string to verify
  • pubKey : public key
  • callback (err, payload) : callback, payload is an object

• jwt.generateKeys (outputDir, outputKeyName) : generate pub / priv ECDSA keys

Notes

TODO :

• blacklist IP which send too many bad token
• to save extra bandwithh: kitten-jwt accepts and generate tokens with one-letter header instead of RFCs JWT header (optional)
• make expiration a little bit random
• should i use https://en.wikipedia.org/wiki/Curve25519 ? https://weakdh.org/imperfect-forward-secrecy-ccs15.pdf https://www.npmjs.com/package/sodium https://github.com/volschin/node-curve25519 https://ianix.com/pub/curve25519-deployment.html