Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 76 additions & 32 deletions deps/undici/src/SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,29 @@ issue.

Undici is an HTTP client library for Node.js. Its threat model is derived from
and aligned with the [Node.js threat model](https://github.com/nodejs/node/blob/HEAD/SECURITY.md#the-nodejs-threat-model).
The Node.js policy is authoritative for the copy of undici bundled with
Node.js. This section applies the same boundaries to the standalone undici
package.

### Security triage dispositions

Security reports are classified using the same dispositions as Node.js:

* **Vulnerability**: An undici defect that is exploitable across an
undici-owned security boundary and meets the criteria under
[What constitutes a vulnerability](#what-constitutes-a-vulnerability),
including any applicable DoS criteria.
* **Security-interest bug**: A real undici defect, or an API behavior likely to
cause security bugs in applications, that is not itself a vulnerability
under this threat model. These are fixed as regular bugs and do not
automatically receive a CVE, but should still be reported privately first
when they affect a common security control such as protocol interpretation,
certificate validation, or TLS decisions.
* **Common bug**: A correctness, robustness, or crash issue without an
undici-owned security boundary or a realistic cross-boundary attacker
benefit.
* **Invalid / out of scope**: A report that cannot be reproduced, is not an
undici defect, or concerns behavior excluded by this policy.

### What constitutes a vulnerability

Expand All @@ -53,35 +76,49 @@ For a behavior to be considered a DoS vulnerability, the proof of concept must
meet the following criteria:

* The API is being correctly used.
* The API is public and documented.
* The behavior is significant enough to cause a denial of service quickly
or in a context not controlled by the application developer (for example,
HTTP parsing).
* The API does not have a warning against its use in production.
* The API is public and documented. For standards-based APIs, the behavior
must be well-defined by the applicable specification.
* The API is stable. For APIs bundled in Node.js, it must have stable (2.0)
status.
* The behavior is significant enough to cause a denial of service quickly or
in a context not controlled by the application developer, such as protocol
parsing.
* The behavior is directly exploitable by an untrusted source without requiring
application mistakes.
* The behavior cannot be reasonably mitigated through standard operational
practices (like process recycling).
practices, such as process recycling.
* The behavior occurs deterministically under normal usage patterns rather than
only in edge cases.
* The behavior occurs at a rate that would cause practical resource exhaustion
within a practical timeframe under typical workloads.
* The attack demonstrates
[asymmetric resource consumption](https://cwe.mitre.org/data/definitions/405.html),
where the attacker expends significantly fewer resources than what is required
by the client to process the attack.
where the attacker expends significantly fewer resources than the client
must expend to process the attack. Attacks requiring comparable resources on
the attacker's side, which can be mitigated through practices such as rate
limiting, may not qualify.

**Undici does NOT trust**:

* Data received from the remote end of HTTP connections (both inbound responses
and server-sent data) that is parsed or transformed by undici before being
passed to the application. This includes:
* Data received from the remote end of outbound network connections created
through undici APIs and transformed or validated by undici before being
passed to the application, **except with respect to payload length**. Undici
trusts applications to make connections and requests that avoid payload
sizes that would result in a denial of service. Subject to that exception,
untrusted data includes:
* HTTP response headers and status lines.
* HTTP response bodies when processed by undici (e.g., chunked transfer
decoding, content-encoding).
* HTTP response bodies processed by undici, such as chunked transfer decoding
and content-encoding.
* WebSocket frames received from a server.
* Server-Sent Events (EventSource) data received from a server.
* TLS certificate validation performed by undici on behalf of the application.

**Undici trusts**:

* The application code that uses its APIs, including all configuration,
options, callbacks, and decisions about which body-consuming APIs to call.
options, callbacks, connection and request decisions, and decisions about
which body-consuming APIs to call.
* The operating system and its network stack.
* The Node.js runtime undici is running on.
* Dependencies installed by the application.
Expand All @@ -99,19 +136,19 @@ meet the following criteria:
bypass organizational, regulatory, or legal controls. Untrusted proxies are
outside the supported threat model.

In other words, if untrusted data passing through undici to the application
can trigger actions other than those documented for the APIs, there is likely
a security vulnerability. Examples of unwanted actions are polluting globals,
causing an unrecoverable crash, or any other unexpected side effects that can
lead to a loss of confidentiality, integrity, or availability.
In other words, if untrusted data passing through undici to the application can
trigger actions other than those documented for the APIs, there is likely a
security vulnerability. Examples include polluting globals, causing an
unrecoverable crash, or other unexpected side effects that can lead to a loss
of confidentiality, integrity, or availability.

### Examples of vulnerabilities

#### Improper Certificate Validation (CWE-295)

* Undici provides TLS connections to HTTPS endpoints. If certificates can be
crafted that result in incorrect validation by undici, that is considered
a vulnerability.
crafted that result in incorrect validation by undici, that is considered a
vulnerability.

#### Inconsistent Interpretation of HTTP Responses (CWE-444)

Expand All @@ -127,12 +164,19 @@ lead to a loss of confidentiality, integrity, or availability.

#### CRLF Injection in Request Headers (CWE-93)

* If untrusted input passed to undici APIs (such as header values or URLs)
can inject additional headers or corrupt the HTTP request stream, that is
* If untrusted input passed to undici APIs, such as header values or URLs, can
inject additional headers or corrupt the HTTP request stream, that is
considered a vulnerability.

### Examples of non-vulnerabilities

#### Defense-in-depth issues

* Bugs whose fixes only improve resilience after another security boundary has
already failed, or reduce the impact of behavior outside this threat model,
are defense-in-depth issues. They are fixed as regular bugs and do not
receive CVEs.

#### Malicious Third-Party Modules (CWE-1357)

* Application code and its dependencies are trusted by undici. Any scenario
Expand All @@ -141,17 +185,17 @@ lead to a loss of confidentiality, integrity, or availability.

#### Prototype Pollution Attacks (CWE-1321)

* Undici trusts the inputs provided to it by application code. It is up to the
application to sanitize appropriately. Any scenario that requires control
over user input passed directly by the application is not considered a
vulnerability in undici.
* Undici trusts inputs provided by application code. The application must
sanitize them appropriately. A scenario that requires control over user input
passed directly by the application is not a vulnerability in undici.

#### Uncontrolled Resource Consumption on Outbound Connections (CWE-400)

* If undici is asked to connect to a remote site and the response payload is
large enough to impact performance or cause the runtime to run out of
resources, that is not considered a vulnerability. Applications are
responsible for setting appropriate limits on response sizes.
* If undici is asked to connect to a remote site and return an artifact, it is
not a vulnerability if the size of that artifact is large enough to impact
performance or cause the runtime to run out of resources. Applications are
responsible for choosing suitable response-processing APIs and enforcing
limits appropriate for their workloads.

#### Calling body-consuming methods on untrusted responses

Expand Down Expand Up @@ -188,9 +232,9 @@ lead to a loss of confidentiality, integrity, or availability.

#### Application Misconfiguration

* Issues arising from incorrect or insecure use of undici APIs (such as
* Issues arising from incorrect or insecure use of undici APIs, such as
disabling TLS verification, ignoring errors, or passing unsanitized user
input to request options) are the application's responsibility, not
input to request options, are the application's responsibility and not
vulnerabilities in undici.

#### Unauthorized or untrusted proxy use
Expand Down
11 changes: 11 additions & 0 deletions deps/undici/src/docs/docs/api/CacheStore.md
Original file line number Diff line number Diff line change
Expand Up @@ -203,6 +203,16 @@ added: v7.0.0
integers; a `TypeError` is thrown otherwise, or if `maxEntrySize` is greater
than 2 GB.

The database is not encrypted, and nothing in it is hashed. The request URL
(including the query string), the response headers and body, and the values of
any request headers named in the response's `Vary` header (for example
`Authorization` or `Cookie`) are written as plain text to `location`. Protect
that file like any other sensitive data, or use `':memory:'`. A response to a
request that carries `Authorization` is only stored when the response allows it
with `public`, `s-maxage`, or `must-revalidate` (see [RFC 9111, Section 3.5][]);
servers can send `Cache-Control: no-store` to keep a response out of the cache
entirely.

### `sqliteCacheStore.close()`

<!-- YAML
Expand Down Expand Up @@ -372,4 +382,5 @@ The value returned by `get`. It contains every field of
body. (optional)

[RFC&nbsp;9111]: https://www.rfc-editor.org/rfc/rfc9111.html
[RFC 9111, Section 3.5]: https://www.rfc-editor.org/rfc/rfc9111.html#section-3.5
[`node:sqlite`]: https://nodejs.org/api/sqlite.html
6 changes: 4 additions & 2 deletions deps/undici/src/docs/docs/api/Client.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,9 @@ added: v1.0.0
positive integer. **Default:** `524288`.
* `pingInterval` {number} The time interval, in milliseconds, between HTTP/2
PING frames. Set to `0` to disable PING frames. Applies only to HTTP/2
connections and emits a `ping` event on the client. **Default:** `60e3`.
connections and emits a `ping` event on the client. A connection whose
PING is still unacknowledged when the next one is due is closed, and new
requests go to a new connection. **Default:** `60e3`.
* `settings` {object} `SETTINGS` frame options. For full reference, take a
look to [HTTP/2#Settings Object](https://nodejs.org/api/http2.html#settings-object)
* `webSocket` {Object} (optional) WebSocket-specific configuration.
Expand Down Expand Up @@ -217,7 +219,7 @@ import { Client, buildConnector } from 'undici'
const connector = buildConnector({ rejectUnauthorized: false })
const client = new Client('https://localhost:3000', {
connect (opts, cb) {
connector(opts, (err, socket) => {
return connector(opts, (err, socket) => {
if (err) {
cb(err)
} else {
Expand Down
11 changes: 9 additions & 2 deletions deps/undici/src/docs/docs/api/Connector.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ const connector = buildConnector({ rejectUnauthorized: false })

const client = new Client('https://localhost:3000', {
connect (opts, cb) {
connector(opts, (err, socket) => {
return connector(opts, (err, socket) => {
if (err) {
cb(err)
} else if (/* assertion */ false) {
Expand Down Expand Up @@ -124,6 +124,13 @@ targets or a [`tls.TLSSocket`][] for `https:` targets, applies TCP keep-alive an
the connect timeout, and invokes `callback` once the socket connects or errors.
The socket is also returned synchronously.

undici uses the returned socket to cancel a connection attempt that no request
needs any more: once every request waiting for it is aborted, the socket is
destroyed and the next request opens a new connection instead of waiting for
it. A connector that wraps another one should return the socket it gets back,
as the examples on this page do. If it returns nothing, the attempt runs until
it connects or fails.

When connecting over TLS, established sessions are cached (subject to
`maxCachedSessions`) and reused for subsequent connections to the same
`servername` or `hostname`.
Expand All @@ -141,7 +148,7 @@ const connector = buildConnector({ rejectUnauthorized: false })

const client = new Client('https://localhost:3000', {
connect (opts, cb) {
connector(opts, (err, socket) => {
return connector(opts, (err, socket) => {
if (err) {
cb(err)
} else if (getIssuerCertificate(socket).fingerprint256 !== caFingerprint) {
Expand Down
20 changes: 20 additions & 0 deletions deps/undici/src/docs/docs/api/Dispatcher.md
Original file line number Diff line number Diff line change
Expand Up @@ -705,6 +705,26 @@ The order of the interceptors matters: the last interceptor in the chain is the
first to be called. Forking the chain of interceptors can lead to unexpected
results.

Because interceptors wrap each other, ordering is the end-user's responsibility.
Certain built-in interceptors are order-sensitive and will throw an
`InvalidArgumentError` if composed in an unsafe order. In particular, the
`cache` interceptor must be composed **after** the `redirect` interceptor. When
`cache` is composed before `redirect`, the cache handler is wrapped *above* the
redirect handler, so it never observes the redirect history and its
cross-origin / credential-bearing redirect guards are silently disabled.
This allows an attacker-controlled or cross-principal redirect response to be
stored under the trusted origin's cache key and replayed to unrelated callers
(see GHSA-75VM-9G8F-99J4, GHSA-MQG3-3V4R-CM32, GHSA-4W7W-5XRC-9H26 and
GHSA-7XG3-FPHP-28HG).

```js
// Correct: cache is composed after redirect.
new Agent().compose(interceptors.redirect({ maxRedirections: 5 }), interceptors.cache({}))

// Throws an InvalidArgumentError: cache composed before redirect.
new Agent().compose(interceptors.cache({}), interceptors.redirect({ maxRedirections: 5 }))
```

```text
compose([interceptor1, interceptor2, interceptor3])

Expand Down
16 changes: 13 additions & 3 deletions deps/undici/src/docs/docs/api/Interceptors.md
Original file line number Diff line number Diff line change
Expand Up @@ -204,9 +204,6 @@ and `x-compress`, is left untouched, matching `fetch()`. As required by
[RFC 9659](https://www.rfc-editor.org/rfc/rfc9659.html), a `zstd` frame that
requires a window size larger than 8 MB fails to decode.
> **Experimental:** This interceptor is experimental and subject to change.
> A one-time `ExperimentalWarning` is emitted on first use.
**Parameters**
* `opts` {Object} (optional)
Expand Down Expand Up @@ -359,12 +356,25 @@ backing store.
**Returns:** {Dispatcher.DispatcherComposeInterceptor}
> **Ordering:** the `cache` interceptor must be composed **after** the
> `redirect` interceptor. When `cache` is composed before `redirect`, the cache
> handler is wrapped above the redirect handler, so it never observes the
> redirect history and its cross-origin / credential-bearing redirect guards are
> silently disabled, which lets an attacker-controlled or cross-principal
> redirect response be stored under the trusted origin's cache key and replayed
> to unrelated callers (GHSA-75VM-9G8F-99J4, GHSA-MQG3-3V4R-CM32,
> GHSA-4W7W-5XRC-9H26, GHSA-7XG3-FPHP-28HG). `compose()` throws an
> `InvalidArgumentError` for this unsafe order. The `deduplicate` interceptor
> participates in the same redirect-history contract and may be placed before or
> after `redirect`, as long as `cache` follows `redirect`.
**Example**
```js
import { Agent, interceptors, cacheStores } from 'undici'

const agent = new Agent().compose(
interceptors.redirect({ maxRedirections: 5 }),
interceptors.cache({ store: new cacheStores.MemoryCacheStore() })
)
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ const success = await bankTransfer('1234567890', '100')

assert.deepEqual(success, { message: 'transaction processed' })

// if you dont want to check whether the body or the headers contain the same value
// if you don't want to check whether the body or the headers contain the same value
// just remove it from interceptor
mockPool.intercept({
path: '/bank-transfer',
Expand Down
Loading
Loading