Skip to content

Commit f35f140

Browse files
committed
docs: clarify formData security considerations
Signed-off-by: Matteo Collina <hello@matteocollina.com>
1 parent f33ecbc commit f35f140

4 files changed

Lines changed: 22 additions & 3 deletions

File tree

README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -340,6 +340,9 @@ The `body` mixins are the most common way to format the request/response body. M
340340
> [!NOTE]
341341
> The body returned from `undici.request` does not implement `.formData()`.
342342
343+
> [!WARNING]
344+
> Calling `body.formData()` on a fetch response causes undici to buffer and parse the entire body. Because multipart parsing has inherent security risks, `body.formData()` must only be called on responses from trusted servers.
345+
343346
Example usage:
344347

345348
```js

SECURITY.md

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ meet the following criteria:
8181
**Undici trusts**:
8282

8383
* The application code that uses its APIs, including all configuration,
84-
options, and callbacks provided by the application.
84+
options, callbacks, and decisions about which body-consuming APIs to call.
8585
* The operating system and its network stack.
8686
* The Node.js runtime undici is running on.
8787
* Dependencies installed by the application.
@@ -142,6 +142,17 @@ lead to a loss of confidentiality, integrity, or availability.
142142
resources, that is not considered a vulnerability. Applications are
143143
responsible for setting appropriate limits on response sizes.
144144

145+
#### Calling `body.formData()` on untrusted responses
146+
147+
* `body.formData()` buffers and parses the entire response body. Multipart
148+
parsing has inherent security risks, especially when the body is supplied by
149+
an untrusted or user-controlled server. Applications must only call
150+
`body.formData()` on responses from trusted servers. For untrusted responses,
151+
applications should use a dedicated streaming multipart parser and enforce
152+
application-specific limits. Resource exhaustion or parser exposure caused by
153+
calling `body.formData()` on untrusted responses is considered an application
154+
responsibility, not a vulnerability in undici.
155+
145156
#### Application Misconfiguration
146157

147158
* Issues arising from incorrect or insecure use of undici APIs (such as

docs/docs/api/Fetch.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,9 @@ This API is implemented as per the standard, you can find documentation on [MDN]
4141
- [`.json()`](https://fetch.spec.whatwg.org/#dom-body-json)
4242
- [`.text()`](https://fetch.spec.whatwg.org/#dom-body-text)
4343

44-
There is an ongoing discussion regarding `.formData()` and its usefulness and performance in server environments. It is recommended to use a dedicated library for parsing `multipart/form-data` bodies, such as [Busboy](https://www.npmjs.com/package/busboy) or [@fastify/busboy](https://www.npmjs.com/package/@fastify/busboy).
44+
There is an ongoing discussion regarding `body.formData()` and its usefulness, performance, and security in server environments. Calling `body.formData()` causes undici to buffer and parse the entire body. Because multipart parsing has inherent security risks, `body.formData()` must only be called on responses from trusted servers.
45+
46+
For responses from untrusted or user-controlled servers, use a dedicated streaming library for parsing `multipart/form-data` bodies, such as [Busboy](https://www.npmjs.com/package/busboy) or [@fastify/busboy](https://www.npmjs.com/package/@fastify/busboy), and apply application-specific limits.
4547

4648
These libraries can be interfaced with fetch with the following example code:
4749

types/fetch.d.ts

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,10 @@ export class BodyMixin {
3636
readonly bytes: () => Promise<Uint8Array>
3737
/**
3838
* @deprecated This method is not recommended for parsing multipart/form-data bodies in server environments.
39-
* It is recommended to use a library such as [@fastify/busboy](https://www.npmjs.com/package/@fastify/busboy) as follows:
39+
* Calling body.formData() buffers and parses the entire body. Because multipart parsing has inherent security risks,
40+
* this method must only be called on responses from trusted servers.
41+
* For responses from untrusted or user-controlled servers, use a dedicated streaming parser such as
42+
* [@fastify/busboy](https://www.npmjs.com/package/@fastify/busboy) and apply application-specific limits as follows:
4043
*
4144
* @example
4245
* ```js

0 commit comments

Comments
 (0)