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

Signed-off-by: Matteo Collina <hello@matteocollina.com>

Author: mcollina

doc/api/cli.md

@@ -139,6 +139,46 @@ Error: Cannot load native addon because loading addons is disabled.
 }
 ```
 
+### `--allow-async-hooks`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Allow use of `async_hooks.createHook()`. This flag is required to enable
+the `createHook` API, which is disabled by default.
+
+Example:
+
+```mjs
+import { createHook } from 'node:async_hooks';
+
+createHook({ init() {} }).enable();
+```
+
+```cjs
+const { createHook } = require('node:async_hooks');
+
+createHook({ init() {} }).enable();
+```
+
+```console
+$ node index.js
+node:async_hooks:160
+    throw new ERR_ASYNC_HOOKS_CREATE_HOOK_DISABLED();
+    ^
+
+Error [ERR_ASYNC_HOOKS_CREATE_HOOK_DISABLED]: async_hooks.createHook() is disabled. Use --allow-async-hooks to enable it.
+    at createHook (node:async_hooks:160:11)
+    at Object.<anonymous> (/home/user/index.js:3:1)
+    ...
+```
+
+```console
+$ node --allow-async-hooks index.js
+# Works without error
+```
+
 ### `--allow-child-process`
 
 <!-- YAML

doc/api/errors.md

@@ -733,6 +733,17 @@ by the `node:assert` module.
 An attempt was made to register something that is not a function as an
 `AsyncHooks` callback.
 
+<a id="ERR_ASYNC_HOOKS_CREATE_HOOK_DISABLED"></a>
+
+### `ERR_ASYNC_HOOKS_CREATE_HOOK_DISABLED`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+An attempt was made to call [`async_hooks.createHook()`][] without the
+[`--allow-async-hooks`][] flag.
+
 <a id="ERR_ASYNC_LOADER_REQUEST_NEVER_SETTLED"></a>
 
 ### `ERR_ASYNC_LOADER_REQUEST_NEVER_SETTLED`
@@ -4770,6 +4781,7 @@ An error occurred trying to allocate memory. This should never happen.
 [`"exports"`]: packages.md#exports
 [`"imports"`]: packages.md#imports
 [`'uncaughtException'`]: process.md#event-uncaughtexception
+[`--allow-async-hooks`]: cli.md#--allow-async-hooks
 [`--disable-proto=throw`]: cli.md#--disable-protomode
 [`--force-fips`]: cli.md#--force-fips
 [`--no-addons`]: cli.md#--no-addons
@@ -4795,6 +4807,7 @@ An error occurred trying to allocate memory. This should never happen.
 [`Writable`]: stream.md#class-streamwritable
 [`ZipBuffer`]: zlib.md#class-zlibzipbuffer
 [`ZipFile`]: zlib.md#class-zlibzipfile
+[`async_hooks.createHook()`]: async_hooks.md#async_hookscreatehookoptions
 [`child_process`]: child_process.md
 [`cipher.getAuthTag()`]: crypto.md#ciphergetauthtag
 [`crypto.getDiffieHellman()`]: crypto.md#cryptogetdiffiehellmangroupname

doc/node.1

@@ -86,6 +86,36 @@ Error: Cannot load native addon because loading addons is disabled.
 }
 .Ed
 .
+.It Fl -allow-async-hooks
+Allow use of \fBasync_hooks.createHook()\fR. This flag is required to enable
+the \fBcreateHook\fR API, which is disabled by default.
+Example:
+.Bd -literal
+import { createHook } from 'node:async_hooks';
+
+createHook({ init() {} }).enable();
+.Ed
+.Bd -literal
+const { createHook } = require('node:async_hooks');
+
+createHook({ init() {} }).enable();
+.Ed
+.Bd -literal
+$ node index.js
+node:async_hooks:160
+    throw new ERR_ASYNC_HOOKS_CREATE_HOOK_DISABLED();
+    ^
+
+Error [ERR_ASYNC_HOOKS_CREATE_HOOK_DISABLED]: async_hooks.createHook() is disabled. Use --allow-async-hooks to enable it.
+    at createHook (node:async_hooks:160:11)
+    at Object.<anonymous> (/home/user/index.js:3:1)
+    ...
+.Ed
+.Bd -literal
+$ node --allow-async-hooks index.js
+# Works without error
+.Ed
+.
 .It Fl -allow-child-process
 When using the Permission Model, the process will not be able to spawn any
 child process by default.

lib/async_hooks.js

@@ -16,6 +16,7 @@ const {
 
 const {
   ERR_ASYNC_CALLBACK,
+  ERR_ASYNC_HOOKS_CREATE_HOOK_DISABLED,
   ERR_ASYNC_RESOURCE_DOMAIN_REMOVED,
   ERR_ASYNC_TYPE,
   ERR_INVALID_ASYNC_ID,
@@ -29,6 +30,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');
@@ -168,6 +170,9 @@ class AsyncHook {
 
 
 function createHook(fns) {
+  if (!getOptionValue('--allow-async-hooks')) {
+    throw new ERR_ASYNC_HOOKS_CREATE_HOOK_DISABLED();
+  }
   return new AsyncHook(fns);
 }
 

lib/internal/errors.js

@@ -1143,6 +1143,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_RESOURCE_DOMAIN_REMOVED',

src/node_options.cc

@@ -947,6 +947,10 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             kAllowedInEnvvar,
             false,
             OptionNamespaces::kPermissionNamespace);
+  AddOption("--allow-async-hooks",
+            "allow use of async_hooks.createHook",
+            BOOL_FIELD(allow_async_hooks),
+            kAllowedInEnvvar);
   AddOption("--allow-openssl-store",
             "allow use of OpenSSL STORE loaders when any permissions are set",
             BOOL_FIELD(allow_openssl_store),

src/node_options.h

@@ -238,6 +238,7 @@ class EnvironmentOptions : public Options {
   DEFINE_BOOL_FIELD(allow_ffi) = false;
   DEFINE_BOOL_FIELD(allow_openssl_store) = false;
   DEFINE_BOOL_FIELD(allow_worker_threads) = false;
+  DEFINE_BOOL_FIELD(allow_async_hooks) = false;
   DEFINE_BOOL_FIELD(experimental_vm_modules) = EXPERIMENTALS_DEFAULT_VALUE;
   DEFINE_BOOL_FIELD(expose_internals) = false;
   DEFINE_BOOL_FIELD(force_node_api_uncaught_exceptions_policy) = false;

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,4 +1,5 @@
 'use strict';
+// Flags: --allow-async-hooks
 
 const common = require('../../common');
 const assert = require('assert');

test/async-hooks/init-hooks.js

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