wrote examples and added more documentation

Author: Leon Strauss

README.md

@@ -17,8 +17,6 @@ get the middleware:
 The middleware will now check incoming requests to match the credentials
 `admin:supersecret`.
 
-## How it behaves
-
 The middleware will check incoming requests for a basic auth (`Authorization`)
 header, parse it and check if the credentials are legit.
 
@@ -27,8 +25,10 @@ header, parse it and check if the credentials are legit.
 **If a request is successfully authorized**, an `auth` property will be added to the request,
 containing an object with `user` and `password` properties, filled with the credentials.
 
+# Static Users
+
 If you simply want to check basic auth against one or multiple static credentials,
-you can simply pass the credentials as in the example above:
+you can pass those credentials as in the example above:
 
     app.use(basicAuth({
         users: {
@@ -41,6 +41,8 @@ you can simply pass the credentials as in the example above:
 The middleware will check incoming requests to have a basic auth header matching
 one of the three passed credentials.
 
+# Custom authorization
+
 Alternatively, you can pass your own `authorizer` function, to check the credentials
 however you want. It will be called with a username and password and is expected to
 return `true` or `false` to indicate that the credentials were approved or not:
@@ -55,6 +57,8 @@ This will authorize all requests with credentials where the username begins with
 `'A'` and the password begins with `'secret'`. In an actual application you would
 likely look up some data instead ;-)
 
+# Custom Async Authorization
+
 Note that the `authorizer` function is expected to be synchronous here. This is
 the default behavior, you can pass `authorizeAsync: true` in the options object to indicate
 that your authorizer is asynchronous. In this case it will be passed a callback
@@ -73,3 +77,26 @@ Let's look at the same authorizer again, but this time asynchronous:
         else
             return cb(null, false)
     }
+
+# Challenge
+
+Per default the middleware will not add a `WWW-Authenticate` challenge header to
+responses of unauthorized requests. You can enable that by adding `challenge: true`
+to the options object. This will cause most browsers to show a popup to enter credentials
+on unauthorized responses:
+
+    app.use(basicAuth({
+        users: { 'someuser': 'somepassword' },
+        challenge: true
+    }));
+
+# Try it
+
+The repository contains an `example.js` that you can run to play around and try
+the middleware. To use it just put it somewhere (or leave it where it is), run
+
+    npm install express express-basic-auth
+    node example.js
+
+This will start a small express server listening at port 8080. Just look at the file,
+try out the requests and play around with the options.

example.js

@@ -0,0 +1,77 @@
+var express = require('express');
+
+var app = express();
+
+var basicAuth = require('./index.js');
+
+/**
+* express-basic-auth
+*
+* Example server. Just run in the same folder:
+*
+* npm install express express-basic-auth
+*
+* and then run this file with node ('node example.js')
+*
+* You can send GET requests to localhost:8080/async , /custom, /challenge or /static
+* and see how it refuses or accepts your request matching the basic auth settings.
+*/
+
+//Requires basic auth with username 'Admin' and password 'secret1234'
+var staticUserAuth = basicAuth({
+    users: {
+        'Admin': 'secret1234'
+    },
+    challenge: false
+});
+
+//Uses a custom (synchronous) authorizer function
+var customAuthorizerAuth = basicAuth({
+    authorizer: myAuthorizer
+});
+
+//Same, but sends a basic auth challenge header when authorization fails
+var challengeAuth = basicAuth({
+    authorizer: myAuthorizer,
+    challenge: true
+});
+
+//Uses a custom asynchronous authorizer function
+var asyncAuth = basicAuth({
+    authorizer: myAsyncAuthorizer,
+    authorizeAsync: true
+});
+
+
+app.get('/static', staticUserAuth, function(req, res) {
+    res.status(200).send('You passed');
+});
+
+app.get('/custom', customAuthorizerAuth, function(req, res) {
+    res.status(200).send('You passed');
+});
+
+app.get('/challenge', challengeAuth, function(req, res) {
+    res.status(200).send('You passed');
+});
+
+app.get('/async', asyncAuth, function(req, res) {
+    res.status(200).send('You passed');
+});
+
+app.listen(8080, function() {
+    console.log("Listening!");
+});
+
+//Cusotm authorizer checking if the username starts with 'A' and the password with 'secret'
+function myAuthorizer(username, password) {
+    return username.startsWith('A') && password.startsWith('secret');
+}
+
+//Same but asynchronous
+function myAsyncAuthorizer(username, password, cb) {
+    if(username.startsWith('A') && password.startsWith('secret'))
+        return cb(null, true);
+    else
+        return cb(null, false)
+}