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: #44911 (comment)

Author: Trott

doc/api/deprecations.md

@@ -3258,7 +3258,7 @@ changes:
     description: Runtime deprecation.
 -->
 
-Type: Runtime.
+Type: Runtime
 
 The implicit suppression of uncaught exceptions in Node-API callbacks is now
 deprecated.
@@ -3267,6 +3267,21 @@ 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.
 
+### DEP0169: Insecure url.parse()
+
+<!-- YAML
+changes:
+  - version:
+      - REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/44918
+    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.
+
 [Legacy URL API]: url.md#legacy-url-api
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3

doc/api/url.md

@@ -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:[email protected]: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:[email protected]: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/44918
+    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,8 @@ 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. Use the [WHATWG URL][] API
+instead.
 
 ### `url.resolve(from, to)`