From 19a909902aec2cb9af13bf901db720b0b9472294 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Tue, 11 Oct 2022 15:35:52 -0700 Subject: [PATCH] doc: deprecate url.parse() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 PR-URL: https://github.com/nodejs/node/pull/44919 Reviewed-By: Geoffrey Booth Reviewed-By: Matteo Collina Reviewed-By: Luigi Pinca Reviewed-By: Rafael Gonzaga Reviewed-By: Juan José Arboleda Reviewed-By: Antoine du Hamel Reviewed-By: Michael Dawson Reviewed-By: Danielle Adams --- doc/api/deprecations.md | 25 ++++++++++++++++++++++--- doc/api/url.md | 22 +++++++++------------- 2 files changed, 31 insertions(+), 16 deletions(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 2a26f80c2ee9ce..fbb52be894f9a6 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -2288,6 +2288,9 @@ future release. -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() + + + +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 diff --git a/doc/api/url.md b/doc/api/url.md index 1ba0ca9ddf3d32..5745f82d1fe395 100644 --- a/doc/api/url.md +++ b/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: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: -> 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)`