Merge branch 'master' into dependabot/npm_and_yarn/type-is-2.1.0

Author: jankapunkt

.github/workflows/deploy_docs.yml

@@ -46,7 +46,7 @@ jobs:
       - name: Build with VitePress
         run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@v5
         with:
           path: docs/.vitepress/dist
 
@@ -61,4 +61,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

SECURITY.md

@@ -1,26 +1,56 @@
 # Security Policy
 
+This security policy covers the npm package [`@node-oauth/oauth2-server`](https://www.npmjs.com/package/@node-oauth/oauth2-server), maintained in the [`node-oauth/node-oauth2-server`](https://github.com/node-oauth/node-oauth2-server) repository.
+
+Because this project is a security-sensitive OAuth 2.0 authorization server library (RFC 6749 / RFC 6750), we take vulnerability reports seriously and handle them under a coordinated-disclosure process. We are grateful to the security researchers who help keep this project and its users safe.
+
 ## Supported Versions
 
-Use this section to tell people about which versions of your project are
-currently being supported with security updates.
+Security fixes are developed against the latest `5.x` release. To stay protected, keep your dependency up to date with the most recent published version.
 
 | Version | Supported                                        |
 |---------|--------------------------------------------------|
 | 5.x.x   | :white_check_mark:                               |
-| 4.x.x   | :white_check_mark: but only high severity issues |
+| 4.x.x   | :white_check_mark: but only high-severity issues |
 | 3.x.x   | :x:                                              |
 | < 3     | :x:                                              |
 
+The `5.x` line is actively maintained and receives all security fixes. The `4.x` line is a legacy line that receives backports for high-severity issues only. Versions `3.x` and older are unsupported and will not receive security updates.
+
 ## Reporting a Vulnerability
 
-Report security vulnerabilities to info@jankuester.com
+**Please report vulnerabilities privately using GitHub's private vulnerability reporting — do not open a public issue, pull request, or discussion for a security bug.** Public disclosure before a fix is available puts every user of the library at risk.
+
+To report a vulnerability:
+
+1. Open the **[Report a vulnerability](https://github.com/node-oauth/node-oauth2-server/security/advisories/new)** form directly, or go to the repository's **[Security tab](https://github.com/node-oauth/node-oauth2-server/security)** and click **"Report a vulnerability"**.
+2. Fill in the title and description (only those two fields are required) and submit the report.
+
+You will need to be signed in to GitHub. Submitting through this channel keeps the report private, notifies the maintainers directly, and automatically adds you as a collaborator on the draft advisory so we can discuss the issue with you and credit you when it is published.
+
+Reports are handled by the maintainers, [Jan Küster (@jankapunkt)](https://github.com/jankapunkt) and [Dan Hensby (@dhensby)](https://github.com/dhensby).
+
+## What to Include in a Report
+
+To help us triage, reproduce, and fix the issue quickly, please include as much of the following as you can:
+
+- A clear description of the vulnerability and its **security impact** — what an attacker can achieve by exploiting it.
+- The **affected version(s)**, and if known the relevant commit or branch.
+- **Steps to reproduce**, ideally with a minimal **proof of concept**.
+- Any **configuration or environment** needed to trigger the issue (for example the grant types, model behaviour, or framework adapter in use).
+- Optionally: a suggested fix or mitigation, your severity assessment, and whether you would like public credit in the advisory.
+
+We need to be able to **reproduce** the vulnerability — just as we do with ordinary bug reports — before we can safely fix it, so clear reproduction steps and impact details are the most valuable thing you can provide.
 
-Please specify exactly how the vulnerability is to be exploited so we can estimate how severe the consequences can be (unless you also can specify them, too).
+## What Happens Next
 
-Please note that we need to reproduce the vulnerability (as like with bugs) in order to safely fix it.
+1. **Acknowledgement & triage.** We confirm receipt of your report and begin assessing it privately through the GitHub security advisory.
+2. **Reproduction.** We reproduce the issue to understand its impact and estimate severity. We may follow up with you for clarification or additional detail.
+3. **Private fix.** A fix is developed in private — within the draft advisory or a temporary private fork — until we can confirm the vulnerability is closed. If you would like to help, let us know and we can collaborate on the fix in a private fork; only a maintainer can merge it.
+4. **Validation.** All security fixes must pass the **full test suite and dependency audits** before they ship — a security fix is never released at the expense of correctness.
+5. **Release.** Once a fix is ready, we publish a new release promptly and update the supported release lines as appropriate.
+6. **Disclosure & credit.** We publish a GitHub Security Advisory (GHSA), request a CVE where warranted, and credit you for the report unless you ask otherwise. The project actively uses GitHub Security Advisories — for example, [GHSA-jhm7-29pj-4xvf](https://github.com/node-oauth/node-oauth2-server/security/advisories/GHSA-jhm7-29pj-4xvf) (CVE-2026-41213, a PKCE brute-force issue) was fixed in `5.3.0`.
 
-A fix will be implemented in private until we can ensure the vulnerability is closed. A new release will immediately be published.
-If you want to provide a fix please let us know in the e-mail so we can setup a completely private repository to work on it together.
+## Disclosure Expectations
 
-Finally, all security fixes will also require to pass all tests and audits.
+We follow **coordinated disclosure**. Please give us a reasonable opportunity to investigate and release a fix before disclosing the vulnerability publicly, and please do not share details — including via public issues, pull requests, or discussions — until a patched release is available and the advisory is published. We will keep you informed of our progress throughout, and we aim to resolve and disclose issues promptly.

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

docs/guide/getting-started.md

@@ -81,6 +81,45 @@ oauth.authenticate(request, response)
     });
 ```
 
+### Sending the response
+
+This library is **framework-agnostic and does not send the HTTP response for you**.
+`authenticate()`, `authorize()` and `token()` resolve with their result *and*
+populate the `Response` object you passed in — setting `response.status`,
+`response.headers` and `response.body`. It is up to you to copy those onto your
+framework's real response and send it. For `authorize()` this is how the redirect
+happens: the `location` header is set on the `Response`, but you still have to
+issue it.
+
+A minimal Express example for the authorization endpoint:
+
+```js
+app.get('/authorize', async (req, res) => {
+    // Wrap the framework objects in NEW variables — see the warning below.
+    const request = new Request(req);
+    const response = new Response(res);
+
+    try {
+        await oauth.authorize(request, response, { authenticateHandler });
+    } catch (err) {
+        return res.status(err.code || 500).json({ error: err.name, error_description: err.message });
+    }
+
+    // The library populated `response`; now you send it. For authorize that is a redirect:
+    res.set(response.headers);                // includes the `location` header
+    return res.status(response.status).end(); // 302 -> the browser follows `location`
+});
+```
+
+> **Do not reassign your framework's `req`/`res`** to the library's objects
+> (e.g. `res = new Response(res)`). Doing so discards framework methods such as
+> `res.redirect()`, and is a common cause of a request appearing to "hang".
+
+If you use Express or Koa, prefer the official adapters
+([express-oauth-server](https://www.npmjs.com/package/@node-oauth/express-oauth-server),
+[koa-oauth-server](https://npmjs.org/package/koa-oauth-server)), which take care of
+all of this for you.
+
 The most crucial part in this setup is the `model`.
 It acts as the bridge between the OAuth2 server library and your system.
 

index.d.ts

@@ -258,13 +258,13 @@ declare namespace OAuth2Server {
          * Invoked to retrieve a client using a client id or a client id/client secret combination, depending on the grant type.
          *
          */
-        getClient(clientId: string, clientSecret: string): Promise<Client | Falsey>;
+        getClient(clientId: string, clientSecret?: string): Promise<Client | Falsey>;
 
         /**
          * Invoked to save an access token and optionally a refresh token, depending on the grant type.
          *
          */
-        saveToken(token: Token, client: Client, user: User): Promise<Token | Falsey>;
+        saveToken(token: Omit<Token, 'client' | 'user'>, client: Client, user: User): Promise<Token | Falsey>;
     }
 
     interface RequestAuthenticationModel {
@@ -464,6 +464,11 @@ declare namespace OAuth2Server {
          * A human-readable error message.
          */
         message: string;
+
+        /**
+         * The original error, present when this error was constructed by wrapping another `Error`.
+         */
+        inner?: Error;
     }
 
     class AccessDeniedError extends OAuthError {}

lib/grant-types/refresh-token-grant-type.js

@@ -54,10 +54,12 @@ class RefreshTokenGrantType extends AbstractGrantType {
 
     let token;
     token = await this.getRefreshToken(request, client);
-    token = await this.revokeToken(token);
 
+    // Validate scope before revoking token to prevent destroying tokens on scope validation errors
     const scope = this.getScope(request, token);
 
+    token = await this.revokeToken(token);
+
     return this.saveToken(token.user, client, scope);
   }