permission: handle case-sensitive file systems

doc/api/cli.md

@@ -588,6 +588,14 @@ added: v16.6.0
 
 Use this flag to disable top-level await in REPL.
 
+### `--no-permission-case-sensitive`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Use this flag to force disable case-sensitive in the [Permission Model][].
+
 ### `--experimental-shadow-realm`
 
 <!-- YAML
@@ -1082,6 +1090,29 @@ unless either the `--pending-deprecation` command-line flag, or the
 are used to provide a kind of selective "early warning" mechanism that
 developers may leverage to detect deprecated API usage.
 
+### `--permission-case-sensitive`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Determines whether the [Permission Model][] considers file and directory
+permissions as case-sensitive.
+
+If the flag is enabled, the file system will differentiate between uppercase and
+lowercase letters in file and directory permissions, so `/home/user/file.md` and
+`/home/USER/fiLE.MD` would be treated as distinct files.
+
+If the flag is disabled, file and directory permissions would be considered
+case-insensitive, so `/home/user/file.md` and `/home/USER/fiLE.MD` would be
+considered the same file.
+
+The default value for this flag varies depending on the operating system.
+Currently, Linux is the only operating system that has this flag enabled by
+default. Further information can be found in [Case-insensitive file systems][].
+
 ### `--policy-integrity=sri`
 
 <!-- YAML
@@ -2121,6 +2152,7 @@ Node.js options that are allowed are:
 * `--no-extra-info-on-fatal-exception`
 * `--no-force-async-hooks-checks`
 * `--no-global-search-paths`
+* `--no-permission-case-sensitive`
 * `--no-warnings`
 * `--node-memory-debug`
 * `--openssl-config`
@@ -2523,6 +2555,7 @@ done
 ```
 
 [#42511]: https://github.com/nodejs/node/issues/42511
+[Case-insensitive file systems]: permissions.md#case-insensitive-file-systems
 [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
 [CommonJS]: modules.md
 [CommonJS module]: modules.md

doc/api/permissions.md

@@ -565,6 +565,9 @@ There are constraints you need to know before using this system:
 * The model does not inherit to a worker thread.
 * When creating symlinks the target (first argument) should have read and
   write access.
+* Environment with a custom case-sensitive file system,
+  ensure to use the `--permission-case-sensitive` flag properly.
+  See [Case-insensitive file systems][] for further information.
 * Permission changes are not retroactively applied to existing resources.
   Consider the following snippet:
   ```js
