Initial Commit

Author: KernCheh

.gitignore

@@ -0,0 +1,2 @@
+.idea
+node_modules

.npmignore

@@ -0,0 +1 @@
+.idea

LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Sim Kern Cheh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

README.md

@@ -0,0 +1,76 @@
+# Express Header Token Authentication
+
+This package parses Authorization headers from an Express request object for an authorization token.
+
+## Installation
+
+```
+npm install express-header-token-auth
+```
+
+## Usage
+
+Token validation can be done through a routing middleware or part of the routed action.
+
+Incoming Payload can be simulated by:
+
+`curl -IH "Authorization: Token token=test;param1=option1;param2=option2" http://myapp.com/protected/resource`
+
+Accepted Authorization Header formats are:
+
+
+    Authorization: Token token=test,param1=option1,param2=option2
+    Authorization: Token token="test",param1="option1",param2="option2"
+    //Any variation of commas(,), semicolons(;) or tabs(   ) are accepted as delimiters
+
+
+### As routing middleware
+
+
+    router.use('/protected/resource', function(req, res, next) {
+      new TokenAuth(req, res).authenticateOrRequestWithHttpToken(function(err, token, options) {
+        if (!err) {
+          if (isValidToken(token, options))
+            next();
+          else {
+            // send out invalid response
+          }
+        }
+        // `else` case is not needed. If `err` is present, a HTTP response with status 401 will automatically be sent out.
+      });
+    });
+
+
+### As action
+
+
+    router.use('/protected/resource', function(req, res, next) {
+      new TokenAuth(req, res).authenticateOrRequestWithHttpToken(function(err, token, options) {
+        if (!err) {
+          if (isValidToken(token, options))
+            // valid response
+          else {
+            // send out invalid response
+          }
+        }
+        // `else` case is not needed. If `err` is present, a HTTP response with status 401 will automatically be sent out.
+      });
+    });
+
+
+## Methods
+
+`authenticateOrRequestWithHttpToken([realm], callback)`
+
+Used to grab token and options from callback. When token is not found, HTTP status 401 challenge is automatically sent.
+The `realm` parameter defaults to `Application`, which is used when challenging for token.
+
+`authenticate(callback, [callbackOnError])`
+
+Similar to `authenticateOrRequestWithHttpToken`, except the HTTP status 401 challenge will not be sent on failure to identify token. User is responsible for deciding the next course of action.
+The `callbackOnError` parameter defaults to `true` and should rarely be needed.
+
+
+`requestHttpTokenAuthentication(realm)`
+
+Issues HTTP Status 401 challenge to current Response object.

lib/TokenAuth.js

@@ -0,0 +1,103 @@
+var _ = require('underscore');
+
+var TokenAuth = function(req, resp) {
+  this.req = req;
+  this.resp = resp;
+};
+
+_.extend(TokenAuth.prototype, {
+  TOKEN_KEY: 'token=',
+  TOKEN_REGEX: /^Token /,
+  AUTHN_PAIR_DELIMITERS: /\s*(?:,|;|\t+)\s*/,
+
+  /**
+   * Parses token from Authorization header and returns token and options from callback.
+   * Automatically responds with 401 requesting for Token Authentication.
+   *
+   * @param realm - Current authentication realm. Optional, defaults to 'Application'
+   * @param callback - Can be passed in as first parameter. Parameters - (error, token, options)
+   */
+  authenticateOrRequestWithHttpToken: function(realm, callback) {
+    if (typeof(realm) === 'function'){
+      callback = realm;
+      realm = 'Application';
+    }
+
+    if (!this.resp) {
+      callback(new Error('Response object required to use `authenticateOrRequestWithHTTPToken`'));
+      return;
+    }
+    return this.authenticate(callback, false) || this.requestHttpTokenAuthentication(realm) && callback(new Error('HTTP Basic: Access denied.'));
+  },
+
+  /**
+   * Sets 401 response to Response object.
+   *
+   * @param realm - Current authentication realm
+   */
+  requestHttpTokenAuthentication: function(realm) {
+    this.resp.set('WWW-Authenticate', 'Basic realm="' + realm + '"');
+    this.resp.status(401);
+    this.resp.send("HTTP Basic: Access denied.\n");
+    return true;
+  },
+
+  /**
+   * Attempts to parse Token and options from Authorization header.
+   *
+   * @param callback - (error, token, options)
+   * @param callbackOnError - Optional. Defaults to true. When false, errors will not trigger callback.
+   * @returns true if token is found, false if otherwise
+   */
+  authenticate: function(callback, callbackOnError) {
+    if (callbackOnError === undefined)
+      callbackOnError = true;
+
+    var tokenAndOpts = this.tokenAndOptions();
+    if (tokenAndOpts && tokenAndOpts[0]) {
+      callback(null, tokenAndOpts[0], tokenAndOpts[1]);
+      return true;
+    }
+
+    if (callbackOnError) {
+      callback(new Error('Token not found'));
+    }
+    return false;
+  },
+
+  tokenAndOptions: function() {
+    var auth = this.req.headers.authorization;
+    if (auth && auth.match(this.TOKEN_REGEX)) {
+      var params = this.tokenParamsFrom(auth);
+      return [params.shift(1)[1], _.object(params)];
+    }
+  },
+
+  tokenParamsFrom: function(auth) {
+    return this.rewriteParamValues( this.paramsArrayFrom( this.rawParams(auth) ) );
+  },
+
+  rawParams: function(authorizationHeader) {
+    var rawParams = authorizationHeader.replace(this.TOKEN_REGEX, '').split(this.AUTHN_PAIR_DELIMITERS);
+    if (!rawParams[0].match(new RegExp('^' + this.TOKEN_KEY))) {
+      rawParams[0] = this.TOKEN_KEY + rawParams[0];
+    }
+
+    return rawParams;
+  },
+
+  paramsArrayFrom: function(rawParams) {
+    return _.map(rawParams, function(param) {
+      return param.split(/=(?=.+)/);
+    });
+  },
+
+  rewriteParamValues: function(arrayParams) {
+    return _.map(arrayParams, function(param) {
+      param[1] = (param[1] || '').replace(/^"|"$/g, '');
+      return param;
+    });
+  }
+});
+
+module.exports = TokenAuth;

