Skip to content

Commit

Permalink
doc: deprecate url.parse()
Browse files Browse the repository at this point in the history
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)
PR-URL: #44919
Reviewed-By: Geoffrey Booth <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Rafael Gonzaga <[email protected]>
Reviewed-By: Juan José Arboleda <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>
Reviewed-By: Michael Dawson <[email protected]>
Reviewed-By: Danielle Adams <[email protected]>
  • Loading branch information
Trott authored and danielleadams committed Jan 3, 2023
1 parent 4fcbc92 commit b4cc30e
Show file tree
Hide file tree
Showing 2 changed files with 31 additions and 16 deletions.
25 changes: 22 additions & 3 deletions doc/api/deprecations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -3255,7 +3258,7 @@ changes:
description: Runtime deprecation.
-->

Type: Runtime.
Type: Runtime

The implicit suppression of uncaught exceptions in Node-API callbacks is now
deprecated.
Expand All @@ -3264,7 +3267,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
Expand Down Expand Up @@ -3410,6 +3428,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
Expand Down
22 changes: 9 additions & 13 deletions doc/api/url.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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';
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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)`

Expand Down

0 comments on commit b4cc30e

Please sign in to comment.