async_hooks: add --allow-async-hooks flag

Add a new `--allow-async-hooks` flag that must be passed to enable
`async_hooks.createHook()`. This is a breaking change - createHook is
now disabled by default.

When createHook() is called without the flag, it throws
ERR_ASYNC_HOOKS_CREATE_HOOK_DISABLED with a message indicating that
the flag is required.

This change affects all code using async_hooks.createHook(), including
APM tools and debugging utilities. Users must now explicitly opt-in
to this functionality.

BREAKING CHANGE: async_hooks.createHook() now requires --allow-async-hooks

Author: mcollina

doc/api/cli.md

@@ -16,6 +16,7 @@ const {
 
 const {
   ERR_ASYNC_CALLBACK,
+  ERR_ASYNC_HOOKS_CREATE_HOOK_DISABLED,
   ERR_ASYNC_TYPE,
   ERR_INVALID_ASYNC_ID,
 } = require('internal/errors').codes;
@@ -26,6 +27,7 @@ const {
   validateFunction,
   validateString,
 } = require('internal/validators');
+const { getOptionValue } = require('internal/options');
 const internal_async_hooks = require('internal/async_hooks');
 
 const AsyncContextFrame = require('internal/async_context_frame');
@@ -154,6 +156,9 @@ class AsyncHook {
 
 
 function createHook(fns) {
+  if (!getOptionValue('--allow-async-hooks')) {
+    throw new ERR_ASYNC_HOOKS_CREATE_HOOK_DISABLED();
+  }
   return new AsyncHook(fns);
 }
 

lib/async_hooks.js

@@ -1137,6 +1137,8 @@ E('ERR_AMBIGUOUS_ARGUMENT', 'The "%s" argument is ambiguous. %s', TypeError);
 E('ERR_ARG_NOT_ITERABLE', '%s must be iterable', TypeError);
 E('ERR_ASSERTION', '%s', Error);
 E('ERR_ASYNC_CALLBACK', '%s must be a function', TypeError);
+E('ERR_ASYNC_HOOKS_CREATE_HOOK_DISABLED',
+  'async_hooks.createHook() is disabled. Use --allow-async-hooks to enable it.', Error);
 E('ERR_ASYNC_LOADER_REQUEST_NEVER_SETTLED',
   'Async loader request never settled', Error);
 E('ERR_ASYNC_TYPE', 'Invalid name for async "type": %s', TypeError);

lib/internal/errors.js

@@ -653,6 +653,10 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             kAllowedInEnvvar,
             false,
             OptionNamespaces::kPermissionNamespace);
+  AddOption("--allow-async-hooks",
+            "allow use of async_hooks.createHook",
+            &EnvironmentOptions::allow_async_hooks,
+            kAllowedInEnvvar);
   AddOption("--experimental-repl-await",
             "experimental await keyword support in REPL",
             &EnvironmentOptions::experimental_repl_await,

src/node_options.cc

@@ -146,6 +146,7 @@ class EnvironmentOptions : public Options {
   bool allow_net = false;
   bool allow_wasi = false;
   bool allow_worker_threads = false;
+  bool allow_async_hooks = false;
   bool experimental_repl_await = true;
   bool experimental_vm_modules = false;
   bool async_context_frame = true;

src/node_options.h

@@ -1,4 +1,5 @@
 'use strict';
+// Flags: --allow-async-hooks
 
 const common = require('../../common');
 const assert = require('assert');

test/addons/async-resource/test.js

@@ -1,4 +1,5 @@
 'use strict';
+// Flags: --allow-async-hooks
 
 const common = require('../../common');
 const assert = require('assert');

test/addons/callback-scope/test-async-hooks.js

@@ -1,5 +1,5 @@
 'use strict';
-// Flags: --expose-gc
+// Flags: --allow-async-hooks --expose-gc
 
 require('../common');
 const assert = require('assert');

test/async-hooks/init-hooks.js

@@ -1,4 +1,5 @@
 'use strict';
+// Flags: --allow-async-hooks
 const common = require('../common');
 
 // This test ensures async hooks are being properly called

test/async-hooks/test-async-await.js

@@ -1,4 +1,5 @@
 'use strict';
+// Flags: --allow-async-hooks
 const common = require('../common');
 const assert = require('assert');
 const {