cli: add NODE_USE_SYSTEM_CA=1

joyeecheung · aduh95 · commit 8e2076a24f87 · 2025-08-26T11:22:41.000+02:00
Similar to how NODE_USE_ENV_PROXY complements --use-env-proxy, this complements --use-system-ca. This will allow the setting to be applied to workers individually in the future. PR-URL: #59276 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ethan Arrowood <ethan@arrowood.dev> Reviewed-By: Darshan Sen <raisinten@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -3600,6 +3600,18 @@ If `value` equals `'0'`, certificate validation is disabled for TLS connections.
 This makes TLS, and HTTPS by extension, insecure. The use of this environment
 variable is strongly discouraged.
 
+### `NODE_USE_SYSTEM_CA=1`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Node.js uses the trusted CA certificates present in the system store along with
+the `--use-bundled-ca` option and the `NODE_EXTRA_CA_CERTS` environment variable.
+
+This can also be enabled using the [`--use-system-ca`][] command-line flag.
+When both are set, `--use-system-ca` takes precedence.
+
 ### `NODE_V8_COVERAGE=dir`
 
 When set, Node.js will begin outputting [V8 JavaScript code coverage][] and
@@ -3933,6 +3945,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`--print`]: #-p---print-script
 [`--redirect-warnings`]: #--redirect-warningsfile
 [`--require`]: #-r---require-module
+[`--use-system-ca`]: #--use-system-ca
 [`AsyncLocalStorage`]: async_context.md#class-asynclocalstorage
 [`Atomics.wait()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Atomics/wait
 [`Buffer`]: buffer.md#class-buffer
diff --git a/doc/node.1 b/doc/node.1
@@ -809,6 +809,12 @@ When set to
 .Ar 0 ,
 TLS certificate validation is disabled.
 .
+.It Ev NODE_USE_SYSTEM_CA
+Similar to
+.Fl -use-system-ca .
+Use the trusted CA certificates present in the system store, in addition to the certificates in the
+bundled Mozilla CA store and certificates from `NODE_EXTRA_CA_CERTS`.
+.
 .It Ev NODE_V8_COVERAGE Ar dir
 When set, Node.js writes JavaScript code coverage information to
 .Ar dir .
diff --git a/src/node.cc b/src/node.cc
@@ -912,6 +912,15 @@ static ExitCode InitializeNodeWithArgsInternal(
   // default value.
   V8::SetFlagsFromString("--rehash-snapshot");
 
+#if HAVE_OPENSSL
+  // TODO(joyeecheung): make this a per-env option and move the normalization
+  // into HandleEnvOptions.
+  std::string use_system_ca;
+  if (credentials::SafeGetenv("NODE_USE_SYSTEM_CA", &use_system_ca) &&
+      use_system_ca == "1") {
+    per_process::cli_options->use_system_ca = true;
+  }
+#endif  // HAVE_OPENSSL
   HandleEnvOptions(per_process::cli_options->per_isolate->per_env);
 
   std::string node_options;
diff --git a/test/parallel/test-tls-get-ca-certificates-node-use-system-ca.js b/test/parallel/test-tls-get-ca-certificates-node-use-system-ca.js
@@ -0,0 +1,29 @@
+'use strict';
+// This tests that NODE_USE_SYSTEM_CA environment variable works the same
+// as --use-system-ca flag by comparing certificate counts.
+
+const common = require('../common');
+if (!common.hasCrypto) common.skip('missing crypto');
+
+const tls = require('tls');
+const { spawnSyncAndExitWithoutError } = require('../common/child_process');
+
+const systemCerts = tls.getCACertificates('system');
+if (systemCerts.length === 0) {
+  common.skip('no system certificates available');
+}
+
+const { child: { stdout: expectedLength } } = spawnSyncAndExitWithoutError(process.execPath, [
+  '--use-system-ca',
+  '-p',
+  `tls.getCACertificates('default').length`,
+], {
+  env: { ...process.env, NODE_USE_SYSTEM_CA: '0' },
+});
+
+spawnSyncAndExitWithoutError(process.execPath, [
+  '-p',
+  `assert.strictEqual(tls.getCACertificates('default').length, ${expectedLength.toString()})`,
+], {
+  env: { ...process.env, NODE_USE_SYSTEM_CA: '1' },
+});
diff --git a/test/system-ca/test-native-root-certs-env.mjs b/test/system-ca/test-native-root-certs-env.mjs
@@ -0,0 +1,56 @@
+// Env: NODE_USE_SYSTEM_CA=1
+// Same as test-native-root-certs.mjs, just testing the environment variable instead of the flag.
+
+import * as common from '../common/index.mjs';
+import assert from 'node:assert/strict';
+import https from 'node:https';
+import fixtures from '../common/fixtures.js';
+import { it, beforeEach, afterEach, describe } from 'node:test';
+import { once } from 'events';
+
+if (!common.hasCrypto) {
+  common.skip('requires crypto');
+}
+
+// To run this test, the system needs to be configured to trust
+// the CA certificate first (which needs an interactive GUI approval, e.g. TouchID):
+// see the README.md in this folder for instructions on how to do this.
+const handleRequest = (req, res) => {
+  const path = req.url;
+  switch (path) {
+    case '/hello-world':
+      res.writeHead(200);
+      res.end('hello world\n');
+      break;
+    default:
+      assert(false, `Unexpected path: ${path}`);
+  }
+};
+
+describe('use-system-ca', function() {
+
+  async function setupServer(key, cert) {
+    const theServer = https.createServer({
+      key: fixtures.readKey(key),
+      cert: fixtures.readKey(cert),
+    }, handleRequest);
+    theServer.listen(0);
+    await once(theServer, 'listening');
+
+    return theServer;
+  }
+
+  let server;
+
+  beforeEach(async function() {
+    server = await setupServer('agent8-key.pem', 'agent8-cert.pem');
+  });
+
+  it('trusts a valid root certificate', async function() {
+    await fetch(`https://localhost:${server.address().port}/hello-world`);
+  });
+
+  afterEach(async function() {
+    server?.close();
+  });
+});
