lib: hide navigator behind a flag

doc/api/cli.md

@@ -646,6 +646,16 @@ CommonJS. This includes `import` and `export` statements and `import.meta`
 references. It does _not_ include `import()` expressions, which are valid in
 CommonJS.
 
+### `--experimental-global-navigator`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Enable exposition of [Navigator API][] on the global scope.
+
 ### `--experimental-import-meta-resolve`
 
 <!-- YAML
@@ -2313,6 +2323,7 @@ Node.js options that are allowed are:
 * `--experimental-abortcontroller`
 * `--experimental-default-type`
 * `--experimental-detect-module`
+* `--experimental-global-navigator`
 * `--experimental-import-meta-resolve`
 * `--experimental-json-modules`
 * `--experimental-loader`
@@ -2763,6 +2774,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

@@ -598,30 +598,32 @@ This variable may appear to be global but is not. See [`module`][].
 
 <!-- YAML
 added: v21.0.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/50412
+    description: The API is behind the CLI flag `--experimental-global-navigator`.
 -->
 
-> Stability: 1.1 - Active development
+> Stability: 1.1 - Active development. Use `--experimental-global-navigator` to
+> enable this feature.
 
 A partial implementation of the [Navigator API][].
 
 ## `navigator`
 
 <!-- YAML
 added: v21.0.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/50412
+    description: The API is behind the CLI flag `--experimental-global-navigator`.
 -->
 
-> Stability: 1.1 - Active development
+> Stability: 1.1 - Active development. Use `--experimental-global-navigator` to
+> enable this feature.
 
 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

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,10 @@ 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);
   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 = false;
   bool experimental_global_web_crypto = true;
   bool experimental_https_modules = false;
   bool experimental_wasm_modules = false;

test/parallel/test-global.js

@@ -58,7 +58,6 @@ builtinModules.forEach((moduleName) => {
     'structuredClone',
     'fetch',
     'crypto',
-    'navigator',
   ];
   assert.deepStrictEqual(new Set(Object.keys(global)), new Set(expected));
 }

test/parallel/test-navigator.js

@@ -1,3 +1,4 @@
+// Flags: --experimental-global-navigator
 'use strict';
 
 require('../common');