Spec the middleware intervention for exposing the token, fix MrSwitch#11

Author: MrSwitch

README.md

@@ -1,62 +1,95 @@
 # OAuth-shim
-This node module provides a "shim" service for clientside web apps adopting serverside OAuth2 or OAuth1 authentication but fighting to keep it all the browser, and shims the tedious dog legging through servers that has become OAuth1's curse.
+Middleware offering OAuth1/OAuth2 authorization handshake for web applications using the [HelloJS](http://adodson.com/hello.js) clientside authentication library.
 
 
-## Use case
+## tl;dr;
 
-Popular API's like Twitter, Dropbox and Yahoo require this server-to-server authentication paradigm. What oauthshim does is set up a RESTful service which shims up these web API's. This is used by clientside libraries like [HelloJS](http://adodson.com/hello.js) as a fallback to keep everything running in the client.
+[https://auth-server.herokuapp.com](https://auth-server.herokuapp.com) is a service which utilizes this package. If you dont want to implement your own you can simply and freely register thirdparty application Key's and Secret's there.
 
-## Demo
 
-[https://auth-server.herokuapp.com](https://auth-server.herokuapp.com) is a service which utilizes this package. You can register your own Application Key and Secret there if you dont want to set your own up. But for production you shouldn't rely on that service.
+## Implement
 
 
-## Installing on the server
+```bash
+npm install oauth-shim
+```
 
-Install the package
+Middleware for Express/Connect
 
-	npm install oauth-shim
 
+```javascript
+var oauthshim = require('oauth-shim'),
+	express = require('express');
 
-## Using with ExpressJS
-	
-	var oauthshim = require('oauth-shim'),
-		express = require('express');
+var app = express();
+app.all('/oauthproxy', oauthshim);
+
+// Initiate the shim with Client ID's and secret, e.g.
+oauthshim.init({
+	// id : secret
+	'12345' : 'secret678910',
+	'abcde' : 'secretfghijk'
+});
+```
 
-	var app = express();
-	app.all('/oauthproxy', oauthshim.request);
 
-	// Initiate the shim with Client ID's e.g.
-	oauthshim.init({
-		// key : Secret
-		'12345' : 'secret678910',
-		'abcde' : 'secretfghijk'
-	});
 
-	// Print request->response to console.
-	oauthshim.debug = true;
 
 The code above says apply the shim to all requests to the pathname `/oauthproxy`.
 
-## Using with ConnectJS
+## Customised Middleware
+
+### Capture Access Tokens
+
+Use the middleware to capture the access_token registered with your app at any point in the series of operations that this module steps through. In the example below they are disseminated with a `customHandler` in the middleware chain to capture the access_token...
+
+
+```javascript
 
-Change `oauthshim.request` to `oauthshim.listen`
+app.all('/oauthproxy',
+			oauthshim.interpret,
+			customHandler,
+			oauthshim.proxy,
+			oauthshim.redirect,
+			oauthshim.unhandled);
 
 
-### Asynchronsly access secret
+function customHandler(req, res, next){
 
-If you want to return clientID's asynchronosly (perhaps you want to look up from a database) then override the getCredentials method. Here's the basics e.g...
+	// Check that this is a login redirect with an access_token (not a RESTful API call via proxy)
+	if( req.oauthshim &&
+		req.oauthshim.redirect &&
+		req.oauthshim.data &&
+		req.oauthshim.data.access_token &&
+		req.oauthshim.options &&
+		!req.oauthshim.options.path ){
 
-	oauthshim.getCredentials = function(id,callback){
-		// Return
-		if(id === '12345'){
-			callback('secret678910');
-		}
-		if(id === 'abcde'){
-			callback('secretfghijk');
-		}
+			// do something with the token (req.oauthshim.data.access_token)
 	}
 
+	// Call next to complete the operation
+	next()
+}
+
+```
+
+
+### Asynchronsly retrieve the secret
+
+Rewrite the function `getCredentials` to change the way the client secret is stored/retrieved. This method is asyncronous, to access the secret from a database etc.. 
+e.g...
+
+```javascript
+oauthshim.getCredentials = function(id,callback){
+	// Return
+	if(id === '12345'){
+		callback('secret678910');
+	}
+	if(id === 'abcde'){
+		callback('secretfghijk');
+	}
+}
+```
 
 ## Authentication API
 
@@ -171,20 +204,12 @@ Add a JSONP callback function and override the method. E.g.
 	&callback=myJSONP
 
 
-## Contributing
-
-Don't forget to run the tests. 
-
-	# Install the test dependencies.
-
-	npm install -l
-
-	# Run the tests, continuously
-
-	npm test
-
-	# Single
-
-	mocha test
+## Specs
 
+```bash
+# Install the test dependencies.
+npm install -l
 
+# Run tests
+npm test
+```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "oauth-shim",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "OAuth2 shim for OAuth1 services, works with the clientside library HelloJS",
   "main": "index.js",
   "scripts": {
@@ -21,15 +21,11 @@
   "bugs": {
     "url": "https://github.com/MrSwitch/node-oauth-shim/issues"
   },
-  "dependencies": {
-    "crypto": "0.0.3"
-  },
   "devDependencies": {
-    "should": ">= 0.0.0",
     "expect.js" : "*",
     "express": "*",
     "connect": "*",
     "supertest": "*",
-    "mocha": "^2.0.1"
+    "mocha": "*"
   }
 }

test/oauth-shim.js

@@ -29,8 +29,6 @@ var app = express();
 // SETUP SHIM LISTENING
 ////////////////////////////////
 
-oauthshim.debug = false;
-
 oauthshim.init({
 	// OAuth 1
 	'oauth_consumer_key' : 'oauth_consumer_secret',