doc: clarify proxy threat model

Signed-off-by: Matteo Collina <hello@matteocollina.com>
PR-URL: #64366
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com>
Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Gürgün Dayıoğlu <hey@gurgun.day>

Author: mcollina

SECURITY.md

@@ -221,6 +221,16 @@ then untrusted input must not lead to arbitrary JavaScript code execution.
 * The developers and infrastructure that run it.
 * The operating system that Node.js is running under and its configuration,
  along with anything under the control of the operating system.
+* The deployment network environment for the privacy of traffic and routing
+ decisions, including internal networks through which Node.js traffic passes
+ and configured HTTP(S) proxy servers. Built-in proxy support is intended to
+ route traffic through proxies authorized for the deployment, often because a
+ firewall requires one to access external networks. It is not intended to hide
+ traffic from network operators or authorities governing the deployment.
+ Untrusted or unauthorized proxies, as well as deployment policy or legal
+ compliance controls around proxy use, are the responsibility of the deployment
+ operator and are outside this threat model. This does not change that data
+ parsed from network protocol peers is untrusted as described above.
 * The code it is asked to run, including JavaScript, WASM and native code, even
  if said code is dynamically loaded, e.g., all dependencies installed from the
  npm registry.
@@ -301,6 +311,19 @@ the community they pose.
  client consuming unsolicited or misordered responses within the same HTTP/1.1 connection
  reuse lifecycle are generally not considered Node.js vulnerabilities.
 
+#### Unauthorized or untrusted HTTP proxy deployments
+
+* Built-in HTTP proxy support is intended for routing outbound requests through
+ a proxy authorized by the deployment, for example because a firewall requires
+ one to reach external networks. It is not an anonymity, traffic-hiding, or
+ policy-evasion feature.
+* Reports that depend on using an unauthorized proxy, expecting Node.js to
+ provide privacy from a configured proxy or internal network, or expecting
+ Node.js to enforce deployment-specific network policy or legal requirements
+ are not considered Node.js vulnerabilities. Deployment operators are
+ responsible for hardening such environments and controlling which proxy
+ settings are allowed.
+
 #### Malicious Third-Party Modules (CWE-1357)
 
 * Code is trusted by Node.js. Therefore any scenario that requires a malicious

doc/api/cli.md

