# How nvm Handles Mirrored Node.js Downloads with Authentication Headers

> Learn how nvm handles mirrored Node.js downloads with authentication headers by injecting your custom headers into download commands. Discover the process now.

- Repository: [nvm.sh/nvm](https://github.com/nvm-sh/nvm)
- Tags: internals
- Published: 2026-02-27

---

**nvm handles mirrored Node.js downloads with authentication headers by reading the `NVM_AUTH_HEADER` environment variable, sanitizing the value via `nvm_sanitize_auth_header`, and injecting it into curl or wget commands during the download process.**

When working with private or corporate Node.js mirrors that require authentication, the nvm-sh/nvm repository provides built-in support for injecting HTTP Authorization headers without modifying core scripts. This functionality enables seamless downloads from authenticated endpoints through environment-driven configuration.

## Mirror Resolution via nvm_get_mirror

The `nvm_get_mirror` function in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) (lines 2221-2230) determines the base URL for Node.js or io.js downloads. It checks environment variables to override the default public registry.

```sh
nvm_get_mirror() {
  local NVM_MIRROR=''
  case "${1}-${2}" in
    node-std) NVM_MIRROR="${NVM_NODEJS_ORG_MIRROR:-https://nodejs.org/dist}" ;;
    iojs-std) NVM_MIRROR="${NVM_IOJS_ORG_MIRROR:-https://iojs.org/dist}" ;;
    *) nvm_err 'unknown type of node.js or io.js release'; return 1 ;;
  esac
  nvm_echo "${NVM_MIRROR}"
}

```

**Key behaviors:**
- **Flavor detection** – Accepts `node` or `iojs` as the first parameter and `std` as the second.
- **Environment override** – Uses `NVM_NODEJS_ORG_MIRROR` or `NVM_IOJS_ORG_MIRROR` when defined, falling back to official URLs otherwise.
- **URL validation** – Ensures the mirror string is a valid HTTP/HTTPS URL before returning.

## Header Sanitization with nvm_sanitize_auth_header

Before injecting authentication credentials into shell commands, nvm sanitizes the header value to prevent command injection attacks. The `nvm_sanitize_auth_header` function (lines 60-63) strips dangerous characters.

```sh
nvm_sanitize_auth_header() {
  nvm_echo "$1" | command sed 's/[^a-zA-Z0-9:;_. -]//g'
}

```

This function removes any characters outside the allowed set of alphanumeric characters, colons, semicolons, underscores, periods, spaces, and hyphens. It executes only when `NVM_AUTH_HEADER` is present in the environment.

## Download Execution in nvm_download

The `nvm_download` function (lines 118-158) constructs the actual HTTP request. When `NVM_AUTH_HEADER` is set, it builds a curl command with the `--header` flag containing the sanitized Authorization value.

```sh
nvm_download() {
  if nvm_has "curl"; then
    local CURL_COMPRESSED_FLAG=""
    local CURL_HEADER_FLAG=""

    if [ -n "${NVM_AUTH_HEADER:-}" ]; then
      sanitized_header=$(nvm_sanitize_auth_header "${NVM_AUTH_HEADER}")
      CURL_HEADER_FLAG="--header \"Authorization: ${sanitized_header}\""
    fi

    local NVM_DOWNLOAD_ARGS=''
    for arg in "$@"; do
      NVM_DOWNLOAD_ARGS="${NVM_DOWNLOAD_ARGS} \"$arg\""
    done
    eval "curl -q --fail ${CURL_COMPRESSED_FLAG:-} ${CURL_HEADER_FLAG:-} ${NVM_DOWNLOAD_ARGS}"
  elif nvm_has "wget"; then
    # wget implementation mirrors the same header injection logic

    # lines 151-155 handle the equivalent --header parameter for wget

  fi
}

```

**Implementation details:**
- **Conditional injection** – The Authorization header is added only if `NVM_AUTH_HEADER` is non-empty.
- **Dual backend support** – Both **curl** and **wget** paths implement identical authentication logic.
- **Quote safety** – The sanitized header is wrapped in quotes to handle tokens containing spaces.

## Practical Configuration Example

To download Node.js from an authenticated private mirror, export the following environment variables before running nvm commands:

```sh

# Configure the private mirror endpoint

export NVM_NODEJS_ORG_MIRROR="https://private-mirror.company.com/nodejs"

# Set the authentication header (Bearer token example)

export NVM_AUTH_HEADER="Bearer abc123def456"

# Install Node.js - nvm will resolve the mirror and inject the auth header

nvm install 18.20.0

```

This configuration generates a curl command equivalent to:

```sh
curl -q --fail --header "Authorization: Bearer abc123def456" \
     -L -s "https://private-mirror.company.com/nodejs/v18.20.0/node-v18.20.0-linux-x64.tar.xz" -o -

```

If the mirror requires **Basic authentication**, set the header accordingly:

```sh
export NVM_AUTH_HEADER="Basic dXNlcjpwYXNzd29yZA=="

```

## Summary

- **Environment-driven configuration** – Mirrors and authentication are controlled entirely through `NVM_NODEJS_ORG_MIRROR`, `NVM_IOJS_ORG_MIRROR`, and `NVM_AUTH_HEADER` without code modifications.
- **Injection protection** – The `nvm_sanitize_auth_header` function in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) prevents command injection by stripping unsafe characters from header values.
- **Universal backend support** – Both curl and wget implementations in `nvm_download` handle authenticated requests consistently.
- **Zero-touch setup** – Private corporate proxies and authenticated CDNs work seamlessly with standard nvm installations.

## Frequently Asked Questions

### What environment variables configure authenticated mirrors in nvm?

Set `NVM_NODEJS_ORG_MIRROR` (or `NVM_IOJS_ORG_MIRROR` for io.js) to specify the mirror URL, and set `NVM_AUTH_HEADER` to provide the Authorization header value. nvm reads these variables during `nvm install` and `nvm use` operations.

### How does nvm prevent security risks from authentication headers?

The `nvm_sanitize_auth_header` function removes characters that could break shell command syntax or enable injection attacks. It allows only alphanumeric characters, colons, semicolons, underscores, periods, spaces, and hyphens, ensuring the header value cannot escape the curl/wget command context.

### Does nvm support both curl and wget for authenticated downloads?

Yes. The `nvm_download` function in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) implements authentication header injection for both curl (using `--header`) and wget (using `--header` or `--http-user`/`--http-password` depending on the implementation). The logic ensures consistent behavior regardless of which tool is available on the system.

### Can I use nvm with a corporate Node.js mirror requiring authentication?

Absolutely. Configure `NVM_NODEJS_ORG_MIRROR` to point to your corporate mirror (e.g., `https://artifactory.company.com/nodejs-dist`), set `NVM_AUTH_HEADER` to your token or credentials, and run `nvm install` normally. nvm will route all requests to your internal endpoint with proper authentication.