src,permission: add --permission-audit

Add --permission-audit flag that enables the permission model in
warning-only mode. Instead of throwing ERR_ACCESS_DENIED, it emits
a message via diagnostics channel and allows the operation to
continue.

Publish permission check results to per-scope diagnostics channels
(e.g., node:permission-model:fs) so users can observe permission
decisions at runtime via diagnostics_channel.

Refs: #59935

Author: RafaelGSS

doc/api/cli.md

@@ -2174,6 +2174,16 @@ following permissions are restricted:
 * WASI - manageable through [`--allow-wasi`][] flag
 * Addons - manageable through [`--allow-addons`][] flag
 
+### `--permission-audit`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Enable audit only for the permission model. When enabled, permission checks
+are performed but access is not denied. Instead, a warning is emitted for
+each permission violation via diagnostics channel.
+
 ### `--preserve-symlinks`
 
 <!-- YAML
@@ -3660,6 +3670,7 @@ one is included in the list below.
 * `--openssl-legacy-provider`
 * `--openssl-shared-config`
 * `--pending-deprecation`
+* `--permission-audit`
 * `--permission`
 * `--preserve-symlinks-main`
 * `--preserve-symlinks`

doc/node.1

@@ -1115,6 +1115,11 @@ WASI - manageable through \fB--allow-wasi\fR flag
 Addons - manageable through \fB--allow-addons\fR flag
 .El
 .
+.It Fl -permission-audit
+Enable audit only for the permission model. When enabled, permission checks
+are performed but access is not denied. Instead, a warning is emitted for
+each permission violation via diagnostics channel.
+.
 .It Fl -preserve-symlinks
 Instructs the module loader to preserve symbolic links when resolving and
 caching modules.
@@ -1978,6 +1983,8 @@ one is included in the list below.
 .It
 \fB--permission\fR
 .It
+\fB--permission-audit\fR
+.It
 \fB--preserve-symlinks-main\fR
 .It
 \fB--preserve-symlinks\fR

lib/internal/process/pre_execution.js

@@ -630,7 +630,7 @@ function setupDiagnosticsChannel() {
 }
 
 function initializePermission() {
-  const permission = getOptionValue('--permission');
+  const permission = getOptionValue('--permission') || getOptionValue('--permission-audit');
   if (permission) {
     process.binding = function binding(_module) {
       throw new ERR_ACCESS_DENIED('process.binding');

src/env.cc

@@ -918,8 +918,11 @@ Environment::Environment(IsolateData* isolate_data,
                                       tracing::CastTracedValue(traced_value));
   }
 
-  if (options_->permission) {
+  if (options_->permission || options_->permission_audit) {
     permission()->EnablePermissions();
+    if (options_->permission_audit) {
+      permission()->EnableWarningOnly();
+    }
     // The process shouldn't be able to neither
     // spawn/worker nor use addons or enable inspector
     // unless explicitly allowed by the user

src/node_options.cc

@@ -635,6 +635,11 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             kAllowedInEnvvar,
             false,
             OptionNamespaces::kPermissionNamespace);
+  AddOption("--permission-audit",
+            "enable audit only for the permission system",
+            &EnvironmentOptions::permission_audit,
+            kAllowedInEnvvar,
+            false);
   AddOption("--allow-fs-read",
             "allow permissions to read the filesystem",
             &EnvironmentOptions::allow_fs_read,

src/node_options.h

@@ -138,6 +138,7 @@ class EnvironmentOptions : public Options {
   std::string input_type;  // Value of --input-type
   bool entry_is_url = false;
   bool permission = false;
+  bool permission_audit = false;
   std::vector<std::string> allow_fs_read;
   std::vector<std::string> allow_fs_write;
   bool allow_addons = false;

src/permission/permission.cc

@@ -3,6 +3,7 @@
 #include "env-inl.h"
 #include "memory_tracker-inl.h"
 #include "node.h"
+#include "node_diagnostics_channel.h"
 #include "node_errors.h"
 #include "node_external_reference.h"
 #include "node_file.h"
@@ -27,6 +28,29 @@ namespace permission {
 
 namespace {
 
+constexpr std::string_view GetDiagnosticsChannelName(PermissionScope scope) {
+  switch (scope) {
+    case PermissionScope::kFileSystem:
+    case PermissionScope::kFileSystemRead:
+    case PermissionScope::kFileSystemWrite:
+      return "node:permission-model:fs";
+    case PermissionScope::kChildProcess:
+      return "node:permission-model:child";
+    case PermissionScope::kWorkerThreads:
+      return "node:permission-model:worker";
+    case PermissionScope::kNet:
+      return "node:permission-model:net";
+    case PermissionScope::kInspector:
+      return "node:permission-model:inspector";
+    case PermissionScope::kWASI:
+      return "node:permission-model:wasi";
+    case PermissionScope::kAddon:
+      return "node:permission-model:addon";
+    default:
+      return {};
+  }
+}
+
 // permission.has('fs.in', '/tmp/')
 // permission.has('fs.in')
 static void Has(const FunctionCallbackInfo<Value>& args) {
@@ -70,7 +94,7 @@ PermissionScope Permission::StringToPermission(const std::string& perm) {
 }
 #undef V
 
-Permission::Permission() : enabled_(false) {
+Permission::Permission() : enabled_(false), warning_only_(false) {
   std::shared_ptr<PermissionBase> fs = std::make_shared<FSPermission>();
   std::shared_ptr<PermissionBase> child_p =
       std::make_shared<ChildProcessPermission>();
@@ -175,6 +199,73 @@ void Permission::EnablePermissions() {
   }
 }
 
+void Permission::EnableWarningOnly() {
+  if (!warning_only_) {
+    warning_only_ = true;
+  }
+}
+
+bool Permission::is_scope_granted(Environment* env,
+                                  const PermissionScope permission,
+                                  const std::string_view& res) const {
+  auto perm_node = nodes_.find(permission);
+  bool result = false;
+  if (perm_node != nodes_.end()) {
+    result = perm_node->second->is_granted(env, permission, res);
+  }
+
+  if (!result && !publishing_) {
+    auto channel_name = GetDiagnosticsChannelName(permission);
+    if (!channel_name.empty()) {
+      auto ch = GetOrCreateChannel(env, permission);
+      if (ch && ch->HasSubscribers()) {
+        publishing_ = true;
+        v8::Isolate* isolate = env->isolate();
+        v8::HandleScope handle_scope(isolate);
+        v8::Local<v8::Context> context = env->context();
+        v8::Local<v8::Object> msg = v8::Object::New(isolate, v8::Null(isolate), nullptr, nullptr, 0);
+        const char* perm_str = PermissionToString(permission);
+        msg->Set(context,
+                 FIXED_ONE_BYTE_STRING(isolate, "permission"),
+                 v8::String::NewFromUtf8(isolate, perm_str).ToLocalChecked())
+            .Check();
+        msg->Set(context,
+                 FIXED_ONE_BYTE_STRING(isolate, "resource"),
+                 v8::String::NewFromUtf8(isolate,
+                                         res.data(),
+                                         v8::NewStringType::kNormal,
+                                         static_cast<int>(res.size()))
+                     .ToLocalChecked())
+            .Check();
+        ch->Publish(env, msg);
+        publishing_ = false;
+      }
+    }
+  }
+
+  return result;
+}
+
+BaseObjectPtr<diagnostics_channel::Channel>
+Permission::GetOrCreateChannel(
+    Environment* env, PermissionScope scope) const {
+  auto it = channels_.find(scope);
+  if (it != channels_.end()) {
+    // Promote weak ref to strong for the duration of this call.
+    BaseObjectPtr<diagnostics_channel::Channel> ptr(it->second.get());
+    if (ptr) return ptr;
+    channels_.erase(it);
+  }
+  auto channel_name = GetDiagnosticsChannelName(scope);
+  diagnostics_channel::Channel* ch =
+      diagnostics_channel::Channel::Get(env, channel_name.data());
+  if (ch != nullptr) {
+    channels_.emplace(scope, BaseObjectWeakPtr<diagnostics_channel::Channel>(ch));
+    return BaseObjectPtr<diagnostics_channel::Channel>(ch);
+  }
+  return {};
+}
+
 void Permission::Apply(Environment* env,
                        const std::vector<std::string>& allow,
                        PermissionScope scope) {

src/permission/permission.h

@@ -13,6 +13,7 @@
 #include "permission/permission_base.h"
 #include "permission/wasi_permission.h"
 #include "permission/worker_permission.h"
+#include "node_diagnostics_channel.h"
 #include "v8.h"
 
 #include <string_view>
@@ -37,7 +38,7 @@ namespace permission {
         [[unlikely]] {                                                         \
       node::permission::Permission::ThrowAccessDenied(                         \
           env__, perm__, resource__);                                          \
-      return __VA_ARGS__;                                                      \
+      if (!env__->permission()->warning_only()) return __VA_ARGS__;            \
     }                                                                          \
   } while (0)
 
@@ -51,7 +52,7 @@ namespace permission {
         [[unlikely]] {                                                         \
       node::permission::Permission::AsyncThrowAccessDenied(                    \
           env__, (wrap), perm__, resource__);                                  \
-      return __VA_ARGS__;                                                      \
+      if (!env__->permission()->warning_only()) return __VA_ARGS__;            \
     }                                                                          \
   } while (0)
 
@@ -100,6 +101,8 @@ class Permission {
 
   FORCE_INLINE bool enabled() const { return enabled_; }
 
+  FORCE_INLINE bool warning_only() const { return warning_only_; }
+
   static PermissionScope StringToPermission(const std::string& perm);
   static const char* PermissionToString(PermissionScope perm);
   static void ThrowAccessDenied(Environment* env,
@@ -115,20 +118,25 @@ class Permission {
              const std::vector<std::string>& allow,
              PermissionScope scope);
   void EnablePermissions();
+  void EnableWarningOnly();
 
  private:
   COLD_NOINLINE bool is_scope_granted(Environment* env,
                                       const PermissionScope permission,
-                                      const std::string_view& res = "") const {
-    auto perm_node = nodes_.find(permission);
-    if (perm_node != nodes_.end()) {
-      return perm_node->second->is_granted(env, permission, res);
-    }
-    return false;
-  }
+                                      const std::string_view& res = "") const;
+
+  BaseObjectPtr<diagnostics_channel::Channel> GetOrCreateChannel(
+      Environment* env, PermissionScope scope) const;
 
   std::unordered_map<PermissionScope, std::shared_ptr<PermissionBase>> nodes_;
   bool enabled_;
+  bool warning_only_;
+  mutable bool publishing_ = false;
+  // Weak refs: BindingData (via BaseObjectPtr) is the sole owner of Channels.
+  // Using weak refs here avoids keeping Channels alive past Realm teardown.
+  mutable std::unordered_map<PermissionScope,
+                             BaseObjectWeakPtr<diagnostics_channel::Channel>>
+      channels_;
 };
 
 v8::MaybeLocal<v8::Value> CreateAccessDeniedError(Environment* env,

test/parallel/test-bootstrap-modules.js

@@ -105,6 +105,7 @@ expected.beforePreExec = new Set([
   'Internal Binding module_wrap',
   'NativeModule internal/modules/cjs/loader',
   'NativeModule diagnostics_channel',
+  'Internal Binding diagnostics_channel',
   'Internal Binding wasm_web_api',
   'NativeModule internal/events/abort_listener',
   'NativeModule internal/modules/typescript',

test/parallel/test-permission-diagnostics-channel.js

@@ -0,0 +1,29 @@
+// Flags: --permission --allow-fs-read=*
+'use strict';
+
+const common = require('../common');
+const { isMainThread } = require('worker_threads');
+
+if (!isMainThread) {
+  common.skip('This test only works on a main thread');
+}
+
+const assert = require('node:assert');
+const dc = require('node:diagnostics_channel');
+const fs = require('node:fs');
+
+const messages = [];
+dc.subscribe('node:permission-model:fs', (msg) => {
+  messages.push(msg);
+});
+
+// Granted permission should not publish
+fs.readFileSync(__filename);
+assert.strictEqual(messages.length, 0, 'Granted checks should not publish');
+
+// Denied permission should publish
+const hasWrite = process.permission.has('fs.write', '/tmp/test');
+assert.strictEqual(hasWrite, false);
+
+assert.ok(messages.length > 0, 'Expected at least one denied message');
+assert.strictEqual(messages[0].permission, 'FileSystemWrite');