Merge pull request #443 from dhensby/docs/model-typedef-fixes

docs: fix incorrect model typedefs (AuthorizationCodeData / ClientData)

Author: jankapunkt

docs/api/grant-types/authorization-code-grant-type.md

@@ -7,6 +7,7 @@
     * [new AuthorizationCodeGrantType(options)](#new_AuthorizationCodeGrantType_new)
     * [.handle(request, client)](#AuthorizationCodeGrantType+handle)
     * [.getAuthorizationCode(request, client)](#AuthorizationCodeGrantType+getAuthorizationCode) ⇒ <code>Promise.&lt;{user}&gt;</code>
+    * [.verifyPKCE(request, code)](#AuthorizationCodeGrantType+verifyPKCE)
     * [.validateRedirectUri(request, code)](#AuthorizationCodeGrantType+validateRedirectUri)
     * [.revokeAuthorizationCode(code)](#AuthorizationCodeGrantType+revokeAuthorizationCode)
     * [.saveToken(user, client, authorizationCode, requestedScope)](#AuthorizationCodeGrantType+saveToken)
@@ -44,6 +45,23 @@ Get the authorization code.
 | request | <code>Request</code> | 
 | client | <code>ClientData</code> | 
 
+<a name="AuthorizationCodeGrantType+verifyPKCE"></a>
+
+### authorizationCodeGrantType.verifyPKCE(request, code)
+Verify PKCE code_verifier against the stored code_challenge.
+
+This is called from handle() AFTER the authorization code has been
+revoked, so that a failed verification attempt consumes the code
+and prevents online brute-force guessing.
+
+**Kind**: instance method of [<code>AuthorizationCodeGrantType</code>](#AuthorizationCodeGrantType)  
+**See**: https://datatracker.ietf.org/doc/html/rfc7636#section-4.6  
+
+| Param | Type |
+| --- | --- |
+| request | <code>Request</code> | 
+| code | <code>AuthorizationCodeData</code> | 
+
 <a name="AuthorizationCodeGrantType+validateRedirectUri"></a>
 
 ### authorizationCodeGrantType.validateRedirectUri(request, code)

docs/api/handlers/authorize-handler.md

@@ -125,15 +125,20 @@ Update response with the redirect uri and the state parameter, if available.
 <a name="AuthorizeHandler+getCodeChallengeMethod"></a>
 
 ### authorizeHandler.getCodeChallengeMethod()
-Get code challenge method from request or defaults to plain.
-https://www.rfc-editor.org/rfc/rfc7636#section-4.3
+Get code challenge method from request.
+
+When `enablePlainPKCE` is false (the default), the "plain" method is
+rejected and the default (when no method is provided) is "S256".
+When `enablePlainPKCE` is true, "plain" is accepted and used as the
+default per RFC 7636 §4.3.
 
 **Kind**: instance method of [<code>AuthorizeHandler</code>](#AuthorizeHandler)  
 **Throws**:
 
 - <code>InvalidRequestError</code> if request contains unsupported code_challenge_method
  (see https://www.rfc-editor.org/rfc/rfc7636#section-4.4)
 
+**See**: https://www.rfc-editor.org/rfc/rfc7636#section-4.3  
 <a name="responseTypes"></a>
 
 ## responseTypes

docs/api/model.md

@@ -657,7 +657,7 @@ An `Object` representing the authorization code and associated data. `code.clien
 
 | Name | Type | Description |
 | --- | --- | --- |
-| code | <code>string</code> | The authorization code passed to `getAuthorizationCode()`. |
+| authorizationCode | <code>string</code> | The authorization code passed to `getAuthorizationCode()`. |
 | expiresAt | <code>Date</code> | The expiry time of the authorization code. |
 | redirectUri | <code>string</code> | The redirect URI of the authorization code. |
 | scope | <code>Array.&lt;string&gt;</code> | The authorized scope of the authorization code. |
@@ -674,7 +674,7 @@ An `Object` representing the client and associated data.
 
 | Name | Type | Description |
 | --- | --- | --- |
-| id | <code>string</code> | The authorization code passed to `getAuthorizationCode()`. |
+| id | <code>string</code> | A unique string identifying the client. |
 | redirectUris | <code>Array.&lt;string&gt;</code> | Redirect URIs allowed for the client. Required for the `authorization_code` grant. |
 | grants | <code>Array.&lt;string&gt;</code> | Grant types allowed for the client. |
 | accessTokenLifetime | <code>number</code> | Client-specific lifetime of generated access tokens in seconds. |

docs/api/pkce/pkce.md

@@ -1,3 +1,22 @@
+## Modules
+
+<dl>
+<dt><a href="#module_pkce">pkce</a></dt>
+<dd></dd>
+</dl>
+
+## Constants
+
+<dl>
+<dt><a href="#codeChallengeAndVerifierRegexp">codeChallengeAndVerifierRegexp</a> : <code>RegExp</code></dt>
+<dd><p>ABNF for &quot;code_verifier&quot; and &quot;code_challenge&quot; is as follows.</p>
+<p>code-verifier = 43*128unreserved
+unreserved = ALPHA / DIGIT / &quot;-&quot; / &quot;.&quot; / &quot;_&quot; / &quot;~&quot;
+ALPHA = %x41-5A / %x61-7A
+DIGIT = %x30-39</p>
+</dd>
+</dl>
+
 <a name="module_pkce"></a>
 
 ## pkce
@@ -62,3 +81,14 @@ Checks if the code challenge method is one of the supported methods
 | --- | --- |
 | method | <code>String</code> | 
 
+<a name="codeChallengeAndVerifierRegexp"></a>
+
+## codeChallengeAndVerifierRegexp : <code>RegExp</code>
+ABNF for "code_verifier" and "code_challenge" is as follows.
+
+code-verifier = 43*128unreserved
+unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
+ALPHA = %x41-5A / %x61-7A
+DIGIT = %x30-39
+
+**Kind**: global constant  

docs/api/server.md

@@ -43,6 +43,7 @@ Instantiates `OAuth2Server` using the supplied model.
 | [options.requireClientAuthentication] | <code>object</code> \| <code>boolean</code> | <code>object</code> | Require a client secret for grant types (names as keys). Defaults to `true` for all grant types. |
 | [options.alwaysIssueNewRefreshToken] | <code>boolean</code> | <code>true</code> | Always revoke the used refresh token and issue a new one for the `refresh_token` grant. |
 | [options.extendedGrantTypes] | <code>object</code> | <code>object</code> | Additional supported grant types. |
+| [options.enablePlainPKCE] | <code>boolean</code> | <code>false</code> | Allow the use of the `plain` code challenge method for PKCE. This is not recommended for production environments. |
 
 **Example**  
 ```js

lib/model.js

@@ -29,7 +29,7 @@ const ServerError = require('./errors/server-error');
 /**
  * @typedef AuthorizationCodeData
  * @description An `Object` representing the authorization code and associated data. `code.client` and `code.user` can carry additional properties that will be ignored by *oauth2-server*.
- * @property code {string} The authorization code passed to `getAuthorizationCode()`.
+ * @property authorizationCode {string} The authorization code passed to `getAuthorizationCode()`.
  * @property expiresAt {Date} The expiry time of the authorization code.
  * @property redirectUri {string} The redirect URI of the authorization code.
  * @property scope {string[]} The authorized scope of the authorization code.
@@ -41,7 +41,7 @@ const ServerError = require('./errors/server-error');
  * @typedef ClientData
  * @alias ClientData
  * @description An `Object` representing the client and associated data.
- * @property id {string} The authorization code passed to `getAuthorizationCode()`.
+ * @property id {string} A unique string identifying the client.
  * @property redirectUris {string[]} Redirect URIs allowed for the client. Required for the `authorization_code` grant.
  * @property grants {string[]} Grant types allowed for the client.
  * @property accessTokenLifetime {number} Client-specific lifetime of generated access tokens in seconds.