docs: update external docs (#2161)

Co-authored-by: Create or Update Pull Request Action <create-or-update-pull-request@users.noreply.github.com>
2026-02-21 19:41:33 +00:00 · 2026-01-21 21:52:04 -05:00
parent 7d1613e720
commit 34836ff41f
4 changed files with 131 additions and 44 deletions
--- a/_includes/readmes/body-parser.md
+++ b/_includes/readmes/body-parser.md
@@ -51,7 +51,14 @@ $ npm install body-parser
 ## API

 ```js
+// Import all parsers
 const bodyParser = require('body-parser')
+
+// Or import individual parsers directly
+const json = require('body-parser/json')
+const urlencoded = require('body-parser/urlencoded')
+const raw = require('body-parser/raw')
+const text = require('body-parser/text')
 ```

 The `bodyParser` object exposes various factories to create middlewares. All
@@ -221,8 +228,8 @@ encoding of the request. The parsing can be aborted by throwing an error.

 Returns middleware that only parses `urlencoded` bodies and only looks at
 requests where the `Content-Type` header matches the `type` option. This
-parser accepts only UTF-8 encoding of the body and supports automatic
-inflation of `gzip`, `br` (brotli) and `deflate` encodings.
+parser accepts only UTF-8 and ISO-8859-1 encodings of the body and supports 
+automatic inflation of `gzip`, `br` (brotli) and `deflate` encodings.

 A new `body` object containing the parsed data is populated on the `request`
 object after the middleware (i.e. `req.body`). This object will contain
--- a/_includes/readmes/cors.md
+++ b/_includes/readmes/cors.md
@@ -5,7 +5,10 @@
 [![Build Status][github-actions-ci-image]][github-actions-ci-url]
 [![Test Coverage][coveralls-image]][coveralls-url]

-CORS is a [Node.js](https://nodejs.org/en/) package for providing a [Connect](https://github.com/senchalabs/connect)/[Express](https://expressjs.com/) middleware that can be used to enable [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) with various options.
+CORS is a [Node.js](https://nodejs.org/en/) middleware for [Express](https://expressjs.com/)/[Connect](https://github.com/senchalabs/connect) that sets [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) response headers. These headers tell browsers which origins can read responses from your server.
+
+> [!IMPORTANT]
+> **How CORS Works:** This package sets response headers—it doesn't block requests. CORS is enforced by browsers: they check the headers and decide if JavaScript can read the response. Non-browser clients (curl, Postman, other servers) ignore CORS entirely. See the [MDN CORS guide](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) for details.

 * [Installation](#installation)
 * [Usage](#usage)
@@ -16,6 +19,7 @@ CORS is a [Node.js](https://nodejs.org/en/) package for providing a [Connect](ht
  * [Enabling CORS Pre-Flight](#enabling-cors-pre-flight)
  * [Customizing CORS Settings Dynamically per Request](#customizing-cors-settings-dynamically-per-request)
 * [Configuration Options](#configuration-options)
+* [Common Misconceptions](#common-misconceptions)
 * [License](#license)
 * [Original Author](#original-author)

@@ -38,14 +42,15 @@ var express = require('express')
 var cors = require('cors')
 var app = express()

+// Adds headers: Access-Control-Allow-Origin: *
 app.use(cors())

 app.get('/products/:id', function (req, res, next) {
-  res.json({msg: 'This is CORS-enabled for all origins!'})
+  res.json({msg: 'Hello'})
 })

 app.listen(80, function () {
-  console.log('CORS-enabled web server listening on port 80')
+  console.log('web server listening on port 80')
 })
 ```

@@ -56,12 +61,13 @@ var express = require('express')
 var cors = require('cors')
 var app = express()

+// Adds headers: Access-Control-Allow-Origin: *
 app.get('/products/:id', cors(), function (req, res, next) {
-  res.json({msg: 'This is CORS-enabled for a Single Route'})
+  res.json({msg: 'Hello'})
 })

 app.listen(80, function () {
-  console.log('CORS-enabled web server listening on port 80')
+  console.log('web server listening on port 80')
 })
 ```

@@ -79,12 +85,13 @@ var corsOptions = {
  optionsSuccessStatus: 200 // some legacy browsers (IE11, various SmartTVs) choke on 204
 }

+// Adds headers: Access-Control-Allow-Origin: http://example.com, Vary: Origin
 app.get('/products/:id', cors(corsOptions), function (req, res, next) {
-  res.json({msg: 'This is CORS-enabled for only example.com.'})
+  res.json({msg: 'Hello'})
 })

 app.listen(80, function () {
-  console.log('CORS-enabled web server listening on port 80')
+  console.log('web server listening on port 80')
 })
 ```

@@ -118,12 +125,13 @@ var corsOptions = {
  }
 }

+// Adds headers: Access-Control-Allow-Origin: <matched origin>, Vary: Origin
 app.get('/products/:id', cors(corsOptions), function (req, res, next) {
-  res.json({msg: 'This is CORS-enabled for an allowed domain.'})
+  res.json({msg: 'Hello'})
 })

 app.listen(80, function () {
-  console.log('CORS-enabled web server listening on port 80')
+  console.log('web server listening on port 80')
 })
 ```

@@ -141,13 +149,13 @@ var express = require('express')
 var cors = require('cors')
 var app = express()

-app.options('/products/:id', cors()) // enable pre-flight request for DELETE request
+app.options('/products/:id', cors()) // preflight for DELETE
 app.del('/products/:id', cors(), function (req, res, next) {
-  res.json({msg: 'This is CORS-enabled for all origins!'})
+  res.json({msg: 'Hello'})
 })

 app.listen(80, function () {
-  console.log('CORS-enabled web server listening on port 80')
+  console.log('web server listening on port 80')
 })
 ```

@@ -181,12 +189,14 @@ Here’s an example that handles both public routes and restricted, credential-s
 var dynamicCorsOptions = function(req, callback) {
  var corsOptions;
  if (req.path.startsWith('/auth/connect/')) {
+    // Access-Control-Allow-Origin: http://mydomain.com, Access-Control-Allow-Credentials: true, Vary: Origin
    corsOptions = {
-      origin: 'http://mydomain.com', // Allow only a specific origin
-      credentials: true,            // Enable cookies and credentials
+      origin: 'http://mydomain.com',
+      credentials: true
    };
  } else {
-    corsOptions = { origin: '*' };   // Allow all origins for other routes
+    // Access-Control-Allow-Origin: *
+    corsOptions = { origin: '*' };
  }
  callback(null, corsOptions);
 };
@@ -194,15 +204,15 @@ var dynamicCorsOptions = function(req, callback) {
 app.use(cors(dynamicCorsOptions));

 app.get('/auth/connect/twitter', function (req, res) {
-  res.send('CORS dynamically applied for Twitter authentication.');
+  res.send('Hello');
 });

 app.get('/public', function (req, res) {
-  res.send('Public data with open CORS.');
+  res.send('Hello');
 });

 app.listen(80, function () {
-  console.log('CORS-enabled web server listening on port 80')
+  console.log('web server listening on port 80')
 })
 ```

@@ -235,7 +245,19 @@ The default configuration is the equivalent of:
 }
 ```

-For details on the effect of each CORS header, read [this](https://web.dev/articles/cross-origin-resource-sharing) article.
+## Common Misconceptions
+
+### "CORS blocks requests from disallowed origins"
+
+**No.** Your server receives and processes every request. CORS headers tell the browser whether JavaScript can read the response—not whether the request is allowed.
+
+### "CORS protects my API from unauthorized access"
+
+**No.** CORS is not access control. Any HTTP client (curl, Postman, another server) can call your API regardless of CORS settings. Use authentication and authorization to protect your API.
+
+### "Setting `origin: 'http://example.com'` means only that domain can access my server"
+
+**No.** It means browsers will only let JavaScript from that origin read responses. The server still responds to all requests.

 ## License

--- a/_includes/readmes/session.md
+++ b/_includes/readmes/session.md
@@ -49,6 +49,26 @@ For a list of stores, see [compatible session stores](#compatible-session-stores
 Settings object for the session ID cookie. The default value is
 `{ path: '/', httpOnly: true, secure: false, maxAge: null }`.

+In addition to providing a static object, you can also pass a callback function to dynamically generate the cookie options for each request. The callback receives the `req` object as its argument and should return an object containing the cookie settings.
+
+```js
+var app = express()
+app.use(session({
+  secret: 'keyboard cat',
+  resave: false,
+  saveUninitialized: true,
+  cookie: function(req) {
+    var match = req.url.match(/^\/([^/]+)/);
+    return {
+      path: match ? '/' + match[1] : '/',
+      httpOnly: true,
+      secure: req.secure || false,
+      maxAge: 60000
+    }
+  }
+}))
+```
+
 The following are options that can be set in this object.

 ##### cookie.domain
@@ -130,6 +150,7 @@ By default, this is `false`.
  - `'lax'` will set the `SameSite` attribute to `Lax` for lax same site enforcement.
  - `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.
  - `'strict'` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
+  - `'auto'` will set the `SameSite` attribute to `None` for secure connections and `Lax` for non-secure connections.

 More information about the different enforcement levels can be found in
 [the specification][rfc-6265bis-03-4.1.2.7].
@@ -141,6 +162,14 @@ the future. This also means many clients may ignore this attribute until they un
 that requires that the `Secure` attribute be set to `true` when the `SameSite` attribute has been
 set to `'none'`. Some web browsers or other clients may be adopting this specification.

+The `cookie.sameSite` option can also be set to the special value `'auto'` to have
+this setting automatically match the determined security of the connection. When the connection
+is secure (HTTPS), the `SameSite` attribute will be set to `None` to enable cross-site usage.
+When the connection is not secure (HTTP), the `SameSite` attribute will be set to `Lax` for
+better security while maintaining functionality. This is useful when the Express `"trust proxy"`
+setting is properly setup to simplify development vs production configuration, particularly
+for SAML authentication scenarios.
+
 ##### cookie.secure

 Specifies the `boolean` value for the `Secure` `Set-Cookie` attribute. When truthy,
--- a/en/resources/contributing.md
+++ b/en/resources/contributing.md
@@ -301,37 +301,62 @@ visibility or maintainer input.
 This document outlines security procedures and general policies for the Express
 project.

-  * [Reporting a Bug](#reporting-a-bug)
+  * [Reporting a Bug or Security Vulnerability](#reporting-a-bug-or-security-vulnerability)
  * [Disclosure Policy](#disclosure-policy)
  * [Comments on this Policy](#comments-on-this-policy)
+  * [The Express Threat Model](#the-express-threat-model)

-### Reporting a Bug
+### Reporting a Bug or Security Vulnerability  

-The Express team and community take all security bugs in Express seriously.
-Thank you for improving the security of Express. We appreciate your efforts and
-responsible disclosure and will make every effort to acknowledge your
-contributions.
+> [!IMPORTANT]
+> Before reporting a vulnerability, please review the [Express Threat Model](#the-express-threat-model) to check if the issue falls within Express's security scope.

-Report security bugs by emailing `express-security@lists.openjsf.org`.
+The Express team and community take all security vulnerabilities seriously. 
+Thank you for improving the security of Express and related projects. 
+We appreciate your efforts in responsible disclosure and will make every effort 
+to acknowledge your contributions.  

-To ensure the timely response to your report, please ensure that the entirety
-of the report is contained within the email body and not solely behind a web
-link or an attachment.
+A [Security triage team member](https://github.com/expressjs/security-wg#security-triage-team-expressjssecurity-triage) 
+or [the repo captain](https://github.com/expressjs/discussions/blob/master/docs/contributing/captains_and_committers.md) 
+will acknowledge your report as soon as possible. 
+These timelines may extend when our triage 
+volunteers are away on holiday, particularly at the end of the year.

-The lead maintainer will acknowledge your email within 48 hours, and will send a
-more detailed response within 48 hours indicating the next steps in handling
-your report. After the initial reply to your report, the security team will
+After the initial reply to your report, the security team will
 endeavor to keep you informed of the progress towards a fix and full
 announcement, and may ask for additional information or guidance.

-Report security bugs in third-party modules to the person or team maintaining
-the module.
+> [!NOTE]  
+> You can find more information about our process in [this guide](https://github.com/expressjs/security-wg/blob/main/docs/incident_response_plan.md)

-### Pre-release Versions

-Alpha and Beta releases are unstable and **not suitable for production use**.
-Vulnerabilities found in pre-releases should be reported according to the [Reporting a Bug](#reporting-a-bug) section.
-Due to the unstable nature of the branch it is not guaranteed that any fixes will be released in the next pre-release.
+#### Reporting Security Bugs via GitHub Security Advisory (Preferred)  
+
+The preferred way to report security vulnerabilities is through 
+[GitHub Security Advisories](https://github.com/advisories). 
+This allows us to collaborate on a fix while maintaining the 
+confidentiality of the report.  
+
+To report a vulnerability
+([docs](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)):  
+1. Visit the **Security** tab of the affected repository on GitHub.  
+2. Click **Report a vulnerability** and follow the provided steps.  
+
+This process applies to any repositories within the Express ecosystem. 
+If you are unsure whether a repository falls under this policy, 
+feel free to reach out via email.  
+
+#### Reporting via Email  
+
+If you prefer, you can also report security issues by emailing `express-security@lists.openjsf.org`.  
+
+To ensure a timely response, please include all relevant details directly in the email body rather than linking to external sources or attaching files.  
+
+The lead maintainer will acknowledge your email within 48 hours and provide an initial response outlining the next steps. The security team will keep you updated on the progress and may request additional details.  
+
+#### Third-Party Modules  
+
+If the security issue pertains to a third-party module that is not directly maintained within the Express ecosystem, please report it to the maintainers of that module.  

 ### Disclosure Policy

@@ -344,15 +369,19 @@ involving the following steps:
  * Prepare fixes for all releases still under maintenance. These fixes will be
    released as fast as possible to npm.

-### The Express Threat Model
-
-We are currently working on a new version of the security model, the most updated version can be found [here](https://github.com/expressjs/security-wg/blob/main/docs/ThreatModel.md)
-
 ### Comments on this Policy

 If you have suggestions on how this process could be improved please submit a
 pull request.

+### The Express Threat Model
+
+The Express threat model defines the boundaries of what the framework considers its security responsibility. It establishes which elements are trusted (such as the developer, the runtime environment, and application code) versus untrusted (such as data from network connections). Issues arising from trusted elements are considered out of scope, while Express is responsible for safely handling untrusted data.
+
+Many commonly reported concerns fall outside Express's security scope and are the responsibility of the application developer. Such as prototype pollution from unsanitized user input, misconfigured static file serving, or issues in third-party dependencies.
+
+For complete details, see the [Express Threat Model](https://github.com/expressjs/security-wg/blob/main/docs/ThreatModel.md).
+
 ----
 # Contributing to Expressjs.com {#expressjs-website-contributing}