Additional documentation for TokenStrategy.

Author: jaredhanson

lib/passport-http-oauth/strategies/consumer.js

@@ -84,7 +84,7 @@ var passport = require('passport')
  *           if (err) { return done(err); }
  *           if (!token) { return done(null, false); }
  *           // third argument is optional info.  typically used to pass
- *           // details needed to authorize the request (ex: `scope`)
+ *           // details needed to authorize the request (ex: `verifier`)
  *           return done(null, token.secret, { verifier: token.verifier });
  *         });
  *       },

lib/passport-http-oauth/strategies/token.js

@@ -15,6 +15,29 @@ var passport = require('passport')
  * located in an `Authorization` header field, the request entity body, or the
  * URL query parameters.
  *
+ * This strategy requires three functions as callbacks, referred to as
+ * `consumer`, `verify` and `validate`.
+ *
+ * The `consumer` callback accepts `consumerKey` and must call `done` supplying
+ * a `consumer` and `consumerSecret`.  The strategy will use the secret to
+ * compute the signature, failing authentication if it does not match the
+ * request's signature.  If an exception occured, `err` should be set.
+ *
+ * The `verify` callback accepts `accessToken` and must call `done` supplying
+ * a `user`, `tokenSecret` and optional `info`.  Note that `user` is the
+ * authenticating entity of this strategy, and will be set by Passport at
+ * `req.user` upon success.  The strategy will use the secret to compute the
+ * signature, failing authentication if it does not match the request's
+ * signature.  The optional `info` is typically used to carry additional
+ * authorization details associated with the token (scope of access, for
+ * example).  `info` will be set by Passport at `req.authInfo`, where it can be
+ * used by later middleware, avoiding the need to re-query a database for the
+ * same information.  If an exception occured, `err` should be set.
+ *
+ * The `validate` callback is optional, accepting `timestamp` and `nonce` as a
+ * means to protect against replay attacks.
+ *
+ *
  * Note that despite defining a single authentication scheme, OAuth
  * authentication serves two distinct purposes:
  *   1. Authenticating consumers (aka clients) that are requesting access to
@@ -37,6 +60,35 @@ var passport = require('passport')
  *
  * This strategy is inteded to be employed in routes for protected resources.
  *
+ * Examples:
+ *
+ *     passport.use('token', new TokenStrategy(
+ *       function(consumerKey, done) {
+ *         Consumer.findByKey({ key: consumerKey }, function (err, consumer) {
+ *           if (err) { return done(err); }
+ *           if (!consumer) { return done(null, false); }
+ *           return done(null, consumer, consumer.secret);
+ *         });
+ *       },
+ *       function(accessToken, done) {
+ *         AccessToken.findOne(accessToken, function (err, token) {
+ *           if (err) { return done(err); }
+ *           if (!token) { return done(null, false); }
+ *           Users.findOne(token.userId, function(err, user) {
+ *             if (err) { return done(err); }
+ *             if (!user) { return done(null, false); }
+ *             // fourth argument is optional info.  typically used to pass
+ *             // details needed to authorize the request (ex: `scope`)
+ *             return done(null, user, token.secret, { scope: token.scope });
+ *           });
+ *         });
+ *       },
+ *       function(timestamp, nonce, done) {
+ *         // validate the timestamp and nonce as necessary
+ *         done(null, true)
+ *       }
+ *     ));
+ *
  * References:
  *  - [Authenticated Requests](http://tools.ietf.org/html/rfc5849#section-3)
  *  - [Accessing Protected Resources](http://oauth.net/core/1.0a/#anchor12)