doc: clarify fileURLToPath security considerations

RafaelGSS · RafaelGSS · commit 9a9bed9b3a1a · 2026-01-13T10:04:36.000-03:00
Add clarification that fileURLToPath() decodes encoded dot-segments (%2e%2e) which are normalized as path traversal. Applications must perform their own path validation to prevent directory traversal attacks. Also applies to fileURLToPathBuffer(). PR-URL: #60887 Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
diff --git a/doc/api/url.md b/doc/api/url.md
@@ -1329,6 +1329,19 @@ changes:
 This function ensures the correct decodings of percent-encoded characters as
 well as ensuring a cross-platform valid absolute path string.
 
+**Security Considerations:**
+
+This function decodes percent-encoded characters, including encoded dot-segments
+(`%2e` as `.` and `%2e%2e` as `..`), and then normalizes the resulting path.
+This means that encoded directory traversal sequences (such as `%2e%2e`) are
+decoded and processed as actual path traversal, even though encoded slashes
+(`%2F`, `%5C`) are correctly rejected.
+
+**Applications must not rely on `fileURLToPath()` alone to prevent directory
+traversal attacks.** Always perform explicit path validation and security checks
+on the returned path value to ensure it remains within expected boundaries
+before using it for file system operations.
+
 ```mjs
 import { fileURLToPath } from 'node:url';
 
@@ -1384,6 +1397,15 @@ representation of the path, a `Buffer` is returned. This conversion is
 helpful when the input URL contains percent-encoded segments that are
 not valid UTF-8 / Unicode sequences.
 
+**Security Considerations:**
+
+This function has the same security considerations as [`url.fileURLToPath()`][].
+It decodes percent-encoded characters, including encoded dot-segments
+(`%2e` as `.` and `%2e%2e` as `..`), and normalizes the path. **Applications
+must not rely on this function alone to prevent directory traversal attacks.**
+Always perform explicit path validation on the returned buffer value before
+using it for file system operations.
+
 ### `url.format(URL[, options])`
 
 <!-- YAML
@@ -2014,6 +2036,7 @@ console.log(myURL.origin);
 [`querystring`]: querystring.md
 [`url.domainToASCII()`]: #urldomaintoasciidomain
 [`url.domainToUnicode()`]: #urldomaintounicodedomain
+[`url.fileURLToPath()`]: #urlfileurltopathurl-options
 [`url.format()`]: #urlformaturlobject
 [`url.href`]: #urlhref
 [`url.parse()`]: #urlparseurlstring-parsequerystring-slashesdenotehost
