authsux

A simple Node.js authentication library

npm install authsux
1 downloads in the last week
6 downloads in the last month

authsux

A simple Node.js authentication library

authsux follows a very basic HMAC & bearer token strategy.

Authentication Scheme

  • client public key
    • The client's publicly available key; sent with requests
  • client private key
    • The client's "secret" key; hidden from public view
  • bearer token
    • The user's bearer token; granted upon valid authentication
  • signature + timestamp
    • The signature for the request; a timestamp is appended to the end

Express Middleware Example

(You should be able to adapt this to your purposes)

  /* auth.js */

  var authsux = require('./path/to/authsux');

  // a helper function for retrieving a private key, given a public key
  authsux.helpers.getPrivateKey = function(publicKey) {
    // beyond the scope of this example
  }

  // a helper function to check whether a bearer token is valid
  authsux.helpers.isValidToken = function(token) {
    // beyond the scope of this example
  }

  // check for a valid public key and private key
  exports.checkKey = function(request, response, next) {
    if (authsux.hasValidKey(request.query)) {
      next();
    } else {
      response.writeHead(401, 'Unauthorized');
      response.end();
    }
  }

  // check for a valid signature
  exports.checkSignature = function(request, response, next) {
    if (authsux.hasValidSignature(request.query)) {
      next();
    } else {
      response.writeHead(401, 'Unauthorized');
      response.end();
    }
  }

  // check for a valid token
  exports.checkToken = function(request, response, next) {
    if (authsux.hasValidToken(request.query)) {
      next();
    } else {
      response.writeHead(401, 'Unauthorized');
      response.end();
    }
  }

You can then use the middleware like so:

  /* server.js */

  // ...

  var auth = require('./path/to/auth.js');

  // ...

  app.get('/foo', auth.checkToken, function() {
    // will only execute if the keys, token, and signature are all valid
  });

  app.post('/foo', auth.checkSignature, function() {
    // will only execute if the keys and signature are valid
  });

  app.put('/foo', auth.checkKey, function() {
    // will only execute if the keys are valid
  });

  app.del('/foo', function() {
    // performs no authentication
  });

  // ...

Obviously, you might want to add some additional security over top of this, but now you should hopefully have a good base to build upon. My hope is that it abstracts out some of the more mundane tasks - like checking your query parameters and building hashes - so that you can focus on adding more complexity to your security layer. Hopefully, I've provided this for you.

Configuration options

  • authsux.config.signatureField: the query field for the signature value (defaults to 'signature')
  • authsux.config.publicKeyField: the query field for the public key value (defaults to 'key')
  • authsux.config.tokenField: the query field for the token value (defaults to 'token')
  • authsux.config.hashAlgorithm: the crypto hash algorithm to use for the signature (defaults to 'sha256')
  • authsux.config.signatureExpiration: the time (in milliseconds) that the signature will expire (defaults to '300000' - 5 minutes)

Exports

  • authsux.config: configuration parameters (see above)
  • authsux.helpers: helper functions to be defined by the developer and used by authsux internals
  • authsux.sign: the function used to sign requests; accepts an array of query parameters and an optional timestamp
  • authsux.hasValidKey: checks for a valid public key and private key
  • authsux.hasValidSignature: checks for a valid signature; also checks hasValidKey
  • authsux.hasValidToken: checks for a valid token; also checks hasValidSignature

Future Plans

  • Support sending parameters in the header in addition to the query string

I hope you enjoy authsux. If you have any questions or concerns, please voice them!

Thanks,

MP

npm loves you