Merge branch 'release/0.1.0'

.gitignore

@@ -0,0 +1,3 @@
+node_modules
+*.log
+docs

.jshintrc

@@ -0,0 +1,4 @@
+{
+  "node": true,
+  "laxcomma": true
+}

.npmignore

@@ -0,0 +1 @@
+.gitignore

.travis.yml

@@ -0,0 +1,5 @@
+language: node_js
+node_js:
+- '0.10'
+before_script:
+- npm install -g grunt-cli

CHANGELOG.md

@@ -0,0 +1,3 @@
+# [develop](https://github.com/mojolingo/mojo-auth.js)
+
+# [v0.1.0](https://github.com/mojolingo/mojo-auth.js/compare/c8686b66a4c3950e1fa0c7601c52ef6e19d9bf82...v0.1.0) - [2014-10-12](https://www.npmjs.org/package/mojo-auth.js/0.1.0)

Gruntfile.js

@@ -0,0 +1,42 @@
+module.exports = function(grunt) {
+  grunt.initConfig({
+    pkg: grunt.file.readJSON('package.json'),
+    jshint: {
+      all: ['src/**/*.js', 'tests/*.js'],
+      options: {
+        jshintrc: "./.jshintrc",
+      }
+    },
+    watch: {
+      grunt: {
+        files: ['clear', 'Gruntfile.js']
+      },
+      implementation: {
+        files: ['src/**/*.js'],
+        tasks: ['clear', 'jshint', 'mochaTest', 'shell:docs']
+      },
+      tests: {
+        files: ['tests/**/*.js'],
+        tasks: ['clear', 'jshint', 'mochaTest', 'shell:docs']
+      }
+    },
+    mochaTest: {
+      all: {
+        src: 'tests/*.js'
+      }
+    },
+    shell: {
+      docs: {
+        command: 'node_modules/.bin/doxx --source src --target docs'
+      }
+    }
+  });
+
+  grunt.loadNpmTasks('grunt-contrib-jshint');
+  grunt.loadNpmTasks('grunt-contrib-watch');
+  grunt.loadNpmTasks('grunt-clear');
+  grunt.loadNpmTasks('grunt-mocha-test');
+  grunt.loadNpmTasks('grunt-shell');
+
+  grunt.registerTask('default', ['jshint', 'mochaTest', 'shell:docs']);
+};

LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Mojo Lingo LLC
+
+MIT License
+
+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,45 @@
+[![Build Status](https://travis-ci.org/mojolingo/mojo-auth.js.svg?branch=develop)](http://travis-ci.org/mojolingo/mojo-auth.js)
+
+# mojo-auth.js
+
+[mojoauth](http://mojolingo.com/mojoauth) is a set of standard approaches to cross-app authentication based on [Hash-based Message Authentication Codes](http://en.wikipedia.org/wiki/Hash-based_message_authentication_code) (HMAC), inspired by ["A REST API For Access To TURN Services"](http://tools.ietf.org/html/draft-uberti-behave-turn-rest).
+
+## Installation
+
+Run `npm install mojo-auth.js --save` to add this library as a dependency to your Node.js project.
+
+## Usage
+
+```javascript
+> var mojoauth = require('mojo-auth.js');
+
+> var secret, credentials;
+undefined
+
+// Generate a shared secret
+> secret = mojoauth.createSecret();
+'27058c65ab05794cdec23abb2ad49f402e011d1ff56b61d4a4c37032ced2d94df6cff260c4fee814d1f9ea35fa7a2962332f0b2c5415e753b329c328a62c86f8'
+
+// Create temporary credentials
+> credentials = mojoauth.createCredentials({id: 'foobar', secret: secret});
+{ username: '1413151933064:foobar',
+  password: 'lvpE3AcLea5Io4mj8xT/eMlvw9k=' }
+
+// Test credentials
+> mojoauth.testCredentials({username: '1413151933064:foobar', password: 'lvpE3AcLea5Io4mj8xT/eMlvw9k='}, secret);
+'foobar'
+> mojoauth.testCredentials({username: '1413151933064:foobar', password: 'wrongpassword'}, secret);
+false
+
+// 1 day later
+> mojoauth.testCredentials({username: '1413151933064:foobar', password: 'lvpE3AcLea5Io4mj8xT/eMlvw9k='}, secret);
+false
+```
+
+## Contributing
+
+1. [Fork it](https://github.com/mojolingo/mojo_auth.js/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

package.json

@@ -1,10 +1,10 @@
 {
   "name": "mojo-auth.js",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Implementation of MojoAuth in Javascript",
-  "main": "index.js",
+  "main": "src/index.js",
   "scripts": {
-    "test": "grunt test"
+    "test": "grunt"
   },
   "repository": {
     "type": "git",
@@ -15,5 +15,17 @@
   "bugs": {
     "url": "https://github.com/mojolingo/mojo-auth.js/issues"
   },
-  "homepage": "https://github.com/mojolingo/mojo-auth.js"
+  "homepage": "https://github.com/mojolingo/mojo-auth.js",
+  "devDependencies": {
+    "chai": "^1.9.2",
+    "doxx": "^0.7.4",
+    "grunt": "^0.4.5",
+    "grunt-clear": "^0.2.1",
+    "grunt-contrib-jshint": "^0.10.0",
+    "grunt-contrib-watch": "^0.6.1",
+    "grunt-mocha-test": "^0.12.1",
+    "grunt-shell": "^1.1.1",
+    "mocha": "^1.21.5",
+    "timecop": "git+https://github.com/jamesarosen/Timecop.js.git"
+  }
 }

src/index.js

@@ -0,0 +1,68 @@
+/* global define */
+
+'use strict';
+
+var crypto = require('crypto');
+
+var required = function(name) {
+  throw(Error, 'requires ' + name);
+};
+
+var DAY_IN_SECONDS = 86400;
+
+var sign = function(message, secret) {
+  var hmac = crypto.createHmac('sha1', secret);
+  hmac.update(message);
+  return hmac.digest('base64');
+};
+
+/**
+  * Create a new random secret
+  *
+  * @return {String} a new random secret
+ */
+exports.createSecret = function () {
+  return crypto.randomBytes(64).toString('hex');
+};
+
+/**
+  * Create a new credential set
+  *
+  * @param {String} id the identity to be asserted in the credentials
+  * @param {String} secret the shared secret with which to create credentials
+  * @param {Integer} ttl the duration for which the credentials should be valid in seconds
+  *
+  * @return {Object} signed credentials, keys username and password
+ */
+exports.createCredentials = function (args) {
+  var secret = args.secret || required('secret')
+    , ttl = args.ttl || DAY_IN_SECONDS
+    , expiryTimestamp = new Date().getTime() + ttl
+    , username = [expiryTimestamp, args.id].join(':')
+    ;
+
+  return {username: username, password: sign(username, secret)};
+};
+
+/**
+  * Test that credentials are valid
+  *
+  * @param {Object} credentials a set of credentials including a username and a password
+  * @param {String} secret the shared secret against which to test credentials
+  *
+  * @return {Boolean, String} whether or not the credentials are valid (were created using the specified secret) and current (have not yet expired). When the credentials assert an identity, that identity is returned.
+ */
+exports.testCredentials = function (credentials, secret) {
+  var username = credentials.username.split(':')
+    , expiryTimestamp = username[0]
+    , id = username[1]
+    ;
+
+  if (parseInt(expiryTimestamp) < new Date().getTime()) {
+    return false;
+  }
+  if (sign(credentials.username, secret) != credentials.password) {
+    return false;
+  }
+  return id || true;
+};

tests/unit.js

@@ -0,0 +1,163 @@
+/*jshint -W030 */
+
+var mojoauth = require('../src/index')
+  , expect = require('chai').expect
+  , Timecop = require('timecop')
+  ;
+
+describe('creating a secret', function () {
+  it('should be a string', function () {
+    expect(mojoauth.createSecret()).to.be.a('string');
+  });
+
+  it('is longer than 20 characters', function () {
+    expect(mojoauth.createSecret()).to.have.length.above(20);
+  });
+});
+
+describe('creating and testing credentials', function () {
+  describe('without an asserted ID', function () {
+    var credentials
+      , secret = mojoauth.createSecret()
+      ;
+
+    beforeEach(function() {
+      credentials = mojoauth.createCredentials({secret: secret});
+    });
+
+    it('raises if no secret is given', function () {
+      expect(function () { mojoauth.createCredentials({}); }).to.throw('requires secret');
+    });
+
+    describe('for the generated credentials', function () {
+      it('tests true', function () {
+        expect(mojoauth.testCredentials(credentials, secret)).to.be.true;
+      });
+    });
+
+    describe('with an incorrect password', function () {
+      it('tests false', function () {
+        expect(mojoauth.testCredentials({ username: credentials.username, password: 'foobar' }, secret)).to.be.false;
+      });
+    });
+
+    describe('with a different secret', function () {
+      it('tests false', function () {
+        expect(mojoauth.testCredentials(credentials, 'something_else')).to.be.false;
+      });
+    });
+
+    describe('when attempting to extend the expiration', function () {
+      it('tests false', function () {
+        expect(mojoauth.testCredentials({ username: (new Date().getTime() + 100000).toString(), password: credentials.password }, secret)).to.be.false;
+      });
+    });
+
+    describe('after the default TTL (1 day) expires', function () {
+      beforeEach(function () {
+        Timecop.install();
+        Timecop.freeze(new Date().getTime() + 86400 + 1);
+      });
+
+      afterEach(function () {
+        Timecop.uninstall();
+      });
+
+      it('tests false', function () {
+        expect(mojoauth.testCredentials(credentials, secret)).to.be.false;
+      });
+    });
+
+    describe('after expiry of a custom TTL', function () {
+      var ttl = 200;
+
+      beforeEach(function () {
+        credentials = mojoauth.createCredentials({secret: secret, ttl: ttl});
+      });
+
+      beforeEach(function () {
+        Timecop.install();
+        Timecop.freeze(new Date().getTime() + ttl + 1);
+      });
+
+      afterEach(function () {
+        Timecop.uninstall();
+      });
+
+      it('tests false', function () {
+        expect(mojoauth.testCredentials(credentials, secret)).to.be.false;
+      });
+    });
+  });
+
+  describe('with an asserted ID', function () {
+    var id = mojoauth.createSecret()
+      , secret = mojoauth.createSecret()
+      , credentials
+      ;
+
+    beforeEach(function() {
+      credentials = mojoauth.createCredentials({id: id, secret: secret});
+    });
+
+    describe('for the generated credentials', function () {
+      it('tests truthy, returning the asserted ID', function () {
+        expect(mojoauth.testCredentials(credentials, secret)).to.eql(id);
+      });
+    });
+
+    describe('with an incorrect password', function () {
+      it('tests false', function () {
+        expect(mojoauth.testCredentials({ username: credentials.username, password: 'foobar' }, secret)).to.be.false;
+      });
+    });
+
+    describe('with a different secret', function () {
+      it('tests false', function () {
+        expect(mojoauth.testCredentials(credentials, 'something_else')).to.be.false;
+      });
+    });
+
+    describe('when attempting to extend the expiration', function () {
+      it('tests false', function () {
+        expect(mojoauth.testCredentials({ username: (new Date().getTime() + 100000).toString() + ':' + id, password: credentials.password }, secret)).to.be.false;
+      });
+    });
+
+    describe('after the default TTL (1 day) expires', function () {
+      beforeEach(function () {
+        Timecop.install();
+        Timecop.freeze(new Date().getTime() + 86400 + 1);
+      });
+
+      afterEach(function () {
+        Timecop.uninstall();
+      });
+
+      it('tests false', function () {
+        expect(mojoauth.testCredentials(credentials, secret)).to.be.false;
+      });
+    });
+
+    describe('after expiry of a custom TTL', function () {
+      var ttl = 200;
+
+      beforeEach(function () {
+        credentials = mojoauth.createCredentials({secret: secret, ttl: ttl});
+      });
+
+      beforeEach(function () {
+        Timecop.install();
+        Timecop.freeze(new Date().getTime() + ttl + 1);
+      });
+
+      afterEach(function () {
+        Timecop.uninstall();
+      });
+
+      it('tests false', function () {
+        expect(mojoauth.testCredentials(credentials, secret)).to.be.false;
+      });
+    });
+  });
+});