Support authentication for private `--dist-url` Node.js distribution mirrors

从 node-gyp 的集中式下载辅助函数以及构造请求标头的位置开始。跟踪 headers tarball、SHASUMS256.txt 和 Windows node.lib 的请求，然后查看相关 issue，了解现有约束。完成的标准是：一种有文档记录的身份验证方案能够一致地应用，同时不会泄露凭据，也不会将凭据转发到已配置的分发范围之外。

Observed in node-gyp@12.4.0

node-gyp supports custom Node.js distribution mirrors via --dist-url / node_gyp_dist_url, but there does not appear to be a documented way to authenticate requests made to that mirror.

This is a problem in corporate environments where Node.js distributions and headers are served through an authenticated Artifactory mirror.

Example failure

gyp http GET https://artifactory.example.com/artifactory/nodejs-dist/v24.19.0/node-v24.19.0-headers.tar.gz
gyp http 401 https://artifactory.example.com/artifactory/nodejs-dist/v24.19.0/node-v24.19.0-headers.tar.gz

Package installation itself works because npm, pnpm, or Yarn can authenticate against the package registry. The failure happens later, when node-gyp downloads Node.js headers from the configured distribution URL.

Example package registry authentication:

registry=https://artifactory.example.com/artifactory/api/npm/npm-virtual/
//artifactory.example.com/artifactory/api/npm/npm-virtual/:_authToken=${NPM_TOKEN}

Example Node.js distribution mirror:

https://artifactory.example.com/artifactory/nodejs-dist/

Example node-gyp configuration:

npm_package_config_node_gyp_dist_url=https://artifactory.example.com/artifactory/nodejs-dist

Expected behavior

When --dist-url / node_gyp_dist_url points to an authenticated mirror, node-gyp should provide a supported way to authenticate downloads from that mirror.

Authentication would need to apply consistently to:

• the Node.js headers tarball;
• SHASUMS256.txt;
• Windows node.lib files;
• any other files downloaded from the configured distribution URL.

Possible solutions

Any of the following would solve the issue. Explicit node-gyp configuration may be preferable given npm's move away from unsupported custom .npmrc keys.

1. Add explicit node-gyp authentication configuration

For example:

node-gyp rebuild \
  --dist-url=https://artifactory.example.com/artifactory/nodejs-dist \
  --dist-url-auth-token="$NODE_GYP_DIST_TOKEN"

Or through lifecycle-safe configuration:

npm_package_config_node_gyp_dist_url_auth_token=$NODE_GYP_DIST_TOKEN

The option name could be adjusted to match the project's preferred naming and credential model.

2. Support an explicit authentication-header option

For example:

node-gyp rebuild \
  --dist-url=https://artifactory.example.com/artifactory/nodejs-dist \
  --dist-url-auth-header="Authorization: Bearer $NODE_GYP_DIST_TOKEN"

A credential-specific option may be safer than accepting arbitrary headers, but some environments require non-standard authentication headers.

3. Optionally support npm-compatible URL-scoped authentication

For example:

//artifactory.example.com/artifactory/nodejs-dist/:_authToken=${NODE_GYP_DIST_TOKEN}

This should only be considered if it can be implemented as documented, supported node-gyp behavior rather than relying on arbitrary unsupported .npmrc keys.

Implementation context

The downloads appear to be centralized through node-gyp's download helper. The headers tarball, checksum file, and Windows node.lib requests all use the same download path, where request headers are currently constructed.

This seems like a relatively contained integration point: authentication could be resolved once for the configured dist-url and applied to all requests made within that distribution scope.

Security considerations

• Credentials should only be sent to URLs under the configured dist-url.
• Credentials must not be logged, including with verbose or silly logging.
• Credentials should not be forwarded across redirects to a different host.
• Environment-variable-based configuration should be supported so secrets do not need to be committed.
• Authentication should be applied consistently to the tarball, checksum, and node.lib requests.
• If npm-compatible credentials are supported, matching should respect the configured URL scope rather than sending credentials to every URL on the same host.
• Credentials should not appear in error messages, generated files, or process arguments where avoidable.

Current workarounds

There are partial workarounds, but they are difficult to apply reliably in package-manager-driven installs:

• --nodedir requires a compatible local Node.js headers/source tree and a way to pass the option to the actual transitive node-gyp invocation.
• --tarball can avoid network access, but it requires invoking node-gyp install explicitly before the dependency rebuild.
• Manually pre-populating node-gyp's cache is brittle because the cache must match node-gyp's expected layout and metadata, including installVersion.
• Embedding credentials in --dist-url only works when the mirror accepts Basic Auth and may expose credentials in logs or process arguments.

In practice, these workarounds are difficult to standardize across developer machines and CI systems when native modules invoke node-gyp indirectly during installation or bootstrapping.

Related issues

This appears related to:

• #1287 — private Artifactory/mirror header download problems;
• #3000 — node-gyp downloading headers despite a local cache.

Question

Would maintainers be open to supporting authentication for private --dist-url mirrors?

If so, would URL-scoped npm-compatible authentication or explicit node-gyp-specific authentication options be preferred?