@@ -586,12 +589,30 @@ const fd = fs.openSync('./README.md', 'r');
 // Error: Access to this API has been restricted
 ```
 
+#### Case-insensitive file systems
+
+Case-insensitive file systems are commonly used in Windows and macOS
+environments, but they can also be used in Linux and other Unix-like operating
+systems with certain configuration options or software tools.
+
+The Permission Model determines whether file and directory are case-sensitive
+from the operating system. This behavior is manageable by the flag
+[`--permission-case-sensitive`][]. However, in some cases, an operating system
+may have a custom file system configuration where some paths are case-sensitive
+and others are case-insensitive. To ensure consistency, it is recommended to
+enforce case-insensitivity using the `--no-permission-case-sensitive` flag.
+The Permission Model does not allow for multi-path configuration,
+so this flag should be used to apply the same case-sensitivity setting to all
+paths.
+
+[Case-insensitive file systems]: #case-insensitive-file-systems
 [Security Policy]: https://github.com/nodejs/node/blob/main/SECURITY.md
 [`--allow-child-process`]: cli.md#--allow-child-process
 [`--allow-fs-read`]: cli.md#--allow-fs-read
 [`--allow-fs-write`]: cli.md#--allow-fs-write
 [`--allow-worker`]: cli.md#--allow-worker
 [`--experimental-permission`]: cli.md#--experimental-permission
+[`--permission-case-sensitive`]: cli.md#--permission-case-sensitive
 [`permission.deny()`]: process.md#processpermissiondenyscope-reference
 [`permission.has()`]: process.md#processpermissionhasscope-reference
 [import maps]: https://url.spec.whatwg.org/#relative-url-with-fragment-string

src/env.cc

@@ -783,6 +783,8 @@ Environment::Environment(IsolateData* isolate_data,
     // spawn/worker nor use addons unless explicitly allowed by the user
     if (!options_->allow_fs_read.empty() || !options_->allow_fs_write.empty()) {
       options_->allow_native_addons = false;
+      permission()->SetFSPermissionCaseSensitive(
+          options_->permission_case_sensitive);
       if (!options_->allow_child_process) {
         permission()->Deny(permission::PermissionScope::kChildProcess, {});
       }

src/node_options.cc

@@ -420,6 +420,10 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             &EnvironmentOptions::experimental_policy_integrity,
             kAllowedInEnvvar);
   Implies("--policy-integrity", "[has_policy_integrity_string]");
+  AddOption("--permission-case-sensitive",
+            "enforces case-sensitive permission checks in the Permission Model",
+            &EnvironmentOptions::permission_case_sensitive,
+            kAllowedInEnvvar);
   AddOption("--allow-fs-read",
             "allow permissions to read the filesystem",
             &EnvironmentOptions::allow_fs_read,

src/node_options.h

@@ -15,6 +15,13 @@
 #include "openssl/opensslv.h"
 #endif
 
+#if defined(__linux__)
+// Linux filesystems are case-sensitive by default
+#define FILESYSTEM_IS_CASE_SENSITIVE true
+#else
+#define FILESYSTEM_IS_CASE_SENSITIVE false
+#endif
+
 namespace node {
 
 class HostPort {
@@ -121,6 +128,7 @@ class EnvironmentOptions : public Options {
   std::string experimental_policy_integrity;
   bool has_policy_integrity_string = false;
   bool experimental_permission = false;
+  bool permission_case_sensitive = FILESYSTEM_IS_CASE_SENSITIVE;
   std::string allow_fs_read;
   std::string allow_fs_write;
   bool allow_child_process = false;

src/permission/fs_permission.cc

@@ -7,6 +7,7 @@
 #include <limits.h>
 #include <stdlib.h>
 #include <algorithm>
+#include <cctype>
 #include <filesystem>
 #include <string>
 #include <vector>
@@ -154,6 +155,20 @@ bool FSPermission::is_granted(PermissionScope perm,
   }
 }
 
+std::string FSPermission::RadixTree::NormalizePathIfCaseInsensitive(
+    const std::string& path) {
+  if (!case_sensitive_) {
+    std::string transformed_path = path;
+    std::transform(
+        transformed_path.begin(),
+        transformed_path.end(),
+        transformed_path.begin(),
+        [](unsigned char c) -> unsigned char { return std::tolower(c); });
+    return transformed_path;
+  }
+  return path;
+}
+
 FSPermission::RadixTree::RadixTree() : root_node_(new Node("")) {}
 
 FSPermission::RadixTree::~RadixTree() {
@@ -168,7 +183,15 @@ bool FSPermission::RadixTree::Lookup(const std::string_view& s,
   }
 
   unsigned int parent_node_prefix_len = current_node->prefix.length();
-  const std::string path(s);
+  std::string path(s);
+  if (!case_sensitive_) {
+    std::transform(
+        path.begin(),
+        path.end(),
+        path.begin(),
+        [](unsigned char c) -> unsigned char { return std::tolower(c); });
+  }
+
   auto path_len = path.length();
 
   while (true) {
@@ -190,10 +213,11 @@ bool FSPermission::RadixTree::Lookup(const std::string_view& s,
   }
 }
 
-void FSPermission::RadixTree::Insert(const std::string& path) {
+void FSPermission::RadixTree::Insert(const std::string& res) {
   FSPermission::RadixTree::Node* current_node = root_node_;
 
   unsigned int parent_node_prefix_len = current_node->prefix.length();
+  const std::string path = NormalizePathIfCaseInsensitive(res);
   int path_len = path.length();
 
   for (int i = 1; i <= path_len; ++i) {

src/permission/fs_permission.h

@@ -21,6 +21,19 @@ class FSPermission final : public PermissionBase {
             const std::vector<std::string>& params) override;
   bool is_granted(PermissionScope perm, const std::string_view& param) override;
 
+  // For now, case_sensitive is a constant. Once set, its value won't change.
+  // FSPermission is constructed *before* cli evaluation.
+  // That's why we lazy-initialize it here.
+  void CaseSensitive(const bool sensitive) {
+    if (case_sensitive_initialized_) return;
+
+    case_sensitive_initialized_ = true;
+    granted_in_fs_.case_sensitive_ = sensitive;
+    granted_out_fs_.case_sensitive_ = sensitive;
+    deny_in_fs_.case_sensitive_ = sensitive;
+    deny_out_fs_.case_sensitive_ = sensitive;
+  }
+
   // For debugging purposes, use the gist function to print the whole tree
   // https://gist.github.com/RafaelGSS/5b4f09c559a54f53f9b7c8c030744d19
   struct RadixTree {
@@ -126,6 +139,9 @@ class FSPermission final : public PermissionBase {
     void Insert(const std::string& s);
     bool Lookup(const std::string_view& s) { return Lookup(s, false); }
     bool Lookup(const std::string_view& s, bool when_empty_return);
+    std::string NormalizePathIfCaseInsensitive(const std::string& path);
+
+    bool case_sensitive_;
 
    private:
     Node* root_node_;
@@ -135,6 +151,8 @@ class FSPermission final : public PermissionBase {
   void GrantAccess(PermissionScope scope, std::string param);
   void RestrictAccess(PermissionScope scope,
                       const std::vector<std::string>& params);
+
+  bool case_sensitive_initialized_ = false;
   // /tmp/* --grant
   // /tmp/dsadsa/t.js denied in runtime
   //

src/permission/permission.cc

@@ -162,6 +162,16 @@ void Permission::EnablePermissions() {
   }
 }
 
+void Permission::SetFSPermissionCaseSensitive(const bool sensitive) {
+  auto it = nodes_.find(PermissionScope::kFileSystem);
+  if (it != nodes_.end()) {
+    auto fs_permission = std::static_pointer_cast<FSPermission>(it->second);
+    if (fs_permission) {
+      fs_permission->CaseSensitive(sensitive);
+    }
+  }
+}
+
 void Permission::Apply(const std::string& allow, PermissionScope scope) {
   auto permission = nodes_.find(scope);
   if (permission != nodes_.end()) {

src/permission/permission.h

@@ -50,6 +50,7 @@ class Permission {
   // Permission.Deny API
   bool Deny(PermissionScope scope, const std::vector<std::string>& params);
   void EnablePermissions();
+  void SetFSPermissionCaseSensitive(const bool sensitive);
 
  private:
   COLD_NOINLINE bool is_scope_granted(const PermissionScope permission,

test/parallel/test-permission-fs-case-insensitive.js

@@ -0,0 +1,51 @@
+// Flags: --experimental-permission --allow-fs-read=* --no-permission-case-sensitive
+'use strict';
+
+const common = require('../common');
+common.skipIfWorker();
+
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+const fixtures = require('../common/fixtures');
+
+const protectedFile = fixtures.path('permission', 'deny', 'protected-file.md');
+const protectedFileCapsLetters = fixtures.path('permission', 'deny', 'PrOtEcTeD-File.MD');
+
+{
+  assert.ok(process.permission.deny('fs.read', [protectedFile]));
+}
+
+{
+  // Guarantee the initial protection
+  assert.throws(() => {
+    fs.readFile(protectedFile, () => {});
+  }, common.expectsError({
+    code: 'ERR_ACCESS_DENIED',
+    permission: 'FileSystemRead',
+    resource: path.toNamespacedPath(protectedFile),
+  }));
+}
+
+{
+  // uppercase/capitalize files
+  assert.throws(() => {
+    fs.readFile(protectedFile.toUpperCase(), (err) => {
+      assert.ifError(err);
+    });
+  }, common.expectsError({
+    code: 'ERR_ACCESS_DENIED',
+    permission: 'FileSystemRead',
+    resource: path.toNamespacedPath(protectedFile.toUpperCase()),
+  }));
+
+  assert.throws(() => {
+    fs.readFile(protectedFileCapsLetters, (err) => {
+      assert.ifError(err);
+    });
+  }, common.expectsError({
+    code: 'ERR_ACCESS_DENIED',
+    permission: 'FileSystemRead',
+    resource: path.toNamespacedPath(protectedFileCapsLetters),
+  }));
+}

test/parallel/test-permission-fs-case-sensitive-default.js

@@ -0,0 +1,61 @@
+// Flags: --experimental-permission --allow-fs-read=*
+'use strict';
+
+const common = require('../common');
+common.skipIfWorker();
+
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+const fixtures = require('../common/fixtures');
+
+const protectedFile = fixtures.path('permission', 'deny', 'protected-file.md');
+const protectedFileCapsLetters = fixtures.path('permission', 'deny', 'PrOtEcTeD-File.MD');
+
+{
+  assert.ok(process.permission.deny('fs.read', [protectedFile]));
+}
+
+{
+  // Guarantee the initial protection
+  assert.throws(() => {
+    fs.readFile(protectedFile, () => {});
+  }, common.expectsError({
+    code: 'ERR_ACCESS_DENIED',
+    permission: 'FileSystemRead',
+    resource: path.toNamespacedPath(protectedFile),
+  }));
+}
+
+// case-sensitive = true
+if (common.isLinux) {
+  // doesNotThrow
+  fs.readFile(protectedFile.toUpperCase(), (err) => {
+    assert.ifError(err);
+  });
+
+  // doesNotThrow
+  fs.readFile(protectedFileCapsLetters, (err) => {
+    assert.ifError(err);
+  });
+} else {
+  assert.throws(() => {
+    fs.readFile(protectedFile.toUpperCase(), (err) => {
+      assert.ifError(err);
+    });
+  }, common.expectsError({
+    code: 'ERR_ACCESS_DENIED',
+    permission: 'FileSystemRead',
+    resource: path.toNamespacedPath(protectedFile.toUpperCase()),
+  }));
+
+  assert.throws(() => {
+    fs.readFile(protectedFileCapsLetters, (err) => {
+      assert.ifError(err);
+    });
+  }, common.expectsError({
+    code: 'ERR_ACCESS_DENIED',
+    permission: 'FileSystemRead',
+    resource: path.toNamespacedPath(protectedFileCapsLetters),
+  }));
+}