express-simple-secure

Express middleware that only exposes a route (and response body) when the proper token is provided in the query string or header.

change log

Table of Contents

• Requirements
• Installation
• Example usage
• Options
• Environment variables
• Miscellaneous

Requirements

• Node >= v4
• Express >= v4

Installation

npm install --save express-simple-secure

Example usage

  var app = require('express');
  var simpleSecure = require('express-simple-secure');

  var options = {
    httpMethod: 'get',
    paramName: 'nickname',
    token: '007',
    caseSensitive: true,
    checkType: 'query',
    object: {firstName: 'James', lastName: 'Bond', company: 'MI6'},
    contentType: 'json'
  };

  // Via Express router
  var router = express.Router();
  router.get('/agent', simpleSecure(options));
  app.use('/secret', router);

  app.listen(3000, '0.0.0.0');

  // http://localhost:3000/secret/agent?nickname=007

Run npm run dev to test the above code.

Options

  var options = {
    object: null,
    token: '',
    method: 'get',
    paramName: 'key',
    caseSensitive: true,
    checkType: 'query'
  };

• object
  • Required
  • Defines a/n:
    • Object that will be returned as application/json in the body of the response
    • String that will be returned as text/html in the body of the response
    • A function that returns html or an object...

      function(){
        return '<h1>Meow</h1>';
      }

    or

      function() {
        return {
          message: 'Woof'
        };
      }

• token
  • Required
  • A general rule of thumb is make this a very long, strong password or guid
  • If a string value is provided, this will be the token that is checked against the appropriate checkType parameter
  • This is a 'security through obscurity' approach
  • If a falsy value is provided, the middleware will be skipped within the Express app
• method
  • Required
  • Valid values are: get, post, put, patch, options, delete, head, or any
• paramName
  • Optional
  • Default is key
  • When used with the checkType option it is the specific parameter to check against the token value
• caseSensitive
  • Optional
  • Default is true
  • Defines the case sensitivity of the token value actual vs. expected comparison
• checkType
  • Optional
  • Default is query
  • Defines where to check for the paramName defined parameter
  • Valid values are: query, header, or any

Miscellaneous

1. npm run dev # Runs sample app
2. DEBUG=express-simple-secure npm run dev # Runs sample app with debugging
3. npm run test # Runs all tests
4. npm run test-unit # Runs only unit tests
5. npm run test-integration # Runs only self-integration tests
6. npm run coverage # Runs istanbul coverage analysis
7. npm run test-prod # Runs all tests, coverage anyalysis, and uploads results to Code Climate. Requires the CODECLIMATE_REPO_TOKEN environment variable be set.
8. npm run clean # Removes node_modules and other temporary items so you can start the project fresh