@@ -3188,9 +3188,14 @@ added: v24.5.0
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This is equivalent to setting the [`NODE_USE_ENV_PROXY=1`][] environment variable.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -3864,9 +3869,14 @@ added: v24.0.0
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This can also be enabled using the [`--use-env-proxy`][] command-line flag.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -4170,6 +4180,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 <!-- v8-options end -->
 
 [#42511]: https://github.com/nodejs/node/issues/42511
+[Built-in Proxy Support]: http.md#built-in-proxy-support
 [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
 [Chromium's policy for locally trusted certificates]: https://chromium.googlesource.com/chromium/src/+/main/net/data/ssl/chrome_root_store/faq.md#does-the-chrome-certificate-verifier-consider-local-trust-decisions
 [CommonJS module]: modules.md

doc/api/http.md

@@ -4525,6 +4525,22 @@ support.
 
 If the request is made to a Unix domain socket, the proxy settings will be ignored.
 
+### Proxy security considerations
+
+Built-in proxy support routes outbound requests through an HTTP(S) proxy, often
+because a firewall requires one to access external networks. It is not an
+anonymity or traffic-hiding feature and does not attempt to hide traffic from
+the proxy, the local network, network operators, or authorities that govern the
+deployment.
+
+Configure only proxies that are trusted and authorized for the deployment. A
+proxy can observe connection metadata; for plain HTTP requests, or when TLS is
+terminated or intercepted by the proxy, it can also observe request and response
+contents. Node.js does not support treating an untrusted proxy as a privacy
+boundary. Deployment operators are responsible for controlling proxy
+configuration and for meeting deployment-specific network policy and legal
+requirements.
+
 ### Proxy URL Format
 
 Proxy URLs can use either HTTP or HTTPS protocols:

SECURITY.md

@@ -221,6 +221,16 @@ then untrusted input must not lead to arbitrary JavaScript code execution.
 * The developers and infrastructure that run it.
 * The operating system that Node.js is running under and its configuration,
  along with anything under the control of the operating system.
+* The deployment network environment for the privacy of traffic and routing
+ decisions, including internal networks through which Node.js traffic passes
+ and configured HTTP(S) proxy servers. Built-in proxy support is intended to
+ route traffic through proxies authorized for the deployment, often because a
+ firewall requires one to access external networks. It is not intended to hide
+ traffic from network operators or authorities governing the deployment.
+ Untrusted or unauthorized proxies, as well as deployment policy or legal
+ compliance controls around proxy use, are the responsibility of the deployment
+ operator and are outside this threat model. This does not change that data
+ parsed from network protocol peers is untrusted as described above.
 * The code it is asked to run, including JavaScript, WASM and native code, even
  if said code is dynamically loaded, e.g., all dependencies installed from the
  npm registry.
@@ -301,6 +311,19 @@ the community they pose.
  client consuming unsolicited or misordered responses within the same HTTP/1.1 connection
  reuse lifecycle are generally not considered Node.js vulnerabilities.
 
+#### Unauthorized or untrusted HTTP proxy deployments
+
+* Built-in HTTP proxy support is intended for routing outbound requests through
+ a proxy authorized by the deployment, for example because a firewall requires
+ one to reach external networks. It is not an anonymity, traffic-hiding, or
+ policy-evasion feature.
+* Reports that depend on using an unauthorized proxy, expecting Node.js to
+ provide privacy from a configured proxy or internal network, or expecting
+ Node.js to enforce deployment-specific network policy or legal requirements
+ are not considered Node.js vulnerabilities. Deployment operators are
+ responsible for hardening such environments and controlling which proxy
+ settings are allowed.
+
 #### Malicious Third-Party Modules (CWE-1357)
 
 * Code is trusted by Node.js. Therefore any scenario that requires a malicious

doc/api/cli.md

@@ -3188,9 +3188,14 @@ added: v24.5.0
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This is equivalent to setting the [`NODE_USE_ENV_PROXY=1`][] environment variable.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -3864,9 +3869,14 @@ added: v24.0.0
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This can also be enabled using the [`--use-env-proxy`][] command-line flag.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -4170,6 +4180,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 <!-- v8-options end -->
 
 [#42511]: https://github.com/nodejs/node/issues/42511
+[Built-in Proxy Support]: http.md#built-in-proxy-support
 [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
 [Chromium's policy for locally trusted certificates]: https://chromium.googlesource.com/chromium/src/+/main/net/data/ssl/chrome_root_store/faq.md#does-the-chrome-certificate-verifier-consider-local-trust-decisions
 [CommonJS module]: modules.md

doc/api/http.md

@@ -4525,6 +4525,22 @@ support.
 
 If the request is made to a Unix domain socket, the proxy settings will be ignored.
 
+### Proxy security considerations
+
+Built-in proxy support routes outbound requests through an HTTP(S) proxy, often
+because a firewall requires one to access external networks. It is not an
+anonymity or traffic-hiding feature and does not attempt to hide traffic from
+the proxy, the local network, network operators, or authorities that govern the
+deployment.
+
+Configure only proxies that are trusted and authorized for the deployment. A
+proxy can observe connection metadata; for plain HTTP requests, or when TLS is
+terminated or intercepted by the proxy, it can also observe request and response
+contents. Node.js does not support treating an untrusted proxy as a privacy
+boundary. Deployment operators are responsible for controlling proxy
+configuration and for meeting deployment-specific network policy and legal
+requirements.
+
 ### Proxy URL Format
 
 Proxy URLs can use either HTTP or HTTPS protocols:

SECURITY.md

@@ -221,6 +221,16 @@ then untrusted input must not lead to arbitrary JavaScript code execution.
 * The developers and infrastructure that run it.
 * The operating system that Node.js is running under and its configuration,
  along with anything under the control of the operating system.
+* The deployment network environment for the privacy of traffic and routing
+ decisions, including internal networks through which Node.js traffic passes
+ and configured HTTP(S) proxy servers. Built-in proxy support is intended to
+ route traffic through proxies authorized for the deployment, often because a
+ firewall requires one to access external networks. It is not intended to hide
+ traffic from network operators or authorities governing the deployment.
+ Untrusted or unauthorized proxies, as well as deployment policy or legal
+ compliance controls around proxy use, are the responsibility of the deployment
+ operator and are outside this threat model. This does not change that data
+ parsed from network protocol peers is untrusted as described above.
 * The code it is asked to run, including JavaScript, WASM and native code, even
  if said code is dynamically loaded, e.g., all dependencies installed from the
  npm registry.
@@ -301,6 +311,19 @@ the community they pose.
  client consuming unsolicited or misordered responses within the same HTTP/1.1 connection
  reuse lifecycle are generally not considered Node.js vulnerabilities.
 
+#### Unauthorized or untrusted HTTP proxy deployments
+
+* Built-in HTTP proxy support is intended for routing outbound requests through
+ a proxy authorized by the deployment, for example because a firewall requires
+ one to reach external networks. It is not an anonymity, traffic-hiding, or
+ policy-evasion feature.
+* Reports that depend on using an unauthorized proxy, expecting Node.js to
+ provide privacy from a configured proxy or internal network, or expecting
+ Node.js to enforce deployment-specific network policy or legal requirements
+ are not considered Node.js vulnerabilities. Deployment operators are
+ responsible for hardening such environments and controlling which proxy
+ settings are allowed.
+
 #### Malicious Third-Party Modules (CWE-1357)
 
 * Code is trusted by Node.js. Therefore any scenario that requires a malicious

doc/api/cli.md

@@ -3188,9 +3188,14 @@ added: v24.5.0
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This is equivalent to setting the [`NODE_USE_ENV_PROXY=1`][] environment variable.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -3864,9 +3869,14 @@ added: v24.0.0
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This can also be enabled using the [`--use-env-proxy`][] command-line flag.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -4170,6 +4180,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 <!-- v8-options end -->
 
 [#42511]: https://github.com/nodejs/node/issues/42511
+[Built-in Proxy Support]: http.md#built-in-proxy-support
 [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
 [Chromium's policy for locally trusted certificates]: https://chromium.googlesource.com/chromium/src/+/main/net/data/ssl/chrome_root_store/faq.md#does-the-chrome-certificate-verifier-consider-local-trust-decisions
 [CommonJS module]: modules.md

doc/api/http.md

@@ -4525,6 +4525,22 @@ support.
 
 If the request is made to a Unix domain socket, the proxy settings will be ignored.
 
+### Proxy security considerations
+
+Built-in proxy support routes outbound requests through an HTTP(S) proxy, often
+because a firewall requires one to access external networks. It is not an
+anonymity or traffic-hiding feature and does not attempt to hide traffic from
+the proxy, the local network, network operators, or authorities that govern the
+deployment.
+
+Configure only proxies that are trusted and authorized for the deployment. A
+proxy can observe connection metadata; for plain HTTP requests, or when TLS is
+terminated or intercepted by the proxy, it can also observe request and response
+contents. Node.js does not support treating an untrusted proxy as a privacy
+boundary. Deployment operators are responsible for controlling proxy
+configuration and for meeting deployment-specific network policy and legal
+requirements.
+
 ### Proxy URL Format
 
 Proxy URLs can use either HTTP or HTTPS protocols:

SECURITY.md

@@ -221,6 +221,16 @@ then untrusted input must not lead to arbitrary JavaScript code execution.
 * The developers and infrastructure that run it.
 * The operating system that Node.js is running under and its configuration,
  along with anything under the control of the operating system.
+* The deployment network environment for the privacy of traffic and routing
+ decisions, including internal networks through which Node.js traffic passes
+ and configured HTTP(S) proxy servers. Built-in proxy support is intended to
+ route traffic through proxies authorized for the deployment, often because a
+ firewall requires one to access external networks. It is not intended to hide
+ traffic from network operators or authorities governing the deployment.
+ Untrusted or unauthorized proxies, as well as deployment policy or legal
+ compliance controls around proxy use, are the responsibility of the deployment
+ operator and are outside this threat model. This does not change that data
+ parsed from network protocol peers is untrusted as described above.
 * The code it is asked to run, including JavaScript, WASM and native code, even
  if said code is dynamically loaded, e.g., all dependencies installed from the
  npm registry.
@@ -301,6 +311,19 @@ the community they pose.
  client consuming unsolicited or misordered responses within the same HTTP/1.1 connection
  reuse lifecycle are generally not considered Node.js vulnerabilities.
 
+#### Unauthorized or untrusted HTTP proxy deployments
+
+* Built-in HTTP proxy support is intended for routing outbound requests through
+ a proxy authorized by the deployment, for example because a firewall requires
+ one to reach external networks. It is not an anonymity, traffic-hiding, or
+ policy-evasion feature.
+* Reports that depend on using an unauthorized proxy, expecting Node.js to
+ provide privacy from a configured proxy or internal network, or expecting
+ Node.js to enforce deployment-specific network policy or legal requirements
+ are not considered Node.js vulnerabilities. Deployment operators are
+ responsible for hardening such environments and controlling which proxy
+ settings are allowed.
+
 #### Malicious Third-Party Modules (CWE-1357)
 
 * Code is trusted by Node.js. Therefore any scenario that requires a malicious

doc/api/cli.md

@@ -3188,9 +3188,14 @@ added: v24.5.0
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This is equivalent to setting the [`NODE_USE_ENV_PROXY=1`][] environment variable.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -3864,9 +3869,14 @@ added: v24.0.0
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This can also be enabled using the [`--use-env-proxy`][] command-line flag.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -4170,6 +4180,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 <!-- v8-options end -->
 
 [#42511]: https://github.com/nodejs/node/issues/42511
+[Built-in Proxy Support]: http.md#built-in-proxy-support
 [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
 [Chromium's policy for locally trusted certificates]: https://chromium.googlesource.com/chromium/src/+/main/net/data/ssl/chrome_root_store/faq.md#does-the-chrome-certificate-verifier-consider-local-trust-decisions
 [CommonJS module]: modules.md

doc/api/http.md

@@ -4525,6 +4525,22 @@ support.
 
 If the request is made to a Unix domain socket, the proxy settings will be ignored.
 
+### Proxy security considerations
+
+Built-in proxy support routes outbound requests through an HTTP(S) proxy, often
+because a firewall requires one to access external networks. It is not an
+anonymity or traffic-hiding feature and does not attempt to hide traffic from
+the proxy, the local network, network operators, or authorities that govern the
+deployment.
+
+Configure only proxies that are trusted and authorized for the deployment. A
+proxy can observe connection metadata; for plain HTTP requests, or when TLS is
+terminated or intercepted by the proxy, it can also observe request and response
+contents. Node.js does not support treating an untrusted proxy as a privacy
+boundary. Deployment operators are responsible for controlling proxy
+configuration and for meeting deployment-specific network policy and legal
+requirements.
+
 ### Proxy URL Format
 
 Proxy URLs can use either HTTP or HTTPS protocols:

SECURITY.md

@@ -221,6 +221,16 @@ then untrusted input must not lead to arbitrary JavaScript code execution.
 * The developers and infrastructure that run it.
 * The operating system that Node.js is running under and its configuration,
  along with anything under the control of the operating system.
+* The deployment network environment for the privacy of traffic and routing
+ decisions, including internal networks through which Node.js traffic passes
+ and configured HTTP(S) proxy servers. Built-in proxy support is intended to
+ route traffic through proxies authorized for the deployment, often because a
+ firewall requires one to access external networks. It is not intended to hide
+ traffic from network operators or authorities governing the deployment.
+ Untrusted or unauthorized proxies, as well as deployment policy or legal
+ compliance controls around proxy use, are the responsibility of the deployment
+ operator and are outside this threat model. This does not change that data
+ parsed from network protocol peers is untrusted as described above.
 * The code it is asked to run, including JavaScript, WASM and native code, even
  if said code is dynamically loaded, e.g., all dependencies installed from the
  npm registry.
@@ -301,6 +311,19 @@ the community they pose.
  client consuming unsolicited or misordered responses within the same HTTP/1.1 connection
  reuse lifecycle are generally not considered Node.js vulnerabilities.
 
+#### Unauthorized or untrusted HTTP proxy deployments
+
+* Built-in HTTP proxy support is intended for routing outbound requests through
+ a proxy authorized by the deployment, for example because a firewall requires
+ one to reach external networks. It is not an anonymity, traffic-hiding, or
+ policy-evasion feature.
+* Reports that depend on using an unauthorized proxy, expecting Node.js to
+ provide privacy from a configured proxy or internal network, or expecting
+ Node.js to enforce deployment-specific network policy or legal requirements
+ are not considered Node.js vulnerabilities. Deployment operators are
+ responsible for hardening such environments and controlling which proxy
+ settings are allowed.
+
 #### Malicious Third-Party Modules (CWE-1357)
 
 * Code is trusted by Node.js. Therefore any scenario that requires a malicious

doc/api/cli.md

@@ -3188,9 +3188,14 @@ added: v24.5.0
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This is equivalent to setting the [`NODE_USE_ENV_PROXY=1`][] environment variable.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -3864,9 +3869,14 @@ added: v24.0.0
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This can also be enabled using the [`--use-env-proxy`][] command-line flag.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -4170,6 +4180,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 <!-- v8-options end -->
 
 [#42511]: https://github.com/nodejs/node/issues/42511
+[Built-in Proxy Support]: http.md#built-in-proxy-support
 [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
 [Chromium's policy for locally trusted certificates]: https://chromium.googlesource.com/chromium/src/+/main/net/data/ssl/chrome_root_store/faq.md#does-the-chrome-certificate-verifier-consider-local-trust-decisions
 [CommonJS module]: modules.md

doc/api/http.md

@@ -4525,6 +4525,22 @@ support.
 
 If the request is made to a Unix domain socket, the proxy settings will be ignored.
 
+### Proxy security considerations
+
+Built-in proxy support routes outbound requests through an HTTP(S) proxy, often
+because a firewall requires one to access external networks. It is not an
+anonymity or traffic-hiding feature and does not attempt to hide traffic from
+the proxy, the local network, network operators, or authorities that govern the
+deployment.
+
+Configure only proxies that are trusted and authorized for the deployment. A
+proxy can observe connection metadata; for plain HTTP requests, or when TLS is
+terminated or intercepted by the proxy, it can also observe request and response
+contents. Node.js does not support treating an untrusted proxy as a privacy
+boundary. Deployment operators are responsible for controlling proxy
+configuration and for meeting deployment-specific network policy and legal
+requirements.
+
 ### Proxy URL Format
 
 Proxy URLs can use either HTTP or HTTPS protocols:

SECURITY.md

@@ -221,6 +221,16 @@ then untrusted input must not lead to arbitrary JavaScript code execution.
 * The developers and infrastructure that run it.
 * The operating system that Node.js is running under and its configuration,
  along with anything under the control of the operating system.
+* The deployment network environment for the privacy of traffic and routing
+ decisions, including internal networks through which Node.js traffic passes
+ and configured HTTP(S) proxy servers. Built-in proxy support is intended to
+ route traffic through proxies authorized for the deployment, often because a
+ firewall requires one to access external networks. It is not intended to hide
+ traffic from network operators or authorities governing the deployment.
+ Untrusted or unauthorized proxies, as well as deployment policy or legal
+ compliance controls around proxy use, are the responsibility of the deployment
+ operator and are outside this threat model. This does not change that data
+ parsed from network protocol peers is untrusted as described above.
 * The code it is asked to run, including JavaScript, WASM and native code, even
  if said code is dynamically loaded, e.g., all dependencies installed from the
  npm registry.
@@ -301,6 +311,19 @@ the community they pose.
  client consuming unsolicited or misordered responses within the same HTTP/1.1 connection
  reuse lifecycle are generally not considered Node.js vulnerabilities.
 
+#### Unauthorized or untrusted HTTP proxy deployments
+
+* Built-in HTTP proxy support is intended for routing outbound requests through
+ a proxy authorized by the deployment, for example because a firewall requires
+ one to reach external networks. It is not an anonymity, traffic-hiding, or
+ policy-evasion feature.
+* Reports that depend on using an unauthorized proxy, expecting Node.js to
+ provide privacy from a configured proxy or internal network, or expecting
+ Node.js to enforce deployment-specific network policy or legal requirements
+ are not considered Node.js vulnerabilities. Deployment operators are
+ responsible for hardening such environments and controlling which proxy
+ settings are allowed.
+
 #### Malicious Third-Party Modules (CWE-1357)
 
 * Code is trusted by Node.js. Therefore any scenario that requires a malicious

doc/api/cli.md

@@ -3188,9 +3188,14 @@ added: v24.5.0
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This is equivalent to setting the [`NODE_USE_ENV_PROXY=1`][] environment variable.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -3864,9 +3869,14 @@ added: v24.0.0
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This can also be enabled using the [`--use-env-proxy`][] command-line flag.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -4170,6 +4180,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 <!-- v8-options end -->
 
 [#42511]: https://github.com/nodejs/node/issues/42511
+[Built-in Proxy Support]: http.md#built-in-proxy-support
 [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
 [Chromium's policy for locally trusted certificates]: https://chromium.googlesource.com/chromium/src/+/main/net/data/ssl/chrome_root_store/faq.md#does-the-chrome-certificate-verifier-consider-local-trust-decisions
 [CommonJS module]: modules.md

doc/api/http.md

@@ -4525,6 +4525,22 @@ support.
 
 If the request is made to a Unix domain socket, the proxy settings will be ignored.
 
+### Proxy security considerations
+
+Built-in proxy support routes outbound requests through an HTTP(S) proxy, often
+because a firewall requires one to access external networks. It is not an
+anonymity or traffic-hiding feature and does not attempt to hide traffic from
+the proxy, the local network, network operators, or authorities that govern the
+deployment.
+
+Configure only proxies that are trusted and authorized for the deployment. A
+proxy can observe connection metadata; for plain HTTP requests, or when TLS is
+terminated or intercepted by the proxy, it can also observe request and response
+contents. Node.js does not support treating an untrusted proxy as a privacy
+boundary. Deployment operators are responsible for controlling proxy
+configuration and for meeting deployment-specific network policy and legal
+requirements.
+
 ### Proxy URL Format
 
 Proxy URLs can use either HTTP or HTTPS protocols:

SECURITY.md

@@ -221,6 +221,16 @@ then untrusted input must not lead to arbitrary JavaScript code execution.
 * The developers and infrastructure that run it.
 * The operating system that Node.js is running under and its configuration,
  along with anything under the control of the operating system.
+* The deployment network environment for the privacy of traffic and routing
+ decisions, including internal networks through which Node.js traffic passes
+ and configured HTTP(S) proxy servers. Built-in proxy support is intended to
+ route traffic through proxies authorized for the deployment, often because a
+ firewall requires one to access external networks. It is not intended to hide
+ traffic from network operators or authorities governing the deployment.
+ Untrusted or unauthorized proxies, as well as deployment policy or legal
+ compliance controls around proxy use, are the responsibility of the deployment
+ operator and are outside this threat model. This does not change that data
+ parsed from network protocol peers is untrusted as described above.
 * The code it is asked to run, including JavaScript, WASM and native code, even
  if said code is dynamically loaded, e.g., all dependencies installed from the
  npm registry.
@@ -301,6 +311,19 @@ the community they pose.
  client consuming unsolicited or misordered responses within the same HTTP/1.1 connection
  reuse lifecycle are generally not considered Node.js vulnerabilities.
 
+#### Unauthorized or untrusted HTTP proxy deployments
+
+* Built-in HTTP proxy support is intended for routing outbound requests through
+ a proxy authorized by the deployment, for example because a firewall requires
+ one to reach external networks. It is not an anonymity, traffic-hiding, or
+ policy-evasion feature.
+* Reports that depend on using an unauthorized proxy, expecting Node.js to
+ provide privacy from a configured proxy or internal network, or expecting
+ Node.js to enforce deployment-specific network policy or legal requirements
+ are not considered Node.js vulnerabilities. Deployment operators are
+ responsible for hardening such environments and controlling which proxy
+ settings are allowed.
+
 #### Malicious Third-Party Modules (CWE-1357)
 
 * Code is trusted by Node.js. Therefore any scenario that requires a malicious

doc/api/cli.md

@@ -3188,9 +3188,14 @@ added: v24.5.0
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This is equivalent to setting the [`NODE_USE_ENV_PROXY=1`][] environment variable.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -3864,9 +3869,14 @@ added: v24.0.0
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This can also be enabled using the [`--use-env-proxy`][] command-line flag.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -4170,6 +4180,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 <!-- v8-options end -->
 
 [#42511]: https://github.com/nodejs/node/issues/42511
+[Built-in Proxy Support]: http.md#built-in-proxy-support
 [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
 [Chromium's policy for locally trusted certificates]: https://chromium.googlesource.com/chromium/src/+/main/net/data/ssl/chrome_root_store/faq.md#does-the-chrome-certificate-verifier-consider-local-trust-decisions
 [CommonJS module]: modules.md

doc/api/http.md

@@ -4525,6 +4525,22 @@ support.
 
 If the request is made to a Unix domain socket, the proxy settings will be ignored.
 
+### Proxy security considerations
+
+Built-in proxy support routes outbound requests through an HTTP(S) proxy, often
+because a firewall requires one to access external networks. It is not an
+anonymity or traffic-hiding feature and does not attempt to hide traffic from
+the proxy, the local network, network operators, or authorities that govern the
+deployment.
+
+Configure only proxies that are trusted and authorized for the deployment. A
+proxy can observe connection metadata; for plain HTTP requests, or when TLS is
+terminated or intercepted by the proxy, it can also observe request and response
+contents. Node.js does not support treating an untrusted proxy as a privacy
+boundary. Deployment operators are responsible for controlling proxy
+configuration and for meeting deployment-specific network policy and legal
+requirements.
+
 ### Proxy URL Format
 
 Proxy URLs can use either HTTP or HTTPS protocols:

SECURITY.md

@@ -221,6 +221,16 @@ then untrusted input must not lead to arbitrary JavaScript code execution.
 * The developers and infrastructure that run it.
 * The operating system that Node.js is running under and its configuration,
  along with anything under the control of the operating system.
+* The deployment network environment for the privacy of traffic and routing
+ decisions, including internal networks through which Node.js traffic passes
+ and configured HTTP(S) proxy servers. Built-in proxy support is intended to
+ route traffic through proxies authorized for the deployment, often because a
+ firewall requires one to access external networks. It is not intended to hide
+ traffic from network operators or authorities governing the deployment.
+ Untrusted or unauthorized proxies, as well as deployment policy or legal
+ compliance controls around proxy use, are the responsibility of the deployment
+ operator and are outside this threat model. This does not change that data
+ parsed from network protocol peers is untrusted as described above.
 * The code it is asked to run, including JavaScript, WASM and native code, even
  if said code is dynamically loaded, e.g., all dependencies installed from the
  npm registry.
@@ -301,6 +311,19 @@ the community they pose.
  client consuming unsolicited or misordered responses within the same HTTP/1.1 connection
  reuse lifecycle are generally not considered Node.js vulnerabilities.
 
+#### Unauthorized or untrusted HTTP proxy deployments
+
+* Built-in HTTP proxy support is intended for routing outbound requests through
+ a proxy authorized by the deployment, for example because a firewall requires
+ one to reach external networks. It is not an anonymity, traffic-hiding, or
+ policy-evasion feature.
+* Reports that depend on using an unauthorized proxy, expecting Node.js to
+ provide privacy from a configured proxy or internal network, or expecting
+ Node.js to enforce deployment-specific network policy or legal requirements
+ are not considered Node.js vulnerabilities. Deployment operators are
+ responsible for hardening such environments and controlling which proxy
+ settings are allowed.
+
 #### Malicious Third-Party Modules (CWE-1357)
 
 * Code is trusted by Node.js. Therefore any scenario that requires a malicious

doc/api/cli.md

@@ -3188,9 +3188,14 @@ added: v24.5.0
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This is equivalent to setting the [`NODE_USE_ENV_PROXY=1`][] environment variable.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -3864,9 +3869,14 @@ added: v24.0.0
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This can also be enabled using the [`--use-env-proxy`][] command-line flag.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -4170,6 +4180,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 <!-- v8-options end -->
 
 [#42511]: https://github.com/nodejs/node/issues/42511
+[Built-in Proxy Support]: http.md#built-in-proxy-support
 [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
 [Chromium's policy for locally trusted certificates]: https://chromium.googlesource.com/chromium/src/+/main/net/data/ssl/chrome_root_store/faq.md#does-the-chrome-certificate-verifier-consider-local-trust-decisions
 [CommonJS module]: modules.md

doc/api/http.md

@@ -4525,6 +4525,22 @@ support.
 
 If the request is made to a Unix domain socket, the proxy settings will be ignored.
 
+### Proxy security considerations
+
+Built-in proxy support routes outbound requests through an HTTP(S) proxy, often
+because a firewall requires one to access external networks. It is not an
+anonymity or traffic-hiding feature and does not attempt to hide traffic from
+the proxy, the local network, network operators, or authorities that govern the
+deployment.
+
+Configure only proxies that are trusted and authorized for the deployment. A
+proxy can observe connection metadata; for plain HTTP requests, or when TLS is
+terminated or intercepted by the proxy, it can also observe request and response
+contents. Node.js does not support treating an untrusted proxy as a privacy
+boundary. Deployment operators are responsible for controlling proxy
+configuration and for meeting deployment-specific network policy and legal
+requirements.
+
 ### Proxy URL Format
 
 Proxy URLs can use either HTTP or HTTPS protocols: