lib: unmask mode_t values with 0o777

This commit allows permission bits higher than 0o777 to go through
the API (e.g. `S_ISVTX`=`0o1000`, `S_ISGID`=`0o2000`,
`S_ISUID`=`0o4000`).

Also documents that these bits are not exposed through `fs.constants`
and their behaviors are platform-specific, so the users need to
use them on their own risk.

PR-URL: https://github.com/nodejs/node/pull/20975
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: James M Snell <jasnell@gmail.com>

1 files changed, 17 insertions, 6 deletions

diff --git a/lib/internal/validators.js b/lib/internal/validators.js
index 17b10dab18..b7b21d29bf 100644
--- a/lib/internal/validators.js
+++ b/lib/internal/validators.js
@@ -16,11 +16,22 @@ function isUint32(value) {
 
 const octalReg = /^[0-7]+$/;
 const modeDesc = 'must be a 32-bit unsigned integer or an octal string';
-// Validator for mode_t (the S_* constants). Valid numbers or octal strings
-// will be masked with 0o777 to be consistent with the behavior in POSIX APIs.
-function validateAndMaskMode(value, name, def) {
+
+/**
+ * Validate values that will be converted into mode_t (the S_* constants).
+ * Only valid numbers and octal strings are allowed. They could be converted
+ * to 32-bit unsigned integers or non-negative signed integers in the C++
+ * land, but any value higher than 0o777 will result in platform-specific
+ * behaviors.
+ *
+ * @param {*} value Values to be validated
+ * @param {string} name Name of the argument
+ * @param {number} def If specified, will be returned for invalid values
+ * @returns {number}
+ */
+function validateMode(value, name, def) {
   if (isUint32(value)) {
-    return value & 0o777;
+    return value;
   }
 
   if (typeof value === 'number') {
@@ -37,7 +48,7 @@ function validateAndMaskMode(value, name, def) {
       throw new ERR_INVALID_ARG_VALUE(name, value, modeDesc);
     }
     const parsed = parseInt(value, 8);
-    return parsed & 0o777;
+    return parsed;
   }
 
   // TODO(BridgeAR): Only return `def` in case `value == null`
@@ -106,7 +117,7 @@ function validateUint32(value, name, positive) {
 module.exports = {
   isInt32,
   isUint32,
-  validateAndMaskMode,
+  validateMode,
   validateInteger,
   validateInt32,
   validateUint32