refactor: move remaining functions into es6 class and add more compre…

…hensive jsDoc comments
node-oauth · Jan 4, 2024 · 67ae088 · 67ae088
1 parent 32d13c0
commit 67ae088
Showing 1 changed file with 117 additions and 77 deletions.
diff --git a/index.js b/index.js
@@ -9,11 +9,49 @@ const Response = require('@node-oauth/oauth2-server').Response;
 const UnauthorizedRequestError = require('@node-oauth/oauth2-server/lib/errors/unauthorized-request-error');
 
 /**
+ * Complete, compliant and well tested express wrapper for @node-oauth/oauth2-server in node.js.
+ * The module provides two middlewares - one for granting tokens and another to authorize them.
+ * `@node-oauth/express-oauth-server` and, consequently `@node-oauth/oauth2-server`,
+ * expect the request body to be parsed already.
+ * The following example uses `body-parser` but you may opt for an alternative library.
  *
+ * @example
+ * const bodyParser = require('body-parser');
+ * const express = require('express');
+ * const OAuthServer = require('@node-oauth/express-oauth-server');
+ *
+ * const app = express();
+ *
+ * app.oauth = new OAuthServer({
+ *   model: {}, // See https://github.com/node-oauth/node-oauth2-server for specification
+ * });
+ *
+ * app.use(bodyParser.json());
+ * app.use(bodyParser.urlencoded({ extended: false }));
+ * app.use(app.oauth.authorize());
+ *
+ * app.use(function(req, res) {
+ *   res.send('Secret area');
+ * });
+ *
+ * app.listen(3000);
  */
 class ExpressOAuthServer {
   /**
+   * Creates a new OAuth2 server that will be bound to this class' middlewares.
+   * Constructor takes several options as arguments.
+   * The following describes only options, specific to this module.
+   * For all other options, please read the docs from `@node-oauth/oauth2-server`:
+   * @see https://node-oauthoauth2-server.readthedocs.io/en/master/api/oauth2-server.html
    * @constructor
+   * @param options {object=} optional options
+   * @param options.useErrorHandler {boolean=} If false, an error response will be rendered by this component.
+   *   Set this value to true to allow your own express error handler to handle the error.
+   * @param options.continueMiddleware {boolean=} The `authorize()` and `token()` middlewares will both render their
+   *   result to the response and end the pipeline.
+   *   next() will only be called if this is set to true.
+   *   **Note:** You cannot modify the response since the headers have already been sent.
+   *   `authenticate()` does not modify the response and will always call next()
    */
   constructor(options = {}) {
     if (!options.model) {
@@ -29,98 +67,101 @@ class ExpressOAuthServer {
     this.server = new NodeOAuthServer(options);
   }
 
-}
-
-/**
- * Authentication Middleware.
- *
- * Returns a middleware that will validate a token.
- *
- * (See: https://tools.ietf.org/html/rfc6749#section-7)
- */
-
-ExpressOAuthServer.prototype.authenticate = function(options) {
-  const fn = async function(req, res, next) {
-    const request = new Request(req);
-    const response = new Response(res);
-
-    let token
+  /**
+   * Authentication Middleware.
+   * Returns a middleware that will validate a token.
+   *
+   * @param options {object=} will be passed to the authenticate-handler as options, see linked docs
+   * @see https://node-oauthoauth2-server.readthedocs.io/en/master/api/oauth2-server.html#authenticate-request-response-options
+   * @see: https://tools.ietf.org/html/rfc6749#section-7
+   * @return {function(req, res, next):Promise.<Object>}
+   */
+  authenticate(options) {
+    const fn = async function(req, res, next) {
+      const request = new Request(req);
+      const response = new Response(res);
 
-    try {
-      token = await this.server.authenticate(request, response, options);
-    } catch (e) {
-      return handleError.call(this, e, req, res, null, next);
-    }
+      let token
 
-    res.locals.oauth = { token };
-    next();
-  };
-  return fn.bind(this);
-};
+      try {
+        token = await this.server.authenticate(request, response, options);
+      } catch (e) {
+        return handleError.call(this, e, req, res, null, next);
+      }
 
-/**
- * Authorization Middleware.
- *
- * Returns a middleware that will authorize a client to request tokens.
- *
- * (See: https://tools.ietf.org/html/rfc6749#section-3.1)
- */
+      res.locals.oauth = { token };
+      next();
+    };
 
-ExpressOAuthServer.prototype.authorize = function(options) {
-  const fn = async function(req, res, next) {
-    const request = new Request(req);
-    const response = new Response(res);
+    return fn.bind(this);
+  }
 
-    let code
+  /**
+   * Authorization Middleware.
+   * Returns a middleware that will authorize a client to request tokens.
+   *
+   * @param options {object=} will be passed to the authorize-handler as options, see linked docs
+   * @see https://node-oauthoauth2-server.readthedocs.io/en/master/api/oauth2-server.html#authorize-request-response-options
+   * @see: https://tools.ietf.org/html/rfc6749#section-3.1
+   * @return {function(req, res, next):Promise.<Object>}
+   */
+  authorize(options) {
+    const fn = async function(req, res, next) {
+      const request = new Request(req);
+      const response = new Response(res);
 
-    try {
-      code = await this.server.authorize(request, response, options);
-    } catch (e) {
-      return handleError.call(this, e, req, res, response, next);
-    }
+      let code
 
-    res.locals.oauth = { code: code };
-    if (this.continueMiddleware) {
-      next();
-    }
+      try {
+        code = await this.server.authorize(request, response, options);
+      } catch (e) {
+        return handleError.call(this, e, req, res, response, next);
+      }
 
-    return handleResponse.call(this, req, res, response);
-  };
+      res.locals.oauth = { code };
+      if (this.continueMiddleware) {
+        next();
+      }
 
-  return fn.bind(this);
-};
+      return handleResponse.call(this, req, res, response);
+    };
 
-/**
- * Grant Middleware.
- *
- * Returns middleware that will grant tokens to valid requests.
- *
- * (See: https://tools.ietf.org/html/rfc6749#section-3.2)
- */
+    return fn.bind(this);
+  }
 
-ExpressOAuthServer.prototype.token = function(options) {
-  const fn = async function(req, res, next) {
-    const request = new Request(req);
-    const response = new Response(res);
+  /**
+   * Grant Middleware.
+   * Returns middleware that will grant tokens to valid requests.
+   *
+   * @param options {object=} will be passed to the token-handler as options, see linked docs
+   * @see https://node-oauthoauth2-server.readthedocs.io/en/master/api/oauth2-server.html#token-request-response-options
+   * @see: https://tools.ietf.org/html/rfc6749#section-3.2
+   * @return {function(req, res, next):Promise.<Object>}
+   */
+  token(options) {
+    const fn = async function(req, res, next) {
+      const request = new Request(req);
+      const response = new Response(res);
 
-    let token
+      let token
 
-    try {
-      token = await this.server.token(request, response, options);
-    } catch (e) {
-      return handleError.call(this, e, req, res, response, next);
-    }
+      try {
+        token = await this.server.token(request, response, options);
+      } catch (e) {
+        return handleError.call(this, e, req, res, response, next);
+      }
 
-    res.locals.oauth = { token: token };
-    if (this.continueMiddleware) {
-      next();
-    }
+      res.locals.oauth = { token };
+      if (this.continueMiddleware) {
+        next();
+      }
 
-    return handleResponse.call(this, req, res, response);
-  };
+      return handleResponse.call(this, req, res, response);
+    };
 
-  return fn.bind(this);
-};
+    return fn.bind(this);
+  }
+}
 
 /**
  * Handle response.
@@ -140,7 +181,6 @@ const handleResponse = function(req, res, response) {
 /**
  * Handle error.
  */
-
 const handleError = function(e, req, res, response, next) {
   if (this.useErrorHandler === true) {
     next(e);