Repository: nodejs/node
Pull request: doc: deprecate url.parse()

This is a documentation-deprecation only and it is possible that it will not proceed to a runtime-deprecation any time in the foreseeable future. But url.parse() is not standardized and prone to errors that have security implications.

Refs: https://github.com/nodejs/node/issues/44911#issuecomment-1271631345

<!--
Before submitting a pull request, please read
https://github.com/nodejs/node/blob/HEAD/CONTRIBUTING.md.

Commit message formatting guidelines:
https://github.com/nodejs/node/blob/HEAD/doc/contributing/pull-requests.md#commit-message-guidelines

For code changes:
1. Include tests for any bug fixes or new features.
2. Update documentation if relevant.
3. Ensure that `make -j4 test` (UNIX), or `vcbuild test` (Windows) passes.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.
-->


Changed files:
filename: doc/api/deprecations.md
patch: @@ -2288,6 +2288,9 @@ future release.
 
 <!-- YAML
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/44919
+    description: \`url.parse()` is deprecated again in DEP0169.
   - version:
       - v15.13.0
       - v14.17.0
@@ -2300,7 +2303,7 @@ changes:
 
 Type: Deprecation revoked
 
-The [Legacy URL API][] is deprecated. This includes [`url.format()`][],
+The [legacy URL API][] is deprecated. This includes [`url.format()`][],
 [`url.parse()`][], [`url.resolve()`][], and the [legacy `urlObject`][]. Please
 use the [WHATWG URL API][] instead.
 
@@ -3258,7 +3261,7 @@ changes:
     description: Runtime deprecation.
 -->
 
-Type: Runtime.
+Type: Runtime
 
 The implicit suppression of uncaught exceptions in Node-API callbacks is now
 deprecated.
@@ -3267,7 +3270,22 @@ Set the flag [`--force-node-api-uncaught-exceptions-policy`][] to force Node.js
 to emit an [`'uncaughtException'`][] event if the exception is not handled in
 Node-API callbacks.
 
-[Legacy URL API]: url.md#legacy-url-api
+### DEP0169: Insecure url.parse()
+
+<!-- YAML
+changes:
+  - version:
+      - REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/44919
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+[`url.parse()`][] behavior is not standardized and prone to errors that
+have security implications. Use the [WHATWG URL API][] instead. CVEs are not
+issued for `url.parse()` vulnerabilities.
+
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
 [RFC 8247 Section 2.4]: https://www.rfc-editor.org/rfc/rfc8247#section-2.4
@@ -3413,6 +3431,7 @@ Node-API callbacks.
 [alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize
 [from_arraybuffer]: buffer.md#static-method-bufferfromarraybuffer-byteoffset-length
 [from_string_encoding]: buffer.md#static-method-bufferfromstring-encoding
+[legacy URL API]: url.md#legacy-url-api
 [legacy `urlObject`]: url.md#legacy-urlobject
 [static methods of `crypto.Certificate()`]: crypto.md#class-certificate
 [subpath exports]: packages.md#subpath-exports

filename: doc/api/url.md
patch: @@ -27,7 +27,7 @@ The `node:url` module provides two APIs for working with URLs: a legacy API that
 is Node.js specific, and a newer API that implements the same
 [WHATWG URL Standard][] used by web browsers.
 
-A comparison between the WHATWG and Legacy APIs is provided below. Above the URL
+A comparison between the WHATWG and legacy APIs is provided below. Above the URL
 `'https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'`, properties
 of an object returned by the legacy `url.parse()` are shown. Below it are
 properties of a WHATWG `URL` object.
@@ -63,7 +63,7 @@ const myURL =
   new URL('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash');
 ```
 
-Parsing the URL string using the Legacy API:
+Parsing the URL string using the legacy API:
 
 ```mjs
 import url from 'node:url';
@@ -1521,6 +1521,9 @@ The formatting process operates as follows:
 <!-- YAML
 added: v0.1.25
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/44919
+    description: Documentation-only deprecation.
   - version:
       - v15.13.0
       - v14.17.0
@@ -1540,7 +1543,7 @@ changes:
                  when no query string is present.
 -->
 
-> Stability: 3 - Legacy: Use the WHATWG URL API instead.
+> Stability: 0 - Deprecated: Use the WHATWG URL API instead.
 
 * `urlString` {string} The URL string to parse.
 * `parseQueryString` {boolean} If `true`, the `query` property will always
@@ -1562,16 +1565,9 @@ A `URIError` is thrown if the `auth` property is present but cannot be decoded.
 
 `url.parse()` uses a lenient, non-standard algorithm for parsing URL
 strings. It is prone to security issues such as [host name spoofing][]
-and incorrect handling of usernames and passwords.
-
-`url.parse()` is an exception to most of the legacy APIs. Despite its security
-concerns, it is legacy and not deprecated because it is:
-
-* Faster than the alternative WHATWG `URL` parser.
-* Easier to use with regards to relative URLs than the alternative WHATWG `URL` API.
-* Widely relied upon within the npm ecosystem.
-
-Use with caution.
+and incorrect handling of usernames and passwords. Do not use with untrusted
+input. CVEs are not issued for `url.parse()` vulnerabilities. Use the
+[WHATWG URL][] API instead.
 
 ### `url.resolve(from, to)`