package.json

@@ -0,0 +1,24 @@
+{
+  "name": "express-header-token-auth",
+  "version": "1.0.0",
+  "description": "Parses token from Authorization Headers",
+  "main": "lib/TokenAuth.js",
+  "scripts": {
+    "test": "./node_modules/jasmine/bin/jasmine.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "[email protected]:KernCheh/express-header-token-auth.git"
+  },
+  "keywords": [
+    "authorization",
+    "token",
+    "express"
+  ],
+  "author": "Sim Kern Cheh",
+  "license": "MIT",
+  "dependencies": {
+    "jasmine": "^2.3.1",
+    "underscore": "^1.8.3"
+  }
+}

spec/lib/TokenAuthSpec.js

@@ -0,0 +1,82 @@
+describe('TokenAuth', function() {
+  var TokenAuth = require('../../lib/TokenAuth'),
+    fakeRequest = {
+      headers: {
+        authorization: 'Token token="mytesttoken", extraparams="info"'
+      }
+    },
+
+    fakeResponse = {
+      set: function(key, value) {},
+      status: function(status) {},
+      send: function(content) {}
+    };
+
+  beforeEach(function() {
+    this.token = new TokenAuth(fakeRequest, fakeResponse);
+  });
+
+  describe('rawParams', function() {
+    it('gathers params from token', function() {
+      var result = this.token.rawParams('Token token=fake; test=something, param2=true');
+      expect(result).toEqual([ 'token=fake', 'test=something', 'param2=true' ]);
+    });
+  });
+
+  describe('paramsArrayFrom', function() {
+    it('takes raw params and turns into array of parameters', function() {
+      var result = this.token.paramsArrayFrom(['token=fake', 'param2=true']);
+      expect(result).toEqual([ [ 'token', 'fake' ], [ 'param2', 'true' ] ]);
+    });
+  });
+
+  describe('rewriteParamValues', function() {
+    it('removes inverted commas from params', function() {
+      var result = this.token.rewriteParamValues([ [ 'token', '"fake"' ], [ 'param2', '"true"' ] ]);
+      expect(result).toEqual([ [ 'token', 'fake' ], [ 'param2', 'true' ] ]);
+    });
+  });
+
+  describe('tokenAndOptions', function() {
+    it('returns token as first item and additional options as a hash', function() {
+      var result = this.token.tokenAndOptions();
+      expect(result).toEqual([ 'mytesttoken', { extraparams: 'info' } ]);
+    });
+
+    it('returns undefined if header authorization is not present', function() {
+      this.token.req.headers.authorization = undefined;
+      expect(this.token.tokenAndOptions()).toEqual(undefined);
+      this.token.req.headers.authorization = 'Token token="mytesttoken", extraparams="info"';
+    })
+  });
+
+  describe('authenticateOrRequestWithHttpToken', function() {
+    it('defaults to Application realm and calls back if token is found', function(done) {
+      this.token.authenticateOrRequestWithHttpToken(function(err, token, options) {
+        expect(token).toEqual('mytesttoken');
+        expect(options).toEqual({ extraparams: 'info' });
+        done();
+      });
+    });
+
+    it('responds with 401 if token is not found', function(done) {
+      spyOn(fakeResponse, 'set');
+      spyOn(fakeResponse, 'status');
+      spyOn(fakeResponse, 'send');
+
+      var newRequest = {
+        headers: {
+          authorization: undefined
+        }
+      },
+        token = new TokenAuth(newRequest, fakeResponse);
+
+      token.authenticateOrRequestWithHttpToken(function(err, token, options) {
+        expect(fakeResponse.set.calls.allArgs()).toEqual([ [ 'WWW-Authenticate', 'Basic realm="Application"' ] ]);
+        expect(fakeResponse.status.calls.allArgs()).toEqual([ [401] ]);
+        expect(fakeResponse.send.calls.allArgs()).toEqual([ ["HTTP Basic: Access denied.\n"] ]);
+        done();
+      });
+    });
+  });
+});

spec/support/jasmine.json

@@ -0,0 +1,9 @@
+{
+  "spec_dir": "spec",
+  "spec_files": [
+    "**/*[sS]pec.js"
+  ],
+  "helpers": [
+    "helpers/**/*.js"
+  ]
+}