Skip to content

Create an environment variable as an alternative to the --use-system-ca CLI flag #58346

Closed as not planned
Closed as not planned
Create an environment variable as an alternative to the --use-system-ca CLI flag#58346
Labels
feature requestIssues requesting new Node.js features.

Description

@zleroy
zleroy
opened on May 15, 2025

What is the problem this feature will solve?

Working in an enterprise setting, we have security tools that perform SSL decryption using self-signed certificates. This is often problematic for many developer tools.

Since some CLI tools that run on Node often ship with their own CLI shell wrapper executables, it is not always feasible to pass a command line argument to node for the --use-system-ca flag (see https://nodejs.org/en/blog/release/v23.8.0 and #56599 and #56833) in order to leverage the feature.

An example CLI tool that runs on Node.js is Salesforce CLI

The 'sf' command is provided through the following script when the package is installed:

#!/bin/sh
basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")

case `uname` in
    *CYGWIN*|*MINGW*|*MSYS*)
        if command -v cygpath > /dev/null 2>&1; then
            basedir=`cygpath -w "$basedir"`
        fi
    ;;
esac

if [ -x "$basedir/node" ]; then
  exec "$basedir/node" --no-deprecation "$basedir/node_modules/@salesforce/cli/bin/run.js" "$@"
else 
  exec node --no-deprecation "$basedir/node_modules/@salesforce/cli/bin/run.js" "$@"
fi

Due to the use of 'exec' to invoke Node, a workaround to make a shell wrapper function to override calls to Node and inject the --use-system-ca flag on all invocations is not feasible. The only workarounds that tested successfully were to either override 'sf' in ~/.bashrc or or manually edit the 'sf' script above after the package is installed.

There are other ways to work around certificate trust issues for self-signed certificates, but they are often more work or less secure.

Now that --use-system-ca functionality is available, it would be ideal to leverage this functionality with an environment variable rather than manually setting certificate paths, manually building a separate trust store, or using NODE_TLS_REJECT_UNAUTHORIZED=0.

What is the feature you are proposing to solve the problem?

Please make an environment variable that could also control the --use-system-ca flag functionality. The simplest implementation would add a new Boolean environment variable similar to NODE_TLS_REJECT_UNAUTHORIZED which did the exact same thing as passing --use-system-ca on the command line would.

Example:

NODE_USE_SYSTEM_CA=1 - same as passing --use-system-ca on the command line
NODE_USE_SYSTEM_CA=0 - default; same as not passing --use-system-ca on the command line

Would it make sense to make --use-system-ca a default? As a Node user, I would expect Node to use the default certificate management system on the operating system (Windows, MacOS, RedHat, etc.) vs. having to configure Node to do so.

Best regards, and thank you for implementing --use-system-ca! The new feature dramatically simplifies the amount of manual hackery each developer needs to perform on their machines to work in our enterprise.

What alternatives have you considered?

Manually overriding node or sf in shell functions (~/.bashrc) or directly editing packages after installation, use of the NODE_TLS_REJECT_UNAUTHORIZED=0 environment variable setting, or using NODE_EXTRA_CA_CERTS.

Activity

  1. zleroy
    added
    feature requestIssues requesting new Node.js features.
    on May 15, 2025
  2. github-project-automation
    added this to Node.js feature requestson May 15, 2025
  3. github-project-automation
    moved this to Awaiting Triage in Node.js feature requestson May 15, 2025

  4. bnoordhuis commented on May 15, 2025

    @bnoordhuis
    bnoordhuis
    on May 15, 2025
    Member

    Already works: NODE_OPTIONS=--use-system-ca

  5. bnoordhuis
    closed this as not plannedon May 15, 2025

  6. zleroy commented on May 16, 2025

    @zleroy
    zleroy
    on May 16, 2025
    Author

    Great, I was not aware of this. Thank you for the information

  7. petr-ujezdsky commented on Jul 1, 2025

    @petr-ujezdsky
    petr-ujezdsky
    on Jul 1, 2025

    That does not work for corepack in alpine version of docker image.

    docker run --rm -it node:20-alpine sh
    corepack enable yarn
    yarn -v
/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:22051
    throw new Error(
          ^

Error: Error when performing the request to https://registry.npmjs.org/yarn/latest; for troubleshooting help, see https://github.com/nodejs/corepack#troubleshooting
    at fetch (/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:22051:11)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async fetchAsJson (/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:22065:20)
    ... 5 lines matching cause stack trace ...
    at async Object.runMain (/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:23648:7) {
  [cause]: TypeError: fetch failed
      at node:internal/deps/undici/undici:13510:13
      at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
      at async fetch (/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:22045:16)
      at async fetchAsJson (/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:22065:20)
      at async fetchLatestStableVersion (/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:21988:20)
      at async fetchLatestStableVersion2 (/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:22114:14)
      at async Engine.getDefaultVersion (/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:22829:23)
      at async Engine.findProjectSpec (/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:22892:40)
      at async Engine.executePackageManagerRequest (/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:22952:24)
      at async Object.runMain (/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:23648:7) {
    [cause]: Error: self-signed certificate in certificate chain
        at TLSSocket.onConnectSecure (node:_tls_wrap:1677:34)
        at TLSSocket.emit (node:events:524:28)
        at TLSSocket._finishInit (node:_tls_wrap:1076:8)
        at ssl.onhandshakedone (node:_tls_wrap:862:12) {
      code: 'SELF_SIGNED_CERT_IN_CHAIN'
    }
  }
}

Node.js v20.19.3
    export NODE_OPTIONS=--use-system-ca
    yarn -v
node: --use-system-ca is not allowed in NODE_OPTIONS

    The only solution I have found is using the NODE_EXTRA_CA_CERTS env variable.

  8. bnoordhuis commented on Jul 2, 2025

    @bnoordhuis
    bnoordhuis
    on Jul 2, 2025
    Member

    Node.js v20.19.3

    Upgrade to v22.17.0 or newer.

  9. simhnna commented on Jun 18, 2026

    @simhnna
    simhnna
    on Jun 18, 2026

    The issue with NODE_OPTIONS=--use-system-ca is that NODE_OPTIONS is used for other things as well. So every time you set that somewhere you'd actually need to use NODE_OPTION="${NODE_OPTIONS --use-system-ca"

    Setting NODE_EXTRA_CA_CERTS doesn't have that issue. Needing system-ca is usually something outside the users control while the other options are closely tied to the code that's being executed.

    So I'd really welcome an env var (or a node version that eventually uses system ca by default)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    feature requestIssues requesting new Node.js features.

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions