lib: add --no-experimental-global-navigator CLI flag

PR-URL: #50562
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Geoffrey Booth <[email protected]>
Reviewed-By: Chengzhong Wu <[email protected]>
Reviewed-By: Richard Lau <[email protected]>
Reviewed-By: Ethan Arrowood <[email protected]>

Author: aduh95

doc/api/cli.md

@@ -1196,6 +1196,16 @@ added: v19.0.0
 
 Disable exposition of [CustomEvent Web API][] on the global scope.
 
+### `--no-experimental-global-navigator`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Disable exposition of [Navigator API][] on the global scope.
+
 ### `--no-experimental-global-webcrypto`
 
 <!-- YAML
@@ -2359,6 +2369,7 @@ Node.js options that are allowed are:
 * `--no-deprecation`
 * `--no-experimental-fetch`
 * `--no-experimental-global-customevent`
+* `--no-experimental-global-navigator`
 * `--no-experimental-global-webcrypto`
 * `--no-experimental-repl-await`
 * `--no-extra-info-on-fatal-exception`
@@ -2774,6 +2785,7 @@ done
 [Module customization hooks]: module.md#customization-hooks
 [Module customization hooks: enabling]: module.md#enabling
 [Modules loaders]: packages.md#modules-loaders
+[Navigator API]: globals.md#navigator
 [Node.js issue tracker]: https://github.com/nodejs/node/issues
 [OSSL_PROVIDER-legacy]: https://www.openssl.org/docs/man3.0/man7/OSSL_PROVIDER-legacy.html
 [Permission Model]: permissions.md#permission-model

doc/api/globals.md

@@ -600,7 +600,8 @@ This variable may appear to be global but is not. See [`module`][].
 added: v21.0.0
 -->
 
-> Stability: 1.1 - Active development
+> Stability: 1.1 - Active development. Disable this API with the
+> [`--no-experimental-global-navigator`][] CLI flag.
 
 A partial implementation of the [Navigator API][].
 
@@ -610,18 +611,11 @@ A partial implementation of the [Navigator API][].
 added: v21.0.0
 -->
 
-> Stability: 1.1 - Active development
+> Stability: 1.1 - Active development. Disable this API with the
+> [`--no-experimental-global-navigator`][] CLI flag.
 
 A partial implementation of [`window.navigator`][].
 
-If your app or a dependency uses a check for `navigator` to determine whether it
-is running in a browser, the following can be used to delete the `navigator`
-global before app code runs:
-
-```bash
-node --import 'data:text/javascript,delete globalThis.navigator' app.js
-```
-
 ### `navigator.hardwareConcurrency`
 
 <!-- YAML
@@ -1145,6 +1139,7 @@ A browser-compatible implementation of [`WritableStreamDefaultWriter`][].
 [Web Crypto API]: webcrypto.md
 [`--experimental-websocket`]: cli.md#--experimental-websocket
 [`--no-experimental-global-customevent`]: cli.md#--no-experimental-global-customevent
+[`--no-experimental-global-navigator`]: cli.md#--no-experimental-global-navigator
 [`--no-experimental-global-webcrypto`]: cli.md#--no-experimental-global-webcrypto
 [`AbortController`]: https://developer.mozilla.org/en-US/docs/Web/API/AbortController
 [`ByteLengthQueuingStrategy`]: webstreams.md#class-bytelengthqueuingstrategy

lib/internal/bootstrap/web/exposed-window-or-worker.js

@@ -52,10 +52,6 @@ exposeLazyInterfaces(globalThis, 'perf_hooks', [
 
 defineReplaceableLazyAttribute(globalThis, 'perf_hooks', ['performance']);
 
-// https://html.spec.whatwg.org/multipage/system-state.html#the-navigator-object
-exposeLazyInterfaces(globalThis, 'internal/navigator', ['Navigator']);
-defineReplaceableLazyAttribute(globalThis, 'internal/navigator', ['navigator'], false);
-
 // https://w3c.github.io/FileAPI/#creating-revoking
 const { installObjectURLMethods } = require('internal/url');
 installObjectURLMethods();

lib/internal/process/pre_execution.js

@@ -77,6 +77,7 @@ function prepareExecution(options) {
   const mainEntry = patchProcessObject(expandArgv1);
   setupTraceCategoryState();
   setupInspectorHooks();
+  setupNavigator();
   setupWarningHandler();
   setupUndici();
   setupWebCrypto();
@@ -336,6 +337,19 @@ function setupUndici() {
   }
 }
 
+// TODO(aduh95): move this to internal/bootstrap/web/* when the CLI flag is
+//               removed.
+function setupNavigator() {
+  if (getEmbedderOptions().noBrowserGlobals ||
+      getOptionValue('--no-experimental-global-navigator')) {
+    return;
+  }
+
+  // https://html.spec.whatwg.org/multipage/system-state.html#the-navigator-object
+  exposeLazyInterfaces(globalThis, 'internal/navigator', ['Navigator']);
+  defineReplaceableLazyAttribute(globalThis, 'internal/navigator', ['navigator'], false);
+}
+
 // TODO(aduh95): move this to internal/bootstrap/web/* when the CLI flag is
 //               removed.
 function setupWebCrypto() {

src/node_options.cc

@@ -391,6 +391,11 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             &EnvironmentOptions::experimental_global_customevent,
             kAllowedInEnvvar,
             true);
+  AddOption("--experimental-global-navigator",
+            "expose experimental Navigator API on the global scope",
+            &EnvironmentOptions::experimental_global_navigator,
+            kAllowedInEnvvar,
+            true);
   AddOption("--experimental-global-webcrypto",
             "expose experimental Web Crypto API on the global scope",
             &EnvironmentOptions::experimental_global_web_crypto,

src/node_options.h

@@ -110,6 +110,7 @@ class EnvironmentOptions : public Options {
   bool experimental_fetch = true;
   bool experimental_websocket = false;
   bool experimental_global_customevent = true;
+  bool experimental_global_navigator = true;
   bool experimental_global_web_crypto = true;
   bool experimental_https_modules = false;
   bool experimental_wasm_modules = false;