Fixed migration guide

Author: Michael Salinger

docs/misc/migrating-v2-to-v3.rst

@@ -2,99 +2,115 @@
  Migrating from 2.x to 3.x
 ===========================
 
-This module is now promise-based but allows for *ES6 generators*, *async/await* (using _[babel](https://babeljs.io)_ or node v7.6+), *node-style* callbacks and *promises* in your model.
+This module is now promise-based but allows for **ES6 generators**, **async/await** (using *[babel](https://babeljs.io)* or node v7.6+), **node-style** callbacks and **promises** in your model.
 
-## Middlewares
+-----------
+Middlewares
+-----------
 
-  The naming of the exposed middlewares has changed to match the OAuth2 _RFC_ more closely. Please refer to the table below:
+The naming of the exposed middlewares has changed to match the OAuth2 _RFC_ more closely. Please refer to the table below:
 
++-------------------+------------------------------------------------+
 | oauth2-server 2.x | oauth2-server 3.x                              |
-|-------------------|------------------------------------------------|
++===================+================================================+
 | authorise         | authenticate                                   |
++-------------------+------------------------------------------------+
 | authCodeGrant     | authorize                                      |
++-------------------+------------------------------------------------+
 | grant             | token                                          |
++-------------------+------------------------------------------------+
 | errorHandler      | **removed** (now handled by external wrappers) |
-| lockdown          | **removed** (specific to _Express_ middleware) |
++-------------------+------------------------------------------------+
+| lockdown          | **removed** (specific to *Express* middleware) |
++-------------------+------------------------------------------------+
 
-## Server options
+--------------
+Server options
+--------------
 
 The following server options can be set when instantiating the OAuth service:  
 
-  * `addAcceptedScopesHeader`: **default true** Add the `X-Accepted-OAuth-Scopes` header with a list of scopes that will be accepted
-  * `addAuthorizedScopesHeader`: **default true** Add the `X-OAuth-Scopes` header with a list of scopes that the user is authorized for
-  * `allowBearerTokensInQueryString`: **default false** Determine if the bearer token can be included in the query string (i.e. `?access_token=`) for validation calls
-  * `allowEmptyState`: **default false** If true, `state` can be empty or not passed.  If false, `state` is required.
-  * `authorizationCodeLifetime`: **default 300** Default number of milliseconds that the authorization code is active for
-  * `accessTokenLifetime`: **default 3600** Default number of milliseconds that an access token is valid for
-  * `refreshTokenLifetime`: **default 1209600** Default number of milliseconds that a refresh token is valid for
-  * `allowExtendedTokenAttributes`: **default false** Allows additional attributes (such as `id_token`) to be included in token responses.
-  * `requireClientAuthentication`: **default true for all grant types** Allow ability to set client/secret authentication to `false` for a specific grant type.   
+* `addAcceptedScopesHeader`: **default true** Add the `X-Accepted-OAuth-Scopes` header with a list of scopes that will be accepted
+* `addAuthorizedScopesHeader`: **default true** Add the `X-OAuth-Scopes` header with a list of scopes that the user is authorized for
+* `allowBearerTokensInQueryString`: **default false** Determine if the bearer token can be included in the query string (i.e. `?access_token=`) for validation calls
+* `allowEmptyState`: **default false** If true, `state` can be empty or not passed.  If false, `state` is required.
+* `authorizationCodeLifetime`: **default 300** Default number of milliseconds that the authorization code is active for
+* `accessTokenLifetime`: **default 3600** Default number of milliseconds that an access token is valid for
+* `refreshTokenLifetime`: **default 1209600** Default number of milliseconds that a refresh token is valid for
+* `allowExtendedTokenAttributes`: **default false** Allows additional attributes (such as `id_token`) to be included in token responses.
+* `requireClientAuthentication`: **default true for all grant types** Allow ability to set client/secret authentication to `false` for a specific grant type.   
 
 The following server options have been removed in v3.0.0
 
-  * `grants`: **removed** (now returned by the _getClient_ method).
-  * `debug`: **removed** (not the responsibility of this module).
-  * `clientIdRegex`: **removed** (the _getClient_ method can return _undefined_ or throw an error).
-  * `passthroughErrors`: **removed** (not the responsibility of this module).
-  * `continueAfterResponse`: **removed** (not the responsibility of this module).
+* `grants`: **removed** (now returned by the `getClient` method).
+* `debug`: **removed** (not the responsibility of this module).
+* `clientIdRegex`: **removed** (the `getClient` method can return `undefined` or throw an error).
+* `passthroughErrors`: **removed** (not the responsibility of this module).
+* `continueAfterResponse`: **removed** (not the responsibility of this module).
 
-## Model specification
+-------------------
+Model specification
+-------------------
 
-  * `generateAccessToken(client, user, scope)` is **optional** and should return a _String.
+* `generateAccessToken(client, user, scope)` is **optional** and should return a `String`.
+* `generateAuthorizationCode()` is **optional** and should return a _String.
+* `generateRefreshToken(client, user, scope)` is **optional** and should return a `String`.
+* `getAccessToken(token)` should return an object with:
+    
+  * `accessToken` (`String`)
+  * `accessTokenExpiresAt` (`Date`)
+  * `client` (`Object`),  containing at least an `id` property that matches the supplied client
+  * `scope` (optional `String`)
+  * `user` (`Object`)
 
-  * `generateAuthorizationCode()` is **optional** and should return a _String.
+* `getAuthCode()` was renamed to `getAuthorizationCode(code)` and should return:
 
-  * `generateRefreshToken(client, user, scope)` is **optional** and should return a _String.
+  * `client` (`Object`), containing at least an `id` property that matches the supplied client
+  * `expiresAt` (`Date`)
+  * `redirectUri` (optional `String`)
+  * `user` (`Object`)
 
-  * `getAccessToken(token)` should return an object with:
-    * `accessToken` (_String_)
-    * `accessTokenExpiresAt` (_Date_)
-    * `client` (_Object_),  containing at least an `id` property that matches the supplied client
-    * `scope` (optional _String_)
-    * `user` (_Object_)
+* `getClient(clientId, clientSecret)` should return an object with, at minimum:
+  
+  * `redirectUris` (`Array`)
+  * `grants` (`Array`)
 
-  * `getAuthCode()` was renamed to `getAuthorizationCode(code)` and should return:
-    * `client` (_Object_), containing at least an `id` property that matches the supplied client
-    * `expiresAt` (_Date_)
-    * `redirectUri` (optional _String_)
-    * `user` (_Object_)
+* `getRefreshToken(token)` should return an object with:
 
-  * `getClient(clientId, clientSecret)` should return an object with, at minimum:
-    * `redirectUris` (_Array_)
-    * `grants` (_Array_)
+  * `refreshToken` (`String`)
+  * `client` (`Object`),  containing at least an `id` property that matches the supplied client
+  * `refreshTokenExpiresAt` (optional `Date`)
+  * `scope` (optional `String`)
+  * `user` (`Object`)
 
-  * `getRefreshToken(token)` should return an object with:
-    * `refreshToken` (_String_)
-    * `client` (_Object_),  containing at least an `id` property that matches the supplied client
-    * `refreshTokenExpiresAt` (optional _Date_)
-    * `scope` (optional _String_)
-    * `user` (_Object_)
+* `getUser(username, password)` should return an object:
+ 
+  * No longer requires that `id` be returned.
 
-  * `getUser(username, password)` should return an object:
-    * No longer requires that `id` be returned.
+* `getUserFromClient(client)` should return an object:
+    
+  * No longer requires that `id` be returned.
 
-  * `getUserFromClient(client)` should return an object:
-    * No longer requires that `id` be returned.
+* `grantTypeAllowed()` was **removed**. You can instead:
 
-  * `grantTypeAllowed()` was **removed**. You can instead:
-    * Return _falsy_ in your `getClient()`
-    * Throw an error in your `getClient()`
+  * Return *falsy* in your `getClient()`
+  * Throw an error in your `getClient()`
 
-  * `revokeAuthorizationCode(code)` is **required** and should return true
+* `revokeAuthorizationCode(code)` is **required** and should return true
+* `revokeToken(token)` is **required** and should return true
+* `saveAccessToken()` was renamed to `saveToken(token, client, user)` and should return:
 
-  * `revokeToken(token)` is **required** and should return true
+  * `accessToken` (`String`)
+  * `accessTokenExpiresAt` (`Date`)
+  * `client` (`Object`)
+  * `refreshToken` (optional `String`)
+  * `refreshTokenExpiresAt` (optional `Date`)
+  * `user` (`Object`)
 
-  * `saveAccessToken()` was renamed to `saveToken(token, client, user)` and should return:
-    * `accessToken` (_String_)
-    * `accessTokenExpiresAt` (_Date_)
-    * `client` (_Object_)
-    * `refreshToken` (optional _String_)
-    * `refreshTokenExpiresAt` (optional _Date_)
-    * `user` (_Object_)
+* `saveAuthCode()` was renamed to `saveAuthorizationCode(code, client, user)` and should return:
 
-  * `saveAuthCode()` was renamed to `saveAuthorizationCode(code, client, user)` and should return:
-    * `authorizationCode` (_String_)
+  * `authorizationCode` (`String`)
 
-  * `validateScope(user, client, scope)` should return a _Boolean_.
+* `validateScope(user, client, scope)` should return a `Boolean`.
 
 The full model specification is [also available](https://oauth2-server.readthedocs.io/en/latest/model/spec.html).