From 0857fde85e629935412a0d968b1636021d4e9c4a Mon Sep 17 00:00:00 2001
From: RafaelGSS <rafael.nunu@hotmail.com>
Date: Fri, 28 Nov 2025 18:55:05 -0300
Subject: [PATCH] doc: clarify fileURLToPath security considerations

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().
---
 doc/api/url.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/doc/api/url.md b/doc/api/url.md
index 7148a3a33e1975..29dd74479bd2ad 100644
--- 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